@goodandready/dsh-key-rotation 0.8.11 → 0.8.12

package/lib/index.js

@@ -53,6 +53,8 @@ import { registerOpsRoutes } from './routes-ops.js';
 import { StatePersistence, resolveStatePath } from './persistence.js';
 import path from 'node:path';
 import { registerPluginUpdater } from './plugin-updater.js'
+import { notifySwitch, notifyExhaustion, pushEvent } from './notify-events.js';
+export { notifySwitch, notifyExhaustion };
 
 /** The llm-pi-ai namespace whose provider profiles map providers to pools. */
 const PIAI_NS = 'llm-pi-ai';
@@ -63,40 +65,12 @@ let rotationDisabled = false;
 // #207/#208 dedupe maps: one notification per key/window per day.
 const expiryNotifiedAt = new Map();
 const budgetNotifiedAt = new Map();
-const switchNotifiedAt = new Map();
 const lowHealthNotifiedAt = new Map();
 const sloNotifiedAt = new Map();
 const DAY_MS = 86400000;
 
 // #216: one webhook per switch, deduped to at most one message per provider
 // per switchNotifyThrottleMs. Extracted for testability.
-export function notifySwitch(runtime, pool, info, hooks = { webhookSender, now: () => Date.now() }) {
-  if (!runtime?.notifyWebhook) return;
-  const throttle = Math.max(0, runtime.switchNotifyThrottleMs ?? 60000);
-  const last = switchNotifiedAt.get(info.provider) ?? 0;
-  const now = hooks.now();
-  if (now - last < throttle) return;
-  switchNotifiedAt.set(info.provider, now);
-  // #263: non-blocking — enqueue never awaits webhook I/O
-  const send = hooks.notifyQueue
-    ? (url, payload) => { hooks.notifyQueue.enqueue(url, payload); return { sent: true, queued: true }; }
-    : (url, payload) => hooks.webhookSender.send(url, payload);
-  send(runtime.notifyWebhook, {
-    title: `Key switched: ${info.provider}`,
-    text: `${info.from} failed (${info.code}) - next key in pool`,
-    provider: info.provider,
-    kind: 'switch',
-    from: info.from,
-    code: info.code,
-    at: info.at,
-  });
-}
-const MAX_EVENTS = 50;
-function pushEvent(pool, ref, reason, cooldownMs, type) {
-  const ev = { at: Date.now(), ref, reason: String(reason ?? 'UNKNOWN'), cooldownMs, type: type ?? 'fail' };
-  pool.state.events.push(ev);
-  if (pool.state.events.length > MAX_EVENTS) pool.state.events.shift();
-}
 
 
 // Fallback classification by failure message. pi-ai surfaces many real quota /
