@guilz-dev/belay 0.3.0 → 0.6.0

package/dist/core/capability/grant-match.js

@@ -0,0 +1,93 @@
+import { canonicalPath } from '../path-utils.js';
+import { isGrantScopeTooBroad } from './grant.js';
+function principalMatches(grant, request) {
+    if (grant.repoRoot !== request.repoRoot) {
+        return false;
+    }
+    if (request.adapter !== undefined && grant.adapter !== request.adapter) {
+        return false;
+    }
+    if (request.sessionHash !== undefined && grant.sessionHash !== request.sessionHash) {
+        return false;
+    }
+    if (grant.adapter !== undefined && grant.adapter !== request.adapter) {
+        return false;
+    }
+    if (grant.sessionHash !== undefined && grant.sessionHash !== request.sessionHash) {
+        return false;
+    }
+    return true;
+}
+function networkResourceMatches(grant, request) {
+    if (grant.host !== request.host) {
+        return false;
+    }
+    if (grant.port !== undefined && grant.port !== request.port) {
+        return false;
+    }
+    if (grant.protocol !== undefined &&
+        grant.protocol !== 'unknown' &&
+        request.protocol !== undefined &&
+        request.protocol !== 'unknown' &&
+        grant.protocol !== request.protocol) {
+        return false;
+    }
+    return true;
+}
+function grantTargetsResource(grant, request) {
+    if (grant.action !== request.action) {
+        if (grant.action === 'indeterminate') {
+            return request.action === 'indeterminate';
+        }
+        return false;
+    }
+    if (grant.inputFingerprint && grant.inputFingerprint !== request.context.inputFingerprint) {
+        return false;
+    }
+    if (grant.resource.kind === 'path' && request.resource.kind === 'path') {
+        return canonicalPath(grant.resource.path) === canonicalPath(request.resource.path);
+    }
+    if (grant.resource.kind === 'network' && request.resource.kind === 'network') {
+        return networkResourceMatches(grant.resource, request.resource);
+    }
+    if (grant.resource.kind === 'executable' && request.resource.kind === 'executable') {
+        return grant.resource.command === request.resource.command;
+    }
+    if (grant.resource.kind === 'git-ref' && request.resource.kind === 'git-ref') {
+        return grant.resource.ref === request.resource.ref;
+    }
+    if (grant.resource.kind === 'unknown') {
+        if (grant.action === 'network.connect' && request.resource.kind === 'network') {
+            return true;
+        }
+        if (grant.action === 'fs.write' && request.resource.kind === 'path') {
+            return true;
+        }
+        if (grant.action === 'indeterminate') {
+            return request.action === 'indeterminate';
+        }
+    }
+    return grant.resource.kind === request.resource.kind;
+}
+export function grantTargetsRequest(grant, request) {
+    if (grant.usesRemaining <= 0) {
+        return false;
+    }
+    if (!principalMatches(grant.principal, request.principal)) {
+        return false;
+    }
+    return grantTargetsResource(grant, request);
+}
+/** Repo-scoped target match for forged broad-grant detection (principal may be incomplete). */
+export function broadGrantTargetsRequest(grant, request) {
+    if (grant.principal.repoRoot !== request.principal.repoRoot) {
+        return false;
+    }
+    return grantTargetsResource(grant, request);
+}
+export function grantMatchesRequest(grant, request) {
+    if (isGrantScopeTooBroad(grant)) {
+        return false;
+    }
+    return grantTargetsRequest(grant, request);
+}

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

@@ -0,0 +1,16 @@
+import type { CapabilityAction, CapabilityPrincipal, CapabilityResource } from './request.js';
+export declare const CAPABILITY_GRANT_VERSION: 1;
+export interface CapabilityGrantV1 {
+    version: typeof CAPABILITY_GRANT_VERSION;
+    grantId: string;
+    principal: CapabilityPrincipal;
+    action: CapabilityAction;
+    resource: CapabilityResource;
+    inputFingerprint?: string;
+    issuedAt: string;
+    expiresAt: string;
+    maxUses: number;
+    usesRemaining: number;
+    issuer: string;
+}
+export declare function isGrantScopeTooBroad(grant: CapabilityGrantV1): boolean;

