@wopr-network/platform-core 1.0.10 → 1.1.0

package/dist/gateway/webhook-auth.test.js

@@ -0,0 +1,195 @@
+/**
+ * Tests for Twilio webhook authentication middleware.
+ */
+import crypto from "node:crypto";
+import { Hono } from "hono";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { DrizzleSigPenaltyRepository } from "../api/drizzle-sig-penalty-repository.js";
+import { beginTestTransaction, createTestDb, endTestTransaction, rollbackTestTransaction } from "../test/db.js";
+import { createTwilioWebhookAuth } from "./webhook-auth.js";
+let db;
+let pool;
+function makeTestSigPenaltyRepo() {
+    return new DrizzleSigPenaltyRepository(db);
+}
+const TEST_AUTH_TOKEN = "test-auth-token-12345";
+const TEST_WEBHOOK_BASE_URL = "https://api.wopr.network/v1";
+const TEST_TENANT = {
+    id: "tenant-abc",
+    spendLimits: { maxSpendPerHour: null, maxSpendPerMonth: null },
+};
+function computeSignature(authToken, url, params) {
+    const sortedKeys = Object.keys(params).sort();
+    let data = url;
+    for (const key of sortedKeys) {
+        data += key + params[key];
+    }
+    return crypto.createHmac("sha1", authToken).update(data).digest("base64");
+}
+function buildTestApp(resolveTenant = () => TEST_TENANT, sigPenaltyRepo = makeTestSigPenaltyRepo()) {
+    const app = new Hono();
+    const webhookAuth = createTwilioWebhookAuth({
+        twilioAuthToken: TEST_AUTH_TOKEN,
+        webhookBaseUrl: TEST_WEBHOOK_BASE_URL,
+        resolveTenantFromWebhook: resolveTenant,
+        sigPenaltyRepo,
+    });
+    app.post("/v1/phone/inbound/:tenantId", webhookAuth, (c) => {
+        return c.json({ ok: true, tenantId: c.get("gatewayTenant")?.id });
+    });
+    return app;
+}
+/**
+ * Build a test app that simulates real socket addresses by injecting
+ * `c.env.incoming.socket.remoteAddress` from the X-Forwarded-For header.
+ * This allows IP-isolation tests to work without a real TCP socket.
+ */
+function buildTestAppWithSocketInjection(resolveTenant = () => TEST_TENANT, sigPenaltyRepo = makeTestSigPenaltyRepo()) {
+    const app = new Hono();
+    // Inject socket address from XFF so trusted-proxy-aware IP extraction works in tests
+    app.use("*", async (c, next) => {
+        const xff = c.req.header("x-forwarded-for");
+        const firstIp = xff?.split(",")[0]?.trim();
+        if (firstIp) {
+            // In test context c.env is undefined; assign it to simulate a real TCP socket.
+            c.env = { incoming: { socket: { remoteAddress: firstIp } } };
+        }
+        await next();
+    });
+    const webhookAuth = createTwilioWebhookAuth({
+        twilioAuthToken: TEST_AUTH_TOKEN,
+        webhookBaseUrl: TEST_WEBHOOK_BASE_URL,
+        resolveTenantFromWebhook: resolveTenant,
+        sigPenaltyRepo,
+    });
+    app.post("/v1/phone/inbound/:tenantId", webhookAuth, (c) => {
+        return c.json({ ok: true, tenantId: c.get("gatewayTenant")?.id });
+    });
+    return app;
+}
+describe("createTwilioWebhookAuth", () => {
+    beforeAll(async () => {
+        ({ db, pool } = await createTestDb());
+        await beginTestTransaction(pool);
+    });
+    afterAll(async () => {
+        await endTestTransaction(pool);
+        await pool.close();
+    });
+    beforeEach(async () => {
+        await rollbackTestTransaction(pool);
+    });
+    it("returns 400 when X-Twilio-Signature header is missing", async () => {
+        const app = buildTestApp();
+        const res = await app.request("/v1/phone/inbound/tenant-abc", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({}),
+        });
+        expect(res.status).toBe(400);
+        const body = (await res.json());
+        expect(body.error).toMatch(/missing/i);
+    });
+    it("returns 400 when X-Twilio-Signature is invalid", async () => {
+        const app = buildTestApp();
+        const res = await app.request("/v1/phone/inbound/tenant-abc", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "X-Twilio-Signature": "invalidsignature==",
+            },
+            body: JSON.stringify({}),
+        });
+        expect(res.status).toBe(400);
+        const body = (await res.json());
+        expect(body.error).toMatch(/invalid/i);
+    });
+    it("passes through with valid signature and sets gatewayTenant", async () => {
+        const app = buildTestApp();
+        const url = `${TEST_WEBHOOK_BASE_URL}/phone/inbound/tenant-abc`;
+        const params = { CallSid: "CA123", From: "+15005550006", To: "+15005550001" };
+        const signature = computeSignature(TEST_AUTH_TOKEN, url, params);
+        const res = await app.request("/v1/phone/inbound/tenant-abc", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "X-Twilio-Signature": signature,
+            },
+            body: JSON.stringify(params),
+        });
+        expect(res.status).toBe(200);
+        const body = (await res.json());
+        expect(body.ok).toBe(true);
+        expect(body.tenantId).toBe("tenant-abc");
+    });
+    it("returns 401 when tenant cannot be resolved", async () => {
+        const app = buildTestApp(() => null);
+        const url = `${TEST_WEBHOOK_BASE_URL}/phone/inbound/unknown-tenant`;
+        const signature = computeSignature(TEST_AUTH_TOKEN, url, {});
+        const res = await app.request("/v1/phone/inbound/unknown-tenant", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "X-Twilio-Signature": signature,
+            },
+            body: JSON.stringify({}),
+        });
+        expect(res.status).toBe(401);
+    });
+    it("applies exponential backoff after repeated failures from same IP", async () => {
+        const app = buildTestApp();
+        // Send 6 invalid requests from same IP
+        for (let i = 0; i < 6; i++) {
+            await app.request("/v1/phone/inbound/tenant-abc", {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "X-Twilio-Signature": "badsig==",
+                    "X-Forwarded-For": "10.0.0.1",
+                },
+                body: JSON.stringify({}),
+            });
+        }
+        // After enough failures, should get 429
+        const res = await app.request("/v1/phone/inbound/tenant-abc", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "X-Twilio-Signature": "badsig==",
+                "X-Forwarded-For": "10.0.0.1",
+            },
+            body: JSON.stringify({}),
+        });
+        expect(res.status).toBe(429);
+    });
+    it("does not penalize different IPs for each other's failures", async () => {
+        const sharedRepo = makeTestSigPenaltyRepo();
+        const app = buildTestAppWithSocketInjection(() => TEST_TENANT, sharedRepo);
+        // Send many failures from IP A
+        for (let i = 0; i < 10; i++) {
+            await app.request("/v1/phone/inbound/tenant-abc", {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "X-Twilio-Signature": "badsig==",
+                    "X-Forwarded-For": "10.0.0.2",
+                },
+                body: JSON.stringify({}),
+            });
+        }
+        // IP B with valid signature should still get through
+        const url = `${TEST_WEBHOOK_BASE_URL}/phone/inbound/tenant-abc`;
+        const params = {};
+        const signature = computeSignature(TEST_AUTH_TOKEN, url, params);
+        const res = await app.request("/v1/phone/inbound/tenant-abc", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "X-Twilio-Signature": signature,
+                "X-Forwarded-For": "192.168.1.1",
+            },
+            body: JSON.stringify(params),
+        });
+        expect(res.status).toBe(200);
+    });
+});

