golem15/summercms
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(09-01): complete separate-admin genre list tracer plan

Browse Source
This commit is contained in:
Jakub Zych
2026-09-24 17:23:23 +02:00
parent 18b2e85106
commit 0ed980e332
4 changed files with 282 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
.planning/ROADMAP.md
View File

@@ -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 | - |

32
.planning/STATE.md
View File

@@ -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

36
.planning/WINDOWS.md Normal file
View File

@@ -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 <id> "<reason>"` (reason required).
> Mark fixed with `gsd-tools windows fixed <id>`.
| 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"
}
]
````

223
.planning/phases/09-backend-admin-authentication-and-schema-pipeline/09-01-SUMMARY.md Normal file
View File

@@ -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*