@b00dea/cockpit 0.0.0-bootstrap.0 → 0.1.0

package/dist/guards/evaluator.d.ts

@@ -0,0 +1,113 @@
+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[];
+}
+export interface GuardDeclaredAllow {
+    readonly argv: readonly string[];
+    readonly reason: string;
+    readonly cwd?: string;
+}
+export 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[];
+}
+export 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;