@vrtmrz/livesync-commonlib 0.1.0-rc.6 → 0.1.0-rc.8

package/dist/platform/node/storage.d.ts

@@ -2,7 +2,12 @@ import type { UXDataWriteOptions, UXStat } from "../../common/types.js";
 import type { IStorageAdapter } from "../../serviceModules/adapters/IStorageAdapter.js";
 export type NodeStorageStat = UXStat;
 export interface CreateNodeStorageOptions {
-    /** Absolute or process-relative directory which bounds every adapter operation. */
+    /**
+     * Host-selected root directory. Adapter paths are resolved relative to this root.
+     *
+     * The host owns this trust boundary. The adapter is not a filesystem sandbox against
+     * an untrusted local process which can replace path components concurrently.
+     */
     rootPath: string;
 }
 /** Rooted storage adapter backed by Node's file-system APIs. */
@@ -10,6 +15,7 @@ export declare class NodeStorageAdapter implements IStorageAdapter<NodeStorageSt
     private readonly rootPath;
     constructor(rootPath: string);
     private resolvePath;
+    private assertNoSymbolicLinks;
     exists(path: string): Promise<boolean>;
     trystat(path: string): Promise<NodeStorageStat | null>;
     stat(path: string): Promise<NodeStorageStat | null>;
@@ -20,10 +26,13 @@ export declare class NodeStorageAdapter implements IStorageAdapter<NodeStorageSt
     write(path: string, data: string, options?: UXDataWriteOptions): Promise<void>;
     writeBinary(path: string, data: ArrayBuffer, options?: UXDataWriteOptions): Promise<void>;
     append(path: string, data: string, options?: UXDataWriteOptions): Promise<void>;
+    /** Atomically rename or move an entry without leaving the injected root. */
+    rename(sourcePath: string, targetPath: string): Promise<void>;
     list(basePath: string): Promise<{
         files: string[];
         folders: string[];
     }>;
+    private writeFile;
     private applyTimes;
 }
 /** Bind a Node storage adapter to an explicitly selected root directory. */

package/dist/platform/node/storage.js

@@ -1,16 +1,40 @@
+import { constants as nodeFsConstants } from "node:fs";
 import * as nodeFsPromises from "node:fs/promises";
 import * as nodePath from "node:path";
 import { validateStoragePath } from "../storagePath.js";
