Phase 2.0 — Stand up auth-server in dev with opaque tokens + subscription-bound introspection (Phase 2 precursor)

[dfcoffin]

Precursor to #119 Phase 2.
Phase 2 (subscription scoping / data-leakage fix) cannot ship until the
authorization server is running, issues opaque tokens per ESPI 4.0, and exposes
a subscription_id-bearing introspection response. Until then every Phase 2a
design choice is unverifiable against a hypothetical token shape.

See the design analysis posted as a comment on #119:
#119 (comment)

Why this is blocking

ESPI 4.0 requires opaque (reference) access tokens — JWTs are not permitted by
the spec. A resource server cannot read claims from an opaque token; it must
call RFC 7662 token introspection to learn what the token grants. Phase 2's
entire OpaqueTokenIntrospector / ApiAccessValidator design is built around
that introspection response. Without a running auth-server returning the
expected response shape (including subscription_id), no Phase 2 code can be
end-to-end tested.

Shipping a security fix that can't be proven to work against a real token is
the worst outcome for an IDOR / data-leakage fix.

Acceptance criteria

Phase 2.0 is complete when one integration test boots both modules, mints a
real token via the authorization code flow, calls a data-custodian endpoint,
and asserts the principal carries subscription_id. Until that test passes,
no Phase 2a code will be merged.

Checklist

Step 1 — Configuration audit (read-only)

• Find RegisteredClient / OAuth2AuthorizationServerConfiguration; confirm tokenSettings() format (REFERENCE vs SELF_CONTAINED)
• Confirm /oauth2/introspect is enabled and properly authenticated (client credentials, not bearer)
• Find any OpaqueTokenIntrospector / OAuth2TokenCustomizer beans
• Inspect OAuth2Authorization persistence; locate where subscription binding could be stored at grant time
• Verify oauth2_authorization table exists; check for custom columns or join tables linking authorizations to subscriptions
• Post audit findings as an issue comment (what is configured vs what Phase 2 needs)

Step 2 — Local dev environment

• Bring up MySQL (dev-mysql profile)
• Boot openespi-authserver with dev-mysql; resolve any Flyway migration drift
• Verify /oauth2/.well-known/oauth-authorization-server returns a valid metadata document
• Register at least one RegisteredClient (third-party app) and one retail customer via seed data

Step 3 — Verify token format

• Run authorization code flow end-to-end (manual curl / Postman)
• Inspect the issued access token: opaque (short, random) vs JWT (eyJ...)
• If JWT, switch RegisteredClient to OAuth2TokenFormat.REFERENCE and re-test

Step 4 — Add subscription_id to introspection response (the wildcard)

• Try Approach B first: customize auth-server OAuth2TokenIntrospectionAuthenticationProvider / converter to add subscription_id to the introspection claims
• If Spring Authorization Server doesn't expose a clean hook, fall back to Approach A: custom resource-server OpaqueTokenIntrospector that enriches principal via DB lookup
• Document which approach was used and why

Step 5 — Wire data-custodian as resource server

• Add spring.security.oauth2.resourceserver.opaquetoken.* config pointing at auth-server introspection URL
• Register resource-server as a RegisteredClient with client_credentials grant + introspection authority
• Disable any existing JWT resource-server config (mutually exclusive on the same filter chain)

Step 6 — End-to-end smoke test

• Write one integration test that boots both modules, mints a real token via authorization code flow, calls a data-custodian endpoint, asserts the principal carries subscription_id
• Test passes → Phase 2.0 complete → Phase 2a unblocked

Non-goals (deferred)

• Scope-grammar alignment — Phase 7. Phase 2 keeps the existing
  SCOPE_FB_* shorthand and pins parsing behind a single helper for later
  swap.
• JSON output — Phase 3. Cosmetic produces = JSON declarations stay as-is.
• Phase 2a/2b/2c code — does not start until step 6 passes.

Estimate

1–2 working days for a senior Spring developer who knows Spring Authorization
Server. Step 4 is the wildcard (Spring Authorization Server's
OAuth2TokenIntrospectionAuthenticationProvider extensibility is the unknown).

🤖 Generated with Claude Code

[dfcoffin]

Step 1 — Configuration audit findings

Read-only audit complete. The picture is much better than expected for some
items, and exposes a couple of issues that change Phase 2's design.

Confirmed (work already done)

• Token format = opaque (OAuth2TokenFormat.REFERENCE).
  AuthorizationServerConfig.java:254-300 — all three default clients
  (data_custodian_admin, third_party, third_party_admin) set
  accessTokenFormat(OAuth2TokenFormat.REFERENCE). Default profile
  (application.yml:96) also sets espi.token.format: opaque. No JWT
  configuration anywhere on the access-token path.
• Introspection endpoint enabled.
  AuthorizationServerConfig.java:378 — AuthorizationServerSettings declares
  .tokenIntrospectionEndpoint("/oauth2/introspect").
• Data-custodian is already wired as an opaque-token resource server.
  openespi-datacustodian/.../config/SecurityConfiguration.java:188-228 builds
  the SecurityFilterChain with .opaqueToken(opaque -> opaque.introspectionUri(...).introspectionClientCredentials(...))
  and exposes an OpaqueTokenIntrospector bean using
  SpringOpaqueTokenIntrospector.withIntrospectionUri(...).
  application.yml:86-94 provides the matching config keys.
• Authorization persistence = JdbcOAuth2AuthorizationService.
  AuthorizationServerConfig.java:328-330. Writes to oauth2_authorization
  (schema in V1_0_0__create_oauth2_schema.sql).
• Auth-server scopes already use the spec-compliant ESPI 4.0 grammar.
  AuthorizationServerConfig.java:276-277 registers
  "FB=4_5_15;IntervalDuration=3600;BlockDuration=monthly;HistoryLength=13" and
  the 900-second variant as RegisteredClient scopes.

Critical finding: scope-grammar mismatch is real and immediate

Auth-server issues spec-compliant scopes like
FB=4_5_15;IntervalDuration=3600;BlockDuration=monthly;HistoryLength=13.

Data-custodian's @PreAuthorize lines (in every controller) expect
SCOPE_FB_15_READ_3rd_party, SCOPE_FB_16_READ_3rd_party, etc.

These do not match. Spring Security prefixes each scope value with SCOPE_
when converting to GrantedAuthority. The actual authority on the
authentication will be something like
SCOPE_FB=4_5_15;IntervalDuration=3600;BlockDuration=monthly;HistoryLength=13,
which will never satisfy the hasAuthority('SCOPE_FB_15_READ_3rd_party')
predicate. Every legitimate non-admin request will return 403 today once
introspection actually runs end-to-end.

This was tagged as a "Phase 7" concern in the design analysis, but the audit
shows it is a Phase 2 blocker, not a parallel track. The introspection
layer can be perfect and still 100% of authenticated calls will 403 until the
scope grammar is aligned on both sides.

Critical finding: schema binding is customer_id + usage_point_ids, NOT subscription_id

V4_0_0__add_datacustodian_integration.sql added an integration model that
binds OAuth2 authorizations to data-custodian context:

• oauth2_authorization.datacustodian_customer_id — retail customer
• oauth2_authorization.datacustodian_grant_id — grant ID
• datacustodian_integration_mapping table — links authorization_id →
  customer_id + usage_point_ids (JSON array of UUIDs)

There is no subscription_id column anywhere in the auth-server schema.
The ESPI Atom-feed concept of a "Subscription" — the /Subscription/{id}/...
path prefix — is data-custodian-local and maps to (customer + usage-point set),
not to a separate identity in the auth-server.

