pipework 0.69.0 → 0.71.0

package/dist/infra/access-links/person-check.js

@@ -0,0 +1,128 @@
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { sql } from '../../data/db/sql.js';
+import { pipeSystem } from '../../data/db/db.js';
+const ALGORITHM = 'SHA-256';
+const MIN_SECRET_BYTES = 32;
+const MAX_NUMBER_LIMIT = 10_000_000;
+const PRUNE_BATCH = 100;
+function sha256Hex(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+function sameBytes(a, b) {
+    return a.length === b.length && a.length > 0 && timingSafeEqual(a, b);
+}
+function sameHex(a, b) {
+    return sameBytes(Buffer.from(a, 'hex'), Buffer.from(b, 'hex'));
+}
+function positive(name, value) {
+    if (!Number.isFinite(value) || value <= 0)
+        throw new Error(`personCheck: ${name} must be a positive number`);
+    return value;
+}
+function createPersonCheck(config) {
+    const secret = typeof config.secret === 'string' ? Buffer.from(config.secret, 'utf8') : config.secret;
+    if (!Buffer.isBuffer(secret) || secret.length < MIN_SECRET_BYTES) {
+        throw new Error(`personCheck: secret must be ${String(MIN_SECRET_BYTES)} bytes or more, the same in every process (no random fallback: a per-process secret breaks passes across processes)`);
+    }
+    const maxNumber = config.maxNumber ?? 100_000;
+    if (!Number.isInteger(maxNumber) || maxNumber < 1 || maxNumber > MAX_NUMBER_LIMIT) {
+        throw new Error(`personCheck: maxNumber must be an integer from 1 to ${String(MAX_NUMBER_LIMIT)}`);
+    }
+    const challengeMs = positive('challengeMs', config.challengeMs ?? 600_000);
+    const passMs = positive('passMs', config.passMs ?? 1_800_000);
+    const database = config.database;
+    const key = (purpose) => createHmac('sha256', secret).update(`pipework access links person check: ${purpose}`).digest();
+    const challengeKey = key('challenge');
+    const passKey = key('pass');
+    function challenge(code) {
+        const expires = Math.floor((Date.now() + challengeMs) / 1000);
+        const salt = `${randomBytes(12).toString('hex')}?expires=${String(expires)}&link=${encodeURIComponent(code)}`;
+        const secretNumber = randomBytes(4).readUInt32BE() % (maxNumber + 1);
+        const digest = sha256Hex(salt + String(secretNumber));
+        const signature = createHmac('sha256', challengeKey).update(digest).digest('hex');
+        return { algorithm: ALGORITHM, challenge: digest, maxnumber: maxNumber, salt, signature };
+    }
+    function issuePass(code) {
+        const exp = Date.now() + passMs;
+        const body = Buffer.from(JSON.stringify({ code, exp })).toString('base64url');
+        const mac = createHmac('sha256', passKey).update(body).digest('base64url');
+        return { pass: `${body}.${mac}`, expiresAt: new Date(exp) };
+    }
+    // The challenge's expiry in ms when `solution` solves a live challenge made for `code`; otherwise null.
+    function solvedUntil(code, solution) {
+        if (typeof solution !== 'string')
+            return null;
+        let payload;
+        try {
+            payload = JSON.parse(Buffer.from(solution, 'base64').toString('utf8'));
+        }
+        catch {
+            return null;
+        }
+        if (typeof payload !== 'object' || payload === null || Array.isArray(payload))
+            return null;
+        const { algorithm, challenge: id, number, salt, signature } = payload;
+        if (algorithm !== ALGORITHM || typeof id !== 'string' || typeof salt !== 'string' || typeof signature !== 'string')
+            return null;
+        if (typeof number !== 'number' || !Number.isSafeInteger(number) || number < 0)
+            return null;
+        const params = new URLSearchParams(salt.split('?')[1] ?? '');
+        const expires = Number(params.get('expires'));
+        if (!Number.isFinite(expires) || expires * 1000 <= Date.now() || params.get('link') !== code)
+            return null;
+        const expected = createHmac('sha256', challengeKey).update(id).digest('hex');
+        if (!sameHex(expected, signature))
+            return null;
+        if (!sameHex(sha256Hex(salt + String(number)), id))
+            return null;
+        return { id, untilMs: expires * 1000 };
+    }
+    async function verify(code, solution) {
+        const solved = solvedUntil(code, solution);
+        if (solved === null)
+            return null;
+        const db = pipeSystem(database);
+        const spent = await db.execute(sql `
+      INSERT INTO access_link_check_spent (challenge, expires_at)
+      VALUES (${solved.id}, ${new Date(solved.untilMs).toISOString()})
+      ON CONFLICT DO NOTHING RETURNING 1 AS spent`);
+        if (spent.length === 0)
+            return null;
+        // Kept an hour past expiry so clock skew between processes and the database never reopens a solution.
+        await db.execute(sql `
+      DELETE FROM access_link_check_spent WHERE ctid IN (
+        SELECT ctid FROM access_link_check_spent WHERE expires_at < now() - interval '1 hour' LIMIT ${PRUNE_BATCH})`);
+        return issuePass(code);
+    }
+    const check = ({ link, proof }) => {
+        if (typeof proof !== 'string')
+            return Promise.resolve(false);
+        const parts = proof.split('.');
+        const [body, mac] = parts;
+        if (parts.length !== 2 || body === undefined || mac === undefined)
+            return Promise.resolve(false);
+        const expected = createHmac('sha256', passKey).update(body).digest();
+        if (!sameBytes(Buffer.from(mac, 'base64url'), expected))
+            return Promise.resolve(false);
+        try {
+            const claims = JSON.parse(Buffer.from(body, 'base64url').toString('utf8'));
+            return Promise.resolve(typeof claims.exp === 'number' && claims.exp > Date.now() && claims.code === link.code);
+        }
+        catch {
+            return Promise.resolve(false);
+        }
+    };
+    return { challenge, verify, check };
+}
+/** Solves a challenge the way the widget does and returns its base64 payload. For tests: it does the work the browser would. */
+function solvePersonChallenge(c) {
+    for (let n = 0; n <= c.maxnumber; n++) {
+        if (sha256Hex(c.salt + String(n)) === c.challenge) {
+            const payload = { algorithm: c.algorithm, challenge: c.challenge, number: n, salt: c.salt, signature: c.signature, took: 0 };
+            return Buffer.from(JSON.stringify(payload)).toString('base64');
+        }
+    }
+    throw new Error('personCheck.solve: challenge has no solution');
+}
+export const personCheck = Object.assign(createPersonCheck, { solve: solvePersonChallenge });
+//# sourceMappingURL=person-check.js.map

package/dist/infra/access-links/person-check.js.map

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

package/dist/infra/access-links/schema.d.ts

@@ -124,4 +124,12 @@ export declare const accessLinkUse: import("../../data/domain/types.js").Defined
         nullable: true;
     }>;
 }, "access_link_use">;
