@goodandready/dsh-key-rotation 0.8.77 → 0.8.79

package/lib/routes/webhook.js

@@ -0,0 +1,218 @@
+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 {
+  json,
+  readJson,
+} from '../http-bridge.js';
+import { bestEffort } from '../best-effort.js';
+import { WEBHOOK_ACTION_PATH } from './paths.js';
+import { resolveAction } from '../webhook.js';
+
+function constantTimeEqual(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') return false;
+  const aBuf = Buffer.from(a);
+  const bBuf = Buffer.from(b);
+  return aBuf.length === bBuf.length && crypto.timingSafeEqual(aBuf, bBuf);
+}
+
+function getHeader(headers, name) {
+  if (!headers || typeof headers !== 'object') return '';
+  const target = name.toLowerCase();
+  for (const [k, v] of Object.entries(headers)) {
+    if (k.toLowerCase() === target) return String(v ?? '');
+  }
+  return '';
+}
+
+/**
+ * @param {object} ctx cordis context
+ * @param {object} deps live dependencies from apply()
+ */
+export function registerWebhookActionRoute(ctx, deps) {
+  const {
+    buildRuntime,
+    poolState,
+    setRotationDisabled,
+    circuitBreaker,
+  } = deps;
+
+ctx.effect(() => ctx.webServer.register({
+  kind: 'exact',
+  path: WEBHOOK_ACTION_PATH,
+  handler: async (req, res) => {
+    if (req.method !== 'POST') { json(res, 405, { error: { code: 'method', message: 'POST only' } }); return; }
+    const runtime = buildRuntime();
+    const expected = runtime.webhookActionToken;
+    if (!expected) { json(res, 503, { error: { code: 'no-token', message: 'dsh-key-rotation: webhookActionToken is not configured' } }); return; }
+
+    const authHeader = getHeader(req.headers, 'authorization');
+    const secretHeader = getHeader(req.headers, 'x-telegram-bot-api-secret-token');
+    const bearerMatch = constantTimeEqual(authHeader, `Bearer ${expected}`);
+    const secretMatch = constantTimeEqual(secretHeader, expected);
+    if (!bearerMatch && !secretMatch) {
+      json(res, 401, { error: { code: 'unauthorized', message: 'dsh-key-rotation: bad webhook action token' } });
+      return;
+    }
+
+    let body;
+    try { body = await readJson(req); } catch (e) { json(res, 400, { error: { code: 'bad-request', message: String(e?.message ?? e) } }); return; }
+
+    // #222 / #388: Telegram setWebhook registration helper
+    if (typeof body?.setWebhook === 'object' && body.setWebhook) {
+      const botToken = typeof body.setWebhook.botToken === 'string' ? body.setWebhook.botToken : '';
+      if (!botToken) { json(res, 400, { error: { code: 'bad-request', message: 'dsh-key-rotation: setWebhook.botToken required' } }); return; }
+      const TELEGRAM_BOT_TOKEN_RE = /^[0-9]{5,16}:[a-zA-Z0-9_-]{20,50}$/;
+      if (!TELEGRAM_BOT_TOKEN_RE.test(botToken)) {
+        json(res, 400, { error: { code: 'bad-request', message: 'dsh-key-rotation: invalid telegram bot token format' } });
+        return;
+      }
+      const rawUrl = typeof body.setWebhook.url === 'string' ? body.setWebhook.url.trim() : '';
+      if (!rawUrl || !rawUrl.startsWith('https://')) {
+        json(res, 400, { error: { code: 'bad-request', message: 'dsh-key-rotation: explicit public https url required in setWebhook.url' } });
+        return;
+      }
+      try {
+        const hookRes = await fetch(`https://api.telegram.org/bot${botToken}/setWebhook`, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({
+            url: rawUrl,
+            secret_token: expected,
+            allowed_updates: ['callback_query'],
+          }),
+          signal: AbortSignal.timeout(10000),
+        });
+        const hookData = await hookRes.json().catch(() => ({}));
+        json(res, 200, { ok: hookRes.ok, url: rawUrl, secret_token_set: true, telegram: hookData });
+      } catch (e) {
+        json(res, 502, { error: { code: 'telegram-failed', message: String(e?.message ?? e) } });
+      }
+      return;
+    }
+
+    const callbackQueryId = typeof body?.callback_query?.id === 'string'
+      ? body.callback_query.id
+      : (typeof body?.callback_query?.id === 'number' ? String(body.callback_query.id) : '');
+    const botToken = typeof body?.botToken === 'string' ? body.botToken : '';
+
+    const respond = async (statusCode, payload, answerText) => {
+      if (callbackQueryId) {
+        payload.method = 'answerCallbackQuery';
+        payload.callback_query_id = callbackQueryId;
+        payload.text = answerText || payload.error?.message || 'OK';
+        if (botToken) {
+          await bestEffort('telegram-answerCallbackQuery', () => fetch(`https://api.telegram.org/bot${botToken}/answerCallbackQuery`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ callback_query_id: callbackQueryId, text: payload.text }),
+            signal: AbortSignal.timeout(5000),
+          }), ctx?.logger);
+        }
+      }
+      json(res, statusCode, payload);
+    };
+
+    // Accept callback payloads from formatInteractive (Telegram/Discord/Slack) or plain {action}
+    let action = typeof body?.action === 'string' ? body.action : '';
+    if (!action && typeof body?.data === 'string') {
+      try { action = String(JSON.parse(body.data)?.id ?? ''); } catch { action = ''; }
+    }
+    if (!action && typeof body?.callback_data === 'string') {
+      try { action = String(JSON.parse(body.callback_data)?.id ?? ''); } catch { action = ''; }
+    }
+    // #222 / #388: Telegram update envelope {update_id, callback_query:{id, data}}
+    if (!action && typeof body?.callback_query?.data === 'string') {
+      try {
+        const parsed = JSON.parse(body.callback_query.data);
+        action = typeof parsed?.id === 'string' ? parsed.id : String(parsed ?? '');
+      } catch {
+        action = body.callback_query.data;
+      }
+    }
+    action = resolveAction(action);
+    if (!action) {
+      await respond(400, { error: { code: 'bad-action', message: 'dsh-key-rotation: no action in payload' } }, 'No action in payload');
+      return;
+    }
+    const provider = action.startsWith('pause-') || action.startsWith('reset-') ? action.replace(/^(pause|reset)-/, '') : '';
+    try {
+      if (action === 'disable-rotation') {
+        setRotationDisabled(true);
+        (ctx?.logger ? ctx.logger('dsh-key-rotation') : null)?.warn?.('[dsh-key-rotation] rotation DISABLED via webhook action');
+        await respond(200, { ok: true, action }, 'Rotation disabled');
+        return;
+      }
+      if (action === 'enable-rotation') {
+        setRotationDisabled(false);
+        await respond(200, { ok: true, action }, 'Rotation enabled');
+        return;
+      }
+      if (action.startsWith('pause-') || action.startsWith('reset-')) {
+        const st = poolState.get(provider);
+        if (!st) {
+          await respond(404, { error: { code: 'not-found', message: `dsh-key-rotation: no pool for '${provider}'` } }, `Pool not found: ${provider}`);
+          return;
+        }
+        if (action.startsWith('pause-')) {
+          const until = Date.now() + 3600000; // 1h pause
+          let found = false;
+          for (const [key, s] of poolState.entries()) {
+            if (key === provider || key.startsWith(provider + '::')) {
+              found = true;
+              for (const ref of (s.failedUntil ? [...s.failedUntil.keys()] : [])) {
+                s.failedUntil.set(ref, Math.max(s.failedUntil.get(ref) ?? 0, until));
+              }
+            }
+          }
+          for (const p of buildRuntime().poolByRef.values()) {
+            if (p.provider === provider || p.base === provider || p.base?.startsWith(provider + '::')) {
+              found = true;
+              for (const ref of p.refs) p.state?.failedUntil?.set(ref, Math.max(p.state?.failedUntil?.get(ref) ?? 0, until));
+            }
+          }
+          if (!found) {
+            await respond(404, { error: { code: 'not-found', message: `dsh-key-rotation: no pool for '${provider}'` } }, `Pool not found: ${provider}`);
+            return;
+          }
+          (ctx?.logger ? ctx.logger('dsh-key-rotation') : null)?.warn?.(`[dsh-key-rotation] pool ${provider} PAUSED 1h via webhook action`);
+          await respond(200, { ok: true, action, provider, until }, `Pool ${provider} paused 1h`);
+          return;
+        }
+        let found = false;
+        let cleared = 0;
+        for (const [key, s] of poolState.entries()) {
+          if (key === provider || key.startsWith(provider + '::')) {
+            found = true;
+            cleared += s.failedUntil ? s.failedUntil.size : 0;
+            s.failedUntil?.clear();
+            s.failCounts?.clear();
+            s.authFailCounts?.clear();
+            s.brokenUntil?.clear();
+            s.revokedRefs?.clear();
+            s.tokenUsage?.clear();
+            s.switches = 0;
+            s.lastReason = undefined;
+            s.lastSwitchAt = undefined;
+          }
+        }
+        if (!found) {
+          await respond(404, { error: { code: 'not-found', message: `dsh-key-rotation: no pool for '${provider}'` } }, `Pool not found: ${provider}`);
+          return;
+        }
+        let circuitReset = false;
+        const br = circuitBreaker ?? buildRuntime().breaker;
+        if (br) {
+          if (typeof br.reset === 'function') { br.reset(provider); circuitReset = true; }
+          else if (typeof br.onSuccess === 'function') { br.onSuccess(provider); circuitReset = true; }
+        }
+        (ctx?.logger ? ctx.logger('dsh-key-rotation') : null)?.warn?.(`[dsh-key-rotation] pool ${provider} RESET via webhook action (circuitReset=${circuitReset})`);
+        await respond(200, { ok: true, action, provider, cleared, circuitReset }, `Pool ${provider} reset`);
+        return;
+      }
+      await respond(400, { error: { code: 'unknown-action', message: `dsh-key-rotation: unknown action '${action}'` } }, `Unknown action: ${action}`);
+    } catch (e) {
+      await respond(500, { error: { code: 'action-failed', message: String(e?.message ?? e) } }, 'Action failed');
+    }
+  },
+}), 'dsh-key-rotation: webhook-action');
+}

