docs(16.3-03): complete Journal scopes and v0.1.21 release plan

This commit is contained in:
2026-10-11 13:08:54 +02:00
parent 2030fd881a
commit c385dc79eb
3 changed files with 233 additions and 9 deletions

View File

@@ -0,0 +1,221 @@
---
phase: 16.3-backend-admin-personal-api-tokens-with-scopes
plan: 03
subsystem: auth
tags: [api-tokens, journal, ResolveBackend, release, g15, scopes]
requires:
- phase: 16.3-backend-admin-personal-api-tokens-with-scopes
provides: cabana.ResolveBackend, account token API, admin SPA tokens card
provides:
- "journal and journal:read token scopes on sm-journal-plugin"
- "Journal API auth via cabana.ResolveBackend with cover golem15.journal.*"
- "ExampleResolveBackend docs example and Journal README token docs"
- "summercms v0.1.21 release with Journal go.mod and host gitlink bumps"
affects: [16.3-04, sm-journal-plugin, sm-grzybyfunkcjonalne-app]
actuals:
tokens: 20568
tasks: 4
commits: 2
plan_head_before: 611f98e33ba45b1f7718ead84cb8f8474e879f33
plan_head_after: 2030fd881aa08347931c638a90548b16bc188f86
tech-stack:
added: []
patterns:
- "Journal principals only via cabana.ResolveBackend(cover golem15.journal.*)"
- "ErrTokenScope → 403 Insufficient permissions; other resolver errors → 401 Authentication required"
- "Optional-auth reads treat cover/auth failure as anonymous"
key-files:
created:
- ../sm-journal-plugin/token_scopes.go
- ../sm-journal-plugin/controllers/api/auth_test.go
- ../sm-journal-plugin/journal_api_token_smoke_test.go
- modules/cabana/example_tokens_test.go
modified:
- ../sm-journal-plugin/controllers/api/auth.go
- ../sm-journal-plugin/lang/en/lang.yaml
- ../sm-journal-plugin/lang/pl/lang.yaml
- ../sm-journal-plugin/README.md
- ../sm-journal-plugin/go.mod
- docs/services/authentication.md
- modules/cabana/phase10_csrf_test.go
- ../sm-grzybyfunkcjonalne-app/plugins/golem15/journal
key-decisions:
- "Human resume: release v0.1.21 (release-now); no sm-summercmsio-app bump"
- "Probe test scope acme.probe registered for cover-failure cases because admin:read is Full on GET"
- "CSRF walk count updated 30→32 for account token create/revoke routes"
patterns-established:
- "Plugin API writes: ResolveBackend + resolveError mapping to PHP bodies"
- "Release sheet at blocking-human gate before any tag/push"
requirements-completed: [SC-2, SC-4, SC-5]
coverage:
- id: D1
description: "journal-scoped token minted via admin API creates a Journal post as its owner"
requirement: SC-4
verification:
- kind: unit
ref: ../sm-journal-plugin/controllers/api/auth_test.go#TestResolveErrorMapping
status: pass
- kind: integration
ref: ../sm-journal-plugin/journal_api_token_smoke_test.go#TestJournalTokenTracer
status: pass
human_judgment: false
- id: D2
description: "Read/unrelated/revoked tokens, optional draft unlock, featured-image canEdit parity, code-declared roles"
requirement: SC-2
verification:
- kind: integration
ref: ../sm-journal-plugin/journal_api_token_smoke_test.go#TestJournalTokenExpansion
status: pass
human_judgment: false
- id: D3
description: "Journal README and ExampleResolveBackend docs"
requirement: SC-5
verification:
- kind: other
ref: go test ./cmd/summer -run TestDocsTree; go run ./cmd/summer docs:build --check
status: pass
human_judgment: false
- id: D4
description: "Human-approved release v0.1.21 with Journal require and host gitlink"
verification:
- kind: other
ref: git ls-remote --tags origin refs/tags/v0.1.21; release-ok verify
status: pass
human_judgment: true
rationale: "Tag and push require human approval at blocking-human gate"
duration: 658min
completed: 2026-10-11
status: complete
---
# Phase 16.3 Plan 03: Journal scopes, ResolveBackend and v0.1.21 release Summary
**Journal registers `journal` / `journal:read`, authenticates writes through `cabana.ResolveBackend`, documents the path, and ships as summercms `v0.1.21` with plugin and host bumps.**
## Performance
- **Duration:** 658 min (includes overnight pause at the blocking-human release gate)
- **Started:** 2026-10-11T00:09:06Z
- **Completed:** 2026-10-11T11:07:50Z
- **Tasks:** 4
- **Files modified:** 12 (across summercms.go, sm-journal-plugin, sm-grzybyfunkcjonalne-app)
## Accomplishments
- Journal `TokenScopes` + lang keys; API auth switched to `cabana.ResolveBackend` with cover `golem15.journal.*`
- Postgres tracer and expansion matrix (read scope, probe cover, drafts, featured images, revoke, developer role grants)
- `ExampleResolveBackend` in cabana docs; Journal README scopes / Phase 15 D-15 reversal
- Human-approved release: annotated tag `v0.1.21`, Journal `go.mod` require, host journal gitlink
## Task Commits
Each task was committed atomically:
1. **Task 1: Tracer** — `4ec64a3` (sm-journal-plugin, feat)
2. **Task 2: Matrix + docs** — `f2026c5` (sm-journal-plugin, feat); `60873a3` (summercms.go, docs)
3. **Task 3: Release gate** — gate `release-gate-ok`; human reply `release v0.1.21`; CSRF inventory fix `2030fd8` (summercms.go, fix)
4. **Task 4: Release** — tag `v0.1.21` object `dc181e6` on `2030fd8`; Journal bump `09308d9`; host gitlink `e44cfde`
**Plan metadata:** (this commit)
## Human reply (Task 3, verbatim)
```
release v0.1.21
```
No `and summercmsio` — sm-summercmsio-app was not bumped.
## Release
| Item | Value |
|------|-------|
| Proposed / shipped tag | `v0.1.21` |
| Tag object | `dc181e6224389647ce378ac1420e5df48eea2e04` |
| Tag points at | `2030fd881aa08347931c638a90548b16bc188f86` |
| summercms.go master (pushed) | `2030fd8` |
| sm-journal-plugin main (pushed) | `09308d9` (requires `summercms v0.1.21`) |
| sm-grzybyfunkcjonalne-app master (pushed) | `e44cfde` (journal gitlink `09308d9`) |
| sm-summercmsio-app | not bumped |
| UAT redeploy | follow-up (not this plan) |
### One-way surfaces published
`pact.TokenScope` / `HasTokenScopes`; `bouncer.ScopeLimit` / `Principal.Scope`; `party.Activated`; `cabana.BackendAPIToken`, `APITokenPrefix`, `ResolveBackend`, `ErrUnauthenticated`, `ErrTokenScope`; account token routes; `g15_` format; `backend_api_tokens` / migration `202610110001_backend_api_tokens`.
### Release sheet (pre-approval)
- Trees clean and not behind origin; tag absent on origin before create
- Gate printed `release-gate-ok` (after CSRF count 30→32)
- Open high findings: none (`16.3-REVIEW.md` / `16.3-SECURITY.md` absent)
## Postgres verify status
| Suite | Status |
|-------|--------|
| 16.3-01 cabana/lagoon Postgres | **RUN** (prior SUMMARY) |
| `TestJournalTokenTracer` | **RUN** pass |
| `TestJournalTokenExpansion` | **RUN** pass |
| NOT RUN | none on this host for 16.3-03 |
## Decisions Made
- Followed D-04/D-01/D-15 and featured-image PHP parity (CanEdit only).
- Registered test-only `acme.probe` scope for unrelated-cover cases (`admin:read` is Full on GET).
- Human chose release-now `v0.1.21` without summercmsio.
## Deviations from Plan
### Auto-fixed Issues
**1. [Rule 1 - Bug] CSRF state-changing route count stale after token API**
- **Found during:** Task 3 release gate (`TestPhase10CSRF`)
- **Issue:** Walk counted 32 routes (account token create/revoke) but expected 30
- **Fix:** Updated expected count and comment to 32
- **Files modified:** `modules/cabana/phase10_csrf_test.go`
- **Verification:** Six cabana gate tests pass; `release-gate-ok`
- **Committed in:** `2030fd8`
**2. [Rule 3 - Blocking] Probe scope for cover-failure GET path**
- **Found during:** Task 2 expansion (`admin:read` on GET is Full, unlocks drafts as owner)
- **Issue:** Plan suggested `admin:read` for anonymous GET; Full scopes skip cover
- **Fix:** Test plugin `acme.probe` with `acme.probe.*` scope for cover refuse → anonymous GET
- **Files modified:** `journal_api_token_smoke_test.go`
- **Verification:** `TestJournalTokenExpansion` pass
- **Committed in:** `f2026c5`
---
**Total deviations:** 2 auto-fixed (1 bug, 1 blocking)
**Impact on plan:** Required for green release gate and correct cover semantics; no scope creep.
## Issues Encountered
None beyond the deviations above. Overnight pause at Task 3 until human resume.
## User Setup Required
None - no external service configuration required. UAT redeploy remains a separate follow-up.
## Next Phase Readiness
Ready for 16.3-04 (unit/backstop matrix). Framework + Journal token path released; hosts can mint `journal`-scoped tokens after migrate/redeploy.
## Self-Check: PASSED
- Key files exist on disk
- Tag `v0.1.21` on origin; Journal main = origin/main; host gitlink = Journal main; `release-ok`
- Commits grepped for 16.3-03 present in both repos
---
*Phase: 16.3-backend-admin-personal-api-tokens-with-scopes*
*Completed: 2026-10-11*