@claxedo/workspace-relay 0.5.1 → 0.6.0

package/dist/index.mjs

@@ -73,6 +73,7 @@ async function verifyJwt(token, key, input) {
       algorithms: [...algorithms]
     });
   } catch (err) {
+    if (err instanceof errors.JWKSTimeout) throw err;
     if (err instanceof errors.JOSEError) {
       throw new WorkspaceRelayAuthError("invalid_relay_token", "Relay token is invalid");
     }
@@ -221,6 +222,7 @@ function hostTunnelClaims(payload) {
 
 // src/bun.ts
 import {
+  makeTunnelPing,
   makeTunnelPong,
   TUNNEL_PROTOCOL_VERSION,
   validateTunnelMessage
@@ -231,6 +233,48 @@ import { Hono } from "hono";
 import { cors } from "hono/cors";
 import { exportJWK } from "jose";
 
+// src/cors-origins.ts
+var DEFAULT_RELAY_APP_ORIGINS = [
+  "http://localhost:*",
+  "http://127.0.0.1:*",
+  "https://opencode.ai",
+  "https://*.opencode.ai",
+  "https://claxedo.com",
+  "https://*.claxedo.com"
+];
+function parseAllowedOrigins(raw) {
+  const entries = (raw ?? "").split(",").map((item) => item.trim()).filter(Boolean);
+  return entries.length ? entries : void 0;
+}
+function createOriginMatcher(patterns) {
+  const exact = /* @__PURE__ */ new Set();
+  const httpsSuffixes = [];
+  const httpPortPrefixes = [];
+  for (const pattern of patterns) {
+    if (pattern.startsWith("https://*.")) {
+      httpsSuffixes.push(pattern.slice("https://*".length));
+    } else if (pattern.startsWith("http://") && pattern.endsWith(":*")) {
+      httpPortPrefixes.push(pattern.slice(0, -1));
+    } else {
+      exact.add(pattern);
+    }
+  }
+  return (origin) => {
+    if (exact.has(origin)) return true;
+    if (origin.startsWith("https://")) {
+      return httpsSuffixes.some(
+        (suffix) => origin.endsWith(suffix) && origin.length > "https://".length + suffix.length
+      );
+    }
+    if (origin.startsWith("http://")) {
+      return httpPortPrefixes.some(
+        (prefix) => origin.startsWith(prefix) && /^\d+$/.test(origin.slice(prefix.length))
+      );
+    }
+    return false;
+  };
+}
+
 // src/http.ts
 function bearerToken(header) {
   if (!header) return;
@@ -374,9 +418,24 @@ function targetUrl(target, path, search) {
   url.search = search;
   return url;
 }
-function roleAllowsRelayRequest(role, method) {
+var RELAY_VIEWER_DENIED_PATH = /^\/api\/wr\/pty(?:\/|$)/;
+function relayRuntimePath(request) {
+  return new URL(request.url).pathname.replace(/^\/workspaces\/[^/]+\/?/, "/");
+}
+function relayAuthorizationPath(path) {
+  try {
+    return decodeURIComponent(path);
+  } catch {
+    return void 0;
+  }
+}
+function roleAllowsRelayRequest(role, method, path) {
   if (role === "owner" || role === "admin" || role === "editor") return true;
-  if (role === "viewer") return method === "GET" || method === "HEAD" || method === "OPTIONS";
+  if (role === "viewer") {
+    const authorizationPath = relayAuthorizationPath(path);
+    if (!authorizationPath || RELAY_VIEWER_DENIED_PATH.test(authorizationPath)) return false;
+    return method === "GET" || method === "HEAD" || method === "OPTIONS";
+  }
   return false;
 }
 function relayHostTokenCacheTtlMs(options, claims) {
@@ -645,11 +704,21 @@ async function audit(options, event) {
   }
   await options.audit?.(event);
 }
-function denyCorsHeaders(request) {
+var defaultOriginMatcher = createOriginMatcher(DEFAULT_RELAY_APP_ORIGINS);
+var originMatchers = /* @__PURE__ */ new WeakMap();
+function originMatcherFor(options) {
+  if (!options.allowedOrigins) return defaultOriginMatcher;
+  let matcher = originMatchers.get(options);
+  if (!matcher) {
+    matcher = createOriginMatcher(options.allowedOrigins);
+    originMatchers.set(options, matcher);
+  }
+  return matcher;
+}
+function denyCorsHeaders(request, originAllowed = defaultOriginMatcher) {
   const origin = request.headers.get("origin");
   if (!origin) return void 0;
-  const allowed = origin.startsWith("http://localhost:") || origin.startsWith("http://127.0.0.1:") || /^https:\/\/([a-z0-9-]+\.)*opencode\.ai$/.test(origin);
-  if (!allowed) return void 0;
+  if (!originAllowed(origin)) return void 0;
   return {
     "access-control-allow-origin": origin,
     "access-control-allow-headers": "Accept, Authorization, Content-Type, Last-Event-ID, X-Fetch-Bypass-Throttle, X-Daytona-Skip-Preview-Warning, X-Workspace-Id, X-OpenCode-Directory, X-Claxedo-Runner, X-Claxedo-Model, X-Claxedo-Draft-Id, X-Claxedo-Binary",
@@ -671,7 +740,7 @@ async function deny(options, input) {
   });
   return Response.json(errorBody(input.code, input.message), {
     status: input.status,
-    headers: denyCorsHeaders(input.request)
+    headers: denyCorsHeaders(input.request, originMatcherFor(options))
   });
 }
 async function authorizeWorkspaceRelayRequest(options, request, workspaceId, trace) {
@@ -710,7 +779,8 @@ async function authorizeWorkspaceRelayRequest(options, request, workspaceId, tra
         })
       };
     }
-    if (!roleAllowsRelayRequest(claims.role, request.method)) {
+    const path = relayRuntimePath(request);
+    if (!roleAllowsRelayRequest(claims.role, request.method, path)) {
       return {
         ok: false,
         code: "relay_role_denied",
@@ -767,7 +837,7 @@ async function authorizeWorkspaceRelayRequest(options, request, workspaceId, tra
         claims,
         target,
         relayHostToken,
-        path: new URL(request.url).pathname.replace(/^\/workspaces\/[^/]+\/?/, "/")
+        path
       }
     };
   } catch (err) {
@@ -784,7 +854,7 @@ async function authorizeWorkspaceRelayRequest(options, request, workspaceId, tra
     };
   }
 }
-async function forwardWorkspaceRelayRequest(request, target, relayHostToken, path, requestFetch, timeoutMs, trace) {
+async function forwardWorkspaceRelayRequest(request, target, relayHostToken, path, requestFetch, timeoutMs, trace, originAllowed = defaultOriginMatcher) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   const span = (name, run) => trace ? trace.span(name, run) : run();
@@ -803,7 +873,7 @@ async function forwardWorkspaceRelayRequest(request, target, relayHostToken, pat
     headers2.delete("access-control-allow-methods");
     headers2.delete("access-control-expose-headers");
     headers2.delete("access-control-max-age");
-    for (const [key, value] of Object.entries(denyCorsHeaders(request) ?? {})) {
+    for (const [key, value] of Object.entries(denyCorsHeaders(request, originAllowed) ?? {})) {
       headers2.set(key, value);
     }
     return new Response(upstream.body, {
@@ -818,7 +888,7 @@ async function forwardWorkspaceRelayRequest(request, target, relayHostToken, pat
         aborted ? "upstream_timeout" : "upstream_unavailable",
         aborted ? "Workspace upstream timed out" : "Workspace upstream is unavailable"
       ),
-      { status: aborted ? 504 : 503, headers: denyCorsHeaders(request) }
+      { status: aborted ? 504 : 503, headers: denyCorsHeaders(request, originAllowed) }
     );
   } finally {
     clearTimeout(timer);
@@ -893,14 +963,11 @@ function buildMetricsBody(options) {
 }
 function createWorkspaceRelay(options) {
   const app = new Hono();
+  const originAllowed = originMatcherFor(options);
   app.use("*", cors({
     origin: (origin) => {
       if (!origin) return void 0;
-      if (origin.startsWith("http://localhost:")) return origin;
-      if (origin.startsWith("http://127.0.0.1:")) return origin;
-      if (/^https:\/\/([a-z0-9-]+\.)*opencode\.ai$/.test(origin)) return origin;
-      if (/^https:\/\/([a-z0-9-]+\.)*claxedo\.com$/.test(origin)) return origin;
-      return void 0;
+      return originAllowed(origin) ? origin : void 0;
     },
     allowHeaders: [
       "Accept",
@@ -980,7 +1047,7 @@ function createWorkspaceRelay(options) {
     if (options.isDraining?.()) {
       return Response.json(
         errorBody("relay_draining", "Workspace relay is shutting down; try another instance"),
-        { status: 503, headers: denyCorsHeaders(c.req.raw) }
+        { status: 503, headers: denyCorsHeaders(c.req.raw, originAllowed) }
       );
     }
     const response = await trace.span("relay-total", async () => {
@@ -993,7 +1060,8 @@ function createWorkspaceRelay(options) {
         relay.request.path,
         options.fetch ?? fetch,
         options.forwardTimeoutMs ?? 3e4,
-        trace
+        trace,
+        originAllowed
       );
     });
     return workspaceRelayTimingResponse(response, trace);
@@ -1248,12 +1316,7 @@ function tunnelMessage(ws, input, stats) {
 function sendTunnelPing(ws) {
   if (ws.readyState !== WebSocket.OPEN) return;
   ws.data.missedPongs += 1;
-  ws.send(JSON.stringify({
-    type: "ping",
-    protocol: TUNNEL_PROTOCOL_VERSION,
-    id: crypto.randomUUID(),
-    sent_at: Date.now()
-  }));
+  ws.send(JSON.stringify(makeTunnelPing()));
 }
 function clearPendingTimers(entry) {
   clearTimeout(entry.timeout);
@@ -1854,6 +1917,29 @@ function createWorkspaceRelayBun(options, bunOptions = {}) {
             ws.data.missedPongs = 0;
             options.directory?.recordPong(ws.data.hostId);
           }
+          if (parsed?.type === "host.registration.update") {
+            const update = parsed;
+            const workspaceIds = [...new Set(update.workspace_ids)];
+            const hostSocket = ws;
+            const hostId = hostSocket.data.hostId;
+            const authorizationRequest = new Request(
+              `http://relay.local/host-tunnels/${encodeURIComponent(hostId)}`,
+              { headers: { authorization: `Bearer ${update.token}` } }
+            );
+            void authorizeHostTunnel(options, bunOptions, authorizationRequest, {
+              hostId,
+              workspaceIds
+            }).then((authorized) => {
+              if (!authorized) {
+                closeWebSocket(hostSocket, 1008, "Host tunnel registration update denied", 1008);
+                return;
+              }
+              if (hostTunnels.get(hostId) !== hostSocket || hostSocket.readyState !== WebSocket.OPEN) return;
+              hostSocket.data.workspaceIds = workspaceIds;
+              options.directory?.registerHostTunnel({ hostId, workspaceIds });
+            }).catch(() => closeWebSocket(hostSocket, 1008, "Host tunnel registration update denied", 1008));
+            return;
+          }
           if (parsed?.type === "error") {
             if (parsed.request_id) {
               const pending = ws.data.pending.get(parsed.request_id);
@@ -2244,7 +2330,8 @@ function clampRate(input) {
 }
 function traceRequest(request, routeKind, options) {
   const id = clean(request.headers.get(TRACE_ID_HEADER)) ?? crypto.randomUUID();
-  const forced = request.headers.get(TRACE_FORCE_HEADER) === "1";
+  const forceSecret = clean(options.traceForceHeaderSecret);
+  const forced = !!forceSecret && request.headers.get(TRACE_FORCE_HEADER) === forceSecret;
   const rate = clampRate(options.traceSampleRate);
   return {
     id,
@@ -2266,6 +2353,7 @@ function tracedRequest(request, trace) {
   const headers2 = new Headers(request.headers);
   headers2.set(TRACE_ID_HEADER, trace.id);
   if (trace.sampled) headers2.set("x-claxedo-trace-sampled", "1");
+  else headers2.delete("x-claxedo-trace-sampled");
   return new Request(request.url, {
     method: request.method,
     headers: headers2,
@@ -2283,7 +2371,7 @@ function serverTiming(trace) {
 function withTraceHeaders(response, trace) {
   const headers2 = new Headers(response.headers);
   headers2.set(TRACE_ID_HEADER, trace.id);
-  const timing = serverTiming(trace);
+  const timing = trace.sampled ? serverTiming(trace) : "";
   if (timing) {
     const existing = headers2.get("server-timing");
     headers2.set("server-timing", existing ? `${existing}, ${timing}` : timing);
@@ -2324,6 +2412,9 @@ function hostIdFromTunnelPath2(pathname) {
 function websocketRequest2(request) {
   return request.headers.get("upgrade")?.toLowerCase() === "websocket";
 }
+function relayWebSocketTraceEnabled2(request) {
+  return request.headers.get("x-claxedo-relay-ws-trace") === "1";
+}
 function workspaceIdsFromSearch(url) {
   return [...new Set([
     ...url.searchParams.getAll("workspaceId"),
@@ -2441,25 +2532,17 @@ function json(code, message, status) {
 }
 var configuredAppOriginAllowed = () => false;
 function setWorkspaceRelayAppOrigins(raw) {
-  const entries = (raw ?? "").split(",").map((item) => item.trim()).filter(Boolean);
-  const exact = /* @__PURE__ */ new Set();
-  const suffixes = [];
-  for (const entry of entries) {
-    if (entry.startsWith("https://*.")) suffixes.push(entry.slice("https://*".length));
-    else exact.add(entry);
-  }
-  configuredAppOriginAllowed = (origin) => {
-    if (exact.has(origin)) return true;
-    if (!origin.startsWith("https://")) return false;
-    return suffixes.some((suffix) => origin.endsWith(suffix) && origin.length > "https://".length + suffix.length);
-  };
+  configuredAppOriginAllowed = raw?.trim() ? createOriginMatcher(parseAllowedOrigins(raw) ?? []) : () => false;
+}
+var defaultOriginAllowed = createOriginMatcher(DEFAULT_RELAY_APP_ORIGINS);
+var baseOriginAllowed = defaultOriginAllowed;
+function setWorkspaceRelayAllowedOrigins(raw) {
+  const patterns = parseAllowedOrigins(raw);
+  baseOriginAllowed = patterns ? createOriginMatcher(patterns) : defaultOriginAllowed;
 }
 function allowedCorsOrigin2(origin) {
   if (!origin) return;
-  if (origin.startsWith("http://localhost:")) return origin;
-  if (origin.startsWith("http://127.0.0.1:")) return origin;
-  if (/^https:\/\/([a-z0-9-]+\.)*opencode\.ai$/.test(origin)) return origin;
-  if (/^https:\/\/([a-z0-9-]+\.)*claxedo\.com$/.test(origin)) return origin;
+  if (baseOriginAllowed(origin)) return origin;
   if (configuredAppOriginAllowed(origin)) return origin;
 }
 function corsHeaders(request) {
@@ -2581,16 +2664,16 @@ function createWorkspaceRelayDurableObjectGateway(options = {}) {
         headers: headers2
       });
       const gatewayFinishedAt = performance.now();
-      const gatewayTiming = [
-        `relay-gateway-route;dur=${roundedMs3(routeFinishedAt - gatewayStartedAt)}`,
-        `relay-gateway-do-fetch;dur=${roundedMs3(fetchFinishedAt - routeFinishedAt)}`,
-        `relay-gateway-response;dur=${roundedMs3(gatewayFinishedAt - gatewayResponseStartedAt)}`,
-        `relay-gateway;dur=${roundedMs3(gatewayFinishedAt - gatewayStartedAt)}`
-      ].join(", ");
-      tracedResponse.headers.set(
-        "server-timing",
-        tracedResponse.headers.get("server-timing") ? `${tracedResponse.headers.get("server-timing")}, ${gatewayTiming}` : gatewayTiming
-      );
+      const roomTiming = tracedResponse.headers.get("server-timing");
+      if (roomTiming) {
+        const gatewayTiming = [
+          `relay-gateway-route;dur=${roundedMs3(routeFinishedAt - gatewayStartedAt)}`,
+          `relay-gateway-do-fetch;dur=${roundedMs3(fetchFinishedAt - routeFinishedAt)}`,
+          `relay-gateway-response;dur=${roundedMs3(gatewayFinishedAt - gatewayResponseStartedAt)}`,
+          `relay-gateway;dur=${roundedMs3(gatewayFinishedAt - gatewayStartedAt)}`
+        ].join(", ");
+        tracedResponse.headers.set("server-timing", `${roomTiming}, ${gatewayTiming}`);
+      }
       return url.pathname.startsWith("/workspaces/") ? withCors(request, tracedResponse) : tracedResponse;
     }
   };
@@ -2668,6 +2751,7 @@ function createWorkspaceRelayDurableObjectRoom(options) {
         hostTunnels.set(attachment.hostId, {
           hostId: attachment.hostId,
           workspaceIds: attachment.workspaceIds,
+          connectedAt: attachment.connectedAt,
           socket,
           pending: /* @__PURE__ */ new Map(),
           channels: /* @__PURE__ */ new Map()
@@ -2704,6 +2788,16 @@ function createWorkspaceRelayDurableObjectRoom(options) {
     if (!hibernation || hibernatedSocketsRebuilt) return;
     rebuildHibernatedSockets();
   };
+  const refreshHostPresenceFromSockets = () => {
+    if (!hibernation) return;
+    for (const socket of hibernation.getWebSockets()) {
+      const attachment = socketAttachment(socket);
+      if (attachment?.kind !== "host-tunnel") continue;
+      if (!directory.recordPong(attachment.hostId)) {
+        directory.registerHostTunnel({ hostId: attachment.hostId, workspaceIds: attachment.workspaceIds });
+      }
+    }
+  };
   const watchRuntimeAccessToken = (client, onInactive) => {
     const intervalMs = options.runtimeAccessTokenActiveCheckIntervalMs ?? RUNTIME_ACCESS_TOKEN_ACTIVE_CHECK_INTERVAL_MS_DEFAULT;
     if (intervalMs <= 0) return;
@@ -2959,11 +3053,31 @@ function createWorkspaceRelayDurableObjectRoom(options) {
     const parsed = validateTunnelMessage2(row.value);
     const tunnel = hostTunnels.get(hostId);
     if (!parsed.ok || !tunnel) return;
+    directory.recordPong(tunnel.hostId);
     if (parsed.message.type === "ping") {
-      directory.recordPong(tunnel.hostId);
       tunnel.socket.send?.(JSON.stringify(makeTunnelPong2(parsed.message)));
       return;
     }
+    if (parsed.message.type === "host.registration.update") {
+      const update = parsed.message;
+      const workspaceIds = [...new Set(update.workspace_ids)];
+      try {
+        await verifyHostTunnelToken(update.token, options.runtimeAccessKey, { hostId, workspaceIds });
+      } catch {
+        closeSocket(tunnel.socket, 1008, "Host tunnel registration update denied");
+        return;
+      }
+      if (hostTunnels.get(hostId) !== tunnel) return;
+      tunnel.workspaceIds = workspaceIds;
+      tunnel.socket.serializeAttachment?.({
+        kind: "host-tunnel",
+        hostId,
+        workspaceIds,
+        connectedAt: tunnel.connectedAt
+      });
+      directory.registerHostTunnel({ hostId, workspaceIds });
+      return;
+    }
     if (parsed.message.type === "error" && parsed.message.request_id) {
       const pending = tunnel.pending.get(parsed.message.request_id);
       if (!pending) return;
@@ -3102,11 +3216,12 @@ function createWorkspaceRelayDurableObjectRoom(options) {
       }
       throw err;
     }
+    const connectedAt = options.now?.() ?? Date.now();
     const pair = acceptSocket({
       kind: "host-tunnel",
       hostId,
       workspaceIds,
-      connectedAt: options.now?.() ?? Date.now()
+      connectedAt
     });
     const previous = hostTunnels.get(hostId);
     if (previous) {
@@ -3116,6 +3231,7 @@ function createWorkspaceRelayDurableObjectRoom(options) {
     hostTunnels.set(hostId, {
       hostId,
       workspaceIds,
+      connectedAt,
       socket: pair.server,
       pending: /* @__PURE__ */ new Map(),
       channels: /* @__PURE__ */ new Map()
@@ -3138,6 +3254,7 @@ function createWorkspaceRelayDurableObjectRoom(options) {
     return await admitCloudClient(request, authorized.request);
   };
   const admitCloudClient = async (request, authorized) => {
+    const trace = relayWebSocketTraceEnabled2(request) ? { upstreamStartedAt: performance.now(), queueTimes: [], emitted: false } : void 0;
     let upstream;
     try {
       upstream = await connectWebSocket(
@@ -3158,12 +3275,23 @@ function createWorkspaceRelayDurableObjectRoom(options) {
     } catch {
       return json("upstream_unavailable", "Workspace upstream is unavailable", 503);
     }
+    const upstreamConnectedAt = trace ? performance.now() : 0;
     const pair = acceptSocket();
     const client = { request: authorized, socket: pair.server };
     clients.add(client);
     let closed = false;
     let upstreamOpen = upstream.readyState === void 0 || upstream.readyState === 1;
     const queue = [];
+    const emitTrace = (openedAt) => {
+      if (!trace || trace.emitted) return;
+      trace.emitted = true;
+      sendSocket(pair.server, JSON.stringify({
+        type: "relay.trace",
+        wsUpstreamOpenMs: roundedMs3(openedAt - trace.upstreamStartedAt),
+        queuedFrames: trace.queueTimes.length,
+        maxQueuedDelayMs: roundedMs3(trace.queueTimes.reduce((max, at) => Math.max(max, openedAt - at), 0))
+      }));
+    };
     const activeTokenTimer = watchRuntimeAccessToken(client, (reason) => {
       closeSocket(pair.server, 1008, reason);
     });
@@ -3183,6 +3311,7 @@ function createWorkspaceRelayDurableObjectRoom(options) {
     };
     const flushQueue = () => {
       upstreamOpen = true;
+      if (trace) emitTrace(performance.now());
       for (const item of queue.splice(0)) {
         if (!sendSocket(upstream, item)) {
           closeSocket(pair.server, 1011, "Upstream WebSocket connection failed");
@@ -3199,6 +3328,7 @@ function createWorkspaceRelayDurableObjectRoom(options) {
           cleanupClient({ code: 1011, reason: "Upstream WebSocket queue limit exceeded" });
           return;
         }
+        if (trace) trace.queueTimes.push(performance.now());
         queue.push(payload);
         return;
       }
@@ -3213,6 +3343,7 @@ function createWorkspaceRelayDurableObjectRoom(options) {
     });
     upstream.addEventListener?.("close", cleanupUpstream);
     upstream.addEventListener?.("error", () => cleanupUpstream({ code: 1011, reason: "Upstream WebSocket connection failed" }));
+    if (trace && upstreamOpen) emitTrace(upstreamConnectedAt);
     return upgradeResponse(pair.client, request);
   };
   const admitUserHostedClient = (request, authorized) => {
@@ -3390,6 +3521,7 @@ function createWorkspaceRelayDurableObjectRoom(options) {
   return {
     async fetch(request) {
       ensureHibernatedSocketsRebuilt();
+      refreshHostPresenceFromSockets();
       const url = new URL(request.url);
       const roomWorkspaceId = workspaceRelayDurableObjectWorkspaceId(request);
       if (request.method === "OPTIONS" && (url.pathname.startsWith("/workspaces/") || url.pathname.startsWith("/host-tunnels/"))) {
@@ -3457,19 +3589,22 @@ function createWorkspaceRelayDurableObjectRoom(options) {
       return {
         hostTunnelCount: hostTunnels.size,
         clientCount: clients.size,
-        hostIds: [...hostTunnels.keys()]
+        hostIds: [...hostTunnels.keys()],
+        hostWorkspaceIds: Object.fromEntries([...hostTunnels].map(([hostId, tunnel]) => [hostId, tunnel.workspaceIds]))
       };
     },
     drain: drainController
   };
 }
 export {
+  DEFAULT_RELAY_APP_ORIGINS,
   DEFAULT_RELAY_LOCATION_HINT,
   WorkspaceRelayAuthError,
   __slowConsumerInternalsForTest,
   authorizeWorkspaceRelayRequest,
   createCachedRevocationClient,
   createCachedTargetClient,
+  createOriginMatcher,
   createWorkspaceRelay,
   createWorkspaceRelayBun,
   createWorkspaceRelayDirectory,
@@ -3485,10 +3620,12 @@ export {
   mintHostTunnelToken,
   mintRelayHostToken,
   mintRuntimeAccessToken,
+  parseAllowedOrigins,
   relayHostTokenAudience,
   relayHostTokenIssuer,
   runtimeAccessTokenAudience,
   runtimeAccessTokenIssuer,
+  setWorkspaceRelayAllowedOrigins,
   setWorkspaceRelayAppOrigins,
   validateRuntimeAccessTokenClaims,
   verifyHostTunnelToken,

package/dist/main.d.ts

@@ -3,6 +3,49 @@ import { type WorkspaceRelayDirectory } from "./directory";
 import { type RelayHostPublicKey, type RevocationLookup, type WorkspaceRelayTarget } from "./server";
 import type { RelayKey } from "./auth";
 export { createCachedRevocationClient, createCachedTargetClient } from "./server";
+/**
+ * D12 observability: Sentry on the relay (ops floor ADR
+ * docs/plans/2026-07-11-016-wp-ops-floor-design.md §4).
+ *
+ * Gated on `CLAXEDO_RELAY_SENTRY_DSN` (the relay's OWN DSN env — separate
+ * Sentry project from the control plane). Absent DSN → `Sentry.init` is never
+ * called: zero SDK overhead, zero network — the documented no-op posture, safe
+ * before the Sentry account exists. Release = git SHA passed by the D11
+ * deploy workflow (`CLAXEDO_RELEASE`; `GIT_SHA` accepted as alias); events are
+ * tagged unit=relay + deployment_mode (absent → "self-host", mirroring D9's
+ * default). Tracing stays off (ADR: it is where Sentry gets expensive).
+ *
+ * The relay is a Bun process (`Bun.serve`), so this uses `@sentry/bun` —
+ * Sentry's Bun-native SDK with the same init-gated pattern as @sentry/node
+ * (https://docs.sentry.io/platforms/javascript/guides/bun/).
+ */
+export type RelayObservabilityEnv = {
+    CLAXEDO_RELAY_SENTRY_DSN?: string | undefined;
+    CLAXEDO_RELEASE?: string | undefined;
+    GIT_SHA?: string | undefined;
+    CLAXEDO_DEPLOYMENT_MODE?: string | undefined;
+    /** Accept process.env verbatim (extra keys are ignored). */
+    [key: string]: string | undefined;
+};
+export type RelaySentryOptions = {
+    dsn: string;
+    release?: string;
+    tracesSampleRate: 0;
+    initialScope: {
+        tags: {
+            unit: "relay";
+            deployment_mode: string;
+        };
+    };
+};
+/**
+ * Pure env → Sentry options resolver. `undefined` = DSN absent = do NOT init
+ * (no client, no network). Exported for tests.
+ */
+export declare function relaySentryOptions(env: RelayObservabilityEnv): RelaySentryOptions | undefined;
+export declare function initRelayObservability(env?: RelayObservabilityEnv): {
+    enabled: boolean;
+};
 /**
  * Production fail-closed gate for the relay → claxedo-server resolver channel.
  *
@@ -168,6 +211,12 @@ export type FatalProcessHandlerOptions = {
     exit?: (code?: number) => void;
     log?: (message: string) => void;
     register?: boolean;
+    /**
+     * D12: error-tracker hook, invoked (and awaited) before teardown so a fatal
+     * crash reaches Sentry before the process exits. Failures are logged and
+     * never block the exit path. Defaults to none (tests, DSN-absent runs).
+     */
+    report?: (error: unknown, source: "uncaughtException" | "unhandledRejection") => void | Promise<void>;
     stopServer?: () => Promise<void> | void;
 };
 export type FatalProcessHandle = {