@deepseek-ai/dsh-client-connection 0.1.1-rc.2 → 0.1.2-alpha.2

package/lib/index.js

@@ -1,21 +1,15 @@
 import z from "@deepseek-ai/schemastery";
-import { toFetchHandler } from "@deepseek-ai/dsh-host-apiproxy";
+import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { credentialKey } from "@deepseek-ai/dsh-credentials";
 import { Service } from "@deepseek-ai/cordis";
-import { RpcId, clientRequestSchema } from "@deepseek-ai/dsh-host-apiproxy/api";
-import { randomUUID } from "node:crypto";
-import WebSocket, { WebSocketServer } from "ws";
+import { z as z$1 } from "zod";
 //#region lib/types/api-path.js
 /**
 * The /api URL prefix — single source for both halves of the web transport.
-* The node half registers this prefix on the web server; both halves share the
-* event paths below for the browser WebSocket downlinks.
+* The node half registers this prefix on the web server.
 */
 /** Route prefix owning every api request (`/api` and `/api/<anything>`). */
 const API_PATH = "/api";
-/** Browser mux-frame WebSocket pathname. */
-const MUX_EVENTS_PATH = `${API_PATH}/events.mux`;
-/** Browser host-frame WebSocket pathname. */
-const HOST_EVENTS_PATH = `${API_PATH}/events.host`;
 //#endregion
 //#region lib/types/http-bridge.js
 /**
@@ -29,7 +23,7 @@ const HOST_EVENTS_PATH = `${API_PATH}/events.host`;
 const DEFAULT_MAX_REQUEST_BODY_BYTES = 300 * 1024 * 1024;
 /**
 * Bridge one node:http request to the fetch-shaped handler (client close
-* aborts; SSE bodies stream out chunk by chunk).
+* aborts; response bodies stream out chunk by chunk).
 * @param req - incoming node:http request (fully read before dispatch).
 * @param res - node:http response the bridge writes and owns to completion.
 * @param apiHandler - fetch-shaped API carrier the request is dispatched to.
@@ -118,7 +112,7 @@ function isLoopbackHostname(hostname) {
 * Network reachability and authentication stay out of scope: binding policy
 * belongs to the webserver config, and this fence is not an auth layer.
 */
