@cosmicdrift/kumiko-bundled-features 0.392.2 → 0.394.0

package/dist/inbound-mail-foundation/normalize-inbound-message.js

@@ -0,0 +1,90 @@
+// 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.
+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;
+function isHighSurrogate(code) {
+    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, max) {
+    if (value.length <= max)
+        return value;
+    const cut = isHighSurrogate(value.charCodeAt(max - 1)) ? max - 1 : max;
+    return value.slice(0, cut);
+}
+function limitReferences(references) {
+    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))];
+}
+function splitAttachmentsByLimits(attachments) {
+    const stored = [];
+    const skipped = [];
+    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) {
+    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 = 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/dist/inbound-mail-foundation/oauth-access-token.d.ts

@@ -1,7 +1,8 @@
 import { type DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
-import { type InboundMailContext, type InboundMailProviderPlugin, type MailAccountRecord, type OAuthTokenSet } from "./types.ts";
+import type { OAuthTokenSet } from "./inbound-oauth-flow.ts";
+import type { InboundMailContext, InboundMailProviderPlugin, MailAccountRecord } from "./types.ts";
 /** Shared by the OAuth callback and the refresh path so both write the slot identically. */
 export declare function inboundRefreshTokenSecretOptions(accountId: string): {
     redact: (plaintext: string) => string;
@@ -26,3 +27,4 @@ export type OAuthAccessTokenManager = {
     readonly invalidate: (accountId: string) => void;
 };
 export declare function createOAuthAccessTokenManager(deps: OAuthAccessTokenManagerDeps): OAuthAccessTokenManager;
+export declare function storeOAuthCallbackCredential(manager: OAuthAccessTokenManager | undefined, secrets: SecretsContext, account: Pick<MailAccountRecord, "id" | "tenantId">, tokens: OAuthTokenSet, refreshToken: string): Promise<void>;

package/dist/inbound-mail-foundation/oauth-access-token.js

@@ -18,7 +18,7 @@
 import { acquireNamespacedAdvisoryLock, transaction, } from "@cosmicdrift/kumiko-framework/db";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { InboundMailAuthMethods, inboundCredentialSecretKey } from "./constants.js";
-import { InboundAuthError, } from "./types.js";
+import { InboundAuthError, InboundCredentialNotStoredError } from "./provider-errors.js";
 // 'inoa' as ASCII — disjoint from the other fixed advisory-lock namespaces.
 const OAUTH_REFRESH_LOCK_NAMESPACE = 0x696e6f61;
 const ACCESS_TOKEN_EXPIRY_MARGIN = Temporal.Duration.from({ minutes: 2 });
@@ -86,7 +86,7 @@ export function createOAuthAccessTokenManager(deps) {
             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);
@@ -133,3 +133,14 @@ export function createOAuthAccessTokenManager(deps) {
         },
     };
 }
+// 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, secrets, account, tokens, refreshToken) {
+    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/dist/inbound-mail-foundation/outbound-attachment-access.d.ts

@@ -0,0 +1,5 @@
+import { type CanReadFileRefContext, type FileRef } 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 declare function loadAttachableFileRef(ctx: OutboundAttachmentAccessContext, fileRefId: string): Promise<FileRef | null>;

package/dist/inbound-mail-foundation/outbound-attachment-access.js

@@ -0,0 +1,16 @@
+// 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 { fileRefsTable, } from "@cosmicdrift/kumiko-framework/files";
+/** 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, fileRefId) {
+    if (!isUuid(fileRefId))
+        return null;
+    const [fileRef] = await selectMany(ctx.db, fileRefsTable, {
+        id: fileRefId,
+        tenantId: ctx.user.tenantId,
+        isDeleted: false,
+    });
+    return fileRef ?? null;
+}

package/dist/inbound-mail-foundation/outbound-attachments.d.ts

@@ -0,0 +1,18 @@
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import { 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";
+};
+export declare function readableFileName(file: {
+    readonly id: string;
+    readonly fileName: string;
+}): Promise<string>;
+export declare function resolveOutboundAttachments(ctx: ResolveOutboundAttachmentsContext, fileIds: readonly string[]): Promise<ResolvedOutboundAttachments>;

package/dist/inbound-mail-foundation/outbound-attachments.js

@@ -0,0 +1,77 @@
+// 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 { canCallerReadFileRef, fileRefEntity } from "@cosmicdrift/kumiko-framework/files";
+import { FileRefTooLargeError, fileContextForTenant, readFileRefContent, } from "../file-foundation/index.js";
+import { loadAttachableFileRef } from "./outbound-attachment-access.js";
+import { OUTBOUND_ATTACHMENTS_MAX_BYTES } from "./outbound-mail.js";
+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) {
+    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, fileIds) {
+    const uniqueIds = [...new Set(fileIds)];
+    const attachments = [];
+    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;
+        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/dist/inbound-mail-foundation/outbound-mail.d.ts

@@ -1,4 +1,6 @@
 import * as z from "zod";
+/** Raw bytes, not the encoded size: base64 grows them by a third, which stays under the usual 25 MB SMTP limit. */
+export declare const OUTBOUND_ATTACHMENTS_MAX_BYTES: number;
 export declare const outboundMailMessageSchema: z.ZodObject<{
     to: z.ZodArray<z.ZodEmail>;
     cc: z.ZodOptional<z.ZodArray<z.ZodEmail>>;
@@ -7,12 +9,24 @@ export declare const outboundMailMessageSchema: z.ZodObject<{
     html: z.ZodOptional<z.ZodString>;
     inReplyTo: z.ZodOptional<z.ZodString>;
     references: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    attachmentFileIds: z.ZodOptional<z.ZodArray<z.ZodUUID>>;
 }, z.core.$strip>;
 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[];
+};
 /** The mailbox has no outgoing server stored, for example a credential document from before
  *  sending existed. The tenant has to connect the mailbox again. */
 export declare class MailSendNotConfiguredError extends Error {

package/dist/inbound-mail-foundation/outbound-mail.js

@@ -3,6 +3,9 @@
 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.
 const messageIdSchema = z
@@ -22,6 +25,7 @@ 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",

package/dist/inbound-mail-foundation/probe.js

@@ -4,9 +4,9 @@ import { toMailAccountRecord } from "./account-record.js";
 import { InboundMailAccountStatuses } from "./constants.js";
 import { INBOUND_PROBE_KEYS } from "./probe-keys.js";
 import { mailAccountsProjectionTable } from "./projection.js";
+import { isInboundAuthError } from "./provider-errors.js";
 import { resolveInboundProviderForAccount } from "./provider-factory.js";
 import { MAIL_ACCOUNT_LIST_SCREEN_QN } from "./screens.js";
-import { isInboundAuthError } from "./types.js";
 const SHORT_ID_LENGTH = 8;
 function providerContext(ctx) {
     const { configResolver, secrets } = ctx.services;

package/dist/inbound-mail-foundation/projection.d.ts

@@ -17,9 +17,15 @@ export declare const mailAccountsProjectionTable: import("@cosmicdrift/kumiko-fr
     readonly status: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
         required: true;
     };
+    readonly lastError: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
+        required: false;
+    };
     readonly watchState: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
         required: false;
     };
+    readonly trustedAuthservId: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
+        required: false;
+    };
     readonly connectedAt: {
         readonly type: "timestamp";
         readonly description?: string;
@@ -85,6 +91,26 @@ export declare const inboundMessagesProjectionTable: import("@cosmicdrift/kumiko
     readonly scope: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
         required: false;
     };
+    readonly bodyText: import("@cosmicdrift/kumiko-types/fields").EntityLongTextFieldDef & {
+        required: false;
+    };
+    readonly bodyTextTruncated: import("@cosmicdrift/kumiko-types/fields").BooleanFieldDef & {
+        required: false;
+        default: boolean;
+    };
+    readonly attachmentFileIds: import("@cosmicdrift/kumiko-types/fields").FilesFieldDef;
+    readonly skippedAttachments: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
+        required: false;
+    };
+    readonly senderAuthentication: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
+        required: false;
+    };
+    readonly contentState: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
+        required: false;
+    };
+    readonly contentUnavailableReason: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
+        required: false;
+    };
 }, "tenant">>;
 export declare const mailThreadsProjectionTable: import("@cosmicdrift/kumiko-framework/db").EntityTable<import("@cosmicdrift/kumiko-types/fields").EntityDefinition<{
     readonly threadKey: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
@@ -137,5 +163,7 @@ export declare const applyMailAccountUpdated: import("@cosmicdrift/kumiko-types/
 export declare const applyMailAccountDisconnected: import("@cosmicdrift/kumiko-types/projection").SingleStreamApplyFn;
 /** inbound-message-received → INSERT ... ON CONFLICT DO NOTHING. */
 export declare const applyInboundMessageReceived: import("@cosmicdrift/kumiko-types/projection").SingleStreamApplyFn;
+/** inbound-message-content-fetched → fills the content columns of the already projected row. */
+export declare const applyInboundMessageContentFetched: import("@cosmicdrift/kumiko-types/projection").SingleStreamApplyFn;
 /** mail-thread-updated → full UPSERT with the payload snapshot. */
 export declare const applyMailThreadUpdated: import("@cosmicdrift/kumiko-types/projection").SingleStreamApplyFn;

package/dist/inbound-mail-foundation/projection.js

@@ -17,7 +17,7 @@
 // arrive as ciphertext because they are encrypted BEFORE the append in the
 // write handler. The applies only copy them through; decryption happens only
 // in the list queries.
-import { buildEntityTable, insertOnConflictDoNothing, requireEntityTableMeta, upsertOnConflict, } from "@cosmicdrift/kumiko-framework/db";
+import { buildEntityTable, insertOnConflictDoNothing, requireEntityTableMeta, updateMany, upsertOnConflict, } from "@cosmicdrift/kumiko-framework/db";
 import { defineApply } from "@cosmicdrift/kumiko-framework/engine";
 import { inboundMessageEntity, mailAccountEntity, mailThreadEntity } from "./entities.js";
 // Drizzle table instances derived from the entity shapes, shared between
@@ -46,6 +46,8 @@ const applyMailAccountUpsert = defineApply(async (event, tx) => {
         address: p.address,
         status: p.status,
         watchState: p.watchState,
+        lastError: p.lastError,
+        trustedAuthservId: p.trustedAuthservId,
     };
     await upsertOnConflict(tx, mailAccountsProjectionMeta, {
         id: event.aggregateId,
@@ -66,8 +68,8 @@ export const applyMailAccountUpdated = applyMailAccountUpsert;
 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. */
 export const applyInboundMessageReceived = defineApply(async (event, tx) => {
@@ -87,8 +89,28 @@ export const applyInboundMessageReceived = defineApply(async (event, tx) => {
         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(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/dist/inbound-mail-foundation/provider-errors.d.ts

@@ -0,0 +1,28 @@
+export declare class InboundAuthError extends Error {
+    readonly kind: "inbound-auth-error";
+    constructor(message: string);
+}
+/** 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 declare class InboundCredentialNotStoredError extends InboundAuthError {
+    readonly credentialNotStored: true;
+    constructor(message: string);
+}
+export declare class InboundRateLimitError extends Error {
+    readonly kind: "inbound-rate-limit-error";
+    readonly retryAfterMs: number;
+    constructor(message: string, retryAfterMs: number);
+}
+export declare class InboundCursorInvalidError extends Error {
+    readonly kind: "inbound-cursor-invalid-error";
+    constructor(message: string);
+}
+export declare class InboundTransientError extends Error {
+    readonly kind: "inbound-transient-error";
+    constructor(message: string);
+}
+export declare function isInboundAuthError(e: unknown): e is InboundAuthError;
+export declare function isInboundCredentialNotStoredError(e: unknown): e is InboundCredentialNotStoredError;
+export declare function isInboundRateLimitError(e: unknown): e is InboundRateLimitError;
+export declare function isInboundCursorInvalidError(e: unknown): e is InboundCursorInvalidError;
+export declare function isInboundTransientError(e: unknown): e is InboundTransientError;

package/dist/inbound-mail-foundation/provider-errors.js

@@ -0,0 +1,66 @@
+// =============================================================================
+// 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 {
+    kind = "inbound-auth-error";
+    constructor(message) {
+        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 {
+    credentialNotStored = true;
+    constructor(message) {
+        super(message);
+        this.name = "InboundCredentialNotStoredError";
+    }
+}
+export class InboundRateLimitError extends Error {
+    kind = "inbound-rate-limit-error";
+    retryAfterMs;
+    constructor(message, retryAfterMs) {
+        super(message);
+        this.name = "InboundRateLimitError";
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+export class InboundCursorInvalidError extends Error {
+    kind = "inbound-cursor-invalid-error";
+    constructor(message) {
+        super(message);
+        this.name = "InboundCursorInvalidError";
+    }
+}
+export class InboundTransientError extends Error {
+    kind = "inbound-transient-error";
+    constructor(message) {
+        super(message);
+        this.name = "InboundTransientError";
+    }
+}
+export function isInboundAuthError(e) {
+    return e instanceof Error && "kind" in e && e.kind === "inbound-auth-error";
+}
+export function isInboundCredentialNotStoredError(e) {
+    return isInboundAuthError(e) && "credentialNotStored" in e && e.credentialNotStored === true;
+}
+export function isInboundRateLimitError(e) {
+    return e instanceof Error && "kind" in e && e.kind === "inbound-rate-limit-error";
+}
+export function isInboundCursorInvalidError(e) {
+    return e instanceof Error && "kind" in e && e.kind === "inbound-cursor-invalid-error";
+}
+export function isInboundTransientError(e) {
+    return e instanceof Error && "kind" in e && e.kind === "inbound-transient-error";
+}

package/dist/inbound-mail-foundation/quarantine-entities.d.ts

@@ -0,0 +1,61 @@
+export declare const QUARANTINE_REASON_CODES: readonly ["unparseable", "invalid_message", "ingest_failed"];
+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 declare const quarantineEntity: import("@cosmicdrift/kumiko-types/fields").EntityDefinition<{
+    readonly accountId: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
+        required: true;
+    };
+    readonly providerMessageId: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
+        required: true;
+    };
+    readonly reasonCode: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
+        required: true;
+    };
+    readonly quarantinedAt: {
+        readonly type: "timestamp";
+        readonly description?: string;
+        readonly required?: boolean;
+        readonly sortable?: boolean;
+        readonly filterable?: boolean;
+        readonly sensitive?: boolean;
+        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
+        readonly locatedBy?: string;
+        readonly min?: string;
+        readonly max?: string;
+        readonly locale?: string;
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+        required: true;
+    };
+    readonly acknowledgedAt: {
+        readonly type: "timestamp";
+        readonly description?: string;
+        readonly required?: boolean;
+        readonly sortable?: boolean;
+        readonly filterable?: boolean;
+        readonly sensitive?: boolean;
+        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
+        readonly locatedBy?: string;
+        readonly min?: string;
+        readonly max?: string;
+        readonly locale?: string;
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+        required: false;
+    };
+    readonly retryRequestedAt: {
+        readonly type: "timestamp";
+        readonly description?: string;
+        readonly required?: boolean;
+        readonly sortable?: boolean;
+        readonly filterable?: boolean;
+        readonly sensitive?: boolean;
+        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
+        readonly locatedBy?: string;
+        readonly min?: string;
+        readonly max?: string;
+        readonly locale?: string;
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+        required: false;
+    };
+}, "tenant">;
+export declare const quarantineTable: import("@cosmicdrift/kumiko-types/entity-table-meta-types").EntityTableMeta & import("@cosmicdrift/kumiko-types/executor-brand").Writable;

package/dist/inbound-mail-foundation/quarantine-entities.js

@@ -0,0 +1,47 @@
+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"];
+/** 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/dist/inbound-mail-foundation/quarantine-header-import.d.ts

@@ -0,0 +1,9 @@
+import type { DispatchWrite } from "./supervisor-ingest.ts";
+import type { MailAccountRecord, RawInboundMessage, RejectedInboundMessage } from "./types.ts";
+export declare function headerOnlyOf(msg: RawInboundMessage): RawInboundMessage;
+/** Null when the provider reported no headers for the mail: nothing meaningful to show. */
+export declare function headerOnlyOfRejected(entry: RejectedInboundMessage): RawInboundMessage | null;
+export declare function importQuarantinedHeaders(deps: {
+    readonly dispatchWrite: DispatchWrite;
+    readonly log: (line: string) => void;
+}, account: MailAccountRecord, headerOnly: RawInboundMessage | null): Promise<void>;