@openclaw/fs-safe 0.14.0 → 0.16.0

package/dist/windows-security-command.js

@@ -0,0 +1,363 @@
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { FsSafeError } from "./errors.js";
+import { DEFAULT_PERMISSION_EXEC_TIMEOUT_MS, PermissionCommandError } from "./permission-exec.js";
+import { resolveWindowsSystemCommand } from "./windows-command.js";
+import { parseWindowsSecurityCommandFacts } from "./windows-security-facts.js";
+const MAX_OUTPUT_BYTES = 1024 * 1024;
+const TERMINATION_GRACE_MS = 1_000;
+const FULL_IDENTITY = /^[0-9a-f]{16}:[0-9a-f]{32}$/;
+function isFullIdentity(identity) {
+    return typeof identity === "string" && identity.length === 49 && FULL_IDENTITY.test(identity);
+}
+function assertIdentity(identity) {
+    if (!isFullIdentity(identity)) {
+        throw new TypeError("Windows security operation requires a complete file identity");
+    }
+}
+function command(operation, params) {
+    const targetPath = params.targetPath ?? "";
+    // Preserve native EINVAL before child-process environment validation runs.
+    if (targetPath.includes("\0")) {
+        throw Object.assign(new Error("Windows path contains a NUL byte"), { code: "EINVAL" });
+    }
+    if (params.fd !== undefined || operation === "descriptor" || operation === "protect-file" || operation === "verify-file") {
+        if (typeof params.fd !== "number" || !Number.isInteger(params.fd) || params.fd < 0 || params.fd > 0x7fff_ffff) {
+            unverified("Windows security inspection requires a valid descriptor");
+        }
+    }
+    if (params.expectedParentIdentity !== undefined)
+        assertIdentity(params.expectedParentIdentity);
+    if (params.expectedFileIdentity !== undefined)
+        assertIdentity(params.expectedFileIdentity);
+    if (params.expectedLinks !== undefined &&
+        (!Number.isInteger(params.expectedLinks) || params.expectedLinks < 1 || params.expectedLinks > 0xffff_ffff)) {
+        throw new TypeError("Windows security operation requires a positive uint32 link count");
+    }
+    const script = fileURLToPath(new URL("./windows-security-bridge.ps1", import.meta.url));
+    return {
+        file: resolveWindowsSystemCommand(String.raw `WindowsPowerShell\v1.0\powershell.exe`),
+        args: ["-NoLogo", "-NoProfile", "-NonInteractive", "-File", script, "-Operation", operation],
+        // Preserve Windows UTF-16 spelling and leave long paths out of the bounded
+        // command line. This overrides any inherited value only in this child.
+        env: {
+            ...process.env,
+            FS_SAFE_WINDOWS_SECURITY_PATH: targetPath,
+            FS_SAFE_WINDOWS_SECURITY_REQUIRE_PRIVATE: params.requirePrivate ? "1" : "0",
+            FS_SAFE_WINDOWS_SECURITY_PARENT_IDENTITY: params.expectedParentIdentity ?? "",
+            FS_SAFE_WINDOWS_SECURITY_FILE_IDENTITY: params.expectedFileIdentity ?? "",
+            FS_SAFE_WINDOWS_SECURITY_EXPECTED_LINKS: String(params.expectedLinks ?? 1),
+        },
+    };
+}
+function unverified(message, cause) {
+    throw new FsSafeError("permission-unverified", message, cause === undefined ? {} : { cause });
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function parseReply(stdout, operation) {
+    try {
+        return parseReplyValue(stdout, operation);
+    }
+    catch (error) {
+        if (operation === "create" && error instanceof Error && error.code !== "EEXIST") {
+            Object.assign(error, { creationOutcome: "unconfirmed" });
+        }
+        throw error;
+    }
+}
+function parseReplyValue(stdout, operation) {
+    let response;
+    try {
+        response = JSON.parse(stdout.trim());
+    }
+    catch (cause) {
+        unverified("Windows security command returned invalid data", cause);
+    }
+    if (!record(response) || typeof response.ok !== "boolean") {
+        unverified("Windows security command returned an incomplete response");
+    }
+    if (!response.ok) {
+        const codes = new Set(["EACCES", "EPERM", "EEXIST", "ENOENT", "ENOTSUP", "EIO", "EBADF", "ELOOP", "ENOTDIR", "EINVAL", "ENOSPC", "EBUSY"]);
+        if (typeof response.code !== "string" || !codes.has(response.code) || typeof response.message !== "string") {
+            unverified("Windows security command returned an invalid failure");
+        }
+        throw Object.assign(new Error(response.message), { code: response.code });
+    }
+    if (operation === "create" && (!record(response.result) || response.result.created !== true || !isFullIdentity(response.result.identity))) {
+        unverified("Windows security command did not verify private-directory creation");
+    }
+    return response.result;
+}
+function executeSync(operation, params) {
+    const { file, args, env } = command(operation, params);
+    const startedAt = performance.now();
+    const result = spawnSync(file, args, {
+        encoding: "utf8", windowsHide: true, env, stdio: [params.fd ?? "ignore", "pipe", "pipe"],
+        timeout: DEFAULT_PERMISSION_EXEC_TIMEOUT_MS, killSignal: "SIGKILL", maxBuffer: MAX_OUTPUT_BYTES,
+    });
+    if (result.error || result.status !== 0) {
+        const error = new PermissionCommandError(file, performance.now() - startedAt, {
+            cause: result.error, code: result.status,
+            signal: result.error?.code === "ETIMEDOUT" ? "SIGKILL" : result.signal,
+            stderr: result.stderr,
+            killed: result.error?.code === "ETIMEDOUT",
+            ...(operation === "create" ? { creationOutcome: "unconfirmed" } : {}),
+        });
+        if (operation === "create")
+            Object.assign(error, { creationOutcome: "unconfirmed" });
+        throw error;
+    }
+    return parseReply(result.stdout, operation);
+}
+class WindowsSecurityCommandError extends PermissionCommandError {
+    timedOut;
+    creationOutcome;
+    processExitConfirmed;
+    constructor(file, durationMs, receipt, timedOut) {
+        super(file, durationMs, receipt);
+        this.timedOut = timedOut;
+        this.creationOutcome = receipt.creationOutcome;
+        this.processExitConfirmed = receipt.processExitConfirmed;
+        if (timedOut)
+            this.message = `Windows permission inspection timed out after ${DEFAULT_PERMISSION_EXEC_TIMEOUT_MS}ms`;
+        if (!receipt.processExitConfirmed)
+            this.message += "; process exit was not confirmed";
+        else if (!receipt.outputClosed)
+            this.message += "; command output did not close";
+        if (receipt.creationOutcome)
+            this.message += "; private-directory creation outcome is unconfirmed";
+    }
+}
+/** Cleanup must preserve stages still reachable by an unsettled command. */
+export function hasUnsettledWindowsSecurityCommand(error) {
+    const pending = [error];
+    const seen = new Set();
+    for (let inspected = 0; pending.length && inspected < 32; inspected++) {
+        const current = pending.pop();
+        if (current === null || typeof current !== "object" || seen.has(current))
+            continue;
+        seen.add(current);
+        try {
+            if (current instanceof WindowsSecurityCommandError && !current.processExitConfirmed)
+                return true;
+            const cause = Object.getOwnPropertyDescriptor(current, "cause");
+            if (cause && "value" in cause)
+                pending.push(cause.value);
+            if (current instanceof AggregateError) {
+                const errors = Object.getOwnPropertyDescriptor(current, "errors");
+                if (errors && "value" in errors && Array.isArray(errors.value))
+                    pending.push(...errors.value.slice(0, 32));
+            }
+        }
+        catch {
+            // Unknown error wrappers cannot prove that command-owned handles settled.
+            return true;
+        }
+    }
+    return pending.length > 0;
+}
+function ignoreLateError() { }
+async function execute(operation, params) {
+    const { file, args, env } = command(operation, params);
+    const startedAt = performance.now();
+    return await new Promise((resolve, reject) => {
+        const child = spawn(file, args, { windowsHide: true, env, stdio: [params.fd ?? "ignore", "pipe", "pipe"] });
+        const output = [];
+        const errors = [];
+        let bytes = 0;
+        let failure;
+        let failed = false;
+        let timedOut = false;
+        let stopping = false;
+        let settled = false;
+        let processExitConfirmed = false;
+        let exitCode = null;
+        let exitSignal = null;
+        let terminationSignalSent;
+        let terminationError;
+        let grace;
+        let missingPipes;
+        const deadlineError = () => new Error("Windows security command exceeded its inspection deadline");
+        const timeout = setTimeout(() => {
+            timedOut = true;
+            fail(deadlineError());
+        }, DEFAULT_PERMISSION_EXEC_TIMEOUT_MS);
+        const finish = (outputClosed) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            clearTimeout(grace);
+            clearImmediate(missingPipes);
+            child.removeListener("exit", onExit);
+            child.removeListener("close", onClose);
+            child.removeListener("error", onChildError);
+            child.on("error", ignoreLateError);
+            const cleanupErrors = [];
+            for (const [stream, collect] of [[child.stdout, collectOutput], [child.stderr, collectErrors]]) {
+                if (!stream)
+                    continue;
+                stream.removeListener("data", collect);
+                stream.removeListener("error", fail);
+                stream.on("error", ignoreLateError);
+                if (!outputClosed) {
+                    try {
+                        stream.destroy();
+                    }
+                    catch (error) {
+                        cleanupErrors.push(error);
+                    }
+                }
+            }
+            if (!outputClosed && !processExitConfirmed) {
+                try {
+                    child.unref();
+                }
+                catch (error) {
+                    cleanupErrors.push(error);
+                }
+            }
+            if (failed || exitCode !== 0 || !outputClosed) {
+                reject(new WindowsSecurityCommandError(file, performance.now() - startedAt, {
+                    cause: failure, pid: child.pid ?? null, code: exitCode, signal: exitSignal, stderr: Buffer.concat(errors),
+                    processExitConfirmed, outputClosed, terminationSignalSent, terminationError, cleanupErrors,
+                    ...(operation === "create" ? { creationOutcome: "unconfirmed" } : {}),
+                }, timedOut));
+            }
+            else {
+                try {
+                    resolve(parseReply(Buffer.concat(output).toString("utf8"), operation));
+                }
+                catch (error) {
+                    reject(error);
+                }
+            }
+            output.length = 0;
+            errors.length = 0;
+        };
+        const fail = (error) => {
+            if (settled)
+                return;
+            if (!failed) {
+                failed = true;
+                failure = error;
+            }
+            if (stopping)
+                return;
+            stopping = true;
+            clearTimeout(timeout);
+            // kill() can synchronously emit error, throw, or return false. None proves exit.
+            grace = setTimeout(() => finish(false), TERMINATION_GRACE_MS);
+            if (!processExitConfirmed) {
+                try {
+                    terminationSignalSent = child.kill("SIGKILL");
+                }
+                catch (error) {
+                    terminationError ??= error;
+                }
+            }
+        };
+        const collect = (chunks) => (chunk) => {
+            if (failed || settled)
+                return;
+            bytes += chunk.length;
+            if (bytes <= MAX_OUTPUT_BYTES)
+                chunks.push(chunk);
+            else
+                fail(new Error("Windows security command exceeded its output budget"));
+        };
+        const collectOutput = collect(output);
+        const collectErrors = collect(errors);
+        const onChildError = (error) => {
+            if (settled)
+                return;
+            if (stopping)
+                terminationError ??= error;
+            else
+                fail(error);
+        };
+        const onExit = (code, signal) => {
+            processExitConfirmed = true;
+            exitCode = code;
+            exitSignal = signal;
+        };
+        const onClose = (code, signal) => {
+            onExit(code, signal);
+            if (!failed && performance.now() - startedAt >= DEFAULT_PERMISSION_EXEC_TIMEOUT_MS) {
+                timedOut = true;
+                failed = true;
+                failure = deadlineError();
+            }
+            finish(true);
+        };
+        child.on("error", onChildError);
+        child.once("exit", onExit);
+        // Success still joins exit and both pipes. Failure releases only owned endpoints
+        // after grace; the child inherited its own HANDLE, independent of the caller fd.
+        child.once("close", onClose);
+        child.stdout?.on("error", fail);
+        child.stderr?.on("error", fail);
+        child.stdout?.on("data", collectOutput);
+        child.stderr?.on("data", collectErrors);
+        if (!child.stdout || !child.stderr) {
+            // Node reports spawn errors on nextTick, which can follow the current microtask.
+            missingPipes = setImmediate(() => { if (!failed && !settled)
+                fail(new Error("Windows security command output pipes are unavailable")); });
+        }
+    });
+}
+export function readWindowsSecurityFactsCommand(targetPath) {
+    return parseWindowsSecurityCommandFacts(executeSync("path", { targetPath }));
+}
+export async function inspectWindowsDescriptorCommand(fd) {
+    const response = await execute("descriptor", { fd });
+    if (!record(response) || typeof response.identity !== "string") {
+        unverified("Windows security command returned incomplete handle facts");
+    }
+    return { identity: response.identity, security: parseWindowsSecurityCommandFacts(response.security) };
+}
+export async function createPrivateWindowsDirectoryCommand(targetPath, expectedParentIdentity) {
+    return fullIdentityReceipt(await execute("create", { targetPath, expectedParentIdentity }));
+}
+export function createPrivateWindowsDirectoryCommandSync(targetPath, expectedParentIdentity) {
+    return fullIdentityReceipt(executeSync("create", { targetPath, expectedParentIdentity }));
+}
+function fullIdentityReceipt(response, expected) {
+    if (!record(response) || !isFullIdentity(response.identity)) {
+        unverified("Windows security command returned an incomplete file identity");
+    }
+    if (expected !== undefined && response.identity !== expected) {
+        throw new FsSafeError("path-mismatch", "Windows security command observed a different file");
+    }
+    return { identity: response.identity };
+}
+export function inspectWindowsDirectoryCommandSync(targetPath, requirePrivate) {
+    return fullIdentityReceipt(executeSync("directory", { targetPath, requirePrivate }));
+}
+export async function inspectWindowsDirectoryCommand(targetPath, requirePrivate) {
+    return fullIdentityReceipt(await execute("directory", { targetPath, requirePrivate }));
+}
+export function protectPrivateWindowsFileCommandSync(fd, targetPath, expectedParentIdentity) {
+    assertIdentity(expectedParentIdentity);
+    return fullIdentityReceipt(executeSync("protect-file", { fd, targetPath, expectedParentIdentity }));
+}
+export async function protectPrivateWindowsFileCommand(fd, targetPath, expectedParentIdentity) {
+    assertIdentity(expectedParentIdentity);
+    return fullIdentityReceipt(await execute("protect-file", { fd, targetPath, expectedParentIdentity }));
+}
+export function verifyPrivateWindowsFileCommandSync(fd, targetPath, expectedFileIdentity, expectedParentIdentity, expectedLinks = 1) {
+    assertIdentity(expectedFileIdentity);
+    assertIdentity(expectedParentIdentity);
+    fullIdentityReceipt(executeSync("verify-file", {
+        fd, targetPath, expectedFileIdentity, expectedParentIdentity, expectedLinks,
+    }), expectedFileIdentity);
+}
+export async function verifyPrivateWindowsFileCommand(fd, targetPath, expectedFileIdentity, expectedParentIdentity, expectedLinks = 1) {
+    assertIdentity(expectedFileIdentity);
+    assertIdentity(expectedParentIdentity);
+    fullIdentityReceipt(await execute("verify-file", {
+        fd, targetPath, expectedFileIdentity, expectedParentIdentity, expectedLinks,
+    }), expectedFileIdentity);
+}

