parasor 0.1.0

package/server/fs/service.js

@@ -0,0 +1,306 @@
+import { Buffer } from "node:buffer";
+import { existsSync, constants as fsConstants, readFileSync, realpathSync, } from "node:fs";
+import { cp as fsCp, mkdir as fsMkdir, open as fsOpen, readFile as fsReadFile, realpath as fsRealpath, writeFile as fsWriteFile, readdir, stat, } from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
+import ignore from "ignore";
+const HARD_EXCLUDES = new Set([".git", ".DS_Store", "Thumbs.db"]);
+const BUILTIN_IGNORES = [
+    "node_modules",
+    "dist",
+    "build",
+    ".next",
+    ".nuxt",
+    ".venv",
+    "venv",
+    "__pycache__",
+    ".pytest_cache",
+    "target",
+    ".turbo",
+];
+const MAX_FILE_SIZE = 1024 * 1024; // 1 MB
+export class PathTraversalError extends Error {
+    constructor() {
+        super("Path traversal denied");
+        this.name = "PathTraversalError";
+    }
+}
+export class CopySourceNotFoundError extends Error {
+    constructor() {
+        super("Copy source not found");
+        this.name = "CopySourceNotFoundError";
+    }
+}
+export class CopyDestinationExistsError extends Error {
+    constructor() {
+        super("Copy destination already exists");
+        this.name = "CopyDestinationExistsError";
+    }
+}
+export class FilesystemService {
+    projectRoot;
+    ignoreInstance;
+    constructor(projectRoot) {
+        const resolved = resolve(projectRoot);
+        try {
+            this.projectRoot = realpathSync(resolved);
+        }
+        catch {
+            this.projectRoot = resolved;
+        }
+        this.ignoreInstance = this.loadIgnore();
+    }
+    async listDir(relPath) {
+        const absPath = this.resolve(relPath);
+        const ig = this.ignoreInstance;
+        const entries = [];
+        const dirEntries = await readdir(absPath, { withFileTypes: true });
+        for (const dirent of dirEntries) {
+            if (HARD_EXCLUDES.has(dirent.name))
+                continue;
+            const entryRelPath = relative(this.projectRoot, join(absPath, dirent.name));
+            const isDir = dirent.isDirectory();
+            const isGitignored = this.isIgnoredWith(ig, entryRelPath, isDir);
+            const isHidden = dirent.name.startsWith(".");
+            entries.push({
+                name: dirent.name,
+                path: entryRelPath,
+                type: isDir ? "directory" : "file",
+                ...(isGitignored && { isGitignored: true }),
+                ...(isHidden && { isHidden: true }),
+            });
+        }
+        entries.sort((a, b) => {
+            if (a.type !== b.type)
+                return a.type === "directory" ? -1 : 1;
+            return a.name.localeCompare(b.name);
+        });
+        return entries;
+    }
+    async readFile(relPath, maxBytes) {
+        const absPath = this.resolve(relPath);
+        const limit = maxBytes ?? MAX_FILE_SIZE;
+        try {
+            const stats = await stat(absPath);
+            if (stats.size > limit) {
+                throw new Error("File too large");
+            }
+            const content = await fsReadFile(absPath, "utf-8");
+            return content;
+        }
+        catch (err) {
+            if (err instanceof Error && err.message === "File too large")
+                throw err;
+            if (isNodeError(err) && err.code === "ENOENT")
+                return null;
+            throw err;
+        }
+    }
+    /**
+     * Stat a single file, returning `null` when missing. Wraps node `stat()`
+     * to surface `PathTraversalError` consistently and never leak ENOENT
+     * details to the route layer.
+     */
+    async statFile(relPath) {
+        const absPath = this.resolve(relPath);
+        try {
+            return await stat(absPath);
+        }
+        catch (err) {
+            if (isNodeError(err) && err.code === "ENOENT")
+                return null;
+            throw err;
+        }
+    }
+    /**
+     * Open a regular file inside the project root for inline media serving.
+     * The leaf is opened with `O_NOFOLLOW` so a symlink swapped in between
+     * the parent-directory resolve and this open cannot redirect to a target
+     * outside the project tree. The returned `FileHandle` is the single
+     * authoritative reference: callers do `fstat`, magic-number sniff via
+     * `read`, and stream creation through the same handle so size limits and
+     * content-type detection apply to the exact bytes about to be served.
+     * The caller MUST `close()` the handle (or pass it to `createReadStream`
+     * with `autoClose: true`).
+     *
+     * `O_NONBLOCK` keeps `open()` from blocking when the path happens to be a
+     * FIFO/socket/character device (a `*.mp4` FIFO in a cloned repo would
+     * otherwise pin a libuv worker until a writer connects); the post-open
+     * `isFile()` check then rejects everything that isn't a regular file.
+     *
+     * `O_NOFOLLOW` only protects the leaf -- an attacker with FS write access
+     * can still swap a parent directory to a symlink between `resolve()`'s
+     * realpath check and this `open()`. We close that gap by re-resolving the
+     * path *after* open and comparing the canonical result's inode to the
+     * fd's inode. A mid-open swap leaves the fd bound to a file outside the
+     * project tree while the second realpath resolves to the legitimate
+     * (or missing) in-tree entry, so the inodes diverge and we reject.
+     *
+     * Returns `null` for ENOENT so missing files surface as 404 rather than
+     * leaking the absolute path. ELOOP (the leaf was a symlink) raises a
+     * `PathTraversalError` because following symlinks at the leaf is exactly
+     * what we are refusing.
+     */
+    async openInlineFile(relPath) {
+        const absPath = this.resolve(relPath);
+        const NONBLOCK = fsConstants.O_NONBLOCK ?? 0;
+        let handle;
+        try {
+            handle = await fsOpen(absPath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | NONBLOCK);
+        }
+        catch (err) {
+            if (isNodeError(err) && err.code === "ENOENT")
+                return null;
+            if (isNodeError(err) && err.code === "ELOOP") {
+                throw new PathTraversalError();
+            }
+            throw err;
+        }
+        try {
+            const stats = await handle.stat();
+            if (!stats.isFile()) {
+                await handle.close();
+                return null;
+            }
+            let real;
+            try {
+                real = await fsRealpath(absPath);
+            }
+            catch (err) {
+                if (isNodeError(err) && err.code === "ENOENT") {
+                    await handle.close();
+                    return null;
+                }
+                throw err;
+            }
+            if (real !== this.projectRoot &&
+                !real.startsWith(this.projectRoot + sep)) {
+                await handle.close();
+                throw new PathTraversalError();
+            }
+            const pathStats = await stat(real);
+            if (pathStats.ino !== stats.ino || pathStats.dev !== stats.dev) {
+                await handle.close();
+                throw new PathTraversalError();
+            }
+            return { handle, stats };
+        }
+        catch (err) {
+            await handle.close().catch(() => { });
+            throw err;
+        }
+    }
+    /**
+     * Build a read stream from an already-open `FileHandle`, optionally clamped
+     * to a byte range. Uses `FileHandle.createReadStream` with `autoClose: true`
+     * so stream ownership of the handle is explicit -- closing the stream
+     * releases the underlying fd through the FileHandle, avoiding the
+     * double-close hazard of passing the raw `handle.fd` to `createReadStream`
+     * (where the FileHandle's own GC finalizer could close an fd the stream
+     * already returned to the OS). Pairs with `openInlineFile` -- callers must
+     * not reuse the handle after this call returns.
+     */
+    createStreamFromHandle(handle, size, range) {
+        let start = 0;
+        let end = size === 0 ? 0 : size - 1;
+        if (range) {
+            start = range.start;
+            end = range.end;
+        }
+        const stream = size === 0
+            ? handle.createReadStream({ autoClose: true })
+            : handle.createReadStream({ autoClose: true, start, end });
+        return { stream, start, end };
+    }
+    async writeFile(relPath, content) {
+        const byteLength = Buffer.byteLength(content, "utf-8");
+        if (byteLength > MAX_FILE_SIZE) {
+            throw new Error("File too large");
+        }
+        const absPath = this.resolve(relPath);
+        await fsWriteFile(absPath, content, "utf-8");
+    }
+    async mkdir(relPath) {
+        const absPath = this.resolve(relPath);
+        await fsMkdir(absPath, { recursive: true });
+    }
+    /**
+     * Recursive copy of a file or directory inside the project root. Both
+     * sides are routed through `resolve()` so symlink-escape and `..` traversal
+     * remain blocked. Refuses to overwrite an existing destination -- callers
+     * pick a unique name (Finder-style "<n> copy", "<n> copy 2") before invoking.
+     */
+    async cp(srcRelPath, destRelPath) {
+        const srcAbs = this.resolve(srcRelPath);
+        const destAbs = this.resolve(destRelPath);
+        try {
+            await stat(srcAbs);
+        }
+        catch (err) {
+            if (isNodeError(err) && err.code === "ENOENT") {
+                throw new CopySourceNotFoundError();
+            }
+            throw err;
+        }
+        if (existsSync(destAbs)) {
+            throw new CopyDestinationExistsError();
+        }
+        await fsCp(srcAbs, destAbs, {
+            recursive: true,
+            errorOnExist: true,
+            force: false,
+        });
+    }
+    reloadIgnore() {
+        this.ignoreInstance = this.loadIgnore();
+    }
+    isIgnored(relPath, isDir) {
+        if (!relPath || relPath === "." || relPath === "")
+            return false;
+        return this.isIgnoredWith(this.ignoreInstance, relPath, isDir);
+    }
+    resolve(relPath) {
+        // Normalize resolved path against canonical projectRoot
+        const resolved = resolve(this.projectRoot, relPath);
+        if (resolved !== this.projectRoot &&
+            !resolved.startsWith(this.projectRoot + sep)) {
+            throw new PathTraversalError();
+        }
+        // Symlink check: resolve real path if it exists
+        try {
+            const real = realpathSync(resolved);
+            if (real !== this.projectRoot &&
+                !real.startsWith(this.projectRoot + sep)) {
+                throw new PathTraversalError();
+            }
+        }
+        catch (err) {
+            if (err instanceof PathTraversalError)
+                throw err;
+            // ENOENT or other -- path doesn't exist yet, allow (ENOENT handled in callers)
+        }
+        return resolved;
+    }
+    loadIgnore() {
+        const ig = ignore();
+        ig.add(BUILTIN_IGNORES);
+        const gitignorePath = join(this.projectRoot, ".gitignore");
+        if (existsSync(gitignorePath)) {
+            try {
+                const content = readFileSync(gitignorePath, "utf-8");
+                ig.add(content);
+            }
+            catch {
+                // ignore read failures
+            }
+        }
+        return ig;
+    }
+    isIgnoredWith(ig, relPath, isDir) {
+        const testPath = isDir ? `${relPath}/` : relPath;
+        return ig.ignores(testPath);
+    }
+}
+function isNodeError(err) {
+    return err instanceof Error && "code" in err;
+}
+//# sourceMappingURL=service.js.map

package/server/fs/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../src/fs/service.ts"],"names":[],"mappings":"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"}

package/server/fs/upload-staging.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Validation failure for a sessionId that does not match the strict
+ * format. Carries the raw value as a property so log sinks can decide
+ * whether to record it; the human-readable `message` stays a fixed
+ * literal so journald / file logs cannot be ANSI/newline-injected by an
+ * attacker who controls the query string (reviewed for correctness).
+ */
+export declare class InvalidSessionIdError extends Error {
+    readonly reason: "empty" | "format";
+    /** Raw value as received. Not embedded in `message`. */
+    readonly value: string;
+    constructor(reason: "empty" | "format", value: string);
+}
+export interface UploadStagingOptions {
+    /**
+     * Base directory. Resolved through `realpath()` once at construction
+     * (macOS `/tmp` -> `/private/tmp`) so every later `startsWith(rootDir)`
+     * fence compares canonical paths. Defaults to `${tmpdir()}/parasor`.
+     */
+    rootDir?: string;
+    /**
+     * Entries older than this in `sweepStale()` are removed. Default 24h.
+     */
+    ttlMs?: number;
+    /**
+     * Test injection point. Defaults to `Date.now`.
+     */
+    clock?: () => number;
+}
+export declare class UploadStaging {
+    /** Canonical absolute path of `<rootDir>/uploads`. */
+    readonly uploadsDir: string;
+    private readonly ttlMs;
+    private readonly clock;
+    constructor(options?: UploadStagingOptions);
+    /**
+     * Acquire (or re-use) a session-scoped upload directory. The directory
+     * name is `{sessionId}` -- opaque per-PTY, no timestamp suffix. Multiple
+     * concurrent callers for the same sessionId race-safely converge on the
+     * same directory because `mkdir({recursive:true})` is idempotent
+     * (prior `recursive:false` would 500 on EEXIST).
+     */
+    acquire(sessionId: string): Promise<string>;
+    /**
+     * L1 cleanup. Removes the session's directory tree if any. Best-effort:
+     * a failure here is logged by the caller but never breaks shutdown.
+     */
+    releaseSession(sessionId: string): Promise<void>;
+    /**
+     * L2 / L3 cleanup. Walks `uploadsDir` and removes every entry whose
+     * mtime is older than `ttlMs`. We stat instead of parsing the entry
+     * name so a future-dated suffix cannot keep an entry alive forever
+     * (reviewed for correctness). Returns the removed paths so callers can log
+     * a single-line summary.
+     */
+    sweepStale(now?: number): Promise<{
+        swept: string[];
+    }>;
+}
+/**
+ * Best-effort removal of the legacy `.parasor/drops/` directory inside a
+ * project root. Upload staging isolation retires the in-tree drop layout entirely; on
+ * server boot the upload route's old dirs are deleted from every known
+ * project so the surface area for "stale screenshot in repo" goes to
+ * zero. Errors are swallowed (logged by caller) -- the legacy dir is
+ * already `.gitignore`d, so failure to delete is non-fatal.
+ *
+ * target is narrowed to `.parasor/drops/`. The
+ * parent `.parasor/` namespace is removed only when it ends up empty,
+ * so future code writing other entries under `.parasor/<other>` is
+ * not nuked by every server boot.
+ */
+export declare function removeLegacyDropsDir(projectRoot: string): Promise<{
+    removed: boolean;
+}>;
+//# sourceMappingURL=upload-staging.d.ts.map

