agent-inbox 0.2.3 → 0.2.4

package/test/mail/mail-gateway.test.ts

@@ -0,0 +1,419 @@
+import { describe, it, expect } from "vitest";
+import { EventEmitter } from "node:events";
+import { InMemoryStorage } from "../../src/storage/memory.js";
+import { MessageRouter } from "../../src/router/message-router.js";
+import { MailGateway, type MailGatewayConfig } from "../../src/mail/mail-gateway.js";
+import { MockMailTransport, makeInboundMail } from "./mock-mail.js";
+import type { Message } from "../../src/types.js";
+
+function setup(configOver: Partial<MailGatewayConfig> = {}) {
+  const storage = new InMemoryStorage();
+  const events = new EventEmitter();
+  const router = new MessageRouter(storage, events);
+  const transport = new MockMailTransport();
+  const config: MailGatewayConfig = {
+    identity: {
+      localDomains: ["example.com"],
+      mappings: [{ agentId: "alice", address: "alice@example.com" }],
+    },
+    routableDomains: ["external.org"],
+    ...configOver,
+  };
+  const gateway = new MailGateway({ transport, storage, router, events, config });
+  router.setMail(gateway);
+  return { storage, events, router, transport, gateway };
+}
+
+function capture(events: EventEmitter, name: string): unknown[] {
+  const seen: unknown[] = [];
+  events.on(name, (e) => seen.push(e));
+  return seen;
+}
+
+function outboundMessage(over: Partial<Message> = {}): Message {
+  return {
+    id: "M1",
+    scope: "default",
+    sender_id: "alice",
+    recipients: [{ agent_id: "user@external.org", kind: "to" }],
+    subject: "hi",
+    content: { type: "text", text: "hello" },
+    importance: "normal",
+    metadata: {},
+    created_at: new Date().toISOString(),
+    ...over,
+  };
+}
+
+describe("MailGateway ingress", () => {
+  it("ingests inbound mail into the recipient's inbox", async () => {
+    const { gateway, storage, events } = setup();
+    const received = capture(events, "mail.received");
+
+    await gateway.handleInbound(
+      makeInboundMail({
+        from: { address: "ext@other.org" },
+        to: [{ address: "alice@example.com" }],
+        subject: "question",
+        text: "what's up",
+        headers: { messageId: "<q1@other.org>", raw: {} },
+      })
+    );
+
+    const inbox = storage.getInbox("alice");
+    expect(inbox).toHaveLength(1);
+    expect(inbox[0].subject).toBe("question");
+    expect(inbox[0].sender_id).toBe("ext@other.org");
+    expect(received).toHaveLength(1);
+  });
+
+  it("dedups a redelivered Message-ID (ingests once)", async () => {
+    const { gateway, storage, events } = setup();
+    const dup = capture(events, "mail.duplicate");
+    const mail = makeInboundMail({
+      to: [{ address: "alice@example.com" }],
+      headers: { messageId: "<same@x>", raw: {} },
+    });
+
+    await gateway.handleInbound(mail);
+    await gateway.handleInbound(mail);
+
+    expect(storage.getInbox("alice")).toHaveLength(1);
+    expect(dup).toHaveLength(1);
+  });
+
+  it("rejects oversize inbound mail", async () => {
+    const { gateway, storage, events } = setup({ maxMessageBytes: 10 });
+    const rejected = capture(events, "mail.rejected");
+
+    await gateway.handleInbound(
+      makeInboundMail({ to: [{ address: "alice@example.com" }], sizeBytes: 999 })
+    );
+
+    expect(storage.getInbox("alice")).toHaveLength(0);
+    expect(rejected).toEqual([
+      expect.objectContaining({ reason: "size-exceeded" }),
+    ]);
+  });
+
+  it("rejects senders outside the allow-list", async () => {
+    const { gateway, events } = setup({ allowedSenderDomains: ["trusted.org"] });
+    const rejected = capture(events, "mail.rejected");
+
+    await gateway.handleInbound(
+      makeInboundMail({
+        from: { address: "spammer@evil.net" },
+        to: [{ address: "alice@example.com" }],
+      })
+    );
+
+    expect(rejected).toEqual([
+      expect.objectContaining({ reason: "sender-not-allowed" }),
+    ]);
+  });
+
+  it("rejects DMARC failures when configured", async () => {
+    const { gateway, events } = setup({ rejectDmarcFail: true });
+    const rejected = capture(events, "mail.rejected");
+
+    await gateway.handleInbound(
+      makeInboundMail({
+        to: [{ address: "alice@example.com" }],
+        authResults: { spf: "fail", dkim: "fail", dmarc: "fail" },
+      })
+    );
+
+    expect(rejected).toEqual([
+      expect.objectContaining({ reason: "dmarc-fail" }),
+    ]);
+  });
+
+  it("rejects mail with no resolvable local recipient", async () => {
+    const { gateway, events } = setup();
+    const rejected = capture(events, "mail.rejected");
+
+    await gateway.handleInbound(
+      makeInboundMail({ to: [{ address: "ghost@example.com" }] })
+    );
+
+    expect(rejected).toEqual([
+      expect.objectContaining({ reason: "no-local-recipient" }),
+    ]);
+  });
+
+  it("rejects mail with too many attachments", async () => {
+    const { gateway, storage, events } = setup({ maxAttachments: 1 });
+    const rejected = capture(events, "mail.rejected");
+
+    await gateway.handleInbound(
+      makeInboundMail({
+        to: [{ address: "alice@example.com" }],
+        attachments: [
+          { contentType: "text/plain", contentRef: "r1", sizeBytes: 1 },
+          { contentType: "text/plain", contentRef: "r2", sizeBytes: 1 },
+        ],
+      })
+    );
+
+    expect(storage.getInbox("alice")).toHaveLength(0);
+    expect(rejected).toEqual([
+      expect.objectContaining({ reason: "too-many-attachments" }),
+    ]);
+  });
+});
+
+describe("MailGateway rate limiting", () => {
+  it("NACKs (throws) inbound over the per-sender-domain limit", async () => {
+    const { gateway, storage } = setup({
+      rateLimit: { windowMs: 60_000, perSenderDomain: 2 },
+    });
+    let n = 0;
+    const mail = () =>
+      makeInboundMail({
+        from: { address: "ext@flood.org" },
+        to: [{ address: "alice@example.com" }],
+        headers: { messageId: `<flood-${n++}@flood.org>`, raw: {} },
+      });
+
+    await gateway.handleInbound(mail());
+    await gateway.handleInbound(mail());
+    // Third within the window is rejected with a transient NACK.
+    await expect(gateway.handleInbound(mail())).rejects.toThrow(/rate limit/i);
+    expect(storage.getInbox("alice")).toHaveLength(2);
+  });
+
+  it("NACKs inbound over the global limit and emits an event", async () => {
+    const { gateway, events } = setup({
+      rateLimit: { windowMs: 60_000, global: 1 },
+    });
+    const limited = capture(events, "mail.rate_limited");
+
+    await gateway.handleInbound(
+      makeInboundMail({
+        from: { address: "a@one.org" },
+        to: [{ address: "alice@example.com" }],
+      })
+    );
+    await expect(
+      gateway.handleInbound(
+        makeInboundMail({
+          from: { address: "b@two.org" },
+          to: [{ address: "alice@example.com" }],
+        })
+      )
+    ).rejects.toThrow(/rate limit/i);
+    expect(limited).toEqual([expect.objectContaining({ scope: "global" })]);
+  });
+
+  it("does not rate limit when unconfigured", async () => {
+    const { gateway, storage } = setup();
+    for (let i = 0; i < 10; i++) {
+      await gateway.handleInbound(
+        makeInboundMail({
+          to: [{ address: "alice@example.com" }],
+          headers: { messageId: `<m${i}@x>`, raw: {} },
+        })
+      );
+    }
+    expect(storage.getInbox("alice")).toHaveLength(10);
+  });
+});
+
+describe("MailGateway egress", () => {
+  it("renders and delivers a message, marking recipients delivered", async () => {
+    const { gateway, storage, transport, events } = setup();
+    await transport.start();
+    const sent = capture(events, "mail.sent");
+    const msg = outboundMessage();
+    storage.putMessage(msg);
+
+    await gateway.send(msg);
+
+    expect(transport.sent).toHaveLength(1);
+    expect(transport.sent[0].to).toEqual([{ address: "user@external.org" }]);
+    expect(transport.sent[0].from).toEqual({ address: "alice@example.com" });
+    expect(storage.getMessage("M1")!.recipients[0].delivered_at).toBeTruthy();
+    expect(sent).toHaveLength(1);
+    // Outbound Message-ID recorded for later correlation.
+    expect(storage.getMessageIdByExternalId("<M1@example.com>")).toBe("M1");
+  });
+
+  it("queues a transient failure and delivers it on retry", async () => {
+    const { gateway, storage, transport, events } = setup();
+    await transport.start();
+    const queued = capture(events, "mail.queued");
+    const msg = outboundMessage();
+    storage.putMessage(msg);
+
+    transport.programNextSend({ disposition: "transient", code: 451 });
+    await gateway.send(msg);
+
+    expect(transport.sent).toHaveLength(0);
+    expect(gateway.queue.size("mail")).toBe(1);
+    expect(queued).toHaveLength(1);
+
+    // Retry — default outcome is delivered.
+    await gateway.processRetries();
+    expect(transport.sent).toHaveLength(1);
+    expect(gateway.queue.size("mail")).toBe(0);
+  });
+
+  it("bounces a permanent failure and synthesizes an inbox notice", async () => {
+    const { gateway, storage, events, transport } = setup();
+    await transport.start();
+    const bounced = capture(events, "mail.bounced");
+    const msg = outboundMessage();
+    storage.putMessage(msg);
+
+    transport.programNextSend({
+      disposition: "permanent",
+      code: 550,
+      detail: "no such user",
+    });
+
+    await gateway.send(msg);
+
+    expect(bounced).toEqual([
+      expect.objectContaining({ messageId: "M1", recipient: "user@external.org" }),
+    ]);
+    // A bounce notice landed in alice's inbox.
+    const aliceInbox = storage.getInbox("alice");
+    const notice = aliceInbox.find((m) => m.sender_id === "mailer-daemon");
+    expect(notice).toBeTruthy();
+    expect(notice!.importance).toBe("high");
+    expect(notice!.in_reply_to).toBe("M1");
+  });
+
+  it("respects config-gated bounce suppression", async () => {
+    const { gateway, storage, events, transport } = setup({
+      bounce: { emitEvent: false, synthesizeInboxMessage: false },
+    });
+    await transport.start();
+    const bounced = capture(events, "mail.bounced");
+    const msg = outboundMessage();
+    storage.putMessage(msg);
+
+    transport.programNextSend({ disposition: "permanent", code: 550 });
+    await gateway.send(msg);
+
+    expect(bounced).toHaveLength(0);
+    expect(storage.getInbox("alice")).toHaveLength(0);
+  });
+});
+
+describe("MailGateway inbound DSN", () => {
+  it("correlates an inbound bounce to the original message and notifies the sender", async () => {
+    const { gateway, storage, events } = setup();
+    const bounced = capture(events, "mail.bounced");
+
+    // Simulate a prior send: original message + recorded RFC id.
+    const original = outboundMessage({ id: "ORIG" });
+    storage.putMessage(original);
+    storage.recordExternalId("<ORIG@example.com>", "ORIG");
+
+    await gateway.handleInbound(
+      makeInboundMail({
+        from: { address: "mailer-daemon@external.org" },
+        to: [{ address: "alice@example.com" }],
+        bounce: {
+          action: "failed",
+          recipient: "user@external.org",
+          status: "5.1.1",
+          originalMessageId: "<ORIG@example.com>",
+        },
+      })
+    );
+
+    expect(bounced).toEqual([
+      expect.objectContaining({ messageId: "ORIG", status: "5.1.1" }),
+    ]);
+    const notice = storage
+      .getInbox("alice")
+      .find((m) => m.sender_id === "mailer-daemon");
+    expect(notice).toBeTruthy();
+  });
+
+  it("treats a delayed DSN as queued, not bounced", async () => {
+    const { gateway, storage, events } = setup();
+    const bounced = capture(events, "mail.bounced");
+    const queued = capture(events, "mail.queued");
+
+    const original = outboundMessage({ id: "ORIG2" });
+    storage.putMessage(original);
+    storage.recordExternalId("<ORIG2@example.com>", "ORIG2");
+
+    await gateway.handleInbound(
+      makeInboundMail({
+        to: [{ address: "alice@example.com" }],
+        bounce: {
+          action: "delayed",
+          recipient: "user@external.org",
+          originalMessageId: "<ORIG2@example.com>",
+        },
+      })
+    );
+
+    expect(bounced).toHaveLength(0);
+    expect(queued).toEqual([
+      expect.objectContaining({ messageId: "ORIG2", delayed: true }),
+    ]);
+  });
+
+  it("dedups a replayed bounce — no repeated event or inbox notice (flood guard)", async () => {
+    const { gateway, storage, events } = setup();
+    const bounced = capture(events, "mail.bounced");
+
+    const original = outboundMessage({ id: "ORIG3" });
+    storage.putMessage(original);
+    storage.recordExternalId("<ORIG3@example.com>", "ORIG3");
+
+    const dsn = () =>
+      makeInboundMail({
+        to: [{ address: "alice@example.com" }],
+        bounce: {
+          action: "failed",
+          recipient: "user@external.org",
+          status: "5.1.1",
+          originalMessageId: "<ORIG3@example.com>",
+        },
+      });
+
+    await gateway.handleInbound(dsn());
+    await gateway.handleInbound(dsn()); // replay
+    await gateway.handleInbound(dsn()); // replay
+
+    expect(bounced).toHaveLength(1);
+    const notices = storage
+      .getInbox("alice")
+      .filter((m) => m.sender_id === "mailer-daemon");
+    expect(notices).toHaveLength(1);
+  });
+});
+
+describe("MailGateway durable retry exhaustion", () => {
+  it("bounces instead of silently dropping when retryMaxAttempts is exhausted", async () => {
+    const { gateway, storage, events, transport } = setup({
+      queue: { retryMaxAttempts: 1 },
+    });
+    await transport.start();
+    const bounced = capture(events, "mail.bounced");
+    const msg = outboundMessage();
+    storage.putMessage(msg);
+
+    // Initial send fails transiently → queued (attempt 0).
+    transport.programNextSend({ disposition: "transient", code: 451 });
+    await gateway.send(msg);
+    expect(gateway.queue.size("mail")).toBe(1);
+
+    // Retry also fails transiently → attempts hit the cap → bounce, not drop.
+    transport.programNextSend({ disposition: "transient", code: 451 });
+    await gateway.processRetries();
+
+    expect(gateway.queue.size("mail")).toBe(0);
+    expect(bounced).toHaveLength(1);
+    const notice = storage
+      .getInbox("alice")
+      .find((m) => m.sender_id === "mailer-daemon");
+    expect(notice).toBeTruthy();
+  });
+});

