@cosmicdrift/kumiko-samples 0.392.2 → 0.394.0

package/packages/bundled-features/src/inbound-mail-foundation/normalize-inbound-message.ts

@@ -0,0 +1,119 @@
+// Provider-agnostic hardening of a fetched message before it is dispatched to
+// ingest-message. The ingest schema rejects oversized or empty fields; one such
+// mail would otherwise block the cursor of its mailbox forever.
+
+import type { RawInboundAttachment, RawInboundMessage, SkippedInboundAttachment } from "./types.ts";
+
+export const INBOUND_MISSING_SENDER = "(no sender)";
+export const INBOUND_BODY_TEXT_MAX_CHARS = 32_000;
+export const INBOUND_BODY_HTML_MAX_CHARS = 5_000_000;
+export const INBOUND_ATTACHMENT_MAX_BYTES = 25 * 1024 * 1024;
+export const INBOUND_MAIL_ATTACHMENTS_MAX_BYTES = 50 * 1024 * 1024;
+// The .eml holds every attachment again, so it shares the per-mail byte budget.
+export const INBOUND_RAW_MIME_MAX_BYTES = INBOUND_MAIL_ATTACHMENTS_MAX_BYTES;
+export const INBOUND_ATTACHMENTS_MAX_COUNT = 50;
+export const INBOUND_SKIPPED_ATTACHMENTS_MAX_COUNT = 200;
+
+const FROM_MAX = 2000;
+const ADDRESS_MAX = 2000;
+const ADDRESS_LIST_MAX = 200;
+const REFERENCE_MAX = 500;
+const REFERENCES_MAX = 200;
+const SUBJECT_MAX = 4000;
+const SNIPPET_MAX = 4000;
+const MESSAGE_ID_HEADER_MAX = 500;
+
+export type NormalizedInboundMessage = Omit<
+  RawInboundMessage,
+  "text" | "html" | "attachments" | "skippedAttachments"
+> & {
+  readonly bodyText: string;
+  readonly bodyTextTruncated: boolean;
+  readonly bodyHtml: string | null;
+  readonly attachments: readonly RawInboundAttachment[];
+  readonly skippedAttachments: readonly SkippedInboundAttachment[];
+};
+
+function isHighSurrogate(code: number): boolean {
+  return code >= 0xd800 && code <= 0xdbff;
+}
+
+// Cuts at UTF-16 units like the zod max, but never leaves half a surrogate pair behind.
+function clip(value: string, max: number): string {
+  if (value.length <= max) return value;
+  const cut = isHighSurrogate(value.charCodeAt(max - 1)) ? max - 1 : max;
+  return value.slice(0, cut);
+}
+
+function limitReferences(references: readonly string[]): readonly string[] {
+  const usable = references.filter((r) => r.length > 0 && r.length <= REFERENCE_MAX);
+  if (usable.length <= REFERENCES_MAX) return usable;
+  // The root keeps the thread anchor, the newest entries keep the reply chain.
+  return [...usable.slice(0, 1), ...usable.slice(usable.length - (REFERENCES_MAX - 1))];
+}
+
+type AttachmentSplit = {
+  readonly stored: readonly RawInboundAttachment[];
+  readonly skipped: readonly SkippedInboundAttachment[];
+};
+
+function splitAttachmentsByLimits(attachments: readonly RawInboundAttachment[]): AttachmentSplit {
+  const stored: RawInboundAttachment[] = [];
+  const skipped: SkippedInboundAttachment[] = [];
+  let totalBytes = 0;
+  for (const attachment of attachments) {
+    const size = attachment.data.byteLength;
+    if (size > INBOUND_ATTACHMENT_MAX_BYTES) {
+      skipped.push({ mimeType: attachment.mimeType, size, reason: "too_large" });
+    } else if (
+      totalBytes + size > INBOUND_MAIL_ATTACHMENTS_MAX_BYTES ||
+      stored.length >= INBOUND_ATTACHMENTS_MAX_COUNT
+    ) {
+      skipped.push({ mimeType: attachment.mimeType, size, reason: "mail_too_large" });
+    } else {
+      totalBytes += size;
+      stored.push({
+        fileName: clip(attachment.fileName, 255),
+        mimeType: clip(attachment.mimeType, 255),
+        data: attachment.data,
+      });
+    }
+  }
+  return { stored, skipped };
+}
+
+export function normalizeRawInboundMessage(msg: RawInboundMessage): NormalizedInboundMessage {
+  const { text, html, attachments, skippedAttachments, ...envelope } = msg;
+  const from = msg.from.trim();
+  const fullText = text ?? "";
+  const split = splitAttachmentsByLimits(attachments ?? []);
+  const bodyHtml = html ?? null;
+  const rawMimeTooLarge =
+    msg.rawMime !== null && msg.rawMime.byteLength > INBOUND_RAW_MIME_MAX_BYTES;
+  const skippedRawMime: readonly SkippedInboundAttachment[] =
+    rawMimeTooLarge && msg.rawMime !== null
+      ? [{ mimeType: "message/rfc822", size: msg.rawMime.byteLength, reason: "too_large" }]
+      : [];
+  return {
+    ...envelope,
+    rawMime: rawMimeTooLarge ? null : msg.rawMime,
+    messageIdHeader:
+      msg.messageIdHeader !== null && msg.messageIdHeader.length <= MESSAGE_ID_HEADER_MAX
+        ? msg.messageIdHeader
+        : null,
+    references: limitReferences(msg.references),
+    from: from.length === 0 ? INBOUND_MISSING_SENDER : clip(from, FROM_MAX),
+    to: msg.to.slice(0, ADDRESS_LIST_MAX).map((a) => clip(a, ADDRESS_MAX)),
+    cc: msg.cc.slice(0, ADDRESS_LIST_MAX).map((a) => clip(a, ADDRESS_MAX)),
+    subject: clip(msg.subject, SUBJECT_MAX),
+    snippet: clip(msg.snippet, SNIPPET_MAX),
+    bodyText: clip(fullText, INBOUND_BODY_TEXT_MAX_CHARS),
+    bodyTextTruncated: fullText.length > INBOUND_BODY_TEXT_MAX_CHARS,
+    bodyHtml: bodyHtml !== null && bodyHtml.length <= INBOUND_BODY_HTML_MAX_CHARS ? bodyHtml : null,
+    attachments: split.stored,
+    skippedAttachments: [...(skippedAttachments ?? []), ...split.skipped, ...skippedRawMime].slice(
+      0,
+      INBOUND_SKIPPED_ATTACHMENTS_MAX_COUNT,
+    ),
+  };
+}

