@claxedo/workspace-relay 0.6.0 → 0.8.0

package/README.md

@@ -64,7 +64,15 @@ const relay = Bun.serve({
 })
 
 const token = await mintRuntimeAccessToken(
-  { subject: "user_1", orgId: "org_1", workspaceId: "ws_1", hostId: "host_1", role: "editor" },
+  {
+    principalKind: "user",
+    actorId: "user_1",
+    actorKind: "human",
+    orgId: "org_1",
+    workspaceId: "ws_1",
+    hostId: "host_1",
+    role: "editor",
+  },
   runtimeAccessKey.privateKey,
   "EdDSA",
 )
@@ -116,6 +124,49 @@ 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
+
+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
+`GET <CLAXEDO_RELAY_RESOLVER_URL>/host-generation?enrollmentId=` on every
+admission and re-checks established tunnels every 30 s (both adapters). 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 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.
+
 ### Forwarding Boundary
 
 The relay strips client-supplied `x-forwarded-for`, `x-forwarded-host`,
@@ -190,8 +241,11 @@ production fail-closed gate at `src/main.ts`.
 | --- | --- |
 | `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_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_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_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. |
@@ -235,7 +289,7 @@ 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`
+(token introspection, custom OIDC), and `createStaticTokenVerifier`
 for tests and self-hosted single-tenant setups.
 
 `createHttpTokenVerifier` is a reference implementation. Its HTTPS endpoint is
@@ -301,8 +355,8 @@ 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`.
+  (`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
@@ -315,16 +369,16 @@ checks that gate it.
 
 ## 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) |
+| 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) |
 
