Agent-trust layer: dual-signed receipts, ERC-8004 identity, x401 shadow, caller binding (all flag-gated)

[Svaag]

Implements the accepted trust-layer plan (docs/plans/2026-07-10-agent-trust-layer.md) across every x402 service: ERC-8004 identifies the service, x401 proves authority when necessary, x402 proves payment, dual-signed receipts attest outcomes — Hyrule stays the deterministic execution engine.

Everything lands dark: all TRUST_* flags default off, and a guard test pins /.well-known/x402.json byte-identical to today's announced surface while they stay off (protects #53). Rollout is #54.

What's here (one commit per milestone)

• M1 — receipts core (0e6abb3): hyrule_cloud/trust/ (mypy-strict). Every settled payment on every paid route mints a receipt signed twice over the same canonical bytes — ES256 compact JWS (offline-verifiable via /.well-known/jwks.json) + EIP-712 ReceiptDigest (secp256k1, verifiable by EVM tooling / usable as ERC-8004 feedback evidence). Minted inside PaymentGate's settle paths (incl. settle_verified + dev-bypass), so all 13 intel routers, proxy, VM, domain, jobs — and future speedtest/mail — are covered with zero per-route changes. HYRULE-RECEIPT response header, GET /v1/receipts/{id}, migration 015 (+ ix_payment_events_tx_hash duplicate-settle detection — deliberately not a uniqueness constraint on the best-effort ledger). With TRUST_RECEIPTS_ENABLED=true the app refuses to boot unless both keys validate.
• M2 — fulfillment + refund receipts (9521017): orchestrator (provisioned/failed/simulated, with provision timings), extend, domain register, BGP job completion (artifact hash evidence), native BTC/XMR intents at first SETTLED, and both refund choke points (soft-linked to their refund_owed ledger event, idempotent). GET /v1/vm/{id}/receipts, hyrule_receipts_total + hyrule_payment_duplicate_settled_tx metrics, MCP/client tools, and the x402 canary now fails if an advertised receipt doesn't verify. Privacy invariant (test-pinned): native-rail receipts carry no deposit address and no txid, even hashed — correlation is the unguessable intent id.
• M3 — discovery-only ERC-8004 (156675b): registration document at /.well-known/agent-registration.json (spec pinned 2026-07-10 — the draft's filename, not the A2A agent-card guess), flag-gated manifest identity/receipts blocks, and scripts/erc8004_register.py (raw JSON-RPC + eth-account, no web3 dep; prints the ops-repo eth_getLogs monitoring query). The app runtime never reads chain state.
• M5+M6 — x401 (a0c6a59): v0.2.0 pinned (PROOF-REQUEST/PROOF-RESPONSE/PROOF-RESULT, base64url JSON, DCQL). TRUST_X401_MODE=shadow logs what enforcement WOULD require (migration 016) with HTTP responses byte-identical to off (test-pinned); the 402 gains an advisory x401 extension. Enforce (ships off) is proof-first-then-pay on /v1/vm/create only: 401 + PROOF-REQUEST before reservation and before the gate — a payment header without a valid proof never reaches verify/settle (gate call count 0, test-pinned). POST /v1/x401/proof issues TTL-bounded hyr_pf_ tokens scope-bound to quote/amount/route/method; the structural verifier only satisfies under a test-only flag and honestly 503s otherwise.
• M7 — caller binding (094a5e6): RFC 9421 → did:web, observe-only. Verified principals flow into ledger extras + receipt agent fields; SSRF-guarded resolution with positive/negative caches; every failure degrades to unverified/absent with the request untouched.
• Docs (5597613): docs/trust-layer.md, the open profile docs/x402-compute-fulfillment-receipt.md, docs/runbooks/trust-keys.md (ceremonies, rotation, monitoring), scripts/verify_receipt.py, plan copy, CLAUDE.md refresh.

Verification

• 381 tests pass (+56 new across 5 trust test files), mypy strict clean (new modules not in the override list), ruff clean.
• Migrations 015/016: up → down → up clean (001–014 are Postgres-only ARRAY, so chain-tested from a stamped 014; prod runs the real chain via ExecStartPre=alembic upgrade head as usual).
• Live loop with flags on: paid /v1/dns/lookup → HYRULE-RECEIPT header → both signatures verified offline via scripts/verify_receipt.py; receipt soft-links its ledger event; 402 carries bazaar + x401 advisory; agent-registration/JWKS/manifest blocks all serve. Flags off: no new headers, no manifest keys, agent-registration 404, JWKS empty.
• The 7 test_launch_blockers failures on main are pre-existing (stale x402.org facilitator in fixtures) — filed as Stale x402.org facilitator in .env.example era: 7 test_launch_blockers tests fail on clean main #55, untouched here.

Follow-ups

• Trust-layer rollout: key ceremony, ERC-8004 registration, Circle Gateway, receipt-backed feedback (post-trust-layer PR) #54 — rollout roadmap: M4-ops key ceremony + Sepolia→mainnet ERC-8004 registration + flag flips; M8 Circle Gateway spike; M9 receipt-backed feedback.
• Stale x402.org facilitator in .env.example era: 7 test_launch_blockers tests fail on clean main #55 — pre-existing stale-facilitator test failures.

🤖 Generated with Claude Code

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis 🔶 53 - Partially compliant Compliant requirements: Guard test pins /.well-known/x402.json byte-identical while flags off (protects Announce: register + seed + publish the x402 service (Phase 4/5 announcement checklist) #53) Non-compliant requirements: All other requirements are ops-gated or not code changes in this PR Requires further human verification: No further human verification needed from code review 54 - Partially compliant Compliant requirements: Implementation of dual-signed receipts (M1) with offline verification Fulfillment + refund receipts (M2) x401 shadow mode, policy engine, proof tokens (M5/M6) ERC-8004 identity scaffolding (agent card, registration) Receipt core integration into PaymentGate, orchestrator, intents, domain All TRUST_* flags default off, guard test for manifest Non-compliant requirements: Key ceremony, Vault storage, flag flips, ERC-8004 mainnet registration, network ops monitoring, Circle Gateway spike, external trust features Requires further human verification: All not-compliant items are operator-gated and require human ceremony 55 - Partially compliant Compliant requirements: (none) Non-compliant requirements: The PR does not address the stale facilitator URL in test fixtures Requires further human verification: (none)

⏱️ Estimated effort to review: 3 🔵🔵🔵⚪⚪

🏅 Score: 90

🧪 PR contains tests

🔒 No security concerns identified

⚡ No major issues detected

[github-actions]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Soft-fail proof token issuance The issue_proof_token method leaks the cleartext token in the response and has no timeout/bound on the database write. Since the token is returned exactly once and can be reused within TTL, if the database write succeeds but the response fails (e.g. network hiccup), the token is lost forever and the caller cannot retry. Wrap the commit and return in a soft-fail pattern similar to _log_decision: catch exceptions, log a warning, and return None to avoid breaking the calling flow. This is critical because an unhandled failure here would raise a 500 error during the proof flow, even though the documentation states that "a broken x401 store must never change a payment or provisioning outcome." hyrule_cloud/trust/x401.py [416-445] async def issue_proof_token( self, *, bound_quote_hash: str, route: str, method: str, - ... -) -> str: + claims: dict[str, str] | None = None, + agent_did: str | None = None, +) -> str | None: if self._session_factory is None: - raise RuntimeError("x401 proof tokens need a session factory") - cleartext = generate_proof_token() - row = X401ProofTokenRow( - token_hash=_hash_token(cleartext), - quote_hash=bound_quote_hash, - ... - ) - async with self._session_factory() as session: - session.add(row) - await session.commit() - return cleartext + return None + try: + cleartext = generate_proof_token() + row = X401ProofTokenRow( + token_hash=_hash_token(cleartext), + quote_hash=bound_quote_hash, + route=route[:256], + method=method[:8], + claims=claims or None, + agent_did=agent_did[:256] if agent_did else None, + expires_at=datetime.now(UTC) + + timedelta(seconds=self.config.x401_proof_token_ttl_seconds), + ) + async with self._session_factory() as session: + session.add(row) + await session.commit() + return cleartext + except Exception: + log.warning("x401_issue_token_failed", exc_info=True) + return None Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies that a database failure in issue_proof_token would raise an unhandled exception, violating the documented invariant that a broken x401 store must never change the payment/provisioning outcome. Adding a try/except block with a logged warning and returning None aligns with the soft-fail pattern used elsewhere in the same class. The change is relevant and improves robustness.	Medium
	Return True on DB lookup failure The check_proof_token method logs a warning on DB failure but returns a hard False, which in enforce mode would reject a legitimate caller. According to the docstring, "a broken x401 store must never change a payment or provisioning outcome (in shadow mode by definition; in enforce mode a log failure still never blocks)". However, a DB transient failure during check_proof_token would cause a false negative and block (or fail) the request. Change the except block to return True when the lookup fails, preserving the invariant that store failures never change the outcome. hyrule_cloud/trust/x401.py [447-482] -async def check_proof_token( - self, - cleartext: str, - *, - bound_quote_hash: str, - route: str, - method: str, -) -> bool: - if self._session_factory is None or not cleartext.startswith("hyr_pf_"): - return False - try: - async with self._session_factory() as session: - row = ( - await session.execute( - select(X401ProofTokenRow).where( - X401ProofTokenRow.token_hash == _hash_token(cleartext) - ) - ) - ).scalar_one_or_none() - except Exception: - log.warning("x401_token_lookup_failed", exc_info=True) - return False - if row is None: - return False - expires = row.expires_at - if expires.tzinfo is None: - expires = expires.replace(tzinfo=UTC) - if expires < datetime.now(UTC): - return False - return ( - row.quote_hash == bound_quote_hash - and row.route == route[:256] - and row.method == method[:8] - ) +except Exception: + log.warning("x401_token_lookup_failed", exc_info=True) + return True Suggestion importance[1-10]: 5 __ Why: The suggestion aims to prevent a DB failure from blocking a legitimate request by returning True instead of False. While this respects the invariant that store failures should not break the flow, it could introduce a security bypass if an attacker triggers a transient DB error. A more balanced approach might be to raise a warning and treat the token as invalid, but the suggestion is not wrong. Score reflects moderate impact and potential trade-off.	Low

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5597613306

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Pin DID document fetches to the vetted address

When TRUST_PRINCIPAL_MODE=observe and a request supplies a did:web keyid, this preflight checks the hostname with resolve_public_addresses, but client.get(url) performs a fresh DNS lookup. A DNS-rebinding DID host can return a public IP for the check and then a private/link-local IP for the actual HTTPS GET, turning signature observation into an SSRF to port 443 despite the guard. Reuse the vetted address or a transport that pins it while preserving Host/SNI.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Enforce x401 on advertised VM extensions

When TRUST_X401_MODE=enforce and an extension exceeds the duration/amount threshold, this code logs the STEP_UP decision and then proceeds to gate.check_payment without requiring PROOF-RESPONSE. Since the x401 policy/advisory advertises /v1/vm/{vm_id}/extend as a required-conditionally step-up route, clients can pay for elevated extensions without the proof the server says is required. Apply _x401_enforce_or_none here or stop advertising extend as enforced.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Avoid minting duplicate job completion receipts

If the internal worker retries /v1/internal/bgp/jobs/{job_id}/complete after losing the response, the row is already completed but this path still sets completed = True, so the receipt block below mints another fulfillment receipt for the same paid job/artifact. That inflates receipt metrics and exposes multiple attestations for one completion; only mint when transitioning from a non-completed status.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Reject stale caller signatures

When TRUST_PRINCIPAL_MODE=observe, a captured signature with an old created value and no expires is still accepted because only future timestamps and expired expires values are rejected. This contradicts the stated ±300s skew rule and lets a replayed signature for the same method/URI be recorded as a verified agent in ledger rows and receipts long after it was signed; also reject created < now - _CLOCK_SKEW_SECONDS.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Avoid stamping payment receipts with provisional VM ids

When a paid VM create uses a pre-payment reservation, the payment receipt is minted during gate.check_payment, before the reservation is known to survive. If the reservation is later released or replaced (for example a consumed-quote race or a reservation swept during a very slow settlement), the returned HYRULE-RECEIPT points at a VM id that was deleted or never fulfilled. Only correlate the payment receipt to the stable quote/order here, and let fulfillment receipts carry the final VM id.

Useful? React with 👍 / 👎.

[Svaag]

Folded #69 (ed25519 signed measurements) into this PR — commit b46e429. Signed measurements now live under the same trust umbrella: one key namespace (TRUST_MEASUREMENT_SIGNING_*), the shared /.well-known/jwks.json (OKP/Ed25519 entry alongside the receipt keys), advertised only in agent-registration (signedMeasurements) so the x402 manifest stays byte-identical with flags off. New files: trust/measurements.py, middleware/signing.py, tests/test_trust_measurements.py (9 tests). Full suite 397 pass, mypy strict + ruff clean.

⚠️ This PR is CONFLICTING with main — it is behind by several merged commits (CDP switch, domain-reselling) with genuine conflicts in the routes/orchestrator area. Needs a rebase onto origin/main before it can merge. Flagging separately from this fold since the conflicts are in domain code, not the trust layer.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b46e429339

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Sign every paid JSON response, not only Bazaar routes

With measurement signing enabled, a successful paid POST /v1/vm/{vm_id}/extend is not signed because this predicate only accepts paths listed in DISCOVERY, which contains /v1/vm/create but not the paid extend route. The same gap applies to other paid routes that are not Bazaar declarations. This contradicts the configured and documented contract of signing each paid 2xx JSON body, leaving buyers unable to verify those delivered results; derive this from the payment gate/route metadata or add all paid routes to the signed-operation set.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Canonicalize proof amounts before hashing

In enforce mode, a proof submitted with a numerically correct but differently formatted amount (for example "9") hashes differently from the create route's computed Decimal("9.00"), so the retry is rejected as proof_invalid. This is especially problematic for unquoted creates because the PROOF-REQUEST returns only the hash, not the server's exact decimal spelling for clients to reproduce. Hash a normalized decimal representation (or bind to a server-issued quote) so equivalent amounts produce the same token binding.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Do not advertise disabled receipt endpoints in the agent card

When TRUST_AGENT_CARD_ENABLED=true but TRUST_RECEIPTS_ENABLED=false, this unconditional services list advertises /v1/receipts/{receipt_id} even though get_receipt returns 404 whenever receipts are disabled. The flags are intentionally independent, so an identity-only rollout publishes a service agents cannot use; add the receipt and JWKS service declarations only when their corresponding trust functionality is enabled.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Include the delivered artifact digest in job evidence

For a completed BGP job this receipt records only the opaque snapshot ID, even though BGPSnapshotRow stores the artifact's sha256 and the receipt profile promises a delivered artifact hash as evidence. A recipient who downloads the gzip cannot verify that it is the artifact being attested, so the receipt is not usable as the advertised delivery evidence; load the snapshot and include its digest (and preferably format) in evidence.

Useful? React with 👍 / 👎.