@wopr-network/platform-core 0.1.0

package/src/metering/types.ts

@@ -0,0 +1,93 @@
+import type { Credit } from "../credits/credit.js";
+
+/** A single metering event emitted by the socket after observing an adapter call. */
+export interface MeterEvent {
+  /** Tenant identifier (who). */
+  tenant: string;
+  /** Upstream cost from the provider (as Credit value object). */
+  cost: Credit;
+  /** What we charge the tenant (cost x multiplier, as Credit value object). */
+  charge: Credit;
+  /** Capability used (embeddings, voice, search, chat, etc.). */
+  capability: string;
+  /** Which adapter fulfilled the request (replicate, deepgram, elevenlabs, etc.). */
+  provider: string;
+  /** Unix epoch ms when the event occurred. */
+  timestamp: number;
+  /** Groups events from one continuous session (voice calls, etc.). */
+  sessionId?: string;
+  /** Session duration in ms (for usage dashboard display). */
+  duration?: number;
+  /** Generic usage measurement — units + unitType (WOP-512). */
+  usage?: {
+    /** Quantity consumed (tokens, seconds, characters, pixels, requests, etc.). */
+    units: number;
+    /** What the units represent. */
+    unitType: string;
+  };
+  /** Pricing tier for billing multiplier lookup (WOP-512). */
+  tier?: "wopr" | "branded" | "byok";
+  /** Provider-specific details (model name, voice ID, resolution, etc.) (WOP-512). */
+  metadata?: Record<string, unknown>;
+}
+
+/** A meter event row as stored in SQLite. */
+export interface MeterEventRow {
+  id: string;
+  tenant: string;
+  cost: number;
+  charge: number;
+  capability: string;
+  provider: string;
+  timestamp: number;
+  session_id: string | null;
+  duration: number | null;
+  /** WOP-512: Generic usage fields */
+  usage_units: number | null;
+  usage_unit_type: string | null;
+  tier: string | null;
+  metadata: string | null; // JSON string
+}
+
+/** Per-tenant usage summary for a given time window. */
+export interface UsageSummary {
+  tenant: string;
+  capability: string;
+  provider: string;
+  /** Number of events aggregated. */
+  event_count: number;
+  /** Sum of upstream costs. */
+  total_cost: number;
+  /** Sum of charges to tenant. */
+  total_charge: number;
+  /** Sum of durations in ms (for session-based capabilities). */
+  total_duration: number;
+  /** Start of the aggregation window (unix epoch ms). */
+  window_start: number;
+  /** End of the aggregation window (unix epoch ms). */
+  window_end: number;
+}
+
+/** A billing period boundary (e.g., hourly). */
+export interface BillingPeriod {
+  /** Start of the billing period (unix epoch ms, inclusive). */
+  start: number;
+  /** End of the billing period (unix epoch ms, exclusive). */
+  end: number;
+}
+
+/** A per-tenant, per-billing-period rolled-up summary row as stored in SQLite. */
+export interface BillingPeriodSummary {
+  id: string;
+  tenant: string;
+  capability: string;
+  provider: string;
+  event_count: number;
+  total_cost: number;
+  total_charge: number;
+  total_duration: number;
+  period_start: number;
+  period_end: number;
+  /** Unix epoch ms when this row was last (re-)computed. */
+  updated_at: number;
+}

package/src/metering/wal.test.ts

