@claxedo/workspace-relay 0.1.0

package/dist/server.d.ts

@@ -0,0 +1,226 @@
+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 { WorkspaceRelayDirectory } from "./directory";
+export type RelayHostPublicKey = {
+    publicKey: CryptoKey | Uint8Array;
+    kid: string;
+};
+export type WorkspaceRelayTarget = {
+    workspaceId: string;
+    hostId: string;
+    baseUrl: string;
+    access: RelayAccess;
+    backing: RelayBacking;
+};
+export type RuntimeAccessTokenActiveResult = {
+    active: true;
+} | {
+    active: false;
+    code: string;
+    reason: string;
+};
+export type WorkspaceRelayAuditEvent = {
+    action: "relay.request.accepted" | "relay.request.denied" | "relay.request.suppressed_summary" | "host_tunnel.connected" | "host_tunnel.disconnected";
+    result: "allow" | "deny";
+    reason?: string;
+    subject?: string;
+    role?: RelayRole;
+    workspaceId?: string;
+    hostId?: string;
+    method: string;
+    path: string;
+    /**
+     * T16: 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.
+     */
+    suppressedCount?: number;
+};
+export type WorkspaceRelayAuthOptions = {
+    runtimeAccessKey: RelayKey;
+    /**
+     * P-shared: optional override for runtime-access-token verification.
+     *
+     * When set, the relay calls this verifier instead of decoding the JWT
+     * with `runtimeAccessKey`. The verifier returns `{ subject, scopes,
+     * claims }`; the relay continues to use `claims` to drive
+     * `resolveTarget` and the workspace/host audit fields. `runtimeAccessKey`
+     * is then only used for legacy token paths and tests that exercise the
+     * raw JWT codepath.
+     *
+     * This is the seam downstream users plug their own auth backend
+     * through (Clerk-issued tokens, OIDC introspection, custom keys, etc.).
+     * See `@claxedo/workspace-relay-protocol/token-verifier` for the
+     * `HttpTokenVerifier` and `StaticTokenVerifier` reference impls.
+     */
+    tokenVerifier?: TokenVerifier;
+    isRuntimeAccessTokenActive?: (claims: RuntimeAccessTokenClaims) => RuntimeAccessTokenActiveResult | Promise<RuntimeAccessTokenActiveResult>;
+};
+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.
+     */
+    relayHostMintKid?: string;
+};
+export type WorkspaceRelayRoutingOptions = {
+    resolveTarget: (claims: RuntimeAccessTokenClaims) => WorkspaceRelayTarget | Promise<WorkspaceRelayTarget | undefined>;
+    fetch?: typeof fetch;
+    directory?: WorkspaceRelayDirectory;
+};
+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`).
+     */
+    auditAcceptSampleRate?: number;
+    /**
+     * T16: 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?: () => 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, 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`.
+     */
+    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.
+     */
+    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 AuthorizedWorkspaceRelayRequest = {
+    claims: RuntimeAccessTokenClaims;
+    target: WorkspaceRelayTarget;
+    relayHostToken: string;
+    path: string;
+};
+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.
+     */
+    userHosted?: boolean;
+};
+export declare function workspaceRelayTargetUrl(target: WorkspaceRelayTarget, path: string, search: string): URL;
+export declare function workspaceRelayForwardHeaders(input: Headers, relayHostToken: string, workspaceId: string, options?: WorkspaceRelayForwardHeadersOptions): Headers;
+/**
+ * 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<{
+    ok: true;
+    request: AuthorizedWorkspaceRelayRequest;
+} | {
+    ok: false;
+    response: 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/synthetic.d.ts

@@ -0,0 +1,60 @@
+/**
+ * T10: Synthetic end-to-end probe.
+ *
+ * Liveness depends on metrics; metrics can lie. A synthetic probe periodically
+ * exercises the relay's HTTP path and records RTT so we have an independent
+ * signal that the data path actually works.
+ *
+ * Implementation notes
+ * --------------------
+ * - The probe targets `${relayUrl}/health` rather than minting a Runtime
+ *   Access Token and hitting `/workspaces/<id>/...`. `/health` validates HTTP
+ *   connectivity end-to-end without pretending the Relay owns Control Plane
+ *   token issuance.
+ * - All clocks, timers and `fetch` are injectable so tests stay deterministic.
+ * - "Loud" logs after 3 consecutive failures use `console.error` by default;
+ *   pageability (PagerDuty / equivalent) is wired separately.
+ */
+export type SyntheticProbeStats = {
+    successCount: number;
+    failureCount: number;
+    consecutiveFailures: number;
+    /** RTT (ms) of the most recent probe attempt. Undefined before the first probe completes. */
+    lastRttMs?: number;
+    /** p50 / p99 over the rolling RTT window. Undefined if no successes yet. */
+    p50?: number;
+    p99?: number;
+    /** Number of RTTs currently in the rolling window. */
+    windowSize: number;
+};
+export type SyntheticProbe = {
+    stop(): void;
+    stats(): SyntheticProbeStats;
+};
+export type SyntheticProbeOptions = {
+    /** Base URL of the relay, e.g. `http://127.0.0.1:7777`. No trailing slash required. */
+    relayUrl: string;
+    /** Probe cadence. Default 60_000 (60 s). */
+    intervalMs?: number;
+    /** Summary log cadence (p50/p99). Default 300_000 (5 min). */
+    summaryIntervalMs?: number;
+    /** Path to probe. Default `/health`. */
+    probePath?: string;
+    /** Rolling window size for RTT percentile calculation. Default 100. */
+    rttWindowSize?: number;
+    /** Number of consecutive failures that triggers a loud log. Default 3. */
+    loudFailureThreshold?: number;
+    /** Override `fetch`. Defaults to global `fetch`. */
+    fetch?: typeof fetch;
+    /** Override clock for tests. Defaults to `Date.now`. */
+    now?: () => number;
+    /** Override `setInterval` for tests. Defaults to global `setInterval`. */
+    setInterval?: typeof setInterval;
+    /** Override `clearInterval` for tests. Defaults to global `clearInterval`. */
+    clearInterval?: typeof clearInterval;
+    /** Loud-failure logger. Defaults to `console.error`. */
+    logError?: (msg: string, fields?: Record<string, unknown>) => void;
+    /** Periodic summary logger (p50/p99). Defaults to `console.log`. */
+    logSummary?: (msg: string, fields?: Record<string, unknown>) => void;
+};
+export declare function startSyntheticProbe(options: SyntheticProbeOptions): SyntheticProbe;

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@claxedo/workspace-relay",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "workspace-relay": "./dist/main.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "bun run src/main.ts",
+    "dev": "bun run --hot src/main.ts",
+    "build": "tsx scripts/build.ts",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@claxedo/workspace-relay-protocol": "^0.1.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:"
+  }
+}