@aidalinfo/email-mcp 0.1.0 → 0.2.0

package/dist/clients.js

@@ -0,0 +1,144 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import { HARD_MAX_PER_DAY, HARD_MAX_PER_HOUR, parseAllowlist } from "./config.js";
+export const CLIENT_ID_RE = /^[a-z0-9][a-z0-9_.-]{0,63}$/;
+const KEY_HASH_RE = /^sha256:[0-9a-f]{64}$/;
+/** What a client key looks like: `emk_` + 43 base64url characters (256 random bits). */
+export const CLIENT_KEY_RE = /^emk_[A-Za-z0-9_-]{43}$/;
+export const hashKey = (key) => createHash("sha256").update(key).digest("hex");
+/** A new client key and the line to put in the clients file. The key is shown once, the file keeps its hash only. */
+export function generateKey() {
+    const key = `emk_${randomBytes(32).toString("base64url")}`;
+    return { key, hash: `sha256:${hashKey(key)}` };
+}
+/**
+ * Clients JSON (EMAIL_MCP_CLIENTS_FILE or EMAIL_MCP_CLIENTS): a list of
+ * `{ "id", "keys": ["sha256:<hex>", …], "maxPerHour"?, "maxPerDay"?, "allowedRecipients"?, "templatesOnly"?, "disabled"? }`.
+ * Several keys per client allow a rotation without downtime. Only hashes are stored.
+ */
+export function parseClients(raw, config) {
+    let list;
+    try {
+        list = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("clients: not valid JSON");
+    }
+    if (!Array.isArray(list))
+        throw new Error("clients: expected a JSON list");
+    const seenKeys = new Set();
+    const out = [];
+    for (const c of list) {
+        const id = c?.id;
+        if (typeof id !== "string" || !CLIENT_ID_RE.test(id))
+            throw new Error("clients: each client needs an id matching [a-z0-9_.-], 64 characters max");
+        if (out.some((x) => x.id === id))
+            throw new Error(`clients: duplicate id "${id}"`);
+        if (!Array.isArray(c.keys) || !c.keys.length)
+            throw new Error(`clients[${id}]: keys must list at least one "sha256:<hex>" hash`);
+        const keyHashes = c.keys.map((k) => {
+            if (typeof k !== "string" || !KEY_HASH_RE.test(k))
+                throw new Error(`clients[${id}]: keys must be "sha256:<64 hex>" hashes, never raw keys`);
+            if (seenKeys.has(k))
+                throw new Error(`clients[${id}]: a key hash is used twice`);
+            seenKeys.add(k);
+            return Buffer.from(k.slice(7), "hex");
+        });
+        const limit = (v, name, def, max) => {
+            if (v === undefined)
+                return def;
+            if (!Number.isInteger(v) || v < 1 || v > max)
+                throw new Error(`clients[${id}]: ${name} must be an integer 1..${max}`);
+            return Math.min(v, def);
+        };
+        let allowlist;
+        if (c.allowedRecipients !== undefined) {
+            if (typeof c.allowedRecipients !== "string")
+                throw new Error(`clients[${id}]: allowedRecipients must be a string like "a@x.fr,@domain.fr"`);
+            allowlist = parseAllowlist(c.allowedRecipients, `clients[${id}].allowedRecipients`);
+            if (!allowlist.addresses.size && !allowlist.domains.size)
+                throw new Error(`clients[${id}]: allowedRecipients is empty — remove it to use the server allowlist`);
+        }
+        out.push({
+            id,
+            keyHashes,
+            // a client limit can only lower the server-wide one
+            maxPerHour: limit(c.maxPerHour, "maxPerHour", config.maxPerHour, HARD_MAX_PER_HOUR),
+            maxPerDay: limit(c.maxPerDay, "maxPerDay", config.maxPerDay, HARD_MAX_PER_DAY),
+            allowlist,
+            templatesOnly: c.templatesOnly === true,
+            disabled: c.disabled === true,
+        });
+    }
+    if (!out.some((c) => !c.disabled))
+        throw new Error("clients: no enabled client — the server would refuse every request");
+    return out;
+}
+/**
+ * Bearer authentication against the clients list. The file is re-read when it changes, so a key
+ * is added, rotated or revoked without restart; while it is unreadable or invalid every request is
+ * refused (fail-closed) rather than served with a stale list.
+ */
+export class ClientRegistry {
+    source;
+    config;
+    warn;
+    clients = [];
+    mtime = -1;
+    broken;
+    constructor(source, config, warn = (m) => process.stderr.write(`${m}\n`)) {
+        this.source = source;
+        this.config = config;
+        this.warn = warn;
+        if (!source.file && !source.inline)
+            throw new Error("Missing client keys: set EMAIL_MCP_CLIENTS_FILE (or EMAIL_MCP_CLIENTS) — see `email-mcp keygen`");
+        if (source.file)
+            this.reload(true);
+        else
+            this.clients = parseClients(source.inline, config);
+    }
+    reload(strict = false) {
+        const file = this.source.file;
+        try {
+            const m = statSync(file).mtimeMs;
+            if (m === this.mtime && !this.broken)
+                return;
+            this.clients = parseClients(readFileSync(file, "utf-8"), this.config);
+            this.mtime = m;
+            if (this.broken)
+                this.warn(`clients file ${file} is valid again`);
+            this.broken = undefined;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (strict)
+                throw new Error(`clients file ${file}: ${msg}`);
+            if (this.broken !== msg)
+                this.warn(`⚠ clients file ${file} unusable (${msg}) — every request is refused until it is fixed`);
+            this.broken = msg;
+            this.clients = [];
+        }
+    }
+    get count() {
+        return this.clients.filter((c) => !c.disabled).length;
+    }
+    /** The client owning this `Authorization` header, or null (missing, malformed, unknown, revoked or disabled). */
+    authenticate(header) {
+        if (this.source.file)
+            this.reload();
+        const m = /^Bearer (\S+)$/.exec(header ?? "");
+        if (!m || !CLIENT_KEY_RE.test(m[1]))
+            return null;
+        const given = Buffer.from(hashKey(m[1]), "hex");
+        let found = null;
+        // compare against every hash, without early exit
+        for (const c of this.clients)
+            for (const h of c.keyHashes)
+                if (timingSafeEqual(h, given) && !found)
+                    found = c;
+        if (!found || found.disabled)
+            return null;
+        const { keyHashes: _k, disabled: _d, ...profile } = found;
+        return profile;
+    }
+}

