securex

func APIKeyAuth ¶

func APIKeyAuth(r *http.Request, secret []byte, window time.Duration, seen *sync.Map) error

APIKeyAuth verifies Authorization: Bearer <hmac-hex> using a canonical request signature bound to method/path/body/nonce/timestamp and secret. It enforces a time window and replay protection via the seen map.

The request body is streamed through the hash via io.LimitReader with defaultHMACBodyLimit so that a single oversized request cannot exhaust server memory. See APIKeyAuthWithLimit for the explicit-limit variant.

func APIKeyAuthHTTP ¶

func APIKeyAuthHTTP(w http.ResponseWriter, r *http.Request, secret []byte, window time.Duration, seen *sync.Map) bool

APIKeyAuthHTTP wraps APIKeyAuth with HTTP error mapping for PERF #171 (sign-or-413). On success it returns true and the caller continues dispatch with r.Body re-staged (pooledBuffer). On failure it writes the appropriate status (413 for ErrBodyTooLarge, 401 for any other auth error) and a JSON envelope carrying error_code = <status> so observability pipelines can route alerts off a structured field instead of regex-matching on Message.

The 413 status is reserved for the body-size condition; any other authentication failure (bad signature, missing headers, expired timestamp, replayed nonce, etc.) collapses to 401 with the same envelope shape. This is "Option B" from PERF_GAP_ANALYSIS row 13.

func APIKeyAuthHTTPWithLimit ¶

func APIKeyAuthHTTPWithLimit(w http.ResponseWriter, r *http.Request, secret []byte, window time.Duration, seen *sync.Map, maxBodyBytes int64) bool

