@claxedo/workspace-relay 0.8.0 → 0.10.0

package/README.md

@@ -1,98 +1,12 @@
 # `@claxedo/workspace-relay`
 
-The Claxedo workspace relay — the single canonical tunnel process between
-cloud-hosted browsers and workspace-runtime hosts, whether the host is a cloud
-VM or a user laptop. One package, one process, one config surface — there is no
-separate `dev-relay` codepath.
-
-Runtime requirement: the packaged `workspace-relay` bin and the default server
-bootstrap run on **Bun** (they use `Bun.*` APIs via the Bun adapter). Node is
-not supported for the standalone process today; the Cloudflare Worker adapter
-is the other supported runtime.
-
-Production v1 is deliberately single-instance for user-hosted traffic. The
-relay keeps host presence and host-tunnel sockets in process-local maps, and a
-`hostId` has exactly one active tunnel at a time. Deploy one active relay
-process per user-hosted relay fleet; horizontal scaling needs a future routing
-owner for sticky host tunnels, split-brain prevention, and failover. A relay
-process, VM, or region failure drops existing user-hosted HTTP, WebSocket, SSE,
-and PTY sessions until workspace runtimes reconnect.
-
-## Quickstart
+The Claxedo workspace relay: the tunnel between browsers and workspace-runtime
+hosts, whether the host is a cloud VM or a user laptop.
 
-```sh
-bun add @claxedo/workspace-relay jose
-```
-
-The smallest runnable relay: mint an EdDSA key pair to stand in for the
-control plane's signing key, point `resolveTarget` at a cloud-VM-style
-workspace host, boot the Bun adapter, then mint a Runtime Access Token the
-way `claxedo-control-plane` would and use it to reach the target through the
-relay.
-
-```ts
-// relay.ts
-import { generateKeyPair } from "jose"
-import { createWorkspaceRelayBun, mintRuntimeAccessToken } from "@claxedo/workspace-relay"
-
-const runtimeAccessKey = await generateKeyPair("EdDSA", { extractable: true })
-const relayHostKey = await generateKeyPair("EdDSA", { extractable: true })
-
-// Stand-in workspace host: whatever the relay forwards accepted traffic to.
-const host = Bun.serve({
-  port: 0,
-  fetch: (request) => new Response(`host saw ${new URL(request.url).pathname}`),
-})
-
-const handler = createWorkspaceRelayBun({
-  runtimeAccessKey: runtimeAccessKey.publicKey,
-  relayHostSigningKey: relayHostKey.privateKey,
-  relayHostAlgorithm: "EdDSA",
-  resolveTarget: (claims) => ({
-    workspaceId: claims.workspace_id,
-    hostId: claims.host_id,
-    baseUrl: String(host.url).replace(/\/$/, ""),
-    access: "cloud",
-    backing: "cloud-vm",
-  }),
-})
-
-const relay = Bun.serve({
-  port: 7777,
-  fetch: handler.fetch,
-  websocket: handler.websocket,
-})
-
-const token = await mintRuntimeAccessToken(
-  {
-    principalKind: "user",
-    actorId: "user_1",
-    actorKind: "human",
-    orgId: "org_1",
-    workspaceId: "ws_1",
-    hostId: "host_1",
-    role: "editor",
-  },
-  runtimeAccessKey.privateKey,
-  "EdDSA",
-)
-
-console.log(`relay listening on ${relay.url}`)
-console.log(`curl -H "Authorization: Bearer ${token}" ${relay.url}workspaces/ws_1/hello`)
-```
-
-```sh
-bun run relay.ts
-```
-
-Run the printed `curl` command in another terminal — the relay verifies the
-Runtime Access Token, calls `resolveTarget`, mints a Relay Host Token, and
-forwards the request; you'll see `host saw /hello` come back. This mirrors
-what [`src/main.ts`](src/main.ts) assembles for production, minus the
-env-driven resolver client, JWKS, and graceful drain — see
-[docs/architecture.md](docs/architecture.md) for how those pieces fit
-together, and the Configuration table below for the env vars that replace
-the hardcoded values above in a real deployment.
+It deploys as a Cloudflare Worker. `src/worker.ts` is a stateless gateway that
+routes each workspace to its own Durable Object room (`src/cloudflare.ts`), so
+the room that owns a workspace's host tunnel also serves every request for that
+workspace. `scripts/deploy-cloudflare.ts` deploys it.
 
 ## Deployment Security
 
