@procedures/fs 0.2.3 → 0.4.0

package/src/root.ts

@@ -0,0 +1,139 @@
+/**
+ * The root of the file procedures: one folder that confines each path (roadmap R33).
+ *
+ * `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
+ *   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.
+ * - The procedure gets the absolute path, so the paths of the output are absolute.
+ *
+ * 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 | undefined)?.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 file 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 tells if the real path of an absolute path is in the root. It follows each
+ * symlink of the path, also a symlink whose target does not exist.
+ */
+export async function realPathIsInside(root: ResolvedRoot, absolute: string): Promise<boolean> {
+  return isInside(root.real, await realPathOf(absolute));
+}
+
+/**
+ * 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;
+}

package/src/types.ts

@@ -229,8 +229,12 @@ export const CopyInputSchema: z.ZodObject<{
   dest: z.string().describe("Destination path"),
   /** Copy directories recursively (default: true) */
   recursive: z.boolean().optional().default(true).describe("Copy directories recursively (default: true)"),
-  /** Overwrite existing files (default: false) */
-  overwrite: z.boolean().optional().default(false).describe("Overwrite existing files (default: false)"),
+  /** Replace an existing destination (default: false). Without it, an existing destination is an error. */
+  overwrite: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe("Replace an existing destination (default: false). Without it, an existing destination is an error (EEXIST), and the copy changes nothing."),
 });
 
 export type CopyInput = z.infer<typeof CopyInputSchema>;
@@ -405,3 +409,109 @@ export const ReadJsonOutputSchema: z.ZodType<ReadJsonOutput> = z.looseObject({
   data: z.unknown().describe("The parsed JSON value"),
   stats: StatOutputSchema.describe("The stats of the file"),
 });
+
+
+// =============================================================================
+// fs.write.json, fs.hash, fs.temp and fs.watch (roadmap R44)
+// =============================================================================
+
+export interface FsWriteJsonInput {
+  /** The path of the file */
+  path: string;
+  /** The value to write (required: null writes null) */
+  value: unknown;
+  /** The spaces of the indent (default 2) */
+  indent?: number | undefined;
+}
+
+export interface FsWriteJsonOutput {
+  path: string;
+  bytesWritten: number;
+}
+
+export const FsWriteJsonInputSchema: z.ZodType<FsWriteJsonInput> = z.object({
+  path: z.string().describe("The path of the file"),
+  value: z.unknown().describe("The value to write as JSON"),
+  indent: z.number().int().min(0).max(10).optional().describe("The spaces of the indent (default 2)"),
+});
+
+export const FsWriteJsonOutputSchema: z.ZodType<FsWriteJsonOutput> = z.looseObject({
+  path: z.string().describe("The path of the file"),
+  bytesWritten: z.number().describe("The bytes of the file"),
+});
+
+export type HashAlgorithm = "sha256" | "sha512" | "sha1" | "md5";
+
+export interface FsHashInput {
+  path: string;
+  /** The algorithm (default sha256) */
+  algorithm?: HashAlgorithm | undefined;
+}
+
+export interface FsHashOutput {
+  path: string;
+  algorithm: HashAlgorithm;
+  /** The hash, as hexadecimal text */
+  hash: string;
+  /** The bytes of the file */
+  size: number;
+}
+
+export const FsHashInputSchema: z.ZodType<FsHashInput> = z.object({
+  path: z.string().describe("The path of the file"),
+  algorithm: z.enum(["sha256", "sha512", "sha1", "md5"]).optional().describe("The algorithm (default sha256)"),
+});
+
+export const FsHashOutputSchema: z.ZodType<FsHashOutput> = z.looseObject({
+  path: z.string().describe("The path of the file"),
+  algorithm: z.enum(["sha256", "sha512", "sha1", "md5"]).describe("The algorithm"),
+  hash: z.string().describe("The hash, as hexadecimal text"),
+  size: z.number().describe("The bytes of the file"),
+});
+
+export interface FsTempInput {
+  /** The start of the name of the folder (default "procedures-") */
+  prefix?: string | undefined;
+}
+
+export interface FsTempOutput {
+  /** The path of the new folder */
+  path: string;
+}
+
+export const FsTempInputSchema: z.ZodType<FsTempInput> = z.object({
+  prefix: z
+    .string()
+    .regex(/^[A-Za-z0-9._-]{0,40}$/, "letters, digits, dot, underscore and hyphen only")
+    .optional()
+    .describe('The start of the name of the folder (default "procedures-")'),
+});
+
+export const FsTempOutputSchema: z.ZodType<FsTempOutput> = z.looseObject({
+  path: z.string().describe("The path of the new folder"),
+});
+
+export interface FsWatchInput {
+  /** The file or folder to watch */
+  path: string;
+  /** Also the changes in the subfolders */
+  recursive?: boolean | undefined;
+}
+
+/** One change: an item of the stream of fs.watch. */
+export interface FsWatchOutput {
+  /** "rename" for a file that appears or goes away, "change" for a change of its content */
+  event: "rename" | "change";
+  /** The name of the file, relative to the path, when the platform gives it */
+  filename: string | null;
+}
+
+export const FsWatchInputSchema: z.ZodType<FsWatchInput> = z.object({
+  path: z.string().describe("The file or folder to watch"),
+  recursive: z.boolean().optional().describe("Also the changes in the subfolders"),
+});
+
+export const FsWatchOutputSchema: z.ZodType<FsWatchOutput> = z.looseObject({
+  event: z.enum(["rename", "change"]).describe('"rename" for a file that appears or goes away, "change" for its content'),
+  filename: z.string().nullable().describe("The name of the file, relative to the path, when the platform gives it"),
+});