witnora 0.13.4 → 0.13.6

package/dist/runtime-bootstrap.js

@@ -0,0 +1,333 @@
+import { createDecipheriv, createHash, createPrivateKey, createPublicKey, diffieHellman, generateKeyPairSync, hkdfSync, randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { credentialsPath } from "./credentials.js";
+import { saveRuntimeReferenceManifest } from "./runtime-sandbox-kit.js";
+const SCHEMA_VERSION = "witnora.runtime_bootstrap.v0.1";
+const ENVELOPE_ALGORITHM = "X25519-HKDF-SHA256-A256GCM";
+const PROBE_SCOPES = ["outcomes:verify"];
+const HKDF_INFO = "witnora:runtime-bootstrap:probe:v0.1";
+export async function bootstrapLocalRuntime(input) {
+    const server = normalizeServer(input.server);
+    const directory = join(dirname(credentialsPath({ configHome: input.configHome })), "runtime-bootstrap", stableId(server, input.projectId, input.planId));
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const runtimeSigningKeyPath = join(directory, "runtime-signing-private.pem");
+    const runtimePrivateKeyPem = await loadOrCreatePrivateKey(runtimeSigningKeyPath);
+    const runtimePublicKeyPem = createPublicKey(createPrivateKey(runtimePrivateKeyPem)).export({ type: "spki", format: "pem" }).toString();
+    const proposedModules = {
+        sandboxOrigin: exactLocalOrigin(input.modules.sandboxOrigin),
+        adapterDigestSha256: exactDigest(input.modules.adapterDigestSha256, "adapter"),
+        probeDigestSha256: exactDigest(input.modules.probeDigestSha256, "probe"),
+        fixtureContractDigestSha256: exactDigest(input.modules.fixtureContractDigestSha256, "fixture contract"),
+    };
+    const attemptPath = join(directory, "pending-attempt.json");
+    const attempt = await loadOrCreateAttempt(attemptPath, proposedModules);
+    const modules = {
+        adapterDigestSha256: attempt.modules.adapterDigestSha256,
+        probeDigestSha256: attempt.modules.probeDigestSha256,
+        fixtureContractDigestSha256: attempt.modules.fixtureContractDigestSha256,
+    };
+    const contract = {
+        schemaVersion: SCHEMA_VERSION,
+        attemptId: attempt.attemptId,
+        idempotencyKey: attempt.idempotencyKey,
+        runtimeIdentity: { publicKeyPem: runtimePublicKeyPem },
+        delivery: { publicKeyPem: attempt.deliveryPublicKeyPem },
+        modules,
+    };
+    const contractFingerprintSha256 = sha256(canonicalJson({
+        schemaVersion: SCHEMA_VERSION,
+        runtimeIdentity: contract.runtimeIdentity,
+        modules,
+    }));
+    const requestFetch = input.fetch ?? fetch;
+    const endpoint = `${server}/v1/projects/${encodeURIComponent(input.projectId)}/setup-plans/${encodeURIComponent(input.planId)}/runtime-bootstrap`;
+    const response = await requestFetch(endpoint, {
+        method: "POST",
+        headers: { authorization: `Bearer ${input.apiKey}`, "content-type": "application/json" },
+        body: JSON.stringify({ ...contract, contractFingerprintSha256 }),
+    });
+    const body = await response.json().catch(() => ({}));
+    if (!response.ok)
+        throw new Error(`Hosted Runtime bootstrap did not complete (HTTP ${response.status}).`);
+    const issued = validateResponse(body, contractFingerprintSha256, attempt.deliveryPublicKeyPem);
+    const probeCredentialPath = join(directory, "outcome-probe-api-key.txt");
+    const probeCredentialMetadataPath = join(directory, "outcome-probe-api-key.json");
+    const credential = issued.envelope
+        ? decryptEnvelope(issued.bootstrapId, issued.envelope, attempt.deliveryPrivateKeyPem)
+        : await existingCredential(probeCredentialPath, probeCredentialMetadataPath, issued.probeCredential.apiKeyId);
+    if (!credential)
+        throw new Error("Hosted Runtime bootstrap acknowledged delivery but the matching local probe credential is unavailable.");
+    if (credential.apiKeyId !== issued.probeCredential.apiKeyId || JSON.stringify(credential.scopes) !== JSON.stringify(PROBE_SCOPES)) {
+        throw new Error("Hosted Runtime bootstrap credential payload did not match its public binding.");
+    }
+    await atomicWrite(probeCredentialPath, Buffer.from(`${credential.secret}\n`));
+    await atomicWrite(probeCredentialMetadataPath, Buffer.from(`${JSON.stringify({ apiKeyId: credential.apiKeyId, scopes: credential.scopes })}\n`));
+    const references = {
+        bootstrapId: issued.bootstrapId,
+        mandateId: issued.mandate.id,
+        probeApiKeyId: issued.probeCredential.apiKeyId,
+        probeHostedCredentialHandle: pathToFileURL(probeCredentialPath).href,
+        runtimeIdentityId: issued.runtimeIdentity.id,
+        runtimeKeyId: issued.runtimeIdentity.keyId,
+        runtimeSigningKeyHandle: pathToFileURL(runtimeSigningKeyPath).href,
+        setupPlanId: input.planId,
+        sandboxOrigin: attempt.modules.sandboxOrigin,
+        adapterDigestSha256: modules.adapterDigestSha256,
+        probeDigestSha256: modules.probeDigestSha256,
+        fixtureContractDigestSha256: modules.fixtureContractDigestSha256,
+    };
+    if (issued.envelope)
+        await acknowledge(requestFetch, endpoint, input.apiKey, issued.bootstrapId, issued.envelope.digestSha256);
+    const manifestPath = join(dirname(credentialsPath({ configHome: input.configHome })), "runtime-references.json");
+    await saveRuntimeReferenceManifest(manifestPath, input.projectId, server, references);
+    await rm(attemptPath, { force: true });
+    return { references, bootstrapId: issued.bootstrapId };
+}
+async function acknowledge(requestFetch, endpoint, apiKey, bootstrapId, digest) {
+    const response = await requestFetch(`${endpoint}/${encodeURIComponent(bootstrapId)}/ack`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${apiKey}`, "content-type": "application/json" },
+        body: JSON.stringify({ schemaVersion: SCHEMA_VERSION, envelopeDigestSha256: digest }),
+    });
+    const body = await response.json().catch(() => ({}));
+    if (!response.ok || body.schemaVersion !== SCHEMA_VERSION || body.bootstrapId !== bootstrapId || body.acknowledged !== true || body.secretDelivered !== true) {
+        throw new Error(`Hosted Runtime bootstrap credential acknowledgement did not complete (HTTP ${response.status}).`);
+    }
+}
+async function loadOrCreateAttempt(path, modules) {
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        if (parsed.schemaVersion !== SCHEMA_VERSION || !identifier(parsed.attemptId) || !identifier(parsed.idempotencyKey)
+            || exactLocalOrigin(parsed.modules?.sandboxOrigin) !== parsed.modules.sandboxOrigin
+            || !exactDigest(parsed.modules?.adapterDigestSha256, "adapter") || !exactDigest(parsed.modules?.probeDigestSha256, "probe")
+            || !exactDigest(parsed.modules?.fixtureContractDigestSha256, "fixture contract")) {
+            throw new Error("Pending Runtime bootstrap attempt does not match the local contract.");
+        }
+        const privateKey = createPrivateKey(parsed.deliveryPrivateKeyPem);
+        if (privateKey.asymmetricKeyType !== "x25519" || createPublicKey(privateKey).export({ type: "spki", format: "pem" }).toString() !== parsed.deliveryPublicKeyPem) {
+            throw new Error("Pending Runtime bootstrap delivery key is invalid.");
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            try {
+                await rename(path, `${path}.invalid-${Date.now()}`);
+            }
+            catch {
+                throw new Error("Damaged pending Runtime bootstrap state could not be quarantined for safe rotation.");
+            }
+        }
+    }
+    const deliveryKeys = generateKeyPairSync("x25519");
+    const attempt = {
+        schemaVersion: SCHEMA_VERSION,
+        attemptId: `attempt-${randomUUID()}`,
+        idempotencyKey: `runtime-bootstrap-${randomUUID()}`,
+        deliveryPrivateKeyPem: deliveryKeys.privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
+        deliveryPublicKeyPem: deliveryKeys.publicKey.export({ type: "spki", format: "pem" }).toString(),
+        modules,
+    };
+    try {
+        await writePrivateExclusive(path, Buffer.from(`${JSON.stringify(attempt, null, 2)}\n`));
+        return attempt;
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        return loadOrCreateAttempt(path, modules);
+    }
+}
+export async function automaticRuntimeReferencesUsable(references) {
+    if (!references.bootstrapId || !references.setupPlanId || !references.probeApiKeyId || !references.probeHostedCredentialHandle)
+        return false;
+    try {
+        const secretPath = fileURLToPath(new URL(references.probeHostedCredentialHandle));
+        const metadata = JSON.parse(await readFile(join(dirname(secretPath), "outcome-probe-api-key.json"), "utf8"));
+        return Boolean((await readFile(secretPath, "utf8")).trim()
+            && metadata.apiKeyId === references.probeApiKeyId
+            && JSON.stringify(metadata.scopes) === JSON.stringify(PROBE_SCOPES));
+    }
+    catch {
+        return false;
+    }
+}
+export async function verifyAutomaticRuntimeProbe(input) {
+    const { references } = input;
+    if (!references.bootstrapId || !references.setupPlanId || !references.probeApiKeyId || !references.probeHostedCredentialHandle) {
+        throw new Error("Automatic Runtime probe references are incomplete.");
+    }
+    const secret = (await readFile(fileURLToPath(new URL(references.probeHostedCredentialHandle)), "utf8")).trim();
+    if (!secret)
+        throw new Error("Automatic Runtime probe credential is unavailable.");
+    await verifyHostedProbeCredential({
+        projectId: input.projectId,
+        server: input.server,
+        setupPlanId: references.setupPlanId,
+        bootstrapId: references.bootstrapId,
+        probeApiKeyId: references.probeApiKeyId,
+        apiKey: secret,
+        fetch: input.fetch,
+    });
+}
+export async function verifyHostedProbeCredential(input) {
+    const response = await (input.fetch ?? fetch)(`${normalizeServer(input.server)}/v1/projects/${encodeURIComponent(input.projectId)}/setup-plans/${encodeURIComponent(input.setupPlanId)}/runtime-bootstrap/${encodeURIComponent(input.bootstrapId)}/probe-status`, {
+        headers: { authorization: `Bearer ${input.apiKey}` },
+    });
+    const body = await response.json().catch(() => ({}));
+    const credential = object(body.probeCredential);
+    if (!response.ok || body.schemaVersion !== SCHEMA_VERSION || body.bootstrapId !== input.bootstrapId
+        || credential.apiKeyId !== input.probeApiKeyId || credential.projectId !== input.projectId
+        || JSON.stringify(credential.scopes) !== JSON.stringify(PROBE_SCOPES) || credential.status !== "ACTIVE"
+        || (credential.expiresAt !== undefined && !futureDate(credential.expiresAt))) {
+        throw new Error(`Hosted Runtime probe preflight did not establish an active exact credential (HTTP ${response.status}).`);
+    }
+}
+async function loadOrCreatePrivateKey(path) {
+    try {
+        const existing = await readFile(path, "utf8");
+        if (createPrivateKey(existing).asymmetricKeyType !== "ed25519")
+            throw new Error("wrong key type");
+        return existing;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw new Error("The private Runtime signing key is unreadable or invalid.");
+    }
+    const generated = generateKeyPairSync("ed25519").privateKey.export({ type: "pkcs8", format: "pem" }).toString();
+    try {
+        await writePrivateExclusive(path, Buffer.from(generated));
+        return generated;
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        return loadOrCreatePrivateKey(path);
+    }
+}
+function validateResponse(value, fingerprint, deliveryPublicKeyPem) {
+    if (value.schemaVersion !== SCHEMA_VERSION)
+        throw new Error("Hosted Runtime bootstrap returned an unsupported schema.");
+    if (value.contractFingerprintSha256 !== fingerprint)
+        throw new Error("Hosted Runtime bootstrap fingerprint did not match the local contract.");
+    const bootstrapId = identifier(value.bootstrapId) ? value.bootstrapId : undefined;
+    const runtimeIdentity = object(value.runtimeIdentity);
+    const mandate = object(value.mandate);
+    const probeCredential = object(value.probeCredential);
+    if (!bootstrapId || !identifier(runtimeIdentity.id) || !identifier(runtimeIdentity.keyId) || !futureDate(runtimeIdentity.validUntil))
+        throw new Error("Hosted Runtime bootstrap identity binding was invalid.");
+    if (!identifier(mandate.id) || !exactDigest(mandate.digestSha256, "mandate") || !futureDate(mandate.expiresAt) || mandate.maxUses !== 10)
+        throw new Error("Hosted Runtime bootstrap mandate binding was invalid.");
+    if (!identifier(probeCredential.apiKeyId) || JSON.stringify(probeCredential.scopes) !== JSON.stringify(PROBE_SCOPES))
+        throw new Error("Hosted Runtime bootstrap probe credential was invalid.");
+    const envelope = probeCredential.sealedEnvelope === undefined ? undefined : validateEnvelope(object(probeCredential.sealedEnvelope), deliveryPublicKeyPem);
+    if ((envelope && probeCredential.secretDelivered !== false) || (!envelope && probeCredential.secretDelivered !== true)) {
+        throw new Error("Hosted Runtime bootstrap probe credential delivery state was invalid.");
+    }
+    return {
+        bootstrapId,
+        runtimeIdentity: { id: String(runtimeIdentity.id), keyId: String(runtimeIdentity.keyId) },
+        mandate: { id: String(mandate.id) },
+        probeCredential: { apiKeyId: String(probeCredential.apiKeyId) },
+        ...(envelope ? { envelope } : {}),
+    };
+}
+function validateEnvelope(value, deliveryPublicKeyPem) {
+    if (value.algorithm !== ENVELOPE_ALGORITHM || typeof value.ephemeralPublicKeyPem !== "string")
+        throw new Error("Hosted Runtime bootstrap envelope algorithm was invalid.");
+    try {
+        if (createPublicKey(value.ephemeralPublicKeyPem).asymmetricKeyType !== "x25519")
+            throw new Error();
+    }
+    catch {
+        throw new Error("Hosted Runtime bootstrap envelope public key was invalid.");
+    }
+    const clientPublicKeySha256 = sha256(createPublicKey(deliveryPublicKeyPem).export({ type: "spki", format: "der" }));
+    if (value.clientPublicKeySha256 !== clientPublicKeySha256)
+        throw new Error("Hosted Runtime bootstrap envelope was not bound to this client key.");
+    for (const field of ["iv", "ciphertext", "authTag"])
+        if (typeof value[field] !== "string" || !base64url(value[field]))
+            throw new Error("Hosted Runtime bootstrap envelope encoding was invalid.");
+    const digestPayload = {
+        algorithm: value.algorithm, ephemeralPublicKeyPem: value.ephemeralPublicKeyPem, iv: value.iv, ciphertext: value.ciphertext,
+        authTag: value.authTag, clientPublicKeySha256: value.clientPublicKeySha256,
+    };
+    if (value.digestSha256 !== sha256(JSON.stringify(digestPayload)))
+        throw new Error("Hosted Runtime bootstrap envelope digest was invalid.");
+    return value;
+}
+function decryptEnvelope(bootstrapId, envelope, deliveryPrivateKeyPem) {
+    const sharedSecret = diffieHellman({ privateKey: createPrivateKey(deliveryPrivateKeyPem), publicKey: createPublicKey(envelope.ephemeralPublicKeyPem) });
+    const key = Buffer.from(hkdfSync("sha256", sharedSecret, Buffer.from(bootstrapId), Buffer.from(HKDF_INFO), 32));
+    const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(envelope.iv, "base64url"));
+    decipher.setAAD(Buffer.from(bootstrapId));
+    decipher.setAuthTag(Buffer.from(envelope.authTag, "base64url"));
+    let plaintext;
+    try {
+        plaintext = Buffer.concat([decipher.update(Buffer.from(envelope.ciphertext, "base64url")), decipher.final()]);
+    }
+    catch {
+        throw new Error("Hosted Runtime bootstrap credential envelope authentication failed.");
+    }
+    let payload;
+    try {
+        payload = JSON.parse(plaintext.toString("utf8"));
+    }
+    catch {
+        throw new Error("Hosted Runtime bootstrap credential payload was invalid.");
+    }
+    if (!identifier(payload.apiKeyId) || typeof payload.secret !== "string" || !payload.secret || /[\r\n]/.test(payload.secret) || JSON.stringify(payload.scopes) !== JSON.stringify(PROBE_SCOPES)) {
+        throw new Error("Hosted Runtime bootstrap credential payload was invalid.");
+    }
+    return { apiKeyId: payload.apiKeyId, secret: payload.secret, scopes: [...PROBE_SCOPES] };
+}
+async function existingCredential(path, metadataPath, apiKeyId) {
+    try {
+        const [secret, metadata] = await Promise.all([readFile(path, "utf8"), readFile(metadataPath, "utf8")]);
+        const value = JSON.parse(metadata);
+        return value.apiKeyId === apiKeyId && secret.trim() && JSON.stringify(value.scopes) === JSON.stringify(PROBE_SCOPES)
+            ? { apiKeyId, secret: secret.trim(), scopes: [...PROBE_SCOPES] }
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function atomicWrite(path, bytes) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
+    await writeFile(temporary, bytes, { mode: 0o600 });
+    await rename(temporary, path);
+    await chmod(path, 0o600).catch(() => undefined);
+}
+async function writePrivateExclusive(path, bytes) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await writeFile(path, bytes, { mode: 0o600, flag: "wx" });
+    await chmod(path, 0o600).catch(() => undefined);
+}
+function exactDigest(value, label) { if (typeof value !== "string" || !/^[a-f0-9]{64}$/.test(value))
+    throw new Error(`The ${label} digest was invalid.`); return value; }
+function identifier(value) { return typeof value === "string" && /^[A-Za-z0-9._:-]{1,200}$/.test(value); }
+function futureDate(value) { return typeof value === "string" && Number.isFinite(Date.parse(value)) && Date.parse(value) > Date.now(); }
+function exactLocalOrigin(value) { const url = new URL(value); if (url.protocol !== "http:" || url.hostname !== "127.0.0.1" || !url.port || url.pathname !== "/" || url.search || url.hash)
+    throw new Error("Runtime bootstrap sandbox origin must be localhost-only."); return url.origin; }
+function object(value) { return value && typeof value === "object" && !Array.isArray(value) ? value : {}; }
+function normalizeServer(value) { const url = new URL(value); if (url.protocol !== "https:" && url.hostname !== "127.0.0.1" && url.hostname !== "localhost")
+    throw new Error("Witnora server must use HTTPS."); return url.toString().replace(/\/$/, ""); }
+function stableId(...values) { return sha256(canonicalJson(values)); }
+function sha256(value) { return createHash("sha256").update(value).digest("hex"); }
+function base64url(value) { return /^[A-Za-z0-9_-]+$/.test(value); }
+function canonicalJson(value) { return JSON.stringify(canonical(value)); }
+function canonical(value) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return Object.is(value, -0) ? 0 : value;
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (value && typeof value === "object")
+        return Object.fromEntries(Object.keys(value).sort().filter((key) => value[key] !== undefined).map((key) => [key, canonical(value[key])]));
+    throw new Error("Runtime bootstrap contract contains a non-canonical value.");
+}

package/dist/runtime-sandbox-fixture.js

@@ -0,0 +1,166 @@
+import { createHash, randomUUID } from "node:crypto";
+import { createServer } from "node:http";
+import { appendFile, mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const CONTRACT = "witnora.local_sandbox_fixture.v0.1|127.0.0.1|GET,POST|/mock-state/:id|separate-read-write|persistent-state-audit|body<=8192";
+export const LOCAL_SANDBOX_FIXTURE_CONTRACT_SHA256 = createHash("sha256").update(CONTRACT).digest("hex");
+const MAX_BODY_BYTES = 8_192;
+const MAX_AUDIT_BYTES = 10 * 1024 * 1024;
+const MAX_RESOURCES = 1_000;
+const RESOURCE = /^\/mock-state\/([A-Za-z0-9._:-]{1,128})$/;
+const AUDIT = /^\/audit\/actions\/([A-Za-z0-9._:-]{1,256})\/sessions\/([A-Za-z0-9._:-]{1,256})$/;
+export async function findAvailableRuntimeSandboxOrigin() {
+    const server = createServer();
+    await listen(server, 0);
+    const address = server.address();
+    if (!address || typeof address === "string")
+        throw new Error("Could not allocate a localhost sandbox port.");
+    await close(server);
+    return `http://127.0.0.1:${address.port}`;
+}
+export async function startRuntimeSandboxFixture(input) {
+    const origin = exactOrigin(input.origin);
+    if (input.contractSha256 !== LOCAL_SANDBOX_FIXTURE_CONTRACT_SHA256)
+        throw new Error("Local sandbox fixture contract digest does not match.");
+    const [readCredential, writeCredential, auditCredential] = await Promise.all([
+        secret(input.readCredentialHandle), secret(input.writeCredentialHandle), secret(input.auditCredentialHandle),
+    ]);
+    if (new Set([readCredential, writeCredential, auditCredential]).size !== 3)
+        throw new Error("Local sandbox fixture credentials must contain separate values.");
+    const statePath = join(input.directory, "state.json");
+    const auditPath = join(input.directory, "audit.jsonl");
+    await mkdir(input.directory, { recursive: true });
+    let state = await loadState(statePath);
+    let writes = 0;
+    let queue = Promise.resolve();
+    const server = createServer((request, response) => {
+        queue = queue.then(() => handle(request, response)).catch((error) => send(response, 500, { error: safeError(error) }));
+    });
+    async function handle(request, response) {
+        response.setHeader("content-type", "application/json");
+        response.setHeader("cache-control", "no-store");
+        if (!request.url || request.url.length > 512)
+            return send(response, 404, { error: "not_found" });
+        if (request.url === "/healthz" && request.method === "GET") {
+            if (request.headers["x-sandbox-read-credential"] !== readCredential)
+                return send(response, 401, { error: "unauthorized" });
+            return send(response, 200, { schemaVersion: "witnora.local_sandbox_fixture_health.v0.1", contractSha256: input.contractSha256, origin, writes });
+        }
+        const auditMatch = AUDIT.exec(request.url);
+        if (auditMatch && request.method === "GET") {
+            if (request.headers["x-sandbox-audit-credential"] !== auditCredential)
+                return send(response, 401, { error: "unauthorized" });
+            const record = await committedAudit(auditPath, auditMatch[1], auditMatch[2]);
+            return record ? send(response, 200, record) : send(response, 404, { error: "not_found" });
+        }
+        const match = RESOURCE.exec(request.url);
+        if (!match)
+            return send(response, 404, { error: "not_found" });
+        const resourceId = match[1];
+        if (request.method === "GET") {
+            if (request.headers["x-sandbox-read-credential"] !== readCredential)
+                return send(response, 401, { error: "unauthorized" });
+            const value = state[resourceId];
+            return value ? send(response, 200, value) : send(response, 404, { error: "not_found" });
+        }
+        if (request.method !== "POST")
+            return send(response, 405, { error: "method_not_allowed" });
+        if (request.headers["x-sandbox-write-credential"] !== writeCredential)
+            return send(response, 401, { error: "unauthorized" });
+        const body = await readBoundedJson(request);
+        const status = text(body.status, "status", 128);
+        const actionId = text(body.actionId, "actionId", 256);
+        const executionSessionId = text(body.executionSessionId, "executionSessionId", 256);
+        if (!(resourceId in state) && Object.keys(state).length >= MAX_RESOURCES)
+            throw new Error("sandbox_resource_limit_reached");
+        const auditBytes = await stat(auditPath).then((value) => value.size).catch(() => 0);
+        if (auditBytes >= MAX_AUDIT_BYTES)
+            throw new Error("sandbox_audit_limit_reached");
+        const transactionId = randomUUID();
+        const next = { resourceId, status, actionId, executionSessionId };
+        await appendFile(auditPath, `${JSON.stringify({ transactionId, phase: "PREPARED", resourceId, actionId, executionSessionId, at: new Date().toISOString() })}\n`, { mode: 0o600 });
+        state = { ...state, [resourceId]: next };
+        await atomicJson(statePath, state);
+        await appendFile(auditPath, `${JSON.stringify({ transactionId, phase: "COMMITTED", resourceId, actionId, executionSessionId, observedState: next, stateSha256: createHash("sha256").update(JSON.stringify(next)).digest("hex"), at: new Date().toISOString() })}\n`, { mode: 0o600 });
+        writes += 1;
+        return send(response, 200, next);
+    }
+    await listen(server, Number(new URL(origin).port));
+    return { origin, close: () => close(server) };
+}
+async function committedAudit(path, actionId, executionSessionId) {
+    let content;
+    try {
+        content = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    if (Buffer.byteLength(content) > MAX_AUDIT_BYTES + MAX_BODY_BYTES)
+        throw new Error("sandbox_audit_limit_reached");
+    for (const line of content.trim().split("\n").reverse()) {
+        const record = JSON.parse(line);
+        if (record.phase === "COMMITTED" && record.actionId === actionId && record.executionSessionId === executionSessionId)
+            return record;
+    }
+    return undefined;
+}
+async function loadState(path) {
+    try {
+        const value = JSON.parse(await readFile(path, "utf8"));
+        return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return {};
+        throw error;
+    }
+}
+async function atomicJson(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    await rename(temporary, path);
+}
+async function readBoundedJson(request) {
+    const declared = Number(request.headers["content-length"] ?? 0);
+    if (declared > MAX_BODY_BYTES)
+        throw new Error("sandbox_body_too_large");
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        size += Buffer.byteLength(chunk);
+        if (size > MAX_BODY_BYTES)
+            throw new Error("sandbox_body_too_large");
+        chunks.push(Buffer.from(chunk));
+    }
+    const value = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("sandbox_body_invalid");
+    return value;
+}
+async function secret(handle) {
+    const url = new URL(handle);
+    if (url.protocol !== "file:")
+        throw new Error("Local sandbox fixture supports file:// secret handles only.");
+    const value = (await readFile(fileURLToPath(url), "utf8")).trim();
+    if (!value)
+        throw new Error("Local sandbox fixture credential is empty.");
+    return value;
+}
+function exactOrigin(value) {
+    const url = new URL(value);
+    if (url.protocol !== "http:" || url.hostname !== "127.0.0.1" || !url.port || url.username || url.password || url.pathname !== "/" || url.search || url.hash)
+        throw new Error("Local sandbox fixture must use a bare 127.0.0.1 HTTP origin.");
+    return url.origin;
+}
+function text(value, name, max) { if (typeof value !== "string" || !value || value.length > max)
+    throw new Error(`sandbox_${name}_invalid`); return value; }
+function safeError(error) { return error instanceof SyntaxError ? "sandbox_body_invalid" : error instanceof Error && /^sandbox_[a-z_]+$/.test(error.message) ? error.message : "sandbox_internal_error"; }
+function send(response, status, body) { if (response.writableEnded)
+    return; response.statusCode = status; response.end(JSON.stringify(body)); }
+function listen(server, port) { return new Promise((resolve, reject) => { server.once("error", reject); server.listen(port, "127.0.0.1", () => { server.off("error", reject); resolve(); }); }); }
+function close(server) { return new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve())); }