pipework 0.62.0 → 0.63.0

package/dist/infra/email/mail.js

@@ -0,0 +1,144 @@
+import { sql } from '../../data/db/sql.js';
+import { pipeSystem } from '../../data/db/db.js';
+import { schema } from '../../data/schema/namespace.js';
+import { fitting } from '../../request/di/index.js';
+import { getContext } from '../../request/context/store.js';
+import { ValidationError } from '../../core/errors/index.js';
+import { getBaseLogger } from '../../core/logging/index.js';
+import { __flowStep } from '../../trace/runtime/flow-step.js';
+import { auditEmail } from './audit.js';
+export const SEND_JOB = 'pipework.email.send';
+const ADDRESS_RE = /^[^\s@<>,;"]+@[^\s@<>,;"]+$/;
+export function normalizeAddress(address) {
+    return address.trim().toLowerCase();
+}
+/**
+ * Creates the transactional email interface.
+ *
+ * `send(db, { to, template, data, key })` writes a `pipework_email_messages` row and
+ * enqueues a `pipework.email.send` job in the caller's transaction. The job renders the
+ * app's template and sends through the provider, at most once per key, skipping an
+ * address on the suppression list (status `suppressed`, no provider call). The
+ * provider call is a trace step and `Email:sent` / `Email:suppressed` / `Email:failed`
+ * audit records are written under it, in the trace of the flow that called `send`.
+ *
+ * Needs blueprint `email: {}` (tables `pipework_email_messages`, `pipework_email_suppressions`).
+ * A provider error returns the message to `queued` with `error` set and rethrows, so the
+ * queue retries (set `maxAttempts` on the queue); if the queue gives up the row keeps the error.
+ * A run claims the message with a conditional update (`status` `queued`, or `sending` for longer than
+ * `sendingStaleSeconds`), so a re-run of a job whose first run is still in flight does not call the provider.
+ * Residual window: a crash mid-send leaves the message `sending` for the stale window, after which a retry
+ * may send it once more; likewise if the provider accepted it and the process died before the row was marked `sent`. SES v2 has no idempotency token to close it.
+ * Message bodies and template data are never logged.
+ */
+export function createMail(config) {
+    if (config.provider.name === 'dev-stand-in' && config.environment === 'production') {
+        throw new Error('[pipework] mail.devStandIn is refused in production.\n\n' +
+            '  The stand-in writes messages to files instead of sending them.\n' +
+            '  Configure a real provider, e.g. mail.ses({ region, credentials }).\n');
+    }
+    const staleSeconds = config.sendingStaleSeconds ?? 600;
+    const deliver = __flowStep({ ref: 'pipework/email:deliver' }, async (messageId) => {
+        const db = pipeSystem();
+        const rows = await db.execute(sql `SELECT * FROM pipework_email_messages WHERE id = ${messageId}::uuid`);
+        const row = rows[0];
+        if (row === undefined)
+            throw new Error(`[pipework] Email message ${messageId} does not exist.`);
+        const status = row['status'];
+        if (status === 'sent' || status === 'suppressed' || status === 'failed')
+            return { status };
+        const environment = getContext()?.instance.config.environment;
+        if (config.provider.name === 'dev-stand-in' && environment === 'production') {
+            throw new Error('[pipework] mail.devStandIn is refused in production.');
+        }
+        const to = row['to_address'];
+        const suppressed = await db.execute(sql `SELECT reason FROM pipework_email_suppressions WHERE address = ${normalizeAddress(to)}`);
+        if (suppressed.length > 0) {
+            await db.execute(sql `UPDATE pipework_email_messages SET status = 'suppressed' WHERE id = ${messageId}::uuid`);
+            await auditEmail('suppressed', messageId, { reason: suppressed[0]['reason'] });
+            getBaseLogger().info({ event: 'email suppressed send', messageId }, 'email skipped: address is suppressed');
+            return { status: 'suppressed' };
+        }
+        const templateName = row['template'];
+        const template = config.templates[templateName];
+        let rendered = null;
+        let renderError = '';
+        if (template === undefined) {
+            renderError = `no template named "${templateName}"`;
+        }
+        else {
+            try {
+                rendered = template(row['data']);
+            }
+            catch (err) {
+                renderError = `template "${templateName}" threw: ${err instanceof Error ? err.message : String(err)}`;
+            }
+        }
+        if (rendered === null) {
+            await db.execute(sql `UPDATE pipework_email_messages SET status = 'failed', error = ${renderError} WHERE id = ${messageId}::uuid`);
+            await auditEmail('failed', messageId, { error: renderError });
+            getBaseLogger().error({ event: 'email failed', messageId }, `email not sent: ${renderError}`);
+            return { status: 'failed' };
+        }
+        const claimed = await db.execute(sql `
+      UPDATE pipework_email_messages SET status = 'sending', sending_at = now()
+      WHERE id = ${messageId}::uuid
+        AND (status = 'queued' OR (status = 'sending' AND sending_at < now() - make_interval(secs => ${staleSeconds})))
+      RETURNING id`);
+        if (claimed.length === 0) {
+            getBaseLogger().info({ event: 'email send held elsewhere', messageId }, 'email not sent: another run holds the message or it is finished');
+            return { status: 'held' };
+        }
+        try {
+            const sent = await config.provider.send({
+                messageId, from: config.from, to,
+                subject: rendered.subject, text: rendered.text,
+                ...(rendered.html !== undefined ? { html: rendered.html } : {}),
+                ...(config.configurationSet !== undefined ? { configurationSet: config.configurationSet } : {}),
+            });
+            await db.execute(sql `
+        UPDATE pipework_email_messages
+        SET status = 'sent', sending_at = NULL, provider_message_id = ${sent.providerMessageId}, sent_at = now(), error = NULL
+        WHERE id = ${messageId}::uuid`);
+            await auditEmail('sent', messageId, { provider: config.provider.name, providerMessageId: sent.providerMessageId });
+            return { status: 'sent' };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            await db.execute(sql `UPDATE pipework_email_messages SET status = 'queued', sending_at = NULL, error = ${message} WHERE id = ${messageId}::uuid`);
+            await auditEmail('failed', messageId, { error: message, willRetry: true });
+            throw err;
+        }
+    });
+    const sendJob = fitting.use().job(SEND_JOB)
+        .input(schema.check.object({ messageId: schema.check.string() }))
+        .fit(async ({ input }) => deliver(input.messageId));
+    return {
+        async send(db, input) {
+            if (config.templates[input.template] === undefined) {
+                throw new ValidationError({ template: [`no template named "${input.template}" (have: ${Object.keys(config.templates).join(', ')})`] }, `mail.send: unknown template "${input.template}".`);
+            }
+            if (!ADDRESS_RE.test(input.to.trim())) {
+                throw new ValidationError({ to: ['is not an email address'] }, 'mail.send: "to" is not an email address.');
+            }
+            if (input.key.trim() === '') {
+                throw new ValidationError({ key: ['must not be empty'] }, 'mail.send: "key" must not be empty.');
+            }
+            const traceId = getContext()?.trace?.id ?? null;
+            const inserted = await db.execute(sql `
+        INSERT INTO pipework_email_messages (key, to_address, template, data, trace_id)
+        VALUES (${input.key}, ${input.to.trim()}, ${input.template}, ${JSON.stringify(input.data ?? null)}::jsonb, ${traceId}::uuid)
+        ON CONFLICT (key) DO NOTHING
+        RETURNING id`);
+            if (inserted.length === 0) {
+                const existing = await db.execute(sql `SELECT id FROM pipework_email_messages WHERE key = ${input.key}`);
+                return { messageId: existing[0]['id'], queued: false };
+            }
+            const messageId = inserted[0]['id'];
+            await config.queue.enqueue(db, { type: SEND_JOB, payload: { messageId }, continueFlow: true });
+            return { messageId, queued: true };
+        },
+        jobs: [sendJob],
+    };
+}
+//# sourceMappingURL=mail.js.map

