toiljs 0.0.44 → 0.0.45

package/src/devserver/host.ts

@@ -18,6 +18,8 @@
  */
 
 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';
 
@@ -210,21 +212,36 @@ 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

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;

package/src/shared/index.ts

@@ -8,3 +8,39 @@ export const FRAMEWORK_NAME = 'toiljs';
 export interface ToilTarget {
     readonly name: 'client' | 'compiler' | 'cli' | 'server';
 }
+
+/** SMTP connection config (non-secret) for the `smtp` / `gmail` providers. */
+export interface SmtpBackendConfig {
+    /** SMTP host. Empty + provider `gmail` defaults to `smtp.gmail.com`. */
+    readonly host?: string;
+    /** Submission port. `0`/unset defaults to 587 (STARTTLS); 465 = implicit TLS. */
+    readonly port?: number;
+    /** SMTP username. Defaults to `from`. */
+    readonly user?: string;
+}
+
+/**
+ * The **non-secret** email backend config — the typed `email` section of
+ * `toil.config.ts` (`server.email`), consumed by the dev server and the future
+ * Node self-host. The provider API key / SMTP password is a SECRET and is NEVER
+ * here: it comes from `.env.secrets` (`TOIL_EMAIL_API_KEY`). Any `TOIL_EMAIL_*`
+ * env var overrides the matching field here.
+ *
+ * Mirrors the edge's `TOIL_EMAIL_*` keys (toil-backend `host/email.rs`
+ * `EmailSection`). Lives in `toiljs/shared` so both the compiler (config schema)
+ * and the dev server (resolver) can reference it regardless of build order.
+ */
+export interface EmailBackendConfig {
+    /** `"resend"` (JSON API) | `"gmail"` | `"smtp"` (SMTP). Default `"resend"`. */
+    readonly provider?: 'resend' | 'gmail' | 'smtp';
+    /** The "from" address. Validated (single address, no CRLF). */
+    readonly from?: string;
+    /** Per-process send ceiling, sends/minute (rolling). `0` = unlimited. Default 60. */
+    readonly maxPerMin?: number;
+    /** Per-process send ceiling, sends/day (rolling). `0` = unlimited. Default 0. */
+    readonly maxPerDay?: number;
+    /** Per-recipient hourly cap (anti-abuse). Default 5. */
+    readonly maxPerRecipientPerHour?: number;
+    /** SMTP connection details (the `gmail` / `smtp` providers). */
+    readonly smtp?: SmtpBackendConfig;
+}

package/test/devserver-email.test.ts

