SCRUM-196 — gateway_dev: route-policy tests, policy sheet, smoke coverage¶

Plan ref: GWD-6 (docs/11-admin-plane-plan.md). Stacked on SCRUM-195. The admin-edge counterpart of what SCRUM-89 did for the player gateway.

What changed¶

File	What
`route_policy_test.go` (new)	policy tests over the real table and the production wiring (`buildPublicMux`)
`ROUTE-POLICY.md` (new)	the policy and every route with Group, MinRole, Stream, rate-limit bucket, body cap, Upload, SetForwarded; which test enforces what
`testdata/smoke/smoke.sh`	checks 21b–21d (below)
`testdata/manual/fake_upstream.go`	echo upstream now reports `x_forwarded_for` / `x_forwarded_proto`
`testdata/manual/TESTING.md`	smoke list updated

Test	Proves
`TestRoutePolicy_MatchesSpec`	every route's full field set equals a literal expected table — any table change must edit this test
`TestRoutePolicy_FieldsConsistentWithGroup`	public routes have no MinRole; staff routes ≥ viewer; no player routes
`TestRoutePolicy_FailClosedMatrix`	8 staff routes × 8 token kinds = 64 cases: none / garbage / expired / player-domain → 401 (never 403, never 2xx); staff with no roles → 403; viewer / live_ops / admin → 2xx iff role ≥ MinRole else 403
`TestRoutePolicy_PlayerPathsNotServed`	player paths 404
`TestRoutePolicy_JWKSEndpointsNeverProxied`	`/.well-known/jwks.json` 404

Mutation check (done during review): lowering /api/admin/users/ to RoleViewer fails TestRoutePolicy_MatchesSpec with the exact field diff.

New smoke checks:

21b  2 MiB POST /api/admin/session/players (admin)   -> 413 body_too_large
21c  3 MiB POST /api/admin/config/packs (live_ops)   -> 200 upstream=config
     same as viewer                                  -> 403 insufficient_role
21d  POST /admin-auth/login, X-Forwarded-For 6.6.6.6 -> upstream sees XFF=127.0.0.1, proto=http

How to verify¶

cd services/gateway_dev
go vet ./... && go test -race -count=1 ./...
go test -count=1 -v -run TestRoutePolicy .
bash testdata/smoke/smoke.sh | grep -E "21[bcd]|FINDING" -A3

Results at time of writing¶

go vet, go test -race: pass (4 packages); 64/64 matrix cases.
Smoke: 21b–21d as above, 0 findings. No production code changed; no bugs found.

How it was built¶

DeepSeek run scoped (Landlock) to services/gateway_dev (127 s, ~22k output tokens). Claude review: confirmed the harness uses buildPublicMux, mutation check, smoke rerun.