agent-inbox 0.2.4 → 0.2.5

package/src/mail/types.ts

@@ -1,221 +0,0 @@
-/**
- * Mail interop type contract.
- *
- * Defines the `MailTransport` interface and its envelope types — the backend-
- * agnostic contract every mail backend (self-hosted SMTP, managed provider)
- * must satisfy. See docs/MAIL-INTEROP-PLAN.md for the design rationale.
- *
- * Phase 1 lands the types only; no backend, gateway, or router wiring yet.
- */
-
-// ---------------------------------------------------------------------------
-// Capabilities & lifecycle
-// ---------------------------------------------------------------------------
-
-/** What a backend can do. The gateway adapts to these instead of assuming. */
-export interface MailCapabilities {
-  /**
-   * How outbound mail leaves: direct to arbitrary public MX (self-hosted SMTP),
-   * via a configured smarthost relay, or via the backend's own API. Informational.
-   */
-  outbound: "mx" | "relay" | "api";
-  /** Backend signs DKIM itself (provider) or we must sign before handing off. */
-  signsDkim: boolean;
-  /** Backend verifies SPF/DKIM/DMARC on inbound and reports results. */
-  verifiesInboundAuth: boolean;
-  /** Inbound arrives via a long-lived listener (SMTP) or a push webhook. */
-  inbound: "listener" | "webhook" | "none";
-  /** Max message size the backend will accept, bytes. */
-  maxMessageBytes: number;
-}
-
-export type MailTransportState =
-  | "stopped"
-  | "starting"
-  | "ready"
-  | "degraded"
-  | "stopping";
-
-export interface MailHealth {
-  state: MailTransportState;
-  /** Human-readable detail for health endpoints / logs. */
-  detail?: string;
-}
-
-// ---------------------------------------------------------------------------
-// Addresses & attachments
-// ---------------------------------------------------------------------------
-
-export interface MailAddress {
-  /** RFC 5322 addr-spec, e.g. "bob@example.com". */
-  address: string;
-  /** Optional display name. */
-  name?: string;
-}
-
-export interface MailAttachment {
-  filename?: string;
-  contentType: string;
-  /** Content-ID for inline html parts. */
-  contentId?: string;
-  /** Opaque handle into an AttachmentStore — the envelope carries a ref, not bytes. */
-  contentRef: string;
-  sizeBytes: number;
-}
-
-// ---------------------------------------------------------------------------
-// Outbound
-// ---------------------------------------------------------------------------
-
-export interface OutboundMail {
-  /** Stable key for idempotent send. Derived from the inbox Message.id. */
-  idempotencyKey: string;
-  from: MailAddress;
-  to: MailAddress[];
-  cc?: MailAddress[];
-  bcc?: MailAddress[];
-  subject?: string;
-  /** Rendered bodies. At least one of text/html should be present. */
-  text?: string;
-  html?: string;
-  /** RFC 5322 threading headers, already computed by the mapper. */
-  headers: {
-    messageId: string;
-    inReplyTo?: string;
-    references?: string[];
-  };
-  attachments?: MailAttachment[];
-  /** Opaque passthrough for backend-specific knobs (provider tags, etc.). */
-  backendHints?: Record<string, unknown>;
-}
-
-export type MailSendDisposition = "delivered" | "transient" | "permanent";
-
-/**
- * Result of a send attempt. Backends collapse their native failure modes into
- * these three dispositions so the retry/queue layer needs no backend knowledge.
- */
-export interface MailSendResult {
-  disposition: MailSendDisposition;
-  /** Provider/SMTP id when delivered, for correlating DSNs/bounces. */
-  remoteMessageId?: string;
-  /** Numeric SMTP-style code when available (e.g. 250, 451, 550). */
-  code?: number;
-  /** Human-readable, for logs only — never parsed for control flow. */
-  detail?: string;
-  /** For transient failures: hint for next attempt (e.g. greylist retry-after). */
-  retryAfterMs?: number;
-}
-
-// ---------------------------------------------------------------------------
-// Inbound
-// ---------------------------------------------------------------------------
-
-export interface InboundAuthResults {
-  spf: "pass" | "fail" | "softfail" | "neutral" | "none";
-  dkim: "pass" | "fail" | "none";
-  dmarc: "pass" | "fail" | "none";
-}
-
-/**
- * Bounce/DSN classification, parsed from RFC 3464 delivery-status reports.
- * Present when an inbound message is a bounce, so the gateway can correlate it
- * to the failed outbound send instead of treating it as a fresh message.
- */
-export interface InboundBounce {
-  /** "failed" (permanent), "delayed" (transient), "delivered" (positive DSN). */
-  action: "failed" | "delayed" | "delivered";
-  /** The address that bounced. */
-  recipient: string;
-  /** RFC 3463 status code, e.g. "5.1.1". */
-  status?: string;
-  /** Message-ID of the original outbound mail, when the DSN echoes it. */
-  originalMessageId?: string;
-  diagnostic?: string;
-}
-
-export interface InboundMail {
-  /** Peer-asserted SMTP envelope (MAIL FROM / RCPT TO), distinct from headers. */
-  envelopeFrom: string;
-  envelopeTo: string[];
-  from: MailAddress;
-  to: MailAddress[];
-  cc?: MailAddress[];
-  subject?: string;
-  text?: string;
-  html?: string;
-  headers: {
-    messageId?: string;
-    inReplyTo?: string;
-    references?: string[];
-    /** Everything else, lower-cased keys, for the mapper to mine. */
-    raw: Record<string, string | string[]>;
-  };
-  attachments?: MailAttachment[];
-  /** Auth verdict — present iff capabilities.verifiesInboundAuth. */
-  authResults?: InboundAuthResults;
-  /** Peer IP / hostname, for allow-listing and abuse control. */
-  remote?: { ip?: string; reverseDns?: string };
-  /** Set when this inbound mail is a bounce/DSN (see InboundBounce). */
-  bounce?: InboundBounce;
-  sizeBytes: number;
-  receivedAt: string; // ISO
-}
-
-// ---------------------------------------------------------------------------
-// The transport contract
-// ---------------------------------------------------------------------------
-
-/**
- * Ingress handler. The transport awaits this; resolution means "durably
- * accepted" and only then is the peer MTA / webhook ACKed. A thrown handler
- * means NACK so the sender retries — never a silent drop.
- */
-export type InboundHandler = (mail: InboundMail) => Promise<void>;
-
-export interface MailTransport {
-  readonly capabilities: MailCapabilities;
-  readonly state: MailTransportState;
-
-  /**
-   * Idempotent. Resolves only when inbound is actually accepting (port bound /
-   * webhook registered) so callers don't ACK before we can receive.
-   */
-  start(): Promise<void>;
-
-  /** Graceful: stop accepting new inbound, finish in-flight, then release. */
-  stop(): Promise<void>;
-
-  /**
-   * Send one already-rendered outbound message.
-   * MUST be idempotent on `envelope.idempotencyKey`.
-   * MUST NOT throw for delivery failures — return a classified result instead.
-   * MAY throw only for programmer error (e.g. called while stopped).
-   */
-  send(envelope: OutboundMail): Promise<MailSendResult>;
-
-  /** Register the single ingress handler. See InboundHandler. */
-  onReceive(handler: InboundHandler): void;
-
-  /** Liveness for health endpoints and the degraded → ready transition. */
-  health(): Promise<MailHealth>;
-}
-
-// ---------------------------------------------------------------------------
-// Attachment storage (opaque contentRef backing store)
-// ---------------------------------------------------------------------------
-
-/**
- * Swappable attachment byte store. `contentRef` values on MailAttachment are
- * opaque handles produced by `put`. Mirrors the Storage two-impl pattern:
- * SqliteAttachmentStore (default) and FsAttachmentStore (opt-in) land later.
- */
-export interface AttachmentStore {
-  /** Returns a content-addressed ref (sha256-based). Dedups identical bytes. */
-  put(
-    bytes: Buffer,
-    meta: { contentType: string; filename?: string }
-  ): Promise<string>;
-  get(ref: string): Promise<Buffer>;
-  delete(ref: string): Promise<void>;
-}

