agent-inbox 0.2.4 → 0.2.5

package/src/federation/queue-store.ts

@@ -1,124 +0,0 @@
-/**
- * Durable persistence for the delivery queue.
- *
- * The DeliveryQueue keeps an in-memory index for fast reads and write-through
- * journals every mutation to a QueueStore. On construction it hydrates the
- * in-memory index from the store, so queued messages survive a restart.
- *
- * Two impls: the default in-memory behavior needs no store (pass none), and
- * SqliteQueueStore backs durable mode (DeliveryQueueConfig.persistence = "sqlite").
- */
-
-import type Database from "better-sqlite3";
-import type { QueuedMessage } from "../types.js";
-
-export interface QueueStore {
-  /** Insert or replace an entry. */
-  upsert(entry: QueuedMessage): void;
-  /** Remove a single entry by peer + message id. */
-  remove(peerId: string, messageId: string): void;
-  /** Remove all entries for a peer (e.g. on flush). */
-  removePeer(peerId: string): void;
-  /** Load all persisted entries (called once on hydrate). */
-  loadAll(): QueuedMessage[];
-}
-
-/** SQLite-backed durable queue store using a borrowed better-sqlite3 handle. */
-export class SqliteQueueStore implements QueueStore {
-  private table: string;
-  private upsertStmt: Database.Statement;
-  private removeStmt: Database.Statement;
-  private removePeerStmt: Database.Statement;
-  private loadStmt: Database.Statement;
-
-  /**
-   * @param db     A better-sqlite3 handle (lifecycle owned by the caller).
-   * @param prefix Table name prefix to match the Storage convention. Default "".
-   */
-  constructor(
-    private db: Database.Database,
-    prefix: string = ""
-  ) {
-    this.table = `${prefix}delivery_queue`;
-    this.migrate();
-    this.upsertStmt = this.db.prepare(
-      `INSERT INTO ${this.table}
-         (id, peer_id, message, enqueued_at, attempts, last_attempt, next_retry)
-       VALUES (@id, @peer_id, @message, @enqueued_at, @attempts, @last_attempt, @next_retry)
-       ON CONFLICT(id) DO UPDATE SET
-         peer_id = excluded.peer_id,
-         message = excluded.message,
-         enqueued_at = excluded.enqueued_at,
-         attempts = excluded.attempts,
-         last_attempt = excluded.last_attempt,
-         next_retry = excluded.next_retry`
-    );
-    this.removeStmt = this.db.prepare(
-      `DELETE FROM ${this.table} WHERE peer_id = ? AND id = ?`
-    );
-    this.removePeerStmt = this.db.prepare(
-      `DELETE FROM ${this.table} WHERE peer_id = ?`
-    );
-    this.loadStmt = this.db.prepare(
-      `SELECT id, peer_id, message, enqueued_at, attempts, last_attempt, next_retry
-         FROM ${this.table} ORDER BY enqueued_at ASC`
-    );
-  }
-
-  private migrate(): void {
-    this.db.exec(`
-      CREATE TABLE IF NOT EXISTS ${this.table} (
-        id TEXT PRIMARY KEY,
-        peer_id TEXT NOT NULL,
-        message TEXT NOT NULL,
-        enqueued_at TEXT NOT NULL,
-        attempts INTEGER NOT NULL DEFAULT 0,
-        last_attempt TEXT,
-        next_retry TEXT
-      );
-      CREATE INDEX IF NOT EXISTS ${this.table}_peer_idx
-        ON ${this.table}(peer_id);
-    `);
-  }
-
-  upsert(entry: QueuedMessage): void {
-    this.upsertStmt.run({
-      id: entry.id,
-      peer_id: entry.peerId,
-      message: JSON.stringify(entry.message),
-      enqueued_at: entry.enqueuedAt,
-      attempts: entry.attempts,
-      last_attempt: entry.lastAttempt ?? null,
-      next_retry: entry.nextRetry ?? null,
-    });
-  }
-
-  remove(peerId: string, messageId: string): void {
-    this.removeStmt.run(peerId, messageId);
-  }
-
-  removePeer(peerId: string): void {
-    this.removePeerStmt.run(peerId);
-  }
-
-  loadAll(): QueuedMessage[] {
-    const rows = this.loadStmt.all() as Array<{
-      id: string;
-      peer_id: string;
-      message: string;
-      enqueued_at: string;
-      attempts: number;
-      last_attempt: string | null;
-      next_retry: string | null;
-    }>;
-    return rows.map((r) => ({
-      id: r.id,
-      peerId: r.peer_id,
-      message: JSON.parse(r.message),
-      enqueuedAt: r.enqueued_at,
-      attempts: r.attempts,
-      lastAttempt: r.last_attempt ?? undefined,
-      nextRetry: r.next_retry ?? undefined,
-    }));
-  }
-}