package/dist/infra/email/mail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mail.js","sourceRoot":"","sources":["../../../src/infra/email/mail.ts"],"names":[],"mappings":"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"}

package/dist/infra/email/namespace.d.ts

@@ -0,0 +1,15 @@
+import { createMail } from './mail.js';
+import { ses, devStandIn } from './providers.js';
+import { snsWebhook } from './sns.js';
+/** Mail namespace — transactional email through a job queue, SES v2 or a dev stand-in, bounce and complaint suppression. */
+export declare const mail: {
+    /** Creates the mail interface: `send(db, { to, template, data, key })` in the caller's transaction, and the `jobs` that deliver. */
+    readonly create: typeof createMail;
+    /** Amazon SES v2 provider, SigV4-signed without the AWS SDK. */
+    readonly ses: typeof ses;
+    /** Development provider that writes each message to a file instead of sending; refused in production. */
+    readonly devStandIn: typeof devStandIn;
+    /** Inbound handler for SES bounce and complaint events delivered through SNS; suppresses the address. */
+    readonly snsWebhook: typeof snsWebhook;
+};
+//# sourceMappingURL=namespace.d.ts.map

package/dist/infra/email/namespace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"namespace.d.ts","sourceRoot":"","sources":["../../../src/infra/email/namespace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AACtC,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAErC,4HAA4H;AAC5H,eAAO,MAAM,IAAI;IACf,oIAAoI;;IAEpI,gEAAgE;;IAEhE,yGAAyG;;IAEzG,yGAAyG;;CAEjG,CAAA"}

