humanish 0.20.5 → 0.22.0

package/dist/comms-email-catch.d.ts

@@ -0,0 +1,53 @@
+import { type ServerResponse } from "node:http";
+import type { CommsChannel } from "./comms-types.js";
+/** One send, normalized across providers. `body` is html-preferred, else text. */
+export interface NormalizedSend {
+    from: string;
+    to: string[];
+    subject?: string;
+    body: string;
+}
+/**
+ * A provider wire-shape adapter. Vendor-neutral seam: the server owns the HTTP + routing + bus
+ * delivery; a profile only knows how ONE provider (or a custom app) shapes its send request.
+ */
+export interface EmailSendProfile {
+    /** Descriptive name (e.g. "generic", "sendgrid"). Not a dependency — just a label. */
+    name: string;
+    /** Request paths (method POST) this profile accepts a send on. */
+    sendPaths: string[];
+    /** Parse a POST body (already JSON-parsed) into zero+ normalized sends (a batch yields many). */
+    parse(path: string, body: unknown): NormalizedSend[];
+    /** Optional provider-faithful success response. Default: 200 `{ id }` (single) / `{ data:[{id}] }`. */
+    respond?: (res: ServerResponse, ids: string[], batch: boolean) => void;
+}
+export interface EmailCatchServer {
+    /** Point the app's email-API base URL here (loopback only). */
+    readonly url: string;
+    readonly port: number;
+    /** Every normalized send accepted this run (runtime-only; for inspection/tests). */
+    readonly received: NormalizedSend[];
+    close(): Promise<void>;
+}
+export interface EmailCatchOptions {
+    /** Bind host. Default 127.0.0.1 (loopback ONLY). */
+    host?: string;
+    /** Port. Default 0 (ephemeral). */
+    port?: number;
+    /** Wire-shape profiles, tried in order by path. Default [genericEmailProfile, sendgridEmailProfile]. */
+    profiles?: EmailSendProfile[];
+    /** Deterministic id for responses (tests). Default a zero-padded counter. */
+    idFor?: (n: number) => string;
+}
+/** The flat-JSON shape: `{ from, to, subject, html, text }`. Matches Resend (POST /emails) AND a
+ *  custom app that sends the common shape AND Postmark's TitleCase keys (From/To/HtmlBody/…). */
+export declare const genericEmailProfile: EmailSendProfile;
+/** SendGrid's nested shape: `from.email`, `personalizations[].to[].email`, `content[].value`. Proves
+ *  the seam handles a structurally different vendor, not just a field-name rename. */
+export declare const sendgridEmailProfile: EmailSendProfile;
+export declare const DEFAULT_EMAIL_PROFILES: EmailSendProfile[];
+/**
+ * Start the vendor-neutral email catch, routing accepted sends into `channel`. Returns the loopback
+ * URL to hand the app as its email-API base URL. `close()` in a finally (mirror by-id teardown).
+ */
+export declare function startEmailCatchServer(channel: CommsChannel, options?: EmailCatchOptions): Promise<EmailCatchServer>;

package/dist/comms-email-catch.js

