@rynx-ai/server 0.1.11-beta.5 → 0.2.0-beta.2

package/dist/session-portal.js

@@ -0,0 +1,746 @@
+import { request as httpRequest, } from "node:http";
+import { pipeline } from "node:stream/promises";
+import Router from "@koa/router";
+import Koa from "koa";
+import { WebSocket, WebSocketServer } from "ws";
+import { sendSpaFile } from "./control-web-dist.js";
+export const SESSION_PORTAL_HEADER = "x-rynx-session-portal";
+export const SESSION_PORTAL_QUERY = "portal";
+const MAX_TICKET_BYTES = 256;
+const MAX_FILTERED_RESPONSE_BYTES = 16 * 1024 * 1024;
+const MAX_PENDING_SOCKET_FRAMES = 128;
+const MAX_PENDING_SOCKET_BYTES = 1024 * 1024;
+const MAX_SOCKET_BUFFERED_BYTES = 32 * 1024 * 1024;
+const PORTAL_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const RUNTIME_SESSION_PATH = /^\/runtimes\/local\/sessions(?:\/([^/]+))?\/?$/;
+const RUNTIME_SESSION_API_PATH = /^\/api\/runtimes\/local\/sessions(?:\/([^/]+))?(?:\/|$)/;
+const SESSION_COLLECTION_API_PATH = "/api/runtimes/local/sessions";
+const TERMINAL_SOCKET_PATH = /^\/api\/runtimes\/([^/]+)\/sessions\/([^/]+)\/terminal$/;
+const BROWSER_SOCKET_PATH = /^\/api\/runtimes\/([^/]+)\/sessions\/([^/]+)\/browser\/pages\/[^/]+\/surface$/;
+const EMULATOR_SOCKET_PATH = /^\/api\/runtimes\/([^/]+)\/sessions\/([^/]+)\/emulator\/surface$/;
+const HOP_BY_HOP_HEADERS = new Set([
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "proxy-connection",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+]);
+/** Session Portal is a narrow adapter in front of the one Control service. It
+ * serves the native SPA, validates Portal grants, and forwards only authorized
+ * Session HTTP calls to Control; it owns no Session or Runtime handlers. */
+export function createSessionPortalApp(options) {
+    const app = new Koa();
+    const bootstrapRouter = new Router();
+    app.use(async (ctx, next) => {
+        ctx.set("Cache-Control", "no-store");
+        ctx.set("Referrer-Policy", "no-referrer");
+        ctx.set("X-Content-Type-Options", "nosniff");
+        ctx.set("X-Frame-Options", "DENY");
+        ctx.set("Content-Security-Policy", "default-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline'; " +
+            "connect-src 'self' ws: wss:; img-src 'self' data: blob:; font-src 'self' data:; " +
+            "base-uri 'none'; form-action 'self'; frame-ancestors 'none'");
+        if (options.shutdownSignal?.aborted) {
+            serviceUnavailable(ctx);
+            return;
+        }
+        await next();
+    });
+    bootstrapRouter.get("/health", (ctx) => {
+        ctx.body = { ok: true, surface: "session-portal" };
+    });
+    bootstrapRouter.get("/session-portal/redeem", (ctx) => {
+        ctx.type = "html";
+        ctx.body = redeemPage();
+    });
+    bootstrapRouter.post("/session-portal/redeem", async (ctx) => {
+        const body = await readJsonBody(ctx.req).catch(() => undefined);
+        const ticket = typeof body?.ticket === "string" ? body.ticket : "";
+        if (!ticket || Buffer.byteLength(ticket, "utf8") > MAX_TICKET_BYTES) {
+            ctx.status = 400;
+            ctx.body = { error: "invalid_ticket" };
+            return;
+        }
+        const grant = options.authorization.redeem(ticket);
+        if (!grant) {
+            ctx.status = 401;
+            ctx.body = { error: "ticket_expired_or_used" };
+            return;
+        }
+        ctx.cookies.set(cookieName(grant.portalId), grant.secret, {
+            httpOnly: true,
+            sameSite: "strict",
+            secure: options.scheme === "https",
+            overwrite: true,
+            path: "/",
+            expires: new Date(grant.expiresAt),
+        });
+        const path = grant.scope === "single_session"
+            ? `/runtimes/local/sessions/${encodeURIComponent(grant.sessionId)}`
+            : "/runtimes/local/sessions";
+        ctx.body = {
+            location: `${path}?${SESSION_PORTAL_QUERY}=${encodeURIComponent(grant.portalId)}`,
+            expiresAt: grant.expiresAt,
+        };
+    });
+    app.use(bootstrapRouter.routes());
+    app.use(bootstrapRouter.allowedMethods());
+    app.use(async (ctx, next) => {
+        if (isStaticAssetRequest(ctx))
+            return next();
+        const grant = authorizeHttp(ctx, options.authorization);
+        if (!grant)
+            return;
+        ctx.state.sessionPortal = grant;
+        expireHttpResponseAtGrantDeadline(ctx, grant.expiresAt);
+        if (ctx.path === "/api/session-portal/access") {
+            if (ctx.method !== "GET")
+                return methodNotAllowed(ctx);
+            ctx.body = publicAuthorization(grant);
+            return;
+        }
+        if (!authorizePortalRoute(ctx, grant, options.authorization))
+            return;
+        if (ctx.path.startsWith("/api/")) {
+            await proxyControlHttp(ctx, grant, options);
+            return;
+        }
+        await next();
+    });
+    app.use(async (ctx, next) => {
+        if (ctx.method !== "GET" && ctx.method !== "HEAD")
+            return next();
+        if (ctx.path.startsWith("/api/") || ctx.path.startsWith("/session-portal/"))
+            return next();
+        const grant = ctx.state.sessionPortal;
+        await sendSpaFile(ctx, options.controlWebDist, "/", grant
+            ? (html) => injectPortalBootstrap(html, grant)
+            : undefined);
+    });
+    return app;
+}
+export async function startSessionPortal(options) {
+    if (options.shutdownSignal?.aborted)
+        throw new Error("Control service is shutting down");
+    const lifecycle = new AbortController();
+    let shutdownPortal;
+    const stopForControlShutdown = () => {
+        lifecycle.abort(options.shutdownSignal?.reason ?? new Error("Control service is shutting down"));
+        void shutdownPortal?.().catch(() => undefined);
+    };
+    options.shutdownSignal?.addEventListener("abort", stopForControlShutdown, { once: true });
+    const app = createSessionPortalApp({ ...options, shutdownSignal: lifecycle.signal });
+    let server;
+    try {
+        server = await new Promise((resolve, reject) => {
+            const candidate = app.listen(options.port, options.host, () => {
+                candidate.off("error", reject);
+                resolve(candidate);
+            });
+            candidate.once("error", reject);
+        });
+    }
+    catch (error) {
+        options.shutdownSignal?.removeEventListener("abort", stopForControlShutdown);
+        throw error;
+    }
+    let sockets;
+    try {
+        sockets = attachPortalWebSocketProxy(server, {
+            authorization: options.authorization,
+            controlOrigin: options.controlOrigin,
+            shutdownSignal: lifecycle.signal,
+        });
+    }
+    catch (error) {
+        options.shutdownSignal?.removeEventListener("abort", stopForControlShutdown);
+        await closeHttpServerImmediately(server);
+        throw error;
+    }
+    let shutdownPromise;
+    const shutdown = () => {
+        if (shutdownPromise)
+            return shutdownPromise;
+        lifecycle.abort(new Error("Control service is shutting down"));
+        for (const client of sockets.external.clients)
+            client.terminate();
+        for (const upstream of sockets.upstream)
+            upstream.terminate();
+        shutdownPromise = Promise.all([
+            closeWebSocketServer(sockets.external),
+            closeHttpServerImmediately(server),
+        ]).then(() => {
+            options.shutdownSignal?.removeEventListener("abort", stopForControlShutdown);
+        });
+        return shutdownPromise;
+    };
+    shutdownPortal = shutdown;
+    if (lifecycle.signal.aborted) {
+        await shutdown();
+        throw new Error("Control service is shutting down");
+    }
+    return {
+        server,
+        stopAccepting: () => { void shutdown().catch(() => undefined); },
+        shutdown,
+    };
+}
+export function authorizeSessionPortalWebSocket(request, ports, runtimeSelector, sessionId) {
+    let url;
+    try {
+        url = new URL(request.url ?? "", "http://localhost");
+    }
+    catch {
+        return undefined;
+    }
+    const portalId = url.searchParams.get(SESSION_PORTAL_QUERY) ?? "";
+    if (!PORTAL_ID_PATTERN.test(portalId))
+        return undefined;
+    const secret = cookieValue(request.headers.cookie, cookieName(portalId));
+    if (!secret)
+        return undefined;
+    const grant = ports.authorize(portalId, secret);
+    if (!grant)
+        return undefined;
+    if (runtimeSelector !== "local")
+        return undefined;
+    if (grant.scope === "single_session" && grant.sessionId !== sessionId)
+        return undefined;
+    if (!ports.ownsSession(grant.pluginId, sessionId))
+        return undefined;
+    return grant;
+}
+export function rejectSessionPortalUpgrade(socket) {
+    rejectUpgrade(socket, 401, "session portal grant expired or invalid");
+}
+function authorizeHttp(ctx, ports) {
+    const queryPortal = typeof ctx.query[SESSION_PORTAL_QUERY] === "string"
+        ? ctx.query[SESSION_PORTAL_QUERY]
+        : "";
+    const candidate = ctx.path.startsWith("/api/")
+        ? ctx.get(SESSION_PORTAL_HEADER) || queryPortal
+        : queryPortal;
+    const portalId = candidate.trim();
+    const secret = PORTAL_ID_PATTERN.test(portalId)
+        ? ctx.cookies.get(cookieName(portalId))
+        : undefined;
+    const grant = secret ? ports.authorize(portalId, secret) : undefined;
+    if (!grant) {
+        ctx.status = 401;
+        ctx.body = { error: "session_portal_grant_expired_or_invalid" };
+    }
+    return grant;
+}
+function authorizePortalRoute(ctx, grant, ports) {
+    if (ctx.path === "/") {
+        const target = grant.scope === "single_session"
+            ? `/runtimes/local/sessions/${encodeURIComponent(grant.sessionId)}`
+            : "/runtimes/local/sessions";
+        ctx.redirect(`${target}?${SESSION_PORTAL_QUERY}=${encodeURIComponent(grant.portalId)}`);
+        return false;
+    }
+    const pageMatch = RUNTIME_SESSION_PATH.exec(ctx.path);
+    if (pageMatch) {
+        if (ctx.method !== "GET" && ctx.method !== "HEAD")
+            return methodNotAllowed(ctx);
+        const requested = decoded(pageMatch[1]);
+        if (grant.scope === "single_session" && requested && requested !== grant.sessionId)
+            return notFound(ctx);
+        if (requested && !ports.ownsSession(grant.pluginId, requested))
+            return notFound(ctx);
+        return true;
+    }
+    if (ctx.path === "/api/runtimes/capability" || ctx.path === "/api/runtimes") {
+        if (ctx.method !== "GET")
+            return methodNotAllowed(ctx);
+        return true;
+    }
+    if (ctx.path === SESSION_COLLECTION_API_PATH) {
+        return ctx.method === "GET" ? true : methodNotAllowed(ctx);
+    }
+    const apiMatch = RUNTIME_SESSION_API_PATH.exec(ctx.path);
+    const sessionId = decoded(apiMatch?.[1]);
+    if (sessionId) {
+        if (grant.scope === "single_session" && sessionId !== grant.sessionId)
+            return notFound(ctx);
+        if (!ports.ownsSession(grant.pluginId, sessionId))
+            return notFound(ctx);
+        if (ctx.method === "GET" || ctx.method === "HEAD")
+            return true;
+        if (!isAllowedSessionMutation(ctx, apiMatch[1]))
+            return notFound(ctx);
+        return denyMutation(ctx, grant);
+    }
+    return notFound(ctx);
+}
+async function proxyControlHttp(ctx, grant, options) {
+    let response;
+    try {
+        response = await openControlRequest(ctx, options.controlOrigin, options.shutdownSignal);
+    }
+    catch (error) {
+        if (options.shutdownSignal?.aborted)
+            return serviceUnavailable(ctx);
+        ctx.status = 502;
+        ctx.body = { error: "control_service_unavailable" };
+        return;
+    }
+    if (shouldFilterControlResponse(ctx)) {
+        try {
+            const data = await readBoundedResponse(response, MAX_FILTERED_RESPONSE_BYTES, options.shutdownSignal);
+            applyControlResponseHeaders(ctx, response.headers, true);
+            ctx.status = response.statusCode ?? 502;
+            const body = JSON.parse(data.toString("utf8"));
+            narrowPortalResponse(ctx.path, body, grant, options.authorization);
+            ctx.body = body;
+        }
+        catch {
+            if (options.shutdownSignal?.aborted)
+                return serviceUnavailable(ctx);
+            ctx.status = 502;
+            ctx.body = { error: "invalid_control_response" };
+        }
+        return;
+    }
+    ctx.status = response.statusCode ?? 502;
+    applyControlResponseHeaders(ctx, response.headers, false);
+    ctx.respond = false;
+    ctx.res.statusCode = ctx.status;
+    try {
+        await pipeline(response, ctx.res, ...(options.shutdownSignal
+            ? [{ signal: options.shutdownSignal }]
+            : []));
+    }
+    catch {
+        if (!ctx.res.destroyed)
+            ctx.res.destroy();
+    }
+}
+function openControlRequest(ctx, controlOrigin, signal) {
+    const target = new URL(`${ctx.path}${ctx.search}`, controlOrigin);
+    target.searchParams.delete(SESSION_PORTAL_QUERY);
+    return new Promise((resolve, reject) => {
+        const request = httpRequest(target, {
+            method: ctx.method,
+            headers: controlRequestHeaders(ctx.req.headers, target),
+            ...(signal ? { signal } : {}),
+        }, resolve);
+        request.once("error", reject);
+        ctx.req.once("aborted", () => request.destroy(new Error("Portal request aborted")));
+        ctx.req.pipe(request);
+    });
+}
+function controlRequestHeaders(headers, target) {
+    const forwarded = {};
+    for (const [name, value] of Object.entries(headers)) {
+        const lower = name.toLowerCase();
+        if (value === undefined ||
+            HOP_BY_HOP_HEADERS.has(lower) ||
+            lower === "cookie" ||
+            lower === "host" ||
+            lower === "origin" ||
+            lower === "referer" ||
+            lower === "accept-encoding" ||
+            lower === SESSION_PORTAL_HEADER ||
+            lower.startsWith("forwarded") ||
+            lower.startsWith("x-forwarded-"))
+            continue;
+        forwarded[lower] = value;
+    }
+    forwarded.host = target.host;
+    forwarded.origin = target.origin;
+    forwarded["sec-fetch-site"] = "same-origin";
+    forwarded["accept-encoding"] = "identity";
+    return forwarded;
+}
+function applyControlResponseHeaders(ctx, headers, bodyChanged) {
+    for (const [name, value] of Object.entries(headers)) {
+        const lower = name.toLowerCase();
+        if (value === undefined ||
+            HOP_BY_HOP_HEADERS.has(lower) ||
+            lower === "set-cookie" ||
+            (bodyChanged && (lower === "content-length" || lower === "content-encoding")))
+            continue;
+        ctx.set(name, Array.isArray(value) ? value : String(value));
+    }
+}
+function shouldFilterControlResponse(ctx) {
+    return ctx.method === "GET" && (ctx.path === "/api/runtimes" || ctx.path === SESSION_COLLECTION_API_PATH);
+}
+function narrowPortalResponse(path, body, grant, ports) {
+    if (!body || typeof body !== "object")
+        return;
+    if (path === "/api/runtimes") {
+        const value = body;
+        if (Array.isArray(value.runtimes)) {
+            value.runtimes = value.runtimes.filter((runtime) => runtime.selector === "local");
+        }
+    }
+    if (path === SESSION_COLLECTION_API_PATH) {
+        const value = body;
+        if (Array.isArray(value.sessions)) {
+            value.sessions = value.sessions.filter((session) => typeof session.id === "string" &&
+                ports.ownsSession(grant.pluginId, session.id) &&
+                (grant.scope !== "single_session" || session.id === grant.sessionId));
+        }
+    }
+}
+function attachPortalWebSocketProxy(server, options) {
+    const external = new WebSocketServer({ noServer: true, perMessageDeflate: false });
+    const upstreamSockets = new Set();
+    server.on("upgrade", (request, socket, head) => {
+        if (options.shutdownSignal.aborted)
+            return rejectUpgrade(socket, 503, "Control service is shutting down");
+        const route = portalSocketRoute(request.url);
+        if (!route)
+            return rejectUpgrade(socket, 404, "Session Portal socket not found");
+        const grant = authorizeSessionPortalWebSocket(request, options.authorization, route.runtimeSelector, route.sessionId);
+        if (!grant || !readOnlySocketRoleAllowed(route.kind, request.url, grant)) {
+            rejectSessionPortalUpgrade(socket);
+            return;
+        }
+        try {
+            external.handleUpgrade(request, socket, head, (client) => {
+                bridgePortalWebSocket(client, route.kind, request.url, grant, {
+                    controlOrigin: options.controlOrigin,
+                    shutdownSignal: options.shutdownSignal,
+                    upstreamSockets,
+                });
+            });
+        }
+        catch {
+            rejectUpgrade(socket, 400, "invalid Session Portal WebSocket upgrade");
+        }
+    });
+    return { external, upstream: upstreamSockets };
+}
+function bridgePortalWebSocket(client, kind, requestUrl, grant, options) {
+    const externalTarget = new URL(requestUrl, "http://session-portal.invalid");
+    const target = new URL(`${externalTarget.pathname}${externalTarget.search}`, options.controlOrigin);
+    target.protocol = target.protocol === "https:" ? "wss:" : "ws:";
+    target.searchParams.delete(SESSION_PORTAL_QUERY);
+    const upstream = new WebSocket(target, {
+        origin: options.controlOrigin,
+        headers: { "sec-fetch-site": "same-origin" },
+        perMessageDeflate: false,
+        maxPayload: MAX_SOCKET_BUFFERED_BYTES,
+    });
+    options.upstreamSockets.add(upstream);
+    const pending = [];
+    let pendingBytes = 0;
+    let closed = false;
+    const clearExpiry = scheduleSessionPortalExpiry(grant.expiresAt, () => {
+        closeSocket(client, 4403, "Session Portal grant expired");
+        closeSocket(upstream, 4403, "Session Portal grant expired");
+    });
+    const stopForShutdown = () => {
+        client.terminate();
+        upstream.terminate();
+    };
+    options.shutdownSignal.addEventListener("abort", stopForShutdown, { once: true });
+    const cleanup = () => {
+        if (closed)
+            return;
+        closed = true;
+        clearExpiry();
+        pending.length = 0;
+        pendingBytes = 0;
+        options.upstreamSockets.delete(upstream);
+        options.shutdownSignal.removeEventListener("abort", stopForShutdown);
+    };
+    client.on("message", (data, isBinary) => {
+        if (grant.access === "read_only") {
+            if (kind === "terminal")
+                return;
+            if (!allowedReadOnlySocketFrame(kind, data, isBinary)) {
+                closeSocket(client, 4403, "Session Portal is read only");
+                closeSocket(upstream, 4403, "Session Portal is read only");
+                return;
+            }
+        }
+        const frame = rawDataBuffer(data);
+        if (upstream.readyState === WebSocket.OPEN) {
+            forwardSocketFrame(client, upstream, frame, isBinary);
+            return;
+        }
+        if (pending.length >= MAX_PENDING_SOCKET_FRAMES ||
+            pendingBytes + frame.byteLength > MAX_PENDING_SOCKET_BYTES) {
+            closeSocket(client, 4408, "Session Portal socket queue is full");
+            upstream.terminate();
+            return;
+        }
+        pending.push({ data: frame, isBinary });
+        pendingBytes += frame.byteLength;
+    });
+    upstream.on("open", () => {
+        for (const frame of pending.splice(0)) {
+            pendingBytes -= frame.data.byteLength;
+            if (!forwardSocketFrame(client, upstream, frame.data, frame.isBinary))
+                break;
+        }
+    });
+    upstream.on("message", (data, isBinary) => {
+        forwardSocketFrame(upstream, client, data, isBinary);
+    });
+    client.on("close", (code, reason) => {
+        closeSocket(upstream, normalizedCloseCode(code), reason.toString());
+        cleanup();
+    });
+    upstream.on("close", (code, reason) => {
+        closeSocket(client, normalizedCloseCode(code), reason.toString());
+        cleanup();
+    });
+    client.on("error", () => {
+        upstream.terminate();
+        cleanup();
+    });
+    upstream.on("error", () => {
+        closeSocket(client, 1011, "Control service unavailable");
+    });
+}
+function portalSocketRoute(rawUrl) {
+    let pathname;
+    try {
+        pathname = new URL(rawUrl ?? "", "http://localhost").pathname;
+    }
+    catch {
+        return undefined;
+    }
+    for (const [kind, pattern] of [
+        ["terminal", TERMINAL_SOCKET_PATH],
+        ["browser", BROWSER_SOCKET_PATH],
+        ["emulator", EMULATOR_SOCKET_PATH],
+    ]) {
+        const match = pattern.exec(pathname);
+        if (!match)
+            continue;
+        const runtimeSelector = decoded(match[1]);
+        const sessionId = decoded(match[2]);
+        if (runtimeSelector && sessionId)
+            return { kind, runtimeSelector, sessionId };
+    }
+    return undefined;
+}
+function readOnlySocketRoleAllowed(kind, rawUrl, grant) {
+    if (grant.access !== "read_only" || kind === "emulator")
+        return true;
+    const role = new URL(rawUrl ?? "", "http://localhost").searchParams.get("role");
+    return kind === "terminal" ? role === "read-only" : role === "view";
+}
+function allowedReadOnlySocketFrame(kind, data, isBinary) {
+    if (kind !== "browser" || isBinary)
+        return false;
+    try {
+        const value = JSON.parse(rawDataBuffer(data).toString("utf8"));
+        return value.type === "browser.surface.frame.ack";
+    }
+    catch {
+        return false;
+    }
+}
+function forwardSocketFrame(source, target, data, isBinary) {
+    const bytes = rawDataBytes(data);
+    if (target.readyState !== WebSocket.OPEN ||
+        target.bufferedAmount + bytes > MAX_SOCKET_BUFFERED_BYTES) {
+        closeSocket(source, 4408, "Session Portal socket is too slow");
+        closeSocket(target, 4408, "Session Portal socket is too slow");
+        return false;
+    }
+    target.send(data, { binary: isBinary }, (error) => {
+        if (error) {
+            source.terminate();
+            target.terminate();
+        }
+    });
+    return true;
+}
+function rawDataBuffer(data) {
+    if (Buffer.isBuffer(data))
+        return Buffer.from(data);
+    if (data instanceof ArrayBuffer)
+        return Buffer.from(data);
+    if (Array.isArray(data))
+        return Buffer.concat(data);
+    throw new TypeError("Unsupported WebSocket frame payload");
+}
+function rawDataBytes(data) {
+    if (Buffer.isBuffer(data))
+        return data.byteLength;
+    if (data instanceof ArrayBuffer)
+        return data.byteLength;
+    if (Array.isArray(data))
+        return data.reduce((total, part) => total + part.byteLength, 0);
+    throw new TypeError("Unsupported WebSocket frame payload");
+}
+function closeSocket(socket, code, reason) {
+    if (socket.readyState === WebSocket.CONNECTING) {
+        socket.terminate();
+        return;
+    }
+    if (socket.readyState === WebSocket.OPEN)
+        socket.close(code, reason.slice(0, 120));
+}
+function normalizedCloseCode(code) {
+    return code >= 1000 && code <= 4999 && code !== 1005 && code !== 1006 ? code : 1011;
+}
+function rejectUpgrade(socket, status, message) {
+    if (socket.destroyed)
+        return;
+    const body = `${message}\n`;
+    const statusText = status === 401
+        ? "Unauthorized"
+        : status === 404
+            ? "Not Found"
+            : status === 503
+                ? "Service Unavailable"
+                : "Bad Request";
+    socket.end(`HTTP/1.1 ${status} ${statusText}\r\nConnection: close\r\n` +
+        "Content-Type: text/plain; charset=utf-8\r\n" +
+        `Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`);
+}
+function isAllowedSessionMutation(ctx, encodedSessionId) {
+    const prefix = `${SESSION_COLLECTION_API_PATH}/${encodedSessionId}`;
+    const suffix = ctx.path.slice(prefix.length);
+    if (ctx.method === "POST") {
+        return /^(?:\/interrupt|\/messages(?:\/queue)?|\/terminal\/start|\/resources|\/interactions\/[^/]+\/resolve|\/browser\/(?:open|close|pages)|\/browser\/pages\/[^/]+\/(?:close|activate|back|forward|reload|navigate)|\/emulator\/(?:attach|detach|tap|button|type|rotate|launch|gesture))$/.test(suffix);
+    }
+    return ctx.method === "DELETE" && /^\/resources\/[^/]+$/.test(suffix);
+}
+function denyMutation(ctx, grant) {
+    if (grant.access === "read_write")
+        return true;
+    ctx.status = 403;
+    ctx.body = { error: "session_portal_read_only" };
+    return false;
+}
+function expireHttpResponseAtGrantDeadline(ctx, expiresAt) {
+    const clear = scheduleSessionPortalExpiry(expiresAt, () => {
+        if (!ctx.res.writableEnded)
+            ctx.res.destroy(new Error("Session Portal grant expired"));
+    });
+    ctx.res.once("finish", clear);
+    ctx.res.once("close", clear);
+}
+export function scheduleSessionPortalExpiry(expiresAt, onExpire) {
+    const delay = Math.max(0, Date.parse(expiresAt) - Date.now());
+    const timer = setTimeout(onExpire, delay);
+    timer.unref?.();
+    return () => clearTimeout(timer);
+}
+function publicAuthorization(grant) {
+    return {
+        portalId: grant.portalId,
+        scope: grant.scope,
+        access: grant.access,
+        ...(grant.sessionId ? { sessionId: grant.sessionId } : {}),
+        expiresAt: grant.expiresAt,
+    };
+}
+function injectPortalBootstrap(html, grant) {
+    const value = JSON.stringify(publicAuthorization(grant)).replace(/</g, "\\u003c");
+    return html.replace("</head>", `<script>window.rynxSessionPortal=${value}</script></head>`);
+}
+function isStaticAssetRequest(ctx) {
+    return (ctx.method === "GET" || ctx.method === "HEAD") &&
+        (ctx.path.startsWith("/assets/") || ctx.path === "/favicon.png" || ctx.path === "/favicon.svg");
+}
+function cookieName(portalId) {
+    return `rynx_session_portal_${portalId}`;
+}
+function cookieValue(raw, name) {
+    for (const part of raw?.split(";") ?? []) {
+        const index = part.indexOf("=");
+        if (index < 0 || part.slice(0, index).trim() !== name)
+            continue;
+        try {
+            return decodeURIComponent(part.slice(index + 1).trim());
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+function decoded(value) {
+    if (!value)
+        return undefined;
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+function notFound(ctx) {
+    ctx.status = 404;
+    ctx.body = { error: "session_not_found" };
+    return false;
+}
+function methodNotAllowed(ctx) {
+    ctx.status = 405;
+    ctx.body = { error: "method_not_allowed" };
+    return false;
+}
+function serviceUnavailable(ctx) {
+    ctx.status = 503;
+    ctx.body = { error: "control_service_shutting_down" };
+}
+async function readJsonBody(request) {
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        bytes += buffer.length;
+        if (bytes > 4_096)
+            throw new Error("request body too large");
+        chunks.push(buffer);
+    }
+    const parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("request body must be an object");
+    }
+    return parsed;
+}
+async function readBoundedResponse(response, maxBytes, signal) {
+    const chunks = [];
+    let bytes = 0;
+    const abort = () => response.destroy(signal?.reason instanceof Error ? signal.reason : undefined);
+    if (signal?.aborted)
+        abort();
+    else
+        signal?.addEventListener("abort", abort, { once: true });
+    try {
+        for await (const chunk of response) {
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            bytes += buffer.byteLength;
+            if (bytes > maxBytes)
+                throw new Error("Control response is too large");
+            chunks.push(buffer);
+        }
+        return Buffer.concat(chunks);
+    }
+    finally {
+        signal?.removeEventListener("abort", abort);
+    }
+}
+function closeWebSocketServer(server) {
+    return new Promise((resolve, reject) => {
+        server.close((error) => error ? reject(error) : resolve());
+    });
+}
+function closeHttpServerImmediately(server) {
+    return new Promise((resolve, reject) => {
+        if (!server.listening) {
+            resolve();
+            return;
+        }
+        server.close((error) => error ? reject(error) : resolve());
+        server.closeAllConnections?.();
+    });
+}
+function redeemPage() {
+    return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Rynx Sessions</title><style>body{font:14px Inter,system-ui;margin:0;display:grid;min-height:100vh;place-items:center;background:#f6f6f8;color:#17171b}.box{text-align:center}.spin{width:22px;height:22px;margin:0 auto 14px;border:2px solid #d8d8df;border-top-color:#6d5ce7;border-radius:50%;animation:s .8s linear infinite}@keyframes s{to{transform:rotate(360deg)}}</style></head><body><main class="box"><div class="spin"></div><p id="status">正在打开 Rynx Sessions…</p></main><script>(()=>{const el=document.getElementById('status');const p=new URLSearchParams(location.hash.slice(1));const ticket=p.get('ticket');history.replaceState(null,'',location.pathname);if(!ticket){el.textContent='访问链接缺少票据。';return}fetch(location.pathname,{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({ticket})}).then(async r=>{const b=await r.json();if(!r.ok)throw new Error(b.error||'票据兑换失败');location.replace(b.location)}).catch(e=>{el.textContent='无法打开：'+e.message})})();</script></body></html>`;
+}