account

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 26, 2026 License: AGPL-3.0 Imports: 33 Imported by: 0

Documentation

Overview

Package account 提供前台账户体系:自助注册、邮箱验证、找回密码与账户页。

它不引入自己的用户表——注册用户落核心的 `users` 表,只授内置角色 `member`。 理由是复用:会话、登录限流、argon2 并发闸门、改密踢下线这些都已经是核心的现成实现, 另起一张访客表要把它们再写一遍,而且内容与评论的归属要各认一次。

本模块**不实现 app.RouteProvider**:它产出的是 HTML 表单而不是 REST 接口, 进不了三平面(与 theme 同理)。页面由 MountFrontend 直接挂在根路由上。

Index

Constants

View Source
const (
	// VerifyEmailTTL 是邮箱验证链接的有效期。
	//
	// 给足 48 小时是因为验证邮件经常被投进垃圾箱,用户隔一天才想起来翻;
	// 而验证链接只证明邮箱可达,风险与重置链接不在一个量级。
	VerifyEmailTTL = 48 * time.Hour
	// ResetPasswordTTL 是密码重置链接的有效期。
	//
	// 与验证链接差两个数量级,因为重置链接能在不知道原密码的情况下改掉密码——
	// 邮件被别人翻出来时的破坏力大得多。
	ResetPasswordTTL = 2 * time.Hour
)

令牌有效期。做成代码常量而不是设置项:这两个数字站长改一次就再也不会动, 而每多一个设置项就多一处要解释、要翻译、要写文档的地方。

View Source
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"
)

前台账户路由。

这些是**被保留的固定路径**:它们会遮蔽同名的独立页面(已知限制)。 导出成常量是为了让这份保留清单只有一个出处,将来要改成动态判断也有地方可改。

View Source
const (
	PurposeVerifyEmail   = "verify_email"
	PurposeResetPassword = "reset_password"
)

令牌用途。与 account_tokens 表的 account_tokens_purpose CHECK 一一对应: 拼错的用途在 Go 这边就会被拒绝,不必等数据库报约束错。

View Source
const (

	// FormCSRFField 是渲染进表单的 hidden 字段名。
	//
	// 带下划线前缀是从 Rails / Django 沿用的惯例,读取表单的中间件与扫描工具都认它。
	FormCSRFField = "_csrf"
)

表单 CSRF 的 Cookie 与字段名。

__Host- 前缀要求 Secure + Path=/ 且不带 Domain,能防止子域写入伪造 Cookie; 但它同时要求 HTTPS,故仅在 secure 模式下启用(与 auth 的会话 Cookie 同一处置)。

View Source
const GroupAccount = "account"

GroupAccount 是前台账户设置分组。

View Source
const Name = "account"

Name 是模块名,也是迁移版本表的后缀(goose_db_version_account)。

Variables

View Source
var ErrInvalidToken = errors.New("链接无效或已过期")

ErrInvalidToken 表示令牌不存在、已用过或已过期。

三种情况合并成一个错误:对用户而言处理方式完全相同(重新走一遍流程), 而区分开只会顺带告诉试探者「这一枚是真的,只是用过了」。

Functions

func ReservedPaths

func ReservedPaths() []string

ReservedPaths 返回本模块保留的固定路径,供文档与将来的保留字校验使用。

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 NewCSRF

func NewCSRF(secure bool) *CSRF

NewCSRF 构造表单 CSRF 管理器;secure 决定是否启用 __Host- 前缀与 Secure 属性。

func (*CSRF) CookieName

func (c *CSRF) CookieName() string

CookieName 返回当前模式下的表单令牌 Cookie 名。

func (*CSRF) Ensure

func (c *CSRF) Ensure(w http.ResponseWriter, r *http.Request) string

Ensure 返回本次请求可用的令牌:请求已带着一枚合法的就沿用,否则签发新的。

与 Issue 的差别只在「换不换值」,而这一条是为页眉里的退出登录表单加的: 那张表单出现在**每一个**前台页面上,若每次渲染都换发新令牌, 用户在另一个标签页里开着的注册表单会在切回去提交时被自己的 CSRF 挡下—— 那张表还好好地摆在眼前,提交却说「表单已过期」。

