@procedures/archive 0.3.0 → 0.5.0

package/dist/root.js

@@ -0,0 +1,128 @@
+/**
+ * The root of the archive procedures: one folder that confines each path (roadmap R33).
+ *
+ * The rules are the rules of `root.ts` of `@procedures/fs` (`createFsModule({ root })`):
+ * - 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
+ *   path that goes up with `..`, an absolute path outside the root, a path on another drive, and
+ *   a symlink or a junction that leads out of the root.
+ * - The check uses the real path (`fs.realpath`) of the path. For a path that does not exist, it
+ *   uses the real path of the nearest existing ancestor. So a symlinked parent folder cannot
+ *   lead a write or a `mkdir` out of the root.
+ *
+ * On Windows, the comparison ignores the case of the letters, and `/` and `\` are the same.
+ */
+import { readlink, realpath } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { InvocationError } from "@procedures/client";
+/** The reason of the `FORBIDDEN` error for a path outside the root. */
+export const OUTSIDE_ROOT = "outside-root";
+/** The maximum number of symlinks that one check follows. After it, the check fails with `ELOOP`. */
+const MAX_LINKS = 40;
+/**
+ * This function tells if `path` is `folder` or a path in `folder`. The two paths are absolute.
+ * On Windows, the case of the letters is not significant.
+ */
+export function isInside(folder, path) {
+    const rel = relative(folder, path);
+    return rel === "" || (!isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep}`));
+}
+/** True for the error of a path that does not exist. */
+function isMissing(error) {
+    const code = error.code;
+    return code === "ENOENT" || code === "ENOTDIR";
+}
+/** The target of a symlink, or undefined when the path is not a symlink or does not exist. */
+async function linkTarget(path) {
+    try {
+        return await readlink(path);
+    }
+    catch (error) {
+        // EINVAL: the path is not a symlink
+        const code = error.code;
+        if (code === "EINVAL" || isMissing(error))
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * This function gives the real path of an absolute path. For a path that does not exist, it
+ * gives the real path of the nearest existing ancestor and the rest of the path. A symlink whose
+ * target does not exist leads to its target, because a write follows it.
+ */
+export async function realPathOf(path, links = 0) {
+    const rest = [];
+    let current = path;
+    for (;;) {
+        try {
+            return join(await realpath(current), ...rest);
+        }
+        catch (error) {
+            if (!isMissing(error))
+                throw error;
+        }
+        const target = await linkTarget(current);
+        if (target !== undefined) {
+            if (links >= MAX_LINKS) {
+                const loop = new Error(`Too many symlinks in the path ${path}`);
+                loop.code = "ELOOP";
+                throw loop;
+            }
+            return join(await realPathOf(resolve(dirname(current), target), links + 1), ...rest);
+        }
+        const parent = dirname(current);
+        // No ancestor exists, for example a drive that is not there
+        if (parent === current)
+            return join(current, ...rest);
+        rest.unshift(basename(current));
+        current = parent;
+    }
+}
+/** This function gives the absolute path and the real path of a root. The root must exist. */
+export async function resolveRoot(root) {
+    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 archive procedures does not exist: ${folder}`);
+        missing.code = "ENOENT";
+        throw missing;
+    }
+}
+/** The `FORBIDDEN` error for a path outside the root. */
+export function outsideRoot(procedure, message) {
+    return new InvocationError("FORBIDDEN", `${procedure.join(".")}: ${message}`, procedure, OUTSIDE_ROOT);
+}
+/** True for the `FORBIDDEN` error of a path outside the root. */
+export function isOutsideRoot(error) {
+    return error instanceof InvocationError && error.code === "FORBIDDEN" && error.reason === OUTSIDE_ROOT;
+}
+/**
+ * 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`.
+ */
+export async function inRoot(root, path, procedure) {
+    const absolute = resolve(root.folder, 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.
+    if (!isInside(root.folder, absolute) && !isInside(root.real, absolute) && !isInside(root.real, real)) {
+        throw outsideRoot(procedure, `the path ${JSON.stringify(path)} is outside the root ${root.folder}`);
+    }
+    if (!isInside(root.real, real)) {
+        throw outsideRoot(procedure, `the path ${JSON.stringify(path)} leads out of the root ${root.folder} through a symlink`);
+    }
+    return absolute;
+}
+/** This function gives the paths of one call. With a root, the root must exist when the call starts. */
+export async function placesOf(root, procedure) {
+    if (root === undefined)
+        return { root: undefined, place: async (path) => resolve(path) };
+    const resolved = await resolveRoot(root);
+    return { root: resolved, place: (path) => inRoot(resolved, path, procedure) };
+}
+//# sourceMappingURL=root.js.map

package/dist/root.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"root.js","sourceRoot":"","sources":["../src/root.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/archive",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Archives as procedures: make, list and extract tar.gz and zip, with a check of each path against zip slip and links out of the target.",
   "keywords": [
     "procedures",
@@ -62,7 +62,7 @@
     "procedures": "./dist/register.js"
   },
   "dependencies": {
-    "@procedures/client": "0.3.0",
+    "@procedures/client": "0.5.0",
     "tar": "^7.5.0",
     "zod": "^4.6.5"
   },

package/src/format.ts

@@ -7,12 +7,14 @@ import { open } from "node:fs/promises";
 import { ArchiveError } from "./errors.js";
 import type { ArchiveFormat } from "./types.js";
 
-/** The limits of the procedures of a module. */
+/** The limits and the root of the procedures of a module. */
 export interface ArchiveSettings {
   /** The most bytes of the files of one archive: `extract` and `create` refuse more. */
   readonly maxBytes: number;
   /** The most entries of one archive. */
   readonly maxEntries: number;
+  /** The absolute folder that confines each path of the inputs (roadmap R33), or undefined for no root. */
+  readonly root?: string | undefined;
 }
 
 /** The default most bytes: 1 GiB. */

package/src/index.ts

@@ -6,4 +6,6 @@ export { archiveCreate, archiveExtract, archiveList } from "./procedures/archive
 export { ArchiveError, type ArchiveErrorCode } from "./errors.js";
 export { DEFAULT_ARCHIVE_SETTINGS, DEFAULT_MAX_BYTES, DEFAULT_MAX_ENTRIES, formatOfFile, formatOfName, sniffFormat, type ArchiveSettings } from "./format.js";
 export { entryParts, isAbsoluteName, planExtract, type PlanOptions, type PlannedEntry, type RawEntry } from "./paths.js";
+// The root that confines each path (roadmap R33)
+export { OUTSIDE_ROOT, isInside, isOutsideRoot } from "./root.js";
 export { crc32, readZipDirectory, writeZip, type ZipEntry, type ZipWriteEntry } from "./zip.js";

package/src/module.ts

@@ -4,9 +4,11 @@
  * Scaffold a procedure with: mark procedure new <name> --path packages/archive
  *
  * `archiveModule` has the default limits: 1 GiB of files and 100000 entries in one archive.
- * `createArchiveModule()` gives the same procedures with other limits (roadmap R46).
+ * `createArchiveModule()` gives the same procedures with other limits (roadmap R46), or with a
+ * root that confines each path of the inputs (roadmap R33, `root.ts`).
  */
 
+import { resolve } from "node:path";
 import { z } from "zod";
 import {
   defineModule,
@@ -43,7 +45,7 @@ const ArchiveCreateInputSchema = z.object({
   output: path("The archive to make"),
   source: path("A folder: the archive gets its content").optional(),
   files: z.array(z.string().min(1).max(4096)).min(1).max(10_000).optional().describe("Files and folders, relative to cwd. A folder goes in with its content"),
-  cwd: path("The base folder of files (default: the working folder)").optional(),
+  cwd: path("The base folder of files (default: the working folder, or the root of the module)").optional(),
   format: format.optional().describe("The format (default: from the name of output: .tar.gz, .tgz, .tar or .zip)"),
   overwrite: z.boolean().optional().describe("True: replace an existing archive (default false)"),
 });
@@ -164,28 +166,39 @@ export interface ArchiveModuleOptions {
   readonly maxBytes?: number | undefined;
   /** The most entries of one archive. The default is 100000. */
   readonly maxEntries?: number | undefined;
+  /**
+   * The folder that confines each path of the procedures (roadmap R33), as `createFsModule({ root })`
+   * does. A relative path of an input starts at the root. A path outside the root gives `FORBIDDEN`
+   * with the reason `outside-root`. A relative root starts at the working folder of the process.
+   */
+  readonly root?: string | undefined;
 }
 
 /**
- * This function gives the module of this package with other limits. Without options, it gives
- * `archiveModule`. A host gives it to `createRegistry()` before its bundles, so it replaces the
- * `archiveModule` that a bundle requires (the first module of a name counts).
+ * This function gives the module of this package with other limits, or with a root. Without
+ * options, it gives `archiveModule`. A host gives it to `createRegistry()` before its bundles, so it
+ * replaces the `archiveModule` that a bundle requires (the first module of a name counts).
  */
 export function createArchiveModule(options: ArchiveModuleOptions = {}): ProcedureModule {
   if (Object.values(options).every((value) => value === undefined)) return archiveModule;
-  const settings: ArchiveSettings = {
+  const limits = {
     maxBytes: options.maxBytes ?? DEFAULT_ARCHIVE_SETTINGS.maxBytes,
     maxEntries: options.maxEntries ?? DEFAULT_ARCHIVE_SETTINGS.maxEntries,
   };
-  for (const [name, value] of Object.entries(settings)) {
+  for (const [name, value] of Object.entries(limits)) {
     if (!Number.isSafeInteger(value) || value < 0) throw new TypeError(`createArchiveModule: ${name} must be a whole number of 0 or more`);
   }
+  if (options.root !== undefined && (typeof options.root !== "string" || options.root === "")) {
+    throw new TypeError("createArchiveModule: root must be the path of a folder");
+  }
+  // The root resolves against the working folder of the process now, as the root of @procedures/fs
+  const settings: ArchiveSettings = { ...limits, ...(options.root !== undefined ? { root: resolve(options.root) } : {}) };
   return defineModule("@procedures/archive", archiveProcedures(settings));
 }
 
 /**
  * This function registers the procedures of @procedures/archive in a registry. The default is the
- * global registry. The options are the options of `createArchiveModule()`.
+ * global registry. The options are the options of `createArchiveModule()`, with the root too.
  */
 export function registerArchiveProcedures(registry: ProcedureRegistry = PROCEDURE_REGISTRY, options: ArchiveModuleOptions = {}): void {
   registerModules(registry, [createArchiveModule(options)]);

package/src/procedures/archive/create.ts

@@ -4,36 +4,42 @@
  * Make a tar.gz, tar or zip archive of a folder or of files. The procedure writes a temporary
  * file next to the archive, and renames it at the end: a failed call leaves no part of an
  * archive. The walk does not follow a symbolic link: the archive gets the link.
+ *
+ * With the root of the module, the archive, the source, `cwd` and the folder of each file must be
+ * in the root. A link in the input goes into the archive as a link: the walk does not read its target.
  */
 
 import { randomBytes } from "node:crypto";
 import { mkdir, open, readFile, rename, rm, stat } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
+import { dirname } from "node:path";
 import { ArchiveError } from "../../errors.js";
 import { DEFAULT_ARCHIVE_SETTINGS, formatOfName, type ArchiveSettings } from "../../format.js";
 import { entryParts } from "../../paths.js";
+import { placesOf, type Places } from "../../root.js";
 import { createTar } from "../../tar.js";
-import { folderNames, walk } from "../../walk.js";
+import { folderNames, under, walk } from "../../walk.js";
 import { writeZip, type ZipWriteEntry } from "../../zip.js";
 import type { ArchiveCreateInput, ArchiveCreateOutput } from "../../types.js";
 
 /** The base folder and the names of the input. Exactly one of `source` and `files`. */
-async function inputNames(input: ArchiveCreateInput): Promise<{ base: string; names: string[] }> {
+async function inputNames(input: ArchiveCreateInput, places: Places): Promise<{ base: string; names: string[] }> {
   if ((input.source === undefined) === (input.files === undefined)) {
     throw new ArchiveError("UNSAFE_PATH", "archive.create needs exactly one of source and files");
   }
   if (input.source !== undefined) {
-    const base = resolve(input.source);
+    const base = await places.place(input.source);
     const stats = await stat(base).catch(() => undefined);
     if (!stats?.isDirectory()) throw new ArchiveError("UNSAFE_PATH", `The source ${base} is not a folder`);
     return { base, names: await folderNames(base) };
   }
-  const base = resolve(input.cwd ?? process.cwd());
+  const base = await places.place(input.cwd ?? (places.root === undefined ? process.cwd() : "."));
   const names = (input.files ?? []).map((name) => {
     const parts = entryParts(name);
     if (parts.length === 0) throw new ArchiveError("UNSAFE_PATH", `The file ${JSON.stringify(name)} names the base folder: give source for a whole folder`, name);
     return parts.join("/");
   });
+  // The walk reads through the folders of a name: they must be in the root
+  if (places.root !== undefined) for (const name of names) await places.place(dirname(under(base, name)));
   return { base, names };
 }
 
@@ -41,13 +47,14 @@ async function inputNames(input: ArchiveCreateInput): Promise<{ base: string; na
  * Make a tar.gz or zip archive of a folder or of files
  */
 export async function archiveCreate(input: ArchiveCreateInput, settings: ArchiveSettings = DEFAULT_ARCHIVE_SETTINGS): Promise<ArchiveCreateOutput> {
+  const places = await placesOf(settings.root, ["archive", "create"]);
+  const output = await places.place(input.output);
   const format = formatOfName(input.output, input.format);
-  const output = resolve(input.output);
   const existing = await stat(output).catch(() => undefined);
   if (existing?.isDirectory()) throw new ArchiveError("EXISTS", `${output} is a folder`);
   if (existing !== undefined && input.overwrite !== true) throw new ArchiveError("EXISTS", `${output} exists: give overwrite: true to replace it`);
 
-  const { base, names } = await inputNames(input);
+  const { base, names } = await inputNames(input, places);
   const temporary = `${output}.${randomBytes(6).toString("hex")}.tmp`;
   const entries = await walk(base, names, { ...settings, exclude: new Set([output, temporary]) });
 

package/src/procedures/archive/extract.ts

@@ -7,12 +7,16 @@
  * `overwrite`, or an archive over the limits changes nothing.
  *
  * A damaged entry (its size or its CRC-32) stops the extract, and the files before it stay.
+ *
+ * With the root of the module, the archive and the target must be in the root. The checks of the
+ * entries keep each entry in the target, so the extract stays in the root.
  */
 
 import { lstat, mkdir, realpath, rm, symlink, unlink, utimes } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join } from "node:path";
 import { DEFAULT_ARCHIVE_SETTINGS, formatOfFile, type ArchiveSettings } from "../../format.js";
 import { planExtract, type PlannedEntry, type RawEntry } from "../../paths.js";
+import { isInside, outsideRoot, placesOf } from "../../root.js";
 import { extractTar, readTarEntries } from "../../tar.js";
 import { extractZipFile, readZipDirectory, readZipLink, type ZipEntry } from "../../zip.js";
 import type { ArchiveExtractInput, ArchiveExtractOutput } from "../../types.js";
@@ -72,7 +76,9 @@ function countsOf(planned: readonly PlannedEntry[]): Pick<ArchiveExtractOutput,
  * Extract a tar.gz or zip archive into a folder, with a check of each path
  */
 export async function archiveExtract(input: ArchiveExtractInput, settings: ArchiveSettings = DEFAULT_ARCHIVE_SETTINGS): Promise<ArchiveExtractOutput> {
-  const archive = resolve(input.archive);
+  const places = await placesOf(settings.root, ["archive", "extract"]);
+  const archive = await places.place(input.archive);
+  const folder = await places.place(input.target);
   const format = await formatOfFile(archive, input.format);
   const overwrite = input.overwrite === true;
 
@@ -89,9 +95,12 @@ export async function archiveExtract(input: ArchiveExtractInput, settings: Archi
     raw = (await readTarEntries(archive, settings)).map((entry) => ({ name: entry.name, kind: entry.kind, size: entry.size, linkTarget: entry.linkTarget }));
   }
 
-  const folder = resolve(input.target);
   await mkdir(folder, { recursive: true });
   const target = await realpath(folder);
+  // A link that came after the check of the root does not lead the extract out of it
+  if (places.root !== undefined && !isInside(places.root.real, target)) {
+    throw outsideRoot(["archive", "extract"], `the target ${JSON.stringify(input.target)} leads out of the root ${places.root.folder}`);
+  }
   const planned = planExtract(raw, target, { overwrite, maxBytes: settings.maxBytes, maxEntries: settings.maxEntries });
 
   if (format === "zip") {

package/src/procedures/archive/list.ts

@@ -2,11 +2,12 @@
  * archive.list procedure
  *
  * The entries of a tar.gz, tar or zip archive: the path, the kind, the size, the mode, the time
- * and the target of a link. The list reads the archive and writes nothing.
+ * and the target of a link. The list reads the archive and writes nothing. With the root of the
+ * module, the archive must be in the root.
  */
 
-import { resolve } from "node:path";
 import { DEFAULT_ARCHIVE_SETTINGS, formatOfFile, type ArchiveSettings } from "../../format.js";
+import { placesOf } from "../../root.js";
 import { readTarEntries } from "../../tar.js";
 import { readZipDirectory, readZipLink } from "../../zip.js";
 import type { ArchiveEntry, ArchiveFormat, ArchiveListInput, ArchiveListOutput } from "../../types.js";
@@ -43,7 +44,7 @@ export async function readEntries(path: string, format: ArchiveFormat, settings:
  * The entries of a tar.gz or zip archive
  */
 export async function archiveList(input: ArchiveListInput, settings: ArchiveSettings = DEFAULT_ARCHIVE_SETTINGS): Promise<ArchiveListOutput> {
-  const path = resolve(input.archive);
+  const path = await (await placesOf(settings.root, ["archive", "list"])).place(input.archive);
   const format = await formatOfFile(path, input.format);
   const entries = await readEntries(path, format, { ...settings, maxBytes: Number.MAX_SAFE_INTEGER });
   return { format, entries, bytes: entries.reduce((sum, entry) => sum + (entry.kind === "file" ? entry.size : 0), 0) };

package/src/root.ts

@@ -0,0 +1,149 @@
+/**
+ * The root of the archive procedures: one folder that confines each path (roadmap R33).
+ *
+ * The rules are the rules of `root.ts` of `@procedures/fs` (`createFsModule({ root })`):
+ * - 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
+ *   path that goes up with `..`, an absolute path outside the root, a path on another drive, and
+ *   a symlink or a junction that leads out of the root.
+ * - The check uses the real path (`fs.realpath`) of the path. For a path that does not exist, it
+ *   uses the real path of the nearest existing ancestor. So a symlinked parent folder cannot
+ *   lead a write or a `mkdir` out of the root.
+ *
+ * On Windows, the comparison ignores the case of the letters, and `/` and `\` are the same.
+ */
+
+import { readlink, realpath } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { InvocationError, type ProcedurePath } from "@procedures/client";
+
+/** The reason of the `FORBIDDEN` error for a path outside the root. */
+export const OUTSIDE_ROOT = "outside-root";
+
+/** The maximum number of symlinks that one check follows. After it, the check fails with `ELOOP`. */
+const MAX_LINKS = 40;
+
+/**
+ * This function tells if `path` is `folder` or a path in `folder`. The two paths are absolute.
+ * On Windows, the case of the letters is not significant.
+ */
+export function isInside(folder: string, path: string): boolean {
+  const rel = relative(folder, path);
+  return rel === "" || (!isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep}`));
+}
+
+/** True for the error of a path that does not exist. */
+function isMissing(error: unknown): boolean {
+  const code = (error as NodeJS.ErrnoException).code;
+  return code === "ENOENT" || code === "ENOTDIR";
+}
+
+/** The target of a symlink, or undefined when the path is not a symlink or does not exist. */
+async function linkTarget(path: string): Promise<string | undefined> {
+  try {
+    return await readlink(path);
+  } catch (error) {
+    // EINVAL: the path is not a symlink
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "EINVAL" || isMissing(error)) return undefined;
+    throw error;
+  }
+}
+
+/**
+ * This function gives the real path of an absolute path. For a path that does not exist, it
+ * gives the real path of the nearest existing ancestor and the rest of the path. A symlink whose
+ * target does not exist leads to its target, because a write follows it.
+ */
+export async function realPathOf(path: string, links = 0): Promise<string> {
+  const rest: string[] = [];
+  let current = path;
+  for (;;) {
+    try {
+      return join(await realpath(current), ...rest);
+    } catch (error) {
+      if (!isMissing(error)) throw error;
+    }
+    const target = await linkTarget(current);
+    if (target !== undefined) {
+      if (links >= MAX_LINKS) {
+        const loop = new Error(`Too many symlinks in the path ${path}`) as NodeJS.ErrnoException;
+        loop.code = "ELOOP";
+        throw loop;
+      }
+      return join(await realPathOf(resolve(dirname(current), target), links + 1), ...rest);
+    }
+    const parent = dirname(current);
+    // No ancestor exists, for example a drive that is not there
+    if (parent === current) return join(current, ...rest);
+    rest.unshift(basename(current));
+    current = parent;
+  }
+}
+
+/** A root: the absolute path that the host gave, and its real path. */
+export interface ResolvedRoot {
+  folder: string;
+  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> {
+  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 archive procedures does not exist: ${folder}`) as NodeJS.ErrnoException;
+    missing.code = "ENOENT";
+    throw missing;
+  }
+}
+
+/** The `FORBIDDEN` error for a path outside the root. */
+export function outsideRoot(procedure: ProcedurePath, message: string): InvocationError {
+  return new InvocationError("FORBIDDEN", `${procedure.join(".")}: ${message}`, procedure, OUTSIDE_ROOT);
+}
+
+/** True for the `FORBIDDEN` error of a path outside the root. */
+export function isOutsideRoot(error: unknown): boolean {
+  return error instanceof InvocationError && error.code === "FORBIDDEN" && error.reason === OUTSIDE_ROOT;
+}
+
+/**
+ * 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`.
+ */
+export async function inRoot(root: ResolvedRoot, path: string, procedure: ProcedurePath): Promise<string> {
+  const absolute = resolve(root.folder, 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.
+  if (!isInside(root.folder, absolute) && !isInside(root.real, absolute) && !isInside(root.real, real)) {
+    throw outsideRoot(procedure, `the path ${JSON.stringify(path)} is outside the root ${root.folder}`);
+  }
+  if (!isInside(root.real, real)) {
+    throw outsideRoot(procedure, `the path ${JSON.stringify(path)} leads out of the root ${root.folder} through a symlink`);
+  }
+  return absolute;
+}
+
+/** The paths of one call of a procedure. */
+export interface Places {
+  /** The root of the call, or undefined for a module without a root. */
+  readonly root: ResolvedRoot | undefined;
+  /**
+   * This function gives the absolute path of a path of the input. Without a root, a relative path
+   * starts at the working folder. With a root, it starts at the root, and a path outside it gives
+   * `FORBIDDEN` with the reason `outside-root`.
+   */
+  place(path: string): Promise<string>;
+}
+
+/** This function gives the paths of one call. With a root, the root must exist when the call starts. */
+export async function placesOf(root: string | undefined, procedure: ProcedurePath): Promise<Places> {
+  if (root === undefined) return { root: undefined, place: async (path) => resolve(path) };
+  const resolved = await resolveRoot(root);
+  return { root: resolved, place: (path) => inRoot(resolved, path, procedure) };
+}