@remnic/core 9.54.4 → 9.54.5

package/src/support-passport/index.ts

@@ -0,0 +1,7 @@
+export * from "./card-projection.js";
+export * from "./card-service.js";
+export * from "./contracts.js";
+export * from "./errors.js";
+export * from "./grant-contracts.js";
+export * from "./grant-service.js";
+export * from "./grant-store.js";

package/src/support-passport/offline-sync-guard.ts

@@ -0,0 +1,230 @@
+import path from "node:path";
+
+import type { OfflineSyncFileTarget } from "../offline-sync-file-io.js";
+import {
+  applyOfflineSyncChangeset,
+  applyOfflineSyncFileContentChunk,
+  buildOfflineSyncSnapshot,
+  normalizeOfflineSyncChangeset,
+  type OfflineSyncApplyChangesetResult,
+  type OfflineSyncApplyFileContentChunkResult,
+} from "../offline-sync.js";
+import { validateArchiveRelativePath } from "../transfer/fs-utils.js";
+import type { MemoryFile } from "../types.js";
+import { createSupportPassportPrivateFileExclusion } from "./card-projection.js";
+
+const MAX_SUPPORT_PASSPORT_FRONTMATTER_BYTES = 1_048_576;
+const SUPPORT_PASSPORT_MARKER = "support-passport-";
+const FRONTMATTER_PREFIXES = ["---\n", "---\r\n"] as const;
+
+type FrontmatterDecision = "allow" | "wait";
+
+interface SupportPassportOfflineSyncStorage {
+  dir: string;
+  readMemoryByPath(filePath: string): Promise<MemoryFile | null>;
+  readOfflineSyncFile(filePath: string): Promise<Buffer>;
+  digestOfflineSyncFile(filePath: string): Promise<{ sha256: string; bytes: number }>;
+  writeOfflineSyncFile(filePath: string, content: Buffer): Promise<void>;
+  writeOfflineSyncStagingFile(filePath: string, content: Buffer): Promise<void>;
+  writeOfflineSyncFileChunks(filePath: string, chunks: AsyncIterable<Buffer>): Promise<void>;
+  deleteOfflineSyncFile(filePath: string, deletionMtimeMs?: number | null): Promise<void>;
+  recordReplicatedDeletionRevision(filePath: string, mtimeMs: number): Promise<void>;
+}
+
+interface SupportPassportOfflineSyncFileContentInput {
+  includeTranscripts?: boolean;
+  sourceId: string;
+  path: string;
+  sha256: string;
+  bytes: number;
+  mtimeMs: number;
+  offset?: number;
+  baseSha256?: string;
+  content: Buffer;
+}
+
+interface SupportPassportOfflineSyncApplyInput {
+  changeset: unknown;
+  returnCurrentFiles?: boolean;
+}
+
+function frontmatterPrefixState(raw: Buffer): "absent" | "present" | "pending" {
+  const prefix = raw.subarray(0, Math.min(raw.length, 5)).toString("utf8");
+  if (FRONTMATTER_PREFIXES.some((candidate) => prefix.startsWith(candidate))) return "present";
+  if (FRONTMATTER_PREFIXES.some((candidate) => candidate.startsWith(prefix))) return "pending";
+  return "absent";
+}
+
+function completeFrontmatter(raw: Buffer): string | null {
+  const text = raw.toString("utf8");
+  return /^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/.exec(text)?.[0] ?? null;
+}
+
+function assertFrontmatterAllowed(frontmatter: string, relativePath: string): void {
+  if (frontmatter.includes(SUPPORT_PASSPORT_MARKER)) {
+    throw new Error(`offline sync cannot modify private support-passport record: ${relativePath}`);
+  }
+}
+
+function inspectBufferedFrontmatter(
+  raw: Buffer,
+  relativePath: string,
+  endOfFile: boolean,
+): FrontmatterDecision {
+  const prefixState = frontmatterPrefixState(raw);
+  if (prefixState === "absent") return "allow";
+  if (prefixState === "pending" && !endOfFile) return "wait";
+
+  const frontmatter = completeFrontmatter(raw);
+  if (frontmatter !== null) {
+    assertFrontmatterAllowed(frontmatter, relativePath);
+    return "allow";
+  }
+  if (raw.length > MAX_SUPPORT_PASSPORT_FRONTMATTER_BYTES) {
+    throw new Error(`offline sync frontmatter is too large: ${relativePath}`);
+  }
+  if (endOfFile) {
+    assertFrontmatterAllowed(raw.toString("utf8"), relativePath);
+    return "allow";
+  }
+  return "wait";
+}
+
+async function* guardSupportPassportChunks(
+  chunks: AsyncIterable<Buffer>,
+  relativePath: string,
+): AsyncIterable<Buffer> {
+  const buffered: Buffer[] = [];
+  let bufferedBytes = 0;
+  let passThrough = false;
+  for await (const chunk of chunks) {
+    if (passThrough) {
+      yield chunk;
+      continue;
+    }
+    buffered.push(chunk);
+    bufferedBytes += chunk.length;
+    const raw = Buffer.concat(buffered, bufferedBytes);
+    if (inspectBufferedFrontmatter(raw, relativePath, false) === "wait") continue;
+    for (const bufferedChunk of buffered) yield bufferedChunk;
+    passThrough = true;
+  }
+  if (!passThrough && bufferedBytes > 0) {
+    const raw = Buffer.concat(buffered, bufferedBytes);
+    inspectBufferedFrontmatter(raw, relativePath, true);
+    for (const bufferedChunk of buffered) yield bufferedChunk;
+  }
+}
+
+export function createSupportPassportOfflineSyncGuard(storage: {
+  dir: string;
+  readMemoryByPath(filePath: string): Promise<MemoryFile | null>;
+}) {
+  const excludePrivateFile = createSupportPassportPrivateFileExclusion(storage);
+
+  const targetForPath = (relativePath: string): OfflineSyncFileTarget => {
+    const normalizedPath = validateArchiveRelativePath(relativePath, "path");
+    return {
+      root: storage.dir,
+      path: normalizedPath,
+      filePath: path.resolve(storage.dir, ...normalizedPath.split("/")),
+    };
+  };
+
+  const assertTargetAllowed = async (target: OfflineSyncFileTarget): Promise<void> => {
+    if (await excludePrivateFile(target)) {
+      throw new Error(`offline sync cannot modify private support-passport record: ${target.path}`);
+    }
+  };
+
+  return {
+    async assertPathAllowed(relativePath: string): Promise<void> {
+      await assertTargetAllowed(targetForPath(relativePath));
+    },
+    assertContentAllowed(relativePath: string, content: Buffer): void {
+      inspectBufferedFrontmatter(content, relativePath, true);
+    },
+    assertTargetAllowed,
+    guardChunks(relativePath: string, chunks: AsyncIterable<Buffer>): AsyncIterable<Buffer> {
+      return guardSupportPassportChunks(chunks, relativePath);
+    },
+    excludePrivateFile,
+  };
+}
+
+export async function applySupportPassportOfflineSyncFileContent(
+  storage: SupportPassportOfflineSyncStorage,
+  options: SupportPassportOfflineSyncFileContentInput,
+): Promise<OfflineSyncApplyFileContentChunkResult> {
+  const guard = createSupportPassportOfflineSyncGuard(storage);
+  await guard.assertPathAllowed(options.path);
+  return applyOfflineSyncFileContentChunk({
+    root: storage.dir,
+    sourceId: options.sourceId,
+    path: options.path,
+    sha256: options.sha256,
+    bytes: options.bytes,
+    mtimeMs: options.mtimeMs,
+    offset: options.offset,
+    baseSha256: options.baseSha256,
+    content: options.content,
+    includeTranscripts: options.includeTranscripts !== false,
+    readFile: async ({ filePath }) => storage.readOfflineSyncFile(filePath),
+    readFileDigest: async ({ filePath }) => storage.digestOfflineSyncFile(filePath),
+    writeFile: async ({ filePath, content }) => storage.writeOfflineSyncFile(filePath, content),
+    writeStagingFile: async ({ filePath, content }) => storage.writeOfflineSyncStagingFile(filePath, content),
+    writeFileChunks: async (target) => {
+      await guard.assertTargetAllowed(target);
+      await storage.writeOfflineSyncFileChunks(
+        target.filePath,
+        guard.guardChunks(target.path, target.chunks),
+      );
+    },
+  });
+}
+
+export async function applySupportPassportOfflineSyncChangeset(
+  storage: SupportPassportOfflineSyncStorage,
+  options: SupportPassportOfflineSyncApplyInput,
+): Promise<OfflineSyncApplyChangesetResult> {
+  const guard = createSupportPassportOfflineSyncGuard(storage);
+  const changeset = normalizeOfflineSyncChangeset(options.changeset);
+  for (const change of changeset.changes) {
+    await guard.assertPathAllowed(change.path);
+    if (change.type === "upsert") {
+      guard.assertContentAllowed(change.path, Buffer.from(change.file.contentBase64, "base64"));
+    }
+  }
+  const result = await applyOfflineSyncChangeset({
+    root: storage.dir,
+    changeset,
+    returnCurrentFiles: false,
+    readFile: async ({ filePath }) => storage.readOfflineSyncFile(filePath),
+    readFileDigest: async ({ filePath }) => storage.digestOfflineSyncFile(filePath),
+    writeFile: async (target) => {
+      await guard.assertTargetAllowed(target);
+      guard.assertContentAllowed(target.path, target.content);
+      await storage.writeOfflineSyncFile(target.filePath, target.content);
+    },
+    deleteFile: async (target) => {
+      await guard.assertTargetAllowed(target);
+      await storage.deleteOfflineSyncFile(target.filePath, target.mtimeMs ?? null);
+    },
+    recordDeletionRevision: async ({ filePath, mtimeMs }) =>
+      storage.recordReplicatedDeletionRevision(filePath, mtimeMs),
+  });
+  if (options.returnCurrentFiles === false) return result;
+
+  const current = await buildOfflineSyncSnapshot({
+    root: storage.dir,
+    sourceId: "local",
+    includeContent: false,
+    includeTranscripts: changeset.includeTranscripts,
+    excludeNodeLocalState: false,
+    readFile: async ({ filePath }) => storage.readOfflineSyncFile(filePath),
+    readFileDigest: async ({ filePath }) => storage.digestOfflineSyncFile(filePath),
+    excludeFile: guard.excludePrivateFile,
+  });
+  const { currentFiles: _partialFiles, currentFilesComplete: _incomplete, ...counts } = result;
+  return { ...counts, currentFiles: current.files };
+}

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