@@ -947,29 +921,4 @@ export function apply(ctx, config = {}) {
 // Notify on exhaustion: webhook notification.
 // Extracted at module scope for testability. No I/O outside the injected hooks.
 // ponytail: thresholds and URLs are runtime-resolved per call, so changing Config is reflected immediately.
-export function notifyExhaustion(runtime, pool, options, hooks = { webhookSender }) {
-  if (!runtime || !pool) return;
-  const count = pool.state ? (pool.state.exhaustionCount ?? 0) : 0;
-  if (count <= 0) return;
-  try {
-    if (runtime.notifyWebhook && count >= (runtime.notifyThreshold ?? 0)) {
-      const token = runtime.webhookActionToken ?? '';
-      const payload = {
-        title: `Key pool exhausted: ${options.provider}`,
-        text: `${count} exhaustion(s); keys: ${(pool.refs ?? []).join(', ')}`,
-        provider: options.provider,
-        exhaustionCount: count,
-        at: pool.state.lastExhaustionAt,
-        keys: pool.refs,
-        actionToken: token || undefined,
-        actions: token ? [
-          { id: `reset-${options.provider}`, label: 'Reset cooldown' },
-          { id: `pause-${options.provider}`, label: 'Pause 1h' },
-        ] : undefined,
-      };
-      if (hooks.notifyQueue) hooks.notifyQueue.enqueue(runtime.notifyWebhook, payload);
-      else hooks.webhookSender.send(runtime.notifyWebhook, payload);
-    }
-  } catch (_) { /* ponytail: never crash rotate() */ }
-}
 

package/lib/notify-events.js

@@ -0,0 +1,64 @@
+// lib/notify-events.js — switch/exhaustion notify helpers and pool event ring (#312).
+// Extracted from index.js for size and testability; behavior unchanged.
+
+import { WebhookSender } from './webhook.js';
+
+const switchNotifiedAt = new Map();
+const MAX_EVENTS = 50;
+// Default sender for callers that omit hooks (matches former index.js module scope).
+const defaultWebhookSender = new WebhookSender({ fetchImpl: globalThis.fetch });
+
+export function notifySwitch(runtime, pool, info, hooks = { webhookSender: defaultWebhookSender, now: () => Date.now() }) {
+  if (!runtime?.notifyWebhook) return;
+  const throttle = Math.max(0, runtime.switchNotifyThrottleMs ?? 60000);
+  const last = switchNotifiedAt.get(info.provider) ?? 0;
+  const now = hooks.now();
+  if (now - last < throttle) return;
+  switchNotifiedAt.set(info.provider, now);
+  // #263: non-blocking — enqueue never awaits webhook I/O
+  const send = hooks.notifyQueue
+    ? (url, payload) => { hooks.notifyQueue.enqueue(url, payload); return { sent: true, queued: true }; }
+    : (url, payload) => hooks.webhookSender.send(url, payload);
+  send(runtime.notifyWebhook, {
+    title: `Key switched: ${info.provider}`,
+    text: `${info.from} failed (${info.code}) - next key in pool`,
+    provider: info.provider,
+    kind: 'switch',
+    from: info.from,
+    code: info.code,
+    at: info.at,
+  });
+}
+
+export function pushEvent(pool, ref, reason, cooldownMs, type) {
+  const ev = { at: Date.now(), ref, reason: String(reason ?? 'UNKNOWN'), cooldownMs, type: type ?? 'fail' };
+  pool.state.events.push(ev);
+  if (pool.state.events.length > MAX_EVENTS) pool.state.events.shift();
+}
+
+export function notifyExhaustion(runtime, pool, options, hooks = { webhookSender: defaultWebhookSender }) {
+  if (!runtime || !pool) return;
+  const count = pool.state ? (pool.state.exhaustionCount ?? 0) : 0;
+  if (count <= 0) return;
+  try {
+    if (runtime.notifyWebhook && count >= (runtime.notifyThreshold ?? 0)) {
+      const token = runtime.webhookActionToken ?? '';
+      const payload = {
+        title: `Key pool exhausted: ${options.provider}`,
+        text: `${count} exhaustion(s); keys: ${(pool.refs ?? []).join(', ')}`,
+        provider: options.provider,
+        exhaustionCount: count,
+        at: pool.state.lastExhaustionAt,
+        keys: pool.refs,
+        actionToken: token || undefined,
+        actions: token ? [
+          { id: `reset-${options.provider}`, label: 'Reset cooldown' },
+          { id: `pause-${options.provider}`, label: 'Pause 1h' },
+        ] : undefined,
+      };
+      if (hooks.notifyQueue) hooks.notifyQueue.enqueue(runtime.notifyWebhook, payload);
+      else hooks.webhookSender.send(runtime.notifyWebhook, payload);
+    }
+  } catch (_) { /* ponytail: never crash rotate() */ }
+}
+

package/lib/ops-keys.js

@@ -0,0 +1,189 @@
+// lib/ops-keys.js — key store + cooldown reset + import routes (#312 split from routes-ops.js).
+import {
+  json,
+  readJson,
+  NS,
+} from './http-bridge.js';
+import {
+  isTrustedBridgeRequest,
+  isValidRef,
+  keyTail,
+} from './pool.js';
+import { looksLikeApiSecret } from './keycheck.js';
+import { bestEffort } from './best-effort.js';
+import {
+  KEY_PATH,
+  RESET_PATH,
+  IMPORT_PATH,
+} from './ops-paths.js';
+
+/**
+ * @param {object} ctx cordis context
+ * @param {object} deps live dependencies from apply()
+ */
+export function registerKeyRoutes(ctx, deps) {
+  const {
+    lastTestCache,
+    poolState,
+    buildRuntime,
+    circuitBreaker,
+  } = deps;
+
+// ── key route: store a key value without leaving the rotation card ──
+//
+// Adding a key used to mean two screens: create the credential elsewhere,
+// then type its env name here. The value is write-only from the browser —
+// it is never sent back, only its last few characters are (see the status
+// route) — and the route is loopback- and same-origin-gated like the config
+// bridge next to it.
+ctx.effect(() => ctx.webServer.register({
+  kind: 'exact',
+  path: KEY_PATH,
+  handler: async (req, res) => {
+    if (req.method !== 'PUT' && req.method !== 'DELETE') {
+      json(res, 405, { error: { code: 'method', message: 'PUT or DELETE only' } });
+      return;
+    }
+    if (!isTrustedBridgeRequest(req)) {
+      json(res, 403, { error: { code: 'forbidden', message: 'dsh-key-rotation: keys are local-only' } });
+      return;
+    }
+    const credentialsService = ctx.get('credentials');
+    if (!credentialsService || typeof credentialsService.set !== 'function') {
+      json(res, 503, { error: { code: 'no-credentials', message: 'dsh-key-rotation: no credentials service is mounted' } });
+      return;
+    }
+    let body;
+    try {
+      body = await readJson(req);
+    } catch (error) {
+      json(res, 400, { error: { code: 'bad-request', message: String(error?.message ?? error) } });
+      return;
+    }
+    const ref = typeof body?.ref === 'string' ? body.ref.trim() : '';
+    if (!isValidRef(ref)) {
+      json(res, 400, { error: { code: 'bad-ref', message: 'dsh-key-rotation: ref must be an environment variable name' } });
+      return;
+    }
+    try {
+      if (req.method === 'DELETE') {
+        await credentialsService.unset(ref);
+        for (const st of poolState.values()) {
+          st.failedUntil?.delete(ref);
+          st.failCounts?.delete(ref);
+          st.authFailCounts?.delete(ref);
+          st.brokenUntil?.delete(ref);
+          if (st.lastUsed === ref) st.lastUsed = undefined;
+        }
+        bestEffort('lastTestCache.delete', () => { lastTestCache?.delete?.(ref); }, ctx.logger);
+        json(res, 200, { ok: true, ref });
+        return;
+      }
+      const value = typeof body?.value === 'string' ? body.value.trim() : '';
+      if (value.length === 0) {
+        json(res, 400, { error: { code: 'empty-value', message: 'dsh-key-rotation: an empty key cannot be stored' } });
+        return;
+      }
+      await credentialsService.set(ref, value);
+      // #200: leak-detector hint - stored value should look like a credential
+      const secretShape = looksLikeApiSecret(value);
+      json(res, 200, { ok: true, ref, tail: keyTail(value), looksLikeSecret: secretShape });
+    } catch (error) {
+      // A ref supplied by the launching environment is read-only, and the
+      // service says so in plain words — pass that through to the card.
+      json(res, 409, { error: { code: 'write-rejected', message: String(error?.message ?? error) } });
+    }
+  },
+}), 'dsh-key-rotation: key route');
+
+
+// ── reset route: clear cooldown for a provider (or a single ref) ──
+ctx.effect(() => ctx.webServer.register({
+  kind: 'exact',
+  path: RESET_PATH,
+  handler: async (req, res) => {
+    if (req.method !== 'POST') {
+      json(res, 405, { error: { code: 'method', message: 'POST only' } });
+      return;
+    }
+    if (!isTrustedBridgeRequest(req)) {
+      json(res, 403, { error: { code: 'forbidden', message: 'dsh-key-rotation: reset is local-only' } });
+      return;
+    }
+    let body;
+    try { body = await readJson(req); } catch (e) {
+      json(res, 400, { error: { code: 'bad-request', message: String(e?.message ?? e) } });
+      return;
+    }
+    const provider = typeof body?.provider === 'string' ? body.provider.trim() : '';
+    const ref = typeof body?.ref === 'string' ? body.ref.trim() : '';
+    if (provider) {
+      const st = poolState.get(provider);
+      if (!st) { json(res, 404, { error: { code: 'not-found', message: `dsh-key-rotation: no pool for '${provider}'` } }); return; }
+      const cleared = st.failedUntil.size;
+      st.failedUntil.clear();
+      st.failCounts?.clear();
+      st.authFailCounts?.clear();
+      st.brokenUntil?.clear();
+      st.switches = 0; st.lastReason = undefined; st.lastSwitchAt = undefined;
+      let circuitReset = false;
+      const br = circuitBreaker ?? buildRuntime().breaker;
+      if (br) {
+        if (typeof br.reset === 'function') { br.reset(provider); circuitReset = true; }
+        else if (typeof br.onSuccess === 'function') { br.onSuccess(provider); circuitReset = true; }
+      }
+      json(res, 200, { ok: true, provider, cleared, circuitReset });
+      return;
+    }
+    if (ref) {
+      let found = false;
+      for (const st of poolState.values()) {
+        if (st.failedUntil?.has(ref) || st.failCounts?.has(ref) || st.authFailCounts?.has(ref) || st.brokenUntil?.has(ref)) {
+          st.failedUntil?.delete(ref);
+          st.failCounts?.delete(ref);
+          st.authFailCounts?.delete(ref);
+          st.brokenUntil?.delete(ref);
+          if (st.lastUsed === ref) st.lastUsed = undefined;
+          found = true; break;
+        }
+      }
+      // idempotent: even if ref was not cooling, report ok if it looks like a valid ref name
+      if (!found && !isValidRef(ref)) { json(res, 400, { error: { code: 'bad-ref', message: 'dsh-key-rotation: ref must be an environment variable name' } }); return; }
+      json(res, 200, { ok: true, ref });
+      return;
+    }
+    json(res, 400, { error: { code: 'bad-request', message: 'dsh-key-rotation: POST requires {"provider": "..."} or {"ref": "..."}' } });
+  },
+}), 'dsh-key-rotation: reset route');
+
+
+ctx.effect(() => ctx.webServer.register({
+  kind: 'exact',
+  path: IMPORT_PATH,
+  handler: async (req, res) => {
+    if (req.method !== 'POST') { json(res, 405, { error: { code: 'method', message: 'POST only' } }); return; }
+    if (!isTrustedBridgeRequest(req)) { json(res, 403, { error: { code: 'forbidden', message: 'dsh-key-rotation: import is local-only' } }); return; }
+    let body; try { body = await readJson(req); } catch (e) { json(res, 400, { error: { code: 'bad-request', message: String(e?.message ?? e) } }); return; }
+    const url = typeof body?.url === 'string' ? body.url.trim() : '';
+    if (!url || !url.startsWith('https://')) { json(res, 400, { error: { code: 'bad-url', message: 'dsh-key-rotation: only HTTPS URLs are allowed' } }); return; }
+    try {
+      const resp = await fetch(url);
+      if (!resp.ok) { json(res, 400, { error: { code: 'fetch-failed', message: 'dsh-key-rotation: fetch returned ' + resp.status } }); return; }
+      const data = await resp.json();
+      if (!Array.isArray(data)) { json(res, 400, { error: { code: 'bad-format', message: 'dsh-key-rotation: expected JSON array of providers' } }); return; }
+      const settings = ctx.get('settings');
+      if (!settings) { json(res, 503, { error: { code: 'settings-rejected', message: 'dsh-key-rotation: no settings provider' } }); return; }
+      const desc = settings.describe({ redactSecrets: true }).find((c) => c.ns === NS);
+      const cur = desc?.value?.providers ?? [];
+      const merged = new Map();
+      for (const p of cur) if (p && p.provider) merged.set(p.provider, p);
+      for (const p of data) if (p && p.provider && typeof p.provider === 'string') merged.set(p.provider, p);
+      const mergedArr = [...merged.values()];
+      await settings.replace(NS, { ...(desc?.value ?? {}), providers: mergedArr }, desc?.revision);
+      json(res, 200, { ok: true, providersImported: data.length, total: mergedArr.length });
+    } catch (e) { json(res, 400, { error: { code: 'import-failed', message: String(e?.message ?? e) } }); }
+  },
+}), 'dsh-key-rotation: import route');
+
+// Health for external panels (Beszel/Uptime)
+}

package/lib/ops-paths.js

@@ -0,0 +1,11 @@
+// lib/ops-paths.js — shared HTTP path constants for operational routes (#312).
+export const STATUS_PATH = '/dsh-key-rotation/status';
+export const SNAPSHOT_PATH = '/dsh-key-rotation/snapshot';
+export const KEY_PATH = '/dsh-key-rotation/key';
+export const RESET_PATH = '/dsh-key-rotation/reset';
+export const IMPORT_PATH = '/dsh-key-rotation/import';
+export const HEALTH_PATH = '/dsh-key-rotation/health';
+export const USAGE_PATH = '/dsh-key-rotation/usage';
+export const TEST_PATH = '/dsh-key-rotation/test';
+export const SANDBOX_CACHE_PATH = '/dsh-key-rotation/sandbox-cache';
+export const WEBHOOK_ACTION_PATH = '/dsh-key-rotation/webhook-action';

package/lib/ops-status.js

@@ -0,0 +1,202 @@
+// lib/ops-status.js — status + health operational routes (#312 split from routes-ops.js).
+import { json } from './http-bridge.js';
+import {
+  isTrustedBridgeRequest,
+  keyTail,
+  envValue,
+  computeHealthScore,
+  costForDay,
+  costForWeek,
+  isLoopbackAddress,
+} from './pool.js';
+import { bucketInfo } from './bucket.js';
+import { sanitizeSnapshot } from './sanitize-snapshot.js';
+import {
+  STATUS_PATH,
+  HEALTH_PATH,
+} from './ops-paths.js';
+
+/**
+ * @param {object} ctx cordis context
+ * @param {object} deps live dependencies from apply()
+ */
+export function registerStatusRoutes(ctx, deps) {
+  const {
+    buildRuntime,
+    latencyHistogram,
+    circuitBreaker,
+    quotaStore,
+  } = deps;
+
+// ── status route: what the settings card cannot know on its own ──
+//
+// Reports, per configured provider, which key is in use, which are cooling
+// down and until when, whether an env name resolves to a credential at all
+// (a typo is otherwise silent), and how often rotation has fired.
+//
+// Key VALUES never leave the host — only the boolean fact that one exists.
+ctx.effect(() => ctx.webServer.register({
+  kind: 'exact',
+  path: STATUS_PATH,
+  handler: async (req, res) => {
+    if (req.method !== 'GET') {
+      json(res, 405, { error: { code: 'method', message: 'GET only' } });
+      return;
+    }
+    if (!isTrustedBridgeRequest(req)) {
+      json(res, 403, { error: { code: 'forbidden', message: 'dsh-key-rotation: status is local-only' } });
+      return;
+    }
+    const runtime = buildRuntime();
+    const { poolByRef, providerTags, providerBudgets, latencySloMs } = runtime;
+    const base = ctx.get('credentials');
+    const now = Date.now();
+    const seen = new Set();
+    const providers = [];
+    for (const pool of poolByRef.values()) {
+      if (seen.has(pool.base)) continue;
+      seen.add(pool.base);
+      try {
+      const keys = [];
+      for (const ref of pool.refs) {
+        let present = false;
+        let tail = '';
+        let source = null;
+        let writable = true;
+        try {
+          // The resolve patch is installed on this same service, so ask for
+          // the exact ref: a pool ref would otherwise round-robin to another
+          // key and report a missing name as present.
+          let hit = await (base?.__dshKeyRotationOriginalResolve ?? base?.resolve)?.call(base, ref);
+          present = Boolean(hit && typeof hit.value === 'string' && hit.value.length > 0);
+          if (present) tail = keyTail(hit.value);
+          // fallback: env var bootstrapping (issue #7)
+          if (!present) {
+            const ev = envValue(ref);
+            if (ev !== undefined) { present = true; tail = keyTail(ev); source = 'env'; writable = false; }
+          }
+        } catch {
+          present = false;
+        }
+        try {
+          const described = await base?.describe?.(ref);
+          source = described?.source ?? null;
+          writable = described?.writable !== false;
+        } catch {
+          /* describe is optional — the card falls back to editable */
+        }
+        const until = pool.state.failedUntil.get(ref);
+        keys.push({
+          ref,
+          present,
+          tail,
+          source,
+          writable,
+          active: pool.state.lastUsed === ref,
+          cooldownMsLeft: until !== undefined && until > now ? until - now : 0,
+          // #210: RPM capacity snapshot (null when rpmLimit is off)
+          rpm: bucketInfo(pool.state.rpmWindows, ref, pool.rpmLimit, now),
+          // #215: effective round-robin weight of this key
+          weight: pool.weights?.[pool.refs.indexOf(ref)] ?? 1,
+          usage: pool.state.usageCounts?.get(ref) ?? 0,
+          byModel: pool.state.byModel?.get(ref) ? Object.fromEntries(pool.state.byModel.get(ref)) : {},
+          usageDays: pool.state.usageDays?.get(ref) ? Object.fromEntries(pool.state.usageDays.get(ref)) : {},
+          cost: pool.state.costPerKey?.get(ref) ?? 0,
+          lastUsedAt: pool.state.lastUsedAt?.get(ref) ?? null,
+          expiresAt: pool.expiresAt?.[ref] ?? null,
+          expired: pool.expiresAt?.[ref] !== undefined && now >= pool.expiresAt[ref],
+          broken: pool.state.brokenUntil?.has(ref) ?? false,
+        });
+      }
+      providers.push({
+        provider: pool.base,
+        keys,
+        tags: providerTags.get(pool.base) ?? [],
+        // #260 circuit breaker state (may be null if not yet tripped)
+        circuit: (() => {
+          const br = runtime.breaker;
+          if (!br) return null;
+          const st = br.state(pool.base);
+          return { state: st, threshold: br.threshold, openMs: br.openMs };
+        })(),
+        switches: pool.state.switches ?? 0,
+        lastReason: pool.state.lastReason ?? null,
+        lastSwitchAt: pool.state.lastSwitchAt ?? null,
+        lastExhaustionAt: pool.state.lastExhaustionAt ?? null,
+        exhaustionCount: pool.state.exhaustionCount ?? 0,
+        totalUsage: (() => { let s = 0; if (pool.state.usageCounts) for (const v of pool.state.usageCounts.values()) s += v; return s; })(),
+        // #225: aggregate p95 across the pool's keys
+        p95: (() => {
+          const vals = (pool.refs ?? []).map((r) => (typeof latencyHistogram?.snapshot === 'function' ? latencyHistogram.snapshot(r) : null)).filter((s) => s && s.p95 != null).map((s) => s.p95);
+          return vals.length ? Math.round(Math.max(...vals)) : null;
+        })(),
+        latencySloMs,
+        events: (pool.state.events ?? []).slice(-50),
+        healthScore: computeHealthScore(pool.state),
+        // #208: today/week spend + configured budget for the card
+        todayCost: costForDay(pool.state.costDays),
+        weeklyCost: costForWeek(pool.state.costDays, now),
+        budgetDaily: (providerBudgets?.get ? providerBudgets.get(pool.base) : providerBudgets?.[pool.base])?.costBudgetDaily ?? 0,
+        budgetWeekly: (providerBudgets?.get ? providerBudgets.get(pool.base) : providerBudgets?.[pool.base])?.costBudgetWeekly ?? 0,
+        pauseOnBudget: (providerBudgets?.get ? providerBudgets.get(pool.base) : providerBudgets?.[pool.base])?.pauseOnBudget ?? false,
+        routingStrategy: pool.routingStrategy ?? runtime.routingStrategy ?? 'round-robin',
+        proactiveRateLimitGuard: pool.proactiveRateLimitGuard ?? runtime.proactiveRateLimitGuard ?? true,
+      });
+      } catch (e) {
+        console.warn(`[dsh-key-rotation] status: pool ${pool.base} failed: ${String(e?.message ?? e)} ${e?.stack ?? ''}`);
+        providers.push({ provider: pool.base, keys: [], statusError: String(e?.message ?? e) });
+      }
+    }
+    json(res, 200, sanitizeSnapshot({
+      providers,
+      // #266/#263 operational extras (additive)
+      meta: {
+        expectedClones: [...(runtime.expectedClones ?? [])],
+        notifyQueue: runtime.notifyQueue?.stats?.() ?? null,
+        breakerEnabled: runtime.circuitBreakerEnabled !== false,
+        at: now,
+      },
+    }, now));
+  },
+}), 'dsh-key-rotation: status route');
+
+// #209: usage report - per-key requests/cost over the last N days.
+// ?format=csv returns text/csv; ?days=N window (1..90, default 7).
+
+ctx.effect(() => ctx.webServer.register({
+  kind: 'exact',
+  path: HEALTH_PATH,
+  handler: async (req, res) => {
+    if (!isTrustedBridgeRequest(req) && req.socket?.remoteAddress !== '127.0.0.1' && req.socket?.remoteAddress !== '::1') { } // allow same-origin already checked
+    if (!isTrustedBridgeRequest(req)) {
+      // also allow plain loopback without Origin
+      if (!isLoopbackAddress(req.socket?.remoteAddress)) { res.writeHead(403); res.end(); return; }
+      if (req.headers['sec-fetch-site'] === 'cross-site') { res.writeHead(403); res.end(); return; }
+    }
+    if (req.method !== 'GET') { json(res, 405, { error: { code: 'method', message: 'GET only' } }); return; }
+    const now = Date.now();
+    const pools = {};
+    let exhaustedAny = false;
+    const { poolByRef: pr, providerTags } = buildRuntime();
+    const seenH = new Set();
+    for (const pool of pr.values()) {
+      if (seenH.has(pool.base)) continue;
+      seenH.add(pool.base);
+      let healthy = 0;
+      for (const ref of pool.refs) {
+        const until = pool.state.failedUntil.get(ref);
+        if (until !== undefined && until > now) continue;
+        const exp = pool.expiresAt?.[ref];
+        if (exp !== undefined && now >= exp) continue;
+        healthy++;
+      }
+      const total = pool.refs.length;
+      const exhausted = healthy === 0 && total > 0;
+      if (exhausted) exhaustedAny = true;
+      pools[pool.base] = { healthy, total, exhausted, healthScore: computeHealthScore(pool.state) };
+    }
+    json(res, 200, { status: exhaustedAny ? 'degraded' : 'ok', pools, exhaustedAny, latency: latencyHistogram.snapshotAll(), quota: typeof quotaStore?.snapshot === 'function' ? quotaStore.snapshot() : null });
+  },
+}), 'dsh-key-rotation: health');
+
+}

package/lib/ops-telemetry.js

@@ -0,0 +1,113 @@
+// lib/ops-telemetry.js — usage + snapshot operational routes (#312 split from routes-ops.js).
+import {
+  json,
+  readJson,
+  descriptorOf,
+  NS,
+} from './http-bridge.js';
+import { isTrustedBridgeRequest } from './pool.js';
+import {
+  usageRows,
+  usageCsv,
+} from './usage-report.js';
+import {
+  USAGE_PATH,
+  SNAPSHOT_PATH,
+} from './ops-paths.js';
+import { findSecrets } from './keycheck.js';
+
+/**
+ * @param {object} ctx cordis context
+ * @param {object} deps live dependencies from apply()
+ */
+export function registerTelemetryRoutes(ctx, deps) {
+  const {
+    buildRuntime,
+  } = deps;
+
+ctx.effect(() => ctx.webServer.register({
+  kind: 'exact',
+  path: USAGE_PATH,
+  handler: (req, res) => {
+    if (req.method !== 'GET') { json(res, 405, { error: { code: 'method', message: 'GET only' } }); return; }
+    if (!isTrustedBridgeRequest(req)) { json(res, 403, { error: { code: 'forbidden', message: 'dsh-key-rotation: usage is local-only' } }); return; }
+    const url = new URL(req.url ?? USAGE_PATH, 'http://localhost');
+    const days = Math.min(90, Math.max(1, Number(url.searchParams.get('days')) || 7));
+    const csv = url.searchParams.get('format') === 'csv';
+    const provider = url.searchParams.get('provider') ?? '';
+    const runtime = buildRuntime();
+    const now = Date.now();
+    const seen = new Set();
+    const report = [];
+    for (const pool of runtime.poolByRef.values()) {
+      if (seen.has(pool.base)) continue;
+      seen.add(pool.base);
+      if (provider && pool.base !== provider) continue;
+      report.push({ provider: pool.base, rows: usageRows(pool, days, now) });
+    }
+    if (csv) {
+      res.writeHead(200, { 'content-type': 'text/csv; charset=utf-8', 'content-disposition': 'attachment; filename="dsh-key-rotation-usage.csv"' });
+      const parts = [];
+      for (const p of report) {
+        if (parts.length > 0) parts.push('');
+        parts.push('# ' + p.provider);
+        parts.push(usageCsv(p.rows));
+      }
+      res.end(parts.join('\n') + '\n');
+      return;
+    }
+    json(res, 200, { at: now, days, providers: report });
+  },
+}), 'dsh-key-rotation: usage route');
+
+// #218: full config snapshot - one JSON file to move between machines.
+// Secret values never travel: only credential/env names. Token fields are
+// exported as empty strings; on import they keep existing values when empty.
+
+ctx.effect(() => ctx.webServer.register({
+  kind: 'exact',
+  path: SNAPSHOT_PATH,
+  handler: async (req, res) => {
+    if (req.method !== 'GET' && req.method !== 'POST') { json(res, 405, { error: { code: 'method', message: 'GET (export) or POST (import) only' } }); return; }
+    if (!isTrustedBridgeRequest(req)) { json(res, 403, { error: { code: 'forbidden', message: 'dsh-key-rotation: snapshot is local-only' } }); return; }
+    if (req.method === 'GET') {
+      const descriptor = descriptorOf(ctx, NS);
+      const value = descriptor?.value ?? {};
+      const exportable = { ...value };
+      // token-shaped fields stay empty in the file; refs are names, not secrets
+      exportable.webhookActionToken = '';
+      json(res, 200, { at: Date.now(), version: 1, snapshot: exportable });
+      return;
+    }
+    // POST = import: { snapshot } -> merge with current section, PUT semantics
+    let body;
+    try { body = await readJson(req); } catch (e) { json(res, 400, { error: { code: 'bad-request', message: String(e?.message ?? e) } }); return; }
+    const snap = body?.snapshot;
+    if (!snap || typeof snap !== 'object' || Array.isArray(snap)) { json(res, 400, { error: { code: 'bad-format', message: 'dsh-key-rotation: POST requires {"snapshot": {...}}' } }); return; }
+    // #200 leak guard applies to imported content too
+    try {
+      const masked = structuredClone(snap);
+      if (masked.webhookActionToken) masked.webhookActionToken = '***';
+      if (masked.notifyWebhook) masked.notifyWebhook = '***';
+      const findings = findSecrets(JSON.stringify(masked));
+      if (findings.length > 0) { json(res, 400, { error: { code: 'secret-in-snapshot', message: 'dsh-key-rotation: snapshot carries a live-looking credential', findings } }); return; }
+    } catch { /* scanning must never block a valid import */ }
+    const settings = ctx.get('settings');
+    if (!settings) { json(res, 503, { error: { code: 'settings-rejected', message: 'dsh-key-rotation: no settings provider' } }); return; }
+    const desc = descriptorOf(ctx, NS);
+    if (desc === void 0) { json(res, 500, { error: { code: 'settings-rejected', message: 'dsh-key-rotation: namespace missing' } }); return; }
+    const cur = desc.value ?? {};
+    // empty token fields in the file keep the current values (never wipe a secret)
+    const merged = { ...cur, ...snap };
+    if (!snap.webhookActionToken) merged.webhookActionToken = cur.webhookActionToken ?? '';
+    try {
+      await settings.replace(NS, merged, desc.revision);
+      const after = descriptorOf(ctx, NS);
+      json(res, 200, { ok: true, revision: after?.revision });
+    } catch (e) {
+      json(res, e?.code === 'SETTINGS_CONFLICT' ? 409 : 400, { error: { code: 'settings-rejected', message: String(e?.message ?? e) } });
+    }
+  },
+}), 'dsh-key-rotation: snapshot route');
+
+}