Integration Builder

securityhttp is the top-level assembly package. It composes every security middleware into a single http.Handler through functional options that enforce fail-loud validation at assembly time.

Import

import "github.com/thuongh2/go-security/securityhttp"

Options and Assembly

All configuration goes through functional options passed to New() or NewHandler().

handler, err := securityhttp.NewHandler(app,
    securityhttp.WithSessionStore(store, users),
    securityhttp.WithLogin("/login", manager),
    securityhttp.WithAuthorize(authz.Routes(
        authz.Match("/admin/**").HasRole("ADMIN"),
        authz.AnyRequest().Authenticated(),
    )),
)
if err != nil {
    log.Fatal(err) // fail loud: an incomplete authz set never ships
}
http.ListenAndServe(":8443", handler)

NewHandler assembles the chain, wraps your http.Handler with the full security chain, and returns an http.Handler ready for http.ListenAndServe.

Option Functions

WithSessionStore

func WithSessionStore(s session.Store, users authn.UserService, cookie ...session.CookieConfig) Option

Enables session-backed authentication. Required before WithLogin.

s — any session.Store implementation (memory, or a distributed store)
users — reloaded on every request (SessionAuthentication), so a role change or a disabled/locked account takes effect immediately, never a stale cached principal
cookie — an optional session.CookieConfig that overrides the secure default (pass at most one)

Default cookie (session.DefaultCookieConfig()): SESSION=...; Path=/; Secure; HttpOnly; SameSite=Lax.

securityhttp.WithSessionStore(store, users, session.CookieConfig{
    Name:     "SESSION",
    Path:     "/",
    Secure:   true,
    HttpOnly: true,
    SameSite: http.SameSiteLaxMode,
    MaxAge:   3600,
})

WithLogin

func WithLogin(path string, m auth.Manager) Option

Mounts a JSON login endpoint at path (empty string uses "/login"), authenticated by m — an auth.Manager (the interface *authn.Manager satisfies). Requires WithSessionStore to be set; New/NewHandler return an error otherwise. On success it writes the session cookie via web/auth.LoginHandler.

manager := authn.NewManager([]authn.Provider{
    authn.NewPasswordProvider(users, encoder),
})

securityhttp.WithLogin("/login", manager)

There is no options parameter — request/response field names, redirects, and failure status are not configurable through the option. auth.LoginConfig (in web/auth) does have UsernameField / PasswordField / OnSuccess fields, but NewHandler only populates Manager, Store, and Cookie; to customize those, call auth.LoginHandler directly instead of WithLogin.

WithLoginThrottle

func WithLoginThrottle(t *ratelimit.LoginThrottle) Option

Fronts the login endpoint with a per-(username+IP) throttle, so credential stuffing is slowed without locking the account (that’s lockout’s job). Opt-in.

throttle, err := ratelimit.NewLoginThrottle(ratelimit.LoginThrottleOptions{
    Limiter: limiter, // a ratelimit.Limiter, e.g. NewTokenBucketLimiter
})
if err != nil {
    log.Fatal(err)
}

securityhttp.WithLoginThrottle(throttle)

WithCSRF

func WithCSRF(repo csrf.Repository) Option

Overrides the default session-backed synchronizer with a custom repository. The double-submit repository is useful for stateless APIs:

securityhttp.WithCSRF(csrf.NewDoubleSubmitRepository(csrfCookieOptions))

CSRFDisabled

func CSRFDisabled() Option

Disables CSRF entirely. Only for bearer-token APIs where session cookies are not used. Combining with WithLogin requires AllowLoginWithoutCSRF.

AllowLoginWithoutCSRF

func AllowLoginWithoutCSRF() Option

Suppresses the New() or NewHandler() error for WithLogin + CSRFDisabled. Use only when CSRF is enforced at the edge (gateway, CDN) and you’ve audited it.

WithCORS

func WithCORS(cfg cors.Config) Option

Enables CORS. New() or NewHandler() errors if credentials are enabled with a wildcard origin.

WithRateLimit

func WithRateLimit(cfg ratelimit.Config) Option

Adds the global per-IP rate-limit leg (ratelimit.Middleware). cfg.Limiter is required.

limiter, err := ratelimit.NewTokenBucketLimiter(ratelimit.Options{
    Capacity: 20,
})
if err != nil {
    log.Fatal(err)
}

securityhttp.WithRateLimit(ratelimit.Config{Limiter: limiter})

WithAuthorize

func WithAuthorize(mw middleware.Middleware, err error) Option

Takes a compiled authz route set from authz.Routes(). New() or NewHandler() surfaces the default-deny completeness error if the set has no AnyRequest() and no authz.AllowUnmatched(). The two-value form allows passing authz.Routes(...) directly — Go accepts a two-value function call as the argument list to a function taking two parameters, so no intermediate if err != nil check is needed:

