@curlew/smtp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

package/README.md

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+# @curlew/smtp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Send one message, with attachments, over SMTP. A thin, checked layer on
+[nodemailer](https://nodemailer.com) (pinned exactly): no `gi://`, runs on GJS and on Node.
+
+**This is a library capability, not a tool.** curlew's index and its MCP server stay read-only
+and fail-closed; nothing in `app/src/frontends/mcp` sends mail, and nothing here registers one.
+The caller sends, and only with the human's explicit consent for that message.
+
+## API
+
+```ts
+import { buildMessage, sendMessage, verifyAccount, SmtpError } from '@curlew/smtp';
+
+const account: SmtpAccount = {
+  host: 'smtp.example.invalid',
+  port: 587,
+  security: 'starttls', // 'tls' | 'starttls' | 'none' (127.0.0.1 and localhost only)
+  username: 'user@example.invalid',
+  auth: { kind: 'password', password } /* or { kind: 'oauth2', accessToken } */,
+  tls: { ca: pem }, // optional: trust a private CA; rejectUnauthorized: false switches checking off
+};
+
+await verifyAccount(account); // connects and logs in; sends no MAIL FROM
+const raw = await buildMessage(message); // RFC 5322 bytes, no network
+const sent = await sendMessage(account, message); // { messageId, accepted, rejected, response }
+```
+
+`OutgoingMessage` is `{ from, to[], cc?[], subject, text, html?, attachments?, messageId? }`;
+an attachment is `{ filename, content: Uint8Array, contentType? }`. Without a `messageId` one is
+generated on the domain of `from`.
+
+- Addresses are plain `local@host`. No display names, no groups, no further validation.
+- A line break or other control character in the subject, an address, a filename, a content
+  type or the Message-ID is refused, not stripped (header injection).
+- `sendMessage` returns the recipients the server refused while taking others in `rejected`;
+  when it takes none it throws. `MAIL FROM` is sent by `sendMessage` only.
+- Attachments are bytes. File and URL access are off, so a message can never name a path.
+
+## Errors
+
+Every failure is an `SmtpError` with a `code`: `auth`, `tls`, `connect`, `rejected` or `config`
+(nothing was sent), and the numeric `responseCode` of a server refusal. The message is fixed text
+plus the server's reply with the account's secrets cut out, and the library error is not kept.
+
+## What it does not do
+
+- No MCP tool, no CLI command: sending is not exposed to an agent.
+- No secret in a log, an error text or a result. Credentials are parameters of the call; the
+  package reads no file, no environment, no store, and turns the library's loggers off.
+- No `security: 'none'` beyond the loopback, because that sends the password in the clear.
+
+## Tests
+
+`app/tests/unit/smtp/`, on GJS and Node: message building and validation, errors without
+secrets, and a plaintext dummy server on 127.0.0.1 (no TLS) that records what the client sent:
+`AUTH PLAIN` / `XOAUTH2` arrived, the attachments are the MIME parts, `verifyAccount` sent no
+`MAIL FROM`.
+
+**TLS and STARTTLS are not tested, and have not been run against a real server here.** On GJS they
+need gjsify#2071 (peer verification after the handshake, the socket under a TLS connection),
+which is not released at 0.55.0. Three cases in `send.test.ts` are marked skipped with that
+reference; enable them with the release that carries it. Nothing in this package works around it.

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@curlew/smtp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "license": "LGPL-3.0-or-later",
+  "type": "module",
+  "description": "Sending one message with attachments over SMTP (nodemailer): message building, account validation, verify and send. A library capability only — no MCP tool, no credentials in logs, errors or DTOs. No gi://.",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "check": "tsc --noEmit --project tsconfig.json"
+  },
+  "files": [
+    "src"
+  ],
+  "dependencies": {
+    "nodemailer": "10.0.15"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JumpLink/curlew.git",
+    "directory": "packages/smtp"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/errors.ts

@@ -0,0 +1,35 @@
+/**
+ * SMTP errors.
+ *
+ * The message never carries a credential: it is built from fixed text and, for a server refusal,
+ * the numeric reply code. Nothing of the underlying library error is kept (no `cause`), because
+ * its fields are not ours to vouch for.
+ *
+ * Note: no TypeScript parameter properties — Node's --experimental-strip-types rejects them.
+ */
+
+/** What went wrong, coarse enough to branch on. */
+export type SmtpErrorCode =
+  /** The server refused the login, or no usable credential was given. */
+  | 'auth'
+  /** The TLS handshake or the STARTTLS upgrade failed (certificate included). */
+  | 'tls'
+  /** No connection, a dropped one, a timeout, or a reply that is not SMTP. */
+  | 'connect'
+  /** The server refused the sender, a recipient, or the message. */
+  | 'rejected'
+  /** The account or message is invalid; nothing was sent over the network. */
+  | 'config';
+
+export class SmtpError extends Error {
+  readonly name = 'SmtpError';
+  readonly code: SmtpErrorCode;
+  /** Numeric SMTP reply code of a server refusal, when there was one. */
+  readonly responseCode?: number;
+
+  constructor(code: SmtpErrorCode, message: string, responseCode?: number) {
+    super(message);
+    this.code = code;
+    this.responseCode = responseCode;
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { SmtpError } from './errors.ts';
+export type { SmtpErrorCode } from './errors.ts';
+export { buildMessage } from './message.ts';
+export { sendMessage, verifyAccount } from './transport.ts';
+export type { OutgoingAttachment, OutgoingMessage, SendResult, SmtpAccount } from './types.ts';
+export { validateAccount, validateMessage } from './validate.ts';

package/src/message.ts

@@ -0,0 +1,51 @@
+import MailComposer from 'nodemailer/lib/mail-composer';
+import type { MailComposerOptions } from 'nodemailer/lib/mail-composer';
+
+import type { OutgoingMessage } from './types.ts';
+import { validateMessage } from './validate.ts';
+
+function randomId(): string {
+  const bytes = new Uint8Array(16);
+  globalThis.crypto.getRandomValues(bytes);
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+
+/** The message's own id, or a fresh `<random@domain-of-from>`. Validates the message first. */
+export function resolveMessageId(message: OutgoingMessage): string {
+  validateMessage(message);
+  if (message.messageId) return message.messageId;
+  return `<${randomId()}@${message.from.slice(message.from.lastIndexOf('@') + 1)}>`;
+}
+
+/**
+ * What goes to nodemailer: file and URL access are off, so no attachment can name a path or a
+ * URL — content is bytes the caller handed over, nothing else.
+ */
+export function composerOptions(message: OutgoingMessage, messageId: string): MailComposerOptions {
+  return {
+    from: message.from,
+    to: message.to,
+    cc: message.cc,
+    subject: message.subject,
+    text: message.text,
+    html: message.html,
+    messageId,
+    attachments: (message.attachments ?? []).map((attachment) => ({
+      filename: attachment.filename,
+      content: Buffer.from(attachment.content),
+      contentType: attachment.contentType,
+    })),
+    disableFileAccess: true,
+    disableUrlAccess: true,
+  };
+}
+
+/**
+ * The RFC 5322 message as bytes, without any network: for a preview, a log of what WOULD go out,
+ * or a test. An invalid message throws a `config` SmtpError.
+ */
+export async function buildMessage(message: OutgoingMessage): Promise<Uint8Array> {
+  const messageId = resolveMessageId(message);
+  const raw = await new MailComposer(composerOptions(message, messageId)).compile().build();
+  return new Uint8Array(raw);
+}

package/src/transport.ts

@@ -0,0 +1,126 @@
+import { createTransport } from 'nodemailer';
+import type { NodemailerError } from 'nodemailer/lib/errors';
+import type SMTPTransport from 'nodemailer/lib/smtp-transport';
+
+import { SmtpError } from './errors.ts';
+import type { SmtpErrorCode } from './errors.ts';
+import { composerOptions, resolveMessageId } from './message.ts';
+import type { OutgoingMessage, SendResult, SmtpAccount } from './types.ts';
+import { validateAccount } from './validate.ts';
+
+/** A dead server must end as an error, not as a hang. */
+const CONNECTION_TIMEOUT_MS = 15_000;
+const SOCKET_TIMEOUT_MS = 60_000;
+
+/** Longest server reply text that goes into an error message. */
+const MAX_REPLY_LENGTH = 200;
+
+const BY_LIBRARY_CODE: Record<string, SmtpErrorCode> = {
+  EAUTH: 'auth',
+  ENOAUTH: 'auth',
+  EOAUTH2: 'auth',
+  ETLS: 'tls',
+  EREQUIRETLS: 'tls',
+  EENVELOPE: 'rejected',
+  EMESSAGE: 'rejected',
+  EMAXRECIPIENTS: 'rejected',
+  ECONFIG: 'config',
+};
+
+const SUMMARY: Record<SmtpErrorCode, string> = {
+  auth: 'SMTP login failed',
+  tls: 'SMTP TLS handshake failed',
+  connect: 'SMTP connection failed',
+  rejected: 'SMTP server rejected the message',
+  config: 'SMTP configuration is invalid',
+};
+
+function secretsOf(account: SmtpAccount): string[] {
+  return account.auth.kind === 'password' ? [account.auth.password] : [account.auth.accessToken];
+}
+
+/** The reply text with every form of a secret removed, flattened to one bounded line. */
+function scrub(text: string, secrets: string[]): string {
+  let out = text;
+  for (const secret of secrets) {
+    for (const form of [secret, btoa(secret)]) out = out.split(form).join('[redacted]');
+  }
+  return out.replace(/[\u0000-\u001f\u007f-\u009f]+/g, ' ').trim().slice(0, MAX_REPLY_LENGTH);
+}
+
+/**
+ * What the caller sees of a library error: a code, fixed text, the numeric reply code, and the
+ * server's reply text with the account's secrets cut out. The original error is dropped.
+ */
+function toSmtpError(err: unknown, account: SmtpAccount): SmtpError {
+  const failure = (err ?? {}) as NodemailerError;
+  const code = BY_LIBRARY_CODE[failure.code ?? ''] ?? (failure.responseCode === 535 ? 'auth' : 'connect');
+  const reply = typeof failure.response === 'string' ? scrub(failure.response, secretsOf(account)) : '';
+  const message = reply ? `${SUMMARY[code]}: ${reply}` : SUMMARY[code];
+  return new SmtpError(code, message, failure.responseCode);
+}
+
+function transportFor(account: SmtpAccount) {
+  const options: SMTPTransport.Options = {
+    host: account.host,
+    port: account.port,
+    secure: account.security === 'tls',
+    requireTLS: account.security === 'starttls',
+    ignoreTLS: account.security === 'none',
+    auth:
+      account.auth.kind === 'password'
+        ? { user: account.username, pass: account.auth.password }
+        : { type: 'OAuth2', user: account.username, accessToken: account.auth.accessToken },
+    connectionTimeout: CONNECTION_TIMEOUT_MS,
+    greetingTimeout: CONNECTION_TIMEOUT_MS,
+    socketTimeout: SOCKET_TIMEOUT_MS,
+    // The libraries' loggers print whole SMTP dialogues, AUTH lines included.
+    logger: false,
+    debug: false,
+  };
+  if (account.tls) {
+    options.tls = {};
+    if (account.tls.ca !== undefined) options.tls.ca = account.tls.ca;
+    if (account.tls.rejectUnauthorized !== undefined) {
+      options.tls.rejectUnauthorized = account.tls.rejectUnauthorized;
+    }
+  }
+  return createTransport(options);
+}
+
+/**
+ * Connects and logs in, then hangs up: no MAIL FROM, nothing is sent. Resolves when the server
+ * accepted the credentials; otherwise throws an SmtpError.
+ */
+export async function verifyAccount(account: SmtpAccount): Promise<void> {
+  validateAccount(account);
+  const transport = transportFor(account);
+  try {
+    await transport.verify();
+  } catch (err) {
+    throw toSmtpError(err, account);
+  } finally {
+    transport.close();
+  }
+}
+
+/**
+ * Sends one message. The caller decides whether to; this never asks anyone. `rejected` lists the
+ * recipients the server refused while taking the rest — when it took none, that is an
+ * SmtpError('rejected').
+ */
+export async function sendMessage(account: SmtpAccount, message: OutgoingMessage): Promise<SendResult> {
+  validateAccount(account);
+  const messageId = resolveMessageId(message);
+  const transport = transportFor(account);
+  try {
+    const info = await transport.sendMail(composerOptions(message, messageId));
+    const accepted = info.accepted.map(String);
+    if (accepted.length === 0) throw new SmtpError('rejected', SUMMARY.rejected);
+    return { messageId, accepted, rejected: info.rejected.map(String), response: scrub(info.response, secretsOf(account)) };
+  } catch (err) {
+    throw err instanceof SmtpError ? err : toSmtpError(err, account);
+  } finally {
+    transport.close();
+  }
+}

package/src/types.ts

@@ -0,0 +1,43 @@
+/** Where and how to reach an SMTP server. Credentials are parameters, never read from anywhere. */
+export interface SmtpAccount {
+  host: string;
+  port: number;
+  /** `tls`: TLS from the first byte. `starttls`: upgrade is required. `none`: loopback only. */
+  security: 'tls' | 'starttls' | 'none';
+  /** Required with either `auth` kind; it is the login name. */
+  username: string;
+  auth: { kind: 'password'; password: string } | { kind: 'oauth2'; accessToken: string };
+  tls?: {
+    /** PEM of the certificate authority to trust, e.g. a self-signed server. */
+    ca?: string;
+    /** `false` switches the certificate check off. Do not. */
+    rejectUnauthorized?: boolean;
+  };
+}
+
+export interface OutgoingAttachment {
+  filename: string;
+  content: Uint8Array;
+  contentType?: string;
+}
+
+/** Addresses are plain `local@host`: no display names, no groups. */
+export interface OutgoingMessage {
+  from: string;
+  to: string[];
+  cc?: string[];
+  subject: string;
+  text: string;
+  html?: string;
+  attachments?: OutgoingAttachment[];
+  /** `<id@host>`. Generated from the domain of `from` when absent. */
+  messageId?: string;
+}
+
+export interface SendResult {
+  messageId: string;
+  accepted: string[];
+  rejected: string[];
+  /** The server's final reply to the message. */
+  response: string;
+}

package/src/validate.ts

@@ -0,0 +1,96 @@
+import { SmtpError } from './errors.ts';
+import type { OutgoingMessage, SmtpAccount } from './types.ts';
+
+/** `none` sends the password in the clear, so it is for a server on this machine only. */
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost']);
+
+/** CR, LF, NUL and the rest of C0/C1: any of them in a header value is an injection attempt. */
+const CONTROL = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/;
+
+/** Deliberately simple: one `@`, no whitespace, no quoting, no display name. */
+const ADDRESS = /^[^\s@<>()[\]\\,;:"]+@[^\s@<>()[\]\\,;:"]+$/;
+
+const MESSAGE_ID = /^<[^\s<>@]+@[^\s<>@]+>$/;
+
+function config(message: string): SmtpError {
+  return new SmtpError('config', message);
+}
+
+function nonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0;
+}
+
+/** Throws a `config` error for anything that must not reach the network. */
+export function validateAccount(account: SmtpAccount): void {
+  if (!account || typeof account !== 'object') throw config('SMTP account is missing');
+  const { host, port, security, username, auth, tls } = account;
+
+  if (!nonEmptyString(host) || /\s/.test(host) || CONTROL.test(host)) throw config('SMTP host is missing or invalid');
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw config('SMTP port must be 1-65535');
+  if (security !== 'tls' && security !== 'starttls' && security !== 'none') {
+    throw config("SMTP security must be 'tls', 'starttls' or 'none'");
+  }
+  if (security === 'none' && !LOOPBACK_HOSTS.has(host)) {
+    throw config("security 'none' is allowed for 127.0.0.1 and localhost only");
+  }
+  if (!nonEmptyString(username) || CONTROL.test(username)) throw config('SMTP username is missing or invalid');
+
+  const credential = auth as Partial<{ kind: string; password: string; accessToken: string }> | undefined;
+  if (credential?.kind === 'password') {
+    if (!nonEmptyString(credential.password)) throw config('SMTP password is missing');
+  } else if (credential?.kind === 'oauth2') {
+    if (!nonEmptyString(credential.accessToken)) throw config('SMTP access token is missing');
+  } else {
+    throw config("SMTP auth must be of kind 'password' or 'oauth2'");
+  }
+
+  if (tls !== undefined) {
+    if (tls === null || typeof tls !== 'object') throw config('SMTP tls must be an object');
+    if (tls.ca !== undefined && !nonEmptyString(tls.ca)) throw config('SMTP tls.ca must be a PEM string');
+    if (tls.rejectUnauthorized !== undefined && typeof tls.rejectUnauthorized !== 'boolean') {
+      throw config('SMTP tls.rejectUnauthorized must be a boolean');
+    }
+  }
+}
+
+function validateAddress(address: unknown, what: string): void {
+  if (!nonEmptyString(address) || CONTROL.test(address) || !ADDRESS.test(address)) {
+    throw config(`${what} is not a plain address (local@host)`);
+  }
+}
+
+/** Throws a `config` error. Header values are checked for line breaks, not rewritten. */
+export function validateMessage(message: OutgoingMessage): void {
+  if (!message || typeof message !== 'object') throw config('message is missing');
+
+  validateAddress(message.from, 'from');
+  if (!Array.isArray(message.to) || message.to.length === 0) throw config('to needs at least one recipient');
+  for (const address of message.to) validateAddress(address, 'to');
+  if (message.cc !== undefined) {
+    if (!Array.isArray(message.cc)) throw config('cc must be a list');
+    for (const address of message.cc) validateAddress(address, 'cc');
+  }
+
+  if (typeof message.subject !== 'string' || CONTROL.test(message.subject)) {
+    throw config('subject is missing or contains a line break or control character');
+  }
+  if (typeof message.text !== 'string') throw config('text is missing');
+  if (message.html !== undefined && typeof message.html !== 'string') throw config('html must be a string');
+
+  if (message.messageId !== undefined && !MESSAGE_ID.test(message.messageId)) {
+    throw config('messageId must look like <id@host>');
+  }
+
+  for (const attachment of message.attachments ?? []) {
+    if (!nonEmptyString(attachment?.filename) || CONTROL.test(attachment.filename)) {
+      throw config('attachment filename is missing or contains a control character');
+    }
+    if (!(attachment.content instanceof Uint8Array)) throw config('attachment content must be a Uint8Array');
+    if (
+      attachment.contentType !== undefined &&
+      (!nonEmptyString(attachment.contentType) || CONTROL.test(attachment.contentType))
+    ) {
+      throw config('attachment contentType is invalid');
+    }
+  }
+}