@claxedo/workspace-relay 0.8.0 → 0.10.1

package/dist/relay-audit.d.ts

@@ -0,0 +1,4 @@
+import type { WorkspaceRelayAuditEvent, WorkspaceRelayOptions } from "./server";
+/** Stops the flush timer for `options` and emits any suppressed count it still holds. */
+export declare function disposeAuditSampler(options: WorkspaceRelayOptions): void;
+export declare function audit(options: WorkspaceRelayOptions, event: WorkspaceRelayAuditEvent): Promise<void>;

package/dist/relay-cors.d.ts

@@ -0,0 +1,12 @@
+export declare function setWorkspaceRelayAppOrigins(raw: string | undefined): void;
+export declare function setWorkspaceRelayAllowedOrigins(raw: string | undefined): void;
+/**
+ * The browser-origin gate on workspace WebSocket upgrades, applied after token
+ * authorization and before the upgrade is granted. A request carrying NO
+ * `Origin` header is a non-browser client — browsers always send Origin on
+ * WebSocket upgrades — so there is no origin verdict to enforce and it is
+ * admitted.
+ */
+export declare function workspaceUpgradeOriginDenied(request: Request): Response | null;
+export declare function corsPreflight(request: Request): Response;
+export declare function withRelayResponseHeaders(request: Request, response: Response): Response;

package/dist/relay-location.d.ts

@@ -0,0 +1,93 @@
+export declare const DEFAULT_RELAY_LOCATION_HINT = "apac";
+/**
+ * Where a session's Durable Object lives, and so where the relay room of a
+ * workspace whose sessions run on their objects is created.
+ *
+ * A Durable Object is created near whoever first reaches it and never moves,
+ * so without a hint a session opened from India can land in HKG, where
+ * api.anthropic.com answers every request 403 `forbidden` "Request not
+ * allowed" whatever the credential. Every turn the object calls its model
+ * vendor and the control plane (D1 in ENAM, the API Worker pinned to
+ * aws:us-east-1), so it lives beside them rather than beside its first viewer.
+ *
+ * The room sits on the path of every request to the object and asks the
+ * control plane (IAD) for the token's revocation and the target on a cold
+ * start and every 10 s: from apac each lookup is ~220 ms, from enam ~10 ms,
+ * while the browser's path through the room is the same ~115 ms either way
+ * (docs/perf/pi-durable-latency-2026-10-18/README.md). A machine's room stays
+ * beside its machine, where those lookups would cost a browser in apac
+ * +220 ms a request.
+ */
+export declare const SESSION_HOST_LOCATION_HINT = "enam";
+/**
+ * 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;
+export type RelayRoomPlacement = {
+    locationHint: string;
+    /** The request's URL and headers with the placement inputs removed. */
+    url: string;
+    headers: Headers;
+};
+/**
+ * What the request's own credential says once its signature verifies for the
+ * room's workspace: the host it reaches. A `session-do:` host is the control
+ * plane's signed statement that the workspace's sessions run on their own
+ * Durable Objects.
+ */
+export type RelayPlacementCredential = {
+    hostId: string;
+};
+/**
+ * Where a workspace's room is created, decided from what the request declares
+ * and what its credential proves, and the request as the room should see it.
+ * The declaration is consumed here because the room forwards a request's
+ * remaining query and headers to the runtime, whose routes have no use for the
+ * relay's placement input.
+ *
+ * A credential naming a session's Durable Object places the room beside that
+ * object (`SESSION_HOST_LOCATION_HINT`), whatever the request declares: the
+ * host id is signed by the control plane, so no query parameter or header can
+ * drag the room elsewhere, and a forged token verifies for no workspace.
+ * Request-declared inputs (region, edge country) move the hint off the
+ * configured floor only when the credential verifies, so anonymous first-touch
+ * traffic cannot pin a workspace's room placement.
+ */
+export declare function relayRoomPlacement(request: Request, input: {
+    configured?: string;
+    credential: () => Promise<RelayPlacementCredential | undefined>;
+}): Promise<RelayRoomPlacement>;
+/** The Cloudflare edge country for the request, when running on Cloudflare. */
+export declare function relayRequestCountry(request: Request): string | undefined;

