@robota-sdk/agent-file-authority 3.0.0-beta.81

package/src/windows-native-api.ts

@@ -0,0 +1,234 @@
+import * as koffi from 'koffi';
+
+export type TNativeHandle = bigint | null;
+
+export interface IWindowsAttributeTagInfo {
+  FileAttributes?: number;
+  ReparseTag?: number;
+}
+
+export interface IWindowsFileIdInfo {
+  VolumeSerialNumber?: bigint | number;
+  FileId?: Uint8Array | number[];
+}
+
+export interface IWindowsStandardInfo {
+  Directory?: number;
+}
+
+export interface IWindowsObjectAttributes {
+  Length: number;
+  RootDirectory: TNativeHandle;
+  ObjectName: object;
+  Attributes: number;
+  SecurityDescriptor: null;
+  SecurityQualityOfService: null;
+}
+
+export interface IWindowsIoStatus {
+  Status: number;
+  Information: number;
+}
+
+type TCreateFileW = (
+  path: string,
+  desiredAccess: number,
+  shareMode: number,
+  securityAttributes: null,
+  creationDisposition: number,
+  flagsAndAttributes: number,
+  templateFile: TNativeHandle,
+) => TNativeHandle;
+
+type TGetInformation = (
+  handle: TNativeHandle,
+  informationClass: number,
+  output: object,
+  outputBytes: number,
+) => boolean;
+
+type TNtCreateFile = (
+  output: TNativeHandle[],
+  desiredAccess: number,
+  objectAttributes: IWindowsObjectAttributes,
+  ioStatus: IWindowsIoStatus,
+  allocationSize: null,
+  fileAttributes: number,
+  shareAccess: number,
+  createDisposition: number,
+  createOptions: number,
+  extendedAttributes: null,
+  extendedAttributesBytes: number,
+) => number;
+
+export interface IWindowsApi {
+  readonly handleType: koffi.TypeObject;
+  readonly unicodeStringType: koffi.TypeObject;
+  readonly objectAttributesType: koffi.TypeObject;
+  readonly attributeTagInfoType: koffi.TypeObject;
+  readonly fileIdInfoType: koffi.TypeObject;
+  readonly standardInfoType: koffi.TypeObject;
+  readonly createFileW: TCreateFileW;
+  readonly closeHandle: (handle: TNativeHandle) => boolean;
+  readonly getAttributeTagInfo: TGetInformation;
+  readonly getFileIdInfo: TGetInformation;
+  readonly getStandardInfo: TGetInformation;
+  readonly getFileSizeEx: (handle: TNativeHandle, size: bigint[]) => boolean;
+  readonly readFile: (
+    handle: TNativeHandle,
+    buffer: Uint8Array,
+    bytesToRead: number,
+    bytesRead: number[],
+    overlapped: null,
+  ) => boolean;
+  readonly getLastError: () => number;
+  readonly ntCreateFile: TNtCreateFile;
+  readonly ntClose: (handle: TNativeHandle) => number;
+}
+
+interface IWindowsTypes {
+  readonly handleType: koffi.TypeObject;
+  readonly unicodeStringType: koffi.TypeObject;
+  readonly objectAttributesType: koffi.TypeObject;
+  readonly ioStatusBlockType: koffi.TypeObject;
+  readonly attributeTagInfoType: koffi.TypeObject;
+  readonly fileIdInfoType: koffi.TypeObject;
+  readonly standardInfoType: koffi.TypeObject;
+}
+
+const FILE_ID_BYTES = 16;
+
+function defineWindowsTypes(): IWindowsTypes {
+  const handleType = koffi.pointer('RobotaStableFileHandle', koffi.opaque());
+  const unicodeStringType = koffi.struct('RobotaUnicodeString', {
+    Length: 'uint16_t',
+    MaximumLength: 'uint16_t',
+    Buffer: koffi.pointer('char16_t'),
+  });
+  const objectAttributesType = koffi.struct('RobotaObjectAttributes', {
+    Length: 'uint32_t',
+    RootDirectory: handleType,
+    ObjectName: koffi.pointer(unicodeStringType),
+    Attributes: 'uint32_t',
+    SecurityDescriptor: 'void *',
+    SecurityQualityOfService: 'void *',
+  });
+  return {
+    handleType,
+    unicodeStringType,
+    objectAttributesType,
+    ioStatusBlockType: koffi.struct('RobotaIoStatusBlock', {
+      Status: 'intptr_t',
+      Information: 'uintptr_t',
+    }),
+    attributeTagInfoType: koffi.struct('RobotaFileAttributeTagInfo', {
+      FileAttributes: 'uint32_t',
+      ReparseTag: 'uint32_t',
+    }),
+    fileIdInfoType: koffi.struct('RobotaFileIdInfo', {
+      VolumeSerialNumber: 'uint64_t',
+      FileId: koffi.array('uint8_t', FILE_ID_BYTES, 'Typed'),
+    }),
+    standardInfoType: koffi.struct('RobotaFileStandardInfo', {
+      AllocationSize: 'int64_t',
+      EndOfFile: 'int64_t',
+      NumberOfLinks: 'uint32_t',
+      DeletePending: 'uint8_t',
+      Directory: 'uint8_t',
+    }),
+  };
+}
+
+function bindKernel32(
+  library: koffi.LibraryHandle,
+  types: IWindowsTypes,
+): Pick<
+  IWindowsApi,
+  | 'createFileW'
+  | 'closeHandle'
+  | 'getAttributeTagInfo'
+  | 'getFileIdInfo'
+  | 'getStandardInfo'
+  | 'getFileSizeEx'
+  | 'readFile'
+  | 'getLastError'
+> {
+  return {
+    createFileW: library.func('CreateFileW', types.handleType, [
+      koffi.pointer('char16_t'),
+      'uint32_t',
+      'uint32_t',
+      'void *',
+      'uint32_t',
+      'uint32_t',
+      types.handleType,
+    ]) as TCreateFileW,
+    closeHandle: library.func('CloseHandle', 'bool', [types.handleType]),
+    ...bindInformationFunctions(library, types),
+    getFileSizeEx: library.func('GetFileSizeEx', 'bool', [
+      types.handleType,
+      koffi.out(koffi.pointer('int64_t')),
+    ]),
+    readFile: library.func('ReadFile', 'bool', [
+      types.handleType,
+      koffi.out(koffi.pointer('uint8_t')),
+      'uint32_t',
+      koffi.out(koffi.pointer('uint32_t')),
+      'void *',
+    ]),
+    getLastError: library.func('GetLastError', 'uint32_t', []),
+  };
+}
+
+function bindInformationFunctions(
+  library: koffi.LibraryHandle,
+  types: IWindowsTypes,
+): Pick<IWindowsApi, 'getAttributeTagInfo' | 'getFileIdInfo' | 'getStandardInfo'> {
+  const bind = (outputType: koffi.TypeObject): TGetInformation =>
+    library.func('GetFileInformationByHandleEx', 'bool', [
+      types.handleType,
+      'int32_t',
+      koffi.out(koffi.pointer(outputType)),
+      'uint32_t',
+    ]) as TGetInformation;
+  return {
+    getAttributeTagInfo: bind(types.attributeTagInfoType),
+    getFileIdInfo: bind(types.fileIdInfoType),
+    getStandardInfo: bind(types.standardInfoType),
+  };
+}
+
+function bindNtDll(
+  library: koffi.LibraryHandle,
+  types: IWindowsTypes,
+): Pick<IWindowsApi, 'ntCreateFile' | 'ntClose'> {
+  return {
+    ntCreateFile: library.func('NtCreateFile', 'int32_t', [
+      koffi.out(koffi.pointer(types.handleType)),
+      'uint32_t',
+      koffi.pointer(types.objectAttributesType),
+      koffi.out(koffi.pointer(types.ioStatusBlockType)),
+      'void *',
+      'uint32_t',
+      'uint32_t',
+      'uint32_t',
+      'uint32_t',
+      'void *',
+      'uint32_t',
+    ]) as TNtCreateFile,
+    ntClose: library.func('NtClose', 'int32_t', [types.handleType]),
+  };
+}
+
+let cachedApi: IWindowsApi | undefined;
+
+export function getWindowsApi(): IWindowsApi {
+  if (cachedApi !== undefined) return cachedApi;
+  const types = defineWindowsTypes();
+  cachedApi = {
+    ...types,
+    ...bindKernel32(koffi.load('kernel32.dll'), types),
+    ...bindNtDll(koffi.load('ntdll.dll'), types),
+  };
+  return cachedApi;
+}

