@jeffusion/bungee-types 4.3.0 → 4.4.0

package/dist/config-v2.d.ts

@@ -0,0 +1,68 @@
+import type { AppConfig, Endpoint, PluginConfigOptions, RouteConfig, Service } from './types.js';
+export type ConfigurationId = string;
+export type Sha256Digest = `sha256:${string}`;
+export interface PluginActivationV2 {
+    readonly plugin_name: string;
+}
+export interface PluginBindingV2 {
+    readonly id: ConfigurationId;
+    readonly position: number;
+    readonly name: string;
+    readonly options?: PluginConfigOptions;
+    readonly enabled: boolean;
+}
+export interface UpstreamManagedByV2 {
+    readonly plugin: string;
+    readonly contributionId: string;
+    readonly bindingId: ConfigurationId;
+}
+type UpstreamPolicyV2 = Omit<Endpoint, 'id' | 'plugins' | 'weight' | 'priority' | 'is_disabled'>;
+export interface UpstreamV2 extends UpstreamPolicyV2 {
+    readonly id: ConfigurationId;
+    readonly position: number;
+    readonly weight: number;
+    readonly priority: number;
+    readonly is_disabled: boolean;
+    readonly managedBy?: UpstreamManagedByV2;
+    readonly plugins: readonly PluginBindingV2[];
+}
+type ServicePolicyV2 = Omit<Service, 'name' | 'endpoints' | 'plugins'>;
+export interface ServiceV2 extends ServicePolicyV2 {
+    readonly id: ConfigurationId;
+    readonly position: number;
+    readonly name: string;
+    readonly endpoints: readonly UpstreamV2[];
+    readonly plugins: readonly PluginBindingV2[];
+}
+type RoutePolicyV2 = Omit<RouteConfig, 'path' | 'service' | 'endpoints' | 'plugins'>;
+interface RouteV2Base extends RoutePolicyV2 {
+    readonly id: ConfigurationId;
+    readonly position: number;
+    readonly path: string;
+    readonly plugins: readonly PluginBindingV2[];
+}
+export interface ServiceRouteV2 extends RouteV2Base {
+    readonly service_id: ConfigurationId;
+    readonly endpoints?: never;
+}
+export interface DirectRouteV2 extends RouteV2Base {
+    readonly service_id?: never;
+    readonly endpoints: readonly UpstreamV2[];
+}
+export type RouteV2 = ServiceRouteV2 | DirectRouteV2;
+type GlobalPolicyV2 = Omit<AppConfig, 'config_version' | 'plugins' | 'services' | 'routes'>;
+export interface LogicalConfigurationV2 extends GlobalPolicyV2 {
+    readonly services: readonly ServiceV2[];
+    readonly routes: readonly RouteV2[];
+    readonly plugins: readonly PluginBindingV2[];
+}
+export interface ConfigurationAggregateV2 {
+    readonly logical_configuration: LogicalConfigurationV2;
+    readonly plugin_activations: readonly PluginActivationV2[];
+}
+export interface CommittedConfigurationSnapshotV2 {
+    readonly revision: number;
+    readonly content_hash: Sha256Digest;
+    readonly aggregate: ConfigurationAggregateV2;
+}
+export {};

package/dist/config-v2.js

@@ -0,0 +1 @@
+export {};

package/dist/daemon-control.d.ts

