@cosmicdrift/kumiko-samples 0.393.0 → 0.395.0

package/packages/bundled-features/src/inbound-mail-foundation/connect-callback-verify.ts

@@ -0,0 +1,65 @@
+import type { SignatureExtraRouteVerifyRequest } from "@cosmicdrift/kumiko-framework/api";
+import { ExtraRouteRejection } from "@cosmicdrift/kumiko-framework/api";
+import type { Context } from "hono";
+import { errorJson } from "./connect-route-responses.ts";
+import { normalizeMailAddress } from "./handlers/account-address.ts";
+import type { OAuthCodeExchange } from "./inbound-oauth-flow.ts";
+import { type OAuthStatePayload, verifyOAuthState } from "./oauth-state.ts";
+
+export type VerifiedCallback = { readonly code: string; readonly state: OAuthStatePayload };
+
+export function verifyCallbackRequest(
+  request: SignatureExtraRouteVerifyRequest,
+  stateSecret: string,
+): VerifiedCallback {
+  const code = request.query["code"] ?? "";
+  const rawState = request.query["state"] ?? "";
+  if (!code || !rawState) {
+    throw new ExtraRouteRejection(
+      400,
+      { error: { code: "invalid_callback", message: "missing code or state" } },
+      "inbound-mail oauth callback missing code or state",
+    );
+  }
+  const verified = verifyOAuthState(rawState, stateSecret);
+  if (!verified.ok) {
+    throw new ExtraRouteRejection(
+      400,
+      { error: { code: "invalid_state", message: `state rejected: ${verified.reason}` } },
+      `inbound-mail oauth callback state rejected: ${verified.reason}`,
+    );
+  }
+  return { code, state: verified.payload };
+}
+
+// The refresh token the account needs, or the response that refuses the exchange result.
+export function refreshTokenOrRefusal(
+  c: Context,
+  state: OAuthStatePayload,
+  tokens: OAuthCodeExchange,
+): string | Response {
+  // Personal only: a shared mailbox is often an M365 shared mailbox the admin opens with their own
+  // login (delegated access). A token without access to it shows up as auth_error on the first sync.
+  if (
+    state.ownerUserId &&
+    normalizeMailAddress(tokens.accountAddress) !== normalizeMailAddress(state.mailbox)
+  ) {
+    return errorJson(
+      c,
+      403,
+      "mailbox_address_mismatch",
+      `the account you signed in with is not ${state.mailbox}; sign in with that mailbox's account`,
+    );
+  }
+  // No refresh token, no server-side sync. Consent must request offline_access (or
+  // access_type=offline); the provider's oauth block owns the scopes.
+  if (!tokens.refreshToken) {
+    return errorJson(
+      c,
+      502,
+      "no_refresh_token",
+      `provider "${state.providerKey}" returned no refresh token — check the offline-access scope in the provider's oauth.scopes`,
+    );
+  }
+  return tokens.refreshToken;
+}

package/packages/bundled-features/src/inbound-mail-foundation/connect-route-responses.ts

@@ -0,0 +1,26 @@
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+import type { Context } from "hono";
+import { InboundMailConnectErrors } from "./constants.ts";
+
+const CONNECT_CONFLICT_MESSAGES: Readonly<Record<string, string>> = {
+  [InboundMailConnectErrors.addressAlreadyConnected.reason]:
+    "this mailbox address is already connected",
+  [InboundMailConnectErrors.addressDisconnected.reason]:
+    "this mailbox was disconnected before; reconnect it from the mailbox list instead",
+};
+
+export function connectFailureResponse(c: Context, error: unknown) {
+  const reason = propertyOf(propertyOf(error, "details"), "reason");
+  const conflict = typeof reason === "string" ? CONNECT_CONFLICT_MESSAGES[reason] : undefined;
+  if (typeof reason === "string" && conflict) return errorJson(c, 409, reason, conflict);
+  return errorJson(c, 502, "account_create_failed", JSON.stringify(error ?? {}));
+}
+
+export function errorJson(
+  c: Context,
+  status: 400 | 401 | 403 | 404 | 409 | 500 | 502,
+  code: string,
+  message: string,
+) {
+  return c.json({ error: { code, message } }, status);
+}

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

