@dbx-tools/email 0.3.28 → 0.3.30

package/test/executor.test.ts

@@ -0,0 +1,162 @@
+import assert from "node:assert/strict";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, it } from "node:test";
+import type { EmailMessage } from "@dbx-tools/shared-email";
+import { EMAIL_SEND_SETTINGS, type EmailExecutionSettings } from "../src/defaults";
+import {
+  getEmailRuntime,
+  resetEmailRuntime,
+  sendEmail,
+  setEmailExecutor,
+  type EmailExecutor,
+} from "../src/transport";
+
+// The runtime is a process-wide singleton built from the environment on first
+// use, so the outbox mode has to be in place before any test sends.
+process.env.EMAIL_OUTBOX_MODE = "1";
+process.env.EMAIL_OUTBOX_DIR = mkdtempSync(join(tmpdir(), "email-executor-"));
+process.env.EMAIL_ALLOWED_SENDERS = "*@example.com";
+
+const FROM = "alerts@example.com";
+
+function message(overrides: Partial<EmailMessage> = {}): EmailMessage {
+  return { to: ["alice@example.com"], subject: "Subject", body: "Body", ...overrides };
+}
+
+/** One recorded call to a spying executor. */
+interface Recorded {
+  settings: EmailExecutionSettings;
+}
+
+/**
+ * An executor that records what it was handed and runs the call, standing in
+ * for the plugin's `execute()`. `supplied` is the signal it hands the call,
+ * mirroring the one the timeout interceptor provides.
+ */
+function spyExecutor(calls: Recorded[], supplied?: AbortSignal): EmailExecutor {
+  return async (fn, settings) => {
+    calls.push({ settings });
+    try {
+      return { ok: true, data: await fn(supplied) };
+    } catch (err) {
+      return { ok: false, status: 500, message: err instanceof Error ? err.message : "failed" };
+    }
+  };
+}
+
+// Dropping the runtime also drops the installed executor, so each case starts
+// on the unregistered fallback.
+afterEach(() => resetEmailRuntime());
+
+describe("send executor registration", () => {
+  it("sends without a registered plugin, through the direct fallback", async () => {
+    const result = await sendEmail(message(), FROM);
+    assert.equal(result.sent, true);
+    assert.ok(result.messageId?.endsWith(".html"));
+  });
+
+  it("installs the supplied executor on the shared runtime", () => {
+    const replacement: EmailExecutor = async (fn) => ({ ok: true, data: await fn() });
+    const fallback = getEmailRuntime().execute;
+    setEmailExecutor(replacement);
+    assert.notEqual(fallback, replacement);
+    assert.equal(getEmailRuntime().execute, replacement);
+  });
+
+  it("routes a send through the installed executor", async () => {
+    const calls: Recorded[] = [];
+    setEmailExecutor(spyExecutor(calls));
+    const result = await sendEmail(message(), FROM);
+    assert.equal(result.sent, true);
+    assert.equal(calls.length, 1);
+  });
+
+  it("hands the executor the write settings, so cache and retry stay off", async () => {
+    const calls: Recorded[] = [];
+    setEmailExecutor(spyExecutor(calls));
+    await sendEmail(message(), FROM);
+    assert.equal(calls[0]!.settings, EMAIL_SEND_SETTINGS);
+    assert.equal(calls[0]!.settings.default.cache?.enabled, false);
+    assert.equal(calls[0]!.settings.default.retry?.enabled, false);
+  });
+
+  it("replaces the previous executor so a re-registered plugin is not stale", async () => {
+    const first: Recorded[] = [];
+    const second: Recorded[] = [];
+    setEmailExecutor(spyExecutor(first));
+    setEmailExecutor(spyExecutor(second));
+    await sendEmail(message(), FROM);
+    assert.equal(first.length, 0);
+    assert.equal(second.length, 1);
+  });
+
+  it("stops using an executor once the runtime is dropped", async () => {
+    const calls: Recorded[] = [];
+    setEmailExecutor(spyExecutor(calls));
+    resetEmailRuntime();
+    await sendEmail(message(), FROM);
+    assert.equal(calls.length, 0);
+  });
+});
+
+describe("send executor failure handling", () => {
+  it("raises a stable error that does not leak the upstream message", async () => {
+    setEmailExecutor(async () => ({ ok: false, status: 502, message: "relay said 5.7.1 nope" }));
+    await assert.rejects(
+      () => sendEmail(message(), FROM),
+      (err: Error) => {
+        assert.match(err.message, /email: send failed/);
+        assert.doesNotMatch(err.message, /5\.7\.1/);
+        return true;
+      },
+    );
+  });
+
+  it("keeps validation ahead of the chain, so the executor never runs", async () => {
+    const calls: Recorded[] = [];
+    setEmailExecutor(spyExecutor(calls));
+    await assert.rejects(() => sendEmail(message({ to: [] }), FROM), /Missing required field: to/);
+    await assert.rejects(() => sendEmail(message(), "evil@attacker.com"), /Invalid value for from/);
+    assert.equal(calls.length, 0);
+  });
+});
+
+describe("send executor user scoping", () => {
+  it("reads the caller scope in force at send time, not at registration time", async () => {
+    // Stands in for AppKit's executionContextStorage: `asUser(req)` wraps the
+    // dispatch in `runInUserContext`, an AsyncLocalStorage.run, so an executor
+    // registered once at setup still resolves the per-call identity.
+    const storage = new AsyncLocalStorage<string>();
+    const seen: (string | undefined)[] = [];
+    setEmailExecutor(async (fn) => {
+      seen.push(storage.getStore());
+      return { ok: true, data: await fn() };
+    });
+    await storage.run("alice@databricks.com", () => sendEmail(message(), FROM));
+    await sendEmail(message(), FROM);
+    assert.deepEqual(seen, ["alice@databricks.com", undefined]);
+  });
+});
+
+describe("send executor cancellation", () => {
+  it("honors the signal the executor supplies", async () => {
+    const calls: Recorded[] = [];
+    setEmailExecutor(spyExecutor(calls, AbortSignal.abort()));
+    await assert.rejects(() => sendEmail(message(), FROM), /email: send failed/);
+    assert.equal(calls.length, 1);
+  });
+
+  it("honors the caller's own signal on the direct fallback", async () => {
+    await assert.rejects(() => sendEmail(message(), FROM, AbortSignal.abort()), /cancel/i);
+  });
+
+  it("honors the caller's signal when the executor supplies a live one", async () => {
+    const calls: Recorded[] = [];
+    setEmailExecutor(spyExecutor(calls, new AbortController().signal));
+    await assert.rejects(() => sendEmail(message(), FROM, AbortSignal.abort()), /cancel/i);
+    assert.equal(calls.length, 1);
+  });
+});

