@qilin-agent/client-connection 3.1.5 → 3.1.7

package/README.i18n.yaml

@@ -18,8 +18,8 @@
   en: ef04350968741ba3
   zh: abcded86153ddd9b
 /qilin-agent-client-connection/browser-authentication-and-request-trust:
-  en: 73a9f2fd2c2d559e
-  zh: 4b629185fecee159
+  en: e0384068ca1d7bdc
+  zh: 4bfba70fcfd4644f
 /qilin-agent-client-connection/connection-generation:
   en: d260c2ac53a86c8f
   zh: 3f1de43f27afd85e
@@ -30,8 +30,8 @@
   en: ca75c51c89c2c9b0
   zh: de54f3467ef3b9be
 /qilin-agent-client-connection/known-limitations-and-deferred-work:
-  en: 21d90520c2e5d4b9
-  zh: c9ae88395b272977
+  en: 8cae222e65d57f54
+  zh: e5b9d49db39be732
 /qilin-agent-client-connection/known-limitations-and-deferred-work/dev-note:
   en: e67f633dc6fe7773
   zh: e88aeb617ffb74ea

package/README.md

@@ -38,11 +38,13 @@ Every Host RPC method and WebSocket stream requires one browser session; there i
 
 `ctx.connection.session` is the seat where an authentication capability installs an account-session authority. `install(authority)` seats one `ConnectionSessionAuthority` and returns the disposer releasing it; a second installation fails the installing plugin's load, because two session authorities cannot compose. The authority owns three verdicts: `authorizeIndex` owns the browser response for a gated index request, `isPublicApiRequest` marks the requests that belong to the authentication surface itself and need no session, and `verify` checks the request's session. While an authority claims the seat, `requestRejection` requires `verify` for every `/api` request it does not declare public, and `authorizeIndex` runs the launch-token exchange first — cleaning the printed URL into the entry redirect — then serves a gated index only for a verified session. Without an authority the device cookie stays the only browser credential, which is what a deployment with the gate disabled keeps.
 
-The cookie signing secret is the owner-scoped `client-connection/browser-session` grant record in `ctx.credentials`. The local provider persists it in `$QILIN_HOME/.credentials.yaml`; `BrowserAuth` loads or creates the record during Connection activation and retains the secret in memory, so request authentication is synchronous. Deleting or replacing the record takes effect on the next Connection activation. Cookies carry an absolute issue/expiry interval, defaulting to 30 days through `cookieMaxAgeDays`, and bind the normalized hostname plus port in both their deterministic name and signed payload. They are host-only, `Path=/`, `HttpOnly`, and `SameSite=Strict`; they deliberately omit `Secure` because the shipped server uses loopback HTTP.
+The cookie signing secret is the owner-scoped `client-connection/browser-session` grant record in `ctx.credentials`. The local provider persists it in `$QILIN_HOME/.credentials.yaml`; `BrowserAuth` loads or creates the record during Connection activation and retains the secret in memory, so request authentication is synchronous. Deleting or replacing the record takes effect on the next Connection activation. Cookies carry an absolute issue/expiry interval, defaulting to 30 days through `cookieMaxAgeDays`, and bind the normalized hostname plus port in both their deterministic name and signed payload. They are host-only, `Path=/`, `HttpOnly`, and `SameSite=Strict`, and carry `Secure` exactly when the listener that received the index request serves TLS; only that listener's own protocol decides, never a `publicUrl` announcement or a forwarded header.
 
-Before authentication, every request still passes `src/api-request-trust.ts`. Its `Host` must be loopback or match a `trustedHosts` entry: exact on `host:port`, any port on port-less entries, both sides WHATWG-normalized. An attached `Origin` must equal that Host and `sec-fetch-site: cross-site` is refused. Malformed configured authorities fail plugin load. These checks defend DNS rebinding and cross-site browser requests; they never establish identity. A failed Host/Origin check returns 403, while a trusted but unauthenticated request returns 401. `qilin web --host 0.0.0.0` remains unsupported. Decision records: [browser request trust](../../../.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md) and [browser token authentication](../../../.agents/notes/implemented/architecture/2026-08-24-browser-token-authentication.md).
+HTTPS cookie names and signed audiences include the `https:` scheme, so HTTP cookies cannot authenticate to a TLS listener even on the same hostname and port. Default ports normalize under the listener's scheme. Existing HTTP cookie audiences remain unchanged.
 
-Every admitted request speaks for one Peer, the operator. `ctx.connection.operator` is that `PeerScope`: its `ctx` is a Kylin scope that owns connection-lifetime registrations and is disposed with the Connection. `ctx.connection.admit(request)` runs the trust and authentication checks and answers with the rejection status or the operator; the `/api` route and the Gateway's WebSocket upgrade admit through it, and every RPC handler receives the Peer of its call. `OperatorPeer` is exported so a composition without Connection, such as the Gateway's in-process carrier, owns an operator scope with the same contract.
+Before authentication, every request still passes `src/api-request-trust.ts`. Its `Host` must be loopback, equal the listener's bind IP literal on any port, or match a `trustedHosts` entry: exact on `host:port`, any port on port-less entries. Host and configured entries use the listener's scheme for WHATWG default-port normalization, not a forwarded header or `Origin`. An attached HTTP(S) `Origin` must name the same authority, with Host parsed under that Origin's scheme to support HTTPS proxies over HTTP upstreams; `sec-fetch-site: cross-site` is refused. Malformed configured authorities fail plugin load. These checks defend DNS rebinding and cross-site browser requests; they never establish identity. A failed Host/Origin check returns 403, while a trusted but unauthenticated request returns 401. `qilin web --host 0.0.0.0` remains unsupported. Decision records: [browser request trust](../../../.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md) and [browser token authentication](../../../.agents/notes/implemented/architecture/2026-08-24-browser-token-authentication.md).
+
+Every admitted request speaks for one Peer, the operator. `ctx.connection.operator` is that `PeerScope`: its `ctx` is a Kylin scope that owns connection-lifetime registrations and is disposed with the Connection. `ctx.connection.admit(request)` runs the trust and authentication checks and answers with the rejection status or the operator; the `/api` route and the Gateway's WebSocket upgrade admit through it, and every RPC handler receives the Peer of its call. `Peer` is the concrete `PeerScope`: a composition without Connection, such as the Gateway's in-process carrier, constructs one with the same contract.
 
 Authenticated shared HTTP requests pass through the `connection/request` waterfall before body transfer. A listener may refuse new requests or await `next()` through response completion; removing its owning fiber removes admission behavior. Desktop uses this hook to lock new API work during an approved installation without canceling already-admitted work. WebSocket stream ownership remains with API Gateway.
 
@@ -72,7 +74,7 @@ None; this package neither assembles nor sends a provider request.
 <a id="known-limitations-and-deferred-work"></a>
 
 - **Buffered `/api` routes retain each request body in memory** — `maxRequestBodyBytes` (default 300 MiB, sized for the default 200 MiB aggregate image limit after base64 expansion plus envelope headroom) bounds ordinary image and RPC envelopes. Opt-in streaming routes receive backpressured chunks and bypass the aggregate cap; route implementations own persistence, cancellation, and any storage quota.
-- **The browser cookie is not marked `Secure`** — loopback HTTP is the shipped transport, so exposing the same authority over plaintext networking can expose the bearer cookie in transit.
+- **A plain-HTTP listener exposes the bearer cookie in transit** — such a deployment cannot mark the browser cookie `Secure`, so serving the same authority over a network can leak the session cookie; configure TLS on the Web carrier ([`qilin-host-webserver`](../../host/webserver/README.md)) to have the cookie marked `Secure` and confined to TLS.
 - **The device cookie has no logout operation** — clearing the browser cookie ends one browser session; deleting the owner credential record and restarting `qilin` revokes every session.
 
 

package/README.zh.md

@@ -38,11 +38,13 @@ kind: "package-reference"
 
 `ctx.connection.session` 是认证能力安置账户会话 authority 的席位。`install(authority)` 安置唯一的 `ConnectionSessionAuthority` 并返回释放该席位的 disposer；第二次安置会让安装方插件加载失败，因为两个会话 authority 无法组合。authority 拥有三项判定：`authorizeIndex` 拥有受门禁 index 请求的浏览器响应，`isPublicApiRequest` 标记属于认证表层本身、无需会话的请求，`verify` 校验请求的会话。authority 占据席位期间，`requestRejection` 对该 authority 未声明为公开的每个 `/api` 请求都要求 `verify` 通过；`authorizeIndex` 先执行启动令牌交换——把打印出的 URL 清理为入口重定向——再只为通过校验的会话提供受门禁 index。没有 authority 时，设备 cookie 仍是唯一的浏览器凭据，这正是禁用门禁的部署所保留的行为。
 
