@goodandready/dsh-key-rotation 0.8.20 → 0.8.22

package/lib/config-compat.js

@@ -0,0 +1,82 @@
+// 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.
+export function createConfigReader(config, ctx) {
+  let previous;
+  let dirty = true;
+  if (ctx && typeof ctx.on === 'function') {
+    const markDirty = () => { dirty = true; };
+    if (typeof ctx.effect === 'function') {
+      ctx.effect(() => ctx.on('settings/document-updated', markDirty));
+      ctx.effect(() => ctx.on('loader/volatile-update', markDirty));
+      ctx.effect(() => ctx.on('config', markDirty));
+    } else {
+      ctx.on('settings/document-updated', markDirty);
+      ctx.on('loader/volatile-update', markDirty);
+      ctx.on('config', markDirty);
+    }
+  }
+
+  const read = (value, held) => {
+    if (value && typeof value.get === 'function') value = value.get();
+    if (!value || typeof value !== 'object') return value;
+    const keys = Object.keys(value);
+    const next = Array.isArray(value) ? [] : {};
+    let same = held && typeof held === 'object' && Array.isArray(value) === Array.isArray(held)
+      && keys.length === Object.keys(held).length;
+    for (const key of keys) {
+      Object.defineProperty(next, key, { value: read(value[key], held?.[key]), writable: true, enumerable: true, configurable: true });
+      if (!held || !Object.hasOwn(held, key) || !Object.is(next[key], held[key])) same = false;
+    }
+    return same ? held : next;
+  };
+
+  return () => {
+    if (ctx && !dirty && previous !== undefined) {
+      return previous;
+    }
+    previous = read(config, previous);
+    dirty = false;
+    return previous;
+  };
+}
+
+// Modern settings owns descriptors rather than the removed get(namespace) API.
+// Cache by document invalidation; clone-producing describe() and tree-materializing
+// settings.get() on 0.1.7+ must not execute on every request.
+export function createProviderProfilesReader(ctx, namespace) {
+  let dirty = true, held = null, owner;
+  const markDirty = () => { dirty = true; };
+  if (typeof ctx?.effect === 'function') {
+    ctx.effect(() => ctx.on('settings/document-updated', markDirty));
+  } else if (typeof ctx?.on === 'function') {
+    ctx.on('settings/document-updated', markDirty);
+  }
+
+  return () => {
+    const settings = ctx?.get?.('settings');
+    if (settings !== owner) { owner = settings; dirty = true; }
+    if (!settings) return null;
+    if (dirty) {
+      if (typeof settings.get === 'function') {
+        try {
+          held = settings.get(namespace)?.providers ?? null;
+          dirty = false;
+        } catch (_) {
+          held = null;
+          dirty = false;
+        }
+      } else {
+        try {
+          held = settings.describe({ redactSecrets: true }).find(row => row.ns === namespace)?.value?.providers ?? null;
+          dirty = false;
+        } catch (_) {
+          held = null;
+          dirty = false;
+        }
+      }
+    }
+    return held;
+  };
+}

package/lib/http-bridge.js

@@ -1,6 +1,7 @@
 // lib/http-bridge.js — shared HTTP helpers for dsh-key-rotation routes.
 import { findSecrets } from './keycheck.js';
 import { isTrustedBridgeRequest } from './pool.js';
+import { mutateSettings, plainObject, requireRevision, sectionOps, validateOps } from './settings-write.js';
 
 export const NS = 'dsh-key-rotation';
 
@@ -9,18 +10,37 @@ export function json(res, status, obj) {
   res.end(JSON.stringify(obj));
 }
 