package/src/windows-native-authority.ts

@@ -0,0 +1,227 @@
+import * as koffi from 'koffi';
+
+import { authorityError } from './contracts.js';
+import {
+  getWindowsApi,
+  type IWindowsApi,
+  type IWindowsAttributeTagInfo,
+  type IWindowsIoStatus,
+  type IWindowsObjectAttributes,
+  type IWindowsStandardInfo,
+  type TNativeHandle,
+} from './windows-native-api.js';
+import {
+  queryWindowsIdentity,
+  readWindowsFile,
+  windowsLastErrorCode,
+  type IWindowsIdentity,
+} from './windows-native-read.js';
+import { classifyNtOpenFailure } from './windows-native-status.js';
+
+import type { IFileAuthorityTestHooks } from './host-backend.js';
+
+export type { IWindowsIdentity } from './windows-native-read.js';
+
+const GENERIC_READ = 0x80000000;
+const FILE_READ_DATA = 0x0001;
+const FILE_LIST_DIRECTORY = 0x0001;
+const FILE_READ_ATTRIBUTES = 0x0080;
+const SYNCHRONIZE = 0x00100000;
+const FILE_SHARE_READ = 0x00000001;
+const FILE_SHARE_WRITE = 0x00000002;
+const FILE_SHARE_DELETE = 0x00000004;
+const OPEN_EXISTING = 3;
+const FILE_ATTRIBUTE_REPARSE_POINT = 0x00000400;
+const FILE_FLAG_OPEN_REPARSE_POINT = 0x00200000;
+const FILE_FLAG_BACKUP_SEMANTICS = 0x02000000;
+const FILE_OPEN = 1;
+const FILE_DIRECTORY_FILE = 0x00000001;
+const FILE_SYNCHRONOUS_IO_NONALERT = 0x00000020;
+const FILE_NON_DIRECTORY_FILE = 0x00000040;
+const FILE_OPEN_REPARSE_POINT = 0x00200000;
+const OBJ_CASE_INSENSITIVE = 0x00000040;
+const OBJ_DONT_REPARSE = 0x00001000;
+const FILE_STANDARD_INFO_CLASS = 1;
+const FILE_ATTRIBUTE_TAG_INFO_CLASS = 9;
+const HANDLE_WIDTH_BITS = 64;
+const INVALID_HANDLE_VALUE = BigInt('-1');
+
+function isInvalidHandle(handle: TNativeHandle): boolean {
+  return handle === null || BigInt.asIntN(HANDLE_WIDTH_BITS, handle) === INVALID_HANDLE_VALUE;
+}
+
+/** Raw Windows handle operations. Native HANDLE and Koffi values stay inside this module. */
+export class WindowsNativeAuthority {
+  private readonly api: IWindowsApi;
+
+  constructor() {
+    try {
+      this.api = getWindowsApi();
+    } catch {
+      throw authorityError('UNSUPPORTED_BACKEND', 'load-windows-backend');
+    }
+  }
+
+  openRoot(rootDirectory: string): TNativeHandle {
+    const handle = this.api.createFileW(
+      rootDirectory,
+      GENERIC_READ,
+      FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE,
+      null,
+      OPEN_EXISTING,
+      FILE_FLAG_BACKUP_SEMANTICS | FILE_FLAG_OPEN_REPARSE_POINT,
+      null,
+    );
+    if (isInvalidHandle(handle)) {
+      throw authorityError('HOST_IO', 'open-root', { hostCode: this.lastErrorCode() });
+    }
+    try {
+      this.assertSafeHandle(handle, true, 'inspect-root');
+      return handle;
+    } catch (error) {
+      this.close(handle);
+      throw error;
+    }
+  }
+
+  openRelative(
+    parentHandle: TNativeHandle,
+    segment: string,
+    final: boolean,
+    segmentIndex: number,
+  ): TNativeHandle | undefined {
+    const { handle, status } = this.issueRelativeOpen(parentHandle, segment, final);
+    if (status >= 0) {
+      if (isInvalidHandle(handle)) throw authorityError('HOST_IO', 'open-relative');
+      try {
+        this.assertSafeHandle(
+          handle,
+          !final,
+          final ? 'inspect-file' : 'inspect-directory',
+          segmentIndex,
+        );
+        return handle;
+      } catch (error) {
+        this.close(handle);
+        throw error;
+      }
+    }
+    if (!isInvalidHandle(handle)) this.close(handle);
+    const failure = classifyNtOpenFailure(status);
+    if (failure.kind === 'missing') return undefined;
+    const details = { segmentIndex, hostCode: failure.hostCode };
+    if (failure.kind === 'unsafe') {
+      throw authorityError('UNSAFE_ENTRY', final ? 'open-file' : 'open-directory', details);
+    }
+    throw authorityError('HOST_IO', final ? 'open-file' : 'open-directory', details);
+  }
+
+  readFile(handle: TNativeHandle, maxBytes: number, hooks: IFileAuthorityTestHooks): Uint8Array {
+    return readWindowsFile(this.api, handle, maxBytes, hooks);
+  }
+
+  queryIdentity(handle: TNativeHandle, operation: string): IWindowsIdentity {
+    return queryWindowsIdentity(this.api, handle, operation);
+  }
+
+  close(handle: TNativeHandle): void {
+    try {
+      if (this.api.ntClose(handle) >= 0) return;
+    } catch {
+      // allow-fallback: CloseHandle is the native cleanup fallback after NtClose itself throws
+    }
+    try {
+      this.api.closeHandle(handle);
+    } catch {
+      // allow-fallback: close failure cannot restore authority or make a later read safe
+    }
+  }
+
+  private issueRelativeOpen(
+    parentHandle: TNativeHandle,
+    segment: string,
+    final: boolean,
+  ): { handle: TNativeHandle; status: number } {
+    const unicodeName = koffi.alloc(this.api.unicodeStringType, 1);
+    try {
+      koffi.encode(unicodeName, this.api.unicodeStringType, {
+        Length: Buffer.byteLength(segment, 'utf16le'),
+        MaximumLength: Buffer.byteLength(`${segment}\0`, 'utf16le'),
+        Buffer: segment,
+      });
+      const attributes: IWindowsObjectAttributes = {
+        Length: koffi.sizeof(this.api.objectAttributesType),
+        RootDirectory: parentHandle,
+        ObjectName: unicodeName,
+        Attributes: OBJ_CASE_INSENSITIVE | OBJ_DONT_REPARSE,
+        SecurityDescriptor: null,
+        SecurityQualityOfService: null,
+      };
+      const output: TNativeHandle[] = [null];
+      const ioStatus: IWindowsIoStatus = { Status: 0, Information: 0 };
+      // A final read cannot verify same-size in-place rewrites from identity and size alone.
+      // Deny write sharing for that handle so existing and new writers cannot race the read.
+      const shareAccess = final
+        ? FILE_SHARE_READ | FILE_SHARE_DELETE
+        : FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE;
+      const status = this.api.ntCreateFile(
+        output,
+        (final ? FILE_READ_DATA : FILE_LIST_DIRECTORY) | FILE_READ_ATTRIBUTES | SYNCHRONIZE,
+        attributes,
+        ioStatus,
+        null,
+        0,
+        shareAccess,
+        FILE_OPEN,
+        (final ? FILE_NON_DIRECTORY_FILE : FILE_DIRECTORY_FILE) |
+          FILE_SYNCHRONOUS_IO_NONALERT |
+          FILE_OPEN_REPARSE_POINT,
+        null,
+        0,
+      );
+      return { handle: output[0], status };
+    } finally {
+      koffi.free(unicodeName);
+    }
+  }
+
+  private assertSafeHandle(
+    handle: TNativeHandle,
+    directory: boolean,
+    operation: string,
+    segmentIndex?: number,
+  ): void {
+    const attributes: IWindowsAttributeTagInfo = {};
+    const standard: IWindowsStandardInfo = {};
+    if (
+      !this.api.getAttributeTagInfo(
+        handle,
+        FILE_ATTRIBUTE_TAG_INFO_CLASS,
+        attributes,
+        koffi.sizeof(this.api.attributeTagInfoType),
+      ) ||
+      !this.api.getStandardInfo(
+        handle,
+        FILE_STANDARD_INFO_CLASS,
+        standard,
+        koffi.sizeof(this.api.standardInfoType),
+      )
+    ) {
+      throw authorityError('HOST_IO', operation, { hostCode: this.lastErrorCode() });
+    }
+    const unsafe =
+      ((attributes.FileAttributes ?? 0) & FILE_ATTRIBUTE_REPARSE_POINT) !== 0 ||
+      Boolean(standard.Directory) !== directory;
+    if (unsafe) {
+      throw authorityError(
+        'UNSAFE_ENTRY',
+        operation,
+        segmentIndex === undefined ? {} : { segmentIndex },
+      );
+    }
+  }
+
+  private lastErrorCode(): string {
+    return windowsLastErrorCode(this.api);
+  }
+}

