humanish 0.104.3 → 0.106.0

package/dist/comms/receiving.js

@@ -0,0 +1,508 @@
+/** Run-scoped real-email receiving. Resource authority and message content stay on the host. */
+import { CommsLeaseStore, validReceivingIdentity, validReceivingLease, } from "./lease-store.js";
+import { CommsReceivingError, errorCode, releaseOwned, REQUEST_MS, withDeadline, } from "./receiving-common.js";
+import { MAX_RECEIVING_MESSAGES } from "./receiving-render.js";
+import { isReceivingProviderId } from "./providers.js";
+import { COMMS_RECEIVING_SCHEMA, } from "./receiving-types.js";
+import { capturedInlineImages } from "./images.js";
+const POLL_MS = 3_000;
+const SURFACE_MS = 8_000;
+const EVIDENCE_MS = 5_000;
+const MAX_CONTENT_BYTES = 16 * 1024 * 1024;
+function addCode(codes, code) {
+    if (!codes.includes(code) && codes.length < 64)
+        codes.push(code);
+}
+function providerCodes(codes, values, safe) {
+    for (const value of values)
+        addCode(codes, safe.has(value) ? value : "provider_coverage_limited");
+}
+function isoNow() {
+    return new Date().toISOString();
+}
+function providerTime(value) {
+    if (!value || !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{1,9})?(?:Z|[+-]\d\d:\d\d)$/.test(value))
+        return undefined;
+    const time = Date.parse(value);
+    return Number.isFinite(time) ? new Date(time).toISOString() : undefined;
+}
+function contentBytes(message) {
+    return (Buffer.byteLength(message.from) +
+        Buffer.byteLength(message.text) +
+        Buffer.byteLength(message.html ?? "") +
+        Buffer.byteLength(message.subject ?? "") +
+        message.inlineImages.reduce((sum, image) => sum + Buffer.byteLength(JSON.stringify(image)), 0));
+}
+/** Provider IDs deduplicate observations, not successful hydration. A later fetch may restore missing content. */
+function reconcileMessage(previous, next) {
+    const prefer = (oldValue, newValue) => {
+        if (!newValue)
+            return oldValue;
+        // Received mail is immutable: a retry may fill/truncate a representation, not revise its meaning.
+        return !oldValue || newValue.length > oldValue.length ? newValue : oldValue;
+    };
+    const images = new Map(previous.inlineImages.map((image) => [image.contentId, image]));
+    for (const image of next.inlineImages)
+        if (!images.has(image.contentId))
+            images.set(image.contentId, image);
+    const html = prefer(previous.html, next.html);
+    const subject = previous.subject || next.subject;
+    const timestamp = previous.providerTimestamp ?? next.providerTimestamp;
+    return {
+        channel: "email",
+        id: previous.id,
+        from: previous.from || next.from,
+        text: prefer(previous.text, next.text) ?? "",
+        ...(html === undefined ? {} : { html }),
+        ...(subject === undefined ? {} : { subject }),
+        ...(timestamp === undefined ? {} : { providerTimestamp: timestamp }),
+        inlineImages: capturedInlineImages([...images.values()]),
+        limitations: next.limitations,
+    };
+}
+function visibleContent(message) {
+    return JSON.stringify([
+        message.from,
+        message.subject,
+        message.text,
+        message.html,
+        message.inlineImages,
+    ]);
+}
+class ReceivingRun {
+    options;
+    store;
+    participants = new Map();
+    evidence;
+    evidenceQueue = Promise.resolve();
+    pendingEvidence;
+    finishPromise;
+    onAbort = () => {
+        void this.finish().catch(() => undefined);
+    };
+    constructor(options, store) {
+        this.options = options;
+        this.store = store;
+        this.evidence = {
+            schema: COMMS_RECEIVING_SCHEMA,
+            channel: "email",
+            provider: options.adapter.provider,
+            publication: "restricted-real-communications",
+            state: "acquiring",
+            browserConfinement: "mail-surface-only",
+            participants: [],
+            limitations: [
+                "delivery_after_observation_end_unknown",
+                "participant_read_not_inferred_from_publication",
+            ],
+        };
+        for (const record of store.snapshot().leases) {
+            const evidence = {
+                participantId: record.participantId,
+                leaseId: record.leaseId,
+                acquisition: "pending",
+                cleanup: "pending",
+                observed: 0,
+                published: 0,
+                linkCount: 0,
+                codeCount: 0,
+                blockedAssetCount: 0,
+                blockedLinkCount: 0,
+                messages: [],
+                limitations: [],
+            };
+            this.evidence.participants.push(evidence);
+            this.participants.set(record.participantId, {
+                record,
+                evidence,
+                messages: new Map(),
+                contentBytes: 0,
+                revision: 0,
+                allowedOrigins: [],
+                finished: false,
+            });
+        }
+    }
+    snapshot() {
+        return structuredClone(this.evidence);
+    }
+    participant(id) {
+        const participant = this.participants.get(id);
+        if (!participant)
+            throw new CommsReceivingError("comms_participant_unknown");
+        return participant;
+    }
+    async persist() {
+        const operation = this.evidenceQueue.then(async () => {
+            // A timed-out callback may still complete. Never let a later write race its older snapshot.
+            if (this.pendingEvidence)
+                return false;
+            try {
+                const pending = Promise.resolve().then(() => this.options.writeEvidence(this.snapshot()));
+                this.pendingEvidence = pending;
+                void pending.then(() => {
+                    if (this.pendingEvidence === pending)
+                        delete this.pendingEvidence;
+                }, () => {
+                    if (this.pendingEvidence === pending)
+                        delete this.pendingEvidence;
+                });
+                await withDeadline(() => pending, EVIDENCE_MS);
+                return true;
+            }
+            catch {
+                addCode(this.evidence.limitations, "evidence_write_failed");
+                return false;
+            }
+        });
+        this.evidenceQueue = operation.catch(() => undefined);
+        return operation;
+    }
+    async acquire() {
+        try {
+            // Establish the publication restriction before any provider resource or participant content.
+            if (!(await this.persist()))
+                throw new CommsReceivingError("evidence_write_failed");
+            for (const participant of this.participants.values()) {
+                if (this.options.signal?.aborted)
+                    throw new CommsReceivingError("comms_cancelled");
+                await this.store.setState(participant.record.participantId, "intent");
+                participant.record.state = "intent";
+                const lease = await withDeadline((context) => this.options.adapter.acquire(participant.record.clientId, context), REQUEST_MS, this.options.signal);
+                if (!validReceivingLease(lease, participant.record.clientId))
+                    throw new CommsReceivingError("comms_ownership_mismatch");
+                // Never release an unexpected duplicate under a second client's authority.
+                if ([...this.participants.values()].some((other) => other !== participant && other.lease?.resourceId === lease.resourceId)) {
+                    throw new CommsReceivingError("comms_ownership_mismatch");
+                }
+                participant.lease = structuredClone(lease);
+                await this.store.bind(participant.record.participantId, lease);
+                participant.record.state = "active";
+                this.options.registerSecrets([lease.address]);
+                if ([...this.participants.values()].some((other) => other !== participant &&
+                    other.lease?.address.toLowerCase() === lease.address.toLowerCase())) {
+                    throw new CommsReceivingError("comms_duplicate_address");
+                }
+                participant.evidence.acquisition = "active";
+                if (!(await this.persist()))
+                    throw new CommsReceivingError("evidence_write_failed");
+            }
+            if (this.options.signal?.aborted)
+                throw new CommsReceivingError("comms_cancelled");
+            this.evidence.state = "running";
+            if (!(await this.persist()))
+                throw new CommsReceivingError("evidence_write_failed");
+            this.options.signal?.addEventListener("abort", this.onAbort, { once: true });
+        }
+        catch (error) {
+            const code = errorCode(error, "comms_acquisition_failed", this.options.adapter.codes);
+            addCode(this.evidence.limitations, code);
+            for (const participant of this.participants.values()) {
+                if (participant.evidence.acquisition === "pending") {
+                    participant.evidence.acquisition = "failed";
+                    addCode(participant.evidence.limitations, code);
+                }
+            }
+            await this.finish();
+            throw new CommsReceivingError(code);
+        }
+    }
+    address(participantId) {
+        const participant = this.participant(participantId);
+        if (this.evidence.state !== "running" ||
+            !participant.lease ||
+            participant.finished ||
+            participant.finishing) {
+            throw new CommsReceivingError("comms_participant_inactive");
+        }
+        return participant.lease.address;
+    }
+    remember(participant, message) {
+        if (!message.providerMessageId)
+            return;
+        const previous = participant.messages.get(message.providerMessageId);
+        providerCodes(participant.evidence.limitations, message.limitations, this.options.adapter.codes);
+        const timestamp = providerTime(message.providerTimestamp);
+        if (message.providerTimestamp && !timestamp)
+            addCode(participant.evidence.limitations, "provider_timestamp_invalid");
+        const id = previous?.id ?? `message-${String(participant.messages.size + 1).padStart(6, "0")}`;
+        const { providerMessageId: _privateId, ...content } = message;
+        const current = previous ? reconcileMessage(previous, { ...content, id }) : { ...content, id };
+        const size = contentBytes(current);
+        const previousSize = previous ? contentBytes(previous) : 0;
+        if ((!previous && participant.messages.size >= MAX_RECEIVING_MESSAGES) ||
+            participant.contentBytes - previousSize + size > MAX_CONTENT_BYTES) {
+            addCode(participant.evidence.limitations, "observation_memory_limit");
+            return;
+        }
+        participant.messages.set(message.providerMessageId, structuredClone(current));
+        participant.contentBytes += size - previousSize;
+        const contentChanged = !previous || visibleContent(previous) !== visibleContent(current);
+        if (contentChanged)
+            participant.revision += 1;
+        if (previous) {
+            const observation = participant.evidence.messages.find((item) => item.id === id);
+            if (timestamp && observation.providerTimestamp === undefined)
+                observation.providerTimestamp = timestamp;
+            if (observation.publishedAt && contentChanged) {
+                // publishedAt is the first publication, not a claim that a subsequently enriched version was seen.
+                addCode(participant.evidence.limitations, "message_content_updated_after_publication");
+            }
+        }
+        else
+            participant.evidence.messages.push({
+                id,
+                firstObservedAt: isoNow(),
+                ...(timestamp ? { providerTimestamp: timestamp } : {}),
+            });
+        participant.evidence.observed = participant.messages.size;
+    }
+    async publish(participant) {
+        if (!participant.surface || !participant.lease)
+            return false;
+        // Polling reconciles provider coverage, but an unchanged visible snapshot needs no desktop I/O.
+        // Advance only after acknowledged publication so failures and later hydration remain retryable.
+        if (participant.publishedRevision === participant.revision)
+            return true;
+        if (participant.pendingPublication) {
+            addCode(participant.evidence.limitations, "surface_publication_pending");
+            return false;
+        }
+        try {
+            const revision = participant.revision;
+            const rendered = this.options.render({
+                address: participant.lease.address,
+                messages: [...participant.messages.values()],
+                allowedOrigins: participant.allowedOrigins,
+                ...(participant.originMap ? { originMap: participant.originMap } : {}),
+            });
+            this.options.registerSecrets(rendered.secrets);
+            participant.evidence.linkCount = rendered.linkCount;
+            participant.evidence.codeCount = rendered.codeCount;
+            participant.evidence.blockedAssetCount = rendered.blockedAssetCount;
+            participant.evidence.blockedLinkCount = rendered.blockedLinkCount;
+            if (rendered.blockedAssetCount > 0)
+                addCode(participant.evidence.limitations, "remote_or_unsafe_assets_blocked");
+            if (rendered.blockedLinkCount > 0)
+                addCode(participant.evidence.limitations, "out_of_scope_links_blocked");
+            const pending = Promise.resolve().then(() => participant.surface.publish(rendered.files));
+            participant.pendingPublication = pending;
+            void pending.then(() => {
+                if (participant.pendingPublication === pending)
+                    delete participant.pendingPublication;
+            }, () => {
+                if (participant.pendingPublication === pending)
+                    delete participant.pendingPublication;
+            });
+            await withDeadline(() => pending, SURFACE_MS);
+            participant.publishedRevision = revision;
+            const publishedAt = isoNow();
+            for (const message of participant.evidence.messages)
+                message.publishedAt ??= publishedAt;
+            participant.evidence.published = participant.evidence.messages.filter((message) => message.publishedAt !== undefined).length;
+            return true;
+        }
+        catch {
+            addCode(participant.evidence.limitations, "surface_publication_failed");
+            return false;
+        }
+    }
+    async poll(participant, final = false) {
+        if (!participant.lease || (!final && (participant.finishing || participant.finished)))
+            return;
+        const controller = new AbortController();
+        participant.readAbort = controller;
+        try {
+            await this.store.assertOwnership();
+            const batch = await withDeadline((context) => this.options.adapter.read(structuredClone(participant.lease), context), REQUEST_MS, controller.signal);
+            for (const message of batch.messages)
+                this.remember(participant, message);
+            providerCodes(participant.evidence.limitations, batch.limitations, this.options.adapter.codes);
+            if (!batch.complete)
+                addCode(participant.evidence.limitations, "provider_coverage_limited");
+        }
+        catch (error) {
+            // A final bounded reconciliation follows an intentional in-flight cancellation.
+            if (!(participant.finishing && !final && controller.signal.aborted))
+                addCode(participant.evidence.limitations, errorCode(error, "mail_poll_failed", this.options.adapter.codes));
+        }
+        finally {
+            delete participant.readAbort;
+        }
+        // Retained messages are retried even if this provider read failed or no longer lists them.
+        await this.persist();
+        if (participant.surface)
+            await this.publish(participant);
+        await this.persist();
+    }
+    schedule(participant) {
+        if (participant.finished || participant.finishing || this.finishPromise)
+            return;
+        participant.timer = setTimeout(() => {
+            participant.task = this.poll(participant).finally(() => {
+                delete participant.task;
+                this.schedule(participant);
+            });
+        }, POLL_MS);
+        participant.timer.unref();
+    }
+    async attach(participantId, options) {
+        const participant = this.participant(participantId);
+        if (this.evidence.state !== "running" ||
+            participant.surface ||
+            participant.finishing ||
+            participant.finished) {
+            try {
+                await withDeadline(() => options.surface.stop(), SURFACE_MS);
+            }
+            catch {
+                /* The caller still owns the desktop. */
+            }
+            throw new CommsReceivingError("comms_participant_inactive");
+        }
+        participant.surface = options.surface;
+        participant.allowedOrigins = [...options.allowedOrigins];
+        if (options.originMap)
+            participant.originMap = structuredClone(options.originMap);
+        participant.task = (async () => {
+            if (!(await this.publish(participant)))
+                throw new CommsReceivingError("surface_publication_failed");
+            await this.persist();
+            await this.poll(participant);
+        })();
+        try {
+            await participant.task;
+        }
+        finally {
+            delete participant.task;
+            this.schedule(participant);
+        }
+    }
+    async release(participant) {
+        if (!participant.lease) {
+            if (participant.record.state === "planned") {
+                await this.store.setState(participant.record.participantId, "not-created");
+                participant.evidence.cleanup = "absent";
+            }
+            else {
+                await this.store.setState(participant.record.participantId, "unresolved");
+                participant.evidence.cleanup = "unresolved";
+                addCode(participant.evidence.limitations, "acquisition_outcome_unknown");
+            }
+            return;
+        }
+        await this.store.assertOwnership();
+        if (!this.store
+            .snapshot()
+            .leases.find((item) => item.participantId === participant.record.participantId)?.lease) {
+            await this.store.bind(participant.record.participantId, participant.lease);
+        }
+        await this.store.setState(participant.record.participantId, "closing");
+        const status = await releaseOwned(this.options.adapter, participant.lease, this.store);
+        participant.evidence.cleanup = status;
+        await this.store.setState(participant.record.participantId, status);
+        if (status === "deleting")
+            addCode(participant.evidence.limitations, "cleanup_absence_unconfirmed");
+    }
+    finishParticipant(participantId) {
+        const participant = this.participant(participantId);
+        if (participant.finishing)
+            return participant.finishing;
+        participant.finishing = Promise.resolve().then(async () => {
+            if (participant.timer)
+                clearTimeout(participant.timer);
+            participant.readAbort?.abort();
+            try {
+                await participant.task;
+            }
+            catch {
+                /* Final reconciliation retries publication. */
+            }
+            try {
+                await this.store.setState(participantId, participant.lease ? "closing" : participant.record.state);
+            }
+            catch {
+                addCode(participant.evidence.limitations, "comms_authority_unavailable");
+            }
+            if (participant.lease && this.evidence.state === "running")
+                await this.poll(participant, true);
+            if (!participant.surface && participant.lease)
+                addCode(participant.evidence.limitations, "participant_surface_not_attached");
+            const evidenceSaved = await this.persist();
+            if (participant.surface) {
+                try {
+                    await withDeadline(() => participant.surface.stop(), SURFACE_MS);
+                }
+                catch {
+                    addCode(participant.evidence.limitations, "surface_stop_unconfirmed");
+                }
+            }
+            try {
+                if (!evidenceSaved && participant.lease) {
+                    // Preserve the only retrievable copy when observation evidence could not be committed.
+                    participant.evidence.cleanup = "unresolved";
+                    addCode(participant.evidence.limitations, "cleanup_retained_for_evidence");
+                    await this.store.setState(participantId, "unresolved");
+                }
+                else
+                    await this.release(participant);
+            }
+            catch (error) {
+                participant.evidence.cleanup = "unresolved";
+                addCode(participant.evidence.limitations, errorCode(error, "cleanup_failed", this.options.adapter.codes));
+                try {
+                    await this.store.setState(participantId, "unresolved");
+                }
+                catch {
+                    addCode(participant.evidence.limitations, "comms_authority_unavailable");
+                }
+            }
+            participant.finished = true;
+            participant.messages.clear();
+            await this.persist();
+        });
+        return participant.finishing;
+    }
+    finish() {
+        this.finishPromise ??= (async () => {
+            this.options.signal?.removeEventListener("abort", this.onAbort);
+            await Promise.all([...this.participants.keys()].map((id) => this.finishParticipant(id)));
+            this.evidence.state = "finished";
+            await this.persist();
+            try {
+                await this.store.close();
+            }
+            catch {
+                addCode(this.evidence.limitations, "comms_authority_unavailable");
+                await this.persist();
+            }
+            return this.snapshot();
+        })();
+        return this.finishPromise;
+    }
+}
+export async function startCommsReceiving(options) {
+    try {
+        if (!isReceivingProviderId(options.adapter.provider))
+            throw new CommsReceivingError("comms_provider_unsupported");
+        // The adapter rejects a credential that cannot acquire fresh inboxes.
+        const identity = await withDeadline((context) => options.adapter.authenticate(context), REQUEST_MS, options.signal);
+        if (!validReceivingIdentity(identity) || identity.provider !== options.adapter.provider)
+            throw new CommsReceivingError("comms_identity_invalid");
+        const store = await CommsLeaseStore.create({
+            cwd: options.cwd,
+            runId: options.runId,
+            connectionName: options.connectionName,
+            apiKeyEnv: options.apiKeyEnv,
+            identity,
+            participants: options.participants,
+            ...(options.stateDir ? { stateDir: options.stateDir } : {}),
+        });
+        const run = new ReceivingRun(options, store);
+        await run.acquire();
+        return run;
+    }
+    catch (error) {
+        throw new CommsReceivingError(errorCode(error, "comms_start_failed", options.adapter.codes));
+    }
+}

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

