@openclaw/fs-safe 0.15.0 → 0.16.0

package/dist/secure-file-windows.js

@@ -1,30 +1,12 @@
 import { FsSafeError } from "./errors.js";
 import { recordFileObservationFailure } from "./file-observation.js";
 import { getNativeBinding } from "./native.js";
+import { getFsSafeNativeConfig } from "./native-config.js";
+import { warnNativeFallback } from "./native-fallback-warning.js";
+import { inspectWindowsDescriptorCommand } from "./windows-security-command.js";
+import { validateSecureWindowsSecurityFacts } from "./windows-security-facts.js";
 const IDENTITY_RE = /^([0-9a-f]{8}):([0-9a-f]{16})$/;
-const SID_RE = /^s-\d+-\d+(?:-\d+)+$/;
-const OWNER_CLASSES = new Set(["current-user", "system", "administrators", "foreign"]);
 const TRUSTED_OWNER_CLASSES = new Set(["current-user", "system", "administrators"]);
-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",
-]);
-const GENERIC_READ = 0x8000_0000;
-const GENERIC_WRITE = 0x4000_0000;
-const GENERIC_ALL = 0x1000_0000;
-const DELETE_ACCESS = 0x0001_0000;
-const WRITE_DAC = 0x0004_0000;
-const WRITE_OWNER = 0x0008_0000;
-const FILE_READ_DATA = 0x0000_0001;
-const FILE_WRITE_DATA = 0x0000_0002;
-const FILE_APPEND_DATA = 0x0000_0004;
-const FILE_READ_EA = 0x0000_0008;
-const FILE_WRITE_EA = 0x0000_0010;
-const FILE_DELETE_CHILD = 0x0000_0040;
-const FILE_READ_ATTRIBUTES = 0x0000_0080;
-const FILE_WRITE_ATTRIBUTES = 0x0000_0100;
 function permissionUnverified(message, cause) {
     throw new FsSafeError("permission-unverified", message, cause === undefined ? {} : { cause });
 }
