2.1 用戶模型#

每個用戶由用戶名 + 密碼標識——密碼既是身份，也是解密鑰匙。

2.2 隱藏登錄入口#

一個有意思的設計：未登錄時首頁顯示的表單，外观看起來像「快速添加 TOTP」（名稱框 + 字符串框 + 按鈕），實際邏輯是：

• 如果名稱匹配某用戶名且字符串匹配其密碼 → 登錄成功進入 vault
• 否則顯示通用錯誤「格式不正確」

不給任何「這是登錄入口」的提示。算是一種樸素的混淆。

3.1 密鑰派生#

1
用戶密碼 + 隨機鹽 → PBKDF2-SHA256（600,000 次迭代）→ 64 字節
2
    ├── 前 32 字節 → AES-GCM 加密密鑰（保護 TOTP 種子）
3
    └── 後 32 字節 → HMAC-SHA256 驗證密鑰（服務端驗證身份，不存密碼）

關鍵點：

• 服務端從不存儲密碼明文，只存 HMAC 驗證值
• 600,000 次 PBKDF2 迭代讓暴力破解成本極高
• 鹽是每用戶隨機的，彩虹表無效

3.2 TOTP 種子加密流程#

1
// 簡化示意，實際代碼在 worker.js 中
2
async function encryptSeed(seed, password, salt) {
3
  // 1. 派生密鑰
4
  const keyMaterial = await crypto.subtle.importKey(
5
    "raw",
6
    new TextEncoder().encode(password),
7
    "PBKDF2",
8
    false,
9
    ["deriveBits"]
10
  );
11
  const bits = await crypto.subtle.deriveBits(
12
    { name: "PBKDF2", salt, iterations: 600000, hash: "SHA-256" },
13
    keyMaterial,
14
    512  // 64 字節
15
  );
16

17
  // 2. 拆分：前 32 字節加密，後 32 字節驗證
18
  const encKey = await crypto.subtle.importKey(
19
    "raw", bits.slice(0, 32), "AES-GCM", false, ["encrypt"]
20
  );
21

22
  // 3. AES-GCM 加密種子
23
  const iv = crypto.getRandomValues(new Uint8Array(12));
24
  const ciphertext = await crypto.subtle.encrypt(
25
    { name: "AES-GCM", iv },
26
    encKey,
27
    new TextEncoder().encode(seed)
28
  );
29

30
  return { ciphertext, iv, salt };
31
}

解密在前端完成——種子明文永遠不會離開瀏覽器。Worker 只負責存取密文blob。

3.3 為什麼是 600,000 次？#

OWASP 2023 年對 PBKDF2-HMAC-SHA256 的推薦是 600,000 次迭代。這不是拍腦袋的數字：

300ms 的登錄延遲完全可接受，換來的是攻擊者每次猜測都要燒 300ms 的 CPU。

4.1 本機快速預覽（不連 Cloudflare）#

需要 Node.js 24，在項目根目錄運行：

1
node scripts/preview.mjs

打開 http://127.0.0.1:8788。首次設置的初始化令牌為 local-preview-only-setup-token-000000000，自行設置測試管理員用戶名和至少 12 位密碼。

此服務僅綁定 127.0.0.1，數據庫在內存中，重啟即清空。固定令牌僅供本地測試，生產環境絕不能使用。

4.2 直接部署到 Cloudflare#

需要 Node.js 24、npm 和 Cloudflare 帳號：

1
npm ci
2
npx wrangler login
3
npx wrangler d1 create vault

記下輸出的 database_id，寫入 wrangler.toml：

1
[[d1_databases]]
2
binding = "DB"
3
database_name = "vault"
4
database_id = "你的-database-id"

初始化數據庫表結構：

1
npx wrangler d1 execute vault --file=schema.sql

設置初始化令牌（僅用一次）：

1
npx wrangler secret put SETUP_TOKEN
2
# 輸入一個足夠隨機的字符串，初始化後立即刪除

部署：

1
npx wrangler deploy

首次訪問時用 SETUP_TOKEN 初始化管理員帳號，完成後立即刪除這個 secret：

1
npx wrangler secret delete SETUP_TOKEN

5.1 已知限制（誠實聲明）#

• 密碼遺失無法恢復：這是設計使然，不是 bug。沒有後門，沒有「忘記密碼」。
• 測試版本：已完成本地代碼審查和自動化測試，不代表絕對安全或第三方審計認證。
• 先用測試帳號驗證，再導入真實 2FA。

5.2 D1 ID 脫敏#

公開倉庫的 wrangler.toml 中的真實 D1 ID 和域名註釋已替換為佔位符。Git 歷史壓成一個乾淨 commit 並強推，refs 中已確認找不到真實 D1 ID。

生產部署前必須注入真實 D1 ID，不能直接使用公開 wrangler.toml。