fix: add tamper check for all blockchain functions

[RishabhS7]

Overview

Adds document signature verification to all blockchain operations to prevent tampering before executing transactions.

Changes

New File

• src/utils/document-verification.ts: Implements verifyDocumentSignature() function that validates both OpenAttestation (v2/v3) and W3C credential signatures

Updated Commands

Document Store (5 files):

• issue.ts, revoke.ts, grant-role.ts, revoke-role.ts, transfer-ownership.ts

Token Registry (1 file):

• mint.ts

Title Escrow (9 files):

• accept-return-to-issuer.ts, endorse-transfer-owner.ts, nominate-transfer-owner.ts
• reject-return-to-issuer.ts, reject-transfer-holder.ts, reject-transfer-owner.ts, reject-transfer-owner-holder.ts
• return-to-issuer.ts, transfer-holder.ts, transfer-owner-holder.ts

Test Updates

Updated 26 test files to mock verification functions (isWrappedV2Document, isWrappedV3Document, verifyOASignature, verifyW3CSignature, deriveW3C, verifyDocumentSignature)

Impact

• ✅ All blockchain operations now verify document integrity before execution
• ✅ Prevents tampered documents from being processed
• ✅ Supports both OpenAttestation and W3C credential formats

Security Enhancement

Documents are now validated for tampering at the earliest point in each command's execution flow, immediately after reading the document and before any blockchain interactions.

Summary by CodeRabbit

• New Features

  • Added document signature verification to validate authenticity before processing. This security check is now enforced across all document store operations and title-escrow operations before further processing.

• Tests

  • Updated test mocks to support signature verification testing across affected operations.

[coderabbitai]

ℹ️ Recent review info

Configuration used: defaults

Review profile: CHILL

Plan: Free

📥 Commits

Reviewing files that changed from the base of the PR and between a3906da and 5395c12.

📒 Files selected for processing (42)

• src/commands/document-store/grant-role.ts
• src/commands/document-store/issue.ts
• src/commands/document-store/revoke-role.ts
• src/commands/document-store/revoke.ts
• src/commands/document-store/transfer-ownership.ts
• src/commands/title-escrow/accept-return-to-issuer.ts
• src/commands/title-escrow/endorse-transfer-owner.ts
• src/commands/title-escrow/nominate-transfer-owner.ts
• src/commands/title-escrow/reject-return-to-issuer.ts
• src/commands/title-escrow/reject-transfer-holder.ts
• src/commands/title-escrow/reject-transfer-owner-holder.ts
• src/commands/title-escrow/reject-transfer-owner.ts
• src/commands/title-escrow/return-to-issuer.ts
• src/commands/title-escrow/transfer-holder.ts
• src/commands/title-escrow/transfer-owner-holder.ts
• src/commands/token-registry/mint.ts
• src/utils/document-verification.ts
• src/utils/index.ts
• tests/commands/document-store/grant-role.test.ts
• tests/commands/document-store/issue.test.ts
• tests/commands/document-store/revoke-role.test.ts
• tests/commands/document-store/revoke.test.ts
• tests/commands/document-store/transfer-ownership.test.ts
• tests/commands/title-escrow/accept-return-to-issuer-astron.test.ts
• tests/commands/title-escrow/accept-return-to-issuer-astrontestnet.test.ts
• tests/commands/title-escrow/accept-return-to-issuer.test.ts
• tests/commands/title-escrow/endorse-transfer-owner-astron.test.ts
• tests/commands/title-escrow/endorse-transfer-owner-astrontestnet.test.ts
• tests/commands/title-escrow/endorse-transfer-owner.test.ts
• tests/commands/title-escrow/nominate-transfer-owner-astron.test.ts
• tests/commands/title-escrow/nominate-transfer-owner-astrontestnet.test.ts
• tests/commands/title-escrow/nominate-transfer-owner.test.ts
• tests/commands/title-escrow/reject-return-to-issuer.test.ts
• tests/commands/title-escrow/reject-transfer-holder.test.ts
• tests/commands/title-escrow/return-to-issuer.test.ts
• tests/commands/title-escrow/transfer-holder-astron.test.ts
• tests/commands/title-escrow/transfer-holder-astrontestnet.test.ts
• tests/commands/title-escrow/transfer-holder.test.ts
• tests/commands/title-escrow/transfer-owner-holder-astron.test.ts
• tests/commands/title-escrow/transfer-owner-holder-astrontestnet.test.ts
• tests/commands/title-escrow/transfer-owner-holder.test.ts
• tests/commands/token-registry/mint.test.ts