@@ -104,18 +18,37 @@ accepted traffic to the selected host with a freshly minted relay-host token.
 | Token | Default TTL | Issuer | Audience | Purpose |
 | --- | ---: | --- | --- | --- |
 | Runtime Access Token (RAT) | 30 minutes | `claxedo-control-plane` | `workspace-relay` | User/browser authorization to reach one workspace and host through the relay. |
-| Host Tunnel Token (HTT) | 5 minutes | `claxedo-control-plane` | `workspace-relay-host-tunnel` | Workspace runtime authorization to register a user-hosted tunnel. |
+| Host Tunnel Token (HTT) | 5 minutes | `claxedo-control-plane` | `workspace-relay-host-tunnel` | Workspace runtime authorization to register a host tunnel. |
 | Relay Host Token (RHT) | 60 seconds | `workspace-relay` | `workspace-host-service` | Per-request relay-to-host authorization minted after RAT validation. |
 
 Runtime access tokens and host tunnel tokens bind issuer, audience, subject,
 workspace id, host id, expiry, issue time, and JTI. Runtime access tokens also
-bind role. Relay-host tokens additionally bind the deployment pair:
-`cloud/cloud-vm` or `user-hosted/local-worktree`.
+bind role. Relay-host tokens additionally bind the placement: `cloud-vm`,
+`local-worktree` or `durable-object`.
+
+A cloud runtime access token carries `routing_id`, a UUID owned by the lease
+store's address transition. It changes when the address or resource changes and
+on a new acquisition, including after lease deletion. The resolver requires the
+signed identity to match the current ready lease; otherwise it returns 401
+`runtime_access_token_invalid`. The app renews through connection POST once.
+
+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
+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
+on its own cadence. The revocation check and the target lookup go out together,
+since each needs only the token's claims. A request already resolving or
+forwarding when the lease changes can finish with its previous snapshot;
+established streams are not disconnected by this fence. The runtime receives a
+relay-host token, so it does not independently fence the original routing
+identity. The relay does not retry upstream failures.
 
 ### Revocation And Active Checks
 
-`isRuntimeAccessTokenActive` is the revocation/target freshness hook. Production
-deployments should implement it by calling the control plane or an equivalent
+`isRuntimeAccessTokenActive` is the revocation/target freshness hook. A deployed
+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.
 
@@ -126,11 +59,10 @@ requirement, the control plane must also close the session/runtime channel.
 
 ### Host Tunnel Serving-Generation Fence
 
-A Host Tunnel Token minted by a connect-enrolled host carries `enrollment_id`
-and `generation`. A relay built by `src/main.ts` or `src/worker.ts` — that is,
-any relay with a resolver — asks
+Every Host Tunnel Token carries `enrollment_id` and `generation`. A relay
+requires a host-generation resolver and asks
 `GET <CLAXEDO_RELAY_RESOLVER_URL>/host-generation?enrollmentId=` on every
-admission and re-checks established tunnels every 30 s (both adapters). The
+admission and re-checks established tunnels every 30 s. The
 verdicts, in order:
 
 | Control plane answer | Admission | Established tunnel |
@@ -142,30 +74,20 @@ verdicts, in order:
 | `404 relay_resolver_enrollment_not_found` | `403 host_enrollment_unknown` | closed `1008` |
 | Any other status, a bare 404 (route missing), malformed body, or the 5 s deadline | `503 host_generation_lookup_unavailable` (retry) | survives two consecutive failures, closed `1012` on the third |
 
