@guilz-dev/belay 0.4.0 → 0.7.0

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

@@ -0,0 +1,165 @@
+import { constants } from 'node:fs';
+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;
+async function sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function isStaleApprovalLock(lockPath) {
+    try {
+        const raw = await readFile(lockPath, 'utf8');
+        const [pidText, timestampText] = raw.trim().split(':');
+        const timestamp = Number(timestampText);
+        if (Number.isFinite(timestamp) && Date.now() - timestamp > LOCK_STALE_MS) {
+            return true;
+        }
+        const pid = Number(pidText);
+        if (!Number.isFinite(pid)) {
+            return true;
+        }
+        try {
+            process.kill(pid, 0);
+            return false;
+        }
+        catch {
+            return true;
+        }
+    }
+    catch {
+        return false;
+    }
+}
+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);
+            await handle.writeFile(`${process.pid}:${Date.now()}`);
+            await handle.close();
+            return async () => {
+                await unlink(lockPath).catch(() => { });
+            };
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'EEXIST') {
+                throw error;
+            }
+            if (await isStaleApprovalLock(lockPath)) {
+                await unlink(lockPath).catch(() => { });
+            }
+            await sleep(5 + attempt * 8);
+        }
+    }
+    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 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);
+            if (!outcome) {
+                return null;
+            }
+            const next = {
+                ...outcome.state,
+                version: 3,
+                revision: revision + 1,
+            };
+            const verifyBeforeWrite = upgradeApprovalStateToV3((await params.load()).state);
+            if ((verifyBeforeWrite.revision ?? 0) !== revision) {
+                continue;
+            }
+            await params.write(loaded.filePath, next);
+            const verify = upgradeApprovalStateToV3((await params.load()).state);
+            if ((verify.revision ?? 0) === revision + 1) {
+                return outcome.result;
+            }
+        }
+        finally {
+            if (release) {
+                await release();
+            }
+        }
+    }
+    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

@@ -0,0 +1,32 @@
+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[], 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

