Feat/core id creation logic

[coodos]

Description of change

adds w3id core class

Issue Number

closes #12
closes #13
closes #17
closes #22

Type of change

• New (a change which implements a new feature)

How the change has been tested

Tests

Change checklist

• I have ensured that the CI Checks pass locally
• I have removed any unnecessary logic
• My code is well documented
• I have signed my commits
• My code follows the pattern of the application
• I have self reviewed my code

Summary by CodeRabbit

• New Features
  • Introduced a builder for creating decentralized identifiers (DIDs) with configurable options, supporting both simple and key-attached IDs.
  • Added a utility to generate random alphanumeric strings.
• Improvements
  • Enhanced log management by associating signers directly with log managers for streamlined cryptographic operations.
  • Improved error handling and documentation for identifier and log creation.
• Tests
  • Added comprehensive tests for identifier creation, log management, and key rotation.
  • Centralized and simplified test utilities for cryptography and storage.

[coderabbitai]

Warning

Rate limit exceeded

@coodos has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 5 minutes and 3 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 9791ea6 and e8ed604.

📒 Files selected for processing (1)

• .github/workflows/tests-w3id.yml (1 hunks)

Walkthrough

This set of changes introduces a modular W3ID library that implements a factory pattern for creating and managing decentralized identifiers (DIDs) with support for key rotation and logging. The new W3ID and W3IDBuilder classes allow configurable creation of identifiers, with optional integration of cryptographic signers and log managers. The logging subsystem is refactored to associate signers with the IDLogManager instance rather than passing them per operation. Supporting utilities for random string generation, cryptographic operations, and in-memory storage are added for testing. Comprehensive tests validate ID creation, determinism, log management, and key rotation. Error handling and type annotations are refined throughout.

Changes

File(s)	Change Summary
infrastructure/w3id/src/index.ts	Replaces default export with new W3ID and W3IDBuilder classes, implementing the factory pattern for DID generation and management, supporting options for entropy, namespace, signer, repository, and key rotation.
infrastructure/w3id/src/logs/log-manager.ts	Refactors IDLogManager to hold a signer instance property, updates method signatures and documentation, and ensures signing is managed at the class level. Adds explicit return types and JSDoc comments.
infrastructure/w3id/src/logs/log.types.ts	Removes signer from RotationLogOptions and GenesisLogOptions types, aligning with the new signer management strategy.
infrastructure/w3id/src/errors/errors.ts	Removes explicit : string type annotations from custom error class constructors, retaining default messages.
infrastructure/w3id/src/utils/rand.ts	Adds generateRandomAlphaNum utility function for generating random alphanumeric strings.
infrastructure/w3id/tests/logs/log.test.ts	Refactors tests to use shared cryptographic and storage utilities, updates IDLogManager instantiation to use constructor-injected signer, and cleans up imports.
infrastructure/w3id/tests/utils/crypto.ts	Adds test utility module providing verifierCallback for signature verification and createSigner for generating signer objects from key pairs.
infrastructure/w3id/tests/utils/store.ts	Adds InMemoryStorage class implementing StorageSpec for in-memory log event storage, with methods for creating and querying entries.
infrastructure/w3id/tests/w3id.test.ts	Adds comprehensive test suite for W3IDBuilder, covering ID creation, global/local flags, deterministic UUIDs, log manager integration, and key rotation with log validation.

Sequence Diagram(s)

sequenceDiagram
    participant ConsumerApp
    participant W3IDBuilder
    participant W3ID
    participant IDLogManager
    participant Storage
    participant Signer

    ConsumerApp->>W3IDBuilder: Configure builder (namespace, entropy, etc.)
    ConsumerApp->>W3IDBuilder: Optionally set Signer and Storage
    ConsumerApp->>W3IDBuilder: build()
    alt With Signer and Storage
        W3IDBuilder->>IDLogManager: Create (with Signer, Storage)
        IDLogManager->>Storage: Store genesis log event
        W3IDBuilder->>W3ID: Instantiate (id, IDLogManager)
    else Without Signer
        W3IDBuilder->>W3ID: Instantiate (id)
    end
    W3ID-->>ConsumerApp: Return instance

Loading

sequenceDiagram
    participant W3ID
    participant IDLogManager
    participant Signer
    participant Storage

    W3ID->>IDLogManager: Rotate key (with nextKeySigner)
    IDLogManager->>Signer: Sign rotation event
    IDLogManager->>Storage: Append new log event
    IDLogManager-->>W3ID: Updated logs

Loading

Assessment against linked issues