package/dist/inference/budget-guard.d.ts

@@ -0,0 +1,8 @@
+import type { ISessionUsageRepository } from "./session-usage-repository.js";
+export type BudgetTier = "anonymous" | "free" | "paid";
+export interface BudgetCheckResult {
+    allowed: boolean;
+    remainingUsd: number;
+    capUsd: number;
+}
+export declare function checkSessionBudget(repo: ISessionUsageRepository, sessionId: string, tier: BudgetTier): Promise<BudgetCheckResult>;

package/dist/inference/budget-guard.js

@@ -0,0 +1,15 @@
+const BUDGET_CAPS_USD = {
+    anonymous: 0.1,
+    free: 0.25,
+    paid: 1.0,
+};
+export async function checkSessionBudget(repo, sessionId, tier) {
+    const cap = BUDGET_CAPS_USD[tier];
+    const spent = await repo.sumCostBySession(sessionId);
+    const remaining = cap - spent;
+    return {
+        allowed: remaining > 0,
+        remainingUsd: Math.max(0, remaining),
+        capUsd: cap,
+    };
+}

package/dist/inference/budget-guard.test.d.ts

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

package/dist/inference/budget-guard.test.js

@@ -0,0 +1,51 @@
+import { describe, expect, it, vi } from "vitest";
+import { checkSessionBudget } from "./budget-guard.js";
+function mockRepo(costBySession) {
+    return {
+        insert: vi.fn(),
+        findBySessionId: vi.fn(),
+        sumCostByUser: vi.fn(),
+        sumCostBySession: vi.fn().mockResolvedValue(costBySession),
+        aggregateByDay: vi.fn(),
+        aggregateByPage: vi.fn(),
+        cacheHitRate: vi.fn(),
+        aggregateSessionCost: vi.fn(),
+    };
+}
+describe("checkSessionBudget", () => {
+    it("allows when under budget", async () => {
+        const result = await checkSessionBudget(mockRepo(0.05), "sess-1", "anonymous");
+        expect(result.allowed).toBe(true);
+        expect(result.remainingUsd).toBeCloseTo(0.05);
+    });
+    it("rejects when over anonymous cap ($0.10)", async () => {
+        const result = await checkSessionBudget(mockRepo(0.11), "sess-1", "anonymous");
+        expect(result.allowed).toBe(false);
+    });
+    it("uses higher cap for authenticated free tier ($0.25)", async () => {
+        const result = await checkSessionBudget(mockRepo(0.2), "sess-1", "free");
+        expect(result.allowed).toBe(true);
+    });
+    it("uses highest cap for paid users ($1.00)", async () => {
+        const result = await checkSessionBudget(mockRepo(0.9), "sess-1", "paid");
+        expect(result.allowed).toBe(true);
+    });
+    it("rejects when exactly at anonymous cap ($0.10)", async () => {
+        const result = await checkSessionBudget(mockRepo(0.1), "sess-1", "anonymous");
+        expect(result.allowed).toBe(false);
+        expect(result.remainingUsd).toBeCloseTo(0);
+        expect(result.capUsd).toBe(0.1);
+    });
+    it("rejects when exactly at free tier cap ($0.25)", async () => {
+        const result = await checkSessionBudget(mockRepo(0.25), "sess-1", "free");
+        expect(result.allowed).toBe(false);
+        expect(result.remainingUsd).toBeCloseTo(0);
+        expect(result.capUsd).toBe(0.25);
+    });
+    it("rejects when exactly at paid tier cap ($1.00)", async () => {
+        const result = await checkSessionBudget(mockRepo(1.0), "sess-1", "paid");
+        expect(result.allowed).toBe(false);
+        expect(result.remainingUsd).toBeCloseTo(0);
+        expect(result.capUsd).toBe(1.0);
+    });
+});