@@ -0,0 +1,16 @@
+/**
+ * The self-contained in-sandbox capture server — a plain **python3** script (stdlib only), because the
+ * stock E2B desktop template ships python3 but NOT node, and the co-located catcher must run in a
+ * runtime the sandbox guarantees (the precedented choice: LocalStack is a python catcher the app points
+ * at; you pick the runtime the environment has). It runs on the sandbox's own python3, imports nothing
+ * from humanish. 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. It also serves the host-rendered inbox
+ * surface statically at /inbox + /api/inbox (with a script-forbidding CSP). argv: <port> <deliveriesFile>
+ * <servedDir> [inboxPort]. The capture listener binds 127.0.0.1 (loopback) — the app under test reaches
+ * it in-sandbox, nothing on the internet can inject a fake send. When an [inboxPort] is given (the
+ * shared-world route, where the persona lives in a DIFFERENT sandbox), it ALSO starts a READ-ONLY inbox
+ * listener on 0.0.0.0:<inboxPort> so getHost can proxy the persona's inbox reads to it; that listener
+ * serves GET only (POST → 405). The CUA same-sandbox route omits it and stays loopback-only.
+ */
+export declare const SANDBOX_CATCH_SCRIPT = "import json\nimport os\nimport random\nimport sys\nimport threading\nimport time\nfrom http.server import BaseHTTPRequestHandler, ThreadingHTTPServer\nfrom urllib.parse import unquote\n\nPORT = int(sys.argv[1]) if len(sys.argv) > 1 else 8025\nOUT_FILE = sys.argv[2] if len(sys.argv) > 2 else \"/tmp/humanish-comms/deliveries.ndjson\"\nSERVED_DIR = sys.argv[3] if len(sys.argv) > 3 else (os.path.dirname(OUT_FILE) + \"/surface\")\nINBOX_PORT = int(sys.argv[4]) if len(sys.argv) > 4 else 0\n# Optional shared token guarding GET /deliveries (the drain read). Empty = unguarded, which is the\n# in-sandbox default: the capture listener binds loopback there, so nothing external can reach it.\n# An ADOPTER-HOSTED catch is reachable over the network, so it should pass one.\nDELIVERIES_TOKEN = sys.argv[5] if len(sys.argv) > 5 else \"\"\n# Optional loopback SMTP listener. Most self-hostable apps send mail over SMTP rather than an HTTP\n# provider API, so without this the catch only works for the minority that speak HTTP.\nSMTP_PORT = int(sys.argv[6]) if len(sys.argv) > 6 else 0\ntry:\n    os.makedirs(os.path.dirname(OUT_FILE), exist_ok=True)\nexcept Exception:\n    pass\nMAX_BODY = 5 * 1024 * 1024\nCSP = \"default-src 'self'; script-src 'none'; object-src 'none'; base-uri 'none'; frame-src 'none'; img-src * data:; style-src 'unsafe-inline'; font-src * data:\"\n\n\ndef message_id():\n    return \"humanish-catch-\" + format(int(time.time() * 1000), \"x\") + format(random.randrange(16 ** 8), \"08x\")\n\n\nclass BaseHandler(BaseHTTPRequestHandler):\n    def log_message(self, *args):\n        return\n\n    def _json(self, status, obj, extra_headers=None):\n        payload = json.dumps(obj).encode(\"utf-8\")\n        self.send_response(status)\n        self.send_header(\"content-type\", \"application/json; charset=utf-8\")\n        for key, value in (extra_headers or {}).items():\n            self.send_header(key, value)\n        self.end_headers()\n        self.wfile.write(payload)\n\n    def do_GET(self):\n        path = self.path.split(\"?\")[0]\n        if path == \"/health\":\n            self._json(200, {\"ok\": True, \"service\": \"humanish-comms-catch\", \"capabilities\": [\"recipient-inbox-v1\", \"captured-inline-images-v1\"]})\n            return\n        if path == \"/\":\n            # A persona that trims the /inbox path lands here. It used to get the health JSON and read\n            # it as \"wrong place / broken\", so send it where it meant to go. /health keeps the machine\n            # marker: both readiness probes assert on /health specifically, never on /.\n            self.send_response(200)\n            self.send_header(\"content-type\", \"text/html; charset=utf-8\")\n            self.send_header(\"content-security-policy\", CSP)\n            self.end_headers()\n            self.wfile.write(b\"<!doctype html><title>Mailbox</title><p><a href='/inbox'>Open the inbox</a></p>\")\n            return\n        if path == \"/deliveries\":\n            # The drain read. In-sandbox humanish reads the NDJSON file directly; an adopter-hosted\n            # catch is on another machine, so the same bytes are served over HTTP. Capture bodies\n            # can contain a verification link, so this is the one route worth guarding.\n            if DELIVERIES_TOKEN:\n                supplied = self.headers.get(\"authorization\", \"\")\n                if supplied != (\"Bearer \" + DELIVERIES_TOKEN):\n                    self._json(401, {\"error\": \"unauthorized\"})\n                    return\n            try:\n                with open(OUT_FILE, \"rb\") as handle:\n                    body = handle.read()\n            except Exception:\n                body = b\"\"\n            self.send_response(200)\n            self.send_header(\"content-type\", \"application/x-ndjson; charset=utf-8\")\n            self.send_header(\"cache-control\", \"no-store\")\n            self.end_headers()\n            self.wfile.write(body)\n            return\n        if path == \"/inbox\" or path.startswith(\"/inbox/\") or path == \"/api/inbox\" or path.startswith(\"/api/inbox/\"):\n            rel = unquote(path)\n            if \"..\" in rel or chr(0) in rel:\n                self.send_response(400)\n                self.end_headers()\n                return\n            data = None\n            for candidate in (SERVED_DIR + rel, SERVED_DIR + rel + \"/index\"):\n                try:\n                    with open(candidate, \"rb\") as handle:\n                        data = handle.read()\n                    break\n                except Exception:\n                    data = None\n            if data is None:\n                import re\n                if re.fullmatch(r\"/(api/)?inbox/for/[a-f0-9]{64}/?\", rel):\n                    if rel.startswith(\"/api/\"):\n                        self._json(200, [])\n                        return\n                    self.send_response(200)\n                    self.send_header(\"content-type\", \"text/html; charset=utf-8\")\n                    self.send_header(\"content-security-policy\", CSP)\n                    self.send_header(\"cache-control\", \"no-store\")\n                    self.end_headers()\n                    self.wfile.write(b\"<!doctype html><html lang='en'><meta name='viewport' content='width=device-width,initial-scale=1'><title>Your inbox</title><main><h1>Your inbox</h1><p>No messages yet.</p></main></html>\")\n                    return\n                # A JSON route answers in JSON; only the HTML route answers in HTML.\n                if rel.startswith(\"/api/\"):\n                    self._json(404, {\"error\": \"message not found\"})\n                    return\n                self.send_response(404)\n                self.send_header(\"content-type\", \"text/html; charset=utf-8\")\n                self.send_header(\"content-security-policy\", CSP)\n                self.end_headers()\n                scope = re.match(r\"^/inbox/for/[a-f0-9]{64}(?:/|$)\", rel)\n                back = scope.group(0).rstrip(\"/\") if scope else (None if rel.startswith(\"/inbox/for\") else \"/inbox\")\n                body = \"<!doctype html><title>Mailbox</title><p>message not found</p>\"\n                if back:\n                    body += \"<p><a href='\" + back + \"'>Back to the inbox</a></p>\"\n                self.wfile.write(body.encode(\"utf-8\"))\n                return\n            is_api = rel.startswith(\"/api/\")\n            self.send_response(200)\n            self.send_header(\"cache-control\", \"no-store\")\n            self.send_header(\"referrer-policy\", \"no-referrer\")\n            self.send_header(\"x-content-type-options\", \"nosniff\")\n            self.send_header(\"content-type\", \"application/json; charset=utf-8\" if is_api else \"text/html; charset=utf-8\")\n            if not is_api:\n                self.send_header(\"content-security-policy\", CSP)\n            self.end_headers()\n            self.wfile.write(data)\n            return\n        self._json(404, {\"error\": \"not found\"})\n\n\nclass CaptureHandler(BaseHandler):\n    def do_POST(self):\n        path = self.path.split(\"?\")[0]\n        try:\n            length = int(self.headers.get(\"content-length\") or 0)\n        except Exception:\n            length = 0\n        if length > MAX_BODY:\n            self.send_response(413)\n            self.end_headers()\n            return\n        body = self.rfile.read(length).decode(\"utf-8\", \"replace\") if length > 0 else \"\"\n        try:\n            with open(OUT_FILE, \"a\", encoding=\"utf-8\") as handle:\n                print(json.dumps({\"t\": int(time.time() * 1000), \"path\": path, \"body\": body}), file=handle)\n        except Exception:\n            pass\n        mid = message_id()\n        if path == \"/v3/mail/send\":\n            self.send_response(202)\n            self.send_header(\"x-message-id\", mid)\n            self.end_headers()\n        elif path.endswith(\"/batch\"):\n            self._json(200, {\"data\": [{\"id\": mid}]})\n        else:\n            self._json(200, {\"id\": mid})\n\n\nclass ReadOnlyHandler(BaseHandler):\n    def do_GET(self):\n        if self.path.split(\"?\")[0] == \"/deliveries\":\n            self._json(404, {\"error\": \"not found\"})\n            return\n        super().do_GET()\n\n    def do_POST(self):\n        self.send_response(405)\n        self.end_headers()\n\n\n# Optional read-only inbox listener on 0.0.0.0 (getHost-reachable from a DIFFERENT sandbox on the\n# shared-world route). Serves GET /inbox + /api/inbox + /health only; POST capture stays on the\n# 127.0.0.1 listener so nothing on the internet can inject a fake captured send. Started only when a\n# distinct inbox port is provided (the CUA same-sandbox route omits it and stays loopback-only).\n# Bound here, before any listener serves, so a busy inbox port stops startup like a busy SMTP port.\nif INBOX_PORT and INBOX_PORT != PORT:\n    inbox_server = ThreadingHTTPServer((\"0.0.0.0\", INBOX_PORT), ReadOnlyHandler)\n    threading.Thread(target=inbox_server.serve_forever, daemon=True).start()\n\n\n# Minimal SMTP capture listener. Most self-hostable apps send mail through SMTP, not an HTTP provider\n# API, so an HTTP-only catch could not study them at all. Plain sockets and the stdlib email parser:\n# python 3.12 removed smtpd, and a co-located catcher must not need a dependency.\n#\n# It normalizes each message into the SAME NDJSON line an HTTP send produces, on the /emails path, so\n# every host-side profile, the inbox surface, and the drain work unchanged \u2014 SMTP is a transport\n# here, not a second pipeline.\n# Built from chr() rather than a backslash escape: this script lives inside a TS template\n# literal, where JS would consume the escape before python ever saw it.\nCRLF = chr(13) + chr(10)\n\n\ndef smtp_reply(conn, text):\n    conn.sendall((text + CRLF).encode(\"utf-8\"))\n\n\ndef smtp_session(conn):\n    import email\n    from email import policy\n\n    reader = conn.makefile(\"rb\")\n    smtp_reply(conn, \"220 humanish-comms-catch\")\n    sender = \"\"\n    rcpts = []\n    while True:\n        line = reader.readline()\n        if not line:\n            break\n        command = line.decode(\"utf-8\", \"replace\").strip()\n        upper = command.upper()\n        if upper.startswith(\"EHLO\") or upper.startswith(\"HELO\"):\n            # AUTH is advertised and then accepted unconditionally: the app under test holds\n            # whatever credentials its config carries, and this listener is loopback-only.\n            smtp_reply(conn, \"250-humanish-comms-catch\")\n            smtp_reply(conn, \"250 AUTH PLAIN LOGIN\")\n        elif upper.startswith(\"AUTH\"):\n            smtp_reply(conn, \"235 2.7.0 accepted\")\n        elif upper.startswith(\"MAIL FROM\"):\n            sender = command[command.find(\":\") + 1 :].strip().strip(\"<>\")\n            smtp_reply(conn, \"250 2.1.0 ok\")\n        elif upper.startswith(\"RCPT TO\"):\n            rcpts.append(command[command.find(\":\") + 1 :].strip().strip(\"<>\"))\n            smtp_reply(conn, \"250 2.1.5 ok\")\n        elif upper == \"DATA\":\n            smtp_reply(conn, \"354 end with <CRLF>.<CRLF>\")\n            raw = b\"\"\n            while True:\n                chunk = reader.readline()\n                if not chunk or chunk.strip() == b\".\":\n                    break\n                # Undo dot-stuffing (RFC 5321): a leading '.' on a body line is doubled on the wire.\n                if chunk.startswith(b\"..\"):\n                    chunk = chunk[1:]\n                raw += chunk\n                if len(raw) > MAX_BODY:\n                    break\n            try:\n                parsed = email.message_from_bytes(raw, policy=policy.default)\n                subject = str(parsed.get(\"subject\") or \"\")\n                html_part = parsed.get_body(preferencelist=(\"html\", \"plain\"))\n                body = html_part.get_content() if html_part is not None else \"\"\n                import base64\n                inline_images = []\n                image_bytes = 0\n                for part in parsed.walk():\n                    cid = str(part.get(\"Content-ID\") or \"\").strip().strip(\"<>\")\n                    content_type = part.get_content_type()\n                    if not cid or len(cid) > 256 or content_type not in (\"image/png\", \"image/jpeg\", \"image/gif\", \"image/webp\"):\n                        continue\n                    payload = part.get_payload(decode=True) or b\"\"\n                    if not payload or len(payload) > 1024 * 1024:\n                        continue\n                    image_bytes += len(payload)\n                    if len(inline_images) >= 12 or image_bytes > 2 * 1024 * 1024:\n                        break\n                    inline_images.append({\"contentId\": cid, \"contentType\": content_type, \"base64\": base64.b64encode(payload).decode(\"ascii\")})\n            except Exception:\n                subject = \"\"\n                body = raw.decode(\"utf-8\", \"replace\")\n                inline_images = []\n            record = {\n                \"t\": int(time.time() * 1000),\n                \"path\": \"/emails\",\n                \"body\": json.dumps({\"from\": sender, \"to\": rcpts, \"subject\": subject, \"html\": body, \"inlineImages\": inline_images})\n            }\n            # Same append convention as the HTTP capture path: one line, opened in append mode.\n            with open(OUT_FILE, \"a\", encoding=\"utf-8\") as handle:\n                print(json.dumps(record), file=handle)\n            sender = \"\"\n            rcpts = []\n            smtp_reply(conn, \"250 2.0.0 queued\")\n        elif upper == \"RSET\":\n            sender = \"\"\n            rcpts = []\n            smtp_reply(conn, \"250 2.0.0 ok\")\n        elif upper == \"QUIT\":\n            smtp_reply(conn, \"221 2.0.0 bye\")\n            break\n        elif upper == \"NOOP\":\n            smtp_reply(conn, \"250 2.0.0 ok\")\n        else:\n            smtp_reply(conn, \"250 2.0.0 ok\")\n    try:\n        conn.close()\n    except Exception:\n        pass\n\n\ndef smtp_serve(server):\n    while True:\n        conn, _ = server.accept()\n        threading.Thread(target=smtp_session, args=(conn,), daemon=True).start()\n\n\nif SMTP_PORT:\n    import socket\n\n    # Bind before serving HTTP health: a busy SMTP port must fail startup, not\n    # leave a healthy-looking catch that silently cannot receive the app's mail.\n    smtp_server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n    smtp_server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)\n    smtp_server.bind((\"127.0.0.1\", SMTP_PORT))\n    smtp_server.listen(16)\n    threading.Thread(target=lambda: smtp_serve(smtp_server), daemon=True).start()\n\nThreadingHTTPServer((\"127.0.0.1\", PORT), CaptureHandler).serve_forever()\n";