@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/environment/env-schema-observation.js

@@ -0,0 +1,241 @@
+// Owns: observing the env-schema status of siblings that have adopted Varlock (they contain a
+// `.env.schema`). Must not: read, keep or print a resolved value, decide the health verdict
+// (observations.ts), or spawn a process itself (environment-exec/execute.ts runs the step).
+// Varlock is optional, so a sibling without `.env.schema` is not observed at all and an absent
+// binary is advisory. Handed off to: health-composition.ts (producer) and application/health.ts (rows,
+// diagnostics).
+//
+// `varlock load --agent` still prints partial values, and its error messages can quote a value, so
+// the report is reduced to key names, the sensitive flag and a validity category the moment it is
+// parsed. Nothing else leaves this module.
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { authenticatedExecutionOutcome } from '../environment-exec/execute.js';
+import { isMissing, RefusalError, ENVIRONMENT_CODES, errorCause, isCanonicalTimestamp, snapshotEnvironmentObservation, snapshotExecutionStep, } from './contract.js';
+import { resolveExecutable } from './executable.js';
+const OWNER = 'env-schema-observation';
+const ENV_SCHEMA_FILE = '.env.schema';
+export const VARLOCK_INSTALL_URL = 'https://varlock.dev';
+export const observationDeclarations = Object.freeze([
+    { id: 'env-schema', owner: OWNER, postures: ['environment'], stages: [{ stage: 'bootstrap', disposition: 'required' }, { stage: 'steady', disposition: 'required' }], code: ENVIRONMENT_CODES.ENV_SCHEMA_UNHEALTHY, isIssued: isEnvSchemaObservation, issuedAt: observationIssuedAt },
+]);
+const issuedObservations = new WeakMap();
+function issueObservation(value) {
+    const snapshot = snapshotEnvironmentObservation(value);
+    if (!snapshot || snapshot.owner !== OWNER)
+        throw new RefusalError('env-schema observation is malformed');
+    issuedObservations.set(snapshot, Date.now());
+    return snapshot;
+}
+function isEnvSchemaObservation(value) {
+    return value !== null && typeof value === 'object' && issuedObservations.has(value);
+}
+function observationIssuedAt(value) {
+    return value !== null && typeof value === 'object' ? issuedObservations.get(value) : undefined;
+}
+const STDOUT_LIMIT_BYTES = 262_144;
+const STDERR_LIMIT_BYTES = 16_384;
+const KEY_LIMIT = 4_096;
+const KEY_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+const REASON_BUDGET_BYTES = 900;
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+// Reads the key names and error categories out of a `--format json-full` report and drops
+// everything else, including every `value` and every error message (a message may quote a value).
+function reduceReport(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout.toString('utf8'));
+    }
+    catch { // Parser text would quote varlock output, which can hold environment values.
+        return { kind: 'malformed' };
+    }
+    if (!isRecord(parsed) || !isRecord(parsed.config))
+        return { kind: 'malformed' };
+    const names = Object.keys(parsed.config);
+    if (names.length > KEY_LIMIT)
+        return { kind: 'malformed' };
+    const failures = [];
+    let schemaError = false;
+    const errors = parsed.errors;
+    if (errors !== undefined) {
+        const items = isRecord(errors) ? errors.configItems : undefined;
+        if (isRecord(items)) {
+            for (const [key, message] of Object.entries(items)) {
+                if (!KEY_NAME.test(key) || typeof message !== 'string')
+                    return { kind: 'malformed' };
+                failures.push({ key, problem: /required/i.test(message) ? 'missing-required' : 'invalid' });
+            }
+        }
+        if (failures.length === 0)
+            schemaError = true;
+    }
+    return { kind: 'report', keys: names.length, failures: failures.sort((a, b) => a.key < b.key ? -1 : 1), schemaError };
+}
+async function hasEnvSchema(root) {
+    try {
+        return { adopted: (await stat(join(root, ENV_SCHEMA_FILE))).isFile() };
+    }
+    catch (error) {
+        if (isMissing(error))
+            return { adopted: false };
+        return { adopted: true, unreadable: `${ENV_SCHEMA_FILE} could not be inspected (${errorCause(error)})` };
+    }
+}
+function createStep(input) {
+    const { executable, sibling } = input;
+    return snapshotExecutionStep({
+        id: `env-schema:${sibling.slug}`,
+        argv: [executable.canonicalPath, 'load', '--agent', '--format', 'json-full', '--path', sibling.root],
+        argv0: executable.invocationPath,
+        cwd: sibling.root,
+        env: input.env,
+        timeoutMs: input.timeoutMs,
+        stdoutLimitBytes: STDOUT_LIMIT_BYTES,
+        stderrLimitBytes: STDERR_LIMIT_BYTES,
+        paths: [],
+        ports: [],
+        labels: { producer: 'env-schema', stackId: input.stackId, sibling: sibling.slug },
+        expected: [{ kind: 'path', target: sibling.root, state: 'directory' }],
+        consumedFiles: [{ path: executable.canonicalPath, sha256: executable.sha256, maxBytes: 536_870_912, argvIndexes: [0], executable: true, executionMode: executable.executionMode }],
+        filesystemChecks: [],
+        compensation: [],
+    });
+}
+function describeFailure(outcome, timeoutMs) {
+    switch (outcome.code) {
+        case ENVIRONMENT_CODES.EXECUTION_TIMEOUT:
+            return `varlock timed out after ${timeoutMs} ms (a secret provider may be prompting or unreachable)`;
+        case ENVIRONMENT_CODES.EXECUTION_STDOUT_LIMIT:
+            return `varlock output exceeded ${STDOUT_LIMIT_BYTES} bytes`;
+        case ENVIRONMENT_CODES.EXECUTION_SPAWN_FAILED:
+            return 'varlock could not be started';
+        default:
+            return `varlock failed (${outcome.code}, exit status ${outcome.execution.exitCode}) without a readable report`;
+    }
+}
+async function checkSibling(sibling, executable, input, execute) {
+    if (!executable)
+        return { state: 'tool-missing' };
+    const step = createStep({ executable, sibling, ...input });
+    if (!step)
+        return { state: 'unavailable', cause: 'varlock invocation could not be planned' };
+    let raw;
+    try {
+        raw = await execute(step);
+    }
+    catch (error) {
+        return { state: 'unavailable', cause: `varlock execution is unavailable: ${errorCause(error)}` };
+    }
+    const outcome = authenticatedExecutionOutcome(raw, step);
+    if (!outcome)
+        return { state: 'unavailable', cause: 'varlock execution evidence is unauthenticated' };
+    // Varlock exits nonzero when validation fails but still prints the report, so a refusal
+    // for a plain nonzero exit is still decoded.
+    const exitedNonzero = outcome.kind === 'refusal' && outcome.code === ENVIRONMENT_CODES.EXECUTION_STEP_FAILED
+        && outcome.execution.signal === null;
+    if (outcome.kind === 'refusal' && !exitedNonzero)
+        return { state: 'unavailable', cause: describeFailure(outcome, input.timeoutMs) };
+    const report = reduceReport(outcome.stdout);
+    if (report.kind === 'malformed') {
+        return {
+            state: 'unavailable',
+            cause: outcome.kind === 'refusal'
+                ? describeFailure(outcome, input.timeoutMs)
+                : 'varlock produced a report in an unrecognised shape',
+        };
+    }
+    if (report.failures.length > 0 || report.schemaError) {
+        return { state: 'invalid', failures: report.failures, schemaError: report.schemaError };
+    }
+    return outcome.kind === 'refusal'
+        ? { state: 'unavailable', cause: describeFailure(outcome, input.timeoutMs) }
+        : { state: 'valid', keys: report.keys };
+}
+function bounded(text) {
+    if (Buffer.byteLength(text) <= REASON_BUDGET_BYTES)
+        return text;
+    return `${Buffer.from(text).subarray(0, REASON_BUDGET_BYTES).toString('utf8').replace(/�$/, '')}...`;
+}
+function invalidSummary(sibling, status) {
+    const group = (problem) => status.failures.filter((failure) => failure.problem === problem).map(({ key }) => key);
+    const parts = [
+        ...(group('missing-required').length > 0 ? [`missing required ${group('missing-required').join(', ')}`] : []),
+        ...(group('invalid').length > 0 ? [`invalid ${group('invalid').join(', ')}`] : []),
+        ...(status.schemaError && status.failures.length === 0 ? ['schema could not be loaded'] : []),
+    ];
+    return `${sibling.slug} (${sibling.dir}): ${parts.join('; ')}`;
+}
+/**
+ * Observes every sibling that contains `.env.schema`. Returns one aggregate observation per
+ * stack, with the per-sibling status in its measured value. `env` is the caller's environment:
+ * a secret provider may need its own variables to resolve.
+ */
+export async function observeEnvSchemas(input, options) {
+    const detected = await Promise.all(input.siblings.map(async (sibling) => ({ sibling, ...(await hasEnvSchema(sibling.root)) })));
+    const adopted = detected.filter(({ adopted }) => adopted);
+    const needsBinary = adopted.some(({ unreadable }) => unreadable === undefined);
+    const resolved = needsBinary ? await resolveExecutable('varlock', input.env) : undefined;
+    const executable = resolved?.state === 'available' ? resolved.value : undefined;
+    const shared = {
+        env: Object.fromEntries(Object.entries(input.env)
+            .filter((entry) => typeof entry[1] === 'string')),
+        timeoutMs: input.timeoutMs,
+        stackId: input.stackId,
+    };
+    const statuses = await Promise.all(adopted.map(async ({ sibling, unreadable }) => [sibling, unreadable !== undefined
+            ? { state: 'unavailable', cause: unreadable }
+            : await checkSibling(sibling, executable, shared, options.execute)]));
+    const observedAt = new Date().toISOString();
+    if (!isCanonicalTimestamp(observedAt))
+        throw new RefusalError('env-schema observation timestamp is not canonical');
+    const common = {
+        code: ENVIRONMENT_CODES.ENV_SCHEMA_UNHEALTHY,
+        owner: OWNER,
+        stackId: input.stackId,
+        source: 'env-schema',
+        applicability: { state: 'required', posture: 'environment' },
+        freshness: { state: 'current' },
+    };
+    const invalid = statuses.flatMap(([sibling, status]) => status.state === 'invalid' ? [[sibling, status]] : []);
+    const unavailable = statuses.flatMap(([sibling, status]) => status.state === 'unavailable' ? [[sibling, status]] : []);
+    const remedy = 'run `varlock load` in each named sibling directory and fix the reported keys';
+    if (invalid.length > 0) {
+        return [issueObservation({
+                ...common,
+                observed: { state: 'failed', reason: bounded(`env schema is invalid in ${invalid.map(([sibling, status]) => invalidSummary(sibling, status)).join('; ')}`), observedAt },
+                expectation: { kind: 'equal', value: true },
+                remedy,
+            })];
+    }
+    if (unavailable.length > 0) {
+        return [issueObservation({
+                ...common,
+                observed: { state: 'unavailable', reason: bounded(`env schema could not be checked: ${unavailable.map(([sibling, status]) => `${sibling.slug} (${sibling.dir}): ${status.cause}`).join('; ')}`), observedAt },
+                expectation: { kind: 'equal', value: true },
+                remedy,
+            })];
+    }
+    // An absent varlock binary is advisory because varlock is optional; applicationDiagnostics
+    // turns it into a warning instead of a failing row.
+    const entries = statuses
+        .map(([sibling, status]) => status.state === 'valid'
+        ? { sibling: sibling.slug, state: 'valid', keys: status.keys }
+        : { sibling: sibling.slug, state: 'tool-missing' })
+        .sort((a, b) => a.sibling < b.sibling ? -1 : 1);
+    const measured = entries;
+    return [issueObservation({
+            ...common,
+            observed: { state: 'available', value: measured, observedAt },
+            expectation: { kind: 'equal', value: measured },
+            remedy: `install Varlock (${VARLOCK_INSTALL_URL}) to validate the env schema`,
+        })];
+}
+/** Siblings whose schema was skipped because varlock is not installed, from a passing row. */
+export function envSchemaToolMissing(check) {
+    if (check.owner !== OWNER || check.verdict !== 'pass' || !Array.isArray(check.measured))
+        return [];
+    return check.measured.flatMap((entry) => isRecord(entry) && entry.state === 'tool-missing' && typeof entry.sibling === 'string'
+        ? [entry.sibling] : []);
+}

