Skip to content

Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.

14.7 KB
Raw Blame
/**
 * Inbound email triggers: Amazon SES receipt rule -> SNS topic -> HTTPS subscription to
 * `POST /api/events/email/sns`.
 *
 * WHY THIS ROUTE. It is the one established inbound-mail path that works identically on AWS and on a
 * self-hosted deployment (SES receiving only needs an AWS account and an MX record, not AWS
 * hosting), needs no mailbox credentials, and is authenticated by AWS's own published signature
 * scheme rather than a secret we would have to distribute. OpenBot has no Gmail/Outlook push
 * connector to watch a mailbox with (the Workspace MCP servers are request/response only).
 *
 * Each email trigger gets its own address, `trigger-<triggerId>@<OPENBOT_INBOUND_EMAIL_DOMAIN>`; the
 * receipt rule covers the whole domain and routing happens here by the envelope recipients SES
 * reports. SNS messages are verified per AWS's documented procedure
 * (https://docs.aws.amazon.com/sns/latest/dg/sns-verify-signature-of-message.html): the signing
 * certificate is fetched only over HTTPS from an `sns.<region>.amazonaws.com` host, the canonical
 * string is rebuilt from the named fields, SignatureVersion 1 is RSA-SHA1 and 2 is RSA-SHA256, and a
 * message from any topic not in OPENBOT_INBOUND_EMAIL_SNS_TOPIC_ARNS is refused (a valid AWS
 * signature proves AWS sent it, not that it is our topic).
 */
import { createVerify, X509Certificate } from "node:crypto";
import { Hono } from "hono";
import { bodyLimit } from "hono/body-limit";
import { deliverToTrigger, type TriggerIngressDeps } from "./trigger-routes";
import { matchesFilter } from "./triggers";

export type InboundEmailConfig = { domain: string; topicArns: string[] };

/** Read from the environment by the assembly; absent means the email route is not mounted. */
export function inboundEmailConfigFromEnv(
  env: Record<string, string | undefined>,
): InboundEmailConfig | null {
  const domain = env.OPENBOT_INBOUND_EMAIL_DOMAIN?.trim().toLowerCase();
  const topicArns = (env.OPENBOT_INBOUND_EMAIL_SNS_TOPIC_ARNS ?? "")
    .split(",")
    .map((value) => value.trim())
    .filter(Boolean);
  return domain && topicArns.length ? { domain, topicArns } : null;
}

export function inboundAddressFor(triggerId: string, domain: string) {
  return `trigger-${triggerId}@${domain}`;
}

export type SnsMessage = {
  Type: "Notification" | "SubscriptionConfirmation" | "UnsubscribeConfirmation";
  MessageId: string;
  TopicArn: string;
  Message: string;
  Timestamp: string;
  SignatureVersion: string;
  Signature: string;
  SigningCertURL: string;
  Subject?: string;
  SubscribeURL?: string;
  Token?: string;
};

const SNS_HOST = /^sns\.[a-z0-9-]+\.amazonaws\.com(\.cn)?$/;
export function isSnsUrl(value: string, pem = false) {
  try {
    const url = new URL(value);
    return (
      url.protocol === "https:" &&
      SNS_HOST.test(url.hostname) &&
      !url.username &&
      !url.port &&
      (!pem || url.pathname.endsWith(".pem"))
    );
  } catch {
    return false;
  }
}

/** The canonical string AWS signs: `Name\nValue\n` pairs in byte order of the names it lists. */
export function snsStringToSign(message: SnsMessage): string | null {
  const fields =
    message.Type === "Notification"
      ? [
          "Message",
          "MessageId",
          ...(message.Subject !== undefined ? ["Subject"] : []),
          "Timestamp",
          "TopicArn",
          "Type",
        ]
      : [
          "Message",
          "MessageId",
          "SubscribeURL",
          "Timestamp",
          "Token",
          "TopicArn",
          "Type",
        ];
  let out = "";
  for (const field of fields) {
    const value = (message as Record<string, unknown>)[field];
    if (typeof value !== "string") return null;
    out += `${field}\n${value}\n`;
  }
  return out;
}

