@procedures/fs 0.6.0 → 0.8.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/fs",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "File system procedures: read, write, copy, move, glob, exists, mkdir and JSON read and write, callable in process, over RPC or from Claude through MCP.",
   "keywords": [
     "filesystem",
@@ -37,6 +37,10 @@
     "./register": {
       "types": "./dist/register.d.ts",
       "import": "./dist/register.js"
+    },
+    "./root": {
+      "types": "./dist/root.d.ts",
+      "import": "./dist/root.js"
     }
   },
   "files": [
@@ -61,7 +65,7 @@
     "procedures": "./dist/register.js"
   },
   "dependencies": {
-    "@procedures/client": "0.6.0",
+    "@procedures/client": "0.8.0",
     "zod": "^4.6.5"
   },
   "devDependencies": {

package/src/confine.ts

@@ -0,0 +1,246 @@
+/**
+ * The root of the files for all the procedures of a registry (roadmap R33).
+ *
+ * `confineFsProcedures()` gives the `fs.*` procedures the handlers of the root. The other
+ * procedures reach files too: they read with `node:fs`, or they start a program. This file
+ * applies the rules that each procedure declares in `metadata.fsRoot` (`FsRootRules` of the core):
+ *
+ * - **confined**: the procedure names its path inputs. The host examines each of them before the
+ *   handler starts. A working folder that the call does not give is the root. A path of `paths`
+ *   starts at the root, and the handler gets it absolute. A path of `names` starts at the working
+ *   folder, and the handler gets it as the caller gave it (a program resolves it the same way).
+ * - **program**: the procedure starts the program of its input (`shell.run`). The host refuses a
+ *   call of a client. It accepts the nested call of a confined procedure that names the program
+ *   procedure in `metadata.calls`: that caller chose the program and its arguments.
+ * - **refused**: the rules give the reason that the root cannot confine the procedure.
+ *
+ * A procedure without rules gets a decision from its effects. The decision fails closed: the host
+ * refuses the procedure when its effects are not known, when it reads or writes `fs`, or when it
+ * writes `process`. A data-driven procedure stays as it is: it reaches files only through its
+ * nested calls, and each nested call gets the rules of its own procedure.
+ *
+ * Each refusal is the error of a path outside the root: `FORBIDDEN` with the reason `outside-root`.
+ */
+
+import {
+  callMatches,
+  declaredCalls,
+  effectsOf,
+  isDataDriven,
+  pathToKey,
+  scopeOf,
+  withScope,
+  type AnyProcedure,
+  type FsRootRules,
+  type ProcedureContext,
+  type ProcedurePath,
+  type ProcedureRegistry,
+} from "@procedures/client";
+import { inRoot, outsideRoot, resolveRoot, type ResolvedRoot } from "./root.js";
+
+/** What a root does to a procedure. */
+export type RootKind = "fs" | "confined" | "program" | "refused" | "unchanged";
+
+/** The decision of a root for one procedure. */
+export interface RootDecision {
+  readonly kind: RootKind;
+  /** For the kind `refused`: the reason. */
+  readonly reason?: string;
+}
+
+/** The resource name of the files of the host (CAPABILITIES-2026-10). */
+const FILES = "fs";
+/** The resource name of a procedure that starts any program. */
+const PROGRAMS = "process";
+
+/** The keys of the rules that `FsRootRules` has. */
+const RULE_KEYS: ReadonlySet<string> = new Set(["cwd", "paths", "names", "required", "values", "refuse", "program"]);
+
+/** The procedure key of a path, for the messages. */
+const keyOf = (procedure: { readonly path: ProcedurePath }): string => pathToKey(procedure.path);
+
+/** True for a list of names that are not empty. */
+function isNameList(value: unknown): value is readonly string[] {
+  return Array.isArray(value) && value.every((name) => typeof name === "string" && name.length > 0);
+}
+
+/**
+ * This function gives the rules of a procedure, or undefined when it has none. It throws for
+ * rules that are not correct, because the root cannot apply them.
+ */
+export function rootRulesOf(procedure: Pick<AnyProcedure, "path" | "metadata">): FsRootRules | undefined {
+  const rules = (procedure.metadata as { fsRoot?: unknown } | undefined)?.fsRoot;
+  if (rules === undefined) return undefined;
+  const invalid = (problem: string): Error => new Error(`The metadata.fsRoot of ${keyOf(procedure)} is not correct: ${problem}`);
+  if (rules === null || typeof rules !== "object" || Array.isArray(rules)) throw invalid("it must be an object");
+  const record = rules as Record<string, unknown>;
+  for (const key of Object.keys(record)) {
+    if (!RULE_KEYS.has(key)) throw invalid(`it has the unknown key ${key}`);
+  }
+  if (record["cwd"] !== undefined && (typeof record["cwd"] !== "string" || record["cwd"] === "")) throw invalid("cwd must be the name of an input");
+  for (const key of ["paths", "names", "required", "values"] as const) {
+    if (record[key] !== undefined && !isNameList(record[key])) throw invalid(`${key} must be a list of texts`);
+  }
+  if (record["refuse"] !== undefined && (typeof record["refuse"] !== "string" || record["refuse"] === "")) throw invalid("refuse must be the reason, as text");
+  if (record["program"] !== undefined && typeof record["program"] !== "boolean") throw invalid("program must be true or false");
+  const typed = rules as FsRootRules;
+  if (typed.refuse !== undefined && Object.keys(record).length > 1) throw invalid("refuse cannot go with other rules");
+  const paths = new Set(typed.paths ?? []);
+  for (const name of typed.required ?? []) {
+    if (!paths.has(name)) throw invalid(`the required input ${name} is not in paths`);
+  }
+  const inputs = [...(typed.cwd !== undefined ? [typed.cwd] : []), ...(typed.paths ?? []), ...(typed.names ?? [])];
+  if (new Set(inputs).size !== inputs.length) throw invalid("an input is in more than one of cwd, paths and names");
+  return typed;
+}
+
+/**
+ * This function tells what a root does to a procedure, without a root. It throws for rules that
+ * are not correct. `confineToRoot()` uses the same decision.
+ */
+export function rootDecisionOf(procedure: Pick<AnyProcedure, "path" | "metadata" | "handler">): RootDecision {
+  if (procedure.path[0] === FILES) return { kind: "fs" };
+  const rules = rootRulesOf(procedure);
+  if (rules !== undefined) {
+    if (rules.refuse !== undefined) return { kind: "refused", reason: rules.refuse };
+    return { kind: rules.program === true ? "program" : "confined" };
+  }
+  // A data-driven procedure runs the refs of its caller: each nested call gets its own decision
+  if (isDataDriven(procedure)) return { kind: "unchanged" };
+  const effects = effectsOf(procedure);
+  if (effects?.reads === undefined || effects.writes === undefined) {
+    return { kind: "refused", reason: "it declares no effects and no metadata.fsRoot, so its files are not known" };
+  }
+  if (effects.reads.includes(FILES) || effects.writes.includes(FILES)) {
+    return { kind: "refused", reason: "it reads or writes files, and it declares no metadata.fsRoot" };
+  }
+  if (effects.writes.includes(PROGRAMS)) {
+    return { kind: "refused", reason: "it starts a program, and it declares no metadata.fsRoot" };
+  }
+  return { kind: "unchanged" };
+}
+
+/** What `confineToRoot()` did. Each list holds the keys of the procedures. */
+export interface ConfinedRegistry {
+  /** The absolute path of the root. */
+  root: string;
+  /** The `fs.*` procedures: they have the handlers of `createFsModule({ root })`. */
+  fs: string[];
+  /** The procedures whose path inputs the root examines. */
+  confined: string[];
+  /** The procedures that start the program of their input: only as a nested call of a confined procedure. */
+  programs: string[];
+  /** The procedures that the root refuses. */
+  refused: string[];
+  /** The procedures that reach no file: the root does not change them. */
+  unchanged: string[];
+}
+
+/** The values of a path input: a text, or a list of texts. Another value cannot be examined. */
+function pathValues(value: unknown, name: string, at: ProcedurePath): string[] {
+  if (typeof value === "string") return [value];
+  if (Array.isArray(value) && value.every((item) => typeof item === "string")) return value as string[];
+  throw outsideRoot(at, `the input ${name} is not a path or a list of paths, so the root cannot examine it`);
+}
+
+/**
+ * This function gives the input with each path in the root. The working folder that the call does
+ * not give is the root. Each path of `paths` starts at the root and becomes absolute. A path of
+ * `names` starts at the working folder, and it stays as it is.
+ */
+async function confinedInput(input: unknown, rules: FsRootRules, root: ResolvedRoot, at: ProcedurePath): Promise<unknown> {
+  const examines = rules.cwd !== undefined || (rules.paths?.length ?? 0) > 0 || (rules.names?.length ?? 0) > 0;
+  if (!examines) return input;
+  if (input === null || typeof input !== "object" || Array.isArray(input)) {
+    throw outsideRoot(at, "the input is not an object, so the root cannot examine its paths");
+  }
+  const given = input as Record<string, unknown>;
+  const next: Record<string, unknown> = { ...given };
+  const kept = new Set(rules.values ?? []);
+  let base = root.folder;
+  if (rules.cwd !== undefined) {
+    const value = given[rules.cwd];
+    if (value !== undefined && value !== null && typeof value !== "string") {
+      throw outsideRoot(at, `the input ${rules.cwd} is not a folder, so the root cannot examine it`);
+    }
+    base = await inRoot(root, typeof value === "string" ? value : ".", at);
+    next[rules.cwd] = base;
+  }
+  for (const name of rules.paths ?? []) {
+    const value = given[name];
+    if (value === undefined || value === null) {
+      if (rules.required?.includes(name)) {
+        throw outsideRoot(at, `the input ${name} has no value, and its default is outside the root ${root.folder}: give a path in the root`);
+      }
+      continue;
+    }
+    const absolute: string[] = [];
+    for (const path of pathValues(value, name, at)) absolute.push(kept.has(path) ? path : await inRoot(root, path, at));
+    next[name] = typeof value === "string" ? absolute[0] : absolute;
+  }
+  for (const name of rules.names ?? []) {
+    const value = given[name];
+    if (value === undefined || value === null) continue;
+    for (const path of pathValues(value, name, at)) if (!kept.has(path)) await inRoot(root, path, at, base);
+  }
+  // A runner reads the scope of its raw input: the copy keeps it (DOC-10)
+  return withScope(next, scopeOf(input));
+}
+
+/** The handler of a procedure under a root. */
+type Handler = NonNullable<AnyProcedure["handler"]>;
+
+/**
+ * This function applies the decision of each procedure of the registry, except `fs.*`, to a root
+ * that exists. It replaces the handler of each confined, program and refused procedure, and it
+ * adds no procedure. `confineToRoot()` of the module starts it after the `fs.*` procedures.
+ */
+export function confineOtherProcedures(registry: ProcedureRegistry, folder: string): Omit<ConfinedRegistry, "root" | "fs"> {
+  const result: Omit<ConfinedRegistry, "root" | "fs"> = { confined: [], programs: [], refused: [], unchanged: [] };
+  // All decisions first: a rule that is not correct throws before the registry changes
+  const decisions = registry
+    .getAll()
+    .filter((procedure) => procedure.path[0] !== FILES)
+    .map((procedure) => ({ procedure, decision: rootDecisionOf(procedure) }));
+  const confinedProcedures = new WeakSet<AnyProcedure>();
+  const root = (): Promise<ResolvedRoot> => resolveRoot(folder);
+
+  for (const { procedure, decision } of decisions) {
+    const key = keyOf(procedure);
+    const original = procedure.handler;
+    if (decision.kind === "unchanged" || original === undefined) {
+      result.unchanged.push(key);
+      continue;
+    }
+    const rules = rootRulesOf(procedure) ?? {};
+    let handler: Handler;
+    if (decision.kind === "refused") {
+      const message = `the root ${folder} cannot confine this procedure: ${decision.reason ?? "no reason"}`;
+      handler = (async () => {
+        throw outsideRoot(procedure.path, message);
+      }) as Handler;
+      result.refused.push(key);
+    } else if (decision.kind === "program") {
+      handler = (async (input: unknown, ctx: ProcedureContext | undefined) => {
+        const caller = ctx?.caller;
+        const named = caller !== undefined && (declaredCalls(caller) ?? []).some((entry) => callMatches(entry, key));
+        if (caller === undefined || !confinedProcedures.has(caller) || !named) {
+          const from = caller === undefined ? "a client" : keyOf(caller);
+          throw outsideRoot(
+            procedure.path,
+            `this procedure starts the program of its input. Under the root ${folder}, it runs only as the nested call of a confined procedure that names it in metadata.calls, not for ${from}`,
+          );
+        }
+        return original(await confinedInput(input, rules, await root(), procedure.path), ctx as ProcedureContext);
+      }) as Handler;
+      result.programs.push(key);
+    } else {
+      handler = (async (input: unknown, ctx: ProcedureContext) =>
+        original(await confinedInput(input, rules, await root(), procedure.path), ctx)) as Handler;
+      result.confined.push(key);
+    }
+    registry.register({ ...procedure, handler }, { override: true });
+    if (decision.kind === "confined") confinedProcedures.add(registry.get(procedure.path)!);
+  }
+  return result;
+}

package/src/module.ts

@@ -7,13 +7,15 @@
  * This file is referenced by package.json's client.procedures field.
  *
  * `fsModule` operates on each path. `createFsModule({ root })` gives the same procedures, and
- * each path of their input must be in the root (roadmap R33, `root.ts`).
+ * each path of their input must be in the root (roadmap R33, `root.ts`). `confineToRoot()` gives
+ * a root to all the procedures of a registry (`confine.ts`).
  */
 
 import { createProcedure, zodAdapter, defineModule, type AnyProcedure, type Effects, type ProcedureModule, PROCEDURE_REGISTRY, registerModules, type ProcedureRegistry } from "@procedures/client";
 import { statSync } from "node:fs";
 import { resolve } from "node:path";
 import { HANDLER_NAMES, rootedHandlers } from "./handlers.js";
+import { confineOtherProcedures, rootDecisionOf, type ConfinedRegistry } from "./confine.js";
 import { read } from "./procedures/fs/read.js";
 import { write } from "./procedures/fs/write.js";
 import { exists } from "./procedures/fs/exists.js";
@@ -325,6 +327,9 @@ const fsWatchProcedure = createProcedure()
 // Registration
 // =============================================================================
 
+// The root for all the procedures of a registry (roadmap R33)
+export { rootDecisionOf, rootRulesOf, type ConfinedRegistry, type RootDecision, type RootKind } from "./confine.js";
+
 /**
  * The module of this package, for `createRegistry()`: its procedures as data. Importing this
  * file registers nothing. (`register.ts` registers the same procedures in the global registry.)
@@ -395,8 +400,19 @@ export interface ConfinedFs {
  * A nested call of another procedure (`lib.scan` calls `fs.readdir`) finds the procedure in the
  * registry, so the root confines that call too. The root must be a folder that exists. An `fs.*`
  * procedure that this package does not have is an error, because the root cannot confine it.
+ *
+ * This function changes only the `fs.*` procedures. A host uses `confineToRoot()`: it also keeps
+ * the paths of the other procedures in the root, or it refuses them.
  */
 export function confineFsProcedures(registry: ProcedureRegistry, root: string): ConfinedFs {
+  const folder = rootFolder(root);
+  const rooted = rootedFsProcedures(registry, folder);
+  for (const procedure of rooted) registry.register(procedure, { override: true });
+  return { root: folder, procedures: rooted.map((procedure) => procedure.path.join(".")) };
+}
+
+/** The absolute path of a root. It throws when the root does not exist or is not a folder. */
+function rootFolder(root: string): string {
   const folder = resolve(root);
   let isFolder: boolean;
   try {
@@ -405,19 +421,43 @@ export function confineFsProcedures(registry: ProcedureRegistry, root: string):
     throw new Error(`The root of the file procedures does not exist: ${folder}`);
   }
   if (!isFolder) throw new Error(`The root of the file procedures is not a folder: ${folder}`);
+  return folder;
+}
+
+/** The procedures with a root for the `fs.*` procedures of a registry. An unknown `fs.*` procedure is an error. */
+function rootedFsProcedures(registry: ProcedureRegistry, folder: string): AnyProcedure[] {
   const rooted = new Map(createFsModule({ root: folder }).procedures.map((procedure) => [procedure.path.join("."), procedure]));
   const present = registry.getAll().filter((procedure) => procedure.path[0] === "fs");
-  for (const procedure of present) {
-    const key = procedure.path.join(".");
-    if (!rooted.has(key)) throw new Error(`The root of the file procedures cannot confine ${key}: @procedures/fs has no such procedure`);
-  }
-  const procedures: string[] = [];
-  for (const procedure of present) {
+  return present.map((procedure) => {
     const key = procedure.path.join(".");
-    registry.register(rooted.get(key)!, { override: true });
-    procedures.push(key);
-  }
-  return { root: folder, procedures };
+    const replacement = rooted.get(key);
+    if (!replacement) throw new Error(`The root of the file procedures cannot confine ${key}: @procedures/fs has no such procedure`);
+    return replacement;
+  });
+}
+
+/**
+ * This function confines each procedure of a registry to a root (roadmap R33). A host starts it
+ * after the last registration: `mark --fs-root`, `procedure-server --fs-root` and `MCP_FS_ROOT`.
+ *
+ * - Each `fs.*` procedure gets the handler of `createFsModule({ root })`, as with
+ *   `confineFsProcedures()`.
+ * - Each other procedure gets the decision of `rootDecisionOf()`: the host examines its path
+ *   inputs (`metadata.fsRoot`), or it refuses the procedure. A procedure that reaches no file
+ *   stays as it is.
+ *
+ * The function adds no procedure, and the names of the tools do not change. It changes nothing
+ * when it throws: for a root that does not exist, an unknown `fs.*` procedure, or rules that are
+ * not correct.
+ */
+export function confineToRoot(registry: ProcedureRegistry, root: string): ConfinedRegistry {
+  const folder = rootFolder(root);
+  const rooted = rootedFsProcedures(registry, folder);
+  // Each decision before a change: rules that are not correct throw here
+  for (const procedure of registry.getAll()) rootDecisionOf(procedure);
+  for (const procedure of rooted) registry.register(procedure, { override: true });
+  const others = confineOtherProcedures(registry, folder);
+  return { root: folder, fs: rooted.map((procedure) => procedure.path.join(".")), ...others };
 }
 
 /**

package/src/root.ts

@@ -1,6 +1,9 @@
 /**
  * The root of the file procedures: one folder that confines each path (roadmap R33).
  *
+ * This file is the `./root` entry of the package: the rules without the procedures. Another
+ * package that confines its own paths imports them, for example `@procedures/archive`.
+ *
  * `createFsModule({ root })` sends each path of an input through `inRoot()`:
  * - A relative path starts at the root, not at the working folder of the process.
  * - A path outside the root gives `FORBIDDEN` with the reason `outside-root`. This includes a
@@ -88,14 +91,17 @@ export interface ResolvedRoot {
   real: string;
 }
 
-/** This function gives the absolute path and the real path of a root. The root must exist. */
-export async function resolveRoot(root: string): Promise<ResolvedRoot> {
+/**
+ * This function gives the absolute path and the real path of a root. The root must exist. The
+ * error of a missing root names `owner`, for example "the archive procedures".
+ */
+export async function resolveRoot(root: string, owner = "the file procedures"): Promise<ResolvedRoot> {
   const folder = resolve(root);
   try {
     return { folder, real: await realpath(folder) };
   } catch (error) {
     if (!isMissing(error)) throw error;
-    const missing = new Error(`The root of the file procedures does not exist: ${folder}`) as NodeJS.ErrnoException;
+    const missing = new Error(`The root of ${owner} does not exist: ${folder}`) as NodeJS.ErrnoException;
     missing.code = "ENOENT";
     throw missing;
   }
@@ -120,12 +126,12 @@ export async function realPathIsInside(root: ResolvedRoot, absolute: string): Pr
 }
 
 /**
- * This function gives the absolute path of `path` in the root. A relative path starts at the
- * root. The real path decides: a path whose real path is outside the real path of the root gives
- * `FORBIDDEN` with the reason `outside-root`.
+ * This function gives the absolute path of `path` in the root. A relative path starts at `base`,
+ * and the default `base` is the root. The real path decides: a path whose real path is outside the
+ * real path of the root gives `FORBIDDEN` with the reason `outside-root`.
  */
-export async function inRoot(root: ResolvedRoot, path: string, procedure: ProcedurePath): Promise<string> {
-  const absolute = resolve(root.folder, path);
+export async function inRoot(root: ResolvedRoot, path: string, procedure: ProcedurePath, base: string = root.folder): Promise<string> {
+  const absolute = resolve(base, path);
   const real = await realPathOf(absolute);
   // A path counts as inside by its given form or by its real form. On Windows, the two forms of a
   // folder can differ by more than the links: a short 8.3 name (RUNNER~1) has a long real name.