@b00dea/cockpit 0.0.0-stage → 0.1.1

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,38 @@
+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>;
+/**
+ * Whether a command can be started from `cwd`, found the way a wrapper that changes into `cwd` would
+ * find it, without hashing the file: a command with a slash is relative to `cwd`, a bare name is
+ * looked up on PATH. For callers that report presence rather than run the file.
+ */
+export declare function locateExecutable(command: string, env: Readonly<Record<string, string | undefined>>, cwd: string): Promise<Readonly<{
+    state: 'present';
+    path: string;
+}> | Readonly<{
+    state: 'unavailable';
+    reason: string;
+}>>;
+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>;