@effected/walker 0.19.0 → 0.20.1

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,3 +1,4 @@
+import { resolveSegments } from "./internal/segments.js";
 import { Effect, FileSystem, Path, Schema } from "effect";
 
 // src/Descend.ts
@@ -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. */

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,32 +1,11 @@
 import { Effect, FileSystem, Option, Path } from "effect";
 
 // src/Walker.ts
-const ascend = (start, options) => Effect.gen(function* () {
-	const path = yield* Path.Path;
-	const maxDepth = options?.maxDepth ?? 256;
-	if (!Number.isInteger(maxDepth) || maxDepth < 1) return yield* Effect.die(/* @__PURE__ */ new Error(`Walker.ascend: maxDepth must be a positive integer, received ${maxDepth}`));
-	if (options?.stopAt !== void 0 && !path.isAbsolute(options.stopAt)) return yield* Effect.die(/* @__PURE__ */ new Error(`Walker.ascend: stopAt must be an absolute path, received ${JSON.stringify(options.stopAt)} (ascending from ${JSON.stringify(start)})`));
-	const ceiling = options?.stopAt === void 0 ? void 0 : path.resolve(options.stopAt);
-	const dirs = [];
-	let current = start;
-	for (let depth = 0; depth < maxDepth; depth++) {
-		dirs.push(current);
-		if (ceiling !== void 0 && (current === ceiling || path.resolve(current) === ceiling)) break;
-		const parent = path.dirname(current);
-		if (parent === current) break;
-		current = parent;
-	}
-	return dirs;
-});
-const ascendWithin = (start, ceiling, options) => Effect.gen(function* () {
-	if (Option.isNone(ceiling)) return yield* ascend(start, options);
-	return yield* ascendToPhysical(start, ceiling.value, options);
-});
 const ascendToPhysical = (start, ceiling, options) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const path = yield* Path.Path;
 	if (!path.isAbsolute(ceiling)) return yield* Effect.die(/* @__PURE__ */ new Error(`Walker.ascendWithin: ceiling must be an absolute path, received ${JSON.stringify(ceiling)} (ascending from ${JSON.stringify(start)})`));
