@hyperfrontend/project-scope 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.3](https://github.com/AndrewRedican/hyperfrontend/compare/5f116abb8ba6355dfb283fa03b7481e5eb029480...7fb26b6a30c007cd0392f1fc973265c3d25e16dd) - 2026-06-28
+
+### Bug Fixes
+
+- confine import resolution to the project root
+- reject NUL-byte paths in fs primitives
+
 ## [0.2.2](https://github.com/AndrewRedican/hyperfrontend/compare/d96fee4d4d3a70178c8a01e5f2e2ae675fa23f37...466c0388c4cd516b9c704214140b4df1004098e6) - 2026-06-23
 
 ### Other

package/_shared/core/fs/guard/index.cjs.js

@@ -0,0 +1,7 @@
+'use strict';
+
+function isSafePath(filePath) {
+    return !filePath.includes('\u0000');
+}
+
+exports.isSafePath = isSafePath;

package/_shared/core/fs/guard/index.esm.js

@@ -0,0 +1,5 @@
+function isSafePath(filePath) {
+    return !filePath.includes('\u0000');
+}
+
+export { isSafePath };

package/_shared/core/fs/stat/index.cjs.js

@@ -1,9 +1,10 @@
 'use strict';
 
+const { isSafePath } = require('../guard/index.cjs.js');
 const node_fs = require('node:fs');
 
 function getFileStat(filePath, followSymlinks = true) {
-    if (!node_fs.existsSync(filePath)) {
+    if (!isSafePath(filePath) || !node_fs.existsSync(filePath)) {
         return null;
     }
     try {
@@ -36,7 +37,7 @@ function isSymlink(linkPath) {
     return stats?.isSymlink ?? false;
 }
 function exists(filePath) {
-    return node_fs.existsSync(filePath);
+    return isSafePath(filePath) && node_fs.existsSync(filePath);
 }
 
 exports.getFileStat = getFileStat;

package/_shared/core/fs/stat/index.esm.js

@@ -1,7 +1,8 @@
+import { isSafePath } from '../guard/index.esm.js';
 import { existsSync, statSync, lstatSync } from 'node:fs';
 
 function getFileStat(filePath, followSymlinks = true) {
-    if (!existsSync(filePath)) {
+    if (!isSafePath(filePath) || !existsSync(filePath)) {
         return null;
     }
     try {
@@ -34,7 +35,7 @@ function isSymlink(linkPath) {
     return stats?.isSymlink ?? false;
 }
 function exists(filePath) {
-    return existsSync(filePath);
+    return isSafePath(filePath) && existsSync(filePath);
 }
 
 export { getFileStat, isFile, isDirectory, isSymlink, exists };

package/_shared/core/path/confine/index.cjs.js

@@ -0,0 +1,22 @@
+'use strict';
+
+const { removeTrailingSlash, normalizePath } = require('../normalize/index.cjs.js');
+const node_path = require('node:path');
+const node_fs = require('node:fs');
+
+function contains(root, path) {
+    const base = removeTrailingSlash(root);
+    return path === base || path.startsWith(`${base}/`);
+}
+function isWithinRoot(root, candidate) {
+    if (!contains(normalizePath(node_path.resolve(root)), normalizePath(node_path.resolve(candidate)))) {
+        return false;
+    }
+    if (!node_fs.existsSync(candidate)) {
+        return true;
+    }
+    return contains(normalizePath(node_fs.realpathSync(root)), normalizePath(node_fs.realpathSync(candidate)));
+}
+
+exports.contains = contains;
+exports.isWithinRoot = isWithinRoot;

package/_shared/core/path/confine/index.esm.js

@@ -0,0 +1,19 @@
+import { removeTrailingSlash, normalizePath } from '../normalize/index.esm.js';
+import { existsSync, realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+function contains(root, path) {
+    const base = removeTrailingSlash(root);
+    return path === base || path.startsWith(`${base}/`);
+}
+function isWithinRoot(root, candidate) {
+    if (!contains(normalizePath(resolve(root)), normalizePath(resolve(candidate)))) {
+        return false;
+    }
+    if (!existsSync(candidate)) {
+        return true;
+    }
+    return contains(normalizePath(realpathSync(root)), normalizePath(realpathSync(candidate)));
+}
+
+export { contains, isWithinRoot };

package/cli/index.cjs.js

@@ -14,6 +14,7 @@ const index_cjs_js$6 = require('../_dependencies/@hyperfrontend/immutable-api-ut
 const index_cjs_js$7 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/map/index.cjs.js');
 const index_cjs_js$8 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/math/index.cjs.js');
 const index_cjs_js$9 = require('../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/number/index.cjs.js');
+const { isSafePath } = require('../_shared/core/fs/guard/index.cjs.js');
 const { getFileStat, isDirectory, exists } = require('../_shared/core/fs/stat/index.cjs.js');
 const { join } = require('../_shared/core/path/join/index.cjs.js');
 const { createConfigError } = require('../_shared/core/errors/structured-errors/index.cjs.js');
@@ -233,6 +234,9 @@ function createFileSystemError(message, code, context) {
  * ```
  */
 function readFileContent(filePath, encoding = 'utf-8') {
+    if (!isSafePath(filePath)) {
+        throw createFileSystemError(`Unsafe file path: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read' });
+    }
     if (!node_fs.existsSync(filePath)) {
         fsLogger.debug('File not found', { path: filePath });
         throw createFileSystemError(`File not found: ${filePath}`, 'FS_NOT_FOUND', { path: filePath, operation: 'read' });
@@ -261,7 +265,7 @@ function readFileContent(filePath, encoding = 'utf-8') {
  * ```
  */
 function readFileIfExists(filePath, encoding = 'utf-8') {
-    if (!node_fs.existsSync(filePath)) {
+    if (!isSafePath(filePath) || !node_fs.existsSync(filePath)) {
         return null;
     }
     try {

package/cli/index.esm.js

@@ -12,6 +12,7 @@ import { createError } from '../_dependencies/@hyperfrontend/immutable-api-utils
 import { createMap } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/map/index.esm.js';
 import { min, round } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/math/index.esm.js';
 import { parseInt, parseFloat } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/number/index.esm.js';
+import { isSafePath } from '../_shared/core/fs/guard/index.esm.js';
 import { getFileStat, isDirectory, exists } from '../_shared/core/fs/stat/index.esm.js';
 import { join } from '../_shared/core/path/join/index.esm.js';
 import { createConfigError } from '../_shared/core/errors/structured-errors/index.esm.js';
@@ -231,6 +232,9 @@ function createFileSystemError(message, code, context) {
  * ```
  */
 function readFileContent(filePath, encoding = 'utf-8') {
+    if (!isSafePath(filePath)) {
+        throw createFileSystemError(`Unsafe file path: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read' });
+    }
     if (!existsSync(filePath)) {
         fsLogger.debug('File not found', { path: filePath });
         throw createFileSystemError(`File not found: ${filePath}`, 'FS_NOT_FOUND', { path: filePath, operation: 'read' });
@@ -259,7 +263,7 @@ function readFileContent(filePath, encoding = 'utf-8') {
  * ```
  */
 function readFileIfExists(filePath, encoding = 'utf-8') {
-    if (!existsSync(filePath)) {
+    if (!isSafePath(filePath) || !existsSync(filePath)) {
         return null;
     }
     try {

package/core/fs/index.cjs.js

@@ -9,6 +9,7 @@ const index_cjs_js$2 = require('../../_dependencies/@hyperfrontend/immutable-api
 const index_cjs_js = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/set/index.cjs.js');
 const index_cjs_js$1 = require('../../_dependencies/@hyperfrontend/logging/index.cjs.js');
 const index_cjs_js$6 = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.cjs.js');
+const { isSafePath } = require('../../_shared/core/fs/guard/index.cjs.js');
 const { getFileStat, isFile, isDirectory, isSymlink, exists } = require('../../_shared/core/fs/stat/index.cjs.js');
 const { join } = require('../../_shared/core/path/join/index.cjs.js');
 
@@ -197,6 +198,9 @@ function createFileSystemError(message, code, context) {
  * ```
  */
 function readFileContent(filePath, encoding = 'utf-8') {
+    if (!isSafePath(filePath)) {
+        throw createFileSystemError(`Unsafe file path: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read' });
+    }
     if (!node_fs.existsSync(filePath)) {
         fsLogger.debug('File not found', { path: filePath });
         throw createFileSystemError(`File not found: ${filePath}`, 'FS_NOT_FOUND', { path: filePath, operation: 'read' });
@@ -223,6 +227,9 @@ function readFileContent(filePath, encoding = 'utf-8') {
  * ```
  */
 function readFileBuffer(filePath) {
+    if (!isSafePath(filePath)) {
+        throw createFileSystemError(`Unsafe file path: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read' });
+    }
     if (!node_fs.existsSync(filePath)) {
         throw createFileSystemError(`File not found: ${filePath}`, 'FS_NOT_FOUND', { path: filePath, operation: 'read' });
     }
@@ -249,7 +256,7 @@ function readFileBuffer(filePath) {
  * ```
  */
 function readFileIfExists(filePath, encoding = 'utf-8') {
-    if (!node_fs.existsSync(filePath)) {
+    if (!isSafePath(filePath) || !node_fs.existsSync(filePath)) {
         return null;
     }
     try {
@@ -281,6 +288,9 @@ function readFileIfExists(filePath, encoding = 'utf-8') {
  * ```
  */
 function readJsonFile(filePath, options) {
+    if (!isSafePath(filePath)) {
+        throw createFileSystemError(`Unsafe file path: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read' });
+    }
     if (!node_fs.existsSync(filePath)) {
         if (options && 'default' in options) {
             fsLogger.debug('JSON file not found, using default', { path: filePath });
@@ -320,7 +330,7 @@ function readJsonFile(filePath, options) {
  * ```
  */
 function readJsonFileIfExists(filePath) {
-    if (!node_fs.existsSync(filePath)) {
+    if (!isSafePath(filePath) || !node_fs.existsSync(filePath)) {
         return null;
     }
     try {

package/core/fs/index.esm.js

@@ -7,6 +7,7 @@ import { freeze, entries, keys, defineProperties } from '../../_dependencies/@hy
 import { createSet } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/set/index.esm.js';
 import { createLogger } from '../../_dependencies/@hyperfrontend/logging/index.esm.js';
 import { createError } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.esm.js';
+import { isSafePath } from '../../_shared/core/fs/guard/index.esm.js';
 import { getFileStat, isFile, isDirectory, isSymlink, exists } from '../../_shared/core/fs/stat/index.esm.js';
 import { join } from '../../_shared/core/path/join/index.esm.js';
 
@@ -195,6 +196,9 @@ function createFileSystemError(message, code, context) {
  * ```
  */
 function readFileContent(filePath, encoding = 'utf-8') {
+    if (!isSafePath(filePath)) {
+        throw createFileSystemError(`Unsafe file path: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read' });
+    }
     if (!existsSync(filePath)) {
         fsLogger.debug('File not found', { path: filePath });
         throw createFileSystemError(`File not found: ${filePath}`, 'FS_NOT_FOUND', { path: filePath, operation: 'read' });
@@ -221,6 +225,9 @@ function readFileContent(filePath, encoding = 'utf-8') {
  * ```
  */
 function readFileBuffer(filePath) {
+    if (!isSafePath(filePath)) {
+        throw createFileSystemError(`Unsafe file path: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read' });
+    }
     if (!existsSync(filePath)) {
         throw createFileSystemError(`File not found: ${filePath}`, 'FS_NOT_FOUND', { path: filePath, operation: 'read' });
     }
@@ -247,7 +254,7 @@ function readFileBuffer(filePath) {
  * ```
  */
 function readFileIfExists(filePath, encoding = 'utf-8') {
-    if (!existsSync(filePath)) {
+    if (!isSafePath(filePath) || !existsSync(filePath)) {
         return null;
     }
     try {
@@ -279,6 +286,9 @@ function readFileIfExists(filePath, encoding = 'utf-8') {
  * ```
  */
 function readJsonFile(filePath, options) {
+    if (!isSafePath(filePath)) {
+        throw createFileSystemError(`Unsafe file path: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read' });
+    }
     if (!existsSync(filePath)) {
         if (options && 'default' in options) {
             fsLogger.debug('JSON file not found, using default', { path: filePath });
@@ -318,7 +328,7 @@ function readJsonFile(filePath, options) {
  * ```
  */
 function readJsonFileIfExists(filePath) {
-    if (!existsSync(filePath)) {
+    if (!isSafePath(filePath) || !existsSync(filePath)) {
         return null;
     }
     try {

package/core/index.cjs.js

@@ -12,9 +12,10 @@ const index_cjs_js$7 = require('../_dependencies/@hyperfrontend/immutable-api-ut
 const node_fs = require('node:fs');
 const node_path = require('node:path');
 const node_os = require('node:os');
+const { isSafePath } = require('../_shared/core/fs/guard/index.cjs.js');
 const { getFileStat, isFile, isDirectory, isSymlink, exists } = require('../_shared/core/fs/stat/index.cjs.js');
-const { join, joinPosix } = require('../_shared/core/path/join/index.cjs.js');
 const { normalizePath, normalizeToForwardSlashes, normalizeToNative, removeTrailingSlash, ensureTrailingSlash } = require('../_shared/core/path/normalize/index.cjs.js');
+const { join, joinPosix } = require('../_shared/core/path/join/index.cjs.js');
 const { resolvePath, resolveFromWorkspace, resolveRealPath, relativePath, joinPath, isAbsolute, offsetFromRoot } = require('../_shared/core/path/resolve/index.cjs.js');
 const { pathSegments, getBasename, getDirname, getExtension, getFileNameWithoutExtension, parsePath } = require('../_shared/core/path/segments/index.cjs.js');
 const { createStructuredError, createConfigError, createFsError, createParseError, createValidationError } = require('../_shared/core/errors/structured-errors/index.cjs.js');
@@ -512,6 +513,9 @@ function createFileSystemError(message, code, context) {
  * ```
  */
 function readFileContent(filePath, encoding = 'utf-8') {
+    if (!isSafePath(filePath)) {
+        throw createFileSystemError(`Unsafe file path: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read' });
+    }
     if (!node_fs.existsSync(filePath)) {
         fsLogger.debug('File not found', { path: filePath });
         throw createFileSystemError(`File not found: ${filePath}`, 'FS_NOT_FOUND', { path: filePath, operation: 'read' });
@@ -538,6 +542,9 @@ function readFileContent(filePath, encoding = 'utf-8') {
  * ```
  */
 function readFileBuffer(filePath) {
+    if (!isSafePath(filePath)) {
+        throw createFileSystemError(`Unsafe file path: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read' });
+    }
     if (!node_fs.existsSync(filePath)) {
         throw createFileSystemError(`File not found: ${filePath}`, 'FS_NOT_FOUND', { path: filePath, operation: 'read' });
     }
@@ -564,7 +571,7 @@ function readFileBuffer(filePath) {
  * ```
  */
 function readFileIfExists(filePath, encoding = 'utf-8') {
-    if (!node_fs.existsSync(filePath)) {
+    if (!isSafePath(filePath) || !node_fs.existsSync(filePath)) {
         return null;
     }
     try {
@@ -596,6 +603,9 @@ function readFileIfExists(filePath, encoding = 'utf-8') {
  * ```
  */
 function readJsonFile(filePath, options) {
+    if (!isSafePath(filePath)) {
+        throw createFileSystemError(`Unsafe file path: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read' });
+    }
     if (!node_fs.existsSync(filePath)) {
         if (options && 'default' in options) {
             fsLogger.debug('JSON file not found, using default', { path: filePath });
@@ -635,7 +645,7 @@ function readJsonFile(filePath, options) {
  * ```
  */
 function readJsonFileIfExists(filePath) {
-    if (!node_fs.existsSync(filePath)) {
+    if (!isSafePath(filePath) || !node_fs.existsSync(filePath)) {
         return null;
     }
     try {

package/core/index.esm.js

@@ -8,11 +8,12 @@ import { stringify, parse } from '../_dependencies/@hyperfrontend/immutable-api-
 import { createLogger } from '../_dependencies/@hyperfrontend/logging/index.esm.js';
 import { min } from '../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/math/index.esm.js';
 import { existsSync, readFileSync, statSync, lstatSync, mkdirSync, readdirSync, rmSync, realpathSync, writeFileSync, mkdtempSync, unlinkSync, rmdirSync } from 'node:fs';
-import { join as join$1, posix, normalize, sep, isAbsolute as isAbsolute$1, relative, resolve, basename, dirname, extname, parse as parse$1 } from 'node:path';
+import { join as join$1, normalize, sep, posix, isAbsolute as isAbsolute$1, relative, resolve, basename, dirname, extname, parse as parse$1 } from 'node:path';
 import { tmpdir, platform, arch } from 'node:os';
+import { isSafePath } from '../_shared/core/fs/guard/index.esm.js';
 import { getFileStat, isFile, isDirectory, isSymlink, exists } from '../_shared/core/fs/stat/index.esm.js';
-import { join, joinPosix } from '../_shared/core/path/join/index.esm.js';
 import { normalizePath, normalizeToForwardSlashes, normalizeToNative, removeTrailingSlash, ensureTrailingSlash } from '../_shared/core/path/normalize/index.esm.js';
+import { join, joinPosix } from '../_shared/core/path/join/index.esm.js';
 import { resolvePath, resolveFromWorkspace, resolveRealPath, relativePath, joinPath, isAbsolute, offsetFromRoot } from '../_shared/core/path/resolve/index.esm.js';
 import { pathSegments, getBasename, getDirname, getExtension, getFileNameWithoutExtension, parsePath } from '../_shared/core/path/segments/index.esm.js';
 import { createStructuredError, createConfigError, createFsError, createParseError, createValidationError } from '../_shared/core/errors/structured-errors/index.esm.js';
@@ -510,6 +511,9 @@ function createFileSystemError(message, code, context) {
  * ```
  */
 function readFileContent(filePath, encoding = 'utf-8') {
+    if (!isSafePath(filePath)) {
+        throw createFileSystemError(`Unsafe file path: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read' });
+    }
     if (!existsSync(filePath)) {
         fsLogger.debug('File not found', { path: filePath });
         throw createFileSystemError(`File not found: ${filePath}`, 'FS_NOT_FOUND', { path: filePath, operation: 'read' });
@@ -536,6 +540,9 @@ function readFileContent(filePath, encoding = 'utf-8') {
  * ```
  */
 function readFileBuffer(filePath) {
+    if (!isSafePath(filePath)) {
+        throw createFileSystemError(`Unsafe file path: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read' });
+    }
     if (!existsSync(filePath)) {
         throw createFileSystemError(`File not found: ${filePath}`, 'FS_NOT_FOUND', { path: filePath, operation: 'read' });
     }
@@ -562,7 +569,7 @@ function readFileBuffer(filePath) {
  * ```
  */
 function readFileIfExists(filePath, encoding = 'utf-8') {
-    if (!existsSync(filePath)) {
+    if (!isSafePath(filePath) || !existsSync(filePath)) {
         return null;
     }
     try {
@@ -594,6 +601,9 @@ function readFileIfExists(filePath, encoding = 'utf-8') {
  * ```
  */
 function readJsonFile(filePath, options) {
+    if (!isSafePath(filePath)) {
+        throw createFileSystemError(`Unsafe file path: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read' });
+    }
     if (!existsSync(filePath)) {
         if (options && 'default' in options) {
             fsLogger.debug('JSON file not found, using default', { path: filePath });
@@ -633,7 +643,7 @@ function readJsonFile(filePath, options) {
  * ```
  */
 function readJsonFileIfExists(filePath) {
-    if (!existsSync(filePath)) {
+    if (!isSafePath(filePath) || !existsSync(filePath)) {
         return null;
     }
     try {

package/core/path/index.cjs.js

@@ -1,9 +1,10 @@
 'use strict';
 
-const node_path = require('node:path');
 const node_fs = require('node:fs');
-const { join, joinPosix } = require('../../_shared/core/path/join/index.cjs.js');
+const node_path = require('node:path');
 const { normalizePath, normalizeToForwardSlashes, normalizeToNative, removeTrailingSlash, ensureTrailingSlash } = require('../../_shared/core/path/normalize/index.cjs.js');
+const { isWithinRoot } = require('../../_shared/core/path/confine/index.cjs.js');
+const { join, joinPosix } = require('../../_shared/core/path/join/index.cjs.js');
 const { resolvePath, resolveFromWorkspace, resolveRealPath, relativePath, joinPath, isAbsolute, offsetFromRoot } = require('../../_shared/core/path/resolve/index.cjs.js');
 const { pathSegments, getBasename, getDirname, getExtension, getFileNameWithoutExtension, parsePath } = require('../../_shared/core/path/segments/index.cjs.js');
 
@@ -13,6 +14,7 @@ exports.getDirname = getDirname;
 exports.getExtension = getExtension;
 exports.getFileNameWithoutExtension = getFileNameWithoutExtension;
 exports.isAbsolute = isAbsolute;
+exports.isWithinRoot = isWithinRoot;
 exports.join = join;
 exports.joinPath = joinPath;
 exports.joinPosix = joinPosix;

package/core/path/index.d.ts

@@ -99,6 +99,27 @@ declare function getFileNameWithoutExtension(filePath: string): string;
  */
 declare function parsePath(filePath: string): ParsedPath;
 
+/**
+ * Reports whether `candidate` resolves to a location inside `root`.
+ *
+ * The lexical check runs first and rejects `..` traversal and absolute escapes
+ * with no filesystem access at all, so a hostile path is never stat-ed. Only a
+ * path that is already lexically contained is then resolved through symlinks, so
+ * an in-tree link cannot tunnel outside the root — and that realpath touches
+ * only paths the caller would legitimately read anyway.
+ *
+ * @param root - The directory the candidate must stay within.
+ * @param candidate - The path to validate (resolved relative to the cwd if not absolute).
+ * @returns True when the candidate is the root or contained within it.
+ *
+ * @example Confining a resolved import target
+ * ```typescript
+ * isWithinRoot('/project', '/project/src/index.ts') // true
+ * isWithinRoot('/project', '/project/../etc/passwd') // false
+ * ```
+ */
+declare function isWithinRoot(root: string, candidate: string): boolean;
+
 /**
  * Join path segments.
  * Uses platform-specific separators (e.g., / or \).
@@ -302,5 +323,5 @@ declare function isAbsolute(filePath: string): boolean;
  */
 declare function offsetFromRoot(filePath: string): string;
 
-export { ensureTrailingSlash, getBasename, getDirname, getExtension, getFileNameWithoutExtension, isAbsolute, join, joinPath, joinPosix, normalizePath, normalizeToForwardSlashes, normalizeToNative, offsetFromRoot, parsePath, pathSegments, relativePath, removeTrailingSlash, resolveFromWorkspace, resolvePath, resolveRealPath };
+export { ensureTrailingSlash, getBasename, getDirname, getExtension, getFileNameWithoutExtension, isAbsolute, isWithinRoot, join, joinPath, joinPosix, normalizePath, normalizeToForwardSlashes, normalizeToNative, offsetFromRoot, parsePath, pathSegments, relativePath, removeTrailingSlash, resolveFromWorkspace, resolvePath, resolveRealPath };
 export type { ParsedPath };

package/core/path/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/project-scope/src/core/path/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAA;AACxC,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACnI,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,cAAc,EAAE,YAAY,EAAE,oBAAoB,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAClI,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,2BAA2B,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/project-scope/src/core/path/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AACxC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAA;AACxC,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACnI,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,cAAc,EAAE,YAAY,EAAE,oBAAoB,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAClI,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,2BAA2B,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA"}

package/core/path/index.esm.js

@@ -1,8 +1,9 @@
-import { join as join$1, posix, normalize, sep, isAbsolute as isAbsolute$1, relative, resolve, basename, dirname, extname, parse } from 'node:path';
 import { existsSync, realpathSync } from 'node:fs';
-import { join, joinPosix } from '../../_shared/core/path/join/index.esm.js';
+import { normalize, sep, resolve, join as join$1, posix, isAbsolute as isAbsolute$1, relative, basename, dirname, extname, parse } from 'node:path';
 import { normalizePath, normalizeToForwardSlashes, normalizeToNative, removeTrailingSlash, ensureTrailingSlash } from '../../_shared/core/path/normalize/index.esm.js';
+import { isWithinRoot } from '../../_shared/core/path/confine/index.esm.js';
+import { join, joinPosix } from '../../_shared/core/path/join/index.esm.js';
 import { resolvePath, resolveFromWorkspace, resolveRealPath, relativePath, joinPath, isAbsolute, offsetFromRoot } from '../../_shared/core/path/resolve/index.esm.js';
 import { pathSegments, getBasename, getDirname, getExtension, getFileNameWithoutExtension, parsePath } from '../../_shared/core/path/segments/index.esm.js';
 
-export { ensureTrailingSlash, getBasename, getDirname, getExtension, getFileNameWithoutExtension, isAbsolute, join, joinPath, joinPosix, normalizePath, normalizeToForwardSlashes, normalizeToNative, offsetFromRoot, parsePath, pathSegments, relativePath, removeTrailingSlash, resolveFromWorkspace, resolvePath, resolveRealPath };
+export { ensureTrailingSlash, getBasename, getDirname, getExtension, getFileNameWithoutExtension, isAbsolute, isWithinRoot, join, joinPath, joinPosix, normalizePath, normalizeToForwardSlashes, normalizeToNative, offsetFromRoot, parsePath, pathSegments, relativePath, removeTrailingSlash, resolveFromWorkspace, resolvePath, resolveRealPath };

package/heuristics/dependencies/index.cjs.js

@@ -10,7 +10,9 @@ const index_cjs_js$3 = require('../../_dependencies/@hyperfrontend/immutable-api
 const index_cjs_js$5 = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/json/index.cjs.js');
 const index_cjs_js$1 = require('../../_dependencies/@hyperfrontend/logging/index.cjs.js');
 const index_cjs_js$6 = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.cjs.js');
+const { isSafePath } = require('../../_shared/core/fs/guard/index.cjs.js');
 const { isFile, isDirectory, exists } = require('../../_shared/core/fs/stat/index.cjs.js');
+const { isWithinRoot } = require('../../_shared/core/path/confine/index.cjs.js');
 
 /**
  * Global log level registry.
@@ -197,6 +199,9 @@ function createFileSystemError(message, code, context) {
  * ```
  */
 function readFileContent(filePath, encoding = 'utf-8') {
+    if (!isSafePath(filePath)) {
+        throw createFileSystemError(`Unsafe file path: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read' });
+    }
     if (!node_fs.existsSync(filePath)) {
         fsLogger.debug('File not found', { path: filePath });
         throw createFileSystemError(`File not found: ${filePath}`, 'FS_NOT_FOUND', { path: filePath, operation: 'read' });
@@ -225,7 +230,7 @@ function readFileContent(filePath, encoding = 'utf-8') {
  * ```
  */
 function readFileIfExists(filePath, encoding = 'utf-8') {
-    if (!node_fs.existsSync(filePath)) {
+    if (!isSafePath(filePath) || !node_fs.existsSync(filePath)) {
         return null;
     }
     try {
@@ -434,6 +439,10 @@ function resolveImportPath(importPath, fromFile, projectPath, extensions) {
     }
     const fromDir = node_path.dirname(fromFile);
     const absolutePath = node_path.resolve(fromDir, importPath);
+    // why: An import string comes from untrusted source code; reject targets that escape the project root before any stat, so a hostile `../../etc/passwd` can't probe the filesystem.
+    if (!isWithinRoot(projectPath, absolutePath)) {
+        return null;
+    }
     if (exists(absolutePath)) {
         if (isFile(absolutePath)) {
             return node_path.relative(projectPath, absolutePath);

package/heuristics/dependencies/index.esm.js

@@ -1,14 +1,16 @@
-import { join, relative, dirname, resolve } from 'node:path';
+import { join, normalize, sep, resolve, relative, dirname } from 'node:path';
 import { createMap } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/map/index.esm.js';
 import { freeze, entries, keys, defineProperties, values } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/object/index.esm.js';
 import { createSet } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/set/index.esm.js';
-import { existsSync, readFileSync, statSync, lstatSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, statSync, lstatSync, readdirSync, realpathSync } from 'node:fs';
 import { isArray } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/array/index.esm.js';
 import { error, warn, log, info, debug } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/console/index.esm.js';
 import { stringify, parse } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/json/index.esm.js';
 import { createLogger } from '../../_dependencies/@hyperfrontend/logging/index.esm.js';
 import { createError } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.esm.js';
+import { isSafePath } from '../../_shared/core/fs/guard/index.esm.js';
 import { isFile, isDirectory, exists } from '../../_shared/core/fs/stat/index.esm.js';
+import { isWithinRoot } from '../../_shared/core/path/confine/index.esm.js';
 
 /**
  * Global log level registry.
@@ -195,6 +197,9 @@ function createFileSystemError(message, code, context) {
  * ```
  */
 function readFileContent(filePath, encoding = 'utf-8') {
+    if (!isSafePath(filePath)) {
+        throw createFileSystemError(`Unsafe file path: ${filePath}`, 'FS_READ_ERROR', { path: filePath, operation: 'read' });
+    }
     if (!existsSync(filePath)) {
         fsLogger.debug('File not found', { path: filePath });
         throw createFileSystemError(`File not found: ${filePath}`, 'FS_NOT_FOUND', { path: filePath, operation: 'read' });
@@ -223,7 +228,7 @@ function readFileContent(filePath, encoding = 'utf-8') {
  * ```
  */
 function readFileIfExists(filePath, encoding = 'utf-8') {
-    if (!existsSync(filePath)) {
+    if (!isSafePath(filePath) || !existsSync(filePath)) {
         return null;
     }
     try {
@@ -432,6 +437,10 @@ function resolveImportPath(importPath, fromFile, projectPath, extensions) {
     }
     const fromDir = dirname(fromFile);
     const absolutePath = resolve(fromDir, importPath);
+    // why: An import string comes from untrusted source code; reject targets that escape the project root before any stat, so a hostile `../../etc/passwd` can't probe the filesystem.
+    if (!isWithinRoot(projectPath, absolutePath)) {
+        return null;
+    }
     if (exists(absolutePath)) {
         if (isFile(absolutePath)) {
             return relative(projectPath, absolutePath);

package/heuristics/entry-points/index.cjs.js

@@ -10,6 +10,7 @@ const index_cjs_js$4 = require('../../_dependencies/@hyperfrontend/immutable-api
 const index_cjs_js$6 = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/json/index.cjs.js');
 const index_cjs_js$3 = require('../../_dependencies/@hyperfrontend/logging/index.cjs.js');
 const index_cjs_js$7 = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.cjs.js');
+const { isSafePath } = require('../../_shared/core/fs/guard/index.cjs.js');
 const { isDirectory, exists } = require('../../_shared/core/fs/stat/index.cjs.js');
 const { createCache } = require('../../_shared/core/cache/index.cjs.js');
 const { matchGlobPattern } = require('../../_shared/core/patterns/glob/index.cjs.js');
@@ -198,7 +199,7 @@ function createFileSystemError(message, code, context) {
  * ```
  */
 function readFileIfExists(filePath, encoding = 'utf-8') {
-    if (!node_fs.existsSync(filePath)) {
+    if (!isSafePath(filePath) || !node_fs.existsSync(filePath)) {
         return null;
     }
     try {

package/heuristics/entry-points/index.esm.js

@@ -8,6 +8,7 @@ import { error, warn, log, info, debug } from '../../_dependencies/@hyperfronten
 import { stringify, parse } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/json/index.esm.js';
 import { createLogger } from '../../_dependencies/@hyperfrontend/logging/index.esm.js';
 import { createError } from '../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.esm.js';
+import { isSafePath } from '../../_shared/core/fs/guard/index.esm.js';
 import { isDirectory, exists } from '../../_shared/core/fs/stat/index.esm.js';
 import { createCache } from '../../_shared/core/cache/index.esm.js';
 import { matchGlobPattern } from '../../_shared/core/patterns/glob/index.esm.js';
@@ -196,7 +197,7 @@ function createFileSystemError(message, code, context) {
  * ```
  */
 function readFileIfExists(filePath, encoding = 'utf-8') {
-    if (!existsSync(filePath)) {
+    if (!isSafePath(filePath) || !existsSync(filePath)) {
         return null;
     }
     try {

package/heuristics/framework/index.cjs.js

@@ -11,6 +11,7 @@ const node_path = require('node:path');
 const index_cjs_js$7 = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.cjs.js');
 const node_fs = require('node:fs');
 const index_cjs_js$8 = require('../../_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/math/index.cjs.js');
+const { isSafePath } = require('../../_shared/core/fs/guard/index.cjs.js');
 const { isDirectory, exists } = require('../../_shared/core/fs/stat/index.cjs.js');
 const { join } = require('../../_shared/core/path/join/index.cjs.js');
 const { createCache } = require('../../_shared/core/cache/index.cjs.js');
@@ -201,7 +202,7 @@ function createFileSystemError(message, code, context) {
  * ```
  */
 function readFileIfExists(filePath, encoding = 'utf-8') {
-    if (!node_fs.existsSync(filePath)) {
+    if (!isSafePath(filePath) || !node_fs.existsSync(filePath)) {
         return null;
     }
     try {