@claxedo/workspace-relay 0.10.1 → 0.10.3

package/README.md

@@ -34,7 +34,7 @@ signed identity to match the current ready lease; otherwise it returns 401
 
 Target lookups are keyed by workspace, host and routing identity. A resolved
 cloud or host-tunnel target is kept for `CLAXEDO_RELAY_TARGET_CACHE_TTL_MS`
-(10 s), the same lag the revocation cache allows; a workspace still starting is
+(30 s), the same lag the revocation cache allows; a workspace still starting is
 asked about on every request. A `durable-object` target is kept for 30 minutes,
 the longest life of a Runtime Access Token, because the host id names the
 session's object and the object never moves; revocation is still asked about
@@ -52,10 +52,25 @@ relay implements it by calling the control plane or an equivalent
 authority on every new HTTP request and WebSocket upgrade. A false result
 rejects before forwarding to the host.
 
-Long-lived relayed sockets are authorized at establishment time. Already-open
-SSE, PTY, and WebSocket streams may live until normal close, reconnect, relay
-drain, host disconnect, or process restart. If immediate stream revocation is a
-requirement, the control plane must also close the session/runtime channel.
+The answer is held for 30 s (`CLAXEDO_RELAY_REVOCATION_CACHE_TTL_MS`), which is
+the bound on how late a revocation is seen: no byte is forwarded on an answer
+older than that.
+
+- **A request** is checked when it arrives.
+- **A WebSocket frame**, in either direction, is checked as it passes. The socket
+  itself is swept every 30 s by the room's alarm and closed `1008` once revoked
+  or expired, so an idle socket can stay open that long while carrying nothing.
+- **A response stream** (SSE) keeps its answer fresh while it is open
+  (`guardStreamStanding`): the room asks the authority again 2 s before the
+  held answer reaches the bound, and ends the stream when the token is revoked
+  or expires. Ending cancels the tunnel stream, which frees its slot and tells
+  the host to stop. This costs one lookup every 28 s for each
+  token with a stream open, shared by all of that token's streams and requests.
+
+An authority that cannot be reached is given `resolverOutageGraceAttempts`
+consecutive failures (3) before a stream or socket is closed over it, and a
+failed re-read leaves a still-valid held answer in place; the token's `exp`
+ends every path regardless.
 
 ### Host Tunnel Serving-Generation Fence
 
@@ -130,7 +145,8 @@ Re-exported from [`src/index.ts`](src/index.ts):
 | Concern | Module | Notable exports |
 | --- | --- | --- |
 | Token issuance / verification | [`src/auth.ts`](src/auth.ts) | `mintRuntimeAccessToken`, `verifyRuntimeAccessToken`, `mintRelayHostToken`, `verifyRelayHostToken`, `mintHostTunnelToken`, `verifyHostTunnelToken`, types `RelayRole`, `RelayBacking`, `RelayJwtAlgorithm`, `RuntimeAccessTokenClaims`, `RelayKey`, `RelayKeyResolver`, error class `WorkspaceRelayAuthError` |
-| Request authorization and forwarding | [`src/server.ts`](src/server.ts) | `authorizeWorkspaceRelayRequest`, `workspaceRelayForwardRequestInit`, `workspaceRelayTargetUrl`, the cached resolver clients, types `WorkspaceRelayOptions`, `WorkspaceRelayTarget`, `RuntimeAccessTokenActiveResult`, `WorkspaceRelayAuditEvent` |
+| Request authorization and forwarding | [`src/server.ts`](src/server.ts) | `authorizeWorkspaceRelayRequest`, `workspaceRelayForwardRequestInit`, `workspaceRelayTargetUrl`, types `WorkspaceRelayOptions`, `WorkspaceRelayTarget`, `WorkspaceRelayAuditEvent` |
+| Resolver clients | [`src/resolver-clients.ts`](src/resolver-clients.ts) | `createCachedRevocationClient`, `createCachedTargetClient`, `createCachedHostGenerationClient`, `runtimeAccessTokenRevocationDelayMs`, type `RuntimeAccessTokenActiveResult` |
 | CORS policy | [`src/cors-origins.ts`](src/cors-origins.ts) | `DEFAULT_RELAY_APP_ORIGINS`, `RELAY_ALLOWED_REQUEST_HEADERS`, `createOriginMatcher`, `parseAllowedOrigins` |
 | Active-host directory | [`src/directory.ts`](src/directory.ts) | `createWorkspaceRelayDirectory`, types `WorkspaceRelayDirectory`, `HostTunnelPresence` |
 | Cloudflare Worker gateway and room | [`src/cloudflare.ts`](src/cloudflare.ts) | `createWorkspaceRelayDurableObjectGateway`, `createWorkspaceRelayDurableObjectRoom` |
