@guilz-dev/belay 0.1.0

package/dist/core/audit-types.d.ts

@@ -0,0 +1,65 @@
+import type { Assessment } from './types.js';
+export declare const AUDIT_METRICS_SCHEMA_VERSION = 2;
+export declare const GATE_EVENTS: Set<string>;
+export interface AuditRecord {
+    timestamp?: string;
+    event?: string;
+    kind?: string;
+    verdict?: string;
+    reason?: string;
+    fingerprint?: string;
+    summary?: string;
+    approvalId?: string;
+    wouldBlock?: boolean;
+    permission?: string;
+    mode?: string;
+    assessment?: Assessment;
+    predictedAssessment?: Assessment;
+    observedAssessment?: Assessment;
+    transactional?: boolean;
+    transactionalReason?: string;
+    transactionalCategories?: string[];
+    transactionalChangeCount?: number;
+    transactionalSkipReason?: string;
+    [key: string]: unknown;
+}
+export interface AuditFilter {
+    since?: string;
+    until?: string;
+    verdict?: string;
+    reason?: string;
+    kind?: string;
+    fingerprint?: string;
+    event?: string;
+    limit?: number;
+    location?: string;
+    opacity?: string;
+    effect?: string;
+    confidence?: string;
+}
+export interface ApprovalRoundTrip {
+    denyTimestamp: string;
+    approvalTimestamp?: string;
+    executeTimestamp?: string;
+    approvalId?: string;
+    fingerprint: string;
+    reason: string;
+    summary: string;
+    kind: string;
+    approvalLatencyMs?: number;
+}
+export interface BypassAttempt {
+    afterDenyTimestamp: string;
+    denyFingerprint: string;
+    denySummary: string;
+    attemptTimestamp: string;
+    attemptSummary: string;
+    attemptFingerprint: string;
+    signal: 'similar_command' | 'agent_assessment_mismatch' | 'wrapper_pattern';
+}
+export interface NoisyRuleCandidate {
+    reason: string;
+    denyCount: number;
+    approvedCount: number;
+    approvalRate: number;
+}

package/dist/core/audit-types.js

@@ -0,0 +1,2 @@
+export const AUDIT_METRICS_SCHEMA_VERSION = 2;
+export const GATE_EVENTS = new Set(['beforeShellExecution', 'preToolUse', 'subagentGate']);

package/dist/core/capability/allowlist.d.ts

@@ -0,0 +1,10 @@
+import type { BelayConfigV3 } from '../config.js';
+import type { FsScopeAllowlistEntry, FsScopeAllowlistFile } from './types.js';
+export declare function fsScopeAllowlistPath(config: BelayConfigV3, repoLocalStateDir: string): string;
+export declare function loadFsScopeAllowlist(filePath: string): Promise<FsScopeAllowlistFile>;
+export declare function loadFsScopeAllowlistSync(filePath: string): FsScopeAllowlistFile;
+export declare function saveFsScopeAllowlist(filePath: string, state: FsScopeAllowlistFile): Promise<void>;
+export declare function normalizeAllowlistPath(targetPath: string): string;
+export declare function isPathAllowlisted(absolutePath: string, allowlist: FsScopeAllowlistFile): boolean;
+export declare function allPathsAllowlisted(absolutePaths: string[], allowlist: FsScopeAllowlistFile): boolean;
+export declare function addPathToAllowlist(allowlist: FsScopeAllowlistFile, entry: FsScopeAllowlistEntry): FsScopeAllowlistFile;

