agent-inbox 0.2.2 → 0.2.4

package/dist/mail/email-mapper.js

@@ -0,0 +1,216 @@
+/**
+ * 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";
+/** Thrown when no inbound recipient resolves to a local agent. */
+export class UnknownRecipientError extends Error {
+    recipients;
+    constructor(recipients) {
+        super(`No inbound recipient resolved to a local agent: ${recipients.join(", ")}`);
+        this.recipients = recipients;
+        this.name = "UnknownRecipientError";
+    }
+}
+// ---------------------------------------------------------------------------
+// Inbound: email → Message
+// ---------------------------------------------------------------------------
+export function inboundMailToMessage(mail, ctx) {
+    const recipients = [];
+    const unresolved = [];
+    let scope;
+    const addKind = (addrs, kind) => {
+        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 = {};
+    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;
+    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, ctx) {
+    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
+        : 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
+        : 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) {
+    if (!Array.isArray(value))
+        return undefined;
+    const out = [];
+    for (const a of value) {
+        if (a &&
+            typeof a === "object" &&
+            typeof a.contentRef === "string" &&
+            typeof a.contentType === "string") {
+            const att = a;
+            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, kind) {
+    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, inReplyTo, messageId) {
+    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, ctx) {
+    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 : 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
+            : []);
+    return {
+        inReplyTo: parentRfcId,
+        references: [...parentRefs, parentRfcId],
+    };
+}
+function mintMessageId(inboxId, domain) {
+    return `<${inboxId}@${domain}>`;
+}
+function textFromContent(msg) {
+    const c = msg.content;
+    if (c.type === "text" && typeof c.text === "string")
+        return c.text;
+    return JSON.stringify(c);
+}
+function importanceFromHeaders(raw) {
+    const header = (k) => {
+        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";
+}
+//# sourceMappingURL=email-mapper.js.map

package/dist/mail/email-mapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-mapper.js","sourceRoot":"","sources":["../../src/mail/email-mapper.ts"],"names":[],"mappings":"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"}

package/dist/mail/fs-attachment-store.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Filesystem-backed AttachmentStore — opt-in for large/high-volume deployments.
+ *
+ * Keeps attachment bytes out of the SQLite DB (no WAL bloat, no synchronous
+ * blob I/O blocking the event loop). Content-addressed by sha256, so identical
+ * bytes dedup. Files live at `<dir>/<aa>/<sha256>` (sharded by the first byte
+ * to avoid one enormous directory).
+ *
+ * Durability: writes go to a unique temp file, are fsync'd, then atomically
+ * renamed into place. Because the caller stores the attachment (this `put`)
+ * BEFORE committing the message row that references it, a crash can only ever
+ * leave an orphan file (reclaimable by GC) — never a row pointing at missing
+ * bytes. See docs/MAIL-INTEROP-PLAN.md §4c.
+ */
+import type { AttachmentStore } from "./types.js";
+export declare class FsAttachmentStore implements AttachmentStore {
+    private dir;
+    constructor(dir: string);
+    put(bytes: Buffer, _meta: {
+        contentType: string;
+        filename?: string;
+    }): Promise<string>;
+    get(ref: string): Promise<Buffer>;
+    delete(ref: string): Promise<void>;
+    /**
+     * Garbage-collect orphan files: delete any stored attachment whose ref is not
+     * in `liveRefs` AND that is older than `minAgeMs` (default 1h).
+     *
+     * The age guard prevents a TOCTOU race: an attachment is `put` (file lands on
+     * disk) before the message row that references it is committed, so a just-
+     * written file may legitimately not appear in a `liveRefs` snapshot yet.
+     * Skipping recently-written files avoids deleting such in-flight attachments.
+     */
+    gc(liveRefs: Set<string>, minAgeMs?: number): Promise<number>;
+    private pathForHex;
+    private pathForRef;
+}
+//# sourceMappingURL=fs-attachment-store.d.ts.map

package/dist/mail/fs-attachment-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-attachment-store.d.ts","sourceRoot":"","sources":["../../src/mail/fs-attachment-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAIlD,qBAAa,iBAAkB,YAAW,eAAe;IAC3C,OAAO,CAAC,GAAG;gBAAH,GAAG,EAAE,MAAM;IAEzB,GAAG,CACP,KAAK,EAAE,MAAM,EACb,KAAK,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAChD,OAAO,CAAC,MAAM,CAAC;IAoCZ,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAYjC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC;;;;;;;;OAQG;IACG,EAAE,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,QAAQ,GAAE,MAAkB,GAAG,OAAO,CAAC,MAAM,CAAC;IAoC9E,OAAO,CAAC,UAAU;IAKlB,OAAO,CAAC,UAAU;CASnB"}

package/dist/mail/fs-attachment-store.js

@@ -0,0 +1,165 @@
+/**
+ * Filesystem-backed AttachmentStore — opt-in for large/high-volume deployments.
+ *
+ * Keeps attachment bytes out of the SQLite DB (no WAL bloat, no synchronous
+ * blob I/O blocking the event loop). Content-addressed by sha256, so identical
+ * bytes dedup. Files live at `<dir>/<aa>/<sha256>` (sharded by the first byte
+ * to avoid one enormous directory).
+ *
+ * Durability: writes go to a unique temp file, are fsync'd, then atomically
+ * renamed into place. Because the caller stores the attachment (this `put`)
+ * BEFORE committing the message row that references it, a crash can only ever
+ * leave an orphan file (reclaimable by GC) — never a row pointing at missing
+ * bytes. See docs/MAIL-INTEROP-PLAN.md §4c.
+ */
+import { createHash } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+const REF_RE = /^sha256:([0-9a-f]{64})$/;
+export class FsAttachmentStore {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    async put(bytes, _meta) {
+        const hex = createHash("sha256").update(bytes).digest("hex");
+        const ref = `sha256:${hex}`;
+        const full = this.pathForHex(hex);
+        // Content-addressed: if the bytes are already stored, we're done.
+        if (await exists(full))
+            return ref;
+        await fs.mkdir(path.dirname(full), { recursive: true });
+        // Atomic durable write: unique temp file → fsync → rename into place.
+        const tmp = `${full}.tmp-${process.pid}-${Date.now()}-${Math.random()
+            .toString(36)
+            .slice(2)}`;
+        let handle;
+        try {
+            handle = await fs.open(tmp, "wx");
+            await handle.writeFile(bytes);
+            await handle.sync();
+        }
+        finally {
+            await handle?.close();
+        }
+        try {
+            await fs.rename(tmp, full);
+        }
+        catch (err) {
+            // A concurrent put of identical bytes may have won the race — that's fine
+            // (same content). Clean up our temp file and return the ref.
+            await fs.rm(tmp, { force: true });
+            if (!(await exists(full)))
+                throw err;
+        }
+        // Durability: fsync the containing directory so the rename survives a crash
+        // (atomic rename alone is not crash-durable without a parent-dir fsync).
+        await fsyncDir(path.dirname(full));
+        return ref;
+    }
+    async get(ref) {
+        const full = this.pathForRef(ref);
+        try {
+            return await fs.readFile(full);
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                throw new Error(`Attachment not found: ${ref}`);
+            }
+            throw err;
+        }
+    }
+    async delete(ref) {
+        await fs.rm(this.pathForRef(ref), { force: true });
+    }
+    /**
+     * Garbage-collect orphan files: delete any stored attachment whose ref is not
+     * in `liveRefs` AND that is older than `minAgeMs` (default 1h).
+     *
+     * The age guard prevents a TOCTOU race: an attachment is `put` (file lands on
+     * disk) before the message row that references it is committed, so a just-
+     * written file may legitimately not appear in a `liveRefs` snapshot yet.
+     * Skipping recently-written files avoids deleting such in-flight attachments.
+     */
+    async gc(liveRefs, minAgeMs = 3_600_000) {
+        let removed = 0;
+        const cutoff = Date.now() - minAgeMs;
+        let shards;
+        try {
+            shards = await fs.readdir(this.dir, { withFileTypes: true });
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return 0;
+            throw err;
+        }
+        for (const shard of shards) {
+            if (!shard.isDirectory())
+                continue; // ignore stray files at the root
+            const shardDir = path.join(this.dir, shard.name);
+            let files;
+            try {
+                files = await fs.readdir(shardDir);
+            }
+            catch {
+                continue;
+            }
+            for (const name of files) {
+                if (name.includes(".tmp-"))
+                    continue; // leave in-flight temp files
+                if (liveRefs.has(`sha256:${name}`))
+                    continue;
+                const filePath = path.join(shardDir, name);
+                try {
+                    const st = await fs.stat(filePath);
+                    if (st.mtimeMs > cutoff)
+                        continue; // too new — may be mid-ingestion
+                }
+                catch {
+                    continue;
+                }
+                await fs.rm(filePath, { force: true });
+                removed++;
+            }
+        }
+        return removed;
+    }
+    pathForHex(hex) {
+        // Shard by the first byte of the hash to bound directory fan-out.
+        return path.join(this.dir, hex.slice(0, 2), hex);
+    }
+    pathForRef(ref) {
+        const m = REF_RE.exec(ref);
+        if (!m) {
+            // Strict validation prevents path traversal via a crafted ref (refs are
+            // always sha256-of-content, never caller-chosen).
+            throw new Error(`Invalid attachment ref: ${ref}`);
+        }
+        return this.pathForHex(m[1]);
+    }
+}
+async function exists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** fsync a directory so a rename into it is durable. Best-effort across platforms. */
+async function fsyncDir(dir) {
+    let handle;
+    try {
+        handle = await fs.open(dir, "r");
+        await handle.sync();
+    }
+    catch {
+        // Some platforms (e.g. Windows) don't permit fsync on a directory handle.
+        // Atomic rename still holds; this only weakens the durability guarantee.
+    }
+    finally {
+        await handle?.close().catch(() => { });
+    }
+}
+//# sourceMappingURL=fs-attachment-store.js.map

package/dist/mail/fs-attachment-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-attachment-store.js","sourceRoot":"","sources":["../../src/mail/fs-attachment-store.ts"],"names":[],"mappings":"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"}

package/dist/mail/mail-gateway.d.ts

@@ -0,0 +1,114 @@
+/**
+ * MailGateway — the only mail-aware component the rest of the system touches.
+ *
+ * Ingress: transport.onReceive → policy (size / allow-list / DMARC) → dedup →
+ * bounce-detect → map → commit via router.routeMessage (single ingestion path).
+ * The transport ACKs only after this resolves (commit-before-ACK); a throw
+ * NACKs so the sender retries.
+ *
+ * Egress: router calls send() for mail-class recipients. The message is rendered
+ * and attempted; transient failures are queued durably and retried; permanent
+ * failures (and inbound DSNs) converge on one config-gated bounce handler.
+ *
+ * See docs/MAIL-INTEROP-PLAN.md §7, §8.
+ */
+import { EventEmitter } from "node:events";
+import type { Storage } from "../storage/interface.js";
+import type { MessageRouter, MailEgress } from "../router/message-router.js";
+import { DeliveryQueue } from "../federation/delivery-queue.js";
+import type { QueueStore } from "../federation/queue-store.js";
+import type { Message, MailIdentityConfig, DeliveryQueueConfig } from "../types.js";
+import type { MailTransport, InboundMail } from "./types.js";
+export interface MailGatewayConfig {
+    identity: MailIdentityConfig;
+    /** Domains we send to without erroring; combined with identity.localDomains. */
+    routableDomains?: string[];
+    /** Override the transport's maxMessageBytes for inbound rejection. */
+    maxMessageBytes?: number;
+    /** Inbound sender allow-list (domains). Empty/undefined = allow all. */
+    allowedSenderDomains?: string[];
+    /** Drop inbound mail whose DMARC verdict is "fail". */
+    rejectDmarcFail?: boolean;
+    /** Max attachments on an inbound message before it is rejected. */
+    maxAttachments?: number;
+    /**
+     * Inbound rate limiting (abuse control). Over-limit inbound is NACKed
+     * (transient) so legitimate senders back off and retry. Disabled if unset.
+     */
+    rateLimit?: {
+        /** Sliding window, ms (default 60000). */
+        windowMs?: number;
+        /** Max inbound per sender domain per window. */
+        perSenderDomain?: number;
+        /** Max inbound across all senders per window. */
+        global?: number;
+    };
+    /** Bounce behavior; both paths default on. */
+    bounce?: {
+        emitEvent?: boolean;
+        synthesizeInboxMessage?: boolean;
+    };
+    /** Domain used to mint outbound Message-IDs (defaults to primary local domain). */
+    messageIdDomain?: string;
+    /** Default inbox scope for inbound mail without plus-addressing. */
+    defaultScope?: string;
+    /** Delivery queue config for outbound retries. */
+    queue?: Partial<DeliveryQueueConfig>;
+}
+/** Thrown to NACK over-limit inbound so the sender backs off and retries. */
+export declare class RateLimitedError extends Error {
+    readonly scope: string;
+    constructor(scope: string);
+}
+export declare class MailGateway implements MailEgress {
+    private transport;
+    private storage;
+    private router;
+    private events;
+    private config;
+    private addressBook;
+    private mailDomains;
+    private senderLimiter;
+    private globalLimiter;
+    readonly queue: DeliveryQueue;
+    private retryTimer?;
+    private retrying;
+    constructor(opts: {
+        transport: MailTransport;
+        storage: Storage;
+        router: MessageRouter;
+        events: EventEmitter;
+        config: MailGatewayConfig;
+        /** Durable queue store for outbound retries (sqlite). Memory if omitted. */
+        queueStore?: QueueStore;
+    });
+    /** Start the underlying transport and the retry/TTL timers. */
+    start(intervalMs?: number): Promise<void>;
+    stop(): Promise<void>;
+    /** True if this recipient's domain is one we route mail for. */
+    ownsRecipient(agentId: string): boolean;
+    /** Render and deliver the mail-class recipients of a message. */
+    send(message: Message): Promise<void>;
+    /**
+     * Handle one inbound message. Resolves on ACK; throws on NACK (transient
+     * failure the sender should retry). Policy rejections ACK-and-drop so the
+     * sender does not retry forever.
+     */
+    handleInbound(mail: InboundMail): Promise<void>;
+    /** Attempt delivery; classify the result and queue/bounce accordingly. */
+    private attemptDelivery;
+    /** Re-attempt all retryable queued mail. Call from a timer or deterministically. */
+    processRetries(): Promise<void>;
+    private markDelivered;
+    private handleInboundBounce;
+    private bounce;
+    /** Inject a bounce notification into the original sender's inbox. */
+    private synthesizeBounce;
+    private reject;
+    /** Throw RateLimitedError (→ NACK) when an inbound limiter is exceeded. */
+    private enforceRateLimits;
+    private senderAllowed;
+    /** Dedup key: RFC Message-ID when present, else a synthetic content hash. */
+    private externalIdFor;
+}
+//# sourceMappingURL=mail-gateway.d.ts.map

package/dist/mail/mail-gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mail-gateway.d.ts","sourceRoot":"","sources":["../../src/mail/mail-gateway.ts"],"names":[],"mappings":"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"}