@j0hanz/filesystem-mcp 1.19.1 → 2.0.0

package/dist/core/path-utils.d.ts

@@ -0,0 +1,9 @@
+export declare function getReservedDeviceNameForPath(requestedPath: string): string | undefined;
+export declare function isWindowsDriveRelativePath(requestedPath: string): boolean;
+export declare function normalizePath(p: string): string;
+export declare const IS_CASE_INSENSITIVE_FS: boolean;
+export declare function isSamePath(left: string, right: string): boolean;
+export declare function normalizeAllowedDirectory(dir: string): string;
+export declare function isPathInsideDirectory(normalizedDirectory: string, normalizedCandidate: string): boolean;
+export declare function isPathWithinDirectories(normalizedPath: string, allowedDirs: readonly string[]): boolean;
+//# sourceMappingURL=path-utils.d.ts.map

package/dist/core/path-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-utils.d.ts","sourceRoot":"","sources":["../../src/core/path-utils.ts"],"names":[],"mappings":"AAwCA,wBAAgB,4BAA4B,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAStF;AAED,wBAAgB,0BAA0B,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAkBzE;AAUD,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAa/C;AAED,eAAO,MAAM,sBAAsB,SAAwC,CAAC;AAM5E,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAO/D;AAED,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAa7D;AAED,wBAAgB,qBAAqB,CACnC,mBAAmB,EAAE,MAAM,EAC3B,mBAAmB,EAAE,MAAM,GAC1B,OAAO,CAST;AAED,wBAAgB,uBAAuB,CACrC,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B,OAAO,CAET"}

package/dist/core/path-utils.js

@@ -0,0 +1,121 @@
+import { homedir, platform } from 'node:os';
+import { join, parse, resolve, sep } from 'node:path';
+import { IS_WINDOWS, isAlpha, isSlash } from './primitives.js';
+const CHAR_COLON = 58;
+const HOMEDIR = homedir();
+const RESERVED_DEVICE_NAMES = new Set([
+    'CON',
+    'PRN',
+    'AUX',
+    'NUL',
+    'COM1',
+    'COM2',
+    'COM3',
+    'COM4',
+    'COM5',
+    'COM6',
+    'COM7',
+    'COM8',
+    'COM9',
+    'LPT1',
+    'LPT2',
+    'LPT3',
+    'LPT4',
+    'LPT5',
+    'LPT6',
+    'LPT7',
+    'LPT8',
+    'LPT9',
+]);
+function getReservedDeviceName(segment) {
+    const trimmed = segment.replace(/[. ]+$/, '');
+    const withoutStream = trimmed.split(':')[0] ?? '';
+    const baseName = (withoutStream.split('.')[0] ?? '').toUpperCase();
+    return RESERVED_DEVICE_NAMES.has(baseName) ? baseName : undefined;
+}
+export function getReservedDeviceNameForPath(requestedPath) {
+    const segments = requestedPath.split(/[\\/]/u);
+    for (const segment of segments) {
+        const reserved = getReservedDeviceName(segment);
+        if (reserved) {
+            return reserved;
+        }
+    }
+    return undefined;
+}
+export function isWindowsDriveRelativePath(requestedPath) {
+    // Check on all platforms so cross-platform clients cannot smuggle drive-relative
+    // inputs (e.g. C:relative) to a POSIX-hosted server where path.resolve would
+    // silently expand them relative to CWD.
+    if (requestedPath.length < 2) {
+        return false;
+    }
+    if (requestedPath.charCodeAt(1) !== CHAR_COLON) {
+        return false;
+    }
+    if (!isAlpha(requestedPath.charCodeAt(0))) {
+        return false;
+    }
+    if (requestedPath.length === 2) {
+        return true;
+    }
+    return !isSlash(requestedPath.charCodeAt(2));
+}
+function expandHome(filepath) {
+    if (filepath === '~' || filepath.startsWith('~/') || filepath.startsWith('~\\')) {
+        const rest = filepath.slice(1).replace(/^[/\\]+/, '');
+        return rest ? join(HOMEDIR, rest) : HOMEDIR;
+    }
+    return filepath;
+}
+export function normalizePath(p) {
+    const resolved = resolve(expandHome(p));
+    // On Windows only the drive letter is lowercased (e.g. "C:\Foo\Bar").
+    // The rest of the path retains its original casing.
+    // IMPORTANT: callers must use isSamePath / isPathInsideDirectory for all
+    // equality and containment checks — never raw string equality — because
+    // those helpers apply full case-folding before comparing.
+    if (IS_WINDOWS && resolved.length >= 2 && resolved.charCodeAt(1) === CHAR_COLON) {
+        return resolved.charAt(0).toLowerCase() + resolved.slice(1);
+    }
+    return resolved;
+}
+export const IS_CASE_INSENSITIVE_FS = IS_WINDOWS || platform() === 'darwin';
+function normalizeCaseForComparison(value) {
+    return IS_CASE_INSENSITIVE_FS ? value.toLowerCase() : value;
+}
+export function isSamePath(left, right) {
+    if (left === right) {
+        return true;
+    }
+    const leftResolved = normalizeCaseForComparison(resolve(left));
+    const rightResolved = normalizeCaseForComparison(resolve(right));
+    return leftResolved === rightResolved;
+}
+export function normalizeAllowedDirectory(dir) {
+    const trimmed = dir.trim();
+    if (trimmed.length === 0)
+        return '';
+    const normalized = normalizePath(trimmed);
+    const { root } = parse(normalized);
+    // Keep filesystem roots as-is ("/", "c:\\", "\\\\server\\share\\").
+    if (isSamePath(normalized, root)) {
+        return root;
+    }
+    return normalized.length > 1 && normalized.endsWith(sep) ? normalized.slice(0, -1) : normalized;
+}
+export function isPathInsideDirectory(normalizedDirectory, normalizedCandidate) {
+    const root = normalizeCaseForComparison(normalizedDirectory);
+    const candidate = normalizeCaseForComparison(normalizedCandidate);
+    if (root === candidate)
+        return true;
+    if (!candidate.startsWith(root))
+        return false;
+    if (isSlash(root.charCodeAt(root.length - 1)))
+        return true;
+    return isSlash(candidate.charCodeAt(root.length));
+}
+export function isPathWithinDirectories(normalizedPath, allowedDirs) {
+    return allowedDirs.some((dir) => isPathInsideDirectory(dir, normalizedPath));
+}
+//# sourceMappingURL=path-utils.js.map

