typedmailer 1.1.0 → 1.2.0

package/dist/webhooks/shared.js

@@ -0,0 +1,69 @@
+import { timingSafeEqual } from 'node:crypto';
+import { WebhookVerificationError, defaultTimestampToleranceSeconds } from './types.js';
+export function assertRecentTimestamp(value, now, toleranceSeconds) {
+    if (!value || !/^\d+$/.test(value))
+        throw new WebhookVerificationError('invalid_signature');
+    const timestamp = Number(value);
+    const tolerance = toleranceSeconds ?? defaultTimestampToleranceSeconds;
+    if (!Number.isSafeInteger(timestamp) || !Number.isSafeInteger(tolerance) || tolerance < 1) {
+        throw new WebhookVerificationError('invalid_signature');
+    }
+    const seconds = Math.floor((now ?? new Date()).getTime() / 1000);
+    if (Math.abs(seconds - timestamp) > tolerance)
+        throw new WebhookVerificationError('invalid_signature');
+}
+export function getHeader(headers, name) {
+    const entry = Object.entries(headers).find(([key]) => key.toLowerCase() === name.toLowerCase())?.[1];
+    return typeof entry === 'string' ? entry : Array.isArray(entry) ? entry.join(' ') : undefined;
+}
+export function safeEqual(left, right) {
+    return left.byteLength === right.byteLength && timingSafeEqual(left, right);
+}
+export function decodeBase64(value) {
+    if (!/^[A-Za-z0-9+/]+={0,2}$/.test(value))
+        return Buffer.alloc(0);
+    return Buffer.from(value, 'base64');
+}
+export function decodeHex(value) {
+    if (!/^(?:[a-fA-F0-9]{2})+$/.test(value))
+        return Buffer.alloc(0);
+    return Buffer.from(value, 'hex');
+}
+export function parseDate(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        const milliseconds = value < 10_000_000_000 ? value * 1000 : value;
+        const result = new Date(milliseconds);
+        return Number.isNaN(result.getTime()) ? undefined : result;
+    }
+    if (typeof value === 'string' && value.length > 0) {
+        const result = new Date(value);
+        return Number.isNaN(result.getTime()) ? undefined : result;
+    }
+    return undefined;
+}
+export function asRecord(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new WebhookVerificationError('invalid_payload');
+    }
+    return value;
+}
+export function asOptionalRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+export function asString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+export function asId(value) {
+    return typeof value === 'string' || typeof value === 'number' ? String(value) : undefined;
+}
+export function isString(value) {
+    return typeof value === 'string';
+}
+export function asStringArray(value) {
+    return Array.isArray(value) ? value.filter(isString) : [];
+}
+export function firstString(value) {
+    return asString(value) ?? asStringArray(value)[0];
+}

package/dist/webhooks/signatures.d.ts

@@ -0,0 +1,16 @@
+import type { VerifyWebhookInput } from './types.js';
+export declare function verifyResend(input: Extract<VerifyWebhookInput, {
+    provider: 'resend';
+}>, rawBody: Uint8Array): void;
+export declare function verifyMailgun(input: Extract<VerifyWebhookInput, {
+    provider: 'mailgun';
+}>, payload: unknown): void;
+export declare function verifySendGrid(input: Extract<VerifyWebhookInput, {
+    provider: 'sendgrid';
+}>, rawBody: Uint8Array): void;
+export declare function verifyAuthorization(input: Extract<VerifyWebhookInput, {
+    provider: 'brevo' | 'postmark';
+}>, headerName: string): void;
+export declare function verifySnsNotification(input: Extract<VerifyWebhookInput, {
+    provider: 'ses';
+}>, payload: unknown): Promise<unknown>;

package/dist/webhooks/signatures.js

