feat: document builder bbs2023 support

[Moiz47]

Summary

Document builder signing support for bbs2023

Summary by CodeRabbit

• Chores

  • Updated credential and W3C context dependencies to latest alpha versions.

• Bug Fixes

  • Removed support for BbsBlsSignature2020 crypto suite; requests using this suite will now throw an error.

• Tests

  • Enhanced test coverage for BBS2023 cryptographic signature and verification flows.

[coderabbitai]

Walkthrough

Dependency versions for @trustvc/w3c-related packages updated. DocumentBuilder test coverage expanded to include BBS2023 sign, derive, and verify flows while removing legacy BBS2020 tests. Core DocumentBuilder.sign() method refactored to exclude BbsBlsSignature2020 and simplify derived-verification logic.

Changes

Cohort / File(s)	Summary
Dependency Updates package.json	Updated @trustvc/w3c-related scoped packages to newer alpha versions: @trustvc/w3c (^1.3.0-alpha.14 → ^1.3.0-alpha.17), @trustvc/w3c-credential-status (^1.3.0-alpha.12 → ^1.3.0-alpha.13), @trustvc/w3c-vc (^1.3.0-alpha.14 → ^1.3.0-alpha.17).
Test Suite Expansion src/__tests__/core/documentBuilder.test.ts	Added comprehensive BBS2023 test coverage including sign, derive, verify, and error flows; removed legacy BBS2020 test block; updated imports to include Bbs2023PrivateKeyPair and CryptoSuite; refined test descriptions to indicate crypto suite in use.
Core Implementation src/core/documentBuilder.ts	Removed CryptoSuite and BBS_V1_URL imports; updated sign() signature to exclude BbsBlsSignature2020 via Exclude type; added runtime guard to reject BbsBlsSignature2020; unconditionally added DATA_INTEGRITY_V2_URL context; simplified verify flow derived-check logic.

Sequence Diagram(s)

sequenceDiagram
    participant Caller
    participant DocumentBuilder
    participant SignatureHandler
    participant VerifyHandler

    rect rgb(220, 240, 255)
        Note over Caller,VerifyHandler: Sign Flow (BBS2023 or ECDSA allowed)
        Caller->>DocumentBuilder: sign(privateKey, cryptoSuite)
        alt cryptoSuite === 'BbsBlsSignature2020'
            DocumentBuilder-->>Caller: ❌ Error: BbsBlsSignature2020 not supported
        else cryptoSuite is BBS2023 or ECDSA
            DocumentBuilder->>SignatureHandler: Sign with selected suite
            Note over DocumentBuilder: Add DATA_INTEGRITY_V2_URL context
            SignatureHandler-->>DocumentBuilder: ✅ Signed document
            DocumentBuilder-->>Caller: Return signed document
        end
    end

    rect rgb(240, 220, 255)
        Note over Caller,VerifyHandler: Verify Flow (derived-required check)
        Caller->>DocumentBuilder: verify(document, publicKey)
        alt !isDerived
            DocumentBuilder-->>Caller: ❌ Error: Derivation required for verification
        else isDerived
            DocumentBuilder->>VerifyHandler: Verify derived document
            VerifyHandler-->>DocumentBuilder: ✅ Verification successful
            DocumentBuilder-->>Caller: Return verification result
        end
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

The changes involve refactored crypto suite handling logic, updated method signatures with type constraints, runtime guards, modified verification flow, and expanded test coverage. Changes are cohesive and pattern-driven but require careful verification of cryptographic logic correctness, type safety, and test validity across multiple files.

Possibly related PRs

• feat: update sign and derive #114: Directly modifies DocumentBuilder signing and derivation behavior to disallow BbsBlsSignature2020 while adding BBS2023 flow tests.
• feat: bbs2023 verification fragment #115: Implements BBS2023 verification fragment and derived-verification flow logic related to the DocumentBuilder verify changes.
• feat: update document builder to data model 2.0 #104: Modifies src/core/documentBuilder.ts sign() method signature and cryptographic suite/context handling with similar BBS suite guards.

Suggested reviewers

• RishabhS7
• rongquan1

Poem

