Skip to content

Validate buyer-required JSON output paths - #2

Open
epistemedeus wants to merge 2 commits into
bilalxashraf:mainfrom
epistemedeus:codex/output-contract-validation-r1
Open

epistemedeus wants to merge 2 commits into
bilalxashraf:mainfrom
epistemedeus:codex/output-contract-validation-r1

Conversation

@epistemedeus

Copy link
Copy Markdown

Summary

Add an optional buyer-owned output contract to paid_fetch:

  • callers can declare up to 16 required own-property JSON paths through the CLI, MCP, or daemon API
  • the canonical path set binds into the existing request/idempotency hash before authorization
  • settled responses are recorded before delivery validation
  • invalid delivery returns OUTPUT_INVALID with bounded payment and contract evidence
  • replay revalidates the stored response without another merchant request, signature, or payment

Calls without requiredJsonPaths preserve the existing request hash and behavior. This adds no dependency or database migration.

Why

SpendTree already proves authorization, settlement, response persistence, and replay. The remaining buyer-side gap is deciding whether the purchased response contains the fields that make it usable. This change provides a narrow presence contract without claiming that the seller attested to it or introducing general JSON Schema machinery.

It also makes the planned maintained canary in #1 able to distinguish "paid" from "paid and delivered the fields the buyer required."

Safety properties

  • canonical, deduplicated and order-independent path identity
  • maximum 16 paths, 8 segments, and 256 characters per path
  • prototype-related segments and unsafe syntax rejected
  • own-property traversal only; a present null value still counts as present
  • non-2xx, malformed JSON, truncated responses, and missing paths fail closed when a contract is requested
  • settlement and bounded response evidence remain recorded before an invalid-delivery error
  • unchanged v0 request hashes when no contract is supplied

Verification

Run on Node.js 24.20.0:

  • npm ci
  • npm run check (17/17 tests)
  • npm run build
  • built CLI help exposes repeatable --require-path
  • built MCP paid_fetch schema exposes optional requiredJsonPaths with maxItems: 16

The hostile regression proves that a settled HTTP 200 missing a required nested path is recorded, rejected, and rejected again on replay with zero additional network calls or payment signatures.

@epistemedeus

Copy link
Copy Markdown
Author

Controller replay on the current head 782ee77 passes npm run check under the repository-required Node 24: strict typecheck plus all 17 tests. The follow-up commit only makes the flat test/*.test.ts suite reachable through the existing npm test command. The buyer contract remains bound into request identity before authorization; settled invalid delivery stays stored, counted, and replayed without a second signature.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant