middleware

Documentation

Overview

Package middleware 提供标准库形态的认证、授权与 CSRF 中间件， 可插拔到任何基于 net/http 的 Web 服务。

Index

• func Auth(signer *token.Signer, opts ...Option) func(http.Handler) http.Handler
• func CSRF(cookieName, headerName string, skipMethods ...string) func(http.Handler) http.Handler
• func CSRFProtect(cookieName, headerName string, opts ...CSRFOption) func(http.Handler) http.Handler
• func ClaimsFrom(ctx context.Context) (token.Claims, bool)
• func DefaultErrorHandler(w http.ResponseWriter, r *http.Request, status int, err error)
• func GenerateCSRFToken() (string, error)
• func RequirePermission(r *rbac.RBAC, permission string) func(http.Handler) http.Handler
• func RequireRole(r *rbac.RBAC, role string) func(http.Handler) http.Handler
• func RotateSession(w http.ResponseWriter, r *http.Request) error
• func Session(store session.Store, cookieName string, opts ...SessionOption) func(http.Handler) http.Handler
• func SessionFrom(ctx context.Context) (session.Session, bool)
• func UserID(ctx context.Context) string
• func ValidateCSRFToken(cookie, header string) bool
• type CSRFOption
  • func WithCSRFAllowedOrigins(origins ...string) CSRFOption
  • func WithCSRFClock(now func() time.Time) CSRFOption
  • func WithCSRFErrorHandler(handler ErrorHandler) CSRFOption
  • func WithCSRFHTTPOnly(httpOnly bool) CSRFOption
  • func WithCSRFPath(path string) CSRFOption
  • func WithCSRFSameSite(sameSite http.SameSite) CSRFOption
  • func WithCSRFSecure(secure bool) CSRFOption
  • func WithCSRFTTL(ttl time.Duration) CSRFOption
• type ErrorHandler
• type ErrorResponse
• type Option
  • func WithAuthErrorHandler(handler ErrorHandler) Option
  • func WithRealm(realm string) Option
• type SessionOption
  • func WithSessionClock(now func() time.Time) SessionOption
  • func WithSessionErrorHandler(handler ErrorHandler) SessionOption
  • func WithSessionHTTPOnly(httpOnly bool) SessionOption
  • func WithSessionLogger(logger logx.Logger) SessionOption
  • func WithSessionPath(path string) SessionOption
  • func WithSessionSameSite(sameSite http.SameSite) SessionOption
  • func WithSessionSecure(secure bool) SessionOption
  • func WithSessionSigningKey(key []byte) SessionOption
  • func WithSessionTTL(ttl time.Duration) SessionOption

Functions

func Auth

func Auth(signer *token.Signer, opts ...Option) func(http.Handler) http.Handler

Auth 构造 Bearer Token 认证中间件：解析并校验令牌，注入用户身份。 校验失败返回 401 标准响应；成功后继续处理链。

func CSRF

func CSRF(cookieName, headerName string, skipMethods ...string) func(http.Handler) http.Handler

CSRF 构造双提交 Cookie 校验中间件：非安全方法要求请求头与 Cookie 一致。

func CSRFProtect

func CSRFProtect(cookieName, headerName string, opts ...CSRFOption) func(http.Handler) http.Handler

CSRFProtect 构造双提交 Cookie 中间件：安全方法放行并保证已种令牌， 非安全方法要求请求头与 Cookie 令牌一致（常量时间比较）。

func ClaimsFrom

func ClaimsFrom(ctx context.Context) (token.Claims, bool)

ClaimsFrom 从请求上下文读取已认证用户的令牌载荷。

func DefaultErrorHandler

func DefaultErrorHandler(w http.ResponseWriter, r *http.Request, status int, err error)

DefaultErrorHandler 输出结构化 JSON 错误响应。

func GenerateCSRFToken

func GenerateCSRFToken() (string, error)

GenerateCSRFToken 生成 32 字节随机 base64url 令牌。

func RequirePermission

func RequirePermission(r *rbac.RBAC, permission string) func(http.Handler) http.Handler

RequirePermission 校验当前用户是否具备指定权限（须先经过 Auth 中间件）。 未认证返回 401，权限不足返回 403。

func RequireRole

func RequireRole(r *rbac.RBAC, role string) func(http.Handler) http.Handler

RequireRole 校验当前用户是否具备指定角色（须先经过 Auth 中间件）。

func RotateSession

func RotateSession(w http.ResponseWriter, r *http.Request) error

RotateSession 轮换当前会话 ID（防会话固定攻击），并同步更新 Cookie 与上下文。 仅在经过 Session 中间件的处理器中调用；未装配会话或读取会话失败时返回错误。

func Session

func Session(store session.Store, cookieName string, opts ...SessionOption) func(http.Handler) http.Handler