+export declare const accessLinkCheckSpent: import("../../data/domain/types.js").DefinedTable<{
+    challenge: import("../../data/domain/types.js").FieldDescriptor<string, {
+        primaryKey: true;
+    }> & import("../../data/domain/field.js").FieldModifiers<string, {
+        primaryKey: true;
+    }>;
+    expiresAt: import("../../data/domain/types.js").FieldDescriptor<Date, {}> & import("../../data/domain/field.js").FieldModifiers<Date, {}>;
+}, "access_link_check_spent">;
 //# sourceMappingURL=schema.d.ts.map

package/dist/infra/access-links/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/infra/access-links/schema.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,wBAAwB,gDAAiD,CAAA;AAEtF,eAAO,MAAM,cAAc;;;;;;;;;;;;;sBAKzB,CAAA;AAEF,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgBrB,CAAA;AAEF,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAiBxB,CAAA"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/infra/access-links/schema.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,wBAAwB,gDAAiD,CAAA;AAEtF,eAAO,MAAM,cAAc;;;;;;;;;;;;;sBAKzB,CAAA;AAEF,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgBrB,CAAA;AAEF,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAiBxB,CAAA;AAIF,eAAO,MAAM,oBAAoB;;;;;;;6BAG/B,CAAA"}

package/dist/infra/access-links/schema.js

@@ -1,4 +1,4 @@
-// The three tables behind access links. `access_link_code` is deliberately NOT
+// The four tables behind access links. `access_link_code` is deliberately NOT
 // tenant-scoped: it maps a code to its tenant so a request with no tenant can
 // find where to look, and holds nothing else. `access_link` and
 // `access_link_use` carry a `.tenant()` key, so generated migrations put them
@@ -49,4 +49,10 @@ export const accessLinkUse = define('access_link_use', {
         byLink: index('idx_access_link_use_link').on(t['linkId'], t['status']),
     }),
 });
+// Person-check solutions already accepted, kept until the challenge has expired:
+// one solved challenge makes one pass, across processes. Not tenant-scoped.
+export const accessLinkCheckSpent = define('access_link_check_spent', {
+    challenge: field.text().primaryKey(),
+    expiresAt: field.timestamp(),
+});
 //# sourceMappingURL=schema.js.map

package/dist/infra/access-links/schema.js.map

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

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