package/lib/routes-ops.js

@@ -1,29 +1,2 @@
-// lib/routes-ops.js — operational HTTP routes for dsh-key-rotation (#253/#312/#504/#499).
-// Thin orchestrator: each route family lives in its own lib/ops-*.js module.
-// Registration is injected with the live apply() dependencies.
-
-import { registerStatusRoutes } from './ops-status.js';
-import { registerTelemetryRoutes } from './ops-telemetry.js';
-import { registerKeyRoutes } from './ops-keys.js';
-import { registerTestRoutes } from './ops-test.js';
-import { registerWebhookActionRoute } from './ops-webhook.js';
-import { registerMetricsRoutes } from './ops-metrics.js';
-import { registerBalanceRoutes } from './ops-balance.js';
-import { registerConfigIoRoutes } from './ops-config-io.js';
-import { registerQuickActionRoutes } from './ops-quick-action.js';
-
-/**
- * @param {object} ctx cordis context
- * @param {object} deps live dependencies from apply()
- */
-export function registerOpsRoutes(ctx, deps) {
-  registerStatusRoutes(ctx, deps);
-  registerTelemetryRoutes(ctx, deps);
-  registerKeyRoutes(ctx, deps);
-  registerTestRoutes(ctx, deps);
-  registerWebhookActionRoute(ctx, deps);
-  registerMetricsRoutes(ctx, deps);
-  registerBalanceRoutes(ctx, deps);
-  registerConfigIoRoutes(ctx, deps);
-  registerQuickActionRoutes(ctx, deps);
-}
+// lib/routes-ops.js — Re-export facade for lib/routes/ (#522).
+export * from "./routes/index.js";