package/test/sender.test.ts

@@ -0,0 +1,153 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { ResolvedEmailConfig } from "../src/config";
+import {
+  assertSenderAllowed,
+  deriveSenderAddress,
+  isSenderAllowed,
+  listSenderOptions,
+  parseAllowedSenders,
+  resolveSenderAddress,
+} from "../src/sender";
+
+/** A resolved outbox config with only the sender fields under test set. */
+function outboxConfig(sender: Partial<ResolvedEmailConfig> = {}): ResolvedEmailConfig {
+  return {
+    mode: "file",
+    outDir: "/tmp/email-outbox",
+    allowedSenders: [],
+    senderPolicy: "allowlist",
+    ...sender,
+  } as ResolvedEmailConfig;
+}
+
+describe("sender allow-list parsing", () => {
+  it("accepts an array or a comma / whitespace separated string", () => {
+    assert.deepEqual(parseAllowedSenders("a@x.com, b@x.com"), ["a@x.com", "b@x.com"]);
+    assert.deepEqual(parseAllowedSenders("a@x.com b@x.com"), ["a@x.com", "b@x.com"]);
+    assert.deepEqual(parseAllowedSenders(["a@x.com", "b@x.com"]), ["a@x.com", "b@x.com"]);
+  });
+
+  it("lower-cases, trims, and de-dupes", () => {
+    assert.deepEqual(parseAllowedSenders(["  A@X.com ", "a@x.com"]), ["a@x.com"]);
+  });
+
+  it("yields nothing for an absent or empty value", () => {
+    assert.deepEqual(parseAllowedSenders(undefined), []);
+    assert.deepEqual(parseAllowedSenders("  ,  "), []);
+  });
+});
+
+describe("sender allow-list matching", () => {
+  it("matches an exact address case-insensitively", () => {
+    assert.equal(isSenderAllowed("Alerts@Example.com", ["alerts@example.com"]), true);
+    assert.equal(isSenderAllowed("other@example.com", ["alerts@example.com"]), false);
+  });
+
+  it("matches any local part on a wildcard or bare domain", () => {
+    assert.equal(isSenderAllowed("alice@mail.example.com", ["*@mail.example.com"]), true);
+    assert.equal(isSenderAllowed("bob@mail.example.com", ["mail.example.com"]), true);
+    assert.equal(isSenderAllowed("alice@other.example.com", ["*@mail.example.com"]), false);
+  });
+
+  it("requires a local part for a domain pattern", () => {
+    assert.equal(isSenderAllowed("@mail.example.com", ["*@mail.example.com"]), false);
+  });
+
+  it("treats a lone star as any address", () => {
+    assert.equal(isSenderAllowed("anyone@anywhere.com", ["*"]), true);
+  });
+
+  it("permits everything when the effective list is empty", () => {
+    assert.equal(isSenderAllowed("anyone@anywhere.com", []), true);
+  });
+
+  it("assertSenderAllowed rejects a denied address and passes a permitted one", () => {
+    assert.throws(
+      () => assertSenderAllowed("evil@attacker.com", ["*@mail.example.com"]),
+      /Invalid value for from/,
+    );
+    assert.doesNotThrow(() => assertSenderAllowed("alice@mail.example.com", ["mail.example.com"]));
+  });
+
+  it("keeps the allow-list patterns out of the thrown message", () => {
+    assert.throws(
+      () => assertSenderAllowed("evil@attacker.com", ["*@mail.example.com"]),
+      (err: Error) => !err.message.includes("mail.example.com"),
+    );
+  });
+});
+
+describe("sender derivation", () => {
+  it("re-homes the user's local part on the sending domain", () => {
+    assert.equal(
+      deriveSenderAddress("alice@databricks.com", "mail.example.com"),
+      "alice@mail.example.com",
+    );
+  });
+
+  it("refuses to derive without an on-behalf-of user", () => {
+    assert.throws(() => deriveSenderAddress(undefined, "mail.example.com"), /user email/);
+    assert.throws(() => deriveSenderAddress("  ", "mail.example.com"), /user email/);
+  });
+
+  it("prefers an explicit From over the per-user derivation", () => {
+    const config = outboxConfig({ from: "alerts@example.com", domain: "mail.example.com" });
+    assert.equal(resolveSenderAddress(config, "alice@databricks.com"), "alerts@example.com");
+  });
+
+  it("derives from the domain when no explicit From is set", () => {
+    const config = outboxConfig({ domain: "mail.example.com" });
+    assert.equal(resolveSenderAddress(config, "alice@databricks.com"), "alice@mail.example.com");
+  });
+
+  it("falls back to the user's own address when neither is configured", () => {
+    assert.equal(
+      resolveSenderAddress(outboxConfig(), "alice@databricks.com"),
+      "alice@databricks.com",
+    );
+  });
+
+  it("refuses when no source and no user yield an address", () => {
+    assert.throws(() => resolveSenderAddress(outboxConfig(), undefined), /Email sender address/);
+  });
+});
+
+describe("sender options for a picker", () => {
+  it("offers the default sender first", () => {
+    const config = outboxConfig({
+      domain: "mail.example.com",
+      allowedSenders: ["alerts@example.com", "*@mail.example.com"],
+    });
+    assert.deepEqual(listSenderOptions(config, "alice@databricks.com"), [
+      "alice@mail.example.com",
+      "alerts@example.com",
+    ]);
+  });
+
+  it("expands a domain pattern against the user's local part", () => {
+    const config = outboxConfig({ allowedSenders: ["*@mail.example.com", "other.example.com"] });
+    assert.deepEqual(listSenderOptions(config, "alice@databricks.com"), [
+      "alice@mail.example.com",
+      "alice@other.example.com",
+    ]);
+  });
+
+  it("drops domain patterns when there is no user local part to expand with", () => {
+    const config = outboxConfig({ allowedSenders: ["*@mail.example.com"] });
+    assert.deepEqual(listSenderOptions(config, undefined), []);
+  });
+
+  it("cannot enumerate a lone star, so it offers only the default", () => {
+    const config = outboxConfig({ from: "alerts@example.com", allowedSenders: ["*"] });
+    assert.deepEqual(listSenderOptions(config, "alice@databricks.com"), ["alerts@example.com"]);
+  });
+
+  it("omits a default the allow-list does not permit", () => {
+    const config = outboxConfig({
+      from: "alerts@example.com",
+      allowedSenders: ["*@mail.example.com"],
+    });
+    assert.deepEqual(listSenderOptions(config, "alice@databricks.com"), ["alice@mail.example.com"]);
+  });
+});

