Inkstone 安全机制深度解析:从密码哈希、TOTP 双因素到限流防护的 5 层安全设计

原创2026-10-14 18:23:541,689 阅读

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 函数。

还有两个容易被忽视的细节:

  1. 时序安全比较:验证时通过 timingSafeEqual 逐字节恒定时间比对,防止攻击者通过响应耗时推断哈希前缀;
  2. 虚拟哈希(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。

它的工作方式:

  1. 首次使用时生成 32 字节主密钥,持久化在 DO 私有存储中,任何业务代码都无法直接读取;
  2. 通过 HKDF-SHA256 按 scope(totp:{userId} / backup:{userId})派生出互不相同的数据密钥(targetKey)——即便两个用户的数据放在一起,一把密钥也解不开另一把锁;
  3. 用 AES-256-GCM 加密,IV 与 scope 一起绑定到附加认证数据(associatedData),密文被篡改会解密失败;
  4. 明文上限 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 层机制基本把"应用层"该做的安全功课都做到了位。

登录后查看全文
inkstone