@groundmail/groundhog 0.0.0-stage → 0.1.0

package/dist/providers/sendgrid.js

@@ -0,0 +1,128 @@
+import { randomBytes } from 'node:crypto';
+import { ingestApiSend, toAddress, toAddressList } from '../mime.js';
+import { sendgridSignature } from '../signing.js';
+import { attachment, headerRecord, recipient, str, unixSeconds } from './common.js';
+const EVENT_NAMES = {
+    delivered: 'delivered',
+    bounced: 'bounce',
+    complained: 'spamreport',
+    opened: 'open',
+    clicked: 'click',
+};
+function error(status, message, field = null, help = null) {
+    return { status, body: { errors: [{ message, field, help }] } };
+}
+function substitute(value, subs) {
+    if (!value || !subs)
+        return value;
+    let out = value;
+    for (const [key, replacement] of Object.entries(subs))
+        out = out.split(key).join(String(replacement));
+    return out;
+}
+async function sendgridSend(ctx, hub) {
+    if (await hub.guard(ctx, sendgrid))
+        return;
+    const body = await ctx.json();
+    const personalizations = (Array.isArray(body.personalizations) ? body.personalizations : []);
+    if (!personalizations.length) {
+        return error(400, 'The personalizations field is required and must have at least one personalization.', 'personalizations', 'http://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/errors.html#-Personalizations-Errors');
+    }
+    const from = toAddress(body.from);
+    if (!from)
+        return error(400, 'The from object must be provided for every email send. It is an object that requires the email parameter, but may also contain a name parameter.', 'from.email');
+    const content = (Array.isArray(body.content) ? body.content : []);
+    const templateId = str(body.template_id);
+    const baseHtml = content.find((c) => c.type === 'text/html')?.value;
+    const baseText = content.find((c) => c.type === 'text/plain')?.value;
+    const attachments = Array.isArray(body.attachments)
+        ? body.attachments.map((a) => attachment(a.filename, a.content, a.type, a.content_id))
+        : undefined;
+    const categories = Array.isArray(body.categories) ? body.categories : [];
+    const xMessageId = randomBytes(16).toString('base64url').slice(0, 22);
+    const caught = [];
+    for (const [index, p] of personalizations.entries()) {
+        const to = toAddressList(p.to);
+        if (!to.length)
+            return error(400, 'The to array is required for all personalization objects, and must have at least one email object with a valid email address.', `personalizations.${index}.to`);
+        let html = substitute(baseHtml, p.substitutions);
+        let text = substitute(baseText, p.substitutions);
+        if (!html && !text && templateId) {
+            text = `Sent with SendGrid dynamic template ${templateId}. Groundhog can't render stored templates; the data it was sent with:\n\n${JSON.stringify(p.dynamic_template_data ?? {}, null, 2)}`;
+        }
+        const customArgs = { ...(body.custom_args ?? {}), ...(p.custom_args ?? {}) };
+        caught.push(await ingestApiSend({
+            from,
+            to,
+            cc: toAddressList(p.cc),
+            bcc: toAddressList(p.bcc),
+            replyTo: toAddressList(body.reply_to_list ?? body.reply_to),
+            subject: substitute(p.subject ?? str(body.subject), p.substitutions) ?? '',
+            html: html ?? null,
+            text: text ?? null,
+            headers: { ...(headerRecord(body.headers) ?? {}), ...(headerRecord(p.headers) ?? {}) },
+            attachments,
+        }, {
+            via: 'sendgrid',
+            providerMessageId: personalizations.length > 1 ? `${xMessageId}.${index}` : xMessageId,
+            tags: categories,
+            metadata: Object.fromEntries(Object.entries(customArgs).map(([k, v]) => [k, String(v)])),
+        }));
+    }
+    for (const email of caught)
+        hub.ingest(email);
+    return { status: 202, headers: { 'X-Message-Id': xMessageId } };
+}
+/** SendGrid's v3 Mail Send, at `/sendgrid/v3/mail/send`. */
+export const sendgrid = {
+    id: 'sendgrid',
+    eventNames: EVENT_NAMES,
+    register(router, hub) {
+        router.post('/sendgrid/v3/mail/send', (ctx) => sendgridSend(ctx, hub));
+    },
+    fail(kind) {
+        switch (kind) {
+            case 'rate_limit':
+                return { ...error(429, 'too many requests'), headers: { 'X-RateLimit-Limit': '600', 'X-RateLimit-Remaining': '0', 'X-RateLimit-Reset': String(unixSeconds() + 1) } };
+            case 'invalid_recipient':
+                return error(400, 'Does not contain a valid address.', 'personalizations.0.to.0.email', 'http://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/errors.html#message.personalizations.to');
+            case 'unauthorized':
+                return error(401, 'The provided authorization grant is invalid, expired, or revoked');
+            case 'outage':
+                return error(503, 'Service Unavailable');
+        }
+    },
+    webhook(event, email, ctx) {
+        const timestamp = unixSeconds();
+        const eventId = randomBytes(16).toString('base64url').slice(0, 22);
+        const base = {
+            email: recipient(email),
+            timestamp,
+            'smtp-id': `<${email.providerMessageId}@groundhog.local>`,
+            event: EVENT_NAMES[event],
+            category: email.tags,
+            sg_event_id: eventId,
+            sg_message_id: `${email.providerMessageId}.groundhog.0`,
+            ...email.metadata,
+        };
+        if (event === 'delivered')
+            base.response = '250 2.0.0 OK';
+        if (event === 'bounced')
+            Object.assign(base, { reason: '550 5.1.1 The email account that you tried to reach does not exist.', status: '5.1.1', type: 'bounce', bounce_classification: 'Invalid Address' });
+        if (event === 'opened' || event === 'clicked')
+            Object.assign(base, { useragent: 'Groundhog', ip: '127.0.0.1', sg_machine_open: false });
+        if (event === 'clicked')
+            Object.assign(base, { url: ctx.link, url_offset: { index: 0, type: 'html' } });
+        const body = JSON.stringify([base]);
+        const ts = String(timestamp);
+        return {
+            eventId,
+            body,
+            headers: {
+                'Content-Type': 'application/json',
+                'X-Twilio-Email-Event-Webhook-Timestamp': ts,
+                'X-Twilio-Email-Event-Webhook-Signature': sendgridSignature(ts, body),
+            },
+        };
+    },
+};

