dsh-realtime-audio-ws 0.1.2 → 0.2.0

package/lib/client/bundle.js

@@ -0,0 +1,313 @@
+window.__ModuleLoader__.load({ id: "dsh-realtime-audio-ws",
+  factory: (require) => {
+    const exports = {}
+    const module = { exports }
+    "use strict";
+    /**
+     * The browser face: microphone in, speaker out, over the host route.
+     *
+     * This is the client half of the transport. `dsh-realtime-audio-ws` claims the socket on the host and
+     * bridges it to the agent's audio events; this file opens that socket, captures the microphone into it, and
+     * plays what comes back.
+     *
+     * **One file, on purpose.** A client face is served as a single resource (`<package>/client.js`), so a
+     * relative value import would emit a second file the loader never serves. Everything therefore lives here,
+     * including the API shapes it needs.
+     *
+     * **No DOM lib, also on purpose.** The browser APIs are described structurally and read off `globalThis`
+     * through one cast, so this compiles in the package's ordinary program — no second tsconfig, no DOM lib,
+     * no bundler — and every path is testable by injecting fakes. `standard-browser-types` would have bought
+     * accurate types for six objects at the cost of a whole second build face; this is the cheaper trade.
+     *
+     * **`ScriptProcessorNode`, and why.** The modern capture path is an `AudioWorklet`, whose module must be
+     * fetched from a URL — a `blob:` URL, which a page's Content-Security-Policy can refuse. The desktop app
+     * demonstrably *has* a CSP (a `connect-src 'none'` string is in its bundle, governing the shell pages), and
+     * I have not read the app page's policy. `ScriptProcessorNode` needs no URL, no module fetch and no policy
+     * grant, and it runs in the page, so the whole capture path is testable. It is deprecated and its latency is
+     * worse. That is a deliberate, disclosed trade: swap it for a worklet once the app page's `script-src` has
+     * actually been read, rather than shipping a capture path that a policy might silently kill.
+     */
+    Object.defineProperty(exports, "__esModule", { value: true });
+    exports.INJECTED_KEY = exports.GLOBAL_KEY = exports.MAX_BACKLOG_SECONDS = exports.CAPTURE_BUFFER = exports.SAMPLE_RATE = exports.DEFAULT_PATH = exports.inject = exports.name = void 0;
+    exports.socketUrl = socketUrl;
+    exports.pageAuthority = pageAuthority;
+    exports.withToken = withToken;
+    exports.pcm16FromFloat32 = pcm16FromFloat32;
+    exports.float32FromPcm16 = float32FromPcm16;
+    exports.defaultDeps = defaultDeps;
+    exports.createAudioClient = createAudioClient;
+    exports.apply = apply;
+    /** Browser-side plugin name. */
+    exports.name = 'realtime-audio-client';
+    /**
+     * No client services. The socket, the device and the audio graph are all this plugin's own, so it injects
+     * nothing — and a client face that needs nothing cannot be broken by another plugin's absence.
+     */
+    exports.inject = [];
+    /** Where the host route lives. Duplicated from the host package because a client face cannot import it. */
+    exports.DEFAULT_PATH = '/dsh-realtime/audio';
+    /** The session's declared rate. The graph is opened at this rate or the client refuses to run. */
+    exports.SAMPLE_RATE = 24_000;
+    /** Capture chunk in samples. 1024 at 24 kHz is ~43 ms: the 2^10 floor the API allows, so latency is lowest. */
+    exports.CAPTURE_BUFFER = 1024;
+    /** Backlog past which incoming speech is dropped rather than queued — the same rule the host carries. */
+    exports.MAX_BACKLOG_SECONDS = 0.5;
+    /** Global the client publishes itself on. There is no UI surface yet; this is how it is started. */
+    exports.GLOBAL_KEY = '__dshRealtimeAudio';
+    /** Optional host-injected settings, published as a `global` index-injection row before this file runs. */
+    exports.INJECTED_KEY = '__DSH_REALTIME_AUDIO__';
+    // ---- pure helpers --------------------------------------------------------------------------------------
+    /**
+     * The socket URL for the host route.
+     *
+     * @param location - the page's location, or undefined when there is none.
+     * @param path - the route pathname.
+     * @returns the URL, or undefined when this page cannot host a socket at all.
+     */
+    function socketUrl(location, path, authority) {
+        const host = authority !== undefined && authority !== '' ? authority : pageAuthority(location);
+        if (host === undefined)
+            return undefined;
+        // An https page may not open a ws:// socket — the browser blocks it as mixed content — so the scheme has
+        // to follow the page rather than being decided here.
+        const scheme = location?.protocol === 'https:' ? 'wss' : 'ws';
+        return `${scheme}://${host}${path}`;
+    }
+    /**
+     * The authority a page can derive for itself, or undefined when it cannot derive a usable one.
+     *
+     * Only an http(s) page addresses a server. The desktop app's page is served from `dsh-app://app`, whose
+     * host is the literal string `app`: deriving a socket URL from it yields `ws://app/...`, which resolves
+     * nowhere and fails in a way that reads exactly like the host refusing the connection — a wrong answer
+     * that costs an afternoon. Returning undefined lets the caller name the real cause instead.
+     *
+     * @param location - the page's location, or undefined when there is none.
+     * @returns the authority, or undefined when this page has no usable one of its own.
+     */
+    function pageAuthority(location) {
+        if (location === undefined)
+            return undefined;
+        if (location.protocol !== 'http:' && location.protocol !== 'https:')
+            return undefined;
+        return location.host === '' ? undefined : location.host;
+    }
+    /**
+     * Attach the capability token, when the host injected one.
+     *
+     * @param url - the socket URL.
+     * @param token - the injected token, or undefined on a host that injects none.
+     * @returns the URL to open.
+     */
+    function withToken(url, token) {
+        if (token === undefined || token === '')
+            return url;
+        return `${url}?t=${encodeURIComponent(token)}`;
+    }
+    /**
+     * Convert one captured float block to the wire's PCM16.
+     *
+     * Clamped, not wrapped: a sample above 1.0 is a loud peak, and letting it wrap turns a loud voice into
+     * noise. Asymmetric on purpose — 32767 is the largest Int16 and -32768 the smallest, so scaling both by the
+     * same factor would clip every negative peak one step early.
+     *
+     * @param input - samples in the range [-1, 1].
+     * @returns the same samples as little-endian PCM16 bytes.
+     */
+    function pcm16FromFloat32(input) {
+        const out = new Int16Array(input.length);
+        // `entries()` rather than an index: under `noUncheckedIndexedAccess` an indexed read is
+        // `number | undefined`, and guarding that would add a branch that can never be taken at runtime.
+        for (const [index, raw] of input.entries()) {
+            const sample = Math.max(-1, Math.min(1, raw));
+            out[index] = Math.round(sample < 0 ? sample * 32768 : sample * 32767);
+        }
+        return out;
+    }
+    /**
+     * Read one PCM16 frame as playback samples.
+     *
+     * @param bytes - the frame.
+     * @returns samples in [-1, 1).
+     */
+    function float32FromPcm16(bytes) {
+        const samples = new Int16Array(bytes.buffer, bytes.byteOffset, Math.floor(bytes.byteLength / 2));
+        const out = new Float32Array(samples.length);
+        for (const [index, sample] of samples.entries())
+            out[index] = sample / 32768;
+        return out;
+    }
+    /**
+     * Read the real browser APIs, and any settings the host injected.
+     *
+     * @param scope - the global scope, injectable so both the present and absent cases are testable without
+     * mutating the process's own globals.
+     * @returns the production dependencies. Every one may be absent, which is why `start` reports rather than
+     * throws: a page without a microphone API is a fact about the page, not a defect in the caller.
+     */
+    function defaultDeps(scope = globalThis) {
+        const media = scope.navigator?.mediaDevices;
+        const Audio = scope.AudioContext;
+        const Socket = scope.WebSocket;
+        return {
+            location: scope.location,
+            getUserMedia: media === undefined ? undefined : (constraints) => media.getUserMedia(constraints),
+            createAudioContext: Audio === undefined ? undefined : (rate) => new Audio({ sampleRate: rate }),
+            createSocket: Socket === undefined ? undefined : (url) => new Socket(url),
+            injected: scope.__DSH_REALTIME_AUDIO__,
+        };
+    }
+    /**
+     * The client: one microphone in, one socket out, one speaker fed.
+     *
+     * @param deps - the outside world, injected so every path is testable.
+     * @returns the start/stop/state handle.
+     */
+    function createAudioClient(deps) {
+        let current = { kind: 'idle' };
+        let socket;
+        let context;
+        let stream;
+        let processor;
+        let silence;
+        let playsAt = 0;
+        const fail = (reason) => {
+            current = { kind: 'failed', reason };
+            return current;
+        };
+        /** Release everything held. Idempotent, because stop, an error and a close all reach it. */
+        const release = () => {
+            socket?.close();
+            socket = undefined;
+            processor?.disconnect();
+            processor = undefined;
+            silence?.disconnect();
+            silence = undefined;
+            for (const track of stream?.getTracks() ?? [])
+                track.stop();
+            stream = undefined;
+            const closing = context;
+            context = undefined;
+            if (closing !== undefined)
+                void closing.close().catch(() => undefined);
+            playsAt = 0;
+        };
+        /** Play one frame, dropping it rather than queueing when we are already behind. */
+        const play = (bytes) => {
+            if (context === undefined)
+                return;
+            const samples = float32FromPcm16(bytes);
+            if (samples.length === 0)
+                return;
+            const buffer = context.createBuffer(1, samples.length, exports.SAMPLE_RATE);
+            buffer.getChannelData(0).set(samples);
+            const now = context.currentTime;
+            const at = Math.max(now, playsAt);
+            // Unbuffered, like the host: audio that is already late is dropped rather than played behind, because a
+            // queue that grows converts a stutter into a permanent delay that never recovers.
+            if (at - now > exports.MAX_BACKLOG_SECONDS)
+                return;
+            const source = context.createBufferSource();
+            source.buffer = buffer;
+            source.connect(context.destination);
+            source.start(at);
+            playsAt = at + buffer.duration;
+        };
+        /** Build the capture graph and start shipping frames. */
+        const attachCapture = () => {
+            if (context === undefined || stream === undefined || socket === undefined) {
+                return fail('the audio graph went away before the socket opened');
+            }
+            const source = context.createMediaStreamSource(stream);
+            const node = context.createScriptProcessor(exports.CAPTURE_BUFFER, 1, 1);
+            node.onaudioprocess = (event) => {
+                const pcm16 = pcm16FromFloat32(event.inputBuffer.getChannelData(0));
+                socket?.send(new Uint8Array(pcm16.buffer));
+            };
+            // A ScriptProcessorNode only fires while connected to the destination — and connecting the microphone
+            // there is a feedback loop. A zero-gain node keeps it running with nothing audible, which is the whole
+            // reason this chain looks the way it does.
+            const mute = context.createGain();
+            mute.gain.value = 0;
+            source.connect(node);
+            node.connect(mute);
+            mute.connect(context.destination);
+            processor = node;
+            silence = mute;
+            current = { kind: 'live' };
+            return current;
+        };
+        const stop = () => {
+            release();
+            current = { kind: 'idle' };
+        };
+        const start = async () => {
+            if (current.kind === 'live')
+                return current;
+            const route = socketUrl(deps.location, deps.injected?.path ?? exports.DEFAULT_PATH, deps.injected?.authority);
+            if (route === undefined) {
+                return fail('no authority for the audio socket: this page has none of its own and the host injected none');
+            }
+            const url = withToken(route, deps.injected?.token);
+            if (deps.getUserMedia === undefined)
+                return fail('this page has no microphone API');
+            if (deps.createAudioContext === undefined)
+                return fail('this page has no audio API');
+            if (deps.createSocket === undefined)
+                return fail('this page has no WebSocket API');
+            try {
+                stream = await deps.getUserMedia({
+                    audio: { channelCount: 1, echoCancellation: true, noiseSuppression: true },
+                });
+            }
+            catch (error) {
+                // A refused permission is the ordinary case here, not an error to hide: the reason is what tells the
+                // user whether to grant it or to look somewhere else.
+                return fail(error instanceof Error ? error.message : String(error));
+            }
+            context = deps.createAudioContext(exports.SAMPLE_RATE);
+            if (context.sampleRate !== exports.SAMPLE_RATE) {
+                // Refuse rather than mislabel. Streaming 48 kHz samples declared as 24 kHz arrives at half speed and
+                // sounds like a provider fault, which is the most expensive possible way to learn about a resampler.
+                const opened = context.sampleRate;
+                release();
+                return fail(`the audio graph opened at ${String(opened)} Hz, not ${String(exports.SAMPLE_RATE)}`);
+            }
+            const opened = deps.createSocket(url);
+            socket = opened;
+            opened.binaryType = 'arraybuffer';
+            opened.onmessage = (event) => {
+                if (event.data instanceof ArrayBuffer)
+                    play(new Uint8Array(event.data));
+            };
+            opened.onclose = () => {
+                release();
+                current = { kind: 'idle' };
+            };
+            return await new Promise((resolve) => {
+                opened.onopen = () => { resolve(attachCapture()); };
+                opened.onerror = () => { resolve(fail('the host refused the audio socket')); };
+            });
+        };
+        return { start, stop, state: () => current };
+    }
+    /**
+     * The client plugin. Publishes the client on a global and releases it with the plugin.
+     *
+     * There is no UI surface yet, so a global is how it is driven — a settings card is its own increment and a
+     * bigger one than this. `inject` is empty for the same reason: nothing here needs another plugin.
+     *
+     * @param ctx - the client context, used only to own the lifetime.
+     */
+    function apply(ctx) {
+        const client = createAudioClient(defaultDeps());
+        globalThis[exports.GLOBAL_KEY] = {
+            start: () => client.start(),
+            stop: () => { client.stop(); },
+            state: () => client.state(),
+        };
+        // A held microphone and a live audio graph must not outlive the plugin that opened them.
+        ctx.effect(() => () => { client.stop(); }, 'realtime-audio-client');
+    }
+    return exports
+  },
+})

