@b00dea/cockpit 0.0.0-bootstrap.0 → 0.1.0

package/dist/environment/posture-observation.d.ts

@@ -0,0 +1,68 @@
+import { type AddressingPosture, type AuthPosture } from '../schema.js';
+import { type CockpitId, type EnvironmentObservation, type JsonSnapshot, type StackId } from './contract.js';
+import { type StackVariant } from './identity.js';
+import { type LifecycleStageAuthority } from './lifecycle-stage.js';
+/** The owner of the posture-requirement checks preflight derives from the declared postures. */
+export declare const POSTURE_REQUIREMENT_OWNER = "posture-requirements";
+export interface ResolvedPostureAuthority {
+    readonly stackId: StackId;
+    readonly evaluatedAt: string;
+    readonly validThrough: string;
+    readonly revision: string;
+    readonly source: string;
+    readonly postures: readonly string[];
+    readonly environmentPostures: Readonly<{
+        addressing: AddressingPosture | null;
+        authentication: AuthPosture | null;
+    }>;
+    readonly postureRequirements: readonly Readonly<{
+        requirement: string;
+        addressing?: AddressingPosture;
+        authentication?: AuthPosture;
+    }>[];
+}
+interface ObservationPostureInput {
+    readonly configuration: EnvironmentObservation;
+    readonly cockpitId: CockpitId;
+    readonly checkoutPath: string;
+    readonly variant: StackVariant;
+}
+export declare function resolveObservationPostures(input: ObservationPostureInput): Promise<ResolvedPostureAuthority>;
+export declare function refreshObservationPostures(input: ObservationPostureInput & {
+    readonly previous: ResolvedPostureAuthority;
+}): Promise<ResolvedPostureAuthority>;
+export interface PreflightContext {
+    readonly authorities: readonly ResolvedPostureAuthority[];
+    readonly stages: readonly LifecycleStageAuthority[];
+}
+interface PostureRequirementCheck {
+    readonly code: EnvironmentObservation['code'];
+    readonly owner: string;
+    readonly stackId: StackId;
+    readonly source: string;
+    readonly verdict: 'pass' | 'fail';
+    readonly reason: string;
+    readonly remedy: string;
+    readonly observedAt: string;
+    readonly measured?: JsonSnapshot;
+    readonly expected: EnvironmentObservation['expectation'];
+}
+export type PostureDimension = 'addressing' | 'authentication';
+/**
+ * Whether each selected posture is named by the requirements that depend on it, and every tag agrees.
+ * Preflight gates on this; init applies it to an operator's posture answer so a draft that can never
+ * pass preflight is refused while the operator is still answering.
+ */
+export declare function judgePostureDeclaration(postures: ResolvedPostureAuthority['environmentPostures'], requirements: ResolvedPostureAuthority['postureRequirements']): readonly Readonly<{
+    dimension: PostureDimension;
+    selected: AddressingPosture | AuthPosture | null;
+    pass: boolean;
+    reason: string;
+}>[];
+export declare function authenticateObservationPostureContext(context: PreflightContext): {
+    evaluationInstant: number;
+    authorities: Map<StackId, ResolvedPostureAuthority>;
+    stages: Map<StackId, "bootstrap" | "steady">;
+    checks: PostureRequirementCheck[];
+};
+export {};

package/dist/environment/posture-observation.js

