docs(16.3): verification passed after admin gate fix

Re-verify after d1b043a: SC-6 closed, check-phase16.3.sh --all green, score 6/6. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-11 14:08:06 +02:00
parent d1b043a361
commit 5913337cda
2 changed files with 199 additions and 7 deletions
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -3,11 +3,11 @@ msd_state_version: "1.0"
 milestone: v1.0
 current_phase: "16.3"
 current_phase_name: Backend admin personal API tokens with scopes
-status: executing
-stopped_at: Completed 16.3-04-PLAN.md
-last_updated: "2026-10-11T11:42:00.000Z"
+status: verified
+stopped_at: Phase 16.3 verification passed (6/6)
+last_updated: "2026-10-11T12:06:35.000Z"
 last_activity: 2026-10-11
-last_activity_desc: Completed 16.3-04 unit tests, Postgres suites and phase gate
+last_activity_desc: "16.3-VERIFICATION.md: passed (6/6) after d1b043a + gate --all green"
 state_head: e565062479ec6289d8af31a41afb40c2dac0b557
 progress:
  total_phases: 40
@@ -29,10 +29,10 @@ See: .planning/PROJECT.md (updated 2026-09-16)

 ## Current Position

-Phase: 16.3 (Backend admin personal API tokens with scopes) — EXECUTING
+Phase: 16.3 (Backend admin personal API tokens with scopes) — VERIFIED
 Plan: 4 of 4
-Status: Plans complete — ready for verify-work
-Last activity: 2026-10-11 — Completed 16.3-04 (unit tests, Postgres suites, phase gate)
+Status: Verification passed (6/6) — see 16.3-VERIFICATION.md
+Last activity: 2026-10-11 — Re-verify after d1b043a; check-phase16.3.sh --all green

 Progress: [█████░░░░░] 48%

