@velum-labs/routekit-gateway 0.11.0 → 0.13.0

package/dist/auth.d.ts

@@ -1,10 +1,32 @@
 import type { IncomingMessage } from "node:http";
+/** Trusted principal header injected by the switching proxy after auth. */
+export declare const ROUTEKIT_PRINCIPAL_HEADER = "x-routekit-principal";
+export type GatewayPrincipal = {
+    id: string;
+    label: string;
+    role: "owner" | "admin";
+};
 /** 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;
+/**
+ * Extract the presented credential from either `Authorization: Bearer` or
+ * `x-api-key`. Returns undefined when neither is present.
+ */
+export declare function presentedCredential(req: IncomingMessage): string | undefined;
 /**
  * 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;
+/**
+ * Resolve a principal from the request using a token registry. Falls back to
+ * a single shared token (legacy) when `legacyToken` matches.
+ */
+export declare function resolvePrincipal(req: IncomingMessage, input: {
+    resolve?: (presented: string) => GatewayPrincipal | undefined;
+    legacyToken?: string;
+}): GatewayPrincipal | undefined;
+/** Parse a trusted principal header value injected by the switching proxy. */
+export declare function parsePrincipalHeader(value: string | undefined): GatewayPrincipal | undefined;

package/dist/auth.js

@@ -4,6 +4,8 @@
  * neither content nor length differences are observable through timing.
  */
 import { createHash, timingSafeEqual } from "node:crypto";