@@ -0,0 +1,159 @@
+import { createHmac, createVerify, X509Certificate } from 'node:crypto';
+import { WebhookVerificationError } from './types.js';
+import { asRecord, asString, assertRecentTimestamp, decodeBase64, decodeHex, getHeader, safeEqual } from './shared.js';
+export function verifyResend(input, rawBody) {
+    const messageId = getHeader(input.headers, 'svix-id');
+    const timestamp = getHeader(input.headers, 'svix-timestamp');
+    const signatures = getHeader(input.headers, 'svix-signature');
+    assertRecentTimestamp(timestamp, input.now, input.toleranceSeconds);
+    if (!messageId || !signatures || !input.webhookSecret.startsWith('whsec_')) {
+        throw new WebhookVerificationError('invalid_signature');
+    }
+    let key;
+    try {
+        key = Buffer.from(input.webhookSecret.slice('whsec_'.length), 'base64');
+    }
+    catch {
+        throw new WebhookVerificationError('invalid_signature');
+    }
+    if (key.length === 0)
+        throw new WebhookVerificationError('invalid_signature');
+    const expected = createHmac('sha256', key).update(`${messageId}.${timestamp}.`).update(rawBody).digest();
+    const matches = signatures
+        .split(' ')
+        .some((item) => item.startsWith('v1,') && safeEqual(expected, decodeBase64(item.slice(3))));
+    if (!matches)
+        throw new WebhookVerificationError('invalid_signature');
+}
+export function verifyMailgun(input, payload) {
+    const root = asRecord(payload);
+    const signature = asRecord(root.signature);
+    const timestamp = asString(signature.timestamp);
+    const token = asString(signature.token);
+    const received = asString(signature.signature);
+    assertRecentTimestamp(timestamp, input.now, input.toleranceSeconds);
+    if (!timestamp || !token || !received || !input.signingKey) {
+        throw new WebhookVerificationError('invalid_signature');
+    }
+    const expected = createHmac('sha256', input.signingKey).update(`${timestamp}${token}`).digest('hex');
+    if (!safeEqual(Buffer.from(expected, 'hex'), decodeHex(received))) {
+        throw new WebhookVerificationError('invalid_signature');
+    }
+}
+export function verifySendGrid(input, rawBody) {
+    const timestamp = getHeader(input.headers, 'x-twilio-email-event-webhook-timestamp');
+    const signature = getHeader(input.headers, 'x-twilio-email-event-webhook-signature');
+    assertRecentTimestamp(timestamp, input.now, input.toleranceSeconds);
+    if (!timestamp || !signature || !input.publicKey)
+        throw new WebhookVerificationError('invalid_signature');
+    try {
+        const verifier = createVerify('sha256');
+        verifier.update(timestamp);
+        verifier.update(rawBody);
+        verifier.end();
+        if (!verifier.verify(input.publicKey, signature, 'base64')) {
+            throw new WebhookVerificationError('invalid_signature');
+        }
+    }
+    catch (error) {
+        if (error instanceof WebhookVerificationError)
+            throw error;
+        throw new WebhookVerificationError('invalid_signature');
+    }
+}
+export function verifyAuthorization(input, headerName) {
+    const received = getHeader(input.headers, headerName);
+    if (!received || !input.authorization || !safeEqual(Buffer.from(received), Buffer.from(input.authorization))) {
+        throw new WebhookVerificationError('invalid_signature');
+    }
+}
+export async function verifySnsNotification(input, payload) {
+    const envelope = asRecord(payload);
+    const topicArn = asString(envelope.TopicArn);
+    const signingCertUrl = asString(envelope.SigningCertURL);
+    const signature = asString(envelope.Signature);
+    const signatureVersion = asString(envelope.SignatureVersion);
+    if (envelope.Type !== 'Notification' ||
+        topicArn !== input.topicArn ||
+        !signingCertUrl ||
+        !signature ||
+        (signatureVersion !== '1' && signatureVersion !== '2')) {
+        throw new WebhookVerificationError('invalid_signature');
+    }
+    let certificateUrl;
+    try {
+        certificateUrl = new URL(signingCertUrl);
+    }
+    catch {
+        throw new WebhookVerificationError('invalid_signature');
+    }
+    const topicMatch = /^arn:(aws|aws-us-gov|aws-cn):sns:([a-z0-9-]+):\d{12}:[^:]+$/.exec(input.topicArn);
+    const expectedHost = topicMatch
+        ? topicMatch[1] === 'aws-cn'
+            ? `sns.${topicMatch[2]}.amazonaws.com.cn`
+            : `sns.${topicMatch[2]}.amazonaws.com`
+        : undefined;
+    if (certificateUrl.protocol !== 'https:' ||
+        certificateUrl.username ||
+        certificateUrl.password ||
+        certificateUrl.port ||
+        certificateUrl.search ||
+        certificateUrl.hash ||
+        certificateUrl.hostname !== expectedHost ||
+        !/^\/SimpleNotificationService-[A-Za-z0-9_-]+\.pem$/.test(certificateUrl.pathname)) {
+        throw new WebhookVerificationError('invalid_signature');
+    }
+    let response;
+    try {
+        response = await fetch(certificateUrl, { redirect: 'error', signal: AbortSignal.timeout(5_000) });
+    }
+    catch {
+        throw new WebhookVerificationError('invalid_signature');
+    }
+    if (!response.ok)
+        throw new WebhookVerificationError('invalid_signature');
+    let certificateBody;
+    try {
+        certificateBody = await response.text();
+    }
+    catch {
+        throw new WebhookVerificationError('invalid_signature');
+    }
+    if (certificateBody.length > 32_768)
+        throw new WebhookVerificationError('invalid_signature');
+    try {
+        const certificate = new X509Certificate(certificateBody);
+        const now = input.now ?? new Date();
+        if (!certificate.subject.split('\n').some((line) => line === 'CN=Amazon SNS') ||
+            now < new Date(certificate.validFrom) ||
+            now > new Date(certificate.validTo)) {
+            throw new WebhookVerificationError('invalid_signature');
+        }
+        const fields = snsFields(envelope);
+        const verifier = createVerify(signatureVersion === '2' ? 'sha256' : 'sha1');
+        verifier.update(fields);
+        verifier.end();
+        if (!verifier.verify(certificate.publicKey, signature, 'base64')) {
+            throw new WebhookVerificationError('invalid_signature');
+        }
+    }
+    catch (error) {
+        if (error instanceof WebhookVerificationError)
+            throw error;
+        throw new WebhookVerificationError('invalid_signature');
+    }
+    try {
+        const message = JSON.parse(asString(envelope.Message) ?? '');
+        return message;
+    }
+    catch {
+        throw new WebhookVerificationError('invalid_payload');
+    }
+}
+function snsFields(envelope) {
+    const fields = ['Message', 'MessageId'];
+    if (envelope.Subject !== undefined)
+        fields.push('Subject');
+    fields.push('Timestamp', 'TopicArn', 'Type');
+    return fields.map((field) => `${field}\n${asString(envelope[field]) ?? ''}\n`).join('');
+}

