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

package/src/__tests__/windows-native-authority.test.ts

@@ -0,0 +1,113 @@
+import * as koffi from 'koffi';
+import { describe, expect, it, vi } from 'vitest';
+
+import { WindowsNativeAuthority } from '../windows-native-authority.js';
+
+import type { TNativeHandle } from '../windows-native-api.js';
+
+function uninitializedAuthority(): WindowsNativeAuthority {
+  return Object.create(WindowsNativeAuthority.prototype) as WindowsNativeAuthority;
+}
+
+describe('WindowsNativeAuthority cleanup', () => {
+  it('closes a successfully opened handle when safety inspection rejects it', () => {
+    const authority = uninitializedAuthority();
+    const handle = BigInt(42);
+    const close = vi.fn<(value: TNativeHandle) => void>();
+    Reflect.set(authority, 'issueRelativeOpen', () => ({ handle, status: 0 }));
+    Reflect.set(authority, 'assertSafeHandle', () => {
+      throw new Error('unsafe handle');
+    });
+    Reflect.set(authority, 'close', close);
+
+    expect(() => authority.openRelative(BigInt(1), 'payload.bin', true, 0)).toThrow(
+      'unsafe handle',
+    );
+    expect(close).toHaveBeenCalledExactlyOnceWith(handle);
+  });
+
+  it('closes a returned handle when NtCreateFile reports failure', () => {
+    const authority = uninitializedAuthority();
+    const handle = BigInt(42);
+    const close = vi.fn<(value: TNativeHandle) => void>();
+    Reflect.set(authority, 'issueRelativeOpen', () => ({ handle, status: -1 }));
+    Reflect.set(authority, 'close', close);
+
+    expect(() => authority.openRelative(BigInt(1), 'payload.bin', true, 0)).toThrow();
+    expect(close).toHaveBeenCalledExactlyOnceWith(handle);
+  });
+
+  it('falls back to CloseHandle when NtClose returns a failure status', () => {
+    const authority = uninitializedAuthority();
+    const ntClose = vi.fn<() => number>().mockReturnValue(-1);
+    const closeHandle = vi.fn<() => boolean>().mockReturnValue(true);
+    Reflect.set(authority, 'api', { ntClose, closeHandle });
+
+    authority.close(BigInt(42));
+
+    expect(ntClose).toHaveBeenCalledOnce();
+    expect(closeHandle).toHaveBeenCalledOnce();
+  });
+
+  it('does not double-close after NtClose succeeds', () => {
+    const authority = uninitializedAuthority();
+    const ntClose = vi.fn<() => number>().mockReturnValue(0);
+    const closeHandle = vi.fn<() => boolean>().mockReturnValue(true);
+    Reflect.set(authority, 'api', { ntClose, closeHandle });
+
+    authority.close(BigInt(42));
+
+    expect(ntClose).toHaveBeenCalledOnce();
+    expect(closeHandle).not.toHaveBeenCalled();
+  });
+});
+
+describe('WindowsNativeAuthority read sharing', () => {
+  it('excludes concurrent writers only while a final file is held for reading', () => {
+    const authority = uninitializedAuthority();
+    const handleType = koffi.pointer('TestStableReadHandle', koffi.opaque());
+    const unicodeStringType = koffi.struct('TestStableReadUnicodeString', {
+      Length: 'uint16_t',
+      MaximumLength: 'uint16_t',
+      Buffer: koffi.pointer('char16_t'),
+    });
+    const objectAttributesType = koffi.struct('TestStableReadObjectAttributes', {
+      Length: 'uint32_t',
+      RootDirectory: handleType,
+      ObjectName: koffi.pointer(unicodeStringType),
+      Attributes: 'uint32_t',
+      SecurityDescriptor: 'void *',
+      SecurityQualityOfService: 'void *',
+    });
+    const shares: number[] = [];
+    Reflect.set(authority, 'api', {
+      unicodeStringType,
+      objectAttributesType,
+      ntCreateFile: (
+        output: TNativeHandle[],
+        _desiredAccess: number,
+        _attributes: object,
+        _ioStatus: object,
+        _allocationSize: null,
+        _fileAttributes: number,
+        shareAccess: number,
+      ) => {
+        shares.push(shareAccess);
+        output[0] = BigInt(42);
+        return 0;
+      },
+    });
+    const issueRelativeOpen = Reflect.get(authority, 'issueRelativeOpen') as (
+      parent: TNativeHandle,
+      segment: string,
+      final: boolean,
+    ) => unknown;
+
+    issueRelativeOpen.call(authority, BigInt(1), 'nested', false);
+    issueRelativeOpen.call(authority, BigInt(1), 'payload.bin', true);
+
+    expect(shares).toHaveLength(2);
+    expect(shares[0] & 0x2).toBe(0x2);
+    expect(shares[1] & 0x2).toBe(0);
+  });
+});

