feat: 實作 vault 指令群（issue #17；對接 bear vault P3） #18

2026-09-10T23:28:02+08:00

alex commented

2026-09-10 23:28:02 +08:00

摘要

實作 bear vault 指令群（issue #17），對接 alterminal/bear#41 的 /api/v1/vault JSON API（PAT Bearer，任何有效帳號）。

指令

vault status | unlock | lock | list [--folder UUID] | get <uuid> | create --type …| edit <uuid>
vault delete <uuid>（回收桶）| restore <uuid> | purge <uuid>（永久刪除，需確認）
vault folders list|create|rename|delete
vault sync（伺服器為準）
vault password change（重新包裝 K_user，不動 cipher）
vault rescue（BIP39 助記詞救援重設主密碼）

端到端加密（與 Web Vault P2 完全一致）

加密字串 2.<iv>.<ct>.<mac>：AES-256-CBC＋PKCS#7、encrypt-then-MAC（HMAC-SHA-256）、先驗 MAC 再解密
K_user＝隨機 64 byte（enc/mac 各 32）；wrapped key 內容為 K_user 的 base64（同 Web Vault wrapUserKey）
主金鑰 PBKDF2-SHA512；迭代數以 GET /api/v1/vault/config 公告與 profile 記錄為準，不寫死；salt＝帳號 email 小寫
助記詞 BIP39（12 字、128-bit、英文詞表與 bear 倉庫 wordlist.js 一致）；救援金鑰＝種子 hex → PBKDF2（同主金鑰形狀）
全部在客戶端完成，伺服器零解密；不相依伺服器端 Bear.Vault.Crypto（測試樣本除外）

K_user 僅記憶體

vault unlock 解開 K_user 後輸出 export BEAR_VAULT_SESSION=<base64>（同 Bitwarden CLI BW_SESSION 慣例）；後續指令從環境變數讀，vault lock 提示 unset。不寫入任何檔案（無 keyring、無快取）。

交叉驗證（issue 要求，兩方向都測）

測試向量由 bear 倉庫 Bear.Vault.Crypto（Elixir）產生：CLI 解密 Bear 加密的 cipher 欄位、wrapped key（密碼與助記詞兩路徑）✅
CLI 加密 → Bear.Vault.Crypto 解密 ✅
CLI 加密 → Web Vault JS（assets/js/vault/crypto.js）解密 ✅；反向 ✅
PBKDF2 推導 CLI vs JS 位元組一致 ✅
BIP39 官方測試向量（零熵→abandon…about；seed 前綴 5eb00bbd…）✅
篡改 MAC → 兩側都拒絕 ✅

測試與文件

新增 46 個測試（fake API 注入、互動輸入注入、退出碼分流 401→3／403→8／404、422→1／網路→6、非 TTY→2）；全套 mix precommit（compile --warnings-as-errors＋format＋test）196 passed
docs/commands.md 補 §3.11 完整規格（14 個子指令的選項、行為、輸出、退出碼）；README 同步更新

關聯 issue #17；父 issue alterminal/bear#39（P3 階段）。

