@deepseek-ai/dsh-client-connection 0.2.1-alpha.2 → 0.2.1-alpha.3

package/lib/index.js

@@ -13,6 +13,11 @@ import { createScope } from "@deepseek-ai/dsh-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 ? {
@@ -347,12 +353,12 @@ function signature(secret, body) {
 }
 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);
@@ -365,8 +371,22 @@ 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;
-	return decoded;
+	if (!isRecord(decoded) || decoded.version !== COOKIE_PAYLOAD_VERSION && decoded.version !== 2 || version !== `v${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) return {
+		version: COOKIE_PAYLOAD_VERSION,
+		...payload
+	};
+	if (typeof decoded.id !== "string" || decoded.id.length === 0) return void 0;
+	return {
+		version: 2,
+		...payload,
+		id: decoded.id
+	};
 }
 async function initializeSecret(credentials) {
 	const generated = {
@@ -476,21 +496,77 @@ var BrowserAuth = class BrowserAuth {
 		return false;
 	}
 	/**
+	* 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 = new URL(req.url ?? "/", "http://dsh.invalid");
+		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 uses TLS, including its default port.
 	* @returns true only for an unexpired cookie signed by this activation's loaded secret.
 	*/
 	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 false;
+		if (authority === void 0 || rawCookie === void 0) return void 0;
 		const value = cookieValue(rawCookie, cookieName(authority));
-		if (value === void 0) return false;
+		if (value === void 0) return void 0;
 		const payload = decodeCookie(value, this.secret);
-		if (payload === void 0 || payload.authority !== authority) return false;
+		if (payload === void 0 || payload.authority !== authority) return void 0;
 		const now = Date.now();
-		return payload.issuedAt <= now && payload.expiresAt > now && payload.expiresAt > payload.issuedAt && payload.expiresAt - payload.issuedAt <= this.maxAgeMilliseconds;
+		if (payload.issuedAt > now || payload.expiresAt <= now || payload.expiresAt <= payload.issuedAt || payload.expiresAt - payload.issuedAt > this.maxAgeMilliseconds) return void 0;
+		return payload;
 	}
 	writeUnauthorized(req, res) {
 		res.writeHead(401, {
@@ -567,26 +643,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 @deepseek-ai/dsh-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 @deepseek-ai/dsh-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() {
@@ -603,8 +692,11 @@ const ENDPOINT_SEGMENT_PATTERN = /^[A-Za-z0-9_$.-]+$/;
 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();
 	allowsRemoteAuthorities;
@@ -618,8 +710,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");
 		this.allowsRemoteAuthorities = trustedHosts.some(isRemoteAuthority);
 	}
 	/** Generic channel registry scoped to the Context reading this service. */
@@ -635,16 +733,74 @@ var HostConnectionService = class extends Service {
 		const owner = this.ctx;
 		return { register: (route) => this.registerFetchRoute(owner, route) };
 	}
-	/** Apply the Host/Origin fence, then browser authentication. */
+	/** Apply the Host/Origin fence and require an authenticated live Peer. */
 	requestRejection(request) {
-		const carrier = this.ctx.get("webServer");
-		if (!isTrustedApiRequest(request, this.trustedHosts, carrier?.host, carrier?.protocol ?? "http:")) return 403;
-		return this.browserAuth.isAuthenticated(request, carrier?.protocol === "https:") ? 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; API HTTP does not depend on an attached socket. */
 	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:";
+		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; native TLS listeners mint Secure cookies.
@@ -667,14 +823,17 @@ 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);
+				}
 				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);
 			}
 		};
 	}
@@ -695,7 +854,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,
@@ -706,7 +865,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`);
@@ -715,7 +874,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`);
@@ -726,10 +885,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 });
@@ -893,14 +1052,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, apply, clientRequestSchema, inject, name, rpcErrorSchema, rpcIdSchema, rpcMessageSchema, rpcResultSchema, serverResponseSchema, transportError };
+export { API_PATH, CONNECT_PATH, Config, HostConnectionService, Peer, RpcId, 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 '@deepseek-ai/dsh-typert-protocol';
+import { type ConnectionInteractions } from './connect-protocol.ts';
 import type { CredentialProvider } from '@deepseek-ai/dsh-credentials';
 import type { ConnectionIndexRequest, ConnectionIndexResponse, ConnectionTrustRequest } from './rpc.ts';
 /**
@@ -40,6 +42,14 @@ export declare class BrowserAuth {
      * @returns true only when the caller may serve index.html.
      */
     authorizeIndex(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.
@@ -47,6 +57,14 @@ export declare class BrowserAuth {
      * @returns true only for an unexpired cookie signed by this activation's loaded secret.
      */
     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;
     private writeUnauthorized;
 }
 //# sourceMappingURL=browser-auth.d.ts.map

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

@@ -3,6 +3,10 @@ import type { Context } from '@deepseek-ai/cordis';
 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 '@deepseek-ai/cordis' {
     interface Events {
         /**
@@ -60,13 +64,15 @@ export interface ClientTransportHooks {
     /**
      * The transport owner declares the page owns the Host outright: the Host
      * runs inside a worker this page spawned, so no other party can reach it and
-     * the loopback stand-in for "the operator's own machine" is vacuous.
+     * the loopback stand-in for "the owner's own machine" is vacuous.
      * `ctx.connection.isLoopback` then reports the privileged surface reachable
      * regardless of the page authority. Only a shell that assembles its own
      * 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;
     /**
@@ -125,7 +141,7 @@ export interface ConnectionLoop {
 /**
  * Install one Context-owned Connection service from explicit composition inputs.
  * @param ctx - client Cordis context.
- * @param options - physical carrier, reconnect timing, and page location.
+ * @param options - interaction participation, physical carrier, reconnect timing, and page location.
  */
 export declare function installConnection(ctx: Context, options?: ConnectionInstallOptions): 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 } from 'node:http';
+import type { PeerScope } from '@deepseek-ai/dsh-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
@@ -25,8 +26,9 @@ interface BridgeServerResponse {
  * @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: BridgeServerResponse, apiHandler: ConnectionFetchHandler, maxRequestBodyBytes?: number): Promise<void>;
+export declare function bridge(req: IncomingMessage, res: BridgeServerResponse, apiHandler: ConnectionFetchHandler, peer: PeerScope, maxRequestBodyBytes?: number): Promise<void>;
 export {};
 //# sourceMappingURL=http-bridge.d.ts.map

package/lib/types/index.d.ts

@@ -3,10 +3,12 @@ import type { Context } from '@deepseek-ai/cordis';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import z from '@deepseek-ai/schemastery';
 import { type ConnectionRecoveryConfig } from './recovery-config.ts';
-export type { PeerAdmission, ConnectionFetchMethod, ConnectionFetchHandler, ConnectionFetchRoute, ConnectionIndexRequest, ConnectionIndexResponse, ConnectionRpcEndpointMatcher, ConnectionRpcAttachment, ConnectionRpcFailure, ConnectionRpcHandler, ConnectionRpcHandlerResult, ConnectionRequestRejection, ConnectionRpcResult, ConnectionRequestBodyMode, ConnectionTrustRequest, ClientRequest, HostConnectionHandle, HostConnectionFetch, HostConnectionRpc, RpcMessage, ServerResponse, } from './rpc.ts';
-export type { PeerId, PeerScope, RemoteInvocation } from '@deepseek-ai/dsh-typert-protocol';
+export type { PeerAdmission, ConnectionAdmission, ConnectionFetchMethod, ConnectionFetchHandler, ConnectionFetchRoute, ConnectionIndexRequest, ConnectionIndexResponse, ConnectionRpcEndpointMatcher, ConnectionRpcAttachment, ConnectionRpcFailure, ConnectionRpcHandler, ConnectionRpcHandlerResult, ConnectionRequestRejection, ConnectionRpcResult, ConnectionRequestBodyMode, ConnectionTrustRequest, ClientRequest, HostConnectionHandle, HostConnectionFetch, HostConnectionRpc, RpcMessage, ServerResponse, } from './rpc.ts';
+export type { PeerId, PeerScope, Principal, RemoteInvocation } from '@deepseek-ai/dsh-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';
@@ -38,7 +40,7 @@ export interface ConnectionConfig {
      * an entry here. A non-canonical or non-bare 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 @deepseek-ai/dsh-client-connection/src/peer
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { PeerId, PeerScope, Principal } from '@deepseek-ai/dsh-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