@@ -0,0 +1,59 @@
+export declare const DAEMON_METADATA_SCHEMA: "bungee-daemon-metadata-v1";
+export declare const DAEMON_METADATA_MAX_BYTES: number;
+export declare const DAEMON_SHUTDOWN_PATH: "/__bungee/internal/daemon/v1/shutdown";
+export declare const DAEMON_CONTROL_HTTP_PREFIX: "/__bungee/internal/daemon/";
+export declare const DAEMON_AUTHORIZATION_HEADER: "authorization";
+export declare const DAEMON_BOOT_HEADER: "x-bungee-daemon-boot";
+export declare const DAEMON_INSTANCE_HEADER: "x-bungee-daemon-instance";
+export declare const DAEMON_PID_HEADER: "x-bungee-daemon-pid";
+export declare const DAEMON_PROCESS_IDENTITY_MARKER_PREFIX: "--bungee-process-identity=";
+type DaemonMetadataBase = {
+    readonly schema: typeof DAEMON_METADATA_SCHEMA;
+    readonly launcher_pid: number;
+    readonly boot_nonce: string;
+    readonly executable: string;
+    readonly shutdown_secret: string;
+    readonly entrypoint: string | null;
+};
+export type DaemonMetadataLaunching = DaemonMetadataBase & {
+    readonly state: 'launching';
+    readonly pid: null;
+    readonly instance_id: null;
+    readonly management_host: null;
+    readonly management_port: null;
+};
+export type DaemonMetadataStarting = DaemonMetadataBase & {
+    readonly state: 'starting';
+    readonly pid: number;
+    readonly instance_id: null;
+    readonly management_host: null;
+    readonly management_port: null;
+};
+type DaemonMetadataServing = DaemonMetadataBase & {
+    readonly pid: number;
+    readonly instance_id: string;
+    readonly management_host: '127.0.0.1';
+    readonly management_port: number;
+};
+export type DaemonMetadataArmed = DaemonMetadataServing & {
+    readonly state: 'armed';
+};
+export type DaemonMetadataStopping = DaemonMetadataServing & {
+    readonly state: 'stopping';
+};
+export type DaemonMetadataV1 = DaemonMetadataLaunching | DaemonMetadataStarting | DaemonMetadataArmed | DaemonMetadataStopping;
+export type DaemonMetadataState = DaemonMetadataV1['state'];
+export type DaemonMetadataCodecErrorCode = 'invalid_metadata' | 'duplicate_key' | 'unknown_field' | 'missing_field' | 'invalid_utf8' | 'message_too_large';
+export declare class DaemonMetadataCodecError extends Error {
+    readonly code: DaemonMetadataCodecErrorCode;
+    readonly name = "DaemonMetadataCodecError";
+    constructor(code: DaemonMetadataCodecErrorCode, message?: string);
+}
+export declare function decodeDaemonShutdownSecret(value: string): Uint8Array;
+export declare function encodeDaemonShutdownSecret(value: Uint8Array): string;
+export declare function validateDaemonMetadataV1(value: unknown): DaemonMetadataV1;
+export declare function decodeDaemonMetadataV1(value: string | Uint8Array): DaemonMetadataV1;
+export declare function encodeDaemonMetadataV1(value: DaemonMetadataV1): string;
+export declare const parseDaemonMetadataV1: typeof decodeDaemonMetadataV1;
+export declare const serializeDaemonMetadataV1: typeof encodeDaemonMetadataV1;
+export {};

package/dist/daemon-control.js

