@cosmicdrift/kumiko-samples 0.341.0 → 0.343.0

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

@@ -1,11 +1,66 @@
+import {
+  DELIVERY_FAILURE_CODES,
+  DELIVERY_SKIP_REASONS,
+  type DeliveryFailureCode,
+  type DeliverySkipReason,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { DeliveryStatus, type DeliveryStatusValue } from "./public-names.js";
+
 type LocalizedString = { readonly en: string };
 
+// Typed over the code vocabularies, so a new code without a label fails to compile.
+const ERROR_LABELS = {
+  timeout: "Timed out",
+  network_error: "Network error",
+  redirect_blocked: "Redirect blocked",
+  host_not_allowed: "Host not allowed",
+  missing_credentials: "Missing credentials",
+  invalid_address: "Invalid address",
+  unexpected_response: "Unexpected provider response",
+  render_failed: "Rendering failed",
+  send_failed: "Sending failed",
+  channel_error: "Channel error",
+  channel_disabled: "Channel disabled",
+  preference_disabled: "Disabled in preferences",
+  rate_limited: "Rate limited",
+  no_address: "No address",
+  unsubscribed: "Unsubscribed",
+  duplicate_idempotency_key: "Duplicate request",
+} as const satisfies Record<DeliveryFailureCode | DeliverySkipReason, string>;
+
+const STATUS_LABELS = {
+  queued: "Queued",
+  sent: "Sent",
+  failed: "Failed",
+  skipped: "Skipped",
+} as const satisfies Record<DeliveryStatusValue, string>;
+
+function labelKeys(
+  prefix: string,
+  codes: readonly string[],
+  labels: Readonly<Record<string, string>>,
+): Record<string, LocalizedString> {
+  return Object.fromEntries(
+    codes.map((code) => [`${prefix}.${code}`, { en: labels[code] ?? code }]),
+  );
+}
+
 export const DELIVERY_I18N: Readonly<Record<string, LocalizedString>> = {
   "screen:delivery-log.title": { en: "Delivery log" },
   "delivery:nav.deliveryLog": { en: "Delivery" },
+  "delivery.log.col.createdAt": { en: "Time" },
   "delivery.log.col.tenantId": { en: "Tenant" },
   "delivery.log.col.type": { en: "Type" },
   "delivery.log.col.channel": { en: "Channel" },
   "delivery.log.col.recipient": { en: "Recipient" },
   "delivery.log.col.status": { en: "Status" },
+  "delivery.log.col.error": { en: "Error" },
+  ...labelKeys("delivery.status", Object.values(DeliveryStatus), STATUS_LABELS),
+  ...labelKeys(
+    "delivery.error",
+    [...DELIVERY_FAILURE_CODES, ...DELIVERY_SKIP_REASONS],
+    ERROR_LABELS,
+  ),
+  "delivery.status.sentUnconfirmed": { en: "Sent (unconfirmed)" },
+  "delivery.error.http": { en: "HTTP {status}" },
 };

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

@@ -10,6 +10,7 @@ export {
   type ChatSendFailureCode,
   type ChatSendResult,
   type ChatWebhookRequest,
+  type ChatWebhookResponse,
   type ChatWebhookTarget,
   chatConnectionNameSchema,
   chatWebhookUrlSchema,
@@ -38,6 +39,7 @@ export {
   type RateLimitConfig,
 } from "./delivery-service.js";
 export { createDeliveryFeature, type DeliveryFeatureOptions } from "./feature.js";
+export { createDeliveryNotifyFactory } from "./notify-factory.js";
 export {
   deliveryAttemptsTable,
   notificationAddressOptOutEntity,

package/packages/bundled-features/src/delivery/jobs.ts

@@ -7,6 +7,7 @@
 
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import type {
+  DeliveryErrorCode,
   JobContext,
   JobHandlerFn,
   Registry,
@@ -18,7 +19,7 @@ import * as z from "zod";
 import { appendAttemptEvent } from "./attempt-log.js";
 import { buildChannelContext } from "./channel-context.js";
 import { DeliveryJobs, deliveryPriorityRank } from "./constants.js";
-import { collectChannels } from "./delivery-service.js";
+import { collectChannels, redactedMessageOf } from "./delivery-service.js";
 import type {
   ChannelMessage,
   DeliveryChannel,
@@ -90,8 +91,9 @@ function toMessage(p: RenderJobPayload): ChannelMessage {
 function entryFor(
   p: RenderJobPayload,
   status: DeliveryLogEntry["status"],
-  error: string | null,
+  error: DeliveryErrorCode | null,
   address: string | null,
+  confirmed?: false,
 ): DeliveryLogEntry {
   return {
     tenantId: p.tenantId as TenantId, // @cast-boundary engine-payload — job payload string is the stream tenant
@@ -102,11 +104,33 @@ function entryFor(
     status,
     error,
     priority: p.priority,
+    ...(confirmed === false && { confirmed }),
   };
 }
 
-function messageOf(err: unknown): string {
-  return err instanceof Error ? err.message : String(err);
+// The job runner stores err.message in the run row, and BullMQ keeps failedReason and
+// the stack trace in Redis in plain text, so the rethrown error carries only the code.
+// The redacted message goes to the log.
+async function failAttempt(
+  ctx: JobContext,
+  db: DbConnection,
+  registry: Registry,
+  p: RenderJobPayload,
+  code: DeliveryErrorCode,
+  err: unknown,
+): Promise<never> {
+  const message = redactedMessageOf(err);
+  ctx.log.error(`delivery.${p.channelName} ${code}: ${message}`, {
+    notificationType: p.notificationType,
+    channel: p.channelName,
+  });
+  await appendAttemptEvent(
+    db,
+    registry,
+    p.deliveryAttemptId,
+    entryFor(p, "failed", code, p.address),
+  );
+  throw new Error(code);
 }
 
 // Render the message and hand off to delivery.send. On failure: record the
@@ -119,11 +143,16 @@ export const deliveryRenderJob: JobHandlerFn = async (payload, ctx) => {
   const channel = resolveChannel(registry, p.channelName);
   const channelCtx = buildChannelContext(db, registry, undefined, tenantId, ctx.secrets);
 
+  let rendered: RenderedMessage;
   try {
     if (!channel.render) {
       throw new Error(`delivery.render: channel "${p.channelName}" has no render step`);
     }
-    const rendered: RenderedMessage = await channel.render(toMessage(p), channelCtx);
+    rendered = await channel.render(toMessage(p), channelCtx);
+  } catch (err) {
+    return failAttempt(ctx, db, registry, p, "render_failed", err);
+  }
+  try {
     const jobRunner = ctx["jobRunner"] as JobRunner; // @cast-boundary dynamic-key — dispatch lives on the concrete runner
     await jobRunner.dispatch(
       DeliveryJobs.send,
@@ -131,13 +160,7 @@ export const deliveryRenderJob: JobHandlerFn = async (payload, ctx) => {
       { priority: deliveryPriorityRank[p.priority] },
     );
   } catch (err) {
-    await appendAttemptEvent(
-      db,
-      registry,
-      p.deliveryAttemptId,
-      entryFor(p, "failed", `render: ${messageOf(err)}`, p.address),
-    );
-    throw err;
+    return failAttempt(ctx, db, registry, p, "channel_error", err);
   }
 };
 
@@ -157,15 +180,15 @@ export const deliverySendJob: JobHandlerFn = async (payload, ctx) => {
       db,
       registry,
       p.deliveryAttemptId,
-      entryFor(p, result.status, result.error ?? null, result.address ?? p.address),
+      entryFor(
+        p,
+        result.status,
+        result.error ?? null,
+        result.address ?? p.address,
+        result.confirmed,
+      ),
     );
   } catch (err) {
-    await appendAttemptEvent(
-      db,
-      registry,
-      p.deliveryAttemptId,
-      entryFor(p, "failed", `send: ${messageOf(err)}`, p.address),
-    );
-    throw err;
+    return failAttempt(ctx, db, registry, p, "send_failed", err);
   }
 };

package/packages/bundled-features/src/delivery/notify-factory.ts

@@ -0,0 +1,19 @@
+import type { NotifyFactory } from "@cosmicdrift/kumiko-framework/engine";
+import type { DeliveryService } from "./types.js";
+
+// The same binding runProdApp wires into the app context: the calling context's
+// job dispatcher is handed to notify() per call, so queued channels go through
+// the delivery jobs. deliverQueuedInline drops the dispatcher and sends inline.
+export function createDeliveryNotifyFactory(
+  deliveryService: Pick<DeliveryService, "notify">,
+  options: { readonly deliverQueuedInline?: boolean } = {},
+): NotifyFactory {
+  return (user, tenantId, jobDispatcher) => (notificationType, notifyOptions) =>
+    deliveryService.notify(
+      notificationType,
+      notifyOptions,
+      user,
+      tenantId,
+      options.deliverQueuedInline === true ? undefined : jobDispatcher,
+    );
+}

package/packages/bundled-features/src/delivery/public-names.ts

@@ -33,6 +33,10 @@ export const DELIVERY_LOG_SCREEN_ID = "delivery-log" as const;
 // column — see `screen.columns[].renderer.react.__component` in feature.ts
 // and `deliveryClient()`'s `columnRenderers` map.
 export const DELIVERY_STATUS_CELL_COMPONENT = "DeliveryStatusCell" as const;
+export const DELIVERY_TYPE_CELL_COMPONENT = "DeliveryTypeCell" as const;
+export const DELIVERY_CHANNEL_CELL_COMPONENT = "DeliveryChannelCell" as const;
+export const DELIVERY_TIME_CELL_COMPONENT = "DeliveryTimeCell" as const;
+export const DELIVERY_ERROR_CELL_COMPONENT = "DeliveryErrorCell" as const;
 
 export const DeliveryErrors = {
   noRecipient: "delivery_no_recipient",

package/packages/bundled-features/src/delivery/tables.ts

@@ -43,6 +43,8 @@ export const deliveryAttemptsTable = pgTable(
     recipientAddress: text("recipient_address"),
     status: text("status").notNull().$type<"queued" | "sent" | "failed" | "skipped">(),
     error: text("error"),
+    // false = provider accepted but did not confirm; null = confirmed or not applicable.
+    confirmed: boolean("confirmed"),
     // Default covers rows that predate the column; new rows always carry the
     // notify() priority from the event payload.
     priority: text("priority").notNull().default("normal").$type<"critical" | "normal" | "low">(),
@@ -71,6 +73,7 @@ export const deliveryAttemptsTableMeta: EntityTableMeta = defineUnmanagedTable({
     { name: "recipient_address", pgType: "text", notNull: false },
     { name: "status", pgType: "text", notNull: true },
     { name: "error", pgType: "text", notNull: false },
+    { name: "confirmed", pgType: "boolean", notNull: false },
     { name: "priority", pgType: "text", notNull: true, defaultSql: "'normal'" },
     { name: "created_at", pgType: "timestamptz", notNull: true, defaultSql: "now()" },
   ],

package/packages/bundled-features/src/delivery/testing.ts

@@ -1,15 +1,13 @@
 import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import type {
-  EscapeHatchAuditSink,
-  Registry,
-  TenantId,
-} from "@cosmicdrift/kumiko-framework/engine";
+import type { EscapeHatchAuditSink, Registry } from "@cosmicdrift/kumiko-framework/engine";
 import type { JobRunner } from "@cosmicdrift/kumiko-framework/jobs";
 import type { Logger } from "@cosmicdrift/kumiko-framework/logging";
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import type { Redis } from "ioredis";
 import type { KillSwitchResolver, RateLimitConfig } from "./delivery-service.js";
 import { collectChannels, createDeliveryService } from "./delivery-service.js";
+import { createDeliveryNotifyFactory } from "./notify-factory.js";
 import type { DeliveryService } from "./types.js";
 
 export type CreateDeliveryTestContextOptions = {
@@ -19,6 +17,7 @@ export type CreateDeliveryTestContextOptions = {
   readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
   readonly log?: Logger;
   readonly jobRunner?: JobRunner;
+  readonly secrets?: SecretsContext;
 };
 
 /**
@@ -47,9 +46,6 @@ export function createDeliveryTestContext(
 
   return {
     deliveryService, // exposed so tests can inspect/call directly if needed
-    _notifyFactory:
-      (user: { id: number; tenantId: TenantId }, tenantId: TenantId) =>
-      (notificationType: string, notifyOptions: Record<string, unknown>) =>
-        deliveryService.notify(notificationType, notifyOptions as never, user as never, tenantId), // @cast-boundary engine-bridge
+    _notifyFactory: createDeliveryNotifyFactory(deliveryService),
   };
 }

package/packages/bundled-features/src/delivery/types.ts

@@ -1,6 +1,7 @@
 import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
 import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type {
+  DeliveryErrorCode,
   NotifyDeliveryStatus,
   NotifyJobDispatcher,
   NotifyOptions,
@@ -35,7 +36,9 @@ export type ChannelMessage = {
 
 export type ChannelResult = {
   readonly status: "sent" | "failed" | "skipped";
-  readonly error?: string;
+  readonly error?: DeliveryErrorCode;
+  // Only ever set to false: the provider accepted the message but did not confirm delivery.
+  readonly confirmed?: false;
   readonly address?: string;
 };
 
@@ -91,8 +94,9 @@ export type DeliveryLogEntry = {
   readonly recipientId: string | null;
   readonly recipientAddress: string | null;
   readonly status: NotifyDeliveryStatus;
-  readonly error: string | null;
+  readonly error: DeliveryErrorCode | null;
   readonly priority: NotifyPriority;
+  readonly confirmed?: false;
 };
 
 // --- Delivery Service ---

package/packages/bundled-features/src/delivery/web/client-plugin.tsx

@@ -1,8 +1,19 @@
 // @runtime client
 import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
 import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
-import { DELIVERY_FEATURE, DELIVERY_STATUS_CELL_COMPONENT } from "../public-names.js";
+import {
+  DELIVERY_CHANNEL_CELL_COMPONENT,
+  DELIVERY_ERROR_CELL_COMPONENT,
+  DELIVERY_FEATURE,
+  DELIVERY_STATUS_CELL_COMPONENT,
+  DELIVERY_TIME_CELL_COMPONENT,
+  DELIVERY_TYPE_CELL_COMPONENT,
+} from "../public-names.js";
+import { DeliveryChannelCell } from "./delivery-channel-cell.js";
+import { DeliveryErrorCell } from "./delivery-error-cell.js";
 import { DeliveryStatusCell } from "./delivery-status-cell.js";
+import { DeliveryTimeCell } from "./delivery-time-cell.js";
+import { DeliveryTypeCell } from "./delivery-type-cell.js";
 
 export type DeliveryClientOptions = {
   readonly translations?: TranslationsByLocale;
@@ -13,6 +24,10 @@ export function deliveryClient(options?: DeliveryClientOptions): ClientFeatureDe
     name: DELIVERY_FEATURE,
     columnRenderers: {
       [DELIVERY_STATUS_CELL_COMPONENT]: DeliveryStatusCell,
+      [DELIVERY_TYPE_CELL_COMPONENT]: DeliveryTypeCell,
+      [DELIVERY_CHANNEL_CELL_COMPONENT]: DeliveryChannelCell,
+      [DELIVERY_TIME_CELL_COMPONENT]: DeliveryTimeCell,
+      [DELIVERY_ERROR_CELL_COMPONENT]: DeliveryErrorCell,
     },
     ...(options?.translations !== undefined && { translations: options.translations }),
   };

package/packages/bundled-features/src/delivery/web/delivery-channel-cell.tsx

@@ -0,0 +1,13 @@
+// @runtime client
+// Channel column: the label comes from `delivery.channel.<name>`, registered by each
+// channel feature; unknown channels show their raw name.
+
+import { type ColumnRendererProps, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+import { translateOrRaw } from "../../shared/web/translate-or-raw.js";
+
+export function DeliveryChannelCell({ row }: ColumnRendererProps): ReactNode {
+  const t = useTranslation();
+  const channel = typeof row["channel"] === "string" ? row["channel"] : "";
+  return translateOrRaw(t, `delivery.channel.${channel}`, channel);
+}

package/packages/bundled-features/src/delivery/web/delivery-error-cell.tsx

@@ -0,0 +1,17 @@
+// @runtime client
+// Error column. The log only carries fixed codes (`DeliveryErrorCode`); `http_<status>`
+// takes the status as a parameter, anything unknown shows as the raw value.
+
+import { type ColumnRendererProps, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { HTTP_ERROR_CODE_PATTERN } from "@cosmicdrift/kumiko-types/handlers";
+import type { ReactNode } from "react";
+import { translateOrRaw } from "../../shared/web/translate-or-raw.js";
+
+export function DeliveryErrorCell({ row }: ColumnRendererProps): ReactNode {
+  const t = useTranslation();
+  const error = row["error"];
+  if (typeof error !== "string" || error === "") return null;
+  const http = HTTP_ERROR_CODE_PATTERN.exec(error);
+  if (http) return t("delivery.error.http", { status: http[1] });
+  return translateOrRaw(t, `delivery.error.${error}`, error);
+}

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

@@ -4,9 +4,10 @@
 // in feature.ts). The list frame itself is the generic declarative
 // projectionList renderer — only this one cell stays TSX.
 
-import type { ColumnRendererProps } from "@cosmicdrift/kumiko-renderer";
+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 "../../shared/web/translate-or-raw.js";
 import { DeliveryStatus } from "../public-names.js";
 
 const STATUS_TONE: Readonly<Record<string, StatusTone>> = {
@@ -17,10 +18,16 @@ const STATUS_TONE: Readonly<Record<string, StatusTone>> = {
 };
 
 export function DeliveryStatusCell({ row }: ColumnRendererProps): ReactNode {
+  const t = useTranslation();
   const status = typeof row["status"] === "string" ? row["status"] : "";
+  const unconfirmed = status === DeliveryStatus.sent && row["confirmed"] === false;
+  const labelKey = unconfirmed ? "delivery.status.sentUnconfirmed" : `delivery.status.${status}`;
   return (
-    <StatusBadge tone={STATUS_TONE[status] ?? "muted"} testId="delivery-status-cell">
-      {status}
+    <StatusBadge
+      tone={unconfirmed ? "muted" : (STATUS_TONE[status] ?? "muted")}
+      testId="delivery-status-cell"
+    >
+      {translateOrRaw(t, labelKey, status)}
     </StatusBadge>
   );
 }

package/packages/bundled-features/src/delivery/web/delivery-time-cell.tsx

@@ -0,0 +1,8 @@
+// @runtime client
+import { type ColumnRendererProps, formatWhen } from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+
+export function DeliveryTimeCell({ row }: ColumnRendererProps): ReactNode {
+  const createdAt = row["createdAt"];
+  return typeof createdAt === "string" ? formatWhen(createdAt) : "";
+}

package/packages/bundled-features/src/delivery/web/delivery-type-cell.tsx

@@ -0,0 +1,20 @@
+// @runtime client
+// Notification type column. Types are QNs like `<scope>:notify:<name>`; the
+// translation key is `<scope>.notification.<name>`, registered by the app that
+// owns the notification (bundled features register none). Falls back to the short
+// name, or to the raw value for any other format.
+
+import { type ColumnRendererProps, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+import { translateOrRaw } from "../../shared/web/translate-or-raw.js";
+
+const NOTIFICATION_QN_PATTERN = /^([^:]+):notify:(.+)$/;
+
+export function DeliveryTypeCell({ row }: ColumnRendererProps): ReactNode {
+  const t = useTranslation();
+  const type = typeof row["type"] === "string" ? row["type"] : "";
+  const match = NOTIFICATION_QN_PATTERN.exec(type);
+  if (!match) return type;
+  const [, scope, name] = match;
+  return translateOrRaw(t, `${scope}.notification.${name}`, name ?? type);
+}

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

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.343.0",
+    "type": "improvement",
+    "title": "ctx.crossTenantReads for read-only cross-tenant job reads",
+    "detail": "Jobs whose `escapeHatch` grants `unsafeRaw` get `ctx.crossTenantReads` with `selectMany`, `fetchOne` and `count` across all tenants, read-only. Each call is reported as the new escape-hatch kind `cross-tenant-read`; system crons audit it once per process and the metric `kumiko_escape_hatch_uses_total` counts every call. `EscapeHatchKind` and the `escape-hatch-used` audit schema gain `cross-tenant-read`.\n`tenant-lifecycle:job:run-tenant-destruction` checks through `ctx.crossTenantReads` whether a tenant is due and only then calls `ctx.db.unsafeRaw()`, so idle minutes no longer write an `unsafe-raw` audit event."
+  },
   {
     "version": "0.336.0",
     "type": "improvement",

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,