gitnexus 1.6.11-rc.8 → 1.6.11

package/dist/server/git-clone.js

@@ -7,10 +7,14 @@
 import { spawn } from 'child_process';
 import path from 'path';
 import fs from 'fs/promises';
-import { isIP } from 'net';
+import os from 'node:os';
 import { logger } from '../core/logger.js';
-import { parseRepoNameFromUrl, stripUrlCredentials } from '../storage/git.js';
 import { getGlobalDir } from '../storage/repo-manager.js';
+import { sanitizeRepoName, stripUrlCredentials } from '../storage/git.js';
+import { validateGitUrl } from '../core/net/url-guard.js';
+import { assertDirectoryOwnerAndPermissions, quarantineAutoSyncPartial, } from '../core/auto-sync/path-security.js';
+import { validateAutoSyncRemoteUrl } from '../core/auto-sync/config.js';
+export { validateGitUrl };
 /**
  * Root directory for all cloned repositories. Targets must resolve inside this.
  *
@@ -35,16 +39,41 @@ export const REPO_NAME_PATTERN = /^[a-zA-Z0-9._-]+$/;
  * clone root via path traversal.
  */
 export function extractRepoName(url) {
-    const name = parseRepoNameFromUrl(url);
+    let trimmed = url.trim();
+    while (trimmed.endsWith('/'))
+        trimmed = trimmed.slice(0, -1);
+    const withoutGit = trimmed.toLowerCase().endsWith('.git') ? trimmed.slice(0, -4) : trimmed;
+    const name = withoutGit.split(/[/:]/).filter(Boolean).pop() ?? '';
     if (!name ||
         name === '.' ||
         name === '..' ||
         name === 'unknown' ||
+        name.startsWith('-') ||
         !REPO_NAME_PATTERN.test(name)) {
         throw new Error('Could not extract a valid repository name from URL');
     }
     return name;
 }
+/**
+ * Derive a clone directory name for the web `/api/analyze` boundary.
+ *
+ * The API historically accepted Azure DevOps and similar URLs whose repo
+ * segment contains spaces or other directory-unsafe characters by sanitizing
+ * the final segment. Keep that compatibility at the web boundary while leaving
+ * `extractRepoName()` strict for internal/security-sensitive callers.
+ */
+export function extractWebRepoName(url) {
+    let trimmed = url.trim();
+    while (trimmed.endsWith('/'))
+        trimmed = trimmed.slice(0, -1);
+    const withoutGit = trimmed.toLowerCase().endsWith('.git') ? trimmed.slice(0, -4) : trimmed;
+    const rawName = withoutGit.split(/[/:]/).filter(Boolean).pop() ?? '';
+    const safeName = sanitizeRepoName(rawName);
+    if (!rawName || safeName === 'unknown') {
+        throw new Error('Could not extract a valid repository name from URL');
+    }
+    return safeName;
+}
 /** Get the clone target directory for a repo name. */
 export function getCloneDir(repoName) {
     // Re-validate at the boundary even though extractRepoName already checked —
@@ -54,148 +83,6 @@ export function getCloneDir(repoName) {
     }
     return path.join(CLONE_ROOT, repoName);
 }
