@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/auth-claims.md

@@ -0,0 +1,351 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/auth-claims. Do not edit. -->
+
+# auth-claims
+
+r.authClaims() — features contribute identity facts into the JWT at login time with auto-prefixed keys.
+
+## README
+
+# Auth Claims
+
+Features inject identity facts into the JWT.
+
+## What it shows
+
+- `r.authClaims(fn)` contributing to `SessionUser.claims`
+- Claims recomputed on login and tenant switch
+
+## 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/auth-claims
+bun test
+```
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Auth Claims Sample — Integration Test
+//
+// Drives the resolver end-to-end: features register r.claimKey() + r.authClaims(),
+// the resolver runs the hooks in parallel, merges the results under auto-prefixed
+// keys, and readClaim(user, handle) retrieves them with proper JS typing.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, mock, test } from "bun:test";
+import type { AuthClaimsContext } from "@cosmicdrift/kumiko-framework/engine";
+import { defineFeature, readClaim } from "@cosmicdrift/kumiko-framework/engine";
+import { resolveAuthClaims } from "@cosmicdrift/kumiko-framework/pipeline";
+import { setupTestStack, type TestStack, testTenantId } from "@cosmicdrift/kumiko-framework/stack";
+import {
+  type BetaFlagStore,
+  fakeSession,
+  makeBetaFlagsFeature,
+  makeBrokenFeature,
+  makeDriftFeature,
+  makeTeamsFeature,
+  type TeamStore,
+} from "../feature";
+
+// Stores are mutated in place across tests (cleared in beforeEach). The
+// features capture them by closure at registration time.
+const teamStore: TeamStore = new Map();
+const betaFlagStore: BetaFlagStore = new Map();
+const driftState = { value: false };
+
+// Build the features once so we can reach the typed handles via the
+// returned `exports.Claims` maps. The test suite references these handles
+// when asserting — no hand-written qualified strings.
+const teamsFeature = makeTeamsFeature(teamStore);
+const betaFlagsFeature = makeBetaFlagsFeature(betaFlagStore);
+const brokenFeature = makeBrokenFeature();
+const driftFeature = makeDriftFeature(driftState);
+
+const TeamsClaims = teamsFeature.exports.Claims;
+const BetaClaims = betaFlagsFeature.exports.Claims;
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [teamsFeature, betaFlagsFeature, brokenFeature, driftFeature],
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(() => {
+  teamStore.clear();
+  betaFlagStore.clear();
+  driftState.value = false;
+});
+
+// The resolver needs an AuthClaimsContext per hook run. This sample doesn't
+// exercise ctx.db or ctx.queryAs — real features would, and that's the
+// point of the fresh TenantDb the dispatcher builds. A stub is fine here.
+const stubContext: AuthClaimsContext = {
+  db: {} as AuthClaimsContext["db"],
+  queryAs: async () => {
+    throw new Error("queryAs not exercised in this sample");
+  },
+};
+
+const tenantA = testTenantId(1);
+const userAlice = "11111111-0000-4000-8000-000000000001";
+
+describe("scenario 1: typed readClaim access", () => {
+  test("feature hook sets the value → readClaim returns it narrowed to the handle's JS type", async () => {
+    teamStore.set(userAlice, "eng");
+    betaFlagStore.set(userAlice, ["dark-mode", "new-checkout"]);
+
+    const user = fakeSession(userAlice, tenantA);
+    const claims = await resolveAuthClaims({
+      user,
+      hooks: stack.registry.getAuthClaimsHooks(),
+      contextFactory: () => stubContext,
+    });
+    const userWithClaims = { ...user, claims };
+
+    // readClaim narrows to `string | undefined` for the teamId handle — no
+    // manual `as string`, no magic key-string.
+    const teamId = readClaim(userWithClaims, TeamsClaims.teamId);
+    expect(teamId).toBe("eng");
+
+    // readClaim narrows to `readonly string[] | undefined` for flags.
+    const flags = readClaim(userWithClaims, BetaClaims.flags);
+    expect(flags).toEqual(["dark-mode", "new-checkout"]);
+  });
+
+  test("feature hook returns empty → readClaim returns undefined", async () => {
+    const user = fakeSession(userAlice, tenantA);
+    const claims = await resolveAuthClaims({
+      user,
+      hooks: stack.registry.getAuthClaimsHooks(),
+      contextFactory: () => stubContext,
+    });
+    const userWithClaims = { ...user, claims };
+
+    expect(readClaim(userWithClaims, TeamsClaims.teamId)).toBeUndefined();
+    expect(readClaim(userWithClaims, BetaClaims.flags)).toBeUndefined();
+  });
+});
+
+describe("scenario 2: best-effort policy — broken hook does not fail the login", () => {
+  test("broken feature throws → other features still contribute their claims", async () => {
+    teamStore.set(userAlice, "eng");
+
+    const user = fakeSession(userAlice, tenantA);
+    const claims = await resolveAuthClaims({
+      user,
+      hooks: stack.registry.getAuthClaimsHooks(),
+      contextFactory: () => stubContext,
+    });
+    const userWithClaims = { ...user, claims };
+
+    expect(readClaim(userWithClaims, TeamsClaims.teamId)).toBe("eng");
+    expect("broken:anything" in claims).toBe(false);
+  });
+});
+
+describe("scenario 3: drift-warning when a hook returns an undeclared key", () => {
+  test("declared teamId + undeclared 'rouge' → warn logged, both land in JWT (best-effort)", async () => {
+    driftState.value = true;
+
+    const warn = mock();
+    const log = {
+      warn,
+      info: mock(),
+      error: mock(),
+      debug: mock(),
+      child: () => log,
+    };
+
+    const user = fakeSession(userAlice, tenantA);
+    const claims = await resolveAuthClaims({
+      user,
+      hooks: stack.registry.getAuthClaimsHooks(),
+      contextFactory: () => stubContext,
+      log,
+    });
+
+    // Both claims are present — the drift-check is advisory, not strict.
+    expect(claims["drift:teamId"]).toBe("declared");
+    expect(claims["drift:rouge"]).toBe("undeclared");
+
+    const driftWarns = warn.mock.calls.filter(
+      (c) => (c[1] as { featureName?: string })?.featureName === "drift",
+    );
+    expect(driftWarns).toHaveLength(1);
+    expect(driftWarns[0]?.[1]).toMatchObject({
+      featureName: "drift",
+      undeclaredKey: "rouge",
+    });
+  });
+});
+
+describe("scenario 4: auto-prefix prevents cross-feature collisions on same inner key", () => {
+  test("two features returning the SAME inner key `teamId` coexist under separate prefixes", async () => {
+    const billingWithTeamId = defineFeature("billing", (r) => {
+      const teamId = r.claimKey("teamId", { type: "string" });
+      r.authClaims(async (user) => (user.id === userAlice ? { teamId: "billing-A" } : {}));
+      return { Claims: { teamId } as const };
+    });
+
+    teamStore.set(userAlice, "eng");
+
+    const collisionStack = await setupTestStack({
+      features: [makeTeamsFeature(teamStore), billingWithTeamId],
+    });
+    try {
+      const user = fakeSession(userAlice, tenantA);
+      const claims = await resolveAuthClaims({
+        user,
+        hooks: collisionStack.registry.getAuthClaimsHooks(),
+        contextFactory: () => stubContext,
+      });
+
+      expect(claims["teams:teamId"]).toBe("eng");
+      expect(claims["billing:teamId"]).toBe("billing-A");
+    } finally {
+      await collisionStack.cleanup();
+    }
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Auth Claims Sample
+//
+// Shows how features contribute identity facts into SessionUser.claims via
+// `r.authClaims()`, and how handlers read those facts back with typed
+// handles from `r.claimKey()` + the `readClaim(user, handle)` helper.
+//
+// Why the handle pattern: reading `user.claims["teams:teamId"] as string`
+// hand-codes the qualified name (magic string, breaks under a rename) and
+// casts without the compiler's help. A declared handle threads the qualified
+// name and JS type through `readClaim<T>(user, handle)`, so a rename in
+// `r.claimKey("teamId", ...)` cascades to every call site, and `readClaim`
+// narrows the return type to `string | undefined` automatically.
+//
+// Design rules the sample bakes in:
+//  1. Auto-prefix means cross-feature keys cannot collide. Feature "teams"
+//     returning `{ teamId: ... }` lands at `"teams:teamId"`. Feature
+//     "billing" returning the same inner key lands at `"billing:teamId"`.
+//     Both coexist.
+//  2. Best-effort errors: if one feature's hook throws, that feature's
+//     claims are missing from the JWT, but the login still succeeds.
+//     Identity-facts are convenience, not access-gates.
+//  3. Hook context is trimmed (AuthClaimsContext, not HandlerContext) —
+//     login is a read, so appendEvent/archive/tz aren't available. queryAs
+//     + db cover the cross-feature lookups a claims-hook realistically
+//     needs.
+//  4. Declaring claim keys via r.claimKey also turns on a runtime drift-
+//     check: if a hook returns an undeclared inner-key, the resolver logs
+//     a warning (the claim still lands in the JWT — this is typo
+//     protection, not strict schema).
+
+import {
+  createEntity,
+  createTextField,
+  defineFeature,
+  type SessionUser,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+export const teamMembershipEntity = createEntity({
+  table: "read_sample_auth_team_memberships",
+  fields: {
+    userId: createTextField({ personal: "ref", required: true }),
+    teamId: createTextField({ personal: false, reason: "is_system_identifier", required: true }),
+  },
+});
+
+export const betaFlagsEntity = createEntity({
+  table: "read_sample_auth_beta_flags",
+  fields: {
+    userId: createTextField({ personal: "ref", required: true }),
+    flag: createTextField({ personal: false, reason: "is_business_data", required: true }),
+  },
+});
+
+// Plain in-memory state that the hooks read from — keeps the sample focused
+// on the claim mechanism, not on DB seeding. A real feature would SELECT
+// from its own table via ctx.db.
+export type TeamStore = Map<string, string>;
+export type BetaFlagStore = Map<string, readonly string[]>;
+
+// Feature: Teams. Declares a typed `teamId` claim and a hook that fills it.
+// The setup callback returns an `exports` object carrying the handles — the
+// test (or any other feature) imports them via `teamsFeature.exports.Claims`
+// without knowing or re-typing the qualified name.
+export function makeTeamsFeature(store: TeamStore) {
+  return defineFeature("teams", (r) => {
+    const teamId = r.claimKey("teamId", { type: "string" });
+
+    r.authClaims(async (user: SessionUser) => {
+      const value = store.get(user.id);
+      return value ? { teamId: value } : {};
+    });
+
+    return { Claims: { teamId } as const };
+  });
+}
+
+// Feature: BetaFlags. Array claim — shows the handle's type parameter
+// narrowing for non-scalar values.
+export function makeBetaFlagsFeature(store: BetaFlagStore) {
+  return defineFeature("betaFlags", (r) => {
+    const flags = r.claimKey("flags", { type: "string[]" });
+
+    r.authClaims(async (user: SessionUser) => {
+      const value = store.get(user.id);
+      return value && value.length > 0 ? { flags: value } : {};
+    });
+
+    return { Claims: { flags } as const };
+  });
+}
+
+// Feature: Broken. Demonstrates the best-effort policy — this hook always
+// throws. The tests assert that a broken hook does not fail the login and
+// the other features' claims still land in the JWT.
+export function makeBrokenFeature() {
+  return defineFeature("broken", (r) => {
+    r.authClaims(async () => {
+      throw new Error("pretend the DB just disappeared");
+    });
+  });
+}
+
+// Feature: Drift — declares `teamId` but its hook returns `rouge` as well.
+// Exercises the drift-warning that r.claimKey unlocks: the resolver logs a
+// warn for `rouge` but still merges both into the JWT (best-effort).
+export function makeDriftFeature(shouldFire: { value: boolean }) {
+  return defineFeature("drift", (r) => {
+    r.claimKey("teamId", { type: "string" });
+
+    r.authClaims(async () => {
+      if (!shouldFire.value) return {};
+      return { teamId: "declared", rouge: "undeclared" };
+    });
+  });
+}
+
+// Helper used by tests to build a fake session for a given user/tenant.
+// The sample avoids requiring the full auth-email-password feature —
+// the claim-resolver mechanism is tested directly.
+export function fakeSession(userId: string, tenantId: TenantId): SessionUser {
+  return { id: userId, tenantId, roles: ["User"] };
+}
+```

