@withtruing/companion 0.0.0-stage → 0.13.0

package/dist/sandbox.js

@@ -0,0 +1,215 @@
+/**
+ * Defense-in-depth for repository reads, on top of the caller's own read-only tool restrictions.
+ * Snapshot reads are performed only in a disposable detached worktree at the exact requested
+ * commit. Failure to obtain that commit is reported explicitly; the live checkout is never used
+ * as a substitute.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { chmodSync, lstatSync, mkdtempSync, readdirSync, realpathSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { isAbsolute, join, relative } from 'node:path';
+import { managedFetchEnvironment, reportBackgroundFetch } from './managed-repo.js';
+const execFileAsync = promisify(execFile);
+const FULL_COMMIT_ID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+function chmodFilesReadOnly(dir) {
+    for (const entry of readdirSync(dir)) {
+        if (entry === '.git')
+            continue;
+        const path = join(dir, entry);
+        const stat = statSync(path);
+        if (stat.isDirectory())
+            chmodFilesReadOnly(path);
+        else
+            chmodSync(path, 0o444);
+    }
+}
+function chmodFilesWritable(dir) {
+    for (const entry of readdirSync(dir)) {
+        if (entry === '.git')
+            continue;
+        const path = join(dir, entry);
+        const stat = statSync(path);
+        if (stat.isDirectory())
+            chmodFilesWritable(path);
+        else
+            chmodSync(path, 0o644);
+    }
+}
+export function gitErrorMessage(error) {
+    const candidate = error;
+    const raw = typeof candidate.stderr === 'string' && candidate.stderr.trim()
+        ? candidate.stderr.trim()
+        : typeof candidate.message === 'string'
+            ? candidate.message.trim()
+            : String(error);
+    return raw
+        .replace(/(https?:\/\/)[^\s/@]+@/gi, '$1[redacted]@')
+        .replace(/\s+/g, ' ')
+        .slice(0, 500);
+}
+function rawGitError(error) {
+    const candidate = error;
+    return typeof candidate.stderr === 'string' && candidate.stderr.trim()
+        ? candidate.stderr
+        : typeof candidate.message === 'string' ? candidate.message : String(error);
+}
+async function cleanupWorktree(repoPath, dir) {
+    try {
+        chmodFilesWritable(dir);
+    }
+    catch {
+        // The forced Git removal or filesystem fallback may still succeed.
+    }
+    try {
+        await execFileAsync('git', ['worktree', 'remove', '--force', dir], { cwd: repoPath, windowsHide: true });
+    }
+    catch {
+        rmSync(dir, { recursive: true, force: true });
+        try {
+            await execFileAsync('git', ['worktree', 'prune'], { cwd: repoPath, windowsHide: true });
+        }
+        catch {
+            // Nothing more can be cleaned locally; the temp directory removal above is authoritative.
+        }
+    }
+}
+export async function assertSnapshotReadBoundary(worktreePath) {
+    const { stdout } = await execFileAsync('git', ['ls-files', '-z', '--stage'], { cwd: worktreePath, maxBuffer: 64 * 1024 * 1024, windowsHide: true });
+    const root = realpathSync(worktreePath);
+    for (const record of stdout.split('\0')) {
+        if (!record)
+            continue;
+        const tab = record.indexOf('\t');
+        if (tab === -1)
+            throw new Error('Malformed tracked-path record.');
+        const metadata = record.slice(0, tab);
+        const path = record.slice(tab + 1);
+        const mode = metadata.slice(0, metadata.indexOf(' '));
+        if (mode === '120000' || mode === '160000') {
+            throw new Error('Snapshot contains an external link or unbound submodule.');
+        }
+        const absolutePath = join(worktreePath, path);
+        if (lstatSync(absolutePath).isSymbolicLink()) {
+            throw new Error('Snapshot contains an external link or unbound submodule.');
+        }
+        const resolved = realpathSync(absolutePath);
+        const fromRoot = relative(root, resolved);
+        if (fromRoot === '..' || fromRoot.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) || isAbsolute(fromRoot)) {
+            throw new Error('Snapshot path escapes its captured worktree.');
+        }
+    }
+}
+function unavailable(fetchOk, reason) {
+    const normalizedReason = reason.replace(/\s+/g, ' ').trim().slice(0, 700);
+    return {
+        target: 'requested_commit',
+        obtainedBy: 'unavailable',
+        ...(fetchOk === undefined ? {} : { fetchOk }),
+        reason: normalizedReason,
+        sourceIdentity: `unavailable:${normalizedReason}`,
+        cleanup: async () => { },
+    };
+}
+/** Read HEAD from inside a worktree and reject any identity mismatch. Exported so the invariant can
+ * be exercised directly against real worktrees in the package's integration tests. */
+export async function readAndVerifyWorktreeCommit(worktreePath, requestedCommit) {
+    const { stdout } = await execFileAsync('git', ['rev-parse', '--verify', 'HEAD^{commit}'], { cwd: worktreePath, windowsHide: true });
+    const observedCommit = stdout.trim();
+    if (observedCommit !== requestedCommit) {
+        throw new Error(`Sandbox commit mismatch: requested ${requestedCommit}, read back ${observedCommit}`);
+    }
+    return observedCommit;
+}
+/** Resolve an exact full commit object locally, fetching configured remotes only when it is absent,
+ * and create a detached worktree. A missing/unobtainable commit is data, not an exception;
+ * malformed targets and identity mismatches are caller/invariant bugs and throw. */
+export async function createSandbox(repoPath, requestedCommit) {
+    if (!FULL_COMMIT_ID.test(requestedCommit)) {
+        throw new Error(`Sandbox target must be a full lowercase commit id, got ${JSON.stringify(requestedCommit)}`);
+    }
+    let resolvedCommit;
+    try {
+        const { stdout } = await execFileAsync('git', ['rev-parse', '--verify', `${requestedCommit}^{commit}`], { cwd: repoPath, windowsHide: true });
+        resolvedCommit = stdout.trim();
+    }
+    catch {
+        // The requested object may be available from a configured remote.
+    }
+    let fetchOk;
+    let fetchFailure = '';
+    if (resolvedCommit === undefined) {
+        try {
+            const { stdout: remotes } = await execFileAsync('git', ['remote'], { cwd: repoPath, windowsHide: true });
+            if (!remotes.trim()) {
+                fetchFailure = 'no configured Git remote';
+            }
+            else {
+                fetchOk = false;
+                await execFileAsync('git', ['fetch', '--all'], { cwd: repoPath, env: await managedFetchEnvironment(repoPath), windowsHide: true });
+                fetchOk = true;
+                reportBackgroundFetch(repoPath, { ok: true });
+            }
+        }
+        catch (error) {
+            fetchFailure = gitErrorMessage(error);
+            if (fetchOk === false)
+                reportBackgroundFetch(repoPath, { ok: false, stderr: rawGitError(error) });
+        }
+        try {
+            const { stdout } = await execFileAsync('git', ['rev-parse', '--verify', `${requestedCommit}^{commit}`], { cwd: repoPath, windowsHide: true });
+            resolvedCommit = stdout.trim();
+        }
+        catch (error) {
+            const fetchContext = fetchOk === true
+                ? 'fetch succeeded'
+                : fetchOk === false
+                    ? `fetch failed (${fetchFailure})`
+                    : `fetch was not attempted (${fetchFailure})`;
+            return unavailable(fetchOk, `commit ${requestedCommit} could not be resolved after ${fetchContext}: ${gitErrorMessage(error)}`);
+        }
+    }
+    if (resolvedCommit !== requestedCommit) {
+        throw new Error(`Resolved commit mismatch: requested ${requestedCommit}, resolved ${resolvedCommit}`);
+    }
+    const dir = mkdtempSync(join(tmpdir(), 'pc-companion-'));
+    try {
+        await execFileAsync('git', ['worktree', 'add', '--detach', dir, resolvedCommit], { cwd: repoPath, windowsHide: true });
+    }
+    catch (error) {
+        await cleanupWorktree(repoPath, dir);
+        return unavailable(fetchOk, `worktree creation failed for ${requestedCommit}: ${gitErrorMessage(error)}`);
+    }
+    let observedCommit;
+    try {
+        observedCommit = await readAndVerifyWorktreeCommit(dir, requestedCommit);
+    }
+    catch (error) {
+        await cleanupWorktree(repoPath, dir);
+        throw error;
+    }
+    try {
+        chmodFilesReadOnly(dir);
+    }
+    catch (error) {
+        console.warn(`  [sandbox] couldn't mark ${dir} read-only (${gitErrorMessage(error)}) — continuing anyway.`);
+    }
+    return {
+        target: 'requested_commit',
+        obtainedBy: 'sandbox_worktree',
+        path: dir,
+        resolvedCommit: observedCommit,
+        sourceIdentity: `commit:${observedCommit}`,
+        ...(fetchOk === undefined ? {} : { fetchOk }),
+        cleanup: () => cleanupWorktree(repoPath, dir),
+    };
+}
+export async function createLegacyHeadSandbox(repoPath) {
+    const { stdout } = await execFileAsync('git', ['rev-parse', '--verify', 'HEAD^{commit}'], { cwd: repoPath, windowsHide: true });
+    const headCommit = stdout.trim();
+    const sandbox = await createSandbox(repoPath, headCommit);
+    if (sandbox.obtainedBy === 'unavailable') {
+        throw new Error(`Could not create legacy local-HEAD sandbox: ${sandbox.reason}`);
+    }
+    return { ...sandbox, target: 'legacy_local_head' };
+}