@@ -0,0 +1,369 @@
+export const DAEMON_METADATA_SCHEMA = 'bungee-daemon-metadata-v1';
+export const DAEMON_METADATA_MAX_BYTES = 4 * 1024;
+export const DAEMON_SHUTDOWN_PATH = '/__bungee/internal/daemon/v1/shutdown';
+export const DAEMON_CONTROL_HTTP_PREFIX = '/__bungee/internal/daemon/';
+export const DAEMON_AUTHORIZATION_HEADER = 'authorization';
+export const DAEMON_BOOT_HEADER = 'x-bungee-daemon-boot';
+export const DAEMON_INSTANCE_HEADER = 'x-bungee-daemon-instance';
+export const DAEMON_PID_HEADER = 'x-bungee-daemon-pid';
+export const DAEMON_PROCESS_IDENTITY_MARKER_PREFIX = '--bungee-process-identity=';
+export class DaemonMetadataCodecError extends Error {
+    constructor(code, message = code) {
+        super(message);
+        this.code = code;
+        this.name = 'DaemonMetadataCodecError';
+    }
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const BASE64URL = /^[A-Za-z0-9_-]{43}$/;
+const METADATA_FIELDS = [
+    'schema', 'state', 'launcher_pid', 'boot_nonce', 'shutdown_secret', 'executable', 'entrypoint',
+    'pid', 'instance_id', 'management_host', 'management_port',
+];
+function fail(code, message) {
+    throw new DaemonMetadataCodecError(code, message);
+}
+function utf8ByteLength(value) {
+    let length = 0;
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code < 0x80)
+            length += 1;
+        else if (code < 0x800)
+            length += 2;
+        else if (code >= 0xd800 && code <= 0xdbff && index + 1 < value.length
+            && value.charCodeAt(index + 1) >= 0xdc00 && value.charCodeAt(index + 1) <= 0xdfff) {
+            length += 4;
+            index += 1;
+        }
+        else
+            length += 3;
+    }
+    return length;
+}
+function decodeUtf8(bytes) {
+    let result = '';
+    for (let index = 0; index < bytes.length;) {
+        const first = bytes[index++];
+        if (first < 0x80) {
+            result += String.fromCharCode(first);
+            continue;
+        }
+        const count = first >= 0xf0 ? 3 : first >= 0xe0 ? 2 : 1;
+        if (index + count > bytes.length)
+            fail('invalid_utf8', 'metadata is not valid UTF-8');
+        let code = first & (count === 3 ? 0x07 : count === 2 ? 0x0f : 0x1f);
+        for (let part = 0; part < count; part += 1) {
+            const next = bytes[index++];
+            if ((next & 0xc0) !== 0x80)
+                fail('invalid_utf8', 'metadata is not valid UTF-8');
+            code = (code << 6) | (next & 0x3f);
+        }
+        if ((count === 1 && code < 0x80) || (count === 2 && code < 0x800)
+            || (count === 3 && code < 0x10000) || code > 0x10ffff || (code >= 0xd800 && code <= 0xdfff)) {
+            fail('invalid_utf8', 'metadata is not valid UTF-8');
+        }
+        if (code <= 0xffff)
+            result += String.fromCharCode(code);
+        else {
+            const scalar = code - 0x10000;
+            result += String.fromCharCode(0xd800 + (scalar >> 10), 0xdc00 + (scalar & 0x3ff));
+        }
+    }
+    return result;
+}
+function stringEnd(value, start) {
+    for (let index = start + 1; index < value.length; index += 1) {
+        const char = value.charCodeAt(index);
+        if (char === 0x22)
+            return index + 1;
+        if (char < 0x20)
+            fail('invalid_metadata', 'metadata contains an invalid string');
+        if (char === 0x5c) {
+            index += 1;
+            if (index >= value.length)
+                fail('invalid_metadata', 'metadata contains an invalid escape');
+            if (value[index] === 'u')
+                index += 4;
+            if (index >= value.length)
+                fail('invalid_metadata', 'metadata contains an invalid escape');
+        }
+    }
+    fail('invalid_metadata', 'metadata contains an unterminated string');
+}
+function skipWhitespace(value, start) {
+    let index = start;
+    while (index < value.length && /\s/.test(value[index]))
+        index += 1;
+    return index;
+}
+function scanValue(value, start) {
+    const index = skipWhitespace(value, start);
+    if (value[index] === '"')
+        return stringEnd(value, index);
+    if (value[index] === '{') {
+        let cursor = skipWhitespace(value, index + 1);
+        const keys = new Set();
+        if (value[cursor] === '}')
+            return cursor + 1;
+        while (true) {
+            if (value[cursor] !== '"')
+                fail('invalid_metadata', 'object key must be a string');
+            const end = stringEnd(value, cursor);
+            let key;
+            try {
+                key = JSON.parse(value.slice(cursor, end));
+            }
+            catch {
+                fail('invalid_metadata', 'object key is not valid JSON');
+            }
+            if (keys.has(key))
+                fail('duplicate_key', `duplicate object key: ${key}`);
+            keys.add(key);
+            cursor = skipWhitespace(value, end);
+            if (value[cursor] !== ':')
+                fail('invalid_metadata', 'object key is missing a colon');
+            cursor = scanValue(value, cursor + 1);
+            cursor = skipWhitespace(value, cursor);
+            if (value[cursor] === '}')
+                return cursor + 1;
+            if (value[cursor] !== ',')
+                fail('invalid_metadata', 'object is missing a comma');
+            cursor = skipWhitespace(value, cursor + 1);
+        }
+    }
+    if (value[index] === '[') {
+        let cursor = skipWhitespace(value, index + 1);
+        if (value[cursor] === ']')
+            return cursor + 1;
+        while (true) {
+            cursor = scanValue(value, cursor);
+            cursor = skipWhitespace(value, cursor);
+            if (value[cursor] === ']')
+                return cursor + 1;
+            if (value[cursor] !== ',')
+                fail('invalid_metadata', 'array is missing a comma');
+            cursor = skipWhitespace(value, cursor + 1);
+        }
+    }
+    let cursor = index;
+    while (cursor < value.length && !',]}'.includes(value[cursor]) && !/\s/.test(value[cursor]))
+        cursor += 1;
+    if (cursor === index)
+        fail('invalid_metadata', 'metadata contains an invalid value');
+    return cursor;
+}
+function assertNoDuplicateKeys(value) {
+    const end = scanValue(value, 0);
+    if (skipWhitespace(value, end) !== value.length)
+        fail('invalid_metadata', 'metadata contains trailing data');
+}
+function base64Value(character) {
+    if (character >= 'A' && character <= 'Z')
+        return character.charCodeAt(0) - 65;
+    if (character >= 'a' && character <= 'z')
+        return character.charCodeAt(0) - 71;
+    if (character >= '0' && character <= '9')
+        return character.charCodeAt(0) + 4;
+    if (character === '-')
+        return 62;
+    if (character === '_')
+        return 63;
+    return -1;
+}
+function encodeSecret(value) {
+    const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+    let result = '';
+    for (let index = 0; index < value.length; index += 3) {
+        const a = value[index];
+        const b = index + 1 < value.length ? value[index + 1] : 0;
+        const c = index + 2 < value.length ? value[index + 2] : 0;
+        result += alphabet[a >> 2] + alphabet[((a & 3) << 4) | (b >> 4)];
+        if (index + 1 < value.length)
+            result += alphabet[((b & 15) << 2) | (c >> 6)];
+        if (index + 2 < value.length)
+            result += alphabet[c & 63];
+    }
+    return result;
+}
+function decodeSecret(value) {
+    if (!BASE64URL.test(value))
+        fail('invalid_metadata', 'shutdown_secret must be canonical base64url');
+    const result = new Uint8Array(32);
+    let output = 0;
+    for (let index = 0; index < value.length; index += 4) {
+        const a = base64Value(value[index]);
+        const b = base64Value(value[index + 1]);
+        const c = index + 2 < value.length ? base64Value(value[index + 2]) : 0;
+        const d = index + 3 < value.length ? base64Value(value[index + 3]) : 0;
+        if (a < 0 || b < 0 || c < 0 || d < 0)
+            fail('invalid_metadata', 'shutdown_secret must be canonical base64url');
+        if (output < 32)
+            result[output++] = (a << 2) | (b >> 4);
+        if (output < 32 && index + 2 < value.length)
+            result[output++] = ((b & 15) << 4) | (c >> 2);
+        if (output < 32 && index + 3 < value.length)
+            result[output++] = ((c & 3) << 6) | d;
+    }
+    if (encodeSecret(result) !== value)
+        fail('invalid_metadata', 'shutdown_secret is not canonical base64url');
+    return result;
+}
+export function decodeDaemonShutdownSecret(value) {
+    return decodeSecret(value);
+}
+export function encodeDaemonShutdownSecret(value) {
+    if (value.byteLength !== 32)
+        fail('invalid_metadata', 'shutdown_secret must decode to 32 bytes');
+    return encodeSecret(value);
+}
+function plain(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)
+        || (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)) {
+        fail('invalid_metadata', 'metadata must be a plain object');
+    }
+    return value;
+}
+function exactFields(value) {
+    const actual = Object.keys(value).sort();
+    const expected = [...METADATA_FIELDS].sort();
+    if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index])) {
+        const unknown = actual.find((key) => !expected.includes(key));
+        if (unknown !== undefined)
+            fail('unknown_field', 'metadata fields are not exact');
+        fail(actual.length < expected.length ? 'missing_field' : 'invalid_metadata', 'metadata fields are not exact');
+    }
+}
+function stringField(value, field) {
+    if (typeof value[field] !== 'string')
+        fail('invalid_metadata', `${field} must be a string`);
+    return value[field];
+}
+function numberField(value, field) {
+    if (typeof value[field] !== 'number' || !Number.isSafeInteger(value[field])) {
+        fail('invalid_metadata', `${field} must be a safe integer`);
+    }
+    return value[field];
+}
+function uuidField(value, field) {
+    const result = stringField(value, field);
+    if (!UUID.test(result))
+        fail('invalid_metadata', `${field} must be a canonical lowercase UUID`);
+    return result;
+}
+function absolutePath(value) {
+    return value.startsWith('/') || /^[A-Za-z]:[\\/]/.test(value) || value.startsWith('\\\\');
+}
+function entrypointField(value) {
+    const entrypoint = value.entrypoint;
+    if (entrypoint === null)
+        return null;
+    if (typeof entrypoint !== 'string' || entrypoint.length === 0 || entrypoint.trim() !== entrypoint
+        || entrypoint.includes('\0') || !absolutePath(entrypoint)) {
+        fail('invalid_metadata', 'entrypoint must be null or an absolute non-empty path');
+    }
+    return entrypoint;
+}
+function nullField(value, field) {
+    if (value[field] !== null)
+        fail('invalid_metadata', `${field} must be null for this state`);
+    return null;
+}
+function positivePid(value, field) {
+    const result = numberField(value, field);
+    if (result <= 0)
+        fail('invalid_metadata', `${field} must be positive`);
+    return result;
+}
+function managementPort(value) {
+    const result = numberField(value, 'management_port');
+    if (result < 1 || result > 65535)
+        fail('invalid_metadata', 'management_port must be a valid TCP port');
+    return result;
+}
+function managementHost(value) {
+    const result = stringField(value, 'management_host');
+    if (result !== '127.0.0.1')
+        fail('invalid_metadata', 'management_host must be 127.0.0.1');
+    return result;
+}
+function validate(value) {
+    const input = plain(value);
+    exactFields(input);
+    const schema = stringField(input, 'schema');
+    const state = stringField(input, 'state');
+    const launcherPid = positivePid(input, 'launcher_pid');
+    const bootNonce = uuidField(input, 'boot_nonce');
+    const executable = stringField(input, 'executable');
+    const secret = stringField(input, 'shutdown_secret');
+    const entrypoint = entrypointField(input);
+    if (schema !== DAEMON_METADATA_SCHEMA)
+        fail('invalid_metadata', 'schema is unsupported');
+    if (executable.length === 0 || executable.trim() !== executable || executable.includes('\0')) {
+        fail('invalid_metadata', 'executable must be a non-empty unpadded string');
+    }
+    decodeSecret(secret);
+    const base = {
+        schema: DAEMON_METADATA_SCHEMA,
+        launcher_pid: launcherPid,
+        boot_nonce: bootNonce,
+        executable,
+        shutdown_secret: secret,
+        entrypoint,
+    };
+    let result;
+    if (state === 'launching') {
+        result = Object.freeze({
+            ...base, state, pid: nullField(input, 'pid'), instance_id: nullField(input, 'instance_id'),
+            management_host: nullField(input, 'management_host'), management_port: nullField(input, 'management_port'),
+        });
+    }
+    else if (state === 'starting') {
+        result = Object.freeze({
+            ...base, state, pid: positivePid(input, 'pid'), instance_id: nullField(input, 'instance_id'),
+            management_host: nullField(input, 'management_host'), management_port: nullField(input, 'management_port'),
+        });
+    }
+    else if (state === 'armed' || state === 'stopping') {
+        result = Object.freeze({
+            ...base, state, pid: positivePid(input, 'pid'), instance_id: uuidField(input, 'instance_id'),
+            management_host: managementHost(input), management_port: managementPort(input),
+        });
+    }
+    else {
+        fail('invalid_metadata', 'state is invalid');
+    }
+    if (utf8ByteLength(JSON.stringify(result)) > DAEMON_METADATA_MAX_BYTES) {
+        fail('message_too_large', 'daemon metadata exceeds 4 KiB');
+    }
+    return result;
+}
+export function validateDaemonMetadataV1(value) {
+    return validate(value);
+}
+export function decodeDaemonMetadataV1(value) {
+    if (value instanceof Uint8Array && value.byteLength > DAEMON_METADATA_MAX_BYTES) {
+        fail('message_too_large', 'daemon metadata exceeds 4 KiB');
+    }
+    const text = typeof value === 'string' ? value : decodeUtf8(value);
+    if (utf8ByteLength(text) > DAEMON_METADATA_MAX_BYTES)
+        fail('message_too_large', 'daemon metadata exceeds 4 KiB');
+    try {
+        assertNoDuplicateKeys(text);
+        return validate(JSON.parse(text));
+    }
+    catch (error) {
+        if (error instanceof DaemonMetadataCodecError)
+            throw error;
+        fail('invalid_metadata', 'metadata is not valid JSON');
+    }
+}
+export function encodeDaemonMetadataV1(value) {
+    const metadata = validate(value);
+    const result = JSON.stringify(metadata);
+    if (utf8ByteLength(result) > DAEMON_METADATA_MAX_BYTES)
+        fail('message_too_large', 'daemon metadata exceeds 4 KiB');
+    return result;
+}
+export const parseDaemonMetadataV1 = decodeDaemonMetadataV1;
+export const serializeDaemonMetadataV1 = encodeDaemonMetadataV1;

