Skip to content

Add backward-compatible CLAS proof signature union support#26

Merged
GsCommand merged 1 commit into
mainfrom
codex/update-runtime-core-for-clas-proof-compatibility
May 22, 2026
Merged

Add backward-compatible CLAS proof signature union support#26
GsCommand merged 1 commit into
mainfrom
codex/update-runtime-core-for-clas-proof-compatibility

Conversation

@GsCommand
Copy link
Copy Markdown
Contributor

Motivation

  • Make metadata.proof compatible with CLAS trust schemas that allow either legacy single-signature objects or multi-signature arrays, and avoid crashes when proof.signature is not an object.
  • Preserve existing single-signature behavior and fail closed on unsupported or malformed proofs.
  • Recognize new canonicalization identifiers such as erc8211.merkle.v1 without silently accepting them as cryptographically verified.

Description

  • Introduce explicit types for signatures and roles: CommandLayerProofSignature, CommandLayerProofSignatureRole, CommandLayerProofSignatureWithRole, and CommandLayerProofSignatureField, and update CommandLayerProof.signature to use the union type. (src/compat.ts)
  • Add type guards and helpers: isSingleSignature, isMultiSignature, and getPrimarySignature(proof, preferredRole?) which selects a concrete signature with priority runtimeagentverifier → first valid. (src/compat.ts)
  • Update verifyCommandLayerReceipt to select and validate a single concrete signature entry before accessing .value/.kid/.alg, return structured errors for malformed signatures instead of throwing, and verify only the selected signature. (src/compat.ts)
  • Extend default allowed canonicalizations to include erc8211.merkle.v1 and add a clear fail-closed result ERR_UNSUPPORTED_MERKLE_VERIFICATION when Merkle verification is recognized but not implemented. (src/compat.ts)
  • Update isSignedCommandLayerReceipt to accept either a single signature object or a multi-signature array with at least one valid entry, and ensure metadata like metadata.trace does not cause false negatives. (src/compat.ts)
  • Export the new helpers/types from the package entry so callers can use them. (src/index.ts)
  • Add and update tests to cover single-signature compatibility, multi-signature shapes, non-throwing multi-signature verification, malformed arrays returning invalid results, Merkle canonicalization recognition, and safe handling of metadata.trace. (test/compat.test.ts)

Testing

  • Ran npm install, npm test, npm run build, and npm run typecheck; all commands completed successfully.
  • Unit tests added and updated in test/compat.test.ts passed; existing single-signature verification tests continue to pass.
  • New tests verify that multi-signature arrays are accepted by the shape guard and do not crash verification, malformed signature arrays return INVALID with ERR_MALFORMED_SIGNATURE_ARRAY, and erc8211.merkle.v1 is recognized but results in ERR_UNSUPPORTED_MERKLE_VERIFICATION until full Merkle verification is implemented.
  • Files changed: src/compat.ts, src/index.ts, test/compat.test.ts.

Codex Task

@GsCommand GsCommand merged commit d6ba13e into main May 22, 2026
3 checks passed
@GsCommand GsCommand deleted the codex/update-runtime-core-for-clas-proof-compatibility branch May 22, 2026 19:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant