Repository navigation
Description
Purpose
Prioritise every open issue towards one objective: operational Authorization Server, Data Custodian and Third Party applications that can be tested by hand, quickly.
- Phases run in order. Within a phase, the order is the critical path.
- Size: S ≈ a day, M ≈ a few days, L ≈ a week or more.
Principles:
- Unblock the end-to-end flow before adding breadth.
- Make local setup reproducible before debugging it.
- Fix wrong data exposure before anything is shared.
- Keep one source of truth for each concern: schema = Flyway, access rules = one policy, registration = RFC 7591.
Completed issues are struck through.
Progress (updated 2026-11-18)
Done in Phase 1:
Local manual-test kit: aligned AS/DC/TP local profiles, start/stop/smoke scripts, and docs/LOCAL_TESTING.md #254(PR feat(local): one-command local manual-test kit for AS, DC and TP (#254) #259),DC local profile: seed a deterministic ESPI sample dataset (customer, usage, PII, ApplicationInformation) for manual testing #253(PR feat(datacustodian): seed a deterministic ESPI sample dataset on the local profile (#253) #261),AS: unauthenticated /oauth2/authorize redirects to /authorize/delegate without parameters (400); outbound delegation to DC is broken #232(PR fix(authserver): carry the authorization request to /authorize/delegate (#232) #262),AS/DC: customer scope narrowing yields invalid_scope on authorize replay #211(PR fix(authserver,datacustodian): allow ESPI scope narrowing by the Third Party and the customer (#211) #265)Third Party: add a username/password login page matching the Data Custodian login design #249(PR feat(thirdparty): username/password login matching the Data Custodian design (#249) #268, review follow-up PR fix(thirdparty): address the #268 review of Third Party form login (#249) #270),Third Party: make Flyway own the schema in every profile using the openespi-common scripts (split from #241) #267(PR feat(thirdparty): Flyway owns the Third Party schema in every profile (#267) #272)TP bring-up: missing JAXB Atom marshaller, narrow component scan, and broader OAuth2-client wiring gaps #146(PR feat(thirdparty): Spring Security oauth2Client for the Data Custodian authorization (#146) #275),Third Party cannot unmarshal any ESPI Atom feed (AtomFeedDto date adapters + abstract entry type) #197(PR feat(common): ESPI resources inside atom:content, and XSD validation of ESPI XML (#197) #280)
Found and fixed along the way:
DC feed (collection) endpoints return 500: a bare List is passed to JAXB instead of an Atom feed #247: the DC feed endpoints returned 500 (PR fix(#247): export DC collection endpoints as Atom feeds instead of a bare List #250).DC: Authorization Screen consent submit is rejected as a handoff replay, and login does not return to the screen #263: Authorization Screen consent was rejected as a handoff replay, and login did not return to the screen (PR fix(datacustodian): complete the Authorization Screen consent and return to it after login (#263) #264).
Filed since this roadmap:
| Issue | Topic | Source | Placed in |
|---|---|---|---|
| TP Flyway | split from #241 | Phase 1, item 4a; done | |
| #256 | DC Batch/Bulk API | Phase 2 | |
| #266 | NAESB errata for REQ.21 v4.1 OAuth 2.0 Scope | submitted 2026-11-15 | tracking only, no code change |
| #271 | AS and DC H2 console settings | #270 review | Phase 2, item 9a |
| #273 | openespi-common's jar application.properties and application-<profile>.yml override each application's own config |
#272 review | Phase 2, item 14 |
| #274 | The AS drops the PKCE code_challenge in the DC delegation, so PKCE is off in the TP for now |
#146 | Phase 2, item 9b |
| #276 | AS remembered consent skips the DC delegation, so a repeat authorization gets no Subscription and no token-response URIs | #146 | Phase 1, item 5a |
| #277 | AboutControllerTest fails on a JDK whose java.version is exactly 25 |
Continuous | |
| #278 | Enumeration XML values: REQ.21 needs numeric codes for ServiceKind and PhaseCodeKind, and exact literals for the other kinds, never Java constant names | #197 | Phase 3, schema compliance |
| #279 | DC Batch/Subscription |
#197 | Phase 1, item 6 |
| #281 | Every ESPI atom:id a permanent, repeatable UUID v5 from business keys: no random v4, no URL or token names |
#280 | Phase 2, item 10a |
TP now:
- Form login:
admin/adminis the TP administrator;customer/customeronlocal. - The H2 console is limited to the TP administrator.
localis the default profile and listens on127.0.0.1only.- Flyway owns the schema on H2, MySQL and PostgreSQL (
ddl-auto: validate, with schema tests on all three).
TP OAuth client (#146):
- Uses Spring Security
oauth2Client. The TP customer stays signed in while authorizing at the DC. - Tokens and the token-response URIs are stored in the TP's ESPI
authorizationstable (Flyway V6). - The TP administrator obtains the
FB=34_35client access token on the admin page. - Verified end to end on
local.
ESPI XML (#197):
- Each resource is now inside
<atom:content>, in both the DC export and the TP reader. EspiXmlSchemaValidatorchecks ESPI XML against atom.xsd, espi.xsd and customer.xsd.- The feed
publishedand the empty feed's link type were fixed. docs/ESPI_ATOM_PROFILE.mdrecords where ESPI deliberately differs from RFC 4287.- Decision 3 below is resolved.
#202 split:
- The TP side is done in
TP bring-up: missing JAXB Atom marshaller, narrow component scan, and broader OAuth2-client wiring gaps #146. - The AS side remains, now Phase 2, item 11a, ahead of DC: implement ESPI Batch/Bulk API — Third Party client access token only, scoped to its own Authorizations #256:
customerResourceURIgated on FB_51;- refresh must not re-provision;
- the
FB=34_35client access token must carryauthorizationURI, the energy usage BulkresourceURIand the Customer PII BulkcustomerResourceURI.
Next: #279 DC Batch/Subscription, then minimal #89, so the TP fetches, validates and displays the customer's data. That is the last Phase 1 exit criterion.
Phase 1: Manually testable locally (critical path)
Exit criteria:
scripts/local/start-all→smokepasses.- A TP user logs in to the TP and authorizes access, then logs in and consents at the DC.
- The TP receives a token and displays that customer's usage data.
- Admin and token checks run from
docs/LOCAL_TESTING.md.
| # | Item | Size | Why now |
|---|---|---|---|
| 1 | ✅ |
S | Removes the hidden-secret and mismatch friction; everything after builds on it |
| 2 | ✅ |
S–M | Without data, consent and feeds can't be exercised |
| 3 | ✅ |
S | Blocks the customer flow |
| 4 | ✅ |
M | A TP user must exist to start the flow; before this, the login button gave a 500 |
| 4a | ✅ |
M | Not needed for the local H2 exit criteria; needed to run the TP on MySQL/PostgreSQL. Can run in parallel with #249 |
| 5 | ✅ |
M | TP must obtain and store the token and know where the customer's resources are |
| 5a | #276 AS remembered consent skips the DC delegation (no Subscription, no URIs on a repeat authorization) | S–M | Every repeat authorization during manual testing hits it; today only an AS restart clears it |
| 6 | ✅ <atom:content>, getResource(), empty feed, XSD validationBatch/Subscription (next; pass the feed's resource name to buildFeed explicitly) → minimal #89 (TP fetches the Subscription, validates it with EspiXmlSchemaValidator in off/report/enforce mode, captures it on local/dev only, and displays a UsagePoint and its readings) |
M + M | TP must show data to prove the flow end to end |
| 7 | ✅ invalid_scope |
S–M | Consent with fewer function blocks must work |
| 8 | #225 401 (not 302) on unauthenticated token / introspect / revoke; #234 missing AS H2 tables | S + S | Makes curl testing and the logs trustworthy |
Phase 2: Safe to share (sandbox / demo deployment)
| # | Item | Size | Notes |
|---|---|---|---|
| 9 | Fixes for privately reported security advisories (tracked in GitHub Security Advisories) | M | Before anything is exposed beyond localhost |
| 9a | #271 AS and DC H2 console settings (AS web-allow-others: true, no console module; DC permitAll), aligned with the TP's (#270) |
S | Before anything is exposed beyond localhost |
| 9b | #274 AS carries the PKCE code_challenge through the DC delegation; then restore PKCE in the TP (TpCustomerAuthorizationRequestResolver) |
S–M | The TP sends no PKCE until then |
| 10 | #187 resource scoping: ESPI GETs must be limited to the token's Subscription/Authorization (today Subscription-scoped GETs ignore subscriptionId, per CLAUDE.md) |
L | Prevents one customer's data being returned for another's token |
| 10a | #281 permanent, repeatable UUID v5 atom:ids: remove the random v4 default from IdentifiedObject; use a per-DC namespace and names from business keys; Authorization from correlationId; IntervalBlock from the interval start; single-resource endpoints return <entry> |
M–L | Third Parties rely on stable ids to recognise repeated data; ids must not change once data is shared. Single-resource <entry> fits with #187 |
| 11 | #138 consent withdrawal → token revocation + subscription cleanup | M | |
| 11a | #202 (AS side) token-response URIs: FB_51 gating, no re-provisioning on refresh, the FB=34_35 client access token's authorizationURI + Bulk resourceURI / customerResourceURI → #256 DC Batch/Bulk API (Third Party client access token only, scoped to its own Authorizations) |
S–M + M–L | #256 after #202 and #251; uses the #187 scoping. The TP already stores and shows the client token's URIs |
| 12 | #251 registration access token (RFC 7591 + FB=36_40 renewal, DC accepts it for ApplicationInformation) → #252 TP self-registration |
M + L | Replaces the seeded TP client; spike done |
| 13 | #131 dependency CVEs; #237 CodeQL triage | M | |
| 14 | #241 (DC, including local Flyway on H2, and AS; the TP part moved to docker/prod/aws-sandbox profile files block those deployment profiles); #200 audit-log writers; #199 abandoned-authorization cleanup |
M–L | Needed for the MySQL/PostgreSQL deployment profiles |
| 15 | #233 metadata advertises unsupported JWT/JWKS features; #188 TLS certificates | S + M |
Phase 3: ESPI completeness and certification readiness
- Remediation: ESPI REST controller modernization (post-#116) #119 epic.
- E1: DC resource engine + Atom entry-assembly (GET-first) — UsagePoint & Customer verticals, scope-enforced #187 E1 engine: all resources.
- Full Implement comprehensive JAXB unmarshalling support for XML import #89 import.
- Add ProgramIdMappings entity + UsagePoint↔ProgramIdMappings relationship (energy) #168 / Map existing PII-tree FKs into JPA entity relationships (CustomerAgreement/ServiceLocation tree) #169 / Verify Entity Field Types and Lengths Match ESPI 4.0 XSD Schemas #101 / ESPI DTO enums are written as Java constant names, not the XSD values (e.g. ServiceCategory) #278 schema compliance. ESPI DTO enums are written as Java constant names, not the XSD values (e.g. ServiceCategory) #278 is the enumeration XML values; with
EspiXmlSchemaValidator, these show up as XSD errors. - DC customer portal: implement usage points, Download My Data and the legacy customer home (or retire them) #245 DC customer portal (usage, Download My Data).
- Authorization Server: add a home/landing page (no AS home screen exists today) #186 AS home page.
Continuous: quality and hygiene (pick up alongside)
- Rebuild AS OAuth2 flow integration suite on AbstractAuthserverIntegrationTest #151 rebuild the AS OAuth flow integration suite. It would have caught
AS: unauthenticated /oauth2/authorize redirects to /authorize/delegate without parameters (400); outbound delegation to DC is broken #232; prioritise it early in Phase 2. - Remove or fix skipped / @Disabled / CI-excluded tests across modules #194 skipped and disabled tests.
- fix: Cross-platform timestamp test failures due to OS timestamp resolution differences #78 timestamp-resolution flake (seen again:
CustomerAccountRepositoryTest.shouldUpdateTimestampsOnModification). - AboutControllerTest fails on a JDK whose java.version is exactly "25" (matches Bootstrap w-25) #277
AboutControllerTestand ajava.versionof exactly25. - Comprehensive DTO Test Coverage and Standardization #88, Enhance XML Debug Tests for Additional ESPI Entities #103, Cleanup: controll-update-status.md filename typo + unimplemented @accountSecurityService bean #133.
Closed after review (confirmed 2026-11-16)
All six were closed with a comment giving the reason: #141, #204, #205 and #98 as completed; #203 and #117 as not planned.
| # | Reason |
|---|---|
Done in #250: DC Authorization endpoints implemented with per-TP filtering (AdminCaller, AdminRowScopeTest) |
|
Done: admin API bearer tokens are on main (merged with the GHSA-mh65 fix, 40812eb) |
|
Done: admin user store + passkey MFA + bootstrap are on main (same merge) |
|
| Superseded by #251: the certification question is answered, since REQ.21 requires the registration access token | |
| Delivered by #116; no description of its own; remaining work is in #187 / #119 | |
Obsolete: pr-checks.yml no longer exists, and no workflow runs Spotless |
Decisions needed
- Third Party: register itself via RFC 7591 dynamic client registration and manage its registration #252: how a Third Party receives its RFC 7591 initial access token during onboarding: from the DC operator, from GBA, or through another out-of-band step.
- Registration access token: issue it on RFC 7591 registration, renew via FB=36_40, and require it for ApplicationInformation #251: RFC 7592 (Experimental) says a registration access token should not expire while the client is registered; ESPI renews an expired one through
FB=36_40. Document this as a deliberate ESPI profile choice. - ✅
Third Party cannot unmarshal any ESPI Atom feed (AtomFeedDto date adapters + abstract entry type) #197: adopting theResolved: done as one change in PR feat(common): ESPI resources inside atom:content, and XSD validation of ESPI XML (#197) #280, following the certified ScriptLogs and the DMD validator's atom.xsd.<atom:content>wrapper changes the wire format for both DC export and TP import. Confirm it should be done as one change. - ESPI atom:id: every resource id a permanent, repeatable UUID v5 from business keys (no random v4, no URL or token names) #281: see that issue's "Points to settle":
- the client_credentials Authorization's name input (proposal: the AS's own grant record id);
- whether the DC namespace is non-public configuration, since account and serial numbers are guessable names.
References
RFC 7591 (Dynamic Client Registration), RFC 7592 (Registration Management, Experimental), NAESB REQ.21 v4.1, GBA Generating Persistent UUIDs, docs/ESPI_ATOM_PROFILE.md, CLAUDE.md "Known Issues"
🤖 Generated with Claude Code
Activity
dfcoffin commentedon Nov 14, 2026
Roadmap update:
Batch/BulkAPI, Third Party client access token only) next to ESPI token-response URIs: FB_51 gating, re-provisioning on refresh, missing URIs for client_credentials tokens #202. Registration access token: issue it on RFC 7591 registration, renew via FB=36_40, and require it for ApplicationInformation #251 now also covers grantingclient_credentialsto registered Third Parties, limited by the server toThirdParty_Admin_AccessandFB=36_40, so customer FB scopes can only come fromauthorization_code.🤖 Generated with Claude Code