@openclaw/fs-safe 0.18.0 → 0.18.1

package/dist/creation-path.js

@@ -1,83 +0,0 @@
-import fs, {} from "node:fs";
-import fsAsync from "node:fs/promises";
-import path from "node:path";
-import { assertDirectoryIdentitySync, inspectDirectoryIdentitySync, } from "./directory-guard.js";
-import { FsSafeError } from "./errors.js";
-import { assertDarwinCreationDirectoryAcl, assertDarwinPrivateDirectoryMode } from "./creation-darwin.js";
-import { assertSynchronousCallbackResult } from "./mutation-authority.js";
-import { assertNoNulPathInput } from "./path.js";
-import { realpathSync } from "./realpath.js";
-import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot } from "./windows-path-alias.js";
-export function assertBeforeCreation(selected, permissions, assertion, kind) {
-    if (permissions.private)
-        assertDarwinCreationDirectoryAcl(selected.parent.dir, selected.parent.stat, kind);
-    assertSynchronousCallbackResult(assertion?.(), "assertBeforeMutation");
-    selected.assertParent();
-    if (permissions.private && kind === "directory")
-        assertDarwinPrivateDirectoryMode(permissions.mode);
-    if (permissions.private)
-        assertDarwinCreationDirectoryAcl(selected.parent.dir, selected.parent.stat, kind);
-}
-export function creationAdmissionFromParent(parent) {
-    const { dev, ino } = parent.stat;
-    if (typeof dev !== "bigint" || typeof ino !== "bigint") {
-        throw new FsSafeError("path-mismatch", "private creation requires an exact parent identity");
-    }
-    const identity = inspectDirectoryIdentitySync(parent.dir, { dev, ino });
-    return { expectedParentIdentity: { dev: identity.dev, ino: identity.ino, realPath: parent.realPath } };
-}
-export function prepareCreationPath(input, expectedParent) {
-    expectedParent = expectedParent && { dev: expectedParent.dev, ino: expectedParent.ino, realPath: expectedParent.realPath };
-    assertNoNulPathInput(input);
-    assertNoWindowsPathAlias(input, "filesystem");
-    if (process.platform === "win32" && input.replaceAll("/", "\\").split("\\")
-        .some(component => component.endsWith(".") || component.endsWith(" "))) {
-        throw new FsSafeError("invalid-path", "creation path contains an ambiguous Windows component");
-    }
-    const target = resolvePathPreservingWindowsRoot(input);
-    const directory = path.dirname(target);
-    if (target === directory || input.length === 0) {
-        throw new FsSafeError("invalid-path", "creation requires a child name");
-    }
-    if (expectedParent)
-        assertDirectoryIdentitySync(directory, expectedParent);
-    const stat = inspectDirectoryIdentitySync(directory);
-    const realPath = realpathSync.native(directory);
-    const parent = { dir: directory, realPath, stat };
-    const assertParent = () => {
-        assertDirectoryIdentitySync(directory, { dev: stat.dev, ino: stat.ino, realPath });
-        if (expectedParent)
-            assertDirectoryIdentitySync(directory, expectedParent);
-    };
-    assertParent();
-    return { target, parent, assertParent };
-}
-export function creationCollision(error) {
-    if (error?.code === "EEXIST") {
-        return new FsSafeError("already-exists", "creation target already exists", { cause: error });
-    }
-    return error;
-}
-/** Remove only the recorded empty stage; never traverse a replaced directory. */
-export function removeCreationDirectory(directory, identity, assertParent) {
-    assertParent();
-    try {
-        assertDirectoryIdentitySync(directory, identity);
-        fs.rmdirSync(directory);
-    }
-    catch (error) {
-        if (error?.code !== "ENOENT")
-            throw error;
-    }
-}
-export async function removeCreationDirectoryAsync(directory, identity, assertParent) {
-    assertParent();
-    try {
-        assertDirectoryIdentitySync(directory, identity);
-        await fsAsync.rmdir(directory);
-    }
-    catch (error) {
-        if (error?.code !== "ENOENT")
-            throw error;
-    }
-}

package/dist/creation-permissions.d.ts

