@cosmicdrift/kumiko-samples 0.359.0 → 0.361.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.359.0",
+  "version": "0.361.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.359.0",
+  "version": "0.361.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>",
@@ -116,6 +116,7 @@
     "./channel-teams": "./src/channel-teams/index.ts",
     "./channel-telegram": "./src/channel-telegram/index.ts",
     "./renderer-simple": "./src/renderer-simple/index.ts",
+    "./renderer-pdf": "./src/renderer-pdf/index.ts",
     "./files-provider-s3": "./src/files-provider-s3/index.ts",
     "./rate-limiting": "./src/rate-limiting/index.ts",
     "./presets": "./src/presets/index.ts",
@@ -166,6 +167,7 @@
     "mailparser": "^3.9.32",
     "marked": "^18.0.3",
     "nodemailer": "^10.0.13",
+    "pdf-lib": "^1.17.1",
     "qrcode": "^1.5.4",
     "react": "^19.2.6",
     "sharp": "^0.35.5",
@@ -555,6 +557,10 @@
         "types": "./dist/renderer-simple/index.d.ts",
         "default": "./dist/renderer-simple/index.js"
       },
+      "./renderer-pdf": {
+        "types": "./dist/renderer-pdf/index.d.ts",
+        "default": "./dist/renderer-pdf/index.js"
+      },
       "./files-provider-s3": {
         "types": "./dist/files-provider-s3/index.d.ts",
         "default": "./dist/files-provider-s3/index.js"
@@ -683,6 +689,7 @@
     "@testing-library/user-event": "^14.6.1",
     "@cosmicdrift/kumiko-locale-de": "workspace:*",
     "@cosmicdrift/kumiko-locale-es": "workspace:*",
-    "jsqr": "^1.4.0"
+    "jsqr": "^1.4.0",
+    "unpdf": "^1.8.1"
   }
 }

