@rynx-ai/daemon 0.1.0 → 0.1.9

package/dist/direct-runtime-authenticator.js

@@ -0,0 +1,127 @@
+import { createHash, createPublicKey, randomBytes, randomUUID, verify, } from "node:crypto";
+import { DIRECT_RUNTIME_BINDING_PROTOCOL, DIRECT_RUNTIME_BROWSER_SURFACE_BINDING_PROTOCOL, encodeClientAuthenticateCanonical, encodeClientAuthenticateProofPayload, encodeServerHelloCanonical, parseServerAccepted, parseServerHello, } from "@rynx-ai/protocol/direct-runtime";
+/** Daemon-side proof verification shared by Direct control and Browser Surface bindings. */
+export class DaemonDirectRuntimeAuthenticator {
+    identity;
+    runtime;
+    access;
+    constructor(identity, runtime, access) {
+        this.identity = identity;
+        this.runtime = runtime;
+        this.access = access;
+    }
+    createServerHello({ channelBinding, role, signal, }) {
+        signal.throwIfAborted();
+        const status = this.runtime.status();
+        if (status.daemonId !== this.identity.installationId) {
+            throw new Error("daemon Runtime identity does not match its installation identity");
+        }
+        const fields = {
+            type: "server.hello",
+            role,
+            daemonId: status.daemonId,
+            daemonInstanceId: status.daemonInstanceId,
+            identityPublicKey: this.identity.publicKey,
+            nonce: randomBytes(32).toString("base64url"),
+            bindingProtocolVersion: bindingProtocol(role).currentVersion,
+            minimumCompatibleBindingVersion: bindingProtocol(role).minimumCompatibleVersion,
+            coreProtocolVersion: status.coreProtocolVersion,
+            minimumCompatibleCoreVersion: status.minimumCompatibleCoreVersion,
+        };
+        return parseServerHello({
+            ...fields,
+            signature: this.identity.signDirectRuntimeServerHello(channelBinding, fields),
+        });
+    }
+    authenticate({ channelBinding, role, serverHello, clientAuthenticate, signal, }) {
+        signal.throwIfAborted();
+        if (clientAuthenticate.role !== role || serverHello.role !== role) {
+            throw new Error("unsupported Direct Runtime channel role");
+        }
+        if (role === "browser-surface" && clientAuthenticate.mode !== "connect") {
+            throw new Error("Browser Surface channels require an existing Direct Runtime grant");
+        }
+        if (clientAuthenticate.daemonId !== serverHello.daemonId ||
+            clientAuthenticate.daemonInstanceId !== serverHello.daemonInstanceId ||
+            clientAuthenticate.bindingProtocolVersion <
+                serverHello.minimumCompatibleBindingVersion ||
+            clientAuthenticate.bindingProtocolVersion > serverHello.bindingProtocolVersion ||
+            clientAuthenticate.coreProtocolVersion < serverHello.minimumCompatibleCoreVersion ||
+            clientAuthenticate.coreProtocolVersion > serverHello.coreProtocolVersion) {
+            throw new Error("Direct Runtime authentication negotiation does not match server hello");
+        }
+        const helloFields = withoutSignature(serverHello);
+        const authenticateFields = withoutSignature(clientAuthenticate);
+        const helloHash = sha256(encodeServerHelloCanonical(helloFields));
+        const authenticateHash = sha256(encodeClientAuthenticateCanonical(authenticateFields));
+        const clientPublicKey = createEd25519PublicKey(clientAuthenticate.clientPublicKey);
+        const clientProof = encodeClientAuthenticateProofPayload(channelBinding, helloHash, authenticateFields);
+        if (!verify(null, clientProof, clientPublicKey, Buffer.from(clientAuthenticate.signature, "base64url"))) {
+            throw new Error("Direct Runtime client proof is invalid");
+        }
+        signal.throwIfAborted();
+        const grant = clientAuthenticate.mode === "enroll"
+            ? this.access.redeemPairingClaim({
+                claimId: clientAuthenticate.claimId,
+                claimSecret: clientAuthenticate.claimSecret,
+                clientId: clientAuthenticate.clientId,
+                clientPublicKey: clientAuthenticate.clientPublicKey,
+            })
+            : this.access.resolveActiveGrant({
+                grantId: clientAuthenticate.grantId,
+                clientId: clientAuthenticate.clientId,
+                clientPublicKey: clientAuthenticate.clientPublicKey,
+            });
+        signal.throwIfAborted();
+        const acceptedFields = {
+            type: "server.accepted",
+            role,
+            daemonId: serverHello.daemonId,
+            daemonInstanceId: serverHello.daemonInstanceId,
+            bindingProtocolVersion: clientAuthenticate.bindingProtocolVersion,
+            coreProtocolVersion: clientAuthenticate.coreProtocolVersion,
+            channelId: randomUUID(),
+            grantId: grant.grantId,
+            clientId: grant.clientId,
+            authorities: ["daemon.full"],
+        };
+        const accepted = parseServerAccepted({
+            ...acceptedFields,
+            signature: this.identity.signDirectRuntimeServerAccepted(channelBinding, helloHash, authenticateHash, acceptedFields),
+        });
+        return {
+            peer: {
+                clientId: grant.clientId,
+                grantId: grant.grantId,
+                subject: {
+                    subjectId: `client:${grant.clientId}`,
+                    effectiveAuthorities: [...grant.authorities],
+                },
+            },
+            accepted,
+        };
+    }
+}
+function bindingProtocol(role) {
+    return role === "control"
+        ? DIRECT_RUNTIME_BINDING_PROTOCOL
+        : DIRECT_RUNTIME_BROWSER_SURFACE_BINDING_PROTOCOL;
+}
+function withoutSignature(value) {
+    const { signature: _signature, ...fields } = value;
+    return fields;
+}
+function sha256(value) {
+    return Uint8Array.from(createHash("sha256").update(value).digest());
+}
+function createEd25519PublicKey(encoded) {
+    const key = createPublicKey({
+        key: Buffer.from(encoded, "base64url"),
+        format: "der",
+        type: "spki",
+    });
+    if (key.asymmetricKeyType !== "ed25519") {
+        throw new Error("Direct Runtime client key must use Ed25519");
+    }
+    return key;
+}

