create-ailk 0.1.0 → 0.2.0

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

@@ -0,0 +1,64 @@
+// oss: false
+/**
+ * GET /v1/waitlist-experiments
+ *
+ * List + rollup in the caller's scope (#4665 D7, B0). The scope is ALWAYS
+ * derived server-side from `request.tenant` via `resolveWaitlistReadScope`
+ * (D2) — there is no client-supplied site/org id, so cross-tenant
+ * enumeration is structurally impossible.
+ *
+ * Registered inside `server.ts`'s tenant scope (D7) behind
+ * `tenantPreHandlerPlugin` — a caller with no resolvable tenant is denied by
+ * the preHandler (403) before this handler ever runs.
+ *
+ * Role floor (D2): `owner | admin` — the dashboard exposes signup PII, so
+ * membership alone is not authorization. Checked BEFORE any read, mirroring
+ * `routes/billing/usage.ts`'s #3819 gate.
+ */
+import { waitlistDashboardListSchema } from "@working-theory/validation";
+import type { FastifyReply, FastifyRequest } from "fastify";
+
+import {
+  listExperiments,
+  resolveWaitlistReadScope,
+  WAITLIST_DASHBOARD_ROLES,
+} from "../../services/waitlist-dashboard.js";
+
+import { sendValidated } from "./respond.js";
+
+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" },
+  });
+}
+
+export async function listWaitlistExperimentsHandler(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  const tenant = request.tenant;
+  // Defensive fallback — the tenant preHandler denies an unresolvable tenant
+  // before this handler runs; `request.tenant` is `TenantContext | undefined`
+  // at the type level, mirroring the sibling billing routes.
+  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] list denied; insufficient role",
+    );
+    return forbidden(reply);
+  }
+
+  const scope = resolveWaitlistReadScope(tenant);
+  const data = await listExperiments(scope);
+  return sendValidated(reply, waitlistDashboardListSchema, data, "list");
+}

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

@@ -0,0 +1,42 @@
+// oss: false
+/**
+ * Response-schema validation for the waitlist-experiments dashboard routes
+ * (Low finding, PR #4687 security review: "response schemas are contract-
+ * only, never enforced on the wire" — the D6 schemas types the service
+ * layer, but nothing previously re-parsed the value against its own
+ * `.strict()` schema before it left the process). A defensive net: the
+ * service layer already guards against the anomalies this would catch (the
+ * corrupt-config skip, the missing-`waitlistKey` skip), so this should never
+ * fire in practice — if it does, it is a genuine internal error (a future
+ * service change drifting from its own contract), not a client-facing 4xx.
+ */
+import { logger } from "@working-theory/observability";
+import type { FastifyReply } from "fastify";
+import type { z } from "zod";
+
+/**
+ * Parse `data` against `schema`; on success send the ORIGINAL `data` object
+ * (not the parsed clone) at `200`, matching every route's existing envelope.
+ * On failure, log the zod issues (never the raw `data`, which may carry
+ * signup PII) and reply `500` — a shape drift is an internal-error class,
+ * never something a client 4xx can describe.
+ */
+export function sendValidated<T>(
+  reply: FastifyReply,
+  schema: z.ZodType<T>,
+  data: T,
+  routeName: string,
+): FastifyReply {
+  const parsed = schema.safeParse(data);
+  if (!parsed.success) {
+    logger.error(
+      { route: routeName, issues: parsed.error.issues },
+      "[waitlist-experiments] response failed its own contract schema",
+    );
+    return reply.status(500).send({
+      ok: false,
+      error: { code: "internal_error", message: "Response failed contract validation" },
+    });
+  }
+  return reply.status(200).send({ ok: true, data });
+}

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

