toiljs 0.0.43 → 0.0.45

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

package/src/devserver/email/wire.ts

@@ -0,0 +1,55 @@
+/**
+ * Decode the `email_send` request blob the guest writes into wasm memory — the
+ * v2 wire format, byte-for-byte the edge's (`email_send_import.rs::parse_request`
+ * and `server/globals/email.ts`):
+ *
+ *   u16 to_len | u16 subject_len | u16 purpose_len | u32 body_len | u32 html_len
+ *   [to][subject][purpose][body][html]      (14-byte LE header, then UTF-8 payloads)
+ *
+ * `html_len == 0` is a plain-text send. Returns `null` on truncation, a length
+ * that overruns the blob, trailing garbage, or non-UTF-8 — all guest encode bugs
+ * the caller maps to `BadRecipient`.
+ */
+export interface ParsedEmail {
+    readonly to: string;
+    readonly subject: string;
+    readonly purpose: string;
+    readonly body: string;
+    readonly html: string;
+}
+
+const HEADER_LEN = 14;
+
+export function parseEmailBlob(raw: Buffer): ParsedEmail | null {
+    if (raw.length < HEADER_LEN) return null;
+    const toLen = raw.readUInt16LE(0);
+    const subjectLen = raw.readUInt16LE(2);
+    const purposeLen = raw.readUInt16LE(4);
+    const bodyLen = raw.readUInt32LE(6);
+    const htmlLen = raw.readUInt32LE(10);
+
+    const total = toLen + subjectLen + purposeLen + bodyLen + htmlLen;
+    // Exact fit: the five payloads must consume the rest of the blob precisely.
+    if (HEADER_LEN + total !== raw.length) return null;
+
+    let off = HEADER_LEN;
+    const take = (n: number): string | null => {
+        const end = off + n;
+        const slice = raw.subarray(off, end);
+        // Reject invalid UTF-8 (Buffer.toString is lossy, so verify by round-trip).
+        const s = slice.toString('utf8');
+        if (Buffer.byteLength(s, 'utf8') !== n) return null;
+        off = end;
+        return s;
+    };
+
+    const to = take(toLen);
+    const subject = take(subjectLen);
+    const purpose = take(purposeLen);
+    const body = take(bodyLen);
+    const html = take(htmlLen);
+    if (to === null || subject === null || purpose === null || body === null || html === null) {
+        return null;
+    }
+    return { to, subject, purpose, body, html };
+}

package/src/devserver/env.ts

@@ -0,0 +1,30 @@
+/**
+ * Dev-only source for `Environment.get` / `getSecure`, mirroring the edge's
+ * per-tenant env store. Reads two optional dotenv files at the project root via
+ * the shared loader (`./dotenv.ts`):
+ *
+ *   - `.env`          -> plain vars  (`Environment.get`); `process.env` overlays
+ *   - `.env.secrets`  -> secrets     (`Environment.getSecure`); keep gitignored
+ *
+ * DISJOINT like the edge: `get` sees only vars, `getSecure` only secrets, so a
+ * secret never comes back through `get`. Framework-reserved `TOIL_*` keys are
+ * host-only (the email backend config reads them) and never a tenant var/secret.
+ *
+ * Cached after first read; restart `toiljs dev` to pick up edits. The edge
+ * resolves this PER TENANT from `$TOIL_ENV_DIR/<host>.env` + `<host>.env.secrets`
+ * (and the edge DB later) through a lazy, bounded cache; dev has a single
+ * project, so two files are enough and no eviction is needed.
+ */
+import { loadEnvFiles } from './dotenv.js';
+
+/** A plain var by exact key, or `null`. Reads ONLY the `.env` (vars) bucket. */
+export function devEnvGet(key: string): string | null {
+    const v = loadEnvFiles(process.cwd()).vars.get(key);
+    return v === undefined ? null : v;
+}
+
+/** A secret by exact key, or `null`. Reads ONLY the `.env.secrets` bucket. */
+export function devEnvGetSecure(key: string): string | null {
+    const v = loadEnvFiles(process.cwd()).secrets.get(key);
+    return v === undefined ? null : v;
+}

