@crewhaus/gateway-server 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/gateway-server",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "description": "Bun.serve daemon speaking gateway-protocol — JWT auth + per-tenant routing + budget enforcement",
   "main": "src/index.ts",
@@ -12,16 +12,17 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/audit-log": "0.1.1",
-    "@crewhaus/errors": "0.1.1",
-    "@crewhaus/gateway-protocol": "0.1.1",
-    "@crewhaus/tenancy": "0.1.1"
+    "@crewhaus/durable-state": "0.1.3",
+    "@crewhaus/audit-log": "0.1.3",
+    "@crewhaus/errors": "0.1.3",
+    "@crewhaus/gateway-protocol": "0.1.3",
+    "@crewhaus/tenancy": "0.1.3"
   },
   "license": "Apache-2.0",
   "author": {
     "name": "Max Meier",
-    "email": "max@studiomax.io",
-    "url": "https://studiomax.io"
+    "email": "max@crewhaus.ai",
+    "url": "https://crewhaus.ai"
   },
   "repository": {
     "type": "git",
@@ -33,12 +34,7 @@
     "url": "https://github.com/crewhaus/factory/issues"
   },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
-  "files": [
-    "src",
-    "README.md",
-    "LICENSE",
-    "NOTICE"
-  ]
+  "files": ["src", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -1,9 +1,45 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { createHmac } from "node:crypto";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { SqliteBudgetStore } from "@crewhaus/durable-state";
+import { ErrorCode } from "@crewhaus/gateway-protocol";
 import { type Tenant, buildTenant } from "@crewhaus/tenancy";
-import { createGatewayServer, signJwt, verifyJwt } from "./index";
+import {
+  GatewayServerError,
+  PROTOCOL_VERSION,
+  createGatewayServer,
+  signJwt,
+  statusFor,
+  verifyJwt,
+} from "./index";
+
+/**
+ * Forge a token with an arbitrary header + claims (signed with `secret`) so
+ * we can exercise rejection paths `signJwt` would never produce — e.g. an
+ * `alg: none` header or a body with no `exp`.
+ */
+function forgeToken(
+  header: Record<string, unknown>,
+  claims: Record<string, unknown>,
+  secret: string,
+): string {
+  const b64url = (s: string): string =>
+    Buffer.from(s, "utf8")
+      .toString("base64")
+      .replace(/\+/g, "-")
+      .replace(/\//g, "_")
+      .replace(/=+$/, "");
+  const data = `${b64url(JSON.stringify(header))}.${b64url(JSON.stringify(claims))}`;
+  const sig = createHmac("sha256", secret)
+    .update(data)
+    .digest("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+  return `${data}.${sig}`;
+}
 
 let tmp: string;
 
@@ -61,6 +97,46 @@ describe("JWT round-trip", () => {
     const token = signJwt({ tenant_id: "../etc" }, SECRET);
     expect(() => verifyJwt(token, SECRET)).toThrow(/invalid tenantId/);
   });
+
+  test("valid short-lived HS256 token verifies", () => {
+    const iat = Math.floor(Date.now() / 1000);
+    const token = signJwt({ tenant_id: "tenant-a", iat, exp: iat + 300 }, SECRET);
+    const claims = verifyJwt(token, SECRET);
+    expect(claims.tenant_id).toBe("tenant-a");
+    expect(claims.exp).toBe(iat + 300);
+  });
+
+  test("rejects token with no exp claim (CWE-613)", () => {
+    // Forge directly — `signJwt` always injects an exp.
+    const token = forgeToken({ alg: "HS256", typ: "JWT" }, { tenant_id: "tenant-a" }, SECRET);
+    expect(() => verifyJwt(token, SECRET)).toThrow(/missing exp/);
+  });
+
+  test("rejects token whose header alg is not HS256", () => {
+    const iat = Math.floor(Date.now() / 1000);
+    const token = forgeToken(
+      { alg: "none", typ: "JWT" },
+      { tenant_id: "tenant-a", iat, exp: iat + 300 },
+      SECRET,
+    );
+    expect(() => verifyJwt(token, SECRET)).toThrow(/unsupported alg/);
+  });
+
+  test("rejects token whose header typ is not JWT", () => {
+    const iat = Math.floor(Date.now() / 1000);
+    const token = forgeToken(
+      { alg: "HS256", typ: "JWE" },
+      { tenant_id: "tenant-a", iat, exp: iat + 300 },
+      SECRET,
+    );
+    expect(() => verifyJwt(token, SECRET)).toThrow(/unsupported typ/);
+  });
+
+  test("rejects a token whose lifetime exceeds the 24h ceiling", () => {
+    const iat = Math.floor(Date.now() / 1000);
+    const token = signJwt({ tenant_id: "tenant-a", iat, exp: iat + 25 * 60 * 60 }, SECRET);
+    expect(() => verifyJwt(token, SECRET)).toThrow(/lifetime exceeds maximum/);
+  });
 });
 
 describe("server.handle (T2/T3 contract)", () => {
@@ -137,9 +213,9 @@ describe("server.handle (T2/T3 contract)", () => {
 describe("budget enforcement", () => {
   test("recordUsage increments cumulative usage", async () => {
     const { server } = makeServer();
-    server.recordUsage("tenant-a", { input: 1000, output: 200 });
-    server.recordUsage("tenant-a", { input: 500, output: 100 });
-    expect(server.usage("tenant-a")).toEqual({ input: 1500, output: 300 });
+    await server.recordUsage("tenant-a", { input: 1000, output: 200 });
+    await server.recordUsage("tenant-a", { input: 500, output: 100 });
+    expect(await server.usage("tenant-a")).toEqual({ input: 1500, output: 300 });
   });
 
   test("exhausted input budget → 429 budget_exceeded", async () => {
@@ -151,7 +227,7 @@ describe("budget enforcement", () => {
       handler: async () => ({ ok: true }),
       tenantOverrides: { "tenant-a": tinyA },
     });
-    server.recordUsage("tenant-a", { input: 999, output: 0 });
+    await server.recordUsage("tenant-a", { input: 999, output: 0 });
     const token = signJwt({ tenant_id: "tenant-a" }, SECRET);
     const res = await server.handle({
       bearer: token,
@@ -166,6 +242,110 @@ describe("budget enforcement", () => {
       error: { code: "budget_exceeded", message: expect.stringMatching(/input tokens/) },
     });
   });
+
+  // SECURITY: without an in-flight reservation, concurrent requests all pass
+  // checkBudget (which only sees recorded usage = 0) before any records, so a
+  // burst blows past the cap. The reservation counts each in-flight request.
+  test("in-flight reservation bounds a concurrent burst (TOCTOU)", async () => {
+    const tenantA = buildTenant("tenant-a", { tenantsRoot: tmp });
+    const tinyA: Tenant = { ...tenantA, budget: { maxInputTokens: 100, maxOutputTokens: 100 } };
+    const server = createGatewayServer({
+      jwtSecret: SECRET,
+      tenantsRoot: tmp,
+      handler: async () => ({ ok: true }),
+      tenantOverrides: { "tenant-a": tinyA },
+      estimateUsage: () => ({ input: 60, output: 0 }),
+    });
+    const token = signJwt({ tenant_id: "tenant-a" }, SECRET);
+    const req = (id: string) =>
+      server.handle({
+        bearer: token,
+        body: {
+          protocol: "crewhaus.v1",
+          id,
+          method: "runs.create",
+          params: { spec: "s", input: "" },
+        },
+      });
+    // Three concurrent requests @ 60 est. tokens vs a 100-token budget: with
+    // recorded usage 0, all three would pass the old check; the cumulative
+    // reservation (60+60+60) blocks the 2nd and 3rd.
+    const results = await Promise.all([req("1"), req("2"), req("3")]);
+    const rejected = results.filter(
+      (r) =>
+        typeof r === "object" &&
+        r !== null &&
+        "error" in r &&
+        (r as { error: { code: string } }).error.code === "budget_exceeded",
+    );
+    expect(rejected.length).toBeGreaterThanOrEqual(2);
+  });
+
+  // SECURITY (audit R3): two gateway "replicas" sharing a durable budget
+  // store enforce ONE budget. Before the seam each replica had its own
+  // in-memory maps, multiplying every tenant budget by the replica count.
+  test("replicas sharing a SqliteBudgetStore enforce a single budget", async () => {
+    const tenantA = buildTenant("tenant-a", { tenantsRoot: tmp });
+    const tinyA: Tenant = { ...tenantA, budget: { maxInputTokens: 100, maxOutputTokens: 100 } };
+    const storeFile = join(tmp, "budget.db");
+    const mk = () =>
+      createGatewayServer({
+        jwtSecret: SECRET,
+        tenantsRoot: tmp,
+        handler: async () => ({ ok: true }),
+        tenantOverrides: { "tenant-a": tinyA },
+        estimateUsage: () => ({ input: 60, output: 0 }),
+        budgetStore: new SqliteBudgetStore({ path: storeFile }),
+      });
+    const replicaA = mk();
+    const replicaB = mk();
+    // Usage recorded through replica A is visible to replica B...
+    await replicaA.recordUsage("tenant-a", { input: 70, output: 0 });
+    expect(await replicaB.usage("tenant-a")).toEqual({ input: 70, output: 0 });
+    // ...and bounds replica B's requests (70 recorded + 60 estimate >= 100).
+    const token = signJwt({ tenant_id: "tenant-a" }, SECRET);
+    const res = await replicaB.handle({
+      bearer: token,
+      body: {
+        protocol: "crewhaus.v1",
+        id: "1",
+        method: "runs.create",
+        params: { spec: "s", input: "" },
+      },
+    });
+    expect(res).toMatchObject({
+      error: { code: "budget_exceeded", message: expect.stringMatching(/input tokens 130\/100/) },
+    });
+  });
+
+  test("reservation is released after each request (sequential requests aren't starved)", async () => {
+    const tenantA = buildTenant("tenant-a", { tenantsRoot: tmp });
+    const tinyA: Tenant = { ...tenantA, budget: { maxInputTokens: 100, maxOutputTokens: 100 } };
+    const server = createGatewayServer({
+      jwtSecret: SECRET,
+      tenantsRoot: tmp,
+      handler: async () => ({ ok: true }),
+      tenantOverrides: { "tenant-a": tinyA },
+      estimateUsage: () => ({ input: 60, output: 0 }),
+    });
+    const token = signJwt({ tenant_id: "tenant-a" }, SECRET);
+    const req = () =>
+      server.handle({
+        bearer: token,
+        body: {
+          protocol: "crewhaus.v1",
+          id: "x",
+          method: "runs.create",
+          params: { spec: "s", input: "" },
+        },
+      });
+    // Run-to-completion releases the 60-token reservation, so the next request
+    // (recorded usage still 0 here) reserves freshly and succeeds.
+    const a = await req();
+    const b = await req();
+    expect(a).not.toMatchObject({ error: { code: "budget_exceeded" } });
+    expect(b).not.toMatchObject({ error: { code: "budget_exceeded" } });
+  });
 });
 
 describe("tenancy isolation", () => {
@@ -218,4 +398,418 @@ describe("audit log", () => {
     for await (const r of log.read()) rows.push(r);
     expect(rows.length).toBe(1);
   });
+
+  test("the audit row carries method, tenantId and the token's sub claim", async () => {
+    const { server, tenantA } = makeServer();
+    const token = signJwt({ tenant_id: "tenant-a", sub: "user-42" }, SECRET);
+    await server.handle({
+      bearer: token,
+      body: {
+        protocol: "crewhaus.v1",
+        id: "1",
+        method: "runs.create",
+        params: { spec: "s", input: "" },
+      },
+    });
+    const log = await server.getAuditLog(tenantA);
+    const rows: Array<{ payload: { method: string; tenantId: string; sub?: string } }> = [];
+    for await (const r of log.read())
+      rows.push(r as { payload: { method: string; tenantId: string; sub?: string } });
+    expect(rows[0]?.payload).toEqual({
+      method: "runs.create",
+      tenantId: "tenant-a",
+      sub: "user-42",
+    });
+  });
+
+  test("getAuditLog memoises — the same log instance is returned per tenant", async () => {
+    const { server, tenantA } = makeServer();
+    const first = await server.getAuditLog(tenantA);
+    const second = await server.getAuditLog(tenantA);
+    expect(second).toBe(first);
+  });
+});
+
+describe("verifyJwt — iat edge cases (forged tokens)", () => {
+  test("rejects a token whose iat is in the future", () => {
+    const future = Math.floor((Date.now() + 10 * 60_000) / 1000);
+    const token = forgeToken(
+      { alg: "HS256", typ: "JWT" },
+      { tenant_id: "tenant-a", iat: future, exp: future + 60 },
+      SECRET,
+    );
+    expect(() => verifyJwt(token, SECRET)).toThrow(/iat in the future/);
+  });
+
+  test("rejects a token whose iat is non-numeric", () => {
+    const iat = Math.floor(Date.now() / 1000);
+    const token = forgeToken(
+      { alg: "HS256", typ: "JWT" },
+      { tenant_id: "tenant-a", iat: "soon", exp: iat + 300 },
+      SECRET,
+    );
+    expect(() => verifyJwt(token, SECRET)).toThrow(/malformed iat/);
+  });
+
+  test("rejects a body with a missing tenant_id claim", () => {
+    const iat = Math.floor(Date.now() / 1000);
+    const token = forgeToken({ alg: "HS256", typ: "JWT" }, { iat, exp: iat + 300 }, SECRET);
+    expect(() => verifyJwt(token, SECRET)).toThrow(/missing tenant_id/);
+  });
+
+  test("rejects a token whose body is not valid JSON", () => {
+    // Header is valid; body decodes to non-JSON bytes; signature matches that body.
+    const b64url = (s: string): string =>
+      Buffer.from(s, "utf8")
+        .toString("base64")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+    const headerB64 = b64url(JSON.stringify({ alg: "HS256", typ: "JWT" }));
+    const bodyB64 = b64url("this-is-not-json{");
+    const data = `${headerB64}.${bodyB64}`;
+    const sig = createHmac("sha256", SECRET)
+      .update(data)
+      .digest("base64")
+      .replace(/\+/g, "-")
+      .replace(/\//g, "_")
+      .replace(/=+$/, "");
+    expect(() => verifyJwt(`${data}.${sig}`, SECRET)).toThrow(/malformed JWT body/);
+  });
+
+  test("rejects a token whose header is not valid JSON", () => {
+    const b64url = (s: string): string =>
+      Buffer.from(s, "utf8")
+        .toString("base64")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+    const headerB64 = b64url("not-json{");
+    const iat = Math.floor(Date.now() / 1000);
+    const bodyB64 = b64url(JSON.stringify({ tenant_id: "tenant-a", iat, exp: iat + 300 }));
+    const data = `${headerB64}.${bodyB64}`;
+    const sig = createHmac("sha256", SECRET)
+      .update(data)
+      .digest("base64")
+      .replace(/\+/g, "-")
+      .replace(/\//g, "_")
+      .replace(/=+$/, "");
+    expect(() => verifyJwt(`${data}.${sig}`, SECRET)).toThrow(/malformed JWT header/);
+  });
+});
+
+describe("createGatewayServer — injected clock + default tenant building", () => {
+  test("honours an injected now() for expiry checks", async () => {
+    // Token expires at T+300s. Pin the clock past expiry; the request must 401.
+    const iat = 1_000_000;
+    const token = signJwt({ tenant_id: "tenant-a", iat, exp: iat + 300 }, SECRET);
+    const tenantA = buildTenant("tenant-a", { tenantsRoot: tmp });
+    const server = createGatewayServer({
+      jwtSecret: SECRET,
+      tenantsRoot: tmp,
+      handler: async () => ({ ok: true }),
+      tenantOverrides: { "tenant-a": tenantA },
+      now: () => (iat + 10_000) * 1000,
+    });
+    const res = await server.handle({
+      bearer: token,
+      body: {
+        protocol: "crewhaus.v1",
+        id: "1",
+        method: "runs.create",
+        params: { spec: "s", input: "" },
+      },
+    });
+    expect(res).toMatchObject({
+      error: { code: "unauthorized", message: expect.stringMatching(/expired/) },
+    });
+  });
+
+  test("builds a tenant from tenantsRoot when no override is supplied", async () => {
+    // No tenantOverrides → tenantFor() falls through to buildTenant(tenantsRoot).
+    let seenRoot: string | undefined;
+    const server = createGatewayServer({
+      jwtSecret: SECRET,
+      tenantsRoot: tmp,
+      handler: async ({ tenant }) => {
+        seenRoot = tenant.auditRoot;
+        return { ok: true };
+      },
+    });
+    const token = signJwt({ tenant_id: "tenant-a" }, SECRET);
+    const res = await server.handle({
+      bearer: token,
+      body: {
+        protocol: "crewhaus.v1",
+        id: "1",
+        method: "runs.create",
+        params: { spec: "s", input: "" },
+      },
+    });
+    expect(res).toMatchObject({ protocol: "crewhaus.v1", id: "1" });
+    expect(seenRoot?.startsWith(tmp)).toBe(true);
+  });
+
+  test("builds a tenant with the package default root when tenantsRoot is omitted", async () => {
+    // Neither override nor tenantsRoot → buildTenant() uses its own default root.
+    // We never write to disk here: budget is exhausted first so the handler/audit
+    // never runs, keeping the test free of real filesystem side effects.
+    const server = createGatewayServer({
+      jwtSecret: SECRET,
+      handler: async () => ({ ok: true }),
+    });
+    await server.recordUsage("tenant-a", { input: 10_000_000, output: 0 });
+    const token = signJwt({ tenant_id: "tenant-a" }, SECRET);
+    const res = await server.handle({
+      bearer: token,
+      body: {
+        protocol: "crewhaus.v1",
+        id: "1",
+        method: "runs.create",
+        params: { spec: "s", input: "" },
+      },
+    });
+    expect(res).toMatchObject({ error: { code: "budget_exceeded" } });
+  });
+});
+
+describe("budget enforcement — output dimension + internal errors", () => {
+  test("exhausted output budget → 429 budget_exceeded", async () => {
+    const tenantA = buildTenant("tenant-a", { tenantsRoot: tmp });
+    const tinyA: Tenant = { ...tenantA, budget: { maxInputTokens: 1000, maxOutputTokens: 100 } };
+    const server = createGatewayServer({
+      jwtSecret: SECRET,
+      tenantsRoot: tmp,
+      handler: async () => ({ ok: true }),
+      tenantOverrides: { "tenant-a": tinyA },
+    });
+    await server.recordUsage("tenant-a", { input: 0, output: 100 });
+    const token = signJwt({ tenant_id: "tenant-a" }, SECRET);
+    const res = await server.handle({
+      bearer: token,
+      body: {
+        protocol: "crewhaus.v1",
+        id: "1",
+        method: "runs.create",
+        params: { spec: "s", input: "" },
+      },
+    });
+    expect(res).toMatchObject({
+      error: { code: "budget_exceeded", message: expect.stringMatching(/output tokens/) },
+    });
+  });
+
+  test("a handler that rejects surfaces as 500 internal_error", async () => {
+    const { server } = makeServer(async () => {
+      throw new Error("handler boom");
+    });
+    const token = signJwt({ tenant_id: "tenant-a" }, SECRET);
+    const res = await server.handle({
+      bearer: token,
+      body: {
+        protocol: "crewhaus.v1",
+        id: "1",
+        method: "runs.create",
+        params: { spec: "s", input: "" },
+      },
+    });
+    expect(res).toMatchObject({
+      error: { code: "internal_error", message: "handler boom" },
+    });
+  });
+
+  test("a handler that throws a non-Error value is stringified into internal_error", async () => {
+    // Reject with a raw (non-Error) string to exercise the server's
+    // `String(err)` branch. A plain rejected promise (rather than an `async`
+    // body that `throw`s a string literal) keeps the rejection reason exactly
+    // "raw string failure" without tripping useAwait / noThrowLiteral.
+    const { server } = makeServer(() => Promise.reject("raw string failure"));
+    const token = signJwt({ tenant_id: "tenant-a" }, SECRET);
+    const res = await server.handle({
+      bearer: token,
+      body: {
+        protocol: "crewhaus.v1",
+        id: "1",
+        method: "runs.create",
+        params: { spec: "s", input: "" },
+      },
+    });
+    expect(res).toMatchObject({
+      error: { code: "internal_error", message: "raw string failure" },
+    });
+  });
+
+  test("a GatewayServerError that is neither budget nor auth maps to 400 bad_request", async () => {
+    const { server } = makeServer(async () => {
+      throw new GatewayServerError("some other config problem");
+    });
+    const token = signJwt({ tenant_id: "tenant-a" }, SECRET);
+    const res = await server.handle({
+      bearer: token,
+      body: {
+        protocol: "crewhaus.v1",
+        id: "1",
+        method: "runs.create",
+        params: { spec: "s", input: "" },
+      },
+    });
+    expect(res).toMatchObject({
+      error: { code: "bad_request", message: "some other config problem" },
+    });
+  });
+});
+
+describe("statusFor — exhaustive wire code → HTTP status map", () => {
+  test("maps every standard ErrorCode and falls back to 200", () => {
+    expect(statusFor(ErrorCode.Unauthorized)).toBe(401);
+    expect(statusFor(ErrorCode.Forbidden)).toBe(403);
+    expect(statusFor(ErrorCode.NotFound)).toBe(404);
+    expect(statusFor(ErrorCode.BadRequest)).toBe(400);
+    expect(statusFor(ErrorCode.BudgetExceeded)).toBe(429);
+    expect(statusFor(ErrorCode.InternalError)).toBe(500);
+    // Unknown / empty codes fall through to the 200 default.
+    expect(statusFor("totally_unknown_code")).toBe(200);
+    expect(statusFor("")).toBe(200);
+  });
+});
+
+describe("listen — real Bun.serve HTTP surface (loopback)", () => {
+  /** Start the daemon on an ephemeral loopback port and return a teardown. */
+  async function withHttp(
+    server: ReturnType<typeof createGatewayServer>,
+    fn: (base: string) => Promise<void>,
+  ): Promise<void> {
+    const { port, close } = await server.listen(0);
+    expect(typeof port).toBe("number");
+    expect(port).toBeGreaterThan(0);
+    try {
+      await fn(`http://127.0.0.1:${port}`);
+    } finally {
+      await close();
+    }
+  }
+
+  test("authenticated POST returns 200 with the success envelope", async () => {
+    const { server } = makeServer(async ({ tenant }) => ({
+      runId: "run_h",
+      sessionId: "sess_h",
+      tenantId: tenant.id,
+    }));
+    const token = signJwt({ tenant_id: "tenant-a" }, SECRET);
+    await withHttp(server, async (base) => {
+      const res = await fetch(base, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+        body: JSON.stringify({
+          protocol: PROTOCOL_VERSION,
+          id: "1",
+          method: "runs.create",
+          params: { spec: "s", input: "hi" },
+        }),
+      });
+      expect(res.status).toBe(200);
+      expect(await res.json()).toEqual({
+        protocol: PROTOCOL_VERSION,
+        id: "1",
+        result: { runId: "run_h", sessionId: "sess_h", tenantId: "tenant-a" },
+      });
+    });
+  });
+
+  test("missing Authorization header returns 401", async () => {
+    const { server } = makeServer();
+    await withHttp(server, async (base) => {
+      const res = await fetch(base, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          protocol: PROTOCOL_VERSION,
+          id: "1",
+          method: "runs.create",
+          params: { spec: "s", input: "" },
+        }),
+      });
+      expect(res.status).toBe(401);
+      expect(await res.json()).toMatchObject({ error: { code: "unauthorized" } });
+    });
+  });
+
+  test("a non-Bearer Authorization scheme is treated as no token (401)", async () => {
+    const { server } = makeServer();
+    await withHttp(server, async (base) => {
+      const res = await fetch(base, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: "Basic abc123" },
+        body: JSON.stringify({
+          protocol: PROTOCOL_VERSION,
+          id: "1",
+          method: "runs.create",
+          params: { spec: "s", input: "" },
+        }),
+      });
+      expect(res.status).toBe(401);
+    });
+  });
+
+  test("a non-JSON body returns 400 before auth is even consulted", async () => {
+    const { server } = makeServer();
+    await withHttp(server, async (base) => {
+      const res = await fetch(base, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: "Bearer whatever" },
+        body: "}{ not json",
+      });
+      expect(res.status).toBe(400);
+      expect(await res.json()).toMatchObject({
+        error: { code: "bad_request", message: expect.stringMatching(/must be JSON/) },
+      });
+    });
+  });
+
+  test("an over-budget request returns HTTP 429", async () => {
+    const tenantA = buildTenant("tenant-a", { tenantsRoot: tmp });
+    const tinyA: Tenant = { ...tenantA, budget: { maxInputTokens: 50, maxOutputTokens: 50 } };
+    const server = createGatewayServer({
+      jwtSecret: SECRET,
+      tenantsRoot: tmp,
+      handler: async () => ({ ok: true }),
+      tenantOverrides: { "tenant-a": tinyA },
+    });
+    await server.recordUsage("tenant-a", { input: 50, output: 0 });
+    const token = signJwt({ tenant_id: "tenant-a" }, SECRET);
+    await withHttp(server, async (base) => {
+      const res = await fetch(base, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+        body: JSON.stringify({
+          protocol: PROTOCOL_VERSION,
+          id: "1",
+          method: "runs.create",
+          params: { spec: "s", input: "" },
+        }),
+      });
+      expect(res.status).toBe(429);
+    });
+  });
+
+  test("binds on an explicit host argument", async () => {
+    const { server } = makeServer();
+    const { port, close } = await server.listen(0, "127.0.0.1");
+    try {
+      const token = signJwt({ tenant_id: "tenant-a" }, SECRET);
+      const res = await fetch(`http://127.0.0.1:${port}`, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+        body: JSON.stringify({
+          protocol: PROTOCOL_VERSION,
+          id: "1",
+          method: "runs.create",
+          params: { spec: "s", input: "" },
+        }),
+      });
+      expect(res.status).toBe(200);
+    } finally {
+      await close();
+    }
+  });
 });

