@cosmicdrift/kumiko-bundled-features 0.392.2 → 0.394.0

package/dist/inbound-mail-foundation/handlers/list-accounts.query.js

@@ -3,40 +3,74 @@
 // billing-foundation list-subscriptions pattern.
 //
 // **Scope visibility:** authorized users can see shared mailboxes
-// (ownerUserId=null); personal mailboxes are visible only to their owner,
-// TenantAdmin, or SystemAdmin for compliance access. Filtering runs in memory
+// (ownerUserId=null); personal mailboxes are listed (metadata only) for their owner and the
+// admin roles, but only the owner sees their quarantine. Filtering runs in memory
 // after the tenant-scoped select because a tenant has only a single- to
 // double-digit number of connected mailboxes.
 import { configuredPiiSubjectKms, decryptPiiFieldValues, } from "@cosmicdrift/kumiko-framework/crypto";
 import { MAX_LIST_LIMIT } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
+import { IMAP_PROVIDER_KEY, InboundMailAccountStatuses, InboundMailAuthMethods, MailAccountReactivationPaths, } from "../constants.js";
 import { MAIL_ACCOUNT_PII_FIELDS } from "../entities.js";
 import { mailAccountsProjectionTable } from "../projection.js";
-import { isVisibleToCaller } from "./scope-visibility.js";
+import { quarantineTable } from "../quarantine-entities.js";
+import { isAccountListableBy, mayManageQuarantine, mayReactivateMailbox, } from "./scope-visibility.js";
+const REACTIVATABLE_STATUSES = new Set([
+    InboundMailAccountStatuses.disconnected,
+    InboundMailAccountStatuses.authError,
+]);
+// Null where no way back exists for this caller, so no row action leads into a refusal.
+function reactivationPathOf(row, user, adminRoles) {
+    if (!REACTIVATABLE_STATUSES.has(row["status"]))
+        return null;
+    if (!mayReactivateMailbox(row["ownerUserId"], user, adminRoles))
+        return null;
+    if (row["authMethod"] === InboundMailAuthMethods.oauth)
+        return MailAccountReactivationPaths.oauthFlow;
+    const isPasswordImap = row["provider"] === IMAP_PROVIDER_KEY && row["authMethod"] === InboundMailAuthMethods.password;
+    return isPasswordImap ? MailAccountReactivationPaths.passwordForm : null;
+}
 // The projectionList screen always sends `limit`; unknown keys stay rejected.
 const listAccountsSchema = z
     .object({ limit: z.number().int().min(1).max(MAX_LIST_LIMIT).default(MAX_LIST_LIMIT) })
     .strict();
-export const listAccountsQuery = {
-    name: "account:list",
-    schema: listAccountsSchema,
-    access: { roles: ["SystemAdmin", "TenantAdmin", "User"] },
-    description: "Lists the connected mailboxes of the caller's tenant with the mailbox address decrypted, hiding personal mailboxes the caller neither owns nor administers; use it for the mail connect and settings views.",
-    handler: async (query, ctx) => {
-        const { limit } = listAccountsSchema.parse(query.payload);
-        const allRows = await ctx.db.selectMany(mailAccountsProjectionTable, {
-            tenantId: ctx.user.tenantId,
-        });
-        const rows = allRows
-            .filter((row) => isVisibleToCaller(row, ctx.user))
-            .sort((a, b) => String(a["id"]).localeCompare(String(b["id"])))
-            .slice(0, limit);
-        const piiKms = configuredPiiSubjectKms();
-        if (!piiKms)
-            return { rows };
-        const decryptedRows = await Promise.all(rows.map((row) => decryptPiiFieldValues(row, MAIL_ACCOUNT_PII_FIELDS, piiKms, {
-            requestId: `inbound-mail-foundation:list-accounts:${ctx.user.tenantId}`,
-        })));
-        return { rows: decryptedRows };
-    },
-};
+export function createListAccountsQuery({ memberRoles, adminRoles, }) {
+    return {
+        name: "account:list",
+        schema: listAccountsSchema,
+        access: { roles: [...memberRoles] },
+        description: "Lists the connected mailboxes of the caller's tenant with the mailbox address decrypted, hiding personal mailboxes the caller neither owns nor administers and the quarantine of personal mailboxes the caller does not own; use it for the mail connect and settings views.",
+        handler: async (query, ctx) => {
+            const { limit } = listAccountsSchema.parse(query.payload);
+            const allRows = await ctx.db.selectMany(mailAccountsProjectionTable, {
+                tenantId: ctx.user.tenantId,
+            });
+            const rows = allRows
+                .filter((row) => isAccountListableBy(row, ctx.user, adminRoles))
+                .sort((a, b) => String(a["id"]).localeCompare(String(b["id"])))
+                .slice(0, limit);
+            // One grouped count for all mailboxes instead of a query per row.
+            const openQuarantine = await ctx.db.aggregate(quarantineTable, { measure: { fn: "count" }, groupBy: [{ field: "accountId" }] }, { acknowledgedAt: null });
+            const quarantinedCountOf = new Map(openQuarantine.map((group) => [String(group.keys[0]), group.value ?? 0]));
+            // The screen's row condition cannot compare a count or combine fields, so it gets booleans.
+            const withQuarantine = (row) => {
+                const owner = row["ownerUserId"];
+                const mayManage = mayManageQuarantine(typeof owner === "string" && owner !== "" ? owner : null, ctx.user, adminRoles);
+                const quarantinedCount = mayManage ? (quarantinedCountOf.get(String(row["id"])) ?? 0) : 0;
+                return {
+                    ...row,
+                    quarantinedCount,
+                    hasOpenQuarantine: quarantinedCount > 0,
+                    reactivateVia: reactivationPathOf(row, ctx.user, adminRoles),
+                };
+            };
+            const piiKms = configuredPiiSubjectKms();
+            if (!piiKms)
+                return { rows: rows.map(withQuarantine) };
+            const decryptedRows = await Promise.all(rows.map((row) => decryptPiiFieldValues(row, MAIL_ACCOUNT_PII_FIELDS, piiKms, {
+                requestId: `inbound-mail-foundation:list-accounts:${ctx.user.tenantId}`,
+            })));
+            return { rows: decryptedRows.map(withQuarantine) };
+        },
+    };
+}