-cookie 签名密钥是 `ctx.credentials` 中由 `client-connection/browser-session` 拥有的 grant 记录。本地提供方把它持久化到 `$QILIN_HOME/.credentials.yaml`；`BrowserAuth` 在 Connection 激活期间加载或创建该记录，并把密钥留在内存中，因此请求认证同步执行。删除或替换该记录会在下一次 Connection 激活时生效。cookie 携带绝对签发与过期区间，`cookieMaxAgeDays` 默认设为 30 天，并在确定性名称与签名 payload 中同时绑定规范化 hostname 和 port。它是 host-only、`Path=/`、`HttpOnly`、`SameSite=Strict`；随附服务器使用 loopback HTTP，因此刻意不设置 `Secure`。
+cookie 签名密钥是 `ctx.credentials` 中由 `client-connection/browser-session` 拥有的 grant 记录。本地提供方把它持久化到 `$QILIN_HOME/.credentials.yaml`；`BrowserAuth` 在 Connection 激活期间加载或创建该记录，并把密钥留在内存中，因此请求认证同步执行。删除或替换该记录会在下一次 Connection 激活时生效。cookie 携带绝对签发与过期区间，`cookieMaxAgeDays` 默认设为 30 天，并在确定性名称与签名 payload 中同时绑定规范化 hostname 和 port。它是 host-only、`Path=/`、`HttpOnly`、`SameSite=Strict`，并且只在接收 index 请求的监听器以 TLS 服务时才带 `Secure`；由该监听器自身的协议决定，绝不由 `publicUrl` 公告或转发头决定。
 
-认证之前，每个请求仍经过 `src/api-request-trust.ts`。其 `Host` 必须是 loopback，或与 `trustedHosts` 条目匹配：带端口的 `host:port` 精确匹配，不带端口的条目匹配任意端口，两侧均经 WHATWG 归一化。若附带 `Origin`，它必须等于该 Host；`sec-fetch-site: cross-site` 一律拒绝。畸形配置 authority 会让插件加载失败。这些检查防御 DNS rebinding 与跨站浏览器请求，绝不建立身份。Host/Origin 校验失败返回 403；Host 可信但未认证的请求返回 401。`qilin web --host 0.0.0.0` 仍不受支持。决策记录：[浏览器请求信任](../../../.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.zh.md)与[浏览器令牌认证](../../../.agents/notes/implemented/architecture/2026-08-24-browser-token-authentication.zh.md)。
+HTTPS cookie 的名称与签名 audience 都包含 `https:` scheme，因此 HTTP cookie 无法向 TLS 监听器认证，即便 hostname 和端口相同。默认端口按监听器的 scheme 归一化。既有 HTTP cookie audience 保持不变。
 
-每个被接纳的请求都代表同一个 Peer——操作者。`ctx.connection.operator` 就是这个 `PeerScope`：其 `ctx` 是拥有连接期注册的 Kylin scope，随 Connection 一起释放。`ctx.connection.admit(request)` 执行信任与认证检查，以拒绝状态或操作者作答；`/api` 路由与 Gateway 的 WebSocket 升级都经它接纳，每个 RPC 处理器都收到本次调用的 Peer。`OperatorPeer` 对外导出，供没有 Connection 的组合（例如 Gateway 的进程内载体）以同一约定拥有一个操作者 scope。
+认证之前，每个请求仍经过 `src/api-request-trust.ts`。其 `Host` 必须是 loopback、等于监听器自身的 bind IP 字面量（任意端口），或与 `trustedHosts` 条目匹配：带端口的 `host:port` 精确匹配，不带端口的条目匹配任意端口。Host 与配置条目按监听器的 scheme 做 WHATWG 默认端口归一化，而不是转发头或 `Origin`。若附带 HTTP(S) `Origin`，它必须指名同一 authority，Host 按该 Origin 的 scheme 解析以支持 HTTP 上游之前的 HTTPS 代理；`sec-fetch-site: cross-site` 一律拒绝。畸形配置 authority 会让插件加载失败。这些检查防御 DNS rebinding 与跨站浏览器请求，绝不建立身份。Host/Origin 校验失败返回 403；Host 可信但未认证的请求返回 401。`qilin web --host 0.0.0.0` 仍不受支持。决策记录：[浏览器请求信任](../../../.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.zh.md)与[浏览器令牌认证](../../../.agents/notes/implemented/architecture/2026-08-24-browser-token-authentication.zh.md)。
+
+每个被接纳的请求都代表同一个 Peer——操作者。`ctx.connection.operator` 就是这个 `PeerScope`：其 `ctx` 是拥有连接期注册的 Kylin scope，随 Connection 一起释放。`ctx.connection.admit(request)` 执行信任与认证检查，以拒绝状态或操作者作答；`/api` 路由与 Gateway 的 WebSocket 升级都经它接纳，每个 RPC 处理器都收到本次调用的 Peer。`Peer` 是 `PeerScope` 的具体实现：没有 Connection 的组合（例如 Gateway 的进程内载体）按同一约定构造一个。
 
 通过认证的共享 HTTP 请求在传输请求体之前经过 `connection/request` waterfall。监听器可以拒绝新请求，或等待 `next()` 直到响应完成；释放所属 fiber 会移除准入行为。Desktop 使用此扩展点，在已批准的安装期间锁住新的 API 工作，而不取消已接纳的工作。WebSocket 流仍由 API Gateway 负责。
 
@@ -72,7 +74,7 @@ API Gateway Client 把内部 `$events` logical stream 注册为唯一 generation
 <a id="known-limitations-and-deferred-work"></a>
 
 - **缓冲型 `/api` 路由会把每个请求体保留在内存里**：`maxRequestBodyBytes`（默认 300 MiB，按默认 200 MiB 图片总量上限经 base64 膨胀加信封余量得出）限制普通图片与 RPC 信封。显式启用的流式路由接收带背压的分块并绕过总量上限；路由实现负责持久化、取消与存储配额。
-- **浏览器 cookie 不带 `Secure`**：随附载体是 loopback HTTP；若部署经明文网络暴露同一 authority，bearer cookie 可能在传输中泄露。
+- **明文 HTTP 监听器会在传输中暴露 bearer cookie**：这类部署无法给浏览器 cookie 加 `Secure`，经网络服务同一 authority 可能泄露会话 cookie；在 Web 载体上配置 TLS（[`qilin-host-webserver`](../../host/webserver/README.zh.md)）即可让 cookie 带 `Secure` 并被限定在 TLS 内。
 - **设备 cookie 没有 logout 操作**：清除浏览器 cookie 会结束单个浏览器会话；删除 owner 凭据记录并重启 `qilin` 会撤销全部会话。
 
 

package/lib/client.js

@@ -1292,6 +1292,23 @@ window.__ModuleLoader__.load({
 			return parts.length === 4 && parts[0] === "127" && parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255);
 		}
 		//#endregion
+		//#region lib/types/client/socket.js
+		/** Physical socket selection for browser, desktop, and authenticated Node connections. */
+		/**
+		* Resolve a logical channel against the explicit Host or the page's document base.
+		* @param path - absolute logical channel path.
+		* @param factory - authenticated socket factory; omission uses the browser API.
+		* @param baseUrl - Host base URL, required outside a document.
+		* @returns a socket owned by the calling channel.
+		*/
+		function openConnectionWebSocket(path, factory = (url) => new WebSocket(url), baseUrl) {
+			const base = baseUrl ?? (typeof document === "undefined" ? void 0 : document.baseURI);
+			if (base === void 0) throw new Error("connection: WebSocket carrier requires streamBaseUrl outside a document");
+			const url = new URL(path.slice(1), base);
+			url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+			return factory(url.href);
+		}
+		//#endregion
 		//#region lib/types/client/index.js
 		/** Required services (none — this is the wire root). */
 		const inject = [];
