create-ailk 0.4.0 → 0.5.0

package/templates/apps/api/src/middleware/__tests__/default-tenant.test.ts

@@ -0,0 +1,339 @@
+/**
+ * @file default-tenant.test.ts
+ *
+ * Tenant-isolation coverage for the BASE-build tenant guard (#5677) —
+ * `middleware/default-tenant.ts`, the guard a build WITHOUT the multi-tenant
+ * module runs so the already-built review dashboard is reachable at Pro.
+ *
+ * SECURITY-SENSITIVE (tenant isolation). Two load-bearing groups here. The
+ * OPERATOR-PIN cases are the #5693 security-review remediation: on this build
+ * the review surface and `isPlatformOperator`'s unfiltered `{kind: "all"}`
+ * scope became reachable together, so the guard seats only the caller whose
+ * email matches `AILK_OPERATOR_EMAIL` and seats nobody when it is unset —
+ * including a caller who already holds the operator Membership. The FOREIGN
+ * WORKSPACE case is the other: a single-tenant caller naming another workspace's id in the
+ * URL is refused with the same 403 the paid slice returns, before any lookup
+ * of the target. This proves the base path did not relax the default-deny
+ * posture — it reproduces it. The multi-tenant slice's own isolation tests
+ * (`services/__tests__/tenant-context.test.ts`, #3631) are untouched and cover
+ * the module path.
+ *
+ * Mocks the module-level `prisma` singleton via the repo's manual-mock
+ * convention — `resolveDefaultTenant` reads the singleton directly and has no
+ * DI seam, the same shape `tenant-context.test.ts` uses.
+ */
+
+import Fastify from "fastify";
+import type { FastifyInstance } from "fastify";
+
+// 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 { prisma } from "../../lib/prisma.js";
+import type { Id } from "@working-theory/ids";
+
+import { defaultTenantPreHandlerPlugin } from "../default-tenant.js";
+
+// The reserved-range sentinel values from database/tenancy.ts (ADR-0031
+// rule 7) — re-declared here as literals so the test pins the WIRE values,
+// not whatever the constants happen to be.
+const DEFAULT_ORG_ID = "org_00000000-0000-7000-8000-000000000001";
+const DEFAULT_WORKSPACE_ID = "wksp_00000000-0000-7000-8000-000000000001";
+
+/** A workspace id belonging to somebody else — never this caller's. */
+const FOREIGN_WORKSPACE_ID = "wksp_01936b2c-0000-7000-8000-00000000beef";
+
+const USER_ID = "solo-operator" as Id<"user">;
+const OPERATOR_EMAIL = "operator@example.com";
+
+/**
+ * Stubs the single-tenant prerequisites `resolveDefaultTenant` checks:
+ * `workspace.count() === 1` and the sentinel default Workspace present on the
+ * sentinel default Organization.
+ */
+function mockSingleTenantWorkspace(): void {
+  (prisma.workspace.count as jest.Mock).mockResolvedValue(1);
+  (prisma.workspace.findUnique as jest.Mock).mockResolvedValue({
+    id: DEFAULT_WORKSPACE_ID,
+    organizationId: DEFAULT_ORG_ID,
+  });
+}
+
+/**
+ * The caller holds the operator Membership on the default Organization AND is
+ * the pinned operator — the only combination this guard grants on.
+ */
+function mockBoundOperator(): void {
+  (prisma.user.findUnique as jest.Mock).mockResolvedValue({
+    email: OPERATOR_EMAIL,
+    emailVerified: true,
+  });
+  (prisma.membership.create as jest.Mock).mockResolvedValue({});
+  (prisma.membership.findUnique as jest.Mock).mockResolvedValue({
+    role: "owner",
+  });
+}
+
+/**
+ * Builds an app whose routes sit behind the base guard. `authenticated`
+ * mirrors what the dual-mode auth preHandler decorates upstream: a cookie
+ * session sets both `userId` and `sessionTenant`; a bearer request sets only
+ * `userId`.
+ */
+function buildApp(
+  authenticated: "cookie" | "bearer" | "none" = "cookie",
+): FastifyInstance {
+  const app = Fastify();
+  app.addHook("preHandler", async (req) => {
+    if (authenticated === "none") return;
+    req.userId = USER_ID;
+    if (authenticated === "cookie") {
+      req.sessionTenant = {
+        sessionRowId: "session-1" as Id<"session">,
+        activeOrganizationId: null,
+        activeWorkspaceId: null,
+      };
+    }
+  });
+  app.register(defaultTenantPreHandlerPlugin);
+  app.get("/scoped", async (req) => ({
+    workspaceId: req.tenant?.workspaceId ?? null,
+    role: req.tenant?.role ?? null,
+  }));
+  app.get("/workspaces/:workspaceId/config", async (req) => ({
+    workspaceId: req.tenant?.workspaceId ?? null,
+  }));
+  return app;
+}
+
+const ORIGINAL_ENV = process.env;
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  process.env = { ...ORIGINAL_ENV };
+  // Pinned by default: this guard grants on no other configuration, so the
+  // cases below would all be trivially 403 without it.
+  process.env.AILK_OPERATOR_EMAIL = OPERATOR_EMAIL;
+});
+
+afterAll(() => {
+  process.env = ORIGINAL_ENV;
+});
+
+describe("default tenant guard — isolation (#5677)", () => {
+  it("DENIES a foreign workspaceId with 403, before any lookup of the target", async () => {
+    mockSingleTenantWorkspace();
+    mockBoundOperator();
+    const app = buildApp();
+
+    const res = await app.inject({
+      method: "GET",
+      url: `/workspaces/${FOREIGN_WORKSPACE_ID}/config`,
+    });
+
+    expect(res.statusCode).toBe(403);
+    expect(res.json()).toEqual({
+      ok: false,
+      error: { code: "forbidden", message: "Forbidden" },
+    });
+    // No enumeration: the foreign id is never handed to a lookup. The only
+    // workspace read is `resolveDefaultTenant`'s own by-sentinel-id read.
+    const workspaceReads = (prisma.workspace.findUnique as jest.Mock).mock.calls;
+    expect(workspaceReads).toHaveLength(1);
+    expect(workspaceReads[0]?.[0]?.where?.id).toBe(DEFAULT_WORKSPACE_ID);
+    await app.close();
+  });
+
+  it("GRANTS the caller's OWN workspaceId — the same URL shape, its own id", async () => {
+    mockSingleTenantWorkspace();
+    mockBoundOperator();
+    const app = buildApp();
+
+    const res = await app.inject({
+      method: "GET",
+      url: `/workspaces/${DEFAULT_WORKSPACE_ID}/config`,
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({ workspaceId: DEFAULT_WORKSPACE_ID });
+    await app.close();
+  });
+
+  it("resolves the SEEDED default workspace for an authenticated site owner — no tenant is synthesized", async () => {
+    mockSingleTenantWorkspace();
+    mockBoundOperator();
+    const app = buildApp();
+
+    const res = await app.inject({ method: "GET", url: "/scoped" });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({
+      workspaceId: DEFAULT_WORKSPACE_ID,
+      role: "owner",
+    });
+    await app.close();
+  });
+
+  it("DENIES a caller holding no Membership on the default Organization (a second OAuth sign-in after TOFU)", async () => {
+    mockSingleTenantWorkspace();
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue({
+      email: OPERATOR_EMAIL,
+      emailVerified: true,
+    });
+    (prisma.membership.create as jest.Mock).mockRejectedValue({ code: "P2002" });
+    (prisma.membership.findUnique as jest.Mock).mockResolvedValue(null);
+    const app = buildApp();
+
+    const res = await app.inject({ method: "GET", url: "/scoped" });
+
+    expect(res.statusCode).toBe(403);
+    await app.close();
+  });
+
+  it("DENIES once a SECOND workspace exists — the guard never grants outside an unambiguously single-tenant deployment", async () => {
+    (prisma.workspace.count as jest.Mock).mockResolvedValue(2);
+    mockBoundOperator();
+    const app = buildApp();
+
+    const res = await app.inject({ method: "GET", url: "/scoped" });
+
+    expect(res.statusCode).toBe(403);
+    expect(prisma.workspace.findUnique).not.toHaveBeenCalled();
+    await app.close();
+  });
+
+  it("DENIES when the sole workspace is NOT the well-known default", async () => {
+    (prisma.workspace.count as jest.Mock).mockResolvedValue(1);
+    (prisma.workspace.findUnique as jest.Mock).mockResolvedValue(null);
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue({
+      email: OPERATOR_EMAIL,
+      emailVerified: true,
+    });
+    const app = buildApp();
+
+    const res = await app.inject({ method: "GET", url: "/scoped" });
+
+    expect(res.statusCode).toBe(403);
+    await app.close();
+  });
+
+  it("DENIES when the sole default workspace hangs off a NON-sentinel organization", async () => {
+    (prisma.workspace.count as jest.Mock).mockResolvedValue(1);
+    (prisma.workspace.findUnique as jest.Mock).mockResolvedValue({
+      id: DEFAULT_WORKSPACE_ID,
+      organizationId: "org_01936b2c-0000-7000-8000-00000000beef",
+    });
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue({
+      email: OPERATOR_EMAIL,
+      emailVerified: true,
+    });
+    const app = buildApp();
+
+    const res = await app.inject({ method: "GET", url: "/scoped" });
+
+    expect(res.statusCode).toBe(403);
+    expect(prisma.membership.create).not.toHaveBeenCalled();
+    await app.close();
+  });
+
+  it("DENIES a bearer-authenticated caller with 403 — no workspace binding on an agent token (#3591)", async () => {
+    mockSingleTenantWorkspace();
+    mockBoundOperator();
+    const app = buildApp("bearer");
+
+    const res = await app.inject({ method: "GET", url: "/scoped" });
+
+    expect(res.statusCode).toBe(403);
+    expect(prisma.workspace.count).not.toHaveBeenCalled();
+    await app.close();
+  });
+
+  it("DENIES when AILK_OPERATOR_EMAIL is UNSET, even for a caller holding the owner Membership — an unpinned deployment seats nobody (#5693 security review)", async () => {
+    delete process.env.AILK_OPERATOR_EMAIL;
+    mockSingleTenantWorkspace();
+    mockBoundOperator();
+    const app = buildApp();
+
+    const res = await app.inject({ method: "GET", url: "/scoped" });
+
+    expect(res.statusCode).toBe(403);
+    // Fails closed BEFORE the TOFU bind: an unpinned deployment must not seat
+    // whoever authenticates first, because `isPlatformOperator` would later
+    // promote exactly that identity to an unfiltered read.
+    expect(prisma.membership.create).not.toHaveBeenCalled();
+    expect(prisma.workspace.count).not.toHaveBeenCalled();
+    await app.close();
+  });
+
+  it("DENIES a caller who ALREADY HOLDS the owner Membership but is not the pinned operator — a squatter bound before the pin existed stays denied (#5693 security review)", async () => {
+    mockSingleTenantWorkspace();
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue({
+      email: "squatter@evil.example",
+      emailVerified: true,
+    });
+    (prisma.membership.create as jest.Mock).mockResolvedValue({});
+    (prisma.membership.findUnique as jest.Mock).mockResolvedValue({
+      role: "owner",
+    });
+    const app = buildApp();
+
+    const res = await app.inject({ method: "GET", url: "/scoped" });
+
+    expect(res.statusCode).toBe(403);
+    // The Membership row is not enough — the email is re-checked per request,
+    // so a pre-existing bind cannot be inherited by adding the pin later.
+    expect(prisma.workspace.count).not.toHaveBeenCalled();
+    await app.close();
+  });
+
+  it("GRANTS the pinned operator case-insensitively, with surrounding whitespace trimmed", async () => {
+    process.env.AILK_OPERATOR_EMAIL = "  OPERATOR@Example.COM  ";
+    mockSingleTenantWorkspace();
+    mockBoundOperator();
+    const app = buildApp();
+
+    const res = await app.inject({ method: "GET", url: "/scoped" });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({
+      workspaceId: DEFAULT_WORKSPACE_ID,
+      role: "owner",
+    });
+    await app.close();
+  });
+
+  it("DENIES the pinned operator whose email is UNVERIFIED — an unverified address is an unproven claim to the pin", async () => {
+    mockSingleTenantWorkspace();
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue({
+      email: OPERATOR_EMAIL,
+      emailVerified: false,
+    });
+    const app = buildApp();
+
+    const res = await app.inject({ method: "GET", url: "/scoped" });
+
+    expect(res.statusCode).toBe(403);
+    expect(prisma.workspace.count).not.toHaveBeenCalled();
+    await app.close();
+  });
+
+  it("DENIES when the pinned caller has no User row", async () => {
+    mockSingleTenantWorkspace();
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(null);
+    const app = buildApp();
+
+    const res = await app.inject({ method: "GET", url: "/scoped" });
+
+    expect(res.statusCode).toBe(403);
+    await app.close();
+  });
+
+  it("returns 401 for an unauthenticated caller", async () => {
+    const app = buildApp("none");
+
+    const res = await app.inject({ method: "GET", url: "/scoped" });
+
+    expect(res.statusCode).toBe(401);
+    await app.close();
+  });
+});

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

@@ -377,3 +377,111 @@ describe("per-IP rate limit middleware", () => {
     expect(DEFAULT_PER_IP_PER_MINUTE_STRICT).toBe(10);
   });
 });