package/dist/environment/evidence.d.ts

@@ -0,0 +1,136 @@
+import { type ExecuteProbeOutcome } from '../environment-exec/execute.js';
+import { ENVIRONMENT_CODES, type EnvironmentCommandOutcome, type EnvironmentDiagnostic, type ExecutionFailureCode, type StackId } from './contract.js';
+import { type ResolvedExecutable } from './executable.js';
+export declare const STABILITY_CAPTURE_OUTPUT_LIMIT_BYTES = 65536;
+type JsonPrimitive = null | boolean | number | string;
+export type JsonValue = JsonPrimitive | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+export interface EnvironmentSnapshotInput {
+    readonly stackId: StackId;
+    readonly configSha256: string;
+    readonly createdAt: string;
+    readonly creationSource: 'resolved-config';
+    readonly intendedState: JsonValue;
+}
+export interface EnvironmentSnapshot {
+    readonly artifact: 'generated-environment-snapshot';
+    readonly schemaVersion: 1;
+    readonly stackId: StackId;
+    readonly configSha256: string;
+    readonly createdAt: string;
+    readonly creationSource: string;
+    readonly intendedState: JsonValue;
+    readonly snapshotSha256: string;
+}
+export declare function createEnvironmentSnapshot(input: EnvironmentSnapshotInput): EnvironmentSnapshot;
+export interface StabilityCapturePlanInput {
+    readonly stackId: StackId;
+    readonly configSha256: string;
+    readonly runtimeExecutable: ResolvedExecutable;
+    readonly cwd: string;
+    readonly env: Readonly<Record<string, string>>;
+    readonly containerId: string;
+    readonly batchId: string;
+    readonly runtime: {
+        readonly name: string;
+        readonly version: string;
+    };
+    readonly contentPaths: readonly string[];
+    readonly timeoutMs: number;
+    readonly outputLimitBytes: number;
+}
+export declare function createStabilityCapturePlan(rawInput: StabilityCapturePlanInput): EnvironmentCommandOutcome<null>;
+declare const authenticatedCaptureBrand: unique symbol;
+export interface AuthenticatedStabilityCapture {
+    readonly [authenticatedCaptureBrand]: true;
+    readonly stackId: StackId;
+    readonly configSha256: string;
+    readonly batchId: string;
+    readonly containerId: string;
+    readonly runtime: Readonly<{
+        name: string;
+        version: string;
+        executableSha256: string;
+    }>;
+    readonly startedAt: string;
+    readonly finishedAt: string;
+    readonly command: Readonly<{
+        stepIds: readonly [string, string];
+        timeoutMs: number;
+        stdoutLimitBytes: number;
+        stderrLimitBytes: number;
+    }>;
+    readonly observedBytes: Readonly<{
+        stdout: number;
+        stderr: number;
+    }>;
+    readonly processIdentity: string;
+    readonly contentHash: string;
+}
+export type StabilityStepResult = ExecuteProbeOutcome;
+export declare function authenticateStabilityCapture(input: {
+    readonly plan: Extract<EnvironmentCommandOutcome<null>, {
+        kind: 'preview';
+    }>;
+    readonly results: readonly StabilityStepResult[];
+}): AuthenticatedStabilityCapture | UnavailableRuntimeEvidence;
+export interface RuntimeEvidenceInput {
+    readonly capture: AuthenticatedStabilityCapture;
+}
+export interface CapturedEvidenceCommand {
+    readonly batchId: string;
+    readonly containerId: string;
+    readonly stepIds: readonly [string, string];
+    readonly timeoutMs: number;
+    readonly stdoutLimitBytes: number;
+    readonly stderrLimitBytes: number;
+}
+export interface CapturedRuntimeEvidence {
+    readonly state: 'available';
+    readonly artifact: 'captured-runtime-evidence';
+    readonly schemaVersion: 1;
+    readonly stackId: StackId;
+    readonly configSha256: string;
+    readonly runtime: Readonly<{
+        name: string;
+        version: string;
+        executableSha256: string;
+    }>;
+    readonly observedAt: string;
+    readonly captureStartedAt: string;
+    readonly command: Readonly<CapturedEvidenceCommand>;
+    readonly observedBytes: Readonly<{
+        stdout: number;
+        stderr: number;
+    }>;
+    readonly stability: Readonly<{
+        processIdentitySha256: string;
+        contentHash: string;
+    }>;
+    readonly evidenceSha256: string;
+}
+export interface UnavailableRuntimeEvidence {
+    readonly state: 'unavailable';
+    readonly code: typeof ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE | ExecutionFailureCode;
+    readonly reason: string;
+}
+export type RuntimeEvidence = CapturedRuntimeEvidence | UnavailableRuntimeEvidence;
+export declare function captureRuntimeEvidence(input: RuntimeEvidenceInput): RuntimeEvidence;
+export type EnvironmentComparison = {
+    readonly verdict: 'stable';
+    readonly processIdentity: 'unchanged';
+    readonly contentHash: 'unchanged';
+    readonly diagnostics: readonly [];
+} | {
+    readonly verdict: 'void';
+    readonly processIdentity: 'unchanged' | 'moved';
+    readonly contentHash: 'unchanged' | 'moved';
+    readonly diagnostics: readonly EnvironmentDiagnostic[];
+} | {
+    readonly verdict: 'stale' | 'unavailable';
+    readonly diagnostics: readonly EnvironmentDiagnostic[];
+};
+export declare function compareEnvironmentSnapshot(rawSnapshot: EnvironmentSnapshot, rawBefore: RuntimeEvidence, rawAfter: RuntimeEvidence): EnvironmentComparison;
+export declare function isRuntimeEvidenceAuthentic(rawEvidence: CapturedRuntimeEvidence): boolean;
+export {};