gitnexus 1.6.8-rc.9 → 1.6.8

package/dist/server/git-clone.js

@@ -1,23 +1,32 @@
 /**
  * Git Clone Utility
  *
- * Shallow-clones repositories into ~/.gitnexus/repos/{name}/.
+ * Shallow-clones repositories into the clone root (getGlobalDir()/repos/{name}/).
  * If already cloned, does git pull instead.
  */
 import { spawn } from 'child_process';
 import path from 'path';
-import os from 'os';
 import fs from 'fs/promises';
 import { isIP } from 'net';
 import { logger } from '../core/logger.js';
 import { parseRepoNameFromUrl } from '../storage/git.js';
-/** Root directory for all cloned repositories. Targets must resolve inside this. */
-const CLONE_ROOT = path.resolve(path.join(os.homedir(), '.gitnexus', 'repos'));
+import { getGlobalDir } from '../storage/repo-manager.js';
+/**
+ * Root directory for all cloned repositories. Targets must resolve inside this.
+ *
+ * Sourced from getGlobalDir() so it honors GITNEXUS_HOME — the Docker image sets
+ * GITNEXUS_HOME=/data/gitnexus, the persistent volume that also holds the
+ * registry and indexes. Without this, clones landed in the container's
+ * ephemeral ~/.gitnexus/repos and were lost on container recreation while the
+ * registry still pointed at the dead path. Falls back to ~/.gitnexus when the
+ * env var is unset (CLI / local installs), matching the prior behavior exactly.
+ */
+const CLONE_ROOT = path.resolve(path.join(getGlobalDir(), 'repos'));
 // A valid git repository name is filesystem-safe: alphanumerics plus `. _ -`.
 // Rejecting anything else (including `..`, `/`, `\`, shell metacharacters)
 // guarantees getCloneDir(repoName) cannot escape CLONE_ROOT regardless of
 // how the caller derived repoName.
-const REPO_NAME_PATTERN = /^[a-zA-Z0-9._-]+$/;
+export const REPO_NAME_PATTERN = /^[a-zA-Z0-9._-]+$/;
 /**
  * Extract the repository name from a git URL (HTTPS or SSH).
  *
@@ -197,6 +206,60 @@ function assertNotPrivateIPv4(ip) {
  *
  * Exported so the separator placement is testable without mocking spawn.
  */
