session

Documentation

Overview

Package session provides cookie helpers for auth flows. Package session 提供认证流程的 cookie 辅助函数。

Usage (Double-submit CSRF) / 用法（双提交 CSRF）:

csrf := uuid.NewString()
SetCSRFCookie(w, csrf, exp, CookieConfig{Name: DefaultCSRFCookieName, Path: "/"})
// Client sends header: X-CSRF-Token: <csrf>
ok := ValidateDoubleSubmit(r, DefaultCSRFCookieName, DefaultCSRFHeaderName)

Index

• Constants
• func ClearCookie(w http.ResponseWriter, cfg CookieConfig)
• func ReadCookie(r *http.Request, name string) string
• func SetCSRFCookie(w http.ResponseWriter, token string, exp time.Time, cfg CookieConfig)
• func SetRefreshCookie(w http.ResponseWriter, token string, exp time.Time, cfg CookieConfig)
• func ValidateDoubleSubmit(r *http.Request, cookieName, headerName string) bool
• type CookieConfig
  • func DefaultCookieConfig(r *http.Request, opts CookieTrustOptions) CookieConfig
• type CookieTrustOptions

Constants

const (
	DefaultRefreshCookieName = "refresh"
	DefaultCSRFCookieName    = "csrf"
	DefaultCSRFHeaderName    = "X-CSRF-Token"
)

Functions

func ClearCookie

func ClearCookie(w http.ResponseWriter, cfg CookieConfig)

ClearCookie removes a cookie. ClearCookie 删除 cookie。

func ReadCookie

func ReadCookie(r *http.Request, name string) string

ReadCookie returns the cookie value. Missing cookies return an empty string. ReadCookie 返回 cookie 值。 缺失 cookie 时返回空字符串。

func SetCSRFCookie

func SetCSRFCookie(w http.ResponseWriter, token string, exp time.Time, cfg CookieConfig)

SetCSRFCookie writes the CSRF token cookie. SetCSRFCookie 写入 CSRF token cookie。

func SetRefreshCookie

func SetRefreshCookie(w http.ResponseWriter, token string, exp time.Time, cfg CookieConfig)

SetRefreshCookie writes the refresh token cookie. SetRefreshCookie 写入 refresh token cookie。

func ValidateDoubleSubmit

func ValidateDoubleSubmit(r *http.Request, cookieName, headerName string) bool

ValidateDoubleSubmit compares the CSRF cookie and header. ValidateDoubleSubmit 比较 CSRF cookie 与 header。

Types

type CookieConfig

type CookieConfig struct {
	Name        string
	Path        string
	Domain      string
	Secure      bool
	SameSite    http.SameSite
	SessionOnly bool
}

CookieConfig configures auth cookies. CookieConfig 配置认证 cookie。

func DefaultCookieConfig

func DefaultCookieConfig(r *http.Request, opts CookieTrustOptions) CookieConfig

DefaultCookieConfig derives Secure and SameSite from r. TLS is always trusted. X-Forwarded-Proto is trusted only for TrustedProxies. DefaultCookieConfig 从 r 推导 Secure 与 SameSite。 TLS 总是可信；X-Forwarded-Proto 仅对 TrustedProxies 生效。

type CookieTrustOptions

type CookieTrustOptions struct {
	TrustedProxies []netip.Prefix
}

CookieTrustOptions configures forwarded-proto trust. CookieTrustOptions 配置转发协议头信任边界。