create-ailk 0.1.0 → 0.2.0

package/templates/apps/api/src/routes/waitlist-experiments/__tests__/tenant-isolation.test.ts

@@ -0,0 +1,577 @@
+// oss: false
+/**
+ * @file tenant-isolation.test.ts
+ *
+ * THE ACCEPTANCE GATE for the operator dashboard read API (#4665 D3/D7,
+ * #4671 AC1/AC3/AC4). Registration mirrors server.ts exactly: REAL
+ * `authPreHandlerPlugin -> tenantPreHandlerPlugin -> waitlistExperimentRoutes`,
+ * mocked `lib/prisma.js`, fixture sessions for: a sentinel-org owner (sees
+ * two sites), a second-org admin (sees only its site; 404 on the other
+ * site's experiment id and lead id), a second-org member (403), a bearer
+ * token (403), no cookie (401). Every success body parses under the D6
+ * schema.
+ */
+import Fastify from "fastify";
+import type { FastifyInstance } from "fastify";
+import {
+  waitlistDashboardListSchema,
+  waitlistExperimentComparisonSchema,
+  waitlistSignupDetailSchema,
+  waitlistSignupListSchema,
+} from "@working-theory/validation";
+
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
+jest.mock("../../../lib/prisma.js", () => ({
+  prisma: {
+    session: { findUnique: jest.fn() },
+    apiToken: {
+      findUnique: jest.fn(),
+      update: jest.fn().mockResolvedValue(undefined),
+    },
+    workspace: { findUnique: jest.fn(), count: jest.fn() },
+    membership: { findUnique: jest.fn() },
+    waitlistExperiment: { findMany: jest.fn(), findFirst: jest.fn() },
+    lead: { findMany: jest.fn(), findFirst: jest.fn() },
+    waitlistScore: { findMany: jest.fn(), findFirst: jest.fn(), findUnique: jest.fn() },
+  },
+}));
+
+import { prisma } from "../../../lib/prisma.js";
+import { authPreHandlerPlugin } from "../../../middleware/auth.js";
+import { tenantPreHandlerPlugin } from "../../../middleware/tenant.js";
+import { waitlistExperimentRoutes } from "../index.js";
+
+const FRONTEND = "https://app.example.com";
+const FUTURE = new Date(Date.now() + 60 * 60 * 1000);
+
+// ── Fixture ids (DEFAULT_ORG_ID / DEFAULT_WORKSPACE_ID from database/tenancy.ts) ──
+
+const ORG_SENTINEL = "org_00000000-0000-7000-8000-000000000001";
+const WS_A = "wksp_00000000-0000-7000-8000-000000000001";
+// A genuinely non-sentinel org — a real (non-zero-timestamp) v7 uuid.
+const ORG_B = "org_01991234-5678-7000-8000-0000000000bb";
+const WS_B = "wksp_00000000-0000-7000-8000-0000000000bb";
+
+const WORKSPACES = [
+  { id: WS_A, organizationId: ORG_SENTINEL },
+  { id: WS_B, organizationId: ORG_B },
+];
+
+const MEMBERSHIPS = [
+  { organizationId: ORG_SENTINEL, userId: "alice", role: "owner" },
+  { organizationId: ORG_B, userId: "bob", role: "owner" },
+  { organizationId: ORG_B, userId: "erin", role: "admin" },
+  { organizationId: ORG_B, userId: "carol", role: "member" },
+];
+
+const SESSION_ROWS: Record<string, Record<string, unknown>> = {
+  cookie_alice: {
+    id: "sess_alice",
+    userId: "alice",
+    expiresAt: FUTURE,
+    activeOrganizationId: ORG_SENTINEL,
+    activeWorkspaceId: WS_A,
+  },
+  cookie_bob: {
+    id: "sess_bob",
+    userId: "bob",
+    expiresAt: FUTURE,
+    activeOrganizationId: ORG_B,
+    activeWorkspaceId: WS_B,
+  },
+  cookie_erin: {
+    id: "sess_erin",
+    userId: "erin",
+    expiresAt: FUTURE,
+    activeOrganizationId: ORG_B,
+    activeWorkspaceId: WS_B,
+  },
+  cookie_carol: {
+    id: "sess_carol",
+    userId: "carol",
+    expiresAt: FUTURE,
+    activeOrganizationId: ORG_B,
+    activeWorkspaceId: WS_B,
+  },
+};
+
+// ── Waitlist-domain fixtures ──────────────────────────────────────────────────
+
+const en = (s: string) => ({ en: s });
+
+const EXP_A = "wlexp_00000000-0000-7000-8000-0000000000aa"; // site A (sentinel), scored
+const EXP_B = "wlexp_00000000-0000-7000-8000-0000000000bb"; // site B (org B), unscored
+
+const CONFIG_A = {
+  key: "exp-a",
+  mode: "qualifying" as const,
+  status: "live" as const,
+  waitlists: [{ key: "wl1", flowSlug: "exp-a-wl1" }],
+  questionSet: {
+    version: 1 as const,
+    questions: [
+      {
+        id: "role",
+        prompt: en("Role?"),
+        answerType: "single" as const,
+        options: [
+          { value: "founder", label: en("Founder") },
+          { value: "other", label: en("Other") },
+        ],
+      },
+    ],
+  },
+  scoring: {
+    version: 1 as const,
+    points: [
+      { name: "role_pt", question: "role", kind: "optionWeights" as const, weights: { founder: 5, other: 0 } },
+    ],
+    scores: { total: { sum: ["role_pt"] } },
+    tiers: [
+      { key: "hot", when: { score: "total", gte: 5 } },
+      { key: "cold", when: { score: "total", gte: 0 } },
+    ],
+    default: "cold",
+    serviceableExcludes: ["cold"],
+  },
+  tracking: {
+    version: 1 as const,
+    utm: { source: "utm_source", medium: "utm_medium", campaign: "utm_campaign" },
+    waitlists: { wl1: { campaign: "a-campaign", channels: ["organic"] } },
+  },
+  stripeConfigRef: null,
+};
+
+const CONFIG_B = {
+  key: "exp-b",
+  mode: "lead-capture" as const,
+  status: "draft" as const,
+  waitlists: [{ key: "wl2", flowSlug: "exp-b-wl2" }],
+  questionSet: {
+    version: 1 as const,
+    questions: [{ id: "role", prompt: en("Role?"), answerType: "text" as const, minLength: 1 }],
+  },
+  tracking: {
+    version: 1 as const,
+    utm: { source: "utm_source", medium: "utm_medium", campaign: "utm_campaign" },
+    waitlists: { wl2: { campaign: "b-campaign", channels: ["organic"] } },
+  },
+  stripeConfigRef: null,
+};
+
+const EXPERIMENTS = [
+  {
+    id: EXP_A,
+    siteId: WS_A,
+    key: CONFIG_A.key,
+    mode: CONFIG_A.mode,
+    status: CONFIG_A.status,
+    config: CONFIG_A,
+    createdAt: new Date("2026-08-01T00:00:00.000Z"),
+    updatedAt: new Date("2026-08-01T00:00:00.000Z"),
+  },
+  {
+    id: EXP_B,
+    siteId: WS_B,
+    key: CONFIG_B.key,
+    mode: CONFIG_B.mode,
+    status: CONFIG_B.status,
+    config: CONFIG_B,
+    createdAt: new Date("2026-08-02T00:00:00.000Z"),
+    updatedAt: new Date("2026-08-02T00:00:00.000Z"),
+  },
+];
+
+const LEAD_A1 = "lead_00000000-0000-7000-8000-0000000000a1"; // site A, scored hot
+const LEAD_A2 = "lead_00000000-0000-7000-8000-0000000000a2"; // site A, unscored
+const LEAD_B1 = "lead_00000000-0000-7000-8000-0000000000b1"; // site B
+
+const LEADS = [
+  {
+    id: LEAD_A1,
+    siteId: WS_A,
+    email: "a1@example.com",
+    source: "flow:exp-a-wl1",
+    payload: { experimentKey: "exp-a", waitlistKey: "wl1", role: "founder" },
+    createdAt: new Date("2026-08-10T00:00:00.000Z"),
+  },
+  {
+    id: LEAD_A2,
+    siteId: WS_A,
+    email: "a2@example.com",
+    source: "flow:exp-a-wl1",
+    payload: { experimentKey: "exp-a", waitlistKey: "wl1", role: "other" },
+    createdAt: new Date("2026-08-11T00:00:00.000Z"),
+  },
+  {
+    id: LEAD_B1,
+    siteId: WS_B,
+    email: "b1@example.com",
+    source: "flow:exp-b-wl2",
+    payload: { experimentKey: "exp-b", waitlistKey: "wl2", role: "member-org" },
+    createdAt: new Date("2026-08-12T00:00:00.000Z"),
+  },
+];
+
+const SCORES = [
+  {
+    leadId: LEAD_A1,
+    siteId: WS_A,
+    experimentKey: "exp-a",
+    tier: "hot",
+    score: 5,
+    categoryScores: { total: 5 },
+    ruleTrace: { fired: ["role_pt"] },
+    updatedAt: new Date("2026-08-10T01:00:00.000Z"),
+  },
+];
+
+// ── A generic, where-clause-honoring in-memory matcher (mirrors
+// services/__tests__/waitlist-dashboard.test.ts's discipline) ────────────────
+
+type Row = Record<string, unknown>;
+type Where = Record<string, unknown>;
+
+function valuesEqual(a: unknown, b: unknown): boolean {
+  if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
+  return a === b;
+}
+function lessThan(a: unknown, b: unknown): boolean {
+  if (a instanceof Date && b instanceof Date) return a.getTime() < b.getTime();
+  return (a as never) < (b as never);
+}
+
+function matchesWhere(row: Row, where: Where): boolean {
+  for (const [key, cond] of Object.entries(where)) {
+    if (key === "OR") {
+      if (!(cond as Where[]).some((w) => matchesWhere(row, w))) return false;
+      continue;
+    }
+    if (key === "AND") {
+      if (!(cond as Where[]).every((w) => matchesWhere(row, w))) return false;
+      continue;
+    }
+    if (key === "payload") {
+      const { path, equals } = cond as { path: string[]; equals: unknown };
+      const payload = row.payload as Record<string, unknown> | undefined;
+      const value = payload ? payload[path[0] as string] : undefined;
+      if (!valuesEqual(value, equals)) return false;
+      continue;
+    }
+    const rowValue = row[key];
+    if (cond !== null && typeof cond === "object" && !Array.isArray(cond) && !(cond instanceof Date)) {
+      const condObj = cond as Record<string, unknown>;
+      if ("in" in condObj) {
+        if (!(condObj.in as unknown[]).some((v) => valuesEqual(v, rowValue))) return false;
+        continue;
+      }
+      if ("lt" in condObj) {
+        if (!lessThan(rowValue, condObj.lt)) return false;
+        continue;
+      }
+    }
+    if (!valuesEqual(rowValue, cond)) return false;
+  }
+  return true;
+}
+
+function sortRows(rows: Row[], orderBy: unknown): Row[] {
+  if (!orderBy) return rows;
+  const orders = Array.isArray(orderBy) ? orderBy : [orderBy];
+  return [...rows].sort((a, b) => {
+    for (const ord of orders as Array<Record<string, "asc" | "desc">>) {
+      const [field, dir] = Object.entries(ord)[0] as [string, "asc" | "desc"];
+      const av = a[field];
+      const bv = b[field];
+      let cmp: number;
+      if (av instanceof Date && bv instanceof Date) cmp = av.getTime() - bv.getTime();
+      else if ((av as never) < (bv as never)) cmp = -1;
+      else if ((av as never) > (bv as never)) cmp = 1;
+      else cmp = 0;
+      if (dir === "desc") cmp = -cmp;
+      if (cmp !== 0) return cmp;
+    }
+    return 0;
+  });
+}
+
+function installFixtureMocks(): void {
+  (prisma.session.findUnique as jest.Mock).mockImplementation(
+    ({ where }: { where: { token?: string } }) =>
+      Promise.resolve(where.token ? (SESSION_ROWS[where.token] ?? null) : null),
+  );
+  (prisma.workspace.findUnique as jest.Mock).mockImplementation(
+    ({ where }: { where: { id?: string } }) =>
+      Promise.resolve(WORKSPACES.find((w) => w.id === where.id) ?? null),
+  );
+  // Genuinely multi-tenant (2 workspaces across 2 orgs) — the single-tenant
+  // default-resolution branch (count() === 1) must never fire here.
+  (prisma.workspace.count as jest.Mock).mockResolvedValue(WORKSPACES.length);
+  (prisma.membership.findUnique as jest.Mock).mockImplementation(
+    ({ where }: { where: { organizationId_userId?: { organizationId: string; userId: string } } }) => {
+      const key = where.organizationId_userId;
+      if (!key) return Promise.resolve(null);
+      return Promise.resolve(
+        MEMBERSHIPS.find((m) => m.organizationId === key.organizationId && m.userId === key.userId) ?? null,
+      );
+    },
+  );
+
+  (prisma.waitlistExperiment.findMany as jest.Mock).mockImplementation(
+    ({ where }: { where?: Where }) =>
+      Promise.resolve(sortRows(EXPERIMENTS.filter((e) => matchesWhere(e, where ?? {})), { createdAt: "desc" })),
+  );
+  (prisma.waitlistExperiment.findFirst as jest.Mock).mockImplementation(
+    ({ where }: { where?: Where }) => Promise.resolve(EXPERIMENTS.find((e) => matchesWhere(e, where ?? {})) ?? null),
+  );
+  (prisma.lead.findMany as jest.Mock).mockImplementation(
+    ({ where, orderBy, take }: { where?: Where; orderBy?: unknown; take?: number }) => {
+      let rows = LEADS.filter((l) => matchesWhere(l, where ?? {}));
+      rows = sortRows(rows, orderBy);
+      if (typeof take === "number") rows = rows.slice(0, take);
+      return Promise.resolve(rows);
+    },
+  );
+  (prisma.lead.findFirst as jest.Mock).mockImplementation(({ where }: { where?: Where }) =>
+    Promise.resolve(LEADS.find((l) => matchesWhere(l, where ?? {})) ?? null),
+  );
+  (prisma.waitlistScore.findMany as jest.Mock).mockImplementation(({ where }: { where?: Where }) =>
+    Promise.resolve(SCORES.filter((s) => matchesWhere(s, where ?? {}))),
+  );
+  (prisma.waitlistScore.findFirst as jest.Mock).mockImplementation(({ where }: { where?: Where }) =>
+    Promise.resolve(SCORES.find((s) => matchesWhere(s, where ?? {})) ?? null),
+  );
+  (prisma.waitlistScore.findUnique as jest.Mock).mockImplementation(
+    ({ where }: { where: { leadId: string } }) => Promise.resolve(SCORES.find((s) => s.leadId === where.leadId) ?? null),
+  );
+}
+
+// ── App assembly (mirrors server.ts registration order) ─────────────────────
+
+async function buildApp(): Promise<FastifyInstance> {
+  const app = Fastify();
+  app.register(authPreHandlerPlugin, { frontendOrigin: FRONTEND });
+  app.register(async (scope) => {
+    await scope.register(tenantPreHandlerPlugin);
+    await scope.register(waitlistExperimentRoutes);
+  });
+  await app.ready();
+  return app;
+}
+
+function cookieHeaders(token: string): Record<string, string> {
+  return { cookie: `better-auth.session_token=${token}` };
+}
+
+const ORIGINAL_ENV = process.env;
+
+describe("waitlist-experiments dashboard — tenant isolation", () => {
+  let app: FastifyInstance;
+
+  beforeEach(async () => {
+    jest.clearAllMocks();
+    installFixtureMocks();
+    // This suite's premise is a deployment where the platform-operator pin
+    // is already set (alice, the sentinel-org owner, IS the platform
+    // operator throughout) — the pin's own set/unset behavior is
+    // `services/__tests__/waitlist-dashboard.test.ts`'s "isPlatformOperator /
+    // resolveWaitlistReadScope" describe block's job, not this file's
+    // (Sam-disposed 2026-09-02, PR #4687 security review, High finding).
+    process.env = { ...ORIGINAL_ENV, AILK_OPERATOR_EMAIL: "op@example.com" };
+    app = await buildApp();
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  afterAll(() => {
+    process.env = ORIGINAL_ENV;
+  });
+
+  // ── AC4 — the sentinel-org owner is the platform operator (sees both sites) ──
+
+  it("a sentinel-org owner sees both sites' experiments (scope: 'all', rollup.sites = 2)", async () => {
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/waitlist-experiments",
+      headers: cookieHeaders("cookie_alice"),
+    });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(waitlistDashboardListSchema.safeParse(body.data).success).toBe(true);
+    expect(body.data.scope).toBe("all");
+    expect(body.data.experiments.map((e: { id: string }) => e.id).sort()).toEqual([EXP_A, EXP_B].sort());
+    expect(body.data.rollup.sites).toBe(2);
+  });
+
+  // ── AC4 — a second-org admin sees only its own site's experiment ────────────
+
+  it("a second-org admin sees only its own site's experiment (scope: 'site')", async () => {
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/waitlist-experiments",
+      headers: cookieHeaders("cookie_erin"),
+    });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.data.scope).toBe("site");
+    expect(body.data.experiments.map((e: { id: string }) => e.id)).toEqual([EXP_B]);
+    expect(body.data.rollup.sites).toBe(1);
+  });
+
+  // ── AC4 — a foreign experiment/lead id is 404, indistinguishable from missing ──
+
+  it("404s on the other site's experiment id, and on a foreign lead id", async () => {
+    const foreignExperiment = await app.inject({
+      method: "GET",
+      url: `/v1/waitlist-experiments/${EXP_A}`,
+      headers: cookieHeaders("cookie_erin"),
+    });
+    expect(foreignExperiment.statusCode).toBe(404);
+
+    const foreignLead = await app.inject({
+      method: "GET",
+      url: `/v1/waitlist-experiments/${EXP_B}/signups/${LEAD_A1}`,
+      headers: cookieHeaders("cookie_erin"),
+    });
+    expect(foreignLead.statusCode).toBe(404);
+
+    const missing = await app.inject({
+      method: "GET",
+      url: "/v1/waitlist-experiments/wlexp_00000000-0000-7000-8000-00000000dead",
+      headers: cookieHeaders("cookie_alice"),
+    });
+    expect(missing.statusCode).toBe(404);
+    // A foreign id and a genuinely-missing id are indistinguishable (the
+    // no-enumeration posture, D3) — same status, same error shape.
+    expect(missing.json().error.code).toBe(foreignExperiment.json().error.code);
+    expect(missing.body).toBe(foreignExperiment.body);
+  });
+
+  // ── AC4 — a second-org member is refused before any read ─────────────────────
+
+  it("a second-org member gets 403 on every route, before any read", async () => {
+    const list = await app.inject({
+      method: "GET",
+      url: "/v1/waitlist-experiments",
+      headers: cookieHeaders("cookie_carol"),
+    });
+    expect(list.statusCode).toBe(403);
+    expect(prisma.waitlistExperiment.findMany).not.toHaveBeenCalled();
+
+    const comparison = await app.inject({
+      method: "GET",
+      url: `/v1/waitlist-experiments/${EXP_B}`,
+      headers: cookieHeaders("cookie_carol"),
+    });
+    expect(comparison.statusCode).toBe(403);
+  });
+
+  // ── AC4 — a bearer token gets 403 (no workspace binding, default-deny) ───────
+
+  it("a bearer token gets 403 (no tenant binding)", async () => {
+    (prisma.apiToken.findUnique as jest.Mock).mockResolvedValue({
+      id: "tok1",
+      userId: "bob",
+      expiresAt: null,
+      revokedAt: null,
+    });
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/waitlist-experiments",
+      headers: { authorization: "Bearer tok_raw" },
+    });
+    expect(res.statusCode).toBe(403);
+    expect(prisma.waitlistExperiment.findMany).not.toHaveBeenCalled();
+  });
+
+  // ── AC4 — no cookie gets 401 ───────────────────────────────────────────────
+
+  it("no cookie gets 401", async () => {
+    const res = await app.inject({ method: "GET", url: "/v1/waitlist-experiments" });
+    expect(res.statusCode).toBe(401);
+  });
+
+  // ── AC2 — comparison, schema-valid ────────────────────────────────────────
+
+  it("GET the comparison for an owned experiment — 200, schema-valid", async () => {
+    const res = await app.inject({
+      method: "GET",
+      url: `/v1/waitlist-experiments/${EXP_A}`,
+      headers: cookieHeaders("cookie_alice"),
+    });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(waitlistExperimentComparisonSchema.safeParse(body.data).success).toBe(true);
+    expect(body.data.waitlists[0].raw).toBe(2);
+    expect(body.data.waitlists[0].qualified).toBe(1); // only LEAD_A1 (hot) qualifies
+  });
+
+  // ── AC1 — signups list, schema-valid, cursor pagination ──────────────────
+
+  it("GET signups — 200, schema-valid, tier/score joined from WaitlistScore", async () => {
+    const res = await app.inject({
+      method: "GET",
+      url: `/v1/waitlist-experiments/${EXP_A}/signups?limit=1`,
+      headers: cookieHeaders("cookie_alice"),
+    });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(waitlistSignupListSchema.safeParse(body.data).success).toBe(true);
+    expect(body.data.items).toHaveLength(1);
+    expect(body.data.items[0].leadId).toBe(LEAD_A2); // newest first
+    expect(body.data.nextCursor).toBe(LEAD_A2);
+  });
+
+  it("400s on a malformed :experimentId", async () => {
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/waitlist-experiments/not-a-valid-id/signups",
+      headers: cookieHeaders("cookie_alice"),
+    });
+    expect(res.statusCode).toBe(400);
+  });
+
+  // ── AC3 — signup drill-down, scored and unscored ──────────────────────────
+
+  it("GET a scored signup detail — schema-valid, carries tier/score/ruleTrace", async () => {
+    const res = await app.inject({
+      method: "GET",
+      url: `/v1/waitlist-experiments/${EXP_A}/signups/${LEAD_A1}`,
+      headers: cookieHeaders("cookie_alice"),
+    });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(waitlistSignupDetailSchema.safeParse(body.data).success).toBe(true);
+    expect(body.data.score).toEqual({
+      tier: "hot",
+      score: 5,
+      categoryScores: { total: 5 },
+      ruleTrace: { fired: ["role_pt"] },
+      updatedAt: "2026-08-10T01:00:00.000Z",
+    });
+  });
+
+  it("GET an unscored signup detail — score: null", async () => {
+    const res = await app.inject({
+      method: "GET",
+      url: `/v1/waitlist-experiments/${EXP_A}/signups/${LEAD_A2}`,
+      headers: cookieHeaders("cookie_alice"),
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.json().data.score).toBeNull();
+  });
+
+  // bob (org B owner) can read his own org's data — the grant path works for
+  // both tenants, mirroring usage.test.ts's equivalent assertion.
+  it("bob (org B owner) can read his own org's data", async () => {
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/waitlist-experiments",
+      headers: cookieHeaders("cookie_bob"),
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.json().data.experiments.map((e: { id: string }) => e.id)).toEqual([EXP_B]);
+  });
+});

