@vincentt-xr/harness 1.0.0 → 1.2.0

package/dist/tunnel/forwardTarget.js

@@ -0,0 +1,174 @@
+/**
+ * The forward target — what the tunnel client is allowed to reach (2.15.4).
+ *
+ * READ THIS BEFORE CHANGING ANYTHING HERE.
+ *
+ * THIS FILE IS A DEFENSE, NOT A SECURITY CONTROL. Every rule in it executes on
+ * the CREATOR'S MACHINE, in software the creator can replace. It stops the
+ * ACCIDENT — a viewer-controlled path reaching a second local service — and it
+ * stops NOTHING a hostile creator wants to do. The controls that bind a hostile
+ * creator are at the edge: the abuse budget and the header set.
+ *
+ * The earlier draft's argument that "one outbound connection, nothing dials into
+ * the laptop" made this safe was about CONNECTION DIRECTION, which is not an
+ * authorization boundary for what the laptop does with a request once it
+ * arrives.
+ */
+import { isIP } from "node:net";
+import { lookup } from "node:dns/promises";
+export class ForwardTargetError extends Error {
+    code;
+    constructor(code) {
+        // The code and nothing else. A rejected path in an error message would put
+        // a viewer-controlled string into the creator's terminal.
+        super(code);
+        this.code = code;
+        this.name = "ForwardTargetError";
+    }
+}
+/**
+ * LOOPBACK is the only address family the client will connect to. It is checked
+ * at START and RE-CHECKED AT CONNECT TIME, so a DNS rebind cannot move the
+ * target between the two.
+ */
+function isLoopback(addr) {
+    if (isIP(addr) === 4)
+        return addr.startsWith("127.");
+    if (isIP(addr) === 6)
+        return addr === "::1" || addr === "::ffff:127.0.0.1";
+    return false;
+}
+const defaultResolver = async (host) => (await lookup(host)).address;
+/**
+ * resolveForwardTarget captures the ONE configured target at
+ * `vincentt preview` start, from the creator's own flag or config — NEVER from
+ * a request.
+ */
+export async function resolveForwardTarget(host, port, resolve = defaultResolver) {
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new ForwardTargetError("invalid_target");
+    }
+    const address = isIP(host) ? host : await resolve(host);
+    if (!isLoopback(address))
+        throw new ForwardTargetError("non_loopback_target");
+    return { host, port, address };
+}
+/**
+ * assertStillLoopback is the CONNECT-TIME re-check. Resolving once at start and
+ * trusting it forever is exactly the window a DNS rebind uses.
+ */
+export async function assertStillLoopback(t, resolve = defaultResolver) {
+    // An IP literal cannot be rebound, so it needs no second lookup — which also
+    // keeps the common case (127.0.0.1) off the resolver entirely.
+    const address = isIP(t.host) ? t.host : await resolve(t.host);
+    if (!isLoopback(address))
+        throw new ForwardTargetError("non_loopback_target");
+}
+/**
+ * normalizeRequestTarget applies rules 2 and 3.
+ *
+ * Rule 2: an ABSOLUTE-FORM target (`GET http://... HTTP/1.1`) is refused
+ * outright. That is the shape that turns a forwarding proxy into an open relay.
+ *
+ * Rule 3: NORMALIZE, THEN CHECK — never check-then-normalize. Percent-encoded
+ * traversal (`%2e%2e%2f`) passes a naive `includes('..')` check and then decodes
+ * into one, so the decode has to happen FIRST, and it has to happen repeatedly
+ * because double-encoding (`%252e`) decodes into `%2e`.
+ */
+export function normalizeRequestTarget(target) {
+    if (target === "" || !target.startsWith("/")) {
+        // Anything not origin-form: absolute-form, authority-form, asterisk-form.
+        throw new ForwardTargetError("absolute_form_target");
+    }
+    // A scheme-relative target (`//evil.example/x`) is origin-form by the leading
+    // slash but is treated as a network path by many URL parsers.
+    if (target.startsWith("//"))
+        throw new ForwardTargetError("absolute_form_target");
+    const [rawPath = "", ...rest] = target.split("?");
+    const query = rest.length > 0 ? rest.join("?") : undefined;
+    // Decode repeatedly until it stops changing, so a double-encoded traversal
+    // cannot survive by decoding one level less than we check.
+    let decoded = rawPath;
+    for (let i = 0; i < 4; i++) {
+        let next;
+        try {
+            next = decodeURIComponent(decoded);
+        }
+        catch {
+            // A malformed escape sequence. Refuse rather than guess.
+            throw new ForwardTargetError("path_traversal");
+        }
+        if (next === decoded)
+            break;
+        decoded = next;
+    }
+    // Backslash is a path separator on Windows and is normalized by some servers.
+    const probe = decoded.replace(/\\/g, "/");
+    for (const segment of probe.split("/")) {
+        if (segment === "..")
+            throw new ForwardTargetError("path_traversal");
+    }
+    // NUL and control bytes in a path are a request-smuggling primitive.
+    // eslint-disable-next-line no-control-regex
+    if (/[\x00-\x1f\x7f]/.test(probe))
+        throw new ForwardTargetError("path_traversal");
+    // The ORIGINAL (still-encoded) path is what is forwarded: re-encoding could
+    // change the creator's app's routing. Only the CHECK used the decoded form.
+    return query === undefined ? rawPath : `${rawPath}?${query}`;
+}
+/**
+ * VIEWER_ROUTING_HEADERS are DROPPED and replaced with the client's own
+ * (rule 4). A Host-honoring proxy is a routing primitive, and the forwarded-for
+ * family would carry the viewer's IP onto the creator's machine — a viewer
+ * identity the platform has no business handing over.
+ *
+ * The edge already drops these; dropping them again here is deliberate defense
+ * in depth, because this list is the one that runs closest to the local server.
+ */
+const VIEWER_ROUTING_HEADERS = new Set([
+    "host",
+    "forwarded",
+    "x-forwarded-for",
+    "x-forwarded-host",
+    "x-forwarded-proto",
+    "x-forwarded-port",
+    "x-forwarded-server",
+    "x-real-ip",
+]);
+const HOP_BY_HOP = new Set([
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+]);
+/**
+ * sanitizeHeaders drops the viewer's routing headers and every hop-by-hop
+ * header, and substitutes the client's own Host.
+ */
+export function sanitizeHeaders(headers, target) {
+    const out = [];
+    for (const [name, value] of headers) {
+        const lower = name.toLowerCase();
+        if (VIEWER_ROUTING_HEADERS.has(lower))
+            continue;
+        if (lower.startsWith("x-forwarded-"))
+            continue;
+        if (HOP_BY_HOP.has(lower))
+            continue;
+        out.push([name, value]);
+    }
+    // ITS OWN Host, never the viewer's.
+    out.push(["host", `${target.host}:${target.port}`]);
+    return out;
+}
+/**
+ * FOLLOW_REDIRECTS is false and there is no option to change it (rule 6). The
+ * BROWSER follows a redirect, on the viewer's own origin, where the viewer's
+ * own security context applies. A proxy that followed one on the creator's
+ * behalf would resolve a Location against the LOCAL machine.
+ */
+export const FOLLOW_REDIRECTS = false;