package/test/transport.test.ts

@@ -0,0 +1,105 @@
+import assert from "node:assert/strict";
+import { mkdtempSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { after, describe, it } from "node:test";
+import type { EmailAttachment, EmailMessage } from "@dbx-tools/shared-email";
+import {
+  MAX_ATTACHMENT_BYTES,
+  MAX_ATTACHMENT_COUNT,
+  MAX_ATTACHMENTS_TOTAL_BYTES,
+  MAX_BODY_CHARS,
+} from "../src/defaults";
+import { resetEmailRuntime, sendEmail } from "../src/transport";
+
+// The runtime is a process-wide singleton built from the environment on first
+// use, so the outbox mode has to be in place before any test sends.
+const OUTBOX_DIR = mkdtempSync(join(tmpdir(), "email-outbox-"));
+process.env.EMAIL_OUTBOX_MODE = "1";
+process.env.EMAIL_OUTBOX_DIR = OUTBOX_DIR;
+process.env.EMAIL_ALLOWED_SENDERS = "*@example.com";
+
+const FROM = "alerts@example.com";
+
+function message(overrides: Partial<EmailMessage> = {}): EmailMessage {
+  return { to: ["alice@example.com"], subject: "Subject", body: "Body", ...overrides };
+}
+
+/** An attachment whose inline content decodes to exactly `bytes` bytes. */
+function attachment(filename: string, bytes: number): EmailAttachment {
+  return { filename, content: "x".repeat(bytes) };
+}
+
+after(() => resetEmailRuntime());
+
+describe("send validation", () => {
+  it("rejects a message with no recipient", async () => {
+    await assert.rejects(() => sendEmail(message({ to: [] }), FROM), /Missing required field: to/);
+  });
+
+  it("rejects a body over the character cap", async () => {
+    await assert.rejects(
+      () => sendEmail(message({ body: "x".repeat(MAX_BODY_CHARS + 1) }), FROM),
+      /Invalid value for body/,
+    );
+  });
+
+  it("rejects a single attachment over the per-file byte cap", async () => {
+    const attachments = [attachment("big.bin", MAX_ATTACHMENT_BYTES + 1)];
+    await assert.rejects(
+      () => sendEmail(message({ attachments }), FROM),
+      /Invalid value for attachments\[\]\.content/,
+    );
+  });
+
+  it("rejects attachments that together exceed the total byte cap", async () => {
+    const each = Math.ceil(MAX_ATTACHMENTS_TOTAL_BYTES / 3);
+    const attachments = ["a", "b", "c"].map((name) => attachment(`${name}.bin`, each));
+    await assert.rejects(
+      () => sendEmail(message({ attachments }), FROM),
+      /at most \d+ bytes across all files/,
+    );
+  });
+
+  it("rejects more attachments than the count cap", async () => {
+    const attachments = Array.from({ length: MAX_ATTACHMENT_COUNT + 1 }, (_, index) =>
+      attachment(`f${index}.txt`, 1),
+    );
+    await assert.rejects(() => sendEmail(message({ attachments }), FROM), /at most \d+ files/);
+  });
+
+  it("refuses a sender the effective allow-list does not permit", async () => {
+    await assert.rejects(() => sendEmail(message(), "evil@attacker.com"), /Invalid value for from/);
+  });
+
+  it("rejects a send that was already aborted", async () => {
+    await assert.rejects(() => sendEmail(message(), FROM, AbortSignal.abort()));
+  });
+});
+
+describe("outbox send", () => {
+  it("writes a rendered HTML preview under the sender folder", async () => {
+    const result = await sendEmail(
+      message({ cc: ["team@example.com"], body: "## Status\nResolved." }),
+      FROM,
+    );
+    assert.equal(result.sent, true);
+    assert.equal(result.from, FROM);
+    assert.equal(result.recipient, "alice@example.com");
+    assert.ok(result.messageId?.startsWith(join(OUTBOX_DIR, FROM)));
+    const html = await readFile(result.messageId!, "utf8");
+    assert.match(html, /Status<\/h2>/);
+    assert.match(html, /team@example\.com/);
+  });
+
+  it("measures a base64 attachment by its decoded size, not its text length", async () => {
+    // Four characters carry three decoded bytes, so the text is longer than
+    // what the cap counts.
+    const attachments = [
+      { filename: "a.bin", content: Buffer.alloc(1024, 7).toString("base64"), encoding: "base64" },
+    ];
+    const result = await sendEmail(message({ attachments }), FROM);
+    assert.equal(result.sent, true);
+  });
+});