@openclaw/fs-safe 0.18.0 → 0.18.1

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

@@ -1,8 +1,76 @@
-import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import fsSync, {} from "node:fs";
+import { inspectDirectoryIdentitySync, observeDirectoryIdentitySync } 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";
+import { recordFileObservationFailure } from "./file-observation.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+export const TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY = process.platform === "linux" || process.platform === "darwin";
+export function projectTempWorkspaceNumericIdentity(identity) {
+    const dev = Number(identity.dev);
+    const ino = Number(identity.ino);
+    if (!Number.isSafeInteger(dev) || dev < 0 || BigInt(dev) !== identity.dev ||
+        !Number.isSafeInteger(ino) || ino < 0 || BigInt(ino) !== identity.ino) {
+        return undefined;
+    }
+    return Object.freeze({ dev, ino });
+}
+function identityMismatch() {
+    const error = new FsSafeError("path-mismatch", "file identity changed or could not be verified");
+    recordFileObservationFailure(error, "identity");
+    throw error;
+}
+function inspectNumericIdentity(current, expected) {
+    if (!Number.isSafeInteger(current.dev) || current.dev < 0 || current.dev !== expected.dev ||
+        !Number.isSafeInteger(current.ino) || current.ino < 0 || current.ino !== expected.ino) {
+        identityMismatch();
+    }
+    return current;
+}
+export function inspectTempWorkspaceDescriptorIdentitySync(fd, expected, numeric) {
+    // A malformed or mismatched numeric observation is definite and never
+    // retried. Unsafe receipts and other platforms retain exact replay.
+    if (TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY && numeric) {
+        return inspectNumericIdentity(fsSync.fstatSync(fd), numeric);
+    }
+    return inspectFileIdentitySync(() => fsSync.fstatSync(fd, { bigint: true }), expected);
+}
+export function inspectTempWorkspaceDirectoryIdentitySync(dir, expected, numeric) {
+    if (TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY && numeric) {
+        return inspectNumericIdentity(observeDirectoryIdentitySync(dir), numeric);
+    }
+    return inspectFileIdentitySync(() => observeDirectoryIdentitySync(dir, { bigint: true }), expected);
+}
+export function validateTempWorkspaceDirMode(mode) {
+    if (!Number.isInteger(mode) || mode < 0 || mode > 0o7777) {
+        throw new FsSafeError("insecure-permissions", "temp workspace dirMode must be permission bits");
+    }
+    if (process.platform !== "win32" && (mode & 0o022) !== 0) {
+        throw new FsSafeError("insecure-permissions", "temp workspace must not be group/world writable");
+    }
+}
+export function assertTrustedTempWorkspaceDirectory(stat, uid, child = false) {
+    if (uid === undefined)
+        return;
+    const ownedByUser = typeof stat.uid === "bigint" ? stat.uid === BigInt(uid) : stat.uid === uid;
+    const ownedByRoot = typeof stat.uid === "bigint" ? stat.uid === 0n : stat.uid === 0;
+    if (!ownedByUser && (child || !ownedByRoot)) {
+        throw new FsSafeError("not-owned", "temp workspace directory has an untrusted owner");
+    }
+    // A root/current-user-owned sticky directory protects children owned by us,
+    // including the usual shared system temp directory. Never chmod that parent.
+    const writable = typeof stat.mode === "bigint"
+        ? (stat.mode & 18n) !== 0n
+        : Number.isSafeInteger(stat.mode) && stat.mode >= 0 && (stat.mode & 0o022) !== 0;
+    const sticky = typeof stat.mode === "bigint"
+        ? (stat.mode & 512n) !== 0n
+        : Number.isSafeInteger(stat.mode) && stat.mode >= 0 && (stat.mode & 0o1000) !== 0;
+    if (typeof stat.mode !== "bigint" && (!Number.isSafeInteger(stat.mode) || stat.mode < 0)) {
+        throw new FsSafeError("insecure-permissions", "temp workspace directory permissions are invalid");
+    }
+    if (writable && (child || !sticky)) {
+        throw new FsSafeError("insecure-permissions", "temp workspace directory is group/world writable without sticky protection");
+    }
+}
 const WINDOWS = process.platform === "win32";
 export function assertTempWorkspaceChildState(stat, ownerUid) {
     const exactIdentity = typeof stat.dev === "bigint" && typeof stat.ino === "bigint" &&

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

@@ -1,7 +1,7 @@
 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";
+import { type TempWorkspaceIdentityStat } from "./temp-workspace-child-admission.js";
 type DirectoryDescriptorAccess = "read" | "search";
 export type RetainedDirectory = {
     fd: number;

package/dist/temp-workspace-descriptor.js

@@ -5,8 +5,7 @@ import { assertOwnedDirectory } from "./directory-mode-owner.js";
 import { FsSafeError } from "./errors.js";
 import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
-import { assertTempWorkspaceChildState, childHasRequestedMode, validateAdmittedTempWorkspaceChild, } from "./temp-workspace-child-admission.js";
-import { inspectTempWorkspaceDescriptorIdentitySync, inspectTempWorkspaceDirectoryIdentitySync, projectTempWorkspaceNumericIdentity, TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY, } from "./temp-workspace-identity.js";
+import { assertTempWorkspaceChildState, childHasRequestedMode, validateAdmittedTempWorkspaceChild, inspectTempWorkspaceDescriptorIdentitySync, inspectTempWorkspaceDirectoryIdentitySync, projectTempWorkspaceNumericIdentity, TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY, } from "./temp-workspace-child-admission.js";
 function assertRetainedChildDirectory(stat) {
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
         throw new FsSafeError("not-file", "temp workspace child must be a real directory");

package/dist/text-atomic.js

@@ -1,5 +1,5 @@
 import { replaceFileAtomic } from "./replace-file.js";
-import { admitStandalonePublicationPath } from "./standalone-publication-path.js";
+import { admitStandalonePublicationPath } from "./windows-path-alias.js";
 export async function writeTextAtomic(filePath, content, options) {
     const admittedPath = admitStandalonePublicationPath(filePath);
     const payload = options?.trailingNewline && !content.endsWith("\n") ? `${content}\n` : content;

package/dist/windows-owner.js

@@ -1,4 +1,4 @@
-import { formatCaughtPermissionFailure, formatPermissionErrorDetail, getPermissionCommandFailure, } from "./permission-exec.js";
+import { formatCaughtPermissionFailure, getPermissionCommandFailure, } from "./permission-exec.js";
 import { resolveWindowsSystemCommand } from "./windows-command.js";
 import { hasWindowsPathAlias } from "./windows-path-alias.js";
 const SID_RE = /^\*?s-\d+-\d+(-\d+)+$/i;

package/dist/windows-path-alias.d.ts

@@ -36,3 +36,4 @@ export declare function hasWindowsPathAlias(value: string, kind: WindowsPathAlia
 export declare function assertNoWindowsPathAliasForPlatform(value: string, kind: WindowsPathAliasKind, message: string, platform: NodeJS.Platform | string | undefined): void;
 export declare function assertNoWindowsPathAlias(value: string, kind?: WindowsPathAliasKind, message?: string, platform?: NodeJS.Platform | string): void;
 export declare function isWindowsPathAliasError(error: unknown): error is FsSafeError;
+export declare function admitStandalonePublicationPath(value: string, message?: string): string;

package/dist/windows-path-alias.js

@@ -115,3 +115,8 @@ export function assertNoWindowsPathAlias(value, kind = "filesystem", message = "
 export function isWindowsPathAliasError(error) {
     return error instanceof FsSafeError && error.details?.reason === "windows-path-alias";
 }
+export function admitStandalonePublicationPath(value, message) {
+    const admittedPath = anchorWindowsDriveRelativePath(value);
+    assertNoWindowsPathAlias(admittedPath, "filesystem", message);
+    return admittedPath;
+}

package/docs/advanced.md

@@ -106,7 +106,9 @@ before component traversal. Immediately before transferring descriptor ownership
 they check that root, freshly canonicalize the consumed pathname, admit the fresh
 spelling under the captured root, compare a no-follow canonical-leaf observation
 with the retained descriptor, and check the root again. Boundary or identity drift
-is a validation failure and the descriptor is closed. A custom `ioFs` supplies
+is a validation failure and triggers one descriptor-close attempt. If cleanup also
+fails, the selected admission failure result is preserved. Successful opens transfer
+descriptor ownership to the caller. A custom `ioFs` supplies
 these observations; the built-in adapter uses fs-safe's native realpath wrapper.
 On Windows, the built-in adapter binds native root spelling before traversal,
 including supplied `rootRealPath`, and returns that spelling in its root receipt.

package/docs/secret-file.md

@@ -205,6 +205,10 @@ Both mode options must resolve to integers between `0o0000` and `0o7777`; invali
 
 After this operation wins directory creation, initialization uses a pinned descriptor bound to the admitted identity and effective user, with ancestor checks before chmod. It does not chmod the caller's pathname. Creation and descriptor admission are separate operations, not an atomic create-and-pin guarantee. A raced directory that has not reached its requested mode yet is rejected rather than repaired; callers may retry after its creator finishes initialization.
 
+If initial directory-descriptor admission fails, its original identity, ownership,
+or inspection error is preserved even when closing the rejected descriptor fails.
+Close failures after successful admission remain reportable.
+
 Initialization fails closed if the platform cannot safely pin a created directory. In particular, a non-root macOS process cannot pin a new `000` directory produced by `umask(0o777)`; the write fails without repairing that directory or writing a secret. Restrictive masks retaining owner search permission remain usable. Linux x64/arm64 can use the guarded `O_PATH`/procfs descriptor route where available. There is no unguarded pathname-chmod fallback, and a failure may leave a created directory for caller-managed cleanup.
 
 ### `createSecretFileAtomic(params)`

package/docs/sidecar-lock.md

@@ -199,6 +199,10 @@ explicit `retry.retries` still applies with `timeoutMs: Infinity`, and zero allo
 only the initial attempt. After process defaults are applied, an omitted retry
 count means unlimited retries, and an omitted or infinite timeout means no
 deadline. With neither budget bounded, contention can wait indefinitely.
+Finite deadlines use monotonic elapsed time, so system clock corrections do not
+extend or shorten the retry budget. Payload timestamps, `heldEntries().acquiredAt`,
+and stale-policy `nowMs` remain wall-clock based. Deadlines are checked at retry
+boundaries; they do not interrupt callbacks or filesystem operations.
 `parsePayload` replaces JSON parsing for legacy or custom sidecars. Its `unknown`
 result is passed to `shouldReclaim` and `shouldRemoveStaleLock`, allowing PID,
 process-start, argv, or role schemas to remain application-owned.

package/docs/store.md

@@ -93,6 +93,12 @@ existing single-load rejection and batch-skip behavior. A caller or migration
 error with code `ENOENT` is still a failure, not a missing queue entry; only a
 claim that is absent or disappears before reading returns `null` from a single load.
 
+If closing the read descriptor also fails, the original read, validation,
+callback, or migration failure keeps precedence, including non-Error rejection
+values. A close failure without an earlier failure is reported through the same
+loader policy: direct reads and single loads reject, while batch loads skip it
+unless migration has started.
+
 On Windows, migration releases its read pin once at this publication boundary
 because an open target can block replacement. It rechecks the exact pathname
 identity after the asynchronous close while still holding the transfer lock.

package/docs/temp.md

@@ -31,6 +31,8 @@ rejects with `permission-unverified`. Existing supplied directories keep their
 permissions. Missing root components are created at `0o700` and initialized
 from their first exact security snapshot; if a restrictive umask changes that
 mode, correction uses a verified directory descriptor.
+An initial mode-descriptor admission error is preserved if closing that rejected
+descriptor also fails; close failures after successful admission remain reportable.
 
 For an already existing canonical root, discovery retains only its immutable
 exact identity. Cleanup-parent retention is provisional: after any native
@@ -645,7 +647,12 @@ recursive-`mkdir` winner is inspected as an untrusted existing directory.
 Broad-mode repair also uses a pinned descriptor; there is no pathname chmod.
 
 Repair and finalization require a known nonnegative safe-integer UID and exact
-bigint device, inode, owner, mode, and directory-type facts. They open with
+bigint device, inode, owner, mode, and directory-type facts. Device and inode
+identities accept Node's signed 64-bit stat representation, including negative
+values down to `-(1n << 63n)`; inode zero remains invalid. Previously supported
+nonnegative device and positive inode adapter values remain supported without
+an upper cap. Values are compared exactly as received: signed and unsigned
+encodings of the same bits are not treated as equal. They open with
 `O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_NONBLOCK`, verify the descriptor and
 current directory entry against the initial receipt before `fchmod`, then
 verify identity, permissions, and write/search access again before closing.

package/docs/writing.md

@@ -198,6 +198,11 @@ existing `durable` file/directory synchronization policy; it does not turn
 best-effort synchronization into a strict crash-durability guarantee or strengthen
 JavaScript pathname containment.
 
+Wider option objects do not enable create-only `atomic` or `private` behavior on
+`write` or `writeJson`. Buffered Root writes and creates also ignore an extra
+`maxBytes` property; that byte limit belongs to streamed creation and `copyIn`.
+File synchronization follows each method's documented `durable` option.
+
 Atomic and streamed creates settle owned cleanup and close operations before
 returning. Failed or unverifiable cleanup is reported rather than silently
 discarded. Errors after publication and incomplete-settlement errors carry the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -169,13 +169,13 @@
     "archive:producer-smoke": "node scripts/archive-producer-smoke.mjs"
   },
   "optionalDependencies": {
-    "@openclaw/fs-safe-darwin-arm64": "0.18.0",
-    "@openclaw/fs-safe-darwin-x64": "0.18.0",
-    "@openclaw/fs-safe-linux-arm64-gnu": "0.18.0",
-    "@openclaw/fs-safe-linux-arm64-musl": "0.18.0",
-    "@openclaw/fs-safe-linux-x64-gnu": "0.18.0",
-    "@openclaw/fs-safe-linux-x64-musl": "0.18.0",
-    "@openclaw/fs-safe-win32-x64-msvc": "0.18.0",
+    "@openclaw/fs-safe-darwin-arm64": "0.18.1",
+    "@openclaw/fs-safe-darwin-x64": "0.18.1",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.18.1",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.18.1",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.18.1",
+    "@openclaw/fs-safe-linux-x64-musl": "0.18.1",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.18.1",
     "jszip": "^3.10.2"
   },
   "devDependencies": {

package/dist/archive-native.d.ts

@@ -1,10 +0,0 @@
-import type { ArchiveKind } from "./archive-kind.js";
-import { type TarMeterLimits } from "./archive-limits.js";
-import type { StagedArchiveExtractOptions } from "./archive-options.js";
-import type { NativeBinding } from "./native.js";
-export declare function throwMappedNativeArchiveError(error: unknown): never;
-export declare function extractNativeArchive(params: StagedArchiveExtractOptions & {
-    binding: NativeBinding;
-    kind: ArchiveKind;
-    tarLimits: TarMeterLimits;
-}): Promise<void>;

package/dist/archive-native.js

@@ -1,73 +0,0 @@
-import { classifyArchiveParserError } from "./archive-parser-errors.js";
-import { constants as fsConstants } from "node:fs";
-import fs from "node:fs/promises";
-import { ArchiveFormatError, isArchiveFormatErrorMessage, } from "./archive-errors.js";
-import { validateArchiveEntryPath } from "./archive-entry.js";
-import { createArchiveEntryPlanner } from "./archive-plan.js";
-import { assertArchiveEntryCountWithinLimit, } from "./archive-limits.js";
-import { prepareArchiveDestinationGuard } from "./archive-staging.js";
-import { withStagedArchivePublication } from "./archive-merge.js";
-import { admitZipFile } from "./archive-zip-admission.js";
-import { validateNativeZipManifest } from "./archive-zip-manifest.js";
-export function throwMappedNativeArchiveError(error) {
-    if (error instanceof Error) {
-        const mapped = classifyArchiveParserError(error.message, { cause: error });
-        if (mapped)
-            throw mapped;
-        if (isArchiveFormatErrorMessage(error.message)) {
-            throw new ArchiveFormatError(error.message, { cause: error });
-        }
-        if (error.code === "InvalidArg") {
-            throw new ArchiveFormatError(`invalid archive: ${error.message}`, { cause: error });
-        }
-    }
-    throw error;
-}
-export async function extractNativeArchive(params) {
-    const { archivePath, limits, tarLimits, deadline } = params;
-    const zipEntries = [];
-    if (params.kind === "zip") {
-        await admitZipFile(archivePath, limits, deadline, (entry) => { zipEntries.push(entry); });
-    }
-    const destinationGuard = await prepareArchiveDestinationGuard(params.destDir);
-    await withStagedArchivePublication({ ...params, destinationGuard }, async (stagingDir) => {
-        deadline.check();
-        // N-API retains completed task state on its signal; each pass needs its own.
-        const manifest = await params.binding
-            .inspectArchiveNative(archivePath, params.kind, tarLimits, AbortSignal.any([deadline.signal]))
-            .catch(throwMappedNativeArchiveError);
-        deadline.check();
-        assertArchiveEntryCountWithinLimit(manifest.length, limits);
-        if (params.kind === "zip") {
-            validateNativeZipManifest(manifest, zipEntries);
-        }
-        // Recheck the native manifest before any caller callback observes an entry.
-        if (params.kind !== "zip") {
-            for (const entry of manifest)
-                validateArchiveEntryPath(entry.path);
-        }
-        const planEntry = createArchiveEntryPlanner({ ...params, rootDir: stagingDir }, params.kind);
-        const plan = [];
-        for (const entry of manifest) {
-            deadline.check();
-            const mode = params.kind === "zip"
-                ? zipEntries[entry.index].creatorSystem === 3
-                    ? zipEntries[entry.index].externalAttributes >>> 16
-                    : undefined
-                : entry.mode;
-            const accepted = planEntry({ ...entry, mode });
-            if (accepted)
-                plan.push({ ...accepted, index: entry.index });
-        }
-        const directory = await fs.open(stagingDir, fsConstants.O_RDONLY |
-            (typeof fsConstants.O_DIRECTORY === "number" ? fsConstants.O_DIRECTORY : 0));
-        try {
-            deadline.check();
-            await params.binding.extractArchiveNative(archivePath, params.kind, directory.fd, plan.map((entry) => ({ ...entry, mode: entry.kind === "directory" ? 0o700 : 0o600 })), tarLimits, AbortSignal.any([deadline.signal])).catch(throwMappedNativeArchiveError);
-        }
-        finally {
-            await directory.close().catch(() => undefined);
-        }
-        return plan;
-    });
-}

package/dist/archive-options.d.ts

@@ -1,30 +0,0 @@
-import type { ArchiveKind } from "./archive-kind.js";
-import type { ExtractionDeadline } from "./archive-deadline.js";
-import type { ArchiveExtractLimits, ResolvedArchiveExtractLimits } from "./archive-limits.js";
-import type { ArchiveEntryFilter, ArchiveEntryModePolicy, ArchiveFilteredEntryPolicy } from "./archive-policy.js";
-export type ArchiveLogger = {
-    info?: (message: string) => void;
-    warn?: (message: string) => void;
-};
-export type ExtractArchiveOptions = {
-    archivePath: string;
-    destDir: string;
-    timeoutMs: number;
-    /** Sync published files and directories before returning. Defaults to false. */
-    durable?: boolean;
-    kind?: ArchiveKind;
-    stripComponents?: number;
-    tarGzip?: boolean;
-    limits?: ArchiveExtractLimits;
-    logger?: ArchiveLogger;
-    entryModes?: ArchiveEntryModePolicy;
-    /** Remove these rwx bits from final entry modes. Defaults to zero. */
-    entryUmask?: number;
-    entryFilter?: ArchiveEntryFilter;
-    onFiltered?: ArchiveFilteredEntryPolicy;
-};
-/** Private executors receive owned options and an already-staged archive path. */
-export type StagedArchiveExtractOptions = Pick<ExtractArchiveOptions, "archivePath" | "destDir" | "durable" | "stripComponents" | "entryModes" | "entryUmask" | "entryFilter" | "onFiltered"> & {
-    limits: ResolvedArchiveExtractLimits;
-    deadline: ExtractionDeadline;
-};

package/dist/archive-policy.d.ts

@@ -1,21 +0,0 @@
-export type ArchiveEntryKind = "file" | "directory" | "symlink" | "other";
-export type ArchiveEntryModePolicy = "clamp" | "preserve";
-export type ArchiveFilteredEntryPolicy = "reject-archive" | "skip-entry";
-export type ArchiveEntryFilter = (entry: {
-    /** Validated canonical archive path before stripping: / separators, no empty or . components. */
-    path: string;
-    kind: ArchiveEntryKind;
-    size: number;
-}) => "extract" | "skip";
-export declare function archiveEntryKindFromTarType(type: string): ArchiveEntryKind;
-export declare function resolveArchiveEntryMode(params: {
-    kind: "file" | "directory";
-    archivedMode?: number | null;
-    policy?: ArchiveEntryModePolicy;
-}): number;
-export declare function resolveArchiveFilteredEntryPolicy(value: unknown): ArchiveFilteredEntryPolicy;
-export declare function shouldExtractArchiveEntry(params: {
-    filter?: ArchiveEntryFilter;
-    onFiltered?: ArchiveFilteredEntryPolicy;
-    entry: Parameters<ArchiveEntryFilter>[0];
-}): boolean;

package/dist/archive-policy.js

@@ -1,38 +0,0 @@
-import { ArchiveSecurityError } from "./archive-errors.js";
-import { formatErrorDetail } from "./error-detail.js";
-export function archiveEntryKindFromTarType(type) {
-    if (type === "Directory" || type === "GNUDumpDir")
-        return "directory";
-    if (type === "File" || type === "OldFile" || type === "ContiguousFile")
-        return "file";
-    if (type === "SymbolicLink" || type === "Link")
-        return "symlink";
-    return "other";
-}
-export function resolveArchiveEntryMode(params) {
-    const archivedMode = (params.archivedMode ?? 0) & 0o777;
-    if (params.policy === "preserve") {
-        return params.archivedMode == null ? (params.kind === "directory" ? 0o755 : 0o644) : archivedMode;
-    }
-    if (params.kind === "directory") {
-        return 0o755;
-    }
-    return archivedMode & 0o100 ? 0o755 : 0o644;
-}
-export function resolveArchiveFilteredEntryPolicy(value) {
-    if (value === undefined || value === "reject-archive")
-        return "reject-archive";
-    if (value === "skip-entry")
-        return "skip-entry";
-    throw new RangeError('archive onFiltered must be "reject-archive" or "skip-entry"');
-}
-export function shouldExtractArchiveEntry(params) {
-    const onFiltered = resolveArchiveFilteredEntryPolicy(params.onFiltered);
-    if (!params.filter || params.filter(params.entry) === "extract") {
-        return true;
-    }
-    if (onFiltered === "reject-archive") {
-        throw new ArchiveSecurityError("entry-filtered", `archive entry rejected by filter: ${formatErrorDetail(params.entry.path)}`);
-    }
-    return false;
-}

package/dist/archive-tar-inspect.d.ts

@@ -1,6 +0,0 @@
-import type { ExtractArchiveOptions } from "./archive-options.js";
-import { type ArchivePlanEntry } from "./archive-plan.js";
-export type InspectTarArchiveOptions = Pick<ExtractArchiveOptions, "archivePath" | "timeoutMs" | "limits" | "entryFilter" | "onFiltered">;
-export type InspectedTarEntry = Readonly<Pick<ArchivePlanEntry, "path" | "kind" | "size">>;
-/** Complete TAR/gzip admission and zero-strip extraction policy, without output writes. */
-export declare function inspectTarArchive(params: InspectTarArchiveOptions): Promise<readonly InspectedTarEntry[]>;

package/dist/archive-tar-inspect.js

@@ -1,62 +0,0 @@
-import { withExtractionDeadline } from "./archive-deadline.js";
-import { validateArchiveEntryPath } from "./archive-entry.js";
-import { stageArchiveFileForExtraction } from "./archive-input.js";
-import { resolveExtractLimits, resolveTarMeterLimits } from "./archive-limits.js";
-import { throwMappedNativeArchiveError } from "./archive-native.js";
-import { createArchiveEntryPlanner } from "./archive-plan.js";
-import { resolveArchiveFilteredEntryPolicy } from "./archive-policy.js";
-import { createTarEntryPlanner } from "./archive-tar.js";
-import { inspectTar } from "./archive-tar-stream.js";
-import { getNativeBinding } from "./native.js";
-import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
-/** Complete TAR/gzip admission and zero-strip extraction policy, without output writes. */
-export async function inspectTarArchive(params) {
-    const archivePath = params.archivePath;
-    const onFiltered = resolveArchiveFilteredEntryPolicy(params.onFiltered);
-    const limits = resolveExtractLimits(params.limits);
-    const tarLimits = resolveTarMeterLimits(limits);
-    const native = getNativeBinding();
-    assertNoWindowsPathAlias(archivePath, "filesystem", "archive source uses a Windows filesystem namespace alias");
-    return await withExtractionDeadline(params.timeoutMs, "inspect tar", async (deadline) => {
-        const staged = await stageArchiveFileForExtraction({ archivePath, limits, deadline });
-        try {
-            // Staging closes descriptors asynchronously; expiry there must not start a decoder.
-            deadline.check();
-            const entries = [];
-            const append = (entry) => {
-                if (entry)
-                    entries.push(Object.freeze({ path: entry.path, kind: entry.kind, size: entry.size }));
-            };
-            const policy = { limits, entryFilter: params.entryFilter, onFiltered };
-            if (native) {
-                const manifest = await native.inspectArchiveNative(staged.path, "tar", tarLimits, deadline.signal)
-                    .catch(throwMappedNativeArchiveError);
-                deadline.check();
-                // Match extraction's whole-manifest validation before caller policy runs.
-                for (const entry of manifest)
-                    validateArchiveEntryPath(entry.path);
-                const planEntry = createArchiveEntryPlanner(policy, "tar");
-                for (const entry of manifest) {
-                    deadline.check();
-                    append(planEntry(entry));
-                }
-            }
-            else {
-                const manifest = [];
-                await inspectTar({ archivePath: staged.path, limits: tarLimits, signal: deadline.signal,
-                    onMember: (entry) => { manifest.push(entry); } });
-                const planEntry = createTarEntryPlanner(policy);
-                for (const entry of manifest) {
-                    deadline.check();
-                    append(planEntry(entry));
-                }
-            }
-            deadline.check();
-            // This is bounded evidence about the staged bytes, not a reusable write plan.
-            return Object.freeze(entries);
-        }
-        finally {
-            await staged.cleanup();
-        }
-    });
-}

package/dist/archive-tar.d.ts

@@ -1,18 +0,0 @@
-import type { ArchiveExtractLimits } from "./archive-limits.js";
-import { type ArchivePlanEntry, type ArchivePlanOptions } from "./archive-plan.js";
-import { type ArchiveEntryFilter, type ArchiveFilteredEntryPolicy } from "./archive-policy.js";
-export type TarEntryInfo = {
-    path: string;
-    type: string;
-    size: number;
-    mode?: number;
-};
-export declare function createTarEntryPlanner(params: ArchivePlanOptions): (entry: TarEntryInfo) => ArchivePlanEntry | null;
-export declare function createTarEntryPreflightChecker(params: {
-    rootDir: string;
-    stripComponents?: number;
-    limits?: ArchiveExtractLimits;
-    escapeLabel?: string;
-    entryFilter?: ArchiveEntryFilter;
-    onFiltered?: ArchiveFilteredEntryPolicy;
-}): (entry: TarEntryInfo) => boolean;

package/dist/archive-tar.js

@@ -1,21 +0,0 @@
-import { createArchiveEntryPlanner, } from "./archive-plan.js";
-import { archiveEntryKindFromTarType, } from "./archive-policy.js";
-const BLOCKED_TAR_ENTRY_TYPES = new Set([
-    "BlockDevice",
-    "CharacterDevice",
-    "FIFO",
-    "Socket",
-]);
-export function createTarEntryPlanner(params) {
-    // Preserve inherited/getter-backed public options and per-entry policy reads.
-    const plan = createArchiveEntryPlanner(params, "tar");
-    return (entry) => {
-        const kind = BLOCKED_TAR_ENTRY_TYPES.has(entry.type) ? "blocked" : archiveEntryKindFromTarType(entry.type);
-        // The public checker accepts structural entry objects, including class getters.
-        return plan({ path: entry.path, kind, size: entry.size, mode: entry.mode });
-    };
-}
-export function createTarEntryPreflightChecker(params) {
-    const plan = createTarEntryPlanner(params);
-    return (entry) => plan(entry) !== null;
-}

package/dist/create-directory.d.ts

@@ -1,18 +0,0 @@
-import { type BigIntStats } from "node:fs";
-import { type CreationPermissions } from "./creation-permissions.js";
-import { type CreationParentIdentity } from "./creation-path.js";
-export type CreateDirectoryOptions = CreationPermissions & {
-    assertBeforeMutation?: () => void;
-};
-export type CreationAdmission = {
-    expectedParentIdentity?: CreationParentIdentity;
-};
-export type CreationDirectoryReceipt = {
-    stat: BigIntStats;
-    windowsIdentity?: string;
-};
-export declare function createDirectory(targetPath: string, options?: CreateDirectoryOptions): Promise<void>;
-export declare function createDirectoryWithAdmission(targetPath: string, options?: CreateDirectoryOptions, admission?: CreationAdmission): Promise<void>;
-export declare function createDirectoryWithReceipt(targetPath: string, options?: CreateDirectoryOptions, admission?: CreationAdmission): Promise<CreationDirectoryReceipt>;
-export declare function createDirectorySync(targetPath: string, options?: CreateDirectoryOptions): void;
-export declare function createDirectoryWithReceiptSync(targetPath: string, options?: CreateDirectoryOptions, admission?: CreationAdmission): CreationDirectoryReceipt;