@claxedo/workspace-relay 0.5.1 → 0.5.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Claxedo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -5,6 +5,11 @@ 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
@@ -13,6 +18,74 @@ 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
+
+```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.
+
 ## Deployment Security
 
 The relay is a public edge service for workspace traffic, but it is not the
@@ -125,8 +198,17 @@ production fail-closed gate at `src/main.ts`.
 | `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. |
 
+Cloudflare Worker tracing knobs (Durable Object deployment):
+
+| Env var | Purpose |
+| --- | --- |
+| `CLAXEDO_RELAY_TRACE_SAMPLE_RATE` | 0–1 sampling rate for request traces. Only sampled requests emit `Server-Timing` phase headers and structured trace logs; unsampled responses carry just the `x-claxedo-trace-id` correlation header. Defaults to 0 (off). |
+| `CLAXEDO_RELAY_TRACE_FORCE_SECRET` | Optional operator secret. When set, a request with `x-claxedo-relay-trace: <secret>` forces sampling for that request (targeted debugging). Unset (default) means the force header is ignored — clients can never force tracing or timing emission. |
+| `CLAXEDO_APP_ORIGINS` | Cloudflare-only, **additive** origin entries layered on top of the base allowlist (kept for existing deploys; prefer `CLAXEDO_RELAY_ALLOWED_ORIGINS` for full control). |
+
 Token verification is pluggable today via the
 `RelayKey | RelayKeyResolver` pair on `verifyRuntimeAccessToken` and
 friends, **and** via the unified

package/dist/auth.d.ts

@@ -35,6 +35,7 @@ export type RelayHostTokenClaims = {
     org_id: string;
     workspace_id: string;
     host_id: string;
+    role: RelayRole;
     exp: number;
     iat: number;
     jti: string;

package/dist/cloudflare.d.ts

@@ -53,6 +53,7 @@ export type WorkspaceRelayDurableObjectRoomOptions = WorkspaceRelayOptions & {
     runtimeAccessTokenActiveCheckIntervalMs?: number;
     workspaceTargetActiveCheckIntervalMs?: number;
     traceSampleRate?: number;
+    traceForceHeaderSecret?: string;
     traceLog?: (event: WorkspaceRelayTraceLogEvent) => void;
     now?: () => number;
 };
@@ -98,6 +99,7 @@ export type WorkspaceRelayDurableObjectDrainController = {
 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>;
 };
@@ -110,6 +112,9 @@ export declare function createWorkspaceRelayDurableObjectRoom(options: Workspace
         hostTunnelCount: number;
         clientCount: number;
         hostIds: string[];
+        hostWorkspaceIds: {
+            [k: string]: string[];
+        };
     };
     drain: WorkspaceRelayDurableObjectDrainController;
 };

package/dist/cors-origins.d.ts

@@ -0,0 +1,3 @@
+export declare const DEFAULT_RELAY_APP_ORIGINS: string[];
+export declare function parseAllowedOrigins(raw: string | undefined): string[] | undefined;
+export declare function createOriginMatcher(patterns: string[]): (origin: string) => boolean;

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./auth";
 export * from "./bun";
 export * from "./cloudflare";
+export * from "./cors-origins";
 export * from "./directory";
 export * from "./server";