TwickaS/delorun--packages-client-connection ↗★ 1
@deepseek-ai/dsh-client-connection
Authenticated RPC transport and generation lifecycle
同名包的其他仓库
- deepseek-ai/deepseek-harness--packages-client-connection
- whitelonng/dshcode--packages-client-connection
- fufankeji/deepseek-harness-studio--packages-client-connection
- op7418/pilot-harness--packages-client-connection
- See-Sol-Lab/DeepSeekGUI--packages-client-connection
- SuperJJ007/papermachine--packages-client-connection
安装
此插件尚未提供可验证的 bundle,或兼容性检查未通过。请先阅读仓库说明。 阅读完整 README ↗
说明文档
阅读完整 README ↗description: "Browser-host wire layer for the web GUI: Remote RPC, event-stream delivery with reconnect, exact Fetch routes, the /api HTTP bridge, and the browser-trust fence." kind: "package-reference"
@deepseek-ai/dsh-client-connection
English | 中文
Summary
The package carries browser-to-Host Remote calls, exact Fetch responses, and connection generations. The Client plugin mounts ctx.connection with current-page loopback state, generic RPC, the active generation and its Host facts, observable recovery state, an immediate reconnect command, and the registration point for one generation source. A generation becomes visible when its source reports ready; source completion, failure, withdrawal, or an explicit stop clears it before ConnectionController applies its retry policy.
Table of Contents
- Use this package
- Browser authentication and request trust
- Admission providers and reach listeners
- Request extras
- Connection generation
- Model Experience
- Known Limitations and Deferred Work
- Dev Note
Use this package
The ./client import selects the standalone lib/client.node.js ESM bundle in Node and the lib/client.browser.js loader factory in browsers. The Web Host still serves the browser export at the logical /plugins/.../client.js URL. Import the Client entry for a non-page Cordis tree; the separate package root is the Host entry.
A static desktop page can provide __DSH_TRANSPORT__.streamBaseUrl for the HTTP origin of its owned Host. The Gateway uses that origin for its WebSocket while HTTP transport remains independently selected. The desktop carrier owns authentication; setting the origin alone grants no access.
Unary RPC requests use JSON. A Host handler may return byte attachments that it has already separated from the JSON-compatible result value, with each attachment naming its result-relative path. Connection writes these values as multipart parts. The JSON metadata part contains the RPC response envelope with null placeholders and an attachment table recording each path, codec, and part identifier. Paths use string keys and numeric array indices; no business field name is reserved. The Client validates the envelope, rpcId, attachment table, and parts, then restores each byte value as an ArrayBuffer-backed view. Results without attachments, including base64 strings, and failures remain JSON. Logical RPC carriers return decoded native values directly. Connection does not discover binary fields or depend on Typert; the handler that owns a result protocol performs any type-directed or runtime projection before returning. Binary parameters, events, and streamed binary results are unsupported.
The browser uses HTTP POST for Remote unary calls. API Gateway owns the /api/remote.mux WebSocket and its logical streams; shell-owned compositions provide equivalent Remote streams, including a stream's uplink, through connection.rpc.open without opening a WebSocket. The browser plugin reads the page transport, recovery settings, and location, then delegates to installConnection(ctx, options). A composition that owns its carrier may call the same installer directly; the whole-client test tier does so. Non-page carriers supply ClientTransportHooks.createWebSocket with the same authenticated Cookie as HTTP and a streamBaseUrl; ConnectionHandle.openWebSocket() resolves the Mux path against that base and invokes the selected factory. Each invocation creates one Context-owned service, so several Client trees can use different carriers in one realm. The Host half always provides the carrier-neutral RPC and exact GET/HEAD/POST route registries. When a Web carrier is present it also owns the sole /api route, Fetch bridge, browser authentication, and Host/Origin checks; a shell-owned carrier dispatches the shared Fetch handler directly. Each exact route declares buffered or streaming request-body handling before the bridge reads any bytes. Typert Gateway claims generated Remote endpoints, feature packages register non-JSON responses such as Session-log downloads and raw file uploads, and unclaimed requests return 404. Loopback hostname classification remains package-internal to the browser-facing Client state. Browser raw-body transfer is provided by dsh-client-file-upload.
Browser authentication and request trust
Over the Web carrier, every Host RPC method and WebSocket stream requires an authenticated browser or API Peer; there is no method-specific loopback tier. Each process mints a random launch token. dsh-web-app prints and opens its application URL with ?token=..., preserving the caller's authority and mount; frontend-static delegates root and index requests to ctx.connection.authorizeIndex, which accepts that token only on GET /, writes an authority-bound signed cookie, and redirects to clean ./, which drops the token and keeps the request's directory. A missing, expired, malformed, or wrong-authority cookie returns 401 before RPC dispatch. Static assets remain public. The HTTP carrier accepts query tokens only at the root exchange and /connect, and accepts no Authorization-header token.
With oneTimeLaunchTokens: true no reusable process token exists. Each authenticatedUrl call mints a token bound to that URL's protocol and host; it expires after 60 seconds, at most 5 wait at once and minting another drops the oldest, and its first presentation consumes it whatever the outcome: at the root or /connect, refused there by the fence or a provider policy or not, on any other path of the main listener through the web server's webserver/request event, and on a reach listener. A request with more than 4 token values is refused before any value is hashed. A token presented at another host than its own is refused with a 401 text that names the host it was minted for. The exchange is refused when Host differs from the minted URL's host, when Sec-Fetch-Site is neither none nor same-origin, or when Origin names another origin. oneTimeLaunchTokens reports the mode, and dsh-web-app then prints its URL without a token and mints one for each browser handoff. Only SHA-256 digests of waiting tokens are held, compared in constant time. reopenHint sets the instruction in the 401 body; the signed cookie and its lifetime are the same in both modes.
The cookie signing secret is the owner-scoped client-connection/browser-session grant record in ctx.credentials. The local provider persists it in $DSH_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.
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.
Before authentication, every request 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. A request with more than one Host line never reaches this fence: the web server answers it 400 before any route. A state-changing request (any method but GET, HEAD and OPTIONS) whose target is /api or below, read through WHATWG URL parsing as the router reads it, so /x/../api and its percent-encoded spellings count, must also state where it came from: an Origin, or sec-fetch-site: same-origin or none; same-site and cross-origin are refused. One with neither Origin nor sec-fetch-site passes only toward a loopback Host or an HTTPS listener, the destinations a Fetch-Metadata browser always marks; over plain HTTP to another authority it is refused, so a non-browser client there sends an Origin naming the listener. Malformed configured authorities fail plugin load. allowsRemoteAuthorities reports whether trustedHosts permits a non-loopback authority; accepting the bind IP does not change that list. 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. dsh web --host 0.0.0.0 is unsupported. Decision records: browser request trust and browser token authentication.
Every request speaks for one Peer, a PeerScope whose principal names the caller, whose interactions governs participation in forwarded events, and whose signal aborts when its scope ends. ctx.connection.browserPeer is shared by authenticated browser connections; it has owner principal and defaults to interactions: 'answer'. ctx.connection.admit(request) checks trust and browser or API authentication and returns the credential's live Peer or a rejection. The /api route and Gateway WebSocket upgrade use this admission; handlers receive the call's Peer. ctx.connection.createPeer({ principal, interactions? }) creates an independent in-process Peer, disposed with the Context that read the service or earlier through its own dispose(); omitted interactions default to answer. The exported Peer class accepts the same options. fetch(request, peer) and the HTTP bridge take the Peer explicitly; an exact route answers 403 to a non-owner Peer unless the route declares admitPeer and it admits that Peer, which a route decides through remote access for the action it performs on the resource its URL names. Method-level access for other principals belongs to dsh-api-remote-access.
Only API callers use GET /connect?token=...&interactions=answer|none: it immediately creates a Peer with owner principal and returns 302 with the Mux destination and a signed API Cookie. The API connection defaults to none; invalid or repeated declarations return 400. HTTP may precede WebSocket establishment. One API socket owns cleanup: duplicate attachment returns 409, closure removes its Peer, and later HTTP using that Cookie is refused. Already-admitted unary calls retain request-level cancellation, but invocation.peer.ctx cannot register effects after its Peer has been disposed. API callers keep their Cookie separate from browser storage; the authority-specific Cookie name is shared.
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. Client disconnection aborts the handler signal; the bridge stops socket writes and drains any remaining response chunks. WebSocket stream ownership remains with API Gateway.
Admission providers and reach listeners
Authenticator is the admission seam's Service Definition, provided as ctx.authenticator. A provider subclasses it: admit(request, listener) returns admitted with a Peer, pre-login with one route, or refused with a status and code, synchronously from in-memory state; policy(listener) returns the listener's declared scheme, Host rule, launch-token acceptance and pre-login routes, or undefined for a listener it does not serve; and authenticator/policy announces a changed policy. While no plugin provides authenticator, the loopback listener admits with ctx.connection.builtinAdmission(request), the launch-token and signed-cookie admission above, unchanged, and no reach listener can open. When a provider is loaded, the loopback listener still applies the Host/Origin fence first and then calls admit(request, 'loopback'); a provider may delegate to builtinAdmission. A loopback index request without a launch token is admitted by the provider too, and the launch-token exchange at the root and at /connect runs only while the provider's loopback policy, if it returns one, accepts the launch token. A setCookie the provider returns for a loopback request is added to the /api and RPC-channel responses, and to an index response whose writer offers setHeader. Each loopback credential Connection mints, from the launch-token exchange (kind: 'browser') or /connect (kind: 'api', with its Peer id), is announced with authenticator/minted synchronously before the response that carries it is written; the event carries the SHA-256 of the cookie value as base64url, its audience, and its issue and expiry times, never the value, so a provider can keep a record of every credential it will later admit.
ctx.connection.openReachListener({ listener, bind }) opens a reach listener through the web server's openListener: bind is loopback, a TCP port on 127.0.0.1 the operating system assigns, or streams, TLS ended on byte streams the caller hands in, and neither form takes a host or port. The listener opens only while a provider is loaded and returns a valid reach policy for it: the https scheme, no launch token, an https origin that names no loopback host, equals-address for loopback binds and equals-bound-name-and-sni for streams, and pre-login paths whose only placeholder is a final `` segment. It lives in a fiber that injects authenticator, so it closes, with every connection it accepted, before its provider is removed or replaced, and it never reopens by itself; it also stops when the provider's policy for it becomes invalid or absent, and when the Context that opened it is disposed.
Before any route, upgrade handler or the fallback runs, a reach listener's dispatcher applies these steps to every request and upgrade request, in order: it removes request headers whose names begin with tailscale- from the parsed, distinct and raw header views; it refuses a request target that is not in origin form, a second Host header line, or a Host other than the policy's address with 421 HOST_MISMATCH, and on a streams listener an SNI other than the address's hostname with 421 SNI_MISMATCH; it refuses an Origin other than the address, Sec-Fetch-Site: cross-site, or an upgrade without Origin with 403 ORIGIN_MISMATCH; it refuses a token query parameter with 401 LAUNCH_TOKEN_REFUSED, /connect with 401 CONNECT_REFUSED and any dsh-auth-* cookie with 401 UPSTREAM_COOKIE_REFUSED; and it calls admit. An admitted request is dispatched with its Peer,