@inflexa-ai/harness 0.42.1 → 0.43.0

package/dist/sandbox/await-exec.js

@@ -1,417 +0,0 @@
-/**
- * `awaitExec` — awaits a submitted exec's terminal result, forwarding progress
- * events, under one of two transports selected by `options.transport`:
- *
- *   - `poll` (default): {@link awaitExecPoll} loops durable pull steps against
- *     `GET /exec/{execId}?since={cursor}`. The sandbox initiates nothing; the
- *     host asks. Inherently restart-proof — a recovered workflow just resumes
- *     polling from its current identity — so the recovery wedge (#41) does not
- *     apply. A machine that dies mid-exec fast-fails in-loop: sustained
- *     `unavailable` polls escalate to a backend-inspect probe (`liveness.ts`)
- *     and an observably dead machine returns the synthetic-failure result
- *     instead of waiting out the deadline.
- *   - `callback`: {@link awaitExecCallback} is the recv loop below, with the
- *     pull as its recovery backstop.
- *
- * Both run in the workflow body (NOT a step) — `DBOS.recv`, `DBOS.writeStream`,
- * and `DBOS.sleepms` are body-only — and both verify every result against the
- * per-sandbox HMAC, treating a bad/stale signature as a hard cancel.
- *
- * ## Callback mode: the recv loop
- *
- * On each received envelope:
- *
- *   1. If it carries `signature: null` and the payload is a
- *      `synthetic-failure` done-marker, accept it — the watchdog is an
- *      in-process trusted sender. Any other null-signature message
- *      hard-cancels.
- *   2. Otherwise HMAC-verify against the per-sandbox `callbackSecret`.
- *      A bad or stale signature throws `HardCancelError`, which DBOS
- *      treats as a fatal workflow error (no retry).
- *   3. If the verified payload is a done-marker, return its `result`.
- *   4. Otherwise forward the payload via `emit` and continue.
- *
- * `deadline` is an absolute unix-ms timestamp — the durable backstop
- * (typically `step.timeout`). `T` is liveness-agnostic recv pacing: we
- * use `min(5s, remaining)` so the loop returns often enough to honour
- * the deadline.
- *
- * ## Recv is not the only way home
- *
- * The completion callback is a *push* to an address baked into the container at
- * creation. A host that dies mid-exec comes back with a different ingress port,
- * so the push can never land — the sandbox retries into a void while the
- * recovered recv waits for a message that will never arrive. That is the
- * recovery wedge (#41), and it is silent: a `running` row that never advances.
- *
- * So whenever the topic falls quiet, this loop stops waiting and *asks*:
- * `GET /exec/{execId}` on the sandbox itself returns the terminal result,
- * signed fresh at request time. The bytes are the ones the callback would have
- * carried, so the provenance frame survives the recovery path intact and one
- * verification path serves both. Push remains the fast path; pull is what makes
- * the protocol durable rather than merely optimistic.
- *
- * The pull is a DBOS step, not a bare `fetch`: a body-level call whose result
- * varied between replays would desynchronise the recorded function-ID sequence.
- */
-import { DBOS } from "@dbos-inc/dbos-sdk";
-import { ATTR_INFLEXA_ATTEMPT, ATTR_INFLEXA_EXEC_ID, stableSpan, untracedFetch } from "../lib/otel-spans.js";
-import { digestBody } from "./digest.js";
-import { signCallback, verifyCallback } from "./hmac.js";
-import { createEscalationPolicy, probeLiveness, syntheticFailureReason, syntheticFailureResult } from "./liveness.js";
-import { ExecResultSchema, isDoneMarker, isSyntheticFailure, PollResponseSchema, } from "./types.js";
-const DEFAULT_FRESHNESS_SECONDS = 300;
-const MAX_RECV_TIMEOUT_SECONDS = 5;
-/**
- * Two-phase poll cadence. Every poll writes a durable step row (plus a durable
- * sleep), so the interval is a direct multiplier on DBOS system-table growth
- * for the life of the exec: 1.5s for the first 40 attempts (~the exec's first
- * minute) keeps short commands snappy; 10s thereafter keeps an hours-long
- * exec's row growth bounded, at a terminal-latency cost that is noise at that
- * runtime. Attempt-derived, so the schedule is a pure function of the
- * checkpointed step sequence and replays identically.
- */
-const DEFAULT_POLL_INTERVAL_MS = 1_500;
-const DEFAULT_FAST_POLL_ATTEMPTS = 40;
-const DEFAULT_SLOW_POLL_INTERVAL_MS = 10_000;
-/**
- * Silent recv slices to tolerate before pulling. At `MAX_RECV_TIMEOUT_SECONDS`
- * per slice this is ~30s of silence — long enough that a chatty exec never
- * pulls at all, short enough that a recovered workflow converges quickly. Each
- * pull is a durable step, so polling every slice would write a step row every
- * five seconds for the life of a quiet three-hour exec.
- */
-const PULL_AFTER_SILENT_SLICES = 6;
-const PULL_HTTP_TIMEOUT_MS = 10_000;
-/**
- * Fetch the terminal result for `execId` directly from sandbox-server.
- *
- * Never throws: every failure mode collapses to `unavailable`, because a failed
- * pull is not a failed exec. Returning an error here would fail the enclosing
- * DBOS step and take the workflow with it, when the correct response is simply
- * to keep waiting for the push.
- *
- * A terminal response is distinguished by the presence of the signature header
- * — sandbox-server leaves a still-running exec unsigned, having nothing to
- * attest to yet.
- */
-async function pullExecResult(fetchImpl, ref, execId) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), PULL_HTTP_TIMEOUT_MS);
-    try {
-        // The result discloses the command's output, so sandbox-server requires a
-        // signed request. Sign an empty body over the same construction as the
-        // callbacks. `Date.now()` is safe: this runs inside a `DBOS.runStep` whose
-        // cached result is replayed without re-executing the body.
-        const reqTimestamp = Math.floor(Date.now() / 1000);
-        const reqSignature = signCallback({ execId, body: "", timestamp: reqTimestamp, secret: ref.callbackSecret });
-        const res = await untracedFetch(fetchImpl, `http://${ref.host}:${ref.port}/exec/${encodeURIComponent(execId)}`, {
-            method: "GET",
-            headers: {
-                "x-sandbox-signature": reqSignature,
-                "x-sandbox-timestamp": String(reqTimestamp),
-            },
-            signal: controller.signal,
-        });
-        if (!res.ok) {
-            await res.text().catch(() => "");
-            return { kind: "unavailable", detail: `status ${res.status}` };
-        }
-        const signature = res.headers.get("x-sandbox-signature");
-        const raw = await res.text();
-        if (signature === null)
-            return { kind: "running" };
-        const tsHeader = res.headers.get("x-sandbox-timestamp");
-        const parsedTs = tsHeader === null ? null : Number.parseInt(tsHeader, 10);
-        return {
-            kind: "completed",
-            raw,
-            signature,
-            // An unparseable timestamp forwards as null so `verifyCallback`
-            // reports `missing` rather than us guessing a wall-clock.
-            timestamp: parsedTs === null || Number.isNaN(parsedTs) ? null : parsedTs,
-        };
-    }
-    catch (cause) {
-        return { kind: "unavailable", detail: cause instanceof Error ? cause.message : String(cause) };
-    }
-    finally {
-        clearTimeout(timer);
-    }
-}
-export class HardCancelError extends Error {
-    execId;
-    reason;
-    constructor(execId, reason, detail) {
-        super(`awaitExec[${execId}]: hard cancel — ${reason}${detail ? ` (${detail})` : ""}`);
-        this.execId = execId;
-        this.reason = reason;
-    }
-}
-export class ExecTimeoutError extends Error {
-    execId;
-    constructor(execId) {
-        super(`awaitExec[${execId}]: deadline exceeded before done-marker`);
-        this.execId = execId;
-    }
-}
-/**
- * Await a submitted exec's terminal result. Dispatches on transport — `poll`
- * (default) or `callback`. Both verify every result against the per-sandbox
- * HMAC and are bounded by `deadlineMs`.
- */
-export async function awaitExec(ref, execId, emit, deadlineMs, options = {}) {
-    const transport = options.transport ?? "poll";
-    return transport === "callback" ? awaitExecCallback(ref, execId, emit, deadlineMs, options) : awaitExecPoll(ref, execId, emit, deadlineMs, options);
-}
-/**
- * Body of the recv loop (callback transport). Hoisted so it's testable without
- * spinning up DBOS — `recv` is injectable and `now` is overridable.
- */
-export async function awaitExecCallback(ref, execId, emit, deadlineMs, options = {}) {
-    const topic = `exec-event:${execId}`;
-    const callbackSecret = ref.callbackSecret;
-    const now = options.now ?? (() => DBOS.now());
-    const recv = options.recv ?? (async (t, sec) => DBOS.recv(t, sec));
-    const fetchImpl = options.fetch ?? fetch;
-    const runStep = options.runStep ?? ((fn, c) => DBOS.runStep(fn, c));
-    // Both counters are pure functions of the checkpointed recv sequence, so a
-    // replay issues exactly the same pulls in exactly the same order — which is
-    // what keeps the DBOS function-ID sequence stable.
-    let silentSlices = 0;
-    let pullAttempt = 0;
-    /** Ask the sandbox directly. Returns null when the exec has not finished. */
-    const pull = async () => {
-        pullAttempt += 1;
-        const pullStepName = `sandbox.pull-exec-result.${execId}.${pullAttempt}`;
-        const pulled = await runStep(() => {
-            stableSpan(pullStepName, "sandbox.pull-exec-result", { [ATTR_INFLEXA_EXEC_ID]: execId, [ATTR_INFLEXA_ATTEMPT]: pullAttempt });
-            return pullExecResult(fetchImpl, ref, execId);
-        }, { name: pullStepName });
-        if (pulled.kind !== "completed")
-            return null;
-        // Identical treatment to a pushed completion: the bytes were signed by
-        // the same secret, so a forgery is as fatal here as it is there.
-        const verified = verifyCallback({
-            execId,
-            body: Buffer.from(pulled.raw, "utf8"),
-            signature: pulled.signature,
-            timestamp: pulled.timestamp,
-            secret: callbackSecret,
-            nowSec: Math.floor((await now()) / 1000),
-            freshnessSec: DEFAULT_FRESHNESS_SECONDS,
-        });
-        if (!verified.valid) {
-            throw new HardCancelError(execId, verified.reason, "pulled result");
-        }
-        return ExecResultSchema.parse(JSON.parse(pulled.raw));
-    };
-    while (true) {
-        const remainingMs = deadlineMs - (await now());
-        if (remainingMs <= 0) {
-            // A lost callback is not a slow command. Ask once before declaring a
-            // timeout — the result may have been sitting in the sandbox the whole
-            // time, and reporting a timeout would discard a completed analysis.
-            const pulled = await pull();
-            if (pulled !== null)
-                return pulled;
-            throw new ExecTimeoutError(execId);
-        }
-        const timeoutSec = Math.min(MAX_RECV_TIMEOUT_SECONDS, Math.max(1, Math.ceil(remainingMs / 1000)));
-        const msg = await recv(topic, timeoutSec);
-        if (msg === null) {
-            silentSlices += 1;
-            if (silentSlices >= PULL_AFTER_SILENT_SLICES) {
-                silentSlices = 0;
-                const pulled = await pull();
-                if (pulled !== null)
-                    return pulled;
-            }
-            continue;
-        }
-        silentSlices = 0;
-        if (msg.signature === null) {
-            if (isSyntheticFailure(msg.payload)) {
-                return ExecResultSchema.parse(msg.payload.result);
-            }
-            throw new HardCancelError(execId, "synthetic-without-marker");
-        }
-        // Verify against the exact bytes sandbox-server signed. The route
-        // reduces them to `payloadDigest` at ingress — the signature covers that
-        // digest, so it is all verification needs and the message never carries
-        // a second copy of the body. `payloadRaw` is the superseded form, and
-        // the JSON.stringify fallback covers messages persisted before either
-        // field existed — re-serializing diverges from Go's HTML-escaping
-        // encoder, so it is a last resort, not a normal path.
-        const bodyDigest = msg.payloadDigest ?? digestBody(Buffer.from(msg.payloadRaw ?? JSON.stringify(msg.payload), "utf8"));
-        const result = verifyCallback({
-            execId,
-            bodyDigest,
-            signature: msg.signature,
-            timestamp: msg.timestamp,
-            secret: callbackSecret,
-            nowSec: Math.floor((await now()) / 1000),
-            freshnessSec: DEFAULT_FRESHNESS_SECONDS,
-        });
-        if (!result.valid) {
-            throw new HardCancelError(execId, result.reason);
-        }
-        if (isDoneMarker(msg.payload)) {
-            return ExecResultSchema.parse(msg.payload.result);
-        }
-        await emit(msg.payload);
-    }
-}
-async function pollExecOnce(fetchImpl, ref, execId, cursor) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), PULL_HTTP_TIMEOUT_MS);
-    try {
-        // The response discloses the command's output, so the request is signed
-        // over an empty body — the same construction as the callbacks. `Date.now()`
-        // is safe: this runs inside a `DBOS.runStep` whose cached result is
-        // replayed without re-executing the body.
-        const reqTimestamp = Math.floor(Date.now() / 1000);
-        const reqSignature = signCallback({ execId, body: "", timestamp: reqTimestamp, secret: ref.callbackSecret });
-        const res = await untracedFetch(fetchImpl, `http://${ref.host}:${ref.port}/exec/${encodeURIComponent(execId)}?since=${cursor}`, {
-            method: "GET",
-            headers: {
-                "x-sandbox-signature": reqSignature,
-                "x-sandbox-timestamp": String(reqTimestamp),
-            },
-            signal: controller.signal,
-        });
-        if (!res.ok) {
-            await res.text().catch(() => "");
-            return { kind: "unavailable", detail: `status ${res.status}` };
-        }
-        const signature = res.headers.get("x-sandbox-signature");
-        const raw = await res.text();
-        if (signature === null)
-            return { kind: "unavailable", detail: "poll response missing signature" };
-        const tsHeader = res.headers.get("x-sandbox-timestamp");
-        const parsedTs = tsHeader === null ? null : Number.parseInt(tsHeader, 10);
-        return {
-            kind: "ok",
-            raw,
-            signature,
-            timestamp: parsedTs === null || Number.isNaN(parsedTs) ? null : parsedTs,
-        };
-    }
-    catch (cause) {
-        return { kind: "unavailable", detail: cause instanceof Error ? cause.message : String(cause) };
-    }
-    finally {
-        clearTimeout(timer);
-    }
-}
-/**
- * Body of the poll loop (poll transport). No `DBOS.recv`, no per-exec topic, no
- * callback handler: a sequence of durable pull steps named
- * `sandbox.poll-exec-result.${execId}.${n}`, each fetching the signed
- * `{ status, events, cursor, result? }`, verifying it exactly as a pushed
- * completion is verified, forwarding new events via `emit`, advancing the
- * cursor, and returning `result` once terminal. `sleep`, `now`, `fetch`,
- * `runStep`, and `isAlive` are injectable so the loop is testable without DBOS.
- *
- * Liveness: when the `isAlive` seam is wired (the client always wires it),
- * consecutive `unavailable` polls past the module threshold escalate to a
- * durable probe step `sandbox.probe-liveness.${execId}.${k}`; a dead verdict
- * returns the synthetic-failure result in-loop — the poll-mode analogue of the
- * watchdog's synthetic-complete, minus the topic and the race gate, since the
- * verdict is produced and consumed by the same workflow in sequence.
- *
- * The `cursor`, `pollAttempt`, and `probeAttempt` counters are pure functions
- * of the cached step sequence, so a replay issues the same polls and probes in
- * the same order and the DBOS function-ID sequence stays stable.
- */
-export async function awaitExecPoll(ref, execId, emit, deadlineMs, options = {}) {
-    const callbackSecret = ref.callbackSecret;
-    const now = options.now ?? (() => DBOS.now());
-    const fetchImpl = options.fetch ?? fetch;
-    const runStep = options.runStep ?? ((fn, c) => DBOS.runStep(fn, c));
-    const sleep = options.sleep ?? ((ms) => DBOS.sleepms(ms));
-    const warn = options.warn ?? ((message) => DBOS.logger.warn(message));
-    const isAlive = options.isAlive;
-    let cursor = 0;
-    let pollAttempt = 0;
-    // Sustained-unavailability escalation (`liveness.ts`): consecutive
-    // `unavailable` polls arm a backend-inspect probe; poll failures alone
-    // never fail the exec (`unavailable` conflates unreachable with unknown
-    // execId / non-200). Policy state and the probe counter are pure functions
-    // of the checkpointed poll outcomes, so replays walk the identical
-    // poll/probe step sequence.
-    const escalation = createEscalationPolicy();
-    let probeAttempt = 0;
-    while (true) {
-        pollAttempt += 1;
-        const pollStepName = `sandbox.poll-exec-result.${execId}.${pollAttempt}`;
-        const polled = await runStep(() => {
-            stableSpan(pollStepName, "sandbox.poll-exec-result", { [ATTR_INFLEXA_EXEC_ID]: execId, [ATTR_INFLEXA_ATTEMPT]: pollAttempt });
-            return pollExecOnce(fetchImpl, ref, execId, cursor);
-        }, { name: pollStepName });
-        if (polled.kind === "ok") {
-            // Identical treatment to a pushed completion: the bytes were signed by
-            // the same secret, so a forgery is as fatal here as it is there.
-            const verified = verifyCallback({
-                execId,
-                body: Buffer.from(polled.raw, "utf8"),
-                signature: polled.signature,
-                timestamp: polled.timestamp,
-                secret: callbackSecret,
-                nowSec: Math.floor((await now()) / 1000),
-                freshnessSec: DEFAULT_FRESHNESS_SECONDS,
-            });
-            if (!verified.valid) {
-                throw new HardCancelError(execId, verified.reason, "poll response");
-            }
-            const resp = PollResponseSchema.parse(JSON.parse(polled.raw));
-            // Forward only events past the local cursor, before returning, so
-            // trailing progress lands ahead of the terminal result. The filter is
-            // load-bearing: the signature covers the body but not the request's
-            // `since`, so any validly-signed snapshot verifies against any poll —
-            // a replayed or crossed response must not re-emit delivered events.
-            const newEvents = resp.events.filter((ev) => ev.seq > cursor);
-            // Sequence numbers are per-exec contiguous, so a hole between the
-            // local cursor and the next delivered (or high-water) seq is exact
-            // proof the ring shed events before the host saw them. Advisory: the
-            // terminal result, not the event stream, is the authoritative outcome.
-            const nextSeq = newEvents.length > 0 ? newEvents[0].seq : resp.cursor > cursor ? resp.cursor + 1 : cursor + 1;
-            const lost = nextSeq - cursor - 1;
-            if (lost > 0) {
-                warn(`awaitExecPoll[${execId}]: ${lost} progress event(s) (seq ${cursor + 1}-${cursor + lost}) shed by the sandbox ring before delivery; the terminal result is unaffected`);
-            }
-            for (const ev of newEvents) {
-                await emit(ev.payload);
-            }
-            if (resp.cursor > cursor)
-                cursor = resp.cursor;
-            if (resp.result !== undefined)
-                return resp.result;
-        }
-        if (isAlive && escalation.onPoll(polled.kind === "ok" ? "ok" : "unavailable")) {
-            probeAttempt += 1;
-            const probeStepName = `sandbox.probe-liveness.${execId}.${probeAttempt}`;
-            const verdict = await runStep(() => {
-                stableSpan(probeStepName, "sandbox.probe-liveness", { [ATTR_INFLEXA_EXEC_ID]: execId, [ATTR_INFLEXA_ATTEMPT]: probeAttempt });
-                return probeLiveness(isAlive, ref);
-            }, { name: probeStepName });
-            // Only an observably dead machine fails the exec — the result lives
-            // in that machine and nowhere else, so it is unrecoverable and the
-            // synthetic failure races nothing. `alive` (live-but-slow exec,
-            // evicted execId) and `inconclusive` (backend API error) both
-            // resume polling, bounded by the deadline.
-            if (verdict.kind === "dead") {
-                return syntheticFailureResult(execId, syntheticFailureReason({ oomKilled: verdict.oomKilled }));
-            }
-        }
-        // The deadline gate sits AFTER the poll so the loop always asks once more
-        // before declaring a timeout — same reasoning as the callback loop's
-        // deadline pull: a lost poll window is not a slow command, and reporting
-        // a timeout would discard a completed analysis.
-        const remainingMs = deadlineMs - (await now());
-        if (remainingMs <= 0)
-            throw new ExecTimeoutError(execId);
-        const intervalMs = pollAttempt <= DEFAULT_FAST_POLL_ATTEMPTS ? DEFAULT_POLL_INTERVAL_MS : DEFAULT_SLOW_POLL_INTERVAL_MS;
-        await sleep(Math.min(intervalMs, remainingMs));
-    }
-}

