@cosmicdrift/kumiko-samples 0.393.0 → 0.395.0

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

@@ -1,11 +1,21 @@
 import { ACTION_FORM_ENTITY } from "@cosmicdrift/kumiko-framework/ui-types";
 import { fieldLabelKey } from "@cosmicdrift/kumiko-renderer/headless";
-import { INBOUND_MAIL_FOUNDATION_FEATURE, InboundMailAccountStatuses } from "./constants.ts";
+import {
+  INBOUND_MAIL_FOUNDATION_FEATURE,
+  InboundMailAccountStatuses,
+  InboundMailConnectErrors,
+  InboundMailLastErrors,
+} from "./constants.ts";
 import { INBOUND_PROBE_I18N } from "./probe-keys.ts";
+import { QUARANTINE_REASON_OPTION_KEY_PREFIX } from "./quarantine-screens.ts";
 import {
   MAIL_ACCOUNT_EDIT_SCREEN_ID,
+  MAIL_ACCOUNT_LAST_ERROR_OPTION_KEY_PREFIX,
   MAIL_ACCOUNT_LIST_SCREEN_ID,
+  MAIL_ACCOUNT_SENDER_CHECK_SCREEN_ID,
   MAIL_ACCOUNT_STATUS_OPTION_KEY_PREFIX,
+  MAIL_QUARANTINE_SCREEN_ID,
+  MY_MAIL_ACCOUNT_LIST_SCREEN_ID,
 } from "./screens.ts";
 import { MAIL_SEND_ERRORS } from "./send-from-account.ts";
 