package/dist/inbound-mail-foundation/handlers/list-messages.query.d.ts

@@ -1,2 +1,3 @@
 import type { QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
-export declare const listMessagesQuery: QueryHandlerDef;
+import type { InboundMailRoles } from "../mail-roles.ts";
+export declare function createListMessagesQuery({ memberRoles }: InboundMailRoles): QueryHandlerDef;

package/dist/inbound-mail-foundation/handlers/list-messages.query.js

@@ -9,9 +9,20 @@
 // compatibly without breaking the QN.
 import { configuredPiiSubjectKms, decryptPiiFieldValues, } from "@cosmicdrift/kumiko-framework/crypto";
 import * as z from "zod";
-import { INBOUND_MESSAGE_PII_FIELDS } from "../entities.js";
+import { INBOUND_MESSAGE_PII_FIELDS, inboundMessageEntity } from "../entities.js";
 import { inboundMessagesProjectionTable } from "../projection.js";
 import { isVisibleToCaller } from "./scope-visibility.js";
+// The full text is delivered only by message:content; selecting it here would also decrypt it.
+const LIST_MESSAGE_COLUMNS = [
+    "id",
+    "tenantId",
+    "version",
+    "insertedAt",
+    "modifiedAt",
+    "insertedById",
+    "modifiedById",
+    ...Object.keys(inboundMessageEntity.fields).filter((name) => name !== "bodyText"),
+];
 const listMessagesSchema = z
     .object({
     accountId: z.uuid().optional(),
@@ -19,31 +30,34 @@ const listMessagesSchema = z
     scope: z.string().min(1).max(200).optional(),
 })
     .strict();
-export const listMessagesQuery = {
-    name: "message:list",
-    schema: listMessagesSchema,
-    access: { roles: ["SystemAdmin", "TenantAdmin", "User"] },
-    description: "Lists received mail of the caller's tenant with sender, recipients, subject and snippet decrypted, optionally narrowed to one account, thread or folder scope and hiding messages of personal mailboxes the caller neither owns nor administers; use it to read an inbox or a conversation.",
-    handler: async (query, ctx) => {
-        // @cast-boundary engine-payload — dispatcher-zod-validated payload
-        const payload = query.payload;
-        const filter = { tenantId: ctx.user.tenantId };
-        if (payload.accountId)
-            filter["accountId"] = payload.accountId;
-        if (payload.threadKey)
-            filter["threadKey"] = payload.threadKey;
-        if (payload.scope)
-            filter["scope"] = payload.scope;
-        const allRows = await ctx.db.selectMany(inboundMessagesProjectionTable, filter);
-        // Scope visibility: messages in personal mailboxes are visible only to the
-        // owner or TenantAdmin/SystemAdmin.
-        const rows = allRows.filter((row) => isVisibleToCaller(row, ctx.user));
-        const piiKms = configuredPiiSubjectKms();
-        if (!piiKms)
-            return { rows };
-        const decryptedRows = await Promise.all(rows.map((row) => decryptPiiFieldValues(row, INBOUND_MESSAGE_PII_FIELDS, piiKms, {
-            requestId: `inbound-mail-foundation:list-messages:${ctx.user.tenantId}`,
-        })));
-        return { rows: decryptedRows };
-    },
-};
+export function createListMessagesQuery({ memberRoles }) {
+    return {
+        name: "message:list",
+        schema: listMessagesSchema,
+        access: { roles: [...memberRoles] },
+        description: "Lists received mail of the caller's tenant with sender, recipients, subject and snippet decrypted, optionally narrowed to one account, thread or folder scope and hiding messages of personal mailboxes the caller does not own; use it to read an inbox or a conversation.",
+        handler: async (query, ctx) => {
+            // @cast-boundary engine-payload — dispatcher-zod-validated payload
+            const payload = query.payload;
+            const filter = { tenantId: ctx.user.tenantId };
+            if (payload.accountId)
+                filter["accountId"] = payload.accountId;
+            if (payload.threadKey)
+                filter["threadKey"] = payload.threadKey;
+            if (payload.scope)
+                filter["scope"] = payload.scope;
+            const allRows = await ctx.db.selectMany(inboundMessagesProjectionTable, filter, {
+                fields: LIST_MESSAGE_COLUMNS,
+            });
+            // Scope visibility: messages in personal mailboxes are visible only to the owner.
+            const rows = allRows.filter((row) => isVisibleToCaller(row, ctx.user));
+            const piiKms = configuredPiiSubjectKms();
+            if (!piiKms)
+                return { rows };
+            const decryptedRows = await Promise.all(rows.map((row) => decryptPiiFieldValues(row, INBOUND_MESSAGE_PII_FIELDS, piiKms, {
+                requestId: `inbound-mail-foundation:list-messages:${ctx.user.tenantId}`,
+            })));
+            return { rows: decryptedRows };
+        },
+    };
+}

package/dist/inbound-mail-foundation/handlers/list-quarantine.query.d.ts

@@ -0,0 +1,3 @@
+import { type QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import type { InboundMailRoles } from "../mail-roles.ts";
+export declare function createListQuarantineQuery({ memberRoles, adminRoles, }: InboundMailRoles): QueryHandlerDef;

package/dist/inbound-mail-foundation/handlers/list-quarantine.query.js

@@ -0,0 +1,75 @@
+// quarantine:list — open quarantine entries with the sender and subject of the header-only import
+// (looked up by the deterministic message aggregate id; null when the provider gave no headers).
+import { configuredPiiSubjectKms, decryptPiiFieldValues, } from "@cosmicdrift/kumiko-framework/crypto";
+import { MAX_LIST_LIMIT } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { inboundMessageAggregateId } from "../aggregate-id.js";
+import { INBOUND_MESSAGE_PII_FIELDS } from "../entities.js";
+import { inboundMessagesProjectionTable, mailAccountsProjectionTable } from "../projection.js";
+import { quarantineTable } from "../quarantine-entities.js";
+import { mayManageQuarantine } from "./scope-visibility.js";
+// The projectionList screen always sends `limit`; unknown keys stay rejected.
+const listQuarantineSchema = z
+    .object({
+    accountId: z.uuid().optional(),
+    limit: z.number().int().min(1).max(MAX_LIST_LIMIT).default(MAX_LIST_LIMIT),
+})
+    .strict();
+function textOrNull(value) {
+    return typeof value === "string" ? value : null;
+}
+export function createListQuarantineQuery({ memberRoles, adminRoles, }) {
+    return {
+        name: "quarantine:list",
+        schema: listQuarantineSchema,
+        access: { roles: [...memberRoles] },
+        agent: { expose: false },
+        description: "Lists the open quarantine entries (mails the import could not take) of the mailboxes the caller may manage, newest first, with reason, retry state and the sender and subject of the header-only import when there is one; use it to review and retry quarantined mails.",
+        handler: async (query, ctx) => {
+            const { accountId, limit } = listQuarantineSchema.parse(query.payload);
+            const accounts = await ctx.db.selectMany(mailAccountsProjectionTable, {
+                tenantId: ctx.user.tenantId,
+            });
+            const managed = accounts.filter((row) => (accountId === undefined || row["id"] === accountId) &&
+                mayManageQuarantine(textOrNull(row["ownerUserId"]) || null, ctx.user, adminRoles));
+            if (managed.length === 0)
+                return { rows: [] };
+            const accountName = new Map(managed.map((row) => [String(row["id"]), row["displayName"]]));
+            const entries = await ctx.db.selectMany(quarantineTable, { accountId: { in: [...accountName.keys()] }, acknowledgedAt: null }, { limit, orderBy: [{ col: "quarantinedAt", direction: "desc" }, { col: "id" }] });
+            if (entries.length === 0)
+                return { rows: [] };
+            const headers = await ctx.db.selectMany(inboundMessagesProjectionTable, {
+                id: {
+                    in: entries.map((entry) => inboundMessageAggregateId(String(entry["accountId"]), String(entry["providerMessageId"]))),
+                },
+            }, { fields: ["id", "from", "subject"] });
+            const piiKms = configuredPiiSubjectKms();
+            const readableHeaders = new Map();
+            for (const header of headers) {
+                const readable = piiKms
+                    ? await decryptPiiFieldValues(header, INBOUND_MESSAGE_PII_FIELDS, piiKms, {
+                        requestId: `inbound-mail-foundation:list-quarantine:${ctx.user.tenantId}`,
+                    })
+                    : header;
+                readableHeaders.set(String(header["id"]), readable);
+            }
+            return {
+                rows: entries.map((entry) => {
+                    const accountIdOfEntry = String(entry["accountId"]);
+                    const header = readableHeaders.get(inboundMessageAggregateId(accountIdOfEntry, String(entry["providerMessageId"])));
+                    return {
+                        id: entry["id"],
+                        accountId: accountIdOfEntry,
+                        accountName: accountName.get(accountIdOfEntry) ?? null,
+                        providerMessageId: entry["providerMessageId"],
+                        reason: entry["reasonCode"],
+                        quarantinedAt: entry["quarantinedAt"],
+                        retryRequestedAt: entry["retryRequestedAt"] ?? null,
+                        sender: textOrNull(header?.["from"]),
+                        subject: textOrNull(header?.["subject"]),
+                    };
+                }),
+            };
+        },
+    };
+}

package/dist/inbound-mail-foundation/handlers/mark-credential-stored.write.d.ts

@@ -0,0 +1,7 @@
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+export declare const CREDENTIAL_STORED_AUDIT_REASON = "credential_stored";
+export declare const markCredentialStoredSchema: z.ZodObject<{
+    accountId: z.ZodUUID;
+}, z.core.$strip>;
+export declare const markCredentialStoredHandler: WriteHandlerDef;

package/dist/inbound-mail-foundation/handlers/mark-credential-stored.write.js

@@ -0,0 +1,38 @@
+// mark-credential-stored — the OAuth callback stores the refresh token after the account commit,
+// so the wake from connect-account can fire before the credential exists. This re-emits the
+// unchanged active state with a fresh event, which the wake consumer turns into a sync.
+import { failNotFound } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { InboundMailAccountStatuses } from "../constants.js";
+import { MAIL_ACCOUNT_AGGREGATE_TYPE, MAIL_ACCOUNT_UPDATED_EVENT_QN, } from "../events.js";
+import { loadCurrentMailAccountPayload } from "./account-state.js";
+export const CREDENTIAL_STORED_AUDIT_REASON = "credential_stored";
+export const markCredentialStoredSchema = z.object({ accountId: z.uuid() });
+export const markCredentialStoredHandler = {
+    name: "mark-credential-stored",
+    schema: markCredentialStoredSchema,
+    access: { roles: ["SystemAdmin"] },
+    agent: { expose: false },
+    description: "Signals that the credential of an active mailbox was stored after the account was created, so the first sync can start right away.",
+    handler: async (event, ctx) => {
+        const payload = markCredentialStoredSchema.parse(event.payload);
+        const current = await loadCurrentMailAccountPayload(ctx, payload.accountId);
+        if (!current)
+            return failNotFound("mail-account", payload.accountId);
+        if (current.status !== InboundMailAccountStatuses.active) {
+            return { isSuccess: true, data: { accountId: payload.accountId, marked: false } };
+        }
+        const headers = {
+            providerName: current.provider,
+            reason: CREDENTIAL_STORED_AUDIT_REASON,
+        };
+        await ctx.events.unsafeAppend({
+            aggregateId: payload.accountId,
+            aggregateType: MAIL_ACCOUNT_AGGREGATE_TYPE,
+            type: MAIL_ACCOUNT_UPDATED_EVENT_QN,
+            payload: current,
+            headers,
+        });
+        return { isSuccess: true, data: { accountId: payload.accountId, marked: true } };
+    },
+};

package/dist/inbound-mail-foundation/handlers/message-content.d.ts

@@ -0,0 +1,70 @@
+import type { HandlerContext, Registry } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { type InboundContentState } from "../events.ts";
+import type { RawInboundAttachment, SkippedInboundAttachment } from "../types.ts";
+export declare const inboundContentPayloadShape: {
+    bodyText: z.ZodDefault<z.ZodString>;
+    bodyTextTruncated: z.ZodDefault<z.ZodBoolean>;
+    rawMime: z.ZodOptional<z.ZodInstanceOf<Uint8Array<ArrayBuffer>>>;
+    bodyHtml: z.ZodOptional<z.ZodString>;
+    attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        fileName: z.ZodString;
+        mimeType: z.ZodString;
+        data: z.ZodInstanceOf<Uint8Array<ArrayBuffer>>;
+    }, z.core.$strip>>>;
+    skippedAttachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        mimeType: z.ZodString;
+        size: z.ZodNumber;
+        reason: z.ZodEnum<{
+            mail_too_large: "mail_too_large";
+            nesting_too_deep: "nesting_too_deep";
+            no_file_storage: "no_file_storage";
+            rejected: "rejected";
+            too_large: "too_large";
+        }>;
+    }, z.core.$strip>>>;
+};
+export type InboundContentInput = {
+    readonly accountId: string;
+    readonly messageAggId: string;
+    /** From the app's storeBody hook; wins over the default storage. */
+    readonly bodyRef: string;
+    readonly rawMime?: Uint8Array | undefined;
+    readonly bodyHtml?: string | undefined;
+    readonly attachments?: readonly RawInboundAttachment[] | undefined;
+    readonly skippedAttachments?: readonly SkippedInboundAttachment[] | undefined;
+};
+export type StoredInboundContent = {
+    readonly bodyRef: string;
+    readonly attachmentFileIds: string[];
+    readonly skippedAttachments: SkippedInboundAttachment[];
+    /** "unavailable" when something had to be stored but the dispatcher has no file storage. */
+    readonly contentStorage: "stored" | "unavailable";
+};
+type ContentContext = Pick<HandlerContext, "db" | "services" | "registry" | "user">;
+export declare function inboundMessageBodyKey(tenantId: string, accountId: string, messageAggId: string, extension: "eml" | "html"): string;
+export type OriginalToStore = {
+    readonly data: Uint8Array;
+    readonly extension: "eml" | "html";
+    readonly mimeType: string;
+};
+export declare function originalOf(input: InboundContentInput): OriginalToStore | undefined;
+export declare function inboundAttachmentMaxSize(registry: Registry): number;
+/** Binds an attachment fileRef to the mail row, so the file guard uses the mail's visibility. */
+export declare function inboundAttachmentTarget(messageAggId: string): {
+    readonly entityType: "inbound-message";
+    readonly entityId: string;
+    readonly fieldName: "attachmentFileIds";
+};
+export declare function needsFileStorage(input: InboundContentInput): boolean;
+/** What a dispatcher without file storage makes of the content: nothing is stored, attachments are skipped. */
+export declare function contentWithoutFileStorage(input: InboundContentInput): StoredInboundContent;
+export declare function storeInboundMessageContent(ctx: ContentContext, input: InboundContentInput): Promise<StoredInboundContent>;
+export declare const MESSAGE_LOCK_NAMESPACE = 1768844643;
+export declare function encryptMessageBodyText(tenantId: string, messageAggId: string, bodyText: string): Promise<string>;
+export declare function contentStateOf(args: {
+    readonly bodyText: string;
+    readonly hasOriginal: boolean;
+    readonly contentStorage: StoredInboundContent["contentStorage"];
+}): InboundContentState;
+export {};