@@ -1322,6 +1339,7 @@ window.__ModuleLoader__.load({
 			const pageLocation = options.location;
 			const transport = options.transport;
 			const recovery = options.recovery ?? {};
+			const interactions = options.interactions ?? (pageLocation === void 0 ? "none" : "answer");
 			const rpc = transport?.rpc ?? createWebConnectionRpc(transport?.fetch, transport?.openStream);
 			let generationSource;
 			let owner;
@@ -1357,6 +1375,8 @@ window.__ModuleLoader__.load({
 				publishState(void 0);
 			};
 			const handle = {
+				interactions,
+				openWebSocket: (path) => openConnectionWebSocket(path, transport?.createWebSocket, transport?.streamBaseUrl),
 				isLoopback: transport?.ownsHost === true || pageLocation === void 0 || isLoopbackHostname(pageLocation.hostname),
 				generation: {
 					getSnapshot: () => generation,

package/lib/index.js

@@ -13,6 +13,11 @@ import { createScope } from "@qilin-agent/scope";
 /** Route prefix owning every api request (`/api` and `/api/<anything>`). */
 const API_PATH = "/api";
 //#endregion
+//#region lib/types/connect-protocol.js
+/** API connection inputs shared by the Host and its clients. */
+/** Launch-token exchange route for API clients. */
+const CONNECT_PATH = "/connect";
+//#endregion
 //#region lib/types/http-bridge.js
 /**
 * node:http ↔ WHATWG fetch bridge for the /api transport (host side of the
@@ -29,9 +34,10 @@ const DEFAULT_MAX_REQUEST_BODY_BYTES = 300 * 1024 * 1024;
 * @param req - incoming node:http request.
 * @param res - node:http response the bridge writes and owns to completion.
 * @param apiHandler - fetch-shaped API carrier the request is dispatched to.
+* @param peer - Peer the carrier admitted the request as.
 * @param maxRequestBodyBytes - maximum bytes buffered for a buffered route.
 */
-async function bridge(req, res, apiHandler, maxRequestBodyBytes = DEFAULT_MAX_REQUEST_BODY_BYTES) {
+async function bridge(req, res, apiHandler, peer, maxRequestBodyBytes = DEFAULT_MAX_REQUEST_BODY_BYTES) {
 	const abort = new AbortController();
 	res.on("close", () => {
 		if (!res.writableEnded) abort.abort();
@@ -79,7 +85,7 @@ async function bridge(req, res, apiHandler, maxRequestBodyBytes = DEFAULT_MAX_RE
 		signal: abort.signal,
 		duplex: "half"
 	});
-	const response = await apiHandler.fetch(request);
+	const response = await apiHandler.fetch(request, peer);
 	const requestUnread = bodyMode === "streaming" && !req.readableEnded;
 	const responseHeaders = Object.fromEntries(response.headers.entries());
 	res.writeHead(response.status, requestUnread ? {
@@ -297,12 +303,13 @@ function header(headers, name) {
 	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) {
+/** Protocol-scoped cookie audience; HTTP retains its existing authority-only spelling. */
+function requestAudience(headers, secure) {
 	const host = header(headers, "host");
 	if (host === void 0) return void 0;
 	try {
-		return new URL(`http://${host}`).host;
+		const url = new URL(`${secure ? "https:" : "http:"}//${host}`);
+		return secure ? url.origin : url.host;
 	} catch {
 		return;
 	}
@@ -337,8 +344,9 @@ function cookieValue(headerValue, name) {
 	}
 }
 /** 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 sessionCookie(name, value, expiresAt, maxAgeSeconds, secure) {
+	const attributes = `${name}=${value}; Max-Age=${String(maxAgeSeconds)}; Path=/; Expires=${new Date(expiresAt).toUTCString()}; HttpOnly; SameSite=Strict`;
+	return secure ? `${attributes}; Secure` : attributes;
 }
 function signature(secret, body) {
 	return createHmac("sha256", secret).update(body).digest();
@@ -359,12 +367,12 @@ function writeEntryRedirect(res) {
 }
 function encodeCookie(payload, secret) {
 	const body = encodeBase64Url(Buffer.from(JSON.stringify(payload), "utf8"));
-	return `v1.${body}.${encodeBase64Url(signature(secret, body))}`;
+	return `v${payload.version}.${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;
+	if (parts.length !== 3 || version !== "v1" && version !== "v2" || body === void 0 || encodedSignature === void 0) return;
 	const actualSignature = decodeBase64Url(encodedSignature);
 	if (actualSignature === void 0) return void 0;
 	const expectedSignature = signature(secret, body);
@@ -377,9 +385,26 @@ function decodeCookie(value, secret) {
 	} 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;
-	if (decoded.displayName !== void 0 && !boundedDisplayName(decoded.displayName)) return void 0;
-	return decoded;
+	if (!isRecord(decoded) || decoded.version !== COOKIE_PAYLOAD_VERSION && decoded.version !== 2 || version !== `v${String(decoded.version)}` || typeof decoded.authority !== "string" || typeof decoded.issuedAt !== "number" || !Number.isSafeInteger(decoded.issuedAt) || typeof decoded.expiresAt !== "number" || !Number.isSafeInteger(decoded.expiresAt)) return void 0;
+	const payload = {
+		authority: decoded.authority,
+		issuedAt: decoded.issuedAt,
+		expiresAt: decoded.expiresAt
+	};
+	if (decoded.version === COOKIE_PAYLOAD_VERSION) {
+		if (decoded.displayName !== void 0 && !boundedDisplayName(decoded.displayName)) return void 0;
+		return {
+			version: COOKIE_PAYLOAD_VERSION,
+			...payload,
+			displayName: decoded.displayName
+		};
+	}
+	if (typeof decoded.id !== "string" || decoded.id.length === 0) return void 0;
+	return {
+		version: 2,
+		...payload,
+		id: decoded.id
+	};
 }
 /** Accept a display name the launching host attached: trimmed, bounded, control-free. */
 function boundedDisplayName(value) {
@@ -457,20 +482,24 @@ var BrowserAuth = class BrowserAuth {
 	* 401 response.
 	* @param req - incoming entry or configured-index request.
 	* @param res - response owned when this method returns false.
+	* @param secure - whether the listener receiving this request serves TLS; the
+	* minted cookie carries `Secure` when it does. Only that listener's own
+	* protocol decides, never a `publicUrl` announcement or a forwarded header:
+	* those describe a hop this process does not terminate.
 	* @returns true only when the caller may serve index.html.
 	*/
-	authorizeIndex(req, res) {
+	authorizeIndex(req, res, secure = false) {
 		const url = requestUrl(req);
 		if (url.searchParams.getAll(TOKEN_QUERY).length > 0) {
-			if (this.exchangeToken(req, res)) return false;
-			if (req.method === "GET" && url.pathname === "/workspace" && this.isAuthenticated(req)) {
+			if (this.exchangeToken(req, res, secure)) return false;
+			if (req.method === "GET" && url.pathname === "/workspace" && this.isAuthenticated(req, secure)) {
 				writeEntryRedirect(res);
 				return false;
 			}
 			this.writeUnauthorized(req, res);
 			return false;
 		}
-		if (this.isAuthenticated(req)) return true;
+		if (this.isAuthenticated(req, secure)) return true;
 		this.writeUnauthorized(req, res);
 		return false;
 	}
@@ -479,12 +508,14 @@ var BrowserAuth = class BrowserAuth {
 	* entry path: the handoff that turns the printed URL into a browser session.
 	* @param req - incoming request; its only token input is the query.
 	* @param res - response owned when the exchange applies.
+	* @param secure - whether the listener receiving this request serves TLS; the
+	* minted cookie carries `Secure` and an `https:`-scoped audience when it does.
 	* @returns true when a valid token was exchanged and the redirect written.
 	*/
-	exchangeToken(req, res) {
+	exchangeToken(req, res, secure = false) {
 		const url = requestUrl(req);
 		const tokens = url.searchParams.getAll(TOKEN_QUERY);
-		const authority = requestAuthority(req.headers);
+		const authority = requestAudience(req.headers, secure);
 		if (req.method !== "GET" || url.pathname !== "/workspace" || tokens.length !== 1 || authority === void 0 || !tokenMatches(tokens.join(""), this.launchToken)) return false;
 		const requested = url.searchParams.get(DISPLAY_NAME_QUERY)?.trim();
 		const issuedAt = Date.now();
@@ -500,18 +531,84 @@ var BrowserAuth = class BrowserAuth {
 			"cache-control": "no-store",
 			"location": WEB_ENTRY_PATH,
 			"referrer-policy": "no-referrer",
-			"set-cookie": sessionCookie(cookieName(authority), value, expiresAt, Math.floor(this.maxAgeMilliseconds / 1e3))
+			"set-cookie": sessionCookie(cookieName(authority), value, expiresAt, Math.floor(this.maxAgeMilliseconds / 1e3), secure)
 		});
 		res.end();
 		return true;
 	}
 	/**
+	* Exchange the launch token for an independent API operator; omitted interactions default to none.
+	* @param req - trusted GET request on /connect with at most one interactions declaration.
+	* @param res - response owned to completion, redirecting to the API mux on success.
+	* @param secure - whether the receiving listener serves TLS.
+	* @param publish - synchronously create the operator before exposing its signed credential.
+	*/
+	authorizeConnect(req, res, secure, publish) {
+		const url = requestUrl(req);
+		const declarations = url.searchParams.getAll("interactions");
+		const interactions = declarations[0] ?? "none";
+		if (declarations.length > 1 || interactions !== "answer" && interactions !== "none") {
+			res.writeHead(400, {
+				"cache-control": "no-store",
+				"content-type": "text/plain; charset=utf-8"
+			});
+			res.end("interactions must be declared once as answer or none\n");
+			return;
+		}
+		const tokens = url.searchParams.getAll(TOKEN_QUERY);
+		const authority = requestAudience(req.headers, secure);
+		if (req.method !== "GET" || url.pathname !== "/connect" || tokens.length !== 1 || authority === void 0 || !tokenMatches(tokens.join(""), this.launchToken)) {
+			this.writeUnauthorized(req, res);
+			return;
+		}
+		const issuedAt = Date.now();
+		const expiresAt = issuedAt + this.maxAgeMilliseconds;
+		const value = encodeCookie({
+			version: 2,
+			authority,
+			id: publish(interactions),
+			issuedAt,
+			expiresAt
+		}, this.secret);
+		res.writeHead(302, {
+			"cache-control": "no-store",
+			"location": "./api/remote.mux",
+			"referrer-policy": "no-referrer",
+			"set-cookie": sessionCookie(cookieName(authority), value, expiresAt, Math.floor(this.maxAgeMilliseconds / 1e3), secure)
+		});
+		res.end();
+	}
+	/**
 	* Verify the authority-bound browser cookie on a Host request.
 	* @param request - request headers carrying Host and Cookie.
+	* @param secure - whether the receiving listener serves TLS; only a cookie
+	* minted for that same protocol's audience authenticates.
 	* @returns true only for an unexpired cookie signed by this activation's loaded secret.
 	*/
-	isAuthenticated(request) {
-		return this.identity(request).authenticated;
+	isAuthenticated(request, secure = false) {
+		return this.authenticate(request, secure)?.version === COOKIE_PAYLOAD_VERSION;
+	}
+	/**
+	* Verify an API credential without creating or reviving its operator.
+	* @param request - request headers carrying Host and Cookie.
+	* @param secure - whether the receiving listener uses TLS.
+	* @returns the signed operator id, or undefined for invalid, expired, or browser cookies.
+	*/
+	authenticateApi(request, secure = false) {
+		const payload = this.authenticate(request, secure);
+		return payload?.version === 2 ? payload.id : void 0;
+	}
+	authenticate(request, secure) {
+		const authority = requestAudience(request.headers, secure);
+		const rawCookie = header(request.headers, "cookie");
+		if (authority === void 0 || rawCookie === void 0) return void 0;
+		const value = cookieValue(rawCookie, cookieName(authority));
+		if (value === void 0) return void 0;
+		const payload = decodeCookie(value, this.secret);
+		if (payload === void 0 || payload.authority !== authority) return void 0;
+		const now = Date.now();
+		if (payload.issuedAt > now || payload.expiresAt <= now || payload.expiresAt <= payload.issuedAt || payload.expiresAt - payload.issuedAt > this.maxAgeMilliseconds) return void 0;
+		return payload;
 	}
 	/**
 	* Read the device session behind a Host request: its authentication fact and
@@ -519,21 +616,16 @@ var BrowserAuth = class BrowserAuth {
 	* identity channel for deployments without the account gate, and the gate's
 	* own status route stays authoritative wherever that is mounted.
 	* @param request - request headers carrying Host and Cookie.
+	* @param secure - whether the receiving listener serves TLS; the cookie
+	* audience is scoped to that protocol.
 	* @returns the session fact and display name of the request's device session.
 	*/
-	identity(request) {
-		const authority = requestAuthority(request.headers);
-		const rawCookie = header(request.headers, "cookie");
-		if (authority === void 0 || rawCookie === void 0) return UNIDENTIFIED;
-		const value = cookieValue(rawCookie, cookieName(authority));
-		if (value === void 0) return UNIDENTIFIED;
-		const payload = decodeCookie(value, this.secret);
-		if (payload === void 0 || payload.authority !== authority) return UNIDENTIFIED;
-		const now = Date.now();
-		const authenticated = payload.issuedAt <= now && payload.expiresAt > now && payload.expiresAt > payload.issuedAt && payload.expiresAt - payload.issuedAt <= this.maxAgeMilliseconds;
+	identity(request, secure = false) {
+		const payload = this.authenticate(request, secure);
+		if (payload === void 0 || payload.version !== COOKIE_PAYLOAD_VERSION) return UNIDENTIFIED;
 		return {
-			authenticated,
-			accountName: authenticated ? payload.displayName ?? null : null
+			authenticated: true,
+			accountName: payload.displayName ?? null
 		};
 	}
 	writeUnauthorized(req, res) {
@@ -611,26 +703,39 @@ const serverResponseSchema = z$1.object({
 /** Either Connection RPC envelope direction. */
 const rpcMessageSchema = z$1.discriminatedUnion("type", [clientRequestSchema, serverResponseSchema]);
 //#endregion
-//#region lib/types/operator-peer.js
+//#region lib/types/peer.js
 /**
-* The operator Peer: the one party this Host answers to. Connection owns it
-* for its own lifetime, admits every request as it, and hands it to each
-* Remote call as `invocation.peer`.
-* @module @qilin-agent/client-connection/src/operator-peer
+* The Peer: one party admitted to this Host. Its creator fixes the principal
+* it speaks for and owns its lifetime; Gateway hands it to each Remote call as
+* `invocation.peer`.
+* @module @qilin-agent/client-connection/src/peer
 */
 /**
-* The operator's scope. The instance is its own scope key, so `scopeOf(peer.ctx)`
+* One Peer's scope. The instance is its own scope key, so `scopeOf(peer.ctx)`
 * returns it and events dispatched with `scopeTarget(subject, peer)` reach
 * listeners registered through `peer.ctx` and nobody else.
 */
-var OperatorPeer = class {
+var Peer = class {
 	id = randomUUID();
 	ctx;
+	principal;
+	interactions;
+	signal;
 	scope;
-	/** @param owner - Connection plugin context the scope fiber hangs under. */
-	constructor(owner) {
+	/**
+	* @param owner - Context the scope fiber hangs under; disposing it disposes the Peer.
+	* @param options - the principal fixed for this Peer's lifetime.
+	*/
+	constructor(owner, options) {
+		this.principal = options.principal;
+		this.interactions = options.interactions ?? "answer";
 		this.scope = createScope(owner, this);
 		this.ctx = this.scope.ctx;
+		const lifetime = new AbortController();
+		this.signal = lifetime.signal;
+		this.ctx.effect(() => () => {
+			lifetime.abort(/* @__PURE__ */ new Error(`Peer ${this.id} was disposed`));
+		}, "client-connection: Peer lifetime");
 	}
 	/** Tear down every connection-lifetime registration; racing calls share one completion. */
 	dispose() {
@@ -654,8 +759,11 @@ const AUTH_STATUS_PATH = "/api/auth/status";
 var HostConnectionService = class extends Service {
 	trustedHosts;
 	browserAuth;
-	/** The operator Peer every admitted request speaks for. */
-	operator;
+	/** The Peer every authenticated browser connection shares. */
+	browserPeer;
+	peers = /* @__PURE__ */ new Map();
+	owner;
+	disposed = false;
 	interceptors = /* @__PURE__ */ new Map();
 	fetchRoutes = /* @__PURE__ */ new Map();
 	sessionAuthority;
@@ -669,8 +777,14 @@ var HostConnectionService = class extends Service {
 		super(ctx, "connection");
 		this.trustedHosts = trustedHosts;
 		this.browserAuth = browserAuth;
-		this.operator = new OperatorPeer(ctx);
-		ctx.effect(() => () => this.operator.dispose(), "client-connection: operator Peer");
+		this.owner = ctx;
+		this.browserPeer = new Peer(ctx, { principal: { kind: "owner" } });
+		ctx.effect(() => async () => {
+			this.disposed = true;
+			const peers = [this.browserPeer, ...Array.from(this.peers.values(), (record) => record.peer)];
+			this.peers.clear();
+			await Promise.all(peers.map((peer) => peer.dispose()));
+		}, "client-connection: Peer scopes");
 	}
 	/** Generic channel registry scoped to the Context reading this service. */
 	get rpc() {
@@ -702,27 +816,89 @@ var HostConnectionService = class extends Service {
 	* cookie minted by the launch-token exchange.
 	*/
 	requestRejection(request) {
-		const carrier = this.ctx.get("webServer");
-		if (!isTrustedApiRequest(request, this.trustedHosts, carrier?.host, carrier?.protocol ?? "http:")) return 403;
-		const authority = this.sessionAuthority;
-		if (authority === void 0) return this.browserAuth.isAuthenticated(request) ? void 0 : 401;
-		if (authority.isPublicApiRequest(request)) return void 0;
-		return authority.verify(request) ? void 0 : 401;
+		const admission = this.admit(request);
+		return "rejection" in admission ? admission.rejection : void 0;
 	}
-	/** A request that passes the fence and authentication speaks for the operator. */
+	/** Browser requests share an owner Peer; the account-session authority admits its own bearers. */
 	admit(request) {
-		const rejection = this.requestRejection(request);
-		return rejection === void 0 ? { peer: this.operator } : { rejection };
+		if (!this.isTrusted(request)) return { rejection: 403 };
+		if (this.disposed) return { rejection: 401 };
+		const secure = this.owner.get("webServer")?.protocol === "https:";
+		const authority = this.sessionAuthority;
+		if (authority !== void 0) {
+			if (authority.isPublicApiRequest(request) || authority.verify(request)) return { peer: this.browserPeer };
+			return { rejection: 401 };
+		}
+		if (this.browserAuth.isAuthenticated(request, secure)) return { peer: this.browserPeer };
+		const id = this.browserAuth.authenticateApi(request, secure);
+		const record = id === void 0 ? void 0 : this.peers.get(id);
+		return record === void 0 ? { rejection: 401 } : { peer: record.peer };
+	}
+	/** Create one in-process Peer owned by the Context that read this service. */
+	createPeer(options) {
+		return new Peer(this.ctx, options);
+	}
+	/** Claim API socket ownership synchronously; callers release on termination or failed upgrade. */
+	admitConnection(request) {
+		const admission = this.admit(request);
+		if ("rejection" in admission) return admission;
+		const record = this.peers.get(admission.peer.id);
+		if (record === void 0) return {
+			...admission,
+			release: () => Promise.resolve()
+		};
+		if (record.ownsSocket) return { rejection: 409 };
+		record.ownsSocket = true;
+		let released;
+		return {
+			peer: record.peer,
+			release: () => {
+				if (released !== void 0) return released;
+				this.peers.delete(record.peer.id);
+				released = record.peer.dispose();
+				return released;
+			}
+		};
+	}
+	isTrusted(request) {
+		const carrier = this.owner.get("webServer");
+		return isTrustedApiRequest(request, this.trustedHosts, carrier?.host, carrier?.protocol ?? "http:");
+	}
+	publishPeer(interactions) {
+		const peer = new Peer(this.owner, {
+			principal: { kind: "owner" },
+			interactions
+		});
+		this.peers.set(peer.id, {
+			peer,
+			ownsSocket: false
+		});
+		return peer.id;
+	}
+	/**
+	* Authenticate and publish a credential before sending the connect redirect.
+	* @param request - launch-token request on /connect.
+	* @param response - response owned to completion.
+	*/
+	authorizeConnect(request, response) {
+		if (!this.isTrusted(request) || this.disposed) {
+			response.writeHead(this.disposed ? 401 : 403);
+			response.end(this.disposed ? "unauthorized" : "forbidden");
+			return;
+		}
+		this.browserAuth.authorizeConnect(request, response, this.owner.get("webServer")?.protocol === "https:", (interactions) => this.publishPeer(interactions));
 	}
 	/**
 	* Authenticate an index request: the launch-token exchange first, then the
 	* installed account-session authority, or the device cookie when no
-	* authority claims the seat.
+	* authority claims the seat. Native TLS listeners mint `Secure` device
+	* cookies; the installed gate owns its own cookie security.
 	*/
 	authorizeIndex(request, response) {
+		const secure = this.ctx.get("webServer")?.protocol === "https:";
 		const authority = this.sessionAuthority;
-		if (authority === void 0) return this.browserAuth.authorizeIndex(request, response);
-		if (this.browserAuth.exchangeToken(request, response)) return false;
+		if (authority === void 0) return this.browserAuth.authorizeIndex(request, response, secure);
+		if (this.browserAuth.exchangeToken(request, response, secure)) return false;
 		return authority.authorizeIndex(request, response);
 	}
 	/** Add this process's launch token, and an optional display name, to the clean application URL. */
@@ -740,15 +916,18 @@ var HostConnectionService = class extends Service {
 				const route = this.fetchRoutes.get(url.pathname);
 				return route?.methods.has(method) === true ? route.requestBody : "buffered";
 			},
-			fetch: (request) => {
+			fetch: (request, peer) => {
 				const pathname = new URL(request.url).pathname;
 				const route = this.fetchRoutes.get(pathname);
-				if (route?.methods.has(request.method) === true) return route.fetch(request);
+				if (route?.methods.has(request.method) === true) {
+					if (peer.principal.kind !== "owner") return Promise.resolve(new Response("forbidden", { status: 403 }));
+					return route.fetch(request);
+				}
 				if (request.method === "GET" && pathname === AUTH_STATUS_PATH) return Promise.resolve(this.deviceStatusAnswer(request));
 				const endpoint = endpointFromPath(channel, pathname);
 				const interceptor = this.interceptors.get(channel);
 				if (endpoint === void 0 || interceptor === void 0 || !interceptor.matches(endpoint)) return Promise.resolve(new Response("not found", { status: 404 }));
-				return interceptor.fetchHandler.fetch(request);
+				return interceptor.fetchHandler.fetch(request, peer);
 			}
 		};
 	}
@@ -759,7 +938,7 @@ var HostConnectionService = class extends Service {
 	* the menu without any identity channel.
 	*/
 	deviceStatusAnswer(request) {
-		const identity = this.browserAuth.identity(request);
+		const identity = this.browserAuth.identity(request, this.ctx.get("webServer")?.protocol === "https:");
 		return Response.json({
 			enabled: false,
 			needsSetup: false,
@@ -796,7 +975,7 @@ var HostConnectionService = class extends Service {
 	}
 	register(owner, channel, handler) {
 		assertChannel(channel);
-		const fetchHandler = rpcFetchHandler(channel, handler, this.operator);
+		const fetchHandler = rpcFetchHandler(channel, handler);
 		const route = {
 			kind: "prefix",
 			path: channel,
@@ -807,7 +986,7 @@ var HostConnectionService = class extends Service {
 					res.end(admission.rejection === 401 ? "unauthorized" : "forbidden");
 					return;
 				}
-				await bridge(req, res, fetchHandler);
+				await bridge(req, res, fetchHandler, admission.peer);
 			}
 		};
 		return owner.effect(() => owner.webServer.register(route), `client-connection: ${channel} rpc channel`);
@@ -816,7 +995,7 @@ var HostConnectionService = class extends Service {
 		if (channel !== "/api") throw new Error(`connection: invalid shared RPC channel ${JSON.stringify(channel)}`);
 		const interceptor = {
 			matches,
-			fetchHandler: rpcFetchHandler(channel, handler, this.operator)
+			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`);
@@ -827,10 +1006,10 @@ var HostConnectionService = class extends Service {
 		}, `client-connection: ${channel} rpc interceptor`);
 	}
 };
-function rpcFetchHandler(channel, handler, peer) {
+function rpcFetchHandler(channel, handler) {
 	return {
 		requestBodyMode: () => "buffered",
-		async fetch(request) {
+		async fetch(request, peer) {
 			const endpoint = endpointFromPath(channel, new URL(request.url).pathname);
 			if (request.method !== "POST" || endpoint === void 0) return new Response("not found", { status: 404 });
 			if (request.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase() !== "application/json") return new Response("content type must be application/json", { status: 415 });
@@ -970,14 +1149,21 @@ async function apply(ctx, config) {
 					res.end(admission.rejection === 401 ? "unauthorized" : "forbidden");
 					return;
 				}
-				await webCtx.waterfall("connection/request", req, res, () => bridge(req, res, fetchHandler, maxRequestBodyBytes));
+				await webCtx.waterfall("connection/request", req, res, () => bridge(req, res, fetchHandler, admission.peer, maxRequestBodyBytes));
 			}
 		};
 		webCtx.effect(() => webCtx.webServer.register(route), "client-connection: /api route");
+		webCtx.effect(() => webCtx.webServer.register({
+			kind: "exact",
+			path: CONNECT_PATH,
+			handler: (req, res) => {
+				connection.authorizeConnect(req, res);
+			}
+		}), "client-connection: /connect route");
 	});
 	ctx.inject(["attachments"], (attachmentCtx) => {
 		assertImageBodyCapacity(attachmentCtx, maxRequestBodyBytes);
 	});
 }
 //#endregion
-export { API_PATH, Config, HostConnectionService, OperatorPeer, RpcId, WEB_ENTRY_PATH, apply, clientRequestSchema, inject, name, rpcErrorSchema, rpcIdSchema, rpcMessageSchema, rpcResultSchema, serverResponseSchema, transportError };
+export { API_PATH, CONNECT_PATH, Config, HostConnectionService, Peer, RpcId, WEB_ENTRY_PATH, apply, clientRequestSchema, inject, name, rpcErrorSchema, rpcIdSchema, rpcMessageSchema, rpcResultSchema, serverResponseSchema, transportError };

package/lib/types/browser-auth.d.ts

@@ -1,4 +1,6 @@
 /** Browser-session authentication for the Host Connection carrier. */
+import type { PeerId } from '@qilin-agent/typert-protocol';
+import { type ConnectionInteractions } from './connect-protocol.ts';
 import type { CredentialProvider } from '@qilin-agent/credentials';
 import type { ConnectionIndexRequest, ConnectionIndexResponse, ConnectionTrustRequest } from './rpc.ts';
 /**
@@ -34,32 +36,58 @@ export declare class BrowserAuth {
      * 401 response.
      * @param req - incoming entry or configured-index request.
      * @param res - response owned when this method returns false.
+     * @param secure - whether the listener receiving this request serves TLS; the
+     * minted cookie carries `Secure` when it does. Only that listener's own
+     * protocol decides, never a `publicUrl` announcement or a forwarded header:
+     * those describe a hop this process does not terminate.
      * @returns true only when the caller may serve index.html.
      */
-    authorizeIndex(req: ConnectionIndexRequest, res: ConnectionIndexResponse): boolean;
+    authorizeIndex(req: ConnectionIndexRequest, res: ConnectionIndexResponse, secure?: boolean): boolean;
     /**
      * Mint the device cookie for one valid launch token and redirect to the clean
      * entry path: the handoff that turns the printed URL into a browser session.
      * @param req - incoming request; its only token input is the query.
      * @param res - response owned when the exchange applies.
+     * @param secure - whether the listener receiving this request serves TLS; the
+     * minted cookie carries `Secure` and an `https:`-scoped audience when it does.
      * @returns true when a valid token was exchanged and the redirect written.
      */
-    exchangeToken(req: ConnectionIndexRequest, res: ConnectionIndexResponse): boolean;
+    exchangeToken(req: ConnectionIndexRequest, res: ConnectionIndexResponse, secure?: boolean): boolean;
+    /**
+     * Exchange the launch token for an independent API operator; omitted interactions default to none.
+     * @param req - trusted GET request on /connect with at most one interactions declaration.
+     * @param res - response owned to completion, redirecting to the API mux on success.
+     * @param secure - whether the receiving listener serves TLS.
+     * @param publish - synchronously create the operator before exposing its signed credential.
+     */
+    authorizeConnect(req: ConnectionIndexRequest, res: ConnectionIndexResponse, secure: boolean, publish: (interactions: ConnectionInteractions) => PeerId): void;
     /**
      * Verify the authority-bound browser cookie on a Host request.
      * @param request - request headers carrying Host and Cookie.
+     * @param secure - whether the receiving listener serves TLS; only a cookie
+     * minted for that same protocol's audience authenticates.
      * @returns true only for an unexpired cookie signed by this activation's loaded secret.
      */
-    isAuthenticated(request: ConnectionTrustRequest): boolean;
+    isAuthenticated(request: ConnectionTrustRequest, secure?: boolean): boolean;
+    /**
+     * Verify an API credential without creating or reviving its operator.
+     * @param request - request headers carrying Host and Cookie.
+     * @param secure - whether the receiving listener uses TLS.
+     * @returns the signed operator id, or undefined for invalid, expired, or browser cookies.
+     */
+    authenticateApi(request: ConnectionTrustRequest, secure?: boolean): PeerId | undefined;
+    private authenticate;
     /**
      * Read the device session behind a Host request: its authentication fact and
      * the operator display name the launching host attached, if any. This is the
      * identity channel for deployments without the account gate, and the gate's
      * own status route stays authoritative wherever that is mounted.
      * @param request - request headers carrying Host and Cookie.
+     * @param secure - whether the receiving listener serves TLS; the cookie
+     * audience is scoped to that protocol.
      * @returns the session fact and display name of the request's device session.
      */
-    identity(request: ConnectionTrustRequest): {
+    identity(request: ConnectionTrustRequest, secure?: boolean): {
         readonly authenticated: boolean;
         readonly accountName: string | null;
     };

package/lib/types/client/index.d.ts

@@ -3,6 +3,10 @@ import type { Context } from '@qilin-agent/kylin';
 import { type ConnectionRecoveryConfig, type ConnectionGeneration, type ConnectionGenerationSource, type ConnectionSinks, type ConnectionState } from './connection.ts';
 import { type RpcFetch, type RpcStreamOpen } from './rpc.ts';
 import type { ClientConnectionRpc } from '../rpc.ts';
+import type { ConnectionInteractions } from '../connect-protocol.ts';
+import { type ConnectionWebSocket, type ConnectionWebSocketFactory } from './socket.ts';
+export type { ConnectionInteractions } from '../connect-protocol.ts';
+export type { ConnectionWebSocket, ConnectionWebSocketFactory } from './socket.ts';
 declare module '@qilin-agent/kylin' {
     interface Events {
         /**
@@ -66,7 +70,9 @@ export interface ClientTransportHooks {
      * transport can set this; served pages never carry the global at all.
      */
     ownsHost?: boolean;
-    /** HTTP origin of a shell-owned Host when its WebSocket uses a different page origin. */
+    /** Authenticated WebSocket factory; omission uses the browser API and its cookie jar. */
+    createWebSocket?: ConnectionWebSocketFactory;
+    /** Host base URL for desktop or Node sockets; omission uses the document base. */
     streamBaseUrl?: string;
 }
 /** Browser location fields used to classify loopback authority. */
@@ -75,6 +81,8 @@ export interface ConnectionLocation {
 }
 /** Instance-local inputs for installing a Connection service. */
 export interface ConnectionInstallOptions {
+    /** Forwarded-event participation; omission selects answer for a page and none otherwise. */
+    readonly interactions?: ConnectionInteractions;
     /** Explicit physical carrier; omit for the browser HTTP + WebSocket carrier. */
     readonly transport?: ClientTransportHooks;
     /** Reconnect timing overrides; omitted fields use controller defaults. */
@@ -87,6 +95,8 @@ export interface ConnectionInstallOptions {
  * and reset callbacks; Connection stays independent of downstream domain state.
  */
 export interface ConnectionHandle {
+    /** Forwarded-event participation selected at installation. */
+    readonly interactions: ConnectionInteractions;
     /**
      * Whether the privileged surface is reachable: the page authority is
      * loopback, the transport declares the page owns the Host
@@ -99,6 +109,12 @@ export interface ConnectionHandle {
     readonly state: ConnectionStateSource;
     /** Generic logical RPC channels over the same Connection transport. */
     readonly rpc: ClientConnectionRpc;
+    /**
+     * Create a socket on the selected carrier; the channel owns framing and closing.
+     * @param path - absolute logical channel path, resolved beneath the Host mount.
+     * @returns a newly connecting socket using the installed authentication factory.
+     */
+    openWebSocket(path: string): ConnectionWebSocket;
     /** Reset retry progression and replace the current attempt immediately. */
     reconnect(): void;
     /**

package/lib/types/client/socket.d.ts

@@ -0,0 +1,50 @@
+/** Physical socket selection for browser, desktop, and authenticated Node connections. */
+/** Socket events consumed by the Gateway on browser and Node carriers. */
+export interface ConnectionWebSocketEventMap {
+    readonly open: object;
+    readonly error: object;
+    readonly close: object;
+    readonly message: {
+        readonly data: unknown;
+    };
+}
+/** Text WebSocket operations shared by the browser API and Node carriers. */
+export interface ConnectionWebSocket {
+    /** Standard WebSocket state, from CONNECTING (0) through CLOSED (3). */
+    readonly readyState: number;
+    /** @param data - complete text frame to send. */
+    send(data: string): void;
+    /**
+     * @param code - protocol close code.
+     * @param reason - peer-facing close explanation.
+     */
+    close(code?: number, reason?: string): void;
+    /**
+     * @param event - physical socket event.
+     * @param listener - callback for that event.
+     * @param options - whether the callback is removed after its first delivery.
+     */
+    addEventListener<Event extends keyof ConnectionWebSocketEventMap>(event: Event, listener: (event: ConnectionWebSocketEventMap[Event]) => void, options?: {
+        readonly once?: boolean;
+    }): void;
+    /**
+     * @param event - physical socket event.
+     * @param listener - previously registered callback.
+     */
+    removeEventListener<Event extends keyof ConnectionWebSocketEventMap>(event: Event, listener: (event: ConnectionWebSocketEventMap[Event]) => void): void;
+}
+/**
+ * Create an authenticated socket; its consumer owns framing and closing.
+ * @param url - absolute WebSocket URL beneath the selected Host mount.
+ * @returns a newly connecting socket, before it emits open or failure.
+ */
+export type ConnectionWebSocketFactory = (url: string) => ConnectionWebSocket;
+/**
+ * Resolve a logical channel against the explicit Host or the page's document base.
+ * @param path - absolute logical channel path.
+ * @param factory - authenticated socket factory; omission uses the browser API.
+ * @param baseUrl - Host base URL, required outside a document.
+ * @returns a socket owned by the calling channel.
+ */
+export declare function openConnectionWebSocket(path: string, factory?: ConnectionWebSocketFactory, baseUrl?: string): ConnectionWebSocket;
+//# sourceMappingURL=socket.d.ts.map

package/lib/types/connect-protocol.d.ts

@@ -0,0 +1,6 @@
+/** API connection inputs shared by the Host and its clients. */
+/** Whether a Peer participates in forwarded human interactions. */
+export type ConnectionInteractions = 'answer' | 'none';
+/** Launch-token exchange route for API clients. */
+export declare const CONNECT_PATH = "/connect";
+//# sourceMappingURL=connect-protocol.d.ts.map

package/lib/types/http-bridge.d.ts

@@ -3,6 +3,7 @@
  * web carrier; the fetch-shaped handler itself is transport-agnostic).
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { PeerScope } from '@qilin-agent/typert-protocol';
 import type { ConnectionFetchHandler } from './rpc.ts';
 /** Default carrier cap for all HTTP RPC bodies: sized for the default
  * aggregate image limit (200 MiB) after base64 expansion plus envelope
@@ -15,7 +16,8 @@ export declare const DEFAULT_MAX_REQUEST_BODY_BYTES: number;
  * @param req - incoming node:http request.
  * @param res - node:http response the bridge writes and owns to completion.
  * @param apiHandler - fetch-shaped API carrier the request is dispatched to.
+ * @param peer - Peer the carrier admitted the request as.
  * @param maxRequestBodyBytes - maximum bytes buffered for a buffered route.
  */
-export declare function bridge(req: IncomingMessage, res: ServerResponse, apiHandler: ConnectionFetchHandler, maxRequestBodyBytes?: number): Promise<void>;
+export declare function bridge(req: IncomingMessage, res: ServerResponse, apiHandler: ConnectionFetchHandler, peer: PeerScope, maxRequestBodyBytes?: number): Promise<void>;
 //# sourceMappingURL=http-bridge.d.ts.map

package/lib/types/index.d.ts

@@ -3,10 +3,12 @@ import type { Context } from '@qilin-agent/kylin';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import z from '@qilin-agent/schemastery';
 import { type ConnectionRecoveryConfig } from './recovery-config.ts';
-export type { PeerAdmission, ConnectionFetchMethod, ConnectionFetchHandler, ConnectionFetchRoute, ConnectionIndexRequest, ConnectionIndexResponse, ConnectionSessionAuthority, HostConnectionSession, ConnectionRpcEndpointMatcher, ConnectionRpcFailure, ConnectionRpcHandler, ConnectionRequestRejection, ConnectionRpcResult, ConnectionRequestBodyMode, ConnectionTrustRequest, ClientRequest, HostConnectionHandle, HostConnectionFetch, HostConnectionRpc, RpcMessage, ServerResponse, } from './rpc.ts';
-export type { PeerId, PeerScope, RemoteInvocation } from '@qilin-agent/typert-protocol';
+export type { PeerAdmission, ConnectionAdmission, ConnectionFetchMethod, ConnectionFetchHandler, ConnectionFetchRoute, ConnectionIndexRequest, ConnectionIndexResponse, ConnectionSessionAuthority, HostConnectionSession, ConnectionRpcEndpointMatcher, ConnectionRpcFailure, ConnectionRpcHandler, ConnectionRequestRejection, ConnectionRpcResult, ConnectionRequestBodyMode, ConnectionTrustRequest, ClientRequest, HostConnectionHandle, HostConnectionFetch, HostConnectionRpc, RpcMessage, ServerResponse, } from './rpc.ts';
+export type { PeerId, PeerScope, Principal, RemoteInvocation } from '@qilin-agent/typert-protocol';
 export { RpcId, transportError } from './rpc.ts';
-export { OperatorPeer } from './operator-peer.ts';
+export { Peer } from './peer.ts';
+export type { PeerOptions } from './peer.ts';
+export { CONNECT_PATH, type ConnectionInteractions } from './connect-protocol.ts';
 export { clientRequestSchema, rpcErrorSchema, rpcIdSchema, rpcMessageSchema, rpcResultSchema, serverResponseSchema, } from './rpc-schema.ts';
 export { HostConnectionService } from './rpc-host.ts';
 export { API_PATH } from './api-path.ts';
@@ -41,7 +43,7 @@ export interface ConnectionConfig {
      * bind. An entry that is not a bare, canonical authority fails plugin load.
      */
     trustedHosts?: string[];
-    /** Absolute browser-session lifetime in days. Default: 30. */
+    /** Absolute browser and API cookie lifetime in days. Default: 30. */
     cookieMaxAgeDays?: number;
     /** Maximum buffered JSON body for every `/api` request. Default: 300 MiB. */
     maxRequestBodyBytes?: number;

package/lib/types/peer.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The Peer: one party admitted to this Host. Its creator fixes the principal
+ * it speaks for and owns its lifetime; Gateway hands it to each Remote call as
+ * `invocation.peer`.
+ * @module @qilin-agent/client-connection/src/peer
+ */
+import type { Context } from '@qilin-agent/kylin';
+import type { PeerId, PeerScope, Principal } from '@qilin-agent/typert-protocol';
+/** Construction options for one {@link Peer}. */
+export interface PeerOptions {
+    /** Caller identity every call through this Peer speaks for. */
+    readonly principal: Principal;
+    /** Omission permits an event stream; non-owner Peers still cannot answer waterfalls. */
+    readonly interactions?: 'answer' | 'none';
+}
+/**
+ * One Peer's scope. The instance is its own scope key, so `scopeOf(peer.ctx)`
+ * returns it and events dispatched with `scopeTarget(subject, peer)` reach
+ * listeners registered through `peer.ctx` and nobody else.
+ */
+export declare class Peer implements PeerScope {
+    readonly id: PeerId;
+    readonly ctx: Context;
+    readonly principal: Principal;
+    readonly interactions: 'answer' | 'none';
+    readonly signal: AbortSignal;
+    private readonly scope;
+    /**
+     * @param owner - Context the scope fiber hangs under; disposing it disposes the Peer.
+     * @param options - the principal fixed for this Peer's lifetime.
+     */
+    constructor(owner: Context, options: PeerOptions);
+    /** Tear down every connection-lifetime registration; racing calls share one completion. */
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=peer.d.ts.map

package/lib/types/rpc-host.d.ts

@@ -1,8 +1,9 @@
 /** Host registry and HTTP adapter for generic Connection RPC channels. */
 import { Context, Service } from '@qilin-agent/kylin';
-import type { PeerScope } from '@qilin-agent/typert-protocol';
+import type { PeerScope, Principal } from '@qilin-agent/typert-protocol';
+import type { ConnectionInteractions } from './connect-protocol.ts';
 import type { BrowserAuth } from './browser-auth.ts';
-import type { PeerAdmission, ConnectionIndexRequest, ConnectionIndexResponse, ConnectionFetchHandler, HostConnectionFetch, HostConnectionSession, ConnectionRequestRejection, ConnectionTrustRequest, HostConnectionHandle, HostConnectionRpc } from './rpc.ts';
+import type { PeerAdmission, ConnectionAdmission, ConnectionIndexRequest, ConnectionIndexResponse, ConnectionFetchHandler, HostConnectionFetch, HostConnectionSession, ConnectionRequestRejection, ConnectionTrustRequest, HostConnectionHandle, HostConnectionRpc } from './rpc.ts';
 declare module '@qilin-agent/kylin' {
     interface Context {
         /** Host Connection transport and RPC registrations. */
@@ -13,8 +14,11 @@ declare module '@qilin-agent/kylin' {
 export declare class HostConnectionService extends Service implements HostConnectionHandle {
     private readonly trustedHosts;
     private readonly browserAuth;
-    /** The operator Peer every admitted request speaks for. */
-    readonly operator: PeerScope;
+    /** The Peer every authenticated browser connection shares. */
+    readonly browserPeer: PeerScope;
+    private readonly peers;
+    private readonly owner;
+    private disposed;
     private readonly interceptors;
     private readonly fetchRoutes;
     private sessionAuthority;
@@ -39,12 +43,28 @@ export declare class HostConnectionService extends Service implements HostConnec
      * cookie minted by the launch-token exchange.
      */
     requestRejection(request: ConnectionTrustRequest): ConnectionRequestRejection;
-    /** A request that passes the fence and authentication speaks for the operator. */
+    /** Browser requests share an owner Peer; the account-session authority admits its own bearers. */
     admit(request: ConnectionTrustRequest): PeerAdmission;
+    /** Create one in-process Peer owned by the Context that read this service. */
+    createPeer(options: {
+        readonly principal: Principal;
+        readonly interactions?: ConnectionInteractions;
+    }): PeerScope;
+    /** Claim API socket ownership synchronously; callers release on termination or failed upgrade. */
+    admitConnection(request: ConnectionTrustRequest): ConnectionAdmission;
+    private isTrusted;
+    private publishPeer;
+    /**
+     * Authenticate and publish a credential before sending the connect redirect.
+     * @param request - launch-token request on /connect.
+     * @param response - response owned to completion.
+     */
+    authorizeConnect(request: ConnectionIndexRequest, response: ConnectionIndexResponse): void;
     /**
      * Authenticate an index request: the launch-token exchange first, then the
      * installed account-session authority, or the device cookie when no
-     * authority claims the seat.
+     * authority claims the seat. Native TLS listeners mint `Secure` device
+     * cookies; the installed gate owns its own cookie security.
      */
     authorizeIndex(request: ConnectionIndexRequest, response: ConnectionIndexResponse): boolean;
     /** Add this process's launch token, and an optional display name, to the clean application URL. */

package/lib/types/rpc.d.ts

@@ -1,6 +1,6 @@
 /** Generic unary RPC contracts shared by the Host and Client Connection halves. */
 import type { Branded } from '@qilin-agent/brand';
-import type { PeerScope } from '@qilin-agent/typert-protocol';
+import type { PeerScope, Principal } from '@qilin-agent/typert-protocol';
 /** Correlation id minted by a caller and echoed by the Connection response. */
 export type RpcId = Branded<'rpc-id'>;
 /**
@@ -74,15 +74,23 @@ export interface ConnectionIndexResponse {
     writeHead(status: number, headers?: Readonly<Record<string, string>>): unknown;
     end(body?: string): unknown;
 }
-/** Outcome of admitting one request: the operator Peer it speaks for, or the status refusing it. */
+/** Outcome of admitting one request: the Peer it speaks for, or the status refusing it. */
 export type PeerAdmission = {
     readonly peer: PeerScope;
 } | {
     readonly rejection: 401 | 403;
 };
+/** Socket admission claims API ownership until its carrier calls release, including failed upgrades. */
+export type ConnectionAdmission = {
+    readonly peer: PeerScope;
+    /** Remove and dispose an API Peer; browser releases leave the shared browser Peer intact. */
+    readonly release: () => Promise<void>;
+} | {
+    readonly rejection: 401 | 403 | 409;
+};
 /**
  * Handler invoked after Connection has decoded the transport envelope.
- * `peer` is the Peer the request was admitted as: the operator.
+ * `peer` is the Peer the carrier admitted or the in-process caller supplied.
  */
 export type ConnectionRpcHandler = (endpoint: string, payload: unknown, signal: AbortSignal, peer: PeerScope) => Promise<ConnectionRpcResult<unknown>>;
 /** Synchronous ownership test for one endpoint on a shared RPC channel. */
@@ -99,7 +107,11 @@ export interface ConnectionFetchRoute {
     readonly methods: readonly ConnectionFetchMethod[];
     /** Buffered requests obey the configured JSON cap; streaming requests arrive with backpressure and no aggregate cap. */
     readonly requestBody: ConnectionRequestBodyMode;
-    /** Handle one request after the physical carrier has applied its trust and authentication policy. */
+    /**
+     * Handle one request after the physical carrier has applied its trust and
+     * authentication policy. Only owner Peers reach an exact route; the shared
+     * handler answers 403 for every other principal.
+     */
     readonly fetch: (request: Request) => Promise<Response>;
 }
 /** Host registry for exact Fetch routes that cannot use JSON Remote invocation. */
@@ -174,8 +186,8 @@ export interface HostConnectionHandle {
     readonly rpc: HostConnectionRpc;
     /** Exact Fetch routes for streaming or browser-native responses. */
     readonly fetch: HostConnectionFetch;
-    /** The operator Peer every admitted request speaks for; its scope lives as long as Connection. */
-    readonly operator: PeerScope;
+    /** The owner Peer every authenticated browser connection shares. */
+    readonly browserPeer: PeerScope;
     /** Account-session gate seat; unclaimed keeps device-token authentication. */
     readonly session: HostConnectionSession;
     /**
@@ -197,14 +209,32 @@ export interface HostConnectionHandle {
      */
     requestRejection(request: ConnectionTrustRequest): ConnectionRequestRejection;
     /**
-     * Admit one request: it passes {@link requestRejection} and speaks for the
-     * operator, or it is refused with that status.
+     * Admit an HTTP request against its signed browser or API credential and live Peer.
      * @param request - request headers from the HTTP or upgrade request.
-     * @returns the operator Peer, or the rejection status.
+     * @returns the credential's Peer, or the rejection status.
      */
     admit(request: ConnectionTrustRequest): PeerAdmission;
+    /**
+     * Create an independent in-process Peer, disposed with the Context that read `ctx.connection`.
+     * @param options - fixed principal and optional interaction participation (default `answer`).
+     * @returns a new Peer distinct from every other Peer.
+     */
+    createPeer(options: {
+        readonly principal: Principal;
+        readonly interactions?: 'answer' | 'none';
+    }): PeerScope;
+    /**
+     * Claim a physical socket for an API Peer; browser sockets share their owner Peer.
+     * @param request - authenticated upgrade request headers.
+     * @returns the Peer and idempotent release, or 409 for duplicate API ownership.
+     * The carrier releases on socket termination or failed upgrade; release removes
+     * API admission synchronously without cancelling independent HTTP calls.
+     */
+    admitConnection(request: ConnectionTrustRequest): ConnectionAdmission;
     /**
      * Authenticate one frontend index request, owning a token redirect or 401.
+     * The cookie this mints is `Secure` when the mounted Web carrier serves TLS,
+     * which only that listener's protocol decides.
      * @param request - root or configured-index HTTP request.
      * @param response - response owned when the result is false.
      * @returns true only when the frontend may serve index.html.
@@ -232,9 +262,10 @@ export interface ConnectionFetchHandler {
     /**
      * Dispatch one already-authenticated request.
      * @param request - Fetch request below the shared channel.
-     * @returns the registered response or a 404 response.
+     * @param peer - Peer to dispatch as; required, never defaulted.
+     * @returns the registered response, a 403 response for an exact route and a non-owner Peer, or a 404 response.
      */
-    fetch(request: Request): Promise<Response>;
+    fetch(request: Request, peer: PeerScope): Promise<Response>;
 }
 /** Client caller for logical RPC channels carried by the current transport. */
 export interface ClientConnectionRpc {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@qilin-agent/client-connection",
   "description": "Authenticated RPC transport and generation lifecycle",
-  "version": "3.1.5",
+  "version": "3.1.7",
   "publishConfig": {
     "access": "public"
   },
@@ -38,8 +38,8 @@
   "license": "MIT",
   "dependencies": {
     "zod": "^4.4.3",
-    "@qilin-agent/credentials": "3.1.5",
-    "@qilin-agent/schemastery": "~3.18.3"
+    "@qilin-agent/credentials": "3.1.7",
+    "@qilin-agent/schemastery": "~3.18.5"
   },
   "files": [
     "lib/index.js",
@@ -47,22 +47,22 @@
     "lib/types/**/*.d.ts"
   ],
   "peerDependencies": {
-    "@qilin-agent/kylin": "~4.0.3",
-    "@qilin-agent/scope": "3.1.5"
+    "@qilin-agent/kylin": "~4.0.5",
+    "@qilin-agent/scope": "3.1.7"
   },
   "devDependencies": {
-    "@qilin-agent/kylin": "~4.0.3",
-    "@qilin-agent/brand": "3.1.5",
-    "@qilin-agent/attachment": "3.1.5",
-    "@qilin-agent/host-webserver": "3.1.5",
-    "@qilin-agent/llm": "3.1.5",
-    "@qilin-agent/session": "3.1.5",
-    "@qilin-agent/typert-protocol": "3.1.5",
-    "@qilin-agent/scope": "3.1.5",
-    "@qilin-agent/tool-todo": "3.1.5",
-    "@qilin-agent/commands": "3.1.5",
-    "@qilin-agent/util-values": "3.1.5",
-    "@qilin-agent/settings": "3.1.5",
-    "@qilin-agent/host-directory-picker": "3.1.5"
+    "@qilin-agent/kylin": "~4.0.5",
+    "@qilin-agent/brand": "3.1.7",
+    "@qilin-agent/attachment": "3.1.7",
+    "@qilin-agent/llm": "3.1.7",
+    "@qilin-agent/scope": "3.1.7",
+    "@qilin-agent/session": "3.1.7",
+    "@qilin-agent/typert-protocol": "3.1.7",
+    "@qilin-agent/host-webserver": "3.1.7",
+    "@qilin-agent/tool-todo": "3.1.7",
+    "@qilin-agent/commands": "3.1.7",
+    "@qilin-agent/settings": "3.1.7",
+    "@qilin-agent/host-directory-picker": "3.1.7",
+    "@qilin-agent/util-values": "3.1.7"
   }
 }

package/lib/types/operator-peer.d.ts

@@ -1,23 +0,0 @@
-/**
- * The operator Peer: the one party this Host answers to. Connection owns it
- * for its own lifetime, admits every request as it, and hands it to each
- * Remote call as `invocation.peer`.
- * @module @qilin-agent/client-connection/src/operator-peer
- */
-import type { Context } from '@qilin-agent/kylin';
-import type { PeerId, PeerScope } from '@qilin-agent/typert-protocol';
-/**
- * The operator's scope. The instance is its own scope key, so `scopeOf(peer.ctx)`
- * returns it and events dispatched with `scopeTarget(subject, peer)` reach
- * listeners registered through `peer.ctx` and nobody else.
- */
-export declare class OperatorPeer implements PeerScope {
-    readonly id: PeerId;
-    readonly ctx: Context;
-    private readonly scope;
-    /** @param owner - Connection plugin context the scope fiber hangs under. */
-    constructor(owner: Context);
-    /** Tear down every connection-lifetime registration; racing calls share one completion. */
-    dispose(): Promise<void>;
-}
-//# sourceMappingURL=operator-peer.d.ts.map