@vincentt-xr/cli 0.20.0 → 0.22.0

package/dist/tunnel/client.js

@@ -16,7 +16,9 @@ import { request as httpRequest } from "node:http";
 import { connect as netConnect } from "node:net";
 import { WebSocket } from "ws";
 import { FrameDecoder, FrameType, MAX_FRAME_LEN, ProtocolError, ResetReason, RELAY_BUF_SIZE, INITIAL_CREDIT, TUNNEL_PING_INTERVAL_MS, TUNNEL_PING_TIMEOUT_MS, decodeCredit, encodeCredit, encodeFrame, } from "./frame.js";
-import { decodeControl, decodeOpen, encodeHead, parseUAClass, parseViewerLabel, } from "./cbor.js";
+import { BASE_CAPS, decodeControl, decodeOpen, encodeHead, parseUAClass, parseViewerLabel, } from "./cbor.js";
+import { CAPS_HEADER, OFFERED_CAPS_VALUE, parseAgreedCaps } from "./caps.js";
+import { CLIENT_HEADER, clientHeaderValue } from "../shared/clientHeader.js";
 import { FOLLOW_REDIRECTS, ForwardTargetError, assertStillLoopback, normalizeRequestTarget, sanitizeHeaders, } from "./forwardTarget.js";
 /** RECONNECT_BACKOFF_MS is 0.5s -> 8s with jitter (2.2). */
 const BACKOFF_BASE_MS = 500;
@@ -79,6 +81,19 @@ export const RESUME_HEADER = "x-vincentt-resume";
 export const SESSION_HEADER = "x-vincentt-session";
 /** The Authorization header, named once so the never-send-both rule cites it. */
 export const AUTHORIZATION_HEADER = "authorization";
+/**
+ * The version refusal on a dial: `410` with these headers (f3 §2.2.3). 410 is
+ * in a released client's stop set; only a client that reads the reason header
+ * knows it means "upgrade".
+ */
+export const REFUSAL_HEADER = "x-vincentt-refusal";
+export const CLI_MINIMUM_HEADER = "x-vincentt-cli-minimum";
+export const CLI_DECLARED_HEADER = "x-vincentt-cli-declared";
+export const UPGRADE_REQUIRED_REFUSAL = "cli_upgrade_required";
+/** One header value, or undefined when absent or not a single string. */
+function single(v) {
+    return typeof v === "string" ? v : undefined;
+}
 /**
  * RESUME_TOKEN_LEN is base64url(32 random bytes), unpadded. It mirrors
  * `resumeTokenLen` in the Go edge so the two ends of this wire state the same
@@ -104,22 +119,40 @@ export function parseResumeToken(raw) {
         return null;
     return RESUME_TOKEN_RE.test(raw) ? raw : null;
 }
+/** The forwarded content-length, parsed as digits only. */
+function declaredLength(headers) {
+    const values = headers
+        .filter(([k]) => k.toLowerCase() === "content-length")
+        .map(([, v]) => v);
+    if (values.length === 0)
+        return { kind: "none" };
+    if (values.length > 1 || !/^\d{1,15}$/.test(values[0]))
+        return { kind: "invalid" };
+    return { kind: "length", n: Number(values[0]) };
+}
 /**
- * Whether the edge will stream a body for this request. The edge pumps DATA and
- * a closing END only when the request has one (`pumpRequestBody`, taken when
- * ContentLength != 0), so a request without a positive content-length gets no
- * END at all and must be ended locally at once, as before.
+ * With `open-body` agreed, the edge's `body` decides and a content-length must
+ * agree with it (the edge writes at most one, positive). Without it, the base
+ * rule: a positive content-length streams, anything else ends at OPEN. An
+ * upgrade has no body whatever it declares.
  */