package/dist/core/capability/grant.js

@@ -0,0 +1,16 @@
+export const CAPABILITY_GRANT_VERSION = 1;
+export function isGrantScopeTooBroad(grant) {
+    if (grant.action === 'network.connect' && grant.resource.kind === 'unknown') {
+        return true;
+    }
+    if (grant.resource.kind === 'network' && grant.resource.host === '*') {
+        return true;
+    }
+    if (grant.action === 'fs.write' && grant.resource.kind === 'unknown') {
+        return true;
+    }
+    if (grant.action === 'indeterminate') {
+        return true;
+    }
+    return false;
+}

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

@@ -1,5 +1,14 @@
 export { addPathToAllowlist, allPathsAllowlisted, fsScopeAllowlistPath, isPathAllowlisted, loadFsScopeAllowlist, loadFsScopeAllowlistSync, saveFsScopeAllowlist, } from './allowlist.js';
+export { BOUNDARY_ATTESTATION_VERSION, type BoundaryAttestation, type BoundaryDriverId, isAttestationFresh, } from './attestation.js';
+export { BOUNDARY_PROFILE_L1_ATTESTED, BOUNDARY_PROFILE_L3_L4_ONLY, BOUNDARY_PROFILE_L3_POLICY, boundaryVerifiedAllowEnabled, isAttestedBoundary, resolveBoundaryProfile, } from './boundary-profile.js';
 export { evaluateL1FullStatus, hasSandboxRuntime, isCapabilityBrokerDemotionActive, isSandboxBrokerEnabled, } from './broker.js';
+export { CAPABILITY_GRANT_VERSION, type CapabilityGrantV1, isGrantScopeTooBroad, } from './grant.js';
+export { checkGatedActionLimits, MAX_SHELL_COMMAND_BYTES, MAX_TOOL_PAYLOAD_BYTES, } from './limits.js';
 export { collectOutsideRepoPaths, collectOutsideRepoPathsFromToolPayload } from './paths.js';
+export { type CapabilityAuthorizationMetadata, type PolicyLegacyReasonHints, policyDecisionToLegacyReason, policyReasonToLegacyReason, singleCapabilityMetadata, } from './policy-bridge.js';
+export { buildFileMutationCapabilityRequest, buildShellCapabilityRequest, createTypeScriptPolicyEngine, evaluateFileMutationPolicy, evaluateShellPolicy, evaluateSubagentPolicy, type FileMutationCapabilityAnalysis, getDefaultPolicyEngine, policyDecisionRequiresAsk, type ShellCapabilityAnalysis, type SubagentCapabilityAnalysis, } from './policy-engine.js';
+export type { AuthorizationContext, PolicyDecision, PolicyEngine, PolicyOutcome, } from './policy-types.js';
 export { FS_SCOPE_REASONS, shouldSkipBrokerApprovedOnce, shouldSkipBrokerApprovedRecord, } from './reasons.js';
-export type { CapabilityApprovalScope, FsScopeAllowlistEntry, FsScopeAllowlistFile, } from './types.js';
+export { CAPABILITY_REQUEST_VERSION, type CapabilityAction, type CapabilityEvidence, type CapabilityEvidenceLevel, type CapabilityHookKind, type CapabilityPrincipal, type CapabilityRequestContext, type CapabilityRequestV1, type CapabilityResource, } from './request.js';
+export { addTrustedWorkspaceRoot, isBroadTrustedWorkspaceRoot, isHighStakesTrustedWorkspaceRoot, isPathWithinTrustedWorkspaceRoots, loadTrustedWorkspaceRoots, loadTrustedWorkspaceRootsSync, normalizeTrustedWorkspaceRootPath, saveTrustedWorkspaceRoots, trustedWorkspaceRootsPath, validateTrustedWorkspaceRootCandidate, } from './trusted-workspace-roots.js';
+export type { CapabilityApprovalScope, FsScopeAllowlistEntry, FsScopeAllowlistFile, TrustedWorkspaceRootEntry, TrustedWorkspaceRootsFile, } from './types.js';

