pipework 0.70.0 → 0.71.0

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

@@ -0,0 +1,199 @@
+import type { Queue } from '../../async/jobs/queue.js';
+import type { Handler } from '../../request/di/types.js';
+import type { StorageBackend } from '../storage/backend.js';
+import type { Storage, StoredFile } from '../storage/handle.js';
+export declare const RECEIVE_JOB = "pipework.email.receive";
+export interface EmailAddress {
+    readonly address: string;
+    readonly name: string;
+}
+export interface ReceivedAttachment {
+    readonly filename: string | null;
+    readonly mediaType: string;
+    readonly size: number;
+    /** Lowercase hex SHA-256 of the decoded content. */
+    readonly sha256: string;
+    /** The `Content-ID` without angle brackets, for `cid:` references from the HTML. */
+    readonly contentId: string | null;
+    readonly inline: boolean;
+    /** The stored file, or `null` when no tenant was resolved or no `storage` was given. */
+    readonly file: StoredFile | null;
+}
+/** What SES concluded about a received message: each of `PASS`, `FAIL`, `GRAY` or `PROCESSING_FAILED`. */
+export interface EmailVerdicts {
+    readonly spam: string | null;
+    readonly virus: string | null;
+    readonly spf: string | null;
+    readonly dkim: string | null;
+    readonly dmarc: string | null;
+}
+/** What is known about a message before it is threaded: everything but its conversation and tenant. Handed to `resolveTenant`. */
+export type UnthreadedEmail = Omit<ReceivedEmail, 'conversationId' | 'isNewConversation' | 'tenantId'>;
+/** A received, parsed and threaded message, as handed to `onMessage`. */
+export interface ReceivedEmail {
+    /** The `pipework_email_inbound` row id; pass it as `inReplyTo` to `mail.send` to answer. */
+    readonly id: string;
+    readonly conversationId: string;
+    /** True when no earlier received or sent message matched this one's `In-Reply-To`/`References`. */
+    readonly isNewConversation: boolean;
+    readonly tenantId: string | null;
+    /** The `Message-ID` without angle brackets, or `null`. */
+    readonly messageId: string | null;
+    readonly inReplyTo: string | null;
+    readonly references: readonly string[];
+    /** An empty address and name when the message has no readable From. */
+    readonly from: EmailAddress;
+    readonly to: readonly EmailAddress[];
+    readonly cc: readonly EmailAddress[];
+    readonly replyTo: readonly EmailAddress[];
+    readonly subject: string;
+    readonly date: Date | null;
+    readonly text: string | null;
+    readonly html: string | null;
+    readonly attachments: readonly ReceivedAttachment[];
+    /** `null` for a message from the folder stand-in. */
+    readonly verdicts: EmailVerdicts | null;
+    /** The envelope recipients SES accepted the message for; for the stand-in, the To and Cc addresses. */
+    readonly recipients: readonly string[];
+}
+/** A received message's row, without bodies. */
+export interface InboundRecord {
+    readonly id: string;
+    readonly source: 'ses' | 'folder';
+    readonly status: 'received' | 'processed' | 'failed';
+    readonly error: string | null;
+    readonly messageId: string | null;
+    readonly conversationId: string | null;
+    readonly tenantId: string | null;
+    readonly subject: string | null;
+    readonly fromAddress: string | null;
+    readonly verdicts: EmailVerdicts | null;
+    readonly receivedAt: Date;
+    readonly processedAt: Date | null;
+    readonly rawExpiresAt: Date;
+    readonly rawDeletedAt: Date | null;
+}
+export interface InboundSweepResult {
+    /** Raw copies deleted. */
+    readonly deleted: number;
+    /** Raw copies that could not be deleted (left for the next sweep). */
+    readonly failed: number;
+}
+export interface InboundScanResult {
+    /** Files taken in. */
+    readonly received: number;
+    /** Files already taken in earlier (same bytes); moved to `received/` without a new row. */
+    readonly duplicates: number;
+}
+type RawLocation = Record<string, unknown>;
+/** Where received mail comes from. Made by `mail.sesReceipt` or `mail.inboundFolder`. */
+export interface InboundSource {
+    readonly kind: 'ses' | 'folder';
+    /** Reads the raw message; throws `RawTooLargeError` past `maxBytes` and `RawNotFoundError` when it definitely does not exist. */
+    read(location: RawLocation, maxBytes: number): Promise<Buffer>;
+    remove(location: RawLocation): Promise<void>;
+    readonly ses?: SesReceiptConfig;
+    readonly folder?: {
+        readonly dir: string;
+    };
+}
+export declare class RawNotFoundError extends Error {
+    constructor(detail: string);
+}
+export declare class RawTooLargeError extends Error {
+    readonly maxBytes: number;
+    constructor(maxBytes: number);
+}
+export interface SesReceiptConfig {
+    /** A storage backend over the SES receipt bucket with no prefix (`storage.s3({ bucket, region, credentials })`); keys are the S3 action's object keys. */
+    readonly bucket: StorageBackend;
+    /** The SNS topics SES publishes receipt notifications to. */
+    readonly topicArns: readonly string[];
+    readonly region?: string;
+    readonly fetchCert?: (url: string) => Promise<string>;
+    readonly confirm?: (url: string) => Promise<void>;
+}
+/**
+ * The SES receipt source. SES stores each raw message in S3 (receipt rule action "S3" with an SNS topic)
+ * and notifies the topic; `inbound.webhook` verifies the notification and records it, and the receive job
+ * reads the object from `bucket`. A notification whose action is not S3 (for example the SNS action,
+ * which carries the message inline), or whose type is not `Received`, is answered 200 and ignored.
+ */
+export declare function sesReceipt(config: SesReceiptConfig): InboundSource;
+/**
+ * The development source: `.eml` files dropped in `dir` are received by `inbound.scan()`, which copies each
+ * to `<dir>/received/` (where the raw copy stays until `sweep`) and removes the original. Refused when the
+ * environment is `production`.
+ */
+export declare function inboundFolder(config: {
+    readonly dir: string;
+}): InboundSource;
+export interface InboundConfig {
+    readonly source: InboundSource;
+    /** The app's job queue; its worker surface must run `inbound.jobs`. */
+    readonly queue: Queue;
+    /**
+     * Called in the receive job with each parsed, threaded message. A throw makes the queue retry the job.
+     * It is called at least once per message: a retry after a handler error, or a job re-run after a crash,
+     * calls it again with the same `id`. Make it idempotent on `id`.
+     */
+    readonly onMessage: (email: ReceivedEmail) => Promise<void> | void;
+    /** Stores attachments (as the resolved tenant's files). Without it, or without a tenant, attachments have `file: null`. */
+    readonly storage?: Storage;
+    /**
+     * Names the tenant a message belongs to (`null` for none), e.g. by its recipient address. It runs before
+     * threading, so it gets the message without a conversation: a message is only joined to a conversation of
+     * the same tenant (or of a message with no tenant).
+     */
+    readonly resolveTenant?: (email: UnthreadedEmail) => Promise<string | null>;
+    /** Days the raw copy is kept before `sweep` deletes it. Default 30. */
+    readonly rawRetentionDays?: number;
+    /** Raw messages larger than this are marked `failed` and not handled. Default 40 MiB. */
+    readonly maxRawBytes?: number;
+    /** The app's environment; `inboundFolder` is refused when this is `production`. */
+    readonly environment?: string;
+}
+export interface Inbound {
+    /** The public POST endpoint SNS delivers SES receipt notifications to (SES source only). */
+    webhook(config: {
+        readonly path: string;
+    }): Handler<Record<string, unknown>, unknown>;
+    /** Job handlers for the receive job; spread into the worker surface's `jobs`. */
+    readonly jobs: readonly Handler<Record<string, unknown>, unknown>[];
+    /** Folder source only: receives every `.eml` file in the folder. Needs a Flow (a job or schedule run). */
+    scan(): Promise<InboundScanResult>;
+    /** Deletes raw copies past their retention. Needs a Flow (a job or schedule run). */
+    sweep(options?: {
+        readonly limit?: number;
+    }): Promise<InboundSweepResult>;
+    /** The row of a received message, or `null`. Needs a Flow (a job, request or test context). */
+    get(id: string): Promise<InboundRecord | null>;
+}
+/**
+ * Receiving email. `inbound.webhook` (SES) or `inbound.scan` (folder) records each message in
+ * `pipework_email_inbound` and enqueues the `pipework.email.receive` job, once per message. The job
+ * reads the raw message, parses it, assigns a conversation, resolves the tenant, stores the attachments
+ * as that tenant's files and calls `onMessage` with a `ReceivedEmail`.
+ *
+ * Needs blueprint `email: {}` (table `pipework_email_inbound`; `pipework_email_messages` gains `conversation_id`).
+ * The row is not tenant-scoped (it exists before a tenant is known) and holds no bodies: the raw message
+ * is the copy and `sweep` deletes it after `rawRetentionDays`.
+ *
+ * Threading: the ids in In-Reply-To then References are matched to an earlier received message's
+ * Message-ID, or, for an id `<X@region.amazonses.com>`, to a sent message whose `provider_message_id` is `X`
+ * (set the sent message's conversation with `mail.send({ conversationId })` or `inReplyTo`). The first match
+ * decides the conversation; with none the message starts one (`isNewConversation: true`). Ids are matched exactly.
+ * A received message is matched only when its tenant equals the tenant `resolveTenant` named for this message or
+ * either is null; a sent message's conversation is refused when it holds a received message of another tenant.
+ *
+ * Threading is not authentication: Message-IDs are not secret and From is forgeable. Before attaching a message to
+ * a conversation's participants, the app checks `from` against them and the DKIM and DMARC verdicts.
+ *
+ * The receive job is a trace step `pipework/email:receive` with an `EmailInbound:received` audit record on success.
+ * A handler error (or a failure reading the raw message) rethrows so the queue retries; attachments stored by
+ * an earlier attempt are reused. Set `maxAttempts` on the queue. A raw message over `maxRawBytes` is marked
+ * `failed` and not retried. Message bodies are never logged.
+ */
+export declare function createInbound(config: InboundConfig): Inbound;
+export {};
+//# sourceMappingURL=inbound.d.ts.map

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

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

