@goodandready/dsh-key-rotation 0.7.39 → 0.7.40

package/README.md

@@ -57,7 +57,7 @@ Unlike naive routing proxies that alter provider identifiers, `dsh-key-rotation`
 * **The provider identity never changes**: Agent replay states, multi-call turns, and tool schemas remain 100% consistent.
 * **Pre-emptive Token Bucket**: Throttled keys are skipped *before* issuing network calls, eliminating retry latency.
 * **Least-Connections Concurrency Control**: Balances in-flight streams across keys to prevent burst saturation.
-* **Autonomous Self-Healing & Cascades**: Proactively tests quarantined keys via canary probes and smoothly escalates to fallback providers if an entire pool is exhausted.
+* **Autonomous Self-Healing & Cascades**: Lifts expired quarantines on idle keys and smoothly escalates to fallback providers if an entire pool is exhausted.
 
 ---
 
@@ -85,8 +85,8 @@ graph LR
         Failover -.->|All Pool Keys Exhausted| CascadeEngine["Cross-Provider Cascade"]
         
         BackoffCalc --> QuotaWindow["Calendar Reset / Midnight Window"]
-        BackoffCalc --> CanaryProbe["Active Canary Prober (Sandbox Ping)"]
-        CanaryProbe -->|Verified Healthy| PoolReady["Restored to Ready Pool"]
+        BackoffCalc --> SelfHeal["Self-Heal Idle Sweep"]
+        SelfHeal -->|Cooldown Expired| PoolReady["Restored to Ready Pool"]
     end
 
     subgraph UpstreamLayer ["Model Provider Endpoints"]
@@ -117,21 +117,18 @@ graph LR
 
 ### 🛡️ 3. Autonomous Healing & Cascade Escalation
 * **Cross-Provider Failover Cascade (`lib/cascade.js`)**: If all keys for a selected provider are in cooldown, requests automatically cascade to an alternative fallback provider pool (e.g., primary provider → fallback proxy / secondary provider).
-* **Active Canary Prober (`lib/canary.js`)**: Before releasing a key from quarantine, a lightweight background probe (`/models` probe or single-token check via `SandboxRunner`) validates upstream availability without exposing real user traffic to risk.
+* **Sandbox Key Probes (`lib/sandbox.js`)**: On-demand `/models` probes validate a key before returning it to rotation; idle cooldowns are lifted by the self-heal sweep.
 * **Calendar & Rolling Quota Reset Windows (`lib/quota-window.js`)**: Supports scheduled quota reset alignments (`midnight_utc`, `midnight_pst`, and `rolling_24h`) so daily free/tier quotas unfreeze exactly when upstream resets them.
 * **Adaptive Exponential Backoff (`lib/pool.js`)**: Successive failures on a key double its quarantine duration (base → ×2 → ×4 → cap ×8). Successful requests gradually restore healthy status.
 
-### 🎯 4. Model-Aware & Geolocation Routing
+### 🎯 4. Model-Aware Routing
 * **Model Sub-Pools (`lib/pool.js`)**: Configure dedicated key pools for specific model tiers (e.g. reasoning/heavy models vs fast/cheap utility models).
 * **Tag-Based Routing**: Assign operational tags (`production`, `background`, `eval`) to match key usage with workload priorities.
-* **Region Mapping (`lib/region.js`)**: Route queries through geographically optimal credentials and endpoints.
 
 ### 📊 5. Observability, Telemetry & Webhooks
 * **Interactive Multi-Platform Webhooks (`lib/webhook.js`)**: Dispatches rich notifications with HMAC-signed action buttons for **Telegram** (Inline Keyboards), **Discord** (Action Rows), and **Slack** (Block Kit). Administrators can click buttons to reset cooldowns or pause providers directly from their mobile chat.
 * **Usage & Cost Reporting (`lib/usage-report.js`)**: Per-key daily request counters and estimated cost breakdown with one-click CSV/JSON export (`GET /dsh-key-rotation/usage-report`).
 * **Latency SLO & Histogram (`lib/histogram.js`)**: Tracks Time-To-First-Token (TTFT) and stream durations with health score degradation scoring (`0..100`).