package/dist/sandbox/deliver-exec-event.d.ts

@@ -1,25 +0,0 @@
-/**
- * Ingress-side delivery of a sandbox-server callback onto the per-exec DBOS
- * topic (`awaitExec`'s recv loop, `await-exec.ts`).
- *
- * Exists so an embedder hosting the HTTP callback endpoint never touches the
- * DBOS SDK itself: `DBOS` is module-singleton state, and an embedder with its
- * own `node_modules` would import a SECOND, un-launched SDK instance whose
- * `send` writes nowhere. Routing delivery through the harness pins the call to
- * the same instance `launchDbos` initialized — and keeps the topic-name format
- * beside its consumer instead of duplicated in every host.
- *
- * HMAC verification is deliberately NOT done here: `awaitExec` verifies inside
- * the workflow body against the per-sandbox `callbackSecret`, so the ingress
- * stays secret-free and a forged POST is rejected where the secret lives.
- */
-import type { ExecEventMessage } from "./types.js";
-/** Topic `awaitExec` listens on for one exec's events and done-marker. */
-export declare function execEventTopic(execId: string): string;
-/**
- * Send one callback envelope (an event, or a `DoneMarker`-shaped completion
- * payload) to the workflow awaiting `execId`. The caller derives
- * `workflowId` via `workflowIdFromExec` and owns HTTP status mapping:
- * a rejection here is retryable (5xx), a malformed execId is not (4xx).
- */
-export declare function deliverExecEvent(workflowId: string, execId: string, message: ExecEventMessage): Promise<void>;