沿用旧值不削弱双提交:它赌的是攻击者读不到也写不了这个 Cookie,与令牌换不换无关。 每次仍重设一遍 Cookie 是为了续期——人停在一个页面上超过 formCSRFTTL 之后, 页面里那枚令牌还在,Cookie 却已经过期,退出登录会莫名其妙地失败一次。

func (*CSRF) Issue

func (c *CSRF) Issue(w http.ResponseWriter) string

Issue 生成一枚新令牌,写进 Cookie 并返回明文(调用方填进表单的隐藏字段)。

出错时返回空串:调用方会渲染出一张没有令牌的表单,提交时被自己的 CSRF 校验挡下。 这是 fail-closed 的方向——宁可让这一次提交失败,也不要放行一个未经校验的请求。

func (*CSRF) Verify

func (c *CSRF) Verify(r *http.Request, formValue string) bool

Verify 比对 Cookie 值与表单字段值。

用定时安全比较:普通字符串比较会在第一个不同的字节处提前返回, 理论上可按响应时间逐字节还原令牌。

type Limiter

type Limiter struct {
	// contains filtered or unexported fields
}

Limiter 是窗口计数限流器,计数存在数据库里,多实例共享同一份额度。

不复用 auth.LoginLimiter:那个的语义是「**失败**计数,成功即清零」, 而这里要的是「总次数」——注册成功之后当然还要继续计数, 否则一个脚本每成功注册一次就把自己的额度刷回来。

func NewLimiter

func NewLimiter(counter *ratelimit.Counter, logger *slog.Logger) *Limiter

NewLimiter 构造限流器。

func (*Limiter) Allow

func (l *Limiter) Allow(ctx context.Context, key string, limit int, per time.Duration) bool

Allow 记一次计数并报告是否仍在额度内。

窗口从**第一次**命中开始算,之后窗口内的每次调用都累加到同一个计数上; 窗口过期则重新开一个。计数出错时放行并记 warn:这些表单本身也要读写数据库, 为限流把它们打成 500 不划算。

type Module

type Module struct {
	// contains filtered or unexported fields
}

Module 是前台账户模块。

func From

func From(a *app.App) *Module

From 取回账户模块;未装配时返回 nil。

func New

func New() *Module

New 构造模块。

func (*Module) EnsureFormCSRF

func (m *Module) EnsureFormCSRF(w http.ResponseWriter, r *http.Request) string

EnsureFormCSRF 为本次响应准备一枚表单 CSRF 令牌,供主题页眉里的退出登录表单使用。

导出给 theme:页眉出现在**每一个**前台页面上,而签发令牌要写 Cookie, 只有拿得到 ResponseWriter 的地方做得了。serve 在两个模块都装配完之后把它接上去 (见 cmd/lumo/serve.go 与 theme.Renderer.UseFormCSRF), theme 因此不必反过来依赖 account——那会是一个导入环。

用 Ensure 而不是 Issue:换发新令牌会把访客在别的标签页里开着的表单作废。

func (*Module) Migrations

func (m *Module) Migrations() fs.FS

Migrations 实现 app.Migrator。

func (*Module) MountFrontend

func (m *Module) MountFrontend(r chi.Router, optional func(http.Handler) http.Handler)

MountFrontend 把前台账户路由挂到根路由上。

必须在 theme 的 MountFrontend **之前**调用:theme 的 /{slug}(独立页面) 与 NotFound 会吞掉根路径下的一切单段路径,挂晚了 /login、/account 都会 被当成同名独立页面。

optional 是 auth.Authenticator.Optional:前台不经三平面,登录态只能靠它注入。

func (*Module) Name

func (m *Module) Name() string

Name 实现 app.Module。

func (*Module) Register

func (m *Module) Register(a *app.App) error

Register 实现 app.Module:只做装配,不访问数据库。

依赖经 app.Lookup 取:auth.Core(认证实例,必须与后台**同一批**)、 theme(页面渲染器)、settings 与 mail(站点信息与发信能力)。

func (*Module) Routes added in v0.1.9

func (m *Module) Routes(r app.Router)

Routes 实现 app.RouteProvider。

func (*Module) Settings

func (m *Module) Settings() []app.SettingGroup

Settings 实现 app.SettingsProvider。

不依赖数据库与认证栈,故 migrate 那条路径上也照常声明分组——设置项的定义 属于编译期常量,与能不能渲染页面无关。

func (*Module) Start