+/**
+ * Detect Azure DevOps URLs — both self-hosted (via AZURE_DEVOPS_URL env)
+ * and cloud (dev.azure.com / *.visualstudio.com).
+ *
+ * Self-hosted Azure DevOps Server instances use arbitrary hostnames
+ * (e.g. `http://tfs.corp.example/Collection/Project/_git/Repo`), so the
+ * function checks `AZURE_DEVOPS_URL` first. Cloud addresses are a
+ * hardcoded fallback so PAT injection works out-of-the-box for
+ * dev.azure.com without extra configuration.
+ */
+export function isAzureDevOpsUrl(url) {
+    try {
+        // Strip a single trailing dot: `dev.azure.com.` is a valid absolute FQDN
+        // that resolves to the same host, so it must match too.
+        const host = new URL(url).hostname.toLowerCase().replace(/\.$/, '');
+        // Self-hosted: match against the configured base URL.
+        const configuredBase = process.env.AZURE_DEVOPS_URL;
+        if (configuredBase) {
+            try {
+                const baseHost = new URL(configuredBase).hostname.toLowerCase().replace(/\.$/, '');
+                if (host === baseHost)
+                    return true;
+            }
+            catch {
+                /* invalid AZURE_DEVOPS_URL — fall through to cloud check */
+            }
+        }
+        // Cloud fallback.
+        return host === 'dev.azure.com' || host.endsWith('.visualstudio.com');
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * One-time startup warning when AZURE_DEVOPS_URL is configured over cleartext
+ * http:// — the Azure DevOps PAT would then be sent unencrypted on every
+ * clone. Self-hosted instances that only serve http are still supported (we
+ * do not refuse), but operators rarely read request-time logs, so surface it
+ * at boot too. Call once from server startup.
+ */
+export function warnIfInsecureAzureConfig() {
+    const base = process.env.AZURE_DEVOPS_URL;
+    if (!base)
+        return;
+    try {
+        if (new URL(base).protocol === 'http:') {
+            logger.warn('AZURE_DEVOPS_URL is configured over cleartext http:// — the Azure DevOps PAT will be sent unencrypted. Prefer https:// where your instance supports it.');
+        }
+    }
+    catch {
+        /* invalid AZURE_DEVOPS_URL — isAzureDevOpsUrl already tolerates this */
+    }
+}
 export function buildCloneArgs(url, targetDir) {
     return ['clone', '--depth', '1', '--', url, targetDir];
 }
@@ -327,7 +390,7 @@ export async function assertRemoteMatchesRequestedUrl(targetDir, requestedUrl) {
  *     `--` (e.g. `--upload-pack=evil`) cannot be interpreted as a git option
  *     (CodeQL js/second-order-command-line-injection).
  */
-export async function cloneOrPull(url, targetDir, onProgress) {
+export async function cloneOrPull(url, targetDir, onProgress, options) {
     // Containment barrier — inline with the canonical path.relative idiom so
     // CodeQL recognizes the sanitizer at every following filesystem and
     // subprocess sink. The same `safeTarget` is used for every downstream
@@ -355,28 +418,160 @@ export async function cloneOrPull(url, targetDir, onProgress) {
         // whatever remote the dir was originally cloned from.
         await assertRemoteMatchesRequestedUrl(safeTarget, url);
         onProgress?.({ phase: 'pulling', message: 'Pulling latest changes...' });
-        await runGit(['pull', '--ff-only'], safeTarget);
+        await runGit(['pull', '--ff-only'], safeTarget, { token: options?.token, url });
     }
     else {
         await fs.mkdir(path.dirname(safeTarget), { recursive: true });
         onProgress?.({ phase: 'cloning', message: `Cloning ${url}...` });
-        await runGit(buildCloneArgs(url, safeTarget));
+        await runGit(buildCloneArgs(url, safeTarget), undefined, { token: options?.token, url });
     }
     return safeTarget;
 }
-function runGit(args, cwd) {
+/**
+ * Hosts the per-request GitHub PAT may be sent to. Exported so the
+ * /api/analyze boundary check and this injection-site check share one
+ * allowlist (they must agree, or a token accepted by the API could be
+ * silently dropped — or worse — at injection).
+ */
+export const GITHUB_TOKEN_HOSTS = new Set(['github.com', 'www.github.com']);
+/**
+ * Resolve at most ONE git credential for a clone/pull, by server-side policy
+ * keyed on the clone host against a fixed allowlist (never a free-form user
+ * toggle):
+ *   1. a per-request GitHub PAT — only for hosts in GITHUB_TOKEN_HOSTS;
+ *   2. else the server's AZURE_DEVOPS_PAT — only for Azure DevOps hosts;
+ *   3. else none.
+ * The two host sets are disjoint, so at most one credential ever applies; the
+ * GitHub token taking precedence is deterministic for the pathological case
+ * where AZURE_DEVOPS_URL is itself configured to a github.com host. Returns
+ * the base64 of the Basic-auth `user:secret` pair, or undefined.
+ *
+ * Security note (re CodeQL js/user-controlled-bypass): the clone URL is
+ * user-controlled and selects WHICH credential applies, but it cannot
+ * redirect a credential to an arbitrary host — the host is matched against
+ * fixed server-side allowlists (GITHUB_TOKEN_HOSTS, isAzureDevOpsUrl's
+ * dev.azure.com/*.visualstudio.com/configured AZURE_DEVOPS_URL), and the
+ * emitted header is host-scoped (buildExtraHeaderKey). A URL outside the
+ * allowlists yields no credential. The selection is therefore server-policy,
+ * not a bypass the user can steer.
+ */
+function resolveGitCredential(options) {
+    const url = options?.url;
+    if (!url)
+        return undefined;
+    let host;
+    try {
+        host = new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        return undefined;
+    }
+    // 1. Per-request GitHub PAT — github.com only (mirrors the /api/analyze
+    //    host-bind so the user's token is never sent off github.com).
+    if (options.token && GITHUB_TOKEN_HOSTS.has(host)) {
+        return Buffer.from(`x-access-token:${options.token}`).toString('base64');
+    }
+    // 2. Server-configured Azure DevOps PAT — Azure hosts only.
+    const azurePat = process.env.AZURE_DEVOPS_PAT;
+    if (azurePat && isAzureDevOpsUrl(url)) {
+        return Buffer.from(`:${azurePat}`).toString('base64');
+    }
+    return undefined;
+}
+/**
+ * Build the host-scoped git config key `http.<origin+path>.extraHeader` from
+ * the raw clone URL, so the Authorization header is attached only to the
+ * intended origin (and its clone sub-requests like /info/refs), never a
+ * redirect target. Derived from the SAME raw URL git clones from — not the
+ * normalize-for-compare form, which strips `.git` and would desync the key
+ * from the wire URL and silently disable the header. Userinfo/query/fragment
+ * are dropped (not part of git's URL match) and control characters stripped
+ * (git rejects a newline in a config key outright).
+ */
+function buildExtraHeaderKey(url) {
+    let scoped;
+    try {
+        const u = new URL(url);
+        u.username = '';
+        u.password = '';
+        u.search = '';
+        u.hash = '';
+        scoped = `${u.protocol}//${u.host}${u.pathname}`;
+    }
+    catch {
+        return undefined;
+    }
+    scoped = scoped.replace(/[\r\n\0]/g, '');
+    return `http.${scoped}.extraHeader`;
+}
+/**
+ * Warn (do not block) when a credential is about to be sent over cleartext
+ * http://. Base64 is encoding, not encryption, so an on-path observer can
+ * read the PAT. We keep http:// working for self-hosted Azure DevOps Server.
+ */
+function warnIfCleartextCredential(url) {
+    if (!url)
+        return;
+    try {
+        const u = new URL(url);
+        if (u.protocol === 'http:') {
+            logger.warn(`Sending a git credential over cleartext http:// (${u.host}) — base64 is not encryption. Prefer https:// where the host supports it.`);
+        }
+    }
+    catch {
+        /* resolver already validated the 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
+ * unit tests.
+ */
+export function buildGitEnv(baseEnv, options) {
+    const env = {
+        ...baseEnv,
+        // Prevent git from prompting for credentials (hangs the process)
+        GIT_TERMINAL_PROMPT: '0',
+        // Ensure no credential helper tries to open a GUI prompt
+        GIT_ASKPASS: process.platform === 'win32' ? 'echo' : '/bin/true',
+        // Scrub git's HTTP/transport trace vars: if inherited from the parent
+        // process they dump every request header — including the injected
+        // Authorization header — to stderr, which runGit captures and logs.
+        // `undefined` makes child_process omit the key from the child env.
+        GIT_TRACE: undefined,
+        GIT_TRACE_CURL: undefined,
+        GIT_TRACE_PACKET: undefined,
+        GIT_CURL_VERBOSE: undefined,
+    };
+    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}`;
+        warnIfCleartextCredential(options?.url);
+    }
+    return env;
+}
+// `options` carries the inputs the credential resolver needs: a per-request
+// GitHub `token` and the clone `url`. buildGitEnv injects at most ONE
+// 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) {
     return new Promise((resolve, reject) => {
         const proc = spawn('git', args, {
             cwd,
             stdio: ['ignore', 'pipe', 'pipe'],
             windowsHide: true,
-            env: {
-                ...process.env,
-                // Prevent git from prompting for credentials (hangs the process)
-                GIT_TERMINAL_PROMPT: '0',
-                // Ensure no credential helper tries to open a GUI prompt
-                GIT_ASKPASS: process.platform === 'win32' ? 'echo' : '/bin/true',
-            },
+            env: buildGitEnv(process.env, options),
         });
         let stderr = '';
         proc.stderr.on('data', (chunk) => {

package/dist/server/mcp-http.d.ts

@@ -1,12 +1,11 @@
 /**
- * MCP over HTTP
+ * MCP over HTTP — route mount helper for the web-UI server.
  *
- * Mounts the GitNexus MCP server on Express using StreamableHTTP transport.
- * Each connecting client gets its own stateful session; the LocalBackend
- * is shared across all sessions (thread-safe — lazy LadybugDB per repo).
+ * Mounts the GitNexus MCP endpoint (/api/mcp) onto an existing Express
+ * application. Session management lives in mcp/http-transport.ts, preserving
+ * the established server/ → mcp/ dependency direction.
  *
- * Sessions are cleaned up on explicit close or after SESSION_TTL_MS of inactivity
- * (guards against network drops that never trigger onclose).
+ * Used by server/api.ts to wire up the full web server.
  */
 import type { Express } from 'express';
 import type { LocalBackend } from '../mcp/local/local-backend.js';

package/dist/server/mcp-http.js

@@ -1,80 +1,18 @@
 /**
- * MCP over HTTP
+ * MCP over HTTP — route mount helper for the web-UI server.
  *
- * Mounts the GitNexus MCP server on Express using StreamableHTTP transport.
- * Each connecting client gets its own stateful session; the LocalBackend
- * is shared across all sessions (thread-safe — lazy LadybugDB per repo).
+ * Mounts the GitNexus MCP endpoint (/api/mcp) onto an existing Express
+ * application. Session management lives in mcp/http-transport.ts, preserving
+ * the established server/ → mcp/ dependency direction.
  *
- * Sessions are cleaned up on explicit close or after SESSION_TTL_MS of inactivity
- * (guards against network drops that never trigger onclose).
+ * Used by server/api.ts to wire up the full web server.
  */
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { createMCPServer } from '../mcp/server.js';
-import { randomUUID } from 'crypto';
+import { createStreamableHttpHandler } from '../mcp/http-transport.js';
 import { logger } from '../core/logger.js';
-/** Idle sessions are evicted after 30 minutes */
-const SESSION_TTL_MS = 30 * 60 * 1000;
-/** Cleanup sweep runs every 5 minutes */
-const CLEANUP_INTERVAL_MS = 5 * 60 * 1000;
 export function mountMCPEndpoints(app, backend) {
-    const sessions = new Map();
-    // Periodic cleanup of idle sessions (guards against network drops)
-    const cleanupTimer = setInterval(() => {
-        const now = Date.now();
-        for (const [id, session] of sessions) {
-            if (now - session.lastActivity > SESSION_TTL_MS) {
-                try {
-                    session.server.close();
-                }
-                catch { }
-                sessions.delete(id);
-            }
-        }
-    }, CLEANUP_INTERVAL_MS);
-    if (cleanupTimer && typeof cleanupTimer === 'object' && 'unref' in cleanupTimer) {
-        cleanupTimer.unref();
-    }
-    const handleMcpRequest = async (req, res) => {
-        const sessionId = req.headers['mcp-session-id'];
-        if (sessionId && sessions.has(sessionId)) {
-            // Existing session — delegate to its transport
-            const session = sessions.get(sessionId);
-            session.lastActivity = Date.now();
-            await session.transport.handleRequest(req, res, req.body);
-        }
-        else if (sessionId) {
-            // Unknown/expired session ID — tell client to re-initialize (per MCP spec)
-            res.status(404).json({
-                jsonrpc: '2.0',
-                error: { code: -32001, message: 'Session not found. Re-initialize.' },
-                id: null,
-            });
-        }
-        else if (req.method === 'POST') {
-            // No session ID — new client initializing
-            const transport = new StreamableHTTPServerTransport({
-                sessionIdGenerator: () => randomUUID(),
-            });
-            const server = createMCPServer(backend);
-            await server.connect(transport);
-            await transport.handleRequest(req, res, req.body);
-            if (transport.sessionId) {
-                sessions.set(transport.sessionId, { server, transport, lastActivity: Date.now() });
-                transport.onclose = () => {
-                    sessions.delete(transport.sessionId);
-                };
-            }
-        }
-        else {
-            res.status(400).json({
-                jsonrpc: '2.0',
-                error: { code: -32000, message: 'No valid session. Send a POST to initialize.' },
-                id: null,
-            });
-        }
-    };
+    const { handler, cleanup } = createStreamableHttpHandler(backend);
     app.all('/api/mcp', (req, res) => {
-        void handleMcpRequest(req, res).catch((err) => {
+        void handler(req, res).catch((err) => {
             logger.error({ err }, 'MCP HTTP request failed:');
             if (res.headersSent)
                 return;
@@ -85,17 +23,6 @@ export function mountMCPEndpoints(app, backend) {
             });
         });
     });
-    const cleanup = async () => {
-        clearInterval(cleanupTimer);
-        const closers = [...sessions.values()].map(async (session) => {
-            try {
-                await Promise.resolve(session.server.close());
-            }
-            catch { }
-        });
-        sessions.clear();
-        await Promise.allSettled(closers);
-    };
-    console.log('MCP HTTP endpoints mounted at /api/mcp');
+    logger.info('MCP HTTP endpoints mounted at /api/mcp');
     return cleanup;
 }

package/dist/server/middleware.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Shared Express route guards (alongside createRouteLimiter in validation.ts).
+ */
+import type { Request, Response } from 'express';
+/**
+ * Canonicalize a bound-host string into the form a browser `Origin` hostname
+ * takes after WHATWG URL parsing, so the same-host comparison in
+ * {@link createLocalhostOriginGuard} can use a plain `===`.
+ *
+ * Returns `undefined` when the host carries no single comparable identity:
+ *   - empty / not provided
+ *   - a wildcard bind (`0.0.0.0`, `::`, expanded `0:0:0:0:0:0:0:0`) — the server
+ *     listens on every interface and has no one address a browser Origin maps to,
+ *     so writes stay loopback-only (we deliberately do NOT trust the whole subnet)
+ *   - an unparseable value
+ *
+ * Otherwise returns `new URL(...).hostname` (lowercased, IPv6 bracketed and
+ * compressed) — provably identical to how the request Origin is parsed below.
+ * Hand-rolling lowercase + bracketing is insufficient: it fails to compress
+ * non-canonical IPv6 forms (e.g. `fe80:0:0:0:0:0:0:1`, `::ffff:127.0.0.1`).
+ */
+export declare function normalizeBoundHost(boundHost?: string): string | undefined;
+/**
+ * Restrict a route to same-host browser origins. Allows:
+ *   - loopback (`localhost`, `127.0.0.1`, `[::1]`)
+ *   - the server's own bound host (when non-loopback, e.g. a LAN IP)
+ *
+ * Non-browser requests (no Origin header, e.g. curl / the CLI) pass through.
+ * This closes cross-origin reach to write routes without affecting read routes.
+ *
+ * @param boundHost - The hostname/IP the server is listening on (from
+ *   `createServer`'s `host` parameter). When `undefined`, `'localhost'`, or a
+ *   wildcard (`0.0.0.0`/`::`), only loopback origins are admitted.
+ */
+export declare function createLocalhostOriginGuard(boundHost?: string): (req: Request, res: Response, next: () => void) => void;
+/**
+ * Default guard that only allows loopback origins. For use in tests or when
+ * the bound host is not available.
+ */
+export declare const requireLocalhostOrigin: (req: Request, res: Response, next: () => void) => void;

package/dist/server/middleware.js

@@ -0,0 +1,92 @@
+/**
+ * Shared Express route guards (alongside createRouteLimiter in validation.ts).
+ */
+/**
+ * Canonicalize a bound-host string into the form a browser `Origin` hostname
+ * takes after WHATWG URL parsing, so the same-host comparison in
+ * {@link createLocalhostOriginGuard} can use a plain `===`.
+ *
+ * Returns `undefined` when the host carries no single comparable identity:
+ *   - empty / not provided
+ *   - a wildcard bind (`0.0.0.0`, `::`, expanded `0:0:0:0:0:0:0:0`) — the server
+ *     listens on every interface and has no one address a browser Origin maps to,
+ *     so writes stay loopback-only (we deliberately do NOT trust the whole subnet)
+ *   - an unparseable value
+ *
+ * Otherwise returns `new URL(...).hostname` (lowercased, IPv6 bracketed and
+ * compressed) — provably identical to how the request Origin is parsed below.
+ * Hand-rolling lowercase + bracketing is insufficient: it fails to compress
+ * non-canonical IPv6 forms (e.g. `fe80:0:0:0:0:0:0:1`, `::ffff:127.0.0.1`).
+ */
+export function normalizeBoundHost(boundHost) {
+    if (!boundHost)
+        return undefined;
+    // Bracket a bare IPv6 literal so `new URL` can parse it as a host.
+    const candidate = boundHost.includes(':') && !boundHost.startsWith('[') ? `[${boundHost}]` : boundHost;
+    let hostname;
+    try {
+        hostname = new URL(`http://${candidate}`).hostname;
+    }
+    catch {
+        return undefined;
+    }
+    // Wildcard binds have no single host identity → keep writes loopback-only.
+    if (hostname === '' || hostname === '0.0.0.0' || hostname === '[::]') {
+        return undefined;
+    }
+    return hostname;
+}
+/**
+ * Restrict a route to same-host browser origins. Allows:
+ *   - loopback (`localhost`, `127.0.0.1`, `[::1]`)
+ *   - the server's own bound host (when non-loopback, e.g. a LAN IP)
+ *
+ * Non-browser requests (no Origin header, e.g. curl / the CLI) pass through.
+ * This closes cross-origin reach to write routes without affecting read routes.
+ *
+ * @param boundHost - The hostname/IP the server is listening on (from
+ *   `createServer`'s `host` parameter). When `undefined`, `'localhost'`, or a
+ *   wildcard (`0.0.0.0`/`::`), only loopback origins are admitted.
+ */
+export function createLocalhostOriginGuard(boundHost) {
+    const normalizedBoundHost = normalizeBoundHost(boundHost);
+    return function requireLocalhostOrigin(req, res, next) {
+        const origin = req.headers.origin;
+        if (origin === undefined) {
+            next();
+            return;
+        }
+        try {
+            const parsed = new URL(origin);
+            const hostname = parsed.hostname;
+            const protocol = parsed.protocol;
+            if (protocol !== 'http:' && protocol !== 'https:') {
+                throw new Error('Unsupported origin protocol');
+            }
+            if (hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]') {
+                next();
+                return;
+            }
+            // Allow origin matching the server's own bound host (same-host check).
+            // `normalizedBoundHost` is canonicalized to the WHATWG form `hostname`
+            // already carries; it is `undefined` for wildcard/no binds (loopback-only).
+            // This covers the case where the operator runs `gitnexus serve --host <LAN-IP>`.
+            if (normalizedBoundHost && hostname === normalizedBoundHost) {
+                next();
+                return;
+            }
+        }
+        catch {
+            /* malformed origin → reject */
+        }
+        res.status(403).json({
+            error: 'This endpoint is restricted to same-host origins',
+            code: 'origin_not_allowed',
+        });
+    };
+}
+/**
+ * Default guard that only allows loopback origins. For use in tests or when
+ * the bound host is not available.
+ */
+export const requireLocalhostOrigin = createLocalhostOriginGuard();

package/dist/server/private-ip.d.ts

@@ -0,0 +1 @@
+export declare const isRfc1918PrivateIpv4: (hostname: string) => boolean;

package/dist/server/private-ip.js

@@ -0,0 +1,15 @@
+const parseIpv4Octets = (hostname) => {
+    if (!/^\d{1,3}(\.\d{1,3}){3}$/.test(hostname))
+        return null;
+    const octets = hostname.split('.').map(Number);
+    if (octets.some((o) => !Number.isInteger(o) || o < 0 || o > 255))
+        return null;
+    return octets;
+};
+export const isRfc1918PrivateIpv4 = (hostname) => {
+    const octets = parseIpv4Octets(hostname);
+    if (octets === null)
+        return false;
+    const [a, b] = octets;
+    return a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168);
+};

package/dist/server/upload-ingest.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Secure ingestion of a browser folder upload (multipart/form-data).
+ *
+ * Replaces the path-injection-prone GET /api/fs/list directory listing. The
+ * client streams the selected files plus a JSON `manifest` of their
+ * webkitRelativePaths; we write each into an mkdtemp staging dir under
+ * UPLOAD_ROOT with PROVABLE containment (resolve-then-contain), hard resource
+ * caps, and guaranteed cleanup on every failure/abort path. No client value
+ * ever reaches a filesystem READ — the server only writes into a sandbox it
+ * created, then hands that sandbox to the analysis pipeline.
+ *
+ * Security references: CodeQL js/path-injection (resolve + startsWith(root+sep)),
+ * OWASP File Upload / Path Traversal.
+ */
+import type { IncomingMessage } from 'http';
+export interface IngestLimits {
+    /** Aggregate bytes across all files (busboy has no aggregate limit). */
+    maxTotalBytes: number;
+    /** Per-file byte cap. */
+    maxFileBytes: number;
+    /** Maximum number of files. */
+    maxFiles: number;
+    /** Maximum multipart parts (files + fields). */
+    maxParts: number;
+    /** Maximum directories created (inode-exhaustion guard). */
+    maxDirs: number;
+    /** Maximum size of the manifest field. */
+    maxFieldBytes: number;
+}
+export declare const DEFAULT_INGEST_LIMITS: IngestLimits;
+export interface IngestResult {
+    /** Absolute path to the populated staging directory (realpath-canonical). */
+    stageRoot: string;
+    fileCount: number;
+    totalBytes: number;
+    /** First path segment shared by the uploaded tree (the picked folder). */
+    topLevelName: string;
+}
+/**
+ * Resolve a client-provided relative path to an absolute destination PROVABLY
+ * contained within `stageRoot`. Throws BadRequestError on any unsafe input.
+ * This is the load-bearing path-traversal-on-write control; keep it pure and
+ * unit-tested.
+ */
+export declare function resolveContainedDest(stageRoot: string, rel: unknown): string;
+export interface IngestOptions {
+    /** Override the staging parent dir (defaults to UPLOAD_ROOT; for tests). */
+    root?: string;
+}
+/**
+ * Parse and securely write a multipart folder upload into a fresh staging
+ * directory under UPLOAD_ROOT. Resolves with the populated staging dir, or
+ * rejects with a BadRequestError (status 400/413) after removing the staging
+ * dir. The caller owns promotion + cleanup of the returned `stageRoot`.
+ */
+export declare function ingestUpload(req: IncomingMessage, limitsOverride?: Partial<IngestLimits>, opts?: IngestOptions): Promise<IngestResult>;