@aidalinfo/email-mcp 0.1.1 → 0.3.0

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

package/dist/redact.js

@@ -0,0 +1,23 @@
+/**
+ * Central redaction for everything that leaves the process as text (tool errors, audit lines,
+ * HTTP error bodies): registered secrets, auth headers and client keys, whatever their source.
+ */
+export class Redactor {
+    secrets = new Set();
+    /** Registers a secret value; values under 8 characters are ignored (too likely to hit plain text). */
+    add(secret) {
+        if (secret && secret.length >= 8)
+            this.secrets.add(secret);
+    }
+    apply(text) {
+        let t = text;
+        for (const s of this.secrets)
+            t = t.split(s).join("[REDACTED]");
+        return t
+            .replace(/(x-auth-token["']?\s*[:=]\s*["']?)[^"'\s,}]+/gi, "$1[REDACTED]")
+            .replace(/(authorization["']?\s*[:=]\s*["']?)(?:(bearer|basic)\s+)?[^"'\s,}]+/gi, (_, h, scheme) => `${h}${scheme ? `${scheme} ` : ""}[REDACTED]`)
+            .replace(/\bemk_[A-Za-z0-9_-]{16,}/g, "[REDACTED]");
+    }
+}
+/** Process-wide instance: the entry point registers the secrets it loads. */
+export const redactor = new Redactor();

package/dist/smtp-client.js

@@ -0,0 +1,70 @@
+import nodemailer from "nodemailer";
+import { EmailError } from "./errors.js";
+import { redactSecret } from "./tem-client.js";
+export const SMTP_HOST = "smtp.tem.scaleway.com";
+/** TEM refuses an email above 50 MB over SMTP, headers, bodies and encoded attachments included. */
+export const SMTP_MAX_EMAIL_BYTES = 50_000_000;
+export const SMTP_TIMEOUT_MS = 120_000;
+/** Stages before the message body leaves: a failure there means nothing was sent. */
+const BEFORE_DATA = new Set(["CONN", "GREETING", "EHLO", "HELO", "LHLO", "STARTTLS", "AUTH", "AUTH PLAIN", "AUTH LOGIN", "MAIL FROM", "RCPT TO"]);
+const NOT_CONNECTED = new Set(["ECONNECTION", "EDNS", "ETLS", "EAUTH", "EENVELOPE"]);
+/** Same outcome rules as the API: a refusal is certain, a cut after the body started is unknown. */
+export function smtpError(err, secret) {
+    const e = (err ?? {});
+    const detail = redactSecret(String(e.response ?? e.message ?? err), secret).slice(0, 300);
+    const code = e.responseCode;
+    if (e.code === "EAUTH" || code === 530 || code === 535) {
+        return new EmailError("permission_missing", `permission_missing: SMTP authentication refused — the API key needs Transactional Email permissions on the project (${detail})`, code);
+    }
+    if (code && code >= 400) {
+        if (code === 552)
+            return new EmailError("invalid_request", `invalid_request: TEM refused the email as too large over SMTP (${detail})`, code);
+        if (code < 500)
+            return new EmailError("transient", `transient: SMTP send refused for now (${detail}) — retry later`, code);
+        return new EmailError("invalid_request", `invalid_request: TEM refused the email over SMTP (${detail})`, code);
+    }
+    if (NOT_CONNECTED.has(e.code ?? "") || BEFORE_DATA.has(e.command ?? "")) {
+        return new EmailError("transient", `transient: SMTP connection to ${SMTP_HOST} failed before sending (${detail})`);
+    }
+    return new EmailError("unknown_outcome", `unknown_outcome: the SMTP send was interrupted (${detail}) — the email may have been sent; check email_status and the TEM console before sending again`);
+}
+/** TEM over SMTP: user = project id, password = the same secret key as the API. */
+export class SmtpClient {
+    secretKey;
+    transport;
+    constructor(projectId, secretKey, port) {
+        this.secretKey = secretKey;
+        this.transport = nodemailer.createTransport({
+            host: SMTP_HOST,
+            port,
+            secure: port === 465 || port === 2465,
+            requireTLS: true,
+            auth: { user: projectId, pass: secretKey },
+            connectionTimeout: 30_000,
+            greetingTimeout: 30_000,
+            socketTimeout: SMTP_TIMEOUT_MS,
+            // contents come from the resolver only: never let the library read a path or a URL
+            disableFileAccess: true,
+            disableUrlAccess: true,
+        });
+    }
+    async send(m) {
+        try {
+            const info = await this.transport.sendMail({
+                from: m.from.name ? { name: m.from.name, address: m.from.email } : m.from.email,
+                replyTo: m.replyTo,
+                to: m.to,
+                cc: m.cc.length ? m.cc : undefined,
+                subject: m.subject,
+                text: m.text,
+                html: m.html,
+                attachments: m.attachments.map((a) => ({ filename: a.name, contentType: a.type, content: a.content })),
+            });
+            const list = (v) => (Array.isArray(v) ? v.map((x) => String(typeof x === "object" && x && "address" in x ? x.address : x).toLowerCase()) : []);
+            return { response: String(info.response ?? ""), accepted: list(info.accepted), rejected: list(info.rejected) };
+        }
+        catch (err) {
+            throw smtpError(err, this.secretKey);
+        }
+    }
+}

package/dist/tem-client.js

@@ -73,4 +73,18 @@ export class TemClient {
     async getEmail(id) {
         return this.call("GET", `${this.base}/emails/${encodeURIComponent(id)}`, "get email");
     }
+    async listEmails(q) {
+        const qs = new URLSearchParams({ project_id: this.projectId, mail_from: q.mailFrom, since: q.since, page_size: "100" });
+        if (q.messageId)
+            qs.set("message_id", q.messageId);
+        if (q.subject)
+            qs.set("subject", q.subject);
+        const res = await this.call("GET", `${this.base}/emails?${qs}`, "list emails");
+        return (res.emails ?? []).filter((e) => e.project_id === this.projectId);
+    }
+    async listBlocklists(domainId, email) {
+        const qs = new URLSearchParams({ domain_id: domainId, email, page_size: "20" });
+        const res = await this.call("GET", `${this.base}/blocklists?${qs}`, "list TEM blocklists");
+        return (res.blocklists ?? []).filter((b) => b.domain_id === domainId && b.email.toLowerCase() === email);
+    }
 }

package/dist/templates.js

@@ -0,0 +1,118 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { EmailError } from "./errors.js";
+export const TEMPLATE_NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const VARIABLE_RE = /^[a-z][a-z0-9_]{0,39}$/;
+const PLACEHOLDER_RE = /\{\{\s*([a-z][a-z0-9_]{0,39})\s*\}\}/g;
+export const DEFAULT_VARIABLE_LENGTH = 1_000;
+export const HARD_VARIABLE_LENGTH = 10_000;
+const escapeHtml = (s) => s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+function parseTemplate(raw, file) {
+    const t = raw;
+    const fail = (m) => {
+        throw new Error(`template ${file}: ${m}`);
+    };
+    if (!t || typeof t !== "object")
+        fail("not a JSON object");
+    if (typeof t.name !== "string" || !TEMPLATE_NAME_RE.test(t.name))
+        fail("name must match [a-z0-9-], 64 characters max");
+    if (!Number.isInteger(t.version) || t.version < 1)
+        fail("version must be a positive integer");
+    for (const k of ["subject", "text"])
+        if (typeof t[k] !== "string" || !t[k].trim())
+            fail(`${k} is required`);
+    if (t.html !== undefined && (typeof t.html !== "string" || !t.html.trim()))
+        fail("html must be a non-empty string when present");
+    if (/[\u0000-\u001f\u007f]/.test(t.subject))
+        fail("subject must not contain line breaks or control characters");
+    const variables = {};
+    for (const [name, spec] of Object.entries((t.variables ?? {}))) {
+        if (!VARIABLE_RE.test(name))
+            fail(`variable "${name}" must match [a-z][a-z0-9_]*`);
+        const maxLength = spec?.maxLength ?? DEFAULT_VARIABLE_LENGTH;
+        if (!Number.isInteger(maxLength) || maxLength < 1 || maxLength > HARD_VARIABLE_LENGTH)
+            fail(`variable "${name}": maxLength must be 1..${HARD_VARIABLE_LENGTH}`);
+        variables[name] = { required: spec?.required !== false, maxLength: maxLength, description: typeof spec?.description === "string" ? spec.description : undefined };
+    }
+    for (const k of ["subject", "text", "html"]) {
+        for (const m of (t[k] ?? "").matchAll(PLACEHOLDER_RE)) {
+            if (!Object.hasOwn(variables, m[1]))
+                fail(`${k} uses {{${m[1]}}}, which is not declared in variables`);
+        }
+    }
+    if (t.clients !== undefined && (!Array.isArray(t.clients) || t.clients.some((c) => typeof c !== "string")))
+        fail("clients must be a list of client ids");
+    return {
+        name: t.name,
+        version: t.version,
+        description: typeof t.description === "string" ? t.description : undefined,
+        subject: t.subject,
+        text: t.text,
+        html: t.html,
+        variables,
+        clients: t.clients,
+    };
+}
+/**
+ * Versioned templates for recurring sends, loaded once at startup from EMAIL_TEMPLATES_DIR
+ * (one JSON file per name and version). A send names the exact version: changing a template means
+ * adding a new version, never editing the content a routine was approved with.
+ */
+export class TemplateCatalog {
+    dir;
+    byKey = new Map();
+    constructor(dir) {
+        this.dir = dir;
+        if (!dir)
+            return;
+        for (const f of readdirSync(dir).filter((n) => n.endsWith(".json")).sort()) {
+            let raw;
+            try {
+                raw = JSON.parse(readFileSync(join(dir, f), "utf-8"));
+            }
+            catch (err) {
+                throw new Error(`template ${f}: invalid JSON (${err instanceof Error ? err.message : String(err)})`);
+            }
+            const t = parseTemplate(raw, f);
+            const key = `${t.name}@${t.version}`;
+            if (this.byKey.has(key))
+                throw new Error(`template ${f}: ${key} is defined twice`);
+            this.byKey.set(key, t);
+        }
+    }
+    get configured() {
+        return !!this.dir;
+    }
+    list(clientId) {
+        return [...this.byKey.values()].filter((t) => !t.clients || t.clients.includes(clientId));
+    }
+    /** Renders a template for a client. Variables are escaped in the HTML body and refused with control characters in the subject. */
+    render(clientId, name, version, vars) {
+        if (!this.configured)
+            throw new EmailError("capability_unavailable", "capability_unavailable: no template directory is configured (EMAIL_TEMPLATES_DIR)");
+        const t = this.byKey.get(`${name}@${version}`);
+        if (!t || (t.clients && !t.clients.includes(clientId)))
+            throw new EmailError("not_found", `not_found: template ${name}@${version} does not exist for this client — see email_templates`);
+        for (const k of Object.keys(vars)) {
+            if (!Object.hasOwn(t.variables, k))
+                throw new EmailError("invalid_request", `invalid_request: template ${name}@${version} has no variable "${k.slice(0, 40)}"`);
+        }
+        for (const [k, spec] of Object.entries(t.variables)) {
+            const v = Object.hasOwn(vars, k) ? vars[k] : undefined;
+            if (v === undefined || v === "") {
+                if (spec.required)
+                    throw new EmailError("invalid_request", `invalid_request: variable "${k}" is required by ${name}@${version}`);
+                continue;
+            }
+            if (v.length > spec.maxLength)
+                throw new EmailError("invalid_request", `invalid_request: variable "${k}" is longer than ${spec.maxLength} characters`);
+        }
+        const fill = (s, esc) => s.replace(PLACEHOLDER_RE, (_, k) => esc(Object.hasOwn(vars, k) ? vars[k] : ""));
+        const subject = fill(t.subject, (v) => {
+            if (/[\u0000-\u001f\u007f]/.test(v))
+                throw new EmailError("invalid_request", "invalid_request: a variable used in the subject contains a line break or a control character");
+            return v;
+        });
+        return { subject, text: fill(t.text, (v) => v), html: t.html === undefined ? undefined : fill(t.html, escapeHtml) };
+    }
+}