agent-inbox 0.2.3 → 0.2.4

package/test/mail/dsn-parse.test.ts

@@ -0,0 +1,239 @@
+import { describe, it, expect } from "vitest";
+import { parseDsnFromParsed, parsedToInboundMail } from "../../src/mail/smtp-transport.js";
+
+// Build a mailparser-like object with a delivery-status part and (optionally) a
+// returned message/rfc822 part.
+function dsnParsed(opts: {
+  contentType?: string;
+  statusText: string;
+  originalRfc822?: string;
+}) {
+  const attachments = [
+    {
+      content: Buffer.from(opts.statusText),
+      contentType: "message/delivery-status",
+      size: opts.statusText.length,
+    },
+  ];
+  if (opts.originalRfc822) {
+    attachments.push({
+      content: Buffer.from(opts.originalRfc822),
+      contentType: "message/rfc822",
+      size: opts.originalRfc822.length,
+    });
+  }
+  return {
+    headers: new Map<string, unknown>([
+      [
+        "content-type",
+        opts.contentType ?? "multipart/report; report-type=delivery-status",
+      ],
+    ]),
+    attachments,
+  };
+}
+
+describe("parseDsnFromParsed", () => {
+  it("returns undefined for ordinary mail", () => {
+    expect(
+      parseDsnFromParsed({ subject: "hello", text: "hi", attachments: [] })
+    ).toBeUndefined();
+  });
+
+  it("parses a hard-failure DSN", () => {
+    const dsn = parseDsnFromParsed(
+      dsnParsed({
+        statusText:
+          "Reporting-MTA: dns; mail.example.com\r\n" +
+          "Final-Recipient: rfc822; gone@nowhere.example\r\n" +
+          "Action: failed\r\n" +
+          "Status: 5.1.1\r\n" +
+          "Diagnostic-Code: smtp; 550 5.1.1 No such user\r\n",
+        originalRfc822: "Message-ID: <orig-123@example.com>\r\nSubject: hi\r\n",
+      })
+    );
+    expect(dsn).toEqual({
+      action: "failed",
+      recipient: "gone@nowhere.example",
+      status: "5.1.1",
+      originalMessageId: "<orig-123@example.com>",
+      diagnostic: "smtp; 550 5.1.1 No such user",
+    });
+  });
+
+  it("classifies a 4.x.x status as delayed even without Action", () => {
+    const dsn = parseDsnFromParsed(
+      dsnParsed({
+        statusText:
+          "Final-Recipient: rfc822; slow@example.com\r\nStatus: 4.4.1\r\n",
+      })
+    );
+    expect(dsn?.action).toBe("delayed");
+  });
+
+  it("honors Action: delayed", () => {
+    const dsn = parseDsnFromParsed(
+      dsnParsed({
+        statusText:
+          "Final-Recipient: rfc822; slow@example.com\r\nAction: delayed\r\nStatus: 4.2.2\r\n",
+      })
+    );
+    expect(dsn?.action).toBe("delayed");
+  });
+
+  it("maps a positive (relayed/delivered) DSN to delivered", () => {
+    const dsn = parseDsnFromParsed(
+      dsnParsed({
+        statusText:
+          "Final-Recipient: rfc822; ok@example.com\r\nAction: relayed\r\nStatus: 2.0.0\r\n",
+      })
+    );
+    expect(dsn?.action).toBe("delivered");
+  });
+
+  it("falls back to Original-Recipient when Final-Recipient is absent", () => {
+    const dsn = parseDsnFromParsed(
+      dsnParsed({
+        statusText:
+          "Original-Recipient: rfc822; orig@example.com\r\nAction: failed\r\nStatus: 5.0.0\r\n",
+      })
+    );
+    expect(dsn?.recipient).toBe("orig@example.com");
+  });
+
+  it("does NOT classify an ordinary message that merely carries an attached DSN", () => {
+    // Top-level content-type is not multipart/report (e.g. a user forwarding a
+    // bounce to support). Detecting on the attachment alone would misroute it.
+    const dsn = parseDsnFromParsed(
+      dsnParsed({
+        contentType: "multipart/mixed; boundary=x",
+        statusText: "Final-Recipient: rfc822; x@y.com\r\nAction: failed\r\nStatus: 5.0.0\r\n",
+      })
+    );
+    expect(dsn).toBeUndefined();
+  });
+
+  it("returns undefined for a multipart/report with no delivery-status part", () => {
+    expect(
+      parseDsnFromParsed({
+        headers: new Map([["content-type", "multipart/report; report-type=delivery-status"]]),
+        attachments: [],
+      })
+    ).toBeUndefined();
+  });
+
+  it("flows through parsedToInboundMail into the bounce field", () => {
+    const mail = parsedToInboundMail(
+      dsnParsed({
+        statusText:
+          "Final-Recipient: rfc822; gone@x.com\r\nAction: failed\r\nStatus: 5.1.1\r\n",
+      }),
+      { envelopeFrom: "mailer-daemon@mta", envelopeTo: [], sizeBytes: 100 }
+    );
+    expect(mail.bounce).toMatchObject({ action: "failed", recipient: "gone@x.com" });
+  });
+});
+
+// Integration: parse a realistic DSN with the REAL mailparser, since synthetic
+// fixtures above don't match how mailparser surfaces a multipart/report (it
+// folds the delivery-status block into `text`, not `attachments`, when there is
+// no Content-Disposition). This guards against the regression where real
+// Postfix/Gmail bounces were silently dropped.
+const haveMailparser = await import("mailparser")
+  .then(() => true)
+  .catch(() => false);
+
+describe.skipIf(!haveMailparser)("parseDsnFromParsed (real mailparser)", () => {
+  // A Postfix-style hard bounce: multipart/report, delivery-status part has NO
+  // Content-Disposition, plus a text/rfc822-headers part with the original id.
+  const RAW_HARD_BOUNCE = [
+    "From: MAILER-DAEMON@mail.example.com",
+    "To: alice@example.com",
+    "Subject: Undelivered Mail Returned to Sender",
+    "MIME-Version: 1.0",
+    'Content-Type: multipart/report; report-type=delivery-status; boundary="BOUND"',
+    "",
+    "--BOUND",
+    "Content-Type: text/plain; charset=us-ascii",
+    "",
+    "This is the mail system at host mail.example.com.",
+    "Your message could not be delivered.",
+    "",
+    "--BOUND",
+    "Content-Type: message/delivery-status",
+    "",
+    "Reporting-MTA: dns; mail.example.com",
+    "",
+    "Final-Recipient: rfc822; gone@nowhere.example",
+    "Action: failed",
+    "Status: 5.1.1",
+    "Diagnostic-Code: smtp; 550 5.1.1 <gone@nowhere.example>: User unknown",
+    "",
+    "--BOUND",
+    "Content-Type: text/rfc822-headers",
+    "",
+    "Message-ID: <orig-abc@example.com>",
+    "Subject: hi there",
+    "",
+    "--BOUND--",
+    "",
+  ].join("\r\n");
+
+  async function parse(raw: string) {
+    const { simpleParser } = await import("mailparser");
+    return simpleParser(Buffer.from(raw));
+  }
+
+  it("detects a real Postfix-style hard bounce folded into the text body", async () => {
+    const parsed = await parse(RAW_HARD_BOUNCE);
+    const dsn = parseDsnFromParsed(parsed as never);
+    expect(dsn).toBeTruthy();
+    expect(dsn!.action).toBe("failed");
+    expect(dsn!.recipient).toBe("gone@nowhere.example");
+    expect(dsn!.status).toBe("5.1.1");
+    expect(dsn!.originalMessageId).toBe("<orig-abc@example.com>");
+    expect(dsn!.diagnostic).toMatch(/User unknown/);
+  });
+
+  it("classifies a real 4.x.x soft bounce as delayed", async () => {
+    const soft = RAW_HARD_BOUNCE.replace("Action: failed", "Action: delayed").replace(
+      "Status: 5.1.1",
+      "Status: 4.4.1"
+    );
+    const dsn = parseDsnFromParsed((await parse(soft)) as never);
+    expect(dsn?.action).toBe("delayed");
+  });
+
+  it("does not classify an ordinary multipart/mixed email as a bounce", async () => {
+    const ordinary = [
+      "From: bob@example.com",
+      "To: alice@example.com",
+      "Subject: hi",
+      "MIME-Version: 1.0",
+      'Content-Type: multipart/mixed; boundary="B"',
+      "",
+      "--B",
+      "Content-Type: text/plain",
+      "",
+      "just a normal message",
+      "--B--",
+      "",
+    ].join("\r\n");
+    const dsn = parseDsnFromParsed((await parse(ordinary)) as never);
+    expect(dsn).toBeUndefined();
+  });
+
+  it("flows a real bounce through parsedToInboundMail into the bounce field", async () => {
+    const parsed = await parse(RAW_HARD_BOUNCE);
+    const mail = parsedToInboundMail(parsed as never, {
+      envelopeFrom: "MAILER-DAEMON@mail.example.com",
+      envelopeTo: ["alice@example.com"],
+      sizeBytes: RAW_HARD_BOUNCE.length,
+    });
+    expect(mail.bounce).toMatchObject({
+      action: "failed",
+      recipient: "gone@nowhere.example",
+      originalMessageId: "<orig-abc@example.com>",
+    });
+  });
+});

