Add protocol v1.1.0 schema validation and tooling#4
Merged
Conversation
…I/tests/docs Critical fixes: - Fix COMMANDLAYER_VERIFY_PATH default: /api/verify → /verify (matches runtime) - Remove dead receiptVerifier.js (4th incompatible receipt format, never called) - Remove unused canonicalize.js (only imported by the now-dead receiptVerifier) - Add shared receiptSchema.js with Zod v1.1.0 receipt schema (new field names) - verify_receipt tool now validates receipt structure before proxying (was z.any()) Architecture improvement: - Tool definitions moved to module level; server still created per-request to avoid concurrent-request transport collision, but schemas/handlers defined once New tools: - get_protocol_version: returns signing spec, canonicalization, schema host - validate_receipt_schema: validates receipt structure without crypto (dev tool) Infrastructure: - Add test/tools.test.js with unit tests for all tool handlers - Add .github/workflows/ci.yml - Add .env.example documenting all env vars - Add SECURITY.md, CHANGELOG.md - Bump version to 1.1.0 - Health endpoint now returns version
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR introduces protocol v1.1.0 support with structured receipt schema validation, two new diagnostic tools, and comprehensive test coverage. The server now validates receipt structure at the MCP layer before proxying to the runtime, and provides tools for clients to discover protocol capabilities and validate receipts without cryptographic verification.
Key Changes
New receipt schema (
src/lib/receiptSchema.js) — Zod-based validation for the v1.1.0 receipt format with strict proof field validation (canonical, alg, signature, kid, signer_id). Reused by bothverify_receiptinput validation and the newvalidate_receipt_schematool.New tools:
get_protocol_version— returns protocol version (1.1.0), signing spec, canonicalization method, proof field names, and schema host URLvalidate_receipt_schema— validates receipt structure without cryptographic verification; returns structured field-level errors for development/debuggingTool registration refactored — tool definitions now declared at module level (
TOOL_DEFS) so Zod schemas and handler references are evaluated once at startup rather than per-request. New McpServer instance still created per request to avoid transport collision under concurrent load.Breaking change: Default verify path corrected from
/api/verifyto/verifyto match the runtime server's actual endpoint. Configurable viaCOMMANDLAYER_VERIFY_PATH.Dead code removed:
src/lib/receiptVerifier.js— implemented a 4th incompatible receipt format (payload/signer/hash/signature) never called by any toolsrc/lib/canonicalize.js— duplicate implementation only imported by receiptVerifier; canonical implementation lives in @commandlayer/runtime-coreTest suite (
test/tools.test.js) — 11 unit tests covering all tool handlers (no network required). Tests validate schema acceptance/rejection, capability filtering, and error handling.Documentation:
CHANGELOG.md— detailed v1.1.0 release notes with breaking changesSECURITY.md— security model, rate limiting guidance, and known limitations.env.example— environment variable referenceCI/CD — GitHub Actions workflow (
.github/workflows/ci.yml) runs tests on every push and PR.Version bump — package.json and health endpoint updated to 1.1.0.
Implementation Details
safeParse()to return structured errors with field paths and codes, enabling clients to provide precise feedback.canonical: 'json.sorted_keys.v1'andalg: 'ed25519'as literals to reject pre-v1.1.0 field names at the MCP boundary.validate_receipt_schemais intentionally non-cryptographic — it validates structure only and must not be used as a security gate.https://claude.ai/code/session_0112Taq5ne2BieC3hfqjjf3r