package/dist/tunnel/frame.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The tunnel protocol's Node half.
+ *
+ * This is the SECOND implementation of one binary protocol, in a second
+ * language — the highest-risk contract in the product to date. Two green
+ * per-language suites do not prove a contract, so every limit and every
+ * refusal here is pinned against a SHARED CHECKED-IN FIXTURE that neither
+ * implementation generates (`fixtures/`), and the malformed fixture's row count
+ * is asserted in both languages: a row present in one runner and absent in the
+ * other must FAIL.
+ *
+ * A Go/Node divergence on what to REFUSE is exactly how one implementation
+ * becomes a bypass for the other's limits.
+ *
+ * As on the Go side, DATA IS OPAQUE. Nothing in this file reads a DATA payload,
+ * branches on it, or keeps it.
+ */
+export declare enum FrameType {
+    /** edge->client. payload: CBOR {viewerLabel, method, path, headers, upgrade?} */
+    OPEN = 1,
+    /** both. payload: OPAQUE bytes. Never parsed. */
+    DATA = 2,
+    /** both. half-close a stream (or, with a u24 payload, a credit replenishment) */
+    END = 3,
+    /** both. payload: u8 reason */
+    RESET = 4,
+    /** client->edge. payload: CBOR {status, headers} */
+    HEAD = 5,
+    /** both, streamId MUST be 0 */
+    PING = 16,
+    PONG = 17,
+    /** edge->client, streamId MUST be 0 */
+    CONTROL = 18
+}
+export declare enum ResetReason {
+    PROTOCOL_ERROR = 1,
+    STREAM_CLOSED = 2,
+    REFUSED = 3,
+    IDLE = 4,
+    SESSION_ENDED = 5,
+    UNKNOWN = 255
+}
+/**
+ * MAX_FRAME_LEN is checked against the HEADER, before any allocation. The
+ * `length` field is u24 — 16 MiB of attacker-controlled allocation per frame if
+ * a decoder does `Buffer.alloc(length)` before dispatch. It equals the initial
+ * credit window so a single frame can never exceed a stream's credit.
+ */
+export declare const MAX_FRAME_LEN: number;
+/** The ONE decode path: OPEN/HEAD CBOR control payloads. Never DATA. */
+export declare const MAX_OPEN_PAYLOAD: number;
+export declare const FRAME_HEADER_LEN = 8;
+export declare const MAX_HEADERS = 64;
+export declare const MAX_HEADER_BYTES: number;
+export declare const MAX_PATH_LEN: number;
+export declare const MAX_CBOR_DEPTH = 4;
+export declare const MAX_CONCURRENT_STREAMS = 256;
+export declare const INITIAL_CREDIT: number;
+export declare const RELAY_BUF_SIZE: number;
+export declare const IDLE_STREAM_TIMEOUT_MS = 60000;
+export declare const TUNNEL_PING_INTERVAL_MS = 15000;
+export declare const TUNNEL_PING_TIMEOUT_MS = 45000;
+/** Protocol errors. They are for the CLIENT's own log, never for a wire body. */
+export declare class ProtocolError extends Error {
+    readonly code: ProtocolErrorCode;
+    readonly fatal: boolean;
+    /**
+     * `fatal` is the 2.15.3 behavior table expressed ONCE, so the Go edge and
+     * this client cannot drift on which violations close the tunnel and which
+     * only reset a stream.
+     */
+    constructor(code: ProtocolErrorCode, fatal: boolean);
+}
+export type ProtocolErrorCode = "frame_too_large" | "unknown_frame_type" | "even_stream_id" | "zero_stream_id" | "nonzero_stream_id" | "short_payload" | "open_payload_too_large" | "cbor_malformed" | "cbor_depth" | "cbor_headers" | "cbor_header_bytes" | "cbor_path_len" | "cbor_status" | "cbor_viewer";
+export interface FrameHeader {
+    type: FrameType;
+    streamId: number;
+    length: number;
+}
+export interface Frame extends FrameHeader {
+    payload: Uint8Array;
+}
+/**
+ * validateFrameShape is the single place the 2.15.2 invariants live, shared by
+ * the encoder and the decoder so the two cannot disagree about what is legal.
+ *
+ * `fromEdge` selects the parity rule: a frame arriving FROM the edge may carry
+ * any id, but a frame this client WRITES must carry an odd one, because the
+ * edge assigns odd ids and the client never opens a stream. There is no path
+ * from the platform into this machine that this machine did not open.
+ */
+export declare function validateFrameShape(type: number, streamId: number, length: number, fromEdge: boolean): void;
+/** encodeHeader writes the 8-byte header: type u8 | streamId u32 | length u24. */
+export declare function encodeHeader(type: FrameType, streamId: number, length: number): Uint8Array;
+/** encodeFrame serializes one whole frame. */
+export declare function encodeFrame(type: FrameType, streamId: number, payload?: Uint8Array): Uint8Array;
+/**
+ * decodeHeader reads and VALIDATES the header. Every limit the declared length
+ * can trip is checked here — this is the "before the byte that triggers them
+ * can allocate" boundary.
+ */
+export declare function decodeHeader(b: Uint8Array, fromEdge: boolean): FrameHeader;
+/**
+ * FrameDecoder is a streaming demultiplexer over a byte stream.
+ *
+ * It NEVER sizes a buffer from a declared length before that length has passed
+ * decodeHeader — the accumulator only ever grows by bytes that actually
+ * arrived, so a frame declaring 16 MiB costs a comparison, not 16 MiB.
+ */
+export declare class FrameDecoder {
+    private readonly fromEdge;
+    private buf;
+    private header;
+    constructor(fromEdge: boolean);
+    /** push appends bytes and returns every complete frame they produced. */
+    push(chunk: Uint8Array): Frame[];
+    /**
+     * end reports whether the stream closed mid-frame. A declared length longer
+     * than the bytes that arrived is a violation, and THE PARTIAL IS DROPPED —
+     * never returned, never logged.
+     */
+    end(): void;
+}
+/** encodeCredit/decodeCredit carry a u24 byte count on an END frame. */
+export declare function encodeCredit(n: number): Uint8Array;
+export declare function decodeCredit(b: Uint8Array): number;

