Skip to content

feat: DRS verify-explain — human-readable verification failure explainer #6

@OkeyAmy

Description

@OkeyAmy

Problem

When chain verification fails, the verifier returns a structured VerificationResult with error code, message, and suggestion. But for developers and operators who are new to DRS, the error codes and messages are not always immediately clear. There is no tool that explains WHY verification failed in plain language with contextual help.

Proposed Solution

Build a drs verify-explain CLI command and/or SDK function that takes a VerificationResult and produces a detailed, human-readable explanation.

Acceptance Criteria

  • CLI command: drs verify-explain <bundle.json> — runs verification and outputs a detailed explanation of the result
  • On success: shows the verified context (root principal, chain depth, leaf policy, consent record if present)
  • On failure: shows the error code, which block (A-F) failed, what the verifier expected vs what it found, and a concrete fix suggestion
  • SDK function: explainVerificationResult(result: VerificationResult): string — can be used programmatically
  • Tests cover: all error codes from the verifier (EMPTY_CHAIN, MALFORMED_RECEIPT, CHAIN_BREAK, INVALID_SIGNATURE, POLICY_ESCALATION, EXPIRED, REVOKED, etc.)
  • No hardcoded error messages in tests — load error codes from a fixture or enum

Relevant Files

  • drs-verify/pkg/verify/chain.go — all error codes defined here
  • drs-verify/pkg/types/types.go — VerificationResult, VerificationError types
  • drs-sdk/src/sdk/types.ts — TypeScript mirror of the same types
  • drs-sdk/src/cli/commands/verify.ts — existing verify CLI command

Implementation Notes

Map each error code to a verification block (A-F) and provide block-specific context. The explainer should be useful for both developers debugging integration issues and operators investigating verification failures in production.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions