toiljs 0.0.44 → 0.0.46

package/src/compiler/plugin.ts

@@ -8,6 +8,7 @@ import { fileURLToPath } from 'node:url';
 import { type Plugin, version as viteVersion } from 'vite';
 
 import { AiProvider, type DevtoolsAiConfig, type ResolvedToilConfig } from './config.js';
+import { emailsVersion, listEmails, previewShellHtml, renderEmailByName } from './email-preview.js';
 import { generate } from './generate.js';
 import { scanRoutes } from './routes.js';
 
@@ -58,7 +59,9 @@ async function aiComplete(ai: DevtoolsAiConfig, prompt: string): Promise<string>
 /** Reads a package's version resolved from `<fromDir>`, or 'unknown'. */
 function depVersion(fromDir: string, name: string): string {
     try {
-        const pkgPath = createRequire(path.join(fromDir, 'package.json')).resolve(`${name}/package.json`);
+        const pkgPath = createRequire(path.join(fromDir, 'package.json')).resolve(
+            `${name}/package.json`,
+        );
         const raw = JSON.parse(fs.readFileSync(pkgPath, 'utf8')) as { version?: string };
         return raw.version ?? 'unknown';
     } catch {
@@ -69,7 +72,12 @@ function depVersion(fromDir: string, name: string): string {
 /** toiljs's own version (package.json two levels up from build/compiler). */
 function frameworkVersion(): string {
     try {
-        const p = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+        const p = path.resolve(
+            path.dirname(fileURLToPath(import.meta.url)),
+            '..',
+            '..',
+            'package.json',
+        );
         const raw = JSON.parse(fs.readFileSync(p, 'utf8')) as { version?: string };
         return raw.version ?? '0.0.0';
     } catch {
@@ -231,7 +239,9 @@ export function toilPlugin(cfg: ResolvedToilConfig): Plugin {
                             const parsed = JSON.parse(body || '{}') as { prompt?: string };
                             // Cap the prompt actually forwarded upstream (independent of the raw-body cap).
                             const prompt =
-                                typeof parsed.prompt === 'string' ? parsed.prompt.slice(0, 16000) : '';
+                                typeof parsed.prompt === 'string'
+                                    ? parsed.prompt.slice(0, 16000)
+                                    : '';
                             const text = await aiComplete(ai, prompt);
                             res.setHeader('content-type', 'application/json');
                             res.end(JSON.stringify({ text }));
@@ -243,7 +253,11 @@ export function toilPlugin(cfg: ResolvedToilConfig): Plugin {
                             );
                             res.statusCode = 500;
                             res.setHeader('content-type', 'application/json');
-                            res.end(JSON.stringify({ error: 'AI request failed (see dev server logs).' }));
+                            res.end(
+                                JSON.stringify({
+                                    error: 'AI request failed (see dev server logs).',
+                                }),
+                            );
                         }
                     })();
                 });
@@ -291,6 +305,76 @@ export function toilPlugin(cfg: ResolvedToilConfig): Plugin {
                 }
             });
 