package/src/contracts.ts

@@ -0,0 +1,54 @@
+export type TStableFileAuthorityErrorCode =
+  | 'INVALID_PATH'
+  | 'UNSAFE_ENTRY'
+  | 'UNSUPPORTED_BACKEND'
+  | 'AUTHORITY_CLOSED'
+  | 'ROOT_CHANGED'
+  | 'FILE_CHANGED'
+  | 'OVER_BUDGET'
+  | 'HOST_IO';
+
+export interface IStableFileAuthorityErrorContext {
+  readonly operation: string;
+  readonly segmentIndex?: number;
+  readonly hostCode?: string;
+}
+
+const ERROR_MESSAGES: Readonly<Record<TStableFileAuthorityErrorCode, string>> = {
+  INVALID_PATH: 'The requested root-relative file operation is invalid.',
+  UNSAFE_ENTRY: 'The requested entry cannot be opened without following an unsafe object.',
+  UNSUPPORTED_BACKEND: 'This host cannot provide stable root-relative file reads.',
+  AUTHORITY_CLOSED: 'The stable rooted file authority is closed.',
+  ROOT_CHANGED: 'The retained root identity changed during the operation.',
+  FILE_CHANGED: 'The file identity or contents changed during the bounded read.',
+  OVER_BUDGET: 'The file exceeds the supplied byte budget.',
+  HOST_IO: 'The host could not complete the stable root-relative file operation.',
+};
+
+/** A stable, secret-free failure from a rooted file authority. */
+export class StableFileAuthorityError extends Error {
+  readonly code: TStableFileAuthorityErrorCode;
+  readonly context: Readonly<IStableFileAuthorityErrorContext>;
+
+  constructor(code: TStableFileAuthorityErrorCode, context: IStableFileAuthorityErrorContext) {
+    super(ERROR_MESSAGES[code]);
+    this.name = 'StableFileAuthorityError';
+    this.code = code;
+    this.context = Object.freeze({ ...context });
+  }
+}
+
+/** Opaque authority for bounded regular-file reads beneath one retained directory identity. */
+export interface IStableRootedFileReader {
+  readBytes(relativeSegments: readonly string[], maxBytes: number): Uint8Array | undefined;
+  close(): void;
+  [Symbol.dispose](): void;
+}
+
+export function authorityError(
+  code: TStableFileAuthorityErrorCode,
+  operation: string,
+  details: Omit<IStableFileAuthorityErrorContext, 'operation'> = {},
+): StableFileAuthorityError {
+  return new StableFileAuthorityError(code, { operation, ...details });
+}

package/src/host-backend.ts