securityhttp.WithAuthorize(authz.Routes(
    authz.Match("/admin/**").HasRole("ADMIN"),
    authz.AnyRequest().Authenticated(),
))

AllowUnmatched is an authz.RoutesOption passed into authz.Routes(...) as an argument:

authz.Routes(
    authz.AllowUnmatched(),
    authz.Match("/admin/**").HasRole("ADMIN"),
)

WithHeaders

func WithHeaders(opts ...middleware.HeaderOption) Option

Extends the default security headers. HSTS example:

securityhttp.WithHeaders(middleware.WithHSTS(31536000, true, true))

WithObserve

func WithObserve(h observe.Hooks) Option

Wires metrics and structured-log hooks through the chain — a denied authorization increments observe.EventAccessDenied, a 429 increments observe.EventRateLimited, and so on. Only the fixed, low-cardinality Event enum is ever recorded — never a username, IP, or token.

securityhttp.WithObserve(observe.Hooks{Metrics: observe.SlogMetrics{Logger: logger}})

WithAnonymous

func WithAnonymous(authorities ...core.Authority) Option

Overrides the authorities granted to the anonymous token injected for unauthenticated callers (default: ROLE_ANONYMOUS).

securityhttp.WithAnonymous(core.Roles("GUEST")...)

Not (yet) on the Options

Logout and remember-me are real go-security features, but the options don’t wire them in yet — mount them yourself against the handler returned by NewHandler():

Logout: web/auth.LogoutHandler(web/auth.LogoutConfig{...})
Remember-me: web/rememberme.NewTokenBased(web/rememberme.TokenBasedConfig{...})

New vs NewHandler

// Returns a Chain you can mount in a custom mux
chain, err := securityhttp.New(opts...)

// Returns http.Handler — wraps your app directly
handler, err := securityhttp.NewHandler(app, opts...)

Both fail on misconfiguration rather than returning a half-wired handler.

Middleware ordering

The chain enforces a security-correct fixed order. SessionAuthentication runs before CSRF so the synchronizer token can be located on the session, and Login is mounted inside the chain (via pathMux) so CSRF still applies to the login POST: Login is mounted inside your handler (at the path you specified), so CSRF protection applies to the login POST.

Validation at Assembly Time

New() / NewHandler() return an error for:

Condition	Error
`WithLogin()` without `WithSessionStore()`	”Login requires a SessionStore”
`WithLogin()` without a Manager	”Login requires a Manager”
`WithLogin()` + `CSRFDisabled()` without `AllowLoginWithoutCSRF()`	”login-CSRF risk”
`WithAuthorize()` with no catch-all and no `authz.AllowUnmatched()`	”no AnyRequest rule”
CORS credentials + wildcard origin	”credentials with wildcard origin”

Always-on defaults

Every chain assembled with New() or NewHandler() includes, at zero configuration cost:

Feature	Default
`X-Content-Type-Options: nosniff`	Always
`X-Frame-Options: DENY`	Always
`Referrer-Policy: no-referrer`	Always
Secure session cookie	When `WithSessionStore()` is set
CSRF synchronizer token	When `WithSessionStore()` is set
Default-deny authorization	`New()` / `NewHandler()` error without a catch-all

Foundation

Authentication

Authorization

Session & Cookies

OAuth2 & JWT

HTTP Layer

Resilience

Observability

Distributed Stores

Import

Options and Assembly

Option Functions

WithSessionStore

WithLogin

WithLoginThrottle

WithCSRF

CSRFDisabled

AllowLoginWithoutCSRF

WithCORS

WithRateLimit

WithAuthorize

WithHeaders

WithObserve

WithAnonymous

Not (yet) on the Options

New vs NewHandler

Middleware ordering

Validation at Assembly Time

Always-on defaults

​Import

​Options and Assembly

​Option Functions

​WithSessionStore

​WithLogin

​WithLoginThrottle

​WithCSRF

​CSRFDisabled

​AllowLoginWithoutCSRF

​WithCORS

​WithRateLimit

​WithAuthorize

​WithHeaders

​WithObserve

​WithAnonymous

​Not (yet) on the Options

​New vs NewHandler

​Middleware ordering

​Validation at Assembly Time

​Always-on defaults

Import

Options and Assembly

Option Functions

WithSessionStore

WithLogin

WithLoginThrottle

WithCSRF

CSRFDisabled

AllowLoginWithoutCSRF

WithCORS

WithRateLimit

WithAuthorize

WithHeaders

WithObserve

WithAnonymous

Not (yet) on the Options

New vs NewHandler

Middleware ordering

Validation at Assembly Time

Always-on defaults