package/lib/stream-metrics.js

@@ -1,4 +1,4 @@
-// lib/stream-metrics.js — streaming success telemetry, usage, cost and token recording (#512).
+// lib/stream-metrics.js — streaming success telemetry, usage, cost and token recording (#512, #546, #549).
 // Extracted from lib/rotate.js to enforce < 600 line modularity standard.
 
 import { recordSuccess, setSessionSticky, recordFailure, extractRateLimit, isRateLimited } from './pool.js';
@@ -7,6 +7,7 @@ import { recordRequestOutcome } from './ops-analytics.js';
 import { tpmRecord } from './bucket.js';
 import { extractUsageTokens, consumeModelTokens } from './model-quota.js';
 import { extractProviderLimits } from './provider-limits-detector.js';
+import { normalizeUsageTokens } from './transports/tokens.js';
 
 export async function* preserveDispatchContext(iterable, storage, store) {
   if (!storage || typeof storage.getStore !== 'function') {
@@ -68,11 +69,15 @@ export function recordStreamSuccessMetrics(pool, activeRef, options, chunk, deps
     cascaded: Boolean(options.__isCascade),
   }, wallNow);
 
-  // 3. TPM sliding window bucket recording
-  const usedTokens = extractUsageTokens(usagePayload);
+  // 3. TPM sliding window bucket recording & token normalization (#546, #549)
+  const normUsage = normalizeUsageTokens(usagePayload);
+  const usedTokens = normUsage.totalTokens > 0 ? normUsage.totalTokens : extractUsageTokens(usagePayload);
   if (usedTokens && usedTokens > 0) {
     if (!pool.state.tpmWindows) pool.state.tpmWindows = new Map();
     tpmRecord(pool.state.tpmWindows, activeRef, usedTokens, wallNow);
+    if (pool.state.quotaRunway && typeof pool.state.quotaRunway.recordUsage === 'function') {
+      pool.state.quotaRunway.recordUsage(activeRef, usedTokens, wallNow);
+    }
   }
 
   // 4. Local model quota consumption
@@ -91,12 +96,15 @@ export function recordStreamSuccessMetrics(pool, activeRef, options, chunk, deps
     }
   }
 