@@ -1,18 +0,0 @@
-export type CreationPermissions = {
-    private?: boolean;
-    mode?: number;
-};
-export declare function resolveCreationPermissions(options: CreationPermissions, directory: boolean): {
-    private: boolean;
-    mode: number | undefined;
-};
-export declare function assertPrivateFileCreationAvailable(): void;
-/** Full Windows identity, with security validation when requested; no repairs. */
-export declare function inspectCreationDirectorySync(targetPath: string, privatePath: boolean): string;
-export declare function inspectCreationDirectory(targetPath: string, privatePath: boolean): Promise<string>;
-export declare function assertPrivateDirectorySync(targetPath: string): void;
-export declare function assertPrivateDirectory(targetPath: string): Promise<void>;
-export declare function protectCreatedFileSync(fd: number, targetPath: string, parentIdentity: string): string;
-export declare function protectCreatedFile(fd: number, targetPath: string, parentIdentity: string): Promise<string>;
-export declare function verifyCreatedFileSync(fd: number, targetPath: string, identity: string, parentIdentity: string, links?: number): void;
-export declare function verifyCreatedFile(fd: number, targetPath: string, identity: string, parentIdentity: string, links?: number): Promise<void>;

package/dist/creation-permissions.js

@@ -1,115 +0,0 @@
-import { inspectDirectoryIdentitySync } from "./directory-guard.js";
-import { FsSafeError } from "./errors.js";
-import { getNativeBinding } from "./native.js";
-import { getFsSafeNativeConfig } from "./native-config.js";
-import { warnNativeFallback } from "./native-fallback-warning.js";
-import { inspectWindowsDirectoryCommand, inspectWindowsDirectoryCommandSync, protectPrivateWindowsFileCommand, protectPrivateWindowsFileCommandSync, verifyPrivateWindowsFileCommand, verifyPrivateWindowsFileCommandSync, } from "./windows-security-command.js";
-import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
-import { assertDarwinCreationDirectoryAcl, assertDarwinPrivateCreationAvailable, assertDarwinPrivateDirectoryMode } from "./creation-darwin.js";
-export function resolveCreationPermissions(options, directory) {
-    const privatePath = options.private;
-    const mode = options.mode;
-    if (privatePath !== undefined && typeof privatePath !== "boolean") {
-        throw new TypeError("private must be a boolean");
-    }
-    if (mode !== undefined && (!Number.isInteger(mode) || mode < 0 || mode > 0o7777)) {
-        throw new RangeError("mode must contain only permission bits");
-    }
-    if (privatePath && mode !== undefined && (mode & 0o7077) !== 0) {
-        throw new FsSafeError("insecure-permissions", "private creation requires owner-only permission bits");
-    }
-    if (privatePath)
-        assertDarwinPrivateCreationAvailable();
-    if (privatePath && directory)
-        assertDarwinPrivateDirectoryMode(mode ?? 0o700);
-    return { private: privatePath === true, mode: mode ?? (privatePath ? directory ? 0o700 : 0o600 : undefined) };
-}
-function assertPrivatePosixDirectory(stat) {
-    if (typeof process.getuid !== "function" || stat.uid !== BigInt(process.getuid())) {
-        throw new FsSafeError("not-owned", "private directory must belong to the current user");
-    }
-    if ((stat.mode & 3647n) !== 0n) {
-        throw new FsSafeError("insecure-permissions", "existing directory is not private");
-    }
-}
-function unavailable() {
-    throw new FsSafeError("helper-unavailable", "private Windows creation requires an up-to-date native helper");
-}
-export function assertPrivateFileCreationAvailable() {
-    const native = getNativeBinding();
-    if (process.platform !== "win32" || getFsSafeNativeConfig().mode !== "require")
-        return;
-    if (typeof native?.createPrivateDirectoryWithParentIdentity !== "function" ||
-        typeof native.inspectWindowsDirectory !== "function" ||
-        typeof native.protectPrivateWindowsFile !== "function" ||
-        typeof native.verifyPrivateWindowsFile !== "function")
-        unavailable();
-}
-function commandFallback() {
-    if (getFsSafeNativeConfig().mode === "require")
-        unavailable();
-    warnNativeFallback("windows-private-creation", "Private Windows creation uses a slower built-in system command.");
-}
-function creationOperation(name) {
-    const native = getNativeBinding();
-    const operation = native?.[name];
-    if (typeof operation === "function")
-        return operation.bind(native);
-    commandFallback();
-    return undefined;
-}
-/** Full Windows identity, with security validation when requested; no repairs. */
-export function inspectCreationDirectorySync(targetPath, privatePath) {
-    assertNoWindowsPathAlias(targetPath, "filesystem");
-    const inspect = creationOperation("inspectWindowsDirectory");
-    return (inspect ? inspect(targetPath, privatePath) : inspectWindowsDirectoryCommandSync(targetPath, privatePath)).identity;
-}
-export async function inspectCreationDirectory(targetPath, privatePath) {
-    assertNoWindowsPathAlias(targetPath, "filesystem");
-    const inspect = creationOperation("inspectWindowsDirectory");
-    return (inspect ? inspect(targetPath, privatePath) : await inspectWindowsDirectoryCommand(targetPath, privatePath)).identity;
-}
-export function assertPrivateDirectorySync(targetPath) {
-    const stat = inspectDirectoryIdentitySync(targetPath);
-    if (process.platform === "win32")
-        inspectCreationDirectorySync(targetPath, true);
-    else {
-        assertPrivatePosixDirectory(stat);
-        assertDarwinCreationDirectoryAcl(targetPath, stat);
-    }
-    inspectDirectoryIdentitySync(targetPath, stat);
-}
-export async function assertPrivateDirectory(targetPath) {
-    const stat = inspectDirectoryIdentitySync(targetPath);
-    if (process.platform === "win32")
-        await inspectCreationDirectory(targetPath, true);
-    else {
-        assertPrivatePosixDirectory(stat);
-        assertDarwinCreationDirectoryAcl(targetPath, stat);
-    }
-    inspectDirectoryIdentitySync(targetPath, stat);
-}
-export function protectCreatedFileSync(fd, targetPath, parentIdentity) {
-    const protect = creationOperation("protectPrivateWindowsFile");
-    return (protect ? protect(fd, targetPath, parentIdentity)
-        : protectPrivateWindowsFileCommandSync(fd, targetPath, parentIdentity)).identity;
-}
-export async function protectCreatedFile(fd, targetPath, parentIdentity) {
-    const protect = creationOperation("protectPrivateWindowsFile");
-    return (protect ? protect(fd, targetPath, parentIdentity)
-        : await protectPrivateWindowsFileCommand(fd, targetPath, parentIdentity)).identity;
-}
-export function verifyCreatedFileSync(fd, targetPath, identity, parentIdentity, links = 1) {
-    const verify = creationOperation("verifyPrivateWindowsFile");
-    if (verify)
-        verify(fd, targetPath, identity, parentIdentity, links);
-    else
-        verifyPrivateWindowsFileCommandSync(fd, targetPath, identity, parentIdentity, links);
-}
-export async function verifyCreatedFile(fd, targetPath, identity, parentIdentity, links = 1) {
-    const verify = creationOperation("verifyPrivateWindowsFile");
-    if (verify)
-        verify(fd, targetPath, identity, parentIdentity, links);
-    else
-        await verifyPrivateWindowsFileCommand(fd, targetPath, identity, parentIdentity, links);
-}

