@vhyxvoid/protocol 1.0.0

package/dist/canonical.d.ts

@@ -0,0 +1,28 @@
+export interface CanonicalParams {
+    method: string;
+    path: string;
+    query: string;
+    body: string;
+    requestId: string;
+    ts: number;
+}
+/**
+ * Build the canonical string that both sides sign/verify.
+ * Format: METHOD|PATH|QUERY|BODY_SHA256|REQUEST_ID|TIMESTAMP_MS
+ *
+ * All fields are always present (empty string if absent).
+ * Order is fixed — SDK and Hub must agree exactly.
+ */
+export declare function buildCanonical(params: CanonicalParams): string;
+/**
+ * Sign a canonical string with HMAC-SHA256.
+ * secretHash = HMAC-SHA256(rawSecret, SERVER_HMAC_PEPPER) — stored in DB.
+ * Agent signs using the same secretHash.
+ */
+export declare function signCanonical(canonical: string, secretHash: string): string;
+/**
+ * Timing-safe HMAC verification.
+ * Returns false if lengths differ (prevents length-extension attacks).
+ */
+export declare function verifyCanonical(canonical: string, signature: string, secretHash: string): boolean;
+//# sourceMappingURL=canonical.d.ts.map

package/dist/canonical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.d.ts","sourceRoot":"","sources":["../src/canonical.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAa9D;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAK3E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAUT"}

package/dist/canonical.js

