@guilz-dev/belay 0.4.0 → 0.6.0

package/README.md

@@ -244,7 +244,13 @@ Notable settings:
   (`judge.providerId`); **driver** is the API compatibility layer (`judge.provider`:
   `ollama`, `openai-compatible`, or `anthropic`); **host** is where hooks install
   (`config.adapter`: `cursor`, `claude`, `codex`). Set `judge.endpoint` when needed;
-  credentials via `belay config credential mode project|apiKey` or env vars. Record egress
+  credentials via `belay config credential mode project|apiKey` or env vars. **`project`**
+  reads API keys from the shell environment at runtime (`BELAY_JUDGE_API_KEY`, then provider
+  vars such as `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `CURSOR_API_KEY`); Belay does **not**
+  load `.env` files for Judge. When the native CLI is available, `project` can also use the
+  host login session without a stored key. **`apiKey`** stores a key in Belay's credential store
+  (`credentials.json`, mode `0600`; under `~/.config/belay/` when control plane is enabled).
+  Record egress
   consent during `belay config` or via `belay judge consent` → `belay approve` →
   `belay judge use … --cloud-consent-approval-id`. Cloud providers can use native CLI
   transport without `judge.endpoint` when the host CLI is available (`codex-cli`,

package/dist/adapters/layouts/scope.js

@@ -1,5 +1,6 @@
 import os from 'node:os';
 import path from 'node:path';
+import { isPathOutsideRoot } from '../../core/path-utils.js';
 function agentHomeDir(adapter) {
     const home = os.homedir();
     if (adapter === 'cursor') {
@@ -23,13 +24,13 @@ export function isPathInside(child, parent) {
     const resolvedChild = path.resolve(child);
     const resolvedParent = path.resolve(parent);
     const relative = path.relative(resolvedParent, resolvedChild);
-    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+    return relative === '' || (!isPathOutsideRoot(relative) && !path.isAbsolute(relative));
 }
 export function buildRunnerInvocation(platform, hooksDir, repoRoot, hookScript, ...args) {
     const runnerFile = platform === 'win32' ? 'belay-runner.cmd' : 'belay-runner';
     const runnerAbs = path.resolve(hooksDir, runnerFile);
     const relative = path.relative(path.resolve(repoRoot), runnerAbs);
-    const useRelative = relative.length > 0 && !relative.startsWith('..') && !path.isAbsolute(relative);
+    const useRelative = relative.length > 0 && !isPathOutsideRoot(relative) && !path.isAbsolute(relative);
     const runnerRef = useRelative
         ? platform === 'win32'
             ? `.\\${relative.split(path.sep).join('\\')}`

package/dist/adapters/shared/gate-runtime.d.ts

@@ -1,6 +1,5 @@
 import { type ApprovalReplayHint } from '../../core/approval-replay.js';
-import type { GatedActionKind } from '../../core/gate-contract.js';
-import { type GatePermissionResponse, type GateVerdict } from '../../core/gate-contract.js';
+import { type GatedActionKind, type GatePermissionResponse, type GateVerdict } from '../../core/gate-contract.js';
 import { GateNormalizationError } from '../../core/gate-engine.js';
 import { type BelayConfigV3 } from '../../core/index.js';
 import type { ApprovalStateFile, ClassifierOptions } from '../../core/types.js';

package/dist/adapters/shared/gate-runtime.js

@@ -7,16 +7,27 @@ import { buildReplayHint, buildRetryInstructionForConfig, getExecutionLeaseMs, r
 import { consumeApprovedAfterCliReplay, gateApprovalStoreFromDeps, recordApproval, } from '../../core/approval-service.js';
 import { issueApprovalToken } from '../../core/approval-token.js';
 import { buildAuditActionSnapshot, buildAuditReplayContext, } from '../../core/audit-replay-context.js';
+import { mutateApprovalStateWithRetry } from '../../core/capability/approval-state-mutation.js';
+import { APPROVAL_STATE_VERSION_V3 } from '../../core/capability/approval-v3.js';
+import { isEgressProxyActive } from '../../core/capability/boundary-egress.js';
+import { resolveBoundaryDriverContext } from '../../core/capability/boundary-session.js';
+import { hashCapabilityRequests } from '../../core/capability/capability-request-hash.js';
+import { recordGateApprovalAsk, scheduleGateShadowAudit, } from '../../core/capability/gate-shadow-audit.js';
+import { consumeGrantLease, findMatchingGrant, grantsFromApprovedState, } from '../../core/capability/grant-lease.js';
+import { loadClassifierAuthorization } from '../../core/capability/grant-loader.js';
 import { collectOutsideRepoPaths, collectOutsideRepoPathsFromToolPayload, fsScopeAllowlistPath, isCapabilityBrokerDemotionActive, loadFsScopeAllowlistSync, loadTrustedWorkspaceRootsSync, shouldSkipBrokerApprovedOnce, shouldSkipBrokerApprovedRecord, trustedWorkspaceRootsPath, validateTrustedWorkspaceRootCandidate, } from '../../core/capability/index.js';
 import { resolveLayeredConfig, teamConfigPath } from '../../core/config-layers.js';
 import { classifyResultToGateVerdict, unnormalizedGateVerdict, } from '../../core/gate-contract.js';
 import { classifyGatedActionAsync, extractAgentAssessment, GateNormalizationError, gateEnabledForAction, normalizeGatedAction, } from '../../core/gate-engine.js';
-import { approvalCommandMatch, approvedApprovalsFile, canonicalStringify, classifierOptionsFromConfig, configuredControlPlaneDir, pendingApprovalsFile, resolveControlPlaneDir, scrubOptionsFromConfig, scrubValue, toolFingerprint, } from '../../core/index.js';
+import { approvalCommandMatch, approvedApprovalsFile, belayStateDir, canonicalStringify, classifierOptionsFromConfig, configuredControlPlaneDir, pendingApprovalsFile, resolveControlPlaneDir, scrubOptionsFromConfig, scrubValue, toolFingerprint, } from '../../core/index.js';
+import { extractJudgeFallbackReason, formatJudgeInfrastructureDenyMessage, inferProviderIdFromFallbackReason, isJudgeInfrastructureFailure, } from '../../core/judge-fallback-hints.js';
 import { notifyDeny } from '../../core/notify.js';
 import { canonicalPath } from '../../core/path-utils.js';
+import { recoveryFailClosedResult, recoveryFailReasonFromSkip, } from '../../core/recovery/fail-closed.js';
 import { fingerprintReplayPayload } from '../../core/replay-scrub.js';
 import { loadStandingAllow, resolveStandingAllowMatch, standingAllowFile, } from '../../core/standing-allow.js';
 import { isTransactionalEligible, runTransactionalExecution, TRANSACTIONAL_ALREADY_APPLIED, TRANSACTIONAL_APPROVAL_BYPASS_REASONS, } from '../../core/transactional/index.js';
+import { egressStatus } from '../../services/egress-service.js';
 import { protectedArtifactRoots } from '../layouts/protected-paths.js';
 const EMPTY_APPROVALS = {
     version: 1,
@@ -66,10 +77,12 @@ export function createDefaultGateRuntimeDeps() {
                 ? pendingApprovalsFile(ctx.config, repoLocalStateDir)
                 : approvedApprovalsFile(ctx.config, repoLocalStateDir);
             const loaded = await loadJsonFile(filePath, EMPTY_APPROVALS);
+            const version = loaded.version === 3 ? 3 : loaded.version === 2 ? 2 : 1;
             return {
                 filePath,
                 state: {
-                    version: loaded.version === 2 ? 2 : 1,
+                    version,
+                    ...(loaded.revision !== undefined ? { revision: loaded.revision } : {}),
                     approvals: Array.isArray(loaded.approvals) ? loaded.approvals : [],
                 },
             };
@@ -133,7 +146,7 @@ async function ensurePendingApproval(ctx, deps, kind, result, approvalInput, sco
         approval.repoRoot === ctx.repoRoot);
     if (existing) {
         await deps.writeApprovals(pending.filePath, pending.state);
-        return existing;
+        return { approval: existing, created: false };
     }
     const approval = createApprovalRecordWithEnvelope({
         kind,
@@ -145,11 +158,13 @@ async function ensurePendingApproval(ctx, deps, kind, result, approvalInput, sco
         approvalId: `belay_${randomUUID().replaceAll('-', '').slice(0, 12)}`,
         approvalInput,
         scopeHint,
+        capabilityRequests: result.capabilityRequests,
     });
-    pending.state.version = 2;
+    pending.state.version = APPROVAL_STATE_VERSION_V3;
+    pending.state.revision = (pending.state.revision ?? 0) + 1;
     pending.state.approvals.push(approval);
     await deps.writeApprovals(pending.filePath, pending.state);
-    return approval;
+    return { approval, created: true };
 }
 function extractShellCommandFromPayload(payload) {
     const toolInput = payload.tool_input;
@@ -208,26 +223,53 @@ function deriveWorkspaceRootScopeHint(params) {
     return { scope: 'workspace-root', path: validation.normalizedPath };
 }
 async function consumeApprovedApproval(ctx, deps, kind, fingerprint) {
-    const approved = await deps.loadApprovals(ctx, 'approved-approvals.json');
-    approved.state = compactApprovals(approved.state);
-    const index = approved.state.approvals.findIndex((approval) => approval.kind === kind &&
+    const loaded = await deps.loadApprovals(ctx, 'approved-approvals.json');
+    loaded.state = compactApprovals(loaded.state);
+    const index = loaded.state.approvals.findIndex((approval) => approval.kind === kind &&
         approval.fingerprint === fingerprint &&
         approval.repoRoot === ctx.repoRoot);
     if (index === -1) {
-        await deps.writeApprovals(approved.filePath, approved.state);
+        await deps.writeApprovals(loaded.filePath, loaded.state);
         return null;
     }
-    const approval = approved.state.approvals[index];
+    const approval = loaded.state.approvals[index];
     if (approval.executionLeaseExpiresAt) {
-        await deps.writeApprovals(approved.filePath, approved.state);
-        return approval;
+        await deps.writeApprovals(loaded.filePath, loaded.state);
+        return { approval, firstExecution: false };
+    }
+    const consumed = await mutateApprovalStateWithRetry({
+        load: () => deps.loadApprovals(ctx, 'approved-approvals.json'),
+        write: (filePath, state) => deps.writeApprovals(filePath, state),
+        mutate: (state) => {
+            const compacted = compactApprovals(state);
+            const matchIndex = compacted.approvals.findIndex((approval) => approval.kind === kind &&
+                approval.fingerprint === fingerprint &&
+                approval.repoRoot === ctx.repoRoot);
+            if (matchIndex === -1) {
+                return null;
+            }
+            const approval = compacted.approvals[matchIndex];
+            if (approval.grant && approval.grant.usesRemaining <= 0) {
+                compacted.approvals.splice(matchIndex, 1);
+                return { state: compacted, result: null };
+            }
+            compacted.approvals[matchIndex] = {
+                ...approval,
+                executionLeaseExpiresAt: new Date(Date.now() + getExecutionLeaseMs(ctx.config)).toISOString(),
+                grant: approval.grant
+                    ? {
+                        ...approval.grant,
+                        usesRemaining: Math.max(0, approval.grant.usesRemaining - 1),
+                    }
+                    : undefined,
+            };
+            return { state: compacted, result: approval };
+        },
+    });
+    if (!consumed) {
+        return null;
     }
-    approved.state.approvals[index] = {
-        ...approval,
-        executionLeaseExpiresAt: new Date(Date.now() + getExecutionLeaseMs(ctx.config)).toISOString(),
-    };
-    await deps.writeApprovals(approved.filePath, approved.state);
-    return approval;
+    return { approval: consumed, firstExecution: true };
 }
 export async function evaluateGatedAction(ctx, deps, params) {
     let action;
@@ -280,15 +322,42 @@ export async function evaluateGatedAction(ctx, deps, params) {
         });
     }
     const classifierOptions = runtimeClassifierOptions(ctx, ctx.config);
-    const predicted = await classifyGatedActionAsync(action, ctx.config, classifierOptions);
+    const approvedForAuth = await deps.loadApprovals(ctx, 'approved-approvals.json');
+    const authorization = await loadClassifierAuthorization({
+        repoRoot: ctx.repoRoot,
+        config: ctx.config,
+        approvedState: compactApprovals(approvedForAuth.state),
+    });
+    const egress = await egressStatus({ targetDir: ctx.repoRoot });
+    const egressProxyActive = isEgressProxyActive({
+        config: ctx.config,
+        running: egress.running,
+        foreignProxy: egress.foreignProxy,
+        repoRootMismatch: egress.repoRootMismatch,
+    });
+    const enrichedClassifierOptions = {
+        ...classifierOptions,
+        ...authorization,
+        egressProxyActive,
+    };
+    const predicted = await classifyGatedActionAsync(action, ctx.config, enrichedClassifierOptions);
     let result = predicted;
     let predictedAssessment;
     let observedAssessment;
     let transactionalLayer;
-    if (isTransactionalEligible(ctx.config, params.kind, predicted) &&
+    const recoveryCandidate = isTransactionalEligible(ctx.config, params.kind, predicted) &&
         params.kind === 'shell' &&
-        params.command) {
+        Boolean(params.command);
+    if (recoveryCandidate && params.command) {
         const transactional = ctx.config.policy.transactional;
+        const boundaryDriverId = ctx.config.capability?.boundaryDriver ??
+            (ctx.config.sandbox.runtime === 'container' ? 'container' : 'host-integration');
+        const boundaryContext = await resolveBoundaryDriverContext({
+            repoRoot: ctx.repoRoot,
+            config: ctx.config,
+            driverId: boundaryDriverId,
+            egressProxyRunning: egressProxyActive,
+        });
         const txResult = await runTransactionalExecution({
             command: params.command,
             cwd: params.cwd,
@@ -299,9 +368,11 @@ export async function evaluateGatedAction(ctx, deps, params) {
             diffContext: {
                 repoRoot: ctx.repoRoot,
                 sensitivePaths: ctx.config.classifier.sensitivePaths,
-                protectedRoots: classifierOptions.protectedArtifactRoots ?? [],
+                protectedRoots: enrichedClassifierOptions.protectedArtifactRoots ?? [],
                 maxDeletionCount: transactional.maxDeletionCount,
             },
+            boundaryContext,
+            dirtyIgnoreRoots: protectedArtifactRoots(ctx.layout, ctx.repoRoot, ctx.config.controlPlane.enabled ? configuredControlPlaneDir(ctx.config) : null),
         });
         if (!txResult.skipped && txResult.observed) {
             result = txResult.result;
@@ -315,10 +386,15 @@ export async function evaluateGatedAction(ctx, deps, params) {
                 transactionalTimedOut: txResult.timedOut === true,
             };
         }
-        else if (txResult.skipReason) {
+        else {
+            const skipReason = txResult.skipReason ?? 'recovery_observation_failed';
+            result = recoveryFailClosedResult(predicted, recoveryFailReasonFromSkip(skipReason), [
+                skipReason,
+            ]);
             transactionalLayer = {
                 transactional: false,
-                transactionalSkipReason: txResult.skipReason,
+                transactionalSkipReason: skipReason,
+                recoveryFailClosed: true,
             };
         }
     }
@@ -353,7 +429,7 @@ export async function evaluateGatedAction(ctx, deps, params) {
             fingerprint: result.fingerprint,
             repoRoot: ctx.repoRoot,
         },
-        classifierOptions,
+        classifierOptions: enrichedClassifierOptions,
         scopeHintPayload: params.payload,
     });
 }
@@ -392,9 +468,47 @@ export async function gateUnmappedToolVerdict(ctx, deps, toolName, payload) {
         },
     });
 }
+async function consumeCapabilityGrantIfUsed(ctx, deps, result) {
+    if (result.reason !== 'capability_grant' &&
+        result.authorizationDecision?.matchedRule !== 'grant.exact') {
+        return true;
+    }
+    const request = result.capabilityRequests?.[0];
+    if (!request) {
+        return false;
+    }
+    const consumed = await mutateApprovalStateWithRetry({
+        load: () => deps.loadApprovals(ctx, 'approved-approvals.json'),
+        write: (filePath, state) => deps.writeApprovals(filePath, state),
+        mutate: (state) => {
+            const compacted = compactApprovals(state);
+            const grant = findMatchingGrant(grantsFromApprovedState(compacted, ctx.repoRoot), request);
+            if (!grant) {
+                return null;
+            }
+            const lease = consumeGrantLease(compacted, grant.grantId);
+            if (!lease.consumed) {
+                return null;
+            }
+            return { state: lease.state, result: true };
+        },
+    });
+    return consumed === true;
+}
 async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {}) {
     const replayContext = buildAuditReplayContext(kind, result, auditExtras.replayAction);
     const actionSnapshot = buildAuditActionSnapshot(kind, result, auditExtras.replayAction);
+    const providerId = String(ctx.config.judge?.providerId ?? 'cursor');
+    const stateDir = belayStateDir(ctx.config, ctx.layout.repoLocalStateDir(ctx.repoRoot));
+    const capabilityAudit = scheduleGateShadowAudit({
+        repoRoot: ctx.repoRoot,
+        config: ctx.config,
+        providerId,
+        result,
+        command: auditExtras.replayAction?.command ??
+            (kind === 'shell' ? auditExtras.approvalInput?.input : undefined),
+        stateDir,
+    });
     const gateBase = {
         event: gateAuditEventName(kind),
         kind,
@@ -407,6 +521,7 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
         schemaVersion: result.axes ? 2 : 1,
         ...(result.axes ?? {}),
         ...auditExtras.transactionalLayer,
+        ...capabilityAudit,
         ...(replayContext ? { replayContext } : {}),
         ...(actionSnapshot ? { actionSnapshot } : {}),
     };
@@ -470,6 +585,32 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
             entry.fingerprint === result.fingerprint &&
             entry.repoRoot === ctx.repoRoot);
         if (!shouldSkipBrokerApprovedRecord(brokerActive, matchedApproval?.reason)) {
+            if (matchedApproval &&
+                matchedApproval.capabilityRequestHash &&
+                result.capabilityRequests?.length &&
+                matchedApproval.capabilityRequestHash !== hashCapabilityRequests(result.capabilityRequests)) {
+                await deps.appendAudit(ctx, {
+                    ...gateBase,
+                    verdict: 'deny_pending_approval',
+                    reason: 'approval_replay_mismatch',
+                    approvalId: matchedApproval.approvalId,
+                    wouldBlock: true,
+                    permission: 'deny',
+                });
+                return classifyResultToGateVerdict({
+                    result: {
+                        ...result,
+                        verdict: 'deny_pending_approval',
+                        reason: 'approval_replay_mismatch',
+                    },
+                    mode: ctx.config.mode,
+                    permission: 'deny',
+                    wouldBlock: true,
+                    approvalId: matchedApproval.approvalId,
+                    user_message: 'Belay denied this action because capability requests changed after approval. Re-approve the exact action or run belay explain.',
+                    agent_message: 'Belay denied this action because capability requests changed after approval.',
+                });
+            }
             if (matchedApproval &&
                 auditExtras.replayAction &&
                 !validateReplayEnvelope(matchedApproval, auditExtras.replayAction)) {
@@ -499,11 +640,14 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
         }
     }
     if (approved) {
+        if (approved.firstExecution) {
+            await recordGateApprovalAsk(stateDir, result.reason, true);
+        }
         await deps.appendAudit(ctx, {
             ...gateBase,
             verdict: 'allow',
             reason: 'approved_once',
-            approvalId: approved.approvalId,
+            approvalId: approved.approval.approvalId,
             wouldBlock: false,
             permission: 'allow',
         });
@@ -512,10 +656,32 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
             mode: ctx.config.mode,
             permission: 'allow',
             wouldBlock: false,
-            approvalId: approved.approvalId,
+            approvalId: approved.approval.approvalId,
         });
     }
     if (result.verdict === 'allow' || result.verdict === 'allow_flagged') {
+        const grantConsumed = await consumeCapabilityGrantIfUsed(ctx, deps, result);
+        if (!grantConsumed) {
+            await deps.appendAudit(ctx, {
+                ...gateBase,
+                verdict: 'deny_pending_approval',
+                reason: 'capability_grant_unavailable',
+                wouldBlock: true,
+                permission: 'deny',
+            });
+            return classifyResultToGateVerdict({
+                result: {
+                    ...result,
+                    verdict: 'deny_pending_approval',
+                    reason: 'capability_grant_unavailable',
+                },
+                mode: ctx.config.mode,
+                permission: 'deny',
+                wouldBlock: true,
+                user_message: 'Belay denied this action because the capability grant could not be consumed. Re-approve or run belay explain.',
+                agent_message: 'Belay denied this action because the capability grant was missing, expired, or already used.',
+            });
+        }
         await deps.appendAudit(ctx, {
             ...gateBase,
             verdict: result.verdict,
@@ -545,12 +711,44 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
             wouldBlock: true,
         });
     }
-    const approval = await ensurePendingApproval(ctx, deps, kind, result, auditExtras.approvalInput, deriveWorkspaceRootScopeHint({
+    if (isJudgeInfrastructureFailure(result)) {
+        const fallbackReason = extractJudgeFallbackReason(result);
+        const providerId = inferProviderIdFromFallbackReason(fallbackReason, String(ctx.config.judge.providerId ?? 'cursor'));
+        const denyMessages = formatJudgeInfrastructureDenyMessage({
+            providerId,
+            fallbackReason,
+            command: result.normalizedCommand ?? result.summary,
+        });
+        await deps.appendAudit(ctx, {
+            ...gateBase,
+            verdict: result.verdict,
+            reason: 'judge_transport_unavailable',
+            judgeFallbackReason: fallbackReason,
+            wouldBlock: true,
+            permission: 'deny',
+        });
+        return classifyResultToGateVerdict({
+            result: {
+                ...result,
+                verdict: 'deny_pending_approval',
+                reason: 'judge_transport_unavailable',
+            },
+            mode: ctx.config.mode,
+            permission: 'deny',
+            wouldBlock: true,
+            user_message: denyMessages.user_message,
+            agent_message: denyMessages.agent_message,
+        });
+    }
+    const { approval, created } = await ensurePendingApproval(ctx, deps, kind, result, auditExtras.approvalInput, deriveWorkspaceRootScopeHint({
         result,
         replayAction: auditExtras.replayAction,
         payloadForScopeHint: auditExtras.scopeHintPayload,
         options: auditExtras.classifierOptions ?? {},
     }));
+    if (created) {
+        await recordGateApprovalAsk(stateDir, result.reason, false);
+    }
     let approvalToken;
     try {
         approvalToken = await issueApprovalToken({