@j0hanz/filesystem-mcp 2.8.1 → 2.9.0

package/dist/core/path.d.ts

@@ -3,6 +3,19 @@ export interface ValidatedPathDetails {
     resolvedPath: string;
     isSymlink: boolean;
 }
+/** How one walk prints the paths it found; see `PathGuard.resultPaths`. */
+export interface ResultPaths {
+    /** The root the relative paths are relative to, as configured; the walked directory when there is none. */
+    readonly root: string;
+    /** The walked directory is that root itself. */
+    readonly atRoot: boolean;
+    show(absolutePath: string): string;
+}
+/** A root and every spelling that names it: as configured, and its realpath when that differs. */
+interface RootSpellings {
+    readonly root: string;
+    readonly spellings: readonly string[];
+}
 export interface ServerOptions {
     allowCwd?: boolean;
     cliAllowedDirs?: string[];
@@ -13,11 +26,16 @@ export declare function resolveAllowedDirectoriesState(dirs: readonly string[],
 /**
  * TOCTOU note: validation returns a plain string and the fs operation is a
  * later syscall, so a symlink swapped in between could redirect it. Reads and
- * appends in core/fs.ts open with O_NOFOLLOW (final component)
- * and re-check the fd's real path on Linux (ancestor swap). Residual: write
- * paths that resolve a parent by name (`rename`, `mkdir`, `rm`, `cp`) would
- * need openat()-relative-to-dirfd, which Node lacks; non-Linux skips the fd
- * re-check.
+ * appends in core/fs.ts open with O_NOFOLLOW (final component) and re-check the
+ * fd's real path on Linux (ancestor swap). stat's directory count opens and
+ * re-checks the directory, and reads entries through that descriptor, only on
+ * Linux with procfs; elsewhere it reads the directory by path, so the swap
+ * window stays there, like the read path's non-Linux residual. Residuals: the
+ * directory walker behind list and the search tools (core/glob.ts) still
+ * resolves each entry by path, as the count does for a symlinked entry;
+ * write paths that resolve a parent by name
+ * (`rename`, `mkdir`, `rm`, `cp`) would need openat()-relative-to-dirfd, which
+ * Node lacks; non-Linux skips the fd re-check.
  */
 export declare class PathGuard {
     private allowedDirectoriesState;
@@ -39,14 +57,28 @@ export declare class PathGuard {
      * field — so the recompute can rebuild from it without re-filtering.
      */
     private grantedDirectories;
+    /**
+     * The grants a user approved for a path a tool asked about, as opposed to
+     * the workspace roots a client declared. Relative paths never resolve
+     * against these: one approval must not change what a relative path names,
+     * neither in a later round of the same call nor in a later call.
+     */
+    private accessGrants;
+    /**
+     * Where relative paths resolve: the roots minus `accessGrants`, each with
+     * its spellings, plus every spelling flattened for containment.
+     */
+    private relativeBases;
     private rootBoundaries;
     private readonly options;
     constructor(options?: ServerOptions);
     /**
      * `expanded` is the containment set (each root plus its realpath alias);
      * `roots` is what a caller choosing "the root" sees, one entry per root.
+     * `relativeBases` lists the roots relative paths resolve against, with
+     * their spellings; without it, every root, each spelled only as given.
      */
-    initialize(expanded: readonly string[], roots?: readonly string[]): void;
+    initialize(expanded: readonly string[], roots?: readonly string[], relativeBases?: readonly RootSpellings[]): void;
     isInitialized(): boolean;
     getAllowedDirectories(): string[];
     /**
@@ -63,6 +95,16 @@ export declare class PathGuard {
      */
     getRoots(): string[];
     isSensitive(filePath: string): boolean;
+    /**
+     * True when a walked entry is inside the allowed directories and not sensitive,
+     * on both its requested and resolved paths. Every entry is realpath-resolved: a
+     * symlinked ancestor pointing outside the sandbox would otherwise pass the
+     * lexical check (fs.glob follows symlinks and yields external entries as
+     * non-symlink dirents). Escapes and sensitive targets throw ACCESS_DENIED and
+     * skippable errors filter the entry; anything else is fatal. The accepted
+     * TOCTOU window is documented on this class.
+     */
+    isEntryAccessible(entryPath: string): Promise<boolean>;
     validateExistingPath(requestedPath: string): Promise<string>;
     /**
      * True when a grant must never admit `targetDir` — an unsafe path (home,
@@ -98,20 +140,82 @@ export declare class PathGuard {
      * 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`.
+     *
+     * `kind` says where the grant came from: `access` for a path the user
+     * approved when a tool asked, `workspace` for a root the client declared.
+     * Only a workspace root becomes a place relative paths resolve.
      */
-    applyGrant(targetDir: string): Promise<boolean>;
+    applyGrant(targetDir: string, kind?: 'access' | 'workspace'): Promise<boolean>;
     private isWithinBoundary;
     private validateAccess;
     private handleRealpathError;
     validateExistingPathDetailed(requestedPath: string): Promise<ValidatedPathDetails>;
     validateExistingDirectory(requestedPath: string): Promise<string>;
     resolvePathOrRoot(pathValue: string | undefined): string;
+    /**
+     * Where the relative paths a caller sent should point, keyed by the spelling
+     * sent; a path that keeps its meaning is absent. A relative path resolves
+     * against the working directory, as it always has, while that lands inside
+     * a root. When it does not — a desktop host starts the server outside the
+     * project, and an HTTP client never shares its working directory — it
+     * resolves against the roots: the one root, or with several, the one it
+     * exists under. Searches print paths relative to the root (`resultPaths`),
+     * so this is what lets one tool's output feed the next.
+     *
+     * "Roots" here are the configured ones and those a client declared, never an
+     * access grant (see `accessGrants`). Absolute, `~` and drive paths keep their
+     * meaning, as does every path when there is no such root; validation judges
+     * them as before. A Windows drive path on POSIX is left for validation to
+     * refuse: joined to a root, `C:\x` would be an absolute path that passes. A
+     * relative path that exists under several roots, or under none of several,
+     * is refused rather than guessed.
+     */
+    resolveRelativePaths(paths: readonly string[]): Promise<Map<string, string>>;
+    private resolveAgainstRoots;
+    /**
+     * How a tool prints the paths a walk of `walkedDir` found, so the caller can
+     * pass each one straight back: relative to the root holding `walkedDir`
+     * when `resolveRelativePaths` maps that spelling back to the same path,
+     * absolute otherwise. A scoped search of `src` prints `src/a.ts`, not
+     * `a.ts`, which would name `<root>/a.ts`. `root` is the root as configured,
+     * as `list_roots` shows it, even when the walk went through its realpath.
+     *
+     * The absolute fallback covers a working directory in a subfolder of a root
+     * (relative paths resolve there), a directory under an access grant only
+     * (relative paths never resolve there), several roots with the working
+     * directory outside them (a name two roots share would read back as
+     * ambiguous, and which names are shared can change between the print and
+     * the read), and a name that would not read back as given: `~`, blank, or a
+     * POSIX name holding a backslash or starting with a drive (`C:`).
+     */
+    resultPaths(walkedDir: string): ResultPaths;
     isAllowedRoot(normalizedPath: string): boolean;
     private assertNotSensitiveFile;
     private throwAccessDenied;
     private resolveNearestExistingAncestor;
+    /**
+     * `normalized` re-spelled with the on-disk names of the components that are
+     * missing as typed but present under another Unicode spelling (#101), or
+     * `undefined` when no component changed. Only names below a root are
+     * matched, never the root's own. Each directory is scanned only after its
+     * real path is checked to be inside the roots, and each matched entry is
+     * realpathed and checked again, so a link found this way cannot lead out
+     * (`resolveLast: false` leaves the last one unresolved, for delete). The
+     * first component with no match ends the walk; it and the rest stay as
+     * typed, so a write still creates them. The result is a spelling only:
+     * the caller runs its own containment and denylist checks on it.
+     */
+    private respellMissing;
+    /**
+     * The entry of `realDir` that `name` names: `name` itself when it is
+     * there, else the one entry with the same `unicodeMatchKey`. Two or more
+     * such entries are refused, never chosen between. `undefined` when none
+     * matches or the directory cannot be read.
+     */
+    private findEquivalentEntry;
     validatePathForWrite(requestedPath: string): Promise<string>;
     validatePathForDelete(requestedPath: string): Promise<string>;
     recomputeAllowedDirectories(): Promise<void>;
 }
+export {};
 //# sourceMappingURL=path.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../src/core/path.ts"],"names":[],"mappings":"AAmCA,MAAM,WAAW,oBAAoB;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AA0DD,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAE7E;AAmBD,wBAAsB,8BAA8B,CAClD,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,MAAM,EAAE,CAAC,CAWnB;AAED;;;;;;;;GAQG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,uBAAuB,CAAuB;IACtD,8EAA8E;IAC9E,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0B;IACpD;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,kBAAkB,CAAgB;IAC1C,OAAO,CAAC,cAAc,CAAgB;IAEtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;gBAExC,OAAO,CAAC,EAAE,aAAa;IAInC;;;OAGG;IACH,UAAU,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,GAAE,SAAS,MAAM,EAAa,GAAG,IAAI;IAKlF,aAAa,IAAI,OAAO;IAIxB,qBAAqB,IAAI,MAAM,EAAE;IAOjC;;;;;OAKG;IACH,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAc/D;;;;OAIG;IACH,QAAQ,IAAI,MAAM,EAAE;IAIpB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIhC,oBAAoB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKlE;;;;;;;;OAQG;YACW,mBAAmB;IAYjC,8EAA8E;YAChE,qBAAqB;IAgBnC;;;;;;;;;;OAUG;IACG,cAAc,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAiCjE;;;;;;;;;;OAUG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;YAwCvC,gBAAgB;IAQ9B,OAAO,CAAC,cAAc;YAwDR,mBAAmB;IA0C3B,4BAA4B,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAmClF,yBAAyB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAsBvE,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM;IAwBxD,aAAa,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO;IAW9C,OAAO,CAAC,sBAAsB;IAU9B,OAAO,CAAC,iBAAiB;YAOX,8BAA8B;IAwDtC,oBAAoB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAoB5D,qBAAqB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAoE7D,2BAA2B,IAAI,OAAO,CAAC,IAAI,CAAC;CAwDnD"}
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../src/core/path.ts"],"names":[],"mappings":"AA+CA,MAAM,WAAW,oBAAoB;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,2GAA2G;IAC3G,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;CACpC;AAED,kGAAkG;AAClG,UAAU,aAAa;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AA0DD,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAE7E;AA+BD,wBAAsB,8BAA8B,CAClD,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,MAAM,EAAE,CAAC,CAGnB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,uBAAuB,CAAuB;IACtD,8EAA8E;IAC9E,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0B;IACpD;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,kBAAkB,CAAgB;IAC1C;;;;;OAKG;IACH,OAAO,CAAC,YAAY,CAAgB;IACpC;;;OAGG;IACH,OAAO,CAAC,aAAa,CACoE;IACzF,OAAO,CAAC,cAAc,CAAgB;IAEtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;gBAExC,OAAO,CAAC,EAAE,aAAa;IAInC;;;;;OAKG;IACH,UAAU,CACR,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,KAAK,GAAE,SAAS,MAAM,EAAa,EACnC,aAAa,CAAC,EAAE,SAAS,aAAa,EAAE,GACvC,IAAI;IAkBP,aAAa,IAAI,OAAO;IAIxB,qBAAqB,IAAI,MAAM,EAAE;IAOjC;;;;;OAKG;IACH,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAc/D;;;;OAIG;IACH,QAAQ,IAAI,MAAM,EAAE;IAIpB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAItC;;;;;;;;OAQG;IACG,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IActD,oBAAoB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKlE;;;;;;;;OAQG;YACW,mBAAmB;IAYjC,8EAA8E;YAChE,qBAAqB;IAgBnC;;;;;;;;;;OAUG;IACG,cAAc,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IA4CjE;;;;;;;;;;;;;;OAcG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,GAAE,QAAQ,GAAG,WAAsB,GAAG,OAAO,CAAC,OAAO,CAAC;YAkDhF,gBAAgB;IAQ9B,OAAO,CAAC,cAAc;YAkER,mBAAmB;IA0C3B,4BAA4B,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAwDlF,yBAAyB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAsBvE,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM;IAwBxD;;;;;;;;;;;;;;;;;OAiBG;IACG,oBAAoB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YAkBpE,mBAAmB;IAgCjC;;;;;;;;;;;;;;;OAeG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW;IAmD3C,aAAa,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO;IAW9C,OAAO,CAAC,sBAAsB;IAU9B,OAAO,CAAC,iBAAiB;YAOX,8BAA8B;IA0E5C;;;;;;;;;;;OAWG;YACW,cAAc;IAuD5B;;;;;OAKG;YACW,mBAAmB;IA2B3B,oBAAoB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAgD5D,qBAAqB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAuF7D,2BAA2B,IAAI,OAAO,CAAC,IAAI,CAAC;CAgEnD"}