283 lines
16 KiB
Markdown
283 lines
16 KiB
Markdown
---
|
|
phase: 10.1-runtime-admin-extension-point
|
|
plan: 01
|
|
subsystem: api
|
|
tags: [go, cabana, pact, boardwalk, html-template, x-net-html, openapi, swag, admin]
|
|
|
|
requires:
|
|
- phase: 10-admin-vue-spa
|
|
provides: cabana admin API, requireAjax CSRF guard, boardwalk SPA serving, typed admin OpenAPI pipeline, conformance and inventory tests
|
|
- phase: 10.2-nest-framework-packages-under-modules-and-write-run-docs
|
|
provides: modules/ layout and module README rules
|
|
provides:
|
|
- pact contracts AdminClientAssets, AdminAction, AdminActionInput, AdminActionResult, HasAdminActions, AdminPartialData
|
|
- fields.yaml type widget (widget, action, fill) and type partial (path); config_list.yaml headerPartial; registered toolbar.buttons names
|
|
- POST {prefix}/api/v1/{vendor}/{plugin}/{controller}/widgets/{field} and .../toolbar/{action}
|
|
- GET {prefix}/api/v1/{vendor}/{plugin}/{controller}/partials/{name} returning an allowlisted node tree
|
|
- GET {prefix}/assets/{vendor}/{plugin}/{file...} exact-allowlist plugin asset route with SPA fall-through
|
|
- list and form schema keys assets, toolbarActions, headerPartial and field keys widget, action, actionLabel, fill, path
|
|
- exported boardwalk.ContentType and boardwalk.SetSecurityHeaders
|
|
- typed OpenAPI operations and schemas (AdminActionRequest, AdminActionResult, ControllerAssets, ToolbarAction, PartialNode, PartialView)
|
|
affects: [10.1-02 SPA extension seams, 10.1-03 Albums extension, 10.1-04 unit tests and gate, 14 Discogs]
|
|
|
|
actuals:
|
|
tokens: 39500
|
|
tasks: 3
|
|
commits: 3
|
|
plan_head_before: 9b98d8409fcfc25e815983ced43853f21ae3be64
|
|
plan_head_after: 771d2ccce0bf3357d4be1d200bebe906f5a6bb70
|
|
|
|
tech-stack:
|
|
added: [golang.org/x/net/html (promoted from indirect to direct, no new module)]
|
|
patterns:
|
|
- "Cabana-owned action routes: plugins register Go Run functions; cabana owns the route, CSRF, permissions and record scope"
|
|
- "Single action namespace: toolbar.buttons and widget action: both resolve through CompiledController.Actions; create and delete are reserved"
|
|
- "Exact-key asset allowlist built at boot, miss falls through to the SPA handler"
|
|
- "Server-sanitized partials: html/template Clone per request, ParseFragment, allowlist walk into JSON nodes with caps"
|
|
|
|
key-files:
|
|
created:
|
|
- modules/cabana/extension.go
|
|
- modules/cabana/actions.go
|
|
- modules/cabana/plugin_assets.go
|
|
- modules/cabana/partial_render.go
|
|
modified:
|
|
- modules/pact/capabilities.go
|
|
- modules/pact/README.md
|
|
- modules/boardwalk/boardwalk.go
|
|
- modules/boardwalk/README.md
|
|
- modules/cabana/form_schema.go
|
|
- modules/cabana/list_schema.go
|
|
- modules/cabana/schema_types.go
|
|
- modules/cabana/contracts.go
|
|
- modules/cabana/registry.go
|
|
- modules/cabana/messages.go
|
|
- modules/cabana/settings.go
|
|
- modules/cabana/http.go
|
|
- modules/cabana/admin_openapi.go
|
|
- modules/cabana/README.md
|
|
- modules/cabana/openapi_conformance_test.go
|
|
- modules/cabana/security_coverage_test.go
|
|
- admin/openapi/admin.json
|
|
- admin/src/api/schema.d.ts
|
|
- go.mod
|
|
- ../fonoteka.go/plugins/golem15/fonoteka/admin_phase09_security_test.go
|
|
- ../fonoteka.go/plugins/golem15/fonoteka/admin_collections_test.go
|
|
|
|
key-decisions:
|
|
- "An action Label containing :: is treated as a phrase key and must resolve at boot; other labels are literal button text"
|
|
- "A toolbar action body must be {} exactly: record_id or values (even an empty values object) is a 422"
|
|
- "The partial view-model guard also refuses types containing html/template trusted content types (template.HTML and siblings), enforcing the plan's no-raw-HTML prohibition"
|
|
- "Partial and asset href/src URLs with whitespace or control characters are refused, since browsers strip them and could turn /<tab>/host into a protocol-relative URL"
|
|
- "The empty-body POST is a 422 like any malformed body; the SPA sends {}"
|
|
|
|
patterns-established:
|
|
- "compileExtension runs after BindWritableFields and owns every controller-level extension check (actions, widgets, assets, partials)"
|
|
- "Per-request locale for action messages and partial trans through towel.WithLocale(schemaLocale(...))"
|
|
|
|
requirements-completed: [ADMIN-07]
|
|
|
|
coverage:
|
|
- id: D1
|
|
description: "Widget field runs its registered action through POST .../widgets/{field}; the response fill holds only the declared fill keys"
|
|
requirement: ADMIN-07
|
|
verification:
|
|
- kind: integration
|
|
ref: "modules/cabana/openapi_conformance_test.go#TestPhase10OpenAPIConformance/POST_/{vendor}/{plugin}/{controller}/widgets/{field}"
|
|
status: pass
|
|
- kind: unit
|
|
ref: "modules/cabana/phase10_csrf_test.go#TestPhase10CSRF"
|
|
status: pass
|
|
- kind: unit
|
|
ref: "modules/cabana/security_coverage_test.go#TestPhase09PermissionMatrix"
|
|
status: pass
|
|
human_judgment: false
|
|
- id: D2
|
|
description: "Controller JS/CSS served at {prefix}/assets/{vendor}/{plugin}/... with explicit MIME, nosniff, CSP, CORP, no-cache and ETag; schema URLs carry ?v=; undeclared files fall through to the SPA 404"
|
|
requirement: ADMIN-07
|
|
verification:
|
|
- kind: integration
|
|
ref: "modules/cabana/openapi_conformance_test.go#TestPhase10OpenAPIConformance/GET_/{vendor}/{plugin}/{controller}/schema/list (assertPluginAsset)"
|
|
status: pass
|
|
- kind: integration
|
|
ref: "../fonoteka.go/plugins/golem15/fonoteka#TestPhase10TracerSPA"
|
|
status: pass
|
|
human_judgment: false
|
|
- id: D3
|
|
description: "Registered toolbar actions: toolbar.buttons resolves create, delete and registered names; toolbarActions is permission-filtered; POST .../toolbar/{action} runs the action"
|
|
requirement: ADMIN-07
|
|
verification:
|
|
- kind: integration
|
|
ref: "modules/cabana/openapi_conformance_test.go#TestPhase10OpenAPIConformance/POST_/{vendor}/{plugin}/{controller}/toolbar/{action}"
|
|
status: pass
|
|
- kind: unit
|
|
ref: "modules/cabana/messages_test.go#TestPhase10Toolbar"
|
|
status: pass
|
|
- kind: unit
|
|
ref: "modules/cabana/list_schema_test.go#TestListSchemaRejects"
|
|
status: pass
|
|
human_judgment: false
|
|
- id: D4
|
|
description: "Header and form partials render through html/template into an allowlisted, capped node tree served by GET .../partials/{name}"
|
|
requirement: ADMIN-07
|
|
verification:
|
|
- kind: integration
|
|
ref: "modules/cabana/openapi_conformance_test.go#TestPhase10OpenAPIConformance/GET_/{vendor}/{plugin}/{controller}/partials/{name}"
|
|
status: pass
|
|
- kind: unit
|
|
ref: "modules/cabana/form_schema_test.go#TestFormSchemaRejects"
|
|
status: pass
|
|
human_judgment: false
|
|
- id: D5
|
|
description: "Sanitizer edge behaviour (dropped script/svg/on*/style/id, javascript: and // URLs, 64 KiB, 2000-node and depth-32 caps) and the model-type guard have dedicated unit tests"
|
|
verification: []
|
|
human_judgment: true
|
|
rationale: "Checked here only with a throwaway probe; the named sanitizer, asset and action unit tests (TestPhase101*) are plan 10.1-04's scope per CLAUDE.md rule 3"
|
|
- id: D6
|
|
description: "OpenAPI document and generated TypeScript types cover every new admin API route"
|
|
requirement: ADMIN-07
|
|
verification:
|
|
- kind: other
|
|
ref: "scripts/check-admin-openapi.sh --check"
|
|
status: pass
|
|
- kind: unit
|
|
ref: "modules/cabana/phase09_contract_test.go#TestPhase09ContractInventory"
|
|
status: pass
|
|
- kind: other
|
|
ref: "npm --prefix admin run typecheck"
|
|
status: pass
|
|
human_judgment: false
|
|
|
|
duration: 25min
|
|
completed: 2026-09-28
|
|
status: complete
|
|
---
|
|
|
|
# Phase 10.1 Plan 01: Runtime admin extension point (framework Go) Summary
|
|
|
|
**cabana-owned widget, toolbar and partial routes backed by new pact contracts, an exact-allowlist plugin asset route under the admin prefix, and an html/template partial renderer whose output is sanitized with x/net/html into a capped JSON node tree, all typed in the admin OpenAPI document and proven on the acme conformance fixture**
|
|
|
|
## Performance
|
|
|
|
- **Duration:** 25 min
|
|
- **Started:** 2026-09-28T21:28:17Z
|
|
- **Completed:** 2026-09-28T21:52:58Z
|
|
- **Tasks:** 3
|
|
- **Files modified:** 31 in summercms.go, 2 in fonoteka.go
|
|
|
|
## Accomplishments
|
|
|
|
- Six pact contracts (`AdminClientAssets`, `AdminAction`, `AdminActionInput`, `AdminActionResult`, `HasAdminActions`, `AdminPartialData`) that plans 02 and 03 build against.
|
|
- `type: widget` fields with boot checks: the tag must start with the plugin's `{vendor}-{plugin}-` prefix and must not be a reserved name, the action must be registered, fill keys must be writable scalar fields of the same form, and the controller must declare JS. `POST .../widgets/{field}` loads the record through `FormExtendQuery` without a row lock and filters fill keys on the server.
|
|
- Registered toolbar actions share one namespace with widget actions, with `create` and `delete` reserved. `toolbarActions` in the list schema is filtered by permission, and `POST .../toolbar/{action}` accepts only `{}`.
|
|
- Plugin JS/CSS is read and sha256-hashed at boot and served by exact key with `boardwalk.SetSecurityHeaders`, `Cross-Origin-Resource-Policy: same-origin`, `no-cache` and an ETag. List and form schemas carry `assets` URLs with `?v=`. A lookup miss falls through to the SPA, so dist assets still load.
|
|
- `type: partial` is supported and `headerPartial` is added. Templates are parsed at boot and cloned for each request. Output goes through x/net/html `ParseFragment` and a tag, attribute and URL allowlist, with caps of 64 KiB, 2000 nodes and depth 32. `GET .../partials/{name}` with an optional scoped `?id=` serves the result.
|
|
- OpenAPI regenerated with the recursive `cabana.PartialNode`. Route inventories were updated in both repositories, and the acme conformance fixture exercises widget, toolbar, both partials and both assets end to end.
|
|
|
|
## Task Commits
|
|
|
|
summercms.go:
|
|
1. **Task 1: widget action tracer** - `f928194` (feat)
|
|
2. **Task 2: controller assets and toolbar actions** - `8b1cb24` (feat)
|
|
3. **Task 3: header and form partials** - `771d2cc` (feat)
|
|
|
|
fonoteka.go (route inventory, separate repository):
|
|
1. `dcb64c9` test(10.1-01): expect the framework widget action route
|
|
2. `75ab47f` test(10.1-01): expect the framework toolbar action route
|
|
3. `be3fbf4` test(10.1-01): expect the framework partial route and new partial error
|
|
|
|
## Files Created/Modified
|
|
|
|
- `modules/pact/capabilities.go`: the six extension contracts
|
|
- `modules/cabana/extension.go`: boot validation of actions, widgets, client assets and partials
|
|
- `modules/cabana/actions.go`: widget and toolbar handlers, strict body decode, `readScopedRecord`, fill filter
|
|
- `modules/cabana/plugin_assets.go`: exact-allowlist asset handler and schema URL builder
|
|
- `modules/cabana/partial_render.go`: template parse and render, allowlist walk, caps, view-model guard, partial handler
|
|
- `modules/cabana/form_schema.go`, `list_schema.go`, `settings.go`: widget, partial, `headerPartial` and toolbar YAML rules
|
|
- `modules/cabana/schema_types.go`, `contracts.go`, `registry.go`, `messages.go`, `http.go`, `admin_openapi.go`: types, registry wiring, label checks, routes, annotations
|
|
- `modules/boardwalk/boardwalk.go`: exported `ContentType`, `SetSecurityHeaders`
|
|
- `admin/openapi/admin.json`, `admin/src/api/schema.d.ts`: regenerated
|
|
- `admin/tests/fixtures/*.json`: `assets` and `toolbarActions` keys for the typed fixtures
|
|
- READMEs of pact, cabana and boardwalk
|
|
|
|
## Decisions Made
|
|
|
|
- An action label containing `::` is a phrase key and must resolve at boot. Any other label is literal text.
|
|
- A toolbar action body must be exactly `{}`. A `record_id` or `values` key is a 422, so a toolbar action can never become a record lookup.
|
|
- The partial view-model guard also refuses types that contain html/template's trusted content types (`template.HTML` and its siblings). This enforces the plan's "no raw HTML string marked safe" rule at the type level. The allowlist still backs it up for values stored behind `any`.
|
|
- Any href or src containing whitespace or control characters is refused. Browsers strip those characters, so `/<tab>/host` would otherwise become a protocol-relative URL.
|
|
|
|
## Deviations from Plan
|
|
|
|
### Auto-fixed Issues
|
|
|
|
**1. [Rule 3 - Blocking] Renamed the new scalar helper to avoid a collision**
|
|
- **Found during:** Task 1
|
|
- **Issue:** `scalarValue` already exists in `query.go` (it converts a filter jsonScalar), so the package did not compile.
|
|
- **Fix:** Named the new predicate `isJSONScalar`.
|
|
- **Files modified:** modules/cabana/actions.go
|
|
- **Committed in:** f928194
|
|
|
|
**2. [Rule 3 - Blocking] Updated the unsafe-route pins in TestPhase10CSRF and TestPhase10Coverage**
|
|
- **Found during:** Tasks 1 and 2
|
|
- **Issue:** Both tests pin the exact set of mounted unsafe routes (9, besides login). The plan's inventory step named only `phase09Routes` and `phase09ProtectedCalls`.
|
|
- **Fix:** Added each new POST to the pinned list and raised the count to 10, then 11. The CSRF walk still exercises every new route automatically.
|
|
- **Files modified:** modules/cabana/phase10_csrf_test.go, modules/cabana/phase10_coverage_test.go
|
|
- **Committed in:** f928194, 8b1cb24
|
|
|
|
**3. [Rule 3 - Blocking] Updated the exact-JSON list schema expectations**
|
|
- **Found during:** Task 2
|
|
- **Issue:** `TestListSchemaCompile/Empty/Single/Filter` compare whole `ListSchema` JSON, and `toolbarActions` and `assets` are always emitted.
|
|
- **Fix:** Inserted `"toolbarActions":[],"assets":{"scripts":[],"styles":[]}` after `toolbarButtons` in the expected strings.
|
|
- **Files modified:** modules/cabana/list_schema_test.go
|
|
- **Committed in:** 8b1cb24
|
|
|
|
**4. [Rule 3 - Blocking] Updated a fonoteka test that pinned the Phase 9 partial rejection text**
|
|
- **Found during:** Task 3 (full fonoteka suite)
|
|
- **Issue:** `TestCollectionsAdminRejectsPartial` expected "type partial is not supported", which the plan removes.
|
|
- **Fix:** It now expects "type partial needs a path". A bare legacy `type: partial` still fails boot, for the new reason.
|
|
- **Files modified:** ../fonoteka.go/plugins/golem15/fonoteka/admin_collections_test.go
|
|
- **Committed in:** be3fbf4 (fonoteka.go)
|
|
|
|
**5. [Rule 2 - Missing critical] Extra URL and view-model hardening**
|
|
- **Found during:** Task 3
|
|
- **Issue:** The plan's URL rule (one leading `/`) is bypassable with tab or newline characters. Its model-type guard does not cover `template.HTML` fields.
|
|
- **Fix:** `safePartialURL` refuses whitespace and control characters. `refusedViewModel` refuses trusted template content types.
|
|
- **Files modified:** modules/cabana/partial_render.go
|
|
- **Committed in:** 771d2cc
|
|
|
|
---
|
|
|
|
**Total deviations:** 5 auto-fixed (4 blocking, 1 missing critical)
|
|
**Impact on plan:** All were needed to keep pinned tests green or to close a security gap. No scope creep.
|
|
|
|
## Issues Encountered
|
|
|
|
- `go.sum` did not change; `go mod tidy` only moved `golang.org/x/net` to the direct block. `go.sum` is listed in the plan's files but needed no edit.
|
|
- Task 1 and Task 2 ran the plan's targeted fonoteka tests. The full fonoteka suite ran at Task 3 and surfaced deviation 4, which was fixed in the same task.
|
|
|
|
## Known Stubs
|
|
|
|
None. The fixture actions are test doubles by design, and the Discogs stubs belong to plan 10.1-03.
|
|
|
|
## User Setup Required
|
|
|
|
None. No external service configuration required.
|
|
|
|
## Next Phase Readiness
|
|
|
|
- Plan 10.1-02 (SPA) can consume `assets`, `toolbarActions`, `headerPartial`, the widget field keys, and the `PartialNode`/`PartialView`/`AdminActionResult` schema aliases from `schema.d.ts`.
|
|
- Plan 10.1-03 (Albums) implements `AdminClientAssets`, `HasAdminActions` and `AdminPartialData` on the albums controller.
|
|
- Plan 10.1-04 owns the named unit tests (TestPhase101FormExtensionSchema, Actions, Toolbar, Assets, PartialSanitizer) and `scripts/check-phase10.1.sh`.
|
|
- The README partial example uses the `summer-stats` class names. The admin SPA only styles them after plan 10.1-02.
|
|
|
|
## Self-Check: PASSED
|
|
|
|
- FOUND: modules/cabana/extension.go, actions.go, plugin_assets.go, partial_render.go, modules/pact/capabilities.go, admin/openapi/admin.json
|
|
- FOUND commits: f928194, 8b1cb24, 771d2cc (summercms.go); dcb64c9, 75ab47f, be3fbf4 (fonoteka.go)
|
|
- Plan verification: `go vet ./... && go test ./...` (summercms.go), `go vet` and `go test ./plugins/golem15/fonoteka/...` (fonoteka.go), `scripts/check-admin-openapi.sh --check`, `npm --prefix admin run typecheck`, `scripts/check-phase10.sh --hygiene`: all pass.
|
|
|
|
---
|
|
*Phase: 10.1-runtime-admin-extension-point*
|
|
*Completed: 2026-09-28*
|