package/packages/bundled-features/src/inbound-mail-foundation/oauth-access-token.ts

@@ -24,13 +24,9 @@ import {
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { InboundMailAuthMethods, inboundCredentialSecretKey } from "./constants.ts";
-import {
-  InboundAuthError,
-  type InboundMailContext,
-  type InboundMailProviderPlugin,
-  type MailAccountRecord,
-  type OAuthTokenSet,
-} from "./types.ts";
+import type { OAuthTokenSet } from "./inbound-oauth-flow.ts";
+import { InboundAuthError, InboundCredentialNotStoredError } from "./provider-errors.ts";
+import type { InboundMailContext, InboundMailProviderPlugin, MailAccountRecord } from "./types.ts";
 
 // 'inoa' as ASCII — disjoint from the other fixed advisory-lock namespaces.
 const OAUTH_REFRESH_LOCK_NAMESPACE = 0x696e6f61;
@@ -148,7 +144,7 @@ export function createOAuthAccessTokenManager(
       const secrets = deps.secrets.withRunner(tx);
       const stored = await secrets.get(account.tenantId, secretKey);
       if (!stored) {
-        throw new InboundAuthError("no refresh token stored for account");
+        throw new InboundCredentialNotStoredError("no refresh token stored for account");
       }
       const currentRefreshToken = stored.reveal();
       const tokens = await refreshWithTimeout(plugin, account, currentRefreshToken);
@@ -207,3 +203,25 @@ export function createOAuthAccessTokenManager(
     },
   };
 }