+
+/**
+ * Cross-isolate demonstration (#5040 AC-1).
+ *
+ * The middleware's `buckets` store is module-scoped (see the module
+ * docstring's SINGLE-REPLICA CAVEAT) — it is per-process state, not a
+ * shared external store. On the real deployment target this means: each
+ * serverless isolate that cold-loads this module gets its own empty Map,
+ * so the same visitor IP is tracked independently per isolate rather than
+ * against one shared counter.
+ *
+ * This process cannot spin up two real Vercel isolates (no live target —
+ * see #5040's issue comment + docs/specs/5111-limiter-surface-spec.md §8
+ * for the exact probe attempted and why it could not reach one as of
+ * 2026-09-15). What IS fully within this process's control is the root
+ * mechanism itself: module-scoped state does not survive a fresh module
+ * load. `jest.isolateModules` gives each block below its own Jest module
+ * registry, so requiring the middleware module inside each returns a
+ * DISTINCT module instance with its own private `buckets` Map — the same
+ * state-isolation shape a serverless cold start produces (a fresh module
+ * load with an empty Map), reproduced deterministically in-process.
+ *
+ * This demonstrates — rather than merely asserts, per AC-1's own wording —
+ * that the per-IP limit, AS CURRENTLY DESIGNED, does NOT hold across
+ * separate execution contexts: the same IP, already rate-limited to
+ * exhaustion on one instance, is granted a fresh budget on another. This
+ * is the accepted, documented trade-off recorded in
+ * docs/specs/5111-limiter-surface-spec.md § D4 (no new store for OSS v1;
+ * MAX_BUCKETS bounds memory, not the cross-isolate aggregate rate) — this
+ * test makes that trade-off provable rather than only claimed in a
+ * comment, and will fail (correctly) the day a cross-isolate store
+ * replaces the in-process Map.
+ *
+ * What this test does NOT demonstrate: whether the LIVE deployment
+ * actually runs more than one concurrent isolate for a given route today.
+ * That is a platform fact only a reachable live deployment can answer
+ * (#5040 AC-1's deployment-level half, recorded open in the issue).
+ */
+describe("cross-isolate limit — does NOT hold by design (#5040, SINGLE-REPLICA CAVEAT)", () => {
+  it("the same IP, exhausted on one module instance, is freshly allowed on an independently-loaded instance", async () => {
+    const perIpPerMinute = 5;
+    const ip = "198.51.100.7";
+
+    let isolateAppA: ReturnType<typeof buildApp> | undefined;
+    let isolateAppB: ReturnType<typeof buildApp> | undefined;
+
+    // Each isolateModules block gets a fresh require cache: requiring the
+    // middleware module inside it yields a module instance distinct from
+    // the top-level `rateLimitMiddleware` import used by every other test
+    // in this file (and distinct from each other).
+    jest.isolateModules(() => {
+      const isolateA: typeof import("../rate-limit") = require("../rate-limit");
+      const app = Fastify({ trustProxy: true });
+      app.register(isolateA.rateLimitMiddleware, { perIpPerMinute });
+      app.get("/test", async () => ({ ok: true }));
+      isolateAppA = app;
+    });
+
+    jest.isolateModules(() => {
+      const isolateB: typeof import("../rate-limit") = require("../rate-limit");
+      const app = Fastify({ trustProxy: true });
+      app.register(isolateB.rateLimitMiddleware, { perIpPerMinute });
+      app.get("/test", async () => ({ ok: true }));
+      isolateAppB = app;
+    });
+
+    if (!isolateAppA || !isolateAppB) {
+      throw new Error("isolateModules did not synchronously assign both apps");
+    }
+
+    await isolateAppA.ready();
+    await isolateAppB.ready();
+
+    try {
+      // Exhaust isolate A's per-IP budget entirely.
+      for (let i = 0; i < perIpPerMinute; i++) {
+        const res = await isolateAppA.inject({
+          method: "GET",
+          url: "/test",
+          headers: { "x-forwarded-for": ip },
+        });
+        expect(res.statusCode).toBe(200);
+      }
+      const exhaustedOnA = await isolateAppA.inject({
+        method: "GET",
+        url: "/test",
+        headers: { "x-forwarded-for": ip },
+      });
+      expect(exhaustedOnA.statusCode).toBe(429);
+
+      // The SAME ip, already 429'd on A, hits an independently-loaded
+      // instance (B) for the first time — B's own buckets Map has never
+      // seen this IP, so it is granted a full fresh budget rather than
+      // being held to the aggregate limit across A+B. This is the
+      // cross-isolate gap: (perIpPerMinute × isolate count) requests
+      // succeed in aggregate for one IP, not perIpPerMinute.
+      const firstOnB = await isolateAppB.inject({
+        method: "GET",
+        url: "/test",
+        headers: { "x-forwarded-for": ip },
+      });
+      expect(firstOnB.statusCode).toBe(200);
+    } finally {
+      await isolateAppA.close();
+      await isolateAppB.close();
+    }
+  });
+});

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

