@cosmicdrift/kumiko-bundled-features 0.392.2 → 0.394.0

package/dist/inbound-provider-imap/connect-mailbox.d.ts

@@ -1,6 +1,9 @@
+import { type InboundMailRoles } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import { type BeforeTransactionResult, type HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import type { WriteResult } from "@cosmicdrift/kumiko-types/handlers";
 import * as z from "zod";
 import { type ImapCredentialDocument } from "./credential-document.ts";
-declare const connectMailboxSchema: z.ZodObject<{
+export declare const connectMailboxSchema: z.ZodObject<{
     host: z.ZodString;
     port: z.ZodDefault<z.ZodNumber>;
     user: z.ZodString;
@@ -9,11 +12,30 @@ declare const connectMailboxSchema: z.ZodObject<{
     password: z.ZodString;
     smtpHost: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>>;
     smtpPort: z.ZodNumber;
+    trustedAuthservId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
-type ConnectMailboxPayload = z.infer<typeof connectMailboxSchema>;
+type ConnectMailboxLoginFields = Pick<z.infer<typeof connectMailboxSchema>, "host" | "port" | "user" | "password" | "smtpHost" | "smtpPort">;
+export declare const CREDENTIAL_PREVIEW = "IMAP login";
 export declare function deriveSmtpHost(imapHost: string): string;
-export declare function credentialDocumentOf(payload: ConnectMailboxPayload): ImapCredentialDocument;
-export declare const connectMailboxHandler: import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"connect-mailbox", z.ZodObject<{
+export declare function credentialDocumentOf(payload: ConnectMailboxLoginFields): ImapCredentialDocument;
+export declare function checkMailboxLogin(doc: ImapCredentialDocument, log: {
+    warn(message: string, data?: Record<string, unknown>): void;
+}): Promise<BeforeTransactionResult<null>>;
+export declare const SECRET_TRANSACTION_REASON = "the credential secret is written on the request transaction so a failed account connect rolls it back too";
+type ConnectedMailbox = {
+    readonly displayName: string;
+    readonly address: string;
+    readonly credentialDocument: ImapCredentialDocument;
+};
+export declare function connectPasswordMailbox(handlerName: string, event: {
+    readonly user: {
+        readonly id: string;
+        readonly tenantId: string;
+    };
+}, ctx: HandlerContext, mailbox: ConnectedMailbox, scope: "shared" | "user"): Promise<WriteResult<{
+    accountId: string;
+}>>;
+export declare const createConnectMailboxHandler: ({ adminRoles }: InboundMailRoles) => import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"connect-mailbox", z.ZodObject<{
     host: z.ZodString;
     port: z.ZodDefault<z.ZodNumber>;
     user: z.ZodString;
@@ -22,7 +44,8 @@ export declare const connectMailboxHandler: import("@cosmicdrift/kumiko-types/de
     password: z.ZodString;
     smtpHost: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>>;
     smtpPort: z.ZodNumber;
+    trustedAuthservId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>, {
     accountId: string;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, null>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, null, undefined>;
 export {};

package/dist/inbound-provider-imap/connect-mailbox.js

@@ -2,9 +2,10 @@
 // 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 { findMailboxByAddress, InboundAuthError, InboundMailAccountStatuses, InboundMailAuthMethods, InboundMailFoundationHandlers, inboundCredentialSecretKey, } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
 import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
-import { defineWriteHandler, } from "@cosmicdrift/kumiko-framework/engine";
+import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
+import { createSystemUser, 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.js";
@@ -14,23 +15,29 @@ import { SmtpFailureError, verifySmtpLogin } from "./smtp-client.js";
 // 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),
+    trustedAuthservId: z.string().trim().max(255).nullish(),
 });
+function isReopenableByThisForm(existing, ownerUserId) {
+    return (existing.status === InboundMailAccountStatuses.disconnected &&
+        existing.provider === IMAP_PROVIDER_KEY &&
+        existing.authMethod === InboundMailAuthMethods.password &&
+        existing.ownerUserId === ownerUserId);
+}
 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";
+export const CREDENTIAL_PREVIEW = "IMAP login";
 // Most hosters name the outgoing server like the incoming one, or with smtp. for imap.
 export function deriveSmtpHost(imapHost) {
     return /^imap\./i.test(imapHost) ? `smtp.${imapHost.slice("imap.".length)}` : imapHost;
@@ -73,53 +80,96 @@ async function checkSmtpLogin(doc) {
         throw err;
     }
 }
-export const connectMailboxHandler = defineWriteHandler({
+// Checks the IMAP login, then the SMTP login of the outgoing server; shared by connect and reconnect.
+export async function checkMailboxLogin(doc, log) {
+    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 SECRET_TRANSACTION_REASON = "the credential secret is written on the request transaction so a failed account connect rolls it back too";
+// Shared by the admin form (shared mailbox) and the member form (personal mailbox, owner = caller).
+// A disconnected password mailbox of the same scope and owner is brought back under its old account id,
+// so cursor, seen anchors and threads survive; anything else keeps connect-account's conflict answer.
+export async function connectPasswordMailbox(handlerName, event, ctx, mailbox, scope) {
+    const { displayName, address, credentialDocument } = mailbox;
+    const ownerUserId = scope === "user" ? event.user.id : null;
+    const existing = await findMailboxByAddress(ctx, event.user.tenantId, address);
+    const reopened = existing !== undefined && isReopenableByThisForm(existing, ownerUserId);
+    let accountId;
+    if (reopened) {
+        accountId = existing.id;
+    }
+    else {
+        const accountFields = {
+            provider: IMAP_PROVIDER_KEY,
+            authMethod: InboundMailAuthMethods.password,
+            displayName,
+            address,
+            scope,
+        };
+        // connect-account is admin-only, so a member's personal mailbox goes through the system identity
+        // with the owner taken from this session, like the OAuth callback does.
+        const connected = scope === "user"
+            ? await ctx.dispatch.writeAs(createSystemUser(ctx.user.tenantId, [ROLES.SystemAdmin]), InboundMailFoundationHandlers.connectAccount, { ...accountFields, ownerUserIdOverride: event.user.id })
+            : await ctx.dispatch.write(InboundMailFoundationHandlers.connectAccount, accountFields);
+        if (!connected.isSuccess)
+            return connected;
+        accountId = connectedAccountSchema.parse(connected.data).accountId;
+    }
+    const secrets = requireSecretsContext({ secrets: ctx.services.secrets, user: ctx.user }, handlerName).withRunner(ctx.db.unsafeRaw());
+    await secrets.set(event.user.tenantId, inboundCredentialSecretKey(accountId), JSON.stringify(credentialDocument), {
+        redact: () => CREDENTIAL_PREVIEW,
+        hint: `IMAP credentials for inbound mail account ${accountId}`,
+        updatedBy: event.user.id,
+    });
+    if (reopened) {
+        // Secret first: reactivating a disconnected account requires the credential to exist.
+        const reactivated = await ctx.dispatch.write(InboundMailFoundationHandlers.reactivateAccount, {
+            accountId,
+        });
+        if (!reactivated.isSuccess)
+            return reactivated;
+    }
+    return { isSuccess: true, data: { accountId } };
+}
+export const createConnectMailboxHandler = ({ adminRoles }) => 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"] },
+    access: { roles: [...adminRoles] },
     // 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) => {
-        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, {
-            provider: IMAP_PROVIDER_KEY,
-            authMethod: InboundMailAuthMethods.password,
-            displayName,
-            address,
-            scope: "shared",
-        });
+        const { displayName, address, trustedAuthservId } = event.payload;
+        const connected = await connectPasswordMailbox("connect-mailbox", event, ctx, { displayName, address, credentialDocument: credentialDocumentOf(event.payload) }, "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,
-        });
+        const { accountId } = connected.data;
+        if (trustedAuthservId) {
+            const trusted = await ctx.dispatch.write(InboundMailFoundationHandlers.setTrustedAuthservId, {
+                accountId,
+                trustedAuthservId,
+            });
+            if (!trusted.isSuccess)
+                return trusted;
+        }
         return { isSuccess: true, data: { accountId } };
     },
 });

package/dist/inbound-provider-imap/connect-my-mailbox.d.ts

@@ -0,0 +1,13 @@
+import type { InboundMailRoles } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+export declare const createConnectMyMailboxHandler: ({ memberRoles }: InboundMailRoles) => import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"connect-my-mailbox", import("zod").ZodObject<{
+    host: import("zod").ZodString;
+    port: import("zod").ZodDefault<import("zod").ZodNumber>;
+    user: import("zod").ZodString;
+    displayName: import("zod").ZodString;
+    address: import("zod").ZodEmail;
+    password: import("zod").ZodString;
+    smtpHost: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodUnion<readonly [import("zod").ZodLiteral<"">, import("zod").ZodString]>>>;
+    smtpPort: import("zod").ZodNumber;
+}, import("zod/v4/core").$strip>, {
+    accountId: string;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, null, undefined>;

package/dist/inbound-provider-imap/connect-my-mailbox.js

@@ -0,0 +1,25 @@
+// connect-my-mailbox: a member connects a personal password IMAP mailbox (owner = the caller).
+// Same login check and secret write as connect-mailbox; the sender-check policy is tenant-wide and
+// stays with the admin form.
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { checkMailboxLogin, connectMailboxSchema, connectPasswordMailbox, credentialDocumentOf, SECRET_TRANSACTION_REASON, } from "./connect-mailbox.js";
+const connectMyMailboxSchema = connectMailboxSchema.omit({ trustedAuthservId: true });
+const MY_MAILBOX_ESCAPE_REASON = `${SECRET_TRANSACTION_REASON}; the account is created with writeAs(system) on connect-account, which is admin-only, and the owner comes from the caller's session`;
+export const createConnectMyMailboxHandler = ({ memberRoles }) => defineWriteHandler({
+    name: "connect-my-mailbox",
+    description: "Connects a personal IMAP mailbox of the caller with a password over implicit TLS: checks the IMAP login and the SMTP login of the outgoing server first, then creates the mail account owned by the caller and stores both servers, user and password as its credential secret in one step. A disconnected personal mailbox of the caller with the same address is reactivated under its old account id.",
+    // The payload carries the plaintext password: as a tool call it would reach the model provider.
+    agent: { expose: false },
+    schema: connectMyMailboxSchema,
+    access: { roles: [...memberRoles] },
+    // Each call opens a connection to a host the caller picks; per user, because any member may call it.
+    rateLimit: { per: "user", limit: 10, windowSeconds: 600 },
+    // connect-account is admin-only; the personal mailbox is created through the system identity. The owner
+    // is always event.user.id from the session, never a payload field.
+    escapeHatch: { grants: ["unsafeRaw", "systemIdentity"], reason: MY_MAILBOX_ESCAPE_REASON },
+    beforeTransaction: (event, ctx) => checkMailboxLogin(credentialDocumentOf(event.payload), ctx.obs.log),
+    handler: async (event, ctx) => {
+        const { displayName, address } = event.payload;
+        return connectPasswordMailbox("connect-my-mailbox", event, ctx, { displayName, address, credentialDocument: credentialDocumentOf(event.payload) }, "user");
+    },
+});

package/dist/inbound-provider-imap/constants.d.ts

@@ -1,7 +1,18 @@
 export declare const FEATURE_NAME = "inbound-provider-imap";
-export declare const IMAP_PROVIDER_KEY = "imap";
+export { IMAP_PROVIDER_KEY } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
 export declare const ImapHandlers: {
     readonly connectMailbox: "inbound-provider-imap:write:connect-mailbox";
+    readonly connectMyMailbox: "inbound-provider-imap:write:connect-my-mailbox";
+    readonly reconnectMailbox: "inbound-provider-imap:write:reconnect-mailbox";
+};
+export declare const ImapQueries: {
+    readonly reconnectPrefill: "inbound-provider-imap:query:reconnect-prefill";
+};
+export declare const IMAP_RECONNECT_ERRORS: {
+    readonly notPasswordImap: {
+        readonly reason: "reconnect_not_password_imap";
+        readonly i18nKey: "inboundMail.imap.reconnect.errors.notPasswordImap";
+    };
 };
 export declare const IMAP_CONNECT_ERRORS: {
     readonly hostUnreachable: {

package/dist/inbound-provider-imap/constants.js

@@ -1,7 +1,18 @@
 export const FEATURE_NAME = "inbound-provider-imap";
-export const IMAP_PROVIDER_KEY = "imap";
+export { IMAP_PROVIDER_KEY } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
 export const ImapHandlers = {
     connectMailbox: "inbound-provider-imap:write:connect-mailbox",
+    connectMyMailbox: "inbound-provider-imap:write:connect-my-mailbox",
+    reconnectMailbox: "inbound-provider-imap:write:reconnect-mailbox",
+};
+export const ImapQueries = {
+    reconnectPrefill: "inbound-provider-imap:query:reconnect-prefill",
+};
+export const IMAP_RECONNECT_ERRORS = {
+    notPasswordImap: {
+        reason: "reconnect_not_password_imap",
+        i18nKey: "inboundMail.imap.reconnect.errors.notPasswordImap",
+    },
 };
 export const IMAP_CONNECT_ERRORS = {
     hostUnreachable: {

package/dist/inbound-provider-imap/credential-document.js

@@ -18,7 +18,7 @@
 // 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, inboundCredentialSecretKey, } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import { InboundAuthError, InboundCredentialNotStoredError, inboundCredentialSecretKey, } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
 import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
 import * as z from "zod";
 import { FEATURE_NAME, SMTP_SUBMISSION_PORT } from "./constants.js";
@@ -60,7 +60,7 @@ export async function readCredentialDocument(ctx, account) {
     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} — ` +
+        throw new InboundCredentialNotStoredError(`${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());

package/dist/inbound-provider-imap/download-batch.d.ts

@@ -0,0 +1,6 @@
+import type { RawInboundMessage, RejectedInboundMessage } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import type { ImapFlow } from "imapflow";
+export declare function downloadBatch(client: ImapFlow, batch: readonly number[], uidValidity: string, trustedAuthservId: string | null): Promise<{
+    readonly messages: RawInboundMessage[];
+    readonly rejected: RejectedInboundMessage[];
+}>;

package/dist/inbound-provider-imap/download-batch.js

@@ -0,0 +1,24 @@
+import { coerceDate, parseOrReject } from "./parse-message.js";
+export async function downloadBatch(client, batch, uidValidity, trustedAuthservId) {
+    const messages = [];
+    const rejected = [];
+    if (batch.length === 0)
+        return { messages, rejected };
+    for await (const msg of client.fetch(batch.join(","), { uid: true, internalDate: true, source: true, envelope: true }, { uid: true })) {
+        if (!msg.source)
+            continue;
+        const parsed = await parseOrReject({
+            source: msg.source,
+            uid: msg.uid,
+            uidValidity,
+            internalDate: coerceDate(msg.internalDate ?? undefined),
+            envelope: msg.envelope,
+            trustedAuthservId,
+        });
+        if ("message" in parsed)
+            messages.push(parsed.message);
+        else
+            rejected.push(parsed.rejected);
+    }
+    return { messages, rejected };
+}

package/dist/inbound-provider-imap/feature.d.ts

@@ -1,9 +1,9 @@
-import { type InboundMailProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import { type InboundMailProviderPlugin, type InboundMailRoleOptions } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
 export { IMAP_PROVIDER_KEY } from "./constants.ts";
 export { setImapMailHostLookup } from "./imap-client.ts";
 /** Exported for the live test (imap-live.integration.test.ts) —
  *  applications use the feature, never the plugin directly. */
 export declare const imapInboundMailPlugin: InboundMailProviderPlugin;
-export declare function createInboundProviderImapFeature(): import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
+export declare function createInboundProviderImapFeature(options?: InboundMailRoleOptions): import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
     readonly exports: void;
 };

package/dist/inbound-provider-imap/feature.js

@@ -23,25 +23,36 @@
 // (credential-document.ts), not tenant configuration, because one tenant
 // can have multiple accounts with different hosts.
 import { mailAllowedPrivateHostsEnvSchema } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
-import { INBOUND_MAIL_PROVIDER_EXTENSION, } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import { assertRolesMatchFoundation, INBOUND_MAIL_PROVIDER_EXTENSION, resolveInboundMailRoles, roleDedupeOptions, } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { instantToLegacyDate } from "@cosmicdrift/kumiko-framework/time";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
-import { connectMailboxHandler } from "./connect-mailbox.js";
+import { createConnectMailboxHandler } from "./connect-mailbox.js";
+import { createConnectMyMailboxHandler } from "./connect-my-mailbox.js";
 import { FEATURE_NAME, IMAP_PROVIDER_KEY } from "./constants.js";
 import { readCredentialDocument } from "./credential-document.js";
+import { downloadBatch } from "./download-batch.js";
+import { fetchMessageContent } from "./fetch-content.js";
 import { INBOUND_PROVIDER_IMAP_I18N } from "./i18n.js";
-import { assertUidValidity, coerceDate, connectOnce, createImapClient, IMAP_MAILBOX, imapMailHostGuard, mapImapError, parseImapCursor, toRawInboundMessage, } from "./imap-client.js";
-import { imapConnectScreen } from "./screens.js";
+import { assertUidValidity, closeOnAbort, connectOnce, createImapClient, IMAP_MAILBOX, imapMailHostGuard, mapImapError, parseImapCursor, } from "./imap-client.js";
+import { buildProviderMessageId, coerceDate, parseOrReject } from "./parse-message.js";
+import { createReconnectMailboxHandler } from "./reconnect-mailbox.js";
+import { createReconnectPrefillQuery } from "./reconnect-prefill.query.js";
+import { createImapScreens } from "./screens.js";
 import { sendFromImapAccount } from "./send-mail.js";
 export { IMAP_PROVIDER_KEY } from "./constants.js";
 export { setImapMailHostLookup } from "./imap-client.js";
 // =============================================================================
 // fetch — inkrementeller UID-Sync
 // =============================================================================
+async function unknownUidsOf(uids, uidValidity, filterUnknownMessageIds) {
+    const unknownIds = await filterUnknownMessageIds(uids.map((uid) => buildProviderMessageId(uidValidity, uid)));
+    return uids.filter((uid) => unknownIds.has(buildProviderMessageId(uidValidity, uid)));
+}
 async function fetchMessages(ctx, account, cursor, opts) {
     const doc = await readCredentialDocument(ctx, account);
     const client = await createImapClient(doc, imapMailHostGuard());
+    const stopWatchingAbort = closeOnAbort(client, opts.signal);
     let lock;
     try {
         await client.connect();
@@ -65,27 +76,19 @@ async function fetchMessages(ctx, account, cursor, opts) {
             uids = (await client.search({ since: instantToLegacyDate(since) }, { uid: true })) || [];
         }
         uids.sort((a, b) => a - b);
-        const batch = uids.slice(0, opts.maxMessages);
-        const hasMore = uids.length > batch.length;
-        const messages = [];
-        let maxUid = parsedCursor?.lastUid ?? 0;
-        if (batch.length > 0) {
-            for await (const msg of client.fetch(batch.join(","), { uid: true, internalDate: true, source: true }, { uid: true })) {
-                if (!msg.source)
-                    continue;
-                messages.push(await toRawInboundMessage({
-                    source: msg.source,
-                    uid: msg.uid,
-                    uidValidity: serverUidValidity,
-                    internalDate: coerceDate(msg.internalDate ?? undefined),
-                }));
-                if (msg.uid > maxUid)
-                    maxUid = msg.uid;
-            }
-        }
+        // Known mails (ingested or quarantined) are not downloaded again; the cursor still moves past them.
+        const unknown = opts.filterUnknownMessageIds
+            ? await unknownUidsOf(uids, serverUidValidity, opts.filterUnknownMessageIds)
+            : uids;
+        const batch = unknown.slice(0, opts.maxMessages);
+        const hasMore = unknown.length > batch.length;
+        const { messages, rejected } = await downloadBatch(client, batch, serverUidValidity, account.trustedAuthservId ?? null);
+        // From the UIDs, not from what was downloaded: a known or skipped mail must not hold the cursor back.
+        const lastUid = Math.max(parsedCursor?.lastUid ?? 0, ...(hasMore ? batch : uids));
         return {
             messages,
-            nextCursor: { uidValidity: serverUidValidity, lastUid: maxUid },
+            ...(rejected.length > 0 && { rejected }),
+            nextCursor: { uidValidity: serverUidValidity, lastUid },
             hasMore,
         };
     }
@@ -93,6 +96,7 @@ async function fetchMessages(ctx, account, cursor, opts) {
         throw err instanceof Error && "kind" in err ? err : mapImapError(err, doc.host);
     }
     finally {
+        stopWatchingAbort();
         lock?.release();
         await client.logout().catch(() => { });
     }
@@ -114,23 +118,29 @@ async function watchMailbox(ctx, account, handlers) {
         let nextUid = Number(mailbox.uidNext ?? 1);
         const drainNew = async () => {
             const messages = [];
+            const rejected = [];
             let maxSeen = nextUid - 1;
             for await (const msg of client.fetch(`${nextUid}:*`, { uid: true, internalDate: true, source: true }, { uid: true })) {
                 // `N:*` gotcha (see fetch): filter out the previous last message.
                 if (msg.uid < nextUid || !msg.source)
                     continue;
-                messages.push(await toRawInboundMessage({
+                const parsed = await parseOrReject({
                     source: msg.source,
                     uid: msg.uid,
                     uidValidity,
                     internalDate: coerceDate(msg.internalDate ?? undefined),
-                }));
+                    trustedAuthservId: account.trustedAuthservId ?? null,
+                });
+                if ("message" in parsed)
+                    messages.push(parsed.message);
+                else
+                    rejected.push(parsed.rejected);
                 if (msg.uid > maxSeen)
                     maxSeen = msg.uid;
             }
             nextUid = maxSeen + 1;
-            if (messages.length > 0)
-                await handlers.onMessages(messages);
+            if (messages.length > 0 || rejected.length > 0)
+                await handlers.onMessages(messages, rejected);
         };
         client.on("exists", () => {
             // skip: ignore delayed exists events after the watcher has stopped.
@@ -190,15 +200,17 @@ export const imapInboundMailPlugin = {
     verify: async (ctx, account) => connectOnce(await readCredentialDocument(ctx, account), false),
     probe: async (ctx, account) => connectOnce(await readCredentialDocument(ctx, account), true),
     fetch: fetchMessages,
+    fetchContent: fetchMessageContent,
     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).
 };
-export function createInboundProviderImapFeature() {
+export function createInboundProviderImapFeature(options = {}) {
+    const roles = resolveInboundMailRoles(options);
     return defineFeature(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.');
+        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 shared mailbox through the "Connect mailbox" form on the mail accounts list and members a personal one through the same form on "My mail accounts" (`connect-mailbox` and `connect-my-mailbox` check 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",
             category: "notifications",
@@ -208,8 +220,13 @@ 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.bootCheck(({ features }) => assertRolesMatchFoundation(FEATURE_NAME, roles, features));
+        r.writeHandler(createConnectMailboxHandler(roles));
+        r.writeHandler(createConnectMyMailboxHandler(roles));
+        r.writeHandler(createReconnectMailboxHandler(roles));
+        r.queryHandler(createReconnectPrefillQuery(roles));
+        for (const screen of createImapScreens(roles))
+            r.screen(screen);
         r.translations({ keys: INBOUND_PROVIDER_IMAP_I18N });
-    }, { dedupeOptions: {} });
+    }, { dedupeOptions: roleDedupeOptions(roles) });
 }

package/dist/inbound-provider-imap/fetch-content.d.ts

@@ -0,0 +1,4 @@
+import type { InboundContentFetchResult, InboundMailContext, MailAccountRecord } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+export declare function fetchMessageContent(ctx: InboundMailContext, account: MailAccountRecord, providerMessageIds: readonly string[], opts?: {
+    readonly signal?: AbortSignal;
+}): Promise<InboundContentFetchResult>;

package/dist/inbound-provider-imap/fetch-content.js

@@ -0,0 +1,68 @@
+// Re-downloads already imported mails whose content was stored as snippet only. A provider message
+// id is "<uidValidity>:<uid>"; ids from another UIDVALIDITY or gone from the server are "missing"
+// (nothing to reload, ever), mails the parser cannot read are "rejected".
+import { InboundTransientError } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import { readCredentialDocument } from "./credential-document.js";
+import { closeOnAbort, createImapClient, IMAP_MAILBOX, imapMailHostGuard, mapImapError, } from "./imap-client.js";
+import { coerceDate, parseOrReject } from "./parse-message.js";
+function uidOf(providerMessageId, serverUidValidity) {
+    const separator = providerMessageId.lastIndexOf(":");
+    if (separator < 0 || providerMessageId.slice(0, separator) !== serverUidValidity)
+        return null;
+    const uid = Number(providerMessageId.slice(separator + 1));
+    return Number.isInteger(uid) && uid > 0 ? uid : null;
+}
+export async function fetchMessageContent(ctx, account, providerMessageIds, opts) {
+    const doc = await readCredentialDocument(ctx, account);
+    const client = await createImapClient(doc, imapMailHostGuard());
+    const stopWatchingAbort = closeOnAbort(client, opts?.signal);
+    let lock;
+    try {
+        await client.connect();
+        lock = await client.getMailboxLock(IMAP_MAILBOX);
+        const mailbox = client.mailbox;
+        if (typeof mailbox === "boolean")
+            throw new InboundTransientError("mailbox not open");
+        const serverUidValidity = String(mailbox.uidValidity);
+        const idByUid = new Map();
+        const missing = [];
+        for (const id of providerMessageIds) {
+            const uid = uidOf(id, serverUidValidity);
+            if (uid === null)
+                missing.push(id);
+            else
+                idByUid.set(uid, id);
+        }
+        const messages = [];
+        const rejected = [];
+        if (idByUid.size > 0) {
+            for await (const msg of client.fetch([...idByUid.keys()].join(","), { uid: true, internalDate: true, source: true, envelope: true }, { uid: true })) {
+                if (!msg.source)
+                    continue;
+                const parsed = await parseOrReject({
+                    source: msg.source,
+                    uid: msg.uid,
+                    uidValidity: serverUidValidity,
+                    internalDate: coerceDate(msg.internalDate ?? undefined),
+                    envelope: msg.envelope,
+                });
+                idByUid.delete(msg.uid);
+                if ("message" in parsed)
+                    messages.push(parsed.message);
+                else
+                    rejected.push(parsed.rejected);
+            }
+        }
+        // What the server did not return is gone (expunged since the import).
+        missing.push(...idByUid.values());
+        return { messages, missing, rejected };
+    }
+    catch (err) {
+        throw err instanceof Error && "kind" in err ? err : mapImapError(err, doc.host);
+    }
+    finally {
+        stopWatchingAbort();
+        lock?.release();
+        await client.logout().catch(() => { });
+    }
+}