@cosmicdrift/kumiko-samples 0.338.0

package/samples/recipes/apex-surface-auth/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-apex-surface-auth",
+  "description": "Apex-Surface: öffentliche Account-Flows (Login/Register/PW/Löschen) via createPublicSurface + AuthShell, inkl. anonymem email-verifiziertem Deletion-Flow.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}

package/samples/recipes/apex-surface-auth/src/feature.ts

@@ -0,0 +1,113 @@
+// apex-surface-auth Recipe — der evidente Weg für öffentlichen Apex-Content.
+//
+// Eine Kumiko-App hat eine öffentliche Apex-Präsenz (Landing/Login) UND eine
+// schema-getriebene Admin-UI. Die Admin-UI mountet via createKumikoApp (volles
+// Schema). Die Apex mountet via createPublicSurface — schema-LOS, anonym
+// erreichbar, kein Admin-Nav/Topologie-Leak. Beide teilen Locale + Primitives.
+//
+// Dieses Recipe zeigt:
+//   1. Server: die Feature-Komposition für die 4 Account-Flows + den anonymen,
+//      email-verifizierten Deletion-Flow (Lockout-sicher).
+//   2. Client (Kommentar unten + README): wie createPublicSurface + AuthShell
+//      die Screens in der Apex-Chrome mounten.
+//
+// CLIENT-WIRING (apex.tsx der App — renderer-web, hier nur als Referenz, da
+// Recipes keine Browser-Deps ziehen):
+//
+//   import {
+//     ForgotPasswordScreen, SignupScreen, createLoginRoute,
+//     AuthShellProvider, emailPasswordClient,
+//   } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/web";
+//   import {
+//     RequestAccountDeletionScreen, ConfirmAccountDeletionScreen,
+//     defaultTranslations as deletionI18n,
+//   } from "@cosmicdrift/kumiko-bundled-features/user-data-rights/web";
+//   import { createPublicSurface } from "@cosmicdrift/kumiko-renderer-web";
+//
+//   // AuthShell: die Auth-Card rendert in der Marketing-Chrome statt
+//   // Fullscreen. Default (ohne Provider) bleibt der Fullscreen-Wrapper.
+//   const shell = ({ children }) => (
+//     <MarketingChrome>
+//       <AuthShellProvider shell={(card) => <div className="py-12 flex justify-center">{card}</div>}>
+//         {children}
+//       </AuthShellProvider>
+//     </MarketingChrome>
+//   );
+//
+//   // createLoginRoute — NICHT LoginScreen direkt rendern: die Route
+//   // braucht die Challenge-Swap-Logik für einen zweiten Faktor. Ohne die
+//   // (z.B. raw <LoginScreen />) bleibt ein MFA-enrolter User beim Login
+//   // hängen, sobald die App irgendwann auth-mfa mountet. Mountet die App
+//   // auth-mfa, `mfaVerifyScreen: MfaVerifyScreen` (aus
+//   // "@cosmicdrift/kumiko-bundled-features/auth-mfa/web") ergänzen.
+//   const LoginRoute = createLoginRoute({ loginScreenProps: { signupHref: "/signup" } });
+//
+//   createPublicSurface({
+//     clientFeatures: [emailPasswordClient()],   // bringt SessionProvider + i18n
+//     shell,
+//     routes: [
+//       { path: "/login",            component: <LoginRoute /> },
+//       { path: "/signup",           component: <SignupScreen loginHref="/login" /> },
+//       { path: "/forgot-password",  component: <ForgotPasswordScreen loginHref="/login" /> },
+//       { path: "/delete-account",          component: <RequestAccountDeletionScreen /> },
+//       { path: "/delete-account/confirm",  component: <ConfirmAccountDeletionScreen /> },
+//     ],
+//     fallback: <LoginRoute />,
+//   });
+//
+//
+// SERVER-WIRING: die App aktiviert `anonymousAccess` (defaultTenantId = der
+// Apex-Host-Tenant), damit /api/write die anonymen Deletion-Handler erreicht:
+//
+//   runProdApp({ features: composeApexAccountApp({...}),
+//                anonymousAccess: { defaultTenantId: APEX_TENANT_ID } })
+
+import { createAuthEmailPasswordFeature } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
+import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { createComplianceProfilesFeature } from "@cosmicdrift/kumiko-bundled-features/compliance-profiles";
+import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
+import { createDataRetentionFeature } from "@cosmicdrift/kumiko-bundled-features/data-retention";
+import { createPersonalAccessTokensFeature } from "@cosmicdrift/kumiko-bundled-features/personal-access-tokens";
+import { createSessionsFeature } from "@cosmicdrift/kumiko-bundled-features/sessions";
+import { createTenantFeature } from "@cosmicdrift/kumiko-bundled-features/tenant";
+import { createUserFeature } from "@cosmicdrift/kumiko-bundled-features/user";
+import {
+  createUserDataRightsFeature,
+  type SendDeletionVerificationEmailFn,
+} from "@cosmicdrift/kumiko-bundled-features/user-data-rights";
+import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+
+export type ApexAccountAppOptions = {
+  /** HMAC-Secret für das Deletion-Verify-Token. */
+  readonly deletionTokenSecret: string;
+  /** Apex-Route des Confirm-Screens; der Handler hängt das Token als
+   *  URL-Fragment an (`#token=`). */
+  readonly deletionVerifyUrl: string;
+  /** Versand des Verify-Magic-Links. MUSS non-blocking sein (enqueue) — ein
+   *  synchroner Send würde ein Timing-Oracle für Account-Enumeration öffnen. */
+  readonly sendDeletionVerificationEmail: SendDeletionVerificationEmailFn;
+};
+
+// Volle Feature-Komposition für die öffentlichen Account-Flows. Die
+// user-data-rights-Options aktivieren den anonymen Deletion-Flow; die übrigen
+// Features liefern Login/Register/PW (auth-email-password) + die
+// Require-Kette (user-data-rights → data-retention + compliance-profiles +
+// sessions).
+export function composeApexAccountApp(opts: ApexAccountAppOptions): FeatureDefinition[] {
+  return [
+    createConfigFeature(),
+    createUserFeature(),
+    createTenantFeature(),
+    createAuthEmailPasswordFeature(),
+    createDataRetentionFeature(),
+    createComplianceProfilesFeature(),
+    authFoundationFeature,
+    createPersonalAccessTokensFeature({ scopes: {} }),
+    createSessionsFeature(),
+    createUserDataRightsFeature({
+      deletionTokenSecret: opts.deletionTokenSecret,
+      deletionVerifyUrl: opts.deletionVerifyUrl,
+      sendDeletionVerificationEmail: opts.sendDeletionVerificationEmail,
+    }),
+  ];
+}

