@cosmicdrift/kumiko-samples 0.393.0 → 0.395.0

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

@@ -0,0 +1,149 @@
+import type {
+  RawInboundMessage,
+  RejectedInboundMessage,
+} from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+import { legacyDateToInstant } from "@cosmicdrift/kumiko-framework/time";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import type { MessageEnvelopeObject } from "imapflow";
+import { type AddressObject, type ParsedMail, simpleParser } from "mailparser";
+import { extractMailContent } from "./mime-content.ts";
+import { senderAuthenticationOf } from "./sender-auth-headers.ts";
+
+const SNIPPET_MAX = 300;
+
+const log = createFallbackLogger("inbound-provider-imap");
+
+// =============================================================================
+// Message-Normalisierung → RawInboundMessage
+// =============================================================================
+
+function stripAngles(id: string): string {
+  return id.replace(/^<|>$/g, "").trim();
+}
+
+/** Normalizes the References chain: mailparser returns string | string[]
+ *  | undefined; when References is missing, In-Reply-To provides the thread
+ *  anchor. */
+export function normalizeReferences(parsed: {
+  references?: string | string[];
+  inReplyTo?: string;
+}): string[] {
+  const raw = parsed.references;
+  const list = raw === undefined ? [] : Array.isArray(raw) ? raw : raw.split(/\s+/);
+  const refs = list.map(stripAngles).filter((r) => r.length > 0);
+  if (refs.length === 0 && parsed.inReplyTo) {
+    const inReplyTo = stripAngles(parsed.inReplyTo);
+    if (inReplyTo) return [inReplyTo];
+  }
+  return refs;
+}
+
+function addressList(a: AddressObject | AddressObject[] | undefined): string[] {
+  if (!a) return [];
+  const arr = Array.isArray(a) ? a : [a];
+  return arr.map((x) => x.text).filter((t): t is string => Boolean(t));
+}
+
+/** imapflow provides internalDate as either a Date or string depending on
+ *  the code path. The string form is deliberately discarded (no date parsing
+ *  in feature code, no-date-api); toRawInboundMessage then falls back to the
+ *  mailparser Date header, which is always a real Date. */
+export function coerceDate(d: Date | string | undefined): Date | undefined {
+  return d instanceof Date ? d : undefined;
+}
+
+/** providerMessageId: a UID is unique only within a UIDVALIDITY; together,
+ *  they form the stable idempotency anchor. */
+export function buildProviderMessageId(uidValidity: string, uid: number): string {
+  return `${uidValidity}:${uid}`;
+}
+
+export async function toRawInboundMessage(args: {
+  readonly source: Uint8Array;
+  readonly uid: number;
+  readonly uidValidity: string;
+  readonly internalDate: Date | undefined;
+  /** IMAP envelope; lets a mail that cannot be parsed still show sender and subject. */
+  readonly envelope?: MessageEnvelopeObject | undefined;
+  /** authserv-id of the mailbox's own server; without it senderAuthentication is null. */
+  readonly trustedAuthservId?: string | null;
+}): Promise<RawInboundMessage> {
+  const parsed: ParsedMail = await simpleParser(Buffer.from(args.source));
+  const messageIdHeader = parsed.messageId ? stripAngles(parsed.messageId) : null;
+  const receivedAt = args.internalDate ?? parsed.date;
+  const content = await extractMailContent(parsed);
+  const text = parsed.text?.trim() ?? "";
+  return {
+    providerMessageId: buildProviderMessageId(args.uidValidity, args.uid),
+    messageIdHeader: messageIdHeader && messageIdHeader.length > 0 ? messageIdHeader : null,
+    providerThreadId: null,
+    references: normalizeReferences(parsed),
+    from: parsed.from?.text ?? "",
+    to: addressList(parsed.to),
+    cc: addressList(parsed.cc),
+    subject: parsed.subject ?? "",
+    snippet: text.slice(0, SNIPPET_MAX),
+    // Lib-boundary bridge (Date from imapflow/mailparser) → Temporal;
+    // when no date exists, Epoch is the honest marker.
+    receivedAtIso: (receivedAt
+      ? legacyDateToInstant(receivedAt)
+      : Temporal.Instant.fromEpochMilliseconds(0)
+    ).toString(),
+    text: content.text,
+    ...(content.html !== null && { html: content.html }),
+    attachments: content.attachments,
+    skippedAttachments: content.skipped,
+    senderAuthentication: senderAuthenticationOf(parsed, args.trustedAuthservId ?? null),
+    rawMime: args.source,
+    scope: "inbox",
+  };
+}
+
+function envelopeAddresses(list: MessageEnvelopeObject["to"]): string[] {
+  return (list ?? []).map((a) => a.address ?? "").filter((a) => a !== "");
+}
+
+function headersOfEnvelope(
+  envelope: MessageEnvelopeObject,
+  internalDate: Date | undefined,
+): NonNullable<RejectedInboundMessage["headers"]> {
+  const sender = envelope.from?.[0];
+  const receivedAt = internalDate ?? coerceDate(envelope.date);
+  return {
+    from: sender?.address ?? "",
+    to: envelopeAddresses(envelope.to),
+    cc: envelopeAddresses(envelope.cc),
+    subject: envelope.subject ?? "",
+    messageIdHeader: envelope.messageId ? stripAngles(envelope.messageId) : null,
+    receivedAtIso: receivedAt ? legacyDateToInstant(receivedAt).toString() : "",
+  };
+}
+
+export type ParsedOrRejected =
+  | { readonly message: RawInboundMessage }
+  | { readonly rejected: RejectedInboundMessage };
+
+/** A mail the MIME parser cannot handle must not stop the mailbox: it is reported as rejected so the
+ *  foundation quarantines it and the cursor moves on. */
+export async function parseOrReject(
+  args: Parameters<typeof toRawInboundMessage>[0],
+): Promise<ParsedOrRejected> {
+  try {
+    return { message: await toRawInboundMessage(args) };
+  } catch (err) {
+    // Class name only: parser messages can quote header content.
+    log.warn("mail could not be parsed", {
+      uid: args.uid,
+      error: err instanceof Error ? err.name : typeof err,
+    });
+    return {
+      rejected: {
+        providerMessageId: buildProviderMessageId(args.uidValidity, args.uid),
+        reason: "unparseable",
+        rawMime: args.source,
+        ...(args.envelope && { headers: headersOfEnvelope(args.envelope, args.internalDate) }),
+      },
+    };
+  }
+}

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

