witnora 0.13.4 → 0.13.6

package/dist/runtime-sandbox-kit.js

@@ -0,0 +1,295 @@
+import { createHash } from "node:crypto";
+import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { credentialsPath } from "./credentials.js";
+import { findAvailableRuntimeSandboxOrigin, LOCAL_SANDBOX_FIXTURE_CONTRACT_SHA256 } from "./runtime-sandbox-fixture.js";
+export const LOCAL_SANDBOX_ADAPTER_ID = "witnora.local-sandbox.v1";
+export const LOCAL_SANDBOX_ADAPTER_VERSION = "1.0.0";
+export const LOCAL_SANDBOX_PROBE_ID = "witnora.local-sandbox.read-only-probe.v1";
+export async function discoverRuntimeReferences(input) {
+    const entries = {
+        mandateId: input.env.WITNORA_RUNTIME_MANDATE_ID?.trim(),
+        probeConnectionName: input.env.WITNORA_RUNTIME_PROBE_CONNECTION?.trim(),
+        probeHostedCredentialHandle: input.env.WITNORA_RUNTIME_PROBE_HOSTED_CREDENTIAL_HANDLE?.trim(),
+        runtimeIdentityId: input.env.WITNORA_RUNTIME_IDENTITY_ID?.trim(),
+        runtimeKeyId: input.env.WITNORA_RUNTIME_KEY_ID?.trim(),
+        runtimeSigningKeyHandle: input.env.WITNORA_RUNTIME_SIGNING_KEY_HANDLE?.trim(),
+    };
+    const manifestPath = join(dirname(credentialsPath({ configHome: input.configHome })), "runtime-references.json");
+    const manifest = await optionalJson(manifestPath);
+    const manifestReferences = manifest?.schemaVersion === "witnora.runtime_references.v0.1" && manifest.projectId === input.projectId && manifest.server === input.server
+        ? completeReferences(manifest.references)
+        : undefined;
+    const environmentOverrides = Object.fromEntries(Object.entries(entries).filter(([, value]) => value));
+    const configuredReferences = completeReferences({ ...manifestReferences, ...environmentOverrides });
+    if (configuredReferences) {
+        if (Object.keys(environmentOverrides).length > 0)
+            await saveRuntimeReferenceManifest(manifestPath, input.projectId, input.server, configuredReferences);
+        return { references: configuredReferences, manifestPath };
+    }
+    for (const candidate of [
+        join(input.repository, "runtime-production-acceptance.config.json"),
+        join(input.repository, ".witnora", "runtime-production-acceptance.config.json"),
+        join(input.repository, ".witnora", "runtime-acceptance", "config.json"),
+    ]) {
+        const acceptance = await optionalJson(candidate);
+        const migrated = acceptanceReferences(acceptance, input.projectId, input.server);
+        if (!migrated)
+            continue;
+        const migratedWithOverrides = completeReferences({ ...migrated, ...environmentOverrides });
+        if (!migratedWithOverrides)
+            continue;
+        await saveRuntimeReferenceManifest(manifestPath, input.projectId, input.server, migratedWithOverrides);
+        return { references: migratedWithOverrides, manifestPath };
+    }
+    const present = Object.entries(entries).filter(([, value]) => value).map(([key]) => key);
+    return { limitation: present.length
+            ? `Local sandbox Runtime references are incomplete (${present.join(", ")} present). Existing Gateway setup remains RECORDED_ONLY.`
+            : "No existing private Witnora Runtime reference manifest was found. Gateway setup remains RECORDED_ONLY until Hosted bootstrap can issue one-time Runtime references." };
+}
+function completeReferences(value) {
+    const mandateId = text(value.mandateId);
+    const runtimeIdentityId = text(value.runtimeIdentityId);
+    const runtimeKeyId = text(value.runtimeKeyId);
+    const runtimeSigningKeyHandle = text(value.runtimeSigningKeyHandle);
+    const probeConnectionName = text(value.probeConnectionName);
+    const probeHostedCredentialHandle = text(value.probeHostedCredentialHandle);
+    if (!mandateId || !runtimeIdentityId || !runtimeKeyId || !runtimeSigningKeyHandle || (!probeConnectionName && !probeHostedCredentialHandle))
+        return undefined;
+    return {
+        mandateId,
+        runtimeIdentityId,
+        runtimeKeyId,
+        runtimeSigningKeyHandle,
+        ...(probeConnectionName ? { probeConnectionName } : { probeHostedCredentialHandle }),
+        ...optionalBootstrapFields(value),
+    };
+}
+function acceptanceReferences(value, projectId, server) {
+    if (!value || value.projectId !== projectId || normalizeServer(text(value.hostedBaseUrl)) !== normalizeServer(server))
+        return undefined;
+    const runtime = object(value.runtimeIdentity);
+    const probe = object(value.probe);
+    const privateKeyPath = text(runtime.privateKeyPemPath);
+    const probeApiKeyPath = text(probe.apiKeyPath);
+    if (!privateKeyPath || !probeApiKeyPath)
+        return undefined;
+    return completeReferences({
+        mandateId: value.mandateId,
+        runtimeIdentityId: runtime.runtimeIdentityId,
+        runtimeKeyId: runtime.keyId,
+        runtimeSigningKeyHandle: pathToFileURL(resolve(privateKeyPath)).href,
+        probeHostedCredentialHandle: pathToFileURL(resolve(probeApiKeyPath)).href,
+    });
+}
+export async function saveRuntimeReferenceManifest(path, projectId, server, references) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.tmp`;
+    await writeFile(temporary, `${JSON.stringify({ schemaVersion: "witnora.runtime_references.v0.1", projectId, server, references }, null, 2)}\n`, { mode: 0o600 });
+    await rename(temporary, path);
+    await chmod(path, 0o600).catch(() => undefined);
+}
+export async function planRuntimeSandboxModules() {
+    const sandboxOrigin = await findAvailableRuntimeSandboxOrigin();
+    const generated = generateRuntimeSandboxKit(sandboxOrigin);
+    return {
+        sandboxOrigin,
+        adapterDigestSha256: generated.adapterSha256,
+        probeDigestSha256: generated.probeSha256,
+        fixtureContractDigestSha256: LOCAL_SANDBOX_FIXTURE_CONTRACT_SHA256,
+    };
+}
+function optionalBootstrapFields(value) {
+    const bootstrapId = text(value.bootstrapId);
+    const probeApiKeyId = text(value.probeApiKeyId);
+    const setupPlanId = text(value.setupPlanId);
+    const sandboxOrigin = text(value.sandboxOrigin);
+    const adapterDigestSha256 = digest(value.adapterDigestSha256);
+    const probeDigestSha256 = digest(value.probeDigestSha256);
+    const fixtureContractDigestSha256 = digest(value.fixtureContractDigestSha256);
+    return {
+        ...(bootstrapId ? { bootstrapId } : {}),
+        ...(probeApiKeyId ? { probeApiKeyId } : {}),
+        ...(setupPlanId ? { setupPlanId } : {}),
+        ...(sandboxOrigin ? { sandboxOrigin } : {}),
+        ...(adapterDigestSha256 ? { adapterDigestSha256 } : {}),
+        ...(probeDigestSha256 ? { probeDigestSha256 } : {}),
+        ...(fixtureContractDigestSha256 ? { fixtureContractDigestSha256 } : {}),
+    };
+}
+async function optionalJson(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function text(value) { return typeof value === "string" && value.trim() ? value.trim() : undefined; }
+function digest(value) { const item = text(value); return item && /^[a-f0-9]{64}$/.test(item) ? item : undefined; }
+function object(value) { return value && typeof value === "object" && !Array.isArray(value) ? value : {}; }
+function normalizeServer(value) { try {
+    return value ? new URL(value).toString().replace(/\/$/, "") : undefined;
+}
+catch {
+    return undefined;
+} }
+export function generateRuntimeSandboxKit(sandboxOrigin) {
+    const origin = new URL(sandboxOrigin);
+    if (origin.protocol !== "http:" || origin.hostname !== "127.0.0.1" || !origin.port || origin.pathname !== "/" || origin.search || origin.hash)
+        throw new Error("Generated Runtime sandbox origin must be a bare 127.0.0.1 HTTP origin.");
+    const adapterSource = localSandboxAdapterSource(origin.origin);
+    const probeSource = localSandboxProbeSource(origin.origin);
+    return {
+        adapterSource,
+        adapterSha256: createHash("sha256").update(adapterSource).digest("hex"),
+        probeSource,
+        probeSha256: createHash("sha256").update(probeSource).digest("hex"),
+    };
+}
+function localSandboxAdapterSource(sandboxOrigin) {
+    return `// Witnora localhost-only controlled sandbox adapter. Generated; do not add production origins.
+import { createHash, createPrivateKey, randomBytes, randomUUID, sign } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function createWitnoraRuntimeAdapter(context) {
+  const runtime = exactObject(context.runtimeIdentity, "runtimeIdentity");
+  const signingKey = exactHandle(context.runtimeSigningKey, "runtimeSigningKey");
+  const writeCredential = exactHandle(context.targetWriteCredential, "targetWriteCredential");
+  const reconcileCredential = exactHandle(context.reconcileAuditCredential, "reconcileAuditCredential");
+  if (context.adapterId !== "${LOCAL_SANDBOX_ADAPTER_ID}" || context.adapterVersion !== "${LOCAL_SANDBOX_ADAPTER_VERSION}" || !context.hosted?.request || !context.storageDirectory) throw new Error("runtime_adapter_context_invalid");
+  return {
+    id: context.adapterId,
+    version: context.adapterVersion,
+    reconcileReadOnly: true,
+    capabilities: Object.freeze({ targetSystem: "WitnoraLocalSandbox", operations: ["UPDATE"], origins: ["${sandboxOrigin}"], resources: ["mock-state/*"] }),
+    async prepareClaim({ action, grant }) {
+      const grantPayload = exactObject(grant?.grant?.payload, "grant.payload");
+      const executionSessionId = randomUUID();
+      const payload = {
+        protocolVersion: "agentcert.browser_enforcement.v0.2",
+        objectType: "RuntimeClaim",
+        signatureContext: "onegent.runtime-claim.v0.2",
+        runtimeIdentityId: runtime.id,
+        executionGrantId: grant.id,
+        executionGrantDigest: grant.grant.payloadSha256,
+        actionId: action.id,
+        ...(grantPayload.principalIdentityAssertionId ? { principalIdentityAssertionId: grantPayload.principalIdentityAssertionId } : {}),
+        ...(grantPayload.principalIdentityDigest ? { principalIdentityDigest: grantPayload.principalIdentityDigest } : {}),
+        ...(grantPayload.principalIdentityProvider ? { principalIdentityProvider: grantPayload.principalIdentityProvider } : {}),
+        executionSessionId,
+        claimNonce: randomBytes(24).toString("base64url"),
+        claimedAt: new Date().toISOString(),
+        runtimeKeyId: runtime.keyId,
+        idempotencyKey: "claim:" + grantPayload.jti,
+      };
+      const payloadSha256 = sha256(canonicalJson(payload));
+      const privateKeyPem = await readSecretHandle(signingKey.handle);
+      const signature = sign(null, Buffer.from(payloadSha256, "hex"), createPrivateKey(privateKeyPem)).toString("base64url");
+      await persistClaim(context.storageDirectory, action.id, { executionSessionId });
+      return { executionSessionId, claim: { payload, payloadSha256, signature: { algorithm: "Ed25519", keyId: runtime.keyId, signature } } };
+    },
+    async execute({ action, proposal, grant, hostedReservation }) {
+      const target = localhostTarget(proposal);
+      const executionSessionId = hostedReservation.executionSessionId;
+      await context.hosted.request("execution-attempts/" + encodeURIComponent(executionSessionId) + "/phase", { method: "POST", body: { executionSessionId, runtimeClaim: hostedReservation.claim, phase: "DISPATCH_STARTED" } });
+      const credential = await readSecretHandle(writeCredential.handle);
+      const response = await fetch(target.url, { method: "POST", redirect: "error", headers: { "content-type": "application/json", "x-sandbox-write-credential": credential }, body: JSON.stringify({ ...proposal.executionIntent.approvedParameters, actionId: action.id, executionSessionId }) });
+      const observedState = await response.json().catch(() => ({}));
+      if (!response.ok) throw new Error("sandbox_write_failed_" + response.status);
+      await context.hosted.request("execution-attempts/" + encodeURIComponent(executionSessionId) + "/phase", { method: "POST", body: { executionSessionId, runtimeClaim: hostedReservation.claim, phase: "DISPATCH_ACKNOWLEDGED", writeResponseCommitment: sha256(canonicalJson(observedState)), targetOperationId: executionSessionId } });
+      await context.hosted.request("execution-grants/" + encodeURIComponent(grant.id) + "/consume", { method: "POST", body: { executionSessionId, runtimeClaim: hostedReservation.claim } });
+      const execution = { executionSessionId, observedState, targetOperationId: executionSessionId };
+      await persistExecution(context.storageDirectory, action.id, execution);
+      return execution;
+    },
+    async reconcile({ action }) {
+      try { return JSON.parse(await readFile(join(context.storageDirectory, "executions", safeId(action.id) + ".json"), "utf8")); }
+      catch (error) { if (error?.code !== "ENOENT") throw error; }
+      let pending;
+      try { pending = JSON.parse(await readFile(join(context.storageDirectory, "claims", safeId(action.id) + ".json"), "utf8")); }
+      catch (error) { if (error?.code === "ENOENT") return undefined; throw error; }
+      const credential = await readSecretHandle(reconcileCredential.handle);
+      const response = await fetch("${sandboxOrigin}/audit/actions/" + encodeURIComponent(action.id) + "/sessions/" + encodeURIComponent(pending.executionSessionId), { redirect: "error", headers: { "x-sandbox-audit-credential": credential } });
+      if (response.status === 404) return undefined;
+      const audit = await response.json().catch(() => ({}));
+      if (!response.ok || audit.phase !== "COMMITTED" || audit.actionId !== action.id || audit.executionSessionId !== pending.executionSessionId) throw new Error("sandbox_reconcile_audit_invalid");
+      const execution = { executionSessionId: pending.executionSessionId, observedState: audit.observedState, targetOperationId: pending.executionSessionId, reconciledFromAudit: true };
+      await persistExecution(context.storageDirectory, action.id, execution);
+      return execution;
+    },
+  };
+}
+
+function localhostTarget(proposal) {
+  if (proposal?.targetSystem !== "WitnoraLocalSandbox") throw new Error("sandbox_target_system_invalid");
+  const origins = proposal?.executionIntent?.allowedOrigins;
+  if (!Array.isArray(origins) || origins.length !== 1) throw new Error("localhost_origin_required");
+  const origin = new URL(origins[0]);
+  if (origin.protocol !== "http:" || !new Set(["127.0.0.1", "localhost", "[::1]"]).has(origin.hostname) || origin.username || origin.password || origin.search || origin.hash || (origin.pathname && origin.pathname !== "/")) throw new Error("localhost_origin_required");
+  if (origin.origin !== "${sandboxOrigin}") throw new Error("sandbox_origin_binding_invalid");
+  const resource = String(proposal.executionIntent.allowedResource ?? "");
+  if (!/^mock-state\\/[A-Za-z0-9._:-]+$/.test(resource) || proposal.executionIntent.allowedOperation !== "UPDATE") throw new Error("sandbox_resource_invalid");
+  const resourceId = resource.slice("mock-state/".length);
+  if (proposal.executionIntent.approvedParameters?.resourceId !== resourceId) throw new Error("sandbox_resource_binding_invalid");
+  return { url: origin.origin + "/mock-state/" + encodeURIComponent(resourceId) };
+}
+async function persistExecution(directory, actionId, execution) {
+  const path = join(directory, "executions", safeId(actionId) + ".json");
+  await mkdir(dirname(path), { recursive: true });
+  const temporary = path + "." + randomUUID() + ".tmp";
+  await writeFile(temporary, JSON.stringify(execution) + "\\n", { mode: 0o600 });
+  await rename(temporary, path);
+}
+async function persistClaim(directory, actionId, claim) {
+  const path = join(directory, "claims", safeId(actionId) + ".json");
+  await mkdir(dirname(path), { recursive: true });
+  const temporary = path + "." + randomUUID() + ".tmp";
+  await writeFile(temporary, JSON.stringify(claim) + "\\n", { mode: 0o600 });
+  await rename(temporary, path);
+}
+function exactObject(value, label) { if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(label + "_invalid"); return value; }
+function exactHandle(value, label) { const item = exactObject(value, label); if (typeof item.handle !== "string" || item.access !== "READ_ONLY" && item.access !== "WRITE_ONLY") throw new Error(label + "_invalid"); return item; }
+function safeId(value) { if (!/^[A-Za-z0-9._:-]+$/.test(value)) throw new Error("action_id_invalid"); return value; }
+async function readSecretHandle(handle) { const url = new URL(handle); if (url.protocol !== "file:") throw new Error("only_file_secret_provider_supported"); const value = (await readFile(fileURLToPath(url), "utf8")).trim(); if (!value) throw new Error("credential_reference_empty"); return value; }
+function sha256(value) { return createHash("sha256").update(value).digest("hex"); }
+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("canonical_value_invalid"); }
+`;
+}
+function localSandboxProbeSource(sandboxOrigin) {
+    return `// Witnora independent READ_ONLY localhost sandbox probe. Generated and executed in an isolated child process.
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+export function createWitnoraOutcomeProbe(context) {
+  if (context.targetReadCredential?.access !== "READ_ONLY") throw new Error("read_only_probe_required");
+  return {
+    id: context.probeId,
+    credentialHandle: context.targetReadCredential.handle,
+    readOnly: true,
+    async observe({ proposal }) {
+      const origins = proposal?.executionIntent?.allowedOrigins;
+      if (!Array.isArray(origins) || origins.length !== 1) throw new Error("localhost_origin_required");
+      const origin = new URL(origins[0]);
+      if (origin.protocol !== "http:" || !new Set(["127.0.0.1", "localhost", "[::1]"]).has(origin.hostname) || origin.username || origin.password || origin.search || origin.hash || (origin.pathname && origin.pathname !== "/")) throw new Error("localhost_origin_required");
+      if (origin.origin !== "${sandboxOrigin}") throw new Error("sandbox_origin_binding_invalid");
+      const resource = String(proposal.executionIntent.allowedResource ?? "");
+      if (!/^mock-state\\/[A-Za-z0-9._:-]+$/.test(resource)) throw new Error("sandbox_resource_invalid");
+      const credentialUrl = new URL(context.targetReadCredential.handle);
+      if (credentialUrl.protocol !== "file:") throw new Error("only_file_secret_provider_supported");
+      const credential = (await readFile(fileURLToPath(credentialUrl), "utf8")).trim();
+      if (!credential) throw new Error("credential_reference_empty");
+      const resourceId = resource.slice("mock-state/".length);
+      const response = await fetch(origin.origin + "/mock-state/" + encodeURIComponent(resourceId), { redirect: "error", headers: { "x-sandbox-read-credential": credential } });
+      const observedState = await response.json().catch(() => ({}));
+      if (!response.ok) throw new Error("sandbox_probe_failed_" + response.status);
+      return { observedState, observationMethod: "TARGET_API", observationSource: context.probeId, confidence: 1 };
+    },
+  };
+}
+`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "witnora",
-  "version": "0.13.4",
+  "version": "0.13.6",
   "description": "Independent assurance for covered agent action paths across models and frameworks.",
   "type": "module",
   "license": "Apache-2.0",