description	kind
Browser-host wire layer for the web GUI: the shared API client, event-stream delivery with reconnect, the /api HTTP bridge, and the browser-trust fence, for users and maintainers composing or debugging the connection.	package-reference

@deepseek-ai/dsh-client-connection

English | 中文

Summary

Protocol and connection-generation layer. The Client plugin mounts ctx.connection, containing the shared API client, current-page loopback state, generation-scoped observable hostDescription, a generic RPC carrier, and the registration point for one generation source and the connection loop. A generation publishes hostDescription and calls onConnected only after its source is ready and host.describe succeeds; source completion, failure, withdrawal, or an explicit stop clears that value before ConnectionController reconnects with backoff.

Use this package
Browser authentication and request trust
Connection generation
Model Experience
Known Limitations and Deferred Work
Dev Note

Use this package

The browser uses HTTP POST for API Proxy and generic Remote unary calls. API Gateway owns the /api/remote.mux WebSocket and its logical streams; in-process compositions provide equivalent Remote streams through connection.rpc.open without opening a WebSocket. The Host half owns the sole /api route, Fetch bridge, browser authentication, and Host/Origin checks. Typert Gateway claims its Remote endpoints first, and unclaimed requests fall through to API Proxy. Loopback hostname classification remains package-internal to the browser-facing Client state.

Browser authentication and request trust

Every Host RPC method and WebSocket stream requires one browser session; there is no method-specific loopback tier. Each process mints a random launch token. dsh-web-app prints and opens the ordinary root URL with ?token=...; 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 /. A missing, expired, malformed, or wrong-authority cookie returns 401 before RPC dispatch. Static assets remain public. The HTTP carrier accepts no query token outside the root exchange and no Authorization-header token.

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; they deliberately omit Secure because the shipped server uses loopback HTTP.

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. dsh web --host 0.0.0.0 remains unsupported. Decision records: browser request trust and browser token authentication.

Connection generation

API Gateway Client registers the internal $events logical stream as the sole generation source, independently of whether any $on listener exists. The Host attaches all incremental listeners in the API Remotes source factory, then sends one { type: 'ready' } item before events. ConnectionController waits for that item and host.describe in parallel; onConnected cannot start baseline reads until both succeed, so baseline acquisition cannot race ahead of incremental observation.

An ended $events stream, a Remote stream error, a non-ready opening item, or a malformed event item invalidates the current generation. The controller immediately withdraws hostDescription, publishes reconnecting, and rebuilds the $events plus host.describe handshake after backoff. Gateway mux reconnects the physical WebSocket; Connection generation reopens the logical stream and establishes the next baseline starting point.

Model Experience

None, as the wire consumer layer moves already-composed messages between browser and host; nothing here reaches a model request.

KV Cache effect

None; this package neither assembles nor sends a provider request.

Known Limitations and Deferred Work

The /api bridge buffers each request body in memory — maxRequestBodyBytes (default 300 MiB, sized for the default 200 MiB aggregate image limit after base64 expansion plus envelope headroom) is therefore also the per-request resident bound; a streaming body path would be needed to lower it without shrinking the image limits.
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.
There is no logout operation — clearing the browser cookie ends one browser session; deleting the owner credential record and restarting dsh revokes every session.

Dev Note

Working context for maintainers — click to expand

None.

README.md