package/src/mail/address-book.ts

@@ -1,111 +0,0 @@
-/**
- * Mail identity / address book.
- *
- * Maps between agent ids and external email addresses, and declares which
- * domains we own (for inbound RCPT acceptance). Plus-addressing aware:
- * `agent+scope@domain` resolves to agent `agent` in inbox scope `scope`.
- *
- * See docs/MAIL-INTEROP-PLAN.md §6.
- */
-
-import type { MailIdentityConfig } from "../types.js";
-import type { MailAddress } from "./types.js";
-
-export interface ResolvedInbound {
-  agentId: string;
-  /** Inbox scope from plus-addressing, if present. */
-  scope?: string;
-}
-
-export class AddressBook {
-  private localDomains: string[];
-  /** lower-cased address → agentId */
-  private byAddress = new Map<string, string>();
-  /** agentId → canonical address */
-  private byAgent = new Map<string, string>();
-  private catchAllAgentId?: string;
-  /** Address mappings that collided (same address → multiple agents). */
-  readonly conflicts: string[] = [];
-
-  constructor(config: MailIdentityConfig) {
-    this.localDomains = config.localDomains.map((d) => d.toLowerCase());
-    this.catchAllAgentId = config.catchAllAgentId;
-    for (const { agentId, address } of config.mappings) {
-      const lower = address.toLowerCase();
-      const existing = this.byAddress.get(lower);
-      if (existing !== undefined && existing !== agentId) {
-        // Two agents mapped to the same address — inbound routing would be
-        // ambiguous. Keep the first and record the collision for surfacing.
-        this.conflicts.push(`${address} → ${existing} & ${agentId}`);
-        continue;
-      }
-      this.byAddress.set(lower, agentId);
-      // First mapping for an agent is its canonical from-address.
-      if (!this.byAgent.has(agentId)) this.byAgent.set(agentId, address);
-    }
-  }
-
-  /** Primary local domain — used to mint Message-IDs and default from-addresses. */
-  primaryDomain(): string {
-    return this.localDomains[0] ?? "localhost";
-  }
-
-  /** True if `domain` (or a parent of it) is one we receive mail for. */
-  ownsDomain(domain: string): boolean {
-    const d = domain.toLowerCase();
-    return this.localDomains.some(
-      (own) => d === own || d.endsWith(`.${own}`)
-    );
-  }
-
-  /**
-   * Resolve an inbound recipient email to a local agent (+ scope).
-   * Returns undefined if the domain is not ours, or the mailbox is unknown and
-   * no catch-all is configured.
-   */
-  resolveInbound(address: string): ResolvedInbound | undefined {
-    const parsed = splitAddress(address);
-    if (!parsed) return undefined;
-    const { local, domain } = parsed;
-
-    if (!this.ownsDomain(domain)) return undefined;
-
-    // Plus-addressing: agent+scope → base agent, scope.
-    const plusIdx = local.indexOf("+");
-    const base = plusIdx === -1 ? local : local.slice(0, plusIdx);
-    const scope = plusIdx === -1 ? undefined : local.slice(plusIdx + 1) || undefined;
-
-    const canonical = `${base}@${domain}`.toLowerCase();
-    const agentId = this.byAddress.get(canonical);
-    if (agentId) return { agentId, scope };
-
-    if (this.catchAllAgentId) return { agentId: this.catchAllAgentId, scope };
-    return undefined;
-  }
-
-  /**
-   * Resolve the from-address for an outbound sender agent. Falls back to
-   * `<agentId>@<primaryDomain>` when the agent has no explicit mapping.
-   */
-  resolveFrom(agentId: string): MailAddress {
-    const mapped = this.byAgent.get(agentId);
-    if (mapped) return { address: mapped };
-    return { address: `${agentId}@${this.primaryDomain()}` };
-  }
-}
-
-/** Split an addr-spec into local-part and domain. Returns undefined if malformed. */
-function splitAddress(
-  address: string
-): { local: string; domain: string } | undefined {
-  const at = address.indexOf("@");
-  if (at <= 0 || at !== address.lastIndexOf("@") || at === address.length - 1) {
-    // Reject empty local/domain and unquoted multiple "@" (e.g. "a@b@c"), so
-    // this layer agrees with parseAddress (which splits on the first "@").
-    return undefined;
-  }
-  const domain = address.slice(at + 1);
-  // A domain must not contain "/" (a federation scope separator) — defensive.
-  if (domain.includes("/")) return undefined;
-  return { local: address.slice(0, at), domain };
-}