@@ -0,0 +1,13 @@
+export interface IFileAuthorityTestHooks {
+  readonly afterDirectoryOpened?: (segmentIndex: number) => void;
+  readonly afterReadChunk?: (bytesRead: number) => void;
+}
+
+export interface IStableFileHostBackend {
+  readBytes(
+    relativeSegments: readonly string[],
+    maxBytes: number,
+    hooks: IFileAuthorityTestHooks,
+  ): Uint8Array | undefined;
+  close(): void;
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export {
+  StableFileAuthorityError,
+  type IStableRootedFileReader,
+  type TStableFileAuthorityErrorCode,
+} from './contracts.js';
+export { createStableRootedFileReader } from './stable-rooted-file-reader.js';

package/src/posix-backend.ts

@@ -0,0 +1,253 @@
+import { closeSync, constants, fstatSync, readSync, type BigIntStats } from 'node:fs';
+
+import * as koffi from 'koffi';
+
+import { authorityError, StableFileAuthorityError } from './contracts.js';
+
+import type { IFileAuthorityTestHooks, IStableFileHostBackend } from './host-backend.js';
+
+interface IPosixIdentity {
+  readonly device: bigint;
+  readonly inode: bigint;
+  readonly mode: bigint;
+}
+
+interface IPosixFileSnapshot extends IPosixIdentity {
+  readonly size: bigint;
+  readonly modified: bigint;
+  readonly changed: bigint;
+}
+
+type TOpen = (path: string, flags: number) => number;
+type TOpenAt = (directory: number, path: string, flags: number) => number;
+
+const CHUNK_BYTES = 1_048_576;
+const DARWIN_CLOSE_ON_EXEC = 0x01000000;
+const LINUX_CLOSE_ON_EXEC = 0x00080000;
+
+function identity(metadata: BigIntStats): IPosixIdentity {
+  return { device: metadata.dev, inode: metadata.ino, mode: metadata.mode };
+}
+
+function snapshot(metadata: BigIntStats): IPosixFileSnapshot {
+  return {
+    ...identity(metadata),
+    size: metadata.size,
+    modified: metadata.mtimeNs,
+    changed: metadata.ctimeNs,
+  };
+}
+
+function sameIdentity(left: IPosixIdentity, right: IPosixIdentity): boolean {
+  return left.device === right.device && left.inode === right.inode && left.mode === right.mode;
+}
+
+function sameSnapshot(left: IPosixFileSnapshot, right: IPosixFileSnapshot): boolean {
+  return (
+    sameIdentity(left, right) &&
+    left.size === right.size &&
+    left.modified === right.modified &&
+    left.changed === right.changed
+  );
+}
+
+function hostCode(errno: number): string {
+  for (const [name, value] of Object.entries(koffi.os.errno)) {
+    if (value === errno) return name;
+  }
+  return `ERRNO_${errno}`;
+}
+
+function flags(directory: boolean): number {
+  const closeOnExec =
+    (constants as typeof constants & { readonly O_CLOEXEC?: number }).O_CLOEXEC ??
+    (process.platform === 'darwin' ? DARWIN_CLOSE_ON_EXEC : LINUX_CLOSE_ON_EXEC);
+  return (
+    constants.O_RDONLY |
+    constants.O_NOFOLLOW |
+    constants.O_NONBLOCK |
+    closeOnExec |
+    (directory ? constants.O_DIRECTORY : 0)
+  );
+}
+
+function safeFstat(descriptor: number, operation: string): BigIntStats {
+  try {
+    return fstatSync(descriptor, { bigint: true });
+  } catch (error) {
+    const code = nodeErrorCode(typeof error === 'object' ? error : null);
+    throw authorityError('HOST_IO', operation, code === undefined ? {} : { hostCode: code });
+  }
+}
+
+function nodeErrorCode(error: object | null): string | undefined {
+  if (error === null || !('code' in error)) return undefined;
+  return typeof error.code === 'string' ? error.code : undefined;
+}
+
+/** POSIX implementation; descriptors never leave this module. */
+export class PosixStableFileHostBackend implements IStableFileHostBackend {
+  private readonly openAt: TOpenAt;
+  private readonly rootIdentity: IPosixIdentity;
+  private rootDescriptor: number | undefined;
+
+  constructor(rootDirectory: string) {
+    try {
+      const libc = koffi.load(
+        process.platform === 'darwin' ? '/usr/lib/libSystem.B.dylib' : 'libc.so.6',
+      );
+      const open = libc.func('int open(const char *path, int flags)') as TOpen;
+      this.openAt = libc.func('int openat(int fd, const char *path, int flags)') as TOpenAt;
+      const descriptor = open(rootDirectory, flags(true));
+      if (descriptor < 0) this.throwOpenFailure(koffi.errno(), 'open-root');
+      this.rootDescriptor = descriptor;
+      const metadata = safeFstat(descriptor, 'inspect-root');
+      if (!metadata.isDirectory()) throw authorityError('UNSAFE_ENTRY', 'open-root');
+      this.rootIdentity = identity(metadata);
+    } catch (error) {
+      if (this.rootDescriptor !== undefined) {
+        this.closeDescriptor(this.rootDescriptor);
+        this.rootDescriptor = undefined;
+      }
+      if (error instanceof StableFileAuthorityError) throw error;
+      throw authorityError('UNSUPPORTED_BACKEND', 'load-posix-backend');
+    }
+  }
+
+  readBytes(
+    relativeSegments: readonly string[],
+    maxBytes: number,
+    hooks: IFileAuthorityTestHooks,
+  ): Uint8Array | undefined {
+    const rootDescriptor = this.rootDescriptor;
+    if (rootDescriptor === undefined) throw authorityError('AUTHORITY_CLOSED', 'read');
+    this.assertRootIdentity(rootDescriptor);
+
+    let parentDescriptor = rootDescriptor;
+    let ownsParent = false;
+    let fileDescriptor: number | undefined;
+    try {
+      for (let index = 0; index < relativeSegments.length; index += 1) {
+        const final = index === relativeSegments.length - 1;
+        const descriptor = this.openAt(parentDescriptor, relativeSegments[index], flags(!final));
+        if (descriptor < 0) {
+          const errno = koffi.errno();
+          if (errno === koffi.os.errno.ENOENT) return undefined;
+          this.throwOpenFailure(errno, final ? 'open-file' : 'open-directory', index);
+        }
+
+        if (final) {
+          fileDescriptor = descriptor;
+          break;
+        }
+
+        const metadata = safeFstat(descriptor, 'inspect-directory');
+        if (!metadata.isDirectory()) {
+          this.closeDescriptor(descriptor);
+          throw authorityError('UNSAFE_ENTRY', 'inspect-directory', { segmentIndex: index });
+        }
+        if (ownsParent) this.closeDescriptor(parentDescriptor);
+        parentDescriptor = descriptor;
+        ownsParent = true;
+        hooks.afterDirectoryOpened?.(index);
+      }
+
+      if (fileDescriptor === undefined) throw authorityError('HOST_IO', 'open-file');
+      const bytes = this.readFile(fileDescriptor, maxBytes, hooks);
+      this.assertRootIdentity(rootDescriptor);
+      return bytes;
+    } catch (error) {
+      if (error instanceof StableFileAuthorityError) throw error;
+      const code = nodeErrorCode(typeof error === 'object' ? error : null);
+      throw authorityError('HOST_IO', 'read', code === undefined ? {} : { hostCode: code });
+    } finally {
+      this.closeOptionalDescriptor(fileDescriptor);
+      this.closeOptionalDescriptor(ownsParent ? parentDescriptor : undefined);
+    }
+  }
+
+  close(): void {
+    const descriptor = this.rootDescriptor;
+    if (descriptor === undefined) return;
+    this.rootDescriptor = undefined;
+    this.closeDescriptor(descriptor);
+  }
+
+  private readFile(
+    descriptor: number,
+    maxBytes: number,
+    hooks: IFileAuthorityTestHooks,
+  ): Uint8Array {
+    const beforeMetadata = safeFstat(descriptor, 'inspect-file');
+    if (!beforeMetadata.isFile()) throw authorityError('UNSAFE_ENTRY', 'inspect-file');
+    if (beforeMetadata.size > BigInt(maxBytes)) throw authorityError('OVER_BUDGET', 'read-file');
+
+    const expectedBytes = Number(beforeMetadata.size);
+    let bytes: Buffer;
+    try {
+      bytes = Buffer.alloc(expectedBytes);
+    } catch {
+      throw authorityError('HOST_IO', 'allocate-read-buffer');
+    }
+
+    let offset = 0;
+    while (offset < expectedBytes) {
+      const count = readSync(
+        descriptor,
+        bytes,
+        offset,
+        Math.min(CHUNK_BYTES, expectedBytes - offset),
+        offset,
+      );
+      if (count === 0) break;
+      offset += count;
+      hooks.afterReadChunk?.(offset);
+    }
+
+    const probe = Buffer.alloc(1);
+    const grew = readSync(descriptor, probe, 0, 1, expectedBytes) !== 0;
+    const afterMetadata = safeFstat(descriptor, 'reinspect-file');
+    if (grew && expectedBytes >= maxBytes) throw authorityError('OVER_BUDGET', 'read-file');
+    if (
+      offset !== expectedBytes ||
+      grew ||
+      !sameSnapshot(snapshot(beforeMetadata), snapshot(afterMetadata))
+    ) {
+      throw authorityError('FILE_CHANGED', 'read-file');
+    }
+    return bytes;
+  }
+
+  private assertRootIdentity(descriptor: number): void {
+    const metadata = safeFstat(descriptor, 'inspect-root');
+    if (!metadata.isDirectory() || !sameIdentity(this.rootIdentity, identity(metadata))) {
+      throw authorityError('ROOT_CHANGED', 'inspect-root');
+    }
+  }
+
+  private throwOpenFailure(errno: number, operation: string, segmentIndex?: number): never {
+    const code = hostCode(errno);
+    const details =
+      segmentIndex === undefined ? { hostCode: code } : { hostCode: code, segmentIndex };
+    if (
+      errno === koffi.os.errno.ELOOP ||
+      errno === koffi.os.errno.ENOTDIR ||
+      errno === koffi.os.errno.EISDIR
+    ) {
+      throw authorityError('UNSAFE_ENTRY', operation, details);
+    }
+    throw authorityError('HOST_IO', operation, details);
+  }
+
+  private closeDescriptor(descriptor: number): void {
+    try {
+      closeSync(descriptor);
+    } catch {
+      // allow-fallback: descriptor close failures cannot restore authority or make a later read safe
+    }
+  }
+
+  private closeOptionalDescriptor(descriptor: number | undefined): void {
+    if (descriptor !== undefined) this.closeDescriptor(descriptor);
+  }
+}

package/src/stable-rooted-file-reader.ts

@@ -0,0 +1,124 @@
+import { resolve } from 'node:path';
+
+import {
+  authorityError,
+  StableFileAuthorityError,
+  type IStableRootedFileReader,
+} from './contracts.js';
+import { PosixStableFileHostBackend } from './posix-backend.js';
+import { WindowsStableFileHostBackend } from './windows-backend.js';
+
+import type { IFileAuthorityTestHooks, IStableFileHostBackend } from './host-backend.js';
+
+export type { IFileAuthorityTestHooks } from './host-backend.js';
+
+const SUPPORTED_HOSTS = new Set([
+  'darwin-arm64',
+  'darwin-x64',
+  'linux-arm64',
+  'linux-x64',
+  'win32-x64',
+]);
+
+const finalizer = new FinalizationRegistry<IStableFileHostBackend>((backend) => {
+  backend.close();
+});
+
+function validateRoot(rootDirectory: string): string {
+  if (
+    typeof rootDirectory !== 'string' ||
+    rootDirectory.trim().length === 0 ||
+    rootDirectory.includes('\0')
+  ) {
+    throw authorityError('INVALID_PATH', 'validate-root');
+  }
+  return resolve(rootDirectory);
+}
+
+function validateReadInput(relativeSegments: readonly string[], maxBytes: number): void {
+  if (!Array.isArray(relativeSegments) || relativeSegments.length === 0) {
+    throw authorityError('INVALID_PATH', 'validate-segments');
+  }
+  for (let index = 0; index < relativeSegments.length; index += 1) {
+    const segment = relativeSegments[index];
+    if (
+      typeof segment !== 'string' ||
+      segment.length === 0 ||
+      segment === '.' ||
+      segment === '..' ||
+      segment.includes('\0') ||
+      segment.includes('/') ||
+      segment.includes('\\')
+    ) {
+      throw authorityError('INVALID_PATH', 'validate-segments', { segmentIndex: index });
+    }
+  }
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) {
+    throw authorityError('INVALID_PATH', 'validate-budget');
+  }
+}
+
+function createHostBackend(rootDirectory: string): IStableFileHostBackend {
+  const host = `${process.platform}-${process.arch}`;
+  if (!SUPPORTED_HOSTS.has(host)) {
+    throw authorityError('UNSUPPORTED_BACKEND', 'select-backend', { hostCode: host });
+  }
+  if (process.platform === 'win32') return new WindowsStableFileHostBackend(rootDirectory);
+  return new PosixStableFileHostBackend(rootDirectory);
+}
+
+class StableRootedFileReader implements IStableRootedFileReader {
+  private backend: IStableFileHostBackend | undefined;
+  private readonly finalizerToken = {};
+
+  constructor(
+    rootDirectory: string,
+    private readonly hooks: IFileAuthorityTestHooks,
+  ) {
+    const backend = createHostBackend(validateRoot(rootDirectory));
+    this.backend = backend;
+    finalizer.register(this, backend, this.finalizerToken);
+  }
+
+  readBytes(relativeSegments: readonly string[], maxBytes: number): Uint8Array | undefined {
+    const backend = this.backend;
+    if (backend === undefined) throw authorityError('AUTHORITY_CLOSED', 'read');
+    validateReadInput(relativeSegments, maxBytes);
+    try {
+      return backend.readBytes(relativeSegments, maxBytes, this.hooks);
+    } catch (error) {
+      if (error instanceof StableFileAuthorityError) throw error;
+      throw authorityError('HOST_IO', 'read');
+    }
+  }
+
+  close(): void {
+    const backend = this.backend;
+    if (backend === undefined) return;
+    this.backend = undefined;
+    finalizer.unregister(this.finalizerToken);
+    try {
+      backend.close();
+    } catch (error) {
+      if (error instanceof StableFileAuthorityError) throw error;
+      throw authorityError('HOST_IO', 'close');
+    }
+  }
+
+  [Symbol.dispose](): void {
+    this.close();
+  }
+}
+
+/** Create a stable, opaque read authority rooted at the currently opened directory identity. */
+export function createStableRootedFileReader(rootDirectory: string): IStableRootedFileReader {
+  return new StableRootedFileReader(rootDirectory, {});
+}
+
+/** Internal-only deterministic seams used by native replacement tests. */
+export function createStableRootedFileReaderForTest(
+  rootDirectory: string,
+  hooks: IFileAuthorityTestHooks,
+): IStableRootedFileReader {
+  return new StableRootedFileReader(rootDirectory, hooks);
+}

