@nvae/llmswitch 0.6.0 → 0.8.0

package/dist/gateway/health.js

@@ -0,0 +1,45 @@
+/**
+ * In-process failure breaker per provider.
+ *
+ * Without it, a dead primary upstream absorbs one failed attempt on every
+ * request before fallback kicks in. After repeated failures the provider is put
+ * on an exponentially growing cooldown (capped); during cooldown routing skips
+ * it straight to the next candidate. If every candidate is cooling down the
+ * gateway tries them anyway — a delayed answer beats a hard failure.
+ *
+ * State is owned by the running server instance: process-local by design, so a
+ * restart clears it and tests never leak between servers.
+ */
+const COOLDOWN_BASE_MS = 5_000;
+const COOLDOWN_MAX_MS = 120_000;
+export class ProviderBreaker {
+    states = new Map();
+    allows(provider, now = Date.now()) {
+        const state = this.states.get(provider);
+        if (!state)
+            return true;
+        return now >= state.openUntil;
+    }
+    failure(provider, message, now = Date.now()) {
+        const state = this.states.get(provider) ??
+            { consecutiveFailures: 0, openUntil: 0, lastError: "" };
+        state.consecutiveFailures += 1;
+        state.lastError = message.slice(0, 300);
+        const backoff = Math.min(COOLDOWN_BASE_MS * 2 ** (state.consecutiveFailures - 1), COOLDOWN_MAX_MS);
+        state.openUntil = now + backoff;
+        this.states.set(provider, state);
+    }
+    success(provider) {
+        this.states.delete(provider);
+    }
+    snapshot(now = Date.now()) {
+        return [...this.states.entries()]
+            .map(([provider, state]) => ({
+            provider,
+            consecutiveFailures: state.consecutiveFailures,
+            coolingMsRemaining: Math.max(0, state.openUntil - now),
+            lastError: state.lastError,
+        }))
+            .sort((a, b) => b.coolingMsRemaining - a.coolingMsRemaining);
+    }
+}

package/dist/gateway/keys.js