package/dist/infra/email/namespace.js

@@ -0,0 +1,15 @@
+import { createMail } from './mail.js';
+import { ses, devStandIn } from './providers.js';
+import { snsWebhook } from './sns.js';
+/** Mail namespace — transactional email through a job queue, SES v2 or a dev stand-in, bounce and complaint suppression. */
+export const mail = {
+    /** Creates the mail interface: `send(db, { to, template, data, key })` in the caller's transaction, and the `jobs` that deliver. */
+    create: createMail,
+    /** Amazon SES v2 provider, SigV4-signed without the AWS SDK. */
+    ses,
+    /** Development provider that writes each message to a file instead of sending; refused in production. */
+    devStandIn,
+    /** Inbound handler for SES bounce and complaint events delivered through SNS; suppresses the address. */
+    snsWebhook,
+};
+//# sourceMappingURL=namespace.js.map

package/dist/infra/email/namespace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"namespace.js","sourceRoot":"","sources":["../../../src/infra/email/namespace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AACtC,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAErC,4HAA4H;AAC5H,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,oIAAoI;IACpI,MAAM,EAAE,UAAU;IAClB,gEAAgE;IAChE,GAAG;IACH,yGAAyG;IACzG,UAAU;IACV,yGAAyG;IACzG,UAAU;CACF,CAAA"}

package/dist/infra/email/providers.d.ts

@@ -0,0 +1,42 @@
+import { type AwsCredentials } from './sigv4.js';
+/** One rendered message handed to a provider. */
+export interface OutgoingMessage {
+    /** The message row id; unique per message. */
+    readonly messageId: string;
+    readonly from: string;
+    readonly to: string;
+    readonly subject: string;
+    readonly text: string;
+    readonly html?: string;
+    readonly configurationSet?: string;
+}
+/** Sends one rendered message. A throw means it was not accepted and may be retried. */
+export interface MailProvider {
+    readonly name: string;
+    send(message: OutgoingMessage): Promise<{
+        providerMessageId: string;
+    }>;
+}
+export interface SesConfig {
+    readonly region: string;
+    /** Called for every send, so short-lived credentials can be refreshed by the app. */
+    readonly credentials: () => Promise<AwsCredentials>;
+    readonly configurationSet?: string;
+    /** Base URL instead of `https://email.<region>.amazonaws.com`; for tests against a local server. */
+    readonly endpoint?: string;
+}
+/**
+ * Amazon SES v2 provider. Posts to `/v2/email/outbound-emails`, signed with SigV4
+ * (no AWS SDK). Credentials come from the app, never from the environment.
+ * A non-2xx answer throws with the status and AWS's message.
+ */
+export declare function ses(config: SesConfig): MailProvider;
+/**
+ * Development stand-in: writes each rendered message to `<dir>/<messageId>.json`
+ * (from, to, subject, text, html) and logs one line, sending nothing.
+ * `mail.create` refuses it when the environment is production.
+ */
+export declare function devStandIn(config: {
+    readonly dir: string;
+}): MailProvider;
+//# sourceMappingURL=providers.d.ts.map

