@claxedo/workspace-relay 0.8.0 → 0.10.0

package/dist/auth.d.ts

@@ -5,23 +5,47 @@ 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;
     principal_kind: "user" | "service";
     actor_id: string;
+    user_id?: string;
     actor_kind: "human" | "agent";
     actor_public_id?: string;
     actor_name?: string;
@@ -30,6 +54,17 @@ export type RuntimeAccessTokenClaims = {
     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;
@@ -39,6 +74,7 @@ export type RelayHostTokenClaims = {
     aud: typeof relayHostTokenAudience;
     principal_kind: "user" | "service";
     actor_id: string;
+    user_id?: string;
     actor_kind: "human" | "agent";
     actor_public_id?: string;
     actor_name?: string;
@@ -47,38 +83,37 @@ export type RelayHostTokenClaims = {
     workspace_id: string;
     host_id: string;
     role: RelayRole;
+    scope: TokenScope;
+    session_id?: string;
+    purpose?: TokenPurpose;
+    channel_identity?: ChannelIdentityClaim;
     exp: number;
     iat: number;
     jti: string;
     /** Durable parent Runtime Access Token id used for revocation checks. */
     parent_jti: string;
-} & RelayClaimPair;
+    backing: RelayBacking;
+};
 export type HostTunnelTokenClaims = {
     iss: typeof runtimeAccessTokenIssuer;
     aud: typeof hostTunnelTokenAudience;
     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;
+    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 = {
     principalKind: "user" | "service";
     actorId: string;
+    userId?: string;
     actorKind: ActorKind;
     actorPublicId?: string;
     actorName?: string;
@@ -87,11 +122,16 @@ type RuntimeInput = {
     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;
     /**
@@ -107,8 +147,8 @@ type HostTunnelInput = {
     subject: string;
     hostId: string;
     workspaceIds: string[];
-    enrollmentId?: string;
-    generation?: number;
+    enrollmentId: string;
+    generation: number;
     ttlSeconds?: number;
     jti?: string;
     now?: number;
@@ -122,10 +162,7 @@ type ExpectedHostTunnel = {
     workspaceIds: string[];
 };
 export declare function isHostGeneration(value: unknown): value is number;
-export declare function isRelayClaimPair(input: {
-    access?: unknown;
-    backing?: unknown;
-}): input is RelayClaimPair;
+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
@@ -138,18 +175,15 @@ export type RelayKey = CryptoKey | Uint8Array | RelayKeyResolver;
  *
  * `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.
+ * 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.
  *
- * 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.
+ * 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>;
 /**
@@ -162,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 {};

package/dist/cloudflare.d.ts

@@ -1,54 +1,17 @@
 import { type AuthorizedWorkspaceRelayRequest, type WorkspaceRelayOptions } from "./server";
+import { type SessionHostNamespace } from "./session-host-forwarding";
 export type WorkspaceRelayDurableObjectId = unknown;
 export type WorkspaceRelayDurableObjectStub = {
     fetch: (request: Request) => Promise<Response>;
 };
 export type WorkspaceRelayDurableObjectGetOptions = {
+    /** Cloudflare's placement hint, honoured on the room's first creation only: beside the workspace's runtime (`workspaceRelayRoomPlacement`). */
     locationHint?: string;
 };
 export type WorkspaceRelayDurableObjectNamespace = {
     idFromName: (name: string) => WorkspaceRelayDurableObjectId;
     get: (id: WorkspaceRelayDurableObjectId, options?: WorkspaceRelayDurableObjectGetOptions) => WorkspaceRelayDurableObjectStub;
 };
-export declare const DEFAULT_RELAY_LOCATION_HINT = "apac";
-/**
- * The complete set of Cloudflare Durable Object location hints.
- *
- * Cloudflare rejects an unknown hint, and a rejected `get()` fails the request —
- * so an unrecognised region must fall back rather than be passed through. This
- * list is the validator for that.
- */
-export declare const RELAY_LOCATION_HINTS: readonly ["wnam", "enam", "sam", "weur", "eeur", "apac", "oc", "afr", "me"];
-export type RelayLocationHint = typeof RELAY_LOCATION_HINTS[number];
-/** A workspace region carried on the request, if the caller supplied one. */
-export declare const RELAY_REGION_HEADER = "x-claxedo-workspace-region";
-/**
- * Chooses the location hint for a workspace's Durable Object.
- *
- * This decision is PERMANENT: a DO's location is fixed at first creation and
- * never migrates, so a workspace created with the wrong hint pays the extra
- * ocean crossing on every frame for its entire life. That is why an
- * unrecognised value falls back to the configured default instead of being
- * passed through or guessed at.
- *
- * Precedence, most authoritative first:
- *  1. the workspace's own region (header or `?region=`), which is what the
- *     control plane knows and the only signal tied to the WORKSPACE rather than
- *     to whoever happens to be connecting first;
- *  2. the requesting user's Cloudflare edge country, a decent proxy when the
- *     workspace has no region yet;
- *  3. the deployment-wide configured hint (`CLAXEDO_RELAY_LOCATION_HINT`), then
- *     `DEFAULT_RELAY_LOCATION_HINT`.
- */
-export declare function relayLocationHint(input: {
-    configured?: string;
-    region?: string;
-    country?: string;
-}): string;
-/** The workspace region a request declares, if any. */
-export declare function relayRequestRegion(request: Request): string | undefined;
-/** The Cloudflare edge country for the request, when running on Cloudflare. */
-export declare function relayRequestCountry(request: Request): string | undefined;
 export type WorkspaceRelayDurableObjectEnv = Record<string, unknown>;
 export type WorkspaceRelayDurableObjectGatewayOptions = {
     bindingName?: string;
@@ -77,6 +40,7 @@ export type WorkspaceRelayDurableObjectConnectWebSocket = (url: string, init: {
     headers: Record<string, string>;
 }) => WorkspaceRelayDurableObjectSocket | Promise<WorkspaceRelayDurableObjectSocket>;
 export type WorkspaceRelayDurableObjectRoomOptions = WorkspaceRelayOptions & {
+    sessionHost?: SessionHostNamespace;
     createWebSocketPair?: () => WorkspaceRelayDurableObjectSocketPair;
     connectWebSocket?: WorkspaceRelayDurableObjectConnectWebSocket;
     hibernation?: WorkspaceRelayDurableObjectHibernation;
@@ -89,6 +53,15 @@ export type WorkspaceRelayDurableObjectRoomOptions = WorkspaceRelayOptions & {
     tunnelResponseBodyMaxBytes?: number;
     slowConsumerHighWaterMarkBytes?: number;
     slowConsumerTimeoutMs?: number;
+    /**
+     * How often established client WebSockets are re-checked for revocation.
+     * 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
+     * gets `resolverOutageGraceAttempts` and never extends the socket past the
+     * token's `exp`, which the watcher enforces locally.
+     */
     runtimeAccessTokenActiveCheckIntervalMs?: number;
     workspaceTargetActiveCheckIntervalMs?: number;
     /**
@@ -154,13 +127,12 @@ export type WorkspaceRelaySocketAttachment = {
     hostId: string;
     workspaceIds: string[];
     connectedAt: number;
-    /** Fence pair from the admitting Host Tunnel Token; absent on sockets attached before the fence existed. */
-    enrollmentId?: string;
-    generation?: number;
+    enrollmentId: string;
+    generation: number;
     /** Consecutive unavailable generation lookups, persisted so hibernation cannot reset the outage grace. */
     generationCheckFailures?: number;
 } | {
-    kind: "user-hosted-client";
+    kind: "host-tunnel-client";
     channelId: string;
     claims: RuntimeAccessAttachmentClaims;
     target: WorkspaceRelayTargetAttachment;
@@ -204,8 +176,6 @@ export declare function relayFrameDiagnostics(data: unknown): Promise<{
 }>;
 export declare function workspaceRelayDurableObjectRoomName(workspaceId: string): string;
 export declare function workspaceRelayDurableObjectWorkspaceId(request: Request): string | undefined;
-export declare function setWorkspaceRelayAppOrigins(raw: string | undefined): void;
-export declare function setWorkspaceRelayAllowedOrigins(raw: string | undefined): void;
 export declare function createWorkspaceRelayDurableObjectGateway(options?: WorkspaceRelayDurableObjectGatewayOptions): {
     fetch(request: Request, env?: WorkspaceRelayDurableObjectEnv): Promise<Response>;
 };

package/dist/cors-origins.d.ts

@@ -1,3 +1,5 @@
 export declare const DEFAULT_RELAY_APP_ORIGINS: string[];
+/** Request headers a browser may send on relayed workspace requests, as the `access-control-allow-headers` value. */
+export declare const RELAY_ALLOWED_REQUEST_HEADERS: string;
 export declare function parseAllowedOrigins(raw: string | undefined): string[] | undefined;
 export declare function createOriginMatcher(patterns: string[]): (origin: string) => boolean;

package/dist/directory.d.ts

@@ -11,56 +11,23 @@ export type HostTunnelPresence = {
     expiresAt: number;
 };
 /**
- * Presence is keyed by (host, workspace): one host may hold a separate tunnel
- * per workspace on a Bun relay, and a later registration for a workspace takes
- * that workspace over without touching the host's other entries. `recordPong`
- * and `disconnectHost` take the optional workspace set for the same reason —
- * without it they act on every entry of the host, which is what a
- * single-workspace Cloudflare room wants.
+ * Presence is keyed by (host, workspace), so a later registration for a
+ * workspace takes that workspace over without touching the host's other
+ * entries. `recordPong` and `disconnectHost` act on every entry of the host.
  */
 export type WorkspaceRelayDirectory = {
     registerHostTunnel(input: {
         hostId: string;
         workspaceIds: string[];
     }): HostTunnelPresence;
-    recordPong(hostId: string, workspaceIds?: string[]): HostTunnelPresence | undefined;
-    disconnectHost(hostId: string, workspaceIds?: string[]): void;
+    recordPong(hostId: string): HostTunnelPresence | undefined;
+    disconnectHost(hostId: string): void;
     activeHost(input: {
         hostId: string;
         workspaceId: string;
     }): HostTunnelPresence | undefined;
-    /**
-     * Manually run an expiry sweep over the presence map. Removes any entry
-     * whose `expiresAt <= now()`. Safe to call on a fresh/empty directory.
-     * Useful in tests; the production path runs this on a timer (see
-     * `sweepIntervalMs`).
-     */
-    sweep(): void;
-    /**
-     * Stop the active sweep timer (if one was started). Safe to call multiple
-     * times and on directories that were created with `sweepIntervalMs: 0`.
-     */
-    dispose(): void;
-    /**
-     * Count of hosts with at least one non-expired presence entry, taken as a
-     * snapshot without evicting. Surfaced via `/metrics` as
-     * `directory.activeHostCount`.
-     */
-    size(): number;
 };
 export declare function createWorkspaceRelayDirectory(options?: {
     ttlMs?: number;
     now?: () => number;
-    /**
-     * Interval in milliseconds at which a background sweep runs to evict
-     * expired host presence entries. Defaults to 30_000. Set to `0` to disable
-     * the timer entirely (useful for tests; callers can still drive cleanup
-     * manually via `sweep()`).
-     */
-    sweepIntervalMs?: number;
 }): WorkspaceRelayDirectory;
-/**
- * Convenience companion to `createWorkspaceRelayDirectory` for callers that
- * prefer a free function over a method. Equivalent to `directory.dispose()`.
- */
-export declare function disposeWorkspaceRelayDirectory(directory: WorkspaceRelayDirectory): void;

package/dist/gateway-placement.d.ts

@@ -0,0 +1,7 @@
+import type { WorkspaceRelayDurableObjectEnv } from "./cloudflare";
+/**
+ * Where the gateway creates the room of the request's workspace. The room's
+ * location is fixed at its first creation and never migrates, so this
+ * decision is permanent for the workspace.
+ */
+export declare function workspaceRelayRoomPlacement(request: Request, env: WorkspaceRelayDurableObjectEnv, workspaceId: string): Promise<import("./relay-location").RelayRoomPlacement>;

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

@@ -0,0 +1,7 @@
+export type HostTunnelFailureCode = "host_tunnel_timeout" | "host_tunnel_response_body_too_large" | "host_tunnel_unavailable";
+export declare function hostTunnelFailure(code: HostTunnelFailureCode): Error & {
+    code: HostTunnelFailureCode;
+    status: number;
+    retryable: boolean;
+};
+export declare function hostTunnelFailureResponse(error: unknown): Response;

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

@@ -0,0 +1,29 @@
+import type { RelayBacking } from "./auth";
+/**
+ * Whether a relay target is reached through a host tunnel.
+ *
+ * A `local-worktree` placement runs on an enrolled machine that dials the
+ * relay and multiplexes its traffic over that one socket; a `cloud-vm`
+ * placement runs on the provisioner's machine, which the relay reaches by a
+ * direct upstream connection.
+ */
+export declare function isHostTunnelTarget(target: {
+    backing: RelayBacking;
+}): boolean;
+export type WorkspaceRelaySocketKind = "host-tunnel-client" | "client";
+export declare function socketKindFor(target: {
+    backing: RelayBacking;
+}): WorkspaceRelaySocketKind;
+/**
+ * Privacy rule: never forward the browser's `Cookie` header through a host
+ * tunnel. The host process runs on a machine somebody uses, whose cookie jar
+ * the browser may share (localhost dev tooling), so passing cookies verbatim
+ * 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;
+}, headers: Headers): Headers;

package/dist/http.d.ts

@@ -6,3 +6,7 @@ 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[];

package/dist/index.d.ts

@@ -1,5 +1,10 @@
 export * from "./auth";
 export * from "./cloudflare";
+export * from "./relay-cors";
 export * from "./cors-origins";
 export * from "./directory";
+export * from "./gateway-placement";
+export * from "./relay-location";
+export * from "./relay-target";
 export * from "./server";
+export * from "./resolver-clients";