package/src/mail/attachment-store.ts

@@ -1,90 +0,0 @@
-/**
- * Attachment byte stores.
- *
- * `MailAttachment.contentRef` is opaque; bytes live behind an AttachmentStore.
- * Default impl is SQLite-backed (atomic with the message, single-file backup,
- * works with the in-memory DB used in tests). A filesystem impl is opt-in for
- * large/high-volume deployments (added later). Refs are content-addressed
- * (sha256) so identical bytes dedup. See docs/MAIL-INTEROP-PLAN.md §4c.
- */
-
-import type Database from "better-sqlite3";
-import { createHash } from "node:crypto";
-import type { AttachmentStore } from "./types.js";
-
-export class SqliteAttachmentStore implements AttachmentStore {
-  private table: string;
-  private putStmt: Database.Statement;
-  private getStmt: Database.Statement;
-  private delStmt: Database.Statement;
-
-  /**
-   * @param db     A better-sqlite3 handle (lifecycle owned by the caller).
-   * @param prefix Table name prefix to match the Storage convention. Default "".
-   */
-  constructor(
-    private db: Database.Database,
-    prefix: string = ""
-  ) {
-    this.table = `${prefix}mail_attachments`;
-    this.migrate();
-    this.putStmt = this.db.prepare(
-      `INSERT INTO ${this.table} (ref, content_type, filename, bytes, size_bytes, created_at)
-       VALUES (@ref, @content_type, @filename, @bytes, @size_bytes, @created_at)
-       ON CONFLICT(ref) DO NOTHING`
-    );
-    this.getStmt = this.db.prepare(
-      `SELECT bytes FROM ${this.table} WHERE ref = ?`
-    );
-    this.delStmt = this.db.prepare(`DELETE FROM ${this.table} WHERE ref = ?`);
-  }
-
-  private migrate(): void {
-    this.db.exec(`
-      CREATE TABLE IF NOT EXISTS ${this.table} (
-        ref TEXT PRIMARY KEY,
-        content_type TEXT NOT NULL,
-        filename TEXT,
-        bytes BLOB NOT NULL,
-        size_bytes INTEGER NOT NULL,
-        created_at TEXT NOT NULL
-      );
-    `);
-  }
-
-  async put(
-    bytes: Buffer,
-    meta: { contentType: string; filename?: string }
-  ): Promise<string> {
-    const ref = "sha256:" + createHash("sha256").update(bytes).digest("hex");
-    // ON CONFLICT DO NOTHING — content-addressed, so identical bytes are deduped.
-    this.putStmt.run({
-      ref,
-      content_type: meta.contentType,
-      filename: meta.filename ?? null,
-      bytes,
-      size_bytes: bytes.length,
-      created_at: new Date().toISOString(),
-    });
-    return ref;
-  }
-
-  async get(ref: string): Promise<Buffer> {
-    assertValidRef(ref);
-    const row = this.getStmt.get(ref) as { bytes: Buffer } | undefined;
-    if (!row) throw new Error(`Attachment not found: ${ref}`);
-    return row.bytes;
-  }
-
-  async delete(ref: string): Promise<void> {
-    assertValidRef(ref);
-    this.delStmt.run(ref);
-  }
-}
-
-/** Refs are always sha256-of-content; reject anything else (parity with FS store). */
-function assertValidRef(ref: string): void {
-  if (!/^sha256:[0-9a-f]{64}$/.test(ref)) {
-    throw new Error(`Invalid attachment ref: ${ref}`);
-  }
-}

