@claxedo/workspace-relay-protocol 0.8.0 → 0.10.1

package/README.md

@@ -59,7 +59,7 @@ const claims = await verifier.verify("test-token")
 | `TunnelMessageValidation` | Stable | Result type returned by `validateTunnelMessage` — `{ ok: true, message }` or a typed failure (`protocol_mismatch` / `invalid`). |
 | `makeTunnelPing`, `makeTunnelPong` | Stable | Helpers for heartbeat requests and replies. |
 | `TokenVerifier` and claim types | Stable | Narrow verifier interface shared by relay/runtime boundaries. |
-| `RelayHostVerifierClaims` (incl. `role`) | Stable | Claims shape for host-side verification: org, `role` (`viewer` \| `editor` \| `admin` \| `owner`), and cloud/user-hosted backing discriminant. |
+| `RelayHostVerifierClaims` (incl. `role`) | Stable | Claims shape for host-side verification: org, `role` (`viewer` \| `editor` \| `admin` \| `owner`), and the `cloud-vm` / `local-worktree` backing that names the placement. |
 | `createOidcTokenVerifier` | Public beta | Verifies session JWTs with issuer, audience, JWKS, and algorithm constraints. |
 | `createHttpTokenVerifier` | Public beta | Calls an operator-controlled verifier endpoint over HTTP. |
 | `createStaticTokenVerifier` | Test/single-tenant only | Fixed token table for tests and isolated self-hosted deployments. |
@@ -100,8 +100,11 @@ endpoint and expects `{ subject, scopes?, claims }` back. The endpoint is a
 trusted operator configuration value. Do not derive it from a request, tenant
 record, query string, workspace config, or other user-controlled input.
 
-The endpoint should normally be an HTTPS URL on infrastructure you control. It
-must enforce issuer, audience, expiry, key selection, and replay/revocation
+The endpoint requires HTTPS and redirects are refused. Explicit
+`allowInsecureLoopback: true` permits HTTP only to `localhost`, `127.0.0.1`, or
+`::1` for development. URL credentials and fragments are rejected. Returned
+claims must match the subject and be within their issued/expiry/not-before
+window. The endpoint must enforce issuer, audience, key selection, and replay/revocation
 policy before returning claims. Treat a compromised verifier endpoint as
 equivalent to a compromised token issuer.
 

package/dist/index.d.ts

@@ -1,6 +1,41 @@
 export declare const TUNNEL_PROTOCOL_VERSION = 1;
 export declare const SESSION_STREAM_LEASE_TTL_MS = 15000;
 export declare const SESSION_TURN_LEASE_TTL_MS = 60000;
