@rynx-ai/server 0.1.0 → 0.1.9

package/dist/direct-runtime-browser-surface-server.js

@@ -0,0 +1,821 @@
+import { decodeDirectRuntimeFrame, DIRECT_RUNTIME_BROWSER_SURFACE_BINDING_PROTOCOL, DIRECT_RUNTIME_BROWSER_SURFACE_PATH, DIRECT_RUNTIME_CLOSE_CODE, DIRECT_RUNTIME_MAX_HANDSHAKE_FRAME_BYTES, encodeDirectRuntimeFrame, parseServerAccepted, parseServerHello, } from "@rynx-ai/protocol/direct-runtime";
+import { encodeRuntimeBrowserSurfaceImageFrame, parseRuntimeBrowserSurfaceClientFrame, parseRuntimeBrowserSurfaceServerFrame, RUNTIME_BROWSER_SURFACE_HEARTBEAT_INTERVAL_MS, RUNTIME_BROWSER_SURFACE_MAX_CONTROL_FRAME_BYTES, RUNTIME_BROWSER_SURFACE_MAX_RELIABLE_INPUT_QUEUE, RUNTIME_BROWSER_SURFACE_PEER_LIVENESS_TIMEOUT_MS, } from "@rynx-ai/protocol/runtime-browser-surface";
+import { createServerE2EEChannel, createServerSurfaceE2EEChannel, DIRECT_RUNTIME_E2EE_MAX_ENVELOPE_BYTES, DIRECT_RUNTIME_SURFACE_E2EE_MAX_BINARY_ENVELOPE_BYTES, DIRECT_RUNTIME_SURFACE_E2EE_MAX_TEXT_ENVELOPE_BYTES, inspectDirectRuntimeSurfaceTextRecordContext, } from "@rynx-ai/remote-runtime-e2ee";
+import { WebSocket, WebSocketServer } from "ws";
+import { BrowserSurfaceControlQueue, BrowserSurfaceControlQueueCapacityError, } from "./browser-surface-control-queue.js";
+const CLOSE_BAD_PROTOCOL = DIRECT_RUNTIME_CLOSE_CODE.badProtocol;
+const CLOSE_UNAUTHORIZED = DIRECT_RUNTIME_CLOSE_CODE.unauthorized;
+const CLOSE_AUTH_TIMEOUT = DIRECT_RUNTIME_CLOSE_CODE.authenticationTimeout;
+const CLOSE_CAPACITY = DIRECT_RUNTIME_CLOSE_CODE.capacity;
+const CLOSE_INTERNAL = DIRECT_RUNTIME_CLOSE_CODE.internal;
+const DEFAULT_MAX_CONNECTIONS = 64;
+const DEFAULT_MAX_UNAUTHENTICATED_CONNECTIONS_PER_SOURCE = 4;
+const DEFAULT_MAX_AUTHENTICATION_ATTEMPTS_PER_SOURCE = 20;
+const DEFAULT_AUTHENTICATION_ATTEMPT_WINDOW_MS = 60_000;
+const DEFAULT_MAX_TRACKED_AUTHENTICATION_SOURCES = 1_024;
+const DEFAULT_MAX_CONNECTIONS_PER_GRANT = 8;
+const DEFAULT_MAX_BUFFERED_BYTES = 8 * 1024 * 1024;
+const DEFAULT_SHUTDOWN_DEADLINE_MS = 5_000;
+const CONNECTION_CLOSE_DEADLINE_MS = 1_000;
+export class DirectRuntimeBrowserSurfaceHostError extends Error {
+    reason;
+    constructor(reason, message, options) {
+        super(message, options);
+        this.reason = reason;
+        this.name = "DirectRuntimeBrowserSurfaceHostError";
+    }
+}
+/** Attach only the V3 Browser Surface route to an existing Direct HTTP server. */
+export function attachDirectRuntimeBrowserSurfaceServer(server, options) {
+    const limits = resolveLimits(options.limits);
+    const wss = new WebSocketServer({
+        noServer: true,
+        clientTracking: true,
+        perMessageDeflate: false,
+        maxPayload: Math.max(DIRECT_RUNTIME_SURFACE_E2EE_MAX_BINARY_ENVELOPE_BYTES, DIRECT_RUNTIME_E2EE_MAX_ENVELOPE_BYTES),
+    });
+    const connections = new Set();
+    const pendingUpgradesBySource = new Map();
+    const unauthenticatedConnectionsBySource = new Map();
+    const authenticationAttempts = new SourceAuthenticationAttemptLimiter({
+        maxAttempts: limits.maxAuthenticationAttemptsPerSource,
+        windowMs: limits.authenticationAttemptWindowMs,
+        maxSources: limits.maxTrackedAuthenticationSources,
+    });
+    let pendingUpgrades = 0;
+    let stopping = false;
+    let heartbeatTimer;
+    let shutdownPromise;
+    const handleUpgrade = (request, socket, head) => {
+        if (request.url !== DIRECT_RUNTIME_BROWSER_SURFACE_PATH)
+            return;
+        const sourceAddress = socketSourceAddress(request);
+        if (stopping) {
+            rejectUpgrade(socket, 503, "Browser Surface is stopping");
+            return;
+        }
+        if (connections.size + pendingUpgrades >= limits.maxConnections) {
+            rejectUpgrade(socket, 503, "Browser Surface connection capacity reached");
+            return;
+        }
+        if ((unauthenticatedConnectionsBySource.get(sourceAddress) ?? 0) +
+            (pendingUpgradesBySource.get(sourceAddress) ?? 0) >=
+            limits.maxUnauthenticatedConnectionsPerSource) {
+            rejectUpgrade(socket, 503, "Browser Surface authentication capacity reached");
+            return;
+        }
+        pendingUpgrades += 1;
+        incrementCount(pendingUpgradesBySource, sourceAddress);
+        let pending = true;
+        const releasePending = () => {
+            if (!pending)
+                return;
+            pending = false;
+            pendingUpgrades -= 1;
+            decrementCount(pendingUpgradesBySource, sourceAddress);
+        };
+        try {
+            wss.handleUpgrade(request, socket, head, (ws) => {
+                releasePending();
+                connections.add(acceptConnection(ws, sourceAddress));
+            });
+        }
+        catch (error) {
+            releasePending();
+            options.onError?.(error, "Browser Surface websocket upgrade");
+            rejectUpgrade(socket, 400, "invalid Browser Surface WebSocket upgrade");
+        }
+    };
+    server.on("upgrade", handleUpgrade);
+    function acceptConnection(ws, sourceAddress) {
+        const abortController = new AbortController();
+        let connection;
+        const authenticationTimer = setTimeout(() => {
+            abortController.abort(new Error("Browser Surface authentication timed out"));
+            connection.close(CLOSE_AUTH_TIMEOUT, "Browser Surface authentication timed out");
+        }, limits.authenticationTimeoutMs);
+        authenticationTimer.unref?.();
+        connection = {
+            ws,
+            sourceAddress,
+            countedAsUnauthenticated: true,
+            state: "awaiting_e2ee_hello",
+            attachmentClosed: false,
+            abortController,
+            authenticationTimer,
+            receiveTail: Promise.resolve(),
+            queuedFrames: 0,
+            authenticationFrameQueued: false,
+            lastInboundActivityAt: Date.now(),
+            close(code, reason) {
+                closeConnection(connection, code, reason);
+            },
+        };
+        incrementCount(unauthenticatedConnectionsBySource, sourceAddress);
+        ws.on("message", (data, isBinary) => {
+            connection.lastInboundActivityAt = Date.now();
+            if (isClosed(connection))
+                return;
+            if (connection.state !== "active" && connection.authenticationFrameQueued) {
+                connection.close(CLOSE_BAD_PROTOCOL, "Browser Surface traffic must remain ordered");
+                return;
+            }
+            if (connection.state !== "active")
+                connection.authenticationFrameQueued = true;
+            connection.queuedFrames += 1;
+            if (connection.queuedFrames > limits.maxQueuedFrames) {
+                connection.queuedFrames -= 1;
+                connection.close(CLOSE_CAPACITY, "Browser Surface input queue is full");
+                return;
+            }
+            connection.receiveTail = connection.receiveTail
+                .then(() => handleFrame(connection, data, isBinary))
+                .catch((error) => {
+                if (isClosed(connection))
+                    return;
+                options.onError?.(error, "Browser Surface frame");
+                connection.close(CLOSE_INTERNAL, "Browser Surface frame handling failed");
+            })
+                .finally(() => {
+                connection.queuedFrames -= 1;
+            });
+        });
+        ws.on("ping", () => {
+            connection.lastInboundActivityAt = Date.now();
+        });
+        ws.on("pong", () => {
+            connection.lastInboundActivityAt = Date.now();
+        });
+        ws.on("close", () => void cleanupConnection(connection, "client_closed"));
+        ws.on("error", (error) => {
+            options.onError?.(error, "Browser Surface socket");
+            void cleanupConnection(connection, "transport_error");
+        });
+        return connection;
+    }
+    async function handleFrame(connection, data, isBinary) {
+        if (isClosed(connection))
+            return;
+        if (isBinary) {
+            connection.close(CLOSE_BAD_PROTOCOL, "Browser Surface client records must be text");
+            return;
+        }
+        const wireBytes = rawDataBytes(data);
+        if (connection.state === "awaiting_e2ee_hello") {
+            await establishE2EE(connection, wireBytes);
+            return;
+        }
+        if (wireBytes.byteLength > DIRECT_RUNTIME_SURFACE_E2EE_MAX_TEXT_ENVELOPE_BYTES) {
+            connection.close(CLOSE_BAD_PROTOCOL, "Browser Surface text record is too large");
+            return;
+        }
+        if (connection.state === "awaiting_authentication") {
+            await authenticateConnection(connection, wireBytes);
+            return;
+        }
+        if (connection.state === "authenticating") {
+            connection.close(CLOSE_BAD_PROTOCOL, "Browser Surface authentication is already in progress");
+            return;
+        }
+        await handleSurfaceControl(connection, decodeText(wireBytes));
+    }
+    async function establishE2EE(connection, bytes) {
+        if (bytes.byteLength > DIRECT_RUNTIME_MAX_HANDSHAKE_FRAME_BYTES) {
+            connection.close(CLOSE_BAD_PROTOCOL, "Browser Surface E2EE hello is too large");
+            return;
+        }
+        try {
+            const frame = decodeDirectRuntimeFrame(bytes);
+            if (frame.type !== "e2ee.client-hello") {
+                throw new Error("first Browser Surface frame must be e2ee.client-hello");
+            }
+            const sharedSecret = options.e2ee.deriveSharedSecret(frame.clientEphemeralPublicKey);
+            const input = {
+                sharedSecret,
+                serverEncryptionPublicKey: options.e2ee.serverPublicKey,
+                clientHello: frame,
+            };
+            connection.surfaceChannelInput = input;
+            connection.authenticationChannel = createServerE2EEChannel(input);
+            await sendWireText(connection, encodeDirectRuntimeFrame({ type: "e2ee.ready" }));
+            await initializeServerHello(connection);
+        }
+        catch {
+            connection.close(CLOSE_BAD_PROTOCOL, "invalid Browser Surface E2EE client hello");
+        }
+    }
+    async function initializeServerHello(connection) {
+        try {
+            const channel = connection.authenticationChannel;
+            if (!channel)
+                throw new Error("Browser Surface authentication channel is unavailable");
+            const hello = parseServerHello(await options.authenticator.createServerHello({
+                channelBinding: channel.channelBinding,
+                role: "browser-surface",
+                signal: connection.abortController.signal,
+            }));
+            if (hello.role !== "browser-surface") {
+                throw new Error("Browser Surface authenticator returned the wrong role");
+            }
+            if (hello.bindingProtocolVersion !==
+                DIRECT_RUNTIME_BROWSER_SURFACE_BINDING_PROTOCOL.currentVersion ||
+                hello.minimumCompatibleBindingVersion !==
+                    DIRECT_RUNTIME_BROWSER_SURFACE_BINDING_PROTOCOL.minimumCompatibleVersion) {
+                throw new Error("Browser Surface authenticator returned an incompatible binding");
+            }
+            const encoded = encodeDirectRuntimeFrame(hello);
+            connection.serverHello = hello;
+            connection.serverHelloBytes = Uint8Array.from(Buffer.from(encoded, "utf8"));
+            connection.authenticationFrameQueued = false;
+            connection.state = "awaiting_authentication";
+            await sendAuthenticationText(connection, encoded);
+        }
+        catch (error) {
+            if (isClosed(connection))
+                return;
+            options.onError?.(error, "Browser Surface server hello");
+            connection.close(CLOSE_INTERNAL, "Browser Surface authentication setup failed");
+        }
+    }
+    async function authenticateConnection(connection, wireBytes) {
+        if (!authenticationAttempts.tryConsume(connection.sourceAddress)) {
+            connection.close(CLOSE_CAPACITY, "Browser Surface authentication limit reached");
+            return;
+        }
+        const channel = connection.authenticationChannel;
+        const serverHello = connection.serverHello;
+        const serverHelloBytes = connection.serverHelloBytes;
+        if (!channel || !serverHello || !serverHelloBytes) {
+            connection.close(CLOSE_INTERNAL, "Browser Surface server hello is unavailable");
+            return;
+        }
+        let plaintext;
+        let authenticate;
+        try {
+            plaintext = channel.open(decodeText(wireBytes));
+            const bytes = Uint8Array.from(Buffer.from(plaintext, "utf8"));
+            if (bytes.byteLength > DIRECT_RUNTIME_MAX_HANDSHAKE_FRAME_BYTES) {
+                throw new Error("Browser Surface authentication frame is too large");
+            }
+            const frame = decodeDirectRuntimeFrame(bytes);
+            if (frame.type !== "client.authenticate" || frame.role !== "browser-surface") {
+                throw new Error("Browser Surface client role is invalid");
+            }
+            authenticate = frame;
+        }
+        catch {
+            connection.close(CLOSE_BAD_PROTOCOL, "invalid Browser Surface authentication frame");
+            return;
+        }
+        connection.state = "authenticating";
+        try {
+            const authenticationBytes = Uint8Array.from(Buffer.from(plaintext, "utf8"));
+            const result = await options.authenticator.authenticate({
+                channelBinding: channel.channelBinding,
+                role: "browser-surface",
+                serverHello,
+                serverHelloBytes: new Uint8Array(serverHelloBytes),
+                clientAuthenticate: authenticate,
+                clientAuthenticateBytes: authenticationBytes,
+                signal: connection.abortController.signal,
+            });
+            if (connection.state !== "authenticating")
+                return;
+            const accepted = parseServerAccepted(result.accepted);
+            assertAuthenticationResult(serverHello, authenticate, result.peer, accepted);
+            connection.peer = result.peer;
+            const registration = options.connectionHub.registerWithinLimit(result.peer.grantId, connection, limits.maxConnectionsPerGrant);
+            if (registration === "revoked") {
+                connection.close(CLOSE_UNAUTHORIZED, "Remote Runtime grant is not active");
+                return;
+            }
+            if (registration === "capacity") {
+                connection.close(CLOSE_CAPACITY, "Remote Runtime grant connection capacity reached");
+                return;
+            }
+            const acceptedSend = sendAuthenticationText(connection, encodeDirectRuntimeFrame(accepted));
+            const surfaceInput = connection.surfaceChannelInput;
+            if (!surfaceInput)
+                throw new Error("Browser Surface key exchange is unavailable");
+            connection.accepted = accepted;
+            connection.surfaceChannel = createServerSurfaceE2EEChannel(surfaceInput);
+            connection.surfaceChannelInput = undefined;
+            connection.authenticationChannel = undefined;
+            connection.state = "awaiting_open";
+            connection.authenticationFrameQueued = false;
+            releaseUnauthenticated(connection);
+            clearTimeout(connection.authenticationTimer);
+            await acceptedSend;
+        }
+        catch (error) {
+            if (isClosed(connection))
+                return;
+            options.onError?.(error, "Browser Surface client authentication");
+            connection.close(CLOSE_UNAUTHORIZED, "Browser Surface authentication failed");
+        }
+    }
+    async function handleSurfaceControl(connection, encoded) {
+        const channel = connection.surfaceChannel;
+        const accepted = connection.accepted;
+        const peer = connection.peer;
+        if (!channel || !accepted || !peer) {
+            connection.close(CLOSE_BAD_PROTOCOL, "Browser Surface channel is unavailable");
+            return;
+        }
+        let context = connection.recordContext;
+        try {
+            if (!context) {
+                context = inspectDirectRuntimeSurfaceTextRecordContext(encoded, "client-to-server");
+                if (context.channelId !== accepted.channelId) {
+                    throw new Error("Browser Surface channel id does not match authentication");
+                }
+            }
+            const plaintext = channel.openText(encoded, context);
+            if (Buffer.byteLength(plaintext, "utf8") > RUNTIME_BROWSER_SURFACE_MAX_CONTROL_FRAME_BYTES) {
+                throw new Error("Browser Surface control frame is too large");
+            }
+            const frame = parseRuntimeBrowserSurfaceClientFrame(JSON.parse(plaintext));
+            if (frame.subscriptionId !== context.subscriptionId) {
+                throw new Error("Browser Surface subscription id does not match its record context");
+            }
+            if (!connection.recordContext) {
+                if (frame.type !== "browser.surface.open") {
+                    throw new Error("first Browser Surface control frame must be open");
+                }
+                connection.recordContext = context;
+                await openSurface(connection, frame);
+                return;
+            }
+            if (frame.type === "browser.surface.open") {
+                throw new Error("Browser Surface admits one subscription per connection");
+            }
+            if (connection.state !== "active" || !connection.attachment) {
+                throw new Error("Browser Surface is not active");
+            }
+            if (frame.type !== "browser.surface.frame.ack" &&
+                frame.browserGeneration !== connection.attachment.ready.browserGeneration) {
+                await sendSurfaceClosed(connection, "generation_changed", "Browser generation changed");
+                connection.close(1000, "Browser generation changed");
+                return;
+            }
+            if (connection.attachment.ready.grantedRole === "view" &&
+                (frame.type === "browser.surface.driver.take" || frame.type === "browser.surface.input")) {
+                await sendSurfaceClosed(connection, "unauthorized", "Browser Surface is view-only");
+                connection.close(CLOSE_UNAUTHORIZED, "Browser Surface is view-only");
+                return;
+            }
+            let active;
+            try {
+                active = await options.isPeerActive(peer);
+            }
+            catch (error) {
+                options.onError?.(error, "Browser Surface peer activity check");
+                await sendSurfaceClosed(connection, "internal_error", "Could not verify Runtime grant")
+                    .catch(() => undefined);
+                connection.close(CLOSE_INTERNAL, "Browser Surface grant check failed");
+                return;
+            }
+            if (!active) {
+                await sendSurfaceClosed(connection, "unauthorized", "Remote Runtime grant is not active");
+                connection.close(CLOSE_UNAUTHORIZED, "Remote Runtime grant is not active");
+                return;
+            }
+            const controlQueue = connection.controlQueue;
+            if (!controlQueue)
+                throw new Error("Browser Surface control queue is unavailable");
+            try {
+                controlQueue.enqueue(frame);
+            }
+            catch (error) {
+                await failSurfaceControl(connection, error);
+            }
+        }
+        catch (error) {
+            if (isClosed(connection))
+                return;
+            options.onError?.(error, "Browser Surface client control");
+            if (connection.recordContext) {
+                await sendSurfaceClosed(connection, "protocol_error", "invalid Browser Surface control frame")
+                    .catch(() => undefined);
+            }
+            connection.close(CLOSE_BAD_PROTOCOL, "invalid Browser Surface control frame");
+        }
+    }
+    async function openSurface(connection, frame) {
+        const peer = connection.peer;
+        if (!peer)
+            throw new Error("Browser Surface peer is unavailable");
+        connection.state = "opening";
+        try {
+            if (!(await options.isPeerActive(peer))) {
+                throw new DirectRuntimeBrowserSurfaceHostError("unauthorized", "Remote Runtime grant is not active");
+            }
+            const attachment = await options.host.open(frame, {
+                peer,
+                signal: connection.abortController.signal,
+            });
+            if (isClosed(connection)) {
+                await attachment.close("client_closed");
+                return;
+            }
+            const ready = parseRuntimeBrowserSurfaceServerFrame(attachment.ready);
+            if (ready.type !== "browser.surface.ready" ||
+                ready.subscriptionId !== frame.subscriptionId ||
+                ready.browserGeneration !== frame.browserGeneration ||
+                ready.format !== frame.format ||
+                (frame.requestedRole === "view" && ready.grantedRole !== "view")) {
+                await attachment.close("transport_error");
+                throw new Error("Browser Surface host returned an inconsistent ready frame");
+            }
+            connection.attachment = attachment;
+            connection.controlQueue = new BrowserSurfaceControlQueue({
+                maxPendingFrames: limits.maxQueuedFrames,
+                dispatch: (control) => attachment.handle(control),
+                onError: (error) => void failSurfaceControl(connection, error),
+            });
+            connection.state = "active";
+            await sendSurfaceText(connection, ready);
+            void pumpAttachmentEvents(connection, attachment);
+        }
+        catch (error) {
+            if (isClosed(connection))
+                return;
+            const reason = error instanceof DirectRuntimeBrowserSurfaceHostError
+                ? error.reason
+                : "internal_error";
+            const message = error instanceof Error ? error.message : "Browser Surface could not open";
+            await sendSurfaceClosed(connection, reason, message).catch(() => undefined);
+            connection.close(reason === "unauthorized" ? CLOSE_UNAUTHORIZED : CLOSE_INTERNAL, message);
+        }
+    }
+    async function pumpAttachmentEvents(connection, attachment) {
+        try {
+            for await (const event of attachment.events) {
+                if (isClosed(connection) || connection.attachment !== attachment)
+                    return;
+                if (isImageFrame(event)) {
+                    if (event.subscriptionId !== connection.recordContext?.subscriptionId) {
+                        throw new Error("Browser Surface host emitted an image for another subscription");
+                    }
+                    await sendSurfaceImage(connection, event);
+                    continue;
+                }
+                const frame = parseRuntimeBrowserSurfaceServerFrame(event);
+                if (frame.type === "browser.surface.ready" ||
+                    frame.subscriptionId !== connection.recordContext?.subscriptionId) {
+                    throw new Error("Browser Surface host emitted an inconsistent control frame");
+                }
+                await sendSurfaceText(connection, frame);
+                if (frame.type === "browser.surface.closed") {
+                    connection.close(1000, "Browser Surface closed");
+                    return;
+                }
+            }
+            if (!isClosed(connection)) {
+                await sendSurfaceClosed(connection, "internal_error", "Browser Surface event stream ended unexpectedly").catch(() => undefined);
+                connection.close(CLOSE_INTERNAL, "Browser Surface event stream ended");
+            }
+        }
+        catch (error) {
+            if (isClosed(connection))
+                return;
+            options.onError?.(error, "Browser Surface host events");
+            await sendSurfaceClosed(connection, "internal_error", "Browser Surface event stream failed")
+                .catch(() => undefined);
+            connection.close(CLOSE_INTERNAL, "Browser Surface event stream failed");
+        }
+    }
+    async function sendSurfaceClosed(connection, reason, message) {
+        const subscriptionId = connection.recordContext?.subscriptionId;
+        if (!subscriptionId)
+            return;
+        await sendSurfaceText(connection, {
+            type: "browser.surface.closed",
+            subscriptionId,
+            reason,
+            ...(message === undefined ? {} : { message: message.slice(0, 1_024) }),
+        });
+    }
+    async function failSurfaceControl(connection, error) {
+        if (isClosed(connection))
+            return;
+        const reason = error instanceof DirectRuntimeBrowserSurfaceHostError
+            ? error.reason
+            : error instanceof BrowserSurfaceControlQueueCapacityError
+                ? "capacity"
+                : "internal_error";
+        const message = error instanceof Error ? error.message : "Browser Surface input failed";
+        options.onError?.(error, "Browser Surface host input");
+        await sendSurfaceClosed(connection, reason, message).catch(() => undefined);
+        connection.close(reason === "unauthorized"
+            ? CLOSE_UNAUTHORIZED
+            : reason === "capacity"
+                ? CLOSE_CAPACITY
+                : CLOSE_INTERNAL, message);
+    }
+    async function sendAuthenticationText(connection, plaintext) {
+        const channel = connection.authenticationChannel;
+        if (!channel)
+            throw new Error("Browser Surface authentication channel is unavailable");
+        await sendWireText(connection, channel.seal(plaintext));
+    }
+    async function sendSurfaceText(connection, untrustedFrame) {
+        const channel = connection.surfaceChannel;
+        const context = connection.recordContext;
+        if (!channel || !context)
+            throw new Error("Browser Surface record channel is unavailable");
+        const frame = parseRuntimeBrowserSurfaceServerFrame(untrustedFrame);
+        const encrypted = channel.sealText(JSON.stringify(frame), context);
+        await sendWireText(connection, encrypted);
+    }
+    async function sendSurfaceImage(connection, frame) {
+        const channel = connection.surfaceChannel;
+        const context = connection.recordContext;
+        if (!channel || !context)
+            throw new Error("Browser Surface record channel is unavailable");
+        const encrypted = channel.sealBytes(encodeRuntimeBrowserSurfaceImageFrame(frame), context);
+        await sendWireBytes(connection, encrypted);
+    }
+    async function sendWireText(connection, frame) {
+        await sendWire(connection, frame, false, Buffer.byteLength(frame, "utf8"));
+    }
+    async function sendWireBytes(connection, frame) {
+        await sendWire(connection, frame, true, frame.byteLength);
+    }
+    async function sendWire(connection, frame, binary, byteLength) {
+        if (connection.ws.readyState !== WebSocket.OPEN) {
+            throw new Error("Browser Surface WebSocket is not open");
+        }
+        if (byteLength > limits.maxBufferedBytes ||
+            connection.ws.bufferedAmount + byteLength > limits.maxBufferedBytes) {
+            connection.close(CLOSE_CAPACITY, "Browser Surface output buffer is full");
+            throw new Error("Browser Surface output buffer is full");
+        }
+        await new Promise((resolve, reject) => {
+            connection.ws.send(frame, { binary, compress: false }, (error) => {
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            });
+        });
+    }
+    function closeConnection(connection, code, reason) {
+        if (isClosed(connection))
+            return;
+        const closeReason = code === CLOSE_UNAUTHORIZED ? "grant_revoked" : "transport_error";
+        connection.state = "closing";
+        connection.controlQueue?.abort();
+        connection.abortController.abort(new Error(reason));
+        if (connection.ws.readyState === WebSocket.OPEN) {
+            connection.ws.close(code, boundedCloseReason(reason));
+            connection.closeTimer = setTimeout(() => {
+                if (connection.ws.readyState !== WebSocket.CLOSED)
+                    connection.ws.terminate();
+            }, CONNECTION_CLOSE_DEADLINE_MS);
+            connection.closeTimer.unref?.();
+        }
+        else if (connection.ws.readyState !== WebSocket.CLOSED) {
+            connection.ws.terminate();
+        }
+        void closeAttachment(connection, closeReason);
+    }
+    async function cleanupConnection(connection, reason) {
+        if (connection.state === "closed")
+            return;
+        connection.state = "closed";
+        connection.controlQueue?.abort();
+        clearTimeout(connection.authenticationTimer);
+        if (connection.closeTimer)
+            clearTimeout(connection.closeTimer);
+        connection.abortController.abort(new Error("Browser Surface connection closed"));
+        releaseUnauthenticated(connection);
+        options.connectionHub.unregister(connection);
+        connections.delete(connection);
+        await closeAttachment(connection, reason);
+    }
+    async function closeAttachment(connection, reason) {
+        if (connection.attachmentClosed)
+            return;
+        connection.attachmentClosed = true;
+        try {
+            await connection.attachment?.close(reason);
+        }
+        catch (error) {
+            options.onError?.(error, "Browser Surface attachment cleanup");
+        }
+    }
+    function releaseUnauthenticated(connection) {
+        if (!connection.countedAsUnauthenticated)
+            return;
+        connection.countedAsUnauthenticated = false;
+        decrementCount(unauthenticatedConnectionsBySource, connection.sourceAddress);
+    }
+    heartbeatTimer = setInterval(() => {
+        const now = Date.now();
+        for (const connection of connections) {
+            if (connection.ws.readyState !== WebSocket.OPEN)
+                continue;
+            if (now - connection.lastInboundActivityAt > limits.peerLivenessTimeoutMs) {
+                connection.ws.terminate();
+                continue;
+            }
+            try {
+                connection.ws.ping();
+            }
+            catch {
+                connection.ws.terminate();
+            }
+        }
+    }, limits.heartbeatIntervalMs);
+    heartbeatTimer.unref?.();
+    return {
+        path: DIRECT_RUNTIME_BROWSER_SURFACE_PATH,
+        get activeConnectionCount() {
+            return connections.size;
+        },
+        shutdown() {
+            if (shutdownPromise)
+                return shutdownPromise;
+            shutdownPromise = (async () => {
+                stopping = true;
+                server.removeListener("upgrade", handleUpgrade);
+                if (heartbeatTimer)
+                    clearInterval(heartbeatTimer);
+                heartbeatTimer = undefined;
+                for (const connection of [...connections]) {
+                    connection.state = "closing";
+                    connection.abortController.abort(new Error("Browser Surface server is shutting down"));
+                    void closeAttachment(connection, "server_shutdown");
+                    if (connection.ws.readyState === WebSocket.OPEN) {
+                        connection.ws.close(1001, "Browser Surface server is shutting down");
+                    }
+                    else if (connection.ws.readyState !== WebSocket.CLOSED) {
+                        connection.ws.terminate();
+                    }
+                }
+                const deadline = Date.now() + limits.shutdownDeadlineMs;
+                while (connections.size > 0 && Date.now() < deadline) {
+                    await new Promise((resolve) => setTimeout(resolve, 10));
+                }
+                for (const connection of [...connections])
+                    connection.ws.terminate();
+                await closeWebSocketServer(wss);
+            })();
+            return shutdownPromise;
+        },
+    };
+}
+function assertAuthenticationResult(hello, authenticate, peer, accepted) {
+    if (hello.role !== "browser-surface" ||
+        authenticate.role !== "browser-surface" ||
+        accepted.role !== "browser-surface" ||
+        authenticate.mode !== "connect" ||
+        accepted.daemonId !== hello.daemonId ||
+        accepted.daemonInstanceId !== hello.daemonInstanceId ||
+        authenticate.daemonId !== hello.daemonId ||
+        authenticate.daemonInstanceId !== hello.daemonInstanceId ||
+        authenticate.bindingProtocolVersion !==
+            DIRECT_RUNTIME_BROWSER_SURFACE_BINDING_PROTOCOL.currentVersion ||
+        accepted.bindingProtocolVersion !== authenticate.bindingProtocolVersion ||
+        accepted.coreProtocolVersion !== authenticate.coreProtocolVersion ||
+        accepted.clientId !== authenticate.clientId ||
+        accepted.clientId !== peer.clientId ||
+        accepted.grantId !== authenticate.grantId ||
+        accepted.grantId !== peer.grantId ||
+        accepted.authorities.length !== peer.subject.effectiveAuthorities.length ||
+        accepted.authorities.some((authority, index) => authority !== peer.subject.effectiveAuthorities[index])) {
+        throw new Error("Browser Surface authenticator returned an inconsistent identity");
+    }
+}
+function isImageFrame(event) {
+    return !("type" in event);
+}
+function isClosed(connection) {
+    return connection.state === "closing" || connection.state === "closed";
+}
+function rawDataBytes(data) {
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data);
+    if (Array.isArray(data))
+        return Uint8Array.from(Buffer.concat(data));
+    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+}
+function decodeText(bytes) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch (error) {
+        throw new Error("Browser Surface frame must be valid UTF-8", { cause: error });
+    }
+}
+function socketSourceAddress(request) {
+    const address = request.socket.remoteAddress;
+    if (!address)
+        return "unknown";
+    return address.startsWith("::ffff:") ? address.slice("::ffff:".length) : address;
+}
+function rejectUpgrade(socket, status, message) {
+    if (socket.destroyed)
+        return;
+    const body = `${message}\n`;
+    socket.end(`HTTP/1.1 ${status} ${statusText(status)}\r\n` +
+        "Connection: close\r\n" +
+        "Cache-Control: no-store\r\n" +
+        "Content-Type: text/plain; charset=utf-8\r\n" +
+        `Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`);
+}
+function statusText(status) {
+    if (status === 400)
+        return "Bad Request";
+    if (status === 404)
+        return "Not Found";
+    if (status === 503)
+        return "Service Unavailable";
+    return "Error";
+}
+function boundedCloseReason(reason) {
+    const bytes = Buffer.from(reason, "utf8");
+    if (bytes.byteLength <= 123)
+        return reason;
+    return bytes.subarray(0, 123).toString("utf8").replace(/\uFFFD+$/u, "");
+}
+function incrementCount(counts, key) {
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+}
+function decrementCount(counts, key) {
+    const current = counts.get(key);
+    if (current === undefined || current <= 1)
+        counts.delete(key);
+    else
+        counts.set(key, current - 1);
+}
+function resolveLimits(limits) {
+    const resolved = {
+        authenticationTimeoutMs: positiveInteger(limits?.authenticationTimeoutMs, 10_000),
+        maxConnections: positiveInteger(limits?.maxConnections, DEFAULT_MAX_CONNECTIONS),
+        maxUnauthenticatedConnectionsPerSource: positiveInteger(limits?.maxUnauthenticatedConnectionsPerSource, DEFAULT_MAX_UNAUTHENTICATED_CONNECTIONS_PER_SOURCE),
+        maxAuthenticationAttemptsPerSource: positiveInteger(limits?.maxAuthenticationAttemptsPerSource, DEFAULT_MAX_AUTHENTICATION_ATTEMPTS_PER_SOURCE),
+        authenticationAttemptWindowMs: positiveInteger(limits?.authenticationAttemptWindowMs, DEFAULT_AUTHENTICATION_ATTEMPT_WINDOW_MS),
+        maxTrackedAuthenticationSources: positiveInteger(limits?.maxTrackedAuthenticationSources, DEFAULT_MAX_TRACKED_AUTHENTICATION_SOURCES),
+        maxConnectionsPerGrant: positiveInteger(limits?.maxConnectionsPerGrant, DEFAULT_MAX_CONNECTIONS_PER_GRANT),
+        maxQueuedFrames: positiveInteger(limits?.maxQueuedFrames, RUNTIME_BROWSER_SURFACE_MAX_RELIABLE_INPUT_QUEUE),
+        maxBufferedBytes: positiveInteger(limits?.maxBufferedBytes, DEFAULT_MAX_BUFFERED_BYTES),
+        heartbeatIntervalMs: positiveInteger(limits?.heartbeatIntervalMs, RUNTIME_BROWSER_SURFACE_HEARTBEAT_INTERVAL_MS),
+        peerLivenessTimeoutMs: positiveInteger(limits?.peerLivenessTimeoutMs, RUNTIME_BROWSER_SURFACE_PEER_LIVENESS_TIMEOUT_MS),
+        shutdownDeadlineMs: positiveInteger(limits?.shutdownDeadlineMs, DEFAULT_SHUTDOWN_DEADLINE_MS),
+    };
+    if (resolved.maxConnectionsPerGrant > resolved.maxConnections) {
+        throw new Error("Browser Surface per-grant limit must not exceed maxConnections");
+    }
+    if (resolved.peerLivenessTimeoutMs <= resolved.heartbeatIntervalMs) {
+        throw new Error("Browser Surface liveness timeout must exceed its heartbeat interval");
+    }
+    if (resolved.maxBufferedBytes < DIRECT_RUNTIME_SURFACE_E2EE_MAX_BINARY_ENVELOPE_BYTES) {
+        throw new Error("Browser Surface output limit must admit one maximum binary record");
+    }
+    return resolved;
+}
+function positiveInteger(value, fallback) {
+    const resolved = value ?? fallback;
+    if (!Number.isSafeInteger(resolved) || resolved <= 0) {
+        throw new Error("Browser Surface limits must be positive safe integers");
+    }
+    return resolved;
+}
+class SourceAuthenticationAttemptLimiter {
+    options;
+    entries = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    tryConsume(sourceAddress, now = Date.now()) {
+        const existing = this.entries.get(sourceAddress);
+        if (existing && now - existing.startedAt < this.options.windowMs) {
+            existing.attempts += 1;
+            this.entries.delete(sourceAddress);
+            this.entries.set(sourceAddress, existing);
+            return existing.attempts <= this.options.maxAttempts;
+        }
+        if (existing)
+            this.entries.delete(sourceAddress);
+        while (this.entries.size >= this.options.maxSources) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.entries.delete(oldest);
+        }
+        this.entries.set(sourceAddress, { startedAt: now, attempts: 1 });
+        return true;
+    }
+}
+function closeWebSocketServer(server) {
+    return new Promise((resolve) => {
+        try {
+            server.close(() => resolve());
+        }
+        catch {
+            resolve();
+        }
+    });
+}