@guilz-dev/belay 0.6.0 → 0.8.0

package/dist/core/recovery/snapshot-node.js

@@ -0,0 +1,261 @@
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { chmod, copyFile, lstat, mkdir, open, readFile, readlink, rm, rmdir, symlink, writeFile, } from 'node:fs/promises';
+import path from 'node:path';
+import { canonicalStringify, hashValue } from '../fingerprint.js';
+import { canonicalPath } from '../path-utils.js';
+export const RECOVERY_UNSUPPORTED_FILE_KIND = 'recovery_unsupported_file_kind';
+export function validRecoveryRelativePath(relativePath) {
+    if (!relativePath || relativePath.includes('\0') || path.isAbsolute(relativePath))
+        return false;
+    const normalized = path.normalize(relativePath);
+    return normalized !== '.' && normalized !== '..' && !normalized.startsWith(`..${path.sep}`);
+}
+export async function assertRecoverySafeTarget(resourceRoot, relativePath) {
+    if (!validRecoveryRelativePath(relativePath))
+        throw new Error('recovery_path_escape');
+    const root = canonicalPath(resourceRoot);
+    const target = path.resolve(root, relativePath);
+    const relative = path.relative(root, target);
+    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error('recovery_path_escape');
+    }
+    let current = root;
+    const parentParts = path.relative(root, path.dirname(target)).split(path.sep).filter(Boolean);
+    for (const part of parentParts) {
+        current = path.join(current, part);
+        if (!existsSync(current))
+            break;
+        const info = await lstat(current);
+        if (info.isSymbolicLink())
+            throw new Error('recovery_symlink_escape');
+        if (!info.isDirectory())
+            break;
+    }
+    return target;
+}
+async function fsyncPath(filePath) {
+    const handle = await open(filePath, 'r');
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+function normalizedMode(mode) {
+    return mode & 0o777;
+}
+export function recoveryDirectoryHash(mode) {
+    return hashValue(`directory:${normalizedMode(mode)}`);
+}
+export function recoverySnapshotHash(snapshot) {
+    return hashValue(canonicalStringify(snapshot));
+}
+export function withoutRecoveryBlob(snapshot) {
+    if (snapshot.kind !== 'file')
+        return { ...snapshot };
+    const { blob: _blob, ...rest } = snapshot;
+    return rest;
+}
+export async function captureRecoverySnapshot(filePath, options) {
+    let info;
+    try {
+        info = await lstat(filePath);
+    }
+    catch (error) {
+        if (!['ENOENT', 'ENOTDIR'].includes(error.code ?? ''))
+            throw error;
+        return { kind: 'absent' };
+    }
+    if (info.isSymbolicLink()) {
+        const symlinkTarget = await readlink(filePath);
+        return {
+            kind: 'symlink',
+            symlinkTarget,
+            hash: hashValue(`symlink:${symlinkTarget}`),
+        };
+    }
+    if (info.isDirectory()) {
+        const mode = normalizedMode(info.mode);
+        return { kind: 'directory', mode, hash: recoveryDirectoryHash(mode) };
+    }
+    if (!info.isFile())
+        throw new Error(RECOVERY_UNSUPPORTED_FILE_KIND);
+    const content = await readFile(filePath);
+    const hash = createHash('sha256').update(content).digest('hex');
+    let blob;
+    if (options?.blobDir) {
+        await mkdir(options.blobDir, { recursive: true, mode: 0o700 });
+        const blobPath = path.join(options.blobDir, hash);
+        if (!existsSync(blobPath)) {
+            await writeFile(blobPath, content, { mode: 0o600 });
+            await fsyncPath(blobPath);
+        }
+        blob = `blobs/${hash}`;
+    }
+    return { kind: 'file', mode: normalizedMode(info.mode), hash, ...(blob ? { blob } : {}) };
+}
+export async function recoverySnapshotMatches(filePath, expected) {
+    try {
+        const current = await captureRecoverySnapshot(filePath);
+        return (recoverySnapshotHash(withoutRecoveryBlob(current)) ===
+            recoverySnapshotHash(withoutRecoveryBlob(expected)));
+    }
+    catch {
+        return false;
+    }
+}
+export async function validateRecoverySnapshot(params) {
+    const { snapshot } = params;
+    if (!snapshot || typeof snapshot !== 'object' || Array.isArray(snapshot)) {
+        throw new Error(params.corruptReason);
+    }
+    const record = snapshot;
+    const hasExactKeys = (allowed) => {
+        const keys = Object.keys(record);
+        return keys.length === allowed.length && keys.every((key) => allowed.includes(key));
+    };
+    const validHash = (value) => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+    const validMode = (value) => typeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= 0o777;
+    if (record.kind === 'absent') {
+        if (!hasExactKeys(['kind']))
+            throw new Error(params.corruptReason);
+        return;
+    }
+    if (record.kind === 'directory') {
+        if (params.manifestVersion !== 2 ||
+            !hasExactKeys(['kind', 'mode', 'hash']) ||
+            !validMode(record.mode) ||
+            !validHash(record.hash) ||
+            record.hash !== recoveryDirectoryHash(record.mode)) {
+            throw new Error(params.corruptReason);
+        }
+        return;
+    }
+    if (record.kind === 'symlink') {
+        if (!hasExactKeys(['kind', 'symlinkTarget', 'hash']) ||
+            typeof record.symlinkTarget !== 'string' ||
+            !validHash(record.hash) ||
+            record.hash !== hashValue(`symlink:${record.symlinkTarget}`)) {
+            throw new Error(params.corruptReason);
+        }
+        return;
+    }
+    if (record.kind !== 'file')
+        throw new Error(params.corruptReason);
+    const allowedKeys = record.blob === undefined ? ['kind', 'mode', 'hash'] : ['kind', 'mode', 'hash', 'blob'];
+    if (!hasExactKeys(allowedKeys) ||
+        !validMode(record.mode) ||
+        !validHash(record.hash) ||
+        (record.blob !== undefined && typeof record.blob !== 'string')) {
+        throw new Error(params.corruptReason);
+    }
+    if (params.side === 'before' && !record.blob)
+        throw new Error(params.corruptReason);
+    if (!record.blob)
+        return;
+    if (record.blob !== `blobs/${record.hash}`)
+        throw new Error(params.corruptReason);
+    let content;
+    try {
+        content = await readFile(path.join(params.artifactDir, record.blob));
+    }
+    catch {
+        throw new Error(params.corruptReason);
+    }
+    if (createHash('sha256').update(content).digest('hex') !== record.hash) {
+        throw new Error(params.corruptReason);
+    }
+}
+async function removeTargetWithoutRecursion(target) {
+    let info;
+    try {
+        info = await lstat(target);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    if (info.isDirectory() && !info.isSymbolicLink()) {
+        await rmdir(target);
+        return;
+    }
+    await rm(target, { force: true, recursive: false });
+}
+export async function applyRecoverySnapshot(target, snapshot, artifactDir, corruptReason) {
+    if (snapshot.kind === 'absent') {
+        await removeTargetWithoutRecursion(target);
+        return;
+    }
+    let current;
+    try {
+        current = await lstat(target);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    if (snapshot.kind === 'directory') {
+        if (current && (!current.isDirectory() || current.isSymbolicLink())) {
+            await removeTargetWithoutRecursion(target);
+            current = undefined;
+        }
+        if (!current)
+            await mkdir(target, { recursive: false, mode: snapshot.mode });
+        await chmod(target, snapshot.mode);
+        return;
+    }
+    if (current)
+        await removeTargetWithoutRecursion(target);
+    await mkdir(path.dirname(target), { recursive: true });
+    if (snapshot.kind === 'symlink') {
+        if (snapshot.symlinkTarget === undefined)
+            throw new Error(corruptReason);
+        await symlink(snapshot.symlinkTarget, target);
+        return;
+    }
+    if (!snapshot.blob || !snapshot.hash)
+        throw new Error(corruptReason);
+    const blobPath = path.join(artifactDir, snapshot.blob);
+    let content;
+    try {
+        content = await readFile(blobPath);
+    }
+    catch {
+        throw new Error(corruptReason);
+    }
+    if (createHash('sha256').update(content).digest('hex') !== snapshot.hash) {
+        throw new Error(corruptReason);
+    }
+    await copyFile(blobPath, target);
+    if (snapshot.mode !== undefined)
+        await chmod(target, snapshot.mode);
+}
+function pathDepth(relativePath) {
+    return relativePath.split(path.sep).length;
+}
+export function sortRecoveryEntriesForSide(entries, side) {
+    const rank = (entry) => {
+        if (entry[side].kind === 'absent')
+            return 0;
+        if (entry[side].kind === 'directory')
+            return 1;
+        return 2;
+    };
+    return [...entries].sort((left, right) => {
+        const rankDifference = rank(left) - rank(right);
+        if (rankDifference !== 0)
+            return rankDifference;
+        const depthDifference = pathDepth(left.path) - pathDepth(right.path);
+        if (left[side].kind === 'absent' && depthDifference !== 0)
+            return -depthDifference;
+        if (depthDifference !== 0)
+            return depthDifference;
+        return left.path.localeCompare(right.path);
+    });
+}
+export function recoveryStateHash(entries, side) {
+    return hashValue(canonicalStringify(entries.map((entry) => ({ path: entry.path, state: entry[side] }))));
+}

package/dist/core/recovery/types.d.ts

@@ -7,11 +7,95 @@ export interface RecoveryProofV1 {
     inputFingerprint: string;
     resourceScope: string;
     baseStateHash: string;
-    effectClosure: 'repo_local_fs';
+    /** The proof covers only filesystem effects observed inside the repository. */
+    effectClosure: 'repo_local_fs_observed';
     issuedAt: string;
     expiresAt: string;
     probeSignals: string[];
 }
+export type RecoveryCheckpointState = 'prepared' | 'applying' | 'applied' | 'restoring' | 'restored' | 'conflict' | 'corrupt' | 'needs_manual_repair';
+export type RecoveryFileKind = 'absent' | 'file' | 'symlink';
+export interface RecoveryFileSnapshotV1 {
+    kind: RecoveryFileKind;
+    mode?: number;
+    hash?: string;
+    blob?: string;
+    symlinkTarget?: string;
+}
+export interface RecoveryCheckpointEntryV1 {
+    path: string;
+    before: RecoveryFileSnapshotV1;
+    after: RecoveryFileSnapshotV1;
+}
+export interface RecoveryCheckpointManifestV1 {
+    version: 1;
+    checkpointId: string;
+    backend: RecoveryBackend;
+    repoRoot: string;
+    repoIdentity: string;
+    commandFingerprint: string;
+    createdAt: string;
+    expiresAt: string;
+    proof: RecoveryProofV1;
+    entries: RecoveryCheckpointEntryV1[];
+}
+export type RecoveryFileSnapshotV2 = RecoveryFileSnapshotV1 | {
+    kind: 'directory';
+    mode: number;
+    hash: string;
+};
+export interface RecoveryCheckpointEntryV2 {
+    path: string;
+    before: RecoveryFileSnapshotV2;
+    after: RecoveryFileSnapshotV2;
+}
+export type RecoveryCheckpointEntry = RecoveryCheckpointEntryV1 | RecoveryCheckpointEntryV2;
+export interface RecoveryCheckpointManifestV2 {
+    version: 2;
+    checkpointId: string;
+    backend: RecoveryBackend;
+    repoRoot: string;
+    resourceKind: 'git_repository' | 'directory';
+    repoIdentity: string;
+    commandFingerprint: string;
+    createdAt: string;
+    expiresAt: string;
+    proof: RecoveryProofV1;
+    entries: RecoveryCheckpointEntryV2[];
+}
+export type RecoveryCheckpointManifest = RecoveryCheckpointManifestV1 | RecoveryCheckpointManifestV2;
+export interface RecoveryCheckpointStateV1 {
+    version: 1;
+    state: RecoveryCheckpointState;
+    updatedAt: string;
+    manifestHash: string;
+    detail?: string;
+}
+export interface RecoveryReceiptV1 {
+    version: 1;
+    checkpointId: string;
+    manifestHash: string;
+    proofHash: string;
+    postStateHash: string;
+    appliedAt: string;
+    changeCount: number;
+}
+export interface RecoveryCheckpointSummary {
+    checkpointId: string;
+    state: RecoveryCheckpointState;
+    /** Operator-facing detail from durable checkpoint state (e.g. mixed-state reason). */
+    stateDetail?: string;
+    backend: RecoveryBackend;
+    repoRoot: string;
+    commandFingerprint: string;
+    createdAt: string;
+    expiresAt: string;
+    changeCount: number;
+    manifestHash: string;
+    receiptHash?: string;
+    proofHash?: string;
+    postStateHash?: string;
+}
 export interface RecoveryProofContext {
     repoRoot: string;
     cwd: string;

package/dist/core/shell-substitution.d.ts

@@ -4,3 +4,4 @@ export { MAX_SUBSTITUTION_DEPTH };
  * Finds inner commands for $(...) and backtick substitution, respecting escapes and nesting.
  */
 export declare function findCommandSubstitutions(command: string): string[];
+export declare function findStructuralCommandSubstitutions(command: string): string[];

package/dist/core/shell-substitution.js

@@ -68,6 +68,67 @@ export function findCommandSubstitutions(command) {
     }
     return results;
 }
+export function findStructuralCommandSubstitutions(command) {
+    const results = [];
+    let index = 0;
+    let inSingle = false;
+    let inDouble = false;
+    let escaping = false;
+    while (index < command.length) {
+        const char = command[index];
+        if (escaping) {
+            escaping = false;
+            index += 1;
+            continue;
+        }
+        if (char === '\\' && !inSingle) {
+            escaping = true;
+            index += 1;
+            continue;
+        }
+        if (!inDouble && char === "'") {
+            inSingle = !inSingle;
+            index += 1;
+            continue;
+        }
+        if (!inSingle && char === '"') {
+            inDouble = !inDouble;
+            index += 1;
+            continue;
+        }
+        if (inSingle) {
+            index += 1;
+            continue;
+        }
+        if (char === '`') {
+            const end = findClosingBacktick(command, index + 1);
+            if (end === -1) {
+                break;
+            }
+            const inner = command.slice(index + 1, end).trim();
+            if (inner) {
+                results.push(inner);
+            }
+            index = end + 1;
+            continue;
+        }
+        if (char === '$' && command[index + 1] === '(') {
+            const closed = extractBalancedParenContent(command, index + 2);
+            if (!closed) {
+                index += 1;
+                continue;
+            }
+            const inner = closed.content.trim();
+            if (inner) {
+                results.push(inner);
+            }
+            index = closed.endIndex;
+            continue;
+        }
+        index += 1;
+    }
+    return results;
+}
 function findClosingBacktick(command, start) {
     let index = start;
     while (index < command.length) {

package/dist/core/standing-allow.d.ts

@@ -1,7 +1,7 @@
 import type { BelayConfigV4 } from './config.js';
 import type { GatedActionKind } from './gate-contract.js';
 import type { ClassifyResult } from './types.js';
-export type StandingAllowSource = 'provably-benign-corpus' | 'must-allow-catalog' | 'operator' | 'availability-reconfirmed';
+export type StandingAllowSource = 'operator' | 'availability-reconfirmed';
 export interface StandingAllowEntry {
     kind: GatedActionKind;
     fingerprint: string;
@@ -18,7 +18,6 @@ export interface StandingAllowFile {
 }
 export interface StandingAllowMatch {
     source: StandingAllowSource;
-    catalogCommand?: string;
     entryId?: string;
 }
 /** Default TTL for operator / availability-reconfirmed standing-allow entries. */

package/dist/core/standing-allow.js

@@ -1,7 +1,6 @@
 import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { STANDING_ALLOW_CATALOG } from '../corpus/standing-allow-catalog.generated.js';
 import { belayStateDir } from './config.js';
 const EMPTY_STANDING_ALLOW = {
     version: 1,
@@ -9,8 +8,6 @@ const EMPTY_STANDING_ALLOW = {
 };
 /** Default TTL for operator / availability-reconfirmed standing-allow entries. */
 export const DEFAULT_STANDING_ALLOW_TTL_MS = 30 * 24 * 60 * 60 * 1000;
-const PROVABLY_BENIGN_COMMANDS = new Set(STANDING_ALLOW_CATALOG.shell.provablyBenign.map((entry) => entry.normalizedCommand));
-const MUST_ALLOW_COMMANDS = new Set(STANDING_ALLOW_CATALOG.shell.mustAllow.map((entry) => entry.normalizedCommand));
 /** Reasons that must never be silenced via standing-allow (defense in depth with signal checks). */
 const STANDING_ALLOW_BLOCKED_REASONS = new Set([
     'external_effect',
@@ -95,18 +92,6 @@ export async function saveStandingAllow(filePath, state) {
     const compacted = compactStandingAllow(state);
     await writeFile(filePath, `${JSON.stringify(compacted, null, 2)}\n`, 'utf8');
 }
-function matchBundledCatalog(kind, normalizedCommand) {
-    if (kind !== 'shell' || !normalizedCommand) {
-        return null;
-    }
-    if (PROVABLY_BENIGN_COMMANDS.has(normalizedCommand)) {
-        return { source: 'provably-benign-corpus', catalogCommand: normalizedCommand };
-    }
-    if (MUST_ALLOW_COMMANDS.has(normalizedCommand)) {
-        return { source: 'must-allow-catalog', catalogCommand: normalizedCommand };
-    }
-    return null;
-}
 function matchStateEntry(params) {
     const now = params.now ?? Date.now();
     const match = params.state.entries.find((entry) => entry.kind === params.kind &&
@@ -119,17 +104,15 @@ function matchStateEntry(params) {
     return { source: match.source, entryId: match.fingerprint };
 }
 export function resolveStandingAllowMatch(params) {
+    if (params.kind === 'shell') {
+        return null;
+    }
     if (params.result.verdict !== 'deny_pending_approval') {
         return null;
     }
     if (isTier0StandingAllowBlocked(params.result)) {
         return null;
     }
-    const normalizedCommand = params.result.normalizedCommand ?? params.result.summary ?? '';
-    const catalogMatch = matchBundledCatalog(params.kind, normalizedCommand);
-    if (catalogMatch) {
-        return catalogMatch;
-    }
     return matchStateEntry({
         kind: params.kind,
         fingerprint: params.result.fingerprint,

package/dist/core/transactional/apply-observed-changes.d.ts

@@ -0,0 +1,13 @@
+import type { ObservedFileChange } from './file-tree.js';
+import type { TransactionalFileChange } from './types.js';
+export declare const TRANSACTIONAL_APPLY_TOCTOU = "transactional_apply_toctou";
+export declare const TRANSACTIONAL_APPLY_CONFLICT = "transactional_apply_conflict";
+export declare const TRANSACTIONAL_APPLY_ROLLBACK_FAILED = "transactional_apply_rollback_failed";
+export interface ApplyObservedChangesParams {
+    sourceRoot: string;
+    targetRoot: string;
+    changes: ObservedFileChange[];
+    afterApply?: () => Promise<void>;
+}
+export declare function applyObservedChanges(params: ApplyObservedChangesParams): Promise<void>;
+export declare function buildObservedChangesFromTransactional(baselineRoot: string, executionRoot: string, changes: TransactionalFileChange[]): Promise<ObservedFileChange[]>;