create-ailk 0.3.0 → 0.5.0

package/templates/apps/api/src/services/__tests__/leads-inbox.test.ts

@@ -0,0 +1,329 @@
+/**
+ * @file leads-inbox.test.ts
+ * @description Unit tests for the leads-inbox read service (#5678).
+ *
+ * The load-bearing case is ISOLATION: this endpoint returns contact PII, so
+ * the claim "a caller cannot read another site's leads" is tested, not argued.
+ *
+ * External dependency boundary mocked:
+ *   - apps/api/src/lib/prisma — the repo-standard `__mocks__/prisma.ts` manual
+ *     mock (`jest.mock("../../lib/prisma.js")`).
+ *
+ * `prisma.lead.findMany` / `findFirst` are given a REALISTIC filtering
+ * implementation over an in-memory fixture "table" rather than a static
+ * `mockResolvedValue`, mirroring `lead-promotion.test.ts`. That is what makes
+ * the isolation test real: a bug that widened the `siteId` match set would
+ * surface the other site's lead in the returned page, not merely in an
+ * argument-shape assertion.
+ *
+ * `tenant-context.ts`'s `listTenancy` runs REAL — a pure read over the mocked
+ * `prisma.membership.findMany` — so these tests also exercise the
+ * "resolve through `lead-promotion.ts`'s `resolveOwnerWorkspaces`" contract
+ * rather than re-stubbing it.
+ */
+
+// eslint-disable-next-line no-restricted-syntax -- lib/prisma.ts wraps the external DB boundary (PrismaClient requires a live connection); __mocks__/prisma.ts is the repo-standard test double for this boundary.
+jest.mock("../../lib/prisma.js");
+
+import type { Id } from "@working-theory/ids";
+
+import { prisma } from "../../lib/prisma.js";
+import { listOwnedLeads } from "../leads-inbox";
+
+// ─── Fixtures ─────────────────────────────────────────────────────────────────
+
+const USER_ID = "user_00000000-0000-7000-8000-0000000000a1" as Id<"user">;
+const OWN_ORG_ID = "org_00000000-0000-7000-8000-0000000000b1";
+/** The caller's own workspace — and therefore the `siteId` of their own leads. */
+const OWN_SITE_ID = "wksp_00000000-0000-7000-8000-0000000000c1";
+/** A DIFFERENT organization's workspace. The caller holds no membership in it. */
+const OTHER_SITE_ID = "wksp_00000000-0000-7000-8000-0000000000c2";
+
+type FakeLeadRow = {
+  id: string;
+  siteId: string;
+  email: string;
+  source: string;
+  payload: unknown;
+  createdAt: Date;
+};
+
+/** Shapes `prisma.membership.findMany`'s return — what `listTenancy` reads. */
+function membershipsWithRole(role: string) {
+  return [
+    {
+      role,
+      organization: {
+        id: OWN_ORG_ID,
+        name: "Acme",
+        slug: "acme",
+        workspaces: [{ id: OWN_SITE_ID, name: "Acme HQ", slug: "acme-hq" }],
+      },
+    },
+  ];
+}
+
+function lead(overrides: Partial<FakeLeadRow> & { id: string }): FakeLeadRow {
+  return {
+    siteId: OWN_SITE_ID,
+    email: "contact@example.com",
+    source: "web",
+    payload: { name: "Ada Lovelace", message: "please call me", phone: "555" },
+    createdAt: new Date("2026-09-15T12:00:00.000Z"),
+    ...overrides,
+  };
+}
+
+/**
+ * Wires `prisma.lead.findFirst` / `findMany` to a realistic in-memory "table"
+ * filtered by the `where` the service passes — so a row outside `siteId.in` is
+ * genuinely never returned, exactly as a real WHERE clause would exclude it.
+ */
+function seedLeadTable(rows: FakeLeadRow[]) {
+  const table = rows.map((r) => ({ ...r }));
+
+  type Where = {
+    siteId: { in: string[] };
+    id?: string;
+    OR?: Array<{
+      createdAt?: Date | { lt: Date };
+      id?: { lt: string };
+    }>;
+  };
+
+  const inScope = (row: FakeLeadRow, where: Where) =>
+    where.siteId.in.includes(row.siteId) &&
+    (where.id === undefined || row.id === where.id);
+
+  const afterCursor = (row: FakeLeadRow, where: Where) => {
+    if (!where.OR) return true;
+    return where.OR.some((clause) => {
+      if (clause.createdAt instanceof Date) {
+        return (
+          row.createdAt.getTime() === clause.createdAt.getTime() &&
+          clause.id !== undefined &&
+          row.id < clause.id.lt
+        );
+      }
+      const lt = (clause.createdAt as { lt: Date }).lt;
+      return row.createdAt.getTime() < lt.getTime();
+    });
+  };
+
+  (prisma.lead.findFirst as jest.Mock).mockImplementation(
+    async (args: { where: Where }) =>
+      table.find((row) => inScope(row, args.where)) ?? null,
+  );
+
+  (prisma.lead.findMany as jest.Mock).mockImplementation(
+    async (args: { where: Where; take: number }) =>
+      table
+        .filter((row) => inScope(row, args.where) && afterCursor(row, args.where))
+        .sort((a, b) =>
+          b.createdAt.getTime() - a.createdAt.getTime() || (a.id < b.id ? 1 : -1),
+        )
+        .slice(0, args.take),
+  );
+
+  return table;
+}
+
+describe("listOwnedLeads", () => {
+  // The workspace resolution is module-conditional (isModuleEnabled
+  // 'multi-tenant' — see lead-promotion.ts), so every test that expects rows
+  // needs the module explicitly enabled: AILK_ENABLED_MODULES unset means no
+  // paid modules (D-44, #5368).
+  const priorEnabledModules = process.env.AILK_ENABLED_MODULES;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    process.env.AILK_ENABLED_MODULES = "multi-tenant";
+  });
+
+  afterAll(() => {
+    if (priorEnabledModules === undefined) {
+      delete process.env.AILK_ENABLED_MODULES;
+    } else {
+      process.env.AILK_ENABLED_MODULES = priorEnabledModules;
+    }
+  });
+
+  // ── ISOLATION (load-bearing) ───────────────────────────────────────────────
+  it("never returns a lead whose siteId belongs to another site", async () => {
+    (prisma.membership.findMany as jest.Mock).mockResolvedValue(
+      membershipsWithRole("owner"), // the caller belongs ONLY to OWN_ORG_ID
+    );
+    seedLeadTable([
+      lead({
+        id: "lead_own_1",
+        siteId: OWN_SITE_ID,
+        email: "mine@example.com",
+        createdAt: new Date("2026-09-15T12:00:00.000Z"),
+      }),
+      lead({
+        id: "lead_other_1",
+        siteId: OTHER_SITE_ID,
+        email: "theirs@example.com",
+        createdAt: new Date("2026-09-15T13:00:00.000Z"), // NEWER — would sort first
+      }),
+    ]);
+
+    const result = await listOwnedLeads({ userId: USER_ID, limit: 50 });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.items.map((row) => row.id)).toEqual(["lead_own_1"]);
+    expect(JSON.stringify(result.value)).not.toContain("theirs@example.com");
+    expect(JSON.stringify(result.value)).not.toContain(OTHER_SITE_ID);
+    // The scope reaches the DB as a filter, not a post-filter in JS.
+    expect(prisma.lead.findMany).toHaveBeenCalledWith(
+      expect.objectContaining({ where: expect.objectContaining({ siteId: { in: [OWN_SITE_ID] } }) }),
+    );
+  });
+
+  it("returns an empty page when the caller belongs to no workspace at all", async () => {
+    (prisma.membership.findMany as jest.Mock).mockResolvedValue([]);
+    seedLeadTable([lead({ id: "lead_other_1", siteId: OTHER_SITE_ID })]);
+
+    const result = await listOwnedLeads({ userId: USER_ID, limit: 50 });
+
+    expect(result).toEqual({ ok: true, value: { items: [], nextCursor: null } });
+    // No workspace means no query at all — not a query with an empty `in`.
+    expect(prisma.lead.findMany).not.toHaveBeenCalled();
+  });
+
+  it("returns an empty page for a `member` — the role floor is owner|admin", async () => {
+    (prisma.membership.findMany as jest.Mock).mockResolvedValue(
+      membershipsWithRole("member"),
+    );
+    seedLeadTable([lead({ id: "lead_own_1", siteId: OWN_SITE_ID })]);
+
+    const result = await listOwnedLeads({ userId: USER_ID, limit: 50 });
+
+    expect(result).toEqual({ ok: true, value: { items: [], nextCursor: null } });
+    expect(prisma.lead.findMany).not.toHaveBeenCalled();
+  });
+
+  it("rejects a cursor that resolves outside the caller's scope", async () => {
+    (prisma.membership.findMany as jest.Mock).mockResolvedValue(
+      membershipsWithRole("admin"),
+    );
+    seedLeadTable([
+      lead({ id: "lead_own_1", siteId: OWN_SITE_ID }),
+      lead({ id: "lead_other_1", siteId: OTHER_SITE_ID }),
+    ]);
+
+    const result = await listOwnedLeads({
+      userId: USER_ID,
+      cursor: "lead_other_1",
+      limit: 50,
+    });
+
+    expect(result).toEqual({
+      ok: false,
+      error: {
+        kind: "invalid_cursor",
+        message: "cursor does not resolve within this scope",
+      },
+    });
+    // The rejection is indistinguishable from "no such lead" — a foreign
+    // cursor is never a probe that confirms another site's row exists.
+    expect(prisma.lead.findMany).not.toHaveBeenCalled();
+  });
+
+  // ── Row shape (the PII floor) ──────────────────────────────────────────────
+  it("returns exactly the five rendered fields — never the rest of the record", async () => {
+    (prisma.membership.findMany as jest.Mock).mockResolvedValue(
+      membershipsWithRole("owner"),
+    );
+    seedLeadTable([
+      lead({
+        id: "lead_own_1",
+        email: "ada@example.com",
+        source: "conversational-intake",
+        payload: { name: "Ada Lovelace", message: "please call me", phone: "555-0100" },
+      }),
+    ]);
+
+    const result = await listOwnedLeads({ userId: USER_ID, limit: 50 });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.items).toEqual([
+      {
+        id: "lead_own_1",
+        name: "Ada Lovelace",
+        email: "ada@example.com",
+        source: "conversational-intake",
+        createdAt: "2026-09-15T12:00:00.000Z",
+      },
+    ]);
+    // The rest of `payload` is never on the wire.
+    const serialized = JSON.stringify(result.value);
+    expect(serialized).not.toContain("please call me");
+    expect(serialized).not.toContain("555-0100");
+    expect(serialized).not.toContain("siteId");
+  });
+
+  it("truncates an unbounded name — one anonymous write cannot size the page", async () => {
+    // PR #5705 security review, finding 1: `boundedLeadPayload` bounds the
+    // payload at 64 KEYS and nothing else, and `POST /v1/leads/submit` is
+    // anonymous with no ownership check on `siteId`, so a stranger can plant a
+    // ~1 MB `name` in the owner's inbox. Ordering is `createdAt desc` and this
+    // unit ships no delete surface, so it would sit on page one for good.
+    (prisma.membership.findMany as jest.Mock).mockResolvedValue(
+      membershipsWithRole("owner"),
+    );
+    seedLeadTable([
+      lead({ id: "lead_own_1", payload: { name: "A".repeat(900_000) } }),
+    ]);
+
+    const result = await listOwnedLeads({ userId: USER_ID, limit: 50 });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.items[0]?.name).toBe("A".repeat(200));
+    expect(JSON.stringify(result.value).length).toBeLessThan(1000);
+  });
+
+  it("reads `name` as null when the site's form captured none", async () => {
+    (prisma.membership.findMany as jest.Mock).mockResolvedValue(
+      membershipsWithRole("owner"),
+    );
+    seedLeadTable([lead({ id: "lead_own_1", payload: { company: "Acme" } })]);
+
+    const result = await listOwnedLeads({ userId: USER_ID, limit: 50 });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.items[0]?.name).toBeNull();
+  });
+
+  // ── Pagination ─────────────────────────────────────────────────────────────
+  it("pages newest first and hands back the last row's id as nextCursor", async () => {
+    (prisma.membership.findMany as jest.Mock).mockResolvedValue(
+      membershipsWithRole("owner"),
+    );
+    seedLeadTable([
+      lead({ id: "lead_a", createdAt: new Date("2026-09-15T10:00:00.000Z") }),
+      lead({ id: "lead_b", createdAt: new Date("2026-09-15T11:00:00.000Z") }),
+      lead({ id: "lead_c", createdAt: new Date("2026-09-15T12:00:00.000Z") }),
+    ]);
+
+    const first = await listOwnedLeads({ userId: USER_ID, limit: 2 });
+    expect(first.ok).toBe(true);
+    if (!first.ok) return;
+    expect(first.value.items.map((row) => row.id)).toEqual(["lead_c", "lead_b"]);
+    expect(first.value.nextCursor).toBe("lead_b");
+
+    const second = await listOwnedLeads({
+      userId: USER_ID,
+      cursor: first.value.nextCursor ?? undefined,
+      limit: 2,
+    });
+    expect(second.ok).toBe(true);
+    if (!second.ok) return;
+    expect(second.value.items.map((row) => row.id)).toEqual(["lead_a"]);
+    expect(second.value.nextCursor).toBeNull();
+  });
+});