package/agents/examples/auth-foundation-providers.md

@@ -0,0 +1,155 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/auth-foundation-providers. Do not edit. -->
+
+# auth-foundation-providers
+
+Register custom tenantResolver / tenantExistence via auth-foundation extension points (no anonymousAccess callbacks).
+
+## README
+
+# Auth Foundation Providers
+
+Pluggable auth providers on top of auth-foundation.
+
+## What it shows
+
+- Provider registration shape for email/password (and peers)
+- How foundation wires sessions + JWT issuance
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+## Tests
+
+```bash
+cd samples/recipes/auth-foundation-providers
+bun test
+```
+
+## Source files
+
+### src/__tests__/feature.test.ts
+
+```ts
+import { describe, expect, test } from "bun:test";
+import {
+  authFoundationFeature,
+  resolveAnonymousAccessFromRegistry,
+  resolveTenantExistence,
+  resolveTenantResolver,
+} from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { createRegistry, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { createSubdomainTenantRoutingFeature } from "../feature";
+
+const TENANT = "00000000-0000-4000-8000-0000000000aa" as TenantId;
+const fakeDb = {} as DbConnection;
+
+describe("auth-foundation-providers recipe", () => {
+  test("useExtension registers resolver + existence; boot merge fills anonymousAccess", async () => {
+    const routing = createSubdomainTenantRoutingFeature({
+      lookupBySubdomain: async (sub) => (sub === "acme" ? TENANT : null),
+      existsById: async (id) => id === TENANT,
+      trust: "authoritative",
+    });
+    const registry = createRegistry([authFoundationFeature, routing]);
+
+    const resolved = await resolveTenantResolver({ db: fakeDb, registry });
+    expect(resolved?.trust).toBe("authoritative");
+    expect(
+      await resolved?.resolve({
+        req: { header: (n: string) => (n === "Host" ? "acme.shop.com" : undefined) },
+      }),
+    ).toBe(TENANT);
+
+    const exists = await resolveTenantExistence({ db: fakeDb, registry });
+    expect(await exists?.(TENANT)).toBe(true);
+
+    const anon = await resolveAnonymousAccessFromRegistry({}, { db: fakeDb, registry });
+    expect(anon?.resolverTrust).toBe("authoritative");
+    expect(anon?.tenantResolver).toBeDefined();
+    expect(anon?.tenantExists).toBeDefined();
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Auth-foundation providers — custom tenantResolver + tenantExistence
+//
+// After #1374, apps do NOT pass tenantResolver/tenantExists on
+// anonymousAccess. They mount a feature that registers providers via
+// r.useExtension(EXT_TENANT_RESOLVER / EXT_TENANT_EXISTENCE). Boot
+// (runProdApp / runDevApp) merges them through
+// resolveAnonymousAccessFromRegistry.
+//
+// What to copy:
+//
+//   composeFeatures([
+//     authFoundationFeature,
+//     createSubdomainTenantRoutingFeature({ lookupBySubdomain, existsById }),
+//     …appFeatures,
+//   ], { includeBundled: true })
+//
+//   anonymousAccess: { /* defaultTenantId only, if single-tenant */ }
+//
+// Pair with samples/recipes/anonymous-access-multitenant for the
+// subdomain+cache lookup helpers (reuse createSubdomainResolver inside
+// the provider build).
+
+import {
+  EXT_TENANT_EXISTENCE,
+  EXT_TENANT_RESOLVER,
+  type TenantExistenceProvider,
+  type TenantResolverProvider,
+} from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import {
+  defineFeature,
+  type FeatureDefinition,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+export type SubdomainTenantRoutingOptions = {
+  readonly lookupBySubdomain: (subdomain: string) => Promise<TenantId | null>;
+  readonly existsById: (tenantId: TenantId) => Promise<boolean>;
+  readonly reservedSubdomains?: readonly string[];
+  /** Provider trust — usually "authoritative" for Host-derived tenants. */
+  readonly trust?: "authoritative" | "fallback-only";
+};
+
+export function createSubdomainTenantRoutingFeature(
+  opts: SubdomainTenantRoutingOptions,
+): FeatureDefinition {
+  const trust = opts.trust ?? "authoritative";
+  const reserved = new Set(opts.reservedSubdomains ?? ["www", "app", "api", "admin"]);
+
+  return defineFeature("sample-subdomain-tenant-routing", (r) => {
+    r.requires("auth-foundation");
+
+    const resolverPlugin: TenantResolverProvider = {
+      trust,
+      build: () => async (c: unknown) => {
+        const ctx = c as {
+          req: { header: (n: string) => string | undefined };
+        };
+        const host = ctx.req.header("Host");
+        if (!host) return null;
+        const noPort = host.split(":")[0] ?? host;
+        const labels = noPort.split(".");
+        if (labels.length < 3) return null;
+        const subdomain = labels[0] ?? null;
+        if (subdomain === null || reserved.has(subdomain)) return null;
+        return opts.lookupBySubdomain(subdomain);
+      },
+    };
+
+    const existencePlugin: TenantExistenceProvider = {
+      build: () => (tenantId) => opts.existsById(tenantId as TenantId),
+    };
+
+    r.useExtension(EXT_TENANT_RESOLVER, "subdomain", resolverPlugin);
+    r.useExtension(EXT_TENANT_EXISTENCE, "db", existencePlugin);
+  });
+}
+```