@effected/walker 0.18.0 → 0.20.0

package/Confine.js

@@ -0,0 +1,191 @@
+import { resolveSegments } from "./internal/segments.js";
+import { Effect, Result, Schema } from "effect";
+
+// src/Confine.ts
+/**
+* Why {@link confineRelativeResult} refused a candidate path.
+*
+* @remarks
+* - `nulByte` — the candidate holds a NUL character, which no filesystem
+*   path can carry and which some APIs truncate at.
+* - `absolute` — the candidate is rooted: a leading `/` or `\` (which covers
+*   UNC `\\server\share` and `//server/share`), or a win32 drive prefix such
+*   as `C:\x`, `C:/x` or the drive-relative `C:x`, before or after
+*   normalisation (`./C:/x` and `og/../C:x` are absolute too).
+* - `traversal` — after normalisation a `..` segment climbs above the base.
+* - `empty` — the candidate names the base itself: `""`, `.`, `./`, or a
+*   path such as `og/..` that normalises to nothing.
+* - `reservedName` — a normalised segment win32 reads as something other
+*   than a plain entry: one holding a `:` (a drive designator, or an NTFS
+*   alternate data stream such as `x::$DATA`), one made only of dots and
+*   spaces (`...`, `.. `, which win32 trims to nothing or to `..`), or a
+*   reserved device name (`CON`, `PRN`, `AUX`, `NUL`, `COM1`–`COM9`,
+*   `LPT1`–`LPT9`), in any case and with or without an extension
+*   (`nul.txt`).
+*
+* @public
+*/
+const PathEscapeReason = Schema.Literals([
+	"nulByte",
+	"absolute",
+	"traversal",
+	"empty",
+	"reservedName"
+]);
+/**
+* An untrusted relative path would leave, or does not name anything under,
+* the base directory it was confined to.
+*
+* @remarks
+* This is caller input, not a wiring defect: recover from it with
+* `Effect.catchTag("PathEscapeError", ...)`, typically by rejecting the
+* archive or manifest that named the path. The candidate is carried
+* verbatim, and the message renders it JSON-quoted so a control character
+* in it cannot forge a log line.
+*
+* @public
+*/
+var PathEscapeError = class extends Schema.TaggedError()("PathEscapeError", {
+	/** The candidate path, exactly as the caller passed it. */
+	candidate: Schema.String,
+	/** Why the candidate was refused. */
+	reason: PathEscapeReason
+}) {
+	get message() {
+		return `the path ${JSON.stringify(this.candidate)} ${REASON_TEXT[this.reason]}`;
+	}
+};
+/** The predicate of each refusal's message, after the quoted candidate. */
+const REASON_TEXT = {
+	nulByte: "contains a NUL character",
+	absolute: "is absolute, so it is not confined to the base directory",
+	traversal: "climbs above the base directory",
+	empty: "names the base directory itself, not an entry under it",
+	reservedName: "has a segment win32 reserves or reads as something else"
+};
+/** A win32 drive prefix: `C:\x`, `C:/x`, and the drive-relative `C:x`. */
+const DRIVE_PREFIX = /^[A-Za-z]:/;
+/** A segment of dots and spaces only, which win32 trims to nothing or to `..`. */
+const DOTS_AND_SPACES = /^[. ]+$/;
+/** A win32 reserved device name, with or without an extension, in any case. */
+const DEVICE_NAME = /^(?:con|prn|aux|nul|com[0-9\u00b9\u00b2\u00b3]|lpt[0-9\u00b9\u00b2\u00b3]|conin\$|conout\$) *(?:\..*)?$/i;
+/** Whether win32 reads a normalised segment as something other than a plain entry. */
+const isReservedSegment = (segment) => segment.includes(":") || DOTS_AND_SPACES.test(segment) || DEVICE_NAME.test(segment);
+/** `path` without trailing `/` or `\`: a loop, because `/[\\/]+$/` backtracks quadratically on a long separator run. */
+const stripTrailingSeparators = (path) => {
+	let end = path.length;
+	while (end > 0 && (path[end - 1] === "/" || path[end - 1] === "\\")) end -= 1;
+	return path.slice(0, end);
+};
+/**
+* Confine an untrusted relative path to a base directory, synchronously.
+*
+* @remarks
+* The check is lexical and does no IO. Both `/` and `\` are separators,
+* whatever the platform, so a backslash variant of an escape is caught on
+* POSIX as well as on win32. In order, a candidate is refused when it holds
+* a NUL character, when it is absolute (POSIX `/x`, UNC `\\server\share`,
+* a win32 drive form such as `C:\x` or `C:x`), when a `..` segment climbs
+* above the base after normalisation (`og/../x` is fine, `og/../../x` is
+* not), or when it normalises to the base itself (`""`, `.`, `og/..`). The
+* last is a deliberate choice: a caller confining a path means to name an
+* entry under the base, and an archive entry naming its own root is malformed.
+* The normalised path is then checked again: a first segment with a drive
+* prefix is absolute (`./C:/x` would otherwise survive an empty base as
+* `C:/x`), and any segment win32 reserves (a `:`, dots and spaces only, a
+* device name such as `CON` or `nul.txt`) is refused as `reservedName`, on
+* every platform, so an archive that is safe on POSIX is safe on win32.
+*
+* No percent-decoding happens. `%2e%2e%2fx` is one ordinary file name, which
+* is exactly how a filesystem reads it, so it stays confined; a caller whose
+* input is URL-encoded decodes first and confines the decoded text.
+*
+* On success the result is the base joined with the normalised candidate:
+* `.` and empty segments dropped, `..` resolved, segments joined with `/`.
+* The base is kept verbatim apart from trailing separators, so a win32 base
+* yields `C:\out/og/x`, which every Node filesystem API accepts. An empty
+* base yields the normalised relative path alone. The check is lexical, not
+* physical, and symlinks are out of scope: a symlink already inside the
+* base can still point out of it, so a caller extracting into a directory
+* it does not own resolves links separately.
+*
+* {@link confineRelative} is defined in terms of this function and adds
+* only the tracing span.
+*
+* @example
+* ```ts
+* import { confineRelativeResult } from "@effected/walker";
+* import { Result } from "effect";
+*
+* const ok = confineRelativeResult("/srv/site", "og\\card.png");
+* // Result.succeed("/srv/site/og/card.png")
+* const bad = confineRelativeResult("/srv/site", "og/../../etc/passwd");
+* // Result.fail(PathEscapeError { reason: "traversal" })
+* if (Result.isFailure(bad)) console.error(bad.failure.message);
+* ```
+*
+* @param base - The directory the candidate must stay under.
+* @param candidate - The untrusted relative path.
+* @returns A `Result` succeeding with the joined path, or failing with
+* {@link PathEscapeError}.
+*
+* @public
+*/
+const confineRelativeResult = (base, candidate) => {
+	if (candidate.includes("\0")) return Result.fail(new PathEscapeError({
+		candidate,
+		reason: "nulByte"
+	}));
+	const unified = candidate.replaceAll("\\", "/");
+	if (unified.startsWith("/") || DRIVE_PREFIX.test(unified)) return Result.fail(new PathEscapeError({
+		candidate,
+		reason: "absolute"
+	}));
+	const segments = resolveSegments(unified.split("/"));
+	if (segments === void 0) return Result.fail(new PathEscapeError({
+		candidate,
+		reason: "traversal"
+	}));
+	if (segments.length === 0) return Result.fail(new PathEscapeError({
+		candidate,
+		reason: "empty"
+	}));
+	if (DRIVE_PREFIX.test(segments[0] ?? "")) return Result.fail(new PathEscapeError({
+		candidate,
+		reason: "absolute"
+	}));
+	if (segments.some(isReservedSegment)) return Result.fail(new PathEscapeError({
+		candidate,
+		reason: "reservedName"
+	}));
+	const relative = segments.join("/");
+	return Result.succeed(base === "" ? relative : `${stripTrailingSeparators(base)}/${relative}`);
+};
+/**
+* Confine an untrusted relative path to a base directory.
+*
+* @remarks
+* Defined in terms of {@link confineRelativeResult}, whose remarks carry the
+* full contract; this form adds the `Walker.confineRelative` tracing span
+* and puts {@link PathEscapeError} on the error channel.
+*
+* @example
+* ```ts
+* import { confineRelative } from "@effected/walker";
+* import { Effect } from "effect";
+*
+* const target = confineRelative("/srv/site", "og/card.png").pipe(
+*   Effect.catchTag("PathEscapeError", (error) => Effect.die(error)),
+* );
+* ```
+*
+* @param base - The directory the candidate must stay under.
+* @param candidate - The untrusted relative path.
+* @returns An `Effect` succeeding with the joined path, or failing with
+* {@link PathEscapeError}.
+*
+* @public
+*/
+const confineRelative = Effect.fn("Walker.confineRelative")((base, candidate) => Effect.fromResult(confineRelativeResult(base, candidate)));
+
+export { PathEscapeError, PathEscapeReason, confineRelative, confineRelativeResult };