-* **Automated Incident Reporting (`lib/incident.js`)**: Lazily creates structured GitHub Issues on sustained upstream outages.
-* **Shadow Traffic Routing (`lib/shadow.js`)**: Fork a configurable percentage of live requests to evaluate secondary providers in shadow mode.
 
 ---
 
@@ -195,7 +192,6 @@ dsh-key-rotation:
     - UNKNOWN_MODEL
     - AUTH
   cooldownMs: 60000
-  canaryProbing: true
   concurrencyLimit: 5
   quotaResetWindow:
     type: midnight_utc
@@ -224,7 +220,6 @@ dsh-key-rotation:
 |---|---|---|---|
 | `switchCodes` | `string[]` | `[QUOTA, RATE_LIMIT, ...]` | List of error codes that immediately trigger failover. |
 | `cooldownMs` | `number` | `60000` (1 min) | Base penalty duration (in ms) for quarantined keys. |
-| `canaryProbing` | `boolean` | `true` | Runs background ping probe before restoring quarantined keys. |
 | `concurrencyLimit` | `number` | `0` (disabled) | Max concurrent in-flight streams per key (0 = unlimited). |
 | `quotaResetWindow` | `object` | `null` | Calendar reset alignment (`midnight_utc`, `midnight_pst`, `rolling_24h`). |
 | `cascade` | `array` | `[]` | Fallback provider chain when primary pool is completely exhausted. |

package/README.ru.md

@@ -57,7 +57,7 @@
 * **Идентичность провайдера остаётся неизменной**: Внутреннее Replay-состояние агента `pi-ai` и контекст инструментов остаются на 100% консистентными.
 * **Предиктивный Token Bucket**: Перегруженные ключи пропускаются **до** выполнения сетевого запроса, устраняя задержку на сетевой ретрай.
 * **Балансировка Least-Connections**: Запросы равномерно распределяются по свободным ключам с контролем параллелизма (`maxConcurrency`).
-* **Автономное самовосстановление и каскад**: Фоновые canary-зонды проверяют заблокированные ключи, а при полном исчерпании пула запрос бесшовно передаётся запасному провайдеру.
+* **Автономное самовосстановление и каскад**: Просроченные кулдауны простаивающих ключей снимаются автоматически, а при полном исчерпании пула запрос бесшовно передаётся запасному провайдеру.
 
 ---
 
@@ -85,8 +85,8 @@ graph LR
         Failover -.->|Все ключи в кулдауне| CascadeEngine["Межпровайдерный каскад"]
         
         BackoffCalc --> QuotaWindow["Календарный сброс / Полночь UTC/PST"]
-        BackoffCalc --> CanaryProbe["Active Canary-зонд (Sandbox Ping)"]
-        CanaryProbe -->|Ключ работоспособен| PoolReady["Возврат в пул готовых ключей"]
+        BackoffCalc --> SelfHeal["Self-Heal sweep простаивания"]
+        SelfHeal -->|Кулдаун истёк| PoolReady["Возврат в пул готовых ключей"]
     end
 
     subgraph UpstreamLayer ["Эндпоинты провайдеров"]
@@ -117,21 +117,18 @@ graph LR
 
 ### 🛡️ 3. Автономное самовосстановление и каскадный Failover
 * **Межпровайдерный каскад (`lib/cascade.js`)**: При исчерпании всех ключей выбранного провайдера запрос автоматически каскадируется на настроенного резервного провайдера (`cascade: [{ provider, model }]`).