package/dist/inbound-mail-foundation/handlers/message-content.js

@@ -0,0 +1,137 @@
+// Content persistence shared by ingest-message and attach-message-content: the original
+// message and the attachments go to file storage, the event only carries references.
+import { configuredPiiSubjectKms, encryptPiiFieldValues, } from "@cosmicdrift/kumiko-framework/crypto";
+import { configuredMaxUploadBytes, createFileRefFromBytes, } from "@cosmicdrift/kumiko-framework/files";
+import * as z from "zod";
+import { INBOUND_MESSAGE_PII_FIELDS, inboundMessageEntity } from "../entities.js";
+import { INBOUND_MESSAGE_AGGREGATE_TYPE, skippedAttachmentSchema, } from "../events.js";
+import { INBOUND_ATTACHMENT_MAX_BYTES, INBOUND_BODY_HTML_MAX_CHARS, INBOUND_BODY_TEXT_MAX_CHARS, INBOUND_RAW_MIME_MAX_BYTES, INBOUND_SKIPPED_ATTACHMENTS_MAX_COUNT, } from "../normalize-inbound-message.js";
+// Bytes only travel in-process (system dispatch); no JSON request can carry a Uint8Array.
+export const inboundContentPayloadShape = {
+    bodyText: z.string().max(INBOUND_BODY_TEXT_MAX_CHARS).default(""),
+    bodyTextTruncated: z.boolean().default(false),
+    rawMime: z
+        .instanceof(Uint8Array)
+        .refine((bytes) => bytes.byteLength <= INBOUND_RAW_MIME_MAX_BYTES)
+        .optional(),
+    bodyHtml: z.string().max(INBOUND_BODY_HTML_MAX_CHARS).optional(),
+    attachments: z
+        .array(z.object({
+        fileName: z.string().max(255),
+        mimeType: z.string().max(255),
+        data: z.instanceof(Uint8Array),
+    }))
+        .max(50)
+        .optional(),
+    skippedAttachments: z.array(skippedAttachmentSchema).max(200).optional(),
+};
+// Deterministic, so a re-ingest after a rollback overwrites the same object instead of orphaning one.
+// Same keyspace the retention sweep deletes from (createFileProviderForTenant).
+export function inboundMessageBodyKey(tenantId, accountId, messageAggId, extension) {
+    return `${tenantId}/inbound-mail/${accountId}/${messageAggId}.${extension}`;
+}
+export function originalOf(input) {
+    if (input.rawMime !== undefined) {
+        return { data: input.rawMime, extension: "eml", mimeType: "message/rfc822" };
+    }
+    if (input.bodyHtml === undefined)
+        return undefined;
+    return {
+        data: new TextEncoder().encode(input.bodyHtml),
+        extension: "html",
+        mimeType: "text/html",
+    };
+}
+// The mail size limit is the cap; an app that configured a smaller upload limit keeps it, but the
+// 10 MB default of createFileRefFromBytes must not cut a 25 MB mail attachment that was accepted above.
+export function inboundAttachmentMaxSize(registry) {
+    return Math.min(INBOUND_ATTACHMENT_MAX_BYTES, configuredMaxUploadBytes(registry) ?? INBOUND_ATTACHMENT_MAX_BYTES);
+}
+/** Binds an attachment fileRef to the mail row, so the file guard uses the mail's visibility. */
+export function inboundAttachmentTarget(messageAggId) {
+    return {
+        entityType: INBOUND_MESSAGE_AGGREGATE_TYPE,
+        entityId: messageAggId,
+        fieldName: "attachmentFileIds",
+    };
+}
+export function needsFileStorage(input) {
+    const hasOriginal = input.rawMime !== undefined || input.bodyHtml !== undefined;
+    return (input.attachments ?? []).length > 0 || (input.bodyRef === "" && hasOriginal);
+}
+/** What a dispatcher without file storage makes of the content: nothing is stored, attachments are skipped. */
+export function contentWithoutFileStorage(input) {
+    const skipped = [...(input.skippedAttachments ?? [])];
+    for (const attachment of input.attachments ?? []) {
+        skipped.push({
+            mimeType: attachment.mimeType,
+            size: attachment.data.byteLength,
+            reason: "no_file_storage",
+        });
+    }
+    return {
+        bodyRef: input.bodyRef,
+        attachmentFileIds: [],
+        skippedAttachments: skipped.slice(0, INBOUND_SKIPPED_ATTACHMENTS_MAX_COUNT),
+        contentStorage: needsFileStorage(input) ? "unavailable" : "stored",
+    };
+}
+async function storeOriginal(files, tenantId, input) {
+    const original = originalOf(input);
+    if (!original)
+        return "";
+    const key = inboundMessageBodyKey(tenantId, input.accountId, input.messageAggId, original.extension);
+    await files.ref(key).write(original.data, original.mimeType);
+    return key;
+}
+// Nested dispatches (an app handler calling ingest-message) have no pre-transaction phase, so the
+// bytes are written here, inside the caller's transaction.
+export async function storeInboundMessageContent(ctx, input) {
+    const { files } = ctx.services;
+    if (!files)
+        return contentWithoutFileStorage(input);
+    const skipped = [...(input.skippedAttachments ?? [])];
+    const bodyRef = input.bodyRef !== "" ? input.bodyRef : await storeOriginal(files, ctx.user.tenantId, input);
+    const attachmentFileIds = [];
+    const maxSize = inboundAttachmentMaxSize(ctx.registry);
+    for (const attachment of input.attachments ?? []) {
+        const created = await createFileRefFromBytes(ctx, {
+            fileName: attachment.fileName,
+            mimeType: attachment.mimeType,
+            data: attachment.data,
+            attachTo: inboundAttachmentTarget(input.messageAggId),
+            maxSize,
+        });
+        if (created.isSuccess) {
+            attachmentFileIds.push(created.data.id);
+        }
+        else {
+            skipped.push({
+                mimeType: attachment.mimeType,
+                size: attachment.data.byteLength,
+                reason: "rejected",
+            });
+        }
+    }
+    return {
+        bodyRef,
+        attachmentFileIds,
+        skippedAttachments: skipped.slice(0, INBOUND_SKIPPED_ATTACHMENTS_MAX_COUNT),
+        contentStorage: "stored",
+    };
+}
+// 'inmc': serializes ingest and content attachment per message; disjoint from the thread-rollup namespace.
+export const MESSAGE_LOCK_NAMESPACE = 0x696e6d63;
+// Encrypts a single message PII field outside the batch encryption of ingest-message.
+export async function encryptMessageBodyText(tenantId, messageAggId, bodyText) {
+    const piiKms = configuredPiiSubjectKms();
+    if (!piiKms)
+        return bodyText;
+    const encrypted = await encryptPiiFieldValues({ tenantId, bodyText }, inboundMessageEntity, INBOUND_MESSAGE_PII_FIELDS, piiKms, { requestId: `inbound-mail-foundation:message-content:${messageAggId}`, tenantId }, { tenantId, entityName: INBOUND_MESSAGE_AGGREGATE_TYPE });
+    return encrypted.bodyText;
+}
+export function contentStateOf(args) {
+    if (args.contentStorage === "unavailable")
+        return "unavailable";
+    return args.bodyText.length > 0 || args.hasOriginal ? "complete" : "snippet";
+}