Objective	Addressed	Explanation
Export modular W3ID base class and implement as a library (#12)	✅
Implement W3ID factory pattern for instance creation (#13)	✅
Implement key rotation and corresponding tests (#17)	✅
Publish updated DID Document to did:web endpoint (#22)	❌	No code for publishing or updating a DID Document at a did:web endpoint is present.

Possibly related PRs

• Feat/w3id log generation #98: Modifies constructors of the same custom error classes in infrastructure/w3id/src/errors/errors.ts, directly relating to error handling changes in this PR.

Suggested reviewers

• dkraemerwork
• JulienAuvo

Poem

In the warren of code, a new path is laid,
With builders and logs, our DIDs are made.
Keys can now rotate, with logs in their wake,
And random strings hop out, for security’s sake.
With storage and signers, the tests all agree—
This bunny’s new toolkit is w3id-glee!
🐇✨

---

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Generate unit testing code for this file.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai generate unit testing code for this file.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and generate unit testing code.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai generate docstrings to generate docstrings for this PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (6)

infrastructure/w3id/tests/utils/store.ts (2)

16-20: Consider adding type safety to the create method

The type casting as unknown as K is a TypeScript anti-pattern that bypasses type checking. While this might be acceptable in a test utility, it could hide potential issues.

If possible, consider implementing a proper type conversion function or validation:

public async create(body: T): Promise<K> {
-   const entry = body as unknown as K;
+   // Either implement proper validation/conversion
+   // Or document why this cast is necessary
+   const entry = this.convertToK(body);
    this.data.push(entry);
    return entry;
}

+ // Add a private method to handle the conversion with validation
+ private convertToK(input: T): K {
+   // Implement proper validation/conversion logic
+   return input as unknown as K;
+ }

---

22-31: Improve error handling in findOne method

The current error message "Not found" provides no context about which record wasn't found or what filter was used.

Enhance the error message with more specific information:

public async findOne(options: Partial<K>): Promise<K> {
    const result = this.data.find((item) =>
        Object.entries(options).every(
            ([key, value]) => item[key as keyof K] === value,
        ),
    );

-   if (!result) throw new Error("Not found");
+   if (!result) throw new Error(`Record not found with filter: ${JSON.stringify(options)}`);
    return result;
}

infrastructure/w3id/tests/w3id.test.ts (2)

12-13: Best practice: Extract the key pair creation to a setup function or beforeEach hook

The keyPair is created outside of any test context. Consider moving it to a setup function or using a beforeEach hook to ensure clean test state isolation.

-const keyPair = nacl.sign.keyPair();
+
+describe("W3IDBuilder", () => {
+    let keyPair: nacl.SignKeyPair;
+    
+    beforeEach(() => {
+        keyPair = nacl.sign.keyPair();
+    });

---

26-29: Fix grammatical error in test description

The test description has a grammatical error.

-    test("ID Generation: Local ID begins doesn't begin with `@`", async () => {
+    test("ID Generation: Local ID doesn't begin with `@`", async () => {

infrastructure/w3id/tests/utils/crypto.ts (1)

27-38: Add error handling for signing operation

The sign method could potentially fail during buffer conversion or signing operations, but there's no error handling. Consider adding try/catch to gracefully handle failures.

     const signer: Signer = {
         pubKey: publicKey,
-        sign: (str: string) => {
-            const buffer = stringToUint8Array(str);
-            const signature = nacl.sign.detached(buffer, keyPair.secretKey);
-            return base58btc.encode(signature);
+        sign: (str: string) => {
+            try {
+                const buffer = stringToUint8Array(str);
+                const signature = nacl.sign.detached(buffer, keyPair.secretKey);
+                return base58btc.encode(signature);
+            } catch (error) {
+                throw new Error(`Failed to sign message: ${error.message}`);
+            }
         },
     };

infrastructure/w3id/src/index.ts (1)

105-113: Improve error messages for missing requirements

The error messages could be more specific about why the repository and next key hash are required when a signer is provided.

-			throw new Error(
-				"Repository is required, pass with `withRepository` method",
-			);
+			throw new Error(
+				"Repository is required when a signer is provided. Use the `withRepository` method to add one.",
+			);

-			throw new Error(
-				"NextKeyHash is required pass with `withNextKeyHash` method",
-			);
+			throw new Error(
+				"NextKeyHash is required when a signer is provided. Use the `withNextKeyHash` method to specify the hash of the next key.",
+			);

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 6bccab0 and 9e0580a.

📒 Files selected for processing (9)

• infrastructure/w3id/src/errors/errors.ts (1 hunks)
• infrastructure/w3id/src/index.ts (1 hunks)
• infrastructure/w3id/src/logs/log-manager.ts (5 hunks)
• infrastructure/w3id/src/logs/log.types.ts (0 hunks)
• infrastructure/w3id/src/utils/rand.ts (1 hunks)
• infrastructure/w3id/tests/logs/log.test.ts (2 hunks)
• infrastructure/w3id/tests/utils/crypto.ts (1 hunks)
• infrastructure/w3id/tests/utils/store.ts (1 hunks)
• infrastructure/w3id/tests/w3id.test.ts (1 hunks)

💤 Files with no reviewable changes (1)

• infrastructure/w3id/src/logs/log.types.ts

🧰 Additional context used

🧬 Code Graph Analysis (5)

infrastructure/w3id/tests/utils/store.ts (1)

infrastructure/w3id/src/logs/log.types.ts (1)

• LogEvent (1-9)

infrastructure/w3id/src/index.ts (4)

infrastructure/w3id/src/logs/log-manager.ts (1)

• IDLogManager (30-188)

infrastructure/w3id/src/logs/log.types.ts (2)

• Signer (17-20)
• LogEvent (1-9)

infrastructure/w3id/src/utils/rand.ts (1)

• generateRandomAlphaNum (8-19)

infrastructure/w3id/src/utils/uuid.ts (1)

• generateUuid (12-17)

infrastructure/w3id/tests/utils/crypto.ts (2)

infrastructure/w3id/src/logs/log.types.ts (2)

• VerifierCallback (11-15)
• Signer (17-20)

infrastructure/w3id/src/utils/codec.ts (3)

• stringToUint8Array (18-20)
• hexToUint8Array (7-16)
• uint8ArrayToHex (1-5)

infrastructure/w3id/tests/w3id.test.ts (7)

infrastructure/w3id/src/index.ts (2)

• W3IDBuilder (15-121)
• W3ID (8-13)

infrastructure/w3id/tests/utils/store.ts (1)

• InMemoryStorage (4-40)

infrastructure/w3id/tests/utils/crypto.ts (2)

• createSigner (27-38)
• verifierCallback (10-25)

infrastructure/w3id/src/logs/log-manager.ts (1)

• IDLogManager (30-188)

infrastructure/w3id/src/utils/hash.ts (1)

• hash (4-26)

infrastructure/w3id/src/utils/codec.ts (1)

• uint8ArrayToHex (1-5)

infrastructure/w3id/src/logs/log.types.ts (1)

• LogEvent (1-9)

infrastructure/w3id/src/logs/log-manager.ts (1)

infrastructure/w3id/src/logs/log.types.ts (6)

• Signer (17-20)
• LogEvent (1-9)
• VerifierCallback (11-15)
• RotationLogOptions (22-25)
• GenesisLogOptions (27-30)
• CreateLogEventOptions (43-43)

🪛 Biome (1.9.4)

infrastructure/w3id/tests/w3id.test.ts

[error] 55-55: Unsafe usage of optional chaining.

If it short-circuits with 'undefined' the evaluation will throw TypeError here:

(lint/correctness/noUnsafeOptionalChaining)

🔇 Additional comments (26)

infrastructure/w3id/src/errors/errors.ts (1)

1-34: LGTM! Type annotation cleanup

The removal of redundant : string type annotations from the error constructors is a good cleanup. The parameter types are already inferred from the default values, making the explicit annotations unnecessary.

infrastructure/w3id/tests/logs/log.test.ts (3)

1-8: Good refactoring of utility imports

The refactoring to import utilities from dedicated files rather than defining them inline improves code organization and reusability.

Also applies to: 16-17

---

22-25: Good use of dependency injection

Passing the signer to the IDLogManager constructor follows good dependency injection practices, making the code more maintainable and testable.

---

30-30:

❓ Verification inconclusive

Consider consistent signer usage

There's an inconsistency in how signers are used. A global signer is defined (line 22), but local signers are created in several test cases. While this might be intentional for specific test scenarios, it's worth reviewing if all these separate instances are necessary.

Also applies to: 63-64, 76-77, 116-117

---

🏁 Script executed:

#!/bin/bash
# Check how many unique signer instances are created and where they're used

echo "Checking signer creation patterns in test file:"
cat infrastructure/w3id/tests/logs/log.test.ts | grep -n "createSigner" | grep -v "import"

echo -e "\nChecking if these signers are necessary by examining how they're used:"
cat infrastructure/w3id/tests/logs/log.test.ts | grep -A 5 -B 5 "nextKeySigner" | grep -v "^--$"

Length of output: 2089

---

Review Consistent Signer Usage

It appears that multiple signer instances are created in this test file even when using the same key pair. For example:

• A global signer is defined with const signer = createSigner(keyPair); on line 22.
• A local instance is re-created with the same initialization on line 30.
• Additional signers are instantiated in key rotation tests (lines 63–64, 76–77, and 116–117) with varying key pairs.

Please verify if all these separate instances are intentional for simulating different scenarios or if consolidating them (for instance, reusing the global signer where possible) would maintain clarity and reduce potential redundancy.

infrastructure/w3id/tests/w3id.test.ts (4)

15-19: LGTM! Good basic test for ID creation

This test correctly verifies that a basic W3ID can be created without any additional options, and that the logs property remains undefined in this case.

---

21-24: LGTM! Good verification of global ID format

This test correctly verifies that when the global flag is set to true, the resulting ID starts with '@'.

---

31-46: LGTM! Excellent test for deterministic ID generation

This test properly validates the deterministic nature of the ID generation when the same namespace and entropy are provided, which is crucial for consistency.

---

59-80: LGTM! Comprehensive test for key rotation

This test thoroughly validates the key rotation functionality by creating a new key pair, performing a rotation, and verifying the log chain remains valid. The assertions are well-chosen to ensure the integrity of the log chain.

infrastructure/w3id/tests/utils/crypto.ts (1)

10-25: LGTM! Well-implemented signature verification

The verifierCallback implementation correctly handles the complex process of signature verification:

1. Decodes the signature from base58btc
2. Converts the message to a Uint8Array
3. Converts the public key from hex format
4. Uses tweetnacl's verify method with proper parameters

infrastructure/w3id/src/index.ts (10)

8-13: LGTM! Clean and simple W3ID class design

The W3ID class has a clean interface with just the essential properties - an ID string and an optional logs manager.

---

15-22: LGTM! Well-structured properties for the builder pattern

The W3IDBuilder class correctly implements the builder pattern with private properties for all configuration options. The default value for global (false) is appropriate.

---

23-31: LGTM! Well-documented fluent interface method

Good implementation of the fluent interface pattern with thorough JSDoc documentation.

---

33-41: LGTM! Clear documentation for namespace parameter

The withNamespace method is well-documented, clearly explaining its purpose in generating UUIDv5 identifiers.

---

43-56: LGTM! Excellent documentation of the global identifier concept

The withGlobal method has comprehensive documentation that clearly explains the purpose and meaning of global identifiers in the system, which is very helpful for developers.

---

58-67: LGTM! Good documentation for repository integration

The withRepository method is well-documented, explaining its purpose in the overall W3ID architecture.

---

69-78: LGTM! Clear documentation of signer requirements

The withSigner method's documentation effectively communicates that a repository is also required when attaching a keypair.

---

80-89: LGTM! Well-documented next key hash method

The withNextKeyHash method is well-documented, clearly explaining its purpose in the key rotation mechanism.

---

96-104: LGTM! Good fallback handling for optional parameters

The build method correctly handles optional parameters by providing fallbacks for entropy and namespace, and properly formats the ID based on the global flag.

---

114-120: LGTM! Proper initialization of IDLogManager and genesis log

The build method correctly initializes the IDLogManager with the repository and signer, and creates a genesis log event with the ID and next key hash.

infrastructure/w3id/src/logs/log-manager.ts (7)

14-14: LGTM! Proper type usage for Signer

Good use of the type keyword for importing types, which ensures they're only used for type checking and don't affect the runtime.

---

32-37: LGTM! Good refactoring to centralize signer management

Storing the signer as an instance property centralizes the signing responsibility within the class, which is a good design improvement.

---

39-50: LGTM! Improved method documentation

The addition of proper JSDoc comments with param tags and return type documentation improves the API clarity.

---

85-97: LGTM! Comprehensive documentation for verifyLogEventProof

The addition of detailed JSDoc comments with param tags and return type improves the understanding of this critical security method.

---

116-148: LGTM! Well-documented appendEntry method with proper signer update

The refactored appendEntry method now correctly:

1. Uses the instance signer for signing
2. Updates the instance signer to the next key signer after rotation
3. Has improved documentation

This is a significant improvement to the key rotation flow.

---

150-171: LGTM! Improved genesis entry creation

The createGenesisEntry method now properly:

1. Uses the instance signer for signing
2. Handles IDs with '@' prefix correctly
3. Uses the signer's public key for updateKeys
4. Has enhanced documentation

---

173-187: LGTM! Well-typed createLogEvent method

The addition of explicit return type and comprehensive JSDoc comments improves the API clarity for this key method.