+
+// Refresh token into the per-account secret slot (slot = accountId); access tokens (~1h) are never
+// persisted. A shared manager writes under the account's refresh lock and primes its cache.
+export async function storeOAuthCallbackCredential(
+  manager: OAuthAccessTokenManager | undefined,
+  secrets: SecretsContext,
+  account: Pick<MailAccountRecord, "id" | "tenantId">,
+  tokens: OAuthTokenSet,
+  refreshToken: string,
+): Promise<void> {
+  if (manager) {
+    await manager.storeRefreshToken(account, refreshToken);
+    manager.primeFromExchange(account, tokens);
+  } else {
+    await secrets.set(
+      account.tenantId,
+      inboundCredentialSecretKey(account.id),
+      refreshToken,
+      inboundRefreshTokenSecretOptions(account.id),
+    );
+  }
+}

package/packages/bundled-features/src/inbound-mail-foundation/outbound-attachment-access.ts

@@ -0,0 +1,28 @@
+// Who may attach a stored file to an outgoing mail: exactly who may download it. Attachments of
+// imported mails are bound to the mail, so the file guard answers with the mail's visibility.
+
+import { selectMany } from "@cosmicdrift/kumiko-framework/db";
+import { isUuid } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  type CanReadFileRefContext,
+  type FileRef,
+  fileRefsTable,
+} from "@cosmicdrift/kumiko-framework/files";
+import type { ResolveOutboundAttachmentsContext } from "./outbound-attachments.ts";
+
+export type OutboundAttachmentAccessContext = ResolveOutboundAttachmentsContext &
+  CanReadFileRefContext;
+
+/** The file of the sender's tenant, or null: another tenant's and a deleted file read like a missing one. */
+export async function loadAttachableFileRef(
+  ctx: OutboundAttachmentAccessContext,
+  fileRefId: string,
+): Promise<FileRef | null> {
+  if (!isUuid(fileRefId)) return null;
+  const [fileRef] = await selectMany<FileRef>(ctx.db, fileRefsTable, {
+    id: fileRefId,
+    tenantId: ctx.user.tenantId,
+    isDeleted: false,
+  });
+  return fileRef ?? null;
+}

package/packages/bundled-features/src/inbound-mail-foundation/outbound-attachments.ts