package/dist/inbound-mail-foundation/handlers/message-content.query.d.ts

@@ -0,0 +1,19 @@
+import type { HandlerContext, QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { type InboundContentState, type InboundContentUnavailableReason } from "../events.ts";
+import type { InboundMailRoles } from "../mail-roles.ts";
+import { type SenderAuthentication } from "../sender-auth.ts";
+import type { SkippedInboundAttachment } from "../types.ts";
+export type InboundMessageContent = {
+    readonly messageId: string;
+    readonly bodyText: string;
+    readonly bodyTextTruncated: boolean;
+    readonly bodyRef: string;
+    readonly attachmentFileIds: readonly string[];
+    readonly skippedAttachments: readonly SkippedInboundAttachment[];
+    readonly contentState: InboundContentState;
+    readonly contentUnavailableReason: InboundContentUnavailableReason | null;
+    /** null = no trustworthy statement; see isSenderAuthenticated. */
+    readonly senderAuthentication: SenderAuthentication | null;
+};
+export declare function loadInboundMessageContent(ctx: Pick<HandlerContext, "db" | "user">, messageId: string): Promise<InboundMessageContent | null>;
+export declare function createMessageContentQuery({ memberRoles }: InboundMailRoles): QueryHandlerDef;

package/dist/inbound-mail-foundation/handlers/message-content.query.js

@@ -0,0 +1,59 @@
+// message:content — the decrypted full text, attachment ids and content state of one message.
+// message:list deliberately omits all of it so inbox lists stay small.
+import { configuredPiiSubjectKms, decryptPiiFieldValues, } from "@cosmicdrift/kumiko-framework/crypto";
+import { parseJsonOrThrow } from "@cosmicdrift/kumiko-framework/utils";
+import * as z from "zod";
+import { INBOUND_MESSAGE_PII_FIELDS } from "../entities.js";
+import { INBOUND_CONTENT_STATES, INBOUND_CONTENT_UNAVAILABLE_REASONS, skippedAttachmentSchema, } from "../events.js";
+import { inboundMessagesProjectionTable } from "../projection.js";
+import { senderAuthenticationFieldSchema } from "../sender-auth.js";
+import { isVisibleToCaller } from "./scope-visibility.js";
+const messageContentSchema = z.object({ messageId: z.uuid() }).strict();
+const fileIdsSchema = z.array(z.uuid());
+const skippedListSchema = z.array(skippedAttachmentSchema);
+// Columns hold JSON text (nullable JSON stays text); rows from before the columns read as empty.
+function parseJsonColumn(raw, schema, fallback) {
+    if (typeof raw !== "string" || raw === "")
+        return fallback;
+    return schema.parse(parseJsonOrThrow(raw, "inbound message content column"));
+}
+function contentStateOfRow(raw) {
+    return INBOUND_CONTENT_STATES.find((state) => state === raw) ?? "snippet";
+}
+// Same visibility and decryption as the query, for server-side consumers (apps).
+export async function loadInboundMessageContent(ctx, messageId) {
+    const row = await ctx.db.fetchOne(inboundMessagesProjectionTable, { id: messageId });
+    if (!row || !isVisibleToCaller(row, ctx.user))
+        return null;
+    const piiKms = configuredPiiSubjectKms();
+    const readable = piiKms
+        ? await decryptPiiFieldValues(row, INBOUND_MESSAGE_PII_FIELDS, piiKms, {
+            requestId: `inbound-mail-foundation:message-content:${ctx.user.tenantId}`,
+        })
+        : row;
+    const bodyText = readable["bodyText"];
+    return {
+        messageId,
+        bodyText: typeof bodyText === "string" ? bodyText : "",
+        bodyTextTruncated: row["bodyTextTruncated"] === true,
+        bodyRef: typeof row["bodyRef"] === "string" ? row["bodyRef"] : "",
+        attachmentFileIds: fileIdsSchema.parse(row["attachmentFileIds"] ?? []),
+        skippedAttachments: parseJsonColumn(row["skippedAttachments"], skippedListSchema, []),
+        contentState: contentStateOfRow(row["contentState"]),
+        contentUnavailableReason: INBOUND_CONTENT_UNAVAILABLE_REASONS.find((reason) => reason === row["contentUnavailableReason"]) ?? null,
+        senderAuthentication: parseJsonColumn(row["senderAuthentication"], senderAuthenticationFieldSchema, null),
+    };
+}
+export function createMessageContentQuery({ memberRoles }) {
+    return {
+        name: "message:content",
+        schema: messageContentSchema,
+        access: { roles: [...memberRoles] },
+        agent: { expose: false },
+        description: "Returns the full decrypted text, the attachment file ids, the skipped attachments and the content state (complete, snippet or unavailable) of one received mail, or null when it does not exist or belongs to a personal mailbox the caller may not see; use it to read a mail beyond its snippet.",
+        handler: async (query, ctx) => {
+            const { messageId } = messageContentSchema.parse(query.payload);
+            return loadInboundMessageContent(ctx, messageId);
+        },
+    };
+}

package/dist/inbound-mail-foundation/handlers/message-detail.query.d.ts

@@ -0,0 +1,3 @@
+import type { QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import type { InboundMailRoles } from "../mail-roles.ts";
+export declare function createMessageDetailQuery({ memberRoles }: InboundMailRoles): QueryHandlerDef;

package/dist/inbound-mail-foundation/handlers/message-detail.query.js

@@ -0,0 +1,23 @@
+// inbound-message:detail — the record the file read guard asks for when someone opens a mail
+// attachment (createRecordReadCheck runs "<entity>:detail" as the caller). It answers with
+// visibility only: no PII column is selected, so opening a file never reaches the KMS.
+import * as z from "zod";
+import { INBOUND_MESSAGE_AGGREGATE_TYPE } from "../events.js";
+import { inboundMessagesProjectionTable } from "../projection.js";
+import { isVisibleToCaller } from "./scope-visibility.js";
+const messageDetailSchema = z.object({ id: z.uuid() }).strict();
+const DETAIL_COLUMNS = ["id", "tenantId", "accountId", "ownerUserId", "scope", "receivedAt"];
+export function createMessageDetailQuery({ memberRoles }) {
+    return {
+        name: `${INBOUND_MESSAGE_AGGREGATE_TYPE}:detail`,
+        schema: messageDetailSchema,
+        access: { roles: [...memberRoles] },
+        agent: { expose: false },
+        description: "Returns the non-personal envelope fields of one received mail, or null when it does not exist or belongs to a personal mailbox the caller does not own; the file read guard uses it to decide who may open the mail's attachments.",
+        handler: async (query, ctx) => {
+            const { id } = messageDetailSchema.parse(query.payload);
+            const [row] = await ctx.db.selectMany(inboundMessagesProjectionTable, { id, tenantId: ctx.user.tenantId }, { fields: DETAIL_COLUMNS });
+            return row && isVisibleToCaller(row, ctx.user) ? row : null;
+        },
+    };
+}