🐰✨ Hops through code with joy so bright,
BBS2023 shines in cryptic light,
Legacy BBS2020, farewell old friend,
Derived checks ensure verification's end,
Tests hop forward, signatures align,
Trust and verification—now by design! 🔐

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description Check	⚠️ Warning	The pull request description is significantly incomplete compared to the required template. While the description includes a "Summary" section heading, it provides only a single-line statement ("Document builder signing support for bbs2023") without explaining the background context. More critically, the description is missing two required sections entirely: the "Changes" section (which should detail what modifications were made, including dependency updates, test additions, and DocumentBuilder modifications) and the "Issues" section (which should reference related issues or stories). The current description lacks the structured detail necessary for reviewers to understand the scope and rationale of the changes.	To meet the repository's description requirements, please expand the pull request description to include all template sections. In the Summary, provide background context explaining why BBS2023 support is needed in the DocumentBuilder. In the Changes section, itemize the key modifications such as the dependency version bumps, the addition of BBS2023 test coverage, the removal of BBS2020 tests, and the updates to the DocumentBuilder.sign method signature and implementation. Finally, add an Issues section that references any associated GitHub issues, feature requests, or stories related to this work.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The pull request title "feat: document builder bbs2023 support" directly corresponds to the primary changes in the changeset, which focus on adding BBS2023 cryptographic suite support to the DocumentBuilder class. The title is specific and clear—it indicates both the component being modified (document builder) and the main feature being added (bbs2023 support). This is evidenced by the significant modifications to documentBuilder.ts that introduce BBS2023 handling and the expansion of test coverage in documentBuilder.test.ts to validate BBS2023 flows. The title is concise and avoids vague or generic terminology, making it easy for teammates reviewing the git history to understand the core intent of this change.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/document-builder-bbs2023-support

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between cbf2bb1 and 49c360a.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (3)

• package.json (1 hunks)
• src/__tests__/core/documentBuilder.test.ts (8 hunks)
• src/core/documentBuilder.ts (4 hunks)

🧰 Additional context used

🪛 Gitleaks (8.28.0)

src/__tests__/core/documentBuilder.test.ts

[high] 35-35: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.

(generic-api-key)

---

[high] 176-176: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.

(generic-api-key)

---

[high] 226-226: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.

(generic-api-key)

---

[high] 282-282: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.

(generic-api-key)

🔇 Additional comments (12)

src/core/documentBuilder.ts (5)

1-1: LGTM: Import cleanup aligns with type signature changes.

Removing CryptoSuite from the @trustvc/w3c-issuer import is correct since CryptoSuiteName is already imported from @trustvc/w3c-vc at line 6.

---

17-24: LGTM: Context import cleanup reflects BBS2020 deprecation.

Removing BBS_V1_URL is consistent with the deprecation of BbsBlsSignature2020 support. The code now relies on DATA_INTEGRITY_V2_URL (line 210) for all signing operations.

---

175-186: LGTM: Defense-in-depth approach for deprecating BbsBlsSignature2020.

The combination of compile-time type exclusion (Exclude<CryptoSuiteName, 'BbsBlsSignature2020'>) and runtime guard ensures robust deprecation enforcement. The runtime check protects against JavaScript callers and explicit type assertions, while TypeScript users get compile-time errors.

---

210-210: LGTM: Unconditional context addition aligns with Data Integrity v2 requirement.

Since both BBS2023 and ECDSA-SD-2023 require the Data Integrity v2 context, unconditionally adding it simplifies the logic and is correct for all supported crypto suites.

---

236-239: LGTM: Simplified verification logic enforces derived-only policy.

The updated logic correctly enforces that both ECDSA-SD-2023 and BBS-2023 require documents to be derived before verification. This simplification removes cryptosuite-specific checks while ensuring correct behavior for all supported suites.

Note: This is a behavioral change that makes derive() mandatory before verify() for all crypto suites.

src/__tests__/core/documentBuilder.test.ts (6)

3-8: LGTM: Import additions support BBS2023 test coverage.

The addition of Bbs2023PrivateKeyPair and CryptoSuite imports is necessary for the new BBS2023 test cases added below.

---

28-36: LGTM: Test key pair properly defined for BBS2023 testing.

The bbs2023KeyPair constant follows the same pattern as existing test keys. The static analysis warnings about the secretKeyMultibase field are false positives—these are test keys, not production secrets.

---

144-144: LGTM: Test descriptions clarified with crypto suite information.

Adding "using ECDSA" to test descriptions improves readability and helps distinguish between ECDSA and BBS2023 test cases.

Also applies to: 159-159

---

172-198: LGTM: Comprehensive BBS2023 test coverage added.

The new test cases validate the complete sign → derive → verify flow for both transferableRecords and verifiableDocument credential status types using BBS2023. The tests mirror the ECDSA test structure, ensuring consistent coverage across crypto suites.

---

208-208: LGTM: Error handling tests expanded for BBS2023.

Adding crypto suite identifiers to error test descriptions and including a BBS2023-specific error test ensures comprehensive error handling validation across both supported crypto suites.

Also applies to: 222-234

---

280-286: LGTM: Test validates BbsBlsSignature2020 deprecation enforcement.

This test properly validates the runtime guard that rejects BbsBlsSignature2020. The intentional use of as any bypasses TypeScript's type exclusion to test the runtime check, which protects against JavaScript callers and explicit type assertions.

package.json (1)

125-129: Confirm @TrustVC alpha dependencies and plan for breaking changes. All 1.3.0-alpha.x releases exist on npm; alpha versions may introduce breaking changes without notice—ensure these are intended for production or upgrade to stable versions.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[sonarqubecloud]

Quality Gate failed

Failed conditions
1 Security Hotspot

See analysis details on SonarQube Cloud

[tradetrustimda]

🎉 This PR is included in version 2.3.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