@claxedo/workspace-relay 0.1.0 → 0.5.0

package/dist/server.d.ts

@@ -1,6 +1,6 @@
 import { Hono } from "hono";
-import type { TokenVerifier } from "@claxedo/workspace-relay-protocol";
-import { type RelayAccess, type RelayBacking, type RelayJwtAlgorithm, type RelayKey, type RelayRole, type RuntimeAccessTokenClaims } from "./auth";
+import type { RuntimeAccessVerifierClaims, TokenVerifier } from "@claxedo/workspace-relay-protocol";
+import { type RelayClaimPair, type RelayJwtAlgorithm, type RelayKey, type RelayRole, type RuntimeAccessTokenClaims } from "./auth";
 import type { WorkspaceRelayDirectory } from "./directory";
 export type RelayHostPublicKey = {
     publicKey: CryptoKey | Uint8Array;
@@ -10,9 +10,8 @@ export type WorkspaceRelayTarget = {
     workspaceId: string;
     hostId: string;
     baseUrl: string;
-    access: RelayAccess;
-    backing: RelayBacking;
-};
+    upstreamHeaders?: Record<string, string>;
+} & RelayClaimPair;
 export type RuntimeAccessTokenActiveResult = {
     active: true;
 } | {
@@ -20,6 +19,29 @@ export type RuntimeAccessTokenActiveResult = {
     code: string;
     reason: string;
 };
+export type RevocationLookupArgs = {
+    jti: string;
+    workspaceId: string;
+    hostId: string;
+};
+export type RevocationLookup = (args: RevocationLookupArgs) => Promise<RuntimeAccessTokenActiveResult>;
+export type CachedRevocationOptions = {
+    /** TTL in milliseconds for cached revocation responses. Defaults to 10_000. */
+    ttlMs?: number;
+    /** Clock injection for tests. Defaults to `Date.now`. */
+    now?: () => number;
+};
+export type TargetLookupArgs = {
+    workspaceId: string;
+    hostId: string;
+};
+export type TargetLookup = (args: TargetLookupArgs) => Promise<WorkspaceRelayTarget | undefined>;
+export type CachedTargetOptions = {
+    /** TTL in milliseconds for positive target responses. Defaults to 5_000. */
+    ttlMs?: number;
+    /** Clock injection for tests. Defaults to `Date.now`. */
+    now?: () => number;
+};
 export type WorkspaceRelayAuditEvent = {
     action: "relay.request.accepted" | "relay.request.denied" | "relay.request.suppressed_summary" | "host_tunnel.connected" | "host_tunnel.disconnected";
     result: "allow" | "deny";
@@ -39,6 +61,13 @@ export type WorkspaceRelayAuditEvent = {
 };
 export type WorkspaceRelayAuthOptions = {
     runtimeAccessKey: RelayKey;
+    /**
+     * Cache signature/introspection-verified Runtime Access Token claims by the
+     * full token string. Revocation/active checks, role enforcement, and target
+     * resolution still run for every request after this cache hit. Defaults to
+     * 10s and is always capped by the token's exp claim minus skew.
+     */
+    runtimeAccessTokenCacheTtlMs?: number;
     /**
      * P-shared: optional override for runtime-access-token verification.
      *
@@ -54,7 +83,7 @@ export type WorkspaceRelayAuthOptions = {
      * See `@claxedo/workspace-relay-protocol/token-verifier` for the
      * `HttpTokenVerifier` and `StaticTokenVerifier` reference impls.
      */
-    tokenVerifier?: TokenVerifier;
+    tokenVerifier?: TokenVerifier<RuntimeAccessVerifierClaims>;
     isRuntimeAccessTokenActive?: (claims: RuntimeAccessTokenClaims) => RuntimeAccessTokenActiveResult | Promise<RuntimeAccessTokenActiveResult>;
 };
 export type WorkspaceRelayHostTokenOptions = {
@@ -75,10 +104,18 @@ export type WorkspaceRelayHostTokenOptions = {
      * `relayHostPublicKeys` so JWKS and mint agree by construction.
      */
     relayHostMintKid?: string;
+    /**
+     * Cache Relay Host Tokens minted from an already-verified Runtime Access
+     * Token. The relay still verifies the RAT, checks revocation, enforces role,
+     * and resolves the target on every request; this only avoids repeated signing
+     * work for the same jti/target after those gates pass. Defaults to 30s.
+     */
+    relayHostTokenCacheTtlMs?: number;
 };
 export type WorkspaceRelayRoutingOptions = {
     resolveTarget: (claims: RuntimeAccessTokenClaims) => WorkspaceRelayTarget | Promise<WorkspaceRelayTarget | undefined>;
     fetch?: typeof fetch;
+    forwardTimeoutMs?: number;
     directory?: WorkspaceRelayDirectory;
 };
 export type WorkspaceRelayDrainOptions = {
@@ -125,18 +162,17 @@ export type WorkspaceRelayMetricsOptions = {
     /**
      * T31: returns the remote IP of the inbound `/metrics` request (used to
      * gate access to the loopback when `metricsToken` is unset). When this is
-     * also unset, the relay falls back to "allow" for dev convenience — the
-     * production deploy is expected to either set `metricsToken` or wire this
-     * resolver to `Bun.Server.requestIP`.
+     * also unset, `/metrics` fails closed. The Bun adapter wires this resolver
+     * through `Bun.Server.requestIP`; other callers should set either this or
+     * `metricsToken`.
      */
     metricsRemoteAddress?: (request: Request) => string | undefined;
     /**
      * T31: optional providers used to assemble the `/metrics` response body. The
-     * fragmentation/slow-consumer counters live in the bun adapter (module-
-     * scoped state in `bun.ts`), and the in-flight pending count lives on the
-     * drain controller — `createWorkspaceRelayBun` wires these to make ops
-     * counters visible on `/metrics` without giving `server.ts` a hard
-     * dependency on the bun-only state.
+     * fragmentation/slow-consumer counters live in the bun adapter's per-handler
+     * telemetry, and the in-flight pending count lives on the drain controller.
+     * `createWorkspaceRelayBun` wires these to make ops counters visible on
+     * `/metrics` without giving `server.ts` a hard dependency on bun-only state.
      */
     metricsSources?: WorkspaceRelayMetricsSources;
 };
@@ -183,6 +219,28 @@ export type AuthorizedWorkspaceRelayRequest = {
     relayHostToken: string;
     path: string;
 };
+export type WorkspaceRelayAuthorizeTrace = {
+    span<T>(name: string, run: () => Promise<T>): Promise<T>;
+};
+export type WorkspaceRelayTracePhase = {
+    name: string;
+    ms: number;
+};
+export type WorkspaceRelayTrace = WorkspaceRelayAuthorizeTrace & {
+    phases: WorkspaceRelayTracePhase[];
+};
+/**
+ * Wraps a revocation lookup with a small in-memory cache keyed by `jti`.
+ * Both positive and negative results are cached for the full TTL; revocation
+ * lag is bounded by the same TTL by design. Concurrent misses share one lookup.
+ */
+export declare function createCachedRevocationClient(inner: RevocationLookup, options?: CachedRevocationOptions): RevocationLookup;
+/**
+ * Caches positive workspace target lookups by workspace+host. Missing targets
+ * are only coalesced while in flight, not retained, so cold-start polling can
+ * see readiness as soon as the control plane records it.
+ */
+export declare function createCachedTargetClient(inner: TargetLookup, options?: CachedTargetOptions): TargetLookup;
 export type WorkspaceRelayForwardHeadersOptions = {
     /**
      * When true, also strip the `Cookie` request header. User-hosted workspaces
@@ -194,21 +252,31 @@ export type WorkspaceRelayForwardHeadersOptions = {
      * is to NOT strip cookies. T26.
      */
     userHosted?: boolean;
+    upstreamHeaders?: Record<string, string>;
+};
+export type WorkspaceRelayForwardRequestInitOptions = WorkspaceRelayForwardHeadersOptions & {
+    signal?: AbortSignal;
 };
 export declare function workspaceRelayTargetUrl(target: WorkspaceRelayTarget, path: string, search: string): URL;
 export declare function workspaceRelayForwardHeaders(input: Headers, relayHostToken: string, workspaceId: string, options?: WorkspaceRelayForwardHeadersOptions): Headers;
+export declare function workspaceRelayForwardRequestInit(request: Request, relayHostToken: string, workspaceId: string, options?: WorkspaceRelayForwardRequestInitOptions): RequestInit;
 /**
  * T16: dispose the sampler's periodic flush timer for a given options object.
  * Tests call this in cleanup so the bun process can exit.
  */
 export declare function disposeAuditSampler(options: WorkspaceRelayOptions): void;
-export declare function authorizeWorkspaceRelayRequest(options: WorkspaceRelayOptions, request: Request, workspaceId: string): Promise<{
+export declare function createWorkspaceRelayTrace(): WorkspaceRelayTrace;
+export declare function workspaceRelayServerTiming(trace: WorkspaceRelayTrace): string;
+export declare function workspaceRelayTimingResponse(response: Response, trace: WorkspaceRelayTrace): Response;
+export declare function authorizeWorkspaceRelayRequest(options: WorkspaceRelayOptions, request: Request, workspaceId: string, trace?: WorkspaceRelayAuthorizeTrace): Promise<{
     ok: true;
     request: AuthorizedWorkspaceRelayRequest;
 } | {
     ok: false;
     response: Response;
+    code: string;
 }>;
+export declare function forwardWorkspaceRelayRequest(request: Request, target: WorkspaceRelayTarget, relayHostToken: string, path: string, requestFetch: typeof fetch, timeoutMs: number, trace?: WorkspaceRelayAuthorizeTrace): Promise<Response>;
 export type WorkspaceRelayApp = Hono & {
     /**
      * T16: clear the sampler's periodic flush timer. Tests must call this so

package/dist/worker.d.ts

@@ -0,0 +1,50 @@
+import { type WorkspaceRelayDurableObjectNamespace, type WorkspaceRelayDurableObjectRoomOptions, type WorkspaceRelayDurableObjectSocket } from "./cloudflare";
+import type { RuntimeAccessTokenActiveResult, WorkspaceRelayTarget } from "./server";
+export type WorkspaceRelayWorkerEnv = Record<string, unknown> & {
+    WORKSPACE_RELAY_ROOM?: WorkspaceRelayDurableObjectNamespace;
+    CLAXEDO_RELAY_RESOLVER_URL?: string;
+    CLAXEDO_CENTRAL_URL?: string;
+    CLAXEDO_RELAY_RESOLVER_TOKEN?: string;
+    CLAXEDO_CONTROL_PLANE_JWKS_URL?: string;
+    CLAXEDO_RUNTIME_ACCESS_TOKEN_PUBLIC_KEY_PEM?: string;
+    CLAXEDO_RELAY_HOST_SIGNING_KEY_PEM?: string;
+    CLAXEDO_RELAY_HOST_PUBLIC_KEY_PEM?: string;
+    CLAXEDO_RELAY_HOST_NEXT_PUBLIC_KEY_PEM?: string;
+    CLAXEDO_RELAY_HOST_KID?: string;
+    CLAXEDO_RELAY_HOST_NEXT_KID?: string;
+    CLAXEDO_RELAY_AUDIT_ACCEPT_SAMPLE_RATE?: string;
+    CLAXEDO_RELAY_TUNNEL_CHANNEL_CAP?: string;
+    CLAXEDO_RELAY_TRACE_SAMPLE_RATE?: string;
+    CLAXEDO_RELAY_REVOCATION_CACHE_TTL_MS?: string;
+    CLAXEDO_RELAY_TARGET_CACHE_TTL_MS?: string;
+    CLAXEDO_APP_ORIGINS?: string;
+};
+type ResolverClient = {
+    target(workspaceId: string, hostId: string): Promise<WorkspaceRelayTarget | undefined>;
+    revocation(args: {
+        jti: string;
+        workspaceId: string;
+        hostId: string;
+    }): Promise<RuntimeAccessTokenActiveResult>;
+};
+type ResolverFetch = (url: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export declare function workspaceRelayWorkerResolverUrl(env: WorkspaceRelayWorkerEnv): string;
+export declare function workspaceRelayWorkerResolverClient(env: WorkspaceRelayWorkerEnv, fetcher?: ResolverFetch): ResolverClient;
+export declare function workspaceRelayDurableObjectOptions(env: WorkspaceRelayWorkerEnv): Promise<WorkspaceRelayDurableObjectRoomOptions>;
+export declare class WorkspaceRelayRoom {
+    private state;
+    private env;
+    private room?;
+    private loading?;
+    constructor(state: unknown, env: WorkspaceRelayWorkerEnv);
+    private hibernation;
+    private loadRoom;
+    fetch(request: Request): Promise<Response>;
+    webSocketMessage(socket: WorkspaceRelayDurableObjectSocket, message: string | ArrayBuffer): Promise<void>;
+    webSocketClose(socket: WorkspaceRelayDurableObjectSocket, code: number, reason: string, wasClean: boolean): Promise<void>;
+    webSocketError(socket: WorkspaceRelayDurableObjectSocket, error: unknown): Promise<void>;
+}
+declare const _default: {
+    fetch(request: Request, env: WorkspaceRelayWorkerEnv): Promise<Response>;
+};
+export default _default;

package/package.json

@@ -1,13 +1,23 @@
 {
   "name": "@claxedo/workspace-relay",
-  "version": "0.1.0",
+  "version": "0.5.0",
   "type": "module",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./dist/index.mjs",
+      "development": "./dist/index.mjs",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
   "bin": {
-    "workspace-relay": "./dist/main.mjs"
+    "workspace-relay": "dist/main.mjs"
   },
   "files": [
+    "README.md",
     "dist"
   ],
   "publishConfig": {
@@ -22,15 +32,15 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@claxedo/workspace-relay-protocol": "^0.1.0",
+    "@claxedo/workspace-relay-protocol": "0.5.0",
     "hono": "4.10.7",
     "jose": "6.0.11"
   },
   "devDependencies": {
-    "@tsconfig/node-lts": "^22.0.0",
-    "@types/bun": "catalog:",
-    "esbuild": "^0.25.0",
-    "tsx": "^4.0.0",
-    "typescript": "catalog:"
+    "@tsconfig/node-lts": "22.0.4",
+    "@types/bun": "1.3.13",
+    "esbuild": "0.25.12",
+    "tsx": "4.22.3",
+    "typescript": "5.8.2"
   }
 }