@claxedo/workspace-relay 0.1.0

package/README.md

@@ -0,0 +1,135 @@
+# `@claxedo/workspace-relay`
+
+The Claxedo workspace relay — a single canonical bidirectional tunnel
+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.
+
+## 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.
+
+## Public surface
+
+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) | `createWorkspaceRelayServer`, 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` |
+
+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.
+
+## 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`.
+
+| 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_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. |
+| `NODE_ENV` | `production` / `development` / `test`. Switches the production fail-closed gate. |
+
+Token verification is pluggable today via the
+`RelayKey | RelayKeyResolver` pair on `verifyRuntimeAccessToken` and
+friends, **and** via the unified
+[`TokenVerifier`](../workspace-relay-protocol/src/token-verifier.ts)
+interface in `@claxedo/workspace-relay-protocol`. To swap the relay's
+auth backend in a self-hosted deployment:
+
+```ts
+import { createStaticTokenVerifier } from "@claxedo/workspace-relay-protocol"
+
+const verifier = createStaticTokenVerifier({
+  tokens: {
+    "tok-tenant-1": { subject: "u1", scopes: ["workspace:write"], claims: {} },
+  },
+})
+// Pass `verifier` into a future `WorkspaceRelayOptions.tokenVerifier`
+// option when the relay accepts custom verification backends directly.
+```
+
+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.
+
+## 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.
+
+## Seam: `internal-relay` vs `workspace-relay`
+
+| | `claxedo-server/src/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) |
+
+This split is deliberate: the relay never reads Convex or Clerk
+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 typecheck
+```
+
+The TS error baseline for this package is **0** — keep it that way.
+
+## Boundary rule
+
+Consumers outside this package import `@claxedo/workspace-relay` only —
+not `@claxedo/workspace-relay/src/...`. Direct deep-source imports
+break the package boundary. The check is
+
+```sh
+grep -rn "workspace-relay/src/" packages/claxedo-{server,app}/src
+```
+
+— required to return zero hits.

package/dist/auth.d.ts

@@ -0,0 +1,107 @@
+import { type JWTVerifyGetKey } from "jose";
+declare const algorithms: readonly ["EdDSA", "ES256", "RS256"];
+export declare const runtimeAccessTokenIssuer = "claxedo-control-plane";
+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 RelayAccess = "cloud" | "user-hosted";
+export type RelayBacking = "local-worktree" | "cloud-vm";
+export type RelayJwtAlgorithm = (typeof algorithms)[number];
+export type RelayRole = "viewer" | "editor" | "admin" | "owner";
+export type RuntimeAccessTokenClaims = {
+    iss: typeof runtimeAccessTokenIssuer;
+    aud: typeof runtimeAccessTokenAudience;
+    sub: string;
+    org_id: string;
+    workspace_id: string;
+    host_id: string;
+    role: RelayRole;
+    exp: number;
+    iat: number;
+    jti: string;
+};
+export type RelayHostTokenClaims = {
+    iss: typeof relayHostTokenIssuer;
+    aud: typeof relayHostTokenAudience;
+    sub: string;
+    org_id: string;
+    workspace_id: string;
+    host_id: string;
+    access: RelayAccess;
+    backing: RelayBacking;
+    exp: number;
+    iat: number;
+    jti: string;
+};
+export type HostTunnelTokenClaims = {
+    iss: typeof runtimeAccessTokenIssuer;
+    aud: typeof hostTunnelTokenAudience;
+    sub: string;
+    host_id: string;
+    workspace_ids: string[];
+    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);
+}
+type RuntimeInput = {
+    subject: string;
+    orgId: string;
+    workspaceId: string;
+    hostId: string;
+    role: RelayRole;
+    ttlSeconds?: number;
+    jti?: string;
+    now?: number;
+};
+type RelayHostInput = RuntimeInput & {
+    access: RelayAccess;
+    backing: RelayBacking;
+    /**
+     * 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
+     * minted RHT must carry the same `kid` that the relay publishes at
+     * `/.well-known/jwks.json`. When omitted, the header has no `kid` and
+     * verifiers fall back to single-key matching (PEM env-var path).
+     */
+    kid?: string;
+};
+type HostTunnelInput = {
+    subject: string;
+    hostId: string;
+    workspaceIds: string[];
+    ttlSeconds?: number;
+    jti?: string;
+    now?: number;
+};
+type ExpectedTarget = {
+    workspaceId: string;
+    hostId?: string;
+};
+type ExpectedHostTunnel = {
+    hostId: string;
+    workspaceIds: string[];
+};
+/**
+ * Resolver function returned by `createRemoteJWKSet` / `createLocalJWKSet`.
+ * Accepted by `jwtVerify` directly — jose dispatches based on whether the
+ * argument is callable.
+ */
+export type RelayKeyResolver = JWTVerifyGetKey;
+export type RelayKey = CryptoKey | Uint8Array | RelayKeyResolver;
+/**
+ * Mint variants accept only a signing key — never a resolver. Resolvers are
+ * verification-only. This narrowed alias keeps the mint signatures unchanged.
+ */
+type RelaySigningKey = CryptoKey | Uint8Array;
+export declare function mintRuntimeAccessToken(input: RuntimeInput, key: RelaySigningKey, alg: RelayJwtAlgorithm): Promise<string>;
+export declare function verifyRuntimeAccessToken(token: string, key: RelayKey, expected: ExpectedTarget): Promise<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>;
+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 {};

