@cosmicdrift/kumiko-samples 0.387.0 → 0.388.0

package/packages/bundled-features/src/config/write-helpers.ts

@@ -75,8 +75,9 @@ export async function configRowHoldsValue(
   serializedValue: string,
 ): Promise<boolean> {
   if (row?.value === null || row?.value === undefined) return false;
-  if (!keyDef?.encrypted && !keyDef?.piiEncrypted) return row.value === serializedValue;
-  if (!keyDef) return false;
+  if (keyDef === undefined || (!keyDef.encrypted && !keyDef.piiEncrypted)) {
+    return row.value === serializedValue;
+  }
   try {
     return (await decryptStoredValue(row.value, keyDef, cipher, qualifiedKey)) === serializedValue;
   } catch {
@@ -194,12 +195,7 @@ export function validateScope(
   definedScope: ConfigScope,
   key: string,
 ): KumikoError | null {
-  const levels: Record<ConfigScope, number> = {
-    [ConfigScopes.system]: 0,
-    [ConfigScopes.tenant]: 1,
-    [ConfigScopes.user]: 2,
-  };
-  if (levels[requestedScope] > levels[definedScope]) {
+  if (SCOPE_LEVEL[requestedScope] > SCOPE_LEVEL[definedScope]) {
     return new UnprocessableError("invalid_scope", {
       i18nKey: "config.errors.invalidScope",
       details: { key, definedScope, requestedScope },
@@ -208,6 +204,29 @@ export function validateScope(
   return null;
 }
 
+const SCOPE_LEVEL: Record<ConfigScope, number> = {
+  [ConfigScopes.system]: 0,
+  [ConfigScopes.tenant]: 1,
+  [ConfigScopes.user]: 2,
+};
+
+// Reads a tenant/user key at a narrower scope, e.g. system for a system-level screen.
+// Only a SystemAdmin may widen the read to the platform level; everyone else keeps the normal cascade.
+export function keyDefAtScope(
+  keyDef: ConfigKeyDefinition,
+  readScope: ConfigScope | undefined,
+  roles: readonly string[],
+): ConfigKeyDefinition {
+  if (
+    readScope === undefined ||
+    !roles.includes("SystemAdmin") ||
+    SCOPE_LEVEL[readScope] >= SCOPE_LEVEL[keyDef.scope]
+  ) {
+    return keyDef;
+  }
+  return { ...keyDef, scope: readScope };
+}
+
 export function resolveScopeIds(
   scope: ConfigScope,
   tenantId: TenantId,

package/packages/bundled-features/src/crypto-shredding/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "forget-subject audit event survives a failing record owner lookup",
+    "detail": "The lookup of the record row's owning tenant now runs inside the file purge step, so a database error there is reported as cleanupError on the subject-forgotten event instead of aborting the handler after the key was erased."
+  },
   {
     "version": "0.377.0",
     "type": "fix",

package/packages/bundled-features/src/crypto-shredding/handlers/forget-subject.write.ts

@@ -324,11 +324,6 @@ async function sweepDerivedSubjectData(
   audit: { readonly requestId: string; readonly erasedBy: string },
   rawSubject: SubjectIdInput,
 ): Promise<string | undefined> {
-  const recordTenantId = await owningTenantOfRecordSubject(
-    crossTenantRunner,
-    ctx.registry.features,
-    rawSubject,
-  );
   const failureLabels: string[] = [];
   const runStep = async (step: (runner: DbRunner) => Promise<void>): Promise<void> => {
     try {
@@ -367,8 +362,14 @@ async function sweepDerivedSubjectData(
   });
 
   // File columns hold only the fileRef id, so the key erase never reaches the bytes.
-  await runStep((crossTenantSubjectRunner) =>
-    purgeFilesReachingSubject({
+  await runStep(async (crossTenantSubjectRunner) => {
+    // Inside the step: a failing owner lookup must land in the audit label, not abort the handler.
+    const recordTenantId = await owningTenantOfRecordSubject(
+      crossTenantSubjectRunner,
+      ctx.registry.features,
+      rawSubject,
+    );
+    await purgeFilesReachingSubject({
       registry: ctx.registry,
       db: crossTenantSubjectRunner,
       subject,
@@ -376,8 +377,8 @@ async function sweepDerivedSubjectData(
       ...(recordTenantId !== undefined && { recordTenantId }),
       resolveDeleteBytes: resolveFileBytesDeleter(ctx),
       missingStorage: { mode: "fail" },
-    }),
-  );
+    });
+  });
 
   return failureLabels[0];
 }

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

@@ -1,4 +1,34 @@
 [
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Preferences query reports renamed notification types under the current name",
+    "detail": "Rows stored under a former notification name are returned with the current name and collapsed per channel with the delivery precedence (current-name row wins, otherwise any disabled row disables), so settings screens show the effective state."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Inline mail image retries on transient storage errors",
+    "detail": "Only a missing file storage for the file's tenant sends the mail without the inline image; any other read error (timeout, provider failure, DB) is rethrown so the send job retries instead of mailing without the logo."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Unsubscribe tenant origin resolved once per notify call",
+    "detail": "The app's tenantOrigin callback runs once per notify call and tenant instead of once per recipient and channel, so a newsletter no longer causes one lookup and one fallback warning per address. The docs state the callback must only return verified, active domains."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "One-click unsubscribe POST keeps the JSON rejection",
+    "detail": "RFC 8058 one-click POSTs (form body List-Unsubscribe=One-Click) answer an invalid or expired token with the JSON 400 again and skip the branding lookup; only browser form submits get the HTML page."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Resubscribe limit page has its own text",
+    "detail": "A browser that hits the resubscribe limit sees that the address cannot be subscribed again here, instead of the generic \"try again later\" error (new key mail.unsubscribe.resubscribeLimitReached in en, de, es, fr, it)."
+  },
   {
     "version": "0.383.0",
     "type": "fix",

package/packages/bundled-features/src/delivery/channel-context.ts

@@ -5,7 +5,11 @@ import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 import type { FileContext } from "@cosmicdrift/kumiko-framework/files";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
-import { type FileRefContent, readFileRefContent } from "../file-foundation/index.ts";
+import {
+  type FileRefContent,
+  FileStorageUnavailableError,
+  readFileRefContent,
+} from "../file-foundation/index.ts";
 import {
   collectRendererPlugins,
   createRendererFoundationApi,
@@ -86,7 +90,8 @@ function createPdfRenderer(
   };
 }
 
-// A decorative inline image (logo) that cannot be read must not fail the whole mail.
+// A decorative inline image (logo) of a tenant without file storage must not fail the whole mail;
+// transient read errors rethrow so the send job retries.
 async function readInlineImageOrNull(
   fileRefId: string,
   read: () => Promise<FileRefContent | null>,
@@ -94,9 +99,10 @@ async function readInlineImageOrNull(
   try {
     return await read();
   } catch (err) {
+    if (!(err instanceof FileStorageUnavailableError)) throw err;
     createFallbackLogger("delivery").warn("inline image could not be read, sending without it", {
       fileRefId,
-      errorName: err instanceof Error ? err.name : typeof err,
+      errorName: err.name,
     });
     return null;
   }

package/packages/bundled-features/src/delivery/db/queries/preferences.ts

@@ -1,5 +1,5 @@
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/db";
+import { toPostgresArrayLiteral, unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 
 export type NotificationPreferenceRow = {
@@ -27,6 +27,6 @@ export async function selectNotificationPreferences(
          OR (notification_type = '*' AND channel = $4)
          OR (notification_type = ANY($3::text[]) AND channel = '*')
        )`,
-    [tenantId, userId, notificationTypeNames, channelName],
+    [tenantId, userId, toPostgresArrayLiteral(notificationTypeNames), channelName],
   );
 }

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

@@ -484,9 +484,37 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     }
   }
 
+  // The app's tenantOrigin callback typically hits the DB: once per run and tenant, not per recipient.
+  const unsubscribeOriginsByRun = new WeakMap<NotifyRun, Map<TenantId, Promise<string>>>();
+
+  function unsubscribeOriginOnce(
+    run: NotifyRun,
+    links: UnsubscribeLinkConfig,
+    channelCtx: ChannelContext,
+    notificationType: string,
+  ): Promise<string> {
+    let originsByTenant = unsubscribeOriginsByRun.get(run);
+    if (originsByTenant === undefined) {
+      originsByTenant = new Map();
+      unsubscribeOriginsByRun.set(run, originsByTenant);
+    }
+    let origin = originsByTenant.get(channelCtx.tenantId);
+    if (origin === undefined) {
+      origin = unsubscribeLinkOrigin(links, channelCtx, (reason) =>
+        logError.warn(`unsubscribe link falls back to the app origin: ${reason}`, {
+          tenantId: channelCtx.tenantId,
+          notificationType,
+        }),
+      );
+      originsByTenant.set(channelCtx.tenantId, origin);
+    }
+    return origin;
+  }
+
   // A caller-supplied unsubscribeUrl wins; the recipient comes from the server-side notify
   // context, never from the notification data.
   async function withUnsubscribeUrl(
+    run: NotifyRun,
     message: ChannelMessage,
     channelName: string,
     recipient: UnsubscribeLinkRecipient,
@@ -498,11 +526,11 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     }
     const supplied = message.data?.["unsubscribeUrl"];
     if (typeof supplied === "string" && supplied !== "") return message;
-    const origin = await unsubscribeLinkOrigin(unsubscribeLinks, channelCtx, (reason) =>
-      logError.warn(`unsubscribe link falls back to the app origin: ${reason}`, {
-        tenantId: channelCtx.tenantId,
-        notificationType: message.notificationType,
-      }),
+    const origin = await unsubscribeOriginOnce(
+      run,
+      unsubscribeLinks,
+      channelCtx,
+      message.notificationType,
     );
     const unsubscribeUrl = await buildUnsubscribeUrl(unsubscribeLinks, origin, recipient, {
       tenantId: channelCtx.tenantId,
@@ -811,6 +839,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
           channel,
           address,
           message: await withUnsubscribeUrl(
+            run,
             message,
             channel.name,
             { kind: "user", userId },
@@ -914,6 +943,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
           channel,
           address,
           message: await withUnsubscribeUrl(
+            run,
             message,
             channel.name,
             { kind: "address", address },

package/packages/bundled-features/src/delivery/handlers/preferences.query.ts

@@ -2,6 +2,7 @@ import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
+import { currentNotificationType } from "../notification-type-aliases.ts";
 import { notificationPreferencesTable } from "../tables.ts";
 
 export const preferencesQuery = defineQueryHandler({
@@ -37,6 +38,24 @@ export const preferencesQuery = defineQueryHandler({
       userId: query.user.id,
     });
 
-    return { rows };
+    // Rows stored under a former notification name are reported under the current
+    // one, collapsed with the same precedence as delivery: an exact row wins,
+    // otherwise any disabled former-name row disables.
+    const collapsed = new Map<string, { row: (typeof rows)[number]; isExact: boolean }>();
+    for (const row of rows) {
+      const notificationType = currentNotificationType(ctx.registry, row.notificationType);
+      const key = `${notificationType}\u0000${row.channel}`;
+      const isExact = row.notificationType === notificationType;
+      const existing = collapsed.get(key);
+      if (existing?.isExact) continue;
+      const formerNameRowDisablesAlready =
+        existing !== undefined &&
+        !isExact &&
+        (existing.row.enabled === false || row.enabled !== false);
+      if (formerNameRowDisablesAlready) continue;
+      collapsed.set(key, { row: { ...row, notificationType }, isExact });
+    }
+
+    return { rows: [...collapsed.values()].map((entry) => entry.row) };
   },
 });

package/packages/bundled-features/src/delivery/handlers/unsubscribe-page-chrome.query.ts

@@ -33,7 +33,7 @@ export const unsubscribePageChromeQuery = defineQueryHandler({
   // or createUnsubscribePageChromeReader for a tenant the app resolved server-side.
   agent: { expose: false },
   description:
-    "Returns the tenant's mail brand row and footer resolved for one locale, or null without a mail renderer; dispatched by the signed unsubscribe route to dress its pages like the mail, not meant for UI callers.",
+    "Returns the tenant's mail brand row and footer resolved for one locale, or null without a mail renderer; dispatched by the signed unsubscribe route or by createUnsubscribePageChromeReader for a tenant the app resolved server-side, to dress its pages like the mail; not meant for UI callers.",
   handler: async (query, ctx): Promise<MailChrome | null> => {
     const { tenantId } = query.user;
     if (!ctx.systemDb) {

package/packages/bundled-features/src/delivery/unsubscribe-link.ts

@@ -10,7 +10,9 @@ export type UnsubscribeLinkConfig = {
   readonly secret: string;
   readonly baseUrl: string;
   /** The sending tenant's own public origin (subdomain or custom domain), null when it has
-   *  none. The host must serve this app's `/api` routes. Null, a throw or an unusable value
+   *  none. The host must serve this app's `/api` routes, and the callback must only return a
+   *  verified, active domain of the tenant (the check that lets the app serve under it), else null:
+   *  the link carries a bearer token that unsubscribes and yields a resubscribe token. Null, a throw or an unusable value
    *  fall back to `baseUrl`, so a missing tenant origin never fails a send. */
   readonly tenantOrigin?: (ctx: ChannelContext) => Promise<string | null | undefined>;
 };

package/packages/bundled-features/src/delivery/unsubscribe-page-strings.ts

@@ -14,6 +14,7 @@ export const UNSUBSCRIBE_PAGE_EN = {
   "mail.unsubscribe.resubscribedMessage": "You have been subscribed again.",
   "mail.unsubscribe.failed": "That did not work. Please try again later.",
   "mail.unsubscribe.failedTitle": "Something went wrong",
+  "mail.unsubscribe.resubscribeLimitReached": "This address cannot be subscribed again here.",
   "mail.unsubscribe.invalidTitle": "Link no longer valid",
   "mail.unsubscribe.invalidMessage":
     "This link is invalid or has expired. Please use the unsubscribe link in a more recent email.",

package/packages/bundled-features/src/delivery/unsubscribe-page.ts

@@ -11,6 +11,7 @@ export type UnsubscribePageState =
   | { readonly kind: "unsubscribed"; readonly resubscribeToken?: string }
   | { readonly kind: "resubscribed" }
   | { readonly kind: "failed" }
+  | { readonly kind: "resubscribeLimitReached" }
   | { readonly kind: "invalid" };
 
 export type UnsubscribePageInput = {
@@ -162,6 +163,11 @@ ${tokenForm(DELIVERY_RESUBSCRIBE_PATH, state.resubscribeToken, mailT(lang, "mail
         title: mailT(lang, "mail.unsubscribe.failedTitle"),
         bodyHtml: paragraph("mail.unsubscribe.failed"),
       };
+    case "resubscribeLimitReached":
+      return {
+        title: mailT(lang, "mail.unsubscribe.failedTitle"),
+        bodyHtml: paragraph("mail.unsubscribe.resubscribeLimitReached"),
+      };
     case "invalid":
       return {
         title: mailT(lang, "mail.unsubscribe.invalidTitle"),

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

@@ -569,11 +569,20 @@ async function verifyPost(
   encodedSecret: Uint8Array,
   purpose: TokenPurpose,
 ): Promise<VerifiedUnsubscribe | RejectedForPage> {
-  return isFormRequest(request.headers["content-type"])
+  return isFormRequest(request.headers["content-type"]) && !isOneClickPost(request)
     ? verifyForPage(token, encodedSecret, purpose, request.headers)
     : verifyUnsubscribeToken(token, encodedSecret, purpose);
 }
 
+// RFC 8058 mail-provider POSTs are form-encoded too, but nobody looks at the answer: they keep
+// the JSON rejection and get no branded page.
+function isOneClickPost(request: SignatureExtraRouteVerifyRequest): boolean {
+  return (
+    isFormRequest(request.headers["content-type"]) &&
+    request.rawBody.trim() === DELIVERY_UNSUBSCRIBE_ONE_CLICK_HEADER_VALUE
+  );
+}
+
 function isFormRequest(contentType: string | undefined): boolean {
   return contentType?.includes("application/x-www-form-urlencoded") === true;
 }
@@ -635,22 +644,37 @@ export function createUnsubscribeRoutes(
         : pageResponse(c, deps, { kind: "confirm", token: verified.token }, verified, 200),
   });
 
-  const writeRoute = signatureRoute<VerifiedUnsubscribe | RejectedForPage>({
+  const writeRoute = signatureRoute<
+    (VerifiedUnsubscribe & { readonly oneClick: boolean }) | RejectedForPage
+  >({
     method: "POST",
     path: DELIVERY_UNSUBSCRIBE_PATH,
     entry: "signature",
-    verify: async (request) =>
-      verifyPost(request, tokenFromPostRequest(request), encodedSecret, "unsubscribe"),
+    verify: async (request) => {
+      const verified = await verifyPost(
+        request,
+        tokenFromPostRequest(request),
+        encodedSecret,
+        "unsubscribe",
+      );
+      return verified.kind === "rejected"
+        ? verified
+        : { ...verified, oneClick: isOneClickPost(request) };
+    },
     handler: async (c, verified, deps) => {
       if (verified.kind === "rejected") {
         return pageResponse(c, deps, { kind: "invalid" }, verified, 400);
       }
+      // No chrome lookup for a one-click client: it never renders the page.
+      const pageScope: PageScope = verified.oneClick
+        ? { tenantId: undefined, locale: verified.locale }
+        : verified;
       // Token-verify passed — everything below is a legitimate write. Don't
       // swallow write-errors as "invalid token", that would mask real bugs
       // (e.g. events-table missing, DB down) behind a misleading 400.
       const succeeded = await dispatchUnsubscribeWrite(verified, deps);
       if (!succeeded) {
-        return pageResponse(c, deps, { kind: "failed" }, verified, 500);
+        return pageResponse(c, deps, { kind: "failed" }, pageScope, 500);
       }
       return pageResponse(
         c,
@@ -659,7 +683,7 @@ export function createUnsubscribeRoutes(
           kind: "unsubscribed",
           resubscribeToken: await signResubscribeToken(verified, encodedSecret),
         },
-        verified,
+        pageScope,
         200,
       );
     },
@@ -681,15 +705,12 @@ export function createUnsubscribeRoutes(
       const outcome = await dispatchResubscribeWrite(verified, deps);
       // The undo button on the unsubscribed page posts a form; a browser should land on a page.
       if (isFormRequest(c.req.header("content-type"))) {
-        return outcome === "success"
-          ? pageResponse(c, deps, { kind: "resubscribed" }, verified, 200)
-          : pageResponse(
-              c,
-              deps,
-              { kind: "failed" },
-              verified,
-              outcome === "limit_reached" ? 409 : 500,
-            );
+        if (outcome === "success") {
+          return pageResponse(c, deps, { kind: "resubscribed" }, verified, 200);
+        }
+        return outcome === "limit_reached"
+          ? pageResponse(c, deps, { kind: "resubscribeLimitReached" }, verified, 409)
+          : pageResponse(c, deps, { kind: "failed" }, verified, 500);
       }
       if (outcome === "limit_reached") {
         return c.json(

package/packages/bundled-features/src/file-foundation/index.ts

@@ -10,6 +10,7 @@ export {
 export {
   type FileRefContent,
   FileRefTooLargeError,
+  FileStorageUnavailableError,
   fileContextForTenant,
   fileContextFromResolver,
   readFileRefContent,

package/packages/bundled-features/src/file-foundation/read-file-ref-content.ts

@@ -53,6 +53,12 @@ export class FileRefTooLargeError extends Error {
   }
 }
 
+export class FileStorageUnavailableError extends Error {
+  constructor() {
+    super("readFileRefContent: no file storage is available for the file's tenant");
+  }
+}
+
 // fileName of the row is never used: it is personal data and may be a PII ciphertext.
 export async function readFileRefContent(args: {
   readonly db: DbRunner | TenantDb;
@@ -82,7 +88,7 @@ export async function readFileRefContent(args: {
   }
   const files = args.filesForTenant(row.tenantId);
   if (files === undefined) {
-    throw new Error("readFileRefContent: no file storage is available for the file's tenant");
+    throw new FileStorageUnavailableError();
   }
   const content = await files.refFromFileRef(row).read();
   return { content, contentType: row.mimeType, tenantId: row.tenantId, size };

package/packages/bundled-features/src/file-provider-s3/env-named-feature.ts

@@ -13,8 +13,6 @@ export type NamedS3EnvProviderOptions = {
   readonly name: string;
   /** Env prefix of the credential set, e.g. `RELEASES_S3_`. */
   readonly envPrefix: string;
-  /** Tolerate missing credentials at boot; the provider then fails on its first file operation. */
-  readonly lazy?: boolean;
 };
 
 /** An additional S3 provider next to `"s3-env"`, reading its credentials from `<envPrefix>BUCKET` etc. */

package/packages/bundled-features/src/files/README.md

@@ -15,7 +15,7 @@ bewirtschaftet. Das öffnet die Tür für Cross-Feature-Hooks:
 ## Was es NICHT macht
 
 - **Keine Upload-/Download-Routes** — die bleiben in
-  `framework/src/api/server.ts` via `options.files`-Bootstrap.
+  `framework/src/api/server-routes.ts` (`mountFileRoutes`).
   Multipart-Form-Body und Binary-Streaming passen nicht ins Write/Query-
   Handler-Pattern; ein Refactor zu `r.httpRoute` wäre orthogonal zu
   diesem Sprint.

package/packages/bundled-features/src/form-draft/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Encrypted drafts without a PII key service raise an error",
+    "detail": "Reading a ciphertext draft with no PII subject key service configured throws instead of returning an empty draft, so the stale-draft cleanup defers it and no longer releases its file refs as if it were empty."
+  },
   {
     "version": "0.379.0",
     "type": "breaking",

package/packages/bundled-features/src/form-draft/db/queries/cleanup.ts

@@ -1,5 +1,5 @@
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/db";
+import { toPostgresArrayLiteral, unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { readStoredDraft } from "../../decrypt-draft.ts";
@@ -48,7 +48,7 @@ export async function selectStaleDraftsBatch(
      AND NOT ("id"::text = ANY($3::text[]))
      ORDER BY COALESCE("modified_at", "inserted_at") ASC
      LIMIT $2`,
-    [olderThanDays, batchSize, [...excludeIds]],
+    [olderThanDays, batchSize, toPostgresArrayLiteral([...excludeIds])],
   );
   return Promise.all(
     rows.map(async (row) => {

package/packages/bundled-features/src/form-draft/decrypt-draft.ts

@@ -4,6 +4,7 @@ import {
   decryptPiiFieldValues,
   isPiiCiphertext,
 } from "@cosmicdrift/kumiko-framework/crypto";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { type FormDraftBlob, formDraftBlobSchema } from "./schemas.ts";
 
 // Raw reads (fetchOne/selectMany/SQL) return the stored column, which is
@@ -13,7 +14,9 @@ import { type FormDraftBlob, formDraftBlobSchema } from "./schemas.ts";
 export async function readStoredDraft(stored: unknown): Promise<FormDraftBlob | null> {
   let plain = stored;
   const kms = configuredPiiSubjectKms();
-  if (isPiiCiphertext(stored) && kms) {
+  if (isPiiCiphertext(stored)) {
+    // A silent null would make the stale-draft cleanup treat the draft as empty and leak its file refs.
+    if (!kms) throw new InternalError({ message: "form-draft: pii kms not configured" });
     const out = await decryptPiiFieldValues({ draft: stored }, ["draft"], kms, {
       requestId: requestContext.get()?.requestId ?? "form-draft:read",
     });

package/packages/bundled-features/src/host-routing/README.md

@@ -92,5 +92,5 @@ allowlists stay in the app: wrap the dispatch function and fall through to it.
 
 - `tenantBy: (host, db) => TenantId | null` resolves every host that is neither the apex nor a fixed host (profile subdomains, custom domains). The tenant must be enabled and active; null means 404 for pages and `tenant_required` for the API. `createHostTenantIdResolver(options, db)` exposes the same mapping for managed-pages' `resolveApexTenant`.
 - `tenantPathPrefix` is optional in host and resolver mode and serves `<prefix>/<key>` on the apex. The API half still takes the apex anchor there; an app that needs a path-named tenant on API calls resolves it itself.
-- `redirects: [{ from, to, host?, status? }]` run before host classification. `to` is configured, never derived from the request.
+- `redirects: [{ from, to, host?, status? }]` run before host classification inside hostDispatch, i.e. only for requests that reach the HTML fallback (no static file, no API route); a `from` that matches a static file or `/api/...` never fires. `to` is configured, never derived from the request.
 - `apexAnonymousQueryAllowlist: { "example.com": ["feature:query:x"] }` limits the anonymous apex anchor to the listed query types on that host, for `/api/query` and `/api/stream`; other paths keep the anchor. `example.com` and `www.example.com` share one entry (a host without its own uses the other's). Combined with `tenantBy: "path"` it throws at boot, because the client names its tenant there (X-Tenant wins over the resolver) and would bypass the allowlist.

package/packages/bundled-features/src/host-routing/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Redirects documented as hostDispatch-only",
+    "detail": "The redirects option and README state that redirects run inside hostDispatch, so only for requests that reach the HTML fallback; a from matching a static file or an API route never fires. The shared existence lookup of the host and resolver modes is one helper."
+  },
   {
     "version": "0.376.0",
     "type": "improvement",

package/packages/bundled-features/src/host-routing/dispatch.ts

@@ -30,33 +30,32 @@ export type HostRoutingDispatchFn = (
 
 const tenantKeyExistsResultSchema = z.object({ exists: z.boolean() });
 
-async function isTenantKeyKnown(systemQuery: PageHeadSystemQuery, key: string): Promise<boolean> {
+async function existsViaSystemQuery(
+  systemQuery: PageHeadSystemQuery,
+  queryType: string,
+  payload: Record<string, string>,
+): Promise<boolean> {
   let result: unknown;
   try {
-    result = await systemQuery(HostRoutingQueries.tenantKeyExists, { key }, SYSTEM_TENANT_ID);
+    result = await systemQuery(queryType, payload, SYSTEM_TENANT_ID);
   } catch (error) {
     if (error instanceof ValidationError) return false;
-    // Over the rate limit every key looks the same: serve the tenant shell,
-    // which leaks nothing; the API behind it still resolves the tenant itself.
+    // Over the rate limit every key looks the same: serve the shell, which
+    // leaks nothing. The API resolver is authoritative and answers
+    // tenant_required for unknown hosts, while a 404 would hit visitors
+    // behind a shared NAT under load.
     if (error instanceof RateLimitError) return true;
     throw error;
   }
   return tenantKeyExistsResultSchema.parse(result).exists;
 }
 
-async function isHostKnown(systemQuery: PageHeadSystemQuery, host: string): Promise<boolean> {
-  let result: unknown;
-  try {
-    result = await systemQuery(HostRoutingQueries.hostTenantExists, { host }, SYSTEM_TENANT_ID);
-  } catch (error) {
-    if (error instanceof ValidationError) return false;
-    // The shell is harmless: the API resolver is authoritative and answers
-    // tenant_required for unknown hosts, while a 404 would hit visitors behind
-    // a shared NAT under load.
-    if (error instanceof RateLimitError) return true;
-    throw error;
-  }
-  return tenantKeyExistsResultSchema.parse(result).exists;
+function isTenantKeyKnown(systemQuery: PageHeadSystemQuery, key: string): Promise<boolean> {
+  return existsViaSystemQuery(systemQuery, HostRoutingQueries.tenantKeyExists, { key });
+}
+
+function isHostKnown(systemQuery: PageHeadSystemQuery, host: string): Promise<boolean> {
+  return existsViaSystemQuery(systemQuery, HostRoutingQueries.hostTenantExists, { host });
 }
 
 function serve(

package/packages/bundled-features/src/host-routing/options.ts

@@ -81,6 +81,7 @@ export type HostRoutingOptions = HostRoutingTenantMode & {
   // Not allowed with tenantBy "path" (boot error): there the client's X-Tenant
   // wins over the resolver, so the allowlist would be ineffective.
   readonly apexAnonymousQueryAllowlist?: Readonly<Record<string, readonly string[]>>;
-  // Checked first, before any host classification.
+  // Checked first within hostDispatch, i.e. only for requests that reach the HTML
+  // fallback (no static file, no API route): a `from` matching either never fires.
   readonly redirects?: readonly HostRoutingRedirect[];
 };