package/src/windows-native-read.ts

@@ -0,0 +1,122 @@
+import * as koffi from 'koffi';
+
+import { authorityError } from './contracts.js';
+
+import type { IFileAuthorityTestHooks } from './host-backend.js';
+import type { IWindowsApi, IWindowsFileIdInfo, TNativeHandle } from './windows-native-api.js';
+
+export interface IWindowsIdentity {
+  readonly volume: bigint;
+  readonly fileId: string;
+}
+
+interface IWindowsFileSnapshot extends IWindowsIdentity {
+  readonly size: bigint;
+}
+
+const FILE_ID_INFO_CLASS = 18;
+const CHUNK_BYTES = 1_048_576;
+const ZERO_SIZE = BigInt('0');
+
+function bytesToHex(value: Uint8Array | number[] | undefined): string {
+  if (value instanceof Uint8Array) return Buffer.from(value).toString('hex');
+  if (Array.isArray(value)) return Buffer.from(value).toString('hex');
+  throw authorityError('UNSUPPORTED_BACKEND', 'decode-file-identity');
+}
+
+export function windowsLastErrorCode(api: IWindowsApi): string {
+  return `WIN32_${api.getLastError()}`;
+}
+
+export function queryWindowsIdentity(
+  api: IWindowsApi,
+  handle: TNativeHandle,
+  operation: string,
+): IWindowsIdentity {
+  const info: IWindowsFileIdInfo = {};
+  if (!api.getFileIdInfo(handle, FILE_ID_INFO_CLASS, info, koffi.sizeof(api.fileIdInfoType))) {
+    throw authorityError('UNSUPPORTED_BACKEND', operation, {
+      hostCode: windowsLastErrorCode(api),
+    });
+  }
+  return {
+    volume: BigInt(info.VolumeSerialNumber ?? ZERO_SIZE),
+    fileId: bytesToHex(info.FileId),
+  };
+}
+
+export function readWindowsFile(
+  api: IWindowsApi,
+  handle: TNativeHandle,
+  maxBytes: number,
+  hooks: IFileAuthorityTestHooks,
+): Uint8Array {
+  const before = queryFileSnapshot(api, handle);
+  if (before.size > BigInt(maxBytes)) throw authorityError('OVER_BUDGET', 'read-file');
+  const expectedBytes = Number(before.size);
+  let bytes: Buffer;
+  try {
+    bytes = Buffer.alloc(expectedBytes);
+  } catch {
+    throw authorityError('HOST_IO', 'allocate-read-buffer');
+  }
+
+  const offset = readExpectedBytes(api, handle, bytes, hooks);
+  const probeCount = [0];
+  if (!api.readFile(handle, Buffer.alloc(1), 1, probeCount, null)) {
+    throw authorityError('HOST_IO', 'probe-file', { hostCode: windowsLastErrorCode(api) });
+  }
+  const after = queryFileSnapshot(api, handle);
+  if (probeCount[0] !== 0 && expectedBytes >= maxBytes) {
+    throw authorityError('OVER_BUDGET', 'read-file');
+  }
+  if (!isStableRead(before, after, offset, expectedBytes, probeCount[0])) {
+    throw authorityError('FILE_CHANGED', 'read-file');
+  }
+  return bytes;
+}
+
+function readExpectedBytes(
+  api: IWindowsApi,
+  handle: TNativeHandle,
+  bytes: Buffer,
+  hooks: IFileAuthorityTestHooks,
+): number {
+  let offset = 0;
+  while (offset < bytes.length) {
+    const length = Math.min(CHUNK_BYTES, bytes.length - offset);
+    const count = [0];
+    if (!api.readFile(handle, bytes.subarray(offset, offset + length), length, count, null)) {
+      throw authorityError('HOST_IO', 'read-file', { hostCode: windowsLastErrorCode(api) });
+    }
+    if (count[0] === 0) break;
+    offset += count[0];
+    hooks.afterReadChunk?.(offset);
+  }
+  return offset;
+}
+
+function queryFileSnapshot(api: IWindowsApi, handle: TNativeHandle): IWindowsFileSnapshot {
+  const identity = queryWindowsIdentity(api, handle, 'inspect-file');
+  const size = [ZERO_SIZE];
+  if (!api.getFileSizeEx(handle, size)) {
+    throw authorityError('HOST_IO', 'inspect-file', { hostCode: windowsLastErrorCode(api) });
+  }
+  return { ...identity, size: BigInt(size[0]) };
+}
+
+function isStableRead(
+  before: IWindowsFileSnapshot,
+  after: IWindowsFileSnapshot,
+  actualBytes: number,
+  expectedBytes: number,
+  probeBytes: number,
+): boolean {
+  return (
+    actualBytes === expectedBytes &&
+    probeBytes === 0 &&
+    before.volume === after.volume &&
+    before.fileId === after.fileId &&
+    before.size === after.size
+  );
+}

