@tsa-group/claude-usage 0.4.8 → 0.4.9

package/README.md

@@ -350,6 +350,12 @@ v0.4.7 起支援自我更新，但**由伺服器決定**，不是去問 npm：
 ## 已知限制
 
 - **非官方 endpoint**：額度 % 來自 Claude Code 內部的 `/api/oauth/usage`，Anthropic 可能變更。
+- **macOS 桌面版憑證也是逆向出來的**：Claude.app 把 OAuth token 存在
+  `~/Library/Application Support/Claude/config.json` 的 `oauth:tokenCacheV2`，用 Chromium 的
+  macOS 方案（Keychain「Claude Safe Storage」主金鑰 + PBKDF2-SHA1 + AES-128-CBC）加密。
+  首次背景存取會彈 Keychain 授權對話 —— 在終端機跑一次
+  `security find-generic-password -w -s "Claude Safe Storage"` 並按**一律允許**即可，
+  之後 daemon 讀得到。`doctor` 會偵測這個狀態並提示。與 `/api/oauth/usage` 同一風險類別。
 - **Windows 桌面版憑證是逆向出來的**：桌面版把 OAuth token 存在
   `%LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\config.json` 的
   `oauth:tokenCacheV2`，以 Chromium 的 `v10` 方案（DPAPI + AES-256-GCM）加密。

package/dist/creds-mac-desktop.js