@@ -13,30 +13,81 @@
 import type {
   ExtraRouteDefinition,
   SignatureExtraRouteDeps,
-  SignatureExtraRouteVerifyRequest,
   UserExtraRouteDeps,
 } from "@cosmicdrift/kumiko-framework/api";
-import { ExtraRouteRejection, signatureRoute } from "@cosmicdrift/kumiko-framework/api";
+import { signatureRoute } from "@cosmicdrift/kumiko-framework/api";
 import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import type { Context } from "hono";
 import {
+  refreshTokenOrRefusal,
+  type VerifiedCallback,
+  verifyCallbackRequest,
+} from "./connect-callback-verify.ts";
+import { connectFailureResponse, errorJson } from "./connect-route-responses.ts";
+import {
+  INBOUND_MAIL_CONNECT_PATH,
   INBOUND_MAIL_FOUNDATION_FEATURE,
   InboundMailAuthMethods,
   InboundMailFoundationHandlers,
-  inboundCredentialSecretKey,
 } from "./constants.ts";
+import { isMailAdmin } from "./handlers/scope-visibility.ts";
+import { readInboundMailRoles } from "./mail-roles.ts";
 import {
-  inboundRefreshTokenSecretOptions,
   type OAuthAccessTokenManager,
+  storeOAuthCallbackCredential,
 } from "./oauth-access-token.ts";
-import { type OAuthStatePayload, signOAuthState, verifyOAuthState } from "./oauth-state.ts";
+import { signOAuthState } from "./oauth-state.ts";
 import { resolveInboundProviderForKey } from "./provider-factory.ts";
 import type { InboundMailContext } from "./types.ts";
 
 const DEFAULT_STATE_TTL_MINUTES = 15;
-const DEFAULT_CONNECT_PATH = "/api/inbound-mail/connect";
 const DEFAULT_CALLBACK_PATH = "/inbound-mail/oauth/callback";
 
