@goodandready/dsh-key-rotation 0.8.82 → 0.8.84

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.8.83 (2026-10-31)
+
+### TypeScript Migration & Type-Safe Core Architecture (Block 11 Release)
+- **TypeScript Server-Side Architecture (Issue #524)**: Migrated server-side codebase to TypeScript with `src/` directory structure, strict `tsconfig.json`, and `tsdown` build pipeline generating `lib/index.d.ts`.
+- **Domain Type Definitions (`src/types/`)**: Defined comprehensive TypeScript types for configuration schemas (`PoolConfig`, `ModelQuotaConfig`, `FailoverConfig`, `PluginConfig`), pool & key state machines (`KeyState`, `KeyStatus`, `PoolItem`, `ResolvedKey`, `RoutingDecision`, `QuotaWindow`), and Cordis service interaction contracts (`Context`, `LlmService`, `WebServerService`, `SettingsService`, `CredentialsService`).
+- **Static Type Safety & Tooling**: Integrated `npm run typecheck` (`tsc --noEmit`) into `npm run check`, guaranteeing compile-time type safety across all configuration fields, service bindings, and event handlers with 0 errors.
+- **Zero Runtime Dependencies**: All TypeScript build tools (`typescript`, `tsdown`, `@types/node`) maintained strictly in `devDependencies`, with `dependencies: {}` preserved.
+
 ## 0.8.82 (2026-10-30)
 
 ### Modernized UI Builder & JSX Pipeline (Block 10 Release)

package/lib/index.js

@@ -36,6 +36,7 @@ import { CircuitBreaker } from './circuit-breaker.js';
 import { NotifyQueue } from './notify-queue.js';
 import { classifyFailure } from './error-taxonomy.js';
 import { registerOpsRoutes } from './routes-ops.js';
+import { getWebServer } from './routes/guard.js';
 import { registerPluginUpdater } from './plugin-updater.js';
 import { notifySwitch, notifyExhaustion, notifyEarlyWarning, pushEvent } from './notify-events.js';
 import { QUOTA_WINDOW_TYPES } from './quota-window.js';
@@ -178,7 +179,7 @@ export const Config = typeof Schema.number().volatile === 'function'
   : SettingsSchema;
 
 function registerConfigBridge(ctx, getCloneIds) {
-  return ctx.webServer.register({
+  return getWebServer(ctx).register({
     kind: 'exact',
     path: CONFIG_PATH,
     handler: (req, res) => {
@@ -246,9 +247,11 @@ export function apply(ctx, config = {}) {
 
   setupAutoUnbreakEffect(ctx, getConfig, buildRuntime, ensureSandboxRunner, logger);
 
-  // Dynamic webServer registration (#528)
+  // Dynamic webServer registration (#528, #567)
   const setupWebRoutes = (webCtx = ctx) => {
-    const target = webCtx?.webServer ? webCtx : ctx;
+    const target = getWebServer(webCtx) ? webCtx : ctx;
+    const ws = getWebServer(target);
+    if (!ws) return;
     registerConfigBridge(target, () => buildRuntime().cloneIds);
     registerOpsRoutes(target, {
       buildRuntime,
@@ -265,7 +268,7 @@ export function apply(ctx, config = {}) {
       selectionTraceStore,
       diagBuffer,
     });
-    if (typeof target.webServer?.register === 'function') {
+    if (typeof ws?.register === 'function') {
       registerPluginUpdater(target, {
         endpoint: '/api/dsh-key-rotation/update',
         packageName: '@goodandready/dsh-key-rotation',
@@ -274,10 +277,12 @@ export function apply(ctx, config = {}) {
     }
   };
 
-  if (ctx.webServer) {
+  if (Object.prototype.hasOwnProperty.call(ctx, 'webServer') && ctx.webServer) {
     setupWebRoutes(ctx);
   } else if (typeof ctx.inject === 'function') {
     ctx.inject(['webServer'], setupWebRoutes);
+  } else if (getWebServer(ctx)) {
+    setupWebRoutes(ctx);
   }
 
   // Periodic sweep of expired cooldowns

package/lib/lifecycle.js

@@ -45,7 +45,7 @@ export function setupAutoUnbreakEffect(ctx, getConfig, buildRuntime, ensureSandb
         await autoUnbreakBrokenKeys(pools, async (ref) => {
           // A rotating resolver can substitute a healthy neighbor for this
           // quarantined ref, falsely proving that the broken key recovered.
-          const credentials = ctx.get?.('credentials') ?? ctx.credentials;
+          const credentials = (typeof ctx?.get === 'function' ? ctx.get('credentials') : undefined) ?? (ctx && Object.prototype.hasOwnProperty.call(ctx, 'credentials') ? ctx.credentials : undefined);
           const resolve = credentials?.__dshKeyRotationOriginalResolve ?? credentials?.resolve;
           const hit = await resolve?.call(credentials, ref);
           const raw = typeof hit?.value === 'string' && hit.value.length > 0
@@ -197,7 +197,7 @@ export function setupProactiveHealthProbeEffect(ctx, getConfig, buildRuntime, en
           for (const ref of candidates) {
             if (disposed) break;
             try {
-              const credentials = ctx.get?.('credentials') ?? ctx.credentials;
+              const credentials = (typeof ctx?.get === 'function' ? ctx.get('credentials') : undefined) ?? (ctx && Object.prototype.hasOwnProperty.call(ctx, 'credentials') ? ctx.credentials : undefined);
               const resolve = credentials?.__dshKeyRotationOriginalResolve ?? credentials?.resolve;
               const hit = await resolve?.call(credentials, ref);
               const raw = typeof hit?.value === 'string' && hit.value.length > 0 ? hit.value : envValue(ref);

package/lib/plugin-updater.js

@@ -314,7 +314,10 @@ function json(response, statusCode, value) {
 
 export function registerPluginUpdater(ctx, options) {
   let installing = false
-  return ctx.webServer.register({
+  const viaOwn = ctx && Object.prototype.hasOwnProperty.call(ctx, 'webServer') && typeof ctx.webServer?.register === 'function' ? ctx.webServer : undefined
+  const viaGet = typeof ctx?.get === 'function' ? ctx.get('webServer') : undefined
+  const ws = viaOwn ?? (typeof viaGet?.register === 'function' ? viaGet : undefined) ?? ctx?.webServer
+  return ws.register({
     kind: 'exact',
     path: options.endpoint,
     handler: async (request, response) => {

package/lib/routes/balance.js

@@ -1,3 +1,4 @@
+import { getWebServer } from './guard.js';
 // lib/ops-balance.js — operational HTTP routes for balance inspection (#495).
 
 import {
@@ -18,7 +19,7 @@ export function registerBalanceRoutes(ctx, deps) {
     buildRuntime,
   } = deps;
 
-  ctx.effect(() => ctx.webServer.register({
+  ctx.effect(() => getWebServer(ctx).register({
     kind: 'exact',
     path: BALANCE_PATH,
     handler: async (req, res) => {

package/lib/routes/config.js

@@ -1,3 +1,4 @@
+import { getWebServer } from './guard.js';
 // lib/ops-config-io.js — full configuration export and import (#504).
 import crypto from 'node:crypto';
 import { readFileSync } from 'node:fs';
@@ -187,7 +188,7 @@ export function diffConfigs(currentConfig, incomingConfig, mode = 'merge') {
 
 export function registerConfigIoRoutes(ctx, deps) {
   // ── GET & POST /dsh-key-rotation/export (#552: support POST for safe passphrase transmission) ──
-  ctx.effect(() => ctx.webServer.register({
+  ctx.effect(() => getWebServer(ctx).register({
     kind: 'exact',
     path: CONFIG_EXPORT_PATH,
     handler: async (req, res) => {
@@ -448,7 +449,7 @@ export function registerConfigIoRoutes(ctx, deps) {
     });
   };
 
-  ctx.effect(() => ctx.webServer.register({
+  ctx.effect(() => getWebServer(ctx).register({
     kind: 'exact',
     path: CONFIG_IMPORT_PATH,
     handler: handleImport,

package/lib/routes/guard.js

@@ -11,3 +11,26 @@ export {
   json,
   readJson,
 } from '../http-bridge.js';
+
+/**
+ * Safely resolve webServer from a Cordis context or test mock without
+ * triggering Cordis's Proxy trap (`cannot get property "webServer" without inject`)
+ * when `webServer` is provided by a sibling plugin and not in static `inject`.
+ */
+export function getWebServer(ctx) {
+  if (!ctx) return undefined;
+  if (Object.prototype.hasOwnProperty.call(ctx, 'webServer') && typeof ctx.webServer?.register === 'function') {
+    return ctx.webServer;
+  }
+  if (typeof ctx.get === 'function') {
+    const viaGet = ctx.get('webServer');
+    if (typeof viaGet?.register === 'function') return viaGet;
+  }
+  try {
+    const ws = ctx.webServer;
+    if (typeof ws?.register === 'function') return ws;
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}

package/lib/routes/keys.js

@@ -1,3 +1,4 @@
+import { getWebServer } from './guard.js';
 import { decryptSecret, encryptSecret } from '../crypto-storage.js';
 // lib/ops-keys.js — key store + cooldown reset + import routes (#312 split from routes-ops.js).
 import {
@@ -156,7 +157,7 @@ export async function discoverUnconfiguredKeys(ctx, runtimePools = []) {
 
 export function registerKeyRoutes(ctx, deps) {
 
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: DRAIN_PATH,
   handler: async (req, res) => {
@@ -219,7 +220,7 @@ ctx.effect(() => ctx.webServer.register({
 // it is never sent back, only its last few characters are (see the status
 // route) — and the route is loopback- and same-origin-gated like the config
 // bridge next to it.
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: KEY_PATH,
   handler: async (req, res) => {
@@ -289,7 +290,7 @@ ctx.effect(() => ctx.webServer.register({
 
 
 // ── reset route: clear cooldown for a provider (or a single ref) ──
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: RESET_PATH,
   handler: async (req, res) => {
@@ -374,7 +375,7 @@ ctx.effect(() => ctx.webServer.register({
 }), 'dsh-key-rotation: reset route');
 
 
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: IMPORT_PATH,
   handler: async (req, res) => {
@@ -411,7 +412,7 @@ ctx.effect(() => ctx.webServer.register({
 // Health for external panels (Beszel/Uptime)
 
 // ── discover unconfigured keys route (#491) ──
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: DISCOVER_PATH,
   handler: async (req, res) => {
@@ -434,7 +435,7 @@ ctx.effect(() => ctx.webServer.register({
 }), 'dsh-key-rotation: discover route');
 
 // ── auto-import discovered keys into pools (#491) ──
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: AUTO_IMPORT_PATH,
   handler: async (req, res) => {
@@ -528,7 +529,7 @@ ctx.effect(() => ctx.webServer.register({
   },
 }), 'dsh-key-rotation: auto-import route');
 
-  ctx.effect(() => ctx.webServer.register({
+  ctx.effect(() => getWebServer(ctx).register({
     kind: 'exact',
     path: PRESET_LIMITS_PATH,
     handler: async (req, res) => {

package/lib/routes/metrics.js

@@ -1,3 +1,4 @@
+import { getWebServer } from './guard.js';
 // lib/ops-metrics.js — Prometheus / OpenMetrics export route (#373).
 import { METRICS_PATH } from './paths.js';
 import { isTrustedBridgeRequest, isKeyPaused, isKeyRevoked } from '../pool.js';
@@ -10,7 +11,7 @@ import { hasModelQuotaConfig, isModelQuotaAvailable } from '../model-quota.js';
 export function registerMetricsRoutes(ctx, deps) {
   const { buildRuntime, poolState } = deps;
 
-  ctx.effect(() => ctx.webServer.register({
+  ctx.effect(() => getWebServer(ctx).register({
     kind: 'exact',
     path: METRICS_PATH,
     handler: async (req, res) => {

package/lib/routes/quick-action.js

@@ -1,3 +1,4 @@
+import { getWebServer } from './guard.js';
 import { json, readJson, isTrustedBridgeRequest } from '../http-bridge.js';
 import { QUICK_ACTION_PATH } from './paths.js';
 import { keyTail, isKeyPaused } from '../pool.js';
@@ -9,7 +10,7 @@ import { keyTail, isKeyPaused } from '../pool.js';
 export function registerQuickActionRoutes(ctx, deps) {
   const { buildRuntime, pushEvent, circuitBreaker } = deps;
 
-  ctx.effect(() => ctx.webServer.register({
+  ctx.effect(() => getWebServer(ctx).register({
     kind: 'exact',
     path: QUICK_ACTION_PATH,
     handler: async (req, res) => {

package/lib/routes/status.js

@@ -1,3 +1,4 @@
+import { getWebServer } from './guard.js';
 import { getModelQuotaStatus, isModelQuotaAvailable, hasModelQuotaConfig } from '../model-quota.js';
 import { providerOfBase, basePoolForBase, modelPoolsForRef } from '../pool-index.js';
 import { decryptSecret } from '../crypto-storage.js';
@@ -44,7 +45,7 @@ export function registerStatusRoutes(ctx, deps) {
 // (a typo is otherwise silent), and how often rotation has fired.
 //
 // Key VALUES never leave the host — only the boolean fact that one exists.
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: STATUS_PATH,
   handler: async (req, res) => {
@@ -204,7 +205,7 @@ ctx.effect(() => ctx.webServer.register({
 // #209: usage report - per-key requests/cost over the last N days.
 // ?format=csv returns text/csv; ?days=N window (1..90, default 7).
 
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: HEALTH_PATH,
   handler: async (req, res) => {

package/lib/routes/telemetry.js

@@ -1,3 +1,4 @@
+import { getWebServer } from './guard.js';
 // lib/ops-telemetry.js — usage + snapshot operational routes (#312 split from routes-ops.js).
 import {
   json,
@@ -71,7 +72,7 @@ export function registerTelemetryRoutes(ctx, deps) {
     buildRuntime,
   } = deps;
 
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: USAGE_PATH,
   handler: (req, res) => {
@@ -116,7 +117,7 @@ ctx.effect(() => ctx.webServer.register({
 // Secret values never travel: only credential/env names. Token fields are
 // exported as empty strings; on import they keep existing values when empty.
 
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: SNAPSHOT_PATH,
   handler: async (req, res) => {
@@ -162,7 +163,7 @@ ctx.effect(() => ctx.webServer.register({
 }), 'dsh-key-rotation: snapshot route');
 
 
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: TRACE_PATH,
   handler: (req, res) => {
@@ -187,7 +188,7 @@ ctx.effect(() => ctx.webServer.register({
 }), 'dsh-key-rotation: trace route');
 
 
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: SIMULATE_PATH,
   handler: async (req, res) => {
@@ -243,7 +244,7 @@ ctx.effect(() => ctx.webServer.register({
   },
 }), 'dsh-key-rotation: simulate route');
 
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: DIAG_PATH,
   handler: async (req, res) => {

package/lib/routes/testing.js

@@ -1,3 +1,4 @@
+import { getWebServer } from './guard.js';
 // lib/ops-test.js — sandbox test + sandbox cache routes (#312 split from routes-ops.js).
 import {
   json,
@@ -29,7 +30,7 @@ export function registerTestRoutes(ctx, deps) {
   } = deps;
 
 // ── test route: dry-run a single key without rotation ──
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: TEST_PATH,
   handler: async (req, res) => {
@@ -105,7 +106,7 @@ ctx.effect(() => ctx.webServer.register({
 // straight through.
 // Read-only cache snapshot for clients (badge polling).
 
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: SANDBOX_CACHE_PATH,
   handler: (req, res) => {
@@ -125,7 +126,7 @@ ctx.effect(() => ctx.webServer.register({
 // cannot be same-origin, so a shared secret is the gate).
 
 // ── test matrix route: batch probe all configured keys (#490) ──
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: TEST_MATRIX_PATH,
   handler: async (req, res) => {

package/lib/routes/webhook.js

@@ -1,3 +1,4 @@
+import { getWebServer } from './guard.js';
 import crypto from 'node:crypto';
 // lib/ops-webhook.js — webhook interactive action route (#312 split from routes-ops.js, #388 telegram secret-token & answerCallbackQuery).
 import {
@@ -36,7 +37,7 @@ export function registerWebhookActionRoute(ctx, deps) {
     circuitBreaker,
   } = deps;
 
-ctx.effect(() => ctx.webServer.register({
+ctx.effect(() => getWebServer(ctx).register({
   kind: 'exact',
   path: WEBHOOK_ACTION_PATH,
   handler: async (req, res) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-key-rotation",
-  "version": "0.8.82",
+  "version": "0.8.84",
   "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": [
@@ -24,7 +24,10 @@
   "type": "module",
   "main": "lib/index.js",
   "exports": {
-    ".": "./lib/index.js",
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
     "./client": "./lib/client.js",
     "./transports": "./lib/transports/index.js",
     "./catalog": "./lib/model-catalog.js",
@@ -60,16 +63,19 @@
     "node": ">=18"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-llm": "^0.1.7-rc.2 || >=0.2.0-rc.1 <0.2.1-0 || >=0.2.1-alpha.1 <0.2.2-0",
-    "@deepseek-ai/schemastery": "^3.18.4"
+    "@deepseek-ai/cordis": "^4.0.1 || >=4.0.6-alpha.1 <5.0.0-0",
+    "@deepseek-ai/dsh-llm": "^0.1.7-rc.2 || >=0.2.0-rc.1 <0.2.1-0 || >=0.2.1-alpha.1 <0.2.2-0 || >=0.2.2-alpha.1 <0.2.3-0",
+    "@deepseek-ai/schemastery": "^3.18.4 || >=3.18.6-alpha.1 <4.0.0-0"
   },
   "scripts": {
     "test": "node tools/test.mjs",
     "test:core": "node tools/test.mjs --core",
-    "check": "node tools/check.mjs",
+    "check": "npm run typecheck && node tools/check.mjs",
     "build:client": "node scripts/build-client.mjs",
-    "pretest": "node scripts/build-client.mjs"
+    "pretest": "node scripts/build-client.mjs",
+    "typecheck": "tsc --noEmit",
+    "build:server": "tsdown",
+    "build": "npm run build:server && npm run build:client"
   },
   "devDependencies": {
     "react": "18.3.1",
@@ -78,7 +84,11 @@
     "@deepseek-ai/dsh-llm": "^0.2.0-rc.2",
     "@deepseek-ai/schemastery": "^3.18.4",
     "semver": "^7.6.3",
-    "esbuild": "^0.28.2"
+    "esbuild": "^0.28.2",
+    "typescript": "^5.7.2",
+    "tsdown": "^0.22.14",
+    "@types/node": "^22.0.0"
   },
-  "dependencies": {}
+  "dependencies": {},
+  "types": "./lib/index.d.ts"
 }