@@ -143,8 +159,14 @@ implement the tunnel protocol without pulling Jose.
 
 ## Configuration
 
-All knobs are environment variables: Worker vars and secrets in
-`wrangler.toml` and `scripts/deploy-cloudflare.ts`.
+All knobs are environment variables. `wrangler.toml` declares what every
+deployment shares; `scripts/deploy-cloudflare.ts` renders it with one
+deployment's names (`CLAXEDO_RELAY_WORKER_NAME`, the session host
+`CLAXEDO_SESSION_HOST_WORKER_NAME` that `SESSION_HOST` binds, an optional
+`CLAXEDO_RELAY_TUNNEL_CHANNEL_CAP`, and the custom domain when
+`CLAXEDO_RELAY_URL` is not on `workers.dev`), passes the deployment's vars
+(`CLAXEDO_CENTRAL_URL`, `CLAXEDO_APP_ORIGINS`, `CLAXEDO_CONTROL_PLANE_JWKS_URL`)
+and uploads its secrets.
 
 | Env var | Purpose |
 | --- | --- |
@@ -152,7 +174,8 @@ All knobs are environment variables: Worker vars and secrets in
 | `CLAXEDO_RELAY_RESOLVER_TOKEN` | Bearer token the relay sends to the resolver. The Worker refuses to start without it. |
 | `CLAXEDO_RELAY_HOST_GENERATION_URL` | Optional absolute URL of the host-generation lookup. Unset (the normal case) derives `<CLAXEDO_RELAY_RESOLVER_URL>/host-generation`; set it only when the lookup lives at a different origin than the rest of the resolver. There is no way to turn the fence off on a resolver-backed relay. |
 | `CLAXEDO_RELAY_HOST_GENERATION_CACHE_TTL_MS` | Cache TTL for host-generation answers. Defaults to 10000. A superseded tunnel closes within the re-check interval (30 s) plus this TTL. |
-| `CLAXEDO_RELAY_REVOCATION_CACHE_TTL_MS` | Cache TTL for `/revocation` answers (default 10000 ms). Target answers are not retained. |
+| `CLAXEDO_RELAY_REVOCATION_CACHE_TTL_MS` | Cache TTL for `/revocation` answers (default 10000 ms). |
+| `CLAXEDO_RELAY_TARGET_CACHE_TTL_MS` | Cache TTL for a resolved cloud or host-tunnel target (default 10000 ms). A workspace still starting is not cached. |
 | `CLAXEDO_CONTROL_PLANE_JWKS_URL` | Remote JWKS the relay uses to verify runtime-access and host-tunnel tokens. |
 | `CLAXEDO_RUNTIME_ACCESS_TOKEN_PUBLIC_KEY_PEM` | Inline public key (alternative to JWKS). |
 | `CLAXEDO_RELAY_HOST_SIGNING_KEY_PEM` | Private PEM the relay uses to mint relay-host tokens. The Worker publishes its public half at `/.well-known/jwks.json`. |
@@ -164,9 +187,9 @@ Cloudflare Worker tracing knobs (Durable Object deployment):
 | --- | --- |
 | `CLAXEDO_RELAY_TRACE_SAMPLE_RATE` | 0–1 sampling rate for request traces. Only sampled requests emit `Server-Timing` phase headers and structured trace logs; unsampled responses carry just the `x-claxedo-trace-id` correlation header. Defaults to 0 (off). |
 | `CLAXEDO_RELAY_TRACE_FORCE_SECRET` | Optional operator secret. When set, a request with `x-claxedo-relay-trace: <secret>` forces sampling for that request (targeted debugging). Unset (default) means the force header is ignored — clients can never force tracing or timing emission. |
-| `CLAXEDO_APP_ORIGINS` | Cloudflare-only, **additive** origin entries layered on top of the base allowlist (kept for existing deploys; prefer `CLAXEDO_RELAY_ALLOWED_ORIGINS` for full control). |
+| `CLAXEDO_APP_ORIGINS` | **Additive** origin entries layered on top of the base allowlist; `CLAXEDO_RELAY_ALLOWED_ORIGINS` replaces the base list itself. |
 
-Token verification is pluggable today via the
+Token verification is pluggable via the
 `RelayKey | RelayKeyResolver` pair on `verifyRuntimeAccessToken` and
 friends, **and** via the unified
 [`TokenVerifier`](../workspace-relay-protocol/src/token-verifier.ts)
