create-ailk 0.19.1 → 0.21.0

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();

package/templates/apps/api/src/middleware/__tests__/rate-limit-cross-isolate.db.test.ts

@@ -0,0 +1,220 @@
+/**
+ * @file rate-limit-cross-isolate.db.test.ts
+ *
+ * LIVE-DATABASE proof of the shared store (#5040 D8: AC-1, AC-7, AC-8). Runs
+ * only when `AILK_TEST_LIVE_DATABASE === "1"` — `apps/api/src/__tests__/setup.ts`
+ * always sets a placeholder `DATABASE_URL`, so the usual
+ * `DATABASE_URL ? describe : describe.skip` gate can't distinguish a real
+ * database from the placeholder; `.github/workflows/api-postgres-compat.yml`'s
+ * full-suite step sets this variable beside its real `DATABASE_URL`.
+ *
+ * Uses the `pg` driver directly (raw SQL), the same reason
+ * `database/__tests__/prefixed-ids.db.test.ts` does: the generated Prisma
+ * client is ESM-only and cannot load under this package's CJS ts-jest
+ * transform. AC-1 drives the store's SQL through a `pg.Client` shim that
+ * turns a tagged template's strings and values into `$1…$n` text, not
+ * through the Prisma binding production uses — that binding is exercised by
+ * `rate-limit-store.test.ts`'s mocked-SQL-client unit tests.
+ */
+import { createHash, randomUUID } from "node:crypto";
+
+import Fastify, { type FastifyInstance } from "fastify";
+import { Client } from "pg";
+
+import {
+  createDatabaseRateLimitStore,
+  type RateLimitSqlClient,
+} from "../../lib/rate-limit-store.js";
+
+const describeDb =
+  process.env.AILK_TEST_LIVE_DATABASE === "1" ? describe : describe.skip;
+
+function sha256Hex(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+/** Turns a tagged template's strings + values into `$1…$n` text for `pg`. */
+function sqlClient(pgClient: Client): RateLimitSqlClient {
+  function toParamText(
+    strings: TemplateStringsArray,
+    values: readonly unknown[],
+  ): string {
+    let text = strings[0] ?? "";
+    for (let i = 0; i < values.length; i++) {
+      text += `$${i + 1}${strings[i + 1] ?? ""}`;
+    }
+    return text;
+  }
+
+  async function queryRaw(
+    strings: TemplateStringsArray,
+    ...values: unknown[]
+  ): Promise<unknown[]> {
+    const res = await pgClient.query(toParamText(strings, values), values);
+    return res.rows;
+  }
+
+  async function executeRaw(
+    strings: TemplateStringsArray,
+    ...values: unknown[]
+  ): Promise<number> {
+    const res = await pgClient.query(toParamText(strings, values), values);
+    return res.rowCount ?? 0;
+  }
+
+  return {
+    $queryRaw: queryRaw as RateLimitSqlClient["$queryRaw"],
+    $executeRaw: executeRaw as RateLimitSqlClient["$executeRaw"],
+  };
+}
+
+describeDb("rate limiter — the shared database store (live, #5040)", () => {
+  let db: Client;
+
+  beforeAll(async () => {
+    db = new Client({ connectionString: process.env.DATABASE_URL });
+    await db.connect();
+  });
+
+  afterAll(async () => {
+    await db.end();
+  });
+
+  it("AC-1: 20 concurrent requests spread 10/10 over two isolated module instances, one identity, perIpPerMinute 5 — exactly 5×200, 15×429, stored count 20", async () => {
+    const identity = `rl-demo-${randomUUID()}`;
+    const clientA = new Client({ connectionString: process.env.DATABASE_URL });
+    const clientB = new Client({ connectionString: process.env.DATABASE_URL });
+    await clientA.connect();
+    await clientB.connect();
+
+    let appA: FastifyInstance | undefined;
+    let appB: FastifyInstance | undefined;
+
+    // Each isolateModules block gives a fresh require cache: requiring
+    // rate-limit-store AND rate-limit inside it yields module instances
+    // distinct from every other test file's top-level import, with their
+    // own process-default-store memoization — exactly the D8 pattern PR
+    // #5544 already used for the memory-store proof.
+    jest.isolateModules(() => {
+      const storeMod: typeof import("../../lib/rate-limit-store") = require("../../lib/rate-limit-store");
+      const rateLimitMod: typeof import("../rate-limit") = require("../rate-limit");
+      const app = Fastify({ trustProxy: true });
+      app.register(rateLimitMod.rateLimitMiddleware, {
+        perIpPerMinute: 5,
+        store: storeMod.createDatabaseRateLimitStore(sqlClient(clientA)),
+      });
+      app.get("/test", async () => ({ ok: true }));
+      appA = app;
+    });
+
+    jest.isolateModules(() => {
+      const storeMod: typeof import("../../lib/rate-limit-store") = require("../../lib/rate-limit-store");
+      const rateLimitMod: typeof import("../rate-limit") = require("../rate-limit");
+      const app = Fastify({ trustProxy: true });
+      app.register(rateLimitMod.rateLimitMiddleware, {
+        perIpPerMinute: 5,
+        store: storeMod.createDatabaseRateLimitStore(sqlClient(clientB)),
+      });
+      app.get("/test", async () => ({ ok: true }));
+      appB = app;
+    });
+
+    if (!appA || !appB) {
+      throw new Error("isolateModules did not synchronously assign both apps");
+    }
+    await appA.ready();
+    await appB.ready();
+
+    try {
+      const inject = (app: FastifyInstance) =>
+        app.inject({
+          method: "GET",
+          url: "/test",
+          headers: { "x-forwarded-for": identity },
+        });
+      const results = await Promise.all([
+        ...Array.from({ length: 10 }, () => inject(appA!)),
+        ...Array.from({ length: 10 }, () => inject(appB!)),
+      ]);
+      const statuses = results.map((r) => r.statusCode);
+      expect(statuses.filter((s) => s === 200)).toHaveLength(5);
+      expect(statuses.filter((s) => s === 429)).toHaveLength(15);
+
+      const hash = sha256Hex(identity);
+      const row = await db.query(
+        `SELECT "count" FROM "rate_limit_counters" WHERE "key_hash" = $1`,
+        [hash],
+      );
+      expect(row.rows[0]?.count).toBe(20);
+    } finally {
+      await appA.close();
+      await appB.close();
+      await clientA.end();
+      await clientB.end();
+    }
+  });
+
+  it("AC-7: sweep deletes an expired row only on the interval trigger, never on 'limited'", async () => {
+    const store = createDatabaseRateLimitStore(sqlClient(db));
+    const now = Date.now();
+    const staleHash = sha256Hex(`rl-stale-${randomUUID()}`);
+    const openHash = sha256Hex(`rl-open-${randomUUID()}`);
+
+    await db.query(
+      `INSERT INTO "rate_limit_counters" ("key_hash", "window_start_ms", "window_ms", "count") VALUES ($1, $2, $3, 1)`,
+      [staleHash, now - 120_000, 60_000],
+    );
+    await db.query(
+      `INSERT INTO "rate_limit_counters" ("key_hash", "window_start_ms", "window_ms", "count") VALUES ($1, $2, $3, 1)`,
+      [openHash, now, 60_000],
+    );
+
+    await store.sweep(now, 60_000, "limited");
+    let rows = await db.query(
+      `SELECT "key_hash" FROM "rate_limit_counters" WHERE "key_hash" IN ($1, $2)`,
+      [staleHash, openHash],
+    );
+    expect(rows.rows).toHaveLength(2);
+
+    await store.sweep(now, 60_000, "interval");
+    rows = await db.query(
+      `SELECT "key_hash" FROM "rate_limit_counters" WHERE "key_hash" IN ($1, $2)`,
+      [staleHash, openHash],
+    );
+    expect(rows.rows.map((r: { key_hash: string }) => r.key_hash)).toEqual([
+      openHash,
+    ]);
+  });
+
+  it("AC-8: key_hash is always a sha256 digest, never the raw identity, and both format CHECKs hold", async () => {
+    const store = createDatabaseRateLimitStore(sqlClient(db));
+    const identity = `203.0.113.${1 + Math.floor(Math.random() * 254)}`;
+    const now = Date.now();
+    await store.hit(identity, now, 60_000);
+
+    const allRows = await db.query(`SELECT "key_hash" FROM "rate_limit_counters"`);
+    for (const row of allRows.rows as Array<{ key_hash: string }>) {
+      expect(row.key_hash).not.toContain("203.0.113");
+    }
+    const hash = sha256Hex(identity);
+    const matched = await db.query(
+      `SELECT 1 FROM "rate_limit_counters" WHERE "key_hash" = $1`,
+      [hash],
+    );
+    expect(matched.rows).toHaveLength(1);
+
+    await expect(
+      db.query(
+        `INSERT INTO "rate_limit_counters" ("key_hash", "window_start_ms", "window_ms", "count") VALUES ('not-hex', $1, 60000, 1)`,
+        [now],
+      ),
+    ).rejects.toThrow(/rate_limit_counters_key_hash_hex/);
+
+    await expect(
+      db.query(
+        `INSERT INTO "rate_limit_counters" ("id", "key_hash", "window_start_ms", "window_ms", "count") VALUES ('bad', $1, $2, 60000, 1)`,
+        [sha256Hex(`rl-bad-id-${randomUUID()}`), now],
+      ),
+    ).rejects.toThrow(/rate_limit_counters_id_format/);
+  });
+});