carlyemail 0.6.6 → 0.7.0

package/README.md

@@ -170,12 +170,23 @@ import { createEmailHandler } from "carlyemail/webhooks";
 
 const handleEmail = createEmailHandler({
   secret: env.CARLYEMAIL_WEBHOOK_SECRET,
+  inbox: "frontdesk@carlyemail.com",
+  allowFrom: ["sam@gmail.com"],
   async onEmail(event) {
     console.log(event.message);
   },
 });
+
+export default {
+  fetch: (request, env, ctx) => handleEmail(request, env, ctx),
+};
 ```
 
+Only `message.received` reaches `onEmail`: spam, blocked and unauthenticated
+mail does not, nor does mail from the inbox itself, a sender outside
+`allowFrom`, or a redelivery. The handler answers 202 and runs `onEmail` after,
+through `ctx.waitUntil` when it is given one. A bad signature gets 401.
+
 ## Licence
 
 MIT — see `LICENSE`. That covers **this CLI only**. The CarlyEmail service it

package/carlyemail.js

@@ -18,7 +18,7 @@ import { basename, extname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { randomBytes } from "node:crypto";
 
-export const VERSION = "0.6.6";
+export const VERSION = "0.7.0";
 
 const DEFAULT_API = "https://api.carlyemail.com";
 const CONFIG_DIR = join(homedir(), ".carlyemail");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carlyemail",
-  "version": "0.6.6",
+  "version": "0.7.0",
   "description": "Real email inboxes your agent can send, receive and reply from. SDK and CLI.",
   "keywords": [
     "email",

package/webhooks.d.ts

@@ -28,8 +28,31 @@ export declare function verifyWebhook(
   options?: VerifyWebhookOptions,
 ): Promise<CarlyEmailEvent>;
 
-export declare function createEmailHandler(options: {
+export declare const RECEIVED: "message.received";
+export declare const SPAM: "message.received.spam";
+export declare const BLOCKED: "message.received.blocked";
+export declare const UNAUTHENTICATED: "message.received.unauthenticated";
+
+export interface CreateEmailHandlerOptions {
   secret: string;
   onEmail: (event: CarlyEmailEvent, request: Request) => unknown | Promise<unknown>;
+  /** The address being answered, so mail it sent itself is dropped. */
+  inbox?: string;
+  /** Who may write: `emma@example.com` or `@example.com`. Empty means anyone. */
+  allowFrom?: string[] | string;
+  /** Event types that reach `onEmail`, matched exactly. Defaults to `message.received`. */
+  eventTypes?: string[];
   toleranceSeconds?: number;
-}): (request: Request) => Promise<Response>;
+  /** Event ids held in memory to ignore redeliveries. Defaults to 2048. */
+  remember?: number;
+  /**
+   * `true` (the default) answers 202 and runs `onEmail` afterwards, handing it
+   * to a `waitUntil` found among the handler's later arguments. `false` runs it
+   * first and lets an exception become a 5xx so the delivery retries.
+   */
+  background?: boolean;
+}
+
+export declare function createEmailHandler(
+  options: CreateEmailHandlerOptions,
+): (request: Request, ...context: unknown[]) => Promise<Response>;

package/webhooks.js

@@ -81,30 +81,108 @@ export async function verifyWebhook(secret, body, headers, options = {}) {
   throw new WebhookVerificationError("webhook signature does not match");
 }
 
+// The four ways a message arrives. They are separate event types rather than a
+// flag on one type, so a subscription to RECEIVED alone never sees the other
+// three. Match them exactly: `startsWith("message.received")` is true of all
+// four, and hands spam and forged senders straight to the model.
+export const RECEIVED = "message.received";
+export const SPAM = "message.received.spam";
+export const BLOCKED = "message.received.blocked";
+export const UNAUTHENTICATED = "message.received.unauthenticated";
+
+function addressOf(from) {
+  const value = String(from ?? "").trim();
+  const angled = value.match(/<([^<>]*)>\s*$/);
+  return (angled ? angled[1] : value).trim().toLowerCase();
+}
+
 /**
  * Build a fetch-compatible handler with a Cloudflare-style `onEmail(event)`
- * callback. Handler errors are allowed through so the delivery gets a 5xx and
- * retries; only verification errors are turned into terminal 400 responses.
+ * callback, making the same decisions as the Python `create_email_router`:
+ * verify the raw body, admit only the event types asked for (exactly), drop
+ * the inbox's own mail, check the sender, ignore a redelivery, and answer the
+ * delivery before the agent runs.
+ *
+ * A model turn can outlast the delivery timeout, and a timed-out delivery is
+ * retried, so by default the handler answers 202 and runs `onEmail` after. Pass
+ * the runtime's context as a later argument (`handle(request, env, ctx)` in a
+ * Worker) and the run goes to its `waitUntil`. `background: false` runs
+ * `onEmail` first and lets an exception become a 5xx so the delivery retries.
  */
-export function createEmailHandler({ secret, onEmail, toleranceSeconds = 300 }) {
+export function createEmailHandler({
+  secret,
+  onEmail,
+  inbox = "",
+  allowFrom = [],
+  eventTypes = [RECEIVED],
+  toleranceSeconds = 300,
+  remember = 2048,
+  background = true,
+}) {
   if (!secret) throw new Error("createEmailHandler requires a webhook secret");
   if (typeof onEmail !== "function") throw new TypeError("createEmailHandler requires onEmail");
 
-  return async function handle(request) {
+  const ownAddress = inbox.toLowerCase();
+  const allowed = new Set(
+    (typeof allowFrom === "string" ? allowFrom.split(",") : allowFrom)
+      .map((entry) => entry.trim().toLowerCase())
+      .filter(Boolean),
+  );
+  const admitted = new Set(eventTypes);
+  // Bounded and in memory, so it resets with the isolate. Redeliveries cluster
+  // in the minutes after a failure, which this covers; record `event_id`
+  // somewhere durable if acting twice on one email is costly.
+  const seen = new Set();
+
+  function allows(from) {
+    if (!allowed.size) return true;
+    // Compared whole, never as a substring: `emma@example.com.attacker.net`
+    // is a domain anyone can register and sign mail from.
+    const address = addressOf(from);
+    if (!address.includes("@")) return false;
+    return allowed.has(address) || allowed.has(`@${address.split("@").pop()}`);
+  }
+
+  function firstSighting(eventId) {
+    if (seen.has(eventId)) return false;
+    seen.add(eventId);
+    if (seen.size > remember) seen.delete(seen.values().next().value);
+    return true;
+  }
+
+  return async function handle(request, ...context) {
     const body = new Uint8Array(await request.arrayBuffer());
     let event;
     try {
       event = await verifyWebhook(secret, body, request.headers, { toleranceSeconds });
     } catch (error) {
+      // 401 and nothing else: an unverified caller learns the URL exists.
       if (error instanceof WebhookVerificationError) {
-        return new Response(error.message, { status: 400 });
+        return new Response(error.message, { status: 401 });
       }
       throw error;
     }
 
-    if (event.event_type?.startsWith("message.received")) {
+    const message = event?.message;
+    if (
+      !admitted.has(event?.event_type) ||
+      typeof message !== "object" ||
+      message === null ||
+      (ownAddress && addressOf(message.from) === ownAddress) ||
+      !allows(message.from) ||
+      (event.event_id && !firstSighting(event.event_id))
+    ) {
+      return new Response(null, { status: 204 });
+    }
+
+    if (!background) {
       await onEmail(event, request);
+      return new Response(null, { status: 204 });
     }
-    return new Response(null, { status: 204 });
+    const run = Promise.resolve()
+      .then(() => onEmail(event, request))
+      .catch((error) => console.error("carlyemail: onEmail failed", error));
+    context.find((item) => typeof item?.waitUntil === "function")?.waitUntil(run);
+    return new Response(null, { status: 202 });
   };
 }