@cosmicdrift/kumiko-samples 0.393.0 → 0.394.0

package/packages/bundled-features/src/inbound-mail-foundation/web/client-plugin.ts

@@ -0,0 +1,73 @@
+// Client feature for inbound-mail-foundation. The mail account screens offer "Reactivate" for an OAuth
+// mailbox as a clientAction: signing in again is a browser redirect into the same connect route and
+// callback that created the mailbox, which a writeHandler cannot do.
+
+import type { ClientActionHandler, ClientActionOutcome } from "@cosmicdrift/kumiko-renderer";
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer/web";
+import {
+  INBOUND_MAIL_CONNECT_PATH,
+  INBOUND_MAIL_FOUNDATION_FEATURE,
+  INBOUND_MAIL_RECONNECT_OAUTH_ACTION,
+} from "./constants.ts";
+
+export type InboundMailFoundationClientOptions = {
+  /** Mount path of the connect route, when the app moved it (`connectPath` of
+   *  createInboundMailConnectRoutes). Default "/api/inbound-mail/connect". */
+  readonly connectPath?: string;
+  /** Leaves the app for the provider's sign-in page. Default: `location.assign`. */
+  readonly navigate?: (url: string) => void;
+};
+
+const INVALID_RECONNECT_ROW = "inboundMail.accounts.reconnect.invalidRow";
+
+function textField(payload: Readonly<Record<string, unknown>>, field: string): string | undefined {
+  const value = payload[field];
+  return typeof value === "string" && value !== "" ? value : undefined;
+}
+
+// The callback trusts only the signed state, which the connect route builds from the session and these
+// parameters; scope "user" makes the signed-in caller the owner, so the route re-checks ownership.
+export function oauthReconnectUrl(
+  connectPath: string,
+  row: { readonly provider: string; readonly address: string; readonly ownerUserId?: string },
+): string {
+  const query = new URLSearchParams({
+    provider: row.provider,
+    scope: row.ownerUserId === undefined ? "shared" : "user",
+    mailbox: row.address,
+  });
+  return `${connectPath}?${query.toString()}`;
+}
+
+function reconnectOauthHandler(
+  connectPath: string,
+  navigate: (url: string) => void,
+): ClientActionHandler {
+  return async (payload): Promise<ClientActionOutcome> => {
+    const provider = textField(payload, "provider");
+    const address = textField(payload, "address");
+    if (provider === undefined || address === undefined) {
+      return { ok: false, message: INVALID_RECONNECT_ROW };
+    }
+    const ownerUserId = textField(payload, "ownerUserId");
+    navigate(
+      oauthReconnectUrl(connectPath, { provider, address, ...(ownerUserId && { ownerUserId }) }),
+    );
+    return { ok: true };
+  };
+}
+
+export function inboundMailFoundationClient(
+  options: InboundMailFoundationClientOptions = {},
+): ClientFeatureDefinition {
+  const navigate = options.navigate ?? ((url: string) => globalThis.location.assign(url));
+  return {
+    name: INBOUND_MAIL_FOUNDATION_FEATURE,
+    clientActions: {
+      [INBOUND_MAIL_RECONNECT_OAUTH_ACTION]: reconnectOauthHandler(
+        options.connectPath ?? INBOUND_MAIL_CONNECT_PATH,
+        navigate,
+      ),
+    },
+  };
+}

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

@@ -0,0 +1,7 @@
+// Constants the browser client shares with the server feature; the server constants re-export them.
+export const INBOUND_MAIL_FOUNDATION_FEATURE = "inbound-mail-foundation" as const;
+
+/** Default mount path of the OAuth connect route; the web client builds the reconnect link from it. */
+export const INBOUND_MAIL_CONNECT_PATH = "/api/inbound-mail/connect";
+/** Client action of the OAuth "Reactivate" row action: sends the browser to the OAuth connect route. */
+export const INBOUND_MAIL_RECONNECT_OAUTH_ACTION = `${INBOUND_MAIL_FOUNDATION_FEATURE}:reconnect-oauth`;

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

@@ -0,0 +1,5 @@
+export {
+  type InboundMailFoundationClientOptions,
+  inboundMailFoundationClient,
+  oauthReconnectUrl,
+} from "./client-plugin.ts";

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