-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`).
 

package/dist/auth.d.ts

@@ -16,10 +16,16 @@ export type RelayAccess = RelayClaimPair["access"];
 export type RelayBacking = RelayClaimPair["backing"];
 export type RelayJwtAlgorithm = (typeof algorithms)[number];
 export type RelayRole = "viewer" | "editor" | "admin" | "owner";
+export type ActorKind = "human" | "agent";
 export type RuntimeAccessTokenClaims = {
     iss: typeof runtimeAccessTokenIssuer;
     aud: typeof runtimeAccessTokenAudience;
-    sub: string;
+    principal_kind: "user" | "service";
+    actor_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;
@@ -31,7 +37,12 @@ export type RuntimeAccessTokenClaims = {
 export type RelayHostTokenClaims = {
     iss: typeof relayHostTokenIssuer;
     aud: typeof relayHostTokenAudience;
-    sub: string;
+    principal_kind: "user" | "service";
+    actor_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;
@@ -39,6 +50,8 @@ export type RelayHostTokenClaims = {
     exp: number;
     iat: number;
     jti: string;
+    /** Durable parent Runtime Access Token id used for revocation checks. */
+    parent_jti: string;
 } & RelayClaimPair;
 export type HostTunnelTokenClaims = {
     iss: typeof runtimeAccessTokenIssuer;
@@ -46,6 +59,15 @@ export type HostTunnelTokenClaims = {
     sub: string;
     host_id: string;
     workspace_ids: string[];
+    /**
+     * Serving-generation fence. `generation` is only valid together with
+     * `enrollment_id`; a relay with a host-generation resolver refuses a token
+     * whose generation is below the enrollment's current one. A token without a
+     * generation is admitted exactly as before the fence existed, which is what
+     * desktop and self-hosted mints still produce.
+     */
+    enrollment_id?: string;
+    generation?: number;
     exp: number;
     iat: number;
     jti: string;
@@ -55,7 +77,12 @@ export declare class WorkspaceRelayAuthError extends Error {
     constructor(code: "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;
+    actorKind: ActorKind;
+    actorPublicId?: string;
+    actorName?: string;
+    actorAvatarUrl?: string;
     orgId: string;
     workspaceId: string;
     hostId: string;
@@ -65,6 +92,8 @@ type RuntimeInput = {
     now?: number;
 };
 type RelayHostInput = RuntimeInput & RelayClaimPair & {
+    /** 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 +107,8 @@ type HostTunnelInput = {
     subject: string;
     hostId: string;
     workspaceIds: string[];
+    enrollmentId?: string;
+    generation?: number;
     ttlSeconds?: number;
     jti?: string;
     now?: number;
@@ -90,6 +121,7 @@ type ExpectedHostTunnel = {
     hostId: string;
     workspaceIds: string[];
 };
+export declare function isHostGeneration(value: unknown): value is number;
 export declare function isRelayClaimPair(input: {
     access?: unknown;
     backing?: unknown;
@@ -101,6 +133,25 @@ 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 — the two callers
+ * (`main.ts` for Bun, `worker.ts` for Cloudflare) previously asserted it away
+ * with their own copies of this round-trip.
+ */
+export declare function deriveRelayHostPublicKey(privateKey: CryptoKey): Promise<CryptoKey>;
+/**
+ * The relay-host key id, derived from the key's public component.
+ *
+ * ONE implementation on purpose: a Bun relay and a Cloudflare relay signing
+ * with the same key must publish the same `kid`, or a token minted by one fails
+ * key lookup at the other. It is written against WebCrypto rather than
+ * `node:crypto` so the workerd bundle can use it too.
+ */
+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.

package/dist/bun.d.ts

@@ -1,15 +1,28 @@
 import { type WorkspaceRelayOptions } from "./server";
+import { type RuntimeAccessTokenClaims } from "./auth";
+import { type UpstreamWebSocketConstructor } from "./upstream-websocket";
+/**
+ * Bun expresses HTTP idle timeout in seconds. Runtime SSE heartbeats arrive
+ * every 30 seconds, so this exceeds that interval while still bounding idle
+ * unauthenticated and incomplete HTTP connections.
+ */
+export declare const WORKSPACE_RELAY_IDLE_TIMEOUT_SECONDS = 45;
 type RelayClientWebSocketData = {
     kind: "client";
+    claims: RuntimeAccessTokenClaims;
     upstreamUrl: string;
     headers: Record<string, string>;
     queue: Array<{
         payload: string | Buffer<ArrayBuffer>;
         queuedAt: number;
     }>;
+    /** Running byte size of `queue`; reset when the queue is flushed upstream. */
+    queuedBytes?: number;
     upstream?: WebSocket;
     upstreamOpenTimer?: ReturnType<typeof setTimeout>;
     trace?: RelayClientWebSocketTrace;
+    accessCheckTimer?: ReturnType<typeof setInterval>;
+    expiryTimer?: ReturnType<typeof setTimeout>;
 };
 type RelayClientWebSocketTrace = {
     acceptedAt: number;
@@ -23,24 +36,33 @@ type RelayHostTunnelWebSocketData = {
     kind: "host-tunnel";
     hostId: string;
     workspaceIds: string[];
+    /** Fence pair from the last verified Host Tunnel Token (connect or registration update); absent for tokens without one. */
+    enrollmentId?: string;
+    generation?: number;
     pending: Map<string, PendingTunnelHttpResponse>;
-    channels: Map<string, Bun.ServerWebSocket<RelayUserHostedClientWebSocketData>>;
+    channels: Map<string, RelayUserHostedClientWebSocket>;
     heartbeat?: ReturnType<typeof setInterval>;
     missedPongs: number;
+    generationCheckTimer?: ReturnType<typeof setInterval>;
+    generationCheckFailures: number;
     messageBuffer: string;
 };
 type RelayUserHostedClientWebSocketData = {
     kind: "user-hosted-client";
+    claims: RuntimeAccessTokenClaims;
     hostId: string;
     workspaceId: string;
     channelId: string;
     path: string;
     relayHostToken: string;
+    accessCheckTimer?: ReturnType<typeof setInterval>;
+    expiryTimer?: ReturnType<typeof setTimeout>;
 };
 type RelayWebSocketData = RelayClientWebSocketData | RelayHostTunnelWebSocketData | RelayUserHostedClientWebSocketData;
-type UpstreamWebSocketConstructor = {
-    new (url: string, options: Bun.WebSocketOptions): WebSocket;
-};
+/** The socket type Bun hands every handler: one type carrying the data union. */
+type RelayWebSocket = Bun.ServerWebSocket<RelayWebSocketData>;
+type RelayHostTunnelWebSocket = Bun.ServerWebSocket<RelayHostTunnelWebSocketData>;
+type RelayUserHostedClientWebSocket = Bun.ServerWebSocket<RelayUserHostedClientWebSocketData>;
 type PendingTunnelHttpResponse = {
     controller: ReadableStreamDefaultController<Uint8Array>;
     stream: ReadableStream<Uint8Array>;
@@ -51,14 +73,40 @@ type PendingTunnelHttpResponse = {
     bytesQueued: number;
     slowConsumerTimeout?: ReturnType<typeof setTimeout>;
     responseStarted: boolean;
+    /**
+     * The relay's own CORS headers for this request, applied to whatever the
+     * tunnelled host answers with. The browser talks to the RELAY, so the
+     * relay's allowlist is the one that decides what it may read — the host
+     * behind the tunnel runs its own, unrelated policy, and passing its headers
+     * through made a relay's configured app origin readable only when the host
+     * happened to allow it too.
+     */
+    corsHeaders: (upstream: Headers) => Headers;
 };
 export type WorkspaceRelayHostTunnelOptions = {
+    /**
+     * Test seam replacing Host Tunnel Token verification. A boolean carries no
+     * claims, so a tunnel admitted through it has no generation and is never
+     * fenced.
+     */
     authorizeHostTunnel?: (request: Request, input: {
         hostId: string;
         workspaceIds: string[];
     }) => boolean | Promise<boolean>;
     hostTunnelPingIntervalMs?: number;
     hostTunnelMaxMissedPongs?: number;
+    /**
+     * How often an established host tunnel's generation is re-checked against
+     * `resolveHostGeneration`. Defaults to 30s; 0 disables the check. Because
+     * the lookup may answer from its cache, a superseded tunnel closes within
+     * this interval plus the lookup's cache TTL.
+     */
+    hostGenerationCheckIntervalMs?: number;
+    /**
+     * Consecutive unavailable lookups an established tunnel survives before it
+     * is closed 1012 for the host to reconnect. Defaults to 3.
+     */
+    hostGenerationOutageGraceAttempts?: number;
     hostTunnelStateDebounceMs?: number;
 };
 export type WorkspaceRelayBackpressureOptions = {
@@ -70,18 +118,31 @@ export type WorkspaceRelayBackpressureOptions = {
     directHttpConcurrency?: number;
     upstreamWebSocketOpenTimeoutMs?: number;
     upstreamWebSocketPreOpenQueueMaxFrames?: number;
+    upstreamWebSocketPreOpenQueueMaxBytes?: number;
     upstreamWebSocket?: UpstreamWebSocketConstructor;
     webSocketBufferedAmountMaxBytes?: number;
 };
-export type WorkspaceRelayBunOptions = WorkspaceRelayHostTunnelOptions & WorkspaceRelayBackpressureOptions;
+export type WorkspaceRelayBunOptions = WorkspaceRelayHostTunnelOptions & WorkspaceRelayBackpressureOptions & {
+    /** How often established user WebSockets are re-checked for revocation. Defaults to 30s. */
+    runtimeAccessTokenActiveCheckIntervalMs?: number;
+    /** Clock injection used to calculate the local token-expiry deadline. */
+    now?: () => number;
+};
+/**
+ * Declared as function-valued properties, not methods, because every member is
+ * a closure over the adapter's counters and is routinely handed around
+ * detached (`metricsSources.fragmentation ?? telemetry.getFragmentationStats`).
+ * None of them reads `this`, and the same shape is used by
+ * `WorkspaceRelayMetricsSources` in `./server`.
+ */
 export type WorkspaceRelayBunTelemetry = {
-    getFragmentationStats(): FragmentationStats;
-    resetFragmentationStats(): void;
-    getSlowConsumerStats(): SlowConsumerStats;
-    resetSlowConsumerStats(): void;
+    getFragmentationStats: () => FragmentationStats;
+    resetFragmentationStats: () => void;
+    getSlowConsumerStats: () => SlowConsumerStats;
+    resetSlowConsumerStats: () => void;
 };
 /**
- * T9: drain controller exposed by `createWorkspaceRelayBun`.
+ * Drain controller exposed by `createWorkspaceRelayBun`.
  *
  * On SIGTERM the operator (see `installShutdownDrainHandler` in main.ts)
  * flips `setDraining(true)`; from that point onward the relay
@@ -93,16 +154,41 @@ export type WorkspaceRelayBunTelemetry = {
  * `pendingCount()` reports the total number of in-flight tunnel HTTP
  * responses across every connected host tunnel — this is what the operator
  * polls via `waitForDrain(timeoutMs)` before hard-closing remaining sockets.
+ *
+ * Function-valued properties rather than methods, for the same reason as
+ * `WorkspaceRelayBunTelemetry`: `isDraining` and `pendingCount` are passed
+ * detached into `createWorkspaceRelay`, and none of them reads `this`.
  */
 export type WorkspaceRelayBunDrainController = {
-    isDraining(): boolean;
-    setDraining(value: boolean): void;
-    pendingCount(): number;
-    waitForDrain(timeoutMs: number): Promise<{
+    isDraining: () => boolean;
+    setDraining: (value: boolean) => void;
+    pendingCount: () => number;
+    waitForDrain: (timeoutMs: number) => Promise<{
         drained: boolean;
         remaining: number;
     }>;
 };
+/**
+ * Bytes queued in a socket's send buffer, or `undefined` if it cannot report.
+ *
+ * Bun spells this `getBufferedAmount()` — a method, not the browser's
+ * `bufferedAmount` property. Reading the property on a Bun socket yields
+ * `undefined`, and `undefined > limit` is always false, so a guard built on it
+ * never fires.
+ *
+ * Fails open on a socket that cannot report, deliberately: an unguarded healthy
+ * connection beats a guard that kills healthy connections. This is also why the
+ * guard is not portable to `cloudflare.ts` — workerd's WebSocket exposes no
+ * buffer depth, so bounding that path needs a protocol-level credit/ack window.
+ */
+export declare const relayBufferedBytes: (socket: unknown) => number | undefined;
+/**
+ * True only when the socket reports a depth over the limit. Unknown ⇒ false.
+ *
+ * Exported for `bun.test.ts`: a loopback peer drains faster than a test can
+ * fill it, so the decision is asserted directly.
+ */
+export declare const relayOverBackpressureLimit: (socket: unknown, limitBytes: number) => boolean;
 export type FragmentationStats = {
     fragmentsBuffered: number;
     oversizedClosed: number;
@@ -114,7 +200,7 @@ export type SlowConsumerStats = {
 };
 declare function createSlowConsumerStats(): SlowConsumerStats;
 declare function enqueueChunkWithBackpressure(input: {
-    ws: Bun.ServerWebSocket<RelayHostTunnelWebSocketData>;
+    ws: RelayHostTunnelWebSocket;
     requestId: string;
     entry: PendingTunnelHttpResponse;
     chunk: Uint8Array;
@@ -126,12 +212,12 @@ export declare const __slowConsumerInternalsForTest: {
     createSlowConsumerStats: typeof createSlowConsumerStats;
 };
 export declare function createWorkspaceRelayBun(options: WorkspaceRelayOptions, bunOptions?: WorkspaceRelayBunOptions): {
-    fetch(request: Request, server: Bun.Server<RelayWebSocketData>): Promise<Response | undefined>;
+    fetch: (request: Request, server: Bun.Server<RelayWebSocketData>) => Promise<Response | undefined>;
     websocket: {
         maxPayloadLength: number;
-        message(ws: Bun.ServerWebSocket<RelayWebSocketData>, message: string | Buffer<ArrayBuffer>): void;
-        open(ws: Bun.ServerWebSocket<RelayWebSocketData>): void;
-        close(ws: Bun.ServerWebSocket<RelayWebSocketData>, code: number, reason: string): void;
+        message(ws: RelayWebSocket, message: string | Buffer<ArrayBuffer>): void;
+        open(ws: RelayWebSocket): void;
+        close(ws: RelayWebSocket, code: number, reason: string): void;
     };
     drain: WorkspaceRelayBunDrainController;
     telemetry: WorkspaceRelayBunTelemetry;