package/dist/bun.d.ts

@@ -0,0 +1,107 @@
+import { type WorkspaceRelayOptions } from "./server";
+type RelayClientWebSocketData = {
+    kind: "client";
+    upstreamUrl: string;
+    headers: Record<string, string>;
+    queue: Array<string | Buffer<ArrayBuffer>>;
+    upstream?: WebSocket;
+};
+type RelayHostTunnelWebSocketData = {
+    kind: "host-tunnel";
+    hostId: string;
+    workspaceIds: string[];
+    pending: Map<string, PendingTunnelHttpResponse>;
+    channels: Map<string, Bun.ServerWebSocket<RelayUserHostedClientWebSocketData>>;
+    heartbeat?: ReturnType<typeof setInterval>;
+    messageBuffer: string;
+};
+type RelayUserHostedClientWebSocketData = {
+    kind: "user-hosted-client";
+    hostId: string;
+    workspaceId: string;
+    channelId: string;
+    path: string;
+    relayHostToken: string;
+};
+type RelayWebSocketData = RelayClientWebSocketData | RelayHostTunnelWebSocketData | RelayUserHostedClientWebSocketData;
+type PendingTunnelHttpResponse = {
+    controller: ReadableStreamDefaultController<Uint8Array>;
+    stream: ReadableStream<Uint8Array>;
+    resolve: (response: Response) => void;
+    reject: (error: Error) => void;
+    timeout: ReturnType<typeof setTimeout>;
+    pendingChunks: Uint8Array[];
+    bytesQueued: number;
+    slowConsumerTimeout?: ReturnType<typeof setTimeout>;
+    responseStarted: boolean;
+};
+export type WorkspaceRelayHostTunnelOptions = {
+    authorizeHostTunnel?: (request: Request, input: {
+        hostId: string;
+        workspaceIds: string[];
+    }) => boolean | Promise<boolean>;
+    hostTunnelPingIntervalMs?: number;
+    hostTunnelStateDebounceMs?: number;
+};
+export type WorkspaceRelayBackpressureOptions = {
+    slowConsumerHighWaterMarkBytes?: number;
+    slowConsumerTimeoutMs?: number;
+};
+export type WorkspaceRelayBunOptions = WorkspaceRelayHostTunnelOptions & WorkspaceRelayBackpressureOptions;
+/**
+ * T9: drain controller exposed by `createWorkspaceRelayBun`.
+ *
+ * On SIGTERM the operator (see `installShutdownDrainHandler` in main.ts)
+ * flips `setDraining(true)`; from that point onward the relay
+ *   - returns 503 from `/health` so Fly removes the instance from routing
+ *   - rejects new HTTP requests with 503 (`relay_draining`) before doing auth
+ *   - rejects new host-tunnel WebSocket upgrades with 503
+ *   - leaves all existing in-flight HTTP requests, host tunnels, and
+ *     multiplexed WS channels alone so they can complete naturally
+ *
+ * `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.
+ */
+export type WorkspaceRelayBunDrainController = {
+    isDraining(): boolean;
+    setDraining(value: boolean): void;
+    pendingCount(): number;
+    waitForDrain(timeoutMs: number): Promise<{
+        drained: boolean;
+        remaining: number;
+    }>;
+};
+export declare function getFragmentationStats(): {
+    fragmentsBuffered: number;
+    oversizedClosed: number;
+};
+export declare function resetFragmentationStats(): void;
+export declare function getSlowConsumerStats(): {
+    overflowEvents: number;
+    timerFired: number;
+    droppedRequests: number;
+};
+export declare function resetSlowConsumerStats(): void;
+export declare function __resetHostTunnelStateDebounce(): void;
+declare function enqueueChunkWithBackpressure(input: {
+    ws: Bun.ServerWebSocket<RelayHostTunnelWebSocketData>;
+    requestId: string;
+    entry: PendingTunnelHttpResponse;
+    chunk: Uint8Array;
+    slowConsumerTimeoutMs: number;
+}): void;
+export declare const __slowConsumerInternalsForTest: {
+    enqueueChunkWithBackpressure: typeof enqueueChunkWithBackpressure;
+};
+export declare function createWorkspaceRelayBun(options: WorkspaceRelayOptions, bunOptions?: WorkspaceRelayBunOptions): {
+    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;
+    };
+    drain: WorkspaceRelayBunDrainController;
+};
+export {};

package/dist/directory.d.ts

@@ -0,0 +1,55 @@
+export type HostTunnelPresence = {
+    hostId: string;
+    workspaceIds: string[];
+    connectedAt: number;
+    lastPongAt: number;
+    expiresAt: number;
+};
+export type WorkspaceRelayDirectory = {
+    registerHostTunnel(input: {
+        hostId: string;
+        workspaceIds: string[];
+    }): HostTunnelPresence;
+    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;
+    /**
+     * T31: count of currently-active (non-expired) host presence entries.
+     * Equivalent to running `sweep()` then returning the residual map size, but
+     * implemented as a single pass without mutating eviction state when the
+     * caller only wants a snapshot. Surfaced via the `/metrics` endpoint 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/http.d.ts

@@ -0,0 +1,7 @@
+export declare function bearerToken(header: string | null | undefined): string | undefined;
+export declare function errorBody(code: string, message: string): {
+    error: {
+        code: string;
+        message: string;
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./auth";
+export * from "./bun";
+export * from "./directory";
+export * from "./server";