middleware

func AuditInterceptor ¶

func AuditInterceptor(logger *slog.Logger, claimsFrom ClaimsLookup) connect.Interceptor

AuditInterceptor creates a Connect interceptor that produces audit log entries for every RPC call. Audit logs capture: who made the call (user ID — the email goes to the durable sink only, never to slog), what procedure was called, when, the result (success/error code), the duration, and the OTel trace id when the request carries a span.

Audit records are emitted with log_type=audit on a child logger, so they can be routed to a dedicated audit sink (separate file, SIEM, compliance database) independent of operational logs. The record message is "audit.event" ([auditMessage]) — INFO on success, WARN on error.

claimsFrom is the project's ClaimsFromContext (the project owns the claims context key — see ClaimsLookup). When nil, or when no claims are present (unauthenticated request), the user is logged as "anonymous".

This is the slog-only constructor; it is fully backward compatible. For compliance-grade durable persistence (so projects can delete a hand-rolled DB-persisting interceptor), use AuditInterceptorWithSink to additionally fan each event out to an AuditSink.

func AuditInterceptorWithSink ¶

func AuditInterceptorWithSink(logger *slog.Logger, claimsFrom ClaimsLookup, sink AuditSink) connect.Interceptor

AuditInterceptorWithSink is AuditInterceptor plus a durable sink. Every RPC is logged to slog exactly as the slog-only variant does AND dispatched to sink.Record on a fresh bounded-timeout context off the request path, so the sink never blocks the RPC response. Passing a nil sink yields behavior identical to AuditInterceptor.

func CORSMiddleware ¶

func CORSMiddleware(allowOrigins []string, allowCredentials bool, opts ...CORSOption) func(http.Handler) http.Handler

CORSMiddleware returns an HTTP middleware that applies the CORS policy described by allowOrigins and allowCredentials.

Semantics (per the Fetch / CORS specs):

• When the request has no Origin header, no CORS headers are written and the request is passed through. Emitting ACAO with an empty value (or "*") on a same-origin request is a well-known footgun: the browser never needed CORS on it in the first place, and some caches key on the ACAO value.

• When allowOrigins contains "*" AND allowCredentials is true, this middleware panics. The combination is spec-invalid (browsers reject it) and must be caught at config validation time (the scaffolded config.Validate does). The panic is a belt-and- suspenders guard if validation is bypassed.

• When allowOrigins contains "*" and credentials are disabled, the request Origin is echoed back rather than a literal "*". Echoing keeps the response compatible with future credentialed callers (no silent breakage) and still satisfies "*" semantically.

• When specific origins are listed, an exact (case-insensitive) match on the Origin header is required. No match → no CORS headers (the browser will block the response).

Vary: Origin is always set so intermediate caches key on the Origin.

The allowed request headers and the exposed response headers default to what Connect, forge's frontend runtime and tracing need (DefaultCORSAllowHeaders, DefaultCORSExposeHeaders). A project whose client sends or reads more extends them with WithAllowHeaders / WithExposeHeaders — see CORSOption for why that has to be the middleware's job.

func ContextWithRequestID ¶

func ContextWithRequestID(ctx context.Context, id string) context.Context

ContextWithRequestID returns a copy of ctx with the given request ID attached. Exposed so tests and non-HTTP entrypoints can propagate the value into code paths that read RequestIDFromContext.

func DevCORSMiddleware ¶

func DevCORSMiddleware(allowCredentials bool, opts ...CORSOption) func(http.Handler) http.Handler

DevCORSMiddleware returns an HTTP middleware that reflects ANY request Origin back to the caller — an allow-all CORS policy intended for LOCAL DEVELOPMENT ONLY. It exists so a freshly-forged product's browser frontend works cross-origin out of the box, without the author first hand-curating a CORS_ORIGINS allow-list.

Why this instead of passing "*" to CORSMiddleware:

• Credential-safe. It always echoes the CONCRETE request Origin into Access-Control-Allow-Origin (never the literal "*"), so pairing it with Access-Control-Allow-Credentials: true stays spec-valid. The "*" path in CORSMiddleware, by contrast, panics when credentials are enabled (the wildcard+credentials combination is spec-invalid and rejected in prod).

• Unambiguously dev-scoped. The generated server selects it ONLY when ENVIRONMENT=development, so the permissive behavior can never leak into a production build the way a stray "*" in a prod allow-list could.

