@sriinnu/kosha-discovery 0.5.0

package/dist/resilience.js

@@ -0,0 +1,292 @@
+/**
+ * kosha-discovery — Resilience primitives.
+ *
+ * Provides a {@link CircuitBreaker} for per-provider fault isolation,
+ * a {@link HealthTracker} that manages breakers for all known providers,
+ * and a {@link StaleCachePolicy} that implements stale-while-revalidate
+ * semantics on top of {@link KoshaCache}.
+ *
+ * The module is self-contained with no side-effects on import.
+ * @module
+ */
+// ---------------------------------------------------------------------------
+// CircuitBreaker
+// ---------------------------------------------------------------------------
+/**
+ * Per-provider circuit breaker with three states.
+ *
+ * - **closed** — Normal operation. All requests are allowed. Consecutive
+ *   failures are counted; once the {@link CircuitBreakerOptions.failureThreshold}
+ *   is reached the circuit transitions to `open`.
+ * - **open** — Requests are rejected immediately (canExecute returns false).
+ *   After {@link CircuitBreakerOptions.resetTimeoutMs} has elapsed the circuit
+ *   transitions to `half-open` so a single probe request can be attempted.
+ * - **half-open** — Exactly one request is let through. A success closes the
+ *   circuit; a failure re-opens it and resets the timeout.
+ *
+ * @example
+ * const cb = new CircuitBreaker("anthropic", { failureThreshold: 5 });
+ * if (cb.canExecute()) {
+ *   try {
+ *     const result = await callApi();
+ *     cb.onSuccess();
+ *   } catch (err) {
+ *     cb.onFailure(err.message);
+ *   }
+ * }
+ */
+export class CircuitBreaker {
+    providerId;
+    options;
+    state = "closed";
+    failureCount = 0;
+    successCount = 0;
+    lastFailureTime = 0;
+    lastSuccessTime = 0;
+    lastError;
+    /** Resolved threshold: consecutive failures before opening. */
+    failureThreshold;
+    /** Resolved open-state duration before allowing a probe. */
+    resetTimeoutMs;
+    /** Resolved success count in half-open needed to close. */
+    halfOpenSuccessThreshold;
+    constructor(providerId, options = {}) {
+        this.providerId = providerId;
+        this.options = options;
+        this.failureThreshold = options.failureThreshold ?? 3;
+        this.resetTimeoutMs = options.resetTimeoutMs ?? 60_000;
+        this.halfOpenSuccessThreshold = options.halfOpenSuccessThreshold ?? 1;
+    }
+    /**
+     * Check whether a request should be allowed through.
+     *
+     * - `closed` → always true.
+     * - `open` → false, unless the reset timeout has elapsed, in which case
+     *   the circuit transitions to `half-open` and returns true for the probe.
+     * - `half-open` → true (the probe request is already in flight).
+     */
+    canExecute() {
+        if (this.state === "closed") {
+            return true;
+        }
+        if (this.state === "open") {
+            const elapsed = Date.now() - this.lastFailureTime;
+            if (elapsed >= this.resetTimeoutMs) {
+                // Transition to half-open: allow a single probe
+                this.state = "half-open";
+                this.successCount = 0;
+                return true;
+            }
+            return false;
+        }
+        // half-open: allow the probe through
+        return true;
+    }
+    /**
+     * Record a successful API call.
+     *
+     * In `half-open` state, once enough successes accumulate (per
+     * {@link CircuitBreakerOptions.halfOpenSuccessThreshold}) the circuit closes.
+     * In `closed` state the failure counter is reset.
+     */
+    onSuccess() {
+        this.lastSuccessTime = Date.now();
+        if (this.state === "half-open") {
+            this.successCount++;
+            if (this.successCount >= this.halfOpenSuccessThreshold) {
+                this.transitionToClosed();
+            }
+            return;
+        }
+        // In closed state reset the failure counter on any success
+        if (this.state === "closed") {
+            this.failureCount = 0;
+        }
+    }
+    /**
+     * Record a failed API call.
+     *
+     * In `closed` state, increments the failure counter and opens the circuit
+     * when the threshold is reached. In `half-open` state, immediately
+     * re-opens the circuit.
+     *
+     * @param error - Optional error message to store for diagnostics.
+     */
+    onFailure(error) {
+        this.lastFailureTime = Date.now();
+        this.lastError = error;
+        if (this.state === "half-open") {
+            // Probe failed — reopen immediately
+            this.transitionToOpen();
+            return;
+        }
+        if (this.state === "closed") {
+            this.failureCount++;
+            if (this.failureCount >= this.failureThreshold) {
+                this.transitionToOpen();
+            }
+        }
+    }
+    /**
+     * Return a point-in-time health snapshot for this provider's circuit.
+     */
+    health() {
+        return {
+            providerId: this.providerId,
+            state: this.state,
+            failureCount: this.failureCount,
+            lastFailureTime: this.lastFailureTime,
+            lastError: this.lastError,
+            lastSuccessTime: this.lastSuccessTime,
+        };
+    }
+    /**
+     * Force the circuit back to `closed` state, resetting all counters.
+     * Useful for manual recovery or test teardown.
+     */
+    reset() {
+        this.transitionToClosed();
+        this.lastFailureTime = 0;
+        this.lastSuccessTime = 0;
+        this.lastError = undefined;
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    transitionToOpen() {
+        this.state = "open";
+        this.successCount = 0;
+    }
+    transitionToClosed() {
+        this.state = "closed";
+        this.failureCount = 0;
+        this.successCount = 0;
+    }
+}
+// ---------------------------------------------------------------------------
+// HealthTracker
+// ---------------------------------------------------------------------------
+/**
+ * Manages {@link CircuitBreaker} instances for all tracked providers.
+ *
+ * Breakers are created lazily on first access via {@link breaker}.
+ *
+ * @example
+ * const tracker = new HealthTracker();
+ * const cb = tracker.breaker("anthropic");
+ * if (cb.canExecute()) { ... }
+ */
+export class HealthTracker {
+    breakers = new Map();
+    /**
+     * Retrieve the {@link CircuitBreaker} for the given provider, creating
+     * one with default options if it does not yet exist.
+     *
+     * @param providerId - Provider slug (e.g. `"anthropic"`).
+     * @param options    - Options forwarded to a newly created breaker only.
+     */
+    breaker(providerId, options) {
+        let cb = this.breakers.get(providerId);
+        if (!cb) {
+            cb = new CircuitBreaker(providerId, options);
+            this.breakers.set(providerId, cb);
+        }
+        return cb;
+    }
+    /**
+     * Return health snapshots for every tracked provider, sorted by provider ID.
+     */
+    healthReport() {
+        return Array.from(this.breakers.values())
+            .map((cb) => cb.health())
+            .sort((a, b) => a.providerId.localeCompare(b.providerId));
+    }
+    /**
+     * Return provider IDs whose circuit is `closed` or `half-open`
+     * (i.e. requests are currently being allowed through).
+     */
+    availableProviders() {
+        return Array.from(this.breakers.values())
+            .filter((cb) => cb.canExecute())
+            .map((cb) => cb.providerId)
+            .sort();
+    }
+    /**
+     * Return provider IDs whose circuit is `open`
+     * (i.e. requests are currently being rejected).
+     */
+    downProviders() {
+        return Array.from(this.breakers.values())
+            .filter((cb) => !cb.canExecute())
+            .map((cb) => cb.providerId)
+            .sort();
+    }
+    /**
+     * Reset all tracked circuit breakers to `closed` state.
+     */
+    resetAll() {
+        for (const cb of this.breakers.values()) {
+            cb.reset();
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// StaleCachePolicy
+// ---------------------------------------------------------------------------
+/**
+ * Utility that wraps {@link KoshaCache} reads to implement
+ * stale-while-revalidate semantics.
+ *
+ * Unlike the registry's normal cache path (which returns `null` for expired
+ * entries), this policy always returns whatever was cached along with a
+ * `stale` flag. This lets callers serve the old data immediately while
+ * triggering a background refresh.
+ *
+ * Returns `null` only when the cache has never held a value for the key.
+ *
+ * @example
+ * const result = await StaleCachePolicy.getWithStale<ModelCard[]>(cache, "provider_anthropic");
+ * if (result) {
+ *   serveToClient(result.data); // always fast
+ *   if (result.stale) triggerBackgroundRefresh();
+ * }
+ */
+export class StaleCachePolicy {
+    /**
+     * Fetch a cached value regardless of its expiry, annotating the result
+     * with staleness metadata.
+     *
+     * @param cache - The {@link KoshaCache} instance to read from.
+     * @param key   - Cache key to look up.
+     * @returns A {@link StaleResult} when any cached value exists, or `null`
+     *          when the key has never been written.
+     */
+    static async getWithStale(cache, key) {
+        // Use the raw get() which returns the entry regardless of TTL.
+        // TTL checking is done separately so we can set the stale flag.
+        const entry = await cache.get(key);
+        if (entry === null) {
+            return null;
+        }
+        const now = Date.now();
+        const age = now - entry.timestamp;
+        // We need to determine staleness. KoshaCache.isExpired requires a TTL,
+        // but StaleCachePolicy is TTL-agnostic — we expose the raw age and let
+        // the caller decide. We set stale=true when age > 0 to signal that the
+        // entry is not brand-new; callers that want TTL-based staleness should
+        // compare age against their own threshold.
+        //
+        // A more useful signal: mark stale when the entry is older than the
+        // default 24 h cache TTL used by the registry. Callers with custom TTLs
+        // can compare age directly.
+        const DEFAULT_TTL_MS = 86_400_000;
+        const stale = age > DEFAULT_TTL_MS;
+        return {
+            data: entry.data,
+            stale,
+            age,
+            cachedAt: entry.timestamp,
+        };
+    }
+}
+//# sourceMappingURL=resilience.js.map

package/dist/resilience.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resilience.js","sourceRoot":"","sources":["../src/resilience.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAgEH,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,cAAc;IAeL;IAA4B;IAdzC,KAAK,GAAiB,QAAQ,CAAC;IAC/B,YAAY,GAAG,CAAC,CAAC;IACjB,YAAY,GAAG,CAAC,CAAC;IACjB,eAAe,GAAG,CAAC,CAAC;IACpB,eAAe,GAAG,CAAC,CAAC;IACpB,SAAS,CAAU;IAE3B,+DAA+D;IAC9C,gBAAgB,CAAS;IAC1C,4DAA4D;IAC3C,cAAc,CAAS;IACxC,2DAA2D;IAC1C,wBAAwB,CAAS;IAElD,YAAqB,UAAkB,EAAU,UAAiC,EAAE;QAA/D,eAAU,GAAV,UAAU,CAAQ;QAAU,YAAO,GAAP,OAAO,CAA4B;QACnF,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,CAAC,CAAC;QACtD,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,MAAM,CAAC;QACvD,IAAI,CAAC,wBAAwB,GAAG,OAAO,CAAC,wBAAwB,IAAI,CAAC,CAAC;IACvE,CAAC;IAED;;;;;;;OAOG;IACH,UAAU;QACT,IAAI,IAAI,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC7B,OAAO,IAAI,CAAC;QACb,CAAC;QAED,IAAI,IAAI,CAAC,KAAK,KAAK,MAAM,EAAE,CAAC;YAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe,CAAC;YAClD,IAAI,OAAO,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;gBACpC,gDAAgD;gBAChD,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC;gBACzB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;gBACtB,OAAO,IAAI,CAAC;YACb,CAAC;YACD,OAAO,KAAK,CAAC;QACd,CAAC;QAED,qCAAqC;QACrC,OAAO,IAAI,CAAC;IACb,CAAC;IAED;;;;;;OAMG;IACH,SAAS;QACR,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAElC,IAAI,IAAI,CAAC,KAAK,KAAK,WAAW,EAAE,CAAC;YAChC,IAAI,CAAC,YAAY,EAAE,CAAC;YACpB,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,wBAAwB,EAAE,CAAC;gBACxD,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAC3B,CAAC;YACD,OAAO;QACR,CAAC;QAED,2DAA2D;QAC3D,IAAI,IAAI,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC7B,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;QACvB,CAAC;IACF,CAAC;IAED;;;;;;;;OAQG;IACH,SAAS,CAAC,KAAc;QACvB,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAClC,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;QAEvB,IAAI,IAAI,CAAC,KAAK,KAAK,WAAW,EAAE,CAAC;YAChC,oCAAoC;YACpC,IAAI,CAAC,gBAAgB,EAAE,CAAC;YACxB,OAAO;QACR,CAAC;QAED,IAAI,IAAI,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC7B,IAAI,CAAC,YAAY,EAAE,CAAC;YACpB,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;gBAChD,IAAI,CAAC,gBAAgB,EAAE,CAAC;YACzB,CAAC;QACF,CAAC;IACF,CAAC;IAED;;OAEG;IACH,MAAM;QACL,OAAO;YACN,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,eAAe,EAAE,IAAI,CAAC,eAAe;YACrC,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,eAAe,EAAE,IAAI,CAAC,eAAe;SACrC,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK;QACJ,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC1B,IAAI,CAAC,eAAe,GAAG,CAAC,CAAC;QACzB,IAAI,CAAC,eAAe,GAAG,CAAC,CAAC;QACzB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC5B,CAAC;IAED,8EAA8E;IAC9E,kBAAkB;IAClB,8EAA8E;IAEtE,gBAAgB;QACvB,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC;QACpB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;IACvB,CAAC;IAEO,kBAAkB;QACzB,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC;QACtB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;IACvB,CAAC;CACD;AAED,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,MAAM,OAAO,aAAa;IACjB,QAAQ,GAAG,IAAI,GAAG,EAA0B,CAAC;IAErD;;;;;;OAMG;IACH,OAAO,CAAC,UAAkB,EAAE,OAA+B;QAC1D,IAAI,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACvC,IAAI,CAAC,EAAE,EAAE,CAAC;YACT,EAAE,GAAG,IAAI,cAAc,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;YAC7C,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QACnC,CAAC;QACD,OAAO,EAAE,CAAC;IACX,CAAC;IAED;;OAEG;IACH,YAAY;QACX,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;aACvC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC;aACxB,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;IAC5D,CAAC;IAED;;;OAGG;IACH,kBAAkB;QACjB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;aACvC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,UAAU,EAAE,CAAC;aAC/B,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,UAAU,CAAC;aAC1B,IAAI,EAAE,CAAC;IACV,CAAC;IAED;;;OAGG;IACH,aAAa;QACZ,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;aACvC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,UAAU,EAAE,CAAC;aAChC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,UAAU,CAAC;aAC1B,IAAI,EAAE,CAAC;IACV,CAAC;IAED;;OAEG;IACH,QAAQ;QACP,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;YACzC,EAAE,CAAC,KAAK,EAAE,CAAC;QACZ,CAAC;IACF,CAAC;CACD;AAED,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,gBAAgB;IAC5B;;;;;;;;OAQG;IACH,MAAM,CAAC,KAAK,CAAC,YAAY,CAAI,KAAiB,EAAE,GAAW;QAC1D,+DAA+D;QAC/D,gEAAgE;QAChE,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,GAAG,CAAI,GAAG,CAAC,CAAC;QACtC,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACpB,OAAO,IAAI,CAAC;QACb,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,GAAG,GAAG,GAAG,GAAG,KAAK,CAAC,SAAS,CAAC;QAElC,uEAAuE;QACvE,uEAAuE;QACvE,uEAAuE;QACvE,uEAAuE;QACvE,2CAA2C;QAC3C,EAAE;QACF,oEAAoE;QACpE,wEAAwE;QACxE,4BAA4B;QAC5B,MAAM,cAAc,GAAG,UAAU,CAAC;QAClC,MAAM,KAAK,GAAG,GAAG,GAAG,cAAc,CAAC;QAEnC,OAAO;YACN,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,KAAK;YACL,GAAG;YACH,QAAQ,EAAE,KAAK,CAAC,SAAS;SACzB,CAAC;IACH,CAAC;CACD"}

package/dist/security.d.ts

@@ -0,0 +1,44 @@
+/**
+ * kosha-discovery — Security guardrails for external data.
+ *
+ * Centralised defences against supply-chain data injection.
+ * Every external data ingestion point (HTTP responses, CLI output,
+ * cache reads) MUST pass through {@link assertCleanPayload} before
+ * the parsed payload is used.
+ *
+ * Threat catalogue:
+ * - **base64**           Encoded credential exfiltration (LiteLLM incident)
+ * - **credential_leak**  Leaked API keys / tokens (OpenAI, AWS, GitHub, Slack, Google, etc.)
+ * - **script_injection** XSS / HTML injection via `<script>`, `javascript:`, event handlers
+ * - **shell_injection**  Command injection via `$(…)`, backtick blocks, pipe/chain to shells
+ * - **data_uri**         Executable data URIs (`data:text/html`, `data:application/…`)
+ * - **null_byte**        Null-byte injection to bypass string validators
+ * - **proto_pollution**  Prototype pollution via `__proto__` keys
+ * - **hex_payload**      Long hex-encoded binary blobs (potential obfuscated payloads)
+ * - **oversized_string** Unreasonably long strings for model metadata (>2048 chars)
+ *
+ * @module
+ */
+export interface ThreatHit {
+    threat: string;
+    path: string;
+    value: string;
+}
+/**
+ * Deep-scan a parsed JSON payload for security threats in keys and string
+ * values at any nesting depth.
+ *
+ * @returns The first {@link ThreatHit} found, or `undefined` if clean.
+ */
+export declare function scanPayload(obj: unknown, path?: string): ThreatHit | undefined;
+/**
+ * Throw if the given payload contains **any** security threat — base64,
+ * leaked credentials, script injection, shell injection, data URIs,
+ * null bytes, prototype pollution keys, hex blobs, or oversized strings.
+ *
+ * @param data   - Parsed JSON payload to scan.
+ * @param source - Human-readable label for error messages (e.g. "litellm", "OpenAI API").
+ * @throws {Error} with the threat name and offending path.
+ */
+export declare function assertCleanPayload(data: unknown, source: string): void;
+//# sourceMappingURL=security.d.ts.map

package/dist/security.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../src/security.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAiIH,MAAM,WAAW,SAAS;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACd;AAMD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,SAAK,GAAG,SAAS,GAAG,SAAS,CA8B1E;AAMD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAOtE"}

package/dist/security.js

@@ -0,0 +1,184 @@
+/**
+ * kosha-discovery — Security guardrails for external data.
+ *
+ * Centralised defences against supply-chain data injection.
+ * Every external data ingestion point (HTTP responses, CLI output,
+ * cache reads) MUST pass through {@link assertCleanPayload} before
+ * the parsed payload is used.
+ *
+ * Threat catalogue:
+ * - **base64**           Encoded credential exfiltration (LiteLLM incident)
+ * - **credential_leak**  Leaked API keys / tokens (OpenAI, AWS, GitHub, Slack, Google, etc.)
+ * - **script_injection** XSS / HTML injection via `<script>`, `javascript:`, event handlers
+ * - **shell_injection**  Command injection via `$(…)`, backtick blocks, pipe/chain to shells
+ * - **data_uri**         Executable data URIs (`data:text/html`, `data:application/…`)
+ * - **null_byte**        Null-byte injection to bypass string validators
+ * - **proto_pollution**  Prototype pollution via `__proto__` keys
+ * - **hex_payload**      Long hex-encoded binary blobs (potential obfuscated payloads)
+ * - **oversized_string** Unreasonably long strings for model metadata (>2048 chars)
+ *
+ * @module
+ */
+/** 32+ chars of pure base64 alphabet with optional `=` padding. */
+const BASE64_PATTERN = /^[A-Za-z0-9+/]{32,}={0,2}$/;
+/** Known credential prefixes — each must be followed by enough chars to be a real key. */
+const CREDENTIAL_PATTERNS = [
+    /\bsk-[A-Za-z0-9]{20,}/, // OpenAI API keys
+    /\bsk-proj-[A-Za-z0-9]{20,}/, // OpenAI project keys
+    /\bAKIA[A-Z0-9]{16}/, // AWS access key IDs
+    /\bghp_[A-Za-z0-9]{36,}/, // GitHub personal access tokens
+    /\bgho_[A-Za-z0-9]{36,}/, // GitHub OAuth tokens
+    /\bghs_[A-Za-z0-9]{36,}/, // GitHub app installation tokens
+    /\bxoxb-[A-Za-z0-9\-]{24,}/, // Slack bot tokens
+    /\bxoxp-[A-Za-z0-9\-]{24,}/, // Slack user tokens
+    /\bAIza[A-Za-z0-9_\-]{30,}/, // Google API keys
+    /\bya29\.[A-Za-z0-9_\-]{50,}/, // Google OAuth access tokens
+    /\bglpat-[A-Za-z0-9\-]{20,}/, // GitLab personal access tokens
+    /\bnpm_[A-Za-z0-9]{36,}/, // npm tokens
+    /\bpypi-[A-Za-z0-9]{50,}/, // PyPI tokens
+    /\bhf_[A-Za-z0-9]{30,}/, // Hugging Face tokens
+    /\bBearer\s+[A-Za-z0-9._\-]{40,}/, // Generic bearer tokens in data
+];
+/** Script / HTML injection patterns (case-insensitive). */
+const SCRIPT_PATTERN = /<script[\s>]/i;
+const EVENT_HANDLER_PATTERN = /\bon\w+\s*=\s*["'`]/i;
+const JAVASCRIPT_URI_PATTERN = /javascript\s*:/i;
+/** Shell injection — command substitution and chaining to exfiltration tools. */
+const SHELL_INJECTION_PATTERNS = [
+    /\$\([^)]+\)/, // $(command)
+    /`[^`]{2,}`/, // `command` (backtick execution, 2+ chars to avoid markdown)
+    /[;|&]\s*(curl|wget|nc|bash|sh|python|node|ruby|perl|php)\b/i, // chain to dangerous commands
+];
+/** Data URIs that can carry executable content. */
+const DATA_URI_PATTERN = /^data:(text\/html|application\/)/i;
+/** Null byte in any form. */
+const NULL_BYTE_PATTERN = /\x00|\\x00|\\u0000|%00/;
+/** Long hex-only blobs (64+ hex chars) — potential obfuscated payloads. */
+const HEX_BLOB_PATTERN = /^(0x)?[0-9a-fA-F]{64,}$/;
+/** Prototype pollution key — `__proto__` is the only key that directly
+ *  triggers pollution on `JSON.parse` output when merged naively.
+ *  `constructor` and `prototype` are common legitimate JSON keys and
+ *  are intentionally not flagged to avoid false positives. */
+const PROTO_POLLUTION_KEY = "__proto__";
+/** Maximum reasonable string length for model metadata values. */
+const MAX_STRING_LENGTH = 2048;
+// ---------------------------------------------------------------------------
+// Threat registry — evaluated once per string value during scan.
+// ---------------------------------------------------------------------------
+// Ordered most-specific first → broadest last.  This ensures that a leaked
+// API key (which is also valid base64) reports "credential_leak" rather than
+// the generic "base64" catch-all.
+const VALUE_THREATS = [
+    {
+        name: "null_byte",
+        test: (v) => NULL_BYTE_PATTERN.test(v),
+    },
+    {
+        name: "credential_leak",
+        test: (v) => CREDENTIAL_PATTERNS.some((p) => p.test(v)),
+    },
+    {
+        name: "script_injection",
+        test: (v) => SCRIPT_PATTERN.test(v) || EVENT_HANDLER_PATTERN.test(v) || JAVASCRIPT_URI_PATTERN.test(v),
+    },
+    {
+        name: "shell_injection",
+        test: (v) => SHELL_INJECTION_PATTERNS.some((p) => p.test(v)),
+    },
+    {
+        name: "data_uri",
+        test: (v) => DATA_URI_PATTERN.test(v),
+    },
+    {
+        name: "oversized_string",
+        test: (v) => v.length > MAX_STRING_LENGTH,
+    },
+    {
+        name: "hex_payload",
+        test: (v) => HEX_BLOB_PATTERN.test(v),
+    },
+    {
+        name: "base64",
+        test: (v) => BASE64_PATTERN.test(v),
+    },
+];
+/** Threats checked against object keys specifically. */
+const KEY_THREATS = [
+    {
+        name: "null_byte",
+        test: (v) => NULL_BYTE_PATTERN.test(v),
+    },
+    {
+        name: "proto_pollution",
+        test: (v) => v === PROTO_POLLUTION_KEY,
+    },
+    {
+        name: "credential_leak",
+        test: (v) => CREDENTIAL_PATTERNS.some((p) => p.test(v)),
+    },
+    {
+        name: "base64",
+        test: (v) => BASE64_PATTERN.test(v),
+    },
+];
+// ---------------------------------------------------------------------------
+// Deep scanner
+// ---------------------------------------------------------------------------
+/**
+ * Deep-scan a parsed JSON payload for security threats in keys and string
+ * values at any nesting depth.
+ *
+ * @returns The first {@link ThreatHit} found, or `undefined` if clean.
+ */
+export function scanPayload(obj, path = "") {
+    if (typeof obj === "string") {
+        for (const t of VALUE_THREATS) {
+            if (t.test(obj)) {
+                return { threat: t.name, path, value: obj.length > 80 ? `${obj.slice(0, 80)}…` : obj };
+            }
+        }
+        return undefined;
+    }
+    if (Array.isArray(obj)) {
+        for (let i = 0; i < obj.length; i++) {
+            const hit = scanPayload(obj[i], `${path}[${i}]`);
+            if (hit)
+                return hit;
+        }
+        return undefined;
+    }
+    if (obj !== null && typeof obj === "object") {
+        for (const key of Object.keys(obj)) {
+            // Check the key itself
+            for (const t of KEY_THREATS) {
+                if (t.test(key)) {
+                    return { threat: t.name, path: `${path}.${key}`, value: key };
+                }
+            }
+            // Recurse into the value
+            const hit = scanPayload(obj[key], `${path}.${key}`);
+            if (hit)
+                return hit;
+        }
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Public assertion API
+// ---------------------------------------------------------------------------
+/**
+ * Throw if the given payload contains **any** security threat — base64,
+ * leaked credentials, script injection, shell injection, data URIs,
+ * null bytes, prototype pollution keys, hex blobs, or oversized strings.
+ *
+ * @param data   - Parsed JSON payload to scan.
+ * @param source - Human-readable label for error messages (e.g. "litellm", "OpenAI API").
+ * @throws {Error} with the threat name and offending path.
+ */
+export function assertCleanPayload(data, source) {
+    const hit = scanPayload(data);
+    if (hit) {
+        throw new Error(`Rejected ${source} data: ${hit.threat} detected at "${hit.path}" — refusing to load potentially compromised payload`);
+    }
+}
+//# sourceMappingURL=security.js.map

package/dist/security.js.map

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

package/dist/server.d.ts

@@ -0,0 +1,41 @@
+/**
+ * kosha-discovery — HTTP API server (Hono-based).
+ *
+ * Exposes the model registry over a lightweight REST API so that
+ * editor extensions, scripts, and other tools can query discovered
+ * models without importing the library directly.
+ *
+ * Routes:
+ *   GET  /api/models                     — List models (query: ?provider, ?originProvider, ?mode, ?capability)
+ *   GET  /api/models/cheapest            — Cheapest eligible models for a role/capability
+ *   GET  /api/models/:idOrAlias/routes   — All provider routes with preferred/direct metadata
+ *   GET  /api/models/:idOrAlias          — Get a single model by ID or alias (+ baseUrl/version)
+ *   GET  /api/roles                      — Provider->model->roles matrix
+ *   GET  /api/providers                  — List all providers (summary)
+ *   GET  /api/providers/:id              — Get a single provider with its models
+ *   POST /api/refresh                    — Trigger re-discovery (body: { provider?: string })
+ *   GET  /api/resolve/:alias             — Resolve an alias to its canonical model ID
+ *   GET  /api/discovery-errors            — Errors from last discovery pass
+ *   GET  /health                         — Health check
+ * @module
+ */
+import { Hono } from "hono";
+import { ModelRegistry } from "./registry.js";
+/**
+ * Create a Hono application wired to the given {@link ModelRegistry}.
+ *
+ * The returned app is not yet listening — call `serve()` or mount it
+ * inside another Hono app to start accepting requests.
+ *
+ * @param registry - A pre-populated (or lazy) ModelRegistry instance.
+ * @returns A configured Hono app with all kosha REST routes.
+ */
+export declare function createServer(registry: ModelRegistry): Hono;
+/**
+ * Boot a standalone kosha API server.
+ *
+ * Runs full discovery, then starts an HTTP listener on the given port.
+ * @param port - TCP port to bind (default `3000`, overridable via `PORT` env var).
+ */
+export declare function startServer(port?: number): Promise<void>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAI5B,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAiC9C;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAwP1D;AAMD;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,IAAI,SAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAyB5D"}