package/src/windows-native-status.ts

@@ -0,0 +1,41 @@
+type TNtOpenFailureKind = 'missing' | 'unsafe' | 'host-io';
+
+export interface INtOpenFailure {
+  readonly kind: TNtOpenFailureKind;
+  readonly hostCode: string;
+}
+
+const HEX_RADIX = 16;
+const STATUS_NO_SUCH_FILE = 0xc000000f;
+const STATUS_OBJECT_NAME_NOT_FOUND = 0xc0000034;
+const STATUS_OBJECT_PATH_NOT_FOUND = 0xc000003a;
+const STATUS_STOPPED_ON_SYMLINK = 0x8000002d;
+const STATUS_FILE_IS_A_DIRECTORY = 0xc00000ba;
+const STATUS_NOT_A_DIRECTORY = 0xc0000103;
+const STATUS_REPARSE_POINT_ENCOUNTERED = 0xc0000279;
+const STATUS_IO_REPARSE_TAG_NOT_HANDLED = 0xc000050b;
+
+const MISSING_STATUSES = new Set([
+  STATUS_NO_SUCH_FILE,
+  STATUS_OBJECT_NAME_NOT_FOUND,
+  STATUS_OBJECT_PATH_NOT_FOUND,
+]);
+const UNSAFE_STATUSES = new Set([
+  STATUS_STOPPED_ON_SYMLINK,
+  STATUS_FILE_IS_A_DIRECTORY,
+  STATUS_NOT_A_DIRECTORY,
+  STATUS_REPARSE_POINT_ENCOUNTERED,
+  STATUS_IO_REPARSE_TAG_NOT_HANDLED,
+]);
+
+export function classifyNtOpenFailure(status: number): INtOpenFailure {
+  const normalized = status >>> 0;
+  return {
+    kind: MISSING_STATUSES.has(normalized)
+      ? 'missing'
+      : UNSAFE_STATUSES.has(normalized)
+        ? 'unsafe'
+        : 'host-io',
+    hostCode: `NTSTATUS_0x${normalized.toString(HEX_RADIX)}`,
+  };
+}