saros-proxy 0.10.2 → 1.0.0

package/dist/secrets/source.js

@@ -0,0 +1,332 @@
+/**
+ * source.ts — Where the passphrase that unlocks `enc:v1:` envelopes comes from.
+ *
+ * Resolution order (first match wins):
+ *   1. `SAROS_PASSPHRASE` in the environment — systemd / container friendly.
+ *   2. The OS secret store, always through the platform's own CLI:
+ *        Linux   secret-tool lookup service saros-proxy account <user>
+ *        macOS   security find-generic-password -s saros-proxy -a <user> -w
+ *        Windows PowerShell DPAPI, blob in %APPDATA%\saros\secret.dpapi
+ *   3. A TTY prompt — only foreground `serve` asks; never a daemon child.
+ *
+ * Every source returns `{ value } | { reason }`. Reasons never contain the
+ * secret, so they are safe for `secret status`, logs and error messages.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { Writable } from 'node:stream';
+export const SERVICE_NAME = 'saros-proxy';
+export const ENV_PASSPHRASE = 'SAROS_PASSPHRASE';
+export const NO_SOURCE_MESSAGE = [
+    'Encrypted API keys found, but no passphrase source is available.',
+    '  a. Set SAROS_PASSPHRASE in the environment (systemd: use systemd-creds).',
+    '  b. Store the passphrase in the OS secret store: saros-proxy secret set',
+    '  c. Run `saros-proxy serve` in a terminal to be prompted.',
+].join('\n');
+/**
+ * Raised when encrypted keys cannot be unlocked. The message is safe to log:
+ * it names sources and options, never a passphrase, plaintext or ciphertext.
+ */
+export class SecretSourceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SecretSourceError';
+    }
+}
+export function decryptFailureMessage(label, detail) {
+    return (`Cannot decrypt API key "${label}": ${detail}. ` +
+        'Check SAROS_PASSPHRASE or run `saros-proxy secret status`.');
+}
+/**
+ * Run a platform CLI without a shell. Failures carry only a generic reason
+ * plus exit status and (bounded) stderr for the store classifier — callers
+ * never print stderr, and stdout is dropped.
+ */
+export function runCommand(command, args, options = {}) {
+    const result = spawnSync(command, args, {
+        encoding: 'utf8',
+        input: options.input,
+        env: options.env ? { ...process.env, ...options.env } : process.env,
+        timeout: 15_000,
+        windowsHide: true,
+        maxBuffer: 1024 * 1024,
+    });
+    if (result.error) {
+        const code = result.error.code;
+        return { ok: false, stdout: '', reason: code === 'ENOENT' ? `${command} is not installed` : `${command} could not be run` };
+    }
+    if (result.status !== 0) {
+        const detail = result.status === null ? 'was terminated' : `exited with code ${result.status}`;
+        return {
+            ok: false,
+            stdout: '',
+            reason: `${command} ${detail}`,
+            status: result.status,
+            // Diagnostics for the store classifier only; never printed verbatim.
+            stderr: (result.stderr || '').slice(0, 4096),
+        };
+    }
+    return { ok: true, stdout: result.stdout || '' };
+}
+/** Strip the trailing newline a CLI adds; keep spaces inside the secret. */
+function firstLine(stdout) {
+    const line = stdout.split('\n')[0];
+    return line.replace(/\r$/, '');
+}
+/** `secret-tool`/`security` say "no match" through exit code and stderr. */
+const STORE_NOT_FOUND = /not found|no such|does not exist|item could not be found|errSecItemNotFound/i;
+const STORE_UNAVAILABLE = /(?:d-?bus|autolaunch|secret service|keyring|locked|denied|permission|not authorized|timed out)/i;
+function lookupFailureReason(result, command) {
+    // Injected runners (tests/embedders) only provide a ready-made reason.
+    if (result.status === undefined)
+        return result.reason;
+    const stderr = result.stderr ?? '';
+    if (STORE_NOT_FOUND.test(stderr) ||
+        result.status === 44 ||
+        (result.status === 1 && stderr.trim().length === 0)) {
+        return `${command}: no entry for service ${SERVICE_NAME} (not found)`;
+    }
+    if (STORE_UNAVAILABLE.test(stderr)) {
+        return `${command}: OS secret store unavailable (keyring locked or error)`;
+    }
+    return result.reason;
+}
+function interpret(result, command, lookup = false) {
+    if (!result.ok) {
+        return { ok: false, reason: lookup ? lookupFailureReason(result, command) : result.reason };
+    }
+    const value = firstLine(result.stdout);
+    return value.length > 0
+        ? { ok: true, value }
+        : { ok: false, reason: `${command} returned an empty secret` };
+}
+export function readEnvPassphrase(env = process.env) {
+    const value = env[ENV_PASSPHRASE];
+    return typeof value === 'string' && value.length > 0
+        ? { ok: true, value }
+        : { ok: false, reason: `${ENV_PASSPHRASE} is not set` };
+}
+function currentUsername() {
+    return process.env.USER || process.env.USERNAME || 'user';
+}
+export function defaultDpapiPath(env = process.env) {
+    const appData = env.APPDATA || join(homedir(), 'AppData', 'Roaming');
+    return join(appData, 'saros', 'secret.dpapi');
+}
+const DPAPI_BLOB = /^[A-Za-z0-9+/]+={0,2}$/;
+function readDpapi(passphrasePath, run) {
+    if (!existsSync(passphrasePath)) {
+        return { ok: false, reason: `DPAPI blob not found at ${passphrasePath}` };
+    }
+    let blob;
+    try {
+        blob = readFileSync(passphrasePath, 'utf8').trim();
+    }
+    catch {
+        return { ok: false, reason: `DPAPI blob at ${passphrasePath} could not be read` };
+    }
+    if (blob.length === 0) {
+        return { ok: false, reason: `DPAPI blob at ${passphrasePath} is empty` };
+    }
+    // Fail closed before PowerShell sees anything: a quote in the blob used to
+    // break out of the single-quoted string and run arbitrary commands.
+    if (!DPAPI_BLOB.test(blob) || blob.length % 4 !== 0) {
+        return { ok: false, reason: `DPAPI blob at ${passphrasePath} is not valid base64` };
+    }
+    // The blob travels in the child environment, never interpolated into the
+    // script, so no base64 character can become PowerShell syntax.
+    const script = "$ErrorActionPreference='Stop';" +
+        'Add-Type -AssemblyName System.Security;' +
+        '$b=[Convert]::FromBase64String($env:SAROS_DPAPI_BLOB);' +
+        "[System.Text.Encoding]::UTF8.GetString([System.Security.Cryptography.ProtectedData]::Unprotect($b, $null, 'CurrentUser'))";
+    return interpret(run('powershell', ['-NoProfile', '-NonInteractive', '-Command', script], {
+        env: { SAROS_DPAPI_BLOB: blob },
+    }), 'powershell');
+}
+/** Read the passphrase from the OS store. Never prompts. */
+export function readStorePassphrase(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const run = options.run ?? runCommand;
+    const username = options.username ?? currentUsername();
+    if (platform === 'linux') {
+        return interpret(run('secret-tool', ['lookup', 'service', SERVICE_NAME, 'account', username]), 'secret-tool', true);
+    }
+    if (platform === 'darwin') {
+        return interpret(run('security', ['find-generic-password', '-s', SERVICE_NAME, '-a', username, '-w']), 'security', true);
+    }
+    if (platform === 'win32') {
+        const path = options.dpapiPath ?? defaultDpapiPath(options.env);
+        return readDpapi(path, run);
+    }
+    return { ok: false, reason: `the OS secret store is not supported on ${platform}` };
+}
+export function isInteractive(input = process.stdin) {
+    return input.isTTY === true;
+}
+/** Read one line from stdin when it is piped (`secret set` in scripts). */
+export async function readStdinLine(input) {
+    let buffer = '';
+    for await (const chunk of input) {
+        buffer += String(chunk);
+        const newline = buffer.indexOf('\n');
+        if (newline !== -1)
+            return buffer.slice(0, newline).replace(/\r$/, '');
+    }
+    return buffer.length > 0 ? buffer : null;
+}
+/** Hidden TTY prompt. Resolves null when there is no TTY or no input. */
+export function promptHidden(options = {}) {
+    const input = options.input ?? process.stdin;
+    const output = options.output ?? process.stderr;
+    if (!isInteractive(input))
+        return Promise.resolve(null);
+    const promise = new Promise((resolve) => {
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(value);
+        };
+        // A sink as readline's output discards the echoed characters; the question
+        // itself is written to the real stderr.
+        const sink = new Writable({
+            write(_chunk, _encoding, callback) {
+                callback();
+            },
+        });
+        const rl = createInterface({ input, output: sink, terminal: true });
+        output.write(options.question ?? 'Passphrase: ');
+        rl.once('line', (line) => {
+            finish(line.length > 0 ? line : null);
+            output.write('\n');
+            rl.close();
+        });
+        rl.once('close', () => finish(null));
+    });
+    return promise;
+}
+export async function readTtyPassphrase(options = {}) {
+    if (!isInteractive(options.input ?? process.stdin)) {
+        return { ok: false, reason: 'stdin is not a TTY' };
+    }
+    const value = await promptHidden(options);
+    return value === null
+        ? { ok: false, reason: 'no passphrase entered' }
+        : { ok: true, value };
+}
+function attempt(source, result) {
+    return result.ok ? { source, ok: true } : { source, ok: false, reason: result.reason };
+}
+/** One line per failed source; safe for errors, never includes a value. */
+export function formatAttempts(attempts) {
+    return attempts
+        .filter((entry) => !entry.ok)
+        .map((entry) => `  ${entry.source}: ${entry.reason}`)
+        .join('\n');
+}
+/**
+ * Resolve the passphrase in precedence order. The TTY source runs only when
+ * `allowTty` is true (foreground serve), never for the daemon child.
+ */
+export async function resolvePassphrase(options = {}) {
+    const attempts = [];
+    const envResult = readEnvPassphrase(options.env);
+    attempts.push(attempt('env', envResult));
+    if (envResult.ok) {
+        return { ok: true, value: envResult.value, source: 'env', attempts };
+    }
+    const storeResult = readStorePassphrase(options);
+    attempts.push(attempt('store', storeResult));
+    if (storeResult.ok) {
+        return { ok: true, value: storeResult.value, source: 'store', attempts };
+    }
+    if (options.allowTty !== true) {
+        attempts.push({
+            source: 'tty',
+            ok: false,
+            reason: 'interactive prompt is disabled in this context',
+        });
+        return { ok: false, attempts };
+    }
+    const ttyResult = await readTtyPassphrase(options);
+    attempts.push(attempt('tty', ttyResult));
+    return ttyResult.ok
+        ? { ok: true, value: ttyResult.value, source: 'tty', attempts }
+        : { ok: false, attempts };
+}
+export function storeBackend(platform = process.platform) {
+    if (platform === 'linux')
+        return 'secret-tool (libsecret)';
+    if (platform === 'darwin')
+        return 'macOS Keychain (security)';
+    if (platform === 'win32')
+        return 'Windows DPAPI (CurrentUser)';
+    return `unsupported platform (${platform})`;
+}
+/** Read-only snapshot for `saros-proxy secret status`; never returns a value. */
+export function getSecretStatus(options = {}) {
+    const env = readEnvPassphrase(options.env);
+    const store = readStorePassphrase(options);
+    const tty = isInteractive(options.input ?? process.stdin);
+    return {
+        env: env.ok,
+        store: {
+            backend: storeBackend(options.platform ?? process.platform),
+            populated: store.ok,
+            reason: store.ok ? '' : store.reason,
+        },
+        tty,
+        effective: env.ok ? 'env' : store.ok ? 'store' : tty ? 'tty' : null,
+    };
+}
+/** Store a passphrase through the platform CLI (used by `secret set`). */
+export function storePassphrase(passphrase, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const backend = storeBackend(platform);
+    if (passphrase.length === 0) {
+        return { ok: false, backend, reason: 'passphrase must not be empty' };
+    }
+    const run = options.run ?? runCommand;
+    const username = options.username ?? currentUsername();
+    if (platform === 'linux') {
+        const result = run('secret-tool', ['store', '--label=saros-proxy passphrase', 'service', SERVICE_NAME, 'account', username], { input: passphrase });
+        return result.ok ? { ok: true, backend } : { ok: false, backend, reason: result.reason };
+    }
+    if (platform === 'darwin') {
+        const result = run('security', [
+            'add-generic-password',
+            '-U',
+            '-s',
+            SERVICE_NAME,
+            '-a',
+            username,
+            '-w',
+            passphrase,
+        ]);
+        return result.ok ? { ok: true, backend } : { ok: false, backend, reason: result.reason };
+    }
+    if (platform === 'win32') {
+        const path = options.dpapiPath ?? defaultDpapiPath(options.env);
+        try {
+            mkdirSync(dirname(path), { recursive: true });
+        }
+        catch {
+            return { ok: false, backend, reason: `could not create ${dirname(path)}` };
+        }
+        const script = "$ErrorActionPreference='Stop';" +
+            'Add-Type -AssemblyName System.Security;' +
+            '$b=[System.Text.Encoding]::UTF8.GetBytes($env:SAROS_SECRET_VALUE);' +
+            "$p=[System.Security.Cryptography.ProtectedData]::Protect($b,$null,'CurrentUser');" +
+            '[System.IO.File]::WriteAllText($env:SAROS_SECRET_BLOB,[Convert]::ToBase64String($p))';
+        const result = run('powershell', ['-NoProfile', '-NonInteractive', '-Command', script], {
+            env: { SAROS_SECRET_VALUE: passphrase, SAROS_SECRET_BLOB: path },
+        });
+        return result.ok ? { ok: true, backend } : { ok: false, backend, reason: result.reason };
+    }
+    return { ok: false, backend, reason: `the OS secret store is not supported on ${platform}` };
+}
+//# sourceMappingURL=source.js.map