package/dist/infra/email/inbound.js

@@ -0,0 +1,451 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { copyFile, mkdir, readdir, readFile, stat, unlink } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { Readable } from 'node:stream';
+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 { getBaseLogger } from '../../core/logging/index.js';
+import { __flowStep } from '../../trace/runtime/flow-step.js';
+import { auditEmail } from './audit.js';
+import { parseMime } from './mime.js';
+import { snsHandler } from './sns.js';
+export const RECEIVE_JOB = 'pipework.email.receive';
+const DEFAULT_RETENTION_DAYS = 30;
+const DEFAULT_MAX_RAW_BYTES = 41_943_040;
+const DEFAULT_SWEEP_LIMIT = 500;
+export class RawNotFoundError extends Error {
+    constructor(detail) {
+        super(`raw message not found: ${detail}`);
+    }
+}
+export class RawTooLargeError extends Error {
+    maxBytes;
+    constructor(maxBytes) {
+        super(`raw message is larger than ${maxBytes} bytes`);
+        this.maxBytes = maxBytes;
+    }
+}
+async function collect(stream, maxBytes) {
+    const parts = [];
+    let size = 0;
+    for await (const chunk of stream) {
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buf.length;
+        if (size > maxBytes) {
+            if (stream instanceof Readable)
+                stream.destroy();
+            throw new RawTooLargeError(maxBytes);
+        }
+        parts.push(buf);
+    }
+    return Buffer.concat(parts);
+}
+/**
+ * The SES receipt source. SES stores each raw message in S3 (receipt rule action "S3" with an SNS topic)
+ * and notifies the topic; `inbound.webhook` verifies the notification and records it, and the receive job
+ * reads the object from `bucket`. A notification whose action is not S3 (for example the SNS action,
+ * which carries the message inline), or whose type is not `Received`, is answered 200 and ignored.
+ */
+export function sesReceipt(config) {
+    if (config.topicArns.length === 0)
+        throw new Error('[pipework] mail.sesReceipt needs at least one topic ARN in topicArns.');
+    return {
+        kind: 'ses',
+        ses: config,
+        async read(location, maxBytes) {
+            let stream;
+            try {
+                stream = await config.bucket.read(String(location['key']));
+            }
+            catch (err) {
+                if (/\bNoSuchKey\b/.test(err instanceof Error ? err.message : String(err)))
+                    throw new RawNotFoundError(String(location['key']));
+                throw err;
+            }
+            return collect(stream, maxBytes);
+        },
+        async remove(location) {
+            await config.bucket.remove(String(location['key']));
+        },
+    };
+}
+/**
+ * The development source: `.eml` files dropped in `dir` are received by `inbound.scan()`, which copies each
+ * to `<dir>/received/` (where the raw copy stays until `sweep`) and removes the original. Refused when the
+ * environment is `production`.
+ */
+export function inboundFolder(config) {
+    return {
+        kind: 'folder',
+        folder: config,
+        async read(location, maxBytes) {
+            const path = String(location['path']);
+            try {
+                if ((await stat(path)).size > maxBytes)
+                    throw new RawTooLargeError(maxBytes);
+                return await readFile(path);
+            }
+            catch (err) {
+                if (err.code === 'ENOENT')
+                    throw new RawNotFoundError(path);
+                throw err;
+            }
+        },
+        async remove(location) {
+            try {
+                await unlink(String(location['path']));
+            }
+            catch (err) {
+                if (err.code !== 'ENOENT')
+                    throw err;
+            }
+        },
+    };
+}
+function toDate(value) {
+    if (value instanceof Date)
+        return value;
+    const text = String(value);
+    return new Date(/(Z|[+-]\d\d(:?\d\d)?)$/.test(text) ? text : `${text.replace(' ', 'T')}Z`);
+}
+/** A Postgres text-array literal, sent as one parameter and cast with `::text[]`. */
+function textArray(values) {
+    return `{${values.map(v => `"${v.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`).join(',')}}`;
+}
+function verdictsOf(receipt) {
+    const status = (key) => {
+        const v = receipt[key];
+        return typeof v?.status === 'string' ? v.status : null;
+    };
+    return {
+        spam: status('spamVerdict'), virus: status('virusVerdict'), spf: status('spfVerdict'),
+        dkim: status('dkimVerdict'), dmarc: status('dmarcVerdict'),
+    };
+}
+function addressOf(a) {
+    return a === null ? { address: '', name: '' } : { address: a.address, name: a.name };
+}
+/**
+ * Receiving email. `inbound.webhook` (SES) or `inbound.scan` (folder) records each message in
+ * `pipework_email_inbound` and enqueues the `pipework.email.receive` job, once per message. The job
+ * reads the raw message, parses it, assigns a conversation, resolves the tenant, stores the attachments
+ * as that tenant's files and calls `onMessage` with a `ReceivedEmail`.
+ *
+ * Needs blueprint `email: {}` (table `pipework_email_inbound`; `pipework_email_messages` gains `conversation_id`).
+ * The row is not tenant-scoped (it exists before a tenant is known) and holds no bodies: the raw message
+ * is the copy and `sweep` deletes it after `rawRetentionDays`.
+ *
+ * Threading: the ids in In-Reply-To then References are matched to an earlier received message's
+ * Message-ID, or, for an id `<X@region.amazonses.com>`, to a sent message whose `provider_message_id` is `X`
+ * (set the sent message's conversation with `mail.send({ conversationId })` or `inReplyTo`). The first match
+ * decides the conversation; with none the message starts one (`isNewConversation: true`). Ids are matched exactly.
+ * A received message is matched only when its tenant equals the tenant `resolveTenant` named for this message or
+ * either is null; a sent message's conversation is refused when it holds a received message of another tenant.
+ *
+ * Threading is not authentication: Message-IDs are not secret and From is forgeable. Before attaching a message to
+ * a conversation's participants, the app checks `from` against them and the DKIM and DMARC verdicts.
+ *
+ * The receive job is a trace step `pipework/email:receive` with an `EmailInbound:received` audit record on success.
+ * A handler error (or a failure reading the raw message) rethrows so the queue retries; attachments stored by
+ * an earlier attempt are reused. Set `maxAttempts` on the queue. A raw message over `maxRawBytes` is marked
+ * `failed` and not retried. Message bodies are never logged.
+ */
+export function createInbound(config) {
+    if (config.source.kind === 'folder' && config.environment === 'production') {
+        throw new Error('[pipework] mail.inboundFolder is refused in production.\n\n' +
+            '  The stand-in reads .eml files from a folder.\n' +
+            '  Configure a real source, e.g. mail.sesReceipt({ bucket, topicArns }).\n');
+    }
+    const retentionDays = Math.floor(config.rawRetentionDays ?? DEFAULT_RETENTION_DAYS);
+    const maxRawBytes = config.maxRawBytes ?? DEFAULT_MAX_RAW_BYTES;
+    if (!(retentionDays >= 0))
+        throw new Error('[pipework] inbound rawRetentionDays must be zero or more.');
+    if (!(maxRawBytes > 0))
+        throw new Error('[pipework] inbound maxRawBytes must be positive.');
+    async function record(source, sourceId, location, extra) {
+        const traceId = getContext()?.trace?.id ?? null;
+        return pipeSystem().transaction(async (tx) => {
+            const inserted = await tx.execute(sql `
+        INSERT INTO pipework_email_inbound
+          (source_id, source, raw_location, raw_expires_at, verdicts, recipients, from_address, trace_id)
+        VALUES (${sourceId}, ${source}, ${JSON.stringify(location)}::jsonb, now() + make_interval(days => ${retentionDays}::int),
+          ${extra.verdicts === null ? null : JSON.stringify(extra.verdicts)}::jsonb,
+          ${extra.recipients === null ? null : JSON.stringify(extra.recipients)}::jsonb, ${extra.from}, ${traceId}::uuid)
+        ON CONFLICT (source_id) DO NOTHING
+        RETURNING id`);
+            if (inserted.length === 0)
+                return null;
+            const inboundId = inserted[0]['id'];
+            await config.queue.enqueue(tx, { type: RECEIVE_JOB, payload: { inboundId }, continueFlow: true });
+            return inboundId;
+        });
+    }
+    async function ingestNotification(message) {
+        let parsed;
+        try {
+            parsed = JSON.parse(message);
+        }
+        catch {
+            return { ignored: true };
+        }
+        if (typeof parsed !== 'object' || parsed === null)
+            return { ignored: true };
+        const event = parsed;
+        if (event['notificationType'] !== 'Received')
+            return { ignored: true };
+        const mailPart = event['mail'];
+        const receipt = event['receipt'];
+        const action = receipt?.['action'];
+        if (typeof mailPart?.messageId !== 'string' || receipt === undefined)
+            return { ignored: true };
+        if (action?.type !== 'S3' || typeof action.bucketName !== 'string' || typeof action.objectKey !== 'string') {
+            getBaseLogger().info({ event: 'email receipt ignored', actionType: action?.type ?? null }, 'SES receipt ignored: its action is not S3');
+            return { ignored: true };
+        }
+        const recipientList = Array.isArray(receipt['recipients']) ? receipt['recipients'] : mailPart.destination;
+        const recipients = Array.isArray(recipientList) ? recipientList.filter((r) => typeof r === 'string') : [];
+        const id = await record('ses', mailPart.messageId, { bucket: action.bucketName, key: action.objectKey }, {
+            verdicts: verdictsOf(receipt), recipients, from: typeof mailPart.source === 'string' ? mailPart.source : null,
+        });
+        if (id === null)
+            getBaseLogger().info({ event: 'email receipt duplicate', sourceId: mailPart.messageId }, 'SES receipt already recorded');
+        return {};
+    }
+    async function thread(ids, recorded, tenantId) {
+        const db = pipeSystem();
+        if (ids.length > 0) {
+            const sesLocals = ids.flatMap(id => {
+                const m = /^(.+)@[^@]*amazonses\.com$/i.exec(id);
+                return m === null ? [] : [m[1]];
+            });
+            const received = await db.execute(sql `
+        SELECT message_id_header AS id, conversation_id FROM pipework_email_inbound
+        WHERE message_id_header = ANY(${textArray(ids)}::text[]) AND conversation_id IS NOT NULL
+          AND (${tenantId}::uuid IS NULL OR tenant_id IS NULL OR tenant_id = ${tenantId}::uuid)`);
+            const sent = sesLocals.length === 0 ? [] : await db.execute(sql `
+        SELECT provider_message_id AS id, conversation_id FROM pipework_email_messages
+        WHERE provider_message_id = ANY(${textArray(sesLocals)}::text[]) AND conversation_id IS NOT NULL`);
+            const byId = new Map();
+            for (const r of received)
+                byId.set(r['id'], r['conversation_id']);
+            const bySes = new Map();
+            for (const r of sent) {
+                const conversation = r['conversation_id'];
+                const foreign = tenantId === null ? [] : await db.execute(sql `
+          SELECT 1 FROM pipework_email_inbound
+          WHERE conversation_id = ${conversation}::uuid AND tenant_id IS NOT NULL AND tenant_id <> ${tenantId}::uuid LIMIT 1`);
+                if (foreign.length === 0)
+                    bySes.set(r['id'], conversation);
+            }
+            for (const id of ids) {
+                const hit = byId.get(id) ?? bySes.get(/^(.+)@[^@]*amazonses\.com$/i.exec(id)?.[1] ?? '\u0000');
+                if (hit !== undefined)
+                    return { conversationId: hit, isNew: false };
+            }
+        }
+        // No match: this message's own conversation, kept from an earlier attempt of the job.
+        if (recorded !== null)
+            return { conversationId: recorded, isNew: true };
+        return { conversationId: randomUUID(), isNew: true };
+    }
+    async function fail(id, error) {
+        await pipeSystem().execute(sql `UPDATE pipework_email_inbound SET status = 'failed', error = ${error} WHERE id = ${id}::uuid`);
+        await auditEmail('failed', id, { error }, 'EmailInbound');
+        getBaseLogger().error({ event: 'email receive failed', inboundId: id }, `received email not handled: ${error}`);
+        return { status: 'failed' };
+    }
+    const receive = __flowStep({ ref: 'pipework/email:receive' }, async (inboundId) => {
+        const db = pipeSystem();
+        const row = (await db.execute(sql `SELECT * FROM pipework_email_inbound WHERE id = ${inboundId}::uuid`))[0];
+        if (row === undefined)
+            throw new Error(`[pipework] Received email ${inboundId} does not exist.`);
+        const status = row['status'];
+        if (status === 'processed' || status === 'failed')
+            return { status };
+        if (config.source.kind === 'folder' && getContext()?.instance.config.environment === 'production') {
+            throw new Error('[pipework] mail.inboundFolder is refused in production.');
+        }
+        if (row['raw_deleted_at'] !== null)
+            return fail(inboundId, 'the raw message was deleted before it was handled');
+        let raw;
+        try {
+            raw = await config.source.read(row['raw_location'], maxRawBytes);
+        }
+        catch (err) {
+            if (err instanceof RawTooLargeError || err instanceof RawNotFoundError)
+                return fail(inboundId, err.message);
+            const message = err instanceof Error ? err.message : String(err);
+            await db.execute(sql `UPDATE pipework_email_inbound SET error = ${message} WHERE id = ${inboundId}::uuid`);
+            throw err;
+        }
+        const parsed = parseMime(raw);
+        const recipients = row['recipients'] ?? [...parsed.to, ...parsed.cc].map(a => a.address);
+        const verdicts = row['verdicts'] ?? null;
+        const unthreaded = {
+            id: inboundId,
+            messageId: parsed.messageId, inReplyTo: parsed.inReplyTo, references: parsed.references,
+            from: addressOf(parsed.from),
+            to: parsed.to.map(addressOf), cc: parsed.cc.map(addressOf), replyTo: parsed.replyTo.map(addressOf),
+            subject: parsed.subject, date: parsed.date, text: parsed.text, html: parsed.html,
+            attachments: parsed.attachments.map(a => ({
+                filename: a.filename, mediaType: a.mediaType, size: a.size, sha256: createHash('sha256').update(a.content).digest('hex'),
+                contentId: a.contentId, inline: a.inline, file: null,
+            })),
+            verdicts, recipients,
+        };
+        let tenantId = row['tenant_id'] ?? null;
+        if (tenantId === null && config.resolveTenant !== undefined)
+            tenantId = await config.resolveTenant(unthreaded);
+        const { conversationId, isNew } = await thread(parsed.threadIds, row['conversation_id'] ?? null, tenantId);
+        const base = { ...unthreaded, conversationId, isNewConversation: isNew, tenantId };
+        await db.execute(sql `
+      UPDATE pipework_email_inbound SET
+        message_id_header = ${parsed.messageId}, in_reply_to = ${parsed.inReplyTo}, "references" = ${JSON.stringify(parsed.references)}::jsonb,
+        from_address = ${base.from.address}, subject = ${parsed.subject}, conversation_id = ${conversationId}::uuid,
+        tenant_id = ${tenantId}::uuid, recipients = ${JSON.stringify(recipients)}::jsonb, error = NULL
+      WHERE id = ${inboundId}::uuid`);
+        let attachments = base.attachments;
+        if (config.storage !== undefined && tenantId !== null && parsed.attachments.length > 0) {
+            const storage = config.storage;
+            const stored = Array.isArray(row['attachment_files']) ? [...row['attachment_files']] : [];
+            const files = [];
+            for (let i = 0; i < parsed.attachments.length; i++) {
+                const part = parsed.attachments[i];
+                let file = null;
+                const earlier = stored[i];
+                if (typeof earlier === 'string')
+                    file = await storage.getFor(tenantId, earlier);
+                if (file === null) {
+                    file = await storage.putFor(tenantId, {
+                        body: Readable.from([part.content]), mediaType: part.mediaType,
+                        ...(part.filename !== null ? { filename: part.filename } : {}),
+                        expectedSha256: attachments[i].sha256,
+                    });
+                    stored[i] = file.id;
+                    await db.execute(sql `UPDATE pipework_email_inbound SET attachment_files = ${JSON.stringify(stored)}::jsonb WHERE id = ${inboundId}::uuid`);
+                }
+                files.push(file);
+            }
+            attachments = attachments.map((a, i) => ({ ...a, file: files[i] ?? null }));
+        }
+        try {
+            await config.onMessage({ ...base, tenantId, attachments });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            await db.execute(sql `UPDATE pipework_email_inbound SET error = ${message} WHERE id = ${inboundId}::uuid`);
+            throw err;
+        }
+        const traceId = getContext()?.trace?.id ?? null;
+        await db.execute(sql `
+      UPDATE pipework_email_inbound SET status = 'processed', processed_at = now(), error = NULL, trace_id = COALESCE(${traceId}::uuid, trace_id)
+      WHERE id = ${inboundId}::uuid`);
+        await auditEmail('received', inboundId, {
+            conversationId, isNewConversation: isNew, tenantId, attachments: attachments.length,
+        }, 'EmailInbound');
+        return { status: 'processed' };
+    });
+    const receiveJob = fitting.use().job(RECEIVE_JOB)
+        .input(schema.check.object({ inboundId: schema.check.string() }))
+        .fit(async ({ input }) => receive(input.inboundId));
+    return {
+        webhook(webhook) {
+            const ses = config.source.ses;
+            if (config.source.kind !== 'ses' || ses === undefined) {
+                throw new Error('[pipework] inbound.webhook needs a mail.sesReceipt source; this inbound reads a folder.');
+            }
+            return snsHandler({
+                path: webhook.path, topicArns: ses.topicArns,
+                ...(ses.region !== undefined ? { region: ses.region } : {}),
+                ...(ses.fetchCert !== undefined ? { fetchCert: ses.fetchCert } : {}),
+                ...(ses.confirm !== undefined ? { confirm: ses.confirm } : {}),
+            }, ingestNotification);
+        },
+        jobs: [receiveJob],
+        async scan() {
+            const folder = config.source.folder;
+            if (config.source.kind !== 'folder' || folder === undefined) {
+                throw new Error('[pipework] inbound.scan needs a mail.inboundFolder source; this inbound receives through SES.');
+            }
+            let names;
+            try {
+                names = (await readdir(folder.dir)).filter(n => n.toLowerCase().endsWith('.eml')).sort();
+            }
+            catch (err) {
+                if (err.code === 'ENOENT')
+                    return { received: 0, duplicates: 0 };
+                throw err;
+            }
+            const done = join(folder.dir, 'received');
+            let received = 0;
+            let duplicates = 0;
+            for (const name of names) {
+                const from = join(folder.dir, name);
+                if (!(await stat(from)).isFile())
+                    continue;
+                const bytes = await readFile(from);
+                const sha = createHash('sha256').update(bytes).digest('hex');
+                await mkdir(done, { recursive: true });
+                const to = join(done, `${sha.slice(0, 12)}-${basename(name)}`);
+                await copyFile(from, to);
+                const id = await record('folder', `folder:${sha}`, { path: to }, { verdicts: null, recipients: null, from: null });
+                await unlink(from);
+                if (id === null)
+                    duplicates++;
+                else
+                    received++;
+            }
+            return { received, duplicates };
+        },
+        async sweep(options) {
+            const limit = options?.limit ?? DEFAULT_SWEEP_LIMIT;
+            const db = pipeSystem();
+            const due = await db.execute(sql `
+        SELECT id, raw_location FROM pipework_email_inbound
+        WHERE raw_expires_at <= now() AND raw_deleted_at IS NULL
+        ORDER BY raw_expires_at LIMIT ${limit}`);
+            let deleted = 0;
+            let failed = 0;
+            for (const row of due) {
+                try {
+                    await config.source.remove(row['raw_location']);
+                    await db.execute(sql `UPDATE pipework_email_inbound SET raw_deleted_at = now() WHERE id = ${row['id']}::uuid`);
+                    deleted++;
+                }
+                catch (err) {
+                    failed++;
+                    getBaseLogger().error({ err, inboundId: row['id'] }, 'inbound sweep could not delete a raw message');
+                }
+            }
+            return { deleted, failed };
+        },
+        async get(id) {
+            if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id))
+                return null;
+            const row = (await pipeSystem().execute(sql `SELECT * FROM pipework_email_inbound WHERE id = ${id}::uuid`))[0];
+            if (row === undefined)
+                return null;
+            const date = (v) => (v === null || v === undefined ? null : toDate(v));
+            return {
+                id: row['id'],
+                source: row['source'],
+                status: row['status'],
+                error: row['error'] ?? null,
+                messageId: row['message_id_header'] ?? null,
+                conversationId: row['conversation_id'] ?? null,
+                tenantId: row['tenant_id'] ?? null,
+                subject: row['subject'] ?? null,
+                fromAddress: row['from_address'] ?? null,
+                verdicts: row['verdicts'] ?? null,
+                receivedAt: toDate(row['received_at']),
+                processedAt: date(row['processed_at']),
+                rawExpiresAt: toDate(row['raw_expires_at']),
+                rawDeletedAt: date(row['raw_deleted_at']),
+            };
+        },
+    };
+}
+//# sourceMappingURL=inbound.js.map