@@ -200,10 +223,38 @@ the crypto authority and must enforce issuer, audience, expiry, key selection,
 and replay policy before returning claims. Treat the endpoint as trusted
 operator configuration, not as tenant/user input.
 
-Long-lived relayed sockets are authorized at establishment. Revocation is
-checked for new HTTP requests and WebSocket upgrades; already-established
-WebSocket/SSE/PTY streams may live until their normal close, reconnect, relay
-drain, or room restart.
+## Path And Room Placement
+
+A request for a connected machine crosses these hops, and each one is there for a reason:
+
+1. **Edge.** Wherever the caller's connection lands. Cloudflare and the caller's ISP decide it; nothing here can.
+2. **App Worker**, on the app's origin, strips `/relay` and calls this Worker over a service binding in the same
+   data center. It exists so a browser makes one same-origin request with no preflight. Measured at 4 ms.
+3. **Gateway**, this Worker's stateless half, in that same data center. It names the workspace's room and passes the
+   request to it.
+4. **Room**, one Durable Object per workspace, named `relay-room:<workspaceId>`. It is the only place a browser's
+   connection and a machine's outbound tunnel can meet, because the machine cannot be dialed.
+5. **Tunnel**, the machine's one long-lived WebSocket to the room.
+
+A room is created by the first request that names it, takes its location from that request's hint, and never
+moves. `relayRoomPlacement` decides the hint:
+
+- a session host's room goes beside its Durable Object (`enam`);
+- a cloud runtime's room goes to the region the request declares, which is where its sandbox runs;
+- a person's machine has no region. Its room goes by the edge country of whoever reaches it first with a verified
+  credential: the machine's own dial, or its owner's browser. A region anyone else declares for it is ignored. The
+  control plane sends the deployment's default region for every workspace, and a room placed by that default sat
+  228 ms from a machine and owner who were both in India.
+
+No Indian data center hosts Durable Objects; `apac` from India lands in Singapore. Measured from India on
+2026-11-10, a relayed GET costs about 270 ms with the room in Singapore and cost 765 ms with it in eastern North
+America. The numbers and the rig are in `docs/perf/2026-11-10-relay-baseline.md`.
+
+Renaming rooms moves them, at a price: a room the gateway no longer names still holds its machine's tunnel, and a
+machine with a healthy tunnel does not dial again. Such a room closes its sockets on its next alarm
+(`WorkspaceRelayRoom.alarm`), which took about two minutes on staging. Deploying a Worker that names rooms
+differently from the one running, in either direction, strands tunnels for that long, or until the connector
+restarts if the deployed code has no such release.
 
 ## Tunnel Lifecycle
 
@@ -243,14 +294,14 @@ the request and forwards it to the resolved cloud target or machine tunnel.
 | --- | --- | --- |
 | Layer | Control-plane auth | Tunnel transport |
 | Trust | Authenticates the relay process itself (loopback or bearer) | Authenticates the user's runtime-access token |
-| Routes | `GET /internal/relay/target`, `GET /internal/relay/revocation` | WS upgrade + tunnel framing |
+| Routes | `GET /internal/relay/target`, `GET /internal/relay/revocation`, `GET /internal/relay/host-generation` | WS upgrade + tunnel framing |
 | Owners | `claxedo-server` (depends on the workspace authority, the identity provider, audit log) | `workspace-relay` (no authority or identity-provider dependency) |
 | Lives in | `packages/claxedo-server/` (server-side only) | `packages/workspace-relay/` (Worker and Durable Object) |
 
 This split is deliberate: the relay never reads the workspace authority or the
 identity provider directly. It calls back to `claxedo-server` over HTTP for resolver
 decisions. The decision data crosses the seam as
-`RuntimeAccessTokenActiveResult` (defined in `server.ts`).
+`RuntimeAccessTokenActiveResult` (defined in `resolver-clients.ts`).
 
 ## Development
 