package/dist/inference/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./budget-guard.js";
+export * from "./inference-cost.js";
+export * from "./session-usage-repository.js";

package/dist/inference/index.js

@@ -0,0 +1,3 @@
+export * from "./budget-guard.js";
+export * from "./inference-cost.js";
+export * from "./session-usage-repository.js";

package/dist/inference/inference-cost.d.ts

@@ -0,0 +1,9 @@
+interface TokenUsage {
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    cachedTokens: number;
+    cacheWriteTokens: number;
+}
+export declare function computeInferenceCost(usage: TokenUsage): number;
+export {};

package/dist/inference/inference-cost.js

@@ -0,0 +1,25 @@
+const MODEL_PRICING = {
+    "claude-sonnet-4-20250514": {
+        inputPerMillion: 3,
+        outputPerMillion: 15,
+        cacheReadPerMillion: 0.3,
+        cacheWritePerMillion: 3.75,
+    },
+    "claude-haiku-4-5-20251001": {
+        inputPerMillion: 0.8,
+        outputPerMillion: 4,
+        cacheReadPerMillion: 0.08,
+        cacheWritePerMillion: 1.0,
+    },
+};
+export function computeInferenceCost(usage) {
+    const pricing = MODEL_PRICING[usage.model];
+    if (!pricing)
+        return 0;
+    const nonCachedInput = usage.inputTokens - usage.cachedTokens - usage.cacheWriteTokens;
+    const inputCost = (nonCachedInput * pricing.inputPerMillion) / 1_000_000;
+    const cachedCost = (usage.cachedTokens * pricing.cacheReadPerMillion) / 1_000_000;
+    const cacheWriteCost = (usage.cacheWriteTokens * pricing.cacheWritePerMillion) / 1_000_000;
+    const outputCost = (usage.outputTokens * pricing.outputPerMillion) / 1_000_000;
+    return inputCost + cachedCost + cacheWriteCost + outputCost;
+}

