@cosmicdrift/kumiko-samples 0.393.0 → 0.395.0

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

@@ -22,6 +22,7 @@
 
 import * as z from "zod";
 import { INBOUND_MAIL_FOUNDATION_FEATURE, InboundMailAccountStatuses } from "./constants.ts";
+import { senderAuthenticationFieldSchema } from "./sender-auth.ts";
 
 // Aggregate types for the event store.
 export const MAIL_ACCOUNT_AGGREGATE_TYPE = "mail-account" as const;
@@ -35,6 +36,8 @@ export const MAIL_ACCOUNT_UPDATED_EVENT_SHORT = "mail-account-updated" as const;
 export const MAIL_ACCOUNT_DISCONNECTED_EVENT_SHORT = "mail-account-disconnected" as const;
 export const INBOUND_MESSAGE_RECEIVED_EVENT_SHORT = "inbound-message-received" as const;
 export const MAIL_THREAD_UPDATED_EVENT_SHORT = "mail-thread-updated" as const;
+export const INBOUND_MESSAGE_CONTENT_FETCHED_EVENT_SHORT =
+  "inbound-message-content-fetched" as const;
 
 export const MAIL_ACCOUNT_CONNECTED_EVENT_QN =
   `${INBOUND_MAIL_FOUNDATION_FEATURE}:event:${MAIL_ACCOUNT_CONNECTED_EVENT_SHORT}` as const;
@@ -44,6 +47,8 @@ export const MAIL_ACCOUNT_DISCONNECTED_EVENT_QN =
   `${INBOUND_MAIL_FOUNDATION_FEATURE}:event:${MAIL_ACCOUNT_DISCONNECTED_EVENT_SHORT}` as const;
 export const INBOUND_MESSAGE_RECEIVED_EVENT_QN =
   `${INBOUND_MAIL_FOUNDATION_FEATURE}:event:${INBOUND_MESSAGE_RECEIVED_EVENT_SHORT}` as const;
+export const INBOUND_MESSAGE_CONTENT_FETCHED_EVENT_QN =
+  `${INBOUND_MAIL_FOUNDATION_FEATURE}:event:${INBOUND_MESSAGE_CONTENT_FETCHED_EVENT_SHORT}` as const;
 export const MAIL_THREAD_UPDATED_EVENT_QN =
   `${INBOUND_MAIL_FOUNDATION_FEATURE}:event:${MAIL_THREAD_UPDATED_EVENT_SHORT}` as const;
 
@@ -76,9 +81,51 @@ export const mailAccountEventPayloadSchema = z.object({
   /** Provider-agnostic watch state ("idle", "watching", "backoff:3", ...)
    *  — an operational signal only, not PII. */
   watchState: z.string().max(100),
+  /** Why the mailbox is degraded (InboundMailLastErrors code); null while healthy. A string rather
+   *  than an enum, like authMethod, so a new code needs no upcaster. */
+  lastError: z.string().max(50).nullable(),
+  /** authserv-id (lower case) of the mailbox's own server; only an Authentication-Results header
+   *  with exactly this id is believed (sender-auth.ts). null = not set, no sender verdicts. */
+  trustedAuthservId: z.string().max(255).nullable(),
 });
 export type MailAccountEventPayload = z.infer<typeof mailAccountEventPayloadSchema>;
 