@@ -0,0 +1,111 @@
+// Turns the file references of an outgoing mail into bytes. Only the sender's own tenant is
+// searched, so another tenant's file reads exactly like a missing one; a file the caller may not
+// read counts as missing too (outbound-attachment-access.ts).
+
+import {
+  collectPiiSubjectFields,
+  configuredPiiSubjectKms,
+  decryptPiiFieldValues,
+  isPiiCiphertext,
+  PII_ERASED_SENTINEL,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import { canCallerReadFileRef, fileRefEntity } from "@cosmicdrift/kumiko-framework/files";
+import {
+  FileRefTooLargeError,
+  fileContextForTenant,
+  readFileRefContent,
+} from "../file-foundation/index.ts";
+import { loadAttachableFileRef } from "./outbound-attachment-access.ts";
+import { OUTBOUND_ATTACHMENTS_MAX_BYTES, type OutboundAttachment } from "./outbound-mail.ts";
+
+export type ResolveOutboundAttachmentsContext = Pick<
+  HandlerContext,
+  "db" | "user" | "services" | "obs" | "registry"
+> & { readonly dispatch: Pick<HandlerContext["dispatch"], "query"> };
+
+export type ResolvedOutboundAttachments =
+  | {
+      readonly isSuccess: true;
+      readonly attachments: readonly OutboundAttachment[];
+      readonly fileIds: readonly string[];
+    }
+  | { readonly isSuccess: false; readonly failure: "attachmentInvalid" | "attachmentsTooLarge" };
+
+const FALLBACK_ATTACHMENT_NAME = "attachment";
+const PII_SUBJECT_FIELDS = collectPiiSubjectFields(fileRefEntity);
+
+// The stored name is personal data and may be ciphertext; a name that cannot be read must not
+// stop the mail, and ciphertext or the erased marker never goes into a header.
+export async function readableFileName(file: {
+  readonly id: string;
+  readonly fileName: string;
+}): Promise<string> {
+  const storedName = file.fileName;
+  if (!isPiiCiphertext(storedName)) return storedName;
+  const kms = configuredPiiSubjectKms();
+  if (!kms) return FALLBACK_ATTACHMENT_NAME;
+  try {
+    const decrypted = await decryptPiiFieldValues(
+      { fileName: storedName },
+      PII_SUBJECT_FIELDS,
+      kms,
+      { requestId: `outbound-attachment:${file.id}` },
+    );
+    const name = decrypted["fileName"];
+    if (typeof name !== "string" || isPiiCiphertext(name) || name === PII_ERASED_SENTINEL) {
+      return FALLBACK_ATTACHMENT_NAME;
+    }
+    return name;
+  } catch {
+    // skip: broken crypto metadata must not block the mail; the attachment keeps a neutral name.
+    return FALLBACK_ATTACHMENT_NAME;
+  }
+}
+
+export async function resolveOutboundAttachments(
+  ctx: ResolveOutboundAttachmentsContext,
+  fileIds: readonly string[],
+): Promise<ResolvedOutboundAttachments> {
+  const uniqueIds = [...new Set(fileIds)];
+  const attachments: OutboundAttachment[] = [];
+  let remainingBytes = OUTBOUND_ATTACHMENTS_MAX_BYTES;
+  const tenantId = ctx.user.tenantId;
+  for (const fileRefId of uniqueIds) {
+    // A file the caller may not read answers like an unknown id, so ids cannot be probed.
+    const fileRef = await loadAttachableFileRef(ctx, fileRefId);
+    if (fileRef === null || !(await canCallerReadFileRef(ctx, fileRef))) {
+      return { isSuccess: false, failure: "attachmentInvalid" };
+    }
+    let found: Awaited<ReturnType<typeof readFileRefContent>>;
+    try {
+      found = await readFileRefContent({
+        db: ctx.db,
+        filesForTenant: (forTenantId) => fileContextForTenant(ctx, tenantId, forTenantId),
+        fileRefId,
+        allowedTenantIds: [tenantId],
+        maxBytes: remainingBytes,
+      });
+    } catch (err) {
+      if (err instanceof FileRefTooLargeError) {
+        return { isSuccess: false, failure: "attachmentsTooLarge" };
+      }
+      ctx.obs.log.warn("outbound attachment could not be read", {
+        fileRefId,
+        errorName: err instanceof Error ? err.name : typeof err,
+      });
+      return { isSuccess: false, failure: "attachmentInvalid" };
+    }
+    if (found === null) return { isSuccess: false, failure: "attachmentInvalid" };
+    if (found.content.byteLength > remainingBytes) {
+      return { isSuccess: false, failure: "attachmentsTooLarge" };
+    }
+    remainingBytes -= found.content.byteLength;
+    attachments.push({
+      fileName: await readableFileName({ id: fileRefId, fileName: found.fileName }),
+      mimeType: found.contentType,
+      data: found.content,
+    });
+  }
+  return { isSuccess: true, attachments, fileIds: uniqueIds };
+}

package/packages/bundled-features/src/inbound-mail-foundation/outbound-mail.ts

@@ -5,6 +5,10 @@ import * as z from "zod";
 
 const MAX_RECIPIENTS = 50;
 const MAX_REFERENCES = 100;
+const MAX_ATTACHMENTS = 10;
+
+/** Raw bytes, not the encoded size: base64 grows them by a third, which stays under the usual 25 MB SMTP limit. */
+export const OUTBOUND_ATTACHMENTS_MAX_BYTES = 18 * 1024 * 1024;
 
 // Message ids travel without angle brackets, like RawInboundMessage.references. Anything that
 // could close the bracket or start a new header is refused instead of being encoded.
@@ -26,17 +30,31 @@ export const outboundMailMessageSchema = z
     html: z.string().optional(),
     inReplyTo: messageIdSchema.optional(),
     references: z.array(messageIdSchema).max(MAX_REFERENCES).optional(),
+    attachmentFileIds: z.array(z.uuid()).max(MAX_ATTACHMENTS).optional(),
   })
   .refine((message) => message.text !== undefined || message.html !== undefined, {
     message: "needs text or html",
   });
 export type OutboundMailMessage = z.infer<typeof outboundMailMessageSchema>;
 
