machine-bridge-mcp 2.0.0 → 3.0.0-beta.102

package/src/local/secure-file.mjs

@@ -1,4 +1,7 @@
-import { closeSync, constants as fsConstants, fchmodSync, fstatSync, lstatSync, mkdirSync, openSync, readSync } from "node:fs";
+import { closeSync, constants as fsConstants, fchmodSync, fstatSync, lstatSync, mkdirSync, openSync, readSync, unlinkSync } from "node:fs";
+import { filesystemIdentity, sameFilesystemIdentity } from "./filesystem-identity.mjs";
+
+const MULTIPLE_LINK_RETRY_BUFFER = new Int32Array(new SharedArrayBuffer(4));
 
 export function openRegularFileSync(file, flags, options = {}) {
   const mode = Number.isInteger(options.mode) ? options.mode : undefined;
@@ -14,15 +17,25 @@ export function openRegularFileSync(file, flags, options = {}) {
     throw error;
   }
   try {
-    const info = fstatSync(fd);
+    const inspectDescriptor = options.fstatSync || fstatSync;
+    const info = inspectDescriptor(fd);
     if (!info.isFile()) throw new Error(`${label} is not a regular file`);
+    const descriptorIdentityInfo = options.fstatSync ? info : fstatSync(fd, { bigint: true });
+    const identity = filesystemIdentity(descriptorIdentityInfo, label);
+    if (options.rejectMultipleLinks === true && Number(info.nlink) > 1) {
+      throw Object.assign(new Error(`${label} must not have multiple hard links`), { code: "MBM_MULTIPLE_HARD_LINKS" });
+    }
     if (options.verifyPathIdentity === true) {
-      const pathInfo = lstatSync(file);
+      const inspectPath = options.lstatSync || lstatSync;
+      const pathInfo = inspectPath(file);
       if (pathInfo.isSymbolicLink() || !pathInfo.isFile()) throw new Error(`${label} must be a regular file and not a symbolic link`);
-      if (!sameFileIdentity(info, pathInfo)) throw new Error(`${label} identity changed while opening`);
+      const pathIdentityInfo = options.lstatSync ? pathInfo : lstatSync(file, { bigint: true });
+      if (!sameFilesystemIdentity(identity, filesystemIdentity(pathIdentityInfo, label))) {
+        throw Object.assign(new Error(`${label} identity changed while opening`), { code: "MBM_IDENTITY_CHANGED" });
+      }
     }
     if (Number.isInteger(options.chmod)) setDescriptorMode(fd, options.chmod);
-    return { fd, info };
+    return { fd, info, identity, identityInfo: descriptorIdentityInfo };
   } catch (error) {
     closeSync(fd);
     throw error;
@@ -32,14 +45,60 @@ export function openRegularFileSync(file, flags, options = {}) {
 function withRegularFileSync(file, flags, options, callback) {
   const opened = openRegularFileSync(file, flags, options);
   try {
-    return callback(opened.fd, opened.info);
+    return callback(opened.fd, opened.info, opened.identity, opened.identityInfo);
   } finally {
     closeSync(opened.fd);
   }
 }
 
+export function retryTransientMultipleLinksSync(callback) {
+  for (let attempt = 1; attempt <= 4; attempt += 1) {
+    try { return callback(); }
+    catch (error) {
+      if (error?.code !== "MBM_MULTIPLE_HARD_LINKS" || attempt === 4) throw error;
+      Atomics.wait(MULTIPLE_LINK_RETRY_BUFFER, 0, 0, 1);
+    }
+  }
+  throw new Error("transient multiple-link retry did not settle");
+}
+
 export function chmodRegularFileSync(file, mode, label = "path") {
-  return withRegularFileSync(file, fsConstants.O_RDONLY, { label, chmod: mode }, () => undefined);
+  return withRegularFileSync(file, fsConstants.O_RDONLY, { label, chmod: mode, rejectMultipleLinks: true }, () => undefined);
+}
+
+export function chmodRegularFileIfIdentitySync(file, expectedIdentity, mode, label = "path") {
+  return withRegularFileSync(file, fsConstants.O_RDONLY, { label, rejectMultipleLinks: true }, (fd, _info, identity) => {
+    if (!sameFilesystemIdentity(expectedIdentity, identity)) throw new Error(`${label} changed before permission update`);
+    setDescriptorMode(fd, mode);
+  });
+}
+
+export function ownerOnlyFile(filePath) {
+  return chmodRegularFileSync(filePath, 0o600, "owner-only path");
+}
+
+export function unlinkRegularFileIfIdentitySync(file, expectedIdentity, label = "file") {
+  let current;
+  try { current = lstatSync(file, { bigint: true }); } catch (error) {
+    if (String(/** @type {any} */ (error)?.code || "") === "ENOENT") return false;
+    throw error;
+  }
+  if (current.isSymbolicLink() || !current.isFile() || current.nlink !== 1n
+      || !sameFilesystemIdentity(expectedIdentity, filesystemIdentity(current, label))) return false;
+  try { unlinkSync(file); return true; } catch (error) {
+    if (String(/** @type {any} */ (error)?.code || "") === "ENOENT") return false;
+    throw error;
+  }
+}
+
+
+export function inspectPathIfPresentSync(file, label = "path", options = {}) {
+  const inspect = options.lstatSync || lstatSync;
+  try { return inspect(file); }
+  catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw new Error(`${label} could not be inspected`, { cause: error });
+  }
 }
 
 export function readBoundedRegularFileSync(file, maxBytes, label = "path", options = {}) {
@@ -52,7 +111,8 @@ export function readBoundedRegularFileWithInfoSync(file, maxBytes, label = "path
   return withRegularFileSync(file, fsConstants.O_RDONLY, {
     label,
     verifyPathIdentity: options.verifyPathIdentity === true,
-  }, (fd, info) => {
+    rejectMultipleLinks: options.rejectMultipleLinks === true,
+  }, (fd, info, identity, identityInfo) => {
     if (info.size > limit) throw new Error(`file exceeds ${limit} bytes`);
     options.afterOpen?.({ fd, info });
     const buffer = Buffer.alloc(info.size);
@@ -62,7 +122,7 @@ export function readBoundedRegularFileWithInfoSync(file, maxBytes, label = "path
       if (!count) break;
       offset += count;
     }
-    return { buffer: buffer.subarray(0, offset), info };
+    return { buffer: buffer.subarray(0, offset), info, identity, identityInfo };
   });
 }
 
@@ -108,19 +168,12 @@ export function ensureOwnerOnlyDirectorySync(dir, options = {}) {
   }
 }
 
+export function ensureOwnerOnlyDir(dir, options = {}) {
+  return ensureOwnerOnlyDirectorySync(dir, options);
+}
+
 function setDescriptorMode(fd, mode) {
   try { fchmodSync(fd, mode); } catch (error) {
     if (process.platform !== "win32") throw error;
   }
 }
-
-function sameFileIdentity(left, right) {
-  const leftDevice = Number(left.dev);
-  const rightDevice = Number(right.dev);
-  const leftInode = Number(left.ino);
-  const rightInode = Number(right.ino);
-  if ([leftDevice, rightDevice, leftInode, rightInode].every((value) => Number.isSafeInteger(value) && value >= 0)) {
-    return leftDevice === rightDevice && leftInode === rightInode;
-  }
-  return true;
-}

package/src/local/security-audit-dispatch.mjs

@@ -0,0 +1,35 @@
+export function enqueueSecurityAudit(securityAudit, operation, outcome, failureReporter) {
+  if (!securityAudit?.record || operation.context.origin !== "relay") return;
+  let persistence;
+  try {
+    persistence = securityAudit.record({
+      ...outcome,
+      tool: operation.tool,
+      riskCategory: operation.context.operationAuthorization?.category || "ordinary operation",
+      targetHash: operation.context.operationAuthorization?.targetHash || "",
+      principal: operation.context.authority?.principal || {},
+      inputBytes: safeByteLength(operation.args),
+    });
+  } catch (error) {
+    operation.context.auditWarning = "security_audit_unavailable";
+    failureReporter.report("security.audit.enqueue.failed", { error_class: auditErrorClass(error) }, "Security audit event could not be queued");
+    return;
+  }
+  Promise.resolve(persistence).then((recorded) => {
+    if (recorded) return;
+    operation.context.auditWarning = "security_audit_unavailable";
+    failureReporter.report("security.audit.persist.failed", { tool: operation.tool }, "Security audit event could not be persisted");
+  }).catch((error) => {
+    operation.context.auditWarning = "security_audit_unavailable";
+    failureReporter.report("security.audit.persist.failed", {
+      error_class: auditErrorClass(error), tool: operation.tool,
+    }, "Security audit event could not be persisted");
+  });
+}
+
+function safeByteLength(value) {
+  try { return Buffer.byteLength(JSON.stringify(value)); } catch { return 0; }
+}
+function auditErrorClass(error) {
+  return String(error?.code || error?.name || "audit_error").replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 80);
+}

package/src/local/security-audit-log.mjs

@@ -0,0 +1,215 @@
+import { createHmac, randomBytes } from "node:crypto";
+import { Worker } from "node:worker_threads";
+import {
+  SECURITY_AUDIT_MAX_BYTES,
+  SECURITY_AUDIT_MAX_EVENTS,
+  auditFilePath,
+  unhealthyAuditSnapshot,
+} from "./security-audit-storage.mjs";
+
+const MAX_PENDING_RECORDS = 1024;
+const CLOSE_TIMEOUT_MS = 5000;
+
+export class SecurityAuditLog {
+  constructor({ root = "", now = Date.now, WorkerClass = Worker, identityKey = null } = {}) {
+    this.root = root ? String(root) : "";
+    this.file = this.root ? auditFilePath(this.root) : "";
+    this.now = typeof now === "function" ? now : Date.now;
+    this.identityKey = identityKey ? Buffer.from(identityKey) : randomBytes(32);
+    this.worker = null;
+    this.workerReady = false;
+    this.closed = false;
+    this.nextId = 1;
+    this.pending = new Map();
+    this.droppedRecords = 0;
+    this.cachedSnapshot = this.file ? initializingSnapshot() : disabledSnapshot();
+    if (!this.file) return;
+    try {
+      const worker = new WorkerClass(new URL("./security-audit-worker.mjs", import.meta.url), {
+        workerData: { root: this.root },
+      });
+      this.worker = worker;
+      worker.on("message", (message) => { if (this.worker === worker) this.handleMessage(message); });
+      worker.on("error", (error) => { if (this.worker === worker) this.handleWorkerFailure(error); });
+      worker.on("exit", (code) => {
+        if (this.worker === worker && !this.closed) {
+          this.handleWorkerFailure(Object.assign(new Error("security audit worker exited"), {
+            code: code === 0 ? "audit_worker_unexpected_exit" : "audit_worker_exit",
+          }));
+        }
+      });
+    } catch (error) {
+      this.cachedSnapshot = unhealthyAuditSnapshot(error);
+    }
+  }
+
+  record(input = {}) {
+    if (!this.file || this.closed || !this.worker) return Promise.resolve(false);
+    if (this.pending.size >= MAX_PENDING_RECORDS) {
+      this.droppedRecords += 1;
+      this.cachedSnapshot = { ...this.cachedSnapshot, healthy: false, last_error_class: "audit_queue_full" };
+      return Promise.resolve(false);
+    }
+    const id = this.nextId++;
+    return new Promise((resolvePromise) => {
+      this.pending.set(id, { resolve: resolvePromise, kind: "record" });
+      try {
+        this.worker.postMessage({ type: "record", id, input: projectAuditInput(input, this.identityKey), nowMs: Number(this.now()) });
+      } catch (error) {
+        this.pending.delete(id);
+        this.droppedRecords += 1;
+        this.cachedSnapshot = unhealthyAuditSnapshot(error);
+        resolvePromise(false);
+      }
+    });
+  }
+
+  flush() {
+    return this.barrier("flush");
+  }
+
+  async close({ timeoutMs = CLOSE_TIMEOUT_MS } = {}) {
+    if (this.closed) return true;
+    this.closed = true;
+    if (!this.worker) return false;
+    const worker = this.worker;
+    const closing = this.barrier("close", true);
+    let timer;
+    try {
+      return await Promise.race([
+        closing,
+        new Promise((resolvePromise) => {
+          timer = setTimeout(() => resolvePromise(false), normalizeCloseTimeoutMs(timeoutMs));
+          timer.unref?.();
+        }),
+      ]);
+    } finally {
+      clearTimeout(timer);
+      await worker.terminate().catch(() => { /* Audit shutdown already owns the terminal state; worker termination is best-effort cleanup. */ });
+      if (this.worker === worker) this.worker = null;
+      this.failPending(false);
+    }
+  }
+
+  snapshot() {
+    return {
+      ...this.cachedSnapshot,
+      persistence: this.file ? "worker-thread-batched-atomic" : "disabled",
+      worker_ready: this.workerReady,
+      queue_depth: [...this.pending.values()].filter((entry) => entry.kind === "record").length,
+      queue_capacity: MAX_PENDING_RECORDS,
+      dropped_records: this.droppedRecords,
+    };
+  }
+
+  barrier(type, allowClosed = false) {
+    if (!this.worker || (this.closed && !allowClosed)) return Promise.resolve(false);
+    const id = this.nextId++;
+    return new Promise((resolvePromise) => {
+      this.pending.set(id, { resolve: resolvePromise, kind: type });
+      try { this.worker.postMessage({ type, id }); }
+      catch {
+        this.pending.delete(id);
+        resolvePromise(false);
+      }
+    });
+  }
+
+  handleMessage(message) {
+    if (message?.snapshot) this.cachedSnapshot = message.snapshot;
+    if (message?.type === "ready") {
+      this.workerReady = message.snapshot?.healthy === true;
+      return;
+    }
+    if (message?.type === "record_batch_result" && Array.isArray(message.ids)) {
+      for (const rawId of message.ids) {
+        const id = Number(rawId);
+        const pending = this.pending.get(id);
+        if (!pending) continue;
+        this.pending.delete(id);
+        if (message.recorded !== true) this.droppedRecords += 1;
+        pending.resolve(message.recorded === true);
+      }
+      return;
+    }
+    const id = Number(message?.id);
+    const pending = this.pending.get(id);
+    if (!pending) return;
+    this.pending.delete(id);
+    if (message.type === "flushed" || message.type === "closed") pending.resolve(true);
+  }
+
+  handleWorkerFailure(error) {
+    this.workerReady = false;
+    this.cachedSnapshot = unhealthyAuditSnapshot(error);
+    this.droppedRecords += [...this.pending.values()].filter((entry) => entry.kind === "record").length;
+    const worker = this.worker;
+    this.worker = null;
+    this.failPending(false);
+    if (!this.closed) void worker?.terminate?.().catch?.(() => {
+      // The audit worker has already failed and pending records were settled false;
+      // termination is best-effort cleanup and cannot restore audit availability.
+    });
+  }
+
+  failPending(value) {
+    for (const pending of this.pending.values()) pending.resolve(value);
+    this.pending.clear();
+  }
+}
+
+function normalizeCloseTimeoutMs(value) {
+  let numeric;
+  try { numeric = Number(value); } catch { return CLOSE_TIMEOUT_MS; }
+  if (!Number.isFinite(numeric) || numeric <= 0) return CLOSE_TIMEOUT_MS;
+  return Math.min(CLOSE_TIMEOUT_MS, Math.max(1, numeric));
+}
+
+function initializingSnapshot() {
+  return {
+    enabled: true, healthy: false, retained: 0, maximum: SECURITY_AUDIT_MAX_EVENTS, maximum_bytes: SECURITY_AUDIT_MAX_BYTES,
+    last_event_at: null, last_error_class: "audit_initializing",
+    content_logged: false, chain_verified: false,
+  };
+}
+
+function disabledSnapshot() {
+  return {
+    enabled: false,
+    healthy: true,
+    retained: 0,
+    maximum: SECURITY_AUDIT_MAX_EVENTS,
+    maximum_bytes: SECURITY_AUDIT_MAX_BYTES,
+    last_event_at: null,
+    last_error_class: null,
+    content_logged: false,
+    chain_verified: true,
+  };
+}
+
+function projectAuditInput(input, identityKey) {
+  const principal = input?.principal && typeof input.principal === "object" ? input.principal : {};
+  return {
+    outcome: input?.outcome,
+    tool: input?.tool,
+    riskCategory: input?.riskCategory,
+    targetHash: input?.targetHash,
+    durationMs: input?.durationMs,
+    inputBytes: input?.inputBytes,
+    outputBytes: input?.outputBytes,
+    errorCode: input?.errorCode,
+    principal: {
+      kind: principal.kind,
+      accountId: runtimePrivateReference(identityKey, principal.accountId),
+      accountVersion: principal.accountVersion,
+      clientId: runtimePrivateReference(identityKey, principal.clientId),
+      familyId: runtimePrivateReference(identityKey, principal.familyId),
+      role: principal.role,
+    },
+  };
+}
+
+function runtimePrivateReference(key, value) {
+  if (!value) return null;
+  return createHmac("sha256", key).update(String(value)).digest("hex");
+}

package/src/local/security-audit-state.mjs

@@ -0,0 +1,139 @@
+import { createHash, randomBytes } from "node:crypto";
+
+const HASH_PATTERN = /^[a-f0-9]{64}$/;
+
+export function decodeAndVerifyAuditState(buffer, schemaVersion, maximumEvents) {
+  let state;
+  try { state = JSON.parse(buffer.toString("utf8")); } catch (error) {
+    throw new Error("security audit state is not valid JSON", { cause: error });
+  }
+  validateState(state, schemaVersion, maximumEvents);
+  let previous = state.anchor;
+  for (const event of state.events) {
+    if (event.previous_hash !== previous || event.hash !== eventHash(event)) {
+      throw new Error("security audit hash chain verification failed");
+    }
+    previous = event.hash;
+  }
+  return state;
+}
+
+export function emptyAuditState(schemaVersion) {
+  return {
+    schemaVersion,
+    identity_salt: randomBytes(32).toString("hex"),
+    anchor: randomBytes(32).toString("hex"),
+    next_sequence: 1,
+    events: [],
+  };
+}
+
+export function copyAuditState(state) {
+  return { ...state, events: [...state.events] };
+}
+
+export function appendAuditRecords(state, records) {
+  for (const record of records) state.events.push(buildEvent(record?.input || {}, state, record?.nowMs));
+}
+
+export function boundedAuditStateContent(state, maximumEvents, maximumBytes) {
+  const events = state.events;
+  const eventBytes = events.map((event) => Buffer.byteLength(JSON.stringify(event)));
+  let start = Math.max(0, events.length - maximumEvents);
+  let retained = events.length - start;
+  let bytes = Buffer.byteLength(`${JSON.stringify({ ...state, events: [] })}\n`);
+  for (let index = start; index < events.length; index += 1) bytes += eventBytes[index];
+  if (retained > 1) bytes += retained - 1;
+
+  while (bytes > maximumBytes && start < events.length) {
+    bytes -= eventBytes[start];
+    if (retained > 1) bytes -= 1;
+    start += 1;
+    retained -= 1;
+  }
+  if (start > 0) state.anchor = events[start - 1].hash;
+  state.events = events.slice(start);
+
+  const content = `${JSON.stringify(state)}\n`;
+  if (Buffer.byteLength(content) > maximumBytes) throw new Error("security audit state exceeds its size limit");
+  return content;
+}
+
+function buildEvent(input, state, nowMs) {
+  const timestamp = new Date(Number(nowMs)).toISOString();
+  if (!Number.isFinite(Date.parse(timestamp))) throw new Error("security audit timestamp is invalid");
+  const principal = input.principal && typeof input.principal === "object" ? input.principal : {};
+  const event = {
+    sequence: state.next_sequence,
+    timestamp,
+    outcome: boundedToken(input.outcome, "unknown"),
+    tool: boundedToken(input.tool, "unknown"),
+    risk_category: boundedText(input.riskCategory, "ordinary operation", 160),
+    target_hash: HASH_PATTERN.test(String(input.targetHash || "")) ? String(input.targetHash) : null,
+    account_ref: principal.accountId ? privateReference(state.identity_salt, principal.accountId) : null,
+    client_ref: principal.clientId ? privateReference(state.identity_salt, principal.clientId) : null,
+    family_ref: principal.familyId ? privateReference(state.identity_salt, principal.familyId) : null,
+    account_version: Number.isSafeInteger(principal.accountVersion) ? principal.accountVersion : null,
+    role: boundedToken(principal.role, principal.kind === "local" ? "local" : "unknown"),
+    duration_ms: boundedNumber(input.durationMs),
+    input_bytes: boundedNumber(input.inputBytes),
+    output_bytes: boundedNumber(input.outputBytes),
+    error_code: input.errorCode ? boundedToken(input.errorCode, "unknown") : null,
+    previous_hash: state.events.at(-1)?.hash || state.anchor,
+  };
+  const completed = { ...event, hash: eventHash(event) };
+  state.next_sequence += 1;
+  return completed;
+}
+
+function validateState(state, schemaVersion, maximumEvents) {
+  if (!plainRecord(state) || state.schemaVersion !== schemaVersion) throw new Error("security audit state schema is invalid");
+  if (!HASH_PATTERN.test(state.identity_salt) || !HASH_PATTERN.test(state.anchor)) {
+    throw new Error("security audit state identity is invalid");
+  }
+  if (!Number.isSafeInteger(state.next_sequence) || state.next_sequence < 1) {
+    throw new Error("security audit sequence is invalid");
+  }
+  if (!Array.isArray(state.events) || state.events.length > maximumEvents || !state.events.every(validEvent)) {
+    throw new Error("security audit events are invalid");
+  }
+  if (state.events.length && state.next_sequence <= state.events.at(-1).sequence) {
+    throw new Error("security audit sequence did not advance");
+  }
+}
+
+function validEvent(event) {
+  return plainRecord(event)
+    && Number.isSafeInteger(event.sequence) && event.sequence > 0
+    && Number.isFinite(Date.parse(String(event.timestamp || "")))
+    && typeof event.outcome === "string" && typeof event.tool === "string" && typeof event.risk_category === "string"
+    && (event.target_hash === null || HASH_PATTERN.test(event.target_hash))
+    && ["account_ref", "client_ref", "family_ref"].every((key) => event[key] === null || HASH_PATTERN.test(event[key]))
+    && (event.account_version === null || Number.isSafeInteger(event.account_version))
+    && typeof event.role === "string"
+    && Number.isFinite(event.duration_ms) && Number.isFinite(event.input_bytes) && Number.isFinite(event.output_bytes)
+    && (event.error_code === null || typeof event.error_code === "string")
+    && HASH_PATTERN.test(event.previous_hash) && HASH_PATTERN.test(event.hash);
+}
+
+function eventHash(event) {
+  const value = { ...event };
+  delete value.hash;
+  return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+
+function privateReference(salt, value) {
+  return createHash("sha256").update(salt).update("\0").update(String(value)).digest("hex");
+}
+
+function boundedToken(value, fallback) {
+  return String(value || fallback).replace(/[^A-Za-z0-9._:-]/g, "_").slice(0, 128) || fallback;
+}
+function boundedText(value, fallback, maximum) {
+  return String(value || fallback).replace(/[\r\n\t\u0000-\u001f\u007f]/g, " ").trim().slice(0, maximum) || fallback;
+}
+function boundedNumber(value) {
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? Math.min(Math.floor(number), Number.MAX_SAFE_INTEGER) : 0;
+}
+function plainRecord(value) { return Boolean(value) && typeof value === "object" && !Array.isArray(value); }

package/src/local/security-audit-storage.mjs

@@ -0,0 +1,135 @@
+import { lstatSync } from "node:fs";
+import path from "node:path";
+import { replaceFileAtomicallySync } from "./exclusive-file.mjs";
+import { withOwnerStateLock } from "./owner-state-lock.mjs";
+import { ensureOwnerOnlyDirectorySync, readBoundedRegularFileWithInfoSync } from "./secure-file.mjs";
+import { exactFilesystemInteger, filesystemIdentity, filesystemTimeMs, sameFilesystemIdentity } from "./filesystem-identity.mjs";
+import {
+  appendAuditRecords,
+  boundedAuditStateContent,
+  copyAuditState,
+  decodeAndVerifyAuditState,
+  emptyAuditState,
+} from "./security-audit-state.mjs";
+
+export const SECURITY_AUDIT_SCHEMA_VERSION = 1;
+export const SECURITY_AUDIT_MAX_EVENTS = 4096;
+export const SECURITY_AUDIT_MAX_BYTES = 4 * 1024 * 1024;
+
+export function auditFilePath(root) {
+  return path.join(path.resolve(root), "security-audit.json");
+}
+
+export function readVerifiedAuditState(root) {
+  return readVerifiedAuditStateWithIdentity(root).state;
+}
+
+export function createAuditStorageSession(root) {
+  const directory = path.resolve(root);
+  const file = auditFilePath(directory);
+  let cachedState = null;
+  let cachedIdentity;
+
+  const loadVerifiedState = () => {
+    const observedIdentity = inspectAuditFile(file);
+    if (cachedState && sameFileIdentity(cachedIdentity, observedIdentity)) return cachedState;
+    const loaded = readVerifiedAuditStateWithIdentity(directory);
+    cachedState = loaded.state;
+    cachedIdentity = loaded.identity;
+    return cachedState;
+  };
+
+  return Object.freeze({
+    snapshot: () => auditSnapshotFromState(loadVerifiedState()),
+    async recordBatch(records) {
+      if (!Array.isArray(records) || records.length === 0) return auditSnapshotFromState(loadVerifiedState());
+      return withOwnerStateLock(directory, async () => {
+        const state = copyAuditState(loadVerifiedState());
+        appendAuditRecords(state, records);
+        const content = boundedAuditStateContent(state, SECURITY_AUDIT_MAX_EVENTS, SECURITY_AUDIT_MAX_BYTES);
+        cachedIdentity = writeState(file, content);
+        cachedState = state;
+        return auditSnapshotFromState(state);
+      }, {
+        purpose: "security-audit", fileName: "security-audit.lock", label: "security audit",
+      });
+    },
+  });
+}
+
+export async function recordAuditBatch(root, records) {
+  return createAuditStorageSession(root).recordBatch(records);
+}
+
+export function auditSnapshotFromState(state) {
+  return {
+    enabled: true, healthy: true, retained: state.events.length,
+    maximum: SECURITY_AUDIT_MAX_EVENTS, maximum_bytes: SECURITY_AUDIT_MAX_BYTES,
+    last_event_at: state.events.at(-1)?.timestamp || null,
+    last_error_class: null, content_logged: false, chain_verified: true,
+  };
+}
+
+export function unhealthyAuditSnapshot(error) {
+  return {
+    enabled: true, healthy: false, retained: 0,
+    maximum: SECURITY_AUDIT_MAX_EVENTS, maximum_bytes: SECURITY_AUDIT_MAX_BYTES,
+    last_event_at: null, last_error_class: auditErrorClass(error),
+    content_logged: false, chain_verified: false,
+  };
+}
+
+export function auditErrorClass(error) {
+  return String(error?.code || error?.name || "audit_error").replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 80);
+}
+
+function readVerifiedAuditStateWithIdentity(root) {
+  const file = auditFilePath(root);
+  let loaded;
+  try {
+    loaded = readBoundedRegularFileWithInfoSync(file, SECURITY_AUDIT_MAX_BYTES, "security audit state", {
+      verifyPathIdentity: true,
+      rejectMultipleLinks: true,
+    });
+  } catch (error) {
+    if (error?.code === "ENOENT") return { state: emptyAuditState(SECURITY_AUDIT_SCHEMA_VERSION), identity: null };
+    throw error;
+  }
+  return {
+    state: decodeAndVerifyAuditState(loaded.buffer, SECURITY_AUDIT_SCHEMA_VERSION, SECURITY_AUDIT_MAX_EVENTS),
+    identity: fileIdentity(loaded.info, loaded.identity),
+  };
+}
+
+function writeState(file, content) {
+  ensureOwnerOnlyDirectorySync(path.dirname(file));
+  replaceFileAtomicallySync(file, content, { mode: 0o600 });
+  return inspectAuditFile(file);
+}
+
+function inspectAuditFile(file) {
+  let info;
+  try { info = lstatSync(file, { bigint: true }); } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+  if (info.isSymbolicLink() || !info.isFile()) throw new Error("security audit state must be a regular file and not a symbolic link");
+  if (Number(info.nlink) > 1) throw new Error("security audit state must not have multiple hard links");
+  return fileIdentity(info);
+}
+
+function fileIdentity(info, exactIdentity = filesystemIdentity(info, "security audit state")) {
+  return {
+    ...exactIdentity,
+    size: exactFilesystemInteger(info.size, "security audit state size"),
+    mtime_ms: filesystemTimeMs(info.mtimeMs, "security audit modification time"),
+    ctime_ms: filesystemTimeMs(info.ctimeMs, "security audit change time"),
+  };
+}
+
+function sameFileIdentity(left, right) {
+  if (left === null || right === null) return left === right;
+  return Boolean(left && right)
+    && sameFilesystemIdentity(left, right) && left.size === right.size
+    && left.mtime_ms === right.mtime_ms && left.ctime_ms === right.ctime_ms;
+}