package/dist/core/capability/index.js

@@ -1,4 +1,12 @@
 export { addPathToAllowlist, allPathsAllowlisted, fsScopeAllowlistPath, isPathAllowlisted, loadFsScopeAllowlist, loadFsScopeAllowlistSync, saveFsScopeAllowlist, } from './allowlist.js';
+export { BOUNDARY_ATTESTATION_VERSION, isAttestationFresh, } from './attestation.js';
+export { BOUNDARY_PROFILE_L1_ATTESTED, BOUNDARY_PROFILE_L3_L4_ONLY, BOUNDARY_PROFILE_L3_POLICY, boundaryVerifiedAllowEnabled, isAttestedBoundary, resolveBoundaryProfile, } from './boundary-profile.js';
 export { evaluateL1FullStatus, hasSandboxRuntime, isCapabilityBrokerDemotionActive, isSandboxBrokerEnabled, } from './broker.js';
+export { CAPABILITY_GRANT_VERSION, isGrantScopeTooBroad, } from './grant.js';
+export { checkGatedActionLimits, MAX_SHELL_COMMAND_BYTES, MAX_TOOL_PAYLOAD_BYTES, } from './limits.js';
 export { collectOutsideRepoPaths, collectOutsideRepoPathsFromToolPayload } from './paths.js';
+export { policyDecisionToLegacyReason, policyReasonToLegacyReason, singleCapabilityMetadata, } from './policy-bridge.js';
+export { buildFileMutationCapabilityRequest, buildShellCapabilityRequest, createTypeScriptPolicyEngine, evaluateFileMutationPolicy, evaluateShellPolicy, evaluateSubagentPolicy, getDefaultPolicyEngine, policyDecisionRequiresAsk, } from './policy-engine.js';
 export { FS_SCOPE_REASONS, shouldSkipBrokerApprovedOnce, shouldSkipBrokerApprovedRecord, } from './reasons.js';
+export { CAPABILITY_REQUEST_VERSION, } from './request.js';
+export { addTrustedWorkspaceRoot, isBroadTrustedWorkspaceRoot, isHighStakesTrustedWorkspaceRoot, isPathWithinTrustedWorkspaceRoots, loadTrustedWorkspaceRoots, loadTrustedWorkspaceRootsSync, normalizeTrustedWorkspaceRootPath, saveTrustedWorkspaceRoots, trustedWorkspaceRootsPath, validateTrustedWorkspaceRootCandidate, } from './trusted-workspace-roots.js';

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

@@ -0,0 +1,7 @@
+import type { GatedAction } from '../gate-contract.js';
+import type { ClassifyResult } from '../types.js';
+import { BOUNDARY_PROFILE_L3_POLICY } from './boundary-profile.js';
+export { BOUNDARY_PROFILE_L3_POLICY };
+export declare const MAX_SHELL_COMMAND_BYTES: number;
+export declare const MAX_TOOL_PAYLOAD_BYTES: number;
+export declare function checkGatedActionLimits(action: GatedAction): ClassifyResult | null;

package/dist/core/capability/limits.js