package/src/mail/email-mapper.ts

@@ -1,288 +0,0 @@
-/**
- * Bidirectional mapping between RFC 5322 email and agent-inbox Messages.
- *
- * Parallels src/mesh/type-mapper.ts. Two pure functions:
- *   - inboundMailToMessage: external email → inbox Message
- *   - messageToOutboundMail: inbox Message → rendered OutboundMail
- *
- * Threading: RFC Message-ID / In-Reply-To / References map onto the inbox's
- * thread_tag + in_reply_to. The RFC Message-ID is preserved in metadata so a
- * later reply can reconstruct the In-Reply-To / References chain. See §5.
- */
-
-import { ulid } from "ulid";
-import { createHash } from "node:crypto";
-import { normalizeContent } from "../router/message-router.js";
-import type { Message, Recipient, RecipientKind, Importance } from "../types.js";
-import type { AddressBook } from "./address-book.js";
-import type {
-  InboundMail,
-  OutboundMail,
-  MailAddress,
-  MailAttachment,
-} from "./types.js";
-
-// ---------------------------------------------------------------------------
-// Contexts
-// ---------------------------------------------------------------------------
-
-export interface InboundMapContext {
-  addressBook: AddressBook;
-  /** Scope assigned when plus-addressing does not specify one. */
-  defaultScope?: string;
-  /**
-   * Resolve an RFC Message-ID we have already stored to its inbox Message id,
-   * so an inbound reply can set `in_reply_to` to the real parent.
-   */
-  lookupInboxIdByRfcMessageId?: (rfcMessageId: string) => string | undefined;
-}
-
-export interface OutboundMapContext {
-  addressBook: AddressBook;
-  /** Domain used to mint Message-IDs. Defaults to the address book primary domain. */
-  messageIdDomain?: string;
-  /** The RFC Message-ID we recorded when the parent inbox message was sent/received. */
-  lookupRfcMessageId?: (inboxId: string) => string | undefined;
-  /** The References chain recorded for the parent inbox message. */
-  lookupReferences?: (inboxId: string) => string[] | undefined;
-}
-
-/** Thrown when no inbound recipient resolves to a local agent. */
-export class UnknownRecipientError extends Error {
-  constructor(public readonly recipients: string[]) {
-    super(
-      `No inbound recipient resolved to a local agent: ${recipients.join(", ")}`
-    );
-    this.name = "UnknownRecipientError";
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Inbound: email → Message
-// ---------------------------------------------------------------------------
-
-export function inboundMailToMessage(
-  mail: InboundMail,
-  ctx: InboundMapContext
-): Message {
-  const recipients: Recipient[] = [];
-  const unresolved: string[] = [];
-  let scope: string | undefined;
-
-  const addKind = (addrs: MailAddress[] | undefined, kind: RecipientKind) => {
-    for (const a of addrs ?? []) {
-      const resolved = ctx.addressBook.resolveInbound(a.address);
-      if (!resolved) {
-        unresolved.push(a.address);
-        continue;
-      }
-      recipients.push({ agent_id: resolved.agentId, kind });
-      // First resolved recipient with a plus-address scope wins. "to" is
-      // processed before "cc", so a to-scope still takes precedence, but a
-      // cc-only scoped recipient is no longer silently dropped.
-      if (scope === undefined && resolved.scope) {
-        scope = resolved.scope;
-      }
-    }
-  };
-
-  addKind(mail.to, "to");
-  addKind(mail.cc, "cc");
-
-  if (recipients.length === 0) {
-    throw new UnknownRecipientError(unresolved);
-  }
-
-  const rfcMessageId = mail.headers.messageId;
-  const rfcInReplyTo = mail.headers.inReplyTo;
-  const rfcReferences = mail.headers.references;
-
-  const metadata: Record<string, unknown> = {};
-  if (rfcMessageId) metadata.rfcMessageId = rfcMessageId;
-  if (rfcInReplyTo) metadata.rfcInReplyTo = rfcInReplyTo;
-  if (rfcReferences) metadata.rfcReferences = rfcReferences;
-  if (mail.html) metadata.htmlBody = mail.html;
-  if (mail.authResults) metadata.authResults = mail.authResults;
-  if (mail.remote) metadata.remote = mail.remote;
-  if (mail.envelopeFrom) metadata.envelopeFrom = mail.envelopeFrom;
-  if (mail.bounce) metadata.bounce = mail.bounce;
-  if (mail.attachments?.length) metadata.mailAttachments = mail.attachments;
-
-  // Resolve in_reply_to to a real inbox id when we can; otherwise leave it unset
-  // (the RFC id is retained in metadata for later correlation).
-  let inReplyTo: string | undefined;
-  if (rfcInReplyTo && ctx.lookupInboxIdByRfcMessageId) {
-    inReplyTo = ctx.lookupInboxIdByRfcMessageId(rfcInReplyTo);
-  }
-
-  const text = mail.text ?? "";
-
-  return {
-    id: ulid(),
-    scope: scope ?? ctx.defaultScope ?? "default",
-    sender_id: mail.from.address,
-    recipients,
-    subject: mail.subject,
-    content: normalizeContent(text),
-    thread_tag: deriveThreadTag(rfcReferences, rfcInReplyTo, rfcMessageId),
-    in_reply_to: inReplyTo,
-    importance: importanceFromHeaders(mail.headers.raw),
-    metadata,
-    created_at: mail.receivedAt,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Outbound: Message → email
-// ---------------------------------------------------------------------------
-
-export function messageToOutboundMail(
-  msg: Message,
-  ctx: OutboundMapContext
-): OutboundMail {
-  const domain = ctx.messageIdDomain ?? ctx.addressBook.primaryDomain();
-
-  const to = recipientsOfKind(msg, "to");
-  const cc = recipientsOfKind(msg, "cc");
-  const bcc = recipientsOfKind(msg, "bcc");
-
-  const { inReplyTo, references } = buildThreadingHeaders(msg, ctx);
-
-  const text = textFromContent(msg);
-  const html = typeof msg.metadata.htmlBody === "string"
-    ? (msg.metadata.htmlBody as string)
-    : undefined;
-
-  const attachments = validateAttachments(msg.metadata.mailAttachments);
-
-  // Only forward an explicit, opt-in hints object to the backend. We do NOT
-  // dump arbitrary internal message metadata to the external mail provider.
-  const backendHints =
-    msg.metadata.mailBackendHints &&
-    typeof msg.metadata.mailBackendHints === "object"
-      ? (msg.metadata.mailBackendHints as Record<string, unknown>)
-      : undefined;
-
-  return {
-    idempotencyKey: msg.id,
-    from: ctx.addressBook.resolveFrom(msg.sender_id),
-    to,
-    ...(cc.length ? { cc } : {}),
-    ...(bcc.length ? { bcc } : {}),
-    subject: msg.subject,
-    text,
-    ...(html ? { html } : {}),
-    headers: {
-      messageId: mintMessageId(msg.id, domain),
-      ...(inReplyTo ? { inReplyTo } : {}),
-      ...(references && references.length ? { references } : {}),
-    },
-    ...(attachments ? { attachments } : {}),
-    ...(backendHints ? { backendHints } : {}),
-  };
-}
-
-/** Validate untrusted attachment metadata, dropping malformed entries. */
-function validateAttachments(value: unknown): MailAttachment[] | undefined {
-  if (!Array.isArray(value)) return undefined;
-  const out: MailAttachment[] = [];
-  for (const a of value) {
-    if (
-      a &&
-      typeof a === "object" &&
-      typeof (a as MailAttachment).contentRef === "string" &&
-      typeof (a as MailAttachment).contentType === "string"
-    ) {
-      const att = a as MailAttachment;
-      out.push({
-        contentRef: att.contentRef,
-        contentType: att.contentType,
-        sizeBytes: typeof att.sizeBytes === "number" ? att.sizeBytes : 0,
-        ...(typeof att.filename === "string" ? { filename: att.filename } : {}),
-        ...(typeof att.contentId === "string" ? { contentId: att.contentId } : {}),
-      });
-    }
-  }
-  return out.length ? out : undefined;
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-function recipientsOfKind(msg: Message, kind: RecipientKind): MailAddress[] {
-  return msg.recipients
-    .filter((r) => r.kind === kind)
-    .map((r) => ({ address: r.agent_id }));
-}
-
-/** Stable thread tag from the root of the References chain. */
-function deriveThreadTag(
-  references: string[] | undefined,
-  inReplyTo: string | undefined,
-  messageId: string | undefined
-): string | undefined {
-  const root =
-    (references && references.length > 0 ? references[0] : undefined) ??
-    inReplyTo ??
-    messageId;
-  if (!root) return undefined;
-  const hash = createHash("sha1").update(root).digest("hex").slice(0, 12);
-  return `mail-${hash}`;
-}
-
-function buildThreadingHeaders(
-  msg: Message,
-  ctx: OutboundMapContext
-): { inReplyTo?: string; references?: string[] } {
-  if (!msg.in_reply_to) {
-    // Fresh thread, but a recorded RFC References chain (e.g. from the inbound
-    // side) should still be carried if present in metadata.
-    const meta = msg.metadata.rfcReferences;
-    return { references: Array.isArray(meta) ? (meta as string[]) : undefined };
-  }
-
-  const domain = ctx.messageIdDomain ?? ctx.addressBook.primaryDomain();
-  const parentRfcId =
-    ctx.lookupRfcMessageId?.(msg.in_reply_to) ??
-    mintMessageId(msg.in_reply_to, domain);
-
-  const parentRefs =
-    ctx.lookupReferences?.(msg.in_reply_to) ??
-    (Array.isArray(msg.metadata.rfcReferences)
-      ? (msg.metadata.rfcReferences as string[])
-      : []);
-
-  return {
-    inReplyTo: parentRfcId,
-    references: [...parentRefs, parentRfcId],
-  };
-}
-
-function mintMessageId(inboxId: string, domain: string): string {
-  return `<${inboxId}@${domain}>`;
-}
-
-function textFromContent(msg: Message): string {
-  const c = msg.content;
-  if (c.type === "text" && typeof c.text === "string") return c.text;
-  return JSON.stringify(c);
-}
-
-function importanceFromHeaders(
-  raw: Record<string, string | string[]>
-): Importance {
-  const header = (k: string): string => {
-    const v = raw[k];
-    return (Array.isArray(v) ? v[0] : v ?? "").toString().toLowerCase();
-  };
-  const importance = header("importance");
-  const priority = header("x-priority");
-  if (importance === "high" || priority.startsWith("1") || priority.startsWith("2")) {
-    return "high";
-  }
-  if (importance === "low" || priority.startsWith("4") || priority.startsWith("5")) {
-    return "low";
-  }
-  return "normal";
-}