@nowcrew/daemon 0.6.15 → 0.6.17

package/dist/directory-projection.js

@@ -0,0 +1,922 @@
+import { randomUUID } from "node:crypto";
+import { chmod, cp, lstat, mkdir, open, readFile, readlink, realpath, readdir, rename, rm, symlink, unlink, writeFile, } from "node:fs/promises";
+import { posix, win32 } from "node:path";
+import { durableAtomicPrivateWrite, durableDirectorySync, durablePrivateUnlink, } from "./atomic-private-write.js";
+import { readExactDirectoryIdentity, sameExactDirectoryIdentity, validExactDirectoryIdentity, } from "./directory-projection-identity.js";
+export class DirectoryProjectionError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = "DirectoryProjectionError";
+    }
+}
+const MARKER_NAME = ".nowcrew-directory-projection.json";
+const SIDECAR_SUFFIX = ".nowcrew-owner.json";
+const COPY_SWAP_JOURNAL_SUFFIX = ".nowcrew-projection-journal.json";
+const MAX_OWNERSHIP_METADATA_BYTES = 16 * 1024;
+const DEFAULT_COPY_LIMITS = Object.freeze({
+    maxEntries: 10_000,
+    maxBytes: 256 * 1024 * 1024,
+    maxDepth: 32,
+    maxFileBytes: 64 * 1024 * 1024,
+});
+// Only Windows permission/policy denials authorize the readonly copy fallback.
+const JUNCTION_COPY_FALLBACK_CODES = new Set(["EACCES", "EPERM"]);
+const hasTraversal = (value, platform) => (platform === "win32" ? value.split(/[\\/]/u) : value.split("/"))
+    .some((component) => component === "..");
+const isFullyQualifiedWindowsPath = (value) => {
+    if (/^\\\\[?.]\\/u.test(value))
+        return false;
+    if (/^[A-Za-z]:[\\/]/u.test(value))
+        return true;
+    return /^\\\\[^\\/]+[\\/][^\\/]+(?:[\\/]|$)/u.test(value);
+};
+const normalizeWindowsLinkTarget = (value) => {
+    if (/^\\\\\?\\UNC\\/iu.test(value))
+        return `\\\\${value.slice(8)}`;
+    if (/^\\\\\?\\[A-Za-z]:\\/u.test(value))
+        return value.slice(4);
+    return value;
+};
+const normalizeAbsolute = (value, platform, path) => {
+    if (value.length === 0 || value.includes("\0") || hasTraversal(value, platform)) {
+        throw new DirectoryProjectionError("directory_projection_path_invalid");
+    }
+    if (platform === "win32" ? !isFullyQualifiedWindowsPath(value) : !path.isAbsolute(value)) {
+        throw new DirectoryProjectionError("directory_projection_path_invalid");
+    }
+    return path.normalize(value);
+};
+const isWithin = (parent, candidate, path) => {
+    const relative = path.relative(parent, candidate);
+    return relative !== ""
+        && relative !== ".."
+        && !relative.startsWith(`..${path.sep}`)
+        && !path.isAbsolute(relative);
+};
+const samePath = (left, right, path) => path.relative(left, right) === "";
+const errorCode = (error) => error.code;
+const resolveLimits = (input) => {
+    const bounded = (name) => {
+        const value = input?.[name] ?? DEFAULT_COPY_LIMITS[name];
+        if (!Number.isSafeInteger(value) || value <= 0) {
+            throw new DirectoryProjectionError("directory_projection_path_invalid");
+        }
+        return Math.min(value, DEFAULT_COPY_LIMITS[name]);
+    };
+    return Object.freeze({
+        maxEntries: bounded("maxEntries"),
+        maxBytes: bounded("maxBytes"),
+        maxDepth: bounded("maxDepth"),
+        maxFileBytes: bounded("maxFileBytes"),
+    });
+};
+const assertWithinLimits = (entries, bytes, depth, fileBytes, limits) => {
+    if (entries > limits.maxEntries
+        || bytes > limits.maxBytes
+        || depth > limits.maxDepth
+        || fileBytes > limits.maxFileBytes) {
+        throw new DirectoryProjectionError("directory_projection_limit_exceeded");
+    }
+};
+const tryLstat = async (projectionFs, target) => {
+    try {
+        return await projectionFs.lstat(target);
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return null;
+        throw error;
+    }
+};
+const markerFor = (source, target, finalTarget, nonce) => Object.freeze({
+    managedBy: "nowcrew-directory-projection",
+    version: 2,
+    source,
+    target,
+    finalTarget,
+    nonce,
+});
+const readMarker = async (projectionFs, root, path) => {
+    const markerPath = path.join(root, MARKER_NAME);
+    const info = await tryLstat(projectionFs, markerPath);
+    if (info === null || !info.isFile() || info.isSymbolicLink()
+        || Number(info.size) > MAX_OWNERSHIP_METADATA_BYTES)
+        return null;
+    let raw;
+    try {
+        raw = await projectionFs.readFile(markerPath, "utf8");
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return null;
+        throw error;
+    }
+    try {
+        const candidate = JSON.parse(raw);
+        if (candidate.managedBy !== "nowcrew-directory-projection"
+            || candidate.version !== 2
+            || typeof candidate.source !== "string"
+            || typeof candidate.target !== "string"
+            || typeof candidate.finalTarget !== "string"
+            || typeof candidate.nonce !== "string")
+            return null;
+        return candidate;
+    }
+    catch {
+        return null;
+    }
+};
+const sameComponent = (left, right, path) => (path === win32 ? left.toLowerCase() : left) === (path === win32 ? right.toLowerCase() : right);
+const normalizedMarker = (marker, path) => {
+    if (marker === null || !/^[A-Za-z0-9-]{1,128}$/u.test(marker.nonce))
+        return null;
+    const platform = path === win32 ? "win32" : "linux";
+    try {
+        return Object.freeze({
+            ...marker,
+            source: normalizeAbsolute(marker.source, platform, path),
+            target: normalizeAbsolute(marker.target, platform, path),
+            finalTarget: normalizeAbsolute(marker.finalTarget, platform, path),
+        });
+    }
+    catch {
+        return null;
+    }
+};
+const hasPermittedFinalTarget = (operationTarget, finalTarget, path) => {
+    if (samePath(operationTarget, finalTarget, path))
+        return true;
+    if (!sameComponent(path.basename(operationTarget), path.basename(finalTarget), path))
+        return false;
+    const operationRoot = path.dirname(operationTarget);
+    const finalRoot = path.dirname(finalTarget);
+    if (!samePath(path.dirname(operationRoot), path.dirname(finalRoot), path))
+        return false;
+    const expectedPrefix = `.${path.basename(finalRoot)}-next-`;
+    const operationRootName = path.basename(operationRoot);
+    const comparableRootName = path === win32 ? operationRootName.toLowerCase() : operationRootName;
+    const comparablePrefix = path === win32 ? expectedPrefix.toLowerCase() : expectedPrefix;
+    return comparableRootName.startsWith(comparablePrefix)
+        && /^[A-Za-z0-9-]{1,128}$/u.test(operationRootName.slice(expectedPrefix.length));
+};
+const markerMatchesOperationTarget = (marker, target, path, nonce) => {
+    const normalized = normalizedMarker(marker, path);
+    return normalized !== null
+        && samePath(normalized.target, target, path)
+        && hasPermittedFinalTarget(normalized.target, normalized.finalTarget, path)
+        && (nonce === undefined || normalized.nonce === nonce);
+};
+const markerMatchesFinalTarget = (marker, target, path, nonce) => {
+    const normalized = normalizedMarker(marker, path);
+    return normalized !== null
+        && samePath(normalized.finalTarget, target, path)
+        && hasPermittedFinalTarget(normalized.target, normalized.finalTarget, path)
+        && (nonce === undefined || normalized.nonce === nonce);
+};
+const readStagingSidecar = async (projectionFs, sidecarPath) => {
+    const info = await tryLstat(projectionFs, sidecarPath);
+    if (info === null || !info.isFile() || info.isSymbolicLink()
+        || Number(info.size) > MAX_OWNERSHIP_METADATA_BYTES)
+        return null;
+    let raw;
+    try {
+        raw = await projectionFs.readFile(sidecarPath, "utf8");
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return null;
+        throw error;
+    }
+    try {
+        const candidate = JSON.parse(raw);
+        if (candidate.managedBy !== "nowcrew-directory-projection-staging"
+            || candidate.version !== 1
+            || typeof candidate.staging !== "string"
+            || typeof candidate.target !== "string"
+            || typeof candidate.nonce !== "string")
+            return null;
+        return candidate;
+    }
+    catch {
+        return null;
+    }
+};
+const stagingSidecarMatches = (sidecar, staging, target, nonce, path) => {
+    if (sidecar === null || sidecar.nonce !== nonce || !/^[A-Za-z0-9-]{1,128}$/u.test(sidecar.nonce))
+        return false;
+    try {
+        const platform = path === win32 ? "win32" : "linux";
+        return samePath(normalizeAbsolute(sidecar.staging, platform, path), staging, path)
+            && samePath(normalizeAbsolute(sidecar.target, platform, path), target, path);
+    }
+    catch {
+        return false;
+    }
+};
+const isAbsoluteLink = (value) => posix.isAbsolute(value) || win32.isAbsolute(value);
+const validateCopySource = async (projectionFs, source, path, limits) => {
+    const rootInfo = await tryLstat(projectionFs, source);
+    if (rootInfo === null || !rootInfo.isDirectory() || rootInfo.isSymbolicLink()) {
+        throw new DirectoryProjectionError("directory_projection_source_invalid");
+    }
+    const pending = [
+        { directory: source, depth: 0 },
+    ];
+    let entryCount = 0;
+    let byteCount = 0;
+    while (pending.length > 0) {
+        const current = pending.pop();
+        const entries = await projectionFs.readdir(current.directory, { withFileTypes: true });
+        for (const entry of entries) {
+            if (current.depth === 0 && entry.name === MARKER_NAME) {
+                throw new DirectoryProjectionError("directory_projection_source_invalid");
+            }
+            const candidate = path.join(current.directory, entry.name);
+            const candidateInfo = await tryLstat(projectionFs, candidate);
+            if (candidateInfo === null) {
+                throw new DirectoryProjectionError("directory_projection_source_invalid");
+            }
+            const depth = current.depth + 1;
+            entryCount += 1;
+            if (candidateInfo.isSymbolicLink()) {
+                const link = await projectionFs.readlink(candidate);
+                if (isAbsoluteLink(link)) {
+                    throw new DirectoryProjectionError("directory_projection_source_invalid");
+                }
+                const resolved = path.resolve(path.dirname(candidate), link);
+                if (!samePath(source, resolved, path) && !isWithin(source, resolved, path)) {
+                    throw new DirectoryProjectionError("directory_projection_source_invalid");
+                }
+            }
+            else if (candidateInfo.isDirectory()) {
+                pending.push({ directory: candidate, depth });
+            }
+            else if (!candidateInfo.isFile()) {
+                throw new DirectoryProjectionError("directory_projection_source_invalid");
+            }
+            else {
+                const fileSize = Number(candidateInfo.size);
+                if (!Number.isSafeInteger(fileSize) || fileSize < 0) {
+                    throw new DirectoryProjectionError("directory_projection_limit_exceeded");
+                }
+                byteCount += fileSize;
+            }
+            const fileSize = candidateInfo.isFile() ? Number(candidateInfo.size) : 0;
+            assertWithinLimits(entryCount, byteCount, depth, fileSize, limits);
+        }
+    }
+};
+const validateStagedCopy = async (projectionFs, staging, path, limits) => {
+    let physicalRoot;
+    try {
+        physicalRoot = await projectionFs.realpath(staging);
+    }
+    catch {
+        throw new DirectoryProjectionError("directory_projection_source_invalid");
+    }
+    const pending = [
+        { directory: staging, depth: 0 },
+    ];
+    let entryCount = 0;
+    let byteCount = 0;
+    while (pending.length > 0) {
+        const current = pending.pop();
+        for (const entry of await projectionFs.readdir(current.directory, { withFileTypes: true })) {
+            const candidate = path.join(current.directory, entry.name);
+            const info = await projectionFs.lstat(candidate);
+            const adapterMarker = current.depth === 0 && entry.name === MARKER_NAME;
+            const depth = current.depth + 1;
+            if (!adapterMarker)
+                entryCount += 1;
+            if (info.isSymbolicLink()) {
+                const link = await projectionFs.readlink(candidate);
+                if (isAbsoluteLink(link)) {
+                    throw new DirectoryProjectionError("directory_projection_source_invalid");
+                }
+                const lexicalTarget = path.resolve(path.dirname(candidate), link);
+                if (!samePath(staging, lexicalTarget, path) && !isWithin(staging, lexicalTarget, path)) {
+                    throw new DirectoryProjectionError("directory_projection_source_invalid");
+                }
+                let physicalTarget;
+                try {
+                    physicalTarget = await projectionFs.realpath(candidate);
+                }
+                catch {
+                    throw new DirectoryProjectionError("directory_projection_source_invalid");
+                }
+                if (!samePath(physicalRoot, physicalTarget, path) && !isWithin(physicalRoot, physicalTarget, path)) {
+                    throw new DirectoryProjectionError("directory_projection_source_invalid");
+                }
+            }
+            else if (info.isDirectory()) {
+                pending.push({ directory: candidate, depth });
+            }
+            else if (!info.isFile()) {
+                throw new DirectoryProjectionError("directory_projection_source_invalid");
+            }
+            else if (!adapterMarker) {
+                const fileSize = Number(info.size);
+                if (!Number.isSafeInteger(fileSize) || fileSize < 0) {
+                    throw new DirectoryProjectionError("directory_projection_limit_exceeded");
+                }
+                byteCount += fileSize;
+            }
+            if (!adapterMarker) {
+                assertWithinLimits(entryCount, byteCount, depth, info.isFile() ? Number(info.size) : 0, limits);
+            }
+        }
+    }
+};
+const applyBestEffortReadonly = async (projectionFs, root, path) => {
+    const pending = [
+        { candidate: root, visited: false },
+    ];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        const info = await projectionFs.lstat(current.candidate);
+        if (info.isSymbolicLink())
+            continue;
+        if (info.isDirectory() && !current.visited) {
+            pending.push({ candidate: current.candidate, visited: true });
+            for (const entry of await projectionFs.readdir(current.candidate, { withFileTypes: true })) {
+                pending.push({ candidate: path.join(current.candidate, entry.name), visited: false });
+            }
+        }
+        else if (info.isDirectory()) {
+            await projectionFs.chmod(current.candidate, 0o555);
+        }
+        else if (info.isFile()) {
+            await projectionFs.chmod(current.candidate, info.mode & 0o111 ? 0o555 : 0o444);
+        }
+    }
+};
+const makeWritable = async (projectionFs, root, path) => {
+    const pending = [root];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        const info = await projectionFs.lstat(current);
+        if (info.isSymbolicLink())
+            continue;
+        if (!info.isDirectory()) {
+            await projectionFs.chmod(current, 0o600);
+            continue;
+        }
+        await projectionFs.chmod(current, 0o700);
+        for (const entry of await projectionFs.readdir(current, { withFileTypes: true })) {
+            pending.push(path.join(current, entry.name));
+        }
+    }
+};
+const assertOwnedArtifact = async (projectionFs, root, target, path, identity, nonce) => {
+    const info = await tryLstat(projectionFs, root);
+    if (info === null || !info.isDirectory() || info.isSymbolicLink()
+        || !(identity === "operation"
+            ? markerMatchesOperationTarget(await readMarker(projectionFs, root, path), target, path, nonce)
+            : markerMatchesFinalTarget(await readMarker(projectionFs, root, path), target, path))) {
+        throw new DirectoryProjectionError("directory_projection_artifact_unmanaged");
+    }
+};
+const removeOwnedStaging = async (projectionFs, staging, sidecarPath, target, nonce, path) => {
+    if (!stagingSidecarMatches(await readStagingSidecar(projectionFs, sidecarPath), staging, target, nonce, path)) {
+        throw new DirectoryProjectionError("directory_projection_artifact_unmanaged");
+    }
+    const staged = await tryLstat(projectionFs, staging);
+    if (staged !== null) {
+        if (!staged.isDirectory() || staged.isSymbolicLink()) {
+            throw new DirectoryProjectionError("directory_projection_artifact_unmanaged");
+        }
+        await makeWritable(projectionFs, staging, path);
+        await projectionFs.rm(staging, { recursive: true, force: true });
+    }
+    await projectionFs.unlink(sidecarPath);
+};
+const removeOwnedSidecar = async (projectionFs, sidecarPath, staging, target, nonce, path) => {
+    if (!stagingSidecarMatches(await readStagingSidecar(projectionFs, sidecarPath), staging, target, nonce, path))
+        return;
+    await projectionFs.unlink(sidecarPath);
+};
+const copyArtifactPaths = (target, nonce, path) => {
+    const parent = path.dirname(target);
+    const name = path.basename(target);
+    return Object.freeze({
+        parent,
+        staging: path.join(parent, `.${name}.nowcrew-projection-staging-${nonce}`),
+        rollback: path.join(parent, `.${name}.nowcrew-projection-rollback-${nonce}`),
+        discard: path.join(parent, `.${name}.nowcrew-projection-discard-${nonce}`),
+        stagingSidecar: path.join(parent, `.${name}.nowcrew-projection-staging-${nonce}${SIDECAR_SUFFIX}`),
+        journal: path.join(parent, `.${name}${COPY_SWAP_JOURNAL_SUFFIX}`),
+    });
+};
+const copyDirectoryIdentity = async (projectionFs, target) => {
+    try {
+        return await readExactDirectoryIdentity(target, projectionFs.lstat);
+    }
+    catch {
+        throw new DirectoryProjectionError("directory_projection_artifact_unmanaged");
+    }
+};
+const assertCopyIdentity = async (projectionFs, target, expected) => {
+    const actual = await copyDirectoryIdentity(projectionFs, target);
+    if (actual === null || !sameExactDirectoryIdentity(actual, expected)) {
+        throw new DirectoryProjectionError("directory_projection_artifact_unmanaged");
+    }
+};
+const readCopySwapJournal = async (projectionFs, target, path) => {
+    const placeholder = copyArtifactPaths(target, "placeholder", path);
+    const info = await tryLstat(projectionFs, placeholder.journal);
+    if (info === null)
+        return null;
+    if (!info.isFile() || info.isSymbolicLink() || Number(info.size) > MAX_OWNERSHIP_METADATA_BYTES) {
+        throw new DirectoryProjectionError("directory_projection_artifact_unmanaged");
+    }
+    let candidate;
+    try {
+        candidate = JSON.parse(await projectionFs.readFile(placeholder.journal, "utf8"));
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            throw new DirectoryProjectionError("directory_projection_artifact_unmanaged");
+        }
+        throw error;
+    }
+    if (candidate.managedBy !== "nowcrew-directory-projection-swap"
+        || candidate.version !== 1
+        || (candidate.phase !== "prepared"
+            && candidate.phase !== "previous_moved"
+            && candidate.phase !== "committed")
+        || typeof candidate.nonce !== "string"
+        || !/^[A-Za-z0-9-]{1,128}$/u.test(candidate.nonce)
+        || typeof candidate.source !== "string"
+        || typeof candidate.target !== "string"
+        || typeof candidate.finalTarget !== "string"
+        || typeof candidate.staging !== "string"
+        || typeof candidate.rollback !== "string"
+        || typeof candidate.discard !== "string"
+        || typeof candidate.stagingSidecar !== "string"
+        || typeof candidate.hadPrevious !== "boolean"
+        || !validExactDirectoryIdentity(candidate.activatedIdentity)
+        || (candidate.previousIdentity !== null && !validExactDirectoryIdentity(candidate.previousIdentity))
+        || (candidate.previousNonce !== null && typeof candidate.previousNonce !== "string")) {
+        throw new DirectoryProjectionError("directory_projection_artifact_unmanaged");
+    }
+    const platform = path === win32 ? "win32" : "linux";
+    let normalizedSource;
+    let normalizedTarget;
+    let normalizedFinalTarget;
+    let normalizedStaging;
+    let normalizedRollback;
+    let normalizedDiscard;
+    let normalizedSidecar;
+    try {
+        normalizedSource = normalizeAbsolute(candidate.source, platform, path);
+        normalizedTarget = normalizeAbsolute(candidate.target, platform, path);
+        normalizedFinalTarget = normalizeAbsolute(candidate.finalTarget, platform, path);
+        normalizedStaging = normalizeAbsolute(candidate.staging, platform, path);
+        normalizedRollback = normalizeAbsolute(candidate.rollback, platform, path);
+        normalizedDiscard = normalizeAbsolute(candidate.discard, platform, path);
+        normalizedSidecar = normalizeAbsolute(candidate.stagingSidecar, platform, path);
+    }
+    catch {
+        throw new DirectoryProjectionError("directory_projection_artifact_unmanaged");
+    }
+    const expected = copyArtifactPaths(target, candidate.nonce, path);
+    if (!samePath(normalizedTarget, target, path)
+        || !samePath(normalizedStaging, expected.staging, path)
+        || !samePath(normalizedRollback, expected.rollback, path)
+        || !samePath(normalizedDiscard, expected.discard, path)
+        || !samePath(normalizedSidecar, expected.stagingSidecar, path)
+        || !hasPermittedFinalTarget(normalizedTarget, normalizedFinalTarget, path)
+        || samePath(normalizedSource, normalizedTarget, path)
+        || isWithin(normalizedSource, normalizedTarget, path)
+        || isWithin(normalizedTarget, normalizedSource, path)
+        || samePath(normalizedSource, normalizedFinalTarget, path)
+        || isWithin(normalizedSource, normalizedFinalTarget, path)
+        || isWithin(normalizedFinalTarget, normalizedSource, path)
+        || candidate.hadPrevious !== (candidate.previousIdentity !== null)
+        || candidate.hadPrevious !== (candidate.previousNonce !== null)
+        || (candidate.previousNonce !== null && !/^[A-Za-z0-9-]{1,128}$/u.test(candidate.previousNonce))) {
+        throw new DirectoryProjectionError("directory_projection_artifact_unmanaged");
+    }
+    return Object.freeze({
+        ...candidate,
+        source: normalizedSource,
+        target: normalizedTarget,
+        finalTarget: normalizedFinalTarget,
+        staging: normalizedStaging,
+        rollback: normalizedRollback,
+        discard: normalizedDiscard,
+        stagingSidecar: normalizedSidecar,
+    });
+};
+const writeCopySwapJournal = async (projectionFs, journal, path) => {
+    const journalPath = copyArtifactPaths(journal.target, journal.nonce, path).journal;
+    await durableAtomicPrivateWrite(journalPath, `${JSON.stringify(journal)}\n`, {
+        fs: projectionFs,
+        parentDirectory: path.dirname(journalPath),
+    });
+};
+const removeCopySwapJournal = async (projectionFs, journal, path) => {
+    const journalPath = copyArtifactPaths(journal.target, journal.nonce, path).journal;
+    await durablePrivateUnlink(journalPath, {
+        fs: projectionFs,
+        parentDirectory: path.dirname(journalPath),
+    });
+};
+const assertActivatedCopy = async (projectionFs, root, journal, path) => {
+    await assertCopyIdentity(projectionFs, root, journal.activatedIdentity);
+    await assertOwnedArtifact(projectionFs, root, journal.target, path, "operation", journal.nonce);
+};
+const assertPreviousCopy = async (projectionFs, root, journal, path, requireMarker) => {
+    if (journal.previousIdentity === null || journal.previousNonce === null) {
+        throw new DirectoryProjectionError("directory_projection_artifact_unmanaged");
+    }
+    await assertCopyIdentity(projectionFs, root, journal.previousIdentity);
+    if (requireMarker && !markerMatchesFinalTarget(await readMarker(projectionFs, root, path), journal.target, path, journal.previousNonce)) {
+        throw new DirectoryProjectionError("directory_projection_artifact_unmanaged");
+    }
+};
+const cleanupCommittedCopySwap = async (projectionFs, journal, path, syncDirectory) => {
+    const parent = path.dirname(journal.target);
+    await assertActivatedCopy(projectionFs, journal.target, journal, path);
+    const rollback = await copyDirectoryIdentity(projectionFs, journal.rollback);
+    if (rollback !== null) {
+        if (!journal.hadPrevious || await copyDirectoryIdentity(projectionFs, journal.discard) !== null) {
+            throw new DirectoryProjectionError("directory_projection_artifact_unmanaged");
+        }
+        await assertPreviousCopy(projectionFs, journal.rollback, journal, path, true);
+        await projectionFs.rename(journal.rollback, journal.discard);
+        await syncDirectory(parent);
+    }
+    const discard = await copyDirectoryIdentity(projectionFs, journal.discard);
+    if (discard !== null) {
+        if (!journal.hadPrevious)
+            throw new DirectoryProjectionError("directory_projection_artifact_unmanaged");
+        await assertPreviousCopy(projectionFs, journal.discard, journal, path, false);
+        await makeWritable(projectionFs, journal.discard, path);
+        await projectionFs.rm(journal.discard, { recursive: true, force: true });
+        await syncDirectory(parent);
+    }
+    if (await copyDirectoryIdentity(projectionFs, journal.staging) !== null) {
+        throw new DirectoryProjectionError("directory_projection_artifact_unmanaged");
+    }
+    await removeOwnedSidecar(projectionFs, journal.stagingSidecar, journal.staging, journal.target, journal.nonce, path);
+    await syncDirectory(parent);
+    await removeCopySwapJournal(projectionFs, journal, path);
+};
+const rollbackUncommittedCopySwap = async (projectionFs, journal, path, syncDirectory) => {
+    const parent = path.dirname(journal.target);
+    const current = await copyDirectoryIdentity(projectionFs, journal.target);
+    const currentIsPrevious = current !== null
+        && journal.previousIdentity !== null
+        && sameExactDirectoryIdentity(current, journal.previousIdentity);
+    if (current !== null && !currentIsPrevious) {
+        await assertActivatedCopy(projectionFs, journal.target, journal, path);
+        if (await copyDirectoryIdentity(projectionFs, journal.discard) !== null) {
+            throw new DirectoryProjectionError("directory_projection_artifact_unmanaged");
+        }
+        await projectionFs.rename(journal.target, journal.discard);
+        await syncDirectory(parent);
+    }
+    const afterActivation = await copyDirectoryIdentity(projectionFs, journal.target);
+    if (journal.hadPrevious) {
+        if (afterActivation === null) {
+            await assertPreviousCopy(projectionFs, journal.rollback, journal, path, true);
+            await projectionFs.rename(journal.rollback, journal.target);
+            await syncDirectory(parent);
+        }
+        else {
+            await assertPreviousCopy(projectionFs, journal.target, journal, path, true);
+        }
+    }
+    else if (afterActivation !== null) {
+        throw new DirectoryProjectionError("directory_projection_artifact_unmanaged");
+    }
+    if (await copyDirectoryIdentity(projectionFs, journal.rollback) !== null) {
+        throw new DirectoryProjectionError("directory_projection_artifact_unmanaged");
+    }
+    if (await copyDirectoryIdentity(projectionFs, journal.discard) !== null) {
+        await assertCopyIdentity(projectionFs, journal.discard, journal.activatedIdentity);
+        await makeWritable(projectionFs, journal.discard, path);
+        await projectionFs.rm(journal.discard, { recursive: true, force: true });
+        await syncDirectory(parent);
+    }
+    const staging = await copyDirectoryIdentity(projectionFs, journal.staging);
+    if (staging !== null) {
+        if (!sameExactDirectoryIdentity(staging, journal.activatedIdentity)) {
+            throw new DirectoryProjectionError("directory_projection_artifact_unmanaged");
+        }
+        await removeOwnedStaging(projectionFs, journal.staging, journal.stagingSidecar, journal.target, journal.nonce, path);
+        await syncDirectory(parent);
+    }
+    else {
+        await removeOwnedSidecar(projectionFs, journal.stagingSidecar, journal.staging, journal.target, journal.nonce, path);
+        await syncDirectory(parent);
+    }
+    await removeCopySwapJournal(projectionFs, journal, path);
+};
+const recoverManagedCopySwap = async (projectionFs, target, path, syncDirectory) => {
+    const journal = await readCopySwapJournal(projectionFs, target, path);
+    if (journal === null)
+        return;
+    if (journal.phase === "committed") {
+        await cleanupCommittedCopySwap(projectionFs, journal, path, syncDirectory);
+    }
+    else {
+        await rollbackUncommittedCopySwap(projectionFs, journal, path, syncDirectory);
+    }
+};
+const mappedPublishError = (error) => new DirectoryProjectionError(errorCode(error) === "EXDEV"
+    ? "directory_projection_cross_volume"
+    : "directory_projection_publish_failed");
+const mappedCleanupError = () => new DirectoryProjectionError("directory_projection_cleanup_pending");
+const projectManagedCopy = async (projectionFs, source, target, finalTarget, path, limits, randomId, syncDirectory) => {
+    await validateCopySource(projectionFs, source, path, limits);
+    const nonce = randomId();
+    if (!/^[A-Za-z0-9-]{1,128}$/u.test(nonce)) {
+        throw new DirectoryProjectionError("directory_projection_path_invalid");
+    }
+    const artifacts = copyArtifactPaths(target, nonce, path);
+    const parent = artifacts.parent;
+    const name = path.basename(target);
+    if (name.length === 0)
+        throw new DirectoryProjectionError("directory_projection_path_invalid");
+    const { staging, rollback, discard, stagingSidecar } = artifacts;
+    if (!samePath(path.dirname(staging), parent, path)
+        || !samePath(path.dirname(rollback), parent, path)
+        || !samePath(path.dirname(discard), parent, path)
+        || !samePath(path.parse(staging).root, path.parse(target).root, path)
+        || !samePath(path.parse(rollback).root, path.parse(target).root, path)
+        || !samePath(path.parse(discard).root, path.parse(target).root, path)) {
+        throw new DirectoryProjectionError("directory_projection_cross_volume");
+    }
+    if (await tryLstat(projectionFs, staging) !== null
+        || await tryLstat(projectionFs, rollback) !== null
+        || await tryLstat(projectionFs, discard) !== null
+        || await tryLstat(projectionFs, stagingSidecar) !== null
+        || await tryLstat(projectionFs, artifacts.journal) !== null) {
+        throw new DirectoryProjectionError("directory_projection_artifact_unmanaged");
+    }
+    const sidecar = Object.freeze({
+        managedBy: "nowcrew-directory-projection-staging",
+        version: 1,
+        staging,
+        target,
+        nonce,
+    });
+    try {
+        await projectionFs.writeFile(stagingSidecar, JSON.stringify(sidecar), {
+            encoding: "utf8",
+            mode: 0o600,
+            flag: "wx",
+        });
+    }
+    catch (error) {
+        if (errorCode(error) !== "EEXIST" && stagingSidecarMatches(await readStagingSidecar(projectionFs, stagingSidecar), staging, target, nonce, path)) {
+            await projectionFs.unlink(stagingSidecar);
+        }
+        if (errorCode(error) === "EEXIST") {
+            throw new DirectoryProjectionError("directory_projection_artifact_unmanaged");
+        }
+        throw error;
+    }
+    try {
+        await projectionFs.mkdir(staging, { mode: 0o700 });
+    }
+    catch (error) {
+        await removeOwnedSidecar(projectionFs, stagingSidecar, staging, target, nonce, path);
+        if (errorCode(error) === "EEXIST") {
+            throw new DirectoryProjectionError("directory_projection_artifact_unmanaged");
+        }
+        throw error;
+    }
+    const marker = markerFor(source, target, finalTarget, nonce);
+    try {
+        await projectionFs.writeFile(path.join(staging, MARKER_NAME), JSON.stringify(marker), {
+            encoding: "utf8",
+            mode: 0o600,
+            flag: "wx",
+        });
+    }
+    catch (error) {
+        await removeOwnedStaging(projectionFs, staging, stagingSidecar, target, nonce, path);
+        throw error;
+    }
+    try {
+        await projectionFs.cp(source, staging, {
+            recursive: true,
+            preserveTimestamps: true,
+            dereference: false,
+            verbatimSymlinks: true,
+        });
+        await validateStagedCopy(projectionFs, staging, path, limits);
+        if (!markerMatchesOperationTarget(await readMarker(projectionFs, staging, path), target, path, nonce)) {
+            throw new DirectoryProjectionError("directory_projection_source_invalid");
+        }
+        await applyBestEffortReadonly(projectionFs, staging, path);
+    }
+    catch (error) {
+        await removeOwnedStaging(projectionFs, staging, stagingSidecar, target, nonce, path);
+        throw error;
+    }
+    let previousIdentity = null;
+    let previousNonce = null;
+    try {
+        const previous = await tryLstat(projectionFs, target);
+        if (previous !== null) {
+            const previousMarker = await readMarker(projectionFs, target, path);
+            if (!previous.isDirectory() || previous.isSymbolicLink()
+                || !markerMatchesFinalTarget(previousMarker, target, path)) {
+                throw new DirectoryProjectionError("directory_projection_target_unmanaged");
+            }
+            previousIdentity = await copyDirectoryIdentity(projectionFs, target);
+            if (previousIdentity === null) {
+                throw new DirectoryProjectionError("directory_projection_artifact_unmanaged");
+            }
+            previousNonce = previousMarker.nonce;
+        }
+    }
+    catch (error) {
+        await removeOwnedStaging(projectionFs, staging, stagingSidecar, target, nonce, path);
+        throw error;
+    }
+    const activatedIdentity = await copyDirectoryIdentity(projectionFs, staging);
+    if (activatedIdentity === null) {
+        await removeOwnedStaging(projectionFs, staging, stagingSidecar, target, nonce, path);
+        throw new DirectoryProjectionError("directory_projection_artifact_unmanaged");
+    }
+    let journal = Object.freeze({
+        managedBy: "nowcrew-directory-projection-swap",
+        version: 1,
+        phase: "prepared",
+        nonce,
+        source,
+        target,
+        finalTarget,
+        staging,
+        rollback,
+        discard,
+        stagingSidecar,
+        hadPrevious: previousIdentity !== null,
+        previousNonce,
+        previousIdentity,
+        activatedIdentity,
+    });
+    try {
+        await writeCopySwapJournal(projectionFs, journal, path);
+        if (journal.hadPrevious) {
+            await projectionFs.rename(target, rollback);
+            await syncDirectory(parent);
+            await assertPreviousCopy(projectionFs, rollback, journal, path, true);
+        }
+        journal = Object.freeze({ ...journal, phase: "previous_moved" });
+        await writeCopySwapJournal(projectionFs, journal, path);
+        await assertActivatedCopy(projectionFs, staging, journal, path);
+        await projectionFs.rename(staging, target);
+        await syncDirectory(parent);
+        await assertActivatedCopy(projectionFs, target, journal, path);
+        const committed = Object.freeze({ ...journal, phase: "committed" });
+        await writeCopySwapJournal(projectionFs, committed, path);
+        journal = committed;
+    }
+    catch (error) {
+        const rollbackJournal = journal.phase === "committed"
+            ? Object.freeze({ ...journal, phase: "previous_moved" })
+            : journal;
+        try {
+            await writeCopySwapJournal(projectionFs, rollbackJournal, path);
+            await rollbackUncommittedCopySwap(projectionFs, rollbackJournal, path, syncDirectory);
+        }
+        catch {
+            throw mappedCleanupError();
+        }
+        if (error instanceof DirectoryProjectionError)
+            throw error;
+        throw mappedPublishError(error);
+    }
+    try {
+        await cleanupCommittedCopySwap(projectionFs, journal, path, syncDirectory);
+    }
+    catch {
+        throw mappedCleanupError();
+    }
+    return Object.freeze({ mode: "copy", target, copyProtection: "best-effort" });
+};
+const resolveFileSystem = (options) => ({
+    chmod: options.fs?.chmod ?? chmod,
+    cp: options.fs?.cp ?? cp,
+    lstat: options.fs?.lstat ?? lstat,
+    mkdir: options.fs?.mkdir ?? mkdir,
+    open: options.fs?.open ?? open,
+    readFile: options.fs?.readFile ?? readFile,
+    readlink: options.fs?.readlink ?? readlink,
+    realpath: options.fs?.realpath ?? realpath,
+    readdir: options.fs?.readdir ?? readdir,
+    rename: options.fs?.rename ?? rename,
+    rm: options.fs?.rm ?? rm,
+    symlink: options.fs?.symlink ?? symlink,
+    unlink: options.fs?.unlink ?? unlink,
+    writeFile: options.fs?.writeFile ?? writeFile,
+});
+export async function isManagedDirectoryProjectionCopy(target, platform, options = {}) {
+    if (platform !== "win32")
+        return false;
+    const path = platform === "win32" ? win32 : posix;
+    let normalizedTarget;
+    try {
+        normalizedTarget = normalizeAbsolute(target, platform, path);
+    }
+    catch {
+        return false;
+    }
+    const projectionFs = resolveFileSystem(options);
+    const info = await tryLstat(projectionFs, normalizedTarget);
+    return info !== null
+        && info.isDirectory()
+        && !info.isSymbolicLink()
+        && markerMatchesFinalTarget(await readMarker(projectionFs, normalizedTarget, path), normalizedTarget, path);
+}
+/**
+ * Projects one absolute directory without exposing host paths in errors.
+ *
+ * Containment is component-based in the target platform's path flavor: source and target may live in
+ * unrelated trees, but neither target identity may contain the source or be contained by it. Every
+ * adapter-owned staging, rollback, discard, and sidecar path is a direct sibling of the target on its
+ * volume. Raw `..` traversal, drive-relative/root-relative Windows paths, and device namespaces are
+ * rejected before IO.
+ *
+ * Windows copy ownership requires a version-2 marker whose normalized `finalTarget` exactly equals the
+ * inspected target. A distinct operation target is accepted only for the complete sibling
+ * `.skills-next-<id>/<name>` to `skills/<name>` lineage used by Project Skills reconciliation. Legacy,
+ * incomplete, POSIX, or mismatched markers never authorize refresh or deletion.
+ *
+ * Copy fallback never follows source links, rejects every absolute link form, and permits a relative link
+ * only when its completed staging target is both lexically and physically contained by that staging tree.
+ * Both traversals enforce fixed entry/byte/depth/file-size ceilings. Chmod only preserves readonly intent:
+ * on Windows copy protection is explicitly `best-effort`, not an enforced ACL security boundary, and the
+ * capability remains gated from Windows advertisement pending a native ACL rollout smoke test.
+ *
+ * Links use one symlink call, and a new copy is published by one rename. Refreshing a managed copy uses
+ * two same-parent renames, so the target name can be briefly absent, but readers never see a partially
+ * copied or mixed tree. A swap journal is fsynced before projection mutations; the new copy commits only
+ * after its activated identity and the committed journal rename are durable. Pre-commit failures restore
+ * the validated previous copy. Post-commit cleanup failures return `directory_projection_cleanup_pending`
+ * with the journal retained so the next call resumes exact nonce-owned cleanup. `EXDEV` is reported as
+ * `directory_projection_cross_volume` instead of claiming an atomic cross-volume switch.
+ */
+export async function projectDirectory(source, target, platform, options = {}) {
+    const path = platform === "win32" ? win32 : posix;
+    const normalizedSource = normalizeAbsolute(source, platform, path);
+    const normalizedTarget = normalizeAbsolute(target, platform, path);
+    const normalizedFinalTarget = options.finalTarget === undefined
+        ? normalizedTarget
+        : normalizeAbsolute(options.finalTarget, platform, path);
+    const overlapsSource = (candidate) => samePath(normalizedSource, candidate, path)
+        || isWithin(normalizedSource, candidate, path)
+        || isWithin(candidate, normalizedSource, path);
+    if (overlapsSource(normalizedTarget)
+        || overlapsSource(normalizedFinalTarget)
+        || !hasPermittedFinalTarget(normalizedTarget, normalizedFinalTarget, path)) {
+        throw new DirectoryProjectionError("directory_projection_path_overlap");
+    }
+    const projectionFs = resolveFileSystem(options);
+    const syncDirectory = options.syncDirectory ?? ((directory) => durableDirectorySync(directory, { fs: projectionFs }));
+    const limits = resolveLimits(options.limits);
+    const mode = platform === "win32" ? "junction" : "symlink";
+    if (platform === "win32") {
+        try {
+            await recoverManagedCopySwap(projectionFs, normalizedTarget, path, syncDirectory);
+        }
+        catch (error) {
+            if (error instanceof DirectoryProjectionError)
+                throw error;
+            throw mappedCleanupError();
+        }
+    }
+    const existing = await tryLstat(projectionFs, normalizedTarget);
+    if (existing !== null) {
+        if (existing.isSymbolicLink()) {
+            const rawLink = await projectionFs.readlink(normalizedTarget);
+            const link = path.resolve(path.dirname(normalizedTarget), platform === "win32" ? normalizeWindowsLinkTarget(rawLink) : rawLink);
+            if (!samePath(link, normalizedSource, path)) {
+                throw new DirectoryProjectionError("directory_projection_target_unmanaged");
+            }
+            return Object.freeze({ mode, target: normalizedTarget });
+        }
+        if (platform === "win32" && existing.isDirectory()
+            && markerMatchesFinalTarget(await readMarker(projectionFs, normalizedTarget, path), normalizedTarget, path)) {
+            return projectManagedCopy(projectionFs, normalizedSource, normalizedTarget, normalizedFinalTarget, path, limits, options.randomId ?? randomUUID, syncDirectory);
+        }
+        throw new DirectoryProjectionError("directory_projection_target_unmanaged");
+    }
+    try {
+        await projectionFs.symlink(normalizedSource, normalizedTarget, platform === "win32" ? "junction" : "dir");
+    }
+    catch (error) {
+        if (platform !== "win32" || !JUNCTION_COPY_FALLBACK_CODES.has(errorCode(error) ?? ""))
+            throw error;
+        return projectManagedCopy(projectionFs, normalizedSource, normalizedTarget, normalizedFinalTarget, path, limits, options.randomId ?? randomUUID, syncDirectory);
+    }
+    return Object.freeze({ mode, target: normalizedTarget });
+}