-export function readJson(request) {
+export function readJson(request, maxBytes = 1024 * 1024) {
   return new Promise((resolve, reject) => {
-    let raw = '';
-    request.on('data', (c) => { raw += c; });
-    request.on('end', () => {
-      try {
-        resolve(JSON.parse(raw || '{}'));
-      } catch (e) {
-        reject(e);
+    let size = 0;
+    const chunks = [];
+    const off = (evt, fn) => {
+      if (typeof request?.off === 'function') request.off(evt, fn);
+      else if (typeof request?.removeListener === 'function') request.removeListener(evt, fn);
+    };
+    const cleanup = () => {
+      off('data', onData); off('end', onEnd);
+      off('error', onError); off('aborted', onAborted);
+    };
+    const onError = (error) => { cleanup(); reject(error); };
+    const onAborted = () => onError(new Error('Request body was aborted'));
+    const onData = (chunk) => {
+      const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      size += bytes.length;
+      if (size > maxBytes) {
+        onError(Object.assign(new Error('Request body exceeds the 1 MiB limit'), { status: 413 }));
+        request.resume();
+        return;
       }
-    });
-    request.on('error', reject);
+      chunks.push(bytes);
+    };
+    const onEnd = () => {
+      cleanup();
+      try { resolve(JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}')); }
+      catch (error) { reject(error); }
+    };
+    request.on('data', onData); request.on('end', onEnd);
+    request.on('error', onError); request.on('aborted', onAborted);
   });
 }
 
@@ -42,14 +62,20 @@ export function viewOf(descriptor, settings) {
   };
 }
 
-export async function writeSection(ctx, ns, section, expectedRevision, res) {
+export async function writeSection(ctx, ns, section, expectedRevision, res, reset = false) {
   const settings = ctx.get('settings');
   if (settings === void 0) {
     json(res, 503, { error: { code: 'settings-rejected', message: 'dsh-key-rotation: no settings provider is mounted' } });
     return;
   }
   try {
-    await settings.replace(ns, section, expectedRevision);
+    if (reset) {
+      // DELETE is the explicit reset API; an ordinary save/import never comes here.
+      await settings.replace(ns, {}, expectedRevision);
+    } else {
+      const ops = Array.isArray(section) ? validateOps(section) : sectionOps(section);
+      await mutateSettings(settings, ns, ops, expectedRevision);
+    }
   } catch (error) {
     if (error?.code === 'SETTINGS_CONFLICT') {
       json(res, 409, { error: { code: 'settings-conflict', message: `dsh-key-rotation: changed elsewhere (expected revision ${String(error.expected)}, current ${String(error.actual)}); reload and retry` } });
@@ -89,8 +115,7 @@ 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) {
   if (!isTrustedBridgeRequest(request)) {
-    res.writeHead(403);
-    res.end();
+    json(res, 403, { error: { code: 'forbidden', message: 'Settings writes require a trusted loopback origin' } });
     return;
   }
   const method = request.method ?? 'GET';
@@ -128,17 +153,20 @@ export async function handleConfigBridge(ctx, request, res, getCloneIds) {
       try {
         body = await readJson(request);
       } catch (error) {
-        json(res, 400, { error: { code: 'settings-rejected', message: `dsh-key-rotation: invalid request body: ${error instanceof Error ? error.message : String(error)}` } });
+        json(res, error?.status === 413 ? 413 : 400, { error: { code: 'settings-rejected', message: `dsh-key-rotation: invalid request body: ${error instanceof Error ? error.message : String(error)}` } });
         return;
       }
-      if (typeof body !== 'object' || body === null || typeof body.section !== 'object' || body.section === null || Array.isArray(body.section)) {
-        json(res, 400, { error: { code: 'settings-rejected', message: 'dsh-key-rotation: PUT requires {"section": {...}}' } });
+      try {
+        if (!plainObject(body) || (Object.hasOwn(body, 'ops') === Object.hasOwn(body, 'section'))) {
+          throw new TypeError('PUT requires exactly one of {ops: [...]} or {section: {...}}');
+        }
+        section = Object.hasOwn(body, 'ops') ? validateOps(body.ops) : sectionOps(body.section);
+      } catch (error) {
+        json(res, 400, { error: { code: 'settings-rejected', message: error.message } });
         return;
       }
-      section = body.section;
-      expectedRevision = typeof body.expectedRevision === 'number' ? body.expectedRevision : void 0;
       try {
-        const findings = scanForLiveSecrets(section);
+        const findings = findSecrets(JSON.stringify(section.filter(op => !['webhookActionToken', 'notifyWebhook'].includes(op.path[0]))));
         if (findings.length > 0) {
           json(res, 400, {
             error: {
@@ -152,11 +180,17 @@ export async function handleConfigBridge(ctx, request, res, getCloneIds) {
       } catch {
         /* scanning must never block a valid save */
       }
+      try {
+        expectedRevision = requireRevision(body.expectedRevision);
+      } catch (error) {
+        json(res, 400, { error: { code: 'settings-rejected', message: error.message } });
+        return;
+      }
     } else {
       section = {};
       expectedRevision = void 0;
     }
-    await writeSection(ctx, NS, section, expectedRevision, res);
+    await writeSection(ctx, NS, section, expectedRevision, res, method === 'DELETE');
     return;
   }
   json(res, 405, { error: { code: 'method', message: 'GET, PUT, or DELETE only' } });

package/lib/index.js

@@ -6,6 +6,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,
   DEFAULT_SWITCH_CODES, isValidRef, pickNext, applyCooldown, recordFailure,
@@ -73,7 +74,7 @@ const { ensureSandboxRunner, probeRef, lastTestCache } = sandboxService;
 
 const DEFAULT_PROVIDERS = [];
 
-export const Config = Schema.object({
+const SettingsSchema = Schema.object({
   switchCodes: Schema.array(Schema.string()).default([...DEFAULT_SWITCH_CODES]),
   cooldownMs: Schema.number().default(60000),
   maxCooldownMs: Schema.number(),
@@ -130,6 +131,15 @@ export const Config = Schema.object({
   })).default([...DEFAULT_PROVIDERS]),
 });
 
+// New settings derives editable forms from volatile entry Config fields. Keep
+// initialization-only persistence options ordinary (restart-bound) and retain a
+// plain schema for old namespace registration. Older schemastery has no volatile.
+export const Config = typeof Schema.number().volatile === 'function'
+  ? Schema.object(Object.fromEntries(Object.entries(SettingsSchema.dict).map(([name, field]) => [
+    name, ['persistenceEnabled', 'persistencePath'].includes(name) ? field : field.volatile(),
+  ])))
+  : SettingsSchema;
+
 function registerConfigBridge(ctx, getCloneIds) {
   return ctx.webServer.register({
     kind: 'exact',
@@ -140,14 +150,16 @@ function registerConfigBridge(ctx, getCloneIds) {
         res.end(JSON.stringify({ error: 'Method Not Allowed' }));
         return;
       }
-      handleConfigBridge(ctx, req, res, getCloneIds);
+      return handleConfigBridge(ctx, req, res, getCloneIds);
     },
   });
 }
 
 export function apply(ctx, config = {}) {
   const logger = getLogger(ctx);
-  getConfig = () => config;
+  const readEntryConfig = createConfigReader(config, ctx);
+  getConfig = readEntryConfig;
+  const readProfiles = createProviderProfilesReader(ctx, PIAI_NS);
   registerConfigBridge(ctx, () => buildRuntime().cloneIds);
   ensureSandboxRunner(ctx);
 
@@ -210,7 +222,7 @@ export function apply(ctx, config = {}) {
     const cfg = getConfig() ?? {};
     let profilesSnapshot = null;
     try {
-      profilesSnapshot = ctx.get('settings')?.get(PIAI_NS)?.providers ?? null;
+      profilesSnapshot = readProfiles();
     } catch {
       profilesSnapshot = null;
     }
@@ -276,7 +288,7 @@ export function apply(ctx, config = {}) {
 
     let profiles = {};
     try {
-      profiles = ctx.get('settings')?.get(PIAI_NS)?.providers ?? {};
+      profiles = profilesSnapshot ?? {};
     } catch { /* settings not mounted yet */ }
     for (const [provider, profile] of Object.entries(profiles)) {
       if (profile?.apiKeyEnv && poolByRef.has(profile.apiKeyEnv)) {
@@ -536,14 +548,13 @@ export function apply(ctx, config = {}) {
 
   ctx.inject(['settings'], (sctx) => {
     const settingsSvc = sctx.get('settings');
-    if (!settingsSvc || typeof settingsSvc.register !== 'function') {
-      logger.warn('[dsh-key-rotation] settings service unavailable — config scope not registered');
-      return;
+    // Modern SettingsForms already owns this Loader entry's volatile Config.
+    // Legacy SettingsProvider instead needs a plain namespace registration.
+    if (typeof settingsSvc?.register !== 'function') return;
+    const scope = settingsSvc.register(NS, SettingsSchema, { base: readEntryConfig() });
+    getConfig = () => scope.get() ?? readEntryConfig();
+    if (typeof sctx?.effect === 'function') {
+      sctx.effect(() => () => { getConfig = readEntryConfig; });
     }
-    const scope = settingsSvc.register(NS, Config, { base: config });
-    getConfig = () => scope.get() ?? config;
-    sctx.effect(() => () => {
-      getConfig = () => config;
-    });
   });
 }

package/lib/lifecycle.js

@@ -4,11 +4,11 @@ import { StatePersistence, resolveStatePath } from './persistence.js';
 import path from 'node:path';
 import { envValue } from './pool.js';
 
-export function setupIdleHealEffect(ctx, getConfig, buildRuntime) {
+export function setupIdleHealEffect(ctx, getConfig, buildRuntime, timers = globalThis) {
   return ctx.effect(() => {
-    const cfg = getConfig();
-    if (!cfg || cfg.selfHealCooldown === false) return () => {};
-    const timer = setInterval(() => {
+    // Keep the cheap scheduler alive so a disabled-at-start preference can be
+    // enabled later without restarting the plugin.
+    const timer = timers.setInterval(() => {
       try {
         const c = getConfig();
         if (!c || c.selfHealCooldown === false) return;
@@ -21,20 +21,17 @@ export function setupIdleHealEffect(ctx, getConfig, buildRuntime) {
       } catch (_) { /* ponytail: never crash the timer */ }
     }, 60000);
     if (typeof timer.unref === 'function') timer.unref();
-    return () => clearInterval(timer);
+    return () => timers.clearInterval(timer);
   }, 'dsh-key-rotation: self-healing idle');
 }
 
-export function setupAutoUnbreakEffect(ctx, getConfig, buildRuntime, ensureSandboxRunner, logger) {
+export function setupAutoUnbreakEffect(ctx, getConfig, buildRuntime, ensureSandboxRunner, logger, timers = globalThis) {
   return ctx.effect(() => {
-    const cfg = getConfig();
-    const intervalMin = cfg?.selfHealingIntervalMinutes ?? 30;
-    if (!intervalMin || intervalMin <= 0) return () => {};
-    const intervalMs = intervalMin * 60 * 1000;
+    let timer, intervalMs;
     let running = false;
     let disposed = false;
     const isActive = () => !disposed && (getConfig()?.selfHealingIntervalMinutes ?? 0) > 0;
-    const timer = setInterval(async () => {
+    const run = async () => {
       if (running || disposed) return;
       running = true;
       try {
@@ -55,9 +52,26 @@ export function setupAutoUnbreakEffect(ctx, getConfig, buildRuntime, ensureSandb
         }, Date.now(), { isActive });
       } catch (e) { logger?.warn?.('[dsh-key-rotation] auto-unbreak failed', e); }
       finally { running = false; }
-    }, intervalMs);
-    if (typeof timer.unref === 'function') timer.unref();
-    return () => { disposed = true; clearInterval(timer); };
+    };
+    const configure = () => {
+      if (disposed) return;
+      const minutes = getConfig()?.selfHealingIntervalMinutes ?? 30;
+      const next = Number.isFinite(minutes) && minutes > 0
+        ? Math.max(1000, Math.min(2147483647, minutes * 60000)) : 0;
+      if (next === intervalMs) return;
+      if (timer !== undefined) timers.clearInterval(timer);
+      intervalMs = next;
+      timer = next ? timers.setInterval(run, next) : undefined;
+      timer?.unref?.();
+    };
+    const changed = () => queueMicrotask(configure);
+    const off = [
+      typeof ctx?.on === 'function' ? ctx.on('settings/document-updated', changed) : () => {},
+      typeof ctx?.on === 'function' ? ctx.on('loader/volatile-update', changed) : () => {},
+    ];
+    configure();
+    return () => { disposed = true; if (timer !== undefined) timers.clearInterval(timer); for (const stop of off) stop(); };
+
   }, 'dsh-key-rotation: auto-unbreak');
 }
 

package/lib/ops-keys.js

@@ -10,6 +10,7 @@ import {
   keyTail,
 } from './pool.js';
 import { looksLikeApiSecret } from './keycheck.js';
+import { mutateSettings, validateProviders } from './settings-write.js';
 import { bestEffort } from './best-effort.js';
 import {
   KEY_PATH,
@@ -170,20 +171,21 @@ ctx.effect(() => ctx.webServer.register({
       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();
-      if (!Array.isArray(data)) { json(res, 400, { error: { code: 'bad-format', message: 'dsh-key-rotation: expected JSON array of providers' } }); return; }
+      validateProviders(data);
       const settings = ctx.get('settings');
       if (!settings) { json(res, 503, { error: { code: 'settings-rejected', message: 'dsh-key-rotation: no settings provider' } }); return; }
       const desc = settings.describe({ redactSecrets: true }).find((c) => c.ns === NS);
-      const cur = desc?.value?.providers ?? [];
+      if (!desc) throw new Error('Settings namespace is unavailable');
+      const cur = desc.value?.providers ?? [];
       const merged = new Map();
       for (const p of cur) if (p && p.provider) merged.set(p.provider, p);
       for (const p of data) if (p && p.provider && typeof p.provider === 'string') merged.set(p.provider, p);
       const mergedArr = [...merged.values()];
-      await settings.replace(NS, { ...(desc?.value ?? {}), providers: mergedArr }, desc?.revision);
+      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';
-      json(res, isTimeout ? 504 : 400, { error: { code: isTimeout ? 'timeout' : 'import-failed', message: String(e?.message ?? e) } });
+      json(res, isTimeout ? 504 : e?.code === 'SETTINGS_CONFLICT' ? 409 : 400, { error: { code: isTimeout ? 'timeout' : 'import-failed', message: String(e?.message ?? e) } });
     }
   },
 }), 'dsh-key-rotation: import route');

package/lib/ops-telemetry.js

@@ -15,6 +15,7 @@ import {
   SNAPSHOT_PATH,
 } from './ops-paths.js';
 import { findSecrets } from './keycheck.js';
+import { mutateSettings, sectionOps } from './settings-write.js';
 
 /**
  * @param {object} ctx cordis context
@@ -96,12 +97,11 @@ ctx.effect(() => ctx.webServer.register({
     if (!settings) { json(res, 503, { error: { code: 'settings-rejected', message: 'dsh-key-rotation: no settings provider' } }); return; }
     const desc = descriptorOf(ctx, NS);
     if (desc === void 0) { json(res, 500, { error: { code: 'settings-rejected', message: 'dsh-key-rotation: namespace missing' } }); return; }
-    const cur = desc.value ?? {};
-    // empty token fields in the file keep the current values (never wipe a secret)
-    const merged = { ...cur, ...snap };
-    if (!snap.webhookActionToken) merged.webhookActionToken = cur.webhookActionToken ?? '';
     try {
-      await settings.replace(NS, merged, desc.revision);
+      // Empty exported tokens mean omitted, not erased. Never reconstruct a
+      // complete section from the redacted describe response.
+      const ops = sectionOps(snap, { preserveEmptySecrets: true });
+      await mutateSettings(settings, NS, ops, body.expectedRevision ?? desc.revision);
       const after = descriptorOf(ctx, NS);
       json(res, 200, { ok: true, revision: after?.revision });
     } catch (e) {

package/lib/pool-builder.js

@@ -23,9 +23,15 @@ export function buildPoolItem({
   rpmLimit,
   makeState,
 }) {
-  const refs = (keys ?? []).filter((ref) => typeof ref === 'string' && isValidRef(ref.trim()));
+  const seen = new Set();
+  const indexed = (Array.isArray(keys) ? keys : []).map((key, index) => ({ ref: typeof key === 'string' ? key.trim() : '', index }))
+    .filter(({ ref }) => { if (!isValidRef(ref) || seen.has(ref)) return false; seen.add(ref); return true; });
+  const refs = indexed.map(item => item.ref);
   if (refs.length === 0) return null;
-  const w = Array.isArray(weights) ? weights : [];
+  const w = indexed.map(({ index }) => {
+    const value = Array.isArray(weights) ? weights[index] : undefined;
+    return Number.isFinite(value) && value > 0 ? Math.max(1, Math.min(1000, Math.floor(value))) : 1;
+  });
   const weightedRefs = [];
   for (let i = 0; i < refs.length; i++) {
     const ww = typeof w[i] === 'number' && w[i] > 0 ? Math.floor(w[i]) : 1;
@@ -34,7 +40,7 @@ export function buildPoolItem({
   const parsedExpiry = {};
   if (Array.isArray(expiresAt)) {
     for (let i = 0; i < refs.length; i++) {
-      const exp = parseExpiry(expiresAt[i]);
+      const exp = parseExpiry(expiresAt[indexed[i].index]);
       if (exp !== undefined) parsedExpiry[refs[i]] = exp;
     }
   }

package/lib/pool.js

@@ -16,7 +16,7 @@ export function keyTail(key) {
 export function isLoopbackAddress(ip) {
   if (!ip || typeof ip !== 'string') return false;
   if (ip === '127.0.0.1' || ip === '::1' || ip === '::ffff:127.0.0.1') return true;
-  if (ip.startsWith('127.')) return true;
+  if (/^127(?:\.(?:0|[1-9]\d{0,2})){3}$/.test(ip) && ip.split('.').every(part => Number(part) <= 255)) return true;
   return false;
 }
 
@@ -32,7 +32,8 @@ export function isTrustedBridgeRequest(req) {
   try {
     const originUrl = new URL(origin);
     if (originUrl.host !== hostHeader) return false;
-    return isLoopbackAddress(originUrl.hostname) || originUrl.hostname === 'localhost';
+    const hostname = originUrl.hostname.replace(/^\[|\]$/g, '');
+    return ['http:', 'https:'].includes(originUrl.protocol) && (isLoopbackAddress(hostname) || hostname === 'localhost');
   } catch (_) {
     return false;
   }

package/lib/settings-write.js

@@ -0,0 +1,77 @@
+// 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 UNSAFE_FIELDS = new Set(['__proto__', 'prototype', 'constructor']);
+
+export function plainObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+export 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;
+  if (Array.isArray(value)) { for (const item of value) assertJson(item, depth + 1); return; }
+  if (plainObject(value)) {
+    for (const [key, child] of Object.entries(value)) {
+      if (UNSAFE_FIELDS.has(key)) throw new TypeError('Unsafe configuration field');
+      assertJson(child, depth + 1);
+    }
+    return;
+  }
+  throw new TypeError('Configuration must contain finite JSON-compatible values');
+}
+
+export function sectionOps(section, { preserveEmptySecrets = false } = {}) {
+  if (!plainObject(section)) throw new TypeError('Expected a configuration object');
+  assertJson(section);
+  if (Object.hasOwn(section, 'providers')) validateProviders(section.providers);
+  return Object.entries(section)
+    .filter(([key, value]) => !(preserveEmptySecrets && SECRET_FIELDS.has(key) && (value === '' || value === null)))
+    .map(([key, value]) => ({ op: 'set', path: [key], value }));
+}
+
+export function validateOps(ops) {
+  if (!Array.isArray(ops) || ops.length > 1000) throw new TypeError('Expected at most 1000 field operations');
+  for (const op of ops) {
+    if (!plainObject(op) || !['set', 'unset'].includes(op.op) || !Array.isArray(op.path)
+      || !op.path.length || op.path.length > 40
+      || op.path.some(part => typeof part !== 'string' || !part || UNSAFE_FIELDS.has(part))) {
+      throw new TypeError('Expected set/unset operations with non-empty, safe field paths');
+    }
+    if (op.op === 'set') {
+      assertJson(op.value);
+      if (op.path.length === 1 && op.path[0] === 'providers') validateProviders(op.value);
+    }
+  }
+  return ops;
+}
+
+export function requireRevision(revision) {
+  if (!Number.isSafeInteger(revision) || revision < 0) throw new TypeError('A non-negative expectedRevision from the latest read is required');
+  return revision;
+}
+
+export async function mutateSettings(settings, ns, ops, expectedRevision) {
+  validateOps(ops);
+  requireRevision(expectedRevision);
+  if (typeof settings?.mutate !== 'function') throw new Error('This host does not provide atomic field mutation');
+  // Do not retry with replace or drop the revision fence after a refusal.
+  await settings.mutate(ns, ops, expectedRevision);
+}
+
+export function validateProviders(providers) {
+  if (!Array.isArray(providers)) throw new TypeError('Expected an array of provider key pools');
+  assertJson(providers);
+  const names = new Set();
+  for (const provider of providers) {
+    if (!plainObject(provider) || typeof provider.provider !== 'string' || !provider.provider.trim()
+      || names.has(provider.provider) || !Array.isArray(provider.keys) || new Set(provider.keys).size !== provider.keys.length || provider.keys.some(key => typeof key !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))) {
+      throw new TypeError('Each provider must have a unique name and valid, unique credential reference names');
+    }
+    names.add(provider.provider);
+  }
+  return providers;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-key-rotation",
-  "version": "0.8.20",
+  "version": "0.8.22",
   "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": [
@@ -61,6 +61,12 @@
     "@deepseek-ai/dsh-llm": "^0.1.0-rc.6"
   },
   "scripts": {
-    "test": "node --test --test-timeout=10000 test/*.test.js test/*.test.mjs"
+    "test": "node tools/test.mjs",
+    "test:core": "node tools/test.mjs --core",
+    "check": "node tools/check.mjs"
+  },
+  "devDependencies": {
+    "react": "18.3.1",
+    "react-test-renderer": "18.3.1"
   }
 }