@@ -1,15 +1,14 @@
 // Loads the mailbox a reconnect targets. The db is tenant-scoped, so another tenant's account id
-// finds nothing.
+// finds nothing. A disconnected mailbox is reconnectable on purpose: it keeps its id, threads and
+// sync cursor, so reconnecting never re-imports history.
 
 import {
-  InboundMailAccountStatuses,
   InboundMailAuthMethods,
   mailAccountsProjectionTable,
 } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
 import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import {
   failNotFound,
-  failUnprocessable,
   UnprocessableError,
   type WriteFailure,
   writeFailure,
@@ -21,7 +20,9 @@ type ReconnectAccountRow = {
   readonly provider: string;
   readonly authMethod: string;
   readonly displayName: string | null;
+  readonly ownerUserId: string | null;
   readonly status: string | null;
+  readonly trustedAuthservId: string | null;
 };
 
 export type ReconnectAccountLookup =
@@ -36,9 +37,6 @@ export async function findReconnectableAccount(
     id: accountId,
   });
   if (!row) return failNotFound("mail-account", accountId);
-  if (row.status === InboundMailAccountStatuses.disconnected) {
-    return failUnprocessable("account_disconnected", { accountId });
-  }
   if (row.provider !== IMAP_PROVIDER_KEY || row.authMethod !== InboundMailAuthMethods.password) {
     const { reason, i18nKey } = IMAP_RECONNECT_ERRORS.notPasswordImap;
     return writeFailure(new UnprocessableError(reason, { i18nKey, details: { accountId } }));

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

@@ -1,18 +1,21 @@
 // reconnect-mailbox: new credentials for an existing password IMAP mailbox, typically after the
 // account went to auth_error. The login is checked before the transaction opens; only then the
-// account goes back to active and the credential secret of the same account is overwritten, both
+// credential secret of the same account is overwritten and the account goes back to active (also from disconnected), both
 // on the request transaction, so a failure leaves status and secret as they were.
 
 import {
-  InboundMailAccountStatuses,
   InboundMailFoundationHandlers,
+  type InboundMailRoles,
   inboundCredentialSecretKey,
+  isMailAdmin,
+  mayReactivateMailbox,
 } 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 { failNotFound } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import {
   CREDENTIAL_PREVIEW,
@@ -23,51 +26,78 @@ import {
 import { findReconnectableAccount } from "./reconnect-account.ts";
 
 const reconnectMailboxSchema = connectMailboxSchema
-  .pick({ host: true, port: true, user: true, password: true, smtpHost: true, smtpPort: true })
+  .pick({
+    host: true,
+    port: true,
+    user: true,
+    password: true,
+    smtpHost: true,
+    smtpPort: true,
+    trustedAuthservId: true,
+  })
   .extend({ accountId: z.uuid() });
 
 const SECRET_TRANSACTION_REASON =
   "the credential secret is written on the request transaction so a failed reconnect rolls the account status back too";
 
-export const reconnectMailboxHandler = defineWriteHandler({
-  name: "reconnect-mailbox",
-  description:
-    "Replaces the credentials of an existing password IMAP mailbox: checks the IMAP login and the SMTP login of the outgoing server first, then overwrites the credential secret of the same account and sets it back to active, keeping its threads and sync cursor.",
-  // The payload carries the plaintext password: as a tool call it would reach the model provider.
-  agent: { expose: false },
-  schema: reconnectMailboxSchema,
-  access: { roles: ["SystemAdmin", "TenantAdmin"] },
-  // Same cap as connect: each call opens a connection to a host the caller picks.
-  rateLimit: { per: "tenant+handler", limit: 10, windowSeconds: 600 },
-  escapeHatch: { grants: ["unsafeRaw"], reason: SECRET_TRANSACTION_REASON },
-  beforeTransaction: async (event, ctx): Promise<BeforeTransactionResult<null>> => {
-    const lookup = await findReconnectableAccount(ctx.db, event.payload.accountId);
-    if (!lookup.isSuccess) return lookup;
-    return checkMailboxLogin(credentialDocumentOf(event.payload), ctx.obs.log);
-  },
-  handler: async (event, ctx) => {
-    const { accountId } = event.payload;
-    const reactivated = await ctx.dispatch.write(InboundMailFoundationHandlers.updateAccount, {
-      accountId,
-      status: InboundMailAccountStatuses.active,
-      watchState: "idle",
-    });
-    if (!reactivated.isSuccess) return reactivated;
-
-    const secrets = requireSecretsContext(
-      { secrets: ctx.services.secrets, user: ctx.user },
-      "reconnect-mailbox",
-    ).withRunner(ctx.db.unsafeRaw());
-    await secrets.set(
-      event.user.tenantId,
-      inboundCredentialSecretKey(accountId),
-      JSON.stringify(credentialDocumentOf(event.payload)),
-      {
-        redact: () => CREDENTIAL_PREVIEW,
-        hint: `IMAP credentials for inbound mail account ${accountId}`,
-        updatedBy: event.user.id,
-      },
-    );
-    return { isSuccess: true, data: { accountId } };
-  },
-});
+export const createReconnectMailboxHandler = ({ memberRoles, adminRoles }: InboundMailRoles) =>
+  defineWriteHandler({
+    name: "reconnect-mailbox",
+    description:
+      "Replaces the credentials of an existing password IMAP mailbox: checks the IMAP login and the SMTP login of the outgoing server first, then overwrites the credential secret of the same account and sets it back to active, keeping its threads and sync cursor.",
+    // The payload carries the plaintext password: as a tool call it would reach the model provider.
+    agent: { expose: false },
+    schema: reconnectMailboxSchema,
+    // Members: the owner re-arms a personal mailbox; the lookup gate keeps shared ones to admins.
+    access: { roles: [...memberRoles] },
+    // Same cap as connect: each call opens a connection to a host the caller picks.
+    rateLimit: { per: "tenant+handler", limit: 10, windowSeconds: 600 },
+    escapeHatch: { grants: ["unsafeRaw"], reason: SECRET_TRANSACTION_REASON },
+    beforeTransaction: async (event, ctx): Promise<BeforeTransactionResult<null>> => {
+      const lookup = await findReconnectableAccount(ctx.db, event.payload.accountId);
+      if (!lookup.isSuccess) return lookup;
+      // Before the login check, so a denied caller cannot make the server probe a host; same answer as a missing account.
+      if (!mayReactivateMailbox(lookup.row.ownerUserId, ctx.user, adminRoles)) {
+        return failNotFound("mail-account", event.payload.accountId);
+      }
+      return checkMailboxLogin(credentialDocumentOf(event.payload), ctx.obs.log);
+    },
+    handler: async (event, ctx) => {
+      const { accountId } = event.payload;
+      // Secret first: reactivate from disconnected requires the credential to exist.
+      const secrets = requireSecretsContext(
+        { secrets: ctx.services.secrets, user: ctx.user },
+        "reconnect-mailbox",
+      ).withRunner(ctx.db.unsafeRaw());
+      await secrets.set(
+        event.user.tenantId,
+        inboundCredentialSecretKey(accountId),
+        JSON.stringify(credentialDocumentOf(event.payload)),
+        {
+          redact: () => CREDENTIAL_PREVIEW,
+          hint: `IMAP credentials for inbound mail account ${accountId}`,
+          updatedBy: event.user.id,
+        },
+      );
+      const reactivated = await ctx.dispatch.write(
+        InboundMailFoundationHandlers.reactivateAccount,
+        {
+          accountId,
+        },
+      );
+      if (!reactivated.isSuccess) return reactivated;
+      // The sender-check policy is tenant-wide: only admins set it, the owner's form does not carry it.
+      if (isMailAdmin(event.user, adminRoles)) {
+        // The admin form shows the stored id, so an empty field means the admin cleared it.
+        const trusted = await ctx.dispatch.write(
+          InboundMailFoundationHandlers.setTrustedAuthservId,
+          {
+            accountId,
+            trustedAuthservId: event.payload.trustedAuthservId ?? null,
+          },
+        );
+        if (!trusted.isSuccess) return trusted;
+      }
+      return { isSuccess: true, data: { accountId } };
+    },
+  });

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

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