@kisev/safe-fs 1.0.0-dev.46.gfbe1e4c6992e

package/README.md

@@ -0,0 +1,18 @@
+# safe-fs
+
+[Русская версия](README.ru.md)
+
+`@kisev/safe-fs` holds the shared filesystem safety primitives used by the
+kisev agent packages: `writeAtomic` for private single-link atomic replacement,
+`readRegular` for reading regular files only, `assertSafePath` for
+symlink-free traversal, and the `LifecycleError` failure type.
+
+## Install
+
+```bash
+npm install @kisev/safe-fs
+```
+
+Every write goes through an exclusive temporary file with `fsync`, a mode
+restriction, and a directory sync, and rejects symlinks, multi-link files, and
+non-directory parents.

package/README.ru.md

@@ -0,0 +1,18 @@
+# safe-fs
+
+[English version](README.md)
+
+`@kisev/safe-fs` — общие примитивы безопасной работы с файловой системой для
+пакетов kisev: `writeAtomic` для приватной атомарной замены файлов с одной
+ссылкой, `readRegular` для чтения только обычных файлов, `assertSafePath` для
+обхода без симлинков и тип ошибки `LifecycleError`.
+
+## Установка
+
+```bash
+npm install @kisev/safe-fs
+```
+
+Каждая запись идёт через эксклюзивный временный файл с `fsync`, ограничением
+прав и синхронизацией каталога; симлинки, файлы с несколькими ссылками и
+каталоги-не-родители отклоняются.

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { LifecycleError, assertSafePath, ensureDirectory, lstatSafe, readRegular, writeAtomic, } from "./safe-fs.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { LifecycleError, assertSafePath, ensureDirectory, lstatSafe, readRegular, writeAtomic, } from "./safe-fs.js";

package/dist/safe-fs.d.ts

@@ -0,0 +1,12 @@
+export declare class LifecycleError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function lstatSafe(path: string): Promise<import("fs").Stats | undefined>;
+export declare function assertSafePath(path: string, options?: {
+    target?: "file" | "directory";
+    allowMissing?: boolean;
+}): Promise<void>;
+export declare function readRegular(path: string): Promise<Buffer | undefined>;
+export declare function ensureDirectory(path: string, mode: number): Promise<string[]>;
+export declare function writeAtomic(path: string, content: Buffer, mode: number): Promise<void>;

package/dist/safe-fs.js

@@ -0,0 +1,113 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { chmod, lstat, mkdir, open, readFile, rename, rm } from "node:fs/promises";
+import { basename, dirname, join, parse, resolve, sep } from "node:path";
+export class LifecycleError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export async function lstatSafe(path) {
+    try {
+        return await lstat(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+export async function assertSafePath(path, options = {}) {
+    const target = resolve(path);
+    const parsed = parse(target);
+    let current = parsed.root;
+    const pieces = target.slice(parsed.root.length).split(sep).filter(Boolean);
+    for (let index = 0; index < pieces.length; index += 1) {
+        current = join(current, pieces[index]);
+        const metadata = await lstatSafe(current);
+        if (!metadata) {
+            if (options.allowMissing !== false)
+                return;
+            throw new LifecycleError("unsafe_path", `Required path is missing: ${current}`);
+        }
+        if (metadata.isSymbolicLink())
+            throw new LifecycleError("unsafe_path", `Symlink is not allowed: ${current}`);
+        const final = index === pieces.length - 1;
+        if (!final && !metadata.isDirectory())
+            throw new LifecycleError("unsafe_path", `Path parent is not a directory: ${current}`);
+        if (final && options.target === "file" && !metadata.isFile())
+            throw new LifecycleError("unsafe_path", `Target is not a regular file: ${current}`);
+        if (final && options.target === "directory" && !metadata.isDirectory())
+            throw new LifecycleError("unsafe_path", `Target is not a directory: ${current}`);
+    }
+}
+export async function readRegular(path) {
+    await assertSafePath(path);
+    const metadata = await lstatSafe(path);
+    if (!metadata)
+        return undefined;
+    if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.nlink !== 1) {
+        throw new LifecycleError("unsafe_path", `Target is not a single-link regular file: ${path}`);
+    }
+    return readFile(path);
+}
+export async function ensureDirectory(path, mode) {
+    const target = resolve(path);
+    const parsed = parse(target);
+    let current = parsed.root;
+    const created = [];
+    for (const piece of target.slice(parsed.root.length).split(sep).filter(Boolean)) {
+        current = join(current, piece);
+        const metadata = await lstatSafe(current);
+        if (metadata) {
+            if (!metadata.isDirectory() || metadata.isSymbolicLink())
+                throw new LifecycleError("unsafe_path", `Unsafe directory: ${current}`);
+            continue;
+        }
+        try {
+            await mkdir(current, { mode });
+            created.push(current);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const raced = await lstat(current);
+            if (!raced.isDirectory() || raced.isSymbolicLink())
+                throw new LifecycleError("unsafe_path", `Unsafe directory: ${current}`);
+        }
+    }
+    return created;
+}
+export async function writeAtomic(path, content, mode) {
+    await ensureDirectory(dirname(path), 0o700);
+    await assertSafePath(path);
+    const current = await lstatSafe(path);
+    if (current && (!current.isFile() || current.isSymbolicLink() || current.nlink !== 1)) {
+        throw new LifecycleError("unsafe_path", `Target is not a single-link regular file: ${path}`);
+    }
+    const temporary = join(dirname(path), `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
+    const handle = await open(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, mode);
+    try {
+        await handle.writeFile(content);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    try {
+        await chmod(temporary, mode);
+        await rename(temporary, path);
+        const directory = await open(dirname(path), constants.O_RDONLY | constants.O_DIRECTORY);
+        try {
+            await directory.sync();
+        }
+        finally {
+            await directory.close();
+        }
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@kisev/safe-fs",
+  "version": "1.0.0-dev.46.gfbe1e4c6992e",
+  "description": "Safe filesystem primitives: private atomic writes and symlink-free path traversal.",
+  "homepage": "https://github.com/kisev/skills#readme",
+  "bugs": {
+    "url": "https://github.com/kisev/skills/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kisev/skills.git",
+    "directory": "packages/safe-fs"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "README.ru.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "node scripts/clean-dist.mjs && tsc --project tsconfig.json",
+    "pack:check": "node test/pack-allowlist.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "22.15.30",
+    "typescript": "7.0.2"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}