package/dist/direct-runtime-config.d.ts

@@ -0,0 +1,20 @@
+export interface DirectRuntimeConfig {
+    bindHost: string;
+    /** Preferred port. The daemon replaces this with the actual bound port. */
+    port: number;
+    /** Present only in automatic mode. Candidates are tried after `port`. */
+    fallbackPorts?: readonly number[];
+    /** The preferred port came from advisory persisted state, so any bind failure may skip it. */
+    preferredPortIsPersistedFallback?: boolean;
+    /** Present only in automatic mode. Records the successfully bound port. */
+    recordListeningPort?: (port: number) => Promise<void>;
+}
+/**
+ * Resolve the daemon's always-available Direct Runtime listener.
+ *
+ * Normal operation has no certificate, advertised-route, or enablement
+ * configuration. The two RYNX_RUNTIME_* inputs are intentionally narrow
+ * deployment/test seams for overriding the socket bind only.
+ */
+export declare function loadDirectRuntimeConfig(env?: NodeJS.ProcessEnv): Promise<DirectRuntimeConfig>;
+export declare function directRuntimeFallbackPortFile(env?: NodeJS.ProcessEnv): string;

package/dist/direct-runtime-config.js

@@ -0,0 +1,101 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { rynxHome } from "@rynx-ai/core";
+const DEFAULT_BIND_HOST = "0.0.0.0";
+const DEFAULT_PORT = 7443;
+const FALLBACK_PORT_FILE = "direct-runtime-port";
+/**
+ * Resolve the daemon's always-available Direct Runtime listener.
+ *
+ * Normal operation has no certificate, advertised-route, or enablement
+ * configuration. The two RYNX_RUNTIME_* inputs are intentionally narrow
+ * deployment/test seams for overriding the socket bind only.
+ */
+export async function loadDirectRuntimeConfig(env = process.env) {
+    const bindHost = parseBindHost(env.RYNX_RUNTIME_BIND_HOST);
+    const explicitPort = parseExplicitPort(env.RYNX_RUNTIME_PORT);
+    if (explicitPort !== undefined)
+        return { bindHost, port: explicitPort };
+    const persistedPort = await readPersistedFallbackPort(env);
+    return {
+        bindHost,
+        port: persistedPort ?? DEFAULT_PORT,
+        fallbackPorts: persistedPort === undefined
+            ? [0]
+            : [DEFAULT_PORT, 0],
+        ...(persistedPort === undefined
+            ? {}
+            : { preferredPortIsPersistedFallback: true }),
+        recordListeningPort: (port) => persistFallbackPort(port, env),
+    };
+}
+export function directRuntimeFallbackPortFile(env = process.env) {
+    return join(rynxHome(env), FALLBACK_PORT_FILE);
+}
+function parseBindHost(value) {
+    const host = value?.trim() || DEFAULT_BIND_HOST;
+    if (/\s|\//.test(host)) {
+        throw new Error("RYNX_RUNTIME_BIND_HOST is invalid");
+    }
+    return host;
+}
+function parseExplicitPort(value) {
+    if (value === undefined || value.trim() === "")
+        return undefined;
+    if (!/^\d{1,5}$/.test(value)) {
+        throw new Error("RYNX_RUNTIME_PORT must be an integer from 1 to 65535");
+    }
+    const port = Number(value);
+    if (port < 1 || port > 65_535) {
+        throw new Error("RYNX_RUNTIME_PORT must be an integer from 1 to 65535");
+    }
+    return port;
+}
+async function readPersistedFallbackPort(env) {
+    let value;
+    try {
+        value = (await readFile(directRuntimeFallbackPortFile(env), "utf8")).trim();
+    }
+    catch (error) {
+        if (hasCode(error, "ENOENT"))
+            return undefined;
+        throw error;
+    }
+    if (!/^\d{1,5}$/.test(value))
+        return undefined;
+    const port = Number(value);
+    return port >= 1 && port <= 65_535 && port !== DEFAULT_PORT
+        ? port
+        : undefined;
+}
+async function persistFallbackPort(port, env) {
+    if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+        throw new Error("Direct Runtime listening port must be an integer from 1 to 65535");
+    }
+    const file = directRuntimeFallbackPortFile(env);
+    if (port === DEFAULT_PORT) {
+        await rm(file, { force: true });
+        return;
+    }
+    const directory = rynxHome(env);
+    const temporary = `${file}.tmp-${process.pid}-${randomUUID()}`;
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    try {
+        await writeFile(temporary, `${port}\n`, {
+            encoding: "utf8",
+            flag: "wx",
+            mode: 0o600,
+        });
+        await rename(temporary, file);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+function hasCode(error, code) {
+    return Boolean(error &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === code);
+}

package/dist/embedded-browser-profile-cleanup.d.ts

@@ -0,0 +1,58 @@
+import { type SessionBrowserHost, type SessionBrowserHostCreateInput, type SessionBrowserHostHandle } from "@rynx-ai/server";
+export interface EmbeddedBrowserProfileStateSnapshot {
+    ownedSessionIds: string[];
+    pendingDeletionSessionIds: string[];
+}
+export interface EmbeddedBrowserProfileStateStoreOptions {
+    /** Defaults to ~/.rynx/browser/profiles/embedded-electron. */
+    rootDir?: string;
+}
+/** Protected, atomically replaced ownership/tombstone state for Electron profiles. */
+export declare class EmbeddedBrowserProfileStateStore {
+    private readonly rootDir;
+    private readonly statePath;
+    constructor(options?: EmbeddedBrowserProfileStateStoreOptions);
+    snapshot(): EmbeddedBrowserProfileStateSnapshot;
+    owns(sessionId: string): boolean;
+    /**
+     * Conservatively records that this daemon may own an Electron profile.
+     * The marker is durable before browser.create is dispatched, so an
+     * ambiguous Host outcome can still be cleaned up with the Session.
+     * Returns true only when this call introduced the marker.
+     */
+    markPossibleOwnership(sessionId: string): boolean;
+    /** Removes only a create-intent proven not to have produced Host state. */
+    discardCreateIntent(sessionId: string): void;
+    markPendingDeletion(sessionId: string): boolean;
+    confirmDeleted(sessionId: string): void;
+    private readState;
+    private writeState;
+}
+export interface ConnectedDesktopBrowserHost extends SessionBrowserHost {
+    readonly connected: boolean;
+    onConnected(listener: () => void | Promise<void>): () => void;
+    deleteSessionData(sessionId: string): Promise<void>;
+}
+export interface DurableEmbeddedBrowserProfileHostOptions {
+    store?: EmbeddedBrowserProfileStateStore;
+    warn?: (message: string) => void;
+}
+/**
+ * Adds daemon-durable Electron profile ownership to the ephemeral Desktop Host.
+ * Delete failures intentionally become retryable tombstones so logical Session
+ * deletion can finish while the desktop app is absent.
+ */
+export declare class DurableEmbeddedBrowserProfileHost implements SessionBrowserHost {
+    private readonly desktop;
+    private readonly store;
+    private readonly warn;
+    private operations;
+    private readonly unsubscribe;
+    constructor(desktop: ConnectedDesktopBrowserHost, options?: DurableEmbeddedBrowserProfileHostOptions);
+    createBrowser(input: SessionBrowserHostCreateInput): Promise<SessionBrowserHostHandle>;
+    deleteSessionData(sessionId: string): Promise<void>;
+    flushPendingDeletions(): Promise<void>;
+    dispose(): void;
+    private tryDelete;
+    private exclusive;
+}

package/dist/embedded-browser-profile-cleanup.js

@@ -0,0 +1,338 @@
+import { randomBytes } from "node:crypto";
+import { chmodSync, closeSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { constants as fsConstants } from "node:fs";
+import { join, resolve } from "node:path";
+import { rynxHome } from "@rynx-ai/core";
+import { DesktopBrowserHostAbsentError, SessionBrowserHostError, } from "@rynx-ai/server";
+const STATE_FILE = "profile-ownership.json";
+const STATE_KIND = "rynx-embedded-browser-profile-ownership";
+const MAX_STATE_BYTES = 64 * 1_024;
+const MAX_SESSION_IDS = 4_096;
+const MAX_SESSION_ID_CHARS = 512;
+const SESSION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._~-]*$/;
+/** Protected, atomically replaced ownership/tombstone state for Electron profiles. */
+export class EmbeddedBrowserProfileStateStore {
+    rootDir;
+    statePath;
+    constructor(options = {}) {
+        this.rootDir = options.rootDir === undefined
+            ? ensureDefaultStoreRoot()
+            : resolve(options.rootDir);
+        this.statePath = join(this.rootDir, STATE_FILE);
+        ensureProtectedDirectory(this.rootDir);
+        this.readState();
+    }
+    snapshot() {
+        const state = this.readState();
+        return {
+            ownedSessionIds: [...state.ownedSessionIds],
+            pendingDeletionSessionIds: [...state.pendingDeletionSessionIds],
+        };
+    }
+    owns(sessionId) {
+        requireSessionId(sessionId);
+        return this.readState().ownedSessionIds.includes(sessionId);
+    }
+    /**
+     * Conservatively records that this daemon may own an Electron profile.
+     * The marker is durable before browser.create is dispatched, so an
+     * ambiguous Host outcome can still be cleaned up with the Session.
+     * Returns true only when this call introduced the marker.
+     */
+    markPossibleOwnership(sessionId) {
+        requireSessionId(sessionId);
+        const state = this.readState();
+        if (state.pendingDeletionSessionIds.includes(sessionId)) {
+            throw new Error("Embedded Browser profile is pending deletion");
+        }
+        if (state.ownedSessionIds.includes(sessionId))
+            return false;
+        state.ownedSessionIds.push(sessionId);
+        this.writeState(state);
+        return true;
+    }
+    /** Removes only a create-intent proven not to have produced Host state. */
+    discardCreateIntent(sessionId) {
+        requireSessionId(sessionId);
+        const state = this.readState();
+        if (state.pendingDeletionSessionIds.includes(sessionId)) {
+            throw new Error("Embedded Browser profile is pending deletion");
+        }
+        const ownedSessionIds = state.ownedSessionIds.filter((value) => value !== sessionId);
+        if (ownedSessionIds.length === state.ownedSessionIds.length)
+            return;
+        this.writeState({ ...state, ownedSessionIds });
+    }
+    markPendingDeletion(sessionId) {
+        requireSessionId(sessionId);
+        const state = this.readState();
+        if (!state.ownedSessionIds.includes(sessionId))
+            return false;
+        if (!state.pendingDeletionSessionIds.includes(sessionId)) {
+            state.pendingDeletionSessionIds.push(sessionId);
+            this.writeState(state);
+        }
+        return true;
+    }
+    confirmDeleted(sessionId) {
+        requireSessionId(sessionId);
+        const state = this.readState();
+        const ownedSessionIds = state.ownedSessionIds.filter((value) => value !== sessionId);
+        const pendingDeletionSessionIds = state.pendingDeletionSessionIds.filter((value) => value !== sessionId);
+        if (ownedSessionIds.length === state.ownedSessionIds.length &&
+            pendingDeletionSessionIds.length === state.pendingDeletionSessionIds.length)
+            return;
+        this.writeState({ ...state, ownedSessionIds, pendingDeletionSessionIds });
+    }
+    readState() {
+        if (!pathEntryExists(this.statePath))
+            return emptyState();
+        rejectSymlinkOrNonFile(this.statePath);
+        chmodSync(this.statePath, 0o600);
+        const descriptor = openNoFollow(this.statePath, fsConstants.O_RDONLY);
+        try {
+            const stat = fstatSync(descriptor);
+            if (!stat.isFile() || stat.size > MAX_STATE_BYTES) {
+                throw new Error("Embedded Browser profile state is not a bounded regular file");
+            }
+            let value;
+            try {
+                value = JSON.parse(readFileSync(descriptor, "utf8"));
+            }
+            catch {
+                throw new Error("Embedded Browser profile state is invalid JSON");
+            }
+            return parseState(value);
+        }
+        finally {
+            closeSync(descriptor);
+        }
+    }
+    writeState(value) {
+        const state = parseState({
+            ...value,
+            ownedSessionIds: [...value.ownedSessionIds].sort(),
+            pendingDeletionSessionIds: [...value.pendingDeletionSessionIds].sort(),
+        });
+        const encoded = Buffer.from(`${JSON.stringify(state)}\n`, "utf8");
+        if (encoded.byteLength > MAX_STATE_BYTES) {
+            throw new Error("Embedded Browser profile state exceeds its durable size bound");
+        }
+        ensureProtectedDirectory(this.rootDir);
+        rejectSymlinkOrNonFile(this.statePath);
+        const temporaryPath = join(this.rootDir, `.${STATE_FILE}.${process.pid}.${randomBytes(12).toString("hex")}.tmp`);
+        let descriptor;
+        try {
+            descriptor = openNoFollow(temporaryPath, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL, 0o600);
+            writeFileSync(descriptor, encoded);
+            fsyncSync(descriptor);
+            closeSync(descriptor);
+            descriptor = undefined;
+            renameSync(temporaryPath, this.statePath);
+            chmodSync(this.statePath, 0o600);
+            fsyncDirectory(this.rootDir);
+        }
+        finally {
+            if (descriptor !== undefined)
+                closeSync(descriptor);
+            rmSync(temporaryPath, { force: true });
+        }
+    }
+}
+/**
+ * Adds daemon-durable Electron profile ownership to the ephemeral Desktop Host.
+ * Delete failures intentionally become retryable tombstones so logical Session
+ * deletion can finish while the desktop app is absent.
+ */
+export class DurableEmbeddedBrowserProfileHost {
+    desktop;
+    store;
+    warn;
+    operations = Promise.resolve();
+    unsubscribe;
+    constructor(desktop, options = {}) {
+        this.desktop = desktop;
+        this.store = options.store ?? new EmbeddedBrowserProfileStateStore();
+        this.warn = options.warn ?? (() => undefined);
+        this.unsubscribe = desktop.onConnected(() => this.flushPendingDeletions());
+        if (desktop.connected)
+            queueMicrotask(() => void this.flushPendingDeletions());
+    }
+    createBrowser(input) {
+        return this.exclusive(async () => {
+            if (this.store.snapshot().pendingDeletionSessionIds.includes(input.sessionId)) {
+                throw new SessionBrowserHostError("unavailable", "Embedded Browser profile deletion is still pending");
+            }
+            const introducedCreateIntent = this.store.markPossibleOwnership(input.sessionId);
+            try {
+                return await this.desktop.createBrowser(input);
+            }
+            catch (error) {
+                if (introducedCreateIntent && isDefinitiveCreateRejection(error)) {
+                    this.store.discardCreateIntent(input.sessionId);
+                }
+                throw error;
+            }
+        });
+    }
+    deleteSessionData(sessionId) {
+        return this.exclusive(async () => {
+            if (!this.store.markPendingDeletion(sessionId))
+                return;
+            if (!this.desktop.connected)
+                return;
+            await this.tryDelete(sessionId);
+        });
+    }
+    flushPendingDeletions() {
+        return this.exclusive(async () => {
+            if (!this.desktop.connected)
+                return;
+            const pending = this.store.snapshot().pendingDeletionSessionIds;
+            for (const sessionId of pending) {
+                if (!this.desktop.connected)
+                    return;
+                await this.tryDelete(sessionId);
+            }
+        });
+    }
+    dispose() {
+        this.unsubscribe();
+    }
+    async tryDelete(sessionId) {
+        try {
+            await this.desktop.deleteSessionData(sessionId);
+            this.store.confirmDeleted(sessionId);
+        }
+        catch (error) {
+            try {
+                this.warn(`Embedded Browser profile deletion will retry for ${sessionId}: ${errorMessage(error)}`);
+            }
+            catch {
+                // Diagnostics must not make a durable deletion tombstone non-retryable.
+            }
+        }
+    }
+    exclusive(operation) {
+        const result = this.operations.then(operation, operation);
+        this.operations = result.then(() => undefined, () => undefined);
+        return result;
+    }
+}
+function emptyState() {
+    return {
+        schemaVersion: 1,
+        kind: STATE_KIND,
+        ownedSessionIds: [],
+        pendingDeletionSessionIds: [],
+    };
+}
+function parseState(value) {
+    if (!isRecord(value))
+        throw new Error("Embedded Browser profile state must be an object");
+    const keys = Object.keys(value).sort();
+    const expected = ["kind", "ownedSessionIds", "pendingDeletionSessionIds", "schemaVersion"];
+    if (keys.length !== expected.length || keys.some((key, index) => key !== expected[index])) {
+        throw new Error("Embedded Browser profile state contains unknown fields");
+    }
+    if (value.schemaVersion !== 1 || value.kind !== STATE_KIND) {
+        throw new Error("Embedded Browser profile state identity is invalid");
+    }
+    const ownedSessionIds = sessionIds(value.ownedSessionIds, "ownedSessionIds");
+    const pendingDeletionSessionIds = sessionIds(value.pendingDeletionSessionIds, "pendingDeletionSessionIds");
+    const owned = new Set(ownedSessionIds);
+    if (pendingDeletionSessionIds.some((sessionId) => !owned.has(sessionId))) {
+        throw new Error("Embedded Browser deletion tombstone has no owned profile");
+    }
+    return {
+        schemaVersion: 1,
+        kind: STATE_KIND,
+        ownedSessionIds,
+        pendingDeletionSessionIds,
+    };
+}
+function sessionIds(value, label) {
+    if (!Array.isArray(value) || value.length > MAX_SESSION_IDS) {
+        throw new Error(`Embedded Browser ${label} is invalid`);
+    }
+    const result = value.map((sessionId) => {
+        requireSessionId(sessionId);
+        return sessionId;
+    });
+    if (new Set(result).size !== result.length) {
+        throw new Error(`Embedded Browser ${label} contains duplicates`);
+    }
+    return result;
+}
+function requireSessionId(value) {
+    if (typeof value !== "string" ||
+        value.length < 1 ||
+        value.length > MAX_SESSION_ID_CHARS ||
+        !SESSION_ID_PATTERN.test(value))
+        throw new Error("Embedded Browser Session identity is invalid");
+}
+function ensureProtectedDirectory(path) {
+    mkdirSync(path, { recursive: true, mode: 0o700 });
+    const stat = lstatSync(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new Error("Embedded Browser profile state root must be a direct directory");
+    }
+    chmodSync(path, 0o700);
+}
+function ensureDefaultStoreRoot() {
+    let current = resolve(rynxHome());
+    ensureProtectedDirectory(current);
+    for (const child of ["browser", "profiles", "embedded-electron"]) {
+        current = join(current, child);
+        if (!pathEntryExists(current))
+            mkdirSync(current, { mode: 0o700 });
+        ensureProtectedDirectory(current);
+    }
+    return current;
+}
+function rejectSymlinkOrNonFile(path) {
+    if (!pathEntryExists(path))
+        return;
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+        throw new Error("Embedded Browser profile state path must be a direct regular file");
+    }
+}
+function pathEntryExists(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+function openNoFollow(path, flags, mode) {
+    return openSync(path, flags | (fsConstants.O_NOFOLLOW ?? 0), mode);
+}
+function fsyncDirectory(path) {
+    const descriptor = openSync(path, fsConstants.O_RDONLY);
+    try {
+        fsyncSync(descriptor);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isDefinitiveCreateRejection(error) {
+    // `capacity` is deliberately not definitive: the Desktop Host also uses it
+    // when this Session already owns a Browser generation. In that recovery
+    // case, discarding the marker would make the existing profile uncollectable.
+    return error instanceof DesktopBrowserHostAbsentError;
+}

package/dist/headless-browser-host.d.ts

@@ -0,0 +1,14 @@
+import { type SessionBrowserHost } from "@rynx-ai/server";
+import { type ChromeForTestingArtifactStore } from "./chrome-for-testing-store.js";
+export interface HeadlessBrowserHostOptions {
+    /** Defaults to the immutable managed Chrome for Testing artifact store. */
+    artifactStore?: Pick<ChromeForTestingArtifactStore, "reserveActiveForLaunch">;
+    /** Defaults to ~/.rynx/browser/profiles/headless-chromium. */
+    profileRoot?: string;
+    startupTimeoutMs?: number;
+    cdpCommandTimeoutMs?: number;
+    terminationGraceMs?: number;
+    activePortPollMs?: number;
+}
+export declare function createHeadlessBrowserHost(options?: HeadlessBrowserHostOptions): SessionBrowserHost;
+export declare function headlessBrowserProfilePath(profileRoot: string, sessionId: string): string;