create-ailk 0.19.1 → 0.20.0

package/templates/apps/api/src/bin/__tests__/rate-limit-probe.test.ts

@@ -0,0 +1,184 @@
+/**
+ * @file rate-limit-probe.test.ts
+ *
+ * Unit tests for `runRateLimitProbe` (#5040 AC-10), with a stubbed `fetch`
+ * and a no-op `sleep`. Each stub tracks per-identity call counts; the probe
+ * itself picks its TEST-NET-3 addresses at random, so the stubs key their
+ * behavior off "the first identity used" and "every other identity" rather
+ * than a literal address.
+ */
+import { runRateLimitProbe, type ProbeFetch } from "../../lib/rate-limit-probe.js";
+
+const ORIGIN = "https://example-deployment.vercel.app";
+const noopSleep = async () => undefined;
+
+function headerIdentity(init: { headers: Record<string, string> }): string {
+  return init.headers["x-forwarded-for"] ?? "unknown";
+}
+
+/** Limits every distinct identity independently to `limit` per window. */
+function perIdentityLimiter(limit: number): ProbeFetch {
+  const counts = new Map<string, number>();
+  return async (_url, init) => {
+    const id = headerIdentity(init);
+    const count = (counts.get(id) ?? 0) + 1;
+    counts.set(id, count);
+    return { status: count <= limit ? 200 : 429 };
+  };
+}
+
+/**
+ * Limits ONLY the first identity used; every other identity always
+ * succeeds (#5040 AC-10(d): "answers 200 to every burst request").
+ */
+function firstIdentityOnlyLimiter(limit: number): ProbeFetch {
+  let firstId: string | undefined;
+  const counts = new Map<string, number>();
+  return async (_url, init) => {
+    const id = headerIdentity(init);
+    if (firstId === undefined) firstId = id;
+    if (id !== firstId) return { status: 200 };
+    const count = (counts.get(id) ?? 0) + 1;
+    counts.set(id, count);
+    return { status: count <= limit ? 200 : 429 };
+  };
+}
+
+/**
+ * Limits the first identity and never lets ANY other identity through
+ * either (#5040 AC-10(f): "answers 429 to every burst request").
+ */
+function alwaysOverLimiter(limit: number): ProbeFetch {
+  let firstId: string | undefined;
+  const counts = new Map<string, number>();
+  return async (_url, init) => {
+    const id = headerIdentity(init);
+    if (firstId === undefined) firstId = id;
+    const count = (counts.get(id) ?? 0) + 1;
+    counts.set(id, count);
+    if (id === firstId) return { status: count <= limit ? 200 : 429 };
+    return { status: 429 };
+  };
+}
+
+describe("runRateLimitProbe (#5040 AC-10)", () => {
+  it("(a) a per-identity limiter gives xff: survives, burst: holds (10/30), exit 0", async () => {
+    const log = jest.fn();
+    const code = await runRateLimitProbe({
+      origin: ORIGIN,
+      fetch: perIdentityLimiter(10),
+      sleep: noopSleep,
+      log,
+    });
+    expect(code).toBe(0);
+    expect(log).toHaveBeenCalledWith("xff: survives");
+    expect(log).toHaveBeenCalledWith("burst: holds (10/30)");
+  });
+
+  it("(b) a shared, header-blind identity gives xff: overwritten, sleeps exactly once with 62000, exit 0", async () => {
+    let count = 0;
+    const fetch: ProbeFetch = async () => {
+      count += 1;
+      return { status: count <= 10 ? 200 : 429 };
+    };
+    const sleep = jest.fn(async (ms: number) => {
+      // Simulate the real window rolling over once the probe waits it out.
+      void ms;
+      count = 0;
+    });
+
+    const code = await runRateLimitProbe({
+      origin: ORIGIN,
+      fetch,
+      sleep,
+      log: jest.fn(),
+    });
+
+    expect(code).toBe(0);
+    expect(sleep).toHaveBeenCalledTimes(1);
+    expect(sleep).toHaveBeenCalledWith(62_000);
+  });
+
+  it("(c) a limiter that never answers 429 gives limiter: not-observed, exit 1", async () => {
+    const log = jest.fn();
+    const fetchAlways200: ProbeFetch = async () => ({ status: 200 });
+    const code = await runRateLimitProbe({
+      origin: ORIGIN,
+      fetch: fetchAlways200,
+      sleep: noopSleep,
+      log,
+    });
+    expect(code).toBe(1);
+    expect(log).toHaveBeenCalledWith("limiter: not-observed");
+  });
+
+  it("(d) only the first identity is limited, every other answers 200: burst: exceeded (30/30), exit 1", async () => {
+    const log = jest.fn();
+    const code = await runRateLimitProbe({
+      origin: ORIGIN,
+      fetch: firstIdentityOnlyLimiter(10),
+      sleep: noopSleep,
+      log,
+    });
+    expect(code).toBe(1);
+    expect(log).toHaveBeenCalledWith("xff: survives");
+    expect(log).toHaveBeenCalledWith("burst: exceeded (30/30)");
+  });
+
+  it("(e) --origin http://example.com is refused before any fetch call", async () => {
+    const fetch = jest.fn();
+    const log = jest.fn();
+    const code = await runRateLimitProbe({
+      origin: "http://example.com",
+      fetch,
+      sleep: noopSleep,
+      log,
+    });
+    expect(code).toBe(2);
+    expect(fetch).not.toHaveBeenCalled();
+    expect(log).toHaveBeenCalledWith("probe: error invalid-origin");
+  });
+
+  it("(f) every burst request answers 429: burst: inconclusive (0/30), exit 1", async () => {
+    const log = jest.fn();
+    const code = await runRateLimitProbe({
+      origin: ORIGIN,
+      fetch: alwaysOverLimiter(10),
+      sleep: noopSleep,
+      log,
+    });
+    expect(code).toBe(1);
+    expect(log).toHaveBeenCalledWith("burst: inconclusive (0/30)");
+  });
+
+  it("a loopback http origin is accepted", async () => {
+    const code = await runRateLimitProbe({
+      origin: "http://localhost:3002",
+      fetch: perIdentityLimiter(10),
+      sleep: noopSleep,
+      log: jest.fn(),
+    });
+    expect(code).toBe(0);
+  });
+
+  it("a network error during the burst answers probe: error <code>, exit 2", async () => {
+    const log = jest.fn();
+    let count = 0;
+    const fetch: ProbeFetch = async () => {
+      count += 1;
+      if (count <= 11) return { status: count <= 10 ? 200 : 429 };
+      if (count === 12) return { status: 200 }; // the xff probe (survives)
+      const err = new Error("boom") as Error & { code: string };
+      err.code = "ECONNRESET";
+      throw err;
+    };
+    const code = await runRateLimitProbe({
+      origin: ORIGIN,
+      fetch,
+      sleep: noopSleep,
+      log,
+    });
+    expect(code).toBe(2);
+    expect(log).toHaveBeenCalledWith("probe: error ECONNRESET");
+  });
+});