package/dist/providers/ses.d.ts

@@ -0,0 +1,3 @@
+import type { ProviderModule } from './types.js';
+/** Amazon SES: the v2 JSON API (`/ses/v2/email/outbound-emails`) and the v1 query API (`POST /ses`). */
+export declare const ses: ProviderModule;

package/dist/providers/ses.js

@@ -0,0 +1,244 @@
+import { randomBytes } from 'node:crypto';
+import { ingestApiSend, parseEmail, toAddress, toAddressList, uuid } from '../mime.js';
+import { allRecipients, attachment, decodeContent, headerRecord } from './common.js';
+const EVENT_NAMES = {
+    delivered: 'Delivery',
+    bounced: 'Bounce',
+    complained: 'Complaint',
+    opened: 'Open',
+    clicked: 'Click',
+};
+function sesMessageId() {
+    return `0100${randomBytes(6).toString('hex')}-${uuid()}-000000`;
+}
+function xmlEscape(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+const V2_ERRORS = {
+    rate_limit: { status: 429, type: 'TooManyRequestsException', message: 'Maximum sending rate exceeded.' },
+    invalid_recipient: { status: 400, type: 'BadRequestException', message: "Missing final '@domain'" },
+    unauthorized: { status: 403, type: 'UnrecognizedClientException', message: 'The security token included in the request is invalid.' },
+    outage: { status: 503, type: 'ServiceUnavailable', message: 'Service is unavailable. Please try again later.' },
+};
+const V1_ERRORS = {
+    rate_limit: { status: 400, code: 'Throttling', type: 'Sender', message: 'Maximum sending rate exceeded.' },
+    invalid_recipient: { status: 400, code: 'InvalidParameterValue', type: 'Sender', message: "Missing final '@domain'" },
+    unauthorized: { status: 403, code: 'InvalidClientTokenId', type: 'Sender', message: 'The security token included in the request is invalid.' },
+    outage: { status: 503, code: 'ServiceUnavailable', type: 'Receiver', message: 'Service is unavailable. Please try again later.' },
+};
+function v2Error(status, type, message) {
+    return { status, headers: { 'x-amzn-ErrorType': type, 'x-amzn-RequestId': uuid() }, body: { message } };
+}
+function v1Error(status, code, type, message) {
+    return {
+        status,
+        headers: { 'Content-Type': 'text/xml' },
+        body: `<ErrorResponse xmlns="http://ses.amazonaws.com/doc/2010-12-01/"><Error><Type>${type}</Type><Code>${code}</Code><Message>${xmlEscape(message)}</Message></Error><RequestId>${uuid()}</RequestId></ErrorResponse>`,
+    };
+}
+function isV1(ctx) {
+    return ctx.method === 'POST' && !ctx.url.pathname.includes('/v2/') && ctx.header('content-type').includes('x-www-form-urlencoded');
+}
+function render(template, data) {
+    if (!template)
+        return template;
+    return template.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_m, key) => {
+        const value = key.split('.').reduce((obj, part) => (obj && typeof obj === 'object' ? obj[part] : undefined), data);
+        return value == null ? '' : String(value);
+    });
+}
+async function sendV2(ctx, hub) {
+    if (await hub.guard(ctx, ses))
+        return;
+    const body = await ctx.json();
+    const messageId = sesMessageId();
+    const tags = (body.EmailTags ?? []).map((tag) => `${tag.Name}:${tag.Value}`);
+    const metadata = body.ConfigurationSetName ? { ConfigurationSetName: body.ConfigurationSetName } : {};
+    let email;
+    if (body.Content?.Raw?.Data) {
+        email = await parseEmail(decodeContent(body.Content.Raw.Data), {
+            via: 'ses',
+            providerMessageId: messageId,
+            envelopeTo: toAddressList([...(body.Destination?.ToAddresses ?? []), ...(body.Destination?.CcAddresses ?? []), ...(body.Destination?.BccAddresses ?? [])]),
+            tags,
+            metadata,
+        });
+    }
+    else {
+        const from = toAddress(body.FromEmailAddress);
+        const to = toAddressList(body.Destination?.ToAddresses);
+        const cc = toAddressList(body.Destination?.CcAddresses);
+        const bcc = toAddressList(body.Destination?.BccAddresses);
+        if (!from)
+            return v2Error(400, 'BadRequestException', 'FromEmailAddress is required.');
+        if (!to.length && !cc.length && !bcc.length)
+            return v2Error(400, 'BadRequestException', 'Missing required field Destination');
+        let subject = body.Content?.Simple?.Subject?.Data ?? '';
+        let html = body.Content?.Simple?.Body?.Html?.Data;
+        let text = body.Content?.Simple?.Body?.Text?.Data;
+        const template = body.Content?.Template;
+        if (template) {
+            let data = {};
+            try {
+                data = JSON.parse(template.TemplateData ?? '{}');
+            }
+            catch {
+                // Keep the raw data in the text below.
+            }
+            if (template.TemplateContent) {
+                subject = render(template.TemplateContent.Subject, data) ?? '';
+                html = render(template.TemplateContent.Html, data);
+                text = render(template.TemplateContent.Text, data);
+            }
+            else {
+                const name = template.TemplateName ?? template.TemplateArn ?? 'unknown';
+                subject = `SES template ${name}`;
+                text = `Sent with SES template ${name}. Groundhog can't render stored templates; the data it was sent with:\n\n${template.TemplateData ?? '{}'}`;
+            }
+        }
+        email = await ingestApiSend({
+            from,
+            to,
+            cc,
+            bcc,
+            replyTo: toAddressList(body.ReplyToAddresses),
+            subject,
+            html: html ?? null,
+            text: text ?? null,
+            headers: headerRecord(body.Content?.Simple?.Headers),
+            attachments: body.Content?.Simple?.Attachments?.map((a) => attachment(a.FileName, a.RawContent, a.ContentType, a.ContentId)),
+        }, { via: 'ses', providerMessageId: messageId, tags, metadata });
+    }
+    hub.ingest(email);
+    return { status: 200, headers: { 'x-amzn-RequestId': uuid() }, body: { MessageId: messageId } };
+}
+function members(pairs, prefix) {
+    return pairs
+        .filter(([key]) => key.startsWith(`${prefix}.member.`))
+        .sort(([a], [b]) => Number(a.split('.').pop()) - Number(b.split('.').pop()))
+        .map(([, value]) => value);
+}
+async function sendV1(ctx, hub) {
+    const pairs = await ctx.formPairs();
+    const get = (key) => pairs.find(([k]) => k === key)?.[1];
+    const action = get('Action');
+    if (action !== 'SendEmail' && action !== 'SendRawEmail') {
+        return v1Error(400, 'InvalidAction', 'Sender', `Groundhog only emulates SendEmail and SendRawEmail (got ${action ?? 'nothing'}).`);
+    }
+    if (await hub.guard(ctx, ses))
+        return;
+    const messageId = sesMessageId();
+    const tags = [];
+    for (let i = 1; get(`Tags.member.${i}.Name`); i += 1)
+        tags.push(`${get(`Tags.member.${i}.Name`)}:${get(`Tags.member.${i}.Value`) ?? ''}`);
+    let email;
+    if (action === 'SendRawEmail') {
+        const data = get('RawMessage.Data');
+        if (!data)
+            return v1Error(400, 'InvalidParameterValue', 'Sender', 'RawMessage.Data is required.');
+        email = await parseEmail(Buffer.from(data, 'base64'), { via: 'ses', providerMessageId: messageId, envelopeTo: toAddressList(members(pairs, 'Destinations')), tags });
+    }
+    else {
+        const from = toAddress(get('Source'));
+        if (!from)
+            return v1Error(400, 'InvalidParameterValue', 'Sender', 'Missing required header Source.');
+        email = await ingestApiSend({
+            from,
+            to: toAddressList(members(pairs, 'Destination.ToAddresses')),
+            cc: toAddressList(members(pairs, 'Destination.CcAddresses')),
+            bcc: toAddressList(members(pairs, 'Destination.BccAddresses')),
+            replyTo: toAddressList(members(pairs, 'ReplyToAddresses')),
+            subject: get('Message.Subject.Data') ?? '',
+            html: get('Message.Body.Html.Data') ?? null,
+            text: get('Message.Body.Text.Data') ?? null,
+        }, { via: 'ses', providerMessageId: messageId, tags });
+    }
+    hub.ingest(email);
+    const requestId = uuid();
+    return {
+        status: 200,
+        headers: { 'Content-Type': 'text/xml' },
+        body: `<${action}Response xmlns="http://ses.amazonaws.com/doc/2010-12-01/"><${action}Result><MessageId>${messageId}</MessageId></${action}Result><ResponseMetadata><RequestId>${requestId}</RequestId></ResponseMetadata></${action}Response>`,
+    };
+}
+/** Amazon SES: the v2 JSON API (`/ses/v2/email/outbound-emails`) and the v1 query API (`POST /ses`). */
+export const ses = {
+    id: 'ses',
+    eventNames: EVENT_NAMES,
+    register(router, hub) {
+        router.post('/ses/v2/email/outbound-emails', (ctx) => sendV2(ctx, hub));
+        router.post('/ses', (ctx) => sendV1(ctx, hub));
+    },
+    fail(kind, ctx) {
+        if (ctx && isV1(ctx)) {
+            const e = V1_ERRORS[kind];
+            return v1Error(e.status, e.code, e.type, e.message);
+        }
+        const e = V2_ERRORS[kind];
+        return v2Error(e.status, e.type, e.message);
+    },
+    webhook(event, email, ctx) {
+        const now = new Date().toISOString();
+        const recipients = allRecipients(email);
+        const sesEvent = {
+            eventType: EVENT_NAMES[event],
+            mail: {
+                timestamp: email.createdAt,
+                source: email.from?.address ?? '',
+                sourceArn: `arn:aws:ses:us-east-1:000000000000:identity/${email.from?.address.split('@')[1] ?? 'localhost'}`,
+                sendingAccountId: '000000000000',
+                messageId: email.providerMessageId,
+                destination: recipients,
+                headersTruncated: false,
+                headers: email.headers.slice(0, 20).map(([name, value]) => ({ name, value })),
+                commonHeaders: {
+                    from: email.from ? [email.from.name ? `${email.from.name} <${email.from.address}>` : email.from.address] : [],
+                    to: email.to.map((a) => a.address),
+                    messageId: email.providerMessageId,
+                    subject: email.subject,
+                },
+                tags: Object.fromEntries(email.tags.map((tag) => tag.split(':')).map(([k, ...v]) => [k, [v.join(':')]])),
+            },
+        };
+        const feedbackId = sesMessageId();
+        switch (event) {
+            case 'delivered':
+                sesEvent.delivery = { timestamp: now, processingTimeMillis: 512, recipients, smtpResponse: '250 2.6.0 Message received', reportingMTA: 'groundhog.local' };
+                break;
+            case 'bounced':
+                sesEvent.bounce = {
+                    bounceType: 'Permanent', bounceSubType: 'General', timestamp: now, feedbackId, reportingMTA: 'dsn; groundhog.local',
+                    bouncedRecipients: [{ emailAddress: recipients[0], action: 'failed', status: '5.1.1', diagnosticCode: 'smtp; 550 5.1.1 user unknown' }],
+                };
+                break;
+            case 'complained':
+                sesEvent.complaint = { complainedRecipients: [{ emailAddress: recipients[0] }], timestamp: now, feedbackId, userAgent: 'Groundhog', complaintFeedbackType: 'abuse', arrivalDate: now };
+                break;
+            case 'opened':
+                sesEvent.open = { ipAddress: '127.0.0.1', timestamp: now, userAgent: 'Groundhog' };
+                break;
+            case 'clicked':
+                sesEvent.click = { ipAddress: '127.0.0.1', timestamp: now, userAgent: 'Groundhog', link: ctx.link, linkTags: {} };
+                break;
+        }
+        const id = uuid();
+        const topic = 'arn:aws:sns:us-east-1:000000000000:groundhog-ses-events';
+        const notification = {
+            Type: 'Notification',
+            MessageId: id,
+            TopicArn: topic,
+            Message: JSON.stringify(sesEvent),
+            Timestamp: now,
+            SignatureVersion: '1',
+            // AWS signs SNS messages with its own certificate, which can't be reproduced locally.
+            Signature: randomBytes(256).toString('base64'),
+            SigningCertURL: `${ctx.baseUrl}/ses/sns-signing-cert.pem`,
+            UnsubscribeURL: `${ctx.baseUrl}/ses/sns-unsubscribe?SubscriptionArn=${encodeURIComponent(topic)}`,
+        };
+        return {
+            eventId: id,
+            body: JSON.stringify(notification),
+            headers: { 'Content-Type': 'text/plain; charset=UTF-8', 'x-amz-sns-message-type': 'Notification', 'x-amz-sns-message-id': id, 'x-amz-sns-topic-arn': topic },
+        };
+    },
+};

