@b00dea/cockpit 0.0.0-bootstrap.0 → 0.1.0

package/dist/guards/harness-adapter.d.ts

@@ -0,0 +1,17 @@
+import { type JsonSnapshotObject } from '../environment/contract.js';
+import { type GuardSurfaceTarget } from '../surfaces/harness-registry.js';
+import type { GuardDecision } from './evaluator.js';
+export declare const GUARD_HANDLER_ARGV: readonly ["guard-evaluate"];
+export interface NativeGuardOutput {
+    readonly target: GuardSurfaceTarget | null;
+    readonly capability: 'instructed';
+    readonly decision: GuardDecision['decision'];
+    readonly exitCode: 0 | 2;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/** Native spelling cannot add grants or change the evaluator's hard boundaries. */
+export declare function adaptGuardDecision(harness: unknown, input: unknown): NativeGuardOutput;
+/** Only measured field-name normalization; shell and patch grammar belong to the parser. */
+export declare function normalizeOpenCodeInput(input: unknown): JsonSnapshotObject | undefined;
+/** The application binds this data to the shared process executor; no handler is installed here. */

package/dist/guards/harness-adapter.js

@@ -0,0 +1,57 @@
+import { posix } from 'node:path';
+import { exactKeys } from '../exact-keys.js';
+import { snapshotJson } from '../environment/contract.js';
+import { GUARD_SURFACE_TARGETS } from '../surfaces/harness-registry.js';
+import { GUARD_INPUT_LIMITS } from './invocation-parser.js';
+export const GUARD_HANDLER_ARGV = Object.freeze(['guard-evaluate']);
+function target(value) { return typeof value === 'string' && GUARD_SURFACE_TARGETS.some((item) => item === value); }
+function record(value) { return value !== null && typeof value === 'object' && !Array.isArray(value); }
+function text(value, limit) { return typeof value === 'string' && Buffer.byteLength(value) <= limit && !/[\uD800-\uDFFF]/u.test(value); }
+function absolute(value) {
+    return text(value, GUARD_INPUT_LIMITS.pathBytes) && value.startsWith('/') && value !== '/' && !value.endsWith('/')
+        && posix.normalize(value) === value && !/[\x00-\x1f\x7f\\]/.test(value);
+}
+function decision(value) {
+    const captured = snapshotJson(value);
+    if (!record(captured) || !exactKeys(captured, ['decision', 'reason']) || !['allow', 'ask', 'deny', 'unavailable'].includes(String(captured.decision))
+        || !text(captured.reason, 4096) || !captured.reason.trim() || /[\x00-\x1f\x7f-\x9f\u061c\u200e\u200f\u2028-\u202e\u2066-\u2069]/.test(captured.reason))
+        return undefined;
+    return captured;
+}
+/** Native spelling cannot add grants or change the evaluator's hard boundaries. */
+export function adaptGuardDecision(harness, input) {
+    const resolved = decision(input);
+    const native = target(harness) ? harness : null;
+    const selected = resolved && native ? resolved : { decision: 'unavailable', reason: 'Guard adapter received an invalid harness or closed decision.' };
+    const verdict = selected.decision === 'ask' && native !== 'claudecode' ? 'deny' : selected.decision;
+    let stdout = '';
+    let stderr = '';
+    let exitCode = 0;
+    if (verdict === 'unavailable' || native === 'opencode' && verdict !== 'allow') {
+        exitCode = 2;
+        stderr = `cockpit guard: ${selected.reason}\n`;
+    }
+    else if (verdict !== 'allow') {
+        stdout = JSON.stringify({ hookSpecificOutput: {
+                hookEventName: 'PreToolUse', permissionDecision: verdict, permissionDecisionReason: selected.reason,
+            } }) + '\n';
+    }
+    return { target: native, capability: 'instructed', decision: verdict, exitCode, stdout, stderr };
+}
+/** Only measured field-name normalization; shell and patch grammar belong to the parser. */
+export function normalizeOpenCodeInput(input) {
+    const value = snapshotJson(input);
+    if (!record(value) || !exactKeys(value, ['tool', 'args', 'cwd']) || typeof value.tool !== 'string' || !record(value.args) || !absolute(value.cwd))
+        return undefined;
+    const tools = { bash: 'Bash', edit: 'Edit', write: 'Write', apply_patch: 'apply_patch' };
+    const tool = Object.hasOwn(tools, value.tool) ? tools[value.tool] : undefined;
+    if (!tool)
+        return undefined;
+    const field = tool === 'Bash' ? value.args.command : tool === 'apply_patch' ? value.args.patchText : value.args.filePath ?? value.args.path ?? value.args.file;
+    if (typeof field !== 'string')
+        return undefined;
+    const result = snapshotJson({ hook_event_name: 'PreToolUse', tool_name: tool, cwd: value.cwd,
+        tool_input: tool === 'Bash' || tool === 'apply_patch' ? { command: field } : { file_path: field } });
+    return record(result) && Buffer.byteLength(JSON.stringify(result)) <= GUARD_INPUT_LIMITS.inputBytes ? result : undefined;
+}
+/** The application binds this data to the shared process executor; no handler is installed here. */

package/dist/guards/host.d.ts

@@ -0,0 +1,8 @@
+export declare const GUARD_HOST_LIMITS: Readonly<{
+    hostnameBytes: 253;
+    labelBytes: 63;
+    rows: 128;
+}>;
+export declare const GUARD_HOST_PATTERN: RegExp;
+export declare function isGuardHost(value: unknown): value is string;
+export declare function normalizeGuardHost(value: string): string;

package/dist/guards/host.js

@@ -0,0 +1,10 @@
+export const GUARD_HOST_LIMITS = Object.freeze({ hostnameBytes: 253, labelBytes: 63, rows: 128 });
+const label = `[a-z0-9](?:[a-z0-9-]{0,${GUARD_HOST_LIMITS.labelBytes - 2}}[a-z0-9])?`;
+// ASCII makes these character bounds identical to UTF-8 byte bounds, including in editor schemas.
+export const GUARD_HOST_PATTERN = new RegExp(`^(?:\\*\\.)?(?=[a-z0-9.-]{1,${GUARD_HOST_LIMITS.hostnameBytes}}(?![\\s\\S]))${label}(?:\\.${label})*(?![\\s\\S])`);
+export function isGuardHost(value) {
+    return typeof value === 'string' && GUARD_HOST_PATTERN.test(value);
+}
+export function normalizeGuardHost(value) {
+    return value.startsWith('*.') ? value.slice(2) : value;
+}

package/dist/guards/invocation-parser.d.ts

@@ -0,0 +1,66 @@
+export declare const GUARD_INPUT_LIMITS: Readonly<{
+    inputBytes: 65536;
+    invocations: 256;
+    words: 4096;
+    wordBytes: 4096;
+    paths: 256;
+    pathBytes: 4096;
+}>;
+export type InvocationRole = 'executable' | 'argument' | 'environment-assignment-value' | 'wrapper-option-value' | 'redirect-target' | 'heredoc-body' | 'comment' | 'definition' | 'directory';
+export interface InvocationWord {
+    readonly role: InvocationRole;
+    readonly value: string;
+}
+export interface ParsedInvocation {
+    readonly executable: string | null;
+    readonly argv: readonly string[];
+    readonly cwd: string;
+    readonly wrapped: boolean;
+    readonly words: readonly InvocationWord[];
+    /** `truncate` marks `>` and `>|`, which empty an existing file before anything is written. */
+    readonly redirects: readonly {
+        readonly target: string;
+        readonly write: boolean;
+        readonly truncate: boolean;
+    }[];
+    /**
+     * An argument, assignment or wrapper option holds `$?`, the previous command's exit status. It expands to digits the guard
+     * cannot see, so a word holding it is never proven to name a path.
+     */
+    readonly expandsStatus?: true;
+}
+/** The new text a file tool call carries, as the payload spells it, kept so the policy pin can apply it. */
+export type GuardFileContent = Readonly<{
+    kind: 'replace';
+    path: string;
+    old: string;
+    new: string;
+    all: boolean;
+}> | Readonly<{
+    kind: 'write';
+    path: string;
+    content: string;
+}> | Readonly<{
+    kind: 'patch';
+    text: string;
+}>;
+export type GuardParseResult = {
+    readonly status: 'parsed';
+    readonly tool: 'Bash' | 'Edit' | 'Write' | 'NotebookEdit' | 'apply_patch';
+    readonly cwd: string;
+    readonly invocations: readonly ParsedInvocation[];
+    readonly paths: readonly string[];
+    /** Targets deleted, moved away from or emptied, as opposed to edited in place. */
+    readonly removed: readonly string[];
+    readonly content?: GuardFileContent;
+} | {
+    readonly status: 'unavailable';
+    readonly reason: string;
+};
+export declare function isParsedGuardInput(value: unknown): value is Extract<GuardParseResult, {
+    status: 'parsed';
+}>;
+/** A word as a refusal quotes it: JSON-escaped, with the controls a harness rejects in a reason escaped too, and bounded. */
+export declare function shownGuardWord(word: string): string;
+/** Capture once: the evaluator never consumes native payloads or reparses shell text. */
+export declare function parseGuardInput(input: unknown): GuardParseResult;