package/lib/client/index.js

@@ -26,6 +26,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.INJECTED_KEY = exports.GLOBAL_KEY = exports.MAX_BACKLOG_SECONDS = exports.CAPTURE_BUFFER = exports.SAMPLE_RATE = exports.DEFAULT_PATH = exports.inject = exports.name = void 0;
 exports.socketUrl = socketUrl;
+exports.pageAuthority = pageAuthority;
+exports.withToken = withToken;
 exports.pcm16FromFloat32 = pcm16FromFloat32;
 exports.float32FromPcm16 = float32FromPcm16;
 exports.defaultDeps = defaultDeps;
@@ -48,7 +50,7 @@ exports.CAPTURE_BUFFER = 1024;
 exports.MAX_BACKLOG_SECONDS = 0.5;
 /** Global the client publishes itself on. There is no UI surface yet; this is how it is started. */
 exports.GLOBAL_KEY = '__dshRealtimeAudio';
-/** Optional host-injected settings. A future index-injection row may set the path; the default matches. */
+/** Optional host-injected settings, published as a `global` index-injection row before this file runs. */
 exports.INJECTED_KEY = '__DSH_REALTIME_AUDIO__';
 // ---- pure helpers --------------------------------------------------------------------------------------
 /**
@@ -58,13 +60,44 @@ exports.INJECTED_KEY = '__DSH_REALTIME_AUDIO__';
  * @param path - the route pathname.
  * @returns the URL, or undefined when this page cannot host a socket at all.
  */