+export const INBOUND_CONTENT_STATES = ["complete", "snippet", "unavailable"] as const;
+export type InboundContentState = (typeof INBOUND_CONTENT_STATES)[number];
+
+/** Why a message has no content: held back by the quarantine (retry possible), no file storage wired, or gone from the server. */
+export const INBOUND_CONTENT_UNAVAILABLE_REASONS = [
+  "quarantined",
+  "no_file_storage",
+  "gone_from_server",
+] as const;
+export type InboundContentUnavailableReason = (typeof INBOUND_CONTENT_UNAVAILABLE_REASONS)[number];
+
+export const skippedAttachmentSchema = z.object({
+  mimeType: z.string().max(255),
+  size: z.number().int().min(0),
+  reason: z.enum([
+    "too_large",
+    "mail_too_large",
+    "rejected",
+    "no_file_storage",
+    "nesting_too_deep",
+  ]),
+});
+
+// Shared by inbound-message-received (v2+) and inbound-message-content-fetched.
+// bodyText is ciphertext: 32_000 characters become roughly 75 KB, hence the generous max.
+const inboundMessageContentShape = {
+  bodyText: z.string().max(200_000),
+  bodyTextTruncated: z.boolean(),
+  /** file-foundation FileRef ids (plaintext uuids). Attachments outlive the mail: apps turn them
+   *  into documents, so the retention sweep never deletes them. */
+  attachmentFileIds: z.array(z.uuid()).max(50),
+  skippedAttachments: z.array(skippedAttachmentSchema).max(200),
+  contentState: z.enum(INBOUND_CONTENT_STATES),
+  contentUnavailableReason: z.enum(INBOUND_CONTENT_UNAVAILABLE_REASONS).nullable(),
+};
+
 // ============================================================================
 // inbound-message stream — exactly ONE received event per message
 // ============================================================================
@@ -110,15 +157,35 @@ export const inboundMessageEventPayloadSchema = z.object({
   /** ISO instant — receipt time reported by the provider (INTERNALDATE or
    *  receivedDateTime), not ingest time. */
   receivedAtIso: z.string().min(1),
-  /** file-foundation reference to the raw body (MIME). Empty when the app
-   *  is mounted without body persistence (snippet-only mode). */
+  /** file-foundation reference to the original (.eml, or .html for HTML-only mails). Empty for
+   *  snippet-only mails and when no file storage is available. */
   bodyRef: z.string().max(500),
   /** Domain scope hint for downstream business processes — generic
    *  ("inbox", folder name), with NO app-specific semantics. */
   scope: z.string().max(200),
+  /** SPF/DKIM/DMARC as reported by the mailbox's own server; null when there is no trustworthy
+   *  statement. Not PII. */
+  senderAuthentication: senderAuthenticationFieldSchema,
+  ...inboundMessageContentShape,
 });
 export type InboundMessageEventPayload = z.infer<typeof inboundMessageEventPayloadSchema>;
 
+// ============================================================================
+// Content of a message that was imported as snippet only and re-downloaded later.
+// Same aggregate as the received event; applies as an update of the projection row.
+// ============================================================================
+export const inboundMessageContentFetchedEventPayloadSchema = z.object({
+  /** Account and scope of the message, so a subscriber can route the event without loading the
+   *  stream. Null on events stored before v3: the stream id cannot be reversed to the account. */
+  accountId: z.uuid().nullable(),
+  ownerUserId: z.string().max(36).nullable(),
+  bodyRef: z.string().max(500),
+  ...inboundMessageContentShape,
+});
+export type InboundMessageContentFetchedEventPayload = z.infer<
+  typeof inboundMessageContentFetchedEventPayloadSchema
+>;
+
 // ============================================================================
 // mail-thread-Stream — Thread-Rollup pro (tenantId, threadKey)
 // ============================================================================

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

@@ -1,52 +1,28 @@
 // kumiko-feature-version: 1
-//
-// inbound-mail-foundation — Plugin host for inbound e-mail
-// (inbox federation). Counterpart to mail-foundation (outbound): separate
-// extension points, separate state — architectural model is
-// file-foundation (the foundation owns state), not mail-transport.
-//
-// **Multi-provider from day one** (as with billing-foundation): NO global
-// `provider` config key. A tenant can connect IMAP and (later) M365/Gmail
-// mailboxes in parallel; the provider is specified per MailAccount.
+// inbound-mail-foundation: plugin host for inbound e-mail (inbox federation), the counterpart to
+// mail-foundation (outbound) with its own extension points and state. Modelled on file-foundation
+// (the foundation owns state), not on mail-transport.
 //
 // **What this foundation provides:**
