@vibesdotdev/kernel-rpc 1.0.0-rc.3 → 1.0.0-rc.7

package/dist/transports/relay/broker/relay-broker.js

@@ -0,0 +1,1417 @@
+/**
+ * Relay broker — the per-host state machine between relay consumers and the
+ * daemon's outbound socket. One instance per machine, keyed by hostId.
+ *
+ * This is transport mechanics only (kernel-rpc). Durable Object custody,
+ * host enrollment, presence records and consumer admission policy stay with
+ * the composing app, injected through {@link RelayBrokerPorts}: the app's DO
+ * shell owns storage sockets' host bindings, `hostAdmission` fences daemon
+ * acceptance against the app's host records, `onPresence` records daemon
+ * reachability, and `report` receives the broker's operator events.
+ *
+ * CAPABILITY-TOKEN MODEL (iteration 2 hardening):
+ *
+ * A. __relay_handshake mints a crypto-random consumerId AND a secret session-token
+ *    per consumer. Both are returned to the relay client in the handshake response.
+ *    consumerId → sessionToken is stored in durable storage (survives hibernation).
+ *
+ * B. Every consumer call (rpc, stream-open, stream/write, stream/close) MUST carry
+ *    consumerId + session-token. The DO validates the pair FAIL-CLOSED: missing,
+ *    unknown consumerId, or token mismatch → 4xx. Never silently routed.
+ *
+ * C. Routes forward consumerId + session-token from the consumer request to the DO
+ *    (they are NOT dropped by the SvelteKit worker routes).
+ *
+ * D. channelId is DO-minted (random), stored as channelId → owning consumerId.
+ *    write/close validate channelId ownership against the validated consumerId,
+ *    fail-closed when consumerId absent.
+ *
+ * E. Per-consumer IsolatedConsumerTable on the daemon listen session (see
+ *    relay-listen-session.ts): refs are crypto-random; a ref from consumer X is
+ *    unresolvable for consumer Y. Binary frames require consumerId and are dropped
+ *    if the channel is not owned by that consumer.
+ *
+ * F. Empty methods set DENIES ALL (relay-listen-session.ts): the Proxy.get trap
+ *    and invokeRemote pre-send guard both treat size===0 as deny-all.
+ *
+ * G. Per-consumer reverse channels keyed by consumerId. Opening one NEVER evicts
+ *    another consumer's channel. reverse-reply requires consumerId+token validated.
+ *    Reverse callbacks cannot resolve a pending entry for a different consumer.
+ *
+ * H. Bounds: reverse streams capped at MAX_REVERSE_STREAMS; reconnect rate-limit
+ *    persisted to durable storage (survives hibernation); pending entries get
+ *    timeout + cleanup.
+ *
+ * §3.7 CANONICAL broker<->daemon WS protocol:
+ *   - Text frames are JSON ENVELOPES:
+ *       broker->daemon: { type:'rpc_request',  consumerId, request }
+ *       daemon->broker: { type:'rpc_response', consumerId, response }
+ *       reverse leg  : { type:'rpc_request',  consumerId, request: RpcInvoke }
+ *       keepalive    : { type:'keepalive' }
+ *                      (a daemon->broker keepalive is auto-answered AT THE EDGE
+ *                      with { type:'keepalive_ack' } without waking this DO —
+ *                      see KEEPALIVE_AUTO_RESPONSE_* below)
+ *   - Binary frames: [36-byte channelId][1-byte frameType][payload].
+ */
+import { RpcStreamSchema } from '@vibesdotdev/kernel-rpc';
+import { CapabilityError, CaughtFailureSchema, constantTimeEqual } from '@vibesdotdev/kernel';
+import { JsonValueSchema } from '@vibesdotdev/kernel/schemas/json';
+import { z } from 'zod/v4';
+import { RelayDaemonHandshakeResultSchema, RelayJsonMessageSchema, RelayConsumerCloseBodySchema, RelayConsumerClosedMessageSchema, RelayRpcRequestMessageSchema, RelayRpcResponseMessageSchema, encodeBinaryFrame, decodeBinaryFrame, encodeBase64, decodeBase64, daemonReadsVerifiedCaller, RELAY_DAEMON_CAPS_HEADER, RELAY_SSE_FRAME_EVENT, RELAY_VERIFIED_ORG_HEADER, RELAY_VERIFIED_USER_HEADER } from "../wire.js";
+const FRAME_DATA = 0x00;
+const FRAME_CLOSE = 0x01;
+/** Stream write/close bodies as presented; every field is checked before use. */
+const StreamWriteBodySchema = z.looseObject({
+    channelId: z.string().optional(),
+    consumerId: z.string().optional(),
+    sessionToken: z.string().optional(),
+    data: z.string().optional()
+});
+const StreamCloseBodySchema = z.looseObject({
+    channelId: z.string().optional(),
+    consumerId: z.string().optional(),
+    sessionToken: z.string().optional()
+});
+/** The verified caller a broker-internal request presents; only this Worker sets these headers. */
+function verifiedCallerFromHeaders(request) {
+    const userId = request.headers.get(RELAY_VERIFIED_USER_HEADER)?.trim();
+    if (!userId)
+        return null;
+    const caller = { userId };
+    const orgId = request.headers.get(RELAY_VERIFIED_ORG_HEADER)?.trim();
+    if (orgId)
+        caller.orgId = orgId;
+    return caller;
+}
+/** The capability names its admitted daemon; closed rows retain only close-retry authority until expiry. */
+const StoredCapabilityTokenSchema = z.object({
+    sessionToken: z.string().min(1), expiresAt: z.number().finite(),
+    daemonConnectionId: z.uuid(),
+    state: z.enum(['open', 'closing', 'closed']).optional(),
+    /** The user the handshake was authorized for (D1); every later request must be that user. */
+    userId: z.string().min(1).optional(),
+    /** The organization that user was authorized in (D1), for an organization-owned host. */
+    orgId: z.string().min(1).optional()
+});
+const ConsumerCloseInput = RelayConsumerCloseBodySchema;
+const SSE_FRAME_EVENT = RELAY_SSE_FRAME_EVENT;
+const KEEPALIVE_ALARM_MS = 90_000;
+// Durable flag: "a keepalive probe is outstanding, awaiting the daemon's echo."
+// See `alarm()` — a healthy-but-idle daemon gets ONE probe-and-wait cycle before
+// the DO declares it dead, instead of the alarm evicting on silence alone.
+const KEEPALIVE_PROBE_PENDING_KEY = 'relay:keepaliveProbePending';
+// Persisted keepalive due time. `keepaliveDueAt` is in-memory and is null after
+// a hibernation wake; this key lets alarm()/armAlarm restore the cadence.
+const KEEPALIVE_DUE_AT_KEY = 'relay:keepaliveDueAt';
+// Hibernation auto-response for the §3.7 keepalive frame. The EXACT text the
+// daemon emits (`JSON.stringify({ type: 'keepalive' })`, no whitespace) is
+// answered at the edge without waking this DO, and the runtime stamps the
+// socket (`getWebSocketAutoResponseTimestamp`) so `alarm()` can read liveness
+// instead of paying a webSocketMessage wake + two storage writes per frame.
+//
+// The reply is deliberately NOT another `{"type":"keepalive"}`: the daemon's
+// RelayListenSession echoes every keepalive it receives
+// (runtime-rpc/src/relay/relay-listen-session.ts), so a symmetric pair would
+// ping-pong between the edge and the daemon forever. `keepalive_ack` falls
+// through the daemon's dispatch untouched (unknown types are ignored, never
+// echoed). Protocol contract relied on here (framework #463 owns the client):
+//   1. the daemon sends the exact bytes KEEPALIVE_AUTO_RESPONSE_REQUEST;
+//   2. the daemon ignores KEEPALIVE_AUTO_RESPONSE_REPLY and never echoes it.
+const KEEPALIVE_AUTO_RESPONSE_REQUEST = JSON.stringify({ type: 'keepalive' });
+const KEEPALIVE_AUTO_RESPONSE_REPLY = JSON.stringify({ type: 'keepalive_ack' });
+// An auto-answered keepalive inside the last window is proof of life with no
+// probe; one inside TWO windows still vetoes an eviction (a probe that landed
+// late). Older than that, the socket is treated as silent.
+const KEEPALIVE_LIVENESS_WINDOW_MS = KEEPALIVE_ALARM_MS;
+const KEEPALIVE_EVICT_STALE_MS = 2 * KEEPALIVE_ALARM_MS;
+// Capability tokens are a backstop-expiry keyspace. The PRIMARY reclaim is
+// webSocketClose (a dropped daemon kills every consumer session for this host),
+// but a long-lived daemon with churning consumers never closes, so each token
+// also carries an expiry that the keepalive alarm + a mint-time opportunistic
+// sweep reclaim. 12h comfortably outlives any interactive relay session.
+const CAPABILITY_TOKEN_TTL_MS = 12 * 60 * 60_000;
+const MAX_REVERSE_STREAMS = 32;
+// Cap concurrent FORWARD (consumer→daemon) SSE channels too. Without this an
+// authenticated consumer could open unbounded GET /stream channels, each pinning
+// a ReadableStream controller + encoder in this per-host DO's heap.
+const MAX_FORWARD_STREAMS = 64;
+const MAX_RECONNECT_PER_MINUTE = 10;
+// Handshake, stream admission and close-control policy. Ordinary invokes follow
+// their consumer and native request lifetime, including long PTY exit waits.
+const PENDING_ENTRY_TIMEOUT_MS = 300_000;
+// Wake coalescing for a disconnected handshake. The per-host DO is the EXISTING
+// durable owner for this host, so the claim lives in its own storage — not a
+// new ledger, table, or queue. A dispatch marker younger than this window
+// suppresses a second provider wake attempt (a concurrent handshake, or a retry
+// that lands while the placement is still booting); a failed dispatch releases
+// it explicitly and an accepted daemon socket clears it.
+const WAKE_CLAIM_KEY = 'relay:wakeClaimedAt';
+const WAKE_CLAIM_TTL_MS = 90_000;
+/*
+ * Plain class (classic Durable Object constructor shape), NOT `extends DurableObject` from
+ * `cloudflare:workers`: every consumer talks to the stub via `stub.fetch()`,
+ * and the value import of `cloudflare:workers` cannot execute outside workerd.
+ * The composing app's DO shell constructs one broker per DO instance and
+ * delegates `fetch`/`alarm`/`webSocket*` to it.
+ */
+export class RelayBroker {
+    ctx;
+    ports;
+    constructor(ctx, ports) {
+        this.ctx = ctx;
+        this.ports = ports;
+        this.registerKeepaliveAutoResponse();
+    }
+    /** One operator event to the composing host, when it listens. */
+    report(event) {
+        this.ports.report?.(event);
+    }
+    /** Close a daemon socket; a failure is reported, never fatal to cleanup. */
+    closeSocket(ws, code, reason) {
+        try {
+            ws.close(code, reason);
+        }
+        catch (caught) {
+            this.report({ type: 'socket-close-failed', error: CaughtFailureSchema.parse(caught) });
+        }
+    }
+    /** Close one consumer stream; a failure is reported, never fatal to cleanup. */
+    closeStream(stream) {
+        try {
+            stream.controller.close();
+        }
+        catch (caught) {
+            this.report({ type: 'stream-close-failed', error: CaughtFailureSchema.parse(caught) });
+        }
+    }
+    /** Send one frame; false when the socket refused it (reported, never fatal). */
+    sendToSocket(ws, message) {
+        try {
+            ws.send(message);
+            return true;
+        }
+        catch (caught) {
+            this.report({ type: 'socket-send-failed', error: CaughtFailureSchema.parse(caught) });
+            return false;
+        }
+    }
+    /**
+     * Register the keepalive auto-response at construction (the Hibernation API
+     * pattern: re-applied on every DO wake). Guarded so the class still
+     * constructs where the API or the pair factory is absent.
+     */
+    registerKeepaliveAutoResponse() {
+        const createPair = this.ports.createAutoResponsePair;
+        if (!createPair)
+            return;
+        if (this.ctx.setWebSocketAutoResponse === undefined)
+            return;
+        try {
+            this.ctx.setWebSocketAutoResponse(createPair(KEEPALIVE_AUTO_RESPONSE_REQUEST, KEEPALIVE_AUTO_RESPONSE_REPLY));
+        }
+        catch (caught) {
+            this.report({
+                type: 'keepalive-auto-response-failed',
+                error: CaughtFailureSchema.parse(caught)
+            });
+        }
+    }
+    /**
+     * Latest edge-answered keepalive across the given sockets (ms epoch), or
+     * null when the runtime has none / does not expose the timestamp.
+     */
+    lastKeepaliveAnsweredAt(sockets) {
+        const read = this.ctx.getWebSocketAutoResponseTimestamp;
+        if (read === undefined)
+            return null;
+        let latest = null;
+        for (const ws of sockets) {
+            let at = null;
+            try {
+                at = read.call(this.ctx, ws);
+            }
+            catch (caught) {
+                this.report({
+                    type: 'keepalive-timestamp-failed',
+                    error: CaughtFailureSchema.parse(caught)
+                });
+                at = null;
+            }
+            const ms = at instanceof Date ? at.getTime() : null;
+            if (ms != null && Number.isFinite(ms) && (latest == null || ms > latest))
+                latest = ms;
+        }
+        return latest;
+    }
+    pending = new Map();
+    /** Next keepalive due time; multiplexed onto the single DO alarm with pending expiries. */
+    keepaliveDueAt = null;
+    /** The alarm currently scheduled, so armAlarm only pulls it earlier. */
+    nextAlarmAt = null;
+    streams = new Map();
+    /** G: per-consumer reverse channels; never evicts another consumer. */
+    reverseStreams = new Map();
+    hasDaemonSocket = false;
+    retired = false;
+    /**
+     * In-memory mirror of `WAKE_CLAIM_KEY`. The check-and-set below is
+     * synchronous, so two concurrent claims cannot both observe "unclaimed"
+     * across the storage read/write await boundary.
+     */
+    wakeClaimedAt = null;
+    async isRetired() {
+        const persisted = await this.ctx.storage.get('retired');
+        this.retired = this.retired || persisted === true;
+        return this.retired;
+    }
+    /** Persist the fence before fallible cleanup. Retrying never reopens admission. */
+    async retire(hostId) {
+        this.retired = true;
+        await this.ctx.storage.put('retired', true);
+        for (const ws of this.ctx.getWebSockets('daemon')) {
+            this.closeSocket(ws, 4003, 'host retired');
+        }
+        for (const { reject } of this.pending.values()) {
+            reject({ code: 'RPC_DISCONNECTED', message: 'host retired' });
+        }
+        this.pending.clear();
+        for (const channels of [this.streams, this.reverseStreams]) {
+            for (const stream of channels.values()) {
+                this.closeStream(stream);
+            }
+            channels.clear();
+        }
+        this.hasDaemonSocket = false;
+        this.wakeClaimedAt = null;
+        this.nextAlarmAt = null;
+        await this.persistKeepaliveDueAt(null);
+        await this.clearAllCapabilityTokens();
+        await this.ctx.storage.delete(WAKE_CLAIM_KEY);
+        await this.ctx.storage.deleteAlarm();
+        await this.writePresence(hostId, false);
+        return new Response(null, { status: 204 });
+    }
+    expireDuePendings(now) {
+        for (const [key, entry] of this.pending.entries()) {
+            if (entry.expiresAt === null || entry.expiresAt > now)
+                continue;
+            this.pending.delete(key);
+            if (entry.kind !== 'stream') {
+                entry.reject({ code: 'RPC_DISCONNECTED', message: 'request timed out' });
+            }
+        }
+    }
+    /** Daemon sockets that still accept frames (hibernation + test fakes). */
+    openDaemonSockets() {
+        return this.ctx.getWebSockets('daemon').filter((ws) => {
+            const readyState = ws.readyState;
+            if (readyState === 2 || readyState === 3)
+                return false;
+            // Test fakes record their close code instead of a readyState.
+            const closed = z
+                .object({ closeCode: z.number().nullable() })
+                .safeParse(ws);
+            return !closed.success || closed.data.closeCode == null;
+        });
+    }
+    socketForOwner(daemonConnectionId) {
+        return this.openDaemonSockets().find(socket => readSocketMeta(socket)?.connectionId === daemonConnectionId);
+    }
+    async socketForConsumer(consumerId) {
+        const stored = await this.readStoredToken(consumerId);
+        return stored ? this.socketForOwner(stored.daemonConnectionId) : undefined;
+    }
+    /**
+     * Restore the keepalive due time after hibernation. Memory is empty on a
+     * wake; storage survives; failing that, daemon sockets and their
+     * hibernation attachments still prove a probe cadence is required.
+     */
+    async resolvedKeepaliveDueAt(now, sockets) {
+        if (this.keepaliveDueAt == null) {
+            const persisted = z
+                .number()
+                .finite()
+                .safeParse(await this.ctx.storage.get(KEEPALIVE_DUE_AT_KEY));
+            if (persisted.success) {
+                this.keepaliveDueAt = persisted.data;
+            }
+        }
+        if (this.keepaliveDueAt != null)
+            return this.keepaliveDueAt;
+        const daemon = sockets ?? this.openDaemonSockets();
+        if (daemon.length === 0)
+            return null;
+        let earliest = null;
+        for (const ws of daemon) {
+            const meta = readSocketMeta(ws);
+            if (meta == null)
+                continue;
+            const due = meta.acceptedAt + KEEPALIVE_ALARM_MS;
+            if (earliest == null || due < earliest)
+                earliest = due;
+        }
+        // Hibernated daemon socket with no persisted due and no attachment:
+        // the alarm that woke us is the keepalive tick.
+        return earliest ?? now;
+    }
+    async persistKeepaliveDueAt(at) {
+        this.keepaliveDueAt = at;
+        if (at == null)
+            await this.ctx.storage.delete(KEEPALIVE_DUE_AT_KEY);
+        else
+            await this.ctx.storage.put(KEEPALIVE_DUE_AT_KEY, at);
+    }
+    async armAlarm() {
+        const now = Date.now();
+        const candidates = [];
+        const keepaliveAt = await this.resolvedKeepaliveDueAt(now);
+        if (keepaliveAt != null)
+            candidates.push(keepaliveAt);
+        for (const entry of this.pending.values()) {
+            if (entry.expiresAt !== null)
+                candidates.push(entry.expiresAt);
+        }
+        if (candidates.length === 0) {
+            this.nextAlarmAt = null;
+            await this.ctx.storage.deleteAlarm();
+            return;
+        }
+        const at = Math.min(...candidates);
+        if (this.nextAlarmAt != null && this.nextAlarmAt <= at)
+            return;
+        this.nextAlarmAt = at;
+        await this.ctx.storage.setAlarm(at);
+    }
+    waitForPending(key, { timeoutMs, kind = 'rpc', signal, daemonConnectionId }) {
+        const existing = this.pending.get(key)?.answer;
+        if (existing)
+            return existing;
+        const outcome = Promise.withResolvers();
+        const release = () => signal?.removeEventListener('abort', aborted);
+        const aborted = () => {
+            this.pending.delete(key);
+            release();
+            outcome.reject({ code: 'RPC_DISCONNECTED', message: 'consumer request closed' });
+        };
+        this.pending.set(key, {
+            answer: outcome.promise, kind, daemonConnectionId, expiresAt: timeoutMs === null ? null : Date.now() + timeoutMs,
+            resolve: response => { release(); outcome.resolve(response); },
+            reject: error => { release(); outcome.reject(error); }
+        });
+        if (signal?.aborted)
+            aborted();
+        else
+            signal?.addEventListener('abort', aborted, { once: true });
+        void this.armAlarm();
+        return outcome.promise;
+    }
+    trackStreamPending(key, daemonConnectionId) {
+        this.pending.set(key, {
+            daemonConnectionId,
+            resolve: () => undefined,
+            reject: () => undefined,
+            expiresAt: Date.now() + PENDING_ENTRY_TIMEOUT_MS,
+            kind: 'stream'
+        });
+        void this.armAlarm();
+    }
+    // -------------------------------------------------------------------------
+    // Wake claim (cloud fleet lifecycle)
+    // -------------------------------------------------------------------------
+    /**
+     * The per-host wake claim. A disconnected handshake asks here before any
+     * provider wake is dispatched: exactly one caller receives `dispatch: true`;
+     * concurrent or retry handshakes inside the claim window receive
+     * `dispatch: false` and must wait for an OBSERVED daemon socket instead of
+     * synthesizing readiness. A live socket answers `connected: true`.
+     */
+    async handleWakeClaim() {
+        if (this.ctx.getWebSockets('daemon').length > 0) {
+            return Response.json({ dispatch: false, connected: true });
+        }
+        const now = Date.now();
+        const persisted = await this.ctx.storage.get(WAKE_CLAIM_KEY);
+        const claimed = this.wakeClaimedAt;
+        if (claimed != null && now - claimed < WAKE_CLAIM_TTL_MS) {
+            return Response.json({ dispatch: false, connected: false });
+        }
+        if (persisted != null && now - persisted < WAKE_CLAIM_TTL_MS) {
+            this.wakeClaimedAt = persisted;
+            return Response.json({ dispatch: false, connected: false });
+        }
+        this.wakeClaimedAt = now;
+        await this.ctx.storage.put(WAKE_CLAIM_KEY, now);
+        return Response.json({ dispatch: true, connected: false });
+    }
+    /**
+     * A dispatch that produced no starting placement releases the claim, so the
+     * next handshake may retry immediately rather than waiting out the window.
+     */
+    async handleWakeResult(request) {
+        let raw;
+        try {
+            raw = JsonValueSchema.parse(await request.json());
+        }
+        catch (caught) {
+            this.report({ type: 'wake-result-invalid', error: CaughtFailureSchema.parse(caught) });
+            return new Response('invalid JSON', { status: 400 });
+        }
+        const body = z.object({ ok: z.unknown().optional() }).safeParse(raw);
+        if (!body.success || body.data.ok !== true) {
+            this.wakeClaimedAt = null;
+            await this.ctx.storage.delete(WAKE_CLAIM_KEY);
+        }
+        return new Response(null, { status: 204 });
+    }
+    // -------------------------------------------------------------------------
+    // Capability token management (A, B)
+    // Key: `token:<consumerId>` -> sessionToken
+    // -------------------------------------------------------------------------
+    tokenKey(consumerId) {
+        return `token:${consumerId}`;
+    }
+    async mintCapabilityToken(daemonConnectionId, caller) {
+        // Opportunistic reclaim: the keepalive alarm only fires when the daemon goes
+        // SILENT, so on a healthy long-lived daemon mint-time is the reliable trim
+        // point for expired consumer rows (mirrors the self-trimming reconnect window
+        // at recordReconnect). Without it, churning consumers leak permanent rows.
+        await this.sweepExpiredCapabilityTokens();
+        const consumerId = crypto.randomUUID();
+        const sessionToken = crypto.randomUUID();
+        const stored = {
+            sessionToken,
+            expiresAt: Date.now() + CAPABILITY_TOKEN_TTL_MS,
+            daemonConnectionId
+        };
+        if (caller) {
+            stored.userId = caller.userId;
+            if (caller.orgId)
+                stored.orgId = caller.orgId;
+        }
+        await this.ctx.storage.put(this.tokenKey(consumerId), stored);
+        return { consumerId, sessionToken };
+    }
+    /** Decode the owner record; malformed and obsolete rows cannot admit work. */
+    async readStoredToken(consumerId) {
+        const raw = await this.ctx.storage.get(this.tokenKey(consumerId));
+        const parsed = StoredCapabilityTokenSchema.safeParse(raw);
+        if (!parsed.success && raw !== undefined)
+            await this.ctx.storage.delete(this.tokenKey(consumerId));
+        return parsed.success ? parsed.data : null;
+    }
+    /**
+     * Validate (consumerId, sessionToken). FAIL-CLOSED: any missing/unknown/mismatch
+     * returns false. Constant-time comparison prevents timing attacks. An expired
+     * token is rejected AND pruned lazily (mirrors repo-coordinator.verifyToken).
+     */
+    async validateCapabilityToken(consumerId, sessionToken, allowClosing = false) {
+        if (!consumerId || !sessionToken || await this.isRetired())
+            return false;
+        const stored = await this.readStoredToken(consumerId);
+        if (!stored || (!allowClosing && stored.state && stored.state !== 'open'))
+            return false;
+        if (stored.expiresAt < Date.now()) {
+            await this.ctx.storage.delete(this.tokenKey(consumerId));
+            return false;
+        }
+        return !this.retired && constantTimeEqual(sessionToken, stored.sessionToken);
+    }
+    /**
+     * D1: a consumer pair acts only for the caller its handshake was authorized
+     * for. Another user holding the pair (with their own authority over this
+     * host) is refused, as is the same user admitted in a different
+     * organization; a pair minted before identity binding stays unbound.
+     */
+    async consumerUser(consumerId, request) {
+        const stored = await this.readStoredToken(consumerId);
+        if (!stored?.userId)
+            return { ok: true, caller: null };
+        const presented = verifiedCallerFromHeaders(request);
+        if (!presented || presented.userId !== stored.userId)
+            return { ok: false };
+        if (stored.orgId !== undefined && presented.orgId !== stored.orgId)
+            return { ok: false };
+        const caller = { userId: stored.userId };
+        if (stored.orgId)
+            caller.orgId = stored.orgId;
+        return { ok: true, caller };
+    }
+    async revokeCapabilityToken(consumerId) {
+        await this.ctx.storage.delete(this.tokenKey(consumerId));
+    }
+    /**
+     * Delete EVERY `token:<consumerId>` row for this host. A dropped daemon socket
+     * invalidates all consumer sessions (a consumer can't reach a daemon that's
+     * gone), so the capability keyspace is evicted wholesale on close rather than
+     * left to accumulate permanent rows nothing else reclaims.
+     */
+    async clearAllCapabilityTokens() {
+        const rows = await this.ctx.storage.list({ prefix: 'token:' });
+        for (const key of rows.keys()) {
+            await this.ctx.storage.delete(key);
+        }
+    }
+    /**
+     * Delete expired capability rows. Driven by the keepalive alarm and a mint-time
+     * opportunistic call so a long-lived daemon (where webSocketClose never fires)
+     * still self-trims. Legacy bare-string rows have no expiry and are left for the
+     * close-time clear.
+     */
+    async sweepExpiredCapabilityTokens() {
+        const now = Date.now();
+        const rows = await this.ctx.storage.list({ prefix: 'token:' });
+        for (const [key, raw] of rows) {
+            const stored = StoredCapabilityTokenSchema.safeParse(raw);
+            if (!stored.success || stored.data.expiresAt < now)
+                await this.ctx.storage.delete(key);
+        }
+    }
+    // ------------------------------------------------------------------
+    // Hibernation lifecycle callbacks
+    // ------------------------------------------------------------------
+    async webSocketMessage(ws, message) {
+        if (await this.isRetired())
+            return;
+        await this.persistKeepaliveDueAt(Date.now() + KEEPALIVE_ALARM_MS);
+        await this.armAlarm();
+        // ANY message is proof of life — including the echoed keepalive probe
+        // `alarm()` sends. Clear the pending-probe flag so the NEXT silent window
+        // gets a fresh probe-and-wait cycle rather than an immediate evict.
+        await this.ctx.storage.delete(KEEPALIVE_PROBE_PENDING_KEY);
+        if (this.retired)
+            return;
+        const textMessage = z.string().safeParse(message);
+        if (textMessage.success) {
+            let envelope;
+            try {
+                const parsed = RelayJsonMessageSchema.safeParse(JSON.parse(textMessage.data));
+                if (!parsed.success) {
+                    this.report({ type: 'daemon-envelope-invalid' });
+                    return;
+                }
+                envelope = parsed.data;
+            }
+            catch (caught) {
+                this.report({
+                    type: 'daemon-envelope-malformed',
+                    error: CaughtFailureSchema.parse(caught)
+                });
+                return;
+            }
+            if (envelope.type === 'keepalive') {
+                this.hasDaemonSocket = true;
+                return;
+            }
+            if (envelope.type === 'consumer_closed') {
+                const parsed = RelayConsumerClosedMessageSchema.safeParse(envelope);
+                if (!parsed.success)
+                    return;
+                const key = 'close:' + pendingKey(parsed.data.consumerId, parsed.data.response.id);
+                const pending = this.pending.get(key);
+                if (pending?.kind !== 'close' || pending.daemonConnectionId !== readSocketMeta(ws)?.connectionId)
+                    return;
+                this.pending.delete(key);
+                pending.resolve(parsed.data.response);
+                return;
+            }
+            if (envelope.type === 'rpc_response') {
+                // Route by consumerId (DO-issued, echoed by daemon). No extra token check:
+                // the daemon's consumerId came from the DO itself (we minted it).
+                const parsed = RelayRpcResponseMessageSchema.safeParse(envelope);
+                if (!parsed.success)
+                    return;
+                const { consumerId, response } = parsed.data;
+                const key = pendingKey(consumerId, String(response.id));
+                const pending = this.pending.get(key);
+                if (pending && pending.kind !== 'close' && pending.daemonConnectionId === readSocketMeta(ws)?.connectionId) {
+                    this.pending.delete(key);
+                    pending.resolve(response);
+                }
+                return;
+            }
+            if (envelope.type === 'rpc_request') {
+                // G: REVERSE LEG - route ONLY to the owning consumer's reverse channel.
+                const parsed = RelayRpcRequestMessageSchema.safeParse(envelope);
+                if (!parsed.success)
+                    return;
+                const consumerId = parsed.data.consumerId;
+                if (!consumerId)
+                    return; // fail-closed
+                const reverse = this.reverseStreams.get(consumerId);
+                if (reverse && reverse.daemonConnectionId === readSocketMeta(ws)?.connectionId) {
+                    try {
+                        reverse.controller.enqueue(reverse.encoder.encode(`event: reverse_invoke\ndata: ${JSON.stringify(envelope)}\n\n`));
+                    }
+                    catch (caught) {
+                        this.report({
+                            type: 'stream-enqueue-failed',
+                            error: CaughtFailureSchema.parse(caught)
+                        });
+                        this.reverseStreams.delete(consumerId);
+                    }
+                }
+                return;
+            }
+            return;
+        }
+        // Binary frame: E - validate channel ownership before routing.
+        const binaryMessage = z.instanceof(ArrayBuffer).safeParse(message);
+        if (!binaryMessage.success)
+            return;
+        const bytes = new Uint8Array(binaryMessage.data);
+        if (bytes.length === 0) {
+            this.hasDaemonSocket = true;
+            return;
+        }
+        const { channelId, frameType, payload } = decodeBinaryFrame(bytes);
+        const stream = this.streams.get(channelId);
+        if (!stream || stream.daemonConnectionId !== readSocketMeta(ws)?.connectionId)
+            return;
+        try {
+            const frameBytes = frameType === FRAME_CLOSE
+                ? new Uint8Array([FRAME_CLOSE])
+                : (() => {
+                    const out = new Uint8Array(1 + payload.length);
+                    out[0] = FRAME_DATA;
+                    out.set(payload, 1);
+                    return out;
+                })();
+            stream.controller.enqueue(stream.encoder.encode(`event: ${SSE_FRAME_EVENT}\ndata: ${encodeBase64(frameBytes)}\n\n`));
+            if (frameType === FRAME_CLOSE) {
+                this.closeStream(stream);
+                this.streams.delete(channelId);
+            }
+        }
+        catch (caught) {
+            this.report({
+                type: 'stream-enqueue-failed',
+                error: CaughtFailureSchema.parse(caught)
+            });
+            this.streams.delete(channelId);
+        }
+    }
+    async webSocketClose(ws, code, reason, wasClean) {
+        // Compute this FIRST. A reconnect ACCEPTS the replacement socket BEFORE the
+        // old one's close event fires, so "the daemon dropped" is only true when no
+        // other daemon socket is live. The host-level side effects below (keepalive
+        // alarm, presence row, capability keyspace) belong to the HOST, not to this
+        // socket — running them for a replaced socket deleted the new socket's
+        // alarm and flipped relay_reachable to 0 under a live daemon.
+        const liveDaemons = this.ctx.getWebSockets('daemon').filter((s) => s !== ws);
+        const replaced = liveDaemons.length > 0;
+        const meta = readSocketMeta(ws);
+        const hostId = meta?.hostId ?? (await this.ctx.storage.get('hostId'));
+        this.report({
+            type: 'daemon-socket-closed',
+            hostId: hostId ?? null,
+            code,
+            reason,
+            wasClean,
+            ageMs: meta ? Date.now() - meta.acceptedAt : null,
+            replaced,
+            liveDaemons: liveDaemons.length,
+            pending: this.pending.size,
+            streams: this.streams.size,
+            reverseStreams: this.reverseStreams.size
+        });
+        const daemonConnectionId = readSocketMeta(ws)?.connectionId;
+        for (const [key, pending] of this.pending) {
+            if (pending.daemonConnectionId !== daemonConnectionId)
+                continue;
+            this.pending.delete(key);
+            pending.reject({ code: 'RPC_DISCONNECTED', message: 'owning daemon socket closed' });
+        }
+        for (const channels of [this.streams, this.reverseStreams]) {
+            for (const [key, stream] of channels) {
+                if (stream.daemonConnectionId !== daemonConnectionId)
+                    continue;
+                this.closeStream(stream);
+                channels.delete(key);
+            }
+        }
+        if (replaced)
+            return;
+        // Per-HOST state: only when the last daemon socket is gone.
+        this.hasDaemonSocket = false;
+        this.nextAlarmAt = null;
+        await this.persistKeepaliveDueAt(null);
+        await this.ctx.storage.deleteAlarm();
+        // A dropped daemon socket invalidates every consumer session for this host,
+        // so evict the whole `token:` keyspace instead of leaking permanent rows.
+        await this.clearAllCapabilityTokens();
+        if (hostId)
+            await this.writePresence(hostId, false);
+    }
+    async webSocketError(ws, error) {
+        this.report({ type: 'daemon-socket-error', error: CaughtFailureSchema.parse(error) });
+    }
+    // ------------------------------------------------------------------
+    // Alarm handler
+    // ------------------------------------------------------------------
+    async alarm() {
+        if (await this.isRetired())
+            return;
+        const now = Date.now();
+        this.nextAlarmAt = null;
+        this.expireDuePendings(now);
+        // Reclaim expired capability rows on alarm — belt to the
+        // webSocketClose suspenders, and the reclaimer of last resort for a daemon
+        // that went silent (the alarm fires, sweeps, then closes the dead socket).
+        await this.sweepExpiredCapabilityTokens();
+        const sockets = this.openDaemonSockets();
+        const keepaliveAt = await this.resolvedKeepaliveDueAt(now, sockets);
+        const keepaliveDue = keepaliveAt != null && keepaliveAt <= now;
+        if (!keepaliveDue) {
+            await this.armAlarm();
+            return;
+        }
+        const hostId = (await this.ctx.storage.get('hostId')) ?? null;
+        if (sockets.length === 0) {
+            await this.ctx.storage.delete(KEEPALIVE_PROBE_PENDING_KEY);
+            await this.persistKeepaliveDueAt(null);
+            this.report({ type: 'keepalive-no-socket', hostId });
+            if (hostId)
+                await this.writePresence(hostId, false);
+            await this.armAlarm();
+            return;
+        }
+        // LIVENESS FROM THE EDGE. A daemon keepalive (today: its echo of the probe
+        // below; a client-initiated ping once framework #463 lands) is auto-answered
+        // without waking this DO, so it never reaches webSocketMessage — the
+        // runtime's per-socket auto-response timestamp is the primary proof of life.
+        const lastAnsweredAt = this.lastKeepaliveAnsweredAt(sockets);
+        const sinceAnsweredMs = lastAnsweredAt == null ? null : now - lastAnsweredAt;
+        if (sinceAnsweredMs != null && sinceAnsweredMs <= KEEPALIVE_LIVENESS_WINDOW_MS) {
+            await this.ctx.storage.delete(KEEPALIVE_PROBE_PENDING_KEY);
+            await this.persistKeepaliveDueAt(now + KEEPALIVE_ALARM_MS);
+            await this.armAlarm();
+            this.report({ type: 'keepalive-alive', hostId, sockets: sockets.length, sinceAnsweredMs });
+            return;
+        }
+        // PROBE BEFORE EVICT (§3.7 keepalive frame). The daemon's RelayListenSession
+        // already echoes `{type:'keepalive'}` the instant it receives one
+        // (runtime-rpc/src/relay/relay-listen-session.ts) — but nothing on this side
+        // ever SENT one, so a daemon idle for KEEPALIVE_ALARM_MS with no organic RPC
+        // traffic (the common case for a host with nothing queued) was evicted on
+        // silence alone, even though it was alive and would have answered. That
+        // forced a needless reconnect (and the daemon's connect loop always pays a
+        // ~1s backoff before redialing), repeating every idle window — the "relay
+        // socket closed" / "reconnecting" churn seen in fleet-daemon logs.
+        //
+        // Fix: on the FIRST silent window, send the probe and give the daemon one
+        // more full window to answer (webSocketMessage resets the alarm AND clears
+        // the pending flag on ANY reply, including this echo). Only a daemon that
+        // stays silent through a SECOND window in a row — i.e. doesn't even answer
+        // a direct ping — is actually gone.
+        const probePending = await this.ctx.storage.get(KEEPALIVE_PROBE_PENDING_KEY);
+        if (!probePending) {
+            await this.ctx.storage.put(KEEPALIVE_PROBE_PENDING_KEY, true);
+            let sent = 0;
+            for (const ws of sockets) {
+                if (this.sendToSocket(ws, KEEPALIVE_AUTO_RESPONSE_REQUEST))
+                    sent++;
+            }
+            await this.persistKeepaliveDueAt(now + KEEPALIVE_ALARM_MS);
+            await this.armAlarm();
+            this.report({ type: 'keepalive-probe-sent', hostId, sockets: sockets.length, sent, sinceAnsweredMs });
+            return;
+        }
+        await this.ctx.storage.delete(KEEPALIVE_PROBE_PENDING_KEY);
+        // Second silent window with a probe outstanding. The daemon's echo does NOT
+        // wake us (it is auto-answered), so consult the edge once more: an answer
+        // inside two windows means the socket is alive and the probe merely landed
+        // late — keep it. Only a socket with nothing answered beyond that is gone.
+        if (sinceAnsweredMs != null && sinceAnsweredMs <= KEEPALIVE_EVICT_STALE_MS) {
+            await this.persistKeepaliveDueAt(now + KEEPALIVE_ALARM_MS);
+            await this.armAlarm();
+            this.report({ type: 'keepalive-probe-answered', hostId, sockets: sockets.length, sinceAnsweredMs });
+            return;
+        }
+        this.report({ type: 'keepalive-evicting', hostId, sockets: sockets.length, sinceAnsweredMs, code: 4001 });
+        await this.persistKeepaliveDueAt(null);
+        for (const ws of sockets) {
+            this.closeSocket(ws, 4001, 'keepalive timeout');
+        }
+        if (hostId)
+            await this.writePresence(hostId, false);
+        await this.armAlarm();
+    }
+    // ------------------------------------------------------------------
+    // Internal fetch dispatch
+    // ------------------------------------------------------------------
+    async fetch(request) {
+        const url = new URL(request.url);
+        const action = url.pathname;
+        if (action === '/do/retire' && request.method === 'POST') {
+            const hostId = request.headers.get('x-relay-host-id');
+            if (!hostId)
+                return new Response('Missing host identity', { status: 400 });
+            return this.retire(hostId);
+        }
+        if (await this.isRetired())
+            return new Response('Host retired', { status: 410 });
+        if (action === '/do/relay-state' && request.method === 'GET') {
+            return Response.json({ connected: this.ctx.getWebSockets('daemon').length > 0 });
+        }
+        if (action === '/do/wake/claim' && request.method === 'POST') {
+            return this.handleWakeClaim();
+        }
+        if (action === '/do/wake/result' && request.method === 'POST') {
+            return this.handleWakeResult(request);
+        }
+        if (action === '/do/accept-daemon' && request.method === 'GET') {
+            return this.handleAcceptDaemon(request);
+        }
+        if (action === '/do/rpc' && request.method === 'POST') {
+            return this.handleRpc(request);
+        }
+        if (action === '/do/stream' && request.method === 'GET') {
+            return this.handleStream(url, request);
+        }
+        if (action === '/do/stream/write' && request.method === 'POST') {
+            return this.handleStreamWrite(request);
+        }
+        if (action === '/do/stream/close' && request.method === 'POST') {
+            return this.handleStreamClose(request);
+        }
+        return new Response('not found', { status: 404 });
+    }
+    // ------------------------------------------------------------------
+    // Accept daemon WS upgrade
+    // ------------------------------------------------------------------
+    async handleAcceptDaemon(request) {
+        const upgradeHeader = request.headers.get('Upgrade');
+        if (!upgradeHeader || upgradeHeader.toLowerCase() !== 'websocket') {
+            return new Response('Expected WebSocket upgrade', { status: 426 });
+        }
+        const hostId = request.headers.get('x-relay-host-id');
+        if (!hostId)
+            return new Response('Missing x-relay-host-id', { status: 400 });
+        // H: rate-limit reconnects (persisted across hibernation) — ENFORCED, not
+        // observational. A storm is rejected BEFORE displacing the live socket, so
+        // it cannot perpetually evict an authenticated daemon (DoS protection).
+        if (!(await this.recordReconnect())) {
+            return new Response('reconnect rate exceeded', { status: 429 });
+        }
+        // The outer request may have validated before retirement. Re-read at the
+        // accepting owner and fence an admission delayed behind a retirement call.
+        const admission = await this.ports.hostAdmission(hostId);
+        if (admission === 'missing')
+            return new Response('Host not found', { status: 404 });
+        if (admission === 'retired') {
+            await this.retire(hostId);
+            return new Response('Host retired', { status: 410 });
+        }
+        if (await this.isRetired())
+            return new Response('Host retired', { status: 410 });
+        const existing = this.ctx.getWebSockets('daemon');
+        for (const ws of existing) {
+            this.closeSocket(ws, 4000, 'replaced by new connection');
+        }
+        const { client, server } = this.ports.createSocketPair();
+        this.ctx.acceptWebSocket(server, ['daemon']);
+        const caps = (request.headers.get(RELAY_DAEMON_CAPS_HEADER) ?? '').split(',').filter((cap) => cap.length > 0);
+        try {
+            attachSocketMeta(server, { hostId, acceptedAt: Date.now(), connectionId: crypto.randomUUID(), caps });
+        }
+        catch (caught) {
+            this.closeSocket(server, 1011, 'daemon identity unavailable');
+            throw caught;
+        }
+        this.hasDaemonSocket = true;
+        // A live socket discharges the wake claim: a later disconnect is a fresh
+        // wake, not a coalesced retry of the one that just booted.
+        this.wakeClaimedAt = null;
+        void this.ctx.storage.delete(WAKE_CLAIM_KEY);
+        this.report({ type: 'daemon-accepted', hostId, replaced: existing.length });
+        void this.ctx.storage.put('hostId', hostId);
+        this.keepaliveDueAt = Date.now() + KEEPALIVE_ALARM_MS;
+        void this.ctx.storage.put(KEEPALIVE_DUE_AT_KEY, this.keepaliveDueAt);
+        void this.armAlarm();
+        // A fresh socket starts with no probe outstanding, even if the replaced
+        // connection had one in flight.
+        void this.ctx.storage.delete(KEEPALIVE_PROBE_PENDING_KEY);
+        void this.writePresence(hostId, true);
+        // The 101 upgrade init is a workerd extension of ResponseInit; the host's
+        // Response constructor reads `webSocket` from it at the edge.
+        const upgrade = { status: 101, webSocket: client };
+        // SAFETY: the pair's client socket is the host's own WebSocket behind the
+        // structural RelayBrokerSocket the port handed back.
+        return new Response(null, upgrade);
+    }
+    /**
+     * H: persist reconnect timestamps across hibernation AND enforce the cap.
+     * Returns false when the per-minute limit is exceeded so the caller rejects
+     * the connection rather than displacing the live socket. The over-limit
+     * attempt still counts toward the window (a sustained storm stays blocked).
+     */
+    async recordReconnect() {
+        const now = Date.now();
+        const windowStart = now - 60_000;
+        const timestamps = (await this.ctx.storage.get('reconnect_timestamps')) ?? [];
+        const recent = timestamps.filter((t) => t > windowStart);
+        recent.push(now);
+        await this.ctx.storage.put('reconnect_timestamps', recent);
+        if (recent.length > MAX_RECONNECT_PER_MINUTE) {
+            this.report({ type: 'reconnect-rate-exceeded', recentPerMinute: recent.length });
+            return false;
+        }
+        return true;
+    }
+    // ------------------------------------------------------------------
+    // Handle RPC: handshake mints tokens; all others validate FAIL-CLOSED.
+    // ------------------------------------------------------------------
+    async handleConsumerClose(input, request) {
+        const { consumerId, sessionToken, id } = input;
+        if (!(await this.validateCapabilityToken(consumerId, sessionToken, true)))
+            return tokenError();
+        const stored = await this.readStoredToken(consumerId);
+        if (!stored)
+            return tokenError();
+        if (stored.state === 'closed')
+            return Response.json({ id });
+        const socket = this.socketForOwner(stored.daemonConnectionId);
+        if (!socket)
+            return Response.json({ id, error: { code: 'RPC_DISCONNECTED', message: 'no daemon socket' } }, { status: 503 });
+        // Revoke normal calls before forwarding, retaining only authenticated close
+        // retry authority until the existing token expiry.
+        await this.ctx.storage.put(this.tokenKey(consumerId), { ...stored, state: 'closing' });
+        const key = 'close:' + pendingKey(consumerId, id);
+        const answer = this.waitForPending(key, { timeoutMs: PENDING_ENTRY_TIMEOUT_MS, kind: 'close', signal: request.signal, daemonConnectionId: stored.daemonConnectionId });
+        try {
+            socket.send(JSON.stringify({ type: 'consumer_close', consumerId, id }));
+            const response = await answer;
+            if (!response.error) {
+                await this.ctx.storage.put(this.tokenKey(consumerId), { ...stored, state: 'closed' });
+                const reverse = this.reverseStreams.get(consumerId);
+                if (reverse) {
+                    this.closeStream(reverse);
+                    this.reverseStreams.delete(consumerId);
+                }
+            }
+            return Response.json(response);
+        }
+        catch (caught) {
+            this.report({ type: 'consumer-close-failed', error: CaughtFailureSchema.parse(caught) });
+            const pending = this.pending.get(key);
+            this.pending.delete(key);
+            pending?.resolve({ id, error: { code: 'RPC_DISCONNECTED', message: 'consumer cleanup was not acknowledged' } });
+            return Response.json({ id, error: { code: 'RPC_DISCONNECTED', message: 'consumer cleanup was not acknowledged' } }, { status: 503 });
+        }
+    }
+    async handleRpc(request) {
+        let body;
+        try {
+            // SAFETY: every branch below re-validates the fields it uses (close
+            // input schema, capability token, handshake result) before acting.
+            body = (await request.json());
+        }
+        catch (caught) {
+            this.report({ type: 'rpc-body-invalid', error: CaughtFailureSchema.parse(caught) });
+            return new Response('invalid JSON', { status: 400 });
+        }
+        const close = ConsumerCloseInput.safeParse(body);
+        if (close.success)
+            return this.handleConsumerClose(close.data, request);
+        if (z.object({ type: z.literal('consumer_close') }).safeParse(body).success)
+            return new Response('invalid close control', { status: 400 });
+        // G: Reverse reply - validate capability token before forwarding down daemon socket.
+        const reverseReply = z
+            .looseObject({
+            type: z.literal('rpc_response'),
+            consumerId: z.string(),
+            response: RelayRpcResponseMessageSchema.shape.response,
+            sessionToken: z.string().optional()
+        })
+            .safeParse(body);
+        if (reverseReply.success) {
+            const rev = reverseReply.data;
+            if (!(await this.validateCapabilityToken(rev.consumerId, rev.sessionToken)) || this.retired) {
+                return tokenError();
+            }
+            const socket = await this.socketForConsumer(rev.consumerId);
+            if (socket) {
+                // Strip sessionToken - internal credential, never forwarded to daemon.
+                const forward = { type: 'rpc_response', consumerId: rev.consumerId, response: rev.response };
+                this.sendToSocket(socket, JSON.stringify(forward));
+            }
+            return new Response(null, { status: 202 });
+        }
+        // SAFETY: not a reverse reply, so the body is the consumer's RPC request;
+        // capability validation and the daemon's invoke pipeline re-validate it.
+        const rpcBody = body;
+        // A: __relay_handshake - the ONLY call that does NOT require a pre-existing token.
+        // It mints the capability pair and returns it to the consumer.
+        const handshakeFields = z
+            .looseObject({ method: z.string().optional(), id: z.string().optional() })
+            .safeParse(rpcBody);
+        if (rpcBody.verb === 'invoke' &&
+            handshakeFields.success &&
+            handshakeFields.data.method === '__relay_handshake') {
+            const socket = this.openDaemonSockets()[0];
+            if (!socket || !readSocketMeta(socket)) {
+                return Response.json({ error: { code: 'RPC_DISCONNECTED', message: 'no daemon socket' } }, { status: 503 });
+            }
+            const daemonMeta = readSocketMeta(socket);
+            const daemonConnectionId = daemonMeta.connectionId;
+            const verifiedCaller = verifiedCallerFromHeaders(request);
+            const capability = await this.mintCapabilityToken(daemonConnectionId, verifiedCaller);
+            if (this.retired) {
+                await this.revokeCapabilityToken(capability.consumerId);
+                return new Response('Host retired', { status: 410 });
+            }
+            const requestId = handshakeFields.data.id ?? crypto.randomUUID();
+            // Compound key (consumerId+requestId) — the response router matches on
+            // consumerId + response.id, and the daemon echoes id === requestId.
+            const handshakePendingKey = pendingKey(capability.consumerId, requestId);
+            const responsePromise = this.waitForPending(handshakePendingKey, { timeoutMs: PENDING_ENTRY_TIMEOUT_MS, signal: request.signal, daemonConnectionId });
+            const envelope = stampCaller({
+                type: 'rpc_request',
+                consumerId: capability.consumerId,
+                request: { ...rpcBody, id: requestId }
+            }, daemonMeta, verifiedCaller);
+            try {
+                socket.send(JSON.stringify(envelope));
+            }
+            catch (caught) {
+                this.report({ type: 'socket-send-failed', error: CaughtFailureSchema.parse(caught) });
+                this.pending.delete(handshakePendingKey);
+                await this.revokeCapabilityToken(capability.consumerId);
+                return Response.json({ error: { code: 'RPC_DISCONNECTED', message: 'daemon socket send failed' } }, { status: 503 });
+            }
+            try {
+                const response = await responsePromise;
+                if (this.retired)
+                    return new Response('Host retired', { status: 410 });
+                // A: normalize the handshake response for the relay client.
+                // The daemon's RelayListenSession returns result.v = { rootRef, consumerId }.
+                // connectRelay expects result.v = rootRef (string) and top-level consumerId+sessionToken.
+                const parsedRoot = RelayDaemonHandshakeResultSchema.safeParse(response.result?.t === 'json' ? response.result.v : undefined);
+                if (!parsedRoot.success || parsedRoot.data.consumerId !== capability.consumerId) {
+                    await this.revokeCapabilityToken(capability.consumerId);
+                    return Response.json({ error: { code: 'RPC_DISCONNECTED', message: 'invalid daemon handshake' } }, { status: 503 });
+                }
+                const rootRef = parsedRoot.data.rootRef;
+                // Return normalized response: result.v = rootRef string, plus capability pair.
+                const normalizedResponse = {
+                    ...response,
+                    result: { t: 'json', v: rootRef }
+                };
+                return Response.json({
+                    ...normalizedResponse,
+                    consumerId: capability.consumerId,
+                    sessionToken: capability.sessionToken
+                });
+            }
+            catch (caught) {
+                this.report({ type: 'handshake-failed', error: CaughtFailureSchema.parse(caught) });
+                await this.revokeCapabilityToken(capability.consumerId);
+                // Pending rejections are RelayPendingRejection records; anything else
+                // is described without its value.
+                const rejection = z
+                    .object({ code: z.string(), message: z.string() })
+                    .safeParse(caught);
+                return Response.json({
+                    error: rejection.success
+                        ? rejection.data
+                        : { code: 'RPC_DISCONNECTED', message: 'handshake failed' }
+                }, { status: 503 });
+            }
+        }
+        // B: All other RPC calls require a valid capability token. FAIL-CLOSED.
+        const { consumerId, sessionToken } = rpcBody;
+        if (!(await this.validateCapabilityToken(consumerId, sessionToken)) || this.retired) {
+            return tokenError();
+        }
+        const consumerUser = await this.consumerUser(consumerId, request);
+        if (!consumerUser.ok)
+            return consumerUserMismatch();
+        const socket = await this.socketForConsumer(consumerId);
+        if (!socket) {
+            return Response.json({ error: { code: 'RPC_DISCONNECTED', message: 'no daemon socket' } }, { status: 503 });
+        }
+        const rpcPendingKey = pendingKey(consumerId, String(rpcBody.id));
+        if (this.pending.has(rpcPendingKey))
+            return Response.json({ id: rpcBody.id,
+                error: { code: 'RPC_INVOKE_FAILED', message: 'request id already in use' } }, { status: 409 });
+        const responsePromise = this.waitForPending(rpcPendingKey, { timeoutMs: null, signal: request.signal, daemonConnectionId: readSocketMeta(socket).connectionId });
+        try {
+            // Strip internal credentials before forwarding to daemon.
+            const { consumerId: _cid, sessionToken: _st, ...forwardRequest } = rpcBody;
+            const envelope = stampCaller({
+                type: 'rpc_request',
+                consumerId: consumerId,
+                // SAFETY: rpcBody minus its credential fields is the consumer's own
+                // RpcRequest; the daemon's invoke pipeline re-validates it.
+                request: forwardRequest
+            }, readSocketMeta(socket), consumerUser.caller);
+            socket.send(JSON.stringify(envelope));
+        }
+        catch (caught) {
+            this.report({ type: 'socket-send-failed', error: CaughtFailureSchema.parse(caught) });
+            this.pending.delete(rpcPendingKey);
+            return Response.json({ error: { code: 'RPC_DISCONNECTED', message: 'daemon socket send failed' } }, { status: 503 });
+        }
+        try {
+            const response = await responsePromise;
+            return Response.json(response);
+        }
+        catch (caught) {
+            this.report({ type: 'request-failed', error: CaughtFailureSchema.parse(caught) });
+            const rejection = z
+                .object({ code: z.string(), message: z.string() })
+                .safeParse(caught);
+            return Response.json({
+                error: rejection.success
+                    ? rejection.data
+                    : { code: 'RPC_DISCONNECTED', message: 'request failed' }
+            }, { status: 503 });
+        }
+    }
+    // ------------------------------------------------------------------
+    // Stream open: DO-mints channelId (D); capability validation (B, G).
+    // ------------------------------------------------------------------
+    async handleStream(url, request) {
+        const isReverse = url.searchParams.get('reverse') === '1';
+        const consumerId = url.searchParams.get('consumerId') ?? undefined;
+        const sessionToken = url.searchParams.get('sessionToken') ?? undefined;
+        // B: validate capability token FAIL-CLOSED.
+        if (!(await this.validateCapabilityToken(consumerId, sessionToken)) || this.retired) {
+            return tokenError();
+        }
+        const consumerUser = await this.consumerUser(consumerId, request);
+        if (!consumerUser.ok)
+            return consumerUserMismatch();
+        const streamCaller = consumerUser.caller;
+        const socket = await this.socketForConsumer(consumerId);
+        const daemonConnectionId = socket && readSocketMeta(socket)?.connectionId;
+        if (!socket || !daemonConnectionId)
+            return Response.json({ error: { code: 'RPC_DISCONNECTED', message: 'owning daemon is unavailable' } }, { status: 503 });
+        // G: per-consumer reverse stream channel.
+        if (isReverse) {
+            if (this.reverseStreams.size >= MAX_REVERSE_STREAMS) {
+                return Response.json({ error: { code: 'RPC_LIMIT', message: 'reverse stream limit reached' } }, { status: 429 });
+            }
+            const encoder = new TextEncoder();
+            let controller;
+            const stream = new ReadableStream({
+                start: (ctrl) => {
+                    controller = ctrl;
+                    ctrl.enqueue(encoder.encode(': open\n\n'));
+                    // G: per-consumer slot; never evicts another consumer.
+                    this.reverseStreams.set(consumerId, { controller, encoder, consumerId: consumerId, daemonConnectionId });
+                },
+                cancel: () => {
+                    this.reverseStreams.delete(consumerId);
+                }
+            });
+            return new Response(stream, {
+                status: 200,
+                headers: {
+                    'content-type': 'text/event-stream',
+                    'cache-control': 'no-cache',
+                    connection: 'keep-alive'
+                }
+            });
+        }
+        // Bound forward channels per host (mirrors the reverse-stream cap above).
+        if (this.streams.size >= MAX_FORWARD_STREAMS) {
+            return Response.json({ error: { code: 'RPC_LIMIT', message: 'forward stream limit reached' } }, { status: 429 });
+        }
+        // D: DO-minted channelId (not client-supplied).
+        if (!socket) {
+            return Response.json({ error: { code: 'RPC_DISCONNECTED', message: 'no daemon socket' } }, { status: 503 });
+        }
+        const channelId = crypto.randomUUID(); // D: DO-minted
+        const encoder = new TextEncoder();
+        let controller;
+        const stream = new ReadableStream({
+            start: (ctrl) => {
+                controller = ctrl;
+                ctrl.enqueue(encoder.encode(': open\n\n'));
+                // D: store channelId -> consumerId ownership.
+                this.streams.set(channelId, { controller, encoder, consumerId: consumerId, daemonConnectionId });
+                const ref = url.searchParams.get('ref');
+                const channel = url.searchParams.get('channel');
+                const streamReq = RpcStreamSchema.parse({ verb: 'stream', id: channelId, ref, channel });
+                const envelope = stampCaller({
+                    type: 'rpc_request',
+                    consumerId: consumerId,
+                    request: streamReq
+                }, readSocketMeta(socket), streamCaller);
+                // H: pending entry with alarm-driven timeout cleanup. Keyed by
+                // consumerId+channelId (the stream-open's id IS the channelId) so
+                // concurrent streams/RPCs from the same consumer do not collide.
+                const streamPendingKey = pendingKey(consumerId, channelId);
+                this.trackStreamPending(streamPendingKey, daemonConnectionId);
+                try {
+                    socket.send(JSON.stringify(envelope));
+                }
+                catch (caught) {
+                    this.report({
+                        type: 'stream-open-send-failed',
+                        error: CaughtFailureSchema.parse(caught)
+                    });
+                    this.pending.delete(streamPendingKey);
+                }
+            },
+            cancel: () => {
+                this.streams.delete(channelId);
+                // H: a consumer that opens then immediately drops the SSE connection
+                // must not leak its pending entry. MAX_FORWARD_STREAMS frees the
+                // stream slot on cancel, so it does NOT rate-limit open/cancel
+                // cycling — without this cleanup each cycle orphans a pending row,
+                // growing the per-host DO heap unbounded.
+                // streamPendingKey is recomputable from the same (consumerId,
+                // channelId) used at open.
+                this.pending.delete(pendingKey(consumerId, channelId));
+            }
+        });
+        // D: return DO-minted channelId in header so the relay client uses it.
+        return new Response(stream, {
+            status: 200,
+            headers: {
+                'content-type': 'text/event-stream',
+                'cache-control': 'no-cache',
+                connection: 'keep-alive',
+                'x-relay-channel-id': channelId
+            }
+        });
+    }
+    // ------------------------------------------------------------------
+    // Stream write: validate capability + channel ownership (B, D).
+    // ------------------------------------------------------------------
+    async handleStreamWrite(request) {
+        const parsedBody = StreamWriteBodySchema.safeParse(await request.json());
+        const { channelId, consumerId, sessionToken, data } = parsedBody.success
+            ? parsedBody.data
+            : { channelId: undefined, consumerId: undefined, sessionToken: undefined, data: undefined };
+        // B: validate capability token FAIL-CLOSED.
+        if (!(await this.validateCapabilityToken(consumerId, sessionToken)) || this.retired) {
+            return tokenError();
+        }
+        // D1: a bound pair writes only for its authorized caller.
+        if (consumerId && !(await this.consumerUser(consumerId, request)).ok)
+            return consumerUserMismatch();
+        // D: validate channelId + consumerId present.
+        if (!channelId || !consumerId) {
+            return new Response(JSON.stringify({ error: { code: 'RPC_UNAUTHENTICATED', message: 'missing channelId or consumerId' } }), { status: 400, headers: { 'content-type': 'application/json' } });
+        }
+        const ch = this.streams.get(channelId);
+        // Unknown channel: best-effort 202.
+        if (!ch)
+            return new Response(null, { status: 202 });
+        // D: ownership check FAIL-CLOSED.
+        if (ch.consumerId !== consumerId) {
+            return new Response(JSON.stringify({ error: { code: 'RPC_FORBIDDEN', message: 'channel not owned by this consumer' } }), { status: 403, headers: { 'content-type': 'application/json' } });
+        }
+        const socket = await this.socketForConsumer(consumerId);
+        if (socket && data !== undefined) {
+            this.sendToSocket(socket, encodeBinaryFrame(channelId, FRAME_DATA, decodeBase64(data)));
+        }
+        return new Response(null, { status: 202 });
+    }
+    // ------------------------------------------------------------------
+    // Stream close: validate capability + channel ownership (B, D).
+    // ------------------------------------------------------------------
+    async handleStreamClose(request) {
+        const parsedBody = StreamCloseBodySchema.safeParse(await request.json());
+        const { channelId, consumerId, sessionToken } = parsedBody.success
+            ? parsedBody.data
+            : { channelId: undefined, consumerId: undefined, sessionToken: undefined };
+        // B: validate capability token FAIL-CLOSED.
+        if (!(await this.validateCapabilityToken(consumerId, sessionToken)) || this.retired) {
+            return tokenError();
+        }
+        // D1: a bound pair closes only for its authorized caller.
+        if (consumerId && !(await this.consumerUser(consumerId, request)).ok)
+            return consumerUserMismatch();
+        // D: validate channelId + consumerId present.
+        if (!channelId || !consumerId) {
+            return new Response(JSON.stringify({ error: { code: 'RPC_UNAUTHENTICATED', message: 'missing channelId or consumerId' } }), { status: 400, headers: { 'content-type': 'application/json' } });
+        }
+        const ch = this.streams.get(channelId);
+        if (ch && ch.consumerId !== consumerId) {
+            // D: ownership check FAIL-CLOSED.
+            return new Response(JSON.stringify({ error: { code: 'RPC_FORBIDDEN', message: 'channel not owned by this consumer' } }), { status: 403, headers: { 'content-type': 'application/json' } });
+        }
+        if (ch) {
+            this.closeStream(ch);
+            this.streams.delete(channelId);
+        }
+        const socket = await this.socketForConsumer(consumerId);
+        if (socket) {
+            this.sendToSocket(socket, encodeBinaryFrame(channelId, FRAME_CLOSE));
+        }
+        return new Response(null, { status: 202 });
+    }
+    // ------------------------------------------------------------------
+    // Presence write
+    // ------------------------------------------------------------------
+    async writePresence(hostId, reachable) {
+        try {
+            await this.ports.onPresence?.(hostId, reachable);
+        }
+        catch (caught) {
+            this.report({ type: 'presence-write-failed', error: CaughtFailureSchema.parse(caught) });
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Hibernation-persistent daemon identity: capabilities and acknowledgements bind to this socket generation. */
+const DaemonSocketMetaSchema = z.object({
+    hostId: z.string().min(1), acceptedAt: z.number().finite(), connectionId: z.uuid(),
+    /** What the daemon declared it reads (`caps`); an older attachment declared nothing. */
+    caps: z.array(z.string()).default([])
+});
+function attachSocketMeta(ws, meta) {
+    const socket = ws;
+    if (!socket.serializeAttachment)
+        throw new CapabilityError('Daemon socket has no durable identity attachment.', 'UNAVAILABLE', {
+            reason: 'rpc-daemon-identity-unavailable'
+        });
+    socket.serializeAttachment(meta);
+}
+function readSocketMeta(ws) {
+    const socket = ws;
+    if (!socket.deserializeAttachment)
+        return null;
+    const parsed = DaemonSocketMetaSchema.safeParse(socket.deserializeAttachment());
+    return parsed.success ? parsed.data : null;
+}
+/**
+ * A forwarded request frame with the consumer's verified user as `caller`, for a
+ * daemon that declared it reads one. An older daemon parses frames strictly and
+ * would refuse the field, so it gets the frame unstamped.
+ */
+function stampCaller(envelope, daemon, caller) {
+    if (!caller || !daemon || !daemonReadsVerifiedCaller(daemon.caps))
+        return envelope;
+    const stamped = caller.orgId
+        ? { userId: caller.userId, orgId: caller.orgId }
+        : { userId: caller.userId };
+    return { ...envelope, caller: stamped };
+}
+/** A consumer pair presented by a user other than the one it was minted for. */
+function consumerUserMismatch() {
+    return Response.json({ error: { code: 'RPC_UNAUTHENTICATED', message: 'this relay consumer belongs to another user' } }, { status: 403 });
+}
+/** Standard capability-token rejection response. */
+function tokenError() {
+    return new Response(JSON.stringify({
+        error: { code: 'RPC_UNAUTHENTICATED', message: 'invalid or missing capability token' }
+    }), { status: 401, headers: { 'content-type': 'application/json' } });
+}
+/**
+ * Pending entries are keyed by consumerId + the request/channel id, NOT by
+ * consumerId alone, so two concurrent in-flight calls from the SAME consumer
+ * do not overwrite each other's resolver. The daemon echoes the id
+ * (response.id === the request id; a stream-open uses the channelId as its id),
+ * so the broker re-derives the identical key when routing the response.
+ */
+function pendingKey(consumerId, id) {
+    return `${consumerId}:${id}`;
+}
+//# sourceMappingURL=relay-broker.js.map