agent-inbox 0.2.3 → 0.2.4

package/test/mail/router-mail-integration.test.ts

@@ -0,0 +1,138 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { EventEmitter } from "node:events";
+import { InMemoryStorage } from "../../src/storage/memory.js";
+import {
+  MessageRouter,
+  type MailEgress,
+} from "../../src/router/message-router.js";
+import { MailGateway } from "../../src/mail/mail-gateway.js";
+import { MockMailTransport } from "./mock-mail.js";
+import type { Agent, Message } from "../../src/types.js";
+
+function agent(id: string): Agent {
+  return {
+    agent_id: id,
+    scope: "default",
+    status: "active",
+    metadata: {},
+    registered_at: new Date().toISOString(),
+    last_active_at: new Date().toISOString(),
+  };
+}
+
+const tick = () => new Promise((r) => setImmediate(r));
+
+describe("router ↔ mail integration", () => {
+  let storage: InMemoryStorage;
+  let events: EventEmitter;
+  let router: MessageRouter;
+  let transport: MockMailTransport;
+  let gateway: MailGateway;
+
+  beforeEach(async () => {
+    storage = new InMemoryStorage();
+    events = new EventEmitter();
+    router = new MessageRouter(storage, events);
+    storage.putAgent(agent("alice"));
+    storage.putAgent(agent("bob"));
+    transport = new MockMailTransport();
+    await transport.start();
+    gateway = new MailGateway({
+      transport,
+      storage,
+      router,
+      events,
+      config: {
+        identity: {
+          localDomains: ["example.com"],
+          mappings: [{ agentId: "alice", address: "alice@example.com" }],
+        },
+        routableDomains: ["external.org"],
+      },
+    });
+    router.setMail(gateway);
+  });
+
+  it("routes external mail recipients to the gateway, not local delivery", async () => {
+    const msg = await router.routeMessage({
+      from: "alice",
+      to: [{ agent_id: "user@external.org", kind: "to" }],
+      payload: "hello world",
+    });
+    await tick();
+
+    expect(transport.sent).toHaveLength(1);
+    expect(transport.sent[0].to).toEqual([{ address: "user@external.org" }]);
+    // The mail recipient is not treated as a delivered local agent.
+    const stored = storage.getMessage(msg.id)!;
+    expect(stored.recipients[0].delivered_at).toBeTruthy(); // set by gateway on send
+  });
+
+  it("delivers local recipients locally and mail recipients via the gateway", async () => {
+    await router.routeMessage({
+      from: "alice",
+      to: [
+        { agent_id: "bob", kind: "to" },
+        { agent_id: "user@external.org", kind: "to" },
+      ],
+      payload: "mixed",
+    });
+    await tick();
+
+    expect(storage.getInbox("bob")).toHaveLength(1);
+    expect(transport.sent).toHaveLength(1);
+  });
+
+  it("does not send local-only messages through mail", async () => {
+    await router.routeMessage({
+      from: "alice",
+      to: [{ agent_id: "bob", kind: "to" }],
+      payload: "local only",
+    });
+    await tick();
+    expect(transport.sent).toHaveLength(0);
+  });
+
+  it("sends non-mail remote recipients to federation, not mail", async () => {
+    const routed: Message[] = [];
+    const fakeFederation = {
+      route: async (m: Message) => {
+        routed.push(m);
+        return { delivered: false };
+      },
+    };
+    // Cast: the router only calls .route() on the federation handle.
+    router.setFederation(fakeFederation as never);
+
+    await router.routeMessage({
+      from: "alice",
+      to: [{ agent_id: "carol@system-2", kind: "to" }],
+      payload: "federated",
+    });
+    await tick();
+
+    expect(routed).toHaveLength(1);
+    expect(transport.sent).toHaveLength(0);
+  });
+
+  it("ownsRecipient distinguishes mail domains from federation systems", () => {
+    expect(gateway.ownsRecipient("user@external.org")).toBe(true);
+    expect(gateway.ownsRecipient("user@example.com")).toBe(true);
+    expect(gateway.ownsRecipient("carol@system-2")).toBe(false);
+    expect(gateway.ownsRecipient("bob")).toBe(false);
+  });
+});
+
+describe("MailEgress contract shape", () => {
+  it("MailGateway satisfies MailEgress", () => {
+    const eg: MailEgress = new MailGateway({
+      transport: new MockMailTransport(),
+      storage: new InMemoryStorage(),
+      router: new MessageRouter(new InMemoryStorage(), new EventEmitter()),
+      events: new EventEmitter(),
+      config: { identity: { localDomains: ["x.com"], mappings: [] } },
+    });
+    expect(typeof eg.ownsRecipient).toBe("function");
+    expect(typeof eg.send).toBe("function");
+  });
+});