-A token without a generation is admitted without asking the control plane. It
-never displaces a socket that carries a generation: for one host+workspace
-identity (Bun) or one room (Cloudflare), an incumbent with a generation yields
-only to an equal or higher generation, and an incumbent without one yields to
-any later socket. Every refusal is audited as `host_tunnel.denied` with the
-code as `reason` (Bun; the Cloudflare room has no audit hook).
-
-A `host.registration.update` frame is re-admitted the same way, with the
-socket's own claims as the first incumbent: an update whose token carries no
-generation, or a lower one than the socket holds, is refused (closed `1008
-Host tunnel registration update superseded`); one that passes is then checked
-against the control plane exactly as a connect is and closed with the table's
-established-tunnel code on refusal (`1012` for an unavailable lookup, without
-the outage grace). An accepted update replaces the socket's claims and
-identities, and a socket that became fenced starts the 30 s re-check (or arms
-the hibernation alarm).
-
-A relay composed directly from `createWorkspaceRelayBun` /
-`createWorkspaceRelayDurableObjectRoom` without `resolveHostGeneration` — the
-desktop and self-hosted composition — admits tokens without a generation
-newest-wins and refuses any token that carries one with
-`403 host_generation_unverifiable` (an update: closed `1008`). A generation is
-a fence the relay cannot verify without the resolver, and the refusal is not
-retryable because the resolver is a property of the composition.
+A token missing either fence claim is refused. An incumbent in a workspace
+room yields only to an equal or higher generation.
+
+A `host.registration.update` frame must carry a complete, verified token. A
+missing fence closes the socket with `1008 Host tunnel registration update
+denied`; a lower generation closes it with `1008 Host tunnel registration
+update superseded`. The relay then checks the control plane and closes with
+the table's established-tunnel code on refusal, without outage grace for an
+update. An accepted update replaces the socket's claims and identities and
+keeps the periodic check or hibernation alarm active.
+
+A relay composed without `resolveHostGeneration` refuses host tunnels with
+`403 host_generation_unverifiable`. This refusal is not retryable because the
+resolver belongs to the composition.
 
 ### Forwarding Boundary
 
@@ -174,45 +96,32 @@ The relay strips client-supplied `x-forwarded-for`, `x-forwarded-host`,
 headers. It replaces `Authorization` with an RHT, sets `x-workspace-id`, and
 adds `x-forwarded-by: workspace-relay`.
 
-For user-hosted targets, `Cookie` is stripped before forwarding. User-hosted
-workspace processes may run near a developer's local browser cookie jar, so
-browser cookies must not be passed through to the local host service. Cloud VM
-targets may receive cookies when the caller intentionally sends them.
+For `local-worktree` targets, `Cookie` is stripped before forwarding. A host
+tunnel ends on a machine someone uses, whose browser cookie jar the host
+service may share, so browser cookies must not be passed through to it. Cloud
+VM targets may receive cookies when the caller intentionally sends them.
+
+A `durable-object` target is a session served by its own Durable Object, host
+`session-do:<root>`. The control plane resolves it with an empty `baseUrl`, and
+the room forwards HTTP to the `SESSION_HOST` binding's object named by the root,
+cookies stripped as for a host tunnel and response streams passed through. A
+WebSocket upgrade to it is refused with `400 durable_object_websocket_unsupported`:
+a session host serves its events over HTTP streams.
 
 ### CORS
 
 The relay owns CORS responses for browser-facing workspace requests. Do not
