chainlesschain 0.166.115 → 0.166.118

package/src/lib/evolution/evolution-ledger.js

@@ -16,6 +16,7 @@ import {
 } from "../secure-fs.js";
 import { withFileLock } from "../with-file-lock.js";
 import { isLocalUiEvolutionFileSystem } from "./evolution-windows-directory-durability.js";
+import { isProductionEvolutionFileSystem } from "./evolution-private-storage.js";
 import {
   assertKnowledgeWikiSourceAdmission,
   WIKI_SOURCE_ADMISSION_INVALID_CODE,
@@ -65,6 +66,8 @@ export const EVOLUTION_LEDGER_V2_CUTOVER_COMPLETED =
   "evolution.ledger-v2.cutover-completed";
 const MIGRATION_SOURCES = new WeakMap();
 const DIRECTORY_BOUNDARIES = new WeakMap();
+const VERIFIED_HISTORY_READERS = new WeakMap();
+const DEFAULT_APPEND_PORTS = new WeakSet();
 
 const IDENTITY_DOMAIN = "chainlesschain.evolution-ledger-identity/v1\0";
 const EVENT_DOMAIN = "chainlesschain.evolution-event/v2\0";
@@ -1684,6 +1687,11 @@ const PHYSICAL_DIRECTORY_FIELDS = Object.freeze([
   "gid",
 ]);
 const physicalBirthtime = (stat) => artifactPhysicalIdentity(stat).birthtimeMs;
+const physicalFileFingerprint = (stat) =>
+  [
+    ...PHYSICAL_FILE_FIELDS.map((field) => String(stat[field])),
+    String(stat.birthtimeNs ?? physicalBirthtime(stat)),
+  ].join(":");
 const samePhysicalFile = (left, right) =>
   PHYSICAL_FILE_FIELDS.every((field) => left[field] === right[field]) &&
   physicalBirthtime(left) === physicalBirthtime(right);
@@ -1713,6 +1721,16 @@ function assertPhysicalFile(stat, maximum, label) {
   }
 }
 
