@cosmicdrift/kumiko-samples 0.371.1 → 0.372.0

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

@@ -24,7 +24,7 @@ import {
   assertNotifyTargetsOwnTenant,
   createEscapeHatchReporter,
 } from "@cosmicdrift/kumiko-framework/pipeline";
-import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import type { EnvelopeCipher, SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import type { Redis } from "ioredis";
 import { fileContextFromResolver } from "../file-foundation/index.ts";
@@ -46,6 +46,7 @@ import {
 } from "./db/queries/address-opt-outs.ts";
 import { selectNotificationPreferences } from "./db/queries/preferences.ts";
 import { notificationTypeNames } from "./notification-type-aliases.ts";
+import { sealRecipientAddress } from "./recipient-address-seal.ts";
 import {
   type ChannelContext,
   type ChannelMessage,
@@ -95,6 +96,9 @@ export type DeliveryServiceOptions = {
   // Credentials source for inline-delivered chat channels (webhook URL / bot
   // token). Jobs get ctx.secrets from the job runner instead.
   readonly secrets?: SecretsContext;
+  // Seals the recipient address inside queued job payloads (tenant scope). Absent means the
+  // payload carries the plaintext address.
+  readonly addressCipher?: EnvelopeCipher;
   // File storage for inline-delivered mails with attachments; jobs use their own ctx instead.
   readonly filesForTenant?: (tenantId: string) => FileContext | undefined;
   // Tenant config for inline rendering (mail layout reads tenant name, locale);
@@ -134,6 +138,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     idempotencyRedis,
     jobRunner,
     secrets,
+    addressCipher,
     filesForTenant,
     tenantConfigFor,
     escapeHatchAuditSink,
@@ -429,7 +434,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
         channel.render ? DeliveryJobs.render : DeliveryJobs.send,
         {
           channelName: channel.name,
-          address,
+          ...(await sealRecipientAddress(address, tenantId, addressCipher)),
           tenantId,
           recipientId,
           notificationType,

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

@@ -29,8 +29,8 @@ export const unsubscribePageChromeQuery = defineQueryHandler({
   name: "unsubscribePageChrome",
   schema: z.object({ locale: z.string().min(2).max(35) }),
   access: { roles: access.systemAdmin },
-  // Only reachable via createUnsubscribeRoutes' dispatchSystemQuery once verify()
-  // proved the token signature.
+  // Only reachable via a system dispatch: the signed unsubscribe routes after verify(),
+  // 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.",

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

@@ -96,11 +96,13 @@ export {
 } from "./types.ts";
 export {
   type AddressUnsubscribeTokenPayload,
+  createUnsubscribePageChromeReader,
   createUnsubscribeRoutes,
   DELIVERY_UNSUBSCRIBE_ONE_CLICK_HEADER_VALUE,
   renderUnsubscribeResultPage,
   signAddressUnsubscribeToken,
   signUnsubscribeToken,
+  type UnsubscribePageChromeReader,
   type UnsubscribeResultPage,
   type UnsubscribeRouteOptions,
   type UnsubscribeTokenPayload,

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

@@ -26,6 +26,11 @@ import { appendAttemptEvent } from "./attempt-log.ts";
 import { buildChannelContext } from "./channel-context.ts";
 import { DeliveryJobs, deliveryIdempotencyRedisKey, deliveryPriorityRank } from "./constants.ts";
 import { collectChannels, redactedMessageOf } from "./delivery-service.ts";
+import {
+  openRecipientAddress,
+  type RecipientAddressField,
+  recipientAddressFieldSchema,
+} from "./recipient-address-seal.ts";
 import type {
   ChannelMessage,
   DeliveryChannel,
@@ -41,9 +46,8 @@ const channelMessageSchema = z.object({
   locale: z.string().optional(),
 });
 
-const renderJobPayloadSchema = z.object({
+const renderJobBaseSchema = z.object({
   channelName: z.string(),
-  address: z.string(),
   tenantId: z.string(),
   recipientId: z.string().nullable(),
   notificationType: z.string(),
@@ -53,18 +57,22 @@ const renderJobPayloadSchema = z.object({
   idempotencyKey: z.string().optional(),
 });
 
-const sendJobPayloadSchema = renderJobPayloadSchema.extend({
-  rendered: z
-    .object({
-      html: z.string(),
-      subject: z.string(),
-      text: z.string().optional(),
-      fromName: z.string().optional(),
-      replyTo: z.string().optional(),
-      attachments: z.array(emailAttachmentRefSchema).max(MAX_EMAIL_ATTACHMENTS).optional(),
-    })
-    .optional(),
-});
+const renderJobPayloadSchema = renderJobBaseSchema.and(recipientAddressFieldSchema);
+
+const sendJobPayloadSchema = renderJobBaseSchema
+  .extend({
+    rendered: z
+      .object({
+        html: z.string(),
+        subject: z.string(),
+        text: z.string().optional(),
+        fromName: z.string().optional(),
+        replyTo: z.string().optional(),
+        attachments: z.array(emailAttachmentRefSchema).max(MAX_EMAIL_ATTACHMENTS).optional(),
+      })
+      .optional(),
+  })
+  .and(recipientAddressFieldSchema);
 
 type RenderJobPayload = z.infer<typeof renderJobPayloadSchema>;
 
@@ -189,6 +197,22 @@ async function releasingKeyOnTerminalFailure<T>(
   }
 }
 
+// A missing or rotated key must not hide the original failure, so the log row just omits the address.
+async function addressForAttemptLog(
+  p: RecipientAddressField & { readonly tenantId: string },
+  ctx: JobContext,
+): Promise<string | null> {
+  try {
+    return await openRecipientAddress(
+      p,
+      p.tenantId as TenantId, // @cast-boundary engine-payload — job payload string is the stream tenant
+      ctx.configEncryption,
+    );
+  } catch {
+    return null;
+  }
+}
+
 // 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.
@@ -209,7 +233,7 @@ async function failAttempt(
     db,
     registry,
     p.deliveryAttemptId,
-    entryFor(p, "failed", code, p.address),
+    entryFor(p, "failed", code, await addressForAttemptLog(p, ctx)),
   );
   throw new Error(code);
 }
@@ -280,18 +304,13 @@ async function sendStep(p: z.infer<typeof sendJobPayloadSchema>, ctx: JobContext
   );
 
   try {
-    const result = await channel.send(p.address, toMessage(p), channelCtx, p.rendered);
+    const address = await openRecipientAddress(p, tenantId, ctx.configEncryption);
+    const result = await channel.send(address, toMessage(p), channelCtx, p.rendered);
     await appendAttemptEvent(
       db,
       registry,
       p.deliveryAttemptId,
-      entryFor(
-        p,
-        result.status,
-        result.error ?? null,
-        result.address ?? p.address,
-        result.confirmed,
-      ),
+      entryFor(p, result.status, result.error ?? null, result.address ?? address, result.confirmed),
     );
     // A soft failure ends the job successfully, so no retry follows and the caller's
     // retry must not be skipped as a duplicate.

package/packages/bundled-features/src/delivery/recipient-address-seal.ts

@@ -0,0 +1,72 @@
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import type { EnvelopeCipher } from "@cosmicdrift/kumiko-framework/secrets";
+import * as z from "zod";
+
+// Queued delivery jobs sit in Redis and the job-run table, so the recipient address travels
+// sealed under the app master key. Without a master key it stays plaintext (`address`); jobs
+// queued before sealing existed carry `address` too and keep working.
+// Exactly one of the two fields: both or neither fails the payload parse.
+export const recipientAddressFieldSchema = z.union([
+  z.object({ address: z.string(), sealedAddress: z.undefined().optional() }),
+  z.object({ sealedAddress: z.string(), address: z.undefined().optional() }),
+]);
+
+export type RecipientAddressField = z.infer<typeof recipientAddressFieldSchema>;
+
+// The cipher is shared with config values and PII entity fields and has no AAD, so the purpose is
+// bound inside the authenticated plaintext. Without it a foreign ciphertext of the same tenant
+// placed into sealedAddress would be decrypted and its plaintext sent to the channel. The tenant
+// is bound there too: the env key provider ignores the encrypt scope, so a sealedAddress of tenant
+// B would otherwise open inside a job of tenant A.
+const RECIPIENT_ADDRESS_PURPOSE = "delivery.recipientAddress";
+
+const sealedRecipientAddressSchema = z.object({
+  purpose: z.literal(RECIPIENT_ADDRESS_PURPOSE),
+  tenantId: z.string(),
+  address: z.string(),
+});
+
+export async function sealRecipientAddress(
+  address: string,
+  tenantId: TenantId,
+  cipher: EnvelopeCipher | undefined,
+): Promise<RecipientAddressField> {
+  if (!cipher) return { address };
+  const plaintext = JSON.stringify({ purpose: RECIPIENT_ADDRESS_PURPOSE, tenantId, address });
+  return { sealedAddress: await cipher.encrypt(plaintext, { tenantId }) };
+}
+
+function parseSealedRecipientAddress(plaintext: string, tenantId: TenantId): string {
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(plaintext);
+  } catch {
+    decoded = undefined;
+  }
+  const parsed = sealedRecipientAddressSchema.safeParse(decoded);
+  if (!parsed.success || parsed.data.tenantId !== tenantId) {
+    throw new InternalError({
+      message: "delivery job: sealedAddress was not sealed as a delivery recipient address",
+    });
+  }
+  return parsed.data.address;
+}
+
+export async function openRecipientAddress(
+  payload: RecipientAddressField,
+  tenantId: TenantId,
+  cipher: EnvelopeCipher | undefined,
+): Promise<string> {
+  if (payload.sealedAddress === undefined) return payload.address;
+  if (!cipher) {
+    throw new InternalError({
+      message:
+        "delivery job: payload carries a sealed recipient address but this process has no master key (configEncryption); run the worker with the same KUMIKO_SECRETS_MASTER_KEY_V<n> as the web process",
+    });
+  }
+  return parseSealedRecipientAddress(
+    await cipher.decrypt(payload.sealedAddress, { tenantId }),
+    tenantId,
+  );
+}

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

@@ -9,7 +9,7 @@ import type {
 import type { FileContext } from "@cosmicdrift/kumiko-framework/files";
 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 { EnvelopeCipher, SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import type { Redis } from "ioredis";
 import type { KillSwitchResolver, RateLimitConfig } from "./delivery-service.ts";
 import { collectChannels, createDeliveryService } from "./delivery-service.ts";
@@ -25,6 +25,8 @@ export type CreateDeliveryTestContextOptions = {
   readonly log?: Logger;
   readonly jobRunner?: JobRunner;
   readonly secrets?: SecretsContext;
+  // Seals queued job payload addresses and, like the boot wiring, doubles as the jobs' ctx.configEncryption.
+  readonly addressCipher?: EnvelopeCipher;
   readonly idempotencyRedis?: Redis;
   readonly filesForTenant?: (tenantId: string) => FileContext | undefined;
   readonly tenantConfigFor?: (tenantId: TenantId) => ConfigAccessor;
@@ -58,5 +60,6 @@ export function createDeliveryTestContext(
   return {
     deliveryService, // exposed so tests can inspect/call directly if needed
     _notifyFactory: createDeliveryNotifyFactory(deliveryService),
+    ...(options.addressCipher && { configEncryption: options.addressCipher }),
   };
 }

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

@@ -3,6 +3,7 @@ import {
   ExtraRouteRejection,
   type SignatureExtraRouteDeps,
   type SignatureExtraRouteVerifyRequest,
+  type SystemDispatchArgs,
   signatureRoute,
 } from "@cosmicdrift/kumiko-framework/api";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
@@ -423,7 +424,9 @@ export type UnsubscribeResultPage =
 
 /** The result page the unsubscribe routes answer with, for apps serving their own
  *  (e.g. legacy) unsubscribe links. Texts come from the mail translations of `locale`;
- *  `chrome` (the mail renderer's readMailChrome) adds the tenant's brand row and footer.
+ *  `chrome` adds the tenant's brand row and footer: read it with
+ *  createUnsubscribePageChromeReader for a tenant the server resolved itself (e.g. by
+ *  Host), never for a tenantId taken from the query string or body.
  *  Served under runProdApp's default CSP the style block and the same-origin font pass;
  *  an https logo additionally needs its origin, e.g.
  *  `securityHeaders: { csp: { extend: { "img-src": [logoOrigin] } } }`. A hand-written CSP
@@ -454,10 +457,14 @@ const mailChromeSchema = z
   })
   .nullable();
 
+type SystemQueryDispatch = {
+  readonly dispatchSystemQuery: (args: SystemDispatchArgs) => Promise<unknown>;
+};
+
 // Branding is decoration: an opt-out that went through must never turn into an
 // error page because a footer resolver or the config read failed.
 async function readPageChrome(
-  deps: SignatureExtraRouteDeps,
+  deps: SystemQueryDispatch,
   tenantId: TenantId,
   locale: string,
 ): Promise<MailChrome | null> {
@@ -477,6 +484,20 @@ async function readPageChrome(
   }
 }
 
+export type UnsubscribePageChromeReader = (
+  tenantId: TenantId,
+  locale: string | undefined,
+) => Promise<MailChrome | null>;
+
+/** Reads the chrome for renderUnsubscribeResultPage in an app route without
+ *  public access: build it once in the `wire` hook from its dispatchSystemQuery.
+ *  Null without a mail renderer or when the read fails. */
+export function createUnsubscribePageChromeReader(
+  deps: SystemQueryDispatch,
+): UnsubscribePageChromeReader {
+  return (tenantId, locale) => readPageChrome(deps, tenantId, pageLocale(locale));
+}
+
 type PageScope = { readonly tenantId: TenantId | undefined; readonly locale: string | undefined };
 
 // no-referrer on every page: the GET page carries the token in its URL, and the

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

@@ -2,7 +2,7 @@ import type { DbRunner, TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { isUuid, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
-  createFileContext,
+  createTenantFileContext,
   type FileContext,
   type FileProviderResolver,
   fileRefsTable,
@@ -44,7 +44,7 @@ export function fileContextFromResolver(
 ): FileContext {
   // @cast-boundary engine-payload — tenantId comes from a trusted job payload or session
   const brandedTenantId = tenantId as TenantId;
-  return createFileContext(() => resolver(brandedTenantId), tenantId);
+  return createTenantFileContext(resolver, brandedTenantId);
 }
 
 export class FileRefTooLargeError extends Error {

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

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.372.0",
+    "type": "breaking",
+    "title": "Orphaned upload bytes are swept through a new upload ledger",
+    "detail": "The files feature registers the store_file_upload_ledger table and an hourly sweep job. FileContext has the new methods writeUploadBytes and forgetUploadBytes, which the four upload paths use; a custom FileContext or resolver must provide the ledger (withUploadLedger wraps a resolver). TenantDb.deleteMany resolves to the number of deleted rows instead of void. A fileRef commit whose ledger row was already swept throws InternalError \"upload expired\".",
+    "migration": "Generate and apply a migration with `kumiko-schema generate` — uploads fail without the new store_file_upload_ledger table"
+  },
   {
     "version": "0.354.0",
     "type": "breaking",

package/packages/bundled-features/src/personal-access-tokens/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.372.0",
+    "type": "fix",
+    "title": "Tenants whose tier excludes API tokens now reach the lockedFallbackScreen",
+    "detail": "GET /api/schema removed every screen of a feature the tenant has switched off, and the role projection then dropped the navs of other features that pointed at them. The token list screen was gone, so the upgrade screen set via lockedFallbackScreen was never shown. Screens that declare a fallback (and the same-feature screens those fallbacks name) now stay in the schema; the server still rejects their queries and writes with feature_disabled, which makes the renderer show the fallback. Navs, content collections and workspaces of the disabled feature are still removed."
+  },
+  {
+    "version": "0.372.0",
+    "type": "improvement",
+    "title": "The token list looks like any other Kumiko list",
+    "detail": "The create button now sits in the page header next to the title, and an empty list shows the standard hint with a create button. The German title of the list screen is \"API-Tokens\" instead of \"Personal Access Tokens\", which also fixes the breadcrumb of the mint screen. Renderer, all apps: a projection list without an entity create button now shows its first primary toolbar action (one that needs no confirmation dialog) in the page header on desktop as well, with its label, instead of in the toolbar row; on phones it already did. On desktop only an icon derived from the action id (or declared on the action) is shown; the plus fallback exists only on phones. Consumers get this after the bump without code changes."
+  },
   {
     "version": "0.368.0",
     "type": "improvement",

package/packages/bundled-features/src/personal-access-tokens/screens.ts

@@ -32,6 +32,15 @@ const PAT_SCREEN_VISIBLE_WHEN = {
   eq: true,
 } as const;
 
+const PAT_CREATE_ACTION = {
+  kind: "navigate",
+  id: "create",
+  label: i18nKey("pat.create.title"),
+  screen: PAT_MINT_SCREEN_ID,
+  style: "primary",
+  icon: "plus",
+} as const;
+
 export const patListScreen: ProjectionListScreenDefinition = {
   id: PAT_SCREEN_ID,
   type: "projectionList",
@@ -82,15 +91,12 @@ export const patListScreen: ProjectionListScreenDefinition = {
       visible: { field: "status", ne: "revoked" },
     },
   ],
-  toolbarActions: [
-    {
-      kind: "navigate",
-      id: "create",
-      label: i18nKey("pat.create.title"),
-      screen: PAT_MINT_SCREEN_ID,
-      style: "primary",
-    },
-  ],
+  toolbarActions: [PAT_CREATE_ACTION],
+  emptyState: {
+    title: i18nKey("kumiko.list.empty.title"),
+    description: i18nKey("kumiko.list.empty.hint"),
+    action: PAT_CREATE_ACTION,
+  },
   access: {
     openToAll: {
       reason:

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

@@ -31,6 +31,20 @@ export {
   parentRowIsVisible,
 } from "./parent-visibility.ts";
 export { hashPassword, verifyDummyPassword, verifyPassword } from "./password-hashing.ts";
+export {
+  type DeleteFileBytes,
+  FileSweepError,
+  type MissingStoragePolicy,
+  purgeFilesReachingSubject,
+} from "./purge-files-reaching-subject.ts";
+export {
+  collectSingleFileHolders,
+  type FileFieldPlan,
+  type FileRefPurgeOutcome,
+  planFileFields,
+  purgeRowFileRefs,
+  type SingleFileHolder,
+} from "./purge-row-file-refs.ts";
 export { rateLimitedTextResponse } from "./rate-limited-text-response.ts";
 export {
   redactBotTokens,

package/packages/bundled-features/src/shared/purge-files-reaching-subject.ts

@@ -0,0 +1,206 @@
+import {
+  resolveSubjectForField,
+  type SubjectId,
+  SubjectResolutionError,
+  subjectIdToKey,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import {
+  createEventStoreExecutor,
+  createTenantDb,
+  type DbRunner,
+  selectMany,
+  type WhereObject,
+} from "@cosmicdrift/kumiko-framework/db";
+import {
+  createSystemUser,
+  type EntityDefinition,
+  parseTenantId,
+  type Registry,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { fileRefEntity, fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
+import {
+  collectSingleFileHolders,
+  type FileRefPurgeOutcome,
+  planFileFields,
+  purgeRowFileRefs,
+  type SingleFileHolder,
+} from "./purge-row-file-refs.ts";
+
+// Callers' error labels read err.code, so audit events name the failure class.
+export class FileSweepError extends Error {
+  constructor(
+    readonly code: Exclude<FileRefPurgeOutcome, "purged">,
+    readonly entityName: string,
+  ) {
+    super(`[files-purge] ${code} while purging files of entity ${entityName}`);
+    this.name = "FileSweepError";
+  }
+}
+
+type FileEntity = {
+  readonly entityName: string;
+  readonly entity: EntityDefinition;
+  readonly table: Parameters<typeof selectMany>[1];
+  readonly fileFields: readonly string[];
+};
+
+function collectFileEntities(registry: Registry): readonly FileEntity[] {
+  const found: FileEntity[] = [];
+  for (const proj of registry.getAllProjections().values()) {
+    if (proj.isImplicit !== true || typeof proj.source !== "string" || !proj.table) continue;
+    const entity = registry.getEntity(proj.source);
+    if (!entity) continue;
+    const { singleFields, multiFields } = planFileFields(entity.fields);
+    const fileFields = [...singleFields, ...multiFields];
+    if (fileFields.length === 0) continue;
+    found.push({ entityName: proj.source, entity, table: proj.table, fileFields });
+  }
+  return found;
+}
+
+// Candidate rows only; the exact per-field subject is verified with resolveSubjectForField,
+// the same resolver that encrypted the field.
+function candidateWheres(
+  subject: SubjectId,
+  recordTenantId: TenantId | undefined,
+  { entityName, entity, fileFields }: FileEntity,
+): readonly WhereObject[] {
+  if (subject.kind === "record") {
+    // Without the owning tenant the record cannot be told apart from a same-id row elsewhere.
+    return entityName === subject.entity && recordTenantId !== undefined
+      ? [{ id: subject.id, tenantId: recordTenantId }]
+      : [];
+  }
+  if (subject.kind !== "user") return [];
+  const wheres: WhereObject[] = [];
+  for (const fieldName of fileFields) {
+    const field = entity.fields[fieldName];
+    if (field && "userOwned" in field && field.userOwned !== undefined) {
+      wheres.push({ [field.userOwned.ownerField]: subject.userId });
+    } else if (field && "pii" in field && field.pii === true && entity.idType !== "serial") {
+      wheres.push({ id: subject.userId });
+    }
+  }
+  return wheres;
+}
+
+function fieldsResolvingToSubject(
+  fileEntity: FileEntity,
+  row: Record<string, unknown>,
+  rowTenantId: TenantId,
+  subjectKey: string,
+): readonly string[] {
+  return fileEntity.fileFields.filter((fieldName) => {
+    try {
+      const resolved = resolveSubjectForField(fileEntity.entity, fieldName, row, {
+        tenantId: rowTenantId,
+        entityName: fileEntity.entityName,
+      });
+      return resolved !== null && subjectIdToKey(resolved) === subjectKey;
+    } catch (err) {
+      // skip: a field whose owner cannot be resolved on this row never encrypted under this subject
+      if (err instanceof SubjectResolutionError) return false;
+      throw err;
+    }
+  });
+}
+
+const fileRefExecutor = createEventStoreExecutor(fileRefsTable, fileRefEntity, {
+  entityName: "fileRef",
+});
+
+export type DeleteFileBytes = (storageKey: string) => Promise<readonly string[]>;
+
+// What to do when a tenant has files to delete but no storage: fail closed (the files would
+// leak while the erasure reads as done) or skip with a warning, for callers whose erasure must
+// not be blocked forever by a misconfigured store.
+export type MissingStoragePolicy =
+  | { readonly mode: "fail" }
+  | { readonly mode: "skip"; readonly warn: (tenantId: TenantId) => void };
+
+async function deleteBytesFailingClosed(
+  deleteBytes: DeleteFileBytes,
+  storageKey: string,
+): Promise<readonly string[]> {
+  try {
+    return await deleteBytes(storageKey);
+  } catch {
+    // skip: an unsafe key or missing list permission fails this file closed, not the whole sweep
+    return [storageKey];
+  }
+}
+
+// Forgetting a subject erases keys; the files behind a personal file field are not ciphertext,
+// so they need their own purge (bytes, derivatives, fileRef rows). The entity row stays:
+// forgetting is crypto-shredding, not deletion. Tenant subjects are covered by
+// files-tenant-data on tenant destroy. The storage is resolved per owning tenant because a
+// subject's rows can live in any tenant.
+export async function purgeFilesReachingSubject(args: {
+  readonly registry: Registry;
+  readonly db: DbRunner;
+  readonly subject: SubjectId;
+  readonly subjectKey: string;
+  // Tenant owning the row of a record subject; a record subject without it purges nothing.
+  readonly recordTenantId?: TenantId;
+  readonly resolveDeleteBytes: (tenantId: TenantId) => Promise<DeleteFileBytes | undefined>;
+  readonly missingStorage: MissingStoragePolicy;
+}): Promise<void> {
+  const { registry, db, subject, subjectKey, recordTenantId, resolveDeleteBytes, missingStorage } =
+    args;
+  // skip: tenant subjects are covered by files-tenant-data on tenant destroy
+  if (subject.kind === "tenant") return;
+
+  const fileHolders: readonly SingleFileHolder[] = collectSingleFileHolders(registry);
+  const storageByTenant = new Map<TenantId, Promise<DeleteFileBytes | undefined>>();
+  let firstFailure: FileSweepError | undefined;
+
+  for (const fileEntity of collectFileEntities(registry)) {
+    const seenRowIds = new Set<string>();
+    for (const where of candidateWheres(subject, recordTenantId, fileEntity)) {
+      const rows = await selectMany<Record<string, unknown>>(db, fileEntity.table, where);
+      for (const row of rows) {
+        const rowId = String(row["id"]);
+        const tenantId = parseTenantId(row["tenantId"]);
+        // skip: a row without a tenant cannot own tenant-scoped file refs
+        if (seenRowIds.has(rowId) || tenantId === null) continue;
+        seenRowIds.add(rowId);
+
+        const fieldNames = fieldsResolvingToSubject(fileEntity, row, tenantId, subjectKey);
+        // skip: none of the row's file fields belongs to this subject
+        if (fieldNames.length === 0) continue;
+
+        let storagePromise = storageByTenant.get(tenantId);
+        if (storagePromise === undefined) {
+          storagePromise = resolveDeleteBytes(tenantId);
+          storageByTenant.set(tenantId, storagePromise);
+        }
+        const deleteBytes = await storagePromise;
+        const systemUser = createSystemUser(tenantId);
+        const tdb = createTenantDb({ db, tenantId, mode: "system" });
+
+        const outcome = await purgeRowFileRefs({
+          db,
+          tenantId,
+          entityName: fileEntity.entityName,
+          entity: fileEntity.entity,
+          table: fileEntity.table,
+          fileHolders,
+          row,
+          fieldNames,
+          deleteBytes: deleteBytes
+            ? (key) => deleteBytesFailingClosed(deleteBytes, key)
+            : undefined,
+          fileRefForget: async (fileRefId) =>
+            (await fileRefExecutor.forget({ id: fileRefId }, systemUser, tdb)).isSuccess,
+        });
+        if (outcome === "missing_file_storage" && missingStorage.mode === "skip") {
+          missingStorage.warn(tenantId);
+        } else if (outcome !== "purged") {
+          firstFailure ??= new FileSweepError(outcome, fileEntity.entityName);
+        }
+      }
+    }
+  }
+  if (firstFailure) throw firstFailure;
+}