package/dist/daemon-file.d.ts

@@ -0,0 +1,84 @@
+import type { DaemonMetadataState, DaemonMetadataV1 } from './daemon-control.js';
+export type DaemonFileErrorCode = 'race' | 'path' | 'symlink' | 'containment' | 'directory' | 'owner' | 'permissions' | 'file' | 'limit' | 'invalid' | 'acl' | 'state' | 'secret' | 'transition';
+export declare class DaemonFileError extends Error {
+    readonly code: DaemonFileErrorCode;
+    readonly name = "DaemonFileError";
+    constructor(code: DaemonFileErrorCode, message?: string, cause?: unknown);
+}
+export type WindowsAclEntry = {
+    readonly sid: string;
+    readonly access: 'allow' | 'deny';
+    readonly rights: number;
+    readonly inheritance: number;
+    readonly propagation: number;
+    readonly inherited: boolean;
+};
+export type WindowsAclSnapshot = {
+    readonly currentSid: string;
+    readonly entries: readonly WindowsAclEntry[];
+};
+export type WindowsAclAdapter = {
+    readonly read: (path: string) => Promise<WindowsAclSnapshot>;
+    readonly set: (path: string, currentSid: string, kind?: 'directory' | 'file') => Promise<void>;
+};
+/** Test-only evidence points for the create-launching primitive. */
+export type DaemonFileTestStage = 'runtime_components' | 'runtime_lstat' | 'runtime_mkdir' | 'runtime_created_lstat' | 'runtime_realpath' | 'profile_realpath' | 'directory_acl' | 'target_components' | 'target_lstat' | 'target_realpath' | 'create_open' | 'descriptor_stat' | 'verify_lstat' | 'file_acl' | 'file_write' | 'file_sync' | 'file_close';
+export type DaemonFileOptions = {
+    /** The trusted, canonical runtime root. The only accepted target is root/daemon.json. */
+    readonly runtimeDirectory: string;
+    /** Test-only platform injection; production leaves this unset. */
+    readonly platform?: NodeJS.Platform;
+    readonly windowsAcl?: WindowsAclAdapter;
+    /** Deterministic race injection for the metadata primitive tests. */
+    readonly testHooks?: {
+        readonly onStage?: (stage: DaemonFileTestStage) => void;
+        readonly afterOpen?: (target: string) => void | Promise<void>;
+        readonly afterInitialStat?: (target: string) => void | Promise<void>;
+        readonly rename?: (from: string, to: string) => Promise<void>;
+        readonly sleep?: (milliseconds: number) => Promise<void>;
+    };
+};
+/** Formats only the bounded, allowlisted fields safe for exposing a Windows ACL failure. */
+export declare function formatDaemonFileAclError(error: unknown): string | null;
+/** @internal source-test probe; not re-exported from the package root. */
+export declare function __testSelectWindowsAclExecutable(environment: NodeJS.ProcessEnv): string;
+/** @internal source-test probe; not re-exported from the package root. */
+export declare function __testReadWindowsAcl(path: string, deadlineMs?: number): Promise<WindowsAclSnapshot>;
+/** @internal source-test probe; not re-exported from the package root. */
+export declare function __testEnsureWindowsAcl(path: string, kind: 'directory' | 'file', deadlineMs?: number): Promise<void>;
+/** @internal source-test probe; not re-exported from the package root. */
+export declare function __testWindowsAclIsSecure(snapshot: WindowsAclSnapshot, kind: 'directory' | 'file'): boolean;
+/** @internal source-test factory; not re-exported from the package root. */
+export declare function __testCreateDaemonFileAclError(overrides?: Readonly<Record<string, unknown>>): DaemonFileError;
+export declare function readDaemonMetadataFile(path: string, options: DaemonFileOptions): Promise<DaemonMetadataV1>;
+export type DaemonMetadataTransition = {
+    readonly expectedBootNonce: string;
+    readonly expectedState: DaemonMetadataState;
+    readonly expectedShutdownSecret: string;
+    readonly next: DaemonMetadataV1;
+};
+export declare function transitionDaemonMetadataFile(path: string, transition: DaemonMetadataTransition, options: DaemonFileOptions): Promise<DaemonMetadataV1>;
+export type DaemonMetadataDeleteExpectation = {
+    readonly bootNonce: string;
+    readonly state: DaemonMetadataState;
+    readonly shutdownSecret: string;
+};
+export type DaemonMetadataMasterDeleteExpectation = {
+    readonly bootNonce: string;
+    readonly shutdownSecret: string;
+    readonly pid: number;
+};
+/**
+ * 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 declare function deleteDaemonMetadataAfterOwnerExit(path: string, expected: DaemonMetadataDeleteExpectation, options: DaemonFileOptions): Promise<boolean>;
+export type DaemonMetadataLauncherDeleteExpectation = {
+    readonly bootNonce: string;
+    readonly shutdownSecret: string;
+};
+/** Deletes a launch record owned by the current CLI process. */
+export declare function deleteDaemonMetadataForLauncher(path: string, expected: DaemonMetadataLauncherDeleteExpectation, options: DaemonFileOptions): Promise<boolean>;
+/** Deletes the current master's stopping record after runtime cleanup succeeds. */
+export declare function deleteDaemonMetadataForMaster(path: string, expected: DaemonMetadataMasterDeleteExpectation, options: DaemonFileOptions): Promise<boolean>;
+export declare function createLaunchingDaemonMetadataFile(path: string, metadata: DaemonMetadataV1, options: DaemonFileOptions): Promise<void>;