@remnic/core 9.54.5 → 9.54.7

package/src/support-passport/owner-lock.ts

@@ -2,7 +2,11 @@ import { createHash } from "node:crypto";
 import path from "node:path";
 
 import type { StorageManager } from "../index.js";
-import { type HeldFileLockController, serializeMutations, withHeldFileLock } from "../utils/serialize-mutations.js";
+import {
+  type HeldFileLockController,
+  serializeMutations,
+  withHeldFileLock,
+} from "../utils/serialize-mutations.js";
 import { SupportPassportError } from "./errors.js";
 
 const CARD_MUTATION_LOCK_STALE_MS = 60_000;
@@ -18,7 +22,7 @@ export function computeSupportPassportOwnerLockKey(namespace: string, principal:
 
 export function supportPassportOwnerLockPath(
   storage: StorageManager,
-  scope: SupportPassportOwnerLockScope
+  scope: SupportPassportOwnerLockScope,
 ): string {
   const ownerLockKey = scope.ownerKey ?? computeSupportPassportOwnerLockKey(scope.namespace, scope.principal);
   if (!/^[a-f0-9]{64}$/.test(ownerLockKey)) {
@@ -30,24 +34,37 @@ export function supportPassportOwnerLockPath(
 export async function withSupportPassportOwnerLock<T>(
   storage: StorageManager,
   scope: SupportPassportOwnerLockScope,
-  task: (lock: HeldFileLockController) => Promise<T>
+  task: (lock: HeldFileLockController) => Promise<T>,
 ): Promise<T> {
   const lockPath = supportPassportOwnerLockPath(storage, scope);
   return await serializeMutations(lockPath, () =>
     withHeldFileLock(
       lockPath,
-      { staleMs: CARD_MUTATION_LOCK_STALE_MS, maxWaitMs: CARD_MUTATION_LOCK_MAX_WAIT_MS },
+      {
+        staleMs: CARD_MUTATION_LOCK_STALE_MS,
+        maxWaitMs: CARD_MUTATION_LOCK_MAX_WAIT_MS,
+      },
       async (acquired, lock) => {
         if (!acquired) {
-          throw new SupportPassportError("storage_conflict", "The support passport is busy. Try again.", 409);
+          throw new SupportPassportError(
+            "storage_conflict",
+            "The support passport is busy. Try again.",
+            409,
+          );
         }
         return await task(lock);
-      }
-    )
+      },
+    ),
   );
 }
 
-export async function requireSupportPassportOwnerLock(lock: HeldFileLockController): Promise<void> {
+export async function requireSupportPassportOwnerLock(
+  lock: HeldFileLockController,
+): Promise<void> {
   if (await lock.refresh()) return;
-  throw new SupportPassportError("storage_conflict", "The support passport changed during the request.", 409);
+  throw new SupportPassportError(
+    "storage_conflict",
+    "The support passport changed during the request.",
+    409,
+  );
 }

package/src/support-passport/private-file.test.ts

@@ -0,0 +1,99 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, open, readFile, rename, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import {
+  appendPrivateFileNoFollow,
+  ensurePrivateDirectoryNoFollow,
+  supportsSupportPassportPrivateFiles,
+  writePrivateFileAtomicallyNoFollow,
+} from "./private-file.js";
+
+test("private support passport files publish their platform gate", () => {
+  assert.equal(supportsSupportPassportPrivateFiles("linux"), true);
+  assert.equal(supportsSupportPassportPrivateFiles("darwin"), true);
+  assert.equal(supportsSupportPassportPrivateFiles("freebsd"), true);
+  assert.equal(supportsSupportPassportPrivateFiles("openbsd"), true);
+  assert.equal(supportsSupportPassportPrivateFiles("win32"), false);
+});
+
+test("private append cannot escape its pinned directory", async (context) => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-private-append-"));
+  context.after(async () => await rm(root, { recursive: true, force: true }));
+  const privateDirectory = path.join(root, "private");
+  const outsidePath = path.join(root, "outside.jsonl");
+  await mkdir(privateDirectory);
+
+  await assert.rejects(appendPrivateFileNoFollow(privateDirectory, outsidePath, "private\n", "private path escaped"));
+  await assert.rejects(readFile(outsidePath, "utf8"), { code: "ENOENT" });
+});
+
+test("private append fails before mutation when descriptor pinning is unavailable", async (context) => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-private-append-win32-"));
+  context.after(async () => await rm(root, { recursive: true, force: true }));
+  const privateDirectory = path.join(root, "private");
+  const auditPath = path.join(privateDirectory, "audit.jsonl");
+  await assert.rejects(
+    ensurePrivateDirectoryNoFollow(root, privateDirectory, "private path escaped", undefined, true, "win32"),
+    /private path escaped/
+  );
+  await assert.rejects(readFile(auditPath, "utf8"), { code: "ENOENT" });
+});
+
+test("private append rejects a renamed target after opening it", async (context) => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-private-append-rename-"));
+  context.after(async () => await rm(root, { recursive: true, force: true }));
+  const privateDirectory = path.join(root, "private");
+  const auditPath = path.join(privateDirectory, "audit.jsonl");
+  const movedPath = path.join(privateDirectory, "moved.jsonl");
+  await mkdir(privateDirectory);
+  await writeFile(auditPath, "before\n", { mode: 0o600 });
+
+  await assert.rejects(
+    appendPrivateFileNoFollow(
+      privateDirectory,
+      auditPath,
+      "after\n",
+      "audit target changed",
+      privateDirectory,
+      process.platform,
+      async (filePath, flags, mode) => {
+        const handle = await open(filePath, flags, mode);
+        await rename(auditPath, movedPath);
+        return handle;
+      }
+    ),
+    /audit target changed/
+  );
+  assert.equal(await readFile(movedPath, "utf8"), "before\n");
+  await assert.rejects(readFile(auditPath, "utf8"), { code: "ENOENT" });
+});
+
+test("private atomic writes reject a final pathname replaced after directory sync", async (context) => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-private-atomic-rename-"));
+  context.after(async () => await rm(root, { recursive: true, force: true }));
+  const privateDirectory = path.join(root, "private");
+  const markerPath = path.join(privateDirectory, "marker.json");
+  const movedPath = path.join(privateDirectory, "moved.json");
+  await mkdir(privateDirectory);
+
+  await assert.rejects(
+    writePrivateFileAtomicallyNoFollow(
+      privateDirectory,
+      markerPath,
+      "committed\n",
+      "marker target changed",
+      privateDirectory,
+      process.platform,
+      async () => {
+        await rename(markerPath, movedPath);
+        await writeFile(markerPath, "replaced\n", { mode: 0o600 });
+      }
+    ),
+    /marker target changed/
+  );
+  assert.equal(await readFile(movedPath, "utf8"), "committed\n");
+  assert.equal(await readFile(markerPath, "utf8"), "replaced\n");
+});

