@effected/kit 0.12.0 → 0.13.0

package/PathContainment.js

@@ -0,0 +1,90 @@
+import { Effect, FileSystem, Path } from "effect";
+
+// src/PathContainment.ts
+/** Link hops followed before a candidate is judged outside (a loop never settles). */
+const MAX_LINK_HOPS = 40;
+/** Whether a platform failure means "nothing is there", the only failure read as absent. */
+const isNotFound = (error) => error.reason?._tag === "NotFound";
+/**
+* Decides whether a caller-supplied path stays inside a root.
+*
+* @remarks
+* Audience: a handler that must refuse a path outside its workspace before
+* reading or writing it. Neither form fails: "outside" is the answer `false`,
+* and the filesystem is required in `R` from core, never owned here. A
+* relative `candidate` is resolved against `root`, never the process working
+* directory.
+*
+* {@link PathContainment.isWithinLexical} is pure and compares spellings, so a
+* link inside the root that points out is invisible to it. Use
+* {@link PathContainment.isWithin} for anything that will touch the disk.
+*
+* @public
+*/
+var PathContainment = class PathContainment {
+	constructor() {}
+	/**
+	* Whether `candidate` is `root` or lies under it, comparing resolved
+	* spellings only (`..` segments and trailing separators are normalised;
+	* links are not followed). A sibling sharing a prefix (`/repo-other` against
+	* `/repo`) is outside. A relative `candidate` is resolved against `root`.
+	*/
+	static isWithinLexical(path, root, candidate) {
+		const base = path.resolve(root);
+		const target = path.resolve(base, candidate);
+		if (target === base) return true;
+		const relative = path.relative(base, target);
+		return relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+	}
+	/**
+	* Whether `candidate` is `root` or lies under it once links are resolved.
+	*
+	* @remarks
+	* The candidate need not exist: its nearest existing ancestor is resolved
+	* with `realPath` and the missing tail appended, so a path about to be
+	* created is judged by where its parent really is. A component that is a
+	* dangling link is followed to where it points (a link out of the root is
+	* outside even when its target is absent), up to a fixed number of hops;
+	* a loop is outside.
+	*
+	* Fails closed: only a `NotFound` counts as absent. Any other failure on a
+	* candidate component (permission denied, a link loop, a non-directory
+	* parent) answers `false`. The lexical answer stands in only when the root's
+	* own real path is `NotFound`; any other failure reading it is `false`.
+	*
+	* A point-in-time check: the filesystem can change between this answer and
+	* the read or write it guards.
+	*/
+	static isWithin = (root, candidate) => Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const base = path.resolve(root);
+		const realRoot = yield* Effect.result(fs.realPath(base));
+		if (realRoot._tag === "Failure") return isNotFound(realRoot.failure) && PathContainment.isWithinLexical(path, root, candidate);
+		let existing = path.resolve(base, candidate);
+		let tail = [];
+		let hops = 0;
+		for (;;) {
+			const real = yield* Effect.result(fs.realPath(existing));
+			if (real._tag === "Success") return PathContainment.isWithinLexical(path, realRoot.success, path.join(real.success, ...tail));
+			if (!isNotFound(real.failure)) return false;
+			const link = yield* Effect.result(fs.readLink(existing));
+			if (link._tag === "Success") {
+				hops += 1;
+				if (hops > MAX_LINK_HOPS) return false;
+				const parent = yield* Effect.result(fs.realPath(path.dirname(existing)));
+				if (parent._tag === "Failure") return false;
+				existing = path.resolve(parent.success, link.success, ...tail);
+				tail = [];
+				continue;
+			}
+			if (!isNotFound(link.failure)) return false;
+			const parent = path.dirname(existing);
+			if (parent === existing) return false;
+			tail = [path.basename(existing), ...tail];
+			existing = parent;
+		}
+	});
+};
+
+export { PathContainment };

package/index.d.ts