-function declaresBody(headers) {
-    return declaredLength(headers) > 0;
-}
-/** The forwarded content-length as a whole number, or 0 when absent or unusable. */
-function declaredLength(headers) {
-    const raw = headers.find(([k]) => k.toLowerCase() === "content-length")?.[1];
-    if (raw === undefined || !/^\s*\d+\s*$/.test(raw))
-        return 0;
-    const n = Number(raw.trim());
-    return Number.isSafeInteger(n) ? n : 0;
+export function bodyPlan(open, caps) {
+    if (open.upgrade !== undefined)
+        return { kind: "none" };
+    const cl = declaredLength(open.headers);
+    if (cl.kind === "invalid")
+        return { kind: "reset" };
+    if (caps.has("open-body")) {
+        if (open.body === true) {
+            if (cl.kind === "none")
+                return { kind: "chunked" };
+            return cl.n > 0 ? { kind: "declared", length: cl.n } : { kind: "reset" };
+        }
+        return cl.kind === "length" && cl.n > 0 ? { kind: "reset" } : { kind: "none" };
+    }
+    return cl.kind === "length" && cl.n > 0
+        ? { kind: "declared", length: cl.n }
+        : { kind: "none" };
 }
 export class TunnelClient {
     opts;
@@ -133,6 +166,8 @@ export class TunnelClient {
      * is a credential in a log.
      */
     resumeToken = null;
+    /** This connection's agreed set. Fixed at its 101, reset on every dial. */
+    caps = BASE_CAPS;
     attempt = 0;
     closed = false;
     state = "connecting";
@@ -182,14 +217,21 @@ export class TunnelClient {
      * a resume token only ever exists after a 101 has delivered one.
      */
     dialHeaders() {
+        // The client tag and the caps offer ride BOTH branches. Neither is a
+        // credential, so the never-send-both rule below is untouched by them.
+        const offer = {
+            [CLIENT_HEADER]: clientHeaderValue(),
+            [CAPS_HEADER]: OFFERED_CAPS_VALUE,
+        };
         if (this.resumeToken === null) {
             // FIRST ATTACH. The grant is a BEARER credential on the upgrade request,
             // never in the URL: a capability in a query string lands in every
             // intermediary's log.
-            return { [AUTHORIZATION_HEADER]: `Bearer ${this.opts.grant}` };
+            return { ...offer, [AUTHORIZATION_HEADER]: `Bearer ${this.opts.grant}` };
         }
         // RECONNECT. The resume pair, and no Authorization header at all.
         return {
+            ...offer,
             [RESUME_HEADER]: this.resumeToken,
             [SESSION_HEADER]: this.opts.sessionId,
         };
@@ -207,6 +249,8 @@ export class TunnelClient {
             });
         this.ws = ws;
         this.decoder = new FrameDecoder(true);
+        // Until a 101 says otherwise, this connection speaks the base protocol.
+        this.caps = BASE_CAPS;
         // `ws` emits BOTH `error` and `close` for a single failed connection, so
         // the handler is bound once per socket and guarded: without the guard each
         // failure schedules TWO retries, the next failure four, and the backoff
@@ -234,6 +278,16 @@ export class TunnelClient {
             // later handshake omitted the header would forfeit a working reconnect.
             if (next !== null)
                 this.resumeToken = next;
+            // The agreed set fixes this connection's grammar. Absent is the base
+            // protocol (an edge that predates negotiation); a malformed answer, or
+            // one naming a token this client did not offer, is the edge
+            // misbehaving and ends the preview.
+            const agreed = parseAgreedCaps(res.headers[CAPS_HEADER], res.rawHeaders);
+            if (agreed === null) {
+                this.fatalViolation(ws);
+                return;
+            }
+            this.caps = agreed;
         });
         /**
          * A REFUSED RECONNECT — the edge answered with a status instead of a 101.
@@ -259,6 +313,16 @@ export class TunnelClient {
          */
         ws.on("unexpected-response", (_req, res) => {
             const status = res.statusCode ?? 0;
+            // The version refusal: final, one dial, no backoff. It is reported
+            // instead of the generic refused-reconnect, whose 410 means "gone".
+            if (status === 410 &&
+                single(res.headers?.[REFUSAL_HEADER]) === UPGRADE_REQUIRED_REFUSAL) {
+                this.closed = true;
+                res.destroy?.();
+                this.opts.onRefused?.("upgrade_required", single(res.headers?.[CLI_MINIMUM_HEADER]), single(res.headers?.[CLI_DECLARED_HEADER]));
+                closeOnce();
+                return;
+            }
             this.opts.onReconnectRefused?.(status);
             // TERMINAL statuses stop the loop. A refused credential does not become
             // valid by being presented again, and re-dialling a 401 is what turns
@@ -317,6 +381,18 @@ export class TunnelClient {
                 this.open();
         }, delay);
     }
+    /**
+     * End the preview for a violation the edge alone could cause. A redial reaches
+     * the same edge and gets the same answer: before this was terminal, a
+     * persistently malformed 101 redialled every 8 seconds indefinitely.
+     */
+    fatalViolation(ws) {
+        if (ws === null || this.ws !== ws || this.closed)
+            return;
+        this.closed = true;
+        this.opts.onProtocolViolation?.();
+        ws.close();
+    }
     startPing() {
         this.stopPing();
         this.pingTimer = setInterval(() => {
@@ -350,18 +426,19 @@ export class TunnelClient {
         try {
             frames = this.decoder.push(chunk);
         }
-        catch (err) {
-            // A FATAL protocol error closes the tunnel; a stream-level one cannot
-            // reach here (the decoder only throws fatal ones).
-            if (err instanceof ProtocolError && err.fatal) {
-                this.ws?.close();
-                return;
-            }
+        catch {
+            // The frame decoder throws only fatal errors: the tunnel closes.
             this.ws?.close();
             return;
         }
-        for (const f of frames)
+        const ws = this.ws;
+        for (const f of frames) {
+            // A fatal frame earlier in this chunk closed the connection; nothing
+            // after it is acted on.
+            if (this.ws !== ws || ws === null || ws.readyState !== WebSocket.OPEN)
+                return;
             this.dispatch(f.type, f.streamId, f.payload);
+        }
     }
     dispatch(type, streamId, payload) {
         switch (type) {
@@ -372,31 +449,41 @@ export class TunnelClient {
                 this.lastPong = Date.now();
                 return;
             case FrameType.CONTROL: {
+                let ctrl;
                 try {
-                    const ctrl = decodeControl(payload);
-                    if (ctrl.kind === "viewer_gone") {
-                        // Routed AWAY from onControl deliberately. The other three kinds
-                        // all mean "this session is ending" and the CLI prints an ending
-                        // screen for them; a viewer leaving means the opposite — the
-                        // session is fine and one device went away.
-                        this.opts.onViewerGone?.(ctrl.viewerLabel);
-                    }
-                    else {
-                        this.opts.onControl?.(ctrl.kind);
-                    }
+                    ctrl = decodeControl(payload, this.caps);
                 }
                 catch {
-                    // A malformed CONTROL is a stream-level fault on stream 0, which
-                    // means it is simply ignored rather than killing a live tunnel.
+                    // A CONTROL this connection cannot read (malformed, unknown, or a
+                    // kind it did not agree) is fatal: only the edge writes stream 0.
+                    this.fatalViolation(this.ws);
+                    return;
+                }
+                if (ctrl.kind === "viewer_gone") {
+                    // Routed AWAY from onControl deliberately. The other kinds all mean
+                    // "this session is ending" and the CLI prints an ending screen for
+                    // them; a viewer leaving means the opposite — the session is fine
+                    // and one device went away.
+                    this.opts.onViewerGone?.(ctrl.viewerLabel);
+                    return;
                 }
+                // The edge drained this session and is about to close the socket. The
+                // session will not come back, so no redial may follow that close.
+                if (ctrl.kind === "authz_expired")
+                    this.closed = true;
+                this.opts.onControl?.(ctrl.kind);
                 return;
             }
             case FrameType.OPEN: {
                 let open;
                 try {
-                    open = decodeOpen(payload);
+                    open = decodeOpen(payload, this.caps);
                 }
-                catch {
+                catch (err) {
+                    if (err instanceof ProtocolError && err.fatal) {
+                        this.fatalViolation(this.ws);
+                        return;
+                    }
                     this.send(FrameType.RESET, streamId, new Uint8Array([ResetReason.PROTOCOL_ERROR]));
                     return;
                 }
@@ -435,6 +522,17 @@ export class TunnelClient {
             }
             case FrameType.END: {
                 const s = this.streams.get(streamId);
+                // An END is bare (half-close) or a u24 credit grant. Any other length
+                // resets that stream; the tunnel survives.
+                if (payload.length !== 0 && payload.length !== 3) {
+                    if (s !== undefined) {
+                        this.quietReset(streamId, s, 0, ResetReason.PROTOCOL_ERROR);
+                    }
+                    else {
+                        this.send(FrameType.RESET, streamId, new Uint8Array([ResetReason.PROTOCOL_ERROR]));
+                    }
+                    return;
+                }
                 if (s === undefined)
                     return;
                 if (payload.length === 3) {
@@ -497,12 +595,19 @@ export class TunnelClient {
         const uaClass = parseUAClass(open.headers.find(([k]) => k.toLowerCase() === "x-vincentt-ua-class")?.[1] ??
             "unknown");
         this.opts.onViewer?.(label, uaClass);
+        // A content-length that disagrees with what the edge said is viewer-made,
+        // so it resets this stream only. No local request is opened for it.
+        const plan = bodyPlan(open, this.caps);
+        if (plan.kind === "reset") {
+            this.send(FrameType.RESET, streamId, new Uint8Array([ResetReason.PROTOCOL_ERROR]));
+            return;
+        }
         // A request with a body is registered BEFORE the loopback await below: the
         // edge sends DATA right behind OPEN, and a frame for an unknown stream is
         // answered with RESET. Bytes that arrive before the local request exists
         // are held here. They are bounded by the edge's credit window, because
         // credit is returned only once the local server has taken them.
-        const expectsBody = open.upgrade === undefined && declaresBody(open.headers);
+        const expectsBody = plan.kind !== "none";
         const early = {
             pending: [],
             ended: false,
@@ -545,11 +650,18 @@ export class TunnelClient {
         // Reset or torn down while the loopback check ran: nothing to open.
         if (early.aborted)
             return;
+        // sanitizeHeaders drops every viewer `x-vincentt-*` and `transfer-encoding`
+        // before anything of ours is stamped.
         const headers = sanitizeHeaders(open.headers, this.opts.target);
         // Stamped AFTER sanitizeHeaders so a viewer-supplied header of the same
         // name cannot shadow ours. Both values are already validated: the label
         // against VIEWER_LABEL_RE, the class against the closed enum of six.
         headers.push([VIEWER_STAMP_HEADER, label], [UA_CLASS_STAMP_HEADER, uaClass]);
+        // Explicit, whatever the method: Node frames no GET, HEAD, DELETE or
+        // OPTIONS body on its own, and unframed bytes on the loopback hop would be
+        // parsed as a second request that bypassed every rule above.
+        if (plan.kind === "chunked")
+            headers.push(["transfer-encoding", "chunked"]);
         this.streams.set(streamId, stream);
         if (open.upgrade !== undefined) {
             // `upgrade` is CARRIED, NOT INTERPRETED, by the protocol — but the local
@@ -565,6 +677,9 @@ export class TunnelClient {
             method: open.method,
             path,
             headers: Object.fromEntries(headers),
+            // One loopback connection per stream: no connection, and so no
+            // leftover bytes, outlives the stream that opened it.
+            agent: false,
             // The BROWSER follows a redirect, on the viewer's own origin. There is
             // no option to change this.
             ...(FOLLOW_REDIRECTS ? {} : {}),
@@ -621,11 +736,11 @@ export class TunnelClient {
         // A body that disagrees with its content-length, long or short, ends in a
         // quiet RESET: extra bytes never reach the socket (they could be smuggled
         // onto a reused connection), and a short body never leaves the local server
-        // waiting for bytes that will not come.
-        const declared = declaredLength(open.headers);
+        // waiting for bytes that will not come. A chunked body has no count to hold.
+        const declared = plan.kind === "declared" ? plan.length : undefined;
         let written = 0;
         stream.writeBody = (b) => {
-            if (written + b.length > declared) {
+            if (declared !== undefined && written + b.length > declared) {
                 // Thrown to the DATA handler, which resets quietly; nothing is written.
                 throw new Error("body exceeds content-length");
             }
@@ -641,8 +756,9 @@ export class TunnelClient {
         // The body ends on the edge's half-close, never at OPEN, and only when every
         // declared byte arrived. Thrown to the caller, which resets quietly.
         stream.endBody = () => {
-            if (written !== declared)
+            if (declared !== undefined && written !== declared) {
                 throw new Error("body shorter than content-length");
+            }
             req.end();
         };
         try {

package/dist/tunnel/frame.d.ts

@@ -71,7 +71,7 @@ export declare class ProtocolError extends Error {
      */
     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 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" | "not_negotiated" | "open_body_missing" | "open_body_with_upgrade";
 export interface FrameHeader {
     type: FrameType;
     streamId: number;

package/dist/tunnel/frame.js

@@ -81,7 +81,7 @@ export class ProtocolError extends Error {
         this.name = "ProtocolError";
     }
 }
-/** The fatal set, matching Go's TunnelFatal exactly. */
+/** Every code that closes the tunnel rather than one stream. */
 const FATAL = new Set([
     "frame_too_large",
     "unknown_frame_type",
@@ -89,6 +89,9 @@ const FATAL = new Set([
     "zero_stream_id",
     "nonzero_stream_id",
     "short_payload",
+    "not_negotiated",
+    "open_body_missing",
+    "open_body_with_upgrade",
 ]);
 function fail(code) {
     throw new ProtocolError(code, FATAL.has(code));
@@ -125,9 +128,10 @@ export function validateFrameShape(type, streamId, length, fromEdge) {
     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.
+        // A frame type outside the set AGREED FOR THIS CONNECTION closes it. No
+        // negotiated element is a frame type, so the agreed set of types is the base
+        // set on every connection. Negotiation narrows what each side may send; it
+        // never widens what a receiver accepts, so an unknown type is never ignored.
         fail("unknown_frame_type");
     }
     if (streamTyped(type)) {

package/dist/tunnel/index.d.ts

@@ -4,6 +4,7 @@
  * fix ships as a CLI release.
  */
 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 { BASE_CAPS, TUNNEL_CAPS, UA_CLASSES, VIEWER_LABEL_RE, decodeControl, decodeHead, decodeOpen, encodeControl, encodeHead, encodeOpen, parseUAClass, parseViewerLabel, type CapSet, type ControlKind, type ControlPayload, type HeadPayload, type OpenPayload, type TunnelCap, type UAClass, } from "./cbor.js";
+export { CAPS_HEADER, OFFERED_CAPS, OFFERED_CAPS_VALUE, parseAgreedCaps } from "./caps.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";
+export { TunnelClient, CLI_DECLARED_HEADER, CLI_MINIMUM_HEADER, REFUSAL_HEADER, RESUME_HEADER, RESUME_TOKEN_LEN, UPGRADE_REQUIRED_REFUSAL, bodyPlan, type BodyPlan, UA_CLASS_STAMP_HEADER, VIEWER_STAMP_HEADER, parseResumeToken, type TunnelClientOptions, type TunnelState, } from "./client.js";

package/dist/tunnel/index.js

@@ -4,6 +4,7 @@
  * fix ships as a CLI release.
  */
 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 { BASE_CAPS, TUNNEL_CAPS, UA_CLASSES, VIEWER_LABEL_RE, decodeControl, decodeHead, decodeOpen, encodeControl, encodeHead, encodeOpen, parseUAClass, parseViewerLabel, } from "./cbor.js";
+export { CAPS_HEADER, OFFERED_CAPS, OFFERED_CAPS_VALUE, parseAgreedCaps } from "./caps.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";
+export { TunnelClient, CLI_DECLARED_HEADER, CLI_MINIMUM_HEADER, REFUSAL_HEADER, RESUME_HEADER, RESUME_TOKEN_LEN, UPGRADE_REQUIRED_REFUSAL, bodyPlan, UA_CLASS_STAMP_HEADER, VIEWER_STAMP_HEADER, parseResumeToken, } from "./client.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincentt-xr/cli",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Vincentt CLI — the vincentt command-line dev loop (login, create, publish, preview, diagnostics, feedback, relay)",
   "license": "UNLICENSED",
   "type": "module",
@@ -28,11 +28,12 @@
     "qrcode": "^1.5.4",
     "ws": "^8.18.0",
     "zod": "^3.23.8",
-    "@vincentt-xr/harness": "2.0.0"
+    "@vincentt-xr/harness": "3.0.0"
   },
   "devDependencies": {
     "@types/qrcode": "^1.5.5",
-    "@types/ws": "^8.5.13"
+    "@types/ws": "^8.5.13",
+    "@vincentt-xr/cli-released": "npm:@vincentt-xr/cli@0.20.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",