export type CertificateFetcher = (url: string) => Promise<string>;
export function createSnsVerifier(fetchCertificate: CertificateFetcher) {
  const cache = new Map<string, Promise<string>>();
  return async function verify(message: SnsMessage): Promise<boolean> {
    if (!isSnsUrl(message.SigningCertURL, true)) return false;
    const algorithm =
      message.SignatureVersion === "1"
        ? "RSA-SHA1"
        : message.SignatureVersion === "2"
          ? "RSA-SHA256"
          : null;
    const canonical = snsStringToSign(message);
    if (!algorithm || !canonical || !message.Signature) return false;
    let pending = cache.get(message.SigningCertURL);
    if (!pending) {
      pending = fetchCertificate(message.SigningCertURL);
      cache.set(message.SigningCertURL, pending);
      pending.catch(() => cache.delete(message.SigningCertURL));
      if (cache.size > 32) cache.delete(cache.keys().next().value ?? "");
    }
    const pem = await pending;
    const certificate = new X509Certificate(pem);
    if (
      !certificate.subjectAltName?.includes("amazonaws.com") &&
      !certificate.subject.includes("amazonaws.com")
    )
      return false;
    const verifier = createVerify(algorithm);
    verifier.update(canonical, "utf8");
    return verifier.verify(certificate.publicKey, message.Signature, "base64");
  };
}

/** HTTPS GET used for the certificate and for confirming the subscription. */
export const fetchText = async (url: string) => {
  const response = await fetch(url, {
    redirect: "error",
    signal: AbortSignal.timeout(10_000),
  });
  if (!response.ok)
    throw new Error(`SNS request failed with ${response.status}.`);
  return response.text();
};

function unfoldHeaders(block: string) {
  const headers = new Map<string, string>();
  for (const line of block.replace(/\r?\n[ \t]+/g, " ").split(/\r?\n/)) {
    const index = line.indexOf(":");
    if (index > 0)
      headers.set(
        line.slice(0, index).trim().toLowerCase(),
        line.slice(index + 1).trim(),
      );
  }
  return headers;
}
/**
 * The text a part's transfer-encoded bytes spell, in the charset its Content-Type names.
 *
 * Base64 and quoted-printable carry bytes, not text: a `charset=iso-8859-1` part saying "caf=E9" is
 * "café", and reading those bytes as UTF-8 turned every accented letter into U+FFFD. A charset the
 * runtime does not know falls back to UTF-8, as before.
 */
function decodeBytes(bytes: Buffer, charset: string | undefined) {
  if (charset) {
    try {
      return new TextDecoder(charset).decode(bytes);
    } catch {
      // unknown label: read as UTF-8
    }
  }
  return bytes.toString("utf8");
}
function decodeBody(
  body: string,
  encoding: string | undefined,
  charset: string | undefined,
) {
  const kind = encoding?.toLowerCase();
  if (kind === "base64")
    return decodeBytes(
      Buffer.from(body.replace(/\s+/g, ""), "base64"),
      charset,
    );
  if (kind === "quoted-printable")
    return decodeBytes(
      Buffer.from(
        body
          .replace(/=\r?\n/g, "")
          .replace(/=([0-9A-F]{2})/gi, (_, hex: string) =>
            String.fromCharCode(Number.parseInt(hex, 16)),
          ),
        "latin1",
      ),
      charset,
    );
  return body;
}
/**
 * An HTML-only mail writes `AT&amp;T` and `we&#8217;re`, and the Bot should read what the sender
 * wrote. Numeric references, the five XML names and `&nbsp;` are decoded in one pass after the tags
 * are stripped, so `&amp;lt;` reads as `&lt;` rather than as a tag, and any other name is left as
 * written.
 */
