@velum-labs/routekit-gateway 0.9.0

package/dist/adapters/validate.js

@@ -0,0 +1,180 @@
+/**
+ * Structural request validation at the gateway's wire doors.
+ *
+ * Hostile-input fuzzing showed that malformed bodies (a `model` array, a
+ * `messages` string, an empty body) sailed past the doors, hit deep code, and
+ * surfaced as 502 `upstream_error`s carrying raw TypeError text
+ * ("requested.startsWith is not a function", "body.messages is not iterable")
+ * or internal implementation details. A caller error must be a 400 in the
+ * door's native error envelope, and it must never reach a provider.
+ *
+ * Validation here is *structural only* — field presence and JSON types
+ * matching what the real providers enforce. Semantic rules (role enums,
+ * schema shapes) stay with the providers, so the doors never reject a shape a
+ * real provider would accept.
+ */
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function openAiError(message) {
+    return {
+        status: 400,
+        body: { error: { message, type: "invalid_request_error", code: "invalid_request" } }
+    };
+}
+function anthropicError(message) {
+    return {
+        status: 400,
+        body: { type: "error", error: { type: "invalid_request_error", message } }
+    };
+}
+/** Validate the common message-array shape without imposing a dialect's role enum. */
+function checkMessages(body, shape, options = {}) {
+    const messages = body.messages;
+    if (!Array.isArray(messages)) {
+        return shape("`messages` is required and must be an array of message objects");
+    }
+    if (messages.length === 0 && options.allowEmpty !== true) {
+        return shape("`messages` must contain at least one message");
+    }
+    for (const message of messages) {
+        if (!isObject(message) || typeof message.role !== "string") {
+            return shape("every message must be an object with a string `role`");
+        }
+        if (message.role === "tool" &&
+            (typeof message.tool_call_id !== "string" || message.tool_call_id.length === 0)) {
+            return shape("tool messages require a non-empty `tool_call_id`");
+        }
+        const content = message.content;
+        if (content === null && options.allowNullContent === false) {
+            return shape("message `content` must not be null");
+        }
+        if (content !== undefined && content !== null && typeof content !== "string" && !Array.isArray(content)) {
+            return shape("message `content` must be a string, an array of content parts, or null");
+        }
+        if (Array.isArray(content) && content.some((part) => !isObject(part))) {
+            return shape("every message content part must be an object");
+        }
+        const toolCalls = message.tool_calls;
+        if (toolCalls !== undefined && toolCalls !== null) {
+            if (!Array.isArray(toolCalls)) {
+                return shape("message `tool_calls` must be an array");
+            }
+            if (message.role !== "assistant") {
+                return shape("message `tool_calls` are only valid on assistant messages");
+            }
+            for (const call of toolCalls) {
+                if (!isObject(call))
+                    return shape("every tool call must be an object");
+                const functionCall = isObject(call.function) ? call.function : call;
+                if (typeof functionCall.name !== "string" || functionCall.name.length === 0) {
+                    return shape("every tool call requires a function name");
+                }
+                if (typeof functionCall.arguments !== "string") {
+                    return shape("tool-call `arguments` must be a JSON string");
+                }
+                try {
+                    const parsed = JSON.parse(functionCall.arguments);
+                    if (!isObject(parsed)) {
+                        return shape("tool-call `arguments` must encode a JSON object");
+                    }
+                }
+                catch {
+                    return shape("tool-call `arguments` must be valid JSON");
+                }
+            }
+        }
+    }
+    return undefined;
+}
+function checkModel(body, shape) {
+    if (body.model !== undefined && typeof body.model !== "string") {
+        return shape("`model` must be a string");
+    }
+    return undefined;
+}
+function checkStream(body, shape) {
+    if (body.stream !== undefined && body.stream !== null && typeof body.stream !== "boolean") {
+        return shape("`stream` must be a boolean");
+    }
+    return undefined;
+}
+function checkPositiveInteger(body, field, shape) {
+    const value = body[field];
+    if (value !== undefined &&
+        value !== null &&
+        (typeof value !== "number" || !Number.isInteger(value) || value < 1)) {
+        return shape(`\`${field}\` must be a positive integer`);
+    }
+    return undefined;
+}
+function checkTools(body, shape) {
+    const tools = body.tools;
+    if (tools === undefined || tools === null)
+        return undefined;
+    if (!Array.isArray(tools)) {
+        return shape("`tools` must be an array of tool definitions");
+    }
+    if (tools.some((tool) => !isObject(tool))) {
+        return shape("every tool definition must be an object");
+    }
+    return undefined;
+}
+/** OpenAI Chat Completions door (`/v1/chat/completions`). */
+export function validateChatRequest(body) {
+    if (!isObject(body))
+        return openAiError("request body must be a JSON object");
+    return (checkModel(body, openAiError) ??
+        checkStream(body, openAiError) ??
+        checkPositiveInteger(body, "max_tokens", openAiError) ??
+        checkPositiveInteger(body, "max_completion_tokens", openAiError) ??
+        checkMessages(body, openAiError) ??
+        checkTools(body, openAiError));
+}
+/** Anthropic Messages door (`/v1/messages`). */
+export function validateAnthropicRequest(body) {
+    if (!isObject(body))
+        return anthropicError("request body must be a JSON object");
+    const system = body.system;
+    return (checkModel(body, anthropicError) ??
+        checkStream(body, anthropicError) ??
+        checkPositiveInteger(body, "max_tokens", anthropicError) ??
+        checkMessages(body, anthropicError, { allowNullContent: false }) ??
+        checkTools(body, anthropicError) ??
+        (system !== undefined && system !== null && typeof system !== "string" && !Array.isArray(system)
+            ? anthropicError("`system` must be a string or an array of text blocks")
+            : undefined));
+}
+/** Anthropic `count_tokens` door: same message-shape contract, no minimum length. */
+export function validateCountTokensRequest(body) {
+    if (!isObject(body))
+        return anthropicError("request body must be a JSON object");
+    return checkMessages(body, anthropicError, {
+        allowEmpty: true,
+        allowNullContent: false
+    });
+}
+/** OpenAI Responses door (`/v1/responses`). */
+export function validateResponsesRequest(body) {
+    if (!isObject(body))
+        return openAiError("request body must be a JSON object");
+    const model = checkModel(body, openAiError) ??
+        checkStream(body, openAiError) ??
+        checkPositiveInteger(body, "max_output_tokens", openAiError) ??
+        checkTools(body, openAiError);
+    if (model !== undefined)
+        return model;
+    const input = body.input;
+    if (typeof input === "string")
+        return undefined;
+    if (Array.isArray(input)) {
+        if (input.length === 0)
+            return openAiError("`input` must not be an empty array");
+        for (const item of input) {
+            if (!isObject(item))
+                return openAiError("every `input` item must be an object");
+        }
+        return undefined;
+    }
+    return openAiError("`input` is required and must be a string or an array of input items");
+}

