@pify/usage 0.4.0 → 0.5.0

package/README.md

@@ -45,19 +45,33 @@ Context window: 22.6k of 200.0k used (11%)
 - **Per-project spend** (v0.2): pi stores sessions one directory per project, so the dashboard can show where the money actually went — the top 5 projects by cost, all time.
 - **`usage_status` tool**: the agent can check session + today totals before committing to expensive work (subagent fan-outs, large reads).
 
-## `/usage quota` (v0.3)
+## `/usage quota` (v0.5)
 
 The one command in this package that touches the network, and only when you run it:
 
 ```
-Quota (openrouter · sk-or-v1-abc...xyz)
-  spent    $0.32 (no credit limit on this key)
-  window   day $0.32 · week $0.32 · month $0.32
+Quota (OpenRouter · sk-or-v1-abc...xyz)
+  spent    $0.33 (no credit limit on this key)
+  window   day $0.01 · week $0.33 · month $0.33
+
+Quota (DeepSeek · granted 10 · topped up 100)
+  balance  CNY 110.00
 ```
 
-The key is read from the same `~/.pi/agent/auth.json` pi already uses (or `OPENROUTER_API_KEY`) — no second place to configure credentials — and only the provider's own masked label is ever printed. An 8-second timeout, and any failure renders as `unavailable — HTTP 401` rather than throwing.
+**Documented endpoints only.** OpenRouter's `/api/v1/key` and DeepSeek's `/user/balance` are published APIs that report a real balance. The subscription-quota endpoints some plugins use for OpenAI, Anthropic and Gemini are undocumented private APIs reverse-engineered from vendor CLIs — they break without notice and were never offered to third parties, so this package does not call them. Providers you have not configured are simply not shown; they are not failures.
+
+**A credentialed request is pinned down** (v0.5), because it carries your provider key:
+
+- HTTPS only, and the host must be on that provider's allowlist.
+- Redirects are refused outright. Following one lets whatever answered choose where the next request goes, with the header already attached.
+- A non-2xx body is **never read**. Error bodies echo request details back, and an echoed `Authorization` header pasted into a notification is exactly the leak this must not cause — the status alone becomes the message.
+- Raw exception text is dropped rather than shown, and everything printed passes a redactor as a last line of defence.
+
+**The key comes from pi** (v0.5): resolved through `modelRegistry`, not by reading `auth.json`. pi owns credential storage — env precedence, OAuth, whatever it grows next — and parsing that file here meant handling secrets this package has no business touching, with a stale copy of pi's rules. Only the provider's own masked label is ever printed.
+
+An 8-second timeout per provider, and any failure renders as `unavailable — the provider rejected the key` rather than throwing.
 