package/Descend.js

@@ -1,6 +1,7 @@
+import { resolveSegments } from "./internal/segments.js";
 import { Effect, FileSystem, Path, Schema } from "effect";
 
-//#region src/Descend.ts
+// src/Descend.ts
 /**
 * Typed failure raised by `descend`: a directory mid-walk was unreadable
 * (under `onUnreadable: "fail"`), or the walk descended past `maxDepth`. Depth
@@ -33,15 +34,7 @@ const DEFAULT_PRUNE = ["node_modules", ".git"];
 * ever happens (a pattern must not enumerate the tree above its documented
 * root).
 */
-const escapesCwd = (relative) => {
-	let depth = 0;
-	for (const segment of relative.split("/")) {
-		if (segment === "" || segment === ".") continue;
-		depth += segment === ".." ? -1 : 1;
-		if (depth < 0) return true;
-	}
-	return false;
-};
+const escapesCwd = (relative) => resolveSegments(relative.split("/")) === void 0;
 /** Shared empty ancestor chain: frames under `followSymlinks: false` never consult theirs. */
 const NO_ANCESTORS = Object.freeze([]);
 /** Not exported — `descend`'s overloads below carry the public documentation. */
@@ -168,5 +161,4 @@ function descend(pattern, options) {
 	return descendImpl(pattern, options);
 }
 