package/dist/infra/email/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../../src/infra/email/providers.ts"],"names":[],"mappings":"AAGA,OAAO,EAAU,KAAK,cAAc,EAAE,MAAM,YAAY,CAAA;AAExD,iDAAiD;AACjD,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CACnC;AAED,wFAAwF;AACxF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,IAAI,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC;QAAE,iBAAiB,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACvE;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,qFAAqF;IACrF,QAAQ,CAAC,WAAW,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,CAAA;IACnD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAClC,oGAAoG;IACpG,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,GAAG,CAAC,MAAM,EAAE,SAAS,GAAG,YAAY,CAsCnD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,YAAY,CAYzE"}

package/dist/infra/email/providers.js

@@ -0,0 +1,71 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getBaseLogger } from '../../core/logging/index.js';
+import { signV4 } from './sigv4.js';
+/**
+ * Amazon SES v2 provider. Posts to `/v2/email/outbound-emails`, signed with SigV4
+ * (no AWS SDK). Credentials come from the app, never from the environment.
+ * A non-2xx answer throws with the status and AWS's message.
+ */
+export function ses(config) {
+    const base = (config.endpoint ?? `https://email.${config.region}.amazonaws.com`).replace(/\/+$/, '');
+    return {
+        name: 'ses',
+        async send(message) {
+            const set = message.configurationSet ?? config.configurationSet;
+            const body = JSON.stringify({
+                FromEmailAddress: message.from,
+                Destination: { ToAddresses: [message.to] },
+                Content: {
+                    Simple: {
+                        Subject: { Data: message.subject, Charset: 'UTF-8' },
+                        Body: {
+                            Text: { Data: message.text, Charset: 'UTF-8' },
+                            ...(message.html !== undefined ? { Html: { Data: message.html, Charset: 'UTF-8' } } : {}),
+                        },
+                    },
+                },
+                ...(set !== undefined ? { ConfigurationSetName: set } : {}),
+            });
+            const url = `${base}/v2/email/outbound-emails`;
+            const headers = signV4({
+                method: 'POST', url, headers: { 'content-type': 'application/json' }, body,
+                region: config.region, service: 'ses', credentials: await config.credentials(),
+            });
+            const res = await fetch(url, { method: 'POST', headers, body });
+            const raw = await res.text();
+            let parsed = {};
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch { /* not JSON */ }
+            if (!res.ok) {
+                const detail = String(parsed['message'] ?? parsed['Message'] ?? raw.slice(0, 200));
+                throw new Error(`[pipework] SES refused the message: HTTP ${res.status} ${res.headers.get('x-amzn-errortype') ?? ''} ${detail}`.replace(/ +/g, ' '));
+            }
+            const id = parsed['MessageId'];
+            if (typeof id !== 'string')
+                throw new Error('[pipework] SES answered without a MessageId.');
+            return { providerMessageId: id };
+        },
+    };
+}
+/**
+ * Development stand-in: writes each rendered message to `<dir>/<messageId>.json`
+ * (from, to, subject, text, html) and logs one line, sending nothing.
+ * `mail.create` refuses it when the environment is production.
+ */
+export function devStandIn(config) {
+    return {
+        name: 'dev-stand-in',
+        async send(message) {
+            await mkdir(config.dir, { recursive: true });
+            const file = join(config.dir, `${message.messageId}.json`);
+            const { from, to, subject, text, html } = message;
+            await writeFile(file, JSON.stringify({ from, to, subject, text, ...(html !== undefined ? { html } : {}) }, null, 2));
+            getBaseLogger().info({ event: 'email dev stand-in', to, file }, 'email written to file instead of sent');
+            return { providerMessageId: `dev-${message.messageId}` };
+        },
+    };
+}
+//# sourceMappingURL=providers.js.map