@@ -0,0 +1,84 @@
+// oss: false
+/**
+ * GET /v1/waitlist-experiments/:experimentId/signups/:leadId
+ *
+ * One signup's answers + score (#4665 D7, B0). Both path ids are validated
+ * at the boundary (`zWaitlistExperimentId`, `zLeadId`, ADR-0031 rule 5) — a
+ * malformed id is `400`. The lead is loaded THROUGH its experiment (D3) — a
+ * foreign or unrelated lead is `404`, indistinguishable from a missing one.
+ *
+ * Role floor + tenant guard — see `list.ts`'s header; identical contract.
+ */
+import { zLeadId, zWaitlistExperimentId } from "@working-theory/ids";
+import { waitlistSignupDetailSchema } from "@working-theory/validation";
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { z } from "zod";
+
+import {
+  getSignup,
+  resolveWaitlistReadScope,
+  WAITLIST_DASHBOARD_ROLES,
+} from "../../services/waitlist-dashboard.js";
+
+import { sendValidated } from "./respond.js";
+
+const paramsSchema = z.object({
+  experimentId: zWaitlistExperimentId,
+  leadId: zLeadId,
+});
+
+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 or lead id" },
+  });
+}
+
+function notFound(reply: FastifyReply) {
+  return reply.status(404).send({
+    ok: false,
+    error: { code: "not_found", message: "Signup not found" },
+  });
+}
+
+export async function getWaitlistSignupHandler(
+  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] signup detail 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 getSignup(
+    scope,
+    parsedParams.data.experimentId,
+    parsedParams.data.leadId,
+  );
+  if (!result.ok) return notFound(reply);
+
+  return sendValidated(reply, waitlistSignupDetailSchema, result.value, "signup");
+}

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

@@ -0,0 +1,119 @@
+// oss: false
+/**
+ * GET /v1/waitlist-experiments/:experimentId/signups?waitlist=&cursor=&limit=
+ *
+ * Paginated signups (#4665 D7, B0). `limit` defaults to 50, max 200;
+ * `createdAt desc, id desc`; `cursor` is the previous page's last row's
+ * `leadId` (a `zLeadId`-validated boundary value, per the same id-format
+ * discipline as `:experimentId`). `waitlist` narrows to one declared
+ * waitlist key (`flowIdentifierSchema`). A malformed query param is `400`
+ * before any lookup runs.
+ *
+ * Role floor + tenant guard — see `list.ts`'s header; identical contract.
+ */
+import { zLeadId, zWaitlistExperimentId } from "@working-theory/ids";
+import { flowIdentifierSchema, waitlistSignupListSchema } from "@working-theory/validation";
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { z } from "zod";
+
+import {
+  listSignups,
+  resolveWaitlistReadScope,
+  WAITLIST_DASHBOARD_ROLES,
+} from "../../services/waitlist-dashboard.js";
+
+import { sendValidated } from "./respond.js";
+
+const paramsSchema = z.object({ experimentId: zWaitlistExperimentId });
+
+const emptyToUndefined = (val: unknown) => (val === "" ? undefined : val);
+
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 200;
+
+const querySchema = z.object({
+  waitlist: z.preprocess(emptyToUndefined, flowIdentifierSchema.optional()),
+  cursor: z.preprocess(emptyToUndefined, zLeadId.optional()),
+  limit: z.preprocess(
+    emptyToUndefined,
+    z.coerce.number().int().min(1).max(MAX_LIMIT).optional(),
+  ),
+});
+
+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 invalidQuery(reply: FastifyReply) {
+  return reply.status(400).send({
+    ok: false,
+    error: { code: "validation_failed", message: "Invalid query parameters" },
+  });
+}
+
+function notFound(reply: FastifyReply) {
+  return reply.status(404).send({
+    ok: false,
+    error: { code: "not_found", message: "Experiment not found" },
+  });
+}
+
+/** A supplied `cursor` that does not resolve within this experiment is a
+ * client input error, not a missing-resource one (Low finding, PR #4687
+ * security review) — distinct from `notFound`'s experiment-not-found case. */
+function invalidCursor(reply: FastifyReply) {
+  return reply.status(400).send({
+    ok: false,
+    error: { code: "validation_failed", message: "cursor does not resolve within this experiment" },
+  });
+}
+
+export async function listWaitlistSignupsHandler(
+  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] signups list denied; insufficient role",
+    );
+    return forbidden(reply);
+  }
+
+  const parsedParams = paramsSchema.safeParse(request.params);
+  if (!parsedParams.success) return invalidParams(reply);
+
+  const parsedQuery = querySchema.safeParse(request.query);
+  if (!parsedQuery.success) return invalidQuery(reply);
+
+  const scope = resolveWaitlistReadScope(tenant);
+  const result = await listSignups(scope, parsedParams.data.experimentId, {
+    waitlist: parsedQuery.data.waitlist,
+    cursor: parsedQuery.data.cursor,
+    limit: parsedQuery.data.limit ?? DEFAULT_LIMIT,
+  });
+  if (!result.ok) {
+    return result.error.kind === "invalid_cursor" ? invalidCursor(reply) : notFound(reply);
+  }
+
+  return sendValidated(reply, waitlistSignupListSchema, result.value, "signups");
+}

