@softure-ai/mailing 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -4,6 +4,49 @@ Newest first. Each version lists what changed for an app that uses `@softure-ai/
 production, the version gets a line `verified in: <app>@<commit>` ([docs/05](../../docs/05-adoption-playbook.md),
 "Definition of done"). Versions before the first one below are described in their GitHub Releases (`mailing@x.y.z`).
 
+## 0.2.5
+
+- Named senders (#798): `mailing({ senders: { alerts: "App <alerts@example.com>" } })` adds senders a mail picks by
+  name with `OutgoingMail.sender` (e.g. operator alerts from `alerts`, client mail from `from`). Each is checked like
+  `from`. An unknown name is `mailing.invalid_input` (`fields=sender`) and nothing is sent; a mail without `sender`
+  goes out from `from`, as before. `deliverOnce`, `runDeliveries` and `enqueueDelivery` (through `buildMail`) carry
+  it with the mail; `previewMail` shows the resolved `From`. `ValidMail` gains `sender` (the name, or `null`).
+- `softure-mail dns` without `--domain` checks every distinct domain of `from` and `senders`, one report each, and
+  fails when any of them fails. The REPLY and INBOUND checks stay with the domain of `from`. With several domains,
+  `--spf-host` and `--return-path` hosts count for the domain they sit under; a host under none of them is an error.
+  A config whose senders all share `from`'s domain prints the same report as before.
+- Migrate an app that sends operator alerts and client mail from one sender:
+  1. Add the second sender: `mailing({ from: "App <hello@example.com>", senders: { alerts: "App <alerts@example.com>" } })`.
+  2. Pass `sender: "alerts"` on the alert mail (in `sendMail`, `deliverOnce` or the alert's `buildMail`).
+  3. Run `softure-mail dns` (with `--spf-host send.<domain>` for each domain on Resend) to check every sender domain.
+
+## 0.2.4
+
+- Attachments on `sendMail` and `deliverOnce` (#655): `attachments?: { filename, contentType, content: Uint8Array }[]`
+  on a mail. Checked before sending (`mailing.invalid_input`, `fields=attachments`): at most `attachments.maxCount`
+  files (default 10), at most `attachments.maxTotalBytes` raw bytes (default and maximum 28,000,000, about 37.3 MB
+  base64, under the 40 MB cap), a filename without path separators or control characters, a content type on
+  `attachments.contentTypes` (default `DEFAULT_ATTACHMENT_CONTENT_TYPES`). New option `attachments` in
+  `mailing({ ... })`.
+- `MailProvider.supportsAttachments`: a provider gets `ProviderMessage.attachments` only when it declares it;
+  otherwise a mail with attachments is refused as `invalid_input` (`cause=provider_without_attachments`). `resend()`
+  sends them as base64 with `content_type`; `fakeMailProvider()` captures them, and its outbox file stores them as
+  base64 that `readMailOutbox` decodes back to bytes.
+- The failure log line adds `attachments=<type>:<bytes>,...` (never filenames or content). `describeAttachments`
+  returns `{ filename, contentType, size }[]`; `formatMailPreview` (`/server`) prints a `previewMail` value with an
+  attachments section, and `softure-mail` previews use it.
+- Queued deliveries carry no bytes: `enqueueDelivery` throws for a payload with a `Uint8Array`, `Buffer` or
+  `ArrayBuffer`; `buildMail` loads attachments from the app's storage by reference.
+- `validateMail(mail, options, limits?)` takes the attachment limits (default: the module defaults).
+- Migrate an app:
+  1. An app that bypasses mailing to send a file (a provider SDK or the user's mailbox API): call `sendMail` (or
+     `deliverOnce`, or `enqueueDelivery` with the file's id in the payload and the bytes loaded in `buildMail`) with
+     `attachments`, and delete the bypass.
+  2. A content type outside the default list: pass `mailing({ attachments: { contentTypes: [...] } })` with the
+     full list the app needs.
+  3. A custom `MailProvider` that should carry attachments: map `message.attachments` and set
+     `supportsAttachments: true`. Nothing to change otherwise.
+
 ## 0.2.3
 
 - `softure-mail test` sends a list-kind test mail without the app database (#573). With `database: null` it skips the

package/README.md

@@ -8,7 +8,7 @@ can be imported into it, and `softure-mail` sends campaigns from a content file.
 
 ## 1. What it provides
 
-- `mailing({ from, replyTo, provider, timeoutMs, ... })` for `softure.config.ts` (section 3).
+- `mailing({ from, senders, replyTo, provider, timeoutMs, ... })` for `softure.config.ts` (section 3).
 - `sendMail(context, mail, options)` in `@softure-ai/mailing/server` and `sendMail(mail, options)` in
   `@softure-ai/mailing/next` (on the registered config). The result is a core `Result`; a failure the
   provider answered with an HTTP status also carries it as `httpStatus`:
@@ -46,8 +46,10 @@ can be imported into it, and `softure-mail` sends campaigns from a content file.
   `importDeliveries` (and `softure-mail import`) seeds it with the app's earlier history.
 - **Deliveries through jobs.** `enqueueDelivery` and `defineDeliveryJobHandler` (`/jobs`) let an app enqueue a
   mail with its own write and have the `@softure-ai/jobs` worker send it, retrying while the provider is down.
+- **Attachments.** `attachments: [{ filename, contentType, content }]` on a mail (an invoice PDF, a report, an
+  export), checked against a count, a total size and a content type allow-list before anything is sent.
 - **Preview and test send.** `previewMail(config, mail)` returns exactly what `sendMail` hands the
-  provider; `softure-mail test` sends a mail to the configured `testAddress` and nowhere else.
+  provider, and `formatMailPreview(message)` prints it for a terminal; `softure-mail test` sends a mail to the configured `testAddress` and nowhere else.
 - **A SQL surface** for the app's own queries: `mailing.recipient_key(address)`,
   `mailing.is_suppressed(address)`, `mailing.was_delivered(scope, address)` and the views
   `mailing.delivery_outcomes` and `mailing.suppressed_recipients` (section 5).
@@ -83,6 +85,12 @@ Rules that hold for every send:
   instead of `mailing({ replyTo })`, e.g. the buyer of a request mailed to the operator:
   `sendMail({ to: operator, replyTo: request.account.email, subject, text })`. Without it the
   configured one is used; the `Reply-To` header stays refused.
+- **Sender per mail, by name.** `sender` names one of `mailing({ senders })`, e.g. operator alerts from
+  `alerts` and client mail from `from`: `sendMail({ to: operator, sender: "alerts", subject, text })`.
+  Without it the mail goes out from `from`. It is never an address, so a request cannot choose the
+  sender; an unknown name is `mailing.invalid_input` (`fields=sender`) and nothing is sent.
+  `deliverOnce` and `enqueueDelivery` carry it as part of the mail (`buildMail` returns it), and
+  `previewMail` shows the resolved `From`.
 - **Text always, HTML optionally.** `text` is required; `html` is a string the app rendered (from a
   template string or React email components rendered to a string: the module does not render).
 - **Headers cannot take over the mail.** `headers` is for headers like `List-Unsubscribe`;
@@ -91,13 +99,52 @@ Rules that hold for every send:
   values and the subject.
 - **Nothing of the mail is logged.** One line per failure:
   `mailing: send failed provider=resend reason=rejected status=422` (with `fields=to,subject` for
-  invalid input). Provider refusal messages are never read: they can echo the address.
+  invalid input, and `attachments=application/pdf:48213,text/csv:512` when the mail has attachments: content
+  type and size only). Provider refusal messages are never read: they can echo the address.
 - **Timeout.** After `timeoutMs` the provider's signal aborts and the send answers `unavailable`,
   even when the provider ignores the signal.
 - **List mail fails closed.** No secret or an unreadable suppression list means nothing is sent.
   A list mail cannot bring its own `List-Unsubscribe` or `List-Unsubscribe-Post`: the module writes
   them (`invalid_input`).
 
+**Attachments.** A mail can carry files, e.g. a received cost invoice forwarded to a bookkeeping service's import
+address, an invoice or monthly report the app generated, or an export the user asked for:
+
+```ts
+import { sendMail } from "@softure-ai/mailing/next";
+
+await sendMail(
+  {
+    to: bookkeeping.importAddress,
+    subject: `Cost invoice ${invoice.number}`,
+    text: "Cost invoice attached.",
+    attachments: [{ filename: `invoice-${invoice.number}.pdf`, contentType: "application/pdf", content: pdfBytes }],
+  },
+  { idempotencyKey: `cost-invoice:${invoice.id}` },
+);
+```
+
+- `content` is a `Uint8Array` (a Node `Buffer` is one), at least one byte. The module sends the bytes as given.
+- Checked before anything leaves the process, else `mailing.invalid_input` with `fields=attachments`: at most
+  `attachments.maxCount` files (default 10); at most `attachments.maxTotalBytes` raw bytes in all (default and
+  maximum 28,000,000: base64 grows them by a third, about 37.3 MB on the wire, under the 40 MB a mail may have at
+  Resend); a filename of 1 to 255 characters without `/`, `\`, control characters, `.` or `..`; a content type
+  (`type/subtype`, parameters allowed) on the allow-list. The default list (`DEFAULT_ATTACHMENT_CONTENT_TYPES`) has
+  PDF, plain text, CSV, calendar, JSON, XML, ZIP, XLSX, DOCX, PNG, JPEG, GIF and WebP; HTML, SVG, scripts and
+  executables are left out. `mailing({ attachments: { contentTypes } })` replaces it with the app's own list.
+- **Only a provider that delivers them gets them.** A provider declares `supportsAttachments: true` (`resend()`
+  and `fakeMailProvider()` do); for any other a mail with attachments is `mailing.invalid_input`
+  (`cause=provider_without_attachments`), so an adapter written before attachments existed never drops a file.
+- **Logs and dry runs.** The failure line names content types and sizes, never filenames (they are the app's text
+  and often name a person or an invoice, like the subject) or bytes. `describeAttachments(attachments)` gives
+  `{ filename, contentType, size }[]` for the app's own records; `previewMail` returns the attachments and
+  `formatMailPreview` lists them as `invoice-42.pdf (application/pdf, 48213 bytes)`.
+- **Queued mail references files.** A delivery through jobs (`enqueueDelivery`) never carries bytes: the job payload
+  holds the app's ids (`{ invoiceId }`), `buildMail` loads the file from the app's storage on every attempt, and
+  `enqueueDelivery` throws for a payload with a `Uint8Array`, `Buffer` or `ArrayBuffer` in it. The app keeps the file
+  (its storage, its retention) until the job is done; it must return the same bytes each attempt, like the body.
+- The delivery ledger stores nothing of the mail, attachments included.
+
 **How a link works.** The link carries `r`, the base64url SHA-256 of the trimmed, lowercased
 address, and `t`, the base64url HMAC-SHA256 of a fixed prefix plus `r` under
 `MAILING_UNSUBSCRIBE_SECRET`. The address never appears in a URL, and the suppression table stores
@@ -194,7 +241,8 @@ await db.transaction(async (tx) => {
   must have no side effects and return the same mail each time: the provider refuses a different body under the
   same idempotency key (`mailing.rejected`). A link with a one-time token must be reproducible per request (derive
   the token from the request's row, or store it encrypted), never minted per attempt. `buildMail` returning `null`
-  ends the job as done with nothing sent (the account is gone).
+  ends the job as done with nothing sent (the account is gone). Attachments are loaded in `buildMail` from the
+  app's storage by an id in the payload; bytes in the payload throw (section 1, Attachments).
 - **The scope is the ledger key and the job's dedup key.** One scope per mail the app means to send once:
   `auth.password-reset:<request id>`, `app.welcome:<user id>`. While a job for it is pending or running, a second
   `enqueueDelivery` returns that job (`isDuplicate: true`). `runAt`, `delaySeconds` and `maxAttempts` pass through to
@@ -454,13 +502,16 @@ address the same way the commands do.
 ### Sender DNS check: `softure-mail dns`
 
 ```bash