@@ -0,0 +1,222 @@
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { Credit } from "../credits/credit.js";
+import { MeterDLQ } from "./dlq.js";
+import type { MeterEvent } from "./types.js";
+import { MeterWAL } from "./wal.js";
+
+const TEST_DIR = "/tmp/wopr-wal-test";
+const TEST_WAL_PATH = `${TEST_DIR}/test-wal.jsonl`;
+const TEST_DLQ_PATH = `${TEST_DIR}/test-dlq.jsonl`;
+
+function makeEvent(overrides: Partial<MeterEvent> = {}): MeterEvent {
+  return {
+    tenant: "tenant-1",
+    cost: Credit.fromDollars(0.001),
+    charge: Credit.fromDollars(0.002),
+    capability: "embeddings",
+    provider: "openai",
+    timestamp: Date.now(),
+    ...overrides,
+  };
+}
+
+describe("MeterWAL", () => {
+  let wal: MeterWAL;
+
+  beforeEach(() => {
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true });
+    }
+    mkdirSync(TEST_DIR, { recursive: true });
+    wal = new MeterWAL(TEST_WAL_PATH);
+  });
+
+  afterEach(() => {
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true });
+    }
+  });
+
+  it("appends events to the WAL", async () => {
+    const event = makeEvent();
+    const result = await wal.append(event);
+
+    expect(result.id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i);
+    expect(result.tenant).toBe("tenant-1");
+    expect(wal.count()).toBe(1);
+  });
+
+  it("preserves event ID if provided", async () => {
+    const event = { ...makeEvent(), id: "custom-id-123" };
+    const result = await wal.append(event);
+
+    expect(result.id).toBe("custom-id-123");
+  });
+
+  it("generates UUID if ID not provided", async () => {
+    const event = makeEvent();
+    const result = await wal.append(event);
+
+    expect(result.id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i);
+  });
+
+  it("readAll returns events in order", async () => {
+    await wal.append(makeEvent({ tenant: "t-1" }));
+    await wal.append(makeEvent({ tenant: "t-2" }));
+    await wal.append(makeEvent({ tenant: "t-3" }));
+
+    const events = wal.readAll();
+    expect(events).toHaveLength(3);
+    expect(events[0].tenant).toBe("t-1");
+    expect(events[1].tenant).toBe("t-2");
+    expect(events[2].tenant).toBe("t-3");
+  });
+
+  it("readAll returns empty array for empty WAL", () => {
+    const events = wal.readAll();
+    expect(events).toEqual([]);
+  });
+
+  it("remove deletes specific events", async () => {
+    const e1 = await wal.append(makeEvent({ tenant: "t-1" }));
+    const e2 = await wal.append(makeEvent({ tenant: "t-2" }));
+    const e3 = await wal.append(makeEvent({ tenant: "t-3" }));
+
+    await wal.remove(new Set([e2.id]));
+
+    const events = wal.readAll();
+    expect(events).toHaveLength(2);
+    expect(events[0].id).toBe(e1.id);
+    expect(events[1].id).toBe(e3.id);
+  });
+
+  it("remove with empty set does nothing", async () => {
+    await wal.append(makeEvent());
+    await wal.remove(new Set());
+
+    expect(wal.count()).toBe(1);
+  });
+
+  it("remove all events clears the WAL file", async () => {
+    const e1 = await wal.append(makeEvent());
+    const e2 = await wal.append(makeEvent());
+
+    await wal.remove(new Set([e1.id, e2.id]));
+
+    expect(wal.isEmpty()).toBe(true);
+    expect(existsSync(TEST_WAL_PATH)).toBe(false);
+  });
+
+  it("clear removes the WAL file", async () => {
+    await wal.append(makeEvent());
+    expect(existsSync(TEST_WAL_PATH)).toBe(true);
+
+    await wal.clear();
+
+    expect(existsSync(TEST_WAL_PATH)).toBe(false);
+    expect(wal.isEmpty()).toBe(true);
+  });
+
+  it("isEmpty returns true for non-existent WAL", () => {
+    expect(wal.isEmpty()).toBe(true);
+  });
+
+  it("isEmpty returns false after append", async () => {
+    await wal.append(makeEvent());
+    expect(wal.isEmpty()).toBe(false);
+  });
+
+  it("count returns 0 for empty WAL", () => {
+    expect(wal.count()).toBe(0);
+  });
+
+  it("handles multiple appends without data loss", async () => {
+    for (let i = 0; i < 100; i++) {
+      await wal.append(makeEvent({ tenant: `t-${i}` }));
+    }
+
+    expect(wal.count()).toBe(100);
+  });
+
+  it("concurrent append during remove does not lose events", async () => {
+    // Seed 3 events
+    const e1 = await wal.append(makeEvent({ tenant: "t-1" }));
+    const e2 = await wal.append(makeEvent({ tenant: "t-2" }));
+    await wal.append(makeEvent({ tenant: "t-3" }));
+
+    // Remove e1 and e2, while concurrently appending e4
+    const removePromise = wal.remove(new Set([e1.id, e2.id]));
+    const appendPromise = wal.append(makeEvent({ tenant: "t-4" }));
+
+    await Promise.all([removePromise, appendPromise]);
+
+    const events = wal.readAll();
+    const tenants = events.map((e) => e.tenant);
+
+    // e3 must survive the remove, e4 must not be lost
+    expect(tenants).toContain("t-3");
+    expect(tenants).toContain("t-4");
+    expect(tenants).not.toContain("t-1");
+    expect(tenants).not.toContain("t-2");
+    expect(events).toHaveLength(2);
+  });
+});
+
+describe("MeterDLQ", () => {
+  let dlq: MeterDLQ;
+
+  beforeEach(() => {
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true });
+    }
+    mkdirSync(TEST_DIR, { recursive: true });
+    dlq = new MeterDLQ(TEST_DLQ_PATH);
+  });
+
+  afterEach(() => {
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true });
+    }
+  });
+
+  it("appends failed events with metadata", () => {
+    const event = { ...makeEvent(), id: "failed-event-1" };
+    dlq.append(event, "Database connection lost", 3);
+
+    const entries = dlq.readAll();
+    expect(entries).toHaveLength(1);
+    expect(entries[0].id).toBe("failed-event-1");
+    expect(entries[0].tenant).toBe("tenant-1");
+    expect(entries[0].dlq_error).toBe("Database connection lost");
+    expect(entries[0].dlq_retries).toBe(3);
+    expect(entries[0].dlq_timestamp).toBeGreaterThan(0);
+  });
+
+  it("readAll returns empty array for empty DLQ", () => {
+    const entries = dlq.readAll();
+    expect(entries).toEqual([]);
+  });
+
+  it("count returns 0 for empty DLQ", () => {
+    expect(dlq.count()).toBe(0);
+  });
+
+  it("count returns correct number of entries", () => {
+    dlq.append({ ...makeEvent(), id: "e1" }, "error1", 3);
+    dlq.append({ ...makeEvent(), id: "e2" }, "error2", 3);
+
+    expect(dlq.count()).toBe(2);
+  });
+
+  it("preserves all DLQ entries across multiple appends", () => {
+    for (let i = 0; i < 10; i++) {
+      dlq.append({ ...makeEvent(), id: `e-${i}` }, `error-${i}`, i + 1);
+    }
+
+    const entries = dlq.readAll();
+    expect(entries).toHaveLength(10);
+    expect(entries[0].dlq_retries).toBe(1);
+    expect(entries[9].dlq_retries).toBe(10);
+  });
+});

