@cosmicdrift/kumiko-samples 0.392.2 → 0.394.0

package/packages/bundled-features/src/inbound-mail-foundation/changes.json

@@ -1,4 +1,159 @@
 [
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Imported mails store full text, original and attachments",
+    "detail": "ingest-message now takes bodyText (at most 32,000 characters, cut with bodyTextTruncated set; 32,000 keeps a long mail readable while one event, one projection row and the PII-encrypted column stay small, the original keeps everything), rawMime, bodyHtml, attachments (at most 50) and skippedAttachments (at most 200). The original is stored as .eml (or .html for HTML-only mails) and each attachment as a file reference through file storage; apps without a file provider still import the mail, mark contentState unavailable and show the mailbox as interrupted. The event inbound-message-received is now v2 with an upcast that defaults the new fields; bodyText is personal tenant data. The new query inbound-mail-foundation:query:message:content returns text, original reference and attachments of one mail; message:list never carries the body. Retention removes the mail row, its body object and its attachment files. RawInboundMessage gains text, html, attachments and skippedAttachments."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "A mail that cannot be parsed is quarantined instead of blocking the mailbox",
+    "detail": "A mail the provider reports as rejected, or whose ingest fails, is normalized where possible and otherwise stored in the unmanaged table store_mail_quarantine; every message is isolated in the supervisor, so the rest of the batch imports and the sync cursor moves on. An ingest failure only counts against a mail once a later mail of the batch succeeded, and the third counted failure quarantines it as ingest_failed; an outage of the database, KMS or file storage never quarantines good mail and never moves the cursor past an unhandled mail. The account list shows quarantinedCount and lastError, the new handler acknowledge-quarantine confirms the entries, acknowledged entries are purged by retention after 90 days, and the tenant-destroy hook removes them."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "A mailbox that stops syncing shows as interrupted with a reason",
+    "detail": "The account events mail-account-connected and mail-account-updated are v2 with lastError (connection_failed, rate_limited, message_quarantined, file_storage_unavailable). Three failed polls in a row set the status degraded, shown as Unterbrochen in German; the next successful poll sets it back to active. New key in all locale packages."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "A disconnected mailbox is reactivated under the same account",
+    "detail": "The new handler reactivate-account puts a disconnected mailbox back to active with its stream and sync cursor, so no mail is imported twice. connect-account refuses an address that is already connected (address_already_connected) or disconnected (address_disconnected) and reopens a disconnected OAuth mailbox in place; connect-routes answers 409 with the reason. reconnect-mailbox now also accepts a disconnected account."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Snippet-only mails get their content reloaded",
+    "detail": "Mails imported before this change carry only a snippet. The supervisor asks the provider for their content through fetchContent and stores it with attach-message-content (event inbound-message-content-fetched v1); a mail the server no longer has becomes unavailable and is not asked for again."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Connected, reconnected and reactivated mailboxes sync immediately",
+    "detail": "A per-instance event consumer wakes the supervisor on a new or active-again mailbox, which syncs once right away instead of waiting for the next poll. A sync of one account never runs twice at the same time. A woken sync that finds the credential not stored yet (the OAuth secret is written after the account) sets no status and leaves it to the next tick; stop() waits for running syncs."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "The first sync after an OAuth connect no longer waits for the next poll",
+    "detail": "The OAuth callback now dispatches the internal handler mark-credential-stored once the refresh token is saved, so the sync that the account commit triggers earlier than the token is repeated as soon as the credential exists. Originals above 50 MB are not stored; they are listed in skippedAttachments as message/rfc822 with reason too_large while text and attachments are kept. attach-message-content no longer accepts a caller-supplied bodyRef."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Outgoing mail carries attachments",
+    "detail": "sendMailFromAccount takes attachmentFileIds (at most 10 file references of the caller's tenant, at most 18 MB together, duplicates dropped). The bytes are read through file storage and sent over SMTP and stored in the sent folder unchanged; an unknown or foreign file gives mail_send_attachment_invalid, too many bytes mail_send_attachments_too_large, and nothing is sent. The plugin method send now receives the resolved attachments as a fourth argument and returns ProviderSentMail. New keys in all locale packages."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "A hanging mailbox no longer blocks the others",
+    "detail": "The supervisor syncs up to 4 accounts at the same time (pollConcurrency), skips an account whose previous sync is still running, and abandons a sync after 10 minutes (accountPollDeadlineMs) as one failed poll; plugin.fetch and plugin.fetchContent receive an AbortSignal, and an abandoned sync stores nothing and moves no cursor. The IMAP client sets connection (20 s) and greeting (16 s) timeouts explicitly."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Sender authentication (SPF, DKIM, DMARC) of imported mails",
+    "detail": "inbound-message-received v2 carries senderAuthentication ({ authservId, spf, dkim, dkimDomains, dmarc, fromDomain } or null; verdicts pass, fail, none, unknown; dkimDomains at most 10), stored as JSON text in read_inbound_messages.sender_authentication and returned by message:content and loadInboundMessageContent; isSenderAuthenticated is true only for a dmarc pass. The mail account has a new optional trustedAuthservId (events mail-account-* v2, read_mail_accounts.trusted_authserv_id, input of connect-account, update-account, reactivate-account and the IMAP connect and reconnect forms). Only the first Authentication-Results header from the top whose authserv-id equals it counts; without an id, without such a header or when its header.from domain differs from the From domain the result is null, and a dmarc result without header.from is unknown. Headers below the trusted one are ignored, so a sender cannot inject a pass. Mails imported before, and content refetched later, have null. New keys in all locale packages."
+  },
+  {
+    "version": "0.394.0",
+    "type": "breaking",
+    "title": "Mail account handlers are stricter and the trusted authserv-id has its own handler",
+    "detail": "trustedAuthservId is no longer accepted by connect-account, update-account and reactivate-account (strict schemas reject unknown keys); set it with the new set-trusted-authserv-id (SystemAdmin, TenantAdmin, not model-callable). update-account accepts status, lastError, watchState and reason only from the system identity; connect-account is no longer exposed to agents. reactivate-account checks the account owner (unless the OAuth override is set), fails with credential_required when a password account has no stored credential, and reopens an account in place only with that override; disconnect-account deletes the stored secret. Outgoing attachments must pass the file read check of the sender, and SendMailFromAccountContext needs dispatch. New screen \"Absenderprüfung\" edits the id. The watch supervisor and the IMAP forms use mapWithConcurrency and implicit TLS on port 465 for SMTPS.",
+    "migration": "Drop trustedAuthservId from connect-account, update-account and reactivate-account payloads and dispatch set-trusted-authserv-id after connecting. Wrapping or agent setups that called connect-account as a model tool need their own exposed handler. Callers of sendMailFromAccount pass a context that includes dispatch. Personal mailboxes are reactivated by their owner only; after disconnect-account a new credential must be stored before reactivate-account."
+  },
+  {
+    "version": "0.394.0",
+    "type": "breaking",
+    "title": "The mailbox row action Reconnect is folded into Reactivate",
+    "detail": "The row action reconnect of mailAccountListScreen and its i18n key inboundMail.accounts.reconnect are removed. A password IMAP mailbox with a sign-in error now shows Reactivate, which opens the same screen mail-account-reconnect-imap; OAuth mailboxes get the client action reactivate-oauth instead.",
+    "migration": "Apps that override inboundMail.accounts.reconnect move the text to inboundMail.accounts.reactivate. Apps that reference the row action id reconnect (tests, screen extensions) use reactivate for password IMAP and reactivate-oauth for OAuth mailboxes, and mount inboundMailFoundationClient() from @cosmicdrift/kumiko-bundled-features/inbound-mail-foundation/web so the OAuth action runs."
+  },
+  {
+    "version": "0.394.0",
+    "type": "breaking",
+    "title": "The OAuth callback only connects a personal mailbox for the account that signed in",
+    "detail": "InboundOAuthFlow.exchangeCode returns OAuthCodeExchange, an OAuthTokenSet with the required accountAddress of the signed-in provider account. The callback compares it with the mailbox address, ignoring case, and answers 403 mailbox_address_mismatch with a plain-text message and no account when they differ, so nobody can claim another person's address. This applies to personal mailboxes; a shared mailbox (only admins start that flow) is often opened with the admin's own login through delegated access, as with M365 shared mailboxes, so its address is not compared, and a token without access to it shows auth_error on the first sync.",
+    "migration": "Inbound providers with an oauth block return accountAddress from exchangeCode, taken from the token's email claim or the provider's profile endpoint (for example the userinfo email). There is no default: a provider that cannot name the signed-in address cannot connect mailboxes."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Failing ingests are counted and a poison mail is quarantined after three intervals",
+    "detail": "The supervisor counts an ingest failure once per poll interval in the unmanaged table store_mail_ingest_failures, but only when another mail of the account went through in the same poll (for a storage failure another storage write); at three it quarantines the mail with reason ingest_failed and moves the cursor on, before that the batch stops and nothing behind it is skipped. A failure nothing proves to be the mail's (KMS, file storage, the app's storeBody hook, the ingest handler or projection failing for every mail) counts nothing (when every failure of a poll was counted before as a storage or ingest failure, they all keep counting), keeps the cursor and sets the account to degraded with lastError encryption_unavailable, file_storage_unavailable or ingest_unavailable; the next interval retries. An account the supervisor cannot poll because the key store fails while decrypting its address is set to encryption_unavailable too, instead of being skipped silently. A mail that waits for its count clears a shown encryption_unavailable or ingest_unavailable, and file_storage_unavailable once a storage write went through. A requested quarantine retry also runs while a failing mail holds the cursor; during an outage, and when a reload fails because of the provider, the KMS or file storage, the request stays and runs after the recovery. Every quarantined mail also gets a header-only entry (contentState unavailable, contentUnavailableReason quarantined); after a storage failure it goes without the original."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Quarantined mails can be retried",
+    "detail": "The write handler retry-quarantined-message (mailbox owner or admin) flags a quarantine entry; the next successful sync loads the mail again, attaches the content to the header entry or ingests it in full, and removes the entry."
+  },
+  {
+    "version": "0.394.0",
+    "type": "breaking",
+    "title": "inbound-message-received is v3 and inbound-message-content-fetched is v2",
+    "detail": "Both events carry contentUnavailableReason (null for older events through upcasters). The read table read_inbound_messages gets content_unavailable_reason, store_mail_quarantine gets retry_requested_at, and store_mail_ingest_failures is new; generate and apply a migration with `kumiko-schema generate`. ingest-message and attach-message-content upload files before their transaction when called at top level, and attach-message-content skips the upload when the mail already shows its content; inside a wrapper handler's transaction they upload in it, as before. RejectedInboundMessage may carry rawMime and headers, and an inbound provider's fetch may take filterUnknownMessageIds to skip mails that are already known.",
+    "migration": "Run `kumiko-schema generate` and apply the migration; read_inbound_messages is rebuilt from events because attachment_file_ids becomes jsonb. Consumers that read the event payloads type them against the new versions (upcasters fill contentUnavailableReason with null). To get the pre-transaction upload, trigger on inbound-message-received or inbound-message-content-fetched instead of wrapping ingest-message in an own write handler."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "A watch that starts during a sync catches up on mail that arrived before it opened",
+    "detail": "After a successful watch start the supervisor runs one catch-up poll (after a running sync finished), and a tick also starts the watch while the account is still syncing. Mail delivered between the last poll and the watch opening is imported without waiting for the poll interval. The watch start is idempotent per account."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Exports for consumers of content events and attachment names",
+    "detail": "INBOUND_MESSAGE_CONTENT_FETCHED_EVENT_QN, its payload type and schema, and readableFileName({ id, fileName }) are exported from the feature index, so an app can react to fetched content and show decrypted attachment names."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Reactivate a disconnected mailbox from the mailbox list",
+    "detail": "list-accounts returns reactivateVia per mailbox (password_form, oauth_flow or null) for a disconnected mailbox or one with a sign-in error, set only for the owner of a personal mailbox and for admins of a shared one. The mailbox list shows Reactivate for password_form; the new dormant screen my-mail-accounts (MY_MAIL_ACCOUNT_LIST_SCREEN_ID, role User) and the admin list show Reactivate for oauth_flow as the client action inbound-mail-foundation:reconnect-oauth, which goes through GET /api/inbound-mail/connect and the callback again and reopens the mailbox under its old id; apps mount it with inboundMailFoundationClient() from inbound-mail-foundation/web. The callback also reopens an OAuth mailbox with a sign-in error. It switches a reopened mailbox back on only after the new refresh token is stored; when storing fails it answers 502 credential_store_failed with a plain-text message and the mailbox keeps its previous state. reactivate-account admits the system user for this step. reactivate-account admits role User, gated by the owner rule for personal mailboxes, and requires a credential for disconnected, auth_error and degraded alike. set-trusted-authserv-id is a tenant security policy: only SystemAdmin and TenantAdmin change it, on every mailbox of the tenant including personal ones. The connect route answers 403 shared_mailbox_requires_admin when a user without admin role starts the shared flow. The row action Reconnect is folded into Reactivate (see the breaking entry). The connect-mailbox form reopens a disconnected shared IMAP mailbox of the same address under its old account id with the new password. For anything else connect-account answers with a text pointing to Reactivate, and credential_required from reactivate-account is a plain-text message. A new i18n key set (de, en, fr, es, it) is part of the locale packages."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Quarantined mails are listed with sender and subject and handled one by one",
+    "detail": "The query quarantine:list and the dormant screen mail-quarantine show the open entries of the mailboxes the caller may manage, with sender and subject from the header-only import (empty without one), reason and date; row actions fetch a mail again or confirm it. acknowledge-quarantine takes an optional providerMessageId (without it all entries of the mailbox as before) and now also admits the owner of a personal mailbox (role User). The mailbox list gets a row action Quarantine for mailboxes with open entries."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Mail attachments are bound to the mail and follow its visibility",
+    "detail": "The attachment fileRefs of an imported mail are bound to the inbound-message record (field attachmentFileIds). GET /files/:id answers with the mail's visibility: owner and admins for a personal mailbox, whoever may see the mail for a shared one. The new query inbound-message:detail ({ id }) backs that check and is not exposed to agents. Outbound attachments use the same rule (canCallerReadFileRef). Retention now also removes the attachment files of a purged mail. read_inbound_messages.attachment_file_ids is jsonb; the migration 0056 carries a table rebuild marker, so the read table is rebuilt from the events. InboundMessageContent.attachmentFileIds stays string[]."
+  },
+  {
+    "version": "0.394.0",
+    "type": "breaking",
+    "title": "Personal mail is private to its owner, roles are configurable",
+    "detail": "Admins no longer read messages, bodies, attachments or quarantine of a personal mailbox; list-accounts still shows them the account without counts. The screens and the IMAP handlers are factories (createMailAccountListScreen, createImapConnectScreen and others) taking the resolved roles instead of constants. The content-fetched event is version 3 with accountId and ownerUserId. createDefaultGuard has a fourth parameter recordOnlyEntityTypes; for those entity types the files privilegedRoles no longer read or delete attached files (shared mailboxes included), only the uploader and readers of the record do. The OAuth connect route answers 403 mail_role_required to callers without a mail role.",
+    "migration": "Apps that import mailAccountListScreen, mailAccountEditScreen, mailAccountSenderCheckScreen, myMailAccountListScreen, mailQuarantineScreen, imapConnectScreen or imapReconnectScreen call the matching create*Screen factory with resolveInboundMailRoles(). Apps with their own roles pass { userRoles, adminRoles } to createInboundMailFoundationFeature and the same options to createInboundProviderImapFeature. Callers of createDefaultGuard pass a Set of record-only entity types as fourth argument. Code that read personal mail as an admin must run as the owner; the nullable accountId and ownerUserId on content-fetched events need no action."
+  },
+  {
+    "version": "0.394.0",
+    "type": "fix",
+    "title": "Supervisor and OAuth callback writes work when the app roles leave out SystemAdmin",
+    "detail": "`update-account`, `connect-account` and `reactivate-account` are dispatched as the system user by the watch supervisor, the account health and the OAuth callback, but their access list held only the configured `adminRoles`/`memberRoles`. An app whose roles exclude SystemAdmin saw every health, watch-state and callback write refused (\"health update was rejected\"), so mailboxes never showed `degraded`. These three handlers now also accept SystemAdmin (the list is `SYSTEM_DISPATCHED_MAIL_HANDLERS`). `isMailAdmin`, screens and what real users may do stay on the configured roles."
+  },
+  {
+    "version": "0.393.0",
+    "type": "improvement",
+    "title": "The mail account list offers Reconnect for accounts with a sign-in error",
+    "detail": "A new row action Reconnect opens the screen mail-account-reconnect-imap of inbound-provider-imap. It shows for every account with status auth_error and, like the Connect mailbox button, only renders in apps that mount that provider. New export IMAP_RECONNECT_SCREEN_ID. New key in all locale packages."
+  },
+  {
+    "version": "0.393.0",
+    "type": "fix",
+    "title": "Mailbox names are stored without surrounding spaces",
+    "detail": "connect-account and update-account trim displayName before storing it, so a name pasted with a leading space no longer shows and sorts with it. connect-account still accepts an empty name as before."
+  },
   {
     "version": "0.392.2",
     "type": "fix",

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