package/dist/providers/types.d.ts

@@ -0,0 +1,35 @@
+import type { HttpResult, RequestContext, Router } from '../http.js';
+import type { WebhookSecrets } from '../signing.js';
+import type { Email, FaultKind, Provider, StoredEmail, WebhookEvent } from '../types.js';
+export type Hub = {
+    /** Add a caught email to the inbox (fires the auto `delivered` webhook when that's on). */
+    ingest(email: StoredEmail): StoredEmail;
+    get(id: string): StoredEmail | undefined;
+    /**
+     * Apply failure mode to this send. Returns true when the request was answered
+     * with a simulated failure (or dropped, for a timeout) and the route must stop.
+     */
+    guard(ctx: RequestContext, provider: ProviderModule): Promise<boolean>;
+};
+export type WebhookRequest = {
+    /** Event id, shown in the delivery log. */
+    eventId: string;
+    headers: Record<string, string>;
+    body: string;
+};
+export type WebhookContext = {
+    secrets: WebhookSecrets;
+    /** Link used for `clicked` events. */
+    link: string;
+    /** Groundhog's own base URL (for SNS cert links and such). */
+    baseUrl: string;
+};
+export type ProviderModule = {
+    id: Exclude<Provider, 'smtp'> | 'smtp';
+    /** The provider's own name for each event, shown on the webhook buttons. */
+    eventNames: Record<WebhookEvent, string>;
+    register?(router: Router, hub: Hub): void;
+    /** The error response this provider returns for a simulated failure. */
+    fail(kind: Exclude<FaultKind, 'timeout'>, ctx?: RequestContext): HttpResult;
+    webhook(event: WebhookEvent, email: Email, ctx: WebhookContext): WebhookRequest;
+};