-//   1. **Plugin API** for inbound providers via r.extendsRegistrar
-//      ("inboundMailProvider"): verify/fetch/oauth?/watch? (types.ts).
+//   1. **Plugin API** for providers via r.extendsRegistrar: verify/fetch/oauth?/watch? (types.ts).
 //   2. **3 event-sourced streams** — mail-account (lifecycle),
 //      inbound-message (exactly ONE received event per message, deterministic
 //      aggregateId ⇒ exactly-once despite at-least-once ingest),
-//      mail-thread (rollup). Full replayable history for later
-//      consumers (business processes: ticket, receipt, auto-reply).
-//   3. **Inline projections** into read_mail_accounts /
-//      read_inbound_messages / read_mail_threads (read-your-own-write).
+//      mail-thread (rollup), fully replayable for later consumers.
+//   3. **Inline projections** into read_mail_accounts/_inbound_messages/_mail_threads (RYOW).
 //   4. **Write/query handlers**: connect/update/disconnect-account,
 //      ingest-message (programmatic, SystemAdmin), account:list +
-//      message:list (PII-decrypted, scope-filtered).
-//   5. **createInboundMailConnectRoutes**: OAuth connect + anonymous
-//      callback (outside /api/*), with HMAC-signed state.
-//   6. **createInboundMailSupervisor**: app-wired watch (IDLE)
-//      supervisor with backoff + reconciliation poll.
+//      message:list (PII-decrypted; personal mail only for its owner).
 //
-// **What this foundation does NOT do:**
-//   - No business semantics (intent, ticket, assignment, read/
-//     completed) — those belong to the app consumer (for example, via an
-//     event job on inbound-message-received + its own projection).
-//   - No body blob in the event store: rawMime → file-foundation via
-//     the Supervisor-storeBody-Hook; the event carries only bodyRef.
-//   - No IMAP flag write-back (V1) — inbox status belongs to the consumer.
+// **Not here:** business semantics (intent, ticket, assignment, read/completed) belong to the
+// app consumer, for example an event job on inbound-message-received with its own projection.
 //
-// **PII/GDPR:** address/from/to/cc/subject/snippet are `personal: "tenant"`
-// — encrypted BEFORE every event append (the only write path), event log AND
-// projections carry ciphertext; tenant-destroy shreds the subject key
-// (crypto-shredding, the same pattern as billing-foundation). The destroy
-// hook additionally archives all streams + deletes the rows.
+// **PII/GDPR:** address/from/to/cc/subject/snippet are `personal: "tenant"`, encrypted BEFORE every
+// event append (the only write path), so event log AND projections carry ciphertext; tenant-destroy
+// shreds the subject key (crypto-shredding, as in billing-foundation) and its hook additionally
+// archives all streams and deletes the rows.
 