@@ -15,12 +25,42 @@ const formFieldKey = (field: string): string =>
 export const INBOUND_MAIL_FOUNDATION_I18N: Readonly<Record<string, { readonly en: string }>> = {
   ...INBOUND_PROBE_I18N,
   [`screen:${MAIL_ACCOUNT_LIST_SCREEN_ID}.title`]: { en: "Mailboxes" },
+  [`screen:${MY_MAIL_ACCOUNT_LIST_SCREEN_ID}.title`]: { en: "Your mailboxes" },
   [`screen:${MAIL_ACCOUNT_EDIT_SCREEN_ID}.title`]: { en: "Edit mailbox" },
+  [`screen:${MAIL_ACCOUNT_SENDER_CHECK_SCREEN_ID}.title`]: { en: "Sender check" },
+  [`screen:${MAIL_QUARANTINE_SCREEN_ID}.title`]: { en: "Quarantined mails" },
   "inboundMail.accounts.col.name": { en: "Name" },
   "inboundMail.accounts.col.address": { en: "Address" },
   "inboundMail.accounts.col.provider": { en: "Provider" },
   "inboundMail.accounts.col.status": { en: "Status" },
   "inboundMail.accounts.col.connected": { en: "Connected" },
+  "inboundMail.accounts.col.lastError": { en: "Problem" },
+  "inboundMail.accounts.col.quarantined": { en: "Quarantined" },
+  [`${MAIL_ACCOUNT_LAST_ERROR_OPTION_KEY_PREFIX}${InboundMailLastErrors.connectionFailed}`]: {
+    en: "The mail server could not be reached. Syncing is retried automatically.",
+  },
+  [`${MAIL_ACCOUNT_LAST_ERROR_OPTION_KEY_PREFIX}${InboundMailLastErrors.rateLimited}`]: {
+    en: "The mail server is limiting requests. Syncing is retried automatically.",
+  },
+  [`${MAIL_ACCOUNT_LAST_ERROR_OPTION_KEY_PREFIX}${InboundMailLastErrors.messageQuarantined}`]: {
+    en: "A mail could not be imported and was set aside. Confirm the quarantine once you have looked into it.",
+  },
+  [`${MAIL_ACCOUNT_LAST_ERROR_OPTION_KEY_PREFIX}${InboundMailLastErrors.fileStorageUnavailable}`]: {
+    en: "File storage is not available, so attachments and originals are not saved.",
+  },
+  [`${MAIL_ACCOUNT_LAST_ERROR_OPTION_KEY_PREFIX}${InboundMailLastErrors.encryptionUnavailable}`]: {
+    en: "The key store is unavailable. New mails are fetched again in the next interval.",
+  },
+  [`${MAIL_ACCOUNT_LAST_ERROR_OPTION_KEY_PREFIX}${InboundMailLastErrors.ingestUnavailable}`]: {
+    en: "Mails cannot be imported right now. The next interval tries again.",
+  },
+  [InboundMailConnectErrors.addressAlreadyConnected.i18nKey]: {
+    en: "This mailbox is already connected.",
+  },
+  [InboundMailConnectErrors.addressDisconnected.i18nKey]: {
+    en: "This mailbox was disconnected before. Use Reactivate in the mailbox list to keep its history.",
+  },
+  "inboundMail.accounts.acknowledgeQuarantine": { en: "Confirm quarantine" },
   [`${MAIL_ACCOUNT_STATUS_OPTION_KEY_PREFIX}${InboundMailAccountStatuses.active}`]: {
     en: "Active",
   },
@@ -34,9 +74,41 @@ export const INBOUND_MAIL_FOUNDATION_I18N: Readonly<Record<string, { readonly en
     en: "Disconnected",
   },
   "inboundMail.accounts.connectImap": { en: "Connect mailbox" },
-  "inboundMail.accounts.reconnect": { en: "Reconnect" },
+  "inboundMail.accounts.reactivateOauth.confirm": {
+    en: "You are taken to the provider's sign-in page. After signing in, the mailbox fetches mail again and keeps its history.",
+  },
+  "inboundMail.accounts.reconnect.invalidRow": {
+    en: "This mailbox cannot be reactivated from here.",
+  },
+  "inboundMail.accounts.reactivate": { en: "Reactivate" },
+  "inboundMail.accounts.quarantine": { en: "Quarantine" },
+  [InboundMailConnectErrors.credentialRequired.i18nKey]: {
+    en: "This mailbox has no stored sign-in. Enter the password again to reactivate it.",
+  },
+  "inboundMail.quarantine.col.sender": { en: "Sender" },
+  "inboundMail.quarantine.col.subject": { en: "Subject" },
+  "inboundMail.quarantine.col.reason": { en: "Reason" },
+  "inboundMail.quarantine.col.mailbox": { en: "Mailbox" },
+  "inboundMail.quarantine.col.date": { en: "Set aside" },
+  "inboundMail.quarantine.retry": { en: "Fetch again" },
+  "inboundMail.quarantine.acknowledge": { en: "Confirm" },
+  [`${QUARANTINE_REASON_OPTION_KEY_PREFIX}unparseable`]: {
+    en: "The mail could not be read.",
+  },
+  [`${QUARANTINE_REASON_OPTION_KEY_PREFIX}invalid_message`]: {
+    en: "The mail is incomplete or invalid.",
+  },
+  [`${QUARANTINE_REASON_OPTION_KEY_PREFIX}ingest_failed`]: {
+    en: "Importing the mail failed repeatedly.",
+  },
   "inboundMail.accounts.edit": { en: "Rename" },
   "inboundMail.accounts.edit.submit": { en: "Save" },
+  "inboundMail.accounts.senderCheck": { en: "Sender check" },
+  "inboundMail.accounts.senderCheck.submit": { en: "Save" },
+  "inboundMail.accounts.senderCheckHint": {
+    en: "Identifier of the mail server from the Authentication-Results header, for example mx.example.com. Only with it the system checks whether a sender is genuine. Leave empty to turn the check off.",
+  },
+  [formFieldKey("trustedAuthservId")]: { en: "Mail server ID" },
   "inboundMail.accounts.disconnect": { en: "Disconnect" },
   "inboundMail.accounts.disconnect.confirm": {
     en: "Disconnect this mailbox? No new mail is fetched; stored mail is kept.",
@@ -58,4 +130,10 @@ export const INBOUND_MAIL_FOUNDATION_I18N: Readonly<Record<string, { readonly en
   [MAIL_SEND_ERRORS.invalidMessage.i18nKey]: {
     en: "The mail was not sent: a recipient, the subject or the reply reference is invalid.",
   },
+  [MAIL_SEND_ERRORS.attachmentInvalid.i18nKey]: {
+    en: "The mail was not sent: an attachment is no longer available.",
+  },
+  [MAIL_SEND_ERRORS.attachmentsTooLarge.i18nKey]: {
+    en: "The mail was not sent: the attachments together are larger than 18 MB.",
+  },
 };

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

@@ -0,0 +1,48 @@
+import type { InboundMailContext, MailAccountRecord } from "./types.ts";
+
+export type OAuthTokenSet = {
+  readonly accessToken: string;
+  /** ISO-Instant. TTL typisch ~1h ⇒ Foundation refresht before-poll. */
+  readonly expiresAt: string;
+  readonly refreshToken?: string;
+  readonly scopesGranted: readonly string[];
+};
+
+export type OAuthCodeExchange = OAuthTokenSet & {
+  /** Mailbox address of the account that signed in, from a token claim or the provider's profile
+   *  call. The callback refuses a mailbox whose address differs, so nobody claims someone else's. */
+  readonly accountAddress: string;
+};
+
+/**
+ * OAuth portion of the contract — OAuth providers only; imap in password
+ * mode omits `oauth`. The Foundation provides the routes
+ * (`/inbound-mail/connect`, `/inbound-mail/oauth/callback`) generically;
+ * providers MUST NOT register their own routes.
+ */
+export type InboundOAuthFlow = {
+  /** Scopes: request receive AND send in a SINGLE consent; re-consent is costly. */
+  readonly scopes: {
+    readonly receive: readonly string[];
+    readonly send?: readonly string[];
+  };
+  readonly buildAuthorizeUrl: (
+    ctx: InboundMailContext,
+    p: { readonly state: string; readonly redirectUri: string },
+  ) => Promise<string>;
+  readonly exchangeCode: (
+    ctx: InboundMailContext,
+    p: { readonly code: string; readonly redirectUri: string },
+  ) => Promise<OAuthCodeExchange>;
+  readonly refreshAccessToken: (
+    ctx: InboundMailContext,
+    account: MailAccountRecord,
+    refreshToken: string,
+    /** The foundation aborts `signal` after a hard timeout while holding a
+     *  per-account lock (a pool connection is pinned meanwhile). Providers
+     *  MUST pass it to their token-endpoint fetch; the foundation awaits the
+     *  provider's result and never drops a late one, because that could lose
+     *  a rotated refresh token. */
+    opts?: { readonly signal?: AbortSignal },
+  ) => Promise<OAuthTokenSet>;
+};

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

@@ -1,5 +1,10 @@
 // Public API of the inbound-mail-foundation bundled-feature.
 
+export {
+  type MailAccountWakeListener,
+  registerMailAccountWakeListener,
+  wakeMailAccount,
+} from "./account-wake.ts";
 export {
   inboundMessageAggregateId,
   mailThreadAggregateId,
@@ -9,15 +14,23 @@ export {
   type InboundMailConnectRoutesOptions,
 } from "./connect-routes.ts";
 export {
+  IMAP_PROVIDER_KEY,
+  INBOUND_MAIL_CONNECT_PATH,
   INBOUND_MAIL_FOUNDATION_FEATURE,
   INBOUND_MAIL_PROVIDER_EXTENSION,
+  INBOUND_MAIL_RECONNECT_OAUTH_ACTION,
   type InboundMailAccountStatus,
   InboundMailAccountStatuses,
   type InboundMailAuthMethod,
   InboundMailAuthMethods,
+  InboundMailConnectErrors,
   InboundMailFoundationHandlers,
   InboundMailFoundationQueries,
+  type InboundMailLastError,
+  InboundMailLastErrors,
   inboundCredentialSecretKey,
+  type MailAccountReactivationPath,
+  MailAccountReactivationPaths,
 } from "./constants.ts";
 export {
   INBOUND_MESSAGE_PII_FIELDS,
@@ -33,10 +46,14 @@ export {
 } from "./entities.ts";
 export {
   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,
+  type InboundMessageContentFetchedEventPayload,
   type InboundMessageEventHeaders,
   type InboundMessageEventPayload,
+  inboundMessageContentFetchedEventPayloadSchema,
   inboundMessageEventPayloadSchema,
   MAIL_ACCOUNT_AGGREGATE_TYPE,
   MAIL_ACCOUNT_CONNECTED_EVENT_QN,
@@ -55,6 +72,36 @@ export {
   mailThreadEventPayloadSchema,
 } from "./events.ts";
 export { createInboundMailFoundationFeature } from "./feature.ts";
+export { type AddressMatch, findMailboxByAddress } from "./handlers/account-address.ts";
+export {
+  type InboundMessageContent,
+  loadInboundMessageContent,
+} from "./handlers/message-content.query.ts";
+export { isMailAdmin, mayReactivateMailbox } from "./handlers/scope-visibility.ts";
+export type { InboundOAuthFlow, OAuthCodeExchange, OAuthTokenSet } from "./inbound-oauth-flow.ts";
+export { ingestFailureEntity, ingestFailureTable } from "./ingest-failures.ts";
+export {
+  assertRolesMatchFoundation,
+  DEFAULT_INBOUND_MAIL_ADMIN_ROLES,
+  DEFAULT_INBOUND_MAIL_USER_ROLES,
+  type InboundMailRoleOptions,
+  type InboundMailRoles,
+  readInboundMailRoles,
+  resolveInboundMailRoles,
+  roleDedupeOptions,
+  SYSTEM_DISPATCHED_MAIL_HANDLERS,
+} from "./mail-roles.ts";
+export {
+  INBOUND_ATTACHMENT_MAX_BYTES,
+  INBOUND_ATTACHMENTS_MAX_COUNT,
+  INBOUND_BODY_HTML_MAX_CHARS,
+  INBOUND_BODY_TEXT_MAX_CHARS,
+  INBOUND_MAIL_ATTACHMENTS_MAX_BYTES,
+  INBOUND_MISSING_SENDER,
+  INBOUND_SKIPPED_ATTACHMENTS_MAX_COUNT,
+  type NormalizedInboundMessage,
+  normalizeRawInboundMessage,
+} from "./normalize-inbound-message.ts";
 export {
   createOAuthAccessTokenManager,
   inboundRefreshTokenSecretOptions,
@@ -68,30 +115,57 @@ export {
   type VerifyOAuthStateResult,
   verifyOAuthState,
 } from "./oauth-state.ts";
+export { readableFileName } from "./outbound-attachments.ts";
 export {
   isMailSendNotConfiguredError,
   isMailSendRejectedError,
   MailSendNotConfiguredError,
   MailSendRejectedError,
+  OUTBOUND_ATTACHMENTS_MAX_BYTES,
+  type OutboundAttachment,
   type OutboundMailMessage,
   type OutboundMailSent,
   outboundMailMessageSchema,
+  type ProviderSentMail,
 } from "./outbound-mail.ts";
 export {
   inboundMessagesProjectionTable,
   mailAccountsProjectionTable,
   mailThreadsProjectionTable,
 } from "./projection.ts";
+export {
+  InboundAuthError,
+  InboundCredentialNotStoredError,
+  InboundCursorInvalidError,
+  InboundRateLimitError,
+  InboundTransientError,
+  isInboundAuthError,
+  isInboundCredentialNotStoredError,
+  isInboundCursorInvalidError,
+  isInboundRateLimitError,
+  isInboundTransientError,
+} from "./provider-errors.ts";
 export {
   resolveInboundProviderForAccount,
   resolveInboundProviderForKey,
 } from "./provider-factory.ts";
+export {
+  QUARANTINE_REASON_CODES,
+  type QuarantineReasonCode,
+  quarantineEntity,
+  quarantineTable,
+} from "./quarantine-entities.ts";
 export {
   IMAP_CONNECT_SCREEN_ID,
   IMAP_RECONNECT_SCREEN_ID,
   MAIL_ACCOUNT_EDIT_SCREEN_ID,
   MAIL_ACCOUNT_LIST_SCREEN_ID,
   MAIL_ACCOUNT_LIST_SCREEN_QN,
+  MAIL_QUARANTINE_SCREEN_ID,
+  MY_IMAP_CONNECT_SCREEN_ID,
+  MY_IMAP_RECONNECT_SCREEN_ID,
+  MY_MAIL_ACCOUNT_LIST_SCREEN_ID,
+  MY_MAIL_ACCOUNT_LIST_SCREEN_QN,
 } from "./screens.ts";
 export {
   MAIL_SEND_ERRORS,
@@ -101,26 +175,30 @@ export {
   sendMailFromAccount,
 } from "./send-from-account.ts";
 export {
-  InboundAuthError,
-  InboundCursorInvalidError,
+  fromDomainOf,
+  isSenderAuthenticated,
+  normalizeTrustedAuthservId,
+  parseSenderAuthentication,
+  SENDER_AUTH_VERDICTS,
+  type SenderAuthentication,
+  type SenderAuthVerdict,
+  senderAuthenticationSchema,
+} from "./sender-auth.ts";
+export {
+  type InboundContentFetchResult,
   type InboundFetchResult,
   type InboundMailContext,
   type InboundMailProviderPlugin,
-  type InboundOAuthFlow,
-  InboundRateLimitError,
-  InboundTransientError,
-  isInboundAuthError,
-  isInboundCursorInvalidError,
   isInboundMailProviderPlugin,
-  isInboundRateLimitError,
-  isInboundTransientError,
   type MailAccountRecord,
-  type OAuthTokenSet,
+  type RawInboundAttachment,
   type RawInboundMessage,
+  type RejectedInboundMessage,
+  type SkippedInboundAttachment,
   type SyncCursorPayload,
 } from "./types.ts";
-export {
-  createInboundMailSupervisor,
-  type InboundMailSupervisor,
-  type InboundMailSupervisorDeps,
-} from "./watch-supervisor.ts";
+export { createInboundMailSupervisor } from "./watch-supervisor.ts";
+export type {
+  InboundMailSupervisor,
+  InboundMailSupervisorDeps,
+} from "./watch-supervisor-types.ts";

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

@@ -0,0 +1,137 @@
+// Failure counter of mails the ingest could not take. Persisted, so every worker replica and every
+// restart sees the same count; a poison mail therefore reaches quarantine instead of blocking the
+// cursor of its mailbox forever. Rows carry ids only, no mail content.
+
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import {
+  deleteMany,
+  deriveEntityTableMeta,
+  fetchOne,
+  insertOnConflictDoNothing,
+  updateMany,
+} from "@cosmicdrift/kumiko-framework/db";
+import {
+  access,
+  createEntity,
+  createNumberField,
+  createTextField,
+  createTimestampField,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+
+export const MAX_COUNTED_INGEST_FAILURES = 3;
+const COMPARE_AND_SET_ATTEMPTS = 3;
+
+const technicalReference = {
+  access: { write: access.privileged },
+  personal: false,
+  reason: "technical_reference",
+} as const;
+
+export const ingestFailureEntity = createEntity({
+  table: "store_mail_ingest_failures",
+  softDelete: false,
+  indexes: [{ unique: true, columns: ["tenantId", "accountId", "providerMessageId"] }],
+  fields: {
+    accountId: createTextField({ required: true, maxLength: 36, ...technicalReference }),
+    providerMessageId: createTextField({ required: true, maxLength: 500, ...technicalReference }),
+    failureCount: createNumberField({ required: true, integer: true, default: 0 }),
+    // Double precision: epoch milliseconds divided by a short poll interval overflow a 32-bit integer.
+    lastCountedBucket: createNumberField({ required: true, default: 0 }),
+    lastFailedAt: createTimestampField({ required: true, access: { write: access.privileged } }),
+  },
+});
+
+export const ingestFailureTable = deriveEntityTableMeta(
+  "mail-ingest-failure",
+  ingestFailureEntity,
+  { source: "unmanaged" },
+);
+
+export type IngestFailureTarget = {
+  readonly tenantId: string;
+  readonly accountId: string;
+  readonly providerMessageId: string;
+};
+
+type CounterRow = { readonly failureCount: number };
+
+/** Bucket of one poll interval: replicas and overlapping polls inside the same interval count a mail once. */
+export function countBucketOf(now: Temporal.Instant, pollIntervalMs: number): number {
+  return Math.floor(now.epochMilliseconds / pollIntervalMs);
+}
+
+export function currentCountBucket(
+  now: (() => Temporal.Instant) | undefined,
+  pollIntervalMs: number,
+): number {
+  return countBucketOf((now ?? Temporal.Now.instant)(), pollIntervalMs);
+}
+
+/** The new failure count, or null when this bucket was already counted (or another worker won the race). */
+export async function countIngestFailure(
+  db: DbConnection,
+  target: IngestFailureTarget,
+  bucket: number,
+): Promise<number | null> {
+  const key = { accountId: target.accountId, providerMessageId: target.providerMessageId };
+  const lastFailedAt = Temporal.Now.instant().toString();
+  const inserted = await insertOnConflictDoNothing(
+    db,
+    ingestFailureTable,
+    {
+      id: crypto.randomUUID(),
+      tenantId: target.tenantId,
+      ...key,
+      failureCount: 1,
+      lastCountedBucket: bucket,
+      lastFailedAt,
+    },
+    { conflictKeys: ["tenantId", "accountId", "providerMessageId"] },
+  );
+  if (inserted) return 1;
+  for (let attempt = 0; attempt < COMPARE_AND_SET_ATTEMPTS; attempt++) {
+    const row = await fetchOne<CounterRow>(db, ingestFailureTable, key);
+    if (!row) return null;
+    const next = row.failureCount + 1;
+    const updated = await updateMany(
+      db,
+      ingestFailureTable,
+      { failureCount: next, lastCountedBucket: bucket, lastFailedAt },
+      { ...key, failureCount: row.failureCount, lastCountedBucket: { lt: bucket } },
+    );
+    if (updated.length > 0) return next;
+    const current = await fetchOne<CounterRow & { readonly lastCountedBucket: number }>(
+      db,
+      ingestFailureTable,
+      key,
+    );
+    // skip: this bucket is counted already, a second count would double the failure of one interval
+    if (!current || current.lastCountedBucket >= bucket) return null;
+  }
+  return null;
+}
+
+export async function hasCountedIngestFailure(
+  db: DbConnection,
+  target: IngestFailureTarget,
+): Promise<boolean> {
+  const row = await fetchOne<CounterRow>(db, ingestFailureTable, {
+    accountId: target.accountId,
+    providerMessageId: target.providerMessageId,
+  });
+  return row !== undefined;
+}
+
+export async function clearIngestFailures(
+  db: DbConnection,
+  accountId: string,
+  providerMessageIds: readonly string[],
+): Promise<void> {
+  // skip: nothing to clear
+  if (providerMessageIds.length === 0) return;
+  await deleteMany(db, ingestFailureTable, {
+    accountId,
+    providerMessageId: { in: [...providerMessageIds] },
+  });
+}

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

@@ -0,0 +1,46 @@
+// The ingest-message payload built from a provider message. Shared by the supervisor's regular
+// ingest, the header import of quarantined mails and the quarantine retry.
+
+import type { NormalizedInboundMessage } from "./normalize-inbound-message.ts";
+import type { MailAccountRecord } from "./types.ts";
+
+export function ingestPayloadOf(
+  account: MailAccountRecord,
+  msg: NormalizedInboundMessage,
+  options: {
+    readonly providerCursor: string;
+    readonly bodyRef: string;
+    readonly contentUnavailableReason?: "quarantined";
+  },
+): Record<string, unknown> {
+  return {
+    accountId: account.id,
+    ownerUserId: account.ownerUserId,
+    providerName: account.provider,
+    providerMessageId: msg.providerMessageId,
+    messageIdHeader: msg.messageIdHeader,
+    providerThreadId: msg.providerThreadId,
+    references: msg.references,
+    from: msg.from,
+    to: msg.to,
+    cc: msg.cc,
+    subject: msg.subject,
+    snippet: msg.snippet,
+    receivedAtIso: msg.receivedAtIso,
+    bodyRef: options.bodyRef,
+    scope: msg.scope,
+    providerCursor: options.providerCursor,
+    bodyText: msg.bodyText,
+    bodyTextTruncated: msg.bodyTextTruncated,
+    ...(msg.rawMime != null && { rawMime: msg.rawMime }),
+    ...(msg.bodyHtml !== null && { bodyHtml: msg.bodyHtml }),
+    attachments: msg.attachments,
+    skippedAttachments: msg.skippedAttachments,
+    ...(msg.senderAuthentication !== undefined && {
+      senderAuthentication: msg.senderAuthentication,
+    }),
+    ...(options.contentUnavailableReason !== undefined && {
+      contentUnavailableReason: options.contentUnavailableReason,
+    }),
+  };
+}

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

@@ -0,0 +1,132 @@
+import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
+import type { FeatureDefinition, Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { INBOUND_MAIL_FOUNDATION_FEATURE, InboundMailFoundationHandlers } from "./constants.ts";
+
+export type InboundMailRoleOptions = {
+  /** Roles that use their own and the shared mailboxes. Admins are always members too. */
+  readonly userRoles?: readonly string[];
+  /** Roles that administer shared mailboxes and see the metadata of personal ones. */
+  readonly adminRoles?: readonly string[];
+};
+
+export type InboundMailRoles = {
+  readonly userRoles: readonly string[];
+  readonly adminRoles: readonly string[];
+  /** admin ∪ user, deduplicated: everyone who may touch the mail feature at all. */
+  readonly memberRoles: readonly string[];
+};
+
+export const DEFAULT_INBOUND_MAIL_USER_ROLES = ["User"] as const;
+export const DEFAULT_INBOUND_MAIL_ADMIN_ROLES = [ROLES.TenantAdmin, ROLES.SystemAdmin] as const;
+
+function validatedRoles(optionName: string, roles: readonly string[]): readonly string[] {
+  if (roles.length === 0) {
+    throw new Error(`createInboundMailFoundationFeature: ${optionName} must not be empty.`);
+  }
+  if (roles.some((role) => role.trim() === "")) {
+    throw new Error(
+      `createInboundMailFoundationFeature: ${optionName} must not contain empty role names.`,
+    );
+  }
+  if (roles.includes("anonymous")) {
+    throw new Error(
+      `createInboundMailFoundationFeature: ${optionName} must not contain "anonymous": mail is only readable by members of the tenant.`,
+    );
+  }
+  return [...roles];
+}
+
+// Handlers the supervisor, the account health, the OAuth callback and the refresh job dispatch as the
+// system user (SystemAdmin). Every new system dispatch must target one of these; a test scans the
+// sources for it.
+export const SYSTEM_DISPATCHED_MAIL_HANDLERS: readonly string[] = [
+  InboundMailFoundationHandlers.ingestMessage,
+  InboundMailFoundationHandlers.connectAccount,
+  InboundMailFoundationHandlers.updateAccount,
+  InboundMailFoundationHandlers.reactivateAccount,
+  InboundMailFoundationHandlers.markCredentialStored,
+  InboundMailFoundationHandlers.attachMessageContent,
+];
+
+// An app whose adminRoles/memberRoles leave SystemAdmin out would see every system dispatch refused.
+// Only handler access lists use this; isMailAdmin and screens keep the configured roles.
+export function accessRolesOf(handlerQn: string, roles: readonly string[]): string[] {
+  return SYSTEM_DISPATCHED_MAIL_HANDLERS.includes(handlerQn)
+    ? [...new Set([...roles, ROLES.SystemAdmin])]
+    : [...roles];
+}
+
+export function resolveInboundMailRoles(options: InboundMailRoleOptions = {}): InboundMailRoles {
+  const userRoles = validatedRoles(
+    "userRoles",
+    options.userRoles ?? DEFAULT_INBOUND_MAIL_USER_ROLES,
+  );
+  const adminRoles = validatedRoles(
+    "adminRoles",
+    options.adminRoles ?? DEFAULT_INBOUND_MAIL_ADMIN_ROLES,
+  );
+  return { userRoles, adminRoles, memberRoles: [...new Set([...adminRoles, ...userRoles])] };
+}
+
+// dedupeOptions accept primitives only: equal role sets collapse, differing ones fail at boot.
+export function roleDedupeOptions(roles: InboundMailRoles): Readonly<Record<string, string>> {
+  return {
+    userRoles: [...roles.userRoles].sort().join(","),
+    adminRoles: [...roles.adminRoles].sort().join(","),
+  };
+}
+
+function isStringArray(value: unknown): value is readonly string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function isInboundMailRoles(value: unknown): value is InboundMailRoles {
+  return (
+    isPlainObject(value) &&
+    isStringArray(value["userRoles"]) &&
+    isStringArray(value["adminRoles"]) &&
+    isStringArray(value["memberRoles"])
+  );
+}
+
+function inboundMailRolesOfFeature(feature: FeatureDefinition): InboundMailRoles | undefined {
+  const exported = feature.exports;
+  return isPlainObject(exported) && isInboundMailRoles(exported["roles"])
+    ? exported["roles"]
+    : undefined;
+}
+
+export function readInboundMailRoles(registry: Registry): InboundMailRoles {
+  const feature = registry.features.get(INBOUND_MAIL_FOUNDATION_FEATURE);
+  return (feature && inboundMailRolesOfFeature(feature)) ?? resolveInboundMailRoles();
+}
+
+function sameRoleSet(a: readonly string[], b: readonly string[]): boolean {
+  return a.length === b.length && a.every((role) => b.includes(role));
+}
+
+// Provider features register forms whose dispatches the foundation's handlers answer, so roles
+// that differ from the foundation's would only surface as 403s at runtime.
+export function assertRolesMatchFoundation(
+  featureName: string,
+  roles: InboundMailRoles,
+  features: readonly FeatureDefinition[],
+): void {
+  const foundation = features.find((feature) => feature.name === INBOUND_MAIL_FOUNDATION_FEATURE);
+  const foundationRoles = foundation && inboundMailRolesOfFeature(foundation);
+  if (
+    foundationRoles !== undefined &&
+    !(
+      sameRoleSet(foundationRoles.userRoles, roles.userRoles) &&
+      sameRoleSet(foundationRoles.adminRoles, roles.adminRoles)
+    )
+  ) {
+    throw new Error(
+      `${featureName}: role options differ from ${INBOUND_MAIL_FOUNDATION_FEATURE} ` +
+        `(userRoles [${roles.userRoles.join(", ")}] vs [${foundationRoles.userRoles.join(", ")}], ` +
+        `adminRoles [${roles.adminRoles.join(", ")}] vs [${foundationRoles.adminRoles.join(", ")}]). ` +
+        `Pass the same userRoles/adminRoles to ${featureName} and ${INBOUND_MAIL_FOUNDATION_FEATURE}.`,
+    );
+  }
+}