It MUST NOT be wired outside development. Reflecting every origin (especially with credentials) is exactly the footgun CORSMiddleware guards against for real deployments.

It takes the same header options as CORSMiddleware and applies them the same way. Reflecting whatever headers a dev request asks for would make dev pass a header that production then refuses — the exact gap that let a web client header take a deployed app down — so dev and production allow one list.

func HTTPAuth ¶

func HTTPAuth(
	authenticate func(token string) (*auth.Claims, error),
	withClaims func(ctx context.Context, claims *auth.Claims) context.Context,
) func(http.Handler) http.Handler

HTTPAuth returns HTTP middleware that validates Bearer tokens and populates the context with claims, mirroring the Connect auth interceptor for plain HTTP routes.

authenticate validates the raw token and returns the claims — pass the project's ValidateToken. withClaims stashes them on the context — pass the project's ContextWithClaims (the project owns the claims context key). If authenticate is nil (dev mode), all requests are allowed through untouched.

func HTTPStack ¶

func HTTPStack(logger *slog.Logger, claimsFrom ClaimsLookup) func(http.Handler) http.Handler

HTTPStack returns HTTP middleware that applies recovery, logging, and audit to plain HTTP handlers. This provides the same cross-cutting concerns as the Connect interceptors for routes that cannot use the Connect protocol (e.g. webhooks, OAuth callbacks, REST endpoints).

claimsFrom is the project's ClaimsFromContext (see ClaimsLookup); nil produces anonymous audit entries.

Auth is NOT included because REST routes often have different auth requirements (e.g. webhook signature verification instead of JWT). Use HTTPAuth separately for routes that need Bearer authentication.

func HeaderList ¶

func HeaderList(csv string) []string

HeaderList splits a comma-separated header list (a config value) into names, dropping blanks. For WithAllowHeaders / WithExposeHeaders.

func IdempotencyInterceptor ¶

func IdempotencyInterceptor(opts IdempotencyOptions) connect.Interceptor

IdempotencyInterceptor returns a Connect interceptor that deduplicates requests carrying an Idempotency-Key header. If the same key is seen within the TTL window, the cached response (or error) is returned without calling the handler again.

Keys are scoped per-procedure so the same key on different RPCs is treated as distinct. For the HTTP-layer equivalent (REST/webhook routes) see IdempotencyMiddleware.

When opts.CacheSize <= 0 the interceptor is disabled and nil is returned.

func IdempotencyMiddleware ¶

func IdempotencyMiddleware(cfg IdempotencyConfig) func(http.Handler) http.Handler

IdempotencyMiddleware returns an http.Handler that deduplicates requests carrying the same key. If a request with that key has already been served (and is still cached), the cached response is replayed without invoking the downstream handler.

By default the key is the Idempotency-Key header and every completed response is cached; IdempotencyConfig.Key and IdempotencyConfig.ShouldCache override each half independently.

Usage:

mux := http.NewServeMux()
cfg := middleware.IdempotencyConfig{CacheSize: 500, TTL: 30 * time.Minute}
handler := middleware.IdempotencyMiddleware(cfg)(mux)

The cache is bounded (LRU over CacheSize entries) and PER-PROCESS: two replicas each keep their own, so a duplicate routed to the other replica is served fresh. Replay also happens BEFORE the wrapped handler runs, so a route that authenticates inside the handler (a webhook verifying its signature) answers unauthenticated duplicates from the cache. When either property matters, deduplicate inside the handler instead — see DedupeStore for the boolean-shaped seam that swaps for a table.

func RateLimitInterceptor ¶

func RateLimitInterceptor(opts RateLimitOptions, claimsFrom ClaimsLookup) connect.Interceptor

RateLimitInterceptor returns a Connect interceptor that enforces a per-key token-bucket rate limit. Keys are derived in this order:

1. authenticated claim subject (claims.UserID) via claimsFrom, if available
2. peer IP from the Connect request/stream peer address

When opts.Rps <= 0 the interceptor is disabled and this function returns nil. Memory is bounded by an LRU cache of up to rateLimitCacheSize limiters; idle keys are evicted in LRU order so the interceptor is safe to expose to anonymous traffic. claimsFrom may be nil (all callers are then keyed by peer IP).

func Redact ¶

func Redact(v any, fields ...string) map[string]any

Redact accepts a struct (or pointer to struct) and a set of field names to mask. It returns a map[string]any mirroring the struct's exported fields, with the named fields replaced by "[REDACTED]".

