@goodandready/dsh-key-rotation 0.8.11 → 0.8.13

package/lib/lifecycle.js

@@ -0,0 +1,122 @@
+// lib/lifecycle.js — background timers and lifecycle effects
+import { healIdleCooldowns, autoUnbreakBrokenKeys } from './heal.js';
+import { StatePersistence, resolveStatePath } from './persistence.js';
+import path from 'node:path';
+
+export function setupIdleHealEffect(ctx, getConfig, buildRuntime) {
+  return ctx.effect(() => {
+    const cfg = getConfig();
+    if (!cfg || cfg.selfHealCooldown === false) return () => {};
+    const timer = setInterval(() => {
+      try {
+        const c = getConfig();
+        if (!c || c.selfHealCooldown === false) return;
+        const idle = Number.isFinite(c.selfHealIdleMs) && c.selfHealIdleMs > 0 ? c.selfHealIdleMs : 3600000;
+        const providers = Array.isArray(c.providers) ? c.providers : [];
+        const pools = providers
+          .map((p) => buildRuntime().providerToPool.get(p.provider))
+          .filter(Boolean);
+        healIdleCooldowns(pools, idle);
+      } catch (_) { /* ponytail: never crash the timer */ }
+    }, 60000);
+    if (typeof timer.unref === 'function') timer.unref();
+    return () => clearInterval(timer);
+  }, 'dsh-key-rotation: self-healing idle');
+}
+
+export function setupAutoUnbreakEffect(ctx, getConfig, buildRuntime, ensureSandboxRunner, logger) {
+  return ctx.effect(() => {
+    const cfg = getConfig();
+    const intervalMin = cfg?.selfHealingIntervalMinutes ?? 30;
+    if (!intervalMin || intervalMin <= 0) return () => {};
+    const intervalMs = intervalMin * 60 * 1000;
+    const timer = setInterval(async () => {
+      try {
+        const c = getConfig();
+        if (!c || !c.selfHealingIntervalMinutes || c.selfHealingIntervalMinutes <= 0) return;
+        const { pools } = buildRuntime();
+        const runner = ensureSandboxRunner(ctx);
+        await autoUnbreakBrokenKeys(pools, async (ref) => {
+          let val = (await ctx.credentials?.resolve?.(ref))?.value;
+          if (!val) return { ok: false };
+          return runner.probeModels(ref, val);
+        });
+      } catch (e) { logger?.warn?.('[dsh-key-rotation] auto-unbreak failed', e); }
+    }, intervalMs);
+    if (typeof timer.unref === 'function') timer.unref();
+    return () => clearInterval(timer);
+  }, 'dsh-key-rotation: auto-unbreak');
+}
+
+export function setupPersistence(ctx, { cfg0, poolState, moduleBreaker, verboseLoggingOn, logger }) {
+  let statePersistence = null;
+  try {
+    const hostDirs = [
+      process.env.DSH_HOME,
+      process.cwd(),
+    ].filter((d) => typeof d === 'string' && d.length > 0);
+    const resolvedPath = resolveStatePath({
+      configuredPath: cfg0.persistencePath,
+      dataDir: hostDirs[0],
+    });
+    if (cfg0.persistenceEnabled !== false && resolvedPath) {
+      statePersistence = new StatePersistence({ filePath: resolvedPath });
+      statePersistence.load().then((snap) => {
+        if (!snap) return;
+        try {
+          StatePersistence.restorePools(poolState, snap);
+          if (moduleBreaker && snap.circuit) moduleBreaker.restore(snap.circuit);
+          if (verboseLoggingOn?.()) {
+            logger?.warn?.(`[dsh-key-rotation] restored ${Object.keys(snap.pools ?? {}).length} pool state(s) from ${path.basename(resolvedPath)}`);
+          }
+        } catch (e) {
+          logger?.warn?.('[dsh-key-rotation] persistence restore failed', e?.message ?? e);
+        }
+      }).catch(() => {});
+    } else if (cfg0.persistenceEnabled !== false && !resolvedPath) {
+      logger?.warn?.('[dsh-key-rotation] persistence disabled: no data directory');
+    }
+  } catch (e) {
+    logger?.warn?.('[dsh-key-rotation] persistence init failed', e?.message ?? e);
+  }
+
+  function persistenceSnapshot() {
+    if (!statePersistence) return null;
+    return StatePersistence.serialize({
+      poolState,
+      circuitSnapshot: moduleBreaker ? moduleBreaker.snapshot() : {},
+      quotaSnapshot: {},
+    });
+  }
+
+  function schedulePersist() {
+    if (!statePersistence) return;
+    const snap = persistenceSnapshot();
+    if (snap) statePersistence.save(snap);
+  }
+
+  ctx.effect(() => {
+    const timer = setInterval(() => {
+      try { schedulePersist(); }
+      catch (e) { logger?.warn?.('[dsh-key-rotation] periodic persist failed', e); }
+    }, 15000);
+    if (typeof timer.unref === 'function') timer.unref();
+    return () => {
+      clearInterval(timer);
+      try {
+        if (statePersistence) {
+          const snap = persistenceSnapshot();
+          if (snap) {
+            statePersistence.save(snap);
+            void statePersistence.flush();
+          }
+          statePersistence.dispose();
+        }
+      } catch (e) {
+        logger?.warn?.('[dsh-key-rotation] dispose persist failed', e);
+      }
+    };
+  }, 'dsh-key-rotation: state persistence');
+
+  return { schedulePersist, persistenceSnapshot };
+}

package/lib/logger.js

@@ -0,0 +1,13 @@
+// lib/logger.js — safe Cordis logger wrapper
+const noop = () => {};
+const noopLogger = { warn: noop, info: noop, error: noop, debug: noop, log: noop };
+
+export function getLogger(ctx, scope = 'dsh-key-rotation') {
+  if (typeof ctx?.logger === 'function') {
+    return ctx.logger(scope);
+  }
+  if (ctx?.logger && typeof ctx.logger.warn === 'function') {
+    return ctx.logger;
+  }
+  return noopLogger;
+}

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) {
+        (ctx?.logger ? ctx.logger('dsh-key-rotation') : null)?.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');
+
+}