@claxedo/workspace-relay-protocol 0.5.0 → 0.5.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Claxedo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -5,15 +5,61 @@ traffic. This package intentionally has no Hono, Bun, or server dependency so
 workspace hosts and non-Node clients can validate tunnel frames without pulling
 in the relay implementation.
 
+## Install
+
+```sh
+npm install @claxedo/workspace-relay-protocol
+```
+
+## Quickstart
+
+```ts
+import { createStaticTokenVerifier, isTunnelMessage, validateTunnelMessage } from "@claxedo/workspace-relay-protocol"
+
+// Validate an inbound tunnel frame before acting on it.
+const result = validateTunnelMessage(JSON.parse(rawFrame))
+if (!result.ok) {
+  throw new Error(`invalid tunnel frame: ${result.reason}`)
+}
+// result.message is a narrowed TunnelMessage here.
+
+// Or use the boolean type guard when you just need a filter.
+const frames = incoming.filter(isTunnelMessage)
+
+// A fixed token table for tests and single-tenant self-hosted deployments.
+const verifier = createStaticTokenVerifier({
+  tokens: {
+    "test-token": {
+      subject: "workspace-abc",
+      scopes: ["relay:connect"],
+      claims: {
+        iss: "claxedo-test",
+        aud: "workspace-relay",
+        sub: "workspace-abc",
+        workspace_id: "workspace-abc",
+        host_id: "host-1",
+        exp: Math.floor(Date.now() / 1000) + 3600,
+        iat: Math.floor(Date.now() / 1000),
+        jti: "jti-1",
+      },
+    },
+  },
+})
+const claims = await verifier.verify("test-token")
+```
+
 ## Public Surface
 
 | Export | Stability | Purpose |
 | --- | --- | --- |
 | `TUNNEL_PROTOCOL_VERSION` | Stable | Current tunnel protocol version. |
-| `TunnelMessage` and message subtypes | Stable | Discriminated union for HTTP, WebSocket, heartbeat, flow-control, and error frames. |
+| `TunnelMessage` and message subtypes | Stable | Discriminated union for HTTP, WebSocket, heartbeat, host-registration, flow-control, and error frames. |
+| `TunnelHostRegistrationUpdate` / `"host.registration.update"` | Stable | Frame a host sends to update the set of workspace IDs it serves and its auth token. |
 | `validateTunnelMessage`, `isTunnelMessage` | Stable | Runtime validation for protocol, message type, and per-message payload shape. |
-| `makeTunnelPong` | Stable | Helper for heartbeat replies. |
+| `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. |
 | `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

@@ -14,6 +14,12 @@ export type TunnelPong = {
     sent_at: number;
     received_at: number;
 };
+export type TunnelHostRegistrationUpdate = {
+    type: "host.registration.update";
+    protocol: typeof TUNNEL_PROTOCOL_VERSION;
+    workspace_ids: string[];
+    token: string;
+};
 export type TunnelHttpRequest = {
     type: "http.request";
     protocol: typeof TUNNEL_PROTOCOL_VERSION;
@@ -80,7 +86,7 @@ export type TunnelError = {
     code: string;
     message: string;
 };
-export type TunnelMessage = TunnelPing | TunnelPong | TunnelHttpRequest | TunnelHttpResponseStart | TunnelHttpResponseChunk | TunnelHttpResponseEnd | TunnelHttpResponseFlow | TunnelWsOpen | TunnelWsFrame | TunnelWsClose | TunnelError;
+export type TunnelMessage = TunnelPing | TunnelPong | TunnelHostRegistrationUpdate | TunnelHttpRequest | TunnelHttpResponseStart | TunnelHttpResponseChunk | TunnelHttpResponseEnd | TunnelHttpResponseFlow | TunnelWsOpen | TunnelWsFrame | TunnelWsClose | TunnelError;
 export type TunnelMessageValidation = {
     ok: true;
     message: TunnelMessage;
@@ -97,3 +103,4 @@ export type TunnelMessageValidation = {
 export declare function validateTunnelMessage(input: unknown): TunnelMessageValidation;
 export declare function isTunnelMessage(input: unknown): input is TunnelMessage;
 export declare function makeTunnelPong(input: TunnelPing, receivedAt?: number): TunnelPong;
+export declare function makeTunnelPing(sentAt?: number, id?: string): TunnelPing;