@srouterhq/server 0.0.0-stage → 0.9.0

package/dist/lib/db-backup.js

@@ -0,0 +1,255 @@
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import { gzipSync, gunzipSync } from 'zlib';
+import { getDefaultDbPath } from '../db/index.js';
+import { restrictToOwner } from './file-permissions.js';
+const MAGIC = Buffer.from('FAPIBK1\0');
+const DEFAULT_INTERVAL_MS = 5 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 30 * 1000;
+const PLACEHOLDER_KEY = 'replace-with-64-char-hex';
+function backupTarget() {
+    const raw = process.env.SROUTER_DB_BACKUP_TARGET
+        ?? process.env.SROUTER_DB_BACKUP_URL
+        ?? process.env.SROUTER_DB_BACKUP_PATH
+        ?? '';
+    const trimmed = raw.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+export function isDbBackupConfigured() {
+    return backupTarget() !== null;
+}
+function backupIntervalMs() {
+    const raw = process.env.SROUTER_DB_BACKUP_INTERVAL_MS;
+    if (!raw)
+        return DEFAULT_INTERVAL_MS;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : DEFAULT_INTERVAL_MS;
+}
+function isHttpTarget(target) {
+    return target.startsWith('https://') || target.startsWith('http://');
+}
+function parseBackupKey() {
+    const raw = (process.env.SROUTER_DB_BACKUP_KEY || process.env.ENCRYPTION_KEY || '').trim();
+    if (!raw || raw === PLACEHOLDER_KEY || !/^[0-9a-fA-F]{64}$/.test(raw)) {
+        throw new Error('SROUTER_DB_BACKUP_KEY or ENCRYPTION_KEY must be a 64-character hex key when DB backup is enabled');
+    }
+    return Buffer.from(raw, 'hex');
+}
+function encryptBackup(plain) {
+    const key = parseBackupKey();
+    const iv = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+    const ciphertext = Buffer.concat([cipher.update(plain), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return Buffer.concat([MAGIC, iv, tag, ciphertext]);
+}
+function decryptBackup(payload) {
+    if (payload.length < MAGIC.length + 12 + 16 || !payload.subarray(0, MAGIC.length).equals(MAGIC)) {
+        throw new Error('backup payload has an unsupported format');
+    }
+    const key = parseBackupKey();
+    const ivStart = MAGIC.length;
+    const tagStart = ivStart + 12;
+    const bodyStart = tagStart + 16;
+    const iv = payload.subarray(ivStart, tagStart);
+    const tag = payload.subarray(tagStart, bodyStart);
+    const ciphertext = payload.subarray(bodyStart);
+    const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
+/**
+ * Split a Hugging Face `/resolve/` download URL into the pieces the commit API
+ * needs, or null for anything else.
+ *
+ * A HF repo serves downloads at `/{type}/{ns}/{repo}/resolve/{rev}/{path}`, but
+ * that route is read-only: a PUT to it is answered 404/405 and the blob never
+ * lands. Writes go through the commit API instead. Both halves are derived from
+ * the one URL the operator configures, so SROUTER_DB_BACKUP_TARGET stays the
+ * plain download URL they can paste into a browser.
+ *
+ * Models are the type with no prefix segment (`/{ns}/{repo}/resolve/...`);
+ * datasets and spaces name themselves. The API path pluralizes the type.
+ */
+export function parseHuggingFaceTarget(target) {
+    let url;
+    try {
+        url = new URL(target);
+    }
+    catch {
+        return null;
+    }
+    if (url.hostname !== 'huggingface.co')
+        return null;
+    const segments = url.pathname.split('/').filter(Boolean);
+    const prefixed = segments[0] === 'datasets' || segments[0] === 'spaces';
+    const type = prefixed ? segments[0] : 'models';
+    const rest = prefixed ? segments.slice(1) : segments;
+    // ns / repo / 'resolve' / rev / path…
+    if (rest.length < 5 || rest[2] !== 'resolve')
+        return null;
+    const [namespace, repo, , revision] = rest;
+    const filePath = rest.slice(4).map(decodeURIComponent).join('/');
+    if (!namespace || !repo || !revision || !filePath)
+        return null;
+    return {
+        commitUrl: `https://huggingface.co/api/${type}/${namespace}/${repo}/commit/${revision}`,
+        filePath,
+    };
+}
+/**
+ * Upload one file through the HF commit API: newline-delimited JSON, a header
+ * line naming the commit followed by a line per file.
+ *
+ * The blob is sent as base64 TEXT rather than as bytes — `encoding: 'utf-8'`,
+ * NOT 'base64', because that flag would tell HF to decode the content back to
+ * binary before writing it, which is exactly what we are avoiding: repos on Xet
+ * storage reject binary blobs pushed through this route. Base64 costs a third
+ * more bytes and buys a file the route will actually accept. readTarget()
+ * reverses it.
+ */
+async function uploadToHuggingFace(commitUrl, filePath, payload, token) {
+    const lines = [
+        { key: 'header', value: { summary: `chore: update ${filePath}` } },
+        { key: 'file', value: { path: filePath, content: payload.toString('base64'), encoding: 'utf-8' } },
+    ];
+    const res = await fetch(commitUrl, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/x-ndjson',
+            Authorization: `Bearer ${token}`,
+        },
+        body: lines.map(line => JSON.stringify(line)).join('\n'),
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    if (!res.ok) {
+        const detail = await res.text().catch(() => '');
+        throw new Error(`backup upload failed: HF commit HTTP ${res.status}${detail ? ` — ${detail.slice(0, 200)}` : ''}`);
+    }
+}
+/** Undo the base64 wrapper uploadToHuggingFace applies. Sniffed rather than
+ *  assumed: a blob left behind by an older build is raw and starts with MAGIC,
+ *  and a restore that silently base64-decoded it would turn a recoverable
+ *  database into a corrupt one. */
+function decodeHuggingFacePayload(raw) {
+    if (raw.subarray(0, MAGIC.length).equals(MAGIC))
+        return raw;
+    return Buffer.from(raw.toString('utf8'), 'base64');
+}
+async function readTarget(target) {
+    if (isHttpTarget(target)) {
+        const headers = {};
+        const token = process.env.SROUTER_DB_BACKUP_TOKEN?.trim();
+        if (token)
+            headers.Authorization = `Bearer ${token}`;
+        const res = await fetch(target, { method: 'GET', headers, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+        if (res.status === 404 || res.status === 204)
+            return null;
+        if (!res.ok)
+            throw new Error(`backup restore failed: HTTP ${res.status}`);
+        const raw = Buffer.from(await res.arrayBuffer());
+        return parseHuggingFaceTarget(target) ? decodeHuggingFacePayload(raw) : raw;
+    }
+    if (!fs.existsSync(target))
+        return null;
+    return fs.readFileSync(target);
+}
+async function writeTarget(target, payload) {
+    if (isHttpTarget(target)) {
+        const token = process.env.SROUTER_DB_BACKUP_TOKEN?.trim();
+        const huggingFace = parseHuggingFaceTarget(target);
+        if (huggingFace) {
+            // Anonymous writes do not exist on HF; without a token every upload would
+            // 401 on a schedule and only ever be noticed as an empty restore.
+            if (!token)
+                throw new Error('SROUTER_DB_BACKUP_TOKEN is required to upload a backup to Hugging Face');
+            await uploadToHuggingFace(huggingFace.commitUrl, huggingFace.filePath, payload, token);
+            return;
+        }
+        const headers = { 'Content-Type': 'application/octet-stream' };
+        if (token)
+            headers.Authorization = `Bearer ${token}`;
+        const res = await fetch(target, {
+            method: 'PUT',
+            headers,
+            body: payload,
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        });
+        if (!res.ok)
+            throw new Error(`backup upload failed: HTTP ${res.status}`);
+        return;
+    }
+    fs.mkdirSync(path.dirname(path.resolve(target)), { recursive: true });
+    // Encrypted, but not therefore safe to leave world-readable: the key is
+    // SROUTER_DB_BACKUP_KEY or ENCRYPTION_KEY, which on a normal install sits in a
+    // .env file on the same host. The mode covers creation; restrictToOwner covers
+    // the overwrite case, where an existing file keeps the mode it already had —
+    // and covers Windows, where the mode argument is a no-op.
+    fs.writeFileSync(target, payload, { mode: 0o600 });
+    if (!restrictToOwner(target)) {
+        console.warn(`[db-backup] could not restrict permissions on ${target} — it may be readable by other local accounts`);
+    }
+}
+export async function restoreDbBackupIfNeeded(dbPath = getDefaultDbPath()) {
+    const target = backupTarget();
+    if (!target)
+        return { ok: true, skipped: 'not configured' };
+    if (dbPath === ':memory:')
+        return { ok: true, target, skipped: 'memory database' };
+    if (fs.existsSync(dbPath) && fs.statSync(dbPath).size > 0)
+        return { ok: true, target, skipped: 'database already exists' };
+    const payload = await readTarget(target);
+    if (!payload || payload.length === 0)
+        return { ok: true, target, skipped: 'no backup found' };
+    let restored;
+    try {
+        restored = gunzipSync(decryptBackup(payload));
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new Error(`could not restore SQLite backup from ${target}: ${detail}`);
+    }
+    fs.mkdirSync(path.dirname(path.resolve(dbPath)), { recursive: true });
+    // This is the decrypted database — provider keys and the dashboard password
+    // hash in the clear. connectDb hardens it too, but that is a later call and
+    // sometimes a later process; the file must not be readable in between.
+    fs.writeFileSync(dbPath, restored, { mode: 0o600 });
+    if (!restrictToOwner(dbPath)) {
+        console.warn(`[db-backup] could not restrict permissions on the restored database at ${dbPath}`);
+    }
+    console.log(`[db-backup] restored ${restored.length} bytes from ${target}`);
+    return { ok: true, target, bytes: restored.length, restored: true };
+}
+export async function backupDbNow(db, dbPath = getDefaultDbPath()) {
+    const target = backupTarget();
+    if (!target)
+        return { ok: true, skipped: 'not configured' };
+    if (dbPath === ':memory:')
+        return { ok: true, target, skipped: 'memory database' };
+    if (!fs.existsSync(dbPath))
+        return { ok: false, target, skipped: 'database file missing' };
+    try {
+        db.pragma('wal_checkpoint(TRUNCATE)');
+    }
+    catch {
+        // Best effort: reading the main DB still works for rollback-journal or quiet WAL DBs.
+    }
+    const plain = fs.readFileSync(dbPath);
+    const payload = encryptBackup(gzipSync(plain));
+    await writeTarget(target, payload);
+    console.log(`[db-backup] uploaded ${plain.length} bytes to ${target}`);
+    return { ok: true, target, bytes: plain.length };
+}
+export function startDbBackupPump(db, scheduler, dbPath = getDefaultDbPath()) {
+    if (!backupTarget())
+        return null;
+    const run = () => {
+        void backupDbNow(db, dbPath).catch(err => {
+            console.warn(`[db-backup] ${err instanceof Error ? err.message : err}`);
+        });
+    };
+    run();
+    return scheduler.every(backupIntervalMs(), run);
+}
+//# sourceMappingURL=db-backup.js.map

package/dist/lib/db-backup.js.map

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

package/dist/lib/endpoint-scope.d.ts

@@ -0,0 +1,42 @@
+import type { Db } from '../db/types.js';
+/** Trailing-slash-insensitive endpoint identity, matching how base_url is stored. */
+export declare function normalizeBaseUrl(raw: string): string;
+/** The scope token for a custom endpoint; '' means "not endpoint-scoped". */
+export declare function endpointScopeForBaseUrl(baseUrl: string | null | undefined): string;
+/**
+ * The scope a model bound to `keyId` belongs to. '' when the key is gone or
+ * carries no base_url — a legacy custom row that predates per-endpoint binding
+ * keeps the un-scoped identity it has always had, so nothing about it changes.
+ */
+export declare function endpointScopeOfKey(db: Db, keyId: number | null | undefined): string;
+/**
+ * A short, typable handle for a scope, used only for naming: the host (with
+ * port) plus path, slugified. Derived purely from the scope, so it is stable —
+ * adding or removing OTHER endpoints never renames an existing one.
+ *
+ *   https://relay-a.example.com/v1  →  relay-a.example.com-v1
+ *   http://127.0.0.1:11434/v1       →  127.0.0.1-11434-v1
+ */
+export declare function endpointHandle(scope: string): string;
+/**
+ * The bucket key for reliability/speed stats and the routing round-robin.
+ * Unchanged (`platform:model_id`) for every catalog model and for un-scoped
+ * legacy custom rows; endpoint-qualified only for rows that actually carry a
+ * scope, so a single-endpoint install keeps its existing history verbatim.
+ */
+export declare function modelStatsKey(platform: string, modelId: string, endpointScope: string | null | undefined): string;
+export declare const ENDPOINT_ID_SEPARATOR = "#";
+/**
+ * The endpoint-qualified model id a client can send to pin ONE relay's copy:
+ * `custom:deepseek-v3.1#relay-a.example.com-v1`. Null for rows with no scope,
+ * whose plain `platform:model_id` member id is already unambiguous — which is
+ * why a single-endpoint install never sees a qualified id anywhere.
+ */
+export declare function qualifiedModelMemberId(platform: string, modelId: string, endpointScope: string | null | undefined): string | null;
+/**
+ * Whether `requested` names this row's endpoint after the separator. Accepts
+ * the handle or the raw base_url (with or without scheme / trailing slash), so
+ * a user who pastes the endpoint URL they typed into the dashboard is right.
+ */
+export declare function endpointRefMatches(requested: string, endpointScope: string): boolean;
+//# sourceMappingURL=endpoint-scope.d.ts.map

package/dist/lib/endpoint-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint-scope.d.ts","sourceRoot":"","sources":["../../src/lib/endpoint-scope.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAC;AAEzC,qFAAqF;AACrF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,6EAA6E;AAC7E,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAElF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAKnF;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQpD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACvC,MAAM,CAER;AAID,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACvC,MAAM,GAAG,IAAI,CAGf;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAOpF"}

package/dist/lib/endpoint-scope.js

@@ -0,0 +1,95 @@
+// ── Endpoint identity for custom relay models (#651) ────────────────────────
+//
+// Every custom relay is stored under platform = 'custom', so two relays that
+// both offer `deepseek-v3.1` used to collapse into ONE `models` row: one
+// enabled flag, one reliability/speed bucket, one binding anchor. Disabling the
+// model because relay A was broken disabled it for relay B too, and relay A's
+// timeouts dragged down the copy relay B served just fine (#619).
+//
+// The discriminator is `models.endpoint_scope`: the normalized base_url of the
+// endpoint the row belongs to, '' for every catalog platform. Uniqueness is
+// (platform, model_id, endpoint_scope), so catalog rows keep exactly their old
+// (platform, model_id) semantics — '' is the same value for all of them — while
+// two relays can each hold their own row for the same model id.
+//
+// Why base_url and not key_id: #640 settled that an endpoint is a base_url
+// holding a POOL of credentials, and a model rotates across that pool. Keying
+// identity on key_id would split one relay's model into one row per credential
+// and undo that. Why a TEXT token and not a foreign key: the scope is opaque to
+// everything except this module, so the per-key model groups of #657 can later
+// refine it (`<base_url>#<group>`) without a second identity migration.
+/** Trailing-slash-insensitive endpoint identity, matching how base_url is stored. */
+export function normalizeBaseUrl(raw) {
+    return raw.trim().replace(/\/+$/, '');
+}
+/** The scope token for a custom endpoint; '' means "not endpoint-scoped". */
+export function endpointScopeForBaseUrl(baseUrl) {
+    return baseUrl ? normalizeBaseUrl(baseUrl) : '';
+}
+/**
+ * The scope a model bound to `keyId` belongs to. '' when the key is gone or
+ * carries no base_url — a legacy custom row that predates per-endpoint binding
+ * keeps the un-scoped identity it has always had, so nothing about it changes.
+ */
+export function endpointScopeOfKey(db, keyId) {
+    if (keyId == null)
+        return '';
+    const row = db.prepare("SELECT base_url FROM api_keys WHERE id = ? AND platform = 'custom'")
+        .get(keyId);
+    return endpointScopeForBaseUrl(row?.base_url);
+}
+/**
+ * A short, typable handle for a scope, used only for naming: the host (with
+ * port) plus path, slugified. Derived purely from the scope, so it is stable —
+ * adding or removing OTHER endpoints never renames an existing one.
+ *
+ *   https://relay-a.example.com/v1  →  relay-a.example.com-v1
+ *   http://127.0.0.1:11434/v1       →  127.0.0.1-11434-v1
+ */
+export function endpointHandle(scope) {
+    const withoutScheme = scope.replace(/^[a-z][a-z0-9+.-]*:\/\//i, '');
+    const slug = withoutScheme
+        .toLowerCase()
+        .replace(/[^a-z0-9.]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^[-.]+|[-.]+$/g, '');
+    return slug || 'endpoint';
+}
+/**
+ * The bucket key for reliability/speed stats and the routing round-robin.
+ * Unchanged (`platform:model_id`) for every catalog model and for un-scoped
+ * legacy custom rows; endpoint-qualified only for rows that actually carry a
+ * scope, so a single-endpoint install keeps its existing history verbatim.
+ */
+export function modelStatsKey(platform, modelId, endpointScope) {
+    return endpointScope ? `${platform}:${modelId}@${endpointScope}` : `${platform}:${modelId}`;
+}
+// The separator between a member id and its endpoint handle. '#' reads as a
+// fragment and — unlike ':', '@' or '/' — does not occur in provider model ids.
+export const ENDPOINT_ID_SEPARATOR = '#';
+/**
+ * The endpoint-qualified model id a client can send to pin ONE relay's copy:
+ * `custom:deepseek-v3.1#relay-a.example.com-v1`. Null for rows with no scope,
+ * whose plain `platform:model_id` member id is already unambiguous — which is
+ * why a single-endpoint install never sees a qualified id anywhere.
+ */
+export function qualifiedModelMemberId(platform, modelId, endpointScope) {
+    if (!endpointScope)
+        return null;
+    return `${platform}:${modelId}${ENDPOINT_ID_SEPARATOR}${endpointHandle(endpointScope)}`;
+}
+/**
+ * Whether `requested` names this row's endpoint after the separator. Accepts
+ * the handle or the raw base_url (with or without scheme / trailing slash), so
+ * a user who pastes the endpoint URL they typed into the dashboard is right.
+ */
+export function endpointRefMatches(requested, endpointScope) {
+    const ref = requested.trim();
+    if (!ref || !endpointScope)
+        return false;
+    // Slugifying BOTH sides is what makes the handle and the raw URL equivalent:
+    // endpointHandle is idempotent, so handle→handle and url→handle both land on
+    // the same token.
+    return endpointHandle(ref) === endpointHandle(endpointScope);
+}
+//# sourceMappingURL=endpoint-scope.js.map

package/dist/lib/endpoint-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint-scope.js","sourceRoot":"","sources":["../../src/lib/endpoint-scope.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,EAAE;AACF,6EAA6E;AAC7E,yEAAyE;AACzE,gFAAgF;AAChF,8EAA8E;AAC9E,kEAAkE;AAClE,EAAE;AACF,+EAA+E;AAC/E,4EAA4E;AAC5E,+EAA+E;AAC/E,gFAAgF;AAChF,gEAAgE;AAChE,EAAE;AACF,2EAA2E;AAC3E,8EAA8E;AAC9E,+EAA+E;AAC/E,gFAAgF;AAChF,+EAA+E;AAC/E,wEAAwE;AAIxE,qFAAqF;AACrF,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACxC,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,uBAAuB,CAAC,OAAkC;IACxE,OAAO,OAAO,CAAC,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAClD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,EAAM,EAAE,KAAgC;IACzE,IAAI,KAAK,IAAI,IAAI;QAAE,OAAO,EAAE,CAAC;IAC7B,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,oEAAoE,CAAC;SACzF,GAAG,CAAC,KAAK,CAA4C,CAAC;IACzD,OAAO,uBAAuB,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,MAAM,aAAa,GAAG,KAAK,CAAC,OAAO,CAAC,0BAA0B,EAAE,EAAE,CAAC,CAAC;IACpE,MAAM,IAAI,GAAG,aAAa;SACvB,WAAW,EAAE;SACb,OAAO,CAAC,cAAc,EAAE,GAAG,CAAC;SAC5B,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC;IACjC,OAAO,IAAI,IAAI,UAAU,CAAC;AAC5B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC3B,QAAgB,EAChB,OAAe,EACf,aAAwC;IAExC,OAAO,aAAa,CAAC,CAAC,CAAC,GAAG,QAAQ,IAAI,OAAO,IAAI,aAAa,EAAE,CAAC,CAAC,CAAC,GAAG,QAAQ,IAAI,OAAO,EAAE,CAAC;AAC9F,CAAC;AAED,4EAA4E;AAC5E,gFAAgF;AAChF,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CACpC,QAAgB,EAChB,OAAe,EACf,aAAwC;IAExC,IAAI,CAAC,aAAa;QAAE,OAAO,IAAI,CAAC;IAChC,OAAO,GAAG,QAAQ,IAAI,OAAO,GAAG,qBAAqB,GAAG,cAAc,CAAC,aAAa,CAAC,EAAE,CAAC;AAC1F,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAAiB,EAAE,aAAqB;IACzE,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,CAAC,GAAG,IAAI,CAAC,aAAa;QAAE,OAAO,KAAK,CAAC;IACzC,6EAA6E;IAC7E,6EAA6E;IAC7E,kBAAkB;IAClB,OAAO,cAAc,CAAC,GAAG,CAAC,KAAK,cAAc,CAAC,aAAa,CAAC,CAAC;AAC/D,CAAC"}

package/dist/lib/env-drift.d.ts

@@ -0,0 +1,17 @@
+export interface EnvDriftReport {
+    missingDocumentedDefaults: string[];
+    unknownKeys: string[];
+}
+export interface EnvDriftPaths {
+    envPath?: string;
+    examplePath?: string;
+}
+export declare function defaultEnvDriftPaths(): Required<EnvDriftPaths>;
+export declare function parseEnvNames(text: string, opts?: {
+    includeCommented?: boolean;
+}): string[];
+export declare function compareEnvText(envText: string, exampleText: string): EnvDriftReport;
+export declare function formatEnvDriftReport(report: EnvDriftReport): string[];
+export declare function checkEnvDrift(paths?: EnvDriftPaths): EnvDriftReport | null;
+export declare function warnOnEnvDrift(paths?: EnvDriftPaths, logger?: Pick<Console, 'warn'>): EnvDriftReport | null;
+//# sourceMappingURL=env-drift.d.ts.map

package/dist/lib/env-drift.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-drift.d.ts","sourceRoot":"","sources":["../../src/lib/env-drift.ts"],"names":[],"mappings":"AA2BA,MAAM,WAAW,cAAc;IAC7B,yBAAyB,EAAE,MAAM,EAAE,CAAC;IACpC,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,oBAAoB,IAAI,QAAQ,CAAC,aAAa,CAAC,CAK9D;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,MAAM,EAAE,CAc/F;AAMD,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,cAAc,CAWnF;AAWD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,EAAE,CAmBrE;AAED,wBAAgB,aAAa,CAAC,KAAK,GAAE,aAAkB,GAAG,cAAc,GAAG,IAAI,CAe9E;AAED,wBAAgB,cAAc,CAAC,KAAK,CAAC,EAAE,aAAa,EAAE,MAAM,GAAE,IAAI,CAAC,OAAO,EAAE,MAAM,CAAW,GAAG,cAAc,GAAG,IAAI,CAKpH"}

package/dist/lib/env-drift.js

@@ -0,0 +1,108 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '../../..');
+const ACTIVE_ENV_RE = /^\s*(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=/;
+const COMMENTED_ENV_RE = /^\s*#\s*(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=/;
+const KNOWN_UNDOCUMENTED_ENV = new Set([
+    'NODE_ENV',
+    'DEV_MODE',
+    'SROUTER_DIR',
+    'SROUTER_DATA_DIR',
+    'PROXY_URL',
+    'CATALOG_BASE_URL',
+    'CATALOG_PUBKEY',
+    'CATALOG_SYNC_DISABLED',
+    'SROUTER_DB_BACKUP_TARGET',
+]);
+const KNOWN_UNDOCUMENTED_PATTERNS = [
+    /^PROVIDER_DAILY_REQUEST_CAP_[A-Z0-9_]+$/,
+    /^PROVIDER_TIMEOUT_[A-Z0-9_]+$/,
+];
+export function defaultEnvDriftPaths() {
+    return {
+        envPath: process.env.SROUTER_ENV_PATH ?? path.join(REPO_ROOT, '.env'),
+        examplePath: path.join(REPO_ROOT, '.env.example'),
+    };
+}
+export function parseEnvNames(text, opts = {}) {
+    const names = new Set();
+    for (const line of text.split(/\r?\n/)) {
+        const active = ACTIVE_ENV_RE.exec(line);
+        if (active) {
+            names.add(active[1]);
+            continue;
+        }
+        if (opts.includeCommented) {
+            const commented = COMMENTED_ENV_RE.exec(line);
+            if (commented)
+                names.add(commented[1]);
+        }
+    }
+    return [...names].sort();
+}
+function isKnownUndocumentedEnv(name) {
+    return KNOWN_UNDOCUMENTED_ENV.has(name) || KNOWN_UNDOCUMENTED_PATTERNS.some(re => re.test(name));
+}
+export function compareEnvText(envText, exampleText) {
+    const actual = new Set(parseEnvNames(envText));
+    const documentedDefaults = parseEnvNames(exampleText);
+    const documented = new Set(parseEnvNames(exampleText, { includeCommented: true }));
+    return {
+        missingDocumentedDefaults: documentedDefaults.filter(name => !actual.has(name)),
+        unknownKeys: [...actual]
+            .filter(name => !documented.has(name) && !isKnownUndocumentedEnv(name))
+            .sort(),
+    };
+}
+function plural(count, one, many) {
+    return count === 1 ? one : many;
+}
+function compactList(names, limit = 8) {
+    if (names.length <= limit)
+        return names.join(', ');
+    return `${names.slice(0, limit).join(', ')} +${names.length - limit} more`;
+}
+export function formatEnvDriftReport(report) {
+    const parts = [];
+    if (report.missingDocumentedDefaults.length > 0) {
+        parts.push(`${report.missingDocumentedDefaults.length} documented ${plural(report.missingDocumentedDefaults.length, 'default', 'defaults')} missing`);
+    }
+    if (report.unknownKeys.length > 0) {
+        parts.push(`${report.unknownKeys.length} unrecognised ${plural(report.unknownKeys.length, 'key', 'keys')}`);
+    }
+    if (parts.length === 0)
+        return [];
+    const lines = [`[config] .env check: ${parts.join('; ')}. Startup continues.`];
+    if (report.missingDocumentedDefaults.length > 0) {
+        lines.push(`[config]   missing from .env: ${compactList(report.missingDocumentedDefaults)}`);
+    }
+    if (report.unknownKeys.length > 0) {
+        lines.push(`[config]   not in .env.example: ${compactList(report.unknownKeys)}`);
+    }
+    lines.push('[config]   Compare .env.example when you next edit your config.');
+    return lines;
+}
+export function checkEnvDrift(paths = {}) {
+    const defaults = defaultEnvDriftPaths();
+    const envPath = paths.envPath ?? defaults.envPath;
+    const examplePath = paths.examplePath ?? defaults.examplePath;
+    if (!fs.existsSync(envPath) || !fs.existsSync(examplePath))
+        return null;
+    try {
+        return compareEnvText(fs.readFileSync(envPath, 'utf8'), fs.readFileSync(examplePath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function warnOnEnvDrift(paths, logger = console) {
+    const report = checkEnvDrift(paths);
+    if (!report)
+        return null;
+    for (const line of formatEnvDriftReport(report))
+        logger.warn(line);
+    return report;
+}
+//# sourceMappingURL=env-drift.js.map

package/dist/lib/env-drift.js.map

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

package/dist/lib/error-classify.d.ts

@@ -0,0 +1,40 @@
+export declare function isRetryableError(err: any): boolean;
+/** True when the error — or anything in its bounded cause chain — is a
+ * transient network transport failure: a reset, dropped, refused or timed-out
+ * socket, a failed TLS handshake, or an undici transport code. */
+export declare function isTransportError(err: any): boolean;
+export declare function isRateLimitSignal(err: any): boolean;
+export declare const TIMEOUT_ERROR_MARKERS: readonly ["timeout", "stalled", "etimedout", "aborted"];
+/** True when an error message reads as a timeout. Expects raw text; caller need
+ * not lowercase it. */
+export declare function isTimeoutErrorText(message: unknown): boolean;
+export declare function newClientAbortError(): Error;
+/** True when an error is (or wraps) the client-disconnect abort above. The
+ * structured marker is the primary signal; `cause` is checked because some
+ * transports re-wrap the abort reason, and the message substring is the last
+ * resort for errors that were stringified across a boundary. */
+export declare function isClientAbortError(err: any): boolean;
+export declare function newHedgeAbortError(): Error;
+/** True when an error is (or wraps) the time-budget hedge abort above. */
+export declare function isHedgeAbortError(err: any): boolean;
+/** True for any fetch-abort rejection surfacing out of a body read — the
+ * per-attempt timeout ('request'-bounds deadline in fetchWithTimeout), an
+ * AbortSignal.timeout, or the client disconnect above. Adapters that wrap
+ * res.json() in a diagnostic catch (openai-compat's non-JSON-body split) must
+ * rethrow these instead of classifying them as a malformed provider body. */
+export declare function isAbortLikeError(err: any): boolean;
+export declare function isKeyAuthError(err: any): boolean;
+export declare function isDailyQuotaExhaustedError(err: any): boolean;
+export declare function isProviderDegradedError(err: any): boolean;
+export declare function isProviderLevelError(err: any): boolean;
+export declare function isUpstreamClassificationOutput(text: unknown, platform?: string): boolean;
+export declare function isProviderBadRequestError(err: any): boolean;
+export declare function isContextTooLargeError(err: any): boolean;
+export declare function isPaymentRequiredError(err: any): boolean;
+export declare function isModelNotFoundError(err: any): boolean;
+export declare function isAccountSuspendedError(err: any): boolean;
+export declare function isModelAccessForbiddenError(err: any): boolean;
+export type ModelRetirementConfidence = 'definitive' | 'probable';
+export declare function modelRetirementSignal(err: any): ModelRetirementConfidence | null;
+export declare function isStreamTruncatedError(err: any): boolean;
+//# sourceMappingURL=error-classify.d.ts.map

package/dist/lib/error-classify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-classify.d.ts","sourceRoot":"","sources":["../../src/lib/error-classify.ts"],"names":[],"mappings":"AAKA,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAyGlD;AAsED;;kEAEkE;AAClE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAuBlD;AAcD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAMnD;AAiBD,eAAO,MAAM,qBAAqB,yDAA0D,CAAC;AAE7F;uBACuB;AACvB,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAG5D;AAWD,wBAAgB,mBAAmB,IAAI,KAAK,CAI3C;AAED;;;gEAGgE;AAChE,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAKpD;AAUD,wBAAgB,kBAAkB,IAAI,KAAK,CAI1C;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAKnD;AAED;;;;6EAI6E;AAC7E,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAIlD;AAqBD,wBAAgB,cAAc,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAgBhD;AAeD,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAM5D;AAQD,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAGzD;AAiBD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAmBtD;AAeD,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAIxF;AAKD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAQ3D;AAuBD,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAsBxD;AAeD,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAUxD;AAaD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CA+BtD;AAaD,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAMzD;AAQD,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAiB7D;AAuCD,MAAM,MAAM,yBAAyB,GAAG,YAAY,GAAG,UAAU,CAAC;AAqBlE,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,GAAG,GAAG,yBAAyB,GAAG,IAAI,CAahF;AAgBD,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CASxD"}