package/test/mail/mail-transport-contract.test.ts

@@ -0,0 +1,134 @@
+/**
+ * Shared MailTransport contract suite.
+ *
+ * Any backend that provides a MailTransportHarness must pass this suite
+ * unchanged — it encodes the hardening guarantees from §2/§3 of the plan.
+ * Run it against new backends by adding another `runMailTransportContract(...)`.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import type { MailTransportHarness } from "./mock-mail.js";
+import { mockMailHarness, makeInboundMail, makeOutboundMail } from "./mock-mail.js";
+import { postmarkHarness } from "./mock-postmark.js";
+
+export function runMailTransportContract(
+  name: string,
+  makeHarness: () => MailTransportHarness
+): void {
+  describe(`MailTransport contract: ${name}`, () => {
+    let h: MailTransportHarness;
+
+    beforeEach(async () => {
+      h = makeHarness();
+      await h.transport.start();
+    });
+
+    afterEach(async () => {
+      await h.transport.stop();
+    });
+
+    it("start() leaves the transport in a ready state", async () => {
+      expect(h.transport.state).toBe("ready");
+      expect((await h.transport.health()).state).toBe("ready");
+    });
+
+    it("start() is idempotent", async () => {
+      await h.transport.start();
+      await h.transport.start();
+      expect(h.transport.state).toBe("ready");
+    });
+
+    it("send() returns delivered (never throws) on success", async () => {
+      h.programNextSend({ disposition: "delivered", remoteMessageId: "x" });
+      const res = await h.transport.send(makeOutboundMail());
+      expect(res.disposition).toBe("delivered");
+    });
+
+    it("send() returns — does not throw — on transient failure", async () => {
+      h.programNextSend({ disposition: "transient", code: 451 });
+      const res = await h.transport.send(makeOutboundMail());
+      expect(res.disposition).toBe("transient");
+    });
+
+    it("send() returns — does not throw — on permanent failure", async () => {
+      h.programNextSend({ disposition: "permanent", code: 550 });
+      const res = await h.transport.send(makeOutboundMail());
+      expect(res.disposition).toBe("permanent");
+    });
+
+    it("is idempotent on idempotencyKey: a duplicate delivered send produces no second email", async () => {
+      const env = makeOutboundMail({ idempotencyKey: "dup-1" });
+      const first = await h.transport.send(env);
+      const second = await h.transport.send(env);
+      expect(first.disposition).toBe("delivered");
+      expect(second.disposition).toBe("delivered");
+      // Both report delivered, but the second is a replay, not a new email.
+      expect(second.detail).toMatch(/idempotent|replay/i);
+    });
+
+    it("ACKs inbound only after the handler resolves", async () => {
+      const order: string[] = [];
+      h.transport.onReceive(async () => {
+        order.push("handler-start");
+        await Promise.resolve();
+        order.push("handler-end");
+      });
+      await h.injectInbound(makeInboundMail());
+      // injectInbound resolving (the ACK) must come strictly after handler-end.
+      expect(order).toEqual(["handler-start", "handler-end"]);
+    });
+
+    it("NACKs inbound (rejects) when the handler throws", async () => {
+      h.transport.onReceive(async () => {
+        throw new Error("storage commit failed");
+      });
+      await expect(h.injectInbound(makeInboundMail())).rejects.toThrow(
+        /storage commit failed/
+      );
+    });
+
+    it("delivers the inbound message to the handler intact", async () => {
+      let received: unknown;
+      h.transport.onReceive(async (mail) => {
+        received = mail;
+      });
+      const mail = makeInboundMail({ subject: "specific-subject" });
+      await h.injectInbound(mail);
+      expect((received as { subject: string }).subject).toBe("specific-subject");
+    });
+  });
+}
+
+// Run the contract against the in-process mock and the Postmark provider
+// backend (via a fake client). Real SMTP I/O is covered by smtp-e2e.test.ts.
+runMailTransportContract("MockMailTransport", () => mockMailHarness());
+runMailTransportContract("PostmarkTransport", () => postmarkHarness());
+
+describe("MockMailTransport specifics", () => {
+  let h: ReturnType<typeof mockMailHarness>;
+
+  beforeEach(async () => {
+    h = mockMailHarness();
+    await h.transport.start();
+  });
+
+  it("send() throws (programmer error) when not started", async () => {
+    const fresh = mockMailHarness();
+    await expect(fresh.transport.send(makeOutboundMail())).rejects.toThrow(
+      /state/
+    );
+  });
+
+  it("records one entry in sent per delivered email and dedups replays", async () => {
+    const env = makeOutboundMail({ idempotencyKey: "k1" });
+    await h.transport.send(env);
+    await h.transport.send(env);
+    expect(h.mock.sent).toHaveLength(1);
+  });
+
+  it("does not record sent for a transient failure", async () => {
+    h.programNextSend({ disposition: "transient" });
+    await h.transport.send(makeOutboundMail({ idempotencyKey: "k2" }));
+    expect(h.mock.sent).toHaveLength(0);
+  });
+});