docs(16.3-03): complete Journal scopes and v0.1.21 release plan
This commit is contained in:
@@ -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*
|
||||
Reference in New Issue
Block a user