package/templates/apps/api/src/bin/rate-limit-probe.ts

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/* istanbul ignore file -- CLI bootstrap; the logic it wraps
+   (runRateLimitProbe) is unit-tested directly in __tests__/rate-limit-probe.test.ts
+   — the abandon-sweep.ts / lib/abandon-email.ts split. */
+/**
+ * The live rate-limiter probe (#5040 D9, FR-7, AC-10).
+ *
+ * Dev:        `pnpm --filter @working-theory/api rate-limit:probe --origin <https origin>`
+ * Production: `node dist/bin/rate-limit-probe.js --origin <https origin>`
+ *
+ * Answers the two platform facts #5040 and #5111 need a live deployment for:
+ *
+ *   1. Does a client-chosen `x-forwarded-for` survive to the serverless
+ *      function, or does the edge overwrite it? (`xff: survives | overwritten`)
+ *   2. Does a concurrent burst against ONE identity stay within the
+ *      configured limit? (`burst: holds | exceeded | inconclusive`)
+ *
+ * It only ever calls `GET <origin>/v1/aeo/score/example` — a no-fetch,
+ * no-write read already behind the aeo scope's strict limiter (#5111) — and
+ * refuses an origin that is not `https:` or loopback `http:` before any
+ * network call.
+ */
+import { runRateLimitProbe } from "../lib/rate-limit-probe.js";
+
+function parseOrigin(argv: readonly string[]): string | undefined {
+  const index = argv.indexOf("--origin");
+  return index === -1 ? undefined : argv[index + 1];
+}
+
+async function main(): Promise<number> {
+  const origin = parseOrigin(process.argv.slice(2));
+  if (!origin) {
+    console.log("probe: error missing --origin");
+    return 2;
+  }
+  return runRateLimitProbe({
+    origin,
+    fetch: (url, init) => globalThis.fetch(url, init),
+  });
+}
+
+main()
+  .then((code) => {
+    process.exitCode = code;
+  })
+  .catch((err: unknown) => {
+    // Belt-and-braces, as abandon-sweep.ts: runRateLimitProbe catches its own
+    // network/status errors, so this only stops a bare unhandled rejection.
+    console.log(
+      `probe: error ${err instanceof Error ? err.message : String(err)}`,
+    );
+    process.exitCode = 2;
+  });

