@guilz-dev/belay 0.3.0 → 0.6.0

package/dist/core/capability/policy-engine.js

@@ -0,0 +1,476 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { matchesSensitivePath } from '../glob.js';
+import { canonicalPath, pathWithinRoot, resolveWorkspaceRootMatch } from '../path-utils.js';
+import { BOUNDARY_GRANT_ISSUER_CONTAINER, isPathWithinBoundaryMount, materializeContainerBoundaryGrant, } from './boundary-grant-materialize.js';
+import { boundaryVerifiedAllowEnabled } from './boundary-profile.js';
+import { isGrantScopeTooBroad } from './grant.js';
+import { broadGrantTargetsRequest, grantMatchesRequest } from './grant-match.js';
+import { CAPABILITY_REQUEST_VERSION, } from './request.js';
+function enrichAuthWithMaterializedGrants(request, config, auth) {
+    if (!auth?.attestation || !boundaryVerifiedAllowEnabled(auth.attestation)) {
+        return auth;
+    }
+    const materialized = materializeContainerBoundaryGrant(request, {
+        attestation: auth.attestation,
+        mountRoot: request.context.cwd,
+        egressProxyActive: auth.egressProxyActive === true,
+        existingGrants: auth.grants,
+        sensitivePaths: auth.sensitivePaths ?? config.classifier.sensitivePaths,
+    });
+    if (!materialized) {
+        return auth;
+    }
+    return { ...auth, grants: [...(auth.grants ?? []), materialized] };
+}
+function buildAuthorizationContext(config, trustedWorkspaceRoots, auth) {
+    return {
+        config,
+        grants: auth?.grants,
+        attestation: auth?.attestation ?? null,
+        trustedWorkspaceRoots,
+    };
+}
+export function buildSubagentCapabilityRequest(analysis) {
+    return {
+        version: CAPABILITY_REQUEST_VERSION,
+        principal: {
+            adapter: analysis.adapter,
+            repoRoot: analysis.repoRoot,
+            sessionHash: hashSession(`${analysis.repoRoot}:${analysis.cwd}`),
+        },
+        action: 'process.exec',
+        resource: { kind: 'executable', command: analysis.subagentType },
+        context: {
+            cwd: analysis.cwd,
+            inputFingerprint: analysis.inputFingerprint,
+            hookKind: 'subagent',
+            analysisBasis: [`subagent:${analysis.subagentType}`],
+        },
+        evidence: {
+            level: 'possible',
+            signals: [...analysis.signals],
+        },
+    };
+}
+export function evaluateSubagentPolicy(analysis, config, auth) {
+    const request = buildSubagentCapabilityRequest(analysis);
+    const enriched = enrichAuthWithMaterializedGrants(request, config, auth);
+    const decision = getDefaultPolicyEngine().evaluate(request, buildAuthorizationContext(config, undefined, enriched));
+    return { request, decision };
+}
+function hashSession(value) {
+    return createHash('sha256').update(value).digest('hex').slice(0, 16);
+}
+function resolveCapabilityPath(targetPath, cwd) {
+    const joined = path.isAbsolute(targetPath) ? targetPath : path.join(cwd, targetPath);
+    return canonicalPath(joined);
+}
+function evidenceLevelForOpacity(opacity) {
+    if (opacity === 'transparent' || opacity === 'recursive') {
+        return 'certain';
+    }
+    if (opacity === 'opaque') {
+        return 'possible';
+    }
+    return 'indeterminate';
+}
+function isGitRefWrite(analysis) {
+    if (analysis.segmentHead !== 'git') {
+        return false;
+    }
+    return analysis.signals.includes('git.push');
+}
+function actionForShellAnalysis(analysis) {
+    if (isGitRefWrite(analysis)) {
+        return 'git.ref.write';
+    }
+    if (analysis.effect === 'remote_mutation' ||
+        analysis.egressClass === 'ambiguous' ||
+        analysis.egressClass === 'read' ||
+        analysis.egressClass === 'destructive') {
+        return 'network.connect';
+    }
+    if (analysis.opacity === 'unparseable' || analysis.effect === 'unknown') {
+        return 'indeterminate';
+    }
+    if (analysis.effect === 'read_only') {
+        return 'fs.read';
+    }
+    if (analysis.location === 'external') {
+        return 'network.connect';
+    }
+    if (analysis.effect === 'local_mutation') {
+        return 'fs.write';
+    }
+    return 'indeterminate';
+}
+function resourcePathForShellAnalysis(analysis) {
+    const targets = analysis.resolvedPathTargets && analysis.resolvedPathTargets.length > 0
+        ? analysis.resolvedPathTargets
+        : analysis.pathArgs;
+    if (targets.length === 0) {
+        return null;
+    }
+    const repoRoot = canonicalPath(analysis.repoRoot);
+    const resolved = targets.map((target) => analysis.resolvedPathTargets?.length
+        ? canonicalPath(target)
+        : resolveCapabilityPath(target, analysis.cwd));
+    if (analysis.effect === 'local_mutation') {
+        const outside = resolved.find((candidate) => !pathWithinRoot(repoRoot, candidate));
+        return outside ?? resolved[resolved.length - 1];
+    }
+    return resolved[0];
+}
+function resourceForShellAnalysis(analysis) {
+    if (isGitRefWrite(analysis)) {
+        return { kind: 'git-ref', ref: 'push' };
+    }
+    if (analysis.egressClass === 'ambiguous' ||
+        analysis.egressClass === 'read' ||
+        analysis.egressClass === 'destructive' ||
+        analysis.location === 'external') {
+        return { kind: 'network', host: '*', protocol: 'unknown' };
+    }
+    const resourcePath = resourcePathForShellAnalysis(analysis);
+    if (resourcePath) {
+        return { kind: 'path', path: resourcePath };
+    }
+    return { kind: 'executable', command: analysis.segmentHead };
+}
+export function buildShellCapabilityRequest(analysis) {
+    return {
+        version: CAPABILITY_REQUEST_VERSION,
+        principal: {
+            adapter: analysis.adapter,
+            repoRoot: analysis.repoRoot,
+            sessionHash: hashSession(`${analysis.repoRoot}:${analysis.cwd}`),
+        },
+        action: actionForShellAnalysis(analysis),
+        resource: resourceForShellAnalysis(analysis),
+        context: {
+            cwd: analysis.cwd,
+            inputFingerprint: analysis.inputFingerprint,
+            hookKind: analysis.hookKind,
+            analysisBasis: [
+                `segment:${analysis.segmentHead}`,
+                `effect:${analysis.effect}`,
+                `location:${analysis.location}`,
+                `opacity:${analysis.opacity}`,
+            ],
+        },
+        evidence: {
+            level: evidenceLevelForOpacity(analysis.opacity),
+            signals: [...analysis.signals],
+        },
+    };
+}
+function actionForFileMutation(analysis) {
+    if (analysis.locationLabel === 'control_plane') {
+        return 'control_plane.write';
+    }
+    if (analysis.locationLabel === 'sensitive_path') {
+        return 'fs.write';
+    }
+    if (analysis.isDelete) {
+        return 'fs.write';
+    }
+    return 'fs.write';
+}
+export function buildFileMutationCapabilityRequest(analysis) {
+    return {
+        version: CAPABILITY_REQUEST_VERSION,
+        principal: {
+            adapter: analysis.adapter,
+            repoRoot: analysis.repoRoot,
+            sessionHash: hashSession(`${analysis.repoRoot}:${analysis.cwd}`),
+        },
+        action: actionForFileMutation(analysis),
+        resource: { kind: 'path', path: analysis.resolvedPath },
+        context: {
+            cwd: analysis.cwd,
+            inputFingerprint: analysis.inputFingerprint,
+            hookKind: analysis.hookKind,
+            analysisBasis: [
+                `tool:${analysis.toolKind}`,
+                `location:${analysis.locationLabel}`,
+                analysis.isDelete ? 'delete' : 'write',
+            ],
+        },
+        evidence: {
+            level: analysis.locationLabel === 'repo_local' ? 'certain' : 'possible',
+            signals: [...analysis.signals],
+        },
+    };
+}
+function findFreshGrant(request, grants) {
+    if (!grants?.length) {
+        return null;
+    }
+    const now = Date.now();
+    for (const grant of grants) {
+        const expires = Date.parse(grant.expiresAt);
+        if (Number.isFinite(expires) && expires > now && grantMatchesRequest(grant, request)) {
+            return grant;
+        }
+    }
+    return null;
+}
+function hasFreshGrant(request, grants) {
+    return findFreshGrant(request, grants) !== null;
+}
+function grantDecisionSignals(request, grant) {
+    const signals = [...request.evidence.signals, 'capability_grant'];
+    if (grant.issuer === BOUNDARY_GRANT_ISSUER_CONTAINER) {
+        signals.push('boundary_materialized_grant');
+    }
+    return signals;
+}
+function shellLocationFromRequest(request) {
+    const entry = request.context.analysisBasis.find((basis) => basis.startsWith('location:'));
+    return entry?.slice('location:'.length) ?? null;
+}
+function isRepoLocalShellLocation(request) {
+    return shellLocationFromRequest(request) === 'repo_local';
+}
+function isRepoLocalRoutineWrite(request, sensitivePaths) {
+    if (!isRepoLocalShellLocation(request)) {
+        return false;
+    }
+    if (request.action !== 'fs.write' && request.action !== 'fs.read') {
+        return false;
+    }
+    if (request.resource.kind !== 'path') {
+        return false;
+    }
+    const resolved = resolveCapabilityPath(request.resource.path, request.context.cwd);
+    const repoRoot = canonicalPath(request.principal.repoRoot);
+    if (!pathWithinRoot(repoRoot, resolved)) {
+        return false;
+    }
+    const relative = resolved.slice(repoRoot.length).replace(/^[/\\]/, '');
+    return !matchesSensitivePath(relative, sensitivePaths);
+}
+function isTrustedWorkspaceWrite(request, trustedWorkspaceRoots) {
+    if (!trustedWorkspaceRoots?.length || request.resource.kind !== 'path') {
+        return false;
+    }
+    const match = resolveWorkspaceRootMatch(request.principal.repoRoot, trustedWorkspaceRoots, request.resource.path);
+    return match?.kind === 'trusted';
+}
+/**
+ * boundary.verified widens only when builtin already allows, or a boundary-materialized
+ * grant is present for an approved high-risk action (network via egress chokepoint).
+ */
+function verifiedBoundaryAllows(request, context) {
+    if (!boundaryVerifiedAllowEnabled(context.attestation)) {
+        return false;
+    }
+    if (request.evidence.level !== 'certain') {
+        return false;
+    }
+    const builtin = builtInRule(request, context);
+    if (builtin?.outcome === 'allow') {
+        return isPathWithinBoundaryMount(request);
+    }
+    if (builtin?.outcome === 'deny') {
+        return false;
+    }
+    return hasFreshGrant(request, context.grants?.filter((grant) => grant.issuer === BOUNDARY_GRANT_ISSUER_CONTAINER));
+}
+function builtInRule(request, context) {
+    const trustedWorkspaceRoots = context.trustedWorkspaceRoots;
+    const sensitivePaths = context.config.classifier.sensitivePaths;
+    if (request.action === 'control_plane.write') {
+        return {
+            outcome: 'require_approval',
+            reason: 'control_plane_mutation',
+            signals: [...request.evidence.signals, 'control_plane_path'],
+            matchedRule: 'builtin.control_plane',
+        };
+    }
+    if (request.action === 'process.exec' && request.context.hookKind === 'subagent') {
+        return {
+            outcome: 'allow',
+            reason: 'subagent_review',
+            signals: [...request.evidence.signals],
+            matchedRule: 'builtin.subagent',
+        };
+    }
+    if (request.action === 'secret.read' || request.action === 'git.ref.write') {
+        return {
+            outcome: 'require_approval',
+            reason: 'high_stakes_path',
+            signals: [...request.evidence.signals, 'secret_path'],
+            matchedRule: 'builtin.secret',
+        };
+    }
+    if (request.action === 'network.connect') {
+        return {
+            outcome: 'require_approval',
+            reason: 'external_effect',
+            signals: [...request.evidence.signals, 'network_connect'],
+            matchedRule: 'builtin.network',
+        };
+    }
+    if (request.action === 'indeterminate' || request.evidence.level === 'indeterminate') {
+        return {
+            outcome: 'require_approval',
+            reason: 'indeterminate_effect',
+            signals: [...request.evidence.signals, 'indeterminate'],
+            matchedRule: 'builtin.indeterminate',
+        };
+    }
+    if (request.resource.kind === 'path' && sensitivePaths?.length) {
+        const repoRoot = canonicalPath(request.principal.repoRoot);
+        const resolved = resolveCapabilityPath(request.resource.path, request.context.cwd);
+        if (pathWithinRoot(repoRoot, resolved)) {
+            const relative = resolved.slice(repoRoot.length).replace(/^[/\\]/, '');
+            if (matchesSensitivePath(relative, sensitivePaths)) {
+                return {
+                    outcome: 'require_approval',
+                    reason: 'high_stakes_path',
+                    signals: [...request.evidence.signals, 'sensitive_path'],
+                    matchedRule: 'builtin.sensitive_path',
+                };
+            }
+        }
+    }
+    if (request.resource.kind === 'path') {
+        const repoRoot = canonicalPath(request.principal.repoRoot);
+        const resolved = resolveCapabilityPath(request.resource.path, request.context.cwd);
+        const insideRepo = pathWithinRoot(repoRoot, resolved);
+        if (!insideRepo && !isTrustedWorkspaceWrite(request, trustedWorkspaceRoots)) {
+            return {
+                outcome: 'require_approval',
+                reason: 'outside_repo_mutation',
+                signals: [...request.evidence.signals, 'outside_repo_path'],
+                matchedRule: 'builtin.outside_repo',
+            };
+        }
+    }
+    if (request.action === 'fs.read' || request.action === 'fs.write') {
+        if (request.action === 'fs.read' &&
+            request.resource.kind === 'executable' &&
+            isRepoLocalShellLocation(request)) {
+            return {
+                outcome: 'allow',
+                reason: 'read_only',
+                signals: [...request.evidence.signals],
+                matchedRule: 'builtin.repo_local',
+            };
+        }
+        if (isRepoLocalRoutineWrite(request, sensitivePaths)) {
+            return {
+                outcome: 'allow',
+                reason: request.action === 'fs.read' ? 'read_only' : 'repo_local_mutation',
+                signals: [...request.evidence.signals],
+                matchedRule: 'builtin.repo_local',
+            };
+        }
+        if (isTrustedWorkspaceWrite(request, trustedWorkspaceRoots)) {
+            return {
+                outcome: 'allow',
+                reason: 'trusted_workspace_root',
+                signals: [...request.evidence.signals, 'trusted_workspace_root'],
+                matchedRule: 'builtin.trusted_workspace',
+            };
+        }
+    }
+    if (request.evidence.signals.includes('unparseable_shell')) {
+        const deny = context.config.policy.unparseableShell === 'deny';
+        return {
+            outcome: deny ? 'require_approval' : 'allow',
+            reason: 'unparseable_shell',
+            signals: [...request.evidence.signals],
+            matchedRule: deny ? 'builtin.unparseable' : 'builtin.unparseable_allow_flagged',
+        };
+    }
+    if (request.evidence.signals.includes('opaque_execution')) {
+        return {
+            outcome: 'require_approval',
+            reason: 'opaque_execution',
+            signals: [...request.evidence.signals],
+            matchedRule: 'builtin.opaque',
+        };
+    }
+    return null;
+}
+export function createTypeScriptPolicyEngine() {
+    return {
+        evaluate(request, context) {
+            if (request.evidence.signals.includes('forged_grant')) {
+                return {
+                    outcome: 'deny',
+                    reason: 'grant_forgery',
+                    signals: [...request.evidence.signals, 'grant_forgery'],
+                    matchedRule: 'forbid.grant_forgery',
+                };
+            }
+            const grants = context.grants;
+            if (grants?.some((grant) => isGrantScopeTooBroad(grant) && broadGrantTargetsRequest(grant, request))) {
+                return {
+                    outcome: 'deny',
+                    reason: 'grant_scope_too_broad',
+                    signals: [...request.evidence.signals, 'grant_scope_too_broad'],
+                    matchedRule: 'forbid.broad_grant',
+                };
+            }
+            const matchedGrant = findFreshGrant(request, grants);
+            if (matchedGrant) {
+                return {
+                    outcome: 'allow',
+                    reason: 'capability_grant',
+                    signals: grantDecisionSignals(request, matchedGrant),
+                    matchedRule: 'grant.exact',
+                };
+            }
+            if (verifiedBoundaryAllows(request, context)) {
+                return {
+                    outcome: 'allow',
+                    reason: 'verified_boundary',
+                    signals: [...request.evidence.signals, 'verified_boundary'],
+                    matchedRule: 'boundary.verified',
+                };
+            }
+            const builtin = builtInRule(request, context);
+            if (builtin) {
+                return builtin;
+            }
+            return {
+                outcome: 'require_approval',
+                reason: 'policy_default',
+                signals: [...request.evidence.signals, 'default_deny'],
+                matchedRule: 'default.require_approval',
+            };
+        },
+    };
+}
+let defaultPolicyEngine = null;
+export function getDefaultPolicyEngine() {
+    if (!defaultPolicyEngine) {
+        defaultPolicyEngine = createTypeScriptPolicyEngine();
+    }
+    return defaultPolicyEngine;
+}
+export function policyDecisionRequiresAsk(decision) {
+    return decision.outcome === 'require_approval' || decision.outcome === 'deny';
+}
+export function evaluateShellPolicy(analysis, config, auth) {
+    const request = buildShellCapabilityRequest(analysis);
+    const enriched = enrichAuthWithMaterializedGrants(request, config, {
+        ...auth,
+        sensitivePaths: auth?.sensitivePaths ?? analysis.sensitivePaths,
+    });
+    const decision = getDefaultPolicyEngine().evaluate(request, buildAuthorizationContext(config, analysis.trustedWorkspaceRoots, enriched));
+    return { request, decision };
+}
+export function evaluateFileMutationPolicy(analysis, config, auth) {
+    const request = buildFileMutationCapabilityRequest(analysis);
+    const enriched = enrichAuthWithMaterializedGrants(request, config, {
+        ...auth,
+        sensitivePaths: auth?.sensitivePaths ?? analysis.sensitivePaths,
+    });
+    const decision = getDefaultPolicyEngine().evaluate(request, buildAuthorizationContext(config, analysis.trustedWorkspaceRoots, enriched));
+    return { request, decision };
+}

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