package/test/mail/email-mapper.test.ts

@@ -0,0 +1,341 @@
+import { describe, it, expect } from "vitest";
+import { AddressBook } from "../../src/mail/address-book.js";
+import {
+  inboundMailToMessage,
+  messageToOutboundMail,
+  UnknownRecipientError,
+  type InboundMapContext,
+  type OutboundMapContext,
+} from "../../src/mail/email-mapper.js";
+import { makeInboundMail } from "./mock-mail.js";
+import type { Message } from "../../src/types.js";
+
+function addressBook(): AddressBook {
+  return new AddressBook({
+    localDomains: ["example.com"],
+    mappings: [
+      { agentId: "alice", address: "alice@example.com" },
+      { agentId: "bob", address: "bob@example.com" },
+    ],
+  });
+}
+
+function inCtx(over: Partial<InboundMapContext> = {}): InboundMapContext {
+  return { addressBook: addressBook(), defaultScope: "default", ...over };
+}
+
+function outCtx(over: Partial<OutboundMapContext> = {}): OutboundMapContext {
+  return { addressBook: addressBook(), ...over };
+}
+
+describe("inboundMailToMessage", () => {
+  it("maps a basic inbound email to a Message", () => {
+    const msg = inboundMailToMessage(
+      makeInboundMail({
+        from: { address: "ext@other.org", name: "Ext" },
+        to: [{ address: "alice@example.com" }],
+        subject: "hi",
+        text: "body text",
+        headers: { messageId: "<abc@other.org>", raw: {} },
+      }),
+      inCtx()
+    );
+    expect(msg.sender_id).toBe("ext@other.org");
+    expect(msg.recipients).toEqual([{ agent_id: "alice", kind: "to" }]);
+    expect(msg.subject).toBe("hi");
+    expect(msg.content).toEqual({ type: "text", text: "body text" });
+    expect(msg.metadata.rfcMessageId).toBe("<abc@other.org>");
+    expect(msg.metadata.envelopeFrom).toBe("ext@example.org");
+  });
+
+  it("resolves cc recipients and preserves kind", () => {
+    const msg = inboundMailToMessage(
+      makeInboundMail({
+        to: [{ address: "alice@example.com" }],
+        cc: [{ address: "bob@example.com" }],
+      }),
+      inCtx()
+    );
+    expect(msg.recipients).toContainEqual({ agent_id: "alice", kind: "to" });
+    expect(msg.recipients).toContainEqual({ agent_id: "bob", kind: "cc" });
+  });
+
+  it("derives scope from plus-addressing on the matched to recipient", () => {
+    const msg = inboundMailToMessage(
+      makeInboundMail({ to: [{ address: "alice+project-x@example.com" }] }),
+      inCtx()
+    );
+    expect(msg.scope).toBe("project-x");
+    expect(msg.recipients[0].agent_id).toBe("alice");
+  });
+
+  it("skips unresolvable recipients but keeps resolvable ones", () => {
+    const msg = inboundMailToMessage(
+      makeInboundMail({
+        to: [
+          { address: "alice@example.com" },
+          { address: "stranger@elsewhere.net" },
+        ],
+      }),
+      inCtx()
+    );
+    expect(msg.recipients).toEqual([{ agent_id: "alice", kind: "to" }]);
+  });
+
+  it("throws UnknownRecipientError when nothing resolves", () => {
+    expect(() =>
+      inboundMailToMessage(
+        makeInboundMail({ to: [{ address: "nobody@elsewhere.net" }] }),
+        inCtx()
+      )
+    ).toThrow(UnknownRecipientError);
+  });
+
+  it("uses catch-all when configured and mailbox is unknown", () => {
+    const ab = new AddressBook({
+      localDomains: ["example.com"],
+      mappings: [],
+      catchAllAgentId: "triage",
+    });
+    const msg = inboundMailToMessage(
+      makeInboundMail({ to: [{ address: "whoever@example.com" }] }),
+      inCtx({ addressBook: ab })
+    );
+    expect(msg.recipients[0].agent_id).toBe("triage");
+  });
+
+  it("derives a stable thread_tag from the References root", () => {
+    const a = inboundMailToMessage(
+      makeInboundMail({
+        to: [{ address: "alice@example.com" }],
+        headers: {
+          messageId: "<m2@x>",
+          references: ["<root@x>", "<m1@x>"],
+          raw: {},
+        },
+      }),
+      inCtx()
+    );
+    const b = inboundMailToMessage(
+      makeInboundMail({
+        to: [{ address: "alice@example.com" }],
+        headers: {
+          messageId: "<m3@x>",
+          references: ["<root@x>"],
+          raw: {},
+        },
+      }),
+      inCtx()
+    );
+    expect(a.thread_tag).toBeTruthy();
+    expect(a.thread_tag).toBe(b.thread_tag); // same root → same thread
+  });
+
+  it("resolves in_reply_to to an inbox id when the RFC id is known", () => {
+    const msg = inboundMailToMessage(
+      makeInboundMail({
+        to: [{ address: "alice@example.com" }],
+        headers: { messageId: "<reply@x>", inReplyTo: "<parent@x>", raw: {} },
+      }),
+      inCtx({
+        lookupInboxIdByRfcMessageId: (id) =>
+          id === "<parent@x>" ? "inbox-parent-123" : undefined,
+      })
+    );
+    expect(msg.in_reply_to).toBe("inbox-parent-123");
+    expect(msg.metadata.rfcInReplyTo).toBe("<parent@x>");
+  });
+
+  it("maps X-Priority / Importance headers to importance", () => {
+    const high = inboundMailToMessage(
+      makeInboundMail({
+        to: [{ address: "alice@example.com" }],
+        headers: { raw: { "x-priority": "1" } },
+      }),
+      inCtx()
+    );
+    expect(high.importance).toBe("high");
+    const low = inboundMailToMessage(
+      makeInboundMail({
+        to: [{ address: "alice@example.com" }],
+        headers: { raw: { importance: "low" } },
+      }),
+      inCtx()
+    );
+    expect(low.importance).toBe("low");
+  });
+
+  it("retains an inbound bounce in metadata", () => {
+    const msg = inboundMailToMessage(
+      makeInboundMail({
+        to: [{ address: "alice@example.com" }],
+        bounce: {
+          action: "failed",
+          recipient: "gone@nowhere.net",
+          status: "5.1.1",
+          originalMessageId: "<orig@example.com>",
+        },
+      }),
+      inCtx()
+    );
+    expect(msg.metadata.bounce).toMatchObject({ action: "failed" });
+  });
+});
+
+describe("messageToOutboundMail", () => {
+  function baseMessage(over: Partial<Message> = {}): Message {
+    return {
+      id: "01ABCDEF",
+      scope: "default",
+      sender_id: "alice",
+      recipients: [{ agent_id: "ext@other.org", kind: "to" }],
+      subject: "subject",
+      content: { type: "text", text: "hello world" },
+      importance: "normal",
+      metadata: {},
+      created_at: new Date().toISOString(),
+      ...over,
+    };
+  }
+
+  it("renders a Message into an OutboundMail", () => {
+    const out = messageToOutboundMail(baseMessage(), outCtx());
+    expect(out.idempotencyKey).toBe("01ABCDEF");
+    expect(out.from).toEqual({ address: "alice@example.com" });
+    expect(out.to).toEqual([{ address: "ext@other.org" }]);
+    expect(out.text).toBe("hello world");
+    expect(out.headers.messageId).toBe("<01ABCDEF@example.com>");
+  });
+
+  it("falls back to <agentId>@primaryDomain for an unmapped sender", () => {
+    const out = messageToOutboundMail(
+      baseMessage({ sender_id: "ghost" }),
+      outCtx()
+    );
+    expect(out.from).toEqual({ address: "ghost@example.com" });
+  });
+
+  it("splits recipients by kind into to/cc/bcc", () => {
+    const out = messageToOutboundMail(
+      baseMessage({
+        recipients: [
+          { agent_id: "a@x.org", kind: "to" },
+          { agent_id: "b@x.org", kind: "cc" },
+          { agent_id: "c@x.org", kind: "bcc" },
+        ],
+      }),
+      outCtx()
+    );
+    expect(out.to).toEqual([{ address: "a@x.org" }]);
+    expect(out.cc).toEqual([{ address: "b@x.org" }]);
+    expect(out.bcc).toEqual([{ address: "c@x.org" }]);
+  });
+
+  it("builds In-Reply-To / References from a known parent", () => {
+    const out = messageToOutboundMail(
+      baseMessage({ in_reply_to: "inbox-parent" }),
+      outCtx({
+        lookupRfcMessageId: (id) =>
+          id === "inbox-parent" ? "<parent@other.org>" : undefined,
+        lookupReferences: () => ["<root@other.org>"],
+      })
+    );
+    expect(out.headers.inReplyTo).toBe("<parent@other.org>");
+    expect(out.headers.references).toEqual([
+      "<root@other.org>",
+      "<parent@other.org>",
+    ]);
+  });
+
+  it("synthesizes a parent Message-ID when the RFC id is unknown", () => {
+    const out = messageToOutboundMail(
+      baseMessage({ in_reply_to: "inbox-parent" }),
+      outCtx()
+    );
+    expect(out.headers.inReplyTo).toBe("<inbox-parent@example.com>");
+  });
+
+  it("carries html body from metadata but does NOT leak arbitrary metadata to the backend", () => {
+    const out = messageToOutboundMail(
+      baseMessage({
+        metadata: { htmlBody: "<p>hi</p>", rfcMessageId: "<x@y>", userTag: "internal" },
+      }),
+      outCtx()
+    );
+    expect(out.html).toBe("<p>hi</p>");
+    // Internal metadata must not be forwarded to the external mail provider.
+    expect(out.backendHints).toBeUndefined();
+  });
+
+  it("forwards only an explicit mailBackendHints object to the backend", () => {
+    const out = messageToOutboundMail(
+      baseMessage({
+        metadata: { secret: "no", mailBackendHints: { tag: "newsletter" } },
+      }),
+      outCtx()
+    );
+    expect(out.backendHints).toEqual({ tag: "newsletter" });
+  });
+
+  it("validates and filters malformed attachment metadata", () => {
+    const out = messageToOutboundMail(
+      baseMessage({
+        metadata: {
+          mailAttachments: [
+            { contentRef: "sha256:a", contentType: "text/plain", sizeBytes: 3, filename: "ok.txt" },
+            { bogus: true }, // dropped — missing contentRef/contentType
+            "not-an-object", // dropped
+          ],
+        },
+      }),
+      outCtx()
+    );
+    expect(out.attachments).toEqual([
+      { contentRef: "sha256:a", contentType: "text/plain", sizeBytes: 3, filename: "ok.txt" },
+    ]);
+  });
+});
+
+describe("round-trip", () => {
+  it("preserves subject, body, and threading across inbound→outbound reply", () => {
+    const ab = addressBook();
+    // Inbound arrives for alice.
+    const inbound = inboundMailToMessage(
+      makeInboundMail({
+        from: { address: "ext@other.org" },
+        to: [{ address: "alice@example.com" }],
+        subject: "Question",
+        text: "what is the status?",
+        headers: { messageId: "<q1@other.org>", raw: {} },
+      }),
+      { addressBook: ab }
+    );
+
+    // Alice replies: a new message in_reply_to the inbound one, to the sender.
+    const reply: Message = {
+      id: "REPLY1",
+      scope: inbound.scope,
+      sender_id: "alice",
+      recipients: [{ agent_id: "ext@other.org", kind: "to" }],
+      subject: "Re: Question",
+      content: { type: "text", text: "all good" },
+      in_reply_to: inbound.id,
+      importance: "normal",
+      metadata: {},
+      created_at: new Date().toISOString(),
+    };
+
+    const out = messageToOutboundMail(reply, {
+      addressBook: ab,
+      // The reply's parent is the inbound message; its recorded RFC id:
+      lookupRfcMessageId: (id) =>
+        id === inbound.id ? (inbound.metadata.rfcMessageId as string) : undefined,
+    });
+
+    expect(out.to).toEqual([{ address: "ext@other.org" }]);
+    expect(out.subject).toBe("Re: Question");
+    expect(out.text).toBe("all good");
+    expect(out.headers.inReplyTo).toBe("<q1@other.org>");
+    expect(out.headers.references).toEqual(["<q1@other.org>"]);
+  });
+});