-  // 5. Provider rate limit headers detection (#503)
+  // 5. Provider rate limit headers detection & predictive runway (#503, #549)
   if (rawHdrs) {
     const detected = extractProviderLimits(rawHdrs);
     if (detected) {
       if (!pool.state.detectedLimits) pool.state.detectedLimits = new Map();
       pool.state.detectedLimits.set(activeRef, { ...detected, at: nowMs });
+      if (pool.state.quotaRunway && typeof pool.state.quotaRunway.updateLimits === 'function') {
+        pool.state.quotaRunway.updateLimits(activeRef, detected, wallNow);
+      }
     }
   }
 
@@ -130,4 +138,4 @@ export function recordStreamSuccessMetrics(pool, activeRef, options, chunk, deps
   if (rate && Number.isFinite(rate.remaining) && quotaStore) {
     quotaStore.set(activeRef, { remaining: rate.remaining, limit: rate.limit, reset: rate.reset, at: nowMs });
   }
-}
+}

package/lib/transports/anthropic.js

@@ -0,0 +1,125 @@
+// lib/transports/anthropic.js — Anthropic Claude Messages wire protocol parsing (#546).
+// Handles event discrimination, text/thinking deltas, and split-event usage accumulation.
+
+import { normalizeUsageTokens } from './tokens.js';
+
+/**
+ * Parses an Anthropic event payload.
+ * @param {string|object} data
+ * @returns {object|null}
+ */
+export function parseAnthropicEvent(data) {
+  if (!data) return null;
+  if (typeof data === 'object') return data;
+  if (typeof data !== 'string') return null;
+
+  const trimmed = data.trim();
+  if (!trimmed) return null;
+
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extracts content or reasoning delta from an Anthropic event.
+ * @param {object} event
+ * @returns {{
+ *   type: string,
+ *   text: string|null,
+ *   thinking: string|null,
+ *   partialJson: string|null,
+ *   stopReason: string|null
+ * }}
+ */
+export function extractAnthropicDelta(event) {
+  if (!event || typeof event !== 'object') {
+    return { type: 'unknown', text: null, thinking: null, partialJson: null, stopReason: null };
+  }
+
+  const type = event.type || 'unknown';
+
+  if (type === 'content_block_delta') {
+    const delta = event.delta || {};
+    const deltaType = delta.type;
+    return {
+      type,
+      text: deltaType === 'text_delta' && typeof delta.text === 'string' ? delta.text : null,
+      thinking: deltaType === 'thinking_delta' && typeof delta.thinking === 'string' ? delta.thinking : null,
+      partialJson: deltaType === 'input_json_delta' && typeof delta.partial_json === 'string' ? delta.partial_json : null,
+      stopReason: null,
+    };
+  }
+
+  if (type === 'message_delta') {
+    return {
+      type,
+      text: null,
+      thinking: null,
+      partialJson: null,
+      stopReason: event.delta?.stop_reason ?? null,
+    };
+  }
+
+  return { type, text: null, thinking: null, partialJson: null, stopReason: null };
+}
+
+/**
+ * Creates an accumulator for Anthropic streaming usage.
+ * Anthropic provides input tokens at `message_start` and output tokens at `message_delta`.
+ *
+ * @returns {{
+ *   accumulate: (event: object) => void,
+ *   getUsage: () => object,
+ *   reset: () => void
+ * }}
+ */
+export function createAnthropicUsageAccumulator() {
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let cacheReadTokens = 0;
+  let cacheWriteTokens = 0;
+  let rawStart = null;
+  let rawDelta = null;
+
+  function accumulate(event) {
+    if (!event || typeof event !== 'object') return;
+
+    if (event.type === 'message_start' && event.message?.usage) {
+      rawStart = event.message.usage;
+      const norm = normalizeUsageTokens(rawStart);
+      inputTokens = norm.inputTokens;
+      cacheReadTokens = norm.cacheReadTokens;
+      cacheWriteTokens = norm.cacheWriteTokens;
+    } else if (event.type === 'message_delta' && event.usage) {
+      rawDelta = event.usage;
+      const norm = normalizeUsageTokens(rawDelta);
+      outputTokens = norm.outputTokens;
+    }
+  }
+
+  function getUsage() {
+    const total = inputTokens + outputTokens;
+    return {
+      inputTokens,
+      outputTokens,
+      cacheReadTokens,
+      cacheWriteTokens,
+      totalTokens: total,
+      raw: { start: rawStart, delta: rawDelta },
+    };
+  }
+
+  function reset() {
+    inputTokens = 0;
+    outputTokens = 0;
+    cacheReadTokens = 0;
+    cacheWriteTokens = 0;
+    rawStart = null;
+    rawDelta = null;
+  }
+
+  return { accumulate, getUsage, reset };
+}

package/lib/transports/index.js

@@ -0,0 +1,23 @@
+// lib/transports/index.js — Unified network transports and token normalization layer (#546).
+
+export {
+  normalizeUsageTokens,
+  extractTotalTokens,
+} from './tokens.js';
+
+export {
+  createSseDecoder,
+  parseSseStream,
+} from './sse.js';
+
+export {
+  parseOpenAiChunk,
+  extractOpenAiDelta,
+  extractOpenAiUsage,
+} from './openai.js';
+
+export {
+  parseAnthropicEvent,
+  extractAnthropicDelta,
+  createAnthropicUsageAccumulator,
+} from './anthropic.js';

package/lib/transports/openai.js

@@ -0,0 +1,93 @@
+// lib/transports/openai.js — OpenAI wire protocol parsing (#546).
+// Handles JSON deltas, reasoning streams, tool calls, and usage payloads.
+
+import { normalizeUsageTokens } from './tokens.js';
+
+/**
+ * Parses an OpenAI streaming JSON data chunk.
+ * @param {string|object} data
+ * @returns {object|null}
+ */
+export function parseOpenAiChunk(data) {
+  if (!data) return null;
+  if (typeof data === 'object') return data;
+  if (typeof data !== 'string') return null;
+
+  const trimmed = data.trim();
+  if (!trimmed || trimmed === '[DONE]') return null;
+
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extracts content delta, reasoning delta, and tool calls from an OpenAI chunk.
+ * @param {object} chunk
+ * @returns {{
+ *   content: string|null,
+ *   reasoningContent: string|null,
+ *   toolCalls: Array<object>|null,
+ *   finishReason: string|null
+ * }}
+ */
+export function extractOpenAiDelta(chunk) {
+  if (!chunk || typeof chunk !== 'object') {
+    return {
+      content: null,
+      reasoningContent: null,
+      toolCalls: null,
+      finishReason: null,
+    };
+  }
+
+  const choice = Array.isArray(chunk.choices) ? chunk.choices[0] : null;
+  if (!choice) {
+    return {
+      content: null,
+      reasoningContent: null,
+      toolCalls: null,
+      finishReason: null,
+    };
+  }
+
+  const delta = choice.delta ?? {};
+  const finishReason = choice.finish_reason ?? null;
+
+  const content = typeof delta.content === 'string' ? delta.content : null;
+
+  // Support reasoning fields: DeepSeek reasoning_content, OpenAI thought/reasoning
+  const reasoningContent =
+    typeof delta.reasoning_content === 'string'
+      ? delta.reasoning_content
+      : typeof delta.reasoning === 'string'
+        ? delta.reasoning
+        : typeof delta.thought === 'string'
+          ? delta.thought
+          : null;
+
+  const toolCalls = Array.isArray(delta.tool_calls) && delta.tool_calls.length > 0
+    ? delta.tool_calls
+    : null;
+
+  return {
+    content,
+    reasoningContent,
+    toolCalls,
+    finishReason,
+  };
+}
+
+/**
+ * Extracts and normalizes usage from an OpenAI chunk (e.g. stream_options.include_usage).
+ * @param {object} chunk
+ * @returns {object|null}
+ */
+export function extractOpenAiUsage(chunk) {
+  if (!chunk || typeof chunk !== 'object') return null;
+  const usage = chunk.usage;
+  if (!usage || typeof usage !== 'object') return null;
+  return normalizeUsageTokens(usage);
+}