@claxedo/workspace-relay-protocol 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,78 @@
+export declare const TUNNEL_PROTOCOL_VERSION = 1;
+export { type TokenClaims, type TokenVerifier, TokenVerifierError, type HttpTokenVerifierOptions, createHttpTokenVerifier, type StaticTokenVerifierOptions, createStaticTokenVerifier, } from "./token-verifier";
+export type TunnelHeaderMap = Record<string, string>;
+export type TunnelPing = {
+    type: "ping";
+    protocol: typeof TUNNEL_PROTOCOL_VERSION;
+    id: string;
+    sent_at: number;
+};
+export type TunnelPong = {
+    type: "pong";
+    protocol: typeof TUNNEL_PROTOCOL_VERSION;
+    id: string;
+    sent_at: number;
+    received_at: number;
+};
+export type TunnelHttpRequest = {
+    type: "http.request";
+    protocol: typeof TUNNEL_PROTOCOL_VERSION;
+    request_id: string;
+    workspace_id: string;
+    method: string;
+    path: string;
+    headers: TunnelHeaderMap;
+    body_base64?: string;
+    end: boolean;
+};
+export type TunnelHttpResponseStart = {
+    type: "http.response.start";
+    protocol: typeof TUNNEL_PROTOCOL_VERSION;
+    request_id: string;
+    status: number;
+    headers: TunnelHeaderMap;
+};
+export type TunnelHttpResponseChunk = {
+    type: "http.response.chunk";
+    protocol: typeof TUNNEL_PROTOCOL_VERSION;
+    request_id: string;
+    body_base64: string;
+};
+export type TunnelHttpResponseEnd = {
+    type: "http.response.end";
+    protocol: typeof TUNNEL_PROTOCOL_VERSION;
+    request_id: string;
+};
+export type TunnelWsOpen = {
+    type: "ws.open";
+    protocol: typeof TUNNEL_PROTOCOL_VERSION;
+    channel_id: string;
+    workspace_id: string;
+    path: string;
+    headers: TunnelHeaderMap;
+};
+export type TunnelWsFrame = {
+    type: "ws.frame";
+    protocol: typeof TUNNEL_PROTOCOL_VERSION;
+    channel_id: string;
+    data_base64: string;
+    binary: boolean;
+};
+export type TunnelWsClose = {
+    type: "ws.close";
+    protocol: typeof TUNNEL_PROTOCOL_VERSION;
+    channel_id: string;
+    code?: number;
+    reason?: string;
+};
+export type TunnelError = {
+    type: "error";
+    protocol: typeof TUNNEL_PROTOCOL_VERSION;
+    request_id?: string;
+    channel_id?: string;
+    code: string;
+    message: string;
+};
+export type TunnelMessage = TunnelPing | TunnelPong | TunnelHttpRequest | TunnelHttpResponseStart | TunnelHttpResponseChunk | TunnelHttpResponseEnd | TunnelWsOpen | TunnelWsFrame | TunnelWsClose | TunnelError;
+export declare function isTunnelMessage(input: unknown): input is TunnelMessage;
+export declare function makeTunnelPong(input: TunnelPing, receivedAt?: number): TunnelPong;

package/dist/index.mjs

