@dbx-tools/email 0.3.28 → 0.3.30

package/src/tool.ts

@@ -9,18 +9,41 @@
  * `getExecutionContext()` returns the OBO user whose local-part seeds
  * the address (see {@link deriveSenderAddress}).
  *
+ * The dispatch itself goes through the executor the plugin installs on the
+ * shared runtime, so a send from this tool picks up the same retry / timeout /
+ * telemetry chain as one from the AppKit tool. In a Mastra app with no AppKit
+ * plugin registered the send still runs, just without interceptors.
+ *
  * @module
  */
 
 import { getExecutionContext } from "@databricks/appkit";
 import { log, string } from "@dbx-tools/shared-core";
-import { email, type EmailMessage } from "@dbx-tools/shared-email";
+import { email } from "@dbx-tools/shared-email";
 import { createTool } from "@mastra/core/tools";
 import { resolveSenderAddress } from "./sender";
 import { getEmailRuntime, sendEmail } from "./transport";
 
 const logger = log.logger("email/tool/send-email");
 
+/**
+ * The model-facing description of the send capability, shared by the Mastra
+ * {@link emailTool} and the AppKit `email.send` tool so both agents get the
+ * same guidance about approval, scope, and body formatting.
+ */
+export const SEND_EMAIL_DESCRIPTION = string.toDescription(`
+  Send an email on the user's behalf. Pass one or more recipient
+  addresses (with optional cc / bcc and file attachments), a subject,
+  and a body; the user is prompted to approve the send before it goes
+  out (this tool is approval-gated). Use it only when the user
+  explicitly asks to send / forward / share something via email -
+  never autonomously. Keep subjects short and bodies self-contained:
+  the recipient has none of the chat context. Write the body in
+  GitHub-Flavored Markdown - headings, lists, and real Markdown
+  tables - not ASCII art (no "=====" dividers or space/pipe-drawn
+  tables); it is rendered to HTML before sending.
+`);
+
 /** Options accepted by {@link emailTool}. */
 export interface EmailToolOptions {
   /**
@@ -50,28 +73,17 @@ export interface EmailToolOptions {
 export function emailTool(opts: EmailToolOptions = {}) {
   return createTool({
     id: opts.id ?? "send_email",
-    description: string.toDescription(`
-      Send an email on the user's behalf. Pass one or more recipient
-      addresses (with optional cc / bcc and file attachments), a subject,
-      and a body; the user is prompted to approve the send before it goes
-      out (this tool is approval-gated). Use it only when the user
-      explicitly asks to send / forward / share something via email -
-      never autonomously. Keep subjects short and bodies self-contained:
-      the recipient has none of the chat context. Write the body in
-      GitHub-Flavored Markdown - headings, lists, and real Markdown
-      tables - not ASCII art (no "=====" dividers or space/pipe-drawn
-      tables); it is rendered to HTML before sending.
-    `),
+    description: SEND_EMAIL_DESCRIPTION,
     inputSchema: email.emailMessageSchema,
     outputSchema: email.emailResultSchema,
     requireApproval: true,
-    execute: async (input) => {
-      const message = input as EmailMessage;
+    execute: async (input, context) => {
+      const message = email.emailMessageSchema.parse(input);
       const { config } = getEmailRuntime();
       const ctx = getExecutionContext();
       const userEmail = "isUserContext" in ctx ? ctx.userEmail : undefined;
       const from = resolveSenderAddress(config, userEmail);
-      const result = await sendEmail(message, from);
+      const result = await sendEmail(message, from, context?.abortSignal);
       logger.info("sent", {
         to: result.recipient,
         from: result.from,

package/src/transport.ts

@@ -8,37 +8,117 @@
  * The first caller (normally the plugin at setup) primes it with the
  * plugin's config; later callers reuse it.
  *
+ * The runtime also carries the {@link EmailExecutor} every outbound send runs
+ * through. The plugin installs its own `execute()` there at setup, which is
+ * how the Mastra tool - a plain function with no plugin instance in scope -
+ * still gets AppKit's retry / timeout / telemetry chain. Without a registered
+ * plugin (a direct call from a script or a test) the send still runs, just
+ * without interceptors.
+ *
+ * Every entry point takes an optional {@link AbortSignal} so the plugin's
+ * `execute()` timeout and a client disconnect both stop the caller waiting
+ * on SMTP.
+ *
  * @module
  */
 
+import {
+  AppKitError,
+  ConfigurationError,
+  ExecutionError,
+  ValidationError,
+  type ExecutionResult,
+} from "@databricks/appkit";
+import { async, error, log } from "@dbx-tools/shared-core";
 import type { EmailAttachment, EmailMessage, EmailResult } from "@dbx-tools/shared-email";
 import nodemailer, { type SendMailOptions, type Transporter } from "nodemailer";
 import { resolveEmailConfig, type EmailPluginConfig, type ResolvedEmailConfig } from "./config";
+import {
+  EMAIL_SEND_SETTINGS,
+  MAX_ATTACHMENT_BYTES,
+  MAX_ATTACHMENT_COUNT,
+  MAX_ATTACHMENTS_TOTAL_BYTES,
+  MAX_BODY_CHARS,
+  type EmailExecutionSettings,
+} from "./defaults";
 import { renderEmailHtml } from "./email-html";
 import { writeOutboxEmail } from "./outbox";
 import { assertSenderAllowed } from "./sender";
 
-/** The shared dispatcher and the config it was built from. */
+const logger = log.logger("email/transport");
+
+/**
+ * Runs one outbound send through AppKit's interceptor chain. Matches
+ * `Plugin.execute()`, which never throws: a failure comes back as
+ * `{ ok: false }`.
+ */
+export type EmailExecutor = <T>(
+  fn: (signal?: AbortSignal) => Promise<T>,
+  settings: EmailExecutionSettings,
+) => Promise<ExecutionResult<T>>;
+
+/** The shared dispatcher, its resolved config, and the send executor. */
 export interface EmailRuntime {
   /** Present only in SMTP mode. */
   transporter?: Transporter;
   config: ResolvedEmailConfig;
+  execute: EmailExecutor;
+}
+
+/**
+ * Combine two optional cancellation sources into one signal. Returns the
+ * single signal when only one is present so the common path allocates
+ * nothing.
+ */
+function mergeSignals(a?: AbortSignal, b?: AbortSignal): AbortSignal | undefined {
+  if (!a) return b;
+  if (!b) return a;
+  const controller = new AbortController();
+  async.tieAbortSignal(controller, a);
+  async.tieAbortSignal(controller, b);
+  return controller.signal;
 }
 
+/**
+ * Executor used until (or unless) the plugin installs its own: run the send
+ * directly, mapping a throw onto the same {@link ExecutionResult} shape so
+ * call sites branch on `ok` either way.
+ */
+const directExecute: EmailExecutor = async (fn) => {
+  try {
+    return { ok: true, data: await fn() };
+  } catch (err) {
+    return {
+      ok: false,
+      status: err instanceof AppKitError ? err.statusCode : 500,
+      message: error.errorMessage(err),
+    };
+  }
+};
+
 let runtime: EmailRuntime | undefined;
 
 /**
- * Return the shared runtime, building it on first use from the supplied
- * config layered over environment defaults. Overrides are only read when
- * the runtime is first created, so prime it from the plugin's config at
- * setup; subsequent calls (e.g. the tool's `execute`) pass nothing and
- * get the same instance.
+ * Return the shared runtime, building it on first use by resolving
+ * `overrides` over the environment (`SMTP_HOST`, `SMTP_PORT`,
+ * `SMTP_SECURE`, `SMTP_USER`, `SMTP_PASSWORD`, `EMAIL_DOMAIN`,
+ * `EMAIL_FROM`, `EMAIL_ALLOWED_SENDERS`, `EMAIL_SENDER_POLICY`,
+ * `EMAIL_OUTBOX_MODE`, `EMAIL_OUTBOX_DIR`) through
+ * {@link resolveEmailConfig}. With SMTP credentials present it holds a
+ * nodemailer transport and its connection pool; otherwise it is in
+ * file/outbox mode and holds none.
+ *
+ * `overrides` is read only on the call that builds the runtime, so prime it
+ * from the plugin's config at setup; later callers (the tool's `execute`,
+ * the sender-options route) pass nothing and get the same instance. Throws
+ * whatever {@link resolveEmailConfig} throws for an unusable configuration.
  */
 export function getEmailRuntime(overrides?: EmailPluginConfig): EmailRuntime {
   if (!runtime) {
     const config = resolveEmailConfig(overrides);
     runtime = {
       config,
+      execute: directExecute,
       ...(config.mode === "smtp"
         ? {
             transporter: nodemailer.createTransport({
@@ -54,17 +134,180 @@ export function getEmailRuntime(overrides?: EmailPluginConfig): EmailRuntime {
   return runtime;
 }
 
-/** Drop the memoized runtime so the next {@link getEmailRuntime} rebuilds it. */
+/**
+ * Install the executor outbound sends run through. The plugin calls this at
+ * setup with its own `execute()`; a second call replaces the previous one, so
+ * a re-registered plugin does not leave the tools bound to a dead instance.
+ */
+export function setEmailExecutor(execute: EmailExecutor): void {
+  getEmailRuntime().execute = execute;
+}
+
+/**
+ * Drop the memoized runtime, closing the SMTP connection pool, so the next
+ * {@link getEmailRuntime} rebuilds it from fresh config and stops calling
+ * through a torn-down plugin's `execute()`. Idempotent, and the plugin's
+ * `shutdown()` hook.
+ */
 export function resetEmailRuntime(): void {
   runtime?.transporter?.close();
   runtime = undefined;
 }
 
+/**
+ * Run one non-idempotent write through the shared executor and unwrap it.
+ *
+ * `execute()` never throws, so a failed send arrives as `{ ok: false }` with a
+ * status the interceptors already sanitized; it is logged here and re-raised
+ * as a stable {@link ExecutionError} so an upstream message never becomes the
+ * caller's error text. `signal` is the caller's own cancellation (an agent
+ * run, a request teardown); it is merged with the signal the timeout
+ * interceptor supplies so either one unwinds the I/O.
+ */
+export async function executeWrite<T>(
+  operation: string,
+  settings: EmailExecutionSettings,
+  fn: (signal?: AbortSignal) => Promise<T>,
+  signal?: AbortSignal,
+): Promise<T> {
+  const { execute } = getEmailRuntime();
+  const result = await execute(
+    (executeSignal) => fn(mergeSignals(executeSignal, signal)),
+    settings,
+  );
+  if (result.ok) return result.data;
+  // A caller that cancelled is not a failure worth reporting as one.
+  if (signal?.aborted) throw ExecutionError.canceled();
+  logger.warn("execution-failed", {
+    operation,
+    status: result.status,
+    error: result.message,
+  });
+  throw new ExecutionError(`email: ${operation} failed`, {
+    context: { operation, status: result.status },
+  });
+}
+
+/**
+ * Open and tear down one SMTP connection to prove the host, port, and
+ * credentials work. Called at plugin setup so a bad relay shows up in the
+ * boot logs rather than on the first approved send.
+ */
+export async function verifyEmailTransport(
+  transporter: Transporter | undefined,
+  signal?: AbortSignal,
+): Promise<void> {
+  if (!transporter) {
+    throw ConfigurationError.invalidConnection(
+      "SMTP",
+      "The runtime resolved to outbox mode, so there is no transport to verify.",
+    );
+  }
+  await abortable(transporter.verify(), signal);
+}
+
+/**
+ * Stop awaiting `promise` as soon as `signal` aborts. nodemailer exposes no
+ * cancellation hook, so the SMTP conversation itself finishes on its own
+ * connection; what unwinds is the caller and everything downstream of it.
+ */
+function abortable<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T> {
+  if (!signal) return promise;
+  signal.throwIfAborted();
+  // The listener is detached once the race settles so a long-lived run signal
+  // does not accumulate one per send.
+  const listener = new AbortController();
+  const aborted = new Promise<never>((_, reject) => {
+    signal.addEventListener("abort", () => reject(signal.reason), {
+      once: true,
+      signal: listener.signal,
+    });
+  });
+  return Promise.race([promise, aborted]).finally(() => listener.abort());
+}
+
 /** The comma-joined recipient string echoed back in {@link EmailResult}. */
 function recipientEcho(to: string[]): string {
   return to.join(", ");
 }
 
+/**
+ * Node buffer encodings a wire attachment may name for its inline `content`.
+ * Anything else is measured as UTF-8, which over-counts rather than letting
+ * an unrecognized encoding slip past the size cap.
+ */
+const CONTENT_ENCODINGS: ReadonlySet<string> = new Set([
+  "ascii",
+  "base64",
+  "base64url",
+  "binary",
+  "hex",
+  "latin1",
+  "ucs2",
+  "ucs-2",
+  "utf8",
+  "utf-8",
+  "utf16le",
+  "utf-16le",
+]);
+
+/**
+ * Decoded byte size of one attachment's inline content. A `path` attachment
+ * contributes nothing: nodemailer streams it, so its bytes never sit in this
+ * process and cannot be measured here.
+ */
+function attachmentBytes(attachment: EmailAttachment): number {
+  const { content, encoding } = attachment;
+  if (content === undefined) return 0;
+  const declared = encoding?.toLowerCase();
+  const resolved =
+    declared && CONTENT_ENCODINGS.has(declared) ? (declared as BufferEncoding) : "utf8";
+  return Buffer.byteLength(content, resolved);
+}
+
+/**
+ * Reject a message whose body or attachments exceed the plugin's caps. The
+ * body and attachment list arrive from a model, so they are unbounded until
+ * something bounds them; most SMTP relays also reject an oversized message
+ * only after the whole payload has been uploaded.
+ */
+function assertMessageWithinCaps(message: EmailMessage): void {
+  if (message.body.length > MAX_BODY_CHARS) {
+    throw ValidationError.invalidValue(
+      "body",
+      message.body.length,
+      `at most ${MAX_BODY_CHARS} characters`,
+    );
+  }
+  const attachments = message.attachments ?? [];
+  if (attachments.length > MAX_ATTACHMENT_COUNT) {
+    throw ValidationError.invalidValue(
+      "attachments",
+      attachments.length,
+      `at most ${MAX_ATTACHMENT_COUNT} files`,
+    );
+  }
+  let total = 0;
+  for (const attachment of attachments) {
+    const bytes = attachmentBytes(attachment);
+    if (bytes > MAX_ATTACHMENT_BYTES) {
+      throw ValidationError.invalidValue(
+        "attachments[].content",
+        bytes,
+        `at most ${MAX_ATTACHMENT_BYTES} bytes per file`,
+      );
+    }
+    total += bytes;
+  }
+  if (total > MAX_ATTACHMENTS_TOTAL_BYTES) {
+    throw ValidationError.invalidValue(
+      "attachments",
+      total,
+      `at most ${MAX_ATTACHMENTS_TOTAL_BYTES} bytes across all files`,
+    );
+  }
+}
+
 /**
  * Map the wire-format {@link EmailAttachment}s onto nodemailer's
  * attachment shape, dropping unset optional keys so nodemailer applies
@@ -86,44 +329,48 @@ function toMailAttachments(
 }
 
 /**
- * Send (SMTP mode) or persist (file/outbox mode) one message from the
- * resolved `from` address. `to` (and optional `cc` / `bcc`) each accept
- * one or more addresses, and `attachments` are forwarded as files. The
- * body is markdown: SMTP sends it as both a plain-text part (the raw
- * source) and an HTML part (rendered), and the outbox embeds the
- * rendered HTML in a document. In file mode the returned `messageId` is
- * the path written. Throws when `to` carries no recipient, or when `from`
- * is not permitted by the configured sender allow-list.
+ * Hand one already-validated message to SMTP, or write it to the outbox when
+ * no credentials are configured. The half of a send that performs I/O, so it
+ * is what runs inside the interceptor chain.
  */
-export async function sendEmail(message: EmailMessage, from: string): Promise<EmailResult> {
-  if (message.to.length === 0) {
-    throw new Error("email: `to` must include at least one recipient");
-  }
+async function dispatch(
+  message: EmailMessage,
+  from: string,
+  signal?: AbortSignal,
+): Promise<EmailResult> {
   const { config, transporter } = getEmailRuntime();
-  assertSenderAllowed(from, config.allowedSenders);
   const recipient = recipientEcho(message.to);
+  signal?.throwIfAborted();
 
   if (config.mode === "file") {
     const path = await writeOutboxEmail(message, from, config.outDir, config.brand);
     return { sent: true, recipient, from, messageId: path };
   }
 
-  if (!transporter) throw new Error("email: SMTP transport unavailable");
+  if (!transporter) {
+    throw ConfigurationError.invalidConnection(
+      "SMTP",
+      "No transport was built for the resolved configuration.",
+    );
+  }
   const attachments = toMailAttachments(message.attachments);
-  const info = await transporter.sendMail({
-    from,
-    to: message.to,
-    subject: message.subject,
-    text: message.body,
-    html: renderEmailHtml({
+  const info = await abortable(
+    transporter.sendMail({
+      from,
+      to: message.to,
       subject: message.subject,
-      body: message.body,
-      ...(config.brand ? { brand: config.brand } : {}),
+      text: message.body,
+      html: renderEmailHtml({
+        subject: message.subject,
+        body: message.body,
+        ...(config.brand ? { brand: config.brand } : {}),
+      }),
+      ...(message.cc && message.cc.length > 0 ? { cc: message.cc } : {}),
+      ...(message.bcc && message.bcc.length > 0 ? { bcc: message.bcc } : {}),
+      ...(attachments ? { attachments } : {}),
     }),
-    ...(message.cc && message.cc.length > 0 ? { cc: message.cc } : {}),
-    ...(message.bcc && message.bcc.length > 0 ? { bcc: message.bcc } : {}),
-    ...(attachments ? { attachments } : {}),
-  });
+    signal,
+  );
   return {
     sent: true,
     recipient,
@@ -131,3 +378,36 @@ export async function sendEmail(message: EmailMessage, from: string): Promise<Em
     ...(info.messageId ? { messageId: info.messageId } : {}),
   };
 }
+
+/**
+ * Send (SMTP mode) or persist (file/outbox mode) one message from the
+ * resolved `from` address. `to` (and optional `cc` / `bcc`) each accept
+ * one or more addresses, and `attachments` are forwarded as files. The
+ * body is markdown: SMTP sends it as both a plain-text part (the raw
+ * source) and an HTML part (rendered), and the outbox embeds the
+ * rendered HTML in a document. In file mode the returned `messageId` is
+ * the path written. Throws when `to` carries no recipient, when the body
+ * or attachments exceed the plugin's caps, or when `from` is not permitted
+ * by the effective sender allow-list.
+ *
+ * The recipient, cap, and sender checks run before the interceptor chain so
+ * their specific status and actionable message reach the caller instead of
+ * the chain's stable failure text. `signal` cancels the send.
+ */
+export async function sendEmail(
+  message: EmailMessage,
+  from: string,
+  signal?: AbortSignal,
+): Promise<EmailResult> {
+  if (message.to.length === 0) {
+    throw ValidationError.missingField("to");
+  }
+  assertMessageWithinCaps(message);
+  assertSenderAllowed(from, getEmailRuntime().config.allowedSenders);
+  return executeWrite(
+    "send",
+    EMAIL_SEND_SETTINGS,
+    (executeSignal) => dispatch(message, from, executeSignal),
+    signal,
+  );
+}

package/test/config.test.ts

@@ -0,0 +1,163 @@
+import assert from "node:assert/strict";
+import { resolve } from "node:path";
+import { beforeEach, describe, it } from "node:test";
+import {
+  DEFAULT_SMTP_PORT,
+  IMPLICIT_TLS_SMTP_PORT,
+  resolveEmailConfig,
+  type ResolvedSmtpConfig,
+  type SenderPolicy,
+} from "../src/config";
+
+/** Every env var {@link resolveEmailConfig} reads, cleared between cases. */
+const ENV_KEYS = [
+  "SMTP_HOST",
+  "SMTP_PORT",
+  "SMTP_SECURE",
+  "SMTP_USER",
+  "SMTP_PASSWORD",
+  "EMAIL_DOMAIN",
+  "EMAIL_FROM",
+  "EMAIL_ALLOWED_SENDERS",
+  "EMAIL_SENDER_POLICY",
+  "EMAIL_OUTBOX_MODE",
+  "EMAIL_OUTBOX_DIR",
+] as const;
+
+const SMTP_CREDENTIALS = {
+  host: "smtp.example.com",
+  user: "apikey",
+  password: "secret",
+} as const;
+
+beforeEach(() => {
+  for (const key of ENV_KEYS) delete process.env[key];
+});
+
+describe("resolveEmailConfig modes", () => {
+  it("refuses to resolve with neither SMTP credentials nor an outbox opt-in", () => {
+    assert.throws(() => resolveEmailConfig(), /SMTP connection not configured/);
+  });
+
+  it("names the missing env vars for a partial SMTP configuration", () => {
+    assert.throws(
+      () => resolveEmailConfig({ smtp: { host: "smtp.example.com" } }),
+      /Missing required environment variables: SMTP_USER, SMTP_PASSWORD/,
+    );
+  });
+
+  it("refuses SMTP with no sender source to derive a From from", () => {
+    assert.throws(() => resolveEmailConfig({ smtp: SMTP_CREDENTIALS }), /Email sender source/);
+  });
+
+  it("resolves SMTP mode with the default port and STARTTLS", () => {
+    const config = resolveEmailConfig({
+      smtp: SMTP_CREDENTIALS,
+      domain: "mail.example.com",
+    }) as ResolvedSmtpConfig;
+    assert.equal(config.mode, "smtp");
+    assert.equal(config.port, DEFAULT_SMTP_PORT);
+    assert.equal(config.secure, false);
+    assert.deepEqual(config.auth, { user: "apikey", pass: "secret" });
+  });
+
+  it("turns on TLS-on-connect for the implicit-TLS port", () => {
+    const config = resolveEmailConfig({
+      smtp: { ...SMTP_CREDENTIALS, port: IMPLICIT_TLS_SMTP_PORT },
+      domain: "mail.example.com",
+    }) as ResolvedSmtpConfig;
+    assert.equal(config.secure, true);
+  });
+
+  it("prefers explicit config over the matching env var", () => {
+    process.env.SMTP_HOST = "env.example.com";
+    process.env.SMTP_PORT = "2525";
+    process.env.SMTP_USER = "envuser";
+    process.env.SMTP_PASSWORD = "envpass";
+    process.env.EMAIL_DOMAIN = "env.example.com";
+    const config = resolveEmailConfig({
+      smtp: SMTP_CREDENTIALS,
+      domain: "mail.example.com",
+    }) as ResolvedSmtpConfig;
+    assert.equal(config.host, "smtp.example.com");
+    assert.equal(config.domain, "mail.example.com");
+    // The port has no explicit value, so the env var still wins over the default.
+    assert.equal(config.port, 2525);
+  });
+
+  it("resolves outbox mode to an absolute directory when opted in", () => {
+    process.env.EMAIL_OUTBOX_MODE = "1";
+    const config = resolveEmailConfig({ outDir: "tmp/email-outbox" });
+    assert.equal(config.mode, "file");
+    assert.equal(config.mode === "file" && config.outDir, resolve("tmp/email-outbox"));
+  });
+
+  it("keeps a sender source optional in outbox mode", () => {
+    process.env.EMAIL_OUTBOX_MODE = "1";
+    const config = resolveEmailConfig();
+    assert.equal(config.mode, "file");
+    assert.equal(config.domain, undefined);
+    assert.equal(config.from, undefined);
+  });
+});
+
+describe("resolveEmailConfig sender policy", () => {
+  it("defaults to allowlist and narrows an empty list to the configured domain", () => {
+    const config = resolveEmailConfig({ smtp: SMTP_CREDENTIALS, domain: "mail.example.com" });
+    assert.equal(config.senderPolicy, "allowlist");
+    assert.deepEqual(config.allowedSenders, ["*@mail.example.com"]);
+  });
+
+  it("narrows an empty list to a fixed From when that is the sender source", () => {
+    const config = resolveEmailConfig({ smtp: SMTP_CREDENTIALS, from: "Alerts@Example.com" });
+    assert.deepEqual(config.allowedSenders, ["alerts@example.com"]);
+  });
+
+  it("includes both patterns when both sender sources are configured", () => {
+    const config = resolveEmailConfig({
+      smtp: SMTP_CREDENTIALS,
+      from: "alerts@example.com",
+      domain: "mail.example.com",
+    });
+    assert.deepEqual(config.allowedSenders, ["alerts@example.com", "*@mail.example.com"]);
+  });
+
+  it("leaves the list empty under the named unrestricted policy", () => {
+    const config = resolveEmailConfig({
+      smtp: SMTP_CREDENTIALS,
+      domain: "mail.example.com",
+      senderPolicy: "unrestricted",
+    });
+    assert.equal(config.senderPolicy, "unrestricted");
+    assert.deepEqual(config.allowedSenders, []);
+  });
+
+  it("reads the policy from EMAIL_SENDER_POLICY", () => {
+    process.env.EMAIL_SENDER_POLICY = "unrestricted";
+    const config = resolveEmailConfig({ smtp: SMTP_CREDENTIALS, domain: "mail.example.com" });
+    assert.equal(config.senderPolicy, "unrestricted");
+  });
+
+  it("rejects an unrecognized policy", () => {
+    const senderPolicy = "open" as SenderPolicy;
+    assert.throws(
+      () => resolveEmailConfig({ smtp: SMTP_CREDENTIALS, domain: "d.com", senderPolicy }),
+      /Invalid value for senderPolicy/,
+    );
+  });
+
+  it("keeps an explicit allow-list instead of the implied one", () => {
+    const config = resolveEmailConfig({
+      smtp: SMTP_CREDENTIALS,
+      domain: "mail.example.com",
+      allowedSenders: "Alerts@Example.com, *@other.example.com",
+    });
+    assert.deepEqual(config.allowedSenders, ["alerts@example.com", "*@other.example.com"]);
+  });
+
+  it("reads an explicit allow-list from EMAIL_ALLOWED_SENDERS", () => {
+    process.env.EMAIL_OUTBOX_MODE = "1";
+    process.env.EMAIL_ALLOWED_SENDERS = "a@x.com b@x.com";
+    assert.deepEqual(resolveEmailConfig().allowedSenders, ["a@x.com", "b@x.com"]);
+  });
+});