@@ -0,0 +1,55 @@
+import { BOUNDARY_PROFILE_L3_POLICY } from './boundary-profile.js';
+export { BOUNDARY_PROFILE_L3_POLICY };
+export const MAX_SHELL_COMMAND_BYTES = 64 * 1024;
+export const MAX_TOOL_PAYLOAD_BYTES = 1024 * 1024;
+function limitExceededResult(reason, summary) {
+    return {
+        verdict: 'deny_pending_approval',
+        reason,
+        fingerprint: `limit:${reason}`,
+        summary,
+        assessment: {
+            reversibility: 'irreversible',
+            external: false,
+            blastRadius: 'gate input budget',
+            confidence: 1,
+            signals: [reason, 'analysis_budget_exceeded'],
+        },
+        boundaryProfile: BOUNDARY_PROFILE_L3_POLICY,
+    };
+}
+function shellCommandFromAction(action) {
+    if (action.command?.trim()) {
+        return action.command.trim();
+    }
+    const payload = action.payload;
+    if (!payload) {
+        return '';
+    }
+    const direct = payload.command;
+    if (typeof direct === 'string' && direct.trim()) {
+        return direct.trim();
+    }
+    const toolInput = payload.tool_input;
+    if (toolInput && typeof toolInput === 'object') {
+        const command = toolInput.command;
+        if (typeof command === 'string' && command.trim()) {
+            return command.trim();
+        }
+    }
+    return '';
+}
+export function checkGatedActionLimits(action) {
+    if (action.kind === 'shell') {
+        const command = shellCommandFromAction(action);
+        if (Buffer.byteLength(command, 'utf8') > MAX_SHELL_COMMAND_BYTES) {
+            return limitExceededResult('input_too_large', command.slice(0, 120));
+        }
+        return null;
+    }
+    const payloadBytes = Buffer.byteLength(JSON.stringify(action.payload ?? {}), 'utf8');
+    if (payloadBytes > MAX_TOOL_PAYLOAD_BYTES) {
+        return limitExceededResult('input_too_large', action.toolName ?? action.kind);
+    }
+    return null;
+}

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

@@ -1,2 +1,2 @@
-export declare function collectOutsideRepoPaths(command: string, cwd: string, repoRoot: string): string[];
-export declare function collectOutsideRepoPathsFromToolPayload(payload: Record<string, unknown>, cwd: string, repoRoot: string): string[];
+export declare function collectOutsideRepoPaths(command: string, cwd: string, repoRoot: string, trustedWorkspaceRoots?: string[]): string[];
+export declare function collectOutsideRepoPathsFromToolPayload(payload: Record<string, unknown>, cwd: string, repoRoot: string, trustedWorkspaceRoots?: string[]): string[];

package/dist/core/capability/paths.js

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { relativeWithinRepo, resolveMutationTarget } from '../path-utils.js';
+import { resolveMutationTarget, resolveWorkspaceRootMatch } from '../path-utils.js';
 import { extractRedirectTargets, tokenizeShell } from '../shell-tokenizer.js';
 function applyPatchTargets(patch) {
     const targets = [];
@@ -42,25 +42,25 @@ function extractToolPatch(payload) {
     }
     return null;
 }