@@ -0,0 +1,209 @@
+// A VENDOR-NEUTRAL loopback catch server for email-send APIs (#297). An app hardwired to a hosted
+// email provider is redirected into the faux bus with ONE env var and no code change: point the app's
+// API base URL at this server. The catch does not depend on, or name itself after, any one vendor —
+// it normalizes each provider's distinct wire shape (Resend's flat body, SendGrid's nested
+// personalizations, Postmark's TitleCase, a custom app's own JSON) to one shape via pluggable
+// PROFILES, and routes the result into a CommsChannel. Resend-compatible and SendGrid-compatible out
+// of the box; extend with a custom profile for anything else. (There is no standardized email-send
+// request shape across vendors, so normalization is by design, not a shortcut.)
+//
+// 127.0.0.1 only; request bodies are never logged; request size is capped.
+import { createServer } from "node:http";
+// ---------------------------------------------------------------- shared parse helpers
+function str(value) {
+    return typeof value === "string" ? value : "";
+}
+function optStr(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/** "Name <email@host>" → "email@host"; a bare address passes through. */
+function bareEmail(value) {
+    const angle = value.match(/<([^>]+)>/);
+    return (angle ? angle[1] ?? value : value).trim();
+}
+/** A recipient field → address strings: an array, a single, or a comma-separated string (Postmark). */
+function toAddresses(value) {
+    if (Array.isArray(value))
+        return value.map((entry) => bareEmail(String(entry)));
+    if (typeof value === "string")
+        return value.split(",").map((part) => bareEmail(part)).filter((part) => part.length > 0);
+    return [];
+}
+// ---------------------------------------------------------------- built-in profiles
+/** The flat-JSON shape: `{ from, to, subject, html, text }`. Matches Resend (POST /emails) AND a
+ *  custom app that sends the common shape AND Postmark's TitleCase keys (From/To/HtmlBody/…). */
+export const genericEmailProfile = {
+    name: "generic",
+    sendPaths: ["/emails", "/emails/batch", "/email", "/email/batch", "/send"],
+    parse(_path, body) {
+        const items = Array.isArray(body) ? body : [body];
+        const out = [];
+        for (const item of items) {
+            if (typeof item !== "object" || item === null)
+                continue;
+            const rec = item;
+            const from = str(rec.from ?? rec.From);
+            const to = toAddresses(rec.to ?? rec.To);
+            const subject = optStr(rec.subject ?? rec.Subject);
+            const bodyValue = str(rec.html ?? rec.HtmlBody ?? rec.text ?? rec.TextBody);
+            if (to.length === 0 && from === "" && bodyValue === "")
+                continue;
+            out.push({ from, to, ...(subject === undefined ? {} : { subject }), body: bodyValue });
+        }
+        return out;
+    }
+};
+/** SendGrid's nested shape: `from.email`, `personalizations[].to[].email`, `content[].value`. Proves
+ *  the seam handles a structurally different vendor, not just a field-name rename. */
+export const sendgridEmailProfile = {
+    name: "sendgrid",
+    sendPaths: ["/v3/mail/send"],
+    parse(_path, body) {
+        if (typeof body !== "object" || body === null)
+            return [];
+        const rec = body;
+        const fromObj = rec.from;
+        const from = typeof fromObj === "object" && fromObj !== null ? str(fromObj.email) : str(fromObj);
+        const subject = optStr(rec.subject);
+        const content = Array.isArray(rec.content) ? rec.content : [];
+        const isPart = (part) => typeof part === "object" && part !== null;
+        const chosen = content.find((part) => isPart(part) && part.type === "text/html") ??
+            content.find((part) => isPart(part) && part.type === "text/plain");
+        const bodyValue = isPart(chosen) ? str(chosen.value) : "";
+        const personalizations = Array.isArray(rec.personalizations) ? rec.personalizations : [];
+        const to = [];
+        for (const personalization of personalizations) {
+            if (!isPart(personalization))
+                continue;
+            const recipients = Array.isArray(personalization.to) ? personalization.to : [];
+            for (const recipient of recipients) {
+                if (!isPart(recipient))
+                    continue;
+                const email = str(recipient.email);
+                if (email.length > 0)
+                    to.push(email);
+            }
+        }
+        if (to.length === 0)
+            return [];
+        return [{ from, to, ...(subject === undefined ? {} : { subject }), body: bodyValue }];
+    },
+    respond(res, ids, _batch) {
+        // SendGrid answers 202 with the id in a header and an empty body.
+        res.statusCode = 202;
+        if (ids[0] !== undefined)
+            res.setHeader("x-message-id", ids[0]);
+        res.end();
+    }
+};
+export const DEFAULT_EMAIL_PROFILES = [genericEmailProfile, sendgridEmailProfile];
+// ---------------------------------------------------------------- server
+class BodyTooLargeError extends Error {
+}
+function readBody(req, limit) {
+    return new Promise((resolve, reject) => {
+        let size = 0;
+        const chunks = [];
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > limit) {
+                // Reject WITHOUT destroying the socket here: the handler responds 413 cleanly first (a
+                // write-after-destroy would otherwise reset the connection), then tears the request down.
+                reject(new BodyTooLargeError("request body too large"));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        req.on("error", reject);
+    });
+}
+const MAX_BODY_BYTES = 5 * 1024 * 1024;
+/**
+ * Start the vendor-neutral email catch, routing accepted sends into `channel`. Returns the loopback
+ * URL to hand the app as its email-API base URL. `close()` in a finally (mirror by-id teardown).
+ */
+export async function startEmailCatchServer(channel, options = {}) {
+    const host = options.host ?? "127.0.0.1";
+    const profiles = options.profiles ?? DEFAULT_EMAIL_PROFILES;
+    const received = [];
+    let idCounter = 0;
+    const idFor = options.idFor ?? ((n) => `humanish-catch-${n.toString().padStart(6, "0")}`);
+    const respondJson = (res, status, value) => {
+        res.statusCode = status;
+        res.setHeader("content-type", "application/json");
+        res.end(JSON.stringify(value));
+    };
+    const handle = async (req, res) => {
+        const path = (req.url ?? "/").split("?")[0] ?? "/";
+        if (req.method === "GET" && (path === "/" || path === "/health")) {
+            respondJson(res, 200, { ok: true, service: "humanish-email-catch", channel: channel.channel, profiles: profiles.map((p) => p.name) });
+            return;
+        }
+        const profile = req.method === "POST" ? profiles.find((candidate) => candidate.sendPaths.includes(path)) : undefined;
+        if (profile === undefined) {
+            respondJson(res, 404, { error: "not found" });
+            return;
+        }
+        let raw;
+        try {
+            raw = await readBody(req, MAX_BODY_BYTES);
+        }
+        catch (error) {
+            if (!res.headersSent)
+                respondJson(res, error instanceof BodyTooLargeError ? 413 : 400, { error: "request body could not be read" });
+            req.destroy();
+            return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw.length > 0 ? raw : "{}");
+        }
+        catch {
+            respondJson(res, 422, { error: "invalid JSON body" });
+            return;
+        }
+        const sends = profile.parse(path, parsed);
+        if (sends.length === 0) {
+            // A well-formed request that names no deliverable recipient (empty body, or a shape the profile
+            // could not resolve to a send) — return a bad-request rather than a fabricated success id.
+            respondJson(res, 422, { error: "no deliverable message in request" });
+            return;
+        }
+        const ids = [];
+        for (const send of sends) {
+            received.push(send);
+            const inbound = {
+                from: send.from,
+                to: send.to,
+                ...(send.subject === undefined ? {} : { subject: send.subject }),
+                body: send.body
+            };
+            await channel.deliverRaw(inbound);
+            idCounter += 1;
+            ids.push(idFor(idCounter));
+        }
+        const batch = Array.isArray(parsed) || path.endsWith("/batch");
+        if (profile.respond)
+            profile.respond(res, ids, batch);
+        else if (batch)
+            respondJson(res, 200, { data: ids.map((id) => ({ id })) });
+        else
+            respondJson(res, 200, { id: ids[0] ?? idFor(idCounter) });
+    };
+    const server = createServer((req, res) => {
+        void handle(req, res).catch(() => {
+            if (!res.headersSent)
+                respondJson(res, 500, { error: "catch server error" });
+        });
+    });
+    await new Promise((resolve) => server.listen(options.port ?? 0, host, () => resolve()));
+    const port = server.address().port;
+    return {
+        url: `http://${host}:${port}`,
+        port,
+        received,
+        close: () => new Promise((resolve) => server.close(() => resolve()))
+    };
+}
+//# sourceMappingURL=comms-email-catch.js.map