-function socketUrl(location, path) {
-    if (location === undefined || location.host === '')
+function socketUrl(location, path, authority) {
+    const host = authority !== undefined && authority !== '' ? authority : pageAuthority(location);
+    if (host === undefined)
         return undefined;
     // An https page may not open a ws:// socket — the browser blocks it as mixed content — so the scheme has
     // to follow the page rather than being decided here.
-    const scheme = location.protocol === 'https:' ? 'wss' : 'ws';
-    return `${scheme}://${location.host}${path}`;
+    const scheme = location?.protocol === 'https:' ? 'wss' : 'ws';
+    return `${scheme}://${host}${path}`;
+}
+/**
+ * The authority a page can derive for itself, or undefined when it cannot derive a usable one.
+ *
+ * Only an http(s) page addresses a server. The desktop app's page is served from `dsh-app://app`, whose
+ * host is the literal string `app`: deriving a socket URL from it yields `ws://app/...`, which resolves
+ * nowhere and fails in a way that reads exactly like the host refusing the connection — a wrong answer
+ * that costs an afternoon. Returning undefined lets the caller name the real cause instead.
+ *
+ * @param location - the page's location, or undefined when there is none.
+ * @returns the authority, or undefined when this page has no usable one of its own.
+ */
+function pageAuthority(location) {
+    if (location === undefined)
+        return undefined;
+    if (location.protocol !== 'http:' && location.protocol !== 'https:')
+        return undefined;
+    return location.host === '' ? undefined : location.host;
+}
+/**
+ * Attach the capability token, when the host injected one.
+ *
+ * @param url - the socket URL.
+ * @param token - the injected token, or undefined on a host that injects none.
+ * @returns the URL to open.
+ */
+function withToken(url, token) {
+    if (token === undefined || token === '')
+        return url;
+    return `${url}?t=${encodeURIComponent(token)}`;
 }
 /**
  * Convert one captured float block to the wire's PCM16.
@@ -206,9 +239,11 @@ function createAudioClient(deps) {
     const start = async () => {
         if (current.kind === 'live')
             return current;
-        const url = socketUrl(deps.location, deps.injected?.path ?? exports.DEFAULT_PATH);
-        if (url === undefined)
-            return fail('this page has no location to open a socket against');
+        const route = socketUrl(deps.location, deps.injected?.path ?? exports.DEFAULT_PATH, deps.injected?.authority);
+        if (route === undefined) {
+            return fail('no authority for the audio socket: this page has none of its own and the host injected none');
+        }
+        const url = withToken(route, deps.injected?.token);
         if (deps.getUserMedia === undefined)
             return fail('this page has no microphone API');
         if (deps.createAudioContext === undefined)

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,MAAM,MAAM,0BAA0B,CAAA;AAC7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAOlD,OAAO,EAML,KAAK,qBAAqB,EAC3B,MAAM,YAAY,CAAA;AAEnB,cAAc,YAAY,CAAA;AAC1B,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAA;AACpF,OAAO,EAAE,qBAAqB,EAAE,aAAa,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAA;AAEzF,mBAAmB;AACnB,eAAO,MAAM,IAAI,sBAAsB,CAAA;AAEvC,eAAO,MAAM,MAAM;;;;;;;;;;aAQjB,CAAA;AAqBF,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,qBAAqB,GAAG,IAAI,CAoDvE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,MAAM,MAAM,0BAA0B,CAAA;AAC7C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAelD,OAAO,EAML,KAAK,qBAAqB,EAC3B,MAAM,YAAY,CAAA;AAEnB,cAAc,YAAY,CAAA;AAC1B,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAA;AACpF,OAAO,EAAE,qBAAqB,EAAE,aAAa,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAA;AAEzF,mBAAmB;AACnB,eAAO,MAAM,IAAI,sBAAsB,CAAA;AAEvC,eAAO,MAAM,MAAM;;;;;;;;;;aAQjB,CAAA;AA4BF,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,qBAAqB,GAAG,IAAI,CA+EvE"}

package/lib/index.js

@@ -12,6 +12,7 @@
  */
 import Schema from '@deepseek-ai/schemastery';
 import { attachAudioSocket } from './bridge.js';
+import { createRouteToken, routeAuthority, routeInjectionRow, tokenFromUrl, verdictFor, } from './injection.js';
 import { createUpgradeAcceptor, rejectUpgrade } from './upgrade.js';
 import { DEFAULT_MAX_CONNECTIONS, DEFAULT_MAX_FRAME_BYTES, DEFAULT_OPEN_SESSION_ON_CONNECT, DEFAULT_PATH, } from './types.js';
 export * from './types.js';
@@ -33,7 +34,18 @@ export function apply(ctx, config) {
         const services = injected;
         const acceptor = createUpgradeAcceptor(config.maxFrameBytes);
         const clients = new Set();
+        const token = createRouteToken();
+        // The injection event is declared by `@deepseek-ai/dsh-host-webserver`, which this package deliberately
+        // does not import: importing it would augment `Context` with a second declaration of `webServer` and
+        // turn the structural dependency above into a compile error. The name is cast at this one boundary.
+        const onInjection = ctx.on;
         ctx.effect(() => {
+            // The page is told where the route is and what to present. The web server gathers this table on every
+            // index render and every worker boot-payload request, so the row is built at emit time — the only
+            // moment the listening port is known for certain, since an index render follows the listen.
+            onInjection('webserver/index-inject', (table) => {
+                table.push(routeInjectionRow(config.path, routeAuthority(services.webServer.config?.host, services.webServer.listenedPort), token));
+            });
             const unregister = services.webServer.registerUpgrade({
                 path: config.path,
                 handler: (req, socket, head) => {
@@ -42,7 +54,12 @@ export function apply(ctx, config) {
                     // microphone audio in and the agent's answers out. DSH's own transport asks the connection
                     // service in exactly this position, so this route asks the same question rather than inventing a
                     // second scheme that would drift from it.
-                    const rejection = services.connection.requestRejection(req);
+                    //
+                    // The token is the one addition, and it is not a second scheme. The desktop app's page is served
+                    // from `dsh-app://app`, so its requests to loopback are cross-site and the harness's
+                    // `SameSite=Strict` cookie cannot travel; without the token that page is refused forever, however
+                    // correct the rest of the client half is.
+                    const rejection = verdictFor(services.connection.requestRejection(req), tokenFromUrl(req.url), token);
                     if (rejection !== undefined) {
                         rejectUpgrade(socket, rejection);
                         return;

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/lib/injection.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The route's page-side settings: the row the host injects, and the credential check that lets the
+ * desktop app's renderer use the route at all.
+ *
+ * Two facts decide this file's shape.
+ *
+ * The first is that the harness web server gathers a structured *injection table* on every index render
+ * and every worker boot-payload request, by emitting `webserver/index-inject`; listeners append their
+ * rows and the rows are read fresh at emit time. That is a door built for plugins, which is why this
+ * package uses it rather than a raw string transform on the HTML.
+ *
+ * The second is a consequence of being a browser face inside the desktop app. That page's origin is
+ * `dsh-app://app`, and the harness's own auth cookie is `SameSite=Strict` and bound to the loopback
+ * authority — so a request from the app page to `127.0.0.1` is cross-site and carries no cookie. The
+ * connection service would therefore refuse the app's renderer, correctly and forever, no matter how
+ * right the rest of the client half is.
+ *
+ * A capability token — generated once per process, injected only into the page the host itself serves —
+ * is the credential that can travel. It is script-readable where the cookie is not, and that is a real
+ * weakening: it is the price of the app working at all. It authorises one route, on loopback, for the
+ * life of the process, and is worthless afterwards.
+ */
+/** Global the page reads its route settings from. Duplicated in the client half, which cannot import it. */
+export declare const INJECTED_KEY = "__DSH_REALTIME_AUDIO__";
+/** Query parameter carrying the capability token on an upgrade request. */
+export declare const TOKEN_PARAM = "t";
+/** A structured index-injection row of the kind this package contributes. */
+export interface InjectedGlobalRow {
+    readonly kind: 'global';
+    readonly name: string;
+    readonly value: unknown;
+}
+/**
+ * Where the client should open its socket, or undefined when the host is not listening yet.
+ *
+ * A wildcard bind is normalised to loopback because the page is on this machine: handing a client
+ * `0.0.0.0:port` asks it to connect to a name meaning "every interface", which resolves nowhere useful.
+ * An IPv6 literal is bracketed so the authority parses as a URL rather than as a host with a port.
+ *
+ * @param host - the configured bind host, as the web server reports it.
+ * @param port - the port actually listening — the OS-assigned value when the config asked for zero.
+ * @returns the authority (`host:port`), or undefined before the server is listening.
+ */
+export declare function routeAuthority(host: string | undefined, port: number | undefined): string | undefined;
+/**
+ * One process-scoped capability token.
+ *
+ * 32 bytes, base64url, because the token travels in a URL query and base64url needs no escaping there.
+ */
+export declare function createRouteToken(): string;
+/**
+ * Read the token off an upgrade request's target.
+ *
+ * @param url - the request target as `node:http` reports it: pathname plus query.
+ * @returns the token, or undefined when absent or empty.
+ */
+export declare function tokenFromUrl(url: string | undefined): string | undefined;
+/**
+ * Compare a presented token with this process's own, in constant time.
+ *
+ * Length is compared first because `timingSafeEqual` throws on buffers of different lengths, which would
+ * turn a probe into a crash. The length is not the secret; the value is.
+ *
+ * @param provided - the token the caller presented, if any.
+ * @param expected - this process's token.
+ * @returns whether the caller may be treated as this process's own page.
+ */
+export declare function tokenMatches(provided: string | undefined, expected: string): boolean;
+/**
+ * The connection service's verdict, overridden by a valid token.
+ *
+ * DSH's own transport asks the connection service in this position, and this route asks the same question
+ * rather than inventing a second scheme that would drift from it. The token is the only addition, and it
+ * is not a second scheme: a caller that cannot carry the cookie at all — the app's renderer — may present
+ * the token the host injected into that very page instead.
+ *
+ * @param rejection - what the connection service said about this request.
+ * @param provided - the token on the request, if any.
+ * @param expected - this process's token.
+ * @returns the rejection to write, or undefined to accept the upgrade.
+ */
+export declare function verdictFor(rejection: 401 | 403 | undefined, provided: string | undefined, expected: string): 401 | 403 | undefined;
+/**
+ * The row the page reads, built at emit time.
+ *
+ * `value` is JSON-serialised by the web server, which escapes `<` so a value cannot close the script
+ * element early; an undefined `authority` is dropped by `JSON.stringify`, which is exactly the "this host
+ * injected no authority" case the client half names rather than guesses at.
+ */
+export declare function routeInjectionRow(path: string, authority: string | undefined, token: string): InjectedGlobalRow;
+//# sourceMappingURL=injection.d.ts.map

package/lib/injection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"injection.d.ts","sourceRoot":"","sources":["../src/injection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,4GAA4G;AAC5G,eAAO,MAAM,YAAY,2BAA2B,CAAA;AAEpD,2EAA2E;AAC3E,eAAO,MAAM,WAAW,MAAM,CAAA;AAE9B,6EAA6E;AAC7E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CACxB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAIrG;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAMxE;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAMpF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CACxB,SAAS,EAAE,GAAG,GAAG,GAAG,GAAG,SAAS,EAChC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,QAAQ,EAAE,MAAM,GACf,GAAG,GAAG,GAAG,GAAG,SAAS,CAGvB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,KAAK,EAAE,MAAM,GACZ,iBAAiB,CAEnB"}

package/lib/injection.js

@@ -0,0 +1,115 @@
+/**
+ * The route's page-side settings: the row the host injects, and the credential check that lets the
+ * desktop app's renderer use the route at all.
+ *
+ * Two facts decide this file's shape.
+ *
+ * The first is that the harness web server gathers a structured *injection table* on every index render
+ * and every worker boot-payload request, by emitting `webserver/index-inject`; listeners append their
+ * rows and the rows are read fresh at emit time. That is a door built for plugins, which is why this
+ * package uses it rather than a raw string transform on the HTML.
+ *
+ * The second is a consequence of being a browser face inside the desktop app. That page's origin is
+ * `dsh-app://app`, and the harness's own auth cookie is `SameSite=Strict` and bound to the loopback
+ * authority — so a request from the app page to `127.0.0.1` is cross-site and carries no cookie. The
+ * connection service would therefore refuse the app's renderer, correctly and forever, no matter how
+ * right the rest of the client half is.
+ *
+ * A capability token — generated once per process, injected only into the page the host itself serves —
+ * is the credential that can travel. It is script-readable where the cookie is not, and that is a real
+ * weakening: it is the price of the app working at all. It authorises one route, on loopback, for the
+ * life of the process, and is worthless afterwards.
+ */
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+/** Global the page reads its route settings from. Duplicated in the client half, which cannot import it. */
+export const INJECTED_KEY = '__DSH_REALTIME_AUDIO__';
+/** Query parameter carrying the capability token on an upgrade request. */
+export const TOKEN_PARAM = 't';
+/**
+ * Where the client should open its socket, or undefined when the host is not listening yet.
+ *
+ * A wildcard bind is normalised to loopback because the page is on this machine: handing a client
+ * `0.0.0.0:port` asks it to connect to a name meaning "every interface", which resolves nowhere useful.
+ * An IPv6 literal is bracketed so the authority parses as a URL rather than as a host with a port.
+ *
+ * @param host - the configured bind host, as the web server reports it.
+ * @param port - the port actually listening — the OS-assigned value when the config asked for zero.
+ * @returns the authority (`host:port`), or undefined before the server is listening.
+ */
+export function routeAuthority(host, port) {
+    if (port === undefined)
+        return undefined;
+    const name = host === undefined || host === '' || host === '0.0.0.0' || host === '::' ? '127.0.0.1' : host;
+    return name.includes(':') ? `[${name}]:${String(port)}` : `${name}:${String(port)}`;
+}
+/**
+ * One process-scoped capability token.
+ *
+ * 32 bytes, base64url, because the token travels in a URL query and base64url needs no escaping there.
+ */
+export function createRouteToken() {
+    return randomBytes(32).toString('base64url');
+}
+/**
+ * Read the token off an upgrade request's target.
+ *
+ * @param url - the request target as `node:http` reports it: pathname plus query.
+ * @returns the token, or undefined when absent or empty.
+ */
+export function tokenFromUrl(url) {
+    if (url === undefined)
+        return undefined;
+    const query = url.indexOf('?');
+    if (query < 0)
+        return undefined;
+    const value = new URLSearchParams(url.slice(query + 1)).get(TOKEN_PARAM);
+    return value === null || value === '' ? undefined : value;
+}
+/**
+ * Compare a presented token with this process's own, in constant time.
+ *
+ * Length is compared first because `timingSafeEqual` throws on buffers of different lengths, which would
+ * turn a probe into a crash. The length is not the secret; the value is.
+ *
+ * @param provided - the token the caller presented, if any.
+ * @param expected - this process's token.
+ * @returns whether the caller may be treated as this process's own page.
+ */
+export function tokenMatches(provided, expected) {
+    if (provided === undefined)
+        return false;
+    const offered = Buffer.from(provided);
+    const own = Buffer.from(expected);
+    if (offered.length !== own.length)
+        return false;
+    return timingSafeEqual(offered, own);
+}
+/**
+ * The connection service's verdict, overridden by a valid token.
+ *
+ * DSH's own transport asks the connection service in this position, and this route asks the same question
+ * rather than inventing a second scheme that would drift from it. The token is the only addition, and it
+ * is not a second scheme: a caller that cannot carry the cookie at all — the app's renderer — may present
+ * the token the host injected into that very page instead.
+ *
+ * @param rejection - what the connection service said about this request.
+ * @param provided - the token on the request, if any.
+ * @param expected - this process's token.
+ * @returns the rejection to write, or undefined to accept the upgrade.
+ */
+export function verdictFor(rejection, provided, expected) {
+    if (rejection === undefined)
+        return undefined;
+    return tokenMatches(provided, expected) ? undefined : rejection;
+}
+/**
+ * The row the page reads, built at emit time.
+ *
+ * `value` is JSON-serialised by the web server, which escapes `<` so a value cannot close the script
+ * element early; an undefined `authority` is dropped by `JSON.stringify`, which is exactly the "this host
+ * injected no authority" case the client half names rather than guesses at.
+ */
+export function routeInjectionRow(path, authority, token) {
+    return { kind: 'global', name: INJECTED_KEY, value: { path, authority, token } };
+}
+//# sourceMappingURL=injection.js.map

package/lib/injection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"injection.js","sourceRoot":"","sources":["../src/injection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE1D,4GAA4G;AAC5G,MAAM,CAAC,MAAM,YAAY,GAAG,wBAAwB,CAAA;AAEpD,2EAA2E;AAC3E,MAAM,CAAC,MAAM,WAAW,GAAG,GAAG,CAAA;AAS9B;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,IAAwB,EAAE,IAAwB;IAC/E,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,SAAS,CAAA;IACxC,MAAM,IAAI,GAAG,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAA;IAC1G,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,KAAK,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,EAAE,CAAA;AACrF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAA;AAC9C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,GAAuB;IAClD,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAA;IACvC,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAC9B,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,SAAS,CAAA;IAC/B,MAAM,KAAK,GAAG,IAAI,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,CAAA;IACxE,OAAO,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAA;AAC3D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAC,QAA4B,EAAE,QAAgB;IACzE,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,KAAK,CAAA;IACxC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IACrC,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IACjC,IAAI,OAAO,CAAC,MAAM,KAAK,GAAG,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IAC/C,OAAO,eAAe,CAAC,OAAO,EAAE,GAAG,CAAC,CAAA;AACtC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,UAAU,CACxB,SAAgC,EAChC,QAA4B,EAC5B,QAAgB;IAEhB,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,SAAS,CAAA;IAC7C,OAAO,YAAY,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAA;AACjE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAY,EACZ,SAA6B,EAC7B,KAAa;IAEb,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,CAAA;AAClF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-realtime-audio-ws",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "The host end of the client half's transport: a WebSocket upgrade route that bridges microphone audio in and agent speech out.",
   "type": "module",
   "main": "lib/index.js",
@@ -12,7 +12,7 @@
     },
     "./client": {
       "types": "./lib/client/index.d.ts",
-      "default": "./lib/client/index.js"
+      "default": "./lib/client/bundle.js"
     },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
@@ -64,7 +64,7 @@
     "@types/ws": "^8.18.2"
   },
   "scripts": {
-    "build": "tsc -b && tsc -p tsconfig.client.json",
+    "build": "tsc -b && tsc -p tsconfig.client.json && node ../../scripts/client-bundle.mjs .",
     "typecheck": "tsc -b --dry"
   }
 }

package/src/client/index.ts

@@ -47,7 +47,17 @@ export const MAX_BACKLOG_SECONDS = 0.5
 /** Global the client publishes itself on. There is no UI surface yet; this is how it is started. */
 export const GLOBAL_KEY = '__dshRealtimeAudio'
 
-/** Optional host-injected settings. A future index-injection row may set the path; the default matches. */
+/**
+ * What the host injects into the page: the route path, the authority to open the socket against, and the
+ * capability token to present. Every field is optional, because an older host injects only the path.
+ */
+export interface InjectedRouteSettings {
+  readonly path?: string
+  readonly authority?: string
+  readonly token?: string
+}
+
+/** Optional host-injected settings, published as a `global` index-injection row before this file runs. */
 export const INJECTED_KEY = '__DSH_REALTIME_AUDIO__'
 
 // ---- the API shapes this file needs, described rather than imported -----------------------------------
@@ -98,7 +108,7 @@ export interface ClientAudioDeps {
   readonly getUserMedia: ((constraints: unknown) => Promise<StreamLike>) | undefined
   readonly createAudioContext: ((sampleRate: number) => ContextLike) | undefined
   readonly createSocket: ((url: string) => SocketLike) | undefined
-  readonly injected: { readonly path?: string } | undefined
+  readonly injected: InjectedRouteSettings | undefined
 }
 
 /** What the caller — or a test — gets to see. */
@@ -125,12 +135,46 @@ export interface ClientAudio {
  * @param path - the route pathname.
  * @returns the URL, or undefined when this page cannot host a socket at all.
  */
-export function socketUrl(location: LocationLike | undefined, path: string): string | undefined {
-  if (location === undefined || location.host === '') return undefined
+export function socketUrl(
+  location: LocationLike | undefined,
+  path: string,
+  authority?: string,
+): string | undefined {
+  const host = authority !== undefined && authority !== '' ? authority : pageAuthority(location)
+  if (host === undefined) return undefined
   // An https page may not open a ws:// socket — the browser blocks it as mixed content — so the scheme has
   // to follow the page rather than being decided here.
-  const scheme = location.protocol === 'https:' ? 'wss' : 'ws'
-  return `${scheme}://${location.host}${path}`
+  const scheme = location?.protocol === 'https:' ? 'wss' : 'ws'
+  return `${scheme}://${host}${path}`
+}
+
+/**
+ * The authority a page can derive for itself, or undefined when it cannot derive a usable one.
+ *
+ * Only an http(s) page addresses a server. The desktop app's page is served from `dsh-app://app`, whose
+ * host is the literal string `app`: deriving a socket URL from it yields `ws://app/...`, which resolves
+ * nowhere and fails in a way that reads exactly like the host refusing the connection — a wrong answer
+ * that costs an afternoon. Returning undefined lets the caller name the real cause instead.
+ *
+ * @param location - the page's location, or undefined when there is none.
+ * @returns the authority, or undefined when this page has no usable one of its own.
+ */
+export function pageAuthority(location: LocationLike | undefined): string | undefined {
+  if (location === undefined) return undefined
+  if (location.protocol !== 'http:' && location.protocol !== 'https:') return undefined
+  return location.host === '' ? undefined : location.host
+}
+
+/**
+ * Attach the capability token, when the host injected one.
+ *
+ * @param url - the socket URL.
+ * @param token - the injected token, or undefined on a host that injects none.
+ * @returns the URL to open.
+ */
+export function withToken(url: string, token: string | undefined): string {
+  if (token === undefined || token === '') return url
+  return `${url}?t=${encodeURIComponent(token)}`
 }
 
 /**
@@ -174,7 +218,7 @@ export interface ScopeLike {
   navigator?: { mediaDevices?: { getUserMedia(constraints: unknown): Promise<StreamLike> } }
   AudioContext?: new (options: { sampleRate: number }) => ContextLike
   WebSocket?: new (url: string) => SocketLike
-  __DSH_REALTIME_AUDIO__?: { readonly path?: string }
+  __DSH_REALTIME_AUDIO__?: InjectedRouteSettings
 }
 
 /**
@@ -285,8 +329,11 @@ export function createAudioClient(deps: ClientAudioDeps): ClientAudio {
 
   const start = async (): Promise<ClientAudioState> => {
     if (current.kind === 'live') return current
-    const url = socketUrl(deps.location, deps.injected?.path ?? DEFAULT_PATH)
-    if (url === undefined) return fail('this page has no location to open a socket against')
+    const route = socketUrl(deps.location, deps.injected?.path ?? DEFAULT_PATH, deps.injected?.authority)
+    if (route === undefined) {
+      return fail('no authority for the audio socket: this page has none of its own and the host injected none')
+    }
+    const url = withToken(route, deps.injected?.token)
     if (deps.getUserMedia === undefined) return fail('this page has no microphone API')
     if (deps.createAudioContext === undefined) return fail('this page has no audio API')
     if (deps.createSocket === undefined) return fail('this page has no WebSocket API')

package/src/index.ts

@@ -18,6 +18,14 @@ import type { Duplex } from 'node:stream'
 // Type-only: pulls the `Events` augmentation that declares the two audio events this package bridges.
 import type {} from 'dsh-realtime-agent'
 import { attachAudioSocket } from './bridge.ts'
+import {
+  createRouteToken,
+  routeAuthority,
+  routeInjectionRow,
+  tokenFromUrl,
+  verdictFor,
+  type InjectedGlobalRow,
+} from './injection.ts'
 import { createUpgradeAcceptor, rejectUpgrade } from './upgrade.ts'
 import {
   DEFAULT_MAX_CONNECTIONS,
@@ -57,6 +65,13 @@ interface WebServerLike {
     path: string
     handler: (req: IncomingMessage, socket: Duplex, head: Buffer) => void | Promise<void>
   }): () => void
+  /**
+   * The port actually listening — the OS-assigned value when the config asked for zero. Read at injection
+   * time rather than at boot, because an index render happens after the listen.
+   */
+  readonly listenedPort?: number
+  /** The configured bind host, so the page can be told an authority it can actually reach. */
+  readonly config?: { readonly host?: string }
 }
 
 /** The slice of the connection service that authenticates an upgrade. Structural for the same reason. */
@@ -69,8 +84,26 @@ export function apply(ctx: Context, config: RealtimeAudioWsConfig): void {
     const services = injected as unknown as { webServer: WebServerLike; connection: ConnectionLike }
     const acceptor = createUpgradeAcceptor(config.maxFrameBytes)
     const clients = new Set<AudioSocket>()
+    const token = createRouteToken()
+    // The injection event is declared by `@deepseek-ai/dsh-host-webserver`, which this package deliberately
+    // does not import: importing it would augment `Context` with a second declaration of `webServer` and
+    // turn the structural dependency above into a compile error. The name is cast at this one boundary.
+    const onInjection = ctx.on as unknown as (
+      name: string,
+      listener: (table: InjectedGlobalRow[]) => void,
+    ) => unknown
 
     ctx.effect(() => {
+      // The page is told where the route is and what to present. The web server gathers this table on every
+      // index render and every worker boot-payload request, so the row is built at emit time — the only
+      // moment the listening port is known for certain, since an index render follows the listen.
+      onInjection('webserver/index-inject', (table) => {
+        table.push(routeInjectionRow(
+          config.path,
+          routeAuthority(services.webServer.config?.host, services.webServer.listenedPort),
+          token,
+        ))
+      })
       const unregister = services.webServer.registerUpgrade({
         path: config.path,
         handler: (req, socket, head) => {
@@ -79,7 +112,16 @@ export function apply(ctx: Context, config: RealtimeAudioWsConfig): void {
           // microphone audio in and the agent's answers out. DSH's own transport asks the connection
           // service in exactly this position, so this route asks the same question rather than inventing a
           // second scheme that would drift from it.
-          const rejection = services.connection.requestRejection(req)
+          //
+          // The token is the one addition, and it is not a second scheme. The desktop app's page is served
+          // from `dsh-app://app`, so its requests to loopback are cross-site and the harness's
+          // `SameSite=Strict` cookie cannot travel; without the token that page is refused forever, however
+          // correct the rest of the client half is.
+          const rejection = verdictFor(
+            services.connection.requestRejection(req),
+            tokenFromUrl(req.url),
+            token,
+          )
           if (rejection !== undefined) {
             rejectUpgrade(socket, rejection)
             return

package/src/injection.ts

@@ -0,0 +1,132 @@
+/**
+ * The route's page-side settings: the row the host injects, and the credential check that lets the
+ * desktop app's renderer use the route at all.
+ *
+ * Two facts decide this file's shape.
+ *
+ * The first is that the harness web server gathers a structured *injection table* on every index render
+ * and every worker boot-payload request, by emitting `webserver/index-inject`; listeners append their
+ * rows and the rows are read fresh at emit time. That is a door built for plugins, which is why this
+ * package uses it rather than a raw string transform on the HTML.
+ *
+ * The second is a consequence of being a browser face inside the desktop app. That page's origin is
+ * `dsh-app://app`, and the harness's own auth cookie is `SameSite=Strict` and bound to the loopback
+ * authority — so a request from the app page to `127.0.0.1` is cross-site and carries no cookie. The
+ * connection service would therefore refuse the app's renderer, correctly and forever, no matter how
+ * right the rest of the client half is.
+ *
+ * A capability token — generated once per process, injected only into the page the host itself serves —
+ * is the credential that can travel. It is script-readable where the cookie is not, and that is a real
+ * weakening: it is the price of the app working at all. It authorises one route, on loopback, for the
+ * life of the process, and is worthless afterwards.
+ */
+
+import { randomBytes, timingSafeEqual } from 'node:crypto'
+
+/** Global the page reads its route settings from. Duplicated in the client half, which cannot import it. */
+export const INJECTED_KEY = '__DSH_REALTIME_AUDIO__'
+
+/** Query parameter carrying the capability token on an upgrade request. */
+export const TOKEN_PARAM = 't'
+
+/** A structured index-injection row of the kind this package contributes. */
+export interface InjectedGlobalRow {
+  readonly kind: 'global'
+  readonly name: string
+  readonly value: unknown
+}
+
+/**
+ * Where the client should open its socket, or undefined when the host is not listening yet.
+ *
+ * A wildcard bind is normalised to loopback because the page is on this machine: handing a client
+ * `0.0.0.0:port` asks it to connect to a name meaning "every interface", which resolves nowhere useful.
+ * An IPv6 literal is bracketed so the authority parses as a URL rather than as a host with a port.
+ *
+ * @param host - the configured bind host, as the web server reports it.
+ * @param port - the port actually listening — the OS-assigned value when the config asked for zero.
+ * @returns the authority (`host:port`), or undefined before the server is listening.
+ */
+export function routeAuthority(host: string | undefined, port: number | undefined): string | undefined {
+  if (port === undefined) return undefined
+  const name = host === undefined || host === '' || host === '0.0.0.0' || host === '::' ? '127.0.0.1' : host
+  return name.includes(':') ? `[${name}]:${String(port)}` : `${name}:${String(port)}`
+}
+
+/**
+ * One process-scoped capability token.
+ *
+ * 32 bytes, base64url, because the token travels in a URL query and base64url needs no escaping there.
+ */
+export function createRouteToken(): string {
+  return randomBytes(32).toString('base64url')
+}
+
+/**
+ * Read the token off an upgrade request's target.
+ *
+ * @param url - the request target as `node:http` reports it: pathname plus query.
+ * @returns the token, or undefined when absent or empty.
+ */
+export function tokenFromUrl(url: string | undefined): string | undefined {
+  if (url === undefined) return undefined
+  const query = url.indexOf('?')
+  if (query < 0) return undefined
+  const value = new URLSearchParams(url.slice(query + 1)).get(TOKEN_PARAM)
+  return value === null || value === '' ? undefined : value
+}
+
+/**
+ * Compare a presented token with this process's own, in constant time.
+ *
+ * Length is compared first because `timingSafeEqual` throws on buffers of different lengths, which would
+ * turn a probe into a crash. The length is not the secret; the value is.
+ *
+ * @param provided - the token the caller presented, if any.
+ * @param expected - this process's token.
+ * @returns whether the caller may be treated as this process's own page.
+ */
+export function tokenMatches(provided: string | undefined, expected: string): boolean {
+  if (provided === undefined) return false
+  const offered = Buffer.from(provided)
+  const own = Buffer.from(expected)
+  if (offered.length !== own.length) return false
+  return timingSafeEqual(offered, own)
+}
+
+/**
+ * The connection service's verdict, overridden by a valid token.
+ *
+ * DSH's own transport asks the connection service in this position, and this route asks the same question
+ * rather than inventing a second scheme that would drift from it. The token is the only addition, and it
+ * is not a second scheme: a caller that cannot carry the cookie at all — the app's renderer — may present
+ * the token the host injected into that very page instead.
+ *
+ * @param rejection - what the connection service said about this request.
+ * @param provided - the token on the request, if any.
+ * @param expected - this process's token.
+ * @returns the rejection to write, or undefined to accept the upgrade.
+ */
+export function verdictFor(
+  rejection: 401 | 403 | undefined,
+  provided: string | undefined,
+  expected: string,
+): 401 | 403 | undefined {
+  if (rejection === undefined) return undefined
+  return tokenMatches(provided, expected) ? undefined : rejection
+}
+
+/**
+ * The row the page reads, built at emit time.
+ *
+ * `value` is JSON-serialised by the web server, which escapes `<` so a value cannot close the script
+ * element early; an undefined `authority` is dropped by `JSON.stringify`, which is exactly the "this host
+ * injected no authority" case the client half names rather than guesses at.
+ */
+export function routeInjectionRow(
+  path: string,
+  authority: string | undefined,
+  token: string,
+): InjectedGlobalRow {
+  return { kind: 'global', name: INJECTED_KEY, value: { path, authority, token } }
+}