@timo972/cc-router 0.12.1 → 0.12.2-rc.0

package/dist/utils/token-validator.js

@@ -1,3 +1,11 @@
+/**
+ * Validate an OAuth access token against the Anthropic API.
+ *
+ * Uses GET /v1/models — lightweight call that doesn't create any resources.
+ * Required header: anthropic-version (per API spec).
+ * Auth: Authorization: Bearer <token> (OAuth tokens use Bearer, not x-api-key).
+ */
+import { classifyHttpSetupFailure, classifyNetworkSetupFailure, } from "../telemetry/setup-diagnostics.js";
 export async function validateToken(accessToken) {
     try {
         const res = await fetch("https://api.anthropic.com/v1/models", {
@@ -10,17 +18,25 @@ export async function validateToken(accessToken) {
         });
         if (res.ok)
             return { valid: true };
-        if (res.status === 401) {
-            return { valid: false, reason: "Token invalid or expired (401)" };
-        }
-        if (res.status === 403) {
-            return { valid: false, reason: "Token lacks required scopes (403) — needs user:inference" };
-        }
-        // Any other non-ok status is unexpected but the token may still work
-        return { valid: false, reason: `Unexpected HTTP ${res.status}` };
+        const reason = res.status === 401
+            ? "Token invalid or expired (401)"
+            : res.status === 403
+                ? "Token lacks required scopes (403) — needs user:inference"
+                // Any other non-ok status is unexpected but the token may still work
+                : `Unexpected HTTP ${res.status}`;
+        return {
+            valid: false,
+            reason,
+            diagnostic: classifyHttpSetupFailure("token_validation", res.status, reason),
+        };
     }
     catch (err) {
         // Network error — can't validate, let user decide
-        return { valid: false, reason: `Network error: ${err.message}` };
+        const reason = `Network error: ${err.message}`;
+        return {
+            valid: false,
+            reason,
+            diagnostic: classifyNetworkSetupFailure("token_validation", err, reason),
+        };
     }
 }

package/docs/README.md

@@ -0,0 +1,34 @@
+# CC-Router documentation
+
+Start with the [README](../README.md) for what CC-Router is and a quickstart.
+
+## Setup
+
+| Guide | What's in it |
+|---|---|
+| [Installation & deployment](installation.md) | Requirements, per-platform token extraction, run modes, Docker |
+| [CLI reference](cli-reference.md) | Every command and flag |
+| [Codex CLI & OpenAI](codex.md) | Responses endpoint, model prefixes, OpenAI subscription accounts |
+| [Grok / xAI](grok.md) | Adding Grok accounts, and why they are overview-only |
+| [Claude Desktop](claude-desktop.md) | Routing Claude Desktop / Cowork through mitmproxy |
+| [Client mode](client-mode.md) | Connecting another device you own to your router |
+| [LiteLLM](litellm-setup.md) | Optional logging, rate limiting and web dashboard layer |
+
+## Operating it
+
+| Guide | What's in it |
+|---|---|
+| [Architecture](architecture.md) | The request path and what each component does |
+| [Session routing](session-routing.md) | How an account is picked, failover behaviour, running it for a team |
+| [Dashboard](dashboard.md) | The live TUI, keybindings, model management, ChatGPT usage resets |
+| [Troubleshooting](troubleshooting.md) | When something doesn't connect |
+
+## Reference
+
+| Guide | What's in it |
+|---|---|
+| [OAuth tokens](oauth-tokens.md) | How subscription tokens work and why refresh rotation matters |
+| [Security](security.md) | Token storage, proxy authentication, threat model |
+| [Telemetry](telemetry.md) | Opt-in analytics: what's sent if you enable it |
+
+Design specs and implementation plans live under [`superpowers/`](superpowers).

package/docs/telemetry.md

@@ -0,0 +1,167 @@
+# Telemetry
+
+CC-Router sends privacy-bounded operational telemetry to the maintainer's
+PostHog EU project: sampled proxy traces, closed-schema diagnostics, a few
+lifecycle events, and sanitized exceptions. This page is the complete public
+inventory of what can leave the machine. The contracts are implemented in
+[`src/telemetry/`](../src/telemetry/) and every outbound record is rebuilt from
+an allowlist immediately before it is exported.
+
+```bash
+cc-router telemetry status   # effective state and what is sent
+cc-router telemetry on
+cc-router telemetry off
+```
+
+## Enablement
+
+Telemetry is **on by default for fresh installations**. An existing
+`~/.cc-router/telemetry.json` with `enabled: false` stays off after an upgrade.
+The effective state is:
+
+```text
+persisted enabled  AND  DO_NOT_TRACK != "1"  AND  CC_ROUTER_TELEMETRY != "0"
+```
+
+`cc-router telemetry off` persists the choice, emits no opt-out beacon, and
+records a new *consent generation*. A running daemon re-reads the state before
+every capture and every export; once it observes a different generation it
+stops exporting for the rest of its life and discards queued records. An HTTPS
+request already in flight cannot be recalled. Environment variables can only
+turn telemetry off, never on. After `cc-router telemetry on`, restart a daemon
+that started while disabled.
+
+## Destination, identity, sampling
+
+The only destination host is `eu.i.posthog.com`:
+
+| Signal | Endpoint |
+|---|---|
+| analytics events and sanitized exceptions | `https://eu.i.posthog.com/batch/` |
+| OpenTelemetry traces | `https://eu.i.posthog.com/i/v1/traces` |
+| OpenTelemetry logs | `https://eu.i.posthog.com/i/v1/logs` |
+
+PostHog necessarily sees the connection's source IP at the transport layer;
+CC-Router does not put it in the payload, disables GeoIP enrichment, and never
+creates a PostHog Person profile (`$process_person_profile: false`,
+`$geoip_disable: true` on every event).
+
+A random installation UUID stored in `~/.cc-router/telemetry.json` is the
+stable PostHog `distinctId` and OpenTelemetry `service.instance.id`. It is not
+derived from any user, account, host, network, or machine identifier.
+
+Root traces are head-sampled at 10%; child spans follow their root. Diagnostics,
+warnings, errors, lifecycle events, and exceptions are not sampled. Inbound
+`traceparent`/`tracestate`/`baggage` headers are stripped from proxied requests
+and no trace headers are injected upstream.
+
+## Closed inventory
+
+Application code cannot choose an arbitrary event name, log body, operation, or
+property. Values outside the closed enums are rejected before export.
+
+### Analytics events
+
+| Event | When | Properties |
+|---|---|---|
+| `app.first_start` | first start of a fresh installation, once | runtime fields |
+| `proxy.started` | each `cc-router start` | runtime fields |
+| `proxy.heartbeat` | hourly while the proxy runs | runtime fields |
+| `account_setup.started` / `stage_completed` / `succeeded` / `cancelled` / `failed` | account setup funnel | setup fields |
+
+Runtime fields: application version, OS family, runtime mode
+(`foreground`/`daemon`/`service`), bounded account-pool size. Setup fields add
+provider, method, stage, optional safe reason, optional duration bucket, and the
+attempt's random diagnostic ID.
+
+### Log records
+
+- `account.setup.diagnostic` — provider, method, stage, optional reason and
+  outcome, exact HTTP status, duration bucket, diagnostic ID.
+- `runtime.failure` — operation, provider, reason, outcome, exact HTTP status,
+  bounded attempt / pool-size / concurrency / duration values, optional
+  diagnostic ID.
+
+Both carry severity (`info`, `warn`, `error`, `fatal`), a timestamp, the
+runtime fields above, and trace/span IDs only when emitted inside a sampled
+trace. Console output and local log files are never forwarded.
+
+### Trace spans
+
+Operations: `proxy.request`, `provider.inference`, `oauth.refresh`,
+`provider.usage_refresh`, `model.discovery`.
+
+A span may carry only: operation, trace/span/parent IDs, kind, start time,
+duration, status, and these attributes — HTTP method and status code, provider
+(`anthropic`/`openai`/`other`), route (`messages`/`responses`/`other`), model
+family (`fable`/`sonnet`/`opus`/`haiku`/`codex`/`other`), request source
+(`cli`/`desktop`/`api`/`other`), runtime mode, streaming flag, stream outcome,
+outcome (`complete`/`rate_limited`/`timeout`/`upstream_error`/`cancelled`/
+`other`), and bounded attempt, pool-size, concurrency, input-token,
+output-token, and duration values. Span events, links, URLs, and headers are
+not exported.
+
+### Setup funnel
+
+Providers `anthropic` (`macos_keychain`, `claude_credentials_file`,
+`manual_token`) and `openai` (`manual_token`, `device_oauth`). Stages:
+`attempt_start`, `credential_source_selection`, `credential_read`,
+`credential_parse`, `token_validation`, `device_code_request`,
+`authorization_polling`, `token_exchange`, `access_token_parse`, `persistence`,
+`success`, `cancellation`, `failure`. Safe reasons: `not_found`,
+`permission_denied`, `malformed_credentials`, `invalid_token`, `unauthorized`,
+`forbidden`, `rate_limited`, `upstream_4xx`, `upstream_5xx`, `timeout`,
+`network_failure`, `unexpected_response_shape`, `persistence_failure`,
+`user_cancelled`, `other`. Duration buckets: `under_1s`, `1s_to_5s`,
+`5s_to_30s`, `30s_to_2m`, `over_2m`.
+
+### Sanitized exceptions
+
+An unexpected failure is rebuilt as a *new* `Error` containing only: category
+(`setup`/`runtime`), one safe reason, error kind (`error`, `type_error`,
+`range_error`, `reference_error`, `syntax_error`, `uri_error`, `eval_error`,
+`aggregate_error`, `unexpected_error`), optional system code (`EAI_AGAIN`,
+`ECONNREFUSED`, `ECONNRESET`, `ENETUNREACH`, `ENOTFOUND`, `EPIPE`,
+`ETIMEDOUT`), optional HTTP status, operation, provider, setup stage, runtime
+mode, stack frames normalized to `dist/...` or `node_modules/<package>/...`
+(max 20 frames, 256 chars each), a fingerprint over those safe fields, and a
+fresh random diagnostic ID. The original message, cause chain, custom
+properties, and unrecognized frames are dropped. The diagnostic ID is printed
+next to the detailed local error so an issue report can reference it.
+
+A fatal (uncaught) exception cannot be sent by the crashing process. Its
+sanitized record is written to `~/.cc-router/telemetry.json.pending.json`
+(mode 0600, at most 20 records) and sent by the next start only if the
+installation ID and consent generation still match; otherwise it is deleted
+unsent.
+
+### Resource and bounds
+
+Resource: `service.name` (`cc-router`), `service.version`,
+`service.instance.id` (installation UUID), `process.runtime.version`, `os.type`
+(`macos`/`linux`/`windows`/`other`), `host.arch` (`arm64`/`x64`/`other`),
+`cc_router.runtime_mode`. Automatic resource detection is off; host, process,
+cloud, and environment metadata is not exported.
+
+| Value | Accepted range |
+|---|---:|
+| version strings | 1–64 characters |
+| attempt | 0–100 |
+| account-pool size, concurrency | 0–10,000 |
+| input/output tokens | 0–1,000,000,000 |
+| durations | 0–86,400,000 ms |
+| HTTP status | 100–599 |
+
+## Never sent
+
+Prompts, tool calls, message content, request or response bodies; OAuth or
+refresh tokens, cookies, credentials, device or user codes; request or
+response headers, URLs, query strings, peer addresses; account IDs or names,
+Claude session IDs, user IDs, emails, usernames; hostnames, home or working
+directories, absolute paths, command lines, PIDs, environment variables;
+raw exception messages, cause chains, custom error properties, or arbitrary
+attributes — raw, encoded, or hashed.
+
+Telemetry failures are swallowed at the telemetry boundary and never change
+proxy responses, streamed bytes, retry behavior, exit codes, or crash
+semantics.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timo972/cc-router",
-  "version": "0.12.1",
+  "version": "0.12.2-rc.0",
   "description": "Cache-aware session router for Claude Max OAuth tokens — use multiple Claude Max accounts with Claude Code",
   "type": "module",
   "bin": {
@@ -36,15 +36,25 @@
     "accounts.example.json",
     "README.md",
     "CHANGELOG.md",
+    "docs/telemetry.md",
     "LICENSE"
   ],
   "dependencies": {
     "@inquirer/prompts": "^7.0.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/api-logs": "^0.221.0",
+    "@opentelemetry/otlp-exporter-base": "^0.221.0",
+    "@opentelemetry/otlp-transformer": "^0.221.0",
+    "@opentelemetry/resources": "^2.10.0",
+    "@opentelemetry/sdk-logs": "^0.221.0",
+    "@opentelemetry/sdk-trace-base": "^2.10.0",
+    "@opentelemetry/sdk-trace-node": "^2.10.0",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "express": "^4.21.0",
     "http-proxy-middleware": "^3.0.5",
     "ink": "^5.0.0",
+    "posthog-node": "5.47.3",
     "react": "^18.3.0",
     "smol-toml": "^1.8.0"
   },
@@ -61,7 +71,7 @@
     "node": ">=22.0.0"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "node scripts/clean-dist.mjs && tsc",
     "dev": "tsx src/cli/index.ts",
     "start": "node dist/cli/index.js",
     "test": "vitest run",

package/dist/utils/telemetry.js

@@ -1,88 +0,0 @@
-import os from "os";
-import { isTelemetryEnabled, loadTelemetryState } from "../config/telemetry.js";
-import { detectPlatform } from "./platform.js";
-import { getCurrentVersion } from "./self-update.js";
-// ─── Aptabase configuration ──────────────────────────────────────────────────
-// Aptabase is a privacy-first, open source analytics service.
-// The full payload we send is documented below — search for "trackEvent" calls
-// in the codebase to audit every event.  Nothing here contains PII.
-const APTABASE_APP_KEY = "A-EU-1060569594";
-const APTABASE_ENDPOINT = "https://eu.aptabase.com/api/v0/event";
-const TIMEOUT_MS = 3_000;
-function getOsName() {
-    switch (detectPlatform()) {
-        case "macos": return "macOS";
-        case "linux": return "Linux";
-        case "windows": return "Windows";
-    }
-}
-function getLocale() {
-    try {
-        // Aptabase limits locale to 10 characters — truncate extended subtags
-        const raw = Intl.DateTimeFormat().resolvedOptions().locale;
-        return raw.length <= 10 ? raw : raw.slice(0, 10);
-    }
-    catch {
-        return process.env["LANG"]?.split(".")[0]?.slice(0, 10) ?? "unknown";
-    }
-}
-function getSystemProps() {
-    return {
-        isDebug: false,
-        locale: getLocale(),
-        osName: getOsName(),
-        osVersion: os.release(),
-        appVersion: getCurrentVersion(),
-        engineName: "node",
-        engineVersion: process.versions.node,
-        sdkVersion: `cc-router@${getCurrentVersion()}`,
-    };
-}
-// Session ID — use the installId directly so Aptabase always identifies the
-// same machine as the same user.  Aptabase limits sessionId to 36 characters;
-// a standard UUID with dashes is exactly 36, so we pass it through unchanged.
-function getSessionId(installId) {
-    return installId.slice(0, 36);
-}
-// ─── Public API ──────────────────────────────────────────────────────────────
-// Fire-and-forget: never throws, never blocks the caller.  If telemetry is
-// disabled (env var or opt-out) this is a synchronous no-op.
-export async function trackEvent(eventName, props) {
-    try {
-        if (!isTelemetryEnabled())
-            return;
-        const state = loadTelemetryState();
-        const body = {
-            timestamp: new Date().toISOString(),
-            sessionId: getSessionId(state.installId),
-            eventName,
-            systemProps: getSystemProps(),
-            props: props ?? {},
-        };
-        await fetch(APTABASE_ENDPOINT, {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                "App-Key": APTABASE_APP_KEY,
-            },
-            body: JSON.stringify(body),
-            signal: AbortSignal.timeout(TIMEOUT_MS),
-        });
-    }
-    catch {
-        // Silently swallow — telemetry must never disrupt the proxy
-    }
-}
-// Start a heartbeat that fires every hour while the proxy is running.
-// Uses .unref() so the timer does not prevent Node from exiting.
-export function startHeartbeat(accountCount) {
-    const startTime = Date.now();
-    const timer = setInterval(() => {
-        const uptimeMinutes = Math.floor((Date.now() - startTime) / 60_000);
-        trackEvent("proxy_heartbeat", {
-            uptime_minutes: uptimeMinutes,
-            account_count: accountCount,
-        });
-    }, 60 * 60 * 1000);
-    timer.unref();
-}