package/dist/windows-security-facts.d.ts

@@ -0,0 +1,6 @@
+import type { NativeWindowsSecurityFacts } from "./native-binding.js";
+/** Raw reporting retains unknown flag bits; secure admission validates them below. */
+export declare function parseWindowsSecurityCommandFacts(value: unknown): NativeWindowsSecurityFacts;
+/** Native and command observations share the same fail-closed admission policy. */
+export declare function validateSecureWindowsSecurityFacts(value: unknown): NativeWindowsSecurityFacts;
+//# sourceMappingURL=windows-security-facts.d.ts.map

package/dist/windows-security-facts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"windows-security-facts.d.ts","sourceRoot":"","sources":["../src/windows-security-facts.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAmC,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAmFvG,sFAAsF;AACtF,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,OAAO,GAAG,0BAA0B,CAU3F;AAED,mFAAmF;AACnF,wBAAgB,kCAAkC,CAAC,KAAK,EAAE,OAAO,GAAG,0BAA0B,CAoB7F"}

package/dist/windows-security-facts.js

@@ -0,0 +1,108 @@
+import { FsSafeError } from "./errors.js";
+const SID_RE = /^s-\d+-\d+(?:-\d+)+$/;
+const SYSTEM_SID = "s-1-5-18";
+const ADMINISTRATORS_SID = "s-1-5-32-544";
+const WORLD_SIDS = new Set([
+    "s-1-1-0", "s-1-5-11", "s-1-5-32-545", "s-1-5-7",
+    "s-1-5-32-546", "s-1-5-4", "s-1-5-2",
+]);
+function unverified(message) {
+    throw new FsSafeError("permission-unverified", message);
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function uint32(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 0xffff_ffff;
+}
+function validateAce(value, allowUnknownFlags) {
+    if (!record(value) || typeof value.sid !== "string" || !SID_RE.test(value.sid) ||
+        !uint32(value.mask) || (value.aceType !== "allow" && value.aceType !== "deny") ||
+        !record(value.flags))
+        return false;
+    const { raw } = value.flags;
+    if (!uint32(raw) || (raw & ~(allowUnknownFlags ? 0xff : 0xdf)) !== 0)
+        return false;
+    const fields = [
+        ["objectInherit", 0x01], ["containerInherit", 0x02],
+        ["noPropagateInherit", 0x04], ["inheritOnly", 0x08], ["inherited", 0x10],
+        ["successfulAccess", 0x40], ["failedAccess", 0x80],
+    ];
+    const flags = value.flags;
+    return fields.every(([field, bit]) => typeof flags[field] === "boolean" && flags[field] === ((raw & bit) !== 0));
+}
+function validateDescriptor(value, allowUnknownFlags) {
+    if (!record(value) || typeof value.ownerSid !== "string" || !SID_RE.test(value.ownerSid) ||
+        typeof value.currentUserSid !== "string" || !SID_RE.test(value.currentUserSid) ||
+        typeof value.daclPresent !== "boolean" || typeof value.isLocal !== "boolean" ||
+        typeof value.aceListComplete !== "boolean" || !Array.isArray(value.unsupportedAceTypes) ||
+        !value.unsupportedAceTypes.every(uint32) || !Array.isArray(value.aces) ||
+        !value.aces.every(ace => validateAce(ace, allowUnknownFlags))) {
+        unverified("Windows descriptor ACL facts were malformed");
+    }
+    if ((!value.daclPresent && value.aces.length !== 0) ||
+        (value.aceListComplete && value.unsupportedAceTypes.length !== 0)) {
+        unverified("Windows descriptor DACL facts were inconsistent");
+    }
+    return value;
+}
+function summarize(facts) {
+    const ownerClass = facts.ownerSid === facts.currentUserSid ? "current-user"
+        : facts.ownerSid === SYSTEM_SID ? "system"
+            : facts.ownerSid === ADMINISTRATORS_SID ? "administrators" : "foreign";
+    let worldReadable = !facts.daclPresent;
+    let worldWritable = !facts.daclPresent;
+    let groupReadable = false;
+    let groupWritable = false;
+    const trusted = new Set([facts.currentUserSid, SYSTEM_SID, ADMINISTRATORS_SID]);
+    for (const ace of facts.aces) {
+        if (ace.aceType !== "allow" || ace.flags.inheritOnly || trusted.has(ace.sid))
+            continue;
+        // Generic and file-specific read/write, delete, and security-control rights.
+        const canRead = (ace.mask & 0x9000_0089) !== 0;
+        const canWrite = (ace.mask & 0x500d_0156) !== 0;
+        if (WORLD_SIDS.has(ace.sid)) {
+            worldReadable ||= canRead;
+            worldWritable ||= canWrite;
+        }
+        else {
+            groupReadable ||= canRead;
+            groupWritable ||= canWrite;
+        }
+    }
+    return { ownerClass, worldReadable, worldWritable, groupReadable, groupWritable };
+}
+/** Raw reporting retains unknown flag bits; secure admission validates them below. */
+export function parseWindowsSecurityCommandFacts(value) {
+    const facts = validateDescriptor(value, true);
+    if (!record(value) || typeof value.daclProtected !== "boolean") {
+        unverified("Windows security command returned malformed descriptor facts");
+    }
+    return {
+        ...facts,
+        ...summarize(facts),
+        fallbackRequired: !facts.isLocal || !facts.aceListComplete,
+    };
+}
+/** Native and command observations share the same fail-closed admission policy. */
+export function validateSecureWindowsSecurityFacts(value) {
+    const descriptor = validateDescriptor(value, false);
+    const facts = value;
+    const summary = summarize(descriptor);
+    const booleans = ["worldWritable", "groupWritable", "worldReadable", "groupReadable", "fallbackRequired"];
+    if (!booleans.every(field => typeof facts[field] === "boolean") ||
+        typeof facts.ownerClass !== "string") {
+        unverified("Windows descriptor ACL facts were malformed");
+    }
+    if (facts.ownerClass !== summary.ownerClass) {
+        unverified("Windows descriptor owner facts were inconsistent");
+    }
+    if (facts.fallbackRequired || !facts.isLocal || !facts.aceListComplete || facts.unsupportedAceTypes.length !== 0) {
+        unverified("Windows descriptor ACL facts were incomplete or unsupported");
+    }
+    if (facts.worldReadable !== summary.worldReadable || facts.worldWritable !== summary.worldWritable ||
+        facts.groupReadable !== summary.groupReadable || facts.groupWritable !== summary.groupWritable) {
+        unverified("Windows descriptor ACL summary was inconsistent");
+    }
+    return facts;
+}

package/docs/advanced.md

@@ -28,7 +28,8 @@ The exports group into a handful of themes. Each documented helper has its own p
 | `pathScope`, `PathScope`, `PathScopeOptions`, `PathScopeResolveOptions` | [path-scope.md](path-scope.md) | Absolute-path boundary helper with `Result`-shaped returns. |
 | `ensureDirectoryWithinRoot` | [path-scope.md](path-scope.md#ensuredir-rel-options) | Create a directory while enforcing the root boundary; same result contract as `pathScope().ensureDir()`. |
 | `resolvePathWithinRoot`, `resolvePathsWithinRoot` | – | Resolve one or many relative paths against a trusted root. |
-| `resolveExistingPathsWithinRoot`, `resolveStrictExistingPathsWithinRoot` | – | Same, but require the targets to exist. |
+| `resolveExistingPathsWithinRoot` | – | Validate existing regular files inside the root, while allowing missing paths. |
+| `resolveStrictExistingPathsWithinRoot` | – | Require every target to exist as a regular non-symlink file inside the root. |
 | `resolveWritablePathWithinRoot` | – | Resolve a write target inside a root. |
 | `resolveRootPath`, `resolveRootPathSync`, `ResolvedRootPath`, `ROOT_PATH_ALIAS_POLICIES`, `RootPathAliasPolicy` | – | Resolve a root directory honoring alias policy. |
 | `resolvePathViaExistingAncestorSync` | – | Walk to an existing ancestor for paths whose tail does not yet exist. |
@@ -68,8 +69,9 @@ Operational filesystem failures such as permissions or I/O errors are rethrown.
 | Export | Page | Notes |
 |---|---|---|
 | `readFileDescriptorBounded`, `readFileDescriptorBoundedSync`, `readFileHandleBounded` | – | Incremental whole-file reads for already-open descriptors/handles. They consume at most `maxBytes + 1`, do not close the input, and throw `FsSafeError("too-large")` on overflow. |
+| `createDirectory`, `createDirectorySync`, `createFileSync` | [Exclusive leaf creation](creation.md) | Create one exclusive entry under an existing trusted parent, optionally with private permissions; file creation returns an owned disposable descriptor. |
 | `readFileWindowFully`, `readFileWindowFullySync`, `ReadFileWindowOptions` | [positional-read.md](positional-read.md) | Fill a caller-owned buffer at an explicit file position, completing short reads and returning the EOF count without moving or closing the descriptor. |
-| `copyFileHandle`, `CopyFileHandleOptions` | [copy.md](copy.md#borrowed-filehandle-transfers) | Copy caller-owned regular-file handles from position zero with byte limits, settled cancellation, and a synchronous source observer; preserves cursors and leaves publication and cleanup to the caller. |
+| `copyFileHandle`, `copyFileDescriptorSync`, `CopyFileHandleOptions` | [copy.md](copy.md#borrowed-filehandle-transfers) | Copy caller-owned regular files through async handles or sync descriptors from position zero with byte limits and synchronous callbacks; preserves cursors and leaves publication and cleanup to the caller. |
 | `overwriteFileHandle`, `OverwriteFileHandleOptions` | [in-place-write.md](in-place-write.md) | Overwrite a borrowed read/write handle with prefix-only preparation and best-effort rollback; preserves its inode, cursor, and caller-owned lifetime. |
 | `openRootFile`, `openRootFileSync`, `canUseRootFileOpen`, `matchRootFileOpenFailure`, related types | – | Low-level root-bounded open; rejects every symlink component by default, with `symlinks: "follow-parents-within-root"` for contained parent aliases or `"follow-within-root"` for final links too. |
 | `appendRegularFile`, `appendRegularFileSync`, `readRegularFile`, `readRegularFileSync`, `statRegularFile`, `statRegularFileSync`, `resolveRegularFileAppendFlags`, `AppendRegularFileOptions`, `RegularFileStatResult` | [regular-file.md](regular-file.md) | Type-checked regular-file I/O. |