@@ -0,0 +1,119 @@
+// src/token-verifier.ts
+var TokenVerifierError = class extends Error {
+  code;
+  status;
+  constructor(input) {
+    super(input.message);
+    this.name = "TokenVerifierError";
+    this.code = input.code;
+    this.status = input.status ?? 401;
+    if (input.cause !== void 0) this.cause = input.cause;
+  }
+};
+function createHttpTokenVerifier(options) {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  if (!fetchImpl) {
+    throw new TokenVerifierError({
+      code: "fetch_unavailable",
+      message: "createHttpTokenVerifier requires a fetch implementation in this runtime",
+      status: 500
+    });
+  }
+  const timeoutMs = options.timeoutMs ?? 5e3;
+  return {
+    async verify(token) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const res = await fetchImpl(options.endpoint, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            ...options.headers ?? {}
+          },
+          body: JSON.stringify({ token }),
+          signal: controller.signal
+        });
+        if (!res.ok) {
+          throw new TokenVerifierError({
+            code: "verifier_rejected",
+            message: `Verifier endpoint returned ${res.status}`,
+            status: res.status === 401 || res.status === 403 ? res.status : 401
+          });
+        }
+        const body = await res.json().catch(() => null);
+        if (!body || typeof body.subject !== "string" || !body.subject) {
+          throw new TokenVerifierError({
+            code: "verifier_response_invalid",
+            message: "Verifier response is missing a subject"
+          });
+        }
+        return {
+          subject: body.subject,
+          scopes: Array.isArray(body.scopes) ? body.scopes.filter((s) => typeof s === "string") : [],
+          claims: body.claims && typeof body.claims === "object" ? body.claims : {}
+        };
+      } catch (err) {
+        if (err instanceof TokenVerifierError) throw err;
+        throw new TokenVerifierError({
+          code: "verifier_unreachable",
+          message: err instanceof Error ? err.message : String(err),
+          cause: err
+        });
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+  };
+}
+function createStaticTokenVerifier(options) {
+  return {
+    async verify(token) {
+      const claims = options.tokens[token];
+      if (!claims) {
+        throw new TokenVerifierError({
+          code: "token_not_in_static_table",
+          message: "Token is not present in the static verifier's accepted set"
+        });
+      }
+      return claims;
+    }
+  };
+}
+
+// src/index.ts
+var TUNNEL_PROTOCOL_VERSION = 1;
+var tunnelMessageTypes = /* @__PURE__ */ new Set([
+  "ping",
+  "pong",
+  "http.request",
+  "http.response.start",
+  "http.response.chunk",
+  "http.response.end",
+  "ws.open",
+  "ws.frame",
+  "ws.close",
+  "error"
+]);
+function isTunnelMessage(input) {
+  if (!input || typeof input !== "object") return false;
+  const row = input;
+  return row.protocol === TUNNEL_PROTOCOL_VERSION && typeof row.type === "string" && tunnelMessageTypes.has(row.type);
+}
+function makeTunnelPong(input, receivedAt = Date.now()) {
+  return {
+    type: "pong",
+    protocol: TUNNEL_PROTOCOL_VERSION,
+    id: input.id,
+    sent_at: input.sent_at,
+    received_at: receivedAt
+  };
+}
+export {
+  TUNNEL_PROTOCOL_VERSION,
+  TokenVerifierError,
+  createHttpTokenVerifier,
+  createStaticTokenVerifier,
+  isTunnelMessage,
+  makeTunnelPong
+};

package/dist/token-verifier.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Unified token-verifier interface (P-shared).
+ *
+ * Each of the four Claxedo boundaries (relay/tunnel, agent extension,
+ * 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.
+ *
+ * The interface is intentionally narrow: token in, claims out. It does
+ * not expose JWKS plumbing, audience-binding sugar, or replay-cache
+ * details — those belong to the impl, not the contract.
+ *
+ * See the boundary READMEs for wiring rules.
+ */
+export type TokenClaims = {
+    /** Stable subject id. The boundary is responsible for mapping this
+     *  to a domain principal (user, workspace, runtime, etc.). */
+    subject: string;
+    /** Scopes / capabilities asserted by the issuer. May be empty. */
+    scopes: string[];
+    /** Full claim payload. Carries audience, issuer, expiry, plus any
+     *  boundary-specific custom claims. */
+    claims: Record<string, unknown>;
+};
+export type TokenVerifier = {
+    verify(token: string): Promise<TokenClaims>;
+};
+export declare class TokenVerifierError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(input: {
+        code: string;
+        message: string;
+        status?: number;
+        cause?: unknown;
+    });
+}
+export type HttpTokenVerifierOptions = {
+    /** Verifier endpoint. Must accept POST with `{ token }` JSON body
+     *  and return `{ subject: string; scopes?: string[]; claims?: Record<string, unknown> }`
+     *  on success, or HTTP non-2xx on failure. */
+    endpoint: string;
+    /** Optional fixed headers (e.g., bearer auth on the verifier itself). */
+    headers?: Record<string, string>;
+    /** fetch override for tests. */
+    fetch?: typeof fetch;
+    /** Request timeout in ms. Default 5000. */
+    timeoutMs?: number;
+};
+export declare function createHttpTokenVerifier(options: HttpTokenVerifierOptions): TokenVerifier;
+export type StaticTokenVerifierOptions = {
+    /** Map of token string → claims to return. */
+    tokens: Record<string, TokenClaims>;
+};
+export declare function createStaticTokenVerifier(options: StaticTokenVerifierOptions): TokenVerifier;

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@claxedo/workspace-relay-protocol",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsx scripts/build.ts",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test src"
+  },
+  "devDependencies": {
+    "@tsconfig/node-lts": "^22.0.0",
+    "@types/bun": "catalog:",
+    "esbuild": "^0.25.0",
+    "tsx": "^4.0.0",
+    "typescript": "catalog:"
+  }
+}