From 9652834ca02230d338888344c5bb0d0c0550abed Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Sat, 10 Oct 2026 16:21:35 +0200 Subject: [PATCH] docs(16.3): insert phase 16.3 and promote the API tokens todo --- .planning/ROADMAP.md | 23 +++++++++++++++++++ .planning/STATE.md | 15 ++++++------ .../.gitkeep | 1 + .../.gitkeep | 1 + .../.gitkeep | 1 + .../.gitkeep | 1 + .planning/state.json | 2 +- .../todos/pending/backend-admin-api-tokens.md | 6 +++-- 8 files changed, 40 insertions(+), 10 deletions(-) create mode 100644 .planning/phases/16.1-journal-admin-urgent-fixes-relation-search-list-state-post-f/.gitkeep create mode 100644 .planning/phases/16.2-plugin-provided-field-types-and-the-blog-editor-formwidget/.gitkeep create mode 100644 .planning/phases/16.3-backend-admin-personal-api-tokens-with-scopes/.gitkeep create mode 100644 .planning/phases/18.1-payment-gateway-subscriptions/.gitkeep diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index f83ebb1..356483e 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -1016,6 +1016,29 @@ Plans: **Wave 4** *(blocked on Wave 3 completion)* - [ ] 16.2-06-PLAN.md — Unit tests: resave contract at every layer, strip-and-report and notices, policy cross-check corpus (both policies, identical copies), category strip, full Go and JS coverage, Postgres tests for a Docker host, phase gate scripts/check-phase16.2.sh, validation map +### Phase 16.3: Backend admin personal API tokens with scopes (INSERTED) + +**Goal:** Backend users can create personal API tokens with a scope they pick at creation time (for example Journal only, or system-wide; later read-only Payment Gateway), so an agent or integration can call the admin and plugin APIs as that backend user, with no more access than the token's scope and the user's own permissions allow. This is the successor of Apparatus `PersonalApiToken` (todo `backend-admin-api-tokens.md`, note `apparatus-dissolved-into-framework.md`) and reverses the Phase 15 D-15 rule that Journal writes accept only a backend JWT. +**Requirements**: TBD +**Depends on:** Phase 9, Phase 10, Phase 15 +**Repos:** `summercms.go` (bouncer guard, token model and migration, scope registry, admin SPA panel, CLI); `sm-journal-plugin` to register its scope and accept tokens on its write routes; host applications only for the version bump +**Constraints from explore (2026-10-10):** + - Tokens keep the `g15_` prefix and are stored only as a hash. The rest of the format can change, and WinterCMS Apparatus tokens are not migrated. + - The user picks the scope when creating a token. Plugins register their own scopes. Scope design (names, read-only variants, system-wide) is settled in discuss-phase. + - Tokens are managed in two places, as in WinterCMS: a panel on the admin SPA backend user form (create, show once, revoke) and a `summer` CLI command. +**Success Criteria** (what must be TRUE): + + 1. The `backend` guard accepts a valid, unexpired, unrevoked `g15_` token as well as the backend JWT, and the request runs as the token's backend user. + 2. A request outside the token's scope is refused even when the user's role would allow it, and a token never grants more than its owner's permissions. + 3. A backend user can create, list and revoke their own tokens in the admin SPA. The plaintext token is shown once. A CLI command does the same for any backend user. + 4. The Journal API accepts a Journal-scoped token for writes, so an agent can manage blog posts as a backend author. + 5. Module READMEs and `docs/` cover the token API, scopes and CLI commands. + 6. The new code has unit tests, delivered in the phase's last plan. +**Plans:** 0 plans + +Plans: +- [ ] TBD (run /msd-plan-phase 16.3 to break down) + ### Phase 17: Blog companions **Goal:** The sitemap, menu and FAQ plugins run on SummerCMS as shared `sm-*-plugin` repos, so a blog site can manage its menus, FAQs and sitemap in the admin again instead of hardcoding them in the Nuxt app. diff --git a/.planning/STATE.md b/.planning/STATE.md index b20ef3d..6332876 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -4,13 +4,13 @@ milestone: v1.0 current_phase: "16.2" current_phase_name: Plugin-provided field types and the Blog Editor formwidget status: executing -stopped_at: Completed 16.2-05-PLAN.md -last_updated: "2026-10-10T12:01:49.546Z" +stopped_at: Phase 16.3 context gathered +last_updated: "2026-10-10T13:33:03.540Z" last_activity: 2026-10-10 last_activity_desc: Phase 16.2 execution started -state_head: 85fe541b03885fbb34c7d66e7ed9bbdfc583ffbe +state_head: c07da3912b1cc4b5d112200f7af16c5ad3061d02 progress: - total_phases: 34 + total_phases: 35 completed_phases: 13 total_plans: 157 completed_plans: 152 @@ -232,6 +232,7 @@ Progress: [██████████] 100% - Phase 18.1 inserted after Phase 18: Payment Gateway Subscriptions (split from Phase 18 per 18-CONTEXT D-01) - Phase 16.1 inserted after Phase 16: Journal admin urgent fixes: relation search, list state, post form content and excerpt (found on UAT) (URGENT) - Phase 16.2 inserted after Phase 16.1: Plugin-provided field types and the Blog Editor formwidget +- Phase 16.3 inserted after Phase 16: Backend admin personal API tokens with user-selected scopes (Journal agent writes as backend author); successor of Apparatus PersonalApiToken (URGENT) ### Decisions @@ -747,6 +748,6 @@ Items acknowledged and carried forward from previous milestone close: ## Session Continuity -Last session: 2026-10-10T11:36:12.850Z -Stopped at: Completed 16.2-05-PLAN.md -Resume file: None +Last session: 2026-10-10T13:33:02.885Z +Stopped at: Phase 16.3 context gathered +Resume file: .planning/phases/16.3-backend-admin-personal-api-tokens-with-scopes/16.3-CONTEXT.md diff --git a/.planning/phases/16.1-journal-admin-urgent-fixes-relation-search-list-state-post-f/.gitkeep b/.planning/phases/16.1-journal-admin-urgent-fixes-relation-search-list-state-post-f/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/.planning/phases/16.1-journal-admin-urgent-fixes-relation-search-list-state-post-f/.gitkeep @@ -0,0 +1 @@ + diff --git a/.planning/phases/16.2-plugin-provided-field-types-and-the-blog-editor-formwidget/.gitkeep b/.planning/phases/16.2-plugin-provided-field-types-and-the-blog-editor-formwidget/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/.planning/phases/16.2-plugin-provided-field-types-and-the-blog-editor-formwidget/.gitkeep @@ -0,0 +1 @@ + diff --git a/.planning/phases/16.3-backend-admin-personal-api-tokens-with-scopes/.gitkeep b/.planning/phases/16.3-backend-admin-personal-api-tokens-with-scopes/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/.planning/phases/16.3-backend-admin-personal-api-tokens-with-scopes/.gitkeep @@ -0,0 +1 @@ + diff --git a/.planning/phases/18.1-payment-gateway-subscriptions/.gitkeep b/.planning/phases/18.1-payment-gateway-subscriptions/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/.planning/phases/18.1-payment-gateway-subscriptions/.gitkeep @@ -0,0 +1 @@ + diff --git a/.planning/state.json b/.planning/state.json index f53cbd9..d6a85d6 100644 --- a/.planning/state.json +++ b/.planning/state.json @@ -144,5 +144,5 @@ "label": "Advance to the next step", "reason": "Phase 16.2 of 34 · executing" }, - "updated_at": "2026-10-10T11:36:07.796Z" + "updated_at": "2026-10-10T12:47:48.195Z" } diff --git a/.planning/todos/pending/backend-admin-api-tokens.md b/.planning/todos/pending/backend-admin-api-tokens.md index 5ecf145..58c731e 100644 --- a/.planning/todos/pending/backend-admin-api-tokens.md +++ b/.planning/todos/pending/backend-admin-api-tokens.md @@ -1,10 +1,12 @@ --- -title: Backend admin personal API tokens (deferred Apparatus PersonalApiToken) +title: Backend admin personal API tokens (Phase 16.3) date: 2026-09-28 -priority: low +priority: high area: summercms.go admin auth --- Apparatus provides personal API tokens for backend admins (`PersonalApiToken` model, `TokenAuthenticate` + `ForceJsonResponse` middleware, token create/revoke on the backend user form). Nothing in Płytarium calls it, so it is deferred past v1. The Phase 9 `backend` guard already accepts `Authorization: Bearer` for CLI and tests. Revisit when a Golem15 project needs scripted access to the admin API. See `.planning/notes/apparatus-dissolved-into-framework.md`. + +**2026-10-10:** Promoted to Phase 16.3 (scoped tokens, Journal agent use case). No migration of Apparatus tokens.