@cosmicdrift/kumiko-bundled-features 0.362.0 → 0.364.0

package/dist/config/write-helpers.d.ts

@@ -2,12 +2,14 @@ import type { SubjectId } from "@cosmicdrift/kumiko-framework/crypto";
 import type { DbConnection, TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import { type ConfigKeyDefinition, type ConfigScope, type Registry, type SessionUser, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { type KumikoError, type WriteFailure } from "@cosmicdrift/kumiko-framework/errors";
+import type { EnvelopeCipher } from "@cosmicdrift/kumiko-framework/secrets";
 export type ConfigRowLookup = {
     readonly id: string;
     readonly version: number;
     readonly value: string | null;
 };
 export declare function findConfigRow(db: DbConnection | TenantDb, key: string, tenantId: TenantId, userId: string | null): Promise<ConfigRowLookup | null>;
+export declare function configRowHoldsValue(row: ConfigRowLookup | null, keyDef: ConfigKeyDefinition | undefined, cipher: EnvelopeCipher | undefined, qualifiedKey: string, serializedValue: string): Promise<boolean>;
 export type PrepareConfigWriteArgs = {
     readonly registry: Registry;
     readonly user: SessionUser;

package/dist/config/write-helpers.js

@@ -6,6 +6,7 @@ import { ConfigScopes, extensionSelectorTargets, isEncryptedAtRest, SYSTEM_ROLE,
 import { AccessDeniedError, InternalError, NotFoundError, UnprocessableError, ValidationError, writeFailure, } from "@cosmicdrift/kumiko-framework/errors";
 import { assertUnreachable } from "@cosmicdrift/kumiko-framework/utils";
 import { ConfigErrors } from "./constants.js";
+import { decryptStoredValue } from "./resolver.js";
 import { configValuesTable } from "./table.js";
 // Locate an existing config_values row by the (key, tenant, user) triple —
 // the effective natural key. System-scope rows carry SYSTEM_TENANT_ID on
@@ -26,6 +27,24 @@ export async function findConfigRow(db, key, tenantId, userId) {
         value: row.value ?? null,
     };
 }
+// Idempotency check for declarative writers: does the stored row already hold
+// `serializedValue` (JSON of the plaintext)? Encrypted rows are decrypted
+// first, since their ciphertext differs on every encrypt.
+export async function configRowHoldsValue(row, keyDef, cipher, qualifiedKey, serializedValue) {
+    if (row?.value === null || row?.value === undefined)
+        return false;
+    if (!keyDef?.encrypted && !keyDef?.piiEncrypted)
+        return row.value === serializedValue;
+    if (!keyDef)
+        return false;
+    try {
+        return (await decryptStoredValue(row.value, keyDef, cipher, qualifiedKey)) === serializedValue;
+    }
+    catch {
+        // Unreadable (rotated key, missing cipher/KMS): the caller rewrites the row, which is the repair.
+        return false;
+    }
+}
 export function prepareConfigWrite(args) {
     const { registry, user, key, scope: requestedScope } = args;
     const keyDef = registry.getConfigKey(key);

package/dist/crypto-shredding/handlers/forget-subject.write.d.ts

@@ -48,4 +48,4 @@ export declare const forgetSubjectWrite: import("@cosmicdrift/kumiko-types/defin
     reason: z.ZodString;
 }, z.core.$strip>, {
     subjectKey: string;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

package/dist/crypto-shredding/handlers/forget-subject.write.js

@@ -1,6 +1,6 @@
 import { requestContext } from "@cosmicdrift/kumiko-framework/api";
 import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
-import { runInSavepointIfSupported } from "@cosmicdrift/kumiko-framework/bun-db";
+import { fetchOne, runInSavepointIfSupported, runnerCanBeginTransaction, transaction, } from "@cosmicdrift/kumiko-framework/bun-db";
 import { computeBlindIndex, configuredBlindIndexKey, configuredPiiSubjectKms, subjectIdSchema, subjectIdToKey, } from "@cosmicdrift/kumiko-framework/crypto";
 import { nullBlindIndexesForSubject, recordEventsOwnedExclusivelyByTenant, recordRowExistsInTenant, recordRowOwningTenantId, subjectRowExistsInTenant, } from "@cosmicdrift/kumiko-framework/db";
 import { defineWriteHandler, } from "@cosmicdrift/kumiko-framework/engine";
@@ -12,7 +12,7 @@ import * as z from "zod";
 import { resolveRetentionPolicyForTenant } from "../../data-retention/index.js";
 import { eraseNoteBodiesReachingSubject } from "../../notes-history-user-data/index.js";
 import { revokeAllPatTokensForUser } from "../../personal-access-tokens/index.js";
-import { USER_STATUS } from "../../user/index.js";
+import { USER_STATUS, userTable } from "../../user/index.js";
 import { denyIfTargetOutsideAdminTenant, isSystemAdminActor, updateUserLifecycle, } from "../../user-data-rights/index.js";
 import { CRYPTO_SHREDDING_AGGREGATE_TYPE, CRYPTO_SHREDDING_FEATURE_NAME, RECORD_ENTITY_NOT_REGISTERED, SUBJECT_FORGET_DENIED_EVENT_NAME, SUBJECT_FORGOTTEN_EVENT_NAME, TARGET_RECORD_NOT_ADMIN_TENANT, TARGET_RECORD_RETENTION_BLOCK_DELETE, TARGET_TENANT_NOT_ADMIN_TENANT, } from "../constants.js";
 export { subjectIdSchema };
@@ -241,22 +241,29 @@ async function sweepDerivedSubjectData(ctx, subject, subjectKey, crossTenantRunn
         return sweepErrorLabel(err);
     }
 }
-// Graceful fail: email-subscribers and other non-user entities may use
-// user-style subject keys without having an actual user row — the key erase is
-// the important part for GDPR compliance; the lifecycle update is best-effort for
-// real users. The savepoint confines the failure so the handler transaction
-// stays usable for the audit event.
-async function closeUserLoginDoorBestEffort(ctx, userId, lifecycleRunner) {
-    try {
-        await runInSavepointIfSupported(lifecycleRunner, async (userLifecycleRunner) => {
-            await updateUserLifecycle(userLifecycleRunner, userId, { status: USER_STATUS.Deleted });
-            if (ctx.registry.features.has("personal-access-tokens")) {
-                await revokeAllPatTokensForUser(userLifecycleRunner, userId);
-            }
-        });
+// Email subscribers and other non-user entities use user-style subject keys
+// without a read_users row — the key erase is the GDPR-relevant part, so no row
+// means nothing to close. For an existing row, failures propagate: the handler
+// throws and the retry re-runs the (idempotent) erase plus the door close. With
+// an outside-transaction runner that can open its own transaction, the door
+// closes there and stays committed when the handler throws afterwards (sweep
+// error). Otherwise a savepoint confines a failure to the handler transaction.
+async function closeUserLoginDoor(ctx, userId, outsideRunner, handlerTxRunner) {
+    const userRow = await fetchOne(handlerTxRunner, userTable, { id: userId });
+    // skip: no user row for this subject key (e.g. email subscribers); there is no door to close.
+    if (!userRow)
+        return;
+    const closeDoor = async (runner) => {
+        await updateUserLifecycle(runner, userId, { status: USER_STATUS.Deleted });
+        if (ctx.registry.features.has("personal-access-tokens")) {
+            await revokeAllPatTokensForUser(runner, userId);
+        }
+    };
+    if (outsideRunner && runnerCanBeginTransaction(outsideRunner)) {
+        await transaction(outsideRunner, closeDoor);
     }
-    catch {
-        // skip: no user row for this subject key (e.g. email subscribers); key erase and sweeps already ran.
+    else {
+        await runInSavepointIfSupported(handlerTxRunner, closeDoor);
     }
 }
 // Through the outside-transaction db when available, so the audit event commits
@@ -351,7 +358,6 @@ export const forgetSubjectWrite = defineWriteHandler({
             userId: event.user.id,
             eraseReason: event.payload.reason,
         });
-        const cleanupError = await sweepDerivedSubjectData(ctx, subject, subjectKey, ctx.db.unsafeRaw(), { requestId, erasedBy: event.user.id });
         // User subject: close the login door. DEK-erase makes the passwordHash
         // ciphertext unreadable, but status + PATs are standalone credentials —
         // the PAT resolver only checks revokedAt/expiresAt, NOT user.status
@@ -367,9 +373,13 @@ export const forgetSubjectWrite = defineWriteHandler({
         // crash recovery is safe. User-feature guard: without the user feature
         // read_users doesn't exist (crypto-only stack). Tenant subjects have no
         // credentials.
+        // Runs before the sweep and in its own transaction: a failing sweep rolls the
+        // handler transaction back, and the handler tx holds no lock on this user's
+        // read_users row yet (only read gates ran), so there is no lock conflict.
         if (raw.kind === "user" && ctx.registry.features.has("user")) {
-            await closeUserLoginDoorBestEffort(ctx, raw.userId, ctx.db.unsafeRaw());
+            await closeUserLoginDoor(ctx, raw.userId, ctx.dbOutsideTransaction?.unsafeRaw(), ctx.db.unsafeRaw());
         }
+        const cleanupError = await sweepDerivedSubjectData(ctx, subject, subjectKey, ctx.db.unsafeRaw(), { requestId, erasedBy: event.user.id });
         await appendSubjectForgotten(ctx, event, subjectAggregateId(raw), {
             subjectKey,
             reason: event.payload.reason,

package/dist/custom-fields/handlers/update-tenant-field.write.js

@@ -11,7 +11,6 @@ export function createUpdateTenantFieldHandler(opts = {}) {
         schema: updateFieldPayloadSchema,
         access: { roles: opts.roles ?? DEFAULT_FIELD_DEFINITION_WRITE_ROLES },
         description: "Replaces a tenant-owned custom-field definition with a complete new spec; serializedField.type may be omitted, in which case the stored type applies, and a different type is refused. Use it to relabel or re-constrain an existing field rather than to create or remove one.",
-        excludedFields: ["type"],
         handler: async (event, ctx) => {
             const payload = event.payload; // @cast-boundary engine-payload
             const tenantId = event.user.tenantId;

package/dist/custom-fields/lib/value-schema.js

@@ -1,4 +1,5 @@
 import { DEFAULT_CURRENCIES, fieldToZod, } from "@cosmicdrift/kumiko-framework/engine";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { SUPPORTED_FIELD_TYPES } from "../constants.js";
 // Builds a Zod schema that validates a custom-field VALUE against its
 // fieldDefinition. Reuses the framework's `fieldToZod` (Builder-Reuse /
@@ -29,10 +30,9 @@ const SUPPORTED_EMBEDDED_SUB_TYPES = new Set([
 // resulting schema validates the type-shape only, not the constraint.
 const CONSTRAINT_KEYS = ["required", "maxLength", "format", "default"];
 export function buildCustomFieldValueSchema(parsedField) {
-    if (!parsedField || typeof parsedField !== "object")
+    if (!isPlainObject(parsedField))
         return null;
-    const obj = parsedField;
-    const rawType = obj["type"];
+    const rawType = parsedField["type"];
     if (typeof rawType !== "string")
         return null;
     if (!SUPPORTED_TYPES_SET.has(rawType))
@@ -47,37 +47,36 @@ export function buildCustomFieldValueSchema(parsedField) {
     // drops everywhere else.
     let strippedSubSchema;
     if (rawType === "embedded") {
-        const schema = obj["schema"];
+        const schema = parsedField["schema"];
         if (!schema || typeof schema !== "object")
             return null;
         strippedSubSchema = {};
         for (const [subKey, sub] of Object.entries(schema)) {
-            if (!sub || typeof sub !== "object")
+            if (!isPlainObject(sub))
                 return null;
-            const subObj = sub;
-            const subType = subObj["type"];
+            const subType = sub["type"];
             if (typeof subType !== "string" || !SUPPORTED_EMBEDDED_SUB_TYPES.has(subType)) {
                 return null;
             }
-            const strippedSub = { ...subObj };
+            const strippedSub = { ...sub };
             for (const k of CONSTRAINT_KEYS)
                 delete strippedSub[k];
             strippedSubSchema[subKey] = strippedSub;
         }
     }
-    const fieldDef = { ...obj };
+    const fieldDef = { ...parsedField };
     for (const k of CONSTRAINT_KEYS)
         delete fieldDef[k];
     if (strippedSubSchema !== undefined)
         fieldDef["schema"] = strippedSubSchema;
     if (rawType === "enum") {
         fieldDef["type"] = "select";
-        fieldDef["options"] = obj["values"] ?? obj["options"] ?? [];
+        fieldDef["options"] = parsedField["values"] ?? parsedField["options"] ?? [];
     }
     // fieldToZod's money case validates `currency` against the passed list, not
     // a field-level key — so surface the field's own currency when it declares
     // one, else fall back to the framework defaults.
-    const currencies = typeof obj["currency"] === "string" ? [obj["currency"]] : DEFAULT_CURRENCIES;
+    const currencies = typeof parsedField["currency"] === "string" ? [parsedField["currency"]] : DEFAULT_CURRENCIES;
     // @cast-boundary serialized-field is the dehydrated r.field.X() output =
     // a FieldDefinition; fieldToZod reads only its type-specific keys (the
     // extra fieldAccess/retention/label keys are ignored).

package/dist/custom-fields/wire-user-data-rights.js

@@ -1,21 +1,22 @@
 // T1.5c — user-data-rights wiring for custom-fields.
 import { extractTableName } from "@cosmicdrift/kumiko-framework/db";
 import { EXT_USER_DATA } from "@cosmicdrift/kumiko-framework/engine";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { selectCustomFieldsHostRows } from "./db/queries/user-data-rights.js";
 function asCustomFieldsHostRow(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
+    if (!isPlainObject(value))
         return null;
-    if (!("id" in value) || typeof value.id !== "string")
+    const id = value["id"];
+    if (typeof id !== "string")
         return null;
-    const record = value;
-    const cf = record["custom_fields"] ?? record["customFields"];
+    const cf = value["custom_fields"] ?? value["customFields"];
     if (cf === undefined)
         return null;
     if (cf === null)
-        return { id: value.id, customFields: null };
+        return { id, customFields: null };
     if (!cf || typeof cf !== "object" || Array.isArray(cf))
         return null;
-    return { id: value.id, customFields: Object.fromEntries(Object.entries(cf)) };
+    return { id, customFields: Object.fromEntries(Object.entries(cf)) };
 }
 // fw#2914 — selectCustomFieldsHostRows runs raw SQL against a dynamic host
 // table name (opts.entityTable varies per call site), so it can't go through

package/dist/data-retention/index.d.ts

@@ -1,2 +1,3 @@
 export type { EffectiveRetentionPolicy, ResolveForTenantArgs, ResolveRetentionPolicyArgs, ResolveTenantPresetArgs, RetentionOverride, RetentionPreset, RetentionPresetKey, } from "./feature.js";
 export { createDataRetentionFeature, RETENTION_PRESETS, resolveRetentionPolicy, resolveRetentionPolicyForTenant, resolveTenantRetentionPreset, retentionOverrideSchema, SELECTABLE_RETENTION_PRESETS, tenantRetentionOverrideEntity, tenantRetentionOverrideTable, } from "./feature.js";
+export { computeCutoff, type Instant } from "./keep-for.js";

package/dist/data-retention/index.js

@@ -1 +1,2 @@
 export { createDataRetentionFeature, RETENTION_PRESETS, resolveRetentionPolicy, resolveRetentionPolicyForTenant, resolveTenantRetentionPreset, retentionOverrideSchema, SELECTABLE_RETENTION_PRESETS, tenantRetentionOverrideEntity, tenantRetentionOverrideTable, } from "./feature.js";
+export { computeCutoff } from "./keep-for.js";

package/dist/data-retention/run-retention-cleanup.js

@@ -43,6 +43,7 @@ import { createEventStoreExecutor, createTenantDb, nullBlindIndexesForSubject, W
 import { deleteStoredFileAndDerivatives } from "@cosmicdrift/kumiko-framework/derivatives";
 import { createSystemUser, entityHasAnonymizableSubjectField, } from "@cosmicdrift/kumiko-framework/engine";
 import { fileRefEntity, fileRefsTable, } from "@cosmicdrift/kumiko-framework/files";
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { runInSubTransaction } from "../shared/index.js";
 import { computeCutoff } from "./keep-for.js";
 import { resolveRetentionPolicyForTenant } from "./resolve-for-tenant.js";
@@ -219,10 +220,9 @@ function collectSingleFileHolders(registry) {
         const { singleFields } = planFileFields(entity.fields);
         if (singleFields.length === 0)
             continue;
-        const table = proj.table; // @cast-boundary column-presence probe
         holders.push({
             table: proj.table,
-            tableHasTenantId: table["tenantId"] !== undefined,
+            tableHasTenantId: propertyOf(proj.table, "tenantId") !== undefined,
             singleFields,
         });
     }
@@ -473,10 +473,9 @@ export async function runRetentionCleanup(args) {
         const entity = registry.getEntity(entityName);
         if (!entity)
             continue;
-        const table = proj.table; // @cast-boundary column-presence probe
         const declaredReference = policy.reference ?? DEFAULT_REFERENCE_FIELD;
         const referenceField = FRAMEWORK_REFERENCE_ALIAS[declaredReference] ?? declaredReference;
-        if (table[referenceField] === undefined) {
+        if (propertyOf(proj.table, referenceField) === undefined) {
             skipped.push({ entityName, reason: "missing_reference_column" });
             continue;
         }
@@ -485,7 +484,7 @@ export async function runRetentionCleanup(args) {
         // Tenant-Scope nur wenn die Tabelle eine tenantId-Spalte hat — identisch zu
         // soft-delete-cleanup. Ohne diesen Filter wuerde ein Tenant die Rows eines
         // anderen treffen.
-        if (table["tenantId"] !== undefined) {
+        if (propertyOf(proj.table, "tenantId") !== undefined) {
             where["tenantId"] = tenantId;
         }
         switch (policy.strategy) {
@@ -531,7 +530,8 @@ export async function runRetentionCleanup(args) {
                 break;
             }
             case "softDelete": {
-                if (table["isDeleted"] === undefined || table["deletedAt"] === undefined) {
+                if (propertyOf(proj.table, "isDeleted") === undefined ||
+                    propertyOf(proj.table, "deletedAt") === undefined) {
                     skipped.push({ entityName, reason: "missing_softdelete_columns" });
                     break;
                 }

package/dist/delivery/attachment-ref.d.ts

@@ -0,0 +1,41 @@
+import * as z from "zod";
+import type { FileAttachmentRef, InlineAttachmentRef, RenderedPdfAttachmentRef } from "../renderer-foundation/index.js";
+export type { FileAttachmentRef, InlineAttachmentRef, RenderedPdfAttachmentRef };
+export type EmailAttachmentRef = InlineAttachmentRef | FileAttachmentRef | RenderedPdfAttachmentRef;
+export declare const MAX_EMAIL_ATTACHMENTS = 20;
+export declare const MAX_RENDERED_PDF_VARIABLES_BYTES = 64000;
+export declare const DELIVERY_ENVELOPE_DATA_KEYS: readonly ["attachments", "from", "fromName", "replyTo", "headers", "unsubscribeUrl"];
+export declare function withoutDeliveryEnvelopeKeys(variables: Readonly<Record<string, unknown>>): Readonly<Record<string, unknown>>;
+export declare const inlineAttachmentRefSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"inline">;
+    cid: z.ZodString;
+    fileRefId: z.ZodString;
+}, z.core.$strict>;
+export declare const fileAttachmentRefSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"file">;
+    fileRefId: z.ZodString;
+    fileName: z.ZodString;
+}, z.core.$strict>;
+export declare const renderedPdfAttachmentRefSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"rendered-pdf">;
+    templateSlug: z.ZodString;
+    variables: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    fileName: z.ZodString;
+    locale: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const emailAttachmentRefSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"inline">;
+    cid: z.ZodString;
+    fileRefId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"file">;
+    fileRefId: z.ZodString;
+    fileName: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"rendered-pdf">;
+    templateSlug: z.ZodString;
+    variables: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    fileName: z.ZodString;
+    locale: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>], "kind">;
+export declare function toAttachmentRef(ref: EmailAttachmentRef): EmailAttachmentRef;

package/dist/delivery/attachment-ref.js

@@ -0,0 +1,78 @@
+import * as z from "zod";
+import { attachmentFileNameSchema } from "../shared/index.js";
+import { isDocumentResourceKey, templateSlugSchema } from "../template-resolver/index.js";
+export const MAX_EMAIL_ATTACHMENTS = 20;
+export const MAX_RENDERED_PDF_VARIABLES_BYTES = 64_000;
+// Channel-data keys that steer delivery itself (envelope, headers, attachments);
+// they are not document variables and must not be copied into attached PDF refs.
+export const DELIVERY_ENVELOPE_DATA_KEYS = [
+    "attachments",
+    "from",
+    "fromName",
+    "replyTo",
+    "headers",
+    "unsubscribeUrl",
+];
+const DELIVERY_ENVELOPE_DATA_KEY_SET = new Set(DELIVERY_ENVELOPE_DATA_KEYS);
+export function withoutDeliveryEnvelopeKeys(variables) {
+    return Object.fromEntries(Object.entries(variables).filter(([key]) => !DELIVERY_ENVELOPE_DATA_KEY_SET.has(key)));
+}
+const MAX_ID_LENGTH = 64;
+const fileRefIdSchema = z.string().min(1).max(MAX_ID_LENGTH);
+export const inlineAttachmentRefSchema = z
+    .object({
+    kind: z.literal("inline"),
+    cid: z.string().min(1).max(MAX_ID_LENGTH).refine(isDocumentResourceKey),
+    fileRefId: fileRefIdSchema,
+})
+    .strict();
+export const fileAttachmentRefSchema = z
+    .object({
+    kind: z.literal("file"),
+    fileRefId: fileRefIdSchema,
+    fileName: attachmentFileNameSchema,
+})
+    .strict();
+export const renderedPdfAttachmentRefSchema = z
+    .object({
+    kind: z.literal("rendered-pdf"),
+    templateSlug: templateSlugSchema,
+    variables: z
+        .record(z.string(), z.unknown())
+        .refine((value) => Buffer.byteLength(JSON.stringify(value)) <= MAX_RENDERED_PDF_VARIABLES_BYTES, {
+        message: `variables must not exceed ${MAX_RENDERED_PDF_VARIABLES_BYTES} bytes as JSON`,
+    }),
+    fileName: attachmentFileNameSchema.refine((name) => name.toLowerCase().endsWith(".pdf"), {
+        message: "file name must end with .pdf",
+    }),
+    locale: z
+        .string()
+        .min(2)
+        .max(8)
+        .regex(/^[a-z]{2}(-[a-z]{2})?$/i, "locale must be ISO 639-1 (e.g. de, en, en-us)")
+        .optional(),
+})
+    .strict();
+export const emailAttachmentRefSchema = z.discriminatedUnion("kind", [
+    inlineAttachmentRefSchema,
+    fileAttachmentRefSchema,
+    renderedPdfAttachmentRefSchema,
+]);
+// Rebuilds only the contract fields so bytes a caller attached to a ref object
+// can never ride into a job payload.
+export function toAttachmentRef(ref) {
+    switch (ref.kind) {
+        case "inline":
+            return { kind: "inline", cid: ref.cid, fileRefId: ref.fileRefId };
+        case "file":
+            return { kind: "file", fileRefId: ref.fileRefId, fileName: ref.fileName };
+        case "rendered-pdf":
+            return {
+                kind: "rendered-pdf",
+                templateSlug: ref.templateSlug,
+                variables: ref.variables,
+                fileName: ref.fileName,
+                ...(ref.locale !== undefined && { locale: ref.locale }),
+            };
+    }
+}

package/dist/delivery/channel-context.d.ts

@@ -1,6 +1,10 @@
 import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
-import { type DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import type { Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { type DbConnection, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { ConfigAccessor, Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { FileContext } from "@cosmicdrift/kumiko-framework/files";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
-import type { ChannelContext } from "./types.js";
-export declare function buildChannelContext(db: DbConnection, registry: Registry, sseBroker: SseBroker | undefined, tenantId: TenantId, secrets?: SecretsContext): ChannelContext;
+import { type MailPayload } from "../renderer-foundation/index.js";
+import type { ChannelContext, RenderedMail } from "./types.js";
+export declare function createTemplateMailRenderer(db: DbConnection | TenantDb, registry: Registry, tenantId: TenantId, config: ConfigAccessor | undefined): (payload: MailPayload) => Promise<RenderedMail>;
+export declare function createEmailAttachmentReader(db: DbConnection | TenantDb, registry: Registry, tenantId: TenantId, config: ConfigAccessor | undefined, filesForTenant: (tenantId: string) => FileContext | undefined): NonNullable<ChannelContext["readAttachment"]>;
+export declare function buildChannelContext(db: DbConnection, registry: Registry, sseBroker: SseBroker | undefined, tenantId: TenantId, secrets?: SecretsContext, tenantConfig?: ConfigAccessor, filesForTenant?: (tenantId: string) => FileContext | undefined): ChannelContext;

package/dist/delivery/channel-context.js

@@ -1,8 +1,100 @@
 import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+import { readFileRefContent } from "../file-foundation/index.js";
+import { collectRendererPlugins, createRendererFoundationApi, RendererError, } from "../renderer-foundation/index.js";
+import { FALLBACK_LOCALE } from "../template-resolver/index.js";
+export function createTemplateMailRenderer(db, registry, tenantId, config) {
+    return async (payload) => {
+        const plugin = createRendererFoundationApi(collectRendererPlugins(registry)).createRendererForTenant({ tenantId, kind: "mail" });
+        const response = await plugin.render({ kind: "mail", payload }, { db, registry, tenantId, ...(config !== undefined && { config }) });
+        if (response.kind !== "mail") {
+            throw new RendererError(`[delivery] renderer "${plugin.name}" answered a mail request with kind "${response.kind}"`, "other");
+        }
+        return {
+            subject: response.subject,
+            html: response.html,
+            text: response.text,
+            ...(response.previewText !== undefined && { previewText: response.previewText }),
+            ...(response.fromName !== undefined && { fromName: response.fromName }),
+            ...(response.replyTo !== undefined && { replyTo: response.replyTo }),
+            ...(response.attachments !== undefined && { attachments: response.attachments }),
+            ...(response.layout !== undefined && { layout: response.layout }),
+        };
+    };
+}
+const INLINE_IMAGE_CONTENT_TYPE_PREFIX = "image/";
+const PDF_CONTENT_TYPE = "application/pdf";
+// Renders at send time so the job payload carries variables, not bytes. A failure throws:
+// the send job retries instead of mailing without the document the recipient expects.
+function createPdfRenderer(db, registry, tenantId, config, filesForTenant) {
+    return async (ref) => {
+        const plugin = createRendererFoundationApi(collectRendererPlugins(registry)).createRendererForTenant({ tenantId, kind: "document-pdf" });
+        const response = await plugin.render({
+            kind: "document-pdf",
+            payload: {
+                slug: ref.templateSlug,
+                locale: ref.locale ?? FALLBACK_LOCALE,
+                variables: ref.variables,
+            },
+        }, { db, registry, tenantId, filesForTenant, ...(config !== undefined && { config }) });
+        if (response.kind !== "document-pdf") {
+            throw new RendererError(`[delivery] renderer "${plugin.name}" answered a document-pdf request with kind "${response.kind}"`, "other");
+        }
+        return { content: response.pdfBytes, contentType: PDF_CONTENT_TYPE };
+    };
+}
+// A decorative inline image (logo) that cannot be read must not fail the whole mail.
+async function readInlineImageOrNull(fileRefId, read) {
+    try {
+        return await read();
+    }
+    catch (err) {
+        createFallbackLogger("delivery").warn("inline image could not be read, sending without it", {
+            fileRefId,
+            errorName: err instanceof Error ? err.name : typeof err,
+        });
+        return null;
+    }
+}
+// Inline images and file attachments the renderer took from a template may come from the system
+// tenant (system template or tenant override of one). A file ref from notify data stays limited to
+// the job's own tenant, since a caller picks it. Inline content that is not an image is dropped, so
+// a swapped fileRef id cannot smuggle a document into the mail body.
+export function createEmailAttachmentReader(db, registry, tenantId, config, filesForTenant) {
+    const renderPdf = createPdfRenderer(db, registry, tenantId, config, filesForTenant);
+    return async (ref, origin = "message") => {
+        if (ref.kind === "rendered-pdf")
+            return renderPdf(ref);
+        const readRef = () => readFileRefContent({
+            db,
+            filesForTenant,
+            fileRefId: ref.fileRefId,
+            allowedTenantIds: ref.kind === "file" && origin === "message" ? [tenantId] : [tenantId, SYSTEM_TENANT_ID],
+        });
+        const found = ref.kind === "inline" ? await readInlineImageOrNull(ref.fileRefId, readRef) : await readRef();
+        if (found === null)
+            return null;
+        if (ref.kind === "inline" && !found.contentType.startsWith(INLINE_IMAGE_CONTENT_TYPE_PREFIX)) {
+            return null;
+        }
+        return { content: found.content, contentType: found.contentType };
+    };
+}
 // Build the per-tenant context a channel's resolve/render/send receives.
 // Shared by the synchronous delivery-service path and the async job handlers
 // (which pass sseBroker=undefined — only the inline inApp channel uses SSE,
 // and it never runs through a job).
-export function buildChannelContext(db, registry, sseBroker, tenantId, secrets) {
-    return { db: createTenantDb(db, tenantId), registry, sseBroker, tenantId, secrets };
+export function buildChannelContext(db, registry, sseBroker, tenantId, secrets, tenantConfig, filesForTenant) {
+    return {
+        db: createTenantDb(db, tenantId),
+        registry,
+        sseBroker,
+        tenantId,
+        secrets,
+        renderMail: createTemplateMailRenderer(db, registry, tenantId, tenantConfig),
+        ...(filesForTenant !== undefined && {
+            readAttachment: createEmailAttachmentReader(db, registry, tenantId, tenantConfig, filesForTenant),
+        }),
+    };
 }

package/dist/delivery/constants.d.ts

@@ -1,5 +1,6 @@
 import type { NotifyPriority } from "@cosmicdrift/kumiko-framework/engine";
 export declare const DELIVERY_CHANNEL_EXTENSION: "deliveryChannel";
+export declare const EMAIL_CHANNEL_NAME: "email";
 export { DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT, DELIVERY_ATTEMPT_EVENT, DELIVERY_CHANNEL_CELL_COMPONENT, DELIVERY_ERROR_CELL_COMPONENT, DELIVERY_FEATURE, DELIVERY_LOG_SCREEN_ID, DELIVERY_RESUBSCRIBE_PATH, DELIVERY_STATUS_CELL_COMPONENT, DELIVERY_TIME_CELL_COMPONENT, DELIVERY_TYPE_CELL_COMPONENT, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, DeliveryJobNames, DeliveryQueries, DeliveryStatus, type DeliveryStatusValue, } from "./public-names.js";
 export declare function deliveryIdempotencyRedisKey(tenantId: string, key: string): string;
 export declare const deliveryPriorityRank: Record<NotifyPriority, number>;

package/dist/delivery/constants.js

@@ -3,6 +3,7 @@ import { DELIVERY_FEATURE, DeliveryJobNames } from "./public-names.js";
 // Extension-point name for delivery-channel plugins (channel-email,
 // channel-in-app, channel-push, ...).
 export const DELIVERY_CHANNEL_EXTENSION = "deliveryChannel";
+export const EMAIL_CHANNEL_NAME = "email";
 export { DELIVERY_ATTEMPT_ADDRESS_ERASED_EVENT, DELIVERY_ATTEMPT_EVENT, DELIVERY_CHANNEL_CELL_COMPONENT, DELIVERY_ERROR_CELL_COMPONENT, DELIVERY_FEATURE, DELIVERY_LOG_SCREEN_ID, DELIVERY_RESUBSCRIBE_PATH, DELIVERY_STATUS_CELL_COMPONENT, DELIVERY_TIME_CELL_COMPONENT, DELIVERY_TYPE_CELL_COMPONENT, DELIVERY_UNSUBSCRIBE_PATH, DeliveryErrors, DeliveryHandlers, DeliveryJobNames, DeliveryQueries, DeliveryStatus, } from "./public-names.js";
 // Single source for claim (delivery-service) and terminal-failure release (jobs).
 export function deliveryIdempotencyRedisKey(tenantId, key) {

package/dist/delivery/delivery-service.d.ts

@@ -1,6 +1,7 @@
 import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import type { EscapeHatchAuditSink, NotifyJobDispatcher, Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { ConfigAccessor, EscapeHatchAuditSink, NotifyJobDispatcher, Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { FileContext } from "@cosmicdrift/kumiko-framework/files";
 import { type Logger } from "@cosmicdrift/kumiko-framework/logging";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import type { Redis } from "ioredis";
@@ -23,6 +24,8 @@ export type DeliveryServiceOptions = {
     readonly idempotencyRedis?: Redis;
     readonly jobRunner?: NotifyJobDispatcher;
     readonly secrets?: SecretsContext;
+    readonly filesForTenant?: (tenantId: string) => FileContext | undefined;
+    readonly tenantConfigFor?: (tenantId: TenantId) => ConfigAccessor;
     readonly escapeHatchAuditSink?: EscapeHatchAuditSink;
     readonly log?: Logger;
 };