Inkstone 安全机制深度解析:从密码哈希、TOTP 双因素到限流防护的 5 层安全设计
Inkstone 安全机制深度解析:从密码哈希、TOTP 双因素到限流防护的 5 层安全设计
Inkstone 是一款运行在 Cloudflare Workers 上的自托管 Markdown 笔记本应用。对于需要自行部署的笔记服务来说,"数据都在自己手里"的另一面是:安全责任也在自己手里。这篇文章带你逐层拆解 Inkstone 内置的 5 层安全设计——scrypt 密码哈希、会话令牌哈希、TOTP 双因素认证、渐进式限流锁定,以及敏感凭据的 AES-GCM 加密存储,帮助你判断这套自托管笔记方案到底安不安全。
Inkstone 安全机制总览:5 层纵深防御
在深入源码之前,先用一张表看清整条防线:每一层各自解决哪类威胁、实现在哪个模块。
| 层级 | 防护机制 | 防御的威胁 | 核心实现 |
|---|---|---|---|
| 第 1 层 | scrypt 密码哈希 + 时序安全比较 | 数据库泄露后的密码还原、时序攻击 | password.ts |
| 第 2 层 | 会话令牌哈希 + HttpOnly Cookie | 窃取会话 Cookie 后的重放、CSRF | session-store.ts、auth.ts |
| 第 3 层 | TOTP 双因素 + 一次性恢复码 | 密码被撞库、异地登录 | totp-service.ts |
| 第 4 层 | 多维限流 + 渐进式锁定 + 计算预算 | 暴力破解、分布式撞库、CPU 消耗攻击 | throttle.ts、auth.ts |
| 第 5 层 | CredentialVault AES-GCM 加密 | TOTP 密钥与备份凭据明文落库 | credential-vault.ts |
这套设计的特点是"纵深防御":即便某一层被突破(比如数据库被拖库),攻击者还会撞上后面四道关卡。下面逐层拆解。
第 1 层:scrypt 密码哈希——数据库拖库也拿不到明文
🔐 很多笔记应用把用户密码直接存成明文或弱哈希。Inkstone 的做法是在 src/worker/lib/password.ts 中使用 scrypt 内存硬(memory-hard)算法:
- 每次哈希都会用
crypto.getRandomValues生成 16 字节随机盐,同一密码两次哈希结果完全不同; - 参数为
N=16384、r=8、p=5,派生出 32 字节密钥,见 SCRYPT_N 等参数,攻击者用 GPU 批量爆破的成本显著高于 MD5/SHA1; - 数据库中只保存形如
scrypt$16384$8$5$<salt>$<hash>的完整描述,密码验证走verifyPassword函数。
还有两个容易被忽视的细节:
- 时序安全比较:验证时通过 timingSafeEqual 逐字节恒定时间比对,防止攻击者通过响应耗时推断哈希前缀;
- 虚拟哈希(dummy verify):当输入的用户名不存在时,系统仍会执行一次 dummyVerify(对内置的假哈希跑一遍完整 scrypt),让"账号存在/不存在"的响应耗时保持一致,防止账号枚举。
在入口层面同样做了收紧:注册接口强制密码至少 8 位(validateNewPassword),用户名必须匹配 ^<a href="https://link.gitcode.com/i/513212b1d5ce08f54fe3a0ab3bebf70a" target="_blank">a-z0-9_-]{3,32}$ 白名单([USERNAME_PATTERN),从源头过滤异常输入。
第 2 层:会话令牌哈希与 Cookie 加固——丢了库也换不了 Cookie
登录成功后,Inkstone 会签发一个 32 字节随机数生成的 64 位十六进制会话令牌(newSessionToken)。关键在于:数据库里从不保存令牌本身,只保存它的 SHA-256 哈希(hashToken)。验证 Cookie 时同样先做哈希再查库(loadSession)。这意味着即使数据库被拖库,攻击者也拿不到任何可直接使用的会话。
Cookie 属性在 sessionCookieString 中逐项加固:
| Cookie 属性 | 作用 |
|---|---|
HttpOnly |
JavaScript 无法读取,XSS 窃取不到令牌 |
SameSite=Lax |
跨站请求默认不带 Cookie,缓解 CSRF |
Secure |
仅在 HTTPS 下生效,防止明文网络嗅探 |
Max-Age |
会话有效期 90 天(SESSION_TTL_MS),剩余不足一半时自动续期 |
另外两个主动防御动作:
- 登录即轮换:每次登录/注册成功都会销毁旧令牌、签发新令牌(rotateSession),旧 Cookie 立即作废;
- 启用双因素即踢出旧会话:开启 TOTP 成功时,该账号的其余所有会话被批量删除(confirmTotpSetup),防止已被入侵的设备继续活动。
第 3 层:TOTP 双因素认证——密码只值一半门票
🛡️ 密码对了也只是"半程通过"。开启双因素后,登录流程会先进入一个 5 分钟有效的挑战(createTotpLoginChallenge,TTL 见 TOTP_LOGIN_TTL_MS),并额外校验挑战创建时密码哈希与当前库中一致——期间若密码被修改,挑战立即失效。
TOTP 本身是标准的 RFC 6238 风格实现,位于 src/worker/lib/totp.ts:
- 6 位数字、30 秒轮换,20 字节随机密钥;
- 验证时允许 ±1 步时间窗口(matchTotpCode),容忍手机与服务器间的时钟漂移,同时用
timingSafeEqual做恒定时间比对; - 防重放:数据库中记录
last_used_step,旧步骤的验证码只能使用一次(completeTotpLogin)。
TOTP 密钥本身怎么存? 不以明文落库,而是交给第 5 层的 CredentialVault 加密后存入 secret_ciphertext 字段。
恢复码(recovery codes) 是双因素的兜底方案:
- 开启时一次性生成 10 个(TOTP_RECOVERY_CODE_COUNT),16 位、按 4 位分组显示;
- 数据库中同样只存哈希(hashRecoveryCode),且绑定代号代际(generation),换一批旧批自动作废;
- 每个恢复码只能用一次,用后标记
used_at(completeTotpLogin),并会在登录结果中返回"剩余恢复码数量"提醒用户。
用户侧的开启/关闭界面见 TotpSettings.tsx,注意:开启和关闭双因素都要求先输入当前密码(routes/totp.ts),防止攻击者持有效 Cookie 悄悄关掉你的二次验证。
第 4 层:限流与渐进式锁定——让暴力破解在时间上破产
🐢 这一层是整条防线里"工程味"最重的部分,核心在 src/worker/lib/throttle.ts。Inkstone 没有用单一计数器,而是同时维护多个维度的失败计数(loginThrottleTargets):
| 限流键 | 免费失败次数 | 设计意图 |
|---|---|---|
login:{ip}:{用户} |
5 次/小时 | 限制单台设备对单账号的尝试 |
login-ip:{ip} |
25 次/小时 | 限制单 IP 的横向撞库 |
login-account:{用户} |
30 次/小时 | 账号级总闸:防止分布式 botnet 从多个 IP 轮流爆破同一账号 |
失败计数的"锁定时长"是渐进式升级的(recordLoginFailure):达到免费次数后依次锁定 1 分钟 → 2 分钟 → 4 分钟 → 8 分钟 → 15 分钟,每次失败都在滚动窗口(1 小时)内累加。触发限流时返回 429 too_many_attempts 并附带 retryAfter 秒数(ThrottleError),客户端可以明确知道"再试要等多久"。
更精妙的是**"计算预算"(work budget)**机制:限流只是不让你试,而暴力破解的真正成本在每次 scrypt 哈希计算上。因此登录接口还叠加了硬预算——10 分钟内同一"身份+IP"最多执行 8 次、同一 IP 最多 30 次哈希计算(loginWorkTargets,由 consumeAttemptBudget 强制执行),注册接口则是每 IP 10 分钟 12 次(register)。这一刀直接砍掉了"用海量 IP 分摊尝试次数"的思路。
还有一个很人性化的细节:登录成功会清空该身份、IP、账号三个维度的全部失败计数(clearLoginFailures)。在 NAT 网关、公司出口 IP 共享等场景下,你的登录成功等于证明这个 IP 是"好人",不会被别人的疯狂尝试连坐封禁。
第 5 层:CredentialVault——敏感凭据的 AES-GCM 加密保险箱
最后来看 TOTP 密钥和备份凭据(WebDAV/S3 账号密码、AccessKey 等)存在哪里。答案是独立的 Durable Object:CredentialVault。
它的工作方式:
- 首次使用时生成 32 字节主密钥,持久化在 DO 私有存储中,任何业务代码都无法直接读取;
- 通过 HKDF-SHA256 按 scope(
totp:{userId}/backup:{userId})派生出互不相同的数据密钥(targetKey)——即便两个用户的数据放在一起,一把密钥也解不开另一把锁; - 用 AES-256-GCM 加密,IV 与 scope 一起绑定到附加认证数据(associatedData),密文被篡改会解密失败;
- 明文上限 24KB,且字段名走白名单校验(TOTP 只允许
secret,备份只允许password/accessKeyId/secretAccessKey,见 isCredentialRecord)。
敏感操作的"重新认证":改密、关 2FA 都要再输一次密码
📌 即使你已经登录,Inkstone 对高危操作仍要求重新验证当前密码:修改密码(routes/auth.ts)、调整实例设置(routes/settings.ts)、开启/关闭/重置 TOTP(routes/totp.ts)都会经过 requireCurrentPassword。
这条路径同样配了独立限流:每个用户的 pw:{userId} 失败计数 + 10 分钟内最多 8 次计算预算(reauth.ts),暴力猜"当前密码"这条路也被堵死。
写在最后:5 层防线怎么协同工作
把视角拉高一点,假设攻击者拿到了你的完整数据库:
- 用户表里只有 scrypt 哈希,还原不了密码;
- 会话表里只有令牌哈希,伪造不出有效 Cookie;
- TOTP 密钥是 AES-GCM 密文,没有 DO 主密钥解不开;
- 恢复码只有哈希,枚举成本极高;
- 而在线的爆破尝试,会被多维限流和计算预算按分钟锁死。
这就是纵深防御的意义——单点被攻破不等于防线被击穿。作为部署者,你还需要守住自己那部分责任:Cloudflare 账号安全、及时更新版本、配置可靠的异地备份,以及遵守 SECURITY.md 中的漏洞报告规范(安全问题请走私有安全通告,而不是公开 issue)。对一套需要"自己当运维"的笔记应用来说,这 5 层机制基本把"应用层"该做的安全功课都做到了位。