package/dist/core/capability/allowlist.js

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { belayStateDir } from '../config.js';
+import { canonicalPath, pathWithinRoot } from '../path-utils.js';
+export function fsScopeAllowlistPath(config, repoLocalStateDir) {
+    return path.join(belayStateDir(config, repoLocalStateDir), 'fs-scope-allowlist.json');
+}
+export async function loadFsScopeAllowlist(filePath) {
+    if (!existsSync(filePath)) {
+        return { version: 1, paths: [] };
+    }
+    const raw = JSON.parse(await readFile(filePath, 'utf8'));
+    return {
+        version: 1,
+        paths: Array.isArray(raw.paths) ? raw.paths : [],
+    };
+}
+export function loadFsScopeAllowlistSync(filePath) {
+    if (!existsSync(filePath)) {
+        return { version: 1, paths: [] };
+    }
+    const raw = JSON.parse(readFileSync(filePath, 'utf8'));
+    return {
+        version: 1,
+        paths: Array.isArray(raw.paths) ? raw.paths : [],
+    };
+}
+export async function saveFsScopeAllowlist(filePath, state) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+}
+export function normalizeAllowlistPath(targetPath) {
+    return canonicalPath(targetPath);
+}
+export function isPathAllowlisted(absolutePath, allowlist) {
+    const resolved = normalizeAllowlistPath(absolutePath);
+    return allowlist.paths.some((entry) => {
+        const scope = normalizeAllowlistPath(entry.path);
+        return resolved === scope || pathWithinRoot(scope, resolved);
+    });
+}
+export function allPathsAllowlisted(absolutePaths, allowlist) {
+    return (absolutePaths.length > 0 && absolutePaths.every((entry) => isPathAllowlisted(entry, allowlist)));
+}
+export function addPathToAllowlist(allowlist, entry) {
+    const normalized = normalizeAllowlistPath(entry.path);
+    const filtered = allowlist.paths.filter((existing) => normalizeAllowlistPath(existing.path) !== normalized);
+    return {
+        version: 1,
+        paths: [...filtered, { ...entry, path: normalized }],
+    };
+}

package/dist/core/capability/broker.d.ts

@@ -0,0 +1,17 @@
+import type { BelayConfigV3 } from '../config.js';
+export declare function isSandboxBrokerEnabled(config: BelayConfigV3): boolean;
+export declare function hasSandboxRuntime(config: BelayConfigV3): boolean;
+/** FS-scope demotion requires a configured external sandbox runtime, not sandbox.enabled alone. */
+export declare function isCapabilityBrokerDemotionActive(config: BelayConfigV3): boolean;
+export interface L1FullStatus {
+    active: boolean;
+    sandbox: boolean;
+    egress: boolean;
+    egressProxyRunning: boolean;
+    controlPlaneIsolation: boolean;
+    approvalSigningRequired: boolean;
+}
+export declare function evaluateL1FullStatus(params: {
+    config: BelayConfigV3;
+    egressProxyRunning: boolean;
+}): L1FullStatus;

package/dist/core/capability/broker.js

@@ -0,0 +1,29 @@
+export function isSandboxBrokerEnabled(config) {
+    return config.sandbox.enabled;
+}
+export function hasSandboxRuntime(config) {
+    return config.sandbox.enabled && config.sandbox.runtime !== 'none';
+}
+/** FS-scope demotion requires a configured external sandbox runtime, not sandbox.enabled alone. */
+export function isCapabilityBrokerDemotionActive(config) {
+    return hasSandboxRuntime(config);
+}
+export function evaluateL1FullStatus(params) {
+    const sandbox = hasSandboxRuntime(params.config);
+    const egress = params.config.egress.enabled;
+    const controlPlaneIsolation = params.config.controlPlane.isolation.mode !== 'none';
+    const approvalSigningRequired = params.config.approvalSigning.required;
+    const active = sandbox &&
+        egress &&
+        params.egressProxyRunning &&
+        controlPlaneIsolation &&
+        approvalSigningRequired;
+    return {
+        active,
+        sandbox,
+        egress,
+        egressProxyRunning: params.egressProxyRunning,
+        controlPlaneIsolation,
+        approvalSigningRequired,
+    };
+}

package/dist/core/capability/index.d.ts

@@ -0,0 +1,5 @@
+export { addPathToAllowlist, allPathsAllowlisted, fsScopeAllowlistPath, isPathAllowlisted, loadFsScopeAllowlist, loadFsScopeAllowlistSync, saveFsScopeAllowlist, } from './allowlist.js';
+export { evaluateL1FullStatus, hasSandboxRuntime, isCapabilityBrokerDemotionActive, isSandboxBrokerEnabled, } from './broker.js';
+export { collectOutsideRepoPaths } from './paths.js';
+export { FS_SCOPE_REASONS, shouldSkipBrokerApprovedOnce } from './reasons.js';
+export type { CapabilityApprovalScope, FsScopeAllowlistEntry, FsScopeAllowlistFile, } from './types.js';

package/dist/core/capability/index.js

@@ -0,0 +1,4 @@
+export { addPathToAllowlist, allPathsAllowlisted, fsScopeAllowlistPath, isPathAllowlisted, loadFsScopeAllowlist, loadFsScopeAllowlistSync, saveFsScopeAllowlist, } from './allowlist.js';
+export { evaluateL1FullStatus, hasSandboxRuntime, isCapabilityBrokerDemotionActive, isSandboxBrokerEnabled, } from './broker.js';
+export { collectOutsideRepoPaths } from './paths.js';
+export { FS_SCOPE_REASONS, shouldSkipBrokerApprovedOnce } from './reasons.js';