@@ -1,3 +1,3 @@
-/** Writes an `Email` audit record under the Flow's open trace step; does nothing when no step is open. */
-export declare function auditEmail(verb: string, entityId: string | null, details: Record<string, unknown>): Promise<void>;
+/** Writes an audit record (entity `Email` unless given) under the Flow's open trace step; does nothing when no step is open. */
+export declare function auditEmail(verb: string, entityId: string | null, details: Record<string, unknown>, entity?: string): Promise<void>;
 //# sourceMappingURL=audit.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../../src/infra/email/audit.ts"],"names":[],"mappings":"AAMA,0GAA0G;AAC1G,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAevH"}
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../../src/infra/email/audit.ts"],"names":[],"mappings":"AAMA,gIAAgI;AAChI,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,SAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAezI"}

package/dist/infra/email/audit.js

@@ -3,8 +3,8 @@ import { pipeSystem } from '../../data/db/db.js';
 import { getContext } from '../../request/context/store.js';
 import { resolveActorId } from '../../data/write/audit/actor.js';
 import { getBaseLogger } from '../../core/logging/index.js';
-/** Writes an `Email` audit record under the Flow's open trace step; does nothing when no step is open. */
-export async function auditEmail(verb, entityId, details) {
+/** Writes an audit record (entity `Email` unless given) under the Flow's open trace step; does nothing when no step is open. */
+export async function auditEmail(verb, entityId, details, entity = 'Email') {
     const flow = getContext();
     const trace = flow?.trace;
     const stepId = trace?.buffer.openStepId ?? null;
@@ -15,7 +15,7 @@ export async function auditEmail(verb, entityId, details) {
       INSERT INTO audit_record
         (trace_day, trace_id, trace_step_id, tenant_id, actor_id, entity, verb, entity_id, after, occurred_at)
       VALUES (${trace.openedDay}, ${trace.id}, ${stepId}, ${flow.tenant}, ${resolveActorId(flow)},
-        'Email', ${verb}, ${entityId}, ${JSON.stringify(details)}::jsonb, now())
+        ${entity}, ${verb}, ${entityId}, ${JSON.stringify(details)}::jsonb, now())
     `);
     }
     catch (err) {

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

@@ -1 +1 @@
-{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../../src/infra/email/audit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAA;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAA;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAA;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAE3D,0GAA0G;AAC1G,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAY,EAAE,QAAuB,EAAE,OAAgC;IACtG,MAAM,IAAI,GAAG,UAAU,EAAE,CAAA;IACzB,MAAM,KAAK,GAAG,IAAI,EAAE,KAAK,CAAA;IACzB,MAAM,MAAM,GAAG,KAAK,EAAE,MAAM,CAAC,UAAU,IAAI,IAAI,CAAA;IAC/C,IAAI,IAAI,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,KAAK,IAAI;QAAE,OAAM;IAC1F,IAAI,CAAC;QACH,MAAM,UAAU,EAAE,CAAC,OAAO,CAAC,GAAG,CAAA;;;gBAGlB,KAAK,CAAC,SAAS,KAAK,KAAK,CAAC,EAAE,KAAK,MAAM,KAAK,IAAI,CAAC,MAAM,KAAK,cAAc,CAAC,IAAI,CAAC;mBAC7E,IAAI,KAAK,QAAQ,KAAK,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;KAC3D,CAAC,CAAA;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,aAAa,EAAE,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,EAAE,EAAE,6BAA6B,IAAI,eAAe,CAAC,CAAA;IACrG,CAAC;AACH,CAAC"}
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../../src/infra/email/audit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAA;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAA;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAA;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAE3D,gIAAgI;AAChI,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAY,EAAE,QAAuB,EAAE,OAAgC,EAAE,MAAM,GAAG,OAAO;IACxH,MAAM,IAAI,GAAG,UAAU,EAAE,CAAA;IACzB,MAAM,KAAK,GAAG,IAAI,EAAE,KAAK,CAAA;IACzB,MAAM,MAAM,GAAG,KAAK,EAAE,MAAM,CAAC,UAAU,IAAI,IAAI,CAAA;IAC/C,IAAI,IAAI,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,KAAK,IAAI;QAAE,OAAM;IAC1F,IAAI,CAAC;QACH,MAAM,UAAU,EAAE,CAAC,OAAO,CAAC,GAAG,CAAA;;;gBAGlB,KAAK,CAAC,SAAS,KAAK,KAAK,CAAC,EAAE,KAAK,MAAM,KAAK,IAAI,CAAC,MAAM,KAAK,cAAc,CAAC,IAAI,CAAC;UACtF,MAAM,KAAK,IAAI,KAAK,QAAQ,KAAK,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;KAC7D,CAAC,CAAA;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,aAAa,EAAE,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,EAAE,EAAE,6BAA6B,IAAI,eAAe,CAAC,CAAA;IACrG,CAAC;AACH,CAAC"}

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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"}