package/templates/apps/api/src/lib/proposal-paid-store.ts

@@ -0,0 +1,49 @@
+/**
+ * The proposal paid stamp's data boundary (#8516, spec
+ * docs/specs/8516-proposals-as-an-artifact-kind-spec.md D13).
+ *
+ * The Stripe webhook (`routes/webhooks/stripe.ts`) is a commerce primitive
+ * registered on every build, so it may import no slice-owned file —
+ * `lib/member-store.ts` is one, and importing it would pull the webhook out of
+ * every scaffold without the member slice (the #5677 failure). Its one piece
+ * write therefore lives here, in the base tree, importing only `prisma.ts`.
+ *
+ * Two statements and no others, both scoped by a workspace id AND a piece id
+ * taken from a Stripe-signed `checkout.session.completed` event's metadata —
+ * written by this server when it opened the session (`ailk_proposal`,
+ * `ailk_workspace`; `services/proposal-payments.ts`), never settable by the
+ * payer: a guarded `updateMany` that stamps an unpaid proposal paid, and a
+ * `findFirst` by the same pair reading back which session paid it. No list,
+ * no other model, no read by any other key; never called by a route.
+ * `architecture.yaml` names this file as a tenant-scope exclusion with that
+ * reason.
+ */
+import { prisma } from "./prisma.js";
+
+/**
+ * - `stamped`      — this session paid an unpaid proposal; stamped now.
+ * - `replay`       — the proposal was already stamped by THIS session.
+ * - `already_paid` — a DIFFERENT session already paid it (a second charge).
+ * - `not_found`    — no proposal of that id in that workspace.
+ */
+export type ProposalPaidOutcome = "stamped" | "replay" | "already_paid" | "not_found";
+
+/** Stamp a proposal paid by `sessionId`, at most once. */
+export async function stampProposalPaid(
+  workspaceId: string,
+  pieceId: string,
+  sessionId: string,
+  now: Date,
+): Promise<ProposalPaidOutcome> {
+  const stamped = await prisma.piece.updateMany({
+    where: { id: pieceId, workspaceId, kind: "proposal", paidAt: null },
+    data: { paidAt: now, paidSessionId: sessionId },
+  });
+  if (stamped.count > 0) return "stamped";
+  const row = await prisma.piece.findFirst({
+    where: { id: pieceId, workspaceId, kind: "proposal" },
+    select: { paidSessionId: true },
+  });
+  if (row === null) return "not_found";
+  return row.paidSessionId === sessionId ? "replay" : "already_paid";
+}

package/templates/apps/api/src/lib/rate-limit-probe.ts