package/dist/core/capability/paths.d.ts

@@ -0,0 +1 @@
+export declare function collectOutsideRepoPaths(command: string, cwd: string, repoRoot: string): string[];

package/dist/core/capability/paths.js

@@ -0,0 +1,20 @@
+import { relativeWithinRepo, resolveMutationTarget } from '../path-utils.js';
+import { extractRedirectTargets, tokenizeShell } from '../shell-tokenizer.js';
+export function collectOutsideRepoPaths(command, cwd, repoRoot) {
+    const tokens = tokenizeShell(command);
+    const redirects = extractRedirectTargets(tokens);
+    const paths = new Set();
+    for (const token of tokens.slice(1)) {
+        const resolved = resolveMutationTarget(token, cwd);
+        if (resolved && relativeWithinRepo(repoRoot, resolved) === null) {
+            paths.add(resolved);
+        }
+    }
+    for (const redirect of redirects) {
+        const resolved = resolveMutationTarget(redirect, cwd);
+        if (resolved && relativeWithinRepo(repoRoot, resolved) === null) {
+            paths.add(resolved);
+        }
+    }
+    return [...paths];
+}

package/dist/core/capability/reasons.d.ts

@@ -0,0 +1,2 @@
+export declare const FS_SCOPE_REASONS: Set<string>;
+export declare function shouldSkipBrokerApprovedOnce(brokerActive: boolean, reason: string): boolean;

package/dist/core/capability/reasons.js

@@ -0,0 +1,4 @@
+export const FS_SCOPE_REASONS = new Set(['outside_repo_mutation', 'outside_repo_redirect']);
+export function shouldSkipBrokerApprovedOnce(brokerActive, reason) {
+    return brokerActive && FS_SCOPE_REASONS.has(reason);
+}

package/dist/core/capability/types.d.ts

@@ -0,0 +1,10 @@
+export type CapabilityApprovalScope = 'once' | 'path';
+export interface FsScopeAllowlistEntry {
+    path: string;
+    approvedAt: string;
+    approvalId: string;
+}
+export interface FsScopeAllowlistFile {
+    version: 1;
+    paths: FsScopeAllowlistEntry[];
+}

package/dist/core/capability/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/capability-approval.d.ts

@@ -0,0 +1,28 @@
+import type { CapabilityApprovalScope } from './capability/types.js';
+import type { BelayConfigV3 } from './config.js';
+import type { ApprovalStateFile } from './types.js';
+export interface CapabilityApprovalStore {
+    loadPending: () => Promise<{
+        filePath: string;
+        state: ApprovalStateFile;
+    }>;
+    loadApproved: () => Promise<{
+        filePath: string;
+        state: ApprovalStateFile;
+    }>;
+    writePending: (filePath: string, state: ApprovalStateFile) => Promise<void>;
+    writeApproved: (filePath: string, state: ApprovalStateFile) => Promise<void>;
+    allowlistPath: string;
+}
+export declare function recordCapabilityApproval(params: {
+    approvalId: string;
+    config: BelayConfigV3;
+    store: CapabilityApprovalStore;
+    scope?: CapabilityApprovalScope;
+    scopePath?: string;
+    token?: string;
+    requireSignedToken?: boolean;
+}): Promise<{
+    ok: boolean;
+    message: string;
+}>;

package/dist/core/capability-approval.js

@@ -0,0 +1,43 @@
+import { recordApproval } from './approval-service.js';
+import { addPathToAllowlist, loadFsScopeAllowlist, normalizeAllowlistPath, saveFsScopeAllowlist, } from './capability/allowlist.js';
+import { FS_SCOPE_REASONS } from './capability/reasons.js';
+export async function recordCapabilityApproval(params) {
+    const pending = await params.store.loadPending();
+    const match = pending.state.approvals.find((approval) => approval.approvalId === params.approvalId);
+    if (params.scope === 'path') {
+        if (!match || !FS_SCOPE_REASONS.has(match.reason)) {
+            return {
+                ok: false,
+                message: 'Path scope approvals apply only to pending outside-repo shell actions (outside_repo_mutation / outside_repo_redirect).',
+            };
+        }
+        if (!params.scopePath?.trim()) {
+            return {
+                ok: false,
+                message: 'approve --scope path requires --path <absolute-or-relative-path>.',
+            };
+        }
+    }
+    const result = await recordApproval({
+        approvalId: params.approvalId,
+        config: params.config,
+        token: params.token,
+        requireSignedToken: params.requireSignedToken ?? false,
+        store: params.store,
+    });
+    if (!result.ok || params.scope !== 'path' || !params.scopePath?.trim()) {
+        return { ok: result.ok, message: result.message };
+    }
+    const allowlist = await loadFsScopeAllowlist(params.store.allowlistPath);
+    const normalizedPath = normalizeAllowlistPath(params.scopePath.trim());
+    const updated = addPathToAllowlist(allowlist, {
+        path: normalizedPath,
+        approvedAt: new Date().toISOString(),
+        approvalId: params.approvalId,
+    });
+    await saveFsScopeAllowlist(params.store.allowlistPath, updated);
+    return {
+        ok: true,
+        message: `${result.message} Path ${normalizedPath} added to fs-scope allowlist.`,
+    };
+}