-forward upstream CORS headers as the source of truth. Add allowed product
-origins in the relay/server CORS configuration and keep wildcard origins out of
-credentialed deployments.
-
-### Metrics
-
-`GET /metrics` is privileged operational data. In production, set
-`CLAXEDO_RELAY_METRICS_TOKEN` and scrape with `Authorization: Bearer <token>`.
-When no metrics token is configured, the endpoint only allows callers that the
-adapter identifies as loopback; if no remote-address resolver exists, it fails
-closed.
-
-### User-Hosted Topology
+forward upstream CORS headers as the source of truth. Configure browser origins
+with `CLAXEDO_RELAY_ALLOWED_ORIGINS` or `CLAXEDO_APP_ORIGINS` (see
+Configuration) and keep wildcard origins out of credentialed deployments. A
+development relay that serves a local app names its loopback origins itself,
+for example `CLAXEDO_APP_ORIGINS=http://localhost:*,http://127.0.0.1:*`; a
+deployed relay admits none by default.
 
-Production v1 supports one active relay instance for user-hosted traffic, or a
-load balancer with strict stickiness that keeps each `hostId` on the relay
-process that owns its tunnel socket. Non-sticky horizontal scaling needs an
-external directory and tunnel routing owner before it is safe to advertise as
-durable.
+### Host-Tunnel Topology
 
-## Why one package, no parallel impl
-
-In the fa9cabf9 design pass the working assumption was clarified:
-
-> "I think this creates a parallel implementation problem — why is there
-> no devmode in the prod relay?"
-
-So this package is the relay. Local-dev configuration is selected by
-environment variables, not by a sibling `dev-relay.ts` module. If a
-future cycle re-introduces a separate `dev-relay.*` file in
-`packages/claxedo-server/`, that should be flagged as a regression.
+A Durable Object room is scoped to one workspace, so a host tunnel registering
+through the Worker presents exactly one `workspaceId` per connection.
 
 ## Public surface
 
