@cosmicdrift/kumiko-bundled-features 0.48.1 → 0.51.0

package/src/config/resolver.ts

@@ -5,11 +5,13 @@ import type {
   ConfigCascadeLevel,
   ConfigKeyDefinition,
   ConfigResolver,
+  ConfigSecretsReader,
   ConfigStoredRowWithSource,
   ConfigValueSource,
   ConfigValueWithSource,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { assertUnreachable, parseJsonOrThrow } from "@cosmicdrift/kumiko-framework/utils";
 import { selectConfigRowsForKeys, selectConfigRowsForScope } from "./db/queries/resolver";
 import { configValuesTable } from "./table";
@@ -65,6 +67,26 @@ export type ConfigResolverOptions = {
   appOverrides?: AppConfigOverrides;
 };
 
+// backing="secrets" keys store their value in the secrets store (flat per
+// (tenant,key) at SYSTEM_TENANT_ID), not in config_values. Both read paths
+// (getWithSource + buildCascade) route the system rung here. Missing reader =
+// the app never wired extraContext.secrets → fail loud, never silently miss.
+async function readBackingSecret(
+  secretsReader: ConfigSecretsReader | undefined,
+  qualifiedKey: string,
+): Promise<string | undefined> {
+  if (!secretsReader) {
+    throw new InternalError({
+      message:
+        `[config] backing="secrets" key "${qualifiedKey}" was read without a secrets ` +
+        `reader — wire extraContext.secrets (and a MasterKeyProvider) so the secrets ` +
+        `store is reachable at request time.`,
+    });
+  }
+  const secret = await secretsReader.get(SYSTEM_TENANT_ID, qualifiedKey);
+  return secret?.reveal();
+}
+
 // Shared cascade-builder. Single-key path passes a `findRow`-bound row
 // fetcher (one SQL per lookup); batch path passes a closure over
 // pre-loaded rows. The builder itself is unaware of which.
@@ -80,6 +102,7 @@ async function buildCascade(
   ) => Promise<ConfigRow | null> | ConfigRow | null,
   appOverrides: AppConfigOverrides | undefined,
   encryption: EncryptionProvider | undefined,
+  secretsReader: ConfigSecretsReader | undefined,
 ): Promise<ConfigCascade> {
   type Lookup = {
     tenantId: string;
@@ -93,6 +116,12 @@ async function buildCascade(
     case "user":
       lookups.push({ tenantId, userId, source: "user-row", label: "User" });
       lookups.push({ tenantId, userId: null, source: "tenant-row", label: "Tenant" });
+      lookups.push({
+        tenantId: SYSTEM_TENANT_ID,
+        userId: null,
+        source: "system-row",
+        label: "System",
+      });
       break;
     case "tenant":
       lookups.push({ tenantId, userId: null, source: "tenant-row", label: "Tenant" });
@@ -119,6 +148,34 @@ async function buildCascade(
   let activeIndex = -1;
 
   for (const lookup of lookups) {
+    // backing="secrets" is system-only (boot-guard), so the single system-row
+    // rung reads from the secrets store instead of config_values. The secret
+    // value is the same JSON-serialized form a config row would hold (set.write
+    // serializes before handing it to secrets), so deserializeValue applies;
+    // no config-level decrypt — the secrets envelope already returned plaintext.
+    if (keyDef.backing === "secrets" && lookup.source === "system-row") {
+      const secret = await readBackingSecret(secretsReader, qualifiedKey);
+      if (secret !== undefined) {
+        if (activeIndex === -1) activeIndex = levels.length;
+        levels.push({
+          label: lookup.label,
+          value: deserializeValue(secret, keyDef.type),
+          source: lookup.source,
+          isActive: false,
+          hasValue: true,
+        });
+      } else {
+        levels.push({
+          label: lookup.label,
+          value: undefined,
+          source: lookup.source,
+          isActive: false,
+          hasValue: false,
+        });
+      }
+      continue;
+    }
+
     const row = await fetchRow(lookup.tenantId, lookup.userId);
     if (row?.value !== null && row?.value !== undefined) {
       let raw = row.value;
@@ -225,10 +282,17 @@ export function createConfigResolver(options: ConfigResolverOptions = {}): Confi
   }
 
   return {
-    async get(qualifiedKey, keyDef, tenantId, userId, db) {
+    async get(qualifiedKey, keyDef, tenantId, userId, db, secretsReader) {
       // get() is a thin wrapper around getWithSource that discards the
       // source tag. Keeps the hot-path a single implementation.
-      const result = await this.getWithSource(qualifiedKey, keyDef, tenantId, userId, db);
+      const result = await this.getWithSource(
+        qualifiedKey,
+        keyDef,
+        tenantId,
+        userId,
+        db,
+        secretsReader,
+      );
       return result.value;
     },
 
@@ -238,9 +302,31 @@ export function createConfigResolver(options: ConfigResolverOptions = {}): Confi
       tenantId,
       userId,
       db,
+      secretsReader,
     ): Promise<ConfigValueWithSource> {
+      // backing="secrets": the value lives in the secrets store at the system
+      // tenant, not config_values. Read it directly (system-only by boot-guard)
+      // and skip the config-row lookups; app-override/computed/default still
+      // form the fallback ladder when the secret is unset.
+      if (keyDef.backing === "secrets") {
+        const secret = await readBackingSecret(secretsReader, qualifiedKey);
+        if (secret !== undefined) {
+          return { value: deserializeValue(secret, keyDef.type), source: "system-row" };
+        }
+        if (appOverrides?.has(qualifiedKey)) {
+          return { value: appOverrides.get(qualifiedKey), source: "app-override" };
+        }
+        if (keyDef.computed) {
+          const value = await keyDef.computed({ tenantId, userId, db });
+          return { value, source: "computed" };
+        }
+        if (keyDef.default !== undefined) {
+          return { value: keyDef.default, source: "default" };
+        }
+        return { value: undefined, source: "missing" };
+      }
       // Resolution cascade based on scope
-      // user:   userId+tenantId → tenantId → default
+      // user:   userId+tenantId → tenantId → SYSTEM_TENANT_ID → default
       // tenant: tenantId → SYSTEM_TENANT_ID → default
       // system: SYSTEM_TENANT_ID → default
       const lookups: Array<{
@@ -253,6 +339,7 @@ export function createConfigResolver(options: ConfigResolverOptions = {}): Confi
         case "user":
           lookups.push({ tenantId, userId, source: "user-row" });
           lookups.push({ tenantId, userId: null, source: "tenant-row" });
+          lookups.push({ tenantId: SYSTEM_TENANT_ID, userId: null, source: "system-row" });
           break;
         case "tenant":
           lookups.push({ tenantId, userId: null, source: "tenant-row" });
@@ -359,7 +446,14 @@ export function createConfigResolver(options: ConfigResolverOptions = {}): Confi
       return result;
     },
 
-    async getCascade(qualifiedKey, keyDef, tenantId, userId, db): Promise<ConfigCascade> {
+    async getCascade(
+      qualifiedKey,
+      keyDef,
+      tenantId,
+      userId,
+      db,
+      secretsReader,
+    ): Promise<ConfigCascade> {
       // Single-key path uses findRow per cascade step. The batch path
       // bulk-loads all rows up-front; both build identical levels arrays.
       return buildCascade(
@@ -371,6 +465,7 @@ export function createConfigResolver(options: ConfigResolverOptions = {}): Confi
         (tid, uid) => findRow(qualifiedKey, tid, uid, db),
         appOverrides,
         encryption,
+        secretsReader,
       );
     },
 
@@ -380,6 +475,7 @@ export function createConfigResolver(options: ConfigResolverOptions = {}): Confi
       tenantId,
       userId,
       db,
+      secretsReader,
     ): Promise<ReadonlyMap<string, ConfigCascade>> {
       if (keys.length === 0) return new Map();
 
@@ -411,6 +507,7 @@ export function createConfigResolver(options: ConfigResolverOptions = {}): Confi
             keyRows.find((r) => r.tenantId === tid && (r.userId ?? null) === uid) ?? null,
           appOverrides,
           encryption,
+          secretsReader,
         );
         result.set(key, cascade);
       }
@@ -505,3 +602,65 @@ export function validateAppOverrides(
 
   return validated;
 }
+
+// --- ENV → App-Override Bridge ---
+//
+// Realises the `env` field of a config key: at boot every config
+// key that declares `env` reads its value from the process environment and
+// injects it as an app-override default (the cascade rung between the
+// tenant/system rows and the declared default). String env values are coerced
+// to the key's type; a mismatch fails the boot loudly rather than silently
+// resolving to the wrong value. Reuses validateAppOverrides for the
+// existence / bounds / options / computed-conflict gates.
+//
+// undefined OR empty-string env vars are skipped — an unset (or `FOO=`)
+// variable must not clobber a declared default.
+
+type EnvSource = Readonly<Record<string, string | undefined>>;
+
+type ConfigKeyRegistry = {
+  getAllConfigKeys: () => ReadonlyMap<string, ConfigKeyDefinition>;
+  getConfigKey: (key: string) => ConfigKeyDefinition | undefined;
+};
+
+function coerceEnvValue(
+  qualifiedKey: string,
+  envName: string,
+  type: ConfigKeyDefinition["type"],
+  raw: string,
+): string | number | boolean {
+  if (type === "number") {
+    const n = Number(raw.trim());
+    if (!Number.isFinite(n)) {
+      throw new Error(
+        `ENV config bridge: "${envName}" → "${qualifiedKey}" expects a number, got "${raw}".`,
+      );
+    }
+    return n;
+  }
+  if (type === "boolean") {
+    const v = raw.trim().toLowerCase();
+    if (v === "true" || v === "1") return true;
+    if (v === "false" || v === "0") return false;
+    throw new Error(
+      `ENV config bridge: "${envName}" → "${qualifiedKey}" expects a boolean (true/false/1/0), got "${raw}".`,
+    );
+  }
+  // text | select — select-option membership is validated by validateAppOverrides
+  return raw;
+}
+
+export function buildEnvConfigOverrides(
+  registry: ConfigKeyRegistry,
+  env: EnvSource,
+): AppConfigOverrides {
+  const record: Record<string, string | number | boolean> = {};
+  for (const [qualifiedKey, keyDef] of registry.getAllConfigKeys()) {
+    const envName = keyDef.env;
+    if (!envName) continue;
+    const raw = env[envName];
+    if (raw === undefined || raw === "") continue;
+    record[qualifiedKey] = coerceEnvValue(qualifiedKey, envName, keyDef.type, raw);
+  }
+  return validateAppOverrides(registry, record);
+}

package/src/config/web/client-plugin.ts

@@ -0,0 +1,24 @@
+// @runtime client
+import { mergeTranslations, type TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+import { CONFIG_FEATURE } from "../constants";
+import { defaultTranslations } from "./i18n";
+
+export type ConfigClientOptions = {
+  /** Key-wise overrides over the default bundles (de/en). */
+  readonly translations?: TranslationsByLocale;
+};
+
+export type ConfigClientFeature = {
+  readonly name: typeof CONFIG_FEATURE;
+  readonly translations: TranslationsByLocale;
+};
+
+// Ships the generic Settings-Hub labels (config.settings.*). Mount it in
+// clientFeatures next to the app's own feature client — without it the
+// audience groups render their raw i18n keys.
+export function configClient(options?: ConfigClientOptions): ConfigClientFeature {
+  return {
+    name: CONFIG_FEATURE,
+    translations: mergeTranslations(defaultTranslations, options?.translations ?? {}),
+  };
+}

package/src/config/web/i18n.ts

@@ -0,0 +1,25 @@
+// @runtime client
+// Default labels for the auto-generated Settings-Hub. The generator
+// (buildConfigFeatureSchema) emits `config.settings.<scope>` for the audience
+// groups and `config.settings.title` for the synthetic workspace — generic
+// across every app, so they ship here. configClient() hangs them into the
+// LocaleProvider as a fallback; an app overrides individual keys via
+// configClient({ translations: { de: { ... } } }). The app only adds labels
+// for ITS keys (mask.title) and the per-feature group key `<feature>.settings`.
+
+import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+
+export const defaultTranslations: TranslationsByLocale = {
+  de: {
+    "config.settings.title": "Einstellungen",
+    "config.settings.system": "Plattform",
+    "config.settings.tenant": "Organisation",
+    "config.settings.user": "Persönlich",
+  },
+  en: {
+    "config.settings.title": "Settings",
+    "config.settings.system": "Platform",
+    "config.settings.tenant": "Organization",
+    "config.settings.user": "Personal",
+  },
+};

package/src/config/web/index.ts

@@ -0,0 +1,3 @@
+// @runtime client
+export { type ConfigClientFeature, type ConfigClientOptions, configClient } from "./client-plugin";
+export { defaultTranslations } from "./i18n";

package/src/config/write-helpers.ts

@@ -16,6 +16,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import {
   AccessDeniedError,
+  InternalError,
   type KumikoError,
   NotFoundError,
   UnprocessableError,
@@ -262,3 +263,39 @@ export function validateBounds(
 
   return null;
 }
+
+// Regex enforcement for text config keys (keyDef.pattern). Hard-reject on
+// mismatch (same posture as validateBounds — never silent-coerce). The value
+// is tenant-supplied, so this is the write-side gate behind the configEdit
+// screen (which dispatches config:write:set per key). A malformed author-
+// supplied regex is surfaced as an InternalError instead of throwing
+// unhandled in the write path.
+export function validatePattern(
+  value: string | number | boolean,
+  keyDef: ConfigKeyDefinition,
+): KumikoError | null {
+  if (keyDef.type !== "text" || !keyDef.pattern) return null;
+  // skip: validateType runs first and guarantees a string for type==="text"
+  if (typeof value !== "string") return null;
+
+  let re: RegExp;
+  try {
+    re = new RegExp(keyDef.pattern.regex, keyDef.pattern.flags);
+  } catch {
+    return new InternalError({
+      message: `config key pattern is not a valid RegExp: ${keyDef.pattern.regex}`,
+    });
+  }
+  if (re.test(value)) return null;
+
+  return new ValidationError({
+    fields: [
+      {
+        path: "value",
+        code: "invalid_format",
+        i18nKey: "errors.validation.invalid_format",
+        params: { value, pattern: keyDef.pattern.regex },
+      },
+    ],
+  });
+}

package/src/custom-fields/aggregate-id.ts

@@ -24,6 +24,7 @@ const FIELD_DEFINITION_NAMESPACE = "f1d3b2c7-4e5a-4b9c-8d1f-2a3b4c5d6e7f";
  *   definieren (422 `fieldKey_conflict`). Verhindert Resolution-Ambiguität
  *   beim Read.
  */
+// @wrapper-known uuid-domain
 export function fieldDefinitionAggregateId(
   tenantId: string,
   entityName: string,

package/src/custom-fields/wire-for-entity.ts

@@ -29,6 +29,7 @@ import { customFieldsFeature } from "./feature";
 //
 // Spec-Promise: customFields verhält sich wie Stammfelder. Default `{}`,
 // NOT NULL — analog zu embedded-Spalten.
+// @wrapper-known semantic-alias
 export function customFieldsField(): JsonbFieldDef {
   return createJsonbField();
 }

package/src/delivery/upsert-preference.ts

@@ -27,6 +27,7 @@ const executor = createEventStoreExecutor(
 // im Helper (db-row-boundary), nicht 4× pro Callsite.
 type PreferenceLookupRow = { readonly id: string; readonly version: number };
 
+// @wrapper-known semantic-alias
 async function lookup(
   db: TenantDb,
   tenantId: TenantId,

package/src/file-provider-inmemory/feature.ts

@@ -73,7 +73,7 @@ export const fileProviderInMemoryFeature = defineFeature(FEATURE_NAME, (r) => {
       // Returnt den per-tenant Storage. Identitätsstabil zwischen calls
       // damit accumulated state erhalten bleibt.
       return getOrCreateProviderForTenant(tenantId);
-    },
+    }, // @wrapper-known semantic-alias
   };
   r.useExtension("fileProvider", "inmemory", plugin);
 });

package/src/file-provider-s3/feature.ts

@@ -97,7 +97,7 @@ export const fileProviderS3Feature = defineFeature(FEATURE_NAME, (r) => {
   // Plugin-Registration. entityName "s3" ist was tenants in
   // file-foundation's `provider` config-key setzen.
   const plugin: FileProviderPlugin = {
-    build: async (ctx: FileProviderContext, tenantId: string) => buildS3Provider(ctx, tenantId),
+    build: async (ctx: FileProviderContext, tenantId: string) => buildS3Provider(ctx, tenantId), // @wrapper-known semantic-alias
   };
   r.useExtension("fileProvider", "s3", plugin);
 

package/src/jobs/__tests__/projection-rebuild-job.integration.test.ts

@@ -0,0 +1,162 @@
+// #362: das `jobs`-Feature registriert den framework-eigenen Single-Run-Job
+// `jobs:job:projection-rebuild`. Sobald jobs komponiert ist, dispatcht
+// `enqueueProjectionRebuild` einen getrackten, retrybaren Rebuild über BullMQ;
+// der Worker ruft `rebuildProjection`. Ohne jobs fällt der Helper auf einen
+// inline-Rebuild zurück (in migrations/__tests__/pending-rebuilds.* abgedeckt).
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import {
+  asRawClient,
+  buildEntityTable,
+  createEventStoreExecutor,
+  createTenantDb,
+  type DbConnection,
+  integer,
+  table as pgTable,
+  selectMany,
+  type TenantDb,
+  uuid,
+} from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntity,
+  createRegistry,
+  createTextField,
+  defineApply,
+  defineFeature,
+  type ProjectionDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { createJobRunner, type JobRunner } from "@cosmicdrift/kumiko-framework/jobs";
+import {
+  enqueueProjectionRebuild,
+  PROJECTION_REBUILD_JOB,
+} from "@cosmicdrift/kumiko-framework/migrations";
+import { createProjectionStateTable } from "@cosmicdrift/kumiko-framework/pipeline";
+import {
+  createTestDb,
+  createTestRedis,
+  type TestDb,
+  type TestRedis,
+  TestUsers,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { sleep } from "@cosmicdrift/kumiko-framework/testing";
+import { createJobsFeature } from "../feature";
+import { createJobRunLogger } from "../job-run-logger";
+import { jobRunLogsTable, jobRunsTable } from "../job-run-table";
+
+const itemEntity = createEntity({
+  table: "read_rebuild_items",
+  fields: {
+    groupId: createTextField({ required: true }),
+    name: createTextField({ required: true }),
+  },
+});
+const itemTable = buildEntityTable("rebuild-item", itemEntity);
+const executor = createEventStoreExecutor(itemTable, itemEntity, { entityName: "rebuild-item" });
+
+const countsTable = pgTable("read_rebuild_counts", {
+  groupId: uuid("group_id").primaryKey(),
+  tenantId: uuid("tenant_id").notNull(),
+  itemCount: integer("item_count").notNull().default(0),
+});
+
+// Eigene (explizite) Projektion — der Executor füllt sie NICHT live, sie wird
+// ausschließlich vom Rebuild materialisiert. Count==2 nach dem Job beweist also
+// den Replay, nicht den Live-Write.
+const countsProjection: ProjectionDefinition = {
+  name: "rebuild-counts",
+  source: "rebuild-item",
+  table: countsTable,
+  apply: {
+    "rebuild-item.created": defineApply<{ groupId: string }>(async (event, tx) => {
+      await asRawClient(tx).unsafe(
+        `INSERT INTO "read_rebuild_counts" (group_id, tenant_id, item_count) VALUES ($1::uuid, $2::uuid, 1)
+         ON CONFLICT (group_id) DO UPDATE SET item_count = read_rebuild_counts.item_count + 1`,
+        [event.payload.groupId, event.tenantId],
+      );
+    }),
+  },
+};
+
+const PROJECTION = "rebuildtest:projection:rebuild-counts";
+const GROUP = "00000000-0000-4000-8000-000000000001";
+
+const appFeature = defineFeature("rebuildtest", (r) => {
+  r.entity("rebuild-item", itemEntity);
+  r.projection(countsProjection);
+});
+
+const admin = TestUsers.admin;
+const registry = createRegistry([appFeature, createJobsFeature()]);
+
+let testDb: TestDb;
+let testRedis: TestRedis;
+let db: DbConnection;
+let tdb: TenantDb;
+let jobRunner: JobRunner;
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  testRedis = await createTestRedis();
+  db = testDb.db;
+
+  await unsafeCreateEntityTable(db, itemEntity, "rebuild-item");
+  await createEventsTable(db);
+  await createProjectionStateTable(db);
+  await unsafePushTables(db, { readRebuildCounts: countsTable, jobRunsTable, jobRunLogsTable });
+  tdb = createTenantDb(db, admin.tenantId);
+
+  const redisUrl = `redis://${testRedis.redis.options.host}:${testRedis.redis.options.port}/${testRedis.redis.options.db}`;
+  const logger = createJobRunLogger({ db, registry });
+  jobRunner = createJobRunner({
+    registry,
+    context: { db },
+    redisUrl,
+    consumerLane: "worker",
+    queueNamePrefix: `kumiko-projrebuild-test-${Date.now()}`,
+    ...logger,
+  });
+  await jobRunner.start();
+});
+
+afterAll(async () => {
+  await jobRunner.stop();
+  await testDb.cleanup();
+  await testRedis.cleanup();
+});
+
+async function getCount(): Promise<number | undefined> {
+  const [row] = await selectMany<{ itemCount: number }>(db, countsTable, { groupId: GROUP });
+  return row?.itemCount;
+}
+
+describe("projection-rebuild job (jobs feature composed)", () => {
+  test("jobs feature registers the framework rebuild job under its qualified name", () => {
+    expect(registry.getJob(PROJECTION_REBUILD_JOB)).toBeDefined();
+  });
+
+  test("enqueueProjectionRebuild dispatches a tracked job that refills the projection", async () => {
+    await executor.create({ groupId: GROUP, name: "a" }, admin, tdb);
+    await executor.create({ groupId: GROUP, name: "b" }, admin, tdb);
+    // Live executor füllt die explizite Projektion nicht — Rebuild ist der einzige Weg.
+    expect(await getCount()).toBeUndefined();
+
+    const outcome = await enqueueProjectionRebuild(PROJECTION, { db, registry, jobRunner });
+    expect(outcome.mode).toBe("dispatched");
+    if (outcome.mode === "dispatched") {
+      expect(outcome.bullJobId).toBeTruthy();
+    }
+
+    // Poll until the worker drained the queue and the rebuild refilled.
+    for (let i = 0; i < 40 && (await getCount()) !== 2; i++) await sleep(200);
+    expect(await getCount()).toBe(2);
+
+    const runs = await selectMany<{ jobName: string; status: string }>(db, jobRunsTable, {
+      jobName: PROJECTION_REBUILD_JOB,
+    });
+    expect(runs.length).toBeGreaterThanOrEqual(1);
+    expect(runs.some((r) => r.status === "completed")).toBe(true);
+  }, 30000);
+});

package/src/jobs/feature.ts

@@ -12,6 +12,10 @@ import type { z } from "zod";
 import { runCompletedSchema, runFailedSchema, runStartedSchema } from "./events";
 import { detailQuery } from "./handlers/detail.query";
 import { listQuery } from "./handlers/list.query";
+import {
+  projectionRebuildJob,
+  projectionRebuildPayloadSchema,
+} from "./handlers/projection-rebuild.job";
 import { retryWrite } from "./handlers/retry.write";
 import { triggerWrite } from "./handlers/trigger.write";
 import {
@@ -149,6 +153,15 @@ export function createJobsFeature(): FeatureDefinition {
       },
     });
 
+    // Framework-provided single-run rebuild job (QN `jobs:job:projection-rebuild`).
+    // Available whenever `jobs` is composed — `enqueueProjectionRebuild` dispatches
+    // it; every run is tracked in read_job_runs + retryable via jobs:write:retry.
+    r.job(
+      "projectionRebuild",
+      { trigger: { manual: true }, schema: projectionRebuildPayloadSchema },
+      projectionRebuildJob,
+    );
+
     const handlers = {
       trigger: r.writeHandler(triggerWrite),
       retry: r.writeHandler(retryWrite),

package/src/jobs/handlers/projection-rebuild.job.ts

@@ -0,0 +1,36 @@
+// Single-run projection-rebuild worker (QN `jobs:job:projection-rebuild`).
+// Replays the event log into one projection via the framework's
+// `rebuildProjection`. Triggered manually — typically through
+// `enqueueProjectionRebuild` (migrations) as the self-service repair for an
+// emptied projection, a deliberate manual rebuild, or a post-upcaster refill.
+// Run-tracking (read_job_runs + read_job_run_logs) and retry come for free
+// from the jobs feature that registers this worker.
+
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { JobHandlerFn } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { rebuildProjection } from "@cosmicdrift/kumiko-framework/pipeline";
+import { z } from "zod";
+
+export const projectionRebuildPayloadSchema = z.object({ projection: z.string().min(1) });
+
+export const projectionRebuildJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> => {
+  const { projection } = projectionRebuildPayloadSchema.parse(rawPayload);
+  if (!ctx.db) {
+    throw new InternalError({
+      message:
+        "[jobs:projection-rebuild] ctx.db missing — job context requires a database connection.",
+    });
+  }
+  if (!ctx.registry) {
+    throw new InternalError({
+      message:
+        "[jobs:projection-rebuild] ctx.registry missing — job context requires the registry.",
+    });
+  }
+  const db = ctx.db as DbConnection; // @cast-boundary db-operator
+  const result = await rebuildProjection(projection, { db, registry: ctx.registry });
+  ctx.log?.info?.(
+    `[jobs:projection-rebuild] rebuilt ${projection}: ${result.eventsProcessed} events in ${result.durationMs}ms`,
+  );
+};

package/src/legal-pages/README.md

@@ -156,19 +156,22 @@ datenschutz-generator.de).
 
 ---
 
-## XSS — currently not secured by design
-
-`marked` renders HTML tags 1:1, so a malicious tenant admin could in
-theory put `<script>` into the body.
-
-Currently accepted because:
-- only `roles: ["TenantAdmin"]` may set texts
-- multi-author setups don't exist yet
-- self-hosted tier without unknown tenant admins
-
-**Phase-2 hardening:** `DOMPurify` or `isomorphic-dompurify`
-sanitization step between `marked.parse()` and the response.
-Documented when a customer with a multi-author setup shows up.
+## XSS hardening (untrusted authors)
+
+The server-render path is hardened for untrusted tenant authors —
+no DOMPurify dependency needed:
+
+- **Raw HTML is escaped, not passed through.** `renderMarkdownToHtml`
+  (`markdown.ts`) configures `marked` so block- and inline-level HTML
+  tokens are emitted as escaped text (`<script>` → `&lt;script&gt;`).
+  Markdown structure (headings, lists, links, code) stays intact.
+- **Link/image hrefs are scheme-restricted** to `http(s)`/`mailto`/
+  relative; `javascript:`/`data:` hrefs are neutralised to `#`.
+- **Defense-in-depth headers** on every response (`security-headers.ts`):
+  `content-security-policy: script-src 'none'; object-src 'none';
+  base-uri 'none'` (no script can run even if injection slips through),
+  plus `x-content-type-options`, `x-frame-options`, `referrer-policy`.
+  No `default-src`, so inline `<style>` layouts stay unaffected.
 
 ---