package/test/mail/smtp-e2e.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { SmtpTransport } from "../../src/mail/smtp-transport.js";
+import { makeOutboundMail } from "./mock-mail.js";
+import type { InboundMail } from "../../src/mail/types.js";
+
+// These libs are optional peer deps; skip the real-socket e2e if absent.
+const haveLibs = await Promise.all([
+  import("smtp-server").then(() => true).catch(() => false),
+  import("nodemailer").then(() => true).catch(() => false),
+  import("mailparser").then(() => true).catch(() => false),
+]).then((r) => r.every(Boolean));
+
+const randomPort = () => 30000 + Math.floor(Math.random() * 5000);
+
+describe.skipIf(!haveLibs)("SmtpTransport e2e (loopback)", () => {
+  const transports: SmtpTransport[] = [];
+  afterEach(async () => {
+    for (const t of transports) await t.stop().catch(() => {});
+    transports.length = 0;
+  });
+
+  it("delivers a message from one transport to another and ACKs after commit", async () => {
+    const recvPort = randomPort();
+
+    // Receiver: captures inbound and resolves only after a simulated commit.
+    const received: InboundMail[] = [];
+    const committed: string[] = [];
+    const receiver = new SmtpTransport({ listenPort: recvPort });
+    receiver.onReceive(async (mail) => {
+      received.push(mail);
+      await new Promise((r) => setTimeout(r, 5)); // simulate async storage commit
+      committed.push("done");
+    });
+    transports.push(receiver);
+    await receiver.start();
+
+    // Sender: listens on a different port, relays to the receiver.
+    const sender = new SmtpTransport({
+      listenPort: randomPort(),
+      relay: { host: "127.0.0.1", port: recvPort, secure: false },
+    });
+    transports.push(sender);
+    await sender.start();
+
+    const result = await sender.send(
+      makeOutboundMail({
+        idempotencyKey: "e2e-1",
+        from: { address: "alice@example.com" },
+        to: [{ address: "bob@receiver.test" }],
+        subject: "e2e subject",
+        text: "e2e body",
+        headers: { messageId: "<e2e-1@example.com>" },
+      })
+    );
+
+    expect(result.disposition).toBe("delivered");
+
+    // Allow the receiver's onData/handler to run.
+    await new Promise((r) => setTimeout(r, 100));
+
+    expect(received).toHaveLength(1);
+    expect(received[0].subject).toBe("e2e subject");
+    expect(received[0].text?.trim()).toBe("e2e body");
+    expect(received[0].headers.messageId).toBe("<e2e-1@example.com>");
+    // The handler's commit ran (ACK happened after it).
+    expect(committed).toEqual(["done"]);
+  });
+
+  it("is idempotent on the sender for a repeated idempotencyKey", async () => {
+    const recvPort = randomPort();
+    const received: InboundMail[] = [];
+    const receiver = new SmtpTransport({ listenPort: recvPort });
+    receiver.onReceive(async (mail) => {
+      received.push(mail);
+    });
+    transports.push(receiver);
+    await receiver.start();
+
+    const sender = new SmtpTransport({
+      listenPort: randomPort(),
+      relay: { host: "127.0.0.1", port: recvPort, secure: false },
+    });
+    transports.push(sender);
+    await sender.start();
+
+    const env = makeOutboundMail({
+      idempotencyKey: "dup-key",
+      to: [{ address: "bob@receiver.test" }],
+      headers: { messageId: "<dup-key@example.com>" },
+    });
+    await sender.send(env);
+    const second = await sender.send(env);
+
+    expect(second.detail).toMatch(/idempotent|replay/i);
+    await new Promise((r) => setTimeout(r, 100));
+    expect(received).toHaveLength(1); // not delivered twice
+  });
+});

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

