@goodandready/dsh-key-rotation 0.7.26 → 0.7.28

package/lib/keycheck.js

@@ -0,0 +1,31 @@
+// lib/keycheck.js - token leak detector (#200).
+// Recognizes live API-key shapes so a real secret pasted into a wrong field
+// (webhook URL, provider name, ...) is caught before it leaves the machine.
+const PATTERNS = [
+  { type: 'anthropic', re: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/ },
+  { type: 'openai', re: /\bsk-(?!ant-)[A-Za-z0-9_-]{20,}\b/ },
+  { type: 'google', re: /\bAIza[0-9A-Za-z_-]{30,}\b/ },
+  { type: 'github', re: /\bgh[pousr]_[A-Za-z0-9]{30,}\b/ },
+  { type: 'aws', re: /\bAKIA[0-9A-Z]{16}\b/ },
+  { type: 'slack', re: /\bxox[bpars]-[A-Za-z0-9-]{10,}\b/ },
+  { type: 'telegram', re: /\b\d{8,10}:AA[A-Za-z0-9_-]{30,}\b/ },
+  { type: 'stripe', re: /\b(sk|pk)_(live|test)_[A-Za-z0-9]{20,}\b/ },
+  { type: 'private-key', re: /-----BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY-----/ },
+];
+
+/** All secrets found in `text`: [{ type, index, preview }]. Preview = first 8 chars only. */
+export function findSecrets(text) {
+  const out = [];
+  const s = String(text ?? '');
+  for (const { type, re } of PATTERNS) {
+    for (const m of s.matchAll(new RegExp(re.source, 'g'))) {
+      out.push({ type, index: m.index, preview: m[0].slice(0, 8) + '…' });
+    }
+  }
+  return out;
+}
+
+/** True when the value itself looks like a live credential (for PUT /key sanity hint). */
+export function looksLikeApiSecret(value) {
+  return findSecrets(value).length > 0;
+}

package/lib/maintenance.js

@@ -0,0 +1,64 @@
+// lib/maintenance.js - pure helpers for #207 (expiry pre-warning) and
+// #208 (cost budget). No I/O; the timers in index.js call these and decide
+// whether to send webhooks.
+
+const DAY_MS = 86400000;
+
+/**
+ * #207: keys of `pool` whose expiresAt falls within the next `warnDays`.
+ * Returns [{ ref, expiresInDays, expiresAt }], soonest first.
+ */
+export function expiringSoon(pool, warnDays, now = Date.now()) {
+  if (!pool || !pool.expiresAt) return [];
+  const horizon = now + Math.max(1, warnDays ?? 7) * DAY_MS;
+  return Object.entries(pool.expiresAt)
+    .filter(([, at]) => at > now && at <= horizon)
+    .map(([ref, at]) => ({ ref, expiresAt: at, expiresInDays: Math.max(0, Math.floor((at - now) / DAY_MS)) }))
+    .sort((a, b) => a.expiresAt - b.expiresAt);
+}
+
+/** #207 dedupe: true when a day-level notification for `key` is due. */
+export function shouldNotifyDaily(lastNotified, key, now = Date.now()) {
+  if (!lastNotified.has(key)) {
+    lastNotified.set(key, now);
+    return true;
+  }
+  const last = lastNotified.get(key);
+  if (now - last < DAY_MS) return false;
+  lastNotified.set(key, now);
+  return true;
+}
+
+/**
+ * #208: total spend of a pool on ISO day `day` (defaults to today)
+ * across costDays Map<ref, Map<day, cost>>.
+ */
+export function costForDay(costDays, day) {
+  const d = day ?? new Date().toISOString().slice(0, 10);
+  let total = 0;
+  for (const perRef of (costDays?.values() ?? [])) {
+    total += perRef.get(d) ?? 0;
+  }
+  return total;
+}
+
+/** #208: total spend over the last 7 ISO days ending today. */
+export function costForWeek(costDays, now = Date.now()) {
+  let total = 0;
+  for (let i = 0; i < 7; i++) {
+    const d = new Date(now - i * 86400000).toISOString().slice(0, 10);
+    total += costForDay(costDays, d);
+  }
+  return total;
+}
+
+/**
+ * #208 budget verdict for a pool: { spend, budget, ratio, warn, exceeded }.
+ * budget <= 0 -> never warn.
+ */
+export function budgetVerdict(spend, budget) {
+  if (!budget || budget <= 0) return { spend, budget: 0, ratio: 0, warn: false, exceeded: false };
+  const ratio = spend / budget;
+  // warn from 80%, exceeded at 100%
+  return { spend, budget, ratio, warn: ratio >= 0.8, exceeded: ratio >= 1 };
+}