const CHARACTER_REFERENCE =
  /&(?:#(\d{1,7})|#x([0-9a-f]{1,6})|(amp|lt|gt|quot|apos|nbsp));/gi;
const NAMED_CHARACTERS: Record<string, string> = {
  amp: "&",
  lt: "<",
  gt: ">",
  quot: '"',
  apos: "'",
  nbsp: " ",
};
function decodeCharacterReference(
  reference: string,
  decimal: string | undefined,
  hex: string | undefined,
  name: string | undefined,
) {
  if (name) return NAMED_CHARACTERS[name.toLowerCase()] ?? reference;
  const code = decimal
    ? Number.parseInt(decimal, 10)
    : Number.parseInt(hex ?? "", 16);
  return code > 0 && code <= 0x10ffff && (code < 0xd800 || code > 0xdfff)
    ? String.fromCodePoint(code)
    : reference;
}
/** Minimal MIME walk: the first text/plain part, else text/html with tags stripped. */
export function extractEmailText(raw: string, depth = 0): string {
  const split = /\r?\n\r?\n/.exec(raw);
  const headers = unfoldHeaders(split ? raw.slice(0, split.index) : raw);
  const body = split ? raw.slice(split.index + split[0].length) : "";
  const type = headers.get("content-type") ?? "text/plain";
  const boundary = /boundary="?([^";]+)"?/i.exec(type)?.[1];
  if (/^multipart\//i.test(type) && boundary && depth < 5) {
    const parts = body
      .split(`--${boundary}`)
      .slice(1)
      .filter((part) => !part.startsWith("--"));
    const texts = parts.map((part) => ({
      type:
        unfoldHeaders(
          part.replace(/^\r?\n/, "").split(/\r?\n\r?\n/)[0] ?? "",
        ).get("content-type") ?? "text/plain",
      part: part.replace(/^\r?\n/, ""),
    }));
    const plain = texts.find(
      (part) =>
        /^text\/plain/i.test(part.type) || /^multipart\//i.test(part.type),
    );
    const chosen =
      plain ?? texts.find((part) => /^text\/html/i.test(part.type));
    return chosen ? extractEmailText(chosen.part, depth + 1) : "";
  }
  const decoded = decodeBody(
    body,
    headers.get("content-transfer-encoding"),
    /charset="?([^";\s]+)"?/i.exec(type)?.[1],
  );
  return /^text\/html/i.test(type)
    ? decoded
        .replace(/<style[\s\S]*?<\/style>|<script[\s\S]*?<\/script>/gi, "")
        .replace(/<[^>]+>/g, " ")
        .replace(CHARACTER_REFERENCE, decodeCharacterReference)
        .replace(/\s+/g, " ")
        .trim()
    : decoded.trim();
}

function addressOf(value: string | undefined) {
  const match = /<([^>]+)>/.exec(value ?? "");
  return (match?.[1] ?? value ?? "").trim().toLowerCase();
}
export function senderAllowed(sender: string, allowed: string[]) {
  if (allowed.length === 0) return true;
  const domain = sender.split("@")[1] ?? "";
  return allowed.some((entry) => {
    const wanted = entry.toLowerCase();
    return wanted.includes("@") ? wanted === sender : wanted === domain;
  });
}

type SesNotification = {
  notificationType?: string;
  content?: string;
  mail?: {
    messageId?: string;
    source?: string;
    timestamp?: string;
    destination?: string[];
    commonHeaders?: {
      from?: string[];
      to?: string[];
      subject?: string;
      date?: string;
    };
  };
  receipt?: {
    recipients?: string[];
    spamVerdict?: { status?: string };
    virusVerdict?: { status?: string };
    spfVerdict?: { status?: string };
    dkimVerdict?: { status?: string };
    dmarcVerdict?: { status?: string };
  };
};