@@ -0,0 +1,138 @@
+import { describe, it, expect } from "vitest";
+import {
+  smtpErrorToResult,
+  parsedToInboundMail,
+  toNodemailerMessage,
+  mailauthToResults,
+} from "../../src/mail/smtp-transport.js";
+import { makeOutboundMail } from "./mock-mail.js";
+
+describe("smtpErrorToResult", () => {
+  it("maps 5xx to permanent", () => {
+    expect(smtpErrorToResult({ responseCode: 550, response: "no user" })).toEqual({
+      disposition: "permanent",
+      code: 550,
+      detail: "no user",
+    });
+  });
+
+  it("maps 4xx to transient", () => {
+    expect(smtpErrorToResult({ responseCode: 451 }).disposition).toBe("transient");
+  });
+
+  it("maps connection/DNS errors (no code) to transient", () => {
+    expect(smtpErrorToResult({ message: "ECONNREFUSED" })).toEqual({
+      disposition: "transient",
+      detail: "ECONNREFUSED",
+    });
+  });
+});
+
+describe("parsedToInboundMail", () => {
+  it("builds an InboundMail from parsed fields", () => {
+    const mail = parsedToInboundMail(
+      {
+        from: { value: [{ address: "ext@other.org", name: "Ext" }] },
+        to: { value: [{ address: "alice@example.com" }] },
+        cc: { value: [{ address: "bob@example.com" }] },
+        subject: "hi",
+        text: "body",
+        messageId: "<m1@other.org>",
+        inReplyTo: "<p0@other.org>",
+        references: "<root@other.org> <p0@other.org>",
+        date: new Date("2026-01-01T00:00:00Z"),
+        headers: new Map([["x-priority", "1"]]),
+      },
+      {
+        envelopeFrom: "ext@other.org",
+        envelopeTo: ["alice@example.com"],
+        remote: { ip: "203.0.113.5" },
+        sizeBytes: 200,
+      }
+    );
+
+    expect(mail.from).toEqual({ address: "ext@other.org", name: "Ext" });
+    expect(mail.to).toEqual([{ address: "alice@example.com", name: undefined }]);
+    expect(mail.cc).toEqual([{ address: "bob@example.com", name: undefined }]);
+    expect(mail.headers.messageId).toBe("<m1@other.org>");
+    expect(mail.headers.references).toEqual([
+      "<root@other.org>",
+      "<p0@other.org>",
+    ]);
+    expect(mail.headers.raw["x-priority"]).toBe("1");
+    expect(mail.remote).toEqual({ ip: "203.0.113.5" });
+    expect(mail.receivedAt).toBe("2026-01-01T00:00:00.000Z");
+  });
+
+  it("falls back to the envelope sender when From is missing", () => {
+    const mail = parsedToInboundMail(
+      { to: { value: [{ address: "alice@example.com" }] } },
+      { envelopeFrom: "bounce@mta.net", envelopeTo: [], sizeBytes: 1 }
+    );
+    expect(mail.from).toEqual({ address: "bounce@mta.net" });
+  });
+});
+
+describe("toNodemailerMessage", () => {
+  it("maps an OutboundMail to nodemailer fields", () => {
+    const msg = toNodemailerMessage(
+      makeOutboundMail({
+        from: { address: "alice@example.com", name: "Alice" },
+        to: [{ address: "ext@other.org" }],
+        cc: [{ address: "c@other.org" }],
+        subject: "subject",
+        text: "text body",
+        headers: {
+          messageId: "<m@example.com>",
+          inReplyTo: "<p@other.org>",
+          references: ["<r@other.org>"],
+        },
+      })
+    );
+    expect(msg.from).toEqual({ name: "Alice", address: "alice@example.com" });
+    expect(msg.to).toEqual(["ext@other.org"]);
+    expect(msg.cc).toEqual(["c@other.org"]);
+    expect(msg.messageId).toBe("<m@example.com>");
+    expect(msg.inReplyTo).toBe("<p@other.org>");
+    expect(msg.references).toEqual(["<r@other.org>"]);
+  });
+
+  it("includes dkim options when provided", () => {
+    const msg = toNodemailerMessage(makeOutboundMail(), {
+      domainName: "example.com",
+      keySelector: "s1",
+      privateKey: "KEY",
+    });
+    expect(msg.dkim).toEqual({
+      domainName: "example.com",
+      keySelector: "s1",
+      privateKey: "KEY",
+    });
+  });
+});
+
+describe("mailauthToResults", () => {
+  it("normalizes a full pass verdict", () => {
+    expect(
+      mailauthToResults({
+        spf: { status: { result: "pass" } },
+        dkim: { results: [{ status: { result: "pass" } }] },
+        dmarc: { status: { result: "pass" } },
+      })
+    ).toEqual({ spf: "pass", dkim: "pass", dmarc: "pass" });
+  });
+
+  it("defaults missing verdicts to none", () => {
+    expect(mailauthToResults({})).toEqual({
+      spf: "none",
+      dkim: "none",
+      dmarc: "none",
+    });
+  });
+
+  it("maps dmarc fail through", () => {
+    expect(
+      mailauthToResults({ dmarc: { status: { result: "fail" } } }).dmarc
+    ).toBe("fail");
+  });
+});