-Only OpenRouter is implemented. The other providers report opaque rate-limit windows rather than a balance, and chasing all of them costs ~18k lines of per-provider contract maintenance (see `@narumitw/pi-usage` if you need them today).
+The hardening, the multi-provider shape, and the documented-APIs-only stance are from [`@imdlan/pi-usage`](https://github.com/imdlan/pi-usage), which supports Z.ai as well.
 
 ## License
 

package/extensions/usage.ts

@@ -30,7 +30,8 @@ import { readFileSync } from "node:fs";
 import { addRecord, aggregate, recordFromEntry, windowTotals } from "../src/aggregate.ts";
 import { buildBreakdown, formatBreakdown } from "../src/context.ts";
 import { footerText, formatCost, formatTokens, historyBlock, sessionBlock } from "../src/format.ts";
-import { fetchOpenRouterQuota, quotaBlock } from "../src/quota.ts";
+import { QUOTA_PROVIDERS, fetchQuota, quotaReport, type QuotaResult } from "../src/quota.ts";
+import { redact } from "../src/redact.ts";
 import { scanSessions } from "../src/sessions.ts";
 import { emptyTotals, isRecord, type UsageTotals } from "../src/types.ts";
 
@@ -97,15 +98,26 @@ export default function usage(pi: ExtensionAPI) {
    * The key pi itself uses, read from the same auth.json — no second place to
    * configure credentials, and no key is ever printed.
    */
-  function providerKey(provider: string): string {
+  /**
+   * Ask pi for the key rather than reading auth.json. pi owns credential
+   * storage — env precedence, OAuth, whatever it grows next — and parsing
+   * that file here meant handling secrets this package has no business
+   * touching, with a copy of pi's rules that would quietly go stale.
+   */
+  async function providerKey(ctx: UiContext, provider: string): Promise<string> {
+    const registry = ctx.modelRegistry as unknown as {
+      getApiKeyForProvider?: (id: string) => Promise<string | undefined>;
+      getProviderAuth?: (id: string) => Promise<{ auth?: { apiKey?: string } } | undefined>;
+    };
     try {
-      const auth = JSON.parse(readFileSync(join(getAgentDir(), "auth.json"), "utf8")) as Record<string, unknown>;
-      const entry = auth[provider];
-      if (isRecord(entry) && typeof entry.key === "string") return entry.key;
+      const direct = await registry.getApiKeyForProvider?.(provider);
+      if (direct) return direct;
+      const auth = await registry.getProviderAuth?.(provider);
+      if (auth?.auth?.apiKey) return auth.auth.apiKey;
     } catch {
-      // no auth.json, or unreadable — fall through to the environment
+      // an unconfigured provider is not an error here
     }
-    return process.env.OPENROUTER_API_KEY ?? "";
+    return "";
   }
 
   /**
@@ -161,10 +173,24 @@ export default function usage(pi: ExtensionAPI) {
     handler: async (args, ctx) => {
       if (!ctx.hasUI) return;
       if ((args ?? "").trim().toLowerCase() === "quota") {
-        // The one networked call in this package, and only when asked for.
-        ctx.ui.notify("Checking provider quota…", "info");
-        const result = await fetchOpenRouterQuota(providerKey("openrouter"));
-        ctx.ui.notify(quotaBlock(result), result.ok ? "info" : "warning");
+        // The one networked path in this package, and only when asked for.
+        // Providers with no key are skipped entirely rather than reported as
+        // broken: an unconfigured provider is not a failure.
+        const configured: Array<{ provider: (typeof QUOTA_PROVIDERS)[number]; key: string }> = [];
+        for (const provider of QUOTA_PROVIDERS) {
+          const key = await providerKey(ctx, provider.id);
+          if (key) configured.push({ provider, key });
+        }
+        if (configured.length === 0) {
+          ctx.ui.notify(quotaReport([]), "info");
+          return;
+        }
+        ctx.ui.notify(`Checking quota for ${configured.map((c) => c.provider.displayName).join(", ")}…`, "info");
+        const results: QuotaResult[] = [];
+        for (const { provider, key } of configured) {
+          results.push(await fetchQuota(provider, key));
+        }
+        ctx.ui.notify(redact(quotaReport(results)), results.every((r) => r.ok) ? "info" : "warning");
         return;
       }
       ctx.ui.notify(dashboard(ctx), "info");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/usage",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Token and cost reporting for pi sessions: live footer, local-history dashboard with per-project costs, opt-in provider quota",
   "keywords": [
     "pi-package",

package/src/http.ts

@@ -0,0 +1,134 @@
+/**
+ * The one networked path in this package, made boring on purpose.
+ *
+ * A quota call carries the user's provider key in an Authorization header, so
+ * the request has to be pinned down rather than merely aimed at the right URL:
+ *
+ *  - HTTPS only, and the host must be on the caller's allowlist. A typo or a
+ *    future edit cannot point a credentialed request somewhere new.
+ *  - Redirects are refused outright (`redirect: "error"`). Following one means
+ *    a provider — or anything that can answer as one — chooses where the next
+ *    request goes, with the header already attached.
+ *  - A non-2xx body is never read. Error bodies echo request details back, and
+ *    an echoed Authorization header pasted into a notification is exactly the
+ *    leak this package must not cause. The status alone is the message.
+ *  - Everything is classified into a small set of reasons, so the caller can
+ *    say something useful without carrying provider text around.
+ *
+ * `fetchImpl` is injectable so tests never touch the network.
+ *
+ * (Structure and the no-body-on-error rule are from imdlan/pi-usage.)
+ */
+
+export type HttpFailureKind =
+  | "unsafe-url"
+  | "not-allowed"
+  | "auth"
+  | "forbidden"
+  | "rate-limited"
+  | "server"
+  | "http"
+  | "timeout"
+  | "network"
+  | "invalid-json";
+
+export interface HttpFailure {
+  ok: false;
+  kind: HttpFailureKind;
+  reason: string;
+  status?: number;
+}
+
+export interface HttpSuccess<T> {
+  ok: true;
+  status: number;
+  data: T;
+}
+
+export type HttpResult<T> = HttpSuccess<T> | HttpFailure;
+
+export interface ControlledGetOptions {
+  url: string;
+  headers?: Record<string, string>;
+  timeoutMs: number;
+  allowlist: readonly string[];
+  fetchImpl?: typeof fetch;
+  signal?: AbortSignal;
+}
+
+const TIMEOUT_SENTINEL = "pify-usage-timeout";
+
+function fail(kind: HttpFailureKind, reason: string, status?: number): HttpFailure {
+  return { ok: false, kind, reason, ...(status === undefined ? {} : { status }) };
+}
+
+/** Reject anything that is not an allowlisted HTTPS host before dialling. */
+export function checkUrl(url: string, allowlist: readonly string[]): HttpFailure | null {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return fail("unsafe-url", "invalid url");
+  }
+  if (parsed.protocol !== "https:") return fail("unsafe-url", "refused a non-HTTPS url");
+  if (!allowlist.includes(parsed.hostname)) {
+    return fail("not-allowed", `host ${parsed.hostname} is not on the allowlist`);
+  }
+  return null;
+}
+
+export function classifyStatus(status: number): HttpFailure {
+  if (status === 401) return fail("auth", "the provider rejected the key", status);
+  if (status === 403) return fail("forbidden", "the key is not allowed to read usage", status);
+  if (status === 429) return fail("rate-limited", "rate limited by the provider", status);
+  if (status >= 500) return fail("server", "the provider is having trouble", status);
+  return fail("http", `HTTP ${status}`, status);
+}
+
+/** GET JSON from an allowlisted host. Never throws; failure is a value. */
+export async function controlledGetJson<T = unknown>(opts: ControlledGetOptions): Promise<HttpResult<T>> {
+  const urlProblem = checkUrl(opts.url, opts.allowlist);
+  if (urlProblem) return urlProblem;
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(new Error(TIMEOUT_SENTINEL)), opts.timeoutMs);
+  if (opts.signal) {
+    if (opts.signal.aborted) controller.abort();
+    else opts.signal.addEventListener("abort", () => controller.abort(), { once: true });
+  }
+  const doFetch = opts.fetchImpl ?? (globalThis.fetch as typeof fetch);
+
+  let response: Response;
+  try {
+    response = await doFetch(opts.url, {
+      method: "GET",
+      headers: opts.headers ?? {},
+      signal: controller.signal,
+      redirect: "error",
+    });
+  } catch (err) {
+    if (controller.signal.aborted) {
+      const timedOut = String(controller.signal.reason ?? "").includes(TIMEOUT_SENTINEL);
+      return timedOut ? fail("timeout", "the provider did not answer in time") : fail("network", "request aborted");
+    }
+    const message = String((err as { message?: unknown })?.message ?? err).toLowerCase();
+    if (message.includes("redirect")) return fail("unsafe-url", "the provider tried to redirect us");
+    if (message.includes("timeout") || message.includes("timed out")) {
+      return fail("timeout", "the provider did not answer in time");
+    }
+    // The raw error is deliberately dropped: it can carry the request, and the
+    // request carries the key.
+    return fail("network", "could not reach the provider");
+  } finally {
+    clearTimeout(timer);
+  }
+
+  if (response.status >= 200 && response.status < 300) {
+    try {
+      return { ok: true, status: response.status, data: (await response.json()) as T };
+    } catch {
+      return fail("invalid-json", "the provider sent something that is not JSON", response.status);
+    }
+  }
+  return classifyStatus(response.status);
+}

package/src/quota.ts

@@ -1,20 +1,25 @@
 /**
- * Provider quota (v0.3). Everything else in this package is computed from
- * local files — this is the one place that talks to a network, so it is
- * opt-in per call, short-timeout, and never blocks the dashboard: a provider
- * that is slow or down shows as unavailable next to the local numbers.
+ * Provider quota. Everything else in this package is computed from local
+ * files; this is the one place that talks to a network, so it is opt-in per
+ * call, short-timeout, pinned to allowlisted HTTPS hosts, and never blocks the
+ * dashboard: a provider that is slow or down shows as unavailable next to the
+ * local numbers.
  *
- * Only OpenRouter is implemented. @narumitw/pi-usage shows what the full set
- * costs — roughly 18k lines of per-provider contract chasing — and OpenRouter
- * is the one endpoint that reports a real balance rather than an opaque
- * rate-limit window.
+ * Documented endpoints only. OpenRouter's `/api/v1/key` and DeepSeek's
+ * `/user/balance` are both published APIs that report a real balance. The
+ * subscription-quota endpoints some plugins use for OpenAI, Anthropic and
+ * Gemini are undocumented private APIs reverse-engineered from vendor CLIs;
+ * they break without notice and were never offered to third parties, so this
+ * package does not call them. (That line is imdlan/pi-usage's, and it is a
+ * better reason than the maintenance cost this package cited before.)
  */
 
+import { controlledGetJson, type HttpResult } from "./http.ts";
 import { finite, isRecord } from "./types.ts";
 
 export interface QuotaInfo {
   provider: string;
-  /** Spend on this key, in USD, as the provider reports it. */
+  /** Spend on this key, in the provider's currency, as it reports it. */
   used: number | null;
   /** Hard credit limit, when the key has one. */
   limit: number | null;
@@ -25,6 +30,8 @@ export interface QuotaInfo {
   monthly: number | null;
   label: string | null;
   freeTier: boolean | null;
+  /** Currency for the amounts above; USD unless the provider says otherwise. */
+  currency: string;
 }
 
 export type QuotaResult =
@@ -37,6 +44,29 @@ function num(value: unknown): number | null {
   return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
 
+/** "110.00" — DeepSeek reports money as strings. */
+function numeric(value: unknown): number | null {
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  if (typeof value !== "string" || !value.trim()) return null;
+  const parsed = Number.parseFloat(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function emptyQuota(provider: string): QuotaInfo {
+  return {
+    provider,
+    used: null,
+    limit: null,
+    remaining: null,
+    daily: null,
+    weekly: null,
+    monthly: null,
+    label: null,
+    freeTier: null,
+    currency: "USD",
+  };
+}
+
 /**
  * Shape the /api/v1/key payload. OpenRouter reports `limit: null` for keys
  * with no cap, so "no limit" and "limit of zero" must not collapse together.
@@ -53,7 +83,7 @@ export function parseOpenRouterKey(payload: unknown): QuotaInfo | null {
   const remaining = num(data.limit_remaining) ?? (limit !== null && used !== null ? limit - used : null);
 
   return {
-    provider: "openrouter",
+    ...emptyQuota("openrouter"),
     used: used === null ? null : finite(used),
     limit,
     remaining,
@@ -65,60 +95,134 @@ export function parseOpenRouterKey(payload: unknown): QuotaInfo | null {
   };
 }
 
-export type Fetcher = (url: string, init: { headers: Record<string, string>; signal: AbortSignal }) => Promise<{
-  ok: boolean;
-  status: number;
-  json(): Promise<unknown>;
-}>;
+/**
+ * DeepSeek's documented `/user/balance`: a list of per-currency balances. The
+ * first available one is reported; a key with no available balance is still a
+ * successful answer, showing zero rather than an error.
+ */
+export function parseDeepSeekBalance(payload: unknown): QuotaInfo | null {
+  if (!isRecord(payload)) return null;
+  const infos = payload.balance_infos;
+  if (!Array.isArray(infos)) return null;
+
+  const first = infos.find((entry) => isRecord(entry) && numeric(entry.total_balance) !== null);
+  if (!isRecord(first)) {
+    return { ...emptyQuota("deepseek"), remaining: 0 };
+  }
+  const total = numeric(first.total_balance);
+  const granted = numeric(first.granted_balance);
+  const topped = numeric(first.topped_up_balance);
+  const parts = [
+    granted === null ? null : `granted ${granted}`,
+    topped === null ? null : `topped up ${topped}`,
+  ].filter((part): part is string => part !== null);
+
+  return {
+    ...emptyQuota("deepseek"),
+    remaining: total,
+    currency: typeof first.currency === "string" ? first.currency : "USD",
+    label: parts.length > 0 ? parts.join(" · ") : null,
+    freeTier: payload.is_available === false ? null : null,
+  };
+}
 
-/** Fetch the OpenRouter key status. Never throws — failure is a result. */
-export async function fetchOpenRouterQuota(
+export interface QuotaProvider {
+  /** pi's provider id, which is also how the key is looked up. */
+  id: string;
+  displayName: string;
+  url: string;
+  allowlist: readonly string[];
+  parse(payload: unknown): QuotaInfo | null;
+}
+
+export const QUOTA_PROVIDERS: readonly QuotaProvider[] = [
+  {
+    id: "openrouter",
+    displayName: "OpenRouter",
+    url: "https://openrouter.ai/api/v1/key",
+    allowlist: ["openrouter.ai"],
+    parse: parseOpenRouterKey,
+  },
+  {
+    id: "deepseek",
+    displayName: "DeepSeek",
+    url: "https://api.deepseek.com/user/balance",
+    allowlist: ["api.deepseek.com"],
+    parse: parseDeepSeekBalance,
+  },
+];
+
+export function findProvider(id: string): QuotaProvider | undefined {
+  return QUOTA_PROVIDERS.find((provider) => provider.id === id.trim().toLowerCase());
+}
+
+/**
+ * Query one provider. Never throws — failure is a result, and its reason is
+ * this package's own wording, never the provider's response text.
+ */
+export async function fetchQuota(
+  provider: QuotaProvider,
   apiKey: string,
-  fetcher: Fetcher = globalThis.fetch as unknown as Fetcher,
+  fetchImpl?: typeof fetch,
   timeoutMs = QUOTA_TIMEOUT_MS,
 ): Promise<QuotaResult> {
-  if (!apiKey.trim()) return { ok: false, provider: "openrouter", reason: "no API key configured" };
-  try {
-    const response = await fetcher("https://openrouter.ai/api/v1/key", {
-      headers: { Authorization: `Bearer ${apiKey.trim()}` },
-      signal: AbortSignal.timeout(timeoutMs),
-    });
-    if (!response.ok) {
-      return { ok: false, provider: "openrouter", reason: `HTTP ${response.status}` };
-    }
-    const quota = parseOpenRouterKey(await response.json());
-    if (!quota) return { ok: false, provider: "openrouter", reason: "unexpected response shape" };
-    return { ok: true, quota };
-  } catch (err) {
-    return {
-      ok: false,
-      provider: "openrouter",
-      reason: err instanceof Error ? err.message : String(err),
-    };
-  }
+  if (!apiKey.trim()) return { ok: false, provider: provider.id, reason: "no API key configured" };
+
+  const result: HttpResult<unknown> = await controlledGetJson({
+    url: provider.url,
+    headers: { Authorization: `Bearer ${apiKey.trim()}`, Accept: "application/json" },
+    timeoutMs,
+    allowlist: provider.allowlist,
+    fetchImpl,
+  });
+  if (!result.ok) return { ok: false, provider: provider.id, reason: result.reason };
+
+  const quota = provider.parse(result.data);
+  if (!quota) return { ok: false, provider: provider.id, reason: "the response did not match the documented shape" };
+  return { ok: true, quota };
 }
 
-function money(value: number | null): string {
+function money(value: number | null, currency = "USD"): string {
   if (value === null) return "—";
-  if (value === 0) return "$0";
-  if (Math.abs(value) < 0.01) return "<$0.01";
-  return `$${value.toFixed(2)}`;
+  const symbol = currency === "USD" ? "$" : `${currency} `;
+  if (value === 0) return `${symbol}0`;
+  if (Math.abs(value) < 0.01) return `<${symbol}0.01`;
+  return `${symbol}${value.toFixed(2)}`;
 }
 
 export function quotaBlock(result: QuotaResult): string {
-  if (!result.ok) {
-    return `Quota (${result.provider})\n  unavailable — ${result.reason}`;
-  }
+  const id = result.ok ? result.quota.provider : result.provider;
+  const name = findProvider(id)?.displayName ?? id;
+  if (!result.ok) return `Quota (${name})\n  unavailable — ${result.reason}`;
+
   const q = result.quota;
-  const lines = [`Quota (${q.provider}${q.label ? ` · ${q.label}` : ""})`];
-  lines.push(
-    q.limit === null
-      ? `  spent    ${money(q.used)} (no credit limit on this key)`
-      : `  spent    ${money(q.used)} of ${money(q.limit)} · ${money(q.remaining)} left`,
-  );
+  const lines = [`Quota (${name}${q.label ? ` · ${q.label}` : ""})`];
+  if (q.used !== null || q.limit !== null) {
+    lines.push(
+      q.limit === null
+        ? `  spent    ${money(q.used, q.currency)} (no credit limit on this key)`
+        : `  spent    ${money(q.used, q.currency)} of ${money(q.limit, q.currency)} · ${money(q.remaining, q.currency)} left`,
+    );
+  } else if (q.remaining !== null) {
+    lines.push(`  balance  ${money(q.remaining, q.currency)}`);
+  }
   if (q.daily !== null || q.weekly !== null || q.monthly !== null) {
-    lines.push(`  window   day ${money(q.daily)} · week ${money(q.weekly)} · month ${money(q.monthly)}`);
+    lines.push(
+      `  window   day ${money(q.daily, q.currency)} · week ${money(q.weekly, q.currency)} · month ${money(q.monthly, q.currency)}`,
+    );
   }
   if (q.freeTier) lines.push("  tier     free");
   return lines.join("\n");
 }
+
+/** What `/usage quota` prints: every provider that has a key, and nothing else. */
+export function quotaReport(results: QuotaResult[]): string {
+  if (results.length === 0) {
+    return [
+      "No provider with a quota endpoint is configured.",
+      `Supported: ${QUOTA_PROVIDERS.map((p) => p.displayName).join(", ")}.`,
+      "Only documented endpoints are used — OpenAI, Anthropic and Gemini publish none for subscription quota.",
+    ].join("\n");
+  }
+  return results.map(quotaBlock).join("\n\n");
+}

package/src/redact.ts

@@ -0,0 +1,41 @@
+/**
+ * Defence in depth for anything this package prints.
+ *
+ * Nothing here is supposed to see a secret: keys come from pi's own auth
+ * resolution and go straight into a header, error bodies are never read, and
+ * raw exception text is dropped rather than shown. This scrubber exists for
+ * the case where one of those is wrong — a key in a message costs the user a
+ * rotation, and the cost of running a regex over a notification is nothing.
+ *
+ * The patterns describe what to REMOVE. They are never used to find or store
+ * a secret. (Idea from imdlan/pi-usage.)
+ */
+
+const REDACTED = "[redacted]";
+
+const RULES: ReadonlyArray<{ re: RegExp; replacement: string }> = [
+  // Provider key shapes, longest-prefix first.
+  { re: /\bsk-or-v1-[A-Za-z0-9]{16,}/g, replacement: REDACTED },
+  { re: /\bsk-ant-[A-Za-z0-9_-]{16,}/g, replacement: REDACTED },
+  { re: /\bsk-[A-Za-z0-9_-]{16,}/g, replacement: REDACTED },
+  { re: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}/g, replacement: REDACTED },
+  { re: /\bAIza[0-9A-Za-z_-]{20,}/g, replacement: REDACTED },
+  { re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g, replacement: REDACTED },
+  { re: /\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g, replacement: REDACTED },
+  // Headers and assignments that name a secret, whatever the value looks like.
+  // To end of line, not to the first space: "Bearer <token>" is two words and
+  // stopping early leaves exactly the half that matters.
+  { re: /\b(?:proxy-)?authorization\s*[:=]\s*[^\r\n;,]+/gi, replacement: `authorization: ${REDACTED}` },
+  {
+    re: /\b(api[_-]?key|access[_-]?token|auth[_-]?token|secret|password)\b\s*[:=]\s*["']?[^\s"',;]+/gi,
+    replacement: `$1=${REDACTED}`,
+  },
+  // A URL's query string can carry a token; the path is enough to identify it.
+  { re: /(https?:\/\/[^\s?]+)\?[^\s]*/gi, replacement: "$1?[redacted]" },
+];
+
+export function redact(text: string): string {
+  let out = text ?? "";
+  for (const { re, replacement } of RULES) out = out.replace(re, replacement);
+  return out;
+}