@goodandready/dsh-key-rotation 0.8.78 → 0.8.80

package/CHANGELOG.md

@@ -55,6 +55,20 @@
 - **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.80] - 2026-10-30
+
+### Changed
+- **#530 (M) Domain Core Layer (`lib/core/`)**: Structured domain core modules under `lib/core/` (`state-machine.js`, `concurrency.js`, `quota.js`, `pool.js`, `rotate.js`, `index.js`) while maintaining transparent backwards-compatible root facades.
+- **#528 (M) Cordis Dynamic Dependency Injection**: Reduced required static `inject` array to minimal `['llm']`. Wrapped HTTP routes and WebServer lifecycle in `ctx.inject(['webServer'], ...)`, enabling fully headless/CLI operation without crashing when WebServer or settings are unmounted.
+- **#525 (M) Append-Only Event Journal Persistence**: Introduced incremental append-only event journaling (`*-journal.jsonl`) alongside debounced periodic atomic snapshots. Eliminates heavy O(N) full state tree disk rewrites on routine key switches and cooldowns, automatically compacting and rotating upon snapshot flush.
+
+## [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/concurrency.js

@@ -1,115 +1,2 @@
-// concurrency.js — per-key in-flight counter + least-connections picking (issues #193, #407, #463).
-
-const CONCURRENCY_DEFAULT_LIMIT = 0;
-// Default stale timeout: 30 minutes to support prolonged streaming generation (#463)
-const CONCURRENCY_STALE_LOCK_MS = 30 * 60 * 1000;
-
-export class ConcurrencyTracker {
-  constructor(opts) {
-    opts = opts || {};
-    const limit = opts.limit !== undefined ? opts.limit : CONCURRENCY_DEFAULT_LIMIT;
-    this._limit = (Number.isFinite(limit) && limit >= 0) ? Math.floor(limit) : 0;
-    this._staleMs = opts.staleMs || CONCURRENCY_STALE_LOCK_MS;
-    this._inFlight = new Map();
-  }
-
-  configure(opts) {
-    if (!opts) return;
-    if (opts.limit !== undefined) {
-      this._limit = (Number.isFinite(opts.limit) && opts.limit >= 0) ? Math.floor(opts.limit) : 0;
-    }
-    if (opts.staleMs !== undefined && Number.isFinite(opts.staleMs) && opts.staleMs > 0) {
-      this._staleMs = opts.staleMs;
-    }
-  }
-
-  isEnabled() { return this._limit > 0; }
-  get limit() { return this._limit; }
-
-  acquire(ref, now, limit) {
-    now = now || Date.now();
-    const effectiveLimit = (typeof limit === 'number' && limit >= 0) ? Math.floor(limit) : this._limit;
-    let e = this._inFlight.get(ref);
-    if (!e) {
-      e = { count: 0, lastAcquired: now };
-      this._inFlight.set(ref, e);
-    }
-    if (now - e.lastAcquired > this._staleMs) {
-      e.count = 0;
-    }
-    if (effectiveLimit > 0 && e.count >= effectiveLimit) return false;
-    e.count += 1;
-    e.lastAcquired = now;
-    return true;
-  }
-
-  touch(ref, now) {
-    now = now || Date.now();
-    const e = this._inFlight.get(ref);
-    if (e && e.count > 0) {
-      e.lastAcquired = now;
-    }
-  }
-
-  release(ref, now) {
-    now = now || Date.now();
-    const e = this._inFlight.get(ref);
-    if (!e) return;
-    e.count = Math.max(0, e.count - 1);
-    e.lastAcquired = now;
-  }
-
-  getActive(ref, now) {
-    now = now || Date.now();
-    if (!ref) return 0;
-    const e = this._inFlight.get(ref);
-    if (!e) return 0;
-    if (now - e.lastAcquired > this._staleMs) {
-      e.count = 0;
-      return 0;
-    }
-    return e.count;
-  }
-
-  snapshot(now) {
-    now = now || Date.now();
-    const out = {};
-    for (const [k, v] of this._inFlight) {
-      let count = v.count;
-      if (now - v.lastAcquired > this._staleMs) {
-        count = 0;
-        v.count = 0;
-      }
-      out[k] = { count };
-    }
-    return out;
-  }
-
-  pickLeastLoaded(candidates, now, weights, limit) {
-    now = now || Date.now();
-    const effectiveLimit = (typeof limit === 'number' && limit >= 0) ? Math.floor(limit) : this._limit;
-    if (!Array.isArray(candidates) || candidates.length === 0) return null;
-    let best = null;
-    let bestScore = Infinity;
-    for (const ref of candidates) {
-      const e = this._inFlight.get(ref);
-      let count = e ? e.count : 0;
-      if (e && now - e.lastAcquired > this._staleMs) count = 0;
-      if (effectiveLimit > 0 && count >= effectiveLimit) continue;
-      const w = (weights && Number(weights[ref]) > 0) ? Number(weights[ref]) : 1;
-      const score = count / w;
-      if (score < bestScore) {
-        best = ref;
-        bestScore = score;
-      }
-    }
-    return best;
-  }
-
-  clear(ref) {
-    if (ref) this._inFlight.delete(ref);
-    else this._inFlight.clear();
-  }
-
-  get size() { return this._inFlight.size; }
-}
+// lib/concurrency.js — Backwards-compatible facade (#530).
+export * from './core/concurrency.js';

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/core/concurrency.js

