migration(rs256): phase 121 — SDK TokenVerifier accepts both RS256 + HS256

[kjgbot]

Phase 121 — SDK dual-verify (RS256 + HS256)

Updates @relayauth/sdk's TokenVerifier to accept both RS256 (new) and HS256 (legacy) during the cutover window. Without this, once phase 122 flips the signer to RS256, any verifier still on the old SDK fails closed.

Part of the api-keys + RS256 migration. See specs/api-keys-and-rs256-migration.md for the full design. This is phase 3a, depends on phase 120 (RS256 signing path), feeds phase 122 (production cutover).

What changed

• packages/sdk/typescript/src/verify.ts: HS256 added to resolveVerificationAlgorithm (mapped to { name: "HMAC", hash: "SHA-256" }) and gated on RELAYAUTH_VERIFIER_ACCEPT_HS256. importVerificationKey learns an HS256 branch that reads the symmetric key from the JWK's k field per RFC 7518 and imports as an HMAC verify-only key. The kty gate in matchesJwk remains the authoritative algorithm/key-type pairing check.
• packages/sdk/typescript/src/__tests__/verify-dual-alg.test.ts: 8 adversarial tests covering happy paths, alg confusion, alg=none, payload tampering, kid spoofing, and the sunset-flag behavior.

Peer review (ran via agent-relay, explicit verdicts)

Two independent reviewers evaluated this exact diff on 2026-04-22. Both approved.

crypto-reviewer:

All eight tests pass, typecheck is clean, and I walked every attack class through the code to confirm the reject path. The verifier is sound for dual-acceptance during the HS256 → RS256 migration. No changes required to merge; the four advisory items can be handled as follow-ups.

Advisory follow-ups (non-blocking, track separately):

1. Consider inverting RELAYAUTH_VERIFIER_ACCEPT_HS256 polarity so missing config rejects HS256 (fail-closed posture).
2. Stricter: require published JWKs to carry an explicit alg matching the request (currently JWKs without alg still pass when kty matches).
3. Defensive kty === "oct" re-check at HS256 key import (relies on upstream selectJwk filter today).
4. Add a regression test for JWK material confusion ({ kty: "RSA", alg: "HS256", k: "…" } — blocked today via kty gate, but a future refactor of matchesJwk could silently open it).

compat-reviewer:

No breaking changes, no consumer updates required. Drop-in compatible, zero code changes required in sage.

Two behavior changes documented (not breaking):

1. HS256 now accepted by default (prior: rejected). Security-hardened consumers can opt out via RELAYAUTH_VERIFIER_ACCEPT_HS256=false.
2. matchesJwk alg matching is stricter: a JWK missing alg no longer matches requests with a specific alg. No-op for well-formed providers; external JWKS providers that omit alg may see new invalid_token errors.

Verification

• node --test --import tsx packages/sdk/typescript/src/__tests__/verify-dual-alg.test.ts: 8/8 pass
• Full SDK suite: 138/138 pass
• npx turbo typecheck --filter=@relayauth/sdk: clean

Note on workflow origin

The agent-relay workflow for this phase ran through the review gates successfully but then failed in the synthesize step (a runner heuristic: the architect agent idled for 30s and was marked incomplete before emitting the expected completion token). The reviews themselves produced complete outputs with explicit verdicts, so I committed the reviewed diff by hand and pasted the verdicts above as evidence. The synthesize failure is a workflow-framework issue unrelated to this code and will be tracked separately.

Run order in the migration

118 → 119 → 120 → 121 → publish + propagate → 122 → 123

This PR is phase 121. 118/119/120 are already merged. After this merges, bump package versions, publish @relayauth/server and @relayauth/sdk, then bump ../cloud deps before phase 122.