@@ -36,9 +18,6 @@ function identityMismatch() {
 function isRecord(value) {
     return typeof value === "object" && value !== null;
 }
-function isUint32(value) {
-    return typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 0xffff_ffff;
-}
 function parseIdentity(value) {
     if (typeof value !== "string")
         identityMismatch();
@@ -50,95 +29,6 @@ function parseIdentity(value) {
         ino: BigInt(`0x${match[2]}`),
     };
 }
-function validateFlags(value) {
-    if (!isRecord(value))
-        return false;
-    const raw = value.raw;
-    if (!isUint32(raw) || (raw & ~0xdf) !== 0)
-        return false;
-    const fields = [
-        ["objectInherit", 0x01], ["containerInherit", 0x02],
-        ["noPropagateInherit", 0x04], ["inheritOnly", 0x08], ["inherited", 0x10],
-        ["successfulAccess", 0x40], ["failedAccess", 0x80],
-    ];
-    return fields.every(([field, bit]) => typeof value[field] === "boolean" && value[field] === ((raw & bit) !== 0));
-}
-function validateAce(value) {
-    return isRecord(value) && typeof value.sid === "string" && SID_RE.test(value.sid) &&
-        isUint32(value.mask) && (value.aceType === "allow" || value.aceType === "deny") &&
-        validateFlags(value.flags);
-}
-function canRead(mask) {
-    return (mask & (GENERIC_ALL | GENERIC_READ | FILE_READ_DATA | FILE_READ_EA |
-        FILE_READ_ATTRIBUTES)) !== 0;
-}
-function canWrite(mask) {
-    return (mask & (GENERIC_ALL | GENERIC_WRITE | FILE_WRITE_DATA | FILE_APPEND_DATA |
-        FILE_WRITE_EA | FILE_WRITE_ATTRIBUTES | FILE_DELETE_CHILD | DELETE_ACCESS |
-        WRITE_DAC | WRITE_OWNER)) !== 0;
-}
-function expectedOwnerClass(facts) {
-    if (facts.ownerSid === facts.currentUserSid)
-        return "current-user";
-    if (facts.ownerSid === SYSTEM_SID)
-        return "system";
-    if (facts.ownerSid === ADMINISTRATORS_SID)
-        return "administrators";
-    return "foreign";
-}
-function validateSecurity(value) {
-    if (!isRecord(value))
-        permissionUnverified("Windows descriptor ACL facts were malformed");
-    const facts = value;
-    const booleans = [
-        "worldWritable", "groupWritable", "worldReadable", "groupReadable",
-        "fallbackRequired", "daclPresent", "isLocal", "aceListComplete",
-    ];
-    if (!booleans.every((field) => typeof facts[field] === "boolean") ||
-        typeof facts.ownerSid !== "string" || !SID_RE.test(facts.ownerSid) ||
-        typeof facts.currentUserSid !== "string" || !SID_RE.test(facts.currentUserSid) ||
-        typeof facts.ownerClass !== "string" || !OWNER_CLASSES.has(facts.ownerClass) ||
-        !Array.isArray(facts.unsupportedAceTypes) ||
-        !facts.unsupportedAceTypes.every(isUint32) ||
-        !Array.isArray(facts.aces) || !facts.aces.every(validateAce)) {
-        permissionUnverified("Windows descriptor ACL facts were malformed");
-    }
-    if (facts.ownerClass !== expectedOwnerClass(facts)) {
-        permissionUnverified("Windows descriptor owner facts were inconsistent");
-    }
-    if (facts.fallbackRequired || !facts.isLocal || !facts.aceListComplete ||
-        facts.unsupportedAceTypes.length !== 0) {
-        permissionUnverified("Windows descriptor ACL facts were incomplete or unsupported");
-    }
-    if (!facts.daclPresent && facts.aces.length !== 0) {
-        permissionUnverified("Windows descriptor DACL facts were inconsistent");
-    }
-    return facts;
-}
-function validatePermissionSummary(facts) {
-    let worldReadable = !facts.daclPresent;
-    let worldWritable = !facts.daclPresent;
-    let groupReadable = false;
-    let groupWritable = false;
-    const trustedSids = new Set([facts.currentUserSid, SYSTEM_SID, ADMINISTRATORS_SID]);
-    for (const ace of facts.aces) {
-        if (ace.aceType !== "allow" || ace.flags.inheritOnly || trustedSids.has(ace.sid))
-            continue;
-        const world = WORLD_SIDS.has(ace.sid);
-        if (world) {
-            worldReadable ||= canRead(ace.mask);
-            worldWritable ||= canWrite(ace.mask);
-        }
-        else {
-            groupReadable ||= canRead(ace.mask);
-            groupWritable ||= canWrite(ace.mask);
-        }
-    }
-    if (facts.worldReadable !== worldReadable || facts.worldWritable !== worldWritable ||
-        facts.groupReadable !== groupReadable || facts.groupWritable !== groupWritable) {
-        permissionUnverified("Windows descriptor ACL summary was inconsistent");
-    }
-}
 export function inspectSecureWindowsDescriptor(params) {
     let native;
     try {
@@ -158,14 +48,16 @@ export function inspectSecureWindowsDescriptor(params) {
     catch (cause) {
         permissionUnverified("Windows descriptor ACL verification failed", cause);
     }
+    return inspectDescriptorResult(params, result, "native");
+}
+function inspectDescriptorResult(params, result, mechanism) {
     if (!isRecord(result))
         permissionUnverified("Windows descriptor ACL facts were malformed");
     const observed = parseIdentity(result.identity);
     if (observed.dev !== params.identity.dev || observed.ino !== params.identity.ino) {
         identityMismatch();
     }
-    const facts = validateSecurity(result.security);
-    validatePermissionSummary(facts);
+    const facts = validateSecureWindowsSecurityFacts(result.security);
     return {
         ok: true,
         isSymlink: false,
@@ -179,8 +71,33 @@ export function inspectSecureWindowsDescriptor(params) {
         groupReadable: facts.groupReadable,
         ownerSid: facts.ownerSid,
         ownerTrusted: TRUSTED_OWNER_CLASSES.has(facts.ownerClass),
-        aclSummary: `native descriptor owner=${facts.ownerClass} world=` +
+        aclSummary: `${mechanism} descriptor owner=${facts.ownerClass} world=` +
             `${facts.worldReadable ? "r" : "-"}${facts.worldWritable ? "w" : "-"} ` +
             `group=${facts.groupReadable ? "r" : "-"}${facts.groupWritable ? "w" : "-"}`,
     };
 }
+/** Both mechanisms inspect the same borrowed handle; the caller owns its lifetime. */
+export async function inspectSecureWindowsFile(params) {
+    let native;
+    try {
+        native = getNativeBinding();
+    }
+    catch (cause) {
+        permissionUnverified("Windows descriptor ACL verification requires the matching native helper", cause);
+    }
+    if (typeof native?.inspectWindowsSecureFileHandle === "function") {
+        return inspectSecureWindowsDescriptor(params);
+    }
+    if (getFsSafeNativeConfig().mode === "require") {
+        permissionUnverified("Windows descriptor ACL verification requires an up-to-date native helper");
+    }
+    warnNativeFallback("windows-secure-file", "Windows descriptor ACL inspection uses a slower built-in system command.");
+    let result;
+    try {
+        result = await inspectWindowsDescriptorCommand(params.fd);
+    }
+    catch (cause) {
+        permissionUnverified("Windows descriptor ACL verification failed", cause);
+    }
+    return inspectDescriptorResult(params, result, "system-command");
+}

package/dist/secure-file.js

@@ -13,7 +13,7 @@ import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { realpathSync } from "./realpath.js";
 import { inspectPathPermissions, isGroupReadable, isGroupWritable, isWorldReadable, isWorldWritable, modeBits, } from "./permissions.js";
 import { inspectFileIdentity } from "./strict-file-identity.js";
-import { inspectSecureWindowsDescriptor } from "./secure-file-windows.js";
+import { inspectSecureWindowsFile } from "./secure-file-windows.js";
 import { scheduleTimeout } from "./timing.js";
 import { anchorWindowsDriveRelativePath, assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 function snapshotTrustedDirs(dirs) {
@@ -209,7 +209,7 @@ async function assertSecurePermissions(options, stat, realPath, identity, fd) {
     const platform = options.inject?.platform ?? process.platform;
     const permissions = platform === "win32"
         ? process.platform === "win32"
-            ? inspectSecureWindowsDescriptor({ fd, identity, stat })
+            ? await inspectSecureWindowsFile({ fd, identity, stat })
             : await inspectPathPermissions(realPath, options.inject)
         : inspectOpenedPermissions(stat, platform);
     const reason = permissions.error ? `: ${formatPermissionErrorDetail(permissions.error)}` : "";

package/dist/sidecar-lock-root.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock-root.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-root.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAGvD,wBAAsB,eAAe,CACnC,QAAQ,EAAE,IAAI,EACd,QAAQ,EAAE,MAAM,EAChB,kBAAkB,CAAC,EAAE,UAAU,GAAG,SAAS,EAC3C,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GACvC,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAyD5B"}
+{"version":3,"file":"sidecar-lock-root.d.ts","sourceRoot":"","sources":["../src/sidecar-lock-root.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAGvD,wBAAsB,eAAe,CACnC,QAAQ,EAAE,IAAI,EACd,QAAQ,EAAE,MAAM,EAChB,kBAAkB,CAAC,EAAE,UAAU,GAAG,SAAS,EAC3C,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GACvC,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CA0D5B"}

package/dist/sidecar-lock-root.js

@@ -61,7 +61,8 @@ export async function openSidecarRoot(lockRoot, relative, discardObservation, on
             }
             catch (probeError) {
                 if (!(probeError instanceof FsSafeError && probeError.code === "not-found") &&
-                    !probe.has(probeError, `stat-leaf-missing:${expectedRealPath}`))
+                    !probe.has(probeError, `stat-leaf-missing:${expectedRealPath}`) &&
+                    !probe.has(probeError, `stat-leaf-changed:${expectedRealPath}`))
                     throw probeError;
             }
             for (const { dir, stat } of parents)

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

@@ -1 +1 @@
-{"version":3,"file":"staged-directory.d.ts","sourceRoot":"","sources":["../src/staged-directory.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAEL,KAAK,4BAA4B,EACjC,KAAK,yBAAyB,EAE/B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAGhE,MAAM,MAAM,uBAAuB,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;AAErE,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,SAAS,EAAE,uBAAuB,CAAC;IACnC,WAAW,EAAE,4BAA4B,CAAC;IAC1C,IAAI,EAAE,WAAW,CAAC;IAClB,cAAc,CAAC,EAAE,yBAAyB,CAAC;IAC3C,kBAAkB,CAAC,IAAI,IAAI,CAAC;CAC7B,CAAC,CAAC;AAEH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,GAC7C,OAAO,CAKT;AAED,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,uBAAuB,CAY7F;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,uBAAuB,GAAG,WAAW,CAS1F;AASD,wBAAgB,6BAA6B,CAC3C,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,aAAa,GACtB,qBAAqB,CA2CvB;AAED,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,qBAAqB,GAC9B,WAAW,CAeb;AAED,wBAAgB,uCAAuC,CACrD,QAAQ,EAAE,qBAAqB,GAC9B,4BAA4B,CAoB9B;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,uBAAuB,CAAC;CAClC,CAiCA"}
+{"version":3,"file":"staged-directory.d.ts","sourceRoot":"","sources":["../src/staged-directory.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAGlE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAEL,KAAK,4BAA4B,EACjC,KAAK,yBAAyB,EAE/B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAGhE,MAAM,MAAM,uBAAuB,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;AAErE,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,SAAS,EAAE,uBAAuB,CAAC;IACnC,WAAW,EAAE,4BAA4B,CAAC;IAC1C,IAAI,EAAE,WAAW,CAAC;IAClB,cAAc,CAAC,EAAE,yBAAyB,CAAC;IAC3C,kBAAkB,CAAC,IAAI,IAAI,CAAC;CAC7B,CAAC,CAAC;AAEH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,GAC7C,OAAO,CAKT;AAED,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,uBAAuB,CAY7F;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,uBAAuB,GAAG,WAAW,CAS1F;AASD,wBAAgB,6BAA6B,CAC3C,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,aAAa,GACtB,qBAAqB,CA2CvB;AAED,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,qBAAqB,GAC9B,WAAW,CAeb;AAED,wBAAgB,uCAAuC,CACrD,QAAQ,EAAE,qBAAqB,GAC9B,4BAA4B,CAoB9B;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,uBAAuB,CAAC;CAClC,CAgCA"}

package/dist/staged-directory.js

@@ -1,5 +1,6 @@
 import fs, {} from "node:fs";
 import path from "node:path";
+import { directoryReceiptAuthority, ownDirectoryReceipt } from "./directory-receipt.js";
 import { FsSafeError } from "./errors.js";
 import { inspectDirectoryIdentitySync } from "./directory-guard.js";
 import { nativePolicyDirectoryObserver, NativePolicyDirectoryMismatch } from "./native-policy-directory-observation.js";
@@ -116,16 +117,15 @@ export function refreshPolicyStagedDirectoryObservation(captured) {
     return checkedMutationDirectory(captured.directory.path, canonicalPath, current);
 }
 export function openStagedDirectory(directory) {
-    // Copy supplied facts before any asynchronous work; receipts are not authority.
-    const pathname = resolvePathPreservingWindowsRoot(typeof directory === "string" ? directory : directory.path);
-    const expected = typeof directory === "string" ? undefined : {
-        realPath: directory.realPath, dev: directory.identity.dev, ino: directory.identity.ino,
-    };
+    const expected = typeof directory === "string"
+        ? undefined
+        : directoryReceiptAuthority(ownDirectoryReceipt(directory));
+    const pathname = resolvePathPreservingWindowsRoot(typeof directory === "string" ? directory : expected.path);
     const before = fs.lstatSync(pathname, { bigint: true });
     if (!before.isDirectory()) {
         throw new FsSafeError("not-file", "staging parent must be a real directory");
     }
-    if (expected && (!exactIdentityMatches(expected, before) || realpathSync(pathname) !== expected.realPath)) {
+    if (expected && (!exactIdentityMatches(expected.identity, before) || realpathSync(pathname) !== expected.realPath)) {
         throw new FsSafeError("path-mismatch", "stale staging directory receipt");
     }
     const fd = fs.openSync(pathname, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);

package/dist/staged-file-settlement.d.ts

@@ -0,0 +1,17 @@
+import type { BigIntStats } from "node:fs";
+import { FsSafeError } from "./errors.js";
+import type { StagedFileCleanupReceipt, StagedFileFailureDetails, StagedFilePublication, StagedFileReceipt } from "./staged-file-types.js";
+export declare function createStagedFileReceipt(directory: StagedFileReceipt["directory"], temporaryBasename: string, stat: BigIntStats): StagedFileReceipt;
+export declare function stagedFileFailure(error: unknown, details: StagedFileFailureDetails): FsSafeError;
+/** Finish owned cleanup and every close before surfacing publication evidence. */
+export declare function settleStagedFile(params: {
+    temporaryBasename: string;
+    publication: StagedFilePublication;
+    phase: StagedFileFailureDetails["phase"];
+    failure?: {
+        error: unknown;
+    };
+    cleanup: () => Promise<StagedFileCleanupReceipt["status"]>;
+    close: readonly (() => Promise<void> | void)[];
+}): Promise<void>;
+//# sourceMappingURL=staged-file-settlement.d.ts.map

package/dist/staged-file-settlement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staged-file-settlement.d.ts","sourceRoot":"","sources":["../src/staged-file-settlement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EACV,wBAAwB,EACxB,wBAAwB,EACxB,qBAAqB,EACrB,iBAAiB,EAClB,MAAM,wBAAwB,CAAC;AAEhC,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,iBAAiB,CAAC,WAAW,CAAC,EACzC,iBAAiB,EAAE,MAAM,EACzB,IAAI,EAAE,WAAW,GAChB,iBAAiB,CAUnB;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,wBAAwB,GAAG,WAAW,CAKhG;AAED,kFAAkF;AAClF,wBAAsB,gBAAgB,CAAC,MAAM,EAAE;IAC7C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,qBAAqB,CAAC;IACnC,KAAK,EAAE,wBAAwB,CAAC,OAAO,CAAC,CAAC;IACzC,OAAO,CAAC,EAAE;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;IAC7B,OAAO,EAAE,MAAM,OAAO,CAAC,wBAAwB,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC3D,KAAK,EAAE,SAAS,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;CAChD,GAAG,OAAO,CAAC,IAAI,CAAC,CAkChB"}

package/dist/staged-file-settlement.js

@@ -0,0 +1,57 @@
+import { FsSafeError } from "./errors.js";
+export function createStagedFileReceipt(directory, temporaryBasename, stat) {
+    return Object.freeze({
+        directory,
+        temporaryBasename,
+        identity: Object.freeze({
+            dev: stat.dev, ino: stat.ino, mode: Number(stat.mode & 4095n),
+            nlink: stat.nlink, size: stat.size, uid: Number(stat.uid), gid: Number(stat.gid),
+            mtimeNs: stat.mtimeNs, ctimeNs: stat.ctimeNs,
+        }),
+    });
+}
+export function stagedFileFailure(error, details) {
+    const code = error instanceof FsSafeError
+        ? error.code
+        : error?.code === "EEXIST" ? "already-exists" : "helper-failed";
+    return new FsSafeError(code, `staged file ${details.phase} failed`, { cause: error, details });
+}
+/** Finish owned cleanup and every close before surfacing publication evidence. */
+export async function settleStagedFile(params) {
+    const errors = params.failure ? [params.failure.error] : [];
+    let status;
+    try {
+        status = await params.cleanup();
+    }
+    catch (error) {
+        status = "failed";
+        errors.push(error);
+    }
+    let resources = "closed";
+    for (const close of params.close) {
+        try {
+            await close();
+        }
+        catch (error) {
+            resources = "close-failed";
+            errors.push(error);
+        }
+    }
+    const incomplete = status === "failed" || status === "preserved" || resources === "close-failed";
+    // A settled pre-publication failure retains the producer/authority rejection exactly.
+    if (!incomplete && (!params.failure || params.publication.status === "not-published"))
+        return;
+    const error = errors.length > 1 ? new AggregateError(errors, "staged operation and settlement failed")
+        : errors.length === 1 ? errors[0] : new FsSafeError("not-removable", "staged cleanup preserved an unverified entry");
+    const cleanup = Object.freeze({
+        temporaryBasename: params.temporaryBasename,
+        publication: params.publication,
+        status,
+        resources,
+    });
+    throw stagedFileFailure(error, {
+        phase: params.failure ? params.phase : "cleanup",
+        publication: params.publication,
+        cleanup,
+    });
+}

package/dist/windows-owner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"windows-owner.d.ts","sourceRoot":"","sources":["../src/windows-owner.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,wBAAwB,EAC9B,MAAM,sBAAsB,CAAC;AAI9B,MAAM,MAAM,gBAAgB,GAAG,CAC7B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,KACX,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEjD,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,IAAI,CAAC,EAAE,eAAe,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,wBAAwB,CAAC;IACvC,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC;AAqDF,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,EAAE,gBAAgB,CAAC;CACxB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAmD/B"}
+{"version":3,"file":"windows-owner.d.ts","sourceRoot":"","sources":["../src/windows-owner.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,wBAAwB,EAC9B,MAAM,sBAAsB,CAAC;AAI9B,MAAM,MAAM,gBAAgB,GAAG,CAC7B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,KACX,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEjD,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,IAAI,CAAC,EAAE,eAAe,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,wBAAwB,CAAC;IACvC,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC;AAsDF,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,EAAE,gBAAgB,CAAC;CACxB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAmD/B"}

package/dist/windows-owner.js

@@ -14,6 +14,7 @@ function windowsOwnerQueryCommand(targetPath) {
     const encodedPath = Buffer.from(targetPath, "utf8").toString("base64");
     return [
         "$ErrorActionPreference='Stop'",
+        "$env:PSModulePath=[IO.Path]::Combine($PSHOME,'Modules')",
         `$p=[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encodedPath}'))`,
         "$sections=[System.Security.AccessControl.AccessControlSections]::Access -bor [System.Security.AccessControl.AccessControlSections]::Owner",
         "$acl=if([IO.Directory]::Exists($p)){[IO.Directory]::GetAccessControl($p,$sections)}else{[IO.File]::GetAccessControl($p,$sections)}",
@@ -29,7 +30,7 @@ function windowsOwnerQueryCommand(targetPath) {
         "$raw=[System.Security.AccessControl.RawSecurityDescriptor]::new($acl.GetSecurityDescriptorBinaryForm(),0)",
         "$dacl=$raw.DiscretionaryAcl;$complete=$true",
         "$aces=@(foreach($ace in $dacl){if($ace -isnot [System.Security.AccessControl.CommonAce] -or $ace.IsCallback -or [int]$ace.AceType -notin @(0,1)){$complete=$false;continue};@{sid=$ace.SecurityIdentifier.Value;mask=([long]$ace.AccessMask -band 4294967295);deny=([int]$ace.AceType -eq 1);inheritOnly=([int]$ace.AceFlags -band 8) -ne 0}})",
-        "@{ownerSid=$ownerSid;currentUserSid=$currentSid;daclPresent=($null -ne $dacl);aces=$aces;complete=$complete;remote=$remote}|ConvertTo-Json -Depth 4 -Compress",
+        "@{ownerSid=$ownerSid;currentUserSid=$currentSid;daclPresent=($null -ne $dacl);aces=$aces;complete=$complete;remote=$remote}|Microsoft.PowerShell.Utility\\ConvertTo-Json -Depth 4 -Compress",
     ].join(";");
 }
 function parseWindowsAclFacts(parsed) {