-* **Active Canary Prober (`lib/canary.js`)**: Перед выводом ключа из кулдауна плагин выполняет легкий фоновый зонд (`/models` probe через `SandboxRunner`), защищая боевой трафик от повторных сбоев.
+* **Sandbox-пробы ключей (`lib/sandbox.js`)**: По запросу выполняется `/models`-проба ключа перед возвратом в ротацию; простаивающие кулдауны снимаются self-heal sweep.
 * **Календарный сброс квот (`lib/quota-window.js`)**: Учитывает окна сброса суточных квот провайдеров (`midnight_utc`, `midnight_pst`, `rolling_24h`), снимая карантин ровно в момент обновления лимитов у апстрима.
 * **Экспоненциальный бэкофф (`lib/pool.js`)**: Повторные сбои на ключе прогрессивно увеличивают время кулдауна (базовое → ×2 → ×4 → максимум ×8).
 
-### 🎯 4. Маршрутизация по моделям и гео-регионам
+### 🎯 4. Маршрутизация по моделям
 * **Модельные подпулы (`lib/pool.js`)**: Назначение выделенных ключей под конкретные модели (например, отдельные ключи для тяжелых reasoning-моделей и дешевые ключи для утилит).
 * **Тегирование ключей**: Метки приоритета (`production`, `background`, `eval`) для разделения квот между интерактивными и фоновыми задачами.
-* **Гео-роутинг (`lib/region.js`)**: Маршрутизация запросов через оптимальные региональные эндпоинты.
 
 ### 📊 5. Телеметрия, аналитика и интерактивные вебхуки
 * **Интерактивные вебхуки (`lib/webhook.js`)**: Отправка форматированных алертов с кнопками действий в **Telegram** (Inline Keyboards), **Discord** (Action Rows) и **Slack** (Block Kit). Администратор может сбросить кулдаун или отключить провайдер прямо из мессенджера.
 * **Отчеты об использовании и расходах (`lib/usage-report.js`)**: Учет суточного числа запросов и расчетной стоимости по каждому ключу с экспортом в CSV/JSON (`GET /dsh-key-rotation/usage-report`).
 * **Гистограмма задержек SLO (`lib/histogram.js`)**: Измерение времени до первого токена (TTFT) и расчет индекса здоровья пула (`0..100`).
-* **Автоматические инциденты (`lib/incident.js`)**: Создание issue в GitHub при масштабных системных сбоях провайдеров.
-* **Shadow-трафик (`lib/shadow.js`)**: Теневое дублирование процента запросов для тестирования альтернативных провайдеров.
 
 ---
 
@@ -195,7 +192,6 @@ dsh-key-rotation:
     - UNKNOWN_MODEL
     - AUTH
   cooldownMs: 60000
-  canaryProbing: true
   concurrencyLimit: 5
   quotaResetWindow:
     type: midnight_utc
@@ -224,7 +220,6 @@ dsh-key-rotation:
 |---|---|---|---|
 | `switchCodes` | `string[]` | `[QUOTA, RATE_LIMIT, ...]` | Список кодов ошибок, инициирующих немедленный переход на следующий ключ. |
 | `cooldownMs` | `number` | `60000` (1 мин) | Базовая длительность нахождения ключа в карантине (в мс). |
-| `canaryProbing` | `boolean` | `true` | Фоновая проверка ключа canary-зондом перед возвратом из карантина. |
 | `concurrencyLimit` | `number` | `0` (отключено) | Лимит одновременных активных запросов на ключ (0 = без ограничений). |
 | `quotaResetWindow` | `object` | `null` | Календарное расписание сброса квот (`midnight_utc`, `midnight_pst`, `rolling_24h`). |
 | `cascade` | `array` | `[]` | Цепочка резервных провайдеров при исчерпании всех ключей основного пула. |

package/README.zh.md

@@ -117,7 +117,7 @@ graph LR
 
 ### 🛡️ 3. 自动愈合与跨提供商级联
 * **跨提供商故障转移级联 (`lib/cascade.js`)**：主提供商密钥全部冷却时，自动级联路由到备用提供商池。