@@ -0,0 +1,63 @@
+"use strict";
+// ─────────────────────────────────────────────────────────────────────────────
+// packages/protocol/src/canonical.ts
+// Canonical string builder — identical in Hub (verify) and SDK (sign).
+// Query string is included to prevent query-parameter injection attacks.
+// ─────────────────────────────────────────────────────────────────────────────
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCanonical = buildCanonical;
+exports.signCanonical = signCanonical;
+exports.verifyCanonical = verifyCanonical;
+const crypto_1 = __importDefault(require("crypto"));
+/**
+ * Build the canonical string that both sides sign/verify.
+ * Format: METHOD|PATH|QUERY|BODY_SHA256|REQUEST_ID|TIMESTAMP_MS
+ *
+ * All fields are always present (empty string if absent).
+ * Order is fixed — SDK and Hub must agree exactly.
+ */
+function buildCanonical(params) {
+    const bodyHash = params.body
+        ? crypto_1.default.createHash("sha256").update(params.body, "utf8").digest("hex")
+        : "";
+    return [
+        params.method.toUpperCase(),
+        params.path,
+        params.query,
+        bodyHash,
+        params.requestId,
+        params.ts.toString(),
+    ].join("|");
+}
+/**
+ * Sign a canonical string with HMAC-SHA256.
+ * secretHash = HMAC-SHA256(rawSecret, SERVER_HMAC_PEPPER) — stored in DB.
+ * Agent signs using the same secretHash.
+ */
+function signCanonical(canonical, secretHash) {
+    return crypto_1.default
+        .createHmac("sha256", secretHash)
+        .update(canonical)
+        .digest("hex");
+}
+/**
+ * Timing-safe HMAC verification.
+ * Returns false if lengths differ (prevents length-extension attacks).
+ */
+function verifyCanonical(canonical, signature, secretHash) {
+    try {
+        const expected = signCanonical(canonical, secretHash);
+        const a = Buffer.from(expected, "hex");
+        const b = Buffer.from(signature, "hex");
+        if (a.length !== b.length)
+            return false;
+        return crypto_1.default.timingSafeEqual(a, b);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=canonical.js.map

package/dist/canonical.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.js","sourceRoot":"","sources":["../src/canonical.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,qCAAqC;AACrC,uEAAuE;AACvE,yEAAyE;AACzE,gFAAgF;;;;;AAoBhF,wCAaC;AAOD,sCAKC;AAMD,0CAcC;AA/DD,oDAA4B;AAW5B;;;;;;GAMG;AACH,SAAgB,cAAc,CAAC,MAAuB;IACpD,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI;QAC1B,CAAC,CAAC,gBAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;QACvE,CAAC,CAAC,EAAE,CAAC;IAEP,OAAO;QACL,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE;QAC3B,MAAM,CAAC,IAAI;QACX,MAAM,CAAC,KAAK;QACZ,QAAQ;QACR,MAAM,CAAC,SAAS;QAChB,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE;KACrB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,SAAgB,aAAa,CAAC,SAAiB,EAAE,UAAkB;IACjE,OAAO,gBAAM;SACV,UAAU,CAAC,QAAQ,EAAE,UAAU,CAAC;SAChC,MAAM,CAAC,SAAS,CAAC;SACjB,MAAM,CAAC,KAAK,CAAC,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,SAAgB,eAAe,CAC7B,SAAiB,EACjB,SAAiB,EACjB,UAAkB;IAElB,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,aAAa,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;QACtD,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QACvC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;QACxC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;QACxC,OAAO,gBAAM,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/constants.d.ts

@@ -0,0 +1,40 @@
+export declare const PROTOCOL_VERSION: "1";
+export declare const TIMING: {
+    /** How long hub waits for agent response before timing out the SDK request */
+    readonly REQUEST_TIMEOUT_MS: 30000;
+    /** Buffer over REQUEST_TIMEOUT_MS for hub:pending Redis TTL */
+    readonly PENDING_TTL_MS: 32000;
+    /** Hub pings every N ms */
+    readonly HEARTBEAT_INTERVAL_MS: 15000;
+    /** Miss this many pings → agent evicted */
+    readonly MAX_MISSED_PINGS: 6;
+    /** Redis presence key TTL (must be > HEARTBEAT_INTERVAL_MS) */
+    readonly AGENT_PRESENCE_TTL_SEC: 25;
+    /** Agent reconnect: initial delay */
+    readonly RECONNECT_INITIAL_MS: 1000;
+    /** Agent reconnect: maximum delay cap */
+    readonly RECONNECT_MAX_MS: 300000;
+    /** Signature timestamp tolerance */
+    readonly SIGNATURE_WINDOW_MS: 60000;
+    /** MessageBatcher flush window */
+    readonly BATCH_WINDOW_MS: 50;
+    /** MessageBatcher max items before immediate flush */
+    readonly BATCH_MAX_SIZE: 100;
+    /** LocalAgentDiscovery timeout */
+    readonly LOCAL_DISCOVERY_TIMEOUT_MS: 50;
+};
+export declare const LIMITS: {
+    /** Max WS message size (10MB) */
+    readonly MAX_PAYLOAD_BYTES: number;
+    /** Port agent broadcasts for local discovery */
+    readonly LOCAL_AGENT_DISCOVERY_PORT: 4242;
+    /** Max retry attempts for queue items */
+    readonly QUEUE_MAX_ATTEMPTS_OUTBOUND: 10;
+    readonly QUEUE_MAX_ATTEMPTS_INBOUND: 5;
+};
+export declare const PLAN_AGENT_LIMITS: {
+    readonly FREE: 1;
+    readonly PRO: 5;
+    readonly ENTERPRISE: number;
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,gBAAgB,EAAG,GAAY,CAAC;AAE7C,eAAO,MAAM,MAAM;IACjB,8EAA8E;;IAE9E,+DAA+D;;IAE/D,2BAA2B;;IAE3B,2CAA2C;;IAE3C,+DAA+D;;IAE/D,qCAAqC;;IAErC,yCAAyC;;IAEzC,oCAAoC;;IAEpC,kCAAkC;;IAElC,sDAAsD;;IAEtD,kCAAkC;;CAE1B,CAAC;AAEX,eAAO,MAAM,MAAM;IACjB,iCAAiC;;IAEjC,gDAAgD;;IAEhD,yCAAyC;;;CAGjC,CAAC;AAEX,eAAO,MAAM,iBAAiB;;;;CAIpB,CAAC"}

package/dist/constants.js

@@ -0,0 +1,46 @@
+"use strict";
+// ─────────────────────────────────────────────────────────────────────────────
+// packages/protocol/src/constants.ts
+// ─────────────────────────────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLAN_AGENT_LIMITS = exports.LIMITS = exports.TIMING = exports.PROTOCOL_VERSION = void 0;
+exports.PROTOCOL_VERSION = "1";
+exports.TIMING = {
+    /** How long hub waits for agent response before timing out the SDK request */
+    REQUEST_TIMEOUT_MS: 30_000,
+    /** Buffer over REQUEST_TIMEOUT_MS for hub:pending Redis TTL */
+    PENDING_TTL_MS: 32_000,
+    /** Hub pings every N ms */
+    HEARTBEAT_INTERVAL_MS: 15_000,
+    /** Miss this many pings → agent evicted */
+    MAX_MISSED_PINGS: 6,
+    /** Redis presence key TTL (must be > HEARTBEAT_INTERVAL_MS) */
+    AGENT_PRESENCE_TTL_SEC: 25,
+    /** Agent reconnect: initial delay */
+    RECONNECT_INITIAL_MS: 1_000,
+    /** Agent reconnect: maximum delay cap */
+    RECONNECT_MAX_MS: 300_000,
+    /** Signature timestamp tolerance */
+    SIGNATURE_WINDOW_MS: 60_000,
+    /** MessageBatcher flush window */
+    BATCH_WINDOW_MS: 50,
+    /** MessageBatcher max items before immediate flush */
+    BATCH_MAX_SIZE: 100,
+    /** LocalAgentDiscovery timeout */
+    LOCAL_DISCOVERY_TIMEOUT_MS: 50,
+};
+exports.LIMITS = {
+    /** Max WS message size (10MB) */
+    MAX_PAYLOAD_BYTES: 10 * 1024 * 1024,
+    /** Port agent broadcasts for local discovery */
+    LOCAL_AGENT_DISCOVERY_PORT: 4242,
+    /** Max retry attempts for queue items */
+    QUEUE_MAX_ATTEMPTS_OUTBOUND: 10,
+    QUEUE_MAX_ATTEMPTS_INBOUND: 5,
+};
+exports.PLAN_AGENT_LIMITS = {
+    FREE: 1,
+    PRO: 5,
+    ENTERPRISE: Infinity,
+};
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,qCAAqC;AACrC,gFAAgF;;;AAEnE,QAAA,gBAAgB,GAAG,GAAY,CAAC;AAEhC,QAAA,MAAM,GAAG;IACpB,8EAA8E;IAC9E,kBAAkB,EAAE,MAAM;IAC1B,+DAA+D;IAC/D,cAAc,EAAE,MAAM;IACtB,2BAA2B;IAC3B,qBAAqB,EAAE,MAAM;IAC7B,2CAA2C;IAC3C,gBAAgB,EAAE,CAAC;IACnB,+DAA+D;IAC/D,sBAAsB,EAAE,EAAE;IAC1B,qCAAqC;IACrC,oBAAoB,EAAE,KAAK;IAC3B,yCAAyC;IACzC,gBAAgB,EAAE,OAAO;IACzB,oCAAoC;IACpC,mBAAmB,EAAE,MAAM;IAC3B,kCAAkC;IAClC,eAAe,EAAE,EAAE;IACnB,sDAAsD;IACtD,cAAc,EAAE,GAAG;IACnB,kCAAkC;IAClC,0BAA0B,EAAE,EAAE;CACtB,CAAC;AAEE,QAAA,MAAM,GAAG;IACpB,iCAAiC;IACjC,iBAAiB,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;IACnC,gDAAgD;IAChD,0BAA0B,EAAE,IAAI;IAChC,yCAAyC;IACzC,2BAA2B,EAAE,EAAE;IAC/B,0BAA0B,EAAE,CAAC;CACrB,CAAC;AAEE,QAAA,iBAAiB,GAAG;IAC/B,IAAI,EAAE,CAAC;IACP,GAAG,EAAE,CAAC;IACN,UAAU,EAAE,QAAQ;CACZ,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,11 @@
+export type HubErrorCode = "AUTH_FAILED" | "KEY_REVOKED" | "KEY_EXPIRED" | "SCOPE_MISSING" | "VERSION_UNSUPPORTED" | "RATE_LIMITED" | "AGENT_LIMIT_REACHED" | "INVALID_MESSAGE" | "INTERNAL_ERROR";
+export type TunnelErrorCode = "AGENT_NOT_FOUND" | "AGENT_DISCONNECTED" | "AGENT_TIMEOUT" | "BACKEND_UNAVAILABLE" | "BACKEND_ERROR" | "PAYLOAD_TOO_LARGE" | "FORBIDDEN_SCOPE" | "SEND_FAILED";
+/** WS close codes (4000-4999 = application level) */
+export declare const WS_CLOSE_CODES: {
+    readonly AUTH_FAILED: 4001;
+    readonly VERSION_UNSUPPORTED: 4002;
+    readonly AGENT_LIMIT_REACHED: 4003;
+    readonly RATE_LIMITED: 4004;
+    readonly INTERNAL_ERROR: 4999;
+};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,YAAY,GACpB,aAAa,GACb,aAAa,GACb,aAAa,GACb,eAAe,GACf,qBAAqB,GACrB,cAAc,GACd,qBAAqB,GACrB,iBAAiB,GACjB,gBAAgB,CAAC;AAErB,MAAM,MAAM,eAAe,GACvB,iBAAiB,GACjB,oBAAoB,GACpB,eAAe,GACf,qBAAqB,GACrB,eAAe,GACf,mBAAmB,GACnB,iBAAiB,GACjB,aAAa,CAAC;AAElB,qDAAqD;AACrD,eAAO,MAAM,cAAc;;;;;;CAMjB,CAAC"}

package/dist/errors.js

@@ -0,0 +1,15 @@
+"use strict";
+// ─────────────────────────────────────────────────────────────────────────────
+// packages/protocol/src/errors.ts
+// ─────────────────────────────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WS_CLOSE_CODES = void 0;
+/** WS close codes (4000-4999 = application level) */
+exports.WS_CLOSE_CODES = {
+    AUTH_FAILED: 4001,
+    VERSION_UNSUPPORTED: 4002,
+    AGENT_LIMIT_REACHED: 4003,
+    RATE_LIMITED: 4004,
+    INTERNAL_ERROR: 4999,
+};
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,kCAAkC;AAClC,gFAAgF;;;AAuBhF,qDAAqD;AACxC,QAAA,cAAc,GAAG;IAC5B,WAAW,EAAE,IAAI;IACjB,mBAAmB,EAAE,IAAI;IACzB,mBAAmB,EAAE,IAAI;IACzB,YAAY,EAAE,IAAI;IAClB,cAAc,EAAE,IAAI;CACZ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./messages";
+export * from "./canonical";
+export * from "./serializer";
+export * from "./constants";
+export * from "./errors";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,28 @@
+"use strict";
+// packages/protocol/src/index.ts
+// Single source of truth for the entire tunnel protocol.
+// Imported by Hub, Agent, and SDK. Never duplicated.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./messages"), exports);
+__exportStar(require("./canonical"), exports);
+__exportStar(require("./serializer"), exports);
+__exportStar(require("./constants"), exports);
+__exportStar(require("./errors"), exports);
+// // Re-export for consumers that need the constant in canonical.ts
+// import { PROTOCOL_VERSION } from "./constants";
+// import type { HubErrorCode } from "./errors";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,iCAAiC;AACjC,yDAAyD;AACzD,qDAAqD;;;;;;;;;;;;;;;;AAErD,6CAA2B;AAC3B,8CAA4B;AAC5B,+CAA6B;AAC7B,8CAA4B;AAC5B,2CAAyB;AAEzB,oEAAoE;AACpE,kDAAkD;AAClD,gDAAgD"}

package/dist/messages.d.ts

@@ -0,0 +1,146 @@
+import type { HubErrorCode, TunnelErrorCode } from "./errors";
+export interface AgentRegisterMsg {
+    v: "1";
+    type: "agent:register";
+    keyId: string;
+    label: string;
+    rawSecret: string;
+    agentVersion: string;
+}
+export interface AgentPongMsg {
+    v: "1";
+    type: "agent:pong";
+    agentId: string;
+    ts: number;
+}
+export interface TunnelResponseMsg {
+    v: "1";
+    type: "tunnel:response";
+    requestId: string;
+    status: number;
+    headers: Record<string, string>;
+    body: string | null;
+    durationMs: number;
+}
+export interface TunnelAgentErrorMsg {
+    v: "1";
+    type: "tunnel:agent-error";
+    requestId: string;
+    code: TunnelErrorCode;
+    message: string;
+}
+export interface AgentBatchMsg {
+    v: "1";
+    type: "agent:batch";
+    messages: Array<TunnelResponseMsg | TunnelAgentErrorMsg | AgentPongMsg>;
+}
+export interface HubRegisteredMsg {
+    v: "1";
+    type: "hub:registered";
+    agentId: string;
+    accountId: string;
+    replayPending: boolean;
+    tunnelUrl?: string;
+}
+export interface HubPingMsg {
+    v: "1";
+    type: "hub:ping";
+    ts: number;
+}
+export interface TunnelForwardMsg {
+    v: "1";
+    type: "tunnel:forward";
+    requestId: string;
+    method: string;
+    path: string;
+    query: string;
+    headers: Record<string, string>;
+    body: string | null;
+    timeoutMs: number;
+}
+export interface HubErrorMsg {
+    v: "1";
+    type: "hub:error";
+    code: HubErrorCode;
+    message: string;
+    requestId?: string;
+    fatal: boolean;
+}
+export interface SdkRegisterMsg {
+    v: "1";
+    type: "sdk:register";
+    keyId: string;
+    requestId: string;
+    ts: number;
+    signature: string;
+}
+export interface SdkRequestMsg {
+    v: "1";
+    type: "sdk:request";
+    keyId: string;
+    requestId: string;
+    ts: number;
+    signature: string;
+    label?: string;
+    method: string;
+    path: string;
+    query: string;
+    headers: Record<string, string>;
+    body: string | null;
+}
+export interface SdkRegisteredMsg {
+    v: "1";
+    type: "sdk:registered";
+    sessionId: string;
+}
+export interface SdkResponseMsg {
+    v: "1";
+    type: "sdk:response";
+    requestId: string;
+    status: number;
+    headers: Record<string, string>;
+    body: string | null;
+    durationMs: number;
+}
+export interface SdkErrorMsg {
+    v: "1";
+    type: "sdk:error";
+    requestId: string;
+    code: TunnelErrorCode | HubErrorCode;
+    message: string;
+    retryable: boolean;
+}
+export type AgentToHubMsg = AgentRegisterMsg | AgentPongMsg | TunnelResponseMsg | TunnelAgentErrorMsg | AgentBatchMsg | TunnelWsMessageMsg | TunnelWsCloseMsg;
+export type HubToAgentMsg = HubRegisteredMsg | HubPingMsg | TunnelForwardMsg | HubErrorMsg | TunnelWsOpenMsg | TunnelWsMessageMsg | TunnelWsCloseMsg;
+export type SdkToHubMsg = SdkRegisterMsg | SdkRequestMsg;
+export type HubToSdkMsg = SdkRegisteredMsg | SdkResponseMsg | SdkErrorMsg;
+export type AnyHubMsg = AgentToHubMsg | HubToAgentMsg | SdkToHubMsg | HubToSdkMsg | TunnelWsErrorMsg;
+export interface TunnelWsOpenMsg {
+    v: "1";
+    type: "tunnel:ws:open";
+    connectionId: string;
+    path: string;
+    query: string;
+    headers: Record<string, string>;
+}
+export interface TunnelWsMessageMsg {
+    v: "1";
+    type: "tunnel:ws:message";
+    connectionId: string;
+    data: string;
+    isBinary: boolean;
+}
+export interface TunnelWsCloseMsg {
+    v: "1";
+    type: "tunnel:ws:close";
+    connectionId: string;
+    code: number;
+    reason: string;
+}
+export interface TunnelWsErrorMsg {
+    v: "1";
+    type: "tunnel:ws:error";
+    connectionId: string;
+    message: string;
+}
+//# sourceMappingURL=messages.d.ts.map

package/dist/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"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"}

package/dist/messages.js

@@ -0,0 +1,8 @@
+"use strict";
+// ─────────────────────────────────────────────────────────────────────────────
+// packages/protocol/src/messages.ts
+// All messages as strict discriminated unions.
+// Both Hub and Agent import these — no duplication.
+// ─────────────────────────────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=messages.js.map

package/dist/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,oCAAoC;AACpC,+CAA+C;AAC/C,oDAAoD;AACpD,gFAAgF"}

package/dist/serializer.d.ts

@@ -0,0 +1,14 @@
+import { HubErrorCode } from "./errors";
+import { AnyHubMsg } from "./messages";
+export declare function serialize(msg: AnyHubMsg): string;
+export declare function deserialize<T = AnyHubMsg>(data: Buffer | string): T;
+/**
+ * Parse and validate that a message has required base fields.
+ * Throws a typed error on malformed input so routers can reject cleanly.
+ */
+export declare function parseMessage(data: Buffer | string): AnyHubMsg;
+export declare class ProtocolError extends Error {
+    readonly code: HubErrorCode;
+    constructor(code: HubErrorCode, message: string);
+}
+//# sourceMappingURL=serializer.d.ts.map

package/dist/serializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,wBAAgB,SAAS,CAAC,GAAG,EAAE,SAAS,GAAG,MAAM,CAEhD;AAED,wBAAgB,WAAW,CAAC,CAAC,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC,CAGnE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAyB7D;AAED,qBAAa,aAAc,SAAQ,KAAK;aAEpB,IAAI,EAAE,YAAY;gBAAlB,IAAI,EAAE,YAAY,EAClC,OAAO,EAAE,MAAM;CAKlB"}

package/dist/serializer.js

@@ -0,0 +1,53 @@
+"use strict";
+// ─────────────────────────────────────────────────────────────────────────────
+// packages/protocol/src/serializer.ts
+// Single abstraction over serialization format.
+// Phase 1: JSON (debug-friendly).
+// Phase 2: swap to msgpackr here — zero other changes.
+// ─────────────────────────────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProtocolError = void 0;
+exports.serialize = serialize;
+exports.deserialize = deserialize;
+exports.parseMessage = parseMessage;
+const constants_1 = require("./constants");
+function serialize(msg) {
+    return JSON.stringify(msg);
+}
+function deserialize(data) {
+    const str = Buffer.isBuffer(data) ? data.toString("utf8") : data;
+    return JSON.parse(str);
+}
+/**
+ * Parse and validate that a message has required base fields.
+ * Throws a typed error on malformed input so routers can reject cleanly.
+ */
+function parseMessage(data) {
+    let msg;
+    try {
+        msg = deserialize(data);
+    }
+    catch {
+        throw new ProtocolError("INVALID_MESSAGE", "Message is not valid JSON");
+    }
+    if (!msg || typeof msg !== "object") {
+        throw new ProtocolError("INVALID_MESSAGE", "Message must be a JSON object");
+    }
+    if (msg.v !== constants_1.PROTOCOL_VERSION) {
+        throw new ProtocolError("VERSION_UNSUPPORTED", `Protocol version "${msg.v}" is not supported. Expected "${constants_1.PROTOCOL_VERSION}".`);
+    }
+    if (!msg.type || typeof msg.type !== "string") {
+        throw new ProtocolError("INVALID_MESSAGE", 'Message missing required "type" field');
+    }
+    return msg;
+}
+class ProtocolError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ProtocolError";
+    }
+}
+exports.ProtocolError = ProtocolError;
+//# sourceMappingURL=serializer.js.map