Non-struct inputs return nil. Unexported fields are silently skipped.

Example:

type User struct {
    ID    string
    Email string
    Name  string
}
out := middleware.Redact(User{ID: "1", Email: "a@b.c", Name: "Alice"}, "Email")
// out == map[string]any{"ID": "1", "Email": "[REDACTED]", "Name": "Alice"}

func RequestIDFromContext ¶

func RequestIDFromContext(ctx context.Context) string

RequestIDFromContext returns the request ID attached to ctx, or "" if none is set. Useful for handlers and downstream logging sites that want to include the ID on custom log lines. Nil ctx returns "" (never panics) so callers in CLI/worker contexts can share the same helper.

The storage is pkg/observe's context key: a request ID set by this HTTP middleware is visible to observe.LoggingInterceptor (and vice versa) without a header round-trip.

func RequestIDMiddleware ¶

func RequestIDMiddleware() func(http.Handler) http.Handler

RequestIDMiddleware is an HTTP middleware that ensures every request carries a correlation ID. It must be wired ahead of the logging middleware so log records inherit the generated ID.

Behavior:

• If the inbound request has a non-empty RequestIDHeader, that value is trusted and reused. This lets edge proxies and upstream services stitch together a single trace across hops without coordination.

• Otherwise a 16-byte crypto/rand hex token is minted — the same shape observe.RequestIDInterceptor mints at the Connect layer, so IDs look uniform whichever layer assigned them. crypto/rand keeps IDs unpredictable to third parties that might otherwise enumerate them.

• The chosen ID is exposed to downstream middleware/handlers via the request context (RequestIDFromContext), stamped back onto the INBOUND request header, and echoed on the response header so the client can log it for later correlation.

This middleware OWNS the response echo for every request that passes through it. observe.RequestIDInterceptor, which runs inside it on the Connect path, adopts the context value and deliberately writes no response header of its own — otherwise connect merges its header into the one already written here and the response carries two conflicting X-Request-Id values.

The inbound stamp exists for the same reason: handlers and interceptors that reach for the request header rather than the context must see the SAME id, not an empty string that invites them to mint another.

func SecurityHeadersMiddleware ¶

func SecurityHeadersMiddleware(cfg SecurityHeadersConfig) func(http.Handler) http.Handler

SecurityHeadersMiddleware returns an HTTP middleware that sets OWASP-recommended security response headers:

• Content-Security-Policy — locks down what the browser may load
• X-Content-Type-Options: nosniff — prevents MIME sniffing
• Referrer-Policy — limits Referer leakage
• Permissions-Policy — opts out of powerful browser APIs
• Strict-Transport-Security — forces HTTPS (production only)

Headers relevant to health/pprof endpoints (health checks don't need CSP stringency, but we still set nosniff/referrer/permissions there for consistency and defense in depth). Callers wire this in at the outermost HTTP layer so every response benefits — including /healthz, /readyz, /metrics, and REST/webhook routes that bypass the Connect interceptor chain.

When cfg.Enabled is false, this becomes a no-op.

func VerifyHMACSHA256 ¶

func VerifyHMACSHA256(body []byte, signature, secret string) bool

VerifyHMACSHA256 reports whether signature is a valid HMAC-SHA256 of body under secret. signature is hex, with or without the "sha256=" prefix some providers (GitHub) prepend, in either letter case.

The comparison is constant-time, and a malformed signature is a plain false rather than an error, so call sites stay a single `if`:

if !middleware.VerifyHMACSHA256(body, r.Header.Get("X-Signature-256"), secret) {
    http.Error(w, "unauthorized", http.StatusUnauthorized)
    return
}

An empty secret always fails: an unconfigured secret must not silently turn signature verification into a no-op.

func WebhookEventID ¶

func WebhookEventID(headers http.Header) string

WebhookEventID returns the sender's unique delivery ID from the first recognised header, or "" when none is present.

Providers do not agree on a header, and none of them use the Idempotency-Key convention that REST clients follow, so this covers the common ones: the generic X-Event-ID / X-Webhook-ID / X-Request-ID spellings plus Stripe-Event-Id and X-GitHub-Delivery. A provider that stamps something else is one header read away — pull it directly and fall back to this:

id := r.Header.Get("X-Acme-Delivery")
if id == "" {
    id = middleware.WebhookEventID(r.Header)
}