package/src/metering/wal.ts

@@ -0,0 +1,139 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import type { MeterEvent } from "./types.js";
+
+/**
+ * Write-Ahead Log for meter events.
+ *
+ * Provides durable, fail-closed event persistence. Events are written
+ * to disk BEFORE being buffered, ensuring no event is lost even if
+ * the process crashes before flush completes.
+ */
+export class MeterWAL {
+  private readonly walPath: string;
+  private lock: Promise<void> = Promise.resolve();
+
+  private async withLock<T>(fn: () => T | Promise<T>): Promise<T> {
+    const prev = this.lock;
+    let resolve!: () => void;
+    this.lock = new Promise<void>((r) => {
+      resolve = r;
+    });
+    try {
+      await prev;
+      return await fn();
+    } finally {
+      resolve();
+    }
+  }
+
+  constructor(walPath: string) {
+    this.walPath = walPath;
+    this.ensureDir();
+  }
+
+  private ensureDir(): void {
+    const dir = dirname(this.walPath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+  }
+
+  /**
+   * Append an event to the WAL. appendFileSync is atomic on POSIX (O_APPEND),
+   * so no mutex is needed here. Returns the event with a generated ID.
+   */
+  append(event: MeterEvent & { id?: string }): MeterEvent & { id: string } {
+    const eventWithId = {
+      ...event,
+      id: event.id ?? crypto.randomUUID(),
+    };
+
+    const line = `${JSON.stringify(eventWithId)}\n`;
+    appendFileSync(this.walPath, line, { encoding: "utf8", flag: "a" });
+
+    return eventWithId;
+  }
+
+  /**
+   * Read all events from the WAL. Returns events in the order they were written.
+   * Skips malformed lines (defensive against incomplete writes).
+   */
+  readAll(): Array<MeterEvent & { id: string }> {
+    if (!existsSync(this.walPath)) {
+      return [];
+    }
+
+    const content = readFileSync(this.walPath, "utf8");
+    if (!content.trim()) {
+      return [];
+    }
+
+    const events: Array<MeterEvent & { id: string }> = [];
+    for (const line of content.trim().split("\n")) {
+      try {
+        events.push(JSON.parse(line) as MeterEvent & { id: string });
+      } catch {
+        // Skip malformed lines (e.g., from incomplete writes).
+      }
+    }
+    return events;
+  }
+
+  /**
+   * Remove specific event IDs from the WAL. This is done by rewriting
+   * the entire file without the specified events. Mutex-guarded.
+   */
+  async remove(eventIds: Set<string>): Promise<void> {
+    return this.withLock(() => {
+      if (!existsSync(this.walPath) || eventIds.size === 0) {
+        return;
+      }
+
+      const events = this.readAll();
+      const filtered = events.filter((e) => !eventIds.has(e.id));
+
+      if (filtered.length === 0) {
+        // All events removed — delete the WAL file.
+        this._clear();
+      } else {
+        // Rewrite the WAL with remaining events.
+        const content = `${filtered.map((e) => JSON.stringify(e)).join("\n")}\n`;
+        writeFileSync(this.walPath, content, { encoding: "utf8" });
+      }
+    });
+  }
+
+  private _clear(): void {
+    if (existsSync(this.walPath)) {
+      unlinkSync(this.walPath);
+    }
+  }
+
+  /**
+   * Clear the entire WAL (typically after successful flush). Mutex-guarded.
+   */
+  async clear(): Promise<void> {
+    return this.withLock(() => {
+      this._clear();
+    });
+  }
+
+  /**
+   * Check if the WAL is empty.
+   */
+  isEmpty(): boolean {
+    if (!existsSync(this.walPath)) {
+      return true;
+    }
+    const content = readFileSync(this.walPath, "utf8");
+    return !content.trim();
+  }
+
+  /**
+   * Get the number of events in the WAL.
+   */
+  count(): number {
+    return this.readAll().length;
+  }
+}

package/src/middleware/csrf.test.ts

@@ -0,0 +1,178 @@
+import { Hono } from "hono";
+import { describe, expect, it } from "vitest";
+import type { SessionAuthEnv } from "../auth/middleware.js";
+import { csrfProtection, validateCsrfOrigin } from "./csrf.js";
+
+// ---------------------------------------------------------------------------
+// validateCsrfOrigin unit tests
+// ---------------------------------------------------------------------------
+
+describe("validateCsrfOrigin", () => {
+  function makeHeaders(headers: Record<string, string>): Headers {
+    return new Headers(headers);
+  }
+
+  it("returns true when Origin matches allowed origin", () => {
+    const result = validateCsrfOrigin(makeHeaders({ origin: "https://app.example.com" }), ["https://app.example.com"]);
+    expect(result).toBe(true);
+  });
+
+  it("returns true when Origin matches one of multiple allowed origins", () => {
+    const result = validateCsrfOrigin(makeHeaders({ origin: "https://staging.example.com" }), [
+      "https://app.example.com",
+      "https://staging.example.com",
+    ]);
+    expect(result).toBe(true);
+  });
+
+  it("returns false when Origin does not match any allowed origin", () => {
+    const result = validateCsrfOrigin(makeHeaders({ origin: "https://evil.com" }), ["https://app.example.com"]);
+    expect(result).toBe(false);
+  });
+
+  it("falls back to Referer when Origin is absent", () => {
+    const result = validateCsrfOrigin(makeHeaders({ referer: "https://app.example.com/dashboard" }), [
+      "https://app.example.com",
+    ]);
+    expect(result).toBe(true);
+  });
+
+  it("returns false when neither Origin nor Referer is present", () => {
+    const result = validateCsrfOrigin(makeHeaders({}), ["https://app.example.com"]);
+    expect(result).toBe(false);
+  });
+
+  it("returns false for malformed Referer URL", () => {
+    const result = validateCsrfOrigin(makeHeaders({ referer: "not-a-url" }), ["https://app.example.com"]);
+    expect(result).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// csrfProtection middleware integration tests
+// ---------------------------------------------------------------------------
+
+describe("csrfProtection middleware", () => {
+  const exemptPaths = [
+    "/api/auth/*",
+    "/api/billing/webhook",
+    "/api/billing/crypto/*",
+    "/internal/*",
+    "/health*",
+    "/auth/*",
+  ];
+
+  function createApp(allowedOrigins: string[]) {
+    const app = new Hono<SessionAuthEnv>();
+    // Simulate session user being set so CSRF validation logic actually runs
+    app.use("/*", async (c, next) => {
+      c.set("user", { id: "test-user", roles: ["user"] });
+      return next();
+    });
+    app.use("/*", csrfProtection({ allowedOrigins, exemptPaths }));
+    app.post("/api/fleet/bots", (c) => c.json({ ok: true }));
+    app.put("/api/billing/checkout", (c) => c.json({ ok: true }));
+    app.delete("/fleet/bots/123", (c) => c.json({ ok: true }));
+    app.get("/api/fleet/bots", (c) => c.json({ ok: true }));
+    app.post("/api/auth/sign-in/email", (c) => c.json({ ok: true }));
+    app.post("/api/billing/webhook", (c) => c.json({ ok: true }));
+    app.post("/internal/nodes/register", (c) => c.json({ ok: true }));
+    app.post("/health", (c) => c.json({ ok: true }));
+    app.post("/trpc/fleet.create", (c) => c.json({ ok: true }));
+    return app;
+  }
+
+  const origins = ["https://app.example.com"];
+
+  it("blocks POST without Origin header", async () => {
+    const app = createApp(origins);
+    const res = await app.request("/api/fleet/bots", { method: "POST" });
+    expect(res.status).toBe(403);
+    const body = await res.json();
+    expect(body.error).toBe("CSRF validation failed");
+  });
+
+  it("blocks POST with wrong Origin", async () => {
+    const app = createApp(origins);
+    const res = await app.request("/api/fleet/bots", {
+      method: "POST",
+      headers: { origin: "https://evil.com" },
+    });
+    expect(res.status).toBe(403);
+  });
+
+  it("allows POST with correct Origin", async () => {
+    const app = createApp(origins);
+    const res = await app.request("/api/fleet/bots", {
+      method: "POST",
+      headers: { origin: "https://app.example.com" },
+    });
+    expect(res.status).toBe(200);
+  });
+
+  it("allows GET requests without Origin", async () => {
+    const app = createApp(origins);
+    const res = await app.request("/api/fleet/bots", { method: "GET" });
+    expect(res.status).toBe(200);
+  });
+
+  it("blocks PUT without Origin", async () => {
+    const app = createApp(origins);
+    const res = await app.request("/api/billing/checkout", { method: "PUT" });
+    expect(res.status).toBe(403);
+  });
+
+  it("blocks DELETE without Origin", async () => {
+    const app = createApp(origins);
+    const res = await app.request("/fleet/bots/123", { method: "DELETE" });
+    expect(res.status).toBe(403);
+  });
+
+  it("exempts /api/auth/* routes", async () => {
+    const app = createApp(origins);
+    const res = await app.request("/api/auth/sign-in/email", { method: "POST" });
+    expect(res.status).toBe(200);
+  });
+
+  it("exempts /api/billing/webhook", async () => {
+    const app = createApp(origins);
+    const res = await app.request("/api/billing/webhook", { method: "POST" });
+    expect(res.status).toBe(200);
+  });
+
+  it("exempts /internal/* routes", async () => {
+    const app = createApp(origins);
+    const res = await app.request("/internal/nodes/register", { method: "POST" });
+    expect(res.status).toBe(200);
+  });
+
+  it("exempts /health routes", async () => {
+    const app = createApp(origins);
+    const res = await app.request("/health", { method: "POST" });
+    expect(res.status).toBe(200);
+  });
+
+  it("skips CSRF check when Authorization Bearer header is present", async () => {
+    const app = createApp(origins);
+    const res = await app.request("/api/fleet/bots", {
+      method: "POST",
+      headers: { authorization: "Bearer some-token" },
+    });
+    expect(res.status).toBe(200);
+  });
+
+  it("protects /trpc/* mutation routes", async () => {
+    const app = createApp(origins);
+    const res = await app.request("/trpc/fleet.create", { method: "POST" });
+    expect(res.status).toBe(403);
+  });
+
+  it("allows /trpc/* with correct Origin", async () => {
+    const app = createApp(origins);
+    const res = await app.request("/trpc/fleet.create", {
+      method: "POST",
+      headers: { origin: "https://app.example.com" },
+    });
+    expect(res.status).toBe(200);
+  });
+});