@remnic/core 9.3.519 → 9.3.520

package/src/binary-lifecycle/backend.ts

@@ -6,7 +6,7 @@
  * so swapping storage providers requires no pipeline changes.
  */
 
-import fs from "node:fs";
+import type { Stats } from "node:fs";
 import fsp from "node:fs/promises";
 import path from "node:path";
 import type { BinaryStorageBackendConfig } from "./types.js";
@@ -27,6 +27,8 @@ export interface BinaryStorageBackend {
   exists(remotePath: string): Promise<boolean>;
   /** Delete a file from the backend. */
   delete(remotePath: string): Promise<void>;
+  /** Return the user-resolvable markdown target for a stored backend path. */
+  getRedirectTarget?(remotePath: string): string;
 }
 
 // ---------------------------------------------------------------------------
@@ -45,10 +47,9 @@ export class FilesystemBackend implements BinaryStorageBackend {
   }
 
   private resolveRemotePath(remotePath: string): string {
-    if (path.isAbsolute(remotePath)) {
-      throw new Error(`FilesystemBackend remotePath must be relative: ${JSON.stringify(remotePath)}`);
-    }
-    const resolved = path.resolve(this.basePath, remotePath);
+    const resolved = path.isAbsolute(remotePath)
+      ? path.resolve(remotePath)
+      : path.resolve(this.basePath, remotePath);
     const relative = path.relative(this.basePath, resolved);
     if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
       throw new Error(`FilesystemBackend remotePath escapes basePath: ${JSON.stringify(remotePath)}`);
@@ -56,26 +57,169 @@ export class FilesystemBackend implements BinaryStorageBackend {
     return resolved;
   }
 
-  async upload(localPath: string, remotePath: string): Promise<string> {
+  private isInsideBase(candidate: string, realBase: string): boolean {
+    const relative = path.relative(realBase, candidate);
+    return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+  }
+
+  private async realBasePathIfExists(): Promise<string | null> {
+    try {
+      const stat = await fsp.lstat(this.basePath);
+      if (stat.isSymbolicLink()) {
+        throw new Error(`FilesystemBackend basePath must not be a symlink: ${this.basePath}`);
+      }
+      if (!stat.isDirectory()) {
+        throw new Error(`FilesystemBackend basePath must be a directory: ${this.basePath}`);
+      }
+      return await fsp.realpath(this.basePath);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        return null;
+      }
+      throw err;
+    }
+  }
+
+  private async ensureBaseDirectory(): Promise<string> {
+    await fsp.mkdir(this.basePath, { recursive: true });
+    const realBase = await this.realBasePathIfExists();
+    if (realBase === null) {
+      throw new Error(`FilesystemBackend failed to create basePath: ${this.basePath}`);
+    }
+    return realBase;
+  }
+
+  private async ensureSafeParentDirectory(dest: string): Promise<string> {
+    const realBase = await this.ensureBaseDirectory();
+    const destDir = path.dirname(dest);
+    const relativeDir = path.relative(this.basePath, destDir);
+    const segments = relativeDir === "" ? [] : relativeDir.split(path.sep);
+    let current = this.basePath;
+
+    for (const segment of segments) {
+      if (segment === "." || segment === "") continue;
+      current = path.join(current, segment);
+      try {
+        const stat = await fsp.lstat(current);
+        if (stat.isSymbolicLink()) {
+          throw new Error(`FilesystemBackend remotePath traverses symlink: ${current}`);
+        }
+        if (!stat.isDirectory()) {
+          throw new Error(`FilesystemBackend remotePath parent is not a directory: ${current}`);
+        }
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+          throw err;
+        }
+        await fsp.mkdir(current);
+      }
+    }
+
+    const realParent = await fsp.realpath(destDir);
+    if (!this.isInsideBase(realParent, realBase)) {
+      throw new Error(`FilesystemBackend remotePath parent escapes basePath: ${dest}`);
+    }
+    return realBase;
+  }
+
+  private async resolveExistingRemotePath(remotePath: string): Promise<string | null> {
     const dest = this.resolveRemotePath(remotePath);
+    const realBase = await this.realBasePathIfExists();
+    if (realBase === null) {
+      return null;
+    }
+
     const destDir = path.dirname(dest);
-    await fsp.mkdir(destDir, { recursive: true });
-    await fsp.copyFile(localPath, dest);
+    const relativeDir = path.relative(this.basePath, destDir);
+    const segments = relativeDir === "" ? [] : relativeDir.split(path.sep);
+    let current = this.basePath;
+    for (const segment of segments) {
+      if (segment === "." || segment === "") continue;
+      current = path.join(current, segment);
+      let stat: Stats;
+      try {
+        stat = await fsp.lstat(current);
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+          return null;
+        }
+        throw err;
+      }
+      if (stat.isSymbolicLink()) {
+        throw new Error(`FilesystemBackend remotePath traverses symlink: ${current}`);
+      }
+      if (!stat.isDirectory()) {
+        return null;
+      }
+    }
+
+    const realParent = await fsp.realpath(destDir).catch((err: NodeJS.ErrnoException) => {
+      if (err.code === "ENOENT") return null;
+      throw err;
+    });
+    if (realParent === null) {
+      return null;
+    }
+    if (!this.isInsideBase(realParent, realBase)) {
+      throw new Error(`FilesystemBackend remotePath parent escapes basePath: ${JSON.stringify(remotePath)}`);
+    }
+
+    try {
+      const stat = await fsp.lstat(dest);
+      if (stat.isSymbolicLink()) {
+        throw new Error(`FilesystemBackend remotePath points to symlink: ${dest}`);
+      }
+      if (!stat.isFile()) {
+        return null;
+      }
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        return null;
+      }
+      throw err;
+    }
+
+    const realDest = await fsp.realpath(dest);
+    if (!this.isInsideBase(realDest, realBase)) {
+      throw new Error(`FilesystemBackend remotePath escapes basePath: ${JSON.stringify(remotePath)}`);
+    }
     return dest;
   }
 