@@ -0,0 +1,165 @@
+/**
+ * The live rate-limiter probe's logic (#5040 D9, FR-7). Pure: takes its
+ * `fetch` and `sleep` so the CLI bin (`bin/rate-limit-probe.ts`) and the test
+ * suite can both drive it without a real network or a real 60-second wait.
+ * See the bin's header for what it answers and why.
+ */
+
+const TEST_NET_3_PREFIX = "203.0.113.";
+
+export type ProbeFetch = (
+  url: string,
+  init: { headers: Record<string, string> },
+) => Promise<{ status: number }>;
+
+export interface RunRateLimitProbeOptions {
+  origin: string;
+  fetch: ProbeFetch;
+  limit?: number;
+  windowMs?: number;
+  sleep?: (ms: number) => Promise<void>;
+  log?: (msg: string) => void;
+}
+
+function isAllowedOrigin(origin: string): boolean {
+  let url: URL;
+  try {
+    url = new URL(origin);
+  } catch {
+    return false;
+  }
+  if (url.protocol === "https:") return true;
+  if (url.protocol !== "http:") return false;
+  const host = url.hostname;
+  return host === "localhost" || host === "127.0.0.1" || host === "::1";
+}
+
+function randomTestNet3(exclude: ReadonlySet<string>): string {
+  let candidate: string;
+  do {
+    candidate = `${TEST_NET_3_PREFIX}${1 + Math.floor(Math.random() * 254)}`;
+  } while (exclude.has(candidate));
+  return candidate;
+}
+
+function describeError(err: unknown): string {
+  if (
+    err !== null &&
+    typeof err === "object" &&
+    "code" in err &&
+    typeof (err as { code?: unknown }).code === "string"
+  ) {
+    return (err as { code: string }).code;
+  }
+  return err instanceof Error ? err.message : String(err);
+}
+
+const PROBE_PATH = "/v1/aeo/score/example";
+
+/**
+ * Runs the two-fact probe (#5040 D9) against `origin`. Returns the process
+ * exit code the bin should use: `0` on `burst: holds`, `1` on every other
+ * conclusive-but-not-holding outcome (`limiter: not-observed`,
+ * `burst: exceeded`, `burst: inconclusive`), `2` on a refused origin or a
+ * network/status error.
+ */
+export async function runRateLimitProbe(
+  opts: RunRateLimitProbeOptions,
+): Promise<number> {
+  const {
+    origin,
+    fetch,
+    limit = 10,
+    windowMs = 60_000,
+    sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)),
+    log = (msg: string) => console.log(msg),
+  } = opts;
+
+  if (!isAllowedOrigin(origin)) {
+    log("probe: error invalid-origin");
+    return 2;
+  }
+
+  const url = `${origin}${PROBE_PATH}`;
+  const used = new Set<string>();
+  const identityA = randomTestNet3(used);
+  used.add(identityA);
+
+  async function send(identity: string): Promise<number> {
+    const res = await fetch(url, { headers: { "x-forwarded-for": identity } });
+    return res.status;
+  }
+
+  let lastStatus: number | undefined;
+  try {
+    for (let i = 0; i < limit + 1; i++) {
+      const status = await send(identityA);
+      if (status !== 200 && status !== 429) {
+        log(`probe: error ${status}`);
+        return 2;
+      }
+      lastStatus = status;
+    }
+  } catch (err) {
+    log(`probe: error ${describeError(err)}`);
+    return 2;
+  }
+
+  if (lastStatus !== 429) {
+    log("limiter: not-observed");
+    return 1;
+  }
+
+  const identityB = randomTestNet3(used);
+  used.add(identityB);
+  let survives: boolean;
+  try {
+    const status = await send(identityB);
+    if (status !== 200 && status !== 429) {
+      log(`probe: error ${status}`);
+      return 2;
+    }
+    survives = status === 200;
+  } catch (err) {
+    log(`probe: error ${describeError(err)}`);
+    return 2;
+  }
+  log(survives ? "xff: survives" : "xff: overwritten");
+
+  let burstIdentity: string;
+  if (survives) {
+    burstIdentity = randomTestNet3(used);
+  } else {
+    await sleep(windowMs + 2_000);
+    burstIdentity = identityA;
+  }
+
+  const total = 3 * limit;
+  let successes = 0;
+  try {
+    const results = await Promise.all(
+      Array.from({ length: total }, () => send(burstIdentity)),
+    );
+    for (const status of results) {
+      if (status !== 200 && status !== 429) {
+        log(`probe: error ${status}`);
+        return 2;
+      }
+      if (status === 200) successes += 1;
+    }
+  } catch (err) {
+    log(`probe: error ${describeError(err)}`);
+    return 2;
+  }
+
+  if (successes === 0) {
+    log(`burst: inconclusive (0/${total})`);
+    return 1;
+  }
+  if (successes > limit) {
+    log(`burst: exceeded (${successes}/${total})`);
+    return 1;
+  }
+  log(`burst: holds (${successes}/${total})`);
+  return 0;
+}