package/templates/apps/api/src/routes/waitlist-experiments/comparison.ts

@@ -0,0 +1,78 @@
+// oss: false
+/**
+ * GET /v1/waitlist-experiments/:experimentId
+ *
+ * Per-waitlist comparison + total (#4665 D7, B0). `:experimentId` is
+ * validated with `zWaitlistExperimentId` (ADR-0031 rule 5) before any
+ * lookup runs — a malformed id is `400`, never reaches the service. A
+ * foreign or missing experiment id is `404`, indistinguishable (D3
+ * no-enumeration posture).
+ *
+ * Role floor + tenant guard — see `list.ts`'s header; identical contract.
+ */
+import { zWaitlistExperimentId } from "@working-theory/ids";
+import { waitlistExperimentComparisonSchema } from "@working-theory/validation";
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { z } from "zod";
+
+import {
+  getExperimentComparison,
+  resolveWaitlistReadScope,
+  WAITLIST_DASHBOARD_ROLES,
+} from "../../services/waitlist-dashboard.js";
+
+import { sendValidated } from "./respond.js";
+
+const paramsSchema = z.object({ experimentId: zWaitlistExperimentId });
+
+function unauthorized(reply: FastifyReply) {
+  return reply.status(401).send({
+    ok: false,
+    error: { code: "unauthorized", message: "Authentication required" },
+  });
+}
+
+function forbidden(reply: FastifyReply) {
+  return reply.status(403).send({
+    ok: false,
+    error: { code: "forbidden", message: "Forbidden" },
+  });
+}
+
+function invalidParams(reply: FastifyReply) {
+  return reply.status(400).send({
+    ok: false,
+    error: { code: "validation_failed", message: "Invalid experiment id" },
+  });
+}
+
+function notFound(reply: FastifyReply) {
+  return reply.status(404).send({
+    ok: false,
+    error: { code: "not_found", message: "Experiment not found" },
+  });
+}
+
+export async function getWaitlistExperimentComparisonHandler(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  const tenant = request.tenant;
+  if (!tenant) return unauthorized(reply);
+  if (!WAITLIST_DASHBOARD_ROLES.has(tenant.role)) {
+    request.log.warn(
+      { method: request.method, path: request.url, status: 403 },
+      "[waitlist-experiments] comparison denied; insufficient role",
+    );
+    return forbidden(reply);
+  }
+
+  const parsedParams = paramsSchema.safeParse(request.params);
+  if (!parsedParams.success) return invalidParams(reply);
+
+  const scope = resolveWaitlistReadScope(tenant);
+  const result = await getExperimentComparison(scope, parsedParams.data.experimentId);
+  if (!result.ok) return notFound(reply);
+
+  return sendValidated(reply, waitlistExperimentComparisonSchema, result.value, "comparison");
+}