export function createEmailTriggerRoutes(
  deps: TriggerIngressDeps & {
    config: InboundEmailConfig;
    verify: (message: SnsMessage) => Promise<boolean>;
    confirmSubscription: (url: string) => Promise<unknown>;
  },
) {
  const routes = new Hono();
  routes.use(
    "*",
    // SNS messages are at most 256 KiB; SES's SNS action carries mail up to 150 KB.
    bodyLimit({
      maxSize: 300 * 1024,
      onError: (context) => context.json({ error: "Too large." }, 413),
    }),
  );
  routes.onError((error, context) => {
    console.error(
      JSON.stringify({
        type: "email-trigger-error",
        errorType: error.name,
        error: error.message,
      }),
    );
    return context.json(
      { error: "The email could not be accepted. Try again." },
      503,
    );
  });
  routes.post("/sns", async (context) => {
    let message: SnsMessage;
    try {
      message = JSON.parse(await context.req.text()) as SnsMessage;
    } catch {
      return context.json({ error: "Not an SNS message." }, 400);
    }
    if (
      !message ||
      typeof message !== "object" ||
      typeof message.TopicArn !== "string"
    )
      return context.json({ error: "Not an SNS message." }, 400);
    if (!deps.config.topicArns.includes(message.TopicArn))
      return context.json({ error: "Unexpected SNS topic." }, 403);
    if (!(await deps.verify(message)))
      return context.json({ error: "Invalid SNS signature." }, 401);
    if (message.Type === "SubscriptionConfirmation") {
      if (!message.SubscribeURL || !isSnsUrl(message.SubscribeURL))
        return context.json({ error: "Unexpected SubscribeURL." }, 400);
      await deps.confirmSubscription(message.SubscribeURL);
      return context.json({ confirmed: true });
    }
    if (message.Type !== "Notification")
      return context.json({ accepted: true, queued: false });
    let notification: SesNotification;
    try {
      notification = JSON.parse(message.Message) as SesNotification;
    } catch {
      return context.json({
        accepted: true,
        queued: false,
        reason: "not an SES notification",
      });
    }
    const mail = notification.mail;
    const receipt = notification.receipt;
    if (notification.notificationType !== "Received" || !mail?.messageId)
      return context.json({
        accepted: true,
        queued: false,
        reason: "not a received email",
      });
    if (
      receipt?.virusVerdict?.status === "FAIL" ||
      receipt?.spamVerdict?.status === "FAIL"
    )
      return context.json({
        accepted: true,
        queued: false,
        reason: "spam or virus",
      });
    const pattern = new RegExp(
      `^trigger-([0-9a-f-]{36})@${deps.config.domain.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`,
      "i",
    );
    const triggerIds = [
      ...new Set(
        (receipt?.recipients ?? [])
          .map((recipient) =>
            pattern.exec(recipient.trim())?.[1]?.toLowerCase(),
          )
          .filter((id): id is string => !!id),
      ),
    ].slice(0, 10);
    const from = addressOf(mail.commonHeaders?.from?.[0] ?? mail.source);
    const authenticated =
      receipt?.dmarcVerdict?.status === "PASS" ||
      receipt?.dkimVerdict?.status === "PASS";
    const payload = {
      from,
      to: mail.commonHeaders?.to ?? mail.destination ?? [],
      subject: mail.commonHeaders?.subject ?? "",
      date: mail.commonHeaders?.date ?? mail.timestamp ?? "",
      messageId: mail.messageId,
      senderAuthenticated: authenticated,
      text: Array.from(extractEmailText(notification.content ?? ""))
        .slice(0, 16_000)
        .join(""),
    };
    const results = [];
    for (const id of triggerIds) {
      const trigger = await deps.directory.resolve(id);
      if (trigger?.config.kind !== "email") continue;
      const config = trigger.config;
      const allowed =
        config.allowedSenders.length === 0 ||
        (authenticated && senderAllowed(from, config.allowedSenders));
      results.push(
        await deliverToTrigger(
          deps,
          trigger,
          { deliveryId: mail.messageId, type: "received", payload },
          allowed && matchesFilter(config.filter, "received", payload),
        ),
      );
    }
    // SNS retries anything but 2xx, so an unrouted or filtered mail is still acknowledged.
    return context.json({ accepted: true, deliveries: results.length });
  });
  return routes;
}