@@ -259,8 +310,6 @@ bun --cwd packages/workspace-relay test        # unit suites, including the work
 bun --cwd packages/workspace-relay typecheck
 ```
 
-The TS error baseline for this package is **0** — keep it that way.
-
 ## Boundary rule
 
 Consumers outside this package import `@claxedo/workspace-relay` only —

package/dist/auth.d.ts

@@ -186,25 +186,23 @@ export declare function deriveRelayHostPublicKey(privateKey: CryptoKey): Promise
  * WebCrypto rather than `node:crypto` so the workerd bundle can use it.
  */
 export declare function deriveRelayHostKid(publicKey: CryptoKey): Promise<string>;
-/**
- * Mint variants accept only a signing key — never a resolver. Resolvers are
- * verification-only. This narrowed alias keeps the mint signatures unchanged.
- */
 type RelaySigningKey = CryptoKey | Uint8Array;
 export declare function mintRuntimeAccessToken(input: RuntimeInput, key: RelaySigningKey, alg: RelayJwtAlgorithm): Promise<string>;
 export declare function verifyRuntimeAccessToken(token: string, key: RelayKey, expected: ExpectedTarget): Promise<RuntimeAccessTokenClaims>;
 export declare function validateRuntimeAccessTokenClaims(input: Record<string, unknown>, expected: ExpectedTarget): RuntimeAccessTokenClaims;
 export declare function mintHostTunnelToken(input: HostTunnelInput, key: RelaySigningKey, alg: RelayJwtAlgorithm): Promise<string>;
 export declare function verifyHostTunnelToken(token: string, key: RelayKey, expected: ExpectedHostTunnel): Promise<HostTunnelTokenClaims>;
-/**
- * Validates a claims result a custom `authorizeHostTunnel` policy returns.
- * The policy decides WHO the tunnel is; the binding is the relay's: the
- * claims' `host_id` must equal the requested host and its `workspace_ids`
- * must cover every requested workspace, so a permissive policy cannot widen
- * the identity its own claims assert.
- */
 /** What a Relay Host Token minted from a verified Runtime Access Token carries over from it. */
 export declare function relayHostInputFromRuntimeClaims(claims: RuntimeAccessTokenClaims): Omit<RelayHostInput, "backing" | "hostId" | "workspaceId">;
+/**
+ * A Relay Host Token authenticates one HTTP request or WebSocket upgrade from
+ * the relay to the host, and the relay mints a fresh one for every request.
+ * Its 60 s life bounds replay while tolerating clock skew. A long-lived socket
+ * (PTY, SSE, event stream) outlives it: the token admits the connection, the
+ * host's own session bounds its life, and a reconnect mints a new token.
+ * Refreshing mid-stream would put the relay, and the control plane behind its
+ * resolver, in the streaming path for no security gain.
+ */
 export declare function mintRelayHostToken(input: RelayHostInput, key: RelaySigningKey, alg: RelayJwtAlgorithm): Promise<string>;
 export declare function verifyRelayHostToken(token: string, key: RelayKey, expected: ExpectedTarget): Promise<RelayHostTokenClaims>;
 export declare function tokenScopePayload(sessionId: string | undefined): {
@@ -214,11 +212,11 @@ export declare function tokenScopePayload(sessionId: string | undefined): {
     scope: "session";
     session_id: string;
 };
-/** The token's reach, or nothing when it names neither the workspace nor exactly one session. */
 /** The purpose claim, or undefined when it names a purpose this build does not know. */
 export declare function tokenPurposeClaims(payload: Record<string, unknown>): {
     purpose?: TokenPurpose;
 } | undefined;
+/** The token's reach, or nothing when it names neither the workspace nor exactly one session. */
 export declare function tokenScopeClaims(payload: Record<string, unknown>): {
     scope: TokenScope;
     session_id?: string;

package/dist/cloudflare.d.ts

@@ -1,6 +1,8 @@
 import { type AuthorizedWorkspaceRelayRequest, type WorkspaceRelayOptions } from "./server";
+import { type StreamStandingOptions } from "./stream-standing";
 import { type SessionHostNamespace } from "./session-host-forwarding";
-import { type WorkspaceRelayTraceLogEvent } from "./relay-trace";
+import { type RelayLog } from "./relay-log";
+import { type RelayTraceSampling, type WorkspaceRelayTraceLogEvent } from "./relay-trace";
 export type { WorkspaceRelayTraceLogEvent } from "./relay-trace";
 export type WorkspaceRelayDurableObjectId = unknown;
 export type WorkspaceRelayDurableObjectStub = {
@@ -41,7 +43,7 @@ export type WorkspaceRelayDurableObjectSocketPair = {
 export type WorkspaceRelayDurableObjectConnectWebSocket = (url: string, init: {
     headers: Record<string, string>;
 }) => WorkspaceRelayDurableObjectSocket | Promise<WorkspaceRelayDurableObjectSocket>;
-export type WorkspaceRelayDurableObjectRoomOptions = WorkspaceRelayOptions & {
+export type WorkspaceRelayDurableObjectRoomOptions = WorkspaceRelayOptions & RelayTraceSampling & {
     sessionHost?: SessionHostNamespace;
     createWebSocketPair?: () => WorkspaceRelayDurableObjectSocketPair;
     connectWebSocket?: WorkspaceRelayDurableObjectConnectWebSocket;
@@ -60,7 +62,7 @@ export type WorkspaceRelayDurableObjectRoomOptions = WorkspaceRelayOptions & {
      * Defaults to 30s; 0 disables the re-check. Because the check may answer
      * from the revocation lookup's cache, a revoked token closes the socket
      * within this interval plus the lookup's cache TTL — see
-     * `runtimeAccessTokenRevocationDelayMs` in `./server`. A resolver outage
+     * `runtimeAccessTokenRevocationDelayMs` in `./resolver-clients`. A resolver outage
      * gets `resolverOutageGraceAttempts` and never extends the socket past the
      * token's `exp`, which the watcher enforces locally.
      */
@@ -91,9 +93,12 @@ export type WorkspaceRelayDurableObjectRoomOptions = WorkspaceRelayOptions & {
      * non-hibernating path and in tests that do not exercise it.
      */
     alarms?: WorkspaceRelayDurableObjectAlarms;
-    traceSampleRate?: number;
-    traceForceHeaderSecret?: string;
+    /** How an open response stream's token is kept inside the revocation bound; absent, streams are not re-checked. */
+    streamStanding?: Pick<StreamStandingOptions, "standing" | "boundMs">;
+    /** Where a fault of the room's own code is reported: a frame handler or the revocation alarm throwing. */
+    report: (error: unknown, task: string) => void;
     traceLog?: (event: WorkspaceRelayTraceLogEvent) => void;
+    relayLog?: RelayLog;
     now?: () => number;
 };
 export type WorkspaceRelayDurableObjectHibernation = {
@@ -141,30 +146,6 @@ export type WorkspaceRelayDurableObjectDrainController = {
         remaining: number;
     }>;
 };
-/**
- * Exported for `relay-base64.test.ts`, which proves byte-equality against a
- * per-byte reference across the chunk boundaries. This sits on the path every
- * frame pays, so its equivalence is worth asserting directly rather than
- * inferring from a round-trip.
- */
-export declare function bytesToBase64(bytes: Uint8Array): string;
-/**
- * Runs the two frame decoders over one runtime-delivered `event.data` and
- * reports what they produced.
- *
- * Exists so `relay-workerd-binary.test.ts` can assert the decoders against what
- * REAL workerd delivers. The rest of the suite drives hand-rolled socket
- * doubles, which by construction hand us whatever we chose to hand ourselves —
- * so they cannot catch the hazard that binary `event.data` becomes a `Blob` at
- * `compatibility_date >= 2026-03-17`. Test-support surface, not a relay path.
- */
-export declare function relayFrameDiagnostics(data: unknown): Promise<{
-    frameDropped: boolean;
-    payloadDropped: boolean;
-    binary?: boolean | undefined;
-    dataBase64?: string | undefined;
-    payloadBase64: string | undefined;
-}>;
 export declare function workspaceRelayDurableObjectRoomName(workspaceId: string): string;
 export declare function workspaceRelayDurableObjectWorkspaceId(request: Request): string | undefined;
 export declare function createWorkspaceRelayDurableObjectGateway(options?: WorkspaceRelayDurableObjectGatewayOptions): {
@@ -179,7 +160,7 @@ export declare function createWorkspaceRelayDurableObjectRoom(options: Workspace
      */
     alarm(): Promise<void>;
     webSocketClose(socket: WorkspaceRelayDurableObjectSocket, code: number, reason: string): void;
-    webSocketError(socket: WorkspaceRelayDurableObjectSocket): void;
+    webSocketError(socket: WorkspaceRelayDurableObjectSocket, error?: unknown): void;
     state(): {
         hostTunnelCount: number;
         clientCount: number;

package/dist/host-tunnel-forwarding.d.ts

@@ -21,8 +21,6 @@ export declare function socketKindFor(target: {
  * risks leaking session data to it. A cloud-vm sits behind a dedicated network
  * boundary where a session cookie may legitimately be needed, so it passes
  * `Cookie` through unchanged.
- *
- * Returns a new `Headers` instance; `headers` is not mutated.
  */
 export declare function forwardHeadersFor(target: {
     backing: RelayBacking;

package/dist/http.d.ts

@@ -6,7 +6,5 @@ export declare function errorBody(code: string, message: string): {
         message: string;
     };
 };
-/** The host a tunnel request names, `/host-tunnels/<hostId>`. */
 export declare function hostIdFromTunnelPath(pathname: string): string | undefined;
-/** The workspaces a tunnel request registers for, under either spelling of the query name. */
 export declare function workspaceIdsFromSearch(url: URL): string[];