@claxedo/workspace-relay-protocol

@claxedo/workspace-relay-protocol holds the shared wire types and token-verifier contracts for Claxedo workspace relay traffic. It intentionally has no Hono, Bun, or server dependency, so workspace hosts and non-Node clients can validate tunnel frames and plug in custom token verification without pulling in the relay implementation.

Install

npm install @claxedo/workspace-relay-protocol

pnpm add @claxedo/workspace-relay-protocol

bun add @claxedo/workspace-relay-protocol

Quickstart

Validate an incoming tunnel frame and build a heartbeat reply:

import {
  TUNNEL_PROTOCOL_VERSION,
  validateTunnelMessage,
  makeTunnelPong,
} from "@claxedo/workspace-relay-protocol"

const result = validateTunnelMessage(incoming)
if (result.ok && result.message.type === "ping") {
  send(makeTunnelPong(result.message))
}

For custom relay/runtime auth, implement the small TokenVerifier interface (verify(token) only) or use a shipped reference implementation:

import { createStaticTokenVerifier } from "@claxedo/workspace-relay-protocol"

const verifier = createStaticTokenVerifier({
  tokens: {
    "tok-tenant-1": {
      subject: "u1",
      scopes: ["workspace:write"],
      // The consuming boundary re-validates these claims against its own
      // contract (e.g. RuntimeAccessVerifierClaims or RelayHostVerifierClaims)
      // — see the relay and workspace-runtime pages for complete examples.
      claims: {},
    },
  },
})

Key capabilities

Wire types — TunnelMessage discriminated union (HTTP, WebSocket, heartbeat, flow-control, error frames) plus TUNNEL_PROTOCOL_VERSION.
Validation — validateTunnelMessage / isTunnelMessage reject non-objects, protocol mismatches, unknown types, missing fields, malformed headers, bad base64, and invalid status/close codes (extra fields allowed for forward compatibility).
Token verifiers — TokenVerifier interface plus createClerkTokenVerifier, createHttpTokenVerifier, and createStaticTokenVerifier.

Stability

Per the README surface table: Stable for wire types, validation helpers, makeTunnelPong, and TokenVerifier; Public beta for createClerkTokenVerifier and createHttpTokenVerifier; Test/single-tenant only for createStaticTokenVerifier. The current wire version is 1; breaking message changes require a new TUNNEL_PROTOCOL_VERSION.

Full API

See the README on GitHub for the full surface table, validation rules, verifier-endpoint contract, and compatibility policy.