package/dist/comms-email-catch.js.map

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

package/dist/comms-evidence.d.ts

@@ -0,0 +1,27 @@
+import type { CommsMessage } from "./comms-types.js";
+export declare const COMMS_THREAD_SCHEMA = "humanish.comms-thread.v1";
+export interface CommsThreadEntry {
+    id: string;
+    channel: CommsMessage["channel"];
+    /** sha256-16 of the raw sender address. */
+    fromDigest: string;
+    /** sha256-16 of each recipient inbox address. */
+    toDigests: string[];
+    /** sha256-16 of the subject (non-reversible for a PII subject; correlates identical subjects). */
+    subjectDigest?: string;
+    /** sha256-16 of each actionable link (high-entropy → non-reversible). */
+    linkDigests: string[];
+    /** COUNT ONLY — a short OTP's digest is reversible, so the code itself never lands here. */
+    codeCount: number;
+    sentAt: number;
+    deliveredAt: number;
+}
+export interface CommsThreadArtifact {
+    schema: typeof COMMS_THREAD_SCHEMA;
+    channel: CommsMessage["channel"];
+    count: number;
+    thread: CommsThreadEntry[];
+}
+/** Project polled inbox messages into the digest-only thread artifact. Pure; the caller writes it into
+ *  the run dir and registers it as an adapter-artifact. */
+export declare function buildCommsThreadArtifact(messages: CommsMessage[]): CommsThreadArtifact;