@@ -0,0 +1,20 @@
+import type { BelayConfigV4 } from '../config.js';
+import type { BoundaryAttestation } from './attestation.js';
+import type { CapabilityGrantV1 } from './grant.js';
+import type { CapabilityRequestV1 } from './request.js';
+export type PolicyOutcome = 'allow' | 'require_approval' | 'deny';
+export interface PolicyDecision {
+    outcome: PolicyOutcome;
+    reason: string;
+    signals: string[];
+    matchedRule?: string;
+}
+export interface AuthorizationContext {
+    config: BelayConfigV4;
+    grants?: CapabilityGrantV1[];
+    attestation?: BoundaryAttestation | null;
+    trustedWorkspaceRoots?: string[];
+}
+export interface PolicyEngine {
+    evaluate(request: CapabilityRequestV1, context: AuthorizationContext): PolicyDecision;
+}

package/dist/core/capability/policy-types.js

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

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

@@ -0,0 +1,45 @@
+export declare const CAPABILITY_REQUEST_VERSION: 1;
+export type CapabilityAction = 'fs.read' | 'fs.write' | 'process.exec' | 'network.connect' | 'secret.read' | 'git.ref.write' | 'control_plane.write' | 'indeterminate';
+export type CapabilityEvidenceLevel = 'certain' | 'possible' | 'indeterminate';
+export type CapabilityHookKind = 'shell' | 'tool' | 'subagent';
+export interface CapabilityPrincipal {
+    adapter?: string;
+    repoRoot: string;
+    sessionHash?: string;
+}
+export type CapabilityResource = {
+    kind: 'path';
+    path: string;
+} | {
+    kind: 'network';
+    host: string;
+    port?: number;
+    protocol?: string;
+} | {
+    kind: 'executable';
+    command: string;
+} | {
+    kind: 'git-ref';
+    ref: string;
+} | {
+    kind: 'unknown';
+};
+export interface CapabilityRequestContext {
+    cwd: string;
+    inputFingerprint: string;
+    hookKind: CapabilityHookKind;
+    analysisBasis: string[];
+    boundaryProfile?: string;
+}
+export interface CapabilityEvidence {
+    level: CapabilityEvidenceLevel;
+    signals: string[];
+}
+export interface CapabilityRequestV1 {
+    version: typeof CAPABILITY_REQUEST_VERSION;
+    principal: CapabilityPrincipal;
+    action: CapabilityAction;
+    resource: CapabilityResource;
+    context: CapabilityRequestContext;
+    evidence: CapabilityEvidence;
+}

