@wopr-network/platform-core 1.0.10 → 1.1.0

package/dist/gateway/rate-lookup.test.js

@@ -0,0 +1,153 @@
+import { describe, expect, it, vi } from "vitest";
+import { logger } from "../config/logger.js";
+import { createCachedRateLookup, DEFAULT_TOKEN_RATES, resolveTokenRates } from "./rate-lookup.js";
+vi.mock("../config/logger.js", () => ({
+    logger: { warn: vi.fn(), info: vi.fn(), error: vi.fn(), debug: vi.fn() },
+}));
+function makeSellRate(overrides = {}) {
+    return {
+        id: "test-id",
+        capability: "chat-completions",
+        display_name: "Test Rate",
+        unit: overrides.unit ?? "1K-tokens",
+        price_usd: overrides.price_usd ?? 0.01,
+        model: overrides.model ?? "test-model",
+        is_active: true,
+        sort_order: 0,
+        created_at: new Date().toISOString(),
+        updated_at: new Date().toISOString(),
+    };
+}
+describe("createCachedRateLookup", () => {
+    it("returns cached result on second call (raw lookup called once)", async () => {
+        const rawLookup = vi.fn().mockResolvedValue(makeSellRate());
+        const lookup = createCachedRateLookup(rawLookup);
+        await lookup("chat-completions", "gpt-4o");
+        await lookup("chat-completions", "gpt-4o");
+        expect(rawLookup).toHaveBeenCalledTimes(1);
+    });
+    it("re-queries after TTL expires", async () => {
+        const rawLookup = vi.fn().mockResolvedValue(makeSellRate());
+        // Use a 50ms TTL so the test doesn't need fake timers
+        const lookup = createCachedRateLookup(rawLookup, 50);
+        await lookup("chat-completions", "gpt-4o");
+        await new Promise((r) => setTimeout(r, 60)); // wait past TTL
+        await lookup("chat-completions", "gpt-4o");
+        expect(rawLookup).toHaveBeenCalledTimes(2);
+    });
+    it("caches null results to avoid repeated DB queries for unknown models", async () => {
+        const rawLookup = vi.fn().mockResolvedValue(null);
+        const lookup = createCachedRateLookup(rawLookup);
+        await lookup("chat-completions", "unknown-model");
+        await lookup("chat-completions", "unknown-model");
+        expect(rawLookup).toHaveBeenCalledTimes(1);
+    });
+    it("uses separate cache entries for different models", async () => {
+        const rawLookup = vi.fn().mockResolvedValue(null);
+        const lookup = createCachedRateLookup(rawLookup);
+        await lookup("chat-completions", "model-a");
+        await lookup("chat-completions", "model-b");
+        expect(rawLookup).toHaveBeenCalledTimes(2);
+    });
+});
+describe("resolveTokenRates", () => {
+    it("returns defaults when model is undefined", async () => {
+        const lookupFn = async () => null;
+        const rates = await resolveTokenRates(lookupFn, "chat-completions", undefined);
+        expect(rates).toEqual(DEFAULT_TOKEN_RATES);
+    });
+    it("returns defaults when lookup returns null", async () => {
+        const lookupFn = async () => null;
+        const rates = await resolveTokenRates(lookupFn, "chat-completions", "some-model");
+        expect(rates).toEqual(DEFAULT_TOKEN_RATES);
+    });
+    it("uses sell rate price_usd for matching model with blended unit", async () => {
+        const rate = makeSellRate({
+            price_usd: 0.015,
+            unit: "1K-tokens",
+            model: "anthropic/claude-3.5-sonnet",
+        });
+        // No unit-specific rows; blended row returned only when no unit filter is passed
+        const lookupFn = async (_cap, _model, unit) => (unit ? null : rate);
+        const rates = await resolveTokenRates(lookupFn, "chat-completions", "anthropic/claude-3.5-sonnet");
+        expect(rates.inputRatePer1K).toBe(0.015);
+        expect(rates.outputRatePer1K).toBe(0.015); // blended rate applied equally to both
+    });
+    it("handles unit containing 'input' — sets only inputRatePer1K when no output row exists", async () => {
+        const inputRate = makeSellRate({ price_usd: 0.015, unit: "1K-input-tokens" });
+        // Return input rate for "1K-input-tokens" lookup, null for "1K-output-tokens"
+        const lookupFn = async (_cap, _model, unit) => (unit === "1K-input-tokens" ? inputRate : null);
+        const rates = await resolveTokenRates(lookupFn, "chat-completions", "some-model");
+        expect(rates.inputRatePer1K).toBe(0.015);
+        expect(rates.outputRatePer1K).toBe(DEFAULT_TOKEN_RATES.outputRatePer1K);
+    });
+    it("handles unit containing 'output' — sets only outputRatePer1K when no input row exists", async () => {
+        const outputRate = makeSellRate({ price_usd: 0.075, unit: "1K-output-tokens" });
+        // Return output rate for "1K-output-tokens" lookup, null for "1K-input-tokens"
+        const lookupFn = async (_cap, _model, unit) => (unit === "1K-output-tokens" ? outputRate : null);
+        const rates = await resolveTokenRates(lookupFn, "chat-completions", "some-model");
+        expect(rates.inputRatePer1K).toBe(DEFAULT_TOKEN_RATES.inputRatePer1K);
+        expect(rates.outputRatePer1K).toBe(0.075);
+    });
+    it("uses separate input and output rates when both direction rows exist", async () => {
+        const inputRate = makeSellRate({ price_usd: 0.015, unit: "1K-input-tokens" });
+        const outputRate = makeSellRate({ price_usd: 0.075, unit: "1K-output-tokens" });
+        const lookupFn = async (_cap, _model, unit) => {
+            if (unit === "1K-input-tokens")
+                return inputRate;
+            if (unit === "1K-output-tokens")
+                return outputRate;
+            return null;
+        };
+        const rates = await resolveTokenRates(lookupFn, "chat-completions", "some-model");
+        expect(rates.inputRatePer1K).toBe(0.015);
+        expect(rates.outputRatePer1K).toBe(0.075);
+    });
+    it("handles blended rate with single price for both directions", async () => {
+        const rate = makeSellRate({ price_usd: 0.005, unit: "per-1K-tokens" });
+        // No unit-specific rows; blended row returned only when no unit filter is passed
+        const lookupFn = async (_cap, _model, unit) => (unit ? null : rate);
+        const rates = await resolveTokenRates(lookupFn, "chat-completions", "some-model");
+        expect(rates.inputRatePer1K).toBe(0.005);
+        expect(rates.outputRatePer1K).toBe(0.005); // blended rate applied equally to both
+    });
+    it("logs a warning when no sell rate exists for a known model", async () => {
+        vi.mocked(logger.warn).mockClear();
+        const lookupFn = async () => null;
+        await resolveTokenRates(lookupFn, "chat-completions", "anthropic/claude-3.5-sonnet");
+        expect(logger.warn).toHaveBeenCalledWith("No sell rate found for model — using default fallback rates", expect.objectContaining({
+            capability: "chat-completions",
+            model: "anthropic/claude-3.5-sonnet",
+        }));
+    });
+    it("logs a warning when only input rate exists but not output rate", async () => {
+        vi.mocked(logger.warn).mockClear();
+        const inputRate = makeSellRate({ price_usd: 0.015, unit: "1K-input-tokens" });
+        const lookupFn = async (_cap, _model, unit) => (unit === "1K-input-tokens" ? inputRate : null);
+        await resolveTokenRates(lookupFn, "chat-completions", "some-model");
+        expect(logger.warn).toHaveBeenCalledWith("No output sell rate found for model — using default for output direction", expect.objectContaining({
+            capability: "chat-completions",
+            model: "some-model",
+        }));
+    });
+    it("does not log a warning when model is undefined", async () => {
+        vi.mocked(logger.warn).mockClear();
+        const lookupFn = async () => null;
+        await resolveTokenRates(lookupFn, "chat-completions", undefined);
+        expect(logger.warn).not.toHaveBeenCalled();
+    });
+    it("does not log a warning when both direction rates are found", async () => {
+        vi.mocked(logger.warn).mockClear();
+        const inputRate = makeSellRate({ price_usd: 0.015, unit: "1K-input-tokens" });
+        const outputRate = makeSellRate({ price_usd: 0.075, unit: "1K-output-tokens" });
+        const lookupFn = async (_cap, _model, unit) => {
+            if (unit === "1K-input-tokens")
+                return inputRate;
+            if (unit === "1K-output-tokens")
+                return outputRate;
+            return null;
+        };
+        await resolveTokenRates(lookupFn, "chat-completions", "some-model");
+        expect(logger.warn).not.toHaveBeenCalled();
+    });
+});

