diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index cfdc90d..2d5e85c 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -375,13 +375,13 @@ Plans: 4. The relation-manager schema supports search/link/unlink/manage-or-view lists for Collections' editors tab, replacing the `partial` field entirely. 5. Admin CRUD endpoints expose `listExtendQuery`/`formExtendQuery`/`formBeforeCreate`/`formBeforeUpdate`/`relationExtendManageQuery` hooks, bulk delete runs each record's lifecycle hooks, and the Settings model binds to a settings screen through the same schema pipeline. -**Plans**: 12 plans +**Plans**: 1/12 plans executed **Research flag:** yes Plans: **Wave 1** -- [ ] 09-01-PLAN.md — Prove the architecture with one production end-to-end Genre list +- [x] 09-01-PLAN.md — Prove the architecture with one production end-to-end Genre list **Wave 2** *(blocked on Wave 1 completion)* - [ ] 09-02-PLAN.md — Complete backend identity lifecycle and operator provisioning @@ -529,7 +529,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → | 6. HTTP routing, auth groups and rate limiting | 14/14 | Complete | 2026-09-21 | | 7. User plugin and authentication | 8/8 | Complete | 2026-09-23 | | 8. OAuth2.1 authorization server | 10/10 | Complete | 2026-09-23 | -| 9. Backend admin authentication and schema pipeline | 0/TBD | Not started | - | +| 9. Backend admin authentication and schema pipeline | 1/12 | In Progress| | | 10. Admin Vue SPA | 0/TBD | Not started | - | | 11. Jobs, realtime and search infrastructure | 0/TBD | Not started | - | | 12. Płytarium API — Collections and Albums | 0/TBD | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index f69e400..bb04645 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,18 +2,18 @@ gsd_state_version: "1.0" milestone: v1.0 current_phase: 09 -current_phase_name: backend-admin-authentication-and-schema-pipeline +current_phase_name: Backend admin authentication and schema pipeline status: executing -stopped_at: Phase 08 complete (10/10) — ready to discuss Phase 09 -last_updated: "2026-09-24T14:43:54.863Z" +stopped_at: Completed 09-01-PLAN.md +last_updated: "2026-09-24T15:22:53.884Z" last_activity: 2026-09-24 -last_activity_desc: Phase 09 planning complete -state_head: 1fbf492450fe6d8b0cf4fa0cd6f742d40e117ce5 +last_activity_desc: Phase 09 execution started +state_head: 18b2e851063f3a50b7a13c87413ac4ae3ece9998 progress: total_phases: 15 completed_phases: 8 total_plans: 67 - completed_plans: 55 + completed_plans: 56 milestone_name: milestone --- @@ -24,14 +24,14 @@ milestone_name: milestone See: .planning/PROJECT.md (updated 2026-09-16) **Core value:** An existing WinterCMS-shaped app can be ported plugin by plugin to a single Go binary without its frontend noticing: the PHP version's API contract is the acceptance test. -**Current focus:** Phase 09 — backend admin authentication and schema pipeline +**Current focus:** Phase 09 — Backend admin authentication and schema pipeline ## Current Position -Phase: 09 (backend-admin-authentication-and-schema-pipeline) — READY TO EXECUTE -Plan: Not started +Phase: 09 (Backend admin authentication and schema pipeline) — EXECUTING +Plan: 2 of 12 Status: Ready to execute -Last activity: 2026-09-24 — Phase 09 planning complete +Last activity: 2026-09-24 — Phase 09 execution started Progress: [██████████] 100% @@ -105,6 +105,11 @@ Progress: [██████████] 100% | Phase 08 P08 | 20min | 2 tasks | 4 files | | Phase 08 P09 | 55min | 3 tasks | 25 files | | Phase 08 P10 | 55min | 3 tasks | 17 files | +**Per-Plan Metrics:** + +| Plan | Duration | Tasks | Files | +|------|----------|-------|-------| +| Phase 09 P01 | 26min | 2 tasks | 26 files | ## Accumulated Context @@ -264,6 +269,9 @@ Recent decisions affecting current work: - [Phase 08]: Security review self-performed by the 08-10 executor (no Task/Agent spawner available), disclosed in 08-SECURITY-REVIEW.md's frontmatter and Reviewer Note — Per 08-CONTEXT.md D-04's documented fallback; every cited file:TestName was individually re-run, not inherited unverified - [Phase 08]: Checkpoint decision: approved closing Phase 8 with the Playwright UI matrix gap (check-phase8-ui.mjs:458) carried forward as a named follow-up — Every other scripts/check-phase8.sh stage ran green in the sole full gate execution; the Playwright matrix was a deliberate, never-authored fatal() left by 08-05 as 08-10's seam - [Phase 08]: AUTH-05, AUTH-06 and AUTH-07 marked complete in REQUIREMENTS.md — Each requirement's exact text is satisfied by the delivered backend/gate evidence; none mandates a Playwright-verified browser regression suite, so the carried-forward UI gap does not block completion +- [Phase 09]: Frontend verification accepts PHP tokens that omit aud and rejects any other explicit audience +- [Phase 09]: Backend JWTs require aud=backend, use admin.jwt.secret, and omit the PHP user prv hash +- [Phase 09]: Cabana mounts from BuildRouter only when a plugin registers admin controllers; an empty admin.jwt.secret fails that assembly ### Pending Todos @@ -286,6 +294,6 @@ Items acknowledged and carried forward from previous milestone close: ## Session Continuity -Last session: 2026-09-23T23:03:36.023Z -Stopped at: Completed 08-10-PLAN.md (Phase 8 closed; Playwright UI matrix gap carried forward) +Last session: 2026-09-24T15:22:53.442Z +Stopped at: Completed 09-01-PLAN.md Resume file: None diff --git a/.planning/WINDOWS.md b/.planning/WINDOWS.md new file mode 100644 index 0000000..d5c6817 --- /dev/null +++ b/.planning/WINDOWS.md @@ -0,0 +1,36 @@ +--- +schema_version: 1 +open_count: 0 +waived_count: 0 +fixed_count: 1 +total_count: 1 +last_updated: 2026-09-24T15:23:23.945Z +--- + +# Broken Windows Ledger + +> Cross-phase defect register. With `workflow.windows_enforce` enabled, `/gsd-ship` blocks while `open_count > 0`. +> Waive with `gsd-tools windows waive ""` (reason required). +> Mark fixed with `gsd-tools windows fixed `. + +| id | phase | kind | file | line | description | status | reason | recorded_at | resolved_at | +|----|-------|------|------|------|-------------|--------|--------|-------------|-------------| +| 1 | 09 | deviation | plugins/golem15/fonoteka/routes_cors_test.go | | Admin test secret also set on bootConfigWithHTTP and testConfigCORS so router assembly keeps failing closed | fixed | | 2026-09-24T15:22:55.173Z | 2026-09-24T15:23:23.945Z | + +````json +[ + { + "id": 1, + "kind": "deviation", + "phase": "09", + "file": "plugins/golem15/fonoteka/routes_cors_test.go", + "line": null, + "description": "Admin test secret also set on bootConfigWithHTTP and testConfigCORS so router assembly keeps failing closed", + "status": "fixed", + "reason": "", + "recorded_at": "2026-09-24T15:22:55.173Z", + "resolved_at": "2026-09-24T15:23:23.945Z", + "milestone": "v1.0" + } +] +```` diff --git a/.planning/phases/09-backend-admin-authentication-and-schema-pipeline/09-01-SUMMARY.md b/.planning/phases/09-backend-admin-authentication-and-schema-pipeline/09-01-SUMMARY.md new file mode 100644 index 0000000..257e6a0 --- /dev/null +++ b/.planning/phases/09-backend-admin-authentication-and-schema-pipeline/09-01-SUMMARY.md @@ -0,0 +1,223 @@ +--- +phase: 09-backend-admin-authentication-and-schema-pipeline +plan: 01 +subsystem: auth +tags: [jwt, postgres, gorm, admin, cabana, bouncer] + +requires: + - phase: 06-http-routing-auth-groups-and-rate-limiting + provides: named bouncer guards and raw route groups + - phase: 07-user-plugin-and-authentication + provides: HS256 mint/verify, bcrypt, and the jti blacklist +provides: + - Audience-separated frontend and backend JWTs + - Framework backend_users and backend_user_roles tables + - Cabana raw admin login, list schema, and record-list routes + - One compiled Genre list served from embedded Winter YAML +affects: [09-backend-admin-authentication-and-schema-pipeline, admin-api, phase-10-spa] + +actuals: + tokens: 17027 + tasks: 2 + commits: 3 + +tech-stack: + added: [] + patterns: + - "Admin routes mount from surf.BuildRouter only when a plugin registers admin controllers" + - "D-10 envelopes stay inside cabana; frontend 401 bodies stay PHP-shaped" + - "Plugin AdminFS plus AdminRecordSource keep table names and permission codes out of cabana" + +key-files: + created: + - cabana/http.go + - cabana/auth.go + - cabana/schema.go + - cabana/registry.go + - cabana/contracts.go + - lagoon/backend_admin_migrations.go + - bouncer/audience_test.go + - cabana/security_test.go + modified: + - bouncer/jwt.go + - bouncer/mint.go + - bouncer/refresh.go + - bouncer/context.go + - pact/capabilities.go + - surf/router.go + - lagoon/migrations.go + +key-decisions: + - "Frontend verification still accepts PHP tokens that omit aud, and rejects any explicit audience other than user" + - "Backend tokens require aud=backend, use admin.jwt.secret, and omit the PHP user prv lock-subject" + - "Empty admin.jwt.secret fails router assembly only when admin controllers are registered; there is no fallback secret" + - "golang-jwt emits a one-element aud array; both guards accept that form" + +patterns-established: + - "Pattern: guard, then controller lookup, then RequiredPermissions, then schema or SQL" + - "Pattern: Winter list YAML is compiled once at activation with DisallowUnknownField" + +requirements-completed: [AUTH-08, ADMIN-02] + +coverage: + - id: D1 + description: A developer-role backend admin logs in and reads one persisted Genre through the compiled admin list. + requirement: ADMIN-02 + verification: + - kind: integration + ref: plugins/golem15/fonoteka/admin_tracer_test.go#TestAdminTracerGenreList/genre_list + status: pass + human_judgment: false + - id: D2 + description: An empty admin.jwt.secret fails router assembly with a named configuration error. + requirement: AUTH-08 + verification: + - kind: integration + ref: plugins/golem15/fonoteka/admin_tracer_test.go#TestAdminTracerGenreList/empty_secret + status: pass + human_judgment: false + - id: D3 + description: Frontend and backend guards reject each other's audience even when the HMAC secret matches. + requirement: AUTH-08 + verification: + - kind: unit + ref: bouncer/audience_test.go#TestAudienceCrossover + status: pass + human_judgment: false + - id: D4 + description: Missing and invalid admin credentials return unauthenticated 401 before a missing controller can be distinguished, and bodies do not echo secrets or tokens. + requirement: AUTH-08 + verification: + - kind: integration + ref: plugins/golem15/fonoteka/admin_tracer_test.go#TestAdminTracerAuthBoundary + status: pass + - kind: unit + ref: cabana/security_test.go#TestSecretRedaction + status: pass + human_judgment: false + - id: D5 + description: A non-superuser without the Genre permission receives forbidden 403 before schema or SQL, and a superuser can list. + requirement: ADMIN-02 + verification: + - kind: unit + ref: cabana/security_test.go#TestAuthorizationOrder + status: pass + - kind: integration + ref: plugins/golem15/fonoteka/admin_tracer_test.go#TestAdminTracerPermissionBoundary + status: pass + human_judgment: false + +duration: 26min +completed: 2026-09-24 +status: complete +plan_head_before: 01d3871510f503f07e89282aa5501022cc4839af +plan_head_after: 18b2e851063f3a50b7a13c87413ac4ae3ece9998 +--- + +# Phase 9 Plan 01: Separate-admin Genre list tracer Summary + +**A backend administrator logs in with a distinct JWT audience and reads one real Genre row through a boot-compiled Winter list schema on PostgreSQL.** + +## Performance + +- **Duration:** 26 min +- **Started:** 2026-09-24T14:55:33Z +- **Completed:** 2026-09-24T15:21:30Z +- **Tasks:** 2 +- **Files modified:** 26 + +## Accomplishments + +- Backend identity lives in Winter-shaped `backend_users` and `backend_user_roles` tables, seeded with the developer and publisher system roles, and is never read from frontend `users`. +- `surf.BuildRouter` activates cabana only when a plugin registers admin controllers, and refuses an empty `admin.jwt.secret` instead of borrowing the user secret. +- `POST /_admin/api/v1/auth/login` accepts a login or a normalized email, and `GET /_admin/api/v1/golem15/fonoteka/genres` returns the persisted row plus list meta from the embedded `columns.yaml`. +- The same HMAC secret cannot move a token across the frontend and backend guards. Permission denial happens before the list callback. + +## Task Commits + +Each task was committed atomically. SummerCMS `commits: 3` is `git rev-list --count` from the plan ledger. Fonoteka commits are in the sibling repository. + +1. **Task 1: Genre list tracer (RED)** - `9defed3` (test, fonoteka.go) login was 404 and an empty admin secret still assembled +2. **Task 1: Genre list tracer (GREEN)** - `dfa00f7` (feat, summercms.go) and `a87eacc` (feat, fonoteka.go) +3. **Task 2: Token and permission boundaries (RED)** - `8c1de83` (test, summercms.go) and `195c95c` (test, fonoteka.go) +4. **Task 2: Token and permission boundaries (GREEN)** - `18b2e85` (feat, summercms.go) frontend guard rejects a backend audience + +**Plan metadata:** pending docs commit + +## Files Created/Modified + +- `cabana/http.go` - raw admin login, list-schema, and record-list routes +- `cabana/auth.go` - backend user model, login lookup, and principal grants +- `cabana/schema.go` - strict compile of `config_list.yaml` and `columns.yaml` +- `cabana/registry.go` - immutable controller registry +- `cabana/contracts.go` - D-10 envelopes and permission matching +- `lagoon/backend_admin_migrations.go` - backend identity tables and system roles +- `bouncer/jwt.go` - audience-aware verify and backend guard +- `bouncer/mint.go` / `bouncer/refresh.go` - audience-preserving mint and refresh +- `pact/capabilities.go` - admin asset, permission, navigation, settings, and hook contracts +- `surf/router.go` - activates cabana before route wrapping +- `fonoteka.go` `admin.go`, Genre controller, and embedded list YAML +- `fonoteka.go/config/admin.yaml` - empty `admin.jwt.secret` with no production default + +## Decisions Made + +- Legacy frontend tokens with no `aud` claim stay valid. A present audience must be `user` on the frontend guard and `backend` on the backend guard. +- Backend tokens do not carry the PHP user `prv` hash. +- Admin route assembly is skipped when no plugin implements `HasAdminControllers`, so existing surf tests do not need an admin secret. +- golang-jwt v5 writes `aud` as a JSON array even for one value. The tracer accepts that encoding. + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 3 - Blocking] Admin test secret added to every shared router config helper** +- **Found during:** Task 1 (Genre list tracer) +- **Issue:** Once the Genre controller is registered, every full-app `BuildRouter` needs `admin.jwt.secret`. The plan named `plugin_boot_test.go` and `parity/migrate_test.go`, but `routes_cors_test.go` and `parity/genre_security_test.go` assemble the same router through their own helpers. +- **Fix:** Set `SUMMER_ADMIN__JWT__SECRET` to the test-only admin secret in those helpers too. It is not the user secret and it is not a production default. +- **Files modified:** `plugins/golem15/fonoteka/routes_cors_test.go`, `parity/genre_security_test.go`, plus the two helpers the plan named +- **Verification:** `go test ./plugins/golem15/fonoteka -count=1` passed +- **Committed in:** `a87eacc` (fonoteka.go) + +--- + +**Total deviations:** 1 auto-fixed (1 blocking) +**Impact on plan:** The extra helpers are the same test-secret change the plan required. No production secret was added and no module dependency changed. + +## TDD Gate Compliance + +| Gate | Commit | Result | +|------|--------|--------| +| RED task 1 | `9defed3` test(09-01) | `TestAdminTracerGenreList` failed on login 404 and a nil empty-secret error | +| GREEN task 1 | `dfa00f7` / `a87eacc` feat(09-01) | tracer passed on real PostgreSQL | +| RED task 2 | `8c1de83` test(09-01) | `TestAudienceCrossover` failed because the frontend guard accepted a backend token | +| GREEN task 2 | `18b2e85` feat(09-01) | audience, authorization-order, and boundary tests passed | + +`gsd_run check tdd-red-evidence` returned `RED_EVIDENCE_OK` for both RED runs. Go's test output is not TAP, so each evidence record appends a TAP trailer that names the test the go harness actually failed. + +## Authentication Gates + +None. + +## Issues Encountered + +None. + +## User Setup Required + +None - no external service configuration required. + +Production boots that register admin controllers must set `SUMMER_ADMIN__JWT__SECRET`. `config/admin.yaml` ships the key empty on purpose. + +## Next Phase Readiness + +Ready for 09-02. The cabana registry, backend principal, audience-aware bouncer helpers, and D-10 envelope are the skeleton later plans extend. `AUTH-08` and `ADMIN-02` stay shared with later plans in this phase, so they are not marked complete yet. + +## Self-Check: PASSED + +- FOUND: cabana/http.go, cabana/auth.go, cabana/schema.go, cabana/registry.go, cabana/contracts.go, lagoon/backend_admin_migrations.go +- FOUND: fonoteka admin.go, genres admin controller, config_list.yaml, columns.yaml, admin_tracer_test.go, config/admin.yaml +- FOUND commits: 9defed3, dfa00f7, a87eacc, 8c1de83, 195c95c, 18b2e85 + +--- +*Phase: 09-backend-admin-authentication-and-schema-pipeline* +*Completed: 2026-09-24*