@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/apex-surface-auth.md

@@ -0,0 +1,355 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/apex-surface-auth. Do not edit. -->
+
+# apex-surface-auth
+
+Apex-Surface: öffentliche Account-Flows (Login/Register/PW/Löschen) via createPublicSurface + AuthShell, inkl. anonymem email-verifiziertem Deletion-Flow.
+
+## README
+
+# apex-surface-auth
+
+The **standard pattern for public apex auth**: login, signup, forgot-password,
+and account-deletion on your marketing surface — schema-less, anonymously
+reachable, without leaking admin nav or internal topology.
+
+A typical app has two mounts sharing locale and primitives:
+
+- **Admin UI** → `createKumikoApp` (loads the full schema after login via
+  the authenticated `GET /api/schema`)
+- **Apex** → `createPublicSurface` (no schema, ever)
+
+## What it shows
+
+- **Four public routes** — `/login`, `/signup`, `/forgot-password`,
+  `/delete-account` (+ confirm) using bundled auth screens.
+- **`createPublicSurface`** — stacks `clientFeatures` providers and i18n only,
+  **not** their gates (an `AuthGate` would lock the public surface).
+- **`AuthShellProvider`** — auth card inside marketing chrome instead of
+  fullscreen (optional; default fullscreen still works).
+- **`composeApexAccountApp()`** — server feature list for all four flows.
+- **Anonymous deletion** — email-verified magic-link flow when the user cannot
+  log in (GDPR Art. 17 lockout case).
+- **`anonymousAccess`** — lets unauthenticated `/api/write` hit anonymous
+  handlers on the apex host tenant.
+
+## Client: `createPublicSurface` + `AuthShell`
+
+```tsx illustration
+import {
+  ForgotPasswordScreen, SignupScreen, createLoginRoute,
+  AuthShellProvider, emailPasswordClient,
+} from "@cosmicdrift/kumiko-bundled-features/auth-email-password/web";
+import {
+  RequestAccountDeletionScreen, ConfirmAccountDeletionScreen,
+} from "@cosmicdrift/kumiko-bundled-features/user-data-rights/web";
+import { createPublicSurface } from "@cosmicdrift/kumiko-renderer-web";
+
+// createLoginRoute, not a raw LoginScreen render — it owns the challenge-
+// swap for a second factor, so mounting auth-mfa later doesn't need this
+// route touched again. Pass `mfaVerifyScreen: MfaVerifyScreen` (from
+// `.../auth-mfa/web`) once the app mounts auth-mfa.
+const LoginRoute = createLoginRoute({ loginScreenProps: { signupHref: "/signup" } });
+
+createPublicSurface({
+  clientFeatures: [emailPasswordClient()],   // SessionProvider + i18n
+  shell: ({ children }) => (
+    <MarketingChrome>
+      <AuthShellProvider shell={(card) => <div className="py-12 flex justify-center">{card}</div>}>
+        {children}
+      </AuthShellProvider>
+    </MarketingChrome>
+  ),
+  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: composition + `anonymousAccess`
+
+`composeApexAccountApp()` (see `src/feature.ts`) mounts features for all four
+flows. Login/signup/password reset come from `auth-email-password`; the
+anonymous **email-verified** deletion flow from `user-data-rights`:
+
+- `request-deletion-by-email` (anonymous, enumeration-safe) → magic link
+- `confirm-deletion-by-token` (anonymous) → starts grace period
+
+```ts illustration
+runProdApp({
+  features: composeApexAccountApp({
+    deletionTokenSecret: process.env.DELETION_TOKEN_SECRET!,
+    deletionVerifyUrl: "https://app.example.com/delete-account/confirm",
+    sendDeletionVerificationEmail: async ({ email, verifyUrl }) => {
+      // Must be non-blocking (enqueue) — synchronous send enables timing oracle.
+      await delivery.notify("account.deletion.verify", { email, verifyUrl });
+    },
+  }),
+  anonymousAccess: { defaultTenantId: APEX_TENANT_ID },
+});
+```
+
+## Why deletion is anonymous
+
+GDPR Art. 17 applies when the user **cannot log in** (lockout). The flow is
+email-verified (magic link), not login-gated. The HMAC token carries `userId`
++ expiry (no DB table); purpose `"deletion-request"` blocks replay on other
+token endpoints. Second confirm is idempotent (`user_not_in_active_state`).
+
+## 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
+bun test src/__tests__/feature.integration.test.ts
+```
+
+Proves end-to-end over real `/api/write` without auth:
+
+1. `request-deletion-by-email` → verification email enqueued
+2. `confirm-deletion-by-token` → user status `DeletionRequested`
+3. Unknown email → same 200 response, no mail (enumeration-safe)
+
+## Related samples
+
+- [user-profile](/en/samples/recipes-user-profile/) — logged-in self-service
+  profile (password, email, deletion while authenticated).
+- [session-revocation](/en/samples/recipes-session-revocation/) — wire
+  `createSessionCallbacks()` so logout invalidates JWTs server-side.
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Beweist: composeApexAccountApp() bootet (volle Account-Komposition inkl.
+// auth + user-data-rights) UND der anonyme email-verifizierte Deletion-Flow
+// läuft end-to-end durch /api/write OHNE Auth (anonymousAccess).
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import {
+  tenantComplianceProfileEntity,
+  tenantComplianceProfileTable,
+} from "@cosmicdrift/kumiko-bundled-features/compliance-profiles";
+import { USER_STATUS, userEntity, userTable } from "@cosmicdrift/kumiko-bundled-features/user";
+import type { SendDeletionVerificationEmailFn } from "@cosmicdrift/kumiko-bundled-features/user-data-rights";
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createEventsTable, eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { resetTestTables, seedRow } from "@cosmicdrift/kumiko-framework/testing";
+import { composeApexAccountApp } from "../feature";
+
+const REQUEST_BY_EMAIL = "user-data-rights:write:request-deletion-by-email";
+const CONFIRM_BY_TOKEN = "user-data-rights:write:confirm-deletion-by-token";
+const SECRET = "recipe-deletion-secret-0123456789";
+const VERIFY_URL = "https://app.example.test/delete-account/confirm";
+
+const tenant = testTenantId(1);
+const user = createTestUser({ id: 7, tenantId: tenant, roles: ["Member"] });
+const EMAIL = "user@example.com";
+
+const verifyCalls: Parameters<SendDeletionVerificationEmailFn>[0][] = [];
+const sendDeletionVerificationEmail: SendDeletionVerificationEmailFn = async (args) => {
+  verifyCalls.push(args);
+};
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: composeApexAccountApp({
+      deletionTokenSecret: SECRET,
+      deletionVerifyUrl: VERIFY_URL,
+      sendDeletionVerificationEmail,
+    }),
+    anonymousAccess: { defaultTenantId: tenant },
+  });
+  await unsafeCreateEntityTable(stack.db, userEntity);
+  await unsafeCreateEntityTable(stack.db, tenantComplianceProfileEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  verifyCalls.length = 0;
+  await resetTestTables(stack.db, [userTable, tenantComplianceProfileTable, eventsTable]);
+  await seedRow(stack.db, userTable, {
+    id: user.id,
+    tenantId: tenant,
+    email: EMAIL,
+    passwordHash: "hashed",
+    displayName: "User",
+    locale: "de",
+    emailVerified: true,
+    roles: '["Member"]',
+    status: USER_STATUS.Active,
+    gracePeriodEnd: null,
+  });
+});
+
+describe("apex-surface-auth recipe", () => {
+  test("anonymer Deletion-Flow: request-by-email → confirm-by-token → Grace-Period", async () => {
+    const reqRes = await stack.http.raw("POST", "/api/write", {
+      type: REQUEST_BY_EMAIL,
+      payload: { email: EMAIL },
+    });
+    expect(reqRes.status).toBe(200);
+    expect(verifyCalls).toHaveLength(1);
+
+    const verifyUrl = new URL(verifyCalls[0]?.verifyUrl ?? "");
+    const token = new URLSearchParams(verifyUrl.hash.slice(1)).get("token") ?? "";
+    expect(token.length).toBeGreaterThan(0);
+
+    const confirmRes = await stack.http.raw("POST", "/api/write", {
+      type: CONFIRM_BY_TOKEN,
+      payload: { token },
+    });
+    expect(confirmRes.status).toBe(200);
+
+    const rows = (await selectMany(stack.db, userTable, { id: user.id })) as Array<{
+      status: string;
+    }>;
+    expect(rows[0]?.status).toBe(USER_STATUS.DeletionRequested);
+  });
+
+  test("enumeration-safe: unbekannte Email → success, keine Mail", async () => {
+    const res = await stack.http.raw("POST", "/api/write", {
+      type: REQUEST_BY_EMAIL,
+      payload: { email: "nobody@example.com" },
+    });
+    expect(res.status).toBe(200);
+    expect(verifyCalls).toHaveLength(0);
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// 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,
+    }),
+  ];
+}
+```