@@ -0,0 +1,115 @@
+// concurrency.js — per-key in-flight counter + least-connections picking (issues #193, #407, #463).
+
+const CONCURRENCY_DEFAULT_LIMIT = 0;
+// Default stale timeout: 30 minutes to support prolonged streaming generation (#463)
+const CONCURRENCY_STALE_LOCK_MS = 30 * 60 * 1000;
+
+export class ConcurrencyTracker {
+  constructor(opts) {
+    opts = opts || {};
+    const limit = opts.limit !== undefined ? opts.limit : CONCURRENCY_DEFAULT_LIMIT;
+    this._limit = (Number.isFinite(limit) && limit >= 0) ? Math.floor(limit) : 0;
+    this._staleMs = opts.staleMs || CONCURRENCY_STALE_LOCK_MS;
+    this._inFlight = new Map();
+  }
+
+  configure(opts) {
+    if (!opts) return;
+    if (opts.limit !== undefined) {
+      this._limit = (Number.isFinite(opts.limit) && opts.limit >= 0) ? Math.floor(opts.limit) : 0;
+    }
+    if (opts.staleMs !== undefined && Number.isFinite(opts.staleMs) && opts.staleMs > 0) {
+      this._staleMs = opts.staleMs;
+    }
+  }
+
+  isEnabled() { return this._limit > 0; }
+  get limit() { return this._limit; }
+
+  acquire(ref, now, limit) {
+    now = now || Date.now();
+    const effectiveLimit = (typeof limit === 'number' && limit >= 0) ? Math.floor(limit) : this._limit;
+    let e = this._inFlight.get(ref);
+    if (!e) {
+      e = { count: 0, lastAcquired: now };
+      this._inFlight.set(ref, e);
+    }
+    if (now - e.lastAcquired > this._staleMs) {
+      e.count = 0;
+    }
+    if (effectiveLimit > 0 && e.count >= effectiveLimit) return false;
+    e.count += 1;
+    e.lastAcquired = now;
+    return true;
+  }
+
+  touch(ref, now) {
+    now = now || Date.now();
+    const e = this._inFlight.get(ref);
+    if (e && e.count > 0) {
+      e.lastAcquired = now;
+    }
+  }
+
+  release(ref, now) {
+    now = now || Date.now();
+    const e = this._inFlight.get(ref);
+    if (!e) return;
+    e.count = Math.max(0, e.count - 1);
+    e.lastAcquired = now;
+  }
+
+  getActive(ref, now) {
+    now = now || Date.now();
+    if (!ref) return 0;
+    const e = this._inFlight.get(ref);
+    if (!e) return 0;
+    if (now - e.lastAcquired > this._staleMs) {
+      e.count = 0;
+      return 0;
+    }
+    return e.count;
+  }
+
+  snapshot(now) {
+    now = now || Date.now();
+    const out = {};
+    for (const [k, v] of this._inFlight) {
+      let count = v.count;
+      if (now - v.lastAcquired > this._staleMs) {
+        count = 0;
+        v.count = 0;
+      }
+      out[k] = { count };
+    }
+    return out;
+  }
+
+  pickLeastLoaded(candidates, now, weights, limit) {
+    now = now || Date.now();
+    const effectiveLimit = (typeof limit === 'number' && limit >= 0) ? Math.floor(limit) : this._limit;
+    if (!Array.isArray(candidates) || candidates.length === 0) return null;
+    let best = null;
+    let bestScore = Infinity;
+    for (const ref of candidates) {
+      const e = this._inFlight.get(ref);
+      let count = e ? e.count : 0;
+      if (e && now - e.lastAcquired > this._staleMs) count = 0;
+      if (effectiveLimit > 0 && count >= effectiveLimit) continue;
+      const w = (weights && Number(weights[ref]) > 0) ? Number(weights[ref]) : 1;
+      const score = count / w;
+      if (score < bestScore) {
+        best = ref;
+        bestScore = score;
+      }
+    }
+    return best;
+  }
+
+  clear(ref) {
+    if (ref) this._inFlight.delete(ref);
+    else this._inFlight.clear();
+  }
+
+  get size() { return this._inFlight.size; }
+}

package/lib/core/index.js

@@ -0,0 +1,6 @@
+// lib/core/index.js — Unified Domain Core Layer (#530).
+export * from './state-machine.js';
+export * from './concurrency.js';
+export * from './quota.js';
+export * from './pool.js';
+export * from './rotate.js';

package/lib/core/pool.js

@@ -0,0 +1,2 @@
+// lib/core/pool.js — Core pool exports (#530).
+export * from '../pool.js';

package/lib/core/quota.js

@@ -0,0 +1,39 @@
+// lib/quota.js — quota-remaining persistence per ref.
+// ponytail: pure helpers, snapshot() returns shallow copies.
+
+export class QuotaStore {
+  constructor() {
+    this._data = new Map(); // ref -> { remaining, limit, reset, at }
+  }
+
+  set(ref, info) {
+    if (!ref) return;
+    if (!info || typeof info !== 'object') return;
+    const next = {
+      remaining: Number.isFinite(info.remaining) ? info.remaining : null,
+      limit: Number.isFinite(info.limit) ? info.limit : null,
+      reset: Number.isFinite(info.reset) ? info.reset : null,
+      at: Number.isFinite(info.at) ? info.at : Date.now(),
+    };
+    this._data.set(ref, next);
+  }
+
+  get(ref) {
+    return this._data.get(ref);
+  }
+
+  snapshot() {
+    const out = {};
+    for (const [k, v] of this._data) out[k] = v;
+    return out;
+  }
+
+  clear(ref) {
+    if (ref) this._data.delete(ref);
+    else this._data.clear();
+  }
+
+  get size() {
+    return this._data.size;
+  }
+}

package/lib/core/rotate.js

@@ -0,0 +1,2 @@
+// lib/core/rotate.js — Core rotation engine exports (#530).
+export * from '../rotate.js';

package/lib/core/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/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;