package/src/router/destination.ts

@@ -1,140 +0,0 @@
-/**
- * Destination classification.
- *
- * Email addresses are syntactically identical to federation addresses
- * (`bob@example.com` vs `bob@system-2`), so before routing we must classify a
- * recipient as one of: local agent, federation peer, or external mail.
- *
- * Classification is explicit-list driven — nothing is guessed from "looks like
- * a domain". An unknown `@x` is a hard error rather than a silent misroute.
- * Federation peers may declare their own domains, in which case they win over
- * mail config for that domain. See docs/MAIL-INTEROP-PLAN.md §1.
- *
- * This layer sits *above* `parseAddress`, which is left untouched.
- */
-
-import { parseAddress } from "../federation/address.js";
-import type { FederatedAddress } from "../types.js";
-
-export type Destination =
-  | { class: "local"; agentId: string }
-  | { class: "federation"; agentId: string; address: FederatedAddress }
-  | { class: "mail"; email: string };
-
-export interface DestinationPeer {
-  systemId: string;
-  /** Dotted addresses routed to this peer instead of being treated as mail. */
-  domains?: string[];
-}
-
-export interface DestinationContext {
-  /** Returns true if `id` is a known local agent. */
-  isLocalAgent: (id: string) => boolean;
-  /** Configured federation peers (system ids + optionally declared domains). */
-  federationPeers: DestinationPeer[];
-  /** Mail domains we recognize (identity.localDomains ∪ routableDomains). */
-  mailDomains: string[];
-}
-
-/** Thrown when a recipient matches neither a federation peer nor a mail domain. */
-export class UnknownDestinationError extends Error {
-  constructor(public readonly agentId: string) {
-    super(
-      `Cannot classify destination "${agentId}": its domain is not a configured ` +
-        `federation peer or mail domain. Declare it explicitly to route it.`
-    );
-    this.name = "UnknownDestinationError";
-  }
-}
-
-/**
- * Classify a recipient address into local / federation / mail.
- *
- * Priority order (deterministic):
- *   1. No `@`                                  → local
- *   2. `@x` matches a peer systemId or domain  → federation
- *   3. `@x` (or parent domain) in mailDomains  → mail
- *   4. otherwise                               → throw UnknownDestinationError
- *
- * @throws UnknownDestinationError for rule-4 misses.
- */
-export function classifyDestination(
-  agentId: string,
-  ctx: DestinationContext
-): Destination {
-  const atIdx = agentId.indexOf("@");
-
-  // Rule 1: no @ — local agent (no domain to disambiguate).
-  if (atIdx === -1) {
-    return { class: "local", agentId };
-  }
-
-  const addr = parseAddress(agentId);
-  const system = addr.system; // the part after @ (before any /scope)
-
-  // Defensive: parseAddress yielded no system (e.g. trailing-only @) — treat
-  // the whole string as a local agent id rather than guessing a domain.
-  if (!system) {
-    return { class: "local", agentId };
-  }
-
-  // Rule 2: federation peer by systemId or declared domain (wins over mail).
-  for (const peer of ctx.federationPeers) {
-    if (peer.systemId === system || domainMatches(system, peer.domains)) {
-      return { class: "federation", agentId, address: addr };
-    }
-  }
-
-  // Rule 3: configured mail domain (exact or parent-domain suffix match).
-  if (domainMatches(system, ctx.mailDomains)) {
-    return { class: "mail", email: stripScope(agentId) };
-  }
-
-  // Rule 4: explicit-list miss — never guess.
-  throw new UnknownDestinationError(agentId);
-}
-
-/**
- * True if `domain` equals, or is a subdomain of, any entry in `candidates`.
- * Matching is case-insensitive. `mail.example.com` matches a candidate of
- * `example.com`; `notexample.com` does not match `example.com`.
- */
-export function domainMatches(
-  domain: string,
-  candidates: string[] | undefined
-): boolean {
-  if (!candidates || candidates.length === 0) return false;
-  const d = domain.toLowerCase();
-  for (const c of candidates) {
-    const cand = c.toLowerCase();
-    if (d === cand || d.endsWith(`.${cand}`)) return true;
-  }
-  return false;
-}
-
-/**
- * Drop a trailing `/scope` qualifier from an address, leaving a bare email.
- * `bob@example.com/work` → `bob@example.com`.
- */
-function stripScope(agentId: string): string {
-  const atIdx = agentId.indexOf("@");
-  if (atIdx === -1) return agentId;
-  const slashIdx = agentId.indexOf("/", atIdx);
-  return slashIdx === -1 ? agentId : agentId.slice(0, slashIdx);
-}
-
-/**
- * Detect domains claimed by both a federation peer and mail config. Federation
- * wins (see classifyDestination), but callers should surface this at startup
- * via a `mail.config.conflict` warning. Returns the conflicting domains.
- */
-export function findDomainConflicts(ctx: DestinationContext): string[] {
-  const mail = new Set(ctx.mailDomains.map((d) => d.toLowerCase()));
-  const conflicts: string[] = [];
-  for (const peer of ctx.federationPeers) {
-    for (const dom of peer.domains ?? []) {
-      if (mail.has(dom.toLowerCase())) conflicts.push(dom);
-    }
-  }
-  return conflicts;
-}