@@ -1,4 +1,34 @@
 [
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "The IMAP provider reads text, HTML and attachments",
+    "detail": "The provider parses full mails. Inline images are skipped, forwarded message/rfc822 mails are unpacked up to depth 3, and the limits are 25 MB per attachment, 50 MB per mail and 50 attachments; everything skipped is reported in skippedAttachments with its reason. The new plugin method fetchContent reloads the content of a mail by provider id."
+  },
+  {
+    "version": "0.394.0",
+    "type": "fix",
+    "title": "IMAP and SMTP hosts given as IP addresses connect over TLS",
+    "detail": "imapflow passes servername false for an IP literal, which Bun's TLS rejects, so such mailboxes could not connect. The IMAP client now sets an undefined servername; nodemailer already omits it for SMTP."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "The IMAP cursor follows UIDs and skips known mails",
+    "detail": "lastUid is derived from the fetched UIDs, so a quarantined or already known mail at the end of a full batch no longer holds the cursor back or gets fetched again; the envelope is read so a mail the parser throws on still gets its header entry. A forwarded mail that cannot be parsed is kept as an attachment instead of failing the whole mail."
+  },
+  {
+    "version": "0.394.0",
+    "type": "improvement",
+    "title": "Members connect a personal IMAP mailbox from \"My mail accounts\"",
+    "detail": "The new write handler inbound-provider-imap:write:connect-my-mailbox (every mail member role, not exposed to the agent, 10 calls per user in 10 minutes) takes the connect-mailbox fields without trustedAuthservId, checks the IMAP and SMTP login first and creates a mailbox owned by the caller. A disconnected personal mailbox of the caller with the same address is reactivated under its old account id; an address that belongs to another user or to a shared mailbox is refused with the usual conflict answer. connect-account stays admin-only; the handler creates the personal account through the system identity with the owner taken from the caller session, never from the payload. The dormant screen my-mail-account-connect-imap (exported as MY_IMAP_CONNECT_SCREEN_ID) is reached from the new \"Connect mailbox\" toolbar action of my-mail-accounts; it has no sender-check field, that policy stays with the admin form. New keys in all locale packages."
+  },
+  {
+    "version": "0.394.0",
+    "type": "fix",
+    "title": "The IMAP watch quarantines an unparseable mail right away",
+    "detail": "A mail the MIME parser cannot handle used to be dropped by the live watch and reached the quarantine only with the next reconciliation poll, up to five minutes later. The provider watch handler now passes such mails to `handlers.onMessages(messages, rejected)` and the supervisor quarantines them through the same ingest path as the poll. `onMessages` takes an optional second argument, so existing providers are unaffected. A failed account health update after a quarantine now logs the error code of the rejected write."
+  },
   {
     "version": "0.393.0",
     "type": "improvement",

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

@@ -4,17 +4,25 @@
 // leaves neither behind.
 
 import {
+  type AddressMatch,
+  findMailboxByAddress,
   InboundAuthError,
+  InboundMailAccountStatuses,
   InboundMailAuthMethods,
   InboundMailFoundationHandlers,
+  type InboundMailRoles,
   inboundCredentialSecretKey,
 } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
 import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import { ROLES } from "@cosmicdrift/kumiko-framework/auth";
 import {
   type BeforeTransactionResult,
+  createSystemUser,
   defineWriteHandler,
+  type HandlerContext,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import type { WriteResult } from "@cosmicdrift/kumiko-types/handlers";
 import * as z from "zod";
 import { IMAP_CONNECT_ERRORS, IMAP_PROVIDER_KEY, SMTP_CONNECT_ERRORS } from "./constants.ts";
 import {
@@ -36,12 +44,22 @@ export const connectMailboxSchema = imapCredentialDocumentSchema
     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(),
   });
 type ConnectMailboxLoginFields = Pick<
   z.infer<typeof connectMailboxSchema>,
   "host" | "port" | "user" | "password" | "smtpHost" | "smtpPort"
 >;
 
+function isReopenableByThisForm(existing: AddressMatch, ownerUserId: string | null): boolean {
+  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
@@ -52,9 +70,6 @@ const TLS_FAILURE = /certificate|self[- ]signed|wrong[ _]version[ _]number|EPROT
 // A fixed preview: any slice of the JSON document would expose the host or the user.
 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";
-
 type ConnectFailure = keyof typeof IMAP_CONNECT_ERRORS;
 
 // Most hosters name the outgoing server like the incoming one, or with smtp. for imap.
@@ -122,46 +137,114 @@ export async function checkMailboxLogin(
   return { isSuccess: true, data: null };
 }
 
-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: (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, {
+export 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;
+};
+
+// 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: string,
+  event: { readonly user: { readonly id: string; readonly tenantId: string } },
+  ctx: HandlerContext,
+  mailbox: ConnectedMailbox,
+  scope: "shared" | "user",
+): Promise<WriteResult<{ accountId: string }>> {
+  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: string;
+  if (reopened) {
+    accountId = existing.id;
+  } else {
+    const accountFields = {
       provider: IMAP_PROVIDER_KEY,
       authMethod: InboundMailAuthMethods.password,
       displayName,
       address,
-      scope: "shared",
-    });
+      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;
-    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 } };
-  },
-});
+    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 }: InboundMailRoles) =>
+  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: [...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: (event, ctx) =>
+      checkMailboxLogin(credentialDocumentOf(event.payload), ctx.obs.log),
+    handler: async (event, ctx) => {
+      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 } = 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/packages/bundled-features/src/inbound-provider-imap/connect-my-mailbox.ts

@@ -0,0 +1,45 @@
+// 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 type { InboundMailRoles } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  checkMailboxLogin,
+  connectMailboxSchema,
+  connectPasswordMailbox,
+  credentialDocumentOf,
+  SECRET_TRANSACTION_REASON,
+} from "./connect-mailbox.ts";
+
+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 }: InboundMailRoles) =>
+  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/packages/bundled-features/src/inbound-provider-imap/constants.ts

@@ -1,8 +1,9 @@
 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",
 } as const;
 

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

@@ -21,6 +21,7 @@
 
 import {
   InboundAuthError,
+  InboundCredentialNotStoredError,
   type InboundMailContext,
   inboundCredentialSecretKey,
   type MailAccountRecord,
@@ -82,7 +83,7 @@ export async function readCredentialDocument(
   );
   const secret = await secrets.get(account.tenantId, inboundCredentialSecretKey(account.id));
   if (!secret) {
-    throw new InboundAuthError(
+    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`,
     );

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

@@ -0,0 +1,38 @@
+import type {
+  RawInboundMessage,
+  RejectedInboundMessage,
+} from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import type { ImapFlow } from "imapflow";
+import { coerceDate, parseOrReject } from "./parse-message.ts";
+
+export async function downloadBatch(
+  client: ImapFlow,
+  batch: readonly number[],
+  uidValidity: string,
+  trustedAuthservId: string | null,
+): Promise<{
+  readonly messages: RawInboundMessage[];
+  readonly rejected: RejectedInboundMessage[];
+}> {
+  const messages: RawInboundMessage[] = [];
+  const rejected: RejectedInboundMessage[] = [];
+  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 };
+}