@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/anonymous-access-multitenant.md

@@ -0,0 +1,443 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/anonymous-access-multitenant. Do not edit. -->
+
+# anonymous-access-multitenant
+
+Subdomain-based tenant resolution for anonymous-access — SaaS shop / CMS pattern with per-tenant public surface.
+
+## README
+
+# Anonymous Access Multitenant
+
+Anonymous access that still resolves a tenant.
+
+## What it shows
+
+- Public write/read paths in a multi-tenant app
+- Tenant resolution without a session user
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+## Tests
+
+Needs a running Postgres and `TEST_DATABASE_URL` set (e.g. `postgres://postgres:postgres@127.0.0.1:5432/postgres`, see `demo/.env.example`).
+
+```bash
+cd samples/recipes/anonymous-access-multitenant
+bun test
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Multi-tenant anonymous access: resolver + tenantExists + cookie
+// persistence working together. The test shop has two real tenants
+// (acme + globex) and one bogus subdomain to prove the 404 path.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { setTenantCookie } from "@cosmicdrift/kumiko-framework/api";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { multiTenantShopFeature, productEntity, productTable } from "../feature";
+import { createSubdomainResolver, extractSubdomain } from "../subdomain-resolver";
+
+const ACME_TENANT_ID = "00000000-0000-4000-8000-000000000001" as TenantId;
+const GLOBEX_TENANT_ID = "00000000-0000-4000-8000-000000000002" as TenantId;
+
+// App-supplied lookup. In a real deployment this hits the tenants table;
+// the in-memory map keeps the recipe focused on the resolution chain.
+const KNOWN_TENANTS: Record<string, TenantId> = {
+  acme: ACME_TENANT_ID,
+  globex: GLOBEX_TENANT_ID,
+};
+
+let stack: TestStack;
+let resolver: ReturnType<typeof createSubdomainResolver>;
+// Counters prove that the cache actually hits — one DB lookup per
+// subdomain in a tight loop is the difference between a working shop
+// under load and one that buckles.
+let lookupCount = 0;
+let existsCount = 0;
+
+beforeAll(async () => {
+  resolver = createSubdomainResolver({
+    lookupBySubdomain: async (sub) => {
+      lookupCount++;
+      return KNOWN_TENANTS[sub] ?? null;
+    },
+    existsById: async (id) => {
+      existsCount++;
+      return id === ACME_TENANT_ID || id === GLOBEX_TENANT_ID;
+    },
+    cacheTtlSeconds: 60,
+  });
+
+  stack = await setupTestStack({
+    features: [multiTenantShopFeature],
+    anonymousAccess: {
+      tenantResolver: resolver.tenantResolver,
+      tenantExists: resolver.tenantExists,
+      // This recipe teaches "client X-Tenant header wins over the resolver"
+      // as the intended fallback-convenience pattern — see the test below
+      // asserting the header takes precedence and the resolver is skipped.
+      resolverTrust: "fallback-only",
+    },
+  });
+  await unsafeCreateEntityTable(stack.db, productEntity);
+  await createEventsTable(stack.db);
+
+  // Stamp test routes that exercise setTenantCookie. The framework gives
+  // apps the helper; the route is app-territory.
+  stack.app.get("/api/_set-tenant-cookie", (c) => {
+    const tenantId = c.req.query("tenantId") as TenantId | undefined;
+    if (!tenantId) return c.json({ error: "missing tenantId" }, 400);
+    setTenantCookie(c, tenantId);
+    return c.json({ ok: true });
+  });
+});
+
+afterAll(async () => {
+  await stack?.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe(`DELETE FROM "${productTable.tableName}"`);
+  resolver.invalidateAll();
+  lookupCount = 0;
+  existsCount = 0;
+});
+
+describe("subdomain resolution", () => {
+  test("acme.shop.com → acme tenant", async () => {
+    // Seed a product into acme — it should be visible to anonymous
+    // visitors who land on acme.shop.com.
+    await stack.http.writeOk(
+      "mtshop:write:product:create",
+      { name: "Acme Anvil" },
+      { ...TestUsers.admin, tenantId: ACME_TENANT_ID },
+    );
+
+    const res = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "mtshop:query:product:list", payload: {} },
+      { Host: "acme.shop.com" },
+    );
+
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { data: Array<{ name: string }> };
+    expect(body.data.map((p) => p.name)).toEqual(["Acme Anvil"]);
+  });
+
+  test("unknown subdomain → 400 tenant_required (resolver returned null)", async () => {
+    const res = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "mtshop:query:product:list", payload: {} },
+      { Host: "bogus.shop.com" },
+    );
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("tenant_required");
+  });
+
+  test("reserved subdomain (www) → 400 tenant_required", async () => {
+    // www.shop.com is the marketing landing — it must NOT silently fall
+    // onto whatever tenant happens to be first in the DB.
+    const res = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "mtshop:query:product:list", payload: {} },
+      { Host: "www.shop.com" },
+    );
+    expect(res.status).toBe(400);
+  });
+
+  test("apex host without subdomain → 400 tenant_required", async () => {
+    const res = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "mtshop:query:product:list", payload: {} },
+      { Host: "shop.com" },
+    );
+    expect(res.status).toBe(400);
+  });
+});
+
+describe("cache behaviour", () => {
+  test("repeated requests to the same subdomain hit the cache (1 DB lookup)", async () => {
+    for (let i = 0; i < 5; i++) {
+      const res = await stack.http.raw(
+        "POST",
+        "/api/query",
+        { type: "mtshop:query:product:list", payload: {} },
+        { Host: "acme.shop.com" },
+      );
+      expect(res.status).toBe(200);
+    }
+    expect(lookupCount).toBe(1);
+  });
+
+  test("invalidate() drops the cache entry → next request hits DB", async () => {
+    // Warm the cache.
+    await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "mtshop:query:product:list", payload: {} },
+      { Host: "acme.shop.com" },
+    );
+    expect(lookupCount).toBe(1);
+
+    // Simulate a tenant-disable flow: invalidate the cache entry, the
+    // next request must consult the DB again.
+    resolver.invalidate("acme");
+    await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "mtshop:query:product:list", payload: {} },
+      { Host: "acme.shop.com" },
+    );
+    expect(lookupCount).toBe(2);
+  });
+});
+
+describe("cookie persistence", () => {
+  test("X-Tenant header for known tenant routes through tenantExists", async () => {
+    // Header-supplied tenants don't go through tenantResolver — they go
+    // through tenantExists. This proves the second cache works.
+    for (let i = 0; i < 3; i++) {
+      const res = await stack.http.raw(
+        "POST",
+        "/api/query",
+        { type: "mtshop:query:product:list", payload: {} },
+        { Host: "anything.shop.com", "X-Tenant": ACME_TENANT_ID },
+      );
+      expect(res.status).toBe(200);
+    }
+    // tenantResolver was NOT called (header took precedence); tenantExists
+    // was called once and then served from cache.
+    expect(lookupCount).toBe(0);
+    expect(existsCount).toBe(1);
+  });
+
+  test("X-Tenant for unknown id → 404 tenant_not_found", async () => {
+    const res = await stack.http.raw(
+      "POST",
+      "/api/query",
+      { type: "mtshop:query:product:list", payload: {} },
+      {
+        Host: "anything.shop.com",
+        "X-Tenant": "00000000-0000-4000-8000-deadbeefdead",
+      },
+    );
+    expect(res.status).toBe(404);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("tenant_not_found");
+  });
+});
+
+describe("extractSubdomain (unit)", () => {
+  test("typical SaaS host", () => {
+    expect(extractSubdomain("acme.shop.com")).toBe("acme");
+  });
+  test("strips port", () => {
+    expect(extractSubdomain("acme.shop.com:443")).toBe("acme");
+  });
+  test("apex returns null", () => {
+    expect(extractSubdomain("shop.com")).toBeNull();
+  });
+  test("localhost returns null", () => {
+    expect(extractSubdomain("localhost")).toBeNull();
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Multi-Tenant Anonymous Access — Subdomain-Resolver Pattern
+//
+// Use case: SaaS deployment where every customer gets `<tenant>.shop.com`.
+// Anonymous visitors land on the right tenant via the host header. The
+// recipe shows the three pieces an app needs:
+//
+//  1. tenantResolver — parses the Host header, looks up the tenantId in
+//     a small cache + DB. Returns null on misses (404 to the visitor).
+//  2. tenantExists   — guards header/cookie-supplied ids the same cache.
+//  3. setTenantCookie — once the resolver decided, persist on the visitor
+//     so subsequent requests skip the parse + DB lookup.
+//
+// The product/order entities are minimal — the focus of this recipe is
+// the resolution chain, not the domain logic. Pair this with the
+// single-tenant recipe (samples/recipes/anonymous-access/) for
+// comparison.
+
+import { buildEntityTable, createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import {
+  access,
+  createEntity,
+  createTextField,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+export const productEntity = createEntity({
+  table: "mt_products",
+  fields: {
+    name: createTextField({ personal: false, reason: "is_business_data", required: true }),
+  },
+});
+
+export const productTable = buildEntityTable("product", productEntity);
+
+export const multiTenantShopFeature = defineFeature("mtshop", (r) => {
+  r.entity("product", productEntity);
+
+  // Public listing — every tenant has its own products, scoped by tenantId
+  // automatically via the framework's tenant-isolation. Anonymous visitors
+  // see only the tenant they landed on.
+  r.queryHandler(
+    "product:list",
+    z.object({}),
+    async (_event, ctx) => ctx.db.selectMany(productTable),
+    {
+      access: { roles: [...access.anonymous, "User", "Admin"] },
+      rateLimit: { per: "ip+handler", limit: 60, windowSeconds: 60 },
+    },
+  );
+
+  // Admin-only — proves role-gating still works on top of the multi-tenant
+  // anonymous resolution.
+  r.writeHandler(
+    "product:create",
+    z.object({ name: z.string().min(1) }),
+    async (event, ctx) => {
+      const exec = createEventStoreExecutor(productTable, productEntity, {
+        entityName: "product",
+      });
+      return exec.create(event.payload, event.user, ctx.db);
+    },
+    { access: { roles: ["Admin"] } },
+  );
+});
+```
+
+### src/subdomain-resolver.ts
+
+```ts
+// Subdomain-based tenantResolver + tenantExists wired against an LRU cache.
+// Apps drop this into anonymousAccess: { tenantResolver, tenantExists, … }.
+//
+// Cache strategy: 5-minute TTL is the sweet spot — it absorbs traffic
+// bursts (a Reddit hug peaks for ~10 minutes; cache means one DB lookup
+// for the entire wave) without holding stale data so long that a freshly
+// disabled tenant keeps serving content. Apps with stricter SLA can drop
+// the TTL or call invalidateTenantCache(slug) from their disable-tenant
+// handler.
+
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+
+export type TenantLookup = (subdomain: string) => Promise<TenantId | null>;
+export type TenantExistsLookup = (tenantId: TenantId) => Promise<boolean>;
+
+export type SubdomainResolverOptions = {
+  // Subdomain → tenantId. Typically queries the tenants table for an
+  // active row matching the slug (acme.shop.com → "acme"). Returning null
+  // is the legitimate "no such tenant" answer — throw only on infra
+  // failures.
+  readonly lookupBySubdomain: TenantLookup;
+  // tenantId → exists?. Called when a visitor presents an X-Tenant header
+  // or kumiko_tenant cookie (so a cookie that survives a server restart
+  // still re-validates against the DB on first use). Apps usually wrap
+  // the same tenants table — keep the implementation symmetric to
+  // lookupBySubdomain.
+  readonly existsById: TenantExistsLookup;
+  // Apex / non-tenant hosts that should NOT be resolved. Common pattern:
+  // `shop.com` is the marketing site, `app.shop.com` is the admin app —
+  // anonymous traffic to those should 404 rather than land on a default.
+  readonly reservedSubdomains?: readonly string[];
+  // TTL in seconds. Default 300s (5min) — see top-of-file rationale.
+  readonly cacheTtlSeconds?: number;
+};
+
+type CacheEntry<T> = { value: T; expiresAt: number };
+
+// Builds resolver + tenantExists that share independent caches by lookup
+// key (subdomain vs tenantId), so the two callbacks each amortise their
+// own DB load. Apps drop the returned object into
+// `anonymousAccess: { tenantResolver: r.tenantResolver, tenantExists: r.tenantExists }`.
+export function createSubdomainResolver(opts: SubdomainResolverOptions): {
+  tenantResolver: (c: {
+    req: { url: string; header: (name: string) => string | undefined };
+  }) => Promise<TenantId | null>;
+  tenantExists: (id: TenantId) => Promise<boolean>;
+  invalidate: (subdomainOrTenantId: string) => void;
+  invalidateAll: () => void;
+} {
+  const ttlMs = (opts.cacheTtlSeconds ?? 300) * 1000;
+  const reserved = new Set(opts.reservedSubdomains ?? ["www", "app", "api", "admin"]);
+  const subdomainCache = new Map<string, CacheEntry<TenantId | null>>();
+  const existsCache = new Map<TenantId, CacheEntry<boolean>>();
+
+  async function lookupBySubdomainCached(subdomain: string): Promise<TenantId | null> {
+    const now = Date.now();
+    const cached = subdomainCache.get(subdomain);
+    if (cached && cached.expiresAt > now) return cached.value;
+
+    const tenantId = await opts.lookupBySubdomain(subdomain);
+    subdomainCache.set(subdomain, { value: tenantId, expiresAt: now + ttlMs });
+    return tenantId;
+  }
+
+  async function existsByIdCached(tenantId: TenantId): Promise<boolean> {
+    const now = Date.now();
+    const cached = existsCache.get(tenantId);
+    if (cached && cached.expiresAt > now) return cached.value;
+
+    const exists = await opts.existsById(tenantId);
+    existsCache.set(tenantId, { value: exists, expiresAt: now + ttlMs });
+    return exists;
+  }
+
+  return {
+    tenantResolver: async (c) => {
+      const host = c.req.header("Host");
+      if (!host) return null;
+      const subdomain = extractSubdomain(host);
+      if (subdomain === null) return null;
+      if (reserved.has(subdomain)) return null;
+      return lookupBySubdomainCached(subdomain);
+    },
+    tenantExists: existsByIdCached,
+    invalidate: (key) => {
+      subdomainCache.delete(key);
+      existsCache.delete(key as TenantId);
+    },
+    invalidateAll: () => {
+      subdomainCache.clear();
+      existsCache.clear();
+    },
+  };
+}
+
+// Extracts the leftmost DNS label, dropping the port and assuming the
+// host has at least 3 labels (subdomain.domain.tld). Bare hosts like
+// "localhost" or "shop.com" return null so the caller falls through to
+// the "no tenant" branch.
+export function extractSubdomain(host: string): string | null {
+  const noPort = host.split(":")[0] ?? host;
+  const labels = noPort.split(".");
+  if (labels.length < 3) return null;
+  return labels[0] ?? null;
+}
+```