humanish 0.21.0 → 0.23.0

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

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

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

package/dist/cua-actor-lab.js

@@ -31,6 +31,7 @@ import { CHROMIUM_EVIDENCE_HYGIENE_FLAGS, chromiumEvidenceProfilePreferencesJson
 import { DEFAULT_OPENAI_CU_MODEL } from "./openai-responses-cu.js";
 import { createDesktopSandbox, loadE2BDesktopModule } from "./e2b-desktop-launch.js";
 import { probeUrl, readDetachedLog, runDetachedStep, startDetachedProcess } from "./e2b-detached.js";
+import { DEFAULT_SANDBOX_CATCH_PORT, deployCommsCatch } from "./comms-sandbox-catch.js";
 import { DEFAULT_DEVICE_PRESET, isDevicePresetName, resolveDevicePreset } from "./device-presets.js";
 import { cuaLaneValidationReason, isHttpUrl, isLoopbackUrl, MAX_CUA_LANES, subjectStateInvalidReason } from "./lab-config.js";
 import { mapWithConcurrency } from "./concurrency.js";
@@ -987,6 +988,15 @@ export async function runCuaLane(spec, deps) {
     const { config, appUrl, cloneRoute, localTreeRoute, serve, subjectRepo, subjectEnvNames } = deps;
     const targetUrl = spec.targetUrl ?? appUrl;
     const env = deps.env;
+    // Off-app comms (#297): on an in-sandbox subject route, redirect the app's email-API sends into an
+    // in-sandbox catch (loopback) so its verification mail is CAPTURED, not sent to the internet. Gated
+    // ENTIRELY on config.comms — no comms declared → zero change. The base-URL env is injected at
+    // sandbox-create (below, so the app reads it at boot); the catch is started right after create.
+    const commsEmail = (cloneRoute || localTreeRoute) ? config.comms?.email : undefined;
+    const commsPort = commsEmail ? (commsEmail.port ?? DEFAULT_SANDBOX_CATCH_PORT) : undefined;
+    const commsEnv = commsEmail && commsPort !== undefined
+        ? { [commsEmail.injectEnv]: `http://127.0.0.1:${commsPort}` }
+        : {};
     const warnings = [];
     const screenshots = [];
     const writeScreenshot = makeLaneWriteScreenshot(deps.artifactRoot, spec, screenshots);
@@ -1055,8 +1065,8 @@ export async function runCuaLane(spec, deps) {
             },
             // Env placement per the doctrine: the ACTOR's key never enters the sandbox (the model drives
             // from outside). The SUBJECT's declared env NAMES are provisioned here on the clone route.
-            ...(subjectEnvNames.length > 0
-                ? { envs: Object.fromEntries(subjectEnvNames.map((name) => [name, env[name]])) }
+            ...(subjectEnvNames.length > 0 || Object.keys(commsEnv).length > 0
+                ? { envs: { ...Object.fromEntries(subjectEnvNames.map((name) => [name, env[name]])), ...commsEnv } }
                 : {}),
             resolution: spec.resolution,
             dpi: 96,
@@ -1068,6 +1078,15 @@ export async function runCuaLane(spec, deps) {
         if (deps.hooks.prepareDesktop) {
             await deps.hooks.prepareDesktop(desktop, { laneId: spec.laneId, laneIndex: spec.laneIndex, laneCount: deps.laneCount });
         }
+        // Start the in-sandbox email catch BEFORE the subject serve, so the app's send-API base URL (injected
+        // into its env at create) resolves the moment it boots. A comms-declared lab that can't stand the
+        // catch up is a setup failure (fail closed) rather than silently sending real mail.
+        if (commsEmail && commsPort !== undefined) {
+            const deployedComms = await deployCommsCatch(desktop, { port: commsPort, requestTimeoutMs: deps.requestTimeoutMs });
+            if (!deployedComms.ready) {
+                throw new Error(`comms email catch did not become ready on 127.0.0.1:${commsPort} in the subject sandbox`);
+            }
+        }
         // Per-lane geometry assertion (fail-closed) — the device claim is verified in-sandbox.
         const screenGeometry = await inspectDesktopScreenGeometry({
             desktop,