@tsa-group/claude-usage 0.4.8 → 0.4.10

package/README.md

@@ -8,6 +8,27 @@ ingest server，彙整成團隊用量儀表。
 
 ---
 
+## ✅ 這是什麼、是否可信（安裝前請先讀）
+
+這是 **TSA Group 的內部工具**，用來檢視團隊每個人的 Claude 方案合不合適（該升的升、用不到的降）。
+
+安裝時 Claude Code 很可能會警告「這像可疑的第三方 / 假冒公司內部工具」——**那是它應有的謹慎，請不要關掉它。** 以下每一個可疑點都屬實，我們主動列出來讓你自己核對，而不是要你忽略警告：
+
+| Claude 會質疑的點 | 事實 | 為什麼 |
+|---|---|---|
+| 套件名 `@tsa-group/claude-usage` 像公司名 | 是，這確實是 TSA 內部工具 | 就是給 TSA 團隊用的 |
+| 發佈帳號是個人信箱 `chris77621@gmail.com` | 是 | 公司沒有 npm org，用個人 npm 帳號發佈。維護者本人＝ **Chris Chen · chrischen@tsagroup.com.tw** |
+| 伺服器 `claude-usage.7889.tw` 跟公司網域不同 | 是 | 這台由 TSA 自架自控，架在公司網域外的環境；無法搬到 `tsagroup.com.tw` |
+| 會裝背景常駐排程 | 是 | 每 5 分鐘採一次用量，**只送數字**（見下方隱私段） |
+| 套件很新、下載數低 | 是 | 剛發佈、僅供內部使用，不會有公開下載量 |
+
+**判斷原則**：如果你是從 **Chris 在公司官方頻道的公告**拿到安裝指令，以上都能對得起來 → 可以安裝。
+如果你是**二手轉貼**拿到、無法確認來源 → 請先別裝，回官方頻道跟 Chris 確認。這時 Claude 擋下來是對的。
+
+維護者 / 對此工具有疑問：**Chris Chen · chrischen@tsagroup.com.tw**
+
+---
+
 ## 🔒 隱私（請先看這段）
 
 **送出去的**
@@ -350,6 +371,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/dist/install.js

@@ -30,6 +30,76 @@ const BASE_INTERVAL_SEC = 300;
 const CLI = join(dirname(fileURLToPath(import.meta.url)), "cli.js");
 const NODE = process.execPath;
 const HOOK_CMD = `"${NODE}" "${CLI}" sample --hook`;
