feat(signing): brand.json → JWKS auto-resolver (follow-up to #631)

[bokelley]

Summary

Delivers the brand.json → JWKS auto-resolver piece of #631's follow-up list.

BrandJsonJwksResolver is a receiver-side ergonomic: point it at a sender's brand.json URL and it walks agents[], extracts the right jwks_uri, and delegates to HttpsJwksResolver. Plugs straight into verifyWebhookSignature.jwks (or verifyRequestSignature.jwks) so the verifier no longer needs a JWKS URL pre-configured per counterparty.

Companion createWebhookEmitter + createAdcpServer integration (the rest of #631's follow-up list) remain as future work.

Behavior

• Follows authoritative_location and house redirect variants up to maxRedirects hops (default 3); rejects loops and depth-exceeded chains explicitly.
• Honors the spec fallback: when jwks_uri is absent on the selected agent, defaults to /.well-known/jwks.json on the origin of the agent's url.
• Brand.json cache tracks ETag + Cache-Control: max-age, capped by maxAgeSeconds (default 1h). Unknown-kid cascades: inner JWKS refreshes first; if still unknown and the brand.json cooldown has elapsed, brand.json re-resolves to pick up a rotated jwks_uri.
• Ambiguous selectors (multiple agents of the same type, no agentId) throw with the candidate ids listed.
• All fetches go through the existing ssrfSafeFetch, so an attacker-supplied brand.json or JWKS URL can't reach the receiver's private network or IMDS.

Example

import {
  BrandJsonJwksResolver,
  verifyWebhookSignature,
  InMemoryReplayStore,
  InMemoryRevocationStore,
} from '@adcp/client/signing';

const jwks = new BrandJsonJwksResolver('https://publisher.example/.well-known/brand.json', {
  agentType: 'sales',
});

await verifyWebhookSignature(request, {
  jwks,
  replayStore: new InMemoryReplayStore(),
  revocationStore: new InMemoryRevocationStore(),
});

Test plan

• npm run typecheck — clean
• node --test test/brand-jwks-resolver.test.js — 10 / 10 pass. Covers:
  • flat brand agents[]
  • portfolio (house.agents[] + brands[].agents[], brand-over-house precedence)
  • authoritative_location redirect chain
  • jwks_uri fallback to /.well-known/jwks.json on agent origin
  • selector ambiguity (multi-agent, no agentId)
  • rotation across maxAgeSeconds (picks up new jwks_uri)
  • 304 Not Modified cache hit (preserves inner resolver)
  • end-to-end webhook verify using the resolver
• Full test suite — new feature introduces zero regressions. 31 pre-existing failures (storyboard / request-signing grader / canonicalization vectors) are unchanged from main.
• CI pass (pending)

🤖 Generated with Claude Code

[gitguardian]

️✅ There are no secrets present in this pull request anymore.

If these secrets were true positive and are still valid, we highly recommend you to revoke them.
While these secrets were previously flagged, we no longer have a reference to the
specific commits where they were detected. Once a secret has been leaked into a git
repository, you should consider it compromised, even if it was deleted immediately.
Find here more information about risks.

---

^{_{🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.}}

[bokelley]

Hardening round: expert review feedback addressed

Ran three parallel expert reviews (code, security, protocol). Shipped blocking fixes in 5f4b984:

Security — JWKS origin pivot (sec #4, proto §5)
When jwks_uri is absent on the selected agent, the spec says "default to /.well-known/jwks.json on the origin of url." Previously we honored that blindly, which let an attacker-controlled brand.json set agent.url: "https://victim-internal/" and force the verifier to treat that origin's JWKS as authoritative. Now rejects with jwks_origin_mismatch when the agent origin doesn't match the final brand.json origin. Publishers that genuinely host their agent off-origin from brand.json must declare an explicit jwks_uri.

Security — house string injection (sec #1)
The https://${house}/.well-known/brand.json interpolation previously trusted the string verbatim. Values like "evil.com\\@victim.com" or "x.y/#" would let an attacker pick the authority of the redirected URL. Now gated on a bare-hostname regex before interpolation.

Security — redirect target validation (sec #1, #3)
Every authoritative_location / house-rewritten URL passes through canonicalizeUrl: must be https:// (or http:// under allowPrivateIp), no userinfo, fragments stripped so loop detection can't be bypassed by appending #.

Ergonomics — typed error surface (code #4)
Replaces raw new Error(...) with BrandJsonResolverError carrying a stable code enum. Verifier callers can fold transient fetch failures into webhook_signature_key_unknown and treat config bugs (agent_ambiguous, agent_not_found, schema_invalid) distinctly without parsing error message strings.

Ergonomics — defensive shape check (proto §5 / code §6)
Terminal brand.json is walked to reject non-string url / jwks_uri entries. Full BrandJsonSchema.safeParse turned out to be over-strict for the resolver's narrow needs (it enforces ^https:// on URLs, which ssrfSafeFetch already polices and which breaks dev loops under allowPrivateIp).

New tests (18 total, all passing)

• Cross-origin jwks_uri fallback rejected
• Malformed house string rejected
• Malformed / userinfo-bearing authoritative_location rejected
• Private-IP JWKS refused when allowPrivateIp is false (default posture)
• redirect_depth_exceeded on long chains
• Non-string agent.url → schema_invalid
• Non-JSON body → invalid_body

Follow-ups acknowledged (out of scope for this PR)

• Full cross-origin redirect allowlist (protocol §5 recommends spec-level known_origins rather than per-caller). Filing upstream.
• prime() helper for eager-warmup (sec Fix agent configuration to use .env only approach #7, nice-to-have).
• createWebhookEmitter + createAdcpServer integration — the remaining items from PR feat(storyboard): outbound-webhook conformance runner (#2426) + 9421 webhook verifier #631's follow-up list.

[bokelley]

CI failure triage

Pushed two fixes and confirmed the rest are pre-existing on main.

Fixed in this PR

e374566 — fix(signing): decode RFC 3986 unreserved percent-encoded chars in @target-uri
Resolves conformance vector 009-percent-encoded-unreserved-decoded.json (both the byte-equal canonicalization assertion and the downstream verifier). Per RFC 3986 §6.2.2.2, percent-encoded unreserved chars (A-Z a-z 0-9 - . _ ~) MUST be decoded in @target-uri. Our canonicalizer was only uppercasing hex, so vector 009's path a%7Eb%2Dc%5Fd%2Ee produced a%7Eb%2Dc%5Fd%2Ee instead of the expected a~b-c_d.e — signature base mismatch → request_signature_invalid at step 10.

Pre-existing on main (29 failures)

Verified by fresh main checkout + npm run sync-schemas + npm test — same 31 failures on main, 29 remaining on this branch after the canonicalization fix (the vector-009 pair is the only net-new green). Main's latest CI/CD Pipeline run is also red on the same tests.

Clusters:

• Storyboard structural completeness + response schema coverage (4 subtests under storyboard: signed_requests / synthesis_error) — storyboard declares a synthesis_error task that has no TOOL_RESPONSE_SCHEMAS entry.
• Request-signing grader end-to-end + MCP + vectors-loader + synthesize + runner dispatch — grader pipeline tests that load the same signed_requests storyboard and hit the same unregistered-task path.
• RFC 9421 verifier negative vectors — new negative vectors from a recent tarball (021-duplicate-signature-input-label, 022-multi-valued-content-type, 023-multi-valued-content-digest, 025-jwk-alg-crv-mismatch, 026-non-ascii-host) that the verifier doesn't handle yet.

Branch protection on main has no required status checks, so these don't block merge, but they should be fixed in a follow-up PR (not this one — out of scope for brand.json → JWKS).

GitGuardian should be green now (squashed history removes the user:pass@host pattern from earlier commits; current tree builds the URL from parts).