create-ailk 0.24.0 → 0.26.0

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

@@ -1,416 +0,0 @@
-/**
- * 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, on its
- * null-binding branch only (the session carries no active workspace), calls
- * `resolveDefaultTenantForOperator` — the same pinned, verified-operator entry
- * point the base guard uses (#7523). Its explicit-binding branch never reaches
- * this file. Without the module, `middleware/default-tenant.ts` calls
- * `resolveDefaultTenantForOperator` directly. There is one resolution, behind
- * one pin check, 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,
-  OPERATOR_MEMBERSHIP_ID,
-  resolveDefaultWorkspaceRow as resolveDefaultWorkspaceRowShared,
-} from "@working-theory/database/tenancy";
-import type { Id } from "@working-theory/ids";
-import {
-  AGENT_GRANTABLE_PERMISSIONS,
-  can,
-  lowerRole,
-  type AgentGrantablePermission,
-} from "@working-theory/validation";
-
-import type { AgentGrant } from "../lib/agent-store.js";
-import { prisma } from "../lib/prisma.js";
-
-import { findVerifiedEmail } from "./verified-email.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;
-  /**
-   * Set ONLY on an agent's tenant (#7864 D3), and only when at least one of
-   * its grants survives the clamp: the grantable permissions it holds on top
-   * of its role. A person's tenant never carries it. Read through
-   * `@working-theory/validation`'s `allows`.
-   */
-  grants?: readonly AgentGrantablePermission[];
-  /**
-   * Set ONLY by `agentTenant` (#8514 D4); a person's tenant never carries it.
-   * `@working-theory/validation`'s `roleAllows` / `allows` read it to withhold
-   * `AGENT_WITHHELD_PERMISSIONS` from an agent's role, and both tenant guards
-   * refuse an agent request whose tenant lacks it (fail closed).
-   */
-  agent?: true;
-}
-
-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 VERIFIED
- * `User.email` matches it (#5701 AC-2 — the read goes through
- * `findVerifiedEmail`, so an unverified address is refused here and not only
- * at the base-build entry above); 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) {
-    // The verified-email read is `services/verified-email.ts` (#5701 D4) — the
-    // same one `resolveDefaultTenantForOperator` uses. It returns the address
-    // only when `emailVerified === true`, so an address that merely CLAIMS to
-    // be the pin can no longer mint `OPERATOR_MEMBERSHIP_ID`. Both refusals
-    // (`user_not_found`, `email_unverified`) take the branch's existing early
-    // return — the caller is then unbound and denied by the
-    // `membership.findUnique` that follows.
-    const verified = await findVerifiedEmail(userId);
-    if (!verified.ok) {
-      return;
-    }
-    if (verified.value.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 BOTH PATHS NEED THIS. 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-operator-reads.ts`'s `isPlatformOperator`, which grants
- * `{kind: "all"}` — every site's rows, unfiltered — to an `owner` of the
- * sentinel default Organization. Until #7523 that predicate never compared the
- * caller to the pin; the pin was an on/off switch for it. It now goes through
- * `isPinnedOperator` below too, but the bind is the half this function closes.
- *
- * 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 reached the same race the same way: its null-binding
- * branch called `resolveDefaultTenant` directly, so on a one-workspace
- * multi-tenant deployment with the pin unset the first signed-in caller to
- * touch a tenant route from `apps/web` (whose sessions never carry an active
- * workspace) was seated as owner. Since #7523 that branch calls this wrapper
- * too (docs/specs/7523-a-multi-tenant-session-with-spec.md D1), so a session
- * with no active workspace is granted the default tenant only when its
- * caller is the pinned, verified operator. Sessions that DO carry an active
- * workspace — every Admin-app request — never reach this function.
- *
- * `docs/specs/single-tenant-owner-pin-spec.md` D5 already recommended pinning;
- * on both paths it is now 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. `apps/web/auth.ts` no longer configures social providers only: it also
- * enables email+password and magic-link sign-in, so the address can be
- * caller-chosen. Only a VERIFIED row is compared (`findVerifiedEmail`), and
- * verifying it needs a mailbox proof, so a second row for the pin's address
- * in a different case is reachable only by someone who controls that
- * mailbox. The durable fix is still 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> {
-  return (await isPinnedOperator(userId)) ? resolveDefaultTenant(userId) : null;
-}
-
-/**
- * An agent's tenant (#3591 D5, #7864): its person's tenant with the role
- * clamped to the agent's ceiling and, when any survive, the agent's grants
- * that its person's own role holds. `grants` is omitted when none survive,
- * so an agent with no effective grant is the same shape as before. It always
- * carries `agent: true` (#8514 D4), which withholds the client-keeping rows a
- * member holds by role.
- *
- * The one clamp both tenant guards apply — `resolveAgentTenant` (multi-tenant)
- * and `resolveDefaultTenantForAgent` (base build) — so the two builds cannot
- * hold an agent to different rules.
- */
-export function agentTenant(
-  personTenant: TenantContext,
-  agent: AgentGrant,
-): TenantContext {
-  const role = lowerRole(personTenant.role, agent.permissionLevel);
-  // D1 order, no duplicates, only the five, and only what the person holds.
-  const grants = AGENT_GRANTABLE_PERMISSIONS.filter(
-    (p) => agent.grants.includes(p) && can(personTenant.role, p),
-  );
-  return grants.length > 0
-    ? { ...personTenant, role, agent: true, grants }
-    : { ...personTenant, role, agent: true };
-}
-
-/**
- * The base-build grant for an AGENT (#3591 spec D5, D7). The same steps as
- * `resolveDefaultTenantForOperator` — the pin check, then the default
- * resolution and its one Membership read — so an agent and its person's
- * session drive the same reads. On top of them: the resolved workspace must
- * be the one the agent is bound to, and the Membership the read found must be
- * the one the agent was created under. The tenant is then clamped
- * (`agentTenant`), so the operator's agent acts as a member plus the grants
- * the operator holds.
- *
- * The membership id is compared here rather than carried on `TenantContext`,
- * which stays one shape for every caller. On a base build only the pinned,
- * verified operator holds a membership this admits, so only the operator's
- * agents, bound to the default workspace, ever pass.
- */
-export async function resolveDefaultTenantForAgent(
-  userId: Id<"user">,
-  agent: AgentGrant,
-): Promise<TenantContext | null> {
-  if (!(await isPinnedOperator(userId))) return null;
-  const granted = await resolveDefaultGrant(userId);
-  if (
-    !granted ||
-    granted.tenant.workspaceId !== agent.workspaceId ||
-    granted.tenant.organizationId !== agent.organizationId ||
-    granted.membershipId !== agent.responsibleMembershipId
-  ) {
-    return null;
-  }
-  return agentTenant(granted.tenant, agent);
-}
-
-/**
- * The one pin-match predicate in `apps/api` (#7523 D2): `true` only when
- * `AILK_OPERATOR_EMAIL` is set and the caller's VERIFIED `User.email` equals
- * it. Both sides are trimmed and lowercased; a blank pin counts as unset and
- * refuses before any read, so it can never "match" a blank `User.email`.
- *
- * Shared by the two tenant guards (through `resolveDefaultTenantForOperator`)
- * and by `services/waitlist-operator-reads.ts`'s `isPlatformOperator`. It
- * lives in this base-build file because that operator-read file rides more
- * than one module slice and may import only files every build ships.
- * `bindOperatorMembership` keeps its own inline check: it must allow a bind
- * when the pin is unset, which this predicate never does.
- */
-export async function isPinnedOperator(userId: Id<"user">): Promise<boolean> {
-  const pinnedEmail = process.env.AILK_OPERATOR_EMAIL?.trim().toLowerCase();
-  if (!pinnedEmail) {
-    return false;
-  }
-  // The verified-email read is `services/verified-email.ts` (#5701 D4) — the
-  // one this and the four other email-keyed paths share. It returns the
-  // address only when `emailVerified === true`, which is what makes a match
-  // against the pin a proven claim rather than an asserted one.
-  const verified = await findVerifiedEmail(userId);
-  if (!verified.ok) {
-    return false;
-  }
-  return verified.value.email.trim().toLowerCase() === pinnedEmail;
-}
-
-/**
- * The DEPLOYMENT half of the default resolution, extracted so it exists once
- * (#5852 D2). Returns the sole, well-known default Workspace row, or `null`
- * the instant the deployment is not unambiguously one-workspace — a second
- * Workspace exists, none does, or the sole one is not the seeded default.
- *
- * Carries no authentication: it answers "is this deployment one-workspace, and
- * which workspace is it", nothing about the caller. `resolveDefaultTenant`
- * adds the authentication half on top; `services/public-site-resolver.ts`
- * (unauthenticated public reads) uses the deployment half alone. One
- * predicate, reached two ways — never two predicates.
- *
- * The predicate itself is `@working-theory/database/tenancy`'s
- * `resolveDefaultWorkspaceRow` (#5876 spec D2/D3) — this is now a thin
- * pass-through of `apps/api`'s own `prisma` singleton, kept as a named local
- * function (rather than re-exporting the shared one directly) so every
- * existing caller — this file's own `resolveDefaultWorkspaceId` and
- * `resolveDefaultTenant`, and `services/public-site-resolver.ts`'s dynamic
- * import of the wrapper — is untouched. There is exactly one implementation
- * of the one-workspace predicate in the repository (NFR-7); apps/mcp's own
- * resolution (`apps/mcp/src/lib/public-workspace.ts`) delegates to the same
- * shared export.
- */
-async function resolveDefaultWorkspaceRow(): Promise<{
-  id: string;
-  organizationId: string;
-} | null> {
-  return resolveDefaultWorkspaceRowShared(prisma);
-}
-
-/**
- * The one-workspace deployment predicate, as a workspace id (#5852 D2).
- * `null` means the deployment is not unambiguously one-workspace, and every
- * caller fails closed on it.
- */
-export async function resolveDefaultWorkspaceId(): Promise<Id<"workspace"> | null> {
-  const workspace = await resolveDefaultWorkspaceRow();
-  return workspace ? (workspace.id as Id<"workspace">) : null;
-}
-
-/**
- * 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> {
-  return (await resolveDefaultGrant(userId))?.tenant ?? null;
-}
-
-/**
- * `resolveDefaultTenant`'s body, also handing back the id of the Membership
- * it read, which the agent path compares (#3591 D5). One read serves both:
- * its `select` is widened from `{ role }` to `{ id, role }`.
- */
-async function resolveDefaultGrant(
-  userId: Id<"user">,
-): Promise<{ tenant: TenantContext; membershipId: string } | null> {
-  const workspace = await resolveDefaultWorkspaceRow();
-  if (!workspace) {
-    return null;
-  }
-  await bindOperatorMembership(userId);
-  const membership = await prisma.membership.findUnique({
-    where: {
-      organizationId_userId: {
-        organizationId: workspace.organizationId,
-        userId,
-      },
-    },
-    select: { id: true, role: true },
-  });
-  if (!membership) {
-    return null;
-  }
-  return {
-    tenant: {
-      userId,
-      organizationId: workspace.organizationId as Id<"organization">,
-      workspaceId: workspace.id as Id<"workspace">,
-      role: membership.role as MembershipRole,
-    },
-    membershipId: membership.id,
-  };
-}