@cosmicdrift/kumiko-samples 0.342.0 → 0.344.0

package/packages/bundled-features/src/renderer-simple/simple-renderer.ts

@@ -1,5 +1,6 @@
 import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
 import type { NotificationRenderer } from "../delivery/index.js";
+import { renderSafeMarkdown } from "../page-render/index.js";
 
 export type MailBranding = {
   /** Shown as text when there is no logo, and as the logo alt text. */
@@ -141,6 +142,8 @@ function renderBrandingFooter(
 
 type Section =
   | { readonly text: string }
+  | { readonly heading: string }
+  | { readonly markdown: string }
   | { readonly button: { readonly label: string; readonly url: string } };
 
 type EmailTemplateData = {
@@ -157,6 +160,13 @@ function renderSection(section: Section, primaryColor: string): string {
   if ("text" in section) {
     return `<p style="margin:0 0 16px;color:#333;font-size:14px;line-height:1.5">${escapeHtml(section.text)}</p>`;
   }
+  if ("heading" in section) {
+    return `<h2 style="margin:24px 0 12px;color:#111;font-size:16px;font-weight:600">${escapeHtml(section.heading)}</h2>`;
+  }
+  if ("markdown" in section) {
+    const markdownHtml = renderSafeMarkdown(section.markdown);
+    return `<div style="color:#333;font-size:14px;line-height:1.5">${markdownHtml}</div>`;
+  }
   if ("button" in section) {
     return `<p style="margin:0 0 16px"><a href="${escapeHtml(section.button.url)}" style="display:inline-block;padding:10px 24px;background:${escapeHtmlAttr(primaryColor)};color:#fff;text-decoration:none;border-radius:4px;font-size:14px">${escapeHtml(section.button.label)}</a></p>`;
   }

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

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.343.0",
+    "type": "improvement",
+    "title": "Recognise the invalid-secret-value error",
+    "detail": "`secrets` exports `isInvalidSecretValueError`, which recognises the validation error that `secrets:write:set` and `ctx.secrets.set` raise when a value fails the key's `valueSchema`. It also exports `SECRETS_ERROR_KEYS` (the i18n keys of the secrets write errors) and `INVALID_SECRET_VALUE_CODE` (the field error code), so callers can map the failure to their own message instead of matching strings."
+  },
   {
     "version": "0.341.0",
     "type": "improvement",

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

@@ -10,3 +10,13 @@ import type { AccessRule } from "@cosmicdrift/kumiko-framework/engine";
 // design, not a per-tenant RBAC surface.
 export const DEFAULT_SECRETS_ROLES = ["TenantAdmin"] as const;
 export const DEFAULT_SECRETS_ACCESS: AccessRule = { roles: DEFAULT_SECRETS_ROLES };
+
+// Error i18n keys of the secrets write path. Shared by the write gate, the
+// bundled translations and callers that need to recognise a specific failure.
+export const SECRETS_ERROR_KEYS = {
+  unknownKey: "secrets.errors.unknownKey",
+  writeDenied: "secrets.errors.writeDenied",
+  invalidValue: "secrets.errors.invalidValue",
+} as const;
+
+export const INVALID_SECRET_VALUE_CODE = "invalid_secret_value" as const;

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

@@ -32,6 +32,10 @@ const ROTATE_ESCAPE_HATCH_REASON = "re-encrypts every tenant's secrets with the
  */
 export const SECRETS_FEATURE_NAME = "secrets";
 
+/** Env keys that carry the KEK keyring. Optional when the app supplies its own
+ *  `masterKey` provider. */
+export const SECRETS_MASTER_KEK_ENV_KEYS = ["KUMIKO_SECRETS_MASTER_KEY_V1"] as const;
+
 export const secretsEnvSchema = z.object({
   KUMIKO_SECRETS_MASTER_KEY_V1: z
     .string()

package/packages/bundled-features/src/secrets/i18n.ts

@@ -1,13 +1,15 @@
+import { SECRETS_ERROR_KEYS } from "./constants.js";
+
 export const SECRETS_I18N = {
-  "secrets.errors.unknownKey": {
+  [SECRETS_ERROR_KEYS.unknownKey]: {
     en: "Unknown secret key.",
     de: "Unbekannter Geheimnis-Schlüssel.",
   },
-  "secrets.errors.writeDenied": {
+  [SECRETS_ERROR_KEYS.writeDenied]: {
     en: "You are not allowed to change this secret.",
     de: "Dieses Geheimnis darf nicht geändert werden.",
   },
-  "secrets.errors.invalidValue": {
+  [SECRETS_ERROR_KEYS.invalidValue]: {
     en: "This value is not valid for this secret.",
     de: "Dieser Wert ist für dieses Geheimnis nicht gültig.",
   },

package/packages/bundled-features/src/secrets/index.ts

@@ -1,9 +1,15 @@
-export { DEFAULT_SECRETS_ACCESS, DEFAULT_SECRETS_ROLES } from "./constants.js";
+export {
+  DEFAULT_SECRETS_ACCESS,
+  DEFAULT_SECRETS_ROLES,
+  INVALID_SECRET_VALUE_CODE,
+  SECRETS_ERROR_KEYS,
+} from "./constants.js";
 export {
   createSecretsContext,
   createSecretsFeature,
   requireSecretsContext,
   SECRETS_FEATURE_NAME,
+  SECRETS_MASTER_KEK_ENV_KEYS,
   type SecretsContext,
   type SecretsContextOptions,
   type SecretsFeatureOptions,
@@ -21,3 +27,4 @@ export {
   rotateJob,
 } from "./handlers/rotate.job.js";
 export { createSetHandler } from "./handlers/set.write.js";
+export { isInvalidSecretValueError } from "./write-gate.js";

package/packages/bundled-features/src/secrets/write-gate.ts

@@ -5,11 +5,13 @@ import type {
 } from "@cosmicdrift/kumiko-framework/engine";
 import {
   AccessDeniedError,
+  isKumikoError,
   NotFoundError,
   ValidationError,
   type WriteFailure,
   writeFailure,
 } from "@cosmicdrift/kumiko-framework/errors";
+import { INVALID_SECRET_VALUE_CODE, SECRETS_ERROR_KEYS } from "./constants.js";
 
 // Fixed keys carry their definition (redact fn, writeRoles); namespace keys
 // only the namespace, which has no redact fn.
@@ -21,7 +23,7 @@ function unknownKeyFailure(key: string): SecretKeyWriteCheck {
   return {
     ok: false,
     failure: writeFailure(
-      new NotFoundError("secretKey", key, { i18nKey: "secrets.errors.unknownKey" }),
+      new NotFoundError("secretKey", key, { i18nKey: SECRETS_ERROR_KEYS.unknownKey }),
     ),
   };
 }
@@ -53,7 +55,7 @@ export function checkSecretKeyWrite(
       failure: writeFailure(
         new AccessDeniedError({
           message: "secret write access denied",
-          i18nKey: "secrets.errors.writeDenied",
+          i18nKey: SECRETS_ERROR_KEYS.writeDenied,
           details: { requiredRoles: writeRoles },
         }),
       ),
@@ -72,12 +74,22 @@ export function invalidSecretValueError(): ValidationError {
       fields: [
         {
           path: "value",
-          code: "invalid_secret_value",
-          i18nKey: "secrets.errors.invalidValue",
+          code: INVALID_SECRET_VALUE_CODE,
+          i18nKey: SECRETS_ERROR_KEYS.invalidValue,
         },
       ],
     },
-    { i18nKey: "secrets.errors.invalidValue" },
+    { i18nKey: SECRETS_ERROR_KEYS.invalidValue },
+  );
+}
+
+// Matches on the i18n key and error code rather than instanceof, which is fragile
+// when the error crosses a package boundary with a duplicated framework copy.
+export function isInvalidSecretValueError(err: unknown): err is ValidationError {
+  return (
+    isKumikoError(err) &&
+    err.code === "validation_error" &&
+    err.i18nKey === SECRETS_ERROR_KEYS.invalidValue
   );
 }
 

package/packages/bundled-features/src/shared/index.ts

@@ -25,6 +25,12 @@ export {
   parentRowIsVisible,
 } from "./parent-visibility.js";
 export { hashPassword, verifyDummyPassword, verifyPassword } from "./password-hashing.js";
+export {
+  redactBotTokens,
+  redactEmailAddresses,
+  redactErrorText,
+  redactUrls,
+} from "./redact.js";
 export {
   type RowBoundGrantResult,
   redeemRowBoundGrant,

package/packages/bundled-features/src/shared/redact.ts

@@ -0,0 +1,27 @@
+// Adapter errors usually quote the rejected recipient ("550 <ops@example.com> rejected"); the
+// address must not outlive the crypto-shredded dispatch payload in logs.
+export function redactEmailAddresses(text: string): string {
+  return text.replace(/[^\s<>,;"']+@[^\s<>,;"']+/g, "[redacted-address]");
+}
+
+// Provider URLs carry secrets in the path (Slack hook, Telegram bot token), the query or
+// the userinfo. The origin stays so the log still says which host failed. Any scheme
+// counts: smtp://user:pass@host carries credentials just like https.
+export function redactUrls(text: string): string {
+  return text.replace(
+    /([a-z][a-z0-9+.-]*:\/\/)([^\s/?#<>"']*)([^\s<>"']*)/gi,
+    (_match, scheme: string, authority: string, rest: string) => {
+      const host = authority.slice(authority.lastIndexOf("@") + 1);
+      return rest.length > 0 && rest !== "/" ? `${scheme}${host}/[redacted]` : `${scheme}${host}`;
+    },
+  );
+}
+
+// Telegram-style bot tokens outside a URL ("<digits>:<35 chars>"). Times like 12:30 are too short to match.
+export function redactBotTokens(text: string): string {
+  return text.replace(/\b\d{6,}:[A-Za-z0-9_-]{30,}\b/g, "[redacted-token]");
+}
+
+export function redactErrorText(text: string): string {
+  return redactBotTokens(redactEmailAddresses(redactUrls(text)));
+}

package/packages/bundled-features/src/step-dispatcher/feature.ts

@@ -25,12 +25,8 @@ import {
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import { SYSTEM_USER_ID } from "@cosmicdrift/kumiko-types/identifiers";
 import * as z from "zod";
-import {
-  type MailSpec,
-  mailSpecSchema,
-  performMailDispatch,
-  redactEmailAddresses,
-} from "./mail-runner.js";
+import { redactEmailAddresses } from "../shared/index.js";
+import { type MailSpec, mailSpecSchema, performMailDispatch } from "./mail-runner.js";
 import {
   performWebhookDispatch,
   WEBHOOK_ALLOWED_PRIVATE_HOSTS_ENV_VAR,

package/packages/bundled-features/src/step-dispatcher/mail-runner.ts

@@ -31,9 +31,3 @@ export function setMailRunner(fn: (spec: MailSpec) => Promise<MailDispatchResult
 export async function performMailDispatch(spec: MailSpec): Promise<MailDispatchResult> {
   return mailRunner(spec);
 }
-
-// Adapter errors usually quote the rejected recipient ("550 <ops@example.com> rejected"); the
-// address must not outlive the crypto-shredded dispatch payload in logs.
-export function redactEmailAddresses(text: string): string {
-  return text.replace(/[^\s<>,;"']+@[^\s<>,;"']+/g, "[redacted-address]");
-}

package/packages/bundled-features/src/tenant/web/member-roles-cell.tsx

@@ -5,7 +5,7 @@
 
 import { type ColumnRendererProps, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import type { ReactNode } from "react";
-import { translateOrRaw } from "./translate-or-raw.js";
+import { translateOrRaw } from "../../shared/web/translate-or-raw.js";
 
 export function MemberRolesCell({ row }: ColumnRendererProps): ReactNode {
   const t = useTranslation();

package/packages/bundled-features/src/tenant/web/member-status-cell.tsx

@@ -7,7 +7,7 @@
 import { type ColumnRendererProps, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import { StatusBadge, type StatusTone } from "@cosmicdrift/kumiko-renderer-web";
 import type { ReactNode } from "react";
-import { translateOrRaw } from "./translate-or-raw.js";
+import { translateOrRaw } from "../../shared/web/translate-or-raw.js";
 
 const STATUS_TONE: Readonly<Record<string, StatusTone>> = {
   active: "ok",

package/packages/bundled-features/src/tenant-lifecycle/feature.ts

@@ -34,7 +34,11 @@ import {
 } from "./events.js";
 import { cancelDestructionWrite } from "./handlers/cancel-destruction.write.js";
 import { requestDestructionWrite } from "./handlers/request-destruction.write.js";
-import { resolveTenantLifecycleGate, runTenantDestructionSweep } from "./run-tenant-destroy.js";
+import {
+  hasTenantDestructionWork,
+  resolveTenantLifecycleGate,
+  runTenantDestructionSweep,
+} from "./run-tenant-destroy.js";
 
 const tenantLifecycleStatusPlugin: TenantLifecycleStatusPlugin = {
   async resolveStatus(tenantId, { db }) {
@@ -125,10 +129,16 @@ export function createTenantLifecycleFeature(): FeatureDefinition {
           throw new Error("run-tenant-destruction: ctx.registry required (JobContext incomplete)");
         }
         const T = (await import("@cosmicdrift/kumiko-framework/time")).getTemporal();
+        const now = T.Now.instant();
+        // Without crossTenantReads (undeclared hatch) fall through to the sweep.
+        if (ctx.crossTenantReads && !(await hasTenantDestructionWork(ctx.crossTenantReads, now))) {
+          // skip: no tenant is due, so the sweep would not touch anything
+          return;
+        }
         await runTenantDestructionSweep({
           db: ctx.db.unsafeRaw() as import("@cosmicdrift/kumiko-framework/db").DbConnection, // @cast-boundary db-operator — jobs never run inside a DbTx
           registry: ctx.registry,
-          now: T.Now.instant(),
+          now,
           log: (message) => ctx.log?.warn(message),
           fileProviderResolver: ctx._fileProviderResolver,
           escapeHatchAuditSink: ctx._escapeHatchAuditSink,

package/packages/bundled-features/src/tenant-lifecycle/run-tenant-destroy.ts

@@ -1,6 +1,6 @@
 /// <reference types="temporal-polyfill/global" preserve="true" />
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import type { DbRunner, TenantDb, WhereObject } from "@cosmicdrift/kumiko-framework/db";
 import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 import {
   createSystemUser,
@@ -307,6 +307,26 @@ export async function runNextDestructionStage(args: {
   }
 }
 
+function destroyRequestedDueWhere(now: Temporal.Instant): WhereObject {
+  return {
+    status: "destroyRequested",
+    gracePeriodEnd: { lte: now.subtract({ milliseconds: TEARDOWN_GATE_SETTLE_MS }) },
+  };
+}
+
+const destroyingWhere: WhereObject = { status: "destroying" };
+
+export async function hasTenantDestructionWork(
+  reads: Pick<TenantDb, "count">,
+  now: Temporal.Instant,
+): Promise<boolean> {
+  const [due, destroying] = await Promise.all([
+    reads.count(tenantTable, destroyRequestedDueWhere(now)),
+    reads.count(tenantTable, destroyingWhere),
+  ]);
+  return due > 0 || destroying > 0;
+}
+
 /** Cron entry: start destruction for tenants past grace, then advance stages. */
 export async function runTenantDestructionSweep(args: {
   readonly db: DbRunner;
@@ -319,10 +339,7 @@ export async function runTenantDestructionSweep(args: {
 }): Promise<{ readonly triggered: number; readonly advanced: number }> {
   const T = getTemporal();
   const now = args.now ?? T.Now.instant();
-  const due = await selectMany<{ id: string }>(args.db, tenantTable, {
-    status: "destroyRequested",
-    gracePeriodEnd: { lte: now.subtract({ milliseconds: TEARDOWN_GATE_SETTLE_MS }) },
-  });
+  const due = await selectMany<{ id: string }>(args.db, tenantTable, destroyRequestedDueWhere(now));
 
   let triggered = 0;
   for (const row of due) {
@@ -354,9 +371,7 @@ export async function runTenantDestructionSweep(args: {
   }
 
   let advanced = 0;
-  const destroying = await selectMany<{ id: string }>(args.db, tenantTable, {
-    status: "destroying",
-  });
+  const destroying = await selectMany<{ id: string }>(args.db, tenantTable, destroyingWhere);
   for (const row of destroying) {
     try {
       const result = await runNextDestructionStage({

package/packages/bundled-features/src/user/index.ts

@@ -6,6 +6,7 @@ export {
 } from "./db/queries/stream-tenant-backfill.js";
 export { createUserFeature } from "./feature.js";
 export { isPrincipalBlocked, principalStatusPlugin } from "./principal-status.js";
+export { resolveUserDisplayNames } from "./resolve-display-names.js";
 export type { UserStatus } from "./schema/user.js";
 export {
   USER_ANONYMIZED_DISPLAY_NAME,

package/packages/bundled-features/src/user/resolve-display-names.ts

@@ -0,0 +1,35 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { decryptStoredPii, mapWithConcurrency } from "../shared/index.js";
+import { userTable } from "./schema/user.js";
+
+// Shares the KMS adapter's small dedicated pool, same as member-directory.
+const KMS_POOL_CONCURRENCY = 4;
+
+// One batched lookup for a page of user ids. Users that are missing, have no
+// display name, or whose name cannot be decrypted (e.g. crypto-shredded) are
+// left out, so callers fall back to the raw id instead of failing the page.
+export async function resolveUserDisplayNames(
+  db: TenantDb,
+  userIds: readonly string[],
+): Promise<ReadonlyMap<string, string>> {
+  const names = new Map<string, string>();
+  if (userIds.length === 0) return names;
+  const users = await selectMany(db, userTable, { id: [...userIds] });
+  const named = users.filter((user) => typeof user.displayName === "string");
+  await mapWithConcurrency(named, KMS_POOL_CONCURRENCY, async (user) => {
+    try {
+      names.set(
+        String(user.id),
+        await decryptStoredPii(
+          String(user.displayName),
+          "displayName",
+          "user:resolve-display-names",
+        ),
+      );
+    } catch {
+      // Unreadable name: the caller's fallback applies.
+    }
+  });
+  return names;
+}

package/samples/apps/use-all-bundled/e2e-billing-gallery/gallery-features.ts

@@ -69,8 +69,8 @@ export function createGalleryBillingFeature(baseUrl: string): FeatureDefinition
     baseUrl,
     catalog: {
       plans: ["starter", "pro"],
-      tierLabelKey: (tier) => `gallery.plan.${tier}.label`,
-      benefits: (tier) => [{ labelKey: `gallery.plan.${tier}.benefit` }],
+      tierLabelKey: (tier) => `gallery-screens:plan.${tier}.label`,
+      benefits: (tier) => [{ labelKey: `gallery-screens:plan.${tier}.benefit` }],
       resolveCurrentTier,
       viewRoles: ["TenantAdmin", "SystemAdmin"],
       successPath: GALLERY_PLAN_PATH,
@@ -83,9 +83,8 @@ export function createGalleryBillingFeature(baseUrl: string): FeatureDefinition
       operatorEmail: GALLERY_OPERATOR_EMAIL,
       terminationScope: "platform",
       legalLinks: {
-        terms: "/legal/terms",
-        withdrawal: "/legal/withdrawal",
-        privacy: "/legal/privacy",
+        de: { terms: "/legal/terms", withdrawal: "/legal/withdrawal", privacy: "/legal/privacy" },
+        en: { terms: "/legal/terms", withdrawal: "/legal/withdrawal", privacy: "/legal/privacy" },
       },
     },
   });
@@ -140,12 +139,12 @@ export const galleryScreensFeature: FeatureDefinition = defineFeature("gallery-s
   r.translations({
     keys: {
       "gallery:nav.billing": { de: "Abrechnung", en: "Billing" },
-      "gallery.plan.free.label": { de: "Free", en: "Free" },
-      "gallery.plan.starter.label": { de: "Starter", en: "Starter" },
-      "gallery.plan.pro.label": { de: "Pro", en: "Pro" },
-      "gallery.plan.starter.benefit": { de: "Für kleine Teams", en: "For small teams" },
-      "gallery.plan.pro.benefit": { de: "Für wachsende Teams", en: "For growing teams" },
-      "gallery.plan.free.benefit": { de: "Zum Ausprobieren", en: "To try things out" },
+      "gallery-screens:plan.free.label": { de: "Free", en: "Free" },
+      "gallery-screens:plan.starter.label": { de: "Starter", en: "Starter" },
+      "gallery-screens:plan.pro.label": { de: "Pro", en: "Pro" },
+      "gallery-screens:plan.starter.benefit": { de: "Für kleine Teams", en: "For small teams" },
+      "gallery-screens:plan.pro.benefit": { de: "Für wachsende Teams", en: "For growing teams" },
+      "gallery-screens:plan.free.benefit": { de: "Zum Ausprobieren", en: "To try things out" },
     },
   });
   return {};

package/samples/apps/use-all-bundled/e2e-billing-gallery/server.ts

@@ -42,8 +42,8 @@ const features = [
 ];
 
 const TERMS_TEXT: Readonly<Record<string, string>> = {
-  de: "## Allgemeine Geschäftsbedingungen\n\nDiese Bedingungen gelten für alle Verträge über die Plattform.",
-  en: "## Terms and conditions\n\nThese terms apply to every contract concluded through the platform.",
+  de: "Diese Bedingungen gelten für alle Verträge über die Plattform.",
+  en: "These terms apply to every contract concluded through the platform.",
 };
 
 const seedTerms: SeedFn = async (stack) => {