package/test/federation/delivery-queue-sqlite.test.ts

@@ -1,158 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
-import { EventEmitter } from "node:events";
-import Database from "better-sqlite3";
-import { DeliveryQueue } from "../../src/federation/delivery-queue.js";
-import { SqliteQueueStore } from "../../src/federation/queue-store.js";
-import type { DeliveryQueueConfig, Message } from "../../src/types.js";
-
-function makeMessage(id: string): Message {
-  return {
-    id,
-    scope: "default",
-    sender_id: "sender",
-    recipients: [{ agent_id: "remote@peer", kind: "to" }],
-    content: { type: "text", text: `msg-${id}` },
-    importance: "normal",
-    metadata: {},
-    created_at: new Date().toISOString(),
-  };
-}
-
-const baseConfig: DeliveryQueueConfig = {
-  persistence: "sqlite",
-  maxTTL: 10_000,
-  maxQueueSize: 3,
-  retryStrategy: "exponential",
-  retryBaseInterval: 100,
-  retryMaxAttempts: 0,
-  flushOnReconnect: true,
-  overflow: "drop-oldest",
-};
-
-describe("DeliveryQueue (sqlite persistence)", () => {
-  let db: Database.Database;
-  let events: EventEmitter;
-
-  beforeEach(() => {
-    db = new Database(":memory:");
-    events = new EventEmitter();
-  });
-
-  afterEach(() => {
-    db.close();
-  });
-
-  function makeQueue(config: Partial<DeliveryQueueConfig> = {}) {
-    return new DeliveryQueue(
-      events,
-      { ...baseConfig, ...config },
-      { store: new SqliteQueueStore(db) }
-    );
-  }
-
-  it("persists enqueued messages to the store", () => {
-    const q = makeQueue();
-    q.enqueue("peer-1", makeMessage("m1"));
-    q.enqueue("peer-1", makeMessage("m2"));
-
-    const rows = db.prepare("SELECT * FROM delivery_queue").all();
-    expect(rows).toHaveLength(2);
-  });
-
-  it("survives a restart by hydrating from the store", () => {
-    const q1 = makeQueue();
-    q1.enqueue("peer-1", makeMessage("m1"));
-    q1.enqueue("peer-2", makeMessage("m2"));
-    expect(q1.totalSize()).toBe(2);
-
-    // Simulate restart: new queue + new store over the same db handle.
-    const q2 = new DeliveryQueue(events, baseConfig, {
-      store: new SqliteQueueStore(db),
-    });
-    expect(q2.totalSize()).toBe(2);
-    expect(q2.size("peer-1")).toBe(1);
-    expect(q2.size("peer-2")).toBe(1);
-    expect(q2.peers().sort()).toEqual(["peer-1", "peer-2"]);
-  });
-
-  it("removes entries from the store on removeEntry", () => {
-    const q = makeQueue();
-    const id = q.enqueue("peer-1", makeMessage("m1"))!;
-    q.removeEntry("peer-1", id);
-
-    expect(db.prepare("SELECT * FROM delivery_queue").all()).toHaveLength(0);
-  });
-
-  it("clears the store for a peer on flush", () => {
-    const q = makeQueue();
-    q.enqueue("peer-1", makeMessage("m1"));
-    q.enqueue("peer-1", makeMessage("m2"));
-    q.flush("peer-1");
-
-    expect(
-      db.prepare("SELECT * FROM delivery_queue WHERE peer_id = ?").all("peer-1")
-    ).toHaveLength(0);
-  });
-
-  it("drops the oldest entry from the store on overflow", () => {
-    const q = makeQueue({ maxQueueSize: 2, overflow: "drop-oldest" });
-    q.enqueue("peer-1", makeMessage("m1"));
-    q.enqueue("peer-1", makeMessage("m2"));
-    q.enqueue("peer-1", makeMessage("m3")); // evicts m1
-
-    const messages = (
-      db.prepare("SELECT message FROM delivery_queue").all() as Array<{
-        message: string;
-      }>
-    ).map((r) => JSON.parse(r.message).id);
-    expect(messages.sort()).toEqual(["m2", "m3"]);
-  });
-
-  it("updates attempt/next-retry state in the store on recordAttempt", () => {
-    const q = makeQueue({ retryMaxAttempts: 5 });
-    const id = q.enqueue("peer-1", makeMessage("m1"))!;
-    q.recordAttempt("peer-1", id);
-
-    const row = db
-      .prepare("SELECT attempts, next_retry FROM delivery_queue WHERE id = ?")
-      .get(id) as { attempts: number; next_retry: string | null };
-    expect(row.attempts).toBe(1);
-    expect(row.next_retry).toBeTruthy();
-  });
-
-  it("removes the entry from the store when max attempts are exceeded", () => {
-    const q = makeQueue({ retryMaxAttempts: 1 });
-    const id = q.enqueue("peer-1", makeMessage("m1"))!;
-    const kept = q.recordAttempt("peer-1", id);
-    expect(kept).toBe(false);
-    expect(db.prepare("SELECT * FROM delivery_queue").all()).toHaveLength(0);
-  });
-
-  it("removes expired entries from the store on tick", () => {
-    const q = makeQueue({ maxTTL: -1 }); // everything is immediately expired
-    q.enqueue("peer-1", makeMessage("m1"));
-    const expired = q.tick();
-    expect(expired).toBe(1);
-    expect(db.prepare("SELECT * FROM delivery_queue").all()).toHaveLength(0);
-  });
-
-  it("round-trips the full message payload through the store", () => {
-    const q1 = makeQueue();
-    const msg = makeMessage("m1");
-    msg.subject = "hello";
-    msg.thread_tag = "thread-xyz";
-    q1.enqueue("peer-1", msg);
-
-    const q2 = new DeliveryQueue(events, baseConfig, {
-      store: new SqliteQueueStore(db),
-    });
-    const flushed = q2.flush("peer-1");
-    expect(flushed).toHaveLength(1);
-    expect(flushed[0].message.subject).toBe("hello");
-    expect(flushed[0].message.thread_tag).toBe("thread-xyz");
-    expect(flushed[0].message.content).toEqual({
-      type: "text",
-      text: "msg-m1",
-    });
-  });
-});

