@claxedo/workspace-relay 0.7.0 → 0.10.0

package/README.md

@@ -1,90 +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(
-  { subject: "user_1", 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
 
@@ -96,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.
 
@@ -116,6 +57,38 @@ 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.
 
+### Host Tunnel Serving-Generation Fence
+
+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. The
+verdicts, in order:
+
+| Control plane answer | Admission | Established tunnel |
+| --- | --- | --- |
+| Same generation, not revoked | admitted | kept |
+| Higher generation | `403 host_generation_superseded` | closed `1008` |
+| Lower generation | `403 host_generation_unknown` | closed `1008` |
+| Enrollment revoked or paused | `403 host_enrollment_revoked` | closed `1008` |
+| `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 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
 
 The relay strips client-supplied `x-forwarded-for`, `x-forwarded-host`,
@@ -123,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
 
@@ -169,37 +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` | Where to fetch `RuntimeAccessTokenActiveResult`s (typically `claxedo-server/internal/relay/target`). |
-| `CLAXEDO_RELAY_RESOLVER_TOKEN` | Bearer token the relay sends to the resolver. **Required in production.** |
-| `CLAXEDO_RELAY_JWKS_URL` | Optional remote JWKS the relay uses to verify runtime-access tokens. |
+| `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_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):
 
@@ -218,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"
@@ -235,8 +192,8 @@ The `TokenVerifier` interface intentionally contains only `verify(token)`.
 JWKS fetching, audience binding, and replay caches belong to the
 implementation. Two reference implementations ship in the protocol
 package: `createHttpTokenVerifier` for remote verifiers
-(Clerk-style introspection, custom OIDC), and `createStaticTokenVerifier`
-for tests and self-hosted single-tenant setups.
+(token introspection, custom OIDC), and `createStaticTokenVerifier`
+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,
@@ -246,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
 
@@ -256,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
@@ -274,65 +224,38 @@ 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/proxy.ts:205`) on its top-level Hono
-  app at `packages/claxedo-server/src/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`
 
-| | `claxedo-server/src/routes/internal-relay.ts` | `@claxedo/workspace-relay` |
+| | `claxedo-server/src/deployments/shared-routes/internal-relay.ts` | `@claxedo/workspace-relay` |
 | --- | --- | --- |
 | 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 |
-| Owners | `claxedo-server` (depends on Convex authority, Clerk, audit log) | `workspace-relay` (no Convex/Clerk dependency) |
-| Lives in | `packages/claxedo-server/` (server-side only) | `packages/workspace-relay/` (own process) |
+| 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 Convex or Clerk
-directly. It calls back to `claxedo-server` over HTTP for resolver
+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`).
 
 ## 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
 ```
 

package/dist/auth.d.ts

@@ -5,25 +5,66 @@ export declare const runtimeAccessTokenAudience = "workspace-relay";
 export declare const hostTunnelTokenAudience = "workspace-relay-host-tunnel";
 export declare const relayHostTokenIssuer = "workspace-relay";
 export declare const relayHostTokenAudience = "workspace-host-service";
-export type RelayClaimPair = {
-    access: "cloud";
-    backing: "cloud-vm";
-} | {
-    access: "user-hosted";
-    backing: "local-worktree";
-};
-export type RelayAccess = RelayClaimPair["access"];
-export type RelayBacking = RelayClaimPair["backing"];
+/**
+ * Where the host behind a relayed request runs: the provisioner's machine
+ * (`cloud-vm`), an enrolled one (`local-worktree`), or one session's Durable
+ * Object (`durable-object`). The only placement word on the relay wire; the
+ * control plane stores the first two as a workspace's backing.
+ */
+export type RelayBacking = "cloud-vm" | "local-worktree" | "durable-object";
 export type RelayJwtAlgorithm = (typeof algorithms)[number];
 export type RelayRole = "viewer" | "editor" | "admin" | "owner";
+export type ActorKind = "human" | "agent";
+/**
+ * Earliest `iat` a Runtime Access Token may carry (2026-09-21T00:00:00Z).
+ *
+ * Tokens minted before channel provenance existed carry no `channel_identity`,
+ * so a channel-issued one among them is indistinguishable from an app token
+ * and there is no binding generation to check it against. The whole vintage is
+ * refused rather than trusted until it expires.
+ */
+export declare const RUNTIME_ACCESS_TOKEN_ISSUED_AT_FLOOR_SECONDS = 1789948800;
+/** The channel binding that authorized a token, as the token carries it. */
+export type ChannelIdentityClaim = {
+    channel: string;
+    external_user_id: string;
+    identity_version: number;
+};
+/** The same binding as a mint argument. */
+export type ChannelIdentityInput = {
+    channel: string;
+    externalUserId: string;
+    identityVersion: number;
+};
+export declare function toChannelIdentityClaim(input: ChannelIdentityInput): ChannelIdentityClaim;
+export type TokenScope = "workspace" | "session";
+/** A token minted for one job; only the routes serving that job accept it. */
+export type TokenPurpose = "turn-execution";
 export type RuntimeAccessTokenClaims = {
     iss: typeof runtimeAccessTokenIssuer;
     aud: typeof runtimeAccessTokenAudience;
-    sub: string;
+    principal_kind: "user" | "service";
+    actor_id: string;
+    user_id?: string;
+    actor_kind: "human" | "agent";
+    actor_public_id?: string;
+    actor_name?: string;
+    actor_avatar_url?: string;
     org_id: string;
     workspace_id: string;
     host_id: string;
     role: RelayRole;
+    /**
+     * What the token reaches: the whole workspace (its owner's token) or the one
+     * session `session_id` names (a share holder's). A token naming neither is
+     * refused, so a token minted before reach was named reaches nothing.
+     */
+    scope: TokenScope;
+    session_id?: string;
+    purpose?: TokenPurpose;
+    channel_identity?: ChannelIdentityClaim;
+    /** Present for cloud workspaces; assigned atomically with the sandbox address. */
+    routing_id?: string;
     exp: number;
     iat: number;
     jti: string;
@@ -31,40 +72,68 @@ export type RuntimeAccessTokenClaims = {
 export type RelayHostTokenClaims = {
     iss: typeof relayHostTokenIssuer;
     aud: typeof relayHostTokenAudience;
-    sub: string;
+    principal_kind: "user" | "service";
+    actor_id: string;
+    user_id?: string;
+    actor_kind: "human" | "agent";
+    actor_public_id?: string;
+    actor_name?: string;
+    actor_avatar_url?: string;
     org_id: string;
     workspace_id: string;
     host_id: string;
     role: RelayRole;
+    scope: TokenScope;
+    session_id?: string;
+    purpose?: TokenPurpose;
+    channel_identity?: ChannelIdentityClaim;
     exp: number;
     iat: number;
     jti: string;
-} & RelayClaimPair;
+    /** Durable parent Runtime Access Token id used for revocation checks. */
+    parent_jti: string;
+    backing: RelayBacking;
+};
 export type HostTunnelTokenClaims = {
     iss: typeof runtimeAccessTokenIssuer;
     aud: typeof hostTunnelTokenAudience;
     sub: string;
     host_id: string;
     workspace_ids: string[];
+    enrollment_id: string;
+    generation: number;
     exp: number;
     iat: number;
     jti: string;
 };
 export declare class WorkspaceRelayAuthError extends Error {
-    readonly code: "invalid_relay_token" | "relay_token_workspace_mismatch" | "relay_token_host_mismatch" | "relay_token_claims_invalid";
-    constructor(code: "invalid_relay_token" | "relay_token_workspace_mismatch" | "relay_token_host_mismatch" | "relay_token_claims_invalid", message: string);
+    readonly code: "runtime_access_token_invalid" | "invalid_relay_token" | "relay_token_workspace_mismatch" | "relay_token_host_mismatch" | "relay_token_claims_invalid";
+    constructor(code: "runtime_access_token_invalid" | "invalid_relay_token" | "relay_token_workspace_mismatch" | "relay_token_host_mismatch" | "relay_token_claims_invalid", message: string);
 }
 type RuntimeInput = {
-    subject: string;
+    principalKind: "user" | "service";
+    actorId: string;
+    userId?: string;
+    actorKind: ActorKind;
+    actorPublicId?: string;
+    actorName?: string;
+    actorAvatarUrl?: string;
     orgId: string;
     workspaceId: string;
     hostId: string;
     role: RelayRole;
+    sessionId?: string;
+    purpose?: TokenPurpose;
+    channelIdentity?: ChannelIdentityInput;
+    routingId?: string;
     ttlSeconds?: number;
     jti?: string;
     now?: number;
 };
-type RelayHostInput = RuntimeInput & RelayClaimPair & {
+type RelayHostInput = RuntimeInput & {
+    backing: RelayBacking;
+    /** The Runtime Access Token jti from which this one-request RHT is derived. */
+    parentJti: string;
     /**
      * Optional `kid` to embed in the JWT protected header. Verifiers using a
      * JWKS resolver dispatch on this to pick the matching key, so a freshly
@@ -78,6 +147,8 @@ type HostTunnelInput = {
     subject: string;
     hostId: string;
     workspaceIds: string[];
+    enrollmentId: string;
+    generation: number;
     ttlSeconds?: number;
     jti?: string;
     now?: number;
@@ -90,10 +161,8 @@ type ExpectedHostTunnel = {
     hostId: string;
     workspaceIds: string[];
 };
-export declare function isRelayClaimPair(input: {
-    access?: unknown;
-    backing?: unknown;
-}): input is RelayClaimPair;
+export declare function isHostGeneration(value: unknown): value is number;
+export declare function isRelayBacking(input: unknown): input is RelayBacking;
 /**
  * Resolver function returned by `createRemoteJWKSet` / `createLocalJWKSet`.
  * Accepted by `jwtVerify` directly — jose dispatches based on whether the
@@ -101,6 +170,22 @@ export declare function isRelayClaimPair(input: {
  */
 export type RelayKeyResolver = JWTVerifyGetKey;
 export type RelayKey = CryptoKey | Uint8Array | RelayKeyResolver;
+/**
+ * Re-imports the PUBLIC half of an EdDSA relay-host signing key.
+ *
+ * `importJWK` is declared `Promise<CryptoKey | Uint8Array>` because a symmetric
+ * (`oct`) JWK imports as raw bytes. An EdDSA public JWK never does, so the byte
+ * branch is a configuration error worth failing loudly on.
+ */
+export declare function deriveRelayHostPublicKey(privateKey: CryptoKey): Promise<CryptoKey>;
+/**
+ * The relay-host key id, derived from the key's public component.
+ *
+ * Signing with the same key must always publish the same `kid`, or a token
+ * minted under one build fails key lookup at the next. Written against
+ * 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.
@@ -111,6 +196,31 @@ export declare function verifyRuntimeAccessToken(token: string, key: RelayKey, e
 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">;
 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): {
+    scope: "workspace";
+    session_id?: 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;
+export declare function tokenScopeClaims(payload: Record<string, unknown>): {
+    scope: TokenScope;
+    session_id?: string;
+} | undefined;
 export {};