@cosmicdrift/kumiko-samples 0.341.0 → 0.342.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.341.0",
+  "version": "0.342.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.341.0",
+  "version": "0.342.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/src/audit/constants.ts

@@ -24,3 +24,8 @@ export const AUDIT_LOG_SCREEN_ID = "audit-log" as const;
 
 /** Single-event detail screen, breadcrumb-linked to the audit-log list. */
 export const AUDIT_LOG_DETAIL_SCREEN_ID = "audit-log-detail" as const;
+
+/** Config key (system scope) for how long `escapeHatchUse` audit events are kept. */
+export const ESCAPE_HATCH_RETENTION_DAYS_KEY = "audit:config:escape-hatch-retention-days" as const;
+
+export const DEFAULT_ESCAPE_HATCH_RETENTION_DAYS = 90;

package/packages/bundled-features/src/audit/feature.ts

@@ -1,14 +1,22 @@
 import {
   access,
+  createSystemConfig,
   defineFeature,
   type FeatureDefinition,
   i18nKey,
+  SYSTEM_USER_ID,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { AUDIT_LOG_DETAIL_SCREEN_ID, AUDIT_LOG_SCREEN_ID, AuditQueries } from "./constants.js";
+import {
+  AUDIT_LOG_DETAIL_SCREEN_ID,
+  AUDIT_LOG_SCREEN_ID,
+  AuditQueries,
+  DEFAULT_ESCAPE_HATCH_RETENTION_DAYS,
+} from "./constants.js";
 import { escapeHatchUsedSchema } from "./escape-hatch-audit-sink.js";
 import { detailsQuery } from "./handlers/details.query.js";
 import { listQuery } from "./handlers/list.query.js";
 import { AUDIT_I18N } from "./i18n.js";
+import { runEscapeHatchRetention } from "./run-escape-hatch-retention.js";
 
 // Audit feature — exposes a filtered read over the framework's event log.
 //
@@ -18,10 +26,11 @@ import { AUDIT_I18N } from "./i18n.js";
 // the existing `events` table. See handlers/list.query.ts for the filter
 // surface.
 //
-// Retention lives elsewhere. Events are kept indefinitely as the source of
-// truth for state; archive or compress policies are a separate concern
-// (tracked with the snapshot/archive infrastructure that already exists in
-// the framework).
+// Retention: only `escapeHatchUse` events are pruned (daily job, config key
+// `escapeHatchRetentionDays`). All other events stay as the source of truth
+// for state; archive or compress policies are a separate concern (tracked
+// with the snapshot/archive infrastructure that already exists in the
+// framework).
 export function createAuditFeature(): FeatureDefinition {
   return defineFeature(
     "audit",
@@ -35,11 +44,43 @@ export function createAuditFeature(): FeatureDefinition {
         recommended: false,
       });
       r.translations({ keys: AUDIT_I18N });
-      r.requires("tenant", "user");
+      r.requires("tenant", "user", "config");
 
       // Registered so ops tools/MSPs can discover the type — escape-hatch-audit-sink.ts appends it via the low-level event-store API.
       r.defineEvent("escape-hatch-used", escapeHatchUsedSchema, { piiFields: "none" });
 
+      r.config(
+        "escapeHatchRetentionDays",
+        createSystemConfig("number", {
+          default: DEFAULT_ESCAPE_HATCH_RETENTION_DAYS,
+          bounds: { min: 1 },
+        }),
+      );
+
+      r.job({
+        name: "escape-hatch-retention",
+        trigger: { cron: "30 3 * * *" },
+        concurrency: "skip",
+        // pruneEvents needs a transaction-capable connection, which only unsafeRaw() hands a job.
+        escapeHatch: {
+          reason: "prunes expired escapeHatchUse audit events through pruneEvents",
+          grants: ["unsafeRaw"],
+        },
+        handler: async (_payload, ctx) => {
+          if (!ctx.registry) {
+            throw new Error(
+              "escape-hatch-retention: ctx.registry required (JobContext incomplete)",
+            );
+          }
+          await runEscapeHatchRetention({
+            db: ctx.db.unsafeRaw(),
+            registry: ctx.registry,
+            configResolver: ctx.configResolver,
+            userId: ctx._userId ?? SYSTEM_USER_ID,
+          });
+        },
+      });
+
       const queries = {
         list: r.queryHandler(listQuery),
         details: r.queryHandler(detailsQuery),

package/packages/bundled-features/src/audit/run-escape-hatch-retention.ts

@@ -0,0 +1,53 @@
+import type { DbConnection, DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import {
+  type ConfigResolver,
+  type Registry,
+  SYSTEM_TENANT_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { type PruneEventsResult, pruneEvents } from "@cosmicdrift/kumiko-framework/pipeline";
+import { createConfigAccessor } from "../config/index.js";
+import {
+  DEFAULT_ESCAPE_HATCH_RETENTION_DAYS,
+  ESCAPE_HATCH_RETENTION_DAYS_KEY,
+} from "./constants.js";
+import { ESCAPE_HATCH_USE_AGGREGATE_TYPE } from "./escape-hatch-audit-sink.js";
+
+// pruneEvents opens its own transaction, so a runner that cannot begin one (a tx handle) is rejected instead of nested.
+export function isDbConnection(runner: DbRunner): runner is DbConnection {
+  return "begin" in runner && typeof runner.begin === "function";
+}
+
+async function resolveRetentionDays(args: {
+  readonly registry: Registry;
+  readonly configResolver: ConfigResolver | undefined;
+  readonly db: DbConnection;
+  readonly userId: string;
+}): Promise<number> {
+  if (!args.configResolver) return DEFAULT_ESCAPE_HATCH_RETENTION_DAYS;
+  const config = createConfigAccessor(
+    args.registry,
+    args.configResolver,
+    SYSTEM_TENANT_ID,
+    args.userId,
+    args.db,
+  );
+  const raw = await config(ESCAPE_HATCH_RETENTION_DAYS_KEY);
+  return typeof raw === "number" && raw >= 1 ? raw : DEFAULT_ESCAPE_HATCH_RETENTION_DAYS;
+}
+
+export async function runEscapeHatchRetention(args: {
+  readonly db: DbRunner;
+  readonly registry: Registry;
+  readonly configResolver: ConfigResolver | undefined;
+  readonly userId: string;
+}): Promise<PruneEventsResult> {
+  const { db } = args;
+  if (!isDbConnection(db)) {
+    throw new Error("audit escape-hatch retention: a transaction-free DbConnection is required");
+  }
+  const olderThanDays = await resolveRetentionDays({ ...args, db });
+  return pruneEvents(db, {
+    aggregateTypes: [ESCAPE_HATCH_USE_AGGREGATE_TYPE],
+    olderThanDays,
+  });
+}

package/packages/bundled-features/src/auth-email-password/bootstrap.ts

@@ -5,13 +5,17 @@
 // invitation row holds membership role + global roles until the invitee
 // accepts through the regular invite-accept routes.
 
-import { makeDispatchSystemWrite } from "@cosmicdrift/kumiko-framework/api";
+import {
+  makeDispatchSystemWrite,
+  type SystemDispatchArgs,
+} from "@cosmicdrift/kumiko-framework/api";
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import {
   ConfigScopes,
   createSystemUser,
   type TenantId,
+  type WriteResult,
 } from "@cosmicdrift/kumiko-framework/engine";
 import type { Dispatcher } from "@cosmicdrift/kumiko-framework/pipeline";
 import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
@@ -48,6 +52,12 @@ export type BootstrapSeedDeps = {
   readonly tenantId: TenantId;
   readonly db: DbConnection;
   readonly dispatchSystemWrite: ReturnType<typeof makeDispatchSystemWrite>;
+  /** Writes as the system user with the given tenant roles in the seeded
+   *  tenant; use it when the app gates tenant data on its own roles rather
+   *  than SystemAdmin. */
+  readonly dispatchWriteAs: (
+    args: Pick<SystemDispatchArgs, "handlerQn" | "payload"> & { readonly roles: readonly string[] },
+  ) => Promise<WriteResult>;
 };
 
 export type BootstrapConfigValue = string | number | boolean;
@@ -276,7 +286,13 @@ export async function bootstrapTenants(
     const outcome = await ensureTenant(deps, tenant);
     const shouldSeed = outcome === "created" && plan.seed !== undefined;
     if (shouldSeed) {
-      await plan.seed?.({ tenantId: tenant.id, db: deps.db, dispatchSystemWrite });
+      await plan.seed?.({
+        tenantId: tenant.id,
+        db: deps.db,
+        dispatchSystemWrite,
+        dispatchWriteAs: ({ handlerQn, payload, roles }) =>
+          deps.dispatcher.write(handlerQn, payload, createSystemUser(tenant.id, roles)),
+      });
     }
     const configApplied = await applyTenantConfig(deps, tenant);
     tenants.push({ id: tenant.id, outcome, seeded: shouldSeed, configApplied });

package/packages/bundled-features/src/auth-email-password/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.342.0",
+    "type": "improvement",
+    "title": "AuthCard styling hooks (className, headerClassName, titleClassName, bodyClassName)",
+    "detail": "AuthCard takes className, headerClassName, titleClassName and bodyClassName\n`AuthCard` renders the body wrapper (`p-6 pt-0 flex flex-col gap-4`) itself and accepts `className` (Card), `headerClassName`, `titleClassName` and `bodyClassName`, merged with tailwind-merge over the defaults. The auth-email-password and auth-mfa screens no longer carry their own body wrapper; the rendered DOM stays the same. The session bootstrap error screen keeps its former bottom padding through `bodyClassName`."
+  },
+  {
+    "version": "0.342.0",
+    "type": "improvement",
+    "title": "Bootstrap seed can write with app tenant roles",
+    "detail": "Bootstrap seed gets `dispatchWriteAs` to write with app tenant roles instead of SystemAdmin."
+  },
   {
     "version": "0.341.0",
     "type": "breaking",

package/packages/bundled-features/src/auth-email-password/web/auth-form-primitives.tsx

@@ -15,7 +15,7 @@
 // die früheren authButtonClass/authMutedLinkClass sind dorthin gewandert.
 
 import { usePrimitives } from "@cosmicdrift/kumiko-renderer";
-import { BareFormProvider } from "@cosmicdrift/kumiko-renderer-web";
+import { BareFormProvider, cn } from "@cosmicdrift/kumiko-renderer-web";
 import { createContext, type ReactNode, useContext, useEffect, useState } from "react";
 
 // Wrappt die zentrierte Auth-Card in ihre Umgebung. Default = Fullscreen-
@@ -47,25 +47,41 @@ export function useAuthShell(): AuthShellRenderer | null {
 export type AuthCardProps = {
   readonly title?: string;
   readonly subtitle?: ReactNode;
+  /** Merged onto the Card (default `w-full max-w-sm`). */
+  readonly className?: string;
+  readonly headerClassName?: string;
+  readonly titleClassName?: string;
+  /** Merged onto the body wrapper (default `p-6 pt-0 flex flex-col gap-4`). */
+  readonly bodyClassName?: string;
   readonly children: ReactNode;
 };
 
 // kumiko-lint-ignore no-custom-primitives Wraps usePrimitives().Card, pure domain name for the auth-screen chrome, not a primitive reimplementation
-export function AuthCard({ title, subtitle, children }: AuthCardProps): ReactNode {
+export function AuthCard({
+  title,
+  subtitle,
+  className,
+  headerClassName,
+  titleClassName,
+  bodyClassName,
+  children,
+}: AuthCardProps): ReactNode {
   const { Card } = usePrimitives();
   const shell = useAuthShell() ?? defaultAuthShell;
   // h1 (Seiten-Hauptüberschrift) via Header-Slot erhalten — die Card-Default-
   // Header wäre h3. padded:false = Form sitzt randlos wie bisher (bare form).
   const card = (
     <Card
-      className="w-full max-w-sm"
+      className={cn("w-full max-w-sm", className)}
       options={{ padded: false }}
       slots={{
         header:
           title !== undefined || subtitle !== undefined ? (
-            <div className="flex flex-col space-y-1.5 p-6 pb-4">
+            <div className={cn("flex flex-col space-y-1.5 p-6 pb-4", headerClassName)}>
               {title !== undefined && (
-                <h1 className="text-xl font-semibold tracking-tight">{title}</h1>
+                <h1 className={cn("text-xl font-semibold tracking-tight", titleClassName)}>
+                  {title}
+                </h1>
               )}
               {subtitle !== undefined && (
                 <p className="text-sm text-muted-foreground">{subtitle}</p>
@@ -74,7 +90,9 @@ export function AuthCard({ title, subtitle, children }: AuthCardProps): ReactNod
           ) : undefined,
       }}
     >
-      <BareFormProvider>{children}</BareFormProvider>
+      <BareFormProvider>
+        <div className={cn("p-6 pt-0 flex flex-col gap-4", bodyClassName)}>{children}</div>
+      </BareFormProvider>
     </Card>
   );
   return shell(card);

package/packages/bundled-features/src/auth-email-password/web/confirm-account-unlock-screen.tsx

@@ -47,12 +47,10 @@ export function ConfirmAccountUnlockScreen({
   if (status === "missing-token") {
     return (
       <AuthCard title={title ?? t("auth.unlockAccount.errorTitle")}>
-        <div className="p-6 pt-0 flex flex-col gap-4">
-          <p className="text-sm text-muted-foreground">{t("auth.unlockAccount.missingToken")}</p>
-          <Link href={loginHref} variant="muted">
-            {t("auth.unlockAccount.goToLogin")}
-          </Link>
-        </div>
+        <p className="text-sm text-muted-foreground">{t("auth.unlockAccount.missingToken")}</p>
+        <Link href={loginHref} variant="muted">
+          {t("auth.unlockAccount.goToLogin")}
+        </Link>
       </AuthCard>
     );
   }
@@ -72,12 +70,10 @@ export function ConfirmAccountUnlockScreen({
   if (status === "success") {
     return (
       <AuthCard title={title ?? t("auth.unlockAccount.successTitle")}>
-        <div className="p-6 pt-0 flex flex-col gap-4">
-          <p className="text-sm text-muted-foreground">{t("auth.unlockAccount.successBody")}</p>
-          <Link href={loginHref} variant="button">
-            {t("auth.unlockAccount.goToLogin")}
-          </Link>
-        </div>
+        <p className="text-sm text-muted-foreground">{t("auth.unlockAccount.successBody")}</p>
+        <Link href={loginHref} variant="button">
+          {t("auth.unlockAccount.goToLogin")}
+        </Link>
       </AuthCard>
     );
   }
@@ -85,12 +81,10 @@ export function ConfirmAccountUnlockScreen({
   // status === "error"
   return (
     <AuthCard title={title ?? t("auth.unlockAccount.errorTitle")}>
-      <div className="p-6 pt-0 flex flex-col gap-4">
-        <p className="text-sm text-muted-foreground">{t("auth.unlockAccount.errorBody")}</p>
-        <Link href={loginHref} variant="muted">
-          {t("auth.unlockAccount.goToLogin")}
-        </Link>
-      </div>
+      <p className="text-sm text-muted-foreground">{t("auth.unlockAccount.errorBody")}</p>
+      <Link href={loginHref} variant="muted">
+        {t("auth.unlockAccount.goToLogin")}
+      </Link>
     </AuthCard>
   );
 }

package/packages/bundled-features/src/auth-email-password/web/forgot-password-screen.tsx

@@ -72,7 +72,7 @@ export function ForgotPasswordScreen({
   return (
     <AuthCard title={effectiveTitle} subtitle={subtitle}>
       {done ? (
-        <div className="p-6 pt-0 flex flex-col gap-4">
+        <>
           <Banner variant="info">
             <p className="font-medium text-foreground">{t("auth.forgotPassword.successTitle")}</p>
             <p className="mt-1">{t("auth.forgotPassword.successBody")}</p>
@@ -80,9 +80,9 @@ export function ForgotPasswordScreen({
           <Link href={loginHref} variant="muted">
             {t("auth.forgotPassword.backToLogin")}
           </Link>
-        </div>
+        </>
       ) : (
-        <div className="p-6 pt-0 flex flex-col gap-4">
+        <>
           <p className="text-sm text-muted-foreground">{t("auth.forgotPassword.intro")}</p>
           <Form onSubmit={onSubmit}>
             <Field id="forgot-email" label={t("auth.forgotPassword.email")} required>
@@ -104,7 +104,7 @@ export function ForgotPasswordScreen({
           <Link href={loginHref} variant="muted" className="self-center">
             {t("auth.forgotPassword.backToLogin")}
           </Link>
-        </div>
+        </>
       )}
     </AuthCard>
   );

package/packages/bundled-features/src/auth-email-password/web/invite-accept-screen.tsx

@@ -186,87 +186,83 @@ export function InviteAcceptScreen({
   if (token === "") {
     return (
       <AuthCard title={effectiveTitle}>
-        <div className="p-6 pt-0 flex flex-col gap-4">
-          <p className="text-sm text-muted-foreground">{t("auth.inviteAccept.missingToken")}</p>
-          <Link href={loginHref} variant="muted">
-            {t("auth.inviteAccept.goToLogin")}
-          </Link>
-        </div>
+        <p className="text-sm text-muted-foreground">{t("auth.inviteAccept.missingToken")}</p>
+        <Link href={loginHref} variant="muted">
+          {t("auth.inviteAccept.goToLogin")}
+        </Link>
       </AuthCard>
     );
   }
 
   return (
     <AuthCard title={effectiveTitle}>
-      <div className="p-6 pt-0 flex flex-col gap-4">
-        <p className="text-sm text-muted-foreground">{t("auth.inviteAccept.intro")}</p>
+      <p className="text-sm text-muted-foreground">{t("auth.inviteAccept.intro")}</p>
 
-        {mode === "loggedin" ? (
-          <Form onSubmit={onSubmit}>
-            <p className="text-sm">
-              {t("auth.inviteAccept.loggedInAs", { email: session.user?.email ?? "" })}
-            </p>
-            {error !== null && <Banner variant="error">{error}</Banner>}
-            <Button type="submit" loading={submitting} disabled={submitting}>
-              {submitting ? t("auth.inviteAccept.submitting") : t("auth.inviteAccept.acceptButton")}
-            </Button>
-            <Button
-              type="button"
-              variant="secondary"
-              onClick={() => {
-                setMode("anon-existing");
-              }}
-            >
-              {t("auth.inviteAccept.useOtherAccount")}
-            </Button>
-          </Form>
-        ) : (
-          <Form onSubmit={onSubmit}>
-            {mode === "anon-existing" && (
-              <Field id="invite-email" label={t("auth.inviteAccept.email")} required>
-                <Input
-                  kind="email"
-                  id="invite-email"
-                  name="invite-email"
-                  value={email}
-                  onChange={setEmail}
-                  disabled={submitting}
-                  required
-                  autoComplete="email"
-                />
-              </Field>
-            )}
-            <Field id="invite-password" label={t("auth.inviteAccept.password")} required>
+      {mode === "loggedin" ? (
+        <Form onSubmit={onSubmit}>
+          <p className="text-sm">
+            {t("auth.inviteAccept.loggedInAs", { email: session.user?.email ?? "" })}
+          </p>
+          {error !== null && <Banner variant="error">{error}</Banner>}
+          <Button type="submit" loading={submitting} disabled={submitting}>
+            {submitting ? t("auth.inviteAccept.submitting") : t("auth.inviteAccept.acceptButton")}
+          </Button>
+          <Button
+            type="button"
+            variant="secondary"
+            onClick={() => {
+              setMode("anon-existing");
+            }}
+          >
+            {t("auth.inviteAccept.useOtherAccount")}
+          </Button>
+        </Form>
+      ) : (
+        <Form onSubmit={onSubmit}>
+          {mode === "anon-existing" && (
+            <Field id="invite-email" label={t("auth.inviteAccept.email")} required>
               <Input
-                kind="password"
-                id="invite-password"
-                name="invite-password"
-                value={password}
-                onChange={setPassword}
+                kind="email"
+                id="invite-email"
+                name="invite-email"
+                value={email}
+                onChange={setEmail}
                 disabled={submitting}
                 required
-                autoComplete={mode === "anon-existing" ? "current-password" : "new-password"}
+                autoComplete="email"
               />
             </Field>
-            {error !== null && <Banner variant="error">{error}</Banner>}
-            <Button type="submit" loading={submitting} disabled={submitting}>
-              {submitting ? t("auth.inviteAccept.submitting") : t("auth.inviteAccept.submit")}
-            </Button>
-            <Button
-              type="button"
-              variant="secondary"
-              onClick={() => {
-                setMode(mode === "anon-existing" ? "anon-new" : "anon-existing");
-                setError(null);
-              }}
-            >
-              {mode === "anon-existing"
-                ? t("auth.inviteAccept.toggleNew")
-                : t("auth.inviteAccept.toggleExisting")}
-            </Button>
-          </Form>
-        )}
-      </div>
+          )}
+          <Field id="invite-password" label={t("auth.inviteAccept.password")} required>
+            <Input
+              kind="password"
+              id="invite-password"
+              name="invite-password"
+              value={password}
+              onChange={setPassword}
+              disabled={submitting}
+              required
+              autoComplete={mode === "anon-existing" ? "current-password" : "new-password"}
+            />
+          </Field>
+          {error !== null && <Banner variant="error">{error}</Banner>}
+          <Button type="submit" loading={submitting} disabled={submitting}>
+            {submitting ? t("auth.inviteAccept.submitting") : t("auth.inviteAccept.submit")}
+          </Button>
+          <Button
+            type="button"
+            variant="secondary"
+            onClick={() => {
+              setMode(mode === "anon-existing" ? "anon-new" : "anon-existing");
+              setError(null);
+            }}
+          >
+            {mode === "anon-existing"
+              ? t("auth.inviteAccept.toggleNew")
+              : t("auth.inviteAccept.toggleExisting")}
+          </Button>
+        </Form>
+      )}
     </AuthCard>
   );
 }