package/dist/inference/inference-cost.test.d.ts

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

package/dist/inference/inference-cost.test.js

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import { computeInferenceCost } from "./inference-cost.js";
+describe("computeInferenceCost", () => {
+    it("computes cost for Claude Sonnet with no caching", () => {
+        const cost = computeInferenceCost({
+            model: "claude-sonnet-4-20250514",
+            inputTokens: 1000,
+            outputTokens: 200,
+            cachedTokens: 0,
+            cacheWriteTokens: 0,
+        });
+        // Sonnet: $3/M input, $15/M output
+        // (1000 * 3/1e6) + (200 * 15/1e6) = 0.003 + 0.003 = 0.006
+        expect(cost).toBeCloseTo(0.006);
+    });
+    it("applies cache read discount (10% of input price)", () => {
+        const cost = computeInferenceCost({
+            model: "claude-sonnet-4-20250514",
+            inputTokens: 1000,
+            outputTokens: 200,
+            cachedTokens: 800,
+            cacheWriteTokens: 0,
+        });
+        // Non-cached input: 200 tokens * $3/M = 0.0006
+        // Cached read: 800 tokens * $0.30/M = 0.00024
+        // Output: 200 tokens * $15/M = 0.003
+        // Total: 0.0006 + 0.00024 + 0.003 = 0.00384
+        expect(cost).toBeCloseTo(0.00384);
+    });
+    it("applies cache write surcharge (125% of input price)", () => {
+        const cost = computeInferenceCost({
+            model: "claude-sonnet-4-20250514",
+            inputTokens: 1000,
+            outputTokens: 100,
+            cachedTokens: 0,
+            cacheWriteTokens: 500,
+        });
+        // Non-cached input: 500 tokens * $3/M = 0.0015
+        // Cache write: 500 tokens * $3.75/M = 0.001875
+        // Output: 100 tokens * $15/M = 0.0015
+        // Total: 0.0015 + 0.001875 + 0.0015 = 0.004875
+        expect(cost).toBeCloseTo(0.004875);
+    });
+    it("returns 0 for unknown model (fallback to OpenRouter cost header)", () => {
+        const cost = computeInferenceCost({
+            model: "unknown-model-v9",
+            inputTokens: 1000,
+            outputTokens: 200,
+            cachedTokens: 0,
+            cacheWriteTokens: 0,
+        });
+        expect(cost).toBe(0);
+    });
+});