Session 构造会话中间件：读取/创建会话，请求结束后自动保存。 处理器内通过 SessionFrom 读取，修改 Values 后由中间件统一落库。

func SessionFrom

func SessionFrom(ctx context.Context) (session.Session, bool)

SessionFrom 从上下文读取会话。

func UserID

func UserID(ctx context.Context) string

UserID 返回已认证用户主体标识（未认证时为空字符串）。

func ValidateCSRFToken

func ValidateCSRFToken(cookie, header string) bool

ValidateCSRFToken 常量时间比较 Cookie 与请求头令牌；超长或空值直接拒绝。

Types

type CSRFOption

type CSRFOption func(*csrfOptions)

CSRFOption 双提交 CSRF 中间件配置项。

func WithCSRFAllowedOrigins

func WithCSRFAllowedOrigins(origins ...string) CSRFOption

WithCSRFAllowedOrigins 设置允许的跨站来源（Origin 精确匹配； 请求无 Origin 头时回退校验 Referer 的 scheme://host）。

func WithCSRFClock

func WithCSRFClock(now func() time.Time) CSRFOption

WithCSRFClock 注入时间源（测试用）。

func WithCSRFErrorHandler

func WithCSRFErrorHandler(handler ErrorHandler) CSRFOption

WithCSRFErrorHandler 自定义 CSRF 校验失败响应处理器。

func WithCSRFHTTPOnly

func WithCSRFHTTPOnly(httpOnly bool) CSRFOption

WithCSRFHTTPOnly 设置 CSRF Cookie HttpOnly 标记（默认 false，前端脚本需读取）。

func WithCSRFPath

func WithCSRFPath(path string) CSRFOption

WithCSRFPath 设置 CSRF Cookie 路径。

func WithCSRFSameSite

func WithCSRFSameSite(sameSite http.SameSite) CSRFOption

WithCSRFSameSite 设置 CSRF Cookie SameSite 策略。

func WithCSRFSecure

func WithCSRFSecure(secure bool) CSRFOption

WithCSRFSecure 设置 CSRF Cookie Secure 标记。

func WithCSRFTTL

func WithCSRFTTL(ttl time.Duration) CSRFOption

WithCSRFTTL 设置 CSRF Cookie 有效期（必须为正）。

type ErrorHandler

type ErrorHandler func(w http.ResponseWriter, r *http.Request, status int, err error)

ErrorHandler 自定义错误响应处理器；status 为建议 HTTP 状态码。

type ErrorResponse

type ErrorResponse struct {
	// Code 错误码（如 authx_token_invalid）。
	Code string `json:"code"`
	// Kind 错误分类（如 unauthorized / forbidden / unavailable）。
	Kind string `json:"kind"`
	// Message 面向用户的错误描述。
	Message string `json:"message"`
}

ErrorResponse 中间件统一 JSON 错误响应体（errx 语义）。

type Option

type Option func(*authOptions)

Option 认证中间件配置项。

func WithAuthErrorHandler

func WithAuthErrorHandler(handler ErrorHandler) Option

WithAuthErrorHandler 自定义认证失败响应处理器。

func WithRealm

func WithRealm(realm string) Option

WithRealm 设置 WWW-Authenticate 提示域。

type SessionOption

type SessionOption func(*sessionOptions)

SessionOption 会话中间件配置项。

func WithSessionClock

func WithSessionClock(now func() time.Time) SessionOption

WithSessionClock 注入时间源（测试用）。

func WithSessionErrorHandler

func WithSessionErrorHandler(handler ErrorHandler) SessionOption

WithSessionErrorHandler 自定义会话服务错误响应处理器。

func WithSessionHTTPOnly

func WithSessionHTTPOnly(httpOnly bool) SessionOption

WithSessionHTTPOnly 设置 Cookie HttpOnly 标记。

func WithSessionLogger

func WithSessionLogger(logger logx.Logger) SessionOption

WithSessionLogger 注入日志器：会话保存失败时记录告警（nil 表示不记录）。

func WithSessionPath

func WithSessionPath(path string) SessionOption

WithSessionPath 设置 Cookie 路径。

func WithSessionSameSite

func WithSessionSameSite(sameSite http.SameSite) SessionOption

WithSessionSameSite 设置 Cookie SameSite 策略。

func WithSessionSecure

func WithSessionSecure(secure bool) SessionOption

WithSessionSecure 设置 Cookie Secure 标记。

func WithSessionSigningKey

func WithSessionSigningKey(key []byte) SessionOption

WithSessionSigningKey 启用会话 Cookie 值 HMAC-SHA256 签名（防篡改/伪造会话 ID）。 密钥至少 16 字节；多实例部署时各实例必须使用同一密钥。

func WithSessionTTL

func WithSessionTTL(ttl time.Duration) SessionOption

WithSessionTTL 设置会话有效期（必须为正）。