package/dist/gateway/repository-types.d.ts

@@ -0,0 +1,6 @@
+export interface CircuitBreakerEntry {
+    instanceId: string;
+    count: number;
+    windowStart: number;
+    trippedAt: number | null;
+}

package/dist/gateway/repository-types.js

@@ -0,0 +1 @@
+export {};

package/dist/gateway/route-mounting.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Integration tests for gateway route mounting (WOP-1621).
+ *
+ * Verifies all expected routes are reachable (non-404), auth middleware
+ * is correctly applied, and route ordering is correct.
+ */
+export {};

package/dist/gateway/route-mounting.test.js

@@ -0,0 +1,233 @@
+/**
+ * Integration tests for gateway route mounting (WOP-1621).
+ *
+ * Verifies all expected routes are reachable (non-404), auth middleware
+ * is correctly applied, and route ordering is correct.
+ */
+import { Credit } from "@wopr-network/platform-core/credits";
+import { Hono } from "hono";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { createGatewayRoutes } from "./routes.js";
+vi.mock("../config/logger.js", () => ({
+    logger: { info: vi.fn(), error: vi.fn(), warn: vi.fn(), debug: vi.fn() },
+}));
+const VALID_KEY = "sk-test-route-mounting";
+const TEST_TENANT = {
+    id: "tenant-route-test",
+    spendLimits: { maxSpendPerHour: null, maxSpendPerMonth: null },
+};
+function buildTestConfig(overrides = {}) {
+    const meter = {
+        emit: vi.fn(),
+        flush: vi.fn(),
+        pending: 0,
+        close: vi.fn(),
+        queryEvents: vi.fn(),
+    };
+    const budgetChecker = {
+        check: vi.fn().mockResolvedValue({
+            allowed: true,
+            currentHourlySpend: 0,
+            currentMonthlySpend: 0,
+            maxSpendPerHour: null,
+            maxSpendPerMonth: null,
+        }),
+        invalidate: vi.fn(),
+        clearCache: vi.fn(),
+    };
+    const creditLedger = {
+        balance: vi.fn().mockResolvedValue(Credit.fromCents(10000)),
+        debit: vi.fn().mockResolvedValue(undefined),
+        credit: vi.fn(),
+        history: vi.fn(),
+    };
+    const fetchFn = vi.fn().mockResolvedValue(new Response(JSON.stringify({
+        id: "test",
+        choices: [],
+        usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 },
+    }), {
+        status: 200,
+        headers: { "Content-Type": "application/json", "x-openrouter-cost": "0.001" },
+    }));
+    return {
+        meter: meter,
+        budgetChecker: budgetChecker,
+        creditLedger,
+        providers: { openrouter: { apiKey: "or-test-key" } },
+        fetchFn,
+        resolveServiceKey: (key) => (key === VALID_KEY ? TEST_TENANT : null),
+        ...overrides,
+    };
+}
+function buildApp(config) {
+    const app = new Hono();
+    app.route("/v1", createGatewayRoutes(config));
+    return app;
+}
+function authedRequest(app, method, path, body) {
+    const headers = {
+        Authorization: `Bearer ${VALID_KEY}`,
+        "Content-Type": "application/json",
+    };
+    return app.request(path, { method, headers, body });
+}
+function unauthedRequest(app, method, path) {
+    return app.request(path, { method });
+}
+// ---------------------------------------------------------------------------
+// Route reachability — all routes return non-404 with valid auth
+// ---------------------------------------------------------------------------
+describe("gateway route mounting — reachability", () => {
+    let app;
+    beforeEach(() => {
+        app = buildApp(buildTestConfig());
+    });
+    const protectedPostRoutes = [
+        "/v1/chat/completions",
+        "/v1/completions",
+        "/v1/embeddings",
+        "/v1/audio/transcriptions",
+        "/v1/audio/speech",
+        "/v1/images/generations",
+        "/v1/video/generations",
+        "/v1/phone/outbound",
+        "/v1/phone/numbers",
+        "/v1/messages/sms",
+    ];
+    it.each(protectedPostRoutes)("POST %s is reachable (non-404)", async (path) => {
+        const res = await authedRequest(app, "POST", path, JSON.stringify({ model: "test", messages: [] }));
+        expect(res.status).not.toBe(404);
+    });
+    it("GET /v1/phone/numbers is reachable (non-404)", async () => {
+        const res = await authedRequest(app, "GET", "/v1/phone/numbers");
+        expect(res.status).not.toBe(404);
+    });
+    it("DELETE /v1/phone/numbers/:id is reachable (non-404)", async () => {
+        const res = await authedRequest(app, "DELETE", "/v1/phone/numbers/pn-123");
+        expect(res.status).not.toBe(404);
+    });
+    it("GET /v1/models is reachable (non-404)", async () => {
+        const res = await authedRequest(app, "GET", "/v1/models");
+        expect(res.status).not.toBe(404);
+    });
+});
+// ---------------------------------------------------------------------------
+// Auth middleware — protected routes reject unauthenticated requests
+// ---------------------------------------------------------------------------
+describe("gateway route mounting — auth enforcement", () => {
+    let app;
+    beforeEach(() => {
+        app = buildApp(buildTestConfig());
+    });
+    const protectedRoutes = [
+        ["POST", "/v1/chat/completions"],
+        ["POST", "/v1/completions"],
+        ["POST", "/v1/embeddings"],
+        ["POST", "/v1/audio/transcriptions"],
+        ["POST", "/v1/audio/speech"],
+        ["POST", "/v1/images/generations"],
+        ["POST", "/v1/video/generations"],
+        ["POST", "/v1/phone/outbound"],
+        ["POST", "/v1/phone/numbers"],
+        ["GET", "/v1/phone/numbers"],
+        ["DELETE", "/v1/phone/numbers/pn-123"],
+        ["POST", "/v1/messages/sms"],
+        ["GET", "/v1/models"],
+    ];
+    it.each(protectedRoutes)("%s %s returns 401 without auth", async (method, path) => {
+        const res = await unauthedRequest(app, method, path);
+        expect(res.status).toBe(401);
+        const json = await res.json();
+        expect(json.error.code).toBe("missing_api_key");
+    });
+});
+// ---------------------------------------------------------------------------
+// Public routes — no auth required
+// ---------------------------------------------------------------------------
+describe("gateway route mounting — public routes", () => {
+    let app;
+    beforeEach(() => {
+        app = buildApp(buildTestConfig());
+    });
+    it("GET /v1/phone/twiml/hangup is accessible without auth", async () => {
+        const res = await unauthedRequest(app, "GET", "/v1/phone/twiml/hangup");
+        expect(res.status).not.toBe(401);
+        expect(res.status).not.toBe(404);
+    });
+});
+// ---------------------------------------------------------------------------
+// Route ordering — webhook routes registered before serviceKeyAuth wildcard
+// ---------------------------------------------------------------------------
+describe("gateway route mounting — webhook route ordering", () => {
+    it("webhook routes are reachable when Twilio is fully configured", async () => {
+        const sigPenaltyRepo = {
+            get: vi.fn().mockResolvedValue(null),
+            recordFailure: vi.fn().mockResolvedValue({ failures: 1, blockedUntil: 0 }),
+            clear: vi.fn().mockResolvedValue(undefined),
+            purgeStale: vi.fn().mockResolvedValue(0),
+        };
+        const config = buildTestConfig({
+            providers: {
+                openrouter: { apiKey: "or-test-key" },
+                twilio: { accountSid: "AC-test", authToken: "twilio-auth-token" },
+            },
+            webhookBaseUrl: "https://api.test.example/v1",
+            resolveTenantFromWebhook: () => TEST_TENANT,
+            sigPenaltyRepo: sigPenaltyRepo,
+        });
+        const app = buildApp(config);
+        // Webhook routes use Twilio HMAC auth, not Bearer. They should NOT return 404.
+        // They will return 401/403 (bad signature) but NOT 404.
+        const webhookPaths = [
+            "/v1/phone/inbound/tenant-1",
+            "/v1/phone/outbound/status/tenant-1",
+            "/v1/messages/sms/inbound/tenant-1",
+            "/v1/messages/sms/status/tenant-1",
+        ];
+        for (const path of webhookPaths) {
+            const res = await app.request(path, {
+                method: "POST",
+                headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                body: "test=1",
+            });
+            expect(res.status, `${path} should be 400 (Twilio HMAC missing sig, not 401/404)`).toBe(400);
+        }
+    });
+    it("webhook routes return 401 when Twilio is NOT configured (wildcard auth catches them)", async () => {
+        const config = buildTestConfig(); // no twilio config
+        const app = buildApp(config);
+        // Without Twilio config, webhook routes are not registered.
+        // The serviceKeyAuth wildcard catches these paths and returns 401 (no Bearer).
+        const res = await app.request("/v1/phone/inbound/tenant-1", {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: "test=1",
+        });
+        expect(res.status).toBe(401);
+    });
+});
+// ---------------------------------------------------------------------------
+// Protocol sub-routes mounted
+// ---------------------------------------------------------------------------
+describe("gateway route mounting — protocol sub-routes", () => {
+    let app;
+    beforeEach(() => {
+        app = buildApp(buildTestConfig());
+    });
+    it("POST /v1/anthropic/... is mounted (non-404)", async () => {
+        const res = await app.request("/v1/anthropic/v1/messages", {
+            method: "POST",
+            headers: { "Content-Type": "application/json", "x-api-key": "test-key" },
+            body: JSON.stringify({ model: "claude-3", messages: [] }),
+        });
+        expect(res.status).not.toBe(404);
+    });
+    it("POST /v1/openai/... is mounted (non-404)", async () => {
+        const res = await app.request("/v1/openai/v1/chat/completions", {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Authorization: "Bearer test-key" },
+            body: JSON.stringify({ model: "gpt-4", messages: [] }),
+        });
+        expect(res.status).not.toBe(404);
+    });
+});

