feat(auth): [T4] HAIP request signing — x509_hash Client Identifier over a signed JAR (#377 Phases A+B)

[EsTharian]

Refs #377 — PR 1 of 2. Deliberately does not close the issue: this is Phase A + Phase B
(request signing). Phase C (encrypted direct_post.jwt response) is a separate PR and nothing
here touches it.

What lands

Phase A — the verifier's signing identity is provisionable. #298 shipped ES256 into
@qauth-labs/core-crypto and nothing outside that library could use it, because no operator
could provision a P-256 key. Six new variables fix that, each following the
JWT_RS256_PRIVATE_KEY / _PATH precedent:

• OID4VP_VERIFIER_SIGNING_KEY / _PATH — ES256 (EC P-256) PKCS#8 PEM
• OID4VP_VERIFIER_CERTIFICATE_CHAIN / _PATH — leaf first, anchor excluded
• OID4VP_VERIFIER_TRUST_ANCHORS / _PATH — what the chain must terminate at

The two chain sources are a precedence (x5c is an ordered sequence, so interleaving two
independently authored chains produces one whose middle link does not issue the one after it);
the two anchor sources are a union (an anchor set is a set). That is the same asymmetry
resolveStatusListTrustAnchorPems already documents, applied per variable.

createVerifierSigningMaterial validates the chain at boot with the existing
resolveAnchoredSigningCertificate — no second DER walk — and additionally proves the key
belongs to the leaf. ProvisionedVerifierMaterial is threaded into createConfiguredProviders,
replacing the "deliberately not passed" comment, and deriveCryptoCapabilities' ES256 entry
becomes a real predicate over both halves (a key with no chain signs something no wallet can
attribute to anyone).

Phase B — signed requests. buildX509HashClientId computes base64url(SHA-256(DER(leaf)))
per OID4VP 1.0 §5.9.3. selectClientIdPrefix widens past the single unsigned prefix — the
comment at the old client_id line predicted the widening would break it, and the branch is
taken there. signOid4vpRequestObject produces an ES256 JAR whose x5c carries leaf +
intermediates with the anchor excluded, and GET /oid4vp/request/:handle serves it as
application/oauth-authz-req+jwt. Under a signed prefix encodeOid4vpRequestUri refuses to
emit the query-parameter form at all, so HAIP §5.1's mandate is unreachable-to-violate rather
than merely unpreferred. assertRequestSigningAllowed — fully implemented and previously
callerless — is routed into the signed path.

The mock wallet gains the other side, written against node:crypto and jose with no import
of the code under test: it parses the request_uri reference, refuses one that also carries
the unsigned parameters, walks the x5c chain to an anchor it holds out of band, and checks
client_id against the digest of the leaf before verifying the signature.

Also repoints the two stale #233/#234 pointers in configured-providers.ts at #377.

Acceptance criteria — verified

• A deployment that provisions an ES256 key and a non-self-signed chain reports ES256 in
  VerifierCryptoCapabilities.signingAlgs. Unit test on the pure deriveCryptoCapabilities
  (crypto-capabilities.test.ts), plus the two single-half cases that must NOT claim it.
• client_id carries the x509_hash prefix, delivered as a request_uri reference to a
  signed object whose x5c contains leaf + intermediates and not the anchor, validated by
  the mock wallet against an out-of-band anchor. helpers/wallet-login-request.test.ts
  drives the app's own builder end to end and hands the JAR to the mock wallet, with a
  control asserting a wallet holding a different anchor refuses it.
• The verifier's P-256 key never appears in GET /.well-known/jwks.json and cannot sign a
  QAuth access or ID token. verifier-key-isolation.integration.test.ts, on a deployment
  that HAS provisioned one — a suite that only inspected the default JWKS would pass for the
  wrong reason. Also asserts the JWT plugin refuses a P-256 PEM at admission, with an
  Ed25519 control.
• haip-1.0 still refuses to boot, and the assertion names a specific count rather than
  matching any /haip-1\.0/ message. See the caveat below on which count.
• oid4vp-1.0-base is unchanged. Asserted directly: the same builder call with and
  without provisioned material produces an equal request.

Two things to look at, both deliberate

1. The haip-1.0 refusal names responseEncryption, not keyStorageAssurance. The issue
asked for the refusal to land on the keyStorageAssurance count alone. It cannot, and the reason
is ordering rather than an omission: assertProfileWithinCryptoCapabilities runs before
assertKeyStorageAssuranceProvisioned in createConfiguredProviders, and it also owns the
responseEncryption: 'required' check — which is Phase C and untouched here. So after this PR
haip-1.0 refuses on the response-encryption count, and on key-storage assurance once Phase C
clears that.

Rather than assert something untrue, the suite asserts both halves:

• wallet-federation-haip.integration.test.ts boots a deployment with the chain provisioned
  and asserts the refusal names the response-encryption count and explicitly not the
  certificate count or the ES256 count — the two this work cleared. Provisioning the chain is
  what stops the test passing for the state that existed before.
• crypto-capabilities.test.ts hands the gate a descriptor whose responseEncryption is
  hypothetically true — the one member Phase C changes — and asserts the next refusal is
  keyStorageAssurance (feat: [T4] wire #308 key-storage assurance into #237's assurance policy (and gate subject resolution at boot) #379). The ordering is proven now rather than assumed.

2. request-object.ts signs with jose's SignJWT, not core-crypto's sign(). The key
still comes through core-crypto (importPrivateSigningKey), so the crypto-agility seam is
unbroken; only the claim shaping is local. sign() mandates iss, aud and exp because every
token QAuth issues has all three, but a request object's claim set is RFC 9101 §4's — the
authorization request parameters — and aud has no OID4VP-wide value, since a wallet is not an
OpenID Provider with an Issuer Identifier. Emitting a guessed audience produces requests a
conformant wallet rejects for audience mismatch, so aud is omitted by default and settable
by an ecosystem that mandates one. Happy to route it back through sign() with a required
audience if you'd rather.

Test-profile note

The signed path is exercised against a haip-1.0 posture with exactly two members relaxed —
responseModes: ['direct_post'] and responseEncryption: 'permitted' — because the builder still
refuses both, correctly, as Phase C. Every other mandate (clientIdPrefixes: ['x509_hash'],
requestSigning: 'required', signingAlgs: ['ES256']) is the shipped table's own, and a control
test asserts the literal haip-1.0 entry still fails on the response-mode count. When Phase C
lands, the table entry flows through this path unchanged.

Beyond the literal issue text

Three additions the work required, called out so they are reviewed rather than absorbed:

• OID4VP_VERIFIER_TRUST_ANCHORS / _PATH. resolveAnchoredSigningCertificate needs an
  anchor set, and "the chain is non-self-signed" is only meaningful against something. A chain
  configured with no anchor is a boot failure naming the variable, rather than an opaque
  no-path-to-anchor.
• OID4VP_REQUEST_OBJECT_RATE_LIMIT / _RATE_WINDOW. The new endpoint is unauthenticated;
  falling back to the global limit is the wrong shape. Its own budget rather than the response
  endpoint's, because the two are opposite halves of the exchange and a slow-wallet retry budget
  must not also be a state-guessing budget.
• apps/auth-server/src/testing/x509-der.ts. mock-status-list.ts already carried an in-app
  DER encoder, and the E2E needed a second one for the verifier's PKI. The encoder moved into one
  module both build on; the app/lib independence that makes these interoperability tests is
  untouched. Certificate defaults are byte-identical to the old encoder, so the status-list E2E
  exercises exactly what it did before.

Three defects found and fixed on this branch

An adversarial pass over the first two commits found three, all fixed in the fourth commit:

1. (high, a regression in a shipped path) deliverRequest chose the delivery form from
   capability.signingMaterial !== undefined, while signedness is decided independently by the
   builder from the profile's prefix. A deployment running oid4vp-1.0-base and provisioning a
   verifier identity — supported, since the boot validates that material whatever profile is
   selected — would emit an unsigned request, try to deliver it by request_uri, and be refused.
   Every wallet login on the base profile would break the moment an operator configured a
   chain. Fixed by exporting isSignedOid4vpRequest and asking it in both places. The
   regression test fails with the exact refusal a real deployment would hit if the branch is put
   back — verified by reintroducing it.
2. (medium) openssl ecparam -name prime256v1 -genkey emits SEC1 (BEGIN EC PRIVATE KEY).
   createPrivateKey parses it, so the boot check passed; jose's importPKCS8 — what the
   signing path uses — refuses it. The deployment would start and fail every presentation. Fixed
   by normalising to PKCS#8 at boot and running the leaf match on those exact bytes, so what boot
   proved is a property of the value the signing path imports.
3. (low, defensive) Key-to-leaf matching compared exported SPKI DER, which is sensitive to the
   EC point conversion form — a CA that encodes the leaf's point compressed (RFC 5480 §2.2 permits
   it) would have its legitimate key refused. Now compared as crv/x/y.

Verification

pnpm exec nx affected -t lint typecheck test build   # 5 projects, all green
pnpm exec vitest run --coverage                      # 218 files, 3961 passed, 8 skipped

Coverage is comfortably above the repo gate (70/55/65/70): 89.3% statements, 82.7% branches.
New modules: client-identifier.ts, request-object.ts, crypto-capabilities.ts,
verifier-identity.ts and routes/oid4vp/request-object.ts at 100% statements;
verifier-signing-material.ts 100% / 94% branches; authorization-request.ts 98% / 98%.

Docker was not available on the runner this was built on, so the container-backed suites did
not run — nx run auth-server:test-integration reports 9 passed | 30 skipped | 2 todo. The
9 that ran are this PR's own: the 8 key-isolation assertions and the haip-1.0 boot refusal,
none of which needs a container. The 30 skipped are the pre-existing #240 wallet-federation E2E
suites (testcontainers Postgres + Redis) — they are unverified here and need a CI run with a
Docker daemon. CI was left unset so requireDockerOrSkip() skipped rather than threw.

Still open on #377

wallet-federation-haip.integration.test.ts still contains two it.todos. Both are Phase C
(decrypting a direct_post.jwt response, and the full HAIP login); the third — signed
x509_hash requests with the anchor excluded from x5c — is gone, covered for real by
helpers/wallet-login-request.test.ts.

---

Generated by Claude Code

[EsTharian]

Closing: this was opened from a wrongly-named branch. Superseded by #394, which carries the identical four commits (same head, 8e90473) on feat/377-haip-request-signing.

Nothing was reviewed here, so no discussion is lost. GitHub does not allow a pull request's head branch to be repointed, hence the replacement rather than an edit.

---

Generated by Claude Code