package/src/index.ts

@@ -26,6 +26,7 @@
 
 import { createHmac, timingSafeEqual } from "node:crypto";
 import { type AppendInput, type AuditLog, openAuditLog } from "@crewhaus/audit-log";
+import { type BudgetStore, InMemoryBudgetStore } from "@crewhaus/durable-state";
 import { CrewhausError } from "@crewhaus/errors";
 import {
   ErrorCode,
@@ -56,6 +57,20 @@ export type JwtClaims = {
 // HS256 JWT — minimal verifier and signer (no external deps).
 // ---------------------------------------------------------------------------
 
+/** Only HS256 is accepted — guards against `alg` confusion (e.g. `none`). */
+const JWT_ALG = "HS256";
+/** Only compact JWS bearer tokens are accepted. */
+const JWT_TYP = "JWT";
+/** Reject tokens whose lifetime (`exp - iat`) exceeds this when `iat` is present. */
+const MAX_JWT_LIFETIME_SECONDS = 24 * 60 * 60;
+/** Allowed clock skew when checking `iat` is not in the future. */
+const IAT_SKEW_MS = 60_000;
+
+type JwtHeader = {
+  readonly alg?: string;
+  readonly typ?: string;
+};
+
 function b64urlEncode(input: Uint8Array | string): string {
   const buf = typeof input === "string" ? Buffer.from(input, "utf8") : Buffer.from(input);
   return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
@@ -67,8 +82,13 @@ function b64urlDecode(input: string): Buffer {
 }
 
 export function signJwt(claims: JwtClaims, secret: string): string {
-  const header = b64urlEncode(JSON.stringify({ alg: "HS256", typ: "JWT" }));
-  const body = b64urlEncode(JSON.stringify(claims));
+  // Convenience minter (tests + smoke only). Default `iat`/`exp` so emitted
+  // tokens satisfy the verifier's mandatory-`exp` + bounded-lifetime contract;
+  // production tokens come from an external IDP.
+  const iat = claims.iat ?? Math.floor(Date.now() / 1000);
+  const exp = claims.exp ?? iat + 60 * 60;
+  const header = b64urlEncode(JSON.stringify({ alg: JWT_ALG, typ: JWT_TYP }));
+  const body = b64urlEncode(JSON.stringify({ ...claims, iat, exp }));
   const data = `${header}.${body}`;
   const sig = createHmac("sha256", secret).update(data).digest();
   return `${data}.${b64urlEncode(sig)}`;
@@ -80,6 +100,20 @@ export function verifyJwt(token: string, secret: string, now: () => number = Dat
     throw new GatewayServerError("malformed JWT — expected 3 segments");
   }
   const [headerB64, bodyB64, sigB64] = parts as [string, string, string];
+  // Validate the header (alg/typ) BEFORE spending an HMAC — rejects
+  // `alg: none` / algorithm-confusion tokens up front.
+  let header: JwtHeader;
+  try {
+    header = JSON.parse(b64urlDecode(headerB64).toString("utf8")) as JwtHeader;
+  } catch (err) {
+    throw new GatewayServerError("malformed JWT header", err);
+  }
+  if (header.alg !== JWT_ALG) {
+    throw new GatewayServerError(`JWT unsupported alg — expected ${JWT_ALG}`);
+  }
+  if (header.typ !== JWT_TYP) {
+    throw new GatewayServerError(`JWT unsupported typ — expected ${JWT_TYP}`);
+  }
   const data = `${headerB64}.${bodyB64}`;
   const expected = createHmac("sha256", secret).update(data).digest();
   let actual: Buffer;
@@ -105,11 +139,26 @@ export function verifyJwt(token: string, secret: string, now: () => number = Dat
   }
   validateTenantId(claims.tenant_id);
   const nowMs = now();
-  if (claims.exp !== undefined && claims.exp * 1000 < nowMs) {
+  // `exp` is mandatory — an absent (or non-numeric) `exp` must not mean
+  // "never expires" (CWE-613).
+  if (typeof claims.exp !== "number" || !Number.isFinite(claims.exp)) {
+    throw new GatewayServerError("JWT missing exp claim");
+  }
+  if (claims.exp * 1000 <= nowMs) {
     throw new GatewayServerError("JWT expired");
   }
-  if (claims.iat !== undefined && claims.iat * 1000 > nowMs + 60_000) {
-    throw new GatewayServerError("JWT iat in the future");
+  if (claims.iat !== undefined) {
+    if (typeof claims.iat !== "number" || !Number.isFinite(claims.iat)) {
+      throw new GatewayServerError("JWT malformed iat claim");
+    }
+    if (claims.iat * 1000 > nowMs + IAT_SKEW_MS) {
+      throw new GatewayServerError("JWT iat in the future");
+    }
+    // Bound the maximum lifetime — a token cannot outlive its `iat` by more
+    // than the configured ceiling.
+    if (claims.exp - claims.iat > MAX_JWT_LIFETIME_SECONDS) {
+      throw new GatewayServerError("JWT lifetime exceeds maximum");
+    }
   }
   return claims;
 }
@@ -135,6 +184,31 @@ export type CreateGatewayServerOptions = {
    */
   readonly tenantOverrides?: Readonly<Record<string, Tenant>>;
   readonly now?: () => number;
+  /**
+   * Optional per-request cost estimate. It is RESERVED against the tenant's
+   * budget before the handler runs and released after — closing the TOCTOU
+   * where concurrent requests all pass `checkBudget` (which only sees
+   * already-recorded usage) before any of them records its usage, each then
+   * running to full cost. A generic gateway can't know token costs, so supply
+   * a realistic estimate here to bound in-flight spend; the default reserves
+   * nothing (behavior-preserving). Actual usage is still recorded out-of-band
+   * via `recordUsage`.
+   */
+  readonly estimateUsage?: (args: {
+    readonly method: MethodT;
+    readonly params: unknown;
+    readonly tenant: Tenant;
+  }) => UsageDelta;
+  /**
+   * Pluggable budget accounting (audit follow-up R3). Default: in-memory —
+   * per-process semantics identical to before the seam existed. Multi-process
+   * single-host deployments pass a `SqliteBudgetStore` (or a spec-built store
+   * via `createBudgetStore("sqlite:<path>")`) so every replica reserves and
+   * records against the SAME counters; multi-host deployments implement
+   * `BudgetStore` against a network store. Without this, N replicas multiply
+   * every tenant budget by N.
+   */
+  readonly budgetStore?: BudgetStore;
 };
 
 export type UsageDelta = {
@@ -154,16 +228,25 @@ export interface GatewayServer {
    * HTTP layer does.
    */
   handle(request: { readonly bearer?: string; readonly body: unknown }): Promise<unknown>;
-  /** Record token usage against a tenant's running total. */
-  recordUsage(tenantId: string, delta: UsageDelta): void;
+  /**
+   * Record token usage against a tenant's running total. Async since the
+   * budget store may be durable (audit R3); await it so usage is committed
+   * before the response is considered complete.
+   */
+  recordUsage(tenantId: string, delta: UsageDelta): Promise<void>;
   /** Read current usage (mostly for tests). */
-  usage(tenantId: string): { input: number; output: number };
+  usage(tenantId: string): Promise<{ input: number; output: number }>;
   /** Get or build the audit log for a tenant. Memoised. */
   getAuditLog(tenant: Tenant): Promise<AuditLog>;
 }
 
+const ZERO_USAGE: UsageDelta = { input: 0, output: 0 };
+
 export function createGatewayServer(opts: CreateGatewayServerOptions): GatewayServer {
-  const usageByTenant = new Map<string, { input: number; output: number }>();
+  // Budget accounting (recorded usage + in-flight reservations) lives behind
+  // the BudgetStore seam; the in-memory default preserves the pre-seam
+  // per-process semantics verbatim.
+  const budget = opts.budgetStore ?? new InMemoryBudgetStore();
   const auditLogByTenant = new Map<string, AuditLog>();
   const now = opts.now ?? Date.now;
 
@@ -183,28 +266,6 @@ export function createGatewayServer(opts: CreateGatewayServerOptions): GatewaySe
     return log;
   }
 
-  function bumpUsage(tenantId: string, delta: UsageDelta): void {
-    const cur = usageByTenant.get(tenantId) ?? { input: 0, output: 0 };
-    usageByTenant.set(tenantId, {
-      input: cur.input + delta.input,
-      output: cur.output + delta.output,
-    });
-  }
-
-  function checkBudget(tenant: Tenant): void {
-    const used = usageByTenant.get(tenant.id) ?? { input: 0, output: 0 };
-    if (used.input >= tenant.budget.maxInputTokens) {
-      throw new GatewayServerError(
-        `budget exceeded: input tokens ${used.input}/${tenant.budget.maxInputTokens}`,
-      );
-    }
-    if (used.output >= tenant.budget.maxOutputTokens) {
-      throw new GatewayServerError(
-        `budget exceeded: output tokens ${used.output}/${tenant.budget.maxOutputTokens}`,
-      );
-    }
-  }
-
   async function handleEnvelope(envelope: unknown, bearer: string | undefined): Promise<unknown> {
     let id = "?";
     try {
@@ -215,19 +276,38 @@ export function createGatewayServer(opts: CreateGatewayServerOptions): GatewaySe
       const tenant = tenantFor(claims);
       const decoded = decodeRequest(envelope);
       id = decoded.id;
-      checkBudget(tenant);
-      // Audit every authenticated gateway request.
-      const log = await getAuditLog(tenant);
-      const requestPayload: AppendInput["payload"] = {
-        method: decoded.method,
-        tenantId: tenant.id,
-        sub: claims.sub,
-      };
-      await log.append({ kind: "gateway_request", payload: requestPayload });
-      const result = await withTenant(tenant, () =>
-        opts.handler({ method: decoded.method, params: decoded.params, tenant }),
-      );
-      return encodeSuccess(id, result);
+      // Atomically reserve the estimated cost against recorded + in-flight
+      // usage (the store refuses when the total would exceed the budget on
+      // either dimension) — then release once the request finishes (actual
+      // usage is recorded out-of-band via recordUsage in the meantime). The
+      // check-and-reserve is a single atomic store operation so concurrent
+      // requests — including ones in OTHER processes sharing a durable
+      // store — can't all slip past the cap.
+      const estimate =
+        opts.estimateUsage?.({ method: decoded.method, params: decoded.params, tenant }) ??
+        ZERO_USAGE;
+      const reservation = await budget.tryReserve(tenant.id, estimate, tenant.budget);
+      if (!reservation.ok) {
+        throw new GatewayServerError(
+          `budget exceeded: ${reservation.reason} tokens ${reservation.total}/${reservation.limit}`,
+        );
+      }
+      try {
+        // Audit every authenticated gateway request.
+        const log = await getAuditLog(tenant);
+        const requestPayload: AppendInput["payload"] = {
+          method: decoded.method,
+          tenantId: tenant.id,
+          sub: claims.sub,
+        };
+        await log.append({ kind: "gateway_request", payload: requestPayload });
+        const result = await withTenant(tenant, () =>
+          opts.handler({ method: decoded.method, params: decoded.params, tenant }),
+        );
+        return encodeSuccess(id, result);
+      } finally {
+        await budget.release(tenant.id, estimate);
+      }
     } catch (err) {
       if (err instanceof GatewayProtocolError) {
         return encodeError(id, ErrorCode.BadRequest, err.message);
@@ -291,17 +371,22 @@ export function createGatewayServer(opts: CreateGatewayServerOptions): GatewaySe
     handle(req): Promise<unknown> {
       return handleEnvelope(req.body, req.bearer);
     },
-    recordUsage(tenantId, delta): void {
-      bumpUsage(tenantId, delta);
+    recordUsage(tenantId, delta): Promise<void> {
+      return budget.recordUsage(tenantId, delta);
     },
-    usage(tenantId): { input: number; output: number } {
-      return usageByTenant.get(tenantId) ?? { input: 0, output: 0 };
+    usage(tenantId): Promise<{ input: number; output: number }> {
+      return budget.usage(tenantId);
     },
     getAuditLog,
   };
 }
 
-function statusFor(code: string): number {
+/**
+ * Map a wire `ErrorCode` to its HTTP status. Exported so reference clients
+ * and embedders can render the same status the daemon's HTTP layer does.
+ * Exhaustive over {@link ErrorCode}; unknown codes fall back to `200`.
+ */
+export function statusFor(code: string): number {
   switch (code) {
     case ErrorCode.Unauthorized:
       return 401;