APIKeyAuthHTTPWithLimit is the explicit-limit variant of APIKeyAuthHTTP. A maxBodyBytes of 0 resolves to defaultHMACBodyLimit so that callers who have not migrated to an explicit cap still get the 1 MiB safe default. (PERF #171.)

func APIKeyAuthWithLimit ¶

func APIKeyAuthWithLimit(r *http.Request, secret []byte, window time.Duration, seen *sync.Map, maxBodyBytes int64) error

APIKeyAuthWithLimit is the explicit-limit variant of APIKeyAuth. The maxBodyBytes parameter caps the number of bytes that will be read from r.Body when computing the canonical signature. A value of 0 resolves to defaultHMACBodyLimit. A body strictly larger than maxBodyBytes is rejected with an error that wraps ErrBodyTooLarge; callers can inspect via errors.Is.

func AllowInsecureDev ¶

func AllowInsecureDev(r *http.Request, debugMode bool) bool

AllowInsecureDev reports whether the per-request INSECURE_DEV bypass should be honoured for this request. FOUR conditions must all hold (A-03):

1. The TCP peer is a loopback address. The decision is made against r.RemoteAddr ONLY. X-Forwarded-For, X-Real-IP, and other proxy hints are intentionally ignored so that a reverse proxy cannot be tricked into forging a loopback origin.
2. debugMode is true. The caller derives this from its own runtime mode (e.g. gin.Mode()==gin.DebugMode). Because debug is gin's DEFAULT (active unless GIN_MODE=release), debug mode alone is deliberately NOT sufficient — see condition 4.
3. The environment variable APIC_INSECURE_DEV is set to a truthy value (1, true, yes, y, on - case insensitive).
4. The environment variable APIC_ENV is set to "development" (case insensitive). This is the EXPLICIT positive development assertion that A-03 requires so the bypass cannot engage merely because debug mode shipped by omission.

If any condition fails, the bypass is denied. As a fail-closed guard, when APIC_INSECURE_DEV is truthy while the runtime is in release mode (GIN_MODE=release) the function PANICS — refusing to serve — rather than silently denying, because that combination is an unambiguous misconfiguration. A warning is logged at most once per process lifetime when the bypass first activates.

func AllowInsecureDevAtStartup ¶

func AllowInsecureDevAtStartup(debugMode bool) bool

AllowInsecureDevAtStartup is the setup-time variant of AllowInsecureDev. No HTTP request is available yet, so only debugMode and the environment variable are checked. This is the correct helper for listener wiring, CORS configuration, and OIDC-missing startup branches - places where the per-request loopback check cannot yet run.

A-03: like AllowInsecureDev it refuses to start (panics) when APIC_INSECURE_DEV is truthy under release mode (GIN_MODE=release). The explicit APIC_ENV=development assertion is deliberately NOT required here: this helper governs the plain-HTTP-listener / TLS bypass (SEC-0002), a separate control from the per-request JWT-validation bypass that A-03 names. The release-mode hard-fail is the relevant fail-closed guard for the startup path; the stricter development-assertion gate is enforced on the per-request AllowInsecureDev, where the auth bypass actually decides a request.

func ContextWithAuthSource ¶ added in v0.18.3

func ContextWithAuthSource(ctx context.Context, src AuthSource) context.Context

ContextWithAuthSource returns a copy of ctx recording src as the credential transport a gate consumed for this request. Passing a nil ctx is safe and returns a context.Background()-derived value (mirrors ContextWithClaims).

func ContextWithClaims ¶

func ContextWithClaims(ctx context.Context, claims *Claims) context.Context

ContextWithClaims returns a copy of ctx carrying the supplied Claims pointer. The generated per-route middleware first checks ClaimsFromContext(r.Context()) before re-parsing the bearer token, so a verifier (e.g. APIOptions.AuthJWT) that calls this once per request avoids the second base64-decode-and-Unmarshal per route. (S-NEW-3.)

Callers MUST only stash claims they have cryptographically verified (signature and expiry checked). Stashing claims from an unverified token is a security defect: downstream RBAC trusts these claims without re-checking the signature.

Passing a nil claims pointer stores a typed-nil so subsequent ClaimsFromContext(ctx) returns (nil, false) — this mirrors the "auth ran, but no claims attached" sentinel used by mcpx's ContextWithRoles when called with a nil slice.

Passing a nil ctx is safe and returns a context.Background()-derived value so downstream code can always derive a new ctx from the result.

func ContextWithMTLSPrincipal ¶ added in v0.18.3

func ContextWithMTLSPrincipal(ctx context.Context, principal, classification string) context.Context

ContextWithMTLSPrincipal returns ctx carrying the identity a route's CertPolicy verifier resolved for the verified client certificate: principal is the value selected by mtls.principal_mapping (subject_cn / upn / san_email / san_dns_first / edipi) and classification is the CAC/PIV classification (cacpiv.Classification.String()). VerifyMTLSRequest calls this ONLY after every check in the policy has passed; callers layering their own verifier on top should honor the same rule and never store an identity for a certificate that was not accepted.

func EvalComposite ¶

func EvalComposite(r *http.Request, groups [][]Gate) (*http.Request, error)

EvalComposite evaluates a disjunctive-normal-form auth expression: the outer slice is OR-of-groups, each inner slice is an AND of gates. It tries groups left-to-right and returns the request from the FIRST group whose every gate passes (short-circuit). Each non-empty group starts from a deep clone of r (via r.Clone) so that header/trailer map mutations AND context-carried claims written by a partially-passing-then-failing group cannot leak into the next group or the handler. Returns the original request and ErrAuthFailed when no group fully passes (fail-closed: empty/nil groups also fail).

Note: r.Clone shares the request Body (io.ReadCloser) across groups — auth gates read TLS state, headers, and cookies, not the body, so this is intentional and out of scope for this isolation guarantee.

func ExtractCookieToken ¶

func ExtractCookieToken(r *http.Request, cookieName string) (string, error)

ExtractCookieToken returns the JWT carried in the named HttpOnly auth cookie.

func MTLSPrincipalFromContext ¶ added in v0.18.3

func MTLSPrincipalFromContext(ctx context.Context) (principal, classification string, ok bool)

MTLSPrincipalFromContext returns the identity recorded by ContextWithMTLSPrincipal. ok is false -- and both strings are empty -- when the request was not admitted through an mTLS route with a CertPolicy (no principal_mapping / cac_piv configured), when the policy rejected the certificate, or when ctx is nil. A false ok never means "anonymous but present": routes without a CertPolicy get no fabricated identity, so consumers that need one must configure principal_mapping.

func NewTestVerifier ¶

func NewTestVerifier() func(*http.Request) error

NewTestVerifier returns an Auth-style request verifier that accepts any request carrying a non-empty `Authorization: Bearer <token>` header. Empty Authorization headers, malformed headers, and missing tokens all return ErrAuthFailed.

The returned function is intended for unit-test ergonomics ONLY. It does not validate the bearer token; any non-empty value passes. Production code MUST NOT wire this verifier -- the apic-generated registration calls explicitly panic with ErrAuthVerifierRequired if the caller supplies nil for a route declaring auth: "jwt", which makes the "forgot to wire a real verifier" failure mode loud at boot.

Example use in a test:

api.RegisterGeneratedAPI(mux, srv, api.APIOptions{
    AuthJWT: securex.NewTestVerifier(),
    Auth:    securex.NewTestVerifier(),
})

The same function value satisfies both APIKey and JWT verifier slots because both contracts are `func(*http.Request) error`.

func RequestWithAuth ¶

func RequestWithAuth(r *http.Request) *http.Request

RequestWithAuth applies the hardened default request auth policy.

func RequestWithAuthPolicy ¶

func RequestWithAuthPolicy(r *http.Request, policy RequestAuthPolicy) *http.Request

RequestWithAuthPolicy clones r and fills auth headers from the configured transport sources, including websocket subprotocol auth markers when browser clients cannot set custom headers during the upgrade.

func RequireABAC ¶

func RequireABAC(secret []byte, policies ...ABACPolicy) func(http.Handler) http.Handler

RequireABAC returns an http.Handler middleware that enforces ABAC policies. The JWT is verified using the secret, and all policies must evaluate to true. Fails with 401 Unauthorized for invalid tokens, and 403 Forbidden for policy failures.

func RequireABACWithOptions ¶

func RequireABACWithOptions(secret []byte, opts JWTVerifyOptions, policies ...ABACPolicy) func(http.Handler) http.Handler

RequireABACWithOptions is the iss/aud-aware variant of RequireABAC (A-01). The supplied JWTVerifyOptions bind the in-handler HS256 fallback to an expected issuer/audience. Zero-value opts reproduce the legacy behavior.

func RequireOwnership ¶

func RequireOwnership(secret []byte, extract OwnerExtractor, next http.Handler) http.Handler

RequireOwnership returns middleware enforcing object-level authorization (SEC-0027 / OWASP API1:2023 BOLA): the authenticated subject (JWT "sub") must equal the resource-owner id returned by extract. This is the building block the generated by-id handlers (e.g. GET/PATCH/DELETE /v1/users/{userId}) cannot supply themselves, because only the consumer knows which claim maps to which resource. Wire it per owner-scoped route.

Secure-by-default: a missing/invalid token is 401; a subject that does not match the resource owner is a generic 403 (ErrOwnershipDenied, logged server-side only). If extract reports no owner-scoped resource, the request passes through unchanged so non-owned routes are unaffected. An empty JWT subject can never match and is therefore always denied.

func RequireOwnershipWithOptions ¶

func RequireOwnershipWithOptions(secret []byte, opts JWTVerifyOptions, extract OwnerExtractor, next http.Handler) http.Handler

RequireOwnershipWithOptions is the iss/aud-aware variant of RequireOwnership (A-01). The supplied JWTVerifyOptions bind the in-handler HS256 fallback to an expected issuer/audience. Zero-value opts reproduce the legacy behavior.

func RequireRole ¶

func RequireRole(minimum Role, secret []byte, next http.Handler) http.Handler

RequireRole returns an http.Handler middleware that enforces a minimum role. The JWT is read from "Authorization: Bearer <token>" and verified with secret. Requests whose highest role is below minimum receive 403 Forbidden. Requests with missing/invalid tokens receive 401 Unauthorized.

func RequireRoleH ¶ added in v0.19.2

func RequireRoleH(h *RoleHierarchy, minimum Role, secret []byte, opts JWTVerifyOptions, next http.Handler) http.Handler

RequireRoleH is RequireRoleWithOptions bound to an EXPLICIT role vocabulary. Prefer it over RequireRole/RequireRoleWithOptions, which can only resolve against the built-in admin > manager > user vocabulary: a server whose security.roles declares platform_admin > assessor > viewer needs its own hierarchy, and before ENG-4634 the only way to install one was SetRoleHierarchy, which mutated a process-wide graph shared with every other server in the binary.

A nil hierarchy falls back to the built-in default, so RequireRoleH(nil, ...) is exactly RequireRoleWithOptions.

func RequireRoleWithOptions ¶

func RequireRoleWithOptions(minimum Role, secret []byte, opts JWTVerifyOptions, next http.Handler) http.Handler

RequireRoleWithOptions is the iss/aud-aware variant of RequireRole (A-01). The supplied JWTVerifyOptions are honoured on the in-handler HS256 fallback, binding the token to an expected issuer/audience so a validly-signed token minted for a different service is rejected (401) rather than accepted. When opts is the zero value this behaves exactly like the legacy RequireRole; set Issuer/Audience (and the matching Require* flags) to enforce binding.

func SetAuditSink ¶ added in v0.18.3

func SetAuditSink(fn func(event string, fields map[string]any))

SetAuditSink installs fn as the destination for WriteUnauthorized and WriteForbidden's audit events. Passing nil restores the default sink, which logs via slog.Default().Warn(event, "fields", fields). pkg/securex intentionally does not import pkg/obsx (avoiding an import cycle); callers that want auth decisions routed through obsx's redacted fanout call securex.SetAuditSink(obsx.LogAudit) themselves (generated servers do this in server_lib.go.tmpl / cli/serve).

func SetRateHeaders ¶

func SetRateHeaders(w http.ResponseWriter, limit, remaining int, reset time.Time)

SetRateHeaders sets basic rate-limit headers on the response.

func SignAPIKeyRequest ¶

func SignAPIKeyRequest(r *http.Request, secret []byte, now time.Time) error

SignAPIKeyRequest signs r using the same canonical request rules enforced by APIKeyAuth. It sets Authorization, X-Nonce, and X-Timestamp on the request.

func SignAPIKeyRequestWithValues ¶

func SignAPIKeyRequestWithValues(r *http.Request, secret []byte, nonce, ts string) error

SignAPIKeyRequestWithValues signs r with explicit nonce and timestamp values. This is useful for deterministic tests and for flows that need to precompute signed WebSocket auth material.

func SignWebhookRequest ¶

func SignWebhookRequest(r *http.Request, secret []byte, alg WebhookAlg, now time.Time) error

SignWebhookRequest stamps r with X-Webhook-Id, X-Timestamp, and the HMAC signature header so the request passes VerifyWebhook against the same secret. Use this from outbound delivery code and from tests; the receiver does NOT depend on this helper.

The id is a 16-byte random nonce (base64-url, no padding) — the same shape APIKeyAuth uses for X-Nonce so consumers see a uniform id format across both auth modes. now is supplied so tests can pin a deterministic timestamp; production callers pass time.Now().

func StartNonceGC ¶

func StartNonceGC(ctx context.Context, seen *sync.Map, interval time.Duration) chan struct{}

StartNonceGC starts a GC loop to remove expired nonces stored by APIKeyAuth. N-15: context-first (ctx is the first parameter, matching the repo's documented context-first convention) and clamps a non-positive interval to defaultNonceGCInterval instead of letting time.NewTicker panic. gen.SafeLoop recovers a panic and restarts the loop body, but interval is a closed-over value that never changes across restarts, so an invalid interval previously spun forever in a panic/backoff/restart cycle rather than ever making progress. The returned channel keeps its existing contract (closing it stops the loop); ctx cancellation stops it too, whichever comes first.

func VerifyJWT ¶

func VerifyJWT(token string, secret []byte) error

VerifyJWT verifies a compact JWS (HS256) with the provided secret. Returns ErrJWTUnsupported if algorithm is not HS256 or token malformed.

SECURE DEFAULT (SEC-0028): VerifyJWT REQUIRES the "exp" claim. A token that omits "exp" never expires, which turns a single leaked bearer token into a permanent authorization-server compromise primitive. RFC 7519 §4.1.4 marks "exp" OPTIONAL, but a resource server MUST NOT accept a non-expiring access token. Callers that truly need the legacy accept-no-exp behavior must opt in explicitly via VerifyJWTAllowNoExpiry (or VerifyJWTWithOptions with RequireExpiry:false) and own that risk.

func VerifyJWTAllowNoExpiry ¶

func VerifyJWTAllowNoExpiry(token string, secret []byte) error

VerifyJWTAllowNoExpiry is the explicit, clearly-named opt-out from the VerifyJWT secure default (SEC-0028). It verifies the HS256 signature and any present "exp"/iss/aud claims, but — unlike VerifyJWT — it ACCEPTS a token that omits "exp" entirely (a never-expiring token).

This exists only for narrow legacy/back-compat call sites that knowingly issue or accept non-expiring tokens. Prefer VerifyJWT (or VerifyJWTWithOptions with the appropriate Require* fields) for anything exposed to untrusted input. Using this on an internet-facing resource server is an authorization weakness.

func VerifyJWTWithJWKS ¶

func VerifyJWTWithJWKS(_ context.Context, token string, keys jwk.Set, opts JWKSVerifyOptions) (jwt.Token, error)

VerifyJWTWithJWKS parses and verifies a compact JWS token using the supplied jwk.Set. Returns the parsed jwt.Token on success, or ErrAuthFailed / ErrJWTUnsupported / ErrJWKSEmpty on failure.

The asymmetric-only contract is enforced before signature verification: the JWS header `alg` is parsed and compared against the allowlist; any `none` or HMAC alg returns ErrJWTUnsupported without touching keys or running the underlying jwt.Parse signature path.

func VerifyJWTWithOptions ¶

func VerifyJWTWithOptions(token string, secret []byte, opts JWTVerifyOptions) error

VerifyJWTWithOptions verifies a compact JWS (HS256) with the provided secret and enforces optional issuer/audience checks when configured.

func VerifyMTLS ¶

func VerifyMTLS(r *http.Request, policy MTLSPolicy) error

VerifyMTLS enforces a per-route mTLS policy against an HTTP request whose connection terminated on a TLS listener. Call after the listener has completed the TLS handshake but before any handler logic runs.

Checks, in order:

1. r and r.TLS are non-nil. Defends against an accidentally plaintext reverse-proxy hop in front of the server stripping mTLS state.
2. If policy.Required, at least one peer certificate is present.
3. The peer cert chain has been verified by the listener (r.TLS.VerifiedChains is non-empty).
4. If policy.EKUValidation, the leaf certificate carries the clientAuth (or ExtKeyUsageAny) Extended Key Usage.
5. If policy.Runtime.CRL and/or policy.Runtime.OCSP is configured (L-51), the leaf is checked against the issuer's CRL/OCSP revocation state. A zero-value Runtime is a no-op here.
6. If policy.Runtime.CertPolicy is configured (L-51), the leaf is verified against the CAC/PIV certificate-classification policy.

SupportedIssuers is intentionally NOT enforced. Callers that need issuer-label validation should layer their own verifier on top after VerifyMTLS returns nil; the apic-emitted handler invokes opts.AuthMTLS for exactly that purpose.

VerifyMTLS is the error-only form: it enforces exactly what VerifyMTLSRequest enforces but cannot hand back the request enriched with the identity step 6 resolved. Callers that run a business handler after the gate should use VerifyMTLSRequest so the principal reaches it (L-55).

func VerifyMTLSRequest ¶ added in v0.18.3

func VerifyMTLSRequest(r *http.Request, policy MTLSPolicy) (*http.Request, error)

VerifyMTLSRequest is VerifyMTLS that also returns the request to continue with. When policy.Runtime.CertPolicy accepts the leaf, the returned request's context carries the resolved principal and classification (MTLSPrincipalFromContext) and -- when the verifier implements CertPolicyContextVerifier, as the generated server's cacpiv adapter does -- the full identity object (mtlsx.From). Otherwise r is returned as-is: a route with no CertPolicy gets NO fabricated identity, and on any error the returned request carries nothing new (the Gate contract's "stash only on success" rule), so a failed AND-group leaves no principal residue.

func VerifyWebhook ¶

func VerifyWebhook(r *http.Request, secret []byte, pol WebhookPolicy) error

VerifyWebhook checks r against pol using the supplied secret. Returns nil on success. Returns ErrBodyTooLarge (detectable via errors.Is) when the request body exceeds pol.MaxBodyBytes so callers can map it to HTTP 413 — mirrors APIKeyAuthWithLimit. Returns ErrWebhookFailed for every other rejection: empty secret, missing/malformed headers, non-allowlisted alg, expired timestamp, bad signature, replay.

The body is rewrapped on success so the user handler can re-read it; on failure the body may be partially consumed and the caller should treat r as untrusted.

secret is supplied per-request (not stored on pol) so the generator can resolve it from APIOptions.AuthWebhook keyed on pol.Name. Zero (nil/empty) secret causes verification to fail regardless of any other input.

func WebhookReplayStorePtr ¶

func WebhookReplayStorePtr() *sync.Map

WebhookReplayStorePtr returns a pointer to the package-shared webhook replay store. Pass this to StartNonceGC at server start so expired entries (entries whose value time.Time is in the past) are reaped on the same cadence as the API-key nonce store. Task 10 of the webhook-receiver plan wires this from server.go.tmpl.

Returning a *sync.Map (not a copy) is intentional: StartNonceGC mutates the map in place to delete expired keys.

func WriteForbidden ¶

func WriteForbidden(w http.ResponseWriter, internalErr error)

WriteForbidden writes the package-standard 403 response: Content-Type application/json, status 403, and the spec ApiError envelope `{"code","message","requestId"}` with a generic, framework-neutral code (GenericForbiddenCode) and message. The supplied internalErr (typically ErrInsufficientRole, or a wrapped scope / attribute reason) is logged at WARN level via log/slog so operators can still triage the underlying cause — it is intentionally NOT echoed into the response body.

Mirrors WriteUnauthorized in shape so the two helpers stay behaviour-symmetric for downstream regression tests that diff the 401 and 403 surfaces side-by-side.

All package-internal call sites that previously emitted `http.Error(w, ErrInsufficientRole.Error(), 403)` or `writeJSONError(w, securex.ErrInsufficientRole.Error(), 403)` MUST route through this helper to guarantee the A-005 closure across the generated server set.

func WriteUnauthorized ¶

func WriteUnauthorized(w http.ResponseWriter, internalErr error)

WriteUnauthorized writes the package-standard 401 response: Content-Type application/json, status 401, and the spec ApiError envelope `{"code","message","requestId"}` with a generic, framework-neutral code (GenericUnauthorizedCode) and message. The supplied internalErr (typically one of the package-level Err* sentinels) is logged at WARN level via log/slog so operators can still triage the underlying cause from server logs — it is intentionally NOT echoed into the response body.

All package-internal call sites that previously emitted `http.Error(w, ErrAuthFailed.Error(), 401)` or `writeJSONError(w, securex.ErrAuthFailed.Error(), 401)` MUST route through this helper to guarantee the F-CR-004 closure across the generated server set.