33 KiB
33 KiB
phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, user_setup, must_haves
| phase | plan | type | wave | depends_on | files_modified | autonomous | requirements | user_setup | must_haves | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 06-http-routing-auth-groups-and-rate-limiting | 03 | execute | 3 |
|
|
false |
|
|
|
Purpose: this plan is the "contract surface" of the phase -- everything a future handler or a future auth guard (OAuth, Phase 8) must be structurally prevented from getting wrong, proven by inspection rather than trusted by convention.
Output: Router.GroupRaw, Router.Routes(), surf.RouteListCommand, wire.WriteJSON/Time/TriBool/Slice, path-scoped surf.cors, per-group body limits, the oauth group declared raw, a committed OpenAPI document, and a resolved (not guessed) production body-size limit.
<execution_context> @$HOME/.claude/get-shit-done/workflows/execute-plan.md @$HOME/.claude/get-shit-done/templates/summary.md </execution_context>
@.planning/PROJECT.md @.planning/phases/06-http-routing-auth-groups-and-rate-limiting/06-CONTEXT.md @.planning/phases/06-http-routing-auth-groups-and-rate-limiting/06-RESEARCH.md @.planning/phases/06-http-routing-auth-groups-and-rate-limiting/06-PATTERNS.md @.planning/phases/06-http-routing-auth-groups-and-rate-limiting/06-01-SUMMARY.md @.planning/phases/06-http-routing-auth-groups-and-rate-limiting/06-02-SUMMARY.md Extended summercms.go/pact/capabilities.go (Router interface):type Router interface { Group(prefix string, middleware []string, fn func(Router)) GroupRaw(prefix string, middleware []string, fn func(Router)) Get(path string, handler http.HandlerFunc, middleware ...string) Post(path string, handler http.HandlerFunc, middleware ...string) Put(path string, handler http.HandlerFunc, middleware ...string) Patch(path string, handler http.HandlerFunc, middleware ...string) Delete(path string, handler http.HandlerFunc, middleware ...string) Where(param, pattern string) WhereIn(param string, values ...string) }
New file summercms.go/surf/routetable.go:
package surf
type RouteInfo struct { Method string Pattern string PluginID string Middleware []string Raw bool }
// Routes returns a defensive copy of every registered route, post-Assemble. func (r *Router) Routes() []RouteInfo
New file summercms.go/surf/routelist_command.go:
package surf
// RouteListCommand mirrors ServeCommand's shape: builds the router the same // way (party.Activate has already run; this command receives app/plugins), // but renders Routes() as a table instead of serving. func RouteListCommand(app *backpack.App, plugins []party.Plugin) bonfire.Command
Router internals (summercms.go/surf/router.go) needed to support the above:
- route struct gains a raw bool field, set from the declaring Group/GroupRaw at add() time (thread it exactly like groupMW already threads through Group/Get/Post/etc).
- Group gains a raw bool field, inherited (once true, stays true through nested Group() calls -- a raw group cannot spawn a non-raw child).
- RegisterMiddleware and RegisterMiddlewareFactory both gain a variant that tags an entry as house-envelope/error (see Task 1 action for the exact shape); wrap() refuses a raw route referencing a house-tagged name at Assemble time (registration time), returning a "surf: raw group cannot use house-envelope middleware %q (plugin %q)" error -- not a runtime check.
- compile()/wrap() recovery moves from one blanket recoverJSON(cors(...)) wrap in compile() to a per-route choice inside wrap(): raw routes get a bare-500 recoverBare; non-raw routes keep recoverJSON's existing {"error":true,"message":"Internal server error"} body.
- Assemble no longer needs a package-level BuildRouter split: RouteListCommand can call the same Assemble(app, plugins) as ServeCommand and then call .(*Router) via a small unexported adapter, OR Assemble is refactored into BuildRouter(app, plugins) (*Router, error) + Assemble = BuildRouter+compile -- choose the refactor (BuildRouter) since it avoids any type assertion on the returned http.Handler and is the cleaner seam for route:list.
New file summercms.go/wire/response.go:
package wire
// WriteJSON is byte-identical to genre_controller.go's private writeJSON // (SetEscapeHTML(false), trailing-newline trim via bytes.TrimSuffix). func WriteJSON(w http.ResponseWriter, status int, v any) func WriteOpaque500(w http.ResponseWriter)
// Time marshals as Carbon's +00:00 form (2006-01-02T15:04:05+00:00), never // Go's default "Z". Unmarshal accepts both +00:00 and Z for read paths. type Time struct{ time.Time } func (t Time) MarshalJSON() ([]byte, error) func (t *Time) UnmarshalJSON(b []byte) error
// TriBool keeps PHP's nullable-boolean tri-state: Valid=false marshals null. type TriBool struct{ Valid, Value bool } func (b TriBool) MarshalJSON() ([]byte, error)
// Slice guarantees a never-nil JSON array. func Slice[T any](s []T) []T
Task 1 (summercms.go): Raw group enforcement, route table, and the route:list command summercms.go/pact/capabilities.go, summercms.go/surf/router.go, summercms.go/surf/router_test.go, summercms.go/surf/routetable.go, summercms.go/surf/routetable_test.go, summercms.go/surf/routelist_command.go, summercms.go/internal/build/build.go, summercms.go/internal/build/build_test.go summercms.go/surf/router.go (full, post-06-02 -- route/Group structs, add/compile/wrap, RegisterMiddleware, Assemble, recoverJSON, cors) summercms.go/surf/serve.go (full -- ServeCommand's bonfire.Command shape to mirror for RouteListCommand) summercms.go/bonfire/command.go (Command/Output shapes; bonfire/widgets.go's Table(headers []string, rows [][]string) signature) summercms.go/lagoon/commands.go (RuntimeCommands -- an existing bonfire.Command-returning function to mirror for style, not for content) summercms.go/internal/build/build.go lines 80-127 (generateMain -- exact lines emitting "commands = append(commands, surf.ServeCommand(app, plugins))"; add the route:list line directly after it) summercms.go/internal/build/build_test.go (existing assertions on generated main.go content to extend) .planning/phases/06-http-routing-auth-groups-and-rate-limiting/06-RESEARCH.md Pattern 3 (raw group structural exemption, lines 303-321) In pact/capabilities.go, add GroupRaw(prefix string, middleware []string, fn func(Router)) to the Router interface, same signature shape as Group.In surf/router.go: add raw bool to both Group and route. Add GroupRaw on *Router and *Group mirroring Group's existing body exactly, except the constructed child Group has raw: true; when Group() is called on an ALREADY-raw Group (g.raw == true), the child it constructs must also be raw:true (sticky inheritance -- a raw group cannot spawn a non-raw child via a later Group() call). Thread raw through add()'s signature (alongside pluginID/prefix/groupMW/method/path/handler/extra) so route.raw is set from whichever Group/GroupRaw declared it.
Add a houseTagged bool field to namedMiddleware and namedMiddlewareFactory. Add RegisterHouseMiddleware(pluginID, name string, fn pact.Middleware) error and RegisterHouseMiddlewareFactory(pluginID, name string, fn func(string) pact.Middleware) error, each calling the existing Register*/RegisterMiddlewareFactory internals but setting houseTagged: true on the stored entry (do not duplicate the dup-check logic -- factor a shared unexported registerNamed(pluginID, name string, tagged bool, ...) if that keeps both call sites DRY, or two thin wrappers if simpler; either is acceptable as long as the dup/empty-name checks are not duplicated verbatim). In fonoteka.go's plugin.go (see Task 3 of this plan for the actual call-site change), "inv.must-change-password" switches from RegisterMiddleware to RegisterHouseMiddleware.
In wrap()'s middleware-resolution loop: after resolving a name to either a namedMiddleware or a factory-built middleware, check `if rt.raw && resolvedHouseTagged { return nil, fmt.Errorf("surf: raw group cannot use house-envelope middleware %q (plugin %q)", name, rt.pluginID) }` -- this makes the refusal a registration-time (Assemble-time) failure, since Assemble already calls r.wrap(rt) once per route specifically to surface these errors before compile().
Change wrap()'s outer recovery: instead of compile() wrapping the whole mux in one recoverJSON(cors(...)), move recovery INTO wrap() per-route: `if rt.raw { h = recoverBare(h) } else { h = recoverJSON(h) }` as the outermost wrap (applied after the locale() wrap, i.e. truly outermost). Add recoverBare(next http.Handler) http.Handler mirroring recoverJSON's shape but on panic writing only w.WriteHeader(http.StatusInternalServerError) with NO body and NO Content-Type header set (D-16: "bare 500, no house JSON body"). compile()'s final return simplifies to just the CORS wrapper around mux (CORS itself becomes path-scoped in Task 3 of this plan -- for THIS task, compile() can keep calling the existing blanket cors(r.origins, mux) unchanged; Task 3 replaces it).
Create routetable.go: RouteInfo exactly as specified in the interfaces block; (r *Router) Routes() []RouteInfo iterating r.routes and returning a defensive copy (new slice, new []string per entry -- do not alias r.routes[i].middleware).
Refactor Assemble into BuildRouter(app *backpack.App, plugins []party.Plugin) (*Router, error) containing everything Assemble currently does EXCEPT the final r.compile() call (return r, nil instead); Assemble(app, plugins) becomes `r, err := BuildRouter(app, plugins); if err != nil { return nil, err }; return r.compile()`. This lets RouteListCommand call BuildRouter directly and read .Routes() without compiling/serving.
Create routelist_command.go: RouteListCommand(app, plugins) bonfire.Command{Name: "route:list", Description: "List registered HTTP routes", Run: func(ctx, in, out) error { r, err := BuildRouter(app, plugins); if err != nil { return err }; rows := make([][]string, 0, len(r.Routes())); for _, rt := range r.Routes() { rows = append(rows, []string{rt.Method, rt.Pattern, rt.PluginID, strings.Join(rt.Middleware, ","), strconv.FormatBool(rt.Raw)}) }; out.Table([]string{"Method","Pattern","Plugin","Middleware","Raw"}, rows); return nil }}.
In internal/build/build.go's generateMain, add a line `b.WriteString("\tcommands = append(commands, surf.RouteListCommand(app, plugins))\n")` directly after the existing `surf.ServeCommand` append line. Update build_test.go's existing content-assertion test to also assert the generated main.go contains "surf.RouteListCommand".
In genre_controller.go, replace the private writeJSON/writeOpaque500 function bodies with thin delegations to wire.WriteJSON/wire.WriteOpaque500 (keep the local function names and call sites unchanged so no other file in this package needs to change -- only the two function bodies become one-line delegations, proving the promotion without a wider refactor this phase). Add swag doc comments directly above the ListGenres function: `// @Summary List genres` / `// @Description Returns the global genre pool with tenant-scoped album counts` / `// @Tags genres` / `// @Produce json` / `// @Param non_empty query string false "1 to only return genres with albums"` / `// @Success 200 {object} GenreList` / `// @Router /_fonoteka/api/v1/genres [get]` (swag's comment-annotation syntax, scanning this handler's existing signature -- no signature change).
Create scripts/check-openapi.sh (fonoteka.go/scripts/, executable): runs `go run github.com/swaggo/swag/cmd/swag@v1.16.6 init --generalInfo plugins/golem15/fonoteka/controllers/genre_controller.go --output docs --parseDependency` (adjust flags to this repo's actual layout after a first local run) to produce docs/openapi.json (swag's default is swagger.json/yaml -- pin the output filename explicitly via swag's -o/--output and --outputTypes json flags so the committed artifact is deterministic), then runs `npx --yes openapi-typescript@7.13.0 docs/openapi.json -o /dev/null` (validity check only -- Phase 10 owns wiring real output into the admin SPA) and fails the script (non-zero exit) if either command errors, and a third check: `git diff --exit-code docs/openapi.json` style drift check IF run in CI (document this as the drift-check step; for local/plan execution, running the script once and committing docs/openapi.json is sufficient).
Run the script once locally, commit the resulting docs/openapi.json.
Create surf/bodylimit.go: two config keys read once in BuildRouter -- http.body_limits.default_bytes and http.body_limits.upload_bytes (both int64 via a small helper since compass.Config.Int returns int; convert). Wrap every non-raw route's handler (innermost, next to constrain()) with http.MaxBytesReader(w, r.Body, defaultBytes) via a bodyLimit(defaultBytes int64) middleware applied unconditionally in wrap() (raw routes are exempt -- RFC endpoints like /oauth/mcp/token have their own well-known limits and must not gain a house-specific cap). Add an opt-in named middleware factory "body.limit" (registered by the router itself, like "throttle") whose param is a byte count string, letting a future upload route request a larger cap by listing "body.limit:20971520" (20 MiB) etc. explicitly in its middleware list, overriding the default for that one route (apply it as the innermost wrap so it supersedes the blanket default-bytes reader for that route only).
In fonoteka.go/config/http.yaml, add: cors: paths: ["api/*", "_user/api/*", "_journal/api/*", "_feedback/api/*", "oauth/mcp/*"], allowed_methods: ["*"], allowed_origins: ["*"], allowed_origins_patterns: [], allowed_headers: ["*"], exposed_headers: [], max_age: 0, supports_credentials: false (byte-for-byte from config/cors.php); body_limits: default_bytes: 8388608 (8 MiB, PHP's stock post_max_size, marked with a comment "INTERIM default per 06-RESEARCH.md Assumption A2 -- replace with the real production client_max_body_size/post_max_size once read off the host"), upload_bytes: 2097152 (2 MiB, PHP's stock upload_max_filesize, same INTERIM comment).
In fonoteka.go/plugins/golem15/fonoteka/plugin.go, switch the "inv.must-change-password" registration from RegisterMiddleware to RegisterHouseMiddleware (Task 1's new capability) -- this is the concrete proof case for D-16's registration-time refusal (a raw group referencing "inv.must-change-password" must now fail boot).
In fonoteka.go/plugins/golem15/fonoteka/routes.go, add the oauth group via r.GroupRaw("/", surf.Use(), func(g pact.Router) {}) -- bindings has no Go equivalent (no route-model binding concept), so the middleware list is empty; the group exists purely to prove GroupRaw's structural behavior at this prefix and to be the landing spot for Phase 8's two real routes, each of which will individually add "throttle:fonoteka-oauth-token"/"throttle:fonoteka-oauth-register" per-route (not group-level, matching routes.php's actual per-route ->middleware() calls at lines 561/565) -- do not attach the throttle names to the empty GroupRaw call itself, since PHP attaches them per-route, not per-group, and there is no route to attach them to yet.
<threat_model>
Trust Boundaries
| Boundary | Description |
|---|---|
| raw group -> house middleware | a misconfigured raw group must fail boot, not silently mount an envelope/error middleware onto an RFC-shaped surface |
| any request body -> handler | an unbounded request body is a resource-exhaustion vector regardless of auth group |
| CORS config -> browser | an overly permissive path-glob match would leak the JWT group's same-origin-only posture to cross-origin callers |
STRIDE Threat Register
| Threat ID | Category | Component | Disposition | Mitigation Plan |
|---|---|---|---|---|
| T-06-10 | Elevation of Privilege | Route table mutual-exclusivity | mitigate | routetable_test.go asserts, over the FULL assembled route table, that no /api/v1/fonoteka route carries jwt.auth and no /_fonoteka/api/v1 route carries inv_token/inv.scope: -- this completes the partial coverage 06-01 accepted (T-06-02) |
| T-06-11 | Tampering | Raw-group house-middleware refusal | mitigate | Registration-time (not request-time) failure; a future PR cannot silently attach an envelope middleware to the OAuth group and have it ship |
| T-06-12 | Denial of Service | Unbounded request body on a non-raw route | mitigate | http.MaxBytesReader applied unconditionally per non-raw route via the default body limit; raw (RFC) routes rely on their own future handler-level limits, matching PHP's own scoping |
| T-06-13 | Information Disclosure | Body-size limits shipped as a guess | mitigate | INTERIM defaults are clearly commented as unverified; the plan cannot close without the blocking checkpoint recording operator-confirmed production numbers -- never presented as verified when it is not |
| T-06-SC | Tampering | npm/go install in scripts/check-openapi.sh (swag, openapi-typescript) | accept | Both packages are STACK.md-named and pass 06-RESEARCH.md's Package Legitimacy Audit (Approved disposition, no [ASSUMED]/[SUS] verdicts) -- no additional human-verify checkpoint required beyond that prior audit |
| </threat_model> |
<success_criteria>
- Raw groups refuse house-tagged middleware at registration time and recover with a bare 500.
- The route table and route:list command exist and prove group mutual-exclusivity by inspection.
- wire package ships the promoted response-convention helpers, unit-tested independently.
- CORS is path-scoped and matches config/cors.php exactly (JWT group: no headers; token group: wildcard).
- Body limits are enforced per group with operator-confirmed production numbers, not a guess.
- The oauth group is declared raw with zero handlers.
- A real OpenAPI document is generated from swag annotations and validated by openapi-typescript.
- go vet ./... and go test ./... are green in both repos. </success_criteria>