@goodandready/dsh-key-rotation 0.8.65 → 0.8.67

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.8.67 - 2026-10-19
+
+### Features
+- **Full Pool Configuration Export & Import (#504)**:
+  - Masked export: exports topology and pools with masked credentials (`sk-...cdef`) and hidden webhook secrets, safe for bug reports and sharing.
+  - Full backup export with AES-256-GCM encryption: optional passphrase encrypts configuration with PBKDF2 (100,000 iterations) using standard `node:crypto`.
+  - Config import route `POST /dsh-key-rotation/config-import`: supports file upload, raw JSON, or encrypted payload with passphrase decryption.
+  - Diff preview mode: `dryRun: true` returns summary of created/updated/removed providers and keys count before applying.
+  - Interactive UI in Settings card: modal drawers for Export (masked vs full, optional passphrase) and Import (file upload, merge vs replace modes, diff preview, apply).
+- **Quick Key Actions in Chat Header Popover (#499)**:
+  - Extended `KeyRotationHeaderChip` popover: displays active provider and key tail (`...abcd`) for each configured pool.
+  - Interactive inline action buttons:
+    - ⏭️ **Skip**: advances active key cursor to the next healthy candidate in the pool without leaving chat.
+    - 🔄 **Reset**: immediately resets failure counts, cooldowns, and circuit breaker for the active provider.
+    - ⏸️ **Pause**: toggles pause state on the currently active key for immediate fault isolation.
+  - Endpoint `POST /dsh-key-rotation/quick-action`: secure loopback-validated operational route executing skip, reset, and pause commands with audit telemetry events.
+
+## 0.8.66 - 2026-10-19
+
+### Features
+- **Dynamic Reset Scheduler Based on Rate-Limit Headers (#498)**:
+  - Exact cooldown alignment: parses upstream `retry-after`, `x-ratelimit-reset-*`, and `anthropic-ratelimit-*-reset` headers or message duration patterns upon rate-limit failures, setting precise cooldown `failedUntil = now + dynamicCooldownMs` (+250ms safety jitter, bounded by `maxCooldownMs`) with `resetReason = 'header'`.
+  - Immediate unref recovery timer: schedules an exact unref `setTimeout` wake-up for the penalised key right when the upstream window rolls over, rather than waiting up to 30s for the periodic sweep.
+  - Exposes `resetReason` and `headerResetMs` in `/dsh-key-rotation/status` and WebUI countdown badge (`⏳ reset in Xs (header)`).
+- **Upstream Balance Inspector & Credit Tracking (#495)**:
+  - Multi-provider balance checker (`lib/balance-inspector.js`): queries live account balances and remaining credits for DeepSeek (`/user/balance`), SiliconFlow (`/v1/user/info`), OpenRouter (`/api/v1/auth/key`), and OpenAI (`/v1/dashboard/billing/credit_grants`).
+  - Balance ops route `GET/POST /dsh-key-rotation/balance` (`lib/ops-balance.js`): queries cached balances or triggers immediate live balance inspection across provider keys.
+  - Pre-emptive empty balance protection: keys with confirmed zero balance (`isZero: true`) enter a soft pause (`EMPTY_BALANCE_PAUSED`), avoiding upstream dispatch failures, and auto-resume immediately when refreshed with positive balance.
+  - Persistent balance state: balances are cached in `pool.state.balances` and persisted across harness restarts via `lib/persistence.js`.
+  - WebUI integration: interactive `Check Balances` action button in provider footer and real-time balance badge pills (`💰 15.50 CNY`, `💰 $4.20`) on key cards.
+
 ## 0.8.65 - 2026-10-18
 
 ### Features

package/README.md

@@ -67,6 +67,14 @@
 - **📡 Status extras**: per-provider `circuit` plus `meta.expectedClones` / `meta.notifyQueue`.
 - **🧪 Smoke harness**: scripted 429 → next-key → success path in `test/smoke-rotation-080.test.mjs`.
 
+### 🚀 What's New in v0.8.67
+- **📥 Full Pool Config Export & Import (#504)**: Masked export for safe sharing, full backup export with AES-256-GCM encryption (PBKDF2), diff preview mode, and import with merge/replace strategies.
+- **⚡ Quick Actions in Chat Header Popover (#499)**: Instant key management directly from the conversation toolbar — skip to next key, reset cooldowns, or pause problematic keys via `/dsh-key-rotation/quick-action`.
+
+### 🚀 What's New in v0.8.66
+- **⏳ Dynamic Reset Scheduler (#498)**: Reads upstream `retry-after` and `x-ratelimit-reset-*` headers to set exact cooldowns (+250ms safety jitter) and schedules immediate unref wake-up timers when the upstream reset window rolls over.
+- **💰 Upstream Balance Inspector & Credit Tracking (#495)**: Live balance checks for DeepSeek, SiliconFlow, OpenRouter, and OpenAI via `/dsh-key-rotation/balance`, pre-emptive empty balance protection (`EMPTY_BALANCE_PAUSED`), persistent balance cache, and WebUI `💰 Balance` pills.
+
 ### 🚀 What's New in v0.8.65
 - **⚡ Leaky Bucket Traffic Smoothing (#496)**: Micro-queue smoothing absorbs rapid multi-agent burst spikes ($\le 1$s) without triggering unnecessary 429 errors or cooldown churning, with zero-delay burst capacity and early failover rotation on queue overflow.
 - **📊 Dynamic Upstream Rate Limits & Presets (#503)**: Dynamic parsing of provider rate limit headers (`x-ratelimit-*`, `anthropic-ratelimit-*`, `retry-after`), live badge display on keys, and 1-click `⚡ Preset Limits` button applying canonical RPM/TPM presets for DeepSeek, Groq, Anthropic, OpenAI, Gemini, and more.

package/README.ru.md

@@ -36,6 +36,14 @@
 
 ---
 
+### 🚀 Что нового в v0.8.67
+- **📥 Экспорт и импорт полной конфигурации пулов (#504)**: Безопасный маскированный экспорт для баг-репортов, полный бэкап с AES-256-GCM шифрованием (PBKDF2), интерактивный diff-предпросмотр и режимы объединения/замены.
+- **⚡ Быстрые действия в поповере шапки чата (#499)**: Управление ключами прямо из тулбара диалога — принудительный пропуск (Skip) на следующий ключ, мгновенный сброс кулдаунов (Reset) и изоляция сбойного ключа (Pause).
+
+### 🚀 Что нового в v0.8.66
+- **⏳ Динамический планировщик сброса кулдауна (#498)**: Точное вычисление времени восстановления ключей по заголовкам `retry-after` и `x-ratelimit-reset-*` (+250мс джиттер) с запуском точного unref-таймера восстановления сразу по истечении окна, не дожидаясь 30-секундного периодического свипа.
+- **💰 Инспектор баланса и отслеживание кредитов (#495)**: Запрос реального баланса провайдеров (DeepSeek, SiliconFlow, OpenRouter, OpenAI) через маршрут `/dsh-key-rotation/balance`, автоматическая мягкая пауза при нулевом балансе (`EMPTY_BALANCE_PAUSED`), персистентное сохранение и плашки баланса в WebUI карточках ключей.
+
 ### 🚀 Что нового в v0.8.65
 - **⚡ Сглаживание трафика (Traffic Smoothing Micro-Queue) (#496)**: Микро-очередь leaky bucket сглаживает кратковременные пики нагрузки (<=1с) от мультиагентных вызовов без лишних ошибок 429 и лишних кулдаунов. При превышении таймаута ожидания микро-очереди запрос автоматически переключается на следующий ключ в пуле.
 - **📊 Динамическое определение лимитов провайдеров и пресеты (#503)**: Автоматический парсинг заголовков `x-ratelimit-*`, `anthropic-ratelimit-*`, `retry-after` с отображением актуальных лимитов прямо на карточке ключа, а также кнопка в 1 клик `⚡ Preset Limits` с каноническими пресетами для DeepSeek, Groq, Anthropic, OpenAI, Gemini и др.

package/README.zh.md

@@ -38,6 +38,14 @@
 
 ## ⚡ 概述与核心痛点
 
+### 🚀 v0.8.67 新特性
+- **📥 密钥池完整配置导入与导出 (#504)**: 支持脱敏导出安全分享、AES-256-GCM 密码加密完整备份、导入差异预览 (Diff Preview) 以及合并/全量替换模式。
+- **⚡ 聊天头部快捷键操作 (#499)**: 直接在对话工具栏气泡中管理密钥 — 快速跳过当前密钥 (Skip)、一键重置冷却与断路器 (Reset)、暂停故障密钥 (Pause)。
+
+### 🚀 v0.8.66 新特性
+- **⏳ 基于限流响应头的动态重置调度器 (#498)**: 解析上游 `retry-after` 与 `x-ratelimit-reset-*` 响应头，设定精确冷却时间（+250ms抖动保护），并通过独立 unref 定时器在窗口重置瞬间立刻唤醒可用密钥，无需等待30秒周期性轮询。
+- **💰 上游余额与信用额度巡检 (#495)**: 支持 DeepSeek、SiliconFlow、OpenRouter、OpenAI 实时余额查询 (`/dsh-key-rotation/balance`)，零余额前置软暂停 (`EMPTY_BALANCE_PAUSED`)，持久化余额状态以及 WebUI 密钥卡片实时余额标签 (`💰 15.50 CNY`)。
+
 ### 🚀 v0.8.65 新特性
 - **⚡ 流量平滑微队列 (Traffic Smoothing Micro-Queue) (#496)**: 漏桶微队列平滑多智能体调用中的毫秒级突发并发，避免触发不必要的429限流与冷却流转。队列等待超限时自动轮转至池中下一个候选密钥。
 - **📊 动态上游限制检测与预设规则 (#503)**: 自动提取上游响应头中的限流数据 (`x-ratelimit-*`, `anthropic-ratelimit-*`, `retry-after`)，并在前端展示实时配额状态；支持一键应用 DeepSeek、Groq、Anthropic、OpenAI、Gemini 等官方规范预设限制。

package/lib/balance-inspector.js

@@ -0,0 +1,176 @@
+// lib/balance-inspector.js — upstream balance inspector and credit tracking (#495).
+
+import { decryptSecret } from './crypto-storage.js';
+
+/**
+ * Inspect upstream balance and credits for a provider API key.
+ * @param {string} provider Provider identifier (e.g., 'deepseek', 'siliconflow', 'openrouter', 'openai')
+ * @param {string} apiKey Raw API key
+ * @param {object} [options]
+ * @returns {Promise<{ ok: boolean, total?: number, currency?: string, isAvailable?: boolean, error?: string }>}
+ */
+export async function checkProviderBalance(provider, apiKey, options = {}) {
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  const timeoutMs = typeof options.timeoutMs === 'number' && options.timeoutMs > 0 ? options.timeoutMs : 6000;
+  const signal = options.signal;
+  const prov = String(provider || '').toLowerCase().trim();
+
+  if (!apiKey || typeof apiKey !== 'string' || !apiKey.trim()) {
+    return { ok: false, error: 'missing api key' };
+  }
+
+  // 1. DeepSeek Official
+  if (prov.includes('deepseek')) {
+    try {
+      const url = 'https://api.deepseek.com/user/balance';
+      const ac = new AbortController();
+      const timer = setTimeout(() => ac.abort(), timeoutMs);
+      const res = await fetchImpl(url, {
+        method: 'GET',
+        headers: {
+          'Authorization': `Bearer ${apiKey.trim()}`,
+          'Accept': 'application/json',
+        },
+        signal: signal ?? ac.signal,
+      });
+      clearTimeout(timer);
+      if (!res.ok) {
+        return { ok: false, status: res.status, error: `HTTP ${res.status}` };
+      }
+      const data = await res.json();
+      const info = data?.balance_infos?.[0];
+      const total = info ? parseFloat(info.total_balance) : 0;
+      const currency = info?.currency || 'CNY';
+      const isAvailable = Boolean(data?.is_available && (Number.isNaN(total) || total > 0));
+      return {
+        ok: true,
+        provider: 'deepseek',
+        total: Number.isFinite(total) ? total : 0,
+        currency,
+        isAvailable,
+        granted: parseFloat(info?.granted_balance || 0),
+        toppedUp: parseFloat(info?.topped_up_balance || 0),
+      };
+    } catch (err) {
+      return { ok: false, error: String(err?.message || err) };
+    }
+  }
+
+  // 2. SiliconFlow
+  if (prov.includes('siliconflow')) {
+    try {
+      const url = 'https://api.siliconflow.cn/v1/user/info';
+      const ac = new AbortController();
+      const timer = setTimeout(() => ac.abort(), timeoutMs);
+      const res = await fetchImpl(url, {
+        method: 'GET',
+        headers: {
+          'Authorization': `Bearer ${apiKey.trim()}`,
+          'Accept': 'application/json',
+        },
+        signal: signal ?? ac.signal,
+      });
+      clearTimeout(timer);
+      if (!res.ok) {
+        return { ok: false, status: res.status, error: `HTTP ${res.status}` };
+      }
+      const json = await res.json();
+      const total = json?.data?.totalBalance !== undefined
+        ? parseFloat(json.data.totalBalance)
+        : (json?.data?.balance !== undefined ? parseFloat(json.data.balance) : 0);
+      const isAvailable = Number.isFinite(total) ? total > 0 : true;
+      return {
+        ok: true,
+        provider: 'siliconflow',
+        total: Number.isFinite(total) ? total : 0,
+        currency: 'CNY',
+        isAvailable,
+      };
+    } catch (err) {
+      return { ok: false, error: String(err?.message || err) };
+    }
+  }
+
+  // 3. OpenRouter
+  if (prov.includes('openrouter')) {
+    try {
+      const url = 'https://openrouter.ai/api/v1/auth/key';
+      const ac = new AbortController();
+      const timer = setTimeout(() => ac.abort(), timeoutMs);
+      const res = await fetchImpl(url, {
+        method: 'GET',
+        headers: {
+          'Authorization': `Bearer ${apiKey.trim()}`,
+          'Accept': 'application/json',
+        },
+        signal: signal ?? ac.signal,
+      });
+      clearTimeout(timer);
+      if (!res.ok) {
+        return { ok: false, status: res.status, error: `HTTP ${res.status}` };
+      }
+      const json = await res.json();
+      const limit = json?.data?.limit;
+      const usage = json?.data?.usage ?? 0;
+      const total = limit != null ? Math.max(0, limit - usage) : null;
+      return {
+        ok: true,
+        provider: 'openrouter',
+        total: total != null ? total : 999,
+        currency: 'USD',
+        isAvailable: total == null || total > 0,
+      };
+    } catch (err) {
+      return { ok: false, error: String(err?.message || err) };
+    }
+  }
+
+  // 4. OpenAI Credit Grants
+  if (prov.includes('openai')) {
+    try {
+      const url = 'https://api.openai.com/v1/dashboard/billing/credit_grants';
+      const ac = new AbortController();
+      const timer = setTimeout(() => ac.abort(), timeoutMs);
+      const res = await fetchImpl(url, {
+        method: 'GET',
+        headers: {
+          'Authorization': `Bearer ${apiKey.trim()}`,
+          'Accept': 'application/json',
+        },
+        signal: signal ?? ac.signal,
+      });
+      clearTimeout(timer);
+      if (!res.ok) {
+        return { ok: false, status: res.status, error: `HTTP ${res.status}` };
+      }
+      const data = await res.json();
+      const total = parseFloat(data?.total_available ?? 0);
+      return {
+        ok: true,
+        provider: 'openai',
+        total: Number.isFinite(total) ? total : 0,
+        currency: 'USD',
+        isAvailable: total > 0,
+      };
+    } catch (err) {
+      return { ok: false, error: String(err?.message || err) };
+    }
+  }
+
+  return { ok: false, error: `Provider '${provider}' does not support balance inspection` };
+}
+
+/**
+ * Resolve credential and inspect balance for a given ref.
+ */
+export async function inspectBalanceForRef(ctx, ref, provider, { testValue, fetchImpl, timeoutMs } = {}) {
+  const base = ctx.get('credentials');
+  let hit = await (base?.__dshKeyRotationOriginalResolve ?? base?.resolve)?.call(base, ref);
+  let rawValue = testValue || hit?.value;
+  if (!rawValue && process.env[ref]) rawValue = process.env[ref];
+  if (typeof rawValue === 'string' && rawValue.startsWith('enc:v1:')) {
+    rawValue = decryptSecret(rawValue);
+  }
+  if (!rawValue) return { ok: false, error: 'no credential' };
+  return checkProviderBalance(provider, rawValue, { fetchImpl, timeoutMs });
+}