@openclaw/fs-safe 0.4.5 → 0.4.7

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## 0.4.7 - 2026-07-24
+
+### Features
+
+- Add `@openclaw/fs-safe/durability` with identity-pinned directory handles,
+  explicit strict sync outcomes, synchronous and best-effort variants, and
+  durable nested-directory creation through every new parent edge.
+
+### Security and Correctness
+
+- Reject final symlinks, FIFOs, non-directories, canonical-path drift, and
+  descriptor/path identity replacement before or after directory sync.
+- Propagate POSIX directory synchronization failures while classifying known
+  unsupported Windows directory flushing only after revalidating the target;
+  directory-open access failures remain strict.
+- Route sibling-temp, root, and pinned-write best-effort parent synchronization
+  through the shared guarded primitive instead of maintaining divergent implementations.
+
+### Docs and Tooling
+
+- Document directory receipts, pin lifecycle, platform outcomes, custom
+  creation callbacks, and the boundary between filesystem durability and
+  application commit protocols.
+
+## 0.4.6 - 2026-07-24
+
+### Highlights
+
+- Reject foreign-owned or unverifiable Windows files in secure reads while
+  preserving supported trusted local owners and exact extended drive paths.
+
+### Security and Correctness
+
+- Report Windows owner SIDs and whether the owner is the current user,
+  LocalSystem, or built-in Administrators so credential-bearing executable
+  checks can reject foreign-owned paths even when their visible DACL is
+  read-only. Secure reads enforce the result and remote filesystems fail
+  closed.
+- Read Windows owner and DACL data through the underlying .NET security
+  descriptor APIs so verification does not depend on PowerShell security-module
+  autoloading.
+- Invoke `icacls.exe` with its supported path-only inspection syntax and use
+  the live Windows user/domain environment for named ACE classification, so
+  ACL verification works on supported Windows hosts instead of failing on the
+  invalid `/sid` argument.
+- Normalize trailing Windows install-root separators with a bounded linear
+  scan so library-provided environment maps cannot trigger regex backtracking.
+
+### Docs and Tooling
+
+- Add the public repository governance baseline, pinned CodeQL analysis,
+  package tarball/import validation, and protected tag-driven npm trusted
+  publishing with provenance and changelog-derived GitHub releases.
+- Let tag-driven publishing continue from an expected registry miss into npm
+  trusted publishing instead of exiting before the publish attempt.
+- Publish the generated tarball through an explicit relative path so npm treats
+  it as a local artifact instead of GitHub repository shorthand.
+
 ## 0.4.5 - 2026-07-20
 
 ### Highlights

package/README.md

