feat(#122 PR C3): AS-side delegation to DC + /oauth2/authorize/continue

[dfcoffin]

Summary

Closes the loop on the customer-facing OAuth2 flow for #122. Wires the GBA Authorization Server into the DC-hosted Authorization Screen (PR C2b) via a signed-handoff round-trip: AS delegates login + consent to DC, then resumes /oauth2/authorize when the customer returns.

This is the AS-side counterpart to PRs C1/C2a/C2b. After this lands, the only remaining piece for full delegation is PR C4 (AS calls DC's back-channel #139 endpoint on grant-success + augments the token response).

What's in this PR

C3.1 — Module extraction (openespi-handoff)
Pivoted from the original "mirror the codec into AS" plan after reconsideration: a shared Maven module is cleaner DRY without violating the long-standing authserver-independent-of-common-domain invariant. The codec is pure infrastructure (HMAC + Jackson + JPA, no ESPI types). All handoff code moved from openespi-common.handoff → openespi-handoff.handoff; AS depends on it directly, common transitively.

C3.2 — Outbound delegation

• OutboundHandoffBuilder — composes AS→DC signed outbound, 5-min TTL, returnUrl from the issuer URI.
• AuthorizeDelegateController (GET /authorize/delegate) — receives Spring AS's loginPage/consentPage redirect, signs the handoff, 302s user-agent to DC's /oauth/authorize-screen.
• DelegationStateService — in-memory ConcurrentMap (sandbox-only; production would back with Redis/JDBC) keyed by correlation_id, storing the TP's redirect_uri and state for the return trip.
• AuthorizationServerConfig wires consentPage("/authorize/delegate") + a LoginUrlAuthenticationEntryPoint for text/html media types. Both endpoints permitAll'd in the default chain.

C3.3 — Return endpoint (/oauth2/authorize/continue)

• Allow path: verify signed return, consume nonce, authenticate customer in AS session (opaque DC-assigned principal, ROLE_CUSTOMER, saved via HttpSessionSecurityContextRepository), pre-populate OAuth2AuthorizationConsentService with the customer's approved_scope split on ;, 302 to /oauth2/authorize with original TP params — Spring AS mints the code transparently.
• Deny path: 302 to TP's redirect_uri with error=access_denied + echoed state per RFC 6749 §4.1.2.1. Blank approved_scope on an "allow" payload also falls through to deny semantics.
• Invalid handoff: @ExceptionHandler(InvalidHandoffException) returns uniform error/400 view (no info leak); internal log captures specific cause (malformed, expired, wrong direction, nonce replay, missing delegation state).

C3.4 — Config + Flyway + tests

• application.yml: espi.handoff.signing-key (HMAC, ≥32 chars, must match DC), espi.datacustodian.baseUrl (customer-browser-reachable).
• Per-vendor V7_0_0__create_handoff_nonces.sql for h2/mysql/postgresql (vendor-neutral TIMESTAMP DDL, identical to handoff module's canonical V4 — AS's Flyway is per-vendor only and doesn't scan classpath:db/migration).
• 22 new tests, all passing:
  • DelegationStateServiceTest (4) — save/consume/peek semantics + null tpState.
  • OutboundHandoffBuilderTest (4) — round-trip via real codec, TTL, issuedAt, cid overload.
  • AuthorizeDelegateControllerTest (3) — state-save under TP-state-as-correlation-id, redirect_uri fallback to RegisteredClient, missing-state generates fresh cid.
  • AuthorizeContinueControllerTest (11, nested) — Allow/Deny/Invalid handoff paths.

Design decisions pinned this PR

Question	Choice	Why
Codec location	Shared openespi-handoff module	DRY without coupling AS to common's domain (pure infra utility, no ESPI types)
Return endpoint shape	Custom GET /oauth2/authorize/continue	Spring AS doesn't expose a clean post-consent resume hook — handle it ourselves
Deny semantics	RFC 6749 §4.1.2.1 error=access_denied + echo state	Spec-compliant; TPs already handle this code path

Test plan

• mvn test on openespi-handoff (handoff module tests) — passes
• mvn test -Dtest='*Delegate*,*Continue*,*DelegationState*,*Outbound*' on AS — 22/22 pass
• CI green
• Manual: bring up AS + DC together, walk through a full auth-code flow with allow path
• Manual: deny path delivers correct error=access_denied to TP
• Manual: replay an already-consumed handoff → 400

Notes / Known limitations

• DelegationStateService is in-memory — fine for sandbox/single-instance deployments, not for horizontal scaling. Documented inline; would back with Redis or a JDBC table in production.
• Customer principal is opaque on the AS — the AS does not maintain a RetailCustomer table or UserDetailsService; it only needs the user authenticated for Spring AS's code mint. The DC-assigned id will appear in OAuth2Authorization.principalName and introspection responses.
• Pre-existing test failures unchanged: 30 failures + 86 errors in integration tests (AuthorizationServerApplicationTests, *TestcontainersIntegrationTest, etc.) all root-cause to H2: Unknown data type: "DATETIME" from V1_0_0__create_oauth2_schema.sql — predates C3, unrelated to this PR.

🤖 Generated with Claude Code