-  async exists(remotePath: string): Promise<boolean> {
+  async upload(localPath: string, remotePath: string): Promise<string> {
+    if (path.isAbsolute(remotePath)) {
+      throw new Error(`FilesystemBackend upload remotePath must be relative: ${JSON.stringify(remotePath)}`);
+    }
     const dest = this.resolveRemotePath(remotePath);
+    const realBase = await this.ensureSafeParentDirectory(dest);
     try {
-      await fsp.access(dest, fs.constants.F_OK);
-      return true;
-    } catch {
-      return false;
+      const stat = await fsp.lstat(dest);
+      if (stat.isSymbolicLink()) {
+        throw new Error(`FilesystemBackend remotePath points to symlink: ${dest}`);
+      }
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+        throw err;
+      }
     }
+    await fsp.copyFile(localPath, dest);
+    const realDest = await fsp.realpath(dest);
+    if (!this.isInsideBase(realDest, realBase)) {
+      throw new Error(`FilesystemBackend remotePath escapes basePath: ${JSON.stringify(remotePath)}`);
+    }
+    return remotePath;
+  }
+
+  async exists(remotePath: string): Promise<boolean> {
+    const dest = await this.resolveExistingRemotePath(remotePath);
+    return dest !== null;
   }
 
   async delete(remotePath: string): Promise<void> {
-    const dest = this.resolveRemotePath(remotePath);
+    const dest = await this.resolveExistingRemotePath(remotePath);
+    if (dest === null) {
+      return;
+    }
     try {
       await fsp.unlink(dest);
     } catch (err: unknown) {
@@ -83,6 +227,10 @@ export class FilesystemBackend implements BinaryStorageBackend {
       if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
     }
   }
+
+  getRedirectTarget(remotePath: string): string {
+    return this.resolveRemotePath(remotePath);
+  }
 }
 
 // ---------------------------------------------------------------------------

package/src/binary-lifecycle/manifest.ts

@@ -24,25 +24,37 @@ export function manifestPath(memoryDir: string): string {
 
 /**
  * Read the manifest from disk. Returns a fresh empty manifest if the file
- * does not exist or contains invalid JSON (CLAUDE.md #18).
+ * does not exist. Existing invalid manifests fail closed so the pipeline does
+ * not overwrite state needed for safe cleanup.
  */
 export async function readManifest(memoryDir: string): Promise<BinaryLifecycleManifest> {
   const filePath = manifestPath(memoryDir);
+  let raw: string;
   try {
-    const raw = await fsp.readFile(filePath, "utf-8");
-    const parsed: unknown = JSON.parse(raw);
-    // CLAUDE.md #18: validate the parsed result is a non-null object.
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    raw = await fsp.readFile(filePath, "utf-8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
       return emptyManifest();
     }
-    const obj = parsed as Record<string, unknown>;
-    if (obj.version !== 1 || !Array.isArray(obj.assets)) {
-      return emptyManifest();
-    }
-    return parsed as BinaryLifecycleManifest;
-  } catch {
-    return emptyManifest();
+    throw new Error(`Failed to read binary lifecycle manifest at ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Invalid binary lifecycle manifest JSON at ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  // CLAUDE.md #18: validate the parsed result is a non-null object.
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`Invalid binary lifecycle manifest shape at ${filePath}: expected object`);
+  }
+  const obj = parsed as Record<string, unknown>;
+  if (obj.version !== 1 || !Array.isArray(obj.assets)) {
+    throw new Error(`Invalid binary lifecycle manifest shape at ${filePath}: expected version 1 with assets array`);
   }
+  return parsed as BinaryLifecycleManifest;
 }
 
 /**