package/dist/adapters/web-search.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Gateway-side web search execution (server-tool parity).
+ *
+ * `web_search` is a *server-executed* tool: callers (Codex, Claude Code, API
+ * clients) declare it but never run it — on the real provider APIs the
+ * backend searches mid-turn. Nothing behind this gateway can do that, so the
+ * gateway becomes the server: the dialect adapters project the tool to the
+ * upstream model, and when it calls the tool the server-tool loop executes the
+ * search here by delegating to a real provider's native web search in a
+ * one-shot, buffered side call.
+ *
+ * Each dialect prefers its own provider (result and citation shapes match
+ * what the caller's provider would have produced), falling back to the other
+ * provider when only one key is available. With no key at all the feature is
+ * off and the adapters keep their honest-drop behavior.
+ */
+export type WebSearchCitation = {
+    url: string;
+    title?: string;
+};
+export type WebSearchOutcome = {
+    /** The answer/result text the upstream model reads. */
+    text: string;
+    citations: WebSearchCitation[];
+    /**
+     * Anthropic-native `web_search_result` blocks, verbatim, when the Anthropic
+     * executor served the search — the Anthropic egress passes them through for
+     * exact result-block parity. Absent for other executors.
+     */
+    anthropicResultBlocks?: unknown[];
+};
+export type WebSearchExecutor = {
+    readonly provider: "openai" | "anthropic";
+    readonly model: string;
+    search(query: string, signal?: AbortSignal): Promise<WebSearchOutcome>;
+};
+export type WebSearchDialect = "responses" | "anthropic";
+/** Hard ceiling on gateway-executed searches within one caller turn. */
+export declare const MAX_WEB_SEARCHES_PER_TURN = 8;
+/**
+ * The executor for a dialect: the matching provider when its key is present,
+ * the other provider as fallback (working search beats provider purity), or
+ * `undefined` when the feature is off (`ROUTEKIT_WEB_SEARCH=0` or no keys),
+ * in which case the adapters keep dropping the tool with a warning.
+ */
+export declare function resolveWebSearchExecutor(dialect: WebSearchDialect, env?: Record<string, string | undefined>): WebSearchExecutor | undefined;

package/dist/adapters/web-search.js

@@ -0,0 +1,151 @@
+/**
+ * Gateway-side web search execution (server-tool parity).
+ *
+ * `web_search` is a *server-executed* tool: callers (Codex, Claude Code, API
+ * clients) declare it but never run it — on the real provider APIs the
+ * backend searches mid-turn. Nothing behind this gateway can do that, so the
+ * gateway becomes the server: the dialect adapters project the tool to the
+ * upstream model, and when it calls the tool the server-tool loop executes the
+ * search here by delegating to a real provider's native web search in a
+ * one-shot, buffered side call.
+ *
+ * Each dialect prefers its own provider (result and citation shapes match
+ * what the caller's provider would have produced), falling back to the other
+ * provider when only one key is available. With no key at all the feature is
+ * off and the adapters keep their honest-drop behavior.
+ */
+import { withDeadline } from "@velum-labs/routekit-runtime";
+/** Hard ceiling on gateway-executed searches within one caller turn. */
+export const MAX_WEB_SEARCHES_PER_TURN = 8;
+/** Per-search wall clock before the delegated call is aborted. */
+const SEARCH_TIMEOUT_MS = 90_000;
+const OPENAI_DEFAULT_MODEL = "gpt-5.5";
+const ANTHROPIC_DEFAULT_MODEL = "claude-haiku-4-5";
+const SEARCH_PROMPT_PREFIX = "Search the web and report what you find, including source URLs. " +
+    "Be factual and concise; do not editorialize. Query:\n\n";
+function searchError(provider, status, detail) {
+    return new Error(`web search via ${provider} failed (${status}): ${detail.slice(0, 500)}`);
+}
+function openAiExecutor(apiKey, env) {
+    const model = env.ROUTEKIT_WEB_SEARCH_OPENAI_MODEL ?? OPENAI_DEFAULT_MODEL;
+    const baseUrl = env.ROUTEKIT_WEB_SEARCH_OPENAI_URL ?? "https://api.openai.com/v1";
+    return {
+        provider: "openai",
+        model,
+        async search(query, signal) {
+            const response = await fetch(`${baseUrl}/responses`, {
+                method: "POST",
+                headers: { authorization: `Bearer ${apiKey}`, "content-type": "application/json" },
+                body: JSON.stringify({
+                    model,
+                    reasoning: { effort: "low" },
+                    tools: [{ type: "web_search" }],
+                    tool_choice: "auto",
+                    input: `${SEARCH_PROMPT_PREFIX}${query}`
+                }),
+                signal: withDeadline(signal, SEARCH_TIMEOUT_MS)
+            });
+            if (!response.ok)
+                throw searchError("openai", response.status, await response.text());
+            const payload = (await response.json());
+            const texts = [];
+            const citations = [];
+            for (const item of payload.output ?? []) {
+                if (item.type !== "message")
+                    continue;
+                for (const part of item.content ?? []) {
+                    if (typeof part.text === "string" && part.text.length > 0)
+                        texts.push(part.text);
+                    // Citation annotations are best-effort: validated live runs sometimes
+                    // return an answer with an empty annotations array.
+                    for (const annotation of part.annotations ?? []) {
+                        if (annotation.type === "url_citation" && typeof annotation.url === "string") {
+                            citations.push({
+                                url: annotation.url,
+                                ...(typeof annotation.title === "string" ? { title: annotation.title } : {})
+                            });
+                        }
+                    }
+                }
+            }
+            return { text: texts.join("\n"), citations };
+        }
+    };
+}
+function anthropicExecutor(apiKey, env) {
+    const model = env.ROUTEKIT_WEB_SEARCH_ANTHROPIC_MODEL ?? ANTHROPIC_DEFAULT_MODEL;
+    const baseUrl = env.ROUTEKIT_WEB_SEARCH_ANTHROPIC_URL ?? "https://api.anthropic.com/v1";
+    return {
+        provider: "anthropic",
+        model,
+        async search(query, signal) {
+            const response = await fetch(`${baseUrl}/messages`, {
+                method: "POST",
+                headers: {
+                    "x-api-key": apiKey,
+                    "anthropic-version": "2023-06-01",
+                    "content-type": "application/json"
+                },
+                body: JSON.stringify({
+                    model,
+                    max_tokens: 2048,
+                    tools: [{ type: "web_search_20250305", name: "web_search", max_uses: 3 }],
+                    messages: [{ role: "user", content: `${SEARCH_PROMPT_PREFIX}${query}` }]
+                }),
+                signal: withDeadline(signal, SEARCH_TIMEOUT_MS)
+            });
+            if (!response.ok)
+                throw searchError("anthropic", response.status, await response.text());
+            const payload = (await response.json());
+            const texts = [];
+            const citations = [];
+            const resultBlocks = [];
+            for (const block of payload.content ?? []) {
+                if (block.type === "text" && typeof block.text === "string" && block.text.length > 0) {
+                    texts.push(block.text);
+                }
+                if (block.type === "web_search_tool_result" && Array.isArray(block.content)) {
+                    resultBlocks.push(...block.content);
+                    for (const result of block.content) {
+                        if (result.type === "web_search_result" && typeof result.url === "string") {
+                            citations.push({
+                                url: result.url,
+                                ...(typeof result.title === "string" ? { title: result.title } : {})
+                            });
+                        }
+                    }
+                }
+            }
+            return {
+                text: texts.join("\n"),
+                citations,
+                ...(resultBlocks.length > 0 ? { anthropicResultBlocks: resultBlocks } : {})
+            };
+        }
+    };
+}
+// ---- selection ----
+/**
+ * The executor for a dialect: the matching provider when its key is present,
+ * the other provider as fallback (working search beats provider purity), or
+ * `undefined` when the feature is off (`ROUTEKIT_WEB_SEARCH=0` or no keys),
+ * in which case the adapters keep dropping the tool with a warning.
+ */
+export function resolveWebSearchExecutor(dialect, env = process.env) {
+    if (env.ROUTEKIT_WEB_SEARCH === "0")
+        return undefined;
+    const openAiKey = env.OPENAI_API_KEY;
+    const anthropicKey = env.ANTHROPIC_API_KEY;
+    const openAi = openAiKey !== undefined && openAiKey.length > 0 ? openAiExecutor(openAiKey, env) : undefined;
+    const anthropic = anthropicKey !== undefined && anthropicKey.length > 0 ? anthropicExecutor(anthropicKey, env) : undefined;
+    switch (dialect) {
+        case "responses":
+            return openAi ?? anthropic;
+        case "anthropic":
+            return anthropic ?? openAi;
+        default: {
+            const exhaustive = dialect;
+            throw new Error(`unknown web search dialect: ${String(exhaustive)}`);
+        }
+    }
+}

package/dist/auth.d.ts

@@ -0,0 +1,10 @@
+import type { IncomingMessage } from "node:http";
+/** Constant-time string equality (length-independent; no timing leaks). */
+export declare function timingSafeStringEqual(a: string, b: string): boolean;
+/** Verify an `Authorization: Bearer <token>` header value. */
+export declare function verifyBearerToken(header: string | undefined, expected: string): boolean;
+/**
+ * The gateway's request-authorization rule: a matching bearer token or a
+ * matching `x-api-key` header.
+ */
+export declare function authorizedRequest(req: IncomingMessage, token: string): boolean;

package/dist/auth.js

@@ -0,0 +1,28 @@
+/**
+ * Shared bearer-token verification for the local gateway servers. One
+ * implementation, hardened once: comparisons run over fixed-length digests so
+ * neither content nor length differences are observable through timing.
+ */
+import { createHash, timingSafeEqual } from "node:crypto";
+/** Constant-time string equality (length-independent; no timing leaks). */
+export function timingSafeStringEqual(a, b) {
+    const aDigest = createHash("sha256").update(a, "utf8").digest();
+    const bDigest = createHash("sha256").update(b, "utf8").digest();
+    // The digest comparison decides; the direct check only guards the
+    // astronomically unlikely hash collision and runs on match alone.
+    return timingSafeEqual(aDigest, bDigest) && a === b;
+}
+/** Verify an `Authorization: Bearer <token>` header value. */
+export function verifyBearerToken(header, expected) {
+    return typeof header === "string" && timingSafeStringEqual(header, `Bearer ${expected}`);
+}
+/**
+ * The gateway's request-authorization rule: a matching bearer token or a
+ * matching `x-api-key` header.
+ */
+export function authorizedRequest(req, token) {
+    if (verifyBearerToken(req.headers.authorization, token))
+        return true;
+    const apiKey = req.headers["x-api-key"];
+    return typeof apiKey === "string" && timingSafeStringEqual(apiKey, token);
+}

package/dist/backend.d.ts

@@ -0,0 +1,151 @@
+/**
+ * The gateway's model backend. The default HTTP implementation speaks
+ * OpenAI-compatible Chat Completions, but provider-native implementations can
+ * adapt another wire protocol behind the same interface. The backend is a thin
+ * `fetch` wrapper that returns the upstream `Response` unchanged, so the chat
+ * surface can stream straight through and the dialect adapters can consume the
+ * same core without a second abstraction.
+ */
+import type { ModelReasoningCapabilities, RequestAttribution } from "@velum-labs/routekit-contracts";
+export type BackendModelRoute = {
+    /** Stable RouteKit catalog id (`provider/model`). */
+    publicId: string;
+    /** Model id understood by the provider's native API. */
+    nativeId: string;
+    /** Configured provider that owns the model. */
+    provider: string;
+    reasoning?: ModelReasoningCapabilities;
+};
+export type Backend = {
+    /** Model id sent to the backend when a request omits one. */
+    readonly defaultModel: string | undefined;
+    /**
+     * All model ids the backend advertises for discovery: the default model
+     * first, then any native passthrough models. When present, the gateway lists
+     * these in `/v1/models` (both OpenAI and Anthropic shapes) so they appear in
+     * the tool's picker. Absent means single-model (just `defaultModel`).
+     */
+    listModelIds?(): readonly string[];
+    /**
+     * Resolve a client-requested model id to the upstream id the backend should
+     * actually run. When absent the gateway falls back to `defaultModel` (the
+     * historical single-model behaviour). A multi-model backend returns the
+     * requested id when it recognises a native model so the gateway can route it
+     * to its provider.
+     */
+    resolveModel?(requested: string | undefined): string | undefined;
+    /**
+     * Resolve a model together with its provider/native identity. An exact
+     * public id always wins. When `nativeProvider` is supplied, a bare native id
+     * may resolve only inside that provider; this powers provider-native client
+     * aliases without making bare ids valid on RouteKit's global API surface.
+     */
+    resolveModelRoute?(requested: string | undefined, nativeProvider?: string): BackendModelRoute | undefined;
+    /**
+     * Whether the backend serves this exact model id itself. Unlike
+     * {@link resolveModel} — which folds unknown
+     * ids into the default — this distinguishes "mine" from "unknown", so the
+     * gateway can hand unknown ids to a relay (e.g. the Codex backend relay)
+     * instead of silently routing them to the default.
+     */
+    servesModel?(model: string): boolean;
+    /** Capabilities advertised for a model id. */
+    capabilities?(model: string): Readonly<Record<string, string>>;
+    /** Structured reasoning controls advertised for a model id. */
+    reasoningCapabilities?(model: string): ModelReasoningCapabilities | undefined;
+    /** POST <base>/chat/completions — supports streaming (SSE) upstream. */
+    chat(body: unknown, signal?: AbortSignal, options?: BackendRequestOptions): Promise<Response>;
+    /** GET <base>/models. */
+    models(signal?: AbortSignal): Promise<Response>;
+    /** POST <base>/embeddings. */
+    embeddings(body: unknown, signal?: AbortSignal, options?: BackendRequestOptions): Promise<Response>;
+    /** Release any owned resources (e.g. a managed model process). Optional. */
+    close?(): Promise<void> | void;
+};
+export type BackendRequestOptions = {
+    modelCallId?: string;
+    reasoningCapabilities?: ModelReasoningCapabilities;
+    /** Request-local, sanitized attribution updates from routing/backends. */
+    onAttribution?: (update: RequestAttributionUpdate) => void;
+    /** Distinguishes compound provider operations within one public request. */
+    attributionOperationId?: string;
+    /**
+     * Neutral request context captured at the HTTP boundary. Backends may
+     * interpret their own namespaced headers; the gateway does not.
+     */
+    requestContext?: {
+        headers: Readonly<Record<string, string | readonly string[] | undefined>>;
+    };
+    /**
+     * The caller will wrap the returned stream in a dialect translator
+     * (Anthropic / Responses) that emits its own keepalive.
+     */
+    translated?: boolean;
+};
+export type RequestAttributionUpdate = Partial<RequestAttribution> & {
+    accountAttempt?: {
+        operationId: string;
+        seat: string;
+    };
+};
+export type OpenAiBackendOptions = {
+    /**
+     * Base URL including the OpenAI API prefix, e.g.
+     * `http://127.0.0.1:8080/v1`. Route paths (`/chat/completions`, `/models`,
+     * `/embeddings`) are appended to this value.
+     */
+    baseUrl: string;
+    /**
+     * Bearer credential forwarded to the backend. Local servers ignore it; the
+     * default mirrors the `not-needed` placeholder the AI SDK uses for local
+     * OpenAI-compatible servers.
+     */
+    apiKey?: string;
+    /** Model id used when a request omits `model`. */
+    defaultModel?: string;
+    /**
+     * When set, every request's `model` is overwritten with this id before it is
+     * forwarded upstream, regardless of what the client sent. Used by per-candidate
+     * capture gateways that are dedicated to one routed endpoint: the driving CLI
+     * (e.g. Claude Code) picks its own model label, but the router must always
+     * receive the routed model id. Absent means the client's model passes through.
+     */
+    forceModel?: string;
+    /** Extra headers sent on every request. */
+    headers?: Record<string, string>;
+};
+/** Join a base URL (which may end in `/`) with a route path. */
+export declare function joinPath(baseUrl: string, path: string): string;
+/** An OpenAI Chat Completions backend reached over HTTP. */
+export declare class OpenAiBackend implements Backend {
+    #private;
+    readonly defaultModel: string | undefined;
+    constructor(options: OpenAiBackendOptions);
+    chat(body: unknown, signal?: AbortSignal, options?: BackendRequestOptions): Promise<Response>;
+    models(signal?: AbortSignal): Promise<Response>;
+    embeddings(body: unknown, signal?: AbortSignal, options?: BackendRequestOptions): Promise<Response>;
+}
+export type ModelRoutedBackendOptions = {
+    /** Requested model ids served by `routed` instead of the primary backend. */
+    routedModelIds: readonly string[];
+    /** Backend for the routed ids. */
+    routed: Backend;
+    /** Backend for everything else (e.g. the member's router endpoint). */
+    primary: Backend;
+};
+/**
+ * A backend that dispatches by requested model id: ids in `routedModelIds` go
+ * to the `routed` backend, everything else to `primary`. This lets selected
+ * model ids use a secondary destination.
+ */
+export declare class ModelRoutedBackend implements Backend {
+    #private;
+    readonly defaultModel: string | undefined;
+    constructor(options: ModelRoutedBackendOptions);
+    listModelIds(): readonly string[];
+    resolveModel(requested: string | undefined): string | undefined;
+    chat(body: unknown, signal?: AbortSignal, options?: BackendRequestOptions): Promise<Response>;
+    models(signal?: AbortSignal): Promise<Response>;
+    embeddings(body: unknown, signal?: AbortSignal, options?: BackendRequestOptions): Promise<Response>;
+    close(): Promise<void>;
+}