@guilz-dev/belay 0.6.0 → 0.7.0

package/dist/core/effect-ir/package-exec-eval.js

@@ -0,0 +1,152 @@
+import { policyDecisionToLegacyReason } from '../capability/policy-bridge.js';
+import { policyDecisionRequiresAsk } from '../capability/policy-engine.js';
+import { cwdRelative } from '../verdict/containment.js';
+import { verdictFingerprint } from '../verdict/fingerprint.js';
+import { redactCommand } from '../verdict/parser.js';
+import { buildEffectPlan } from './build.js';
+import { innerRecipeFromPeel, peelPackageExecArgv } from './package-exec.js';
+import { capabilityRequestsToEffectRequirements, evaluateEffectPlanPolicy } from './policy.js';
+function askFromEffectPlan(params) {
+    const { capabilityRequests, authorizationDecision, decisions } = evaluateEffectPlanPolicy(params.plan, params.context);
+    const legacyReason = policyDecisionRequiresAsk(authorizationDecision)
+        ? policyDecisionToLegacyReason(authorizationDecision)
+        : params.reason;
+    return {
+        permission: 'ask',
+        location: params.inner?.location ?? 'unknown',
+        opacity: params.plan.opacity,
+        effect: params.inner?.effect ?? 'unknown',
+        confidence: 'deterministic',
+        reason: legacyReason,
+        signals: [...new Set([...params.signals, ...params.plan.signals])],
+        capabilityRequests,
+        authorizationDecision,
+        effectPlan: params.plan,
+        effectPlanPolicyDecisions: decisions,
+    };
+}
+function allowFromEffectPlan(params) {
+    const { capabilityRequests, authorizationDecision, decisions } = evaluateEffectPlanPolicy(params.plan, params.context);
+    return {
+        ...params.inner,
+        opacity: params.plan.opacity,
+        signals: [...new Set([...params.inner.signals, ...params.signals, ...params.plan.signals])],
+        capabilityRequests,
+        authorizationDecision,
+        effectPlan: params.plan,
+        effectPlanPolicyDecisions: decisions,
+    };
+}
+export async function evaluatePackageExecSegment(params) {
+    const peel = peelPackageExecArgv(params.peeled);
+    if (!peel) {
+        return {
+            permission: 'ask',
+            location: 'unknown',
+            opacity: 'opaque',
+            effect: 'unknown',
+            confidence: 'deterministic',
+            reason: 'launcher_unresolved',
+            signals: ['launcher_unresolved'],
+        };
+    }
+    const relative = cwdRelative(params.context.repoRoot, params.context.cwd);
+    const inputFingerprint = verdictFingerprint(relative, redactCommand(params.command));
+    if (peel.opaque) {
+        const plan = buildEffectPlan({
+            tokens: params.peeled,
+            cwd: params.context.cwd,
+            repoRoot: params.context.repoRoot,
+            inputFingerprint,
+        }) ??
+            {
+                version: 1,
+                root: { kind: 'merge', children: [] },
+                inputFingerprint,
+                opacity: 'opaque',
+                disposition: 'effects',
+                completeness: 'partial',
+                signals: [peel.reason],
+            };
+        return askFromEffectPlan({
+            plan,
+            context: params.context,
+            reason: peel.reason,
+            signals: [peel.reason, ...peel.signals],
+        });
+    }
+    const innerRecipe = innerRecipeFromPeel(peel);
+    let innerVerdict = null;
+    let innerRequirements;
+    if (innerRecipe) {
+        innerVerdict = await params.evaluateInner(innerRecipe);
+        if (innerVerdict.capabilityRequests?.length) {
+            innerRequirements = capabilityRequestsToEffectRequirements(innerVerdict.capabilityRequests);
+        }
+        else if (innerVerdict.permission === 'allow' && innerVerdict.effect === 'read_only') {
+            innerRequirements = [];
+        }
+    }
+    const plan = buildEffectPlan({
+        tokens: params.peeled,
+        cwd: params.context.cwd,
+        repoRoot: params.context.repoRoot,
+        inputFingerprint,
+        innerRequirements,
+    });
+    if (!plan) {
+        return {
+            permission: 'ask',
+            location: innerVerdict?.location ?? 'unknown',
+            opacity: 'opaque',
+            effect: innerVerdict?.effect ?? 'unknown',
+            confidence: 'deterministic',
+            reason: peel.reason,
+            signals: [peel.reason, ...peel.signals],
+            capabilityRequests: innerVerdict?.capabilityRequests,
+            authorizationDecision: innerVerdict?.authorizationDecision,
+        };
+    }
+    const { capabilityRequests, authorizationDecision, decisions } = evaluateEffectPlanPolicy(plan, params.context);
+    if (policyDecisionRequiresAsk(authorizationDecision)) {
+        return askFromEffectPlan({
+            plan,
+            context: params.context,
+            reason: policyDecisionToLegacyReason(authorizationDecision),
+            signals: [peel.reason, ...peel.signals],
+            inner: innerVerdict ?? undefined,
+        });
+    }
+    if (innerVerdict?.permission === 'ask') {
+        return {
+            ...innerVerdict,
+            opacity: plan.opacity,
+            signals: [...new Set([...innerVerdict.signals, peel.reason, ...plan.signals])],
+            capabilityRequests,
+            authorizationDecision,
+            effectPlan: plan,
+            effectPlanPolicyDecisions: decisions,
+        };
+    }
+    if (!innerVerdict) {
+        return {
+            permission: 'allow',
+            location: 'repo_local',
+            opacity: plan.opacity,
+            effect: 'read_only',
+            confidence: 'deterministic',
+            reason: peel.reason,
+            signals: [peel.reason, ...plan.signals],
+            capabilityRequests,
+            authorizationDecision,
+            effectPlan: plan,
+            effectPlanPolicyDecisions: decisions,
+        };
+    }
+    return allowFromEffectPlan({
+        plan,
+        context: params.context,
+        inner: innerVerdict,
+        signals: [peel.reason, ...peel.signals],
+    });
+}