+function assertWindowsAclPhysicalFile(stat, label) {
+  assertPhysicalFile(stat, Number.MAX_SAFE_INTEGER, label);
+  if (typeof stat.birthtimeNs !== "bigint") {
+    throw ledgerError(
+      "CC_EVOLUTION_LEDGER_CORRUPT",
+      `${label} requires full-precision creation time`,
+    );
+  }
+}
+
 function physicalDirectoryIdentity(stat) {
   if (
     PHYSICAL_DIRECTORY_FIELDS.some(
@@ -1946,6 +1964,7 @@ export class EvolutionLedger {
   #lockTimeoutMs;
   #localUiWindowsDurability;
   #pendingWindowsAclFiles;
+  #productionFs;
   #paths;
   #random;
   #secure;
@@ -2011,6 +2030,7 @@ export class EvolutionLedger {
     this.#localUiWindowsDurability =
       process.platform === "win32" && isLocalUiEvolutionFileSystem(fsImpl);
     this.#pendingWindowsAclFiles = new Map();
+    this.#productionFs = isProductionEvolutionFileSystem(fsImpl);
     this.#fs = captureFs(fsImpl);
     // Identity helpers only open parent/volume directories through this port.
     this.#identityFs = Object.freeze({
@@ -2069,22 +2089,51 @@ export class EvolutionLedger {
         requestedPaths.anchorDir,
       ];
       if (this.#secure && this.#localUiWindowsDurability) {
-        const roots = [
-          requestedPaths.rootDir,
-          requestedPaths.authorityRootDir,
-        ];
-        const children = [
-          requestedPaths.segmentDir,
-          requestedPaths.anchorDir,
-        ];
-        // Secure each parent before creating children so inherited Windows
-        // ACLs are private throughout setup. Batch only the child repair.
+        const roots = [requestedPaths.rootDir, requestedPaths.authorityRootDir];
+        const children = [requestedPaths.segmentDir, requestedPaths.anchorDir];
+        // Prepare the independent roots without creating descendants or ledger
+        // objects. Secure both roots in one native ACL operation before any
+        // children can inherit their permissions.
         for (const directory of roots) {
           ensurePrivateDirectory(directory, {
-            applyWindowsAcl: true,
+            applyWindowsAcl: false,
             failIfUnavailable: true,
           });
         }
+        const rootIdentities = roots.map((directory) => {
+          const stat = this.#fs.lstatSync(directory, { bigint: true });
+          const identity = physicalDirectoryIdentity(stat);
+          if (typeof stat.birthtimeNs !== "bigint") {
+            throw new Error(
+              "Private ledger root requires full-precision creation time",
+            );
+          }
+          return { identity, birthtimeNs: stat.birthtimeNs };
+        });
+        const repairedRoots = repairPrivatePaths(roots);
+        if (
+          repairedRoots.length !== roots.length ||
+          repairedRoots.some(
+            (entry, index) =>
+              entry.target !== roots[index] ||
+              entry.ok !== true ||
+              entry.exists === false,
+          )
+        ) {
+          throw new Error("Could not verify private ledger roots");
+        }
+        for (const [index, directory] of roots.entries()) {
+          const stat = this.#fs.lstatSync(directory, { bigint: true });
+          const identity = physicalDirectoryIdentity(stat);
+          const expected = rootIdentities[index];
+          if (
+            identity.dev !== expected.identity.dev ||
+            identity.ino !== expected.identity.ino ||
+            stat.birthtimeNs !== expected.birthtimeNs
+          ) {
+            throw new Error("Private ledger root changed during ACL setup");
+          }
+        }
         for (const directory of children) {
           ensurePrivateDirectory(directory, {
             applyWindowsAcl: false,
@@ -2275,6 +2324,34 @@ export class EvolutionLedger {
           recheck: Object.freeze(recheck),
         }),
       );
+    if (new.target === EvolutionLedger)
+      VERIFIED_HISTORY_READERS.set(
+        this,
+        Object.freeze((...args) => {
+          if (args.length)
+            throw new TypeError(
+              "verified history takes no replacement context",
+            );
+          return this.#withLock(() => {
+            const state = this.#loadState({
+              allowInitialize: false,
+              incremental: true,
+            });
+            return deepFreeze({
+              authority: this.#authorityProjection(state),
+              events: state.events.slice(0, 10_000),
+            });
+          });
+        }),
+      );
+    if (
+      new.target === EvolutionLedger &&
+      this.#productionFs &&
+      lock === withFileLock &&
+      crashHook == null
+    ) {
+      DEFAULT_APPEND_PORTS.add(this);
+    }
     Object.freeze(this);
   }
 
@@ -3063,7 +3140,7 @@ export class EvolutionLedger {
     label,
     allowMissing,
     samePathHandle,
-    { trustedParentPath = null } = {},
+    { trustedParentPath = null, legacyFingerprint = true } = {},
   ) {
     const heldParent =
       trustedParentPath !== null &&
@@ -3091,19 +3168,24 @@ export class EvolutionLedger {
       // Preserve the exact legacy Number fingerprint already signed into the
       // store marker binding. It is sampled inside a separate BigInt window and
       // is never used as the authority for a physical file/handle comparison.
-      const legacyBefore = this.#fs.lstatSync(filePath);
-      const sampled = this.#fs.lstatSync(filePath, { bigint: true });
-      assertPhysicalFile(sampled, maximum, label);
-      if (
-        !samePhysicalFile(before, sampled) ||
-        (!heldParent && !samePath(realpath(this.#fs, filePath), filePath))
-      ) {
+      let fingerprint = null;
+      if (legacyFingerprint) {
+        const legacyBefore = this.#fs.lstatSync(filePath);
+        const sampled = this.#fs.lstatSync(filePath, { bigint: true });
+        assertPhysicalFile(sampled, maximum, label);
+        if (!samePhysicalFile(before, sampled)) {
+          throw ledgerError(
+            "CC_EVOLUTION_LEDGER_CORRUPT",
+            `${label} changed while its fingerprint was sampled`,
+          );
+        }
+        fingerprint = fileFingerprint(legacyBefore);
+      }
+      if (!heldParent && !samePath(realpath(this.#fs, filePath), filePath))
         throw ledgerError(
           "CC_EVOLUTION_LEDGER_CORRUPT",
           `${label} changed while its fingerprint was sampled`,
         );
-      }
-      const fingerprint = fileFingerprint(legacyBefore);
       descriptor = this.#fs.openSync(
         filePath,
         this.#fs.constants.O_RDONLY |
@@ -3137,7 +3219,9 @@ export class EvolutionLedger {
         );
       }
       const after = this.#fs.fstatSync(descriptor, { bigint: true });
-      const legacyAfter = this.#fs.lstatSync(filePath);
+      const legacyAfter = legacyFingerprint
+        ? this.#fs.lstatSync(filePath)
+        : null;
       const afterPath = this.#fs.lstatSync(filePath, { bigint: true });
       assertPhysicalFile(after, maximum, label);
       assertPhysicalFile(afterPath, maximum, label);
@@ -3154,7 +3238,7 @@ export class EvolutionLedger {
         !samePhysicalFile(before, afterPath) ||
         !samePathHandle(afterPath, after) ||
         !samePhysicalOwner(afterPath, after) ||
-        fileFingerprint(legacyAfter) !== fingerprint ||
+        (legacyFingerprint && fileFingerprint(legacyAfter) !== fingerprint) ||
         (!heldParent && !samePath(realpath(this.#fs, filePath), filePath))
       ) {
         throw ledgerError(
@@ -3162,7 +3246,13 @@ export class EvolutionLedger {
           `${label} pathname changed during bounded read`,
         );
       }
-      return { bytes, fingerprint };
+      return {
+        bytes,
+        fingerprint,
+        physicalFingerprint: this.#productionFs
+          ? physicalFileFingerprint(before)
+          : null,
+      };
     } catch (cause) {
       if (cause instanceof EvolutionLedgerError) throw cause;
       throw ledgerError(
@@ -3193,7 +3283,7 @@ export class EvolutionLedger {
       { trustedParentPath },
     );
     if (file === null) return null;
-    const { bytes, fingerprint } = file;
+    const { bytes } = file;
     if (expectedBytes !== null) {
       if (!Buffer.isBuffer(expectedBytes) || !bytes.equals(expectedBytes)) {
         throw ledgerError(
@@ -3201,7 +3291,7 @@ export class EvolutionLedger {
           `${label} differs from its signed snapshot bytes`,
         );
       }
-      return { bytes, contentDigest: sha256(bytes), fingerprint, record: null };
+      return { ...file, contentDigest: sha256(bytes), record: null };
     }
     let text;
     try {
@@ -3235,7 +3325,7 @@ export class EvolutionLedger {
         `${label} bytes are not canonical`,
       );
     }
-    return { bytes, contentDigest: sha256(bytes), fingerprint, record };
+    return { ...file, contentDigest: sha256(bytes), record };
   }
 
   #writeImmutable(filePath, bytes, label, onPublished = null) {
@@ -3418,9 +3508,27 @@ export class EvolutionLedger {
   #securePublishedFile(filePath, stat) {
     if (!this.#secure) return;
     if (this.#localUiWindowsDurability) {
+      const physical = this.#fs.lstatSync(filePath, { bigint: true });
+      assertWindowsAclPhysicalFile(physical, "published ledger file");
+      // Keep the publication sample consistent, then retain the full-precision
+      // path identity for all ACL checks (the signed legacy binding is unchanged).
+      if (
+        ["dev", "ino", "mode", "size"].some(
+          (field) => Number(physical[field]) !== stat[field],
+        ) ||
+        Number(physical.birthtimeNs / 1_000_000_000n) * 1000 +
+          Number(physical.birthtimeNs % 1_000_000_000n) / 1_000_000 !==
+          stat.birthtimeMs
+      ) {
+        throw ledgerError(
+          "CC_EVOLUTION_LEDGER_STORE_UNSAFE",
+          "published ledger file changed before Windows ACL verification",
+        );
+      }
       this.#pendingWindowsAclFiles.set(path.resolve(filePath), {
-        identity: artifactPhysicalIdentity(stat),
-        size: stat.size,
+        identity: artifactPhysicalIdentity(physical),
+        birthtimeNs: physical.birthtimeNs,
+        size: physical.size,
       });
       return;
     }
@@ -3431,12 +3539,13 @@ export class EvolutionLedger {
   }
 
   #assertPendingWindowsAclFile(filePath, expected) {
-    const stat = this.#fs.lstatSync(filePath);
+    const stat = this.#fs.lstatSync(filePath, { bigint: true });
     if (
       !stat.isFile() ||
       stat.isSymbolicLink() ||
-      stat.nlink !== 1 ||
+      stat.nlink !== 1n ||
       stat.size !== expected.size ||
+      stat.birthtimeNs !== expected.birthtimeNs ||
       !sameArtifactIdentity(stat, expected.identity)
     ) {
       throw ledgerError(
@@ -3456,7 +3565,9 @@ export class EvolutionLedger {
     }
     const entries = [...this.#pendingWindowsAclFiles.entries()];
     const files = entries.map(([filePath]) => filePath);
-    const directories = [...new Set(files.map((filePath) => path.dirname(filePath)))];
+    const directories = [
+      ...new Set(files.map((filePath) => path.dirname(filePath))),
+    ];
     try {
       this.#assertBoundaries();
       for (const [filePath, expected] of entries) {
@@ -3475,31 +3586,73 @@ export class EvolutionLedger {
         throw new Error("Windows ACL batch did not verify every ledger file");
       }
       for (const [filePath, expected] of entries) {
-        this.#assertPendingWindowsAclFile(filePath, expected);
-        const descriptor = this.#fs.openSync(
+        // Affected libuv path stats project dev differently from fstat. Bind
+        // the handle to a separately held parent volume without relaxing the
+        // inode, owner, creation time, or mutation metadata checks.
+        withEvolutionFileIdentity(
+          this.#identityFs,
           filePath,
-          this.#fs.constants.O_RDWR | (this.#fs.constants.O_NOFOLLOW || 0),
-        );
-        try {
-          const opened = this.#fs.fstatSync(descriptor);
-          if (
-            !opened.isFile() ||
-            opened.nlink !== 1 ||
-            opened.size !== expected.size ||
-            !sameArtifactIdentity(opened, expected.identity)
-          ) {
-            throw ledgerError(
-              "CC_EVOLUTION_LEDGER_STORE_UNSAFE",
-              "ledger file identity changed during Windows ACL verification",
+          (samePathHandle) => {
+            const before = this.#assertPendingWindowsAclFile(
+              filePath,
+              expected,
             );
-          }
-          this.#fs.fsyncSync(descriptor);
-        } finally {
-          this.#fs.closeSync(descriptor);
-        }
+            assertWindowsAclPhysicalFile(before, "published ledger file");
+            const descriptor = this.#fs.openSync(
+              filePath,
+              this.#fs.constants.O_RDWR | (this.#fs.constants.O_NOFOLLOW || 0),
+            );
+            try {
+              const opened = this.#fs.fstatSync(descriptor, { bigint: true });
+              assertWindowsAclPhysicalFile(
+                opened,
+                "published ledger descriptor",
+              );
+              if (
+                !opened.isFile() ||
+                opened.nlink !== 1n ||
+                opened.size !== expected.size ||
+                opened.birthtimeNs !== before.birthtimeNs ||
+                !samePathHandle(before, opened) ||
+                !samePhysicalOwner(before, opened)
+              ) {
+                throw ledgerError(
+                  "CC_EVOLUTION_LEDGER_STORE_UNSAFE",
+                  "ledger file identity changed during Windows ACL verification",
+                );
+              }
+              this.#fs.fsyncSync(descriptor);
+              const after = this.#fs.fstatSync(descriptor, { bigint: true });
+              assertWindowsAclPhysicalFile(
+                after,
+                "published ledger descriptor",
+              );
+              const afterPath = this.#assertPendingWindowsAclFile(
+                filePath,
+                expected,
+              );
+              if (
+                !samePhysicalFile(opened, after) ||
+                opened.birthtimeNs !== after.birthtimeNs ||
+                !samePhysicalFile(before, afterPath) ||
+                afterPath.birthtimeNs !== after.birthtimeNs ||
+                !samePathHandle(afterPath, after) ||
+                !samePhysicalOwner(afterPath, after)
+              ) {
+                throw ledgerError(
+                  "CC_EVOLUTION_LEDGER_STORE_UNSAFE",
+                  "ledger file identity changed during Windows ACL verification",
+                );
+              }
+            } finally {
+              this.#fs.closeSync(descriptor);
+            }
+          },
+        );
       }
       this.#assertBoundaries();
-      for (const filePath of files) this.#pendingWindowsAclFiles.delete(filePath);
+      for (const filePath of files)
+        this.#pendingWindowsAclFiles.delete(filePath);
       return directories;
     } catch (cause) {
       if (cause instanceof EvolutionLedgerError) throw cause;
@@ -3832,10 +3985,12 @@ export class EvolutionLedger {
       "cached ledger file",
       false,
       samePathHandle,
-      { trustedParentPath },
+      { trustedParentPath, legacyFingerprint: !this.#productionFs },
     );
     return (
-      file.fingerprint === expected.fingerprint &&
+      (this.#productionFs
+        ? file.physicalFingerprint === expected.physicalFingerprint
+        : file.fingerprint === expected.fingerprint) &&
       sha256(file.bytes) === expected.contentDigest
     );
   }
@@ -4055,6 +4210,7 @@ export class EvolutionLedger {
           anchorFingerprints[entry.name] = Object.freeze({
             contentDigest: file.contentDigest,
             fingerprint: file.fingerprint,
+            physicalFingerprint: file.physicalFingerprint,
           });
         }
       },
@@ -4093,6 +4249,7 @@ export class EvolutionLedger {
           segmentFingerprints[entry.name] = Object.freeze({
             contentDigest: file.contentDigest,
             fingerprint: file.fingerprint,
+            physicalFingerprint: file.physicalFingerprint,
           });
         }
       },
@@ -4453,6 +4610,7 @@ export class EvolutionLedger {
       anchorFingerprints[name] = Object.freeze({
         contentDigest: anchorFile.contentDigest,
         fingerprint: anchorFile.fingerprint,
+        physicalFingerprint: anchorFile.physicalFingerprint,
       });
       anchors.push(anchor);
       if (index === 0) continue;
@@ -4485,6 +4643,7 @@ export class EvolutionLedger {
       segmentFingerprints[segmentName] = Object.freeze({
         contentDigest: segmentFile.contentDigest,
         fingerprint: segmentFile.fingerprint,
+        physicalFingerprint: segmentFile.physicalFingerprint,
       });
       eventIds.add(event.eventId);
       events.push(event);
@@ -5642,6 +5801,18 @@ export class EvolutionLedger {
   }
 }
 
+/** One authenticated state supplies both history and its exact frontier. */
+export function getEvolutionLedgerVerifiedHistoryReader(ledger) {
+  if (arguments.length !== 1)
+    throw new TypeError("verified history capture takes one original ledger");
+  return VERIFIED_HISTORY_READERS.get(ledger) ?? null;
+}
+
+/** Construction identity only: custom filesystem/lock/crash ports keep phases. */
+export function hasEvolutionLedgerDefaultAppendPorts(ledger) {
+  return DEFAULT_APPEND_PORTS.has(ledger);
+}
+
 // Trusted composition port; consumers receive the journal wrapper, never this
 // capability. WeakMap identity excludes structural or prototype impersonation.
 export function captureEvolutionLedgerMigrationSource(ledger) {

package/src/lib/evolution/evolution-private-storage.js

@@ -0,0 +1,20 @@
+import fs from "node:fs";
+import { isUnmodifiedLocalUiEvolutionFileSystem } from "./evolution-windows-directory-durability.js";
+
+export function isProductionEvolutionFileSystem(fsImpl) {
+  return fsImpl === fs || isUnmodifiedLocalUiEvolutionFileSystem(fsImpl);
+}
+
+export function evolutionPrivateStorageOptions(fsImpl, { file = false } = {}) {
+  // The production adapter only adds directory flushing; ACL operations still
+  // use Node's original fs. Preserve explicit dependencies for custom ports.
+  const production = isProductionEvolutionFileSystem(fsImpl);
+  return {
+    ...(production ? {} : { deps: { fs: fsImpl } }),
+    // An elevated Windows token can give a new file its administrator-group
+    // owner even when its DACL inherits only the user's private directory rule.
+    // Explicit repair binds both the file owner and ACL to the current user.
+    ...(file ? { applyWindowsAcl: true } : {}),
+    failIfUnavailable: true,
+  };
+}