@jeffusion/bungee-types 4.2.0 → 4.4.0

package/dist/daemon-file.js

@@ -0,0 +1,944 @@
+import { randomBytes } from 'node:crypto';
+import { constants as fsConstants, existsSync } from 'node:fs';
+import { chmod, lstat, mkdir, open, realpath, rename, unlink } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { isAbsolute, join, normalize, parse, resolve, win32 } from 'node:path';
+import { decodeDaemonMetadataV1, encodeDaemonMetadataV1 } from './daemon-control.js';
+const MAX_BYTES = 4 * 1024;
+const METADATA_FILENAME = 'daemon.json';
+const WINDOWS_RENAME_RETRIES = 3;
+const WINDOWS_RENAME_RETRY_DELAY_MS = 25;
+const WINDOWS_SYSTEM = 'S-1-5-18';
+const WINDOWS_ADMINISTRATORS = 'S-1-5-32-544';
+const WINDOWS_FULL_CONTROL = 2032127;
+const WINDOWS_CONTAINER_INHERIT = 1;
+const WINDOWS_OBJECT_INHERIT = 2;
+const WINDOWS_ACL_EXEC_OPTIONS = {
+    windowsHide: true,
+};
+const WINDOWS_ACL_DEADLINE_MS = 10000;
+const WINDOWS_ACL_MAX_OUTPUT_BYTES = 64 * 1024;
+const WINDOWS_ACL_PHASE_PREFIX = '__BUNGEE_ACL_PHASE__:';
+const WINDOWS_ACL_PHASES = new Set(['started', 'before_get_acl', 'after_get_acl', 'before_set_acl', 'after_set_acl']);
+const WINDOWS_ACL_OPERATIONS = new Set(['read', 'set', 'ensure']);
+const WINDOWS_ACL_OUTCOMES = new Set(['exit', 'timeout', 'signal', 'spawn_error']);
+const WINDOWS_ACL_SIGNALS = new Set([
+    'SIGABRT', 'SIGALRM', 'SIGHUP', 'SIGINT', 'SIGKILL', 'SIGPIPE', 'SIGQUIT', 'SIGTERM',
+    'SIGUSR1', 'SIGUSR2', 'SIGCONT', 'SIGSTOP', 'SIGTSTP', 'SIGTTIN', 'SIGTTOU',
+]);
+const SID = /^S-(?:\d+)(?:-\d+)+$/;
+export class DaemonFileError extends Error {
+    constructor(code, message = code, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.code = code;
+        this.name = 'DaemonFileError';
+    }
+}
+const POSIX_UNSUPPORTED_FSYNC = new Set(['EINVAL', 'ENOTSUP', 'EOPNOTSUPP', 'ENOSYS']);
+const WINDOWS_UNSUPPORTED_FSYNC = new Set([...POSIX_UNSUPPORTED_FSYNC, 'EPERM', 'EISDIR']);
+function fail(code, message, cause) {
+    throw new DaemonFileError(code, message, cause);
+}
+function currentPlatform(options) { return options.platform ?? process.platform; }
+function testStage(options, stage) {
+    options?.testHooks?.onStage?.(stage);
+}
+function comparePath(value, platform) {
+    const normalized = (platform === 'win32' ? win32.normalize(value) : normalize(value)).split('\\').join('/');
+    return platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+function contained(parent, child, platform) {
+    const root = comparePath(parent, platform);
+    const target = comparePath(child, platform);
+    return target !== root && target.startsWith(`${root}/`);
+}
+function sameIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function canonicalSid(value) {
+    if (typeof value !== 'string')
+        return false;
+    return SID.test(value) && value.slice(2).split('-').every((part) => part === '0' || !part.startsWith('0'));
+}
+function identity(stat) {
+    return { dev: String(stat.dev), ino: String(stat.ino) };
+}
+function mode(stat) { return stat.mode & 0o777; }
+async function rejectSymlinkComponents(path, options, stage) {
+    const absolute = resolve(path);
+    const root = parse(absolute).root;
+    let current = root;
+    for (const part of absolute.slice(root.length).split(/[\\/]+/).filter(Boolean)) {
+        current = resolve(current, part);
+        testStage(options, stage);
+        try {
+            if ((await lstat(current)).isSymbolicLink())
+                fail('symlink', 'daemon runtime path contains a symlink');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+    }
+}
+async function canonicalProfile(options) {
+    const profile = process.env.USERPROFILE;
+    if (profile === undefined || !isAbsolute(profile))
+        fail('containment', 'USERPROFILE is unavailable');
+    testStage(options, 'profile_realpath');
+    try {
+        return await realpath(profile);
+    }
+    catch {
+        fail('containment', 'USERPROFILE cannot be canonicalized');
+    }
+}
+async function secureRuntimeDirectory(options, allowCreate) {
+    const requested = options.runtimeDirectory;
+    if (!isAbsolute(requested) || requested.includes('\0'))
+        fail('path', 'runtime directory must be absolute and NUL-free');
+    await rejectSymlinkComponents(requested, options, 'runtime_components');
+    const platform = currentPlatform(options);
+    let runtimePath = requested;
+    let canonicalRuntimePath;
+    let before;
+    testStage(options, 'runtime_lstat');
+    try {
+        before = await lstat(runtimePath);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        if (platform === 'win32') {
+            testStage(options, 'runtime_realpath');
+            try {
+                canonicalRuntimePath = await realpath(requested);
+            }
+            catch (realpathError) {
+                if (realpathError.code !== 'ENOENT')
+                    throw realpathError;
+            }
+        }
+        if (canonicalRuntimePath !== undefined) {
+            runtimePath = canonicalRuntimePath;
+            await rejectSymlinkComponents(runtimePath, options, 'runtime_components');
+            testStage(options, 'runtime_lstat');
+            before = await lstat(runtimePath);
+        }
+        else {
+            if (!allowCreate)
+                throw error;
+            testStage(options, 'runtime_mkdir');
+            await mkdir(requested, { recursive: true, mode: 0o700 });
+            testStage(options, 'runtime_created_lstat');
+            before = await lstat(requested);
+        }
+    }
+    if (!before.isDirectory() || before.isSymbolicLink())
+        fail('directory', 'runtime directory is not a real directory');
+    let root = canonicalRuntimePath;
+    if (root === undefined) {
+        testStage(options, 'runtime_realpath');
+        root = await realpath(runtimePath);
+    }
+    if (platform === 'win32') {
+        const profile = await canonicalProfile(options);
+        if (!contained(profile, root, platform))
+            fail('containment', 'runtime directory must be a strict child of USERPROFILE');
+        // Profile containment is deliberately before any ACL adapter call.
+        await ensureWindowsAcl(root, options.windowsAcl ?? defaultWindowsAclAdapter(), 'directory', options);
+    }
+    else {
+        if (typeof process.geteuid === 'function' && before.uid !== process.geteuid())
+            fail('owner', 'runtime directory owner is invalid');
+        if (mode(before) !== 0o700)
+            await chmod(runtimePath, 0o700);
+        const after = await lstat(runtimePath);
+        if (!after.isDirectory() || after.uid !== before.uid || mode(after) !== 0o700)
+            fail('permissions', 'runtime directory permissions are not 0700');
+    }
+    return root;
+}
+async function secureTarget(targetPath, options, mustExist) {
+    const platform = currentPlatform(options);
+    if (!isAbsolute(targetPath) || targetPath.includes('\0'))
+        fail('path', 'metadata target must be absolute and NUL-free');
+    const requestedTarget = resolve(targetPath);
+    const requestedExpected = resolve(options.runtimeDirectory, METADATA_FILENAME);
+    if (comparePath(requestedTarget, platform) !== comparePath(requestedExpected, platform)) {
+        // Do this before touching the trusted root so an untrusted path cannot cause ACL work.
+        fail('containment', 'metadata target is not the fixed runtime target');
+    }
+    const canonicalRoot = await secureRuntimeDirectory(options, !mustExist);
+    await rejectSymlinkComponents(targetPath, options, 'target_components');
+    const target = resolve(canonicalRoot, METADATA_FILENAME);
+    testStage(options, 'target_lstat');
+    try {
+        const item = await lstat(target);
+        if (item.isSymbolicLink())
+            fail('symlink', 'metadata file must not be a symlink');
+        if (!item.isFile() || item.nlink > 1)
+            fail('file', 'metadata file must be a single regular file');
+        // nlink === 0 is a transient metadata state (e.g. APFS lstat racing an atomic rename),
+        // not a hardlink: classify it as a retryable race so the read retry loop re-verifies.
+        if (item.nlink === 0)
+            fail('race', 'metadata file was detached by rename');
+        if (platform !== 'win32' && typeof process.geteuid === 'function' && item.uid !== process.geteuid())
+            fail('owner', 'metadata owner is invalid');
+        if (platform === 'win32')
+            await ensureWindowsAcl(target, options.windowsAcl ?? defaultWindowsAclAdapter(), 'file', options);
+        testStage(options, 'target_realpath');
+        const canonical = await realpath(target);
+        if (!contained(canonicalRoot, canonical, platform))
+            fail('containment', 'metadata file escaped the runtime root');
+        return { root: canonicalRoot, target, initial: identity(item) };
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT' || mustExist)
+            throw error;
+        return { root: canonicalRoot, target };
+    }
+}
+function assertDescriptor(item, expected, platform) {
+    if (!item.isFile() || item.nlink > 1)
+        fail('file', 'opened metadata descriptor is not a single regular file');
+    if (item.nlink === 0)
+        fail('race', 'opened metadata descriptor was detached by rename');
+    if (expected !== undefined && !sameIdentity(identity(item), expected))
+        fail('race', 'metadata file identity changed');
+    if (platform !== 'win32' && typeof process.geteuid === 'function' && item.uid !== process.geteuid())
+        fail('owner', 'metadata owner changed');
+}
+async function verifyLstat(target, expected, platform, expectedMode, options) {
+    testStage(options, 'verify_lstat');
+    const item = await lstat(target);
+    if (!item.isFile() || item.isSymbolicLink() || item.nlink > 1)
+        fail('file', 'metadata file is not a single regular file');
+    if (item.nlink === 0 || !sameIdentity(identity(item), expected))
+        fail('race', 'metadata file changed');
+    if (platform !== 'win32' && typeof process.geteuid === 'function' && item.uid !== process.geteuid())
+        fail('owner', 'metadata owner changed');
+    if (platform !== 'win32' && expectedMode !== undefined && mode(item) !== expectedMode)
+        fail('permissions', 'metadata file permissions are not exact');
+    return identity(item);
+}
+async function removeOwnedFile(path, expected) {
+    try {
+        const item = await lstat(path);
+        if (!item.isFile() || item.isSymbolicLink() || item.nlink !== 1 || !sameIdentity(identity(item), expected))
+            return;
+        await unlink(path);
+    }
+    catch { /* fail closed: never unlink an unproven replacement */ }
+}
+function bytesEqual(left, right) {
+    return left.byteLength === right.byteLength && left.every((byte, index) => byte === right[index]);
+}
+async function readEvidence(path, options) {
+    const safe = await secureTarget(path, options, true);
+    const platform = currentPlatform(options);
+    if (safe.initial === undefined)
+        fail('file', 'metadata file disappeared');
+    const noFollow = platform === 'win32' ? 0 : fsConstants.O_NOFOLLOW;
+    const handle = await open(safe.target, fsConstants.O_RDONLY | noFollow);
+    try {
+        await options.testHooks?.afterOpen?.(safe.target);
+        testStage(options, 'descriptor_stat');
+        const opened = await handle.stat();
+        assertDescriptor(opened, safe.initial, platform);
+        if (opened.size > MAX_BYTES)
+            fail('limit', 'daemon metadata file exceeds 4 KiB');
+        if (platform !== 'win32' && mode(opened) !== 0o600)
+            await handle.chmod(0o600);
+        testStage(options, 'descriptor_stat');
+        const secured = await handle.stat();
+        assertDescriptor(secured, safe.initial, platform);
+        if (platform !== 'win32' && mode(secured) !== 0o600)
+            fail('permissions', 'metadata file permissions are not exact');
+        await verifyLstat(safe.target, safe.initial, platform, 0o600, options);
+        await options.testHooks?.afterInitialStat?.(safe.target);
+        const chunks = [];
+        let total = 0;
+        while (true) {
+            const chunk = new Uint8Array(MAX_BYTES + 1);
+            const result = await handle.read(chunk, 0, chunk.byteLength, null);
+            if (result.bytesRead === 0)
+                break;
+            total += result.bytesRead;
+            if (total > MAX_BYTES)
+                fail('race', 'daemon metadata file grew while reading');
+            chunks.push(chunk.slice(0, result.bytesRead));
+        }
+        testStage(options, 'descriptor_stat');
+        const finalStat = await handle.stat();
+        assertDescriptor(finalStat, safe.initial, platform);
+        if (finalStat.size !== total || finalStat.size !== opened.size)
+            fail('race', 'metadata file size changed while reading');
+        await verifyLstat(safe.target, safe.initial, platform, 0o600, options);
+        const bytes = new Uint8Array(total);
+        let offset = 0;
+        for (const chunk of chunks) {
+            bytes.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        const metadata = decodeDaemonMetadataV1(bytes);
+        const canonical = new TextEncoder().encode(encodeDaemonMetadataV1(metadata));
+        if (!bytesEqual(bytes, canonical))
+            fail('invalid', 'metadata bytes are not canonical');
+        return { target: safe.target, root: safe.root, bytes: canonical, identity: safe.initial, metadata };
+    }
+    finally {
+        testStage(options, 'file_close');
+        await handle.close();
+    }
+}
+async function ensureWindowsAcl(path, adapter, kind, options) {
+    testStage(options, kind === 'directory' ? 'directory_acl' : 'file_acl');
+    const optimized = adapter;
+    if (optimized.ensure !== undefined) {
+        await optimized.ensure(path, kind);
+        return;
+    }
+    let snapshot = await adapter.read(path);
+    let validation = windowsAclSecure(snapshot, kind);
+    if (validation?.reason === 'invalid_current_sid')
+        throw new WindowsAclValidationError(validation);
+    if (validation !== null) {
+        testStage(options, kind === 'directory' ? 'directory_acl' : 'file_acl');
+        await adapter.set(path, snapshot.currentSid, kind);
+    }
+    testStage(options, kind === 'directory' ? 'directory_acl' : 'file_acl');
+    snapshot = await adapter.read(path);
+    validation = windowsAclSecure(snapshot, kind);
+    if (validation !== null)
+        throw new WindowsAclValidationError(validation);
+}
+const WINDOWS_ACL_VALIDATION_REASONS = new Set([
+    'invalid_current_sid', 'unexpected_sid', 'missing_sid', 'access_type',
+    'rights', 'inheritance', 'propagation', 'inherited',
+]);
+const WINDOWS_ACL_TARGET_KINDS = new Set(['directory', 'file']);
+const MAX_WINDOWS_ACL_EVIDENCE_COUNT = 1024;
+function boundedAclCount(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || !Number.isSafeInteger(value))
+        return 0;
+    return Math.min(MAX_WINDOWS_ACL_EVIDENCE_COUNT, Math.max(0, value));
+}
+function windowsAclSecure(snapshot, kind) {
+    const entries = Array.isArray(snapshot?.entries) ? snapshot.entries : [];
+    const currentSid = snapshot?.currentSid;
+    const validCurrentSid = canonicalSid(currentSid);
+    const allowed = new Set(validCurrentSid ? [currentSid, WINDOWS_SYSTEM, WINDOWS_ADMINISTRATORS] : [WINDOWS_SYSTEM, WINDOWS_ADMINISTRATORS]);
+    const missing = new Set(allowed);
+    const inheritance = kind === 'directory' ? WINDOWS_CONTAINER_INHERIT | WINDOWS_OBJECT_INHERIT : 0;
+    let reason = validCurrentSid ? undefined : 'invalid_current_sid';
+    let unexpectedCount = 0;
+    let inheritedCount = 0;
+    for (const entry of entries) {
+        if (entry?.inherited === true)
+            inheritedCount += 1;
+        if (!canonicalSid(entry?.sid) || !allowed.has(entry.sid)) {
+            unexpectedCount += 1;
+            reason ?? (reason = 'unexpected_sid');
+            continue;
+        }
+        missing.delete(entry.sid);
+        if (entry.access !== 'allow')
+            reason ?? (reason = 'access_type');
+        else if (entry.rights !== WINDOWS_FULL_CONTROL)
+            reason ?? (reason = 'rights');
+        else if (entry.inheritance !== inheritance)
+            reason ?? (reason = 'inheritance');
+        else if (entry.propagation !== 0)
+            reason ?? (reason = 'propagation');
+        else if (entry.inherited)
+            reason ?? (reason = 'inherited');
+    }
+    if (reason === undefined && missing.size !== 0)
+        reason = 'missing_sid';
+    if (reason === undefined)
+        return null;
+    return {
+        reason,
+        targetKind: kind,
+        entriesCount: boundedAclCount(entries.length),
+        unexpectedCount: boundedAclCount(unexpectedCount),
+        inheritedCount: boundedAclCount(inheritedCount),
+        missingCount: boundedAclCount(missing.size),
+    };
+}
+function encodedPowerShell(script) {
+    return Buffer.from(script, 'utf16le').toString('base64');
+}
+function escapeRegExp(value) { return value.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&'); }
+class WindowsAclProcessError extends Error {
+    constructor(diagnostic) {
+        super(JSON.stringify(diagnostic));
+        this.diagnostic = diagnostic;
+        this.code = 'BUNGEE_WINDOWS_ACL_PROCESS';
+        this.name = 'WindowsAclProcessError';
+    }
+}
+class WindowsAclValidationError extends DaemonFileError {
+    constructor(validation) {
+        super('acl', 'Windows ACL validation failed');
+        this.reason = validation.reason;
+        this.targetKind = validation.targetKind;
+        this.entriesCount = validation.entriesCount;
+        this.unexpectedCount = validation.unexpectedCount;
+        this.inheritedCount = validation.inheritedCount;
+        this.missingCount = validation.missingCount;
+    }
+}
+/** Formats only the bounded, allowlisted fields safe for exposing a Windows ACL failure. */
+export function formatDaemonFileAclError(error) {
+    if (!(error instanceof DaemonFileError) || error.code !== 'acl')
+        return null;
+    if (error instanceof WindowsAclValidationError) {
+        const reason = WINDOWS_ACL_VALIDATION_REASONS.has(error.reason) ? error.reason : 'unknown';
+        const targetKind = WINDOWS_ACL_TARGET_KINDS.has(error.targetKind) ? error.targetKind : 'unknown';
+        return `acl_reason=${reason} target_kind=${targetKind}`
+            + ` entries_count=${boundedAclCount(error.entriesCount)}`
+            + ` unexpected_count=${boundedAclCount(error.unexpectedCount)}`
+            + ` inherited_count=${boundedAclCount(error.inheritedCount)}`
+            + ` missing_count=${boundedAclCount(error.missingCount)}`;
+    }
+    const cause = error.cause;
+    if (!(cause instanceof WindowsAclProcessError))
+        return null;
+    const diagnostic = cause.diagnostic;
+    const operation = WINDOWS_ACL_OPERATIONS.has(diagnostic.operation) ? diagnostic.operation : 'unknown';
+    const outcome = WINDOWS_ACL_OUTCOMES.has(diagnostic.outcome) ? diagnostic.outcome : 'unknown';
+    const lastPhase = diagnostic.last_phase === null ? 'null' : WINDOWS_ACL_PHASES.has(diagnostic.last_phase) ? diagnostic.last_phase : 'unknown';
+    return `acl_operation=${operation} outcome=${outcome}`
+        + ` last_phase=${lastPhase} kill_returned_true=${diagnostic.kill_returned_true === true}`
+        + ` spawn_event=${diagnostic.spawn_event === true} exit_event=${diagnostic.exit_event === true}`
+        + ` close_event=${diagnostic.close_event === true}`;
+}
+function boundedElapsed(startedAt, deadlineMs) {
+    return Math.min(deadlineMs, Math.max(0, Date.now() - startedAt));
+}
+function selectWindowsAclExecutable(environment) {
+    const programFiles = environment.ProgramFiles;
+    if (programFiles !== undefined && isAbsolute(programFiles)) {
+        const pwsh = join(programFiles, 'PowerShell', '7', 'pwsh.exe');
+        if (existsSync(pwsh))
+            return pwsh;
+    }
+    return 'powershell.exe';
+}
+function allowedSignal(signal) {
+    return signal !== null && WINDOWS_ACL_SIGNALS.has(signal) ? signal : null;
+}
+function processDiagnostic(operation, startedAt, phase, environment, deadlineMs, result) {
+    return {
+        operation,
+        outcome: result.outcome,
+        elapsed_ms: boundedElapsed(startedAt, deadlineMs),
+        exit_code: typeof result.exitCode === 'number' ? result.exitCode : null,
+        signal: allowedSignal(result.signal ?? null),
+        spawn_event: result.spawnEvent,
+        exit_event: result.exitEvent,
+        close_event: result.closeEvent,
+        kill_returned_true: result.killReturnedTrue,
+        stdout_bytes: Math.min(WINDOWS_ACL_MAX_OUTPUT_BYTES, result.stdoutBytes),
+        stderr_bytes: Math.min(WINDOWS_ACL_MAX_OUTPUT_BYTES, result.stderrBytes),
+        last_phase: phase,
+        psmodulepath_present: false,
+        systemroot_present: Object.keys(environment).some((key) => key.toLowerCase() === 'systemroot'),
+    };
+}
+async function runPowerShell(operation, script, environment, deadlineMs) {
+    const startedAt = Date.now();
+    let phase = null;
+    let child;
+    try {
+        child = spawn(selectWindowsAclExecutable(process.env), ['-NoProfile', '-NonInteractive', '-EncodedCommand', encodedPowerShell(script)], {
+            ...WINDOWS_ACL_EXEC_OPTIONS,
+            env: environment,
+        });
+    }
+    catch {
+        const diagnostic = processDiagnostic(operation, startedAt, phase, environment, deadlineMs, {
+            outcome: 'spawn_error', spawnEvent: false, exitEvent: false, closeEvent: false, killReturnedTrue: false,
+            stdoutBytes: 0, stderrBytes: 0,
+        });
+        throw new WindowsAclProcessError(diagnostic);
+    }
+    let stdout = '';
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let phaseText = '';
+    let timedOut = false;
+    let spawnError = false;
+    let exitCode = null;
+    let exitSignal = null;
+    let spawnEvent = false;
+    let exitEvent = false;
+    let closeEvent = false;
+    let killReturnedTrue = false;
+    let exited = false;
+    let closed = false;
+    let settled = false;
+    let timer;
+    const result = await new Promise((resolve, reject) => {
+        const settle = () => {
+            if (settled || !closed)
+                return;
+            settled = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            const outcome = spawnError ? 'spawn_error' : timedOut ? 'timeout' : exitSignal !== null ? 'signal' : 'exit';
+            const diagnostic = processDiagnostic(operation, startedAt, phase, environment, deadlineMs, {
+                outcome, exitCode, signal: exitSignal, spawnEvent, exitEvent, closeEvent, killReturnedTrue, stdoutBytes, stderrBytes,
+            });
+            if (outcome === 'exit' && exitCode === 0)
+                resolve({ ...diagnostic, stdout });
+            else
+                reject(new WindowsAclProcessError(diagnostic));
+        };
+        child.stdout?.on('data', (chunk) => {
+            const bytes = Buffer.byteLength(chunk);
+            stdoutBytes += bytes;
+            if (stdoutBytes <= WINDOWS_ACL_MAX_OUTPUT_BYTES)
+                stdout += chunk.toString();
+        });
+        child.stderr?.on('data', (chunk) => {
+            const text = chunk.toString();
+            stderrBytes += Buffer.byteLength(text);
+            phaseText = `${phaseText}${text}`.slice(-256);
+            const matches = phaseText.matchAll(new RegExp(`${escapeRegExp(WINDOWS_ACL_PHASE_PREFIX)}(started|before_get_acl|after_get_acl|before_set_acl|after_set_acl)`, 'gu'));
+            for (const match of matches) {
+                const next = match[1];
+                if (next !== undefined && WINDOWS_ACL_PHASES.has(next))
+                    phase = next;
+            }
+        });
+        child.once('spawn', () => { spawnEvent = true; });
+        child.once('error', () => { spawnError = true; settle(); });
+        child.once('exit', (code, signal) => {
+            exitEvent = true;
+            exited = true;
+            exitCode = code;
+            exitSignal = signal;
+            settle();
+        });
+        child.once('close', () => { closeEvent = true; closed = true; settle(); });
+        timer = setTimeout(() => {
+            if (exited || settled)
+                return;
+            timedOut = true;
+            try {
+                killReturnedTrue = child.kill('SIGKILL') === true;
+            }
+            catch {
+                killReturnedTrue = false;
+            }
+        }, deadlineMs);
+    });
+    return result;
+}
+/** @internal source-test probe; not re-exported from the package root. */
+export function __testSelectWindowsAclExecutable(environment) {
+    return selectWindowsAclExecutable(environment);
+}
+function aclEnvironment(path, sid, kind) {
+    const allowed = new Set(['systemroot', 'windir', 'path', 'pathext', 'temp', 'tmp', 'comspec']);
+    const environment = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (allowed.has(key.toLowerCase()) && value !== undefined)
+            environment[key] = value;
+    }
+    environment.BUNGEE_DAEMON_ACL_PATH = path;
+    if (sid !== undefined)
+        environment.BUNGEE_DAEMON_ACL_SID = sid;
+    if (kind !== undefined)
+        environment.BUNGEE_DAEMON_ACL_KIND = kind;
+    return environment;
+}
+function defaultWindowsAclAdapter(deadlineMs = WINDOWS_ACL_DEADLINE_MS) {
+    const phase = (value) => `[Console]::Error.WriteLine('${WINDOWS_ACL_PHASE_PREFIX}${value}');`;
+    const moduleBootstrap = '$env:PSModulePath=[System.IO.Path]::Combine($PSHOME,"Modules");'
+        + 'Import-Module Microsoft.PowerShell.Security -ErrorAction Stop;';
+    const readScript = phase('started') + moduleBootstrap + phase('before_get_acl')
+        + '$item=Get-Item -LiteralPath $env:BUNGEE_DAEMON_ACL_PATH -Force;'
+        + '$a=if($item -is [System.IO.DirectoryInfo]){[System.IO.FileSystemAclExtensions]::GetAccessControl([System.IO.DirectoryInfo]$item,[System.Security.AccessControl.AccessControlSections]::Access)}'
+        + 'elseif($item -is [System.IO.FileInfo]){[System.IO.FileSystemAclExtensions]::GetAccessControl([System.IO.FileInfo]$item,[System.Security.AccessControl.AccessControlSections]::Access)}'
+        + 'else{throw "Windows ACL target is not a file or directory"};'
+        + phase('after_get_acl')
+        + '$sid=[System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value;'
+        + '$e=@($a.GetAccessRules($true,$true,[System.Security.Principal.SecurityIdentifier])|ForEach-Object { @{sid=$_.IdentityReference.Value;'
+        + 'access=$(if([int]$_.AccessControlType -eq 0){"allow"}else{"deny"});rights=[int]$_.FileSystemRights;'
+        + 'inheritance=[int]$_.InheritanceFlags;propagation=[int]$_.PropagationFlags;inherited=[bool]$_.IsInherited} });'
+        + '[Console]::Out.Write((ConvertTo-Json -Compress -Depth 4 @{currentSid=$sid;entries=$e}))';
+    const setScript = phase('started') + moduleBootstrap + '$p=$env:BUNGEE_DAEMON_ACL_PATH;$u=$env:BUNGEE_DAEMON_ACL_SID;'
+        + '$k=$env:BUNGEE_DAEMON_ACL_KIND;$a=if($k -eq "directory"){[System.Security.AccessControl.DirectorySecurity]::new()}else{[System.Security.AccessControl.FileSecurity]::new()};'
+        + '$a.SetAccessRuleProtection($true,$false);$i=if($k -eq "directory"){[System.Security.AccessControl.InheritanceFlags]::ObjectInherit -bor [System.Security.AccessControl.InheritanceFlags]::ContainerInherit}else{[System.Security.AccessControl.InheritanceFlags]::None};'
+        + '@($u,"S-1-5-18","S-1-5-32-544")|ForEach-Object {$a.AddAccessRule([System.Security.AccessControl.FileSystemAccessRule]::new([System.Security.Principal.SecurityIdentifier]::new($_),[System.Security.AccessControl.FileSystemRights]::FullControl,$i,[System.Security.AccessControl.PropagationFlags]::None,[System.Security.AccessControl.AccessControlType]::Allow))};'
+        + phase('before_set_acl') + 'if($k -eq "directory"){[System.IO.FileSystemAclExtensions]::SetAccessControl([System.IO.DirectoryInfo]::new($p),$a)}else{[System.IO.FileSystemAclExtensions]::SetAccessControl([System.IO.FileInfo]::new($p),$a)};' + phase('after_set_acl');
+    const readBlock = phase('before_get_acl') + '$item=Get-Item -LiteralPath $p -Force;'
+        + '$a=if($item -is [System.IO.DirectoryInfo]){[System.IO.FileSystemAclExtensions]::GetAccessControl([System.IO.DirectoryInfo]$item,[System.Security.AccessControl.AccessControlSections]::Access)}'
+        + 'elseif($item -is [System.IO.FileInfo]){[System.IO.FileSystemAclExtensions]::GetAccessControl([System.IO.FileInfo]$item,[System.Security.AccessControl.AccessControlSections]::Access)}'
+        + 'else{throw "Windows ACL target is not a file or directory"};'
+        + '$sid=[System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value;'
+        + '$e=@($a.GetAccessRules($true,$true,[System.Security.Principal.SecurityIdentifier])|ForEach-Object { @{sid=$_.IdentityReference.Value;'
+        + 'access=$(if([int]$_.AccessControlType -eq 0){"allow"}else{"deny"});rights=[int]$_.FileSystemRights;'
+        + 'inheritance=[int]$_.InheritanceFlags;propagation=[int]$_.PropagationFlags;inherited=[bool]$_.IsInherited} });'
+        + phase('after_get_acl') + '@{currentSid=$sid;entries=$e}';
+    const ensureScript = '$ErrorActionPreference=\'Stop\';' + phase('started') + moduleBootstrap + '$p=$env:BUNGEE_DAEMON_ACL_PATH;$k=$env:BUNGEE_DAEMON_ACL_KIND;'
+        + '$readAcl={ ' + readBlock + ' };$before=&$readAcl;$sid=$before.currentSid;'
+        + `$parts=$sid -split "-";$validSid=($sid -cmatch '^S-[0-9]+(?:-[0-9]+)+$') -and (@($parts|Select-Object -Skip 1|Where-Object { $_.Length -gt 1 -and $_.StartsWith("0") }).Count -eq 0);`
+        + '$allowed=@($sid,"S-1-5-18","S-1-5-32-544");$inheritance=if($k -eq "directory"){3}else{0};$missing=@{};$repair=$false;'
+        + 'if($validSid){foreach($name in $allowed){$missing[$name]=$true};foreach($r in @($before.entries)){'
+        + 'if($allowed -notcontains $r.sid){$repair=$true;continue};$missing.Remove($r.sid);'
+        + 'if($r.access -ne "allow" -or [int]$r.rights -ne 2032127 -or [int]$r.inheritance -ne $inheritance -or [int]$r.propagation -ne 0 -or [bool]$r.inherited){$repair=$true}};'
+        + 'if($missing.Count -ne 0){$repair=$true}};'
+        + 'if($repair){$a=if($k -eq "directory"){[System.Security.AccessControl.DirectorySecurity]::new()}else{[System.Security.AccessControl.FileSecurity]::new()};'
+        + '$a.SetAccessRuleProtection($true,$false);$i=if($k -eq "directory"){[System.Security.AccessControl.InheritanceFlags]::ObjectInherit -bor [System.Security.AccessControl.InheritanceFlags]::ContainerInherit}else{[System.Security.AccessControl.InheritanceFlags]::None};'
+        + '@($sid,"S-1-5-18","S-1-5-32-544")|ForEach-Object {$a.AddAccessRule([System.Security.AccessControl.FileSystemAccessRule]::new([System.Security.Principal.SecurityIdentifier]::new($_),[System.Security.AccessControl.FileSystemRights]::FullControl,$i,[System.Security.AccessControl.PropagationFlags]::None,[System.Security.AccessControl.AccessControlType]::Allow))};'
+        + phase('before_set_acl') + 'if($k -eq "directory"){[System.IO.FileSystemAclExtensions]::SetAccessControl([System.IO.DirectoryInfo]::new($p),$a)}else{[System.IO.FileSystemAclExtensions]::SetAccessControl([System.IO.FileInfo]::new($p),$a)};' + phase('after_set_acl') + '};'
+        + '$after=&$readAcl;[Console]::Out.Write((ConvertTo-Json -Compress -Depth 6 @{before=$before;after=$after;repaired=$repair}))';
+    return {
+        async read(path) {
+            let diagnostic;
+            try {
+                const result = await runPowerShell('read', readScript, aclEnvironment(path), deadlineMs);
+                const { stdout, ...completedDiagnostic } = result;
+                diagnostic = completedDiagnostic;
+                const value = JSON.parse(stdout);
+                if (!Array.isArray(value.entries))
+                    fail('acl', 'Windows ACL probe was invalid');
+                return value;
+            }
+            catch (error) {
+                if (error instanceof WindowsAclProcessError)
+                    fail('acl', 'Windows ACL probe failed', error);
+                fail('acl', 'Windows ACL probe was invalid', new WindowsAclProcessError(diagnostic));
+            }
+        },
+        async set(path, currentSid, kind) {
+            if (!canonicalSid(currentSid) || kind === undefined)
+                fail('acl', 'Windows ACL update arguments are invalid');
+            try {
+                await runPowerShell('set', setScript, aclEnvironment(path, currentSid, kind), deadlineMs);
+            }
+            catch (error) {
+                if (error instanceof WindowsAclProcessError)
+                    fail('acl', 'Windows ACL update failed', error);
+                fail('acl', 'Windows ACL update failed');
+            }
+        },
+        async ensure(path, kind) {
+            let diagnostic;
+            try {
+                const result = await runPowerShell('ensure', ensureScript, aclEnvironment(path, undefined, kind), deadlineMs);
+                const { stdout, ...completedDiagnostic } = result;
+                diagnostic = completedDiagnostic;
+                const value = JSON.parse(stdout);
+                if (value.before === undefined || value.after === undefined || typeof value.repaired !== 'boolean'
+                    || typeof value.before.currentSid !== 'string' || typeof value.after.currentSid !== 'string'
+                    || value.before.currentSid !== value.after.currentSid
+                    || !Array.isArray(value.before.entries) || !Array.isArray(value.after.entries)) {
+                    fail('acl', 'Windows ACL ensure was invalid');
+                }
+                const beforeValidation = windowsAclSecure(value.before, kind);
+                if (beforeValidation?.reason === 'invalid_current_sid')
+                    throw new WindowsAclValidationError(beforeValidation);
+                if ((beforeValidation !== null) !== value.repaired)
+                    fail('acl', 'Windows ACL ensure envelope was contradictory');
+                const afterValidation = windowsAclSecure(value.after, kind);
+                if (afterValidation !== null)
+                    throw new WindowsAclValidationError(afterValidation);
+            }
+            catch (error) {
+                if (error instanceof WindowsAclProcessError)
+                    fail('acl', 'Windows ACL ensure failed', error);
+                if (error instanceof WindowsAclValidationError)
+                    throw error;
+                fail('acl', 'Windows ACL ensure was invalid', new WindowsAclProcessError(diagnostic));
+            }
+        },
+    };
+}
+/** @internal source-test probe; not re-exported from the package root. */
+export async function __testReadWindowsAcl(path, deadlineMs = WINDOWS_ACL_DEADLINE_MS) {
+    return defaultWindowsAclAdapter(deadlineMs).read(path);
+}
+/** @internal source-test probe; not re-exported from the package root. */
+export async function __testEnsureWindowsAcl(path, kind, deadlineMs = WINDOWS_ACL_DEADLINE_MS) {
+    const adapter = defaultWindowsAclAdapter(deadlineMs);
+    await adapter.ensure(path, kind);
+}
+/** @internal source-test probe; not re-exported from the package root. */
+export function __testWindowsAclIsSecure(snapshot, kind) {
+    return windowsAclSecure(snapshot, kind) === null;
+}
+/** @internal source-test factory; not re-exported from the package root. */
+export function __testCreateDaemonFileAclError(overrides = {}) {
+    const operation = overrides.operation === 'read' || overrides.operation === 'set' || overrides.operation === 'ensure' ? overrides.operation : 'forged_operation';
+    const outcome = overrides.outcome === 'exit' || overrides.outcome === 'timeout' || overrides.outcome === 'signal' || overrides.outcome === 'spawn_error'
+        ? overrides.outcome : 'forged_outcome';
+    const lastPhase = overrides.last_phase === null || overrides.last_phase === 'started' || overrides.last_phase === 'before_get_acl'
+        || overrides.last_phase === 'after_get_acl' || overrides.last_phase === 'before_set_acl' || overrides.last_phase === 'after_set_acl'
+        ? overrides.last_phase : 'forged_phase';
+    const diagnostic = {
+        operation, outcome, elapsed_ms: typeof overrides.elapsed_ms === 'number' ? overrides.elapsed_ms : 1,
+        exit_code: typeof overrides.exit_code === 'number' ? overrides.exit_code : 17,
+        signal: typeof overrides.signal === 'string' && WINDOWS_ACL_SIGNALS.has(overrides.signal) ? overrides.signal : null,
+        spawn_event: overrides.spawn_event === true,
+        exit_event: overrides.exit_event === true,
+        close_event: overrides.close_event === true,
+        kill_returned_true: overrides.kill_returned_true === true,
+        stdout_bytes: typeof overrides.stdout_bytes === 'number' ? overrides.stdout_bytes : 0,
+        stderr_bytes: typeof overrides.stderr_bytes === 'number' ? overrides.stderr_bytes : 0,
+        last_phase: lastPhase,
+        psmodulepath_present: false,
+        systemroot_present: overrides.systemroot_present === true,
+    };
+    return new DaemonFileError('acl', 'Windows ACL process failed', new WindowsAclProcessError(diagnostic));
+}
+async function fsyncDirectory(root, platform, options) {
+    const unsupported = platform === 'win32' ? WINDOWS_UNSUPPORTED_FSYNC : POSIX_UNSUPPORTED_FSYNC;
+    let handle;
+    testStage(options, 'file_sync');
+    try {
+        handle = await open(root, fsConstants.O_RDONLY | fsConstants.O_DIRECTORY);
+        await handle.sync();
+    }
+    catch (error) {
+        if (!unsupported.has(error.code ?? ''))
+            throw error;
+    }
+    finally {
+        if (handle !== undefined) {
+            testStage(options, 'file_close');
+            try {
+                await handle.close();
+            }
+            catch (error) {
+                if (!unsupported.has(error.code ?? ''))
+                    throw error;
+            }
+        }
+    }
+}
+async function writeAndVerify(handle, target, root, bytes, options, expected, verifyAclBeforeWrite = false) {
+    const platform = currentPlatform(options);
+    testStage(options, 'descriptor_stat');
+    const before = await handle.stat();
+    assertDescriptor(before, expected, platform);
+    if (platform !== 'win32')
+        await handle.chmod(0o600);
+    testStage(options, 'descriptor_stat');
+    const secured = await handle.stat();
+    assertDescriptor(secured, expected, platform);
+    if (platform !== 'win32' && mode(secured) !== 0o600)
+        fail('permissions', 'temporary metadata file is not 0600');
+    await verifyLstat(target, identity(secured), platform, 0o600, options);
+    if (verifyAclBeforeWrite && platform === 'win32') {
+        await ensureWindowsAcl(target, options.windowsAcl ?? defaultWindowsAclAdapter(), 'file', options);
+    }
+    testStage(options, 'file_write');
+    await handle.writeFile(bytes);
+    testStage(options, 'file_sync');
+    await handle.sync();
+    testStage(options, 'descriptor_stat');
+    const after = await handle.stat();
+    assertDescriptor(after, identity(secured), platform);
+    if (after.size !== bytes.byteLength || (platform !== 'win32' && mode(after) !== 0o600))
+        fail('race', 'temporary metadata file changed while writing');
+    await verifyLstat(target, identity(after), platform, 0o600, options);
+    if (platform === 'win32')
+        await ensureWindowsAcl(target, options.windowsAcl ?? defaultWindowsAclAdapter(), 'file', options);
+    return identity(after);
+}
+async function renameAtomically(temporary, target, options) {
+    const platform = currentPlatform(options);
+    const replace = options.testHooks?.rename ?? rename;
+    for (let attempt = 0;; attempt += 1) {
+        try {
+            await replace(temporary, target);
+            return;
+        }
+        catch (error) {
+            if (platform !== 'win32' || error.code !== 'EPERM' || attempt >= WINDOWS_RENAME_RETRIES) {
+                throw error;
+            }
+            const sleep = options.testHooks?.sleep
+                ?? ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
+            await sleep(WINDOWS_RENAME_RETRY_DELAY_MS);
+        }
+    }
+}
+async function atomicReplace(target, root, bytes, options) {
+    const temporary = join(root, `.${METADATA_FILENAME}.${process.pid}.${randomBytes(16).toString('hex')}.tmp`);
+    const handle = await open(temporary, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL, 0o600);
+    let temporaryIdentity;
+    try {
+        testStage(options, 'descriptor_stat');
+        const opened = await handle.stat();
+        assertDescriptor(opened, undefined, currentPlatform(options));
+        temporaryIdentity = identity(opened);
+        const writtenIdentity = await writeAndVerify(handle, temporary, root, bytes, options);
+        if (!sameIdentity(temporaryIdentity, writtenIdentity))
+            fail('race', 'temporary metadata identity changed');
+        testStage(options, 'file_close');
+        await handle.close();
+        await renameAtomically(temporary, target, options);
+        await verifyLstat(target, temporaryIdentity, currentPlatform(options), 0o600, options);
+        if (currentPlatform(options) === 'win32')
+            await ensureWindowsAcl(target, options.windowsAcl ?? defaultWindowsAclAdapter(), 'file', options);
+        await fsyncDirectory(root, currentPlatform(options), options);
+    }
+    catch (error) {
+        try {
+            await handle.close();
+        }
+        catch { /* best effort */ }
+        if (temporaryIdentity !== undefined)
+            await removeOwnedFile(temporary, temporaryIdentity);
+        throw error;
+    }
+}
+export async function readDaemonMetadataFile(path, options) {
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+        try {
+            return (await readEvidence(path, options)).metadata;
+        }
+        catch (error) {
+            if (!(error instanceof DaemonFileError) || error.code !== 'race' || attempt === 3)
+                throw error;
+        }
+    }
+    fail('race', 'metadata read retries were exhausted');
+}
+const LEGAL_TRANSITIONS = {
+    launching: ['starting'], starting: ['armed'], armed: ['stopping'], stopping: [],
+};
+function sameImmutable(left, right) {
+    return left.schema === right.schema && left.launcher_pid === right.launcher_pid && left.boot_nonce === right.boot_nonce
+        && left.shutdown_secret === right.shutdown_secret && left.executable === right.executable && left.entrypoint === right.entrypoint;
+}
+function validTransition(current, next) {
+    if (!LEGAL_TRANSITIONS[current.state].includes(next.state) || !sameImmutable(current, next))
+        return false;
+    if (current.state === 'starting' && (next.state !== 'armed' || next.pid !== current.pid))
+        return false;
+    if (current.state === 'armed' && (next.state !== 'stopping' || next.pid !== current.pid
+        || next.instance_id !== current.instance_id || next.management_host !== current.management_host
+        || next.management_port !== current.management_port))
+        return false;
+    return true;
+}
+export async function transitionDaemonMetadataFile(path, transition, options) {
+    const first = await readEvidence(path, options);
+    if (first.metadata.boot_nonce !== transition.expectedBootNonce || first.metadata.state !== transition.expectedState)
+        fail('state', 'metadata owner or state does not match');
+    if (first.metadata.shutdown_secret !== transition.expectedShutdownSecret)
+        fail('secret', 'metadata secret does not match');
+    if (!validTransition(first.metadata, transition.next))
+        fail('transition', 'metadata state transition is illegal or mutates ownership');
+    const second = await readEvidence(path, options);
+    if (!sameIdentity(first.identity, second.identity) || !bytesEqual(first.bytes, second.bytes))
+        fail('race', 'metadata changed before transition');
+    await atomicReplace(first.target, first.root, new TextEncoder().encode(encodeDaemonMetadataV1(transition.next)), options);
+    return transition.next;
+}
+/**
+ * Deletes metadata only after the caller has independently proven the owner is dead.
+ * This is a guarded delete, not a cross-process CAS primitive.
+ */
+export async function deleteDaemonMetadataAfterOwnerExit(path, expected, options) {
+    let first;
+    try {
+        first = await readEvidence(path, options);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+    if (first.metadata.boot_nonce !== expected.bootNonce || first.metadata.state !== expected.state
+        || first.metadata.shutdown_secret !== expected.shutdownSecret)
+        return false;
+    let second;
+    try {
+        second = await readEvidence(path, options);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+    if (!sameIdentity(first.identity, second.identity) || !bytesEqual(first.bytes, second.bytes))
+        fail('race', 'metadata changed before delete');
+    await verifyLstat(second.target, second.identity, currentPlatform(options), 0o600, options);
+    await unlink(second.target);
+    await fsyncDirectory(second.root, currentPlatform(options), options);
+    return true;
+}
+/** Deletes a launch record owned by the current CLI process. */
+export async function deleteDaemonMetadataForLauncher(path, expected, options) {
+    if (process.pid <= 0)
+        fail('owner', 'current process pid is invalid');
+    const first = await readEvidence(path, options);
+    if (first.metadata.state !== 'launching' || first.metadata.launcher_pid !== process.pid
+        || first.metadata.boot_nonce !== expected.bootNonce
+        || first.metadata.shutdown_secret !== expected.shutdownSecret)
+        return false;
+    const second = await readEvidence(path, options);
+    if (!sameIdentity(first.identity, second.identity) || !bytesEqual(first.bytes, second.bytes)) {
+        fail('race', 'metadata changed before launcher delete');
+    }
+    await verifyLstat(second.target, second.identity, currentPlatform(options), 0o600, options);
+    await unlink(second.target);
+    await fsyncDirectory(second.root, currentPlatform(options), options);
+    return true;
+}
+/** Deletes the current master's stopping record after runtime cleanup succeeds. */
+export async function deleteDaemonMetadataForMaster(path, expected, options) {
+    if (expected.pid !== process.pid)
+        fail('owner', 'metadata pid is not the current process');
+    const first = await readEvidence(path, options);
+    if (first.metadata.state !== 'stopping' || first.metadata.boot_nonce !== expected.bootNonce
+        || first.metadata.shutdown_secret !== expected.shutdownSecret || first.metadata.pid !== expected.pid) {
+        fail('state', 'metadata is not the expected stopping record for this master');
+    }
+    const second = await readEvidence(path, options);
+    if (!sameIdentity(first.identity, second.identity) || !bytesEqual(first.bytes, second.bytes)) {
+        fail('race', 'metadata changed before master delete');
+    }
+    await verifyLstat(second.target, second.identity, currentPlatform(options), 0o600, options);
+    await unlink(second.target);
+    await fsyncDirectory(second.root, currentPlatform(options), options);
+    return true;
+}
+export async function createLaunchingDaemonMetadataFile(path, metadata, options) {
+    if (metadata.state !== 'launching')
+        fail('state', 'launch metadata must be launching');
+    const safe = await secureTarget(path, options, false);
+    const bytes = new TextEncoder().encode(encodeDaemonMetadataV1(metadata));
+    testStage(options, 'create_open');
+    const handle = await open(safe.target, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL, 0o600);
+    let createdIdentity;
+    try {
+        testStage(options, 'descriptor_stat');
+        const opened = await handle.stat();
+        assertDescriptor(opened, undefined, currentPlatform(options));
+        createdIdentity = identity(opened);
+        await writeAndVerify(handle, safe.target, safe.root, bytes, options, createdIdentity, true);
+        testStage(options, 'file_close');
+        await handle.close();
+        await fsyncDirectory(safe.root, currentPlatform(options), options);
+    }
+    catch (error) {
+        try {
+            await handle.close();
+        }
+        catch { /* best effort */ }
+        if (createdIdentity !== undefined)
+            await removeOwnedFile(safe.target, createdIdentity);
+        throw error;
+    }
+}