@@ -26,7 +26,7 @@ Full docs and reference at **[fs-safe.io](https://fs-safe.io)**.
 
 ## Contents
 
-[Why this exists](#why-this-exists) · [Not a sandbox](#not-a-sandbox) · [Install](#install) · [Quick start](#quick-start) · [Reading](#reading) · [Subpaths](#subpaths) · [Failure semantics](#failure-semantics-in-the-name) · [Atomic writes](#atomic-writes) · [External outputs](#external-outputs) · [Stores](#stores) · [Secure absolute reads](#secure-absolute-file-reads) · [Walking](#directory-walking) · [Archive extraction](#archive-extraction) · [Path scopes](#advanced-path-scopes) · [Errors](#errors) · [Safety model](#safety-model) · [Limitations](#limitations)
+[Why this exists](#why-this-exists) · [Not a sandbox](#not-a-sandbox) · [Install](#install) · [Quick start](#quick-start) · [Reading](#reading) · [Subpaths](#subpaths) · [Failure semantics](#failure-semantics-in-the-name) · [Directory durability](#directory-durability) · [Atomic writes](#atomic-writes) · [External outputs](#external-outputs) · [Stores](#stores) · [Secure absolute reads](#secure-absolute-file-reads) · [Walking](#directory-walking) · [Archive extraction](#archive-extraction) · [Path scopes](#advanced-path-scopes) · [Errors](#errors) · [Safety model](#safety-model) · [Limitations](#limitations)
 
 ## Why this exists
 
@@ -189,6 +189,7 @@ that OpenClaw needs to compose higher-level APIs are grouped under
 | `@openclaw/fs-safe/store` | `fileStore`, `fileStoreSync`, and `jsonStore` |
 | `@openclaw/fs-safe/secret` | strict and try-style secret file read/write helpers |
 | `@openclaw/fs-safe/atomic` | `replaceFileAtomic`, `replaceFileAtomicSync`, `replaceDirectoryAtomic`, `movePathWithCopyFallback` |
+| `@openclaw/fs-safe/durability` | pinned directory identities, strict and best-effort directory sync, durable nested-directory creation |
 | `@openclaw/fs-safe/temp` | `tempWorkspace`, `tempWorkspaceSync`, `withTempWorkspace`, `resolveSecureTempRoot` |
 | `@openclaw/fs-safe/secure-file` | fd-pinned absolute file reads with owner, mode, ACL, trusted-dir, size, and timeout checks |
 | `@openclaw/fs-safe/file-lock` | `acquireFileLock`, `withFileLock`, `createFileLockManager`, and related lock types |
@@ -216,6 +217,35 @@ performs the root-bounded open and JSON object validation in one step. Use
 `readRootStructuredFileSync()` when the parser lives outside fs-safe, such as
 JSON5-backed plugin manifests.
 
+## Directory durability
+
+```ts
+import { ensureDurableDirectory, pinDirectory } from "@openclaw/fs-safe/durability";
+
+const receipt = await ensureDurableDirectory({
+  directoryPath: "/srv/backups/sqlite",
+  mode: 0o700,
+});
+const pinned = await pinDirectory(receipt);
+try {
+  await publishSnapshot();
+  const outcome = await pinned.sync();
+  // `unsupported` is explicit on platforms without directory flushing.
+  console.log(outcome.status);
+} finally {
+  await pinned.close();
+}
+```
+
+The durability subpath pins a directory descriptor to its pathname identity,
+detects symlink/FIFO/replacement races, and synchronizes every new parent edge
+when creating a nested directory. Strict sync propagates real I/O failures and
+reports known Windows directory-flush limitations explicitly. Separate
+best-effort helpers preserve operations that do not promise crash durability.
+
+See [Directory durability](docs/durability.md) for the receipt, pin lifecycle,
+creation callback, and platform contract.
+
 ## Atomic writes
 
 `replaceFileAtomic()` writes a sibling temp file, optionally fsyncs it, and renames it over the destination. Mode preservation, rename retry / copy fallback on `EPERM`, parent-directory fsync, and a `beforeRename` hook for backup or observer flows are all opt-in. `movePathWithCopyFallback()` stages cross-device moves before commit and removes only the copied source entries, so concurrent source additions or replacements are preserved.

package/SECURITY.md

@@ -1,12 +1,45 @@
 # Security Policy
 
-`@openclaw/fs-safe` is a filesystem-safety library, so potential boundary bypasses should be reported privately first.
+If you believe you found a security issue in `@openclaw/fs-safe`, report it
+privately.
 
-Email security reports to Peter Steinberger at `steipete@gmail.com` with:
+## Reporting
 
-- affected version or commit
-- platform and filesystem details
-- minimal reproduction steps
-- expected impact
+Open a private report through
+[GitHub Security Advisories](https://github.com/openclaw/fs-safe/security/advisories/new)
+or email `security@openclaw.ai`.
 
-Please do not open a public issue for traversal, symlink, hardlink, archive extraction, or credential-file bugs until we have coordinated disclosure.
+Include:
+
+1. affected version or commit
+2. Node.js version, operating system, filesystem, and mount details
+3. minimal reproduction
+4. demonstrated impact
+5. suggested remediation, if known
+
+Do not open a public issue until maintainers have coordinated disclosure.
+
+## Scope
+
+Security issues in scope generally include:
+
+- traversal or root-confinement bypasses
+- symlink, hardlink, rename, or identity-swap races that cross a documented
+  filesystem boundary
+- archive extraction outside the intended destination
+- unsafe secret-file, permission, ownership, or temporary-file behavior
+- package or release-pipeline compromise affecting the published package
+
+Reports must demonstrate a concrete boundary bypass or impact. Applications
+remain responsible for operating-system isolation, authorization, and choosing
+trusted root directories unless this package documents and fails to enforce a
+specific invariant.
+
+## Operational Guidance
+
+- Keep `@openclaw/fs-safe`, Node.js, and optional archive dependencies current.
+- Treat pathnames and archive contents as untrusted.
+- Use OS-level sandboxing when the threat model includes a hostile process.
+- Pin and review dependency updates before publishing.
+
+There is currently no paid bug bounty program.

package/dist/directory-durability.d.ts

@@ -0,0 +1,44 @@
+import { type Stats } from "node:fs";
+import { type FileIdentityStat } from "./file-identity.js";
+export type DirectorySyncOutcome = {
+    status: "synced";
+} | {
+    status: "unsupported";
+    code?: string;
+};
+export type DirectoryReceipt = {
+    path: string;
+    realPath: string;
+    identity: Stats;
+};
+export type DurableDirectoryReceipt = DirectoryReceipt & {
+    parentSync: DirectorySyncOutcome | {
+        status: "not-needed";
+    };
+};
+export type PinnedDirectory = {
+    readonly receipt: DirectoryReceipt;
+    assertCurrent(): Promise<void>;
+    sync(): Promise<DirectorySyncOutcome>;
+    close(): Promise<void>;
+};
+export type EnsureDurableDirectoryOptions = {
+    directoryPath: string;
+    label?: string;
+    mode?: number;
+    expectedExistingIdentity?: FileIdentityStat;
+    create?: (directoryPath: string) => Promise<void>;
+};
+export declare function pinDirectory(directory: string | DirectoryReceipt, options?: {
+    label?: string;
+}): Promise<PinnedDirectory>;
+export declare function syncDirectory(directory: string | DirectoryReceipt, options?: {
+    label?: string;
+}): Promise<DirectorySyncOutcome>;
+export declare function syncDirectorySync(directory: string | DirectoryReceipt, options?: {
+    label?: string;
+}): DirectorySyncOutcome;
+export declare function syncDirectoryBestEffort(directoryPath: string): Promise<void>;
+export declare function syncDirectoryBestEffortSync(directoryPath: string): void;
+export declare function ensureDurableDirectory(options: EnsureDurableDirectoryOptions): Promise<DurableDirectoryReceipt>;
+//# sourceMappingURL=directory-durability.d.ts.map

package/dist/directory-durability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory-durability.d.ts","sourceRoot":"","sources":["../src/directory-durability.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAM7C,OAAO,EAAoB,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE7E,MAAM,MAAM,oBAAoB,GAC5B;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,GACpB;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7C,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,KAAK,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,gBAAgB,GAAG;IACvD,UAAU,EAAE,oBAAoB,GAAG;QAAE,MAAM,EAAE,YAAY,CAAA;KAAE,CAAC;CAC7D,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACtC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wBAAwB,CAAC,EAAE,gBAAgB,CAAC;IAC5C,MAAM,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD,CAAC;AAgKF,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,GAAG,gBAAgB,EACpC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,OAAO,CAAC,eAAe,CAAC,CAa1B;AAED,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,GAAG,gBAAgB,EACpC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,OAAO,CAAC,oBAAoB,CAAC,CAmB/B;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,GAAG,gBAAgB,EACpC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,oBAAoB,CAuCtB;AAED,wBAAsB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAElF;AAED,wBAAgB,2BAA2B,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAMvE;AAuBD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,uBAAuB,CAAC,CA8ElC"}

package/dist/directory-durability.js

@@ -0,0 +1,299 @@
+import fsSync, {} from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { ensureAbsoluteDirectory } from "./absolute-path.js";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentity } from "./file-identity.js";
+function directoryOpenFlags() {
+    if (process.platform === "win32") {
+        return "r";
+    }
+    return (fsSync.constants.O_RDONLY |
+        fsSync.constants.O_DIRECTORY |
+        fsSync.constants.O_NOFOLLOW |
+        fsSync.constants.O_NONBLOCK);
+}
+function isWindowsDirectorySyncUnsupported(error) {
+    if (process.platform !== "win32") {
+        return false;
+    }
+    const code = error.code;
+    return (code === "EACCES" ||
+        code === "EINVAL" ||
+        code === "EISDIR" ||
+        code === "ENOSYS" ||
+        code === "ENOTSUP" ||
+        code === "EPERM");
+}
+function isWindowsDirectoryOpenUnsupported(error) {
+    if (process.platform !== "win32") {
+        return false;
+    }
+    const code = error.code;
+    return code === "EINVAL" || code === "EISDIR" || code === "ENOSYS" || code === "ENOTSUP";
+}
+function unsupportedOutcome(error) {
+    const code = error.code;
+    return code ? { status: "unsupported", code } : { status: "unsupported" };
+}
+function assertDirectory(identity, pathname, label) {
+    if (identity.isSymbolicLink() || !identity.isDirectory()) {
+        throw new FsSafeError("not-file", `${label} must be a real directory: ${pathname}`);
+    }
+}
+async function createDirectoryReceipt(directoryPath, label) {
+    const resolvedPath = path.resolve(directoryPath);
+    const identity = await fs.lstat(resolvedPath);
+    assertDirectory(identity, resolvedPath, label);
+    return {
+        path: resolvedPath,
+        realPath: await fs.realpath(resolvedPath),
+        identity,
+    };
+}
+function createDirectoryReceiptSync(directoryPath, label) {
+    const resolvedPath = path.resolve(directoryPath);
+    const identity = fsSync.lstatSync(resolvedPath);
+    assertDirectory(identity, resolvedPath, label);
+    return {
+        path: resolvedPath,
+        realPath: fsSync.realpathSync(resolvedPath),
+        identity,
+    };
+}
+async function assertDirectoryReceiptCurrent(receipt, label) {
+    const currentIdentity = await fs.lstat(receipt.path);
+    assertDirectory(currentIdentity, receipt.path, label);
+    if (!sameFileIdentity(receipt.identity, currentIdentity) ||
+        (await fs.realpath(receipt.path)) !== receipt.realPath) {
+        throw new FsSafeError("path-mismatch", `${label} changed during durable directory operation: ${receipt.path}`);
+    }
+}
+function assertDirectoryReceiptCurrentSync(receipt, label) {
+    const currentIdentity = fsSync.lstatSync(receipt.path);
+    assertDirectory(currentIdentity, receipt.path, label);
+    if (!sameFileIdentity(receipt.identity, currentIdentity) ||
+        fsSync.realpathSync(receipt.path) !== receipt.realPath) {
+        throw new FsSafeError("path-mismatch", `${label} changed during durable directory operation: ${receipt.path}`);
+    }
+}
+async function assertOpenDirectoryCurrent(handle, receipt, label) {
+    const openedIdentity = await handle.stat();
+    assertDirectory(openedIdentity, receipt.path, label);
+    if (!sameFileIdentity(receipt.identity, openedIdentity)) {
+        throw new FsSafeError("path-mismatch", `${label} handle changed during directory sync: ${receipt.path}`);
+    }
+    await assertDirectoryReceiptCurrent(receipt, label);
+}
+class PinnedDirectoryImpl {
+    receipt;
+    #handle;
+    #label;
+    #closed = false;
+    constructor(handle, receipt, label) {
+        this.#handle = handle;
+        this.receipt = receipt;
+        this.#label = label;
+    }
+    async assertCurrent() {
+        if (this.#closed) {
+            throw new FsSafeError("helper-failed", `${this.#label} pin is already closed`);
+        }
+        await assertOpenDirectoryCurrent(this.#handle, this.receipt, this.#label);
+    }
+    async sync() {
+        await this.assertCurrent();
+        try {
+            await this.#handle.sync();
+        }
+        catch (error) {
+            if (!isWindowsDirectorySyncUnsupported(error)) {
+                throw error;
+            }
+            await this.assertCurrent();
+            return unsupportedOutcome(error);
+        }
+        await this.assertCurrent();
+        return { status: "synced" };
+    }
+    async close() {
+        if (this.#closed) {
+            return;
+        }
+        this.#closed = true;
+        await this.#handle.close();
+    }
+}
+export async function pinDirectory(directory, options = {}) {
+    const label = options.label ?? "directory";
+    const receipt = typeof directory === "string" ? await createDirectoryReceipt(directory, label) : directory;
+    await assertDirectoryReceiptCurrent(receipt, label);
+    const handle = await fs.open(receipt.path, directoryOpenFlags());
+    try {
+        await assertOpenDirectoryCurrent(handle, receipt, label);
+        return new PinnedDirectoryImpl(handle, receipt, label);
+    }
+    catch (error) {
+        await handle.close().catch(() => undefined);
+        throw error;
+    }
+}
+export async function syncDirectory(directory, options = {}) {
+    const label = options.label ?? "directory";
+    const receipt = typeof directory === "string" ? await createDirectoryReceipt(directory, label) : directory;
+    let pinned;
+    try {
+        pinned = await pinDirectory(receipt, { label });
+    }
+    catch (error) {
+        if (!isWindowsDirectoryOpenUnsupported(error)) {
+            throw error;
+        }
+        await assertDirectoryReceiptCurrent(receipt, label);
+        return unsupportedOutcome(error);
+    }
+    try {
+        return await pinned.sync();
+    }
+    finally {
+        await pinned.close();
+    }
+}
+export function syncDirectorySync(directory, options = {}) {
+    const label = options.label ?? "directory";
+    const receipt = typeof directory === "string" ? createDirectoryReceiptSync(directory, label) : directory;
+    assertDirectoryReceiptCurrentSync(receipt, label);
+    let descriptor;
+    try {
+        descriptor = fsSync.openSync(receipt.path, directoryOpenFlags());
+    }
+    catch (error) {
+        if (!isWindowsDirectoryOpenUnsupported(error)) {
+            throw error;
+        }
+        assertDirectoryReceiptCurrentSync(receipt, label);
+        return unsupportedOutcome(error);
+    }
+    try {
+        const openedIdentity = fsSync.fstatSync(descriptor);
+        assertDirectory(openedIdentity, receipt.path, label);
+        if (!sameFileIdentity(receipt.identity, openedIdentity)) {
+            throw new FsSafeError("path-mismatch", `${label} handle changed during directory sync: ${receipt.path}`);
+        }
+        assertDirectoryReceiptCurrentSync(receipt, label);
+        try {
+            fsSync.fsyncSync(descriptor);
+        }
+        catch (error) {
+            if (!isWindowsDirectorySyncUnsupported(error)) {
+                throw error;
+            }
+            assertDirectoryReceiptCurrentSync(receipt, label);
+            return unsupportedOutcome(error);
+        }
+        assertDirectoryReceiptCurrentSync(receipt, label);
+        return { status: "synced" };
+    }
+    finally {
+        fsSync.closeSync(descriptor);
+    }
+}
+export async function syncDirectoryBestEffort(directoryPath) {
+    await syncDirectory(directoryPath).catch(() => undefined);
+}
+export function syncDirectoryBestEffortSync(directoryPath) {
+    try {
+        syncDirectorySync(directoryPath);
+    }
+    catch {
+        // Compatibility helper for operations whose primary write may remain usable.
+    }
+}
+async function findExistingAncestorReceipt(targetPath, label) {
+    let currentPath = path.resolve(targetPath);
+    while (true) {
+        try {
+            return await createDirectoryReceipt(currentPath, label);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+        }
+        const parentPath = path.dirname(currentPath);
+        if (parentPath === currentPath) {
+            throw new FsSafeError("not-found", `${label} has no existing directory ancestor`);
+        }
+        currentPath = parentPath;
+    }
+}
+export async function ensureDurableDirectory(options) {
+    const directoryPath = path.resolve(options.directoryPath);
+    const label = options.label ?? "directory";
+    const ancestorReceipt = await findExistingAncestorReceipt(directoryPath, label);
+    const targetExists = ancestorReceipt.path === directoryPath;
+    if (options.expectedExistingIdentity &&
+        (!targetExists || !sameFileIdentity(options.expectedExistingIdentity, ancestorReceipt.identity))) {
+        throw new FsSafeError("path-mismatch", `${label} changed before durable directory pinning: ${directoryPath}`);
+    }
+    const ancestor = await pinDirectory(ancestorReceipt, { label });
+    const pinnedDirectories = [ancestor];
+    try {
+        await ancestor.assertCurrent();
+        if (!targetExists) {
+            if (options.create) {
+                await options.create(directoryPath);
+            }
+            else {
+                const created = await ensureAbsoluteDirectory(directoryPath, {
+                    mode: options.mode,
+                    scopeLabel: label,
+                });
+                if (!created.ok) {
+                    throw created.error;
+                }
+            }
+        }
+        await ancestor.assertCurrent();
+        let currentPath = ancestor.receipt.path;
+        for (const segment of path
+            .relative(ancestor.receipt.path, directoryPath)
+            .split(path.sep)
+            .filter(Boolean)) {
+            currentPath = path.join(currentPath, segment);
+            pinnedDirectories.push(await pinDirectory(currentPath, { label }));
+        }
+        let parentSync = { status: "not-needed" };
+        for (let index = pinnedDirectories.length - 1; index > 0; index -= 1) {
+            const parent = pinnedDirectories[index - 1];
+            const child = pinnedDirectories[index];
+            if (!parent || !child) {
+                throw new FsSafeError("helper-failed", `${label} directory pin chain is incomplete`);
+            }
+            await child.assertCurrent();
+            try {
+                const outcome = await parent.sync();
+                if (outcome.status === "unsupported") {
+                    parentSync = outcome;
+                }
+                else if (parentSync.status === "not-needed") {
+                    parentSync = outcome;
+                }
+            }
+            catch (error) {
+                throw new FsSafeError("helper-failed", `${label} could not sync created directory edge ${child.receipt.path} through ${parent.receipt.path}`, { cause: error });
+            }
+            await child.assertCurrent();
+        }
+        const finalReceipt = pinnedDirectories.at(-1)?.receipt;
+        if (!finalReceipt) {
+            throw new FsSafeError("helper-failed", `${label} directory receipt is missing`);
+        }
+        await ancestor.assertCurrent();
+        await assertDirectoryReceiptCurrent(finalReceipt, label);
+        return { ...finalReceipt, parentSync };
+    }
+    finally {
+        await Promise.all(pinnedDirectories.toReversed().map(async (directory) => directory.close()));
+    }
+}

package/dist/durability.d.ts

@@ -0,0 +1,2 @@
+export { ensureDurableDirectory, pinDirectory, syncDirectory, syncDirectoryBestEffort, syncDirectoryBestEffortSync, syncDirectorySync, type DirectoryReceipt, type DirectorySyncOutcome, type DurableDirectoryReceipt, type EnsureDurableDirectoryOptions, type PinnedDirectory, } from "./directory-durability.js";
+//# sourceMappingURL=durability.d.ts.map

package/dist/durability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durability.d.ts","sourceRoot":"","sources":["../src/durability.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,YAAY,EACZ,aAAa,EACb,uBAAuB,EACvB,2BAA2B,EAC3B,iBAAiB,EACjB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,EAClC,KAAK,eAAe,GACrB,MAAM,2BAA2B,CAAC"}

package/dist/durability.js

@@ -0,0 +1 @@
+export { ensureDurableDirectory, pinDirectory, syncDirectory, syncDirectoryBestEffort, syncDirectoryBestEffortSync, syncDirectorySync, } from "./directory-durability.js";

package/dist/fsync.d.ts

@@ -1,2 +1,2 @@
-export declare function syncDirectoryBestEffort(dirPath: string): Promise<void>;
+export { syncDirectoryBestEffort } from "./directory-durability.js";
 //# sourceMappingURL=fsync.d.ts.map

package/dist/fsync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fsync.d.ts","sourceRoot":"","sources":["../src/fsync.ts"],"names":[],"mappings":"AAIA,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiB5E"}
+{"version":3,"file":"fsync.d.ts","sourceRoot":"","sources":["../src/fsync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/fsync.js

@@ -1,21 +1 @@
-import fsSync from "node:fs";
-import fs from "node:fs/promises";
-export async function syncDirectoryBestEffort(dirPath) {
-    if (process.platform === "win32") {
-        return;
-    }
-    let handle;
-    try {
-        const flags = fsSync.constants.O_RDONLY |
-            ("O_DIRECTORY" in fsSync.constants ? fsSync.constants.O_DIRECTORY : 0) |
-            ("O_NOFOLLOW" in fsSync.constants ? fsSync.constants.O_NOFOLLOW : 0);
-        handle = await fs.open(dirPath, flags);
-        await handle.sync();
-    }
-    catch {
-        // Some filesystems reject directory handles; keep the write usable there.
-    }
-    finally {
-        await handle?.close().catch(() => undefined);
-    }
-}
+export { syncDirectoryBestEffort } from "./directory-durability.js";

package/dist/local-file-access.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-file-access.d.ts","sourceRoot":"","sources":["../src/local-file-access.ts"],"names":[],"mappings":"AAWA,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEpE;AAED,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAMT;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAET;AAED,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,SAAS,GAAG,IAAI,CAIjF;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAmBzD;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMxE;AAED,wBAAgB,uBAAuB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAgB3E"}
+{"version":3,"file":"local-file-access.d.ts","sourceRoot":"","sources":["../src/local-file-access.ts"],"names":[],"mappings":"AAWA,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEpE;AAED,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAeT;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAET;AAED,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,SAAS,GAAG,IAAI,CAIjF;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAmBzD;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMxE;AAED,wBAAgB,uBAAuB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAgB3E"}

package/dist/local-file-access.js

@@ -14,7 +14,15 @@ export function isWindowsNetworkPath(filePath, platform = process.platform) {
         return false;
     }
     const normalized = filePath.replace(/\//g, "\\");
-    return normalized.startsWith("\\\\?\\UNC\\") || normalized.startsWith("\\\\");
+    const extendedDrive = normalized.length >= 7 &&
+        normalized.startsWith("\\\\?\\") &&
+        /^[a-z]$/i.test(normalized[4] ?? "") &&
+        normalized[5] === ":" &&
+        normalized[6] === "\\";
+    if (extendedDrive) {
+        return false;
+    }
+    return normalized.startsWith("\\\\");
 }
 export function isWindowsDriveLetterPath(filePath, platform = process.platform) {
     return platform === "win32" && /^[A-Za-z]:[\\/]/.test(filePath);

package/dist/permissions.d.ts

@@ -13,6 +13,12 @@ export type PermissionCheck = {
     groupWritable: boolean;
     worldReadable: boolean;
     groupReadable: boolean;
+    /** Canonical Windows owner SID when the owner query succeeds. */
+    ownerSid?: string;
+    /** Whether the Windows owner is the current user, LocalSystem, or Administrators. */
+    ownerTrusted?: boolean;
+    /** Owner-query failure detail when Windows ownership could not be verified. */
+    ownerError?: string;
     aclSummary?: string;
     error?: string;
 };
@@ -32,6 +38,8 @@ export type SafeStatResult = {
 };
 export type WindowsAclEntry = {
     principal: string;
+    /** Canonical principal SID when resolved from Windows. */
+    sid?: string;
     rights: string[];
     rawRights: string;
     canRead: boolean;
@@ -75,6 +83,9 @@ export declare function summarizeWindowsAcl(entries: WindowsAclEntry[], env?: No
 export declare function inspectWindowsAcl(targetPath: string, opts?: {
     env?: NodeJS.ProcessEnv;
     exec?: PermissionExec;
+    currentUserSid?: string;
+    principalSids?: Record<string, string>;
+    principalTranslationFailed?: boolean;
 }): Promise<WindowsAclSummary>;
 export declare function formatWindowsAclSummary(summary: WindowsAclSummary): string;
 export declare function formatIcaclsResetCommand(targetPath: string, opts: IcaclsResetCommandOptions): string;

package/dist/permissions.d.ts.map

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