package/src/devserver/host.ts

@@ -18,6 +18,9 @@
  */
 
 import { buildCryptoImports, freshCryptoState, type CryptoState } from './crypto.js';
+import { EmailStatus, getEmailService } from './email/index.js';
+import { parseEmailBlob } from './email/wire.js';
+import { devEnvGet, devEnvGetSecure } from './env.js';
 import { ratelimitCheck } from './ratelimit.js';
 
 /** Limits identical to the edge's `set_header` / `respond_file` bounds. */
@@ -105,6 +108,32 @@ function readGuestString(ref: MemoryRef, ptr: number): string {
     return m.toString('utf16le', ptr, ptr + byteLen);
 }
 
+/**
+ * Resolve one `Environment.get`/`getSecure` lookup against the dev env source
+ * and write it into the guest buffer, with the edge's return protocol: the value
+ * byte length (`0` = present-but-empty), `-1` if `outCap` is too small (the guest
+ * retries with a bigger buffer), `-2` if the key is absent.
+ */
+function envLookup(
+    ref: MemoryRef,
+    keyPtr: number,
+    keyLen: number,
+    outPtr: number,
+    outCap: number,
+    secure: boolean,
+): number {
+    const key = readBytes(ref, keyPtr, keyLen).toString('utf8');
+    const val = secure ? devEnvGetSecure(key) : devEnvGet(key);
+    if (val === null) return -2; // ABSENT
+    const bytes = Buffer.from(val, 'utf8');
+    if (bytes.length > outCap) return -1; // TOO_SMALL
+    const m = mem(ref);
+    if (outPtr < 0 || outPtr + bytes.length > m.length)
+        throw new Error('env_get write out of bounds');
+    bytes.copy(m, outPtr);
+    return bytes.length;
+}
+
 /**
  * Build the `env` import object for one instance. `state` collects what the
  * imperative imports produce during a dispatch; bind a fresh state per request.
@@ -183,23 +212,53 @@ export function buildHostImports(ref: MemoryRef, state: DispatchState): WebAssem
                 return d.allowed ? 1 : -Math.max(1, d.retryAfterSecs);
             },
 
-            // `env::email_send`: the dev server has no email provider, so it
-            // parses the recipient for a log line and reports Sent (0), the same
-            // i32 contract the edge returns. The suspension is a host-side concern
-            // on the edge (call_async); the wasm just sees an i32 either way.
+            // `env::email_send`: the FULL email pipeline in dev (./email): parse +
+            // recipient validation + dedup + per-min/day budget + per-recipient cap
+            // run SYNCHRONOUSLY (exact status — BadRecipient/Deduped/Budget/
+            // RecipientCapped), then the real provider send is FIRE-AND-FORGET (a
+            // sync wasm import can't await it), so the guest gets Sent optimistically
+            // and the true outcome is logged. Unconfigured email stays a log-only
+            // mock returning Sent. Mirrors the edge's `email_send_import.rs`.
             email_send: (reqPtr: number, reqLen: number): number => {
-                // Header: u16 to_len | u16 subj_len | u16 purpose_len | u32 body_len
-                // | u32 html_len (14 bytes), then payloads; `to` is first.
                 const raw = readBytes(ref, reqPtr, reqLen);
-                let to = '<unparsed>';
-                if (raw.length >= 14) {
-                    const toLen = raw.readUInt16LE(0);
-                    if (14 + toLen <= raw.length) to = raw.toString('utf8', 14, 14 + toLen);
+                const svc = getEmailService();
+                if (svc === null) {
+                    const to = parseEmailBlob(raw)?.to ?? '<unparsed>';
+                    process.stdout.write(`  ✉ dev email_send -> ${to} (no email config; not sent)\n`);
+                    return EmailStatus.Sent;
                 }
-                process.stdout.write(`  ✉ dev email_send -> ${to} (not actually sent)\n`);
-                return 0; // EmailStatus.Sent
+                const { status, parsed } = svc.prepare(raw);
+                if (parsed === null) {
+                    process.stdout.write(`  ✉ dev email_send -> ${EmailStatus[status]}\n`);
+                    return status;
+                }
+                void svc
+                    .deliver(parsed)
+                    .then((s) => {
+                        const label = s === EmailStatus.Sent ? 'sent' : EmailStatus[s];
+                        process.stdout.write(`  ✉ dev email_send -> ${parsed.to} (${label})\n`);
+                    })
+                    .catch((e: unknown) => {
+                        process.stdout.write(`  ✉ dev email_send -> ${parsed.to} (error: ${String(e)})\n`);
+                    });
+                return EmailStatus.Sent; // optimistic; sync wasm can't await the send
             },
 
+            // `Environment.get` / `getSecure`: copy one tenant env value into the
+            // guest buffer. Returns the byte length (0 = present-but-empty), -1 if
+            // the buffer is too small (the guest retries bigger), -2 if absent.
+            // Disjoint buckets: `env_get` reads vars, `env_get_secure` reads
+            // secrets. Mirrors the edge's `env_get_import.rs`; the dev source is
+            // `.env` (+ process.env vars) and `.env.secrets` (see ./env.ts).
+            env_get: (keyPtr: number, keyLen: number, outPtr: number, outCap: number): number =>
+                envLookup(ref, keyPtr, keyLen, outPtr, outCap, false),
+            env_get_secure: (
+                keyPtr: number,
+                keyLen: number,
+                outPtr: number,
+                outCap: number,
+            ): number => envLookup(ref, keyPtr, keyLen, outPtr, outCap, true),
+
             thread_spawn: (_startArg: number): number => -1,
 
             // `Date.now()` -> wall-clock milliseconds, matching the edge host.

package/src/devserver/index.ts

@@ -25,7 +25,10 @@ import path from 'node:path';
 import { Server, type Request, type Response } from '@dacely/hyper-express';
 import pc from 'picocolors';
 
+import type { EmailBackendConfig } from 'toiljs/shared';
+
 import { applyCacheRule, lookupCache } from './cache.js';
+import { initEmailService } from './email/index.js';
 import { METHOD_CODES, type EnvelopeRequest } from './envelope.js';
 import { WasmServerModule } from './module.js';
 import { proxyToVite, wireWebsocketProxy, type ViteTarget } from './proxy.js';
@@ -81,6 +84,12 @@ export interface DevServerOptions {
     readonly vite: ViteTarget;
     /** Max request body bytes. Default 8 MB. */
     readonly maxBodyLength?: number;