-* **金丝雀探针探活 (`lib/canary.js`)**：密钥出冷却期前，自动发起轻量探测验证上游可用性，避免影响用户真实请求。
+* **沙箱密钥探测 (`lib/sandbox.js`)**：按需对密钥执行 `/models` 探测后再回到轮换；空闲冷却由 self-heal sweep 解除。
 * **配额日历重置对齐 (`lib/quota-window.js`)**：支持 `midnight_utc`、`midnight_pst` 与 `rolling_24h` 配额刷新窗口。
 * **自适应指数退避 (`lib/pool.js`)**：连续失败使冷却时间呈指数递增（基准 → ×2 → ×4 → 上限 ×8）。
 
@@ -125,7 +125,6 @@ graph LR
 * **交互式 Webhook (`lib/webhook.js`)**：向 **Telegram**、**Discord**、**Slack** 推送带交互按钮的富文本警报，可在移动聊天中一键重置冷却或暂停提供商。
 * **使用量与成本报表 (`lib/usage-report.js`)**：按日统计各密钥请求数与预估成本，支持一键导出 CSV/JSON (`GET /dsh-key-rotation/usage-report`)。
 * **延迟 SLO 监控 (`lib/histogram.js`)**：记录首字延迟（TTFT）与健康度评分 (`0..100`)。
-* **影子流量测试 (`lib/shadow.js`)**：支持配置百分比的流量镜像复制以评估次要提供商。
 
 ---
 
@@ -185,7 +184,6 @@ dsh-key-rotation:
     - UNKNOWN_MODEL
     - AUTH
   cooldownMs: 60000
-  canaryProbing: true
   concurrencyLimit: 5
   quotaResetWindow:
     type: midnight_utc

package/lib/http-bridge.js