package/dist/gateway/routes.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Gateway routes — mounts all /v1/... endpoints behind service key auth.
+ *
+ * This is the external API surface that bots consume. All routes require
+ * a valid WOPR service key and follow the authenticate -> budget check ->
+ * proxy -> meter -> respond pattern.
+ */
+import { Hono } from "hono";
+import { type GatewayAuthEnv } from "./service-key-auth.js";
+import type { GatewayConfig } from "./types.js";
+/**
+ * Create the gateway router with all /v1/... endpoints.
+ *
+ * @param config - Gateway configuration (providers, meter, budget checker, etc.)
+ * @returns Hono app to mount at /v1 in the main app
+ */
+export declare function createGatewayRoutes(config: GatewayConfig): Hono<GatewayAuthEnv>;

package/dist/gateway/routes.js

@@ -0,0 +1,145 @@
+/**
+ * Gateway routes — mounts all /v1/... endpoints behind service key auth.
+ *
+ * This is the external API surface that bots consume. All routes require
+ * a valid WOPR service key and follow the authenticate -> budget check ->
+ * proxy -> meter -> respond pattern.
+ */
+import { Hono } from "hono";
+import { rateLimit } from "../api/middleware/rate-limit.js";
+import { logger } from "../config/logger.js";
+import { withMargin } from "../monetization/adapters/types.js";
+import { audioBodyLimit, llmBodyLimit, mediaBodyLimit, webhookBodyLimit } from "./body-limit.js";
+import { botMetricsMiddleware } from "./bot-metrics-middleware.js";
+import { capabilityRateLimit } from "./capability-rate-limit.js";
+import { circuitBreaker, DEFAULT_CIRCUIT_BREAKER_CONFIG } from "./circuit-breaker.js";
+import { hydrateSpendingCaps } from "./hydrate-spending-caps.js";
+import { modelsHandler } from "./models.js";
+import { createAnthropicRoutes } from "./protocol/anthropic.js";
+import { createOpenAIRoutes } from "./protocol/openai.js";
+import { audioSpeech, audioTranscriptions, buildProxyDeps, chatCompletions, embeddings, imageGenerations, phoneInbound, phoneNumberList, phoneNumberProvision, phoneNumberRelease, phoneOutbound, phoneOutboundStatus, phoneTwimlHangup, smsDeliveryStatus, smsInbound, smsOutbound, textCompletions, videoGenerations, } from "./proxy.js";
+import { serviceKeyAuth } from "./service-key-auth.js";
+import { spendingCapCheck } from "./spending-cap.js";
+import { createTwilioWebhookAuth } from "./webhook-auth.js";
+/**
+ * Create the gateway router with all /v1/... endpoints.
+ *
+ * @param config - Gateway configuration (providers, meter, budget checker, etc.)
+ * @returns Hono app to mount at /v1 in the main app
+ */
+export function createGatewayRoutes(config) {
+    const gateway = new Hono();
+    const deps = buildProxyDeps(config);
+    // Protocol-specific routes — these handle their own auth (x-api-key / Bearer)
+    const protocolDeps = {
+        meter: config.meter,
+        budgetChecker: config.budgetChecker,
+        creditLedger: config.creditLedger,
+        topUpUrl: config.topUpUrl ?? "/dashboard/credits",
+        graceBufferCents: config.graceBufferCents,
+        providers: config.providers,
+        defaultMargin: config.defaultMargin ?? 1.3,
+        fetchFn: config.fetchFn ?? fetch,
+        resolveServiceKey: config.resolveServiceKey,
+        withMarginFn: withMargin,
+        rateLookupFn: config.rateLookupFn,
+        capabilityRateLimitConfig: config.capabilityRateLimitConfig,
+        circuitBreakerConfig: config.circuitBreakerConfig,
+        onCircuitBreakerTrip: config.onCircuitBreakerTrip,
+        rateLimitRepo: config.rateLimitRepo,
+        circuitBreakerRepo: config.circuitBreakerRepo,
+        onDebitComplete: config.onDebitComplete,
+        onBalanceExhausted: config.onBalanceExhausted,
+        onSpendAlertCrossed: config.onSpendAlertCrossed,
+    };
+    gateway.route("/anthropic", createAnthropicRoutes(protocolDeps));
+    gateway.route("/openai", createOpenAIRoutes(protocolDeps));
+    // --- Webhook routes (Twilio HMAC signature auth, NOT Bearer) ---
+    // These MUST be registered BEFORE the serviceKeyAuth("/*") middleware.
+    // Twilio sends X-Twilio-Signature headers, not Bearer tokens.
+    if (config.webhookBaseUrl && !config.resolveTenantFromWebhook) {
+        logger.warn("Gateway: webhookBaseUrl is set but resolveTenantFromWebhook is missing — Twilio webhook routes will not be registered and webhooks will receive 404");
+    }
+    if (config.resolveTenantFromWebhook && !config.webhookBaseUrl) {
+        logger.warn("Gateway: resolveTenantFromWebhook is set but webhookBaseUrl is missing — Twilio webhook routes will not be registered and webhooks will receive 404");
+    }
+    if (config.providers.twilio?.authToken &&
+        config.webhookBaseUrl &&
+        config.resolveTenantFromWebhook &&
+        !config.sigPenaltyRepo) {
+        logger.warn("Gateway: Twilio is configured but sigPenaltyRepo is absent — Twilio webhook routes will not be registered and webhooks will receive 404");
+    }
+    if (config.providers.twilio?.authToken &&
+        config.webhookBaseUrl &&
+        config.resolveTenantFromWebhook &&
+        config.sigPenaltyRepo) {
+        const webhookAuth = createTwilioWebhookAuth({
+            twilioAuthToken: config.providers.twilio.authToken,
+            webhookBaseUrl: config.webhookBaseUrl,
+            resolveTenantFromWebhook: config.resolveTenantFromWebhook,
+            sigPenaltyRepo: config.sigPenaltyRepo,
+        });
+        gateway.post("/phone/inbound/:tenantId", webhookBodyLimit(), webhookAuth, phoneInbound(deps));
+        gateway.post("/phone/outbound/status/:tenantId", webhookBodyLimit(), webhookAuth, phoneOutboundStatus(deps));
+        gateway.post("/messages/sms/inbound/:tenantId", webhookBodyLimit(), webhookAuth, smsInbound(deps));
+        gateway.post("/messages/sms/status/:tenantId", webhookBodyLimit(), webhookAuth, smsDeliveryStatus(deps));
+    }
+    // Self-hosted TwiML endpoint — public, no auth required (Twilio fetches it during call setup).
+    // Replaces the third-party http://twiml.ai/hangup used as default TwiML fallback.
+    gateway.get("/phone/twiml/hangup", phoneTwimlHangup());
+    // All remaining gateway routes require service key authentication via Bearer
+    gateway.use("/*", serviceKeyAuth(config.resolveServiceKey));
+    // 0. Hydrate spending caps from DB (must run before spendingCapCheck)
+    if (config.spendingLimitsRepo) {
+        gateway.use("/*", hydrateSpendingCaps(config.spendingLimitsRepo));
+    }
+    // 1. Spending cap enforcement — reject if over daily/monthly cap before consuming rate limit tokens
+    if (config.spendingCapStore) {
+        gateway.use("/*", spendingCapCheck(config.spendingCapStore, config.spendingCapConfig));
+    }
+    // 2. Per-capability rate limiting (replaces flat tenantLimit)
+    gateway.use("/*", capabilityRateLimit(config.capabilityRateLimitConfig, config.rateLimitRepo));
+    // 3. Circuit breaker for runaway instances
+    gateway.use("/*", circuitBreaker({
+        ...DEFAULT_CIRCUIT_BREAKER_CONFIG,
+        ...config.circuitBreakerConfig,
+        repo: config.circuitBreakerRepo,
+        onTrip: config.onCircuitBreakerTrip,
+    }));
+    // 4. Per-bot application metrics (WOP-1514)
+    if (config.botMetricsTracker) {
+        gateway.use("/*", botMetricsMiddleware(config.botMetricsTracker));
+    }
+    // LLM endpoints (OpenRouter)
+    gateway.post("/chat/completions", llmBodyLimit(), chatCompletions(deps));
+    gateway.post("/completions", llmBodyLimit(), textCompletions(deps));
+    gateway.post("/embeddings", llmBodyLimit(), embeddings(deps));
+    // Audio endpoints
+    gateway.post("/audio/transcriptions", audioBodyLimit(), audioTranscriptions(deps));
+    gateway.post("/audio/speech", audioBodyLimit(), audioSpeech(deps));
+    // Image & Video generation (Replicate)
+    gateway.post("/images/generations", mediaBodyLimit(), imageGenerations(deps));
+    gateway.post("/video/generations", mediaBodyLimit(), videoGenerations(deps));
+    // Phone (Twilio/Telnyx)
+    gateway.post("/phone/outbound", webhookBodyLimit(), phoneOutbound(deps));
+    // Phone Number Management
+    gateway.post("/phone/numbers", webhookBodyLimit(), phoneNumberProvision(deps));
+    gateway.get("/phone/numbers", phoneNumberList(deps));
+    gateway.delete("/phone/numbers/:id", phoneNumberRelease(deps));
+    // SMS/MMS (Twilio/Telnyx) — rate-limited per tenant to prevent spam
+    const smsRateLimit = rateLimit({
+        max: config.smsRateLimit ?? 100,
+        windowMs: 60_000,
+        keyGenerator: (c) => {
+            const tenant = c.get("gatewayTenant");
+            return tenant?.id ?? "unknown";
+        },
+        message: "SMS rate limit exceeded. Please slow down.",
+        repo: config.rateLimitRepo,
+        scope: "gateway:sms",
+    });
+    gateway.post("/messages/sms", smsRateLimit, webhookBodyLimit(), smsOutbound(deps));
+    // Model discovery
+    gateway.get("/models", modelsHandler(deps));
+    return gateway;
+}

