133 lines
7.2 KiB
Markdown
133 lines
7.2 KiB
Markdown
# Auth Login Methods(登录方式接入契约)
|
||
|
||
> 面板现有登录方式:密码(+可选 TOTP)、OIDC / GitHub(OAuth)、通行密钥(Passkey / WebAuthn)、Web3 钱包(EIP-4361)。
|
||
> 新增或修改任何登录方式时,以下契约是安全红线,缺一不可。
|
||
|
||
## 1. 登录守卫(防爆破)
|
||
|
||
公开登录端点的失败必须计入 `loginGuard`:`guardKey(clientIP, <账号标识>)`,账号未知用固定占位名(如 passkey 的 `__passkey__`),已知用其标识(如钱包地址小写)。锁定检查在校验之前;失败经 `auth.failLogin`(自带阈值转锁定与告警推送),成功 `guard.success`。阈值/时长取安全设置,不硬编码。
|
||
|
||
## 2. 系统日志留痕
|
||
|
||
公开登录端点不经系统日志中间件,handler 必须显式 `logs.Record` 成败(参考 `authHandler.recordLogin` / `passkeyHandler.recordLogin` / `walletHandler.recordWallet`);登录失败是安全关键事件,不允许无痕。JWT 组内的绑定/解绑由中间件自动留痕,无需额外埋点。
|
||
|
||
## 3. 令牌版本(TokenVersion)
|
||
|
||
绑定、解绑、凭据及认证因子变更均属敏感变更:必须在事务内
|
||
`bumpTokenVersionTx`(或 `RevokeSessions`)使旧 JWT 失效，并按第 6 节携带
|
||
`TokenProof`、接续操作者会话。因子写入与版本递增不得拆成两个独立提交。
|
||
|
||
## 4. 「至少一种登录方式」不变量
|
||
|
||
密码登录禁用要求至少一种在当前 `EffectiveAppURL` 下**可实际登录**的免密方式
|
||
(`usablePasswordlessTx`);地址为空时 Passkey、钱包和 OAuth 均不可用。禁用期间移除
|
||
最后一种免密方式被拒:解绑身份走 `ensureNotLastLogin`,删通行密钥走对称检查。
|
||
这些检查都在事务内先 `lockUserForAuthChange` 锁用户行,防并发绕过。新登录方式要
|
||
明确决策如何参与该不变量:
|
||
|
||
- **复用 `UserIdentity` 表**(如钱包,provider+subject 唯一)→ 走 `identityCountTx` 自动参与,零改动;
|
||
- **独立表**(如 Passkey 的 `UserPasskey`)→ 参照 `passkeyCountTx` 增加计数入口,并在开启门槛(`hasAnyPasswordless`)与两个 `ensureNot*` 检查里对称接入;api 层把 `ErrLastIdentity` 映射 409。
|
||
|
||
## 5. 挑战/状态的一次性消费
|
||
|
||
挑战-响应类流程(OAuth state、WebAuthn challenge、SIWE nonce)一律进程内 `map + mutex + TTL + gc`,取用即删(参考 `oauthPending` / `passkeyPending` / `walletPending`);不落库、不引 Redis。TTL 5-10 分钟。
|
||
|
||
## 6. 场景：已鉴权敏感事务的提交屏障
|
||
|
||
### 1. Scope / Trigger
|
||
|
||
凡请求先通过 JWT 中间件、随后仍会读取 body、等待外部回调或写入认证/安全配置，
|
||
都必须防止请求处理期间的 Logout、定点撤销或撤销全部会话被旧请求绕过。
|
||
|
||
### 2. Signatures
|
||
|
||
```go
|
||
type TokenProof struct {
|
||
Ver uint
|
||
Jti string
|
||
}
|
||
|
||
func tokenProofOf(c *gin.Context) service.TokenProof
|
||
func (s *AuthService) ensureTokenCurrentTx(
|
||
tx *gorm.DB, user *model.User, proof TokenProof,
|
||
) error
|
||
func (s *AuthService) RenewToken(
|
||
ctx context.Context, username, oldToken string, meta SessionMeta,
|
||
) (string, time.Time, error)
|
||
```
|
||
|
||
持久化契约使用 `user_sessions.token_id` 表示逻辑会话；敏感换发不改变该 JTI。
|
||
|
||
### 3. Contracts
|
||
|
||
- `RequireAuth` 必须把本次请求实际观察到的 `TokenVersion + JTI` 写入 Context，
|
||
Handler 不得事后只按用户名读取“最新版本”代替 proof。
|
||
- 敏感事务、`RevokeSession` 与 Logout 的数据库路径统一先锁用户行，再检查/更新
|
||
会话行；持锁后调用 `ensureTokenCurrentTx`。
|
||
- proof 通过后，认证因子写入、版本递增及事务内换发必须同成同败。需要在 Handler
|
||
末尾换发的旧接口，`RenewToken` 也须重新锁用户并确认当前版本恰为
|
||
`oldClaims.Ver + 1`。
|
||
- 换发沿用旧 JWT 的合法 JTI；有旧会话行时只接续未撤销行，存在但已撤销或更新
|
||
失败必须关闭。兼容期无行 Token 可建行，但仍沿用旧 JTI，因此 Logout 的
|
||
tombstone 能同时撤销换发前后的 JWT。
|
||
- Logout 持久撤销须按 JTI 会话行解析稳定的 `user_id`，不得只按旧 JWT 的可变
|
||
username/subject 找用户；JTI tombstone 至少保留“旧 JWT 剩余寿命 +
|
||
一个完整 `tokenTTL`”，兜住 legacy 无行换发、改名提交和持久化撤销之间的
|
||
窄窗口。
|
||
- 外部身份登录须在用户锁内重查身份仍绑定；OAuth 登录还须在最终签发事务内重查
|
||
Provider 当前可用。
|
||
- proof 不二次检查自然到期：请求在 JWT 未过期时通过中间件即取得本次请求的认证
|
||
边界；不得为此额外引入长事务、分布式锁或持久状态机。
|
||
|
||
### 4. Validation & Error Matrix
|
||
|
||
| 条件 | 结果 |
|
||
| --- | --- |
|
||
| `user.TokenVersion != proof.Ver` | `ErrTokenStale` → HTTP 401 |
|
||
| JTI tombstone 命中或会话行已撤销 | `ErrTokenStale` → HTTP 401 |
|
||
| 旧会话行存在但接续命中 0 行 | 失败关闭，不得 fallback 创建 |
|
||
| 已验签当前版本的兼容 Token 确无会话行 | 沿用原 JTI 创建会话行 |
|
||
| 改名后用换发前 JWT Logout | 按 JTI/user_id 撤销新旧 JWT；旧 subject 不参与归属 |
|
||
| Handler 分段换发时版本不是 `oldVer + 1` | `ErrTokenStale`，前端重新登录 |
|
||
| 登录签发前身份已解绑 / Provider 已不可用 | 拒绝登录，不签发 JWT |
|
||
|
||
### 5. Good / Base / Bad Cases
|
||
|
||
- Good：TOTP 激活事务内依次锁用户、验 proof、写因子、递增版本、沿用 JTI 换发。
|
||
- Base：无会话行的存量 JWT 可完成一次合法变更，但换发后的 JWT 与旧 JWT 共用
|
||
JTI，后到 Logout 可同时撤销。
|
||
- Bad：proof 普通查询通过后释放锁，定点撤销完成，再把旧行更新失败当“无行”创建
|
||
新会话；这会复活已撤销 Token。
|
||
|
||
### 6. Tests Required
|
||
|
||
- TOTP 激活 × 撤销全部：旧 proof 返回 `ErrTokenStale`，因子与版本均不改变。
|
||
- proof check → 定点撤销 → renew：撤销后的行不得被新建替代。
|
||
- recorded 与 legacy 无行会话各测一次“改名后 old-token Logout”：换发 JWT
|
||
必须随同失效；recorded 行写入 `revoked_at`，legacy tombstone 覆盖 fresh expiry。
|
||
- OAuth/钱包登录在最终事务前删除身份：不得签发会话；OAuth 禁用同理。
|
||
- Security/OAuth PATCH 使用已撤销 proof：返回 `ErrTokenStale` 且设置不落库。
|
||
|
||
### 7. Wrong vs Correct
|
||
|
||
```go
|
||
// Wrong：只按最新用户状态改因子，随后无条件签最新版本 JWT。
|
||
saveFactor()
|
||
bumpTokenVersion()
|
||
return IssueToken(ctx, username)
|
||
|
||
// Correct：请求 proof、因子写入、版本递增和会话接续共享事务与用户锁。
|
||
return db.Transaction(func(tx *gorm.DB) error {
|
||
user, err := lockUserForAuthChange(tx, username)
|
||
if err != nil { return err }
|
||
if err := auth.ensureTokenCurrentTx(tx, user, proof); err != nil { return err }
|
||
return changeFactorAndRenewTx(tx, user, oldToken)
|
||
})
|
||
```
|
||
|
||
## 其他约定
|
||
|
||
- 面板地址依赖:RP ID / 回调 / SIWE domain 均派生自 `settings.EffectiveAppURL()`,为空时返回引导错误(文案对齐 `ErrOAuthNoAppURL`),不得回退猜测。
|
||
- 登录失败对外文案统一、不透出内部细节(防探测);错误变量集中定义在对应 service 文件头部。
|
||
- 新端点全量 swagger 中文注释并重新生成 docs/;providers 公开端点(`/auth/oauth/providers`)按需追加 `<method>Login` 可用性布尔,供登录页渲染入口。
|