@@ -0,0 +1,148 @@
+/**
+ * macOS 桌面版（Claude.app）的 Claude OAuth 憑證讀取。
+ *
+ * 為什麼需要這條路徑：跟 Windows 桌面版是**同一個問題**（見 creds-win.ts 檔頭）——
+ * 只用桌面版、沒在終端機開過 CLI 的人，`~/.claude/.credentials.json` 裡不會有可用的
+ * token，而 Keychain 裡那份是早期 CLI 登入的殘留，沒人 refresh 就會過期。實機
+ * （2026-08-31, Ashlyn）就是這樣：Claude Code 照常運作（它自己 refresh），但我們讀到
+ * 的 Keychain 憑證從 02:00 起過期，採樣連續 token_expired，而她其實一直在用。
+ *
+ * 桌面版把 token 存在 `~/Library/Application Support/Claude/config.json` 的
+ * `oauth:tokenCacheV2`，用 Chromium 的 macOS 加密方案：
+ *   主金鑰 = PBKDF2-HMAC-SHA1(Keychain「Claude Safe Storage」密碼, "saltysalt", 1003 輪, 16B)
+ *   密文   = base64( "v10"(3B) + AES-128-CBC(IV = 16 個 0x20) ) + PKCS7
+ *
+ * ★ 與 Windows 版的唯一差異就是加密那一步（DPAPI+AES-256-GCM ↔ Keychain+AES-128-CBC）。
+ *   解出來的 JSON 形狀完全相同（實機驗證：2 條目、user:inference 那筆是目標），所以
+ *   **挑選邏輯直接重用 creds-win.ts 的 pickEntry**，不另寫一份。
+ *
+ * ★ 為什麼主金鑰用 `security` CLI 而不是 native Keychain API：與 mac 上讀 Keychain
+ *   token、Windows 上 spawn PowerShell 做 DPAPI 完全對稱 —— 零執行期依賴、免編譯。
+ *
+ * ★ 為什麼 AES-GCM 用 Node crypto 而 KDF 用 Node crypto、只有取主金鑰密碼 spawn
+ *   外部程式：跟 Windows 版同一個分工原則 —— 只有「拿受作業系統保護的秘密」那一步
+ *   非得走系統工具，其餘純運算留在 Node，測得到、也不受外部工具版本影響。
+ *
+ * ⚠️ 未公開的內部格式，Anthropic 改版就可能失效 —— 與 /api/oauth/usage 同一風險類別。
+ *    失敗一律回可辨識的 source 字串，不拋例外把 daemon 打掛。
+ *
+ * SECURITY：解出的 master key 與 token 只留在記憶體，**永不列印、永不寫檔、永不上傳**。
+ */
+import { spawnSync } from "node:child_process";
+import { createDecipheriv, pbkdf2Sync } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { pickEntry } from "./creds-win.js";
+/** Chromium 加密區塊前綴。看到別的就是格式變了，不硬解。 */
+const V10 = "v10";
+/** Chromium 在 macOS 的固定 KDF 參數（公開常數，非機密）。 */
+const KDF_SALT = "saltysalt";
+const KDF_ITER = 1003;
+const KDF_KEYLEN = 16; // AES-128
+/** 桌面版憑證檔位置。Claude.app 走 Electron 的 userData 慣例。 */
+function configPath() {
+    return join(homedir(), "Library", "Application Support", "Claude", "config.json");
+}
+/**
+ * 從 Keychain 取「Claude Safe Storage」密碼，PBKDF2 成 16-byte AES 金鑰。
+ *
+ * `security find-generic-password -w -s <svc>` 只回密碼本體。首次存取可能跳授權
+ * 對話（App 首次要求時使用者已同意過，daemon 走同一個 ACL），非互動下拿不到就回
+ * 可辨識原因，不卡住。
+ */
+function masterKey() {
+    const r = spawnSync("security", ["find-generic-password", "-w", "-s", "Claude Safe Storage"], 
+    // ★ timeout 短是刻意的：`Claude Safe Storage` 的 Keychain ACL 只授權給 Claude.app，
+    //   從別的行程存取會**彈授權對話框並阻塞等點擊**。daemon 是非互動的，等不到人點，
+    //   所以與其掛在那裡耗一個 tick，不如快速 timeout 回一個可辨識的原因。
+    //   使用者只要在 Keychain 存取.app 對這個項目按一次「一律允許」，之後就不再彈。
+    { encoding: "utf8", timeout: 8_000 });
+    // ETIMEDOUT 幾乎必然是「在等授權對話」，與「security 不存在」是兩種不同處置：
+    // 前者要使用者去 Keychain 授權一次，後者是環境壞了。分開回報。
+    if (r.error) {
+        const timedOut = r.error.code === "ETIMEDOUT";
+        return [null, timedOut ? "keychain-needs-authorization" : "keychain-spawn-failed"];
+    }
+    // 非零通常是「找不到項目」(44) 或「使用者拒絕授權」(128)。分開讓資料看得出哪一種。
+    if (r.status !== 0) {
+        const code = r.status === 44 ? "no-item" : r.status === 128 ? "denied" : `rc${r.status}`;
+        return [null, `keychain-${code}`];
+    }
+    const pw = (r.stdout ?? "").trim();
+    if (!pw)
+        return [null, "keychain-empty"];
+    try {
+        const key = pbkdf2Sync(pw, KDF_SALT, KDF_ITER, KDF_KEYLEN, "sha1");
+        return [key, "ok"];
+    }
+    catch {
+        return [null, "kdf-failed"];
+    }
+}
+/**
+ * 拆 v10 區塊並用 AES-128-CBC 解密。
+ * 結構：`"v10"`(3B) │ ciphertext(16 的倍數，含 PKCS7)。IV 固定為 16 個 0x20。
+ *
+ * 與 Windows 的 decryptV10 分開實作而非共用：那邊是 GCM（有 nonce/tag 切割），
+ * 這邊是 CBC（固定 IV、無 tag），共用只會讓兩邊都變成一堆 if。挑選邏輯才是該共用的
+ * 部分，那個已經共用（pickEntry）。
+ */
+export function decryptDesktopMac(b64, key) {
+    let blob;
+    try {
+        blob = Buffer.from(b64, "base64");
+    }
+    catch {
+        return [null, "cache-bad-base64"];
+    }
+    if (blob.subarray(0, 3).toString("latin1") !== V10) {
+        return [null, `cache-not-v10:${blob.subarray(0, 3).toString("latin1")}`];
+    }
+    const ct = blob.subarray(3);
+    // CBC 密文長度必為 16 的倍數且至少一個區塊。不符 = 資料壞了，別餵給 decipher。
+    if (ct.length === 0 || ct.length % 16 !== 0)
+        return [null, `cache-bad-ct-len:${ct.length}`];
+    try {
+        const iv = Buffer.alloc(16, 0x20); // 16 個空白
+        const d = createDecipheriv("aes-128-cbc", key, iv);
+        // autoPadding 預設 true，Node 會驗並剝 PKCS7；padding 不對會在 final() 拋。
+        return [Buffer.concat([d.update(ct), d.final()]).toString("utf8"), "ok"];
+    }
+    catch {
+        // PKCS7 驗證失敗 = 金鑰不對或資料被改過。不要當成「格式變了」。
+        return [null, "cache-decrypt-failed"];
+    }
+}
+/**
+ * macOS 桌面版憑證。回 `[creds, source]`；失敗時 creds 為 null、source 是可辨識原因
+ * （會記進 health / cred_source，之後從資料就看得出卡在哪一步）。
+ */
+export function fromMacDesktop() {
+    if (process.platform !== "darwin")
+        return [null, "not-macos"];
+    const cfgPath = configPath();
+    if (!existsSync(cfgPath))
+        return [null, "desktop-no-config"];
+    let cfg;
+    try {
+        cfg = JSON.parse(readFileSync(cfgPath, "utf8"));
+    }
+    catch {
+        return [null, "desktop-config-unreadable"];
+    }
+    // V2 是新版；舊版鍵名無 V2 後綴。先新後舊，與 Windows 版一致。
+    const cached = cfg["oauth:tokenCacheV2"] ?? cfg["oauth:tokenCache"];
+    if (typeof cached !== "string" || !cached)
+        return [null, "desktop-no-token-cache"];
+    const [key, keyWhy] = masterKey();
+    if (!key)
+        return [null, `desktop-${keyWhy}`];
+    const [plain, decWhy] = decryptDesktopMac(cached, key);
+    if (!plain)
+        return [null, `desktop-${decWhy}`];
+    const [creds, pickWhy] = pickEntry(plain); // ★ 與 Windows 共用挑選邏輯
+    if (!creds)
+        return [null, `desktop-${pickWhy}`];
+    return [creds, "desktop-mac"];
+}

