gitnexus 1.6.8-rc.2 → 1.6.8-rc.21

package/dist/server/api.js

@@ -20,11 +20,15 @@ import { searchFTSFromLbug } from '../core/search/bm25-index.js';
 import { hybridSearch } from '../core/search/hybrid-search.js';
 import { LocalBackend } from '../mcp/local/local-backend.js';
 import { mountMCPEndpoints } from './mcp-http.js';
-import { fork } from 'child_process';
-import { fileURLToPath, pathToFileURL } from 'url';
+import { fileURLToPath } from 'url';
 import { JobManager } from './analyze-job.js';
 import { assertString, escapeRegExp, BadRequestError, createRouteLimiter } from './validation.js';
 import { extractRepoName, getCloneDir, cloneOrPull } from './git-clone.js';
+import { createAnalyzeUploadHandler } from './analyze-upload.js';
+import { requireLocalhostOrigin } from './middleware.js';
+import { createLaunchAnalysisWorker } from './analyze-launch.js';
+import { UPLOAD_ROOT } from './upload-paths.js';
+import { sweepStaleUploads } from './upload-sweep.js';
 import { logger, flushLoggerSync } from '../core/logger.js';
 const _require = createRequire(import.meta.url);
 const pkg = _require('../../package.json');
@@ -640,6 +644,8 @@ export const createServer = async (port, host = '127.0.0.1') => {
     await backend.init();
     const cleanupMcp = mountMCPEndpoints(app, backend);
     const jobManager = new JobManager();
+    // Backstop: remove any upload staging dirs orphaned by a previous crash.
+    void sweepStaleUploads().catch(() => { });
     // Shared repo lock — prevents concurrent analyze + embed on the same repo path,
     // which would corrupt LadybugDB (analyze calls closeLbug + initLbug while embed has queries in flight).
     const activeRepoPaths = new Set();
@@ -653,6 +659,14 @@ export const createServer = async (port, host = '127.0.0.1') => {
     const releaseRepoLock = (repoPath) => {
         activeRepoPaths.delete(repoPath);
     };
+    // Launch the analyze worker for an already-resolved repo directory. Shared by
+    // the JSON /api/analyze route and the multipart /api/analyze/upload route.
+    const launchAnalysisWorker = createLaunchAnalysisWorker({
+        jobManager,
+        backend,
+        acquireRepoLock,
+        releaseRepoLock,
+    });
     /**
      * Maximum time the hold-queue will wait for an active analysis job to complete.
      * Must stay in sync with the frontend's `fetchRepoInfo({ awaitAnalysis: true })` timeout.
@@ -867,6 +881,13 @@ export const createServer = async (port, host = '127.0.0.1') => {
                         /* clone dir may not exist */
                     }
                 }
+                // 2b. Delete the uploaded repo dir if entry.path lives under
+                // UPLOAD_ROOT. Drive this off entry.path (not a name-rederived dir) so
+                // a same-named clone is never affected.
+                const resolvedEntry = path.resolve(entry.path);
+                if (resolvedEntry === UPLOAD_ROOT || resolvedEntry.startsWith(UPLOAD_ROOT + path.sep)) {
+                    await fs.rm(resolvedEntry, { recursive: true, force: true }).catch(() => { });
+                }
                 // 3. Unregister from the global registry
                 const { unregisterRepo } = await import('../storage/repo-manager.js');
                 await unregisterRepo(entry.path);
@@ -1251,7 +1272,7 @@ export const createServer = async (port, host = '127.0.0.1') => {
     });
     // ── Analyze API ──────────────────────────────────────────────────────
     // POST /api/analyze — start a new analysis job