package/packages/bundled-features/src/audit/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.361.0",
+    "type": "fix",
+    "title": "Audit log works under an active subject KMS",
+    "detail": "audit list, audit details and user-data-rights my-audit-log returned event payloads as stored. With a subject KMS configured the payload carried kumiko-pii ciphertext and the API leak guard answered 500 pii_ciphertext_leak. Every PII ciphertext string in the payload is now replaced by REDACTED_PII_PLACEHOLDER (\"[[personal data]]\"); the audit log still never shows plaintext PII."
+  },
   {
     "version": "0.353.0",
     "type": "fix",

package/packages/bundled-features/src/audit/handlers/details.query.ts

@@ -7,6 +7,7 @@ import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import * as z from "zod";
+import { redactPiiCiphertext } from "../../shared/index.js";
 import { AUDIT_SCOPE_VALUES } from "../constants.js";
 import { resolveAuditScopeFilter } from "./resolve-audit-tenant.js";
 
@@ -51,7 +52,7 @@ export const detailsQuery = defineQueryHandler({
       aggregateType: row.aggregateType,
       version: row.version,
       type: row.type,
-      payload: row.payload,
+      payload: redactPiiCiphertext(row.payload),
       metadata: row.metadata,
       createdAt: row.createdAt,
       createdBy: row.createdBy,

package/packages/bundled-features/src/audit/handlers/list.query.ts

@@ -9,16 +9,15 @@
 // A SystemAdmin can pass scope "system" to read the app-instance system events
 // (e.g. app.started); no other cross-tenant read exists.
 //
-// Sensitive field-values are ciphertext inside the event payload (the log
-// carries them encrypted); stripSensitive only strips the event echo. This
-// query returns payloads as stored, so a sensitive value surfaces as ciphertext,
-// never as plaintext.
+// Event payloads hold PII as subject-KMS ciphertext; it is replaced by
+// REDACTED_PII_PLACEHOLDER before returning, since the API leak guard refuses ciphertext.
 
 import { selectMany, type WhereObject } from "@cosmicdrift/kumiko-framework/bun-db";
 import { access, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
+import { redactPiiCiphertext } from "../../shared/index.js";
 import { AUDIT_SCOPE_VALUES } from "../constants.js";
 import { resolveAuditScopeFilter } from "./resolve-audit-tenant.js";
 
@@ -132,7 +131,7 @@ export const listQuery = defineQueryHandler({
       aggregateType: r.aggregateType,
       version: r.version,
       type: r.type,
-      payload: r.payload,
+      payload: redactPiiCiphertext(r.payload),
       metadata: r.metadata,
       createdAt: r.createdAt,
       createdBy: r.createdBy,

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

@@ -452,6 +452,8 @@ export type CurrentUserProfile = {
   readonly email: string;
   readonly displayName: string;
   readonly locale?: string;
+  /** Effective IANA zone (user override, else tenant, else UTC). */
+  readonly effectiveTimeZone?: string;
   readonly globalRoles: readonly string[];
 };
 
@@ -477,6 +479,7 @@ export async function fetchCurrentUser(): Promise<CurrentUserProfile | null> {
       email: string;
       displayName: string;
       locale?: string;
+      effectiveTimeZone?: string;
       // JSON-encoded string[] — siehe userEntity.roles. Default "[]" wenn
       // keine globalen Rollen.
       roles?: string;
@@ -488,6 +491,9 @@ export async function fetchCurrentUser(): Promise<CurrentUserProfile | null> {
     email: body.data.email,
     displayName: body.data.displayName,
     ...(body.data.locale !== undefined && { locale: body.data.locale }),
+    ...(body.data.effectiveTimeZone !== undefined && {
+      effectiveTimeZone: body.data.effectiveTimeZone,
+    }),
     globalRoles: parseRoles(body.data.roles),
   };
 }

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

@@ -10,8 +10,20 @@
 // und die Transitions.
 
 import { readCsrfToken } from "@cosmicdrift/kumiko-dispatcher-live";
-import { useSessionEndedSignal } from "@cosmicdrift/kumiko-renderer";
-import { createContext, type ReactNode, useCallback, useContext, useEffect, useState } from "react";
+import {
+  type CurrentUser,
+  CurrentUserProvider,
+  useSessionEndedSignal,
+} from "@cosmicdrift/kumiko-renderer";
+import {
+  createContext,
+  type ReactNode,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from "react";
 import {
   AuthRequestError,
   type CurrentUserProfile,
@@ -232,7 +244,31 @@ export function SessionProvider({
   }, []);
 
   const api: SessionApi = { ...state, login, logout, switchTenant, refresh: doRefresh };
-  return <SessionContext.Provider value={api}>{children}</SessionContext.Provider>;
+  // Keyed on the primitives, not the profile object: every refresh (tenant
+  // switch, session bootstrap retry) builds a new profile object, and a new
+  // CurrentUser reference would re-seed a create form and drop typed input.
+  const profile = state.user;
+  const userId = profile?.id;
+  const userEmail = profile?.email;
+  const userDisplayName = profile?.displayName;
+  const userTimeZone = profile?.effectiveTimeZone;
+  const currentUser = useMemo<CurrentUser | undefined>(
+    () =>
+      userId === undefined || userEmail === undefined || userDisplayName === undefined
+        ? undefined
+        : {
+            id: userId,
+            email: userEmail,
+            displayName: userDisplayName,
+            ...(userTimeZone !== undefined && { timeZone: userTimeZone }),
+          },
+    [userId, userEmail, userDisplayName, userTimeZone],
+  );
+  return (
+    <SessionContext.Provider value={api}>
+      <CurrentUserProvider user={currentUser}>{children}</CurrentUserProvider>
+    </SessionContext.Provider>
+  );
 }
 
 export function useSession(): SessionApi {

package/packages/bundled-features/src/billing-foundation/consumer-protection/termination-pages.ts

@@ -1,7 +1,7 @@
 // Public § 312k pages (/legal/kuendigen, /legal/cancel): form → review → confirm,
 // no JavaScript. Every echoed value goes through escapeHtml/escapeHtmlAttr.
 
-import type { AnonymousExtraRoute } from "@cosmicdrift/kumiko-framework/api";
+import { type AnonymousExtraRoute, getSessionCookies } from "@cosmicdrift/kumiko-framework/api";
 import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
 import type { Context } from "hono";
 import { getCookie } from "hono/cookie";
@@ -279,7 +279,6 @@ type WriteResponseBody = {
 const RATE_LIMITED_CODE = "rate_limited";
 
 const TENANT_HEADER = "x-tenant";
-const TENANT_COOKIE = "kumiko_tenant";
 // Exactly what the anonymous tenant resolution reads. The resolver and its
 // trust rules still decide; the re-entry only sees what a direct /api/write
 // from this client would see. Never the session cookie or Authorization (the
@@ -298,9 +297,10 @@ function reentryHeaders(c: Context): Headers {
     const value = c.req.header(name);
     if (value !== undefined) headers.set(name, value);
   }
-  const tenantCookie = getCookie(c, TENANT_COOKIE);
+  const tenantCookieName = getSessionCookies(c).names.tenant;
+  const tenantCookie = getCookie(c, tenantCookieName);
   if (tenantCookie !== undefined) {
-    headers.set("cookie", `${TENANT_COOKIE}=${encodeURIComponent(tenantCookie)}`);
+    headers.set("cookie", `${tenantCookieName}=${encodeURIComponent(tenantCookie)}`);
   }
   return headers;
 }

package/packages/bundled-features/src/cap-counter/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.361.0",
+    "type": "improvement",
+    "title": "cap-counter exports capReservationsTable and capReservationsTableMeta",
+    "detail": "The reservation table store_cap_reservations was only reachable through internal imports, so kumiko-enterprise redeclared it in a test. The cap-counter entry now exports capReservationsTable and capReservationsTableMeta, following the feature-toggles pattern."
+  },
   {
     "version": "0.358.0",
     "type": "improvement",

package/packages/bundled-features/src/cap-counter/index.ts

@@ -49,6 +49,7 @@ export {
   type StockCapGuard,
   type StockCapSpec,
 } from "./stock-cap-guard.js";
+export { capReservationsTable, capReservationsTableMeta } from "./tables.js";
 export {
   createValueCapGuard,
   type ValueCapGuard,

package/packages/bundled-features/src/data-retention/run-retention-cleanup.ts

@@ -55,6 +55,7 @@ import {
   nullBlindIndexesForSubject,
   type TenantDb,
   type WhereObject,
+  WritePurposes,
 } from "@cosmicdrift/kumiko-framework/db";
 import { deleteStoredFileAndDerivatives } from "@cosmicdrift/kumiko-framework/derivatives";
 import {
@@ -259,14 +260,14 @@ async function forgetRowAndEraseKeys(args: {
 type FileFieldPlan = {
   /** type file|image — stores the fileRef-id directly in the entity column. */
   readonly singleFields: readonly string[];
-  /** type files|images — no entity column, resolved via file_refs. */
+  /** type files|images — resolved via file_refs (bound by entityType/entityId/fieldName). */
   readonly multiFields: readonly string[];
 };
 
 const NO_FILE_FIELDS: FileFieldPlan = { singleFields: [], multiFields: [] };
 
 // file/image = single-column fields (fileRef-id lives directly in the entity
-// row); files/images = plural, no column, resolved via file_refs. Same set
+// row); files/images = plural, resolved via file_refs. Same set
 // as boot-validator/entity-handler.ts FILE_FIELD_TYPES and engine's
 // isFileField — inlined here rather than importing across the package
 // barrel since this module already needs the single/multi split, not just
@@ -285,8 +286,8 @@ function planFileFields(fields: Readonly<Record<string, unknown>>): FileFieldPla
 }
 
 // Every fileRef-id a row's file/image/files/images-fields reference: single
-// fields hold the id in their own column, plural fields have no column and
-// resolve via file_refs (tenantId, entityType, entityId, fieldName).
+// fields hold the id in their own column, plural fields resolve
+// via file_refs (tenantId, entityType, entityId, fieldName).
 async function collectFileRefIds(
   db: DbRunner,
   tenantId: TenantId,
@@ -771,7 +772,8 @@ export async function runRetentionCleanup(
           proj.table,
           { ...where, isDeleted: false },
           batchLimit,
-          (id) => executor.delete({ id }, systemUser, tdb),
+          (id) =>
+            executor.delete({ id }, systemUser, tdb, { writePurpose: WritePurposes.retention }),
         );
         break;
       }
@@ -803,7 +805,10 @@ export async function runRetentionCleanup(
           batchLimit,
           targets,
           (id, changes) =>
-            executor.update({ id, changes }, systemUser, tdb, { skipOptimisticLock: true }),
+            executor.update({ id, changes }, systemUser, tdb, {
+              skipOptimisticLock: true,
+              writePurpose: WritePurposes.retention,
+            }),
         );
         break;
       }

package/packages/bundled-features/src/folders-user-data/hooks.ts

@@ -4,7 +4,7 @@
 // Mirrors credit-user-data — standard tenant-scoped pattern, no name-stripping
 // (a folder name is tenant data, not per-user PII).
 
-import type { EventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { type EventStoreExecutor, WritePurposes } from "@cosmicdrift/kumiko-framework/db";
 import {
   createEntityExecutor,
   createSystemUser,
@@ -64,7 +64,9 @@ function tenantScopedDelete(
     const systemUser = createSystemUser(ctx.tenantId);
     const rows = await ctx.db.selectMany<{ id: string }>(table, { tenantId: ctx.tenantId });
     for (const row of rows) {
-      await executor.delete({ id: row.id }, systemUser, ctx.db);
+      await executor.delete({ id: row.id }, systemUser, ctx.db, {
+        writePurpose: WritePurposes.erasure,
+      });
     }
   };
 }

package/packages/bundled-features/src/form-draft-user-data/hooks.ts

@@ -3,6 +3,7 @@
 // consumers without the user-data-rights pipeline don't pull a hard
 // dependency.
 
+import { WritePurposes } from "@cosmicdrift/kumiko-framework/db";
 import {
   createSystemUser,
   type UserDataDeleteHook,
@@ -42,7 +43,9 @@ export const formDraftDeleteHook: UserDataDeleteHook = async (ctx) => {
   const systemUser = createSystemUser(ctx.tenantId);
   const failures: string[] = [];
   for (const row of rows) {
-    const result = await formDraftExecutor.delete({ id: row.id }, systemUser, ctx.db);
+    const result = await formDraftExecutor.delete({ id: row.id }, systemUser, ctx.db, {
+      writePurpose: WritePurposes.erasure,
+    });
     if (!result.isSuccess) {
       failures.push(`${row.id}: ${result.error.message}`);
     }

package/packages/bundled-features/src/jobs/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.360.0",
+    "type": "fix",
+    "title": "Finished tenant job run replaces the older one atomically",
+    "detail": "recordTenantRunOutcome wrote the new completed or failed row and pruned older finished rows of the same tenant, job and subject in two separate statements, so the store briefly held two finished rows per subject, and two runs of one subject finishing together could each miss the other's row and leave both. Both writes now run in one transaction under a per-key advisory lock (namespace tjrl). jobs:query:tenant-runs already showed only the newest finished row, so its result does not change."
+  },
   {
     "version": "0.354.0",
     "type": "breaking",

package/packages/bundled-features/src/jobs/job-run-logger.ts

@@ -167,6 +167,8 @@ async function encryptStartedPayload(
 // pg_advisory_xact_lock namespace (int4): 'tjfl' as ASCII, disjoint from the
 // framework's other fixed advisory-lock keys.
 const TENANT_JOB_FAILURE_LOCK_NAMESPACE = 0x746a666c;
+// 'tjrl': serialises the finished-row write + prune per tenant run key.
+const TENANT_JOB_RUN_LOCK_NAMESPACE = 0x746a726c;
 
 // fw#3079 — which row the tenant-visible failure record lives in: one per
 // (tenant, job, subject), so the next outcome of the same work replaces or
@@ -311,16 +313,27 @@ async function recordTenantRunOutcome(
     // skip: retry pending, the row stays active until the final attempt
     return;
   }
-  await upsertOnConflict(
-    db,
-    tenantJobRunsTable,
-    { ...key, bullJobId, status: result, finishedAt: now, updatedAt: now },
-    { conflictKeys: ["bullJobId"], update: { status: result, finishedAt: now, updatedAt: now } },
-  );
-  await deleteMany(db, tenantJobRunsTable, {
-    ...key,
-    status: { in: ["completed", "failed"] },
-    bullJobId: { ne: bullJobId },
+  // One transaction: a reader never sees the new finished row next to the
+  // one it replaces. The per-key lock keeps two runs of the same subject that
+  // finish together from each missing the other's uncommitted row and leaving
+  // both behind.
+  await transaction(db, async (tx) => {
+    await acquireNamespacedAdvisoryLock(
+      tx,
+      TENANT_JOB_RUN_LOCK_NAMESPACE,
+      JSON.stringify([key.tenantId, key.jobName, key.subject]),
+    );
+    await upsertOnConflict(
+      tx,
+      tenantJobRunsTable,
+      { ...key, bullJobId, status: result, finishedAt: now, updatedAt: now },
+      { conflictKeys: ["bullJobId"], update: { status: result, finishedAt: now, updatedAt: now } },
+    );
+    await deleteMany(tx, tenantJobRunsTable, {
+      ...key,
+      status: { in: ["completed", "failed"] },
+      bullJobId: { ne: bullJobId },
+    });
   });
 }
 

package/packages/bundled-features/src/renderer-pdf/README.md

@@ -0,0 +1,27 @@
+# renderer-pdf
+
+Public `document-pdf` renderer plugin: draws a table document as PDF in pure JavaScript (`pdf-lib`, standard Helvetica fonts), no browser and no Puppeteer service. Same input gives byte-identical output.
+
+## Pure function
+
+```typescript
+import { renderTablePdf } from "@cosmicdrift/kumiko-bundled-features/renderer-pdf";
+
+const { pdfBytes, pageCount } = await renderTablePdf(
+  {
+    title: "Prüfprotokoll",
+    meta: [{ label: "Anlage", value: "Kessel 3" }],
+    columns: [{ header: "Datum" }, { header: "Prüfer", weight: 2 }, { header: "Kosten", align: "right" }],
+    rows: [["03.02.2026", "Müller", "120,00 €"]],
+    footerText: "Kumiko GmbH",
+    pageLabel: "Seite {page} von {pages}",
+  },
+  { format: "A4" },
+);
+```
+
+The caller passes ready-formatted strings (dates, numbers); the renderer never reads the clock. Characters Helvetica (WinAnsi) cannot encode are drawn as `?`; umlauts, `ß` and `€` are kept.
+
+## Plugin
+
+Mount `createRendererPdfFeature()` next to `renderer-foundation`. It serves `kind: "document-pdf"` with a `PdfTableDocument` in `payload.variables`; `options.format` and `options.marginMm` apply. Invalid variables raise `RendererError("invalid_payload")`. A Puppeteer plugin keeps precedence (`DEFAULT_PLUGIN_BY_KIND`) when mounted.

package/packages/bundled-features/src/renderer-pdf/changes.json

@@ -0,0 +1,8 @@
+[
+  {
+    "version": "0.360.0",
+    "type": "improvement",
+    "title": "Pure-JS PDF renderer for table documents",
+    "detail": "renderTablePdf(doc, options?) renders a PdfTableDocument (title, subtitle, meta lines, weighted columns, wrapped cells, header row repeated per page, footerText and a pageLabel template with {page} and {pages}) to PDF bytes with pdf-lib. Characters outside WinAnsi are replaced by \"?\". Identical input yields identical bytes. createRendererPdfFeature() registers it as plugin \"pdf\" for kind \"document-pdf\"; payload.variables is validated against pdfTableDocumentSchema, anything else fails with RendererError invalid_payload."
+  }
+]

package/packages/bundled-features/src/renderer-pdf/feature.ts

@@ -0,0 +1,48 @@
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  RENDERER_EXTENSION,
+  RendererError,
+  type RenderRequest,
+  type RenderResponse,
+} from "../renderer-foundation/index.js";
+import { pdfTableDocumentSchema, renderTablePdf } from "./render-table-pdf.js";
+
+export async function renderTablePdfRequest(req: RenderRequest): Promise<RenderResponse> {
+  if (req.kind !== "document-pdf") {
+    throw new RendererError(
+      `renderer-pdf supports only kind="document-pdf", got "${req.kind}"`,
+      "invalid_payload",
+    );
+  }
+  const parsed = pdfTableDocumentSchema.safeParse(req.payload.variables);
+  if (!parsed.success) {
+    throw new RendererError(
+      `renderer-pdf: payload.variables is not a table document: ${parsed.error.message}`,
+      "invalid_payload",
+    );
+  }
+  const { pdfBytes, pageCount } = await renderTablePdf(parsed.data, {
+    ...(req.options?.format && { format: req.options.format }),
+    ...(req.options?.marginMm && { marginMm: req.options.marginMm }),
+  });
+  return { kind: "document-pdf", pdfBytes, pageCount, sizeBytes: pdfBytes.byteLength };
+}
+
+export function createRendererPdfFeature(): FeatureDefinition {
+  return defineFeature("renderer-pdf", (r) => {
+    r.describe(
+      'Renderer plugin for `kind="document-pdf"` that draws a table document (title, meta lines, weighted columns, repeating header, page footer) as a PDF in pure JavaScript, without a browser or Puppeteer service. `payload.variables` must be a `PdfTableDocument`. Requires `renderer-foundation`; mount a Puppeteer-based plugin instead when you need HTML/CSS layouts.',
+    );
+    r.uiHints({
+      displayLabel: "Renderer · PDF tables",
+      category: "notifications",
+      recommended: false,
+    });
+    r.requires("renderer-foundation");
+
+    r.useExtension(RENDERER_EXTENSION, "pdf", {
+      kinds: ["document-pdf"] as const,
+      render: (req) => renderTablePdfRequest(req),
+    });
+  });
+}

package/packages/bundled-features/src/renderer-pdf/index.ts

@@ -0,0 +1,9 @@
+export { createRendererPdfFeature } from "./feature.js";
+export {
+  type PdfTableColumn,
+  type PdfTableDocument,
+  type PdfTableOptions,
+  type PdfTableResult,
+  pdfTableDocumentSchema,
+  renderTablePdf,
+} from "./render-table-pdf.js";