feat(#122 PR C1): signed-handoff codec + nonce table foundation

[dfcoffin]

Summary

Adds the tamper-evident value object the GBA Authorization Server and a Data Custodian sandbox will exchange via URL parameter during the customer-facing OAuth2 flow (Step 3.5 of #122). Replaces a shared Spring Session as the cross-app state mechanism — see the architectural rationale below.

Mechanism only — AS and DC sides that use this land in subsequent PRs (C2a customer login, C2b Authorization Screen, C3 AS delegation, C4 back-channel + token augmentation).

Why signed-redirect-parameter, not shared Spring Session

The AS and DC are independently deployed Spring Boot applications. A shared JDBC/Redis Spring Session would force:

• Cross-app cookie-domain alignment (SameSite=None ⇒ HTTPS required even in dev)
• An ambiguous "whose authenticated principal lives in the shared session" answer
• New infrastructure (Redis) or a shared session schema (JDBC) to provision and reap
• A subtle security boundary between two apps that now share session state

The signed-handoff approach borrows the same idea OAuth2 itself uses for the state parameter: encode the cross-app state in the URL, sign it with HMAC, let each side keep its own session. Replay is prevented by a single-use nonce table on the receiver. Every major OAuth2 provider (Google, GitHub, Microsoft, Auth0, Keycloak, Okta, Spring Authorization Server samples) renders their consent flow server-side with redirect-mediated state, not via shared session — same reasoning.

Wire format

Two dot-separated base64URL segments:

{base64URL(JSON(payload))} . {base64URL(HMAC-SHA256(key, payload))}

Payload (snake_case JSON via Jackson 3.x):

• v — wire-format version (currently 1)
• dir — "outbound" (AS→DC) or "return" (DC→AS)
• cid — opaque correlation id (echoed in both directions, traced in logs)
• iat / exp — issued-at and expires-at instants (5-minute default lifetime)
• nonce — base64URL 128-bit, receiver tracks single-use
• Direction-specific fields: client_id / scope / return_url (outbound) vs. sub / up / cust_uri / consent (return)

Direction tag prevents one direction's token from being replayed as the other. Single-use nonce prevents replay within a direction.

What ships in this PR

openespi-common.handoff package

• SignedHandoff — sealed interface + Outbound / Return records with .of() factory methods that fill in version + direction.
• SignedHandoffCodec — HMAC-SHA256 encode + verify; rejects malformed, tampered (via MessageDigest.isEqual constant-time compare), wrong-direction, wrong-version, expired payloads. Constructor-injected signing key (≥32 chars enforced).
• InvalidHandoffException — uniform rejection signal. Callers must NOT reveal which sub-check failed to the user-agent.
• HandoffNonceEntity — implements Persistable<String> with isNew() == true so JpaRepository.save() routes to entityManager.persist() (INSERT-only), NOT merge() (UPSERT). A duplicate consume surfaces as a PK violation rather than silently UPDATEing the existing row — the bug we'd otherwise have if we relied on default Spring Data save() semantics with assigned-id entities.
• HandoffNonceService.consume — runs in Propagation.REQUIRES_NEW. A partially-completed grant must not allow the same nonce to be reused even if the surrounding business transaction rolls back.

Migration

• V4__Create_Handoff_Nonces.sql — vendor-neutral DDL (H2 / MySQL / PostgreSQL).

Scan-path wiring

• DataCustodianApplication and TestApplication @EntityScan + @EnableJpaRepositories now include the handoff package.
• application.yml documents espi.handoff.signing-key (default for dev; ESPI_HANDOFF_SIGNING_KEY env var in production).

Deferred to later PRs

• AS-side codec mirror — the AS module is deliberately independent of openespi-common; the same codec + entity will be duplicated on the AS side, but only when C3 actually wires the AS to use it. Shipping it now would be dead code with no caller.

Test plan

• SignedHandoffCodecTest — 12 unit tests: round-trip both directions, tampered-payload / tampered-signature / wrong-key rejection (all via constant-time compare), expiry, wrong-direction, wrong-version, malformed / empty token, short signing key.
• HandoffNonceServiceTest — 6 @DataJpaTest cases: first-consume success, replay rejection (PK violation), distinct-nonces independence, uniqueness over 10k generates, blank-nonce rejection, reaper sweep. Assertions are by id-lookup (not row count) because REQUIRES_NEW commits escape the @DataJpaTest rollback.
• DataCustodianApplicationH2Test (full SpringBootTest context): 3 / 3 pass — confirms Spring auto-wires the dual-constructor codec (public ctor is @Autowired; package-private one is for tests).
• openespi-datacustodian full suite: BUILD SUCCESS, 97 / 97 pass + 1 pre-existing @Disabled skip.
• CI: 3-DB integration tests (MySQL / PostgreSQL / H2 via TestContainers).
• CI: Security vulnerability scan + SonarCloud.

Refs

• Foundation for PR C2a (DC customer login), C2b (Authorization Screen), C3 (AS delegation + AS-side codec mirror), C4 (back-channel call + token-response augmentation).
• Builds on PR A (feat(common): ESPI FB-scope parser + Function Block catalog (#122 PR A) #136), PR B1 (refactor(common): subscription↔authorization N:1, authorization as aggregate root (#122 PR B1) #137), PR B2 (feat(#122 PR B2): AS↔DC subscription-provisioning back-channel #139).
• Lifecycle policy (consent withdrawal → token revocation) tracked in Consent withdrawal must trigger token revocation + subscription cleanup #138.

🤖 Generated with Claude Code