@@ -0,0 +1,169 @@
+// lib/http-bridge.js — shared HTTP helpers for dsh-key-rotation routes.
+import { findSecrets } from './keycheck.js';
+import { isTrustedBridgeRequest } from './pool.js';
+
+export const NS = 'dsh-key-rotation';
+
+export function json(res, status, obj) {
+  res.writeHead(status, { 'content-type': 'application/json' });
+  res.end(JSON.stringify(obj));
+}
+
+export function readJson(request) {
+  return new Promise((resolve, reject) => {
+    let raw = '';
+    request.on('data', (c) => { raw += c; });
+    request.on('end', () => {
+      try {
+        resolve(JSON.parse(raw || '{}'));
+      } catch (e) {
+        reject(e);
+      }
+    });
+    request.on('error', reject);
+  });
+}
+
+export function descriptorOf(ctx, ns) {
+  const settings = ctx.get('settings');
+  if (settings === void 0) return void 0;
+  return settings.describe({ redactSecrets: true }).find((candidate) => candidate.ns === ns);
+}
+
+export function viewOf(descriptor, settings) {
+  return {
+    available: true,
+    writable: settings.writable,
+    hasDocument: settings.hasDocument,
+    value: descriptor.value,
+    ...descriptor.base === void 0 ? {} : { base: descriptor.base },
+    ...descriptor.user === void 0 || Object.keys(descriptor.user).length === 0 ? {} : { user: descriptor.user },
+    revision: descriptor.revision,
+  };
+}
+
+export async function writeSection(ctx, ns, section, expectedRevision, res) {
+  const settings = ctx.get('settings');
+  if (settings === void 0) {
+    json(res, 503, { error: { code: 'settings-rejected', message: 'dsh-key-rotation: no settings provider is mounted' } });
+    return;
+  }
+  try {
+    await settings.replace(ns, section, expectedRevision);
+  } catch (error) {
+    if (error?.code === 'SETTINGS_CONFLICT') {
+      json(res, 409, { error: { code: 'settings-conflict', message: `dsh-key-rotation: changed elsewhere (expected revision ${String(error.expected)}, current ${String(error.actual)}); reload and retry` } });
+      return;
+    }
+    json(res, 400, { error: { code: 'settings-rejected', message: error instanceof Error ? error.message : String(error) } });
+    return;
+  }
+  const descriptor = descriptorOf(ctx, ns);
+  if (descriptor === void 0) {
+    json(res, 500, { error: { code: 'settings-rejected', message: 'dsh-key-rotation: namespace vanished after write' } });
+    return;
+  }
+  json(res, 200, viewOf(descriptor, { writable: settings.writable, hasDocument: settings.documentPath !== void 0 }));
+}
+
+export function providerCatalog(ctx, cloneIds) {
+  const seen = new Set();
+  const out = [];
+  for (const info of ctx.llm.listProviders()) {
+    if (seen.has(info.id) || cloneIds.has(info.id)) continue;
+    seen.add(info.id);
+    out.push({ id: info.id, name: info.name ?? info.id });
+  }
+  return out;
+}
+
+export function guardLocal(req, res, label) {
+  if (!isTrustedBridgeRequest(req)) {
+    json(res, 403, { error: { code: 'forbidden', message: `dsh-key-rotation: ${label} is local-only` } });
+    return false;
+  }
+  return true;
+}
+
+export function scanForLiveSecrets(section) {
+  const masked = structuredClone(section);
+  if (masked.webhookActionToken) masked.webhookActionToken = '***';
+  if (masked.notifyWebhook) masked.notifyWebhook = '***';
+  return findSecrets(JSON.stringify(masked));
+}
+
+/** Config bridge GET/PUT/DELETE — extracted from lib/index.js for size (#253). */
+export async function handleConfigBridge(ctx, request, res, getCloneIds) {
+  if (!isTrustedBridgeRequest(request)) {
+    res.writeHead(403);
+    res.end();
+    return;
+  }
+  const method = request.method ?? 'GET';
+  if (method === 'GET') {
+    const settings = ctx.get('settings');
+    const descriptor = descriptorOf(ctx, NS);
+    const body = {
+      providers: providerCatalog(ctx, getCloneIds()),
+    };
+    if (descriptor === void 0) {
+      json(res, 200, {
+        ...body,
+        available: false,
+        writable: settings?.writable ?? false,
+        hasDocument: settings?.documentPath !== void 0,
+        value: void 0,
+        revision: 0,
+      });
+      return;
+    }
+    json(res, 200, {
+      ...body,
+      ...viewOf(descriptor, {
+        writable: settings?.writable ?? false,
+        hasDocument: settings?.documentPath !== void 0,
+      }),
+    });
+    return;
+  }
+  if (method === 'PUT' || method === 'DELETE') {
+    let section;
+    let expectedRevision;
+    if (method === 'PUT') {
+      let body;
+      try {
+        body = await readJson(request);
+      } catch (error) {
+        json(res, 400, { error: { code: 'settings-rejected', message: `dsh-key-rotation: invalid request body: ${error instanceof Error ? error.message : String(error)}` } });
+        return;
+      }
+      if (typeof body !== 'object' || body === null || typeof body.section !== 'object' || body.section === null || Array.isArray(body.section)) {
+        json(res, 400, { error: { code: 'settings-rejected', message: 'dsh-key-rotation: PUT requires {"section": {...}}' } });
+        return;
+      }
+      section = body.section;
+      expectedRevision = typeof body.expectedRevision === 'number' ? body.expectedRevision : void 0;
+      try {
+        const findings = scanForLiveSecrets(section);
+        if (findings.length > 0) {
+          json(res, 400, {
+            error: {
+              code: 'secret-in-config',
+              message: `dsh-key-rotation: value looks like a live credential (${findings[0].type}); store key values via the key field, not the config section`,
+              findings,
+            },
+          });
+          return;
+        }
+      } catch {
+        /* scanning must never block a valid save */
+      }
+    } else {
+      section = {};
+      expectedRevision = void 0;
+    }
+    await writeSection(ctx, NS, section, expectedRevision, res);
+    return;
+  }
+  json(res, 405, { error: { code: 'method', message: 'GET, PUT, or DELETE only' } });
+}