+            // Email preview tool (dev only). `/__toil/emails` -> a standalone page that lists
+            // `emails/*.tsx`, renders the selected one through the live SSR server (so edits and
+            // imported `client/*` CSS show), and live-refreshes by polling `/version`.
+            // Sub-paths are registered before the page so connect's prefix match resolves them first.
+            server.middlewares.use('/__toil/emails/list', (req, res) => {
+                if (isCrossSiteRequest(req.headers)) {
+                    res.statusCode = 403;
+                    res.end();
+                    return;
+                }
+                res.setHeader('content-type', 'application/json');
+                res.end(JSON.stringify(listEmails(cfg)));
+            });
+            server.middlewares.use('/__toil/emails/render', (req, res) => {
+                if (isCrossSiteRequest(req.headers)) {
+                    res.statusCode = 403;
+                    res.end();
+                    return;
+                }
+                void (async () => {
+                    try {
+                        const name = new URL(req.url ?? '', 'http://localhost').searchParams.get(
+                            'name',
+                        );
+                        if (!name) {
+                            res.statusCode = 400;
+                            res.end();
+                            return;
+                        }
+                        const rendered = await renderEmailByName(server, cfg, name);
+                        if (!rendered) {
+                            res.statusCode = 404;
+                            res.end();
+                            return;
+                        }
+                        res.setHeader('content-type', 'application/json');
+                        res.end(JSON.stringify(rendered));
+                    } catch (e) {
+                        // Log the detail to the dev's terminal; the page shows a generic message.
+                        process.stderr.write(
+                            `toil: /__toil/emails/render failed: ${e instanceof Error ? e.message : String(e)}\n`,
+                        );
+                        res.statusCode = 500;
+                        res.end();
+                    }
+                })();
+            });
+            // A tiny mtime fingerprint of `emails/*` + client CSS the page polls (~1s) to detect
+            // edits. Polling (not SSE) because the wasm dev server proxies `/__toil/*` to Vite by
+            // buffering the whole response, so a long-lived stream would hang; a short poll works
+            // in every mode.
+            server.middlewares.use('/__toil/emails/version', (req, res) => {
+                if (isCrossSiteRequest(req.headers)) {
+                    res.statusCode = 403;
+                    res.end();
+                    return;
+                }
+                res.setHeader('content-type', 'text/plain; charset=utf-8');
+                res.end(emailsVersion(cfg));
+            });
+            server.middlewares.use('/__toil/emails', (req, res) => {
+                if (isCrossSiteRequest(req.headers)) {
+                    res.statusCode = 403;
+                    res.end();
+                    return;
+                }
+                res.setHeader('content-type', 'text/html; charset=utf-8');
+                res.end(previewShellHtml());
+            });
+
             // Trailing slash so a sibling like `routes-extra/` doesn't match the `routes/` prefix.
             const routesPrefix = cfg.routesAbsDir.replace(/\\/g, '/').replace(/\/?$/, '/');
             const onChange = (file: string): void => {

package/src/compiler/vite.ts

@@ -154,6 +154,10 @@ export async function createViteConfig(cfg: ResolvedToilConfig): Promise<InlineC
             alias: {
                 'toiljs/client': cfg.runtimePath,
                 'toiljs/routes': path.join(cfg.toilDir, 'routes.ts'),
+                // `client/*` -> the project's client source dir, so anything (pages, and notably
+                // `emails/*.tsx`) can reuse existing client assets, e.g. `import 'client/styles/x.css'`.
+                // Vite's string alias matches only `client` or `client/...`, never `toiljs/client`.
+                client: cfg.clientAbsDir,
                 // `shared/*` is resolved by sharedResolverPlugin (above) so a missing generated
                 // shared/server.ts gives an actionable error instead of an opaque load failure.
                 ...polyfillShimAliases,

package/src/devserver/dotenv.ts

@@ -0,0 +1,94 @@
+/**
+ * Shared dotenv loader for the dev server (and the future Node self-host): reads
+ * a project's `.env` (plain vars) + `.env.secrets` (secrets) and splits out the
+ * framework-reserved `TOIL_*` keys (host-only), mirroring the edge's `env_store`.
+ *
+ * Vite/devserver-free on purpose — both the `Environment.get/getSecure` dev
+ * source (`./env.ts`) and the email backend config (`./email/config.ts`) consume
+ * this one loader, and the self-host will too.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Keys with this prefix are framework-reserved/host-only (never a tenant var/secret). */
+export const RESERVED_PREFIX = 'TOIL_';
+
+export interface LoadedEnv {
+    /** Non-reserved `.env` entries + `process.env` overlay → `Environment.get`. */
+    readonly vars: Map<string, string>;
+    /** Non-reserved `.env.secrets` entries → `Environment.getSecure`. */
+    readonly secrets: Map<string, string>;
+    /** Reserved `TOIL_*` entries from either file (+ `process.env`) → host-only config. */
+    readonly reserved: Map<string, string>;
+}
+
+const cache = new Map<string, LoadedEnv>();
+
+/** Parse one dotenv value: take inside matching quotes, else cut an inline ` #`. */
+function parseValue(rest: string): string {
+    const q = rest[0];
+    if (q === '"' || q === "'") {
+        const end = rest.indexOf(q, 1);
+        return end < 0 ? rest.slice(1) : rest.slice(1, end);
+    }
+    const hash = rest.indexOf(' #');
+    return (hash < 0 ? rest : rest.slice(0, hash)).trimEnd();
+}
+
+/**
+ * Parse dotenv text into `plain` (non-reserved) and `reserved` (`TOIL_*`):
+ * `KEY=value`, `#` comments, optional `export`, optional surrounding quotes.
+ */
+function parseDotenv(text: string, plain: Map<string, string>, reserved: Map<string, string>): void {
+    for (const raw of text.split('\n')) {
+        let line = raw.trim();
+        if (line.length === 0 || line.startsWith('#')) continue;
+        if (line.startsWith('export ')) line = line.slice('export '.length);
+        const eq = line.indexOf('=');
+        if (eq < 0) continue;
+        const key = line.slice(0, eq).trim();
+        if (key.length === 0) continue;
+        const val = parseValue(line.slice(eq + 1).trim());
+        (key.startsWith(RESERVED_PREFIX) ? reserved : plain).set(key, val);
+    }
+}
+
+function readFileInto(file: string, plain: Map<string, string>, reserved: Map<string, string>): void {
+    try {
+        parseDotenv(fs.readFileSync(file, 'utf8'), plain, reserved);
+    } catch {
+        /* file absent: skip */
+    }
+}
+
+/**
+ * Load `<root>/.env` + `<root>/.env.secrets`, cached by resolved root. `process.env`
+ * overlays first (non-reserved → vars, `TOIL_*` → reserved), then the files take
+ * precedence. Secrets come only from `.env.secrets`.
+ */
+export function loadEnvFiles(root: string): LoadedEnv {
+    const key = path.resolve(root);
+    const hit = cache.get(key);
+    if (hit) return hit;
+
+    const vars = new Map<string, string>();
+    const secrets = new Map<string, string>();
+    const reserved = new Map<string, string>();
+
+    // process.env overlay: non-reserved as plain vars, TOIL_* as reserved config.
+    for (const [k, v] of Object.entries(process.env)) {
+        if (typeof v !== 'string') continue;
+        (k.startsWith(RESERVED_PREFIX) ? reserved : vars).set(k, v);
+    }
+    readFileInto(path.join(key, '.env'), vars, reserved);
+    readFileInto(path.join(key, '.env.secrets'), secrets, reserved);
+
+    const out: LoadedEnv = { vars, secrets, reserved };
+    cache.set(key, out);
+    return out;
+}
+
+/** Drop the cache (tests). */
+export function clearEnvCache(): void {
+    cache.clear();
+}

package/src/devserver/email/config.ts

@@ -0,0 +1,123 @@
+/**
+ * Resolve the dev / self-host email config: merge the typed `toil.config.ts`
+ * `email` section (non-secret) with the reserved `TOIL_EMAIL_*` env keys (which
+ * WIN, for edge parity + 12-factor), and pull the API key from
+ * `TOIL_EMAIL_API_KEY` (a secret, only ever in `.env.secrets`/the environment).
+ *
+ * Mirrors the edge's `host/email.rs` (`EmailSection::from_reserved` + `resolve`):
+ * provider parse, `from` validation, Gmail/SMTP defaults. Returns a `null`
+ * config when email is simply not set up (silent), or a `warning` when it is
+ * partially configured but invalid (logged at startup, treated as Disabled).
+ */
+import type { EmailBackendConfig } from 'toiljs/shared';
+
+import { validFrom } from './validate.js';
+
+export type ResolvedProvider = 'resend' | 'smtp';
+
+export interface ResolvedSmtp {
+    readonly host: string;
+    readonly port: number;
+    readonly user: string;
+}
+
+export interface ResolvedEmailConfig {
+    readonly provider: ResolvedProvider;
+    readonly from: string;
+    readonly apiKey: string;
+    readonly maxPerMin: number;
+    readonly maxPerDay: number;
+    readonly maxPerRecipientPerHour: number;
+    /** Present iff `provider === 'smtp'`. */
+    readonly smtp?: ResolvedSmtp;
+}
+
+export interface ResolveResult {
+    /** The resolved config, or `null` when email is unconfigured / invalid. */
+    readonly config: ResolvedEmailConfig | null;
+    /** A reason email is off despite partial config (logged at startup). */
+    readonly warning: string | null;
+}
+
+/** `TOIL_EMAIL_<NAME>` from the reserved map, trimmed; `undefined` if absent/empty. */
+function envOf(reserved: Map<string, string>, name: string): string | undefined {
+    const v = reserved.get(`TOIL_EMAIL_${name}`);
+    const t = v?.trim();
+    return t ? t : undefined;
+}
+
+function parseBool(v: string | undefined): boolean | undefined {
+    if (v === undefined) return undefined;
+    return v === '1' || v === 'true' || v === 'yes' || v === 'on';
+}
+
+function parseInt0(v: string | undefined, fallback: number): number {
+    if (v === undefined) return fallback;
+    const n = Number.parseInt(v, 10);
+    return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+
+export function resolveEmailConfig(
+    cfg: EmailBackendConfig | null | undefined,
+    reserved: Map<string, string>,
+): ResolveResult {
+    const c = cfg ?? {};
+    // Env (TOIL_EMAIL_*) overrides the config file; api key is env-only.
+    const providerId = (envOf(reserved, 'PROVIDER') ?? c.provider ?? 'resend').toLowerCase();
+    const from = envOf(reserved, 'FROM') ?? c.from?.trim();
+    const apiKey = envOf(reserved, 'API_KEY');
+    const enabled = parseBool(envOf(reserved, 'ENABLED'));
+
+    // Unconfigured: explicitly disabled, or no `from` and no key at all -> silent off.
+    if (enabled === false) return { config: null, warning: null };
+    if (from === undefined && apiKey === undefined && cfg == null) {
+        return { config: null, warning: null };
+    }
+
+    if (from === undefined) {
+        return { config: null, warning: 'email config present but `from` is missing' };
+    }
+    if (!validFrom(from)) {
+        return { config: null, warning: 'email `from` is not a valid address (CRLF or no `@`)' };
+    }
+    if (apiKey === undefined) {
+        return {
+            config: null,
+            warning: 'email config present but TOIL_EMAIL_API_KEY is not set (in .env.secrets)',
+        };
+    }
+
+    let provider: ResolvedProvider;
+    let smtp: ResolvedSmtp | undefined;
+    if (providerId === 'resend') {
+        provider = 'resend';
+    } else if (providerId === 'gmail' || providerId === 'smtp') {
+        provider = 'smtp';
+        const isGmail = providerId === 'gmail';
+        const host = envOf(reserved, 'SMTP_HOST') ?? c.smtp?.host?.trim() ?? (isGmail ? 'smtp.gmail.com' : '');
+        if (!host) {
+            return { config: null, warning: 'provider `smtp` requires TOIL_EMAIL_SMTP_HOST' };
+        }
+        const port = parseInt0(envOf(reserved, 'SMTP_PORT'), c.smtp?.port ?? 0) || 587;
+        const user = envOf(reserved, 'SMTP_USER') ?? c.smtp?.user?.trim() ?? from;
+        smtp = { host, port, user };
+    } else {
+        return { config: null, warning: `unknown email provider "${providerId}" (resend|gmail|smtp)` };
+    }
+
+    return {
+        config: {
+            provider,
+            from,
+            apiKey,
+            maxPerMin: parseInt0(envOf(reserved, 'MAX_PER_MIN'), c.maxPerMin ?? 60),
+            maxPerDay: parseInt0(envOf(reserved, 'MAX_PER_DAY'), c.maxPerDay ?? 0),
+            maxPerRecipientPerHour: parseInt0(
+                envOf(reserved, 'MAX_PER_RECIPIENT_PER_HOUR'),
+                c.maxPerRecipientPerHour ?? 5,
+            ),
+            smtp,
+        },
+        warning: null,
+    };
+}

package/src/devserver/email/index.ts

@@ -0,0 +1,111 @@
+/**
+ * The dev / self-host email service — the full edge pipeline in Node, reusable
+ * by the future self-host runtime (this folder has NO Vite/devserver coupling).
+ *
+ * Split for the sync-wasm constraint: `prepare()` is SYNCHRONOUS (parse +
+ * validate + dedup + budget + per-recipient cap) and returns the terminal status
+ * to hand the guest now; `deliver()` is ASYNC (the actual provider send). A
+ * synchronous host (the dev server) fires `deliver()` and returns `Sent`
+ * optimistically; an async-capable host (a future self-host) can `await deliver()`
+ * for the true status.
+ */
+import { loadEnvFiles } from '../dotenv.js';
+import { EmailCaps } from './caps.js';
+import { resolveEmailConfig, type ResolvedEmailConfig } from './config.js';
+import { sendVia, type OutboundMessage } from './providers.js';
+import { EmailStatus } from './status.js';
+import { validRecipient } from './validate.js';
+import { parseEmailBlob, type ParsedEmail } from './wire.js';
+
+import type { EmailBackendConfig } from 'toiljs/shared';
+
+export { EmailStatus } from './status.js';
+export type { ResolvedEmailConfig } from './config.js';
+
+export interface PrepareResult {
+    /** The status to return to the guest now. `Sent` means proceed to `deliver`. */
+    readonly status: EmailStatus;
+    /** The parsed message, present iff `status === Sent` (caller should deliver). */
+    readonly parsed: ParsedEmail | null;
+}
+
+export class NodeEmailService {
+    private readonly caps = new EmailCaps();
+    constructor(private readonly config: ResolvedEmailConfig) {}
+
+    /** The configured provider id (for the startup banner / logs). */
+    get providerLabel(): string {
+        return `${this.config.provider} (${this.config.from})`;
+    }
+
+    /**
+     * Synchronous pre-send: parse the wire blob, validate the recipient, then
+     * dedup + per-minute/day budget + per-recipient cap (all committing). Returns
+     * a terminal status (`BadRecipient` / `Deduped` / `Budget` / `RecipientCapped`),
+     * or `{ status: Sent, parsed }` meaning the caller should `deliver(parsed)`.
+     */
+    prepare(blob: Buffer, now: number = Date.now()): PrepareResult {
+        const parsed = parseEmailBlob(blob);
+        if (parsed === null || !validRecipient(parsed.to)) {
+            return { status: EmailStatus.BadRecipient, parsed: null };
+        }
+        if (this.caps.isDuplicate(parsed.to, parsed.purpose, now)) {
+            return { status: EmailStatus.Deduped, parsed: null };
+        }
+        if (!this.caps.budgetOk(this.config.maxPerMin, this.config.maxPerDay, now)) {
+            return { status: EmailStatus.Budget, parsed: null };
+        }
+        if (!this.caps.recipientOk(parsed.to, this.config.maxPerRecipientPerHour, now)) {
+            return { status: EmailStatus.RecipientCapped, parsed: null };
+        }
+        return { status: EmailStatus.Sent, parsed };
+    }
+
+    /** Actually send via the configured provider; resolves to the real status. */
+    deliver(parsed: ParsedEmail): Promise<EmailStatus> {
+        const msg: OutboundMessage = {
+            from: this.config.from,
+            to: parsed.to,
+            subject: parsed.subject,
+            body: parsed.body,
+            html: parsed.html,
+        };
+        return sendVia(this.config, msg);
+    }
+}
+
+// --- Process-level singleton (one project per dev/self-host process) ----------
+
+let service: NodeEmailService | null = null;
+
+export interface EmailInitResult {
+    /** The service, or `null` when email is unconfigured / invalid. */
+    readonly service: NodeEmailService | null;
+    /** A note for the startup banner: the provider label, or a config warning. */
+    readonly note: string | null;
+}
+
+/**
+ * Build the email service from the `toil.config.ts` `email` section + the
+ * project's `.env.secrets` (`TOIL_EMAIL_*`, holding the API key) and install it
+ * as the process singleton. Call once at startup. Returns a startup note.
+ */
+export function initEmailService(
+    root: string,
+    cfgEmail: EmailBackendConfig | null | undefined,
+): EmailInitResult {
+    const reserved = loadEnvFiles(root).reserved;
+    const { config, warning } = resolveEmailConfig(cfgEmail, reserved);
+    service = config === null ? null : new NodeEmailService(config);
+    return { service, note: service === null ? warning : service.providerLabel };
+}
+
+/** The installed email service, or `null` when email is not configured. */
+export function getEmailService(): NodeEmailService | null {
+    return service;
+}
+
+/** Reset the singleton (tests). */
+export function resetEmailService(): void {
+    service = null;
+}

package/src/devserver/email/providers.ts

@@ -0,0 +1,130 @@
+/**
+ * Provider transports for the dev / self-host mailer, mirroring the edge's
+ * `mailer.rs`: Resend over `fetch` (`send_resend`) and SMTP over nodemailer
+ * (`send_smtp`). Both retry transient failures with capped backoff; a permanent
+ * rejection is terminal (`ProviderError`).
+ *
+ * nodemailer is imported lazily, so a Resend-only project never loads it.
+ */
+import { EmailStatus } from './status.js';
+import type { ResolvedEmailConfig } from './config.js';
+
+const MAX_ATTEMPTS = 3;
+const BACKOFF_BASE_MS = 200;
+const POST_TIMEOUT_MS = 10_000;
+
+/** The concrete parts of one send (already validated + rendered). */
+export interface OutboundMessage {
+    readonly from: string;
+    readonly to: string;
+    readonly subject: string;
+    /** Plain-text body (may be empty when only `html` is set). */
+    readonly body: string;
+    /** Optional HTML body (empty = plain-text send). */
+    readonly html: string;
+}
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Classify an HTTP status (or `null` for a transport failure): 2xx → `Sent`,
+ * 4xx → terminal `ProviderError` (a bad address keeps being bad), else
+ * (5xx / transport) → retry.
+ */
+function classifyHttp(status: number | null): EmailStatus | 'retry' {
+    if (status !== null && status >= 200 && status < 300) return EmailStatus.Sent;
+    if (status !== null && status >= 400 && status < 500) return EmailStatus.ProviderError;
+    return 'retry';
+}
+
+/** Drive one Resend POST with retry. */
+export async function sendResend(
+    cfg: ResolvedEmailConfig,
+    msg: OutboundMessage,
+): Promise<EmailStatus> {
+    const payload: Record<string, unknown> = {
+        from: msg.from,
+        to: [msg.to],
+        subject: msg.subject,
+    };
+    if (msg.body.length > 0) payload.text = msg.body;
+    if (msg.html.length > 0) payload.html = msg.html;
+
+    let backoff = BACKOFF_BASE_MS;
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+        let status: number | null = null;
+        try {
+            const res = await fetch('https://api.resend.com/emails', {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${cfg.apiKey}`,
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify(payload),
+                signal: AbortSignal.timeout(POST_TIMEOUT_MS),
+            });
+            status = res.status;
+        } catch {
+            status = null; // transport error → retry
+        }
+        const verdict = classifyHttp(status);
+        if (verdict !== 'retry') return verdict;
+        if (attempt === MAX_ATTEMPTS) break;
+        await sleep(backoff);
+        backoff *= 2;
+    }
+    return EmailStatus.ProviderError;
+}
+
+/** Send one email over SMTP (nodemailer) with retry. */
+export async function sendSmtp(
+    cfg: ResolvedEmailConfig,
+    msg: OutboundMessage,
+): Promise<EmailStatus> {
+    const smtp = cfg.smtp;
+    if (smtp === undefined) return EmailStatus.ProviderError; // resolve() guarantees Some for smtp
+
+    let transporter: import('nodemailer').Transporter;
+    try {
+        const nodemailer = await import('nodemailer');
+        transporter = nodemailer.createTransport({
+            host: smtp.host,
+            port: smtp.port,
+            secure: smtp.port === 465, // 465 = implicit TLS; else STARTTLS
+            auth: { user: smtp.user, pass: cfg.apiKey },
+            connectionTimeout: POST_TIMEOUT_MS,
+            greetingTimeout: POST_TIMEOUT_MS,
+        });
+    } catch {
+        // nodemailer not installed: SMTP unavailable.
+        return EmailStatus.ProviderError;
+    }
+
+    let backoff = BACKOFF_BASE_MS;
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+        try {
+            await transporter.sendMail({
+                from: msg.from,
+                to: msg.to,
+                subject: msg.subject,
+                text: msg.body.length > 0 ? msg.body : undefined,
+                html: msg.html.length > 0 ? msg.html : undefined,
+            });
+            return EmailStatus.Sent;
+        } catch (e) {
+            // SMTP 5xx is a PERMANENT failure (bad auth / rejected recipient):
+            // terminal. 4xx / transport errors are transient: retry with backoff.
+            const code = (e as { responseCode?: number }).responseCode;
+            if (typeof code === 'number' && code >= 500) return EmailStatus.ProviderError;
+            if (attempt === MAX_ATTEMPTS) break;
+            await sleep(backoff);
+            backoff *= 2;
+        }
+    }
+    return EmailStatus.ProviderError;
+}
+
+/** Dispatch to the configured provider. */
+export function sendVia(cfg: ResolvedEmailConfig, msg: OutboundMessage): Promise<EmailStatus> {
+    return cfg.provider === 'resend' ? sendResend(cfg, msg) : sendSmtp(cfg, msg);
+}

package/src/devserver/email/status.ts

@@ -0,0 +1,23 @@
+/**
+ * The `i32` status `env::email_send` returns to the guest. Byte-identical to the
+ * edge's `EmailStatus` (toil-backend `host/email.rs`, `#[repr(i32)]`) and the
+ * guest `EmailStatus` enum (`server/globals/email.ts`). `Sent` and `Deduped` are
+ * success; the rest say why it was not delivered and whether a retry could help.
+ */
+export enum EmailStatus {
+    Sent = 0,
+    /** No email config (or not enabled). */
+    Disabled = 1,
+    /** Per-process minute/day budget exhausted. Retriable later. */
+    Budget = 2,
+    /** Per-recipient hourly cap hit. Terminal for this recipient/window. */
+    RecipientCapped = 3,
+    /** An identical recent (recipient, purpose) send was collapsed. Treat as sent. */
+    Deduped = 4,
+    /** Saturated / queue full. Retriable; back off. */
+    TryLater = 5,
+    /** The recipient failed host-side validation (CRLF, multiple addresses, malformed). */
+    BadRecipient = 6,
+    /** The provider rejected the send, or transport failed after retries. Terminal. */
+    ProviderError = 7,
+}

package/src/devserver/email/validate.ts

@@ -0,0 +1,40 @@
+/**
+ * Strict single-recipient check for the guest-supplied `to`, byte-for-byte the
+ * edge's (`host/email.rs::valid_recipient`). Rejects header injection
+ * (CR/LF/NUL), multiple addresses (comma, semicolon, whitespace, angle
+ * brackets, quotes), and the obviously malformed, so a guest can never smuggle a
+ * Bcc or a second envelope recipient into the provider call. Exactly one `@`,
+ * non-empty local part, dotted domain.
+ */
+const FORBIDDEN = new Set(['\r', '\n', '\0', ',', ';', ' ', '\t', '<', '>', '"']);
+
+export function validRecipient(s: string): boolean {
+    if (s.length === 0 || Buffer.byteLength(s, 'utf8') > 320) return false;
+    for (const ch of s) {
+        if (FORBIDDEN.has(ch)) return false;
+    }
+    const parts = s.split('@');
+    if (parts.length !== 2) return false; // not exactly one '@'
+    const [local, domain] = parts;
+    return (
+        local.length > 0 &&
+        domain.includes('.') &&
+        !domain.startsWith('.') &&
+        !domain.endsWith('.')
+    );
+}
+
+/**
+ * Lenient validation of the operator-supplied `from` (`host/email.rs::valid_from`):
+ * trusted config, so the only hard requirement is no header injection; the
+ * provider validates deliverability.
+ */
+export function validFrom(s: string): boolean {
+    return (
+        Buffer.byteLength(s, 'utf8') <= 320 &&
+        s.includes('@') &&
+        !s.includes('\r') &&
+        !s.includes('\n') &&
+        !s.includes('\0')
+    );
+}