@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/guards/answer-confirmation.js

@@ -0,0 +1,109 @@
+// Owns who may confirm each init answer listed under `unconfirmed`, and the record of the
+// observations that confirmed one. A person keeps every answer that is a trust decision and every
+// answer no observation settles exactly; an agent may confirm the rest with `cockpit confirm`, which
+// runs the observation and records it here. The guard then lets the agent's own sync apply the
+// removed entry, but only while the record matches the configuration on disk.
+//
+// The record is machine-local, under `.cockpit/local`: the observation is evidence about this machine
+// and its running stack, which another clone has not seen, so there a removed entry still waits for a
+// person. The directory is a guard control directory, so no agent tool call may write it; only the
+// cockpit process that ran the observation does.
+import { canonicalJson } from '../canonical-json.js';
+import { exactKeys } from '../exact-keys.js';
+import { cockpitCommand } from '../fix-catalogue.js';
+import { UNCONFIRMABLE_ANSWERS } from '../schema.js';
+import { sha256Hex } from '../sha256.js';
+import { GUARD_LOCAL_PATHS } from './local-identity.js';
+export const ANSWER_CONFIRMATIONS = Object.freeze({
+    'ports.bases': { by: 'observation', observation: 'preflight',
+        verifies: 'preflight passes with the stack up, its port family leased on the declared bases and every listener and health observation passing' },
+    'environment.compose_files': { by: 'observation', observation: 'check',
+        verifies: 'check passes, which parses the declared Compose files with docker compose config and resolves the stack\'s topology from them' },
+    'environment.machine': { by: 'observation', observation: 'runtime-floor',
+        verifies: 'the container runtime measured on this machine meets the declared memory, CPU and free-disk floor' },
+    guards: { by: 'person', trustDecision: true, why: 'it sets which commands and hosts the guard denies' },
+    testing: { by: 'person', trustDecision: true, why: 'it decides which tests grade the agent\'s own work' },
+    'environment.install_policies': { by: 'person', trustDecision: true, why: 'it sets the build and test commands the guard admits' },
+    sibling: { by: 'person', trustDecision: true, why: 'it sets each repository\'s purpose and the roots agents may write' },
+    'environment.posture': { by: 'person', trustDecision: true, why: 'it decides browser preapproval and what data agents are exposed to' },
+    'cockpit.name': { by: 'person', trustDecision: false,
+        why: 'a name is a choice, and no observation shows it is the one the owner wants; it scopes Compose projects, state and generated files' },
+    'estate.runnable': { by: 'person', trustDecision: false,
+        why: 'a stack that starts shows the declared services run, not that a repository declared not runnable should stay out' },
+    'environment.test_data': { by: 'person', trustDecision: false,
+        why: 'it states what local work needs (seeded data, signed-in users), and no observation shows a need is absent' },
+});
+export const ANSWER_CONFIRMATION_PATH = `${GUARD_LOCAL_PATHS.directory}/answer-confirmations`;
+const FORMAT = 'cockpit-answer-confirmations/v1';
+const RECORD_KEYS = ['observation', 'ranAt', 'result', 'evidenceSha256', 'configurationSha256'];
+const SHA256 = /^[a-f0-9]{64}$/;
+const TIMESTAMP = /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/;
+/**
+ * The digest a record binds to: the whole configuration except the `unconfirmed` list, so confirming
+ * one answer leaves the records of the others current, and any other edit leaves every record stale.
+ */
+export function confirmationConfigurationSha256(config) {
+    const { unconfirmed: _unconfirmed, ...observed } = config;
+    return sha256Hex(canonicalJson(observed));
+}
+function validRecord(answer, value) {
+    const confirmation = ANSWER_CONFIRMATIONS[answer];
+    if (!confirmation || confirmation.by !== 'observation' || value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const row = value;
+    return exactKeys(row, RECORD_KEYS) && row.observation === confirmation.observation && row.result === 'passed'
+        && typeof row.ranAt === 'string' && TIMESTAMP.test(row.ranAt) && Number.isFinite(Date.parse(row.ranAt))
+        && typeof row.evidenceSha256 === 'string' && SHA256.test(row.evidenceSha256)
+        && typeof row.configurationSha256 === 'string' && SHA256.test(row.configurationSha256);
+}
+/** Every well-formed record the bytes hold, or none when they are absent or not a current-format file. */
+export function parseAnswerConfirmations(bytes) {
+    if (!bytes)
+        return {};
+    let value;
+    try {
+        value = JSON.parse(Buffer.from(bytes).toString('utf8'));
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            return {};
+        throw error;
+    }
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return {};
+    const file = value;
+    const confirmations = file.confirmations;
+    if (!exactKeys(file, ['format', 'confirmations']) || file.format !== FORMAT
+        || confirmations === null || typeof confirmations !== 'object' || Array.isArray(confirmations))
+        return {};
+    return Object.fromEntries(Object.entries(confirmations).filter(([answer, row]) => validRecord(answer, row)));
+}
+export function encodeAnswerConfirmations(records) {
+    return `${JSON.stringify({ format: FORMAT, confirmations: records }, null, 2)}\n`;
+}
+/**
+ * The answers whose recorded observation passed against exactly `config`. A missing, malformed or
+ * stale record confirms nothing, and no record confirms an answer only a person may.
+ */
+export function confirmedAnswers(bytes, config) {
+    const digest = confirmationConfigurationSha256(config);
+    return new Set(Object.entries(parseAnswerConfirmations(bytes))
+        .filter(([, row]) => row.configurationSha256 === digest).map(([answer]) => answer));
+}
+export function isUnconfirmedAnswerName(value) {
+    return UNCONFIRMABLE_ANSWERS.includes(value);
+}
+/** The confirmation a person makes, for the answers only a person may confirm. */
+export function personConfirmationFix(answers, configPath) {
+    return `a person confirms ${answers.join(', ')} with whoever owns the product, corrects cockpit.toml if a value is wrong, deletes ${answers.length === 1 ? 'its entry' : 'each entry'} from unconfirmed, then runs ${cockpitCommand('sync', configPath === undefined ? {} : { config: configPath })} in a terminal outside the agent`;
+}
+/** How each listed answer is confirmed: the observation an agent runs, or the person who must. */
+export function unconfirmedFix(answers) {
+    const observed = answers.flatMap(answer => {
+        const confirmation = ANSWER_CONFIRMATIONS[answer];
+        return confirmation.by === 'observation'
+            ? [`run ${cockpitCommand('confirm', { operand: answer })}, which confirms ${answer} only if ${confirmation.verifies}`] : [];
+    });
+    const person = answers.filter(answer => ANSWER_CONFIRMATIONS[answer].by === 'person');
+    return [...observed, ...person.length ? [personConfirmationFix(person)] : []].join('; ');
+}

package/dist/guards/evaluator.d.ts

@@ -0,0 +1,130 @@
+/**
+ * The cockpit commands that run the words after their `--` as a command of their own, and where it
+ * runs: a session's on the host, exec's inside a product container that mounts the checkouts and
+ * may hold their credentials. The guard judges that command as an invocation of its own, so
+ * wrapping a command never admits more than running it directly.
+ */
+export declare const WRAPPING_COMMANDS: ReadonlyMap<string, 'host' | 'container'>;
+/**
+ * The command a wrapping cockpit command runs, from its arguments after the launcher: the words
+ * after its first `--`, and where they run. Undefined when the command wraps none or names no
+ * command after `--`.
+ */
+export declare function innerCommand(argv: readonly string[]): Readonly<{
+    words: readonly string[];
+    runs: 'host' | 'container';
+}> | undefined;
+export interface GuardInvocationProfile {
+    readonly executable: string;
+    readonly cwd: string;
+    readonly argv: readonly string[];
+    /** Files the admitted command reads and may echo back, checked like a read-only command's reads. */
+    readonly reads?: readonly string[];
+}
+export interface GuardProjectCommand {
+    readonly executable: string;
+    readonly checkoutRoot: string;
+    readonly kind: 'build' | 'test';
+    readonly argv: readonly string[];
+}
+/** Filesystem identity of a protected path: its own when it exists, and every existing directory above it. */
+export interface GuardProtectedIdentity {
+    readonly path: string;
+    readonly identity: string | null;
+    readonly ancestors: readonly string[];
+}
+interface GuardDeclaredAllow {
+    readonly argv: readonly string[];
+    readonly reason: string;
+    readonly cwd?: string;
+}
+interface GuardDeclaredDeny {
+    readonly match: 'prefix' | 'contains';
+    readonly argv: readonly string[];
+    readonly reason: string;
+    readonly fix?: string;
+}
+export interface GuardEvaluationPolicy {
+    readonly canonicalRoot: string;
+    /** The configuration every guarded call reads; deleting it strands the agent. */
+    readonly configPath: string;
+    readonly allowedRoots: readonly string[];
+    readonly instances: readonly {
+        readonly name: string;
+        readonly path: string;
+    }[];
+    /** Declared environment templates: `.env*` files that are documentation, not data. */
+    readonly templates: readonly string[];
+    readonly protectedIdentities: readonly GuardProtectedIdentity[];
+    readonly protectedBranches: readonly string[];
+    readonly hostedDatabaseHosts: readonly string[];
+    readonly vendorHosts: readonly string[];
+    readonly declaredAllows: readonly GuardDeclaredAllow[];
+    readonly declaredDenies: readonly GuardDeclaredDeny[];
+    readonly ripgrepConfigActive: boolean;
+    /**
+     * Directories whose code runs as the guard: the installed cockpit package and every package it
+     * loads. Every allowed root's `node_modules/.bin` is protected beside them without being listed.
+     */
+    readonly executionDirectories: readonly string[];
+    /** Absolute command search path directories inside the allowed roots, where a planted file shadows a permitted command. */
+    readonly searchDirectories: readonly string[];
+    /** The first command search path entry that is not absolute, where an empty one is the working directory; null when every entry is absolute. */
+    readonly searchPathRelativeEntry: string | null;
+    /** Identities of every file in the root secrets directory, or null when it held more than the enumeration bound. */
+    readonly secretFileIdentities: readonly string[] | null;
+    /** Some instance or secrets file has another hard link, which a recursive search can read under an unprotected name. */
+    readonly protectedFilesLinked: boolean;
+    readonly cockpitInvocations: readonly GuardInvocationProfile[];
+    /**
+     * Launcher spellings the application proved start the guard's own installed cockpit when run in
+     * `cwd`: the executable and the launcher words after it, such as `npx` with `--no cockpit`. A
+     * matching invocation is evaluated as cockpit with the remaining words; no other one is.
+     */
+    readonly cockpitLaunchers: readonly GuardInvocationProfile[];
+    readonly projectCommands: readonly GuardProjectCommand[];
+}
+interface PathInspectionRequest {
+    readonly path: string;
+    readonly cwd: string;
+    /**
+     * A `search` is a recursive read; its evidence also carries `sensitive`, every existing path at or
+     * below it named `.env*` or `.secrets`, or null past the walk's bound. An `unignored-search` reads
+     * only what Git does not ignore, as ripgrep does by default; its `sensitive` holds only what such
+     * a search reads, and also every declared instance it reads. A `repository` is the Git repository
+     * at the path; its evidence carries `tracked`, every `.env*`, secrets or instance path its index
+     * holds, or null when Git could not say.
+     */
+    readonly operation: 'cwd' | 'write' | 'stage' | 'read' | 'remove' | 'search' | 'unignored-search' | 'repository';
+}
+/** The application supplies current, symlink-aware facts; the evaluator performs no I/O. */
+export type PathInspection = (request: PathInspectionRequest) => unknown;
+export interface GuardDecision {
+    readonly decision: 'allow' | 'ask' | 'deny' | 'unavailable';
+    readonly reason: string;
+}
+/**
+ * Bounds on the locations the policy and the path inspector carry, one per quantity, each set above
+ * what an honest checkout holds so that only an unwalkable tree or a broken install reaches it.
+ */
+export declare const GUARD_LOCATION_LIMITS: Readonly<{
+    packageDirectories: 256;
+    searchPathDirectories: 256;
+    templates: 256;
+    sensitivePaths: 1024;
+}>;
+export declare const GUARD_SECRET_FILE_LIMIT = 512;
+/** Root-relative paths whose identity every policy carries beside each instance's. */
+export declare const GUARD_ROOT_PROTECTIONS: readonly {
+    readonly path: string;
+    readonly type: 'file' | 'directory';
+}[];
+/** One spelling of a file's identity, shared by the policy build and the path inspector. */
+export declare function guardIdentity(status: {
+    readonly dev: number;
+    readonly ino: number;
+}): string;
+export declare function foldGuardSpelling(path: string): string;
+/** Hard boundaries are independent of grants and are evaluated across the complete capture. */
+export declare function evaluateGuard(input: unknown, policy: unknown, inspect: PathInspection): GuardDecision;
+export {};