cabloy 5.1.216 → 5.1.218

package/vona/packages-vona/vona-core/src/lib/core/testClaimFilesystem.ts

@@ -0,0 +1,224 @@
+import { randomBytes } from 'node:crypto';
+import { constants, lstatSync } from 'node:fs';
+import { lstat, mkdir, open, rename, unlink } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  windowsTestClaimFilesystem,
+  windowsTestClaimFilesystemSync,
+} from './testClaimFilesystemWindows.ts';
+
+export const TEST_CLAIM_FILE_LIMIT = 4 * 1024 * 1024;
+
+export function assertTestClaimFilesystemSafePath(file: string, allowMissing = true) {
+  if (process.platform === 'win32') {
+    windowsTestClaimFilesystemSync({
+      command: 'safe-path',
+      path: path.resolve(file),
+      allowMissing,
+    });
+    return;
+  }
+  let current = path.resolve(file);
+  while (true) {
+    try {
+      const stat = lstatSync(current);
+      if (stat.isSymbolicLink() || (current !== path.resolve(file) && !stat.isDirectory()))
+        throw new Error('Unsafe test claim path');
+    } catch (error) {
+      if (!allowMissing || (error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+}
+
+export async function assertTestClaimPrivateDirectory(
+  directory: string,
+  missingAllowed = true,
+): Promise<boolean> {
+  if (process.platform === 'win32') {
+    const value = await windowsTestClaimFilesystem({
+      command: 'directory',
+      path: path.resolve(directory),
+      allowMissing: missingAllowed,
+    });
+    return value.exists === true;
+  }
+  assertTestClaimFilesystemSafePath(directory, missingAllowed);
+  let stat;
+  try {
+    stat = await lstat(directory);
+  } catch (error) {
+    if (missingAllowed && (error as NodeJS.ErrnoException).code === 'ENOENT') return false;
+    throw error;
+  }
+  if (
+    !stat.isDirectory() ||
+    (stat.mode & 0o077) !== 0 ||
+    (process.getuid && stat.uid !== process.getuid())
+  ) {
+    throw new Error('Unsafe shared test claim directory');
+  }
+  return true;
+}
+
+export async function ensureTestClaimPrivateDirectory(directory: string) {
+  if (process.platform === 'win32') {
+    await windowsTestClaimFilesystem({
+      command: 'ensure-directory',
+      path: path.resolve(directory),
+    });
+    return;
+  }
+  assertTestClaimFilesystemSafePath(directory);
+  await mkdir(directory, { mode: 0o700 }).catch(error => {
+    if (error.code !== 'EEXIST') throw error;
+  });
+  await assertTestClaimPrivateDirectory(directory, false);
+}
+
+function assertPrivateFile(file: string) {
+  assertTestClaimFilesystemSafePath(file, false);
+  const stat = lstatSync(file);
+  if (
+    !stat.isFile() ||
+    stat.nlink !== 1 ||
+    (stat.mode & 0o077) !== 0 ||
+    (process.getuid && stat.uid !== process.getuid())
+  ) {
+    throw new Error('Unsafe test claim file');
+  }
+}
+async function syncDirectory(directory: string) {
+  const handle = await open(directory, constants.O_RDONLY);
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+function checkContent(content: string) {
+  if (Buffer.byteLength(content) > TEST_CLAIM_FILE_LIMIT)
+    throw new Error('Invalid test claim file size');
+}
+export async function readTestClaimFile(file: string): Promise<string> {
+  if (process.platform === 'win32') {
+    const value = await windowsTestClaimFilesystem({ command: 'read', path: path.resolve(file) });
+    if (typeof value.content !== 'string') throw new Error('Invalid test claim file response');
+    return value.content;
+  }
+  assertPrivateFile(file);
+  const handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const stat = await handle.stat();
+    if (
+      !stat.isFile() ||
+      stat.nlink !== 1 ||
+      stat.size > TEST_CLAIM_FILE_LIMIT ||
+      (stat.mode & 0o077) !== 0 ||
+      (process.getuid && stat.uid !== process.getuid())
+    ) {
+      throw new Error('Invalid test claim file');
+    }
+    // Bound the allocation and bytes read even if the file grows after fstat.
+    const buffer = Buffer.alloc(TEST_CLAIM_FILE_LIMIT + 1);
+    let offset = 0;
+    while (offset < buffer.length) {
+      const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, null);
+      if (!bytesRead) break;
+      offset += bytesRead;
+    }
+    if (offset > TEST_CLAIM_FILE_LIMIT) throw new Error('Invalid test claim file size');
+    return buffer.subarray(0, offset).toString('utf8');
+  } finally {
+    await handle.close();
+  }
+}
+export async function createTestClaimFile(file: string, content: string) {
+  checkContent(content);
+  if (process.platform === 'win32') {
+    await windowsTestClaimFilesystem({ command: 'create', path: path.resolve(file), content });
+    return;
+  }
+  assertTestClaimFilesystemSafePath(file);
+  const handle = await open(
+    file,
+    constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
+    0o600,
+  );
+  try {
+    await handle.writeFile(content);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  await syncDirectory(path.dirname(file));
+}
+export async function replaceTestClaimFile(file: string, content: string) {
+  checkContent(content);
+  if (process.platform === 'win32') {
+    await windowsTestClaimFilesystem({ command: 'replace', path: path.resolve(file), content });
+    return;
+  }
+  const temp = `${file}.${randomBytes(12).toString('hex')}.tmp`;
+  const handle = await open(
+    temp,
+    constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
+    0o600,
+  );
+  try {
+    try {
+      await handle.writeFile(content);
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    assertPrivateFile(file);
+    await rename(temp, file);
+    await syncDirectory(path.dirname(file));
+  } finally {
+    await unlink(temp).catch(error => {
+      if (error.code !== 'ENOENT') throw error;
+    });
+  }
+}
+export async function deleteTestClaimFile(file: string) {
+  if (process.platform === 'win32') {
+    await windowsTestClaimFilesystem({ command: 'delete', path: path.resolve(file) });
+    return;
+  }
+  assertPrivateFile(file);
+  await unlink(file);
+}
+
+export interface TestClaimFilesystemLock {
+  release(): Promise<void>;
+}
+export async function acquireTestClaimCleanupLock(file: string): Promise<TestClaimFilesystemLock> {
+  const token = randomBytes(24).toString('hex');
+  const content = `${JSON.stringify({ pid: process.pid, hostname: os.hostname(), startTime: String(Date.now() - process.uptime() * 1000), token })}\n`;
+  // Existence, never age, is the ownership gate. A crash leaves the lock for inspection.
+  await createTestClaimFile(file, content);
+  let released = false;
+  return {
+    async release() {
+      if (released) return;
+      if (process.platform === 'win32') {
+        await windowsTestClaimFilesystem({
+          command: 'release-lock',
+          path: path.resolve(file),
+          expected: content,
+        });
+      } else {
+        // Exact serialized token-bearing identity; never remove a replacement lock.
+        if ((await readTestClaimFile(file)) !== content)
+          throw new Error('Test claim cleanup lock identity changed');
+        await unlink(file);
+      }
+      released = true;
+    },
+  };
+}

package/vona/packages-vona/vona-core/src/lib/core/testClaimFilesystemWindows.cs

@@ -0,0 +1,229 @@
+using System;
+using System.Collections.Generic;
+using System.ComponentModel;
+using System.IO;
+using System.Runtime.InteropServices;
+using System.Security.AccessControl;
+using System.Security.Principal;
+using System.Text;
+using Microsoft.Win32.SafeHandles;
+
+namespace Cabloy {
+    // Local NTFS only. FlushFileBuffers + same-directory rename provides committed
+    // process/crash-safe updates, not a promise of power-loss directory durability.
+    public static class TestClaimFilesystem {
+        const uint ReadControl = 0x20000, DeleteAccess = 0x10000, ReadAttributes = 0x80;
+        const uint GenericRead = 0x80000000, GenericWrite = 0x40000000;
+        const uint ShareRead = 1, ShareWrite = 2, OpenExisting = 3, CreateNew = 1;
+        const uint OpenReparsePoint = 0x200000, BackupSemantics = 0x2000000;
+        const uint ReparsePoint = 0x400, DirectoryAttribute = 0x10;
+        const int Limit = 4 * 1024 * 1024;
+        static readonly string UserSid = WindowsIdentity.GetCurrent().User.Value;
+        static readonly Encoding Utf8 = new UTF8Encoding(false, true);
+        [StructLayout(LayoutKind.Sequential)] struct SecurityAttributes {
+            public int Length; public IntPtr Descriptor;
+            [MarshalAs(UnmanagedType.Bool)] public bool Inherit;
+        }
+        [StructLayout(LayoutKind.Sequential)] struct FileInformation {
+            public uint Attributes; public System.Runtime.InteropServices.ComTypes.FILETIME Creation, Access, Write;
+            public uint Volume, SizeHigh, SizeLow, Links, IndexHigh, IndexLow;
+        }
+        [StructLayout(LayoutKind.Sequential)] struct Disposition {
+            [MarshalAs(UnmanagedType.U1)] public bool Delete;
+        }
+        [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+        static extern SafeFileHandle CreateFileW(string name, uint access, uint share, IntPtr security, uint creation, uint flags, IntPtr template);
+        [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+        static extern bool CreateDirectoryW(string name, ref SecurityAttributes security);
+        [DllImport("kernel32.dll", SetLastError = true)] static extern bool GetFileInformationByHandle(SafeFileHandle file, out FileInformation info);
+        [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+        static extern bool GetVolumeInformationByHandleW(SafeFileHandle file, StringBuilder volume, uint volumeSize, out uint serial, out uint maxLength, out uint flags, StringBuilder filesystem, uint filesystemSize);
+        [DllImport("kernel32.dll", CharSet = CharSet.Unicode)] static extern uint GetDriveTypeW(string root);
+        [DllImport("advapi32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+        static extern bool ConvertStringSecurityDescriptorToSecurityDescriptorW(string sddl, uint revision, out IntPtr descriptor, out uint size);
+        [DllImport("advapi32.dll")] static extern uint GetSecurityInfo(SafeFileHandle file, int type, uint information, out IntPtr owner, out IntPtr group, out IntPtr dacl, out IntPtr sacl, out IntPtr descriptor);
+        [DllImport("advapi32.dll")] static extern uint GetSecurityDescriptorLength(IntPtr descriptor);
+        [DllImport("kernel32.dll")] static extern IntPtr LocalFree(IntPtr value);
+        [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+        static extern bool MoveFileExW(string existing, string replacement, uint flags);
+        [DllImport("kernel32.dll", SetLastError = true)] static extern bool FlushFileBuffers(SafeFileHandle file);
+        [DllImport("kernel32.dll", SetLastError = true)] static extern bool SetFileInformationByHandle(SafeFileHandle file, int type, ref Disposition info, uint size);
+
+        static void Check(bool success) { if (!success) throw new Win32Exception(Marshal.GetLastWin32Error()); }
+        static Exception Unsafe() { return new InvalidOperationException("Unsafe claim filesystem"); }
+        static string Canonical(string value) {
+            if (String.IsNullOrEmpty(value) || value.IndexOf('\0') >= 0 || value.StartsWith(@"\\")) throw Unsafe();
+            string full = Path.GetFullPath(value);
+            string root = Path.GetPathRoot(full);
+            if (root.Length != 3 || !Char.IsLetter(root[0]) || root[1] != ':' || GetDriveTypeW(root) != 3) throw Unsafe();
+            // Reject ADS, Win32 aliases, wildcard paths, and path normalization surprises.
+            foreach (string part in full.Substring(root.Length).Split('\\')) {
+                if (part.Length == 0) continue;
+                if (part.EndsWith(".") || part.EndsWith(" ") || part.IndexOfAny(new char[] { ':', '*', '?', '"', '<', '>', '|' }) >= 0) throw Unsafe();
+                string stem = part.Split('.')[0].ToUpperInvariant();
+                if (stem == "CON" || stem == "PRN" || stem == "AUX" || stem == "NUL" ||
+                    (stem.Length == 4 && (stem.StartsWith("COM") || stem.StartsWith("LPT")) && stem[3] >= '0' && stem[3] <= '9')) throw Unsafe();
+            }
+            return full;
+        }
+        static FileInformation Info(SafeFileHandle handle, bool directory) {
+            FileInformation info;
+            Check(GetFileInformationByHandle(handle, out info));
+            if ((info.Attributes & ReparsePoint) != 0 || ((info.Attributes & DirectoryAttribute) != 0) != directory || (!directory && info.Links != 1)) throw Unsafe();
+            StringBuilder fs = new StringBuilder(32), volume = new StringBuilder(256);
+            uint serial, max, flags;
+            Check(GetVolumeInformationByHandleW(handle, volume, 256, out serial, out max, out flags, fs, 32));
+            if (fs.ToString() != "NTFS" || (flags & 8) == 0) throw Unsafe(); // persistent ACLs
+            return info;
+        }
+        static SafeFileHandle Open(string file, bool directory, uint access, uint share = ShareRead) {
+            SafeFileHandle handle = CreateFileW(file, access | ReadAttributes | ReadControl, share, IntPtr.Zero, OpenExisting, OpenReparsePoint | BackupSemantics, IntPtr.Zero);
+            if (handle.IsInvalid) { int error = Marshal.GetLastWin32Error(); handle.Dispose(); throw new Win32Exception(error); }
+            try { Info(handle, directory); return handle; } catch { handle.Dispose(); throw; }
+        }
+        static void Private(SafeFileHandle file) {
+            IntPtr owner, group, dacl, sacl, descriptor;
+            uint code = GetSecurityInfo(file, 1, 5, out owner, out group, out dacl, out sacl, out descriptor);
+            if (code != 0) throw new Win32Exception((int)code);
+            try {
+                byte[] bytes = new byte[GetSecurityDescriptorLength(descriptor)];
+                Marshal.Copy(descriptor, bytes, 0, bytes.Length);
+                RawSecurityDescriptor security = new RawSecurityDescriptor(bytes, 0);
+                if (security.Owner == null || security.Owner.Value != UserSid || security.DiscretionaryAcl == null ||
+                    (security.ControlFlags & ControlFlags.DiscretionaryAclProtected) == 0 ||
+                    (security.ControlFlags & ControlFlags.DiscretionaryAclPresent) == 0) throw Unsafe();
+                bool user = false;
+                foreach (GenericAce item in security.DiscretionaryAcl) {
+                    CommonAce ace = item as CommonAce;
+                    if (ace == null || ace.AceQualifier != AceQualifier.AccessAllowed || ace.IsCallback ||
+                        (ace.AceFlags & (AceFlags.Inherited | AceFlags.InheritOnly)) != 0 ||
+                        (ace.SecurityIdentifier.Value != UserSid && ace.SecurityIdentifier.Value != "S-1-5-18" && ace.SecurityIdentifier.Value != "S-1-5-32-544")) throw Unsafe();
+                    if (ace.SecurityIdentifier.Value == UserSid && (ace.AccessMask & 0x1f01ff) == 0x1f01ff) user = true;
+                }
+                if (!user) throw Unsafe();
+            } finally { if (descriptor != IntPtr.Zero) LocalFree(descriptor); }
+        }
+        sealed class Chain : IDisposable {
+            readonly List<SafeFileHandle> handles = new List<SafeFileHandle>();
+            public Chain(string file, bool includeLeaf, bool missing) {
+                string root = Path.GetPathRoot(file), current = root;
+                try {
+                    handles.Add(Open(root, true, 0, ShareRead | ShareWrite));
+                    string[] parts = file.Substring(root.Length).Split(new char[] { '\\' }, StringSplitOptions.RemoveEmptyEntries);
+                    for (int i = 0; i < parts.Length; i++) {
+                        current = Path.Combine(current, parts[i]);
+                        if (i == parts.Length - 1 && !includeLeaf) break;
+                        try {
+                            // Holding each ancestor without FILE_SHARE_DELETE pins the path
+                            // throughout native operations instead of merely lstat-ing names.
+                            bool leaf = i == parts.Length - 1;
+                            if (leaf) {
+                                SafeFileHandle h = CreateFileW(current, ReadAttributes | ReadControl, ShareRead | ShareWrite, IntPtr.Zero, OpenExisting, OpenReparsePoint | BackupSemantics, IntPtr.Zero);
+                                if (h.IsInvalid) { int e = Marshal.GetLastWin32Error(); h.Dispose(); throw new Win32Exception(e); }
+                                try { FileInformation info; Check(GetFileInformationByHandle(h, out info)); Info(h, (info.Attributes & DirectoryAttribute) != 0); handles.Add(h); } catch { h.Dispose(); throw; }
+                            } else handles.Add(Open(current, true, 0, ShareRead | ShareWrite));
+                        } catch (Win32Exception e) { if (missing && (e.NativeErrorCode == 2 || e.NativeErrorCode == 3)) break; throw; }
+                    }
+                } catch { Dispose(); throw; }
+            }
+            public void Dispose() { for (int i = handles.Count - 1; i >= 0; i--) handles[i].Dispose(); handles.Clear(); }
+        }
+        static IntPtr Descriptor(bool directory) {
+            string inheritance = directory ? "OICI" : "";
+            string sddl = "O:" + UserSid + "D:P(A;" + inheritance + ";FA;;;" + UserSid + ")(A;" + inheritance + ";FA;;;SY)(A;" + inheritance + ";FA;;;BA)";
+            IntPtr descriptor; uint length;
+            Check(ConvertStringSecurityDescriptorToSecurityDescriptorW(sddl, 1, out descriptor, out length));
+            return descriptor;
+        }
+        static SafeFileHandle Create(string file) {
+            IntPtr descriptor = Descriptor(false), memory = IntPtr.Zero;
+            try {
+                SecurityAttributes security = new SecurityAttributes { Length = Marshal.SizeOf<SecurityAttributes>(), Descriptor = descriptor, Inherit = false };
+                memory = Marshal.AllocHGlobal(security.Length); Marshal.StructureToPtr(security, memory, false);
+                SafeFileHandle handle = CreateFileW(file, GenericRead | GenericWrite | ReadControl | DeleteAccess, 0, memory, CreateNew, OpenReparsePoint | BackupSemantics, IntPtr.Zero);
+                if (handle.IsInvalid) { int e = Marshal.GetLastWin32Error(); handle.Dispose(); throw new Win32Exception(e); }
+                try { Info(handle, false); Private(handle); return handle; } catch { handle.Dispose(); throw; }
+            } finally { if (memory != IntPtr.Zero) Marshal.FreeHGlobal(memory); LocalFree(descriptor); }
+        }
+        static void Write(string file, byte[] content) {
+            using (SafeFileHandle handle = Create(file))
+            using (FileStream stream = new FileStream(handle, FileAccess.ReadWrite)) {
+                stream.Write(content, 0, content.Length); stream.Flush(true); Check(FlushFileBuffers(handle));
+            }
+        }
+        static string Read(SafeFileHandle handle) {
+            FileInformation info = Info(handle, false); Private(handle);
+            if (info.SizeHigh != 0 || info.SizeLow > Limit) throw Unsafe();
+            using (FileStream stream = new FileStream(handle, FileAccess.Read)) {
+                byte[] data = new byte[Limit + 1]; int count = 0, n;
+                while (count < data.Length && (n = stream.Read(data, count, data.Length - count)) != 0) count += n;
+                if (count > Limit) throw Unsafe();
+                Info(handle, false); return Utf8.GetString(data, 0, count);
+            }
+        }
+        static void Remove(SafeFileHandle handle) {
+            Disposition info = new Disposition { Delete = true };
+            Check(SetFileInformationByHandle(handle, 4, ref info, (uint)Marshal.SizeOf<Disposition>()));
+        }
+        static void ParentPrivate(string file) { using (SafeFileHandle parent = Open(Path.GetDirectoryName(file), true, 0, ShareRead | ShareWrite)) Private(parent); }
+        static Dictionary<string, object> Success() { return new Dictionary<string, object> { { "ok", true } }; }
+        public static Dictionary<string, object> Execute(string command, string file, bool allowMissing, string content, string expected) {
+            try {
+                file = Canonical(file);
+                Dictionary<string, object> result = Success();
+                if (command == "safe-path") { using (new Chain(file, true, allowMissing)) { } return result; }
+                using (new Chain(file, false, false)) {
+                    if (command == "ensure-directory") {
+                        IntPtr descriptor = Descriptor(true);
+                        try {
+                            SecurityAttributes security = new SecurityAttributes { Length = Marshal.SizeOf<SecurityAttributes>(), Descriptor = descriptor };
+                            if (!CreateDirectoryW(file, ref security)) { int e = Marshal.GetLastWin32Error(); if (e != 183) throw new Win32Exception(e); }
+                        } finally { LocalFree(descriptor); }
+                    }
+                    if (command == "directory" || command == "ensure-directory") {
+                        try { using (SafeFileHandle h = Open(file, true, 0, ShareRead | ShareWrite)) Private(h); result["exists"] = true; }
+                        catch (Win32Exception e) { if (!allowMissing || (e.NativeErrorCode != 2 && e.NativeErrorCode != 3)) throw; result["exists"] = false; }
+                        return result;
+                    }
+                    ParentPrivate(file);
+                    if (command == "read") { using (SafeFileHandle h = Open(file, false, GenericRead)) result["content"] = Read(h); return result; }
+                    if (command == "delete" || command == "release-lock") {
+                        using (SafeFileHandle h = Open(file, false, GenericRead | DeleteAccess)) {
+                            Private(h);
+                            if (command == "release-lock") {
+                                // Read through a non-owning SafeFileHandle so the delete handle stays live.
+                                using (SafeFileHandle borrowed = new SafeFileHandle(h.DangerousGetHandle(), false)) {
+                                    if (Read(borrowed) != expected) throw Unsafe();
+                                }
+                            }
+                            Remove(h);
+                        }
+                        return result;
+                    }
+                    byte[] bytes = Utf8.GetBytes(content);
+                    if (bytes.Length > Limit) throw Unsafe();
+                    if (command == "create") { Write(file, bytes); return result; }
+                    if (command != "replace") throw Unsafe();
+                    using (SafeFileHandle h = Open(file, false, GenericRead)) Private(h);
+                    string temp = file + "." + Guid.NewGuid().ToString("N") + ".tmp";
+                    bool created = false;
+                    try {
+                        Write(temp, bytes); created = true;
+                        using (SafeFileHandle h = Open(file, false, GenericRead)) Private(h);
+                        // No COPY_ALLOWED: same-directory local-NTFS replacement only.
+                        // Both files are flushed first. Failure is never acknowledged.
+                        Check(MoveFileExW(temp, file, 1 | 8)); created = false;
+                        using (SafeFileHandle h = Open(file, false, GenericRead)) { if (Read(h) != content) throw Unsafe(); }
+                    } finally {
+                        if (created) {
+                            using (SafeFileHandle h = Open(temp, false, DeleteAccess)) { Private(h); Remove(h); }
+                        }
+                    }
+                    return result;
+                }
+            } catch (Win32Exception e) {
+                return new Dictionary<string, object> { { "ok", false }, { "code", e.NativeErrorCode == 80 || e.NativeErrorCode == 183 ? "EEXIST" : e.NativeErrorCode == 2 || e.NativeErrorCode == 3 ? "ENOENT" : "EUNSAFE" } };
+            } catch { return new Dictionary<string, object> { { "ok", false }, { "code", "EUNSAFE" } }; }
+        }
+    }
+}

package/vona/packages-vona/vona-core/src/lib/core/testClaimFilesystemWindows.ps1

@@ -0,0 +1,20 @@
+#requires -Version 7.0
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
+[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+try {
+  if (-not $IsWindows) { throw 'Windows is required' }
+  Add-Type -Path (Join-Path $PSScriptRoot 'testClaimFilesystemWindows.cs')
+  while ($null -ne ($line = [Console]::In.ReadLine())) {
+    $request = $line | ConvertFrom-Json -AsHashtable
+    $result = [Cabloy.TestClaimFilesystem]::Execute(
+      [string]$request.command, [string]$request.path, [bool]$request.allowMissing,
+      [string]$request.content, [string]$request.expected)
+    [Console]::Out.WriteLine(($result | ConvertTo-Json -Compress))
+    [Console]::Out.Flush()
+  }
+} catch {
+  # Never copy request contents, paths, or native error diagnostics into logs.
+  [Console]::Out.WriteLine('{"ok":false,"code":"EUNSAFE"}')
+}

package/vona/packages-vona/vona-core/src/lib/core/testClaimFilesystemWindows.ts

@@ -0,0 +1,200 @@
+import type { ChildProcess } from 'node:child_process';
+
+import { execFile, execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export interface WindowsTestClaimFilesystemRequest {
+  command:
+    | 'safe-path'
+    | 'directory'
+    | 'ensure-directory'
+    | 'read'
+    | 'create'
+    | 'replace'
+    | 'delete'
+    | 'release-lock';
+  path: string;
+  allowMissing?: boolean;
+  content?: string;
+  expected?: string;
+}
+
+// Both source and bundled dist consumers use the checked-in, published src assets.
+export function getWindowsTestClaimFilesystemHelper(
+  directory = import.meta.dirname ?? path.dirname(fileURLToPath(import.meta.url)),
+) {
+  let current = directory;
+  while (true) {
+    const manifest = path.join(current, 'package.json');
+    if (existsSync(manifest)) {
+      const value = JSON.parse(readFileSync(manifest, 'utf8'));
+      if (value.name === 'vona-core') {
+        const helper = path.join(current, 'src/lib/core/testClaimFilesystemWindows.ps1');
+        if (!existsSync(helper) || !existsSync(helper.replace(/\.ps1$/, '.cs')))
+          throw new Error('Windows test claim filesystem helper assets are missing');
+        return helper;
+      }
+    }
+    const parent = path.dirname(current);
+    if (parent === current)
+      throw new Error('Cannot locate the vona-core Windows filesystem helper');
+    current = parent;
+  }
+}
+
+function invocation() {
+  if (process.platform !== 'win32') throw new Error('Windows claim filesystem requires Windows');
+  return [
+    '-NoLogo',
+    '-NoProfile',
+    '-NonInteractive',
+    '-File',
+    getWindowsTestClaimFilesystemHelper(),
+  ];
+}
+function decode(source: string): { exists?: boolean; content?: string } {
+  let value;
+  try {
+    value = JSON.parse(source);
+  } catch {
+    throw new Error('Windows test claim filesystem helper returned an invalid response');
+  }
+  if (!value || value.ok !== true) {
+    const error = new Error(
+      value?.code === 'EEXIST'
+        ? 'Test claim file already exists'
+        : `Unsafe Windows test claim filesystem operation (${value?.code ?? 'unknown'})`,
+    );
+    Object.assign(error, { code: value?.code ?? 'EUNSAFE' });
+    throw error;
+  }
+  return value;
+}
+
+export function windowsTestClaimFilesystemSync(request: WindowsTestClaimFilesystemRequest) {
+  try {
+    return decode(
+      execFileSync('pwsh', invocation(), {
+        input: JSON.stringify(request),
+        encoding: 'utf8',
+        windowsHide: true,
+        timeout: 30000,
+        maxBuffer: 8 * 1024 * 1024,
+      }),
+    );
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT')
+      throw new Error('Native Windows test claims require PowerShell 7 (pwsh) on PATH');
+    throw error;
+  }
+}
+
+type Response = { exists?: boolean; content?: string };
+type Pending = {
+  resolve: (value: Response) => void;
+  reject: (error: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+};
+let bridge:
+  | {
+      child: ChildProcess;
+      pending: Pending[];
+      output: string;
+      idle?: ReturnType<typeof setTimeout>;
+    }
+  | undefined;
+
+export function windowsTestClaimFilesystem(
+  request: WindowsTestClaimFilesystemRequest,
+): Promise<Response> {
+  if (!bridge) {
+    // Explicit executable + argv, never a shell. A burst shares Add-Type startup;
+    // the bridge owns no persistent native handles and exits when idle.
+    const child = execFile('pwsh', invocation(), { windowsHide: true, maxBuffer: Infinity });
+    // execFile's collection listeners are for its callback API. This bounded
+    // line protocol consumes the streams itself, without retaining burst history.
+    child.stdout?.removeAllListeners('data');
+    child.stderr?.removeAllListeners('data');
+    const state = {
+      child,
+      pending: [] as Pending[],
+      output: '',
+      idle: undefined as ReturnType<typeof setTimeout> | undefined,
+    };
+    bridge = state;
+    const fail = (error: Error) => {
+      if (bridge === state) bridge = undefined;
+      clearTimeout(state.idle);
+      for (const operation of state.pending.splice(0)) {
+        clearTimeout(operation.timer);
+        operation.reject(error);
+      }
+      child.stdin?.destroy();
+      child.kill();
+    };
+    child.once('error', error =>
+      fail(
+        new Error(
+          (error as NodeJS.ErrnoException).code === 'ENOENT'
+            ? 'Native Windows test claims require PowerShell 7 (pwsh) on PATH'
+            : 'Windows test claim filesystem helper failed; operation not acknowledged',
+        ),
+      ),
+    );
+    child.once('exit', () =>
+      fail(new Error('Windows test claim filesystem helper exited; operation not acknowledged')),
+    );
+    child.stdin?.on('error', () =>
+      fail(new Error('Windows test claim filesystem control stream failed')),
+    );
+    child.stdout?.setEncoding('utf8');
+    child.stderr?.resume();
+    child.stdout?.on('data', (chunk: string) => {
+      state.output += chunk;
+      if (Buffer.byteLength(state.output) > 8 * 1024 * 1024) {
+        fail(new Error('Windows test claim filesystem response exceeded limit'));
+        return;
+      }
+      while (state.output.includes('\n')) {
+        const end = state.output.indexOf('\n');
+        const line = state.output.slice(0, end);
+        state.output = state.output.slice(end + 1);
+        const operation = state.pending.shift();
+        if (!operation) {
+          fail(new Error('Unexpected Windows test claim filesystem response'));
+          return;
+        }
+        clearTimeout(operation.timer);
+        try {
+          operation.resolve(decode(line));
+        } catch (error) {
+          operation.reject(error as Error);
+        }
+      }
+      if (!state.pending.length) {
+        state.idle = setTimeout(() => {
+          if (bridge === state) bridge = undefined;
+          child.stdin?.end();
+        }, 1000);
+      }
+    });
+  }
+  const state = bridge;
+  clearTimeout(state.idle);
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      if (bridge === state) bridge = undefined;
+      for (const operation of state.pending.splice(0)) {
+        clearTimeout(operation.timer);
+        operation.reject(
+          new Error('Windows test claim filesystem operation timed out; not acknowledged'),
+        );
+      }
+      state.child.kill();
+    }, 30000);
+    state.pending.push({ resolve, reject, timer });
+    state.child.stdin?.write(`${JSON.stringify(request)}\n`);
+  });
+}