package/dist/core/capability/request.js

@@ -0,0 +1 @@
+export const CAPABILITY_REQUEST_VERSION = 1;

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

@@ -0,0 +1,4 @@
+export { evaluateSegmentShellPolicy, type SegmentShellPolicyInput, } from '../verdict/shell-policy.js';
+export { BOUNDARY_PROFILE_L3_POLICY, checkGatedActionLimits } from './limits.js';
+export { type CapabilityAuthorizationMetadata, policyReasonToLegacyReason, singleCapabilityMetadata, } from './policy-bridge.js';
+export { buildFileMutationCapabilityRequest, buildShellCapabilityRequest, buildSubagentCapabilityRequest, evaluateFileMutationPolicy, evaluateShellPolicy, evaluateSubagentPolicy, type FileMutationCapabilityAnalysis, policyDecisionRequiresAsk, type ShellCapabilityAnalysis, type SubagentCapabilityAnalysis, } from './policy-engine.js';

package/dist/core/capability/resolver.js

@@ -0,0 +1,4 @@
+export { evaluateSegmentShellPolicy, } from '../verdict/shell-policy.js';
+export { BOUNDARY_PROFILE_L3_POLICY, checkGatedActionLimits } from './limits.js';
+export { policyReasonToLegacyReason, singleCapabilityMetadata, } from './policy-bridge.js';
+export { buildFileMutationCapabilityRequest, buildShellCapabilityRequest, buildSubagentCapabilityRequest, evaluateFileMutationPolicy, evaluateShellPolicy, evaluateSubagentPolicy, policyDecisionRequiresAsk, } from './policy-engine.js';