@@ -0,0 +1,114 @@
+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
+        : state.version === 2
+            ? 2
+            : 1;
+    return { ...state, version };
+}
+export function upgradeApprovalStateToV3(state) {
+    const normalized = normalizeApprovalStateVersion(state);
+    if (normalized.version === APPROVAL_STATE_VERSION_V3) {
+        return normalized;
+    }
+    return {
+        version: APPROVAL_STATE_VERSION_V3,
+        approvals: normalized.approvals.map((approval) => ({
+            ...approval,
+            capabilityRequestHash: approval.capabilityRequestHash ??
+                (approval.capabilityRequests?.length
+                    ? hashCapabilityRequests(approval.capabilityRequests)
+                    : undefined),
+        })),
+    };
+}
+export function attachCapabilityEnvelope(approval, capabilityRequests, effectPlanHash) {
+    const withRequests = !capabilityRequests?.length
+        ? approval
+        : {
+            ...approval,
+            capabilityRequests,
+            capabilityRequestHash: hashCapabilityRequests(capabilityRequests),
+        };
+    if (!effectPlanHash) {
+        return withRequests;
+    }
+    return {
+        ...withRequests,
+        effectPlanHash,
+    };
+}
+/** 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,
+        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,
+        usesRemaining: params.maxUses ?? 1,
+        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) {
+    const normalized = normalizeApprovalGrants(approval);
+    if ((normalized.grants?.length ?? 0) > 0 || !normalized.capabilityRequests?.length) {
+        return normalized;
+    }
+    const grants = mintCapabilityGrantBundle({
+        approval: normalized,
+        capabilityRequests: normalized.capabilityRequests,
+    });
+    if (!grants.length) {
+        return normalized;
+    }
+    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

@@ -0,0 +1,16 @@
+export declare const BOUNDARY_ATTESTATION_VERSION: 1;
+export type BoundaryDriverId = 'container' | 'cursor-sandbox' | 'seatbelt' | 'landlock' | 'host-integration';
+export interface BoundaryAttestation {
+    version: typeof BOUNDARY_ATTESTATION_VERSION;
+    driver: BoundaryDriverId;
+    probedAt: string;
+    expiresAt: string;
+    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

@@ -0,0 +1,62 @@
+export const BOUNDARY_ATTESTATION_VERSION = 1;
+const KNOWN_DRIVERS = new Set([
+    'container',
+    'cursor-sandbox',
+    'seatbelt',
+    'landlock',
+    'host-integration',
+]);
+export function validateBoundaryAttestation(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const record = value;
+    if (record.version !== BOUNDARY_ATTESTATION_VERSION) {
+        return false;
+    }
+    if (!KNOWN_DRIVERS.has(record.driver)) {
+        return false;
+    }
+    if (typeof record.probedAt !== 'string' || typeof record.expiresAt !== 'string') {
+        return false;
+    }
+    if (typeof record.deniesUngrantedEffects !== 'boolean') {
+        return false;
+    }
+    if (typeof record.materializesGrants !== 'boolean') {
+        return false;
+    }
+    if (!Array.isArray(record.probeSignals) ||
+        !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;
+    }
+    if (record.driver === 'container' &&
+        record.materializesGrants &&
+        !record.deniesUngrantedEffects) {
+        return false;
+    }
+    return true;
+}
+export function isAttestationFresh(attestation, now = Date.now()) {
+    const expires = Date.parse(attestation.expiresAt);
+    if (!Number.isFinite(expires)) {
+        return false;
+    }
+    if (expires <= now) {
+        return false;
+    }
+    if (attestation.driver === 'host-integration') {
+        return true;
+    }
+    return attestation.deniesUngrantedEffects;
+}
+export function attestsWorkspaceMountIsolation(attestation) {
+    return attestation?.isolatesWorkspaceMounts === true;
+}

package/dist/core/capability/boundary-attestation-sign.d.ts

@@ -0,0 +1,21 @@
+import type { BoundaryAttestation } from './attestation.js';
+export type BoundaryAttestationFileFormat = 'signed' | 'legacy' | 'missing' | 'invalid';
+export interface SignedBoundaryAttestationFile {
+    version: 1;
+    repoRoot: string;
+    attestation: BoundaryAttestation;
+    signature: string;
+}
+export declare function signBoundaryAttestation(params: {
+    repoRoot: string;
+    attestation: BoundaryAttestation;
+    controlPlaneDir: string;
+}): Promise<SignedBoundaryAttestationFile>;
+export declare function verifySignedBoundaryAttestation(params: {
+    file: unknown;
+    expectedRepoRoot: string;
+    controlPlaneDir: string;
+}): Promise<BoundaryAttestation | null>;
+export declare function readSignedAttestationFile(filePath: string): Promise<unknown>;
+export declare function isLegacyAttestationFormat(file: unknown): file is BoundaryAttestation;
+export declare function inspectBoundaryAttestationFile(filePath: string): Promise<BoundaryAttestationFileFormat>;

package/dist/core/capability/boundary-attestation-sign.js

@@ -0,0 +1,84 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { access, readFile } from 'node:fs/promises';
+import { loadOrCreateApprovalSigningKey } from '../approval-token.js';
+import { canonicalStringify } from '../fingerprint.js';
+import { validateBoundaryAttestation } from './attestation.js';
+function signBody(repoRoot, attestation, key) {
+    const payload = canonicalStringify({ repoRoot, attestation });
+    return createHmac('sha256', key).update(payload).digest('base64url');
+}
+export async function signBoundaryAttestation(params) {
+    const key = await loadOrCreateApprovalSigningKey(params.controlPlaneDir);
+    const signature = signBody(params.repoRoot, params.attestation, key);
+    return {
+        version: 1,
+        repoRoot: params.repoRoot,
+        attestation: params.attestation,
+        signature,
+    };
+}
+export async function verifySignedBoundaryAttestation(params) {
+    if (!params.file || typeof params.file !== 'object') {
+        return null;
+    }
+    const record = params.file;
+    if (record.version !== 1 || typeof record.repoRoot !== 'string' || !record.attestation) {
+        return null;
+    }
+    if (record.repoRoot !== params.expectedRepoRoot) {
+        return null;
+    }
+    if (!validateBoundaryAttestation(record.attestation)) {
+        return null;
+    }
+    if (typeof record.signature !== 'string' || !record.signature) {
+        return null;
+    }
+    const key = await loadOrCreateApprovalSigningKey(params.controlPlaneDir);
+    const expected = signBody(record.repoRoot, record.attestation, key);
+    const actualBuffer = Buffer.from(record.signature);
+    const expectedBuffer = Buffer.from(expected);
+    if (actualBuffer.length !== expectedBuffer.length ||
+        !timingSafeEqual(actualBuffer, expectedBuffer)) {
+        return null;
+    }
+    return record.attestation;
+}
+export async function readSignedAttestationFile(filePath) {
+    return JSON.parse(await readFile(filePath, 'utf8'));
+}
+export function isLegacyAttestationFormat(file) {
+    if (!file || typeof file !== 'object') {
+        return false;
+    }
+    const record = file;
+    return (record.version === 1 &&
+        typeof record.driver === 'string' &&
+        !('signature' in record) &&
+        !('attestation' in record));
+}
+export async function inspectBoundaryAttestationFile(filePath) {
+    try {
+        await access(filePath);
+    }
+    catch {
+        return 'missing';
+    }
+    try {
+        const raw = await readSignedAttestationFile(filePath);
+        if (isLegacyAttestationFormat(raw)) {
+            return validateBoundaryAttestation(raw) ? 'legacy' : 'invalid';
+        }
+        const record = raw;
+        if (record.version === 1 &&
+            typeof record.repoRoot === 'string' &&
+            record.attestation &&
+            typeof record.signature === 'string') {
+            return 'signed';
+        }
+        return 'invalid';
+    }
+    catch {
+        return 'invalid';
+    }
+}

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

@@ -0,0 +1,19 @@
+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>;
+    repoRoot?: string;
+}): BoundaryDriver;