package/templates/apps/api/src/routes/waitlist-experiments/index.ts

@@ -0,0 +1,41 @@
+// oss: false
+/**
+ * Waitlist-experiments dashboard route group (#4665 D7, B0 — the API half of
+ * the operator dashboard; #4671).
+ *
+ * Routes:
+ *   GET /v1/waitlist-experiments                                  — list + rollup
+ *   GET /v1/waitlist-experiments/:experimentId                    — per-waitlist comparison + total
+ *   GET /v1/waitlist-experiments/:experimentId/signups             — paginated signups
+ *   GET /v1/waitlist-experiments/:experimentId/signups/:leadId     — one signup's answers + score
+ *
+ * Registered INSIDE server.ts's `tenantScope` (D7) so `request.tenant` is
+ * populated by `tenantPreHandlerPlugin` before any handler runs — NOT at the
+ * public/checkout registration site.
+ *
+ * API↔MCP parity: identity-bound tenant routes (owner/admin-facing, exposes
+ * signup PII) — no MCP twin (#3591 exception, the same shape as the sibling
+ * `/v1/billing/*` and `/v1/workspaces/*` routes).
+ */
+import type { FastifyPluginAsync } from "fastify";
+
+import { getWaitlistExperimentComparisonHandler } from "./comparison.js";
+import { listWaitlistExperimentsHandler } from "./list.js";
+import { getWaitlistSignupHandler } from "./signup.js";
+import { listWaitlistSignupsHandler } from "./signups.js";
+
+export const waitlistExperimentRoutes: FastifyPluginAsync = async (fastify) => {
+  fastify.get("/v1/waitlist-experiments", listWaitlistExperimentsHandler);
+  fastify.get(
+    "/v1/waitlist-experiments/:experimentId",
+    getWaitlistExperimentComparisonHandler,
+  );
+  fastify.get(
+    "/v1/waitlist-experiments/:experimentId/signups",
+    listWaitlistSignupsHandler,
+  );
+  fastify.get(
+    "/v1/waitlist-experiments/:experimentId/signups/:leadId",
+    getWaitlistSignupHandler,
+  );
+};