@claxedo/workspace-relay-protocol 0.6.0 → 0.8.0

package/README.md

@@ -60,7 +60,7 @@ const claims = await verifier.verify("test-token")
 | `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. |
+| `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. |
 

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 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;
+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,5 +1,26 @@
+// ../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 : void 0;
+}
+function stringClaim(payload, key) {
+  const value = payload[key];
+  return isString(value) && value.trim().length > 0 ? value : void 0;
+}
+function numberClaim(payload, key) {
+  return asFiniteNumber(payload[key]);
+}
+
 // src/token-verifier.ts
-import { createRemoteJWKSet, jwtVerify } from "jose";
+import { createRemoteJWKSet, errors as joseErrors, jwtVerify } from "jose";
 var TokenVerifierError = class extends Error {
   code;
   status;
@@ -30,34 +51,41 @@ function createHttpTokenVerifier(options) {
           method: "POST",
           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"
           });
         }
         return {
-          subject: body.subject,
+          subject,
           scopes: Array.isArray(body.scopes) ? body.scopes.filter((s) => typeof s === "string") : [],
           claims
         };
@@ -66,6 +94,7 @@ function createHttpTokenVerifier(options) {
         throw new TokenVerifierError({
           code: "verifier_unreachable",
           message: err instanceof Error ? err.message : String(err),
+          status: 503,
           cause: err
         });
       } finally {
@@ -74,11 +103,11 @@ function createHttpTokenVerifier(options) {
     }
   };
 }
-var clerkJwks = /* @__PURE__ */ new Map();
-function createClerkTokenVerifier(options) {
+var oidcJwks = /* @__PURE__ */ 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 +116,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 {
@@ -101,9 +130,11 @@ function createClerkTokenVerifier(options) {
         };
       } catch (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,9 +142,10 @@ function createClerkTokenVerifier(options) {
   };
 }
 function createStaticTokenVerifier(options) {
+  const tokens = new Map(Object.entries(options.tokens));
   return {
     async verify(token) {
-      const claims = options.tokens[token];
+      const claims = tokens.get(token);
       if (!claims) {
         throw new TokenVerifierError({
           code: "token_not_in_static_table",
@@ -124,16 +156,8 @@ 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 void 0;
   const iss = stringClaim(input, "iss");
   const aud = stringClaim(input, "aud");
   const sub = stringClaim(input, "sub");
@@ -142,7 +166,7 @@ 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 void 0;
   return {
     ...input,
     iss,
@@ -155,8 +179,11 @@ 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 void 0;
+  const sid = stringClaim(input, "sid");
+  const org_id = stringClaim(input, "org_id");
+  const orgId = stringClaim(input, "orgId");
   return {
     ...input,
     iss: input.iss,
@@ -164,9 +191,9 @@ 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) {
@@ -177,39 +204,24 @@ function scopeClaims(input) {
 
 // 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 = 15e3;
+var SESSION_TURN_LEASE_TTL_MS = 6e4;
 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 {
@@ -228,44 +240,42 @@ 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 === void 0 || 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 === void 0 || isCloseCode(row.code)) && (row.reason === void 0 || 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 === void 0 || isNonEmptyString(row.request_id)) && (row.channel_id === void 0 || 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;
@@ -287,10 +297,12 @@ 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,
-  createClerkTokenVerifier,
   createHttpTokenVerifier,
+  createOidcTokenVerifier,
   createStaticTokenVerifier,
   isTunnelMessage,
   makeTunnelPing,

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,13 +23,27 @@ 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";
+    principal_kind: "user" | "service";
+    actor_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";
+    principal_kind: "user" | "service";
+    actor_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";
@@ -38,9 +52,9 @@ export type RelayHostVerifierClaims = TokenVerifierBaseClaims & {
     backing: "local-worktree";
 });
 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 +64,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;
@@ -83,14 +97,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.6.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,14 +32,17 @@
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {
-    "jose": "6.0.11"
-  },
+  "name": "@claxedo/workspace-relay-protocol",
+  "version": "0.8.0",
   "scripts": {
     "build": "tsx scripts/build.ts",
     "prepublishOnly": "npm run build",
     "typecheck": "tsc --noEmit -p tsconfig.json",
-    "test": "bun test src"
+    "test": "mkdir -p .artifacts/unit && node ../../scripts/test-deadline.mjs bun test src --reporter=junit --reporter-outfile=.artifacts/unit/junit.xml"
+  },
+  "dependencies": {
+    "@claxedo/helpers": "0.1.0",
+    "jose": "6.0.11"
   },
   "devDependencies": {
     "@tsconfig/node-lts": "22.0.4",