@claxedo/workspace-relay 0.6.0 → 0.8.0

package/dist/server.d.ts

@@ -1,6 +1,6 @@
 import { Hono } from "hono";
 import type { RuntimeAccessVerifierClaims, TokenVerifier } from "@claxedo/workspace-relay-protocol";
-import { type RelayClaimPair, type RelayJwtAlgorithm, type RelayKey, type RelayRole, type RuntimeAccessTokenClaims } from "./auth";
+import { type HostTunnelTokenClaims, type RelayClaimPair, type RelayJwtAlgorithm, type RelayKey, type RelayRole, type RuntimeAccessTokenClaims } from "./auth";
 import type { WorkspaceRelayDirectory } from "./directory";
 export type RelayHostPublicKey = {
     publicKey: CryptoKey | Uint8Array;
@@ -19,6 +19,49 @@ export type RuntimeAccessTokenActiveResult = {
     code: string;
     reason: string;
 };
+/**
+ * Both resolver clients — Bun (`main.ts`) and Worker (`worker.ts`) — read the
+ * control plane's JSON with these two parsers rather than asserting a type onto
+ * `Response.json()`. A half-built target used to travel all the way into
+ * routing and fail there as a confusing upstream error; it is now rejected at
+ * the one boundary that knows what the payload was supposed to be.
+ */
+export declare function parseWorkspaceRelayTarget(input: unknown): WorkspaceRelayTarget | undefined;
+export declare function parseRuntimeAccessTokenActiveResult(input: unknown): RuntimeAccessTokenActiveResult | undefined;
+/**
+ * `GET /internal/relay/host-generation?enrollmentId=` as the control plane
+ * answers it: the enrollment's current serving generation, or 404 for an
+ * enrollment it does not know (`undefined` here).
+ */
+export type HostGenerationResult = {
+    enrollmentId: string;
+    generation: number;
+    revoked: boolean;
+};
+export declare function parseHostGenerationResult(input: unknown): HostGenerationResult | undefined;
+export type HostGenerationResolverLookupOptions = {
+    headers: Record<string, string>;
+    fetch?: (url: URL, init: RequestInit) => Promise<Response>;
+    /** Deadline per lookup; past it the lookup rejects, which the relay grades as unavailable. */
+    timeoutMs?: number;
+};
+/**
+ * The HTTP lookup behind `resolveHostGeneration`, shared by the Bun process and
+ * the Worker. Only the control plane's own "enrollment not found" 404 resolves
+ * `undefined`; a bare 404 is a control plane without the route, and like every
+ * other non-ok status, a malformed body, or a hit deadline it throws so the
+ * relay refuses fenced tokens with a retryable 503 instead of grading them as
+ * unknown enrollments.
+ */
+export declare function createHostGenerationResolverLookup(url: string, options: HostGenerationResolverLookupOptions): HostGenerationLookup;
+/**
+ * The fence between two host tunnels for one identity. An incumbent that
+ * carries a generation is displaced only by a candidate at the same or a
+ * higher generation — never by a lower one, and never by a token minted
+ * without a generation. An incumbent without a generation is displaced by
+ * any candidate, which is the pre-fence "newest wins" order.
+ */
+export declare function hostTunnelIncumbentOutranks(incumbentGeneration: number | undefined, candidateGeneration: number | undefined): boolean;
 export type RevocationLookupArgs = {
     jti: string;
     workspaceId: string;
@@ -31,6 +74,24 @@ export type CachedRevocationOptions = {
     /** Clock injection for tests. Defaults to `Date.now`. */
     now?: () => number;
 };
+/**
+ * `generation` is the value the caller holds (a token's, a socket's). The
+ * cached client uses it to decide whether a cached answer may stand in for a
+ * fresh one; an uncached lookup ignores it. Resolves `undefined` for an
+ * unknown enrollment and THROWS when the control plane cannot be reached —
+ * the throw is the "unavailable" signal every consumer grades separately.
+ */
+export type HostGenerationLookupArgs = {
+    enrollmentId: string;
+    generation: number;
+};
+export type HostGenerationLookup = (args: HostGenerationLookupArgs) => Promise<HostGenerationResult | undefined>;
+export type CachedHostGenerationOptions = {
+    /** TTL in milliseconds for cached host-generation answers. Defaults to 10_000. */
+    ttlMs?: number;
+    /** Clock injection for tests. Defaults to `Date.now`. */
+    now?: () => number;
+};
 export type TargetLookupArgs = {
     workspaceId: string;
     hostId: string;
@@ -43,17 +104,19 @@ export type CachedTargetOptions = {
     now?: () => number;
 };
 export type WorkspaceRelayAuditEvent = {
-    action: "relay.request.accepted" | "relay.request.denied" | "relay.request.suppressed_summary" | "host_tunnel.connected" | "host_tunnel.disconnected";
+    action: "relay.request.accepted" | "relay.request.denied" | "relay.request.suppressed_summary" | "host_tunnel.connected" | "host_tunnel.disconnected" | "host_tunnel.denied";
     result: "allow" | "deny";
     reason?: string;
-    subject?: string;
+    actorId?: string;
+    actorKind?: "human" | "agent";
+    principalKind?: "user" | "service";
     role?: RelayRole;
     workspaceId?: string;
     hostId?: string;
     method: string;
     path: string;
     /**
-     * T16: only set on `relay.request.suppressed_summary` events. Counts the
+     * Only set on `relay.request.suppressed_summary` events. Counts the
      * number of `relay.request.accepted` audit events that were dropped by the
      * sampler in the previous flush interval.
      */
@@ -61,6 +124,13 @@ export type WorkspaceRelayAuditEvent = {
 };
 export type WorkspaceRelayAuthOptions = {
     runtimeAccessKey: RelayKey;
+    /**
+     * Serving-generation fence for host tunnels. Unset on desktop and
+     * self-hosted relays, where nothing asks the control plane: tokens without
+     * a generation are admitted newest-wins, tokens with one are refused
+     * `host_generation_unverifiable`.
+     */
+    resolveHostGeneration?: HostGenerationLookup;
     /**
      * Cache signature/introspection-verified Runtime Access Token claims by the
      * full token string. Revocation/active checks, role enforcement, and target
@@ -79,7 +149,7 @@ export type WorkspaceRelayAuthOptions = {
      * raw JWT codepath.
      *
      * This is the seam downstream users plug their own auth backend
-     * through (Clerk-issued tokens, OIDC introspection, custom keys, etc.).
+     * through (issuer-signed tokens, OIDC introspection, custom keys, etc.).
      * See `@claxedo/workspace-relay-protocol/token-verifier` for the
      * `HttpTokenVerifier` and `StaticTokenVerifier` reference impls.
      */
@@ -121,7 +191,7 @@ export type WorkspaceRelayRoutingOptions = {
 };
 export type WorkspaceRelayDrainOptions = {
     /**
-     * T9: when this returns true the relay reports unhealthy via `/health` and
+     * When this returns true the relay reports unhealthy via `/health` and
      * fast-paths every workspace request to a 503 (`relay_draining`) before
      * doing any auth or upstream work. Wired by `createWorkspaceRelayBun` to
      * the drain controller it exposes.
@@ -131,7 +201,7 @@ export type WorkspaceRelayDrainOptions = {
 export type WorkspaceRelayTelemetryOptions = {
     audit?: (event: WorkspaceRelayAuditEvent) => void | Promise<void>;
     /**
-     * T16: probability (0.0 – 1.0) at which `relay.request.accepted` audit
+     * Probability (0.0 – 1.0) at which `relay.request.accepted` audit
      * events are emitted to the user `audit` callback. Denies and tunnel
      * lifecycle events are never sampled. When unset, defaults to 1.0
      * (emit every accept). Suppressed accepts are aggregated into a periodic
@@ -139,21 +209,21 @@ export type WorkspaceRelayTelemetryOptions = {
      */
     auditAcceptSampleRate?: number;
     /**
-     * T16: how often (ms) the sampler emits a `relay.request.suppressed_summary`
+     * How often (ms) the sampler emits a `relay.request.suppressed_summary`
      * audit event with the count of suppressed accepts in the past interval.
      * Defaults to 60_000 (one minute). When sample rate is 1.0 no interval is
      * armed (nothing to flush). Exposed for tests.
      */
     auditFlushIntervalMs?: number;
     /**
-     * T16: random source for the sampler. Defaults to `Math.random`. Override
+     * Random source for the sampler. Defaults to `Math.random`. Override
      * for deterministic tests.
      */
     random?: () => number;
 };
 export type WorkspaceRelayMetricsOptions = {
     /**
-     * T31: bearer token required to access `GET /metrics` from non-loopback
+     * Bearer token required to access `GET /metrics` from non-loopback
      * remotes. When unset, the endpoint allows loopback callers only (using
      * `metricsRemoteAddress` to identify the caller). When set, every request
      * must present `Authorization: Bearer <metricsToken>` regardless of origin.
@@ -161,7 +231,7 @@ export type WorkspaceRelayMetricsOptions = {
      */
     metricsToken?: string;
     /**
-     * T31: returns the remote IP of the inbound `/metrics` request (used to
+     * Returns the remote IP of the inbound `/metrics` request (used to
      * gate access to the loopback when `metricsToken` is unset). When this is
      * also unset, `/metrics` fails closed. The Bun adapter wires this resolver
      * through `Bun.Server.requestIP`; other callers should set either this or
@@ -169,7 +239,7 @@ export type WorkspaceRelayMetricsOptions = {
      */
     metricsRemoteAddress?: (request: Request) => string | undefined;
     /**
-     * T31: optional providers used to assemble the `/metrics` response body. The
+     * Optional providers used to assemble the `/metrics` response body. The
      * fragmentation/slow-consumer counters live in the bun adapter's per-handler
      * telemetry, and the in-flight pending count lives on the drain controller.
      * `createWorkspaceRelayBun` wires these to make ops counters visible on
@@ -191,7 +261,7 @@ export type WorkspaceRelayMetricsSources = {
     drainPending?: () => number;
 };
 /**
- * T31: shape of the JSON body returned by `GET /metrics`. Exported so the
+ * Shape of the JSON body returned by `GET /metrics`. Exported so the
  * bun adapter and ops dashboards can type-narrow against it.
  */
 export type WorkspaceRelayMetrics = {
@@ -236,6 +306,41 @@ export type WorkspaceRelayTrace = WorkspaceRelayAuthorizeTrace & {
  * lag is bounded by the same TTL by design. Concurrent misses share one lookup.
  */
 export declare function createCachedRevocationClient(inner: RevocationLookup, options?: CachedRevocationOptions): RevocationLookup;
+/**
+ * Caches host-generation answers by enrollment id with the fence's own rules:
+ * a cached answer stands only while it is at least the caller's generation
+ * (equal admits; higher is a refusal that needs no fresh read), and a caller
+ * holding a HIGHER generation than the cache — or than the answer an in-flight
+ * lookup settles on — forces a refresh so a fresh `acquire` is never refused
+ * on a stale answer. Unknown enrollments and failures are not cached;
+ * concurrent misses share one lookup.
+ */
+export declare function createCachedHostGenerationClient(inner: HostGenerationLookup, options?: CachedHostGenerationOptions): HostGenerationLookup;
+export type HostTunnelGenerationDecision = {
+    ok: true;
+} | {
+    ok: false;
+    retryable: false;
+    code: "host_generation_superseded" | "host_generation_unknown" | "host_generation_unverifiable" | "host_enrollment_revoked" | "host_enrollment_unknown";
+    reason: string;
+} | {
+    ok: false;
+    retryable: true;
+    code: "host_generation_lookup_unavailable";
+    reason: string;
+};
+/**
+ * The one admission/re-check verdict both relay adapters apply to a host
+ * tunnel, on connect and on every registration update. A token without a
+ * generation is always `ok` — that is the pre-fence behaviour desktop and
+ * self-hosted relays keep. A token WITH a generation asserts a fence, so a
+ * relay composed without a resolver refuses it rather than admit what it
+ * cannot verify; that refusal is not retryable because the resolver is a
+ * property of the composition, not of the moment. `retryable` otherwise
+ * separates "the control plane said no" (the host must not simply reconnect)
+ * from "the control plane could not be asked" (it should).
+ */
+export declare function checkHostTunnelGeneration(lookup: HostGenerationLookup | undefined, claims: Pick<HostTunnelTokenClaims, "enrollment_id" | "generation">): Promise<HostTunnelGenerationDecision>;
 /**
  * Caches positive workspace target lookups by workspace+host. Missing targets
  * are only coalesced while in flight, not retained, so cold-start polling can
@@ -250,7 +355,7 @@ export type WorkspaceRelayForwardHeadersOptions = {
      * verbatim risks leaking sensitive session data to the host. Cloud-vm
      * workspaces sit behind a dedicated network boundary where session cookies
      * may legitimately be needed (e.g. workspace dashboards), so the default
-     * is to NOT strip cookies. T26.
+     * is to not strip cookies.
      */
     userHosted?: boolean;
     upstreamHeaders?: Record<string, string>;
@@ -262,13 +367,30 @@ export declare function workspaceRelayTargetUrl(target: WorkspaceRelayTarget, pa
 export declare function workspaceRelayForwardHeaders(input: Headers, relayHostToken: string, workspaceId: string, options?: WorkspaceRelayForwardHeadersOptions): Headers;
 export declare function workspaceRelayForwardRequestInit(request: Request, relayHostToken: string, workspaceId: string, options?: WorkspaceRelayForwardRequestInitOptions): RequestInit;
 /**
- * T16: dispose the sampler's periodic flush timer for a given options object.
+ * Dispose the sampler's periodic flush timer for a given options object.
  * Tests call this in cleanup so the bun process can exit.
  */
 export declare function disposeAuditSampler(options: WorkspaceRelayOptions): void;
 export declare function createWorkspaceRelayTrace(): WorkspaceRelayTrace;
 export declare function workspaceRelayServerTiming(trace: WorkspaceRelayTrace): string;
 export declare function workspaceRelayTimingResponse(response: Response, trace: WorkspaceRelayTrace): Response;
+/**
+ * Request headers a browser may send to the relay, for every adapter.
+ *
+ * ONE list, because there were three identical copies — `server.ts`,
+ * `cloudflare.ts` and `bun.ts` — and three copies of a list means the next
+ * header is added to two of them. A header missing from the copy that serves a
+ * given deployment does not degrade anything gracefully: the browser refuses to
+ * send the request at all, and the failure surfaces somewhere else entirely.
+ * The control plane's equivalent list is `BROWSER_ALLOWED_REQUEST_HEADERS` in
+ * `claxedo-server-core`; a header the app sends to BOTH must be in both.
+ *
+ * `Traceparent`/`Tracestate` are W3C Trace Context, carried from the browser
+ * through this relay to the laptop.
+ */
+export declare const RELAY_ALLOWED_REQUEST_HEADER_LIST: readonly ["Accept", "Authorization", "Content-Type", "Last-Event-ID", "Traceparent", "Tracestate", "X-Fetch-Bypass-Throttle", "X-Daytona-Skip-Preview-Warning", "X-Workspace-Id", "X-OpenCode-Directory", "X-Claxedo-Runner", "X-Claxedo-Model", "X-Claxedo-Draft-Id", "X-Claxedo-Binary"];
+/** The same list as a header value, for the adapters that write it directly. */
+export declare const RELAY_ALLOWED_REQUEST_HEADERS: string;
 export declare function authorizeWorkspaceRelayRequest(options: WorkspaceRelayOptions, request: Request, workspaceId: string, trace?: WorkspaceRelayAuthorizeTrace): Promise<{
     ok: true;
     request: AuthorizedWorkspaceRelayRequest;
@@ -280,13 +402,13 @@ export declare function authorizeWorkspaceRelayRequest(options: WorkspaceRelayOp
 export declare function forwardWorkspaceRelayRequest(request: Request, target: WorkspaceRelayTarget, relayHostToken: string, path: string, requestFetch: typeof fetch, timeoutMs: number, trace?: WorkspaceRelayAuthorizeTrace, originAllowed?: (origin: string) => boolean): Promise<Response>;
 export type WorkspaceRelayApp = Hono & {
     /**
-     * T16: clear the sampler's periodic flush timer. Tests must call this so
+     * Clear the sampler's periodic flush timer. Tests must call this so
      * `setInterval` doesn't keep the process alive after the test exits.
      */
     disposeAuditSampler(): void;
 };
 /**
- * T31: read the suppressed-accept counter for a given options object. Surfaced
+ * Read the suppressed-accept counter for a given options object. Surfaced
  * for the `/metrics` route handler. Returns 0 if no sampler state has been
  * created yet (no requests have been audit-sampled), which is the same value
  * an external observer would see.

package/dist/upstream-websocket.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The relay's upstream WebSocket constructor, and the one place that names it.
+ *
+ * A relay client socket is proxied to a workspace runtime over a second,
+ * outbound WebSocket that must carry the runtime's auth headers. Bun's global
+ * `WebSocket` really does accept `(url, { headers })` — but that shape is not
+ * expressible in this package's type program, for a reason that is worth
+ * writing down once rather than rediscovering at the call site:
+ *
+ * `bun-types` yields its own `WebSocket` declaration to `lib.dom` whenever
+ * `lib.dom` is loaded (`Bun.__internal.UseLibDomIfAvailable`), and `lib.dom`
+ * declares only the `(url, protocols)` overload — on a `declare var`, which
+ * cannot be augmented. So while `lib.dom` is in `tsconfig.json`, the real
+ * constructor is unreachable through the global's type.
+ *
+ * Dropping `lib.dom` (as `bench/tsconfig.json` does) fixes THIS and breaks more
+ * than it fixes: `bun-types`' `Request` constructor declares `string`,
+ * `RequestInit & { url }` and `Request` inputs and no `URL` input at all, which
+ * this package and its tests rely on.
+ *
+ * The assertion is therefore genuine — the type system cannot express the
+ * value — and it is confined to this module so that the lint override excusing
+ * it covers ~40 lines whose only job is this constructor, rather than blinding
+ * the 4,000-line `bun.ts` that consumes it.
+ */
+export type UpstreamWebSocketConstructor = {
+    new (url: string, options: Bun.WebSocketOptions): WebSocket;
+};
+/**
+ * The constructor used to open the upstream socket: the caller's override when
+ * one is supplied (tests inject fakes to drive open timeouts, pre-open queue
+ * limits and abnormal closes), otherwise Bun's global `WebSocket`.
+ */
+export declare function resolveUpstreamWebSocket(override?: UpstreamWebSocketConstructor): UpstreamWebSocketConstructor;

package/dist/user-hosted-forwarding.d.ts

@@ -0,0 +1,40 @@
+import type { RelayAccess } from "./auth";
+/**
+ * The canonical "is this relay target user-hosted" rule.
+ *
+ * A user-hosted workspace runs on the user's own laptop (backing:
+ * "local-worktree"); a cloud workspace runs on a dedicated cloud VM
+ * (backing: "cloud-vm"). `RelayAccess` has exactly these two members, so
+ * `access === "user-hosted"` and `access !== "cloud"` are equivalent — but
+ * spelling the check either way at each call site invites drift if a third
+ * access kind is ever added. Every caller that needs to branch on this
+ * (choosing a forwarding path, tagging a socket, deciding whether to strip
+ * Cookie) should go through this one predicate instead.
+ */
+export declare function isUserHostedTarget(target: {
+    access: RelayAccess;
+}): boolean;
+export type WorkspaceRelaySocketKind = "user-hosted-client" | "client";
+/**
+ * The socket-kind tag applied when a relay client is admitted against
+ * `target`. A user-hosted target is multiplexed over the host tunnel
+ * (`"user-hosted-client"`); a cloud target gets a direct upstream socket
+ * (`"client"`).
+ */
+export declare function socketKindFor(target: {
+    access: RelayAccess;
+}): WorkspaceRelaySocketKind;
+/**
+ * Privacy rule: never forward the browser's `Cookie` header into a
+ * user-hosted workspace. Its host process runs on the user's own laptop and
+ * may share a cookie jar with the browser (e.g. localhost dev tooling), so
+ * passing cookies through verbatim risks leaking session data to the host.
+ * Cloud-vm workspaces sit behind a dedicated network boundary where session
+ * cookies may legitimately be needed (e.g. workspace dashboards), so cloud
+ * targets pass `Cookie` through unchanged.
+ *
+ * Returns a new `Headers` instance; `headers` is not mutated.
+ */
+export declare function forwardHeadersFor(target: {
+    access: RelayAccess;
+}, headers: Headers): Headers;

package/dist/worker.d.ts

@@ -1,6 +1,7 @@
 import { type WorkspaceRelayDurableObjectNamespace, type WorkspaceRelayDurableObjectRoomOptions, type WorkspaceRelayDurableObjectSocket } from "./cloudflare";
 import type { RuntimeAccessTokenActiveResult, WorkspaceRelayTarget } from "./server";
-export type WorkspaceRelayWorkerEnv = Record<string, unknown> & {
+import { type HostGenerationLookup } from "./server";
+type WorkspaceRelayWorkerBindings = {
     WORKSPACE_RELAY_ROOM?: WorkspaceRelayDurableObjectNamespace;
     CLAXEDO_RELAY_RESOLVER_URL?: string;
     CLAXEDO_CENTRAL_URL?: string;
@@ -18,9 +19,17 @@ export type WorkspaceRelayWorkerEnv = Record<string, unknown> & {
     CLAXEDO_RELAY_TRACE_FORCE_SECRET?: string;
     CLAXEDO_RELAY_REVOCATION_CACHE_TTL_MS?: string;
     CLAXEDO_RELAY_TARGET_CACHE_TTL_MS?: string;
+    /**
+     * Absolute URL of the control plane's host-generation lookup. Unset derives
+     * `<resolver base>/host-generation` from the same base `/target` and
+     * `/revocation` are derived from.
+     */
+    CLAXEDO_RELAY_HOST_GENERATION_URL?: string;
+    CLAXEDO_RELAY_HOST_GENERATION_CACHE_TTL_MS?: string;
     CLAXEDO_APP_ORIGINS?: string;
     CLAXEDO_RELAY_ALLOWED_ORIGINS?: string;
 };
+export type WorkspaceRelayWorkerEnv = Record<string, unknown> & WorkspaceRelayWorkerBindings;
 type ResolverClient = {
     target(workspaceId: string, hostId: string): Promise<WorkspaceRelayTarget | undefined>;
     revocation(args: {
@@ -28,23 +37,54 @@ type ResolverClient = {
         workspaceId: string;
         hostId: string;
     }): Promise<RuntimeAccessTokenActiveResult>;
+    hostGeneration: HostGenerationLookup;
 };
 type ResolverFetch = (url: string | URL | Request, init?: RequestInit) => Promise<Response>;
 export declare function workspaceRelayWorkerResolverUrl(env: WorkspaceRelayWorkerEnv): string;
 export declare function workspaceRelayWorkerResolverClient(env: WorkspaceRelayWorkerEnv, fetcher?: ResolverFetch): ResolverClient;
 export declare function workspaceRelayDurableObjectOptions(env: WorkspaceRelayWorkerEnv): Promise<WorkspaceRelayDurableObjectRoomOptions>;
+/**
+ * The `DurableObjectState` workerd hands a room, modelled structurally like the
+ * rest of this package's Cloudflare surface (see `./cloudflare`) — this package
+ * deliberately carries no `@cloudflare/workers-types` dependency.
+ *
+ * Everything is optional because `cloudflare.ts` treats hibernation and alarms
+ * as capabilities to DETECT: an older runtime, or a harness standing in for
+ * one, may provide neither, and the room degrades rather than failing.
+ */
+export type WorkspaceRelayRoomState = {
+    acceptWebSocket?: (socket: WorkspaceRelayDurableObjectSocket) => void;
+    getWebSockets?: () => WorkspaceRelayDurableObjectSocket[];
+    storage?: {
+        getAlarm?: () => Promise<number | null>;
+        setAlarm?: (scheduledTime: number) => Promise<void>;
+        deleteAlarm?: () => Promise<void>;
+    };
+};
 export declare class WorkspaceRelayRoom {
     private state;
     private env;
     private room?;
     private loading?;
-    constructor(state: unknown, env: WorkspaceRelayWorkerEnv);
+    constructor(state: WorkspaceRelayRoomState, env: WorkspaceRelayWorkerEnv);
     private hibernation;
+    /**
+     * The DO alarm surface, used for the hibernation-safe revocation re-check.
+     * Alarms are the only periodic mechanism that survives hibernation, so this is
+     * what enforces revocation on an idle hibernated connection.
+     */
+    private alarms;
     private loadRoom;
     fetch(request: Request): Promise<Response>;
     webSocketMessage(socket: WorkspaceRelayDurableObjectSocket, message: string | ArrayBuffer): Promise<void>;
     webSocketClose(socket: WorkspaceRelayDurableObjectSocket, code: number, reason: string, wasClean: boolean): Promise<void>;
     webSocketError(socket: WorkspaceRelayDurableObjectSocket, error: unknown): Promise<void>;
+    /**
+     * Forwarded so the room's hibernation-safe revocation sweep actually runs. The
+     * DO has ONE alarm slot; the room only ever moves it earlier and never clears
+     * it, so adding another alarm user here stays safe.
+     */
+    alarm(): Promise<void>;
 }
 declare const _default: {
     fetch(request: Request, env: WorkspaceRelayWorkerEnv): Promise<Response>;

package/dist/workerd-fixture/binary-frame-worker.d.ts

@@ -0,0 +1,33 @@
+type FixtureSocket = {
+    accept: () => void;
+    send: (message: string | ArrayBuffer | Uint8Array) => void;
+    close: (code?: number, reason?: string) => void;
+    binaryType?: string;
+    addEventListener: (type: "message" | "close" | "error", listener: (event: {
+        data?: unknown;
+    }) => void) => void;
+};
+type FixtureState = {
+    acceptWebSocket: (socket: FixtureSocket) => void;
+};
+type FixtureNamespace = {
+    idFromName: (name: string) => unknown;
+    get: (id: unknown) => {
+        fetch: (request: Request) => Promise<Response>;
+    };
+};
+export declare class BinaryFrameRoom {
+    private state;
+    constructor(state: FixtureState);
+    fetch(request: Request): Promise<Response>;
+    /** Hibernation delivery path — survives eviction, so no listener exists. */
+    webSocketMessage(socket: FixtureSocket, message: unknown): Promise<void>;
+    webSocketClose(): Promise<void>;
+    private report;
+}
+declare const _default: {
+    fetch(request: Request, env: {
+        ROOM: FixtureNamespace;
+    }): Promise<Response>;
+};
+export default _default;

package/dist/workerd-fixture/boot.d.ts

@@ -0,0 +1,18 @@
+import { Miniflare, type MiniflareOptions } from "miniflare";
+/**
+ * Kill this process's workerd children outright. The `afterAll` replacement
+ * for `Miniflare#dispose()`, which must never be called (see header). Only
+ * direct children of this process whose command line names workerd can match,
+ * so nothing outside this test process is touched — and because `bun test`
+ * runs files sequentially, the only children alive when a file's `afterAll`
+ * runs are ones whose tests have already finished.
+ */
+export declare function reapWorkerd(): void;
+/**
+ * Boot workerd once and return the ready Miniflare. Call it exactly once per
+ * test file, from `beforeAll`, with a `workers` array hosting every
+ * configuration the file tests. Do NOT dispose the result — not in `afterAll`,
+ * not anywhere: disposal wedges every later boot in the process (see header).
+ * Tear down with `reapWorkerd()` in `afterAll` instead.
+ */
+export declare function bootWorkerd(options: MiniflareOptions): Promise<Miniflare>;

package/package.json

@@ -1,6 +1,4 @@
 {
-  "name": "@claxedo/workspace-relay",
-  "version": "0.6.0",
   "type": "module",
   "description": "Relay/tunnel server that routes authenticated traffic to workspace runtimes: JWT workspace tokens, header-stripping trust boundary, Bun and Cloudflare adapters",
   "license": "MIT",
@@ -19,11 +17,18 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "development": "./src/index.ts",
+      "bun": "./src/index.ts",
       "types": "./dist/index.d.ts",
-      "bun": "./dist/index.mjs",
-      "development": "./dist/index.mjs",
       "import": "./dist/index.mjs",
       "default": "./dist/index.mjs"
+    },
+    "./bun": {
+      "development": "./src/bun.ts",
+      "bun": "./src/bun.ts",
+      "types": "./dist/bun.d.ts",
+      "import": "./dist/bun.mjs",
+      "default": "./dist/bun.mjs"
     }
   },
   "bin": {
@@ -37,26 +42,36 @@
   "publishConfig": {
     "access": "public"
   },
+  "name": "@claxedo/workspace-relay",
+  "version": "0.8.0",
   "scripts": {
     "start": "bun run src/main.ts",
     "dev": "bun run --hot src/main.ts",
     "build": "tsx scripts/build.ts",
     "prepublishOnly": "npm run build",
     "typecheck": "tsc --noEmit -p tsconfig.json",
-    "test": "bun test src"
+    "typecheck:bench": "tsc --noEmit -p bench/tsconfig.json",
+    "test": "mkdir -p .artifacts/unit && node ../../scripts/test-deadline.mjs bun test src bench --path-ignore-patterns='**/relay-workerd-*' --path-ignore-patterns='**/bun.test.ts' --timeout 30000 --reporter=junit --reporter-outfile=.artifacts/unit/junit.xml && node ../../scripts/test-deadline.mjs bun test src/bun.test.ts --timeout 120000 --reporter=junit --reporter-outfile=.artifacts/unit/junit-bun-adapter.xml && node ../../scripts/test-deadline.mjs bun test src/relay-workerd-backpressure.test.ts src/relay-workerd-binary.test.ts --timeout 240000 --reporter=junit --reporter-outfile=.artifacts/unit/junit-workerd.xml",
+    "bench:gate": "bun bench/local-dry-run.ts",
+    "bench:gate:cf": "bun bench/cf-dev-smoke.ts"
   },
   "dependencies": {
-    "@claxedo/workspace-relay-protocol": "0.6.0",
-    "@sentry/bun": "10.64.0",
+    "@claxedo/helpers": "0.1.0",
+    "@claxedo/workspace-relay-protocol": "0.8.0",
     "hono": "4.10.7",
-    "jose": "6.0.11"
+    "jose": "6.0.11",
+    "posthog-node": "4.18.0"
   },
   "devDependencies": {
+    "@claxedo/sandbox-manager": "0.9.0",
+    "@daytona/sdk": "0.192.0",
     "@tsconfig/node-lts": "22.0.4",
     "@types/bun": "1.3.13",
     "esbuild": "0.25.12",
+    "miniflare": "4.20260722.0",
     "tsx": "4.22.3",
     "typescript": "catalog:",
-    "@daytona/sdk": "0.192.0"
+    "wrangler": "4.114.0",
+    "@cloudflare/workers-types": "catalog:"
   }
 }