package/dist/comms-evidence.js

@@ -0,0 +1,31 @@
+// Digest-only evidence for a captured comms thread (#297). Proves "the verification mail arrived and
+// the persona could act on it" WITHOUT persisting raw PHI. Written as an adapter-artifact
+// (humanish.comms-thread.v1), so it inherits the bundle's existence-verify + public-safety scan.
+//
+// Digest discipline (deliberate, see below): addresses + links are digested (high entropy → the digest
+// is not reversible). The subject is DIGESTED too, not stored as text — redactText only scrubs
+// secret-SHAPED tokens/paths, not free-form PII (the #108 gap), so a subject like "results for <name>"
+// would pass through verbatim; a sha256-16 keeps a PII subject non-reversible while still letting you
+// correlate identical subjects. OTP CODES are a COUNT ONLY, never digested — a sha256 of a 6-digit code
+// has ~10^6 preimages and is trivially brute-forced back to the code, so a "code digest" would leak it.
+// Net: NO raw address/subject/link/OTP text ever lands in the artifact. Same caution as the lobby code.
+import { digestText } from "./redaction.js";
+export const COMMS_THREAD_SCHEMA = "humanish.comms-thread.v1";
+/** Project polled inbox messages into the digest-only thread artifact. Pure; the caller writes it into
+ *  the run dir and registers it as an adapter-artifact. */
+export function buildCommsThreadArtifact(messages) {
+    const channel = messages[0]?.channel ?? "email";
+    const thread = messages.map((message) => ({
+        id: message.id,
+        channel: message.channel,
+        fromDigest: digestText(message.from, 16),
+        toDigests: message.to.map((address) => address.digest),
+        ...(message.subject === undefined ? {} : { subjectDigest: digestText(message.subject, 16) }),
+        linkDigests: message.links.map((link) => digestText(link, 16)),
+        codeCount: message.codes.length,
+        sentAt: message.sentAt,
+        deliveredAt: message.deliveredAt
+    }));
+    return { schema: COMMS_THREAD_SCHEMA, channel, count: thread.length, thread };
+}
+//# sourceMappingURL=comms-evidence.js.map

package/dist/comms-evidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comms-evidence.js","sourceRoot":"","sources":["../src/comms-evidence.ts"],"names":[],"mappings":"AAAA,qGAAqG;AACrG,0FAA0F;AAC1F,iGAAiG;AACjG,EAAE;AACF,uGAAuG;AACvG,+FAA+F;AAC/F,uGAAuG;AACvG,sGAAsG;AACtG,wGAAwG;AACxG,wGAAwG;AACxG,wGAAwG;AAGxG,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE5C,MAAM,CAAC,MAAM,mBAAmB,GAAG,0BAA0B,CAAC;AA0B9D;2DAC2D;AAC3D,MAAM,UAAU,wBAAwB,CAAC,QAAwB;IAC/D,MAAM,OAAO,GAA4B,QAAQ,CAAC,CAAC,CAAC,EAAE,OAAO,IAAI,OAAO,CAAC;IACzE,MAAM,MAAM,GAAuB,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QAC5D,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,UAAU,EAAE,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC;QACxC,SAAS,EAAE,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC;QACtD,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,UAAU,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,EAAE,CAAC;QAC5F,WAAW,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC9D,SAAS,EAAE,OAAO,CAAC,KAAK,CAAC,MAAM;QAC/B,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,WAAW,EAAE,OAAO,CAAC,WAAW;KACjC,CAAC,CAAC,CAAC;IACJ,OAAO,EAAE,MAAM,EAAE,mBAAmB,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;AAChF,CAAC"}