-//#endregion
 export { DescendError, descend };

package/Expand.js

@@ -2,7 +2,7 @@ import { DescendError, descend } from "./Descend.js";
 import { Effect, Result, Schema } from "effect";
 import { GlobPattern, GlobPatternError } from "@effected/glob";
 
-//#region src/Expand.ts
+// src/Expand.ts
 /**
 * Typed failure raised by {@link compileAndExpand}: the single error the
 * compile+expand recipe fails with, so a caller catches one tag rather than
@@ -97,5 +97,4 @@ const compileAndExpand = Effect.fn("Walker.compileAndExpand")(function* (pattern
 	})));
 });
 
-//#endregion
 export { GlobExpansionError, compileAndExpand };

package/README.md

@@ -95,6 +95,7 @@ import { Walker, compileAndExpand, descend } from "@effected/walker";
 - `Walker.findRoot(dirs, isRoot)` — the nearest directory a marker predicate accepts. `firstMatch` where the candidate expansion is the identity.
 - `descend(pattern, options)` — the file paths a compiled `@effected/glob` pattern selects under `cwd`, POSIX separators, sorted. `onUnreadable` decides what an unreadable directory mid-walk means: `"fail"` (the default) raises a typed `DescendError`, `"skip"` continues past it and forgets it, and `"record"` continues past it and returns a `DescendResult` — `{ matches, unreadable }`, where each `UnreadableDirectory` carries the directory's `cwd`-relative `path` and the `PlatformError` it failed with, so a report never has to re-read the directory to learn why. The walk base records as `path: ""`, and a directory that vanished mid-walk (`NotFound`) is a benign race, never recorded. `followSymlinks` (default `false`) decides symlinked directories: by default they are never entered (cycle safety); under `true` they are descended under `@actions/glob`'s `traversalChain` cycle guard — a directory is a cycle only when its real path is already an ancestor of the current branch, so link loops terminate while two sibling links resolving to the same target both enumerate; a link whose real path cannot be resolved is never entered, and that failure follows `onUnreadable` exactly as an unreadable directory does — matching `@actions/glob`'s default `followSymbolicLinks: true` (Node's recursive `readdir` also follows links, but keeps no traversal chain and recurses without bound on a loop).
 - `compileAndExpand(pattern, options)` — `descend` from a glob **string**: compiles it with `@effected/glob` (`options.glob`) and expands it, failing typed with `GlobExpansionError` when the pattern does not compile.
+- `confineRelativeResult(base, candidate)` — keep an untrusted relative path (an archive entry, a manifest's asset path) under `base`, synchronously, as a `Result<string, PathEscapeError>`. Both `/` and `\` are separators; a NUL character, an absolute form (POSIX `/x`, UNC `\\server\share`, win32 `C:\x` or `C:x`), a `..` that climbs above `base` after normalisation (`og/../x` is fine, `og/../../x` is not) a path naming `base` itself (`""`, `.`, `og/..`), and a segment win32 reserves (a `:` such as an alternate data stream, dots and spaces only, a device name such as `CON` or `nul.txt`) are refused, with the reason on the error. Lexical and IO-free, with no percent-decoding; the success value is `base` joined with the normalised path. Symlinks are out of scope: the check is lexical. `confineRelative(base, candidate)` is the `Effect` twin.
 
 ## License
 

package/Walker.js

@@ -1,6 +1,6 @@
 import { Effect, FileSystem, Option, Path } from "effect";
 
-//#region src/Walker.ts
+// src/Walker.ts
 const ascend = (start, options) => Effect.gen(function* () {
 	const path = yield* Path.Path;
 	const maxDepth = options?.maxDepth ?? 256;
@@ -154,5 +154,4 @@ var Walker = class {
 	static findRoot = findRoot;
 };
 
-//#endregion
 export { Walker };

package/index.d.ts

@@ -1,6 +1,138 @@
+import { Effect, FileSystem, Option, Path, PlatformError, Result, Schema } from "effect";
 import { GlobPattern, GlobPatternError, GlobPatternOptions } from "@effected/glob";
-import { Effect, FileSystem, Option, Path, PlatformError, Schema } from "effect";
-//#region src/Descend.d.ts
+/**
+ * Why {@link confineRelativeResult} refused a candidate path.
+ *
+ * @remarks
+ * - `nulByte` — the candidate holds a NUL character, which no filesystem
+ *   path can carry and which some APIs truncate at.
+ * - `absolute` — the candidate is rooted: a leading `/` or `\` (which covers
+ *   UNC `\\server\share` and `//server/share`), or a win32 drive prefix such
+ *   as `C:\x`, `C:/x` or the drive-relative `C:x`, before or after
+ *   normalisation (`./C:/x` and `og/../C:x` are absolute too).
+ * - `traversal` — after normalisation a `..` segment climbs above the base.
+ * - `empty` — the candidate names the base itself: `""`, `.`, `./`, or a
+ *   path such as `og/..` that normalises to nothing.
+ * - `reservedName` — a normalised segment win32 reads as something other
+ *   than a plain entry: one holding a `:` (a drive designator, or an NTFS
+ *   alternate data stream such as `x::$DATA`), one made only of dots and
+ *   spaces (`...`, `.. `, which win32 trims to nothing or to `..`), or a
+ *   reserved device name (`CON`, `PRN`, `AUX`, `NUL`, `COM1`–`COM9`,
+ *   `LPT1`–`LPT9`), in any case and with or without an extension
+ *   (`nul.txt`).
+ *
+ * @public
+ */
+export declare const PathEscapeReason: Schema.Literals<readonly ["nulByte", "absolute", "traversal", "empty", "reservedName"]>;
+/**
+ * The decoded type of {@link (PathEscapeReason:variable)}.
+ *
+ * @public
+ */
+export type PathEscapeReason = typeof PathEscapeReason.Type;
+declare const PathEscapeError_base: Schema.Class<PathEscapeError, Schema.TaggedStruct<"PathEscapeError", {
+  /** The candidate path, exactly as the caller passed it. */
+  readonly candidate: Schema.String;
+  /** Why the candidate was refused. */
+  readonly reason: Schema.Literals<readonly ["nulByte", "absolute", "traversal", "empty", "reservedName"]>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * An untrusted relative path would leave, or does not name anything under,
+ * the base directory it was confined to.
+ *
+ * @remarks
+ * This is caller input, not a wiring defect: recover from it with
+ * `Effect.catchTag("PathEscapeError", ...)`, typically by rejecting the
+ * archive or manifest that named the path. The candidate is carried
+ * verbatim, and the message renders it JSON-quoted so a control character
+ * in it cannot forge a log line.
+ *
+ * @public
+ */
+export declare class PathEscapeError extends PathEscapeError_base {
+  get message(): string;
+}
+/**
+ * Confine an untrusted relative path to a base directory, synchronously.
+ *
+ * @remarks
+ * The check is lexical and does no IO. Both `/` and `\` are separators,
+ * whatever the platform, so a backslash variant of an escape is caught on
+ * POSIX as well as on win32. In order, a candidate is refused when it holds
+ * a NUL character, when it is absolute (POSIX `/x`, UNC `\\server\share`,
+ * a win32 drive form such as `C:\x` or `C:x`), when a `..` segment climbs
+ * above the base after normalisation (`og/../x` is fine, `og/../../x` is
+ * not), or when it normalises to the base itself (`""`, `.`, `og/..`). The
+ * last is a deliberate choice: a caller confining a path means to name an
+ * entry under the base, and an archive entry naming its own root is malformed.
+ * The normalised path is then checked again: a first segment with a drive
+ * prefix is absolute (`./C:/x` would otherwise survive an empty base as
+ * `C:/x`), and any segment win32 reserves (a `:`, dots and spaces only, a
+ * device name such as `CON` or `nul.txt`) is refused as `reservedName`, on
+ * every platform, so an archive that is safe on POSIX is safe on win32.
+ *
+ * No percent-decoding happens. `%2e%2e%2fx` is one ordinary file name, which
+ * is exactly how a filesystem reads it, so it stays confined; a caller whose
+ * input is URL-encoded decodes first and confines the decoded text.
+ *
+ * On success the result is the base joined with the normalised candidate:
+ * `.` and empty segments dropped, `..` resolved, segments joined with `/`.
+ * The base is kept verbatim apart from trailing separators, so a win32 base
+ * yields `C:\out/og/x`, which every Node filesystem API accepts. An empty
+ * base yields the normalised relative path alone. The check is lexical, not
+ * physical, and symlinks are out of scope: a symlink already inside the
+ * base can still point out of it, so a caller extracting into a directory
+ * it does not own resolves links separately.
+ *
+ * {@link confineRelative} is defined in terms of this function and adds
+ * only the tracing span.
+ *
+ * @example
+ * ```ts
+ * import { confineRelativeResult } from "@effected/walker";
+ * import { Result } from "effect";
+ *
+ * const ok = confineRelativeResult("/srv/site", "og\\card.png");
+ * // Result.succeed("/srv/site/og/card.png")
+ * const bad = confineRelativeResult("/srv/site", "og/../../etc/passwd");
+ * // Result.fail(PathEscapeError { reason: "traversal" })
+ * if (Result.isFailure(bad)) console.error(bad.failure.message);
+ * ```
+ *
+ * @param base - The directory the candidate must stay under.
+ * @param candidate - The untrusted relative path.
+ * @returns A `Result` succeeding with the joined path, or failing with
+ * {@link PathEscapeError}.
+ *
+ * @public
+ */
+export declare const confineRelativeResult: (base: string, candidate: string) => Result.Result<string, PathEscapeError>;
+/**
+ * Confine an untrusted relative path to a base directory.
+ *
+ * @remarks
+ * Defined in terms of {@link confineRelativeResult}, whose remarks carry the
+ * full contract; this form adds the `Walker.confineRelative` tracing span
+ * and puts {@link PathEscapeError} on the error channel.
+ *
+ * @example
+ * ```ts
+ * import { confineRelative } from "@effected/walker";
+ * import { Effect } from "effect";
+ *
+ * const target = confineRelative("/srv/site", "og/card.png").pipe(
+ *   Effect.catchTag("PathEscapeError", (error) => Effect.die(error)),
+ * );
+ * ```
+ *
+ * @param base - The directory the candidate must stay under.
+ * @param candidate - The untrusted relative path.
+ * @returns An `Effect` succeeding with the joined path, or failing with
+ * {@link PathEscapeError}.
+ *
+ * @public
+ */
+export declare const confineRelative: (base: string, candidate: string) => Effect.Effect<string, PathEscapeError>;
 /**
  * Options for `descend`.
  *
@@ -200,8 +332,6 @@ export declare function descend(pattern: GlobPattern, options: DescendRecordOpti
  * @public
  */
 export declare function descend(pattern: GlobPattern, options: DescendOptions): Effect.Effect<ReadonlyArray<string>, DescendError, FileSystem.FileSystem | Path.Path>;
-//#endregion
-//#region src/Expand.d.ts
 /**
  * Options for {@link compileAndExpand}: every {@link DescendOptions} field,
  * plus the glob options the pattern compiles under.
@@ -303,8 +433,6 @@ export declare class GlobExpansionError extends GlobExpansionError_base {
  * @public
  */
 export declare const compileAndExpand: (pattern: string, options: CompileAndExpandOptions) => Effect.Effect<ReadonlyArray<string>, GlobExpansionError, FileSystem.FileSystem | Path.Path>;
-//#endregion
-//#region src/Walker.d.ts
 /**
  * Options for {@link Walker.ascend}.
  *
@@ -465,6 +593,5 @@ export declare class Walker {
    */
   static readonly findRoot: <E, R>(dirs: ReadonlyArray<string>, isRoot: (dir: string) => Effect.Effect<boolean, E, R>) => Effect.Effect<Option.Option<string>, never, R>;
 }
