@guilz-dev/belay 0.6.0 → 0.7.0

package/dist/core/approval-service.js

@@ -2,18 +2,25 @@ import { approvedApprovalsPath, loadApprovalState, pendingApprovalsPath, saveApp
 import { compactApprovals } from './approval.js';
 import { buildApprovalRecordedMessage } from './approval-replay.js';
 import { verifyApprovalToken } from './approval-token.js';
+import { mutateApprovalStateWithRetry, mutatePendingAndApprovedWithRetry, } from './capability/approval-state-mutation.js';
 import { APPROVAL_STATE_VERSION_V3, mintGrantForApprovedRecord } from './capability/approval-v3.js';
 import { configuredControlPlaneDir } from './config.js';
 export async function recordApproval(params) {
     const { approvalId, config, store, token, requireSignedToken = false, adapter } = params;
-    const pending = await store.loadPending();
+    const [pending, approved] = await Promise.all([store.loadPending(), store.loadApproved()]);
     pending.state = compactApprovals(pending.state);
-    const index = pending.state.approvals.findIndex((approval) => approval.approvalId === approvalId);
-    if (index === -1) {
-        await store.writePending(pending.filePath, pending.state);
+    approved.state = compactApprovals(approved.state);
+    const pendingApproval = pending.state.approvals.find((entry) => entry.approvalId === approvalId);
+    const approvedApproval = approved.state.approvals.find((entry) => entry.approvalId === approvalId);
+    const approval = pendingApproval ?? approvedApproval;
+    if (!approval) {
+        await mutateApprovalStateWithRetry({
+            load: store.loadPending,
+            write: store.writePending,
+            mutate: (state) => ({ state: compactApprovals(state), result: true }),
+        });
         return { ok: false, message: 'Belay approval not found or expired.' };
     }
-    const [approval] = pending.state.approvals.slice(index, index + 1);
     if (requireSignedToken) {
         if (!token) {
             return { ok: false, message: 'Signed approval token required for out-of-band approval.' };
@@ -27,34 +34,86 @@ export async function recordApproval(params) {
             return { ok: false, message: 'Signed approval token does not match the pending approval.' };
         }
     }
-    pending.state.approvals.splice(index, 1);
-    await store.writePending(pending.filePath, pending.state);
-    const approved = await store.loadApproved();
-    approved.state = compactApprovals(approved.state);
-    const approvedRecord = mintGrantForApprovedRecord({
-        ...approval,
-        approvedAt: new Date().toISOString(),
+    if (!pendingApproval && approvedApproval) {
+        return {
+            ok: true,
+            message: buildApprovalRecordedMessage(config, approvedApproval, adapter),
+            approval: approvedApproval,
+        };
+    }
+    const recorded = await mutatePendingAndApprovedWithRetry({
+        loadPending: store.loadPending,
+        loadApproved: store.loadApproved,
+        writePending: store.writePending,
+        writeApproved: store.writeApproved,
+        mutate: (pendingState, approvedState) => {
+            const compactedPending = compactApprovals(pendingState);
+            const compactedApproved = compactApprovals(approvedState);
+            const existing = compactedApproved.approvals.find((entry) => entry.approvalId === approvalId);
+            if (existing &&
+                (existing.fingerprint !== approval.fingerprint || existing.repoRoot !== approval.repoRoot)) {
+                return null;
+            }
+            const pendingIndex = compactedPending.approvals.findIndex((entry) => entry.approvalId === approvalId &&
+                entry.fingerprint === approval.fingerprint &&
+                entry.repoRoot === approval.repoRoot);
+            if (pendingIndex === -1) {
+                return existing
+                    ? {
+                        pending: compactedPending,
+                        approved: compactedApproved,
+                        result: existing,
+                    }
+                    : null;
+            }
+            const [claimed] = compactedPending.approvals.splice(pendingIndex, 1);
+            if (!claimed) {
+                return null;
+            }
+            const approvedRecord = existing ??
+                mintGrantForApprovedRecord({
+                    ...claimed,
+                    approvedAt: new Date().toISOString(),
+                });
+            if (!existing) {
+                compactedApproved.version = APPROVAL_STATE_VERSION_V3;
+                compactedApproved.approvals.push(approvedRecord);
+            }
+            return {
+                pending: compactedPending,
+                approved: compactedApproved,
+                result: approvedRecord,
+            };
+        },
     });
-    approved.state.version = APPROVAL_STATE_VERSION_V3;
-    approved.state.revision = (approved.state.revision ?? 0) + 1;
-    approved.state.approvals.push(approvedRecord);
-    await store.writeApproved(approved.filePath, approved.state);
+    if (!recorded) {
+        return { ok: false, message: 'Belay approval not found, expired, or already claimed.' };
+    }
     return {
         ok: true,
-        message: buildApprovalRecordedMessage(config, approval, adapter),
-        approval: approvedRecord,
+        message: buildApprovalRecordedMessage(config, recorded, adapter),
+        approval: recorded,
     };
 }
-/** CLI `--replay` already executed the shell command; drop the one-shot grant. */
+/** @deprecated Replay callers must claim before execution with `claimApprovedForReplay`. */
 export async function consumeApprovedAfterCliReplay(params) {
-    const approved = await params.store.loadApproved();
-    approved.state = compactApprovals(approved.state);
-    const remaining = approved.state.approvals.filter((approval) => approval.approvalId !== params.approvalId);
-    if (remaining.length === approved.state.approvals.length) {
-        return;
-    }
-    approved.state.approvals = remaining;
-    await params.store.writeApproved(approved.filePath, approved.state);
+    await claimApprovedForReplay(params);
+}
+/** Atomically spend and return a one-shot approval before executing its replay. */
+export async function claimApprovedForReplay(params) {
+    return mutateApprovalStateWithRetry({
+        load: params.store.loadApproved,
+        write: params.store.writeApproved,
+        mutate: (state) => {
+            const compacted = compactApprovals(state);
+            const index = compacted.approvals.findIndex((approval) => approval.approvalId === params.approvalId);
+            if (index === -1) {
+                return null;
+            }
+            const [claimed] = compacted.approvals.splice(index, 1);
+            return { state: compacted, result: claimed ?? null };
+        },
+    });
 }
 export function createGateApprovalStore(repoRoot, config) {
     return {

package/dist/core/approval.d.ts

@@ -25,6 +25,7 @@ export declare function createApprovalRecordWithEnvelope(params: {
     };
     scopeHint?: ApprovalRecord['scopeHint'];
     capabilityRequests?: ApprovalRecord['capabilityRequests'];
+    effectPlanHash?: string;
 }): ApprovalRecord;
 export declare function createApprovalRecord(params: {
     kind: ApprovalRecord['kind'];
@@ -42,4 +43,5 @@ export declare function createApprovalRecord(params: {
     payloadJson?: string;
     scopeHint?: ApprovalRecord['scopeHint'];
     capabilityRequests?: ApprovalRecord['capabilityRequests'];
+    effectPlanHash?: string;
 }): ApprovalRecord;

package/dist/core/approval.js

@@ -7,13 +7,15 @@ export function nowIso() {
     return new Date().toISOString();
 }
 export function isExpired(approval) {
-    return Date.parse(approval.expiresAt) <= Date.now();
+    const expiresAt = Date.parse(approval.expiresAt);
+    return !Number.isFinite(expiresAt) || expiresAt <= Date.now();
 }
 export function isExecutionLeaseExpired(approval) {
     if (!approval.executionLeaseExpiresAt) {
         return false;
     }
-    return Date.parse(approval.executionLeaseExpiresAt) <= Date.now();
+    const expiresAt = Date.parse(approval.executionLeaseExpiresAt);
+    return !Number.isFinite(expiresAt) || expiresAt <= Date.now();
 }
 export function compactApprovals(state) {
     const compacted = {
@@ -89,6 +91,7 @@ export function createApprovalRecordWithEnvelope(params) {
         payloadJson: envelope.payloadJson,
         scopeHint: params.scopeHint,
         capabilityRequests: params.capabilityRequests,
+        effectPlanHash: params.effectPlanHash,
     });
 }
 export function createApprovalRecord(params) {
@@ -123,5 +126,5 @@ export function createApprovalRecord(params) {
     if (params.scopeHint) {
         record.scopeHint = params.scopeHint;
     }
-    return attachCapabilityEnvelope(record, params.capabilityRequests);
+    return attachCapabilityEnvelope(record, params.capabilityRequests, params.effectPlanHash);
 }

package/dist/core/audit-types.d.ts

@@ -20,10 +20,23 @@ export interface AuditRecord {
     predictedAssessment?: Assessment;
     observedAssessment?: Assessment;
     transactional?: boolean;
+    transactionalBackend?: 'git_worktree' | 'file_checkpoint';
+    resourceKind?: 'git_repository' | 'directory';
+    baselineTreeHash?: string;
+    snapshotFileCount?: number;
+    snapshotSourceBytes?: number;
+    snapshotWorkspaceBytes?: number;
+    snapshotCopyStrategy?: 'clonefile' | 'reflink' | 'copy';
+    snapshotPrepareMs?: number;
     transactionalReason?: string;
     transactionalCategories?: string[];
     transactionalChangeCount?: number;
     transactionalSkipReason?: string;
+    transactionalSkipDetail?: string;
+    recoveryCheckpointId?: string;
+    recoveryBackend?: string;
+    recoveryProofHash?: string;
+    recoveryState?: string;
     replayContext?: AuditReplayContext;
     actionSnapshot?: AuditActionSnapshot;
     [key: string]: unknown;

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

@@ -1,4 +1,5 @@
 import type { ApprovalStateFile } from '../types.js';
+export declare function withStateFileLock<T>(filePath: string, operation: () => Promise<T>, maxRetries?: number): Promise<T>;
 export declare function mutateApprovalStateWithRetry<T>(params: {
     load: () => Promise<{
         filePath: string;
@@ -11,3 +12,21 @@ export declare function mutateApprovalStateWithRetry<T>(params: {
     } | null;
     maxRetries?: number;
 }): Promise<T | null>;
+export declare function mutatePendingAndApprovedWithRetry<T>(params: {
+    loadPending: () => Promise<{
+        filePath: string;
+        state: ApprovalStateFile;
+    }>;
+    loadApproved: () => Promise<{
+        filePath: string;
+        state: ApprovalStateFile;
+    }>;
+    writePending: (filePath: string, state: ApprovalStateFile) => Promise<void>;
+    writeApproved: (filePath: string, state: ApprovalStateFile) => Promise<void>;
+    mutate: (pending: ApprovalStateFile, approved: ApprovalStateFile) => {
+        pending: ApprovalStateFile;
+        approved: ApprovalStateFile;
+        result: T;
+    } | null;
+    maxRetries?: number;
+}): Promise<T | null>;

package/dist/core/capability/approval-state-mutation.js

@@ -1,5 +1,6 @@
 import { constants } from 'node:fs';
-import { open, readFile, unlink } from 'node:fs/promises';
+import { mkdir, open, readFile, unlink } from 'node:fs/promises';
+import path from 'node:path';
 import { upgradeApprovalStateToV3 } from './approval-v3.js';
 const DEFAULT_RETRIES = 8;
 const LOCK_STALE_MS = 5 * 60_000;
@@ -31,6 +32,7 @@ async function isStaleApprovalLock(lockPath) {
     }
 }
 async function acquireApprovalStateLock(lockPath, maxRetries) {
+    await mkdir(path.dirname(lockPath), { recursive: true });
     for (let attempt = 0; attempt < maxRetries; attempt += 1) {
         try {
             const handle = await open(lockPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY);
@@ -53,14 +55,27 @@ async function acquireApprovalStateLock(lockPath, maxRetries) {
     }
     throw new Error(`Failed to acquire approval state lock: ${lockPath}`);
 }
+export async function withStateFileLock(filePath, operation, maxRetries = DEFAULT_RETRIES) {
+    const release = await acquireApprovalStateLock(`${filePath}.lock`, maxRetries);
+    try {
+        return await operation();
+    }
+    finally {
+        await release();
+    }
+}
 export async function mutateApprovalStateWithRetry(params) {
     const maxRetries = params.maxRetries ?? DEFAULT_RETRIES;
     for (let attempt = 0; attempt < maxRetries; attempt += 1) {
-        const loaded = await params.load();
-        const lockPath = `${loaded.filePath}.lock`;
+        const initial = await params.load();
+        const lockPath = `${initial.filePath}.lock`;
         let release = null;
         try {
             release = await acquireApprovalStateLock(lockPath, maxRetries);
+            const loaded = await params.load();
+            if (loaded.filePath !== initial.filePath) {
+                throw new Error('Approval state path changed while acquiring lock');
+            }
             const base = upgradeApprovalStateToV3(loaded.state);
             const revision = base.revision ?? 0;
             const outcome = params.mutate(base);
@@ -90,3 +105,61 @@ export async function mutateApprovalStateWithRetry(params) {
     }
     return null;
 }
+export async function mutatePendingAndApprovedWithRetry(params) {
+    const maxRetries = params.maxRetries ?? DEFAULT_RETRIES;
+    const [initialPending, initialApproved] = await Promise.all([
+        params.loadPending(),
+        params.loadApproved(),
+    ]);
+    const lockPaths = [`${initialPending.filePath}.lock`, `${initialApproved.filePath}.lock`].sort();
+    if (lockPaths[0] === lockPaths[1]) {
+        throw new Error('Pending and approved state must use different files');
+    }
+    const releases = [];
+    try {
+        for (const lockPath of lockPaths) {
+            releases.push(await acquireApprovalStateLock(lockPath, maxRetries));
+        }
+        const [pendingLoaded, approvedLoaded] = await Promise.all([
+            params.loadPending(),
+            params.loadApproved(),
+        ]);
+        if (pendingLoaded.filePath !== initialPending.filePath ||
+            approvedLoaded.filePath !== initialApproved.filePath) {
+            throw new Error('Approval state paths changed while acquiring locks');
+        }
+        const pending = upgradeApprovalStateToV3(pendingLoaded.state);
+        const approved = upgradeApprovalStateToV3(approvedLoaded.state);
+        const outcome = params.mutate(pending, approved);
+        if (!outcome) {
+            return null;
+        }
+        const nextApproved = {
+            ...outcome.approved,
+            version: 3,
+            revision: (approved.revision ?? 0) + 1,
+        };
+        const nextPending = {
+            ...outcome.pending,
+            version: 3,
+            revision: (pending.revision ?? 0) + 1,
+        };
+        // Claim first: interruption may require a fresh approval, but can never duplicate a grant.
+        await params.writePending(pendingLoaded.filePath, nextPending);
+        await params.writeApproved(approvedLoaded.filePath, nextApproved);
+        const [verifiedPending, verifiedApproved] = await Promise.all([
+            params.loadPending(),
+            params.loadApproved(),
+        ]);
+        if ((upgradeApprovalStateToV3(verifiedPending.state).revision ?? 0) !== nextPending.revision ||
+            (upgradeApprovalStateToV3(verifiedApproved.state).revision ?? 0) !== nextApproved.revision) {
+            return null;
+        }
+        return outcome.result;
+    }
+    finally {
+        for (const release of releases.reverse()) {
+            await release();
+        }
+    }
+}

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

@@ -2,14 +2,31 @@ import type { ApprovalRecord, ApprovalStateFile } from '../types.js';
 import type { CapabilityGrantV1 } from './grant.js';
 import type { CapabilityRequestV1 } from './request.js';
 export declare const APPROVAL_STATE_VERSION_V3: 3;
+export declare const EFFECT_PLAN_HASH_VERSION: "effect-plan:v1";
 export declare function normalizeApprovalStateVersion(state: ApprovalStateFile): ApprovalStateFile;
 export declare function upgradeApprovalStateToV3(state: ApprovalStateFile): ApprovalStateFile;
-export declare function attachCapabilityEnvelope(approval: ApprovalRecord, capabilityRequests?: CapabilityRequestV1[]): ApprovalRecord;
+export declare function attachCapabilityEnvelope(approval: ApprovalRecord, capabilityRequests?: CapabilityRequestV1[], effectPlanHash?: string): ApprovalRecord;
+/** Dual-read: expose legacy single grant as a one-element bundle without mutating storage. */
+export declare function normalizeApprovalGrants(approval: ApprovalRecord): ApprovalRecord;
+export declare function mintCapabilityGrantForRequest(params: {
+    approval: ApprovalRecord;
+    request: CapabilityRequestV1;
+    grantSuffix?: string;
+    issuer?: string;
+    maxUses?: number;
+}): CapabilityGrantV1;
+/** @deprecated Use mintCapabilityGrantBundle; returns first grant only for legacy callers. */
 export declare function mintCapabilityGrant(params: {
     approval: ApprovalRecord;
     capabilityRequests: CapabilityRequestV1[];
     issuer?: string;
     maxUses?: number;
 }): CapabilityGrantV1 | null;
+export declare function mintCapabilityGrantBundle(params: {
+    approval: ApprovalRecord;
+    capabilityRequests: CapabilityRequestV1[];
+    issuer?: string;
+    maxUses?: number;
+}): CapabilityGrantV1[];
 export declare function mintGrantForApprovedRecord(approval: ApprovalRecord): ApprovalRecord;
 export declare function newGrantId(): string;

package/dist/core/capability/approval-v3.js

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { hashCapabilityRequests } from './capability-request-hash.js';
 import { CAPABILITY_GRANT_VERSION } from './grant.js';
 export const APPROVAL_STATE_VERSION_V3 = 3;
+export const EFFECT_PLAN_HASH_VERSION = 'effect-plan:v1';
 export function normalizeApprovalStateVersion(state) {
     const version = state.version === APPROVAL_STATE_VERSION_V3
         ? APPROVAL_STATE_VERSION_V3
@@ -26,29 +27,45 @@ export function upgradeApprovalStateToV3(state) {
         })),
     };
 }
-export function attachCapabilityEnvelope(approval, capabilityRequests) {
-    if (!capabilityRequests?.length) {
-        return approval;
+export function attachCapabilityEnvelope(approval, capabilityRequests, effectPlanHash) {
+    const withRequests = !capabilityRequests?.length
+        ? approval
+        : {
+            ...approval,
+            capabilityRequests,
+            capabilityRequestHash: hashCapabilityRequests(capabilityRequests),
+        };
+    if (!effectPlanHash) {
+        return withRequests;
     }
     return {
-        ...approval,
-        capabilityRequests,
-        capabilityRequestHash: hashCapabilityRequests(capabilityRequests),
+        ...withRequests,
+        effectPlanHash,
     };
 }
-export function mintCapabilityGrant(params) {
-    const request = params.capabilityRequests[0];
-    if (!request) {
-        return null;
+/** Dual-read: expose legacy single grant as a one-element bundle without mutating storage. */
+export function normalizeApprovalGrants(approval) {
+    if (approval.grants?.length) {
+        return approval;
     }
+    if (approval.grant) {
+        return { ...approval, grants: [approval.grant] };
+    }
+    return approval;
+}
+export function mintCapabilityGrantForRequest(params) {
     const expiresAt = params.approval.expiresAt;
+    const suffix = params.grantSuffix ?? '';
+    const grantId = suffix === '' || suffix === '0'
+        ? `grant_${params.approval.approvalId}${suffix === '0' && params.grantSuffix !== undefined ? '_0' : ''}`
+        : `grant_${params.approval.approvalId}_${suffix}`;
     return {
         version: CAPABILITY_GRANT_VERSION,
-        grantId: `grant_${params.approval.approvalId}`,
-        principal: request.principal,
-        action: request.action,
-        resource: request.resource,
-        inputFingerprint: request.context.inputFingerprint,
+        grantId,
+        principal: params.request.principal,
+        action: params.request.action,
+        resource: params.request.resource,
+        inputFingerprint: params.request.context.inputFingerprint,
         issuedAt: params.approval.approvedAt ?? new Date().toISOString(),
         expiresAt,
         maxUses: params.maxUses ?? 1,
@@ -56,18 +73,41 @@ export function mintCapabilityGrant(params) {
         issuer: params.issuer ?? 'belay-approval-v3',
     };
 }
+/** @deprecated Use mintCapabilityGrantBundle; returns first grant only for legacy callers. */
+export function mintCapabilityGrant(params) {
+    const bundle = mintCapabilityGrantBundle(params);
+    return bundle[0] ?? null;
+}
+export function mintCapabilityGrantBundle(params) {
+    if (!params.capabilityRequests.length) {
+        return [];
+    }
+    return params.capabilityRequests.map((request, index) => mintCapabilityGrantForRequest({
+        approval: params.approval,
+        request,
+        grantSuffix: params.capabilityRequests.length === 1 ? undefined : String(index),
+        issuer: params.issuer,
+        maxUses: params.maxUses,
+    }));
+}
 export function mintGrantForApprovedRecord(approval) {
-    if (approval.grant || !approval.capabilityRequests?.length) {
-        return approval;
+    const normalized = normalizeApprovalGrants(approval);
+    if ((normalized.grants?.length ?? 0) > 0 || !normalized.capabilityRequests?.length) {
+        return normalized;
     }
-    const grant = mintCapabilityGrant({
-        approval,
-        capabilityRequests: approval.capabilityRequests,
+    const grants = mintCapabilityGrantBundle({
+        approval: normalized,
+        capabilityRequests: normalized.capabilityRequests,
     });
-    if (!grant) {
-        return approval;
+    if (!grants.length) {
+        return normalized;
     }
-    return { ...approval, grant };
+    return {
+        ...normalized,
+        grants,
+        grant: grants[0],
+        grantBundleVersion: 1,
+    };
 }
 export function newGrantId() {
     return `grant_${randomUUID().replaceAll('-', '').slice(0, 16)}`;

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

@@ -8,6 +8,9 @@ export interface BoundaryAttestation {
     deniesUngrantedEffects: boolean;
     materializesGrants: boolean;
     probeSignals: string[];
+    /** When true, the driver can mount an execution mirror at the original workspace path. */
+    isolatesWorkspaceMounts?: boolean;
 }
 export declare function validateBoundaryAttestation(value: unknown): value is BoundaryAttestation;
 export declare function isAttestationFresh(attestation: BoundaryAttestation, now?: number): boolean;
+export declare function attestsWorkspaceMountIsolation(attestation: BoundaryAttestation | null | undefined): boolean;

package/dist/core/capability/attestation.js

@@ -30,6 +30,10 @@ export function validateBoundaryAttestation(value) {
         !record.probeSignals.every((s) => typeof s === 'string')) {
         return false;
     }
+    if (record.isolatesWorkspaceMounts !== undefined &&
+        typeof record.isolatesWorkspaceMounts !== 'boolean') {
+        return false;
+    }
     if (record.driver === 'host-integration' && record.materializesGrants) {
         return false;
     }
@@ -53,3 +57,6 @@ export function isAttestationFresh(attestation, now = Date.now()) {
     }
     return attestation.deniesUngrantedEffects;
 }
+export function attestsWorkspaceMountIsolation(attestation) {
+    return attestation?.isolatesWorkspaceMounts === true;
+}

package/dist/core/capability/boundary-driver-container.d.ts

@@ -1,5 +1,17 @@
 import type { BoundaryDriver } from './boundary-driver.js';
+import { type BoundaryRunOptions } from './boundary-run.js';
 export declare function isDockerAvailable(): Promise<boolean>;
+export interface ContainerRunParams {
+    image: string;
+    command: string;
+    cwd: string;
+    proxyEnv: Record<string, string>;
+    mountReadOnly: boolean;
+    repoRoot?: string;
+    runOptions?: BoundaryRunOptions;
+    containerName?: string;
+}
+export declare function buildContainerRunArgs(params: ContainerRunParams): string[];
 export declare function createContainerBoundaryDriver(options?: {
     image?: string;
     egressProxyEnv?: Record<string, string>;