package/dist/comms-faux-inbox.js

@@ -1,5 +1,5 @@
 // The FAUX in-process email/SMS bus (#297 Stage 2). Deterministic, $0, offline, public-safe: a
-// message an app-under-test "sends" (via an ingress like the Resend catch) is routed to the
+// message an app-under-test "sends" (via an ingress like the vendor-neutral email catch) is routed to the
 // addressed actor inbox and read back through the same CommsChannel port a real provider adapter
 // would implement. Nothing leaves the process. See comms-types.ts for the port + public-safety notes.
 import { digestText } from "./redaction.js";
@@ -51,7 +51,9 @@ export function extractOtpCodes(body) {
             list.push(c);
         }
     };
-    const labeledRe = /(?:one[-\s]?time\s+(?:pass)?code|verification\s+code|security\s+code|access\s+code|login\s+code|confirmation\s+code|passcode|\bOTP\b|\bPIN\b|\bcode\b)\D{0,15}\b([0-9]{4,8}|[A-Z0-9]{6,8})\b/gi;
+    // The alphanumeric alternative requires at least one DIGIT (lookahead) so a labeled prose word like
+    // "your code is INVALID" isn't captured as a code; pure-digit codes (4–8) match directly.
+    const labeledRe = /(?:one[-\s]?time\s+(?:pass)?code|verification\s+code|security\s+code|access\s+code|login\s+code|confirmation\s+code|passcode|\bOTP\b|\bPIN\b|\bcode\b)\D{0,15}\b([0-9]{4,8}|(?=[A-Za-z0-9]*[0-9])[A-Z0-9]{6,8})\b/gi;
     let m;
     while ((m = labeledRe.exec(text)) !== null)
         push(labeled, m[1] ?? "");