package/dist/core/effect-ir/package-exec.d.ts

@@ -0,0 +1,29 @@
+import type { PackageExecLauncher } from './types.js';
+export interface PackageExecPeelResult {
+    launcher: PackageExecLauncher;
+    innerTokens: string[];
+    acquisitionSpecs: string[];
+    opaque: boolean;
+    reason: string;
+    forceAcquire: boolean;
+    signals: string[];
+}
+export type PackageAcquisitionSource = {
+    kind: 'local';
+} | {
+    kind: 'registry';
+} | {
+    kind: 'network';
+    host: string;
+    port?: number;
+    protocol: string;
+};
+export declare function isPackageExecLauncher(tokens: string[]): boolean;
+export declare function peelPackageExecArgv(tokens: string[]): PackageExecPeelResult | null;
+export declare function classifyPackageAcquisitionSpec(spec: string): PackageAcquisitionSource;
+export declare function resolveLocalBin(binName: string, cwd: string, repoRoot: string): {
+    path: string;
+    proven: true;
+} | null;
+export declare function innerRecipeFromPeel(peel: PackageExecPeelResult): string | null;
+export declare function isPackageExecHeadToken(head: string): boolean;

package/dist/core/effect-ir/package-exec.js

@@ -0,0 +1,292 @@
+import { existsSync, realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { parseNetworkEndpoint } from '../network-endpoint.js';
+import { pathWithinRoot } from '../path-utils.js';
+const READ_ONLY_SUFFIXES = new Set(['--version', '-v', '--help', '-h']);
+function isPackageExecHead(head) {
+    return head === 'npx' || head === 'npm' || head === 'pnpm';
+}
+export function isPackageExecLauncher(tokens) {
+    const head = tokens[0] ?? '';
+    if (head === 'npx') {
+        return true;
+    }
+    if (head === 'npm' && tokens[1] === 'exec') {
+        return true;
+    }
+    if (head === 'pnpm' && tokens[1] === 'dlx') {
+        return true;
+    }
+    return false;
+}
+export function peelPackageExecArgv(tokens) {
+    const head = tokens[0] ?? '';
+    if (head === 'npx') {
+        return peelNpx(tokens);
+    }
+    if (head === 'npm' && tokens[1] === 'exec') {
+        return peelNpmExec(tokens);
+    }
+    if (head === 'pnpm' && tokens[1] === 'dlx') {
+        return peelPnpmDlx(tokens);
+    }
+    return null;
+}
+function peelNpx(tokens) {
+    const signals = ['package_exec:npx'];
+    const acquisitionSpecs = [];
+    let index = 1;
+    let forceAcquire = false;
+    while (index < tokens.length) {
+        const token = tokens[index] ?? '';
+        if (index === 1 && tokens.length === 2 && READ_ONLY_SUFFIXES.has(token)) {
+            return {
+                launcher: 'npx',
+                innerTokens: [token],
+                acquisitionSpecs,
+                opaque: false,
+                reason: 'npx_wrapper_readonly',
+                forceAcquire: false,
+                signals: [...signals, 'npx_wrapper_readonly'],
+            };
+        }
+        if (token === '--') {
+            index += 1;
+            break;
+        }
+        if (token === '-y' || token === '--yes') {
+            forceAcquire = true;
+            signals.push('npx.force_yes');
+            index += 1;
+            continue;
+        }
+        if (token === '-p' || token === '--package') {
+            const packageSpec = tokens[index + 1];
+            if (!packageSpec) {
+                return opaquePackageExec('npx', 'npx_package_missing', signals, acquisitionSpecs);
+            }
+            acquisitionSpecs.push(packageSpec);
+            forceAcquire = true;
+            signals.push('npx.package_flag');
+            index += 2;
+            continue;
+        }
+        if (token.startsWith('--package=')) {
+            acquisitionSpecs.push(token.slice('--package='.length));
+            forceAcquire = true;
+            signals.push('npx.package_flag');
+            index += 1;
+            continue;
+        }
+        if (token === '-c' || token === '--call') {
+            return {
+                launcher: 'npx',
+                innerTokens: [],
+                acquisitionSpecs,
+                opaque: true,
+                reason: 'npx_call_script',
+                forceAcquire: true,
+                signals: [...signals, 'npx_call_script'],
+            };
+        }
+        if (token.startsWith('-')) {
+            return opaquePackageExec('npx', 'npx_unknown_option', [...signals, 'npx_unknown_option'], acquisitionSpecs);
+        }
+        break;
+    }
+    const innerTokens = tokens.slice(index);
+    if (innerTokens.length === 0) {
+        return {
+            launcher: 'npx',
+            innerTokens: [],
+            acquisitionSpecs,
+            opaque: true,
+            reason: 'npx_target_missing',
+            forceAcquire,
+            signals: [...signals, 'npx_target_missing'],
+        };
+    }
+    if (/^@[^/]+\/[^/]+/.test(innerTokens[0] ?? '')) {
+        if (acquisitionSpecs.length === 0 && innerTokens[0]) {
+            acquisitionSpecs.push(innerTokens[0]);
+        }
+        return opaquePackageExec('npx', 'npx_scoped_package_bin_indeterminate', [...signals, 'npx_scoped_package_bin_indeterminate'], acquisitionSpecs);
+    }
+    if (requiresExplicitPackageAcquisition(innerTokens[0] ?? '')) {
+        forceAcquire = true;
+        signals.push('npx.remote_spec');
+    }
+    if (acquisitionSpecs.length === 0 && innerTokens[0]) {
+        acquisitionSpecs.push(innerTokens[0]);
+    }
+    return {
+        launcher: 'npx',
+        innerTokens,
+        acquisitionSpecs,
+        opaque: false,
+        reason: 'npx_exec',
+        forceAcquire,
+        signals,
+    };
+}
+function peelNpmExec(tokens) {
+    return peelForcedPackageExec(tokens, 2, 'npm', 'npm_exec');
+}
+function peelPnpmDlx(tokens) {
+    return peelForcedPackageExec(tokens, 2, 'pnpm', 'pnpm_dlx');
+}
+function peelForcedPackageExec(tokens, startIndex, launcher, reason) {
+    const signals = [`package_exec:${reason}`, `${reason}_acquire`];
+    const acquisitionSpecs = [];
+    let index = startIndex;
+    while (index < tokens.length) {
+        const token = tokens[index] ?? '';
+        if (token === '--') {
+            index += 1;
+            break;
+        }
+        if (launcher === 'npm' && (token === '-y' || token === '--yes')) {
+            index += 1;
+            continue;
+        }
+        if (launcher === 'npm' && (token === '-p' || token === '--package')) {
+            const packageSpec = tokens[index + 1];
+            if (!packageSpec) {
+                return opaquePackageExec(launcher, `${reason}_package_missing`, signals, acquisitionSpecs);
+            }
+            acquisitionSpecs.push(packageSpec);
+            index += 2;
+            continue;
+        }
+        if (launcher === 'npm' && token.startsWith('--package=')) {
+            acquisitionSpecs.push(token.slice('--package='.length));
+            index += 1;
+            continue;
+        }
+        if (launcher === 'npm' && (token === '-c' || token === '--call')) {
+            return opaquePackageExec(launcher, `${reason}_call_script`, signals, acquisitionSpecs);
+        }
+        if (token.startsWith('-')) {
+            return opaquePackageExec(launcher, `${reason}_unknown_option`, [...signals, `${reason}_unknown_option`], acquisitionSpecs);
+        }
+        break;
+    }
+    const innerTokens = tokens.slice(index);
+    if (acquisitionSpecs.length === 0 && innerTokens[0]) {
+        acquisitionSpecs.push(innerTokens[0]);
+    }
+    return {
+        launcher,
+        innerTokens,
+        acquisitionSpecs,
+        opaque: innerTokens.length === 0,
+        reason: innerTokens.length === 0 ? `${reason}_missing` : reason,
+        forceAcquire: true,
+        signals,
+    };
+}
+function opaquePackageExec(launcher, reason, signals, acquisitionSpecs = []) {
+    return {
+        launcher,
+        innerTokens: [],
+        acquisitionSpecs,
+        opaque: true,
+        reason,
+        forceAcquire: true,
+        signals,
+    };
+}
+function requiresExplicitPackageAcquisition(token) {
+    if (!token || token.startsWith('-')) {
+        return false;
+    }
+    if (classifyPackageAcquisitionSpec(token).kind !== 'registry') {
+        return true;
+    }
+    if (token.includes('@') && !token.startsWith('@')) {
+        return true;
+    }
+    if (/^@[^/]+\/[^/]+@/.test(token)) {
+        return true;
+    }
+    if (token.startsWith('npm:')) {
+        return true;
+    }
+    return false;
+}
+export function classifyPackageAcquisitionSpec(spec) {
+    const normalized = spec.trim();
+    if (normalized.startsWith('file:') ||
+        normalized.startsWith('git+file:') ||
+        normalized.startsWith('link:') ||
+        normalized.startsWith('workspace:') ||
+        normalized.startsWith('./') ||
+        normalized.startsWith('../') ||
+        normalized.startsWith('/') ||
+        normalized.startsWith('~/') ||
+        /^[A-Za-z]:[\\/]/.test(normalized)) {
+        return { kind: 'local' };
+    }
+    const transportSpec = normalized.startsWith('git+') ? normalized.slice(4) : normalized;
+    const endpoint = parseNetworkEndpoint(transportSpec, {
+        allowHostedGitShorthand: true,
+        allowScpStyle: true,
+    });
+    if (endpoint) {
+        return { kind: 'network', ...endpoint };
+    }
+    if (/^[A-Za-z0-9][A-Za-z0-9._-]*\/[^/]+(?:#.*)?$/.test(normalized)) {
+        return { kind: 'network', host: 'github.com', protocol: 'git' };
+    }
+    if (/(?:\.tgz|\.tar|\.tar\.gz)$/i.test(normalized)) {
+        return { kind: 'local' };
+    }
+    if ((normalized.match(/\//g)?.length ?? 0) > 1) {
+        return { kind: 'local' };
+    }
+    return { kind: 'registry' };
+}
+export function resolveLocalBin(binName, cwd, repoRoot) {
+    const base = path.basename(binName);
+    if (!base || base === '.' || base === '..') {
+        return null;
+    }
+    let current = path.resolve(cwd);
+    const stop = path.resolve(repoRoot);
+    if (!pathWithinRoot(stop, current)) {
+        return null;
+    }
+    while (true) {
+        const candidate = path.join(current, 'node_modules', '.bin', base);
+        if (existsSync(candidate)) {
+            try {
+                const resolvedCandidate = realpathSync.native(candidate);
+                if (!pathWithinRoot(stop, resolvedCandidate) || !statSync(resolvedCandidate).isFile()) {
+                    return null;
+                }
+                return { path: resolvedCandidate, proven: true };
+            }
+            catch {
+                return null;
+            }
+        }
+        if (current === stop) {
+            break;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    return null;
+}
+export function innerRecipeFromPeel(peel) {
+    if (peel.opaque || peel.reason === 'npx_wrapper_readonly' || peel.innerTokens.length === 0) {
+        return null;
+    }
+    return peel.innerTokens.join(' ');
+}
+export function isPackageExecHeadToken(head) {
+    return isPackageExecHead(head);
+}

package/dist/core/effect-ir/policy.d.ts

@@ -0,0 +1,13 @@
+import type { PolicyDecision } from '../capability/policy-types.js';
+import type { CapabilityRequestV1 } from '../capability/request.js';
+import type { VerdictContext } from '../verdict/types.js';
+import type { EffectPlan, EffectRequirement } from './types.js';
+export declare function capabilityRequestsToEffectRequirements(requests: readonly CapabilityRequestV1[]): EffectRequirement[];
+export declare function capabilityRequestsFromEffectPlan(plan: EffectPlan, context: VerdictContext): CapabilityRequestV1[];
+export declare function evaluateEffectPlanPolicy(plan: EffectPlan, context: VerdictContext): {
+    capabilityRequests: CapabilityRequestV1[];
+    decisions: PolicyDecision[];
+    authorizationDecision: PolicyDecision;
+};
+export declare function effectPlanPolicyRequiresAsk(decision: PolicyDecision): boolean;
+export declare function effectPlanPolicyLegacyReason(decision: PolicyDecision): string;

package/dist/core/effect-ir/policy.js

@@ -0,0 +1,77 @@
+import { createHash } from 'node:crypto';
+import { policyDecisionToLegacyReason } from '../capability/policy-bridge.js';
+import { evaluateCapabilityRequestsPolicy, policyDecisionRequiresAsk, } from '../capability/policy-engine.js';
+import { collectRequirements, flattenRequirementsToCapabilityRequests } from './build.js';
+function shellPrincipal(repoRoot, cwd) {
+    return {
+        repoRoot,
+        sessionHash: createHash('sha256').update(`${repoRoot}:${cwd}`).digest('hex').slice(0, 16),
+    };
+}
+function capabilityActionToEffectTag(action) {
+    switch (action) {
+        case 'fs.read':
+            return 'fs.read';
+        case 'fs.write':
+            return 'fs.write';
+        case 'process.exec':
+            return 'process.exec';
+        case 'network.connect':
+            return 'network.connect';
+        case 'secret.read':
+            return 'secret.read';
+        case 'git.ref.write':
+            return 'git.ref.write';
+        case 'control_plane.write':
+            return 'control_plane.write';
+        case 'indeterminate':
+            return 'indeterminate';
+        default:
+            return 'indeterminate';
+    }
+}
+export function capabilityRequestsToEffectRequirements(requests) {
+    return requests.map((request) => ({
+        tag: capabilityActionToEffectTag(request.action),
+        action: request.action,
+        resource: request.resource,
+        evidence: {
+            level: request.evidence.level,
+            signals: [...request.evidence.signals],
+            basis: [...request.context.analysisBasis],
+        },
+        provenance: {
+            innerCommand: request.resource.kind === 'executable' ? request.resource.command : undefined,
+        },
+        provenances: [
+            {
+                innerCommand: request.resource.kind === 'executable' ? request.resource.command : undefined,
+            },
+        ],
+    }));
+}
+export function capabilityRequestsFromEffectPlan(plan, context) {
+    const requirements = collectRequirements(plan.root);
+    return flattenRequirementsToCapabilityRequests(requirements, {
+        principal: shellPrincipal(context.repoRoot, context.cwd),
+        cwd: context.cwd,
+        repoRoot: context.repoRoot,
+        hookKind: 'shell',
+        inputFingerprint: plan.inputFingerprint,
+    });
+}
+export function evaluateEffectPlanPolicy(plan, context) {
+    const capabilityRequests = capabilityRequestsFromEffectPlan(plan, context);
+    const { decisions, decision } = evaluateCapabilityRequestsPolicy(capabilityRequests, context.config, {
+        grants: context.grants,
+        attestation: context.attestation,
+        egressProxyActive: context.egressProxyActive,
+    }, context.trustedWorkspaceRoots);
+    return { capabilityRequests, decisions, authorizationDecision: decision };
+}
+export function effectPlanPolicyRequiresAsk(decision) {
+    return policyDecisionRequiresAsk(decision);
+}
+export function effectPlanPolicyLegacyReason(decision) {
+    return policyDecisionToLegacyReason(decision);
+}

package/dist/core/effect-ir/types.d.ts

@@ -0,0 +1,55 @@
+import type { CapabilityAction, CapabilityEvidenceLevel, CapabilityResource } from '../capability/request.js';
+import type { VerdictOpacity } from '../verdict/types.js';
+export declare const EFFECT_PLAN_VERSION: 1;
+export type EffectTag = 'fs.read' | 'fs.write' | 'process.exec' | 'network.connect' | 'network.acquire' | 'git.ref.write' | 'secret.read' | 'control_plane.write' | 'read_only' | 'indeterminate';
+export type LauncherPhase = 'invoke' | 'resolve' | 'acquire' | 'cache_read' | 'cache_write' | 'delegate';
+export type PackageExecLauncher = 'npx' | 'npm' | 'pnpm';
+export interface EffectEvidence {
+    level: CapabilityEvidenceLevel;
+    signals: readonly string[];
+    basis: readonly string[];
+}
+export interface EffectProvenance {
+    segment?: string;
+    launcher?: PackageExecLauncher;
+    phase?: LauncherPhase;
+    innerCommand?: string;
+    innerArgv?: readonly string[];
+}
+export interface EffectRequirement {
+    tag: EffectTag;
+    action: CapabilityAction;
+    resource: CapabilityResource;
+    evidence: EffectEvidence;
+    provenance: EffectProvenance;
+    /** All contributing sources after requirement de-duplication. */
+    provenances?: readonly EffectProvenance[];
+}
+export interface ExecEffectNode {
+    kind: 'exec';
+    commandRedacted: string;
+    segmentHead: string;
+    requirements: readonly EffectRequirement[];
+}
+export interface LauncherEffectNode {
+    kind: 'launcher';
+    launcher: PackageExecLauncher | 'npm' | 'pnpm' | 'make';
+    phase: LauncherPhase;
+    opaque: boolean;
+    reason: string;
+    children: readonly EffectNode[];
+}
+export interface MergeEffectNode {
+    kind: 'merge';
+    children: readonly EffectNode[];
+}
+export type EffectNode = ExecEffectNode | LauncherEffectNode | MergeEffectNode;
+export interface EffectPlan {
+    version: typeof EFFECT_PLAN_VERSION;
+    root: EffectNode;
+    inputFingerprint: string;
+    opacity: VerdictOpacity;
+    disposition: 'effects' | 'effect_free';
+    completeness: 'complete' | 'partial';
+    signals: readonly string[];
+}

package/dist/core/effect-ir/types.js

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

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

@@ -3,5 +3,6 @@ import type { EgressAllowlistEntry, EgressAllowlistFile } from './types.js';
 export declare function egressAllowlistPath(config: BelayConfigV3, repoLocalStateDir: string): string;
 export declare function loadEgressAllowlist(filePath: string): Promise<EgressAllowlistFile>;
 export declare function saveEgressAllowlist(filePath: string, state: EgressAllowlistFile): Promise<void>;
+export declare function mutateEgressAllowlist(filePath: string, mutate: (state: EgressAllowlistFile) => EgressAllowlistFile): Promise<EgressAllowlistFile>;
 export declare function isHostAllowlisted(host: string, allowlist: EgressAllowlistFile): boolean;
 export declare function addDomainToAllowlist(allowlist: EgressAllowlistFile, entry: EgressAllowlistEntry): EgressAllowlistFile;

package/dist/core/egress/allowlist.js

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { withStateFileLock } from '../capability/approval-state-mutation.js';
 import { belayStateDir } from '../config.js';
 export function egressAllowlistPath(config, repoLocalStateDir) {
     return path.join(belayStateDir(config, repoLocalStateDir), 'egress-allowlist.json');
@@ -19,6 +20,13 @@ export async function saveEgressAllowlist(filePath, state) {
     await mkdir(path.dirname(filePath), { recursive: true });
     await writeFile(filePath, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
 }
+export async function mutateEgressAllowlist(filePath, mutate) {
+    return withStateFileLock(filePath, async () => {
+        const updated = mutate(await loadEgressAllowlist(filePath));
+        await saveEgressAllowlist(filePath, updated);
+        return updated;
+    });
+}
 export function isHostAllowlisted(host, allowlist) {
     const normalized = host.toLowerCase();
     return allowlist.domains.some((entry) => entry.host.toLowerCase() === normalized);