@@ -0,0 +1,433 @@
+/**
+ * Gateway API key issuance and verification.
+ *
+ * Keys are high-entropy random secrets, so a single salted SHA-256 is enough at
+ * rest: there is no low-entropy password to grind. A slow KDF would only add
+ * per-request latency on the hot auth path. The plaintext is returned once at
+ * creation and never persisted.
+ *
+ * Plaintext layout: `llmsk-<keyId>-<secret>`. The embedded id makes lookup O(1)
+ * so verification hashes exactly one candidate.
+ */
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { chmodSync, existsSync, readFileSync } from "node:fs";
+import { atomicWriteFile, ensureDir } from "../utils/fs.js";
+import { getGatewayDir, getGatewayKeysPath } from "../utils/paths.js";
+import { checkDailyQuota, checkRateLimit } from "./rate-limit.js";
+import { isGatewayFormat, } from "./types.js";
+const KEY_PREFIX = "llmsk";
+const KEY_ID_BYTES = 6;
+const KEY_SECRET_BYTES = 32;
+const SALT_BYTES = 16;
+/**
+ * Explicit "never rate-limit this key" marker. `0` keeps the legacy meaning of
+ * inheriting the global default so existing key files behave unchanged.
+ */
+export const UNLIMITED_RATE_LIMIT = -1;
+/** Minimum gap between lastUsedAt persists for one key. */
+const TOUCH_INTERVAL_MS = 60_000;
+const lastTouchedAt = new Map();
+export class GatewayKeyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GatewayKeyError";
+    }
+}
+function asRecord(value) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    return null;
+}
+function stringList(value) {
+    if (!Array.isArray(value))
+        return [];
+    return Array.from(new Set(value
+        .filter((item) => typeof item === "string")
+        .map((item) => item.trim())
+        .filter(Boolean)));
+}
+function hashSecret(secret, salt) {
+    return createHash("sha256").update(`${salt}:${secret}`, "utf8").digest("hex");
+}
+function constantTimeEqual(a, b) {
+    const bufA = Buffer.from(a, "utf8");
+    const bufB = Buffer.from(b, "utf8");
+    if (bufA.length !== bufB.length)
+        return false;
+    return timingSafeEqual(bufA, bufB);
+}
+function normalizeFormats(value) {
+    const list = stringList(value);
+    if (!list.length)
+        return ["*"];
+    if (list.includes("*"))
+        return ["*"];
+    const out = list.filter((item) => isGatewayFormat(item));
+    return out.length ? out : ["*"];
+}
+/**
+ * Strict format validation for newly issued keys: an invalid value must fail
+ * loudly instead of silently widening the scope to every format.
+ */
+function assertValidFormats(value) {
+    const list = stringList(value);
+    for (const item of list) {
+        if (item !== "*" && !isGatewayFormat(item)) {
+            throw new GatewayKeyError(`无效的接口格式「${item}」。可用：openai-chat, anthropic, openai-responses, *`);
+        }
+    }
+}
+/** Non-negative integer or 0. */
+function nonNegative(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0
+        ? Math.floor(value)
+        : 0;
+}
+/** Per-key rate limit: >= 1 is a cap, 0 inherits the global default, -1 is unlimited. */
+function normalizeRateLimit(value) {
+    if (value === UNLIMITED_RATE_LIMIT)
+        return UNLIMITED_RATE_LIMIT;
+    if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
+        return Math.floor(value);
+    }
+    return 0;
+}
+function normalizeKey(raw) {
+    const row = asRecord(raw);
+    if (!row)
+        return null;
+    const id = String(row.id || "").trim();
+    const hash = String(row.hash || "").trim();
+    const salt = String(row.salt || "").trim();
+    if (!id || !hash || !salt)
+        return null;
+    return {
+        id,
+        name: typeof row.name === "string" && row.name ? row.name : id,
+        hash,
+        salt,
+        hint: typeof row.hint === "string" ? row.hint : "",
+        createdAt: typeof row.createdAt === "string"
+            ? row.createdAt
+            : new Date(0).toISOString(),
+        expiresAt: typeof row.expiresAt === "string" ? row.expiresAt : null,
+        revokedAt: typeof row.revokedAt === "string" ? row.revokedAt : null,
+        providers: stringList(row.providers),
+        models: stringList(row.models),
+        formats: normalizeFormats(row.formats),
+        rateLimitPerMinute: normalizeRateLimit(row.rateLimitPerMinute),
+        requestsPerDay: nonNegative(row.requestsPerDay),
+        lastUsedAt: typeof row.lastUsedAt === "string" ? row.lastUsedAt : null,
+    };
+}
+export function listGatewayKeys() {
+    const path = getGatewayKeysPath();
+    if (!existsSync(path))
+        return [];
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        const rows = Array.isArray(raw)
+            ? raw
+            : Array.isArray(asRecord(raw)?.keys)
+                ? asRecord(raw).keys
+                : [];
+        return rows
+            .map(normalizeKey)
+            .filter((key) => key !== null);
+    }
+    catch {
+        return [];
+    }
+}
+function writeGatewayKeys(keys) {
+    ensureDir(getGatewayDir());
+    try {
+        chmodSync(getGatewayDir(), 0o700);
+    }
+    catch {
+        // Windows relies on user-directory ACLs.
+    }
+    atomicWriteFile(getGatewayKeysPath(), JSON.stringify({ version: 1, keys }, null, 2) + "\n");
+}
+export function createGatewayKey(options = {}) {
+    assertValidFormats(options.formats);
+    const id = randomBytes(KEY_ID_BYTES).toString("hex");
+    const secret = randomBytes(KEY_SECRET_BYTES).toString("base64url");
+    const salt = randomBytes(SALT_BYTES).toString("hex");
+    const plaintext = `${KEY_PREFIX}-${id}-${secret}`;
+    const days = options.expiresInDays ?? 0;
+    if (days < 0 || !Number.isFinite(days)) {
+        throw new GatewayKeyError("有效期天数必须是非负数");
+    }
+    const expiresAt = days > 0
+        ? new Date(Date.now() + days * 86_400_000).toISOString()
+        : null;
+    const key = {
+        id,
+        name: options.name?.trim() || `key-${id.slice(0, 4)}`,
+        hash: hashSecret(secret, salt),
+        salt,
+        hint: `${KEY_PREFIX}-${id}-${secret.slice(0, 4)}…${secret.slice(-4)}`,
+        createdAt: new Date().toISOString(),
+        expiresAt,
+        revokedAt: null,
+        providers: stringList(options.providers),
+        models: stringList(options.models),
+        formats: normalizeFormats(options.formats),
+        rateLimitPerMinute: normalizeRateLimit(options.rateLimitPerMinute),
+        requestsPerDay: nonNegative(options.requestsPerDay),
+        lastUsedAt: null,
+    };
+    writeGatewayKeys([...listGatewayKeys(), key]);
+    return { key, plaintext };
+}
+export function revokeGatewayKey(idOrName) {
+    const keys = listGatewayKeys();
+    const target = findKeyByIdOrName(keys, idOrName);
+    if (!target)
+        throw new GatewayKeyError(`未找到 API Key「${idOrName}」`);
+    if (target.revokedAt)
+        return target;
+    const revoked = {
+        ...target,
+        revokedAt: new Date().toISOString(),
+    };
+    writeGatewayKeys(keys.map((key) => (key.id === target.id ? revoked : key)));
+    return revoked;
+}
+export function deleteGatewayKey(idOrName) {
+    const keys = listGatewayKeys();
+    const target = findKeyByIdOrName(keys, idOrName);
+    if (!target)
+        throw new GatewayKeyError(`未找到 API Key「${idOrName}」`);
+    writeGatewayKeys(keys.filter((key) => key.id !== target.id));
+    return target;
+}
+export function updateGatewayKey(idOrName, patch) {
+    assertValidFormats(patch.formats ?? []);
+    const days = patch.expiresInDays;
+    if (days !== undefined && (days < 0 || !Number.isFinite(days))) {
+        throw new GatewayKeyError("有效期天数必须是非负数");
+    }
+    const keys = listGatewayKeys();
+    const target = findKeyByIdOrName(keys, idOrName);
+    if (!target)
+        throw new GatewayKeyError(`未找到 API Key「${idOrName}」`);
+    const next = {
+        ...target,
+        name: patch.name?.trim() || target.name,
+        ...(patch.providers ? { providers: stringList(patch.providers) } : {}),
+        ...(patch.models ? { models: stringList(patch.models) } : {}),
+        ...(patch.formats ? { formats: normalizeFormats(patch.formats) } : {}),
+        ...(patch.rateLimitPerMinute !== undefined
+            ? { rateLimitPerMinute: normalizeRateLimit(patch.rateLimitPerMinute) }
+            : {}),
+        ...(patch.requestsPerDay !== undefined
+            ? { requestsPerDay: nonNegative(patch.requestsPerDay) }
+            : {}),
+        ...(days !== undefined
+            ? {
+                expiresAt: days > 0
+                    ? new Date(Date.now() + days * 86_400_000).toISOString()
+                    : null,
+            }
+            : {}),
+    };
+    writeGatewayKeys(keys.map((key) => (key.id === target.id ? next : key)));
+    return next;
+}
+/**
+ * Re-issue a key with a fresh id and secret while keeping its scopes. The old
+ * plaintext stops working immediately; the new one is shown once.
+ */
+export function rotateGatewayKey(idOrName) {
+    const keys = listGatewayKeys();
+    const target = findKeyByIdOrName(keys, idOrName);
+    if (!target)
+        throw new GatewayKeyError(`未找到 API Key「${idOrName}」`);
+    const id = randomBytes(KEY_ID_BYTES).toString("hex");
+    const secret = randomBytes(KEY_SECRET_BYTES).toString("base64url");
+    const salt = randomBytes(SALT_BYTES).toString("hex");
+    const rotated = {
+        ...target,
+        id,
+        hash: hashSecret(secret, salt),
+        salt,
+        hint: `${KEY_PREFIX}-${id}-${secret.slice(0, 4)}…${secret.slice(-4)}`,
+        createdAt: new Date().toISOString(),
+        lastUsedAt: null,
+    };
+    writeGatewayKeys(keys.map((key) => (key.id === target.id ? rotated : key)));
+    return {
+        key: rotated,
+        plaintext: `${KEY_PREFIX}-${id}-${secret}`,
+    };
+}
+function findKeyByIdOrName(keys, idOrName) {
+    const query = idOrName.trim();
+    if (!query)
+        return undefined;
+    return (keys.find((key) => key.id === query) ||
+        keys.find((key) => key.name === query) ||
+        keys.find((key) => key.id.startsWith(query)));
+}
+export function publicKeyView(key) {
+    return {
+        id: key.id,
+        name: key.name,
+        hint: key.hint,
+        createdAt: key.createdAt,
+        expiresAt: key.expiresAt,
+        revokedAt: key.revokedAt,
+        status: keyStatus(key),
+        providers: key.providers,
+        models: key.models,
+        formats: key.formats,
+        rateLimitPerMinute: key.rateLimitPerMinute,
+        requestsPerDay: key.requestsPerDay,
+        lastUsedAt: key.lastUsedAt,
+    };
+}
+export function keyStatus(key) {
+    if (key.revokedAt)
+        return "revoked";
+    if (key.expiresAt && Date.parse(key.expiresAt) <= Date.now()) {
+        return "expired";
+    }
+    return "active";
+}
+export function hasAnyActiveKey() {
+    return listGatewayKeys().some((key) => keyStatus(key) === "active");
+}
+function parsePlaintext(plaintext) {
+    const parts = plaintext.trim().split("-");
+    if (parts.length < 3)
+        return null;
+    if (parts[0] !== KEY_PREFIX)
+        return null;
+    const id = parts[1] ?? "";
+    const secret = parts.slice(2).join("-");
+    if (!id || !secret)
+        return null;
+    return { id, secret };
+}
+/** In-memory fixed-window counters were replaced by a cross-process store. */
+export { checkDailyQuota, checkRateLimit, peekDailyQuota, peekRateLimit, resetRateLimits, } from "./rate-limit.js";
+/** -1 = unlimited, > 0 = per-key cap, otherwise fall back to the global default. */
+export function resolveKeyRateLimit(keyLimit, defaultLimit) {
+    if (keyLimit === UNLIMITED_RATE_LIMIT)
+        return 0;
+    if (keyLimit > 0)
+        return keyLimit;
+    return defaultLimit > 0 ? defaultLimit : 0;
+}
+export function authenticateGatewayKey(presented, options = {}) {
+    if (!presented || !presented.trim())
+        return { ok: false, reason: "missing" };
+    const parsed = parsePlaintext(presented);
+    if (!parsed)
+        return { ok: false, reason: "malformed" };
+    const keys = options.keys ?? listGatewayKeys();
+    const candidate = keys.find((key) => key.id === parsed.id);
+    if (!candidate)
+        return { ok: false, reason: "unknown" };
+    if (!constantTimeEqual(candidate.hash, hashSecret(parsed.secret, candidate.salt))) {
+        return { ok: false, reason: "unknown" };
+    }
+    const now = options.now ?? Date.now();
+    if (candidate.revokedAt)
+        return { ok: false, reason: "revoked" };
+    if (candidate.expiresAt && Date.parse(candidate.expiresAt) <= now) {
+        return { ok: false, reason: "expired" };
+    }
+    if (options.format && !candidate.formats.includes("*")) {
+        if (!candidate.formats.includes(options.format)) {
+            return { ok: false, reason: "format_denied" };
+        }
+    }
+    const limit = resolveKeyRateLimit(candidate.rateLimitPerMinute, options.defaultRateLimitPerMinute ?? 0);
+    const rate = checkRateLimit(candidate.id, limit, now);
+    if (!rate.allowed) {
+        return {
+            ok: false,
+            reason: "rate_limited",
+            retryAfterSeconds: rate.retryAfterSeconds,
+            rate,
+        };
+    }
+    if (candidate.requestsPerDay > 0) {
+        const daily = checkDailyQuota(candidate.id, candidate.requestsPerDay, now);
+        if (!daily.allowed) {
+            return {
+                ok: false,
+                reason: "rate_limited",
+                retryAfterSeconds: daily.retryAfterSeconds,
+                rate: daily,
+            };
+        }
+    }
+    return { ok: true, key: candidate, rate };
+}
+/**
+ * Best-effort last-used bookkeeping. Debounced: a busy key would otherwise
+ * rewrite the whole key file on every single request.
+ */
+export function touchGatewayKey(id, now = Date.now()) {
+    const last = lastTouchedAt.get(id) ?? 0;
+    if (now - last < TOUCH_INTERVAL_MS)
+        return;
+    lastTouchedAt.set(id, now);
+    try {
+        const keys = listGatewayKeys();
+        const next = keys.map((key) => key.id === id ? { ...key, lastUsedAt: new Date(now).toISOString() } : key);
+        writeGatewayKeys(next);
+    }
+    catch {
+        // Non-fatal.
+    }
+}
+/**
+ * Whether a key may use the resolved provider and model.
+ *
+ * `model` is the upstream id resolved by the router; `requestedModel` is the
+ * raw id the client sent (an alias or a qualified `provider/model` reference).
+ * A scope entry matches when it equals either id, so keys scoped to an alias
+ * keep working after the alias is remapped to a different upstream id.
+ */
+export function keyAllowsTarget(key, providerName, model, requestedModel) {
+    if (key.providers.length && !key.providers.includes(providerName)) {
+        return false;
+    }
+    if (!key.models.length)
+        return true;
+    return modelScopeMatches(key.models, providerName, model, requestedModel);
+}
+function modelScopeMatches(scope, providerName, model, requestedModel) {
+    const provider = providerName.trim().toLowerCase();
+    // Every spelling that should count as "this model on this provider".
+    const wanted = new Set();
+    const add = (value) => {
+        const id = value?.trim().toLowerCase();
+        if (!id)
+            return;
+        wanted.add(id);
+        wanted.add(`${provider}/${id}`);
+    };
+    add(model);
+    add(requestedModel);
+    return scope.some((entry) => {
+        const id = entry.trim().toLowerCase();
+        if (!id)
+            return false;
+        if (wanted.has(id))
+            return true;
+        // A scoped entry may itself be qualified (`provider/model`); compare both
+        // halves so an entry for another provider never matches by accident.
+        const separator = id.indexOf("/");
+        if (separator <= 0)
+            return false;
+        return (id.slice(0, separator) === provider &&
+            wanted.has(id.slice(separator + 1)));
+    });
+}