package/dist/relay-target.d.ts

@@ -0,0 +1,25 @@
+import { type RelayBacking } from "./auth";
+export type WorkspaceRelayTarget = {
+    workspaceId: string;
+    hostId: string;
+    baseUrl: string;
+    backing: RelayBacking;
+};
+export declare function parseWorkspaceRelayTarget(input: unknown): WorkspaceRelayTarget | undefined;
+/**
+ * Whether a resolved target's `baseUrl` names a destination the relay may
+ * forward to.
+ *
+ * A `cloud-vm` target is fetched over the network with the Relay Host Token
+ * attached, so it must be HTTPS — or HTTP to a loopback host, the only
+ * plaintext transport that cannot put the token on a network. A
+ * `local-worktree` target is reached over the host tunnel and its `baseUrl` is
+ * never fetched — the control plane sends the empty string — so only that
+ * placeholder or a well-formed HTTP(S) URL is admitted. A `durable-object`
+ * target is reached through the relay's own Durable Object binding, so it
+ * names no destination at all.
+ */
+export declare function isAllowedRelayTargetBaseUrl(target: {
+    baseUrl: string;
+    backing: RelayBacking;
+}): boolean;

package/dist/relay-trace.d.ts

@@ -0,0 +1,54 @@
+export declare const TRACE_ID_HEADER = "x-claxedo-trace-id";
+/**
+ * Set by a room on a sampled trace's response and consumed by the gateway: the
+ * gateway appends its own phases only behind this marker, never behind an
+ * upstream's `server-timing`, which a session host answers on every response.
+ */
+export declare const TRACE_SAMPLED_RESPONSE_HEADER = "x-claxedo-relay-sampled";
+export type WorkspaceRelayTraceLogEvent = {
+    event: "workspace_relay_request";
+    traceId: string;
+    workspaceId?: string;
+    routeKind: string;
+    method: string;
+    path: string;
+    status: number;
+    totalMs: number;
+    phases: Record<string, number>;
+};
+export type RelayTraceSampling = {
+    traceSampleRate?: number;
+    traceForceHeaderSecret?: string;
+    random?: () => number;
+};
+export type RelayTrace = {
+    id: string;
+    sampled: boolean;
+    startedAt: number;
+    routeKind: string;
+    phases: Array<{
+        name: string;
+        ms: number;
+    }>;
+};
+export declare function traceRequest(request: Request, routeKind: string, options: RelayTraceSampling): RelayTrace;
+export declare function traceSpan<T>(trace: RelayTrace | undefined, name: string, fn: () => Promise<T>): Promise<T>;
+export declare function tracedRequest(request: Request, trace: RelayTrace, forwarded?: {
+    url: string;
+    headers: Headers;
+}): Request;
+export declare function serverTiming(phases: ReadonlyArray<{
+    name: string;
+    ms: number;
+}>): string;
+/** The `relay.trace` frame a client that opted in with `x-claxedo-relay-ws-trace` receives once the upstream opens. */
+export declare function webSocketTraceFrame(upstreamStartedAt: number, queueTimes: readonly number[], openedAt: number): {
+    type: string;
+    wsUpstreamOpenMs: number;
+    queuedFrames: number;
+    maxQueuedDelayMs: number;
+};
+export declare function withTraceHeaders(response: Response, trace: RelayTrace): Response;
+export declare function logTrace(options: {
+    traceLog?: (event: WorkspaceRelayTraceLogEvent) => void;
+}, request: Request, workspaceId: string | undefined, trace: RelayTrace, response: Response): void;

package/dist/resolver-clients.d.ts

