@goodandready/dsh-key-rotation 0.8.23 → 0.8.25

package/CHANGELOG.md

@@ -3,6 +3,43 @@
 All notable changes to `@goodandready/dsh-key-rotation` are documented here.
 User-facing feature notes also appear in README (en is source of truth).
 
+## 0.8.25 - 2026-09-27
+
+### Fixed & Hardened
+- **Sandbox cache HTTP method validation (#357)**:
+  - `lib/ops-test.js`: enforced strict `GET` method check on `/dsh-key-rotation/sandbox-cache`. Non-GET requests (`POST`, `PUT`, `DELETE`) now consistently return HTTP 405 Method Not Allowed (`{ error: { code: 'method', message: 'GET only' } }`).
+- **Webhook action security and timeout hardening (#358)**:
+  - `lib/ops-webhook.js`: converted authorization bearer token validation to constant-time comparison via `crypto.timingSafeEqual`, preventing timing side-channel attacks on `webhookActionToken`.
+  - Added strict Telegram bot token format validation (`TELEGRAM_BOT_TOKEN_RE = /^[0-9]{5,16}:[a-zA-Z0-9_-]{20,50}$/`).
+  - Added 10-second timeout guard (`signal: AbortSignal.timeout(10000)`) on outgoing Telegram API `setWebhook` requests to eliminate socket hang risks.
+- **Dead code removal & unexported private symbols (#359)**:
+  - Removed unimported orphaned module `lib/bounded-map.js` and removed its standalone test cases.
+  - Eliminated dead exports in internal modules: unexported `CONCURRENCY_DEFAULT_LIMIT`, `CONCURRENCY_STALE_LOCK_MS` in `lib/concurrency.js`, `MAX_USAGE_RETENTION_DAYS` in `lib/usage-report.js`, `WEBHOOK_*` constants in `lib/webhook.js`, `assertJson` and `SECRET_FIELDS` in `lib/settings-write.js`, and `isNewerVersion` in `lib/plugin-updater.js`.
+- **Documentation contract alignment (#360)**:
+  - `docs/design/DESIGN.md`: added mandatory sections «Политика маршрутов» (complete 12-route method, origin, and authorization matrix) and «Что публикуется» (npm files, exclusions, and verification timestamp) per `dsh-documentation-standard`.
+  - Corrected webhook endpoint URI in DESIGN.md to `/dsh-key-rotation/webhook-action`.
+- **Canonical scoped package name in module export (#361)**:
+  - `lib/index.js`: unified `export const name = '@goodandready/dsh-key-rotation';` across all four package identity checkpoints (`package.json`, `cordis.patch.yml`, `lib/client.js`, and `lib/index.js`), resolving preflight check failure.
+
+## 0.8.24 - 2026-09-25
+
+### Security Hardening
+- **Bridge trust guard fail-closed enforcement (#353)**:
+  - `lib/pool.js`: `isTrustedBridgeRequest` is now strictly fail-closed. Rejects any request missing the `Origin` header (`origin` is required). Validates that `Origin` host strictly matches the `Host` header and that hostname is loopback (`127.0.0.1`, `::1`, `localhost`). Rejects requests with `Sec-Fetch-Site: cross-site`.
+  - `lib/ops-status.js`: removed loopback fallback logic in `/health` (lines 170-175) that previously bypassed the centralized predicate when `Sec-Fetch-Site` was not `cross-site`. All guarded routes (`status`, `health`, `key`, `reset`, `import`, `test`, `sandbox-cache`, `usage`, `snapshot`, `config`) now consistently route through `isTrustedBridgeRequest`.
+  - Added comprehensive test suite `test/route-guard-fail-closed.test.mjs` verifying missing-header and origin-mismatch rejections across all 12 guarded route surfaces.
+- **SSRF protection on provider pool import route (#354)**:
+  - `lib/safe-fetch.js` & `lib/ops-keys.js`: added multi-layered SSRF guard for `/dsh-key-rotation/import`.
+  - Protocol constraint: strictly `https:`.
+  - DNS / IP classification: resolves and rejects private (RFC 1918: `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`), loopback (`127.0.0.0/8`, `::1`), link-local (`169.254.0.0/16`, `fe80::/10`), unique-local (`fc00::/7`), multicast (`224.0.0.0/4`, `ff00::/8`), carrier-grade NAT (`100.64.0.0/10`), IPv4-mapped IPv6, and reserved IP literals and DNS resolutions. Guards against DNS rebinding attacks.
+  - Redirect protection: uses `redirect: 'manual'` and recursively validates redirect target URLs and resolved IPs up to 5 hops (`MAX_REDIRECTS`).
+  - Response size bounding: caps response body stream to 1 MB (`MAX_IMPORT_BYTES = 1048576`) before parsing JSON, preventing memory exhaustion attacks.
+  - Added comprehensive test suite `test/ssrf-protection.test.mjs`.
+- **Short credential masking in keyTail (#355)**:
+  - `lib/pool.js`: `keyTail` now returns a fixed placeholder `***` (`KEY_TAIL_PLACEHOLDER`) for credentials with length <= 5 (`KEY_TAIL_CHARS`), preventing complete credential disclosure through operational telemetry (`status`, `test`). Returns empty string for empty or non-string inputs.
+  - Exported `KEY_TAIL_PLACEHOLDER` and `KEY_TAIL_CHARS`.
+  - Added boundary tests covering lengths 0 through 8 in `test/key-tail.test.js`.
+
 ## 0.8.23 - 2026-09-23
 
 ### Fixed

package/README.md

@@ -205,8 +205,9 @@ Access full visual management under **Settings → Key Rotation** or via the Hea
 
 * **Zero Plaintext Secrets in Plugin Config**: Configuration files store only environment variable reference names (e.g. `MY_PROVIDER_API_KEY`).
 * **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.
-* **Loopback & Same-Origin Fencing**: Administrative endpoints (`GET /status`, `PUT /key`, `POST /reset`, `POST /test-matrix`) strictly enforce loopback origin checks (`isTrustedBridgeRequest`).
+* **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.
 
 ---
 

package/README.ru.md

@@ -192,8 +192,9 @@ graph LR
 
 * **Никаких открытых секретов в конфигурации**: В настройках плагина хранятся только имена переменных окружения (например, `PROVIDER_API_KEY`).
 * **Защищённое хранилище хоста**: Реальные значения ключей сохраняются в `$DSH_HOME/.credentials.yaml` сервисом `Credentials`.
-* **Маскировка в браузере (5 символов)**: Браузер получает только последние 5 символов ключа для визуального отличия.
-* **Ограничение Loopback**: Все управляющие маршруты (`GET /status`, `PUT /key`, `POST /reset`, `POST /test-matrix`) строго проверяют loopback-происхождение запроса (`isTrustedBridgeRequest`).
+* **Маскировка в браузере (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 МБ.
 
 ---
 

package/README.zh.md

@@ -184,8 +184,9 @@ graph LR
 
 * **配置零明文**：插件配置仅保存环境变量引用名（如 `MY_PROVIDER_API_KEY`）。
 * **宿主安全存储**：真实密钥持久化保存在 `$DSH_HOME/.credentials.yaml`。
-* **前台 5 字符脱敏**：前端仅展示密钥后 5 位字符进行视觉区分。
-* **环回安全隔离**：管理接口严格限制来自本地同源请求 (`isTrustedBridgeRequest`)。
+* **前台 5 字符脱敏**：前端仅展示密钥后 5 位字符进行视觉区分。对于长度 <= 5 的短密钥，返回统一脱敏占位符 (`***`)，防止凭证完整泄露。
+* **Fail-Closed 环回同源安全隔离**：管理接口严格通过 `isTrustedBridgeRequest` 验证本地同源请求，强制要求有效 `Origin` 和 `Host` 匹配，无条件拒绝跨站 (`cross-site`) 与非环回调用。
+* **导入接口 SSRF 防护**：远程提供商配置导入严格仅支持 HTTPS，解析并拦截所有私有/保留 IP 地址（RFC 1918、环回、链路本地、多播、CGNAT），对重定向目标进行全程验证，并将响应体上限严格控制在 1 MB 以内。
 
 ---
 

package/lib/concurrency.js

@@ -1,7 +1,7 @@
 // concurrency.js — per-key in-flight counter + least-connections picking (issue #193).
 
-export const CONCURRENCY_DEFAULT_LIMIT = 0;
-export const CONCURRENCY_STALE_LOCK_MS = 5 * 60 * 1000;
+const CONCURRENCY_DEFAULT_LIMIT = 0;
+const CONCURRENCY_STALE_LOCK_MS = 5 * 60 * 1000;
 
 export class ConcurrencyTracker {
   constructor(opts) {

package/lib/index.js

@@ -8,7 +8,7 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 import Schema from '@deepseek-ai/schemastery';
 import { createConfigReader, createProviderProfilesReader } from './config-compat.js';
 import {
-  keyTail, isLoopbackAddress, isTrustedBridgeRequest, SWITCHABLE_MESSAGE_PATTERN,
+  keyTail, KEY_TAIL_CHARS, KEY_TAIL_PLACEHOLDER, isLoopbackAddress, isTrustedBridgeRequest, SWITCHABLE_MESSAGE_PATTERN,
   DEFAULT_SWITCH_CODES, isValidRef, pickNext, applyCooldown, recordFailure,
   recordSuccess, computeBackoff, envValue, sweepExpired, parseRetryAfter,
   computeHealthScore, extractRateLimit, isRateLimited, selectPool, isSwitchableError,
@@ -37,9 +37,9 @@ import { checkBudgetAndHealthAlerts } from './budget-monitor.js';
 import { buildPoolItem, cleanupRemovedProviders } from './pool-builder.js';
 import { setupIdleHealEffect, setupAutoUnbreakEffect, setupPersistence } from './lifecycle.js';
 
-export const name = 'dsh-key-rotation';
+export const name = '@goodandready/dsh-key-rotation';
 export const inject = ['llm', 'webServer', 'settings', 'credentials'];
-export { keyTail, isLoopbackAddress, isTrustedBridgeRequest, DEFAULT_SWITCH_CODES, isSwitchableError, formatExhaustionMessage, getRuntime };
+export { keyTail, KEY_TAIL_CHARS, KEY_TAIL_PLACEHOLDER, isLoopbackAddress, isTrustedBridgeRequest, DEFAULT_SWITCH_CODES, isSwitchableError, formatExhaustionMessage, getRuntime };
 export { notifySwitch, notifyExhaustion };
 
 const NS = 'dsh-key-rotation';

package/lib/ops-keys.js

@@ -4,6 +4,7 @@ import {
   readJson,
   NS,
 } from './http-bridge.js';
+import { safeFetchJson } from './safe-fetch.js';
 import {
   isTrustedBridgeRequest,
   isValidRef,
@@ -168,9 +169,11 @@ ctx.effect(() => ctx.webServer.register({
     const url = typeof body?.url === 'string' ? body.url.trim() : '';
     if (!url || !url.startsWith('https://')) { json(res, 400, { error: { code: 'bad-url', message: 'dsh-key-rotation: only HTTPS URLs are allowed' } }); return; }
     try {
-      const resp = await fetch(url, { signal: AbortSignal.timeout(10000) });
-      if (!resp.ok) { json(res, 400, { error: { code: 'fetch-failed', message: 'dsh-key-rotation: fetch returned ' + resp.status } }); return; }
-      const data = await resp.json();
+      const data = await safeFetchJson(url, {
+        signal: AbortSignal.timeout(10000),
+        fetchImpl: deps.fetchImpl ?? globalThis.fetch,
+        lookupImpl: deps.lookupImpl ?? undefined,
+      });
       validateProviders(data);
       const settings = ctx.get('settings');
       if (!settings) { json(res, 503, { error: { code: 'settings-rejected', message: 'dsh-key-rotation: no settings provider' } }); return; }
@@ -184,7 +187,7 @@ ctx.effect(() => ctx.webServer.register({
       await mutateSettings(settings, NS, [{ op: 'set', path: ['providers'], value: mergedArr }], body.expectedRevision ?? desc.revision);
       json(res, 200, { ok: true, providersImported: data.length, total: mergedArr.length });
     } catch (e) {
-      const isTimeout = e?.name === 'TimeoutError' || e?.name === 'AbortError';
+      const isTimeout = e?.name === 'TimeoutError' || e?.name === 'AbortError' || e?.code === 'timeout';
       json(res, isTimeout ? 504 : e?.code === 'SETTINGS_CONFLICT' ? 409 : 400, { error: { code: isTimeout ? 'timeout' : 'import-failed', message: String(e?.message ?? e) } });
     }
   },

package/lib/ops-status.js

@@ -167,11 +167,9 @@ ctx.effect(() => ctx.webServer.register({
   kind: 'exact',
   path: HEALTH_PATH,
   handler: async (req, res) => {
-    if (!isTrustedBridgeRequest(req) && req.socket?.remoteAddress !== '127.0.0.1' && req.socket?.remoteAddress !== '::1') { } // allow same-origin already checked
     if (!isTrustedBridgeRequest(req)) {
-      // also allow plain loopback without Origin
-      if (!isLoopbackAddress(req.socket?.remoteAddress)) { res.writeHead(403); res.end(); return; }
-      if (req.headers['sec-fetch-site'] === 'cross-site') { res.writeHead(403); res.end(); return; }
+      json(res, 403, { error: { code: 'forbidden', message: 'dsh-key-rotation: health is local-only' } });
+      return;
     }
     if (req.method !== 'GET') { json(res, 405, { error: { code: 'method', message: 'GET only' } }); return; }
     const now = Date.now();

package/lib/ops-test.js

@@ -90,6 +90,7 @@ ctx.effect(() => ctx.webServer.register({
   kind: 'exact',
   path: SANDBOX_CACHE_PATH,
   handler: (req, res) => {
+    if (req.method !== 'GET') { json(res, 405, { error: { code: 'method', message: 'GET only' } }); return; }
     if (!isTrustedBridgeRequest(req)) { json(res, 403, { error: { code: 'forbidden', message: 'dsh-key-rotation: cache is local-only' } }); return; }
     const cacheSnap = typeof lastTestCache?.snapshot === 'function'
       ? lastTestCache.snapshot()

package/lib/ops-webhook.js

@@ -1,3 +1,4 @@
+import crypto from 'node:crypto';
 // lib/ops-webhook.js — webhook interactive action route (#312 split from routes-ops.js).
 import {
   json,
@@ -26,7 +27,11 @@ ctx.effect(() => ctx.webServer.register({
     const expected = runtime.webhookActionToken;
     if (!expected) { json(res, 503, { error: { code: 'no-token', message: 'dsh-key-rotation: webhookActionToken is not configured' } }); return; }
     const auth = String(req.headers.authorization ?? '');
-    if (auth !== `Bearer ${expected}`) { json(res, 401, { error: { code: 'unauthorized', message: 'dsh-key-rotation: bad webhook action token' } }); return; }
+    const expectedAuth = `Bearer ${expected}`;
+    const authBuf = Buffer.from(auth);
+    const expBuf = Buffer.from(expectedAuth);
+    const tokenMatch = authBuf.length === expBuf.length && crypto.timingSafeEqual(authBuf, expBuf);
+    if (!tokenMatch) { json(res, 401, { error: { code: 'unauthorized', message: 'dsh-key-rotation: bad webhook action token' } }); return; }
     let body;
     try { body = await readJson(req); } catch (e) { json(res, 400, { error: { code: 'bad-request', message: String(e?.message ?? e) } }); return; }
     // Accept callback payloads from formatInteractive (Telegram/Discord/Slack) or plain {action}
@@ -45,12 +50,18 @@ ctx.effect(() => ctx.webServer.register({
     if (typeof body?.setWebhook === 'object' && body.setWebhook) {
       const botToken = typeof body.setWebhook.botToken === 'string' ? body.setWebhook.botToken : '';
       if (!botToken) { json(res, 400, { error: { code: 'bad-request', message: 'dsh-key-rotation: setWebhook.botToken required' } }); return; }
+      const TELEGRAM_BOT_TOKEN_RE = /^[0-9]{5,16}:[a-zA-Z0-9_-]{20,50}$/;
+      if (!TELEGRAM_BOT_TOKEN_RE.test(botToken)) {
+        json(res, 400, { error: { code: 'bad-request', message: 'dsh-key-rotation: invalid telegram bot token format' } });
+        return;
+      }
       // derive the public URL from request headers; explicit URL wins
       const url = typeof body.setWebhook.url === 'string' && body.setWebhook.url ? body.setWebhook.url : `https://${String(req.headers.host ?? '')}/dsh-key-rotation/webhook-action`;
       try {
         const hookRes = await fetch(`https://api.telegram.org/bot${botToken}/setWebhook`, {
           method: 'POST', headers: { 'content-type': 'application/json' },
           body: JSON.stringify({ url, allowed_updates: ['callback_query'] }),
+          signal: AbortSignal.timeout(10000),
         });
         const hookData = await hookRes.json().catch(() => ({}));
         json(res, 200, { ok: hookRes.ok, url, telegram: hookData });

package/lib/plugin-updater.js

@@ -135,7 +135,7 @@ function comparePrerelease(left, right) {
   return 0
 }
 
-export function isNewerVersion(currentValue, candidateValue) {
+function isNewerVersion(currentValue, candidateValue) {
   const current = parseSemver(currentValue)
   const candidate = parseSemver(candidateValue)
   if (current === undefined || candidate === undefined) return false

package/lib/pool.js

@@ -5,10 +5,13 @@ import { bestEffort } from './best-effort.js';
 /** Number of characters shown in masked key tails. */
 export const KEY_TAIL_CHARS = 5;
 
-/** Mask key to show only the last KEY_TAIL_CHARS. */
+/** Fixed placeholder for short credentials (len <= KEY_TAIL_CHARS) to prevent disclosure (#355). */
+export const KEY_TAIL_PLACEHOLDER = '***';
+
+/** Mask key to show only the last KEY_TAIL_CHARS; returns placeholder for short keys (#355). */
 export function keyTail(key) {
-  if (typeof key !== 'string') return '';
-  if (key.length <= KEY_TAIL_CHARS) return key;
+  if (typeof key !== 'string' || key.length === 0) return '';
+  if (key.length <= KEY_TAIL_CHARS) return KEY_TAIL_PLACEHOLDER;
   return key.slice(-KEY_TAIL_CHARS);
 }
 
@@ -20,12 +23,12 @@ export function isLoopbackAddress(ip) {
   return false;
 }
 
-/** Check if an incoming HTTP request is from a trusted local bridge origin. */
+/** Check if an incoming HTTP request is from a trusted local bridge origin (#353 fail-closed). */
 export function isTrustedBridgeRequest(req) {
   const remoteAddress = req?.socket?.remoteAddress;
   if (!isLoopbackAddress(remoteAddress)) return false;
   const origin = req?.headers?.origin;
-  if (!origin) return true;
+  if (!origin) return false;
   if (req?.headers?.['sec-fetch-site'] === 'cross-site') return false;
   const hostHeader = req?.headers?.host;
   if (!hostHeader) return false;

package/lib/safe-fetch.js

@@ -0,0 +1,221 @@
+// lib/safe-fetch.js — SSRF-protected HTTP fetch with DNS and IP validation (#354).
+import net from 'node:net';
+import dns from 'node:dns/promises';
+
+export const MAX_IMPORT_BYTES = 1024 * 1024; // 1 MB limit
+export const MAX_REDIRECTS = 5;
+
+/**
+ * Checks if an IPv4 or IPv6 address is private, loopback, link-local, multicast, or reserved.
+ * @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);
+  if (kind === 4) {
+    const parts = ip.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
+    if (a === 10) return true; // 10.0.0.0/8 private
+    if (a === 127) return true; // 127.0.0.0/8 loopback
+    if (a === 169 && b === 254) return true; // 169.254.0.0/16 link-local
+    if (a === 172 && b >= 16 && b <= 31) return true; // 172.16.0.0/12 private
+    if (a === 192 && b === 168) return true; // 192.168.0.0/16 private
+    if (a === 100 && b >= 64 && b <= 127) return true; // 100.64.0.0/10 carrier-grade NAT
+    if (a === 192 && b === 0 && c === 0) return true; // 192.0.0.0/24 IETF protocol
+    if (a === 192 && b === 0 && c === 2) return true; // 192.0.2.0/24 TEST-NET-1
+    if (a === 198 && (b === 18 || b === 19)) return true; // 198.18.0.0/15 benchmarking
+    if (a === 198 && b === 51 && c === 100) return true; // 198.51.100.0/24 TEST-NET-2
+    if (a === 203 && b === 0 && c === 113) return true; // 203.0.113.0/24 TEST-NET-3
+    if (a >= 224) return true; // 224.0.0.0/4 multicast & 240.0.0.0/4 reserved & broadcast
+    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);
+    }
+    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
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Validates a target URL and its hostname/IP against SSRF.
+ * @param {string} urlString
+ * @param {object} options
+ */
+export async function assertSafeUrl(urlString, { lookupImpl = dns.lookup } = {}) {
+  let urlObj;
+  try {
+    urlObj = new URL(urlString);
+  } catch {
+    const err = new Error('dsh-key-rotation: invalid URL');
+    err.code = 'INVALID_URL';
+    throw err;
+  }
+
+  if (urlObj.protocol !== 'https:') {
+    const err = new Error('dsh-key-rotation: only HTTPS URLs are allowed');
+    err.code = 'DISALLOWED_PROTOCOL';
+    throw err;
+  }
+
+  const hostname = urlObj.hostname.replace(/^\[|\]$/g, '');
+  if (!hostname) {
+    const err = new Error('dsh-key-rotation: missing hostname');
+    err.code = 'INVALID_HOST';
+    throw err;
+  }
+
+  if (net.isIP(hostname)) {
+    if (isPrivateOrReservedIp(hostname)) {
+      const err = new Error(`dsh-key-rotation: target IP ${hostname} is private or reserved`);
+      err.code = 'SSRF_BLOCKED';
+      throw err;
+    }
+    return urlObj;
+  }
+
+  let records;
+  try {
+    records = await lookupImpl(hostname, { all: true });
+  } catch (dnsErr) {
+    const err = new Error(`dsh-key-rotation: DNS resolution failed for ${hostname}: ${dnsErr.message}`);
+    err.code = 'DNS_FAILED';
+    throw err;
+  }
+
+  if (!records || records.length === 0) {
+    const err = new Error(`dsh-key-rotation: no DNS records found for ${hostname}`);
+    err.code = 'DNS_FAILED';
+    throw err;
+  }
+
+  for (const rec of records) {
+    const addr = typeof rec === 'string' ? rec : rec.address;
+    if (isPrivateOrReservedIp(addr)) {
+      const err = new Error(`dsh-key-rotation: host ${hostname} resolves to private or reserved IP ${addr}`);
+      err.code = 'SSRF_BLOCKED';
+      throw err;
+    }
+  }
+
+  return urlObj;
+}
+
+/**
+ * Reads a response safely, capping byte size to maxBytes before parsing JSON.
+ * @param {Response} resp
+ * @param {number} maxBytes
+ * @returns {Promise<any>}
+ */
+export async function readBoundedJson(resp, maxBytes = MAX_IMPORT_BYTES) {
+  const clHeader = resp.headers?.get?.('content-length');
+  if (clHeader) {
+    const len = Number(clHeader);
+    if (!isNaN(len) && len > maxBytes) {
+      const err = new Error(`dsh-key-rotation: response exceeds maximum size of ${maxBytes} bytes`);
+      err.code = 'PAYLOAD_TOO_LARGE';
+      throw err;
+    }
+  }
+
+  if (resp.body && typeof resp.body.getReader === 'function') {
+    const reader = resp.body.getReader();
+    let total = 0;
+    const chunks = [];
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        total += value.length;
+        if (total > maxBytes) {
+          reader.cancel();
+          const err = new Error(`dsh-key-rotation: response exceeds maximum size of ${maxBytes} bytes`);
+          err.code = 'PAYLOAD_TOO_LARGE';
+          throw err;
+        }
+        chunks.push(value);
+      }
+    } catch (e) {
+      if (e.code === 'PAYLOAD_TOO_LARGE') throw e;
+      throw new Error(`dsh-key-rotation: error reading response body: ${e.message}`);
+    }
+    const fullBuffer = Buffer.concat(chunks);
+    return JSON.parse(fullBuffer.toString('utf8'));
+  }
+
+  if (typeof resp.text === 'function') {
+    const text = await resp.text();
+    if (Buffer.byteLength(text, 'utf8') > maxBytes) {
+      const err = new Error(`dsh-key-rotation: response exceeds maximum size of ${maxBytes} bytes`);
+      err.code = 'PAYLOAD_TOO_LARGE';
+      throw err;
+    }
+    return JSON.parse(text);
+  }
+
+  if (typeof resp.json === 'function') {
+    return await resp.json();
+  }
+
+  throw new Error('dsh-key-rotation: unable to read response as JSON');
+}
+
+/**
+ * Fetches JSON from a URL with SSRF protection, redirect verification, and size bounding.
+ * @param {string} url
+ * @param {object} options
+ */
+export async function safeFetchJson(url, {
+  signal,
+  fetchImpl = globalThis.fetch,
+  lookupImpl = dns.lookup,
+  maxBytes = MAX_IMPORT_BYTES,
+  redirectsLeft = MAX_REDIRECTS,
+} = {}) {
+  let currentUrl = url;
+  while (true) {
+    await assertSafeUrl(currentUrl, { lookupImpl });
+    const resp = await fetchImpl(currentUrl, {
+      signal,
+      redirect: 'manual',
+    });
+
+    if ([301, 302, 303, 307, 308].includes(resp.status)) {
+      if (redirectsLeft <= 0) {
+        const err = new Error('dsh-key-rotation: too many redirects');
+        err.code = 'TOO_MANY_REDIRECTS';
+        throw err;
+      }
+      redirectsLeft--;
+      const loc = resp.headers?.get?.('location');
+      if (!loc) {
+        const err = new Error('dsh-key-rotation: redirect missing Location header');
+        err.code = 'BAD_REDIRECT';
+        throw err;
+      }
+      currentUrl = new URL(loc, currentUrl).href;
+      continue;
+    }
+
+    if (!resp.ok) {
+      const err = new Error(`dsh-key-rotation: fetch returned ${resp.status}`);
+      err.code = 'FETCH_FAILED';
+      err.status = resp.status;
+      throw err;
+    }
+
+    return await readBoundedJson(resp, maxBytes);
+  }
+}

package/lib/settings-write.js

@@ -1,6 +1,6 @@
 // Settings writes from redacted browser views must never replace an entire
 // namespace. Host-side mutate is atomic and rejects conflicts on both core eras.
-export const SECRET_FIELDS = new Set(['webhookActionToken']);
+const SECRET_FIELDS = new Set(['webhookActionToken']);
 const UNSAFE_FIELDS = new Set(['__proto__', 'prototype', 'constructor']);
 
 export function plainObject(value) {
@@ -9,7 +9,7 @@ export function plainObject(value) {
   return proto === Object.prototype || proto === null;
 }
 
-export function assertJson(value, depth = 0) {
+function assertJson(value, depth = 0) {
   if (depth > 40) throw new TypeError('Configuration is nested too deeply');
   if (value === null || typeof value === 'string' || typeof value === 'boolean') return;
   if (typeof value === 'number' && Number.isFinite(value)) return;

package/lib/usage-report.js

@@ -1,6 +1,6 @@
 // lib/usage-report.js - #209 usage report rows from pool state + 30-day compaction (#11). Pure helpers.
 const DAY_MS = 86400000;
-export const MAX_USAGE_RETENTION_DAYS = 30;
+const MAX_USAGE_RETENTION_DAYS = 30;
 
 /**
  * Build per-key usage rows for the last `days` ISO days (default 7).

package/lib/webhook.js

@@ -1,8 +1,8 @@
 import { bestEffort } from './best-effort.js';
 // lib/webhook.js — webhook sender with throttle, interactive actions + alert digest debouncer (#199, #10).
-export const WEBHOOK_TIMEOUT_MS = 5000;
-export const WEBHOOK_MIN_INTERVAL_MS = 1000;
-export const WEBHOOK_RETRY_DELAY_MS = 2000;
+const WEBHOOK_TIMEOUT_MS = 5000;
+const WEBHOOK_MIN_INTERVAL_MS = 1000;
+const WEBHOOK_RETRY_DELAY_MS = 2000;
 
 /**
  * Detect platform from webhook URL (#199).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-key-rotation",
-  "version": "0.8.23",
+  "version": "0.8.25",
   "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": [

package/lib/bounded-map.js

@@ -1,65 +0,0 @@
-// lib/bounded-map.js — Map with max size + optional TTL (#262).
-
-export class BoundedMap {
-  /** @param {{ max?: number, ttlMs?: number|null }} opts */
-  constructor({ max = 1000, ttlMs = null } = {}) {
-    if (!Number.isFinite(max) || max < 1) throw new Error('BoundedMap: max must be >= 1');
-    this.max = max;
-    this.ttlMs = Number.isFinite(ttlMs) && ttlMs > 0 ? ttlMs : null;
-    this._m = new Map(); // insertion order = LRU order when we re-insert on get/set
-  }
-
-  get size() { return this._m.size; }
-
-  _expired(entry, now) {
-    if (!this.ttlMs || !entry) return false;
-    return now - entry.at >= this.ttlMs;
-  }
-
-  get(key, now = Date.now()) {
-    const e = this._m.get(key);
-    if (!e) return undefined;
-    if (this._expired(e, now)) {
-      this._m.delete(key);
-      return undefined;
-    }
-    // refresh LRU
-    this._m.delete(key);
-    this._m.set(key, e);
-    return e.v;
-  }
-
-  set(key, value, now = Date.now()) {
-    if (this._m.has(key)) this._m.delete(key);
-    this._m.set(key, { v: value, at: now });
-    while (this._m.size > this.max) {
-      const oldest = this._m.keys().next().value;
-      this._m.delete(oldest);
-    }
-    return this;
-  }
-
-  has(key, now = Date.now()) {
-    return this.get(key, now) !== undefined;
-  }
-
-  delete(key) { return this._m.delete(key); }
-  clear() { this._m.clear(); }
-
-  *entries(now = Date.now()) {
-    for (const [k, e] of [...this._m.entries()]) {
-      if (this._expired(e, now)) { this._m.delete(k); continue; }
-      yield [k, e.v];
-    }
-  }
-
-  *keys(now = Date.now()) {
-    for (const [k] of this.entries(now)) yield k;
-  }
-
-  toObject(now = Date.now()) {
-    const out = {};
-    for (const [k, v] of this.entries(now)) out[k] = v;
-    return out;
-  }
-}