Documentation
¶
Overview ¶
Package testsec is the shared negative-security matrix: one place that generalizes the ad hoc 401/403/503/forged-header pattern internal/gateway/admin_position_routes_test.go and admin_group_routes_test.go established, so every guarded route in the gateway and all four module HTTP layers is proven, not just the ones a human remembered to hand-write a matrix for.
Two independent pieces:
Matrix (this file): for each declared RouteSpec, drives missing-bearer (401), malformed-bearer (401), valid-but-forbidden (403), dependency-unavailable (503), and forged-inbound-identity-header assertions against caller-supplied fixtures. Callers own how a fixture is built (a real mux over a fake JWKS + fake downstream, matching every existing *_test.go in this codebase) — this package only owns the request-shape and assertion logic, never fixture construction, so it has zero dependency on any specific package's wiring.
Recorder + AssertNoDrift (recorder.go): the drift pin. A route mounted through a Recorder instead of a bare *http.ServeMux is captured by pattern string at registration time (the REAL mux.Handle/HandleFunc call, not a hand-maintained parallel list) — AssertNoDrift then fails the test if any registered pattern has no corresponding matrix entry, so a route added to a package's mount function without also adding a RouteSpec breaks `make check`.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AssertNoDrift ¶
AssertNoDrift fails t (via Errorf, one failure per offending route, so every gap is reported in one run rather than stopping at the first) if any pattern in registered has no exact match in wantPatterns — the drift pin: a route mounted through a Recorder-typed parameter without a corresponding RouteSpec in the package's matrix declaration fails this check.
func MissingSpecs ¶
MissingSpecs returns every pattern in registered that has no exact match in wantPatterns — the pure comparison AssertNoDrift wraps. Exposed separately (rather than only as a *testing.T side effect) so a test can prove the drift pin actually fires without tripping its OWN t.Errorf/Fatalf: a failing subtest unconditionally marks every ancestor *testing.T as failed in Go's testing package (t.Run's bool return only reports whether the subtest passed — it does not undo that propagation), so "assert this check would fail" cannot be expressed by calling AssertNoDrift itself inside a throwaway subtest and inspecting the result.
Types ¶
type Fixture ¶
Fixture is one scenario's ready-to-drive handler plus (optionally) a bearer token already minted for it.
type Matrix ¶
type Matrix struct {
Routes []RouteSpec
// Allowed builds the fixture for an authorized, dependency-healthy request — the base case
// missing-bearer/malformed-bearer are layered on top of (with the bearer withheld/corrupted)
// and forged-header runs against directly (with a valid bearer, to prove the header — not the
// bearer — is what's rejected/ignored).
Allowed func(t *testing.T) Fixture
// Forbidden builds the fixture for a valid bearer that is authenticated but not authorized
// (non-member/non-admin) — skipped for routes with SkipForbidden.
Forbidden func(t *testing.T) Fixture
// skipped for routes with SkipForbidden (same routes that have no downstream authz call to
// fail).
Unavailable func(t *testing.T) Fixture
// MalformedBearer is a syntactically-invalid bearer value (not a valid JWT) used for the
// malformed-token case.
MalformedBearer string
// ForgedHeaders are the inbound identity headers a real client must never be able to set
// (x-user-*, x-kiban-*, ...) that this suite proves are rejected or ignored.
ForgedHeaders map[string]string
// ForgedBearer selects which bearer to attach alongside ForgedHeaders: "" sends no bearer
// (proving the header cannot substitute for authentication — the shape module routes use,
// since they have no header-rejection layer of their own); "valid" attaches Allowed's own
// minted bearer (the shape gateway routes use, since RequireAuth rejects the header outright
// regardless of an otherwise-valid bearer).
ForgedBearer string // "" or "valid"
// ForgedWant is the expected status for the forged-header request.
ForgedWant int
}
Matrix bundles a route list with the fixture builders needed to run every assertion. Every builder is called once per (scenario, route) — cheap fixtures are expected (in-process httptest servers), matching every existing *_test.go in this codebase.
type Recorder ¶
Recorder wraps a real *http.ServeMux, recording every pattern registered through it (via Handle or HandleFunc) in registration order. A package's route-mounting function takes a small structural interface satisfied by both *http.ServeMux and *Recorder (Go interfaces are satisfied structurally — the production signature widens from *http.ServeMux to that interface with no change to its body), so a test can mount the SAME production code through a Recorder and get back the REAL registered-route list — not a hand-maintained parallel one that could silently drift from what the mount function actually does.
func NewRecorder ¶
func NewRecorder() *Recorder
NewRecorder builds a Recorder over a fresh *http.ServeMux.
func (*Recorder) HandleFunc ¶
HandleFunc records pattern and forwards to the underlying mux.
type RouteSpec ¶
type RouteSpec struct {
// Name is a short, unique label for t.Run subtests.
Name string
// Pattern is the EXACT string the route is registered with (e.g.
// "GET /api/org/admin/companies/{companyId}/positions") — used only for the drift check
// (matched 1:1 against Recorder.Registered), never to build a request.
Pattern string
// Method and Path build the concrete request this route's assertions send — Path has every
// {wildcard} already substituted with a sample value (e.g.
// "/api/org/admin/companies/co-1/positions").
Method string
Path string
// Body is the request body (may be empty for GET/DELETE-shaped routes).
Body string
// SkipForbidden marks a route that has no additional per-request authorization decision
// beyond bearer validation (e.g. the foundation "can"/"batch-can" fixed proxies, whose
// subject-scoping is enforced downstream, not at this layer) — the 403 and 503 assertions
// don't apply and are skipped; the caller must document why.
SkipForbidden bool
}
RouteSpec describes one route to run the negative-security matrix against.