package/dist/core/path-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-utils.js","sourceRoot":"","sources":["../../src/core/path-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAEtD,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE/D,MAAM,UAAU,GAAG,EAAE,CAAC;AACtB,MAAM,OAAO,GAAG,OAAO,EAAE,CAAC;AAE1B,MAAM,qBAAqB,GAAG,IAAI,GAAG,CAAS;IAC5C,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;CACP,CAAC,CAAC;AAEH,SAAS,qBAAqB,CAAC,OAAe;IAC5C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IAC9C,MAAM,aAAa,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAClD,MAAM,QAAQ,GAAG,CAAC,aAAa,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IACnE,OAAO,qBAAqB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;AACpE,CAAC;AAED,MAAM,UAAU,4BAA4B,CAAC,aAAqB;IAChE,MAAM,QAAQ,GAAG,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC/C,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,QAAQ,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC;QAChD,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO,QAAQ,CAAC;QAClB,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,0BAA0B,CAAC,aAAqB;IAC9D,iFAAiF;IACjF,6EAA6E;IAC7E,wCAAwC;IACxC,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,UAAU,EAAE,CAAC;QAC/C,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,SAAS,UAAU,CAAC,QAAgB;IAClC,IAAI,QAAQ,KAAK,GAAG,IAAI,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAChF,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QACtD,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;IAC9C,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,CAAS;IACrC,MAAM,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IAExC,sEAAsE;IACtE,oDAAoD;IACpD,yEAAyE;IACzE,wEAAwE;IACxE,0DAA0D;IAC1D,IAAI,UAAU,IAAI,QAAQ,CAAC,MAAM,IAAI,CAAC,IAAI,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,UAAU,EAAE,CAAC;QAChF,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,CAAC,MAAM,sBAAsB,GAAG,UAAU,IAAI,QAAQ,EAAE,KAAK,QAAQ,CAAC;AAE5E,SAAS,0BAA0B,CAAC,KAAa;IAC/C,OAAO,sBAAsB,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;AAC9D,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,KAAa;IACpD,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,YAAY,GAAG,0BAA0B,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IAC/D,MAAM,aAAa,GAAG,0BAA0B,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IACjE,OAAO,YAAY,KAAK,aAAa,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,GAAW;IACnD,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEpC,MAAM,UAAU,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IAC1C,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC;IAEnC,oEAAoE;IACpE,IAAI,UAAU,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,UAAU,CAAC,MAAM,GAAG,CAAC,IAAI,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;AAClG,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,mBAA2B,EAC3B,mBAA2B;IAE3B,MAAM,IAAI,GAAG,0BAA0B,CAAC,mBAAmB,CAAC,CAAC;IAC7D,MAAM,SAAS,GAAG,0BAA0B,CAAC,mBAAmB,CAAC,CAAC;IAElE,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACpC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAE9C,IAAI,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3D,OAAO,OAAO,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,cAAsB,EACtB,WAA8B;IAE9B,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,qBAAqB,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC,CAAC;AAC/E,CAAC","sourcesContent":["import { homedir, platform } from 'node:os';\nimport { join, parse, resolve, sep } from 'node:path';\n\nimport { IS_WINDOWS, isAlpha, isSlash } from './primitives.js';\n\nconst CHAR_COLON = 58;\nconst HOMEDIR = homedir();\n\nconst RESERVED_DEVICE_NAMES = new Set<string>([\n  'CON',\n  'PRN',\n  'AUX',\n  'NUL',\n  'COM1',\n  'COM2',\n  'COM3',\n  'COM4',\n  'COM5',\n  'COM6',\n  'COM7',\n  'COM8',\n  'COM9',\n  'LPT1',\n  'LPT2',\n  'LPT3',\n  'LPT4',\n  'LPT5',\n  'LPT6',\n  'LPT7',\n  'LPT8',\n  'LPT9',\n]);\n\nfunction getReservedDeviceName(segment: string): string | undefined {\n  const trimmed = segment.replace(/[. ]+$/, '');\n  const withoutStream = trimmed.split(':')[0] ?? '';\n  const baseName = (withoutStream.split('.')[0] ?? '').toUpperCase();\n  return RESERVED_DEVICE_NAMES.has(baseName) ? baseName : undefined;\n}\n\nexport function getReservedDeviceNameForPath(requestedPath: string): string | undefined {\n  const segments = requestedPath.split(/[\\\\/]/u);\n  for (const segment of segments) {\n    const reserved = getReservedDeviceName(segment);\n    if (reserved) {\n      return reserved;\n    }\n  }\n  return undefined;\n}\n\nexport function isWindowsDriveRelativePath(requestedPath: string): boolean {\n  // Check on all platforms so cross-platform clients cannot smuggle drive-relative\n  // inputs (e.g. C:relative) to a POSIX-hosted server where path.resolve would\n  // silently expand them relative to CWD.\n  if (requestedPath.length < 2) {\n    return false;\n  }\n  if (requestedPath.charCodeAt(1) !== CHAR_COLON) {\n    return false;\n  }\n  if (!isAlpha(requestedPath.charCodeAt(0))) {\n    return false;\n  }\n\n  if (requestedPath.length === 2) {\n    return true;\n  }\n  return !isSlash(requestedPath.charCodeAt(2));\n}\n\nfunction expandHome(filepath: string): string {\n  if (filepath === '~' || filepath.startsWith('~/') || filepath.startsWith('~\\\\')) {\n    const rest = filepath.slice(1).replace(/^[/\\\\]+/, '');\n    return rest ? join(HOMEDIR, rest) : HOMEDIR;\n  }\n  return filepath;\n}\n\nexport function normalizePath(p: string): string {\n  const resolved = resolve(expandHome(p));\n\n  // On Windows only the drive letter is lowercased (e.g. \"C:\\Foo\\Bar\").\n  // The rest of the path retains its original casing.\n  // IMPORTANT: callers must use isSamePath / isPathInsideDirectory for all\n  // equality and containment checks — never raw string equality — because\n  // those helpers apply full case-folding before comparing.\n  if (IS_WINDOWS && resolved.length >= 2 && resolved.charCodeAt(1) === CHAR_COLON) {\n    return resolved.charAt(0).toLowerCase() + resolved.slice(1);\n  }\n\n  return resolved;\n}\n\nexport const IS_CASE_INSENSITIVE_FS = IS_WINDOWS || platform() === 'darwin';\n\nfunction normalizeCaseForComparison(value: string): string {\n  return IS_CASE_INSENSITIVE_FS ? value.toLowerCase() : value;\n}\n\nexport function isSamePath(left: string, right: string): boolean {\n  if (left === right) {\n    return true;\n  }\n  const leftResolved = normalizeCaseForComparison(resolve(left));\n  const rightResolved = normalizeCaseForComparison(resolve(right));\n  return leftResolved === rightResolved;\n}\n\nexport function normalizeAllowedDirectory(dir: string): string {\n  const trimmed = dir.trim();\n  if (trimmed.length === 0) return '';\n\n  const normalized = normalizePath(trimmed);\n  const { root } = parse(normalized);\n\n  // Keep filesystem roots as-is (\"/\", \"c:\\\\\", \"\\\\\\\\server\\\\share\\\\\").\n  if (isSamePath(normalized, root)) {\n    return root;\n  }\n\n  return normalized.length > 1 && normalized.endsWith(sep) ? normalized.slice(0, -1) : normalized;\n}\n\nexport function isPathInsideDirectory(\n  normalizedDirectory: string,\n  normalizedCandidate: string,\n): boolean {\n  const root = normalizeCaseForComparison(normalizedDirectory);\n  const candidate = normalizeCaseForComparison(normalizedCandidate);\n\n  if (root === candidate) return true;\n  if (!candidate.startsWith(root)) return false;\n\n  if (isSlash(root.charCodeAt(root.length - 1))) return true;\n  return isSlash(candidate.charCodeAt(root.length));\n}\n\nexport function isPathWithinDirectories(\n  normalizedPath: string,\n  allowedDirs: readonly string[],\n): boolean {\n  return allowedDirs.some((dir) => isPathInsideDirectory(dir, normalizedPath));\n}\n"]}

package/dist/core/path.d.ts

@@ -0,0 +1,148 @@
+import { isSlash, toPosixPath } from './primitives.js';
+import type { EntryType } from './primitives.js';
+export { isSlash, toPosixPath };
+declare const ValidatedPathBrand: unique symbol;
+export type ValidatedPath = string & {
+    readonly [ValidatedPathBrand]: true;
+};
+export interface ValidatedPathDetails {
+    requestedPath: string;
+    resolvedPath: string;
+    isSymlink: boolean;
+}
+export interface ServerOptions {
+    allowCwd?: boolean;
+    cliAllowedDirs?: string[];
+    readOnly?: boolean;
+}
+/** `path.relative` with forward slashes, so displayed paths match across platforms. */
+export declare function toPosixRelative(from: string, to: string): string;
+export interface AllowedDirectoriesState {
+    primary: string[];
+    expanded: string[];
+}
+export declare function normalizeAllowedDirectories(dirs: readonly string[]): string[];
+export declare function resolveRealPath(normalized: string, signal?: AbortSignal): Promise<string | null>;
+/**
+ * Accepted risk: validation methods resolve/verify a path (symlinks, boundaries,
+ * sensitivity) and then return a plain string; the actual fs operation happens
+ * afterward as a separate syscall (classic TOCTOU). A symlink swapped in that
+ * exact window could redirect the follow-up operation. This is mitigated by
+ * re-validating the resolved real path (not just the requested path) and by
+ * walking ancestors to catch escapes before the target exists, but it is not
+ * eliminated — doing so would require fd-based operations (open with
+ * O_NOFOLLOW / operate on the resolved fd) throughout core/fs.ts. Acceptable
+ * tradeoff for a local, single-user filesystem server today.
+ */
+export declare class PathGuard {
+    #private;
+    private allowedDirectoriesState;
+    private readonly sensitive;
+    /**
+     * Directories added by an accepted access grant (R8) — from the tool
+     * executor's grant round-trip, or from a client's declared workspace roots on
+     * the legacy stdio leg. Held separately from the configured baseline because
+     * `recomputeAllowedDirectories` rebuilds that baseline from CLI args and env
+     * on every call: anything merged into it would be recomputed away.
+     *
+     * These are NOT filtered against the baseline. A granted directory is
+     * out-of-baseline by definition, so a baseline filter dropped every one while
+     * `applyGrant` still reported success — the whole round-trip prompted the
+     * user and then changed nothing. FS_ROOT_BOUNDARY and the unsafe-path denylist
+     * remain the limits, both checked in `applyGrant` — the only writer of this
+     * field — so the recompute can rebuild from it without re-filtering.
+     */
+    private grantedDirectories;
+    private rootBoundaries;
+    readonly options: ServerOptions | undefined;
+    /**
+     * True when this guard backs a live MCP server rather than a one-shot CLI
+     * invocation. Operator-facing configuration warnings are suppressed unless
+     * it is set, so `--print-config` and unit construction stay quiet.
+     */
+    readonly isServerContext: boolean;
+    constructor(options?: ServerOptions, isServerContext?: boolean);
+    static fromAllowedDirectories(dirs: readonly string[], signal?: AbortSignal): Promise<PathGuard>;
+    initialize(state: AllowedDirectoriesState): void;
+    isInitialized(): boolean;
+    /**
+     * Run `fn` as the next holder of the guard's single mutation lock. Every
+     * change to the allowed set goes through this so concurrent grants cannot
+     * interleave their read-`await`-write and lose a grant (GRANT-1).
+     */
+    private runExclusive;
+    getAllowedDirectories(): string[];
+    getRootBoundaries(): string[];
+    isSensitive(filePath: string): boolean;
+    /**
+     * True when `entryPath` is both within the guard's allowed directories and
+     * not sensitive, checking the requested AND resolved paths. EVERY entry is
+     * realpath-resolved via validateExistingPathDetailed: a symlinked ancestor
+     * directory pointing outside the sandbox would otherwise pass the lexical
+     * containment check (fs.glob follows symlinks and yields external entries as
+     * non-symlink dirents). validateExistingPathDetailed re-checks containment on
+     * the real path against this.allowedDirectoriesState.expanded (the guard's full
+     * allowed set — a superset of the single-root `bounds` callers pass) and
+     * re-checks sensitivity on the resolved target, throwing ACCESS_DENIED for
+     * escapes/sensitive, which the catch below turns into a filter. `_entryType`
+     * and `_bounds` are retained for call-site compatibility while the guard's own
+     * allowed set is the real gate. Skippable errno/fs errors return false (the
+     * entry is filtered, not fatal). The accepted TOCTOU window is documented at
+     * the class docstring above.
+     */
+    isEntryAccessible(entryPath: string, _entryType: EntryType, _bounds: readonly string[]): Promise<boolean>;
+    validateExistingPath(requestedPath: string): Promise<ValidatedPath>;
+    /** True when a normalized path equals its own filesystem root (`C:\`, `/`). */
+    private isFilesystemRoot;
+    /**
+     * True when a grant must never admit `targetDir` — a bare filesystem root, or
+     * an unsafe path (home, /etc, C:\Windows, ...). Checked on the lexical path
+     * AND on the one it resolves to: `expandAllowedDirectories` pushes each root's
+     * realpath into the allowed set, so a lexical-only check let a symlink or
+     * junction aliasing $HOME/C:\Windows in under an innocuous name — and the
+     * confirmation prompt showed the alias, not the target. A target that cannot
+     * be resolved is judged lexically; it does not exist to escape into.
+     */
+    private isUnsafeGrantTarget;
+    /** Walk up from a blocked path to the closest existing ancestor directory. */
+    private resolveGrantTargetDir;
+    /**
+     * Pre-check (no mutation, no callback): given the paths a tool is about to
+     * operate on, return the sorted, de-duplicated grant-target directories for
+     * those that are outside the allowed roots AND grantable (within FS_ROOT_BOUNDARY
+     * when it is configured). A path whose nearest existing ancestor escapes the
+     * boundary is NOT grantable and is omitted — the operation will fail with
+     * ACCESS_DENIED for it rather than prompt. The caller returns an
+     * `input_required` result carrying exactly this set (R7), and on retry applies
+     * each accepted grant via {@link applyGrant} (R8). `requestState` binds this
+     * set so a grant accepted for X cannot authorize Y (R9).
+     */
+    precheckAccess(paths: readonly string[]): Promise<string[]>;
+    /**
+     * Apply an accepted access grant: enforce FS_ROOT_BOUNDARY again (a TOCTOU
+     * re-check against the boundary resolved at config time), then extend the
+     * allowed roots for the remainder of the session (R8, A4). Returns false when
+     * the boundary or the unsafe-path denylist blocks the grant, AND when the
+     * recompute did not actually admit the directory — the return value now
+     * reports what the guard's allowed set really holds, not merely that the
+     * pre-checks passed. The caller leaves a refused path to fail with
+     * ACCESS_DENIED during the operation. Idempotent: re-granting an already
+     * allowed directory is a no-op via the dedup in `initialize`.
+     */
+    applyGrant(targetDir: string): Promise<boolean>;
+    private isWithinBoundary;
+    private validateAccessAndSensitivity;
+    private validateAccess;
+    private handleRealpathError;
+    validateExistingPathDetailed(requestedPath: string): Promise<ValidatedPathDetails>;
+    validateExistingDirectory(requestedPath: string): Promise<string>;
+    resolvePathOrRoot(pathValue: string | undefined): string;
+    isAllowedRoot(normalizedPath: string): boolean;
+    private assertNotSensitiveFile;
+    private throwAccessDenied;
+    private resolveNearestExistingAncestor;
+    validatePathForWrite(requestedPath: string): Promise<ValidatedPath>;
+    validatePathForDelete(requestedPath: string): Promise<ValidatedPath>;
+    recomputeAllowedDirectories(): Promise<void>;
+}
+//# sourceMappingURL=path.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../src/core/path.ts"],"names":[],"mappings":"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"}