-	const dirs = yield* ascend(start, {
+	const dirs = yield* Walker.ascend(start, {
 		...options,
 		stopAt: ceiling
 	});
@@ -34,27 +13,16 @@ const ascendToPhysical = (start, ceiling, options) => Effect.gen(function* () {
 	if (last !== void 0 && path.resolve(last) === path.resolve(ceiling)) return dirs;
 	const physical = yield* Effect.option(fs.realPath(ceiling));
 	if (Option.isNone(physical)) return dirs;
-	const hit = yield* findRoot(dirs, (dir) => Effect.map(fs.realPath(dir), (real) => real === physical.value));
+	const hit = yield* Walker.findRoot(dirs, (dir) => Effect.map(fs.realPath(dir), (real) => real === physical.value));
 	return Option.isSome(hit) ? dirs.slice(0, dirs.indexOf(hit.value) + 1) : dirs;
 });
-const firstMatch = (candidates, predicate) => Effect.gen(function* () {
-	for (const candidate of candidates) if (yield* Effect.catch(predicate(candidate), () => Effect.succeed(false))) return Option.some(candidate);
-	return Option.none();
-});
-const findUpward = (dirs, candidatesFor) => Effect.gen(function* () {
-	const fs = yield* FileSystem.FileSystem;
-	const candidates = [];
-	for (const dir of dirs) candidates.push(...candidatesFor(dir));
-	return yield* firstMatch(candidates, (candidate) => fs.exists(candidate));
-});
-const findRoot = (dirs, isRoot) => firstMatch(dirs, isRoot);
 /**
 * Upward path traversal primitives: the directory chain from a start path to the
 * root, and first-match scans over it.
 *
 * @public
 */
-var Walker = class {
+var Walker = class Walker {
 	constructor() {}
 	/**
 	* Ascend from `start` toward the filesystem root, yielding each directory,
@@ -90,7 +58,25 @@ var Walker = class {
 	* // Requires `Path` from the platform layer.
 	* ```
 	*/
-	static ascend = ascend;
+	static ascend(start, options) {
+		return Effect.gen(function* () {
+			const path = yield* Path.Path;
+			const maxDepth = options?.maxDepth ?? 256;
+			if (!Number.isInteger(maxDepth) || maxDepth < 1) return yield* Effect.die(/* @__PURE__ */ new Error(`Walker.ascend: maxDepth must be a positive integer, received ${maxDepth}`));
+			if (options?.stopAt !== void 0 && !path.isAbsolute(options.stopAt)) return yield* Effect.die(/* @__PURE__ */ new Error(`Walker.ascend: stopAt must be an absolute path, received ${JSON.stringify(options.stopAt)} (ascending from ${JSON.stringify(start)})`));
+			const ceiling = options?.stopAt === void 0 ? void 0 : path.resolve(options.stopAt);
+			const dirs = [];
+			let current = start;
+			for (let depth = 0; depth < maxDepth; depth++) {
+				dirs.push(current);
+				if (ceiling !== void 0 && (current === ceiling || path.resolve(current) === ceiling)) break;
+				const parent = path.dirname(current);
+				if (parent === current) break;
+				current = parent;
+			}
+			return dirs;
+		});
+	}
 	/**
 	* {@link Walker.ascend} bounded by a PHYSICAL ceiling: stops at the nearest
 	* directory whose real path is the ceiling's real path, inclusive.
@@ -118,7 +104,12 @@ var Walker = class {
 	* A present ceiling must be absolute; a relative one **dies**, for the
 	* reasons {@link AscendOptions.stopAt} gives.
 	*/
-	static ascendWithin = ascendWithin;
+	static ascendWithin(start, ceiling, options) {
+		return Effect.gen(function* () {
+			if (Option.isNone(ceiling)) return yield* Walker.ascend(start, options);
+			return yield* ascendToPhysical(start, ceiling.value, options);
+		});
+	}
 	/**
 	* The first candidate whose `predicate` reports true, or `Option.none()`.
 	*
@@ -133,7 +124,12 @@ var Walker = class {
 	* programmer error and surfaces as a defect. Do not change this to
 	* `Effect.catchCause` — the distinction is load-bearing.
 	*/
-	static firstMatch = firstMatch;
+	static firstMatch(candidates, predicate) {
+		return Effect.gen(function* () {
+			for (const candidate of candidates) if (yield* Effect.catch(predicate(candidate), () => Effect.succeed(false))) return Option.some(candidate);
+			return Option.none();
+		});
+	}
 	/**
 	* The first existing path among the candidates `candidatesFor` produces for each
 	* directory in `dirs`, scanned in order. Nearer directories win.
@@ -142,7 +138,14 @@ var Walker = class {
 	* Candidates materialize up front, bounded by `dirs.length × candidatesFor`'s
 	* output — a few hundred strings under the default `maxDepth`.
 	*/
-	static findUpward = findUpward;
+	static findUpward(dirs, candidatesFor) {
+		return Effect.gen(function* () {
+			const fs = yield* FileSystem.FileSystem;
+			const candidates = [];
+			for (const dir of dirs) candidates.push(...candidatesFor(dir));
+			return yield* Walker.firstMatch(candidates, (candidate) => fs.exists(candidate));
+		});
+	}
 	/**
 	* The first directory in `dirs` that `isRoot` accepts.
 	*
@@ -151,7 +154,9 @@ var Walker = class {
 	* identity. `isRoot` is a caller-supplied marker test (a `.git` entry, a
 	* `pnpm-workspace.yaml`), and its failures are absorbed per directory.
 	*/
-	static findRoot = findRoot;
+	static findRoot(dirs, isRoot) {
+		return Walker.firstMatch(dirs, isRoot);
+	}
 };
 
 export { Walker };

package/index.d.ts

@@ -1,5 +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";
+/**
+ * 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`.
  *
@@ -397,7 +530,7 @@ export declare class Walker {
    * // Requires `Path` from the platform layer.
    * ```
    */
-  static readonly ascend: (start: string, options?: AscendOptions) => Effect.Effect<ReadonlyArray<string>, never, Path.Path>;
+  static ascend(start: string, options?: AscendOptions): Effect.Effect<ReadonlyArray<string>, never, Path.Path>;
   /**
    * {@link Walker.ascend} bounded by a PHYSICAL ceiling: stops at the nearest
    * directory whose real path is the ceiling's real path, inclusive.
@@ -425,7 +558,7 @@ export declare class Walker {
    * A present ceiling must be absolute; a relative one **dies**, for the
    * reasons {@link AscendOptions.stopAt} gives.
    */
-  static readonly ascendWithin: (start: string, ceiling: Option.Option<string>, options?: Pick<AscendOptions, "maxDepth">) => Effect.Effect<ReadonlyArray<string>, never, FileSystem.FileSystem | Path.Path>;
+  static ascendWithin(start: string, ceiling: Option.Option<string>, options?: Pick<AscendOptions, "maxDepth">): Effect.Effect<ReadonlyArray<string>, never, FileSystem.FileSystem | Path.Path>;
   /**
    * The first candidate whose `predicate` reports true, or `Option.none()`.
    *
@@ -440,7 +573,7 @@ export declare class Walker {
    * programmer error and surfaces as a defect. Do not change this to
    * `Effect.catchCause` — the distinction is load-bearing.
    */
-  static readonly firstMatch: <E, R>(candidates: ReadonlyArray<string>, predicate: (candidate: string) => Effect.Effect<boolean, E, R>) => Effect.Effect<Option.Option<string>, never, R>;
+  static firstMatch<E, R>(candidates: ReadonlyArray<string>, predicate: (candidate: string) => Effect.Effect<boolean, E, R>): Effect.Effect<Option.Option<string>, never, R>;
   /**
    * The first existing path among the candidates `candidatesFor` produces for each
    * directory in `dirs`, scanned in order. Nearer directories win.
@@ -449,7 +582,7 @@ export declare class Walker {
    * Candidates materialize up front, bounded by `dirs.length × candidatesFor`'s
    * output — a few hundred strings under the default `maxDepth`.
    */
-  static readonly findUpward: (dirs: ReadonlyArray<string>, candidatesFor: (dir: string) => ReadonlyArray<string>) => Effect.Effect<Option.Option<string>, never, FileSystem.FileSystem>;
+  static findUpward(dirs: ReadonlyArray<string>, candidatesFor: (dir: string) => ReadonlyArray<string>): Effect.Effect<Option.Option<string>, never, FileSystem.FileSystem>;
   /**
    * The first directory in `dirs` that `isRoot` accepts.
    *
@@ -458,7 +591,7 @@ export declare class Walker {
    * identity. `isRoot` is a caller-supplied marker test (a `.git` entry, a
    * `pnpm-workspace.yaml`), and its failures are absorbed per directory.
    */
-  static readonly findRoot: <E, R>(dirs: ReadonlyArray<string>, isRoot: (dir: string) => Effect.Effect<boolean, E, R>) => Effect.Effect<Option.Option<string>, never, R>;
+  static findRoot<E, R>(dirs: ReadonlyArray<string>, isRoot: (dir: string) => Effect.Effect<boolean, E, R>): Effect.Effect<Option.Option<string>, never, R>;
 }
 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.19.0",
+	"version": "0.20.1",
 	"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": [

package/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.59.1"
+      "packageVersion": "7.59.4"
     }
   ]
 }