package/src/windows-backend.ts

@@ -0,0 +1,89 @@
+import { authorityError, StableFileAuthorityError } from './contracts.js';
+import { WindowsNativeAuthority, type IWindowsIdentity } from './windows-native-authority.js';
+
+import type { IFileAuthorityTestHooks, IStableFileHostBackend } from './host-backend.js';
+import type { TNativeHandle } from './windows-native-api.js';
+
+/** Windows implementation; native HANDLE values never leave the native authority module. */
+export class WindowsStableFileHostBackend implements IStableFileHostBackend {
+  private readonly native = new WindowsNativeAuthority();
+  private readonly rootIdentity: IWindowsIdentity;
+  private rootHandle: TNativeHandle | undefined;
+
+  constructor(rootDirectory: string) {
+    try {
+      const handle = this.native.openRoot(rootDirectory);
+      this.rootHandle = handle;
+      this.rootIdentity = this.native.queryIdentity(handle, 'inspect-root');
+    } catch (error) {
+      if (this.rootHandle !== undefined) {
+        this.native.close(this.rootHandle);
+        this.rootHandle = undefined;
+      }
+      if (error instanceof StableFileAuthorityError) throw error;
+      throw authorityError('UNSUPPORTED_BACKEND', 'load-windows-backend');
+    }
+  }
+
+  readBytes(
+    relativeSegments: readonly string[],
+    maxBytes: number,
+    hooks: IFileAuthorityTestHooks,
+  ): Uint8Array | undefined {
+    const rootHandle = this.rootHandle;
+    if (rootHandle === undefined) throw authorityError('AUTHORITY_CLOSED', 'read');
+    this.assertRootIdentity(rootHandle);
+
+    let parentHandle = rootHandle;
+    let ownsParent = false;
+    let fileHandle: TNativeHandle | undefined;
+    try {
+      for (let index = 0; index < relativeSegments.length; index += 1) {
+        const final = index === relativeSegments.length - 1;
+        const handle = this.native.openRelative(
+          parentHandle,
+          relativeSegments[index],
+          final,
+          index,
+        );
+        if (handle === undefined) return undefined;
+        if (final) {
+          fileHandle = handle;
+          break;
+        }
+        if (ownsParent) this.native.close(parentHandle);
+        parentHandle = handle;
+        ownsParent = true;
+        hooks.afterDirectoryOpened?.(index);
+      }
+
+      if (fileHandle === undefined) throw authorityError('HOST_IO', 'open-file');
+      const bytes = this.native.readFile(fileHandle, maxBytes, hooks);
+      this.assertRootIdentity(rootHandle);
+      return bytes;
+    } catch (error) {
+      if (error instanceof StableFileAuthorityError) throw error;
+      throw authorityError('HOST_IO', 'read');
+    } finally {
+      if (fileHandle !== undefined) this.native.close(fileHandle);
+      if (ownsParent) this.native.close(parentHandle);
+    }
+  }
+
+  close(): void {
+    const handle = this.rootHandle;
+    if (handle === undefined) return;
+    this.rootHandle = undefined;
+    this.native.close(handle);
+  }
+
+  private assertRootIdentity(handle: TNativeHandle): void {
+    const current = this.native.queryIdentity(handle, 'inspect-root');
+    if (
+      current.volume !== this.rootIdentity.volume ||
+      current.fileId !== this.rootIdentity.fileId
+    ) {
+      throw authorityError('ROOT_CHANGED', 'inspect-root');
+    }
+  }
+}