--- a/.planning/phases/16.3-backend-admin-personal-api-tokens-with-scopes/16.3-VERIFICATION.md
+++ b/.planning/phases/16.3-backend-admin-personal-api-tokens-with-scopes/16.3-VERIFICATION.md
@@ -0,0 +1,192 @@
+---
+phase: 16.3-backend-admin-personal-api-tokens-with-scopes
+verified: 2026-10-11T12:06:35Z
+status: passed
+score: 6/6 must-haves verified
+covered_files:
+  - .planning/phases/16.3-backend-admin-personal-api-tokens-with-scopes/16.3-01-PLAN.md
+  - .planning/phases/16.3-backend-admin-personal-api-tokens-with-scopes/16.3-01-SUMMARY.md
+  - .planning/phases/16.3-backend-admin-personal-api-tokens-with-scopes/16.3-02-PLAN.md
+  - .planning/phases/16.3-backend-admin-personal-api-tokens-with-scopes/16.3-02-SUMMARY.md
+  - .planning/phases/16.3-backend-admin-personal-api-tokens-with-scopes/16.3-03-PLAN.md
+  - .planning/phases/16.3-backend-admin-personal-api-tokens-with-scopes/16.3-03-SUMMARY.md
+  - .planning/phases/16.3-backend-admin-personal-api-tokens-with-scopes/16.3-04-PLAN.md
+  - .planning/phases/16.3-backend-admin-personal-api-tokens-with-scopes/16.3-04-SUMMARY.md
+  - .planning/phases/16.3-backend-admin-personal-api-tokens-with-scopes/16.3-VALIDATION.md
+  - .planning/phases/16.3-backend-admin-personal-api-tokens-with-scopes/16.3-UI-SPEC.md
+  - .planning/phases/16.3-backend-admin-personal-api-tokens-with-scopes/16.3-REVIEW.md
+  - .planning/phases/16.3-backend-admin-personal-api-tokens-with-scopes/16.3-REVIEW-DISPOSITION.md
+  - modules/pact/capabilities.go
+  - modules/bouncer/context.go
+  - modules/bouncer/context_test.go
+  - modules/party/registry.go
+  - modules/party/registry_test.go
+  - modules/lagoon/backend_admin_migrations.go
+  - modules/lagoon/backend_admin_migrations_test.go
+  - modules/cabana/api_tokens.go
+  - modules/cabana/token_scopes.go
+  - modules/cabana/token_guard.go
+  - modules/cabana/account_tokens.go
+  - modules/cabana/token_commands.go
+  - modules/cabana/contracts.go
+  - modules/cabana/http.go
+  - modules/cabana/registry.go
+  - modules/cabana/admin_openapi.go
+  - modules/cabana/example_tokens_test.go
+  - modules/cabana/token_smoke_test.go
+  - modules/cabana/token_postgres_smoke_test.go
+  - modules/cabana/token_scopes_test.go
+  - modules/cabana/api_tokens_test.go
+  - modules/cabana/token_guard_test.go
+  - modules/cabana/token_routes_test.go
+  - modules/cabana/token_postgres_test.go
+  - modules/cabana/account_tokens_test.go
+  - modules/cabana/token_commands_test.go
+  - modules/cabana/phase10_csrf_test.go
+  - modules/cabana/README.md
+  - modules/pact/README.md
+  - modules/bouncer/README.md
+  - modules/party/README.md
+  - modules/lagoon/README.md
+  - cmd/summer/runtime.go
+  - admin/src/components/account/ApiTokensPanel.vue
+  - admin/src/components/account/ApiTokenCreateDialog.vue
+  - admin/src/views/AccountView.vue
+  - admin/tests/account/ApiTokensPanel.test.ts
+  - admin/tests/account/ApiTokenCreateDialog.test.ts
+  - admin/openapi/admin.json
+  - admin/src/api/schema.d.ts
+  - docs/backend/users-and-permissions.md
+  - docs/services/authentication.md
+  - docs/console/setup-and-maintenance.md
+  - docs/console/introduction.md
+  - docs/plugins/registration.md
+  - docs/examples/blog/token_scopes.go
+  - scripts/check-phase16.3.sh
+covered_digest: "v2:sha256:45cf7b202d293412c7384f25aa1c456492f6571adae14b0413307c48022a218a"
+behavior_unverified: 0
+overrides_applied: 0
+re_verification:
+  previous_status: gaps_found
+  previous_score: 5/6
+  gaps_closed:
+    - "SC-6 / phase gate: d1b043a retargeted ApiTokensPanel tests; orchestrator re-ran check-phase16.3.sh --all → Phase 16.3 gate passed (GATE_EXIT=0)"
+  gaps_remaining: []
+  regressions: []
+---
+
+# Phase 16.3: Backend admin personal API tokens with scopes Verification Report
+
+**Phase 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 and reverses the Phase 15 D-15 rule that Journal writes accept only a backend JWT.
+**Verified:** 2026-10-11T12:06:35Z
+**Status:** passed
+**Re-verification:** Yes — after SC-6 gap closure (`d1b043a`)
+
+ROADMAP Success Criteria (SC-1..SC-6) are the contract truths. REQUIREMENTS.md has no phase-16.3-specific IDs (AUTH-03 is an earlier Płytarium-era checkbox). Plan frontmatter truths expand the same SCs; they were checked as supporting evidence, not as a separate score denominator.
+
+WR-01 / WR-02 from code review are dispositioned fixed (a955d2a / cb4b0a9). SC-6 stale-test gap closed in `d1b043a`. No SECURITY.md yet (secure-phase pending). Tag v0.1.21 exists; Journal `go.mod` requires `v0.1.21`.
+
+## Goal Achievement
+
+### Observable Truths
+
+| # | Truth | Status | Evidence |
+|---|-------|--------|----------|
+| 1 | SC-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 | ✓ VERIFIED | `newCompositeGuard` routes `Bearer g15_` to token lookup; else JWT+cookie. `principal.Scope = limit`. Gate go + postgres `TestBackendTokenPostgres` PASS |
+| 2 | SC-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 | ✓ VERIFIED | `Allows` → `allowsUnderScope` before superuser / empty-list. `TestAllowsScope`, `TestTokenRouteGates`, Journal write matrix on Postgres PASS |
+| 3 | SC-3: A backend user can create, list and revoke their own tokens in the admin SPA; plaintext shown once; CLI does the same for any backend user | ✓ VERIFIED | AccountView → ApiTokensPanel; create dialog show-once + clipboard backstops (vitest). `TestAccountTokens`, `TestTokenCommands` on Postgres PASS |
+| 4 | SC-4: The Journal API accepts a Journal-scoped token for writes | ✓ VERIFIED | `journal` / `journal:read` scopes; `ResolveBackend` with cover `golem15.journal.*`. Postgres `TestJournalTokens` matrix PASS |
+| 5 | SC-5: Module READMEs and `docs/` cover the token API, scopes and CLI commands | ✓ VERIFIED | Module READMEs + backend/auth/console/plugin docs. Gate docs stage PASS |
+| 6 | SC-6: The new code has unit tests, delivered in the phase's last plan | ✓ VERIFIED | `d1b043a` adds disabled-submit case and retargets 422 scopes (select scope first). Re-verify: panel 15/15 + dialog 19/19 PASS; `check-phase16.3.sh admin` PASS (1252 vitest); orchestrator `--all` → `Phase 16.3 gate passed` (GATE_EXIT=0) |
+
+**Score:** 6/6 truths verified (0 present, behavior-unverified)
+
+### Deferred Items
+
+None.
+
+### Required Artifacts
+
+| Artifact | Expected | Status | Details |
+|----------|----------|--------|---------|
+| `modules/pact/capabilities.go` | `TokenScope`, `HasTokenScopes` | ✓ VERIFIED | |
+| `modules/bouncer/context.go` | `ScopeLimit` on `Principal` | ✓ VERIFIED | |
+| `modules/lagoon/backend_admin_migrations.go` | `202610110001_backend_api_tokens` | ✓ VERIFIED | |
+| `modules/cabana/api_tokens.go` | mint/hash/`APITokenPrefix`/`issueAPIToken` | ✓ VERIFIED | |
+| `modules/cabana/token_scopes.go` | compile, `allowsUnderScope` | ✓ VERIFIED | |
+| `modules/cabana/token_guard.go` | composite guard, `ResolveBackend` | ✓ VERIFIED | |
+| `modules/cabana/account_tokens.go` | four account token handlers | ✓ VERIFIED | |
+| `modules/cabana/token_commands.go` | `admin:token:*` | ✓ VERIFIED | |
+| `admin/src/components/account/ApiTokensPanel.vue` | list/create/revoke card | ✓ VERIFIED | |
+| `admin/src/components/account/ApiTokenCreateDialog.vue` | two-step show-once | ✓ VERIFIED | WR-02 `canSubmit` |
+| `../sm-journal-plugin/token_scopes.go` | journal scopes | ✓ VERIFIED | Sibling repo |
+| `../sm-journal-plugin/journal_api_tokens_test.go` | write matrix | ✓ VERIFIED | |
+| `scripts/check-phase16.3.sh` | phase gate | ✓ VERIFIED | `--all` green after `d1b043a` |
+| Plan 01–04 artifact lists | `verify.artifacts` | ✓ VERIFIED | all_passed |
+
+### Key Link Verification
+
+| From | To | Via | Status | Details |
+|------|----|-----|--------|---------|
+| `modules/cabana/http.go` | composite guard | `newCompositeGuard` + `guards.Register(..., "backend", …)` | ✓ WIRED | Cookie-less `backendResolver` published |
+| `modules/cabana/token_guard.go` | `bouncer.Principal.Scope` | `principal.Scope = limit` | ✓ WIRED | |
+| `modules/cabana/contracts.go` `Allows` | `allowsUnderScope` | before superuser / empty list | ✓ WIRED | |
+| account API + CLI | `issueAPIToken` | shared mint path | ✓ WIRED | |
+| `token_commands.go` | `party.Activated` | `app.Lookup[party.Activated]()` | ✓ WIRED | |
+| Journal `auth.go` | `cabana.ResolveBackend` | cover `golem15.journal.*` | ✓ WIRED | |
+| AccountView | ApiTokensPanel | import + render | ✓ WIRED | |
+
+### Data-Flow Trace (Level 4)
+
+| Artifact | Data Variable | Source | Produces Real Data | Status |
+|----------|---------------|--------|--------------------|--------|
+| ApiTokensPanel list | token rows | `GET /account/tokens` | Yes | ✓ FLOWING |
+| Create dialog plaintext | `plaintext` ref | `POST /account/tokens` 201 | Yes; cleared on Done / Esc-confirm | ✓ FLOWING |
+| CLI create stdout | plaintext | `issueAPIToken` | Yes | ✓ FLOWING |
+| Journal writes | principal | `ResolveBackend` | Yes | ✓ FLOWING |
+
+### Behavioral Spot-Checks
+
+| Behavior | Command | Result | Status |
+|----------|---------|--------|--------|
+| Phase gate (full) | `bash scripts/check-phase16.3.sh --all` (orchestrator) | `Phase 16.3 gate passed`, GATE_EXIT=0 | ✓ PASS |
+| Gate admin (re-verify) | `bash scripts/check-phase16.3.sh admin` | `phase16.3 admin passed` (1252 vitest) | ✓ PASS |
+| SPA panel + dialog | `vitest … ApiTokensPanel + ApiTokenCreateDialog` | 34/34 PASS | ✓ PASS |
+| Gate go / docs / postgres | prior verify + orchestrator `--all` | PASS | ✓ PASS |
+
+### Probe Execution
+
+| Probe | Command | Result | Status |
+|-------|---------|--------|--------|
+| — | — | No phase probes declared | SKIP |
+
+### Requirements Coverage
+
+| Requirement | Source Plan | Description | Status | Evidence |
+|-------------|-------------|-------------|--------|----------|
+| SC-1 | 01, 04 | Composite guard + `g15_` | ✓ SATISFIED | |
+| SC-2 | 01, 04 | Scope ≤ owner | ✓ SATISFIED | |
+| SC-3 | 01, 02, 04 | SPA + CLI token CRUD | ✓ SATISFIED | |
+| SC-4 | 03, 04 | Journal-scoped writes | ✓ SATISFIED | |
+| SC-5 | 01, 02, 03 | Docs / READMEs | ✓ SATISFIED | |
+| SC-6 | 04 | Unit tests + phase gate | ✓ SATISFIED | `d1b043a` + `--all` green |
+
+### Anti-Patterns Found
+
+| File | Line | Pattern | Severity | Impact |
+|------|------|---------|----------|--------|
+| — | — | Prior stale 422 case | resolved | Fixed in `d1b043a` |
+| IN-01 / IN-02 (REVIEW) | — | Info findings open | ℹ️ Info | Not goal blockers |
+
+### Human Verification Required
+
+None. Clipboard / show-once behavior is covered by SPA unit backstops (`ApiTokenCreateDialog` plaintext lifetime + copy success/failure cases; panel dialog rules). VALIDATION.md’s real-browser clipboard row remains an optional nicety, not a must-have for this verdict. No SECURITY.md in this phase (secure-phase separate).
+
+### Gaps Summary
+
+No remaining gaps. Previous SC-6 failure closed by `d1b043a` (disabled-submit assertion + 422 path with a selected scope); full phase gate green.
+
+---
+
+_Verified: 2026-10-11T12:06:35Z_
+_Verifier: Claude (msd-verifier)_