package/dist/providers/types.js

@@ -0,0 +1 @@
+export {};

package/dist/server.d.ts

@@ -0,0 +1,38 @@
+import { Faults } from './faults.js';
+import { GroundmailAccount } from './groundmail-account.js';
+import { EmailStore } from './store.js';
+import { Webhooks, type WebhookSettings } from './webhooks.js';
+export declare const VERSION: string;
+export type GroundhogOptions = {
+    /** SMTP port. Default 1025. 0 picks a free port. */
+    smtpPort?: number;
+    /** HTTP port (web UI, testing API, provider APIs). Default 3025. 0 picks a free port. */
+    httpPort?: number;
+    /** `localhost` (default) listens on 127.0.0.1 and ::1. Use `0.0.0.0` in containers. */
+    host?: string;
+    /** Most emails kept; older ones drop off. Default 1000. */
+    maxEmails?: number;
+    /** Save the inbox to this JSON file and load it on start. */
+    storeFile?: string;
+    webhooks?: Partial<WebhookSettings>;
+    /** How long a simulated timeout holds a connection. Default 30 000 ms. */
+    faultTimeoutMs?: number;
+    /** Disable the SMTP listener. */
+    smtp?: boolean;
+    /** Groundmail API base URL for "Send to my real inbox". */
+    groundmailApiUrl?: string;
+    openBrowser?: (url: string) => void;
+    log?: (line: string) => void;
+};
+export type Groundhog = {
+    url: string;
+    smtpPort: number;
+    httpPort: number;
+    host: string;
+    store: EmailStore;
+    faults: Faults;
+    webhooks: Webhooks;
+    account: GroundmailAccount;
+    close(): Promise<void>;
+};
+export declare function startGroundhog(options?: GroundhogOptions): Promise<Groundhog>;