+/** Trusted principal header injected by the switching proxy after auth. */
+export const ROUTEKIT_PRINCIPAL_HEADER = "x-routekit-principal";
 /** Constant-time string equality (length-independent; no timing leaks). */
 export function timingSafeStringEqual(a, b) {
     const aDigest = createHash("sha256").update(a, "utf8").digest();
@@ -16,6 +18,21 @@ export function timingSafeStringEqual(a, b) {
 export function verifyBearerToken(header, expected) {
     return typeof header === "string" && timingSafeStringEqual(header, `Bearer ${expected}`);
 }
+/**
+ * Extract the presented credential from either `Authorization: Bearer` or
+ * `x-api-key`. Returns undefined when neither is present.
+ */
+export function presentedCredential(req) {
+    const authorization = req.headers.authorization;
+    if (typeof authorization === "string" && authorization.startsWith("Bearer ")) {
+        const token = authorization.slice("Bearer ".length);
+        return token.length > 0 ? token : undefined;
+    }
+    const apiKey = req.headers["x-api-key"];
+    if (typeof apiKey === "string" && apiKey.length > 0)
+        return apiKey;
+    return undefined;
+}
 /**
  * The gateway's request-authorization rule: a matching bearer token or a
  * matching `x-api-key` header.
@@ -26,3 +43,38 @@ export function authorizedRequest(req, token) {
     const apiKey = req.headers["x-api-key"];
     return typeof apiKey === "string" && timingSafeStringEqual(apiKey, token);
 }
+/**
+ * Resolve a principal from the request using a token registry. Falls back to
+ * a single shared token (legacy) when `legacyToken` matches.
+ */
+export function resolvePrincipal(req, input) {
+    const presented = presentedCredential(req);
+    if (presented === undefined)
+        return undefined;
+    if (input.resolve !== undefined) {
+        const principal = input.resolve(presented);
+        if (principal !== undefined)
+            return principal;
+    }
+    if (input.legacyToken !== undefined && timingSafeStringEqual(presented, input.legacyToken)) {
+        return { id: "default", label: "default", role: "owner" };
+    }
+    return undefined;
+}
+/** Parse a trusted principal header value injected by the switching proxy. */
+export function parsePrincipalHeader(value) {
+    if (value === undefined || value.length === 0)
+        return undefined;
+    try {
+        const parsed = JSON.parse(value);
+        if (typeof parsed.id !== "string" ||
+            typeof parsed.label !== "string" ||
+            (parsed.role !== "owner" && parsed.role !== "admin")) {
+            return undefined;
+        }
+        return { id: parsed.id, label: parsed.label, role: parsed.role };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/index.d.ts

@@ -35,7 +35,8 @@ export { DEFAULT_MODEL_PRICING, estimateCost, formatUsd, lookupPricing, meterCal
 export type { CallCostRecord, ModelPricing, ProviderCostMetadata, TokenUsage } from "./cost.js";
 export { buildModelCallRecord, MODEL_CALL_ID_HEADER, modelCallId, readProducerVersion, resolveProducerGitSha, responseBodyHash, UNKNOWN_GIT_SHA } from "./provenance.js";
 export type { GatewayDialect, ModelCallRecord, ModelGatewayCallContext, ModelGatewayCallResult, ProvenanceSink } from "./provenance.js";
-export { authorizedRequest } from "./auth.js";
+export { authorizedRequest, parsePrincipalHeader, presentedCredential, resolvePrincipal, ROUTEKIT_PRINCIPAL_HEADER } from "./auth.js";
+export type { GatewayPrincipal } from "./auth.js";
 export { errorEvent, finishChunk, noticeChunk, reasoningChunk, sseResponse } from "./sse-wire.js";
 export { ChatStreamAssembler } from "./sse/chat-assembler.js";
 export type { AssembledToolCall } from "./sse/chat-assembler.js";

package/dist/index.js

@@ -18,7 +18,7 @@ export { ACP_PROTOCOL_VERSION, runAcpAgent } from "./acp-agent.js";
 export { ACP_REGISTRY_URL, fetchAcpRegistry, installAcpAdapters } from "./acp-registry.js";
 export { DEFAULT_MODEL_PRICING, estimateCost, formatUsd, lookupPricing, meterCall, parseUsage, parseUsageFromSse } from "./cost.js";
 export { buildModelCallRecord, MODEL_CALL_ID_HEADER, modelCallId, readProducerVersion, resolveProducerGitSha, responseBodyHash, UNKNOWN_GIT_SHA } from "./provenance.js";
-export { authorizedRequest } from "./auth.js";
+export { authorizedRequest, parsePrincipalHeader, presentedCredential, resolvePrincipal, ROUTEKIT_PRINCIPAL_HEADER } from "./auth.js";
 export { errorEvent, finishChunk, noticeChunk, reasoningChunk, sseResponse } from "./sse-wire.js";
 export { ChatStreamAssembler } from "./sse/chat-assembler.js";
 export { decodeBufferedSse, SseDecoder, SseParseError } from "./sse/parse.js";

package/dist/provenance.js

@@ -153,6 +153,16 @@ export function buildModelCallRecord(context, result) {
                     ...(context.attribution.account !== undefined
                         ? { account: { seat: context.attribution.account.seat } }
                         : {}),
+                    ...(context.attribution.principal !== undefined
+                        ? {
+                            principal: {
+                                token_id: context.attribution.principal.token_id,
+                                ...(context.attribution.principal.label !== undefined
+                                    ? { label: context.attribution.principal.label }
+                                    : {})
+                            }
+                        }
+                        : {}),
                     attempts: context.attribution.attempts,
                     retries: context.attribution.retries,
                     account_failovers: context.attribution.account_failovers

package/dist/server.js

@@ -3,7 +3,7 @@ import { createServer } from "node:http";
 import { ProviderFailureError } from "@velum-labs/routekit-contracts";
 import { anthropicModelsResponse, handleAnthropicMessages, handleCountTokens, resolveClaudeModelAlias } from "./adapters/anthropic.js";
 import { effectiveModel, isStream, withDefaultModel } from "./adapters/chat.js";
-import { authorizedRequest } from "./auth.js";
+import { authorizedRequest, parsePrincipalHeader, ROUTEKIT_PRINCIPAL_HEADER } from "./auth.js";
 import { cursorModelVariants, isCursorChatBody, resolveCursorModelSelection, translateCursorRequest } from "./adapters/cursor.js";
 import { withReasoningSelection } from "./adapters/openai-chat-wire.js";
 import { handleResponses } from "./adapters/responses.js";
@@ -331,6 +331,16 @@ export async function startGateway(options) {
             return;
         }
         const requestContext = { headers: req.headers };
+        const headerPrincipal = parsePrincipalHeader(typeof req.headers[ROUTEKIT_PRINCIPAL_HEADER] === "string"
+            ? req.headers[ROUTEKIT_PRINCIPAL_HEADER]
+            : undefined);
+        const requestPrincipal = headerPrincipal === undefined
+            ? undefined
+            : { token_id: headerPrincipal.id, label: headerPrincipal.label };
+        const dispatchModelCall = (route) => handleModelCall(res, provenance, {
+            ...route,
+            ...(requestPrincipal !== undefined ? { principal: requestPrincipal } : {})
+        });
         if (method === "POST" && (path === "/v1/chat/completions" || path === "/chat/completions")) {
             const raw = await readJson(req, res);
             if (raw === NO_BODY)
@@ -338,7 +348,7 @@ export async function startGateway(options) {
             if (rejectInvalid(res, validateChatRequest(raw)))
                 return;
             const body = withDefaultModel(raw, backend.defaultModel);
-            await handleModelCall(res, provenance, {
+            await dispatchModelCall({
                 dialect: "openai-chat",
                 body,
                 defaultModel: backend.defaultModel,
@@ -394,7 +404,7 @@ export async function startGateway(options) {
             if (rejectInvalid(res, validateChatRequest(translated)))
                 return;
             const body = withDefaultModel(translated, backend.defaultModel);
-            await handleModelCall(res, provenance, {
+            await dispatchModelCall({
                 dialect: "openai-chat",
                 body,
                 defaultModel: backend.defaultModel,
@@ -412,7 +422,7 @@ export async function startGateway(options) {
             if (raw === NO_BODY)
                 return;
             const body = withDefaultModel(raw, backend.defaultModel);
-            await handleModelCall(res, provenance, {
+            await dispatchModelCall({
                 dialect: "openai-embeddings",
                 body,
                 defaultModel: backend.defaultModel,
@@ -478,7 +488,7 @@ export async function startGateway(options) {
             if (anthropicRelay !== undefined &&
                 route?.provider === "claude-code") {
                 const relayBody = withModel(rawBody, route.nativeId);
-                await handleModelCall(res, provenance, {
+                await dispatchModelCall({
                     dialect: "anthropic-messages",
                     body,
                     defaultModel: backend.defaultModel,
@@ -497,7 +507,7 @@ export async function startGateway(options) {
             if (anthropicRelay !== undefined &&
                 backend.resolveModelRoute === undefined &&
                 anthropicRelay.shouldRelay(req.headers, requestedModel, (model) => backend.servesModel?.(model) ?? false)) {
-                await handleModelCall(res, provenance, {
+                await dispatchModelCall({
                     dialect: "anthropic-messages",
                     body,
                     defaultModel: backend.defaultModel,
@@ -515,7 +525,7 @@ export async function startGateway(options) {
                 });
                 return;
             }
-            await handleModelCall(res, provenance, {
+            await dispatchModelCall({
                 dialect: "anthropic-messages",
                 body,
                 defaultModel: backend.defaultModel,
@@ -548,7 +558,7 @@ export async function startGateway(options) {
                         : resolveNativeModelRoute(backend, "codex", requestedModel);
             }
             catch (error) {
-                await handleModelCall(res, provenance, {
+                await dispatchModelCall({
                     dialect: "openai-responses",
                     body,
                     defaultModel: backend.defaultModel,
@@ -566,7 +576,7 @@ export async function startGateway(options) {
             if (codexProviderRelay !== undefined &&
                 route?.provider === "codex") {
                 const relayBody = withModel(body, route.nativeId);
-                await handleModelCall(res, provenance, {
+                await dispatchModelCall({
                     dialect: "openai-responses",
                     body: canonicalBody,
                     defaultModel: backend.defaultModel,
@@ -587,7 +597,7 @@ export async function startGateway(options) {
                 (codexProviderRelay === undefined ||
                     backend.resolveModelRoute === undefined) &&
                 codexRequestRelay.shouldRelay(req.headers, requestedModel, (model) => backend.servesModel?.(model) ?? false)) {
-                await handleModelCall(res, provenance, {
+                await dispatchModelCall({
                     dialect: "openai-responses",
                     body,
                     defaultModel: backend.defaultModel,
@@ -605,7 +615,7 @@ export async function startGateway(options) {
                 });
                 return;
             }
-            await handleModelCall(res, provenance, {
+            await dispatchModelCall({
                 dialect: "openai-responses",
                 body: canonicalBody,
                 defaultModel: backend.defaultModel,
@@ -836,6 +846,7 @@ export function collectAttribution(seed) {
                 provider: current.provider,
                 billing_mode: current.billing_mode,
                 ...(current.account !== undefined ? { account: current.account } : {}),
+                ...(current.principal !== undefined ? { principal: current.principal } : {}),
                 attempts: Math.max(1, attempts),
                 retries,
                 account_failovers: accountFailovers
@@ -845,7 +856,10 @@ export function collectAttribution(seed) {
 }
 async function handleModelCall(res, sink, route) {
     const callId = modelCallId();
-    const attribution = collectAttribution(route.attribution);
+    const attribution = collectAttribution({
+        ...route.attribution,
+        ...(route.principal !== undefined ? { principal: route.principal } : {})
+    });
     const started = Date.now();
     const startedAt = new Date(started).toISOString();
     const context = {

package/dist/switching-proxy.d.ts

@@ -1,3 +1,4 @@
+import { type GatewayPrincipal } from "./auth.js";
 export type SwitchingGatewayProxy = {
     url(): string;
     port(): number;
@@ -12,4 +13,6 @@ export declare function startSwitchingGatewayProxy(input: {
     host?: string;
     port?: number;
     authToken?: string;
+    /** Resolve a named data-plane principal; preferred over `authToken` alone. */
+    resolveDataPrincipal?: (presented: string) => GatewayPrincipal | undefined;
 }): Promise<SwitchingGatewayProxy>;

package/dist/switching-proxy.js

@@ -9,7 +9,7 @@
  */
 import { createServer } from "node:http";
 import { assertAuthenticatedBind, trimTrailingSlashes } from "@velum-labs/routekit-runtime";
-import { authorizedRequest } from "./auth.js";
+import { ROUTEKIT_PRINCIPAL_HEADER, authorizedRequest, resolvePrincipal } from "./auth.js";
 const MAX_BODY_BYTES = 16 * 1024 * 1024;
 const HOP_BY_HOP = new Set([
     "connection",
@@ -21,11 +21,18 @@ const HOP_BY_HOP = new Set([
     "transfer-encoding",
     "upgrade"
 ]);
-function requestHeaders(headers) {
+function requestHeaders(headers, principal) {
     const result = new Headers();
     for (const [name, value] of Object.entries(headers)) {
-        if (value === undefined || HOP_BY_HOP.has(name.toLowerCase()) || name === "host")
+        const lower = name.toLowerCase();
+        if (value === undefined ||
+            HOP_BY_HOP.has(lower) ||
+            lower === "host" ||
+            // Never forward a client-supplied principal; the proxy is the only
+            // trusted source of identity for the inner gateway.
+            lower === ROUTEKIT_PRINCIPAL_HEADER) {
             continue;
+        }
         if (Array.isArray(value)) {
             for (const entry of value)
                 result.append(name, entry);
@@ -34,6 +41,9 @@ function requestHeaders(headers) {
             result.set(name, value);
         }
     }
+    if (principal !== undefined) {
+        result.set(ROUTEKIT_PRINCIPAL_HEADER, JSON.stringify(principal));
+    }
     return result;
 }
 async function requestBody(req) {
@@ -92,6 +102,7 @@ async function pipe(res, upstream) {
 export async function startSwitchingGatewayProxy(input) {
     const host = input.host ?? "127.0.0.1";
     assertAuthenticatedBind(host, input.authToken);
+    const authEnabled = input.resolveDataPrincipal !== undefined || input.authToken !== undefined;
     let active = {
         url: trimTrailingSlashes(input.target),
         leases: 0,
@@ -119,11 +130,28 @@ export async function startSwitchingGatewayProxy(input) {
                 });
                 return;
             }
-            if (input.authToken !== undefined && !authorizedRequest(req, input.authToken)) {
-                writeJson(res, 401, {
-                    error: { message: "unauthorized", type: "auth_error" }
+            let principal;
+            if (authEnabled) {
+                principal = resolvePrincipal(req, {
+                    ...(input.resolveDataPrincipal !== undefined
+                        ? { resolve: input.resolveDataPrincipal }
+                        : {}),
+                    ...(input.authToken !== undefined ? { legacyToken: input.authToken } : {})
                 });
-                return;
+                if (principal === undefined) {
+                    // Preserve the single-token path for callers that only pass authToken.
+                    if (input.resolveDataPrincipal === undefined &&
+                        input.authToken !== undefined &&
+                        authorizedRequest(req, input.authToken)) {
+                        principal = { id: "default", label: "default", role: "owner" };
+                    }
+                    else {
+                        writeJson(res, 401, {
+                            error: { message: "unauthorized", type: "auth_error" }
+                        });
+                        return;
+                    }
+                }
             }
             const selected = active;
             selected.leases += 1;
@@ -137,7 +165,7 @@ export async function startSwitchingGatewayProxy(input) {
                 const body = await requestBody(req);
                 const upstream = await fetch(`${selected.url}${path}`, {
                     method: req.method ?? "GET",
-                    headers: requestHeaders(req.headers),
+                    headers: requestHeaders(req.headers, principal),
                     ...(body !== undefined ? { body } : {}),
                     signal: AbortSignal.any([
                         aborter.signal,

package/dist/test/auth.test.js

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import { authorizedRequest, timingSafeStringEqual, verifyBearerToken } from "../auth.js";
+import { authorizedRequest, parsePrincipalHeader, resolvePrincipal, timingSafeStringEqual, verifyBearerToken } from "../auth.js";
 function requestWithHeaders(headers) {
     return { headers };
 }
@@ -23,3 +23,23 @@ test("authorizedRequest accepts bearer header or x-api-key, rejects otherwise",
     assert.equal(authorizedRequest(requestWithHeaders({ "x-api-key": "nope" }), "tok"), false);
     assert.equal(authorizedRequest(requestWithHeaders({}), "tok"), false);
 });
+test("resolvePrincipal uses the registry and falls back to a legacy token", () => {
+    const principal = resolvePrincipal(requestWithHeaders({ authorization: "Bearer named" }), {
+        resolve: (presented) => presented === "named" ? { id: "abc", label: "bob", role: "admin" } : undefined
+    });
+    assert.deepEqual(principal, { id: "abc", label: "bob", role: "admin" });
+    assert.deepEqual(resolvePrincipal(requestWithHeaders({ "x-api-key": "legacy" }), { legacyToken: "legacy" }), { id: "default", label: "default", role: "owner" });
+    assert.equal(resolvePrincipal(requestWithHeaders({ authorization: "Bearer nope" }), {
+        resolve: () => undefined,
+        legacyToken: "legacy"
+    }), undefined);
+});
+test("parsePrincipalHeader accepts only well-formed JSON principals", () => {
+    assert.deepEqual(parsePrincipalHeader('{"id":"a","label":"bob","role":"admin"}'), {
+        id: "a",
+        label: "bob",
+        role: "admin"
+    });
+    assert.equal(parsePrincipalHeader('{"id":"a","label":"bob","role":"root"}'), undefined);
+    assert.equal(parsePrincipalHeader("not-json"), undefined);
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@velum-labs/routekit-gateway",
   "private": false,
-  "version": "0.11.0",
+  "version": "0.13.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/velum-labs/routekit.git",
@@ -27,10 +27,10 @@
   },
   "dependencies": {
     "zod": "4.4.3",
-    "@velum-labs/routekit-contracts": "0.11.0",
-    "@velum-labs/routekit-registry": "0.11.0",
-    "@velum-labs/routekit-tracing": "0.11.0",
-    "@velum-labs/routekit-runtime": "0.11.0"
+    "@velum-labs/routekit-contracts": "0.13.0",
+    "@velum-labs/routekit-registry": "0.13.0",
+    "@velum-labs/routekit-runtime": "0.13.0",
+    "@velum-labs/routekit-tracing": "0.13.0"
   },
   "keywords": [
     "routekit",