package/templates/apps/api/src/services/default-tenant.ts

@@ -0,0 +1,261 @@
+/**
+ * Default-tenant resolution — the BASE-build half of the tenant guard (#5677).
+ *
+ * A single-tenant site is a ONE-WORKSPACE TENANT, not a special case. The
+ * default Organization / Workspace / operator Membership are already declared
+ * as fixed reserved-range sentinels in `database/tenancy.ts` and already
+ * seeded by `database/seed.ts`, so there is nothing to synthesize here — this
+ * file resolves the seeded default and nothing else.
+ *
+ * WHY IT LIVES IN THE BASE BUILD. `services/tenant-context.ts` and
+ * `middleware/tenant.ts` are multi-tenant SLICE files (`// oss: false`), so on
+ * a build without that module they are not present and the routes behind them
+ * were never REGISTERED — not denied (#5677). The default
+ * resolution and the `TenantContext` shape it yields are needed on every
+ * build, so they live here, in a file that always ships; the multi-tenant
+ * slice imports this one rather than carrying its own copy, which is what
+ * keeps the two paths from drifting.
+ *
+ * PRECEDENCE, NOT PARALLELISM. When the multi-tenant module is present,
+ * `resolveActiveTenant` (the slice) is the entry point and calls
+ * `resolveDefaultTenant` only on the branch it always called it on — the
+ * previously-unconditional-deny null-binding branch. Nothing about the
+ * multi-tenant path changes. Without the module, `middleware/default-tenant.ts`
+ * calls this directly. There is one resolution, reached two ways, never two
+ * resolutions.
+ *
+ * DEFAULT-DENY IS THE FLOOR. `resolveDefaultTenant` returns `null` — never a
+ * grant — the instant the deployment is not unambiguously single-tenant
+ * (a second Workspace exists, or the sole Workspace is not the well-known
+ * default), and `null` again for a caller holding no Membership on the default
+ * Organization. Both branches were written for the multi-tenant slice by the
+ * owner-pin fix (docs/specs/single-tenant-owner-pin-spec.md, #3631) and are
+ * moved here BYTE-FOR-BYTE, not rewritten.
+ *
+ * This file is a sanctioned exception to architecture.yaml's tenant-scope
+ * forbidden pattern, for the same reason `tenant-context.ts` is: it is a
+ * tenancy-model boundary, not a domain-data reader.
+ */
+import {
+  DEFAULT_ORG_ID,
+  DEFAULT_WORKSPACE_ID,
+  OPERATOR_MEMBERSHIP_ID,
+} from "@working-theory/database/tenancy";
+import { isSentinel, type Id } from "@working-theory/ids";
+
+import { prisma } from "../lib/prisma.js";
+
+export type MembershipRole = "owner" | "admin" | "member";
+
+/**
+ * The tenant scope every domain query is bound to. Ids carry the ADR-0031
+ * brand; values originating from Prisma reads are brand-asserted at the read
+ * edge (the DB CHECK constraints are the runtime guarantee).
+ */
+export interface TenantContext {
+  userId: Id<"user">;
+  organizationId: Id<"organization">;
+  workspaceId: Id<"workspace">;
+  role: MembershipRole;
+}
+
+export type TenantErrorKind = "forbidden" | "not_found" | "conflict";
+
+export type TenantResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; error: { kind: TenantErrorKind; message: string } };
+
+export function isUniqueViolation(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as { code?: unknown }).code === "P2002"
+  );
+}
+
+/**
+ * TOFU-binds the operator Membership for a single-tenant deployment (spec
+ * D1–D4) — the replacement for the deleted user-agnostic `owner` grant. The
+ * Membership is created with a fixed, well-known id
+ * (`OPERATOR_MEMBERSHIP_ID`); the `Membership.id` primary-key uniqueness —
+ * not a read-then-write "is this the first user?" guard — enforces exactly
+ * one owner under a concurrent first-login race. The losing caller's
+ * `create` raises `P2002`, swallowed here: that caller is then unbound and
+ * denied by the `membership.findUnique` the caller of this function runs
+ * next.
+ *
+ * Idempotent + at-most-once: a caller who already holds the Membership (a
+ * repeat call, or the deployment's steady state after the first bind) hits
+ * the same `P2002` path and is a no-op. Reachable ONLY from
+ * `resolveDefaultTenant`, itself gated by the
+ * `count === 1 && default-workspace-exists` check — unreachable from any
+ * multi-tenant state (`count > 1`).
+ *
+ * When `AILK_OPERATOR_EMAIL` is set (spec D4 — trimmed + lowercased before
+ * comparison), the bind is attempted ONLY for the caller whose `User.email`
+ * matches it; every other caller returns without writing and is denied
+ * downstream. An empty/whitespace-only `AILK_OPERATOR_EMAIL` normalizes to
+ * `""`, which is falsy — treated as unset (pure TOFU), so a blank pin can
+ * never "match" a blank `User.email`. When unset, the bind is pure TOFU —
+ * first caller wins.
+ */
+async function bindOperatorMembership(userId: Id<"user">): Promise<void> {
+  const pinnedEmail = process.env.AILK_OPERATOR_EMAIL?.trim().toLowerCase();
+  if (pinnedEmail) {
+    const user = await prisma.user.findUnique({
+      where: { id: userId },
+      select: { email: true },
+    });
+    if (!user || user.email.trim().toLowerCase() !== pinnedEmail) {
+      return;
+    }
+  }
+  try {
+    await prisma.membership.create({
+      data: {
+        id: OPERATOR_MEMBERSHIP_ID,
+        organizationId: DEFAULT_ORG_ID,
+        userId,
+        role: "owner",
+      },
+    });
+  } catch (error) {
+    if (!isUniqueViolation(error)) {
+      throw error;
+    }
+    // Another caller already holds OPERATOR_MEMBERSHIP_ID (the TOFU race
+    // winner, or a prior deployment run) — swallow and fall through.
+  }
+}
+
+/**
+ * The BASE-BUILD entry point: `resolveDefaultTenant` narrowed to the caller
+ * whose `User.email` matches `AILK_OPERATOR_EMAIL`, denying everyone when the
+ * pin is unset (#5693 security review, High finding).
+ *
+ * WHY THE BASE PATH NEEDS THIS AND THE MULTI-TENANT PATH DOES NOT. Registering
+ * the review surface on a module-less build made two things reachable together
+ * that were previously unreachable there: this resolution's TOFU operator bind,
+ * and `services/waitlist-dashboard.ts`'s `isPlatformOperator`, which grants
+ * `{kind: "all"}` — every site's rows, unfiltered — to an `owner` of the
+ * sentinel default Organization whenever `AILK_OPERATOR_EMAIL` is merely SET.
+ * That predicate never compares the caller to the pin; the pin is an on/off
+ * switch for it.
+ *
+ * Unpinned TOFU plus that predicate is an escalation. The site's auth
+ * auto-provisions a `User` on first login, so on a deployment with the pin
+ * unset the FIRST authenticated caller to touch a review route — any public
+ * respondent, not necessarily the operator — wins `OPERATOR_MEMBERSHIP_ID`.
+ * The real operator is then denied (their `create` raises `P2002`, swallowed),
+ * finds an empty dashboard, and sets `AILK_OPERATOR_EMAIL` to fix it — which
+ * flips the squatter, not the operator, to `{kind: "all"}`.
+ *
+ * So the base path requires the pin and requires the caller to BE it. Both
+ * halves matter: requiring the pin stops an unpinned race from seating anyone,
+ * and re-checking the caller's email on every request denies a squatter who
+ * was already bound before this code shipped — a Membership row alone is no
+ * longer enough. `bindOperatorMembership` below performs its own email check,
+ * but only at bind time and only for the bind; this is the one that gates the
+ * grant.
+ *
+ * The multi-tenant module is unaffected: `resolveActiveTenant` keeps calling
+ * `resolveDefaultTenant` directly, on exactly the branch it always called it
+ * on. This wrapper is reached only from `middleware/default-tenant.ts`, which
+ * only ever runs on a build without that module.
+ *
+ * `docs/specs/single-tenant-owner-pin-spec.md` D5 already recommended pinning;
+ * on this path it is mandatory rather than advisory, and unset fails closed.
+ *
+ * ONE KNOWN IMPRECISION, deliberate. `User.email` is `@unique` in Postgres,
+ * which is byte-exact, while this comparison lowercases both sides — so two
+ * distinct rows (`Operator@x.com` and `operator@x.com`) could both satisfy one
+ * pin. It is not reachable today: `apps/web/auth.ts` configures social
+ * providers only, so the address is provider-asserted and normalized rather
+ * than caller-chosen. It becomes reachable the moment a credential provider is
+ * enabled, and the durable fix is case-insensitive email uniqueness in the
+ * schema (citext, or lowercase-at-write) so "matches the pin" and "is unique"
+ * agree. Matching case-sensitively here instead would be worse: it would lock
+ * out an operator who typed their own address with different capitalisation.
+ */
+export async function resolveDefaultTenantForOperator(
+  userId: Id<"user">,
+): Promise<TenantContext | null> {
+  const pinnedEmail = process.env.AILK_OPERATOR_EMAIL?.trim().toLowerCase();
+  if (!pinnedEmail) {
+    return null;
+  }
+  const user = await prisma.user.findUnique({
+    where: { id: userId },
+    select: { email: true, emailVerified: true },
+  });
+  // `emailVerified` is load-bearing wherever this codebase joins an identity
+  // to data by email — the respondent reads (`services/waitlist-signups.ts`,
+  // `services/flow-checkouts.ts`) refuse before any Lead read for the same
+  // reason. An unverified address is an unproven claim to the pinned one.
+  if (!user || !user.emailVerified) {
+    return null;
+  }
+  if (user.email.trim().toLowerCase() !== pinnedEmail) {
+    return null;
+  }
+  return resolveDefaultTenant(userId);
+}
+
+/**
+ * Resolves the default single-tenant scope when the deployment is
+ * unambiguously single-tenant — the default Workspace (`DEFAULT_WORKSPACE_ID`)
+ * exists AND it is the ONLY Workspace (`workspace.count() === 1`), the exact
+ * mirror of the Phase-1 provision guard's `count === 0` check (spec D2).
+ * Returns `null` (never grants) the instant a second Workspace exists, or the
+ * sole Workspace is not the well-known default — the caller falls through to
+ * its own default-deny in that case.
+ *
+ * Converges on the SAME Membership-based authz the multi-tenant path uses
+ * (spec D1 — the fix): attempts to TOFU-bind the caller as operator
+ * (`bindOperatorMembership`, a no-op once an operator is already bound or
+ * the caller doesn't match the optional env pin), then runs the real
+ * `membership.findUnique` check. A caller holding no Membership on the
+ * default Org — including every caller after the first once TOFU has bound
+ * someone else — resolves `null` here, and the caller denies. There is no
+ * user-agnostic `owner` grant.
+ *
+ * Formerly `resolveSingleTenantDefault` in `services/tenant-context.ts`
+ * (#3631); moved here verbatim by #5677 so the base build can reach it.
+ */
+export async function resolveDefaultTenant(
+  userId: Id<"user">,
+): Promise<TenantContext | null> {
+  const workspaceCount = await prisma.workspace.count();
+  if (workspaceCount !== 1) {
+    return null;
+  }
+  const workspace = await prisma.workspace.findUnique({
+    where: { id: DEFAULT_WORKSPACE_ID },
+    select: { id: true, organizationId: true },
+  });
+  // The default workspace must hang off the sentinel default Organization
+  // (ADR-0031 rule 7): keyed on the reserved-range predicate, not a literal.
+  if (!workspace || !isSentinel(workspace.organizationId)) {
+    return null;
+  }
+  await bindOperatorMembership(userId);
+  const membership = await prisma.membership.findUnique({
+    where: {
+      organizationId_userId: {
+        organizationId: workspace.organizationId,
+        userId,
+      },
+    },
+    select: { role: true },
+  });
+  if (!membership) {
+    return null;
+  }
+  return {
+    userId,
+    organizationId: workspace.organizationId as Id<"organization">,
+    workspaceId: workspace.id as Id<"workspace">,
+    role: membership.role as MembershipRole,
+  };
+}