-//#endregion
 export type { AscendOptions, CompileAndExpandOptions, DescendOptions, DescendRecordOptions, DescendResult, UnreadableDirectory };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,5 +1,6 @@
+import { PathEscapeError, PathEscapeReason, confineRelative, confineRelativeResult } from "./Confine.js";
 import { DescendError, descend } from "./Descend.js";
 import { GlobExpansionError, compileAndExpand } from "./Expand.js";
 import { Walker } from "./Walker.js";
 
-export { DescendError, GlobExpansionError, Walker, compileAndExpand, descend };
+export { DescendError, GlobExpansionError, PathEscapeError, PathEscapeReason, Walker, compileAndExpand, confineRelative, confineRelativeResult, descend };

package/internal/segments.js

@@ -0,0 +1,25 @@
+// src/internal/segments.ts
+/**
+* Resolve `.` and `..` lexically over path segments, never above the start.
+*
+* Empty and `.` segments are dropped, a `..` pops its parent, and a `..` with
+* nothing left to pop is a climb above the start: the answer is then
+* `undefined`. `og/../x` resolves to `["x"]`; `og/../../x` climbs. The caller
+* splits, because the separator set is the caller's: a glob pattern's
+* backslash is an escape, never a separator.
+*/
+const resolveSegments = (segments) => {
+	const kept = [];
+	for (const segment of segments) {
+		if (segment === "" || segment === ".") continue;
+		if (segment === "..") {
+			if (kept.length === 0) return void 0;
+			kept.pop();
+			continue;
+		}
+		kept.push(segment);
+	}
+	return kept;
+};
+
+export { resolveSegments };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/walker",
-	"version": "0.18.0",
+	"version": "0.20.0",
 	"private": false,
 	"description": "Path traversal as Effect primitives: ascend a directory chain to the first matching candidate, or descend a tree expanding a glob against the filesystem.",
 	"keywords": [
@@ -37,7 +37,7 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/glob": "^0.13.0",
+		"@effected/glob": "^0.14.0",
 		"effect": "^4.0.0"
 	},
 	"engines": {