@@ -220,40 +129,34 @@ 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`, `RelayAccess`, `RelayBacking`, `RelayJwtAlgorithm`, `RuntimeAccessTokenClaims`, `RelayKey`, `RelayKeyResolver`, error class `WorkspaceRelayAuthError` |
-| Hono HTTP surface | [`src/server.ts`](src/server.ts) | `createWorkspaceRelay`, `authorizeWorkspaceRelayRequest`, types `WorkspaceRelayOptions`, `WorkspaceRelayTarget`, `RuntimeAccessTokenActiveResult`, `WorkspaceRelayAuditEvent`, `WorkspaceRelayMetricsSources`, `RelayHostPublicKey` |
-| Active-host directory | [`src/directory.ts`](src/directory.ts) | `createWorkspaceRelayDirectory`, `disposeWorkspaceRelayDirectory`, types `WorkspaceRelayDirectory`, `HostTunnelPresence` |
-| Bun-specific server bootstrap | [`src/bun.ts`](src/bun.ts) | `createWorkspaceRelayBun`, type `WorkspaceRelayBunOptions`, `WorkspaceRelayBunDrainController`, metrics `getFragmentationStats`, `getSlowConsumerStats` |
+| 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` |
+| 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` |
 
 Wire types live in the sibling package
 [`@claxedo/workspace-relay-protocol`](../workspace-relay-protocol/)
 (`TUNNEL_PROTOCOL_VERSION`, `TunnelMessage`, `isTunnelMessage`,
 `makeTunnelPong`). Keep that split — it lets non-Node consumers
-implement the tunnel protocol without pulling Hono and Jose.
+implement the tunnel protocol without pulling Jose.
 
 ## Configuration
 
-All knobs are environment variables. The relay refuses to boot in
-production if `CLAXEDO_RELAY_RESOLVER_TOKEN` is missing — the
-production fail-closed gate at `src/main.ts`.
+All knobs are environment variables: Worker vars and secrets in
+`wrangler.toml` and `scripts/deploy-cloudflare.ts`.
 
 | Env var | Purpose |
 | --- | --- |
-| `CLAXEDO_RELAY_BIND_HOST`, `CLAXEDO_RELAY_BIND_PORT` | Listening socket. Loopback by default. |
-| `CLAXEDO_RELAY_PUBLIC_URL` | Externally-resolvable URL the relay advertises in tokens. |
-| `CLAXEDO_RELAY_RESOLVER_URL` | Control-plane resolver base (`https://<control-plane>/internal/relay`). The relay derives `/target`, `/revocation`, and `/host-generation` from it. Required by the Bun process; the Worker also accepts `CLAXEDO_CENTRAL_URL` and appends `/internal/relay`. |
-| `CLAXEDO_RELAY_RESOLVER_TOKEN` | Bearer token the relay sends to the resolver. **Required in production.** |
+| `CLAXEDO_RELAY_RESOLVER_URL` | Control-plane resolver base (`https://<control-plane>/internal/relay`). The relay derives `/target`, `/revocation`, and `/host-generation` from it. The Worker also accepts `CLAXEDO_CENTRAL_URL` and appends `/internal/relay`. |
+| `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_TARGET_CACHE_TTL_MS`, `CLAXEDO_RELAY_REVOCATION_CACHE_TTL_MS` | Cache TTLs for `/target` (default 30000 on Bun, 5000 on the Worker) and `/revocation` (default 10000) answers. |
-| `CLAXEDO_RELAY_JWKS_URL` | Optional remote JWKS the relay uses to verify runtime-access tokens. |
+| `CLAXEDO_RELAY_REVOCATION_CACHE_TTL_MS` | Cache TTL for `/revocation` answers (default 10000 ms). Target answers are not retained. |
+| `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_VERIFY_PEM` | Public PEM the relay uses to verify host-tunnel tokens. |
-| `CLAXEDO_RELAY_HOST_SIGNING_KEY_PEM` | Private PEM the relay uses to mint relay-host tokens. |
-| `CLAXEDO_RELAY_METRICS_TOKEN` | Optional bearer token for `/metrics`. Without it, `/metrics` requires a trusted loopback remote-address resolver. |
-| `CLAXEDO_RELAY_DRAIN_TIMEOUT_MS` | Graceful shutdown wait before force-closing sockets. Defaults to 30000. |
-| `CLAXEDO_RELAY_ALLOWED_ORIGINS` | Comma-separated browser-origin allowlist for CORS. **Replaces** the built-in default list (Claxedo/OpenCode app origins plus `http://localhost:*` dev hosts) — self-hosted deployments set their own origins here. Grammar: exact origin, `https://*.example.com`, `http://localhost:*`. Works on both the Bun process and the Cloudflare Worker. |
-| `NODE_ENV` | `production` / `development` / `test`. Switches the production fail-closed gate. |
+| `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`. |
+| `CLAXEDO_RELAY_ALLOWED_ORIGINS` | Comma-separated browser-origin allowlist for CORS. **Replaces** the built-in default list (`https://claxedo.com` and `https://*.claxedo.com`; no loopback origin). Grammar: exact origin, `https://*.example.com`, `http://localhost:*`.  |
 
 Cloudflare Worker tracing knobs (Durable Object deployment):
 
@@ -272,7 +175,7 @@ crypto/introspection authority; the relay still validates its output into
 `RuntimeAccessTokenClaims`, binds the URL workspace id to the claims, applies
 revocation, and allowlists roles. Missing, unknown, or malformed roles deny.
 