@@ -0,0 +1,136 @@
+/**
+ * Default-tenant guard preHandler — the BASE-build tenant guard (#5677).
+ *
+ * The base-build counterpart to `./tenant.ts`, which is a multi-tenant SLICE
+ * (`// oss: false`) and therefore absent on a build without that module. Same
+ * posture, same decoration, same denials; the only difference is where the
+ * tenant comes from — the seeded default Workspace
+ * (`services/default-tenant.ts#resolveDefaultTenant`) rather than the
+ * session's active workspace, which a single-tenant site does not have.
+ *
+ * `server.ts` picks ONE of the two per build: multi-tenant's guard when the
+ * module is enabled, this one otherwise. They never both run, and this one is
+ * never reachable on a build that has the module — a fallback beneath it, not
+ * a parallel path.
+ *
+ * Default-deny — every branch that is not an explicit grant is a denial:
+ *
+ *   - unauthenticated                                    → 401
+ *   - bearer-authenticated (no cookie session — #3591)   → 403
+ *   - AILK_OPERATOR_EMAIL is unset                       → 403
+ *   - the caller's email is not the pinned one           → 403
+ *   - the deployment is not unambiguously single-tenant  → 403
+ *   - the caller holds no Membership on the default Org  → 403
+ *   - URL workspaceId ≠ the resolved workspace           → 403
+ *     (compared BEFORE any lookup of the target — no tenant enumeration)
+ *
+ * The two `AILK_OPERATOR_EMAIL` branches are this guard's own, and they are
+ * why it calls `resolveDefaultTenantForOperator` rather than
+ * `resolveDefaultTenant`: on this build the review surface and
+ * `isPlatformOperator`'s unfiltered `{kind: "all"}` scope became reachable
+ * together, so an unpinned deployment must seat nobody rather than seat
+ * whoever authenticates first. See that function for the full reasoning. A
+ * deployment that wants the dashboard MUST pin the operator; unset is a
+ * refusal, not a default-open.
+ *
+ * The URL-workspaceId comparison is not redundant on this path even though
+ * `resolveDefaultTenant` only ever yields the one seeded workspace: it is what
+ * makes a request naming a FOREIGN workspaceId a 403 rather than a silently
+ * mis-scoped read, and it is the same comparison `tenant.ts` makes, in the
+ * same place.
+ *
+ * This guard deliberately does NOT read `sessionTenant.activeWorkspaceId`.
+ * `resolveDefaultTenant` grants only while `workspace.count() === 1` and that
+ * sole workspace is the sentinel default, so on any build this path can grant
+ * on there is no second workspace for a stale session binding to point at.
+ *
+ * On grant it decorates `request.tenant` (a `TenantContext`), exactly as
+ * `tenant.ts` does; route handlers pass that to `tenantDb(tenant)` so every
+ * domain query is workspace-scoped. The `declare module` augmentation below is
+ * the ONE copy of that decoration's type — `tenant.ts` no longer carries its
+ * own, because this file ships on every build and the paid slice does not.
+ */
+import type {
+  FastifyPluginCallback,
+  FastifyReply,
+  FastifyRequest,
+} from "fastify";
+
+import {
+  resolveDefaultTenantForOperator,
+  type TenantContext,
+} from "../services/default-tenant.js";
+
+declare module "fastify" {
+  interface FastifyRequest {
+    tenant?: TenantContext;
+  }
+}
+
+const FORBIDDEN = {
+  ok: false,
+  error: { code: "forbidden", message: "Forbidden" },
+} as const;
+
+/**
+ * Resolve + attach the default tenant, or reply 401/403. Registered as a hook
+ * in a tenant route scope (after auth), so no tenant-scoped handler runs
+ * without a granted TenantContext.
+ */
+export async function defaultTenantPreHandler(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  const userId = request.userId;
+  if (!userId) {
+    reply.code(401).send({
+      ok: false,
+      error: { code: "unauthorized", message: "Authentication required" },
+    });
+    return;
+  }
+
+  // Bearer tokens carry no workspace binding (#3591) — denied here, the same
+  // default-deny `resolveActiveTenant` applies on the multi-tenant path.
+  if (!request.sessionTenant) {
+    reply.code(403).send(FORBIDDEN);
+    return;
+  }
+
+  const tenant = await resolveDefaultTenantForOperator(userId);
+  if (!tenant) {
+    reply.code(403).send(FORBIDDEN);
+    return;
+  }
+
+  // URL-scoped routes: the target workspace MUST be the resolved workspace.
+  // Compared before any target lookup — a foreign (or nonexistent)
+  // workspaceId gets the same 403.
+  const params = request.params as { workspaceId?: string } | undefined;
+  if (params?.workspaceId && params.workspaceId !== tenant.workspaceId) {
+    reply.code(403).send(FORBIDDEN);
+    return;
+  }
+
+  request.tenant = tenant;
+}
+
+/**
+ * Plugin form, mirroring `tenantPreHandlerPlugin`: skip-override so the hook
+ * propagates to sibling route plugins registered in the same scope.
+ */
+export const defaultTenantPreHandlerPlugin: FastifyPluginCallback = (
+  fastify,
+  _opts,
+  done,
+) => {
+  fastify.decorateRequest("tenant", undefined);
+  fastify.addHook("preHandler", defaultTenantPreHandler);
+  done();
+};
+
+(
+  defaultTenantPreHandlerPlugin as FastifyPluginCallback & {
+    [key: symbol]: boolean;
+  }
+)[Symbol.for("skip-override")] = true;