package/dist/infra/email/providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../../../src/infra/email/providers.ts"],"names":[],"mappings":"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"}

package/dist/infra/email/schema.d.ts

@@ -0,0 +1,74 @@
+export declare const EMAIL_TABLE_NAMES: ReadonlySet<string>;
+export declare const EMAIL_STATUSES: readonly ["queued", "sending", "sent", "suppressed", "failed"];
+export declare const SUPPRESSION_REASONS: readonly ["bounce", "complaint"];
+export declare const emailMessages: import("../../data/domain/types.js").DefinedTable<{
+    id: import("../../data/domain/types.js").FieldDescriptor<string, {
+        defaultRandom: true;
+        hasDefault: true;
+    } & {
+        primaryKey: true;
+    }> & import("../../data/domain/field.js").FieldModifiers<string, {
+        defaultRandom: true;
+        hasDefault: true;
+    } & {
+        primaryKey: true;
+    }>;
+    key: import("../../data/domain/types.js").FieldDescriptor<string, {}> & import("../../data/domain/field.js").FieldModifiers<string, {}>;
+    toAddress: import("../../data/domain/types.js").FieldDescriptor<string, {}> & import("../../data/domain/field.js").FieldModifiers<string, {}>;
+    template: import("../../data/domain/types.js").FieldDescriptor<string, {}> & import("../../data/domain/field.js").FieldModifiers<string, {}>;
+    data: import("../../data/domain/types.js").FieldDescriptor<import("zod/v4").JSONType, {}> & import("../../data/domain/field.js").FieldModifiers<import("zod/v4").JSONType, {}>;
+    status: import("../../data/domain/types.js").FieldDescriptor<"failed" | "sent" | "queued" | "sending" | "suppressed", {
+        hasDefault: true;
+    }> & import("../../data/domain/field.js").FieldModifiers<"failed" | "sent" | "queued" | "sending" | "suppressed", {
+        hasDefault: true;
+    }>;
+    providerMessageId: import("../../data/domain/types.js").FieldDescriptor<string | null, {
+        nullable: true;
+    }> & import("../../data/domain/field.js").FieldModifiers<string | null, {
+        nullable: true;
+    }>;
+    error: import("../../data/domain/types.js").FieldDescriptor<string | null, {
+        nullable: true;
+    }> & import("../../data/domain/field.js").FieldModifiers<string | null, {
+        nullable: true;
+    }>;
+    traceId: import("../../data/domain/types.js").FieldDescriptor<string | null, {
+        nullable: true;
+    }> & import("../../data/domain/field.js").FieldModifiers<string | null, {
+        nullable: true;
+    }>;
+    createdAt: import("../../data/domain/types.js").FieldDescriptor<Date, {
+        hasDefault: true;
+    }> & import("../../data/domain/field.js").FieldModifiers<Date, {
+        hasDefault: true;
+    }>;
+    sentAt: import("../../data/domain/types.js").FieldDescriptor<Date | null, {
+        nullable: true;
+    }> & import("../../data/domain/field.js").FieldModifiers<Date | null, {
+        nullable: true;
+    }>;
+    sendingAt: import("../../data/domain/types.js").FieldDescriptor<Date | null, {
+        nullable: true;
+    }> & import("../../data/domain/field.js").FieldModifiers<Date | null, {
+        nullable: true;
+    }>;
+}, "pipework_email_messages">;
+export declare const emailSuppressions: import("../../data/domain/types.js").DefinedTable<{
+    address: import("../../data/domain/types.js").FieldDescriptor<string, {
+        primaryKey: true;
+    }> & import("../../data/domain/field.js").FieldModifiers<string, {
+        primaryKey: true;
+    }>;
+    reason: import("../../data/domain/types.js").FieldDescriptor<"bounce" | "complaint", {}> & import("../../data/domain/field.js").FieldModifiers<"bounce" | "complaint", {}>;
+    detail: import("../../data/domain/types.js").FieldDescriptor<import("zod/v4").JSONType, {
+        nullable: true;
+    }> & import("../../data/domain/field.js").FieldModifiers<import("zod/v4").JSONType, {
+        nullable: true;
+    }>;
+    createdAt: import("../../data/domain/types.js").FieldDescriptor<Date, {
+        hasDefault: true;
+    }> & import("../../data/domain/field.js").FieldModifiers<Date, {
+        hasDefault: true;
+    }>;
+}, "pipework_email_suppressions">;
+//# sourceMappingURL=schema.d.ts.map