-function header(headers, name) {
+function header$1(headers, name) {
 	if (headers instanceof Headers) return headers.get(name) ?? void 0;
 	const value = headers[name];
 	return typeof value === "string" ? value : void 0;
@@ -182,13 +176,13 @@ function isTrustedAuthority(hostUrl, trustedHosts) {
 * @returns true when the Host is ours (loopback or trusted) and any attached browser markers are same-origin.
 */
 function isTrustedApiRequest(request, trustedHosts) {
-	const host = header(request.headers, "host");
+	const host = header$1(request.headers, "host");
 	if (host === void 0) return false;
 	const hostUrl = parseAuthority(host);
 	if (hostUrl === void 0) return false;
 	if (!isLoopbackHostname(hostUrl.hostname) && !isTrustedAuthority(hostUrl, trustedHosts)) return false;
-	if (header(request.headers, "sec-fetch-site") === "cross-site") return false;
-	const origin = header(request.headers, "origin");
+	if (header$1(request.headers, "sec-fetch-site") === "cross-site") return false;
+	const origin = header$1(request.headers, "origin");
 	if (origin === void 0) return true;
 	try {
 		return new URL(origin).host === hostUrl.host;
@@ -197,6 +191,306 @@ function isTrustedApiRequest(request, trustedHosts) {
 	}
 }
 //#endregion
+//#region lib/types/browser-auth.js
+/** Browser-session authentication for the Host Connection carrier. */
+const AUTH_RECORD_KEY = credentialKey("client-connection", "browser-session");
+const DAY_MILLISECONDS = 1440 * 60 * 1e3;
+const SECRET_BYTES = 32;
+const TOKEN_QUERY = "token";
+const COOKIE_PREFIX = "dsh-auth-";
+const COOKIE_PAYLOAD_VERSION = 1;
+const STORED_SECRET_VERSION = 1;
+const BASE64URL_PATTERN = /^[A-Za-z0-9_-]*$/;
+const PROCESS_LAUNCH_TOKENS = /* @__PURE__ */ new WeakMap();
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function encodeBase64Url(value) {
+	return Buffer.from(value).toString("base64").replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/u, "");
+}
+function decodeBase64Url(value) {
+	if (!BASE64URL_PATTERN.test(value) || value.length % 4 === 1) return void 0;
+	const padding = "=".repeat((4 - value.length % 4) % 4);
+	const decoded = Buffer.from(value.replaceAll("-", "+").replaceAll("_", "/") + padding, "base64");
+	return encodeBase64Url(decoded) === value ? decoded : void 0;
+}
+function processLaunchToken(owner) {
+	const existing = PROCESS_LAUNCH_TOKENS.get(owner);
+	if (existing !== void 0) return existing;
+	const created = encodeBase64Url(randomBytes(SECRET_BYTES));
+	PROCESS_LAUNCH_TOKENS.set(owner, created);
+	return created;
+}
+function header(headers, name) {
+	if (headers instanceof Headers) return headers.get(name) ?? void 0;
+	const value = headers[name];
+	return typeof value === "string" ? value : void 0;
+}
+/** Canonical request authority used as the cookie name and signed audience. */
+function requestAuthority(headers) {
+	const host = header(headers, "host");
+	if (host === void 0) return void 0;
+	try {
+		return new URL(`http://${host}`).host;
+	} catch {
+		return;
+	}
+}
+function canonicalSecret(value) {
+	if (typeof value !== "string") return void 0;
+	const decoded = decodeBase64Url(value);
+	if (decoded === void 0 || decoded.byteLength !== SECRET_BYTES) return void 0;
+	return decoded;
+}
+function storedSecret(record) {
+	if (record === void 0) return void 0;
+	if (record.kind !== "grant" || !isRecord(record.payload) || record.payload.version !== STORED_SECRET_VERSION) throw new Error("client-connection: browser-session credential record has an unsupported format");
+	const secret = canonicalSecret(record.payload.secret);
+	if (secret === void 0) throw new Error("client-connection: browser-session credential record has an invalid secret");
+	return secret;
+}
+function tokenMatches(actual, expected) {
+	const actualBytes = Buffer.from(actual, "utf8");
+	const expectedBytes = Buffer.from(expected, "utf8");
+	return actualBytes.byteLength === expectedBytes.byteLength && timingSafeEqual(actualBytes, expectedBytes);
+}
+function cookieName(authority) {
+	return COOKIE_PREFIX + encodeBase64Url(createHash("sha256").update(authority).digest());
+}
+/** Read the exact generated cookie without implementing general Cookie decoding. */
+function cookieValue(headerValue, name) {
+	for (const segment of headerValue.split(";")) {
+		const at = segment.indexOf("=");
+		if (at === -1 || segment.slice(0, at).trim() !== name) continue;
+		return segment.slice(at + 1).trim();
+	}
+}
+/** Serialize the fixed browser-session attributes; generated names and values are cookie-safe base64url. */
+function sessionCookie(name, value, expiresAt, maxAgeSeconds) {
+	return `${name}=${value}; Max-Age=${String(maxAgeSeconds)}; Path=/; Expires=${new Date(expiresAt).toUTCString()}; HttpOnly; SameSite=Strict`;
+}
+function signature(secret, body) {
+	return createHmac("sha256", secret).update(body).digest();
+}
+function encodeCookie(payload, secret) {
+	const body = encodeBase64Url(Buffer.from(JSON.stringify(payload), "utf8"));
+	return `v1.${body}.${encodeBase64Url(signature(secret, body))}`;
+}
+function decodeCookie(value, secret) {
+	const parts = value.split(".");
+	const [version, body, encodedSignature] = parts;
+	if (parts.length !== 3 || version !== "v1" || body === void 0 || encodedSignature === void 0) return;
+	const actualSignature = decodeBase64Url(encodedSignature);
+	if (actualSignature === void 0) return void 0;
+	const expectedSignature = signature(secret, body);
+	if (actualSignature.byteLength !== expectedSignature.byteLength || !timingSafeEqual(actualSignature, expectedSignature)) return void 0;
+	let decoded;
+	try {
+		const bodyBytes = decodeBase64Url(body);
+		if (bodyBytes === void 0) return void 0;
+		decoded = JSON.parse(bodyBytes.toString("utf8"));
+	} catch {
+		return;
+	}
+	if (!isRecord(decoded) || decoded.version !== COOKIE_PAYLOAD_VERSION || typeof decoded.authority !== "string" || !Number.isSafeInteger(decoded.issuedAt) || !Number.isSafeInteger(decoded.expiresAt)) return void 0;
+	return decoded;
+}
+async function initializeSecret(credentials) {
+	const generated = {
+		version: STORED_SECRET_VERSION,
+		secret: encodeBase64Url(randomBytes(SECRET_BYTES))
+	};
+	const secret = storedSecret(await credentials.modifyRecord(AUTH_RECORD_KEY, (current) => {
+		if (current !== void 0) {
+			storedSecret(current);
+			return Promise.resolve(void 0);
+		}
+		return Promise.resolve({
+			kind: "grant",
+			payload: generated
+		});
+	}));
+	if (secret === void 0) throw new Error("client-connection: browser-session credential record was not created");
+	return secret;
+}
+/**
+* Process launch-token exchange and persistent signed-cookie verification.
+* Connection loads the credential provider's signing secret during activation
+* and retains it for synchronous request authentication.
+*/
+var BrowserAuth = class BrowserAuth {
+	secret;
+	launchToken;
+	maxAgeMilliseconds;
+	constructor(processOwner, secret, maxAgeDays) {
+		this.secret = secret;
+		this.launchToken = processLaunchToken(processOwner);
+		this.maxAgeMilliseconds = maxAgeDays * DAY_MILLISECONDS;
+		if (!Number.isSafeInteger(this.maxAgeMilliseconds) || !Number.isSafeInteger(Date.now() + this.maxAgeMilliseconds)) throw new Error("client-connection: cookieMaxAgeDays exceeds the safe timestamp range");
+	}
+	/**
+	* Initialize browser authentication and create its durable signing secret
+	* when this Harness home has none.
+	* @param processOwner - root application context retaining one token across Connection reloads.
+	* @param credentials - persistent credential provider for the Web profile.
+	* @param maxAgeDays - positive absolute browser-cookie lifetime in days.
+	* @returns initialized authentication owner with the process owner's launch token.
+	*/
+	static async create(processOwner, credentials, maxAgeDays) {
+		return new BrowserAuth(processOwner, await initializeSecret(credentials), maxAgeDays);
+	}
+	/**
+	* Add this process's launch token to the ordinary application root URL.
+	* @param baseUrl - canonical browser origin without credentials.
+	* @returns root URL carrying the process token as its sole authentication input.
+	*/
+	authenticatedUrl(baseUrl) {
+		const url = new URL(baseUrl);
+		url.pathname = "/";
+		url.search = "";
+		url.hash = "";
+		url.searchParams.set(TOKEN_QUERY, this.launchToken);
+		return url.href;
+	}
+	/**
+	* Authenticate an index request. A valid root query token mints the cookie
+	* and redirects to clean `/`; a valid cookie lets the caller serve the
+	* index; every other request receives the same minimal 401 response.
+	* @param req - incoming root or configured-index request.
+	* @param res - response owned when this method returns false.
+	* @returns true only when the caller may serve index.html.
+	*/
+	authorizeIndex(req, res) {
+		/* v8 ignore next -- node:http always supplies url on server requests. */
+		const url = new URL(req.url ?? "/", "http://dsh.invalid");
+		const tokens = url.searchParams.getAll(TOKEN_QUERY);
+		if (tokens.length > 0) {
+			const authority = requestAuthority(req.headers);
+			if (req.method === "GET" && url.pathname === "/" && tokens.length === 1 && authority !== void 0 && tokenMatches(tokens.join(""), this.launchToken)) {
+				const issuedAt = Date.now();
+				const expiresAt = issuedAt + this.maxAgeMilliseconds;
+				const value = encodeCookie({
+					version: COOKIE_PAYLOAD_VERSION,
+					authority,
+					issuedAt,
+					expiresAt
+				}, this.secret);
+				res.writeHead(303, {
+					"cache-control": "no-store",
+					"location": "/",
+					"referrer-policy": "no-referrer",
+					"set-cookie": sessionCookie(cookieName(authority), value, expiresAt, Math.floor(this.maxAgeMilliseconds / 1e3))
+				});
+				res.end();
+				return false;
+			}
+			if (req.method === "GET" && url.pathname === "/" && this.isAuthenticated(req)) {
+				res.writeHead(303, {
+					"cache-control": "no-store",
+					"location": "/",
+					"referrer-policy": "no-referrer"
+				});
+				res.end();
+				return false;
+			}
+			this.writeUnauthorized(req, res);
+			return false;
+		}
+		if (this.isAuthenticated(req)) return true;
+		this.writeUnauthorized(req, res);
+		return false;
+	}
+	/**
+	* Verify the authority-bound browser cookie on a Host request.
+	* @param request - request headers carrying Host and Cookie.
+	* @returns true only for an unexpired cookie signed by this activation's loaded secret.
+	*/
+	isAuthenticated(request) {
+		const authority = requestAuthority(request.headers);
+		const rawCookie = header(request.headers, "cookie");
+		if (authority === void 0 || rawCookie === void 0) return false;
+		const value = cookieValue(rawCookie, cookieName(authority));
+		if (value === void 0) return false;
+		const payload = decodeCookie(value, this.secret);
+		if (payload === void 0 || payload.authority !== authority) return false;
+		const now = Date.now();
+		return payload.issuedAt <= now && payload.expiresAt > now && payload.expiresAt > payload.issuedAt && payload.expiresAt - payload.issuedAt <= this.maxAgeMilliseconds;
+	}
+	writeUnauthorized(req, res) {
+		res.writeHead(401, {
+			"cache-control": "no-store",
+			"content-type": "text/plain; charset=utf-8"
+		});
+		res.end(req.method === "HEAD" ? void 0 : "dsh web authentication required; reopen the URL printed by dsh web.\n");
+	}
+};
+//#endregion
+//#region lib/types/rpc.js
+/** Generic unary RPC contracts shared by the Host and Client Connection halves. */
+/**
+* Brand one validated string as a Connection correlation id.
+* @param id - validated wire identity.
+* @returns the same string with the correlation-id brand.
+*/
+function RpcId(id) {
+	return id;
+}
+/**
+* Convert a rejected transport operation into a generic failure result.
+* @param error - rejected transport value.
+* @returns an `internal` failure preserving the available message.
+*/
+function transportError(error) {
+	return {
+		ok: false,
+		error: {
+			code: "gateway/internal",
+			message: error instanceof Error ? error.message : String(error),
+			details: {}
+		}
+	};
+}
+//#endregion
+//#region lib/types/rpc-schema.js
+/** Runtime validation for Connection RPC envelopes. */
+/** Correlation id after wire validation. */
+const rpcIdSchema = z$1.string();
+/** Generic endpoint failure carried in a response envelope. */
+const rpcErrorSchema = z$1.object({
+	code: z$1.string(),
+	message: z$1.string(),
+	details: z$1.record(z$1.string(), z$1.unknown())
+});
+/**
+* Build the result parser for one endpoint value parser.
+* @param value - endpoint-owned success-value parser.
+* @returns parser for either a success value or generic failure.
+*/
+function rpcResultSchema(value) {
+	return z$1.union([z$1.object({
+		ok: z$1.literal(true),
+		value
+	}), z$1.object({
+		ok: z$1.literal(false),
+		error: rpcErrorSchema
+	})]);
+}
+/** Client request envelope; endpoint payload validation belongs to its owner. */
+const clientRequestSchema = z$1.object({
+	type: z$1.literal("client-request"),
+	rpcId: rpcIdSchema,
+	method: z$1.string(),
+	payload: z$1.unknown()
+});
+/** Server response envelope; endpoint value validation belongs to its caller. */
+const serverResponseSchema = z$1.object({
+	type: z$1.literal("server-response"),
+	rpcId: rpcIdSchema,
+	result: rpcResultSchema(z$1.unknown().optional())
+});
+/** Either Connection RPC envelope direction. */
+const rpcMessageSchema = z$1.discriminatedUnion("type", [clientRequestSchema, serverResponseSchema]);
+//#endregion
 //#region lib/types/rpc-host.js
 /** Host registry and HTTP adapter for generic Connection RPC channels. */
 const INVALID_REQUEST_RPC_ID = RpcId("invalid-request");
@@ -205,50 +499,87 @@ const ENDPOINT_SEGMENT_PATTERN = /^[A-Za-z0-9_$.-]+$/;
 /** Host Connection service whose channel registrations belong to the caller fiber. */
 var HostConnectionService = class extends Service {
 	trustedHosts;
+	browserAuth;
 	interceptors = /* @__PURE__ */ new Map();
+	fetchRoutes = /* @__PURE__ */ new Map();
 	/**
 	* Provide the Host half over the active HTTP server.
 	* @param ctx - owning Connection plugin context.
-	* @param trustedHosts - deployment authorities accepted by trusted-host channels.
+	* @param trustedHosts - deployment authorities accepted by the Host/Origin fence.
+	* @param browserAuth - process token and persistent browser-session owner.
 	*/
-	constructor(ctx, trustedHosts) {
+	constructor(ctx, trustedHosts, browserAuth) {
 		super(ctx, "connection");
 		this.trustedHosts = trustedHosts;
+		this.browserAuth = browserAuth;
 	}
 	/** Generic channel registry scoped to the Context reading this service. */
 	get rpc() {
 		const owner = this.ctx;
 		return {
-			handle: (channel, handler, options) => this.register(owner, channel, handler, options),
-			intercept: (channel, matches, handler, options) => this.registerInterceptor(owner, channel, matches, handler, options)
+			handle: (channel, handler) => this.register(owner, channel, handler),
+			intercept: (channel, matches, handler) => this.registerInterceptor(owner, channel, matches, handler)
 		};
 	}
+	/** Exact Fetch-route registry scoped to the Context reading this service. */
+	get fetch() {
+		const owner = this.ctx;
+		return { register: (route) => this.registerFetchRoute(owner, route) };
+	}
+	/** Apply the configured Host/Origin fence, then browser authentication. */
+	requestRejection(request) {
+		if (!isTrustedApiRequest(request, this.trustedHosts)) return 403;
+		return this.browserAuth.isAuthenticated(request) ? void 0 : 401;
+	}
+	/** Authenticate an index request through the process-token exchange or cookie. */
+	authorizeIndex(request, response) {
+		return this.browserAuth.authorizeIndex(request, response);
+	}
+	/** Add this process's launch token to the clean application URL. */
+	authenticatedUrl(baseUrl) {
+		return this.browserAuth.authenticatedUrl(baseUrl);
+	}
 	/**
-	* Compose one shared-channel Fetch handler from its interceptor and fallback.
+	* Compose one shared-channel Fetch handler from exact routes and its interceptor.
 	* @param channel - shared channel mounted by Connection.
-	* @param fallback - handler for endpoints not claimed by the interceptor.
-	* @returns Fetch handler that selects exactly one target for each request.
+	* @returns Fetch handler that selects one owner or returns 404.
 	*/
-	createSharedFetchHandler(channel, fallback) {
+	createSharedFetchHandler(channel) {
 		return { fetch: (request) => {
-			const endpoint = endpointFromPath(channel, new URL(request.url).pathname);
+			const pathname = new URL(request.url).pathname;
+			const route = this.fetchRoutes.get(pathname);
+			if (route?.methods.has(request.method) === true) return route.fetch(request);
+			const endpoint = endpointFromPath(channel, pathname);
 			const interceptor = this.interceptors.get(channel);
-			if (endpoint === void 0 || interceptor === void 0 || !interceptor.matches(endpoint)) return fallback.fetch(request);
-			if (interceptor.options.authority === "loopback" && !isTrustedApiRequest(request, [])) return Promise.resolve(new Response("forbidden", { status: 403 }));
+			if (endpoint === void 0 || interceptor === void 0 || !interceptor.matches(endpoint)) return Promise.resolve(new Response("not found", { status: 404 }));
 			return interceptor.fetchHandler.fetch(request);
 		} };
 	}
-	register(owner, channel, handler, options) {
+	registerFetchRoute(owner, route) {
+		assertFetchRoute(route);
+		const registered = {
+			methods: new Set(route.methods),
+			fetch: route.fetch
+		};
+		return owner.effect(() => {
+			if (this.fetchRoutes.has(route.path)) throw new Error(`connection: exact Fetch route ${JSON.stringify(route.path)} is already registered`);
+			this.fetchRoutes.set(route.path, registered);
+			return () => {
+				this.fetchRoutes.delete(route.path);
+			};
+		}, `client-connection: ${route.path} Fetch route`);
+	}
+	register(owner, channel, handler) {
 		assertChannel(channel);
-		const trustedHosts = options.authority === "loopback" ? [] : this.trustedHosts;
 		const fetchHandler = rpcFetchHandler(channel, handler);
 		const route = {
 			kind: "prefix",
 			path: channel,
 			handler: async (req, res) => {
-				if (!isTrustedApiRequest(req, trustedHosts)) {
-					res.writeHead(403);
-					res.end("forbidden");
+				const rejection = this.requestRejection(req);
+				if (rejection !== void 0) {
+					res.writeHead(rejection);
+					res.end(rejection === 401 ? "unauthorized" : "forbidden");
 					return;
 				}
 				await bridge(req, res, fetchHandler);
@@ -256,12 +587,11 @@ var HostConnectionService = class extends Service {
 		};
 		return owner.effect(() => owner.webServer.register(route), `client-connection: ${channel} rpc channel`);
 	}
-	registerInterceptor(owner, channel, matches, handler, options) {
+	registerInterceptor(owner, channel, matches, handler) {
 		if (channel !== "/api") throw new Error(`connection: invalid shared RPC channel ${JSON.stringify(channel)}`);
 		const interceptor = {
 			matches,
-			fetchHandler: rpcFetchHandler(channel, handler),
-			options
+			fetchHandler: rpcFetchHandler(channel, handler)
 		};
 		return owner.effect(() => {
 			if (this.interceptors.has(channel)) throw new Error(`connection: shared RPC channel ${JSON.stringify(channel)} already has an interceptor`);
@@ -287,7 +617,7 @@ function rpcFetchHandler(channel, handler) {
 		if (!envelope.success) return invalidEnvelopeResponse(body, envelope.error.issues);
 		const message = envelope.data;
 		if (message.method !== endpoint) return errorResponse(message.rpcId, {
-			code: "bad-request",
+			code: "gateway/bad-request",
 			message: `method ${JSON.stringify(message.method)} does not match endpoint ${JSON.stringify(endpoint)}`,
 			details: { issues: [] }
 		});
@@ -302,7 +632,7 @@ function rpcFetchHandler(channel, handler) {
 function invalidEnvelopeResponse(body, issues) {
 	const rawId = body?.rpcId;
 	return errorResponse(typeof rawId === "string" ? RpcId(rawId) : INVALID_REQUEST_RPC_ID, {
-		code: "bad-request",
+		code: "gateway/bad-request",
 		message: "invalid client-request message",
 		details: { issues }
 	});
@@ -330,138 +660,10 @@ function fullResponse(rpcId, result) {
 function assertChannel(channel) {
 	if (!CHANNEL_PATTERN.test(channel) || channel === "/api") throw new Error(`connection: invalid or reserved RPC channel ${JSON.stringify(channel)}`);
 }
-//#endregion
-//#region lib/types/websocket-downlink.js
-/** Host-side WebSocket carrier for the two server-to-browser event streams. */
-function serverRequest(frame) {
-	return {
-		type: "server-request",
-		rpcId: frame.rpcId,
-		method: frame.payload.type,
-		payload: frame.payload
-	};
-}
-function send(socket, frame) {
-	return new Promise((resolve, reject) => {
-		if (socket.readyState !== WebSocket.OPEN) {
-			reject(/* @__PURE__ */ new Error("websocket downlink closed before frame delivery"));
-			return;
-		}
-		socket.send(JSON.stringify(serverRequest(frame)), (error) => {
-			if (error) reject(error);
-			else resolve();
-		});
-	});
-}
-function failureFrame(error) {
-	return {
-		rpcId: RpcId(randomUUID()),
-		payload: {
-			type: "stream/error",
-			error: {
-				code: "internal",
-				message: String(error),
-				details: {}
-			}
-		}
-	};
-}
-/**
-* Owns WebSocket negotiation and frame pumping for the connection plugin's
-* two downlinks. Client messages are a protocol violation: upstream traffic
-* remains on HTTP.
-*/
-var WebSocketDownlinks = class {
-	api;
-	server = new WebSocketServer({ noServer: true });
-	pumps = /* @__PURE__ */ new Set();
-	/** @param api - host API supplying the typed event streams. */
-	constructor(api) {
-		this.api = api;
-	}
-	/**
-	* Upgrade one socket and pump the mux stream until either side closes.
-	* @param req - HTTP upgrade request.
-	* @param socket - Raw socket transferred by the HTTP server.
-	* @param head - Bytes already read after the upgrade headers.
-	*/
-	handleMux(req, socket, head) {
-		this.upgrade(req, socket, head, (signal) => this.api.events.mux({
-			rpcId: RpcId(randomUUID()),
-			payload: {}
-		}, signal));
-	}
-	/**
-	* Upgrade one socket and pump the host stream until either side closes.
-	* @param req - HTTP upgrade request.
-	* @param socket - Raw socket transferred by the HTTP server.
-	* @param head - Bytes already read after the upgrade headers.
-	*/
-	handleHost(req, socket, head) {
-		this.upgrade(req, socket, head, (signal) => this.api.events.host({
-			rpcId: RpcId(randomUUID()),
-			payload: {}
-		}, signal));
-	}
-	/**
-	* Terminate owned sockets and await the no-server acceptor plus frame pumps.
-	* @returns A promise resolving after every socket and source iterator stops.
-	*/
-	async close() {
-		for (const socket of this.server.clients) socket.terminate();
-		await new Promise((resolve, reject) => {
-			this.server.close((error) => {
-				if (error === void 0) resolve();
-				else reject(error);
-			});
-		});
-		await Promise.all(this.pumps);
-	}
-	upgrade(req, socket, head, open) {
-		this.server.handleUpgrade(req, socket, head, (websocket) => {
-			const abort = new AbortController();
-			websocket.once("close", () => {
-				abort.abort();
-			});
-			websocket.once("error", () => {
-				abort.abort();
-			});
-			websocket.once("message", () => {
-				websocket.close(1008, "downlink only");
-			});
-			const pump = this.pump(websocket, open(abort.signal), abort);
-			this.pumps.add(pump);
-			pump.then(() => {
-				this.pumps.delete(pump);
-			});
-		});
-	}
-	async pump(socket, frames, abort) {
-		try {
-			for await (const frame of frames) await send(socket, frame);
-		} catch (error) {
-			if (!abort.signal.aborted) try {
-				await send(socket, failureFrame(error));
-			} catch {}
-		} finally {
-			abort.abort();
-			if (socket.readyState === WebSocket.OPEN) socket.close();
-		}
-	}
-};
-/**
-* Reject an untrusted upgrade before protocol negotiation.
-* @param socket - Raw HTTP socket that remains owned by the caller.
-*/
-function rejectWebSocketUpgrade(socket) {
-	socket.end([
-		"HTTP/1.1 403 Forbidden",
-		"Connection: close",
-		"Content-Type: text/plain; charset=utf-8",
-		"Content-Length: 9",
-		"",
-		"forbidden"
-	].join("\r\n"));
+function assertFetchRoute(route) {
+	if (endpointFromPath("/api", route.path) === void 0) throw new Error(`connection: invalid exact Fetch route ${JSON.stringify(route.path)}`);
+	if (route.methods.length === 0) throw new Error(`connection: exact Fetch route ${JSON.stringify(route.path)} declares no methods`);
+	if (new Set(route.methods).size !== route.methods.length) throw new Error(`connection: exact Fetch route ${JSON.stringify(route.path)} repeats a method`);
 }
 //#endregion
 //#region lib/types/index.js
@@ -475,114 +677,45 @@ function assertImageBodyCapacity(ctx, maxRequestBodyBytes) {
 	const requiredImageBodyBytes = Math.ceil(attachments.imageLimits.maxMessageImageBytes * 4 / 3) + REQUEST_ENVELOPE_HEADROOM_BYTES;
 	if (maxRequestBodyBytes < requiredImageBodyBytes) throw new Error(`client-connection maxRequestBodyBytes (${String(maxRequestBodyBytes)}) must be at least ${String(requiredImageBodyBytes)} for the configured aggregate image limit`);
 }
-/** Services required before providing Connection; API Proxy is an optional `/api` fallback. */
-const inject = ["webServer"];
+/** Services required before providing Connection. */
+const inject = ["webServer", "credentials"];
 const Config = z.object({
 	trustedHosts: z.array(String).default([]),
+	cookieMaxAgeDays: z.natural().min(1).default(30),
 	maxRequestBodyBytes: z.natural().min(1).default(DEFAULT_MAX_REQUEST_BODY_BYTES)
 });
 /**
-* Methods gated to loopback even on a trusted-host deployment. Native dialogs
-* act on the host machine; the settings and credential domains mutate the
-* user's configuration and secret store, and READING them is equally
-* privileged — `settings.describe` returns every exposed namespace's
-* configuration and `credentials.describe` reports whether an arbitrary
-* environment-variable name is configured and where from, which is
-* reconnaissance no anonymous caller should have. `trustedHosts` is a
-* DNS-rebinding fence, explicitly not authentication, so the whole
-* configuration plane stays loopback-same-origin until a real authentication
-* layer exists. `llm.discoverModels` belongs to that plane on both counts: it
-* carries a draft credential, and it makes the HOST issue a GET to a URL the
-* caller chose and reports back the status or the parsed body — an anonymous
-* LAN caller would have a probe for whatever the host can reach and the
-* browser cannot.
-*
-* The model catalog (`llm.providers`, `llm.models`) is deliberately NOT here:
-* it carries provider ids, display names, and model lists — no endpoints,
-* keys, or key state — and a LAN client's model picker legitimately needs it.
-*/
-const PRIVILEGED_METHODS = new Set([
-	"agentPreset.read",
-	"agentPreset.copy",
-	"agentPreset.openDocument",
-	"agentPreset.remove",
-	"host.pickDirectory",
-	"host.openPath",
-	"settings.describe",
-	"settings.openDocument",
-	"settings.update",
-	"settings.replace",
-	"settings.mutate",
-	"credentials.describe",
-	"credentials.set",
-	"credentials.unset",
-	"llm.discoverModels"
-]);
-/**
 * Mounts the API gateway under the browser transport prefix. Every request on
-* the prefix passes the browser-trust fence first (DNS-rebinding and
-* cross-site defense — [api-request-trust](./api-request-trust.ts));
-* privileged methods additionally pass it with an empty trust list, which
-* pins them to loopback.
+* the prefix passes the Host/Origin browser-trust fence and persistent browser
+* authentication before dispatch.
 * @param ctx - Host plugin context.
 * @param config - resolved plugin config (schema defaults applied).
 */
-function apply(ctx, config) {
+async function apply(ctx, config) {
 	const trustedHosts = config?.trustedHosts ?? [];
+	const cookieMaxAgeDays = config?.cookieMaxAgeDays ?? 30;
 	const maxRequestBodyBytes = config?.maxRequestBodyBytes ?? 314572800;
 	for (const entry of trustedHosts) assertTrustedAuthority(entry);
-	if (ctx.get("apiProxy") !== void 0) assertImageBodyCapacity(ctx, maxRequestBodyBytes);
-	const fetchHandler = new HostConnectionService(ctx, trustedHosts).createSharedFetchHandler(API_PATH, { async fetch(request) {
-		const pathname = new URL(request.url).pathname;
-		const method = pathname.startsWith(`/api/`) ? pathname.slice(5) : void 0;
-		if (method !== void 0 && PRIVILEGED_METHODS.has(method) && !isTrustedApiRequest(request, [])) return new Response("forbidden", { status: 403 });
-		if (request.method === "GET" && (pathname === MUX_EVENTS_PATH || pathname === HOST_EVENTS_PATH)) return new Response("upgrade required", {
-			status: 426,
-			headers: {
-				connection: "Upgrade",
-				upgrade: "websocket"
-			}
-		});
-		const apiProxy = ctx.get("apiProxy");
-		if (apiProxy === void 0) return new Response("not found", { status: 404 });
-		return toFetchHandler(apiProxy).fetch(request);
-	} });
+	assertImageBodyCapacity(ctx, maxRequestBodyBytes);
+	const connection = new HostConnectionService(ctx, trustedHosts, await BrowserAuth.create(ctx.root, ctx.credentials, cookieMaxAgeDays));
+	const fetchHandler = connection.createSharedFetchHandler(API_PATH);
 	const route = {
 		kind: "prefix",
 		path: API_PATH,
 		handler: async (req, res) => {
-			if (!isTrustedApiRequest(req, trustedHosts)) {
-				res.writeHead(403);
-				res.end("forbidden");
+			const rejection = connection.requestRejection(req);
+			if (rejection !== void 0) {
+				res.writeHead(rejection);
+				res.end(rejection === 401 ? "unauthorized" : "forbidden");
 				return;
 			}
 			await bridge(req, res, fetchHandler, maxRequestBodyBytes);
 		}
 	};
 	ctx.effect(() => ctx.webServer.register(route), "client-connection: /api route");
-	ctx.inject(["apiProxy"], (apiCtx) => {
-		assertImageBodyCapacity(apiCtx, maxRequestBodyBytes);
-		const downlinks = new WebSocketDownlinks(apiCtx.apiProxy);
-		const registerDownlink = (path, handle) => {
-			apiCtx.effect(() => apiCtx.webServer.registerUpgrade({
-				path,
-				handler: (req, socket, head) => {
-					if (!isTrustedApiRequest(req, trustedHosts)) {
-						rejectWebSocketUpgrade(socket);
-						return;
-					}
-					return handle(req, socket, head);
-				}
-			}), `client-connection: ${path} WebSocket`);
-		};
-		apiCtx.effect(() => () => downlinks.close(), "client-connection: WebSocket downlinks");
-		registerDownlink(MUX_EVENTS_PATH, (req, socket, head) => {
-			downlinks.handleMux(req, socket, head);
-		});
-		registerDownlink(HOST_EVENTS_PATH, (req, socket, head) => {
-			downlinks.handleHost(req, socket, head);
-		});
+	ctx.inject(["attachments"], (attachmentCtx) => {
+		assertImageBodyCapacity(attachmentCtx, maxRequestBodyBytes);
 	});
 }
 //#endregion
-export { API_PATH, Config, HOST_EVENTS_PATH, HostConnectionService, MUX_EVENTS_PATH, apply, inject, name };
+export { API_PATH, Config, HostConnectionService, RpcId, apply, clientRequestSchema, inject, name, rpcErrorSchema, rpcIdSchema, rpcMessageSchema, rpcResultSchema, serverResponseSchema, transportError };