@@ -1,4 +1,4 @@
-import { Context, Duration, Effect, Option, Schema, Scope } from "effect";
+import { Context, Duration, Effect, FileSystem, Option, Path, Schema, Scope } from "effect";
 /**
  * The carrier package a tool's bins were installed through.
  *
@@ -400,6 +400,52 @@ export declare class LaunchContext {
    */
   static readonly projectDir: (input: ProjectDirInput) => string;
 }
+/**
+ * Decides whether a caller-supplied path stays inside a root.
+ *
+ * @remarks
+ * Audience: a handler that must refuse a path outside its workspace before
+ * reading or writing it. Neither form fails: "outside" is the answer `false`,
+ * and the filesystem is required in `R` from core, never owned here. A
+ * relative `candidate` is resolved against `root`, never the process working
+ * directory.
+ *
+ * {@link PathContainment.isWithinLexical} is pure and compares spellings, so a
+ * link inside the root that points out is invisible to it. Use
+ * {@link PathContainment.isWithin} for anything that will touch the disk.
+ *
+ * @public
+ */
+export declare class PathContainment {
+  private constructor();
+  /**
+   * Whether `candidate` is `root` or lies under it, comparing resolved
+   * spellings only (`..` segments and trailing separators are normalised;
+   * links are not followed). A sibling sharing a prefix (`/repo-other` against
+   * `/repo`) is outside. A relative `candidate` is resolved against `root`.
+   */
+  static isWithinLexical(path: Path.Path, root: string, candidate: string): boolean;
+  /**
+   * Whether `candidate` is `root` or lies under it once links are resolved.
+   *
+   * @remarks
+   * The candidate need not exist: its nearest existing ancestor is resolved
+   * with `realPath` and the missing tail appended, so a path about to be
+   * created is judged by where its parent really is. A component that is a
+   * dangling link is followed to where it points (a link out of the root is
+   * outside even when its target is absent), up to a fixed number of hops;
+   * a loop is outside.
+   *
+   * Fails closed: only a `NotFound` counts as absent. Any other failure on a
+   * candidate component (permission denied, a link loop, a non-directory
+   * parent) answers `false`. The lexical answer stands in only when the root's
+   * own real path is `NotFound`; any other failure reading it is `false`.
+   *
+   * A point-in-time check: the filesystem can change between this answer and
+   * the read or write it guards.
+   */
+  static readonly isWithin: (root: string, candidate: string) => Effect.Effect<boolean, never, FileSystem.FileSystem | Path.Path>;
+}
 /**
  * The working-directory half of a process, structurally. Node's `process`
  * satisfies it; pass it in, so nothing here reads `process` itself.

package/index.js

@@ -2,7 +2,8 @@ import { CurrentDistribution, Distribution, DistributionField, distributionSuffi
 import { ErrorText } from "./ErrorText.js";
 import { Exclusive, ExclusiveTimeout } from "./Exclusive.js";
 import { LaunchContext } from "./LaunchContext.js";
+import { PathContainment } from "./PathContainment.js";
 import { ProcessScope, ProcessScopeError } from "./ProcessScope.js";
 import { Remediation } from "./Remediation.js";
 
-export { CurrentDistribution, Distribution, DistributionField, ErrorText, Exclusive, ExclusiveTimeout, LaunchContext, ProcessScope, ProcessScopeError, Remediation, distributionSuffix, withDistribution, withDistributionVersion };
+export { CurrentDistribution, Distribution, DistributionField, ErrorText, Exclusive, ExclusiveTimeout, LaunchContext, PathContainment, ProcessScope, ProcessScopeError, Remediation, distributionSuffix, withDistribution, withDistributionVersion };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/kit",
-	"version": "0.12.0",
+	"version": "0.13.0",
 	"private": false,
 	"description": "Platform-free primitives shared by every front end of an Effect v4 tool: distribution identity, remediation, launch context, and transport-neutral process crash guards",
 	"keywords": [