-To swap the relay's auth backend in a self-hosted deployment:
+To swap the relay's auth backend:
 
 ```ts
 import { createStaticTokenVerifier } from "@claxedo/workspace-relay-protocol"
@@ -290,7 +193,7 @@ JWKS fetching, audience binding, and replay caches belong to the
 implementation. Two reference implementations ship in the protocol
 package: `createHttpTokenVerifier` for remote verifiers
 (token introspection, custom OIDC), and `createStaticTokenVerifier`
-for tests and self-hosted single-tenant setups.
+for tests and single-tenant setups.
 
 `createHttpTokenVerifier` is a reference implementation. Its HTTPS endpoint is
 the crypto authority and must enforce issuer, audience, expiry, key selection,
@@ -300,7 +203,7 @@ 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 process restart.
+drain, or room restart.
 
 ## Tunnel Lifecycle
 
@@ -310,13 +213,6 @@ heartbeat timer, and buffered work before installing the new socket. Stale close
 events identity-check the current owner before deleting presence, so an old
 socket cannot mark a replacement offline.
 
-Relay drain sets `/health` unhealthy, rejects new workspace requests and tunnel
-registrations with `503 relay_draining`, closes active host tunnels so runtimes
-reconnect promptly, waits for pending work up to the configured timeout, then
-stops the server. Truly uncaught exceptions and unhandled rejections are fatal:
-the relay marks itself draining, stops accepting work, disposes timers, and
-exits for supervisor restart.
-
 ## External Directory Design
 
 The current `WorkspaceRelayDirectory` is an in-memory implementation of the
@@ -328,44 +224,18 @@ type WorkspaceRelayDirectory = {
   recordPong(hostId: string): HostTunnelPresence | undefined
   disconnectHost(hostId: string): void
   activeHost(input: { hostId: string; workspaceId: string }): HostTunnelPresence | undefined
-  sweep(): void
-  dispose(): void
-  size(): number
 }
 ```
 
-A Redis, Durable Object, or equivalent implementation should keep the same
-semantics:
-
-- one active owner for a `hostId`;
-- TTL extension on heartbeat pong;
-- immediate removal on disconnect;
-- workspace membership checks before user-hosted forwarding;
-- split-brain prevention when a replacement tunnel connects;
-- observability for active host count and stale owner cleanup.
-
-The missing piece for true multi-instance user-hosted relay is not just durable
-presence storage. HTTP/WebSocket/SSE/PTY traffic must also route to the process
-or durable object that owns the live tunnel socket for that `hostId`.
+The Durable Object room keeps presence with its live socket. Hibernation
+restores presence from socket attachments. Cloudflare routes every request for
+one workspace to that room, which owns its tunnel.
 
 ## Routing
 
-The relay has **no** `/w/{workspaceId}/*` URL prefix of its own. The
-gateway pattern lives in `claxedo-server`:
-
-- The user's browser calls `/api/claxedo/...`.
-- `claxedo-server` mounts `workspaceRuntimeProxy` middleware
-  (`packages/claxedo-server/src/workspace/runtime-dispatch/internals.ts:205`) on its top-level Hono
-  app at `packages/claxedo-server/src/deployments/local/server.ts:93`.
-- The proxy resolves the active workspace target via
-  `internal-relay.ts` (control-plane auth — see "Seam: internal-relay
-  vs workspace-relay" below), strips its own prefix, and forwards
-  to the relay's tunnel endpoint.
-
-If you are adding a new HTTP-level workspace surface, attach it to
-`claxedo-server`'s gateway, not to `workspace-relay`. The relay is
-intentionally narrow — it only handles tunnel traffic and the auth
-checks that gate it.
+Browsers call `/workspaces/:workspaceId/*` on the relay with a Runtime Access
+Token. `src/worker.ts` selects the workspace room; `src/cloudflare.ts` authorizes
+the request and forwards it to the resolved cloud target or machine tunnel.
 
 ## Seam: `internal-relay` vs `workspace-relay`
 
@@ -375,7 +245,7 @@ checks that gate it.
 | 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 |
 | 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/` (own process) |
+| 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
@@ -385,8 +255,7 @@ decisions. The decision data crosses the seam as
 ## Development
 
 ```sh
-bun --cwd packages/workspace-relay dev   # hot-reload main.ts
-bun --cwd packages/workspace-relay test  # run all *.test.ts
+bun --cwd packages/workspace-relay test        # unit suites, including the workerd ones
 bun --cwd packages/workspace-relay typecheck
 ```