package/src/support-passport/private-file.ts

@@ -6,6 +6,8 @@ import path from "node:path";
 const UNSUPPORTED_DIRECTORY_SYNC_ERRORS = new Set(["EINVAL", "ENOSYS", "ENOTSUP", "EOPNOTSUPP"]);
 const NON_WRITABLE_ANCESTOR_SYNC_ERRORS = new Set(["EROFS", "EPERM", "EACCES"]);
 
+type PrivateFileOpener = (filePath: string, flags: number, mode: number) => Promise<FileHandle>;
+
 function assertStableDirectory(before: Stats, opened: Stats, after: Stats, errorMessage: string): void {
   if (
     before.isSymbolicLink() ||
@@ -37,6 +39,14 @@ function assertStableRegularFile(before: Stats, opened: Stats, after: Stats, err
   }
 }
 
+async function lstatPrivateTarget(filePath: string, errorMessage: string): Promise<Stats> {
+  try {
+    return await lstat(filePath);
+  } catch {
+    throw new Error(errorMessage);
+  }
+}
+
 function openFlags(...flags: Array<number | undefined>): number {
   let combined = 0;
   for (const flag of flags) combined |= typeof flag === "number" ? flag : 0;
@@ -62,7 +72,7 @@ async function openDirectoryNoFollow(
   if (before.isSymbolicLink() || !before.isDirectory()) throw new Error(errorMessage);
   const handle = await open(
     directory,
-    openFlags(fsConstants.O_RDONLY, fsConstants.O_DIRECTORY, fsConstants.O_NOFOLLOW),
+    openFlags(fsConstants.O_RDONLY, fsConstants.O_DIRECTORY, fsConstants.O_NOFOLLOW)
   );
   try {
     const opened = await handle.stat();
@@ -103,6 +113,12 @@ export async function resolvePrivateDirectoryPath(
   return pinnedPath;
 }
 
+export function supportsSupportPassportPrivateFiles(
+  platform: NodeJS.Platform = process.platform
+): boolean {
+  return platform === "linux" || platform === "darwin" || platform === "freebsd" || platform === "openbsd";
+}
+
 export function requirePrivateFileDescriptorRoot(platform: NodeJS.Platform, errorMessage: string): string {
   if (platform === "linux") return "/proc/self/fd";
   if (platform === "darwin" || platform === "freebsd" || platform === "openbsd") return "/dev/fd";
@@ -113,7 +129,7 @@ async function openStableDirectoryFromRoot(
   trustedRoot: string,
   directory: string,
   errorMessage: string,
-  platform: NodeJS.Platform = process.platform,
+  platform: NodeJS.Platform = process.platform
 ): Promise<{
   before: Stats;
   opened: Stats;
@@ -149,7 +165,7 @@ async function openStableDirectoryFromRoot(
         current.handle,
         current.opened,
         errorMessage,
-        platform,
+        platform
       ),
     };
   } catch (error) {
@@ -164,7 +180,7 @@ export async function ensurePrivateDirectoryNoFollow(
   errorMessage: string,
   syncVerifiedParent: (handle: FileHandle) => Promise<void> = syncDirectoryHandle,
   hardenExistingChildren = true,
-  platform: NodeJS.Platform = process.platform,
+  platform: NodeJS.Platform = process.platform
 ): Promise<void> {
   const root = path.resolve(trustedRoot);
   const target = path.resolve(directory);
@@ -207,7 +223,7 @@ export async function ensurePrivateDirectoryTreeNoFollow(
   directory: string,
   errorMessage: string,
   syncVerifiedParent: (handle: FileHandle) => Promise<void> = syncDirectoryHandle,
-  platform: NodeJS.Platform = process.platform,
+  platform: NodeJS.Platform = process.platform
 ): Promise<void> {
   const target = path.resolve(directory);
   const filesystemRoot = path.parse(target).root;
@@ -233,7 +249,7 @@ export async function ensurePrivateDirectoryTreeNoFollow(
       }
     },
     false,
-    platform,
+    platform
   );
 }
 
@@ -242,7 +258,7 @@ export async function withPrivateDirectoryNoFollow<T>(
   directory: string,
   errorMessage: string,
   task: (pinnedDirectory: string) => Promise<T>,
-  platform: NodeJS.Platform = process.platform,
+  platform: NodeJS.Platform = process.platform
 ): Promise<T> {
   let directoryHandles: FileHandle[] = [];
   try {
@@ -261,7 +277,7 @@ export async function readPrivateFileNoFollow(
   filePath: string,
   errorMessage: string,
   trustedRoot = directory,
-  platform: NodeJS.Platform = process.platform,
+  platform: NodeJS.Platform = process.platform
 ): Promise<string> {
   if (path.dirname(filePath) !== path.resolve(directory)) throw new Error(errorMessage);
   const targetName = path.basename(filePath);
@@ -290,6 +306,111 @@ export async function readPrivateFileNoFollow(
   }
 }
 
+export async function appendPrivateFileNoFollow(
+  directory: string,
+  filePath: string,
+  content: string,
+  errorMessage: string,
+  trustedRoot = directory,
+  platform: NodeJS.Platform = process.platform,
+  openFile: PrivateFileOpener = open
+): Promise<void> {
+  if (path.dirname(filePath) !== path.resolve(directory)) throw new Error(errorMessage);
+  const targetName = path.basename(filePath);
+  let directoryHandles: FileHandle[] = [];
+  try {
+    const stableDirectory = await openStableDirectoryFromRoot(trustedRoot, directory, errorMessage, platform);
+    directoryHandles = stableDirectory.handles;
+    await appendPrivateFileAtPinnedDirectory(
+      stableDirectory.pinnedDirectory,
+      targetName,
+      content,
+      errorMessage,
+      stableDirectory.handle,
+      openFile
+    );
+    assertStableDirectory(stableDirectory.before, stableDirectory.opened, await lstat(directory), errorMessage);
+  } finally {
+    await closeDirectoryHandles(directoryHandles);
+  }
+}
+
+async function appendPrivateFileAtPinnedDirectory(
+  pinnedDirectory: string,
+  targetName: string,
+  content: string,
+  errorMessage: string,
+  directoryHandle: FileHandle | undefined,
+  openFile: PrivateFileOpener
+): Promise<void> {
+  if (
+    targetName.length === 0 ||
+    targetName === "." ||
+    targetName === ".." ||
+    path.basename(targetName) !== targetName
+  ) {
+    throw new Error(errorMessage);
+  }
+  const targetPath = path.join(pinnedDirectory, targetName);
+  let fileHandle: FileHandle | undefined;
+  try {
+    try {
+      fileHandle = await openFile(
+        targetPath,
+        openFlags(fsConstants.O_WRONLY, fsConstants.O_APPEND, fsConstants.O_CREAT, fsConstants.O_NOFOLLOW),
+        0o600
+      );
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ELOOP") throw new Error(errorMessage);
+      throw error;
+    }
+    const targetMetadata = await lstatPrivateTarget(targetPath, errorMessage);
+    assertStableRegularFile(
+      targetMetadata,
+      await fileHandle.stat(),
+      await lstatPrivateTarget(targetPath, errorMessage),
+      errorMessage
+    );
+    await fileHandle.chmod(0o600);
+    await fileHandle.appendFile(content, "utf8");
+    await fileHandle.sync();
+    assertStableRegularFile(
+      targetMetadata,
+      await fileHandle.stat(),
+      await lstatPrivateTarget(targetPath, errorMessage),
+      errorMessage
+    );
+    if (directoryHandle) await syncDirectoryHandle(directoryHandle);
+  } finally {
+    await fileHandle?.close().catch(() => undefined);
+  }
+}
+
+export async function appendPrivateFileInPinnedDirectory(
+  pinnedDirectory: string,
+  fileName: string,
+  content: string,
+  errorMessage: string,
+  platform: NodeJS.Platform = process.platform
+): Promise<void> {
+  const descriptorRoot = requirePrivateFileDescriptorRoot(platform, errorMessage);
+  const resolvedDirectory = path.resolve(pinnedDirectory);
+  const descriptor = path.relative(descriptorRoot, resolvedDirectory);
+  if (!/^\d+$/.test(descriptor)) throw new Error(errorMessage);
+  const before = await stat(resolvedDirectory);
+  if (!before.isDirectory()) throw new Error(errorMessage);
+  let directoryHandle: FileHandle | undefined;
+  try {
+    directoryHandle = await open(resolvedDirectory, openFlags(fsConstants.O_RDONLY, fsConstants.O_DIRECTORY));
+    const opened = await directoryHandle.stat();
+    assertStableDirectory(before, opened, await stat(resolvedDirectory), errorMessage);
+    await appendPrivateFileAtPinnedDirectory(resolvedDirectory, fileName, content, errorMessage, directoryHandle, open);
+    assertStableDirectory(before, opened, await stat(resolvedDirectory), errorMessage);
+  } finally {
+    await directoryHandle?.close().catch(() => undefined);
+  }
+}
+
 export async function writePrivateFileAtomicallyNoFollow(
   directory: string,
   filePath: string,
@@ -297,6 +418,7 @@ export async function writePrivateFileAtomicallyNoFollow(
   errorMessage: string,
   trustedRoot = directory,
   platform: NodeJS.Platform = process.platform,
+  syncVerifiedDirectory: (handle: FileHandle) => Promise<void> = syncDirectoryHandle
 ): Promise<void> {
   if (path.dirname(filePath) !== path.resolve(directory)) throw new Error(errorMessage);
   const targetName = path.basename(filePath);
@@ -327,12 +449,17 @@ export async function writePrivateFileAtomicallyNoFollow(
     await fileHandle.chmod(0o600);
     await fileHandle.writeFile(content, "utf8");
     await fileHandle.sync();
-    await fileHandle.close();
-    fileHandle = undefined;
     assertStableDirectory(stableDirectory.before, stableDirectory.opened, await lstat(directory), errorMessage);
     await rename(tempPath, targetPath);
     assertStableDirectory(stableDirectory.before, stableDirectory.opened, await lstat(directory), errorMessage);
-    if (stableDirectory.handle) await syncDirectoryHandle(stableDirectory.handle);
+    if (stableDirectory.handle) await syncVerifiedDirectory(stableDirectory.handle);
+    const committedMetadata = await lstatPrivateTarget(targetPath, errorMessage);
+    assertStableRegularFile(
+      committedMetadata,
+      await fileHandle.stat(),
+      await lstatPrivateTarget(targetPath, errorMessage),
+      errorMessage
+    );
   } finally {
     await fileHandle?.close().catch(() => undefined);
     if (tempPath) await rm(tempPath, { force: true }).catch(() => undefined);
@@ -345,7 +472,7 @@ export async function removePrivateFilesNoFollow(
   fileNames: string[],
   errorMessage: string,
   trustedRoot = directory,
-  platform: NodeJS.Platform = process.platform,
+  platform: NodeJS.Platform = process.platform
 ): Promise<void> {
   if (
     fileNames.some(