Documentation
¶
Overview ¶
Package account 提供前台账户体系:自助注册、邮箱验证、找回密码与账户页。
它不引入自己的用户表——注册用户落核心的 `users` 表,只授内置角色 `member`。 理由是复用:会话、登录限流、argon2 并发闸门、改密踢下线这些都已经是核心的现成实现, 另起一张访客表要把它们再写一遍,而且内容与评论的归属要各认一次。
本模块**不实现 app.RouteProvider**:它产出的是 HTML 表单而不是 REST 接口, 进不了三平面(与 theme 同理)。页面由 MountFrontend 直接挂在根路由上。
Index ¶
- Constants
- Variables
- func ReservedPaths() []string
- type CSRF
- type Limiter
- type Module
- func (m *Module) EnsureFormCSRF(w http.ResponseWriter, r *http.Request) string
- func (m *Module) Migrations() fs.FS
- func (m *Module) MountFrontend(r chi.Router, optional func(http.Handler) http.Handler)
- func (m *Module) Name() string
- func (m *Module) Register(a *app.App) error
- func (m *Module) Routes(r app.Router)
- func (m *Module) Settings() []app.SettingGroup
- func (m *Module) Start(ctx context.Context) error
- func (m *Module) Store() *Store
- func (m *Module) Tokens() *TokenStore
- type Settings
- type Store
- func (s *Store) FindByEmail(ctx context.Context, email string) (*userRow, error)
- func (s *Store) FindVerifiedByEmail(ctx context.Context, email string) (*userRow, error)
- func (s *Store) MarkEmailVerified(ctx context.Context, userID int64) error
- func (s *Store) UpdateAvatar(ctx context.Context, userID int64, url string) error
- func (s *Store) UpdateBanner(ctx context.Context, userID int64, url string) error
- func (s *Store) UpdateProfile(ctx context.Context, userID int64, displayName, bio string) error
- type Token
- type TokenStore
- func (s *TokenStore) Check(ctx context.Context, plaintext, purpose string) (int64, error)
- func (s *TokenStore) Consume(ctx context.Context, plaintext, purpose string) (int64, error)
- func (s *TokenStore) DeleteExpired(ctx context.Context, retention time.Duration) (int64, error)
- func (s *TokenStore) Issue(ctx context.Context, userID int64, purpose string, ttl time.Duration) (string, error)
Constants ¶
const ( // VerifyEmailTTL 是邮箱验证链接的有效期。 // // 给足 48 小时是因为验证邮件经常被投进垃圾箱,用户隔一天才想起来翻; // 而验证链接只证明邮箱可达,风险与重置链接不在一个量级。 VerifyEmailTTL = 48 * time.Hour // ResetPasswordTTL 是密码重置链接的有效期。 // // 与验证链接差两个数量级,因为重置链接能在不知道原密码的情况下改掉密码—— // 邮件被别人翻出来时的破坏力大得多。 ResetPasswordTTL = 2 * time.Hour )
令牌有效期。做成代码常量而不是设置项:这两个数字站长改一次就再也不会动, 而每多一个设置项就多一处要解释、要翻译、要写文档的地方。
const ( PathLogin = "/login" PathRegister = "/register" PathVerifyEmail = "/verify-email" PathForgotPassword = "/forgot-password" PathResetPassword = "/reset-password" PathAccount = "/account" // PathAccountProfile 是个人中心里改资料(昵称、简介、头像、封面)的提交地址。 PathAccountProfile = "/account/profile" // PathAccountPassword 是账户页里改密码表单的提交地址。 PathAccountPassword = "/account/password" // PathLogout 是登出表单的提交地址。 PathLogout = "/logout" )
前台账户路由。
这些是**被保留的固定路径**:它们会遮蔽同名的独立页面(已知限制)。 导出成常量是为了让这份保留清单只有一个出处,将来要改成动态判断也有地方可改。
const ( PurposeVerifyEmail = "verify_email" PurposeResetPassword = "reset_password" )
令牌用途。与 account_tokens 表的 account_tokens_purpose CHECK 一一对应: 拼错的用途在 Go 这边就会被拒绝,不必等数据库报约束错。
const ( // FormCSRFField 是渲染进表单的 hidden 字段名。 // // 带下划线前缀是从 Rails / Django 沿用的惯例,读取表单的中间件与扫描工具都认它。 FormCSRFField = "_csrf" )
表单 CSRF 的 Cookie 与字段名。
__Host- 前缀要求 Secure + Path=/ 且不带 Domain,能防止子域写入伪造 Cookie; 但它同时要求 HTTPS,故仅在 secure 模式下启用(与 auth 的会话 Cookie 同一处置)。
const GroupAccount = "account"
GroupAccount 是前台账户设置分组。
const Name = "account"
Name 是模块名,也是迁移版本表的后缀(goose_db_version_account)。
Variables ¶
var ErrInvalidToken = errors.New("链接无效或已过期")
ErrInvalidToken 表示令牌不存在、已用过或已过期。
三种情况合并成一个错误:对用户而言处理方式完全相同(重新走一遍流程), 而区分开只会顺带告诉试探者「这一枚是真的,只是用过了」。
Functions ¶
Types ¶
type CSRF ¶
type CSRF struct {
// contains filtered or unexported fields
}
CSRF 提供前台表单的 CSRF 防护(双提交 Cookie + 隐藏字段)。
为什么不复用会话 CSRF(auth.Authenticator.CSRF):那套是「请求头里的令牌必须与 会话记录里的一致」,而**匿名访客手里根本没有会话**——登录表单、注册表单、 找回密码表单全都发生在这之前。会话 CSRF 在这些页面上无从校验。
已登录用户的账户页表单也走这一套,不与会话 CSRF 混用: 两套机制并存会让模板作者需要判断「这个表单该带哪个令牌」,而判断错了就是 一个静默失效的表单。
已知弱点:双提交无法防住能写 Cookie 的攻击者(同站子域被拿下、 或有中间人能力)。生产环境的两条缓解是 __Host- 前缀(禁掉子域写入) 与 SameSite=Lax(跨站 POST 不带 Cookie),与 session.go 里的说明一致。
func (*CSRF) Ensure ¶
Ensure 返回本次请求可用的令牌:请求已带着一枚合法的就沿用,否则签发新的。
与 Issue 的差别只在「换不换值」,而这一条是为页眉里的退出登录表单加的: 那张表单出现在**每一个**前台页面上,若每次渲染都换发新令牌, 用户在另一个标签页里开着的注册表单会在切回去提交时被自己的 CSRF 挡下—— 那张表还好好地摆在眼前,提交却说「表单已过期」。
沿用旧值不削弱双提交:它赌的是攻击者读不到也写不了这个 Cookie,与令牌换不换无关。 每次仍重设一遍 Cookie 是为了续期——人停在一个页面上超过 formCSRFTTL 之后, 页面里那枚令牌还在,Cookie 却已经过期,退出登录会莫名其妙地失败一次。
type Limiter ¶
type Limiter struct {
// contains filtered or unexported fields
}
Limiter 是窗口计数限流器,计数存在数据库里,多实例共享同一份额度。
不复用 auth.LoginLimiter:那个的语义是「**失败**计数,成功即清零」, 而这里要的是「总次数」——注册成功之后当然还要继续计数, 否则一个脚本每成功注册一次就把自己的额度刷回来。
func NewLimiter ¶
NewLimiter 构造限流器。
type Module ¶
type Module struct {
// contains filtered or unexported fields
}
Module 是前台账户模块。
func (*Module) EnsureFormCSRF ¶
EnsureFormCSRF 为本次响应准备一枚表单 CSRF 令牌,供主题页眉里的退出登录表单使用。
导出给 theme:页眉出现在**每一个**前台页面上,而签发令牌要写 Cookie, 只有拿得到 ResponseWriter 的地方做得了。serve 在两个模块都装配完之后把它接上去 (见 cmd/lumo/serve.go 与 theme.Renderer.UseFormCSRF), theme 因此不必反过来依赖 account——那会是一个导入环。
用 Ensure 而不是 Issue:换发新令牌会把访客在别的标签页里开着的表单作废。
func (*Module) MountFrontend ¶
MountFrontend 把前台账户路由挂到根路由上。
必须在 theme 的 MountFrontend **之前**调用:theme 的 /{slug}(独立页面) 与 NotFound 会吞掉根路径下的一切单段路径,挂晚了 /login、/account 都会 被当成同名独立页面。
optional 是 auth.Authenticator.Optional:前台不经三平面,登录态只能靠它注入。
func (*Module) Register ¶
Register 实现 app.Module:只做装配,不访问数据库。
依赖经 app.Lookup 取:auth.Core(认证实例,必须与后台**同一批**)、 theme(页面渲染器)、settings 与 mail(站点信息与发信能力)。
func (*Module) Settings ¶
func (m *Module) Settings() []app.SettingGroup
Settings 实现 app.SettingsProvider。
不依赖数据库与认证栈,故 migrate 那条路径上也照常声明分组——设置项的定义 属于编译期常量,与能不能渲染页面无关。
type Settings ¶
type Settings struct {
// AllowRegistration 为真才开放自助注册。
AllowRegistration bool `json:"allowRegistration"`
// RegistrationNotice 是显示在注册表单上方的纯文本,不解析 HTML。
RegistrationNotice string `json:"registrationNotice"`
}
Settings 是 account 分组的有效值。
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store 提供账户流程需要的 users 表访问。
只读与只改两个字段:创建用户、改口令、踢会话这些一律走 auth.Store / auth.Service, 本模块不重复实现——那是「共用 users 表」这个决策的意义所在。
func (*Store) FindByEmail ¶
FindByEmail 按邮箱查用户(大小写不敏感)。
邮箱在库里已由 auth.Store.CreateUser 归一化为小写, 这里同样先 lower 再比,避免大小写不同的同一个地址被当成两个账号。
func (*Store) FindVerifiedByEmail ¶
FindVerifiedByEmail 按邮箱查一个**已验证**的用户;不存在或未验证都返回 auth.ErrNotFound。
找回密码用它而不是 FindByEmail:调用方要的正是「可以给他发重置链接」这个判断, 而区分「不存在」与「未验证」的返回值只会在调用处被写成 if, 不如把判断留在这一处。
func (*Store) MarkEmailVerified ¶
MarkEmailVerified 把用户的邮箱标记为已验证。
用 coalesce 保证幂等:链接被点第二次(或用户开了两个标签页同时点)时 保留第一次的时间,不会把「什么时候验证的」改成一个更晚的值。
func (*Store) UpdateAvatar ¶
UpdateAvatar 改头像地址(空串表示改回首字印面)。
func (*Store) UpdateBanner ¶
UpdateBanner 改封面地址(空串表示不显示封面)。
type Token ¶
type Token struct {
bun.BaseModel `bun:"table:account_tokens,alias:at"`
TokenHash string `bun:"token_hash,pk"`
UserID int64 `bun:"user_id,notnull"`
Purpose string `bun:"purpose,notnull"`
ExpiresAt time.Time `bun:"expires_at,notnull"`
UsedAt *time.Time `bun:"used_at"`
CreatedAt time.Time `bun:"created_at,nullzero"`
}
Token 是一次性令牌记录。
库中只存 SHA-256(与 sessions、access_tokens 同一策略):明文只出现在那封邮件的链接里, 库泄漏不等于账号失守。
type TokenStore ¶
type TokenStore struct {
// contains filtered or unexported fields
}
TokenStore 提供一次性令牌的签发、查验与消费。
func (*TokenStore) Check ¶
Check 查验令牌有效但**不消费**它,返回所属用户 ID。
供「打开重置密码页」这一步使用:那时用户还没设新密码,消费掉令牌等于 让一次误刷新就把链接烧掉。
func (*TokenStore) Consume ¶
Consume 原子地消费令牌,返回所属用户 ID。
必须是一条 UPDATE 按影响行数判成败:先 SELECT 再 UPDATE 的话, 同一封邮件被并发点两次会重置两次密码,第二次覆盖掉第一次刚设的新密码。 单条 UPDATE 由数据库的行锁保证只有一个调用者能把它从「未用」改成「已用」。
func (*TokenStore) DeleteExpired ¶
DeleteExpired 删除过期超过 retention 的令牌,返回删除条数。
不删「刚过期」的:留一段时间才回答得了「链接为什么失效」这个问题 (是过期了,还是早就被用过了)。截止时间在 Go 侧算好再传参, 避免把 interval 字面量拼进 SQL。