@goodandready/dsh-key-rotation 0.8.51 → 0.8.53

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.8.53 - 2026-10-09
+
+### Fixed
+- **Official DSH Desktop Build Compatibility (#465, GitHub #22)**:
+  - Fixed issue where all mutating routes (POST, PUT, DELETE) answered `403 "forbidden"` inside the official DSH Desktop application (reported by @onech1cken in GitHub #22).
+  - The Desktop shell (`dsh-app://app/`) uses `forwardWebRequest` proxying which strips the `Origin` header before forwarding requests to the in-process server.
+  - `isTrustedBridgeRequest` now permits absent `Origin` headers (`origin === undefined`) for mutating requests when the remote peer address is verified loopback (`127.0.0.1`, `::1`, `::ffff:127.0.0.1`) and the `Host` header is verified loopback/localhost with no cross-site fetch metadata (`sec-fetch-site !== cross-site`). Real web browsers unconditionally attach `Origin` to cross-origin writes, preventing CSRF.
+  - Explicitly allowed `dsh-app://app` origin when forwarded by Desktop shell.
+  - Preserved strict fail-closed security for non-loopback clients, DNS rebinding, malformed origins, and cross-site requests.
+
+## 0.8.52 - 2026-10-07
+
+### Added
+- **Key Pinning (`pinnedRef`) with Resilient Failover Bypass (#455)**:
+  - Added `pinnedRef` (alias `useKeyRef`) to provider settings schema and pool builder.
+  - In key selection (`lib/resolver.js` and `lib/rotate.js`), healthy pinned keys are prioritized first.
+  - When a pinned key enters cooldown, is paused/revoked, or runs out of token quota, requests automatically and seamlessly bypass the pin to rotate among remaining healthy keys, preventing agent stalls.
+- **User-Defined Key Labels (#456)**:
+  - Added `labels` string array aligned with provider `keys` in settings schema and pool models.
+  - Exposed per-key in `GET /dsh-key-rotation/status` (`label` field) and provider overview.
+  - Displayed as visual tag badges in WebUI settings card.
+- **Secure Plaintext Key Reveal Endpoint (#457)**:
+  - Added `GET /dsh-key-rotation/key?ref=...` in `lib/ops-keys.js` with loopback and same-origin validation (`isTrustedBridgeRequest`).
+  - Decrypts and returns `{ ref, plaintext, tail }` for operator auditing and copying without raw disk inspection.
+- **In-Memory Client Diagnostics Ring Buffer (#458)**:
+  - Added bounded 200-entry diagnostics ring buffer and `/dsh-key-rotation/diag` route in `lib/ops-telemetry.js`.
+  - Ingests frontend runtime errors and fetch failures via `POST /diag` and retrieves log entries via `GET /diag`.
+
+### Changed
+- **PeerDependencies Triplet SemVer Range (#459)**:
+  - Updated `@deepseek-ai/dsh-llm` peer dependency range to `^0.1.7-rc.2 || >=0.2.0-rc.1 <0.2.1-0` in `package.json` to prevent peer dependency warnings across DSH `0.2.0-rc.*` releases.
+
 ## 0.8.51 - 2026-10-06
 
 ### Fixed

package/lib/client.js

@@ -1886,6 +1886,12 @@ window.__ModuleLoader__.load({
             h('span', { key: 'd', className: 'krot-dot', style: { background: st ? st.color : 'var(--dsw-alias-border-l2)' } }),
             h('span', { key: 's', className: 'krot-state' }, st ? st.text : ''),
           ];
+          if (info && info.pinned) {
+            meta.push(h('span', { key: 'pin', className: 'krot-state', title: 'Pinned key' }, '📌'));
+          }
+          if (info && info.label) {
+            meta.push(h('span', { key: 'lbl', className: 'krot-tag', title: 'Key label' }, info.label));
+          }
           if (fromEnv) {
             meta.push(h('span', { key: 'v', className: 'krot-tail', title: t('keyFromEnv') },
               info.tail ? '••••' + info.tail : t('keyFromEnv')));

package/lib/index.js

@@ -118,6 +118,8 @@ const SettingsSchema = Schema.object({
     revoked: Schema.array(Schema.boolean()).default([]),
     expiresAt: Schema.array(Schema.union([Schema.number(), Schema.string()])).default([]),
     tags: Schema.array(Schema.string()).default([]),
+    labels: Schema.array(Schema.string()).default([]),
+    pinnedRef: Schema.string().default(''),
     costBudgetDaily: Schema.number(),
     costBudgetWeekly: Schema.number(),
     pauseOnBudget: Schema.boolean().default(false),

package/lib/ops-keys.js

@@ -10,6 +10,7 @@ import {
   isTrustedBridgeRequest,
   isValidRef,
   keyTail,
+  envValue,
 } from './pool.js';
 import { looksLikeApiSecret } from './keycheck.js';
 import { mutateSettings, validateProviders } from './settings-write.js';
@@ -43,8 +44,8 @@ ctx.effect(() => ctx.webServer.register({
   kind: 'exact',
   path: KEY_PATH,
   handler: async (req, res) => {
-    if (req.method !== 'PUT' && req.method !== 'DELETE') {
-      json(res, 405, { error: { code: 'method', message: 'PUT or DELETE only' } });
+    if (req.method !== 'PUT' && req.method !== 'DELETE' && req.method !== 'GET') {
+      json(res, 405, { error: { code: 'method', message: 'GET, PUT or DELETE only' } });
       return;
     }
     if (!isTrustedBridgeRequest(req)) {
@@ -52,6 +53,30 @@ ctx.effect(() => ctx.webServer.register({
       return;
     }
     const credentialsService = ctx.get('credentials');
+    if (req.method === 'GET') {
+      const url = new URL(req.url, 'http://127.0.0.1');
+      const ref = url.searchParams.get('ref')?.trim();
+      if (!isValidRef(ref)) {
+        json(res, 400, { error: { code: 'bad-ref', message: 'dsh-key-rotation: ref must be an environment variable name' } });
+        return;
+      }
+      try {
+        let hit = await (credentialsService?.__dshKeyRotationOriginalResolve ?? credentialsService?.resolve)?.call(credentialsService, ref);
+        let raw = hit?.value;
+        if (!raw) {
+          raw = envValue(ref);
+        }
+        if (!raw) {
+          json(res, 404, { error: { code: 'not-found', message: `dsh-key-rotation: secret for "${ref}" not found` } });
+          return;
+        }
+        const plain = decryptSecret(raw);
+        json(res, 200, { ref, plaintext: plain, tail: keyTail(plain) });
+      } catch (err) {
+        json(res, 500, { error: { code: 'reveal-failed', message: String(err?.message ?? err) } });
+      }
+      return;
+    }
     if (!credentialsService || typeof credentialsService.set !== 'function') {
       json(res, 503, { error: { code: 'no-credentials', message: 'dsh-key-rotation: no credentials service is mounted' } });
       return;

package/lib/ops-paths.js

@@ -10,3 +10,4 @@ export const TEST_PATH = '/dsh-key-rotation/test';
 export const SANDBOX_CACHE_PATH = '/dsh-key-rotation/sandbox-cache';
 export const WEBHOOK_ACTION_PATH = '/dsh-key-rotation/webhook-action';
 export const METRICS_PATH = '/dsh-key-rotation/metrics';
+export const DIAG_PATH = '/dsh-key-rotation/diag';

package/lib/ops-status.js

@@ -127,6 +127,8 @@ ctx.effect(() => ctx.webServer.register({
         providerName: pool.provider ?? providerOfBase(pool.base),
         basePool: basePool?.base ?? null,
         model: pool.model ?? null,
+        pinnedRef: pool.pinnedRef ?? null,
+        labels: pool.labels ?? {},
         quotasConfigured: hasModelQuotaConfig(pool),
         keys,
         tags: providerTags?.get?.(pool.base) ?? [],

package/lib/ops-telemetry.js

@@ -13,6 +13,7 @@ import {
 import {
   USAGE_PATH,
   SNAPSHOT_PATH,
+  DIAG_PATH,
 } from './ops-paths.js';
 import { findSecrets } from './keycheck.js';
 import { mutateSettings, sectionOps } from './settings-write.js';
@@ -21,6 +22,24 @@ import { mutateSettings, sectionOps } from './settings-write.js';
  * @param {object} ctx cordis context
  * @param {object} deps live dependencies from apply()
  */
+
+const DIAG_BUFFER_LIMIT = 200;
+const diagBuffer = [];
+
+export function pushDiag(entry) {
+  if (diagBuffer.length >= DIAG_BUFFER_LIMIT) {
+    diagBuffer.shift();
+  }
+  diagBuffer.push({
+    timestamp: Date.now(),
+    ...entry,
+  });
+}
+
+export function getDiagBuffer() {
+  return diagBuffer.slice();
+}
+
 export function registerTelemetryRoutes(ctx, deps) {
   const {
     buildRuntime,
@@ -111,4 +130,34 @@ ctx.effect(() => ctx.webServer.register({
   },
 }), 'dsh-key-rotation: snapshot route');
 
+ctx.effect(() => ctx.webServer.register({
+  kind: 'exact',
+  path: DIAG_PATH,
+  handler: async (req, res) => {
+    if (req.method !== 'GET' && req.method !== 'POST') {
+      json(res, 405, { error: { code: 'method', message: 'GET or POST only' } });
+      return;
+    }
+    if (!isTrustedBridgeRequest(req)) {
+      json(res, 403, { error: { code: 'forbidden', message: 'dsh-key-rotation: diag is local-only' } });
+      return;
+    }
+    if (req.method === 'POST') {
+      let body;
+      try { body = await readJson(req); } catch (e) {
+        json(res, 400, { error: { code: 'bad-request', message: String(e?.message ?? e) } });
+        return;
+      }
+      pushDiag({
+        level: typeof body?.level === 'string' ? body.level : 'info',
+        message: typeof body?.message === 'string' ? body.message.slice(0, 500) : 'unknown',
+        details: body?.details ?? null,
+      });
+      json(res, 200, { ok: true, count: diagBuffer.length });
+      return;
+    }
+    json(res, 200, { diag: getDiagBuffer() });
+  },
+}), 'dsh-key-rotation: diag route');
+
 }

package/lib/pool-builder.js

@@ -33,6 +33,9 @@ export function buildPoolItem({
   model = null,
   quotas = null,
   quotaResetWindow = null,
+  labels = null,
+  pinnedRef = null,
+  useKeyRef = null,
 }) {
   const seen = new Set();
   const indexed = (Array.isArray(keys) ? keys : []).map((key, index) => ({ ref: typeof key === 'string' ? key.trim() : '', index }))
@@ -84,6 +87,21 @@ export function buildPoolItem({
   for (let i = 0; i < refs.length; i++) {
     weightsMap[refs[i]] = typeof w[i] === 'number' && w[i] > 0 ? Math.floor(w[i]) : 1;
   }
+  const labelsMap = {};
+  if (Array.isArray(labels)) {
+    for (let i = 0; i < refs.length; i++) {
+      const lbl = labels[indexed[i].index];
+      if (typeof lbl === 'string' && lbl.trim()) labelsMap[refs[i]] = lbl.trim();
+    }
+  } else if (labels && typeof labels === 'object') {
+    for (let i = 0; i < refs.length; i++) {
+      const lbl = labels[refs[i]];
+      if (typeof lbl === 'string' && lbl.trim()) labelsMap[refs[i]] = lbl.trim();
+    }
+  }
+  const cleanPinned = typeof pinnedRef === 'string' && pinnedRef.trim()
+    ? pinnedRef.trim()
+    : (typeof useKeyRef === 'string' && useKeyRef.trim() ? useKeyRef.trim() : null);
   const normalizedQuotas = normalizeModelQuotas(quotas);
   return {
     base,
@@ -107,6 +125,8 @@ export function buildPoolItem({
     concurrencyLimit: typeof concurrencyLimit === 'number' && Number.isFinite(concurrencyLimit) && concurrencyLimit > 0 ? Math.floor(concurrencyLimit) : 0,
     routingStrategy: poolStrategy,
     proactiveRateLimitGuard: poolGuard,
+    labels: labelsMap,
+    pinnedRef: cleanPinned,
   };
 }
 
@@ -145,6 +165,8 @@ export function buildPools({ cfg = {}, poolState = new Map(), defaultState = ini
     const pool = buildPool(p.provider, p.keys, p.weights, p.paused, p.revoked, poolCooldown, poolMax, p.expiresAt, p.routingStrategy, p.proactiveRateLimitGuard, {
       provider: p.provider,
       model: null,
+      labels: p.labels,
+      pinnedRef: p.pinnedRef ?? p.useKeyRef,
     }, provRpm, provTpm, provConcurrency);
     if (pool) {
       for (const ref of pool.refs) {
@@ -171,6 +193,8 @@ export function buildPools({ cfg = {}, poolState = new Map(), defaultState = ini
         provider: p.provider,
         model,
         quotas: mp.quotas,
+        labels: mp.labels ?? p.labels,
+        pinnedRef: mp.pinnedRef ?? mp.useKeyRef ?? p.pinnedRef ?? p.useKeyRef,
       }, modelRpm, modelTpm, modelConcurrency);
       if (!mpool) continue;
       mpool.basePool = pool;

package/lib/pool.js

@@ -42,12 +42,19 @@ export function isTrustedBridgeRequest(req) {
   if (!(isLoopbackAddress(hostName) || hostName === 'localhost')) return false;
 
   const origin = req?.headers?.origin;
-  if (!origin) {
-    const method = String(req?.method ?? 'GET').toUpperCase();
-    return method === 'GET' || method === 'HEAD' || method === 'OPTIONS';
+  if (origin === undefined) {
+    // Official Desktop build forwards requests via forwardWebRequest which strips Origin (#465 / GitHub #22).
+    // Real browsers unconditionally send Origin on cross-origin mutations, so an absent Origin cannot originate
+    // from a malicious website. Peer address and Host header are already verified loopback above.
+    return true;
   }
+  if (!origin) return false; // Explicit empty string or null-like falsy
   try {
     const originUrl = new URL(origin);
+    // Official Desktop build shell origin
+    if (originUrl.protocol === 'dsh-app:' && (originUrl.host === 'app' || originUrl.hostname === 'app')) {
+      return true;
+    }
     if (originUrl.host !== hostHeader) return false;
     const hostname = originUrl.hostname.replace(/^\[|\]$/g, '');
     return ['http:', 'https:'].includes(originUrl.protocol) && (isLoopbackAddress(hostname) || hostname === 'localhost');

package/lib/resolver.js

@@ -125,7 +125,16 @@ export function createResolver({
     // original credential must never be used as a bypass. Decided once, before
     // the loop, so it cannot be re-evaluated mid-iteration.
     const quotaManaged = hasModelQuotaConfig(pool) && isQuotaManagedRequest(runtime.index, ref, requested);
-    const start = strategy === 'round-robin' ? (pool.state.pointer ?? 0) : 0;
+    let start = strategy === 'round-robin' ? (pool.state.pointer ?? 0) : 0;
+    if (pool.pinnedRef && list.includes(pool.pinnedRef)) {
+      const pIdx = list.indexOf(pool.pinnedRef);
+      if (pIdx > 0) {
+        list = list.slice();
+        list.splice(pIdx, 1);
+        list.unshift(pool.pinnedRef);
+      }
+      start = 0;
+    }
 
     for (let i = 0; i < list.length; i++) {
       const index = (start + i) % list.length;

package/lib/rotate.js

@@ -89,6 +89,13 @@ export function createRotate(deps) {
       const quotaManaged = hasModelQuotaConfig(pool);
       let attemptList = (pool.weightedRefs ?? pool.refs).slice();
       attemptList = attemptList.filter((r) => !isKeyPaused(pool, r) && !isKeyRevoked(pool, r) && !isKeyBroken(pool, r, wallNow));
+      if (pool.pinnedRef && attemptList.includes(pool.pinnedRef)) {
+        const pIdx = attemptList.indexOf(pool.pinnedRef);
+        if (pIdx > 0) {
+          attemptList.splice(pIdx, 1);
+          attemptList.unshift(pool.pinnedRef);
+        }
+      }
       if (quotaManaged) {
         attemptList = attemptList.filter((ref) => isModelQuotaAvailable(pool, ref, wallNow));
         if (attemptList.length === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-key-rotation",
-  "version": "0.8.51",
+  "version": "0.8.53",
   "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": [
@@ -57,7 +57,7 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-llm": "^0.1.7-rc.2 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.7-rc.2 || >=0.2.0-rc.1 <0.2.1-0",
     "@deepseek-ai/schemastery": "^3.18.4"
   },
   "scripts": {