@@ -0,0 +1,241 @@
+/**
+ * The dev / self-host email pipeline (src/devserver/email): wire parse,
+ * recipient validation, in-process caps (dedup + per-recipient + per-min/day
+ * budget), config resolution (toil.config + TOIL_EMAIL_* env), the Resend
+ * transport, and the NodeEmailService prepare/deliver split. Mirrors the edge
+ * (toil-backend host/email.rs, mailer.rs, email_budget.rs).
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { EmailCaps } from '../src/devserver/email/caps.js';
+import { resolveEmailConfig, type ResolvedEmailConfig } from '../src/devserver/email/config.js';
+import { NodeEmailService } from '../src/devserver/email/index.js';
+import { sendResend } from '../src/devserver/email/providers.js';
+import { EmailStatus } from '../src/devserver/email/status.js';
+import { validFrom, validRecipient } from '../src/devserver/email/validate.js';
+import { parseEmailBlob } from '../src/devserver/email/wire.js';
+
+/** Encode an `email_send` blob exactly like the guest (`server/globals/email.ts`). */
+function encodeBlob(to: string, subject: string, purpose: string, body: string, html: string): Buffer {
+    const e = (s: string): Buffer => Buffer.from(s, 'utf8');
+    const [t, s, p, b, h] = [e(to), e(subject), e(purpose), e(body), e(html)];
+    const head = Buffer.alloc(14);
+    head.writeUInt16LE(t.length, 0);
+    head.writeUInt16LE(s.length, 2);
+    head.writeUInt16LE(p.length, 4);
+    head.writeUInt32LE(b.length, 6);
+    head.writeUInt32LE(h.length, 10);
+    return Buffer.concat([head, t, s, p, b, h]);
+}
+
+const reserved = (o: Record<string, string>): Map<string, string> => new Map(Object.entries(o));
+
+describe('validate', () => {
+    it('accepts plain addresses, rejects injection / multiple / malformed', () => {
+        expect(validRecipient('user@example.com')).toBe(true);
+        expect(validRecipient('a.b+tag@sub.example.co')).toBe(true);
+        for (const bad of [
+            'a@b.com\r\nBcc: evil@x.com',
+            'a@b.com\nDATA',
+            'a@b.com\0',
+            'a@b.com,c@d.com',
+            'a@b.com;c@d.com',
+            'a@b.com c@d.com',
+            '<a@b.com>',
+            '"a"@b.com',
+            '',
+            'nobody',
+            'a@b@c.com',
+            '@b.com',
+            'a@bcom',
+            'a@.com',
+            'a@b.',
+        ]) {
+            expect(validRecipient(bad), bad).toBe(false);
+        }
+    });
+
+    it('validFrom is lenient but rejects header injection', () => {
+        expect(validFrom('me@example.com')).toBe(true);
+        expect(validFrom('a@b.com\r\nBcc: x')).toBe(false);
+        expect(validFrom('no-at-sign')).toBe(false);
+    });
+});
+
+describe('wire parse', () => {
+    it('round-trips a well-formed blob', () => {
+        const raw = encodeBlob('a@b.com', 'Hi', 'verify', '123456', '<b>x</b>');
+        const p = parseEmailBlob(raw);
+        expect(p).toEqual({ to: 'a@b.com', subject: 'Hi', purpose: 'verify', body: '123456', html: '<b>x</b>' });
+    });
+
+    it('rejects truncated / trailing-garbage / non-UTF8', () => {
+        expect(parseEmailBlob(Buffer.alloc(4))).toBeNull(); // shorter than header
+        const raw = encodeBlob('a@b.com', 's', 'p', 'body', '');
+        expect(parseEmailBlob(raw.subarray(0, raw.length - 1))).toBeNull(); // truncated payload
+        expect(parseEmailBlob(Buffer.concat([raw, Buffer.from([0xff])]))).toBeNull(); // trailing garbage
+        const bad = Buffer.from(raw);
+        bad[bad.length - 1] = 0xff; // corrupt last body byte -> invalid UTF-8
+        expect(parseEmailBlob(bad)).toBeNull();
+    });
+});
+
+describe('caps', () => {
+    it('dedup collapses an identical (recipient, purpose) within the window', () => {
+        const c = new EmailCaps();
+        expect(c.isDuplicate('a@b.com', 'verify', 0)).toBe(false); // first
+        expect(c.isDuplicate('a@b.com', 'verify', 1_000)).toBe(true); // repeat in window
+        expect(c.isDuplicate('a@b.com', 'reset', 1_000)).toBe(false); // different purpose
+        expect(c.isDuplicate('a@b.com', 'verify', 31_000)).toBe(false); // after the 30s window
+    });
+
+    it('per-recipient hourly cap holds then resets', () => {
+        const c = new EmailCaps();
+        expect(c.recipientOk('x@y.com', 2, 0)).toBe(true);
+        expect(c.recipientOk('x@y.com', 2, 10)).toBe(true);
+        expect(c.recipientOk('x@y.com', 2, 20)).toBe(false); // third over the cap
+        expect(c.recipientOk('z@y.com', 2, 20)).toBe(true); // a different recipient is independent
+        expect(c.recipientOk('x@y.com', 2, 3_600_001)).toBe(true); // next hour resets
+    });
+
+    it('per-minute and per-day budgets both gate, 0 = unlimited', () => {
+        const c = new EmailCaps();
+        expect(c.budgetOk(2, 0, 0)).toBe(true);
+        expect(c.budgetOk(2, 0, 0)).toBe(true);
+        expect(c.budgetOk(2, 0, 0)).toBe(false); // minute cap (2) exhausted at the same instant
+        // A separate budget instance with only a day cap.
+        const d = new EmailCaps();
+        expect(d.budgetOk(0, 1, 0)).toBe(true);
+        expect(d.budgetOk(0, 1, 0)).toBe(false); // day cap (1) exhausted
+        // Unlimited (0/0) never blocks.
+        const u = new EmailCaps();
+        for (let i = 0; i < 100; i++) expect(u.budgetOk(0, 0, i)).toBe(true);
+    });
+});
+
+describe('config resolution', () => {
+    it('is unconfigured (silent) with no config + no env', () => {
+        expect(resolveEmailConfig(null, reserved({}))).toEqual({ config: null, warning: null });
+    });
+
+    it('merges toil.config + env, api key from env, env wins', () => {
+        const { config } = resolveEmailConfig(
+            { provider: 'resend', from: 'cfg@x.com', maxPerMin: 10 },
+            reserved({ TOIL_EMAIL_API_KEY: 're_k', TOIL_EMAIL_FROM: 'env@x.com' }),
+        );
+        expect(config).toMatchObject({ provider: 'resend', from: 'env@x.com', apiKey: 're_k', maxPerMin: 10 });
+    });
+
+    it('gmail resolves to smtp with defaults', () => {
+        const { config } = resolveEmailConfig(
+            { provider: 'gmail', from: 'me@gmail.com' },
+            reserved({ TOIL_EMAIL_API_KEY: 'app-pw' }),
+        );
+        expect(config).toMatchObject({ provider: 'smtp', smtp: { host: 'smtp.gmail.com', port: 587, user: 'me@gmail.com' } });
+    });
+
+    it('warns (off) on partial/invalid config', () => {
+        // from but no api key
+        expect(resolveEmailConfig({ from: 'a@b.com' }, reserved({})).warning).toMatch(/API_KEY/);
+        // bad from
+        expect(resolveEmailConfig({ from: 'no-at' }, reserved({ TOIL_EMAIL_API_KEY: 'k' })).warning).toMatch(/from/);
+        // smtp without host
+        expect(
+            resolveEmailConfig({ provider: 'smtp', from: 'a@b.com' }, reserved({ TOIL_EMAIL_API_KEY: 'k' })).warning,
+        ).toMatch(/SMTP_HOST/);
+        // unknown provider
+        expect(
+            resolveEmailConfig({ from: 'a@b.com' }, reserved({ TOIL_EMAIL_API_KEY: 'k', TOIL_EMAIL_PROVIDER: 'mailgun' }))
+                .warning,
+        ).toMatch(/unknown/);
+    });
+
+    it('TOIL_EMAIL_ENABLED=false disables silently', () => {
+        expect(
+            resolveEmailConfig({ provider: 'resend', from: 'a@b.com' }, reserved({ TOIL_EMAIL_API_KEY: 'k', TOIL_EMAIL_ENABLED: 'false' })),
+        ).toEqual({ config: null, warning: null });
+    });
+});
+
+describe('Resend transport', () => {
+    afterEach(() => vi.unstubAllGlobals());
+
+    const cfg: ResolvedEmailConfig = {
+        provider: 'resend',
+        from: 'noreply@x.com',
+        apiKey: 're_secret',
+        maxPerMin: 0,
+        maxPerDay: 0,
+        maxPerRecipientPerHour: 0,
+    };
+
+    it('2xx -> Sent, with the right payload + Bearer auth', async () => {
+        const fetchMock = vi.fn(async () => new Response(null, { status: 200 }));
+        vi.stubGlobal('fetch', fetchMock);
+        const status = await sendResend(cfg, { from: cfg.from, to: 'a@b.com', subject: 'Hi', body: 'text', html: '<b>h</b>' });
+        expect(status).toBe(EmailStatus.Sent);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        const [, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+        expect((init.headers as Record<string, string>).authorization).toBe('Bearer re_secret');
+        expect(JSON.parse(init.body as string)).toEqual({ from: 'noreply@x.com', to: ['a@b.com'], subject: 'Hi', text: 'text', html: '<b>h</b>' });
+    });
+
+    it('4xx -> ProviderError, no retry', async () => {
+        const fetchMock = vi.fn(async () => new Response(null, { status: 422 }));
+        vi.stubGlobal('fetch', fetchMock);
+        const status = await sendResend(cfg, { from: cfg.from, to: 'a@b.com', subject: 's', body: 'b', html: '' });
+        expect(status).toBe(EmailStatus.ProviderError);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+});
+
+describe('NodeEmailService pipeline', () => {
+    afterEach(() => vi.unstubAllGlobals());
+
+    const base: ResolvedEmailConfig = {
+        provider: 'resend',
+        from: 'noreply@x.com',
+        apiKey: 're_secret',
+        maxPerMin: 0,
+        maxPerDay: 0,
+        maxPerRecipientPerHour: 0,
+    };
+
+    it('prepare returns terminal statuses and a parsed message to deliver', () => {
+        const svc = new NodeEmailService(base);
+        // Bad recipient.
+        expect(svc.prepare(encodeBlob('not-an-email', 's', 'p', 'b', ''), 0).status).toBe(EmailStatus.BadRecipient);
+        // Valid -> Sent + parsed.
+        const ok = svc.prepare(encodeBlob('a@b.com', 's', 'verify', 'b', ''), 0);
+        expect(ok.status).toBe(EmailStatus.Sent);
+        expect(ok.parsed?.to).toBe('a@b.com');
+        // Identical (to, purpose) again -> Deduped.
+        expect(svc.prepare(encodeBlob('a@b.com', 's', 'verify', 'b', ''), 1_000).status).toBe(EmailStatus.Deduped);
+    });
+
+    it('enforces the per-minute budget', () => {
+        const svc = new NodeEmailService({ ...base, maxPerMin: 2 });
+        // Distinct recipients so dedup/recipient caps don't fire first.
+        expect(svc.prepare(encodeBlob('a@x.com', 's', 'p', 'b', ''), 0).status).toBe(EmailStatus.Sent);
+        expect(svc.prepare(encodeBlob('b@x.com', 's', 'p', 'b', ''), 0).status).toBe(EmailStatus.Sent);
+        expect(svc.prepare(encodeBlob('c@x.com', 's', 'p', 'b', ''), 0).status).toBe(EmailStatus.Budget);
+    });
+
+    it('enforces the per-recipient hourly cap', () => {
+        const svc = new NodeEmailService({ ...base, maxPerRecipientPerHour: 2 });
+        // Same recipient, distinct purposes so dedup doesn't fire.
+        expect(svc.prepare(encodeBlob('a@x.com', 's', 'p1', 'b', ''), 0).status).toBe(EmailStatus.Sent);
+        expect(svc.prepare(encodeBlob('a@x.com', 's', 'p2', 'b', ''), 0).status).toBe(EmailStatus.Sent);
+        expect(svc.prepare(encodeBlob('a@x.com', 's', 'p3', 'b', ''), 0).status).toBe(EmailStatus.RecipientCapped);
+    });
+
+    it('deliver actually sends via the provider', async () => {
+        const fetchMock = vi.fn(async () => new Response(null, { status: 200 }));
+        vi.stubGlobal('fetch', fetchMock);
+        const svc = new NodeEmailService(base);
+        const { parsed } = svc.prepare(encodeBlob('a@b.com', 's', 'p', 'b', ''), 0);
+        expect(parsed).not.toBeNull();
+        expect(await svc.deliver(parsed!)).toBe(EmailStatus.Sent);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+});