Phase 2 design implication: the principal carries
(customerId, usagePointIds[], scopes, isAdmin), not subscriptionId. The
enforcePathMatch step rewrites: pathSubscriptionId must resolve (via
data-custodian's own SubscriptionEntity or grant lookup) to a (customerId, usagePointIds) tuple that matches the token's binding. The original Phase 2
design document is correct in concept but wrong in identifier — needs revision
to the customer+usage-points model.

Critical finding: introspection response is NOT customized

The default /oauth2/introspect response from Spring Authorization Server
carries active, sub, scope, client_id, exp, iat, token_type,
username, nbf, jti (RFC 7662). It does not carry
datacustodian_customer_id or any ESPI-specific binding.

No OAuth2TokenIntrospectionAuthenticationProvider customization exists. No
custom IntrospectionResponse extension exists. The
EspiTokenCustomizer.java bean (line 54+) is OAuth2TokenCustomizer<JwtEncodingContext>
— JWT-only, and it short-circuits unless espi.token.format=jwt. It is
inert for the opaque-token path and cannot be reused for introspection-response
enrichment.

Approach decision: Step 4 of this issue's checklist must choose between:

• Approach A (resource-server enrichment) — data-custodian's
  OpaqueTokenIntrospector wraps the default, reads principal_name from the
  introspection response, then queries oauth2_authorization (cross-schema or
  via auth-server API) to look up datacustodian_customer_id and the mapped
  usage_point_ids. Couples data-custodian to auth-server's database/API.
• Approach B (auth-server response enrichment) — auth-server registers a
  custom OAuth2TokenIntrospectionAuthenticationProvider (or a bean that wraps
  it) that pulls datacustodian_customer_id from the stored
  OAuth2Authorization attributes and adds it to the introspection response.
  RFC 7662 permits custom claims (§3.1 last paragraph). Resource server gets
  everything from one HTTP call.

Recommendation: Approach B. Spring Authorization Server 1.3+ exposes the
introspection extensibility via a security configurer (OAuth2TokenIntrospectionEndpointConfigurer
or by replacing the default provider in the filter chain). Approach A's
cross-database coupling is a maintenance hazard and breaks if the two modules
ever move to separate deployments — which is the entire point of having two
modules.

Other observations

• JWK source still generated. AuthorizationServerConfig.java:344-355
  generates an in-memory RSA key pair, even though no JWT path is active. This
  is harmless but should be removed in cleanup (id_token signing for OIDC
  still requires it; leave for now).
• Default security filter chain at order(2) is commented out.
  AuthorizationServerConfig.java:184-229 — entire defaultSecurityFilterChain
  bean is // @Bean // @Order(2) and the body is commented inline. The
  authorization-server filter chain at order(1) handles everything. Not a
  bug, but suggests the file needs a cleanup pass.
• JdbcOAuth2AuthorizationService writes the full OAuth2Authorization —
  including attributes (blob) and access_token_metadata (blob) — but
  custom claims placed in those attributes are NOT surfaced through the
  default introspection response. Approach B has to read them back and add
  them explicitly.

Revised Phase 2.0 effort estimate

Step	Status	Notes
1 — Config audit	DONE (this comment)	–
2 — Local dev boot	~1–2 hr	Standard; expect Flyway drift
3 — Verify opaque tokens	~30 min	Should already pass given §1 findings
4 — Introspection enrichment	~4–6 hr (up from 2–4)	Approach B requires customizing OAuth2TokenIntrospectionAuthenticationProvider; needs to surface datacustodian_customer_id + usage_point_ids
5 — Wire data-custodian	MOSTLY DONE	Already configured; only need to swap OpaqueTokenIntrospector bean for one that recognizes the enriched response shape and builds an ESPI principal
6 — End-to-end smoke test	~2–3 hr	Now must also exercise the scope-grammar alignment
NEW Step 4.5 — Scope-grammar alignment	~3–4 hr	Replace SCOPE_FB_15_* shorthand in every controller's @PreAuthorize with a parser-based check against the ESPI 4.0 FB-string grammar. Blocker for Phase 2a; cannot proceed without it.

Revised total: 2–3 working days (vs. 1–2 in the original estimate). The
scope-grammar alignment is the surprise.

Recommended next steps

1. Update issue Phase 2.0 — Stand up auth-server in dev with opaque tokens + subscription-bound introspection (Phase 2 precursor) #122 description with the scope-grammar finding as a new
   acceptance criterion (alignment must work end-to-end in the smoke test).
2. Decide between Approach A and Approach B before any code is written.
3. Boot the auth-server locally (Step 2) and exercise the introspection
   endpoint against one of the seeded clients to confirm the actual
   default response shape — the audit infers it from defaults, not from a live
   run.

[dfcoffin]

Correction — amendment to #issuecomment-4520974698

Two findings from the Step 1 audit were wrong. Posting this as a standalone correction so the audit trail is preserved.

What I got wrong

Claim (in prior comment): "There is no subscription_id column anywhere in the auth-server schema… Phase 2 design implication: the principal carries (customerId, usagePointIds[], scopes, isAdmin), not subscriptionId."

Reality: I was looking in the wrong place. SubscriptionEntity already exists as the canonical model — owned by data-custodian (via openespi-common), not by auth-server:

• openespi-common/src/main/java/org/greenbuttonalliance/espi/common/domain/usage/SubscriptionEntity.java:53-119
  • @Id UUID id — the /Subscription/{id}/... handle exposed on the wire
  • @ManyToOne RetailCustomerEntity retailCustomer — who owns the data
  • @OneToOne AuthorizationEntity authorization — the OAuth2 authorization (1:1)
  • @ManyToOne ApplicationInformationEntity applicationInformation — which third party
  • @ManyToMany List<UsagePointEntity> usagePoints via subscription_usage_points join table — authorized FB resources
  • Helpers: isActive(), isExpired(), isRevoked(), includesUsagePoint(...), belongsToCustomer(...)

The auth-server schema's lack of a subscription_id column is not a gap — auth-server doesn't own subscriptions. SubscriptionEntity is created in data-custodian at OAuth grant time and represents the access token + customer + authorized data resources. A customer can have multiple third-party relationships, and a single third party may hold multiple scope strings against the same customer (e.g., electric, gas, both) — each is a distinct SubscriptionEntity.

Revised principal model

Before	After
EspiPrincipal(customerId, usagePointIds[], scopes, isAdmin)	EspiPrincipal(subscriptionId, isAdmin)

Everything else is derived locally in data-custodian via SubscriptionRepository.findById(subscriptionId) → (retailCustomer, usagePoints, applicationInformation, authorization). No need to carry customer/usage-point arrays across the introspection wire.

Enforcement patterns collapse to two checks:

1. Path-bound endpoints (/Subscription/{subId}/UsagePoint/...): assert pathSubId.equals(principal.subscriptionId) — single string compare.
2. Root collection / by-id endpoints: filter/lookup must be scoped to subscriptionRepository.findById(principal.subscriptionId).getUsagePoints() — return 404 (not 403) for anything outside that set, to avoid existence-leak.

Revised introspection enrichment (simpler)

Approach B (auth-server-side customization) still wins, but the custom claim shrinks:

{
  "active": true,
  "sub": "...",
  "scope": "FB=4_5_15;IntervalDuration=3600;...",
  "client_id": "third_party",
  "exp": 1234567890,
  "subscription_id": "urn:uuid:xxxxxxxx-xxxx-5xxx-xxxx-xxxxxxxxxxxx"   <-- single custom claim
}

One UUID. Data-custodian's OpaqueTokenIntrospector wrapper reads subscription_id and builds the principal; everything else is a local DB lookup. No customer-id or usage-point arrays on the wire.

Auth-server work for Step 4 becomes:

• At grant time (consent acceptance), look up or create the SubscriptionEntity (via the data-custodian integration mapping in V4_0_0__add_datacustodian_integration.sql) and stash its UUID into the OAuth2Authorization attributes blob.
• Customize OAuth2TokenIntrospectionAuthenticationProvider to read that attribute back and add it to the introspection response as subscription_id.

Scope correction — Phase 2c is OUT OF SCOPE

Utilities do not allow third parties to POST, PUT, or DELETE metering or customer personal information data. Only GET request controllers need ESPI access enforcement in Phase 2.

Impact on the prior audit's API table:

• Rows M1–M9 (mutation endpoints) → drop, no enforcement work in this phase
• All @PostMapping / @PutMapping / @DeleteMapping on metering and customer-data controllers remain admin-only or are removed from the third-party path entirely (decision deferred to a follow-up issue if/when a write use case appears)

Net effect on Step 4 effort

Slightly down from the revised 4–6 hr estimate — the introspection customization now surfaces one claim instead of three, and the resource-server side does one repository lookup instead of parsing JSON arrays. Call it 3–5 hr for Step 4. Scope-grammar alignment (Step 4.5, 3–4 hr) is unchanged. Phase 2c drop saves the ~6–8 hr that mutation-ownership-check work would have cost.

Grant-flow wiring audit to follow as a separate comment.

[dfcoffin]

Step 1.5 — Grant→Subscription wiring audit

Follow-up to the Step 1 audit and its correction. Question: does the OAuth2 grant flow actually create a SubscriptionEntity end-to-end today?

Verdict: MISSING

Scaffolding is present (integration service, mapping table, stored proc) but no code path triggers it on grant completion. SubscriptionService.createSubscription(...) has zero production callers in either module. The (retailCustomer, authorization, applicationInformation, usagePoints[]) shape would never be populated by today's flow even if a subscription were created.

Evidence

1. SubscriptionService.createSubscription has no callers

• Interface: openespi-common/.../service/SubscriptionService.java:31
• Impl: openespi-common/.../service/impl/SubscriptionServiceImpl.java:65-104
• grep -r "\.createSubscription(" . → zero matches in production code (both modules).

Module visibility blocks the auth-server from invoking it directly anyway: openespi-authserver/pom.xml:77 — "No OpenESPI-Common dependency - Authorization Server is independent". Subscription creation must happen on the data-custodian side, via a remote call from auth-server.

2. DataCustodianIntegrationService has no inbound caller on the grant path

openespi-authserver/.../service/DataCustodianIntegrationService.java provides the HTTP plumbing:

• createAuthorizationGrant(customerId, clientId, scope, usagePointIds) — lines 257-298, POSTs to {dataCustodian}/api/v1/auth/grants
• storeIntegrationMapping(authorizationId, grantId, ...) — lines 364-384, persists to datacustodian_integration_mapping

Who invokes it: only DataCustodianIntegrationController.java:198 — an admin/manual REST endpoint at /api/v1/datacustodian/grants. No event listener, no OAuth2TokenCustomizer, no consent-accept hook calls it.

ConsentController.processConsent() (lines 155-241) ends at line 232 with a redirect back to /oauth2/authorize. No integration-service call before the redirect.

3. SyncAuthorizationWithDataCustodian stored procedure is dead schema

openespi-authserver/.../db/vendor/{mysql,postgresql}/V4_0_0__add_datacustodian_integration.sql defines the proc. grep -r "SyncAuthorizationWithDataCustodian\|sync_authorization_with_datacustodian" . → zero Java references. The migration runs but the proc is never called.

4. Cross-module pattern: HTTP-callback scaffolding without the trigger

The intended pattern is clearly option (a) HTTP callback auth-server → data-custodian — that's what DataCustodianIntegrationService.createAuthorizationGrant() is built for. What's missing is the moment-of-grant-completion hook that calls it:

• AuthorizationServerConfig.java:328-330 — uses stock JdbcOAuth2AuthorizationService, no customization
• EspiTokenCustomizer.customize() — JWT-only path (lines 65-90), short-circuits for opaque; even if it ran, it doesn't call the integration service
• No ApplicationListener<OAuth2AuthorizationSuccessEvent> or equivalent anywhere

5. AuthorizationEntity link is undefined at runtime

SubscriptionEntity.java:96-98:

@OneToOne(cascade = CascadeType.REMOVE, fetch = FetchType.LAZY)
@JoinColumn(name = "authorization_id")
private AuthorizationEntity authorization;

AuthorizationEntity is data-custodian-local (openespi-common/.../domain/usage/AuthorizationEntity.java). It is not synced from the auth-server's oauth2_authorization table by any code I can find. If a SubscriptionEntity were created today, its authorization field would be null.

What's missing for Phase 2.0

Five gaps, in order of dependency:

1. Grant-completion hook on auth-server — ApplicationListener for the OAuth2 authorization success event (or a custom step in the token-granting filter), invoking DataCustodianIntegrationService.createAuthorizationGrant(...) with the consented customer + usage-point set.
2. Subscription-create endpoint on data-custodian — receives the auth-server callback, creates SubscriptionEntity with (retailCustomer, authorization, applicationInformation, usagePoints[]) populated, returns the new subscription_id (UUID5).
3. AuthorizationEntity materialization — data-custodian must own a row representing the OAuth2 authorization (mirror of auth-server's oauth2_authorization.id), so SubscriptionEntity.authorization is non-null. Created in the same handler as Bump org.postgresql:postgresql from 42.7.4 to 42.7.7 in /openespi-datacustodian/OpenESPI-GreenButton-Workspace/OpenESPI-DataCustodian-java #2.
4. Subscription-id round-trip into the OAuth2Authorization attributes — auth-server stashes the returned subscription_id into the OAuth2Authorization.attributes blob (and oauth2_authorization.datacustodian_grant_id), so the Step 4 introspection customizer can surface it as the subscription_id claim.
5. Activate the stored proc (optional) — SyncAuthorizationWithDataCustodian becomes the fallback for async retry if the synchronous callback in Bump commons-io:commons-io from 2.4 to 2.14.0 in /openespi-datacustodian #1 fails.

Effort impact on Phase 2.0

The earlier estimate assumed Step 4 was just "customize the introspection response." That step now requires the grant-completion plumbing first — gaps #1-#3 are prerequisites, because there's no subscription_id to surface until subscriptions are actually being created.

Revised:

Step	Prior estimate	New estimate	Notes
1 — Config audit	DONE	DONE	–
1.5 — Grant-flow audit	–	DONE (this comment)	–
2 — Local dev boot	1–2 hr	1–2 hr	unchanged
3 — Verify opaque tokens	30 min	30 min	unchanged
3.5 — Grant-completion hook (NEW)	–	4–6 hr	Listener + integration-service call + error handling
3.6 — Subscription-create endpoint (NEW)	–	4–6 hr	Data-custodian REST endpoint + SubscriptionService.createSubscription(...) wired + AuthorizationEntity materialization
4 — Introspection enrichment	3–5 hr	2–3 hr	One claim (subscription_id); simpler now that creation is solved upstream
4.5 — Scope-grammar alignment	3–4 hr	3–4 hr	unchanged
5 — Wire data-custodian	mostly done	mostly done	unchanged
6 — End-to-end smoke test	2–3 hr	3–4 hr	Now covers full grant→subscription→introspection→GET cycle

Revised total: ~3–4 working days (vs. the prior 2–3 day estimate). The grant-completion plumbing is the surprise — without it, the entire Phase 2 enforcement model has nothing to enforce against.

Recommended sequencing for Phase 2.0 implementation

1. Step 2 (boot) and Step 3 (verify opaque) first — cheap, confirms the audit's static findings against runtime reality.
2. Step 3.5 + 3.6 together — they're two halves of one round-trip and can't be tested independently.
3. Step 4 once a real subscription_id exists to surface.
4. Step 4.5 in parallel with Step 4 — independent work, different files.
5. Step 6 last — exercises everything.

[dfcoffin]

Phase 2.0 Step 2 + 3 — Boot reality check vs. static audit (MAJOR update)

Follow-up to the Step 1 audit, correction, and grant-flow audit. Branch: feature/issue-122-auth-server-bringup.

Executive finding

The auth-server has not been booted clean against MySQL in living memory. Static audit findings were optimistic; runtime exposed seven independent pre-existing defects that must be repaired before opaque-token introspection can be verified end-to-end. Eighth defect identified but not yet patched.

The 3-4 day Phase 2.0 estimate from prior comments is invalid. Revised below.

Defects discovered during Step 2/3 boot attempts

#	Defect	File	Severity	Patched on branch
1	oauth2_registered_client.client_id missing UNIQUE constraint → FK from espi_application_info.client_id fails on MySQL CREATE TABLE	db/vendor/mysql/V1_0_0__create_oauth2_schema.sql:67	Blocker	✅ Added UNIQUE KEY uk_oauth2_registered_client_client_id (client_id)
2	Flyway YAML configs point at classpath:db/migration/{mysql,postgresql,h2} but source files live at db/vendor/. Boot only "worked" historically because of stale target/classes/db/migration/ artifacts; mvn clean exposes the gap.	4 profile YAMLs + base application.yml + docker-compose.yml	Blocker	✅ All 6 config files now reference classpath:db/vendor/...
3	V3+ migrations reference columns that don't exist in MySQL V1 schema (client_description, contact_name, contact_email, scope, grant_types, response_types) — ESPI 4.0 XSD-aligned schema repair needed. Tracked separately as #123.	V3_0_0__add_default_data_and_test_clients.sql	Blocker for V3+	✅ Workaround: spring.flyway.target: "2.0.0" in application-dev-mysql.yml. Full fix in #123.
4	authorizationServerSecurityFilterChain declares both OIDC (which auto-wires JWT validation) and .opaqueToken(Customizer.withDefaults()) on the same filter chain → Spring Security 7.x fails fast: "Spring Security only supports JWTs or Opaque Tokens, not both at the same time."	AuthorizationServerConfig.java:140-144	Blocker	✅ Removed .opaqueToken(...); chain now uses .jwt(Customizer.withDefaults()). Outbound opaque tokens to ESPI clients unaffected (controlled per-RegisteredClient via accessTokenFormat(REFERENCE)).
5	Two SecurityFilterChain @Order(0) beans (httpsEnforcementFilterChain, developmentSecurityFilterChain) with securityMatcher("/**") preempt the auth-server's @Order(1) chain, causing every OAuth2 endpoint to return 404. Header injection should not monopolize /** via a SecurityFilterChain.	HttpsEnforcementConfig.java:101-176	Blocker	✅ @Bean annotation commented out on both. Headers should be re-introduced via HeaderWriter or Filter in a follow-up.
6	HikariCP auto-commit: false paired with JdbcRegisteredClientRepository.save() (no @Transactional) → seed INSERT statements never commit and silently roll back on connection return. Boot log says "Inserted registered client: 1" three times; DB has 0 rows.	application-dev-mysql.yml:17 + JdbcRegisteredClientRepository.java:105	Blocker	✅ Set auto-commit: true for dev profile. Architectural fix (proper @Transactional throughout repository) deferred.
7	authorizationServerSecurityFilterChain uses .oauth2AuthorizationServer(...) + .oauth2ResourceServer().jwt(...) + .anyRequest().authenticated() in one chain. Result: resource server bearer filter intercepts POST /oauth2/token before the token-endpoint filter can handle basic auth → 401 WWW-Authenticate: Bearer. Canonical pattern is OAuth2AuthorizationServerConfiguration.applyDefaultSecurity(http) with a SECOND @Order(2) chain for non-OAuth2 endpoints.	AuthorizationServerConfig.java:119-173	Blocker	❌ Not yet patched. Filed as separate issue.
8	JdbcRegisteredClientRepository.findAll() returns empty list even when rows are persisted. Boot log: "Default ESPI Clients: 0" while DB SELECT returns 3 rows. Bug in the custom repository's findAll implementation; not yet diagnosed.	JdbcRegisteredClientRepository.java (line TBD)	Suspected blocker for admin endpoints	❌ Not yet investigated.

What "works" today on the branch

Boot reaches Started AuthorizationServerApplication in ~35-42 seconds. Tomcat listens on 9999.

• GET /.well-known/oauth-authorization-server → 200, advertises correct token + introspection URLs
• GET /.well-known/openid-configuration → 200
• GET /oauth2/jwks → 200
• GET /login → 200

What does NOT work today

• POST /oauth2/token with client_credentials → 401 (defect feat: upgrade to ESPI 4.0 schema and complete Spring Boot 3.5 migration fixes #7)
• Therefore: cannot mint a token, cannot exercise /oauth2/introspect, cannot capture the actual introspection response shape (the original Step 3 objective)

Revised Phase 2.0 estimate

Prior estimate (3-4 working days) invalidated. Realistic estimate:

Work	Effort
Patches #1-#6 → production-quality PR with tests	1-2 days (today's patches are demo-quality; need test coverage and code review)
Patch #7 — filter chain canonical pattern + second chain	0.5-1 day
Patch #8 — diagnose and fix custom JdbcRegisteredClientRepository.findAll()	0.5 day (and likely surfaces more bugs in the custom repo — full audit recommended)
#123 — ESPI 4.0 XSD-aligned schema repair (MySQL/PostgreSQL/H2)	0.5-1 day
V4-V6 migration audit (likely more drift)	0.5 day (audit only; fixes additional)
Spring Authorization Server canonical config audit (find remaining non-canonical patterns)	0.5 day
Original Step 3.5 (grant-completion hook) + 3.6 (subscription-create endpoint)	1-1.5 days (unchanged from prior estimate)
Step 4 (introspection enrichment) + Step 4.5 (scope-grammar alignment)	0.5-1 day combined
Step 6 (end-to-end smoke test)	0.5 day
Total	6-10 working days

Recommendation for sequencing

1. Land today's 6-patch PR (boot reaches Started state on dev-mysql) — discrete, reviewable, well-documented scope.
2. Land patch feat: upgrade to ESPI 4.0 schema and complete Spring Boot 3.5 migration fixes #7 + refactor: standardize repository naming convention #8 as a second PR — restore actual token issuance + repository correctness.
3. ApplicationInformation schema drift from ESPI 4.0 XSD across MySQL/PostgreSQL/H2 V1 migrations #123 schema repair in parallel — different files, independent reviewers possible.
4. Then proceed with the original Phase 2.0 steps 3.5 onwards (grant-completion hook, subscription endpoint, introspection enrichment).

Patches accumulated this session (today's PR scope)

9 files changed, 32 insertions(+), 15 deletions(-)
 openespi-authserver/docker/docker-compose.yml
 .../authserver/config/AuthorizationServerConfig.java        (patch #4)
 .../authserver/config/HttpsEnforcementConfig.java           (patch #5)
 .../resources/application-dev-mysql.yml                     (patches #2, #3, #6)
 .../resources/application-dev-postgresql.yml                (patch #2)
 .../resources/application-local.yml                         (patch #2)
 .../resources/application-prod.yml                          (patch #2)
 .../resources/application.yml                               (patch #2)
 .../db/vendor/mysql/V1_0_0__create_oauth2_schema.sql        (patch #1)

Branch state

feature/issue-122-auth-server-bringup — 6 patches applied, no commits yet. About to be committed as a single PR titled along the lines of "fix(authserver): make dev-mysql boot reach Started state — six pre-existing defects". Patch #7 (filter chain) will land as a separate PR.