+/**
+ * Which generation of the sender-identity contract authorizes. 0 is every
+ * binding row and every token written before the transports were proven to
+ * carry the platform's stable account id, whose key may be a handle that now
+ * belongs to somebody else. Authority stores write this number, the relay
+ * admits only this number, and a lower one is never promoted.
+ */
+export declare const CURRENT_CHANNEL_IDENTITY_VERSION = 1;
+/**
+ * A close code a server may send: 1000–4999 except 1004, 1005 and 1006, which
+ * only ever describe a close and which workerd's `close()` refuses; anything
+ * else becomes `fallback`.
+ */
+export declare function closeCode(code: number | undefined, fallback?: number): number;
+/**
+ * A WebSocket close reason cut to the 123 UTF-8 bytes a close frame carries,
+ * at a character boundary. A WHATWG or Node `ws` socket's `close()` throws past
+ * it, and workerd's does from compatibility date 2026-03-03
+ * (`websocket_close_reason_byte_limit`).
+ */
+export declare function closeReason(reason: unknown): string;
+/**
+ * What a Runtime Access Token's scope reaches, asked of the runtime path a
+ * request names. A token with no session is the workspace owner's and reaches
+ * every path; a token scoped to one session, a share holder's, reaches that
+ * session's routes, its own event stream and the answers to its agent's
+ * questions, and the session authority decides which writes the share
+ * carries. The relay asks it before forwarding and the runtime again on
+ * arrival.
+ */
+export declare function sessionScopeReaches(sessionScope: string | undefined, path: string, search: string): boolean;
+/** The relay host id of a session hosted in its own Durable Object, named by the session at the root of its tree. */
+export declare const SESSION_HOST_PREFIX = "session-do:";
+export declare function sessionHostId(rootSessionId: string): string;
+export declare function sessionHostRootOf(hostId: string): string | undefined;
 export { type TokenClaims, type TokenVerifierBaseClaims, type RuntimeAccessVerifierClaims, type RelayHostVerifierClaims, type TokenVerifier, type OidcTokenVerifierClaims, TokenVerifierError, type OidcTokenVerifierOptions, createOidcTokenVerifier, type HttpTokenVerifierOptions, createHttpTokenVerifier, type StaticTokenVerifierOptions, createStaticTokenVerifier, } from "./token-verifier";
 export type TunnelHeaderMap = Record<string, string>;
 export type TunnelPing = {

package/dist/index.mjs

@@ -9,11 +9,11 @@ function isFiniteNumber(value) {
   return typeof value === "number" && Number.isFinite(value);
 }
 function asFiniteNumber(value) {
-  return isFiniteNumber(value) ? value : void 0;
+  return isFiniteNumber(value) ? value : undefined;
 }
 function stringClaim(payload, key) {
   const value = payload[key];
-  return isString(value) && value.trim().length > 0 ? value : void 0;
+  return isString(value) && value.trim().length > 0 ? value : undefined;
 }
 function numberClaim(payload, key) {
   return asFiniteNumber(payload[key]);
@@ -21,7 +21,22 @@ function numberClaim(payload, key) {
 
 // src/token-verifier.ts
 import { createRemoteJWKSet, errors as joseErrors, jwtVerify } from "jose";
-var TokenVerifierError = class extends Error {
+
+// ../claxedo-helpers/dist/index.mjs
+var requestPeerAddresses = new WeakMap;
+function normalizeHostname(hostname) {
+  const value = (hostname ?? "").trim().toLowerCase();
+  if (value.startsWith("[") && value.endsWith("]") && value.includes(":"))
+    return value.slice(1, -1);
+  return value;
+}
+function isLoopbackHostname(hostname) {
+  const normalized = normalizeHostname(hostname);
+  return normalized === "localhost" || normalized === "127.0.0.1" || normalized === "::1";
+}
+
+// src/token-verifier.ts
+class TokenVerifierError extends Error {
   code;
   status;
   constructor(input) {
@@ -29,10 +44,20 @@ var TokenVerifierError = class extends Error {
     this.name = "TokenVerifierError";
     this.code = input.code;
     this.status = input.status ?? 401;
-    if (input.cause !== void 0) this.cause = input.cause;
+    if (input.cause !== undefined)
+      this.cause = input.cause;
   }
-};
+}
 function createHttpTokenVerifier(options) {
+  let endpoint;
+  try {
+    endpoint = new URL(options.endpoint);
+    if (endpoint.username || endpoint.password || endpoint.hash || endpoint.protocol !== "https:" && !(options.allowInsecureLoopback && endpoint.protocol === "http:" && isLoopbackHostname(endpoint.hostname))) {
+      throw new Error("untrusted verifier endpoint");
+    }
+  } catch {
+    throw new TokenVerifierError({ code: "verifier_endpoint_invalid", status: 500, message: "Verifier endpoint requires HTTPS without URL credentials or a fragment; explicit loopback development is the only HTTP exception" });
+  }
   const fetchImpl = options.fetch ?? globalThis.fetch;
   if (!fetchImpl) {
     throw new TokenVerifierError({
@@ -41,14 +66,15 @@ function createHttpTokenVerifier(options) {
       status: 500
     });
   }
-  const timeoutMs = options.timeoutMs ?? 5e3;
+  const timeoutMs = options.timeoutMs ?? 5000;
   return {
     async verify(token) {
-      const controller = new AbortController();
+      const controller = new AbortController;
       const timer = setTimeout(() => controller.abort(), timeoutMs);
       try {
-        const res = await fetchImpl(options.endpoint, {
+        const res = await fetchImpl(endpoint.href, {
           method: "POST",
+          redirect: "error",
           headers: {
             "content-type": "application/json",
             ...options.headers
@@ -84,13 +110,19 @@ function createHttpTokenVerifier(options) {
             message: "Verifier response is missing required token claims"
           });
         }
+        const now = Date.now() / 1000;
+        const nbf = claims.nbf;
+        if (claims.exp <= now || claims.iat > now || claims.exp <= claims.iat || nbf !== undefined && (typeof nbf !== "number" || !Number.isFinite(nbf) || nbf > now)) {
+          throw new TokenVerifierError({ code: "verifier_claims_invalid", message: "Verifier claims are expired or not yet valid" });
+        }
         return {
           subject,
           scopes: Array.isArray(body.scopes) ? body.scopes.filter((s) => typeof s === "string") : [],
           claims
         };
       } catch (err) {
-        if (err instanceof TokenVerifierError) throw err;
+        if (err instanceof TokenVerifierError)
+          throw err;
         throw new TokenVerifierError({
           code: "verifier_unreachable",
           message: err instanceof Error ? err.message : String(err),
@@ -103,7 +135,7 @@ function createHttpTokenVerifier(options) {
     }
   };
 }
-var oidcJwks = /* @__PURE__ */ new Map();
+var oidcJwks = new Map;
 function createOidcTokenVerifier(options) {
   const algorithms = options.algorithms ?? ["ES256", "EdDSA", "RS256"];
   const remote = oidcJwks.get(options.jwksUrl) ?? createRemoteJWKSet(new URL(options.jwksUrl));
@@ -129,7 +161,8 @@ function createOidcTokenVerifier(options) {
           claims
         };
       } catch (err) {
-        if (err instanceof TokenVerifierError) throw err;
+        if (err instanceof TokenVerifierError)
+          throw err;
         const unavailable = err instanceof joseErrors.JWKSTimeout || !(err instanceof joseErrors.JOSEError);
         throw new TokenVerifierError({
           code: unavailable ? "oidc_verifier_unavailable" : "oidc_token_invalid",
@@ -157,7 +190,8 @@ function createStaticTokenVerifier(options) {
   };
 }
 function tokenVerifierBaseClaims(input) {
-  if (!isRecord(input)) return void 0;
+  if (!isRecord(input))
+    return;
   const iss = stringClaim(input, "iss");
   const aud = stringClaim(input, "aud");
   const sub = stringClaim(input, "sub");
@@ -166,7 +200,8 @@ function tokenVerifierBaseClaims(input) {
   const exp = numberClaim(input, "exp");
   const iat = numberClaim(input, "iat");
   const jti = stringClaim(input, "jti");
-  if (!iss || !aud || !sub || !workspace_id || !host_id || !exp || !iat || !jti) return void 0;
+  if (!iss || !aud || !sub || !workspace_id || !host_id || !exp || !iat || !jti)
+    return;
   return {
     ...input,
     iss,
@@ -180,7 +215,8 @@ function tokenVerifierBaseClaims(input) {
   };
 }
 function oidcClaims(input) {
-  if (!input.iss || !input.sub || !input.exp) return void 0;
+  if (!input.iss || !input.sub || !input.exp)
+    return;
   const sid = stringClaim(input, "sid");
   const org_id = stringClaim(input, "org_id");
   const orgId = stringClaim(input, "orgId");
@@ -197,17 +233,65 @@ function oidcClaims(input) {
   };
 }
 function scopeClaims(input) {
-  if (Array.isArray(input.scp)) return input.scp.filter((item) => typeof item === "string");
-  if (typeof input.scope === "string") return input.scope.split(" ").filter(Boolean);
+  if (Array.isArray(input.scp))
+    return input.scp.filter((item) => typeof item === "string");
+  if (typeof input.scope === "string")
+    return input.scope.split(" ").filter(Boolean);
   return [];
 }
 
 // src/index.ts
 var TUNNEL_PROTOCOL_VERSION = 1;
-var SESSION_STREAM_LEASE_TTL_MS = 15e3;
-var SESSION_TURN_LEASE_TTL_MS = 6e4;
+var SESSION_STREAM_LEASE_TTL_MS = 15000;
+var SESSION_TURN_LEASE_TTL_MS = 60000;
+var CURRENT_CHANNEL_IDENTITY_VERSION = 1;
+function closeCode(code, fallback = 1011) {
+  if (code === undefined)
+    return fallback;
+  if (code >= 1000 && code <= 4999 && ![1004, 1005, 1006].includes(code))
+    return code;
+  return fallback;
+}
+var CLOSE_REASON_MAX_BYTES = 123;
+function closeReason(reason) {
+  if (typeof reason !== "string")
+    return "";
+  const encoder = new TextEncoder;
+  if (encoder.encode(reason).byteLength <= CLOSE_REASON_MAX_BYTES)
+    return reason;
+  let cut = "";
+  let bytes = 0;
+  for (const char of reason) {
+    bytes += encoder.encode(char).byteLength;
+    if (bytes > CLOSE_REASON_MAX_BYTES)
+      return cut;
+    cut += char;
+  }
+  return cut;
+}
+function sessionScopeReaches(sessionScope, path, search) {
+  if (sessionScope === undefined)
+    return true;
+  if (path === "/api/wr/events")
+    return new URLSearchParams(search).get("sessionID") === sessionScope;
+  if (path === `/session/${sessionScope}` || path.startsWith(`/session/${sessionScope}/`))
+    return true;
+  if (/^\/api\/wr\/execution-env\/(fs|exec|mcp\/[^/]+)$/.test(path))
+    return true;
+  return /^\/question\/[^/]+\/(reply|reject)$/.test(path);
+}
+var SESSION_HOST_PREFIX = "session-do:";
+function sessionHostId(rootSessionId) {
+  return `${SESSION_HOST_PREFIX}${rootSessionId}`;
+}
+function sessionHostRootOf(hostId) {
+  if (!hostId.startsWith(SESSION_HOST_PREFIX))
+    return;
+  return hostId.slice(SESSION_HOST_PREFIX.length) || undefined;
+}
 function validateTunnelMessage(input) {
-  if (!isRecord(input)) return { ok: false, reason: "invalid" };
+  if (!isRecord(input))
+    return { ok: false, reason: "invalid" };
   if (input.protocol !== TUNNEL_PROTOCOL_VERSION) {
     return {
       ok: false,
@@ -217,7 +301,8 @@ function validateTunnelMessage(input) {
       ...typeof input.type === "string" ? { type: input.type } : {}
     };
   }
-  if (!isTunnelMessageRecord(input)) return { ok: false, reason: "invalid" };
+  if (!isTunnelMessageRecord(input))
+    return { ok: false, reason: "invalid" };
   return { ok: true, message: input };
 }
 function isTunnelMessage(input) {
@@ -241,7 +326,8 @@ function makeTunnelPing(sentAt = Date.now(), id = crypto.randomUUID()) {
   };
 }
 function isTunnelMessageRecord(row) {
-  if (row.protocol !== TUNNEL_PROTOCOL_VERSION) return false;
+  if (row.protocol !== TUNNEL_PROTOCOL_VERSION)
+    return false;
   switch (row.type) {
     case "ping":
       return isNonEmptyString(row.id) && isFiniteNumber(row.sent_at);
@@ -258,15 +344,15 @@ function isTunnelMessageRecord(row) {
     case "http.response.end":
       return isNonEmptyString(row.request_id);
     case "http.response.flow":
-      return isNonEmptyString(row.request_id) && typeof row.paused === "boolean" && (row.reason === void 0 || row.reason === "slow_consumer" || row.reason === "drained" || row.reason === "closed");
+      return isNonEmptyString(row.request_id) && typeof row.paused === "boolean" && (row.reason === undefined || row.reason === "slow_consumer" || row.reason === "drained" || row.reason === "closed");
     case "ws.open":
       return isNonEmptyString(row.channel_id) && isNonEmptyString(row.workspace_id) && isNonEmptyString(row.path) && isTunnelHeaderMap(row.headers);
     case "ws.frame":
       return isNonEmptyString(row.channel_id) && isBase64(row.data_base64) && typeof row.binary === "boolean";
     case "ws.close":
-      return isNonEmptyString(row.channel_id) && (row.code === void 0 || isCloseCode(row.code)) && (row.reason === void 0 || isNonEmptyString(row.reason));
+      return isNonEmptyString(row.channel_id) && (row.code === undefined || isCloseCode(row.code)) && (row.reason === undefined || isNonEmptyString(row.reason));
     case "error":
-      return (row.request_id === void 0 || isNonEmptyString(row.request_id)) && (row.channel_id === void 0 || isNonEmptyString(row.channel_id)) && isNonEmptyString(row.code) && isNonEmptyString(row.message);
+      return (row.request_id === undefined || isNonEmptyString(row.request_id)) && (row.channel_id === undefined || isNonEmptyString(row.channel_id)) && isNonEmptyString(row.code) && isNonEmptyString(row.message);
     default:
       return false;
   }
@@ -281,31 +367,41 @@ function isHttpStatus(input) {
   return typeof input === "number" && Number.isInteger(input) && input >= 100 && input <= 599;
 }
 function isCloseCode(input) {
-  return typeof input === "number" && Number.isInteger(input) && input >= 0 && input <= 65535;
+  return typeof input === "number" && Number.isInteger(input) && input >= 1000 && input <= 4999 && input !== 1004 && input !== 1005 && input !== 1006 && input !== 1015;
 }
+var HEADER_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
 function isTunnelHeaderMap(input) {
-  if (!input || typeof input !== "object" || Array.isArray(input)) return false;
-  for (const value of Object.values(input)) {
-    if (typeof value !== "string") return false;
+  if (!input || typeof input !== "object" || Array.isArray(input))
+    return false;
+  for (const [name, value] of Object.entries(input)) {
+    if (!HEADER_NAME.test(name) || typeof value !== "string")
+      return false;
   }
   return true;
 }
 function isOptionalBase64(input) {
-  return input === void 0 || isBase64(input);
+  return input === undefined || isBase64(input);
 }
 function isBase64(input) {
   return typeof input === "string" && /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(input);
 }
 export {
-  SESSION_STREAM_LEASE_TTL_MS,
-  SESSION_TURN_LEASE_TTL_MS,
-  TUNNEL_PROTOCOL_VERSION,
-  TokenVerifierError,
-  createHttpTokenVerifier,
-  createOidcTokenVerifier,
-  createStaticTokenVerifier,
-  isTunnelMessage,
-  makeTunnelPing,
+  validateTunnelMessage,
+  sessionScopeReaches,
+  sessionHostRootOf,
+  sessionHostId,
   makeTunnelPong,
-  validateTunnelMessage
+  makeTunnelPing,
+  isTunnelMessage,
+  createStaticTokenVerifier,
+  createOidcTokenVerifier,
+  createHttpTokenVerifier,
+  closeReason,
+  closeCode,
+  TokenVerifierError,
+  TUNNEL_PROTOCOL_VERSION,
+  SESSION_TURN_LEASE_TTL_MS,
+  SESSION_STREAM_LEASE_TTL_MS,
+  SESSION_HOST_PREFIX,
+  CURRENT_CHANNEL_IDENTITY_VERSION
 };

package/dist/token-verifier.d.ts

@@ -26,8 +26,13 @@ export type TokenVerifierBaseClaims = {
 export type RuntimeAccessVerifierClaims = Omit<TokenVerifierBaseClaims, "sub"> & {
     org_id: string;
     role: "viewer" | "editor" | "admin" | "owner";
+    /** The whole workspace, or the one session `session_id` names. */
+    scope: "workspace" | "session";
+    session_id?: string;
+    purpose?: "turn-execution";
     principal_kind: "user" | "service";
     actor_id: string;
+    user_id?: string;
     actor_kind: "human" | "agent";
     actor_public_id?: string;
     actor_name?: string;
@@ -36,21 +41,20 @@ export type RuntimeAccessVerifierClaims = Omit<TokenVerifierBaseClaims, "sub"> &
 export type RelayHostVerifierClaims = Omit<TokenVerifierBaseClaims, "sub"> & {
     org_id: string;
     role: "viewer" | "editor" | "admin" | "owner";
+    scope: "workspace" | "session";
+    session_id?: string;
+    purpose?: "turn-execution";
     principal_kind: "user" | "service";
     actor_id: string;
+    user_id?: string;
     actor_kind: "human" | "agent";
     actor_public_id?: string;
     actor_name?: string;
     actor_avatar_url?: string;
     /** Durable Runtime Access Token id; distinct from this short-lived RHT jti. */
     parent_jti: string;
-} & ({
-    access: "cloud";
-    backing: "cloud-vm";
-} | {
-    access: "user-hosted";
-    backing: "local-worktree";
-});
+    backing: "cloud-vm" | "local-worktree" | "durable-object";
+};
 export type TokenClaims<TClaims extends Record<string, unknown> = Record<string, unknown>> = {
     /** Provider subject for provider-backed identity verifiers. Runtime and
      * relay-host tokens instead carry canonical actor/principal claims. */
@@ -89,6 +93,8 @@ export type HttpTokenVerifierOptions = {
      *  and return `{ subject: string; scopes?: string[]; claims: TokenVerifierBaseClaims }`
      *  on success, or HTTP non-2xx on failure. */
     endpoint: string;
+    /** Development only: permit HTTP to the exact loopback hosts. HTTPS is otherwise required. */
+    allowInsecureLoopback?: boolean;
     /** Optional fixed headers (e.g., bearer auth on the verifier itself). */
     headers?: Record<string, string>;
     /** fetch override for tests. */

package/package.json

@@ -33,22 +33,20 @@
     "access": "public"
   },
   "name": "@claxedo/workspace-relay-protocol",
-  "version": "0.8.0",
+  "version": "0.10.1",
   "scripts": {
-    "build": "tsx scripts/build.ts",
+    "build": "bun scripts/build.ts",
     "prepublishOnly": "npm run build",
     "typecheck": "tsc --noEmit -p tsconfig.json",
-    "test": "mkdir -p .artifacts/unit && node ../../scripts/test-deadline.mjs bun test src --reporter=junit --reporter-outfile=.artifacts/unit/junit.xml"
+    "test": "mkdir -p .artifacts/unit && node ../../script/test-deadline.mjs bun test src --reporter=junit --reporter-outfile=.artifacts/unit/junit.xml"
   },
   "dependencies": {
-    "@claxedo/helpers": "0.1.0",
+    "@claxedo/helpers": "0.2.1",
     "jose": "6.0.11"
   },
   "devDependencies": {
     "@tsconfig/node-lts": "22.0.4",
     "@types/bun": "1.3.13",
-    "esbuild": "0.25.12",
-    "tsx": "4.22.3",
     "typescript": "catalog:"
   }
 }