func (m *Module) Start(ctx context.Context) error

Start 实现 app.Starter:开关开着但发不出信时告警,并启动令牌清理循环。

func (*Module) Store

func (m *Module) Store() *Store

Store 返回账户数据访问对象,供测试取用。

func (*Module) Tokens

func (m *Module) Tokens() *TokenStore

Tokens 返回令牌存储,供测试取用。

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 NewStore

func NewStore(db bun.IDB) *Store

NewStore 构造 Store。

func (*Store) FindByEmail

func (s *Store) FindByEmail(ctx context.Context, email string) (*userRow, error)

FindByEmail 按邮箱查用户(大小写不敏感)。

邮箱在库里已由 auth.Store.CreateUser 归一化为小写, 这里同样先 lower 再比,避免大小写不同的同一个地址被当成两个账号。

func (*Store) FindVerifiedByEmail

func (s *Store) FindVerifiedByEmail(ctx context.Context, email string) (*userRow, error)

FindVerifiedByEmail 按邮箱查一个**已验证**的用户;不存在或未验证都返回 auth.ErrNotFound。

找回密码用它而不是 FindByEmail:调用方要的正是「可以给他发重置链接」这个判断, 而区分「不存在」与「未验证」的返回值只会在调用处被写成 if, 不如把判断留在这一处。

func (*Store) MarkEmailVerified

func (s *Store) MarkEmailVerified(ctx context.Context, userID int64) error

MarkEmailVerified 把用户的邮箱标记为已验证。

用 coalesce 保证幂等:链接被点第二次(或用户开了两个标签页同时点)时 保留第一次的时间,不会把「什么时候验证的」改成一个更晚的值。

func (*Store) UpdateAvatar

func (s *Store) UpdateAvatar(ctx context.Context, userID int64, url string) error

UpdateAvatar 改头像地址(空串表示改回首字印面)。

func (*Store) UpdateBanner

func (s *Store) UpdateBanner(ctx context.Context, userID int64, url string) error

UpdateBanner 改封面地址(空串表示不显示封面)。

func (*Store) UpdateProfile

func (s *Store) UpdateProfile(ctx context.Context, userID int64, displayName, bio string) error

UpdateProfile 更新昵称与简介。

只写这两列:本函数是被「前台自己改自己的资料」调用的,邮箱与角色不在其中, 而一条只 Set 两列的 UPDATE 让这件事在代码里也是显然的—— 用后台那个「整份资料一起写」的入口,将来多一列就会顺手多给前台一列。

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 NewTokenStore

func NewTokenStore(db bun.IDB) *TokenStore

NewTokenStore 构造 TokenStore。

func (*TokenStore) Check

func (s *TokenStore) Check(ctx context.Context, plaintext, purpose string) (int64, error)

Check 查验令牌有效但**不消费**它,返回所属用户 ID。

供「打开重置密码页」这一步使用:那时用户还没设新密码,消费掉令牌等于 让一次误刷新就把链接烧掉。

func (*TokenStore) Consume

func (s *TokenStore) Consume(ctx context.Context, plaintext, purpose string) (int64, error)

Consume 原子地消费令牌,返回所属用户 ID。

必须是一条 UPDATE 按影响行数判成败:先 SELECT 再 UPDATE 的话, 同一封邮件被并发点两次会重置两次密码,第二次覆盖掉第一次刚设的新密码。 单条 UPDATE 由数据库的行锁保证只有一个调用者能把它从「未用」改成「已用」。

func (*TokenStore) DeleteExpired

func (s *TokenStore) DeleteExpired(ctx context.Context, retention time.Duration) (int64, error)

DeleteExpired 删除过期超过 retention 的令牌,返回删除条数。

不删「刚过期」的:留一段时间才回答得了「链接为什么失效」这个问题 (是过期了,还是早就被用过了)。截止时间在 Go 侧算好再传参, 避免把 interval 字面量拼进 SQL。

func (*TokenStore) Issue

func (s *TokenStore) Issue(ctx context.Context, userID int64, purpose string, ttl time.Duration) (string, error)

Issue 签发一枚令牌,返回明文(只在此刻可见)。

签发即作废同用户同用途的旧令牌:用户点了「重新发送验证邮件」之后, 上一封邮件里的链接就该失效——否则每点一次就多留一个仍能改掉密码的入口。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址