@hienlh/ppm 0.17.57 → 0.18.0

package/src/services/fs-ops/fs-ops-copy-move.service.ts

@@ -0,0 +1,60 @@
+import { lstat } from "node:fs/promises";
+import {
+  assertAllowed,
+  assertNotPpmSubtreeDeep,
+  assertNotProtected,
+  resolvePath,
+} from "../fs-path-guard.service.ts";
+import { copyEntry, moveEntry } from "./fs-core-ops.ts";
+
+export interface CopyMoveResult {
+  source: string;
+  destination: string;
+  crossDevice?: boolean;
+  /** False when a cross-device move copied the data but could not delete the source. */
+  sourceRemoved?: boolean;
+}
+
+/**
+ * Resolve and whitelist both sides of a two-path operation. Neither side may
+ * touch the PPM directory: reading that subtree is blocked, so copying out of
+ * it would work around the shield, and writing into it could overwrite the
+ * running server's own state. Real paths are checked too, so a symlink cannot
+ * stand in for either end.
+ */
+async function resolvePair(source: string, destination: string): Promise<[string, string]> {
+  const src = resolvePath(source);
+  const dst = resolvePath(destination);
+  assertAllowed(src);
+  assertAllowed(dst);
+  await assertNotPpmSubtreeDeep(src);
+  await assertNotPpmSubtreeDeep(dst);
+  // Fail early with 404 instead of a confusing copy error.
+  await lstat(src);
+  return [src, dst];
+}
+
+/**
+ * Copy a file or directory tree. `destination` is the FULL target path, not a
+ * containing folder: copying `a.txt` onto folder `docs` must be requested as
+ * `docs/a.txt`. An already-occupied destination — including an existing
+ * directory — surfaces as EEXIST so the caller can prompt instead of merging
+ * two trees by accident.
+ */
+export async function copyPath(source: string, destination: string): Promise<CopyMoveResult> {
+  const [src, dst] = await resolvePair(source, destination);
+  await copyEntry(src, dst);
+  return { source: src, destination: dst };
+}
+
+/**
+ * Move a file or directory. `destination` is the FULL target path, same
+ * contract as `copyPath`. The source is a protected-root candidate because
+ * moving `$HOME` or a drive root away is as destructive as deleting it.
+ */
+export async function movePath(source: string, destination: string): Promise<CopyMoveResult> {
+  const [src, dst] = await resolvePair(source, destination);
+  await assertNotProtected(src);
+  const { crossDevice, sourceRemoved } = await moveEntry(src, dst);
+  return { source: src, destination: dst, crossDevice, sourceRemoved };
+}

package/src/services/fs-ops/fs-ops-mutate.service.ts