package/samples/recipes/api-worker-split/README.md

@@ -0,0 +1,68 @@
+# API/Worker-Split
+
+Run Kumiko as two separate processes — an HTTP API that only enqueues jobs,
+and a worker that executes them and applies the read models the API skips.
+This is the deploy topology behind `runSingleInstance: false` +
+`createWorkerEntrypoint`.
+
+## What it shows
+
+- **Two entrypoints, one feature** — `bin/api.ts` starts the API process
+  (`runProdApp({ runSingleInstance: false })`), `bin/worker.ts` the worker
+  (`runWorkerApp`). Both build the same `orders` feature; they differ only
+  in what they run.
+- **API = enqueuer-only** — the API writes events and pushes `runIn:
+  "worker"` jobs onto the BullMQ queue. It consumes nothing and applies no
+  multiStreamProjections.
+- **Worker = the read side** — the worker's event-dispatcher applies the
+  `order-activity` projection and its BullMQ runner executes
+  `process-order`.
+- **The sharp edge, live** — with `runSingleInstance: false` the API
+  process applies no multiStreamProjections. No worker running means the
+  `order-activity` read side stays empty, silently (the 2026-06-11 incident
+  class). The integration test asserts exactly this.
+- **Result written back through the worker dispatcher** — `JobContext` has
+  no `write`/`query` (fw#1717). `bin/worker.ts` wires a write-bridge from
+  `dispatchSystemWrite` and the job uses it to create a `fulfillment` row
+  (same pattern as `inbound-mail-foundation/watch-supervisor.ts`).
+
+## Run
+
+Requires Postgres + Redis (env: `DATABASE_URL`, `REDIS_URL`, `JWT_SECRET`).
+
+```bash
+bun install
+bun run schema:apply        # creates framework + entity tables (kumiko/migrations)
+bun run api                 # terminal 1 — HTTP + enqueue
+bun run worker              # terminal 2 — consumes jobs, applies projections
+```
+
+Prove the topology. `orders:write:order:create` declares `openToAll`, which
+still requires a valid JWT (any authenticated user, no specific role) — grab
+one the same way `src/__tests__/feature.integration.test.ts` does, via
+`api.jwt.sign(adminUser)` on the entrypoint returned by
+`createApiEntrypoint`:
+
+```bash
+curl -X POST http://localhost:3000/api/write \
+  -H 'Content-Type: application/json' \
+  -H "Authorization: Bearer $TOKEN" \
+  -d '{"type":"orders:write:order:create","payload":{"customerName":"Acme GmbH","amount":499}}'
+```
+
+With only the API running, `read_orders` gains the row but
+`read_order_activity` stays empty. Start the worker and both the activity
+row and the `read_fulfillments` row appear.
+
+## Test
+
+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
+bun test src/__tests__/feature.integration.test.ts
+```
+
+Runs both entrypoints in-process against real Postgres + Redis, at the
+`createApiEntrypoint`/`createWorkerEntrypoint` level (not `bin/api.ts`/
+`bin/worker.ts` themselves), and asserts the API-only read side stays empty
+before the worker picks up the job and writes the fulfillment back.

package/samples/recipes/api-worker-split/bin/api.ts

@@ -0,0 +1,13 @@
+// API process — `runSingleInstance: false` makes this process API-only:
+// HTTP + event writes + BullMQ ENQUEUE, no worker-lane consumption, no
+// multiStreamProjection application. A dedicated worker MUST run next to
+// it (bin/worker.ts) or the read-side stays empty.
+import { runProdApp } from "@cosmicdrift/kumiko-server-runtime";
+import { createApiWorkerSplitFeature } from "../src/feature";
+
+await runProdApp({
+  features: [createApiWorkerSplitFeature()],
+  runSingleInstance: false,
+  // worker-lane queue prefix; must match bin/worker.ts.
+  jobs: { queueNamePrefix: "api-worker-split" },
+});

package/samples/recipes/api-worker-split/bin/kumiko.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env bun
+// Schema CLI for the sample: creates the framework infra tables
+// (idempotent) and applies kumiko/migrations. Requires DATABASE_URL.
+import { runStandaloneSchemaCli } from "@cosmicdrift/kumiko-dev-server/schema-apply";
+import { createApiWorkerSplitFeature } from "../src/feature";
+
+await runStandaloneSchemaCli({ features: [createApiWorkerSplitFeature()] });

package/samples/recipes/api-worker-split/bin/worker.ts

@@ -0,0 +1,24 @@
+// Worker process — consumes the worker-lane BullMQ queue and applies the
+// multiStreamProjections the API skipped. No HTTP surface.
+//
+// wireComponents runs after the entrypoint is up and hands over
+// `dispatchSystemWrite` — a dispatcher-scoped system write. The job's
+// write-bridge is wired here (fw#1717): JobContext has no write/query, so
+// background components persist through this dispatcher instead.
+//
+// ponytail: BullMQ may pop jobs between entrypoint.start() and this hook —
+// those hits throw "no fulfill-write bridge wired" and rely on BullMQ retry
+// until the bridge is set. Upgrade: defer job registration until after wire,
+// or hold fulfillWrite behind a deferred Promise.
+import { runWorkerApp } from "@cosmicdrift/kumiko-server-runtime";
+import { createApiWorkerSplitFeature, setOrderFulfillWrite } from "../src/feature";
+
+await runWorkerApp({
+  features: [createApiWorkerSplitFeature()],
+  jobs: { queueNamePrefix: "api-worker-split" },
+  wireComponents: async ({ dispatchSystemWrite }) => {
+    setOrderFulfillWrite(({ handlerQn, payload, tenantId }) =>
+      dispatchSystemWrite({ handlerQn, payload, tenantId }),
+    );
+  },
+});

package/samples/recipes/api-worker-split/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-api-worker-split",
+  "description": "Split deploy topology: API process (runSingleInstance:false, enqueue-only) + worker process (consumes worker-lane jobs, applies multiStreamProjections, writes results back through the worker dispatcher).",
+  "private": true,
+  "scripts": {
+    "api": "bun bin/api.ts",
+    "worker": "bun bin/worker.ts",
+    "schema:apply": "bun bin/kumiko.ts schema apply",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@cosmicdrift/kumiko-dev-server": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*",
+    "@cosmicdrift/kumiko-server-runtime": "workspace:*"
+  }
+}

package/samples/recipes/api-worker-split/src/feature.ts

@@ -0,0 +1,167 @@
+// API/Worker-Split Sample
+//
+// Proves the split deployment topology end-to-end:
+//
+//   - the API process runs `runSingleInstance: false` — it serves HTTP,
+//     writes events, and ENQUEUES worker-lane jobs. It applies no
+//     multiStreamProjections and consumes no jobs.
+//   - the worker process consumes the worker-lane queue and applies the
+//     multiStreamProjections the API skipped (the 2026-06-11 sharp edge:
+//     without a worker the read-side stays empty, silently).
+//   - a worker-lane job writes its RESULT back through the WORKER's
+//     dispatcher — JobContext has no write/query (fw#1717), so the app
+//     wires a write-bridge at boot (see setOrderFulfillWrite below).
+
+import { insertOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { table, text, uuid } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntity,
+  createNumberField,
+  createTextField,
+  defineFeature,
+  type WriteResult,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+const openAccess = {
+  access: {
+    openToAll: {
+      reason:
+        "demo recipe: any signed-in user manages every order and fulfillment; there " +
+        "is no per-user ownership in this sample",
+    },
+  },
+} as const;
+
+// --- Entities ------------------------------------------------------------
+// Both are plain event-sourced CRUD entities. The write handler rows are
+// written synchronously by the event-store executor — the API process
+// always sees them, split or not.
+
+export const orderEntity = createEntity({
+  table: "read_orders",
+  fields: {
+    customerName: createTextField({ personal: { of: "id" }, find: "none", required: true }),
+    amount: createNumberField({ required: true }),
+    status: createTextField({ personal: false, reason: "is_business_data", default: "pending" }),
+  },
+});
+
+export const fulfillmentEntity = createEntity({
+  table: "read_fulfillments",
+  fields: {
+    orderKey: createTextField({ personal: false, reason: "is_system_identifier", required: true }),
+    carrier: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    label: createTextField({ personal: false, reason: "is_business_data", required: true }),
+  },
+});
+
+// --- Worker-applied read side (the sharp edge) ----------------------------
+// This projection is applied by the event-dispatcher of the WORKER process
+// only. `runSingleInstance: false` turns the API's local dispatcher off, so
+// this table stays empty until a worker runs — exactly the 2026-06-11
+// incident class (#512).
+export const orderActivityTable = table("read_order_activity", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  tenantId: uuid("tenant_id").notNull(),
+  orderKey: text("order_key").notNull(),
+});
+
+// --- The write-bridge (fw#1717) -------------------------------------------
+// JobContext deliberately has no write/query — a background job must not
+// bypass the write path (idempotency, PII, transition guards). The app
+// therefore wires a component with the worker's dispatcher at boot and the
+// job calls it. Same pattern as inbound-mail-foundation's watch-supervisor.
+type FulfillWrite = (args: {
+  readonly handlerQn: string;
+  readonly payload: Record<string, unknown>;
+  readonly tenantId: string;
+}) => Promise<WriteResult>;
+
+let fulfillWrite: FulfillWrite | undefined;
+
+/** Called by bin/worker.ts (wireComponents) with dispatchSystemWrite. */
+export function setOrderFulfillWrite(fn: FulfillWrite): void {
+  fulfillWrite = fn;
+}
+
+// Job payloads arrive as `Record<string, unknown>` (JobHandlerFn) — an
+// unchecked `as string` cast here would let a missing/non-string field
+// through silently, writing `orderKey: undefined` / `label: "label-
+// undefined"` instead of failing loudly. This recipe is a copy-paste
+// template, so the cast would get copied along with it.
+const processOrderPayloadSchema = z.object({
+  customerName: z.string().min(1),
+});
+
+export function createApiWorkerSplitFeature() {
+  return defineFeature("orders", (r) => {
+    r.crud("order", orderEntity, { write: openAccess, read: openAccess });
+    r.crud("fulfillment", fulfillmentEntity, { write: openAccess, read: openAccess });
+
+    // Heavy follow-up work, pinned to the worker lane: the API process only
+    // enqueues (its BullMQ client, no consumer), the worker executes.
+    r.job(
+      "process-order",
+      {
+        trigger: { on: "orders:write:order:create" },
+        runIn: "worker",
+      },
+      async (payload, context) => {
+        if (fulfillWrite === undefined) {
+          throw new Error(
+            "process-order: no fulfill-write bridge wired — bin/worker.ts must call setOrderFulfillWrite at boot",
+          );
+        }
+        // Every event-triggered job carries the tenant of the write that
+        // fired it (job-runner sets `_tenantId` from the triggering user)
+        // — reuse it instead of a fixed tenant, or a job triggered by one
+        // tenant's write silently fulfills into another tenant.
+        const tenantId = context.triggeredBy?.tenantId;
+        if (tenantId === undefined) {
+          throw new Error(
+            "process-order: job context has no triggeredBy.tenantId — expected an order.created-triggered job to always carry the triggering write's tenant",
+          );
+        }
+        const { customerName } = processOrderPayloadSchema.parse(payload);
+        const result = await fulfillWrite({
+          handlerQn: "orders:write:fulfillment:create",
+          payload: {
+            orderKey: customerName,
+            carrier: "DHL",
+            label: `label-${customerName}`,
+          },
+          tenantId,
+        });
+        if (!result.isSuccess) {
+          // Throwing lets BullMQ retry the job — a silently dropped
+          // fulfillment would leave the order stuck "pending" forever.
+          throw new Error(
+            `process-order: fulfillment create failed for order "${customerName}": ${result.error?.code ?? "unknown"}`,
+          );
+        }
+      },
+    );
+
+    // Async read model, applied by the WORKER's event-dispatcher. Entity ids
+    // are generated at write time and are not part of the job payload — the
+    // projection keys off the natural key (customerName), the same way a
+    // background write-back would. Note the event type: the write-handler QN
+    // ("orders:write:order:create") triggers jobs synchronously, but the
+    // STORED event is the entity event "order.created" — that's what the
+    // async dispatcher routes on.
+    r.multiStreamProjection({
+      name: "order-activity",
+      table: orderActivityTable,
+      apply: {
+        "order.created": async (event, tx) => {
+          const payload = event.payload as { customerName: string };
+          await insertOne(tx, orderActivityTable, {
+            tenantId: event.tenantId,
+            orderKey: payload.customerName,
+          });
+        },
+      },
+    });
+  });
+}

package/samples/recipes/auth-claims/README.md

@@ -0,0 +1,21 @@
+# 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
+```

package/samples/recipes/auth-claims/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-auth-claims",
+  "description": "r.authClaims() — features contribute identity facts into the JWT at login time with auto-prefixed keys.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}

package/samples/recipes/auth-claims/src/feature.ts

@@ -0,0 +1,123 @@
+// 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/samples/recipes/auth-foundation-providers/README.md

@@ -0,0 +1,19 @@
+# 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
+```

package/samples/recipes/auth-foundation-providers/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-auth-foundation-providers",
+  "description": "Register custom tenantResolver / tenantExistence via auth-foundation extension points (no anonymousAccess callbacks).",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  }
+}