package/dist/inference/session-usage-repository.d.ts

@@ -0,0 +1,59 @@
+import type { DrizzleDb } from "../db/index.js";
+export interface SessionUsage {
+    id: string;
+    sessionId: string;
+    userId: string | null;
+    page: string | null;
+    inputTokens: number;
+    outputTokens: number;
+    cachedTokens: number;
+    cacheWriteTokens: number;
+    model: string;
+    costUsd: number;
+    createdAt: number;
+}
+export type NewSessionUsage = Omit<SessionUsage, "id" | "createdAt">;
+export interface DailyCostAggregate {
+    day: string;
+    totalCostUsd: number;
+    sessionCount: number;
+}
+export interface PageCostAggregate {
+    page: string;
+    totalCostUsd: number;
+    callCount: number;
+    avgCostUsd: number;
+}
+export interface SessionCostSummary {
+    totalCostUsd: number;
+    totalSessions: number;
+    avgCostPerSession: number;
+}
+export interface CacheStats {
+    hitRate: number;
+    cachedTokens: number;
+    cacheWriteTokens: number;
+    uncachedTokens: number;
+}
+export interface ISessionUsageRepository {
+    insert(record: NewSessionUsage): Promise<SessionUsage>;
+    findBySessionId(sessionId: string): Promise<SessionUsage[]>;
+    sumCostByUser(userId: string, since: number): Promise<number>;
+    sumCostBySession(sessionId: string): Promise<number>;
+    aggregateByDay(since: number): Promise<DailyCostAggregate[]>;
+    aggregateByPage(since: number): Promise<PageCostAggregate[]>;
+    cacheHitRate(since: number): Promise<CacheStats>;
+    aggregateSessionCost(since: number): Promise<SessionCostSummary>;
+}
+export declare class DrizzleSessionUsageRepository implements ISessionUsageRepository {
+    private readonly db;
+    constructor(db: DrizzleDb);
+    insert(record: NewSessionUsage): Promise<SessionUsage>;
+    findBySessionId(sessionId: string): Promise<SessionUsage[]>;
+    sumCostBySession(sessionId: string): Promise<number>;
+    sumCostByUser(userId: string, since: number): Promise<number>;
+    aggregateByDay(since: number): Promise<DailyCostAggregate[]>;
+    aggregateByPage(since: number): Promise<PageCostAggregate[]>;
+    cacheHitRate(since: number): Promise<CacheStats>;
+    aggregateSessionCost(since: number): Promise<SessionCostSummary>;
+}

package/dist/inference/session-usage-repository.js