---

📝 Walkthrough

Walkthrough

A new document signature verification function is introduced and integrated across 14 command modules. The verifyDocumentSignature utility validates documents after reading but before processing, supporting both OpenAttestation and W3C formats with optional credential derivation, and is called early in the input flow to fail fast on invalid signatures.

Changes

Cohort / File(s)	Summary
Document-Store Commands src/commands/document-store/grant-role.ts, issue.ts, revoke-role.ts, revoke.ts, transfer-ownership.ts	Added import and invocation of verifyDocumentSignature(document) after reading the document and before extracting document store info, introducing an early validation checkpoint.
Title-Escrow Commands src/commands/title-escrow/accept-return-to-issuer.ts, endorse-transfer-owner.ts, nominate-transfer-owner.ts, reject-return-to-issuer.ts, reject-transfer-holder.ts, reject-transfer-owner-holder.ts, reject-transfer-owner.ts, return-to-issuer.ts, transfer-holder.ts, transfer-owner-holder.ts	Added import and call to verifyDocumentSignature(document) in promptForInputs following document read, before extracting document info; ensures signature validity prior to further processing.
Token-Registry Commands src/commands/token-registry/mint.ts	Added import and invocation of verifyDocumentSignature(document) after reading the document and before extracting document info.
Verification Utility Core src/utils/document-verification.ts, src/utils/index.ts	New verifyDocumentSignature() function exported; detects document type (OpenAttestation v2/v3 or W3C), calls appropriate verification function (verifyOASignature or verifyW3CSignature), handles optional derivation via deriveW3C, and throws descriptive errors on tampering.
Test Mocks tests/commands/document-store/*.test.ts, tests/commands/title-escrow/*.test.ts, tests/commands/token-registry/mint.test.ts	Added mock implementations for verifyDocumentSignature, isWrappedV2Document, isWrappedV3Document, verifyOASignature, verifyW3CSignature, and deriveW3C to support testing of signature verification flows; removed legacy TradeTrustToken factory mocks from two escrow tests.

Sequence Diagram

sequenceDiagram
    participant Client as Command Handler
    participant promptInputs as promptForInputs()
    participant verifyDS as verifyDocumentSignature()
    participant trustvc as `@trustvc` library
    
    Client->>promptInputs: invoke with document path
    promptInputs->>promptInputs: read document
    promptInputs->>verifyDS: call verifyDocumentSignature(document)
    
    alt is OpenAttestation document
        verifyDS->>trustvc: call verifyOASignature()
        trustvc-->>verifyDS: return verification result
    else is W3C/TrustVC document
        verifyDS->>trustvc: call verifyW3CSignature()
        trustvc-->>verifyDS: return { verified, ... }
        alt derivation required
            verifyDS->>trustvc: call deriveW3C()
            trustvc-->>verifyDS: return derived credential
        end
    end
    
    alt verification successful
        verifyDS-->>promptInputs: return (void)
        promptInputs->>promptInputs: extract document info
        promptInputs-->>Client: continue processing
    else verification failed
        verifyDS-->>promptInputs: throw error
        promptInputs-->>Client: halt with error
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Poem

A signature check hops through the code,
Validating documents down the road,
OpenAttestation and W3C aligned,
No tampering sneaks past our verification line! 🐰✨

Tip

Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs).
Share your feedback on Discord.

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/login.

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

[tradetrustimda]

🎉 This PR is included in version 1.0.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