@groundmail/groundhog 0.0.0-stage → 0.1.0

package/dist/server.js

@@ -0,0 +1,450 @@
+import { readFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { extname, join, normalize } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { FAULT_LABELS, Faults, parseFaultKind } from './faults.js';
+import { GroundmailAccount, withUtm } from './groundmail-account.js';
+import { HttpError, RequestContext, Router } from './http.js';
+import { ingestApiSend } from './mime.js';
+import { HTTP_PROVIDERS, PROVIDER_MODULES, WEBHOOK_FORMATS } from './providers/index.js';
+import { createSmtpServer, SMTP_FAULT_REPLIES } from './smtp.js';
+import { EmailStore, publicEmail } from './store.js';
+import { PROVIDER_LABELS, WEBHOOK_EVENTS } from './types.js';
+import { formatFor, verificationKeys, Webhooks } from './webhooks.js';
+export const VERSION = (() => {
+    try {
+        const pkg = JSON.parse(readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8'));
+        return pkg.version;
+    }
+    catch {
+        return '0.0.0';
+    }
+})();
+const UI_DIR = fileURLToPath(new URL('./ui/', import.meta.url));
+const MIME = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.ico': 'image/x-icon',
+    '.json': 'application/json',
+};
+function summary(email) {
+    const { html: _html, text, headers: _headers, ...rest } = email;
+    return { ...rest, preview: (text ?? '').replace(/\s+/g, ' ').trim().slice(0, 160) };
+}
+function filterFrom(ctx) {
+    return {
+        to: ctx.query('to'),
+        from: ctx.query('from'),
+        subject: ctx.query('subject'),
+        q: ctx.query('q') ?? ctx.query('query'),
+        via: ctx.query('via'),
+        since: ctx.query('since'),
+    };
+}
+/** Point cid: images at the attachment URL so inline images render. */
+function htmlForFrame(email, scheme) {
+    let html = email.html ?? `<pre style="white-space:pre-wrap;font:14px/1.5 ui-monospace,Menlo,monospace">${(email.text ?? '').replace(/[&<>]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' })[c])}</pre>`;
+    for (const attachment of email.attachments) {
+        if (!attachment.contentId)
+            continue;
+        const url = `/api/emails/${email.id}/attachments/${attachment.id}`;
+        html = html.split(`cid:${attachment.contentId}`).join(url);
+    }
+    const base = '<base target="_blank">';
+    const darkStyle = scheme === 'dark' ? '<meta name="color-scheme" content="dark"><style>:root{color-scheme:dark}</style>' : '<meta name="color-scheme" content="light">';
+    if (/<head[^>]*>/i.test(html))
+        return html.replace(/<head([^>]*)>/i, `<head$1>${base}${darkStyle}`);
+    if (/<html[^>]*>/i.test(html))
+        return html.replace(/<html([^>]*)>/i, `<html$1><head><meta charset="utf-8">${base}${darkStyle}</head>`);
+    return `<!doctype html><html><head><meta charset="utf-8">${base}${darkStyle}</head><body>${html}</body></html>`;
+}
+async function sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+const SAMPLE_CODE = () => String(Math.floor(100000 + Math.random() * 900000));
+export async function startGroundhog(options = {}) {
+    const log = options.log ?? (() => { });
+    const store = new EmailStore({ max: options.maxEmails, file: options.storeFile });
+    await store.load();
+    const faults = new Faults(options.faultTimeoutMs ?? 30_000);
+    let baseUrl = 'http://localhost:3025';
+    const webhooks = new Webhooks(options.webhooks ?? {}, () => baseUrl);
+    const account = new GroundmailAccount({ apiUrl: options.groundmailApiUrl, openBrowser: options.openBrowser });
+    const sse = new Set();
+    const broadcast = (event, data) => {
+        const payload = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+        for (const client of sse)
+            client.res.write(payload);
+    };
+    const ingest = (email) => {
+        store.add(email);
+        log(`caught ${email.id} via ${email.via}: "${email.subject}" → ${email.to.map((a) => a.address).join(', ') || '(no to)'}`);
+        if (webhooks.settings.autoDelivered && webhooks.settings.url) {
+            void webhooks.fire(email, 'delivered').catch(() => { });
+        }
+        return email;
+    };
+    store.on('email', (email) => broadcast('email', summary(publicEmail(email))));
+    store.on('delete', (id) => broadcast('delete', { id }));
+    store.on('clear', () => broadcast('clear', {}));
+    faults.on('change', (state) => broadcast('faults', state));
+    webhooks.on('delivery', (entry) => broadcast('webhook', entry));
+    webhooks.on('settings', (settings) => broadcast('webhook-settings', settings));
+    account.on('change', (status) => broadcast('account', status));
+    const hub = {
+        ingest,
+        get: (id) => store.get(id),
+        async guard(ctx, provider) {
+            const kind = faults.take();
+            if (!kind)
+                return false;
+            log(`simulated ${FAULT_LABELS[kind].label.toLowerCase()} on ${PROVIDER_LABELS[provider.id]} ${ctx.method} ${ctx.url.pathname}`);
+            broadcast('fault-fired', { kind, provider: provider.id, path: ctx.url.pathname });
+            if (kind === 'timeout') {
+                await sleep(faults.get().timeoutMs);
+                ctx.req.socket.destroy();
+                return true;
+            }
+            ctx.send(provider.fail(kind, ctx));
+            return true;
+        },
+    };
+    const router = new Router();
+    for (const provider of HTTP_PROVIDERS)
+        provider.register?.(router, hub);
+    // ---- Testing API ---------------------------------------------------------
+    router.get('/api/health', () => ({
+        status: 200,
+        body: { ok: true, name: 'groundhog', version: VERSION, smtpPort, httpPort, emails: store.count() },
+    }));
+    router.get('/api/info', () => ({
+        status: 200,
+        body: {
+            version: VERSION,
+            smtpPort,
+            httpPort,
+            url: baseUrl,
+            providers: Object.fromEntries(HTTP_PROVIDERS.map((p) => [p.id, { label: PROVIDER_LABELS[p.id], events: p.eventNames }])),
+            faultReplies: { smtp: SMTP_FAULT_REPLIES },
+            links: {
+                groundmail: withUtm('https://groundmail.dev/', 'header'),
+                signup: withUtm('https://app.groundmail.dev/signup', 'go_live'),
+                docs: withUtm('https://docs.groundmail.dev/', 'go_live'),
+                repo: 'https://github.com/Groundmail/groundhog',
+            },
+        },
+    }));
+    router.get('/api/emails', (ctx) => {
+        const limit = Math.min(Number(ctx.query('limit')) || 100, 1000);
+        const emails = store.list(filterFrom(ctx), limit).map(publicEmail);
+        const brief = ctx.query('summary') === '1' || ctx.query('summary') === 'true';
+        return { status: 200, body: { data: brief ? emails.map(summary) : emails, total: store.count() } };
+    });
+    router.delete('/api/emails', () => {
+        store.clear();
+        return { status: 200, body: { deleted: true } };
+    });
+    router.get('/api/emails/latest', (ctx) => {
+        const email = store.latest(filterFrom(ctx));
+        if (!email)
+            return { status: 404, body: { error: 'No email matches' } };
+        return { status: 200, body: publicEmail(email) };
+    });
+    router.post('/api/emails/sample', async () => {
+        const code = SAMPLE_CODE();
+        const email = await ingestApiSend({
+            from: { name: 'Acme', address: 'auth@acme.test' },
+            to: [{ name: 'Ada', address: 'ada@example.com' }],
+            subject: 'Your Acme sign-in code',
+            html: `<!doctype html><html><body style="margin:0;padding:24px;background:#f4f4f5;font-family:-apple-system,Segoe UI,Roboto,sans-serif"><div style="max-width:480px;margin:0 auto;background:#fff;border-radius:10px;padding:32px;color:#111827"><div style="font-size:13px;font-weight:700;letter-spacing:.4px;color:#6b7280">ACME</div><h1 style="font-size:22px;margin:12px 0">Your sign-in code</h1><p style="color:#374151;line-height:1.5">Enter this code to finish signing in. It expires in 10 minutes.</p><div style="font:700 30px ui-monospace,Menlo,monospace;letter-spacing:8px;text-align:center;padding:14px;background:#f3f4f6;border-radius:8px">${code}</div><p style="margin-top:20px"><a href="http://localhost:3000/login?code=${code}" style="background:#4f46e5;color:#fff;padding:12px 20px;border-radius:6px;text-decoration:none;display:inline-block">Sign in</a></p><p style="font-size:12px;color:#6b7280;border-top:1px solid #e5e7eb;padding-top:14px">A sample email from Groundhog. Nothing was sent anywhere.</p></div></body></html>`,
+            text: `Your sign-in code\n\nEnter this code to finish signing in. It expires in 10 minutes.\n\n${code}\n\nSign in: http://localhost:3000/login?code=${code}`,
+        }, { via: 'smtp', tags: ['sample'] });
+        ingest(email);
+        return { status: 201, body: publicEmail(email) };
+    });
+    router.get('/api/emails/:id', (ctx) => {
+        const email = store.get(ctx.params.id);
+        if (!email)
+            throw new HttpError(404, 'Email not found');
+        return { status: 200, body: publicEmail(email) };
+    });
+    router.delete('/api/emails/:id', (ctx) => {
+        if (!store.delete(ctx.params.id))
+            throw new HttpError(404, 'Email not found');
+        return { status: 200, body: { deleted: true } };
+    });
+    router.get('/api/emails/:id/source', (ctx) => {
+        const email = store.get(ctx.params.id);
+        if (!email)
+            throw new HttpError(404, 'Email not found');
+        const download = ctx.query('download') != null;
+        return {
+            status: 200,
+            headers: {
+                'Content-Type': download ? 'message/rfc822' : 'text/plain; charset=utf-8',
+                ...(download ? { 'Content-Disposition': `attachment; filename="${email.id}.eml"` } : {}),
+            },
+            body: email.raw,
+        };
+    });
+    router.get('/api/emails/:id/html', (ctx) => {
+        const email = store.get(ctx.params.id);
+        if (!email)
+            throw new HttpError(404, 'Email not found');
+        return {
+            status: 200,
+            headers: {
+                'Content-Type': 'text/html; charset=utf-8',
+                'Content-Security-Policy': "sandbox allow-popups allow-popups-to-escape-sandbox; default-src 'none'; img-src * data: blob:; style-src 'unsafe-inline' *; font-src * data:; media-src * data:",
+                'X-Content-Type-Options': 'nosniff',
+            },
+            body: htmlForFrame(email, ctx.query('scheme')),
+        };
+    });
+    router.get('/api/emails/:id/attachments/:aid', (ctx) => {
+        const email = store.get(ctx.params.id);
+        const info = email?.attachments.find((a) => a.id === ctx.params.aid);
+        const content = info && email?.attachmentContent.get(info.id);
+        if (!email || !info || !content)
+            throw new HttpError(404, 'Attachment not found');
+        const inline = ctx.query('download') == null && /^image\//.test(info.contentType);
+        return {
+            status: 200,
+            headers: {
+                'Content-Type': info.contentType,
+                'Content-Disposition': `${inline ? 'inline' : 'attachment'}; filename="${info.filename.replace(/"/g, '')}"`,
+                'X-Content-Type-Options': 'nosniff',
+                'Content-Security-Policy': "sandbox; default-src 'none'",
+            },
+            body: content,
+        };
+    });
+    router.get('/api/wait', async (ctx) => {
+        const timeout = Math.min(Math.max(Number(ctx.query('timeout')) || 30_000, 0), 300_000);
+        const controller = new AbortController();
+        ctx.req.on('close', () => controller.abort());
+        const email = await store.waitFor(filterFrom(ctx), timeout, controller.signal);
+        if (!email)
+            return { status: 408, body: { error: `No matching email within ${timeout} ms` } };
+        return { status: 200, body: publicEmail(email) };
+    });
+    // ---- Failure simulation --------------------------------------------------
+    router.get('/api/faults', () => ({ status: 200, body: faults.get() }));
+    router.post('/api/faults', async (ctx) => {
+        const body = await ctx.json();
+        const kind = parseFaultKind(body.kind ?? body.status ?? ctx.query('status') ?? ctx.query('kind'));
+        if (!kind)
+            throw new HttpError(400, 'Say which failure: status 429, 422, 401, 5xx or timeout (or kind rate_limit, invalid_recipient, unauthorized, outage, timeout)');
+        const next = Number(body.next ?? ctx.query('next') ?? 1);
+        if (!Number.isFinite(next) || next < 0)
+            throw new HttpError(400, '`next` must be 0 or more');
+        const timeoutMs = body.timeoutMs ?? body.timeout_ms;
+        return { status: 200, body: faults.set(kind, next, timeoutMs == null ? undefined : Number(timeoutMs)) };
+    });
+    router.delete('/api/faults', () => ({ status: 200, body: faults.clear() }));
+    // ---- Webhook simulation --------------------------------------------------
+    const webhookSettingsView = () => ({ ...webhooks.settings, formats: WEBHOOK_FORMATS, events: WEBHOOK_EVENTS, verification: verificationKeys(webhooks.settings) });
+    router.get('/api/webhooks', () => ({ status: 200, body: webhookSettingsView() }));
+    router.put('/api/webhooks', async (ctx) => {
+        try {
+            webhooks.update(await ctx.json());
+        }
+        catch (error) {
+            throw new HttpError(400, error.message);
+        }
+        return { status: 200, body: webhookSettingsView() };
+    });
+    router.get('/api/webhooks/deliveries', (ctx) => ({ status: 200, body: { data: webhooks.deliveries(ctx.query('email')) } }));
+    router.delete('/api/webhooks/deliveries', () => {
+        webhooks.clearLog();
+        return { status: 200, body: { deleted: true } };
+    });
+    router.post('/api/emails/:id/webhooks', async (ctx) => {
+        const email = store.get(ctx.params.id);
+        if (!email)
+            throw new HttpError(404, 'Email not found');
+        const body = await ctx.json();
+        const event = (body.event ?? ctx.query('event') ?? '').replace(/^email\./, '');
+        const aliases = { bounce: 'bounced', failed: 'bounced', spamreport: 'complained', complaint: 'complained', open: 'opened', click: 'clicked', delivery: 'delivered' };
+        const resolved = WEBHOOK_EVENTS.includes(event) ? event : aliases[event.toLowerCase()];
+        if (!resolved)
+            throw new HttpError(400, `event must be one of ${WEBHOOK_EVENTS.join(', ')}`);
+        try {
+            const entry = await webhooks.fire(publicEmail(email), resolved, { url: body.url, format: body.format, link: body.link });
+            return { status: 200, body: entry };
+        }
+        catch (error) {
+            throw new HttpError(400, error.message);
+        }
+    });
+    router.get('/api/emails/:id/webhooks/format', (ctx) => {
+        const email = store.get(ctx.params.id);
+        if (!email)
+            throw new HttpError(404, 'Email not found');
+        const format = formatFor(email, webhooks.settings.format);
+        return { status: 200, body: { format, events: PROVIDER_MODULES[format].eventNames } };
+    });
+    // ---- Groundmail: send to my real inbox ----------------------------------
+    router.get('/api/groundmail', () => ({ status: 200, body: account.status() }));
+    router.post('/api/groundmail/connect', async () => {
+        try {
+            return { status: 200, body: await account.connect() };
+        }
+        catch (error) {
+            throw new HttpError(502, error.message);
+        }
+    });
+    router.post('/api/groundmail/disconnect', async () => ({ status: 200, body: await account.disconnect() }));
+    router.post('/api/emails/:id/send-to-inbox', async (ctx) => {
+        const email = store.get(ctx.params.id);
+        if (!email)
+            throw new HttpError(404, 'Email not found');
+        const body = await ctx.json();
+        try {
+            return { status: 200, body: await account.sendCopy(email, body.to) };
+        }
+        catch (error) {
+            throw new HttpError(400, error.message);
+        }
+    });
+    // ---- Live updates --------------------------------------------------------
+    router.get('/api/events', (ctx) => {
+        ctx.res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive', 'X-Accel-Buffering': 'no' });
+        ctx.res.write(`event: hello\ndata: ${JSON.stringify({ version: VERSION, faults: faults.get(), account: account.status() })}\n\n`);
+        sse.add(ctx);
+        const ping = setInterval(() => ctx.res.write(': ping\n\n'), 20_000);
+        ctx.req.on('close', () => {
+            clearInterval(ping);
+            sse.delete(ctx);
+        });
+    });
+    // ---- Web UI --------------------------------------------------------------
+    const serveFile = (relative) => {
+        const path = normalize(join(UI_DIR, relative));
+        if (!path.startsWith(UI_DIR))
+            throw new HttpError(404, 'Not found');
+        try {
+            const content = readFileSync(path);
+            return { status: 200, headers: { 'Content-Type': MIME[extname(path)] ?? 'application/octet-stream', 'Cache-Control': 'no-cache' }, body: content };
+        }
+        catch {
+            throw new HttpError(404, 'Not found');
+        }
+    };
+    router.get('/', () => serveFile('index.html'));
+    router.get('/ui/*', (ctx) => serveFile(ctx.params.rest));
+    router.get('/favicon.ico', () => serveFile('favicon.svg'));
+    const handle = async (req, res) => {
+        const ctx = new RequestContext(req, res);
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Access-Control-Allow-Headers', '*');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, PATCH, DELETE, OPTIONS');
+        res.setHeader('Access-Control-Expose-Headers', '*');
+        if (ctx.method === 'OPTIONS')
+            return ctx.send({ status: 204 });
+        try {
+            const match = router.match(ctx.method, ctx.url.pathname);
+            if (match === 'method')
+                throw new HttpError(405, `${ctx.method} is not supported on ${ctx.url.pathname}`);
+            if (!match) {
+                throw new HttpError(404, `Groundhog has no route for ${ctx.method} ${ctx.url.pathname}. Provider APIs live under /groundmail, /sendgrid, /postmark, /mailgun, /resend and /ses; the testing API under /api.`);
+            }
+            ctx.params = match.params;
+            const result = await match.route.handler(ctx);
+            if (result)
+                ctx.send(result);
+        }
+        catch (error) {
+            if (error instanceof HttpError)
+                return ctx.send({ status: error.status, body: { error: error.message } });
+            log(`error on ${ctx.method} ${ctx.url.pathname}: ${error.stack ?? error}`);
+            ctx.send({ status: 500, body: { error: error.message } });
+        }
+    };
+    // ---- Listen --------------------------------------------------------------
+    const host = options.host ?? 'localhost';
+    const hosts = host === 'localhost' ? ['127.0.0.1', '::1'] : [host];
+    const httpServers = [];
+    const smtpServers = [];
+    const listenHttp = (port, address, optional) => new Promise((resolve, reject) => {
+        const server = createServer((req, res) => void handle(req, res));
+        server.keepAliveTimeout = 5000;
+        server.once('error', (error) => {
+            if (optional && (error.code === 'EADDRNOTAVAIL' || error.code === 'EAFNOSUPPORT'))
+                return resolve(null);
+            reject(error);
+        });
+        server.listen(port, address, () => {
+            httpServers.push(server);
+            resolve(server.address().port);
+        });
+    });
+    const listenSmtp = (port, address, optional) => new Promise((resolve, reject) => {
+        const server = createSmtpServer({ faults, ingest, onError: (error) => log(`smtp error: ${error.message}`) });
+        const net = server.server;
+        net.once('error', (error) => {
+            if (optional && (error.code === 'EADDRNOTAVAIL' || error.code === 'EAFNOSUPPORT'))
+                return resolve(null);
+            reject(error);
+        });
+        server.listen(port, address, () => {
+            smtpServers.push(server);
+            resolve(net.address().port);
+        });
+    });
+    let httpPort = options.httpPort ?? 3025;
+    let smtpPort = options.smtpPort ?? 1025;
+    try {
+        for (const [index, address] of hosts.entries()) {
+            const port = await listenHttp(httpPort, address, index > 0);
+            if (port != null)
+                httpPort = port;
+        }
+        if (options.smtp !== false) {
+            for (const [index, address] of hosts.entries()) {
+                const port = await listenSmtp(smtpPort, address, index > 0);
+                if (port != null)
+                    smtpPort = port;
+            }
+        }
+    }
+    catch (error) {
+        for (const server of httpServers)
+            server.close();
+        for (const server of smtpServers)
+            server.close(() => { });
+        const e = error;
+        if (e.code === 'EADDRINUSE') {
+            throw new Error(`Port ${e.port ?? ''} is already in use. Is Groundhog (or another local inbox) already running? Pick other ports with --http-port and --smtp-port.`);
+        }
+        throw error;
+    }
+    const displayHost = host === 'localhost' || host === '0.0.0.0' || host === '::' ? 'localhost' : host.includes(':') ? `[${host}]` : host;
+    baseUrl = `http://${displayHost}:${httpPort}`;
+    return {
+        url: baseUrl,
+        smtpPort,
+        httpPort,
+        host,
+        store,
+        faults,
+        webhooks,
+        account,
+        async close() {
+            for (const client of sse)
+                client.res.end();
+            sse.clear();
+            store.saveNow();
+            await Promise.all([
+                ...httpServers.map((server) => new Promise((resolve) => {
+                    server.close(() => resolve());
+                    server.closeAllConnections?.();
+                })),
+                ...smtpServers.map((server) => new Promise((resolve) => server.close(() => resolve()))),
+            ]);
+        },
+    };
+}

package/dist/signing.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Local signing keys for simulated webhooks. They are fixed, published dev keys so
+ * an app's verification code can be configured once and keep working across restarts.
+ * Never use them for anything but local development.
+ */
+import { type KeyObject } from 'node:crypto';
+export type WebhookSecrets = {
+    /** Groundmail: `Groundmail-Signature: t=…,v1=…` (HMAC-SHA256 over `t.body`). */
+    groundmail: string;
+    /** Resend (Svix): `whsec_…`; HMAC-SHA256 over `id.timestamp.body` with the base64 part as key. */
+    resend: string;
+    /** Mailgun: HTTP webhook signing key; HMAC-SHA256 over `timestamp + token`. */
+    mailgun: string;
+};
+export declare const DEFAULT_SECRETS: WebhookSecrets;
+export declare function groundmailSignature(secret: string, body: string, timestamp: number): string;
+export declare function svixSignature(secret: string, id: string, timestamp: number, body: string): string;
+export declare function mailgunSignature(signingKey: string, timestamp: string, token: string): string;
+/** SendGrid signs its Event Webhook with ECDSA P-256; this is Groundhog's fixed local key pair. */
+export declare function sendgridKeyPair(): {
+    privateKey: KeyObject;
+    publicKeyBase64: string;
+};
+/** `X-Twilio-Email-Event-Webhook-Signature`: base64 DER ECDSA-SHA256 over `timestamp + body`. */
+export declare function sendgridSignature(timestamp: string, body: string): string;

package/dist/signing.js

@@ -0,0 +1,47 @@
+/**
+ * Local signing keys for simulated webhooks. They are fixed, published dev keys so
+ * an app's verification code can be configured once and keep working across restarts.
+ * Never use them for anything but local development.
+ */
+import { createECDH, createHash, createHmac, createPrivateKey, createPublicKey, sign as cryptoSign } from 'node:crypto';
+export const DEFAULT_SECRETS = {
+    groundmail: 'whsec_groundhog_local_dev_secret',
+    resend: `whsec_${Buffer.from('groundhog-local-dev-webhook-key!').toString('base64')}`,
+    mailgun: 'groundhog-local-mailgun-signing-key',
+};
+export function groundmailSignature(secret, body, timestamp) {
+    const v1 = createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex');
+    return `t=${timestamp},v1=${v1}`;
+}
+export function svixSignature(secret, id, timestamp, body) {
+    const key = Buffer.from(secret.startsWith('whsec_') ? secret.slice(6) : secret, 'base64');
+    return `v1,${createHmac('sha256', key).update(`${id}.${timestamp}.${body}`).digest('base64')}`;
+}
+export function mailgunSignature(signingKey, timestamp, token) {
+    return createHmac('sha256', signingKey).update(`${timestamp}${token}`).digest('hex');
+}
+let sendgridKey = null;
+/** SendGrid signs its Event Webhook with ECDSA P-256; this is Groundhog's fixed local key pair. */
+export function sendgridKeyPair() {
+    if (sendgridKey)
+        return sendgridKey;
+    const d = createHash('sha256').update('groundhog-local-sendgrid-event-webhook-key').digest();
+    const ecdh = createECDH('prime256v1');
+    ecdh.setPrivateKey(d);
+    const pub = ecdh.getPublicKey();
+    const jwk = {
+        kty: 'EC',
+        crv: 'P-256',
+        d: d.toString('base64url'),
+        x: pub.subarray(1, 33).toString('base64url'),
+        y: pub.subarray(33, 65).toString('base64url'),
+    };
+    const privateKey = createPrivateKey({ key: jwk, format: 'jwk' });
+    const publicKeyBase64 = createPublicKey(privateKey).export({ type: 'spki', format: 'der' }).toString('base64');
+    sendgridKey = { privateKey, publicKeyBase64 };
+    return sendgridKey;
+}
+/** `X-Twilio-Email-Event-Webhook-Signature`: base64 DER ECDSA-SHA256 over `timestamp + body`. */
+export function sendgridSignature(timestamp, body) {
+    return cryptoSign('sha256', Buffer.from(timestamp + body), sendgridKeyPair().privateKey).toString('base64');
+}