package/dist/sandbox/deliver-exec-event.js

@@ -1,29 +0,0 @@
-/**
- * Ingress-side delivery of a sandbox-server callback onto the per-exec DBOS
- * topic (`awaitExec`'s recv loop, `await-exec.ts`).
- *
- * Exists so an embedder hosting the HTTP callback endpoint never touches the
- * DBOS SDK itself: `DBOS` is module-singleton state, and an embedder with its
- * own `node_modules` would import a SECOND, un-launched SDK instance whose
- * `send` writes nowhere. Routing delivery through the harness pins the call to
- * the same instance `launchDbos` initialized — and keeps the topic-name format
- * beside its consumer instead of duplicated in every host.
- *
- * HMAC verification is deliberately NOT done here: `awaitExec` verifies inside
- * the workflow body against the per-sandbox `callbackSecret`, so the ingress
- * stays secret-free and a forged POST is rejected where the secret lives.
- */
-import { DBOS } from "@dbos-inc/dbos-sdk";
-/** Topic `awaitExec` listens on for one exec's events and done-marker. */
-export function execEventTopic(execId) {
-    return `exec-event:${execId}`;
-}
-/**
- * Send one callback envelope (an event, or a `DoneMarker`-shaped completion
- * payload) to the workflow awaiting `execId`. The caller derives
- * `workflowId` via `workflowIdFromExec` and owns HTTP status mapping:
- * a rejection here is retryable (5xx), a malformed execId is not (4xx).
- */
-export async function deliverExecEvent(workflowId, execId, message) {
-    await DBOS.send(workflowId, message, execEventTopic(execId));
-}