+const NO_FOLLOW = nodeFsConstants.O_NOFOLLOW ?? 0;
+class SymbolicLinkStoragePathError extends Error {
+  constructor(path) {
+    super(`Storage paths must not contain symbolic links: ${path}`);
+    this.name = "SymbolicLinkStoragePathError";
+  }
+}
 class NodeStorageAdapter {
+  rootPath;
   constructor(rootPath) {
-    this.rootPath = rootPath;
+    this.rootPath = nodePath.resolve(rootPath);
   }
-  rootPath;
-  resolvePath(path, allowRoot = true) {
-    return nodePath.join(this.rootPath, validateStoragePath(path, allowRoot));
+  async resolvePath(path, allowRoot = true) {
+    const fullPath = nodePath.join(this.rootPath, validateStoragePath(path, allowRoot));
+    await this.assertNoSymbolicLinks(fullPath);
+    return fullPath;
+  }
+  async assertNoSymbolicLinks(fullPath) {
+    const relativePath = nodePath.relative(this.rootPath, fullPath);
+    let currentPath = this.rootPath;
+    for (const segment of relativePath.split(nodePath.sep).filter(Boolean)) {
+      currentPath = nodePath.join(currentPath, segment);
+      try {
+        const stat = await nodeFsPromises.lstat(currentPath);
+        if (stat.isSymbolicLink()) throw new SymbolicLinkStoragePathError(currentPath);
+      } catch (error) {
+        if (error.code === "ENOENT") return;
+        throw error;
+      }
+    }
   }
   async exists(path) {
-    const fullPath = this.resolvePath(path);
+    const fullPath = await this.resolvePath(path);
     try {
       await nodeFsPromises.access(fullPath);
       return true;
@@ -20,14 +44,15 @@ class NodeStorageAdapter {
   }
   async trystat(path) {
     try {
-      const stat = await nodeFsPromises.stat(this.resolvePath(path));
+      const stat = await nodeFsPromises.stat(await this.resolvePath(path));
       return {
         size: stat.size,
         mtime: Math.floor(stat.mtimeMs),
         ctime: Math.floor(stat.ctimeMs),
         type: stat.isDirectory() ? "folder" : "file"
       };
-    } catch {
+    } catch (error) {
+      if (error instanceof SymbolicLinkStoragePathError) throw error;
       return null;
     }
   }
@@ -35,10 +60,12 @@ class NodeStorageAdapter {
     return await this.trystat(path);
   }
   async mkdir(path) {
-    await nodeFsPromises.mkdir(this.resolvePath(path), { recursive: true });
+    const fullPath = await this.resolvePath(path);
+    await nodeFsPromises.mkdir(fullPath, { recursive: true });
+    await this.assertNoSymbolicLinks(fullPath);
   }
   async remove(path) {
-    const fullPath = this.resolvePath(path, false);
+    const fullPath = await this.resolvePath(path, false);
     const stat = await nodeFsPromises.stat(fullPath);
     if (stat.isDirectory()) {
       await nodeFsPromises.rm(fullPath, { recursive: true, force: true });
@@ -47,33 +74,55 @@ class NodeStorageAdapter {
     }
   }
   async read(path) {
-    return await nodeFsPromises.readFile(this.resolvePath(path, false), "utf-8");
+    const handle = await nodeFsPromises.open(
+      await this.resolvePath(path, false),
+      nodeFsConstants.O_RDONLY | NO_FOLLOW
+    );
+    try {
+      return await handle.readFile("utf-8");
+    } finally {
+      await handle.close();
+    }
   }
   async readBinary(path) {
-    const buffer = await nodeFsPromises.readFile(this.resolvePath(path, false));
-    return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+    const handle = await nodeFsPromises.open(
+      await this.resolvePath(path, false),
+      nodeFsConstants.O_RDONLY | NO_FOLLOW
+    );
+    try {
+      const buffer = await handle.readFile();
+      return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+    } finally {
+      await handle.close();
+    }
   }
   async write(path, data, options) {
-    const fullPath = this.resolvePath(path, false);
+    const fullPath = await this.resolvePath(path, false);
     await nodeFsPromises.mkdir(nodePath.dirname(fullPath), { recursive: true });
-    await nodeFsPromises.writeFile(fullPath, data, "utf-8");
-    await this.applyTimes(fullPath, options);
+    await this.writeFile(fullPath, data, options, false);
   }
   async writeBinary(path, data, options) {
-    const fullPath = this.resolvePath(path, false);
+    const fullPath = await this.resolvePath(path, false);
     await nodeFsPromises.mkdir(nodePath.dirname(fullPath), { recursive: true });
-    await nodeFsPromises.writeFile(fullPath, new Uint8Array(data));
-    await this.applyTimes(fullPath, options);
+    await this.writeFile(fullPath, new Uint8Array(data), options, false);
   }
   async append(path, data, options) {
-    const fullPath = this.resolvePath(path, false);
+    const fullPath = await this.resolvePath(path, false);
     await nodeFsPromises.mkdir(nodePath.dirname(fullPath), { recursive: true });
-    await nodeFsPromises.appendFile(fullPath, data, "utf-8");
-    await this.applyTimes(fullPath, options);
+    await this.writeFile(fullPath, data, options, true);
+  }
+  /** Atomically rename or move an entry without leaving the injected root. */
+  async rename(sourcePath, targetPath) {
+    const fullSourcePath = await this.resolvePath(sourcePath, false);
+    const fullTargetPath = await this.resolvePath(targetPath, false);
+    await nodeFsPromises.mkdir(nodePath.dirname(fullTargetPath), { recursive: true });
+    await this.assertNoSymbolicLinks(fullSourcePath);
+    await this.assertNoSymbolicLinks(fullTargetPath);
+    await nodeFsPromises.rename(fullSourcePath, fullTargetPath);
   }
   async list(basePath) {
     try {
-      const entries = await nodeFsPromises.readdir(this.resolvePath(basePath), { withFileTypes: true });
+      const entries = await nodeFsPromises.readdir(await this.resolvePath(basePath), { withFileTypes: true });
       const files = [];
       const folders = [];
       for (const entry of entries) {
@@ -82,15 +131,27 @@ class NodeStorageAdapter {
         else if (entry.isFile()) files.push(entryPath);
       }
       return { files, folders };
-    } catch {
+    } catch (error) {
+      if (error instanceof SymbolicLinkStoragePathError) throw error;
       return { files: [], folders: [] };
     }
   }
-  async applyTimes(fullPath, options) {
+  async writeFile(fullPath, data, options, append) {
+    await this.assertNoSymbolicLinks(fullPath);
+    const flags = nodeFsConstants.O_WRONLY | nodeFsConstants.O_CREAT | NO_FOLLOW | (append ? nodeFsConstants.O_APPEND : nodeFsConstants.O_TRUNC);
+    const handle = await nodeFsPromises.open(fullPath, flags, 438);
+    try {
+      await handle.writeFile(data, typeof data === "string" ? "utf-8" : void 0);
+      await this.applyTimes(handle, options);
+    } finally {
+      await handle.close();
+    }
+  }
+  async applyTimes(handle, options) {
     if (!options?.mtime && !options?.ctime) return;
     const accessTime = options.mtime ? new Date(options.mtime) : /* @__PURE__ */ new Date();
     const modificationTime = options.mtime ? new Date(options.mtime) : /* @__PURE__ */ new Date();
-    await nodeFsPromises.utimes(fullPath, accessTime, modificationTime);
+    await handle.utimes(accessTime, modificationTime);
   }
 }
 function createNodeStorage({ rootPath }) {

package/dist/replication/trystero/addP2PEventHandlers.js

@@ -19,14 +19,11 @@ function addP2PEventHandlers(source, events) {
   });
   events.onEvent(EVENT_SETTING_SAVED, async (settings) => {
     const instance = current();
-    const isOpen = instance.isServing ?? instance.server?.isServing ?? false;
     if (settings.P2P_Enabled && settings.P2P_AutoStart) {
       await instance.open();
       return;
     }
-    if (isOpen) {
-      await instance.close();
-    }
+    await instance.close();
   });
 }
 async function openP2PReplicator(instance) {

package/dist/replication/trystero/useP2PReplicatorFeature.js

@@ -8,6 +8,7 @@ function useP2PReplicatorFeature(host, openReplicationUIFactory, openRebuildUIFa
   let replicator = new LiveSyncTrysteroReplicator({
     services: host.services
   });
+  let replacementPromise;
   if (openReplicationUIFactory) {
     replicator.env.openReplicationUI = openReplicationUIFactory(replicator);
   }
@@ -24,22 +25,31 @@ function useP2PReplicatorFeature(host, openReplicationUIFactory, openRebuildUIFa
     async (settingOverride = {}) => {
       const settings = { ...host.services.setting.currentSettings(), ...settingOverride };
       if (settings.remoteType == REMOTE_P2P) {
-        const existingReplicator = replicator;
+        if (replacementPromise) return await replacementPromise;
+        const operation = (async () => {
+          const existingReplicator = replicator;
+          try {
+            await existingReplicator?.close();
+          } catch (e) {
+            Logger(`Error closing existing p2p replicator`);
+            Logger(e, LOG_LEVEL_VERBOSE);
+          }
+          const newReplicator = new LiveSyncTrysteroReplicator({ services: host.services });
+          if (openReplicationUIFactory) {
+            newReplicator.env.openReplicationUI = openReplicationUIFactory(newReplicator);
+          }
+          if (openRebuildUIFactory) {
+            newReplicator.env.openRebuildUI = openRebuildUIFactory(newReplicator);
+          }
+          replicator = newReplicator;
+          return replicator;
+        })();
+        replacementPromise = operation;
         try {
-          await existingReplicator?.close();
-        } catch (e) {
-          Logger(`Error closing existing p2p replicator`);
-          Logger(e, LOG_LEVEL_VERBOSE);
+          return await operation;
+        } finally {
+          if (replacementPromise === operation) replacementPromise = void 0;
         }
-        const newReplicator = new LiveSyncTrysteroReplicator({ services: host.services });
-        if (openReplicationUIFactory) {
-          newReplicator.env.openReplicationUI = openReplicationUIFactory(newReplicator);
-        }
-        if (openRebuildUIFactory) {
-          newReplicator.env.openRebuildUI = openRebuildUIFactory(newReplicator);
-        }
-        replicator = newReplicator;
-        return replicator;
       }
       return void 0;
     }

package/docs/development.md

@@ -59,7 +59,7 @@ The multiple-remote profile contract has focused unit coverage in `src/serviceFe
 
 ### P2P composition ownership
 
-`useP2PReplicatorFeature` is the sole owner of the active `LiveSyncTrysteroReplicator` and its lifecycle bindings. It creates or replaces the outer replicator when `ReplicatorService` requests one, closes the previous instance before replacement, and returns a stable result object whose `replicator` property resolves the current instance.
+`useP2PReplicatorFeature` is the sole owner of the active `LiveSyncTrysteroReplicator` and its lifecycle bindings. It creates or replaces the outer replicator when `ReplicatorService` requests one, closes the previous instance before replacement, shares an in-flight replacement between concurrent callers, and returns a stable result object whose `replicator` property resolves the current instance.
 
 Consumers must preserve that result object and read `result.replicator` at the point of use. Do not destructure the property into a command, event handler, view, or other long-lived closure: a database reinitialisation or remote-type transition can close and replace the captured instance, and calling `open()` on that obsolete outer object can create a second connection outside the active service state.
 

package/docs/p2p-transport-lifecycle.md

@@ -31,7 +31,9 @@ It is therefore a logical LiveSync disconnection and a physical signalling-serve
 
 ## Reconnection and replacement
 
-An explicit open resumes Trystero relay reconnection before joining the configured room. Settings application may change the relay URLs, room ID, passphrase, or TURN configuration, so the owning service closes and discards the former LiveSync instance before constructing the replacement. No fixed close-to-open delay is required: lifecycle operations are serialised, and peer readiness is observed through discovery.
+An explicit open resumes Trystero relay reconnection before joining the configured room. Settings application may change the relay URLs, room ID, passphrase, or TURN configuration, so the owning service closes and discards the former LiveSync instance before constructing the replacement. Concurrent replacement requests share the same in-flight replacement and receive the same new owner. No fixed close-to-open delay is required: lifecycle operations are serialised, and peer readiness is observed through discovery.
+
+Saving settings with P2P or automatic start disabled always requests `close()`, even when the room has not started serving. This cancels an in-flight open through the same lifecycle queue, so a connection cannot appear after the disabling setting has been applied.
 
 Do not replace a relay socket's `onclose` handler. Trystero 0.25 shares relay clients by URL and uses its own handler to retire and recreate them. Use the exported pause and resume functions around explicit disconnection instead.
 
@@ -51,7 +53,7 @@ Commonlib consequently does not expose a forced physical-disconnection command.
 
 Maintain all five boundaries when this lifecycle changes:
 
-- Commonlib unit tests must prove that normal close leaves the room without directly closing Trystero-owned peers, and that overlapping open and close requests leave one current owner;
+- Commonlib unit tests must prove that normal close leaves the room without directly closing Trystero-owned peers, that disabling settings cancel a pending open, and that concurrent replacement requests leave one current owner;
 - Commonlib rebuild tests must prove that first-device P2P initialisation does not reset a remote database and that an additional-device P2P Fetch performs one explicit peer-selection pass before resuming reflection;
 - the Self-hosted LiveSync Compose P2P lifecycle test must replace a current replicator, rediscover the same real peer, perform bidirectional RPC, and verify transferred content from a separate process;
 - the Self-hosted LiveSync real-Obsidian P2P Setup URI workflow must generate the second-device URI on the first device, accept both peer directions visibly, and verify a two-way note round-trip; and

package/docs/platform-storage.md

@@ -39,6 +39,10 @@ await storage.write('notes/example.md', '# Example');
 
 `rootPath` may be absolute or process-relative. The host should normally resolve and validate configuration before constructing the adapter.
 
+The Node adapter rejects symbolic-link components which it observes in an adapter path before an operation. File opens also use `O_NOFOLLOW` for the final component where the platform exposes that flag. These checks protect against invalid paths and symbolic links which already exist when an operation begins. Its concrete `rename(sourcePath, targetPath)` operation validates both paths before providing the atomic rename expected by Node hosts.
+
+The host-selected `rootPath` is a trust boundary, not an operating-system filesystem sandbox. The adapter assumes that an untrusted local process cannot replace that root or its descendants concurrently with an operation. A host which grants another local actor write access to the tree must not rely on the adapter as a privilege boundary.
+
 ## Shared path contract
 
 Adapter paths are relative to the injected root and use forward slashes. The empty path refers to the root for root-safe operations such as `exists`, `stat`, `list`, and `mkdir`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrtmrz/livesync-commonlib",
-  "version": "0.1.0-rc.6",
+  "version": "0.1.0-rc.8",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "license": "MIT",