package/dist/file-store-copy-source.d.ts

@@ -1,4 +0,0 @@
-export declare function readFileStoreCopySource(params: {
-    sourcePath: string;
-    maxBytes: number;
-}): Promise<Buffer>;

package/dist/file-store-copy-source.js

@@ -1,31 +0,0 @@
-import fs from "node:fs";
-import { FsSafeError } from "./errors.js";
-import { assertFileStoreMaxBytes } from "./file-store-limit.js";
-import { readRegularFile } from "./regular-file.js";
-import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
-export async function readFileStoreCopySource(params) {
-    assertNoWindowsPathAlias(params.sourcePath, "filesystem", "source path uses a Windows filesystem namespace alias");
-    const sourceStat = fs.lstatSync(params.sourcePath);
-    if (sourceStat.isSymbolicLink() || !sourceStat.isFile()) {
-        throw new FsSafeError("not-file", "source path is not a file");
-    }
-    assertFileStoreMaxBytes(sourceStat.size, params.maxBytes);
-    try {
-        return (await readRegularFile({ filePath: params.sourcePath, maxBytes: params.maxBytes }))
-            .buffer;
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        if (message.includes("regular file") || message.includes("not a regular file")) {
-            throw new FsSafeError("not-file", "source path is not a file", {
-                cause: error instanceof Error ? error : undefined,
-            });
-        }
-        if (message.includes(`exceeds ${params.maxBytes} bytes`)) {
-            throw new FsSafeError("too-large", `file exceeds maximum size of ${params.maxBytes} bytes`, {
-                cause: error instanceof Error ? error : undefined,
-            });
-        }
-        throw error;
-    }
-}

package/dist/file-store-limit.d.ts

@@ -1 +0,0 @@
-export declare function assertFileStoreMaxBytes(size: number, limit: number | undefined): void;

package/dist/file-store-limit.js