package/dist/secrets/source.js.map

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

package/dist/token-usage.d.ts

@@ -49,5 +49,12 @@ export declare function getKeyTokenUsage(): {
     since: number;
     keys: Record<string, KeyTokenUsage>;
 };
-/** Test seam: drop in-memory state and any pending debounced write. */
-export declare function resetTokenUsage(): void;
+/**
+ * Test seam: drop in-memory state and any pending debounced write. By default
+ * the persisted file is removed too, so counters cannot leak between tests
+ * that share a config dir; `keepFile` simulates a process restart that
+ * reloads existing history.
+ */
+export declare function resetTokenUsage(options?: {
+    keepFile?: boolean;
+}): void;

package/dist/token-usage.js

@@ -11,7 +11,7 @@
  * Storage mirrors model-stats.ts: a tiny JSON file in the saros config dir,
  * written behind a debounce so the request path never blocks on I/O.
  */
-import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, rmSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { TOKEN_USAGE_SAVE_DEBOUNCE_MS } from './constants.js';
 import { getSarosDir } from './config.js';
@@ -60,7 +60,10 @@ export function parseTokenCounts(usage) {
     return {
         promptTokens,
         completionTokens,
-        totalTokens: total || promptTokens + completionTokens,
+        // A stream merges counts per field, so a chunk can contribute a stale
+        // total while a later chunk raises prompt/completion. Never report a
+        // total below the parts the upstream itself reported.
+        totalTokens: Math.max(total, promptTokens + completionTokens),
     };
 }
 function load() {
@@ -188,8 +191,13 @@ export function getKeyTokenUsage() {
         load();
     return { since, keys: Object.fromEntries(counters) };
 }
-/** Test seam: drop in-memory state and any pending debounced write. */
-export function resetTokenUsage() {
+/**
+ * Test seam: drop in-memory state and any pending debounced write. By default
+ * the persisted file is removed too, so counters cannot leak between tests
+ * that share a config dir; `keepFile` simulates a process restart that
+ * reloads existing history.
+ */
+export function resetTokenUsage(options = {}) {
     if (saveTimer !== undefined) {
         clearTimeout(saveTimer);
         saveTimer = undefined;
@@ -197,5 +205,13 @@ export function resetTokenUsage() {
     counters.clear();
     since = 0;
     loaded = false;
+    if (options.keepFile)
+        return;
+    try {
+        rmSync(getTokenUsagePath(), { force: true });
+    }
+    catch (err) {
+        logger.debug({ err }, 'failed to remove token usage file');
+    }
 }
 //# sourceMappingURL=token-usage.js.map

package/dist/token-usage.js.map

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

package/dist/usage-client.d.ts

@@ -1,9 +1,10 @@
 /**
- * usage-client.ts — Per-key quota usage from the upstream usage API.
+ * usage-client.ts — Per-key quota usage from each provider's usage API.
  *
- * GET <upstream>/zen/go/v1/usage (Bearer = the proxy's own API key) returns:
- *   {"usage":{"rolling":{"status":"ok","percent":12,"resetsAt":"…"},
- *             "weekly":{…},"monthly":{…}}}
+ * Every provider owns its endpoint path, response parser and identity
+ * headers (opencode-go: `/zen/go/v1/usage` behind Cloudflare, which needs the
+ * CLI User-Agent; commandcode: `/alpha/billing/credits`, gated on the same
+ * CLI identity). `fetchKeyUsage` only adds the bearer credential.
  *
  * Refresh strategy: stale-while-revalidate on demand. `maybeRefreshUsage`
  * is called on the request path; when data is older than USAGE_REFRESH_TTL_MS
@@ -13,9 +14,36 @@
  */
 import { type ProxyState } from './proxy-logic.js';
 import type { ProxyConfig } from './config.js';
+import type { KeyProvider } from './providers/index.js';
+/**
+ * Per-key quota usage, normalized as a percentage *of the provider's own
+ * budget* — never absolute capacity. `usedPercent` is the **monthly** window:
+ * 0 = untouched, 100 = monthly allowance spent. `exhausted` is true when any
+ * window (5h, weekly or monthly) reached 100%, which takes the key out of
+ * rotation regardless of how much of the month remains — otherwise a key with
+ * 50% monthly and a spent weekly window would keep receiving traffic and
+ * failing upstream.
+ *
+ * This normalization is the contract mixed-provider pools rely on:
+ * `pickWeighted` (`proxy-logic.ts`) compares the numbers from every provider
+ * directly, so "30%" must always mean "30% of that provider's monthly budget".
+ * Percent is the most saros can honestly compare — opencode-go's
+ * `/zen/go/v1/usage` publishes only percentages
+ * (`{"usage":{"rolling":{"percent":1},"weekly":{"percent":15},
+ * "monthly":{"percent":19}}}`), with no token counts or absolute caps, while
+ * CommandCode publishes `used`/`cap` per window plus the remaining monthly
+ * credits, and its parser converts them to the same percent scale.
+ */
 export interface KeyUsage {
-    /** Worst-window used percent, 0-100. */
-    usedPercent: number;
+    /**
+     * Monthly used percent, 0-100, of this provider's own budget; null when the
+     * payload has no derivable monthly metric (the previous value must survive).
+     */
+    usedPercent: number | null;
+    /** True when any window is at 100% — rotation weighs the key 0. */
+    exhausted: boolean;
+    /** False when the payload carries no monthly percentage (CLI shows n/a). */
+    monthlyAvailable: boolean;
     rollingPercent: number;
     weeklyPercent: number;
     monthlyPercent: number;
@@ -43,15 +71,17 @@ export interface UsageFetchResult {
  * problem, not an account one, and must not match.
  */
 export declare function isEntitlementError(status: number, body: string): boolean;
-/** Parse a usage API response body into KeyUsage (throws on contract violation). */
-export declare function parseUsageResponse(body: string): KeyUsage;
 /**
- * Fetch current usage for one key. Failures (network, timeout, non-200,
- * contract violation) yield `usage: null` — callers treat that as "no fresh
- * data". A 403 entitlement rejection is reported separately because it is
- * definitive rather than transient.
+ * Fetch current usage for one key from its provider's endpoint. The provider
+ * supplies the path, the identity headers (CommandCode and opencode-go both
+ * reject requests without a CLI User-Agent) and the response parser; this
+ * function only adds the bearer credential and the timeout.
+ *
+ * Failures (network, timeout, non-200, contract violation) yield
+ * `usage: null` — callers treat that as "no fresh data". A 403 entitlement
+ * rejection is reported separately because it is definitive, not transient.
  */
-export declare function fetchKeyUsage(upstreamBaseUrl: string, apiKey: string, usagePath?: string): Promise<UsageFetchResult>;
+export declare function fetchKeyUsage(upstreamBaseUrl: string, apiKey: string, provider?: KeyProvider): Promise<UsageFetchResult>;
 /** Test seam: reset coordinator state. */
 export declare function resetUsageRefreshState(): void;
 /**