testsec

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 5, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

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

func AssertNoDrift(t *testing.T, registered []string, wantPatterns []string)

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

func MissingSpecs(registered []string, wantPatterns []string) []string

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

type Fixture struct {
	Handler http.Handler
	Bearer  string
}

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
	// Unavailable builds the fixture for a dependency-down (authz/org unreachable) scenario —
	// 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.

func (Matrix) Patterns

func (m Matrix) Patterns() []string

Patterns returns every route's registration Pattern, for AssertNoDrift.

func (Matrix) Run

func (m Matrix) Run(t *testing.T)

Run drives every assertion in the matrix for every route.

type Recorder

type Recorder struct {
	Mux        *http.ServeMux
	Registered []string
}

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) Handle

func (r *Recorder) Handle(pattern string, handler http.Handler)

Handle records pattern and forwards to the underlying mux.

func (*Recorder) HandleFunc

func (r *Recorder) HandleFunc(pattern string, handler func(http.ResponseWriter, *http.Request))

HandleFunc records pattern and forwards to the underlying mux.

func (*Recorder) ServeHTTP

func (r *Recorder) ServeHTTP(w http.ResponseWriter, req *http.Request)

ServeHTTP delegates to the underlying mux, so a *Recorder can be used directly as the http.Handler under test.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL