@b00dea/cockpit 0.0.0-stage → 0.1.0

package/dist/environment/evidence.js

@@ -0,0 +1,437 @@
+import { sha256Hex } from '../sha256.js';
+import { isAbsolute, normalize } from 'node:path';
+import { authenticatedExecutionOutcome } from '../environment-exec/execute.js';
+import { RefusalError, ENVIRONMENT_CODES, EXECUTION_FAILURE_CODES, snapshotJson, snapshotExecutionPlan, forwardedRefusal, } from './contract.js';
+import { classifyResolvedRuntimeLiterals } from './runtime.js';
+import { isSensitiveField, redactSensitiveText } from './sensitive.js';
+import { isResolvedDockerExecutable } from './executable.js';
+import { exactKeys } from '../exact-keys.js';
+const SHA256 = /^[a-f0-9]{64}$/;
+const STACK_ID = /^stack:[a-f0-9]{64}$/;
+const CONTAINER_ID = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/;
+const ISO_INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/;
+const MAX_TIMEOUT_MS = 30_000;
+// Exported so a caller passes the capture's own bound: the capture prints one stat line and one
+// digest line, and a general output limit sized for logs exceeds what this planner admits.
+export const STABILITY_CAPTURE_OUTPUT_LIMIT_BYTES = 65_536;
+const UNAVAILABLE_EVIDENCE_CODES = new Set([ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE, ...EXECUTION_FAILURE_CODES]);
+const PROCESS_STEP_PREFIX = 'evidence:process-identity:';
+const CONTENT_STEP_PREFIX = 'evidence:content-hash:';
+const PROCESS_SCRIPT = 'IFS= read -r stat < /proc/1/stat; pid=${stat%% *}; rest=${stat##*) }; set -- $rest; printf "%s %s\\n" "$pid" "${20}"';
+// -H follows a symlink named as a content path: /proc/1/exe is one, and without -H find skips it,
+// hashes nothing, and the capture fails with an empty corpus on every real container.
+const CONTENT_SCRIPT = 'tmp=${TMPDIR:-/tmp}/cockpit-content-$$; cockpit_hash_failure=$tmp.failed; export cockpit_hash_failure; trap \'rm -f "$tmp.raw" "$tmp.sorted" "$tmp.failed"\' EXIT HUP INT TERM; find -H "$@" -type f -exec sh -c \'sha256sum -- "$@" || { : > "$cockpit_hash_failure"; exit 1; }\' sh {} + > "$tmp.raw"; [ ! -e "$tmp.failed" ] && [ -s "$tmp.raw" ]; LC_ALL=C sort "$tmp.raw" > "$tmp.sorted"; sha256sum "$tmp.sorted"';
+function stableValue(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableValue).join(',')}]`;
+    if (value !== null && typeof value === 'object') {
+        return `{${Object.entries(value).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+            .map(([key, child]) => `${JSON.stringify(key)}:${stableValue(child)}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function ownedObject(value) {
+    const snapshot = snapshotJson(value);
+    return snapshot !== undefined && snapshot !== null && typeof snapshot === 'object' && !Array.isArray(snapshot)
+        ? snapshot
+        : undefined;
+}
+function sanitize(value, key = '') {
+    if (isSensitiveField(key))
+        return '[redacted]';
+    if (Array.isArray(value))
+        return value.map((item) => sanitize(item));
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([name, child]) => [name, sanitize(child, name)]));
+    }
+    return typeof value === 'string' ? redactSensitiveText(value) : value;
+}
+function validInstant(value) {
+    if (!ISO_INSTANT.test(value))
+        return false;
+    const date = new Date(value);
+    const canonical = value.includes('.') ? value : value.replace('Z', '.000Z');
+    return !Number.isNaN(date.valueOf()) && date.toISOString() === canonical;
+}
+function instantMs(value) { return new Date(value).valueOf(); }
+function diagnostic(message, target) {
+    return { severity: 'error', code: ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE, message, target };
+}
+function refusal(message, target) {
+    return forwardedRefusal([diagnostic(message, target)]);
+}
+export function createEnvironmentSnapshot(input) {
+    const owned = ownedObject(input);
+    if (owned === undefined || !exactKeys(owned, ['configSha256', 'createdAt', 'creationSource', 'intendedState', 'stackId'])
+        || typeof owned.stackId !== 'string' || typeof owned.configSha256 !== 'string' || typeof owned.createdAt !== 'string'
+        || !STACK_ID.test(owned.stackId) || !SHA256.test(owned.configSha256) || !validInstant(owned.createdAt)
+        || owned.creationSource !== 'resolved-config') {
+        throw new RefusalError('environment snapshot provenance is invalid');
+    }
+    const intendedState = sanitize(owned.intendedState);
+    const snapshotSha256 = sha256Hex(stableValue({
+        stackId: owned.stackId,
+        configSha256: owned.configSha256,
+        createdAt: owned.createdAt,
+        creationSource: owned.creationSource,
+        intendedState,
+    }));
+    return {
+        artifact: 'generated-environment-snapshot', schemaVersion: 1, stackId: owned.stackId,
+        configSha256: owned.configSha256, createdAt: owned.createdAt,
+        creationSource: owned.creationSource, intendedState, snapshotSha256,
+    };
+}
+function stabilityCapturePlanInput(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)
+        || !exactKeys(value, ['stackId', 'configSha256', 'runtimeExecutable', 'cwd', 'env', 'containerId', 'batchId', 'runtime', 'contentPaths', 'timeoutMs', 'outputLimitBytes']))
+        return undefined;
+    const input = value;
+    if (!isResolvedDockerExecutable(input.runtimeExecutable)
+        || input.runtime === null || typeof input.runtime !== 'object' || Array.isArray(input.runtime)
+        || !exactKeys(input.runtime, ['name', 'version']) || Object.values(input.runtime).some((part) => typeof part !== 'string')
+        || input.env === null || typeof input.env !== 'object' || Array.isArray(input.env)
+        || Object.entries(input.env).some(([name, part]) => name.length === 0 || typeof part !== 'string')
+        || !Array.isArray(input.contentPaths) || input.contentPaths.some((path) => typeof path !== 'string')
+        || typeof input.stackId !== 'string' || typeof input.configSha256 !== 'string' || typeof input.cwd !== 'string'
+        || typeof input.containerId !== 'string' || typeof input.batchId !== 'string'
+        || typeof input.timeoutMs !== 'number' || typeof input.outputLimitBytes !== 'number')
+        return undefined;
+    return input;
+}
+function captureStep(input, id, argv) {
+    return {
+        id,
+        argv: [...argv],
+        argv0: input.runtimeExecutable.invocationPath,
+        cwd: input.cwd,
+        env: { ...input.env },
+        timeoutMs: input.timeoutMs,
+        stdoutLimitBytes: input.outputLimitBytes,
+        stderrLimitBytes: input.outputLimitBytes,
+        paths: [...input.contentPaths],
+        ports: [],
+        labels: { stackId: input.stackId, configSha256: input.configSha256, containerId: input.containerId, batchId: input.batchId, runtimeName: input.runtime.name, runtimeVersion: input.runtime.version, executableSha256: input.runtimeExecutable.sha256, evidenceRole: id.startsWith(PROCESS_STEP_PREFIX) ? 'process-identity' : 'content-hash' },
+        expected: [],
+        consumedFiles: [{ path: input.runtimeExecutable.canonicalPath, sha256: input.runtimeExecutable.sha256, maxBytes: 536_870_912, argvIndexes: [0], executable: true, executionMode: input.runtimeExecutable.executionMode }],
+        filesystemChecks: [],
+        compensation: [],
+    };
+}
+export function createStabilityCapturePlan(rawInput) {
+    const input = stabilityCapturePlanInput(snapshotJson(rawInput));
+    if (input === undefined)
+        return refusal('stability capture input must be readable JSON data', 'stability-capture');
+    const pathsValid = input.contentPaths.length > 0 && new Set(input.contentPaths).size === input.contentPaths.length
+        && input.contentPaths.every((path) => isAbsolute(path) && normalize(path) === path && !path.includes('\0'));
+    if (!STACK_ID.test(input.stackId) || !SHA256.test(input.configSha256)
+        || !isResolvedDockerExecutable(input.runtimeExecutable)
+        || !isAbsolute(input.cwd) || normalize(input.cwd) !== input.cwd || !CONTAINER_ID.test(input.containerId) || !SHA256.test(input.batchId)
+        || input.runtime.name !== 'docker' || !/^\d+\.\d+\.\d+$/.test(input.runtime.version)
+        || !pathsValid || !Number.isInteger(input.timeoutMs) || input.timeoutMs < 1 || input.timeoutMs > MAX_TIMEOUT_MS
+        || !Number.isInteger(input.outputLimitBytes) || input.outputLimitBytes < 1 || input.outputLimitBytes > STABILITY_CAPTURE_OUTPUT_LIMIT_BYTES) {
+        return refusal('stability capture requires resolved in-container targets and bounded execution', input.containerId);
+    }
+    if (Object.keys(input.env).some((name) => name.startsWith('DOCKER_') || name.startsWith('COMPOSE_'))
+        || classifyResolvedRuntimeLiterals([...Object.keys(input.env), ...Object.values(input.env)]) !== 'resolved') {
+        return refusal('stability capture cannot accept decision-bearing runtime environment', input.containerId);
+    }
+    const steps = [
+        captureStep(input, `${PROCESS_STEP_PREFIX}${input.containerId}`, [
+            input.runtimeExecutable.canonicalPath, 'exec', '--', input.containerId,
+            '/bin/sh', '-eu', '-c', PROCESS_SCRIPT,
+        ]),
+        captureStep(input, `${CONTENT_STEP_PREFIX}${input.containerId}`, [
+            input.runtimeExecutable.canonicalPath, 'exec', '--', input.containerId,
+            '/bin/sh', '-eu', '-c', CONTENT_SCRIPT, 'cockpit-content-hash', ...input.contentPaths,
+        ]),
+    ];
+    const plan = snapshotExecutionPlan({ steps });
+    return plan === undefined
+        ? refusal('stability capture did not produce a valid execution plan', input.containerId)
+        : { kind: 'preview', status: 0, diagnostics: [], result: null, plan };
+}
+const authenticatedCaptureBrand = Symbol('authenticated-stability-capture');
+const issuedCaptures = new WeakMap();
+function ownedResults(value) {
+    return Array.isArray(value) && value.length === 2 ? [value[0], value[1]] : undefined;
+}
+function captureAuthenticationInput(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value) || !exactKeys(value, ['plan', 'results']))
+        return undefined;
+    const { plan, results } = value;
+    return { plan, results };
+}
+export function authenticateStabilityCapture(input) {
+    const ownedInput = captureAuthenticationInput(input);
+    if (ownedInput === undefined)
+        return unavailable('stability capture input is not readable');
+    const plan = ownedObject(ownedInput.plan);
+    const capturedResults = ownedResults(ownedInput.results);
+    if (plan === undefined || capturedResults === undefined || !exactKeys(plan, ['kind', 'status', 'diagnostics', 'result', 'plan'])
+        || plan.kind !== 'preview' || plan.status !== 0 || plan.result !== null || !Array.isArray(plan.diagnostics) || plan.diagnostics.length !== 0) {
+        return unavailable('stability capture input is not readable');
+    }
+    const executionPlan = snapshotExecutionPlan(plan.plan);
+    if (executionPlan === undefined)
+        return unavailable('stability capture input is not readable');
+    const steps = executionPlan.steps;
+    if (steps.length !== 2) {
+        return unavailable('stability capture requires two complete planned execution results');
+    }
+    const authenticatedResults = capturedResults.map((result, index) => authenticatedExecutionOutcome(result, steps[index]));
+    if (authenticatedResults.some((result) => result === undefined)) {
+        return unavailable('stability results do not authenticate against one planned execution cohort');
+    }
+    const refused = authenticatedResults.find((result) => result?.kind === 'refusal');
+    if (refused?.kind === 'refusal')
+        return unavailable('stability capture execution was refused', refused.code);
+    const results = authenticatedResults;
+    const [first, second] = results;
+    const labels = steps[0].labels;
+    const sameCohort = steps.every((step) => step.labels.stackId === labels.stackId
+        && step.labels.configSha256 === labels.configSha256 && step.labels.batchId === labels.batchId
+        && step.labels.containerId === labels.containerId && step.labels.runtimeName === labels.runtimeName
+        && step.labels.runtimeVersion === labels.runtimeVersion && step.labels.executableSha256 === labels.executableSha256
+        && step.argv0 === steps[0].argv0);
+    const executable = steps[0].argv[0];
+    const exactCommands = steps[0].argv.length === 8 && steps[0].argv.slice(1).join('\0') === ['exec', '--', labels.containerId, '/bin/sh', '-eu', '-c', PROCESS_SCRIPT].join('\0')
+        && steps[1].argv.length > 9 && steps[1].argv.slice(1, 8).join('\0') === ['exec', '--', labels.containerId, '/bin/sh', '-eu', '-c', CONTENT_SCRIPT].join('\0')
+        && steps[1].argv[8] === 'cockpit-content-hash'
+        && isAbsolute(steps[0].argv0) && normalize(steps[0].argv0) === steps[0].argv0
+        && steps.every((step) => step.argv[0] === executable && step.filesystemChecks.length === 0
+            && step.consumedFiles.length === 1 && step.consumedFiles[0].path === executable
+            && step.consumedFiles[0].sha256 === labels.executableSha256
+            && step.consumedFiles[0].executable && step.consumedFiles[0].argvIndexes.length === 1
+            && step.consumedFiles[0].argvIndexes[0] === 0);
+    if (!sameCohort || !exactCommands || !STACK_ID.test(labels.stackId ?? '') || !SHA256.test(labels.configSha256 ?? '')
+        || !SHA256.test(labels.batchId ?? '') || !CONTAINER_ID.test(labels.containerId ?? '') || labels.runtimeName !== 'docker'
+        || !/^\d+\.\d+\.\d+$/.test(labels.runtimeVersion ?? '') || !SHA256.test(labels.executableSha256 ?? '')
+        || steps[0].labels.evidenceRole !== 'process-identity' || steps[1].labels.evidenceRole !== 'content-hash'
+        || !validInstant(first.receipt.startedAt) || !validInstant(first.receipt.finishedAt)
+        || !validInstant(second.receipt.startedAt) || !validInstant(second.receipt.finishedAt)
+        || instantMs(first.receipt.startedAt) > instantMs(first.receipt.finishedAt) || instantMs(first.receipt.finishedAt) > instantMs(second.receipt.startedAt)
+        || instantMs(second.receipt.startedAt) > instantMs(second.receipt.finishedAt)
+        || steps[0].id !== `${PROCESS_STEP_PREFIX}${labels.containerId}` || steps[1].id !== `${CONTENT_STEP_PREFIX}${labels.containerId}`
+        || first.receipt.stepId !== steps[0].id || second.receipt.stepId !== steps[1].id) {
+        return unavailable('stability results do not authenticate against one planned execution cohort');
+    }
+    const stdout = first.stdout.byteLength + second.stdout.byteLength;
+    const stderr = first.stderr.byteLength + second.stderr.byteLength;
+    if (results.some((result, index) => result.stdout.byteLength > steps[index].stdoutLimitBytes || result.stderr.byteLength > steps[index].stderrLimitBytes
+        || result.execution.stdoutRetainedBytes !== result.stdout.byteLength || result.execution.stderrRetainedBytes !== result.stderr.byteLength
+        || result.execution.stdoutObservedBytes !== result.stdout.byteLength || result.execution.stderrObservedBytes !== result.stderr.byteLength))
+        return unavailable('stability result exceeded its planned limit');
+    let processIdentity;
+    let contentHash;
+    try {
+        processIdentity = new TextDecoder('utf-8', { fatal: true }).decode(first.stdout).trim();
+        contentHash = new TextDecoder('utf-8', { fatal: true }).decode(second.stdout).trim().split(/\s+/)[0];
+    }
+    catch { /* Invalid UTF-8 is the only throw here and is what the message names. */
+        return unavailable('stability result encoding is invalid');
+    }
+    if (!/^\d+ \d+$/.test(processIdentity) || !SHA256.test(contentHash))
+        return unavailable('stability result shape is invalid');
+    const payload = {
+        stackId: labels.stackId, configSha256: labels.configSha256,
+        batchId: labels.batchId, containerId: labels.containerId,
+        runtime: { name: labels.runtimeName, version: labels.runtimeVersion, executableSha256: labels.executableSha256 }, startedAt: first.receipt.startedAt, finishedAt: second.receipt.finishedAt,
+        command: { stepIds: [steps[0].id, steps[1].id], timeoutMs: Math.max(...steps.map(({ timeoutMs }) => timeoutMs)), stdoutLimitBytes: steps.reduce((sum, step) => sum + step.stdoutLimitBytes, 0), stderrLimitBytes: steps.reduce((sum, step) => sum + step.stderrLimitBytes, 0) },
+        observedBytes: { stdout, stderr }, processIdentity, contentHash,
+    };
+    const capture = { [authenticatedCaptureBrand]: true, ...payload };
+    issuedCaptures.set(capture, payload);
+    return capture;
+}
+function unavailable(reason, code = ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE) {
+    return { state: 'unavailable', code, reason };
+}
+export function captureRuntimeEvidence(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input) || !exactKeys(input, ['capture'])
+        || input.capture === null || typeof input.capture !== 'object') {
+        return unavailable('runtime evidence capture is not readable');
+    }
+    const capture = issuedCaptures.get(input.capture);
+    if (capture === undefined)
+        return unavailable('runtime evidence was not produced by an authenticated capture');
+    if (!validAuthenticatedCapture(capture))
+        return unavailable('runtime evidence provenance is invalid');
+    const [processStepId, contentStepId] = capture.command.stepIds;
+    if (!STACK_ID.test(capture.stackId) || !SHA256.test(capture.configSha256)
+        || !SHA256.test(capture.runtime.executableSha256) || !/^\d+\.\d+\.\d+$/.test(capture.runtime.version)
+        || capture.runtime.name.length === 0 || !SHA256.test(capture.batchId) || !CONTAINER_ID.test(capture.containerId)
+        || processStepId !== `${PROCESS_STEP_PREFIX}${capture.containerId}` || contentStepId !== `${CONTENT_STEP_PREFIX}${capture.containerId}`)
+        return unavailable('runtime evidence provenance is invalid');
+    if (!Number.isSafeInteger(capture.observedBytes.stdout) || !Number.isSafeInteger(capture.observedBytes.stderr)) {
+        return unavailable('runtime evidence exceeded or omitted its declared execution limits');
+    }
+    const observedAt = capture.finishedAt;
+    const command = { ...capture.command, batchId: capture.batchId, containerId: capture.containerId, stepIds: [...capture.command.stepIds] };
+    const observedBytes = { ...capture.observedBytes };
+    const runtime = { ...capture.runtime };
+    const stability = {
+        processIdentitySha256: sha256Hex(capture.processIdentity),
+        contentHash: capture.contentHash,
+    };
+    const captureStartedAt = capture.startedAt;
+    const core = { stackId: capture.stackId, configSha256: capture.configSha256, runtime, observedAt, captureStartedAt, command, observedBytes, stability };
+    return { state: 'available', artifact: 'captured-runtime-evidence', schemaVersion: 1, ...core, evidenceSha256: sha256Hex(stableValue(core)) };
+}
+function sameRuntime(left, right) {
+    return left.runtime.name === right.runtime.name && left.runtime.version === right.runtime.version
+        && left.runtime.executableSha256 === right.runtime.executableSha256;
+}
+function validRuntimeEvidence(value) {
+    if (validEvidence(value))
+        return true;
+    if (value === null || typeof value !== 'object' || Array.isArray(value)
+        || !exactKeys(value, ['state', 'code', 'reason']))
+        return false;
+    const candidate = value;
+    return candidate.state === 'unavailable' && typeof candidate.code === 'string'
+        && UNAVAILABLE_EVIDENCE_CODES.has(candidate.code) && typeof candidate.reason === 'string';
+}
+export function compareEnvironmentSnapshot(rawSnapshot, rawBefore, rawAfter) {
+    const snapshot = ownedObject(rawSnapshot);
+    const before = ownedObject(rawBefore);
+    const after = ownedObject(rawAfter);
+    if (snapshot === undefined || before === undefined || after === undefined) {
+        return { verdict: 'unavailable', diagnostics: [diagnostic('environment evidence is not readable', 'environment-evidence')] };
+    }
+    if (!validSnapshot(snapshot)) {
+        return { verdict: 'unavailable', diagnostics: [diagnostic('generated environment snapshot is invalid', 'environment-snapshot')] };
+    }
+    if (!validRuntimeEvidence(before) || !validRuntimeEvidence(after)) {
+        return { verdict: 'unavailable', diagnostics: [diagnostic('captured runtime evidence is invalid', snapshot.stackId)] };
+    }
+    if (before.state !== 'available' || after.state !== 'available') {
+        return { verdict: 'unavailable', diagnostics: [diagnostic('required runtime evidence is unavailable', snapshot.stackId)] };
+    }
+    if (!isRuntimeEvidenceAuthentic(before) || !isRuntimeEvidenceAuthentic(after)) {
+        return { verdict: 'unavailable', diagnostics: [diagnostic('captured runtime evidence is invalid', snapshot.stackId)] };
+    }
+    if (snapshot.stackId !== before.stackId || snapshot.stackId !== after.stackId
+        || snapshot.configSha256 !== before.configSha256 || snapshot.configSha256 !== after.configSha256
+        || !sameRuntime(before, after)) {
+        return { verdict: 'stale', diagnostics: [diagnostic('evidence authorities changed during comparison', snapshot.stackId)] };
+    }
+    if (before.command.batchId === after.command.batchId || instantMs(before.observedAt) > instantMs(after.captureStartedAt)) {
+        return { verdict: 'unavailable', diagnostics: [diagnostic('evidence batches are replayed or out of order', snapshot.stackId)] };
+    }
+    const processIdentity = before.stability.processIdentitySha256 === after.stability.processIdentitySha256 ? 'unchanged' : 'moved';
+    const contentHash = before.stability.contentHash === after.stability.contentHash ? 'unchanged' : 'moved';
+    if (processIdentity === 'moved' || contentHash === 'moved') {
+        return {
+            verdict: 'void', processIdentity, contentHash,
+            diagnostics: [diagnostic('test subject changed while evidence was captured', snapshot.stackId)],
+        };
+    }
+    const diagnostics = [];
+    return { verdict: 'stable', processIdentity, contentHash, diagnostics };
+}
+function validSnapshot(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)
+        || !exactKeys(value, ['artifact', 'schemaVersion', 'stackId', 'configSha256', 'createdAt', 'creationSource', 'intendedState', 'snapshotSha256']))
+        return false;
+    const snapshot = value;
+    if (typeof snapshot.artifact !== 'string' || typeof snapshot.schemaVersion !== 'number'
+        || typeof snapshot.stackId !== 'string' || typeof snapshot.configSha256 !== 'string'
+        || typeof snapshot.createdAt !== 'string' || typeof snapshot.creationSource !== 'string'
+        || typeof snapshot.snapshotSha256 !== 'string' || snapshot.intendedState === undefined)
+        return false;
+    const core = {
+        stackId: snapshot.stackId, configSha256: snapshot.configSha256, createdAt: snapshot.createdAt,
+        creationSource: snapshot.creationSource, intendedState: snapshot.intendedState,
+    };
+    return snapshot.artifact === 'generated-environment-snapshot' && snapshot.schemaVersion === 1
+        && STACK_ID.test(snapshot.stackId) && SHA256.test(snapshot.configSha256) && validInstant(snapshot.createdAt)
+        && snapshot.creationSource === 'resolved-config' && stableValue(sanitize(snapshot.intendedState)) === stableValue(snapshot.intendedState)
+        && SHA256.test(snapshot.snapshotSha256)
+        && snapshot.snapshotSha256 === sha256Hex(stableValue(core));
+}
+function validAuthenticatedCapture(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)
+        || !exactKeys(value, ['stackId', 'configSha256', 'batchId', 'containerId', 'runtime', 'startedAt', 'finishedAt', 'command', 'observedBytes', 'processIdentity', 'contentHash']))
+        return false;
+    const capture = value;
+    return typeof capture.stackId === 'string' && STACK_ID.test(capture.stackId)
+        && typeof capture.configSha256 === 'string' && SHA256.test(capture.configSha256)
+        && typeof capture.batchId === 'string' && SHA256.test(capture.batchId)
+        && typeof capture.containerId === 'string' && CONTAINER_ID.test(capture.containerId)
+        && capture.runtime !== null && typeof capture.runtime === 'object' && !Array.isArray(capture.runtime)
+        && exactKeys(capture.runtime, ['name', 'version', 'executableSha256'])
+        && typeof capture.runtime.name === 'string' && capture.runtime.name.length > 0
+        && typeof capture.runtime.version === 'string' && /^\d+\.\d+\.\d+$/.test(capture.runtime.version)
+        && typeof capture.runtime.executableSha256 === 'string' && SHA256.test(capture.runtime.executableSha256)
+        && typeof capture.startedAt === 'string' && validInstant(capture.startedAt)
+        && typeof capture.finishedAt === 'string' && validInstant(capture.finishedAt)
+        && capture.command !== null && typeof capture.command === 'object' && !Array.isArray(capture.command)
+        && exactKeys(capture.command, ['stepIds', 'timeoutMs', 'stdoutLimitBytes', 'stderrLimitBytes'])
+        && Array.isArray(capture.command.stepIds) && capture.command.stepIds.length === 2
+        && capture.command.stepIds.every((id) => typeof id === 'string')
+        && Number.isSafeInteger(capture.command.timeoutMs) && capture.command.timeoutMs > 0 && capture.command.timeoutMs <= MAX_TIMEOUT_MS
+        && Number.isSafeInteger(capture.command.stdoutLimitBytes) && capture.command.stdoutLimitBytes > 0 && capture.command.stdoutLimitBytes <= STABILITY_CAPTURE_OUTPUT_LIMIT_BYTES * 2
+        && Number.isSafeInteger(capture.command.stderrLimitBytes) && capture.command.stderrLimitBytes > 0 && capture.command.stderrLimitBytes <= STABILITY_CAPTURE_OUTPUT_LIMIT_BYTES * 2
+        && capture.observedBytes !== null && typeof capture.observedBytes === 'object' && !Array.isArray(capture.observedBytes)
+        && exactKeys(capture.observedBytes, ['stdout', 'stderr'])
+        && Number.isSafeInteger(capture.observedBytes.stdout) && capture.observedBytes.stdout >= 0
+        && Number.isSafeInteger(capture.observedBytes.stderr) && capture.observedBytes.stderr >= 0
+        && capture.observedBytes.stdout <= capture.command.stdoutLimitBytes
+        && capture.observedBytes.stderr <= capture.command.stderrLimitBytes
+        && typeof capture.processIdentity === 'string' && /^\d+ \d+$/.test(capture.processIdentity)
+        && typeof capture.contentHash === 'string' && SHA256.test(capture.contentHash);
+}
+function validEvidence(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)
+        || !exactKeys(value, ['state', 'artifact', 'schemaVersion', 'stackId', 'configSha256', 'runtime', 'observedAt', 'captureStartedAt', 'command', 'observedBytes', 'stability', 'evidenceSha256']))
+        return false;
+    const evidence = value;
+    if (evidence.runtime === null || typeof evidence.runtime !== 'object' || Array.isArray(evidence.runtime)
+        || !exactKeys(evidence.runtime, ['name', 'version', 'executableSha256'])
+        || typeof evidence.runtime.name !== 'string' || typeof evidence.runtime.version !== 'string'
+        || typeof evidence.runtime.executableSha256 !== 'string'
+        || evidence.command === null || typeof evidence.command !== 'object' || Array.isArray(evidence.command)
+        || !exactKeys(evidence.command, ['batchId', 'containerId', 'stepIds', 'timeoutMs', 'stdoutLimitBytes', 'stderrLimitBytes'])
+        || typeof evidence.command.batchId !== 'string' || typeof evidence.command.containerId !== 'string'
+        || !Array.isArray(evidence.command.stepIds) || evidence.command.stepIds.length !== 2
+        || evidence.command.stepIds.some((id) => typeof id !== 'string')
+        || evidence.observedBytes === null || typeof evidence.observedBytes !== 'object' || Array.isArray(evidence.observedBytes)
+        || !exactKeys(evidence.observedBytes, ['stdout', 'stderr'])
+        || evidence.stability === null || typeof evidence.stability !== 'object' || Array.isArray(evidence.stability)
+        || !exactKeys(evidence.stability, ['processIdentitySha256', 'contentHash'])
+        || typeof evidence.stability.processIdentitySha256 !== 'string' || typeof evidence.stability.contentHash !== 'string'
+        || typeof evidence.state !== 'string' || typeof evidence.artifact !== 'string' || typeof evidence.schemaVersion !== 'number'
+        || typeof evidence.stackId !== 'string' || typeof evidence.configSha256 !== 'string'
+        || typeof evidence.observedAt !== 'string' || typeof evidence.captureStartedAt !== 'string'
+        || typeof evidence.evidenceSha256 !== 'string')
+        return false;
+    const core = {
+        stackId: evidence.stackId, configSha256: evidence.configSha256, runtime: evidence.runtime,
+        observedAt: evidence.observedAt, captureStartedAt: evidence.captureStartedAt,
+        command: evidence.command, observedBytes: evidence.observedBytes,
+        stability: evidence.stability,
+    };
+    return evidence.state === 'available' && evidence.artifact === 'captured-runtime-evidence' && evidence.schemaVersion === 1
+        && STACK_ID.test(evidence.stackId) && SHA256.test(evidence.configSha256) && validInstant(evidence.observedAt)
+        && validInstant(evidence.captureStartedAt) && instantMs(evidence.captureStartedAt) <= instantMs(evidence.observedAt)
+        && evidence.runtime.name === 'docker' && /^\d+\.\d+\.\d+$/.test(evidence.runtime.version)
+        && SHA256.test(evidence.runtime.executableSha256) && SHA256.test(evidence.command.batchId)
+        && CONTAINER_ID.test(evidence.command.containerId)
+        && evidence.command.stepIds.length === 2
+        && evidence.command.stepIds[0] === `${PROCESS_STEP_PREFIX}${evidence.command.containerId}`
+        && evidence.command.stepIds[1] === `${CONTENT_STEP_PREFIX}${evidence.command.containerId}`
+        && Number.isSafeInteger(evidence.command.timeoutMs) && evidence.command.timeoutMs > 0 && evidence.command.timeoutMs <= MAX_TIMEOUT_MS
+        && Number.isSafeInteger(evidence.command.stdoutLimitBytes) && evidence.command.stdoutLimitBytes > 0 && evidence.command.stdoutLimitBytes <= STABILITY_CAPTURE_OUTPUT_LIMIT_BYTES * 2
+        && Number.isSafeInteger(evidence.command.stderrLimitBytes) && evidence.command.stderrLimitBytes > 0 && evidence.command.stderrLimitBytes <= STABILITY_CAPTURE_OUTPUT_LIMIT_BYTES * 2
+        && Number.isSafeInteger(evidence.observedBytes.stdout) && evidence.observedBytes.stdout >= 0
+        && Number.isSafeInteger(evidence.observedBytes.stderr) && evidence.observedBytes.stderr >= 0
+        && evidence.observedBytes.stdout <= evidence.command.stdoutLimitBytes
+        && evidence.observedBytes.stderr <= evidence.command.stderrLimitBytes
+        && SHA256.test(evidence.stability.processIdentitySha256) && SHA256.test(evidence.stability.contentHash)
+        && SHA256.test(evidence.evidenceSha256) && evidence.evidenceSha256 === sha256Hex(stableValue(core));
+}
+export function isRuntimeEvidenceAuthentic(rawEvidence) {
+    const evidence = ownedObject(rawEvidence);
+    return evidence !== undefined && validEvidence(evidence);
+}

package/dist/environment/executable.d.ts

@@ -0,0 +1,26 @@
+export declare const GUARD_EXECUTABLE_SEARCH_PATH = "/usr/bin:/bin:/usr/local/bin:/opt/homebrew/bin";
+export interface ResolvedExecutable {
+    readonly canonicalPath: string;
+    readonly invocationPath: string;
+    readonly sha256: string;
+    readonly executionMode: 'verified-path';
+}
+export declare function resolvedExecutable(value: unknown): ResolvedExecutable | undefined;
+export declare function isResolvedExecutable(value: unknown): boolean;
+export declare function resolvedDockerExecutable(value: unknown): ResolvedExecutable | undefined;
+export declare function isResolvedDockerExecutable(value: unknown): boolean;
+export declare function resolvedGitExecutable(value: unknown): ResolvedExecutable | undefined;
+export declare function isResolvedGitExecutable(value: unknown): boolean;
+export type ExecutableResolution = Readonly<{
+    state: 'available';
+    value: ResolvedExecutable;
+}> | Readonly<{
+    state: 'unavailable';
+    reason: string;
+}>;
+export declare function resolveExecutablePath(path: string): Promise<ExecutableResolution>;
+export declare function resolveExecutable(name: string, env: Readonly<Record<string, string | undefined>>): Promise<ExecutableResolution>;
+export declare function resolveGitExecutable(env: Readonly<Record<string, string | undefined>>): Promise<ExecutableResolution>;
+export declare function resolveDiskCapacityExecutable(): Promise<ExecutableResolution>;
+export declare function resolveDockerExecutable(env: Readonly<Record<string, string | undefined>>): Promise<ExecutableResolution>;
+export declare function resolvePathRemovalExecutable(): Promise<ExecutableResolution>;

package/dist/environment/executable.js

@@ -0,0 +1,167 @@
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open, realpath } from 'node:fs/promises';
+import { basename, delimiter, isAbsolute, join, normalize } from 'node:path';
+import { errorCause } from './contract.js';
+import { fileFingerprint, recordVerifiedDigest, verifiedDigest } from '../environment-exec/verified-digest.js';
+import { exactKeys } from '../exact-keys.js';
+// A guard runs inside the agent's hook with an environment the agent controls, so the tools it
+// observes with are found on this fixed search path rather than the inherited PATH.
+export const GUARD_EXECUTABLE_SEARCH_PATH = '/usr/bin:/bin:/usr/local/bin:/opt/homebrew/bin';
+const SHA256 = /^[a-f0-9]{64}$/;
+export function resolvedExecutable(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)
+        || !exactKeys(value, ['canonicalPath', 'invocationPath', 'sha256', 'executionMode']))
+        return undefined;
+    const { canonicalPath, invocationPath, sha256, executionMode } = value;
+    return typeof canonicalPath === 'string' && isAbsolute(canonicalPath) && normalize(canonicalPath) === canonicalPath
+        && !canonicalPath.includes('\0') && typeof invocationPath === 'string' && isAbsolute(invocationPath)
+        && normalize(invocationPath) === invocationPath && !invocationPath.includes('\0')
+        && typeof sha256 === 'string' && SHA256.test(sha256)
+        && executionMode === 'verified-path'
+        ? { canonicalPath, invocationPath, sha256, executionMode }
+        : undefined;
+}
+export function isResolvedExecutable(value) {
+    return resolvedExecutable(value) !== undefined;
+}
+export function resolvedDockerExecutable(value) {
+    const executable = resolvedExecutable(value);
+    return executable !== undefined && basename(executable.invocationPath) === 'docker' ? executable : undefined;
+}
+export function isResolvedDockerExecutable(value) {
+    return resolvedDockerExecutable(value) !== undefined;
+}
+export function resolvedGitExecutable(value) {
+    const executable = resolvedExecutable(value);
+    return executable !== undefined && basename(executable.invocationPath) === 'git' ? executable : undefined;
+}
+export function isResolvedGitExecutable(value) {
+    return resolvedGitExecutable(value) !== undefined;
+}
+const EXECUTABLE_BYTE_LIMIT = 536_870_912;
+const PATH_ENTRY_LIMIT = 256;
+function searchPath(env) {
+    try {
+        return { kind: 'selected', path: env.PATH };
+    }
+    catch { /* A throwing PATH getter means the environment is unreadable; the caller reports it as unavailable. */
+        return { kind: 'unreadable' };
+    }
+}
+function unavailable(reason) {
+    return { state: 'unavailable', reason };
+}
+async function digestRegularFile(path) {
+    let file;
+    try {
+        const before = await lstat(path);
+        if (before.isSymbolicLink() || !before.isFile() || before.size > EXECUTABLE_BYTE_LIMIT || (before.mode & 0o111) === 0)
+            return undefined;
+        file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const opened = await file.stat();
+        if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino || opened.size > EXECUTABLE_BYTE_LIMIT)
+            return undefined;
+        const fingerprint = fileFingerprint(path, opened);
+        const remembered = verifiedDigest(fingerprint);
+        if (remembered !== undefined)
+            return fileFingerprint(path, await lstat(path)) === fingerprint ? remembered : undefined;
+        const hash = createHash('sha256');
+        const chunk = Buffer.allocUnsafe(1_048_576);
+        let total = 0;
+        while (true) {
+            const { bytesRead } = await file.read(chunk, 0, Math.min(chunk.byteLength, EXECUTABLE_BYTE_LIMIT - total + 1), null);
+            if (bytesRead === 0)
+                break;
+            total += bytesRead;
+            if (total > EXECUTABLE_BYTE_LIMIT)
+                return undefined;
+            hash.update(chunk.subarray(0, bytesRead));
+        }
+        const after = await file.stat();
+        const linked = await lstat(path);
+        const sha256 = total === opened.size && after.size === opened.size && after.mtimeMs === opened.mtimeMs
+            && linked.dev === opened.dev && linked.ino === opened.ino && linked.size === opened.size && linked.mtimeMs === opened.mtimeMs
+            ? hash.digest('hex')
+            : undefined;
+        if (sha256 !== undefined && fileFingerprint(path, after) === fingerprint)
+            recordVerifiedDigest(fingerprint, sha256);
+        await file.close();
+        file = undefined;
+        return sha256;
+    }
+    catch {
+        // Any read failure means no digest; the caller reports the executable identity as unavailable.
+        return undefined;
+    }
+    finally {
+        try {
+            await file?.close();
+        }
+        catch { /* The caller receives unavailable; no descriptor authority survives. */ }
+    }
+}
+export async function resolveExecutablePath(path) {
+    if (typeof path !== 'string' || !isAbsolute(path) || normalize(path) !== path || path.includes('\0')) {
+        return unavailable('Executable path must be an exact absolute path');
+    }
+    let invocation;
+    try {
+        invocation = await lstat(path);
+    }
+    catch (error) {
+        return unavailable(`Executable is unavailable: ${path}: ${errorCause(error)}`);
+    }
+    if (!(invocation.isFile() || invocation.isSymbolicLink()) || invocation.isFile() && (invocation.mode & 0o111) === 0) {
+        return unavailable(`Executable is unavailable: ${path}`);
+    }
+    let canonicalPath;
+    try {
+        canonicalPath = await realpath(path);
+    }
+    catch (error) {
+        return unavailable(`Executable is unavailable: ${path}: ${errorCause(error)}`);
+    }
+    const sha256 = await digestRegularFile(canonicalPath);
+    if (sha256 === undefined)
+        return unavailable(`Executable identity is unavailable: ${path}`);
+    const value = resolvedExecutable({ canonicalPath, invocationPath: path, sha256, executionMode: 'verified-path' });
+    return value ? { state: 'available', value } : unavailable(`Executable identity is invalid: ${path}`);
+}
+export async function resolveExecutable(name, env) {
+    if (typeof name !== 'string' || name.length === 0 || name.includes('\0'))
+        return unavailable('Executable name is invalid');
+    if (isAbsolute(name))
+        return resolveExecutablePath(name);
+    if (basename(name) !== name)
+        return unavailable('Executable name must be absolute or a PATH entry name');
+    const selected = searchPath(env);
+    if (selected.kind === 'unreadable')
+        return unavailable('Executable search path is not readable');
+    const pathValue = selected.path;
+    if (typeof pathValue !== 'string' || pathValue.length === 0 || pathValue.includes('\0') || Buffer.byteLength(pathValue) > 65_536) {
+        return unavailable('Executable search path is missing or invalid');
+    }
+    const directories = pathValue.split(delimiter);
+    if (directories.length > PATH_ENTRY_LIMIT || directories.some(path => !isAbsolute(path) || normalize(path) !== path)) {
+        return unavailable('Executable search path must contain bounded absolute directories');
+    }
+    for (const directory of directories) {
+        const result = await resolveExecutablePath(join(directory, name));
+        if (result.state === 'available')
+            return result;
+    }
+    return unavailable(`Executable was not found in the supplied search path: ${name}`);
+}
+export async function resolveGitExecutable(env) {
+    return resolveExecutable('git', env);
+}
+export async function resolveDiskCapacityExecutable() {
+    return resolveExecutablePath(process.execPath);
+}
+export async function resolveDockerExecutable(env) {
+    return resolveExecutable('docker', env);
+}
+export async function resolvePathRemovalExecutable() {
+    return resolveExecutablePath('/bin/rm');
+}

package/dist/environment/generated-application/authorities.d.ts

@@ -0,0 +1,5 @@
+import { type ConsumedWorkApplicationAuthorities, type GeneratedApplicationProjection, type GeneratedEnvironmentCommandInput, type RefusalOutcome, type WorkApplicationAuthoritiesProjection } from './shared.js';
+export declare function generatedApplicationProjection(value: unknown): GeneratedApplicationProjection | undefined;
+export declare function projectWorkApplicationAuthorities(application: GeneratedApplicationProjection): WorkApplicationAuthoritiesProjection | undefined;
+export declare function consumeWorkApplicationAuthorities(projection: WorkApplicationAuthoritiesProjection): ConsumedWorkApplicationAuthorities | undefined;
+export declare function prepareWorkApplicationAuthorities(input: GeneratedEnvironmentCommandInput): Promise<WorkApplicationAuthoritiesProjection | RefusalOutcome>;