@b00dea/cockpit 0.0.0-bootstrap.0 → 0.1.0

package/dist/environment/codex-hook-trust.d.ts

@@ -0,0 +1,11 @@
+import type { EnvironmentDiagnostic } from './contract.js';
+export interface CodexHookTrustInput {
+    readonly root: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * A warning when Codex will skip the generated guard hook on this machine, or when that cannot be
+ * verified; nothing when every hook is trusted, no Codex hook is published, or Codex has never run
+ * as this user.
+ */
+export declare function inspectCodexHookTrust(input: CodexHookTrustInput): Promise<readonly EnvironmentDiagnostic[]>;

package/dist/environment/codex-hook-trust.js

@@ -0,0 +1,185 @@
+// Owns the read-only check of whether Codex will run cockpit's generated guard hook on this machine.
+// Codex 0.165.0 skips a project hook until a person trusts it, and says nothing about the skip: a
+// measured `codex exec` ran a push the guard refuses once the hook was trusted. Codex records trust
+// per user as `[hooks.state."<hooks.json path>:<event>:<group>:<handler>"] trusted_hash`, the SHA-256
+// of a normalized hook identity, so this module recomputes that identity from the published
+// hooks.json and compares. It never writes Codex's configuration and never reports a value from it;
+// anything it cannot read or reproduce is reported as unverified, not as trusted.
+import { createHash } from 'node:crypto';
+import { readFile, realpath, stat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { parse as parseToml, TomlError } from 'smol-toml';
+import { RefusalError, tryParseJson, errorCause, hasErrorCode } from './contract.js';
+const HOOKS_PATH = '.codex/hooks.json';
+const MAX_FILE_BYTES = 4 * 1024 * 1024;
+// Codex's event keys. Events it runs without a matcher drop the matcher from the identity; the
+// session-end and interrupt events normalize their timeout differently and are left unverified.
+const EVENT_KEYS = Object.freeze({
+    PreToolUse: 'pre_tool_use', PermissionRequest: 'permission_request', PostToolUse: 'post_tool_use',
+    PreCompact: 'pre_compact', PostCompact: 'post_compact', SessionStart: 'session_start',
+    SubagentStart: 'subagent_start', SubagentStop: 'subagent_stop', UserPromptSubmit: 'user_prompt_submit', Stop: 'stop',
+});
+const MATCHERLESS = new Set(['user_prompt_submit', 'stop']);
+const HANDLER_KEYS = new Set(['type', 'command', 'commandWindows', 'timeout', 'async', 'statusMessage']);
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function sorted(value) {
+    if (Array.isArray(value))
+        return value.map(sorted);
+    if (!record(value))
+        return value;
+    return Object.fromEntries(Object.keys(value).sort().map(key => [key, sorted(value[key])]));
+}
+/** The hooks Codex discovers in a hooks.json, keyed and hashed as Codex 0.165.0 does, or why not. */
+function codexHooks(bytes) {
+    const parsed = tryParseJson(bytes);
+    if (parsed === undefined)
+        return 'its hooks.json is not JSON';
+    if (!record(parsed) || !record(parsed.hooks))
+        return 'its hooks.json has no hooks object';
+    const hooks = [];
+    for (const [event, groups] of Object.entries(parsed.hooks)) {
+        const key = EVENT_KEYS[event];
+        if (!key)
+            return `its hooks.json declares the ${event} event, whose trust identity cockpit does not reproduce`;
+        if (!Array.isArray(groups))
+            return `its ${event} entry is not a list`;
+        for (const [groupIndex, group] of groups.entries()) {
+            if (!record(group) || !Array.isArray(group.hooks) || group.matcher !== undefined && typeof group.matcher !== 'string') {
+                return `its ${event} group ${groupIndex} is malformed`;
+            }
+            for (const [handlerIndex, handler] of group.hooks.entries()) {
+                if (!record(handler) || handler.type !== 'command' || typeof handler.command !== 'string'
+                    || Object.keys(handler).some(name => !HANDLER_KEYS.has(name))
+                    || handler.timeout !== undefined && !Number.isSafeInteger(handler.timeout)
+                    || handler.async !== undefined && typeof handler.async !== 'boolean'
+                    || handler.statusMessage !== undefined && typeof handler.statusMessage !== 'string') {
+                    return `its ${event} hook ${groupIndex}:${handlerIndex} has a shape whose trust identity cockpit does not reproduce`;
+                }
+                // Codex hashes the handler after normalizing it: the timeout defaults to ten minutes and
+                // the Windows command is dropped on other systems.
+                const normalized = {
+                    type: 'command', command: handler.command, timeout: Math.max(1, handler.timeout ?? 600),
+                    async: handler.async ?? false, ...(handler.statusMessage === undefined ? {} : { statusMessage: handler.statusMessage }),
+                };
+                const identity = { event_name: key, hooks: [normalized],
+                    ...(group.matcher === undefined || MATCHERLESS.has(key) ? {} : { matcher: group.matcher }) };
+                hooks.push({ suffix: `${key}:${groupIndex}:${handlerIndex}`,
+                    hash: `sha256:${createHash('sha256').update(JSON.stringify(sorted(identity))).digest('hex')}` });
+            }
+        }
+    }
+    return hooks;
+}
+async function bounded(path) {
+    try {
+        const bytes = await readFile(path);
+        if (bytes.byteLength > MAX_FILE_BYTES)
+            throw new RefusalError(`${path} exceeds ${MAX_FILE_BYTES} bytes`);
+        return bytes.toString('utf8');
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT'))
+            return 'missing';
+        throw error;
+    }
+}
+function trustFor(states, source, hooks) {
+    let trust = 'trusted';
+    for (const hook of hooks) {
+        const state = states[`${source}:${hook.suffix}`];
+        if (!record(state) || state.trusted_hash === undefined)
+            return 'untrusted';
+        if (state.enabled === false)
+            trust = 'disabled';
+        else if (state.trusted_hash !== hook.hash && trust === 'trusted')
+            trust = 'modified';
+    }
+    return trust;
+}
+function warning(message) {
+    return {
+        severity: 'warning',
+        // Code and fix are literals, so the diagnostic inventory captures the fix beside the code and
+        // the troubleshooting index repeats it. The message names the hook's path, and the printed
+        // fix binds the configuration placeholder to the resolved path.
+        code: 'CODEX_HOOK_UNTRUSTED',
+        message,
+        target: HOOKS_PATH,
+        fix: 'if you use Codex in this cockpit, a person runs codex -C <cockpit root> in a terminal (not codex exec), trusts the folder if asked, and chooses "Trust all and continue" when Codex shows "Hooks need review" (or enables and trusts the hook in its /hooks view); then run npx --no cockpit doctor --config <your cockpit.toml>',
+    };
+}
+/**
+ * A warning when Codex will skip the generated guard hook on this machine, or when that cannot be
+ * verified; nothing when every hook is trusted, no Codex hook is published, or Codex has never run
+ * as this user.
+ */
+export async function inspectCodexHookTrust(input) {
+    const root = resolve(input.root);
+    const hooksPath = join(root, HOOKS_PATH);
+    const unverified = (reason) => [warning(`cockpit could not verify whether Codex trusts the guard hook in ${hooksPath} (${reason}); Codex skips a project hook until a person trusts it, and then runs tool calls without the guard`)];
+    let hooksBytes;
+    try {
+        hooksBytes = await bounded(hooksPath);
+    }
+    catch (error) {
+        return unverified(`reading it failed: ${errorCause(error)}`);
+    }
+    if (hooksBytes === 'missing')
+        return [];
+    const hooks = codexHooks(hooksBytes);
+    if (typeof hooks === 'string')
+        return unverified(hooks);
+    if (hooks.length === 0)
+        return [];
+    const home = input.env.CODEX_HOME || (input.env.HOME ? join(input.env.HOME, '.codex') : undefined);
+    if (!home)
+        return unverified('neither CODEX_HOME nor HOME is set, so Codex\'s configuration cannot be found');
+    // Every cockpit publishes the Codex hook, so a person who never runs Codex here saw this warning on
+    // every check. Codex creates its home on first run; without one no Codex session can skip the hook.
+    try {
+        await stat(home);
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT'))
+            return [];
+        return unverified(`reading ${home} failed: ${errorCause(error)}`);
+    }
+    const codexConfig = join(home, 'config.toml');
+    let states = {};
+    try {
+        const bytes = await bounded(codexConfig);
+        if (bytes !== 'missing') {
+            const parsed = parseToml(bytes);
+            const recorded = record(parsed.hooks) ? parsed.hooks.state : undefined;
+            if (recorded !== undefined && !record(recorded))
+                return unverified(`hooks.state in ${codexConfig} is not a table`);
+            states = recorded ?? {};
+        }
+    }
+    catch (error) {
+        // smol-toml quotes the lines around a syntax error, and Codex's configuration can hold
+        // credentials, so only the position is reported.
+        if (error instanceof TomlError)
+            return unverified(`${codexConfig} is not valid TOML at line ${error.line}, column ${error.column}`);
+        return unverified(`reading ${codexConfig} failed: ${errorCause(error)}`);
+    }
+    // Codex keys trust by the hooks.json path as the session directory spells it, which may or may
+    // not resolve symbolic links, so trust recorded under either spelling counts.
+    let canonical = root;
+    try {
+        canonical = await realpath(root);
+    }
+    catch (error) {
+        return unverified(`resolving ${root} failed: ${errorCause(error)}`);
+    }
+    const results = [...new Set([hooksPath, join(canonical, HOOKS_PATH)])].map(source => trustFor(states, source, hooks));
+    if (results.includes('trusted'))
+        return [];
+    const consequence = 'a Codex session started there skips it and runs tool calls without the guard';
+    const message = results.includes('disabled') ? `the guard hook in ${hooksPath} is disabled in ${codexConfig}, so ${consequence}`
+        : results.includes('modified') ? `Codex trusted an earlier version of the guard hook in ${hooksPath}; until a person trusts the current one, ${consequence}`
+            : `Codex has not trusted the guard hook in ${hooksPath} on this machine, so ${consequence}`;
+    return [warning(message)];
+}

package/dist/environment/compose-environment.d.ts

@@ -0,0 +1 @@
+export declare function composeProcessEnvironment(env: Readonly<Record<string, string>>): Readonly<Record<string, string>>;

package/dist/environment/compose-environment.js

@@ -0,0 +1,6 @@
+// Compose process environments are completed here after their owning boundary has rejected
+// caller-supplied COMPOSE_* values. The fixed value prevents unauthenticated project .env bytes
+// from changing an authenticated plan while leaving service env_file loading available at runtime.
+export function composeProcessEnvironment(env) {
+    return { ...env, COMPOSE_DISABLE_ENV_FILE: '1' };
+}

package/dist/environment/compose-ownership.d.ts

@@ -0,0 +1,21 @@
+/** Published beside cockpit.toml; the cockpit's own Compose files are passed first. */
+export declare const COMPOSE_OWNERSHIP_FILE = "compose.cockpit.yml";
+export type ComposeOwnershipRender = Readonly<{
+    kind: 'complete';
+    bytes: string;
+}> | Readonly<{
+    kind: 'refusal';
+    reason: string;
+    target: string;
+}>;
+export declare function renderComposeOwnership(input: Readonly<{
+    sources: readonly Readonly<{
+        reference: string;
+        source: string;
+    }>[];
+    stackId: string;
+    cockpitId: string;
+    configSha256: string;
+    /** `environment.resettable_volumes`: each must name a volume these files create. */
+    resettableVolumes: readonly string[];
+}>): ComposeOwnershipRender;

package/dist/environment/compose-ownership.js

@@ -0,0 +1,117 @@
+// Renders the Compose override that gives a compose-first cockpit's own services, the images they
+// build, default network and named volumes the ownership labels runtime admission and reclaim read.
+// The cockpit's Compose files stay untouched: `sync` publishes this override as an owned file and
+// `check` drift-checks it like any other, and runtime readiness passes it as the last `--file` only
+// when its bytes equal a fresh render of the current Compose files and identity. It parses YAML only to list service and
+// volume names; what Compose resolves from the files belongs to compose-topology.ts.
+import { createHash } from 'node:crypto';
+import { parseDocument, stringify } from 'yaml';
+/** Published beside cockpit.toml; the cockpit's own Compose files are passed first. */
+export const COMPOSE_OWNERSHIP_FILE = 'compose.cockpit.yml';
+const SERVICE_ID = /^[a-z0-9][a-z0-9_.-]*$/;
+const VOLUME_ID = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/;
+const SOURCE_LIMIT_BYTES = 1_048_576;
+export function renderComposeOwnership(input) {
+    const services = new Set();
+    const built = new Set();
+    // Each owned volume and the labels its own files already declare, as KEY -> value.
+    const volumes = new Map();
+    const external = new Set();
+    for (const { reference, source } of input.sources) {
+        const refuse = (reason) => ({ kind: 'refusal', reason, target: reference });
+        if (Buffer.byteLength(source) > SOURCE_LIMIT_BYTES)
+            return refuse('the Compose file exceeds 1 MiB');
+        const document = parseDocument(source, { merge: true });
+        if (document.errors.length > 0)
+            return refuse(`the Compose file is not valid YAML: ${document.errors[0].message.split('\n', 1)[0]}`);
+        const root = document.toJS({ maxAliasCount: 100 });
+        if (root === null || typeof root !== 'object' || Array.isArray(root))
+            return refuse('the Compose file is not a mapping');
+        const record = root;
+        // An included file declares services this file cannot name, so they would run unlabelled, and
+        // Compose reads it from disk rather than from the snapshot cockpit verified.
+        if (record.include !== undefined)
+            return refuse('`include` is not supported, because Compose reads an included file outside the bytes cockpit verifies and labels; list the file in environment.compose_files instead, where relative paths in every listed file resolve against the first file\'s directory');
+        if (record.volumes !== undefined) {
+            if (record.volumes === null || typeof record.volumes !== 'object' || Array.isArray(record.volumes))
+                return refuse('`volumes` is not a mapping');
+            for (const [id, declaration] of Object.entries(record.volumes)) {
+                if (!VOLUME_ID.test(id))
+                    return refuse(`volume name ${JSON.stringify(id)} is not a Compose volume identifier`);
+                // An external volume is created outside this stack, and Compose refuses labels on one.
+                const record = declaration !== null && typeof declaration === 'object' && !Array.isArray(declaration)
+                    ? declaration : undefined;
+                if (record?.external) {
+                    external.add(id);
+                    continue;
+                }
+                const declared = volumes.get(id) ?? new Map();
+                const labels = record?.labels;
+                if (Array.isArray(labels)) {
+                    for (const entry of labels)
+                        if (typeof entry === 'string' && entry.includes('='))
+                            declared.set(entry.slice(0, entry.indexOf('=')), entry.slice(entry.indexOf('=') + 1));
+                }
+                else if (labels !== null && typeof labels === 'object') {
+                    for (const [key, value] of Object.entries(labels))
+                        declared.set(key, String(value));
+                }
+                volumes.set(id, declared);
+            }
+        }
+        if (record.services === undefined)
+            continue;
+        if (record.services === null || typeof record.services !== 'object' || Array.isArray(record.services))
+            return refuse('`services` is not a mapping');
+        for (const [id, declaration] of Object.entries(record.services)) {
+            if (!SERVICE_ID.test(id))
+                return refuse(`service name ${JSON.stringify(id)} is not a Compose service identifier`);
+            services.add(id);
+            if (declaration !== null && typeof declaration === 'object' && !Array.isArray(declaration)
+                && declaration.build !== undefined)
+                built.add(id);
+        }
+    }
+    // Reset matches a declared name against the Compose volume key, so a name these files do not
+    // create would reset nothing while reading as a control.
+    for (const name of input.resettableVolumes) {
+        if (volumes.has(name))
+            continue;
+        const declared = [...volumes.keys()].sort();
+        return {
+            kind: 'refusal',
+            target: 'environment.resettable_volumes',
+            reason: external.has(name)
+                ? `resettable volume ${JSON.stringify(name)} is external: Compose does not create it, so cockpit cannot label it as this stack's own and reset could never remove it`
+                : `resettable volume ${JSON.stringify(name)} is not a top-level volume in environment.compose_files${declared.length === 0 ? '' : ` (declared: ${declared.join(', ')})`}`,
+        };
+    }
+    const labels = {
+        'dev.b0dea.cockpit.config-sha256': input.configSha256,
+        'dev.b0dea.cockpit.owner-id': '${COCKPIT_OWNER_ID:?cockpit runtime owner identity is unavailable}',
+        'dev.b0dea.cockpit.stack-id': '${COCKPIT_STACK_ID:?cockpit runtime stack identity is unavailable}',
+    };
+    const generation = createHash('sha256').update(`compose-volume-generation\0${input.configSha256}`).digest('hex');
+    // Compose 5.5 refuses to merge a volume label the earlier file already sets to the same value
+    // ("labels must be a mapping"), so a label a volume already carries is not repeated, and a
+    // volume that carries them all needs no entry. Services and networks merge them fine.
+    const volumeLabels = [...volumes].sort(([left], [right]) => left.localeCompare(right)).flatMap(([id, declared]) => {
+        const missing = Object.entries({ ...labels, 'dev.b0dea.cockpit.generation-id': generation })
+            .filter(([key, value]) => declared.get(key) !== value);
+        return missing.length === 0 ? [] : [[id, { labels: Object.fromEntries(missing) }]];
+    });
+    const body = stringify({
+        // A built image carries the set as well, or `down` left every image the stack built. Only a
+        // service that declares `build` gets one: a build section on a pulled image makes Compose build it.
+        services: Object.fromEntries([...services].sort().map((id) => [id, built.has(id) ? { labels, build: { labels } } : { labels }])),
+        // The default network carries the same set, so `down` can remove the network it created.
+        networks: { default: { labels } },
+        // Reset admits a data-bearing volume only with exact ownership and a generation;
+        // unlabelled, a declared resettable volume was unreachable.
+        ...(volumeLabels.length === 0 ? {} : { volumes: Object.fromEntries(volumeLabels) }),
+    }, { aliasDuplicateObjects: false });
+    return {
+        kind: 'complete',
+        bytes: `# Generated by cockpit sync from environment.compose_files: ownership labels only. Do not edit.\n${body}`,
+    };
+}

package/dist/environment/compose-topology.d.ts

@@ -0,0 +1,117 @@
+import { type ExecuteProbeOutcome } from '../environment-exec/execute.js';
+import { type Diagnostic, type ExecutionStep } from './contract.js';
+import type { ResolvedExecutable } from './executable.js';
+/**
+ * The directory every relative path in a cockpit's own Compose files resolves against: the first
+ * file's, as `docker compose -f first.yml -f second.yml` takes it. Compose cannot default it itself
+ * because it reads snapshots of the files, and the cockpit root is the wrong default: a product
+ * repository's Compose file names `./api` relative to the repository.
+ */
+export declare function composeProjectDirectory(root: string, references: readonly string[]): string;
+export interface ComposeTopologyInput {
+    /** Canonical absolute cockpit root. */
+    readonly root: string;
+    /** The declared `environment.compose_files`, relative to `root`. */
+    readonly references: readonly string[];
+    readonly projectName: string;
+    readonly docker: ResolvedExecutable;
+    /** Reads the declared files through the anchored reader, so the probe consumes authenticated bytes. */
+    readonly node: ResolvedExecutable;
+    /** Filtered to the Docker connection variables before it reaches the probe. */
+    readonly env: Readonly<Record<string, string | undefined>>;
+}
+export interface ComposePublishedPort {
+    /** The host side exactly as written, `null` when Compose picks an ephemeral host port. */
+    readonly published: string | null;
+    /** The host interface exactly as written, `null` when none is given, so Docker binds every interface. */
+    readonly hostIp: string | null;
+    readonly target: string;
+}
+export interface ComposeServiceTopology {
+    readonly id: string;
+    readonly ports: readonly ComposePublishedPort[];
+    readonly healthcheck: boolean;
+    readonly image: string | null;
+    readonly build: boolean;
+    /**
+     * Each volume source as Compose reports it without interpolation: the absolute host path of a
+     * bind, or the raw `${VAR}` text of a source still waiting for its variable.
+     */
+    readonly mountSources: readonly string[];
+}
+/** A `[[sibling]]` row as the mount detector needs it: its absolute checkout path and variable. */
+export interface ComposeSiblingMount {
+    readonly slug: string;
+    readonly var: string;
+    readonly mount: string;
+    readonly path: string;
+}
+export type ComposeTopologyObservation = Readonly<{
+    kind: 'complete';
+    services: readonly ComposeServiceTopology[];
+}> | Readonly<{
+    kind: 'unavailable';
+    reason: string;
+}>;
+/**
+ * Splits a Compose short-syntax entry (`[ip:]host:container[/proto]`, `source:target[:mode]`) on
+ * its colons. Variable references and bracketed IPv6 addresses are kept whole so their colons do
+ * not split the entry; an unbalanced one returns `undefined`.
+ */
+export declare function splitComposeShort(value: string): readonly string[] | undefined;
+/** A service's raw `ports` entries, short or long form, or undefined when one cannot be read. */
+export declare function composePublishedPorts(rawPorts?: unknown): readonly ComposePublishedPort[] | undefined;
+/** Runs Compose's own resolution of the declared files and projects the services it reports. */
+export declare function observeComposeTopology(input: ComposeTopologyInput, execute: (step: ExecutionStep) => Promise<ExecuteProbeOutcome>): Promise<ComposeTopologyObservation>;
+export declare function variableName(value: string): string | undefined;
+/**
+ * Where a volume's host side lands, read from its source as written or as Compose reports it
+ * uninterpolated; a relative path resolves against `directory`, the Compose project directory.
+ * `variables` are the values cockpit hands Compose (the sibling directories); any other variable
+ * resolves to its own default, as it does in `up`, or cannot be resolved at all. Returns the
+ * absolute host path of a bind, `'volume'` for a named volume, and `undefined` when the host side
+ * cannot be known.
+ */
+export declare function composeBindPath(source: string, directory: string, variables: Readonly<Record<string, string>>): string | 'volume' | undefined;
+/** The deepest declared mount source holding `bind`, or `undefined` when none does. */
+export declare function bindHolder(bind: string, declared: readonly string[]): string | undefined;
+/**
+ * Pairs each bind with the deepest declared mount source holding it. A bind of a directory inside
+ * a mount = "always" checkout (`./api` of the repository) mounts that checkout, so it counts for
+ * it; a bind inside no declared source is undeclared. A declared source is mounted when a bind
+ * lands in it or when an admitted bind holds it: a generated host path inside a checkout bound
+ * whole reaches the container through that bind, and nothing it is declared for (reset deleting
+ * it, the ignore block, the browser writing there) needs a mount of its own. Any other declared
+ * source is missing. Both `check` and `up` judge their binds with this one rule.
+ */
+export declare function compareBindSources(binds: readonly string[], declared: readonly string[]): Readonly<{
+    missing: readonly string[];
+    unexpected: readonly string[];
+}>;
+/**
+ * The binds inside a declared source whose real path leaves it. Containment above is lexical, and
+ * Docker follows a symbolic link in the bind source, so `./api/cache -> /` would otherwise hand
+ * the host root to a container under a mount = "always" checkout.
+ */
+export declare function redirectedBindSources(binds: readonly string[], declared: readonly string[]): Promise<readonly Readonly<{
+    bind: string;
+    holder: string;
+}>[]>;
+export interface ComposeTopologyDeclarations {
+    /** From composeProjectDirectory; a relative bind source, or a variable's relative default, resolves against it. */
+    readonly projectDirectory: string;
+    readonly portVariables: readonly string[];
+    readonly siblings: readonly ComposeSiblingMount[];
+    /** The `environment.generated_host_paths`, as declared and absolute, which `up` hands to containers beside the checkouts. */
+    readonly hostPaths: readonly Readonly<{
+        declared: string;
+        path: string;
+    }>[];
+}
+/**
+ * Judges a cockpit's own Compose topology. A host port that is not drawn from a leased
+ * `ports.bases` variable is the same number in every worktree and parallel stack, so the second
+ * stack to start fails to bind it; the remaining findings are warnings about what cockpit can
+ * then promise, not about whether the stack runs.
+ */
+export declare function assessComposeTopology(services: readonly ComposeServiceTopology[], declarations: ComposeTopologyDeclarations): Promise<readonly Diagnostic[]>;