package/dist/gateway/service-key-auth.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Service key authentication middleware for the API gateway.
+ *
+ * Bots authenticate with WOPR service keys (not provider API keys).
+ * This middleware extracts the bearer token, resolves the tenant,
+ * and sets gateway context for downstream handlers.
+ */
+import type { Context, Next } from "hono";
+import type { GatewayTenant } from "./types.js";
+export interface GatewayAuthEnv {
+    Variables: {
+        gatewayTenant: GatewayTenant;
+        webhookBody: Record<string, unknown>;
+    };
+}
+/**
+ * Create middleware that authenticates WOPR service keys.
+ *
+ * Extracts the bearer token from the Authorization header, resolves
+ * it to a tenant via the provided resolver function, and stores
+ * the tenant in the Hono context for downstream handlers.
+ *
+ * @param resolveServiceKey - Function that maps a service key to a tenant (or null)
+ */
+export declare function serviceKeyAuth(resolveServiceKey: (key: string) => GatewayTenant | null): (c: Context<GatewayAuthEnv>, next: Next) => Promise<void | (Response & import("hono").TypedResponse<{
+    error: {
+        message: string;
+        type: string;
+        code: string;
+    };
+}, 401, "json">)>;

package/dist/gateway/service-key-auth.js

@@ -0,0 +1,66 @@
+/**
+ * Service key authentication middleware for the API gateway.
+ *
+ * Bots authenticate with WOPR service keys (not provider API keys).
+ * This middleware extracts the bearer token, resolves the tenant,
+ * and sets gateway context for downstream handlers.
+ */
+import { logger } from "../config/logger.js";
+/**
+ * Create middleware that authenticates WOPR service keys.
+ *
+ * Extracts the bearer token from the Authorization header, resolves
+ * it to a tenant via the provided resolver function, and stores
+ * the tenant in the Hono context for downstream handlers.
+ *
+ * @param resolveServiceKey - Function that maps a service key to a tenant (or null)
+ */
+export function serviceKeyAuth(resolveServiceKey) {
+    return async (c, next) => {
+        const authHeader = c.req.header("Authorization");
+        if (!authHeader) {
+            return c.json({
+                error: {
+                    message: "Missing Authorization header",
+                    type: "authentication_error",
+                    code: "missing_api_key",
+                },
+            }, 401);
+        }
+        const trimmed = authHeader.trim();
+        if (!trimmed.toLowerCase().startsWith("bearer ")) {
+            return c.json({
+                error: {
+                    message: "Invalid Authorization header format. Expected: Bearer <service_key>",
+                    type: "authentication_error",
+                    code: "invalid_auth_format",
+                },
+            }, 401);
+        }
+        const serviceKey = trimmed.slice(7).trim();
+        if (!serviceKey) {
+            return c.json({
+                error: {
+                    message: "Empty service key",
+                    type: "authentication_error",
+                    code: "missing_api_key",
+                },
+            }, 401);
+        }
+        const tenant = resolveServiceKey(serviceKey);
+        if (!tenant) {
+            logger.warn("Invalid service key attempted", {
+                keyPrefix: `${serviceKey.slice(0, 8)}...`,
+            });
+            return c.json({
+                error: {
+                    message: "Invalid or expired service key",
+                    type: "authentication_error",
+                    code: "invalid_api_key",
+                },
+            }, 401);
+        }
+        c.set("gatewayTenant", tenant);
+        return next();
+    };
+}