@goodandready/dsh-key-rotation 0.8.37 → 0.8.39

package/CHANGELOG.md

@@ -1,12 +1,41 @@
 # Changelog
 
+## 0.8.39 - 2026-09-30
+
+### Fixed
+- **SSRF guard: IPv4-mapped IPv6 loopbacks & connect-time rebinding (#411)**:
+  - Blocked hex (`::ffff:7f00:1`, `::ffff:7f00:0001`), dotted (`::ffff:127.0.0.1`), IPv4-compatible (`::/96`), and NAT64 (`64:ff9b::/96`) loopback addresses via full 8-word IPv6 unpacking in `lib/safe-fetch.js`.
+  - Added connect-time DNS resolution enforcement using `undici.Agent` lookup hook to prevent TOCTOU DNS rebinding before establishing socket connections.
+- **Fail-closed credential resolver on pool exhaustion (#406)**:
+  - Return fail-closed error `LOCAL_POOL_EXHAUSTED` instead of leaking unmanaged `original(ref)` when all credentials in a managed pool are exhausted or blocked by cooldown, expiry, RPM, or TPM.
+- **Credential status inheritance & permanent auth revocation (#408)**:
+  - Model sub-pools inherit `paused`, `revoked`, and `expiresAt` credentials from their parent base provider pool.
+  - Runtime 401 permanent auth failure marks credential as revoked (`revokedRefs.add` and `failedUntil = Infinity`) across all associated pools sharing the ref.
+- **Persistence of revocation state and spend counters (#409)**:
+  - `StatePersistence` serializes and restores `revokedRefs` (as a Set), `Infinity` failedUntil timestamps, and daily usage/cost aggregation maps (`costDays`, `costPerKey`, `usageDays`, `usageCounts`).
+- **UI credential alignment and model weights on reordering (#412)**:
+  - Preserved `paused` and `revoked` flag alignment with credential references during reordering, deletion, and undo actions in the settings card.
+  - Model pool key reordering preserves model-specific weights and expiry mappings.
+
+## 0.8.38 - 2026-09-30
+
+### Added
+- **Sliding-Window TPM (Tokens Per Minute) Rate Limiting (#402, GH #20)**:
+  - Added 60-second sliding-window TPM rate-limiting alongside existing RPM (`tpmAllow`, `tpmRecord`, `tpmRetryMs`, `tpmSweep`, `tpmInfo` in `lib/bucket.js`).
+  - Added `tpmLimit` configuration at global, provider, and per-model scopes in `lib/index.js` and `lib/pool-builder.js`.
+  - Automatically records consumed tokens on streaming and non-streaming responses in `lib/rotate.js`.
+  - Enforced fail-over and cooldown in `lib/resolver.js` when candidate key exceeds its configured TPM budget.
+  - Exposed live TPM telemetry (`used`, `remaining`, `limit`, `resetMs`) in `GET /dsh-key-rotation/status` with sanitization in `lib/sanitize-snapshot.js`.
+  - Added visual UI badge and editable TPM limit input in `lib/client-src/50-card-main.js` with localization (`en`, `zh`).
+  - Added automated test suite `test/tpm-rate-limit.test.mjs` verifying bucket math, sweep cleanup, resolver fail-over, and snapshot sanitization.
+
 ## 0.8.37
 
 ### Fixed
 - **Peer gate on DSH 0.2.0-rc.1** (#58): the bundle was skipped at profile startup because its `peerDependencies` excluded the running version.
 - **Settings card served no form**: `NS` was the package name rather than the profile entry id, `Config` declared no `.volatile()` field, and `getConfig` handed out `Volatile` boxes. Both 0.1.7-rc.2 and 0.2.0 now serve and read the form.
 - **A saved setting never took effect**: the host applied changes through `settings.register` and `scope.watch`, neither of which exists in either release. Changes are applied on `loader/volatile-update` now.
-- **`settings.plugin.item` registration removed**: retired before DSH 0.1.7-rc.2, so it only registered the card a second time on a seat that no longer exists.
+- **`settings.plugin.item` registration removed**: retired before DSH 0.1.7-rc.2, it only registered the card a second time on a seat that no longer exists.
 
 ## 0.8.36
 

package/README.md

@@ -207,7 +207,9 @@ Access full visual management under **Settings → Key Rotation** or via the Hea
 * **Secure Vault Storage**: Actual secret values reside securely in `$DSH_HOME/.credentials.yaml` managed by the DSH `Credentials` service.
 * **5-Character Masking (`keyTail`)**: Full secret values are never sent to the client browser; only the trailing 5 characters are exposed for visual identification. Short keys (<= 5 characters) return a fixed masked placeholder (`***`) to prevent credential disclosure.
 * **Fail-Closed Loopback & Same-Origin Fencing**: Administrative endpoints strictly enforce loopback origin checks (`isTrustedBridgeRequest`), requiring valid `Origin` headers, matching `Host` headers, and rejecting `cross-site` or non-loopback requests without fallbacks.
-* **SSRF Guard on Import Route**: Remote provider pool import strictly enforces HTTPS-only URLs, validates all resolved IP addresses against private and reserved ranges (RFC 1918, loopback, link-local, multicast, CGNAT), verifies redirect targets, and caps response payload size to 1 MB.
+* **Fail-Closed Resolver on Pool Exhaustion**: When all credentials in a managed pool are exhausted, paused, expired, or blocked by RPM/TPM limits, the resolver fails closed with `LOCAL_POOL_EXHAUSTED` error rather than falling back to leaking unmanaged credentials.
+* **SSRF Protection & Rebinding Guard**: Remote provider pool import strictly enforces HTTPS-only URLs, validates all resolved IP addresses including IPv4-mapped and IPv4-compatible IPv6 addresses (`::ffff:127.0.0.1`, `::ffff:7f00:1`, `64:ff9b::/96`), and enforces connect-time DNS validation via undici agent dispatchers to prevent TOCTOU DNS rebinding.
+* **Cross-Pool Revocation & Inheritance**: Model pools automatically inherit pause, revoke, and expiry states from their base provider; runtime 401 permanent authentication failures revoke the credential across all shared pools immediately.
 
 ---
 

package/README.ru.md

@@ -194,7 +194,9 @@ graph LR
 * **Защищённое хранилище хоста**: Реальные значения ключей сохраняются в `$DSH_HOME/.credentials.yaml` сервисом `Credentials`.
 * **Маскировка в браузере (5 символов)**: Браузер получает только последние 5 символов ключа для визуального отличия. Для коротких ключей (длиной <= 5 символов) возвращается безопасная маскировочная заглушка `***`, исключающая раскрытие ключа целиком.
 * **Fail-Closed изоляция Loopback и Same-Origin**: Все управляющие эндпоинты строго проверяют происхождение через `isTrustedBridgeRequest`, требуя обязательный заголовок `Origin`, соответствие `Host` и отклоняя запросы `cross-site` и не-loopback без каких-либо исключений.
-* **SSRF-защита маршрута импорта**: Маршрут импорта пулов провайдеров разрешает исключительно HTTPS, валидирует все резолвящиеся IP-адреса с блокировкой приватных и зарезервированных диапазонов (RFC 1918, loopback, link-local, multicast, CGNAT), проверяет адреса редиректов и ограничивает размер ответа 1 МБ.
+* **Fail-Closed резолвер при исчерпании пула**: Если все ключи в пуле исчерпаны, приостановлены, истекли или заблокированы по RPM/TPM, резолвер завершается с ошибкой `LOCAL_POOL_EXHAUSTED`, исключая скрытую утечку исходного неконтролируемого ключа.
+* **SSRF-защита и блокировка DNS Rebinding**: Маршрут импорта пулов провайдеров разрешает исключительно HTTPS, валидирует все IP-адреса, включая IPv4-mapped и IPv4-compatible IPv6 представления (`::ffff:127.0.0.1`, `::ffff:7f00:1`, `64:ff9b::/96`), и выполняет проверку адреса в момент соединения (connect-time DNS validation) через диспетчер undici для защиты от TOCTOU DNS rebinding.
+* **Сквозной отзыв и наследование статусов**: Пул конкретной модели автоматически наследует флаги паузы, отзыва и срок действия базового провайдера; перманентный сбой аутентификации 401 немедленно отзывает ключ во всех связанных пулах.
 
 ---
 

package/README.zh.md

@@ -186,7 +186,9 @@ graph LR
 * **宿主安全存储**：真实密钥持久化保存在 `$DSH_HOME/.credentials.yaml`。
 * **前台 5 字符脱敏**：前端仅展示密钥后 5 位字符进行视觉区分。对于长度 <= 5 的短密钥，返回统一脱敏占位符 (`***`)，防止凭证完整泄露。
 * **Fail-Closed 环回同源安全隔离**：管理接口严格通过 `isTrustedBridgeRequest` 验证本地同源请求，强制要求有效 `Origin` 和 `Host` 匹配，无条件拒绝跨站 (`cross-site`) 与非环回调用。
-* **导入接口 SSRF 防护**：远程提供商配置导入严格仅支持 HTTPS，解析并拦截所有私有/保留 IP 地址（RFC 1918、环回、链路本地、多播、CGNAT），对重定向目标进行全程验证，并将响应体上限严格控制在 1 MB 以内。
+* **凭证池耗尽 Fail-Closed 熔断**：当受管凭证池中所有密钥均被耗尽、暂停、过期或触发 RPM/TPM 限制时，解析器立即返回 `LOCAL_POOL_EXHAUSTED` 错误熔断，杜绝静默回退泄漏未受控原始密钥。
+* **SSRF 与 DNS 重绑定防护**：远程配置导入严格仅支持 HTTPS，全面校验解析 IP 并拦截 IPv4-mapped/IPv4-compatible 等各类 IPv6 环回变体（如 `::ffff:127.0.0.1`、`::ffff:7f00:1`、`64:ff9b::/96`），并通过 undici 调度器执行连接时（connect-time）DNS 校验，从根本上防御 TOCTOU DNS 重绑定。
+* **跨池吊销与状态继承**：模型子池自动继承基础提供商的暂停、吊销与过期时间；运行时 401 永久认证失败将即时在所有关联共享池中统一标记吊销。
 
 ---
 

package/lib/bucket.js

@@ -41,3 +41,64 @@ export function bucketInfo(windows, ref, limit, now = Date.now()) {
   };
 }
 
+
+/** Sliding-window check: true if `ref` is under `limit` tokens/min. */
+export function tpmAllow(windows, ref, limit, now = Date.now()) {
+  if (!limit || limit <= 0) return true;
+  const cut = now - WINDOW_MS;
+  const entries = (windows?.get(ref) ?? []).filter((e) => e.time > cut);
+  let total = 0;
+  for (const e of entries) total += e.tokens;
+  return total < limit;
+}
+
+/** Record actual consumed tokens for `ref` in sliding 60s window. */
+export function tpmRecord(windows, ref, tokens, now = Date.now()) {
+  if (!tokens || tokens <= 0 || !windows) return;
+  const cut = now - WINDOW_MS;
+  const validTokens = Math.max(1, Math.floor(tokens));
+  const entries = (windows.get(ref) ?? []).filter((e) => e.time > cut);
+  entries.push({ time: now, tokens: validTokens });
+  windows.set(ref, entries);
+}
+
+/** ms until `ref` may retry again under TPM limit (0 = now). */
+export function tpmRetryMs(windows, ref, limit, now = Date.now()) {
+  if (!limit || limit <= 0) return 0;
+  const cut = now - WINDOW_MS;
+  const entries = (windows?.get(ref) ?? []).filter((e) => e.time > cut);
+  let total = 0;
+  for (const e of entries) total += e.tokens;
+  if (total < limit) return 0;
+  let rem = total;
+  for (const e of entries) {
+    rem -= e.tokens;
+    if (rem < limit) {
+      return Math.max(0, e.time + WINDOW_MS - now);
+    }
+  }
+  return WINDOW_MS;
+}
+
+/** Drop TPM state for refs that no longer exist. */
+export function tpmSweep(windows, liveRefs) {
+  if (!windows) return;
+  for (const ref of [...windows.keys()]) {
+    if (!liveRefs.has(ref)) windows.delete(ref);
+  }
+}
+
+/** Snapshot for /status - used/remaining/limit/resetMs for one ref. */
+export function tpmInfo(windows, ref, limit, now = Date.now()) {
+  if (!limit || limit <= 0) return null;
+  const cut = now - WINDOW_MS;
+  const entries = (windows?.get(ref) ?? []).filter((e) => e.time > cut);
+  let used = 0;
+  for (const e of entries) used += e.tokens;
+  return {
+    used,
+    remaining: Math.max(0, limit - used),
+    limit,
+    resetMs: used >= limit ? tpmRetryMs(windows, ref, limit, now) : 0,
+  };
+}

package/lib/client.js

@@ -117,6 +117,9 @@ window.__ModuleLoader__.load({
       keyWriteFailed: 'could not store the key: {msg}',
       notSecretShape: 'saved, but the value does not look like an API key - check for a typo',
       rpmTitle: 'requests/min: {u} used, {r} remaining',
+      tpmTitle: 'tokens/min: {u} used, {r} remaining',
+      rpmLimitLabel: 'Rate Limit (RPM)',
+      tpmLimitLabel: 'Rate Limit (TPM)',
       budgetLabel: 'budget:',
       exportCsv: 'Export CSV',
       weightHint: 'round-robin weight: how many times this key joins the cycle (1 = equal share)',
@@ -299,6 +302,9 @@ window.__ModuleLoader__.load({
       keyWriteFailed: '无法存储密钥: {msg}',
       notSecretShape: '已保存，但该值看起来不像 API 密钥 - 请检查是否有拼写错误',
       rpmTitle: '请求/分钟: 已用 {u}, 剩余 {r}',
+      tpmTitle: 'Token/分钟: 已用 {u}, 剩余 {r}',
+      rpmLimitLabel: '速率限制 (RPM)',
+      tpmLimitLabel: '速率限制 (TPM)',
       budgetLabel: '预算:',
       exportCsv: '导出 CSV',
       weightHint: '轮换权重：该密钥参与循环的次数 (1 = 等分)',
@@ -932,7 +938,7 @@ window.__ModuleLoader__.load({
 
     function reorderKeys(entry, order) {
       const next = { ...entry, keys: order.map(index => entry.keys[index]) };
-      for (const [field, fallback] of [['weights', 1], ['expiresAt', 0]]) {
+      for (const [field, fallback] of [['weights', 1], ['expiresAt', 0], ['paused', false], ['revoked', false]]) {
         if (Array.isArray(entry[field]) && entry[field].length) next[field] = order.map(index => entry[field][index] ?? fallback);
       }
       return next;
@@ -1207,7 +1213,7 @@ window.__ModuleLoader__.load({
             const entry = { ...providers[index] };
             const at = Math.min(u.kIndex, entry.keys.length);
             entry.keys = [...entry.keys]; entry.keys.splice(at, 0, u.key);
-            for (const [field, fallback] of [['weights', 1], ['expiresAt', 0]]) {
+            for (const [field, fallback] of [['weights', 1], ['expiresAt', 0], ['paused', false], ['revoked', false]]) {
               if (u[field] !== undefined || entry[field]?.length) {
                 const values = Array.from({ length: entry.keys.length - 1 }, (_, i) => entry[field]?.[i] ?? fallback);
                 values.splice(at, 0, u[field] ?? fallback); entry[field] = values;
@@ -1557,7 +1563,7 @@ window.__ModuleLoader__.load({
         const allRefs = providers.flatMap((prov) => prov?.keys ?? []);
         entry.keys = [...(entry.keys ?? []), nextKeyRef(entry.provider, entry.keys, allRefs)];
         // keep weights aligned with keys (#215): new key gets default weight 1
-        for (const [field, fallback] of [['weights', 1], ['expiresAt', 0]]) {
+        for (const [field, fallback] of [['weights', 1], ['expiresAt', 0], ['paused', false], ['revoked', false]]) {
           if (Array.isArray(entry[field]) && entry[field].length) entry[field] = Array.from({ length: entry.keys.length }, (_, i) => entry[field][i] ?? fallback);
         }
         providers[pIndex] = entry;
@@ -1568,7 +1574,8 @@ window.__ModuleLoader__.load({
         const entry = next[pIndex];
         if (!entry || !entry.keys[kIndex]) return cur;
         stashUndo({ type: 'key', provider: entry.provider, kIndex, key: entry.keys[kIndex],
-          weights: entry.weights?.[kIndex], expiresAt: entry.expiresAt?.[kIndex] });
+          weights: entry.weights?.[kIndex], expiresAt: entry.expiresAt?.[kIndex],
+          paused: entry.paused?.[kIndex], revoked: entry.revoked?.[kIndex] });
         next[pIndex] = reorderKeys(entry, entry.keys.map((_, index) => index).filter(index => index !== kIndex));
         return { ...cur, providers: next };
       });
@@ -1685,9 +1692,9 @@ window.__ModuleLoader__.load({
         const keys = Array.isArray(mp.keys) ? [...mp.keys] : [];
         const target = kIndex + delta;
         if (target < 0 || target >= keys.length) return;
-        [keys[kIndex], keys[target]] = [keys[target], keys[kIndex]];
-        mp.keys = keys;
-        models[model] = mp;
+        const order = keys.map((_, i) => i);
+        [order[kIndex], order[target]] = [order[target], order[kIndex]];
+        models[model] = reorderKeys(mp, order);
       });
 
       const save = async () => {
@@ -1918,6 +1925,11 @@ window.__ModuleLoader__.load({
             title: t('rpmTitle').replace('{u}', String(info.rpm.used)).replace('{r}', String(info.rpm.remaining)),
             style: info.rpm.remaining === 0 ? { color: 'var(--dsw-alias-state-error-primary)', fontWeight: 700 } : undefined },
             '⏱' + info.rpm.remaining));
+          // TPM capacity indicator (only when tpmLimit is active)
+          if (info && info.tpm) meta.push(h('span', { key: 'tpm', className: 'krot-tail',
+            title: t('tpmTitle').replace('{u}', String(info.tpm.used)).replace('{r}', String(info.tpm.remaining)),
+            style: info.tpm.remaining === 0 ? { color: 'var(--dsw-alias-state-error-primary)', fontWeight: 700 } : undefined },
+            '⚡' + info.tpm.remaining));
           if (info && typeof info.cost === 'number' && info.cost > 0) meta.push(h('span', { key: 'c', className: 'krot-tail', title: 'cost' }, '$' + info.cost.toFixed(2)));
           const tr = testResult[key];
           if (tr) meta.push(h('span', { key: 'tr', className: 'krot-tail',
@@ -2393,6 +2405,10 @@ window.__ModuleLoader__.load({
           field(t('cooldown'), textInput(String(val.cooldownMs ?? 60000), (v) => setField((cur) => ({ ...cur, cooldownMs: Number(v) || 0 })))),
           field(t('scheduleDays'), textInput(String(val.rotationScheduleDays ?? 0), (v) => setField((cur) => ({ ...cur, rotationScheduleDays: Number(v) || 0 }))))
         ),
+        h('div', { className: 'krot-grid-2', style: { marginTop: '10px' } },
+          field(t('rpmLimitLabel'), textInput(String(val.rpmLimit ?? 0), (v) => setField((cur) => ({ ...cur, rpmLimit: Number(v) || 0 })))),
+          field(t('tpmLimitLabel'), textInput(String(val.tpmLimit ?? 0), (v) => setField((cur) => ({ ...cur, tpmLimit: Number(v) || 0 }))))
+        ),
         h('div', { className: 'krot-grid-3', style: { marginTop: '10px' } },
           field(t('routingStrategyLabel'), h('select', {
             className: 'krot-in',

package/lib/index.js

@@ -52,6 +52,17 @@ export { keyTail, KEY_TAIL_CHARS, KEY_TAIL_PLACEHOLDER, isLoopbackAddress, isTru
 export { notifySwitch, notifyExhaustion };
 
 const NS = 'dsh-key-rotation';
+
+// DSH serves a namespace's settings form from the volatile fields of its profile
+// entry schema, and a volatile field holds a Volatile box rather than its value.
+// Unwrap before any caller reads one, and read lazily: the Loader mutates the
+// boxes in place and re-announces them with loader/volatile-update.
+export function plainConfig(value) {
+  if (value === null || typeof value !== 'object') return value
+  if (Array.isArray(value)) return value.map(plainConfig)
+  if (typeof value.get === 'function') return plainConfig(value.get())
+  return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, plainConfig(v)]))
+}
 const CONFIG_PATH = '/dsh-key-rotation/config';
 const PIAI_NS = 'llm-pi-ai';
 const MARKER = '__dshKeyRotation';
@@ -107,6 +118,7 @@ const SettingsSchema = Schema.object({
   selfHealingIntervalMinutes: Schema.number().default(30),
   routingStrategy: Schema.union(['round-robin', 'least-loaded', 'lowest-latency']).default('round-robin'),
   rpmLimit: Schema.number().default(0),
+  tpmLimit: Schema.number().default(0),
   webhookActionToken: Schema.string().role('secret').default(''),
   expiryWarnDays: Schema.number().default(7),
   switchNotify: Schema.boolean().default(false),
@@ -137,11 +149,15 @@ const SettingsSchema = Schema.object({
       quotas: Schema.dict(Schema.object({
         tokenLimit: Schema.number(),
       })).default({}),
+      rpmLimit: Schema.number(),
+      tpmLimit: Schema.number(),
     })).default({}),
     cooldownMs: Schema.number(),
     maxCooldownMs: Schema.number(),
     routingStrategy: Schema.union(['round-robin', 'least-loaded', 'lowest-latency']),
     proactiveRateLimitGuard: Schema.boolean(),
+    rpmLimit: Schema.number(),
+    tpmLimit: Schema.number(),
   })).default([...DEFAULT_PROVIDERS]),
 });
 
@@ -233,17 +249,20 @@ export function apply(ctx, config = {}) {
   let lastProfilesRef = null;
 
   function buildRuntime() {
-    const cfg = getConfig() ?? {};
+    const rawConfig = getConfig();
+    // Identity check below stays on the raw object: plainConfig allocates a new
+    // object each call, which would defeat the runtime memo cache.
+    const cfg = plainConfig(rawConfig ?? {});
     let profilesSnapshot = null;
     try {
       profilesSnapshot = readProfiles();
     } catch {
       profilesSnapshot = null;
     }
-    if (cachedRuntime && cfg === lastConfigRef && profilesSnapshot === lastProfilesRef) {
+    if (cachedRuntime && rawConfig === lastConfigRef && profilesSnapshot === lastProfilesRef) {
       return cachedRuntime;
     }
-    lastConfigRef = cfg;
+    lastConfigRef = rawConfig;
     lastProfilesRef = profilesSnapshot;
 
     moduleBreaker.configure({
@@ -261,6 +280,7 @@ export function apply(ctx, config = {}) {
     const quotaResetWindow = cfg.quotaResetWindow ?? { type: 'midnight_utc', hour: 0 };
     const rateLimitThreshold = cfg.rateLimitThreshold ?? 0.1;
     const rpmLimit = cfg.rpmLimit ?? 0;
+    const tpmLimit = cfg.tpmLimit ?? 0;
     const webhookActionToken = cfg.webhookActionToken ?? '';
 
     const built = buildPools({ cfg, poolState, defaultState: initializePoolState });
@@ -306,7 +326,7 @@ export function apply(ctx, config = {}) {
 
     cachedRuntime = {
       switchCodes, cooldownMs, maxCooldownMs, notifyWebhook, notifyThreshold,
-      concurrencyLimit, cascade, quotaResetWindow, rateLimitThreshold, rpmLimit,
+      concurrencyLimit, cascade, quotaResetWindow, rateLimitThreshold, rpmLimit, tpmLimit,
       webhookActionToken, expiryWarnDays: cfg.expiryWarnDays ?? 7,
       switchNotify: cfg.switchNotify ?? false, verboseLogging: cfg.verboseLogging ?? false,
       proactiveRateLimitGuard: cfg.proactiveRateLimitGuard ?? true,
@@ -362,7 +382,7 @@ export function apply(ctx, config = {}) {
   let _rotateStartMs = Date.now();
   function recordLatency(pool, reqStore) {
     try {
-      const cfg = getConfig();
+      const cfg = plainConfig(getConfig());
       if (!cfg || cfg.latencyEnabled === false) return;
       const ref = reqStore?.pickedRef ?? pool?.state?.lastUsed;
       if (!ref) return;

package/lib/ops-status.js

@@ -13,7 +13,7 @@ import {
   costForWeek,
   isLoopbackAddress,
 } from './pool.js';
-import { bucketInfo } from './bucket.js';
+import { bucketInfo, tpmInfo } from './bucket.js';
 import { sanitizeSnapshot } from './sanitize-snapshot.js';
 import {
   STATUS_PATH,
@@ -101,6 +101,8 @@ ctx.effect(() => ctx.webServer.register({
           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),
+          // TPM capacity snapshot (null when tpmLimit is off)
+          tpm: tpmInfo(pool.state.tpmWindows, ref, pool.tpmLimit, now),
           // #215: effective round-robin weight of this key
           weight: pool.weights?.[pool.refs.indexOf(ref)] ?? 1,
           usage: pool.state.usageCounts?.get(ref) ?? 0,

package/lib/persistence.js

@@ -33,8 +33,17 @@ export class StatePersistence {
         if (st && st.failedUntil && typeof st.failedUntil.forEach === 'function') {
           st.failedUntil.forEach((until, ref) => {
             if (Number.isFinite(until)) failedUntil[ref] = until;
+            else if (until === Infinity) failedUntil[ref] = 'Infinity';
           });
         }
+        const revokedRefs = [];
+        if (st && st.revokedRefs) {
+          if (typeof st.revokedRefs.forEach === 'function') {
+            st.revokedRefs.forEach((r) => revokedRefs.push(r));
+          } else if (Array.isArray(st.revokedRefs)) {
+            revokedRefs.push(...st.revokedRefs);
+          }
+        }
         const tokenUsage = {};
         if (st && st.tokenUsage && typeof st.tokenUsage.forEach === 'function') {
           st.tokenUsage.forEach((entry, ref) => {
@@ -45,14 +54,38 @@ export class StatePersistence {
             tokenUsage[ref] = { used: Math.floor(used), resetAt: Math.floor(resetAt) };
           });
         }
+        const costDays = {};
+        if (st?.costDays) {
+          const src = st.costDays instanceof Map ? Object.fromEntries(st.costDays) : st.costDays;
+          if (typeof src === 'object' && src !== null) Object.assign(costDays, src);
+        }
+        const costPerKey = {};
+        if (st?.costPerKey) {
+          const src = st.costPerKey instanceof Map ? Object.fromEntries(st.costPerKey) : st.costPerKey;
+          if (typeof src === 'object' && src !== null) Object.assign(costPerKey, src);
+        }
+        const usageDays = {};
+        if (st?.usageDays) {
+          const src = st.usageDays instanceof Map ? Object.fromEntries(st.usageDays) : st.usageDays;
+          if (typeof src === 'object' && src !== null) Object.assign(usageDays, src);
+        }
+        const usageCounts = {};
+        if (st?.usageCounts instanceof Map) {
+          st.usageCounts.forEach((cnt, ref) => {
+            if (Number.isFinite(cnt)) usageCounts[ref] = cnt;
+          });
+        }
         const outPool = {
           failedUntil,
           pointer: Number.isFinite(st?.pointer) ? st.pointer : 0,
           lastUsed: typeof st?.lastUsed === 'string' ? st.lastUsed : null,
         };
-        if (Object.keys(tokenUsage).length > 0) {
-          outPool.tokenUsage = tokenUsage;
-        }
+        if (revokedRefs.length > 0) outPool.revokedRefs = revokedRefs;
+        if (Object.keys(tokenUsage).length > 0) outPool.tokenUsage = tokenUsage;
+        if (Object.keys(costDays).length > 0) outPool.costDays = costDays;
+        if (Object.keys(costPerKey).length > 0) outPool.costPerKey = costPerKey;
+        if (Object.keys(usageDays).length > 0) outPool.usageDays = usageDays;
+        if (Object.keys(usageCounts).length > 0) outPool.usageCounts = usageCounts;
         pools[base] = outPool;
       });
     }
@@ -109,7 +142,7 @@ export class StatePersistence {
   async load() {
     const raw = await safeReadJson(this.filePath, null);
     if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
-    if (raw.version !== 1) return null;
+    if (raw.version !== 1 && raw.version !== 2) return null;
     return raw;
   }
 
@@ -126,7 +159,17 @@ export class StatePersistence {
       if (!existing || !hasPoolActivity(state)) {
         if (saved.failedUntil && typeof saved.failedUntil === 'object' && !Array.isArray(saved.failedUntil)) {
           for (const [ref, until] of Object.entries(saved.failedUntil)) {
-            if (Number.isFinite(until)) state.failedUntil.set(ref, until);
+            if (until === 'Infinity' || until === Infinity) {
+              state.failedUntil.set(ref, Infinity);
+            } else if (Number.isFinite(until)) {
+              state.failedUntil.set(ref, until);
+            }
+          }
+        }
+        if (Array.isArray(saved.revokedRefs)) {
+          if (!state.revokedRefs) state.revokedRefs = new Set();
+          for (const r of saved.revokedRefs) {
+            if (typeof r === 'string') state.revokedRefs.add(r);
           }
         }
         if (saved.tokenUsage && typeof saved.tokenUsage === 'object' && !Array.isArray(saved.tokenUsage)) {
@@ -139,6 +182,30 @@ export class StatePersistence {
             state.tokenUsage.set(ref, { used: Math.floor(used), resetAt: Math.floor(resetAt) });
           }
         }
+        if (saved.costDays && typeof saved.costDays === 'object') {
+          if (!state.costDays) state.costDays = new Map();
+          for (const [day, cost] of Object.entries(saved.costDays)) {
+            if (Number.isFinite(cost)) state.costDays.set(day, cost);
+          }
+        }
+        if (saved.costPerKey && typeof saved.costPerKey === 'object') {
+          if (!state.costPerKey) state.costPerKey = new Map();
+          for (const [k, c] of Object.entries(saved.costPerKey)) {
+            if (Number.isFinite(c)) state.costPerKey.set(k, c);
+          }
+        }
+        if (saved.usageDays && typeof saved.usageDays === 'object') {
+          if (!state.usageDays) state.usageDays = new Map();
+          for (const [d, u] of Object.entries(saved.usageDays)) {
+            if (Number.isFinite(u)) state.usageDays.set(d, u);
+          }
+        }
+        if (saved.usageCounts && typeof saved.usageCounts === 'object') {
+          if (!state.usageCounts) state.usageCounts = new Map();
+          for (const [k, cnt] of Object.entries(saved.usageCounts)) {
+            if (Number.isFinite(cnt)) state.usageCounts.set(k, cnt);
+          }
+        }
         state.pointer = Number.isSafeInteger(saved.pointer) && saved.pointer >= 0 ? saved.pointer : 0;
         state.lastUsed = typeof saved.lastUsed === 'string' ? saved.lastUsed : null;
       }

package/lib/pool-builder.js

@@ -1,5 +1,5 @@
 // lib/pool-builder.js — provider & per-model pool assembly and cleanup
-import { bucketSweep } from './bucket.js';
+import { bucketSweep, tpmSweep } from './bucket.js';
 import { isValidRef } from './pool.js';
 import { normalizeModelQuotas } from './model-quota.js';
 import { createPoolIndex, addProviderPools } from './pool-index.js';
@@ -26,6 +26,7 @@ export function buildPoolItem({
   poolStrategy,
   poolGuard,
   rpmLimit,
+  tpmLimit = 0,
   makeState,
   provider = null,
   model = null,
@@ -52,17 +53,30 @@ export function buildPoolItem({
       const exp = parseExpiry(expiresAt[indexed[i].index]);
       if (exp !== undefined) parsedExpiry[refs[i]] = exp;
     }
+  } else if (expiresAt && typeof expiresAt === 'object') {
+    for (let i = 0; i < refs.length; i++) {
+      const exp = parseExpiry(expiresAt[refs[i]]);
+      if (exp !== undefined) parsedExpiry[refs[i]] = exp;
+    }
   }
   const parsedPaused = new Set();
   if (Array.isArray(paused)) {
     for (let i = 0; i < refs.length; i++) {
-      if (paused[indexed[i].index] === true) parsedPaused.add(refs[i]);
+      if (paused[indexed[i].index] === true || paused.includes(refs[i])) parsedPaused.add(refs[i]);
+    }
+  } else if (paused instanceof Set) {
+    for (let i = 0; i < refs.length; i++) {
+      if (paused.has(refs[i])) parsedPaused.add(refs[i]);
     }
   }
   const parsedRevoked = new Set();
   if (Array.isArray(revoked)) {
     for (let i = 0; i < refs.length; i++) {
-      if (revoked[indexed[i].index] === true) parsedRevoked.add(refs[i]);
+      if (revoked[indexed[i].index] === true || revoked.includes(refs[i])) parsedRevoked.add(refs[i]);
+    }
+  } else if (revoked instanceof Set) {
+    for (let i = 0; i < refs.length; i++) {
+      if (revoked.has(refs[i])) parsedRevoked.add(refs[i]);
     }
   }
   const weightsMap = {};
@@ -88,6 +102,7 @@ export function buildPoolItem({
     maxCooldownMs: poolMax,
     expiresAt: parsedExpiry,
     rpmLimit,
+    tpmLimit: typeof tpmLimit === 'number' && Number.isFinite(tpmLimit) && tpmLimit > 0 ? Math.floor(tpmLimit) : 0,
     routingStrategy: poolStrategy,
     proactiveRateLimitGuard: poolGuard,
   };
@@ -95,6 +110,7 @@ export function buildPoolItem({
 
 export function buildPools({ cfg = {}, poolState = new Map(), defaultState = initializePoolState } = {}) {
   const rpmLimit = cfg.rpmLimit ?? 0;
+  const tpmLimit = cfg.tpmLimit ?? 0;
   const quotaResetWindow = cfg.quotaResetWindow ?? null;
   const poolByRef = new Map();
   const providerToPool = new Map();
@@ -111,19 +127,21 @@ export function buildPools({ cfg = {}, poolState = new Map(), defaultState = ini
     return initializePoolState(st);
   };
 
-  const buildPool = (base, keys, weights, paused, revoked, poolCooldown, poolMax, expiresAt, poolStrategy, poolGuard, meta) =>
+  const buildPool = (base, keys, weights, paused, revoked, poolCooldown, poolMax, expiresAt, poolStrategy, poolGuard, meta, pRpm = rpmLimit, pTpm = tpmLimit) =>
     buildPoolItem({
       base, keys, weights, paused, revoked, poolCooldown, poolMax, expiresAt, poolStrategy, poolGuard,
-      rpmLimit, makeState, quotaResetWindow, ...meta,
+      rpmLimit: pRpm, tpmLimit: pTpm, makeState, quotaResetWindow, ...meta,
     });
 
   for (const p of cfg.providers ?? []) {
     const poolCooldown = typeof p.cooldownMs === 'number' ? p.cooldownMs : (cfg.cooldownMs ?? 60000);
     const poolMax = typeof p.maxCooldownMs === 'number' ? p.maxCooldownMs : (cfg.maxCooldownMs ?? undefined);
+    const provRpm = typeof p.rpmLimit === 'number' ? p.rpmLimit : rpmLimit;
+    const provTpm = typeof p.tpmLimit === 'number' ? p.tpmLimit : tpmLimit;
     const pool = buildPool(p.provider, p.keys, p.weights, p.paused, p.revoked, poolCooldown, poolMax, p.expiresAt, p.routingStrategy, p.proactiveRateLimitGuard, {
       provider: p.provider,
       model: null,
-    });
+    }, provRpm, provTpm);
     if (pool) {
       for (const ref of pool.refs) {
         if (!poolByRef.has(ref)) poolByRef.set(ref, pool);
@@ -133,12 +151,24 @@ export function buildPools({ cfg = {}, poolState = new Map(), defaultState = ini
     }
     const byModel = new Map();
     for (const [model, mp] of Object.entries(p.models ?? {})) {
-      const mpool = buildPool(`${p.provider}::${model}`, mp.keys, mp.weights, mp.paused, mp.revoked, poolCooldown, poolMax, undefined, p.routingStrategy, p.proactiveRateLimitGuard, {
+      const modelRpm = typeof mp.rpmLimit === 'number' ? mp.rpmLimit : provRpm;
+      const modelTpm = typeof mp.tpmLimit === 'number' ? mp.tpmLimit : provTpm;
+      const mergedPaused = new Set([
+        ...(pool?.pausedRefs ?? []),
+        ...(Array.isArray(mp.paused) ? mp.paused : (mp.paused instanceof Set ? [...mp.paused] : [])),
+      ]);
+      const mergedRevoked = new Set([
+        ...(pool?.revokedRefs ?? []),
+        ...(Array.isArray(mp.revoked) ? mp.revoked : (mp.revoked instanceof Set ? [...mp.revoked] : [])),
+      ]);
+      const modelExpiresAt = { ...(pool?.expiresAt ?? {}), ...(typeof mp.expiresAt === 'object' ? mp.expiresAt : {}) };
+      const mpool = buildPool(`${p.provider}::${model}`, mp.keys, mp.weights, mergedPaused, mergedRevoked, poolCooldown, poolMax, modelExpiresAt, p.routingStrategy, p.proactiveRateLimitGuard, {
         provider: p.provider,
         model,
         quotas: mp.quotas,
-      });
+      }, modelRpm, modelTpm);
       if (!mpool) continue;
+      mpool.basePool = pool;
       byModel.set(model, mpool);
       for (const ref of mpool.refs) {
         if (!poolByRef.has(ref)) poolByRef.set(ref, mpool);
@@ -187,6 +217,7 @@ export function cleanupRemovedProviders({
   }
   for (const st of poolState.values()) {
     if (st.rpmWindows) bucketSweep(st.rpmWindows, liveRefs);
+    if (st.tpmWindows) tpmSweep(st.tpmWindows, liveRefs);
     if (st.tokenUsage instanceof Map) {
       for (const ref of [...st.tokenUsage.keys()]) {
         if (!liveRefs.has(ref)) st.tokenUsage.delete(ref);

package/lib/pool-state.js

@@ -3,7 +3,7 @@
 const MAP_FIELDS = [
   'failedUntil', 'failCounts', 'authFailCounts', 'brokenUntil', 'costPerKey',
   'lastUsedAt', 'usageCounts', 'byModel', 'usageDays', 'quotaWindows', 'costDays',
-  'tokenUsage',
+  'tokenUsage', 'rpmWindows', 'tpmWindows',
 ];
 
 export function initializePoolState(state = {}) {

package/lib/pool.js

@@ -316,6 +316,7 @@ export function isKeyPaused(pool, ref) {
   if (Array.isArray(pool.pausedRefs) && pool.pausedRefs.includes(ref)) return true;
   if (pool.state && pool.state.pausedRefs instanceof Set && pool.state.pausedRefs.has(ref)) return true;
   if (pool.state && Array.isArray(pool.state.pausedRefs) && pool.state.pausedRefs.includes(ref)) return true;
+  if (pool.basePool) return isKeyPaused(pool.basePool, ref);
   return false;
 }
 
@@ -560,5 +561,6 @@ export function isKeyRevoked(pool, ref) {
   if (Array.isArray(pool.revokedRefs) && pool.revokedRefs.includes(ref)) return true;
   if (pool.state && pool.state.revokedRefs instanceof Set && pool.state.revokedRefs.has(ref)) return true;
   if (pool.state && Array.isArray(pool.state.revokedRefs) && pool.state.revokedRefs.includes(ref)) return true;
+  if (pool.basePool) return isKeyRevoked(pool.basePool, ref);
   return false;
 }

package/lib/resolver.js

@@ -9,7 +9,7 @@
 // credentials service. It never sees or returns a secret value itself; it
 // delegates to `original(ref)`.
 
-import { bucketAllow, bucketRetryMs } from './bucket.js';
+import { bucketAllow, bucketRetryMs, tpmAllow, tpmRetryMs } from './bucket.js';
 import { envValue, sortAttemptList, isKeyPaused, isKeyRevoked } from './pool.js';
 import { decryptSecret } from './crypto-storage.js';
 import { resolveRefPool, isQuotaManagedRequest } from './pool-index.js';
@@ -22,6 +22,7 @@ import {
 
 /** Internal failure code for "local budgets forbid this dispatch". */
 export const LOCAL_QUOTA_CODE = 'LOCAL_MODEL_QUOTA_EXHAUSTED';
+export const LOCAL_POOL_EXHAUSTED_CODE = 'LOCAL_POOL_EXHAUSTED';
 
 /**
  * @param {object} deps
@@ -78,7 +79,8 @@ export function createResolver({
       if (isKeyPaused(pool, candidate)) continue;
       const until = pool.state.failedUntil.get(candidate);
       if (until !== undefined && until > at) continue;
-      if (pool.expiresAt?.[candidate] !== undefined && at >= pool.expiresAt[candidate]) continue;
+      const candidateExp = pool.expiresAt?.[candidate] ?? pool.basePool?.expiresAt?.[candidate];
+      if (candidateExp !== undefined && at >= candidateExp) continue;
       // Local model token budget: a spent credential is simply not a candidate.
       // This is deliberately NOT recorded as a failure — the key is healthy and
       // merely out of budget — so it must never touch failedUntil / failCounts /
@@ -95,6 +97,17 @@ export function createResolver({
           continue;
         }
       }
+      const tpmLimit = pool.tpmLimit ?? 0;
+      if (tpmLimit > 0) {
+        if (!pool.state.tpmWindows) pool.state.tpmWindows = new Map();
+        if (!tpmAllow(pool.state.tpmWindows, candidate, tpmLimit, at)) {
+          const waitMs = tpmRetryMs(pool.state.tpmWindows, candidate, tpmLimit, at);
+          if ((pool.state.failedUntil.get(candidate) ?? 0) < at + waitMs) {
+            pool.state.failedUntil.set(candidate, at + waitMs);
+          }
+          continue;
+        }
+      }
       if (pool.perHour) {
         if (!pool.state.quotaWindows) pool.state.quotaWindows = new Map();
         let win = pool.state.quotaWindows.get(candidate);
@@ -133,7 +146,10 @@ export function createResolver({
         { code: LOCAL_QUOTA_CODE, localQuota: true },
       );
     }
-    return original(ref);
+    throw Object.assign(
+      new Error(`dsh-key-rotation: all credentials in pool "${pool.base ?? pool.provider}" are currently blocked, paused, expired, or exhausted`),
+      { code: LOCAL_POOL_EXHAUSTED_CODE, localExhausted: true },
+    );
   };
 }
 

package/lib/rotate.js

@@ -16,6 +16,7 @@ import {
 } from './pool.js';
 import { pickCascadeFallback, CASCADE_MAX_DEPTH } from './cascade.js';
 import { nextQuotaReset } from './quota-window.js';
+import { tpmRecord } from './bucket.js';
 import {
   isModelQuotaAvailable,
   hasModelQuotaConfig,
@@ -209,9 +210,10 @@ export function createRotate(deps) {
               return llm.stream({ ...options, [MARKER]: true });
             });
           } catch (e) {
-            if (e?.localQuota || e?.code === LOCAL_QUOTA_CODE) {
-              lastFailure = finishError(LOCAL_QUOTA_CODE, String(e?.message ?? ''));
-              logWarn(`[dsh-key-rotation] ${options.provider}/${options.model ?? '-'}: local model token budget blocks dispatch — no upstream request sent`);
+            if (e?.localQuota || e?.localExhausted || e?.code === LOCAL_QUOTA_CODE || e?.code === LOCAL_POOL_EXHAUSTED_CODE) {
+              const code = e?.code ?? (e?.localQuota ? LOCAL_QUOTA_CODE : LOCAL_POOL_EXHAUSTED_CODE);
+              lastFailure = finishError(code, String(e?.message ?? ''));
+              logWarn(`[dsh-key-rotation] ${options.provider}/${options.model ?? '-'}: local rejection (${code}) — no upstream request sent`);
               break;
             }
             const curRef = reqStore.pickedRef ?? pool.state.lastUsed;
@@ -302,9 +304,16 @@ export function createRotate(deps) {
                   if (activeRef) {
                     recordSuccess(pool, activeRef, now());
                   }
+                  if (activeRef) {
+                    const usedTokens = extractUsageTokens(chunk?.usage ?? chunk?.metadata?.usage);
+                    if (usedTokens && usedTokens > 0) {
+                      if (!pool.state.tpmWindows) pool.state.tpmWindows = new Map();
+                      tpmRecord(pool.state.tpmWindows, activeRef, usedTokens, Date.now());
+                    }
+                  }
                   if (activeRef && quotaManaged) {
                     const charged = consumeModelTokens(
-                      pool, activeRef, extractUsageTokens(chunk.usage),
+                      pool, activeRef, extractUsageTokens(chunk?.usage ?? chunk?.metadata?.usage),
                       runtime0.quotaResetWindow, Date.now(),
                     );
                     if (charged) {

package/lib/safe-fetch.js

@@ -1,20 +1,57 @@
-// lib/safe-fetch.js — SSRF-protected HTTP fetch with DNS and IP validation (#354).
+// lib/safe-fetch.js — SSRF-protected HTTP fetch with DNS and IP validation (#354, #411).
 import net from 'node:net';
 import dns from 'node:dns/promises';
+import nodeDns from 'node:dns';
+import { Agent } from 'undici';
 
 export const MAX_IMPORT_BYTES = 1024 * 1024; // 1 MB limit
 export const MAX_REDIRECTS = 5;
 
+/**
+ * Parses an IPv6 string into an array of 8 16-bit integers (words).
+ * Supports standard hex, compressed `::`, and embedded dotted IPv4 (e.g. `::ffff:127.0.0.1`).
+ * @param {string} ip
+ * @returns {number[]|null}
+ */
+export function parseIpv6Words(ip) {
+  if (typeof ip !== 'string') return null;
+  let s = ip.toLowerCase().trim().replace(/^\[|\]$/g, '');
+  const lastColon = s.lastIndexOf(':');
+  if (lastColon !== -1) {
+    const tail = s.slice(lastColon + 1);
+    if (net.isIP(tail) === 4) {
+      const parts = tail.split('.').map(Number);
+      if (parts.length === 4 && !parts.some(n => isNaN(n) || n < 0 || n > 255)) {
+        const w6 = ((parts[0] << 8) | parts[1]) & 0xffff;
+        const w7 = ((parts[2] << 8) | parts[3]) & 0xffff;
+        s = s.slice(0, lastColon) + ':' + w6.toString(16) + ':' + w7.toString(16);
+      }
+    }
+  }
+  const halves = s.split('::');
+  if (halves.length > 2) return null;
+  const left = halves[0] ? halves[0].split(':').map(x => parseInt(x, 16)) : [];
+  const right = halves.length === 2 && halves[1] ? halves[1].split(':').map(x => parseInt(x, 16)) : [];
+  if (left.some(isNaN) || right.some(isNaN)) return null;
+  const missing = 8 - (left.length + right.length);
+  if (halves.length === 1 && missing !== 0) return null;
+  if (missing < 0) return null;
+  const middle = new Array(missing).fill(0);
+  return [...left, ...middle, ...right];
+}
+
 /**
  * Checks if an IPv4 or IPv6 address is private, loopback, link-local, multicast, or reserved.
+ * Canonicalizes IPv6 addresses including hex and dotted-quad IPv4-mapped forms (#411).
  * @param {string} ip
  * @returns {boolean} true if private/reserved/loopback
  */
 export function isPrivateOrReservedIp(ip) {
   if (!ip || typeof ip !== 'string') return true;
-  const kind = net.isIP(ip);
+  const cleaned = ip.trim().replace(/^\[|\]$/g, '');
+  const kind = net.isIP(cleaned);
   if (kind === 4) {
-    const parts = ip.split('.').map(Number);
+    const parts = cleaned.split('.').map(Number);
     if (parts.length !== 4 || parts.some(n => isNaN(n) || n < 0 || n > 255)) return true;
     const [a, b, c, d] = parts;
     if (a === 0) return true; // 0.0.0.0/8 current network
@@ -33,22 +70,70 @@ export function isPrivateOrReservedIp(ip) {
     return false;
   }
   if (kind === 6) {
-    const norm = ip.toLowerCase();
-    if (norm === '::' || norm === '::1' || norm === '0:0:0:0:0:0:0:0' || norm === '0:0:0:0:0:0:0:1') return true;
-    if (norm.startsWith('::ffff:') || norm.startsWith('0:0:0:0:0:ffff:')) {
-      const last = norm.split(':').pop();
-      if (net.isIP(last) === 4) return isPrivateOrReservedIp(last);
+    const words = parseIpv6Words(cleaned);
+    if (!words || words.length !== 8) return true;
+    const [w0, w1, w2, w3, w4, w5, w6, w7] = words;
+    // Unspecified :: or loopback ::1
+    if (w0 === 0 && w1 === 0 && w2 === 0 && w3 === 0 && w4 === 0 && w5 === 0 && w6 === 0) {
+      if (w7 === 0 || w7 === 1) return true;
+    }
+    // IPv4-mapped (::ffff:0:0/96), IPv4-compatible (::/96), or NAT64 (64:ff9b::/96)
+    const isMapped = (w0 === 0 && w1 === 0 && w2 === 0 && w3 === 0 && w4 === 0 && w5 === 0xffff);
+    const isCompat = (w0 === 0 && w1 === 0 && w2 === 0 && w3 === 0 && w4 === 0 && w5 === 0);
+    const isNat64 = (w0 === 0x0064 && w1 === 0xff9b && w2 === 0 && w3 === 0 && w4 === 0 && w5 === 0);
+    if (isMapped || isCompat || isNat64) {
+      const a = (w6 >> 8) & 0xff;
+      const b = w6 & 0xff;
+      const c = (w7 >> 8) & 0xff;
+      const d = w7 & 0xff;
+      return isPrivateOrReservedIp(`${a}.${b}.${c}.${d}`);
     }
-    if (/^fe[89ab][0-9a-f]:/i.test(norm)) return true; // fe80::/10 link-local
-    if (/^f[cd][0-9a-f]{2}:/i.test(norm)) return true; // fc00::/7 unique local
-    if (/^ff[0-9a-f]{2}:/i.test(norm)) return true; // ff00::/8 multicast
-    if (/^(?:00)?2001:(?:0)?db8:/i.test(norm)) return true; // 2001:db8::/32 documentation
-    if (/^(?:00)?100:/i.test(norm)) return true; // 100::/64 discard
+    if ((w0 & 0xffc0) === 0xfe80) return true; // fe80::/10 link-local
+    if ((w0 & 0xfe00) === 0xfc00) return true; // fc00::/7 unique local
+    if ((w0 & 0xff00) === 0xff00) return true; // ff00::/8 multicast
+    if (w0 === 0x2001 && w1 === 0x0db8) return true; // 2001:db8::/32 documentation
+    if (w0 === 0x0100 && w1 === 0) return true; // 100::/64 discard
     return false;
   }
   return true;
 }
 
+/**
+ * Creates an undici Agent with connect-time lookup validation against DNS rebinding / TOCTOU (#411).
+ * @param {object} [opts]
+ * @param {Function} [opts.lookupImpl]
+ * @returns {Agent}
+ */
+export function createSafeDispatcher({ lookupImpl = nodeDns.lookup } = {}) {
+  return new Agent({
+    connect: {
+      lookup: (hostname, options, callback) => {
+        const cb = typeof options === 'function' ? options : callback;
+        const opts = typeof options === 'function' ? {} : options;
+        lookupImpl(hostname, { ...opts, all: true }, (err, addresses) => {
+          if (err) return cb(err);
+          const list = Array.isArray(addresses) ? addresses : [addresses];
+          for (const item of list) {
+            const addr = typeof item === 'string' ? item : item.address;
+            if (isPrivateOrReservedIp(addr)) {
+              const ssrfErr = new Error(`dsh-key-rotation: connect blocked: host ${hostname} resolves to private or reserved IP ${addr}`);
+              ssrfErr.code = 'SSRF_BLOCKED';
+              return cb(ssrfErr);
+            }
+          }
+          if (typeof options === 'function') {
+            const first = list[0];
+            const addr = typeof first === 'string' ? first : first.address;
+            const fam = typeof first === 'object' && first.family ? first.family : (net.isIP(addr) || 4);
+            return cb(null, addr, fam);
+          }
+          return cb(null, addresses);
+        });
+      },
+    },
+  });
+}
+
 /**
  * Validates a target URL and its hostname/IP against SSRF.
  * @param {string} urlString
@@ -173,7 +258,7 @@ export async function readBoundedJson(resp, maxBytes = MAX_IMPORT_BYTES) {
 }
 
 /**
- * Fetches JSON from a URL with SSRF protection, redirect verification, and size bounding.
+ * Fetches JSON from a URL with SSRF protection, connect-time rebinding guard, redirect verification, and size bounding.
  * @param {string} url
  * @param {object} options
  */
@@ -183,14 +268,18 @@ export async function safeFetchJson(url, {
   lookupImpl = dns.lookup,
   maxBytes = MAX_IMPORT_BYTES,
   redirectsLeft = MAX_REDIRECTS,
+  dispatcher,
 } = {}) {
+  const safeDispatcher = dispatcher ?? (fetchImpl === globalThis.fetch ? createSafeDispatcher() : undefined);
   let currentUrl = url;
   while (true) {
     await assertSafeUrl(currentUrl, { lookupImpl });
-    const resp = await fetchImpl(currentUrl, {
+    const fetchOpts = {
       signal,
       redirect: 'manual',
-    });
+    };
+    if (safeDispatcher) fetchOpts.dispatcher = safeDispatcher;
+    const resp = await fetchImpl(currentUrl, fetchOpts);
 
     if ([301, 302, 303, 307, 308].includes(resp.status)) {
       if (redirectsLeft <= 0) {
@@ -218,4 +307,4 @@ export async function safeFetchJson(url, {
 
     return await readBoundedJson(resp, maxBytes);
   }
-}
+}

package/lib/sanitize-snapshot.js

@@ -45,6 +45,14 @@ export function sanitizeKeyStatus(key, now = Date.now()) {
           limit: clampNonNegative(key.rpm.limit),
         }
       : key.rpm,
+    tpm: key.tpm && typeof key.tpm === 'object'
+      ? {
+          ...key.tpm,
+          used: clampNonNegative(key.tpm.used),
+          remaining: clampNonNegative(key.tpm.remaining),
+          limit: clampNonNegative(key.tpm.limit),
+        }
+      : key.tpm,
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-key-rotation",
-  "version": "0.8.37",
+  "version": "0.8.39",
   "packageManager": "pnpm@10.33.2",
   "description": "Per-provider API key rotation for DeepSeek Harness: a key pool per provider, auto-created clone routes, and switching to the next key on quota/rate-limit errors. Includes a Settings section (Key Rotation) to edit the key pools, cooldown and switch codes.",
   "keywords": [
@@ -57,8 +57,8 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/schemastery": "^3.18.1",
-    "@deepseek-ai/dsh-llm": "^0.1.7-rc.2 || ^0.2.0-rc.1"
+    "@deepseek-ai/dsh-llm": "^0.1.7-rc.2 || ^0.2.0-rc.1",
+    "@deepseek-ai/schemastery": "^3.18.4"
   },
   "scripts": {
     "test": "node tools/test.mjs",
@@ -70,5 +70,8 @@
   "devDependencies": {
     "react": "18.3.1",
     "react-test-renderer": "18.3.1"
+  },
+  "dependencies": {
+    "undici": "^6.29.0"
   }
 }