package/server/fs/upload-staging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-staging.d.ts","sourceRoot":"","sources":["../../src/fs/upload-staging.ts"],"names":[],"mappings":"AAoCA;;;;;;GAMG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,QAAQ,CAAC;IACpC,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBACX,MAAM,EAAE,OAAO,GAAG,QAAQ,EAAE,KAAK,EAAE,MAAM;CAUtD;AAoBD,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;CACtB;AAED,qBAAa,aAAa;IACxB,sDAAsD;IACtD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;gBAEzB,OAAO,GAAE,oBAAyB;IAwB9C;;;;;;OAMG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAgBjD;;;OAGG;IACG,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOtD;;;;;;OAMG;IACG,UAAU,CAAC,GAAG,GAAE,MAAqB,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CAqC3E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CA2D/B"}

package/server/fs/upload-staging.js

@@ -0,0 +1,283 @@
+import { lstatSync, mkdirSync, realpathSync } from "node:fs";
+import { lstat, mkdir, readdir, realpath, rm, rmdir, stat, } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve, sep } from "node:path";
+/**
+ * Image / file drops attached from the chat composer land here, NOT inside
+ * the user's project tree. The directory layout is:
+ *
+ *   {rootDir}/uploads/{sessionId}/<filename>
+ *
+ * `{sessionId}` is opaque per-PTY (UUID). The directory is owned by the
+ * server process and exposed to the live PTY child via the per-session
+ * env var `PARASOR_UPLOAD_DIR` (set in `InProcessPtyHost.buildSessionEnv`)
+ * -- never as a shared root -- so the Claude wrapper's `--add-dir` only
+ * widens that PTY's allowlist to its own subdir, not its siblings'.
+ *
+ * Three-layer GC (upload staging isolation):
+ *  L1 -- `releaseSession()` on PTY exit (immediate, in-process)
+ *  L2 -- `sweepStale()` at server boot (handles SIGKILL leftovers)
+ *  L3 -- `sweepStale()` on a 60-min interval (handles long-lived servers)
+ */
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+const UPLOADS_SUBDIR = "uploads";
+/** Owner-only -- drop dir contents may include unredacted screenshots. */
+const DIR_MODE = 0o700;
+/**
+ * Validation failure for a sessionId that does not match the strict
+ * format. Carries the raw value as a property so log sinks can decide
+ * whether to record it; the human-readable `message` stays a fixed
+ * literal so journald / file logs cannot be ANSI/newline-injected by an
+ * attacker who controls the query string (reviewed for correctness).
+ */
+export class InvalidSessionIdError extends Error {
+    reason;
+    /** Raw value as received. Not embedded in `message`. */
+    value;
+    constructor(reason, value) {
+        super(reason === "empty"
+            ? "uploadStaging: empty sessionId"
+            : "uploadStaging: invalid sessionId format");
+        this.reason = reason;
+        this.value = value;
+        this.name = "InvalidSessionIdError";
+    }
+}
+/** Reject session-id strings that could escape the upload root. */
+function assertSafeSessionId(sessionId) {
+    if (sessionId.length === 0) {
+        throw new InvalidSessionIdError("empty", sessionId);
+    }
+    if (!/^[A-Za-z0-9_-]+$/.test(sessionId)) {
+        throw new InvalidSessionIdError("format", sessionId);
+    }
+}
+function isNodeErrorWithCode(err, code) {
+    return (err instanceof Error &&
+        "code" in err &&
+        err.code === code);
+}
+export class UploadStaging {
+    /** Canonical absolute path of `<rootDir>/uploads`. */
+    uploadsDir;
+    ttlMs;
+    clock;
+    constructor(options = {}) {
+        const baseRaw = options.rootDir ?? join(tmpdir(), "parasor");
+        // mkdirSync runs before realpath because realpath() throws ENOENT on
+        // a missing path. The constructor is sync to keep `index.ts` boot
+        // ordering simple -- every subsequent operation is async.
+        mkdirSync(baseRaw, { recursive: true, mode: DIR_MODE });
+        const uploadsRaw = join(baseRaw, UPLOADS_SUBDIR);
+        mkdirSync(uploadsRaw, { recursive: true, mode: DIR_MODE });
+        // Reject if an attacker pre-planted a symlink at our root: realpath()
+        // would happily follow the link and we'd write under their target.
+        // lstat *before* realpath so the symlink itself is the thing we
+        // inspect (reviewed for correctness). uid is checked against geteuid()
+        // -- owning user only, no group/other writers.
+        assertOwnedRealDir(baseRaw);
+        assertOwnedRealDir(uploadsRaw);
+        // realpath resolves symlinks (notably macOS /tmp -> /private/tmp).
+        // Sync resolution keeps the public `uploadsDir` available for the
+        // `--add-dir` env injection without forcing the constructor to be
+        // async.
+        this.uploadsDir = realpathSync(uploadsRaw);
+        this.ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+        this.clock = options.clock ?? (() => Date.now());
+    }
+    /**
+     * Acquire (or re-use) a session-scoped upload directory. The directory
+     * name is `{sessionId}` -- opaque per-PTY, no timestamp suffix. Multiple
+     * concurrent callers for the same sessionId race-safely converge on the
+     * same directory because `mkdir({recursive:true})` is idempotent
+     * (prior `recursive:false` would 500 on EEXIST).
+     */
+    async acquire(sessionId) {
+        assertSafeSessionId(sessionId);
+        const target = join(this.uploadsDir, sessionId);
+        // Defence in depth -- the sanitizer above already proves `sessionId`
+        // contains no separators, but the realpath-based fence catches a
+        // future regression of the validator.
+        if (!target.startsWith(this.uploadsDir + sep)) {
+            throw new Error("uploadStaging: target escaped uploadsDir");
+        }
+        // recursive:true converts EEXIST into a no-op success. The caller
+        // never sees an error if a sibling acquire() raced ahead, so two
+        // PTYs requesting the same sessionId both get the same dir back.
+        await mkdir(target, { recursive: true, mode: DIR_MODE });
+        return target;
+    }
+    /**
+     * L1 cleanup. Removes the session's directory tree if any. Best-effort:
+     * a failure here is logged by the caller but never breaks shutdown.
+     */
+    async releaseSession(sessionId) {
+        assertSafeSessionId(sessionId);
+        const target = join(this.uploadsDir, sessionId);
+        if (!target.startsWith(this.uploadsDir + sep))
+            return;
+        await rm(target, { recursive: true, force: true });
+    }
+    /**
+     * L2 / L3 cleanup. Walks `uploadsDir` and removes every entry whose
+     * mtime is older than `ttlMs`. We stat instead of parsing the entry
+     * name so a future-dated suffix cannot keep an entry alive forever
+     * (reviewed for correctness). Returns the removed paths so callers can log
+     * a single-line summary.
+     */
+    async sweepStale(now = this.clock()) {
+        const cutoff = now - this.ttlMs;
+        const swept = [];
+        let entries;
+        try {
+            entries = await readdir(this.uploadsDir);
+        }
+        catch (err) {
+            if (isNodeErrorWithCode(err, "ENOENT"))
+                return { swept };
+            throw err;
+        }
+        for (const name of entries) {
+            const full = join(this.uploadsDir, name);
+            // Same fence as acquire: never act outside uploadsDir.
+            if (!full.startsWith(this.uploadsDir + sep))
+                continue;
+            try {
+                const st = await stat(full);
+                // Both birthtime (creation) and mtime (last write) must be old
+                // enough to retire -- a stale dir whose user keeps appending
+                // files stays alive while it's still in use.
+                const ageRef = Math.max(st.mtimeMs, st.birthtimeMs || 0);
+                if (ageRef > cutoff)
+                    continue;
+            }
+            catch (err) {
+                if (isNodeErrorWithCode(err, "ENOENT"))
+                    continue;
+                throw err;
+            }
+            try {
+                await rm(full, { recursive: true, force: true });
+                swept.push(full);
+            }
+            catch (err) {
+                if (isNodeErrorWithCode(err, "ENOENT"))
+                    continue;
+                // Log + continue: a stuck entry must not block the rest of the
+                // sweep. Caller has no actionable response.
+                console.error("[upload-staging] sweep rm failed:", full, err);
+            }
+        }
+        return { swept };
+    }
+}
+/**
+ * Best-effort removal of the legacy `.parasor/drops/` directory inside a
+ * project root. Upload staging isolation retires the in-tree drop layout entirely; on
+ * server boot the upload route's old dirs are deleted from every known
+ * project so the surface area for "stale screenshot in repo" goes to
+ * zero. Errors are swallowed (logged by caller) -- the legacy dir is
+ * already `.gitignore`d, so failure to delete is non-fatal.
+ *
+ * target is narrowed to `.parasor/drops/`. The
+ * parent `.parasor/` namespace is removed only when it ends up empty,
+ * so future code writing other entries under `.parasor/<other>` is
+ * not nuked by every server boot.
+ */
+export async function removeLegacyDropsDir(projectRoot) {
+    // Realpath the project root first so a project pointer like
+    // `~/projects/foo` (already expanded by caller) is canonicalized
+    // before the startsWith fence below.
+    let realProject;
+    try {
+        realProject = await realpath(projectRoot);
+    }
+    catch (err) {
+        if (isNodeErrorWithCode(err, "ENOENT"))
+            return { removed: false };
+        throw err;
+    }
+    const parasorDir = resolve(realProject, ".parasor");
+    const dropsDir = resolve(parasorDir, "drops");
+    // Reject if `.parasor` itself is a symlink -- refuse to follow into
+    // arbitrary territory. Using lstat (not stat) so the symlink itself
+    // is the thing we inspect.
+    try {
+        const parasorLst = await lstat(parasorDir);
+        if (parasorLst.isSymbolicLink())
+            return { removed: false };
+    }
+    catch (err) {
+        if (isNodeErrorWithCode(err, "ENOENT"))
+            return { removed: false };
+        throw err;
+    }
+    // Defence in depth: re-canonicalize and verify the drops path stays
+    // inside the project root. Catches a `.parasor/drops -> /etc` symlink
+    // even after the parent-dir lstat above passed.
+    let realDrops;
+    try {
+        realDrops = await realpath(dropsDir);
+    }
+    catch (err) {
+        if (isNodeErrorWithCode(err, "ENOENT"))
+            return { removed: false };
+        throw err;
+    }
+    if (realDrops !== resolve(realProject, ".parasor", "drops") ||
+        !realDrops.startsWith(realProject + sep)) {
+        return { removed: false };
+    }
+    await rm(realDrops, { recursive: true, force: true });
+    // Best-effort: clean the now-orphaned `.parasor/` shell, but only if
+    // empty. Other tooling that legitimately writes to `.parasor/<other>`
+    // (future features, user scripts) keeps its data.
+    try {
+        await rmdir(parasorDir);
+    }
+    catch (err) {
+        // ENOTEMPTY = other entries present (future namespace neighbours);
+        // ENOENT = removed concurrently. Both fine.
+        if (!isNodeErrorWithCode(err, "ENOTEMPTY") &&
+            !isNodeErrorWithCode(err, "ENOENT") &&
+            // Some platforms return EEXIST instead of ENOTEMPTY for non-empty
+            // rmdir (POSIX permits either).
+            !isNodeErrorWithCode(err, "EEXIST")) {
+            throw err;
+        }
+    }
+    return { removed: true };
+}
+/**
+ * Refuse to use `path` if its `lstat` reports it as a symlink, or its
+ * owner uid does not match the running process's effective uid. The
+ * latter check is skipped on Windows where `geteuid` is unavailable;
+ * elsewhere it ensures an attacker who pre-created the dir under a
+ * different user cannot trick us into writing secrets they can read.
+ */
+function assertOwnedRealDir(path) {
+    let st;
+    try {
+        st = lstatSync(path);
+    }
+    catch {
+        // Constructor only calls this after a successful mkdirSync so
+        // ENOENT here would be a TOCTOU race -- refuse to continue.
+        throw new Error(`uploadStaging: cannot lstat ${path}`);
+    }
+    if (st.isSymbolicLink()) {
+        throw new Error(`uploadStaging: refusing symlink at ${path}`);
+    }
+    if (!st.isDirectory()) {
+        throw new Error(`uploadStaging: not a directory: ${path}`);
+    }
+    // process.geteuid is undefined on Windows; skip the uid check there.
+    const geteuid = process.geteuid;
+    if (geteuid) {
+        const me = geteuid();
+        if (st.uid !== me) {
+            throw new Error(`uploadStaging: ${path} is owned by uid ${st.uid}, expected ${me}`);
+        }
+    }
+}
+//# sourceMappingURL=upload-staging.js.map