@@ -0,0 +1,253 @@
+// Owns current configuration posture and lifecycle context authentication for health and browser use.
+// Keeps producer declarations and verdict aggregation in observations.ts so browser preparation cannot
+// depend on the generated publication it is preparing.
+import { createHash } from 'node:crypto';
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync } from 'node:fs';
+import { realpath } from 'node:fs/promises';
+import { dirname, isAbsolute, normalize, relative, sep } from 'node:path';
+import { loadCockpitConfig } from '../config/load.js';
+import { STRUCTURED_INPUT_ENTRY_LIMIT } from '../schema.js';
+import { ENVIRONMENT_CODES, errorCause, snapshotJson, RefusalError } from './contract.js';
+import { checkoutId, stackId as deriveStackId } from './identity.js';
+import { authenticateLifecycleStageAuthority } from './lifecycle-stage.js';
+import { isStateObservation } from './state.js';
+/** The owner of the posture-requirement checks preflight derives from the declared postures. */
+export const POSTURE_REQUIREMENT_OWNER = 'posture-requirements';
+const compareCodeUnits = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+function boundedArray(value) {
+    return Array.isArray(value) && value.length <= STRUCTURED_INPUT_ENTRY_LIMIT ? value : undefined;
+}
+const issuedPostureAuthorities = new WeakMap();
+const postureRefreshWindows = new WeakMap();
+const POSTURE_AUTHORITY_LIFETIME_MS = 30_000;
+const PREFLIGHT_OBSERVATION_WINDOW_MS = 300_000;
+const CONFIGURATION_BYTE_LIMIT = 1_048_576;
+function currentConfigurationRevision(path) {
+    let descriptor;
+    try {
+        const before = lstatSync(path, { bigint: true });
+        if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1n || before.size > BigInt(CONFIGURATION_BYTE_LIMIT))
+            return undefined;
+        descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        const opened = fstatSync(descriptor, { bigint: true });
+        if (!opened.isFile() || opened.nlink !== 1n || opened.dev !== before.dev || opened.ino !== before.ino
+            || opened.size > BigInt(CONFIGURATION_BYTE_LIMIT))
+            return undefined;
+        const hash = createHash('sha256');
+        const buffer = Buffer.allocUnsafe(65_536);
+        let total = 0;
+        while (true) {
+            const count = readSync(descriptor, buffer, 0, Math.min(buffer.length, CONFIGURATION_BYTE_LIMIT - total + 1), null);
+            if (count === 0)
+                break;
+            total += count;
+            if (total > CONFIGURATION_BYTE_LIMIT)
+                return undefined;
+            hash.update(buffer.subarray(0, count));
+        }
+        const after = fstatSync(descriptor, { bigint: true });
+        const named = lstatSync(path, { bigint: true });
+        if (!named.isFile() || named.isSymbolicLink() || named.dev !== opened.dev || named.ino !== opened.ino
+            || after.dev !== opened.dev || after.ino !== opened.ino || after.size !== opened.size || named.size !== opened.size
+            || after.mtimeNs !== opened.mtimeNs || after.ctimeNs !== opened.ctimeNs || total !== Number(opened.size))
+            return undefined;
+        return hash.digest('hex');
+    }
+    catch (error) {
+        throw new RefusalError(`configuration could not be re-read after posture resolution: ${errorCause(error)}`);
+    }
+    finally {
+        if (descriptor !== undefined) {
+            try {
+                closeSync(descriptor);
+            }
+            catch { /* A failed identity check grants no authority. */ }
+        }
+    }
+}
+async function issueObservationPostures(input, previous) {
+    const configuration = input?.configuration;
+    const owned = snapshotJson({ cockpitId: input.cockpitId, checkoutPath: input.checkoutPath, variant: input.variant });
+    const identity = owned && typeof owned === 'object' && !Array.isArray(owned)
+        ? owned
+        : undefined;
+    let expectedStackId;
+    let canonicalCheckoutPath;
+    try {
+        if (!identity || typeof identity.cockpitId !== 'string' || typeof identity.checkoutPath !== 'string'
+            || normalize(identity.checkoutPath) !== identity.checkoutPath)
+            throw new RefusalError('invalid identity');
+        canonicalCheckoutPath = await realpath(identity.checkoutPath);
+        expectedStackId = deriveStackId({
+            cockpitId: identity.cockpitId,
+            checkoutId: checkoutId({ checkoutPath: canonicalCheckoutPath }),
+            variant: identity.variant,
+        });
+    }
+    catch {
+        throw new RefusalError('resolved posture configuration source is malformed');
+    }
+    const issuedAt = Date.now();
+    const observedAt = configuration && typeof configuration === 'object'
+        && 'observed' in configuration && configuration.observed.state === 'available'
+        ? Date.parse(configuration.observed.observedAt)
+        : Number.NaN;
+    if (!isStateObservation(configuration)
+        || configuration.code !== ENVIRONMENT_CODES.CONFIG_STALE
+        || configuration.observed.state !== 'available'
+        || configuration.stackId !== expectedStackId
+        || observedAt > issuedAt
+        || issuedAt - observedAt > 30_000) {
+        throw new RefusalError('resolved posture configuration source is malformed');
+    }
+    const configurationRoot = relative(canonicalCheckoutPath, dirname(configuration.source));
+    if (configurationRoot === '..' || configurationRoot.startsWith(`..${sep}`) || isAbsolute(configurationRoot)) {
+        throw new RefusalError('resolved posture configuration source is malformed');
+    }
+    const loaded = await loadCockpitConfig(configuration.source);
+    if (loaded.kind !== 'complete')
+        throw new RefusalError('resolved posture configuration source is unavailable');
+    if (loaded.result.source.path !== configuration.source || loaded.result.source.sha256 !== configuration.observed.value) {
+        throw new RefusalError('resolved posture configuration changed after observation');
+    }
+    const previousWindow = previous === undefined ? undefined : postureRefreshWindows.get(previous);
+    if (previous !== undefined && (!previousWindow || previousWindow.cockpitId !== identity.cockpitId
+        || previous.stackId !== configuration.stackId || previous.source !== loaded.result.source.path
+        || previous.revision !== loaded.result.source.sha256)) {
+        throw new RefusalError('resolved posture refresh does not match its initial authority');
+    }
+    const evaluatedAt = previous?.evaluatedAt ?? configuration.observed.observedAt;
+    const windowExpiresAt = previousWindow?.expiresAt ?? Date.parse(evaluatedAt) + PREFLIGHT_OBSERVATION_WINDOW_MS;
+    if (!Number.isSafeInteger(windowExpiresAt) || issuedAt > windowExpiresAt) {
+        throw new RefusalError('resolved posture refresh window expired');
+    }
+    const postures = new Set(['environment']);
+    if (loaded.result.config.environment.machine)
+        postures.add('machine-floor');
+    if (loaded.result.config.environment.compose_files.length > 0)
+        postures.add('running-stack');
+    if (loaded.result.config.sibling.some(({ mount }) => mount === 'always'))
+        postures.add('directory-grants');
+    for (const sibling of loaded.result.config.sibling) {
+        if (sibling.mount === 'none')
+            continue;
+        if (sibling.mount === 'host')
+            postures.add('host');
+        else
+            postures.add('mounted');
+    }
+    const authority = {
+        stackId: configuration.stackId,
+        evaluatedAt,
+        validThrough: new Date(Math.min(issuedAt + POSTURE_AUTHORITY_LIFETIME_MS, windowExpiresAt)).toISOString(),
+        revision: loaded.result.source.sha256,
+        source: loaded.result.source.path,
+        postures: [...postures].sort(compareCodeUnits),
+        environmentPostures: {
+            addressing: loaded.result.config.environment.addressing ?? null,
+            authentication: loaded.result.config.environment.authentication ?? null,
+        },
+        postureRequirements: (loaded.result.config.environment.posture_requirements ?? [])
+            .map((requirement) => ({ ...requirement })),
+    };
+    issuedPostureAuthorities.set(authority, identity.cockpitId);
+    postureRefreshWindows.set(authority, Object.freeze({ cockpitId: identity.cockpitId, expiresAt: windowExpiresAt }));
+    return authority;
+}
+export async function resolveObservationPostures(input) {
+    return issueObservationPostures(input);
+}
+export async function refreshObservationPostures(input) {
+    const previous = input?.previous;
+    if (!previous)
+        throw new RefusalError('resolved posture refresh requires initial authority');
+    return issueObservationPostures(input, previous);
+}
+/**
+ * Whether each selected posture is named by the requirements that depend on it, and every tag agrees.
+ * Preflight gates on this; init applies it to an operator's posture answer so a draft that can never
+ * pass preflight is refused while the operator is still answering.
+ */
+export function judgePostureDeclaration(postures, requirements) {
+    return ['addressing', 'authentication'].map((dimension) => {
+        const selected = postures[dimension];
+        const tagged = requirements.filter((requirement) => requirement[dimension] !== undefined);
+        // A stack with no sign-in has nothing that depends on one, so it needs no tagged requirement.
+        const untaggedNone = selected === 'none' && tagged.length === 0 && requirements.length > 0;
+        const matched = selected !== null && tagged.some((requirement) => requirement[dimension] === selected);
+        const pass = untaggedNone || matched && tagged.every((requirement) => requirement[dimension] === selected);
+        const reason = selected === null
+            ? `${dimension} posture is not declared`
+            : requirements.length === 0
+                ? 'posture requirement catalog is not declared'
+                : untaggedNone ? 'no authentication is declared, and no requirement depends on one'
+                    : tagged.length === 0
+                        ? `${dimension} posture ${selected} is not named by a requirement`
+                        : !pass ? `${dimension} requirement tags do not match selected posture ${selected}`
+                            : 'declared requirement tags match the selected posture';
+        return { dimension, selected, pass, reason };
+    });
+}
+export function authenticateObservationPostureContext(context) {
+    const evaluationInstant = Date.now();
+    const authorityInputs = boundedArray(context?.authorities);
+    const stageInputs = boundedArray(context?.stages);
+    if (!authorityInputs || authorityInputs.length === 0)
+        throw new RefusalError('preflight needs resolved posture authority');
+    const authorities = new Map();
+    let windowStart = Number.NEGATIVE_INFINITY;
+    let windowEnd = Number.POSITIVE_INFINITY;
+    for (const authorityInput of authorityInputs) {
+        const authority = authorityInput;
+        const cockpitId = issuedPostureAuthorities.get(authority);
+        if (!cockpitId)
+            throw new RefusalError('preflight needs resolved posture authority');
+        if (authorities.has(authority.stackId))
+            throw new RefusalError('preflight contains duplicate posture authority');
+        const currentRevision = currentConfigurationRevision(authority.source);
+        if (currentRevision !== authority.revision)
+            throw new RefusalError('configuration changed after posture resolution');
+        const authorityStart = Date.parse(authority.evaluatedAt);
+        const authorityEnd = Date.parse(authority.validThrough);
+        if (!Number.isFinite(authorityStart) || !Number.isFinite(authorityEnd) || authorityStart > authorityEnd)
+            throw new RefusalError('preflight posture authorities are incoherent');
+        if (evaluationInstant > authorityEnd)
+            throw new RefusalError('preflight posture authority has expired');
+        authorities.set(authority.stackId, authority);
+        windowStart = Math.max(windowStart, authorityStart);
+        windowEnd = Math.min(windowEnd, authorityEnd);
+    }
+    if (windowStart > windowEnd)
+        throw new RefusalError('preflight posture authorities are incoherent');
+    if (!stageInputs || stageInputs.length !== authorityInputs.length)
+        throw new RefusalError('preflight needs lifecycle stage authority');
+    const stages = new Map();
+    for (const stageInput of stageInputs) {
+        if (stageInput === null || typeof stageInput !== 'object')
+            throw new RefusalError('preflight needs lifecycle stage authority');
+        const stageStackId = stageInput.stackId;
+        const authority = typeof stageStackId === 'string' ? authorities.get(stageStackId) : undefined;
+        if (!authority || stages.has(authority.stackId))
+            throw new RefusalError('preflight needs one matching lifecycle stage authority per stack');
+        const stage = authenticateLifecycleStageAuthority(stageInput, authority.stackId, issuedPostureAuthorities.get(authority), Date.parse(authority.evaluatedAt), Date.parse(authority.validThrough), evaluationInstant);
+        if (!stage)
+            throw new RefusalError('preflight needs authentic lifecycle stage authority');
+        stages.set(authority.stackId, stage);
+    }
+    if (stages.size !== authorities.size)
+        throw new RefusalError('preflight needs one matching lifecycle stage authority per stack');
+    const postureChecks = [...authorities.values()].flatMap((authority) => judgePostureDeclaration(authority.environmentPostures, authority.postureRequirements).map(({ dimension, selected, pass, reason }) => ({
+        code: ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE,
+        owner: POSTURE_REQUIREMENT_OWNER,
+        stackId: authority.stackId,
+        source: `${authority.source}:${dimension}`,
+        verdict: pass ? 'pass' : 'fail',
+        reason,
+        remedy: `declare ${dimension} and tag every dependent requirement with the same posture`,
+        observedAt: authority.evaluatedAt,
+        ...(selected === null ? {} : { measured: selected }),
+        expected: { kind: 'present' },
+    })));
+    return { evaluationInstant, authorities, stages,
+        checks: postureChecks };
+}

