@cosmicdrift/kumiko-samples 0.393.0 → 0.395.0

package/packages/bundled-features/src/inbound-mail-foundation/handlers/list-messages.query.ts

@@ -14,10 +14,23 @@ import {
 } from "@cosmicdrift/kumiko-framework/crypto";
 import type { QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
-import { INBOUND_MESSAGE_PII_FIELDS } from "../entities.ts";
+import { INBOUND_MESSAGE_PII_FIELDS, inboundMessageEntity } from "../entities.ts";
+import type { InboundMailRoles } from "../mail-roles.ts";
 import { inboundMessagesProjectionTable } from "../projection.ts";
 import { isVisibleToCaller } from "./scope-visibility.ts";
 
+// 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(),
@@ -27,33 +40,36 @@ const listMessagesSchema = z
   .strict();
 type ListMessagesPayload = z.infer<typeof listMessagesSchema>;
 
-export const listMessagesQuery: QueryHandlerDef = {
-  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 as ListMessagesPayload;
-    const filter: Record<string, unknown> = { 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;
+export function createListMessagesQuery({ memberRoles }: InboundMailRoles): QueryHandlerDef {
+  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 as ListMessagesPayload;
+      const filter: Record<string, unknown> = { 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 };
-  },
-};
+      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/packages/bundled-features/src/inbound-mail-foundation/handlers/list-quarantine.query.ts

@@ -0,0 +1,106 @@
+// 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, type QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { inboundMessageAggregateId } from "../aggregate-id.ts";
+import { INBOUND_MESSAGE_PII_FIELDS } from "../entities.ts";
+import type { InboundMailRoles } from "../mail-roles.ts";
+import { inboundMessagesProjectionTable, mailAccountsProjectionTable } from "../projection.ts";
+import { quarantineTable } from "../quarantine-entities.ts";
+import { mayManageQuarantine } from "./scope-visibility.ts";
+
+// 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: unknown): string | null {
+  return typeof value === "string" ? value : null;
+}
+
+export function createListQuarantineQuery({
+  memberRoles,
+  adminRoles,
+}: InboundMailRoles): QueryHandlerDef {
+  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<string, Record<string, unknown>>();
+      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/packages/bundled-features/src/inbound-mail-foundation/handlers/mark-credential-stored.write.ts

@@ -0,0 +1,47 @@
+// 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 type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { failNotFound } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { InboundMailAccountStatuses } from "../constants.ts";
+import {
+  MAIL_ACCOUNT_AGGREGATE_TYPE,
+  MAIL_ACCOUNT_UPDATED_EVENT_QN,
+  type MailAccountEventHeaders,
+} from "../events.ts";
+import { loadCurrentMailAccountPayload } from "./account-state.ts";
+
+export const CREDENTIAL_STORED_AUDIT_REASON = "credential_stored";
+
+export const markCredentialStoredSchema = z.object({ accountId: z.uuid() });
+
+export const markCredentialStoredHandler: WriteHandlerDef = {
+  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 as const, data: { accountId: payload.accountId, marked: false } };
+    }
+    const headers: MailAccountEventHeaders = {
+      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 as const, data: { accountId: payload.accountId, marked: true } };
+  },
+};

package/packages/bundled-features/src/inbound-mail-foundation/handlers/message-content.query.ts

