@cosmicdrift/kumiko-samples 0.392.1 → 0.393.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.392.1",
+  "version": "0.393.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.392.1",
+  "version": "0.393.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

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

@@ -1,4 +1,28 @@
 [
+  {
+    "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",
+    "title": "Mail sync no longer fails when reading IMAP credentials",
+    "detail": "createInboundMailSupervisor builds its provider context with auditUserId defaulting to the system user. Apps that did not set auditUserId in providerCtx got an internal error on every fetch and watch because the secrets context needs an audit identity. An explicitly set auditUserId is kept."
+  },
+  {
+    "version": "0.392.2",
+    "type": "fix",
+    "title": "Mail sync finds the stored IMAP credentials under row-level security",
+    "detail": "createInboundMailSupervisor runs outside any request, so secret reads ran without a tenant scope and the application role saw no row in read_tenant_secrets. The supervisor now wraps providerCtx.secrets with tenantScopedSecrets, which the framework exports from internal/row-level-security. inbound-provider-inmemory gains requireCredentialSecretOnFetch so tests can exercise credential reads; a new integration test runs the secrets against an application-role database."
+  },
   {
     "version": "0.392.0",
     "type": "fix",

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

@@ -37,7 +37,7 @@ export const connectAccountSchema = z.object({
     InboundMailAuthMethods.xoauth2,
     InboundMailAuthMethods.oauth,
   ]),
-  displayName: z.string().max(200),
+  displayName: z.string().trim().max(200),
   /** Mailbox address in plaintext; it is encrypted here. */
   address: z.string().min(1).max(320),
   /** "shared" = shared across the tenant (info@) · "user" = the caller's

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

@@ -31,7 +31,7 @@ export const updateAccountSchema = z.object({
     .optional(),
   /** Ops-Signal ("idle", "watching", "backoff:3", ...). */
   watchState: z.string().max(100).optional(),
-  displayName: z.string().max(200).optional(),
+  displayName: z.string().trim().max(200).optional(),
   /** Audit reason for metadata.headers, honored for the system identity only
    *  ("watch_supervisor", "oauth_refresh"); user callers get a role-derived reason. */
   reason: z.string().min(1).max(100).optional(),

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

@@ -34,6 +34,7 @@ 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.edit": { en: "Rename" },
   "inboundMail.accounts.edit.submit": { en: "Save" },
   "inboundMail.accounts.disconnect": { en: "Disconnect" },

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

@@ -88,6 +88,7 @@ export {
 } from "./provider-factory.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,

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

@@ -17,6 +17,8 @@ export const MAIL_ACCOUNT_LIST_SCREEN_QN = "inbound-mail-foundation:screen:mail-
 // renderer drops a navigate action whose target screen is not mounted, so the toolbar button
 // only shows in apps that mount that provider.
 export const IMAP_CONNECT_SCREEN_ID = "mail-account-connect-imap";
+// Same reason for the row action "Reconnect" on an account with a sign-in error.
+export const IMAP_RECONNECT_SCREEN_ID = "mail-account-reconnect-imap";
 
 export const MAIL_ACCOUNT_STATUS_OPTION_KEY_PREFIX = "inboundMail.accounts.status.";
 
@@ -67,6 +69,15 @@ export const mailAccountListScreen: ProjectionListScreenDefinition = {
       params: { map: { accountId: "id", displayName: "displayName" } },
       visible: { field: "status", ne: InboundMailAccountStatuses.disconnected },
     },
+    {
+      kind: "navigate",
+      id: "reconnect",
+      label: i18nKey("inboundMail.accounts.reconnect"),
+      screen: IMAP_RECONNECT_SCREEN_ID,
+      entityId: "id",
+      // The handler rejects accounts of other providers; the row condition cannot combine fields.
+      visible: { field: "status", eq: InboundMailAccountStatuses.authError },
+    },
     {
       kind: "writeHandler",
       id: "disconnect",

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

@@ -24,7 +24,7 @@ import type { OutboundMailMessage, OutboundMailSent } from "./outbound-mail.ts";
  *   secrets  — tenant secret reads (IMAP password, OAuth refresh token)
  *   auditUserId  — audit identity for secret reads. Handler path: unset,
  *              requireSecretsContext falls back to ctx.user.id; worker/provider
- *              path: system identity set by the resolver.
+ *              path: the supervisor sets the system identity.
  *   metricsFor — metrics handle of a feature by name, same behavior as
  *              HandlerContext.metricsFor: unregistered metrics are a silent
  *              no-op instead of a throw.

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

@@ -49,7 +49,11 @@ import {
 } from "@cosmicdrift/kumiko-framework/crypto";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { fetchOne, insertOne, selectMany, updateMany } from "@cosmicdrift/kumiko-framework/db";
-import { systemScopedRunner } from "@cosmicdrift/kumiko-framework/internal/row-level-security";
+import { SYSTEM_USER_ID } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  systemScopedRunner,
+  tenantScopedSecrets,
+} from "@cosmicdrift/kumiko-framework/internal/row-level-security";
 import type { DistributedLock } from "@cosmicdrift/kumiko-framework/pipeline";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
@@ -186,17 +190,25 @@ export function createInboundMailSupervisor(
   // configured TTL — real deployments (default 90s) never hit it.
   const renewIntervalMs = Math.max(50, Math.floor((leaseTtlSeconds * 1000) / 3));
   const log = deps.log ?? (() => {});
+  // The supervisor runs outside any request: secret reads need an audit
+  // identity, and under enforced row-level security they need the account's
+  // tenant scope, or the credential row is invisible and reads as missing.
+  const providerCtx: InboundMailContext = {
+    ...deps.providerCtx,
+    auditUserId: deps.providerCtx.auditUserId ?? SYSTEM_USER_ID,
+    ...(deps.providerCtx.secrets && { secrets: tenantScopedSecrets(deps.providerCtx.secrets) }),
+  };
   const systemDb = systemScopedRunner(
     deps.db,
     "mail sync supervisor polls accounts and cursors of all tenants outside a request",
   );
   const oauthTokens =
     deps.oauthTokens ??
-    (deps.providerCtx.secrets
+    (providerCtx.secrets
       ? createOAuthAccessTokenManager({
           db: systemDb,
-          secrets: deps.providerCtx.secrets,
-          providerCtx: deps.providerCtx,
+          secrets: providerCtx.secrets,
+          providerCtx,
         })
       : undefined);
 
@@ -447,7 +459,7 @@ export function createInboundMailSupervisor(
       // exhausted.
       for (;;) {
         const accessToken = await resolveAccessToken(account, plugin);
-        const result = await plugin.fetch(deps.providerCtx, account, cursor, {
+        const result = await plugin.fetch(providerCtx, account, cursor, {
           backfillWindowDays,
           maxMessages: budget,
           filterUnknownMessageIds: unknownMessageIdsFilterFor(account),
@@ -469,7 +481,7 @@ export function createInboundMailSupervisor(
     for (const account of accounts) {
       let plugin: InboundMailProviderPlugin;
       try {
-        plugin = resolveInboundProviderForAccount(deps.providerCtx, account);
+        plugin = resolveInboundProviderForAccount(providerCtx, account);
       } catch (err) {
         log(`inbound-mail: ${describeError(err)}`);
         continue;
@@ -642,7 +654,7 @@ export function createInboundMailSupervisor(
     try {
       const accessToken = await resolveAccessToken(account, plugin);
       const stop = await plugin.watch(
-        deps.providerCtx,
+        providerCtx,
         account,
         {
           onMessages: async (msgs) => {

package/packages/bundled-features/src/inbound-provider-imap/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.393.0",
+    "type": "improvement",
+    "title": "IMAP mailboxes with a sign-in error can be reconnected",
+    "detail": "The new write handler inbound-provider-imap:write:reconnect-mailbox (TenantAdmin, SystemAdmin, not exposed to the agent, 10 calls per tenant in 10 minutes) takes the account id plus host, port, user, password and the outgoing server, checks the IMAP and SMTP login like connect-mailbox, then overwrites the credential secret of the same account and sets it back to active in one transaction. A failed check changes nothing. It answers not found for an unknown account or one of another tenant, account_disconnected for a disconnected one and reconnect_not_password_imap for other providers. The form screen mail-account-reconnect-imap is prefilled by the query inbound-provider-imap:query:reconnect-prefill with the stored server settings, never the password. New keys in all locale packages."
+  },
+  {
+    "version": "0.393.0",
+    "type": "fix",
+    "title": "IMAP forms trim the mailbox name and show ports without digit grouping",
+    "detail": "connect-mailbox trims displayName and still requires a non-empty name. The port fields of the connect and reconnect forms show 993 or 13993 instead of 13.993 in locales with digit grouping."
+  },
   {
     "version": "0.392.1",
     "type": "fix",

package/packages/bundled-features/src/inbound-provider-imap/connect-mailbox.ts

@@ -28,16 +28,19 @@ import { type SmtpFailure, SmtpFailureError, verifySmtpLogin } from "./smtp-clie
 // No `secure`: the password never crosses the wire in clear text, so a payload's secure:false is
 // stripped like any unknown key. IMAP uses implicit TLS; SMTP uses implicit TLS on 465 and
 // enforced STARTTLS on every other port.
-const connectMailboxSchema = imapCredentialDocumentSchema
+export const connectMailboxSchema = imapCredentialDocumentSchema
   .pick({ host: true, port: true, user: true })
   .extend({
-    displayName: z.string().min(1).max(200),
+    displayName: z.string().trim().min(1).max(200),
     address: z.email().max(320),
     password: z.string().min(1).max(1000),
     smtpHost: z.union([z.literal(""), smtpHostSchema]).nullish(),
     smtpPort: z.number().int().min(1).max(65535),
   });
-type ConnectMailboxPayload = z.infer<typeof connectMailboxSchema>;
+type ConnectMailboxLoginFields = Pick<
+  z.infer<typeof connectMailboxSchema>,
+  "host" | "port" | "user" | "password" | "smtpHost" | "smtpPort"
+>;
 
 const connectedAccountSchema = z.object({ accountId: z.string() });
 
@@ -47,7 +50,7 @@ const connectedAccountSchema = z.object({ accountId: z.string() });
 const TLS_FAILURE = /certificate|self[- ]signed|wrong[ _]version[ _]number|EPROTO|ERR_SSL|ERR_TLS/i;
 
 // A fixed preview: any slice of the JSON document would expose the host or the user.
-const CREDENTIAL_PREVIEW = "IMAP login";
+export const CREDENTIAL_PREVIEW = "IMAP login";
 
 const SECRET_TRANSACTION_REASON =
   "the credential secret is written on the request transaction so a failed account connect rolls it back too";
@@ -59,7 +62,7 @@ export function deriveSmtpHost(imapHost: string): string {
   return /^imap\./i.test(imapHost) ? `smtp.${imapHost.slice("imap.".length)}` : imapHost;
 }
 
-export function credentialDocumentOf(payload: ConnectMailboxPayload): ImapCredentialDocument {
+export function credentialDocumentOf(payload: ConnectMailboxLoginFields): ImapCredentialDocument {
   const { host, port, user, password, smtpPort } = payload;
   const smtpHost = payload.smtpHost || deriveSmtpHost(host);
   return { host, port, secure: true, user, password, smtpHost, smtpPort };
@@ -96,6 +99,29 @@ async function checkSmtpLogin(doc: ImapCredentialDocument): Promise<ConnectFailu
   }
 }
 
+// Checks the IMAP login, then the SMTP login of the outgoing server; shared by connect and reconnect.
+export async function checkMailboxLogin(
+  doc: ImapCredentialDocument,
+  log: { warn(message: string, data?: Record<string, unknown>): void },
+): Promise<BeforeTransactionResult<null>> {
+  try {
+    await connectOnce(doc, true);
+  } catch (err) {
+    const { reason, i18nKey } = IMAP_CONNECT_ERRORS[imapConnectFailureOf(err)];
+    log.warn("imap connect check failed", { reason });
+    return writeFailure(new UnprocessableError(reason, { i18nKey }));
+  }
+  const smtpFailure = await checkSmtpLogin(doc);
+  if (smtpFailure) {
+    const { reason, i18nKey } = SMTP_CONNECT_ERRORS[smtpFailure];
+    log.warn("smtp connect check failed", { reason });
+    return writeFailure(
+      new UnprocessableError(reason, { i18nKey, i18nParams: { port: doc.smtpPort } }),
+    );
+  }
+  return { isSuccess: true, data: null };
+}
+
 export const connectMailboxHandler = defineWriteHandler({
   name: "connect-mailbox",
   description:
@@ -108,25 +134,8 @@ export const connectMailboxHandler = defineWriteHandler({
   // used to scan ports or to guess passwords at someone else's mail server.
   rateLimit: { per: "tenant+handler", limit: 10, windowSeconds: 600 },
   escapeHatch: { grants: ["unsafeRaw"], reason: SECRET_TRANSACTION_REASON },
-  beforeTransaction: async (event, ctx): Promise<BeforeTransactionResult<null>> => {
-    const doc = credentialDocumentOf(event.payload);
-    try {
-      await connectOnce(doc, true);
-    } catch (err) {
-      const { reason, i18nKey } = IMAP_CONNECT_ERRORS[imapConnectFailureOf(err)];
-      ctx.obs.log.warn("imap connect check failed", { reason });
-      return writeFailure(new UnprocessableError(reason, { i18nKey }));
-    }
-    const smtpFailure = await checkSmtpLogin(doc);
-    if (smtpFailure) {
-      const { reason, i18nKey } = SMTP_CONNECT_ERRORS[smtpFailure];
-      ctx.obs.log.warn("smtp connect check failed", { reason });
-      return writeFailure(
-        new UnprocessableError(reason, { i18nKey, i18nParams: { port: doc.smtpPort } }),
-      );
-    }
-    return { isSuccess: true, data: null };
-  },
+  beforeTransaction: (event, ctx) =>
+    checkMailboxLogin(credentialDocumentOf(event.payload), ctx.obs.log),
   handler: async (event, ctx) => {
     const { displayName, address } = event.payload;
     const connected = await ctx.dispatch.write(InboundMailFoundationHandlers.connectAccount, {

package/packages/bundled-features/src/inbound-provider-imap/constants.ts

@@ -3,6 +3,18 @@ export const IMAP_PROVIDER_KEY = "imap";
 
 export const ImapHandlers = {
   connectMailbox: "inbound-provider-imap:write:connect-mailbox",
+  reconnectMailbox: "inbound-provider-imap:write:reconnect-mailbox",
+} as const;
+
+export const ImapQueries = {
+  reconnectPrefill: "inbound-provider-imap:query:reconnect-prefill",
+} as const;
+
+export const IMAP_RECONNECT_ERRORS = {
+  notPasswordImap: {
+    reason: "reconnect_not_password_imap",
+    i18nKey: "inboundMail.imap.reconnect.errors.notPasswordImap",
+  },
 } as const;
 
 export const IMAP_CONNECT_ERRORS = {

package/packages/bundled-features/src/inbound-provider-imap/feature.ts

@@ -51,7 +51,9 @@ import {
   parseImapCursor,
   toRawInboundMessage,
 } from "./imap-client.ts";
-import { imapConnectScreen } from "./screens.ts";
+import { reconnectMailboxHandler } from "./reconnect-mailbox.ts";
+import { reconnectPrefillQuery } from "./reconnect-prefill.query.ts";
+import { imapConnectScreen, imapReconnectScreen } from "./screens.ts";
 import { sendFromImapAccount } from "./send-mail.ts";
 
 export { IMAP_PROVIDER_KEY } from "./constants.ts";
@@ -248,7 +250,7 @@ export function createInboundProviderImapFeature() {
     FEATURE_NAME,
     (r) => {
       r.describe(
-        'Registers the `"imap"` provider for `inbound-mail-foundation` using imapflow — password/app-password auth covers classic IMAP hosts without any OAuth (plus an XOAUTH2 fallback consuming an access token from the secret slot). Incremental sync via a UIDVALIDITY:lastUid cursor (UIDVALIDITY change triggers a cursor-invalid full resync), initial backfill bounded by the foundation backfill window, and live push via IMAP IDLE for the watch supervisor. Tenant admins connect a mailbox through the "Connect mailbox" form on the mail accounts list (`connect-mailbox` checks the IMAP login and the SMTP login of the outgoing server first, then creates the account and its credential secret in one transaction); programmatic setups store the per-account connection JSON (host/port/secure/user/password, plus smtpHost/smtpPort for sending) in the account credential secret slot before the first sync. Implements the provider `send`: `sendMailFromAccount` sends over the SMTP server of the mailbox itself (implicit TLS, same login) with the mailbox address as From and stores a copy in its sent folder.',
+        'Registers the `"imap"` provider for `inbound-mail-foundation` using imapflow — password/app-password auth covers classic IMAP hosts without any OAuth (plus an XOAUTH2 fallback consuming an access token from the secret slot). Incremental sync via a UIDVALIDITY:lastUid cursor (UIDVALIDITY change triggers a cursor-invalid full resync), initial backfill bounded by the foundation backfill window, and live push via IMAP IDLE for the watch supervisor. Tenant admins connect a mailbox through the "Connect mailbox" form on the mail accounts list (`connect-mailbox` checks the IMAP login and the SMTP login of the outgoing server first, then creates the account and its credential secret in one transaction; `reconnect-mailbox` does the same check for an existing mailbox with a sign-in error and overwrites its credential secret); programmatic setups store the per-account connection JSON (host/port/secure/user/password, plus smtpHost/smtpPort for sending) in the account credential secret slot before the first sync. Implements the provider `send`: `sendMailFromAccount` sends over the SMTP server of the mailbox itself (implicit TLS, same login) with the mailbox address as From and stores a copy in its sent folder.',
       );
       r.uiHints({
         displayLabel: "Inbound Mail · IMAP",
@@ -260,7 +262,10 @@ export function createInboundProviderImapFeature() {
       r.envSchema(mailAllowedPrivateHostsEnvSchema);
       r.useExtension(INBOUND_MAIL_PROVIDER_EXTENSION, IMAP_PROVIDER_KEY, imapInboundMailPlugin);
       r.writeHandler(connectMailboxHandler);
+      r.writeHandler(reconnectMailboxHandler);
+      r.queryHandler(reconnectPrefillQuery);
       r.screen(imapConnectScreen);
+      r.screen(imapReconnectScreen);
       r.translations({ keys: INBOUND_PROVIDER_IMAP_I18N });
     },
     { dedupeOptions: {} },

package/packages/bundled-features/src/inbound-provider-imap/i18n.ts

@@ -1,13 +1,23 @@
-import { IMAP_CONNECT_SCREEN_ID } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import {
+  IMAP_CONNECT_SCREEN_ID,
+  IMAP_RECONNECT_SCREEN_ID,
+} from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
 import { ACTION_FORM_ENTITY } from "@cosmicdrift/kumiko-framework/ui-types";
 import { fieldLabelKey } from "@cosmicdrift/kumiko-renderer/headless";
-import { FEATURE_NAME, IMAP_CONNECT_ERRORS, SMTP_CONNECT_ERRORS } from "./constants.ts";
+import {
+  FEATURE_NAME,
+  IMAP_CONNECT_ERRORS,
+  IMAP_RECONNECT_ERRORS,
+  SMTP_CONNECT_ERRORS,
+} from "./constants.ts";
 
 const formFieldKey = (field: string): string =>
   fieldLabelKey(FEATURE_NAME, ACTION_FORM_ENTITY, field);
 
 export const INBOUND_PROVIDER_IMAP_I18N: Readonly<Record<string, { readonly en: string }>> = {
   [`screen:${IMAP_CONNECT_SCREEN_ID}.title`]: { en: "Connect mailbox" },
+  [`screen:${IMAP_RECONNECT_SCREEN_ID}.title`]: { en: "Reconnect mailbox" },
+  [formFieldKey("accountId")]: { en: "Mailbox" },
   [formFieldKey("displayName")]: { en: "Name" },
   [formFieldKey("address")]: { en: "Email address" },
   [formFieldKey("host")]: { en: "IMAP server" },
@@ -22,6 +32,13 @@ export const INBOUND_PROVIDER_IMAP_I18N: Readonly<Record<string, { readonly en:
     en: "Replies go out from this address over your own mail server, with the same user name and password. Leave the field empty if the server is called like the IMAP server, with smtp. instead of imap. Usually 587, even when your provider lists 465/SSL.",
   },
   "inboundMail.imap.connect.submit": { en: "Check and connect" },
+  "inboundMail.imap.reconnect.hint": {
+    en: "The sign-in is checked before saving. Then the system fetches the mail again.",
+  },
+  "inboundMail.imap.reconnect.submit": { en: "Check and reconnect" },
+  [IMAP_RECONNECT_ERRORS.notPasswordImap.i18nKey]: {
+    en: "Only password IMAP mailboxes can be reconnected here.",
+  },
   [IMAP_CONNECT_ERRORS.hostUnreachable.i18nKey]: {
     en: "The IMAP server cannot be reached or is not allowed. Check the server name.",
   },

package/packages/bundled-features/src/inbound-provider-imap/reconnect-account.ts

@@ -0,0 +1,47 @@
+// Loads the mailbox a reconnect targets. The db is tenant-scoped, so another tenant's account id
+// finds nothing.
+
+import {
+  InboundMailAccountStatuses,
+  InboundMailAuthMethods,
+  mailAccountsProjectionTable,
+} from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  failNotFound,
+  failUnprocessable,
+  UnprocessableError,
+  type WriteFailure,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import { IMAP_PROVIDER_KEY, IMAP_RECONNECT_ERRORS } from "./constants.ts";
+
+type ReconnectAccountRow = {
+  readonly id: string;
+  readonly provider: string;
+  readonly authMethod: string;
+  readonly displayName: string | null;
+  readonly status: string | null;
+};
+
+export type ReconnectAccountLookup =
+  | { readonly isSuccess: true; readonly row: ReconnectAccountRow }
+  | WriteFailure;
+
+export async function findReconnectableAccount(
+  db: Pick<TenantDb, "fetchOne">,
+  accountId: string,
+): Promise<ReconnectAccountLookup> {
+  const row = await db.fetchOne<ReconnectAccountRow>(mailAccountsProjectionTable, {
+    id: accountId,
+  });
+  if (!row) return failNotFound("mail-account", accountId);
+  if (row.status === InboundMailAccountStatuses.disconnected) {
+    return failUnprocessable("account_disconnected", { accountId });
+  }
+  if (row.provider !== IMAP_PROVIDER_KEY || row.authMethod !== InboundMailAuthMethods.password) {
+    const { reason, i18nKey } = IMAP_RECONNECT_ERRORS.notPasswordImap;
+    return writeFailure(new UnprocessableError(reason, { i18nKey, details: { accountId } }));
+  }
+  return { isSuccess: true, row };
+}

package/packages/bundled-features/src/inbound-provider-imap/reconnect-mailbox.ts

@@ -0,0 +1,73 @@
+// reconnect-mailbox: new credentials for an existing password IMAP mailbox, typically after the
+// account went to auth_error. The login is checked before the transaction opens; only then the
+// account goes back to active and the credential secret of the same account is overwritten, both
+// on the request transaction, so a failure leaves status and secret as they were.
+
+import {
+  InboundMailAccountStatuses,
+  InboundMailFoundationHandlers,
+  inboundCredentialSecretKey,
+} from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import {
+  type BeforeTransactionResult,
+  defineWriteHandler,
+} from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import {
+  CREDENTIAL_PREVIEW,
+  checkMailboxLogin,
+  connectMailboxSchema,
+  credentialDocumentOf,
+} from "./connect-mailbox.ts";
+import { findReconnectableAccount } from "./reconnect-account.ts";
+
+const reconnectMailboxSchema = connectMailboxSchema
+  .pick({ host: true, port: true, user: true, password: true, smtpHost: true, smtpPort: true })
+  .extend({ accountId: z.uuid() });
+
+const SECRET_TRANSACTION_REASON =
+  "the credential secret is written on the request transaction so a failed reconnect rolls the account status back too";
+
+export const reconnectMailboxHandler = defineWriteHandler({
+  name: "reconnect-mailbox",
+  description:
+    "Replaces the credentials of an existing password IMAP mailbox: checks the IMAP login and the SMTP login of the outgoing server first, then overwrites the credential secret of the same account and sets it back to active, keeping its threads and sync cursor.",
+  // The payload carries the plaintext password: as a tool call it would reach the model provider.
+  agent: { expose: false },
+  schema: reconnectMailboxSchema,
+  access: { roles: ["SystemAdmin", "TenantAdmin"] },
+  // Same cap as connect: each call opens a connection to a host the caller picks.
+  rateLimit: { per: "tenant+handler", limit: 10, windowSeconds: 600 },
+  escapeHatch: { grants: ["unsafeRaw"], reason: SECRET_TRANSACTION_REASON },
+  beforeTransaction: async (event, ctx): Promise<BeforeTransactionResult<null>> => {
+    const lookup = await findReconnectableAccount(ctx.db, event.payload.accountId);
+    if (!lookup.isSuccess) return lookup;
+    return checkMailboxLogin(credentialDocumentOf(event.payload), ctx.obs.log);
+  },
+  handler: async (event, ctx) => {
+    const { accountId } = event.payload;
+    const reactivated = await ctx.dispatch.write(InboundMailFoundationHandlers.updateAccount, {
+      accountId,
+      status: InboundMailAccountStatuses.active,
+      watchState: "idle",
+    });
+    if (!reactivated.isSuccess) return reactivated;
+
+    const secrets = requireSecretsContext(
+      { secrets: ctx.services.secrets, user: ctx.user },
+      "reconnect-mailbox",
+    ).withRunner(ctx.db.unsafeRaw());
+    await secrets.set(
+      event.user.tenantId,
+      inboundCredentialSecretKey(accountId),
+      JSON.stringify(credentialDocumentOf(event.payload)),
+      {
+        redact: () => CREDENTIAL_PREVIEW,
+        hint: `IMAP credentials for inbound mail account ${accountId}`,
+        updatedBy: event.user.id,
+      },
+    );
+    return { isSuccess: true, data: { accountId } };
+  },
+});

package/packages/bundled-features/src/inbound-provider-imap/reconnect-prefill.query.ts

@@ -0,0 +1,38 @@
+// Initial values of the reconnect form: the server settings of the stored credential, never the
+// password. A missing or unreadable credential leaves the fields empty for the admin to fill in.
+
+import { inboundCredentialSecretKey } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import type { QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { FEATURE_NAME } from "./constants.ts";
+import { parseImapCredentialDocument } from "./credential-document.ts";
+import { findReconnectableAccount } from "./reconnect-account.ts";
+
+const reconnectPrefillSchema = z.object({ accountId: z.uuid() }).strict();
+
+export const reconnectPrefillQuery: QueryHandlerDef = {
+  name: "reconnect-prefill",
+  schema: reconnectPrefillSchema,
+  access: { roles: ["SystemAdmin", "TenantAdmin"] },
+  // Only the reconnect form needs these settings; the agent has no write to use them with.
+  agent: { expose: false },
+  description:
+    "Returns the server settings (IMAP host and port, user name, SMTP host and port) stored for a password IMAP mailbox without its password, or null when the mailbox is not found, disconnected or not a password IMAP mailbox; use it to prefill the reconnect form.",
+  handler: async (query, ctx) => {
+    const { accountId } = reconnectPrefillSchema.parse(query.payload);
+    const lookup = await findReconnectableAccount(ctx.db, accountId);
+    if (!lookup.isSuccess) return null;
+
+    const secrets = requireSecretsContext(
+      { secrets: ctx.services.secrets, user: ctx.user },
+      FEATURE_NAME,
+    );
+    const stored = await secrets.get(ctx.user.tenantId, inboundCredentialSecretKey(accountId));
+    const parsed = stored ? parseImapCredentialDocument(stored.reveal()) : undefined;
+    const displayName = lookup.row.displayName ?? "";
+    if (!parsed?.ok) return { accountId, displayName };
+    const { host, port, user, smtpHost, smtpPort } = parsed.doc;
+    return { accountId, displayName, host, port, user, smtpHost, smtpPort };
+  },
+};

package/packages/bundled-features/src/inbound-provider-imap/screens.ts

@@ -1,10 +1,11 @@
 import {
   IMAP_CONNECT_SCREEN_ID,
+  IMAP_RECONNECT_SCREEN_ID,
   MAIL_ACCOUNT_LIST_SCREEN_QN,
 } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
 import { i18nKey } from "@cosmicdrift/kumiko-framework/engine";
 import type { ActionFormScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
-import { ImapHandlers, SMTP_SUBMISSION_PORT } from "./constants.ts";
+import { ImapHandlers, ImapQueries, SMTP_SUBMISSION_PORT } from "./constants.ts";
 
 // Reached from the toolbar of the foundation's mail account list, never from the nav.
 export const imapConnectScreen: ActionFormScreenDefinition = {
@@ -16,13 +17,22 @@ export const imapConnectScreen: ActionFormScreenDefinition = {
     displayName: { type: "text", required: true, maxLength: 200 },
     address: { type: "text", required: true, maxLength: 320, format: "email" },
     host: { type: "text", required: true, maxLength: 255 },
-    port: { type: "number", integer: true, required: true, min: 1, max: 65535, default: 993 },
+    port: {
+      type: "number",
+      integer: true,
+      grouping: false,
+      required: true,
+      min: 1,
+      max: 65535,
+      default: 993,
+    },
     user: { type: "text", required: true, maxLength: 320 },
     password: { type: "text", required: true, format: "password", sensitive: true },
     smtpHost: { type: "text", maxLength: 255 },
     smtpPort: {
       type: "number",
       integer: true,
+      grouping: false,
       required: true,
       min: 1,
       max: 65535,
@@ -50,3 +60,66 @@ export const imapConnectScreen: ActionFormScreenDefinition = {
   access: { roles: ["SystemAdmin", "TenantAdmin"] },
   dormant: true,
 };
+
+// Reached from the "Reconnect" row action of an account with a sign-in error. The record id comes
+// from the path; the load query returns the stored server settings, never the password.
+export const imapReconnectScreen: ActionFormScreenDefinition = {
+  id: IMAP_RECONNECT_SCREEN_ID,
+  type: "actionForm",
+  agent: { expose: false },
+  handler: ImapHandlers.reconnectMailbox,
+  load: { query: ImapQueries.reconnectPrefill, idParam: "accountId" },
+  fields: {
+    accountId: { type: "text", required: true },
+    displayName: { type: "text", maxLength: 200 },
+    host: { type: "text", required: true, maxLength: 255 },
+    port: {
+      type: "number",
+      integer: true,
+      grouping: false,
+      required: true,
+      min: 1,
+      max: 65535,
+      default: 993,
+    },
+    user: { type: "text", required: true, maxLength: 320 },
+    password: { type: "text", required: true, format: "password", sensitive: true },
+    smtpHost: { type: "text", maxLength: 255 },
+    smtpPort: {
+      type: "number",
+      integer: true,
+      grouping: false,
+      required: true,
+      min: 1,
+      max: 65535,
+      default: SMTP_SUBMISSION_PORT,
+    },
+  },
+  layout: {
+    sections: [
+      {
+        title: i18nKey("inboundMail.imap.connect.server"),
+        description: i18nKey("inboundMail.imap.reconnect.hint"),
+        // The id only travels in the payload; the admin recognises the mailbox by its name.
+        fields: [
+          { field: "accountId", visible: false },
+          { field: "displayName", readOnly: true, submit: false },
+          "host",
+          "port",
+          "user",
+          "password",
+        ],
+      },
+      {
+        title: i18nKey("inboundMail.imap.connect.outgoing"),
+        description: i18nKey("inboundMail.imap.connect.outgoingHint"),
+        fields: ["smtpHost", "smtpPort"],
+      },
+    ],
+  },
+  submitLabel: i18nKey("inboundMail.imap.reconnect.submit"),
+  redirect: MAIL_ACCOUNT_LIST_SCREEN_QN,
+  cancelTarget: MAIL_ACCOUNT_LIST_SCREEN_QN,
+  access: { roles: ["SystemAdmin", "TenantAdmin"] },
+  dormant: true,
+};

package/packages/bundled-features/src/inbound-provider-inmemory/feature.ts

@@ -11,13 +11,16 @@
 // **Pattern basis:** mail-transport-inmemory (module-level state +
 // test-helper exports). Not for production.
 
-import type {
-  InboundFetchResult,
-  InboundMailProviderPlugin,
-  MailAccountRecord,
-  RawInboundMessage,
-  SyncCursorPayload,
+import {
+  InboundAuthError,
+  type InboundFetchResult,
+  type InboundMailContext,
+  type InboundMailProviderPlugin,
+  type MailAccountRecord,
+  type RawInboundMessage,
+  type SyncCursorPayload,
 } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 
 const FEATURE_NAME = "inbound-provider-inmemory";
@@ -38,6 +41,7 @@ type AccountState = {
   watch: WatchHandlers | null;
   nextFetchError: unknown;
   nextVerifyError: unknown;
+  credentialSecretKey: string | null;
 };
 
 const accounts = new Map<string, AccountState>();
@@ -45,7 +49,13 @@ const accounts = new Map<string, AccountState>();
 function stateFor(accountId: string): AccountState {
   let state = accounts.get(accountId);
   if (!state) {
-    state = { log: [], watch: null, nextFetchError: null, nextVerifyError: null };
+    state = {
+      log: [],
+      watch: null,
+      nextFetchError: null,
+      nextVerifyError: null,
+      credentialSecretKey: null,
+    };
     accounts.set(accountId, state);
   }
   return state;
@@ -71,6 +81,25 @@ export function failNextVerifyWith(accountId: string, err: unknown): void {
   stateFor(accountId).nextVerifyError = err;
 }
 
+/** Test helper: every fetch reads this tenant secret first, like a real
+ *  provider reads its stored credentials; a missing secret is an auth error. */
+export function requireCredentialSecretOnFetch(accountId: string, key: string): void {
+  stateFor(accountId).credentialSecretKey = key;
+}
+
+async function readCredentialSecret(
+  ctx: InboundMailContext,
+  account: MailAccountRecord,
+  key: string,
+): Promise<void> {
+  const secrets = requireSecretsContext(
+    { secrets: ctx.secrets, auditUserId: ctx.auditUserId },
+    FEATURE_NAME,
+  );
+  const secret = await secrets.get(account.tenantId, key);
+  if (!secret) throw new InboundAuthError(`${FEATURE_NAME}: no credential secret ${key}`);
+}
+
 /** Test helper: simulates the live connection terminating (the supervisor
  *  must restart with backoff). */
 export function emitWatchError(accountId: string, err: unknown): void {
@@ -111,13 +140,16 @@ export const inMemoryInboundMailPlugin: InboundMailProviderPlugin = {
       throw err;
     }
   },
-  fetch: async (_ctx, account, cursor, opts): Promise<InboundFetchResult> => {
+  fetch: async (ctx, account, cursor, opts): Promise<InboundFetchResult> => {
     const state = stateFor(account.id);
     if (state.nextFetchError) {
       const err = state.nextFetchError;
       state.nextFetchError = null;
       throw err;
     }
+    if (state.credentialSecretKey) {
+      await readCredentialSecret(ctx, account, state.credentialSecretKey);
+    }
     const offset = offsetOf(cursor);
     const slice = state.log.slice(offset, offset + opts.maxMessages);
     const nextOffset = offset + slice.length;

package/packages/bundled-features/src/inbound-provider-inmemory/index.ts

@@ -7,6 +7,7 @@ export {
   failNextVerifyWith,
   INMEMORY_PROVIDER_KEY,
   isWatching,
+  requireCredentialSecretOnFetch,
   resetInboundInMemory,
   seedInboundMessage,
 } from "./feature.ts";

package/samples/apps/use-all-bundled/feature-manifest.json

@@ -1434,7 +1434,7 @@
     },
     {
       "name": "inbound-provider-imap",
-      "description": "Registers the `\"imap\"` provider for `inbound-mail-foundation` using imapflow — password/app-password auth covers classic IMAP hosts without any OAuth (plus an XOAUTH2 fallback consuming an access token from the secret slot). Incremental sync via a UIDVALIDITY:lastUid cursor (UIDVALIDITY change triggers a cursor-invalid full resync), initial backfill bounded by the foundation backfill window, and live push via IMAP IDLE for the watch supervisor. Tenant admins connect a mailbox through the \"Connect mailbox\" form on the mail accounts list (`connect-mailbox` checks the IMAP login and the SMTP login of the outgoing server first, then creates the account and its credential secret in one transaction); programmatic setups store the per-account connection JSON (host/port/secure/user/password, plus smtpHost/smtpPort for sending) in the account credential secret slot before the first sync. Implements the provider `send`: `sendMailFromAccount` sends over the SMTP server of the mailbox itself (implicit TLS, same login) with the mailbox address as From and stores a copy in its sent folder.",
+      "description": "Registers the `\"imap\"` provider for `inbound-mail-foundation` using imapflow — password/app-password auth covers classic IMAP hosts without any OAuth (plus an XOAUTH2 fallback consuming an access token from the secret slot). Incremental sync via a UIDVALIDITY:lastUid cursor (UIDVALIDITY change triggers a cursor-invalid full resync), initial backfill bounded by the foundation backfill window, and live push via IMAP IDLE for the watch supervisor. Tenant admins connect a mailbox through the \"Connect mailbox\" form on the mail accounts list (`connect-mailbox` checks the IMAP login and the SMTP login of the outgoing server first, then creates the account and its credential secret in one transaction; `reconnect-mailbox` does the same check for an existing mailbox with a sign-in error and overwrites its credential secret); programmatic setups store the per-account connection JSON (host/port/secure/user/password, plus smtpHost/smtpPort for sending) in the account credential secret slot before the first sync. Implements the provider `send`: `sendMailFromAccount` sends over the SMTP server of the mailbox itself (implicit TLS, same login) with the mailbox address as From and stores a copy in its sent folder.",
       "toggleableDefault": null,
       "requires": [
         "inbound-mail-foundation",
@@ -1453,7 +1453,8 @@
       "configKeys": [],
       "secrets": [],
       "writeHandlers": [
-        "inbound-provider-imap:write:connect-mailbox"
+        "inbound-provider-imap:write:connect-mailbox",
+        "inbound-provider-imap:write:reconnect-mailbox"
       ],
       "uiHints": {
         "displayLabel": "Inbound Mail · IMAP",

package/samples/recipes/inbound-mail-triage/README.md

@@ -24,6 +24,10 @@ mail-triage  ← this sample                                  (the app-side cons
 3. The handler-trigger fans the write out to the worker lane; the triage job records `{ from, subject, scope, threadHint }`.
 4. A replay of the same `providerMessageId` reports `duplicate: true`, creates no second row — and the keyed triage store stays at one item.
 
+## Sign-in errors
+
+When the provider rejects the stored login, the supervisor sets the account to `auth_error` and stops fetching. With `inbound-provider-imap` mounted, the mail accounts list offers **Reconnect** on that row: the form `mail-account-reconnect-imap` is prefilled with the stored server settings (never the password), `inbound-provider-imap:write:reconnect-mailbox` checks the new login and puts the same account back to `active`. Threads, sync cursor and seen messages stay, so the next poll continues where the account stopped instead of ingesting the mailbox again. The cases are covered in `inbound-provider-imap/__tests__/reconnect-mailbox.integration.test.ts`; they need greenmail, which this sample's in-memory provider does not.
+
 ## Tests
 
 - E2E through `createAllInOneEntrypoint` (HTTP → dispatcher → BullMQ worker lane, no framework-internal shortcuts): connect → ingest → triage item appears.