package/dist/core/classify-subagent.d.ts

@@ -0,0 +1,2 @@
+import type { ClassifierOptions, ClassifyResult } from './types.js';
+export declare function classifySubagent(payload: Record<string, unknown>, repoRoot: string, options?: ClassifierOptions): ClassifyResult;

package/dist/core/classify-subagent.js

@@ -0,0 +1,69 @@
+import { canonicalStringify, subagentFingerprint } from './fingerprint.js';
+import { scrubValue } from './scrub.js';
+const EXTERNAL_TERMS = ['deploy', 'production', 'publish', 'release', 'ship', 'notify', 'email'];
+function extractSubagentText(payload, options) {
+    const toolInput = payload.tool_input;
+    if (toolInput && typeof toolInput === 'object') {
+        const input = toolInput;
+        const description = typeof input.description === 'string' ? input.description : '';
+        const prompt = typeof input.prompt === 'string' ? input.prompt : '';
+        return [description, prompt].filter(Boolean).join(' ');
+    }
+    const task = payload.task;
+    if (typeof task === 'string') {
+        return task;
+    }
+    if (task && typeof task === 'object') {
+        const taskObj = task;
+        const description = typeof taskObj.description === 'string' ? taskObj.description : '';
+        const prompt = typeof taskObj.prompt === 'string' ? taskObj.prompt : '';
+        return [description, prompt].filter(Boolean).join(' ');
+    }
+    return canonicalStringify(scrubValue(payload, options.scrubOptions));
+}
+function fingerprintSource(payload, options) {
+    const toolInput = payload.tool_input;
+    if (toolInput && typeof toolInput === 'object') {
+        const input = toolInput;
+        return scrubValue({
+            description: input.description ?? '',
+            prompt: input.prompt ?? '',
+        }, options.scrubOptions);
+    }
+    const task = payload.task;
+    if (typeof task === 'string') {
+        return scrubValue({ task }, options.scrubOptions);
+    }
+    if (task && typeof task === 'object') {
+        const taskObj = task;
+        return scrubValue({
+            description: taskObj.description ?? '',
+            prompt: taskObj.prompt ?? '',
+        }, options.scrubOptions);
+    }
+    return scrubValue(payload, options.scrubOptions);
+}
+export function classifySubagent(payload, repoRoot, options = {}) {
+    const kind = payload.tool_name === 'Task' ? 'Task' : String(payload.subagent_type ?? 'generalPurpose');
+    const scrubbed = fingerprintSource(payload, options);
+    const summary = extractSubagentText(payload, options);
+    const lowered = summary.toLowerCase();
+    const fingerprint = subagentFingerprint(kind, scrubbed, repoRoot);
+    const hasExternalTerm = EXTERNAL_TERMS.some((term) => {
+        const pattern = new RegExp(`\\b${term}\\b`, 'i');
+        return pattern.test(lowered);
+    });
+    return {
+        verdict: 'allow_flagged',
+        reason: 'subagent_review',
+        summary,
+        fingerprint,
+        assessment: {
+            reversibility: 'recoverable_with_cost',
+            external: false,
+            blastRadius: 'subagent task scope',
+            confidence: hasExternalTerm ? 0.7 : 0.67,
+            signals: hasExternalTerm ? ['subagent_external_intent_hint'] : ['subagent_default_review'],
+        },
+    };
+}

package/dist/core/classify-tool.d.ts

@@ -0,0 +1,3 @@
+import type { BelayConfigV3 } from './config.js';
+import type { ClassifierOptions, ClassifyResult } from './types.js';
+export declare function classifyToolUse(payload: Record<string, unknown>, repoRoot: string, cwd: string, config: BelayConfigV3, options?: ClassifierOptions): Promise<ClassifyResult>;