package/dist/config.js

@@ -18,12 +18,35 @@ export const domainOf = (address) => address.slice(address.lastIndexOf("@") + 1)
 export function isAllowed(list, address) {
     return list.addresses.has(address) || list.domains.has(domainOf(address));
 }
+/** `a@x.fr,@domain.fr` → allowlist. Throws on wildcards and malformed entries; may return an empty list. */
+export function parseAllowlist(raw, name) {
+    const addresses = new Set();
+    const domains = new Set();
+    for (const entry of raw.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean)) {
+        if (entry.includes("*"))
+            throw new Error(`${name}: wildcards are not supported ("${entry}") — list addresses or @domains`);
+        if (entry.startsWith("@")) {
+            if (!DOMAIN_RE.test(entry.slice(1)))
+                throw new Error(`${name}: invalid domain "${entry}"`);
+            domains.add(entry.slice(1));
+        }
+        else {
+            const a = normalizeAddress(entry);
+            if (!a)
+                throw new Error(`${name}: invalid address "${entry}"`);
+            addresses.add(a);
+        }
+    }
+    return { addresses, domains };
+}
 export const DEFAULT_MAX_RECIPIENTS = 10;
 export const HARD_MAX_RECIPIENTS = 50;
 export const DEFAULT_MAX_PER_HOUR = 20;
 export const HARD_MAX_PER_HOUR = 500;
+export const DEFAULT_MAX_PER_DAY = 200;
+export const HARD_MAX_PER_DAY = 5000;
 const get = (env, k) => env[k]?.trim() || undefined;
