@openclaw/fs-safe 0.11.0 → 0.13.0

package/dist/temp-workspace-admission.js

@@ -0,0 +1,374 @@
+import fsSync, {} from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { inspectDirectoryIdentitySync, observeDirectoryIdentitySync, } from "./directory-guard.js";
+import { admitTempWorkspaceChild, admitTempWorkspaceChildSync, } from "./temp-workspace-child-admission.js";
+import { FsSafeError } from "./errors.js";
+import { recordFileObservationFailure } from "./file-observation.js";
+import { realpathSync } from "./realpath.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { inspectTempWorkspaceDescriptorIdentitySync, projectTempWorkspaceNumericIdentity, TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY, } from "./temp-workspace-identity.js";
+import { assertTrustedTempWorkspaceDirectory } from "./temp-workspace-permissions.js";
+const WINDOWS = process.platform === "win32";
+function effectiveOwner() {
+    // Windows mode/uid fields do not describe ACL authority. The supplied root's
+    // ACL remains a caller trust requirement, independently of cleanup safety.
+    if (WINDOWS)
+        return undefined;
+    let uid;
+    try {
+        uid = process.geteuid?.();
+    }
+    catch (cause) {
+        throw new FsSafeError("permission-unverified", "temp workspace requires effective owner identity", { cause });
+    }
+    if (!Number.isSafeInteger(uid) || uid === undefined || uid < 0) {
+        throw new FsSafeError("permission-unverified", "temp workspace requires effective owner identity");
+    }
+    return uid;
+}
+function safeNumericIdentity(stat) {
+    const numeric = projectTempWorkspaceNumericIdentity(stat);
+    return numeric && (!WINDOWS || (numeric.dev !== 0 && numeric.ino !== 0))
+        ? numeric
+        : undefined;
+}
+function copyExactDirectoryObservation(stat) {
+    return Object.freeze({
+        dev: stat.dev,
+        ino: stat.ino,
+        uid: stat.uid,
+        mode: stat.mode,
+        directory: stat.isDirectory(),
+        symbolicLink: stat.isSymbolicLink(),
+    });
+}
+function snapshotFromExactObservation(dir, uid, realPath, stat) {
+    if (stat.symbolicLink || !stat.directory) {
+        throw new FsSafeError("not-file", "temp workspace root component must be a real directory");
+    }
+    assertTrustedTempWorkspaceDirectory(stat, uid);
+    const identity = Object.freeze({ dev: stat.dev, ino: stat.ino });
+    // Retain copied immutable scalars, never a mutable Stats object supplied by
+    // an observation hook. Every later permission check uses a fresh snapshot.
+    return Object.freeze({ dir, identity, numericIdentity: safeNumericIdentity(stat), realPath });
+}
+function canonicalTempWorkspacePath(dir) {
+    assertNoWindowsPathAlias(dir, "filesystem");
+    const canonical = realpathSync.native(pathForWindowsFilesystem(dir));
+    assertNoWindowsPathAlias(canonical, "filesystem");
+    return canonical;
+}
+function snapshot(dir, uid, realPath = canonicalTempWorkspacePath(dir)) {
+    const stat = inspectDirectoryIdentitySync(dir);
+    const observation = copyExactDirectoryObservation(stat);
+    return { entry: snapshotFromExactObservation(dir, uid, realPath, observation), stat };
+}
+function hasCompleteExactIdentity(stat) {
+    return typeof stat.dev === "bigint" && typeof stat.ino === "bigint" &&
+        (!WINDOWS || (stat.dev !== 0n && stat.ino !== 0n));
+}
+function assertCanonicalRoot(entry) {
+    if (canonicalTempWorkspacePath(entry.dir) !== entry.realPath) {
+        throw new FsSafeError("path-mismatch", "temp workspace root ancestry changed");
+    }
+}
+function identityMismatch() {
+    const error = new FsSafeError("path-mismatch", "file identity changed or could not be verified");
+    recordFileObservationFailure(error, "identity");
+    throw error;
+}
+function inspectSnapshotIdentity(entry) {
+    const expected = entry.numericIdentity;
+    if (!expected) {
+        return inspectDirectoryIdentitySync(entry.dir, entry.identity);
+    }
+    const stat = observeDirectoryIdentitySync(entry.dir);
+    let requiresExactRetry = false;
+    const devKnown = Number.isSafeInteger(stat.dev) && stat.dev >= 0 && (!WINDOWS || stat.dev !== 0);
+    if (devKnown) {
+        if (stat.dev !== expected.dev)
+            identityMismatch();
+    }
+    else if (WINDOWS)
+        requiresExactRetry = true;
+    else
+        identityMismatch();
+    const inoKnown = Number.isSafeInteger(stat.ino) && stat.ino >= 0 && (!WINDOWS || stat.ino !== 0);
+    if (inoKnown) {
+        if (stat.ino !== expected.ino)
+            identityMismatch();
+    }
+    else if (WINDOWS)
+        requiresExactRetry = true;
+    else
+        identityMismatch();
+    if (!requiresExactRetry)
+        return stat;
+    // Read exact identity only once. The strict helper may re-check this constant
+    // receipt in memory when Windows still reports an unknown component.
+    const exact = observeDirectoryIdentitySync(entry.dir, { bigint: true });
+    return inspectFileIdentitySync(() => exact, entry.identity);
+}
+function assertSnapshot(entry, uid) {
+    const stat = inspectSnapshotIdentity(entry);
+    assertTrustedTempWorkspaceDirectory(stat, uid);
+    assertCanonicalRoot(entry);
+}
+function assertChain(chain, uid) {
+    for (const entry of chain) {
+        const current = inspectSnapshotIdentity(entry);
+        assertTrustedTempWorkspaceDirectory(current, uid);
+    }
+    const last = chain[chain.length - 1];
+    assertCanonicalRoot(last);
+}
+function canonicalAncestry(root) {
+    const ancestry = [];
+    for (let current = root;; current = path.dirname(current)) {
+        ancestry.push(current);
+        if (path.dirname(current) === current)
+            break;
+    }
+    return ancestry.reverse();
+}
+function exactIdentityMatches(current, expected) {
+    if (current.dev !== expected.dev || current.ino !== expected.ino)
+        identityMismatch();
+}
+function associateTempWorkspaceRoot(entry, ownerUid, descriptorFd) {
+    const stat = inspectTempWorkspaceDescriptorIdentitySync(descriptorFd, entry.identity, entry.numericIdentity);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw new FsSafeError("not-file", "temp workspace cleanup parent must be a real directory");
+    }
+    assertTrustedTempWorkspaceDirectory(stat, ownerUid);
+}
+function discoverMissingTempWorkspaceAncestor(ancestor, missing, missingError) {
+    // The caller already classified the first ENOENT. Keep this handoff out of
+    // the probe catch so neither it nor a later failure is classified twice.
+    const initialParent = path.dirname(ancestor);
+    if (initialParent === ancestor)
+        throw missingError;
+    missing.push(path.basename(ancestor));
+    ancestor = initialParent;
+    for (;;) {
+        try {
+            // Only subsequent non-volume-root probes may return a missing receipt.
+            const parent = path.dirname(ancestor);
+            const allowMissing = parent !== ancestor;
+            assertNoWindowsPathAlias(ancestor, "filesystem");
+            const operationPath = pathForWindowsFilesystem(ancestor);
+            const stat = allowMissing
+                ? fsSync.lstatSync(operationPath, { bigint: true, throwIfNoEntry: false })
+                : fsSync.lstatSync(operationPath, { bigint: true });
+            if (allowMissing && stat === undefined) {
+                missing.push(path.basename(ancestor));
+                ancestor = parent;
+                continue;
+            }
+            return { ancestor, initial: copyExactDirectoryObservation(stat) };
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            const parent = path.dirname(ancestor);
+            if (parent === ancestor)
+                throw error;
+            missing.push(path.basename(ancestor));
+            ancestor = parent;
+        }
+    }
+}
+function rootPlan(rootDir) {
+    assertNoWindowsPathAlias(rootDir, "filesystem");
+    const ownerUid = effectiveOwner();
+    let ancestor = resolvePathPreservingWindowsRoot(rootDir);
+    assertNoWindowsPathAlias(ancestor, "filesystem");
+    const missing = [];
+    let initial;
+    try {
+        initial = copyExactDirectoryObservation(fsSync.lstatSync(pathForWindowsFilesystem(ancestor), { bigint: true }));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        ({ ancestor, initial } = discoverMissingTempWorkspaceAncestor(ancestor, missing, error));
+    }
+    missing.reverse();
+    // Keep the historical support for a caller-approved root alias and standard
+    // system aliases such as macOS /var. A dangling alias fails canonicalization.
+    const observedAncestor = ancestor;
+    ancestor = canonicalTempWorkspacePath(observedAncestor);
+    const existingCanonicalRoot = missing.length === 0 && observedAncestor === ancestor &&
+        !initial.symbolicLink && initial.directory && hasCompleteExactIdentity(initial);
+    if (existingCanonicalRoot) {
+        const discovery = snapshotFromExactObservation(ancestor, ownerUid, ancestor, initial);
+        return {
+            admission: canonicalRootAdmission(discovery, ownerUid),
+            missing,
+            ownerUid,
+        };
+    }
+    const chain = canonicalAncestry(ancestor).map((dir) => snapshot(dir, ownerUid, dir).entry);
+    // Missing-component creation needs a replay before its first mutation. When
+    // the complete root already exists through an alias, retain the historical
+    // guarded route because discovery and mutation use different path spellings.
+    if (missing.length > 0)
+        assertChain(chain, ownerUid);
+    return { chain, missing, ownerUid };
+}
+function rootAdmission(chain, ownerUid) {
+    // Bind the immediate parent now: missing-component creation appends to chain.
+    const current = chain[chain.length - 1];
+    return {
+        dir: current.dir,
+        identity: current.identity,
+        ownerUid,
+        realPath: current.realPath,
+        retainCleanupParent: (descriptorFd) => {
+            assertSnapshot(current, ownerUid);
+            associateTempWorkspaceRoot(current, ownerUid, descriptorFd);
+        },
+        // The guarded route associated the cleanup parent while retaining it.
+        // A native capability probe therefore needs no additional observation.
+        prepareCleanupProbe: () => { },
+        prepareChildCreation: () => { assertChain(chain, ownerUid); },
+        assertCurrent: () => { assertSnapshot(current, ownerUid); },
+        assertAncestry: () => { assertChain(chain, ownerUid); },
+        associateCurrent: (descriptorFd) => {
+            assertSnapshot(current, ownerUid);
+            associateTempWorkspaceRoot(current, ownerUid, descriptorFd);
+        },
+        associateAncestry: (descriptorFd) => {
+            assertChain(chain, ownerUid);
+            associateTempWorkspaceRoot(current, ownerUid, descriptorFd);
+        },
+    };
+}
+function canonicalRootAdmission(discovery, ownerUid) {
+    let admittedChain;
+    const chain = () => {
+        if (!admittedChain) {
+            throw new FsSafeError("path-mismatch", "temp workspace root has not completed creation admission");
+        }
+        return admittedChain;
+    };
+    return {
+        dir: discovery.dir,
+        identity: discovery.identity,
+        ownerUid,
+        realPath: discovery.realPath,
+        // Merely opening the cleanup-parent descriptor grants no authority. The
+        // exact association is completed only at a bounded probe or the mutation
+        // boundary below.
+        retainCleanupParent: () => { },
+        prepareCleanupProbe: (descriptorFd) => {
+            // A native feature probe may inspect only a descriptor associated with
+            // the originally discovered root. This remains provisional: the named
+            // root and complete ancestry are freshly admitted before mutation.
+            assertCanonicalRoot(discovery);
+            associateTempWorkspaceRoot(discovery, ownerUid, descriptorFd);
+        },
+        prepareChildCreation: (descriptorFd) => {
+            const ancestry = canonicalAncestry(discovery.dir);
+            const candidate = ancestry.map((dir, index) => {
+                if (!TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY || index !== ancestry.length - 1) {
+                    return snapshot(dir, ownerUid, dir).entry;
+                }
+                const current = inspectSnapshotIdentity(discovery);
+                assertTrustedTempWorkspaceDirectory(current, ownerUid);
+                return discovery;
+            });
+            const current = candidate[candidate.length - 1];
+            exactIdentityMatches(current.identity, discovery.identity);
+            assertCanonicalRoot(current);
+            if (descriptorFd !== undefined) {
+                associateTempWorkspaceRoot(current, ownerUid, descriptorFd);
+            }
+            // Do not expose even the ancestry receipts until every named and
+            // descriptor association at this pre-mutation boundary has succeeded.
+            admittedChain = candidate;
+        },
+        assertCurrent: () => {
+            const currentChain = chain();
+            assertSnapshot(currentChain[currentChain.length - 1], ownerUid);
+        },
+        assertAncestry: () => { assertChain(chain(), ownerUid); },
+        associateCurrent: (descriptorFd) => {
+            const currentChain = chain();
+            const current = currentChain[currentChain.length - 1];
+            assertSnapshot(current, ownerUid);
+            associateTempWorkspaceRoot(current, ownerUid, descriptorFd);
+        },
+        associateAncestry: (descriptorFd) => {
+            const currentChain = chain();
+            assertChain(currentChain, ownerUid);
+            associateTempWorkspaceRoot(currentChain[currentChain.length - 1], ownerUid, descriptorFd);
+        },
+    };
+}
+export function admitExistingTempWorkspaceRoot(rootDir) {
+    const { admission, chain, missing, ownerUid } = rootPlan(rootDir);
+    if (missing.length > 0) {
+        throw new FsSafeError("helper-unavailable", "temp file cleanup parent is unavailable");
+    }
+    return admission ?? rootAdmission(chain, ownerUid);
+}
+export async function admitTempWorkspaceRoot(rootDir) {
+    const { admission, chain, missing, ownerUid } = rootPlan(rootDir);
+    if (admission)
+        return admission;
+    const guardedChain = chain;
+    for (const segment of missing) {
+        const parent = rootAdmission(guardedChain, ownerUid);
+        const dir = path.join(parent.dir, segment);
+        assertNoWindowsPathAlias(dir, "filesystem");
+        parent.assertCurrent();
+        let created = false;
+        try {
+            await fs.mkdir(dir, { mode: 0o700 });
+            created = true;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        parent.assertCurrent();
+        const observed = snapshot(dir, ownerUid);
+        if (created) {
+            const modeInitialization = admitTempWorkspaceChild(dir, observed.stat, parent, 0o700);
+            if (modeInitialization)
+                await modeInitialization;
+        }
+        guardedChain.push(observed.entry);
+    }
+    return rootAdmission(guardedChain, ownerUid);
+}
+export function admitTempWorkspaceRootSync(rootDir) {
+    const { admission, chain, missing, ownerUid } = rootPlan(rootDir);
+    if (admission)
+        return admission;
+    const guardedChain = chain;
+    for (const segment of missing) {
+        const parent = rootAdmission(guardedChain, ownerUid);
+        const dir = path.join(parent.dir, segment);
+        assertNoWindowsPathAlias(dir, "filesystem");
+        parent.assertCurrent();
+        let created = false;
+        try {
+            fsSync.mkdirSync(dir, { mode: 0o700 });
+            created = true;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        parent.assertCurrent();
+        const observed = snapshot(dir, ownerUid);
+        if (created)
+            admitTempWorkspaceChildSync(dir, observed.stat, parent, 0o700);
+        guardedChain.push(observed.entry);
+    }
+    return rootAdmission(guardedChain, ownerUid);
+}

package/dist/temp-workspace-child-admission.d.ts

@@ -0,0 +1,13 @@
+import type { BigIntStats, Stats } from "node:fs";
+import type { TempWorkspaceRootAdmission } from "./temp-workspace-admission.js";
+import type { TempWorkspaceRetainedChild } from "./temp-workspace-descriptor.js";
+import { type TempWorkspaceIdentityStat } from "./temp-workspace-identity.js";
+export declare function assertTempWorkspaceChildState(stat: BigIntStats | Stats, ownerUid: number | undefined): void;
+export declare function validateInitialTempWorkspaceChild(stat: BigIntStats, ownerUid: number | undefined, mode: number): boolean;
+export declare function childHasRequestedMode(stat: BigIntStats | Stats, mode: number): boolean;
+export declare function admitTempWorkspaceChild(dir: string, expected: BigIntStats, parent: TempWorkspaceRootAdmission, mode: number): Promise<void> | undefined;
+export declare function admitTempWorkspaceChildSync(dir: string, expected: BigIntStats, parent: TempWorkspaceRootAdmission, mode: number): void;
+export declare function admitRetainedTempWorkspaceChild(retained: TempWorkspaceRetainedChild, needsModeInitialization: boolean, parent: TempWorkspaceRootAdmission, mode: number): Promise<void> | undefined;
+export declare function admitRetainedTempWorkspaceChildSync(retained: TempWorkspaceRetainedChild, needsModeInitialization: boolean, parent: TempWorkspaceRootAdmission, mode: number): void;
+export declare function validateAdmittedTempWorkspaceChild(current: TempWorkspaceIdentityStat, ownerUid: number | undefined, mode: number): TempWorkspaceIdentityStat;
+//# sourceMappingURL=temp-workspace-child-admission.d.ts.map

package/dist/temp-workspace-child-admission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"temp-workspace-child-admission.d.ts","sourceRoot":"","sources":["../src/temp-workspace-child-admission.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAIlD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAChF,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,gCAAgC,CAAC;AACjF,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,8BAA8B,CAAC;AAKtC,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,WAAW,GAAG,KAAK,EACzB,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,IAAI,CAaN;AAED,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,WAAW,EACjB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,IAAI,EAAE,MAAM,GACX,OAAO,CAGT;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,WAAW,GAAG,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAMtF;AA0BD,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,WAAW,EACrB,MAAM,EAAE,0BAA0B,EAClC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS,CAG3B;AAED,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,WAAW,EACrB,MAAM,EAAE,0BAA0B,EAClC,IAAI,EAAE,MAAM,GACX,IAAI,CAkBN;AAED,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,0BAA0B,EACpC,uBAAuB,EAAE,OAAO,EAChC,MAAM,EAAE,0BAA0B,EAClC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS,CAG3B;AAED,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,0BAA0B,EACpC,uBAAuB,EAAE,OAAO,EAChC,MAAM,EAAE,0BAA0B,EAClC,IAAI,EAAE,MAAM,GACX,IAAI,CAMN;AAED,wBAAgB,kCAAkC,CAChD,OAAO,EAAE,yBAAyB,EAClC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,IAAI,EAAE,MAAM,GACX,yBAAyB,CAM3B"}

package/dist/temp-workspace-child-admission.js

@@ -0,0 +1,95 @@
+import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { pinNodeDirectoryForMode, pinNodeDirectoryForModeSync } from "./directory-mode-node.js";
+import { FsSafeError } from "./errors.js";
+import { TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY, } from "./temp-workspace-identity.js";
+import { assertTrustedTempWorkspaceDirectory } from "./temp-workspace-permissions.js";
+const WINDOWS = process.platform === "win32";
+export function assertTempWorkspaceChildState(stat, ownerUid) {
+    const exactIdentity = typeof stat.dev === "bigint" && typeof stat.ino === "bigint" &&
+        (!WINDOWS || (stat.dev !== 0n && stat.ino !== 0n));
+    const safeNumericIdentity = TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY &&
+        typeof stat.dev === "number" && Number.isSafeInteger(stat.dev) && stat.dev >= 0 &&
+        typeof stat.ino === "number" && Number.isSafeInteger(stat.ino) && stat.ino >= 0;
+    if (!exactIdentity && !safeNumericIdentity) {
+        throw new FsSafeError("path-mismatch", "temp workspace child identity could not be verified");
+    }
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw new FsSafeError("not-file", "temp workspace child must be a real directory");
+    }
+    assertTrustedTempWorkspaceDirectory(stat, ownerUid, true);
+}
+export function validateInitialTempWorkspaceChild(stat, ownerUid, mode) {
+    assertTempWorkspaceChildState(stat, ownerUid);
+    return !childHasRequestedMode(stat, mode);
+}
+export function childHasRequestedMode(stat, mode) {
+    // Windows st_mode does not establish ACL privacy. Creation still validates
+    // the exact named object, while the supplied root's ACL remains caller trust.
+    return WINDOWS || (typeof stat.mode === "bigint"
+        ? Number(stat.mode & 4095n)
+        : stat.mode & 0o7777) === (mode & 0o7777);
+}
+async function initializeTempWorkspaceChildMode(dir, expected, parent, mode) {
+    parent.assertCurrent();
+    const owner = await pinNodeDirectoryForMode(dir, {
+        expectedIdentity: expected,
+        ownerUid: parent.ownerUid,
+    });
+    try {
+        await owner.apply(mode, { check: parent.assertCurrent });
+        const current = inspectDirectoryIdentitySync(dir, expected);
+        assertTempWorkspaceChildState(current, parent.ownerUid);
+        if (!childHasRequestedMode(current, mode)) {
+            throw new FsSafeError("path-mismatch", "temp workspace final mode could not be verified");
+        }
+        parent.assertCurrent();
+    }
+    finally {
+        await owner.close();
+    }
+}
+export function admitTempWorkspaceChild(dir, expected, parent, mode) {
+    if (!validateInitialTempWorkspaceChild(expected, parent.ownerUid, mode))
+        return undefined;
+    return initializeTempWorkspaceChildMode(dir, expected, parent, mode);
+}
+export function admitTempWorkspaceChildSync(dir, expected, parent, mode) {
+    if (!validateInitialTempWorkspaceChild(expected, parent.ownerUid, mode))
+        return;
+    parent.assertCurrent();
+    const owner = pinNodeDirectoryForModeSync(dir, {
+        expectedIdentity: expected,
+        ownerUid: parent.ownerUid,
+    });
+    try {
+        owner.apply(mode, parent.assertCurrent);
+        const current = inspectDirectoryIdentitySync(dir, expected);
+        assertTempWorkspaceChildState(current, parent.ownerUid);
+        if (!childHasRequestedMode(current, mode)) {
+            throw new FsSafeError("path-mismatch", "temp workspace final mode could not be verified");
+        }
+        parent.assertCurrent();
+    }
+    finally {
+        owner.close();
+    }
+}
+export function admitRetainedTempWorkspaceChild(retained, needsModeInitialization, parent, mode) {
+    if (!needsModeInitialization)
+        return undefined;
+    return retained.initializeMode(mode, parent.ownerUid, parent.assertCurrent);
+}
+export function admitRetainedTempWorkspaceChildSync(retained, needsModeInitialization, parent, mode) {
+    if (!needsModeInitialization) {
+        retained.discardInitialReceipt();
+        return;
+    }
+    retained.initializeModeSync(mode, parent.ownerUid, parent.assertCurrent);
+}
+export function validateAdmittedTempWorkspaceChild(current, ownerUid, mode) {
+    assertTempWorkspaceChildState(current, ownerUid);
+    if (!childHasRequestedMode(current, mode)) {
+        throw new FsSafeError("path-mismatch", "temp workspace final mode could not be verified");
+    }
+    return current;
+}

package/dist/temp-workspace-descriptor.d.ts

@@ -0,0 +1,48 @@
+import fsSync from "node:fs";
+import type { FileIdentityStat } from "./file-identity.js";
+import type { TempWorkspaceRootAdmission } from "./temp-workspace-admission.js";
+import { type TempWorkspaceIdentityStat } from "./temp-workspace-identity.js";
+type DirectoryDescriptorAccess = "read" | "search";
+export type RetainedDirectory = {
+    fd: number;
+    access: DirectoryDescriptorAccess;
+    receipt: Readonly<{
+        path: string;
+        realPath: string;
+        identity: Readonly<{
+            dev: bigint;
+            ino: bigint;
+        }>;
+    }>;
+};
+export type RetainedChildDirectory = {
+    fd: number;
+};
+export declare function openTempWorkspaceCleanupParent(root: string, admission: TempWorkspaceRootAdmission): RetainedDirectory;
+/** Owns the child descriptor until final admission transfers it to cleanup. */
+export declare class TempWorkspaceRetainedChild {
+    #private;
+    private constructor();
+    static retain(dir: string, identity: FileIdentityStat): TempWorkspaceRetainedChild;
+    static retainCreated(dir: string): {
+        retained: TempWorkspaceRetainedChild;
+        stat: fsSync.BigIntStats;
+    };
+    discardInitialReceipt(): void;
+    finalizeAdmission(ownerUid: number | undefined, mode: number): TempWorkspaceIdentityStat;
+    initializeMode(mode: number, ownerUid: number | undefined, assertParent: () => void): Promise<void>;
+    initializeModeSync(mode: number, ownerUid: number | undefined, assertParent: () => void): void;
+    get canEnumerate(): boolean;
+    ensureReadable(): boolean;
+    transfer(retainDescriptor: boolean): {
+        dir: string;
+        identity: Readonly<{
+            dev: bigint;
+            ino: bigint;
+        }>;
+        directory: RetainedChildDirectory | undefined;
+    };
+    close(): void;
+}
+export {};
+//# sourceMappingURL=temp-workspace-descriptor.d.ts.map

package/dist/temp-workspace-descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"temp-workspace-descriptor.d.ts","sourceRoot":"","sources":["../src/temp-workspace-descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAU7B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAMhF,OAAO,EAML,KAAK,yBAAyB,EAC/B,MAAM,8BAA8B,CAAC;AAEtC,KAAK,yBAAyB,GAAG,MAAM,GAAG,QAAQ,CAAC;AASnD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,yBAAyB,CAAC;IAClC,OAAO,EAAE,QAAQ,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,QAAQ,CAAC;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAClD,CAAC,CAAC;CACJ,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAmDpD,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,0BAA0B,GACpC,iBAAiB,CA8BnB;AAED,+EAA+E;AAC/E,qBAAa,0BAA0B;;IAWrC,OAAO,eAqBN;IAED,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,0BAA0B,CAcjF;IAED,MAAM,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG;QACjC,QAAQ,EAAE,0BAA0B,CAAC;QACrC,IAAI,EAAE,MAAM,CAAC,WAAW,CAAC;KAC1B,CAoBA;IAED,qBAAqB,IAAI,IAAI,CAE5B;IAUD,iBAAiB,CACf,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,IAAI,EAAE,MAAM,GACX,yBAAyB,CAsB3B;IAoEK,cAAc,CAClB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,YAAY,EAAE,MAAM,IAAI,GACvB,OAAO,CAAC,IAAI,CAAC,CAgCf;IAED,kBAAkB,CAChB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,YAAY,EAAE,MAAM,IAAI,GACvB,IAAI,CAsBN;IAED,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED,cAAc,IAAI,OAAO,CAmDxB;IAED,QAAQ,CAAC,gBAAgB,EAAE,OAAO,GAAG;QACnC,GAAG,EAAE,MAAM,CAAC;QACZ,QAAQ,EAAE,QAAQ,CAAC;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACjD,SAAS,EAAE,sBAAsB,GAAG,SAAS,CAAC;KAC/C,CAiCA;IAED,KAAK,IAAI,IAAI,CAOZ;CACF"}