-    app.post('/api/analyze', createRouteLimiter({ limit: 10 }), async (req, res) => {
+    app.post('/api/analyze', createRouteLimiter({ limit: 10 }), requireLocalhostOrigin, async (req, res) => {
         try {
             const { url: repoUrl, path: repoLocalPath, force, embeddings, dropEmbeddings } = req.body;
             // Input type validation
@@ -1267,16 +1288,18 @@ export const createServer = async (port, host = '127.0.0.1') => {
                 res.status(400).json({ error: 'Provide "url" (git URL) or "path" (local path)' });
                 return;
             }
-            // Path validation: require absolute path, reject traversal (e.g. /tmp/../etc/passwd)
-            if (repoLocalPath) {
-                if (!path.isAbsolute(repoLocalPath)) {
-                    res.status(400).json({ error: '"path" must be an absolute path' });
-                    return;
-                }
-                if (path.normalize(repoLocalPath) !== path.resolve(repoLocalPath)) {
-                    res.status(400).json({ error: '"path" must not contain traversal sequences' });
-                    return;
-                }
+            // Path validation. The previous `normalize !== resolve` guard was inert
+            // (both collapse `..` identically) and only false-rejected trailing
+            // slashes, so it is dropped. Analyzing a local path the operator names
+            // is the tool's intended capability (same as the CLI); the dangerous
+            // part was cross-origin reach, which is closed by requireLocalhostOrigin
+            // on this route. We only require an absolute path here and let the
+            // analyze worker surface a clear error if it does not exist. (We do NOT
+            // realpath/stat the path in-route: that would be a user-controlled
+            // filesystem read — CodeQL js/path-injection — for no security gain.)
+            if (repoLocalPath && !path.isAbsolute(repoLocalPath)) {
+                res.status(400).json({ error: '"path" must be an absolute path' });
+                return;
             }
             const job = jobManager.createJob({ repoUrl, repoPath: repoLocalPath });
             // If job was already running (dedup), just return its id
@@ -1308,133 +1331,7 @@ export const createServer = async (port, host = '127.0.0.1') => {
                     if (!targetPath) {
                         throw new Error('No target path resolved');
                     }
-                    // Acquire shared repo lock (keyed on storagePath to match embed handler)
-                    const analyzeLockKey = getStoragePath(targetPath);
-                    const lockErr = acquireRepoLock(analyzeLockKey);
-                    if (lockErr) {
-                        jobManager.updateJob(job.id, { status: 'failed', error: lockErr });
-                        return;
-                    }
-                    jobManager.updateJob(job.id, { repoPath: targetPath, status: 'analyzing' });
-                    // ── Worker fork with auto-retry ──────────────────────────────
-                    //
-                    // Forks a child process with 8GB heap. If the worker crashes
-                    // (OOM, native addon segfault, etc.), it retries up to
-                    // MAX_WORKER_RETRIES times with exponential backoff before
-                    // marking the job as permanently failed.
-                    //
-                    // In dev mode (tsx), registers the tsx ESM hook via a file://
-                    // URL so the child can compile TypeScript on-the-fly.
-                    const MAX_WORKER_RETRIES = 2;
-                    const callerPath = fileURLToPath(import.meta.url);
-                    const isDev = callerPath.endsWith('.ts');
-                    const workerFile = isDev ? 'analyze-worker.ts' : 'analyze-worker.js';
-                    const workerPath = path.join(path.dirname(callerPath), workerFile);
-                    const tsxHookArgs = isDev
-                        ? ['--import', pathToFileURL(_require.resolve('tsx/esm')).href]
-                        : [];
-                    const forkWorker = () => {
-                        const currentJob = jobManager.getJob(job.id);
-                        if (!currentJob || currentJob.status === 'complete' || currentJob.status === 'failed')
-                            return;
-                        const child = fork(workerPath, [], {
-                            execArgv: [...tsxHookArgs, '--max-old-space-size=8192'],
-                            stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
-                        });
-                        // Capture stderr for crash diagnostics
-                        let stderrChunks = '';
-                        child.stderr?.on('data', (chunk) => {
-                            stderrChunks += chunk.toString();
-                            if (stderrChunks.length > 4096)
-                                stderrChunks = stderrChunks.slice(-4096);
-                        });
-                        child.on('message', (msg) => {
-                            if (msg.type === 'progress') {
-                                jobManager.updateJob(job.id, {
-                                    status: 'analyzing',
-                                    progress: { phase: msg.phase, percent: msg.percent, message: msg.message },
-                                });
-                            }
-                            else if (msg.type === 'complete') {
-                                releaseRepoLock(analyzeLockKey);
-                                // Reinitialize backend BEFORE marking complete — ensures the new
-                                // repo is queryable when the client receives the SSE complete event.
-                                backend
-                                    .init()
-                                    .then(() => {
-                                    jobManager.updateJob(job.id, {
-                                        status: 'complete',
-                                        repoName: msg.result.repoName,
-                                    });
-                                })
-                                    .catch((err) => {
-                                    logger.error({ err }, 'backend.init() failed after analyze:');
-                                    jobManager.updateJob(job.id, {
-                                        status: 'failed',
-                                        error: 'Server failed to reload after analysis. Try again.',
-                                    });
-                                });
-                            }
-                            else if (msg.type === 'error') {
-                                releaseRepoLock(analyzeLockKey);
-                                jobManager.updateJob(job.id, {
-                                    status: 'failed',
-                                    error: msg.message,
-                                });
-                            }
-                        });
-                        child.on('error', (err) => {
-                            releaseRepoLock(analyzeLockKey);
-                            jobManager.updateJob(job.id, {
-                                status: 'failed',
-                                error: `Worker process error: ${err.message}`,
-                            });
-                        });
-                        child.on('exit', (code) => {
-                            const j = jobManager.getJob(job.id);
-                            if (!j || j.status === 'complete' || j.status === 'failed')
-                                return;
-                            // Worker crashed — attempt retry if under the limit
-                            if (j.retryCount < MAX_WORKER_RETRIES) {
-                                j.retryCount++;
-                                const delay = 1000 * Math.pow(2, j.retryCount - 1); // 1s, 2s
-                                const lastErr = stderrChunks.trim().split('\n').pop() || '';
-                                logger.warn(`Analyze worker crashed (code ${code}), retry ${j.retryCount}/${MAX_WORKER_RETRIES} in ${delay}ms` +
-                                    (lastErr ? `: ${lastErr}` : ''));
-                                jobManager.updateJob(job.id, {
-                                    status: 'analyzing',
-                                    progress: {
-                                        phase: 'retrying',
-                                        percent: j.progress.percent,
-                                        message: `Worker crashed, retrying (${j.retryCount}/${MAX_WORKER_RETRIES})...`,
-                                    },
-                                });
-                                stderrChunks = '';
-                                setTimeout(forkWorker, delay);
-                            }
-                            else {
-                                // Exhausted retries — permanent failure
-                                releaseRepoLock(analyzeLockKey);
-                                jobManager.updateJob(job.id, {
-                                    status: 'failed',
-                                    error: `Worker crashed ${MAX_WORKER_RETRIES + 1} times (code ${code})${stderrChunks ? ': ' + stderrChunks.trim().split('\n').pop() : ''}`,
-                                });
-                            }
-                        });
-                        // Register child for cancellation + timeout tracking
-                        jobManager.registerChild(job.id, child);
-                        // Send start command to child
-                        child.send({
-                            type: 'start',
-                            repoPath: targetPath,
-                            options: {
-                                force: !!force,
-                                embeddings: !!embeddings,
-                                dropEmbeddings: !!dropEmbeddings,
-                            },
-                        });
-                    };
-                    forkWorker();
+                    launchAnalysisWorker(job, targetPath, { force, embeddings, dropEmbeddings });
                 }
                 catch (err) {
                     if (targetPath)
@@ -1456,6 +1353,15 @@ export const createServer = async (port, host = '127.0.0.1') => {
             }
         }
     });
+    // POST /api/analyze/upload — analyze a browser folder upload.
+    // Securely ingests the multipart upload into a sandbox, promotes it to a
+    // persistent dir, and analyzes it via the shared job/worker machinery.
+    // localhost-only (no cross-origin write reach) + conservative rate limit.
+    app.post('/api/analyze/upload', createRouteLimiter({ limit: 5 }), requireLocalhostOrigin, createAnalyzeUploadHandler({
+        createJob: (params) => jobManager.createJob(params),
+        launch: (job, targetPath, opts) => launchAnalysisWorker(job, targetPath, opts),
+        failJob: (jobId, error) => jobManager.updateJob(jobId, { status: 'failed', error }),
+    }));
     // GET /api/analyze/:jobId — poll job status
     app.get('/api/analyze/:jobId', (req, res) => {
         const job = jobManager.getJob(req.params.jobId);

package/dist/server/git-clone.d.ts

@@ -4,6 +4,7 @@
  * Shallow-clones repositories into ~/.gitnexus/repos/{name}/.
  * If already cloned, does git pull instead.
  */
+export declare const REPO_NAME_PATTERN: RegExp;
 /**
  * Extract the repository name from a git URL (HTTPS or SSH).
  *

package/dist/server/git-clone.js

@@ -17,7 +17,7 @@ const CLONE_ROOT = path.resolve(path.join(os.homedir(), '.gitnexus', 'repos'));
 // 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).
  *

package/dist/server/middleware.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared Express route guards (alongside createRouteLimiter in validation.ts).
+ */
+import type { Request, Response } from 'express';
+/**
+ * Restrict a route to localhost browser origins. Non-browser requests (no
+ * Origin header, e.g. curl / the CLI) pass through. This closes cross-origin
+ * reach (the allow-listed public deploy + Private Network Access) to write
+ * routes without affecting read routes.
+ */
+export declare function requireLocalhostOrigin(req: Request, res: Response, next: () => void): void;

package/dist/server/middleware.js

@@ -0,0 +1,27 @@
+/**
+ * Shared Express route guards (alongside createRouteLimiter in validation.ts).
+ */
+/**
+ * Restrict a route to localhost browser origins. Non-browser requests (no
+ * Origin header, e.g. curl / the CLI) pass through. This closes cross-origin
+ * reach (the allow-listed public deploy + Private Network Access) to write
+ * routes without affecting read routes.
+ */
+export function requireLocalhostOrigin(req, res, next) {
+    const origin = req.headers.origin;
+    if (origin === undefined) {
+        next();
+        return;
+    }
+    try {
+        const hostname = new URL(origin).hostname;
+        if (hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1') {
+            next();
+            return;
+        }
+    }
+    catch {
+        /* malformed origin → reject */
+    }
+    res.status(403).json({ error: 'This endpoint is restricted to localhost origins' });
+}

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>;

package/dist/server/upload-ingest.js

@@ -0,0 +1,276 @@
+/**
+ * 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 path from 'path';
+import fs from 'fs';
+import fsp from 'fs/promises';
+import busboy from 'busboy';
+import { UPLOAD_ROOT, STAGING_PREFIX } from './upload-paths.js';
+import { BadRequestError } from './validation.js';
+export const DEFAULT_INGEST_LIMITS = {
+    maxTotalBytes: 250 * 1024 * 1024,
+    maxFileBytes: 25 * 1024 * 1024,
+    maxFiles: 20000,
+    maxParts: 20100,
+    maxDirs: 50000,
+    maxFieldBytes: 2 * 1024 * 1024,
+};
+const MAX_PATH_DEPTH = 64;
+const MAX_PATH_LENGTH = 4096;
+/**
+ * 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 function resolveContainedDest(stageRoot, rel) {
+    if (typeof rel !== 'string' || rel.length === 0) {
+        throw new BadRequestError('Invalid upload path');
+    }
+    if (rel.length > MAX_PATH_LENGTH) {
+        throw new BadRequestError('Upload path too long');
+    }
+    // webkitRelativePath is always relative; a leading slash is absolute/hostile.
+    if (rel.startsWith('/')) {
+        throw new BadRequestError('Invalid upload path');
+    }
+    // Browsers emit forward slashes only; a NUL byte or backslash is hostile.
+    if (rel.includes('\u0000') || rel.includes('\\')) {
+        throw new BadRequestError('Invalid upload path');
+    }
+    const rawSegments = rel.split('/').filter((s) => s.length > 0);
+    if (rawSegments.length === 0 || rawSegments.length > MAX_PATH_DEPTH) {
+        throw new BadRequestError('Invalid upload path');
+    }
+    const segments = [];
+    for (const seg of rawSegments) {
+        // Normalize so NFC/NFD variants don't collide silently on case/unicode
+        // -folding filesystems (macOS/Windows).
+        const s = seg.normalize('NFC');
+        if (s === '.' || s === '..') {
+            throw new BadRequestError('Upload path must not contain traversal segments');
+        }
+        segments.push(s);
+    }
+    const dest = path.resolve(stageRoot, segments.join(path.sep));
+    // Suffix path.sep so a sibling prefix (/sandbox-evil vs /sandbox) can't pass.
+    if (dest !== stageRoot && !dest.startsWith(stageRoot + path.sep)) {
+        throw new BadRequestError('Upload path escapes the sandbox');
+    }
+    return dest;
+}
+/**
+ * Create the parent directories of `destFile` one segment at a time, asserting
+ * after each `mkdir` that the segment is a real directory (not a symlink
+ * swapped in mid-stream) still inside `stageRoot`. Counts created dirs against
+ * the inode-exhaustion cap.
+ */
+function mkdirContained(stageRoot, destFile, state) {
+    const parent = path.dirname(destFile);
+    const relParent = path.relative(stageRoot, parent);
+    if (relParent === '' || relParent === '.')
+        return;
+    const segs = relParent.split(path.sep).filter(Boolean);
+    let cur = stageRoot;
+    for (const seg of segs) {
+        cur = path.join(cur, seg);
+        let made = false;
+        try {
+            fs.mkdirSync(cur);
+            made = true;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+        }
+        const st = fs.lstatSync(cur);
+        if (st.isSymbolicLink() || !st.isDirectory()) {
+            throw new BadRequestError('Upload path escapes the sandbox');
+        }
+        if (made) {
+            state.dirCount++;
+            if (state.dirCount > state.limits.maxDirs) {
+                throw new BadRequestError('Too many directories in upload', 413);
+            }
+        }
+    }
+}
+/**
+ * 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 async function ingestUpload(req, limitsOverride, opts = {}) {
+    const limits = { ...DEFAULT_INGEST_LIMITS, ...limitsOverride };
+    const uploadRoot = opts.root ?? UPLOAD_ROOT;
+    await fsp.mkdir(uploadRoot, { recursive: true });
+    // mkdtemp creates the dir mode 0o700 (owner-only); realpath canonicalizes
+    // the root so the containment prefix check is exact.
+    const stageRoot = await fsp.realpath(await fsp.mkdtemp(path.join(uploadRoot, STAGING_PREFIX)));
+    let cleaned = false;
+    const cleanup = async () => {
+        if (cleaned)
+            return;
+        cleaned = true;
+        await fsp.rm(stageRoot, { recursive: true, force: true }).catch(() => { });
+    };
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let manifest = null;
+        let fileIndex = 0;
+        let fileCount = 0;
+        let totalBytes = 0;
+        let topLevelName = '';
+        const dirState = { dirCount: 0, limits };
+        const writePromises = [];
+        const bb = busboy({
+            headers: req.headers,
+            limits: {
+                fileSize: limits.maxFileBytes,
+                files: limits.maxFiles,
+                parts: limits.maxParts,
+                fields: 10,
+                fieldNameSize: 200,
+                fieldSize: limits.maxFieldBytes,
+                headerPairs: 2000,
+            },
+        });
+        const fail = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                req.unpipe(bb);
+            }
+            catch {
+                /* ignore */
+            }
+            try {
+                req.resume(); // drain remaining body so the socket isn't left hanging
+            }
+            catch {
+                /* ignore */
+            }
+            void cleanup().finally(() => reject(err));
+        };
+        bb.on('field', (name, val) => {
+            if (name !== 'manifest')
+                return;
+            try {
+                const parsed = JSON.parse(val);
+                if (!Array.isArray(parsed) || !parsed.every((p) => typeof p === 'string')) {
+                    return fail(new BadRequestError('Invalid manifest'));
+                }
+                manifest = parsed;
+            }
+            catch {
+                fail(new BadRequestError('Invalid manifest'));
+            }
+        });
+        bb.on('file', (_name, stream, _info) => {
+            if (settled) {
+                stream.resume();
+                return;
+            }
+            if (manifest === null) {
+                // The manifest field MUST arrive before any file part.
+                stream.resume();
+                return fail(new BadRequestError('Manifest must precede file parts'));
+            }
+            const idx = fileIndex++;
+            const rel = manifest[idx];
+            let dest;
+            try {
+                dest = resolveContainedDest(stageRoot, rel);
+                // A folder upload is exactly one top-level directory: every entry must
+                // have ≥2 segments and share the same first segment. This rejects a
+                // bare file at the root (which would make the promote target a file)
+                // and a multi-top manifest (which would silently drop all but the
+                // first folder). Validated here, before any job is created.
+                const segs = String(rel)
+                    .split('/')
+                    .filter((s) => s.length > 0);
+                const firstSeg = (segs[0] ?? '').normalize('NFC');
+                if (!topLevelName) {
+                    topLevelName = firstSeg;
+                }
+                if (segs.length < 2 || firstSeg !== topLevelName) {
+                    throw new BadRequestError('Upload must be a single folder of files');
+                }
+                mkdirContained(stageRoot, dest, dirState);
+            }
+            catch (err) {
+                stream.resume();
+                return fail(err);
+            }
+            fileCount++;
+            const ws = fs.createWriteStream(dest, { flags: 'wx' });
+            const p = new Promise((res, rej) => {
+                stream.on('data', (chunk) => {
+                    totalBytes += chunk.length;
+                    if (totalBytes > limits.maxTotalBytes) {
+                        stream.unpipe(ws);
+                        ws.destroy();
+                        rej(new BadRequestError('Upload exceeds total size limit', 413));
+                    }
+                });
+                stream.on('limit', () => {
+                    ws.destroy();
+                    rej(new BadRequestError('File exceeds size limit', 413));
+                });
+                stream.on('error', rej);
+                ws.on('error', rej);
+                ws.on('finish', () => res());
+                stream.pipe(ws);
+            });
+            writePromises.push(p);
+            p.catch(fail);
+        });
+        bb.on('filesLimit', () => fail(new BadRequestError('Too many files in upload', 413)));
+        bb.on('partsLimit', () => fail(new BadRequestError('Too many parts in upload', 413)));
+        bb.on('fieldsLimit', () => fail(new BadRequestError('Too many fields in upload')));
+        bb.on('error', (err) => fail(err instanceof Error ? err : new BadRequestError('Upload parse error')));
+        bb.on('close', () => {
+            if (settled)
+                return;
+            Promise.all(writePromises)
+                .then(() => {
+                if (settled)
+                    return;
+                if (manifest === null)
+                    return fail(new BadRequestError('Missing manifest'));
+                if (fileCount === 0)
+                    return fail(new BadRequestError('Empty upload'));
+                if (fileCount !== manifest.length) {
+                    return fail(new BadRequestError('Manifest/file count mismatch'));
+                }
+                if (!topLevelName) {
+                    return fail(new BadRequestError('Could not determine upload folder name'));
+                }
+                settled = true;
+                resolve({ stageRoot, fileCount, totalBytes, topLevelName });
+            })
+                .catch(() => {
+                /* a write rejected → fail() already invoked via p.catch */
+            });
+        });
+        req.on('aborted', () => {
+            if (!settled)
+                fail(new BadRequestError('Upload aborted'));
+        });
+        req.on('error', (err) => fail(err instanceof Error ? err : new BadRequestError('Request error')));
+        req.pipe(bb);
+    });
+}

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

@@ -0,0 +1,31 @@
+/**
+ * Upload working-directory paths.
+ *
+ * Browser folder uploads are written into ~/.gitnexus/uploads/{name}/ — a
+ * sibling of the clone root (git-clone.ts CLONE_ROOT) — so an uploaded repo
+ * persists and behaves like a cloned one (the graph UI's /api/file reads its
+ * files after analysis, and DELETE /api/repo removes it). Staging happens in
+ * an mkdtemp dir *under* UPLOAD_ROOT so the promote rename stays on one
+ * filesystem and remains atomic (a rename from os.tmpdir() could trip EXDEV —
+ * the exact Docker case this feature targets; see bridge-db.ts for the same
+ * anchored-staging pattern).
+ */
+/** Root directory for all uploaded repositories. Targets must resolve inside this. */
+export declare const UPLOAD_ROOT: string;
+/** Prefix for per-upload staging directories created under UPLOAD_ROOT. */
+export declare const STAGING_PREFIX = ".staging-";
+/**
+ * Get the upload target directory for a repo name.
+ *
+ * Re-validates at the boundary (callers may derive the name from an untrusted
+ * manifest). Rejects `.`, `..`, the `'unknown'` sentinel that sanitizeRepoName
+ * emits for un-nameable inputs, names beginning with `.` (which would collide
+ * with the `.staging-` prefix), and anything outside the safe charset.
+ */
+export declare function getUploadDir(repoName: string): string;
+/**
+ * Derive a filesystem-safe upload directory name from the manifest's
+ * top-level folder. Returns null when the name is un-nameable (so the caller
+ * rejects with 400 rather than colliding everyone on `UPLOAD_ROOT/unknown`).
+ */
+export declare function deriveUploadName(topLevelName: string): string | null;