package/test/mail/external-id.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect, afterEach } from "vitest";
+import Database from "better-sqlite3";
+import { InMemoryStorage } from "../../src/storage/memory.js";
+import { SqliteStorage } from "../../src/storage/sqlite.js";
+import type { Storage } from "../../src/storage/interface.js";
+
+const dbs: Database.Database[] = [];
+afterEach(() => {
+  while (dbs.length) dbs.pop()!.close();
+});
+
+function sqlite(): Storage {
+  const db = new Database(":memory:");
+  dbs.push(db);
+  return new SqliteStorage({ db });
+}
+
+const impls: Array<[string, () => Storage]> = [
+  ["InMemoryStorage", () => new InMemoryStorage()],
+  ["SqliteStorage", () => sqlite()],
+];
+
+describe.each(impls)("external-id mapping (%s)", (_name, make) => {
+  it("records and looks up an external id", () => {
+    const s = make();
+    s.recordExternalId("<abc@x>", "msg-1");
+    expect(s.getMessageIdByExternalId("<abc@x>")).toBe("msg-1");
+    expect(s.hasSeenExternalId("<abc@x>")).toBe(true);
+  });
+
+  it("reports unseen ids", () => {
+    const s = make();
+    expect(s.hasSeenExternalId("<nope@x>")).toBe(false);
+    expect(s.getMessageIdByExternalId("<nope@x>")).toBeUndefined();
+  });
+
+  it("is idempotent: first mapping wins", () => {
+    const s = make();
+    s.recordExternalId("<dup@x>", "msg-1");
+    s.recordExternalId("<dup@x>", "msg-2");
+    expect(s.getMessageIdByExternalId("<dup@x>")).toBe("msg-1");
+  });
+});