package/dist/smtp.d.ts

@@ -0,0 +1,13 @@
+import { SMTPServer } from 'smtp-server';
+import type { Faults } from './faults.js';
+import type { FaultKind, StoredEmail } from './types.js';
+/** The SMTP reply a real server gives for each simulated failure. */
+export declare const SMTP_FAULT_REPLIES: Record<Exclude<FaultKind, 'timeout'>, {
+    code: number;
+    message: string;
+}>;
+export declare function createSmtpServer(options: {
+    faults: Faults;
+    ingest: (email: StoredEmail) => void;
+    onError?: (error: Error) => void;
+}): SMTPServer;

package/dist/smtp.js

@@ -0,0 +1,70 @@
+import { SMTPServer } from 'smtp-server';
+import { parseEmail } from './mime.js';
+function smtpError(code, message) {
+    const error = new Error(message);
+    error.responseCode = code;
+    return error;
+}
+/** The SMTP reply a real server gives for each simulated failure. */
+export const SMTP_FAULT_REPLIES = {
+    rate_limit: { code: 450, message: '4.7.1 Rate limit exceeded, try again later' },
+    invalid_recipient: { code: 550, message: '5.1.1 Recipient address rejected: user unknown' },
+    unauthorized: { code: 535, message: '5.7.8 Authentication credentials invalid' },
+    outage: { code: 451, message: '4.3.0 Temporary server failure, try again later' },
+};
+export function createSmtpServer(options) {
+    const { faults, ingest } = options;
+    const server = new SMTPServer({
+        name: 'groundhog.local',
+        banner: 'Groundhog local inbox. Nothing is delivered.',
+        authOptional: true,
+        disabledCommands: ['STARTTLS'],
+        allowInsecureAuth: true,
+        size: 50 * 1024 * 1024,
+        logger: false,
+        onAuth(_auth, _session, callback) {
+            callback(null, { user: 'groundhog' });
+        },
+        onMailFrom(_address, session, callback) {
+            const fault = faults.take();
+            session.groundhogFault = fault;
+            if (!fault || fault === 'invalid_recipient')
+                return callback();
+            if (fault === 'timeout') {
+                const delay = faults.get().timeoutMs;
+                setTimeout(() => callback(smtpError(421, '4.4.2 Connection timed out')), delay).unref?.();
+                return;
+            }
+            const reply = SMTP_FAULT_REPLIES[fault];
+            callback(smtpError(reply.code, reply.message));
+        },
+        onRcptTo(_address, session, callback) {
+            if (session.groundhogFault === 'invalid_recipient') {
+                const reply = SMTP_FAULT_REPLIES.invalid_recipient;
+                return callback(smtpError(reply.code, reply.message));
+            }
+            callback();
+        },
+        onData(stream, session, callback) {
+            const chunks = [];
+            stream.on('data', (chunk) => chunks.push(chunk));
+            stream.on('end', async () => {
+                if (stream.sizeExceeded) {
+                    return callback(smtpError(552, '5.3.4 Message too big'));
+                }
+                try {
+                    const envelopeTo = session.envelope.rcptTo.map((rcpt) => ({ name: '', address: rcpt.address }));
+                    const email = await parseEmail(Buffer.concat(chunks), { via: 'smtp', envelopeTo });
+                    ingest(email);
+                    callback(null, `2.0.0 Caught as ${email.id}. Nothing was delivered.`);
+                }
+                catch (error) {
+                    options.onError?.(error);
+                    callback(smtpError(451, '4.3.0 Could not read the message'));
+                }
+            });
+        },
+    });
+    server.on('error', (error) => options.onError?.(error));
+    return server;
+}