@@ -91,6 +93,14 @@ export class FauxInbox {
         if (existing)
             return existing;
         const value = this.channel === "sms" ? smsAddressFor(actorId) : `${sanitizeLocalPart(actorId)}@${this.domain}`;
+        // Address collision guard: two distinct actor ids can sanitize to the same local part. Reuse the
+        // existing inbox rather than resetting its queue (which would drop already-delivered mail). Both
+        // actors then share it — a faux-world edge; declare distinct addresses to avoid it.
+        const prior = this.byValue.get(value.toLowerCase());
+        if (prior) {
+            this.byActor.set(actorId, prior);
+            return prior;
+        }
         const address = { channel: this.channel, actorId, value, digest: digestText(value, 16) };
         this.byActor.set(actorId, address);
         this.byValue.set(value.toLowerCase(), address);

package/dist/comms-faux-inbox.js.map

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

package/dist/comms-sandbox-catch.d.ts

@@ -0,0 +1,63 @@
+import type { CommsChannel } from "./comms-types.js";
+import { type EmailSendProfile } from "./comms-email-catch.js";
+import { type DetachedTimers } from "./e2b-detached.js";
+import type { E2BDesktopSandbox } from "./e2b-desktop-launch.js";
+/** The default in-sandbox loopback port for the catch. Fixed (not ephemeral) so the injected base-URL
+ *  env is known before `createDesktopSandbox`. 8025 is the conventional local-mail-UI port and is
+ *  unlikely to collide with a subject app; override via config if it does. */
+export declare const DEFAULT_SANDBOX_CATCH_PORT = 8025;
+/**
+ * The self-contained in-sandbox capture server (a plain node ESM string — runs on the sandbox's own
+ * node, imports nothing from humanish). It is DELIBERATELY dumb: it records each POST verbatim as an
+ * NDJSON line `{t, path, body}` and returns a plausible provider success — all normalization/profile
+ * parsing happens host-side on the drained lines, so the typed, tested profiles stay in one place.
+ * argv: <port> <deliveriesFile>.
+ */
+export declare const SANDBOX_CATCH_SCRIPT: string;
+export interface DeployCommsCatchOptions {
+    /** Fixed loopback port the catch listens on (default 8025). Must be free inside the sandbox. */
+    port?: number;
+    /** In-sandbox working dir for the script + NDJSON (default /tmp/humanish-comms). */
+    dir?: string;
+    /** Detached-process name ([a-z0-9-]); default "comms-catch". */
+    name?: string;
+    /** Readiness-probe budget (ms) for the catch's /health (default 15000). */
+    readyTimeoutMs?: number;
+    requestTimeoutMs?: number;
+    timers?: DetachedTimers;
+}
+export interface DeployedCommsCatch {
+    port: number;
+    /** Inject THIS as the app's email-API base URL (e.g. RESEND_API_URL) — the sandbox's own loopback. */
+    baseUrl: string;
+    deliveriesPath: string;
+    /** Whether the catch's /health returned OUR service marker within the readiness budget. Callers MUST
+     *  treat `ready === false` as fatal (do not inject baseUrl into a dead catch — the app's sends would
+     *  silently fail with nothing captured). */
+    ready: boolean;
+}
+/** A raw send the in-sandbox catch captured (host-side parsing happens in routeCapturedSends). */
+export interface RawCapturedSend {
+    path: string;
+    body: string;
+    t: number;
+}
+/**
+ * Write + launch the in-sandbox catch (detached), then probe it ready. Call AFTER the subject sandbox
+ * is created and BEFORE the subject app's serve.start, so the base URL resolves at the app's boot.
+ */
+export declare function deployCommsCatch(desktop: E2BDesktopSandbox, options?: DeployCommsCatchOptions): Promise<DeployedCommsCatch>;
+/**
+ * Drain new captured sends from the in-sandbox NDJSON since `cursor` (a line count). Returns the fresh
+ * sends and the new cursor. Cheap `cat` over commands.run; NDJSON is small for a run.
+ */
+export declare function drainCommsCatch(desktop: E2BDesktopSandbox, deployed: Pick<DeployedCommsCatch, "deliveriesPath">, cursor?: number, requestTimeoutMs?: number): Promise<{
+    sends: RawCapturedSend[];
+    cursor: number;
+}>;
+/**
+ * Parse drained raw sends with the host profiles and route them into the CommsChannel (the host-side
+ * FauxInbox). Returns the number of inbox deliveries made. Same profiles as the host catch, so the
+ * in-sandbox and in-process routes normalize identically.
+ */
+export declare function routeCapturedSends(sends: RawCapturedSend[], channel: CommsChannel, profiles?: EmailSendProfile[]): Promise<number>;

package/dist/comms-sandbox-catch.js

@@ -0,0 +1,157 @@
+// Deploy the vendor-neutral email catch INSIDE the subject E2B sandbox and bridge captured sends back
+// to the host bus (#297 config-block core). The host `startEmailCatchServer` binds the HOST's loopback,
+// which a sandboxed app cannot reach — `127.0.0.1:PORT` from the app is the SANDBOX's loopback. So the
+// listener must live in the sandbox: we write a tiny self-contained capture server (no deps, no host
+// import) into the sandbox, launch it detached (the same substrate that serves the subject app), and
+// each poll `cat` its append-only NDJSON of captured sends back to the host, where the real profiles
+// parse them and route into the CommsChannel. A FIXED loopback port is chosen up front so the app's
+// injected base-URL env (`http://127.0.0.1:<port>`) is known before the sandbox is created.
+import { DEFAULT_EMAIL_PROFILES } from "./comms-email-catch.js";
+import { startDetachedProcess } from "./e2b-detached.js";
+/** The default in-sandbox loopback port for the catch. Fixed (not ephemeral) so the injected base-URL
+ *  env is known before `createDesktopSandbox`. 8025 is the conventional local-mail-UI port and is
+ *  unlikely to collide with a subject app; override via config if it does. */
+export const DEFAULT_SANDBOX_CATCH_PORT = 8025;
+const DEFAULT_CATCH_DIR = "/tmp/humanish-comms";
+/** Single-quote for safe shell interpolation. */
+function shq(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+/**
+ * The self-contained in-sandbox capture server (a plain node ESM string — runs on the sandbox's own
+ * node, imports nothing from humanish). It is DELIBERATELY dumb: it records each POST verbatim as an
+ * NDJSON line `{t, path, body}` and returns a plausible provider success — all normalization/profile
+ * parsing happens host-side on the drained lines, so the typed, tested profiles stay in one place.
+ * argv: <port> <deliveriesFile>.
+ */
+export const SANDBOX_CATCH_SCRIPT = [
+    'import { createServer } from "node:http";',
+    'import { appendFileSync, mkdirSync } from "node:fs";',
+    'import { dirname } from "node:path";',
+    'const port = Number(process.argv[2] || 8025);',
+    'const outFile = process.argv[3] || "/tmp/humanish-comms/deliveries.ndjson";',
+    'try { mkdirSync(dirname(outFile), { recursive: true }); } catch {}',
+    'const MAX = 5 * 1024 * 1024;',
+    'createServer((req, res) => {',
+    '  const path = (req.url || "/").split("?")[0];',
+    '  if (req.method === "GET" && (path === "/" || path === "/health")) { res.writeHead(200, { "content-type": "application/json" }); res.end(JSON.stringify({ ok: true, service: "humanish-comms-catch" })); return; }',
+    '  if (req.method !== "POST") { res.writeHead(404, { "content-type": "application/json" }); res.end(JSON.stringify({ error: "not found" })); return; }',
+    '  let size = 0; const chunks = [];',
+    '  req.on("data", (c) => { size += c.length; if (size > MAX) { req.destroy(); } else { chunks.push(c); } });',
+    '  req.on("end", () => {',
+    '    const body = Buffer.concat(chunks).toString("utf8");',
+    '    try { appendFileSync(outFile, JSON.stringify({ t: Date.now(), path, body }) + "\\n"); } catch {}',
+    '    const id = "humanish-catch-" + Date.now().toString(36) + Math.random().toString(36).slice(2, 8);',
+    '    if (path === "/v3/mail/send") { res.writeHead(202, { "x-message-id": id }); res.end(); }',
+    '    else if (path.endsWith("/batch")) { res.writeHead(200, { "content-type": "application/json" }); res.end(JSON.stringify({ data: [{ id }] })); }',
+    '    else { res.writeHead(200, { "content-type": "application/json" }); res.end(JSON.stringify({ id })); }',
+    '  });',
+    '  req.on("error", () => { try { res.writeHead(400); res.end(); } catch {} });',
+    '}).listen(port, "127.0.0.1");'
+].join("\n");
+/** Readiness probe that asserts OUR service marker in the /health body (not merely any 2xx) — so a
+ *  process squatting on the fixed port cannot produce a false "ready" while the app's sends bypass us. */
+async function catchHealthy(desktop, port, options) {
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const deadline = now() + options.timeoutMs;
+    for (;;) {
+        const result = await desktop.commands
+            .run(`curl -s --max-time 5 http://127.0.0.1:${port}/health 2>/dev/null || true`, { requestTimeoutMs: options.requestTimeoutMs })
+            .catch(() => ({ stdout: "" }));
+        if ((result.stdout ?? "").includes("humanish-comms-catch"))
+            return true;
+        if (now() >= deadline)
+            return false;
+        await sleep(1000);
+    }
+}
+/**
+ * Write + launch the in-sandbox catch (detached), then probe it ready. Call AFTER the subject sandbox
+ * is created and BEFORE the subject app's serve.start, so the base URL resolves at the app's boot.
+ */
+export async function deployCommsCatch(desktop, options = {}) {
+    // Validate the port to an integer before it reaches the shell command (defense-in-depth: a future
+    // caller might cast a config value; the value is typed `number` but this makes injection impossible).
+    const port = Math.trunc(Number(options.port ?? DEFAULT_SANDBOX_CATCH_PORT));
+    if (!Number.isInteger(port) || port <= 0 || port > 65_535) {
+        throw new Error(`deployCommsCatch: invalid port ${JSON.stringify(options.port)}`);
+    }
+    const dir = options.dir ?? DEFAULT_CATCH_DIR;
+    const name = options.name ?? "comms-catch";
+    const requestTimeoutMs = options.requestTimeoutMs ?? 30_000;
+    const scriptPath = `${dir}/catch.mjs`;
+    const deliveriesPath = `${dir}/deliveries.ndjson`;
+    await desktop.commands.run(`mkdir -p ${shq(dir)}`, { requestTimeoutMs });
+    await desktop.files.write(scriptPath, SANDBOX_CATCH_SCRIPT);
+    await startDetachedProcess(desktop, {
+        name,
+        command: `node ${shq(scriptPath)} ${port} ${shq(deliveriesPath)}`,
+        requestTimeoutMs
+    });
+    const ready = await catchHealthy(desktop, port, {
+        timeoutMs: options.readyTimeoutMs ?? 15_000,
+        requestTimeoutMs,
+        ...(options.timers ?? {})
+    });
+    return { port, baseUrl: `http://127.0.0.1:${port}`, deliveriesPath, ready };
+}
+/**
+ * Drain new captured sends from the in-sandbox NDJSON since `cursor` (a line count). Returns the fresh
+ * sends and the new cursor. Cheap `cat` over commands.run; NDJSON is small for a run.
+ */
+export async function drainCommsCatch(desktop, deployed, cursor = 0, requestTimeoutMs = 30_000) {
+    const result = await desktop.commands.run(`cat ${shq(deployed.deliveriesPath)} 2>/dev/null || true`, { requestTimeoutMs });
+    const stdout = result.stdout ?? "";
+    let lines = stdout.split("\n").filter((line) => line.trim().length > 0);
+    // If the file doesn't end in a newline, the last line may be a PARTIAL append (the host `cat` raced
+    // an in-sandbox append of a large body). Drop it and don't advance the cursor past it — it re-reads
+    // complete on the next poll, so a captured send is never lost to the race (the script only ever emits
+    // valid JSON, so an incomplete line is the only cause of a parse miss).
+    if (!stdout.endsWith("\n") && lines.length > 0)
+        lines = lines.slice(0, -1);
+    const sends = [];
+    for (const line of lines.slice(cursor)) {
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed.path === "string" && typeof parsed.body === "string") {
+                sends.push({ path: parsed.path, body: parsed.body, t: typeof parsed.t === "number" ? parsed.t : 0 });
+            }
+        }
+        catch {
+            // skip a malformed line
+        }
+    }
+    return { sends, cursor: lines.length };
+}
+/**
+ * Parse drained raw sends with the host profiles and route them into the CommsChannel (the host-side
+ * FauxInbox). Returns the number of inbox deliveries made. Same profiles as the host catch, so the
+ * in-sandbox and in-process routes normalize identically.
+ */
+export async function routeCapturedSends(sends, channel, profiles = DEFAULT_EMAIL_PROFILES) {
+    let delivered = 0;
+    for (const send of sends) {
+        let parsed;
+        try {
+            parsed = JSON.parse(send.body.length > 0 ? send.body : "{}");
+        }
+        catch {
+            continue;
+        }
+        const profile = profiles.find((candidate) => candidate.sendPaths.includes(send.path)) ?? profiles[0];
+        if (profile === undefined)
+            continue;
+        for (const normalized of profile.parse(send.path, parsed)) {
+            const messages = await channel.deliverRaw({
+                from: normalized.from,
+                to: normalized.to,
+                ...(normalized.subject === undefined ? {} : { subject: normalized.subject }),
+                body: normalized.body
+            });
+            delivered += messages.length;
+        }
+    }
+    return delivered;
+}
+//# sourceMappingURL=comms-sandbox-catch.js.map