@@ -0,0 +1,99 @@
+// 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 type { HandlerContext, QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { parseJsonOrThrow } from "@cosmicdrift/kumiko-framework/utils";
+import * as z from "zod";
+import { INBOUND_MESSAGE_PII_FIELDS } from "../entities.ts";
+import {
+  INBOUND_CONTENT_STATES,
+  INBOUND_CONTENT_UNAVAILABLE_REASONS,
+  type InboundContentState,
+  type InboundContentUnavailableReason,
+  skippedAttachmentSchema,
+} from "../events.ts";
+import type { InboundMailRoles } from "../mail-roles.ts";
+import { inboundMessagesProjectionTable } from "../projection.ts";
+import { type SenderAuthentication, senderAuthenticationFieldSchema } from "../sender-auth.ts";
+import type { SkippedInboundAttachment } from "../types.ts";
+import { isVisibleToCaller } from "./scope-visibility.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;
+};
+
+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<T>(raw: unknown, schema: z.ZodType<T>, fallback: T): T {
+  if (typeof raw !== "string" || raw === "") return fallback;
+  return schema.parse(parseJsonOrThrow(raw, "inbound message content column"));
+}
+
+function contentStateOfRow(raw: unknown): InboundContentState {
+  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: Pick<HandlerContext, "db" | "user">,
+  messageId: string,
+): Promise<InboundMessageContent | null> {
+  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 }: InboundMailRoles): QueryHandlerDef {
+  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/packages/bundled-features/src/inbound-mail-foundation/handlers/message-content.ts

@@ -0,0 +1,229 @@
+// 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 type { HandlerContext, Registry } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  configuredMaxUploadBytes,
+  createFileRefFromBytes,
+  type FileContext,
+} from "@cosmicdrift/kumiko-framework/files";
+import * as z from "zod";
+import { INBOUND_MESSAGE_PII_FIELDS, inboundMessageEntity } from "../entities.ts";
+import {
+  INBOUND_MESSAGE_AGGREGATE_TYPE,
+  type InboundContentState,
+  skippedAttachmentSchema,
+} from "../events.ts";
+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.ts";
+import type { RawInboundAttachment, SkippedInboundAttachment } from "../types.ts";
+
+// 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(),
+};
+
+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">;
+
+// 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: string,
+  accountId: string,
+  messageAggId: string,
+  extension: "eml" | "html",
+): string {
+  return `${tenantId}/inbound-mail/${accountId}/${messageAggId}.${extension}`;
+}
+
+export type OriginalToStore = {
+  readonly data: Uint8Array;
+  readonly extension: "eml" | "html";
+  readonly mimeType: string;
+};
+
+export function originalOf(input: InboundContentInput): OriginalToStore | undefined {
+  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: Registry): number {
+  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: string) {
+  return {
+    entityType: INBOUND_MESSAGE_AGGREGATE_TYPE,
+    entityId: messageAggId,
+    fieldName: "attachmentFileIds",
+  } as const;
+}
+
+export function needsFileStorage(input: InboundContentInput): boolean {
+  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: InboundContentInput): StoredInboundContent {
+  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: FileContext,
+  tenantId: string,
+  input: InboundContentInput,
+): Promise<string> {
+  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: ContentContext,
+  input: InboundContentInput,
+): Promise<StoredInboundContent> {
+  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: string[] = [];
+  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: string,
+  messageAggId: string,
+  bodyText: string,
+): Promise<string> {
+  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: {
+  readonly bodyText: string;
+  readonly hasOriginal: boolean;
+  readonly contentStorage: StoredInboundContent["contentStorage"];
+}): InboundContentState {
+  if (args.contentStorage === "unavailable") return "unavailable";
+  return args.bodyText.length > 0 || args.hasOriginal ? "complete" : "snippet";
+}

package/packages/bundled-features/src/inbound-mail-foundation/handlers/message-detail.query.ts

@@ -0,0 +1,34 @@
+// 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 type { QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { INBOUND_MESSAGE_AGGREGATE_TYPE } from "../events.ts";
+import type { InboundMailRoles } from "../mail-roles.ts";
+import { inboundMessagesProjectionTable } from "../projection.ts";
+import { isVisibleToCaller } from "./scope-visibility.ts";
+
+const messageDetailSchema = z.object({ id: z.uuid() }).strict();
+
+const DETAIL_COLUMNS = ["id", "tenantId", "accountId", "ownerUserId", "scope", "receivedAt"];
+
+export function createMessageDetailQuery({ memberRoles }: InboundMailRoles): QueryHandlerDef {
+  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;
+    },
+  };
+}