package/dist/sandbox/digest.d.ts

@@ -1,14 +0,0 @@
-/**
- * Body digest for sandbox callbacks.
- *
- * The callback signature is taken over the hex SHA-256 of the POSTed body
- * rather than over the body itself, so the digest is a value the ingress can
- * compute and forward while the bytes themselves are dropped — verification
- * downstream needs nothing more.
- *
- * This lives apart from `hmac.ts` on purpose. Hashing carries no secret and
- * decides nothing, so the route that only forwards can depend on it without
- * taking on the verification machinery it is required to stay clear of.
- */
-/** Hex SHA-256 of the POSTed bytes — the value the callback signature covers. */
-export declare function digestBody(input: Buffer | string): string;

package/dist/sandbox/digest.js

@@ -1,17 +0,0 @@
-/**
- * Body digest for sandbox callbacks.
- *
- * The callback signature is taken over the hex SHA-256 of the POSTed body
- * rather than over the body itself, so the digest is a value the ingress can
- * compute and forward while the bytes themselves are dropped — verification
- * downstream needs nothing more.
- *
- * This lives apart from `hmac.ts` on purpose. Hashing carries no secret and
- * decides nothing, so the route that only forwards can depend on it without
- * taking on the verification machinery it is required to stay clear of.
- */
-import { createHash } from "node:crypto";
-/** Hex SHA-256 of the POSTed bytes — the value the callback signature covers. */
-export function digestBody(input) {
-    return createHash("sha256").update(input).digest("hex");
-}

