README
¶
authx
工业级认证与授权组件库，与 errx / logx / tracex 家族打通：
- 密码哈希：Argon2id（RFC 9106），支持参数迁移与常量时间比较；
- 令牌：JWT 全套算法（HS/RS/ES/EdDSA）、刷新令牌、撤销列表；
- 授权：RBAC 角色/权限模型（支持角色继承与环检测）；
- 集成：标准 net/http 认证/权限/CSRF 中间件
（
func(http.Handler) http.Handler，可插拔到任意标准库 Web 服务）； - 会话：Session 存储接口 + 内存实现 + 标准会话中间件（自动落库）；
- 多因素：TOTP（RFC 6238）与恢复码；
- OAuth2：客户端（授权码 + PKCE）与服务端（授权码 + PKCE + 刷新令牌）；
- 审计：结构化审计日志（logx 集成）+ 持久化钩子；
- 安全：登录失败计数、账号锁定、滑动窗口清理。
质量基线：核心包 100% 语句覆盖、九目标 fuzz （password/token/rbac/mfa/session/security/audit/middleware/oauth2）、 race 检测、三平台 CI + govulncheck 依赖漏洞扫描、全套基准测试。
目录
authx/
├── errors.go / config.go # errx 错误码与全局配置
├── password/ # Argon2id 哈希、校验、参数迁移
├── token/ # JWT 全套算法、刷新令牌、撤销列表
├── rbac/ # 角色/权限模型、角色继承
├── middleware/ # 标准 net/http 认证/权限/CSRF/会话中间件
├── session/ # 会话模型与存储接口
├── mfa/ # TOTP 与恢复码
├── oauth2/ # OAuth2 客户端与授权服务端
├── audit/ # 结构化审计日志
├── security/ # 登录防爆破守卫
├── examples/full/ # 全套组合示例
└── examples/login-demo/ # 登录全链路演示（注册/会话/CSRF/RBAC/JWT/MFA/OAuth2）
完整错误码清单见 ERRORS.md。
安装
go get github.com/lcylpzls/authx
快速开始
import (
"time"
"github.com/lcylpzls/authx"
"github.com/lcylpzls/authx/password"
"github.com/lcylpzls/authx/token"
)
// 密码哈希：哈希、校验、参数迁移。
hash, err := password.Hash("password123", authx.DefaultPasswordConfig())
ok, err := password.Verify(hash, "password123")
// 访问令牌：签发与校验。
signer, err := token.NewHS256([]byte("0123456789abcdef0123456789abcdef"),
token.WithIssuer("myapp"), token.WithTTL(15*time.Minute))
raw, err := signer.Sign("u-1001", token.WithRoles("admin"))
claims, err := signer.Parse(raw)
// 完整登录流程（会话/CSRF/RBAC/JWT/MFA/OAuth2/审计）见 examples/login-demo。
内存存储周期清理
所有内存存储（会话、刷新令牌、撤销列表、恢复码、登录守卫）均提供
StartCleanup，可自动回收过期条目：
// 刷新令牌存储每 10 分钟清理一次过期哈希。
refreshStore := token.NewMemoryRefreshStore(nil)
cleanup := refreshStore.StartCleanup(10 * time.Minute)
defer cleanup.Stop()
// 会话存储同理。
sessStore := session.NewMemoryStore(nil)
sessCleanup := sessStore.StartCleanup(10 * time.Minute)
defer sessCleanup.Stop()
存储默认容量上限 10 万条，满时新增条目返回 ErrStoreFull；
可通过 NewXxxWithLimit 或 WithMaxEntries 调整。
版本路线
| 版本 | 内容 |
|---|---|
| v0.1.0 | password：Argon2id 哈希、校验、参数迁移（已发布） |
| v0.2.0 | token：JWT 全套、刷新令牌、撤销（已发布） |
| v0.3.0 | rbac + middleware：webx 认证/权限/CSRF（已发布） |
| v0.4.0 | session + mfa：会话与 TOTP（已发布） |
| v0.5.0 | oauth2：客户端与授权码/PKCE 服务端（已发布） |
| v0.6.0 | audit + security：审计、锁定、频控与 full 示例（已发布，版本线完成） |
| v0.7.0 | 防 DoS 与资源上限：容量上限、周期清理、输入上限、随机源失败报错（已发布） |
| v0.8.0 | 会话与 CSRF 加固：会话轮换、保存失败日志、CSRF 令牌、Auth 上限与转义（已发布） |
| v0.9.0 | 密码学完整化：TOTP 算法/位数/周期、恢复码存储、密码强度、JWT leeway（已发布） |
| v0.10.0 | 令牌生命周期：kid 多密钥轮换、刷新令牌轮换助手、存储文档与清理示例（已发布） |
| v0.11.0 | OAuth2 与审计加固：客户端刷新助手、响应上限、Basic Auth、审计限长与钩子隔离（已发布） |
| v0.12.0 | 质量收口：六目标 fuzz、govulncheck、基准测试、SECURITY、终审加固（已发布，版本线完成） |
| v0.13.0 | 中间件错误响应工业化：统一 errx 结构化 JSON、可注入错误处理器（已发布） |
| v0.14.0 | 审计异步化：AsyncAuditor 批量落库、丢弃/阻塞策略、优雅关闭（已发布） |
| v0.15.0 | OAuth2 服务端可插拔存储：WithClientStore/WithTokenStore 多实例就绪（已发布） |
| v0.16.0 | 会话与 CSRF 纵深防御：Cookie HMAC 签名、Origin/Referer 校验（已发布） |
| v0.17.0 | 全链路示例与文档定稿：login-demo、ERRORS.md、README 核对（已发布） |
| v0.18.0 | 边界与并发打磨：TTL 精确边界矩阵、并发 bench、九目标 fuzz（已发布） |
| v0.19.0 | 发布前终审：清理任务 panic 恢复、依赖整理、并发/泄漏终审（已发布，版本线完成） |
| v1.0.0 | 正式版：进入语义化版本稳定期，v1.x 起承诺无破坏性 API 变更（已发布） |
版本策略说明：自家族统一约定起，破坏性变更走 minor 版本 （不强制主版本升级），实际变更以 CHANGELOG 为准。
规范
- 所有日志、打印、注释与文档使用简体中文；
- 错误统一走 errx 语义（401/403 与业务错误码对齐）；
- 核心包每版本 100% 语句覆盖、race、fuzz、三平台 CI + Release；
- examples 为可执行演示（
go test ./examples/full验证）。
Documentation
¶
Overview ¶
Package authx 提供认证授权基座（令牌、会话、密码、MFA、RBAC、OAuth2 与标准中间件）。 实现主体位于 internal/core；token/session/password/mfa/rbac/security/audit/oauth2/middleware 为公开子包。
Index ¶
Constants ¶
View Source
const ( CodePasswordHashInvalid = core.CodePasswordHashInvalid CodePasswordMismatch = core.CodePasswordMismatch CodePasswordTooLong = core.CodePasswordTooLong CodePasswordTooShort = core.CodePasswordTooShort CodePasswordConfigInvalid = core.CodePasswordConfigInvalid CodePasswordInternal = core.CodePasswordInternal CodeTokenInvalid = core.CodeTokenInvalid CodeTokenExpired = core.CodeTokenExpired CodeTokenSignature = core.CodeTokenSignature CodeTokenRevoked = core.CodeTokenRevoked CodeTokenConfigInvalid = core.CodeTokenConfigInvalid CodeRefreshTokenInvalid = core.CodeRefreshTokenInvalid CodeStoreInvalid = core.CodeStoreInvalid CodeForbidden = core.CodeForbidden CodeRBACRoleNotFound = core.CodeRBACRoleNotFound CodeRBACRoleExists = core.CodeRBACRoleExists CodeRBACCycle = core.CodeRBACCycle CodeRBACInvalid = core.CodeRBACInvalid CodeCSRFMismatch = core.CodeCSRFMismatch CodeSessionNotFound = core.CodeSessionNotFound CodeSessionInvalid = core.CodeSessionInvalid CodeSessionStoreInvalid = core.CodeSessionStoreInvalid CodeMFAInvalid = core.CodeMFAInvalid CodeMFAConfigInvalid = core.CodeMFAConfigInvalid CodeOAuth2Invalid = core.CodeOAuth2Invalid CodeOAuth2ConfigInvalid = core.CodeOAuth2ConfigInvalid CodeSecurityConfigInvalid = core.CodeSecurityConfigInvalid CodeStoreFull = core.CodeStoreFull CodeRBACLimit = core.CodeRBACLimit CodeCSRFGenerationFailed = core.CodeCSRFGenerationFailed CodePasswordTooWeak = core.CodePasswordTooWeak CodeTokenMissing = core.CodeTokenMissing CodeAuditQueueFull = core.CodeAuditQueueFull )
Variables ¶
View Source
var ( ErrPasswordHashInvalid = core.ErrPasswordHashInvalid ErrPasswordMismatch = core.ErrPasswordMismatch ErrPasswordTooLong = core.ErrPasswordTooLong ErrPasswordTooShort = core.ErrPasswordTooShort ErrTokenInvalid = core.ErrTokenInvalid ErrTokenExpired = core.ErrTokenExpired ErrTokenSignature = core.ErrTokenSignature ErrTokenRevoked = core.ErrTokenRevoked ErrRefreshTokenInvalid = core.ErrRefreshTokenInvalid ErrForbidden = core.ErrForbidden ErrRoleNotFound = core.ErrRoleNotFound ErrRoleExists = core.ErrRoleExists ErrCycle = core.ErrCycle ErrRBACInvalid = core.ErrRBACInvalid ErrCSRFMismatch = core.ErrCSRFMismatch ErrSessionNotFound = core.ErrSessionNotFound ErrSessionInvalid = core.ErrSessionInvalid ErrSessionStoreInvalid = core.ErrSessionStoreInvalid ErrMFAInvalid = core.ErrMFAInvalid ErrMFAConfigInvalid = core.ErrMFAConfigInvalid ErrOAuth2Invalid = core.ErrOAuth2Invalid ErrOAuth2ConfigInvalid = core.ErrOAuth2ConfigInvalid ErrSecurityConfigInvalid = core.ErrSecurityConfigInvalid ErrStoreFull = core.ErrStoreFull ErrRBACLimit = core.ErrRBACLimit ErrCSRFGenerationFailed = core.ErrCSRFGenerationFailed ErrPasswordTooWeak = core.ErrPasswordTooWeak ErrTokenMissing = core.ErrTokenMissing ErrAuditQueueFull = core.ErrAuditQueueFull )
Functions ¶
This section is empty.
Types ¶
type CleanupHandle ¶ added in v0.7.0
type CleanupHandle = core.CleanupHandle
func StartCleanup ¶ added in v0.7.0
func StartCleanup(interval time.Duration, fn func() int) *CleanupHandle
type PasswordConfig ¶
type PasswordConfig = core.PasswordConfig
func DefaultPasswordConfig ¶
func DefaultPasswordConfig() PasswordConfig
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package audit 提供结构化审计日志（logx 集成）。
|
Package audit 提供结构化审计日志（logx 集成）。 |
|
internal
|
|
|
core
Package authx 提供工业级认证与授权组件，与 errx / logx / webx 深度集成。
|
Package authx 提供工业级认证与授权组件，与 errx / logx / webx 深度集成。 |
|
Package mfa 提供 TOTP（RFC 6238）与恢复码。
|
Package mfa 提供 TOTP（RFC 6238）与恢复码。 |
|
Package middleware 提供标准库形态的认证、授权与 CSRF 中间件， 可插拔到任何基于 net/http 的 Web 服务。
|
Package middleware 提供标准库形态的认证、授权与 CSRF 中间件， 可插拔到任何基于 net/http 的 Web 服务。 |
|
Package oauth2 提供 OAuth2/OIDC 客户端与服务端。
|
Package oauth2 提供 OAuth2/OIDC 客户端与服务端。 |
|
Package password 提供 Argon2id 密码哈希、校验与参数迁移。
|
Package password 提供 Argon2id 密码哈希、校验与参数迁移。 |
|
Package rbac 提供轻量角色-权限模型，支持角色继承与并发安全。
|
Package rbac 提供轻量角色-权限模型，支持角色继承与并发安全。 |
|
Package security 提供登录防护：失败计数、账号锁定与窗口清理。
|
Package security 提供登录防护：失败计数、账号锁定与窗口清理。 |
|
Package session 提供会话数据模型与存储接口（可接 Redis 等外部实现）。
|
Package session 提供会话数据模型与存储接口（可接 Redis 等外部实现）。 |
|
Package token 提供 JWT 全套算法的签发、校验、撤销与刷新令牌。
|
Package token 提供 JWT 全套算法的签发、校验、撤销与刷新令牌。 |
Click to show internal directories.
Click to hide internal directories.