@cosmicdrift/kumiko-samples 0.391.0 → 0.392.0

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

@@ -49,6 +49,7 @@ 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 type { DistributedLock } from "@cosmicdrift/kumiko-framework/pipeline";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
@@ -185,11 +186,15 @@ 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 ?? (() => {});
+  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
       ? createOAuthAccessTokenManager({
-          db: deps.db,
+          db: systemDb,
           secrets: deps.providerCtx.secrets,
           providerCtx: deps.providerCtx,
         })
@@ -219,7 +224,7 @@ export function createInboundMailSupervisor(
   // decrypted (providers never work with ciphertext).
   // ---------------------------------------------------------------
   async function listActiveAccounts(): Promise<readonly MailAccountRecord[]> {
-    const rows = await selectMany<ActiveMailAccountRow>(deps.db, mailAccountsProjectionTable, {
+    const rows = await selectMany<ActiveMailAccountRow>(systemDb, mailAccountsProjectionTable, {
       status: InboundMailAccountStatuses.active,
     });
     const piiKms = configuredPiiSubjectKms();
@@ -264,7 +269,7 @@ export function createInboundMailSupervisor(
   // Cursor-Persistenz (unmanaged direct-write store).
   // ---------------------------------------------------------------
   async function loadCursor(accountId: string): Promise<SyncCursorPayload | null> {
-    const row = await fetchOne<{ cursor: string }>(deps.db, syncCursorTable, {
+    const row = await fetchOne<{ cursor: string }>(systemDb, syncCursorTable, {
       accountId,
       scope: CURSOR_SCOPE,
     });
@@ -284,13 +289,13 @@ export function createInboundMailSupervisor(
     const accountId = account.id;
     const now = Temporal.Now.instant().toString();
     const serialized = JSON.stringify(cursor);
-    const existing = await fetchOne<{ id: string }>(deps.db, syncCursorTable, {
+    const existing = await fetchOne<{ id: string }>(systemDb, syncCursorTable, {
       accountId,
       scope: CURSOR_SCOPE,
     });
     if (existing) {
       await updateMany(
-        deps.db,
+        systemDb,
         syncCursorTable,
         { cursor: serialized, updatedAt: now },
         { accountId, scope: CURSOR_SCOPE },
@@ -298,7 +303,7 @@ export function createInboundMailSupervisor(
       // skip: the update path is complete; do not fall through to the insert branch.
       return;
     }
-    await insertOne(deps.db, syncCursorTable, {
+    await insertOne(systemDb, syncCursorTable, {
       id: crypto.randomUUID(),
       // Direct-write store: no executor stamps the NOT NULL tenant_id for us.
       tenantId: account.tenantId,
@@ -313,7 +318,7 @@ export function createInboundMailSupervisor(
     // No deleteMany import is needed: an empty cursor parses to null, so the
     // next fetch runs as a backfill.
     await updateMany(
-      deps.db,
+      systemDb,
       syncCursorTable,
       { cursor: "", updatedAt: Temporal.Now.instant().toString() },
       { accountId, scope: CURSOR_SCOPE },
@@ -414,7 +419,7 @@ export function createInboundMailSupervisor(
       const seenIds = new Set<string>();
       for (let start = 0; start < providerMessageIds.length; start += SEEN_LOOKUP_CHUNK_SIZE) {
         const seen = await selectMany<{ providerMessageId: string }>(
-          deps.db,
+          systemDb,
           seenMessageTable,
           {
             tenantId: account.tenantId,

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

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.392.0",
+    "type": "improvement",
+    "title": "IMAP mailboxes can be connected from a form",
+    "detail": "The new write handler inbound-provider-imap:write:connect-mailbox (TenantAdmin, SystemAdmin, not exposed to the agent, 10 calls per tenant in 10 minutes) checks the IMAP login before the transaction, then creates a shared mail account and stores host, port, user and password in its credential secret in the same transaction. It always connects with implicit TLS (default port 993); there is no plaintext option, and a secure:false in the payload is ignored. A failed check stores nothing and answers with one of four texts: host not reachable or not allowed, login rejected, TLS failed, no connection. The form screen mail-account-connect-imap has a masked password field and no TLS toggle. New keys in all locale packages."
+  },
+  {
+    "version": "0.392.0",
+    "type": "improvement",
+    "title": "IMAP mailboxes send over their own SMTP server",
+    "detail": "The connect form gets an optional field \"Outgoing server (SMTP)\". Left empty, the IMAP host is used, with smtp. in place of a leading imap.. connect-mailbox now also checks the SMTP login on port 465 (implicit TLS, same user and password, same host guard) and answers a failure with its own text (\"Receiving works, but sending does not: ...\"). The credential document gains smtpHost and smtpPort (default 465). The provider implements send: it sends over SMTP with From = the mailbox address and display name, then stores the same message in the sent folder (special use \\Sent, else Sent, Gesendet or INBOX.Sent); a failed copy is only logged. Accounts stored without smtpHost answer mail_send_not_configured. New keys in all locale packages."
+  },
   {
     "version": "0.390.1",
     "type": "fix",

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

@@ -0,0 +1,156 @@
+// connect-mailbox: the form path for a password IMAP mailbox. The IMAP login and then the SMTP
+// login of the outgoing server are checked before the transaction opens; only then the account
+// stream and its credential secret are written, both on the request transaction, so a failure
+// leaves neither behind.
+
+import {
+  InboundAuthError,
+  InboundMailAuthMethods,
+  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 { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { IMAP_CONNECT_ERRORS, IMAP_PROVIDER_KEY, SMTP_CONNECT_ERRORS } from "./constants.ts";
+import {
+  type ImapCredentialDocument,
+  imapCredentialDocumentSchema,
+  SMTP_IMPLICIT_TLS_PORT,
+  smtpHostSchema,
+} from "./credential-document.ts";
+import { connectOnce, IMAP_HOST_UNREACHABLE_MESSAGE } from "./imap-client.ts";
+import { type SmtpFailure, SmtpFailureError, verifySmtpLogin } from "./smtp-client.ts";
+
+// No `secure` and no SMTP port input: the password never crosses the wire in clear text, so a
+// payload's secure:false or smtpPort is stripped like any unknown key and both logins always use
+// implicit TLS (SMTP on port 465).
+const connectMailboxSchema = imapCredentialDocumentSchema
+  .pick({ host: true, port: true, user: true })
+  .extend({
+    displayName: z.string().min(1).max(200),
+    address: z.email().max(320),
+    password: z.string().min(1).max(1000),
+    smtpHost: z.union([z.literal(""), smtpHostSchema]).nullish(),
+  });
+type ConnectMailboxPayload = z.infer<typeof connectMailboxSchema>;
+
+const connectedAccountSchema = z.object({ accountId: z.string() });
+
+// Matched on the mapped error text, which also carries the host, so only markers no host name
+// contains: a bare "tls" or "ssl" would misread a host like ssl.example.com.
+// BoringSSL (Bun) spells the handshake error WRONG_VERSION_NUMBER, OpenSSL (Node) with spaces.
+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";
+
+const SECRET_TRANSACTION_REASON =
+  "the credential secret is written on the request transaction so a failed account connect rolls it back too";
+
+type ConnectFailure = keyof typeof IMAP_CONNECT_ERRORS;
+
+// Most hosters name the outgoing server like the incoming one, or with smtp. for imap.
+export function deriveSmtpHost(imapHost: string): string {
+  return /^imap\./i.test(imapHost) ? `smtp.${imapHost.slice("imap.".length)}` : imapHost;
+}
+
+function credentialDocumentOf(payload: ConnectMailboxPayload): ImapCredentialDocument {
+  const { host, port, user, password } = payload;
+  const smtpHost = payload.smtpHost || deriveSmtpHost(host);
+  return { host, port, secure: true, user, password, smtpHost, smtpPort: SMTP_IMPLICIT_TLS_PORT };
+}
+
+// The raw error carries the host and the server response; the tenant only gets the category.
+// A blocked host and an unresolvable one share one text on purpose (see createImapClient).
+function imapConnectFailureOf(err: unknown): ConnectFailure {
+  const message = err instanceof Error ? err.message : "";
+  if (message === IMAP_HOST_UNREACHABLE_MESSAGE) return "hostUnreachable";
+  if (err instanceof InboundAuthError) return "loginRejected";
+  if (TLS_FAILURE.test(message)) return "tlsFailed";
+  return "connectFailed";
+}
+
+// verify never sends a mail, so a refused message cannot happen here; anything else answering
+// with an SMTP reply is a server we could not use.
+function smtpConnectFailureOf(failure: SmtpFailure): ConnectFailure {
+  return failure === "rejected" ? "connectFailed" : failure;
+}
+
+async function checkSmtpLogin(doc: ImapCredentialDocument): Promise<ConnectFailure | undefined> {
+  const { smtpHost, smtpPort, user, password } = doc;
+  // A derived host from an odd IMAP host name could not be stored as a valid document.
+  if (!smtpHost || !password || !smtpHostSchema.safeParse(smtpHost).success) {
+    return "hostUnreachable";
+  }
+  try {
+    await verifySmtpLogin({ host: smtpHost, port: smtpPort, user, password });
+    return undefined;
+  } catch (err) {
+    if (err instanceof SmtpFailureError) return smtpConnectFailureOf(err.failure);
+    throw err;
+  }
+}
+
+export const connectMailboxHandler = defineWriteHandler({
+  name: "connect-mailbox",
+  description:
+    "Connects a shared IMAP mailbox with a password over implicit TLS: checks the IMAP login and the SMTP login of the outgoing server (given, or derived from the IMAP host) first, then creates the mail account and stores both servers, user and password as its credential secret in one step.",
+  // The payload carries the plaintext password: as a tool call it would reach the model provider.
+  agent: { expose: false },
+  schema: connectMailboxSchema,
+  access: { roles: ["SystemAdmin", "TenantAdmin"] },
+  // Each call opens a connection to a host the caller picks; the cap keeps the form from being
+  // 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 }));
+    }
+    return { isSuccess: true, data: null };
+  },
+  handler: async (event, ctx) => {
+    const { displayName, address } = event.payload;
+    const connected = await ctx.dispatch.write(InboundMailFoundationHandlers.connectAccount, {
+      provider: IMAP_PROVIDER_KEY,
+      authMethod: InboundMailAuthMethods.password,
+      displayName,
+      address,
+      scope: "shared",
+    });
+    if (!connected.isSuccess) return connected;
+    const { accountId } = connectedAccountSchema.parse(connected.data);
+
+    const secrets = requireSecretsContext(
+      { secrets: ctx.services.secrets, user: ctx.user },
+      "connect-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/constants.ts

@@ -0,0 +1,42 @@
+export const FEATURE_NAME = "inbound-provider-imap";
+export const IMAP_PROVIDER_KEY = "imap";
+
+export const ImapHandlers = {
+  connectMailbox: "inbound-provider-imap:write:connect-mailbox",
+} as const;
+
+export const IMAP_CONNECT_ERRORS = {
+  hostUnreachable: {
+    reason: "imap_host_unreachable",
+    i18nKey: "inboundMail.imap.connect.errors.hostUnreachable",
+  },
+  loginRejected: {
+    reason: "imap_login_rejected",
+    i18nKey: "inboundMail.imap.connect.errors.loginRejected",
+  },
+  tlsFailed: { reason: "imap_tls_failed", i18nKey: "inboundMail.imap.connect.errors.tlsFailed" },
+  connectFailed: {
+    reason: "imap_connect_failed",
+    i18nKey: "inboundMail.imap.connect.errors.connectFailed",
+  },
+} as const;
+
+// Same categories as IMAP_CONNECT_ERRORS, for the outgoing server checked after the IMAP login.
+export const SMTP_CONNECT_ERRORS = {
+  hostUnreachable: {
+    reason: "smtp_host_unreachable",
+    i18nKey: "inboundMail.imap.connect.errors.smtpHostUnreachable",
+  },
+  loginRejected: {
+    reason: "smtp_login_rejected",
+    i18nKey: "inboundMail.imap.connect.errors.smtpLoginRejected",
+  },
+  tlsFailed: {
+    reason: "smtp_tls_failed",
+    i18nKey: "inboundMail.imap.connect.errors.smtpTlsFailed",
+  },
+  connectFailed: {
+    reason: "smtp_connect_failed",
+    i18nKey: "inboundMail.imap.connect.errors.smtpConnectFailed",
+  },
+} as const satisfies Record<keyof typeof IMAP_CONNECT_ERRORS, unknown>;

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

@@ -9,13 +9,35 @@
 // at rest.
 //
 // The account's authMethod determines the interpretation:
-//   password → { host, port, secure, user, password }
+//   password → { host, port, secure, user, password, smtpHost?, smtpPort }
 //   xoauth2  → { host, port, secure, user, accessToken } — V1 fallback:
 //              OAuth providers (M365/Gmail) handle token acquisition and
 //              refresh; the imap provider only consumes a valid access
 //              token from the slot.
+//
+// smtpHost is the outgoing server for sending from the mailbox, with the same user and password
+// over implicit TLS. Documents written before sending existed have none: sending reports
+// "not set up" instead of guessing a host.
 
+import {
+  InboundAuthError,
+  type InboundMailContext,
+  inboundCredentialSecretKey,
+  type MailAccountRecord,
+} from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
 import * as z from "zod";
+import { FEATURE_NAME } from "./constants.ts";
+
+export const SMTP_IMPLICIT_TLS_PORT = 465;
+
+// A bare host name: a port, path or whitespace would point the connect somewhere the guard did
+// not check.
+export const smtpHostSchema = z
+  .string()
+  .min(1)
+  .max(255)
+  .regex(/^[^\s:/@]+$/);
 
 export const imapCredentialDocumentSchema = z.object({
   host: z.string().min(1).max(255),
@@ -24,6 +46,8 @@ export const imapCredentialDocumentSchema = z.object({
   user: z.string().min(1).max(320),
   password: z.string().min(1).optional(),
   accessToken: z.string().min(1).optional(),
+  smtpHost: smtpHostSchema.optional(),
+  smtpPort: z.number().int().min(1).max(65535).default(SMTP_IMPLICIT_TLS_PORT),
 });
 export type ImapCredentialDocument = z.infer<typeof imapCredentialDocumentSchema>;
 
@@ -49,3 +73,27 @@ export function parseImapCredentialDocument(raw: string): ParseCredentialResult
   }
   return { ok: true, doc: parsed.data };
 }
+
+export async function readCredentialDocument(
+  ctx: InboundMailContext,
+  account: MailAccountRecord,
+): Promise<ImapCredentialDocument> {
+  const secrets = requireSecretsContext(
+    { secrets: ctx.secrets, auditUserId: ctx.auditUserId },
+    FEATURE_NAME,
+  );
+  const secret = await secrets.get(account.tenantId, inboundCredentialSecretKey(account.id));
+  if (!secret) {
+    throw new InboundAuthError(
+      `${FEATURE_NAME}: no credential document in secret slot for account ${account.id} — ` +
+        `store the IMAP connection JSON under ${inboundCredentialSecretKey(account.id)} first`,
+    );
+  }
+  const parsed = parseImapCredentialDocument(secret.reveal());
+  if (!parsed.ok) {
+    throw new InboundAuthError(
+      `${FEATURE_NAME}: account ${account.id}: ${parsed.reason}${parsed.detail ? `: ${parsed.detail}` : ""}`,
+    );
+  }
+  return parsed.doc;
+}

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

@@ -26,20 +26,20 @@
 import { mailAllowedPrivateHostsEnvSchema } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
 import {
   INBOUND_MAIL_PROVIDER_EXTENSION,
-  InboundAuthError,
   type InboundFetchResult,
   type InboundMailContext,
   type InboundMailProviderPlugin,
-  inboundCredentialSecretKey,
   type MailAccountRecord,
   type RawInboundMessage,
 } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
-import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { instantToLegacyDate } from "@cosmicdrift/kumiko-framework/time";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import type { ImapFlow, MailboxObject } from "imapflow";
-import { type ImapCredentialDocument, parseImapCredentialDocument } from "./credential-document.ts";
+import { connectMailboxHandler } from "./connect-mailbox.ts";
+import { FEATURE_NAME, IMAP_PROVIDER_KEY } from "./constants.ts";
+import { readCredentialDocument } from "./credential-document.ts";
+import { INBOUND_PROVIDER_IMAP_I18N } from "./i18n.ts";
 import {
   assertUidValidity,
   coerceDate,
@@ -51,40 +51,13 @@ import {
   parseImapCursor,
   toRawInboundMessage,
 } from "./imap-client.ts";
+import { imapConnectScreen } from "./screens.ts";
+import { sendFromImapAccount } from "./send-mail.ts";
 
-const FEATURE_NAME = "inbound-provider-imap";
-export const IMAP_PROVIDER_KEY = "imap";
+export { IMAP_PROVIDER_KEY } from "./constants.ts";
 
 export { setImapMailHostLookup } from "./imap-client.ts";
 
-// =============================================================================
-// Credential-Read — per-Account-Slot, Worker-tauglich (slim ctx).
-// =============================================================================
-
-async function readCredentialDocument(
-  ctx: InboundMailContext,
-  account: MailAccountRecord,
-): Promise<ImapCredentialDocument> {
-  const secrets = requireSecretsContext(
-    { secrets: ctx.secrets, auditUserId: ctx.auditUserId },
-    FEATURE_NAME,
-  );
-  const secret = await secrets.get(account.tenantId, inboundCredentialSecretKey(account.id));
-  if (!secret) {
-    throw new InboundAuthError(
-      `${FEATURE_NAME}: no credential document in secret slot for account ${account.id} — ` +
-        `store the IMAP connection JSON under ${inboundCredentialSecretKey(account.id)} first`,
-    );
-  }
-  const parsed = parseImapCredentialDocument(secret.reveal());
-  if (!parsed.ok) {
-    throw new InboundAuthError(
-      `${FEATURE_NAME}: account ${account.id}: ${parsed.reason}${parsed.detail ? `: ${parsed.detail}` : ""}`,
-    );
-  }
-  return parsed.doc;
-}
-
 // =============================================================================
 // fetch — inkrementeller UID-Sync
 // =============================================================================
@@ -264,6 +237,7 @@ export const imapInboundMailPlugin: InboundMailProviderPlugin = {
   probe: async (ctx, account) => connectOnce(await readCredentialDocument(ctx, account), true),
   fetch: fetchMessages,
   watch: watchMailbox,
+  send: sendFromImapAccount,
   // No oauth block: password authentication runs through the credential
   // form (connect-account + Secret-Write); XOAUTH2 token flows belong to
   // the OAuth providers (M365/Gmail).
@@ -274,7 +248,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. Store the per-account connection JSON (host/port/secure/user/password) in the account credential secret slot before the first sync.',
+        '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.',
       );
       r.uiHints({
         displayLabel: "Inbound Mail · IMAP",
@@ -285,6 +259,9 @@ export function createInboundProviderImapFeature() {
       r.requires({ features: ["secrets"] });
       r.envSchema(mailAllowedPrivateHostsEnvSchema);
       r.useExtension(INBOUND_MAIL_PROVIDER_EXTENSION, IMAP_PROVIDER_KEY, imapInboundMailPlugin);
+      r.writeHandler(connectMailboxHandler);
+      r.screen(imapConnectScreen);
+      r.translations({ keys: INBOUND_PROVIDER_IMAP_I18N });
     },
     { dedupeOptions: {} },
   );

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

@@ -0,0 +1,48 @@
+import { IMAP_CONNECT_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";
+
+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" },
+  [formFieldKey("displayName")]: { en: "Name" },
+  [formFieldKey("address")]: { en: "Email address" },
+  [formFieldKey("host")]: { en: "IMAP server" },
+  [formFieldKey("port")]: { en: "Port" },
+  [formFieldKey("user")]: { en: "User name" },
+  [formFieldKey("password")]: { en: "Password" },
+  [formFieldKey("smtpHost")]: { en: "Outgoing server (SMTP)" },
+  "inboundMail.imap.connect.server": { en: "Server sign-in" },
+  "inboundMail.imap.connect.outgoing": { en: "Sending" },
+  "inboundMail.imap.connect.outgoingHint": {
+    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.",
+  },
+  "inboundMail.imap.connect.submit": { en: "Check and connect" },
+  [IMAP_CONNECT_ERRORS.hostUnreachable.i18nKey]: {
+    en: "The IMAP server cannot be reached or is not allowed. Check the server name.",
+  },
+  [IMAP_CONNECT_ERRORS.loginRejected.i18nKey]: {
+    en: "The IMAP server rejected the sign-in. Check the user name and password.",
+  },
+  [IMAP_CONNECT_ERRORS.tlsFailed.i18nKey]: {
+    en: "The encrypted connection failed. Check the port and the TLS setting.",
+  },
+  [IMAP_CONNECT_ERRORS.connectFailed.i18nKey]: {
+    en: "No connection to the IMAP server. Check the server name and port.",
+  },
+  [SMTP_CONNECT_ERRORS.hostUnreachable.i18nKey]: {
+    en: "Receiving works, but sending does not: the outgoing server cannot be reached or is not allowed. Check its name.",
+  },
+  [SMTP_CONNECT_ERRORS.loginRejected.i18nKey]: {
+    en: "Receiving works, but sending does not: the outgoing server rejected the sign-in.",
+  },
+  [SMTP_CONNECT_ERRORS.tlsFailed.i18nKey]: {
+    en: "Receiving works, but sending does not: the encrypted connection to the outgoing server on port 465 failed.",
+  },
+  [SMTP_CONNECT_ERRORS.connectFailed.i18nKey]: {
+    en: "Receiving works, but sending does not: no connection to the outgoing server on port 465.",
+  },
+};

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

@@ -32,7 +32,7 @@ const log = createFallbackLogger("inbound-provider-imap");
 // was blocked (private/reserved range) or merely failed to resolve, and
 // must never include the host or the underlying error text. Server-side
 // detail goes to `log` only.
-const IMAP_HOST_UNREACHABLE_MESSAGE = "IMAP host is not reachable or not allowed";
+export const IMAP_HOST_UNREACHABLE_MESSAGE = "IMAP host is not reachable or not allowed";
 
 // =============================================================================
 // Client-Factory + Fehler-Mapping

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

@@ -0,0 +1,44 @@
+import {
+  IMAP_CONNECT_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 } from "./constants.ts";
+
+// Reached from the toolbar of the foundation's mail account list, never from the nav.
+export const imapConnectScreen: ActionFormScreenDefinition = {
+  id: IMAP_CONNECT_SCREEN_ID,
+  type: "actionForm",
+  agent: { expose: false },
+  handler: ImapHandlers.connectMailbox,
+  fields: {
+    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 },
+    user: { type: "text", required: true, maxLength: 320 },
+    password: { type: "text", required: true, format: "password", sensitive: true },
+    smtpHost: { type: "text", maxLength: 255 },
+  },
+  layout: {
+    sections: [
+      // The name-based icon guess reads "address" as a postal address.
+      { fields: ["displayName", { field: "address", icon: "mail" }] },
+      {
+        title: i18nKey("inboundMail.imap.connect.server"),
+        fields: ["host", "port", "user", "password"],
+      },
+      {
+        title: i18nKey("inboundMail.imap.connect.outgoing"),
+        description: i18nKey("inboundMail.imap.connect.outgoingHint"),
+        fields: ["smtpHost"],
+      },
+    ],
+  },
+  submitLabel: i18nKey("inboundMail.imap.connect.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-imap/send-mail.ts

@@ -0,0 +1,73 @@
+// send for the imap provider: SMTP with the mailbox's own login, From = the mailbox address.
+// The MIME is built once, so the copy in the sent folder is byte for byte what went out.
+
+import { sanitizeMailDisplayName } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
+import {
+  InboundAuthError,
+  type InboundMailContext,
+  InboundTransientError,
+  type MailAccountRecord,
+  MailSendNotConfiguredError,
+  MailSendRejectedError,
+  type OutboundMailMessage,
+  type OutboundMailSent,
+} from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import MailComposer from "nodemailer/lib/mail-composer";
+import { FEATURE_NAME } from "./constants.ts";
+import { readCredentialDocument } from "./credential-document.ts";
+import { appendToSentFolder } from "./sent-folder.ts";
+import { SmtpFailureError, sendRawViaSmtp } from "./smtp-client.ts";
+
+function toFoundationSendError(err: SmtpFailureError): Error {
+  switch (err.failure) {
+    case "loginRejected":
+      return new InboundAuthError(err.message);
+    case "rejected":
+      return new MailSendRejectedError(err.message);
+    default:
+      return new InboundTransientError(err.message);
+  }
+}
+
+function stripAngles(id: string): string {
+  return id.replace(/^<|>$/g, "");
+}
+
+export async function sendFromImapAccount(
+  ctx: InboundMailContext,
+  account: MailAccountRecord,
+  message: OutboundMailMessage,
+): Promise<OutboundMailSent> {
+  const doc = await readCredentialDocument(ctx, account);
+  if (!doc.smtpHost || !doc.password) {
+    throw new MailSendNotConfiguredError(
+      `${FEATURE_NAME}: account ${account.id} has no outgoing server stored`,
+    );
+  }
+
+  const displayName = sanitizeMailDisplayName(account.displayName);
+  const mime = new MailComposer({
+    from: displayName ? { name: displayName, address: account.address } : account.address,
+    to: [...message.to],
+    ...(message.cc && { cc: [...message.cc] }),
+    subject: message.subject,
+    ...(message.text !== undefined && { text: message.text }),
+    ...(message.html !== undefined && { html: message.html }),
+    ...(message.inReplyTo && { inReplyTo: message.inReplyTo }),
+    ...(message.references && { references: [...message.references] }),
+  }).compile();
+  const raw = await mime.build();
+
+  try {
+    await sendRawViaSmtp(
+      { host: doc.smtpHost, port: doc.smtpPort, user: doc.user, password: doc.password },
+      { from: account.address, to: [...message.to, ...(message.cc ?? [])] },
+      raw,
+    );
+  } catch (err) {
+    throw err instanceof SmtpFailureError ? toFoundationSendError(err) : err;
+  }
+
+  await appendToSentFolder(doc, raw, account.id);
+  return { messageIdHeader: stripAngles(mime.messageId()) };
+}