package/dist/infra/email/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/infra/email/schema.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAEhD,CAAA;AAEF,eAAO,MAAM,cAAc,gEAAiE,CAAA;AAC5F,eAAO,MAAM,mBAAmB,kCAAmC,CAAA;AAEnE,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6BAkBxB,CAAA;AAEF,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;iCAK5B,CAAA"}

package/dist/infra/email/schema.js

@@ -0,0 +1,39 @@
+// The two tables behind `mail`. Enabled with `email: {}` in the blueprint;
+// `pipework generate` then emits them into the default database's migrations,
+// IF NOT EXISTS. Not tenant-scoped: a bounce notification arrives with no
+// tenant, and a suppressed address is suppressed for every tenant.
+import { define } from '../../data/domain/index.js';
+import { field } from '../../data/domain/field.js';
+import { schema } from '../../data/schema/namespace.js';
+import { index, unique } from '../../data/db/idx/index.js';
+export const EMAIL_TABLE_NAMES = new Set([
+    'pipework_email_messages', 'pipework_email_suppressions',
+]);
+export const EMAIL_STATUSES = ['queued', 'sending', 'sent', 'suppressed', 'failed'];
+export const SUPPRESSION_REASONS = ['bounce', 'complaint'];
+export const emailMessages = define('pipework_email_messages', {
+    id: field.uuid().defaultRandom().primaryKey(),
+    key: field.text(),
+    toAddress: field.text(),
+    template: field.text(),
+    data: field.jsonb(schema.check.json()),
+    status: field.enum(EMAIL_STATUSES).default('queued'),
+    providerMessageId: field.text().nullable(),
+    error: field.text().nullable(),
+    traceId: field.uuid().nullable(),
+    createdAt: field.timestamp().default('now'),
+    sentAt: field.timestamp().nullable(),
+    sendingAt: field.timestamp().nullable(),
+}, {
+    indexes: (t) => ({
+        byKey: unique('pipework_email_messages_key_key').on(t['key']),
+        byProviderId: index('idx_pipework_email_messages_provider_id').on(t['providerMessageId']),
+    }),
+});
+export const emailSuppressions = define('pipework_email_suppressions', {
+    address: field.text().primaryKey(),
+    reason: field.enum(SUPPRESSION_REASONS),
+    detail: field.jsonb(schema.check.json()).nullable(),
+    createdAt: field.timestamp().default('now'),
+});
+//# sourceMappingURL=schema.js.map

