claude-rpc 0.7.2 → 0.7.4

package/README.md

@@ -43,6 +43,8 @@ claude-rpc start
 
 That's the whole pitch. Open Claude Code in any project — the daemon picks it up within a second. Something looks wrong? `claude-rpc doctor`.
 
+> `setup` registers a Windows startup entry and wires hooks into Claude Code's `settings.json`, and the daemon reports anonymous totals by default. All of it is reversible (`claude-rpc uninstall`, `community off`) and fully documented in [`SECURITY.md`](SECURITY.md) — read it first if you want to know exactly what runs.
+
 The Discord *desktop* app must be running. The browser client doesn't expose the local IPC bridge that Rich Presence uses.
 
 <details>
@@ -142,6 +144,8 @@ claude-rpc community report       # one-shot manual flush (testing)
 
 Each report sends only: a `sessionsDelta`, a `tokensDelta`, the claude-rpc version, OS family (`linux`/`darwin`/`win32`), and the anonymous UUID v4. No prompts, paths, models, repos, costs, usernames, or hostnames — the Worker's [`validateReport`](worker/src/index.js) is the schema of record. The full Worker source is in this repo so the privacy claim is auditable.
 
+For a complete account of the sensitive things claude-rpc does — startup persistence, hook injection, every outbound request, and the exact telemetry payload — see [`SECURITY.md`](SECURITY.md). It's also the reference for supply-chain scanner findings (Socket.dev et al.): the flagged persistence and hook-injection behaviors are inherent to the tool and documented there.
+
 ## three pieces, glued by json files
 
 ```

package/SECURITY.md

@@ -0,0 +1,169 @@
+# Security & behavior disclosure
+
+claude-rpc is a Discord Rich Presence daemon for Claude Code. To do its job it
+has to (a) register itself to start on login and (b) wire commands into Claude
+Code's hook system. Both are legitimate, documented behaviors — but they are
+also patterns that automated supply-chain scanners (e.g. Socket.dev) flag,
+because malware persists and injects the same way. This document is the
+audit trail: every sensitive thing the package does, where in the source it
+lives, why it's there, its blast radius, and how to reverse or disable it.
+
+Everything below is verifiable against the published source — there is no
+minified bundle, no obfuscation, no `eval`/`new Function`, and no remote code
+fetch-and-execute anywhere in `src/`.
+
+## TL;DR for reviewers
+
+| Behavior | Where | Scope | Reversible? |
+| --- | --- | --- | --- |
+| Startup persistence | `src/install.js` → `addStartupEntry` | `HKCU` Run key, current user, no admin | Yes — `claude-rpc uninstall` / `removeStartupEntry` |
+| Hook injection | `src/install.js` → `installHooks` | Only into Claude Code's own `settings.json`, only our own commands | Yes — `uninstallHooks` removes exactly what it added |
+| Outbound network | `src/community.js`, `src/gist.js`, `default-config.js` asset URLs | Anonymous counters + (opt-in) gist publish + GIF assets | Telemetry: `community off`. Gist: only on explicit `badge --gist`. |
+| Local subprocess | `reg.exe`, `git`, `gh` | Static args, no shell interpolation of untrusted input | n/a |
+
+No credential access, no filesystem scanning outside `~/.claude-rpc` and Claude
+Code transcripts, no keylogging, no clipboard access, no AV/EDR evasion.
+
+## 1. Startup persistence (Windows Run key)
+
+**Source:** `src/install.js`, `addStartupEntry` / `removeStartupEntry`.
+
+On Windows, `setup` writes one value:
+
+```
+HKCU\Software\Microsoft\Windows\CurrentVersion\Run
+  ClaudeRPC = "<path-to-exe>" daemon
+```
+
+- **Why:** the Discord presence is driven by a long-lived daemon. If it doesn't
+  restart on login, your presence silently stops working after every reboot.
+- **Scope:** `HKCU` (current user) only. No admin elevation, no `HKLM`, no
+  service install, no scheduled task.
+- **Reverse it:** `claude-rpc uninstall` deletes the value. You can also delete
+  it by hand in `regedit` or with
+  `reg delete "HKCU\...\Run" /v ClaudeRPC /f`.
+- The value points at the canonical install path (`%LOCALAPPDATA%`-class dir),
+  not at wherever you happened to run the installer from — see
+  `ensureCanonicalExe`.
+
+Non-Windows platforms get **no** persistence registration (`install()` warns
+and skips it).
+
+## 2. Hook injection into Claude Code
+
+**Source:** `src/install.js`, `installHooks` / `uninstallHooks`.
+
+`setup` adds command hooks to Claude Code's `settings.json` for eight lifecycle
+events: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`,
+`Stop`, `SubagentStop`, `Notification`, `SessionEnd`. Each entry looks like:
+
+```jsonc
+{ "matcher": "", "hooks": [{ "type": "command", "command": "\"<exe>\" hook PostToolUse" }] }
+```
+
+- **Why:** this *is* the integration. Claude Code's hook system is the
+  supported, documented way for a tool to observe session lifecycle. The hook
+  reads the event JSON on stdin, updates `~/.claude-rpc/state.json`, and prints
+  `{"continue":true}`. It never blocks, rewrites, or vetoes a tool call — see
+  `src/hook.js`, `processHookEvent`.
+- **What the hook reads:** tool name, file path of the active tool, token usage
+  counters, and `git push`/`git commit` detection (for the "just shipped"
+  card). It writes only to local state/log files. It does not read file
+  *contents*, prompts, or responses beyond the usage counters Claude provides.
+- **Scope:** the installer only ever touches entries whose command matches
+  `isOurHookCommand` (contains `claude-rpc` or `hook.js`). It will not modify,
+  reorder, or delete anyone else's hooks.
+- **Reverse it:** `claude-rpc uninstall` (or `uninstallHooks`) strips exactly
+  the entries it added and leaves the rest of `settings.json` intact.
+
+## 3. Outbound network
+
+There are three distinct network behaviors. Two are optional; one is cosmetic.
+
+### 3a. Community totals (telemetry) — ON by default for fresh installs
+
+**Source:** `src/community.js`; endpoint in `src/default-config.js`
+(`community.endpoint`); receiving end is the full Worker source in
+[`worker/src/index.js`](worker/src/index.js).
+
+A fresh install mints an anonymous UUID v4 and the daemon POSTs to
+`https://claude-rpc-totals.claude-rpc.workers.dev/report` every 30 minutes.
+The **complete** payload (see `buildPayload`, enforced by the Worker's
+`validateReport`) is:
+
+```json
+{
+  "instanceId": "<random UUID v4>",
+  "sessionsDelta": 3,
+  "tokensDelta": 142000,
+  "version": "0.7.3",
+  "osFamily": "win32",
+  "ts": 1716500000000
+}
+```
+
+What is **not** sent, ever: prompts, responses, file paths, file contents,
+project/repo names, models, cost figures, usernames, hostnames, IP (beyond what
+any HTTP request inherently exposes to Cloudflare's edge), or absolute counter
+values — only forward deltas since the last accepted report.
+
+- **Opt out any time:** `claude-rpc community off`.
+- **Upgraders are protected:** anyone upgrading from a pre-v0.7 config is
+  written `community.enabled: false`; re-enabling requires the explicit consent
+  flow `claude-rpc community on`, which prints the payload schema first.
+- **Why on by default:** the live badges in the README aggregate these counters.
+  The trade-off is disclosed here, in the README, and at install time.
+- **Auditable:** the Worker persists only two running integers and a 30-day
+  `seen:<instanceId>` dedup marker. The source is in this repo.
+
+### 3b. Gist badge publishing — only on explicit command
+
+**Source:** `src/gist.js`. Runs **only** when you run `claude-rpc badge --gist`.
+Publishes a badge SVG to *your own* GitHub gist via the `gh` CLI or a
+`GH_TOKEN` you supply with `gist` scope. Hits `api.github.com` /
+`gist.github.com`. Never runs unattended, never on install, never from the
+daemon.
+
+### 3c. Presence GIF assets — Discord-side only
+
+`default-config.js` references `https://cdn.qualit.ly/clawd-*.gif`. These URLs
+are handed to Discord as image keys; **Discord's** client fetches them to render
+the card. The daemon itself doesn't download them. Swap them for your own URLs
+in `config.json` if you prefer.
+
+## 4. Local subprocesses
+
+All `child_process` use is static-argument and visible:
+
+- `reg.exe add/delete` — the Run key above (`src/install.js`).
+- `git` — read last commit subject / branch for the "just shipped" card
+  (`src/git.js`).
+- `gh repo view --json isPrivate` — auto-hide GitHub-private repos from the card
+  (`src/privacy.js`); 1.5s timeout, silent skip if `gh` is absent.
+- `gh gist` — only under 3b above.
+
+No subprocess interpolates untrusted/remote input into a shell. The one
+`shell: true` call (`verifyHookPipe`) uses only static, trusted args and is
+documented inline as such.
+
+## 5. What it stores locally
+
+Under `~/.claude-rpc/` (a.k.a. `%APPDATA%\claude-rpc\` on Windows):
+`config.json`, `state.json`, `aggregate.json`, `events.jsonl` (rotated at 5 MB),
+`private-list.json`, `community-cursor.json`. The scanner also reads Claude Code
+transcript files to build aggregates. None of this leaves your machine except
+the minimal telemetry in 3a.
+
+## 6. Privacy controls
+
+Independent of telemetry, the Discord card has a privacy valve (`src/privacy.js`):
+per-project `.claude-rpc.json`, a runtime private-list, config glob patterns, and
+`gh`-based auto-hide of private repos. Levels: `public` / `name-only` / `hidden`.
+Local dashboards and aggregates are never redacted — privacy is a one-way valve
+from local state to Discord only.
+
+## Reporting a vulnerability
+
+Open an issue at https://github.com/rar-file/claude-rpc/issues, or for anything
+sensitive email c.archer.simmons@gmail.com. Please include version
+(`claude-rpc --version`), OS, and repro steps.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-rpc",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "Discord Rich Presence for Claude Code — live model, project, tokens, and lifetime stats driven by Claude Code's hook system.",
   "type": "module",
   "license": "MIT",
@@ -57,6 +57,7 @@
     "src",
     "config.example.json",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "SECURITY.md"
   ]
 }

package/src/doctor.js

@@ -228,19 +228,30 @@ function checkDaemonLog() {
   }
   const ageMin = (Date.now() - st.mtimeMs) / 60_000;
   const sizeKB = (st.size / 1024).toFixed(1);
-  // Look for "Discord RPC connected" in the tail to confirm Discord IPC.
-  let connected = false;
+  // Infer live IPC state from the log. The daemon connects once and stays
+  // connected without re-logging, so grepping only for "connected" produces
+  // a false warning on a long-lived daemon. Instead: "Discord RPC connected",
+  // "Presence updated", and "Presence cleared" all imply a live connection —
+  // the latter two only log *after* the daemon's `connected` guard passes and
+  // a setActivity/clearActivity succeeds (see daemon.js). A later "retry in
+  // Ns" / "login failed" / "disconnected" line means it dropped. Whichever
+  // happened most recently wins.
+  let ipc = 'unknown';
   try {
-    const tail = readFileSync(LOG_PATH, 'utf8').split('\n').slice(-50).join('\n');
-    connected = /Discord RPC connected/i.test(tail);
-  } catch { /* log unreadable — connected stays false, warn check renders */ }
-  if (connected) {
+    for (const line of readFileSync(LOG_PATH, 'utf8').split('\n').slice(-80)) {
+      if (/Discord RPC connected|Presence updated|Presence cleared/i.test(line)) ipc = 'up';
+      else if (/retry in \d+s|login failed|Discord disconnected/i.test(line)) ipc = 'down';
+    }
+  } catch { /* log unreadable — ipc stays 'unknown', warn renders */ }
+  if (ipc === 'up') {
     check('discord IPC connection', 'pass',
-      `${sizeKB} KB log · last write ${ageMin.toFixed(1)} min ago`);
-  } else {
-    check('discord IPC connection', 'warn',
-      `log shows no recent "connected" line`,
+      `connected · ${sizeKB} KB log · last write ${ageMin.toFixed(1)} min ago`);
+  } else if (ipc === 'down') {
+    check('discord IPC connection', 'warn', 'daemon is reconnecting to Discord',
       'is the discord desktop client running? rpc only works via desktop, not browser');
+  } else {
+    check('discord IPC connection', 'warn', 'no connection activity in the log yet',
+      'start the daemon with discord desktop running');
   }
 }
 

package/src/privacy.js

@@ -25,7 +25,10 @@ import { execFileSync } from 'node:child_process';
 import { join, basename, dirname, resolve as resolvePath } from 'node:path';
 import { DATA_DIR } from './paths.js';
 
-const PRIVATE_LIST_PATH = join(DATA_DIR, 'private-list.json');
+// CLAUDE_RPC_PRIVATE_LIST lets tests point the runtime store at a temp file
+// instead of the user's real ~/.claude-rpc/private-list.json. Unset in normal
+// operation.
+const PRIVATE_LIST_PATH = process.env.CLAUDE_RPC_PRIVATE_LIST || join(DATA_DIR, 'private-list.json');
 const TTL_MS = 5 * 60 * 1000;
 
 const projectFileCache = new Map();   // cwd → { ts, value | null }
@@ -82,7 +85,14 @@ function readPrivateList() {
   if (!existsSync(PRIVATE_LIST_PATH)) return { paths: [] };
   try {
     const v = JSON.parse(readFileSync(PRIVATE_LIST_PATH, 'utf8'));
-    if (Array.isArray(v?.paths)) return v;
+    if (v && typeof v === 'object') {
+      // `paths` is the legacy binary list (presence ≡ hidden). `visibility`
+      // is the richer GUI-managed map: { "<abs cwd>": "hidden|name-only|public" }.
+      return {
+        paths: Array.isArray(v.paths) ? v.paths : [],
+        visibility: (v.visibility && typeof v.visibility === 'object') ? v.visibility : undefined,
+      };
+    }
   } catch { /* broken JSON ≡ no list (treat as empty rather than crash) */ }
   return { paths: [] };
 }
@@ -122,6 +132,50 @@ function isInPrivateList(cwd) {
   );
 }
 
+// ── Central visibility map (GUI-managed) ────────────────────────────────
+// A richer alternative to the binary `paths` list: maps an absolute cwd to
+// an explicit visibility level. Highest-priority runtime layer — an explicit
+// 'public' here even overrides config-glob / gh auto-detect, because the user
+// deliberately marked it. Subdirectories inherit a marked parent.
+
+const VIS_LEVELS = ['public', 'name-only', 'hidden'];
+function normLevel(v) { return VIS_LEVELS.includes(v) ? v : null; }
+
+function visibilityForCwd(cwd) {
+  if (!cwd) return null;
+  const map = readPrivateList().visibility;
+  if (!map) return null;
+  const abs = resolvePath(cwd);
+  if (map[abs]) return normLevel(map[abs]);
+  for (const [p, v] of Object.entries(map)) {
+    if (abs === p || abs.startsWith(p + '/') || abs.startsWith(p + '\\')) return normLevel(v);
+  }
+  return null;
+}
+
+// Set (or clear) the explicit visibility for a cwd. `level` of null/'default'
+// removes the override so resolution falls back through the lower layers.
+// Returns the updated visibility map.
+export function setCwdVisibility(cwd, level) {
+  const abs = resolvePath(cwd);
+  const list = readPrivateList();
+  const map = (list.visibility && typeof list.visibility === 'object') ? list.visibility : {};
+  const norm = normLevel(level);
+  if (norm) map[abs] = norm;
+  else delete map[abs];
+  // A path managed by the map shouldn't also linger in the legacy binary
+  // list, where it would always read as hidden regardless of the map value.
+  list.paths = (list.paths || []).filter((p) => p !== abs);
+  list.visibility = map;
+  writePrivateList(list);
+  return map;
+}
+
+// Read the current explicit-visibility map (abs cwd → level).
+export function listVisibility() {
+  return readPrivateList().visibility || {};
+}
+
 // ── GitHub-private detection (best-effort, gh CLI) ──────────────────────
 
 function detectGithubPrivate(cwd) {
@@ -151,6 +205,12 @@ export function resolveVisibility(cwd, config = {}) {
   if (proj?.visibility) {
     return { visibility: proj.visibility, projectName: proj.projectName, reason: '.claude-rpc.json' };
   }
+  // Central GUI-managed map (incl. explicit 'public' as an opt-out of
+  // auto-hide). Ranks above the legacy binary list and config/gh layers.
+  const mapped = visibilityForCwd(cwd);
+  if (mapped) {
+    return { visibility: mapped, projectName: proj?.projectName ?? null, reason: 'private-list (visibility)' };
+  }
   if (isInPrivateList(cwd)) {
     return { visibility: 'hidden', projectName: proj?.projectName ?? null, reason: 'private-list' };
   }

package/src/server/api.js

@@ -173,3 +173,38 @@ export function dayDetail(dayKeyStr) {
   if (!day) return null;
   return { day: dayKeyStr, ...day };
 }
+
+// Flatten the aggregate's byDay map into a daily-rows CSV for spreadsheet /
+// pandas analysis. One row per day, sorted ascending. Date keys are
+// YYYY-MM-DD and all other columns are numeric, so nothing needs quoting.
+export const CSV_COLUMNS = [
+  'date', 'activeMs', 'activeHours', 'sessions', 'userMessages', 'toolCalls',
+  'linesAdded', 'linesRemoved', 'cost', 'inputTokens', 'outputTokens',
+  'cacheReadTokens', 'cacheWriteTokens', 'notifications',
+];
+
+export function aggregateToCsv(agg) {
+  const byDay = (agg && agg.byDay) || {};
+  const rows = [CSV_COLUMNS.join(',')];
+  for (const date of Object.keys(byDay).sort()) {
+    const d = byDay[date] || {};
+    const activeMs = d.activeMs || 0;
+    rows.push([
+      date,
+      activeMs,
+      (activeMs / 3_600_000).toFixed(3),
+      d.sessions || 0,
+      d.userMessages || 0,
+      d.toolCalls || 0,
+      d.linesAdded || 0,
+      d.linesRemoved || 0,
+      (d.cost || 0).toFixed(4),
+      d.inputTokens || 0,
+      d.outputTokens || 0,
+      d.cacheReadTokens || 0,
+      d.cacheWriteTokens || 0,
+      d.notifications || 0,
+    ].join(','));
+  }
+  return rows.join('\n') + '\n';
+}