mulmoclaude 2.8.0 → 2.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mulmoclaude",
-  "version": "2.8.0",
+  "version": "2.8.1",
   "description": "MulmoClaude — GUI-chat with Claude Code + long-term memory. One command to start.",
   "type": "module",
   "bin": {

package/server/api/routes/plugins.ts

@@ -30,7 +30,6 @@ import { log } from "../../system/logger/index.js";
 import { previewSnippet } from "../../utils/logPreview.js";
 import { publishFileChange } from "../../events/file-change.js";
 import { makeArtifactsFileOps } from "../../plugins/runtime.js";
-import { makeConfinedArtifactsFileOps } from "../../plugins/confined-file-ops.js";
 import { isAblated } from "../../system/env.js";
 import { executeKenteiScript } from "../../plugins/kentei-builtin.js";
 import { META as KENTEI_META } from "../../../src/plugins/manageKenteiScript/meta.js";
@@ -260,7 +259,7 @@ bindRoute(
   router,
   API_ROUTES.spreadsheet.create,
   wrapPluginExecute<SpreadsheetArgs, unknown>((req) => {
-    const context: ToolContext & { files: { artifacts: FileOps } } = { files: { artifacts: makeConfinedArtifactsFileOps() } };
+    const context: ToolContext & { files: { artifacts: FileOps } } = { files: { artifacts: makeArtifactsFileOps() } };
     return executeSpreadsheet(context, req.body);
   }),
 );

package/server/plugins/confined-file-ops.ts

@@ -1,22 +1,84 @@
-// FileOps that refuse a path whose real location (symlinks followed) leaves the scope root.
-// `makeArtifactsFileOps` folds `..` lexically only, so a symlink inside the root still reaches out.
+// Scoped FileOps: a lexical check on the plugin-supplied path, then a realpath check so a
+// symlink inside the scope root cannot lead out of it. Check-then-use, like `resolveWithinRoot`: not atomic
+// against a path swapped between the check and the call (Node fs has no openat / no-follow-parent).
 
 import path from "node:path";
 import { mkdir, readFile, readdir, realpath, stat as fsStat, unlink as fsUnlink } from "node:fs/promises";
 import type { FileOps } from "gui-chat-protocol";
 import { writeFileAtomic } from "../utils/files/atomic.js";
-import { resolveWithinRoot, resolveWriteWithinRoot } from "../utils/files/safe.js";
-import { workspacePath } from "../workspace/paths.js";
+import { isEnoent, resolveWriteWithinRoot } from "../utils/files/safe.js";
+import { ensureInsideBase } from "./runtime-loader.js";
+
+// ─────────────────────────────────────────────────────────────────────
+// Path normalisation contract (see plans/done/feat-plugin-runtime-extensions-1110.md)
+//
+//   1. Replace `\` with `/` (Windows path.join leak repair).
+//   2. `path.posix.normalize` (folds `..`, `.`, `//`).
+//   3. Reject if the normalised form starts with `..` or `/`
+//      (would escape the scope root or be absolute).
+//   4. `path.join(scopeRoot, ...segments)` — platform-aware join so
+//      the returned absolute path uses the host OS separator
+//      (backslashes on Windows, forward slashes on POSIX). Critical
+//      for `ensureInsideBase` to accept the result.
+//
+// Plugin authors should never need `node:path`; the platform meets
+// them where they are even if they mis-import it on Windows.
+// ─────────────────────────────────────────────────────────────────────
+
+/** Resolve a plugin-supplied path to an absolute path inside the
+ *  plugin's scope root. Throws on traversal. Lexical only — symlinks
+ *  are checked by the FileOps below. Exported for tests. */
+export function normalizePluginPath(scopeRoot: string, rel: string): string {
+  const slashed = rel.replace(/\\/g, "/");
+  const normalised = path.posix.normalize(slashed);
+  // `path.posix.normalize` produces `..` alone if the input is `..` itself, hence the equality branch.
+  if (normalised === ".." || normalised.startsWith("../") || normalised.startsWith("/")) {
+    throw new Error(`path escapes plugin scope: ${rel}`);
+  }
+  const segments = normalised === "." ? [] : normalised.split("/");
+  const absolute = path.join(scopeRoot, ...segments);
+  // Defence in depth so a future change to the lexical step cannot silently regress.
+  if (!ensureInsideBase(absolute, scopeRoot)) {
+    throw new Error(`path escapes plugin scope: ${rel}`);
+  }
+  return absolute;
+}
+
+/** The lexically checked path, relative to the scope root in host-native form ("" for the root). */
+const scopeRelative = (scopeRoot: string, rel: string): string => path.relative(scopeRoot, normalizePluginPath(scopeRoot, rel));
 
 /** An escape reads as a missing file, so callers that treat ENOENT as "not there" stay closed. */
 const notInScope = (rel: string): Error & { code: string } => Object.assign(new Error(`not inside the scope: ${rel}`), { code: "ENOENT" });
 
+/** Only a missing path reads as null; EACCES, ELOOP, ENOTDIR … propagate as before. */
+const realpathIfPresent = async (absPath: string): Promise<string | null> => {
+  try {
+    return await realpath(absPath);
+  } catch (err) {
+    if (isEnoent(err)) return null;
+    throw err;
+  }
+};
+
+const isWithin = (rootReal: string, candidateReal: string): boolean => candidateReal === rootReal || candidateReal.startsWith(rootReal + path.sep);
+
+/** Real location of `relative` (host-native, from `scopeRelative`) if it exists inside the root; null when missing or outside. */
+const resolveExisting = async (rootReal: string, relative: string): Promise<string | null> => {
+  const candidateReal = await realpathIfPresent(path.resolve(rootReal, relative));
+  return candidateReal !== null && isWithin(rootReal, candidateReal) ? candidateReal : null;
+};
+
+// Only a write creates the scope root; a read-only call against an absent root sees "missing".
 const realRoot = async (scopeRoot: string): Promise<string> => {
   await mkdir(scopeRoot, { recursive: true });
   return realpath(scopeRoot);
 };
 
-const existingPath = async (scopeRoot: string, rel: string): Promise<string | null> => resolveWithinRoot(await realRoot(scopeRoot), rel);
+const existingPath = async (scopeRoot: string, rel: string): Promise<string | null> => {
+  const relative = scopeRelative(scopeRoot, rel);
+  const rootReal = await realpathIfPresent(scopeRoot);
+  return rootReal === null ? null : resolveExisting(rootReal, relative);
+};
 
 const requireExisting = async (scopeRoot: string, rel: string): Promise<string> => {
   const resolved = await existingPath(scopeRoot, rel);
@@ -24,6 +86,31 @@ const requireExisting = async (scopeRoot: string, rel: string): Promise<string>
   return resolved;
 };
 
+const writeTarget = async (scopeRoot: string, rel: string): Promise<string> => {
+  const target = await resolveWriteWithinRoot(await realRoot(scopeRoot), scopeRelative(scopeRoot, rel));
+  if (target === null) throw new Error(`refusing to write outside the scope: ${rel}`);
+  return target;
+};
+
+// unlink does not follow the leaf, so only the parent is confined: a link is removed, never its target.
+const unlinkTarget = async (scopeRoot: string, rel: string): Promise<string | null> => {
+  const relative = scopeRelative(scopeRoot, rel);
+  const rootReal = await realpathIfPresent(scopeRoot);
+  if (rootReal === null) return null;
+  if (relative === "") return rootReal;
+  const parentReal = await resolveExisting(rootReal, path.dirname(relative));
+  return parentReal === null ? null : path.join(parentReal, path.basename(relative));
+};
+
+const ignoreEnoent = async <T>(operation: () => Promise<T>, fallback: T): Promise<T> => {
+  try {
+    return await operation();
+  } catch (err) {
+    if (isEnoent(err)) return fallback;
+    throw err;
+  }
+};
+
 export function makeConfinedFileOps(scopeRoot: string): FileOps {
   return {
     read: async (rel) => readFile(await requireExisting(scopeRoot, rel), "utf-8"),
@@ -31,14 +118,10 @@ export function makeConfinedFileOps(scopeRoot: string): FileOps {
       const buf = await readFile(await requireExisting(scopeRoot, rel));
       return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
     },
-    write: async (rel, content) => {
-      const target = await resolveWriteWithinRoot(await realRoot(scopeRoot), rel);
-      if (target === null) throw new Error(`refusing to write outside the scope: ${rel}`);
-      await writeFileAtomic(target, content);
-    },
+    write: async (rel, content) => writeFileAtomic(await writeTarget(scopeRoot, rel), content),
     readDir: async (rel) => {
       const resolved = await existingPath(scopeRoot, rel);
-      return resolved === null ? [] : readdir(resolved);
+      return resolved === null ? [] : ignoreEnoent(() => readdir(resolved), []);
     },
     stat: async (rel) => {
       const { mtimeMs, size } = await fsStat(await requireExisting(scopeRoot, rel));
@@ -46,11 +129,8 @@ export function makeConfinedFileOps(scopeRoot: string): FileOps {
     },
     exists: async (rel) => (await existingPath(scopeRoot, rel)) !== null,
     unlink: async (rel) => {
-      const resolved = await existingPath(scopeRoot, rel);
-      if (resolved !== null) await fsUnlink(resolved);
+      const target = await unlinkTarget(scopeRoot, rel);
+      if (target !== null) await ignoreEnoent(() => fsUnlink(target), undefined);
     },
   };
 }
-
-/** The workspace `artifacts/` dir, confined as above. */
-export const makeConfinedArtifactsFileOps = (): FileOps => makeConfinedFileOps(path.join(workspacePath, "artifacts"));

package/server/plugins/runtime.ts

@@ -3,25 +3,23 @@
 //
 // Every helper closes over `pkgName` so a plugin's pubsub channel,
 // data dir, log prefix etc. cannot leak across plugins. Path arguments
-// to `files.{data,config}` are normalised to POSIX, then anchored
-// inside the plugin's scope root via `ensureInsideBase` — so misuse of
-// `node:path` on Windows still works and `"../../etc/passwd"` is
-// rejected.
+// to `files.{data,config,artifacts}` are confined to their scope root
+// by `makeConfinedFileOps` — lexically, then by realpath, so neither
+// `"../../etc/passwd"` nor a symlink inside the root leads out.
 //
 // This module is server-side only. The browser-side counterpart lives
 // at `src/utils/plugin/runtime.ts`.
 
 import path from "node:path";
-import { readFile, readdir, stat as fsStat, unlink as fsUnlink } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import type { FileOps, PluginFetchJsonOptions, PluginFetchOptions, PluginRuntime } from "gui-chat-protocol";
 
 import { WORKSPACE_PATHS, workspacePath } from "../workspace/paths.js";
 import { writeFileAtomic } from "../utils/files/atomic.js";
 import { errorMessage } from "../utils/errors.js";
-import { isErrorWithCode, isRecord } from "../utils/types.js";
+import { isRecord } from "../utils/types.js";
 import { log as hostLog, type Logger } from "../system/logger/index.js";
-import { ensureInsideBase } from "./runtime-loader.js";
+import { makeConfinedFileOps } from "./confined-file-ops.js";
 import { ONE_SECOND_MS } from "../utils/time.js";
 import type { IPubSub } from "../events/pub-sub/index.js";
 import * as notifierEngine from "../notifier/engine.js";
@@ -35,59 +33,6 @@ import { BUILTIN_ROLE_IDS } from "../../src/config/roles.js";
 
 const DEFAULT_FETCH_TIMEOUT_MS = 10 * ONE_SECOND_MS;
 
-// ─────────────────────────────────────────────────────────────────────
-// Path normalisation contract (see plans/done/feat-plugin-runtime-extensions-1110.md)
-//
-//   1. Replace `\` with `/` (Windows path.join leak repair).
-//   2. `path.posix.normalize` (folds `..`, `.`, `//`).
-//   3. Reject if the normalised form starts with `..` or `/`
-//      (would escape the scope root or be absolute).
-//   4. `path.join(scopeRoot, ...segments)` — platform-aware join so
-//      the returned absolute path uses the host OS separator
-//      (backslashes on Windows, forward slashes on POSIX). Critical
-//      for `ensureInsideBase` to accept the result.
-//
-// Plugin authors should never need `node:path`; the platform meets
-// them where they are even if they mis-import it on Windows.
-// ─────────────────────────────────────────────────────────────────────
-
-/** Resolve a plugin-supplied path to an absolute path inside the
- *  plugin's scope root. Throws on traversal. Exported for tests.
- *
- *  Cross-platform: `scopeRoot` is the host OS's native form (drive
- *  letter + backslashes on Windows, forward slashes on POSIX). The
- *  user-supplied `rel` is POSIX-relative by contract; we sanitise
- *  for the lexical traversal check via `path.posix.*`, then join
- *  with `path.join` so the returned absolute path is in the host's
- *  native form (which `ensureInsideBase` requires). */
-export function normalizePluginPath(scopeRoot: string, rel: string): string {
-  // Defang Windows path.join output and any mixed-separator inputs.
-  const slashed = rel.replace(/\\/g, "/");
-  // Fold `..` / `.` / repeated `/` lexically (no fs touch yet).
-  const normalised = path.posix.normalize(slashed);
-  // Reject lexically — anything that escapes the scope root after
-  // normalisation either starts with `..` (parent-traversal) or is
-  // absolute (`/etc/passwd`). `path.posix.normalize` produces `..`
-  // alone if the input is `..` itself, hence the equality branch.
-  if (normalised === ".." || normalised.startsWith("../") || normalised.startsWith("/")) {
-    throw new Error(`path escapes plugin scope: ${rel}`);
-  }
-  const segments = normalised === "." ? [] : normalised.split("/");
-  // `path.join` (platform-aware) so the result uses the host
-  // separator. On Windows that's backslashes; on POSIX, forward
-  // slashes — matching `scopeRoot`'s existing form so
-  // `ensureInsideBase`'s `path.resolve` + `path.sep` comparison
-  // works across both platforms.
-  const absolute = path.join(scopeRoot, ...segments);
-  // Defence in depth: even though the lexical check above should
-  // catch every escape, run `ensureInsideBase` so a future change to
-  // either step doesn't silently regress the safety guarantee.
-  if (!ensureInsideBase(absolute, scopeRoot)) {
-    throw new Error(`path escapes plugin scope: ${rel}`);
-  }
-  return absolute;
-}
-
 // ─────────────────────────────────────────────────────────────────────
 // Scoped FileOps factory
 // ─────────────────────────────────────────────────────────────────────
@@ -99,59 +44,7 @@ export function normalizePluginPath(scopeRoot: string, rel: string): string {
  *  category subdir (`charts/`, …) and all write logic; the host only
  *  provides this generic primitive. */
 export function makeArtifactsFileOps(): FileOps {
-  return makeFileOps(path.join(workspacePath, "artifacts"));
-}
-
-function makeFileOps(scopeRoot: string): FileOps {
-  // The scope root may not exist on first use. Lazy-create at write
-  // time (writeFileAtomic does its own mkdir for the file's parent;
-  // we ensure the scope root exists for readDir() / stat() etc.).
-  // Reads against a never-written plugin throw ENOENT — exposed as
-  // `exists() === false` rather than handled here.
-
-  return {
-    async read(rel) {
-      return readFile(normalizePluginPath(scopeRoot, rel), "utf-8");
-    },
-    async readBytes(rel) {
-      const buf = await readFile(normalizePluginPath(scopeRoot, rel));
-      return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
-    },
-    async write(rel, content) {
-      const abs = normalizePluginPath(scopeRoot, rel);
-      await writeFileAtomic(abs, content);
-    },
-    async readDir(rel) {
-      const abs = normalizePluginPath(scopeRoot, rel);
-      try {
-        return await readdir(abs);
-      } catch (err) {
-        if (isErrorWithCode(err) && err.code === "ENOENT") return [];
-        throw err;
-      }
-    },
-    async stat(rel) {
-      const { mtimeMs, size } = await fsStat(normalizePluginPath(scopeRoot, rel));
-      return { mtimeMs, size };
-    },
-    async exists(rel) {
-      try {
-        await fsStat(normalizePluginPath(scopeRoot, rel));
-        return true;
-      } catch (err) {
-        if (isErrorWithCode(err) && err.code === "ENOENT") return false;
-        throw err;
-      }
-    },
-    async unlink(rel) {
-      try {
-        await fsUnlink(normalizePluginPath(scopeRoot, rel));
-      } catch (err) {
-        if (isErrorWithCode(err) && err.code === "ENOENT") return;
-        throw err;
-      }
-    },
-  };
+  return makeConfinedFileOps(path.join(workspacePath, "artifacts"));
 }
 
 // ─────────────────────────────────────────────────────────────────────
@@ -395,8 +288,8 @@ export function makePluginRuntime(deps: MakePluginRuntimeDeps): MulmoclaudeRunti
     pubsub: makeScopedPubSub(pkgName, pubsub),
     locale,
     files: {
-      data: makeFileOps(dataRoot),
-      config: makeFileOps(configRoot),
+      data: makeConfinedFileOps(dataRoot),
+      config: makeConfinedFileOps(configRoot),
       artifacts: makeArtifactsFileOps(),
     },
     log: makeScopedLogger(pkgName),

package/server/plugins/spreadsheet-builtin.ts

@@ -6,7 +6,7 @@
 // after a save that wrote the file. Imported for side effect at boot (server/index.ts).
 
 import { executeSpreadsheetDispatch, isSpreadsheetDispatchArgs } from "@gui-chat-plugin/spreadsheet";
-import { makeConfinedArtifactsFileOps } from "./confined-file-ops.js";
+import { makeArtifactsFileOps } from "./runtime.js";
 import { publishFileChange } from "../events/file-change.js";
 import { describeKind, registerBuiltinDispatch } from "./builtin-dispatch.js";
 import { wroteSpreadsheetFile } from "./spreadsheet-save-outcome.js";
@@ -18,7 +18,7 @@ registerBuiltinDispatch(SPREADSHEET_SCOPE, async (args) => {
   if (!isSpreadsheetDispatchArgs(args)) {
     throw new Error(`spreadsheet plugin: unrecognised dispatch payload (kind=${describeKind(args)})`);
   }
-  const result = await executeSpreadsheetDispatch(makeConfinedArtifactsFileOps(), args);
+  const result = await executeSpreadsheetDispatch(makeArtifactsFileOps(), args);
   if (wroteSpreadsheetFile(args, result.data)) {
     void publishFileChange(args.path);
   }