saros-proxy 0.1.0

package/dist/key-encryption.d.ts

@@ -0,0 +1,21 @@
+/**
+ * key-encryption.ts — AES-256-GCM encryption for API keys using scrypt KDF.
+ *
+ * Uses Node.js built-in crypto module (no external dependencies).
+ * Format: enc:scrypt:<salt>:<iv>:<ciphertext>:<authTag>
+ */
+/**
+ * Encrypt a plaintext API key using AES-256-GCM with scrypt KDF.
+ * Returns format: "enc:scrypt:<salt>:<iv>:<ciphertext>:<authTag>"
+ */
+export declare function encryptKey(plaintext: string, masterKey: string): string;
+/**
+ * Decrypt an encrypted API key.
+ * Input format: "enc:scrypt:<salt>:<iv>:<ciphertext>:<authTag>"
+ * Throws clear error if decryption fails (wrong key or corrupted data).
+ */
+export declare function decryptKey(encrypted: string, masterKey: string): string;
+/**
+ * Check if a key value is encrypted (starts with "enc:scrypt:").
+ */
+export declare function isEncryptedKey(value: string): boolean;

package/dist/key-encryption.js

@@ -0,0 +1,59 @@
+/**
+ * key-encryption.ts — AES-256-GCM encryption for API keys using scrypt KDF.
+ *
+ * Uses Node.js built-in crypto module (no external dependencies).
+ * Format: enc:scrypt:<salt>:<iv>:<ciphertext>:<authTag>
+ */
+import { randomBytes, scryptSync, createCipheriv, createDecipheriv } from 'node:crypto';
+const ALGO = 'aes-256-gcm';
+const KEY_LEN = 32;
+const SALT_LEN = 16;
+const IV_LEN = 12;
+const SCRYPT_OPTS = { N: 16384, r: 8, p: 1 };
+/**
+ * Encrypt a plaintext API key using AES-256-GCM with scrypt KDF.
+ * Returns format: "enc:scrypt:<salt>:<iv>:<ciphertext>:<authTag>"
+ */
+export function encryptKey(plaintext, masterKey) {
+    const salt = randomBytes(SALT_LEN);
+    const iv = randomBytes(IV_LEN);
+    const key = scryptSync(masterKey, salt, KEY_LEN, SCRYPT_OPTS);
+    const cipher = createCipheriv(ALGO, key, iv);
+    const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    return `enc:scrypt:${salt.toString('base64')}:${iv.toString('base64')}:${encrypted.toString('base64')}:${authTag.toString('base64')}`;
+}
+/**
+ * Decrypt an encrypted API key.
+ * Input format: "enc:scrypt:<salt>:<iv>:<ciphertext>:<authTag>"
+ * Throws clear error if decryption fails (wrong key or corrupted data).
+ */
+export function decryptKey(encrypted, masterKey) {
+    const parts = encrypted.split(':');
+    if (parts.length !== 6 || parts[0] !== 'enc' || parts[1] !== 'scrypt') {
+        throw new Error('Invalid encrypted key format');
+    }
+    const [, , saltB64, ivB64, ciphertextB64, authTagB64] = parts;
+    try {
+        const salt = Buffer.from(saltB64, 'base64');
+        const iv = Buffer.from(ivB64, 'base64');
+        const ciphertext = Buffer.from(ciphertextB64, 'base64');
+        const authTag = Buffer.from(authTagB64, 'base64');
+        const key = scryptSync(masterKey, salt, KEY_LEN, SCRYPT_OPTS);
+        const decipher = createDecipheriv(ALGO, key, iv);
+        decipher.setAuthTag(authTag);
+        const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+        return decrypted.toString('utf8');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to decrypt key: ${message}`);
+    }
+}
+/**
+ * Check if a key value is encrypted (starts with "enc:scrypt:").
+ */
+export function isEncryptedKey(value) {
+    return value.startsWith('enc:scrypt:');
+}
+//# sourceMappingURL=key-encryption.js.map

package/dist/key-encryption.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-encryption.js","sourceRoot":"","sources":["../src/key-encryption.ts"],"names":[],"mappings":"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"}

package/dist/logger.d.ts

@@ -0,0 +1,11 @@
+/**
+ * logger.ts — Structured logging with Pino and automatic API key masking.
+ */
+import pino from 'pino';
+/**
+ * Mask a secret key: show first 4 and last 4 characters.
+ * Masks keys matching common patterns (sk-, key-, api-, token-)
+ * or any string longer than 20 characters.
+ */
+export declare function maskKey(key: string): string;
+export declare const logger: pino.Logger<never, boolean>;

package/dist/logger.js

@@ -0,0 +1,35 @@
+/**
+ * logger.ts — Structured logging with Pino and automatic API key masking.
+ */
+import pino from 'pino';
+/**
+ * Mask a secret key: show first 4 and last 4 characters.
+ * Masks keys matching common patterns (sk-, key-, api-, token-)
+ * or any string longer than 20 characters.
+ */
+export function maskKey(key) {
+    if (!key || key.length < 4)
+        return '****';
+    // Detect common secret patterns
+    const patterns = [/^sk-/, /^key-/, /^api-/, /^token-/];
+    const isSecret = patterns.some((p) => p.test(key)) || key.length > 20;
+    if (!isSecret)
+        return key; // Not a known secret pattern, show as-is
+    // Mask: show first 4 and last 4 chars
+    if (key.length <= 12)
+        return key.slice(0, 4) + '****';
+    return key.slice(0, 4) + '...' + key.slice(-4);
+}
+const isDev = process.env.NODE_ENV !== 'production';
+export const logger = pino({
+    level: process.env.LOG_LEVEL || 'info',
+    ...(isDev
+        ? {
+            transport: {
+                target: 'pino-pretty',
+                options: { colorize: true },
+            },
+        }
+        : {}),
+});
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,GAAW;IACjC,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,MAAM,CAAC;IAE1C,gCAAgC;IAChC,MAAM,QAAQ,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;IACvD,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC;IAEtE,IAAI,CAAC,QAAQ;QAAE,OAAO,GAAG,CAAC,CAAC,yCAAyC;IAEpE,sCAAsC;IACtC,IAAI,GAAG,CAAC,MAAM,IAAI,EAAE;QAAE,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC;IACtD,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,CAAC;AAEpD,MAAM,CAAC,MAAM,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,MAAM;IACtC,GAAG,CAAC,KAAK;QACP,CAAC,CAAC;YACE,SAAS,EAAE;gBACT,MAAM,EAAE,aAAa;gBACrB,OAAO,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;aAC5B;SACF;QACH,CAAC,CAAC,EAAE,CAAC;CACR,CAAC,CAAC"}

package/dist/proxy-logic.d.ts

@@ -0,0 +1,108 @@
+/**
+ * proxy-logic.ts — Pure production logic. Saros picks the best key per request.
+ *
+ * No I/O, no console.log, no HTTP — completely portable and testable.
+ *
+ * Critical fixes over prototype:
+ *   C1. Circuit breaker cooldown (lazy auto-re-enable via disabledAt)
+ *   C2. Error classification (KeyFault | RequestFault | ServerFault)
+ *   C3. Read-only KeySnapshot returned instead of mutable ApiKey reference
+ *   C4. Request-scoped key tracking (activeRequests map)
+ */
+interface ApiKey {
+    label: string;
+    key: string;
+    enabled: boolean;
+    consecutiveFailures: number;
+    lastUsed: number | null;
+    disabledAt: number | null;
+}
+/** Read-only projection returned to callers — cannot mutate internal state. */
+export interface KeySnapshot {
+    label: string;
+    key: string;
+}
+/** Tracks a single HTTP request's key usage through its lifecycle. */
+interface RequestContext {
+    requestId: string;
+    triedKeys: string[];
+    currentKey: KeySnapshot | null;
+}
+export interface ProxyState {
+    keys: ApiKey[];
+    currentIndex: number;
+    circuitBreakerThreshold: number;
+    circuitBreakerCooldownMs: number;
+    activeRequests: Map<string, RequestContext>;
+}
+/**
+ * Usage data for a single account, scraped from the OpenCode-Go workspace.
+ * All values are percentages (0-100). null means no data for that window.
+ */
+export interface UsageInfo {
+    rolling: number | null;
+    weekly: number | null;
+    monthly: number | null;
+}
+/**
+ * Optional parameters for usage-gated key selection.
+ */
+export interface KeySelectionOptions {
+    usageMap?: Map<string, UsageInfo>;
+    usageThreshold?: number;
+}
+/**
+ * Error classification for HTTP responses.
+ * - KeyFault: the API key should be penalised (invalid, revoked, rate-limited, server fault)
+ * - RequestFault: the request itself is bad — no key penalisation
+ * - ServerFault: transient server issue — key penalised (normal circuit-breaker)
+ */
+export type ErrorType = 'KeyFault' | 'RequestFault' | 'ServerFault';
+export declare function createProxyState(keys: Array<{
+    label: string;
+    key: string;
+}>, options?: {
+    circuitBreakerThreshold?: number;
+    circuitBreakerCooldownMs?: number;
+}): ProxyState;
+/**
+ * Obtain a key for a new (or in-flight) request.
+ * Creates a RequestContext if one does not already exist for this requestId.
+ * Skips keys that have already been tried for this request AND keys booked
+ * by any other active request.
+ */
+export declare function selectKeyForRequest(state: ProxyState, requestId: string, options?: KeySelectionOptions): KeySnapshot | null;
+/**
+ * Failover: record the current key of this request as failed and pick the next
+ * available key.  The caller should also call markKeyFailed() with the
+ * appropriate ErrorType; this function only manages the request-context
+ * tracking (adds the current key to triedKeys).
+ */
+export declare function failoverRequest(state: ProxyState, requestId: string, options?: KeySelectionOptions): KeySnapshot | null;
+/**
+ * Complete a request: if successful, mark the current key as succeeded;
+ * always clean up the request context.
+ */
+export declare function completeRequest(state: ProxyState, requestId: string, success: boolean): void;
+/**
+ * Mark a key as failed according to the error type (C2).
+ * - KeyFault / ServerFault: penalise the key (KeyFault disables immediately)
+ * - RequestFault: no penalisation (bad request, not bad key)
+ */
+export declare function markKeyFailed(state: ProxyState, keyLabel: string, errorType: ErrorType): void;
+/**
+ * Mark a key as succeeded — resets consecutive failures.
+ */
+export declare function markKeySucceeded(state: ProxyState, keyLabel: string): void;
+/**
+ * Classify an HTTP error status + optional response body into an ErrorType.
+ *
+ * Rules:
+ *  401               → KeyFault  (invalid/revoked key — immediate disable)
+ *  429               → KeyFault  (rate-limited)
+ *  500 / 502 / 503   → KeyFault if body mentions quota/balance, else ServerFault
+ *  400 / 404 / 422   → RequestFault (bad request — don't penalise the key)
+ *  everything else   → ServerFault
+ */
+export declare function classifyHttpError(status: number, _body?: string): ErrorType;
+export {};

package/dist/proxy-logic.js

@@ -0,0 +1,353 @@
+/**
+ * proxy-logic.ts — Pure production logic. Saros picks the best key per request.
+ *
+ * No I/O, no console.log, no HTTP — completely portable and testable.
+ *
+ * Critical fixes over prototype:
+ *   C1. Circuit breaker cooldown (lazy auto-re-enable via disabledAt)
+ *   C2. Error classification (KeyFault | RequestFault | ServerFault)
+ *   C3. Read-only KeySnapshot returned instead of mutable ApiKey reference
+ *   C4. Request-scoped key tracking (activeRequests map)
+ */
+import { DEFAULT_CIRCUIT_BREAKER_COOLDOWN_MS } from './constants.js';
+// ---------------------------------------------------------------------------
+// State Factory
+// ---------------------------------------------------------------------------
+export function createProxyState(keys, options) {
+    return {
+        keys: keys.map((k) => ({
+            label: k.label,
+            key: k.key,
+            enabled: true,
+            consecutiveFailures: 0,
+            lastUsed: null,
+            disabledAt: null,
+        })),
+        currentIndex: 0,
+        circuitBreakerThreshold: options?.circuitBreakerThreshold ?? 3,
+        circuitBreakerCooldownMs: options?.circuitBreakerCooldownMs ?? DEFAULT_CIRCUIT_BREAKER_COOLDOWN_MS,
+        activeRequests: new Map(),
+    };
+}
+// ---------------------------------------------------------------------------
+// Internal Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Internal: return a read-only snapshot of the key already selected.
+ * (Keeps mutation paths through markKeyFailed / markKeySucceeded / reenableKey.)
+ */
+function toSnapshot(key) {
+    return { label: key.label, key: key.key };
+}
+/**
+ * Internal: check whether a key is available (enabled & under threshold).
+ * If the key is disabled but past its cooldown window, it is lazily re-enabled
+ * (C1 — fixes dead-code cooldown).
+ */
+function isKeyAvailable(state, key) {
+    if (key.enabled && key.consecutiveFailures < state.circuitBreakerThreshold) {
+        return true;
+    }
+    // C1: lazy auto-re-enable after cooldown expires
+    if (!key.enabled && key.disabledAt !== null) {
+        const elapsed = Date.now() - key.disabledAt;
+        if (elapsed >= state.circuitBreakerCooldownMs) {
+            key.enabled = true;
+            key.consecutiveFailures = 0;
+            key.disabledAt = null;
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Check if a key is available based on usage data.
+ * A key is unavailable if ANY of its usage windows >= threshold.
+ *
+ * @param usage - The usage data for this key's account (null = no data = available)
+ * @param threshold - The usage threshold (1-100)
+ * @returns true if the key is available (usage below threshold or no data)
+ */
+function isKeyAvailableByUsage(usage, threshold) {
+    if (usage === null)
+        return true; // no data = don't block
+    return ((usage.rolling === null || usage.rolling < threshold) &&
+        (usage.weekly === null || usage.weekly < threshold) &&
+        (usage.monthly === null || usage.monthly < threshold));
+}
+/**
+ * Internal: when all circuit-breaker-available keys are over the usage
+ * threshold, fall back to the key with the lowest maximum usage across
+ * all windows. If a key has no usage data, it is preferred immediately.
+ */
+function findFallbackKey(state, usageMap) {
+    let best = null;
+    let bestMaxUsage = Infinity;
+    for (const key of state.keys) {
+        if (!isKeyAvailable(state, key))
+            continue;
+        const usage = usageMap.get(key.label);
+        if (!usage) {
+            // No usage data = best possible – take it immediately
+            key.lastUsed = Date.now();
+            return toSnapshot(key);
+        }
+        const maxUsage = Math.max(usage.rolling ?? 0, usage.weekly ?? 0, usage.monthly ?? 0);
+        if (maxUsage < bestMaxUsage) {
+            bestMaxUsage = maxUsage;
+            best = key;
+        }
+    }
+    if (best) {
+        best.lastUsed = Date.now();
+        return toSnapshot(best);
+    }
+    return null;
+}
+/**
+ * Internal: apply usage-gating to an exclusion set, then attempt to find
+ * the next available key.  Falls back to findFallbackKey if all
+ * circuit-breaker-available keys are over the usage threshold.
+ *
+ * Shared by selectKeyForRequest and failoverRequest — extracts the ~90%
+ * identical usage-gating logic that was previously copy-pasted (PR-5).
+ *
+ * @param excludeLabels  Mutable set; usage-over-threshold labels are added.
+ * @returns A key snapshot, or null if no key is available.
+ */
+function selectKeyWithUsageFallback(state, excludeLabels, options) {
+    // Exclude keys whose account usage exceeds the threshold
+    if (options?.usageMap && options?.usageThreshold !== undefined) {
+        const threshold = options.usageThreshold;
+        for (const key of state.keys) {
+            const usage = options.usageMap.get(key.label) ?? null;
+            if (!isKeyAvailableByUsage(usage, threshold)) {
+                excludeLabels.add(key.label);
+            }
+        }
+    }
+    let snapshot = findNextKey(state, excludeLabels);
+    // Fallback: all circuit-breaker-available keys are over threshold
+    if (!snapshot && options?.usageMap) {
+        const fallback = findFallbackKey(state, options.usageMap);
+        if (fallback) {
+            const idx = state.keys.findIndex((k) => k.label === fallback.label);
+            if (idx !== -1) {
+                state.currentIndex = (idx + 1) % state.keys.length;
+            }
+            snapshot = fallback;
+        }
+    }
+    return snapshot;
+}
+/**
+ * Internal: return the set of key labels that are currently *in use* by
+ * active requests (C4 double-booking avoidance).
+ *
+ * Previously this collected ALL ctx.triedKeys, which meant an abandoned key
+ * (one a request failed over from) stayed globally excluded even though
+ * nobody was using it.  Now it only tracks the key each request is actively
+ * using (ctx.currentKey).  Tried keys are still excluded per-request via
+ * the per-request excludeLabels in selectKeyForRequest/failoverRequest.
+ */
+function buildBookedLabels(state) {
+    const booked = new Set();
+    for (const [, ctx] of state.activeRequests) {
+        if (ctx.currentKey) {
+            booked.add(ctx.currentKey.label);
+        }
+    }
+    return booked;
+}
+/**
+ * Internal: find the next available key, skipping:
+ *  - disabled / under-cooldown keys
+ *  - labels in `excludeLabels`
+ * Advances the round-robin index and returns a read-only snapshot.
+ */
+function findNextKey(state, excludeLabels) {
+    const n = state.keys.length;
+    if (n === 0)
+        return null;
+    for (let i = 0; i < n; i++) {
+        const idx = (state.currentIndex + i) % n;
+        const key = state.keys[idx];
+        if (excludeLabels.has(key.label))
+            continue;
+        if (!isKeyAvailable(state, key))
+            continue;
+        // Advance past the selected key
+        state.currentIndex = (idx + 1) % n;
+        key.lastUsed = Date.now();
+        return toSnapshot(key);
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Request-Scoped Key Tracking (C4)
+// ---------------------------------------------------------------------------
+/**
+ * Obtain a key for a new (or in-flight) request.
+ * Creates a RequestContext if one does not already exist for this requestId.
+ * Skips keys that have already been tried for this request AND keys booked
+ * by any other active request.
+ */
+export function selectKeyForRequest(state, requestId, options) {
+    // If context already exists, return the already-assigned current key
+    const existing = state.activeRequests.get(requestId);
+    if (existing) {
+        return existing.currentKey;
+    }
+    // Create new context and pick a fresh key
+    const ctx = { requestId, triedKeys: [], currentKey: null };
+    state.activeRequests.set(requestId, ctx);
+    const excludeLabels = new Set(ctx.triedKeys);
+    // Avoid double-booking: don't assign a key that another request already has
+    const booked = buildBookedLabels(state);
+    for (const label of booked) {
+        excludeLabels.add(label);
+    }
+    const snapshot = selectKeyWithUsageFallback(state, excludeLabels, options);
+    ctx.currentKey = snapshot;
+    return snapshot;
+}
+/**
+ * Failover: record the current key of this request as failed and pick the next
+ * available key.  The caller should also call markKeyFailed() with the
+ * appropriate ErrorType; this function only manages the request-context
+ * tracking (adds the current key to triedKeys).
+ */
+export function failoverRequest(state, requestId, options) {
+    const ctx = state.activeRequests.get(requestId);
+    if (!ctx)
+        return null;
+    // Record current key as tried
+    if (ctx.currentKey) {
+        ctx.triedKeys.push(ctx.currentKey.label);
+    }
+    // Pick next excluding tried keys + double-booking guard
+    const excludeLabels = new Set(ctx.triedKeys);
+    const booked = buildBookedLabels(state);
+    for (const label of booked) {
+        excludeLabels.add(label);
+    }
+    const snapshot = selectKeyWithUsageFallback(state, excludeLabels, options);
+    ctx.currentKey = snapshot;
+    return snapshot;
+}
+/**
+ * Complete a request: if successful, mark the current key as succeeded;
+ * always clean up the request context.
+ */
+export function completeRequest(state, requestId, success) {
+    const ctx = state.activeRequests.get(requestId);
+    if (!ctx)
+        return;
+    if (success && ctx.currentKey) {
+        markKeySucceeded(state, ctx.currentKey.label);
+    }
+    state.activeRequests.delete(requestId);
+}
+// ---------------------------------------------------------------------------
+// Key Status Mutations
+// ---------------------------------------------------------------------------
+/**
+ * Mark a key as failed according to the error type (C2).
+ * - KeyFault / ServerFault: penalise the key (KeyFault disables immediately)
+ * - RequestFault: no penalisation (bad request, not bad key)
+ */
+export function markKeyFailed(state, keyLabel, errorType) {
+    if (errorType === 'RequestFault')
+        return;
+    const key = state.keys.find((k) => k.label === keyLabel);
+    if (!key)
+        return;
+    if (errorType === 'KeyFault') {
+        // Disable immediately — the key is compromised / rate-limited
+        key.consecutiveFailures = state.circuitBreakerThreshold;
+        key.enabled = false;
+        key.disabledAt = Date.now(); // C1: start cooldown timer
+    }
+    else {
+        // ServerFault: normal circuit-breaker increment
+        key.consecutiveFailures++;
+        if (key.consecutiveFailures >= state.circuitBreakerThreshold) {
+            key.enabled = false;
+            key.disabledAt = Date.now(); // C1: start cooldown timer
+        }
+    }
+}
+/**
+ * Mark a key as succeeded — resets consecutive failures.
+ */
+export function markKeySucceeded(state, keyLabel) {
+    const key = state.keys.find((k) => k.label === keyLabel);
+    if (!key)
+        return;
+    key.consecutiveFailures = 0;
+    // C1: clear cooldown on success so next selection isn't penalised
+    key.disabledAt = null;
+}
+/**
+ * Manually re-enable a previously disabled key.
+ */
+function reenableKey(state, keyLabel) {
+    const key = state.keys.find((k) => k.label === keyLabel);
+    if (!key)
+        return;
+    key.enabled = true;
+    key.consecutiveFailures = 0;
+    key.disabledAt = null; // C1: clear cooldown
+}
+// ---------------------------------------------------------------------------
+// Status Queries
+// ---------------------------------------------------------------------------
+/**
+ * Check whether a key is currently disabled.
+ * A key that has passed its cooldown window is considered no longer disabled
+ * (lazy re-enable happens on next selection, but this query reflects that).
+ */
+function isKeyDisabled(state, keyLabel) {
+    const key = state.keys.find((k) => k.label === keyLabel);
+    if (!key)
+        return true;
+    if (!key.enabled) {
+        // C1: past cooldown → effectively not disabled anymore
+        if (key.disabledAt !== null &&
+            Date.now() - key.disabledAt >= state.circuitBreakerCooldownMs) {
+            return false;
+        }
+        return true;
+    }
+    return key.consecutiveFailures >= state.circuitBreakerThreshold;
+}
+// ---------------------------------------------------------------------------
+// Error Classification (C2)
+// ---------------------------------------------------------------------------
+/**
+ * Classify an HTTP error status + optional response body into an ErrorType.
+ *
+ * Rules:
+ *  401               → KeyFault  (invalid/revoked key — immediate disable)
+ *  429               → KeyFault  (rate-limited)
+ *  500 / 502 / 503   → KeyFault if body mentions quota/balance, else ServerFault
+ *  400 / 404 / 422   → RequestFault (bad request — don't penalise the key)
+ *  everything else   → ServerFault
+ */
+export function classifyHttpError(status, _body) {
+    if (status === 401)
+        return 'KeyFault';
+    if (status === 429)
+        return 'KeyFault';
+    if (status === 400 || status === 404 || status === 422)
+        return 'RequestFault';
+    if (status === 500 || status === 502 || status === 503) {
+        // Server errors: if the body hints at a quota/balance issue treat as KeyFault
+        if (_body && /quota|balance|insufficient|limit/i.test(_body)) {
+            return 'KeyFault';
+        }
+        return 'ServerFault';
+    }
+    return 'ServerFault';
+}
+//# sourceMappingURL=proxy-logic.js.map

package/dist/proxy-logic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy-logic.js","sourceRoot":"","sources":["../src/proxy-logic.ts"],"names":[],"mappings":"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"}

package/dist/proxy.d.ts

@@ -0,0 +1,35 @@
+/**
+ * proxy.ts — Hono HTTP proxy app. Saros predicts account exhaustion and cycles between accounts.
+ *
+ * Routes /zen/go/v1/* requests to the upstream API with automatic key
+ * selection, circuit-breaker failover, and streaming pass-through.
+ */
+import { Hono } from 'hono';
+import type { ProxyConfig } from './config.js';
+declare module 'hono' {
+    interface ContextVariableMap {
+        remote: {
+            address: string;
+        };
+    }
+}
+/**
+ * Build upstream URL from base + request path.
+ */
+export declare function buildUpstreamUrl(base: string, path: string): string;
+/**
+ * Clean headers for upstream forwarding: remove hop-by-hop headers
+ * and any pre-existing Authorization.
+ */
+export declare function buildUpstreamHeaders(incoming: Headers, bearerToken: string): Headers;
+/**
+ * Clean headers for downstream (client) response: strip hop-by-hop headers,
+ * security-sensitive headers, internal debug headers, and content-length
+ * (the Response constructor recalculates content-length automatically).
+ */
+export declare function buildDownstreamHeaders(upstreamHeaders: Headers): Headers;
+/**
+ * Check if a request body indicates streaming mode.
+ */
+export declare function isStreamingRequest(bodyText: string): boolean;
+export declare function createProxyApp(config: ProxyConfig): Hono;