package/test/mail/address-book.test.ts

@@ -1,111 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { AddressBook } from "../../src/mail/address-book.js";
-
-function book(): AddressBook {
-  return new AddressBook({
-    localDomains: ["example.com", "agents.example.com"],
-    mappings: [
-      { agentId: "alice", address: "alice@example.com" },
-      { agentId: "bob", address: "bob@example.com" },
-    ],
-    catchAllAgentId: undefined,
-  });
-}
-
-describe("AddressBook", () => {
-  it("reports the primary domain", () => {
-    expect(book().primaryDomain()).toBe("example.com");
-  });
-
-  it("recognizes owned domains and subdomains", () => {
-    const b = book();
-    expect(b.ownsDomain("example.com")).toBe(true);
-    expect(b.ownsDomain("mail.example.com")).toBe(true);
-    expect(b.ownsDomain("agents.example.com")).toBe(true);
-    expect(b.ownsDomain("notexample.com")).toBe(false);
-    expect(b.ownsDomain("other.org")).toBe(false);
-  });
-
-  it("resolves a known inbound mailbox to its agent", () => {
-    expect(book().resolveInbound("bob@example.com")).toEqual({
-      agentId: "bob",
-      scope: undefined,
-    });
-  });
-
-  it("is case-insensitive on the mailbox", () => {
-    expect(book().resolveInbound("ALICE@Example.com")?.agentId).toBe("alice");
-  });
-
-  it("extracts scope from plus-addressing", () => {
-    expect(book().resolveInbound("alice+urgent@example.com")).toEqual({
-      agentId: "alice",
-      scope: "urgent",
-    });
-  });
-
-  it("returns undefined for a foreign domain", () => {
-    expect(book().resolveInbound("alice@other.org")).toBeUndefined();
-  });
-
-  it("returns undefined for an unknown mailbox without catch-all", () => {
-    expect(book().resolveInbound("ghost@example.com")).toBeUndefined();
-  });
-
-  it("routes unknown mailboxes to catch-all when configured", () => {
-    const b = new AddressBook({
-      localDomains: ["example.com"],
-      mappings: [],
-      catchAllAgentId: "triage",
-    });
-    expect(b.resolveInbound("anyone@example.com")).toEqual({
-      agentId: "triage",
-      scope: undefined,
-    });
-  });
-
-  it("resolves a mapped agent's from-address", () => {
-    expect(book().resolveFrom("alice")).toEqual({ address: "alice@example.com" });
-  });
-
-  it("falls back to agentId@primaryDomain for an unmapped agent", () => {
-    expect(book().resolveFrom("ghost")).toEqual({
-      address: "ghost@example.com",
-    });
-  });
-
-  it("ignores malformed addresses", () => {
-    expect(book().resolveInbound("not-an-email")).toBeUndefined();
-    expect(book().resolveInbound("@example.com")).toBeUndefined();
-    expect(book().resolveInbound("foo@")).toBeUndefined();
-  });
-
-  it("rejects addresses with multiple @ (consistent with parseAddress)", () => {
-    expect(book().resolveInbound("a@b@example.com")).toBeUndefined();
-    expect(book().resolveInbound("alice@example.com@evil.com")).toBeUndefined();
-  });
-
-  it("records duplicate-address mapping conflicts and keeps the first", () => {
-    const b = new AddressBook({
-      localDomains: ["example.com"],
-      mappings: [
-        { agentId: "alice", address: "shared@example.com" },
-        { agentId: "bob", address: "shared@example.com" },
-      ],
-    });
-    expect(b.resolveInbound("shared@example.com")?.agentId).toBe("alice");
-    expect(b.conflicts).toHaveLength(1);
-    expect(b.conflicts[0]).toContain("shared@example.com");
-  });
-
-  it("does not flag a repeated identical (agent,address) pair as a conflict", () => {
-    const b = new AddressBook({
-      localDomains: ["example.com"],
-      mappings: [
-        { agentId: "alice", address: "alice@example.com" },
-        { agentId: "alice", address: "alice@example.com" },
-      ],
-    });
-    expect(b.conflicts).toHaveLength(0);
-  });
-});