@@ -0,0 +1,116 @@
+import type { WorkspaceRelayTarget } from "./relay-target";
+export type RuntimeAccessTokenActiveResult = {
+    active: true;
+} | {
+    active: false;
+    code: string;
+    reason: string;
+};
+export declare function parseRuntimeAccessTokenActiveResult(input: unknown): RuntimeAccessTokenActiveResult | undefined;
+/**
+ * `GET /internal/relay/host-generation?enrollmentId=` as the control plane
+ * answers it: the enrollment's current serving generation, or 404 for an
+ * enrollment it does not know (`undefined` here).
+ */
+export type HostGenerationResult = {
+    enrollmentId: string;
+    generation: number;
+    revoked: boolean;
+};
+export type HostGenerationResolverLookupOptions = {
+    headers: Record<string, string>;
+    fetch?: (url: URL, init: RequestInit) => Promise<Response>;
+    /** Deadline per lookup; past it the lookup rejects, which the relay grades as unavailable. */
+    timeoutMs?: number;
+};
+export declare function createHostGenerationResolverLookup(url: string, options: HostGenerationResolverLookupOptions): HostGenerationLookup;
+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;
+};
+/**
+ * `generation` is the value the caller holds (a token's, a socket's). The
+ * cached client uses it to decide whether a cached answer may stand in for a
+ * fresh one; an uncached lookup ignores it. Resolves `undefined` for an
+ * unknown enrollment and THROWS when the control plane cannot be reached —
+ * the throw is the "unavailable" signal every consumer grades separately.
+ */
+export type HostGenerationLookupArgs = {
+    enrollmentId: string;
+    generation: number;
+};
+export type HostGenerationLookup = (args: HostGenerationLookupArgs) => Promise<HostGenerationResult | undefined>;
+export type CachedHostGenerationOptions = {
+    /** TTL in milliseconds for cached host-generation answers. Defaults to 10_000. */
+    ttlMs?: number;
+    /** Clock injection for tests. Defaults to `Date.now`. */
+    now?: () => number;
+};
+export type TargetLookupArgs = {
+    workspaceId: string;
+    hostId: string;
+    routingId?: string;
+};
+export type TargetLookup = (args: TargetLookupArgs) => Promise<WorkspaceRelayTarget | undefined>;
+export declare function pruneExpiringCache<T extends {
+    expiresAt: number;
+}>(cache: Map<string, T>, now: number, maxEntries: number): void;
+/**
+ * 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;
+/**
+ * The longest a revoked Runtime Access Token can keep working after the
+ * authority records the revocation, derived from the configured TTLs rather
+ * than measured timing.
+ *
+ * Every relayed HTTP request re-runs the active check, so a cached `active`
+ * answer delays denial by at most `revocationCacheTtlMs`. An established
+ * socket adds at most one re-check interval — its watcher can tick just
+ * before the stale entry expires — so pass the room's
+ * `runtimeAccessTokenActiveCheckIntervalMs` as `activeCheckIntervalMs`;
+ * omit it for the per-request path. A non-positive interval means the socket
+ * has no revocation watcher at all and the function reports no bound: the
+ * token's `exp`, enforced locally by the socket expiry timer, is then the
+ * only deadline, and it caps every path even while the revocation authority
+ * is unreachable.
+ */
+export declare function runtimeAccessTokenRevocationDelayMs(input?: {
+    revocationCacheTtlMs?: number;
+    activeCheckIntervalMs?: number;
+}): number;
+/**
+ * Caches host-generation answers by enrollment id with the fence's own rules:
+ * a cached answer stands only while it is at least the caller's generation
+ * (equal admits; higher is a refusal that needs no fresh read), and a caller
+ * holding a HIGHER generation than the cache — or than the answer an in-flight
+ * lookup settles on — forces a refresh so a fresh `acquire` is never refused
+ * on a stale answer. Unknown enrollments and failures are not cached;
+ * concurrent misses share one lookup.
+ */
+export declare function createCachedHostGenerationClient(inner: HostGenerationLookup, options?: CachedHostGenerationOptions): HostGenerationLookup;
+export type CachedTargetOptions = {
+    ttlMs?: number;
+    durableObjectTtlMs?: number;
+    now?: () => number;
+};
+/**
+ * Wraps the target lookup with a small in-memory cache keyed by workspace,
+ * host and routing id. Only a resolved target is cached: a workspace whose
+ * sandbox is still starting answers nothing, and must be seen the moment it
+ * is ready. Concurrent misses share one lookup. A cloud or host-tunnel target
+ * that stopped keeps answering for at most `ttlMs`, the same lag the
+ * revocation cache allows; a session's own Durable Object for
+ * `durableObjectTtlMs`.
+ */
+export declare function createCachedTargetClient(inner: TargetLookup, options?: CachedTargetOptions): TargetLookup;