+// connect-account leaves a reopened mailbox off: switched on before its token is stored, the
+// supervisor would sync it with the old, failing credential.
+async function reactivateIfReopened(
+  c: Context,
+  deps: SignatureExtraRouteDeps,
+  tenantId: string,
+  accountId: string,
+  connected: unknown,
+): Promise<Response | undefined> {
+  if (propertyOf(connected, "reconnected") !== true) return undefined;
+  const reactivated = await deps.dispatchSystemWrite({
+    handlerQn: InboundMailFoundationHandlers.reactivateAccount,
+    tenantId,
+    payload: { accountId },
+  });
+  return reactivated.isSuccess ? undefined : connectFailureResponse(c, reactivated.error);
+}
+
+// The callback connects as a system user, so connect-account's role rules (mail member at all,
+// admin for a shared mailbox) have to hold here, before the signed state is handed out.
+function connectRoleRefusal(
+  c: Context,
+  deps: UserExtraRouteDeps,
+  scope: "user" | "shared",
+): Response | undefined {
+  const { memberRoles, adminRoles } = readInboundMailRoles(deps.registry);
+  if (!memberRoles.some((role) => deps.user.roles.includes(role))) {
+    return errorJson(
+      c,
+      403,
+      "mail_role_required",
+      `${INBOUND_MAIL_FOUNDATION_FEATURE}: connecting a mailbox needs one of the roles ${memberRoles.join(", ")}`,
+    );
+  }
+  if (scope === "shared" && !isMailAdmin(deps.user, adminRoles)) {
+    return errorJson(
+      c,
+      403,
+      "shared_mailbox_requires_admin",
+      `${INBOUND_MAIL_FOUNDATION_FEATURE}: only ${adminRoles.join(", ")} connect a shared mailbox`,
+    );
+  }
+  return undefined;
+}
+
 export type InboundMailConnectRoutesOptions = {
   /** HMAC-secret for the state param (deploy-time env — `scope:"system"`
    *  secrets don't exist in secrets-v1). */
@@ -62,36 +113,6 @@ export type InboundMailConnectRoutesOptions = {
   readonly metricsFor?: InboundMailContext["metricsFor"];
 };
 
-function errorJson(c: Context, status: 400 | 401 | 404 | 500 | 502, code: string, message: string) {
-  return c.json({ error: { code, message } }, status);
-}
-
-type VerifiedCallback = { readonly code: string; readonly state: OAuthStatePayload };
-
-function verifyCallbackRequest(
-  request: SignatureExtraRouteVerifyRequest,
-  stateSecret: string,
-): VerifiedCallback {
-  const code = request.query["code"] ?? "";
-  const rawState = request.query["state"] ?? "";
-  if (!code || !rawState) {
-    throw new ExtraRouteRejection(
-      400,
-      { error: { code: "invalid_callback", message: "missing code or state" } },
-      "inbound-mail oauth callback missing code or state",
-    );
-  }
-  const verified = verifyOAuthState(rawState, stateSecret);
-  if (!verified.ok) {
-    throw new ExtraRouteRejection(
-      400,
-      { error: { code: "invalid_state", message: `state rejected: ${verified.reason}` } },
-      `inbound-mail oauth callback state rejected: ${verified.reason}`,
-    );
-  }
-  return { code, state: verified.payload };
-}
-
 /** Builds the `entry:"user"`/`entry:"signature"` extraRoute pair. Mount via
  *  `extraRoutes: createInboundMailConnectRoutes(options)`. */
 export function createInboundMailConnectRoutes(
@@ -101,7 +122,7 @@ export function createInboundMailConnectRoutes(
 
   const connectRoute: ExtraRouteDefinition = {
     method: "GET",
-    path: options.connectPath ?? DEFAULT_CONNECT_PATH,
+    path: options.connectPath ?? INBOUND_MAIL_CONNECT_PATH,
     entry: "user",
     handler: async (c: Context, deps: UserExtraRouteDeps): Promise<Response> => {
       const providerKey = c.req.query("provider") ?? "";
@@ -116,6 +137,9 @@ export function createInboundMailConnectRoutes(
         );
       }
 
+      const refused = connectRoleRefusal(c, deps, scope);
+      if (refused) return refused;
+
       let plugin: ReturnType<typeof resolveInboundProviderForKey>;
       try {
         plugin = resolveInboundProviderForKey({ registry: deps.registry }, providerKey);
@@ -213,17 +237,8 @@ export function createInboundMailConnectRoutes(
           "token exchange with the provider failed",
         );
       }
-      if (!tokens.refreshToken) {
-        // No refresh token → no server-side sync possible. Consent must
-        // request offline_access (or access_type=offline) — the provider's
-        // oauth block owns the scopes.
-        return errorJson(
-          c,
-          502,
-          "no_refresh_token",
-          `provider "${state.providerKey}" returned no refresh token — check the offline-access scope in the provider's oauth.scopes`,
-        );
-      }
+      const refreshToken = refreshTokenOrRefusal(c, state, tokens);
+      if (typeof refreshToken !== "string") return refreshToken;
 
       // Account creation (programmatic SystemUser; the real owner comes from
       // the HMAC-verified state → ownerUserIdOverride).
@@ -240,30 +255,46 @@ export function createInboundMailConnectRoutes(
         },
       });
       if (!dispatched.isSuccess) {
-        return errorJson(c, 502, "account_create_failed", JSON.stringify(dispatched.error ?? {}));
+        return connectFailureResponse(c, dispatched.error);
       }
       const accountId = propertyOf(dispatched.data, "accountId");
       if (typeof accountId !== "string") {
         return errorJson(c, 502, "account_create_failed", "connect-account returned no accountId");
       }
 
-      // Refresh-token into the per-account secret slot (Slot = accountId).
-      // Access tokens (~1h) are never persisted — the supervisor re-mints
-      // them from the refresh token (oauth-access-token.ts).
-      if (options.oauthTokens) {
-        await options.oauthTokens.storeRefreshToken(
+      try {
+        await storeOAuthCallbackCredential(
+          options.oauthTokens,
+          deps.secrets,
           { id: accountId, tenantId: state.tenantId },
-          tokens.refreshToken,
+          tokens,
+          refreshToken,
         );
-        options.oauthTokens.primeFromExchange({ id: accountId }, tokens);
-      } else {
-        await deps.secrets.set(
-          state.tenantId,
-          inboundCredentialSecretKey(accountId),
-          tokens.refreshToken,
-          inboundRefreshTokenSecretOptions(accountId),
+      } catch {
+        return errorJson(
+          c,
+          502,
+          "credential_store_failed",
+          "the sign-in worked but its token could not be saved; the mailbox keeps its previous state, connect it again",
         );
       }
+      const refused = await reactivateIfReopened(
+        c,
+        deps,
+        state.tenantId,
+        accountId,
+        dispatched.data,
+      );
+      if (refused) return refused;
+
+      // Best effort: the account commit already woke the supervisor before the token existed.
+      // Without this event the first sync would wait for the next poll tick; a failure here
+      // only costs that delay, so the connect itself still succeeds.
+      await deps.dispatchSystemWrite({
+        handlerQn: InboundMailFoundationHandlers.markCredentialStored,
+        tenantId: state.tenantId,
+        payload: { accountId },
+      });
 
       if (options.successRedirectUrl) {
         const target = new URL(options.successRedirectUrl);

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

@@ -1,5 +1,10 @@
-// Feature name
-export const INBOUND_MAIL_FOUNDATION_FEATURE = "inbound-mail-foundation" as const;
+import { INBOUND_MAIL_FOUNDATION_FEATURE } from "./web/constants.ts";
+
+export {
+  INBOUND_MAIL_CONNECT_PATH,
+  INBOUND_MAIL_FOUNDATION_FEATURE,
+  INBOUND_MAIL_RECONNECT_OAUTH_ACTION,
+} from "./web/constants.ts";
 
 // Extension-point name for provider plugins (inbound-provider-imap,
 // inbound-provider-m365-graph, inbound-provider-gmail-rest, ...).
@@ -20,6 +25,18 @@ export const InboundMailFoundationHandlers = {
   /** Tenant admin disconnects a mailbox. The stream remains for auditing;
    *  the status becomes disconnected and the watch stops. */
   disconnectAccount: "inbound-mail-foundation:write:disconnect-account",
+  /** The only way from disconnected back to active; also clears auth_error
+   *  and degraded. update-account keeps rejecting disconnected accounts. */
+  reactivateAccount: "inbound-mail-foundation:write:reactivate-account",
+  setTrustedAuthservId: "inbound-mail-foundation:write:set-trusted-authserv-id",
+  /** Owner or admin asks for one quarantined mail to be loaded again on the next sync. */
+  retryQuarantinedMessage: "inbound-mail-foundation:write:retry-quarantined-message",
+  /** Marks all open quarantine entries of a mailbox as acknowledged. */
+  acknowledgeQuarantine: "inbound-mail-foundation:write:acknowledge-quarantine",
+  /** Supervisor-only: stores the content of an already imported snippet mail. */
+  attachMessageContent: "inbound-mail-foundation:write:attach-message-content",
+  /** OAuth callback only: the refresh token is stored now, so an active account can sync. */
+  markCredentialStored: "inbound-mail-foundation:write:mark-credential-stored",
 } as const;
 
 // Qualified query handler names.
@@ -29,6 +46,10 @@ export const InboundMailFoundationQueries = {
   /** Tenant-scoped message list (inbox cockpit). PII is decrypted on read.
    */
   listMessages: "inbound-mail-foundation:query:message:list",
+  /** Open quarantine entries of the mailboxes the caller may manage, with sender and subject from the header import. */
+  listQuarantine: "inbound-mail-foundation:query:quarantine:list",
+  /** Decrypted full text, attachment ids and content state of one message. */
+  messageContent: "inbound-mail-foundation:query:message:content",
 } as const;
 
 // Normalized account status values — provider-agnostic.
@@ -37,7 +58,7 @@ export const InboundMailAccountStatuses = {
   active: "active",
   /** Credentials or token are invalid; the tenant admin must reconnect. */
   authError: "auth_error",
-  /** Transienter Fehler, Supervisor backoff-retried. */
+  /** Interrupted: transient failure, quarantined mail, missing file storage or KMS; see lastError. */
   degraded: "degraded",
   /** Disconnected by the tenant admin; no further syncs run. */
   disconnected: "disconnected",
@@ -45,6 +66,34 @@ export const InboundMailAccountStatuses = {
 export type InboundMailAccountStatus =
   (typeof InboundMailAccountStatuses)[keyof typeof InboundMailAccountStatuses];
 
+// Why a mailbox is degraded. Codes only, never provider error text (that carries hosts/tokens).
+export const InboundMailLastErrors = {
+  connectionFailed: "connection_failed",
+  rateLimited: "rate_limited",
+  messageQuarantined: "message_quarantined",
+  fileStorageUnavailable: "file_storage_unavailable",
+  encryptionUnavailable: "encryption_unavailable",
+  ingestUnavailable: "ingest_unavailable",
+} as const;
+export type InboundMailLastError =
+  (typeof InboundMailLastErrors)[keyof typeof InboundMailLastErrors];
+
+// Business reasons of failed connect writes; connect-routes maps both to 409 with the reason code.
+export const InboundMailConnectErrors = {
+  addressAlreadyConnected: {
+    reason: "address_already_connected",
+    i18nKey: "inboundMail.accounts.errors.addressAlreadyConnected",
+  },
+  addressDisconnected: {
+    reason: "address_disconnected",
+    i18nKey: "inboundMail.accounts.errors.addressDisconnected",
+  },
+  credentialRequired: {
+    reason: "credential_required",
+    i18nKey: "inboundMail.accounts.errors.credentialRequired",
+  },
+} as const;
+
 /**
  * Tenant secret slot for an account: IMAP app password OR OAuth refresh
  * token. The provider interprets the contents according to `authMethod`.
@@ -71,6 +120,20 @@ export const InboundMailAuthMethods = {
 export type InboundMailAuthMethod =
   (typeof InboundMailAuthMethods)[keyof typeof InboundMailAuthMethods];
 
+/** Provider key of inbound-provider-imap: only its password mailboxes have a credential form. */
+export const IMAP_PROVIDER_KEY = "imap";
+
+// How a mailbox the caller may re-arm gets its credential back, computed by account:list because a
+// screen row condition cannot combine provider, auth method, status and owner.
+export const MailAccountReactivationPaths = {
+  /** The IMAP form of inbound-provider-imap (reconnect-mailbox). */
+  passwordForm: "password_form",
+  /** The provider's OAuth sign-in through the connect route; its callback reopens the account. */
+  oauthFlow: "oauth_flow",
+} as const;
+export type MailAccountReactivationPath =
+  (typeof MailAccountReactivationPaths)[keyof typeof MailAccountReactivationPaths];
+
 // **Multi-provider:** no global `provider` config key
 // (unlike mail-foundation, as with billing-foundation). A tenant can connect
 // an IMAP mailbox and an M365 mailbox in parallel; the provider is stored per

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

@@ -0,0 +1,137 @@
+// Reloads the content of mails that were imported as snippet only (event version 1, before full text
+// storage existed). Runs after a successful poll with a small per-account budget, so a large backlog
+// is worked off over several ticks without slowing the regular sync. "unavailable" is terminal:
+// mails that are gone from the server stop being candidates.
+
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { selectMany } from "@cosmicdrift/kumiko-framework/db";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { inboundMessageAggregateId } from "./aggregate-id.ts";
+import { InboundMailFoundationHandlers } from "./constants.ts";
+import { seenMessageTable } from "./entities.ts";
+import { normalizeRawInboundMessage } from "./normalize-inbound-message.ts";
+import { inboundMessagesProjectionTable } from "./projection.ts";
+import type { DispatchWrite } from "./supervisor-ingest.ts";
+import type { InboundMailContext, InboundMailProviderPlugin, MailAccountRecord } from "./types.ts";
+
+export const CONTENT_REFETCH_BUDGET_PER_TICK = 50;
+const SEEN_PAGE_SIZE = 250;
+const SEEN_MAX_PAGES = 4;
+
+type SeenRow = { readonly providerMessageId: string; readonly seenAt: Temporal.Instant };
+type MessageRow = {
+  readonly id: string;
+  readonly bodyRef?: string | null;
+  readonly contentState?: string | null;
+};
+
+function needsContent(row: MessageRow): boolean {
+  const bodyMissing = row.bodyRef === undefined || row.bodyRef === null || row.bodyRef === "";
+  return bodyMissing && (row.contentState == null || row.contentState === "snippet");
+}
+
+async function findSnippetOnlyMessageIds(
+  db: DbConnection,
+  account: MailAccountRecord,
+  windowDays: number,
+): Promise<string[]> {
+  const cutoff = Temporal.Now.instant().subtract({ hours: windowDays * 24 });
+  const found: string[] = [];
+  let before: Temporal.Instant | undefined;
+  for (
+    let page = 0;
+    page < SEEN_MAX_PAGES && found.length < CONTENT_REFETCH_BUDGET_PER_TICK;
+    page++
+  ) {
+    const seen = await selectMany<SeenRow>(
+      db,
+      seenMessageTable,
+      {
+        tenantId: account.tenantId,
+        accountId: account.id,
+        seenAt: before ? { gte: cutoff, lt: before } : { gte: cutoff },
+      },
+      {
+        fields: ["providerMessageId", "seenAt"],
+        orderBy: { col: "seenAt", direction: "desc" },
+        limit: SEEN_PAGE_SIZE,
+      },
+    );
+    if (seen.length === 0) break;
+    const aggregateToProvider = new Map(
+      seen.map((row) => [
+        inboundMessageAggregateId(account.id, row.providerMessageId),
+        row.providerMessageId,
+      ]),
+    );
+    const rows = await selectMany<MessageRow>(
+      db,
+      inboundMessagesProjectionTable,
+      { tenantId: account.tenantId, id: { in: [...aggregateToProvider.keys()] } },
+      { fields: ["id", "bodyRef", "contentState"] },
+    );
+    for (const row of rows) {
+      const providerMessageId = aggregateToProvider.get(row.id);
+      if (providerMessageId !== undefined && needsContent(row)) found.push(providerMessageId);
+    }
+    const oldest = seen[seen.length - 1];
+    if (seen.length < SEEN_PAGE_SIZE || !oldest) break;
+    before = oldest.seenAt;
+  }
+  return found.slice(0, CONTENT_REFETCH_BUDGET_PER_TICK);
+}
+
+export async function refetchSnippetOnlyMessages(args: {
+  readonly db: DbConnection;
+  readonly dispatchWrite: DispatchWrite;
+  readonly providerCtx: InboundMailContext;
+  readonly account: MailAccountRecord;
+  readonly plugin: InboundMailProviderPlugin;
+  readonly windowDays: number;
+  readonly accessToken?: string | undefined;
+  readonly signal?: AbortSignal | undefined;
+}): Promise<void> {
+  const { account, plugin, dispatchWrite } = args;
+  // skip: the provider cannot reload content.
+  if (!plugin.fetchContent) return;
+  const ids = await findSnippetOnlyMessageIds(args.db, account, args.windowDays);
+  // skip: no snippet-only mail to reload.
+  if (ids.length === 0) return;
+  const result = await plugin.fetchContent(
+    args.providerCtx,
+    account,
+    ids,
+    args.accessToken !== undefined || args.signal !== undefined
+      ? {
+          ...(args.accessToken !== undefined && { accessToken: args.accessToken }),
+          ...(args.signal !== undefined && { signal: args.signal }),
+        }
+      : undefined,
+  );
+  const attach = (providerMessageId: string, content: Record<string, unknown>) =>
+    dispatchWrite({
+      handlerQn: InboundMailFoundationHandlers.attachMessageContent,
+      tenantId: account.tenantId,
+      payload: { accountId: account.id, providerMessageId, ...content },
+    });
+  for (const raw of result.messages) {
+    const msg = normalizeRawInboundMessage(raw);
+    if (msg.bodyText === "" && msg.rawMime == null && msg.bodyHtml === null) {
+      // Nothing usable came back: attach would leave the mail at "snippet", i.e. a candidate on
+      // every tick. "unavailable" is terminal.
+      await attach(msg.providerMessageId, { outcome: "unavailable" });
+      continue;
+    }
+    await attach(msg.providerMessageId, {
+      outcome: "fetched",
+      bodyText: msg.bodyText,
+      bodyTextTruncated: msg.bodyTextTruncated,
+      ...(msg.rawMime != null && { rawMime: msg.rawMime }),
+      ...(msg.bodyHtml !== null && { bodyHtml: msg.bodyHtml }),
+      attachments: msg.attachments,
+      skippedAttachments: msg.skippedAttachments,
+    });
+  }
+  const gone = [...result.missing, ...result.rejected.map((r) => r.providerMessageId)];
+  for (const providerMessageId of gone) await attach(providerMessageId, { outcome: "unavailable" });
+}

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

@@ -0,0 +1,5 @@
+// Provider errors can embed token or response data in `message`; logs carry
+// only the error class.
+export function describeError(err: unknown): string {
+  return err instanceof Error ? err.name : typeof err;
+}

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

@@ -2,7 +2,10 @@ import { collectPiiSubjectFields } from "@cosmicdrift/kumiko-framework/crypto";
 import { deriveEntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
 import {
   access,
+  createBooleanField,
   createEntity,
+  createFilesField,
+  createLongTextField,
   createNumberField,
   createTextField,
   createTimestampField,
@@ -64,7 +67,15 @@ export const mailAccountEntity = createEntity({
       personal: false,
       reason: "technical_reference",
     }),
+    // Code of InboundMailLastErrors, never provider error text. Null on rows from before the column.
+    lastError: createTextField({ maxLength: 50, personal: false, reason: "technical_reference" }),
     watchState: createTextField({ maxLength: 100, personal: false, reason: "technical_reference" }),
+    // Lower-case authserv-id of the mailbox's own server; null = none set.
+    trustedAuthservId: createTextField({
+      maxLength: 255,
+      personal: false,
+      reason: "technical_reference",
+    }),
     connectedAt: createTimestampField({ required: true }),
   },
 });
@@ -82,8 +93,7 @@ export const inboundMessageEntity = createEntity({
       reason: "technical_reference",
     }),
     // Scope is inherited from the account at ingest time: messages from a
-    // personal mailbox are visible only to the owner (+ TenantAdmin),
-    // without joining read_mail_accounts.
+    // personal mailbox are visible only to the owner, without joining read_mail_accounts.
     ownerUserId: createTextField({ maxLength: 36, personal: false, reason: "pseudonymous_fk" }),
     messageIdHeader: createTextField({
       required: true,
@@ -106,7 +116,40 @@ export const inboundMessageEntity = createEntity({
     receivedAt: createTimestampField({ required: true }),
     bodyRef: createTextField({ maxLength: 500, personal: false, reason: "technical_reference" }),
     scope: createTextField({ maxLength: 200, personal: false, reason: "technical_reference" }),
+    // Full plaintext, capped at 32_000 characters before encryption (ciphertext is ~2.3x plus envelope).
+    // Null on rows from before the column; list-messages never selects it.
+    bodyText: createLongTextField({ maxLength: 200_000, personal: "tenant", find: "none" }),
+    bodyTextTruncated: createBooleanField(),
+    // Bound to the message (entityType = the aggregate type), so the file guard answers with the
+    // mail's visibility. The fileRefs are bound at ingest, the projection copies the ids.
+    attachmentFileIds: createFilesField({ personal: false, reason: "technical_reference" }),
+    // JSON-stringified SkippedInboundAttachment[]: nullable JSON stays a text column
+    // (jsonb fields are NOT NULL), like to/cc.
+    skippedAttachments: createTextField({
+      maxLength: 20_000,
+      personal: false,
+      reason: "technical_reference",
+    }),
+    // JSON-stringified SenderAuthentication or "null"; a SQL null (rows from before the column) reads as null.
+    senderAuthentication: createTextField({
+      maxLength: 4000,
+      personal: false,
+      reason: "technical_reference",
+    }),
+    // "complete" | "snippet" | "unavailable"; null counts as "snippet".
+    contentState: createTextField({
+      maxLength: 20,
+      personal: false,
+      reason: "technical_reference",
+    }),
+    // One of INBOUND_CONTENT_UNAVAILABLE_REASONS; null while the content is there or not yet missing.
+    contentUnavailableReason: createTextField({
+      maxLength: 30,
+      personal: false,
+      reason: "technical_reference",
+    }),
   },
+  attachedFileAccess: "record-only",
 });
 
 /** Thread-Rollup. PK = aggregateId = mailThreadAggregateId(tenantId,