@cosmicdrift/kumiko-samples 0.392.2 → 0.394.0

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

@@ -3,109 +3,269 @@ import {
   MAX_LIST_LIMIT,
   type ProjectionListScreenDefinition,
 } from "@cosmicdrift/kumiko-framework/engine";
-import type { ActionFormScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type {
+  ActionFormScreenDefinition,
+  RowActionClientAction,
+  RowActionNavigate,
+} from "@cosmicdrift/kumiko-framework/ui-types";
 import {
+  INBOUND_MAIL_RECONNECT_OAUTH_ACTION,
   InboundMailAccountStatuses,
   InboundMailFoundationHandlers,
   InboundMailFoundationQueries,
+  MailAccountReactivationPaths,
 } from "./constants.ts";
+import type { InboundMailRoles } from "./mail-roles.ts";
 
 export const MAIL_ACCOUNT_LIST_SCREEN_ID = "mail-accounts";
 export const MAIL_ACCOUNT_EDIT_SCREEN_ID = "mail-account-edit";
 export const MAIL_ACCOUNT_LIST_SCREEN_QN = "inbound-mail-foundation:screen:mail-accounts";
+export const MY_MAIL_ACCOUNT_LIST_SCREEN_ID = "my-mail-accounts";
+export const MY_MAIL_ACCOUNT_LIST_SCREEN_QN = "inbound-mail-foundation:screen:my-mail-accounts";
 // Registered by inbound-provider-imap, which needs the IMAP client to check the login. The
 // renderer drops a navigate action whose target screen is not mounted, so the toolbar button
 // only shows in apps that mount that provider.
+export const MAIL_ACCOUNT_SENDER_CHECK_SCREEN_ID = "mail-account-sender-check";
 export const IMAP_CONNECT_SCREEN_ID = "mail-account-connect-imap";
+// Same reason for the row action "Reactivate" of a password mailbox.
+export const IMAP_RECONNECT_SCREEN_ID = "mail-account-reconnect-imap";
+export const MY_IMAP_RECONNECT_SCREEN_ID = "my-mail-account-reconnect-imap";
+export const MY_IMAP_CONNECT_SCREEN_ID = "my-mail-account-connect-imap";
+export const MAIL_QUARANTINE_SCREEN_ID = "mail-quarantine";
 
 export const MAIL_ACCOUNT_STATUS_OPTION_KEY_PREFIX = "inboundMail.accounts.status.";
+export const MAIL_ACCOUNT_LAST_ERROR_OPTION_KEY_PREFIX = "inboundMail.accounts.lastError.";
 
-// Same roles as the update/disconnect handlers: a screen rule wider than the
+// Screens get the same roles as the handlers behind them: a screen rule wider than the
 // handlers would only render actions that 403.
-const MAIL_ACCOUNT_ADMIN_ACCESS = { roles: ["SystemAdmin", "TenantAdmin"] } as const;
+
+const reactivateOauthAction: RowActionClientAction = {
+  kind: "clientAction",
+  id: "reactivate-oauth",
+  label: i18nKey("inboundMail.accounts.reactivate"),
+  action: INBOUND_MAIL_RECONNECT_OAUTH_ACTION,
+  payload: { map: { provider: "provider", address: "address", ownerUserId: "ownerUserId" } },
+  confirm: i18nKey("inboundMail.accounts.reactivateOauth.confirm"),
+  visible: { field: "reactivateVia", eq: MailAccountReactivationPaths.oauthFlow },
+};
+
+const reactivateImapOwnerAction: RowActionNavigate = {
+  kind: "navigate",
+  id: "reactivate",
+  label: i18nKey("inboundMail.accounts.reactivate"),
+  screen: MY_IMAP_RECONNECT_SCREEN_ID,
+  entityId: "id",
+  visible: { field: "reactivateVia", eq: MailAccountReactivationPaths.passwordForm },
+};
+
+const quarantineAction: RowActionNavigate = {
+  kind: "navigate",
+  id: "quarantine",
+  label: i18nKey("inboundMail.accounts.quarantine"),
+  screen: MAIL_QUARANTINE_SCREEN_ID,
+  visible: { field: "hasOpenQuarantine", eq: true },
+};
+
+const nameAddressStatusColumns: ProjectionListScreenDefinition["columns"] = [
+  { field: "displayName", label: i18nKey("inboundMail.accounts.col.name"), sortable: false },
+  { field: "address", label: i18nKey("inboundMail.accounts.col.address"), sortable: false },
+  {
+    field: "status",
+    label: i18nKey("inboundMail.accounts.col.status"),
+    sortable: false,
+    renderer: { format: "enumOption", keyPrefix: MAIL_ACCOUNT_STATUS_OPTION_KEY_PREFIX },
+  },
+  {
+    field: "lastError",
+    label: i18nKey("inboundMail.accounts.col.lastError"),
+    sortable: false,
+    renderer: { format: "enumOption", keyPrefix: MAIL_ACCOUNT_LAST_ERROR_OPTION_KEY_PREFIX },
+  },
+];
 
 // Several mailboxes per tenant, one row each. The bound query already filters
 // personal mailboxes the caller neither owns nor administers and returns no
 // credential: the secret lives in the secrets feature, never in the row.
 // dormant: the consuming app places the list in its own settings nav.
-export const mailAccountListScreen: ProjectionListScreenDefinition = {
-  id: MAIL_ACCOUNT_LIST_SCREEN_ID,
-  type: "projectionList",
-  agent: { expose: false },
-  query: InboundMailFoundationQueries.listAccounts,
-  pagination: false,
-  pageSize: MAX_LIST_LIMIT,
-  columns: [
-    { field: "displayName", label: i18nKey("inboundMail.accounts.col.name"), sortable: false },
-    { field: "address", label: i18nKey("inboundMail.accounts.col.address"), sortable: false },
-    {
-      field: "provider",
-      label: i18nKey("inboundMail.accounts.col.provider"),
-      sortable: false,
-      hideOnNarrow: true,
-    },
-    {
-      field: "status",
-      label: i18nKey("inboundMail.accounts.col.status"),
-      sortable: false,
-      renderer: { format: "enumOption", keyPrefix: MAIL_ACCOUNT_STATUS_OPTION_KEY_PREFIX },
-    },
-    {
-      field: "connectedAt",
-      label: i18nKey("inboundMail.accounts.col.connected"),
-      sortable: false,
-      hideOnNarrow: true,
-      renderer: { format: "timestamp" },
+export function createMailAccountListScreen({
+  adminRoles,
+}: InboundMailRoles): ProjectionListScreenDefinition {
+  return {
+    id: MAIL_ACCOUNT_LIST_SCREEN_ID,
+    type: "projectionList",
+    agent: { expose: false },
+    query: InboundMailFoundationQueries.listAccounts,
+    pagination: false,
+    pageSize: MAX_LIST_LIMIT,
+    columns: [
+      ...nameAddressStatusColumns,
+      {
+        field: "provider",
+        label: i18nKey("inboundMail.accounts.col.provider"),
+        sortable: false,
+        hideOnNarrow: true,
+      },
+      {
+        field: "quarantinedCount",
+        label: i18nKey("inboundMail.accounts.col.quarantined"),
+        sortable: false,
+        hideOnNarrow: true,
+      },
+      {
+        field: "connectedAt",
+        label: i18nKey("inboundMail.accounts.col.connected"),
+        sortable: false,
+        hideOnNarrow: true,
+        renderer: { format: "timestamp" },
+      },
+    ],
+    rowActions: [
+      {
+        kind: "navigate",
+        id: "edit",
+        label: i18nKey("inboundMail.accounts.edit"),
+        screen: MAIL_ACCOUNT_EDIT_SCREEN_ID,
+        params: { map: { accountId: "id", displayName: "displayName" } },
+        visible: { field: "status", ne: InboundMailAccountStatuses.disconnected },
+      },
+      {
+        kind: "navigate",
+        id: "sender-check",
+        label: i18nKey("inboundMail.accounts.senderCheck"),
+        screen: MAIL_ACCOUNT_SENDER_CHECK_SCREEN_ID,
+        params: { map: { accountId: "id", trustedAuthservId: "trustedAuthservId" } },
+        visible: { field: "status", ne: InboundMailAccountStatuses.disconnected },
+      },
+      {
+        kind: "navigate",
+        id: "reactivate",
+        label: i18nKey("inboundMail.accounts.reactivate"),
+        screen: IMAP_RECONNECT_SCREEN_ID,
+        entityId: "id",
+        // Brings a disconnected or sign-in-failed mailbox back in place, keeping its history.
+        // reactivateVia comes from the list query: only the owner re-arms a personal mailbox.
+        visible: { field: "reactivateVia", eq: MailAccountReactivationPaths.passwordForm },
+      },
+      reactivateOauthAction,
+      quarantineAction,
+      {
+        kind: "writeHandler",
+        id: "acknowledge-quarantine",
+        label: i18nKey("inboundMail.accounts.acknowledgeQuarantine"),
+        handler: InboundMailFoundationHandlers.acknowledgeQuarantine,
+        payload: { map: { accountId: "id" } },
+        visible: { field: "hasOpenQuarantine", eq: true },
+      },
+      {
+        kind: "writeHandler",
+        id: "disconnect",
+        label: i18nKey("inboundMail.accounts.disconnect"),
+        handler: InboundMailFoundationHandlers.disconnectAccount,
+        payload: { map: { accountId: "id" } },
+        style: "danger",
+        confirm: i18nKey("inboundMail.accounts.disconnect.confirm"),
+        visible: { field: "status", ne: InboundMailAccountStatuses.disconnected },
+      },
+    ],
+    toolbarActions: [
+      {
+        kind: "navigate",
+        id: "connect-imap",
+        label: i18nKey("inboundMail.accounts.connectImap"),
+        screen: IMAP_CONNECT_SCREEN_ID,
+        style: "primary",
+      },
+    ],
+    access: { roles: [...adminRoles] },
+    dormant: true,
+  };
+}
+
+// The mailboxes a user sees (own personal ones and the shared ones), for apps that let users connect
+// their own mailbox: an owner re-arms a personal mailbox here without an admin.
+// dormant: the consuming app places it next to its own connect flow.
+export function createMyMailAccountListScreen({
+  memberRoles,
+}: InboundMailRoles): ProjectionListScreenDefinition {
+  return {
+    id: MY_MAIL_ACCOUNT_LIST_SCREEN_ID,
+    type: "projectionList",
+    agent: { expose: false },
+    query: InboundMailFoundationQueries.listAccounts,
+    pagination: false,
+    pageSize: MAX_LIST_LIMIT,
+    columns: nameAddressStatusColumns,
+    rowActions: [reactivateImapOwnerAction, reactivateOauthAction, quarantineAction],
+    toolbarActions: [
+      {
+        kind: "navigate",
+        id: "connect-imap",
+        label: i18nKey("inboundMail.accounts.connectImap"),
+        screen: MY_IMAP_CONNECT_SCREEN_ID,
+        style: "primary",
+      },
+    ],
+    access: { roles: [...memberRoles] },
+    dormant: true,
+  };
+}
+
+export function createMailAccountEditScreen({
+  adminRoles,
+}: InboundMailRoles): ActionFormScreenDefinition {
+  return {
+    id: MAIL_ACCOUNT_EDIT_SCREEN_ID,
+    type: "actionForm",
+    agent: { expose: false },
+    handler: InboundMailFoundationHandlers.updateAccount,
+    fields: {
+      accountId: { type: "text", required: true },
+      displayName: { type: "text", required: true, maxLength: 200 },
     },
-  ],
-  rowActions: [
-    {
-      kind: "navigate",
-      id: "edit",
-      label: i18nKey("inboundMail.accounts.edit"),
-      screen: MAIL_ACCOUNT_EDIT_SCREEN_ID,
-      params: { map: { accountId: "id", displayName: "displayName" } },
-      visible: { field: "status", ne: InboundMailAccountStatuses.disconnected },
+    layout: {
+      sections: [{ fields: [{ field: "accountId", readOnly: true }, "displayName"] }],
     },
-    {
-      kind: "writeHandler",
-      id: "disconnect",
-      label: i18nKey("inboundMail.accounts.disconnect"),
-      handler: InboundMailFoundationHandlers.disconnectAccount,
-      payload: { map: { accountId: "id" } },
-      style: "danger",
-      confirm: i18nKey("inboundMail.accounts.disconnect.confirm"),
-      visible: { field: "status", ne: InboundMailAccountStatuses.disconnected },
+    submitLabel: i18nKey("inboundMail.accounts.edit.submit"),
+    redirect: MAIL_ACCOUNT_LIST_SCREEN_ID,
+    cancelTarget: MAIL_ACCOUNT_LIST_SCREEN_ID,
+    access: { roles: [...adminRoles] },
+    dormant: true,
+  };
+}
+
+export function createMailAccountSenderCheckScreen({
+  adminRoles,
+}: InboundMailRoles): ActionFormScreenDefinition {
+  return {
+    id: MAIL_ACCOUNT_SENDER_CHECK_SCREEN_ID,
+    type: "actionForm",
+    agent: { expose: false },
+    handler: InboundMailFoundationHandlers.setTrustedAuthservId,
+    fields: {
+      accountId: { type: "text", required: true },
+      trustedAuthservId: { type: "text", maxLength: 255 },
     },
-  ],
-  toolbarActions: [
-    {
-      kind: "navigate",
-      id: "connect-imap",
-      label: i18nKey("inboundMail.accounts.connectImap"),
-      screen: IMAP_CONNECT_SCREEN_ID,
-      style: "primary",
+    layout: {
+      sections: [
+        {
+          description: i18nKey("inboundMail.accounts.senderCheckHint"),
+          fields: [{ field: "accountId", readOnly: true }, "trustedAuthservId"],
+        },
+      ],
     },
-  ],
-  access: MAIL_ACCOUNT_ADMIN_ACCESS,
-  dormant: true,
-};
+    submitLabel: i18nKey("inboundMail.accounts.senderCheck.submit"),
+    redirect: MAIL_ACCOUNT_LIST_SCREEN_ID,
+    cancelTarget: MAIL_ACCOUNT_LIST_SCREEN_ID,
+    access: { roles: [...adminRoles] },
+    dormant: true,
+  };
+}
 
-export const mailAccountEditScreen: ActionFormScreenDefinition = {
-  id: MAIL_ACCOUNT_EDIT_SCREEN_ID,
-  type: "actionForm",
-  agent: { expose: false },
-  handler: InboundMailFoundationHandlers.updateAccount,
-  fields: {
-    accountId: { type: "text", required: true },
-    displayName: { type: "text", required: true, maxLength: 200 },
-  },
-  layout: {
-    sections: [{ fields: [{ field: "accountId", readOnly: true }, "displayName"] }],
-  },
-  submitLabel: i18nKey("inboundMail.accounts.edit.submit"),
-  redirect: MAIL_ACCOUNT_LIST_SCREEN_ID,
-  cancelTarget: MAIL_ACCOUNT_LIST_SCREEN_ID,
-  access: MAIL_ACCOUNT_ADMIN_ACCESS,
-  dormant: true,
-};
+export function createMailAccountScreens(roles: InboundMailRoles) {
+  return [
+    createMailAccountListScreen(roles),
+    createMyMailAccountListScreen(roles),
+    createMailAccountEditScreen(roles),
+    createMailAccountSenderCheckScreen(roles),
+  ] as const;
+}

package/packages/bundled-features/src/inbound-mail-foundation/send-from-account.ts

@@ -14,6 +14,7 @@ import {
 import { type MailAccountRow, toMailAccountRecord } from "./account-record.ts";
 import { InboundMailAccountStatuses } from "./constants.ts";
 import { isVisibleToCaller } from "./handlers/scope-visibility.ts";
+import { resolveOutboundAttachments } from "./outbound-attachments.ts";
 import {
   isMailSendNotConfiguredError,
   isMailSendRejectedError,
@@ -22,13 +23,13 @@ import {
   outboundMailMessageSchema,
 } from "./outbound-mail.ts";
 import { mailAccountsProjectionTable } from "./projection.ts";
-import { resolveInboundProviderForAccount } from "./provider-factory.ts";
 import {
-  type InboundMailContext,
   isInboundAuthError,
   isInboundRateLimitError,
   isInboundTransientError,
-} from "./types.ts";
+} from "./provider-errors.ts";
+import { resolveInboundProviderForAccount } from "./provider-factory.ts";
+import type { InboundMailContext } from "./types.ts";
 
 export const MAIL_SEND_ERRORS = {
   notConfigured: {
@@ -48,13 +49,23 @@ export const MAIL_SEND_ERRORS = {
     reason: "mail_send_invalid_message",
     i18nKey: "inboundMail.send.errors.invalidMessage",
   },
+  attachmentInvalid: {
+    reason: "mail_send_attachment_invalid",
+    i18nKey: "inboundMail.send.errors.attachmentInvalid",
+  },
+  attachmentsTooLarge: {
+    reason: "mail_send_attachments_too_large",
+    i18nKey: "inboundMail.send.errors.attachmentsTooLarge",
+  },
 } as const;
 export type MailSendFailure = keyof typeof MAIL_SEND_ERRORS;
 
+// Query-only dispatch: attachment reads run as the caller, and a send path must not be able to
+// write through the caller's rights.
 export type SendMailFromAccountContext = Pick<
   HandlerContext,
   "db" | "registry" | "user" | "services" | "obs"
->;
+> & { readonly dispatch: Pick<HandlerContext["dispatch"], "query"> };
 
 export type SendMailFromAccountInput = {
   readonly accountId: string;
@@ -104,8 +115,16 @@ export async function sendMailFromAccount(
   const plugin = resolveInboundProviderForAccount(providerCtx, account, HANDLER_NAME);
   if (!plugin.send) return sendFailure("notConfigured");
 
+  const attachmentFileIds = message.data.attachmentFileIds ?? [];
+  const resolved = await resolveOutboundAttachments(ctx, attachmentFileIds);
+  if (!resolved.isSuccess) return sendFailure(resolved.failure);
+
   try {
-    return { isSuccess: true, data: await plugin.send(providerCtx, account, message.data) };
+    const sent = await plugin.send(providerCtx, account, message.data, resolved.attachments);
+    return {
+      isSuccess: true,
+      data: { messageIdHeader: sent.messageIdHeader, attachmentFileIds: resolved.fileIds },
+    };
   } catch (err) {
     const failure = sendFailureOf(err);
     if (!failure) throw err;

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

@@ -0,0 +1,215 @@
+// Sender authentication (SPF, DKIM, DMARC) as the receiving mail server reported it in its
+// Authentication-Results header (RFC 8601). A wrong "pass" is a security bug, so every doubt
+// ends in null (no statement) or "unknown".
+//
+// Trust (RFC 8601 sections 5 and 7.1): the account names the authserv-id of its own mail server
+// (trustedAuthservId). Only the topmost Authentication-Results header is read: the receiving server
+// prepends its own entry, so the topmost one is from the own server and everything below it can be
+// forged by the sender. If the topmost header names a different authserv-id there is no result.
+// Without a trusted id, without a matching header or when the header was evaluated for
+// another From domain than the mail's, there is no result at all.
+
+import * as z from "zod";
+
+export const SENDER_AUTH_VERDICTS = ["pass", "fail", "none", "unknown"] as const;
+export type SenderAuthVerdict = (typeof SENDER_AUTH_VERDICTS)[number];
+
+const verdictSchema = z.enum(SENDER_AUTH_VERDICTS);
+
+export const MAX_DKIM_DOMAINS = 10;
+
+export const senderAuthenticationSchema = z.object({
+  /** The authserv-id of the trusted header the verdicts come from, lower case. */
+  authservId: z.string().min(1).max(255),
+  spf: verdictSchema,
+  dkim: verdictSchema,
+  /** header.d of the dkim results, lower case, at most MAX_DKIM_DOMAINS. */
+  dkimDomains: z.array(z.string().max(255)).max(MAX_DKIM_DOMAINS),
+  dmarc: verdictSchema,
+  /** Domain of the mail's From address, lower case: the domain the dmarc verdict was bound to. */
+  fromDomain: z.string().min(1).max(255),
+});
+export type SenderAuthentication = z.infer<typeof senderAuthenticationSchema>;
+/** null = no trustworthy statement (no trusted id, no matching header, From domain mismatch). */
+export const senderAuthenticationFieldSchema = senderAuthenticationSchema.nullable();
+
+/** True only when the account's own server vouched for the From domain via DMARC. */
+export function isSenderAuthenticated(
+  senderAuthentication: SenderAuthentication | null | undefined,
+): boolean {
+  return senderAuthentication?.dmarc === "pass";
+}
+
+/** Empty input means "not set"; ids are compared case-insensitively, so they are stored lower case. */
+export function normalizeTrustedAuthservId(raw: string | null | undefined): string | null {
+  const id = raw?.trim().toLowerCase() ?? "";
+  return id === "" ? null : id;
+}
+
+export function fromDomainOf(address: string): string | null {
+  const at = address.lastIndexOf("@");
+  const domain = (at < 0 ? "" : address.slice(at + 1)).trim().toLowerCase().replace(/>$/, "");
+  return domain === "" ? null : domain;
+}
+
+const RESULT_TO_VERDICT: Readonly<Record<string, SenderAuthVerdict>> = {
+  pass: "pass",
+  fail: "fail",
+  softfail: "fail",
+  none: "none",
+};
+
+/** Index right after the quoted string that starts at `start`; a backslash escapes the next char. */
+function quotedStringEnd(value: string, start: number): number {
+  for (let i = start + 1; i < value.length; i++) {
+    const char = value.charAt(i);
+    if (char === "\\") i++;
+    else if (char === '"') return i + 1;
+  }
+  return value.length;
+}
+
+/** Comments in parentheses may nest and may hide quoted text; folding is plain whitespace. */
+function stripComments(value: string): string {
+  let depth = 0;
+  let out = "";
+  for (let i = 0; i < value.length; i++) {
+    const char = value.charAt(i);
+    if (depth === 0 && char === '"') {
+      const end = quotedStringEnd(value, i);
+      out += value.slice(i, end);
+      i = end - 1;
+    } else if (char === "\\" && depth > 0) {
+      i++;
+    } else if (char === "(") {
+      depth++;
+    } else if (char === ")" && depth > 0) {
+      depth--;
+    } else if (depth === 0) {
+      out += char;
+    }
+  }
+  return out;
+}
+
+function splitSegments(value: string): string[] {
+  const segments: string[] = [];
+  let current = "";
+  for (let i = 0; i < value.length; i++) {
+    const char = value.charAt(i);
+    if (char === '"') {
+      const end = quotedStringEnd(value, i);
+      current += value.slice(i, end);
+      i = end - 1;
+    } else if (char === ";") {
+      segments.push(current.trim());
+      current = "";
+    } else {
+      current += char;
+    }
+  }
+  segments.push(current.trim());
+  return segments;
+}
+
+const RESULT_PATTERN = /^([a-z0-9-]+)\s*=\s*([a-z0-9-]+)(?:\s|$)/i;
+const PROPERTY_PATTERN = /(?:^|\s)header\.(d|from)\s*=\s*"?([^\s";]+)"?/gi;
+
+type MethodResult = {
+  readonly verdict: SenderAuthVerdict;
+  readonly headerD: string | null;
+  readonly headerFrom: string | null;
+};
+
+function propertyOf(segment: string, name: "d" | "from"): string | null {
+  for (const match of segment.matchAll(PROPERTY_PATTERN)) {
+    if (match[1]?.toLowerCase() === name) return (match[2] ?? "").toLowerCase();
+  }
+  return null;
+}
+
+function methodResults(segments: readonly string[]): {
+  byMethod: Map<string, MethodResult[]>;
+  headerFroms: string[];
+} {
+  const byMethod = new Map<string, MethodResult[]>();
+  const headerFroms: string[] = [];
+  for (const segment of segments) {
+    const match = RESULT_PATTERN.exec(segment);
+    if (!match) continue;
+    const method = (match[1] ?? "").toLowerCase();
+    const headerFrom = propertyOf(segment, "from");
+    if (headerFrom !== null) headerFroms.push(headerFrom);
+    const result: MethodResult = {
+      verdict: RESULT_TO_VERDICT[(match[2] ?? "").toLowerCase()] ?? "unknown",
+      headerD: propertyOf(segment, "d"),
+      headerFrom,
+    };
+    byMethod.set(method, [...(byMethod.get(method) ?? []), result]);
+  }
+  return { byMethod, headerFroms };
+}
+
+// DKIM: one valid signature is enough, a mail may carry several.
+function combineAnyPass(results: readonly MethodResult[] | undefined): SenderAuthVerdict {
+  const verdicts = results?.map((result) => result.verdict) ?? [];
+  if (verdicts.includes("pass")) return "pass";
+  if (verdicts.includes("fail")) return "fail";
+  if (verdicts.includes("none")) return "none";
+  return "unknown";
+}
+
+// SPF and DMARC have one verdict per mail; contradicting entries must never read as a pass.
+function combineAllPass(results: readonly MethodResult[] | undefined): SenderAuthVerdict {
+  const verdicts = results?.map((result) => result.verdict) ?? [];
+  if (verdicts.length > 0 && verdicts.every((verdict) => verdict === "pass")) return "pass";
+  if (verdicts.includes("fail")) return "fail";
+  if (verdicts.includes("none")) return "none";
+  return "unknown";
+}
+
+/** header.from may carry a full address or a bare domain. */
+function domainOfHeaderFrom(value: string): string {
+  return fromDomainOf(value) ?? value;
+}
+
+/**
+ * @param headerValues values of all Authentication-Results headers in file order, topmost first
+ * @param trustedAuthservId authserv-id of the account's own server; null = none set, no result
+ * @param fromDomain domain of the mail's From address
+ */
+export function parseSenderAuthentication(
+  headerValues: readonly string[],
+  trustedAuthservId: string | null,
+  fromDomain: string | null,
+): SenderAuthentication | null {
+  const trusted = normalizeTrustedAuthservId(trustedAuthservId);
+  const from = fromDomain?.toLowerCase() ?? "";
+  if (trusted === null || from === "") return null;
+  const headerValue = headerValues[0];
+  if (headerValue === undefined) return null;
+  const [head = "", ...resultSegments] = splitSegments(stripComments(headerValue));
+  const authservId = head.split(/\s+/)[0]?.toLowerCase() ?? "";
+  if (authservId !== trusted) return null;
+  const { byMethod, headerFroms } = methodResults(resultSegments);
+  if (headerFroms.some((value) => domainOfHeaderFrom(value) !== from)) return null;
+  const dmarcResults = byMethod.get("dmarc");
+  // A dmarc pass only means something for the domain it was evaluated for.
+  const dmarcBound = dmarcResults?.every((result) => result.headerFrom !== null) ?? false;
+  const dkimDomains = [
+    ...new Set(
+      (byMethod.get("dkim") ?? []).flatMap((result) => (result.headerD ? [result.headerD] : [])),
+    ),
+  ].slice(0, MAX_DKIM_DOMAINS);
+  // Values come from sender-controlled headers: one that does not fit the stored shape (length)
+  // must give "no statement", not a validation failure that would quarantine the mail.
+  const parsed = senderAuthenticationSchema.safeParse({
+    authservId,
+    spf: combineAllPass(byMethod.get("spf")),
+    dkim: combineAnyPass(byMethod.get("dkim")),
+    dkimDomains,
+    dmarc: dmarcBound ? combineAllPass(dmarcResults) : "unknown",
+    fromDomain: from,
+  });
+  return parsed.success ? parsed.data : null;
+}