+    /**
+     * The `toil.config.ts` `server.email` section (non-secret). When set (and the
+     * API key is in `.env.secrets`), `EmailService.send` really sends in dev;
+     * otherwise it stays a log-only mock. See `./email`.
+     */
+    readonly email?: EmailBackendConfig;
 }
 
 /** A running dev server. */
@@ -170,6 +179,17 @@ function sendWasmResponse(
 export async function startDevServer(options: DevServerOptions): Promise<RunningDevServer> {
     const host = options.host ?? '127.0.0.1';
     const root = path.resolve(options.root);
+
+    // Wire the email service from toil.config `server.email` + `.env.secrets`
+    // (TOIL_EMAIL_*). Configured -> real sends; otherwise the import stays a
+    // log-only mock. A partial-but-invalid config logs why it stayed off.
+    const emailInit = initEmailService(root, options.email);
+    if (emailInit.service !== null) {
+        process.stdout.write(pc.dim(`  ✉ email enabled: ${emailInit.note}`) + '\n');
+    } else if (emailInit.note !== null) {
+        process.stdout.write(pc.yellow('  ! ') + pc.dim(`email off: ${emailInit.note}`) + '\n');
+    }
+
     const module = new WasmServerModule(options.wasmFile);
 
     let warnedMissing = false;