package/dist/sandbox/exec-id.d.ts

@@ -1,12 +0,0 @@
-/**
- * `execId` parsing — execId is `${workflowId}:${stepId}:${fnId}` where the
- * workflowId portion itself contains exactly one colon (child workflow ids
- * are `${analysisId}:${runId}-${stepIdx}`, parent ids are
- * `${analysisId}:${runId}`). `indexOf(":")` / `split(":")[0]` over an
- * execId would stop INSIDE the workflowId and return only the analysisId,
- * which `DBOS.send` would treat as a wrong-workflow target. Strip the last
- * two colon-delimited segments (`:${stepId}:${fnId}`) to recover the
- * workflowId. `stepId` is a plan-defined slug and `fnId` is `fn-${n.toString(36)}`,
- * neither of which can contain colons.
- */
-export declare function workflowIdFromExec(execId: string): string | null;

package/dist/sandbox/exec-id.js

@@ -1,20 +0,0 @@
-/**
- * `execId` parsing — execId is `${workflowId}:${stepId}:${fnId}` where the
- * workflowId portion itself contains exactly one colon (child workflow ids
- * are `${analysisId}:${runId}-${stepIdx}`, parent ids are
- * `${analysisId}:${runId}`). `indexOf(":")` / `split(":")[0]` over an
- * execId would stop INSIDE the workflowId and return only the analysisId,
- * which `DBOS.send` would treat as a wrong-workflow target. Strip the last
- * two colon-delimited segments (`:${stepId}:${fnId}`) to recover the
- * workflowId. `stepId` is a plan-defined slug and `fnId` is `fn-${n.toString(36)}`,
- * neither of which can contain colons.
- */
-export function workflowIdFromExec(execId) {
-    const lastColon = execId.lastIndexOf(":");
-    if (lastColon <= 0)
-        return null;
-    const secondLastColon = execId.lastIndexOf(":", lastColon - 1);
-    if (secondLastColon <= 0)
-        return null;
-    return execId.slice(0, secondLastColon);
-}