package/templates/apps/api/src/routes/waitlist-signups/__tests__/index.test.ts

@@ -0,0 +1,238 @@
+/**
+ * @file index.test.ts
+ *
+ * THE ACCEPTANCE GATE for the respondent read route (#4731 AC-1/2/3/4/6).
+ * Registration mirrors server.ts: REAL `authPreHandlerPlugin ->
+ * waitlistSignupRoutes` (auth only, no tenant guard), mocked `lib/prisma.js`.
+ * Proves: no session → the preHandler's own 401, untouched; an unverified
+ * user → 403 `email_unverified` with NO Lead read; a verified respondent →
+ * 200 with exactly the seven keys, parsing under the D5 schema; no lead →
+ * 404 `signup_not_found`; an `email` query parameter is ignored (the SESSION
+ * user's signup resolves, never the parameter's); a malformed experimentKey
+ * → 400.
+ */
+import Fastify from "fastify";
+import type { FastifyInstance } from "fastify";
+import { waitlistSignupMeResponseSchema } 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),
+    },
+    user: { findUnique: jest.fn() },
+    lead: { findFirst: jest.fn() },
+    waitlistScore: { findFirst: jest.fn() },
+    flowSession: { findFirst: jest.fn() },
+  },
+}));
+
+import { prisma } from "../../../lib/prisma.js";
+import { authPreHandlerPlugin } from "../../../middleware/auth.js";
+import { waitlistSignupRoutes } from "../index.js";
+
+const FRONTEND = "https://app.example.com";
+const FUTURE = new Date(Date.now() + 60 * 60 * 1000);
+const SITE = "wksp_00000000-0000-7000-8000-000000000001";
+const EXPERIMENT = "ailk-founder-diagnostic";
+const LEAD_ID = "lead_00000000-0000-7000-8000-0000000000a1";
+
+const USERS: Record<string, { id: string; email: string; emailVerified: boolean }> = {
+  alice: { id: "alice", email: "alice@example.com", emailVerified: true },
+  // Email+password account whose address was never verified.
+  mallory: { id: "mallory", email: "mallory@example.com", emailVerified: false },
+  bob: { id: "bob", email: "bob@example.com", emailVerified: true },
+};
+
+const SESSION_ROWS: Record<string, Record<string, unknown>> = {
+  cookie_alice: { id: "sess_alice", userId: "alice", expiresAt: FUTURE, activeOrganizationId: null, activeWorkspaceId: null },
+  cookie_mallory: { id: "sess_mallory", userId: "mallory", expiresAt: FUTURE, activeOrganizationId: null, activeWorkspaceId: null },
+  cookie_bob: { id: "sess_bob", userId: "bob", expiresAt: FUTURE, activeOrganizationId: null, activeWorkspaceId: null },
+};
+
+const ALICE_LEAD = {
+  id: LEAD_ID,
+  payload: {
+    experimentKey: EXPERIMENT,
+    waitlistKey: "early_bird",
+    q1: "solo_builder",
+    q3: "Our site never ships.",
+    name: "Alice",
+    url: "https://alice.example",
+    email: "alice@example.com",
+  },
+  createdAt: new Date("2026-09-03T00:00:00.000Z"),
+};
+
+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.apiToken.findUnique as jest.Mock).mockResolvedValue(null);
+  (prisma.user.findUnique as jest.Mock).mockImplementation(({ where }: { where: { id: string } }) =>
+    Promise.resolve(USERS[where.id] ?? null),
+  );
+  // Only alice owns a lead — matched on the (insensitive) email the SERVICE
+  // derives from the User row, never from the request.
+  (prisma.lead.findFirst as jest.Mock).mockImplementation(
+    ({ where }: { where: { siteId: string; email: { equals: string }; payload: { equals: string } } }) =>
+      Promise.resolve(
+        where.siteId === SITE &&
+          where.email.equals === "alice@example.com" &&
+          where.payload.equals === EXPERIMENT
+          ? ALICE_LEAD
+          : null,
+      ),
+  );
+  (prisma.waitlistScore.findFirst as jest.Mock).mockImplementation(({ where }: { where: { leadId: string } }) =>
+    Promise.resolve(where.leadId === LEAD_ID ? { tier: "hot", score: 12 } : null),
+  );
+  (prisma.flowSession.findFirst as jest.Mock).mockImplementation(({ where }: { where: { leadId: string } }) =>
+    Promise.resolve(
+      where.leadId === LEAD_ID
+        ? { aeoScore: null, completedAt: new Date("2026-09-03T00:00:05.000Z") }
+        : null,
+    ),
+  );
+}
+
+async function buildApp(): Promise<FastifyInstance> {
+  const app = Fastify();
+  await app.register(async (authScope) => {
+    await authScope.register(authPreHandlerPlugin, { frontendOrigin: FRONTEND });
+    await authScope.register(waitlistSignupRoutes);
+  });
+  await app.ready();
+  return app;
+}
+
+const cookie = (token: string) => ({ cookie: `better-auth.session_token=${token}` });
+const URL_ME = `/v1/waitlist-signups/me?experimentKey=${EXPERIMENT}`;
+
+let app: FastifyInstance;
+
+beforeEach(async () => {
+  jest.clearAllMocks();
+  process.env.AILK_SITE_ID = SITE;
+  installFixtureMocks();
+  app = await buildApp();
+});
+
+afterEach(async () => {
+  await app.close();
+});
+
+afterAll(() => {
+  delete process.env.AILK_SITE_ID;
+});
+
+describe("GET /v1/waitlist-signups/me — auth (AC-2/AC-3)", () => {
+  it("no session cookie and no bearer → the preHandler's existing 401, untouched; no User/Lead read", async () => {
+    const res = await app.inject({ method: "GET", url: URL_ME });
+
+    expect(res.statusCode).toBe(401);
+    expect(res.json()).toEqual({ error: "unauthorized" });
+    expect(prisma.user.findUnique).not.toHaveBeenCalled();
+    expect(prisma.lead.findFirst).not.toHaveBeenCalled();
+  });
+
+  it("an expired / unknown cookie → 401", async () => {
+    const res = await app.inject({ method: "GET", url: URL_ME, headers: cookie("cookie_nobody") });
+
+    expect(res.statusCode).toBe(401);
+    expect(prisma.lead.findFirst).not.toHaveBeenCalled();
+  });
+
+  it("unverified email → 403 email_unverified, BEFORE any Lead read", async () => {
+    const res = await app.inject({ method: "GET", url: URL_ME, headers: cookie("cookie_mallory") });
+
+    expect(res.statusCode).toBe(403);
+    expect(res.json()).toEqual({
+      ok: false,
+      error: { code: "email_unverified", message: expect.any(String) },
+    });
+    expect(prisma.lead.findFirst).not.toHaveBeenCalled();
+    expect(prisma.waitlistScore.findFirst).not.toHaveBeenCalled();
+    expect(prisma.flowSession.findFirst).not.toHaveBeenCalled();
+  });
+});
+
+describe("GET /v1/waitlist-signups/me — the read (AC-1/AC-4/AC-6)", () => {
+  it("verified respondent → 200 with exactly the seven keys, parsing under waitlistSignupMeResponseSchema", async () => {
+    const res = await app.inject({ method: "GET", url: URL_ME, headers: cookie("cookie_alice") });
+
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as { ok: true; data: Record<string, unknown> };
+    expect(body.ok).toBe(true);
+    expect(Object.keys(body.data).sort()).toEqual(
+      ["answers", "aeoScore", "completedAt", "experimentKey", "score", "tier", "waitlistKey"].sort(),
+    );
+    expect(waitlistSignupMeResponseSchema.parse(body.data)).toEqual({
+      experimentKey: EXPERIMENT,
+      waitlistKey: "early_bird",
+      completedAt: "2026-09-03T00:00:05.000Z",
+      tier: "hot",
+      score: 12,
+      aeoScore: null,
+      answers: { q3: "Our site never ships." },
+    });
+    // No other payload key leaves the row (name / url / q1 / email).
+    expect(res.body).not.toContain("Alice");
+    expect(res.body).not.toContain("alice.example");
+    expect(res.body).not.toContain("solo_builder");
+    expect(res.body).not.toContain("@example.com");
+  });
+
+  it("verified user with no matching lead → 404 signup_not_found", async () => {
+    const res = await app.inject({ method: "GET", url: URL_ME, headers: cookie("cookie_bob") });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json()).toEqual({
+      ok: false,
+      error: { code: "signup_not_found", message: expect.any(String) },
+    });
+  });
+
+  it("an `email` query parameter is ignored — the SESSION user's signup resolves, never the parameter's", async () => {
+    // bob is verified and owns nothing; naming alice's email must not read alice's row.
+    const smuggled = await app.inject({
+      method: "GET",
+      url: `${URL_ME}&email=alice%40example.com`,
+      headers: cookie("cookie_bob"),
+    });
+    expect(smuggled.statusCode).toBe(404);
+    const bobLeadWhere = (prisma.lead.findFirst as jest.Mock).mock.calls[0][0].where as { email: { equals: string } };
+    expect(bobLeadWhere.email.equals).toBe("bob@example.com");
+
+    // …and alice naming someone else's email still gets HER OWN row.
+    jest.clearAllMocks();
+    installFixtureMocks();
+    const own = await app.inject({
+      method: "GET",
+      url: `${URL_ME}&email=bob%40example.com`,
+      headers: cookie("cookie_alice"),
+    });
+    expect(own.statusCode).toBe(200);
+    expect((own.json() as { data: { waitlistKey: string } }).data.waitlistKey).toBe("early_bird");
+    const aliceLeadWhere = (prisma.lead.findFirst as jest.Mock).mock.calls[0][0].where as { email: { equals: string } };
+    expect(aliceLeadWhere.email.equals).toBe("alice@example.com");
+  });
+
+  it("missing or malformed experimentKey → 400 validation_failed, no read", async () => {
+    const missing = await app.inject({ method: "GET", url: "/v1/waitlist-signups/me", headers: cookie("cookie_alice") });
+    expect(missing.statusCode).toBe(400);
+    expect((missing.json() as { error: { code: string } }).error.code).toBe("validation_failed");
+
+    const malformed = await app.inject({
+      method: "GET",
+      url: "/v1/waitlist-signups/me?experimentKey=Not%20A%20Slug",
+      headers: cookie("cookie_alice"),
+    });
+    expect(malformed.statusCode).toBe(400);
+    expect(prisma.lead.findFirst).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,101 @@
+/**
+ * Waitlist-signups respondent route (#4731 D1 — the Phase C dependency of
+ * the AILK diagnostic, samhenry#152 AC-7).
+ *
+ * Routes:
+ *   GET /v1/waitlist-signups/me?experimentKey=<slug>  — the caller's OWN newest signup
+ *
+ * Registered INSIDE server.ts's `authScope` (auth only — NOT the inner
+ * `tenantScope`: a respondent has no workspace membership, and the tenant
+ * guard is default-deny) so `request.userId` is populated by
+ * `authPreHandlerPlugin` before the handler runs. An unauthenticated caller
+ * receives the preHandler's existing 401, untouched. The identity is
+ * `request.userId` ONLY: the route never accepts an `email` parameter (the
+ * query schema declares `experimentKey` alone; anything else is stripped,
+ * never read), never enumerates, never reads across sites — see
+ * `services/waitlist-signups.ts`.
+ *
+ * Envelope per apps/api/CLAUDE.md: `{ ok: true, data }` /
+ * `{ ok: false, error: { code, message } }`, real HTTP status codes:
+ *   400 validation_failed · 401 unauthorized · 403 email_unverified ·
+ *   404 signup_not_found · 500 internal_error (the 200 body failed its own
+ *   contract schema — a drift is never a leak).
+ *
+ * API↔MCP parity: identity-bound (the session IS the identity; the OSS MCP
+ * surface is identity-blind) — no MCP twin (#3591 exception, the same shape
+ * as `/v1/billing/*`, `/v1/workspaces/*`, `/v1/waitlist-experiments/*`).
+ */
+import { logger } from "@working-theory/observability";
+import {
+  flowSlugSchema,
+  waitlistSignupMeResponseSchema,
+} from "@working-theory/validation";
+import type { FastifyPluginAsync, FastifyReply } from "fastify";
+import { z } from "zod";
+
+import { readMySignup } from "../../services/waitlist-signups.js";
+
+/** Boundary validation (D2): `experimentKey` is the ONLY declared query key. */
+const meQuerySchema = z.object({ experimentKey: flowSlugSchema });
+
+function unauthorized(reply: FastifyReply) {
+  return reply.status(401).send({
+    ok: false,
+    error: { code: "unauthorized", message: "Authentication required" },
+  });
+}
+
+function invalidQuery(reply: FastifyReply) {
+  return reply.status(400).send({
+    ok: false,
+    error: { code: "validation_failed", message: "Invalid experimentKey" },
+  });
+}
+
+const ERROR_STATUS = {
+  not_found_user: 404,
+  email_unverified: 403,
+  signup_not_found: 404,
+} as const;
+
+/** `not_found_user` is reported as `signup_not_found` — the row cannot exist for a user that does not. */
+const ERROR_CODE = {
+  not_found_user: "signup_not_found",
+  email_unverified: "email_unverified",
+  signup_not_found: "signup_not_found",
+} as const;
+
+export const waitlistSignupRoutes: FastifyPluginAsync = async (fastify) => {
+  fastify.get("/v1/waitlist-signups/me", async (request, reply) => {
+    const userId = request.userId;
+    if (!userId) return unauthorized(reply);
+
+    const query = meQuerySchema.safeParse(request.query);
+    if (!query.success) return invalidQuery(reply);
+
+    const result = await readMySignup(userId, query.data.experimentKey);
+    if (!result.ok) {
+      return reply.status(ERROR_STATUS[result.error.kind]).send({
+        ok: false,
+        error: { code: ERROR_CODE[result.error.kind], message: result.error.message },
+      });
+    }
+
+    // D5 — re-validate the body against its own strict contract before it
+    // leaves the process (the waitlist-experiments `respond.ts` idiom): a
+    // shape drift is an internal error, never a leak. Log issues only —
+    // never the value.
+    const parsed = waitlistSignupMeResponseSchema.safeParse(result.value);
+    if (!parsed.success) {
+      logger.error(
+        { route: "waitlist-signups/me", issues: parsed.error.issues },
+        "[waitlist-signups] response failed its own contract schema",
+      );
+      return reply.status(500).send({
+        ok: false,
+        error: { code: "internal_error", message: "Response failed contract validation" },
+      });
+    }
+    return reply.status(200).send({ ok: true, data: parsed.data });
+  });
+};