package/dist/webhooks/types.d.ts

@@ -0,0 +1,43 @@
+export type ProviderName = import('../types.js').ProviderName;
+export type EmailWebhookEventType = 'accepted' | 'delivered' | 'bounced' | 'complained' | 'delayed' | 'opened' | 'clicked' | 'unsubscribed' | 'rejected' | 'failed' | 'other';
+export interface EmailWebhookEvent {
+    readonly provider: Exclude<ProviderName, 'smtp'>;
+    readonly id?: string;
+    readonly type: EmailWebhookEventType;
+    readonly eventType: string;
+    readonly messageId?: string;
+    readonly recipient?: string;
+    readonly occurredAt?: Date;
+    /** Original provider data. It can contain message metadata and personal information. */
+    readonly raw: unknown;
+}
+export type WebhookHeaders = Readonly<Record<string, string | readonly string[] | undefined>>;
+interface RawWebhookInput {
+    readonly rawBody: string | Uint8Array;
+    readonly headers: WebhookHeaders;
+    readonly now?: Date;
+    readonly toleranceSeconds?: number;
+}
+export type VerifyWebhookInput = (RawWebhookInput & {
+    readonly provider: 'resend';
+    readonly webhookSecret: string;
+}) | (RawWebhookInput & {
+    readonly provider: 'mailgun';
+    readonly signingKey: string;
+}) | (RawWebhookInput & {
+    readonly provider: 'sendgrid';
+    readonly publicKey: string;
+}) | (RawWebhookInput & {
+    readonly provider: 'brevo' | 'postmark';
+    readonly authorization: string;
+    readonly authorizationHeader?: string;
+}) | (RawWebhookInput & {
+    readonly provider: 'ses';
+    readonly topicArn: string;
+});
+export declare class WebhookVerificationError extends Error {
+    readonly code: 'invalid_signature' | 'invalid_payload' | 'unsupported_event';
+    constructor(code: 'invalid_signature' | 'invalid_payload' | 'unsupported_event');
+}
+export declare const defaultTimestampToleranceSeconds = 300;
+export {};