package/dist/creds.js

@@ -14,6 +14,7 @@ import { userInfo } from "node:os";
 import { readFileSync } from "node:fs";
 import { claudeDir, credsPath } from "./paths.js";
 import { fromWindowsDesktop } from "./creds-win.js";
+import { fromMacDesktop } from "./creds-mac-desktop.js";
 /** 可區分的結束碼 —— daemon 靠這個把「token 過期」和「網路壞掉」分開記錄。
  *  過去兩者都是 exit 1，daemon 只能寫 sample-failed，於是 2026-08-22 那次
  *  token 過期靜默死了 17.6 小時沒人發現。 */
@@ -111,7 +112,9 @@ const expired = (o) => Boolean(o.expiresAt && Date.now() >= o.expiresAt);
 const SOURCES = [
     fromKeychain, // macOS 主儲存
     fromFile, // CLI 的檔案（Windows/Linux 是主儲存；mac 上只是過時副本）
-    fromWindowsDesktop, // Windows 桌面版（MSIX，加密）
+    fromWindowsDesktop, // Windows 桌面版（MSIX，DPAPI+AES-GCM）
+    fromMacDesktop, // macOS 桌面版（Keychain+AES-CBC）—— 排最後：只有前面都過期/沒有
+    // 才需要它，且取 Keychain 主金鑰有成本，不該每次都跑
 ];
 export function loadToken() {
     const why = [];

package/dist/doctor.js

@@ -15,6 +15,7 @@ import { homedir, platform, release, userInfo } from "node:os";
 import { join } from "node:path";
 import { EXIT, loadToken } from "./creds.js";
 import { desktopDataDirs } from "./creds-win.js";
+import { fromMacDesktop } from "./creds-mac-desktop.js";
 import { claudeDir, claudeSettingsPath, configPath, credsPath, devicePath, projectsDir, serverUrl, stateDir, } from "./paths.js";
 import { healthWarning, loadHealth } from "./health.js";
 import { readJson } from "./util.js";
@@ -113,6 +114,31 @@ export async function doctor() {
             out.push(ok(`執行原則    ${policy}（不會擋 .ps1 啟動器）`));
         }
     }
+    // ── macOS 桌面版（Claude.app）──
+    // 與 Windows 段對稱：只用桌面版、沒開過 CLI 的 mac 使用者，Keychain 那份是舊 CLI
+    // 殘留、會過期，真正的活 token 在桌面版加密庫裡。把狀態攤開，否則診斷會誤判成
+    // 「token 過期，去 /login」——但那治標不治本。
+    if (platform() === "darwin") {
+        const cfg = join(homedir(), "Library", "Application Support", "Claude", "config.json");
+        if (!existsSync(cfg)) {
+            out.push(info("桌面版      找不到 config.json（沒裝桌面版就正常）"));
+        }
+        else {
+            const [creds, why] = fromMacDesktop();
+            if (creds) {
+                out.push(ok(`桌面版      憑證可讀（來源 ${why}, tier=${creds.rateLimitTier}）`));
+            }
+            else if (why === "desktop-keychain-needs-authorization") {
+                out.push(bad("桌面版      Keychain 需要授權一次"));
+                problems.push("macOS 桌面版憑證庫需要授權：在終端機跑一次 " +
+                    '`security find-generic-password -w -s "Claude Safe Storage"`，' +
+                    "跳出對話框時按**一律允許**（Always Allow）。之後背景採樣就讀得到。");
+            }
+            else {
+                out.push(info(`桌面版      ${why}`));
+            }
+        }
+    }
     // ── Windows 桌面版（MSIX）──
     // 只用桌面版、沒登入過 CLI 的人，.credentials.json 裡根本不會有 claudeAiOauth。
     // 這一段把「桌面版憑證庫在哪、有沒有東西」攤開，否則診斷又會退回「猜 + 手寫指令」。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tsa-group/claude-usage",
-  "version": "0.4.8",
+  "version": "0.4.9",
   "description": "Per-user Claude usage collector — measures Claude Code token detail and account-level rate-limit utilization locally, reports to your own ingest server.",
   "type": "module",
   "bin": {