package/dist/serializer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serializer.js","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,sCAAsC;AACtC,gDAAgD;AAChD,kCAAkC;AAClC,uDAAuD;AACvD,gFAAgF;;;AAMhF,8BAEC;AAED,kCAGC;AAMD,oCAyBC;AA1CD,2CAA+C;AAI/C,SAAgB,SAAS,CAAC,GAAc;IACtC,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;AAC7B,CAAC;AAED,SAAgB,WAAW,CAAgB,IAAqB;IAC9D,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACjE,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAM,CAAC;AAC9B,CAAC;AAED;;;GAGG;AACH,SAAgB,YAAY,CAAC,IAAqB;IAChD,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,aAAa,CAAC,iBAAiB,EAAE,2BAA2B,CAAC,CAAC;IAC1E,CAAC;IAED,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QACpC,MAAM,IAAI,aAAa,CAAC,iBAAiB,EAAE,+BAA+B,CAAC,CAAC;IAC9E,CAAC;IACD,IAAI,GAAG,CAAC,CAAC,KAAK,4BAAgB,EAAE,CAAC;QAC/B,MAAM,IAAI,aAAa,CACrB,qBAAqB,EACrB,qBAAqB,GAAG,CAAC,CAAC,iCAAiC,4BAAgB,IAAI,CAChF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC9C,MAAM,IAAI,aAAa,CACrB,iBAAiB,EACjB,uCAAuC,CACxC,CAAC;IACJ,CAAC;IAED,OAAO,GAAgB,CAAC;AAC1B,CAAC;AAED,MAAa,aAAc,SAAQ,KAAK;IAEpB;IADlB,YACkB,IAAkB,EAClC,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,SAAI,GAAJ,IAAI,CAAc;QAIlC,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AARD,sCAQC"}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@vhyxvoid/protocol",
+  "version": "1.0.0",
+  "description": "Shared WebSocket message types and canonical string builder for the tunnel system",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "typescript": "^5.4.0"
+  }
+}