-function intIn(raw, name, def, max, warnings) {
+export function intIn(raw, name, def, max, warnings) {
     if (raw === undefined)
         return def;
     const n = Number(raw);
@@ -66,24 +89,8 @@ export function loadConfig(env) {
     const replyTo = replyToRaw ? normalizeAddress(replyToRaw) : undefined;
     if (replyToRaw && !replyTo)
         throw new Error(`EMAIL_REPLY_TO is not a plain email address: "${replyToRaw}"`);
-    const addresses = new Set();
-    const domains = new Set();
-    for (const entry of (get(env, "EMAIL_ALLOWED_RECIPIENTS") ?? "").split(",").map((s) => s.trim().toLowerCase()).filter(Boolean)) {
-        if (entry.includes("*"))
-            throw new Error(`EMAIL_ALLOWED_RECIPIENTS: wildcards are not supported ("${entry}") — list addresses or @domains`);
-        if (entry.startsWith("@")) {
-            if (!DOMAIN_RE.test(entry.slice(1)))
-                throw new Error(`EMAIL_ALLOWED_RECIPIENTS: invalid domain "${entry}"`);
-            domains.add(entry.slice(1));
-        }
-        else {
-            const a = normalizeAddress(entry);
-            if (!a)
-                throw new Error(`EMAIL_ALLOWED_RECIPIENTS: invalid address "${entry}"`);
-            addresses.add(a);
-        }
-    }
-    if (!addresses.size && !domains.size) {
+    const allowlist = parseAllowlist(get(env, "EMAIL_ALLOWED_RECIPIENTS") ?? "", "EMAIL_ALLOWED_RECIPIENTS");
+    if (!allowlist.addresses.size && !allowlist.domains.size) {
         throw new Error("EMAIL_ALLOWED_RECIPIENTS is empty — list the addresses and/or @domains the agent may write to");
     }
     return {
@@ -92,11 +99,14 @@ export function loadConfig(env) {
         region,
         from: { email: fromEmail, name: fromName },
         replyTo: replyTo ?? undefined,
-        allowlist: { addresses, domains },
+        allowlist,
         maxRecipients: intIn(get(env, "EMAIL_MAX_RECIPIENTS"), "EMAIL_MAX_RECIPIENTS", DEFAULT_MAX_RECIPIENTS, HARD_MAX_RECIPIENTS, warnings),
         maxPerHour: intIn(get(env, "EMAIL_MAX_PER_HOUR"), "EMAIL_MAX_PER_HOUR", DEFAULT_MAX_PER_HOUR, HARD_MAX_PER_HOUR, warnings),
+        maxPerDay: intIn(get(env, "EMAIL_MAX_PER_DAY"), "EMAIL_MAX_PER_DAY", DEFAULT_MAX_PER_DAY, HARD_MAX_PER_DAY, warnings),
         killSwitchFile: get(env, "EMAIL_KILL_SWITCH_FILE"),
         auditFile: get(env, "EMAIL_AUDIT_LOG_FILE"),
+        stateDir: get(env, "EMAIL_STATE_DIR"),
+        templatesDir: get(env, "EMAIL_TEMPLATES_DIR"),
         warnings,
     };
 }

package/dist/errors.js

@@ -1,3 +1,4 @@
+import { redactor } from "./redact.js";
 export class EmailError extends Error {
     code;
     status;
@@ -15,5 +16,6 @@ export function toEmailError(err) {
 }
 export function errorResult(err) {
     const e = toEmailError(err);
-    return { isError: true, content: [{ type: "text", text: e.message.startsWith(`${e.code}:`) ? e.message : `${e.code}: ${e.message}` }] };
+    const text = e.message.startsWith(`${e.code}:`) ? e.message : `${e.code}: ${e.message}`;
+    return { isError: true, content: [{ type: "text", text: redactor.apply(text) }] };
 }

package/dist/http.js

@@ -0,0 +1,131 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { redactor } from "./redact.js";
+import { registerTools, SERVER_INSTRUCTIONS } from "./tools.js";
+import { handleTemWebhook } from "./webhook.js";
+/** JSON-RPC bodies only carry text and references (attachments are fetched by the server). */
+export const MAX_BODY_BYTES = 1_048_576;
+const WEBHOOK_MAX_BODY_BYTES = 262_144;
+const WEBHOOK_SECRET_RE = /^[A-Za-z0-9_-]{32,128}$/;
+export function loadHttpConfig(env) {
+    const get = (k) => env[k]?.trim() || undefined;
+    const port = Number(get("EMAIL_MCP_PORT") ?? 8080);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new Error(`EMAIL_MCP_PORT must be a TCP port (got "${env.EMAIL_MCP_PORT}")`);
+    const webhookSecret = get("EMAIL_WEBHOOK_SECRET");
+    if (webhookSecret && !WEBHOOK_SECRET_RE.test(webhookSecret)) {
+        throw new Error("EMAIL_WEBHOOK_SECRET must be 32 to 128 characters among letters, digits, _ and - (e.g. openssl rand -hex 32)");
+    }
+    redactor.add(webhookSecret);
+    return {
+        host: get("EMAIL_MCP_HOST") ?? "127.0.0.1",
+        port,
+        clientsFile: get("EMAIL_MCP_CLIENTS_FILE"),
+        clientsInline: get("EMAIL_MCP_CLIENTS"),
+        webhookSecret,
+        allowedOrigins: (get("EMAIL_MCP_ALLOWED_ORIGINS") ?? "").split(",").map((s) => s.trim()).filter(Boolean),
+    };
+}
+const sha = (s) => createHash("sha256").update(s).digest();
+function send(res, status, body, headers = {}) {
+    res.writeHead(status, {
+        "Cache-Control": "no-store",
+        "X-Content-Type-Options": "nosniff",
+        ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+        ...headers,
+    });
+    res.end(body === undefined ? undefined : JSON.stringify(body));
+}
+const rpcError = (code, message) => ({ jsonrpc: "2.0", error: { code, message }, id: null });
+async function readBody(req, max) {
+    const chunks = [];
+    let size = 0;
+    for await (const c of req) {
+        size += c.length;
+        if (size > max)
+            return null;
+        chunks.push(c);
+    }
+    return Buffer.concat(chunks).toString("utf-8");
+}
+/**
+ * Streamable HTTP, stateless: every POST /mcp is authenticated, then served by a fresh MCP server
+ * bound to that client (its quotas, its allowlist, its sends). Also /health and the TEM webhook.
+ */
+export function createHttpHandler(svc, clients, http, version, log = (m) => process.stderr.write(`${m}\n`)) {
+    const webhookPath = http.webhookSecret ? sha(`/webhooks/tem/${http.webhookSecret}`) : undefined;
+    return async (req, res) => {
+        try {
+            const path = (req.url ?? "/").split("?")[0];
+            if (path === "/health") {
+                if (req.method !== "GET" && req.method !== "HEAD")
+                    return send(res, 405, { error: "method not allowed" }, { Allow: "GET, HEAD" });
+                return send(res, 200, { status: "ok", service: "email-mcp", version, sending: svc.killSwitchActive() ? "disabled" : "enabled" });
+            }
+            if (path.startsWith("/webhooks/tem/")) {
+                if (!webhookPath || !timingSafeEqual(sha(path), webhookPath))
+                    return send(res, 404, { error: "not found" });
+                if (req.method !== "POST")
+                    return send(res, 405, { error: "method not allowed" }, { Allow: "POST" });
+                const body = await readBody(req, WEBHOOK_MAX_BODY_BYTES);
+                if (body === null)
+                    return send(res, 413, { error: "payload too large" }, { Connection: "close" });
+                const r = await handleTemWebhook(body, { projectId: svc.config.projectId, region: svc.config.region, ledger: svc.ledger });
+                if (r.log)
+                    log(redactor.apply(r.log));
+                return send(res, r.status);
+            }
+            if (path !== "/mcp")
+                return send(res, 404, { error: "not found" });
+            const origin = req.headers.origin;
+            if (origin && !http.allowedOrigins.includes(origin))
+                return send(res, 403, rpcError(-32000, "origin not allowed"));
+            const client = clients.authenticate(req.headers.authorization);
+            if (!client) {
+                svc.audit.log({ tool: "http", result: "refused", from: svc.config.from.email, errorCode: "unauthorized" });
+                return send(res, 401, rpcError(-32001, "unauthorized: a valid client key is required (Authorization: Bearer emk_…)"), { "WWW-Authenticate": 'Bearer realm="email-mcp"' });
+            }
+            // stateless server: no SSE stream to resume, no session to delete
+            if (req.method !== "POST")
+                return send(res, 405, rpcError(-32000, "method not allowed: POST JSON-RPC to /mcp"), { Allow: "POST" });
+            if (!(req.headers["content-type"] ?? "").toLowerCase().startsWith("application/json"))
+                return send(res, 415, rpcError(-32700, "content-type must be application/json"));
+            if (Number(req.headers["content-length"] ?? 0) > MAX_BODY_BYTES)
+                return send(res, 413, rpcError(-32600, `request larger than ${MAX_BODY_BYTES} bytes`), { Connection: "close" });
+            const raw = await readBody(req, MAX_BODY_BYTES);
+            if (raw === null)
+                return send(res, 413, rpcError(-32600, `request larger than ${MAX_BODY_BYTES} bytes`), { Connection: "close" });
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                return send(res, 400, rpcError(-32700, "parse error"));
+            }
+            const server = new McpServer({ name: "email", version }, { instructions: SERVER_INSTRUCTIONS });
+            registerTools(server, { ...svc, client });
+            const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
+            res.on("close", () => {
+                void transport.close();
+                void server.close();
+            });
+            await server.connect(transport);
+            await transport.handleRequest(req, res, parsed);
+        }
+        catch (err) {
+            log(redactor.apply(`email-mcp http: ${err instanceof Error ? err.message : String(err)}`));
+            if (!res.headersSent)
+                send(res, 500, rpcError(-32603, "internal error"));
+            else
+                res.end();
+        }
+    };
+}
+export function createHttpServer(svc, clients, http, version) {
+    const server = createServer(createHttpHandler(svc, clients, http, version));
+    server.headersTimeout = 15_000;
+    server.requestTimeout = 120_000;
+    return server;
+}

package/dist/index.js

@@ -2,26 +2,75 @@
 import { readFileSync } from "node:fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadAttachmentConfig } from "./attachments.js";
+import { CLIENT_ID_RE, ClientRegistry, generateKey } from "./clients.js";
 import { loadConfig } from "./config.js";
+import { createHttpServer, loadHttpConfig } from "./http.js";
+import { redactor } from "./redact.js";
 import { TemClient } from "./tem-client.js";
-import { createContext, registerTools, SERVER_INSTRUCTIONS } from "./tools.js";
+import { createService, localClient, registerTools, SERVER_INSTRUCTIONS } from "./tools.js";
 const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
-// stdout is the MCP transport: everything human-readable goes to stderr.
+// stdout is the MCP transport over stdio: everything human-readable goes to stderr.
 const log = (msg) => process.stderr.write(`${msg}\n`);
-try {
+function keygen(id) {
+    if (!id || !CLIENT_ID_RE.test(id)) {
+        log("usage: email-mcp keygen <client-id>   (client id: [a-z0-9_.-], 64 characters max)");
+        process.exit(2);
+    }
+    const { key, hash } = generateKey();
+    // the key goes to stdout once, for the agent's secret store; the server only keeps the hash
+    process.stdout.write(`client key (give it to "${id}" only, it is not stored anywhere):\n${key}\n\n` +
+        `clients file entry:\n${JSON.stringify({ id, keys: [hash] })}\n`);
+}
+async function main() {
+    if (process.argv[2] === "keygen")
+        return keygen(process.argv[3]);
+    const mode = process.env.EMAIL_MCP_TRANSPORT?.trim() || "stdio";
+    if (mode !== "stdio" && mode !== "http")
+        throw new Error(`EMAIL_MCP_TRANSPORT must be stdio or http (got "${mode}")`);
     const config = loadConfig(process.env);
-    const ctx = createContext(config, new TemClient(config.secretKey, config.projectId, config.region));
-    const server = new McpServer({ name: "email", version: pkg.version }, { instructions: SERVER_INSTRUCTIONS });
-    registerTools(server, ctx);
+    redactor.add(config.secretKey);
+    const attachments = loadAttachmentConfig(process.env, config.warnings);
+    const tem = new TemClient(config.secretKey, config.projectId, config.region);
+    const a = config.allowlist;
+    const summary = `sender: ${config.from.email}, TEM ${config.region}, allowlist: ${a.addresses.size} address(es) + ${a.domains.size} domain(s), ` +
+        `${config.maxRecipients} recipients/email, ${config.maxPerHour}/hour, ${config.maxPerDay}/day, ` +
+        `kill switch: ${config.killSwitchFile ?? "not configured"}, attachment sources: ${attachments.sources.length}, ` +
+        `templates: ${config.templatesDir ?? "not configured"}, state: ${config.stateDir ?? "memory only"}`;
+    if (mode === "stdio") {
+        const svc = createService(config, tem, { attachments });
+        const server = new McpServer({ name: "email", version: pkg.version }, { instructions: SERVER_INSTRUCTIONS });
+        registerTools(server, { ...svc, client: localClient(config) });
+        for (const w of config.warnings)
+            log(w);
+        await server.connect(new StdioServerTransport());
+        log(`email-mcp v${pkg.version} ready over stdio (${summary})`);
+        return;
+    }
+    const http = loadHttpConfig(process.env);
+    // a restart must not forget which idempotency keys already sent
+    if (!config.stateDir)
+        throw new Error("Missing required env var for HTTP: EMAIL_STATE_DIR (persistent volume for the send ledger)");
+    const clients = new ClientRegistry({ file: http.clientsFile, inline: http.clientsInline }, config);
+    const svc = createService(config, tem, { attachments, multiClient: true, webhookConfigured: !!http.webhookSecret });
+    const server = createHttpServer(svc, clients, http, pkg.version);
     for (const w of config.warnings)
         log(w);
-    await server.connect(new StdioServerTransport());
-    const a = config.allowlist;
-    log(`email-mcp v${pkg.version} ready (sender: ${config.from.email}, TEM ${config.region} project ${config.projectId}, ` +
-        `allowlist: ${a.addresses.size} address(es) + ${a.domains.size} domain(s), ${config.maxRecipients} recipients/email, ${config.maxPerHour}/hour, ` +
-        `kill switch: ${config.killSwitchFile ?? "not configured"})`);
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(http.port, http.host, resolve);
+    });
+    log(`email-mcp v${pkg.version} ready over HTTP on ${http.host}:${http.port} (/mcp, /health${http.webhookSecret ? ", TEM webhook" : ""}; ${clients.count} client(s); ${summary})`);
+    // finish the requests in flight (a send must get its answer), then exit; 10 s at most
+    const stop = () => {
+        server.close(() => process.exit(0));
+        server.closeIdleConnections();
+        setTimeout(() => process.exit(0), 10_000).unref();
+    };
+    process.on("SIGTERM", stop);
+    process.on("SIGINT", stop);
 }
-catch (err) {
-    log(`email-mcp: ${err instanceof Error ? err.message : String(err)}`);
+main().catch((err) => {
+    log(redactor.apply(`email-mcp: ${err instanceof Error ? err.message : String(err)}`));
     process.exit(1);
-}
+});

package/dist/ledger.js

@@ -0,0 +1,128 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { EmailError } from "./errors.js";
+import { DAY_MS } from "./quota.js";
+export const IDEMPOTENCY_KEY_RE = /^[A-Za-z0-9._:-]{8,128}$/;
+export const RETENTION_MS = 30 * DAY_MS;
+export const MAX_RECORDS = 20_000;
+export const MAX_EVENTS_PER_EMAIL = 20;
+/**
+ * Every send, keyed by (client, idempotency key): what makes a key never send twice, which client
+ * owns which TEM email id (a client only reads its own) and the delivery events received by webhook.
+ * Persisted as one JSON file (atomic rename, mode 600) when a file is given; in memory otherwise.
+ * A record still `in_flight` when the file is loaded (crash during a send) becomes `unknown_outcome`.
+ */
+export class SendLedger {
+    file;
+    now;
+    records = new Map();
+    owners = new Map();
+    constructor(file, now = Date.now) {
+        this.file = file;
+        this.now = now;
+        if (file && existsSync(file)) {
+            let data;
+            try {
+                data = JSON.parse(readFileSync(file, "utf-8"));
+            }
+            catch (err) {
+                throw new Error(`send ledger ${file} is unreadable (${err instanceof Error ? err.message : String(err)}) — fix or move it; refusing to start without it`);
+            }
+            for (const r of data.records ?? []) {
+                if (r.state === "in_flight")
+                    r.state = "unknown_outcome";
+                this.index(r);
+            }
+            this.prune();
+        }
+    }
+    static id(client, key) {
+        return `${client}\u0000${key}`;
+    }
+    index(r) {
+        this.records.set(SendLedger.id(r.client, r.key), r);
+        for (const id of r.emailIds)
+            this.owners.set(id, r);
+    }
+    prune() {
+        const floor = this.now() - RETENTION_MS;
+        const all = [...this.records.values()].sort((a, b) => a.updatedAt.localeCompare(b.updatedAt));
+        const excess = all.length - MAX_RECORDS;
+        all.forEach((r, i) => {
+            if (i < excess || Date.parse(r.updatedAt) < floor) {
+                this.records.delete(SendLedger.id(r.client, r.key));
+                for (const id of r.emailIds)
+                    this.owners.delete(id);
+            }
+        });
+    }
+    persist() {
+        if (!this.file)
+            return;
+        mkdirSync(dirname(this.file), { recursive: true, mode: 0o700 });
+        const tmp = `${this.file}.${process.pid}.tmp`;
+        writeFileSync(tmp, JSON.stringify({ version: 1, records: [...this.records.values()] }), { mode: 0o600 });
+        renameSync(tmp, this.file);
+    }
+    get size() {
+        return this.records.size;
+    }
+    find(client, key) {
+        return this.records.get(SendLedger.id(client, key));
+    }
+    /** Records the send as in flight before it leaves. Throws `refused` when that cannot be persisted. */
+    begin(client, key, digest) {
+        if (this.find(client, key))
+            throw new EmailError("idempotency_conflict", "idempotency_conflict: this idempotency_key was already used");
+        const at = new Date(this.now()).toISOString();
+        const r = { client, key, digest, state: "in_flight", createdAt: at, updatedAt: at, emailIds: [], events: {} };
+        this.prune();
+        this.index(r);
+        try {
+            this.persist();
+        }
+        catch (err) {
+            this.records.delete(SendLedger.id(client, key));
+            throw new EmailError("refused", `refused: the send ledger cannot be written (${err.code ?? "error"}) — nothing was sent`);
+        }
+        return r;
+    }
+    /** After the provider answered. Never throws: the email has left, a disk error must not hide it. */
+    settle(r, state, emailIds = []) {
+        r.state = state;
+        r.emailIds = emailIds;
+        r.updatedAt = new Date(this.now()).toISOString();
+        for (const id of emailIds)
+            this.owners.set(id, r);
+        this.safePersist();
+    }
+    /** The provider refused the send for certain: the key may be used again. */
+    drop(r) {
+        this.records.delete(SendLedger.id(r.client, r.key));
+        this.safePersist();
+    }
+    ownerOf(emailId) {
+        return this.owners.get(emailId);
+    }
+    /** Stores a webhook event for one of our emails. Returns false (nothing stored) for any other email. */
+    addEvent(emailId, e) {
+        const r = this.owners.get(emailId);
+        if (!r)
+            return false;
+        const list = (r.events[emailId] ??= []);
+        list.push(e);
+        if (list.length > MAX_EVENTS_PER_EMAIL)
+            list.splice(0, list.length - MAX_EVENTS_PER_EMAIL);
+        r.updatedAt = new Date(this.now()).toISOString();
+        this.safePersist();
+        return true;
+    }
+    safePersist() {
+        try {
+            this.persist();
+        }
+        catch (err) {
+            process.stderr.write(`⚠ send ledger not writable (${err.code ?? "error"}) — kept in memory only\n`);
+        }
+    }
+}

package/dist/quota.js

@@ -0,0 +1,77 @@
+import { EmailError } from "./errors.js";
+export const HOUR_MS = 3_600_000;
+export const DAY_MS = 24 * HOUR_MS;
+/** Timestamps of the sends inside a sliding window, per process. */
+export class SlidingWindow {
+    windowMs;
+    now;
+    sends = [];
+    constructor(windowMs, now = Date.now) {
+        this.windowMs = windowMs;
+        this.now = now;
+    }
+    count() {
+        const floor = this.now() - this.windowMs;
+        while (this.sends.length && this.sends[0] <= floor)
+            this.sends.shift();
+        return this.sends.length;
+    }
+    /** Takes a slot; returns a function giving it back (for a send that certainly did not leave). */
+    reserve() {
+        const t = this.now();
+        this.sends.push(t);
+        return () => {
+            const i = this.sends.lastIndexOf(t);
+            if (i >= 0)
+                this.sends.splice(i, 1);
+        };
+    }
+}
+/**
+ * Two windows (hour, day) for the whole server and two for each client: a send needs a slot in
+ * all four. Counters live in memory — a restart resets them (the ledger still blocks duplicates).
+ */
+export class Quotas {
+    limits;
+    now;
+    global;
+    clients = new Map();
+    constructor(limits, now = Date.now) {
+        this.limits = limits;
+        this.now = now;
+        this.global = this.pair();
+    }
+    pair() {
+        return { hour: new SlidingWindow(HOUR_MS, this.now), day: new SlidingWindow(DAY_MS, this.now) };
+    }
+    of(clientId) {
+        let p = this.clients.get(clientId);
+        if (!p)
+            this.clients.set(clientId, (p = this.pair()));
+        return p;
+    }
+    remaining(clientId, client) {
+        const c = this.of(clientId);
+        return {
+            client: { hour: Math.max(0, client.maxPerHour - c.hour.count()), day: Math.max(0, client.maxPerDay - c.day.count()) },
+            global: { hour: Math.max(0, this.limits.maxPerHour - this.global.hour.count()), day: Math.max(0, this.limits.maxPerDay - this.global.day.count()) },
+        };
+    }
+    /** Throws `rate_limited` naming the exhausted window. */
+    check(clientId, client) {
+        const r = this.remaining(clientId, client);
+        if (r.client.hour <= 0)
+            throw new EmailError("rate_limited", `rate_limited: client "${clientId}" reached ${client.maxPerHour} emails in the last hour`);
+        if (r.client.day <= 0)
+            throw new EmailError("rate_limited", `rate_limited: client "${clientId}" reached ${client.maxPerDay} emails in the last 24 hours`);
+        if (r.global.hour <= 0)
+            throw new EmailError("rate_limited", `rate_limited: ${this.limits.maxPerHour} emails already sent in the last hour (EMAIL_MAX_PER_HOUR)`);
+        if (r.global.day <= 0)
+            throw new EmailError("rate_limited", `rate_limited: ${this.limits.maxPerDay} emails already sent in the last 24 hours (EMAIL_MAX_PER_DAY)`);
+    }
+    reserve(clientId) {
+        const c = this.of(clientId);
+        const releases = [c.hour.reserve(), c.day.reserve(), this.global.hour.reserve(), this.global.day.reserve()];
+        return () => releases.forEach((r) => r());
+    }
+}