224 lines
10 KiB
Markdown
224 lines
10 KiB
Markdown
---
|
|
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*
|