-// Cloud metadata hostnames that must never be reachable via user-supplied URLs
-const BLOCKED_HOSTNAMES = new Set([
-    'localhost',
-    'metadata.google.internal',
-    'metadata.azure.com',
-    'metadata.internal',
-]);
-/**
- * Validate a git URL to prevent SSRF attacks.
- * Only allows https:// and http:// schemes. Blocks private/internal addresses,
- * IPv6 private ranges, cloud metadata hostnames, and numeric IP encodings.
- */
-export function validateGitUrl(url) {
-    let parsed;
-    try {
-        parsed = new URL(url);
-    }
-    catch {
-        throw new Error('Invalid URL');
-    }
-    if (!['https:', 'http:'].includes(parsed.protocol)) {
-        throw new Error('Only https:// and http:// git URLs are allowed');
-    }
-    const host = parsed.hostname.toLowerCase();
-    // Block known dangerous hostnames (cloud metadata services)
-    if (BLOCKED_HOSTNAMES.has(host)) {
-        throw new Error('Cloning from private/internal addresses is not allowed');
-    }
-    // Strip IPv6 brackets if present (URL parser behavior varies across Node versions)
-    let normalizedHost = host;
-    if (host.startsWith('[') && host.endsWith(']')) {
-        normalizedHost = host.slice(1, -1);
-    }
-    // Check if this is an IPv6 address
-    // Use manual colon detection as fallback since isIP may return 0 for some
-    // normalized IPv6 forms (e.g. ::ffff:7f00:1)
-    const isIPv6 = isIP(normalizedHost) === 6 || normalizedHost.includes(':');
-    if (isIPv6) {
-        assertNotPrivateIPv6(normalizedHost);
-        return;
-    }
-    // Check if this is an IPv4 address (including numeric encodings)
-    if (isIP(normalizedHost) === 4) {
-        assertNotPrivateIPv4(normalizedHost);
-        return;
-    }
-    // For non-IP hostnames, check for numeric IP tricks
-    // Decimal encoding: 2130706433 = 127.0.0.1
-    // Hex encoding: 0x7f000001 = 127.0.0.1
-    if (/^\d+$/.test(host) || /^0x[0-9a-f]+$/i.test(host)) {
-        throw new Error('Cloning from private/internal addresses is not allowed');
-    }
-    // Standard IPv4 regex checks for dotted notation
-    if (/^127\./.test(host) ||
-        /^10\./.test(host) ||
-        /^172\.(1[6-9]|2\d|3[01])\./.test(host) ||
-        /^192\.168\./.test(host) ||
-        /^169\.254\./.test(host) ||
-        /^0\./.test(host) ||
-        host === '0.0.0.0' ||
-        /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./.test(host) ||
-        /^198\.1[89]\./.test(host)) {
-        throw new Error('Cloning from private/internal addresses is not allowed');
-    }
-}
-function assertNotPrivateIPv6(ip) {
-    // Expand common compressed forms for comparison
-    const lower = ip.toLowerCase();
-    // IPv6 loopback
-    if (lower === '::1' || lower === '0:0:0:0:0:0:0:1') {
-        throw new Error('Cloning from private/internal addresses is not allowed');
-    }
-    // Unspecified address
-    if (lower === '::' || lower === '0:0:0:0:0:0:0:0') {
-        throw new Error('Cloning from private/internal addresses is not allowed');
-    }
-    // IPv6 Unique Local Address (fc00::/7 = fc and fd prefixes)
-    if (lower.startsWith('fc') || lower.startsWith('fd')) {
-        throw new Error('Cloning from private/internal addresses is not allowed');
-    }
-    // IPv6 link-local (fe80::/10)
-    if (lower.startsWith('fe80') ||
-        lower.startsWith('fe8') ||
-        lower.startsWith('fe9') ||
-        lower.startsWith('fea') ||
-        lower.startsWith('feb')) {
-        throw new Error('Cloning from private/internal addresses is not allowed');
-    }
-    // IPv4-mapped IPv6 (::ffff:x.x.x.x or ::ffff:hex:hex)
-    // Node may normalize ::ffff:127.0.0.1 to ::ffff:7f00:1
-    if (lower.startsWith('::ffff:')) {
-        throw new Error('Cloning from private/internal addresses is not allowed');
-    }
-    // Also catch the expanded form: 0:0:0:0:0:ffff:
-    if (lower.includes(':ffff:')) {
-        throw new Error('Cloning from private/internal addresses is not allowed');
-    }
-    // IPv4-compatible IPv6 (RFC 4291 § 2.5.5.1, deprecated form: ::w.x.y.z).
-    // Node's URL parser collapses http://[::127.0.0.1]/ to "::7f00:1" — the IPv4
-    // is hidden in the last 32 bits without the ::ffff: marker, so the check
-    // above misses it. The form is still routable to the embedded IPv4 on most
-    // network stacks, so any address compressed to ::xxxx[:yyyy] must be blocked.
-    if (/^::[0-9a-f]{1,4}(:[0-9a-f]{1,4})?$/.test(lower)) {
-        throw new Error('Cloning from private/internal addresses is not allowed');
-    }
-    // NAT64 well-known prefix (RFC 6052 § 2.1: 64:ff9b::/96, plus the local
-    // 64:ff9b:1::/48 from RFC 8215). Maps any IPv4 address — including private
-    // ranges — into IPv6, so a host with NAT64 can reach the embedded IPv4 via
-    // e.g. 64:ff9b::7f00:1 → 127.0.0.1.
-    // The check intentionally covers the full 64:ff9b::/32 block (broader than
-    // the two cited ranges): IANA reserves it for IPv4-IPv6 translation, so
-    // blocking the whole prefix is defensively sound and prevents a narrower
-    // CIDR check from quietly re-opening the bypass for 64:ff9b:1::/48 or any
-    // future translation assignment.
-    if (lower.startsWith('64:ff9b:')) {
-        throw new Error('Cloning from private/internal addresses is not allowed');
-    }
-    // 6to4 (RFC 3056, 2002::/16). Encodes an IPv4 address in bits 17-48, so
-    // 2002:7f00:0001::1 routes to 127.0.0.1 on 6to4-capable stacks. The
-    // protocol was deprecated by RFC 7526 and the public relay anycast
-    // (192.88.99.1) has been retired, so broad-blocking the prefix has near-
-    // zero false-positive cost while closing the IPv4-embedded bypass.
-    // Teredo (2001::/32) embeds IPv4 obfuscated by XOR; precise blocking is
-    // impractical and is out of scope here.
-    if (lower.startsWith('2002:')) {
-        throw new Error('Cloning from private/internal addresses is not allowed');
-    }
-}
-function assertNotPrivateIPv4(ip) {
-    const parts = ip.split('.').map(Number);
-    const [a, b] = parts;
-    if (a === 127 ||
-        a === 10 ||
-        (a === 172 && b >= 16 && b <= 31) ||
-        (a === 192 && b === 168) ||
-        (a === 169 && b === 254) ||
-        a === 0 ||
-        (a === 100 && b >= 64 && b <= 127) ||
-        (a === 198 && (b === 18 || b === 19))) {
-        throw new Error('Cloning from private/internal addresses is not allowed');
-    }
-}
 /**
  * Build the `git clone` argument list for a given URL and target directory.
  *
@@ -263,6 +150,9 @@ export function warnIfInsecureAzureConfig() {
 export function buildCloneArgs(url, targetDir) {
     return ['clone', '--depth', '1', '--', url, targetDir];
 }
+export function buildBranchCloneArgs(url, targetDir, branch) {
+    return ['clone', '--depth', '1', '--branch', branch, '--', url, targetDir];
+}
 /**
  * Normalize a git URL into a comparable form.
  *
@@ -320,28 +210,16 @@ export function normalizeGitUrlForCompare(url) {
  * remote means for its threat model — for cloneOrPull, a missing remote
  * on an existing clone is treated as a refuse-to-pull condition.
  */