@@ -0,0 +1,59 @@
+import { lstat, mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import {
+  assertAllowed,
+  assertNotPpmSubtreeDeep,
+  assertNotProtected,
+  resolvePath,
+} from "../fs-path-guard.service.ts";
+import { removeEntry, renameEntry } from "./fs-core-ops.ts";
+
+/** Rename in place: the new name is joined onto the source's own directory. */
+export async function renamePath(path: string, newName: string): Promise<{ from: string; to: string }> {
+  if (!newName || /[\\/]/.test(newName)) {
+    throw Object.assign(new Error("newName must be a bare file name"), { status: 400, code: "EINVAL" });
+  }
+  const src = resolvePath(path);
+  assertAllowed(src);
+  // Renaming inside the PPM directory would break the running server's own state.
+  await assertNotPpmSubtreeDeep(src);
+  await assertNotProtected(src);
+  await lstat(src);
+  const dst = join(dirname(src), newName);
+  assertAllowed(dst);
+  await assertNotPpmSubtreeDeep(dst);
+  await renameEntry(src, dst);
+  return { from: src, to: dst };
+}
+
+/** Permanent delete of a file, directory tree or symlink (link only). */
+export async function deletePath(path: string): Promise<{ removed: string }> {
+  const target = resolvePath(path);
+  assertAllowed(target);
+  // Deleting inside the PPM directory would destroy the config database, the
+  // auth token and the stored provider credentials.
+  await assertNotPpmSubtreeDeep(target);
+  await assertNotProtected(target);
+  await lstat(target);
+  await removeEntry(target);
+  return { removed: target };
+}
+
+/** Create an empty file; refuses to clobber an existing entry. */
+export async function touchFile(path: string): Promise<{ path: string }> {
+  const target = resolvePath(path);
+  assertAllowed(target);
+  await assertNotPpmSubtreeDeep(target);
+  // `wx` makes the create-or-fail decision atomic at the syscall level.
+  await writeFile(target, "", { flag: "wx" });
+  return { path: target };
+}
+
+/** Create a directory; `recursive:false` keeps EEXIST visible to the client. */
+export async function makeDir(path: string): Promise<{ path: string }> {
+  const target = resolvePath(path);
+  assertAllowed(target);
+  await assertNotPpmSubtreeDeep(target);
+  await mkdir(target, { recursive: false });
+  return { path: target };
+}

package/src/services/fs-ops/fs-ops-read-write.service.ts

@@ -0,0 +1,70 @@
+import { readFileSync, statSync } from "node:fs";
+import { readFile, stat, writeFile } from "node:fs/promises";
+import {
+  assertAllowed,
+  assertNotPpmDir,
+  realPathOrSelf,
+  realPathOrSelfSync,
+  resolvePath,
+} from "../fs-path-guard.service.ts";
+
+// Re-exported because the raw/docx routes resolve a path before serving it.
+export { realPathOrSelf };
+
+/** Refuse to page a huge file into memory as a string. */
+const READ_MAX_SIZE = 5 * 1024 * 1024;
+
+export interface SystemFileContent {
+  content: string;
+  path: string;
+}
+
+/**
+ * Whitelist and PPM-dir shield, applied to the requested path *and* to the
+ * path it really resolves to — otherwise a symlink parked in a public
+ * directory would hand out the credentials database.
+ */
+export function assertReadPermitted(resolved: string, real: string): void {
+  assertAllowed(resolved);
+  assertNotPpmDir(resolved);
+  assertAllowed(real);
+  assertNotPpmDir(real);
+}
+
+/** Type and size gate shared by both readers. */
+function assertReadable(isFile: boolean, size: number): void {
+  if (!isFile) {
+    throw Object.assign(new Error("Not a file"), { status: 400, code: "EISDIR" });
+  }
+  if (size > READ_MAX_SIZE) {
+    throw Object.assign(new Error("File too large (>5MB)"), { status: 400, code: "EFBIG" });
+  }
+}
+
+/** Read a file outside project scope without blocking the event loop. */
+export async function readSystemFile(filePath: string): Promise<SystemFileContent> {
+  const resolved = resolvePath(filePath);
+  assertReadPermitted(resolved, await realPathOrSelf(resolved));
+  const st = await stat(resolved);
+  assertReadable(st.isFile(), st.size);
+  return { content: await readFile(resolved, "utf-8"), path: resolved };
+}
+
+/**
+ * Blocking variant kept for the project-scoped diff route, which composes its
+ * result synchronously. New callers should use the async version.
+ */
+export function readSystemFileSync(filePath: string): SystemFileContent {
+  const resolved = resolvePath(filePath);
+  assertReadPermitted(resolved, realPathOrSelfSync(resolved));
+  const st = statSync(resolved);
+  assertReadable(st.isFile(), st.size);
+  return { content: readFileSync(resolved, "utf-8"), path: resolved };
+}
+
+/** Write a file outside project scope. */
+export async function writeSystemFile(filePath: string, content: string): Promise<void> {
+  const resolved = resolvePath(filePath);
+  assertReadPermitted(resolved, await realPathOrSelf(resolved));
+  await writeFile(resolved, content, "utf-8");
+}

package/src/services/fs-ops/fs-ops-stat.service.ts

@@ -0,0 +1,109 @@
+import { constants } from "node:fs";
+import { access, lstat, opendir, readlink } from "node:fs/promises";
+import { basename } from "node:path";
+import {
+  assertAllowed,
+  assertNotPpmSubtreeDeep,
+  resolvePath,
+} from "../fs-path-guard.service.ts";
+import { isHiddenName } from "./fs-hidden-names.ts";
+
+export type EntryKind = "file" | "directory" | "symlink" | "unknown";
+
+export interface StatResult {
+  path: string;
+  name: string;
+  kind: EntryKind;
+  size: number;
+  mtime: string;
+  ctime: string;
+  birthtime: string;
+  mode: number;
+  readonly: boolean;
+  isHidden: boolean;
+  /** Symlink destination, unresolved — links are never auto-followed. */
+  target?: string;
+  /** Number of direct children for directories, capped. */
+  childCount?: number;
+  /** True when `childCount` hit the cap and is therefore a lower bound. */
+  truncated?: boolean;
+}
+
+/** Counting children of a huge directory must not turn into an endless scan. */
+const CHILD_COUNT_CAP = 10_000;
+
+export function kindOfStats(st: { isSymbolicLink(): boolean; isDirectory(): boolean; isFile(): boolean }): EntryKind {
+  if (st.isSymbolicLink()) return "symlink";
+  if (st.isDirectory()) return "directory";
+  if (st.isFile()) return "file";
+  return "unknown";
+}
+
+/** Write permission is not encoded in the mode bits on Windows, so probe it. */
+async function isReadOnly(path: string, mode: number): Promise<boolean> {
+  if (process.platform !== "win32") return (mode & 0o200) === 0;
+  try {
+    await access(path, constants.W_OK);
+    return false;
+  } catch {
+    return true;
+  }
+}
+
+async function countChildren(path: string): Promise<{ childCount: number; truncated: boolean }> {
+  let childCount = 0;
+  const dir = await opendir(path);
+  try {
+    for await (const _entry of dir) {
+      childCount++;
+      if (childCount >= CHILD_COUNT_CAP) return { childCount, truncated: true };
+    }
+  } finally {
+    // The async iterator already closes the handle when it drains, and a
+    // second close reports differently per runtime — ignore whatever it says.
+    try {
+      await dir.close();
+    } catch {
+      /* already closed */
+    }
+  }
+  return { childCount, truncated: false };
+}
+
+/** Describe a single entry. Reports the link itself, never its target. */
+export async function statPath(input: string): Promise<StatResult> {
+  const path = resolvePath(input);
+  assertAllowed(path);
+  // Sizes and timestamps of the credentials store are metadata the explorer
+  // has no business exposing; `browse` still lists the names.
+  await assertNotPpmSubtreeDeep(path);
+
+  const st = await lstat(path);
+  const kind = kindOfStats(st);
+  const result: StatResult = {
+    path,
+    name: basename(path) || path,
+    kind,
+    size: st.size,
+    mtime: st.mtime.toISOString(),
+    ctime: st.ctime.toISOString(),
+    birthtime: st.birthtime.toISOString(),
+    mode: st.mode,
+    readonly: await isReadOnly(path, st.mode),
+    isHidden: isHiddenName(basename(path)),
+  };
+
+  if (kind === "symlink") {
+    result.target = await readlink(path).catch(() => undefined);
+  }
+  if (kind === "directory") {
+    try {
+      const counted = await countChildren(path);
+      result.childCount = counted.childCount;
+      if (counted.truncated) result.truncated = true;
+    } catch {
+      // Unreadable directory — size info stays absent rather than failing stat.
+    }
+  }
+  return result;
+}

package/src/services/fs-ops/fs-ops-trash.service.ts

@@ -0,0 +1,111 @@
+import { lstat, stat } from "node:fs/promises";
+import {
+  assertAllowed,
+  assertNotPpmSubtreeDeep,
+  assertNotProtected,
+  resolvePath,
+} from "../fs-path-guard.service.ts";
+
+/**
+ * Move an entry to the OS trash. Every backend is an external program
+ * (PowerShell / Finder / gio), so failure is expected on headless or locked
+ * down machines: it surfaces as NO_TRASH and the client then asks whether to
+ * delete permanently. Falling back to `rm` silently would turn an undoable
+ * action into an irreversible one.
+ */
+
+export type TrashRunner = (cmd: string[]) => Promise<{ exitCode: number; stderr: string }>;
+
+const TRASH_TIMEOUT_MS = 10_000;
+
+function noTrash(reason: string): Error {
+  return Object.assign(new Error(`No OS trash backend available: ${reason}`), {
+    status: 409,
+    code: "NO_TRASH",
+  });
+}
+
+/** Default runner — argv array only, never an interpolated shell string. */
+const spawnRunner: TrashRunner = async (cmd) => {
+  const proc = Bun.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
+  const timer = setTimeout(() => proc.kill(), TRASH_TIMEOUT_MS);
+  try {
+    const [exitCode, stderr] = await Promise.all([proc.exited, new Response(proc.stderr).text()]);
+    return { exitCode, stderr };
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+/** Single-quoted PowerShell literal — the only escape inside is a doubled quote. */
+function psLiteral(value: string): string {
+  return `'${value.replace(/'/g, "''")}'`;
+}
+
+/** AppleScript string literal. */
+function osaLiteral(value: string): string {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+function windowsCommand(path: string, isDirectory: boolean): string[] {
+  const method = isDirectory ? "DeleteDirectory" : "DeleteFile";
+  const script =
+    "Add-Type -AssemblyName Microsoft.VisualBasic; " +
+    `[Microsoft.VisualBasic.FileIO.FileSystem]::${method}(${psLiteral(path)},'OnlyErrorDialogs','SendToRecycleBin')`;
+  const shell = Bun.which("powershell") ?? Bun.which("pwsh");
+  if (!shell) throw noTrash("powershell not found on PATH");
+  return [shell, "-NoProfile", "-NonInteractive", "-Command", script];
+}
+
+/** Paths are always absolute here, so no leading-dash option confusion. */
+function posixCommand(path: string): string[] {
+  if (process.platform === "darwin") {
+    const trash = Bun.which("trash");
+    if (trash) return [trash, path];
+    const osascript = Bun.which("osascript");
+    if (!osascript) throw noTrash("neither trash nor osascript found on PATH");
+    return [osascript, "-e", `tell application "Finder" to delete POSIX file ${osaLiteral(path)}`];
+  }
+  const gio = Bun.which("gio");
+  if (gio) return [gio, "trash", path];
+  const trashPut = Bun.which("trash-put");
+  if (trashPut) return [trashPut, path];
+  throw noTrash("neither gio nor trash-put found on PATH");
+}
+
+/** True when the entry should be handed to the directory-flavoured backend. */
+async function isDirectoryTarget(path: string): Promise<boolean> {
+  const link = await lstat(path);
+  if (!link.isSymbolicLink()) return link.isDirectory();
+  // A link is deleted as a link; the target's type only picks the API flavour.
+  return stat(path)
+    .then((s) => s.isDirectory())
+    .catch(() => false);
+}
+
+export async function trashPath(
+  path: string,
+  options?: { run?: TrashRunner },
+): Promise<{ trashed: true; path: string }> {
+  const target = resolvePath(path);
+  assertAllowed(target);
+  // Same shield as the permanent delete: the Recycle Bin is still a removal.
+  await assertNotPpmSubtreeDeep(target);
+  await assertNotProtected(target);
+  const isDir = await isDirectoryTarget(target);
+
+  const cmd =
+    process.platform === "win32" ? windowsCommand(target, isDir) : posixCommand(target);
+
+  const run = options?.run ?? spawnRunner;
+  let result: { exitCode: number; stderr: string };
+  try {
+    result = await run(cmd);
+  } catch (e) {
+    throw noTrash((e as Error).message);
+  }
+  if (result.exitCode !== 0) {
+    throw noTrash(result.stderr.trim() || `exit code ${result.exitCode}`);
+  }
+  return { trashed: true, path: target };
+}

package/src/services/fs-ops/fs-real-path.ts

@@ -0,0 +1,44 @@
+import { realpathSync } from "node:fs";
+import { realpath } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+
+/**
+ * Resolve a path through symlinks. A path that does not exist yet is resolved
+ * through its deepest existing ancestor, which is what makes a symlinked
+ * parent directory visible to the guards: without it, creating a *new* file
+ * behind such a link would slip past a check on the literal path.
+ *
+ * Imports nothing from the guard, so the guard can build on it freely.
+ */
+export async function realPathOrSelf(target: string): Promise<string> {
+  let current = target;
+  const tail: string[] = [];
+  for (;;) {
+    try {
+      const real = await realpath(current);
+      return tail.length ? join(real, ...tail) : real;
+    } catch {
+      const parent = dirname(current);
+      if (parent === current) return target;
+      tail.unshift(basename(current));
+      current = parent;
+    }
+  }
+}
+
+/** Blocking twin, for the synchronous read path. */
+export function realPathOrSelfSync(target: string): string {
+  let current = target;
+  const tail: string[] = [];
+  for (;;) {
+    try {
+      const real = realpathSync(current);
+      return tail.length ? join(real, ...tail) : real;
+    } catch {
+      const parent = dirname(current);
+      if (parent === current) return target;
+      tail.unshift(basename(current));
+      current = parent;
+    }
+  }
+}

package/src/services/fs-ops/sql-row-reader.ts

@@ -0,0 +1,26 @@
+/** The row-producing half of a bun:sqlite statement. */
+interface RowSource {
+  all(): unknown[];
+  iterate(): Iterable<unknown>;
+}
+
+/**
+ * Read a result set, optionally stopping at `maxRows`. A database opened
+ * through the filesystem door can be arbitrarily large and is not the user's
+ * own project data, so those results are capped rather than pulled into
+ * memory in full; the project-scoped door keeps reading everything.
+ */
+export function readRows(
+  stmt: RowSource,
+  maxRows?: number,
+): { rows: Record<string, unknown>[]; truncated: boolean } {
+  if (maxRows === undefined) {
+    return { rows: stmt.all() as Record<string, unknown>[], truncated: false };
+  }
+  const rows: Record<string, unknown>[] = [];
+  for (const row of stmt.iterate()) {
+    if (rows.length >= maxRows) return { rows, truncated: true };
+    rows.push(row as Record<string, unknown>);
+  }
+  return { rows, truncated: false };
+}

package/src/services/fs-ops/sql-statement-guard.ts

@@ -0,0 +1,63 @@
+/**
+ * ATTACH is a file-open primitive dressed as SQL: `ATTACH DATABASE '<path>' AS
+ * p` binds any file on disk to the open connection (and creates it when
+ * missing), and because connections are cached the attached schema survives
+ * into later requests. Every path guard on the viewer routes is meaningless
+ * while a statement can open a second database, so the arbitrary-SQL door
+ * rejects ATTACH and DETACH outright.
+ */
+
+const ATTACH_KEYWORDS = /\b(?:ATTACH|DETACH)\b/i;
+
+/**
+ * Strip comments and string/identifier literals so the keyword scan cannot be
+ * fooled by `SELECT 'attach'` and cannot miss `/*x* / ATTACH`. Literals are
+ * replaced with a space to keep neighbouring tokens apart.
+ */
+export function stripSqlNoise(sql: string): string {
+  let out = "";
+  let i = 0;
+  while (i < sql.length) {
+    const c = sql[i]!;
+    const next = sql[i + 1];
+    if (c === "-" && next === "-") {
+      const end = sql.indexOf("\n", i);
+      i = end === -1 ? sql.length : end;
+    } else if (c === "/" && next === "*") {
+      const end = sql.indexOf("*/", i + 2);
+      i = end === -1 ? sql.length : end + 2;
+      out += " ";
+    } else if (c === "'" || c === '"' || c === "`" || c === "[") {
+      const closer = c === "[" ? "]" : c;
+      i++;
+      while (i < sql.length) {
+        if (sql[i] === closer) {
+          // A doubled quote is an escaped quote, not the end of the literal.
+          if (sql[i + 1] === closer && closer !== "]") i += 2;
+          else break;
+        } else i++;
+      }
+      i++;
+      out += " ";
+    } else {
+      out += c;
+      i++;
+    }
+  }
+  return out;
+}
+
+/** True when the statement text contains an ATTACH/DETACH keyword. */
+export function hasAttachStatement(sql: string): boolean {
+  return ATTACH_KEYWORDS.test(stripSqlNoise(sql));
+}
+
+/** Reject ATTACH/DETACH before the statement reaches the database. */
+export function assertNoAttachStatement(sql: string): void {
+  if (hasAttachStatement(sql)) {
+    throw Object.assign(new Error("ATTACH and DETACH are not allowed"), {
+      status: 400,
+      code: "EINVAL",
+    });
+  }
+}