@b00dea/cockpit 0.0.0-bootstrap.0 → 0.1.0

package/dist/guards/local-identity.js

@@ -0,0 +1,123 @@
+// Owns the machine-local guard identity file: its path, its bytes and how `sync` writes it.
+// Tracked guard bytes must be identical on every clone, so everything that names this machine
+// (Node, the installed cockpit module, root and configuration device and inode numbers) lives here,
+// in a directory that ignores itself. It decides nothing: the guard application authenticates the
+// file against the running process and the published surfaces before any policy is resolved.
+import { exactKeys } from '../exact-keys.js';
+import { randomBytes } from 'node:crypto';
+import { lstat, mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { readBoundedInput } from '../config/load.js';
+import { errorCause, hasErrorCode } from '../environment/contract.js';
+export const GUARD_LOCAL_PATHS = Object.freeze({
+    directory: '.cockpit/local',
+    identity: '.cockpit/local/guard-identity',
+    ignore: '.cockpit/local/.gitignore',
+});
+// The guard script reads this file with `read` one line at a time, so the layout is lines rather
+// than JSON: a format line, the two executables it launches, then the identity the application checks.
+const FORMAT = 'cockpit-guard-local/v1';
+const LOCAL_FILE_MAX_BYTES = 65_536;
+const KEYS = ['root', 'rootDevice', 'rootInode', 'configPath', 'configSha256', 'configDevice', 'configInode',
+    'node', 'nodeSha256', 'nodeFingerprint', 'module', 'moduleSha256'];
+const IGNORE_BYTES = '# cockpit-owned: machine-local files, written by `cockpit sync`, never committed\n*\n';
+export function encodeGuardLocalIdentity(identity) {
+    const ordered = Object.fromEntries(KEYS.map(key => [key, identity[key]]));
+    return `${FORMAT}\n${identity.node}\n${identity.module}\n${JSON.stringify(ordered)}\n`;
+}
+/** The exact identity the bytes carry, or undefined when they are not a complete current-format file. */
+export function parseGuardLocalIdentity(bytes) {
+    const lines = bytes.split('\n');
+    if (lines.length !== 5 || lines[0] !== FORMAT || lines[4] !== '')
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(lines[3]);
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            return undefined; // not the current format
+        throw error;
+    }
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const record = value;
+    if (!exactKeys(record, KEYS) || !KEYS.every(key => typeof record[key] === 'string'))
+        return undefined;
+    const identity = record;
+    return identity.node === lines[1] && identity.module === lines[2] && encodeGuardLocalIdentity(identity) === bytes ? identity : undefined;
+}
+async function observeLocalFile(path) {
+    try {
+        const before = await lstat(path);
+        if (!before.isFile() || before.isSymbolicLink() || before.size > LOCAL_FILE_MAX_BYTES)
+            return { kind: 'invalid' };
+        const read = await readBoundedInput(path);
+        if (read.kind !== 'complete' || read.bytes.length > LOCAL_FILE_MAX_BYTES)
+            return { kind: 'invalid' };
+        const after = await lstat(path);
+        if (!after.isFile() || after.isSymbolicLink() || after.dev !== before.dev || after.ino !== before.ino
+            || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs)
+            return { kind: 'invalid' };
+        return { kind: 'complete', status: after, bytes: read.bytes };
+    }
+    catch (error) {
+        return hasErrorCode(error, 'ENOENT') ? { kind: 'absent' } : { kind: 'invalid' };
+    }
+}
+async function directoryAt(path, create) {
+    try {
+        const status = await lstat(path);
+        return status.isDirectory() && !status.isSymbolicLink() ? undefined : `${path} is not a plain directory`;
+    }
+    catch (error) {
+        if (!hasErrorCode(error, 'ENOENT') || !create)
+            return `${path} is unavailable (${error.code ?? 'unknown error'})`;
+    }
+    await mkdir(path, { mode: 0o700 });
+    return directoryAt(path, false);
+}
+// Rename replaces a planted symlink at the destination instead of writing through it.
+async function replaceFile(directory, name, bytes) {
+    const temporary = join(directory, `.${name}.${randomBytes(8).toString('hex')}.tmp`);
+    try {
+        await writeFile(temporary, bytes, { flag: 'wx', mode: 0o600 });
+        await rename(temporary, join(directory, name));
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+/** Publish the identity after the tracked surfaces it authenticates; the reason names what failed. */
+export async function writeGuardLocalIdentity(root, identity) {
+    return writeCockpitLocalFiles(root, [{ name: 'guard-identity', bytes: encodeGuardLocalIdentity(identity) }]);
+}
+/** Replace machine-local files under `.cockpit/local`, a directory that ignores itself; the reason names what failed. */
+export async function writeCockpitLocalFiles(root, files) {
+    let current = GUARD_LOCAL_PATHS.directory;
+    try {
+        const parent = await directoryAt(join(root, '.cockpit'), false);
+        if (parent)
+            return { kind: 'refusal', message: parent };
+        const directory = join(root, GUARD_LOCAL_PATHS.directory);
+        const local = await directoryAt(directory, true);
+        if (local)
+            return { kind: 'refusal', message: local };
+        current = GUARD_LOCAL_PATHS.ignore;
+        const ignore = join(root, GUARD_LOCAL_PATHS.ignore);
+        const currentIgnore = await observeLocalFile(ignore);
+        if (currentIgnore.kind !== 'complete' || currentIgnore.bytes.toString('utf8') !== IGNORE_BYTES) {
+            await replaceFile(directory, '.gitignore', IGNORE_BYTES);
+        }
+        for (const file of files) {
+            current = `${GUARD_LOCAL_PATHS.directory}/${file.name}`;
+            if (!/^[a-z0-9][a-z0-9-]*$/.test(file.name))
+                return { kind: 'refusal', message: `${current} is not a plain local file name` };
+            await replaceFile(directory, file.name, file.bytes);
+        }
+        return { kind: 'complete' };
+    }
+    catch (error) {
+        return { kind: 'refusal', message: `${current} could not be written (${errorCause(error)})` };
+    }
+}

package/dist/guards/policy-pin.d.ts

@@ -0,0 +1,13 @@
+import type { GuardDecision } from './evaluator.js';
+import type { GuardFileContent, ParsedInvocation } from './invocation-parser.js';
+/**
+ * The denial for a tool call that would change the pinned policy tables, or undefined. `isConfig`
+ * says whether a lexically resolved path is the configuration, by spelling or by file identity.
+ */
+export declare function pinnedPolicyDenial(input: Readonly<{
+    tool: string;
+    cwd: string;
+    content?: GuardFileContent;
+    paths: readonly string[];
+    invocations: readonly ParsedInvocation[];
+}>, current: string, isConfig: (path: string) => boolean): GuardDecision | undefined;

package/dist/guards/policy-pin.js

@@ -0,0 +1,175 @@
+// Owns the guard's pin on the autonomy policy: an agent tool call that would change cockpit.toml's
+// [work] (with [work.gates]) or [autonomy] table, or [mcp] while a person approves MCP servers, is a
+// hard denial. An edit, write or patch is applied to the current text and the tables compared; a
+// shell command that names the file and is not a proven read, a Git record or cockpit's --config
+// operand cannot be applied, so it is denied too.
+// The decision is pure: the guard application supplies the current text and which targets are the
+// configuration under another name.
+import { posix } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { pinnedPolicyTables } from '../autonomy.js';
+import { classifyReadOnlyInvocation, cockpitLauncherPrefix } from './read-only.js';
+const denial = (reason) => ({ decision: 'deny', reason });
+const PINNED = '[work], [work.gates] and [autonomy] (and [mcp] while [autonomy] mcp_approve is not agent)';
+/** Applies one `*** Update File` section of a patch to `text`, or undefined when a hunk does not match exactly once. */
+function applyPatchSection(text, lines) {
+    let result = text;
+    const hunks = [];
+    for (const line of lines) {
+        if (line.startsWith('@@'))
+            hunks.push([]);
+        else if (line !== '*** End of File')
+            (hunks.at(-1) ?? (hunks.push([]), hunks.at(-1))).push(line);
+    }
+    for (const hunk of hunks) {
+        const before = hunk.filter(line => !line.startsWith('+')).map(line => line.slice(1)).join('\n');
+        const after = hunk.filter(line => !line.startsWith('-')).map(line => line.slice(1)).join('\n');
+        const first = result.indexOf(before);
+        if (first < 0 || result.indexOf(before, first + 1) >= 0)
+            return undefined;
+        result = result.slice(0, first) + after + result.slice(first + before.length);
+    }
+    return result;
+}
+function proposedText(content, isConfig, current) {
+    if (content.kind === 'write')
+        return isConfig(content.path) ? content.content : 'untouched';
+    if (content.kind === 'replace') {
+        if (!isConfig(content.path))
+            return 'untouched';
+        if (!content.old)
+            return undefined;
+        const first = current.indexOf(content.old);
+        if (first < 0 || !content.all && current.indexOf(content.old, first + 1) >= 0)
+            return undefined;
+        return content.all ? current.split(content.old).join(content.new) : current.slice(0, first) + content.new + current.slice(first + content.old.length);
+    }
+    const lines = content.text.trimEnd().split('\n').slice(1, -1);
+    let section;
+    let target;
+    let touched = false;
+    let next = current;
+    const flush = () => {
+        if (!section || !target)
+            return true;
+        if (target === 'add') {
+            next = section.map(line => line.slice(1)).join('\n') + '\n';
+            return true;
+        }
+        const applied = applyPatchSection(next, section);
+        if (applied === undefined)
+            return false;
+        next = applied;
+        return true;
+    };
+    for (const line of lines) {
+        const header = /^\*\*\* (Add File|Update File|Delete File|Move to): (.+)$/.exec(line);
+        if (!header) {
+            section?.push(line);
+            continue;
+        }
+        if (!flush())
+            return undefined;
+        section = undefined;
+        target = undefined;
+        if (!isConfig(header[2]))
+            continue;
+        touched = true;
+        // Deleting or moving the configuration is the structural denial's; either way its tables would change.
+        if (header[1] === 'Delete File' || header[1] === 'Move to')
+            return undefined;
+        section = [];
+        target = header[1] === 'Add File' ? 'add' : 'update';
+    }
+    if (!flush())
+        return undefined;
+    return touched ? next : 'untouched';
+}
+const GIT_RECORDING = new Set(['add', 'commit', 'diff', 'log', 'show', 'status', 'blame']);
+// Only the `git` the command search path finds: a path spelled `git` may be any program.
+function recordsWithoutWriting(invocation) {
+    if (invocation.executable !== 'git')
+        return false;
+    const words = invocation.argv;
+    for (let index = 0; index < words.length; index++) {
+        const word = words[index];
+        if (word === '-C' || word === '-c') {
+            index++;
+            continue;
+        }
+        if (word.startsWith('-'))
+            return false;
+        return GIT_RECORDING.has(word);
+    }
+    return false;
+}
+/**
+ * The invocations the pin judges. A cockpit session runs the words after its `--` as a command of
+ * its own, so that command is judged as one more invocation and the session by the words before it.
+ */
+function judgedInvocations(invocations) {
+    const judged = [];
+    const pending = [...invocations];
+    for (let invocation = pending.shift(); invocation; invocation = pending.shift()) {
+        const prefix = invocation.executable === null ? undefined : cockpitLauncherPrefix(invocation.executable, invocation.argv);
+        const separator = prefix !== undefined && invocation.argv[prefix] === 'session' ? invocation.argv.indexOf('--', prefix) : -1;
+        if (separator < 0) {
+            judged.push(invocation);
+            continue;
+        }
+        judged.push({ ...invocation, argv: invocation.argv.slice(0, separator) });
+        const command = invocation.argv.slice(separator + 1);
+        if (command.length)
+            pending.push({ executable: command[0], argv: command.slice(1), cwd: invocation.cwd, wrapped: false, redirects: [],
+                words: command.map((value, index) => ({ role: index ? 'argument' : 'executable', value })) });
+    }
+    return judged;
+}
+/**
+ * The denial for a tool call that would change the pinned policy tables, or undefined. `isConfig`
+ * says whether a lexically resolved path is the configuration, by spelling or by file identity.
+ */
+export function pinnedPolicyDenial(input, current, isConfig) {
+    const resolved = (cwd) => (path) => isConfig(posix.resolve(cwd, path));
+    if (input.tool === 'Bash') {
+        for (const invocation of judgedInvocations(input.invocations)) {
+            const names = resolved(invocation.cwd);
+            // `--out=cockpit.toml` names the file as surely as a bare operand does.
+            const naming = invocation.argv.flatMap((word, index) => names(word) || word.includes('=') && names(word.slice(word.indexOf('=') + 1)) ? [index] : []);
+            const writes = invocation.redirects.some(redirect => redirect.write);
+            if (!naming.length && !invocation.redirects.some(redirect => redirect.write && names(redirect.target)))
+                continue;
+            // A proven read leaves the file as it is, and staging or committing it records the text the
+            // guard already checked.
+            if (!writes && (classifyReadOnlyInvocation(invocation) || recordsWithoutWriting(invocation)))
+                continue;
+            // Installed cockpit reads the file it is given with --config, but a path or `node <script>`
+            // spells any program as well as cockpit. Whether it starts cockpit is the evaluator's
+            // launcher proof, so only the --config operand is left to it; naming the file anywhere
+            // else is denied whatever the spelling starts.
+            const prefix = invocation.executable === null ? undefined : cockpitLauncherPrefix(invocation.executable, invocation.argv);
+            const configOperand = (index) => prefix !== undefined && index >= prefix
+                && (invocation.argv[index].startsWith('--config=') || index > prefix && invocation.argv[index - 1] === '--config');
+            if (!writes && naming.every(configOperand))
+                continue;
+            return denial(`Refusing a shell command that names the cockpit configuration: the guard cannot tell whether it changes ${PINNED}, which only a person changes. Edit other tables with your editing tool, which the guard can check.`);
+        }
+        return undefined;
+    }
+    if (!input.paths.some(resolved(input.cwd)))
+        return undefined;
+    if (!input.content)
+        return denial(`Refusing an edit of the cockpit configuration whose new text the guard was not given, so it cannot show ${PINNED} unchanged.`);
+    const proposed = proposedText(input.content, resolved(input.cwd), current);
+    if (proposed === 'untouched')
+        return undefined;
+    if (proposed === undefined)
+        return denial(`Refusing an edit of the cockpit configuration that does not apply exactly once to its current text, so the guard cannot show ${PINNED} unchanged.`);
+    const before = pinnedPolicyTables(current);
+    const after = pinnedPolicyTables(proposed);
+    if (!before || !after)
+        return denial(`Refusing an edit that leaves the cockpit configuration unparseable, so the guard cannot show ${PINNED} unchanged.`);
+    if (!isDeepStrictEqual(before, after))
+        return denial(`Refusing to change ${PINNED} in the cockpit configuration: who may pass a gate is a person's decision, made outside the agent. Ask a person to edit it and run sync.`);
+    return undefined;
+}

package/dist/guards/protected-locations.d.ts

@@ -0,0 +1,62 @@
+import { type ExecutionStep } from '../environment/contract.js';
+import type { ResolvedExecutable } from '../environment/executable.js';
+import { type ExecuteProbeOutcome } from '../environment-exec/execute.js';
+/**
+ * The running cockpit package and every package it loads, each under the spelling it was found by
+ * and its real path, plus the consumer's `node_modules` spelling of the package when that is a link
+ * to it. The guard authenticates only its entry point, so all of these are controls.
+ */
+export declare function guardInstalledDirectories(packageRoot: string, consumerRoot: string): readonly string[];
+/**
+ * The file whose identity proves that `executable` with the launcher `words` after it, run in `cwd`,
+ * starts `launcher`, the installed cockpit the guard runs from, or undefined when it may start
+ * something else. A path, or the script `node` is given, qualifies when it resolves to the launcher;
+ * the bare name when the first `cockpit` on the command search path does. `npx` qualifies only in
+ * `root`, where npm runs a `bin` the root package.json declares before any installed one and applies
+ * the root `.npmrc`, whose `script-shell` and `node-options` run other code first; with neither
+ * present it runs the root's `node_modules/.bin/cockpit`, which must resolve to the launcher.
+ */
+export declare function guardLauncherEvidence(executable: string, words: readonly string[], cwd: string, root: string, launcher: string, searchPath: string): string | undefined;
+/**
+ * Absolute search path entries, and their real paths, that lie inside an allowed root. A relative
+ * entry resolves against whatever directory a command runs in, so it names no fixed location.
+ */
+export declare function guardSearchDirectories(searchPath: string, allowedRoots: readonly string[]): readonly string[];
+/** The first entry of `searchPath` that is not absolute, an empty one included, or null when there is none. */
+export declare function guardSearchPathRelativeEntry(searchPath: string): string | null;
+/**
+ * Every path at or below `path` whose case-folded name starts with `.env` or is `.secrets`, of any
+ * type, without following links, as a recursive search would reach it; null once the walk passes
+ * `entryLimit` entries or finds more than the sensitive path bound. A missing path has none.
+ */
+export declare function guardSensitivePathsBelow(path: string, entryLimit?: number): readonly string[] | null;
+export type GuardExecute = (step: ExecutionStep) => Promise<ExecuteProbeOutcome>;
+/**
+ * The paths a default ripgrep search of `path` reads that are named `.env*`, lie below a `.secrets`
+ * directory or are one of `watched`, each reported at its first such name, as Git lists what the
+ * enclosing repository does not ignore; null past the sensitive path bound. Undefined when Git
+ * did not answer or its list cannot stand for ripgrep's: outside a repository, through a
+ * nested repository or submodule, below an `.ignore` or `.rgignore` file, which ripgrep reads and Git
+ * does not, or when the search names an ignored directory, whose children ripgrep may still read.
+ *
+ * Only `.gitignore` files are applied: ripgrep reads those, the repository's exclude file and the
+ * global excludes file, but finds the global one by other rules than Git, so Git applying fewer
+ * lists more. Hidden paths are kept: a type such as `rg -t sh`, which matches `.env`, reads them.
+ * Undefined as well when a `.gitignore` Git reads holds a line the two may match differently.
+ */
+export declare function guardUnignoredSensitivePaths(path: string, watched: readonly string[], git: ResolvedExecutable, execute: GuardExecute): Promise<readonly string[] | null | undefined>;
+/**
+ * Every path `repository`'s index holds that is named `.env*`, lies below a `.secrets` or `.env*`
+ * directory or is one of `watched`, or null past the sensitive path bound or when Git did not
+ * answer. Only the index is asked: a file removed from it stays in history, which this does not walk.
+ */
+export declare function guardTrackedSensitivePaths(repository: string, watched: readonly string[], git: ResolvedExecutable, execute: GuardExecute): Promise<readonly string[] | null>;
+/**
+ * Identities of every file in each case-folded spelling of `env/.secrets` below `root`, and whether
+ * any has a second hard link; `identities` is null once more than the bound of entries was seen,
+ * which leaves every read unproven rather than silently uncovered.
+ */
+export declare function guardSecretFiles(root: string): {
+    readonly identities: readonly string[] | null;
+    readonly linked: boolean;
+};