package/dist/webhooks/types.js

@@ -0,0 +1,13 @@
+export class WebhookVerificationError extends Error {
+    code;
+    constructor(code) {
+        super(code === 'invalid_signature'
+            ? 'The webhook request could not be authenticated.'
+            : code === 'unsupported_event'
+                ? 'The provider webhook event is not supported.'
+                : 'The provider webhook payload is invalid.');
+        this.code = code;
+        this.name = 'WebhookVerificationError';
+    }
+}
+export const defaultTimestampToleranceSeconds = 300;

package/dist/webhooks.d.ts

@@ -1,44 +1,5 @@
-import type { ProviderName } from './types.js';
-export type EmailWebhookEventType = 'accepted' | 'delivered' | 'bounced' | 'complained' | 'delayed' | 'opened' | 'clicked' | 'unsubscribed' | 'rejected' | 'failed' | 'other';
-export interface EmailWebhookEvent {
-    readonly provider: Exclude<ProviderName, 'smtp'>;
-    readonly id?: string;
-    readonly type: EmailWebhookEventType;
-    readonly eventType: string;
-    readonly messageId?: string;
-    readonly recipient?: string;
-    readonly occurredAt?: Date;
-    /** Original provider data. It can contain message metadata and personal information. */
-    readonly raw: unknown;
-}
-export type WebhookHeaders = Readonly<Record<string, string | readonly string[] | undefined>>;
-interface RawWebhookInput {
-    readonly rawBody: string | Uint8Array;
-    readonly headers: WebhookHeaders;
-    readonly now?: Date;
-    readonly toleranceSeconds?: number;
-}
-export type VerifyWebhookInput = (RawWebhookInput & {
-    readonly provider: 'resend';
-    readonly webhookSecret: string;
-}) | (RawWebhookInput & {
-    readonly provider: 'mailgun';
-    readonly signingKey: string;
-}) | (RawWebhookInput & {
-    readonly provider: 'sendgrid';
-    readonly publicKey: string;
-}) | (RawWebhookInput & {
-    readonly provider: 'brevo' | 'postmark';
-    readonly authorization: string;
-    readonly authorizationHeader?: string;
-}) | (RawWebhookInput & {
-    readonly provider: 'ses';
-    readonly topicArn: string;
-});
-export declare class WebhookVerificationError extends Error {
-    readonly code: 'invalid_signature' | 'invalid_payload' | 'unsupported_event';
-    constructor(code: 'invalid_signature' | 'invalid_payload' | 'unsupported_event');
-}
+import type { EmailWebhookEvent, VerifyWebhookInput } from './webhooks/types.js';
+export type { EmailWebhookEvent, EmailWebhookEventType, VerifyWebhookInput, WebhookHeaders } from './webhooks/types.js';
+export { WebhookVerificationError } from './webhooks/types.js';
 /** Authenticates a provider webhook before returning normalized, typed email events. */
 export declare function verifyWebhook(input: VerifyWebhookInput): Promise<readonly EmailWebhookEvent[]>;
-export {};