Phase 4b: ed25519 signed measurements (x402 trust layer)

[Svaag]

What

Every paid catalog 2xx JSON response now carries a detached ed25519 signature over its exact body, so a buyer (or a third party) can prove a Hyrule measurement is authentic and unaltered. This is the x402 ecosystem's most-requested missing piece — a verifiable trust layer, which no other provider offers.

Ships dark: no key configured ⇒ no signing, nothing advertised. Stacked on #67. Operator enablement in docs/runbooks/response-signing.md.

How

• services/signing.py — ResponseSigner (ed25519), verify_signature, load_signer (returns None when unconfigured), and the published key document.
• middleware/signing.py — pure-ASGI middleware that buffers a paid 2xx application/json body and adds Hyrule-Signature: ed25519=<b64> + Hyrule-Signature-Key: <kid>, exposed via Access-Control-Expose-Headers. 402/501, free (non-catalog) endpoints, and non-JSON/streaming (icons, snapshots) pass through untouched. A signing failure returns the body unsigned rather than 500ing.
• app.py — loads the signer in lifespan (dark unless keyed), registers the middleware outermost, serves /.well-known/hyrule-signing-key.json (404 when unconfigured), adds the /llms.txt verification note.
• discovery.py — build_x402_manifest advertises a signingKey block only when configured.
• config / state — response_signing_key / response_signing_key_id, AppState.response_signer.
• canary — --verify-signature asserts every paid 2xx carries a valid signature against the published key.

Signed vs not

Response	Signed?
Paid catalog op, 2xx, application/json	✅ Hyrule-Signature + key id
402 / 501 (unpaid / gated)	❌
Free endpoint (/health, pricing, capabilities)	❌
Non-JSON / streaming (icon, bgp snapshot)	❌ (passthrough)

Tests

tests/test_signing.py: signer roundtrip + tamper-detection, load-gating, key-document shape, middleware behaviour (paid-2xx signed & verifies against the published key; 402/501/non-JSON/free not signed; no-signer no-ops), and manifest + well-known advertisement.

416 passed, ruff check + mypy --strict clean.

Operator enablement (not in this PR)

Generate a 32-byte seed → Vault kv/hyrule-cloud response_signing_key + response_signing_key_id → restart api. Verify with x402_canary.py dns --verify-signature. Rotation = dual-publish. See the runbook.

🤖 Generated with Claude Code

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis 🔶 67 - Partially compliant Compliant requirements: (empty – this PR implements signing, not the prober sidecar) Non-compliant requirements: All requirements listed above (this PR is Phase 4b, stacked on Phase 4a: real /v1/path/* via hyrule-prober sidecar (deliver-then-settle) #67) Requires further human verification: (empty)

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

🏅 Score: 92

🧪 PR contains tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Silent signing failure The middleware buffers the entire response body and attempts ed25519 signing. If signing raises an exception it logs a warning but returns the body unsigned without altering the response status or adding signature headers. A misconfigured or corrupted key seed will silently disable signing with no visible failure. An operator who restarts after provisioning a key and does not run the canary (e.g., due to monitoring gap) may believe all paid responses are verifiable when they are not. The design is intentional (never break the response), but it introduces a trust-footgun: signing can drop silently in production without any alert. body = b"".join(chunks) headers: list[tuple[bytes, bytes]] = list(start_message.get("headers", [])) try: signature = signer.sign(body) headers.append((b"hyrule-signature", f"ed25519={signature}".encode())) headers.append((b"hyrule-signature-key", signer.key_id.encode())) _merge_expose_headers(headers) except Exception as exc: # never fail the response over signing log.warning("response_signing_failed", error=str(exc)) await send({**start_message, "headers": headers}) await send({"type": "http.response.body", "body": body, "more_body": False}) Silent signer load failure load_signer returns None on any exception (malformed key, decoding error). This means a bad key in the environment variable is silently ignored – the feature ships dark even when the operator intended it to be active. Coupled with the middleware's own silent failure above, a signing outage can go entirely unnoticed until a buyer reports missing headers. The only detection path is running the external canary (x402_canary.py --verify-signature), which is not part of the health check or Prometheus metrics. try: return ResponseSigner(key, key_id) except Exception as exc: log.warning("response_signer_load_failed", error=str(exc)) return None

[github-actions]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Fix base64 padding calculation The padding calculation "=" * (-len(text) % 4) is incorrect for already-padded strings; it can add extra padding characters, causing base64.b64decode to fail. Use base64.b64decode(text, validate=False) which handles missing padding automatically, or use a more robust padding approach. hyrule_cloud/services/signing.py [33-44] def _decode_seed(value: str) -> bytes: """Decode a 32-byte ed25519 seed from base64 (std or url, padded or not).""" text = value.strip() - padded = text + "=" * (-len(text) % 4) for decoder in (base64.b64decode, base64.urlsafe_b64decode): try: - raw = decoder(padded) + raw = decoder(text) except (binascii.Error, ValueError): continue if len(raw) == 32: return raw raise ValueError("response signing key must be a base64-encoded 32-byte ed25519 seed") Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies a potential issue with the padding calculation for already-padded strings, which could cause decoding failures. The improved_code removes the manual padding and relies on base64.b64decode's built-in handling, which is cleaner and more robust. This is a valid bug fix with moderate impact.	Medium

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 62e1c3aaa0

ℹ️ 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]

Publish the retiring signing key during rotation

After an operator rotates HYRULE_RESPONSE_SIGNING_KEY, this document always publishes only the new active key, despite the response header carrying a key ID and the runbook requiring dual publication. A buyer who retrieves a response signed before the rotation and then fetches the well-known document cannot locate that response's old key or verify it, so the promised durable verifiability breaks at every rotation. Add configuration/storage for retired public keys and include them in keys[] until their verification window expires.

Useful? React with 👍 / 👎.

[Svaag]

Folded into the canonical trust layer (#56) rather than shipping a parallel signing stack — per operator decision to keep one key namespace, one JWKS, and one runbook for everything the service signs.

Where it went (commit b46e429 on feat/agent-trust-layer):

• hyrule_cloud/trust/measurements.py — MeasurementSigner (ed25519 detached signature over the exact 2xx JSON body bytes), verify_measurement_signature, load_measurement_signer, and a fail-closed enforce_measurement_key_guard that mirrors the receipt boot guard.
• hyrule_cloud/middleware/signing.py — ResponseSigningMiddleware, reading the signer off trust state; passthrough when unconfigured (soft-fail).
• Key is now published in the same /.well-known/jwks.json as the receipt keys (OKP/Ed25519 entry via build_jwks), and advertised under the agent-registration signedMeasurements block — not the x402 manifest, so /.well-known/x402.json stays byte-identical with the flag off.
• Config flags renamed into the trust namespace: TRUST_MEASUREMENT_SIGNING_ENABLED / _KEY / _KEY_ID / _RETIRED_JWKS_JSON (all default off).
• Canary keeps the --verify-signature check; docs live in docs/runbooks/trust-keys.md (generation, enable, rotation) and docs/trust-layer.md.

9 dedicated tests carried over; full suite 397 pass, mypy strict + ruff clean. Closing in favor of #56.