package/dist/environment/read-composition.d.ts

@@ -0,0 +1,27 @@
+import type { ExecuteProbeOutcome } from '../environment-exec/execute.js';
+import { type RuntimeEvidenceObservation } from './application/health.js';
+import { type LogsCommandAdapters } from './application/logs.js';
+import { type ExecutionStep } from './contract.js';
+import { type RuntimeMeasurementProbeAuthority } from './runtime.js';
+export interface ReadCommandCompositionInput {
+    readonly configPath: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly sessionId: string;
+    readonly timeoutMs: number;
+    readonly outputLimitBytes?: number;
+    readonly signal?: AbortSignal;
+    readonly runtimeMeasurementProbeAuthority?: RuntimeMeasurementProbeAuthority;
+}
+export interface ReadCommandAdapterComposition {
+    readonly logs: LogsCommandAdapters;
+    readonly environment: Readonly<{
+        observe: (input: {
+            readonly configPath: string;
+        }) => Promise<RuntimeEvidenceObservation>;
+    }>;
+}
+type Executor = (step: ExecutionStep, options?: {
+    readonly signal?: AbortSignal;
+}) => Promise<ExecuteProbeOutcome>;
+export declare function createReadCommandAdapters(rawInput: ReadCommandCompositionInput, execute: Executor): ReadCommandAdapterComposition;
+export {};