@guilz-dev/belay 0.3.0 → 0.6.0

package/dist/core/capability/trusted-workspace-roots.js

@@ -0,0 +1,149 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { belayStateDir } from '../config.js';
+import { canonicalPath, containingGitRoot, pathWithinRoot, resolveWorkspaceRootMatch, } from '../path-utils.js';
+export function trustedWorkspaceRootsPath(config, repoLocalStateDir) {
+    return path.join(belayStateDir(config, repoLocalStateDir), 'trusted-workspace-roots.json');
+}
+export async function loadTrustedWorkspaceRoots(filePath) {
+    if (!existsSync(filePath)) {
+        return { version: 1, roots: [] };
+    }
+    const raw = JSON.parse(await readFile(filePath, 'utf8'));
+    return { version: 1, roots: sanitizeTrustedWorkspaceRootEntries(raw.roots) };
+}
+export function loadTrustedWorkspaceRootsSync(filePath) {
+    if (!existsSync(filePath)) {
+        return { version: 1, roots: [] };
+    }
+    const raw = JSON.parse(readFileSync(filePath, 'utf8'));
+    return { version: 1, roots: sanitizeTrustedWorkspaceRootEntries(raw.roots) };
+}
+export async function saveTrustedWorkspaceRoots(filePath, state) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+}
+export function normalizeTrustedWorkspaceRootPath(targetPath) {
+    return canonicalPath(targetPath);
+}
+function sanitizeTrustedWorkspaceRootEntries(input) {
+    if (!Array.isArray(input)) {
+        return [];
+    }
+    return input.flatMap((entry) => {
+        if (!entry || typeof entry !== 'object') {
+            return [];
+        }
+        const record = entry;
+        if (typeof record.path !== 'string' || !record.path.trim()) {
+            return [];
+        }
+        const approvedAt = typeof record.approvedAt === 'string' ? record.approvedAt : new Date(0).toISOString();
+        const approvalId = typeof record.approvalId === 'string' ? record.approvalId : 'unknown';
+        const source = record.source === 'approval' ? 'approval' : undefined;
+        return [
+            {
+                path: path.resolve(record.path),
+                approvedAt,
+                approvalId,
+                ...(source ? { source } : {}),
+            },
+        ];
+    });
+}
+const SYSTEM_HIGH_STAKES_PREFIXES = [
+    '/etc',
+    '/private/etc',
+    '/bin',
+    '/sbin',
+    '/usr',
+    '/opt',
+    '/System',
+    '/Library',
+];
+const HOME_HIGH_STAKES_SEGMENTS = ['.ssh', '.gnupg', '.aws', '.kube', '.docker', '.config'];
+function isDirectoryPath(targetPath) {
+    try {
+        return statSync(targetPath).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function isBroadTrustedWorkspaceRoot(targetPath) {
+    const home = process.env.HOME ?? process.env.USERPROFILE;
+    const root = normalizeTrustedWorkspaceRootPath(targetPath);
+    if (root === normalizeTrustedWorkspaceRootPath(path.parse(root).root)) {
+        return true;
+    }
+    if (home && normalizeTrustedWorkspaceRootPath(home) === root) {
+        return true;
+    }
+    return false;
+}
+export function isHighStakesTrustedWorkspaceRoot(targetPath) {
+    const normalized = normalizeTrustedWorkspaceRootPath(targetPath);
+    if (SYSTEM_HIGH_STAKES_PREFIXES.some((prefix) => normalized === normalizeTrustedWorkspaceRootPath(prefix) ||
+        pathWithinRoot(normalizeTrustedWorkspaceRootPath(prefix), normalized))) {
+        return true;
+    }
+    const home = process.env.HOME ?? process.env.USERPROFILE;
+    if (!home) {
+        return false;
+    }
+    const homeRoot = normalizeTrustedWorkspaceRootPath(home);
+    if (!pathWithinRoot(homeRoot, normalized)) {
+        return false;
+    }
+    return HOME_HIGH_STAKES_SEGMENTS.some((segment) => pathWithinRoot(path.join(homeRoot, segment), normalized));
+}
+export function validateTrustedWorkspaceRootCandidate(params) {
+    const normalizedPath = normalizeTrustedWorkspaceRootPath(params.candidatePath);
+    if (params.requireExistingDirectory !== false && !isDirectoryPath(normalizedPath)) {
+        return { ok: false, normalizedPath, reason: 'not_directory' };
+    }
+    if (isBroadTrustedWorkspaceRoot(normalizedPath)) {
+        return { ok: false, normalizedPath, reason: 'broad_root' };
+    }
+    if (isHighStakesTrustedWorkspaceRoot(normalizedPath)) {
+        return { ok: false, normalizedPath, reason: 'high_stakes' };
+    }
+    if (resolveWorkspaceRootMatch(params.repoRoot, [], normalizedPath) !== null) {
+        return { ok: false, normalizedPath, reason: 'inside_repo' };
+    }
+    if (params.requireNonGit !== false && containingGitRoot(normalizedPath)) {
+        return { ok: false, normalizedPath, reason: 'inside_git_repo' };
+    }
+    const normalizedControlPlane = params.controlPlaneDir?.trim()
+        ? normalizeTrustedWorkspaceRootPath(params.controlPlaneDir)
+        : null;
+    if (normalizedControlPlane &&
+        (pathWithinRoot(normalizedControlPlane, normalizedPath) ||
+            pathWithinRoot(normalizedPath, normalizedControlPlane))) {
+        return { ok: false, normalizedPath, reason: 'control_plane_overlap' };
+    }
+    if ((params.protectedRoots ?? []).some((root) => {
+        const normalizedRoot = normalizeTrustedWorkspaceRootPath(root);
+        return (pathWithinRoot(normalizedRoot, normalizedPath) ||
+            pathWithinRoot(normalizedPath, normalizedRoot));
+    })) {
+        return { ok: false, normalizedPath, reason: 'protected_root_overlap' };
+    }
+    return { ok: true, normalizedPath };
+}
+export function isPathWithinTrustedWorkspaceRoots(absolutePath, roots) {
+    const resolved = normalizeTrustedWorkspaceRootPath(absolutePath);
+    return roots.roots.some((entry) => {
+        const root = path.resolve(entry.path);
+        return resolved === root || pathWithinRoot(root, resolved);
+    });
+}
+export function addTrustedWorkspaceRoot(roots, entry) {
+    const normalized = normalizeTrustedWorkspaceRootPath(entry.path);
+    const filtered = roots.roots.filter((existing) => normalizeTrustedWorkspaceRootPath(existing.path) !== normalized);
+    return {
+        version: 1,
+        roots: [...filtered, { ...entry, path: normalized }],
+    };
+}

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

@@ -1,4 +1,4 @@
-export type CapabilityApprovalScope = 'once' | 'path';
+export type CapabilityApprovalScope = 'once' | 'path' | 'workspace-root';
 export interface FsScopeAllowlistEntry {
     path: string;
     approvedAt: string;
@@ -8,3 +8,13 @@ export interface FsScopeAllowlistFile {
     version: 1;
     paths: FsScopeAllowlistEntry[];
 }
+export interface TrustedWorkspaceRootEntry {
+    path: string;
+    approvedAt: string;
+    approvalId: string;
+    source?: 'approval';
+}
+export interface TrustedWorkspaceRootsFile {
+    version: 1;
+    roots: TrustedWorkspaceRootEntry[];
+}

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

@@ -1,5 +1,5 @@
 import type { CapabilityApprovalScope } from './capability/types.js';
-import type { BelayConfigV3 } from './config.js';
+import { type BelayConfigV3 } from './config.js';
 import type { ApprovalStateFile } from './types.js';
 export interface CapabilityApprovalStore {
     loadPending: () => Promise<{
@@ -13,6 +13,7 @@ export interface CapabilityApprovalStore {
     writePending: (filePath: string, state: ApprovalStateFile) => Promise<void>;
     writeApproved: (filePath: string, state: ApprovalStateFile) => Promise<void>;
     allowlistPath: string;
+    trustedRootsPath: string;
 }
 export declare function recordCapabilityApproval(params: {
     approvalId: string;

package/dist/core/capability-approval.js

@@ -1,11 +1,13 @@
 import { recordApproval } from './approval-service.js';
 import { addPathToAllowlist, loadFsScopeAllowlist, normalizeAllowlistPath, saveFsScopeAllowlist, } from './capability/allowlist.js';
 import { FS_SCOPE_REASONS } from './capability/reasons.js';
+import { addTrustedWorkspaceRoot, loadTrustedWorkspaceRoots, normalizeTrustedWorkspaceRootPath, saveTrustedWorkspaceRoots, validateTrustedWorkspaceRootCandidate, } from './capability/trusted-workspace-roots.js';
+import { resolveControlPlaneDir } from './config.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)) {
+        if (!match || match.kind !== 'shell' || !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).',
@@ -18,6 +20,85 @@ export async function recordCapabilityApproval(params) {
             };
         }
     }
+    if (params.scope === 'workspace-root') {
+        if (!match || !FS_SCOPE_REASONS.has(match.reason)) {
+            return {
+                ok: false,
+                message: 'workspace-root scope approvals apply only to pending outside-repo actions (outside_repo_mutation / outside_repo_redirect).',
+            };
+        }
+        if (!params.scopePath?.trim()) {
+            return {
+                ok: false,
+                message: 'approve --scope workspace-root requires --path <absolute-directory-path>.',
+            };
+        }
+        if (!match.scopeHint || match.scopeHint.scope !== 'workspace-root') {
+            return {
+                ok: false,
+                message: 'workspace-root approval requires a pending scope hint. Re-run the original blocked action to mint a scoped approval.',
+            };
+        }
+        const normalizedPath = normalizeTrustedWorkspaceRootPath(params.scopePath.trim());
+        const normalizedHint = normalizeTrustedWorkspaceRootPath(match.scopeHint.path);
+        if (normalizedPath !== normalizedHint) {
+            return {
+                ok: false,
+                message: `workspace-root approval path must exactly match the suggested path: ${normalizedHint}`,
+            };
+        }
+        const validation = validateTrustedWorkspaceRootCandidate({
+            candidatePath: normalizedPath,
+            repoRoot: match.repoRoot,
+            controlPlaneDir: params.config.controlPlane.enabled
+                ? resolveControlPlaneDir(params.config)
+                : undefined,
+            requireExistingDirectory: true,
+            requireNonGit: true,
+        });
+        if (!validation.ok) {
+            if (validation.reason === 'not_directory') {
+                return {
+                    ok: false,
+                    message: 'workspace-root approval requires an existing directory path.',
+                };
+            }
+            if (validation.reason === 'broad_root') {
+                return {
+                    ok: false,
+                    message: 'workspace-root approval rejected: broad roots (/, drive root, HOME) are not allowed.',
+                };
+            }
+            if (validation.reason === 'high_stakes') {
+                return {
+                    ok: false,
+                    message: 'workspace-root approval rejected: high-stakes directories cannot be trusted roots.',
+                };
+            }
+            if (validation.reason === 'inside_repo') {
+                return {
+                    ok: false,
+                    message: 'workspace-root approval rejected: the path is already inside the repository root.',
+                };
+            }
+            if (validation.reason === 'inside_git_repo') {
+                return {
+                    ok: false,
+                    message: `workspace-root approval rejected: ${normalizedPath} is under a git repository.`,
+                };
+            }
+            if (validation.reason === 'control_plane_overlap') {
+                return {
+                    ok: false,
+                    message: 'workspace-root approval rejected: control plane paths cannot be trusted roots.',
+                };
+            }
+            return {
+                ok: false,
+                message: 'workspace-root approval rejected by trusted-root policy.',
+            };
+        }
+    }
     const result = await recordApproval({
         approvalId: params.approvalId,
         config: params.config,
@@ -25,9 +106,26 @@ export async function recordCapabilityApproval(params) {
         requireSignedToken: params.requireSignedToken ?? false,
         store: params.store,
     });
-    if (!result.ok || params.scope !== 'path' || !params.scopePath?.trim()) {
+    if (!result.ok ||
+        (params.scope !== 'path' && params.scope !== 'workspace-root') ||
+        !params.scopePath?.trim()) {
         return { ok: result.ok, message: result.message };
     }
+    if (params.scope === 'workspace-root') {
+        const trustedRoots = await loadTrustedWorkspaceRoots(params.store.trustedRootsPath);
+        const normalizedPath = normalizeTrustedWorkspaceRootPath(params.scopePath.trim());
+        const updated = addTrustedWorkspaceRoot(trustedRoots, {
+            path: normalizedPath,
+            approvedAt: new Date().toISOString(),
+            approvalId: params.approvalId,
+            source: 'approval',
+        });
+        await saveTrustedWorkspaceRoots(params.store.trustedRootsPath, updated);
+        return {
+            ok: true,
+            message: `${result.message} Trusted workspace root ${normalizedPath} added.`,
+        };
+    }
     const allowlist = await loadFsScopeAllowlist(params.store.allowlistPath);
     const normalizedPath = normalizeAllowlistPath(params.scopePath.trim());
     const updated = addPathToAllowlist(allowlist, {

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

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

package/dist/core/classify-subagent.js

@@ -1,4 +1,8 @@
+import { BOUNDARY_PROFILE_L3_L4_ONLY } from './capability/boundary-profile.js';
+import { policyReasonToLegacyReason } from './capability/policy-bridge.js';
+import { evaluateSubagentPolicy, policyDecisionRequiresAsk } from './capability/policy-engine.js';
 import { canonicalStringify, subagentFingerprint } from './fingerprint.js';
+import { subagentFingerprintSource } from './replay-scrub.js';
 import { scrubValue } from './scrub.js';
 const EXTERNAL_TERMS = ['deploy', 'production', 'publish', 'release', 'ship', 'notify', 'email'];
 function extractSubagentText(payload, options) {
@@ -22,28 +26,9 @@ function extractSubagentText(payload, options) {
     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);
+    return subagentFingerprintSource(payload, options.scrubOptions ?? {});
 }
-export function classifySubagent(payload, repoRoot, options = {}) {
+export function classifySubagent(payload, repoRoot, options = {}, config) {
     const kind = payload.tool_name === 'Task' ? 'Task' : String(payload.subagent_type ?? 'generalPurpose');
     const scrubbed = fingerprintSource(payload, options);
     const summary = extractSubagentText(payload, options);
@@ -53,6 +38,36 @@ export function classifySubagent(payload, repoRoot, options = {}) {
         const pattern = new RegExp(`\\b${term}\\b`, 'i');
         return pattern.test(lowered);
     });
+    const signals = hasExternalTerm ? ['subagent_external_intent_hint'] : ['subagent_default_review'];
+    const { request, decision } = evaluateSubagentPolicy({
+        subagentType: kind,
+        summary,
+        repoRoot,
+        cwd: repoRoot,
+        inputFingerprint: fingerprint,
+        signals,
+    }, config, {
+        grants: options.grants,
+        attestation: options.attestation,
+        egressProxyActive: options.egressProxyActive,
+    });
+    if (policyDecisionRequiresAsk(decision)) {
+        return {
+            verdict: 'deny_pending_approval',
+            reason: policyReasonToLegacyReason(decision),
+            summary,
+            fingerprint,
+            assessment: {
+                reversibility: 'recoverable_with_cost',
+                external: hasExternalTerm,
+                blastRadius: 'subagent task scope',
+                confidence: hasExternalTerm ? 0.7 : 0.67,
+                signals: [...signals, ...decision.signals],
+            },
+            capabilityRequests: [request],
+            authorizationDecision: decision,
+        };
+    }
     return {
         verdict: 'allow_flagged',
         reason: 'subagent_review',
@@ -63,7 +78,10 @@ export function classifySubagent(payload, repoRoot, options = {}) {
             external: false,
             blastRadius: 'subagent task scope',
             confidence: hasExternalTerm ? 0.7 : 0.67,
-            signals: hasExternalTerm ? ['subagent_external_intent_hint'] : ['subagent_default_review'],
+            signals,
         },
+        capabilityRequests: [request],
+        authorizationDecision: decision,
+        boundaryProfile: options.boundaryProfile ?? BOUNDARY_PROFILE_L3_L4_ONLY,
     };
 }