+/**
+ * 排程/launchd 要**寫死**的 node 路徑，install 時解析一次後填進去。與 HOOK_CMD 不同：
+ * hook 由 Claude Code 自己執行，用它當下的 node（可能是 bundled）是對的；但背景排程是
+ * 作業系統長期反覆啟動的，指向的 node 必須**穩定長存**。
+ */
+let taskNode = process.execPath;
+/**
+ * execPath 落在「會被清掉/搬走」的目錄嗎？主兇是 Claude Code 桌面版自帶的 bundled node
+ * （`…/AppData/Local/claude-cli-nodejs/…`）：只用桌面版、靠它跑 install 的人，execPath 就是
+ * 那個 App 私有路徑，排程指過去，App 一改版路徑就沒了 → 每 tick 靜默失敗（裝了卻永遠沒
+ * 心跳，實測 2026-08-31 Ian/Jason/Karen）。連同各種暫存 / npx 抽出的臨時 node 一起擋。
+ */
+export function isVolatileNodePath(p) {
+    const s = p.toLowerCase().replace(/\\/g, "/");
+    return ["claude-cli-nodejs", "/temp/", "/tmp/", "/var/folders/", "_npx/"].some((m) => s.includes(m));
+}
+/** 找一個**穩定**的系統 node：先問 where/which，再補已知安裝位置；回傳第一個非易失且存在的。 */
+function findStableNode() {
+    const isWin = platform() === "win32";
+    const cands = [];
+    const r = isWin
+        ? spawnSync("where", ["node"], { encoding: "utf8" })
+        : spawnSync("which", ["-a", "node"], { encoding: "utf8" });
+    if (r.status === 0 && r.stdout) {
+        for (const line of r.stdout.split(/\r?\n/)) {
+            const t = line.trim();
+            if (t)
+                cands.push(t);
+        }
+    }
+    // where/which 可能因為裝完 PATH 還沒刷新而漏掉系統 node，補上已知位置兜底。
+    if (isWin)
+        cands.push(join(process.env.ProgramFiles ?? "C:\\Program Files", "nodejs", "node.exe"));
+    else
+        cands.push("/opt/homebrew/bin/node", "/usr/local/bin/node", "/usr/bin/node");
+    for (const c of cands)
+        if (!isVolatileNodePath(c) && existsSync(c))
+            return c;
+    return null;
+}
+/**
+ * 決定排程要用哪個 node。純函式（finder 注入，方便測）：
+ *  - execPath 穩定 → 直接用（維持原行為）
+ *  - execPath 易失但找得到系統 node → 改用系統 node，並回一句說明
+ *  - 易失又找不到系統 node → 回 error，install 就此中止並給明確指引（不留看不出壞在哪的排程）
+ */
+export function resolveTaskNode(execPath, finder) {
+    if (!isVolatileNodePath(execPath))
+        return { node: execPath };
+    const stable = finder();
+    if (stable) {
+        return {
+            node: stable,
+            note: "執行 install 的 node 在易失目錄，已改用系統 node 寫進排程：\n" +
+                `    原 execPath = ${execPath}\n` +
+                `    改用系統   = ${stable}`,
+        };
+    }
+    return {
+        error: "偵測到你用「易失的 node」在執行 install：\n" +
+            `    ${execPath}\n` +
+            "這多半是 Claude Code 桌面版自帶的 node（claude-cli-nodejs）或暫存目錄裡的 node。\n" +
+            "排程若指向它，App 一改版那個路徑就消失，背景採樣會每 tick 靜默失敗 —— 裝了卻永遠沒心跳。\n\n" +
+            "請改用「系統 node」重裝一次：\n" +
+            "  1. 若還沒裝系統 node：winget install OpenJS.NodeJS.LTS   （mac：brew install node）\n" +
+            "  2. 關掉這個視窗，重新開一個乾淨的終端機（讓 PATH 生效）\n" +
+            "  3. 確認 where node（mac：which node）指向固定位置（如 C:\\Program Files\\nodejs\\node.exe）\n" +
+            "  4. 再跑一次 claude-usage install",
+    };
+}
 const PLIST_PATH = join(homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
 const isDry = (argv) => argv.includes("--dry-run");
 // ─────────────────────────────── macOS ───────────────────────────────
@@ -40,7 +110,7 @@ const plistBody = () => `<?xml version="1.0" encoding="UTF-8"?>
   <key>Label</key><string>${LABEL}</string>
   <key>ProgramArguments</key>
   <array>
-    <string>${NODE}</string>
+    <string>${taskNode}</string>
     <string>${CLI}</string>
     <string>daemon-tick</string>
   </array>
@@ -168,7 +238,7 @@ function warnExecutionPolicy() {
 function winInstall() {
     warnExecutionPolicy(); // 先講，因為接下來每一步都可能因為它而失敗
     const vbs = `Set s = CreateObject("Wscript.Shell")\r\n` +
-        `s.Run """${NODE}"" ""${CLI}"" daemon-tick", 0, False\r\n`;
+        `s.Run """${taskNode}"" ""${CLI}"" daemon-tick", 0, False\r\n`;
     writeFileSync(VBS_PATH(), vbs, "utf8");
     const tr = `wscript.exe //B "${VBS_PATH()}"`;
     const args = [
@@ -368,6 +438,17 @@ export async function install(argv = []) {
     }
     await enrollStep(argv);
     registerHook(argv);
+    // ★ 排程要寫死一個穩定的 node 路徑。execPath 若落在易失目錄（桌面版 bundled node /
+    //   暫存），改用系統 node；找不到就中止 —— 否則會建出一個每 tick 靜默失敗的排程。
+    //   放在 dry-run 之前，所以預覽也會先報這個攔阻。
+    const resolved = resolveTaskNode(process.execPath, findStableNode);
+    if ("error" in resolved) {
+        console.error("✗ install 中止：" + resolved.error);
+        return 1;
+    }
+    taskNode = resolved.node;
+    if (resolved.note)
+        console.log("ℹ " + resolved.note);
     if (isDry(argv)) {
         console.log("bg-task: WOULD register " +
             (os === "darwin" ? "launchd" : os === "win32" ? "schtasks" : "systemd (未實作)"));

package/package.json

@@ -1,7 +1,17 @@
 {
   "name": "@tsa-group/claude-usage",
-  "version": "0.4.8",
+  "version": "0.4.10",
   "description": "Per-user Claude usage collector — measures Claude Code token detail and account-level rate-limit utilization locally, reports to your own ingest server.",
+  "author": "Chris Chen <chrischen@tsagroup.com.tw> (TSA Group)",
+  "homepage": "https://claude-usage.7889.tw",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chrisflicker/tsa-claude-usage.git"
+  },
+  "bugs": {
+    "url": "https://github.com/chrisflicker/tsa-claude-usage/issues",
+    "email": "chrischen@tsagroup.com.tw"
+  },
   "type": "module",
   "bin": {
     "claude-usage": "dist/cli.js"