package/lib/pool.js

@@ -1,227 +1,237 @@
-// Pure helpers for the key-rotation plugin. Kept free of DSH runtime
-// dependencies so they can be unit-tested under `node --test` without
-// `@deepseek-ai/cordis` / `@deepseek-ai/schemastery` being installed.
-// Anything that talks to `ctx` stays in lib/index.js.
-
-/** Number of trailing characters of a key shown in the UI for disambiguation. */
-export const KEY_TAIL_CHARS = 5;
-
-/** Returns the last KEY_TAIL_CHARS characters of a key, or the whole key if shorter. */
-export function keyTail(value) {
-  if (typeof value !== 'string' || value.length === 0) return '';
-  return value.length <= KEY_TAIL_CHARS ? value : value.slice(-KEY_TAIL_CHARS);
-}
-
-/** True if a socket remoteAddress is a loopback (v4 / v6). */
-export function isLoopbackAddress(address) {
-  if (address === undefined || address === null) return false;
-  if (address === '127.0.0.1' || address === '::1') return true;
-  if (typeof address === 'string' && address.startsWith('::ffff:')) {
-    return address.slice(7) === '127.0.0.1';
-  }
-  return false;
-}
-
-/** True if a request is both loopback and same-origin (sec-fetch-site guard). */
-export function isTrustedBridgeRequest(request) {
-  if (!isLoopbackAddress(request?.socket?.remoteAddress)) return false;
-  if (request?.headers?.['sec-fetch-site'] === 'cross-site') return false;
-  const origin = request?.headers?.origin;
-  if (origin === undefined) return true; // no Origin header (loopback tool) is allowed
-  try {
-    const host = request?.headers?.host;
-    if (host === undefined) return false;
-    return new URL(origin).host === host;
-  } catch {
-    return false;
-  }
-}
-
-/** Compiled once at module load. Matches error messages that should rotate the key
- *  even when the structured failure code is not in `switchCodes`.
- *  Mirrors SWITCHABLE_MESSAGE_PATTERN in lib/index.js exactly. */
-export const SWITCHABLE_MESSAGE_PATTERN = new RegExp([
-  /\b(?:quota|usage[\s_-]+limit|rate[\s_-]?limit)\b/i,
-  /\binsufficient[\s_-]+(?:quota|balance|credits?)\b/i,
-  /\bout[\s_-]+of[\s_-]+(?:credits?|budget)\b/i,
-  /\b(?:exceeded|exhausted)[\s_-]+(?:quota|limit|budget)\b/i,
-  /\bbilling\b/i,
-  /\b429\b|\b5\d\d\b/i,
-  /\btime(?:d)?\s*out\b|timeout/i,
-  /\b(?:network|connection|socket|fetch|ECONN[A-Z]+)\b/i,
-  /\bother side closed|premature close|stream ended (?:before|without)\b/i,
-  /\b401\b|\b403\b/i,
-  /\b(?:invalid|expired|revoked|unauthorized)[\s_-]+(?:api[\s_-]?key|token)\b/i,
-  /\bapi[\s_-]?key[\s_-]+(?:is[\s_-]+)?(?:invalid|expired|revoked|unauthorized)\b/i,
-  /\b(?:authentication|unauthorized|not[\s_-]+authorized)\b/i,
-].map((r) => r.source).join('|'), 'i');
-
-/** Default switch codes used by lib/index.js. Kept here so tests assert against
- *  the same list the runtime ships. */
-export const DEFAULT_SWITCH_CODES = [
-  'QUOTA', 'RATE_LIMIT', 'SERVER', 'TIMEOUT', 'TRANSPORT',
-  'EMPTY_RESPONSE', 'UNKNOWN_MODEL', 'AUTH',
-];
-
-/** Ref name validator. Same rule lib/index.js enforces in PUT/DELETE /key. */
-const REF_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
-export function isValidRef(ref) {
-  return typeof ref === 'string' && REF_RE.test(ref);
-}
-
-/**
- * Pick the next healthy ref in a round-robin pool.
- *
- * @param {{ refs: string[], state: { failedUntil: Map<string, number>, pointer: number } }} pool
- * @param {number} now - epoch milliseconds (injectable for tests)
- * @param {number} refsCount - for tests: number of refs to consider (defaults to pool.refs.length)
- * @returns {string|undefined} the ref to use, or undefined if pool has no refs
- *
- * Mirrors the inline logic in the credentials.resolve patch in lib/index.js.
- * Exported here for unit tests; not used at runtime to avoid duplicating logic.
- */
-export function pickNext(pool, now, refsCount = pool.refs.length) {
-  if (refsCount === 0) return undefined;
-  const start = pool.state.pointer ?? 0;
-  for (let i = 0; i < refsCount; i++) {
-    const index = (start + i) % refsCount;
-    const candidate = pool.refs[index];
-    const until = pool.state.failedUntil.get(candidate);
-    if (until !== undefined && until > now) continue;
-    return candidate;
-  }
-  return undefined; // all cooled
-}
-
-/** Apply a failed-key cooldown to pool state. Pure: returns next state shape,
- *  does not mutate input. Runtime in lib/index.js mutates in place; tests use
- *  this helper to construct expected snapshots. */
-export function applyCooldown(pool, ref, cooldownMs, now = Date.now()) {
-  return {
-    ...pool,
-    state: {
-      ...pool.state,
-      failedUntil: new Map(pool.state.failedUntil).set(ref, now + cooldownMs),
-    },
-  };
-}
-
-/** Exponential backoff for a repeatedly failing key.
- *  failCount 1 => baseMs, 2 => baseMs*2, 3 => baseMs*4, capped at baseMs*8 (or maxMs).
- *  Pure and easily unit-tested. */
-export function computeBackoff(baseMs, failCount, maxMs) {
-  const cap = maxMs ?? baseMs * 8;
-  if (failCount <= 1) return Math.min(baseMs, cap);
-  const backoff = baseMs * (1 << (failCount - 1)); // 2^(n-1)
-  return Math.min(backoff, cap);
-}
-
-/** Record a failure for `ref` in `pool.state`, applying exponential backoff.
- *  Mutates pool.state.failedUntil and pool.state.failCounts. Returns the backoff used. */
-export function recordFailure(pool, ref, now, baseMs, maxMs) {
-  if (!pool.state.failCounts) pool.state.failCounts = new Map();
-  const prev = pool.state.failCounts.get(ref) ?? 0;
-  const next = prev + 1;
-  pool.state.failCounts.set(ref, next);
-  const backoff = computeBackoff(baseMs, next, maxMs);
-  pool.state.failedUntil.set(ref, now + backoff);
-  return backoff;
-}
-
-/** Record a success for `ref` — clears its cooldown and resets its fail count. */
-export function recordSuccess(pool, ref) {
-  if (pool.state.failCounts) pool.state.failCounts.delete(ref);
-  pool.state.failedUntil.delete(ref);
-}
-
-/** Return env value for ref if present in process.env, else undefined. */
-export function envValue(ref) {
-  const v = typeof process !== 'undefined' ? process.env?.[ref] : undefined;
-  return typeof v === 'string' && v.length > 0 ? v : undefined;
-}
-
-/** Sweep expired cooldown entries from poolState. Returns count of cleared refs. */
-export function sweepExpired(poolState, now = Date.now()) {
-  let cleared = 0;
-  for (const st of poolState.values()) {
-    for (const [ref, until] of [...st.failedUntil.entries()]) {
-      if (until <= now) {
-        st.failedUntil.delete(ref);
-        st.failCounts?.delete(ref);
-        cleared++;
-      }
-    }
-  }
-  return cleared;
-}
-
-/** Parse Retry-After value from a header string or message.
- *  Supports seconds ("60", "Retry-After: 60") and HTTP-date ("Wed, 21 Oct 2026 07:28:00 GMT").
- *  Returns milliseconds or undefined if not parseable. */
-export function parseRetryAfter(value) {
-  if (typeof value !== 'string' || !value) return undefined;
-  // Try to extract "Retry-After: <val>" from a larger message
-  const m = value.match(/retry-after\s*[:=]\s*(.+)/i);
-  const raw = m ? m[1].trim().split(/[\n\r;]/)[0].trim() : value.trim();
-  // Seconds
-  if (/^\d+$/.test(raw)) {
-    const sec = Number(raw);
-    if (sec >= 0 && sec <= 86400 * 7) return sec * 1000;
-  }
-  // HTTP-date
-  const ts = Date.parse(raw);
-  if (!Number.isNaN(ts)) {
-    const diff = ts - Date.now();
-    if (diff > 0 && diff < 86400 * 7 * 1000) return diff;
-  }
-  return undefined;
-}
-
-/** Pick a key pool for a (provider, model) pair. Model sub-pools win over the
- *  provider base pool; falls back to the base pool when no sub-pool matches. */
-export function selectPool(modelPoolByProvider, providerToPool, provider, model) {
-  const byModel = modelPoolByProvider && modelPoolByProvider.get(provider);
-  return (byModel && byModel.get(model)) || (providerToPool && providerToPool.get(provider)) || null;
-}
-
-/** Parse an expiry value (timestamp ms or ISO date string) to epoch ms. */
-export function parseExpiry(v) {
-  if (typeof v === 'number' && v > 0) return v;
-  if (typeof v === 'string' && v.length > 0) { const ts = Date.parse(v); return Number.isNaN(ts) ? undefined : ts; }
-  return undefined;
-}
-
-/** Compute a 0..100 health score for a pool based on its runtime state.
- *  Deductions: switches * 5, exhaustions * 10, broken keys * 15. */
-export function computeHealthScore(state) {
-  if (!state || typeof state !== 'object') return 100;
-  const switches = state.switches ?? 0;
-  const exhaustions = state.exhaustionCount ?? 0;
-  const broken = state.brokenUntil ? state.brokenUntil.size : 0;
-  return Math.max(0, Math.min(100, 100 - (switches * 5) - (exhaustions * 10) - (broken * 15)));
-}
-
-/** Extract rate-limit info from an object that may carry response headers.
- *  Looks for X-RateLimit-Remaining / X-RateLimit-Limit / X-RateLimit-Reset
- *  (case-insensitive) in headers. Returns { remaining, limit, reset } or null. */
-export function extractRateLimit(headers) {
-  if (!headers || typeof headers !== 'object') return null;
-  const get = (name) => {
-    const v = headers[name] ?? headers[name.toLowerCase()] ?? headers[name.toUpperCase()];
-    if (v === undefined || v === null) return undefined;
-    return Number(String(v));
-  };
-  const remaining = get('X-RateLimit-Remaining');
-  const limit = get('X-RateLimit-Limit');
-  const reset = get('X-RateLimit-Reset');
-  if (remaining === undefined && limit === undefined) return null;
-  return { remaining, limit, reset };
-}
-
-/** True if remaining is below the given threshold fraction of limit (e.g. 0.1). */
-export function isRateLimited(rate, threshold = 0.1) {
-  if (!rate) return false;
-  if (rate.remaining === undefined) return false;
-  if (rate.limit && rate.limit > 0) return rate.remaining < rate.limit * threshold;
-  return rate.remaining <= 0;
-}
+// Pure helpers for the key-rotation plugin. Kept free of DSH runtime
+// dependencies so they can be unit-tested under `node --test` without
+// `@deepseek-ai/cordis` / `@deepseek-ai/schemastery` being installed.
+// Anything that talks to `ctx` stays in lib/index.js.
+
+/** Number of trailing characters of a key shown in the UI for disambiguation. */
+export const KEY_TAIL_CHARS = 5;
+
+/** Returns the last KEY_TAIL_CHARS characters of a key, or the whole key if shorter. */
+export function keyTail(value) {
+  if (typeof value !== 'string' || value.length === 0) return '';
+  return value.length <= KEY_TAIL_CHARS ? value : value.slice(-KEY_TAIL_CHARS);
+}
+
+/** True if a socket remoteAddress is a loopback (v4 / v6). */
+export function isLoopbackAddress(address) {
+  if (address === undefined || address === null) return false;
+  if (address === '127.0.0.1' || address === '::1') return true;
+  if (typeof address === 'string' && address.startsWith('::ffff:')) {
+    return address.slice(7) === '127.0.0.1';
+  }
+  return false;
+}
+
+/** True if a request is both loopback and same-origin (sec-fetch-site guard). */
+export function isTrustedBridgeRequest(request) {
+  if (!isLoopbackAddress(request?.socket?.remoteAddress)) return false;
+  if (request?.headers?.['sec-fetch-site'] === 'cross-site') return false;
+  const origin = request?.headers?.origin;
+  if (origin === undefined) return true; // no Origin header (loopback tool) is allowed
+  try {
+    const host = request?.headers?.host;
+    if (host === undefined) return false;
+    return new URL(origin).host === host;
+  } catch {
+    return false;
+  }
+}
+
+/** Compiled once at module load. Matches error messages that should rotate the key
+ *  even when the structured failure code is not in `switchCodes`.
+ *  Mirrors SWITCHABLE_MESSAGE_PATTERN in lib/index.js exactly. */
+export const SWITCHABLE_MESSAGE_PATTERN = new RegExp([
+  /\b(?:quota|usage[\s_-]+limit|rate[\s_-]?limit)\b/i,
+  /\binsufficient[\s_-]+(?:quota|balance|credits?)\b/i,
+  /\bout[\s_-]+of[\s_-]+(?:credits?|budget)\b/i,
+  /\b(?:exceeded|exhausted)[\s_-]+(?:quota|limit|budget)\b/i,
+  /\bbilling\b/i,
+  /\b429\b|\b5\d\d\b/i,
+  /\btime(?:d)?\s*out\b|timeout/i,
+  /\b(?:network|connection|socket|fetch|ECONN[A-Z]+)\b/i,
+  /\bother side closed|premature close|stream ended (?:before|without)\b/i,
+  /\b401\b|\b403\b/i,
+  /\b(?:invalid|expired|revoked|unauthorized)[\s_-]+(?:api[\s_-]?key|token)\b/i,
+  /\bapi[\s_-]?key[\s_-]+(?:is[\s_-]+)?(?:invalid|expired|revoked|unauthorized)\b/i,
+  /\b(?:authentication|unauthorized|not[\s_-]+authorized)\b/i,
+].map((r) => r.source).join('|'), 'i');
+
+/** Default switch codes used by lib/index.js. Kept here so tests assert against
+ *  the same list the runtime ships. */
+export const DEFAULT_SWITCH_CODES = [
+  'QUOTA', 'RATE_LIMIT', 'SERVER', 'TIMEOUT', 'TRANSPORT',
+  'EMPTY_RESPONSE', 'UNKNOWN_MODEL', 'AUTH',
+];
+
+/** Ref name validator. Same rule lib/index.js enforces in PUT/DELETE /key. */
+const REF_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export function isValidRef(ref) {
+  return typeof ref === 'string' && REF_RE.test(ref);
+}
+
+/**
+ * Pick the next healthy ref in a round-robin pool.
+ *
+ * @param {{ refs: string[], state: { failedUntil: Map<string, number>, pointer: number } }} pool
+ * @param {number} now - epoch milliseconds (injectable for tests)
+ * @param {number} refsCount - for tests: number of refs to consider (defaults to pool.refs.length)
+ * @returns {string|undefined} the ref to use, or undefined if pool has no refs
+ *
+ * Mirrors the inline logic in the credentials.resolve patch in lib/index.js.
+ * Exported here for unit tests; not used at runtime to avoid duplicating logic.
+ */
+export function pickNext(pool, now, refsCount = pool.refs.length) {
+  if (refsCount === 0) return undefined;
+  const start = pool.state.pointer ?? 0;
+  for (let i = 0; i < refsCount; i++) {
+    const index = (start + i) % refsCount;
+    const candidate = pool.refs[index];
+    const until = pool.state.failedUntil.get(candidate);
+    if (until !== undefined && until > now) continue;
+    return candidate;
+  }
+  return undefined; // all cooled
+}
+
+/** Apply a failed-key cooldown to pool state. Pure: returns next state shape,
+ *  does not mutate input. Runtime in lib/index.js mutates in place; tests use
+ *  this helper to construct expected snapshots. */
+export function applyCooldown(pool, ref, cooldownMs, now = Date.now()) {
+  return {
+    ...pool,
+    state: {
+      ...pool.state,
+      failedUntil: new Map(pool.state.failedUntil).set(ref, now + cooldownMs),
+    },
+  };
+}
+
+/** Exponential backoff for a repeatedly failing key.
+ *  failCount 1 => baseMs, 2 => baseMs*2, 3 => baseMs*4, capped at baseMs*8 (or maxMs).
+ *  Pure and easily unit-tested. */
+export function computeBackoff(baseMs, failCount, maxMs) {
+  const cap = maxMs ?? baseMs * 8;
+  if (failCount <= 1) return Math.min(baseMs, cap);
+  const backoff = baseMs * (1 << (failCount - 1)); // 2^(n-1)
+  return Math.min(backoff, cap);
+}
+
+/** Record a failure for `ref` in `pool.state`, applying exponential backoff.
+ *  Mutates pool.state.failedUntil and pool.state.failCounts. Returns the backoff used. */
+export function recordFailure(pool, ref, now, baseMs, maxMs) {
+  if (!pool.state.failCounts) pool.state.failCounts = new Map();
+  const prev = pool.state.failCounts.get(ref) ?? 0;
+  const next = prev + 1;
+  pool.state.failCounts.set(ref, next);
+  const backoff = computeBackoff(baseMs, next, maxMs);
+  pool.state.failedUntil.set(ref, now + backoff);
+  return backoff;
+}
+
+/** Record a success for `ref` — clears its cooldown and resets its fail count. */
+export function recordSuccess(pool, ref) {
+  if (pool.state.failCounts) pool.state.failCounts.delete(ref);
+  pool.state.failedUntil.delete(ref);
+}
+
+/** Return env value for ref if present in process.env, else undefined. */
+export function envValue(ref) {
+  const v = typeof process !== 'undefined' ? process.env?.[ref] : undefined;
+  return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+
+/** Sweep expired cooldown entries from poolState. Returns count of cleared refs. */
+export function sweepExpired(poolState, now = Date.now()) {
+  let cleared = 0;
+  for (const st of poolState.values()) {
+    for (const [ref, until] of [...st.failedUntil.entries()]) {
+      if (until <= now) {
+        st.failedUntil.delete(ref);
+        st.failCounts?.delete(ref);
+        cleared++;
+      }
+    }
+  }
+  return cleared;
+}
+
+/** Parse Retry-After value from a header string or message.
+ *  Supports seconds ("60", "Retry-After: 60") and HTTP-date ("Wed, 21 Oct 2026 07:28:00 GMT").
+ *  Returns milliseconds or undefined if not parseable. */
+export function parseRetryAfter(value) {
+  if (typeof value !== 'string' || !value) return undefined;
+  // Try to extract "Retry-After: <val>" from a larger message
+  const m = value.match(/retry-after\s*[:=]\s*(.+)/i);
+  const raw = m ? m[1].trim().split(/[\n\r;]/)[0].trim() : value.trim();
+  // Seconds
+  if (/^\d+$/.test(raw)) {
+    const sec = Number(raw);
+    if (sec >= 0 && sec <= 86400 * 7) return sec * 1000;
+  }
+  // HTTP-date
+  const ts = Date.parse(raw);
+  if (!Number.isNaN(ts)) {
+    const diff = ts - Date.now();
+    if (diff > 0 && diff < 86400 * 7 * 1000) return diff;
+  }
+  return undefined;
+}
+
+/** Pick a key pool for a (provider, model) pair. Model sub-pools win over the
+ *  provider base pool; falls back to the base pool when no sub-pool matches.
+ *  #195 tier-aware: an exact model pool wins; otherwise the longest model-key
+ *  that is a family prefix of the requested model wins (e.g. a pool defined
+ *  for "gpt-4o" serves "gpt-4o-mini-2024"); otherwise the base pool. */
+export function selectPool(modelPoolByProvider, providerToPool, provider, model) {
+  const byModel = modelPoolByProvider && modelPoolByProvider.get(provider);
+  const base = providerToPool && providerToPool.get(provider);
+  if (!byModel || !model) return base ?? null;
+  if (byModel.has(model)) return byModel.get(model);
+  let best = null;
+  for (const key of byModel.keys()) {
+    if (model.startsWith(key) && key.length > (best ? best.length : 0)) best = key;
+  }
+  return (best ? byModel.get(best) : base) ?? null;
+}
+
+/** Parse an expiry value (timestamp ms or ISO date string) to epoch ms. */
+export function parseExpiry(v) {
+  if (typeof v === 'number' && v > 0) return v;
+  if (typeof v === 'string' && v.length > 0) { const ts = Date.parse(v); return Number.isNaN(ts) ? undefined : ts; }
+  return undefined;
+}
+
+/** Compute a 0..100 health score for a pool based on its runtime state.
+ *  Deductions: switches * 5, exhaustions * 10, broken keys * 15. */
+export function computeHealthScore(state) {
+  if (!state || typeof state !== 'object') return 100;
+  const switches = state.switches ?? 0;
+  const exhaustions = state.exhaustionCount ?? 0;
+  const broken = state.brokenUntil ? state.brokenUntil.size : 0;
+  return Math.max(0, Math.min(100, 100 - (switches * 5) - (exhaustions * 10) - (broken * 15)));
+}
+
+/** Extract rate-limit info from an object that may carry response headers.
+ *  Looks for X-RateLimit-Remaining / X-RateLimit-Limit / X-RateLimit-Reset
+ *  (case-insensitive) in headers. Returns { remaining, limit, reset } or null. */
+export function extractRateLimit(headers) {
+  if (!headers || typeof headers !== 'object') return null;
+  const get = (name) => {
+    const v = headers[name] ?? headers[name.toLowerCase()] ?? headers[name.toUpperCase()];
+    if (v === undefined || v === null) return undefined;
+    return Number(String(v));
+  };
+  const remaining = get('X-RateLimit-Remaining');
+  const limit = get('X-RateLimit-Limit');
+  const reset = get('X-RateLimit-Reset');
+  if (remaining === undefined && limit === undefined) return null;
+  return { remaining, limit, reset };
+}
+
+/** True if remaining is below the given threshold fraction of limit (e.g. 0.1). */
+export function isRateLimited(rate, threshold = 0.1) {
+  if (!rate) return false;
+  if (rate.remaining === undefined) return false;
+  if (rate.limit && rate.limit > 0) return rate.remaining < rate.limit * threshold;
+  return rate.remaining <= 0;
+}

package/lib/quota-window.js

@@ -1,45 +1,45 @@
-// quota-window.js — calendar-based quota reset windows (issue #197).
-
-export const QUOTA_WINDOW_TYPES = ['midnight_utc', 'midnight_pst', 'rolling_24h'];
-
-export function nextQuotaReset(quotaResetWindow, now) {
-  now = now || Date.now();
-  if (!quotaResetWindow || typeof quotaResetWindow !== 'object') return null;
-  const type = quotaResetWindow.type;
-  const hour = Number.isFinite(quotaResetWindow.hour) ? quotaResetWindow.hour : 0;
-
-  if (type === 'rolling_24h') {
-    const d = new Date(now);
-    d.setUTCHours(d.getUTCHours() + 24, 0, 0, 0);
-    return d.getTime();
-  }
-
-  if (type === 'midnight_utc') {
-    const d = new Date(now);
-    d.setUTCHours(hour, 0, 0, 0);
-    if (d.getTime() <= now) d.setUTCDate(d.getUTCDate() + 1);
-    return d.getTime();
-  }
-
-  if (type === 'midnight_pst') {
-    const PST_OFFSET_MS = 8 * 3600_000;
-    const shifted = now + PST_OFFSET_MS;
-    const d = new Date(shifted);
-    d.setUTCHours(hour, 0, 0, 0);
-    if (d.getTime() <= shifted) d.setUTCDate(d.getUTCDate() + 1);
-    return d.getTime() - PST_OFFSET_MS;
-  }
-
-  return null;
-}
-
-export function poolResetAt(pool, quotaResetWindow, now) {
-  return nextQuotaReset(quotaResetWindow, now);
-}
-
-export function isBlockedUntilReset(failedUntil, resetAt, now) {
-  now = now || Date.now();
-  if (!Number.isFinite(failedUntil)) return false;
-  if (resetAt === null || resetAt === undefined) return false;
-  return failedUntil >= resetAt;
-}
+// quota-window.js — calendar-based quota reset windows (issue #197).
+
+export const QUOTA_WINDOW_TYPES = ['midnight_utc', 'midnight_pst', 'rolling_24h'];
+
+export function nextQuotaReset(quotaResetWindow, now) {
+  now = now || Date.now();
+  if (!quotaResetWindow || typeof quotaResetWindow !== 'object') return null;
+  const type = quotaResetWindow.type;
+  const hour = Number.isFinite(quotaResetWindow.hour) ? quotaResetWindow.hour : 0;
+
+  if (type === 'rolling_24h') {
+    const d = new Date(now);
+    d.setUTCHours(d.getUTCHours() + 24, 0, 0, 0);
+    return d.getTime();
+  }
+
+  if (type === 'midnight_utc') {
+    const d = new Date(now);
+    d.setUTCHours(hour, 0, 0, 0);
+    if (d.getTime() <= now) d.setUTCDate(d.getUTCDate() + 1);
+    return d.getTime();
+  }
+
+  if (type === 'midnight_pst') {
+    const PST_OFFSET_MS = 8 * 3600_000;
+    const shifted = now + PST_OFFSET_MS;
+    const d = new Date(shifted);
+    d.setUTCHours(hour, 0, 0, 0);
+    if (d.getTime() <= shifted) d.setUTCDate(d.getUTCDate() + 1);
+    return d.getTime() - PST_OFFSET_MS;
+  }
+
+  return null;
+}
+
+export function poolResetAt(pool, quotaResetWindow, now) {
+  return nextQuotaReset(quotaResetWindow, now);
+}
+
+export function isBlockedUntilReset(failedUntil, resetAt, now) {
+  now = now || Date.now();
+  if (!Number.isFinite(failedUntil)) return false;
+  if (resetAt === null || resetAt === undefined) return false;
+  return failedUntil >= resetAt;
+}