package/dist/infra/email/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/infra/email/schema.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,8EAA8E;AAC9E,0EAA0E;AAC1E,mEAAmE;AAEnE,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAA;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAA;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,gCAAgC,CAAA;AACvD,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAA;AAE1D,MAAM,CAAC,MAAM,iBAAiB,GAAwB,IAAI,GAAG,CAAC;IAC5D,yBAAyB,EAAE,6BAA6B;CACzD,CAAC,CAAA;AAEF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,QAAQ,CAAU,CAAA;AAC5F,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,QAAQ,EAAE,WAAW,CAAU,CAAA;AAEnE,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC,yBAAyB,EAAE;IAC7D,EAAE,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,aAAa,EAAE,CAAC,UAAU,EAAE;IAC7C,GAAG,EAAE,KAAK,CAAC,IAAI,EAAE;IACjB,SAAS,EAAE,KAAK,CAAC,IAAI,EAAE;IACvB,QAAQ,EAAE,KAAK,CAAC,IAAI,EAAE;IACtB,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IACtC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IACpD,iBAAiB,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE;IAC1C,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE;IAC9B,OAAO,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE;IAChC,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IAC3C,MAAM,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,QAAQ,EAAE;IACpC,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,QAAQ,EAAE;CACxC,EAAE;IACD,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACf,KAAK,EAAE,MAAM,CAAC,iCAAiC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QAC7D,YAAY,EAAE,KAAK,CAAC,yCAAyC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC;KAC1F,CAAC;CACH,CAAC,CAAA;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC,6BAA6B,EAAE;IACrE,OAAO,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,UAAU,EAAE;IAClC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC;IACvC,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE;IACnD,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;CAC5C,CAAC,CAAA"}

package/dist/infra/email/sigv4.d.ts

@@ -0,0 +1,24 @@
+export interface AwsCredentials {
+    readonly accessKeyId: string;
+    readonly secretAccessKey: string;
+    readonly sessionToken?: string;
+}
+export interface SigV4Request {
+    readonly method: string;
+    readonly url: string;
+    /** Headers to sign and send, other than host and x-amz-date, which are added. */
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: string | Buffer;
+    readonly region: string;
+    readonly service: string;
+    readonly credentials: AwsCredentials;
+    readonly now?: Date;
+}
+/**
+ * Signs a request with AWS Signature Version 4 and returns the headers to send:
+ * the given ones, `x-amz-date`, `x-amz-security-token` when the credentials carry
+ * a session token, and `authorization`. `host` is signed but not returned; the
+ * HTTP client sets it from the URL.
+ */
+export declare function signV4(req: SigV4Request): Record<string, string>;
+//# sourceMappingURL=sigv4.d.ts.map

package/dist/infra/email/sigv4.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sigv4.d.ts","sourceRoot":"","sources":["../../../src/infra/email/sigv4.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,WAAW,EAAE,cAAc,CAAA;IACpC,QAAQ,CAAC,GAAG,CAAC,EAAE,IAAI,CAAA;CACpB;AAkBD;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAwChE"}

package/dist/infra/email/sigv4.js