@@ -0,0 +1,133 @@
+import { randomUUID } from "node:crypto";
+import { and, eq, gt, sql, sum } from "drizzle-orm";
+import { sessionUsage } from "../db/schema/index.js";
+function toSessionUsage(row) {
+    return {
+        id: row.id,
+        sessionId: row.sessionId,
+        userId: row.userId,
+        page: row.page,
+        inputTokens: row.inputTokens,
+        outputTokens: row.outputTokens,
+        cachedTokens: row.cachedTokens,
+        cacheWriteTokens: row.cacheWriteTokens,
+        model: row.model,
+        costUsd: row.costUsd,
+        createdAt: row.createdAt,
+    };
+}
+export class DrizzleSessionUsageRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async insert(record) {
+        const rows = await this.db
+            .insert(sessionUsage)
+            .values({
+            id: randomUUID(),
+            sessionId: record.sessionId,
+            userId: record.userId ?? null,
+            page: record.page ?? null,
+            inputTokens: record.inputTokens,
+            outputTokens: record.outputTokens,
+            cachedTokens: record.cachedTokens,
+            cacheWriteTokens: record.cacheWriteTokens,
+            model: record.model,
+            costUsd: record.costUsd,
+            createdAt: Date.now(),
+        })
+            .returning();
+        return toSessionUsage(rows[0]);
+    }
+    async findBySessionId(sessionId) {
+        const rows = await this.db.select().from(sessionUsage).where(eq(sessionUsage.sessionId, sessionId));
+        return rows.map(toSessionUsage);
+    }
+    async sumCostBySession(sessionId) {
+        const result = await this.db
+            .select({ total: sum(sessionUsage.costUsd) })
+            .from(sessionUsage)
+            .where(eq(sessionUsage.sessionId, sessionId));
+        return Number(result[0]?.total ?? 0);
+    }
+    async sumCostByUser(userId, since) {
+        const result = await this.db
+            .select({ total: sum(sessionUsage.costUsd) })
+            .from(sessionUsage)
+            .where(and(eq(sessionUsage.userId, userId), gt(sessionUsage.createdAt, since)));
+        return Number(result[0]?.total ?? 0);
+    }
+    async aggregateByDay(since) {
+        const result = (await this.db.execute(sql `
+      SELECT
+        to_char(to_timestamp(created_at / 1000.0), 'YYYY-MM-DD') as day,
+        SUM(cost_usd) as total_cost_usd,
+        COUNT(DISTINCT session_id) as session_count
+      FROM session_usage
+      WHERE created_at > ${since}
+      GROUP BY day
+      ORDER BY day DESC
+    `));
+        return result.rows.map((r) => ({
+            day: r.day,
+            totalCostUsd: Number(r.total_cost_usd),
+            sessionCount: Number(r.session_count),
+        }));
+    }
+    async aggregateByPage(since) {
+        const result = (await this.db.execute(sql `
+      SELECT
+        page,
+        SUM(cost_usd) as total_cost_usd,
+        COUNT(*) as call_count,
+        AVG(cost_usd) as avg_cost_usd
+      FROM session_usage
+      WHERE created_at > ${since} AND page IS NOT NULL
+      GROUP BY page
+      ORDER BY total_cost_usd DESC
+    `));
+        return result.rows.map((r) => ({
+            page: r.page,
+            totalCostUsd: Number(r.total_cost_usd),
+            callCount: Number(r.call_count),
+            avgCostUsd: Number(r.avg_cost_usd),
+        }));
+    }
+    async cacheHitRate(since) {
+        const result = (await this.db.execute(sql `
+      SELECT
+        COALESCE(SUM(cached_tokens), 0) as total_cached,
+        COALESCE(SUM(cache_write_tokens), 0) as total_cache_write,
+        COALESCE(SUM(input_tokens), 0) as total_input
+      FROM session_usage
+      WHERE created_at > ${since}
+    `));
+        const cached = Number(result.rows[0]?.total_cached ?? 0);
+        const cacheWrite = Number(result.rows[0]?.total_cache_write ?? 0);
+        const input = Number(result.rows[0]?.total_input ?? 0);
+        const uncached = Math.max(0, input - cached - cacheWrite);
+        return {
+            hitRate: input > 0 ? cached / input : 0,
+            cachedTokens: cached,
+            cacheWriteTokens: cacheWrite,
+            uncachedTokens: uncached,
+        };
+    }
+    async aggregateSessionCost(since) {
+        const result = (await this.db.execute(sql `
+      SELECT
+        COALESCE(SUM(cost_usd), 0) as total_cost_usd,
+        COUNT(DISTINCT session_id) as total_sessions
+      FROM session_usage
+      WHERE created_at > ${since}
+    `));
+        const totalCostUsd = Number(result.rows[0]?.total_cost_usd ?? 0);
+        const totalSessions = Number(result.rows[0]?.total_sessions ?? 0);
+        return {
+            totalCostUsd,
+            totalSessions,
+            avgCostPerSession: totalSessions > 0 ? totalCostUsd / totalSessions : 0,
+        };
+    }
+}

package/dist/inference/session-usage-repository.test.d.ts

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