@softure-ai/mailing 0.1.6 → 0.1.8

package/src/server/dns.ts

@@ -1,7 +1,9 @@
 // The sender domain's DNS, as receivers check it: SPF (RFC 7208), DKIM (RFC 6376) and DMARC
-// (RFC 7489). Without all three, list mail lands in spam or is refused outright. The check only
-// reads public TXT records; it cannot see whether the provider signs with the published key.
-import { resolveTxt as resolveTxtRecords } from "node:dns/promises";
+// (RFC 7489). Without all three, list mail lands in spam or is refused outright. On request it also
+// holds DMARC to a required minimum, checks that the reply-to domain accepts mail (MX) and that the
+// provider's return-path hosts resolve. The check only reads public records; it cannot see whether
+// the provider signs with the published key.
+import { resolveCname as resolveCnameRecords, resolveMx as resolveMxRecords, resolveTxt as resolveTxtRecords } from "node:dns/promises";
 
 export type DnsCheckStatus = "pass" | "warn" | "fail";
 
@@ -13,6 +15,9 @@ export type DnsFinding =
   | "revoked"
   | "monitor-only"
   | "inherited"
+  | "weak"
+  | "null-mx"
+  | "unexpected-target"
   | "lookup-failed";
 
 export interface DnsCheck {
@@ -29,9 +34,41 @@ export interface SenderDnsReport {
   readonly spf: DnsCheck;
   readonly dkim: DnsCheck;
   readonly dmarc: DnsCheck;
+  /** The reply-to domain's MX, when `replyTo` was given. */
+  readonly replyTo: DnsCheck | null;
+  /** One check per `returnPath` host, in the order given. */
+  readonly returnPath: readonly DnsCheck[];
 }
 
 export type ResolveTxt = (hostname: string) => Promise<string[][]>;
+export interface MxRecord {
+  readonly exchange: string;
+  readonly priority: number;
+}
+export type ResolveMx = (hostname: string) => Promise<MxRecord[]>;
+export type ResolveCname = (hostname: string) => Promise<string[]>;
+
+export type DmarcPolicy = "quarantine" | "reject";
+export type DmarcAlignment = "r" | "s";
+
+/** The least a DMARC record must carry; a weaker one fails as `weak`. Absent tags count as their defaults. */
+export interface DmarcExpectation {
+  /** The policy for the checked domain: `p`, or `sp ?? p` of a parent's record. Also requires `pct` 100. */
+  readonly policy?: DmarcPolicy;
+  /** The policy for subdomains: `sp ?? p`. */
+  readonly subdomainPolicy?: DmarcPolicy;
+  /** `adkim`; absent means relaxed (`r`). */
+  readonly adkim?: DmarcAlignment;
+  /** `aspf`; absent means relaxed (`r`). */
+  readonly aspf?: DmarcAlignment;
+}
+
+/** A host the provider uses for MAIL FROM or bounces. */
+export interface ReturnPathHost {
+  readonly host: string;
+  /** When set, a CNAME must point at this domain or under it (`rmta.net` accepts `send.forge.rmta.net`). */
+  readonly targetDomain?: string;
+}
 
 export interface CheckSenderDnsOptions {
   /** DKIM selectors to look up under `_domainkey`. Default `["resend"]`, the Resend selector. */
@@ -41,22 +78,52 @@ export interface CheckSenderDnsOptions {
    * return path); DMARC accepts that in relaxed alignment.
    */
   readonly spfHosts?: readonly string[];
+  /** Turns a DMARC record weaker than this into a `fail` (e.g. `{ policy: "reject", adkim: "s", aspf: "s" }`). */
+  readonly expectDmarc?: DmarcExpectation;
+  /**
+   * Where replies go (an address, `Name <address>` or a domain): its domain must have MX records and at most one
+   * SPF record, or replies bounce while the sender checks pass.
+   */
+  readonly replyTo?: string;
+  /** Hosts that must resolve as a CNAME or with MX records; `resendReturnPath(domain)` gives Resend's. */
+  readonly returnPath?: readonly ReturnPathHost[];
   readonly resolveTxt?: ResolveTxt;
+  readonly resolveMx?: ResolveMx;
+  readonly resolveCname?: ResolveCname;
 }
 
 export const DEFAULT_DKIM_SELECTORS: readonly string[] = ["resend"];
 
+/** Domain of the CNAME targets Resend publishes for its return-path hosts. */
+export const RESEND_RETURN_PATH_DOMAIN = "rmta.net";
+
+/**
+ * Resend's return-path hosts: `send.<domain>` (MAIL FROM) and `rsend.<domain>`, CNAMEs to `*.rmta.net`. Domains
+ * set up before Resend published `rsend` have MX records on `send` and no `rsend`: check `send` alone there.
+ */
+export function resendReturnPath(domain: string): ReturnPathHost[] {
+  const name = normalizeHost(domain);
+  return [
+    { host: `send.${name}`, targetDomain: RESEND_RETURN_PATH_DOMAIN },
+    { host: `rsend.${name}`, targetDomain: RESEND_RETURN_PATH_DOMAIN },
+  ];
+}
+
 /** Reads the SPF, DKIM and DMARC records of `domain`. Never throws: a failed lookup is a finding. */
 export async function checkSenderDns(domain: string, options: CheckSenderDnsOptions = {}): Promise<SenderDnsReport> {
-  const name = domain.trim().toLowerCase().replace(/\.$/, "");
+  const name = normalizeHost(domain);
   const resolveTxt = options.resolveTxt ?? resolveTxtRecords;
   const lookup = (host: string) => lookupTxt(resolveTxt, host);
-  const [spf, dkim, dmarc] = await Promise.all([
+  const lookupMx = (host: string) => lookupRecords(options.resolveMx ?? resolveMxRecords, host);
+  const lookupCname = (host: string) => lookupRecords(options.resolveCname ?? resolveCnameRecords, host);
+  const [spf, dkim, dmarc, replyTo, returnPath] = await Promise.all([
     checkSpf(lookup, options.spfHosts ?? [name]),
     checkDkim(lookup, (options.dkimSelectors ?? DEFAULT_DKIM_SELECTORS).map((selector) => `${selector}._domainkey.${name}`)),
-    checkDmarc(lookup, name),
+    checkDmarc(lookup, name, options.expectDmarc),
+    options.replyTo === undefined ? null : checkReplyPath(lookup, lookupMx, normalizeHost(getSenderDomain(options.replyTo))),
+    Promise.all((options.returnPath ?? []).map((path) => checkReturnPath(lookupCname, lookupMx, path))),
   ]);
-  return { domain: name, spf, dkim, dmarc };
+  return { domain: name, spf, dkim, dmarc, replyTo, returnPath };
 }
 
 /** The domain part of a sender (`Plan <hello@mail.example.com>` gives `mail.example.com`). */
@@ -69,15 +136,21 @@ export function getSenderDomain(from: string): string {
   return address.slice(address.lastIndexOf("@") + 1).trim().toLowerCase();
 }
 
+function normalizeHost(host: string): string {
+  return host.trim().toLowerCase().replace(/\.$/, "");
+}
+
+type Answer<T> = { readonly kind: "records"; readonly records: T[] } | { readonly kind: "none" } | { readonly kind: "error" };
+type TxtAnswer = Answer<string>;
 type Lookup = (host: string) => Promise<TxtAnswer>;
-type TxtAnswer = { readonly kind: "records"; readonly records: string[] } | { readonly kind: "none" } | { readonly kind: "error" };
+type MxLookup = (host: string) => Promise<Answer<MxRecord>>;
+type CnameLookup = (host: string) => Promise<Answer<string>>;
 
 const NO_RECORD_CODES = new Set(["ENOTFOUND", "ENODATA", "NXDOMAIN"]);
 
-async function lookupTxt(resolveTxt: ResolveTxt, host: string): Promise<TxtAnswer> {
+async function lookupRecords<T>(resolve: (host: string) => Promise<T[]>, host: string): Promise<Answer<T>> {
   try {
-    // A TXT record may arrive in 255-byte chunks; they form one string.
-    const records = (await resolveTxt(host)).map((chunks) => chunks.join(""));
+    const records = await resolve(host);
     return records.length === 0 ? { kind: "none" } : { kind: "records", records };
   } catch (error) {
     const code = (error as { code?: unknown } | null)?.code;
@@ -85,6 +158,15 @@ async function lookupTxt(resolveTxt: ResolveTxt, host: string): Promise<TxtAnswe
   }
 }
 
+async function lookupTxt(resolveTxt: ResolveTxt, host: string): Promise<TxtAnswer> {
+  // A TXT record may arrive in 255-byte chunks; they form one string.
+  return lookupRecords(async (name) => (await resolveTxt(name)).map((chunks) => chunks.join("")), host);
+}
+
+function isSpfRecord(record: string): boolean {
+  return /^v=spf1(\s|$)/i.test(record.trim());
+}
+
 function startsWithTag(record: string, tag: string): boolean {
   return record.trim().toLowerCase().startsWith(tag);
 }
@@ -98,7 +180,7 @@ async function checkSpf(lookup: Lookup, hosts: readonly string[]): Promise<DnsCh
       lookupFailed ??= host;
       continue;
     }
-    const records = answer.kind === "records" ? answer.records.filter((record) => /^v=spf1(\s|$)/i.test(record.trim())) : [];
+    const records = answer.kind === "records" ? answer.records.filter(isSpfRecord) : [];
     if (records.length > 1) return { status: "fail", finding: "multiple", host, record: null };
     const record = records[0];
     if (record === undefined) continue;
@@ -129,9 +211,10 @@ async function checkDkim(lookup: Lookup, hosts: readonly string[]): Promise<DnsC
 
 /**
  * `_dmarc.<domain>`, or the nearest parent's record (the organisational domain's policy, with
- * `sp=` for subdomains when it is set). `p=none` only reports; it protects nothing.
+ * `sp=` for subdomains when it is set). `p=none` only reports; it protects nothing. With an
+ * expectation, a record weaker than it fails as `weak`.
  */
-async function checkDmarc(lookup: Lookup, domain: string): Promise<DnsCheck> {
+async function checkDmarc(lookup: Lookup, domain: string, expected: DmarcExpectation | undefined): Promise<DnsCheck> {
   const labels = domain.split(".");
   const first = `_dmarc.${domain}`;
   for (let index = 0; index <= labels.length - 2; index += 1) {
@@ -144,10 +227,85 @@ async function checkDmarc(lookup: Lookup, domain: string): Promise<DnsCheck> {
     const record = records[0];
     if (record === undefined) continue;
     const inherited = host !== first;
-    const tag = (name: string) => new RegExp(`(?:^|;)\\s*${name}=([^;]*)`, "i").exec(record)?.[1]?.trim().toLowerCase();
-    const policy = (inherited ? (tag("sp") ?? tag("p")) : tag("p")) ?? "none";
+    const tags = readDmarcTags(record);
+    const policy = (inherited ? (tags.get("sp") ?? tags.get("p")) : tags.get("p")) ?? "none";
+    if (expected !== undefined && !meetsDmarcExpectation(tags, policy, expected)) return { status: "fail", finding: "weak", host, record };
     if (policy === "none") return { status: "warn", finding: "monitor-only", host, record };
     return inherited ? { status: "pass", finding: "inherited", host, record } : { status: "pass", finding: "found", host, record };
   }
   return { status: "fail", finding: "missing", host: first, record: null };
 }
+
+/** `tag=value` pairs of a DMARC record, names and values lower-cased; the first occurrence wins. */
+function readDmarcTags(record: string): Map<string, string> {
+  const tags = new Map<string, string>();
+  for (const part of record.split(";")) {
+    const separator = part.indexOf("=");
+    if (separator === -1) continue;
+    const name = part.slice(0, separator).trim().toLowerCase();
+    if (!tags.has(name)) tags.set(name, part.slice(separator + 1).trim().toLowerCase());
+  }
+  return tags;
+}
+
+const POLICY_RANK: Readonly<Record<string, number>> = { none: 0, quarantine: 1, reject: 2 };
+
+/** An unknown policy value counts as `none`, as receivers treat an invalid `p=`. */
+function rankPolicy(policy: string | undefined): number {
+  return (policy === undefined ? undefined : POLICY_RANK[policy]) ?? 0;
+}
+
+function meetsAlignment(actual: string | undefined, expected: DmarcAlignment | undefined): boolean {
+  return expected !== "s" || actual === "s";
+}
+
+function meetsDmarcExpectation(tags: ReadonlyMap<string, string>, policy: string, expected: DmarcExpectation): boolean {
+  if (expected.policy !== undefined) {
+    if (rankPolicy(policy) < rankPolicy(expected.policy)) return false;
+    const percent = tags.get("pct");
+    if (percent !== undefined && Number(percent) !== 100) return false;
+  }
+  if (expected.subdomainPolicy !== undefined && rankPolicy(tags.get("sp") ?? tags.get("p")) < rankPolicy(expected.subdomainPolicy)) return false;
+  return meetsAlignment(tags.get("adkim"), expected.adkim) && meetsAlignment(tags.get("aspf"), expected.aspf);
+}
+
+function formatMx(records: readonly MxRecord[]): string {
+  return [...records]
+    .sort((left, right) => left.priority - right.priority)
+    .map((record) => `${String(record.priority)} ${normalizeHost(record.exchange) || "."}`)
+    .join(", ");
+}
+
+/** A null MX (RFC 7505: one record, exchange `.`) says the domain accepts no mail. Node reports it as `""`. */
+function isNullMx(records: readonly MxRecord[]): boolean {
+  return records.length === 1 && normalizeHost(records[0]?.exchange ?? "") === "";
+}
+
+/** The reply-to domain must accept mail (MX, not a null MX) and publish at most one SPF record. */
+async function checkReplyPath(lookup: Lookup, lookupMx: MxLookup, host: string): Promise<DnsCheck> {
+  const mx = await lookupMx(host);
+  if (mx.kind === "error") return { status: "fail", finding: "lookup-failed", host, record: null };
+  if (mx.kind === "none") return { status: "fail", finding: "missing", host, record: null };
+  if (isNullMx(mx.records)) return { status: "fail", finding: "null-mx", host, record: formatMx(mx.records) };
+  const txt = await lookup(host);
+  if (txt.kind === "error") return { status: "fail", finding: "lookup-failed", host, record: null };
+  if (txt.kind === "records" && txt.records.filter(isSpfRecord).length > 1) return { status: "fail", finding: "multiple", host, record: null };
+  return { status: "pass", finding: "found", host, record: formatMx(mx.records) };
+}
+
+/** A CNAME (to `targetDomain` or under it, when set), else MX records. Strings, not patterns: the domain is input. */
+async function checkReturnPath(lookupCname: CnameLookup, lookupMx: MxLookup, path: ReturnPathHost): Promise<DnsCheck> {
+  const host = normalizeHost(path.host);
+  const cname = await lookupCname(host);
+  if (cname.kind === "error") return { status: "fail", finding: "lookup-failed", host, record: null };
+  if (cname.kind === "records") {
+    const target = normalizeHost(cname.records[0] ?? "");
+    const expected = path.targetDomain === undefined ? null : normalizeHost(path.targetDomain);
+    const matches = expected === null || target === expected || target.endsWith(`.${expected}`);
+    return matches ? { status: "pass", finding: "found", host, record: target } : { status: "fail", finding: "unexpected-target", host, record: target };
+  }
+  const mx = await lookupMx(host);
+  if (mx.kind === "error") return { status: "fail", finding: "lookup-failed", host, record: null };
+  if (mx.kind === "none" || isNullMx(mx.records)) return { status: "fail", finding: "missing", host, record: null };
+  return { status: "pass", finding: "found", host, record: formatMx(mx.records) };
+}

package/src/server/index.ts

@@ -7,6 +7,7 @@ export {
   registerCampaign,
   sendCampaign,
   type CampaignErrorCode,
+  type CampaignHalt,
   type CampaignPlan,
   type CampaignSummary,
   type SendCampaignOptions,
@@ -14,21 +15,32 @@ export {
 export {
   DEFAULT_MAX_ATTEMPTS,
   DEFAULT_STALE_CLAIM_MS,
+  DEFAULT_UNCERTAIN_CLAIM_MS,
   deliverOnce,
   type DeliverOptions,
   type Delivery,
   type DeliveryContext,
   type DeliveryOutcome,
+  type HaltingErrorCode,
 } from "./deliveries.js";
 export {
   checkSenderDns,
   DEFAULT_DKIM_SELECTORS,
   getSenderDomain,
+  RESEND_RETURN_PATH_DOMAIN,
+  resendReturnPath,
   type CheckSenderDnsOptions,
+  type DmarcAlignment,
+  type DmarcExpectation,
+  type DmarcPolicy,
   type DnsCheck,
   type DnsCheckStatus,
   type DnsFinding,
+  type MxRecord,
+  type ResolveCname,
+  type ResolveMx,
   type ResolveTxt,
+  type ReturnPathHost,
   type SenderDnsReport,
 } from "./dns.js";
 export { checkMailingTables } from "./health.js";
@@ -39,6 +51,9 @@ export { isSuppressed, liftSuppression, suppressRecipient, unsubscribe, type Sup
 export {
   buildUnsubscribeLinks,
   getRecipientKey,
+  getUnsubscribeLinkParams,
+  MAX_LEGACY_VALUE_LENGTH,
+  readUnsubscribeLink,
   MIN_UNSUBSCRIBE_SECRET_LENGTH,
   readUnsubscribeSecrets,
   readUnsubscribeToken,
@@ -49,6 +64,8 @@ export {
   UNSUBSCRIBE_SECRET_ENV,
   verifyUnsubscribeToken,
   type Env,
+  type LinkParams,
+  type UnsubscribeLink,
   type UnsubscribeLinks,
   type UnsubscribeSecrets,
   type UnsubscribeToken,

package/src/server/send-mail.ts

@@ -5,7 +5,17 @@
 // link in a footer and the RFC 8058 headers, and is refused for a recipient who unsubscribed.
 import { err, ok, type SoftureConfig } from "@softure-ai/core";
 import type { Queryable } from "@softure-ai/db";
-import { TRANSACTIONAL_KIND, type MailingErrorCode, type MailProvider, type OutgoingMail, type ProviderMessage, type ProviderOutcome, type SendMailOptions, type SendMailResult } from "../contract.js";
+import {
+  TRANSACTIONAL_KIND,
+  type MailingErrorCode,
+  type MailProvider,
+  type OutgoingMail,
+  type ProviderFailureStatus,
+  type ProviderMessage,
+  type ProviderOutcome,
+  type SendMailOptions,
+  type SendMailResult,
+} from "../contract.js";
 import type { MailingMessages } from "../messages/index.js";
 import { addHtmlFooter, addTextFooter, getListUnsubscribeHeaders } from "./list-mail.js";
 import { getMailingModule, getMailingOptions } from "./options.js";
@@ -27,7 +37,9 @@ type MailContent = Omit<ProviderMessage, "from" | "replyTo" | "idempotencyKey">;
 /**
  * Sends `mail` and resolves with the provider's message id or a `mailing.*` code:
  * `invalid_input` (fix the input), `rejected` (do not retry), `unavailable` (retry later with the
- * same `idempotencyKey`), `suppressed` (a list mail to someone who unsubscribed; do not retry).
+ * same `idempotencyKey`), `suppressed` (a list mail to someone who unsubscribed; do not retry),
+ * `provider_refused` / `quota_exceeded` (the account cannot send: stop, fix or wait, then retry). A
+ * failure the provider answered with an HTTP status carries it as `httpStatus`.
  * Throws only when the module is not enabled, or for list mail without `context.db`.
  */
 export async function sendMail(context: MailContext, mail: OutgoingMail, options: SendMailOptions = {}): Promise<SendMailResult> {
@@ -54,11 +66,18 @@ export async function sendMail(context: MailContext, mail: OutgoingMail, options
   if (outcome.status === "sent") {
     return ok({ id: outcome.id, provider: provider.name });
   }
-  const code: MailingErrorCode = `mailing.${outcome.status}`;
+  const code = FAILURE_CODES[outcome.status];
   logFailure(provider, code, { status: outcome.httpStatus });
-  return err(code);
+  return outcome.httpStatus === undefined ? err(code) : { ...err(code), httpStatus: outcome.httpStatus };
 }
 
+const FAILURE_CODES: Readonly<Record<ProviderFailureStatus, MailingErrorCode>> = {
+  rejected: "mailing.rejected",
+  unavailable: "mailing.unavailable",
+  refused: "mailing.provider_refused",
+  quota_exceeded: "mailing.quota_exceeded",
+};
+
 type ListMailResult =
   | { readonly ok: true; readonly value: MailContent }
   | { readonly ok: false; readonly error: "mailing.suppressed" | "mailing.unavailable"; readonly cause: string };
@@ -130,12 +149,17 @@ function readOutcome(outcome: unknown): ProviderOutcome {
   if (status === "sent") {
     return typeof id === "string" && id !== "" ? { status, id } : { status: "unavailable" };
   }
-  if (status === "rejected" || status === "unavailable") {
-    return typeof httpStatus === "number" ? { status, httpStatus } : { status };
+  if (typeof status === "string" && Object.hasOwn(FAILURE_CODES, status)) {
+    const failure = status as ProviderFailureStatus;
+    return isHttpStatus(httpStatus) ? { status: failure, httpStatus } : { status: failure };
   }
   return { status: "unavailable" };
 }
 
+function isHttpStatus(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 100 && value <= 599;
+}
+
 /**
  * The module's only log line. Deliberately takes nothing but the provider, the code, a status,
  * field names and a fixed cause: anything added "for diagnosis" is where an address leaks first.

package/src/server/suppressions.ts

@@ -9,7 +9,7 @@ import { and, eq, inArray } from "drizzle-orm";
 import type { SuppressionSource, UnsubscribeErrorCode } from "../contract.js";
 import { suppressions } from "../schema.js";
 import { getMailingOptions } from "./options.js";
-import { getRecipientKey, readUnsubscribeSecrets, verifyUnsubscribeToken, type Env, type UnsubscribeToken } from "./unsubscribe-link.js";
+import { getRecipientKey, readUnsubscribeSecrets, verifyUnsubscribeToken, type Env, type UnsubscribeLink, type UnsubscribeToken } from "./unsubscribe-link.js";
 
 export type SuppressionContext = ModuleContext<Queryable>;
 
@@ -54,20 +54,22 @@ export async function liftSuppression(ctx: Pick<SuppressionContext, "db">, addre
 }
 
 /**
- * Unsubscribes the recipient of a signed link and runs `onUnsubscribed` in the same transaction,
- * also when the recipient had already unsubscribed (a retried one-click heals a missed hook). The
- * signature is checked before the database is touched; a link that does not verify is
- * `mailing.invalid_link`. Throws on a database failure or when the hook throws (nothing is stored).
+ * Unsubscribes the recipient of a link and runs `onUnsubscribed` in the same transaction, also when
+ * the recipient had already unsubscribed (a retried one-click heals a missed hook). A signed link
+ * (or a bare token) is checked against the secrets before the database is touched; a legacy link
+ * goes to the app's `legacyUnsubscribe.verify`, which names the address. A link that does not
+ * verify is `mailing.invalid_link`. Throws on a database failure, or when `verify` or the hook
+ * throws (nothing is stored).
  */
 export async function unsubscribe(
   ctx: SuppressionContext,
-  token: UnsubscribeToken | null,
+  link: UnsubscribeLink | UnsubscribeToken | null,
   source: Exclude<SuppressionSource, "operator">,
   env: Env = process.env,
 ): Promise<Result<undefined, UnsubscribeErrorCode>> {
-  if (token === null || !verifyUnsubscribeToken(token, readUnsubscribeSecrets(env))) return err("mailing.invalid_link");
+  const recipientKey = await verifyLink(ctx, link, env);
+  if (recipientKey === null) return err("mailing.invalid_link");
   const { onUnsubscribed } = getMailingOptions(ctx.config);
-  const { recipientKey } = token;
   await ctx.db.transaction(async (tx) => {
     const txCtx: SuppressionContext = { ...ctx, db: tx };
     await recordSuppression(txCtx, recipientKey, source);
@@ -75,3 +77,16 @@ export async function unsubscribe(
   });
   return ok();
 }
+
+/** The recipient key a link proves, or `null` when it proves none. */
+async function verifyLink(ctx: SuppressionContext, link: UnsubscribeLink | UnsubscribeToken | null, env: Env): Promise<string | null> {
+  if (link === null) return null;
+  if (!("scheme" in link) || link.scheme === "signed") {
+    const token = "scheme" in link ? link.token : link;
+    return verifyUnsubscribeToken(token, readUnsubscribeSecrets(env)) ? token.recipientKey : null;
+  }
+  const legacy = getMailingOptions(ctx.config).legacyUnsubscribe;
+  if (legacy === undefined) return null;
+  const address: unknown = await legacy.verify(link.values, ctx);
+  return typeof address === "string" && address.trim() !== "" ? getRecipientKey(address) : null;
+}

package/src/server/unsubscribe-link.ts

@@ -5,7 +5,7 @@
 // so it never reaches a log, an error or a result.
 import { createHash, createHmac, timingSafeEqual } from "node:crypto";
 import type { SoftureConfig } from "@softure-ai/core";
-import { getMailingRoutes } from "./options.js";
+import { getMailingOptions, getMailingRoutes } from "./options.js";
 
 /** Signs every new link and verifies. */
 export const UNSUBSCRIBE_SECRET_ENV = "MAILING_UNSUBSCRIBE_SECRET";
@@ -101,6 +101,46 @@ export function buildUnsubscribeLinks(config: SoftureConfig, address: string, se
   };
 }
 
+/** A legacy link's value longer than this makes the link invalid before the app's `verify` sees it. */
+export const MAX_LEGACY_VALUE_LENGTH = 512;
+
+/** The link a person followed: the module's signed one, or one the app sent before it adopted the module. */
+export type UnsubscribeLink =
+  | { readonly scheme: "signed"; readonly token: UnsubscribeToken }
+  | { readonly scheme: "legacy"; readonly values: Readonly<Record<string, string>> };
+
+/** Reads one query or form value; `URLSearchParams` and `FormData` both fit. */
+export interface LinkParams {
+  get(name: string): unknown;
+}
+
+/**
+ * The link in a query or a form. A link with the recipient parameter (`r`) is a signed link, whatever else it
+ * carries, so a crafted URL cannot route a signed link to the app's legacy check. Without it, and with
+ * `mailing({ legacyUnsubscribe })`, a link that has every legacy parameter (non-empty, at most 512 characters) is
+ * a legacy link. Anything else is `null`. Checks no signature: `unsubscribe` does.
+ */
+export function readUnsubscribeLink(params: LinkParams, config: SoftureConfig): UnsubscribeLink | null {
+  if (params.get(RECIPIENT_PARAM) !== null && params.get(RECIPIENT_PARAM) !== undefined) {
+    const token = readUnsubscribeToken(params);
+    return token === null ? null : { scheme: "signed", token };
+  }
+  const legacy = getMailingOptions(config).legacyUnsubscribe;
+  if (legacy === undefined) return null;
+  const values: Record<string, string> = {};
+  for (const name of legacy.params) {
+    const value = params.get(name);
+    if (typeof value !== "string" || value === "" || value.length > MAX_LEGACY_VALUE_LENGTH) return null;
+    values[name] = value;
+  }
+  return { scheme: "legacy", values };
+}
+
+/** The query (or form) parameters that carry `link`, to send it back to the page. */
+export function getUnsubscribeLinkParams(link: UnsubscribeLink): Record<string, string> {
+  return link.scheme === "signed" ? { [RECIPIENT_PARAM]: link.token.recipientKey, [SIGNATURE_PARAM]: link.token.signature } : { ...link.values };
+}
+
 /** The token in a link's query (or a form), when both parameters are present once. */
 export function readUnsubscribeToken(params: { get(name: string): unknown }): UnsubscribeToken | null {
   const recipientKey = params.get(RECIPIENT_PARAM);