package/dist/sandbox/hmac.d.ts

@@ -1,62 +0,0 @@
-/**
- * HMAC verification for sandbox callbacks (see the harness-sandbox-exec spec).
- *
- * sandbox-server signs every outbound event/completion POST with
- * `X-Sandbox-Signature = hex(HMAC-SHA256(callbackSecret,
- *   "${execId}:${timestamp}:${sha256Hex(body)}"))` plus a
- * `X-Sandbox-Timestamp` header. The Cortex-side callback endpoint is
- * **dumb** — it forwards the headers verbatim onto the per-exec DBOS
- * topic. Verification happens here, in the workflow-body recv loop,
- * because that body holds the `callbackSecret` from the cached
- * `createSandbox` step output.
- *
- * A bad or stale signature triggers a hard cancel of the run — under
- * NetworkPolicy isolation a forged event implies a bug or a breach,
- * neither of which should keep a 3-hour sandbox burning.
- */
-export interface VerifyCallbackInput {
-    execId: string;
-    /**
-     * The bytes the sandbox-server POSTed. Supply this or `bodyDigest`.
-     *
-     * The signature covers the hex SHA-256 of the body, never the body itself,
-     * so a caller that has already hashed the bytes can verify from the digest
-     * alone — which is what keeps a large payload from being carried twice.
-     */
-    body?: Buffer | string;
-    /** Hex SHA-256 of the POSTed bytes. Takes precedence over `body`. */
-    bodyDigest?: string;
-    /** `X-Sandbox-Signature` value (lowercase hex). */
-    signature: string | null;
-    /** `X-Sandbox-Timestamp` value (unix seconds). */
-    timestamp: number | null;
-    /** Per-sandbox secret from the cached `createSandbox` step output. */
-    secret: string;
-    /** Current unix-second wall-clock — injectable for tests. */
-    nowSec: number;
-    /** Symmetric freshness window in seconds. */
-    freshnessSec: number;
-}
-export type VerifyResult = {
-    valid: true;
-} | {
-    valid: false;
-    reason: "bad-signature" | "stale-timestamp" | "missing";
-};
-/**
- * Recompute the HMAC and compare in constant time, then check the
- * timestamp falls within a symmetric `freshnessSec` window of `nowSec`.
- *
- * Order: `missing` (one of signature/timestamp is null) is reported
- * separately from `bad-signature` so the caller can log it precisely.
- * Freshness is checked AFTER signature, so a stale-but-valid signature
- * is distinguishable from a forgery.
- */
-export declare function verifyCallback(input: VerifyCallbackInput): VerifyResult;
-/** Convenience for the Cortex side to compute a signature for tests. */
-export declare function signCallback({ execId, body, timestamp, secret }: {
-    execId: string;
-    body: Buffer | string;
-    timestamp: number;
-    secret: string;
-}): string;