@@ -1,7 +0,0 @@
-import { FsSafeError } from "./errors.js";
-// Store operation boundaries admit the primitive limit before reaching this helper.
-export function assertFileStoreMaxBytes(size, limit) {
-    if (limit !== undefined && size > limit) {
-        throw new FsSafeError("too-large", `file exceeds maximum size of ${limit} bytes`);
-    }
-}

package/dist/file-store-path.d.ts

@@ -1,2 +0,0 @@
-export declare function assertRelativePath(relativePath: string): string;
-export declare function resolveStorePath(rootDir: string, relativePath: string): string;

package/dist/file-store-path.js

@@ -1,30 +0,0 @@
-import path from "node:path";
-import { FsSafeError } from "./errors.js";
-import { isPathInside, splitSafeRelativePath } from "./path.js";
-export function assertRelativePath(relativePath) {
-    const raw = relativePath.trim();
-    if (!raw || raw !== relativePath) {
-        throw new FsSafeError("invalid-path", "store key must be non-empty and unpadded");
-    }
-    const segments = splitSafeRelativePath(raw);
-    if (segments.length === 0 ||
-        segments.join("/") !== raw ||
-        raw.normalize("NFC") !== raw ||
-        segments.some((segment) => /[ .]$/u.test(segment))) {
-        throw new FsSafeError("invalid-path", "store key must use one canonical relative spelling");
-    }
-    return raw;
-}
-export function resolveStorePath(rootDir, relativePath) {
-    const key = assertRelativePath(relativePath);
-    // FileStore constructors snapshot an absolute root before this helper runs.
-    // Do not re-resolve it: Node drops the trailing separator from an exact
-    // Windows namespace drive root such as `\\?\C:\`.
-    const root = path.isAbsolute(rootDir) ? rootDir : path.resolve(rootDir);
-    // The immutable key already passed segment validation; keep the containment check.
-    const target = path.resolve(root, key);
-    if (!isPathInside(root, target)) {
-        throw new FsSafeError("outside-workspace", "relative path escapes root");
-    }
-    return target;
-}

package/dist/standalone-publication-path.d.ts

@@ -1 +0,0 @@
-export declare function admitStandalonePublicationPath(value: string, message?: string): string;

package/dist/standalone-publication-path.js

@@ -1,6 +0,0 @@
-import { anchorWindowsDriveRelativePath, assertNoWindowsPathAlias, } from "./windows-path-alias.js";
-export function admitStandalonePublicationPath(value, message) {
-    const admittedPath = anchorWindowsDriveRelativePath(value);
-    assertNoWindowsPathAlias(admittedPath, "filesystem", message);
-    return admittedPath;
-}

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

@@ -1,14 +0,0 @@
-import { type BigIntStats, type Stats } from "node:fs";
-export type TempWorkspaceIdentity = Readonly<{
-    dev: bigint;
-    ino: bigint;
-}>;
-export type TempWorkspaceNumericIdentity = Readonly<{
-    dev: number;
-    ino: number;
-}>;
-export type TempWorkspaceIdentityStat = BigIntStats | Stats;
-export declare const TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY: boolean;
-export declare function projectTempWorkspaceNumericIdentity(identity: TempWorkspaceIdentity): TempWorkspaceNumericIdentity | undefined;
-export declare function inspectTempWorkspaceDescriptorIdentitySync(fd: number, expected: TempWorkspaceIdentity, numeric: TempWorkspaceNumericIdentity | undefined): TempWorkspaceIdentityStat;
-export declare function inspectTempWorkspaceDirectoryIdentitySync(dir: string, expected: TempWorkspaceIdentity, numeric: TempWorkspaceNumericIdentity | undefined): TempWorkspaceIdentityStat;

package/dist/temp-workspace-identity.js

@@ -1,41 +0,0 @@
-import fsSync, {} from "node:fs";
-import { observeDirectoryIdentitySync } from "./directory-guard.js";
-import { FsSafeError } from "./errors.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);
-}

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

@@ -1,3 +0,0 @@
-import type { BigIntStats, Stats } from "node:fs";
-export declare function validateTempWorkspaceDirMode(mode: number): void;
-export declare function assertTrustedTempWorkspaceDirectory(stat: Pick<BigIntStats, "uid" | "mode"> | Pick<Stats, "uid" | "mode">, uid: number | undefined, child?: boolean): void;

package/dist/temp-workspace-permissions.js

@@ -1,32 +0,0 @@
-import { FsSafeError } from "./errors.js";
-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");
-    }
-}