-export type OutboundMailSent = {
+/** An attachment whose file reference was resolved to bytes before the provider sends. */
+export type OutboundAttachment = {
+  readonly fileName: string;
+  readonly mimeType: string;
+  readonly data: Uint8Array;
+};
+
+/** What a provider plugin reports about a mail it sent. */
+export type ProviderSentMail = {
   /** Message-ID header of the sent mail, without angle brackets. */
   readonly messageIdHeader: string;
 };
 
+export type OutboundMailSent = ProviderSentMail & {
+  /** The file references that went out as attachments, for the caller's own record of the mail. */
+  readonly attachmentFileIds: readonly string[];
+};
+
 // Same `kind` discriminant as the inbound error classes (see types.ts).
 
 /** The mailbox has no outgoing server stored, for example a credential document from before

package/packages/bundled-features/src/inbound-mail-foundation/probe.ts

@@ -9,9 +9,10 @@ import { type MailAccountRow, toMailAccountRecord } from "./account-record.ts";
 import { InboundMailAccountStatuses } from "./constants.ts";
 import { INBOUND_PROBE_KEYS } from "./probe-keys.ts";
 import { mailAccountsProjectionTable } from "./projection.ts";
+import { isInboundAuthError } from "./provider-errors.ts";
 import { resolveInboundProviderForAccount } from "./provider-factory.ts";
 import { MAIL_ACCOUNT_LIST_SCREEN_QN } from "./screens.ts";
-import { type InboundMailContext, isInboundAuthError } from "./types.ts";
+import type { InboundMailContext } from "./types.ts";
 
 const SHORT_ID_LENGTH = 8;
 

package/packages/bundled-features/src/inbound-mail-foundation/projection.ts

@@ -23,11 +23,13 @@ import {
   type EntityTableMeta,
   insertOnConflictDoNothing,
   requireEntityTableMeta,
+  updateMany,
   upsertOnConflict,
 } from "@cosmicdrift/kumiko-framework/db";
 import { defineApply } from "@cosmicdrift/kumiko-framework/engine";
 import { inboundMessageEntity, mailAccountEntity, mailThreadEntity } from "./entities.ts";
 import type {
+  InboundMessageContentFetchedEventPayload,
   InboundMessageEventPayload,
   MailAccountEventPayload,
   MailThreadEventPayload,
@@ -74,6 +76,8 @@ const applyMailAccountUpsert = defineApply<MailAccountEventPayload>(async (event
     address: p.address,
     status: p.status,
     watchState: p.watchState,
+    lastError: p.lastError,
+    trustedAuthservId: p.trustedAuthservId,
   };
   await upsertOnConflict(
     tx,
@@ -101,8 +105,8 @@ export const applyMailAccountDisconnected = applyMailAccountUpsert;
 
 // =============================================================================
 // inbound-message — exactly one received event per stream (deterministic
-// aggregateId). INSERT-ignore makes replays no-ops on the primary key;
-// there is no update case.
+// aggregateId). INSERT-ignore makes replays no-ops on the primary key; the
+// only later change is the content-fetched event for snippet-only imports.
 // =============================================================================
 
 /** inbound-message-received → INSERT ... ON CONFLICT DO NOTHING. */
@@ -124,10 +128,37 @@ export const applyInboundMessageReceived = defineApply<InboundMessageEventPayloa
       receivedAt: p.receivedAtIso,
       bodyRef: p.bodyRef,
       scope: p.scope,
+      bodyText: p.bodyText,
+      bodyTextTruncated: p.bodyTextTruncated,
+      attachmentFileIds: p.attachmentFileIds,
+      skippedAttachments: JSON.stringify(p.skippedAttachments),
+      senderAuthentication: JSON.stringify(p.senderAuthentication),
+      contentState: p.contentState,
+      contentUnavailableReason: p.contentUnavailableReason,
     });
   },
 );
 
+/** inbound-message-content-fetched → fills the content columns of the already projected row. */
+export const applyInboundMessageContentFetched =
+  defineApply<InboundMessageContentFetchedEventPayload>(async (event, tx) => {
+    const p = event.payload;
+    await updateMany(
+      tx,
+      inboundMessagesProjectionMeta,
+      {
+        bodyRef: p.bodyRef,
+        bodyText: p.bodyText,
+        bodyTextTruncated: p.bodyTextTruncated,
+        attachmentFileIds: p.attachmentFileIds,
+        skippedAttachments: JSON.stringify(p.skippedAttachments),
+        contentState: p.contentState,
+        contentUnavailableReason: p.contentUnavailableReason,
+      },
+      { id: event.aggregateId },
+    );
+  });
+
 // =============================================================================
 // mail-thread — rollup per (tenantId, threadKey). The write handler computes
 // messageCount/lastMessageAt and appends the updated event with the NEW state.