package/templates/apps/api/src/lib/rate-limit-store.ts

@@ -0,0 +1,142 @@
+/**
+ * The rate limiter's database store (#5040 D1/D3/D4). Counts a bucket in
+ * `rate_limit_counters` so one visitor's limit holds across every concurrent
+ * isolate on a deployment with a database — see
+ * `apps/api/src/middleware/rate-limit.ts`'s `SHARED STORE` header for the
+ * full picture (what this protects against, and what it does not).
+ *
+ * The only file naming `rate_limit_counters` outside `database/`. All SQL is
+ * `db.$queryRaw` / `db.$executeRaw` tagged templates — never `…Unsafe` — so
+ * every value is a bound parameter, never string-interpolated.
+ */
+import { createHash } from "node:crypto";
+
+import type { Prisma } from "@working-theory/database";
+
+/** One bucket's state, as both the memory and database stores report it. */
+export type RateLimitBucket = {
+  count: number;
+  windowStartMs: number;
+};
+
+/** What a store call reports when it ran against a backing database. */
+export type RateLimitStore = {
+  /** Count one request against `key`'s visitor bucket. */
+  hit(key: string, now: number, windowMs: number): Promise<RateLimitBucket>;
+  /** Count one request against `key`'s forwarding-key bucket (#7394 DD-8). */
+  hitKey(key: string, now: number, windowMs: number): Promise<RateLimitBucket>;
+  /** True when `key` has a bucket whose window has not yet ended. */
+  hasOpenWindow(key: string, now: number, windowMs: number): Promise<boolean>;
+  /** Evict expired buckets. `reason` is why the sweep fired (D6). */
+  sweep(now: number, windowMs: number, reason: "interval" | "limited"): Promise<void>;
+};
+
+/** What `createDatabaseRateLimitStore` needs of a Prisma client (D3). */
+export type RateLimitSqlClient = Pick<
+  Prisma.TransactionClient,
+  "$queryRaw" | "$executeRaw"
+>;
+
+function sha256Hex(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+/**
+ * The database store (D1/D3): one atomic upsert per hit, same window rules as
+ * the memory store. `bucketKey` is the exact string the memory store uses as
+ * its Map key; this store hashes it before it ever reaches SQL (FR-5) — the
+ * table never holds a plaintext IP or bucket key.
+ */
+export function createDatabaseRateLimitStore(
+  db: RateLimitSqlClient,
+): RateLimitStore {
+  async function countHit(
+    bucketKey: string,
+    now: number,
+    windowMs: number,
+  ): Promise<RateLimitBucket> {
+    const hash = sha256Hex(bucketKey);
+    const rows = await db.$queryRaw<
+      Array<{ count: number; window_start_ms: bigint | string }>
+    >`
+      INSERT INTO "rate_limit_counters" ("key_hash", "window_start_ms", "window_ms", "count")
+      VALUES (${hash}, ${now}::bigint, ${windowMs}::integer, 1)
+      ON CONFLICT ("key_hash") DO UPDATE SET
+        "count" = CASE WHEN ${now}::bigint - "rate_limit_counters"."window_start_ms" >= ${windowMs}::integer
+                       THEN 1 ELSE "rate_limit_counters"."count" + 1 END,
+        "window_start_ms" = CASE WHEN ${now}::bigint - "rate_limit_counters"."window_start_ms" >= ${windowMs}::integer
+                       THEN ${now}::bigint ELSE "rate_limit_counters"."window_start_ms" END,
+        "window_ms" = ${windowMs}::integer
+      RETURNING "count", "window_start_ms"
+    `;
+    const row = rows[0];
+    if (!row) {
+      throw new Error("rate_limit_counters upsert returned no row");
+    }
+    return {
+      count: Number(row.count),
+      windowStartMs: Number(row.window_start_ms),
+    };
+  }
+
+  async function hasOpenWindow(
+    bucketKey: string,
+    now: number,
+    windowMs: number,
+  ): Promise<boolean> {
+    const hash = sha256Hex(bucketKey);
+    const rows = await db.$queryRaw<Array<{ one: number }>>`
+      SELECT 1 AS "one" FROM "rate_limit_counters"
+      WHERE "key_hash" = ${hash}
+        AND ${now}::bigint - "window_start_ms" < ${windowMs}::integer
+      LIMIT 1
+    `;
+    return rows.length > 0;
+  }
+
+  return {
+    hit: (key, now, windowMs) => countHit(key, now, windowMs),
+    hitKey: (key, now, windowMs) => countHit(key, now, windowMs),
+    hasOpenWindow,
+    async sweep(now, _windowMs, reason) {
+      // D6 — the database store sweeps on the interval trigger only. Sweeping
+      // on every 429 would let an attacker buy a table scan per refused
+      // request.
+      if (reason !== "interval") return;
+      await db.$executeRaw`
+        DELETE FROM "rate_limit_counters"
+        WHERE "window_start_ms" + "window_ms" <= ${now}::bigint
+      `;
+    },
+  };
+}
+
+/**
+ * Which store a registration with no explicit `store` option uses (D4),
+ * resolved once per process and memoized by the middleware. `warn` is called
+ * exactly once for each of the two misconfiguration rows below.
+ */
+export type RateLimitStoreEnv = {
+  DATABASE_URL?: string | undefined;
+  AILK_RATE_LIMIT_STORE?: string | undefined;
+};
+
+export function resolveRateLimitStoreKind(
+  env: RateLimitStoreEnv,
+  warn: (msg: string) => void,
+): "memory" | "database" {
+  const hasDatabase = !!env.DATABASE_URL;
+  const raw = env.AILK_RATE_LIMIT_STORE;
+
+  if (raw === undefined || raw === "") {
+    return hasDatabase ? "database" : "memory";
+  }
+  if (raw === "memory") return "memory";
+  if (raw === "database") {
+    if (hasDatabase) return "database";
+    warn("AILK_RATE_LIMIT_STORE=database needs DATABASE_URL; using memory");
+    return "memory";
+  }
+  warn("AILK_RATE_LIMIT_STORE is not memory or database and is ignored");
+  return hasDatabase ? "database" : "memory";
+}

package/templates/apps/api/src/middleware/__tests__/auth.hub-session-path.test.ts

@@ -77,6 +77,9 @@ const ADMITTED = [
   "POST /v1/member/deletion-request",
   "GET /v1/member/consents",
   "POST /v1/member/consents",
+  // #8515 D13 — the client's onboarding read and write.
+  "GET /v1/member/onboarding",
+  "POST /v1/member/onboarding",
 ];
 
 /** Every route the credential must NOT reach, each a recording stub. */
@@ -174,9 +177,9 @@ afterEach(async () => {
 });
 
 describe("HUB_SESSION_ROUTES", () => {
-  it("is exactly the 20 entries, by method and registered URL — never a prefix (AC-1)", () => {
+  it("is exactly the 24 entries, by method and registered URL — never a prefix (AC-1, #8515 AC-6)", () => {
     expect([...HUB_SESSION_ROUTES]).toEqual(ADMITTED);
-    expect(HUB_SESSION_ROUTES.length).toBe(22);
+    expect(HUB_SESSION_ROUTES.length).toBe(24);
     for (const route of HUB_SESSION_ROUTES) {
       expect({
         route,

package/templates/apps/api/src/middleware/__tests__/default-tenant.test.ts

@@ -580,6 +580,7 @@ describe("defaultTenantPreHandler — agents (#3591 D5, D7)", () => {
       organizationId: DEFAULT_ORG_ID,
       workspaceId: DEFAULT_WORKSPACE_ID,
       role: "member",
+      agent: true,
     });
     await app.close();
   });
@@ -599,6 +600,7 @@ describe("defaultTenantPreHandler — agents (#3591 D5, D7)", () => {
       organizationId: DEFAULT_ORG_ID,
       workspaceId: DEFAULT_WORKSPACE_ID,
       role: "member",
+      agent: true,
       grants: ["content-edit", "magnets-manage"],
     });
     await app.close();