@goodandready/dsh-key-rotation 0.5.0 → 0.5.2

package/README.md

@@ -12,7 +12,7 @@
 - **Cooldown** — an exhausted key is skipped for `cooldownMs`, then returns.
 - **Dead/revoked key handling** — an auth/invalid key rotates to the next pool key instead of erroring out.
 - **Settings GUI** — a **Settings → Key Rotation** section to manage everything without touching config files:
-  - **add a key in one place** — press *Add key*, paste the value, done. The credential name is generated for you (`OPENCODE_GO_API_KEY`, `_2`, `_3`, …) and shown only on hover; the card lists keys as *Key 1*, *Key 2*.
+  - **add a key in one place** — press *Add key*, paste the value, done. The credential name is generated for you (`<PROVIDER>_API_KEY`, then `_2`, `_3`, …) and shown only on hover; the card lists keys as *Key 1*, *Key 2*.
   - **live key status** — per key: in use / ready / cooling down with a countdown / **no such credential**, which is what catches a mistyped name that would otherwise fail silently.
   - **rotation counter** — how many times a provider switched key, on which failure, and how long ago.
   - **key order** — ↑/↓ buttons; the order of keys is the order they are tried.
@@ -46,10 +46,12 @@ dsh-key-rotation:
   switchCodes: [QUOTA, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT, EMPTY_RESPONSE, UNKNOWN_MODEL]
   cooldownMs: 60000
   providers:
-    - provider: opencode-go
-      keys: [OPENCODE_GO_API_KEY, OPENCODE_GO_API_KEY_2, OPENCODE_GO_API_KEY_3]
-    - provider: ollama
-      keys: [OLLAMA_API_KEY, OLLAMA_API_KEY_2, OLLAMA_API_KEY_3]
+    # `provider` is the id of a provider registered with dsh, as it appears
+    # in Settings -> Models. `keys` are CREDENTIAL NAMES, never key values.
+    - provider: my-provider
+      keys: [MY_PROVIDER_API_KEY, MY_PROVIDER_API_KEY_2, MY_PROVIDER_API_KEY_3]
+    - provider: another-provider
+      keys: [ANOTHER_PROVIDER_API_KEY, ANOTHER_PROVIDER_API_KEY_2]
 ```
 
 | Field | Default | Description |
@@ -60,7 +62,7 @@ dsh-key-rotation:
 
 ### How keys are stored
 
-The plugin config only ever references keys by **name** (e.g. `OPENCODE_GO_API_KEY`). The values live in the dsh **Credentials** service or `$DSH_HOME/.credentials.yaml` — never in the plugin config.
+The plugin config only ever references keys by **name** (e.g. `MY_PROVIDER_API_KEY`). The values live in the dsh **Credentials** service or `$DSH_HOME/.credentials.yaml` — never in the plugin config.
 
 A key typed into the Key Rotation card is written to that same credentials store: the value travels to the host once and is never sent back to the browser. Only its **last 5 characters** are, so two keys can be told apart in the UI. A key supplied by the launching environment is shown as read-only, because overwriting it here would be shadowed anyway.
 

package/lib/client.js

@@ -183,7 +183,7 @@ window.__ModuleLoader__.load({
      * Имя переменной под новый ключ.
      *
      * Пользователь его больше не печатает: первый ключ провайдера получает имя
-     * вида OPENCODE_GO_API_KEY, следующие — тот же корень с суффиксом _2, _3…
+     * вида <PROVIDER>_API_KEY, следующие — тот же корень с суффиксом _2, _3…
      * Корень берётся у уже существующих ключей, чтобы вручную заведённые имена
      * не ломались, и проверяется на занятость по ВСЕМ провайдерам — иначе два
      * провайдера незаметно делили бы одну учётную запись.

package/lib/index.js

@@ -9,17 +9,17 @@
 //  any content chunk.
 //
 //  The PROVIDER IDENTITY NEVER CHANGES: requests always go out with the
-//  provider the user selected (e.g. "opencode-go"), only the resolved API key
-//  differs. This keeps pi-ai's replay state consistent across multi-call turns
-//  and multi-turn sessions (the earlier clone-provider approach broke it with
+//  provider the user selected, only the resolved API key differs. This keeps
+//  pi-ai's replay state consistent across multi-call turns and multi-turn
+//  sessions (the earlier clone-provider approach broke it with
 //  INVALID_REPLAY_STATE).
 //
-//  Config is a KEY POOL PER PROVIDER: you list a real provider (e.g. "ollama")
-//  and the env names of its API keys (e.g. OLLAMA_API_KEY, OLLAMA_API_KEY_2,
-//  OLLAMA_API_KEY_3). When a key's limit is exhausted, the request retries on
-//  the next key in the list; exhausted keys stay in cooldown for cooldownMs.
-//  Clone provider routes (opencode-go-2, ...) are no longer used for rotation
-//  but remain registered, so selecting them also rotates (their apiKeyEnv ref
+//  Config is a KEY POOL PER PROVIDER: you list a real provider id and the env
+//  names of its API keys (e.g. <PROVIDER>_API_KEY, <PROVIDER>_API_KEY_2, ...).
+//  When a key's limit is exhausted, the request retries on the next key in the
+//  list; exhausted keys stay in cooldown for cooldownMs. Clone provider routes
+//  (named `<base>-2`, `<base>-3`, ...) are no longer used for rotation but
+//  remain registered, so selecting them also rotates (their apiKeyEnv ref
 //  belongs to the same pool).
 //
 //  The Settings section ("Key Rotation") edits the provider key pools as a
@@ -33,9 +33,11 @@
 //    providers:  array       [{ provider, keys: [envName, ...] }]
 // ─────────────────────────────────────────────────────────────────────────────
 import Schema from '@deepseek-ai/schemastery';
+import { keyTail, isLoopbackAddress, isTrustedBridgeRequest, SWITCHABLE_MESSAGE_PATTERN, DEFAULT_SWITCH_CODES, isValidRef, pickNext, applyCooldown } from './pool.js';
 
 export const name = 'dsh-key-rotation';
 export const inject = ['llm', 'webServer', 'settings', 'credentials'];
+export { keyTail, isLoopbackAddress, isTrustedBridgeRequest, DEFAULT_SWITCH_CODES };
 
 /** Settings namespace owning the GUI-editable section (settingsNamespace-valid). */
 const NS = 'dsh-key-rotation';
@@ -44,21 +46,11 @@ const CONFIG_PATH = '/dsh-key-rotation/config';
 const STATUS_PATH = '/dsh-key-rotation/status';
 const KEY_PATH = '/dsh-key-rotation/key';
 
-/** Хвост ключа для карточки: по нему ключ узнаётся, но не восстанавливается. */
-const KEY_TAIL_CHARS = 5;
-
-function keyTail(value) {
-  if (typeof value !== 'string' || value.length === 0) return '';
-  return value.length <= KEY_TAIL_CHARS ? value : value.slice(-KEY_TAIL_CHARS);
-}
 /** The llm-pi-ai namespace whose provider profiles map providers to pools. */
 const PIAI_NS = 'llm-pi-ai';
 /** Marker on internally re-dispatched requests so the interceptor does not loop. */
 const MARKER = '__dshKeyRotation';
 
-const DEFAULT_SWITCH_CODES = [
-  'QUOTA', 'RATE_LIMIT', 'SERVER', 'TIMEOUT', 'TRANSPORT', 'EMPTY_RESPONSE', 'UNKNOWN_MODEL', 'AUTH',
-];
 
 // Fallback classification by failure message. pi-ai surfaces many real quota /
 // rate-limit / transport failures as thrown exceptions (e.g. the OpenAI SDK
@@ -67,35 +59,13 @@ const DEFAULT_SWITCH_CODES = [
 // provider's own text ("429: ...", "Weekly usage limit reached", ...), so we
 // treat pre-content failures whose message matches these patterns as
 // switchable even when the code is not in `switchCodes`.
-const SWITCHABLE_MESSAGE_PATTERN = new RegExp([
-  /\b(?:quota|usage[\s_-]+limit|rate[\s_-]?limit)\b/i,
-  /\binsufficient[\s_-]+(?:quota|balance|credits?)\b/i,
-  /\bout[\s_-]+of[\s_-]+(?:credits?|budget)\b/i,
-  /\b(?:exceeded|exhausted)[\s_-]+(?:quota|limit|budget)\b/i,
-  /\bbilling\b/i,
-  /\b429\b|\b5\d\d\b/i,
-  /\btime(?:d)?\s*out\b|timeout/i,
-  /\b(?:network|connection|socket|fetch|ECONN[A-Z]+)\b/i,
-  /\bother side closed|premature close|stream ended (?:before|without)\b/i,
-  // auth: a dead/revoked key should also rotate to the next pool key
-  /\b401\b|\b403\b/i,
-  /\b(?:invalid|expired|revoked|unauthorized)[\s_-]+(?:api[\s_-]?key|token)\b/i,
-  /\bapi[\s_-]?key[\s_-]+(?:is[\s_-]+)?(?:invalid|expired|revoked|unauthorized)\b/i,
-  /\b(?:authentication|unauthorized|not[\s_-]+authorized)\b/i,
-].map((r) => r.source).join('|'));
-
-// Bootstrap key pools. The user edits these in the Settings GUI; this is just
-// the default matching the current server setup.
-const DEFAULT_PROVIDERS = [
-  {
-    provider: 'opencode-go',
-    keys: ['OPENCODE_GO_API_KEY', 'OPENCODE_GO_API_KEY_2', 'OPENCODE_GO_API_KEY_3', 'OPENCODE_GO_API_KEY_4'],
-  },
-  {
-    provider: 'ollama',
-    keys: ['OLLAMA_API_KEY', 'OLLAMA_API_KEY_2', 'OLLAMA_API_KEY_3'],
-  },
-];
+
+// Bootstrap key pools. The user configures them in the Settings GUI or via
+// the dsh profile bundle config; the plugin itself ships no provider defaults
+// so it does not bind to any specific installation. Empty array means: until
+// the user adds a pool, no rotation happens, and every provider falls back to
+// its single configured credential exactly as before this plugin was installed.
+const DEFAULT_PROVIDERS = [];
 
 export const Config = Schema.object({
   switchCodes: Schema.array(Schema.string()).default([...DEFAULT_SWITCH_CODES]),
@@ -108,26 +78,6 @@ export const Config = Schema.object({
 
 // ── config bridge (GET/PUT/DELETE on CONFIG_PATH), mirroring llm-fallback ──
 
-function isLoopbackAddress(address) {
-  if (address === void 0) return false;
-  if (address === '127.0.0.1' || address === '::1') return true;
-  if (address.startsWith('::ffff:')) return address.slice(7) === '127.0.0.1';
-  return false;
-}
-
-function isTrustedBridgeRequest(request) {
-  if (!isLoopbackAddress(request.socket?.remoteAddress)) return false;
-  if (request.headers['sec-fetch-site'] === 'cross-site') return false;
-  const origin = request.headers['origin'];
-  if (origin === void 0) return true;
-  try {
-    const host = request.headers['host'];
-    if (host === void 0) return false;
-    return new URL(origin).host === host;
-  } catch {
-    return false;
-  }
-}
 
 function json(res, status, obj) {
   res.writeHead(status, { 'content-type': 'application/json' });
@@ -547,7 +497,7 @@ export function apply(ctx, config = {}) {
         return;
       }
       const ref = typeof body?.ref === 'string' ? body.ref.trim() : '';
-      if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(ref)) {
+      if (!isValidRef(ref)) {
         json(res, 400, { error: { code: 'bad-ref', message: 'dsh-key-rotation: ref must be an environment variable name' } });
         return;
       }

package/lib/pool.js

@@ -0,0 +1,107 @@
+// Pure helpers for the key-rotation plugin. Kept free of DSH runtime
+// dependencies so they can be unit-tested under `node --test` without
+// `@deepseek-ai/cordis` / `@deepseek-ai/schemastery` being installed.
+// Anything that talks to `ctx` stays in lib/index.js.
+
+/** Number of trailing characters of a key shown in the UI for disambiguation. */
+export const KEY_TAIL_CHARS = 5;
+
+/** Returns the last KEY_TAIL_CHARS characters of a key, or the whole key if shorter. */
+export function keyTail(value) {
+  if (typeof value !== 'string' || value.length === 0) return '';
+  return value.length <= KEY_TAIL_CHARS ? value : value.slice(-KEY_TAIL_CHARS);
+}
+
+/** True if a socket remoteAddress is a loopback (v4 / v6). */
+export function isLoopbackAddress(address) {
+  if (address === undefined || address === null) return false;
+  if (address === '127.0.0.1' || address === '::1') return true;
+  if (typeof address === 'string' && address.startsWith('::ffff:')) {
+    return address.slice(7) === '127.0.0.1';
+  }
+  return false;
+}
+
+/** True if a request is both loopback and same-origin (sec-fetch-site guard). */
+export function isTrustedBridgeRequest(request) {
+  if (!isLoopbackAddress(request?.socket?.remoteAddress)) return false;
+  if (request?.headers?.['sec-fetch-site'] === 'cross-site') return false;
+  const origin = request?.headers?.origin;
+  if (origin === undefined) return true; // no Origin header (loopback tool) is allowed
+  try {
+    const host = request?.headers?.host;
+    if (host === undefined) return false;
+    return new URL(origin).host === host;
+  } catch {
+    return false;
+  }
+}
+
+/** Compiled once at module load. Matches error messages that should rotate the key
+ *  even when the structured failure code is not in `switchCodes`.
+ *  Mirrors SWITCHABLE_MESSAGE_PATTERN in lib/index.js exactly. */
+export const SWITCHABLE_MESSAGE_PATTERN = new RegExp([
+  /\b(?:quota|usage[\s_-]+limit|rate[\s_-]?limit)\b/i,
+  /\binsufficient[\s_-]+(?:quota|balance|credits?)\b/i,
+  /\bout[\s_-]+of[\s_-]+(?:credits?|budget)\b/i,
+  /\b(?:exceeded|exhausted)[\s_-]+(?:quota|limit|budget)\b/i,
+  /\bbilling\b/i,
+  /\b429\b|\b5\d\d\b/i,
+  /\btime(?:d)?\s*out\b|timeout/i,
+  /\b(?:network|connection|socket|fetch|ECONN[A-Z]+)\b/i,
+  /\bother side closed|premature close|stream ended (?:before|without)\b/i,
+  /\b401\b|\b403\b/i,
+  /\b(?:invalid|expired|revoked|unauthorized)[\s_-]+(?:api[\s_-]?key|token)\b/i,
+  /\bapi[\s_-]?key[\s_-]+(?:is[\s_-]+)?(?:invalid|expired|revoked|unauthorized)\b/i,
+  /\b(?:authentication|unauthorized|not[\s_-]+authorized)\b/i,
+].map((r) => r.source).join('|'));
+
+/** Default switch codes used by lib/index.js. Kept here so tests assert against
+ *  the same list the runtime ships. */
+export const DEFAULT_SWITCH_CODES = [
+  'QUOTA', 'RATE_LIMIT', 'SERVER', 'TIMEOUT', 'TRANSPORT',
+  'EMPTY_RESPONSE', 'UNKNOWN_MODEL', 'AUTH',
+];
+
+/** Ref name validator. Same rule lib/index.js enforces in PUT/DELETE /key. */
+const REF_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export function isValidRef(ref) {
+  return typeof ref === 'string' && REF_RE.test(ref);
+}
+
+/**
+ * Pick the next healthy ref in a round-robin pool.
+ *
+ * @param {{ refs: string[], state: { failedUntil: Map<string, number>, pointer: number } }} pool
+ * @param {number} now - epoch milliseconds (injectable for tests)
+ * @param {number} refsCount - for tests: number of refs to consider (defaults to pool.refs.length)
+ * @returns {string|undefined} the ref to use, or undefined if pool has no refs
+ *
+ * Mirrors the inline logic in the credentials.resolve patch in lib/index.js.
+ * Exported here for unit tests; not used at runtime to avoid duplicating logic.
+ */
+export function pickNext(pool, now, refsCount = pool.refs.length) {
+  if (refsCount === 0) return undefined;
+  const start = pool.state.pointer ?? 0;
+  for (let i = 0; i < refsCount; i++) {
+    const index = (start + i) % refsCount;
+    const candidate = pool.refs[index];
+    const until = pool.state.failedUntil.get(candidate);
+    if (until !== undefined && until > now) continue;
+    return candidate;
+  }
+  return undefined; // all cooled
+}
+
+/** Apply a failed-key cooldown to pool state. Pure: returns next state shape,
+ *  does not mutate input. Runtime in lib/index.js mutates in place; tests use
+ *  this helper to construct expected snapshots. */
+export function applyCooldown(pool, ref, cooldownMs, now = Date.now()) {
+  return {
+    ...pool,
+    state: {
+      ...pool.state,
+      failedUntil: new Map(pool.state.failedUntil).set(ref, now + cooldownMs),
+    },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-key-rotation",
-  "version": "0.5.0",
+  "version": "0.5.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": [
     "deepseek-harness",
@@ -51,5 +51,11 @@
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/schemastery": "^3.18.1",
     "@deepseek-ai/dsh-llm": "^0.1.0-rc.6"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "publishConfig": {
+    "access": "public"
   }
-}
+}