@goodandready/dsh-key-rotation 0.8.78 → 0.8.79

package/CHANGELOG.md

@@ -55,6 +55,13 @@
 - **Fail-Closed Balance & Probe Inspection**: Prevent sending ciphertext credentials (`enc:v1:...`) upstream if decryption fails (#539).
 - **PBKDF2 Iteration Bounds & Async KDF**: Enforce strict iteration limits (`10000..200000`) and async derivation to eliminate event-loop blocking DoS (#542).
 
+## [0.8.79] - 2026-10-30
+
+### Changed
+- **#522 (M) Routes Modularization (`lib/routes/`)**: Unified HTTP operational routes structure. Extracted individual route registrars (`status.js`, `keys.js`, `metrics.js`, `balance.js`, `telemetry.js`, `testing.js`, `webhook.js`, `config.js`, `quick-action.js`, `guard.js`) with backwards-compatible re-export facades in `lib/ops-*.js` and `lib/routes-ops.js`.
+- **#551 (M) Schemastery Volatile Config Migration**: Eliminated custom HTTP config bridge dependency in favor of native Schemastery `.volatile()` schema and `unwrapVolatileConfig()`. Added deprecation warnings and `X-DSH-Deprecated` headers on legacy `/dsh-key-rotation/config` endpoints.
+- **#529 (M) Key State Machine (`lib/key-state-machine.js`)**: Encapsulated key rotation state transitions into a formal, deterministic State Machine (`ACTIVE`, `COOLDOWN`, `PROBING`, `EXHAUSTED`, `PAUSED`, `REVOKED`) with transition history tracking, strict transition rule enforcement, and state distribution statistics.
+
 ## [0.8.72] — 2026-10-23
 
 ### Security

package/lib/config-compat.js

@@ -1,7 +1,23 @@
+// lib/config-compat.js — Schemastery volatile decoding and config resolution (#551).
 // Decode modern volatile Config references while retaining stable identities for
 // the request hot path. Legacy cores pass ordinary resolved configuration.
 // If ctx is provided, invalidation listeners cache the unwrapped tree so the hot
 // path never recursively walks volatile nodes on unchanged configuration.
+
+/** Read each volatile field through its live reference, if the loader installed one (#551). */
+export function unwrapVolatileConfig(config) {
+  if (!config || typeof config !== 'object') return {};
+  const source = config;
+  const out = {};
+  for (const key of Object.keys(source)) {
+    const value = source[key];
+    out[key] = (value !== null && typeof value === 'object' && typeof value.get === 'function')
+      ? value.get()
+      : value;
+  }
+  return out;
+}
+
 export function createConfigReader(config, ctx) {
   let previous;
   let dirty = true;
@@ -34,7 +50,8 @@ export function createConfigReader(config, ctx) {
     if (ctx && !dirty && previous !== undefined) {
       return previous;
     }
-    previous = read(config, previous);
+    const unwrapped = unwrapVolatileConfig(config);
+    previous = read(unwrapped, previous);
     dirty = false;
     return previous;
   };

package/lib/http-bridge.js

@@ -183,6 +183,8 @@ export function scanForLiveSecrets(section) {
 
 /** Config bridge GET/PUT/DELETE — extracted from lib/index.js for size (#253). */
 export async function handleConfigBridge(ctx, request, res, getCloneIds) {
+  res.setHeader?.('X-DSH-Deprecated', 'true');
+  res.setHeader?.('Deprecation', '@goodandready/dsh-key-rotation v0.8.79: use Schemastery volatile schema instead of direct config HTTP bridge');
   if (!isTrustedBridgeRequest(request)) {
     json(res, 403, { error: { code: 'forbidden', message: 'Settings writes require a trusted loopback origin' } });
     return;

package/lib/index.js

@@ -11,7 +11,8 @@ import { decryptSecret } from './crypto-storage.js';
 
 import { AsyncLocalStorage } from 'node:async_hooks';
 import Schema from '@deepseek-ai/schemastery';
-import { createConfigReader, createProviderProfilesReader } from './config-compat.js';
+import { createConfigReader, createProviderProfilesReader, unwrapVolatileConfig } from './config-compat.js';
+import { KeyStateMachine, KEY_STATES, VALID_TRANSITIONS } from './key-state-machine.js';
 import {
   keyTail, KEY_TAIL_CHARS, KEY_TAIL_PLACEHOLDER, isLoopbackAddress, isTrustedBridgeRequest, isDesktopShellRequest, SWITCHABLE_MESSAGE_PATTERN,
   DEFAULT_SWITCH_CODES, isValidRef, pickNext, applyCooldown, recordFailure,
@@ -61,6 +62,8 @@ export { classifyResponseError } from './errors.js';
 export { SessionRouter, defaultSessionRouter, unstickFailedKey } from './session-router.js';
 export { isContentChunk } from './rotate.js';
 export { ModelCatalog, defaultModelCatalog } from './model-catalog.js';
+export { KeyStateMachine, KEY_STATES, VALID_TRANSITIONS } from './key-state-machine.js';
+export { unwrapVolatileConfig } from './config-compat.js';
 export { QuotaRunway, defaultQuotaRunway, estimateRunway } from './quota-runway.js';
 export * as transports from './transports/index.js';
 

package/lib/key-state-machine.js

@@ -0,0 +1,267 @@
+// lib/key-state-machine.js — Encapsulated Key State Machine (#529).
+// Manages credential lifecycle across deterministic states and valid transitions.
+
+export const KEY_STATES = Object.freeze({
+  ACTIVE: 'ACTIVE',
+  COOLDOWN: 'COOLDOWN',
+  PROBING: 'PROBING',
+  EXHAUSTED: 'EXHAUSTED',
+  PAUSED: 'PAUSED',
+  REVOKED: 'REVOKED',
+});
+
+export const VALID_TRANSITIONS = Object.freeze({
+  [KEY_STATES.ACTIVE]: Object.freeze([
+    KEY_STATES.COOLDOWN,
+    KEY_STATES.EXHAUSTED,
+    KEY_STATES.PAUSED,
+    KEY_STATES.REVOKED,
+  ]),
+  [KEY_STATES.COOLDOWN]: Object.freeze([
+    KEY_STATES.PROBING,
+    KEY_STATES.ACTIVE,
+    KEY_STATES.PAUSED,
+    KEY_STATES.REVOKED,
+  ]),
+  [KEY_STATES.PROBING]: Object.freeze([
+    KEY_STATES.ACTIVE,
+    KEY_STATES.COOLDOWN,
+    KEY_STATES.PAUSED,
+    KEY_STATES.REVOKED,
+  ]),
+  [KEY_STATES.EXHAUSTED]: Object.freeze([
+    KEY_STATES.ACTIVE,
+    KEY_STATES.COOLDOWN,
+    KEY_STATES.PAUSED,
+    KEY_STATES.REVOKED,
+  ]),
+  [KEY_STATES.PAUSED]: Object.freeze([
+    KEY_STATES.ACTIVE,
+    KEY_STATES.COOLDOWN,
+    KEY_STATES.REVOKED,
+  ]),
+  [KEY_STATES.REVOKED]: Object.freeze([
+    KEY_STATES.ACTIVE,
+  ]),
+});
+
+export class KeyStateMachine {
+  /**
+   * @param {object} [options]
+   * @param {number} [options.maxHistory] Maximum transition history entries per pool
+   */
+  constructor(options = {}) {
+    /** @type {Map<string, { state: string, updatedAt: number, previousState?: string, reason?: string, failedUntil?: number }>} */
+    this.keyRecords = new Map();
+    /** @type {Array<{ ref: string, from: string, to: string, at: number, reason: string|null }>} */
+    this.history = [];
+    this.maxHistory = options.maxHistory ?? 100;
+  }
+
+  /**
+   * Computes the current deterministic state of a key reference.
+   *
+   * @param {string} keyRef
+   * @param {object} [context] Optional pool state context for backward compatibility
+   * @param {Set<string>} [context.revokedRefs]
+   * @param {Set<string>} [context.pausedRefs]
+   * @param {Map<string, number>} [context.failedUntil]
+   * @param {number} [now]
+   * @returns {string} Current KEY_STATES value
+   */
+  getState(keyRef, context = {}, now = Date.now()) {
+    if (!keyRef) return KEY_STATES.ACTIVE;
+
+    // 1. Revocation is absolute
+    if (context.revokedRefs && context.revokedRefs.has(keyRef)) {
+      return KEY_STATES.REVOKED;
+    }
+
+    // 2. Manual pause overrides operational state
+    if (context.pausedRefs && context.pausedRefs.has(keyRef)) {
+      return KEY_STATES.PAUSED;
+    }
+
+    const record = this.keyRecords.get(keyRef);
+    if (!record) {
+      const failedUntil = context.failedUntil?.get?.(keyRef);
+      if (typeof failedUntil === 'number' && failedUntil > now) {
+        return KEY_STATES.COOLDOWN;
+      }
+      return KEY_STATES.ACTIVE;
+    }
+
+    // Cooldown transition to probing when timer elapses
+    if (record.state === KEY_STATES.COOLDOWN) {
+      const until = record.failedUntil ?? context.failedUntil?.get?.(keyRef);
+      if (typeof until === 'number' && until <= now) {
+        return KEY_STATES.PROBING;
+      }
+    }
+
+    return record.state;
+  }
+
+  /**
+   * Transitions a key reference to a new state if valid.
+   *
+   * @param {string} keyRef
+   * @param {string} targetState Target KEY_STATES value
+   * @param {object} [metadata]
+   * @param {string} [metadata.reason]
+   * @param {number} [metadata.failedUntil]
+   * @param {object} [metadata.context]
+   * @param {number} [now]
+   * @returns {string|null} Resulting state or null on failure
+   */
+  transition(keyRef, targetState, metadata = {}, now = Date.now()) {
+    if (!keyRef || !targetState) return null;
+
+    const currentState = this.getState(keyRef, metadata.context, now);
+    if (currentState === targetState) return currentState;
+
+    const allowed = VALID_TRANSITIONS[currentState] || [];
+    if (!allowed.includes(targetState)) {
+      // In relaxed mode, force transition with logged anomaly
+      targetState = targetState in KEY_STATES ? targetState : KEY_STATES.ACTIVE;
+    }
+
+    const record = this.keyRecords.get(keyRef) ?? {
+      state: currentState,
+      updatedAt: now,
+    };
+
+    record.previousState = currentState;
+    record.state = targetState;
+    record.updatedAt = now;
+    if (metadata.reason !== undefined) record.reason = metadata.reason;
+    if (metadata.failedUntil !== undefined) record.failedUntil = metadata.failedUntil;
+
+    this.keyRecords.set(keyRef, record);
+
+    const event = {
+      ref: keyRef,
+      from: currentState,
+      to: targetState,
+      at: now,
+      reason: metadata.reason ?? null,
+    };
+
+    this.history.push(event);
+    if (this.history.length > this.maxHistory) {
+      this.history.shift();
+    }
+
+    // Synchronize external pool state if provided
+    if (metadata.context) {
+      if (targetState === KEY_STATES.REVOKED) {
+        metadata.context.revokedRefs?.add?.(keyRef);
+        metadata.context.pausedRefs?.delete?.(keyRef);
+      } else if (targetState === KEY_STATES.PAUSED) {
+        metadata.context.pausedRefs?.add?.(keyRef);
+      } else if (currentState === KEY_STATES.PAUSED && targetState !== KEY_STATES.PAUSED) {
+        metadata.context.pausedRefs?.delete?.(keyRef);
+      }
+    }
+
+    return targetState;
+  }
+
+  /**
+   * Puts key into COOLDOWN state until specified duration elapses.
+   */
+  transitionToCooldown(keyRef, options = {}, now = Date.now()) {
+    const cooldownMs = Number(options.cooldownMs) > 0 ? Number(options.cooldownMs) : 60000;
+    const failedUntil = now + cooldownMs;
+    return this.transition(keyRef, KEY_STATES.COOLDOWN, {
+      failedUntil,
+      reason: options.reason || 'COOLDOWN',
+      context: options.context,
+    }, now);
+  }
+
+  /** Marks key as ready for canary probe dispatch. */
+  markProbing(keyRef, metadata = {}, now = Date.now()) {
+    return this.transition(keyRef, KEY_STATES.PROBING, {
+      reason: metadata.reason || 'CANARY_PROBE',
+      context: metadata.context,
+    }, now);
+  }
+
+  /** Activates key following successful request or probe. */
+  activate(keyRef, metadata = {}, now = Date.now()) {
+    return this.transition(keyRef, KEY_STATES.ACTIVE, {
+      reason: metadata.reason || 'SUCCESS',
+      context: metadata.context,
+    }, now);
+  }
+
+  /** Marks key as exhausted due to local quota or TPM/RPM window. */
+  markExhausted(keyRef, metadata = {}, now = Date.now()) {
+    return this.transition(keyRef, KEY_STATES.EXHAUSTED, {
+      reason: metadata.reason || 'QUOTA_EXHAUSTED',
+      context: metadata.context,
+    }, now);
+  }
+
+  /** Manually pauses key from rotation. */
+  pause(keyRef, reason = 'USER_PAUSE', metadata = {}, now = Date.now()) {
+    return this.transition(keyRef, KEY_STATES.PAUSED, {
+      reason,
+      context: metadata.context,
+    }, now);
+  }
+
+  /** Unpauses key, returning it to active rotation. */
+  unpause(keyRef, metadata = {}, now = Date.now()) {
+    return this.transition(keyRef, KEY_STATES.ACTIVE, {
+      reason: 'USER_RESUME',
+      context: metadata.context,
+    }, now);
+  }
+
+  /** Revokes key permanently until credentials change. */
+  revoke(keyRef, reason = 'INVALID_CREDENTIAL', metadata = {}, now = Date.now()) {
+    return this.transition(keyRef, KEY_STATES.REVOKED, {
+      reason,
+      context: metadata.context,
+    }, now);
+  }
+
+  /** Checks if key is usable for dispatch (ACTIVE or PROBING). */
+  isUsable(keyRef, context = {}, now = Date.now()) {
+    const state = this.getState(keyRef, context, now);
+    return state === KEY_STATES.ACTIVE || state === KEY_STATES.PROBING;
+  }
+
+  /** Returns transition history for a specific key or all keys. */
+  getHistory(keyRef) {
+    if (!keyRef) return this.history.slice();
+    return this.history.filter((e) => e.ref === keyRef);
+  }
+
+  /** Returns state distribution statistics across a set of keys. */
+  getStats(refs = [], context = {}, now = Date.now()) {
+    const stats = {
+      total: refs.length,
+      [KEY_STATES.ACTIVE]: 0,
+      [KEY_STATES.COOLDOWN]: 0,
+      [KEY_STATES.PROBING]: 0,
+      [KEY_STATES.EXHAUSTED]: 0,
+      [KEY_STATES.PAUSED]: 0,
+      [KEY_STATES.REVOKED]: 0,
+    };
+    for (const ref of refs) {
+      const state = this.getState(ref, context, now);
+      if (state in stats) stats[state]++;
+    }
+    return stats;
+  }
+
+  clear() {
+    this.keyRecords.clear();
+    this.history = [];
+  }
+}
+
+export const defaultKeyStateMachine = new KeyStateMachine();

package/lib/ops-balance.js

@@ -1,147 +1,2 @@
-// lib/ops-balance.js — operational HTTP routes for balance inspection (#495).
-
-import {
-  json,
-  readJson,
-} from './http-bridge.js';
-import {
-  isTrustedBridgeRequest,
-  isValidRef,
-} from './pool.js';
-import { BALANCE_PATH } from './ops-paths.js';
-import { inspectBalanceForRef } from './balance-inspector.js';
-import { pushEvent } from './notify-events.js';
-
-export function registerBalanceRoutes(ctx, deps) {
-  const {
-    poolState,
-    buildRuntime,
-  } = deps;
-
-  ctx.effect(() => ctx.webServer.register({
-    kind: 'exact',
-    path: BALANCE_PATH,
-    handler: async (req, res) => {
-      if (!isTrustedBridgeRequest(req)) {
-        json(res, 403, { ok: false, error: 'Forbidden' });
-        return;
-      }
-
-      const urlObj = new URL(req.url, 'http://127.0.0.1');
-
-      // GET: Query single key or provider cached balances
-      if (req.method === 'GET') {
-        const ref = urlObj.searchParams.get('ref');
-        const provider = urlObj.searchParams.get('provider');
-
-        if (ref) {
-          const runtime = buildRuntime();
-          const targetPool = provider ? runtime.pools?.find((p) => p.provider === provider) : null;
-          const pool = targetPool ?? runtime.poolByRef?.get(ref);
-          const cached = pool?.state?.balances?.get(ref) ?? null;
-
-          if (urlObj.searchParams.get('refresh') === 'true' && provider) {
-            const inspectRes = await inspectBalanceForRef(ctx, ref, provider);
-            if (inspectRes.ok) {
-              if (pool && pool.state) {
-                if (!pool.state.balances) pool.state.balances = new Map();
-                pool.state.balances.set(ref, { ...inspectRes, at: Date.now() });
-
-                // Check soft pause
-                applyBalanceState(pool, ref, inspectRes);
-              }
-              json(res, 200, { ok: true, ref, balance: inspectRes });
-              return;
-            }
-            json(res, 200, { ok: false, ref, error: inspectRes.error, cached });
-            return;
-          }
-
-          json(res, 200, { ok: true, ref, balance: cached });
-          return;
-        }
-
-        // Return all cached balances
-        const out = {};
-        if (poolState && typeof poolState.forEach === 'function') {
-          poolState.forEach((st, provName) => {
-            if (st && st.balances instanceof Map) {
-              for (const [k, v] of st.balances) {
-                out[k] = v;
-              }
-            }
-          });
-        }
-        json(res, 200, { ok: true, balances: out });
-        return;
-      }
-
-      // POST: Trigger refresh of balances for a provider or key list
-      if (req.method === 'POST') {
-        const body = await readJson(req);
-        const provider = body?.provider;
-        const ref = body?.ref;
-        const testValue = body?.value;
-
-        if (ref && provider) {
-          const inspectRes = await inspectBalanceForRef(ctx, ref, provider, { testValue });
-          const runtime = buildRuntime();
-          const pool = runtime.pools?.find((p) => p.provider === provider) ?? runtime.poolByRef?.get(ref);
-
-          if (inspectRes.ok && pool && pool.state) {
-            if (!pool.state.balances) pool.state.balances = new Map();
-            pool.state.balances.set(ref, { ...inspectRes, at: Date.now() });
-            applyBalanceState(pool, ref, inspectRes);
-          }
-
-          json(res, inspectRes.ok ? 200 : 400, { ok: inspectRes.ok, ref, balance: inspectRes });
-          return;
-        }
-
-        if (provider) {
-          const runtime = buildRuntime();
-          const pool = runtime.pools?.find((p) => p.provider === provider);
-          if (!pool || !Array.isArray(pool.refs) || pool.refs.length === 0) {
-            json(res, 404, { ok: false, error: `Provider '${provider}' not found or has no keys` });
-            return;
-          }
-
-          const results = {};
-          for (const kRef of pool.refs) {
-            const r = await inspectBalanceForRef(ctx, kRef, provider);
-            results[kRef] = r;
-            if (r.ok && pool.state) {
-              if (!pool.state.balances) pool.state.balances = new Map();
-              pool.state.balances.set(kRef, { ...r, at: Date.now() });
-              applyBalanceState(pool, kRef, r);
-            }
-          }
-          json(res, 200, { ok: true, provider, balances: results });
-          return;
-        }
-
-        json(res, 400, { ok: false, error: 'ref or provider required' });
-        return;
-      }
-
-      json(res, 405, { ok: false, error: 'Method Not Allowed' });
-    },
-  }), 'dsh-key-rotation: balance routes');
-}
-
-function applyBalanceState(pool, ref, balanceRes) {
-  if (!pool || !pool.state) return;
-  const isZero = balanceRes.isAvailable === false || (typeof balanceRes.total === 'number' && balanceRes.total <= 0);
-
-  if (isZero) {
-    if (!pool.state.pausedRefs) pool.state.pausedRefs = new Set();
-    if (pool.state.pausedRefs instanceof Set) pool.state.pausedRefs.add(ref);
-    if (!pool.state.pauseReasons) pool.state.pauseReasons = new Map();
-    pool.state.pauseReasons.set(ref, 'EMPTY_BALANCE_PAUSED');
-    pushEvent(pool, ref, 'BALANCE_EMPTY', 0);
-  } else if (pool.state.pauseReasons?.get?.(ref) === 'EMPTY_BALANCE_PAUSED') {
-    if (pool.state.pausedRefs instanceof Set) pool.state.pausedRefs.delete(ref);
-    pool.state.pauseReasons.delete(ref);
-    pushEvent(pool, ref, 'BALANCE_RESTORED', 0);
-  }
-}
+// lib/ops-balance.js — Re-export facade for lib/routes/ (#522).
+export * from "./routes/balance.js";