feat: add verify command

[pennhan-dex]

Implement verify Command for Document Verification (W3C + OA)

Summary

This PR implements a new CLI command, verify, to validate documents. It supports verification for:

• W3C Verifiable Credentials
  • Non-transferable documents
  • Transferable documents
• OpenAttestation (OA) documents
  • Wrapped OA documents (v2/v3)

The command outputs verification results for the following fragments:

• DOCUMENT_INTEGRITY
• DOCUMENT_STATUS
• ISSUER_IDENTITY

and indicates if the document credential has expired.

What’s Included

Verification behaviour

• Automatic chain detection / provider resolution

  • For W3C transferable credentials, the command extracts chainId from the VC and resolves the correct provider automatically.
  • For OA documents, the command reads network.chainId from the document and resolves the provider accordingly.
  • If blockchain/network information is missing for OA, the command fails fast with an explicit error: Could not find blockchain information.

• Expiration warnings

  • For W3C documents, expiration warnings emitted by the underlying verification library are captured and surfaced as a CLI warning: The document credential has expired.
  • For OA documents, expiration is detected via expirationDate and also produces the same warning message.

• User experience

  • Prompts user for a document path (@inquirer/prompts) and loads it as JSON.
  • Prints success when a fragment is VALID, otherwise prints warn with the failure reason.

---

Tests Added

A total of 10 unit tests were added under tests/commands/verify.test.ts, covering both helper utilities and end-to-end verification flows using real fixtures.

Helper function coverage (6 tests)

• getResultFromFragment
  • Returns the first non-SKIPPED fragment of a given type
  • Throws when no matching non-SKIPPED fragment exists
• logResultStatus
  • Logs success when status is VALID
  • Logs warn (including reason) when status is not VALID
• handleExpiredCredentialWarning
  • Logs expiration warning when present
  • Does nothing when warning is not present

CLI prompt coverage (3 tests)

• Ensures prompt returns a parsed signed VC when a valid path is provided
• Validates required/empty path handling via the prompt validation function
• Throws when readJsonFile fails on an invalid path

End-to-end fixture verification coverage (1 parameterized test with 8 cases)

Uses actual documents in tests/fixtures/ to validate full verification behavior end-to-end:

• 4 W3C fixtures
  • operative
  • expired (expects expiration warning)
  • revoked (expects non-VALID DOCUMENT_STATUS)
  • inoperative
• 4 OA fixtures
  • operative
  • expired (expects expiration warning)
  • revoked (expects non-VALID DOCUMENT_STATUS)
  • inoperative

The test asserts the command produces outputs for:

• DOCUMENT_INTEGRITY
• DOCUMENT_STATUS
• ISSUER_IDENTITY

and validates warnings are emitted only for the expected scenarios.

Summary by CodeRabbit

Release Notes

• New Features

  • Added verify command to CLI for validating W3C credentials and OpenAttestation documents
  • Interactive prompts guide users through document verification workflow
  • Displays verification results for document integrity, issuer identity, and document status

• Tests

  • Added comprehensive test suite with fixture examples for various verification scenarios

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces a new verify CLI command that validates W3C credentials and OpenAttestation documents. It implements verification orchestration with provider-based fallbacks, result handling utilities, warning capture helpers, a comprehensive test suite, and multiple test fixtures for different credential types and verification scenarios.

Changes

Cohort / File(s)	Summary
CLI Command & Type Definitions README.md, src/commands/verify.ts, src/types.ts	Adds verify command with interactive prompts, dual verification paths (W3C and OpenAttestation), provider resolution, result extraction, and logging. Exposes FragmentType enum and public functions (handler, promptQuestions, verify, getResultFromFragment, logResultStatus, handleExpiredCredentialWarning). Updates documentation with usage examples.
Utility Functions src/utils/formatting.ts, src/utils/networks.ts	Introduces CaptureConsoleWarn and CaptureConsoleWarnAsync for capturing console warnings during execution. Minor import reordering in networks module.
Test Suite tests/commands/verify.test.ts	Comprehensive unit tests covering helper functions, promptQuestions validation, and end-to-end verification scenarios using fixture discovery matrix. Tests include assertions for fragment results, warning messages, and dynamic expectations based on fixture filenames.
Test Fixtures: OpenAttestation tests/fixtures/verify/oa/2.0/*, tests/fixtures/verify/oa/3.0/*	Multiple OA document fixtures including DNS-DID, DNS-TXT, DocStore, and TokenRegistry proof types across v2.0 and v3.0 schemas. Includes standard signed/wrapped documents and a variant without network field.
Test Fixtures: W3C tests/fixtures/verify/w3c/*	Various W3C verifiable credential fixtures using BBS 2020/2023 and ECDSA signature schemes, including transferable records, expired, and revoked credentials for comprehensive verification testing.

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI as Verify Handler
    participant Parser as Document Parser
    participant Router as Type Router
    participant VerifyOA as OA Verification
    participant VerifyW3C as W3C Verification
    participant Provider as Provider/Network
    participant Logger as Result Logger

    User->>CLI: invoke verify command
    CLI->>CLI: promptQuestions (interactive)
    User->>CLI: provide document path
    CLI->>Parser: readJsonFile
    Parser-->>CLI: SignedVerifiableCredential
    CLI->>Router: determine type (OA vs W3C)
    
    alt OpenAttestation Document
        Router->>VerifyOA: verifyOpenAttestationDocument
        VerifyOA->>VerifyOA: checkExpiration
        VerifyOA->>Provider: get ChainId
        VerifyOA->>Provider: provider-based verification
        alt Provider Available
            Provider-->>VerifyOA: verification result
        else Provider Unavailable
            VerifyOA->>VerifyOA: fallback verification
        end
        VerifyOA-->>CLI: fragments + warnings
    else W3C Document
        Router->>VerifyW3C: verifyW3CDocument
        VerifyW3C->>Provider: resolveProviderFromNetwork
        alt Provider Resolved
            VerifyW3C->>Provider: provider-based verification
        else Provider Resolution Fails
            VerifyW3C->>VerifyW3C: fallback verification
        end
        VerifyW3C-->>CLI: fragments + warnings
    end
    
    CLI->>Logger: getResultFromFragment
    CLI->>Logger: logResultStatus
    CLI->>Logger: handleExpiredCredentialWarning
    Logger-->>User: display verification results

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~40 minutes

Poem

🐰 twitches nose at credentials new
W3C and OpenAttestation too!
Fragments dance through verify's gate,
Providers hop to seal the fate—
Signatures blessed, trust ornate! 🔐✨

---

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 📦🚀