package/dist/store.d.ts

@@ -0,0 +1,35 @@
+import { EventEmitter } from 'node:events';
+import type { Email, StoredEmail } from './types.js';
+export type EmailFilter = {
+    to?: string;
+    from?: string;
+    subject?: string;
+    q?: string;
+    via?: string;
+    since?: string | Date;
+};
+export declare function publicEmail(email: StoredEmail): Email;
+export declare function matches(email: Email, filter: EmailFilter): boolean;
+/** In-memory inbox, newest first. Optionally saved to a JSON file. */
+export declare class EmailStore extends EventEmitter {
+    private readonly options;
+    private emails;
+    private saveTimer;
+    constructor(options?: {
+        max?: number;
+        file?: string;
+    });
+    get max(): number;
+    load(): Promise<void>;
+    private scheduleSave;
+    saveNow(): void;
+    add(email: StoredEmail): StoredEmail;
+    list(filter?: EmailFilter, limit?: number): StoredEmail[];
+    count(): number;
+    get(id: string): StoredEmail | undefined;
+    latest(filter?: EmailFilter): StoredEmail | undefined;
+    delete(id: string): boolean;
+    clear(): void;
+    /** Resolve with the first email (already caught after `since`, or arriving later) that matches. */
+    waitFor(filter: EmailFilter, timeoutMs: number, signal?: AbortSignal): Promise<StoredEmail | null>;
+}