carlyemail 0.6.6 → 0.8.0

package/README.md

@@ -80,6 +80,7 @@ npm install -g carlyemail
 | | |
 |---|---|
 | `signup --human-email <e> --username <u>` | Create an account and an inbox |
+| `send-code` | Email the owner a code to confirm the account |
 | `verify <code>` | Confirm the owner email |
 | `whoami` | Identity and scope of the current key |
 | `env` | Print `CARLYEMAIL_API_KEY` and `CARLYEMAIL_INBOX` shell exports |
@@ -170,12 +171,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.8.0";
 
 const DEFAULT_API = "https://api.carlyemail.com";
 const CONFIG_DIR = join(homedir(), ".carlyemail");
@@ -416,7 +416,17 @@ define(
     ctx.print(ok(bold(out.inbox_id)));
     ctx.print(ok(`key saved to ${saved}`));
     ctx.print("");
-    ctx.print(arrow(`check ${human_email} for a 6-digit code, then:`));
+
+    // Sign-up emails nothing by itself. The person at this terminal is the one
+    // asking, so ask for them; the key is already saved if this fails.
+    try {
+      await request(config, "POST", "/v0/agent/verification-code");
+      ctx.print(arrow(`check ${human_email} for a 6-digit code, then:`));
+    } catch {
+      ctx.print(arrow("the code did not send — try again with:"));
+      ctx.print(`    carlyemail send-code`);
+      ctx.print(arrow("then:"));
+    }
     ctx.print(`    carlyemail verify <code>`);
     ctx.print("");
     ctx.print(dim(`Until the code is confirmed the account can only email ${human_email}.`));
@@ -462,6 +472,27 @@ define("verify", "Confirm the owner email with the code", "carlyemail verify 123
   ctx.print(ok("verified — this account can send anywhere now"));
 });
 
+define(
+  "send-code",
+  "Email the owner a code to confirm the account",
+  "carlyemail send-code",
+  async (ctx) => {
+    const out = await request(ctx.config, "POST", "/v0/agent/verification-code");
+    if (out.verified) {
+      ctx.print(ok("already verified — this account can send anywhere"));
+      return;
+    }
+    ctx.print(
+      arrow(
+        out.sent
+          ? `check ${out.owner_email} for a 6-digit code, then:`
+          : `a code went to ${out.owner_email} in the last 10 minutes — use that one:`
+      )
+    );
+    ctx.print(`    carlyemail verify <code>`);
+  }
+);
+
 define("whoami", "Show the key's identity and scope", "carlyemail whoami", async (ctx) => {
   const me = await request(ctx.config, "GET", "/v0/auth/me");
   emit(ctx, me, () => {

package/package.json

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

package/sdk.d.ts

@@ -43,6 +43,15 @@ export interface AgentSignupResponse {
   organization_id: string;
   inbox_id: string;
   api_key: string;
+  verified?: boolean;
+  next_step?: string;
+}
+
+export interface AgentVerificationCodeResponse {
+  sent: boolean;
+  verified: boolean;
+  owner_email?: string | null;
+  detail: string;
 }
 
 export interface AgentVerifyRequest {
@@ -781,6 +790,7 @@ export declare class Agent {
   signUp(body: AgentSignupRequest): Promise<AgentSignupResponse>;
   signIn(body: AgentSigninRequest): Promise<AgentSigninResponse>;
   verifySignIn(body: AgentSigninVerifyRequest): Promise<AgentSigninVerifyResponse>;
+  requestVerificationCode(): Promise<AgentVerificationCodeResponse>;
   verify(body: AgentVerifyRequest): Promise<AgentVerifyResponse>;
 }
 

package/sdk.js

@@ -88,6 +88,11 @@ class Agent {
     return this.$.request("POST", `/v0/agent/sign-in/verify`, { body, auth: false });
   }
 
+  /** Request Verification Code */
+  requestVerificationCode() {
+    return this.$.request("POST", `/v0/agent/verification-code`);
+  }
+
   /** Verify */
   verify(body) {
     return this.$.request("POST", `/v0/agent/verify`, { body });

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 });
   };
 }