@claxedo/workspace-relay-protocol 0.7.0 → 0.10.0

package/README.md

@@ -59,8 +59,8 @@ 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. |
-| `createClerkTokenVerifier` | Public beta | Verifies Clerk session tokens with issuer, audience, JWKS, and algorithm constraints. |
+| `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,5 +1,29 @@
 export declare const TUNNEL_PROTOCOL_VERSION = 1;
-export { type TokenClaims, type TokenVerifierBaseClaims, type RuntimeAccessVerifierClaims, type RelayHostVerifierClaims, type TokenVerifier, type ClerkTokenVerifierClaims, TokenVerifierError, type ClerkTokenVerifierOptions, createClerkTokenVerifier, type HttpTokenVerifierOptions, createHttpTokenVerifier, type StaticTokenVerifierOptions, createStaticTokenVerifier, } from "./token-verifier";
+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;
+/**
+ * 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 = {
     type: "ping";

package/dist/index.mjs

@@ -1,6 +1,42 @@
+// ../claxedo-helpers/dist/guards.mjs
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isString(value) {
+  return typeof value === "string";
+}
+function isFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function asFiniteNumber(value) {
+  return isFiniteNumber(value) ? value : undefined;
+}
+function stringClaim(payload, key) {
+  const value = payload[key];
+  return isString(value) && value.trim().length > 0 ? value : undefined;
+}
+function numberClaim(payload, key) {
+  return asFiniteNumber(payload[key]);
+}
+
 // src/token-verifier.ts
-import { createRemoteJWKSet, jwtVerify } from "jose";
-var TokenVerifierError = class extends Error {
+import { createRemoteJWKSet, errors as joseErrors, jwtVerify } from "jose";
+
+// ../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) {
@@ -8,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({
@@ -20,52 +66,67 @@ 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 ?? {}
+            ...options.headers
           },
           body: JSON.stringify({ token }),
           signal: controller.signal
         });
         if (!res.ok) {
           throw new TokenVerifierError({
-            code: "verifier_rejected",
+            code: res.status === 401 || res.status === 403 ? "verifier_rejected" : "verifier_unavailable",
             message: `Verifier endpoint returned ${res.status}`,
-            status: res.status === 401 || res.status === 403 ? res.status : 401
+            status: res.status === 401 || res.status === 403 ? res.status : 503
           });
         }
         const body = await res.json().catch(() => null);
-        if (!body || typeof body.subject !== "string" || !body.subject) {
+        if (!isRecord(body)) {
+          throw new TokenVerifierError({
+            code: "verifier_response_invalid",
+            message: "Verifier response is missing a subject"
+          });
+        }
+        const subject = stringClaim(body, "subject");
+        if (!subject) {
           throw new TokenVerifierError({
             code: "verifier_response_invalid",
             message: "Verifier response is missing a subject"
           });
         }
         const claims = tokenVerifierBaseClaims(body.claims);
-        if (!claims || claims.sub !== body.subject) {
+        if (!claims || claims.sub !== subject) {
           throw new TokenVerifierError({
             code: "verifier_response_invalid",
             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: body.subject,
+          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),
+          status: 503,
           cause: err
         });
       } finally {
@@ -74,11 +135,11 @@ function createHttpTokenVerifier(options) {
     }
   };
 }
-var clerkJwks = /* @__PURE__ */ new Map();
-function createClerkTokenVerifier(options) {
+var oidcJwks = new Map;
+function createOidcTokenVerifier(options) {
   const algorithms = options.algorithms ?? ["ES256", "EdDSA", "RS256"];
-  const remote = clerkJwks.get(options.jwksUrl) ?? createRemoteJWKSet(new URL(options.jwksUrl));
-  clerkJwks.set(options.jwksUrl, remote);
+  const remote = oidcJwks.get(options.jwksUrl) ?? createRemoteJWKSet(new URL(options.jwksUrl));
+  oidcJwks.set(options.jwksUrl, remote);
   return {
     async verify(token) {
       try {
@@ -87,11 +148,11 @@ function createClerkTokenVerifier(options) {
           audience: options.audience,
           algorithms
         });
-        const claims = clerkClaims(result.payload);
+        const claims = oidcClaims(result.payload);
         if (!claims) {
           throw new TokenVerifierError({
-            code: "clerk_claims_invalid",
-            message: "Clerk token is missing required session claims"
+            code: "oidc_claims_invalid",
+            message: "Session token is missing required claims"
           });
         }
         return {
@@ -100,10 +161,13 @@ function createClerkTokenVerifier(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: "clerk_token_invalid",
-          message: "Clerk session token is invalid",
+          code: unavailable ? "oidc_verifier_unavailable" : "oidc_token_invalid",
+          message: unavailable ? "Session verifier is unavailable" : "Session token is invalid",
+          status: unavailable ? 503 : 401,
           cause: err
         });
       }
@@ -111,10 +175,10 @@ function createClerkTokenVerifier(options) {
   };
 }
 function createStaticTokenVerifier(options) {
-  const tokens = Object.assign(/* @__PURE__ */ Object.create(null), options.tokens);
+  const tokens = new Map(Object.entries(options.tokens));
   return {
     async verify(token) {
-      const claims = tokens[token];
+      const claims = tokens.get(token);
       if (!claims) {
         throw new TokenVerifierError({
           code: "token_not_in_static_table",
@@ -125,16 +189,9 @@ function createStaticTokenVerifier(options) {
     }
   };
 }
-function stringClaim(input, key) {
-  const value = input[key];
-  return typeof value === "string" && value.trim() ? value : void 0;
-}
-function numberClaim(input, key) {
-  const value = input[key];
-  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
-}
 function tokenVerifierBaseClaims(input) {
-  if (!input || typeof input !== "object") return;
+  if (!isRecord(input))
+    return;
   const iss = stringClaim(input, "iss");
   const aud = stringClaim(input, "aud");
   const sub = stringClaim(input, "sub");
@@ -143,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;
+  if (!iss || !aud || !sub || !workspace_id || !host_id || !exp || !iat || !jti)
+    return;
   return {
     ...input,
     iss,
@@ -156,8 +214,12 @@ function tokenVerifierBaseClaims(input) {
     jti
   };
 }
-function clerkClaims(input) {
-  if (!input.iss || !input.sub || !input.exp) return;
+function oidcClaims(input) {
+  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");
   return {
     ...input,
     iss: input.iss,
@@ -165,52 +227,62 @@ function clerkClaims(input) {
     exp: input.exp,
     ...input.iat ? { iat: input.iat } : {},
     ...typeof input.jti === "string" ? { jti: input.jti } : {},
-    ...stringClaim(input, "sid") ? { sid: stringClaim(input, "sid") } : {},
-    ...stringClaim(input, "org_id") ? { org_id: stringClaim(input, "org_id") } : {},
-    ...stringClaim(input, "orgId") ? { orgId: stringClaim(input, "orgId") } : {}
+    ...sid ? { sid } : {},
+    ...org_id ? { org_id } : {},
+    ...orgId ? { orgId } : {}
   };
 }
 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 tunnelMessageTypes = /* @__PURE__ */ new Set([
-  "ping",
-  "pong",
-  "host.registration.update",
-  "http.request",
-  "http.response.start",
-  "http.response.chunk",
-  "http.response.end",
-  "http.response.flow",
-  "ws.open",
-  "ws.frame",
-  "ws.close",
-  "error"
-]);
+var SESSION_STREAM_LEASE_TTL_MS = 15000;
+var SESSION_TURN_LEASE_TTL_MS = 60000;
+var CURRENT_CHANNEL_IDENTITY_VERSION = 1;
+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 (!input || typeof input !== "object") return { ok: false, reason: "invalid" };
-  const row = input;
-  if (row.protocol !== TUNNEL_PROTOCOL_VERSION) {
+  if (!isRecord(input))
+    return { ok: false, reason: "invalid" };
+  if (input.protocol !== TUNNEL_PROTOCOL_VERSION) {
     return {
       ok: false,
       reason: "protocol_mismatch",
       expected_protocol: TUNNEL_PROTOCOL_VERSION,
-      actual_protocol: row.protocol,
-      ...typeof row.type === "string" ? { type: row.type } : {}
+      actual_protocol: input.protocol,
+      ...typeof input.type === "string" ? { type: input.type } : {}
     };
   }
-  if (typeof row.type !== "string") return { ok: false, reason: "invalid" };
-  if (!tunnelMessageTypes.has(row.type)) return { ok: false, reason: "invalid" };
-  if (!validateTunnelMessageShape(row)) return { ok: false, reason: "invalid" };
-  return { ok: true, message: row };
+  if (!isTunnelMessageRecord(input))
+    return { ok: false, reason: "invalid" };
+  return { ok: true, message: input };
 }
 function isTunnelMessage(input) {
-  return validateTunnelMessage(input).ok;
+  return isRecord(input) && isTunnelMessageRecord(input);
 }
 function makeTunnelPong(input, receivedAt = Date.now()) {
   return {
@@ -229,72 +301,81 @@ function makeTunnelPing(sentAt = Date.now(), id = crypto.randomUUID()) {
     sent_at: sentAt
   };
 }
-function validateTunnelMessageShape(row) {
+function isTunnelMessageRecord(row) {
+  if (row.protocol !== TUNNEL_PROTOCOL_VERSION)
+    return false;
   switch (row.type) {
     case "ping":
-      return isString(row.id) && isFiniteNumber(row.sent_at);
+      return isNonEmptyString(row.id) && isFiniteNumber(row.sent_at);
     case "pong":
-      return isString(row.id) && isFiniteNumber(row.sent_at) && isFiniteNumber(row.received_at);
+      return isNonEmptyString(row.id) && isFiniteNumber(row.sent_at) && isFiniteNumber(row.received_at);
     case "host.registration.update":
-      return isStringArray(row.workspace_ids) && isString(row.token);
+      return isStringArray(row.workspace_ids) && isNonEmptyString(row.token);
     case "http.request":
-      return isString(row.request_id) && isString(row.workspace_id) && isString(row.method) && isString(row.path) && isTunnelHeaderMap(row.headers) && isOptionalBase64(row.body_base64) && typeof row.end === "boolean";
+      return isNonEmptyString(row.request_id) && isNonEmptyString(row.workspace_id) && isNonEmptyString(row.method) && isNonEmptyString(row.path) && isTunnelHeaderMap(row.headers) && isOptionalBase64(row.body_base64) && typeof row.end === "boolean";
     case "http.response.start":
-      return isString(row.request_id) && isHttpStatus(row.status) && isTunnelHeaderMap(row.headers);
+      return isNonEmptyString(row.request_id) && isHttpStatus(row.status) && isTunnelHeaderMap(row.headers);
     case "http.response.chunk":
-      return isString(row.request_id) && isBase64(row.body_base64);
+      return isNonEmptyString(row.request_id) && isBase64(row.body_base64);
     case "http.response.end":
-      return isString(row.request_id);
+      return isNonEmptyString(row.request_id);
     case "http.response.flow":
-      return isString(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 isString(row.channel_id) && isString(row.workspace_id) && isString(row.path) && isTunnelHeaderMap(row.headers);
+      return isNonEmptyString(row.channel_id) && isNonEmptyString(row.workspace_id) && isNonEmptyString(row.path) && isTunnelHeaderMap(row.headers);
     case "ws.frame":
-      return isString(row.channel_id) && isBase64(row.data_base64) && typeof row.binary === "boolean";
+      return isNonEmptyString(row.channel_id) && isBase64(row.data_base64) && typeof row.binary === "boolean";
     case "ws.close":
-      return isString(row.channel_id) && (row.code === void 0 || isCloseCode(row.code)) && (row.reason === void 0 || isString(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 || isString(row.request_id)) && (row.channel_id === void 0 || isString(row.channel_id)) && isString(row.code) && isString(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;
   }
 }
-function isString(input) {
+function isNonEmptyString(input) {
   return typeof input === "string" && input.length > 0;
 }
 function isStringArray(input) {
-  return Array.isArray(input) && input.length > 0 && input.every(isString);
-}
-function isFiniteNumber(input) {
-  return typeof input === "number" && Number.isFinite(input);
+  return Array.isArray(input) && input.length > 0 && input.every(isNonEmptyString);
 }
 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 {
-  TUNNEL_PROTOCOL_VERSION,
-  TokenVerifierError,
-  createClerkTokenVerifier,
-  createHttpTokenVerifier,
-  createStaticTokenVerifier,
-  isTunnelMessage,
-  makeTunnelPing,
+  validateTunnelMessage,
+  sessionScopeReaches,
+  sessionHostRootOf,
+  sessionHostId,
   makeTunnelPong,
-  validateTunnelMessage
+  makeTunnelPing,
+  isTunnelMessage,
+  createStaticTokenVerifier,
+  createOidcTokenVerifier,
+  createHttpTokenVerifier,
+  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

@@ -1,7 +1,7 @@
 /**
  * Unified token-verifier interface (P-shared).
  *
- * Each of the four Claxedo boundaries (relay/tunnel, agent extension,
+ * Each of the four Claxedo boundaries (relay/tunnel, optional modules,
  * SDK runner, workspace host) historically defined its own ad-hoc
  * verifier shape. This module is the single seam every downstream user
  * can swap a custom implementation through.
@@ -23,24 +23,42 @@ export type TokenVerifierBaseClaims = {
     iat: number;
     jti: string;
 } & Record<string, unknown>;
-export type RuntimeAccessVerifierClaims = 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;
+    actor_avatar_url?: string;
 };
-export type RelayHostVerifierClaims = TokenVerifierBaseClaims & {
+export type RelayHostVerifierClaims = Omit<TokenVerifierBaseClaims, "sub"> & {
     org_id: string;
     role: "viewer" | "editor" | "admin" | "owner";
-} & ({
-    access: "cloud";
-    backing: "cloud-vm";
-} | {
-    access: "user-hosted";
-    backing: "local-worktree";
-});
+    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;
+    backing: "cloud-vm" | "local-worktree" | "durable-object";
+};
 export type TokenClaims<TClaims extends Record<string, unknown> = Record<string, unknown>> = {
-    /** Stable subject id. The boundary is responsible for mapping this
-     *  to a domain principal (user, workspace, runtime, etc.). */
-    subject: string;
+    /** Provider subject for provider-backed identity verifiers. Runtime and
+     * relay-host tokens instead carry canonical actor/principal claims. */
+    subject?: string;
     /** Scopes / capabilities asserted by the issuer. May be empty. */
     scopes: string[];
     /** Full claim payload. Carries the common verifier token contract plus
@@ -50,7 +68,7 @@ export type TokenClaims<TClaims extends Record<string, unknown> = Record<string,
 export type TokenVerifier<TClaims extends Record<string, unknown> = Record<string, unknown>> = {
     verify(token: string): Promise<TokenClaims<TClaims>>;
 };
-export type ClerkTokenVerifierClaims = JWTPayload & {
+export type OidcTokenVerifierClaims = JWTPayload & {
     iss: string;
     sub: string;
     exp: number;
@@ -75,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. */
@@ -83,14 +103,14 @@ export type HttpTokenVerifierOptions = {
     timeoutMs?: number;
 };
 export declare function createHttpTokenVerifier(options: HttpTokenVerifierOptions): TokenVerifier<TokenVerifierBaseClaims>;
-export type ClerkTokenVerifierOptions = {
+export type OidcTokenVerifierOptions = {
     issuer: string;
     jwksUrl: string;
     audience?: string;
     scopes?: string[];
     algorithms?: Array<"ES256" | "EdDSA" | "RS256">;
 };
-export declare function createClerkTokenVerifier(options: ClerkTokenVerifierOptions): TokenVerifier<ClerkTokenVerifierClaims>;
+export declare function createOidcTokenVerifier(options: OidcTokenVerifierOptions): TokenVerifier<OidcTokenVerifierClaims>;
 export type StaticTokenVerifierOptions<TClaims extends Record<string, unknown> = Record<string, unknown>> = {
     /** Map of token string → claims to return. */
     tokens: Record<string, TokenClaims<TClaims>>;

package/package.json

@@ -1,6 +1,4 @@
 {
-  "name": "@claxedo/workspace-relay-protocol",
-  "version": "0.7.0",
   "type": "module",
   "description": "Wire types, message validation, and token verifier interfaces for the Claxedo workspace relay tunnel protocol",
   "license": "MIT",
@@ -19,9 +17,9 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "development": "./src/index.ts",
+      "bun": "./src/index.ts",
       "types": "./dist/index.d.ts",
-      "bun": "./dist/index.mjs",
-      "development": "./dist/index.mjs",
       "import": "./dist/index.mjs",
       "default": "./dist/index.mjs"
     }
@@ -34,20 +32,21 @@
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {
-    "jose": "6.0.11"
-  },
+  "name": "@claxedo/workspace-relay-protocol",
+  "version": "0.10.0",
   "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 && 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.2.0",
+    "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:"
   }
 }