-softure-mail dns                                       # the domain of `from` (and replyTo) in the config
+softure-mail dns                                       # every sender domain in the config (and replyTo)
 softure-mail dns --domain mail.example.com --spf-host send.mail.example.com
 softure-mail dns --spf-host send.mail.example.com --resend-return-path \
   --dmarc-policy reject --dmarc-sp reject --dmarc-adkim s --dmarc-aspf s
 ```
 
-It reports each check as `pass`, `warn` or `fail`, exiting 1 on any `fail`:
+Without `--domain` it checks every distinct domain of `from` and `senders`, `from`'s first, one report each; the
+REPLY and INBOUND checks belong to the first. With several domains, each `--spf-host` and `--return-path` counts for
+the domain it sits under (`send.clients.example.net` for `clients.example.net`), and a host under none of them is an
+error. It reports each check as `pass`, `warn` or `fail`, exiting 1 on any `fail`:
 
 - **SPF**: one `v=spf1` record on the domain or each `--spf-host`; `+all` warns. Resend publishes SPF on
   `send.<domain>`.
@@ -513,6 +564,7 @@ mailing({
 | Option | Type | Default | Meaning |
 | --- | --- | --- | --- |
 | `from` | `string` | required | `addr` or `Name <addr>` (no commas, semicolons or quotes in the name). Must be on the domain the provider signs (DKIM); with DMARC `adkim=s` exactly that subdomain. |
+| `senders` | `Record<string, string>` | none | Named extra senders a mail picks with `sender`, e.g. `{ alerts: "App <alerts@example.com>" }`. Names: a letter, then letters, digits, `_` or `-`, at most 32 characters. Each value is checked like `from` and must be on a domain the provider signs. |
 | `replyTo` | `string` | none | One address for replies; may be on another domain (DMARC does not check it). |
 | `provider` | `MailProvider` | required | `resend()`, `fakeMailProvider()` or your own adapter. |
 | `timeoutMs` | `number` | `10000` | 1000 to 60000. |
@@ -526,6 +578,7 @@ mailing({
 | `uncertainClaimMs` | `number` | `82800000` (23 h) | How old a claim may get before it waits for an operator (`uncertain`). More than `staleClaimMs`, at most 30 days; keep it under the provider's idempotency window. |
 | `testAddress` | `string` | none | The only address `softure-mail test` sends to (section 1, Test send). |
 | `kindAliases` | `Record<string, string>` | none | Alias to kind for campaign files and `softure-mail test --kind`, e.g. `{ news: "newsletter" }`. Kebab-case on both sides; an alias never names a kind another alias points at. |
+| `attachments` | `{ maxCount?, maxTotalBytes?, contentTypes? }` | `10`, `28000000`, `DEFAULT_ATTACHMENT_CONTENT_TYPES` | Limits on a mail's attachments: files 1 to 100; raw bytes in all, at most 28,000,000 (about 37.3 MB base64); the allowed content types, replacing the default list (section 1, Attachments). |
 | `routes` | `{ unsubscribe?, oneClick? }` | `/unsubscribe`, `/api/mailing/unsubscribe` | Where you mount the page and the route; links are built on `appOrigin` plus these paths. |
 
 `resend({ apiKey?, endpoint?, fetch? })`: without `apiKey` it reads `RESEND_API_KEY` on every send,
@@ -548,7 +601,8 @@ const provider: MailProvider = {
 ```
 
 A provider receives a validated `ProviderMessage` (`from`, `to`, `replyTo`, `subject`, `text`, `html`,
-`headers`, `idempotencyKey`, nulls for what is absent) and answers `sent` with an id, or `rejected`
+`headers`, `idempotencyKey`, nulls for what is absent; `attachments` only when the mail has some and the provider
+declares `supportsAttachments: true`) and answers `sent` with an id, or `rejected`
 (this mail), `refused` (the account or key), `quota_exceeded` (the account's quota) or `unavailable`
 (try later), each with an optional `httpStatus`. A throw or anything else reads as `unavailable`.
 
@@ -769,7 +823,9 @@ personal data. So the module neither exports nor deletes per user (`privacy: { e
 
 ## 12. Limitations
 
-- One recipient per call; no cc, bcc or attachments.
+- One recipient per call; no cc or bcc.
+- Attachments are sent as regular files: no inline images (`cid:`), no content scanning. Campaigns
+  (`softure-mail campaign`) carry none.
 - `sendMail` does not retry: the caller retries `unavailable` with the same `idempotencyKey` (Resend
   keeps keys for 24 hours), uses `deliverOnce`, which keeps the state between runs, or enqueues it with
   `enqueueDelivery`, which retries it from a job.
@@ -783,7 +839,9 @@ personal data. So the module neither exports nor deletes per user (`privacy: { e
   removed by hand (`getRecipientKey(address)`).
 - Lowercasing the whole address merges `Ada@` and `ada@` (allowed to differ by RFC 5321, never in
   practice); an unsubscribe then covers both.
-- The display name in `from` cannot contain commas, semicolons or quotes (no RFC 5322 quoting).
+- A named sender carries no reply-to of its own: pass `replyTo` on the mail. Campaigns and
+  `softure-mail test` always send from `from`.
+- The display name in `from` and `senders` cannot contain commas, semicolons or quotes (no RFC 5322 quoting).
 - Address checks are structural (one `@`, a dot in the domain, no separators); the provider has the
   last word.
 

package/dist/attachments.d.ts

@@ -0,0 +1,32 @@
+import type { AttachmentSummary, MailAttachment } from "./contract.js";
+/** Files per mail when `attachments.maxCount` is not set. */
+export declare const DEFAULT_MAX_ATTACHMENTS = 10;
+/**
+ * The most raw bytes all attachments of one mail may hold, and the default. Base64 grows them by a third on the
+ * wire: 28,000,000 bytes encode to about 37.3 MB, under the 40 MB a mail may have at Resend and similar providers,
+ * with room for the bodies. `attachments.maxTotalBytes` can only lower it.
+ */
+export declare const MAX_ATTACHMENT_BYTES = 28000000;
+/**
+ * The content types allowed when `attachments.contentTypes` is not set: documents, data exports, images and calendar
+ * invites. HTML, SVG, scripts and executables are left out: a mail client may run or render them.
+ */
+export declare const DEFAULT_ATTACHMENT_CONTENT_TYPES: readonly string[];
+export declare const MAX_ATTACHMENT_FILENAME_LENGTH = 255;
+/** The limits a mail's attachments are checked against (`mailing({ attachments })`, resolved). */
+export interface AttachmentLimits {
+    readonly maxCount: number;
+    readonly maxTotalBytes: number;
+    /** Lowercase `type/subtype` values. */
+    readonly contentTypes: readonly string[];
+}
+export declare const DEFAULT_ATTACHMENT_LIMITS: AttachmentLimits;
+/** A plain filename: 1 to 255 characters, not blank, no `/` or `\`, no control characters, not `.` or `..`. */
+export declare function isAttachmentFilename(value: string): boolean;
+/** A MIME type `type/subtype`, optionally with parameters (`text/csv; charset=utf-8`). */
+export declare function isContentType(value: string): boolean;
+/** The `type/subtype` of a content type, lowercase, without its parameters. */
+export declare function getContentTypeEssence(value: string): string;
+/** Every attachment without its bytes: filename, content type and size. Safe to keep in an app's own records. */
+export declare function describeAttachments(attachments: readonly MailAttachment[]): AttachmentSummary[];
+//# sourceMappingURL=attachments.d.ts.map

package/dist/attachments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachments.d.ts","sourceRoot":"","sources":["../src/attachments.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEvE,6DAA6D;AAC7D,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,WAAa,CAAC;AAE/C;;;GAGG;AACH,eAAO,MAAM,gCAAgC,EAAE,SAAS,MAAM,EAe7D,CAAC;AAEF,eAAO,MAAM,8BAA8B,MAAM,CAAC;AAElD,kGAAkG;AAClG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,uCAAuC;IACvC,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED,eAAO,MAAM,yBAAyB,EAAE,gBAIvC,CAAC;AAKF,+GAA+G;AAC/G,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAU3D;AAWD,0FAA0F;AAC1F,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED,+EAA+E;AAC/E,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,iHAAiH;AACjH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,SAAS,cAAc,EAAE,GAAG,iBAAiB,EAAE,CAE/F"}

package/dist/attachments.js

@@ -0,0 +1,68 @@
+/** Files per mail when `attachments.maxCount` is not set. */
+export const DEFAULT_MAX_ATTACHMENTS = 10;
+/**
+ * The most raw bytes all attachments of one mail may hold, and the default. Base64 grows them by a third on the
+ * wire: 28,000,000 bytes encode to about 37.3 MB, under the 40 MB a mail may have at Resend and similar providers,
+ * with room for the bodies. `attachments.maxTotalBytes` can only lower it.
+ */
+export const MAX_ATTACHMENT_BYTES = 28_000_000;
+/**
+ * The content types allowed when `attachments.contentTypes` is not set: documents, data exports, images and calendar
+ * invites. HTML, SVG, scripts and executables are left out: a mail client may run or render them.
+ */
+export const DEFAULT_ATTACHMENT_CONTENT_TYPES = [
+    "application/pdf",
+    "text/plain",
+    "text/csv",
+    "text/calendar",
+    "application/json",
+    "application/xml",
+    "text/xml",
+    "application/zip",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    "image/png",
+    "image/jpeg",
+    "image/gif",
+    "image/webp",
+];
+export const MAX_ATTACHMENT_FILENAME_LENGTH = 255;
+export const DEFAULT_ATTACHMENT_LIMITS = {
+    maxCount: DEFAULT_MAX_ATTACHMENTS,
+    maxTotalBytes: MAX_ATTACHMENT_BYTES,
+    contentTypes: DEFAULT_ATTACHMENT_CONTENT_TYPES,
+};
+const TOKEN = "[A-Za-z0-9!#$&^_.+-]+";
+const CONTENT_TYPE = new RegExp(`^${TOKEN}/${TOKEN}(\\s*;\\s*${TOKEN}=("[^"\\r\\n]*"|${TOKEN}))*$`);
+/** A plain filename: 1 to 255 characters, not blank, no `/` or `\`, no control characters, not `.` or `..`. */
+export function isAttachmentFilename(value) {
+    return (value.trim() !== "" &&
+        value.length <= MAX_ATTACHMENT_FILENAME_LENGTH &&
+        !value.includes("/") &&
+        !value.includes("\\") &&
+        !hasControlCharacter(value) &&
+        value !== "." &&
+        value !== "..");
+}
+/** A C0 control character or DEL. */
+function hasControlCharacter(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code < 0x20 || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+/** A MIME type `type/subtype`, optionally with parameters (`text/csv; charset=utf-8`). */
+export function isContentType(value) {
+    return CONTENT_TYPE.test(value);
+}
+/** The `type/subtype` of a content type, lowercase, without its parameters. */
+export function getContentTypeEssence(value) {
+    return (value.split(";")[0] ?? "").trim().toLowerCase();
+}
+/** Every attachment without its bytes: filename, content type and size. Safe to keep in an app's own records. */
+export function describeAttachments(attachments) {
+    return attachments.map(({ filename, contentType, content }) => ({ filename, contentType, size: content.byteLength }));
+}
+//# sourceMappingURL=attachments.js.map

package/dist/attachments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachments.js","sourceRoot":"","sources":["../src/attachments.ts"],"names":[],"mappings":"AAIA,6DAA6D;AAC7D,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,CAAC;AAE1C;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,UAAU,CAAC;AAE/C;;;GAGG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAsB;IACjE,iBAAiB;IACjB,YAAY;IACZ,UAAU;IACV,eAAe;IACf,kBAAkB;IAClB,iBAAiB;IACjB,UAAU;IACV,iBAAiB;IACjB,mEAAmE;IACnE,yEAAyE;IACzE,WAAW;IACX,YAAY;IACZ,WAAW;IACX,YAAY;CACb,CAAC;AAEF,MAAM,CAAC,MAAM,8BAA8B,GAAG,GAAG,CAAC;AAUlD,MAAM,CAAC,MAAM,yBAAyB,GAAqB;IACzD,QAAQ,EAAE,uBAAuB;IACjC,aAAa,EAAE,oBAAoB;IACnC,YAAY,EAAE,gCAAgC;CAC/C,CAAC;AAEF,MAAM,KAAK,GAAG,uBAAuB,CAAC;AACtC,MAAM,YAAY,GAAG,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,KAAK,aAAa,KAAK,mBAAmB,KAAK,MAAM,CAAC,CAAC;AAEpG,+GAA+G;AAC/G,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,OAAO,CACL,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE;QACnB,KAAK,CAAC,MAAM,IAAI,8BAA8B;QAC9C,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC;QACpB,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;QACrB,CAAC,mBAAmB,CAAC,KAAK,CAAC;QAC3B,KAAK,KAAK,GAAG;QACb,KAAK,KAAK,IAAI,CACf,CAAC;AACJ,CAAC;AAED,qCAAqC;AACrC,SAAS,mBAAmB,CAAC,KAAa;IACxC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,GAAG,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QACrC,IAAI,IAAI,GAAG,IAAI,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;IAChD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAClC,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,qBAAqB,CAAC,KAAa;IACjD,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AAC1D,CAAC;AAED,iHAAiH;AACjH,MAAM,UAAU,mBAAmB,CAAC,WAAsC;IACxE,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;AACxH,CAAC"}

package/dist/cli/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"AAWA,OAAO,EAAe,KAAK,aAAa,EAA8B,MAAM,kBAAkB,CAAC;AAE/F,OAAO,EAA6C,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAKhG,OAAO,EAAkI,KAAK,YAAY,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAuB,MAAM,kBAAkB,CAAC;AAK3O,OAAO,EAAiF,KAAK,GAAG,EAAE,MAAM,+BAA+B,CAAC;AAExI,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC;AAED,MAAM,WAAW,iBAAiB;IAChC,oGAAoG;IACpG,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC,wGAAwG;IACxG,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,mEAAmE;IACnE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAC5B,iIAAiI;IACjI,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IACjE,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,QAAQ,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC;IACnB,sFAAsF;IACtF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CAC5C;AAED,eAAO,MAAM,OAAO,IAAI,CAAC;AACzB,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,UAAU,IAAI,CAAC;AAE5B,8EAA8E;AAC9E,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,eAAO,MAAM,UAAU,QAiEwD,CAAC;AAmDhF,yGAAyG;AACzG,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAqB5E"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"AAWA,OAAO,EAAe,KAAK,aAAa,EAA8B,MAAM,kBAAkB,CAAC;AAE/F,OAAO,EAA6C,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAKhG,OAAO,EAAkI,KAAK,YAAY,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAuB,MAAM,kBAAkB,CAAC;AAK3O,OAAO,EAAiF,KAAK,GAAG,EAAE,MAAM,+BAA+B,CAAC;AAExI,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC;AAED,MAAM,WAAW,iBAAiB;IAChC,oGAAoG;IACpG,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC,wGAAwG;IACxG,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,mEAAmE;IACnE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAC5B,iIAAiI;IACjI,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IACjE,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,QAAQ,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC;IACnB,sFAAsF;IACtF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CAC5C;AAED,eAAO,MAAM,OAAO,IAAI,CAAC;AACzB,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,UAAU,IAAI,CAAC;AAE5B,8EAA8E;AAC9E,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,eAAO,MAAM,UAAU,QAoEwD,CAAC;AAmDhF,yGAAyG;AACzG,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAqB5E"}

package/dist/cli/run.js

@@ -17,7 +17,7 @@ import { getCampaignProblems, parseCampaignFile, parseRecipientList } from "../s
 import { listConfiguredCampaignRecipients, planCampaign, sendCampaign } from "../server/campaigns.js";
 import { checkSenderDns, getSenderDomain, resendReturnPath } from "../server/dns.js";
 import { checkImportedDeliveries, importDeliveries } from "../server/import-deliveries.js";
-import { maskAddress, redactUnsubscribeSignatures } from "../server/operator-output.js";
+import { formatMailPreview, maskAddress } from "../server/operator-output.js";
 import { getMailingOptions, resolveMailKind } from "../server/options.js";
 import { previewMail, sendMail, sendMailUnchecked } from "../server/send-mail.js";
 import { MIN_UNSUBSCRIBE_SECRET_LENGTH, readUnsubscribeSecrets, UNSUBSCRIBE_SECRET_ENV } from "../server/unsubscribe-link.js";
@@ -68,11 +68,13 @@ import    Writes deliveries the app made before it adopted the module into the l
           stops the import before anything is written.
   --dry-run            check the file and change nothing
 
-dns       Checks SPF, DKIM and DMARC for the sender domain (default: the domain of "from").
+dns       Checks SPF, DKIM and DMARC for every sender domain (default: the domains of "from"
+          and "senders"; the reply-to and inbound checks go with the domain of "from").
   --domain <domain>       check this domain instead
   --dkim-selector <name>  DKIM selector to look up (default resend; repeatable)
   --spf-host <host>       where SPF is published (default the domain; repeatable;
-                          Resend publishes it on send.<domain>)
+                          Resend publishes it on send.<domain>); with several sender
+                          domains, a host counts for the domain it sits under
   --dmarc-policy <p>      require at least this DMARC policy (quarantine or reject)
                           and pct=100; a weaker record fails
   --dmarc-sp <p>          require at least this subdomain policy (sp, else p)
@@ -80,7 +82,8 @@ dns       Checks SPF, DKIM and DMARC for the sender domain (default: the domain
   --dmarc-aspf <a>        require this SPF alignment (r or s; absent counts as r)
   --reply-to <address>    check that this address's domain accepts mail (MX, one SPF)
                           (default: replyTo of the config, when --domain is not given)
-  --return-path <host>    a return-path host that must be a CNAME or have MX (repeatable)
+  --return-path <host>    a return-path host that must be a CNAME or have MX (repeatable;
+                          with several sender domains, for the domain it sits under)
   --resend-return-path    check Resend's send.<domain> and rsend.<domain> CNAMEs
   --inbound cloudflare    check that Cloudflare Email Routing receives the reply-to domain's
                           mail (its MX and one SPF record that includes it)
@@ -282,25 +285,76 @@ function parseDmarcExpectation(values) {
     return Object.keys(expectation).length === 0 ? undefined : expectation;
 }
 async function runDns(command, options, output) {
-    let domain = command.domain;
-    let replyTo = command.replyTo;
-    if (domain === undefined) {
-        if (options.config === undefined) {
-            output.error("softure-mail dns: pass --domain <domain>, or run it with the app's config to check the sender's domain");
-            return EXIT_FAILED;
-        }
-        const mailing = getMailingOptions(options.config);
-        domain = getSenderDomain(mailing.from);
-        replyTo ??= mailing.replyTo;
+    const targets = getDnsTargets(command, options.config);
+    if (typeof targets === "string") {
+        output.error(`softure-mail dns: ${targets}`);
+        return EXIT_FAILED;
     }
-    const returnPath = [...(command.resendReturnPath ? resendReturnPath(domain) : []), ...command.returnPathHosts.map((host) => ({ host }))];
+    let failed = 0;
+    for (const target of targets)
+        failed += await checkDnsTarget(command, target, options, output);
+    return failed === 0 ? EXIT_OK : EXIT_FAILED;
+}
+/**
+ * The domains to check: `--domain` alone, else the distinct domains of `from` and `senders`, `from`'s first. With
+ * several, a host option goes to the domain it sits under (the longest that matches); one under none is an error.
+ */
+function getDnsTargets(command, config) {
+    const single = (domain, replyTo) => [
+        { domain, spfHosts: command.spfHosts, returnPathHosts: command.returnPathHosts, replyTo, inbound: command.inbound },
+    ];
+    if (command.domain !== undefined)
+        return single(command.domain, command.replyTo);
+    if (config === undefined)
+        return "pass --domain <domain>, or run it with the app's config to check the sender's domain";
+    const mailing = getMailingOptions(config);
+    const domains = [...new Set([mailing.from, ...Object.values(mailing.senders ?? {})].map((sender) => getSenderDomain(sender).toLowerCase()))];
+    const replyTo = command.replyTo ?? mailing.replyTo;
+    const [first = ""] = domains;
+    if (domains.length === 1)
+        return single(first, replyTo);
+    const spfHosts = assignHostsToDomains("--spf-host", command.spfHosts ?? [], domains);
+    if (typeof spfHosts === "string")
+        return spfHosts;
+    const returnPathHosts = assignHostsToDomains("--return-path", command.returnPathHosts, domains);
+    if (typeof returnPathHosts === "string")
+        return returnPathHosts;
+    return domains.map((domain, index) => ({
+        domain,
+        spfHosts: spfHosts.get(domain),
+        returnPathHosts: returnPathHosts.get(domain) ?? [],
+        replyTo: index === 0 ? replyTo : undefined,
+        inbound: index === 0 ? command.inbound : undefined,
+    }));
+}
+/** The hosts of `option` by the domain each sits under, or the error for one under none of `domains`. */
+function assignHostsToDomains(option, hosts, domains) {
+    const byDomain = new Map();
+    for (const host of hosts) {
+        const domain = findHostDomain(host, domains);
+        if (domain === null)
+            return `${option} ${host} sits under none of the sender domains (${domains.join(", ")})`;
+        byDomain.set(domain, [...(byDomain.get(domain) ?? []), host]);
+    }
+    return byDomain;
+}
+/** The longest of `domains` that `host` is or sits under, or `null`. */
+function findHostDomain(host, domains) {
+    const name = host.trim().toLowerCase().replace(/\.$/, "");
+    const matches = domains.filter((domain) => name === domain || name.endsWith(`.${domain}`));
+    return matches.reduce((longest, domain) => (longest === null || domain.length > longest.length ? domain : longest), null);
+}
+/** Checks one domain and prints its report; returns how many checks failed. */
+async function checkDnsTarget(command, target, options, output) {
+    const { domain, replyTo } = target;
+    const returnPath = [...(command.resendReturnPath ? resendReturnPath(domain) : []), ...target.returnPathHosts.map((host) => ({ host }))];
     const report = await checkSenderDns(domain, {
         ...(command.dkimSelectors === undefined ? {} : { dkimSelectors: command.dkimSelectors }),
-        ...(command.spfHosts === undefined ? {} : { spfHosts: command.spfHosts }),
+        ...(target.spfHosts === undefined ? {} : { spfHosts: target.spfHosts }),
         ...(command.expectDmarc === undefined ? {} : { expectDmarc: command.expectDmarc }),
         ...(replyTo === undefined ? {} : { replyTo }),
         returnPath,
-        ...(command.inbound === undefined ? {} : { inbound: command.inbound }),
+        ...(target.inbound === undefined ? {} : { inbound: target.inbound }),
         ...(options.resolveTxt === undefined ? {} : { resolveTxt: options.resolveTxt }),
         ...(options.resolveMx === undefined ? {} : { resolveMx: options.resolveMx }),
         ...(options.resolveCname === undefined ? {} : { resolveCname: options.resolveCname }),
@@ -326,9 +380,10 @@ async function runDns(command, options, output) {
     const failedReply = countFailed(reply);
     const failedPaths = countFailed(paths);
     const failedInbound = countFailed(inbound);
-    if (failedAuthentication + failedReply + failedPaths + failedInbound === 0) {
+    const failed = failedAuthentication + failedReply + failedPaths + failedInbound;
+    if (failed === 0) {
         output.log("receivers can authenticate mail from this domain");
-        return EXIT_OK;
+        return 0;
     }
     if (failedAuthentication > 0)
         output.log(`${String(failedAuthentication)} check(s) failed: list mail from this domain will land in spam or be refused`);
@@ -338,7 +393,7 @@ async function runDns(command, options, output) {
         output.log(`${String(failedPaths)} return-path host(s) failed: the provider cannot use them for bounces`);
     if (failedInbound > 0)
         output.log("the inbound service does not receive this domain's mail: replies will not reach it");
-    return EXIT_FAILED;
+    return failed;
 }
 async function runCampaign(command, options, output) {
     const cwd = options.cwd ?? process.cwd();
@@ -578,18 +633,7 @@ async function reportPlan(ctx, loaded, run, output) {
 const PREVIEW_ADDRESS = "recipient@example.com";
 /** The mail as the provider would get it, one output line per line, the address masked and signatures redacted. */
 function printPreview(message, output) {
-    const headers = [
-        `From: ${message.from}`,
-        `To: ${maskAddress(message.to)}`,
-        ...(message.replyTo === null ? [] : [`Reply-To: ${maskAddress(message.replyTo)}`]),
-        `Subject: ${message.subject}`,
-        ...Object.entries(message.headers).map(([name, value]) => `${name}: ${value}`),
-    ];
-    const sections = [`--- preview (addresses masked, link signatures redacted) ---`, ...headers, "", "--- text ---", message.text];
-    if (message.html !== null)
-        sections.push("--- html ---", message.html);
-    sections.push("--- end of preview ---");
-    for (const line of redactUnsubscribeSignatures(sections.join("\n")).split("\n"))
+    for (const line of formatMailPreview(message))
         output.log(line);
 }
 /** The fixed mail of `softure-mail test` without a content file. Operator text: the test address is the operator's. */