-function addOutsideRepoPath(paths, token, cwd, repoRoot) {
+function addOutsideRepoPath(paths, token, cwd, repoRoot, trustedWorkspaceRoots = []) {
     const resolved = resolveMutationTarget(token, cwd);
-    if (resolved && relativeWithinRepo(repoRoot, resolved) === null) {
+    if (resolved && resolveWorkspaceRootMatch(repoRoot, trustedWorkspaceRoots, resolved) === null) {
         paths.add(resolved);
     }
 }
-export function collectOutsideRepoPaths(command, cwd, repoRoot) {
+export function collectOutsideRepoPaths(command, cwd, repoRoot, trustedWorkspaceRoots = []) {
     const tokens = tokenizeShell(command);
     const redirects = extractRedirectTargets(tokens);
     const paths = new Set();
     for (const token of tokens.slice(1)) {
-        addOutsideRepoPath(paths, token, cwd, repoRoot);
+        addOutsideRepoPath(paths, token, cwd, repoRoot, trustedWorkspaceRoots);
     }
     for (const redirect of redirects) {
-        addOutsideRepoPath(paths, redirect, cwd, repoRoot);
+        addOutsideRepoPath(paths, redirect, cwd, repoRoot, trustedWorkspaceRoots);
     }
     return [...paths];
 }
-export function collectOutsideRepoPathsFromToolPayload(payload, cwd, repoRoot) {
+export function collectOutsideRepoPathsFromToolPayload(payload, cwd, repoRoot, trustedWorkspaceRoots = []) {
     const toolKind = String(payload.tool_name ?? '')
         .trim()
         .toLowerCase();
@@ -68,7 +68,7 @@ export function collectOutsideRepoPathsFromToolPayload(payload, cwd, repoRoot) {
     const filePath = extractToolFilePath(payload);
     if (filePath) {
         const resolved = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
-        if (relativeWithinRepo(repoRoot, resolved) === null) {
+        if (resolveWorkspaceRootMatch(repoRoot, trustedWorkspaceRoots, resolved) === null) {
             paths.add(resolved);
         }
         return [...paths];
@@ -78,7 +78,7 @@ export function collectOutsideRepoPathsFromToolPayload(payload, cwd, repoRoot) {
         if (patch) {
             for (const target of applyPatchTargets(patch)) {
                 const resolved = path.isAbsolute(target) ? target : path.resolve(cwd, target);
-                if (relativeWithinRepo(repoRoot, resolved) === null) {
+                if (resolveWorkspaceRootMatch(repoRoot, trustedWorkspaceRoots, resolved) === null) {
                     paths.add(resolved);
                 }
             }

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

@@ -0,0 +1,18 @@
+import type { PolicyDecision } from './policy-types.js';
+import type { CapabilityRequestV1 } from './request.js';
+export interface CapabilityAuthorizationMetadata {
+    capabilityRequests: CapabilityRequestV1[];
+    authorizationDecision: PolicyDecision;
+}
+export interface PolicyLegacyReasonHints {
+    outsideMutation?: boolean;
+    effect?: 'read_only' | 'local_mutation' | 'remote_mutation' | 'unknown';
+}
+export declare function singleCapabilityMetadata(request: CapabilityRequestV1, decision: PolicyDecision): CapabilityAuthorizationMetadata;
+/**
+ * Maps a PolicyDecision to hook-facing legacy reason strings.
+ * Pass hints when the shell segment context is known (outside-repo mutation, etc.).
+ */
+export declare function policyDecisionToLegacyReason(decision: PolicyDecision, hints?: PolicyLegacyReasonHints): string;
+/** @deprecated Use policyDecisionToLegacyReason for shell segments that need outside-repo hints. */
+export declare function policyReasonToLegacyReason(decision: PolicyDecision): string;

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

@@ -0,0 +1,51 @@
+export function singleCapabilityMetadata(request, decision) {
+    return {
+        capabilityRequests: [request],
+        authorizationDecision: decision,
+    };
+}
+/**
+ * Maps a PolicyDecision to hook-facing legacy reason strings.
+ * Pass hints when the shell segment context is known (outside-repo mutation, etc.).
+ */
+export function policyDecisionToLegacyReason(decision, hints = {}) {
+    if (decision.reason === 'outside_repo_mutation') {
+        return 'outside_repo_mutation';
+    }
+    if (decision.reason === 'external_effect' || decision.reason === 'network_connect') {
+        return 'external_effect';
+    }
+    if (decision.reason === 'high_stakes_path' || decision.reason === 'secret_path') {
+        return 'tier1_catastrophic';
+    }
+    if (decision.reason === 'indeterminate_effect') {
+        return 'unknown_local_effect';
+    }
+    if (decision.reason === 'opaque_execution') {
+        return 'opaque_execution';
+    }
+    if (decision.reason === 'control_plane_mutation') {
+        return 'control_plane_mutation';
+    }
+    if (decision.reason === 'policy_default') {
+        if (decision.signals.includes('outside_repo_path') ||
+            decision.signals.includes('outside_repo_mutation')) {
+            return 'outside_repo_mutation';
+        }
+        if (hints.outsideMutation && hints.effect !== 'read_only') {
+            return 'outside_repo_mutation';
+        }
+        return 'unknown_local_effect';
+    }
+    if (decision.reason === 'subagent_review') {
+        return 'subagent_review';
+    }
+    if (decision.outcome === 'deny') {
+        return decision.reason;
+    }
+    return decision.reason;
+}
+/** @deprecated Use policyDecisionToLegacyReason for shell segments that need outside-repo hints. */
+export function policyReasonToLegacyReason(decision) {
+    return policyDecisionToLegacyReason(decision);
+}

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

@@ -0,0 +1,70 @@
+import type { BelayConfigV4 } from '../config.js';
+import type { VerdictEffect, VerdictLocation, VerdictOpacity } from '../verdict/types.js';
+import type { AuthorizationContext, PolicyDecision, PolicyEngine } from './policy-types.js';
+import { type CapabilityHookKind, type CapabilityRequestV1 } from './request.js';
+export type PolicyAuthExtras = Pick<AuthorizationContext, 'grants' | 'attestation'> & {
+    egressProxyActive?: boolean;
+    sensitivePaths?: string[];
+};
+export interface ShellCapabilityAnalysis {
+    command: string;
+    hookKind: CapabilityHookKind;
+    segmentHead: string;
+    effect: VerdictEffect;
+    location: VerdictLocation;
+    opacity: VerdictOpacity;
+    egressClass?: 'read' | 'destructive' | 'ambiguous';
+    pathArgs: string[];
+    /** Verdict-resolved canonical paths aligned with pathArgs (preferred for policy resource selection). */
+    resolvedPathTargets?: string[];
+    signals: string[];
+    cwd: string;
+    repoRoot: string;
+    inputFingerprint: string;
+    adapter?: string;
+    trustedWorkspaceRoots?: string[];
+    sensitivePaths?: string[];
+    protectedArtifactRoots?: string[];
+}
+export interface FileMutationCapabilityAnalysis {
+    hookKind: CapabilityHookKind;
+    toolKind: string;
+    filePath: string;
+    resolvedPath: string;
+    repoRoot: string;
+    cwd: string;
+    inputFingerprint: string;
+    signals: string[];
+    isDelete: boolean;
+    locationLabel: 'repo_local' | 'outside_repo' | 'sensitive_path' | 'control_plane';
+    trustedWorkspaceRoots?: string[];
+    sensitivePaths?: string[];
+    adapter?: string;
+}
+export interface SubagentCapabilityAnalysis {
+    subagentType: string;
+    summary: string;
+    repoRoot: string;
+    cwd: string;
+    inputFingerprint: string;
+    signals: string[];
+    adapter?: string;
+}
+export declare function buildSubagentCapabilityRequest(analysis: SubagentCapabilityAnalysis): CapabilityRequestV1;
+export declare function evaluateSubagentPolicy(analysis: SubagentCapabilityAnalysis, config: BelayConfigV4, auth?: PolicyAuthExtras): {
+    request: CapabilityRequestV1;
+    decision: PolicyDecision;
+};
+export declare function buildShellCapabilityRequest(analysis: ShellCapabilityAnalysis): CapabilityRequestV1;
+export declare function buildFileMutationCapabilityRequest(analysis: FileMutationCapabilityAnalysis): CapabilityRequestV1;
+export declare function createTypeScriptPolicyEngine(): PolicyEngine;
+export declare function getDefaultPolicyEngine(): PolicyEngine;
+export declare function policyDecisionRequiresAsk(decision: PolicyDecision): boolean;
+export declare function evaluateShellPolicy(analysis: ShellCapabilityAnalysis, config: BelayConfigV4, auth?: PolicyAuthExtras): {
+    request: CapabilityRequestV1;
+    decision: PolicyDecision;
+};
+export declare function evaluateFileMutationPolicy(analysis: FileMutationCapabilityAnalysis, config: BelayConfigV4, auth?: PolicyAuthExtras): {
+    request: CapabilityRequestV1;
+    decision: PolicyDecision;
+};