@claxedo/workspace-relay 0.7.0 → 0.10.0

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/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;

package/dist/server.d.ts

@@ -1,59 +1,23 @@
-import { Hono } from "hono";
-import type { RuntimeAccessVerifierClaims, TokenVerifier } from "@claxedo/workspace-relay-protocol";
-import { type RelayClaimPair, type RelayJwtAlgorithm, type RelayKey, type RelayRole, type RuntimeAccessTokenClaims } from "./auth";
+import { type RuntimeAccessVerifierClaims, type TokenVerifier } from "@claxedo/workspace-relay-protocol";
+import { type HostTunnelTokenClaims, type RelayJwtAlgorithm, type RelayKey, type RelayRole, type RuntimeAccessTokenClaims } from "./auth";
 import type { WorkspaceRelayDirectory } from "./directory";
-export type RelayHostPublicKey = {
-    publicKey: CryptoKey | Uint8Array;
-    kid: string;
-};
-export type WorkspaceRelayTarget = {
-    workspaceId: string;
-    hostId: string;
-    baseUrl: string;
-    upstreamHeaders?: Record<string, string>;
-} & RelayClaimPair;
-export type RuntimeAccessTokenActiveResult = {
-    active: true;
-} | {
-    active: false;
-    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;
-};
+import { type WorkspaceRelayTarget } from "./relay-target";
+import type { HostGenerationLookup, RuntimeAccessTokenActiveResult } from "./resolver-clients";
+export declare function hostTunnelIncumbentOutranks(incumbentGeneration: number, candidateGeneration: number): boolean;
 export type WorkspaceRelayAuditEvent = {
-    action: "relay.request.accepted" | "relay.request.denied" | "relay.request.suppressed_summary" | "host_tunnel.connected" | "host_tunnel.disconnected";
+    action: "relay.request.accepted" | "relay.request.denied" | "relay.request.suppressed_summary";
     result: "allow" | "deny";
     reason?: string;
-    subject?: string;
+    actorId?: string;
+    actorKind?: "human" | "agent";
+    principalKind?: "user" | "service";
     role?: RelayRole;
     workspaceId?: string;
     hostId?: string;
     method: string;
     path: string;
     /**
-     * T16: only set on `relay.request.suppressed_summary` events. Counts the
+     * Only set on `relay.request.suppressed_summary` events. Counts the
      * number of `relay.request.accepted` audit events that were dropped by the
      * sampler in the previous flush interval.
      */
@@ -61,6 +25,11 @@ export type WorkspaceRelayAuditEvent = {
 };
 export type WorkspaceRelayAuthOptions = {
     runtimeAccessKey: RelayKey;
+    /**
+     * Serving-generation fence for host tunnels. A relay composed without it
+     * refuses every host tunnel `host_generation_unverifiable`.
+     */
+    resolveHostGeneration?: HostGenerationLookup;
     /**
      * Cache signature/introspection-verified Runtime Access Token claims by the
      * full token string. Revocation/active checks, role enforcement, and target
@@ -79,7 +48,7 @@ export type WorkspaceRelayAuthOptions = {
      * raw JWT codepath.
      *
      * This is the seam downstream users plug their own auth backend
-     * through (Clerk-issued tokens, OIDC introspection, custom keys, etc.).
+     * through (issuer-signed tokens, OIDC introspection, custom keys, etc.).
      * See `@claxedo/workspace-relay-protocol/token-verifier` for the
      * `HttpTokenVerifier` and `StaticTokenVerifier` reference impls.
      */
@@ -89,19 +58,11 @@ export type WorkspaceRelayAuthOptions = {
 export type WorkspaceRelayHostTokenOptions = {
     relayHostSigningKey: CryptoKey | Uint8Array;
     relayHostAlgorithm: RelayJwtAlgorithm;
-    /**
-     * Public keys to publish at `/.well-known/jwks.json`. The first entry is the
-     * "current" mint key; any further entries are "next" keys (for rolling
-     * rotation). Verifiers (workspace-runtime → workspace-host-service) consume
-     * this set via `jose.createRemoteJWKSet`. Omit to disable the endpoint
-     * (during rollout / for tests that do not need JWKS).
-     */
-    relayHostPublicKeys?: RelayHostPublicKey[];
     /**
      * `kid` to embed in the protected header of freshly minted RHTs. When
      * provided, verifiers can dispatch on `kid` to pick the matching key from
-     * the published JWKS. Should match the `kid` of the first entry in
-     * `relayHostPublicKeys` so JWKS and mint agree by construction.
+     * the published JWKS, so it must be the `kid` of the current key the Worker
+     * publishes at `/.well-known/jwks.json`.
      */
     relayHostMintKid?: string;
     /**
@@ -117,103 +78,31 @@ export type WorkspaceRelayRoutingOptions = {
     fetch?: typeof fetch;
     forwardTimeoutMs?: number;
     directory?: WorkspaceRelayDirectory;
-    allowedOrigins?: string[];
-};
-export type WorkspaceRelayDrainOptions = {
-    /**
-     * T9: when this returns true the relay reports unhealthy via `/health` and
-     * fast-paths every workspace request to a 503 (`relay_draining`) before
-     * doing any auth or upstream work. Wired by `createWorkspaceRelayBun` to
-     * the drain controller it exposes.
-     */
-    isDraining?: () => boolean;
 };
 export type WorkspaceRelayTelemetryOptions = {
     audit?: (event: WorkspaceRelayAuditEvent) => void | Promise<void>;
     /**
-     * T16: probability (0.0 – 1.0) at which `relay.request.accepted` audit
-     * events are emitted to the user `audit` callback. Denies and tunnel
-     * lifecycle events are never sampled. When unset, defaults to 1.0
-     * (emit every accept). Suppressed accepts are aggregated into a periodic
-     * `relay.request.suppressed_summary` event (see `auditFlushIntervalMs`).
+     * Probability (0.0 – 1.0) at which `relay.request.accepted` audit
+     * events are emitted to the user `audit` callback. Denies are never
+     * sampled. When unset, defaults to 1.0 (emit every accept). Suppressed
+     * accepts are aggregated into a periodic `relay.request.suppressed_summary`
+     * event (see `auditFlushIntervalMs`).
      */
     auditAcceptSampleRate?: number;
     /**
-     * T16: how often (ms) the sampler emits a `relay.request.suppressed_summary`
+     * How often (ms) the sampler emits a `relay.request.suppressed_summary`
      * audit event with the count of suppressed accepts in the past interval.
      * Defaults to 60_000 (one minute). When sample rate is 1.0 no interval is
      * armed (nothing to flush). Exposed for tests.
      */
     auditFlushIntervalMs?: number;
     /**
-     * T16: random source for the sampler. Defaults to `Math.random`. Override
-     * for deterministic tests.
+     * Random source for audit and trace sampling. Defaults to `Math.random`.
+     * Override for deterministic tests.
      */
     random?: () => number;
 };
-export type WorkspaceRelayMetricsOptions = {
-    /**
-     * T31: bearer token required to access `GET /metrics` from non-loopback
-     * remotes. When unset, the endpoint allows loopback callers only (using
-     * `metricsRemoteAddress` to identify the caller). When set, every request
-     * must present `Authorization: Bearer <metricsToken>` regardless of origin.
-     * Wired from `CLAXEDO_RELAY_METRICS_TOKEN` in main.ts.
-     */
-    metricsToken?: string;
-    /**
-     * 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, `/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'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;
-};
-export type WorkspaceRelayOptions = WorkspaceRelayAuthOptions & WorkspaceRelayHostTokenOptions & WorkspaceRelayRoutingOptions & WorkspaceRelayDrainOptions & WorkspaceRelayTelemetryOptions & WorkspaceRelayMetricsOptions;
-export type WorkspaceRelayMetricsSources = {
-    fragmentation?: () => {
-        fragmentsBuffered: number;
-        oversizedClosed: number;
-    };
-    slowConsumer?: () => {
-        overflowEvents: number;
-        timerFired: number;
-        droppedRequests: number;
-    };
-    drainPending?: () => number;
-};
-/**
- * T31: shape of the JSON body returned by `GET /metrics`. Exported so the
- * bun adapter and ops dashboards can type-narrow against it.
- */
-export type WorkspaceRelayMetrics = {
-    fragmentation: {
-        fragmentsBuffered: number;
-        oversizedClosed: number;
-    };
-    slowConsumer: {
-        overflowEvents: number;
-        timerFired: number;
-        droppedRequests: number;
-    };
-    directory: {
-        activeHostCount: number;
-    };
-    audit: {
-        suppressedAccepts: number;
-    };
-    drain?: {
-        pendingCount: number;
-    };
-};
+export type WorkspaceRelayOptions = WorkspaceRelayAuthOptions & WorkspaceRelayHostTokenOptions & WorkspaceRelayRoutingOptions & WorkspaceRelayTelemetryOptions;
 export type AuthorizedWorkspaceRelayRequest = {
     claims: RuntimeAccessTokenClaims;
     target: WorkspaceRelayTarget;
@@ -223,37 +112,35 @@ export type AuthorizedWorkspaceRelayRequest = {
 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[];
-};
+export declare const RUNTIME_ACCESS_TOKEN_ACTIVE_CHECK_INTERVAL_MS_DEFAULT = 30000;
 /**
- * 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.
+ * `retryable: false` means the control plane refused this generation, so the
+ * host must not simply reconnect with it; `retryable: true` means the control
+ * plane could not be asked, and a reconnect is the recovery.
  */
-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 HostTunnelGenerationDecision = {
+    ok: true;
+} | {
+    ok: false;
+    retryable: false;
+    code: "host_generation_superseded" | "host_generation_unknown" | "host_generation_unverifiable" | "host_enrollment_revoked" | "host_enrollment_unknown";
+    reason: string;
+} | {
+    ok: false;
+    retryable: true;
+    code: "host_generation_lookup_unavailable";
+    reason: string;
+};
+export declare function checkHostTunnelGeneration(lookup: HostGenerationLookup | undefined, claims: Pick<HostTunnelTokenClaims, "enrollment_id" | "generation">): Promise<HostTunnelGenerationDecision>;
 export type WorkspaceRelayForwardHeadersOptions = {
     /**
-     * When true, also strip the `Cookie` request header. User-hosted workspaces
-     * run on the user's laptop where the host process may share a cookie jar
-     * with the browser (e.g. localhost dev tooling); passing through cookies
-     * verbatim risks leaking sensitive session data to the host. Cloud-vm
-     * workspaces sit behind a dedicated network boundary where session cookies
-     * may legitimately be needed (e.g. workspace dashboards), so the default
-     * is to NOT strip cookies. T26.
+     * When true, also strip the `Cookie` request header. A host tunnel ends on a
+     * machine somebody uses, whose cookie jar the browser may share (localhost
+     * dev tooling); 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 the default is to not strip cookies.
      */
-    userHosted?: boolean;
-    upstreamHeaders?: Record<string, string>;
+    hostTunnel?: boolean;
 };
 export type WorkspaceRelayForwardRequestInitOptions = WorkspaceRelayForwardHeadersOptions & {
     signal?: AbortSignal;
@@ -261,14 +148,6 @@ export type WorkspaceRelayForwardRequestInitOptions = WorkspaceRelayForwardHeade
 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 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;
@@ -277,19 +156,3 @@ export declare function authorizeWorkspaceRelayRequest(options: WorkspaceRelayOp
     response: Response;
     code: string;
 }>;
-export declare function forwardWorkspaceRelayRequest(request: Request, target: WorkspaceRelayTarget, relayHostToken: string, path: string, requestFetch: typeof fetch, timeoutMs: number, trace?: WorkspaceRelayAuthorizeTrace, originAllowed?: (origin: string) => boolean): Promise<Response>;
-export type WorkspaceRelayApp = Hono & {
-    /**
-     * T16: clear the sampler's periodic flush timer. Tests must call this so
-     * `setInterval` doesn't keep the process alive after the test exits.
-     */
-    disposeAuditSampler(): void;
-};
-/**
- * T31: read the suppressed-accept counter for a given options object. Surfaced
- * for the `/metrics` route handler. Returns 0 if no sampler state has been
- * created yet (no requests have been audit-sampled), which is the same value
- * an external observer would see.
- */
-export declare function getAuditSuppressedCount(options: WorkspaceRelayOptions): number;
-export declare function createWorkspaceRelay(options: WorkspaceRelayOptions): WorkspaceRelayApp;

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

@@ -0,0 +1,22 @@
+import type { RelayBacking } from "./auth";
+import { SESSION_HOST_LOCATION_HINT } from "./relay-location";
+import { type AuthorizedWorkspaceRelayRequest } from "./server";
+/** The `SESSION_HOST` binding: one Durable Object per top-level session, named by that session's id. */
+export type SessionHostNamespace = {
+    getByName: (name: string, options?: {
+        locationHint?: typeof SESSION_HOST_LOCATION_HINT;
+    }) => {
+        fetch: (input: string, init?: RequestInit) => Promise<Response>;
+    };
+};
+export declare function isSessionHostTarget(target: {
+    backing: RelayBacking;
+}): boolean;
+export declare function isSessionHostNamespace(value: unknown): value is SessionHostNamespace;
+/**
+ * Forwards one HTTP request to the session's Durable Object with the Relay
+ * Host Token the authorization minted. The browser's cookies never reach it,
+ * as they never reach a host tunnel, and the response body streams through
+ * untouched so a session's event stream stays open.
+ */
+export declare function forwardSessionHostHttp(namespace: SessionHostNamespace | undefined, request: Request, authorized: AuthorizedWorkspaceRelayRequest): Promise<Response>;

package/dist/test-support/unfenced-host-token.d.ts

@@ -0,0 +1,6 @@
+import { type mintHostTunnelToken } from "../auth";
+export declare function signUnfencedHostTunnelToken(input: {
+    subject: string;
+    hostId: string;
+    workspaceIds: string[];
+}, key: Parameters<typeof mintHostTunnelToken>[1]): Promise<string>;