agent-inbox 0.2.4 → 0.2.5

package/src/mail/provider-transport.ts

@@ -1,577 +0,0 @@
-/**
- * Postmark provider MailTransport — the managed swap-in backend.
- *
- * Proves the MailTransport contract holds for an API/webhook world (vs the
- * raw-SMTP world of SmtpTransport). The same shared contract suite validates it
- * (test/mail/mail-transport-contract.test.ts) via a harness.
- *
- * Outbound: Postmark REST API. The SDK is an optional peer dep, loaded via
- *           dynamic import; a client can also be injected (tests / custom).
- * Inbound:  Postmark webhooks POST parsed JSON. `ingestInboundWebhook` /
- *           `ingestBounceWebhook` map the payload and await the handler BEFORE
- *           the caller returns 200 (commit-before-ACK); a throw → 5xx so
- *           Postmark retries. An optional built-in HTTP listener is provided.
- *
- * The pure mapping helpers are exported for unit testing without the SDK,
- * HTTP, or network.
- */
-
-import * as http from "node:http";
-import { timingSafeEqual } from "node:crypto";
-import type {
-  MailTransport,
-  MailCapabilities,
-  MailTransportState,
-  MailHealth,
-  OutboundMail,
-  MailSendResult,
-  InboundMail,
-  InboundHandler,
-  InboundAuthResults,
-  InboundBounce,
-  MailAttachment,
-  AttachmentStore,
-} from "./types.js";
-
-const DEFAULT_MAX_BYTES = 25 * 1024 * 1024;
-
-// ---------------------------------------------------------------------------
-// Injectable client (real impl wraps the `postmark` SDK)
-// ---------------------------------------------------------------------------
-
-export interface PostmarkSendResponse {
-  ErrorCode: number;
-  MessageID?: string;
-  Message?: string;
-  SubmittedAt?: string;
-}
-
-export interface PostmarkClient {
-  sendEmail(message: Record<string, unknown>): Promise<PostmarkSendResponse>;
-}
-
-export interface PostmarkTransportOptions {
-  /** Postmark server API token. Required unless a client is injected. */
-  serverToken?: string;
-  maxMessageBytes?: number;
-  attachmentStore?: AttachmentStore;
-  /** Optional built-in webhook HTTP listener. */
-  webhook?: {
-    port: number;
-    host?: string;
-    inboundPath?: string;
-    bouncePath?: string;
-    /**
-     * Optional HTTP Basic Auth. When set, webhook requests must present
-     * matching credentials (Postmark supports basic-auth in the webhook URL),
-     * else they are rejected 401. Strongly recommended if the port is exposed.
-     */
-    basicAuth?: { user: string; pass: string };
-  };
-  /** Inject a client (tests / custom). Defaults to the postmark SDK. */
-  client?: PostmarkClient;
-}
-
-export class PostmarkTransport implements MailTransport {
-  readonly capabilities: MailCapabilities;
-  private _state: MailTransportState = "stopped";
-  private handler?: InboundHandler;
-  private client?: PostmarkClient;
-  private server?: http.Server;
-  private delivered = new Set<string>();
-  private static readonly MAX_DELIVERED = 50_000;
-
-  constructor(private opts: PostmarkTransportOptions) {
-    this.capabilities = {
-      outbound: "api",
-      signsDkim: true, // Postmark signs DKIM for verified sending domains
-      verifiesInboundAuth: true,
-      inbound: "webhook",
-      maxMessageBytes: opts.maxMessageBytes ?? DEFAULT_MAX_BYTES,
-    };
-    this.client = opts.client;
-  }
-
-  get state(): MailTransportState {
-    return this._state;
-  }
-
-  onReceive(handler: InboundHandler): void {
-    this.handler = handler;
-  }
-
-  async health(): Promise<MailHealth> {
-    return { state: this._state };
-  }
-
-  async start(): Promise<void> {
-    if (this._state === "ready") return;
-    this._state = "starting";
-    if (this.opts.webhook) await this.startHttp(this.opts.webhook);
-    this._state = "ready";
-  }
-
-  async stop(): Promise<void> {
-    this._state = "stopping";
-    if (this.server) {
-      await new Promise<void>((resolve) => this.server!.close(() => resolve()));
-      this.server = undefined;
-    }
-    this._state = "stopped";
-  }
-
-  // -- Outbound ------------------------------------------------------------
-
-  async send(envelope: OutboundMail): Promise<MailSendResult> {
-    if (this._state !== "ready") {
-      throw new Error(`send() called while transport state is "${this._state}"`);
-    }
-    if (this.delivered.has(envelope.idempotencyKey)) {
-      return {
-        disposition: "delivered",
-        remoteMessageId: envelope.headers.messageId,
-        detail: "idempotent replay",
-      };
-    }
-
-    const client = await this.getClient();
-    const contents = await this.resolveAttachmentContents(envelope);
-    try {
-      const res = await client.sendEmail(outboundToPostmark(envelope, contents));
-      const result = postmarkResponseToResult(res);
-      if (result.disposition === "delivered") {
-        this.rememberDelivered(envelope.idempotencyKey);
-      }
-      return result;
-    } catch (err) {
-      return postmarkErrorToResult(err);
-    }
-  }
-
-  /** Record a delivered idempotency key, evicting the oldest when over cap. */
-  private rememberDelivered(key: string): void {
-    if (this.delivered.size >= PostmarkTransport.MAX_DELIVERED) {
-      const oldest = this.delivered.values().next().value;
-      if (oldest !== undefined) this.delivered.delete(oldest);
-    }
-    this.delivered.add(key);
-  }
-
-  private async getClient(): Promise<PostmarkClient> {
-    if (this.client) return this.client;
-    if (!this.opts.serverToken) {
-      throw new Error("PostmarkTransport requires a serverToken or an injected client");
-    }
-    this.client = await loadPostmarkClient(this.opts.serverToken);
-    return this.client;
-  }
-
-  private async resolveAttachmentContents(
-    env: OutboundMail
-  ): Promise<Map<string, string>> {
-    const out = new Map<string, string>();
-    const store = this.opts.attachmentStore;
-    if (!store || !env.attachments?.length) return out;
-    for (const a of env.attachments) {
-      const bytes = await store.get(a.contentRef);
-      out.set(a.contentRef, bytes.toString("base64"));
-    }
-    return out;
-  }
-
-  // -- Inbound webhooks ----------------------------------------------------
-
-  /** Map + ingest a Postmark inbound webhook payload. Awaits the handler. */
-  async ingestInboundWebhook(payload: PostmarkInbound): Promise<void> {
-    const attachments = await this.storeAttachments(payload.Attachments);
-    const mail = postmarkInboundToMail(payload, { attachments });
-    await this.receiveInbound(mail);
-  }
-
-  /** Map + ingest a Postmark bounce webhook payload. Awaits the handler. */
-  async ingestBounceWebhook(payload: PostmarkBounce): Promise<void> {
-    await this.receiveInbound(postmarkBounceToInbound(payload));
-  }
-
-  /**
-   * Deliver an already-mapped inbound message to the handler (commit-before-ACK).
-   * Public so embedders using their own webhook parser can inject directly.
-   */
-  async receiveInbound(mail: InboundMail): Promise<void> {
-    if (!this.handler) throw new Error("no inbound handler registered");
-    await this.handler(mail);
-  }
-
-  private async storeAttachments(
-    atts: PostmarkInbound["Attachments"]
-  ): Promise<MailAttachment[] | undefined> {
-    const store = this.opts.attachmentStore;
-    if (!store || !atts?.length) return undefined;
-    const out: MailAttachment[] = [];
-    for (const a of atts) {
-      const bytes = Buffer.from(a.Content, "base64");
-      const ref = await store.put(bytes, {
-        contentType: a.ContentType,
-        filename: a.Name,
-      });
-      out.push({
-        filename: a.Name,
-        contentType: a.ContentType,
-        contentId: a.ContentID || undefined,
-        contentRef: ref,
-        sizeBytes: a.ContentLength ?? bytes.length,
-      });
-    }
-    return out;
-  }
-
-  // -- Built-in HTTP webhook listener (optional) ---------------------------
-
-  private async startHttp(cfg: NonNullable<PostmarkTransportOptions["webhook"]>): Promise<void> {
-    const inboundPath = cfg.inboundPath ?? "/webhooks/postmark/inbound";
-    const bouncePath = cfg.bouncePath ?? "/webhooks/postmark/bounce";
-    // Cap webhook bodies so an unauthenticated POST can't exhaust memory.
-    const maxBody = Math.max(
-      this.capabilities.maxMessageBytes * 2,
-      1 * 1024 * 1024
-    );
-    const expectedAuth = cfg.basicAuth
-      ? "Basic " +
-        Buffer.from(`${cfg.basicAuth.user}:${cfg.basicAuth.pass}`).toString(
-          "base64"
-        )
-      : undefined;
-    const server = http.createServer((req, res) => {
-      if (req.method !== "POST") {
-        res.writeHead(405).end();
-        return;
-      }
-      if (expectedAuth && !timingSafeEqualStr(req.headers.authorization, expectedAuth)) {
-        res.writeHead(401).end();
-        return;
-      }
-      const chunks: Buffer[] = [];
-      let total = 0;
-      let aborted = false;
-      req.on("data", (c) => {
-        total += c.length;
-        if (total > maxBody) {
-          aborted = true;
-          res.writeHead(413).end();
-          req.destroy();
-          return;
-        }
-        chunks.push(c);
-      });
-      req.on("end", async () => {
-        if (aborted) return;
-        let payload: unknown;
-        try {
-          payload = JSON.parse(Buffer.concat(chunks).toString("utf8"));
-        } catch {
-          res.writeHead(400).end();
-          return;
-        }
-        try {
-          if (req.url?.startsWith(bouncePath)) {
-            await this.ingestBounceWebhook(payload as PostmarkBounce);
-          } else if (req.url?.startsWith(inboundPath)) {
-            await this.ingestInboundWebhook(payload as PostmarkInbound);
-          } else {
-            res.writeHead(404).end();
-            return;
-          }
-          res.writeHead(200).end(); // ACK only after the handler committed
-        } catch {
-          res.writeHead(500).end(); // NACK — Postmark retries
-        }
-      });
-    });
-    await new Promise<void>((resolve) => {
-      this.server = server;
-      server.listen(cfg.port, cfg.host ?? "0.0.0.0", () => resolve());
-    });
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Postmark payload types (minimal structural subset)
-// ---------------------------------------------------------------------------
-
-export interface PostmarkInbound {
-  FromFull?: { Email: string; Name?: string };
-  ToFull?: Array<{ Email: string; Name?: string }>;
-  CcFull?: Array<{ Email: string; Name?: string }>;
-  OriginalRecipient?: string;
-  Subject?: string;
-  TextBody?: string;
-  HtmlBody?: string;
-  Date?: string;
-  Headers?: Array<{ Name: string; Value: string }>;
-  Attachments?: Array<{
-    Name: string;
-    Content: string; // base64
-    ContentType: string;
-    ContentLength?: number;
-    ContentID?: string;
-  }>;
-}
-
-export interface PostmarkBounce {
-  RecordType?: string;
-  Type?: string;
-  TypeCode?: number;
-  Email?: string;
-  MessageID?: string;
-  Description?: string;
-  Details?: string;
-  BouncedAt?: string;
-}
-
-// ---------------------------------------------------------------------------
-// Pure mapping helpers (exported for unit tests)
-// ---------------------------------------------------------------------------
-
-/** Classify a resolved Postmark send response. */
-export function postmarkResponseToResult(
-  res: PostmarkSendResponse
-): MailSendResult {
-  if (res.ErrorCode === 0) {
-    return { disposition: "delivered", remoteMessageId: res.MessageID };
-  }
-  // Non-zero ErrorCode in a 200 body — classify by the same code table.
-  return classifyPostmarkCode(res.ErrorCode, undefined, res.Message);
-}
-
-/** Classify a thrown Postmark error (rejected promise). */
-export function postmarkErrorToResult(err: unknown): MailSendResult {
-  const e = err as {
-    code?: number;
-    statusCode?: number;
-    message?: string;
-  };
-  return classifyPostmarkCode(e?.code, e?.statusCode, e?.message);
-}
-
-// Postmark API error codes that are permanent (won't succeed on retry).
-const PERMANENT_CODES = new Set([
-  300, // Invalid email request (bad address)
-  406, // Inactive recipient
-  409, // Malformed JSON / required field missing
-]);
-
-function classifyPostmarkCode(
-  code: number | undefined,
-  statusCode: number | undefined,
-  message?: string
-): MailSendResult {
-  // Rate limited (HTTP 429, or the in-body ErrorCode 429 "too many messages")
-  // or server-side error → transient.
-  if (statusCode === 429 || code === 429 || (statusCode && statusCode >= 500)) {
-    return { disposition: "transient", code: code ?? statusCode, detail: message };
-  }
-  // Permanent only for known non-retryable application error codes. We do NOT
-  // treat every HTTP 422 as permanent — Postmark returns 422 for transient
-  // conditions too (e.g. pending account approval), and hard-bouncing those
-  // would lose deliverable mail. Unknown codes default to transient (retry).
-  if (code !== undefined && PERMANENT_CODES.has(code)) {
-    return { disposition: "permanent", code, detail: message };
-  }
-  return { disposition: "transient", code: code ?? statusCode, detail: message };
-}
-
-/** Map an OutboundMail to a Postmark sendEmail message object. */
-export function outboundToPostmark(
-  env: OutboundMail,
-  attachmentContents?: Map<string, string>
-): Record<string, unknown> {
-  const fmt = (a: { address: string; name?: string }) =>
-    a.name ? `"${a.name}" <${a.address}>` : a.address;
-  const headers: Array<{ Name: string; Value: string }> = [
-    { Name: "Message-ID", Value: env.headers.messageId },
-  ];
-  if (env.headers.inReplyTo) {
-    headers.push({ Name: "In-Reply-To", Value: env.headers.inReplyTo });
-  }
-  if (env.headers.references?.length) {
-    headers.push({ Name: "References", Value: env.headers.references.join(" ") });
-  }
-
-  const msg: Record<string, unknown> = {
-    From: fmt(env.from),
-    To: env.to.map(fmt).join(", "),
-    Subject: env.subject ?? "",
-    TextBody: env.text,
-    HtmlBody: env.html,
-    Headers: headers,
-  };
-  if (env.cc?.length) msg.Cc = env.cc.map(fmt).join(", ");
-  if (env.bcc?.length) msg.Bcc = env.bcc.map(fmt).join(", ");
-  if (env.attachments?.length) {
-    msg.Attachments = env.attachments.map((a) => ({
-      Name: a.filename ?? "attachment",
-      ContentType: a.contentType,
-      ContentID: a.contentId,
-      Content: attachmentContents?.get(a.contentRef),
-    }));
-  }
-  return msg;
-}
-
-/** Map a Postmark inbound webhook payload to an InboundMail. */
-export function postmarkInboundToMail(
-  payload: PostmarkInbound,
-  ctx: { attachments?: MailAttachment[] } = {}
-): InboundMail {
-  const raw: Record<string, string | string[]> = {};
-  for (const h of payload.Headers ?? []) {
-    raw[h.Name.toLowerCase()] = h.Value;
-  }
-  const header = (name: string): string | undefined => raw[name.toLowerCase()] as string | undefined;
-
-  const refsHeader = header("references");
-  const references = refsHeader
-    ? refsHeader.split(/\s+/).filter(Boolean)
-    : undefined;
-
-  const from = payload.FromFull
-    ? { address: payload.FromFull.Email, name: payload.FromFull.Name }
-    : { address: "" };
-
-  const to = (payload.ToFull ?? []).map((t) => ({
-    address: t.Email,
-    name: t.Name,
-  }));
-  const cc = (payload.CcFull ?? []).map((c) => ({
-    address: c.Email,
-    name: c.Name,
-  }));
-
-  const text = payload.TextBody ?? "";
-  // Include attachment bytes so the gateway's maxMessageBytes check matches the
-  // SMTP path (which counts the full raw message), not just the body length.
-  const attachmentBytes = (payload.Attachments ?? []).reduce(
-    (sum, a) => sum + (a.ContentLength ?? Math.floor((a.Content?.length ?? 0) * 0.75)),
-    0
-  );
-  const sizeBytes =
-    Buffer.byteLength(text) +
-    Buffer.byteLength(payload.HtmlBody ?? "") +
-    attachmentBytes;
-
-  return {
-    envelopeFrom: from.address,
-    envelopeTo: payload.OriginalRecipient
-      ? [payload.OriginalRecipient]
-      : to.map((t) => t.address),
-    from,
-    to,
-    cc,
-    subject: payload.Subject,
-    text,
-    html: payload.HtmlBody || undefined,
-    headers: {
-      messageId: header("message-id"),
-      inReplyTo: header("in-reply-to"),
-      references,
-      raw,
-    },
-    attachments: ctx.attachments,
-    authResults: parseAuthResults(header("authentication-results")),
-    sizeBytes,
-    receivedAt: payload.Date
-      ? new Date(payload.Date).toISOString()
-      : new Date().toISOString(),
-  };
-}
-
-// Postmark bounce Types that mean "still might deliver" (transient/delayed).
-const DELAYED_BOUNCE_TYPES = new Set([
-  "SoftBounce",
-  "Transient",
-  "DnsError",
-  "Blocked",
-]);
-
-/** Map a Postmark bounce webhook payload to an InboundMail carrying a bounce. */
-export function postmarkBounceToInbound(payload: PostmarkBounce): InboundMail {
-  const action: InboundBounce["action"] = DELAYED_BOUNCE_TYPES.has(
-    payload.Type ?? ""
-  )
-    ? "delayed"
-    : "failed";
-  return {
-    envelopeFrom: "",
-    envelopeTo: [],
-    from: { address: payload.Email ?? "" },
-    to: [],
-    headers: { raw: {} },
-    bounce: {
-      action,
-      recipient: payload.Email ?? "",
-      status: payload.TypeCode ? String(payload.TypeCode) : undefined,
-      originalMessageId: payload.MessageID,
-      diagnostic: payload.Details ?? payload.Description,
-    },
-    sizeBytes: 0,
-    receivedAt: payload.BouncedAt
-      ? new Date(payload.BouncedAt).toISOString()
-      : new Date().toISOString(),
-  };
-}
-
-/** Best-effort parse of an Authentication-Results header into verdicts. */
-export function parseAuthResults(
-  header: string | undefined
-): InboundAuthResults | undefined {
-  if (!header) return undefined;
-  const h = header.toLowerCase();
-  const grab = (re: RegExp): string => {
-    const m = h.match(re);
-    return m ? m[1] : "none";
-  };
-  const spf = grab(/spf=(\w+)/);
-  const dkim = grab(/dkim=(\w+)/);
-  const dmarc = grab(/dmarc=(\w+)/);
-  const spfVal: InboundAuthResults["spf"] =
-    spf === "pass" || spf === "fail" || spf === "softfail" || spf === "neutral"
-      ? (spf as InboundAuthResults["spf"])
-      : "none";
-  return {
-    spf: spfVal,
-    dkim: dkim === "pass" ? "pass" : dkim === "fail" ? "fail" : "none",
-    dmarc: dmarc === "pass" ? "pass" : dmarc === "fail" ? "fail" : "none",
-  };
-}
-
-/** Constant-time string compare for the webhook Authorization header. */
-function timingSafeEqualStr(actual: string | undefined, expected: string): boolean {
-  if (!actual) return false;
-  const a = Buffer.from(actual);
-  const b = Buffer.from(expected);
-  if (a.length !== b.length) return false;
-  return timingSafeEqual(a, b);
-}
-
-// ---------------------------------------------------------------------------
-// Optional dynamic import of the postmark SDK
-// ---------------------------------------------------------------------------
-
-async function loadPostmarkClient(token: string): Promise<PostmarkClient> {
-  let mod: {
-    ServerClient?: new (t: string) => { sendEmail: PostmarkClient["sendEmail"] };
-    default?: { ServerClient?: new (t: string) => { sendEmail: PostmarkClient["sendEmail"] } };
-  };
-  try {
-    const spec = "postmark";
-    mod = await import(/* @vite-ignore */ spec);
-  } catch {
-    throw new Error(
-      'PostmarkTransport requires the optional "postmark" package. Install it to enable the Postmark backend.'
-    );
-  }
-  const ServerClient = mod.ServerClient ?? mod.default?.ServerClient;
-  if (!ServerClient) throw new Error("postmark SDK: ServerClient not found");
-  const sdk = new ServerClient(token);
-  return { sendEmail: (m) => sdk.sendEmail(m) };
-}

package/src/mail/rate-limiter.ts

@@ -1,51 +0,0 @@
-/**
- * Sliding-window rate limiter for inbound mail abuse control.
- *
- * Keyed (e.g. by sender domain or IP). `tryAcquire` returns false when the key
- * has reached `max` events within the trailing `windowMs`. Memory is bounded by
- * pruning empty keys; call `prune()` periodically for long-lived processes.
- */
-export class RateLimiter {
-  private hits = new Map<string, number[]>();
-
-  constructor(
-    private windowMs: number,
-    private max: number
-  ) {}
-
-  /** Returns true if the event is allowed (and records it), false if limited. */
-  tryAcquire(key: string, now: number = Date.now()): boolean {
-    if (this.max <= 0) return false;
-    let arr = this.hits.get(key);
-    if (!arr) {
-      arr = [];
-      this.hits.set(key, arr);
-    }
-    const cutoff = now - this.windowMs;
-    // Drop timestamps outside the window (oldest first).
-    let i = 0;
-    while (i < arr.length && arr[i] <= cutoff) i++;
-    if (i > 0) arr.splice(0, i);
-
-    if (arr.length >= this.max) return false;
-    arr.push(now);
-    return true;
-  }
-
-  /** Remove keys with no events in the current window. */
-  prune(now: number = Date.now()): void {
-    const cutoff = now - this.windowMs;
-    for (const [key, arr] of this.hits) {
-      while (arr.length && arr[0] <= cutoff) arr.shift();
-      if (arr.length === 0) this.hits.delete(key);
-    }
-  }
-
-  /** Current recorded events for a key (for tests/metrics). */
-  count(key: string, now: number = Date.now()): number {
-    const arr = this.hits.get(key);
-    if (!arr) return 0;
-    const cutoff = now - this.windowMs;
-    return arr.filter((t) => t > cutoff).length;
-  }
-}