package/dist/tunnel/frame.js

@@ -0,0 +1,244 @@
+/**
+ * The tunnel protocol's Node half.
+ *
+ * This is the SECOND implementation of one binary protocol, in a second
+ * language — the highest-risk contract in the product to date. Two green
+ * per-language suites do not prove a contract, so every limit and every
+ * refusal here is pinned against a SHARED CHECKED-IN FIXTURE that neither
+ * implementation generates (`fixtures/`), and the malformed fixture's row count
+ * is asserted in both languages: a row present in one runner and absent in the
+ * other must FAIL.
+ *
+ * A Go/Node divergence on what to REFUSE is exactly how one implementation
+ * becomes a bypass for the other's limits.
+ *
+ * As on the Go side, DATA IS OPAQUE. Nothing in this file reads a DATA payload,
+ * branches on it, or keeps it.
+ */
+export var FrameType;
+(function (FrameType) {
+    /** edge->client. payload: CBOR {viewerLabel, method, path, headers, upgrade?} */
+    FrameType[FrameType["OPEN"] = 1] = "OPEN";
+    /** both. payload: OPAQUE bytes. Never parsed. */
+    FrameType[FrameType["DATA"] = 2] = "DATA";
+    /** both. half-close a stream (or, with a u24 payload, a credit replenishment) */
+    FrameType[FrameType["END"] = 3] = "END";
+    /** both. payload: u8 reason */
+    FrameType[FrameType["RESET"] = 4] = "RESET";
+    /** client->edge. payload: CBOR {status, headers} */
+    FrameType[FrameType["HEAD"] = 5] = "HEAD";
+    /** both, streamId MUST be 0 */
+    FrameType[FrameType["PING"] = 16] = "PING";
+    FrameType[FrameType["PONG"] = 17] = "PONG";
+    /** edge->client, streamId MUST be 0 */
+    FrameType[FrameType["CONTROL"] = 18] = "CONTROL";
+})(FrameType || (FrameType = {}));
+export var ResetReason;
+(function (ResetReason) {
+    ResetReason[ResetReason["PROTOCOL_ERROR"] = 1] = "PROTOCOL_ERROR";
+    ResetReason[ResetReason["STREAM_CLOSED"] = 2] = "STREAM_CLOSED";
+    ResetReason[ResetReason["REFUSED"] = 3] = "REFUSED";
+    ResetReason[ResetReason["IDLE"] = 4] = "IDLE";
+    ResetReason[ResetReason["SESSION_ENDED"] = 5] = "SESSION_ENDED";
+    ResetReason[ResetReason["UNKNOWN"] = 255] = "UNKNOWN";
+})(ResetReason || (ResetReason = {}));
+/**
+ * MAX_FRAME_LEN is checked against the HEADER, before any allocation. The
+ * `length` field is u24 — 16 MiB of attacker-controlled allocation per frame if
+ * a decoder does `Buffer.alloc(length)` before dispatch. It equals the initial
+ * credit window so a single frame can never exceed a stream's credit.
+ */
+export const MAX_FRAME_LEN = 64 * 1024;
+/** The ONE decode path: OPEN/HEAD CBOR control payloads. Never DATA. */
+export const MAX_OPEN_PAYLOAD = 4 * 1024;
+export const FRAME_HEADER_LEN = 8;
+export const MAX_HEADERS = 64;
+export const MAX_HEADER_BYTES = 8 * 1024;
+export const MAX_PATH_LEN = 2 * 1024;
+export const MAX_CBOR_DEPTH = 4;
+export const MAX_CONCURRENT_STREAMS = 256;
+export const INITIAL_CREDIT = 64 * 1024;
+export const RELAY_BUF_SIZE = 32 * 1024;
+export const IDLE_STREAM_TIMEOUT_MS = 60_000;
+export const TUNNEL_PING_INTERVAL_MS = 15_000;
+export const TUNNEL_PING_TIMEOUT_MS = 45_000;
+/** Protocol errors. They are for the CLIENT's own log, never for a wire body. */
+export class ProtocolError extends Error {
+    code;
+    fatal;
+    /**
+     * `fatal` is the 2.15.3 behavior table expressed ONCE, so the Go edge and
+     * this client cannot drift on which violations close the tunnel and which
+     * only reset a stream.
+     */
+    constructor(code, fatal) {
+        // NOTE: the message is the CODE and nothing else. It never carries a
+        // payload, a length echo, or an offset — a payload in an error string
+        // reaches the process log and any error-reporting integration.
+        super(code);
+        this.code = code;
+        this.fatal = fatal;
+        this.name = "ProtocolError";
+    }
+}
+/** The fatal set, matching Go's TunnelFatal exactly. */
+const FATAL = new Set([
+    "frame_too_large",
+    "unknown_frame_type",
+    "even_stream_id",
+    "zero_stream_id",
+    "nonzero_stream_id",
+    "short_payload",
+]);
+function fail(code) {
+    throw new ProtocolError(code, FATAL.has(code));
+}
+const KNOWN_TYPES = new Set([
+    FrameType.OPEN,
+    FrameType.DATA,
+    FrameType.END,
+    FrameType.RESET,
+    FrameType.HEAD,
+    FrameType.PING,
+    FrameType.PONG,
+    FrameType.CONTROL,
+]);
+/** streamTyped frames address a STREAM and therefore require a non-zero id. */
+function streamTyped(t) {
+    return (t === FrameType.OPEN ||
+        t === FrameType.DATA ||
+        t === FrameType.END ||
+        t === FrameType.RESET ||
+        t === FrameType.HEAD);
+}
+/**
+ * validateFrameShape is the single place the 2.15.2 invariants live, shared by
+ * the encoder and the decoder so the two cannot disagree about what is legal.
+ *
+ * `fromEdge` selects the parity rule: a frame arriving FROM the edge may carry
+ * any id, but a frame this client WRITES must carry an odd one, because the
+ * edge assigns odd ids and the client never opens a stream. There is no path
+ * from the platform into this machine that this machine did not open.
+ */
+export function validateFrameShape(type, streamId, length, fromEdge) {
+    // FIRST. Nothing downstream may allocate from a length that failed here.
+    if (length > MAX_FRAME_LEN)
+        fail("frame_too_large");
+    if (!KNOWN_TYPES.has(type)) {
+        // NOT ignored. "Ignore unknown for forward-compat" is explicitly REJECTED:
+        // this is a closed protocol between two implementations we both own, and
+        // tolerance here would be a place to smuggle bytes.
+        fail("unknown_frame_type");
+    }
+    if (streamTyped(type)) {
+        if (streamId === 0)
+            fail("zero_stream_id");
+        if (!fromEdge && streamId % 2 === 0)
+            fail("even_stream_id");
+    }
+    else if (streamId !== 0) {
+        fail("nonzero_stream_id");
+    }
+    if ((type === FrameType.OPEN || type === FrameType.HEAD) && length > MAX_OPEN_PAYLOAD) {
+        // Refused BEFORE any CBOR decode is attempted.
+        fail("open_payload_too_large");
+    }
+}
+/** encodeHeader writes the 8-byte header: type u8 | streamId u32 | length u24. */
+export function encodeHeader(type, streamId, length) {
+    if (length < 0 || length > MAX_FRAME_LEN)
+        fail("frame_too_large");
+    const h = new Uint8Array(FRAME_HEADER_LEN);
+    h[0] = type;
+    h[1] = (streamId >>> 24) & 0xff;
+    h[2] = (streamId >>> 16) & 0xff;
+    h[3] = (streamId >>> 8) & 0xff;
+    h[4] = streamId & 0xff;
+    h[5] = (length >>> 16) & 0xff;
+    h[6] = (length >>> 8) & 0xff;
+    h[7] = length & 0xff;
+    return h;
+}
+/** encodeFrame serializes one whole frame. */
+export function encodeFrame(type, streamId, payload = new Uint8Array(0)) {
+    validateFrameShape(type, streamId, payload.length, false);
+    const out = new Uint8Array(FRAME_HEADER_LEN + payload.length);
+    out.set(encodeHeader(type, streamId, payload.length), 0);
+    out.set(payload, FRAME_HEADER_LEN);
+    return out;
+}
+/**
+ * decodeHeader reads and VALIDATES the header. Every limit the declared length
+ * can trip is checked here — this is the "before the byte that triggers them
+ * can allocate" boundary.
+ */
+export function decodeHeader(b, fromEdge) {
+    if (b.length < FRAME_HEADER_LEN)
+        fail("short_payload");
+    const type = b[0];
+    const streamId = ((b[1] << 24) >>> 0) + (b[2] << 16) + (b[3] << 8) + b[4];
+    const length = (b[5] << 16) + (b[6] << 8) + b[7];
+    validateFrameShape(type, streamId, length, fromEdge);
+    return { type: type, streamId, length };
+}
+/**
+ * FrameDecoder is a streaming demultiplexer over a byte stream.
+ *
+ * It NEVER sizes a buffer from a declared length before that length has passed
+ * decodeHeader — the accumulator only ever grows by bytes that actually
+ * arrived, so a frame declaring 16 MiB costs a comparison, not 16 MiB.
+ */
+export class FrameDecoder {
+    fromEdge;
+    buf = new Uint8Array(0);
+    header = null;
+    constructor(fromEdge) {
+        this.fromEdge = fromEdge;
+    }
+    /** push appends bytes and returns every complete frame they produced. */
+    push(chunk) {
+        // The accumulator is bounded by one header plus one max-size frame. It can
+        // never hold a declared length, only bytes that arrived.
+        const next = new Uint8Array(this.buf.length + chunk.length);
+        next.set(this.buf, 0);
+        next.set(chunk, this.buf.length);
+        this.buf = next;
+        const out = [];
+        for (;;) {
+            if (this.header === null) {
+                if (this.buf.length < FRAME_HEADER_LEN)
+                    return out;
+                // Throws on any 2.15.2 violation, BEFORE the payload is read at all.
+                this.header = decodeHeader(this.buf, this.fromEdge);
+                this.buf = this.buf.subarray(FRAME_HEADER_LEN);
+            }
+            if (this.buf.length < this.header.length)
+                return out;
+            const payload = this.buf.subarray(0, this.header.length);
+            this.buf = this.buf.subarray(this.header.length);
+            out.push({ ...this.header, payload });
+            this.header = null;
+        }
+    }
+    /**
+     * end reports whether the stream closed mid-frame. A declared length longer
+     * than the bytes that arrived is a violation, and THE PARTIAL IS DROPPED —
+     * never returned, never logged.
+     */
+    end() {
+        if (this.header !== null || this.buf.length > 0) {
+            this.buf = new Uint8Array(0);
+            this.header = null;
+            fail("short_payload");
+        }
+    }
+}
+/** encodeCredit/decodeCredit carry a u24 byte count on an END frame. */
+export function encodeCredit(n) {
+    return new Uint8Array([(n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff]);
+}
+export function decodeCredit(b) {
+    if (b.length !== 3)
+        return 0;
+    return (b[0] << 16) + (b[1] << 8) + b[2];
+}

package/dist/tunnel/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@vincentt-xr/harness/tunnel` — the Node half of the tunnel protocol.
+ *
+ * It is a SUBPATH EXPORT rather than part of the package root deliberately: the
+ * root entry is the browser-side diagnostics provider and must stay free of
+ * `node:` imports. Nothing under `src/client` imports anything here.
+ */
+export { FrameDecoder, FrameType, ProtocolError, ResetReason, FRAME_HEADER_LEN, IDLE_STREAM_TIMEOUT_MS, INITIAL_CREDIT, MAX_CBOR_DEPTH, MAX_CONCURRENT_STREAMS, MAX_FRAME_LEN, MAX_HEADERS, MAX_HEADER_BYTES, MAX_OPEN_PAYLOAD, MAX_PATH_LEN, RELAY_BUF_SIZE, TUNNEL_PING_INTERVAL_MS, TUNNEL_PING_TIMEOUT_MS, decodeCredit, decodeHeader, encodeCredit, encodeFrame, encodeHeader, validateFrameShape, type Frame, type FrameHeader, type ProtocolErrorCode, } from "./frame.js";
+export { UA_CLASSES, VIEWER_LABEL_RE, decodeControl, decodeHead, decodeOpen, encodeControl, encodeHead, encodeOpen, parseUAClass, parseViewerLabel, type ControlKind, type ControlPayload, type HeadPayload, type OpenPayload, type UAClass, } from "./cbor.js";
+export { FOLLOW_REDIRECTS, ForwardTargetError, assertStillLoopback, normalizeRequestTarget, resolveForwardTarget, sanitizeHeaders, type ForwardTarget, type ForwardTargetErrorCode, } from "./forwardTarget.js";
+export { TunnelClient, RESUME_HEADER, RESUME_TOKEN_LEN, UA_CLASS_STAMP_HEADER, VIEWER_STAMP_HEADER, parseResumeToken, type TunnelClientOptions, type TunnelState, } from "./client.js";

package/dist/tunnel/index.js

@@ -0,0 +1,11 @@
+/**
+ * `@vincentt-xr/harness/tunnel` — the Node half of the tunnel protocol.
+ *
+ * It is a SUBPATH EXPORT rather than part of the package root deliberately: the
+ * root entry is the browser-side diagnostics provider and must stay free of
+ * `node:` imports. Nothing under `src/client` imports anything here.
+ */
+export { FrameDecoder, FrameType, ProtocolError, ResetReason, FRAME_HEADER_LEN, IDLE_STREAM_TIMEOUT_MS, INITIAL_CREDIT, MAX_CBOR_DEPTH, MAX_CONCURRENT_STREAMS, MAX_FRAME_LEN, MAX_HEADERS, MAX_HEADER_BYTES, MAX_OPEN_PAYLOAD, MAX_PATH_LEN, RELAY_BUF_SIZE, TUNNEL_PING_INTERVAL_MS, TUNNEL_PING_TIMEOUT_MS, decodeCredit, decodeHeader, encodeCredit, encodeFrame, encodeHeader, validateFrameShape, } from "./frame.js";
+export { UA_CLASSES, VIEWER_LABEL_RE, decodeControl, decodeHead, decodeOpen, encodeControl, encodeHead, encodeOpen, parseUAClass, parseViewerLabel, } from "./cbor.js";
+export { FOLLOW_REDIRECTS, ForwardTargetError, assertStillLoopback, normalizeRequestTarget, resolveForwardTarget, sanitizeHeaders, } from "./forwardTarget.js";
+export { TunnelClient, RESUME_HEADER, RESUME_TOKEN_LEN, UA_CLASS_STAMP_HEADER, VIEWER_STAMP_HEADER, parseResumeToken, } from "./client.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vincentt-xr/harness",
-  "version": "1.0.0",
-  "description": "Vincentt AR dev-loop harness — in-app diagnostics provider + wire contract",
+  "version": "1.2.0",
+  "description": "Vincentt AR dev-loop harness - in-app diagnostics provider + wire contract",
   "license": "UNLICENSED",
   "type": "module",
   "sideEffects": false,
@@ -19,13 +19,25 @@
     "./events": {
       "types": "./dist/shared/events.d.ts",
       "import": "./dist/shared/events.js"
+    },
+    "./tunnel": {
+      "types": "./dist/tunnel/index.d.ts",
+      "import": "./dist/tunnel/index.js"
     }
   },
   "peerDependencies": {
     "react": "^18.2.0"
   },
   "devDependencies": {
-    "@types/react": "^18.3.12"
+    "@types/react": "^18.3.12",
+    "@types/ws": "^8.5.13",
+    "@types/node": "^22.9.0",
+    "@types/qrcode": "^1.5.5",
+    "jsdom": "^25.0.1"
+  },
+  "dependencies": {
+    "ws": "^8.18.0",
+    "qrcode": "^1.5.4"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",