-export function getRemoteOriginUrl(cwd) {
-    return new Promise((resolve) => {
-        const proc = spawn('git', ['config', '--get', 'remote.origin.url'], {
-            cwd,
-            stdio: ['ignore', 'pipe', 'pipe'],
-            windowsHide: true,
-            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
-        });
-        let stdout = '';
-        proc.stdout.on('data', (chunk) => {
-            stdout += chunk;
-        });
-        proc.on('close', (code) => {
-            if (code === 0 && stdout.trim()) {
-                resolve(stdout.trim());
-            }
-            else {
-                resolve(null);
-            }
-        });
-        proc.on('error', () => resolve(null));
-    });
+export async function getRemoteOriginUrl(cwd, timeoutMs) {
+    try {
+        const stdout = await runGit(['config', '--get', 'remote.origin.url'], cwd, { timeoutMs });
+        return stdout.trim() || null;
+    }
+    catch (error) {
+        if (error.message.includes('timed out'))
+            throw error;
+        return null;
+    }
 }
 /**
  * Verify that an existing clone's `remote.origin.url` matches the requested
@@ -357,8 +235,8 @@ export function getRemoteOriginUrl(cwd) {
  * Exported so the comparison logic is testable in isolation against any
  * tmpdir-based fixture, without needing to populate CLONE_ROOT.
  */
-export async function assertRemoteMatchesRequestedUrl(targetDir, requestedUrl) {
-    const remoteUrl = await getRemoteOriginUrl(targetDir);
+export async function assertRemoteMatchesRequestedUrl(targetDir, requestedUrl, timeoutMs) {
+    const remoteUrl = await getRemoteOriginUrl(targetDir, timeoutMs);
     if (remoteUrl === null) {
         throw new Error(`Existing clone at ${targetDir} has no remote.origin — refusing to pull`);
     }
@@ -400,37 +278,179 @@ export async function cloneOrPull(url, targetDir, onProgress, options) {
     // subprocess sink. The same `safeTarget` is used for every downstream
     // path operation — no reassignment that the analyzer could lose track of.
     //
-    // Limitation: this is a lexical containment check, not a realpath check.
-    // If an attacker can place a symlink under CLONE_ROOT pointing outside it,
-    // the lexical check passes but the clone lands at the symlink target. That
-    // requires pre-existing local write access to CLONE_ROOT, so the threat
-    // model considers it out of scope; CodeQL js/path-injection accepts the
-    // lexical form. Tracked as a follow-up if defense-in-depth is needed.
+    // The lexical check runs before filesystem creation; realpath and symlink
+    // checks below run before pull/clone and again after clone completes.
+    const cloneRoot = path.resolve(options?.allowedCloneRoot ?? CLONE_ROOT);
+    const expectedRepoName = options?.expectedRepoName;
+    if (expectedRepoName !== undefined && expectedRepoName !== extractRepoName(url)) {
+        throw new Error(`Clone target repo name ${expectedRepoName} does not match requested URL`);
+    }
     const safeTarget = path.resolve(targetDir);
-    const rel = path.relative(CLONE_ROOT, safeTarget);
+    if (expectedRepoName !== undefined && path.basename(safeTarget) !== expectedRepoName) {
+        throw new Error(`Clone target basename must match repository name ${expectedRepoName}`);
+    }
+    const rel = path.relative(cloneRoot, safeTarget);
     if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
-        throw new Error(`Clone target must be a subdirectory of ${CLONE_ROOT}`);
+        throw new Error(`Clone target must be a subdirectory of ${cloneRoot}`);
     }
     // Always validate the requested URL — the prior shape only ran this in
     // the code path where the repo was cloned. Now it runs unconditionally,
     // preventing SSRF / blocked-host bypasses even when targetDir already exists.
-    validateGitUrl(url);
+    if (options?.allowAutoSyncSsh)
+        validateAutoSyncRemoteUrl(url);
+    else
+        validateGitUrl(url);
+    await fs.mkdir(cloneRoot, { recursive: true });
+    if (options?.allowedCloneRoot) {
+        await assertDirectoryOwnerAndPermissions(cloneRoot);
+    }
+    await assertNoSymlinkPath(cloneRoot, safeTarget, Boolean(options?.allowedCloneRoot));
+    await fs.mkdir(path.dirname(safeTarget), { recursive: true });
+    await assertNoSymlinkPath(cloneRoot, safeTarget, Boolean(options?.allowedCloneRoot));
+    await assertPreRealpathContainment(cloneRoot, safeTarget);
     const exists = await fs.access(path.join(safeTarget, '.git')).then(() => true, () => false);
+    const targetExists = await fs.access(safeTarget).then(() => true, () => false);
     if (exists) {
+        if (options?.allowedCloneRoot) {
+            await assertNoSymlinkPath(cloneRoot, path.join(safeTarget, '.git'), true);
+        }
+        await assertPostRealpathContainment(cloneRoot, safeTarget);
         // Confirm the existing clone is actually the same repository the caller
         // requested. Without this check, a pull would silently succeed against
         // whatever remote the dir was originally cloned from.
-        await assertRemoteMatchesRequestedUrl(safeTarget, url);
+        await assertRemoteMatchesRequestedUrl(safeTarget, url, options?.timeoutMs);
         onProgress?.({ phase: 'pulling', message: 'Pulling latest changes...' });
-        await runGit(['pull', '--ff-only'], safeTarget, { token: options?.token, url });
+        const runGitImpl = options?.runGitForTest ?? runGit;
+        if (options?.branch) {
+            if (!options.overwriteLocalChanges) {
+                const status = await runGitImpl(['status', '--porcelain'], safeTarget, {
+                    token: options?.token,
+                    url,
+                    timeoutMs: options?.timeoutMs,
+                });
+                if (status.trim()) {
+                    throw new Error(`Refusing to update ${safeTarget}: local changes detected. Set overwrite_local_changes: true to overwrite them.`);
+                }
+            }
+            await runGitImpl([
+                'fetch',
+                '--depth',
+                '1',
+                'origin',
+                `refs/heads/${options.branch}:refs/remotes/origin/${options.branch}`,
+            ], safeTarget, {
+                token: options?.token,
+                url,
+                timeoutMs: options?.timeoutMs,
+            });
+            await runGitImpl([
+                'checkout',
+                ...(options.overwriteLocalChanges ? ['--force'] : []),
+                '-B',
+                options.branch,
+                `origin/${options.branch}`,
+            ], safeTarget, {
+                token: options?.token,
+                url,
+                timeoutMs: options?.timeoutMs,
+            });
+            if (options.overwriteLocalChanges) {
+                // `checkout --force` rewrites tracked files only, so untracked sources
+                // left by an operator or an earlier branch survive and then get indexed
+                // as if they were part of the remote commit. Deliberately no `-x`/`-X`:
+                // ignored paths must survive, and `-e /.gitnexus` is belt-and-braces
+                // because `.git/info/exclude` is skipped on a read-only storage mount
+                // and a freshly cloned repo may not have been analyzed yet at all.
+                await runGitImpl(['clean', '--force', '-d', '-e', '/.gitnexus'], safeTarget, {
+                    token: options?.token,
+                    url,
+                    timeoutMs: options?.timeoutMs,
+                });
+            }
+        }
+        else {
+            await runGitImpl(['pull', '--ff-only'], safeTarget, {
+                token: options?.token,
+                url,
+                timeoutMs: options?.timeoutMs,
+            });
+        }
     }
     else {
-        await fs.mkdir(path.dirname(safeTarget), { recursive: true });
+        if (targetExists && (await fs.readdir(safeTarget)).length > 0) {
+            throw new Error(`Clone target already exists but is not a git repository: ${safeTarget}`);
+        }
         onProgress?.({ phase: 'cloning', message: `Cloning ${url}...` });
-        await runGit(buildCloneArgs(url, safeTarget), undefined, { token: options?.token, url });
+        try {
+            const runGitImpl = options?.runGitForTest ?? runGit;
+            const cloneArgs = options?.branch
+                ? buildBranchCloneArgs(url, safeTarget, options.branch)
+                : buildCloneArgs(url, safeTarget);
+            await runGitImpl(cloneArgs, undefined, {
+                token: options?.token,
+                url,
+                timeoutMs: options?.timeoutMs,
+            });
+            await assertPostRealpathContainment(cloneRoot, safeTarget);
+        }
+        catch (err) {
+            if (options?.quarantineRoot) {
+                const partialExists = await fs.access(safeTarget).then(() => true, () => false);
+                if (partialExists) {
+                    try {
+                        await quarantineAutoSyncPartial(safeTarget, options.quarantineRoot);
+                    }
+                    catch (quarantineError) {
+                        throw new AggregateError([err, quarantineError], `Clone failed and partial checkout could not be quarantined: ${safeTarget}`);
+                    }
+                }
+            }
+            throw err;
+        }
     }
     return safeTarget;
 }
+async function assertPreRealpathContainment(root, target) {
+    const realRoot = await fs.realpath(root);
+    const realParent = await fs.realpath(path.dirname(target));
+    const parentRel = path.relative(realRoot, realParent);
+    if (parentRel.startsWith('..') || path.isAbsolute(parentRel)) {
+        throw new Error(`Clone target parent must resolve inside ${root}`);
+    }
+}
+async function assertPostRealpathContainment(root, target) {
+    const realRoot = await fs.realpath(root);
+    const realTarget = await fs.realpath(target);
+    const rel = path.relative(realRoot, realTarget);
+    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+        throw new Error(`Clone target must resolve inside ${root}`);
+    }
+}
+async function assertNoSymlinkPath(root, target, verifyOwnership = false) {
+    const resolvedRoot = path.resolve(root);
+    const resolvedTarget = path.resolve(target);
+    const relativeTarget = path.relative(resolvedRoot, resolvedTarget);
+    if (relativeTarget.startsWith('..') || path.isAbsolute(relativeTarget))
+        return;
+    let current = resolvedRoot;
+    for (const segment of relativeTarget.split(path.sep).filter(Boolean)) {
+        current = path.join(current, segment);
+        let stat;
+        try {
+            stat = await fs.lstat(current);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                break;
+            throw err;
+        }
+        if (stat.isSymbolicLink()) {
+            throw new Error(`Refusing symlink in clone target path: ${current}`);
+        }
+        if (verifyOwnership)
+            await assertDirectoryOwnerAndPermissions(current);
+    }
+}
 /**
  * Hosts the per-request GitHub PAT may be sent to. Exported so the
  * /api/analyze boundary check and this injection-site check share one
@@ -527,11 +547,10 @@ function warnIfCleartextCredential(url) {
     }
 }
 /**
- * Build the spawn env for `git`. Suppresses credential prompts and, when a
- * credential resolves (see resolveGitCredential), injects a single
- * host-scoped Authorization header via the `GIT_CONFIG_*` env protocol
- * (git ≥2.31) so credentials never appear in argv or the URL. Appends after
- * any existing `GIT_CONFIG_COUNT` rather than overwriting it. Exported for
+ * Build the spawn env for managed `git` commands. Suppresses credential
+ * prompts, disables repository hooks, and injects at most one host-scoped
+ * Authorization header via the `GIT_CONFIG_*` env protocol (git ≥2.31).
+ * Managed settings append after any existing GIT_CONFIG_COUNT. Exported for
  * unit tests.
  */
 export function buildGitEnv(baseEnv, options) {
@@ -550,18 +569,20 @@ export function buildGitEnv(baseEnv, options) {
         GIT_TRACE_PACKET: undefined,
         GIT_CURL_VERBOSE: undefined,
     };
+    const existing = Number.parseInt(env.GIT_CONFIG_COUNT ?? '', 10);
+    let next = Number.isInteger(existing) && existing > 0 ? existing : 0;
+    env[`GIT_CONFIG_KEY_${next}`] = 'core.hooksPath';
+    env[`GIT_CONFIG_VALUE_${next}`] = os.devNull;
+    next += 1;
     const credential = resolveGitCredential(options);
     const key = options?.url ? buildExtraHeaderKey(options.url) : undefined;
     if (credential && key) {
-        // Append after any GIT_CONFIG_* the operator already set, so we never
-        // clobber their git config (e.g. an enforced http.sslVerify).
-        const existing = Number.parseInt(env.GIT_CONFIG_COUNT ?? '', 10);
-        const base = Number.isInteger(existing) && existing > 0 ? existing : 0;
-        env.GIT_CONFIG_COUNT = String(base + 1);
-        env[`GIT_CONFIG_KEY_${base}`] = key;
-        env[`GIT_CONFIG_VALUE_${base}`] = `Authorization: Basic ${credential}`;
+        env[`GIT_CONFIG_KEY_${next}`] = key;
+        env[`GIT_CONFIG_VALUE_${next}`] = `Authorization: Basic ${credential}`;
+        next += 1;
         warnIfCleartextCredential(options?.url);
     }
+    env.GIT_CONFIG_COUNT = String(next);
     return env;
 }
 // `options` carries the inputs the credential resolver needs: a per-request
@@ -569,30 +590,63 @@ export function buildGitEnv(baseEnv, options) {
 // host-scoped Authorization header (GitHub PAT for github.com, else the
 // server's AZURE_DEVOPS_PAT for Azure hosts) via the GIT_CONFIG_* protocol —
 // never in argv. See resolveGitCredential / buildExtraHeaderKey.
-function runGit(args, cwd, options) {
+export function runGit(args, cwd, options) {
     return new Promise((resolve, reject) => {
-        const proc = spawn('git', args, {
+        const spawnGit = options?.spawnForTest ?? spawn;
+        const proc = spawnGit('git', args, {
             cwd,
             stdio: ['ignore', 'pipe', 'pipe'],
             windowsHide: true,
             env: buildGitEnv(process.env, options),
         });
+        let stdout = '';
         let stderr = '';
+        let settled = false;
+        let timedOut = false;
+        let killTimer;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            if (killTimer)
+                clearTimeout(killTimer);
+            fn();
+        };
+        const timer = options?.timeoutMs && options.timeoutMs > 0
+            ? setTimeout(() => {
+                timedOut = true;
+                proc.kill('SIGTERM');
+                killTimer = setTimeout(() => {
+                    proc.kill('SIGKILL');
+                    finish(() => reject(new Error(`git ${args[0]} timed out after ${options.timeoutMs}ms`)));
+                }, options.timeoutKillGraceMs ?? 1_000);
+            }, options.timeoutMs)
+            : undefined;
+        proc.stdout?.on('data', (chunk) => {
+            stdout += chunk;
+        });
         proc.stderr.on('data', (chunk) => {
             stderr += chunk;
         });
         proc.on('close', (code) => {
+            if (timedOut) {
+                finish(() => reject(new Error(`git ${args[0]} timed out after ${options?.timeoutMs}ms`)));
+                return;
+            }
             if (code === 0)
-                resolve();
+                finish(() => resolve(stdout));
             else {
                 // Log full stderr internally but don't expose it to API callers (SSRF mitigation)
                 if (stderr.trim())
                     logger.error(`git ${args[0]} stderr: ${stderr.trim()}`);
-                reject(new Error(`git ${args[0]} failed (exit code ${code})`));
+                finish(() => reject(new Error(`git ${args[0]} failed (exit code ${code})`)));
             }
         });
         proc.on('error', (err) => {
-            reject(new Error(`Failed to spawn git: ${err.message}`));
+            finish(() => reject(new Error(`Failed to spawn git: ${err.message}`)));
         });
     });
 }
+export const runGitForTest = runGit;

package/dist/server/grep-params.d.ts

@@ -0,0 +1,18 @@
+/** Hard cap on pattern length — unchanged from the literal-only era. */
+export declare const GREP_PATTERN_MAX_LENGTH = 200;
+/** Wall-clock budget for one /api/grep call; parent terminate()s the scan worker. */
+export declare const GREP_TIME_BUDGET_MS = 5000;
+export declare const GREP_DEFAULT_LIMIT = 50;
+export declare const GREP_MAX_LIMIT = 200;
+export interface ParsedGrepQuery {
+    regex: RegExp;
+    /** Lowercased path substring; '' disables path filtering. */
+    fileFilter: string;
+    limit: number;
+}
+/**
+ * Parse /api/grep query parameters into a ready-to-use regex + filters.
+ * Throws BadRequestError (mapped to HTTP 400 by statusFromError) on
+ * missing/over-long patterns or invalid regex syntax.
+ */
+export declare function parseGrepQuery(query: Record<string, unknown>): ParsedGrepQuery;