package/packages/bundled-features/src/inbound-mail-foundation/provider-errors.ts

@@ -0,0 +1,74 @@
+// =============================================================================
+// Typed errors handled uniformly by the Foundation during polling:
+//   InboundAuthError          → status=auth_error, no retry
+//   InboundRateLimitError     → abort poll, wait for the next cron tick
+//   InboundCursorInvalidError → reset cursor + full resync in the backfill
+//                               window; deduplication handles duplicates
+//   InboundTransientError     → job retry (retries: 3, exponential)
+// =============================================================================
+//
+// Use a `kind` discriminant instead of instanceof: plugins and the Foundation
+// may run in separate bundles (dual-package-hazard), and instanceof is
+// unreliable across realm or package-copy boundaries.
+
+export class InboundAuthError extends Error {
+  readonly kind = "inbound-auth-error" as const;
+  constructor(message: string) {
+    super(message);
+    this.name = "InboundAuthError";
+  }
+}
+
+/** The credential secret is not there (yet). Still an auth error for a regular poll; a sync woken
+ *  right after connect treats it as "not ready" because the secret is written after the account. */
+export class InboundCredentialNotStoredError extends InboundAuthError {
+  readonly credentialNotStored = true as const;
+  constructor(message: string) {
+    super(message);
+    this.name = "InboundCredentialNotStoredError";
+  }
+}
+
+export class InboundRateLimitError extends Error {
+  readonly kind = "inbound-rate-limit-error" as const;
+  readonly retryAfterMs: number;
+  constructor(message: string, retryAfterMs: number) {
+    super(message);
+    this.name = "InboundRateLimitError";
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+
+export class InboundCursorInvalidError extends Error {
+  readonly kind = "inbound-cursor-invalid-error" as const;
+  constructor(message: string) {
+    super(message);
+    this.name = "InboundCursorInvalidError";
+  }
+}
+
+export class InboundTransientError extends Error {
+  readonly kind = "inbound-transient-error" as const;
+  constructor(message: string) {
+    super(message);
+    this.name = "InboundTransientError";
+  }
+}
+
+export function isInboundAuthError(e: unknown): e is InboundAuthError {
+  return e instanceof Error && "kind" in e && e.kind === "inbound-auth-error";
+}
+export function isInboundCredentialNotStoredError(
+  e: unknown,
+): e is InboundCredentialNotStoredError {
+  return isInboundAuthError(e) && "credentialNotStored" in e && e.credentialNotStored === true;
+}
+export function isInboundRateLimitError(e: unknown): e is InboundRateLimitError {
+  return e instanceof Error && "kind" in e && e.kind === "inbound-rate-limit-error";
+}
+export function isInboundCursorInvalidError(e: unknown): e is InboundCursorInvalidError {
+  return e instanceof Error && "kind" in e && e.kind === "inbound-cursor-invalid-error";
+}
+export function isInboundTransientError(e: unknown): e is InboundTransientError {
+  return e instanceof Error && "kind" in e && e.kind === "inbound-transient-error";
+}

package/packages/bundled-features/src/inbound-mail-foundation/quarantine-entities.ts

@@ -0,0 +1,56 @@
+import { deriveEntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+import {
+  access,
+  createEntity,
+  createTextField,
+  createTimestampField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+export const QUARANTINE_REASON_CODES = ["unparseable", "invalid_message", "ingest_failed"] as const;
+export type QuarantineReasonCode = (typeof QUARANTINE_REASON_CODES)[number];
+
+/** A provider message the ingest cannot take. No subject or sender, so nothing here is personal data;
+ *  the UID is enough for the operator to find the mail in the mailbox. */
+export const quarantineEntity = createEntity({
+  table: "store_mail_quarantine",
+  softDelete: false,
+  indexes: [{ unique: true, columns: ["tenantId", "accountId", "providerMessageId"] }],
+  fields: {
+    accountId: createTextField({
+      required: true,
+      maxLength: 36,
+      access: { write: access.privileged },
+      personal: false,
+      reason: "technical_reference",
+    }),
+    providerMessageId: createTextField({
+      required: true,
+      maxLength: 500,
+      access: { write: access.privileged },
+      personal: false,
+      reason: "technical_reference",
+    }),
+    reasonCode: createTextField({
+      required: true,
+      maxLength: 30,
+      access: { write: access.privileged },
+      personal: false,
+      reason: "technical_reference",
+    }),
+    quarantinedAt: createTimestampField({
+      required: true,
+      access: { write: access.privileged },
+    }),
+    acknowledgedAt: createTimestampField({
+      access: { write: access.privileged },
+    }),
+    // Set by retry-quarantined-message; the next successful sync of the mailbox reloads the mail and clears the row.
+    retryRequestedAt: createTimestampField({
+      access: { write: access.privileged },
+    }),
+  },
+});
+
+export const quarantineTable = deriveEntityTableMeta("mail-quarantine", quarantineEntity, {
+  source: "unmanaged",
+});

package/packages/bundled-features/src/inbound-mail-foundation/quarantine-header-import.ts

@@ -0,0 +1,63 @@
+// A quarantined mail stays visible: its headers (and the original, when file storage is there) are
+// imported as a message without content, marked "unavailable / quarantined". The import is best
+// effort: the quarantine row already moves the cursor on, and a retry can still load the content.
+
+import { InboundMailFoundationHandlers } from "./constants.ts";
+import { ingestPayloadOf } from "./ingest-payload.ts";
+import { INBOUND_MISSING_SENDER, normalizeRawInboundMessage } from "./normalize-inbound-message.ts";
+import type { DispatchWrite } from "./supervisor-ingest.ts";
+import type { MailAccountRecord, RawInboundMessage, RejectedInboundMessage } from "./types.ts";
+
+const EPOCH_ISO = "1970-01-01T00:00:00Z";
+
+export function headerOnlyOf(msg: RawInboundMessage): RawInboundMessage {
+  const { text: _text, html: _html, attachments: _a, skippedAttachments: _s, ...envelope } = msg;
+  return { ...envelope, text: "", html: null, attachments: [], skippedAttachments: [] };
+}
+
+/** Null when the provider reported no headers for the mail: nothing meaningful to show. */
+export function headerOnlyOfRejected(entry: RejectedInboundMessage): RawInboundMessage | null {
+  const { headers } = entry;
+  if (!headers) return null;
+  return {
+    providerMessageId: entry.providerMessageId,
+    messageIdHeader: headers.messageIdHeader,
+    providerThreadId: null,
+    references: [],
+    from: headers.from === "" ? INBOUND_MISSING_SENDER : headers.from,
+    to: headers.to,
+    cc: headers.cc,
+    subject: headers.subject,
+    snippet: "",
+    receivedAtIso: headers.receivedAtIso === "" ? EPOCH_ISO : headers.receivedAtIso,
+    rawMime: entry.rawMime ?? null,
+    scope: "inbox",
+  };
+}
+
+export async function importQuarantinedHeaders(
+  deps: { readonly dispatchWrite: DispatchWrite; readonly log: (line: string) => void },
+  account: MailAccountRecord,
+  headerOnly: RawInboundMessage | null,
+): Promise<void> {
+  // skip: no header data to import for this mail
+  if (!headerOnly) return;
+  try {
+    const result = await deps.dispatchWrite({
+      handlerQn: InboundMailFoundationHandlers.ingestMessage,
+      tenantId: account.tenantId,
+      payload: ingestPayloadOf(account, normalizeRawInboundMessage(headerOnly), {
+        providerCursor: "quarantine",
+        bodyRef: "",
+        contentUnavailableReason: "quarantined",
+      }),
+    });
+    if (!result.isSuccess) {
+      deps.log(
+        `inbound-mail: account ${account.id} header import of a quarantined mail was rejected`,
+      );
+    }
+  } catch {
+    deps.log(`inbound-mail: account ${account.id} header import of a quarantined mail failed`);
+  }
+}