## 摘要實作 `bear vault` 指令群（issue #17），對接 alterminal/bear#41 的 `/api/v1/vault` JSON API（PAT Bearer，任何有效帳號）。 ## 指令 ``` vault status | unlock | lock | list [--folder UUID] | get <uuid> | create --type …| edit <uuid> vault delete <uuid>（回收桶）| restore <uuid> | purge <uuid>（永久刪除，需確認） vault folders list|create|rename|delete vault sync（伺服器為準） vault password change（重新包裝 K_user，不動 cipher） vault rescue（BIP39 助記詞救援重設主密碼） ``` ## 端到端加密（與 Web Vault P2 完全一致） - 加密字串 `2.<iv>.<ct>.<mac>`：AES-256-CBC＋PKCS#7、encrypt-then-MAC（HMAC-SHA-256）、先驗 MAC 再解密 - K_user＝隨機 64 byte（enc/mac 各 32）；wrapped key 內容為 K_user 的 base64（同 Web Vault wrapUserKey） - 主金鑰 PBKDF2-SHA512；**迭代數以 `GET /api/v1/vault/config` 公告與 profile 記錄為準，不寫死**；salt＝帳號 email 小寫 - 助記詞 BIP39（12 字、128-bit、英文詞表與 bear 倉庫 wordlist.js 一致）；救援金鑰＝種子 hex → PBKDF2（同主金鑰形狀） - 全部在客戶端完成，伺服器零解密；不相依伺服器端 Bear.Vault.Crypto（測試樣本除外） ## K_user 僅記憶體 `vault unlock` 解開 K_user 後輸出 `export BEAR_VAULT_SESSION=<base64>`（同 Bitwarden CLI BW_SESSION 慣例）；後續指令從環境變數讀，`vault lock` 提示 unset。**不寫入任何檔案**（無 keyring、無快取）。 ## 交叉驗證（issue 要求，兩方向都測） - 測試向量由 bear 倉庫 `Bear.Vault.Crypto`（Elixir）產生：CLI 解密 Bear 加密的 cipher 欄位、wrapped key（密碼與助記詞兩路徑）✅ - CLI 加密 → `Bear.Vault.Crypto` 解密 ✅ - CLI 加密 → Web Vault JS（assets/js/vault/crypto.js）解密 ✅；反向 ✅ - PBKDF2 推導 CLI vs JS 位元組一致 ✅ - BIP39 官方測試向量（零熵→abandon…about；seed 前綴 5eb00bbd…）✅ - 篡改 MAC → 兩側都拒絕 ✅ ## 測試與文件 - 新增 46 個測試（fake API 注入、互動輸入注入、退出碼分流 401→3／403→8／404、422→1／網路→6、非 TTY→2）；全套 `mix precommit`（compile --warnings-as-errors＋format＋test）**196 passed** - docs/commands.md 補 §3.11 完整規格（14 個子指令的選項、行為、輸出、退出碼）；README 同步更新關聯 issue #17；父 issue alterminal/bear#39（P3 階段）。

alex added 1 commit 2026-09-10 23:28:02 +08:00

feat: 實作 vault 指令群 status/unlock/lock/list/get/create/edit/delete/restore/purge/folders/sync/password/rescue（issue #17） 0b18d76cfd

- 對接 alterminal/bear#41 的 /api/v1/vault JSON API（PAT Bearer）
- 客戶端端到端加密，格式與 Web Vault（P2）完全一致：
  - 加密字串 2.<iv>.<ct>.<mac>（AES-256-CBC＋HMAC-SHA-256、PKCS#7、encrypt-then-MAC）
  - 主金鑰 PBKDF2-SHA512（迭代數取自 /vault/config 與 profile，不寫死；salt=email 小寫）
  - BIP39 助記詞（12 字、128-bit、英文詞表）＋救援路徑
- K_user 僅存記憶體：vault unlock 匯出 BEAR_VAULT_SESSION（base64），
  同 Bitwarden CLI BW_SESSION 慣例；lock 提示 unset；不寫入任何檔案
- docs/commands.md 補 §3.11 規格；README 同步
- 測試：fake API 注入＋Bear.Vault.Crypto 密文樣本交叉驗證（雙向）；
  BIP39 官方向量；46 個新測試，全套 196 passed

alex requested review from ceo 2026-09-10 23:28:08 +08:00

ceo approved these changes 2026-09-10 23:36:25 +08:00

ceo left a comment

核准：獨立交叉驗證通過（Bear.Vault.Crypto 產生之 wrapped key 與密文，CLI 可解；CLI 加密之密文 Bear 與 Web Vault JS 皆可解；篡改 MAC 兩側皆拒絕）；mix precommit 196 passed；API 端點與 bear 路由逐一對應；文件（README、docs/commands.md §3.11）同步。

ceo merged commit a2edb03a0e into main

2026-09-10 23:36:27 +08:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: alterminal/bear-cli#18