-import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { defineFeature, EXT_TENANT_DATA } from "@cosmicdrift/kumiko-framework/engine";
-import {
-  createFileProviderForTenant,
-  type FileStorageProvider,
-} from "@cosmicdrift/kumiko-framework/files";
 import { INBOUND_MAIL_FOUNDATION_FEATURE, INBOUND_MAIL_PROVIDER_EXTENSION } from "./constants.ts";
 import {
   inboundMessageEntity,
@@ -57,8 +33,11 @@ import {
 } from "./entities.ts";
 import {
   INBOUND_MESSAGE_AGGREGATE_TYPE,
+  INBOUND_MESSAGE_CONTENT_FETCHED_EVENT_QN,
+  INBOUND_MESSAGE_CONTENT_FETCHED_EVENT_SHORT,
   INBOUND_MESSAGE_RECEIVED_EVENT_QN,
   INBOUND_MESSAGE_RECEIVED_EVENT_SHORT,
+  inboundMessageContentFetchedEventPayloadSchema,
   inboundMessageEventPayloadSchema,
   MAIL_ACCOUNT_AGGREGATE_TYPE,
   MAIL_ACCOUNT_CONNECTED_EVENT_QN,
@@ -73,15 +52,31 @@ import {
   mailAccountEventPayloadSchema,
   mailThreadEventPayloadSchema,
 } from "./events.ts";
-import { connectAccountHandler } from "./handlers/connect-account.write.ts";
-import { disconnectAccountHandler } from "./handlers/disconnect-account.write.ts";
+import { createAcknowledgeQuarantineHandler } from "./handlers/acknowledge-quarantine.write.ts";
+import { attachMessageContentHandler } from "./handlers/attach-message-content.write.ts";
+import { createConnectAccountHandler } from "./handlers/connect-account.write.ts";
+import { createDisconnectAccountHandler } from "./handlers/disconnect-account.write.ts";
 import { ingestMessageHandler } from "./handlers/ingest-message.write.ts";
-import { listAccountsQuery } from "./handlers/list-accounts.query.ts";
-import { listMessagesQuery } from "./handlers/list-messages.query.ts";
-import { updateAccountHandler } from "./handlers/update-account.write.ts";
+import { createListAccountsQuery } from "./handlers/list-accounts.query.ts";
+import { createListMessagesQuery } from "./handlers/list-messages.query.ts";
+import { createListQuarantineQuery } from "./handlers/list-quarantine.query.ts";
+import { markCredentialStoredHandler } from "./handlers/mark-credential-stored.write.ts";
+import { createMessageContentQuery } from "./handlers/message-content.query.ts";
+import { createMessageDetailQuery } from "./handlers/message-detail.query.ts";
+import { createReactivateAccountHandler } from "./handlers/reactivate-account.write.ts";
+import { createRetryQuarantinedMessageHandler } from "./handlers/retry-quarantined-message.write.ts";
+import { createSetTrustedAuthservIdHandler } from "./handlers/set-trusted-authserv-id.write.ts";
+import { createUpdateAccountHandler } from "./handlers/update-account.write.ts";
 import { INBOUND_MAIL_FOUNDATION_I18N } from "./i18n.ts";
+import { ingestFailureTable } from "./ingest-failures.ts";
+import {
+  type InboundMailRoleOptions,
+  resolveInboundMailRoles,
+  roleDedupeOptions,
+} from "./mail-roles.ts";
 import { registerMailboxProbe } from "./probe.ts";
 import {
+  applyInboundMessageContentFetched,
   applyInboundMessageReceived,
   applyMailAccountConnected,
   applyMailAccountDisconnected,
@@ -91,16 +86,20 @@ import {
   mailAccountsProjectionTable,
   mailThreadsProjectionTable,
 } from "./projection.ts";
-import { runInboundMailRetention } from "./retention-sweep.ts";
-import { mailAccountEditScreen, mailAccountListScreen } from "./screens.ts";
+import { quarantineTable } from "./quarantine-entities.ts";
+import { createMailQuarantineScreen } from "./quarantine-screens.ts";
+import { registerInboundMailRetentionJob } from "./retention-job.ts";
+import { createMailAccountScreens } from "./screens.ts";
 import {
   INBOUND_MAIL_TENANT_DESTROY_ARCHIVE_REASON,
   inboundMessageTenantDestroyHook,
   mailAccountTenantDestroyHook,
   mailThreadTenantDestroyHook,
 } from "./tenant-destroy-hook.ts";
+import { registerMailAccountWakeConsumer } from "./wake-consumer.ts";
 
-export function createInboundMailFoundationFeature() {
+export function createInboundMailFoundationFeature(options: InboundMailRoleOptions = {}) {
+  const roles = resolveInboundMailRoles(options);
   return defineFeature(
     INBOUND_MAIL_FOUNDATION_FEATURE,
     (r) => {
@@ -116,28 +115,84 @@ export function createInboundMailFoundationFeature() {
       // The EXT_TENANT_DATA hook requires the tenant-lifecycle host.
       r.requires({ features: ["tenant-lifecycle"] });
 
-      // 5 fine-grained domain-events (Payload-Schemas: events.ts).
       // piiFields: "none" — address/subject/snippet are already ciphertext under the tenant subject key before append (see events.ts).
       // "displayName" stays plaintext (often the mailbox owner's real name for
       // personal accounts); encrypting it would break the entity-projection read
       // path that carries it as `personal: false`.
+      // v2: lastError, trustedAuthservId. Defaults are shared references across upcast events, so none of them is mutated.
+      const mailAccountMigrations = [
+        {
+          fromVersion: 1,
+          toVersion: 2,
+          transform: { default: { lastError: null, trustedAuthservId: null } },
+        },
+      ] as const;
       r.defineEvent(MAIL_ACCOUNT_CONNECTED_EVENT_SHORT, mailAccountEventPayloadSchema, {
         piiFields: "none",
+        version: 2,
+        migrations: mailAccountMigrations,
       });
       r.defineEvent(MAIL_ACCOUNT_UPDATED_EVENT_SHORT, mailAccountEventPayloadSchema, {
         piiFields: "none",
+        version: 2,
+        migrations: mailAccountMigrations,
       });
       r.defineEvent(MAIL_ACCOUNT_DISCONNECTED_EVENT_SHORT, mailAccountEventPayloadSchema, {
         piiFields: "none",
+        version: 2,
+        migrations: mailAccountMigrations,
       });
+      // v1 mails carry the snippet only: bodyText "" and contentState "snippet" let the content
+      // refetch find them. v3 adds the reason a message has no content.
       r.defineEvent(INBOUND_MESSAGE_RECEIVED_EVENT_SHORT, inboundMessageEventPayloadSchema, {
         piiFields: "none",
+        version: 3,
+        migrations: [
+          {
+            fromVersion: 1,
+            toVersion: 2,
+            transform: {
+              default: {
+                bodyText: "",
+                bodyTextTruncated: false,
+                attachmentFileIds: [],
+                skippedAttachments: [],
+                contentState: "snippet",
+                senderAuthentication: null,
+              },
+            },
+          },
+          {
+            fromVersion: 2,
+            toVersion: 3,
+            transform: { default: { contentUnavailableReason: null } },
+          },
+        ],
       });
+      r.defineEvent(
+        INBOUND_MESSAGE_CONTENT_FETCHED_EVENT_SHORT,
+        inboundMessageContentFetchedEventPayloadSchema,
+        {
+          piiFields: "none",
+          version: 3,
+          migrations: [
+            {
+              fromVersion: 1,
+              toVersion: 2,
+              transform: { default: { contentUnavailableReason: null } },
+            },
+            {
+              fromVersion: 2,
+              toVersion: 3,
+              transform: { default: { accountId: null, ownerUserId: null } },
+            },
+          ],
+        },
+      );
       r.defineEvent(MAIL_THREAD_UPDATED_EVENT_SHORT, mailThreadEventPayloadSchema, {
         piiFields: "none",
       });
 
-      // Inline projections — apply in the same transaction as the append.
       r.projection({
         name: "mail-account",
         source: MAIL_ACCOUNT_AGGREGATE_TYPE,
@@ -156,6 +211,7 @@ export function createInboundMailFoundationFeature() {
         entity: inboundMessageEntity,
         apply: {
           [INBOUND_MESSAGE_RECEIVED_EVENT_QN]: applyInboundMessageReceived,
+          [INBOUND_MESSAGE_CONTENT_FETCHED_EVENT_QN]: applyInboundMessageContentFetched,
         },
       });
       r.projection({
@@ -168,6 +224,8 @@ export function createInboundMailFoundationFeature() {
         },
       });
 
+      registerMailAccountWakeConsumer(r);
+
       // Plugin extension point — providers register via
       // r.useExtension("inboundMailProvider", "<key>", plugin).
       r.extendsRegistrar(INBOUND_MAIL_PROVIDER_EXTENSION, {
@@ -187,22 +245,34 @@ export function createInboundMailFoundationFeature() {
         reason: "read_side.mail_seen_messages_direct_write",
       });
 
-      // Write-Handler:
-      //   - ingest-message: programmatic (Supervisor/Poll, SystemAdmin)
-      //   - connect/update/disconnect-account: Lifecycle
+      r.storeTable(quarantineTable, {
+        reason: "read_side.mail_quarantine_direct_write",
+      });
+      r.storeTable(ingestFailureTable, {
+        reason: "read_side.mail_ingest_failures_direct_write",
+      });
+
+      // ingest-message is programmatic (supervisor/poll, SystemAdmin); the rest is account lifecycle.
       r.writeHandler(ingestMessageHandler);
-      r.writeHandler(connectAccountHandler);
-      r.writeHandler(updateAccountHandler);
-      r.writeHandler(disconnectAccountHandler);
+      r.writeHandler(createConnectAccountHandler(roles));
+      r.writeHandler(createUpdateAccountHandler(roles));
+      r.writeHandler(createDisconnectAccountHandler(roles));
+      r.writeHandler(createReactivateAccountHandler(roles));
+      r.writeHandler(createSetTrustedAuthservIdHandler(roles));
+      r.writeHandler(createAcknowledgeQuarantineHandler(roles));
+      r.writeHandler(createRetryQuarantinedMessageHandler(roles));
+      r.writeHandler(attachMessageContentHandler);
+      r.writeHandler(markCredentialStoredHandler);
 
-      // List-Queries (PII-decrypted, scope-gefiltert).
-      r.queryHandler(listAccountsQuery);
-      r.queryHandler(listMessagesQuery);
+      r.queryHandler(createListAccountsQuery(roles));
+      r.queryHandler(createListMessagesQuery(roles));
+      r.queryHandler(createListQuarantineQuery(roles));
+      r.queryHandler(createMessageContentQuery(roles));
+      r.queryHandler(createMessageDetailQuery(roles));
 
-      // Declarative mailbox admin: list (rename, disconnect) and rename form.
-      // The app places `mailAccountListScreen` via r.nav in its settings area.
-      r.screen(mailAccountListScreen);
-      r.screen(mailAccountEditScreen);
+      // The app places the mailbox lists via r.nav (admins in settings, users next to their connect flow).
+      for (const screen of createMailAccountScreens(roles)) r.screen(screen);
+      r.screen(createMailQuarantineScreen(roles));
       r.translations({ keys: INBOUND_MAIL_FOUNDATION_I18N });
       registerMailboxProbe(r);
 
@@ -221,64 +291,9 @@ export function createInboundMailFoundationFeature() {
         escapeHatch: { reason: INBOUND_MAIL_TENANT_DESTROY_ARCHIVE_REASON },
       });
 
-      // Data-Retention — perTenant fan-out (one run per tenant, like
-      // data-retention:retention-cleanup): runInboundMailRetention's raw query
-      // helpers need the unfiltered runner, so the handler declares escapeHatch
-      // and reaches for ctx.db.unsafeRaw(). Without this cron, read_inbound_messages
-      // + the bodies grow unbounded (GDPR Art. 5).
-      const INBOUND_MAIL_RETENTION_REASON =
-        "inbound-mail retention runs raw deletes; every statement filters by this run's tenantId";
-      r.job({
-        name: "inbound-mail-retention",
-        trigger: { cron: "0 3 * * *" },
-        perTenant: true,
-        concurrency: "skip",
-        escapeHatch: { reason: INBOUND_MAIL_RETENTION_REASON },
-        handler: async (_payload, ctx) => {
-          if (!ctx.registry) {
-            throw new Error(
-              "inbound-mail-retention: ctx.registry required (JobContext incomplete)",
-            );
-          }
-          const tenantId = ctx.systemUser?.tenantId ?? ctx._tenantId;
-          if (tenantId === undefined) {
-            // skip: cron fired without a perTenant fan-out tenant — nothing scoped
-            return;
-          }
-          const T = (await import("@cosmicdrift/kumiko-framework/time")).getTemporal();
-          const retentionDb = ctx.db.unsafeRaw() as DbConnection; // @cast-boundary db-operator — jobs never run inside a DbTx
-
-          // Body objects are stored in file-foundation. The provider is lazy and memoized —
-          // ingest currently writes no bodyRef (the storeBody hook is not wired),
-          // so the provider is never built. Once storeBody is wired, retention
-          // also cleans up the bodies.
-          let providerPromise: Promise<FileStorageProvider> | null = null;
-          const deleteBodyObject = async (bodyRef: string): Promise<void> => {
-            if (!providerPromise) {
-              providerPromise = createFileProviderForTenant(
-                { config: ctx.config, registry: ctx.registry, secrets: ctx.services.secrets },
-                tenantId,
-              );
-            }
-            const provider = await providerPromise;
-            await provider.delete(bodyRef);
-          };
-
-          const report = await runInboundMailRetention({
-            db: retentionDb,
-            tenantId,
-            now: T.Now.instant(),
-            deleteBodyObject,
-          });
-          if (report.bodyObjectErrors > 0) {
-            // biome-ignore lint/suspicious/noConsole: operator-visibility for failed body deletes
-            console.warn(
-              `[inbound-mail-foundation:inbound-mail-retention] tenant=${tenantId} bodyObjectErrors=${report.bodyObjectErrors}`,
-            );
-          }
-        },
-      });
+      registerInboundMailRetentionJob(r);
+      return { roles };
     },
-    { dedupeOptions: {} },
+    { dedupeOptions: roleDedupeOptions(roles) },
   );
 }

package/packages/bundled-features/src/inbound-mail-foundation/file-storage-failure.ts

@@ -0,0 +1,23 @@
+import { KumikoError } from "@cosmicdrift/kumiko-framework/errors";
+import { errorCodeOf } from "@cosmicdrift/kumiko-types/type-guards";
+
+export const FILE_STORAGE_WRITE_FAILED_CODE = "file_storage_write_failed";
+
+// Own code on purpose: the supervisor treats validation/unprocessable as a poison mail and
+// quarantines it, but a storage outage says nothing about the mail.
+export class FileStorageWriteFailedError extends KumikoError {
+  readonly code = FILE_STORAGE_WRITE_FAILED_CODE;
+  readonly httpStatus = 503;
+
+  constructor(cause?: Error) {
+    super({
+      message: "inbound mail content could not be written to file storage",
+      i18nKey: "errors.internal",
+      ...(cause && { cause }),
+    });
+  }
+}
+
+export function isFileStorageWriteFailure(error: unknown): boolean {
+  return errorCodeOf(error) === FILE_STORAGE_WRITE_FAILED_CODE;
+}

package/packages/bundled-features/src/inbound-mail-foundation/handlers/account-address.ts

@@ -0,0 +1,79 @@
+// Address lookup across the tenant's mailboxes. Addresses are ciphertext in the projection, so the
+// comparison happens in memory after decrypting (a tenant has a handful of mailboxes).
+
+import {
+  configuredPiiSubjectKms,
+  decryptPiiFieldValues,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import { InboundMailAccountStatuses, InboundMailAuthMethods } from "../constants.ts";
+import { MAIL_ACCOUNT_PII_FIELDS } from "../entities.ts";
+import { mailAccountsProjectionTable } from "../projection.ts";
+
+export type AddressMatch = {
+  readonly id: string;
+  readonly provider: string;
+  readonly authMethod: string;
+  readonly ownerUserId: string | null;
+  readonly status: string;
+};
+
+export function normalizeMailAddress(address: string): string {
+  return address.trim().toLowerCase();
+}
+
+function textOf(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+// A live mailbox wins over a disconnected one: connecting next to a live mailbox is always a duplicate.
+export async function findMailboxByAddress(
+  ctx: Pick<HandlerContext, "db">,
+  tenantId: string,
+  address: string,
+): Promise<AddressMatch | undefined> {
+  const wanted = normalizeMailAddress(address);
+  const rows = await ctx.db.selectMany(mailAccountsProjectionTable, { tenantId });
+  const piiKms = configuredPiiSubjectKms();
+  const matches: AddressMatch[] = [];
+  for (const row of rows) {
+    const readable = piiKms
+      ? await decryptPiiFieldValues(row, MAIL_ACCOUNT_PII_FIELDS, piiKms, {
+          requestId: `inbound-mail-foundation:connect-account:${tenantId}`,
+        })
+      : row;
+    if (normalizeMailAddress(textOf(readable["address"])) !== wanted) continue;
+    matches.push({
+      id: textOf(row["id"]),
+      provider: textOf(row["provider"]),
+      authMethod: textOf(row["authMethod"]),
+      ownerUserId: typeof row["ownerUserId"] === "string" ? row["ownerUserId"] : null,
+      status: textOf(row["status"]),
+    });
+  }
+  return matches.find((m) => m.status !== InboundMailAccountStatuses.disconnected) ?? matches[0];
+}
+
+export type ConnectConflict = "already_connected" | "address_disconnected" | "reopen_in_place";
+
+// A disconnected or sign-in-failed OAuth mailbox of the same provider and owner is reopened (the
+// callback writes the new token into the same slot); everything else must not silently create a second stream for one address.
+export function connectConflictOf(
+  existing: AddressMatch,
+  wanted: {
+    readonly authMethod: string;
+    readonly provider: string;
+    readonly ownerUserId: string | null;
+  },
+): ConnectConflict {
+  const disconnected = existing.status === InboundMailAccountStatuses.disconnected;
+  // A sign-in error of an OAuth mailbox is healed by signing in again, so it reopens like a disconnect.
+  const signInFailed = existing.status === InboundMailAccountStatuses.authError;
+  if (!disconnected && !signInFailed) return "already_connected";
+  const bothOauth =
+    wanted.authMethod === InboundMailAuthMethods.oauth &&
+    existing.authMethod === InboundMailAuthMethods.oauth &&
+    existing.provider === wanted.provider;
+  if (!bothOauth) return disconnected ? "address_disconnected" : "already_connected";
+  return existing.ownerUserId === wanted.ownerUserId ? "reopen_in_place" : "already_connected";
+}

package/packages/bundled-features/src/inbound-mail-foundation/handlers/acknowledge-quarantine.write.ts

@@ -0,0 +1,55 @@
+// acknowledge-quarantine — the mailbox owner (an admin for a shared mailbox) has seen quarantined mails. Open entries (all of
+// the mailbox, or just one when providerMessageId is given) are marked acknowledged; once none is left
+// the supervisor returns the mailbox to active.
+
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  AccessDeniedError,
+  failNotFound,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import * as z from "zod";
+import type { InboundMailRoles } from "../mail-roles.ts";
+import { quarantineTable } from "../quarantine-entities.ts";
+import { loadCurrentMailAccountPayload } from "./account-state.ts";
+import { mayManageQuarantine } from "./scope-visibility.ts";
+
+export const acknowledgeQuarantineSchema = z.object({
+  accountId: z.uuid(),
+  providerMessageId: z.string().min(1).max(500).optional(),
+});
+
+export function createAcknowledgeQuarantineHandler({
+  memberRoles,
+  adminRoles,
+}: InboundMailRoles): WriteHandlerDef {
+  return {
+    name: "acknowledge-quarantine",
+    schema: acknowledgeQuarantineSchema,
+    access: { roles: [...memberRoles] },
+    agent: { expose: false },
+    description:
+      "Marks the open quarantine entries of a mailbox as acknowledged, all of them or only the one mail named by providerMessageId, i.e. the mails the import could not take have been looked at; the mailbox leaves the interrupted state on the next sync. The owner of a personal mailbox or, for a shared one, an admin may call it. Returns the number of acknowledged entries.",
+    handler: async (event, ctx) => {
+      const payload = acknowledgeQuarantineSchema.parse(event.payload);
+      const account = await loadCurrentMailAccountPayload(ctx, payload.accountId);
+      if (!account) return failNotFound("mail-account", payload.accountId);
+      if (!mayManageQuarantine(account.ownerUserId, event.user, adminRoles)) {
+        return writeFailure(new AccessDeniedError({ details: { reason: "not_mailbox_owner" } }));
+      }
+      const updated = await ctx.db.updateMany(
+        quarantineTable,
+        { acknowledgedAt: Temporal.Now.instant().toString() },
+        {
+          accountId: payload.accountId,
+          acknowledgedAt: null,
+          ...(payload.providerMessageId !== undefined && {
+            providerMessageId: payload.providerMessageId,
+          }),
+        },
+      );
+      return { isSuccess: true as const, data: { acknowledged: updated.length } };
+    },
+  };
+}