package/dist/core/capability/trusted-workspace-roots.d.ts

@@ -0,0 +1,25 @@
+import type { BelayConfigV3 } from '../config.js';
+import type { TrustedWorkspaceRootEntry, TrustedWorkspaceRootsFile } from './types.js';
+export declare function trustedWorkspaceRootsPath(config: BelayConfigV3, repoLocalStateDir: string): string;
+export declare function loadTrustedWorkspaceRoots(filePath: string): Promise<TrustedWorkspaceRootsFile>;
+export declare function loadTrustedWorkspaceRootsSync(filePath: string): TrustedWorkspaceRootsFile;
+export declare function saveTrustedWorkspaceRoots(filePath: string, state: TrustedWorkspaceRootsFile): Promise<void>;
+export declare function normalizeTrustedWorkspaceRootPath(targetPath: string): string;
+export interface TrustedWorkspaceRootValidationParams {
+    candidatePath: string;
+    repoRoot: string;
+    controlPlaneDir?: string | null;
+    protectedRoots?: string[];
+    requireExistingDirectory?: boolean;
+    requireNonGit?: boolean;
+}
+export interface TrustedWorkspaceRootValidationResult {
+    ok: boolean;
+    normalizedPath: string;
+    reason?: 'not_directory' | 'broad_root' | 'high_stakes' | 'inside_repo' | 'inside_git_repo' | 'control_plane_overlap' | 'protected_root_overlap';
+}
+export declare function isBroadTrustedWorkspaceRoot(targetPath: string): boolean;
+export declare function isHighStakesTrustedWorkspaceRoot(targetPath: string): boolean;
+export declare function validateTrustedWorkspaceRootCandidate(params: TrustedWorkspaceRootValidationParams): TrustedWorkspaceRootValidationResult;
+export declare function isPathWithinTrustedWorkspaceRoots(absolutePath: string, roots: TrustedWorkspaceRootsFile): boolean;
+export declare function addTrustedWorkspaceRoot(roots: TrustedWorkspaceRootsFile, entry: TrustedWorkspaceRootEntry): TrustedWorkspaceRootsFile;