@@ -0,0 +1,55 @@
+import { createHash, createHmac } from 'node:crypto';
+function sha256Hex(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+function hmac(key, data) {
+    return createHmac('sha256', key).update(data).digest();
+}
+function uriEncode(s) {
+    return encodeURIComponent(s).replace(/[!'()*]/g, c => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+function amzDate(d) {
+    return d.toISOString().replace(/[-:]/g, '').replace(/\.\d{3}/, '');
+}
+/**
+ * Signs a request with AWS Signature Version 4 and returns the headers to send:
+ * the given ones, `x-amz-date`, `x-amz-security-token` when the credentials carry
+ * a session token, and `authorization`. `host` is signed but not returned; the
+ * HTTP client sets it from the URL.
+ */
+export function signV4(req) {
+    const url = new URL(req.url);
+    const stamp = amzDate(req.now ?? new Date());
+    const day = stamp.slice(0, 8);
+    const headers = {};
+    for (const [name, value] of Object.entries(req.headers))
+        headers[name.toLowerCase()] = value.trim().replace(/\s+/g, ' ');
+    headers['x-amz-date'] = stamp;
+    if (req.credentials.sessionToken !== undefined)
+        headers['x-amz-security-token'] = req.credentials.sessionToken;
+    const signed = { ...headers, host: url.host };
+    const names = Object.keys(signed).sort();
+    const canonicalHeaders = names.map(n => `${n}:${signed[n]}\n`).join('');
+    const signedHeaders = names.join(';');
+    const canonicalPath = url.pathname.split('/').map(uriEncode).join('/');
+    const canonicalQuery = [...url.searchParams.entries()]
+        .map(([k, v]) => [uriEncode(k), uriEncode(v)])
+        .sort((a, b) => (a[0] === b[0] ? (a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0) : (a[0] < b[0] ? -1 : 1)))
+        .map(([k, v]) => `${k}=${v}`)
+        .join('&');
+    const canonicalRequest = [
+        req.method.toUpperCase(), canonicalPath, canonicalQuery, canonicalHeaders, signedHeaders, sha256Hex(req.body),
+    ].join('\n');
+    const scope = `${day}/${req.region}/${req.service}/aws4_request`;
+    const stringToSign = ['AWS4-HMAC-SHA256', stamp, scope, sha256Hex(canonicalRequest)].join('\n');
+    const kDate = hmac(`AWS4${req.credentials.secretAccessKey}`, day);
+    const kRegion = hmac(kDate, req.region);
+    const kService = hmac(kRegion, req.service);
+    const kSigning = hmac(kService, 'aws4_request');
+    const signature = createHmac('sha256', kSigning).update(stringToSign).digest('hex');
+    return {
+        ...headers,
+        authorization: `AWS4-HMAC-SHA256 Credential=${req.credentials.accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`,
+    };
+}
+//# sourceMappingURL=sigv4.js.map

package/dist/infra/email/sigv4.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sigv4.js","sourceRoot":"","sources":["../../../src/infra/email/sigv4.ts"],"names":[],"mappings":"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"}

package/dist/infra/email/sns.d.ts

@@ -0,0 +1,32 @@
+import type { Handler } from '../../request/di/types.js';
+export interface SnsWebhookConfig {
+    readonly path: string;
+    /** The SNS topics whose messages are accepted. SNS signs every topic, so without this anyone could subscribe the endpoint to their own topic. */
+    readonly topicArns: readonly string[];
+    /** The SNS region; certificate and SubscribeURL hosts must be `sns.<region>.amazonaws.com`. Default: any AWS region. */
+    readonly region?: string;
+    /** Fetches the signing certificate PEM. Default: `fetch`. Tests serve their own. */
+    readonly fetchCert?: (url: string) => Promise<string>;
+    /** Confirms a subscription by GET of its SubscribeURL. Default: `fetch`. */
+    readonly confirm?: (url: string) => Promise<void>;
+}
+type SnsMessage = Record<string, string | undefined>;
+export declare function snsStringToSign(msg: SnsMessage): string;
+/**
+ * Receives SES bounce and complaint events delivered through SNS (HTTP/S subscription).
+ * A permanent bounce or any complaint puts the address (lowercased) on
+ * `pipework_email_suppressions`, which the send job checks; a transient or undetermined
+ * bounce is only logged. Each one is a trace step with an `Email:bounce` / `Email:complaint`
+ * audit record whose `after` carries `messageTraceId`, the trace of the original send.
+ * A suppression is logged at warn as `email suppressed`; the alert condition (#458) is not built yet.
+ *
+ * Only messages from the configured `topicArns` are accepted (401 otherwise, before any subscription is
+ * confirmed or event processed): SNS signs every topic, including an attacker's own.
+ * Every message's signature (SignatureVersion 1 or 2) is checked against the certificate
+ * at `SigningCertURL`, which must be `https://sns.<region>.amazonaws.com/...`; a failure is a 401.
+ * A SubscriptionConfirmation is confirmed by fetching its `SubscribeURL`.
+ * SES events delivered through EventBridge are not supported.
+ */
+export declare function snsWebhook(config: SnsWebhookConfig): Handler<Record<string, unknown>, unknown>;
+export {};
+//# sourceMappingURL=sns.d.ts.map

package/dist/infra/email/sns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sns.d.ts","sourceRoot":"","sources":["../../../src/infra/email/sns.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAA;AAKxD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,iJAAiJ;IACjJ,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IACrC,wHAAwH;IACxH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,oFAAoF;IACpF,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IACrD,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAClD;AAED,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;AAKpD,wBAAgB,eAAe,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAGvD;AAqED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,CA2D9F"}