@@ -0,0 +1,53 @@
+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 { SupportPassportError } from "./errors.js";
+
+const CARD_MUTATION_LOCK_STALE_MS = 60_000;
+const CARD_MUTATION_LOCK_MAX_WAIT_MS = 30_000;
+
+export type SupportPassportOwnerLockScope =
+  | { namespace: string; principal: string; ownerKey?: never }
+  | { namespace: string; ownerKey: string; principal?: never };
+
+export function computeSupportPassportOwnerLockKey(namespace: string, principal: string): string {
+  return createHash("sha256").update(JSON.stringify([namespace, principal])).digest("hex");
+}
+
+export function supportPassportOwnerLockPath(
+  storage: StorageManager,
+  scope: SupportPassportOwnerLockScope
+): string {
+  const ownerLockKey = scope.ownerKey ?? computeSupportPassportOwnerLockKey(scope.namespace, scope.principal);
+  if (!/^[a-f0-9]{64}$/.test(ownerLockKey)) {
+    throw new SupportPassportError("card_data_invalid", "The support passport owner scope is invalid.", 500);
+  }
+  return path.join(storage.dir, "state", `support-passport-cards-${ownerLockKey}.lock`);
+}
+
+export async function withSupportPassportOwnerLock<T>(
+  storage: StorageManager,
+  scope: SupportPassportOwnerLockScope,
+  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 },
+      async (acquired, lock) => {
+        if (!acquired) {
+          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> {
+  if (await lock.refresh()) return;
+  throw new SupportPassportError("storage_conflict", "The support passport changed during the request.", 409);
+}

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

@@ -0,0 +1,371 @@
+import { randomUUID } from "node:crypto";
+import { type Stats, constants as fsConstants } from "node:fs";
+import { type FileHandle, lstat, mkdir, open, rename, rm, stat } from "node:fs/promises";
+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"]);
+
+function assertStableDirectory(before: Stats, opened: Stats, after: Stats, errorMessage: string): void {
+  if (
+    before.isSymbolicLink() ||
+    !before.isDirectory() ||
+    after.isSymbolicLink() ||
+    !after.isDirectory() ||
+    before.dev !== opened.dev ||
+    before.ino !== opened.ino ||
+    after.dev !== opened.dev ||
+    after.ino !== opened.ino
+  ) {
+    throw new Error(errorMessage);
+  }
+}
+
+function assertStableRegularFile(before: Stats, opened: Stats, after: Stats, errorMessage: string): void {
+  if (
+    before.isSymbolicLink() ||
+    !before.isFile() ||
+    after.isSymbolicLink() ||
+    !after.isFile() ||
+    before.dev !== opened.dev ||
+    before.ino !== opened.ino ||
+    after.dev !== opened.dev ||
+    after.ino !== opened.ino ||
+    opened.nlink !== 1
+  ) {
+    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;
+  return combined;
+}
+
+function assertContainedPath(trustedRoot: string, directory: string, errorMessage: string): void {
+  const relative = path.relative(path.resolve(trustedRoot), path.resolve(directory));
+  if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error(errorMessage);
+  }
+}
+
+async function openDirectoryNoFollow(
+  directory: string,
+  errorMessage: string
+): Promise<{
+  before: Stats;
+  opened: Stats;
+  handle: FileHandle;
+}> {
+  const before = await lstat(directory);
+  if (before.isSymbolicLink() || !before.isDirectory()) throw new Error(errorMessage);
+  const handle = await open(
+    directory,
+    openFlags(fsConstants.O_RDONLY, fsConstants.O_DIRECTORY, fsConstants.O_NOFOLLOW),
+  );
+  try {
+    const opened = await handle.stat();
+    assertStableDirectory(before, opened, await lstat(directory), errorMessage);
+    return { before, opened, handle };
+  } catch (error) {
+    await handle.close().catch(() => undefined);
+    throw error;
+  }
+}
+
+async function closeDirectoryHandles(handles: FileHandle[]): Promise<void> {
+  for (const handle of handles.reverse()) await handle.close().catch(() => undefined);
+}
+
+async function syncDirectoryHandle(handle: FileHandle): Promise<void> {
+  try {
+    await handle.sync();
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (!UNSUPPORTED_DIRECTORY_SYNC_ERRORS.has(code ?? "")) throw error;
+  }
+}
+
+export async function resolvePrivateDirectoryPath(
+  directory: string,
+  handle: FileHandle,
+  opened: Stats,
+  errorMessage: string,
+  platform: NodeJS.Platform = process.platform
+): Promise<string> {
+  const descriptorRoot = requirePrivateFileDescriptorRoot(platform, errorMessage);
+  const pinnedPath = path.join(descriptorRoot, String(handle.fd));
+  const metadata = await stat(pinnedPath);
+  if (!metadata.isDirectory() || metadata.dev !== opened.dev || metadata.ino !== opened.ino) {
+    throw new Error(errorMessage);
+  }
+  return pinnedPath;
+}
+
+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";
+  throw new Error(errorMessage);
+}
+
+async function openStableDirectoryFromRoot(
+  trustedRoot: string,
+  directory: string,
+  errorMessage: string,
+  platform: NodeJS.Platform = process.platform,
+): Promise<{
+  before: Stats;
+  opened: Stats;
+  handle?: FileHandle;
+  handles: FileHandle[];
+  pinnedDirectory: string;
+}> {
+  const root = path.resolve(trustedRoot);
+  const target = path.resolve(directory);
+  assertContainedPath(root, target, errorMessage);
+  requirePrivateFileDescriptorRoot(platform, errorMessage);
+  const relative = path.relative(root, target);
+  const components = relative === "" ? [] : relative.split(path.sep);
+  const handles: FileHandle[] = [];
+  let currentPath = root;
+  try {
+    let current = await openDirectoryNoFollow(root, errorMessage);
+    handles.push(current.handle);
+    for (const component of components) {
+      const pinnedParent = await resolvePrivateDirectoryPath(currentPath, current.handle, current.opened, errorMessage);
+      const child = await openDirectoryNoFollow(path.join(pinnedParent, component), errorMessage);
+      handles.push(child.handle);
+      assertStableDirectory(current.before, current.opened, await lstat(currentPath), errorMessage);
+      currentPath = path.join(currentPath, component);
+      current = child;
+    }
+    assertStableDirectory(current.before, current.opened, await lstat(target), errorMessage);
+    return {
+      ...current,
+      handles,
+      pinnedDirectory: await resolvePrivateDirectoryPath(
+        target,
+        current.handle,
+        current.opened,
+        errorMessage,
+        platform,
+      ),
+    };
+  } catch (error) {
+    await closeDirectoryHandles(handles);
+    throw error;
+  }
+}
+
+export async function ensurePrivateDirectoryNoFollow(
+  trustedRoot: string,
+  directory: string,
+  errorMessage: string,
+  syncVerifiedParent: (handle: FileHandle) => Promise<void> = syncDirectoryHandle,
+  hardenExistingChildren = true,
+  platform: NodeJS.Platform = process.platform,
+): Promise<void> {
+  const root = path.resolve(trustedRoot);
+  const target = path.resolve(directory);
+  assertContainedPath(root, target, errorMessage);
+  const relative = path.relative(root, target);
+  requirePrivateFileDescriptorRoot(platform, errorMessage);
+  const components = relative === "" ? [] : relative.split(path.sep);
+  const handles: FileHandle[] = [];
+  let currentPath = root;
+  try {
+    let current = await openDirectoryNoFollow(root, errorMessage);
+    handles.push(current.handle);
+    for (const component of components) {
+      const pinnedParent = await resolvePrivateDirectoryPath(currentPath, current.handle, current.opened, errorMessage);
+      const childPath = path.join(pinnedParent, component);
+      let created = false;
+      try {
+        await mkdir(childPath, { mode: 0o700 });
+        created = true;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      }
+      await syncVerifiedParent(current.handle);
+      const child = await openDirectoryNoFollow(childPath, errorMessage);
+      handles.push(child.handle);
+      if (created || (hardenExistingChildren && (child.opened.mode & 0o777) !== 0o700)) {
+        await child.handle.chmod(0o700);
+      }
+      assertStableDirectory(current.before, current.opened, await lstat(currentPath), errorMessage);
+      currentPath = path.join(currentPath, component);
+      current = child;
+    }
+    assertStableDirectory(current.before, current.opened, await lstat(target), errorMessage);
+  } finally {
+    await closeDirectoryHandles(handles);
+  }
+}
+
+export async function ensurePrivateDirectoryTreeNoFollow(
+  directory: string,
+  errorMessage: string,
+  syncVerifiedParent: (handle: FileHandle) => Promise<void> = syncDirectoryHandle,
+  platform: NodeJS.Platform = process.platform,
+): Promise<void> {
+  const target = path.resolve(directory);
+  const filesystemRoot = path.parse(target).root;
+  const rootMetadata = await stat(filesystemRoot);
+  await ensurePrivateDirectoryNoFollow(
+    filesystemRoot,
+    target,
+    errorMessage,
+    async (handle) => {
+      try {
+        await syncVerifiedParent(handle);
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code;
+        const metadata = await handle.stat();
+        if (
+          metadata.ino === rootMetadata.ino &&
+          metadata.dev === rootMetadata.dev &&
+          NON_WRITABLE_ANCESTOR_SYNC_ERRORS.has(code ?? "")
+        ) {
+          return;
+        }
+        throw error;
+      }
+    },
+    false,
+    platform,
+  );
+}
+
+export async function withPrivateDirectoryNoFollow<T>(
+  trustedRoot: string,
+  directory: string,
+  errorMessage: string,
+  task: (pinnedDirectory: string) => Promise<T>,
+  platform: NodeJS.Platform = process.platform,
+): Promise<T> {
+  let directoryHandles: FileHandle[] = [];
+  try {
+    const stableDirectory = await openStableDirectoryFromRoot(trustedRoot, directory, errorMessage, platform);
+    directoryHandles = stableDirectory.handles;
+    const result = await task(stableDirectory.pinnedDirectory);
+    assertStableDirectory(stableDirectory.before, stableDirectory.opened, await lstat(directory), errorMessage);
+    return result;
+  } finally {
+    await closeDirectoryHandles(directoryHandles);
+  }
+}
+
+export async function readPrivateFileNoFollow(
+  directory: string,
+  filePath: string,
+  errorMessage: string,
+  trustedRoot = directory,
+  platform: NodeJS.Platform = process.platform,
+): Promise<string> {
+  if (path.dirname(filePath) !== path.resolve(directory)) throw new Error(errorMessage);
+  const targetName = path.basename(filePath);
+  let directoryHandles: FileHandle[] = [];
+  let fileHandle: FileHandle | undefined;
+  try {
+    const stableDirectory = await openStableDirectoryFromRoot(trustedRoot, directory, errorMessage, platform);
+    directoryHandles = stableDirectory.handles;
+    const pinnedDirectory = stableDirectory.pinnedDirectory;
+    const targetPath = path.join(pinnedDirectory, targetName);
+    const before = await lstat(targetPath);
+    if (before.isSymbolicLink() || !before.isFile()) throw new Error(errorMessage);
+    try {
+      fileHandle = await open(targetPath, openFlags(fsConstants.O_RDONLY, fsConstants.O_NOFOLLOW));
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ELOOP") throw new Error(errorMessage);
+      throw error;
+    }
+    const fileMetadata = await fileHandle.stat();
+    assertStableRegularFile(before, fileMetadata, await lstat(targetPath), errorMessage);
+    assertStableDirectory(stableDirectory.before, stableDirectory.opened, await lstat(directory), errorMessage);
+    return await fileHandle.readFile("utf8");
+  } finally {
+    await fileHandle?.close().catch(() => undefined);
+    await closeDirectoryHandles(directoryHandles);
+  }
+}
+
+export async function writePrivateFileAtomicallyNoFollow(
+  directory: string,
+  filePath: string,
+  content: string,
+  errorMessage: string,
+  trustedRoot = directory,
+  platform: NodeJS.Platform = process.platform,
+): Promise<void> {
+  if (path.dirname(filePath) !== path.resolve(directory)) throw new Error(errorMessage);
+  const targetName = path.basename(filePath);
+  const tempName = `.${targetName}.${randomUUID()}.tmp`;
+  let tempPath: string | undefined;
+  let directoryHandles: FileHandle[] = [];
+  let fileHandle: FileHandle | undefined;
+  try {
+    const stableDirectory = await openStableDirectoryFromRoot(trustedRoot, directory, errorMessage, platform);
+    directoryHandles = stableDirectory.handles;
+    const pinnedDirectory = stableDirectory.pinnedDirectory;
+    tempPath = path.join(pinnedDirectory, tempName);
+    const targetPath = path.join(pinnedDirectory, targetName);
+    try {
+      fileHandle = await open(
+        tempPath,
+        openFlags(fsConstants.O_WRONLY, fsConstants.O_CREAT, fsConstants.O_EXCL, fsConstants.O_NOFOLLOW),
+        0o600
+      );
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ELOOP") throw new Error(errorMessage);
+      throw error;
+    }
+    const fileMetadata = await fileHandle.stat();
+    const tempMetadata = await lstat(tempPath);
+    assertStableRegularFile(tempMetadata, fileMetadata, await lstat(tempPath), errorMessage);
+    assertStableDirectory(stableDirectory.before, stableDirectory.opened, await lstat(directory), errorMessage);
+    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);
+  } finally {
+    await fileHandle?.close().catch(() => undefined);
+    if (tempPath) await rm(tempPath, { force: true }).catch(() => undefined);
+    await closeDirectoryHandles(directoryHandles);
+  }
+}
+
+export async function removePrivateFilesNoFollow(
+  directory: string,
+  fileNames: string[],
+  errorMessage: string,
+  trustedRoot = directory,
+  platform: NodeJS.Platform = process.platform,
+): Promise<void> {
+  if (
+    fileNames.some(
+      (fileName) =>
+        fileName.length === 0 || fileName === "." || fileName === ".." || path.basename(fileName) !== fileName
+    )
+  ) {
+    throw new Error(errorMessage);
+  }
+  let directoryHandles: FileHandle[] = [];
+  try {
+    const stableDirectory = await openStableDirectoryFromRoot(trustedRoot, directory, errorMessage, platform);
+    directoryHandles = stableDirectory.handles;
+    const pinnedDirectory = stableDirectory.pinnedDirectory;
+    for (const fileName of fileNames) {
+      await rm(path.join(pinnedDirectory, fileName), { force: true });
+    }
+    assertStableDirectory(stableDirectory.before, stableDirectory.opened, await lstat(directory), errorMessage);
+    if (stableDirectory.handle) await syncDirectoryHandle(stableDirectory.handle);
+  } finally {
+    await closeDirectoryHandles(directoryHandles);
+  }
+}