@vincentt-xr/cli 0.19.0 → 0.21.0

package/dist/tunnel/caps.js

@@ -0,0 +1,52 @@
+/**
+ * Capability negotiation, the client's half (f3 §2.2.2). The client offers on
+ * every dial; the edge answers the agreed set on the 101, or omits the header
+ * when it agreed nothing. The agreed set fixes this connection's decode grammar.
+ */
+import { BASE_CAPS, TUNNEL_CAPS } from "./cbor.js";
+/** Lower-case: Node lower-cases response header names. */
+export const CAPS_HEADER = "x-vincentt-tunnel-caps";
+/** Every element this client understands, offered on every dial. */
+export const OFFERED_CAPS = TUNNEL_CAPS;
+export const OFFERED_CAPS_VALUE = OFFERED_CAPS.join(", ");
+const TOKEN_RE = /^[a-z][a-z0-9-]{0,31}$/;
+const MAX_TOKENS = 8;
+const MAX_BYTES = 256;
+/**
+ * The agreed set from a 101, or null for a protocol violation: the header
+ * duplicated, an array, ungrammatical, or naming a token this client did not
+ * offer. Absent is the base protocol, never a violation. `rawHeaders` is
+ * consulted because Node joins a duplicated header into one comma list, which
+ * would otherwise read as a grammatical value.
+ */
+export function parseAgreedCaps(value, rawHeaders, offered = OFFERED_CAPS) {
+    if (rawHeaders !== undefined) {
+        let seen = 0;
+        for (let i = 0; i < rawHeaders.length; i += 2) {
+            if (rawHeaders[i]?.toLowerCase() === CAPS_HEADER)
+                seen++;
+        }
+        if (seen > 1)
+            return null;
+    }
+    if (value === undefined)
+        return BASE_CAPS;
+    if (typeof value !== "string")
+        return null;
+    if (Buffer.byteLength(value, "utf8") > MAX_BYTES)
+        return null;
+    const tokens = value.split(",").map((t) => t.replace(/^ +| +$/g, ""));
+    if (tokens.length > MAX_TOKENS)
+        return null;
+    const agreed = new Set();
+    for (const t of tokens) {
+        if (!TOKEN_RE.test(t))
+            return null;
+        if (!offered.includes(t))
+            return null;
+        if (agreed.has(t))
+            return null;
+        agreed.add(t);
+    }
+    return agreed;
+}

package/dist/tunnel/cbor.d.ts

@@ -15,6 +15,15 @@
  * themselves, but because the encoder we own never emits them, so accepting
  * them would only widen the input this parser has to be correct about.
  */
+/**
+ * The optional protocol elements a connection may agree on the upgrade (f3
+ * §2.2.2). Each changes one disjoint grammar element.
+ */
+export declare const TUNNEL_CAPS: readonly ["open-body", "control-authz-expired"];
+export type TunnelCap = (typeof TUNNEL_CAPS)[number];
+export type CapSet = ReadonlySet<TunnelCap>;
+/** The agreed-nothing grammar: exactly the pre-negotiation protocol. */
+export declare const BASE_CAPS: CapSet;
 /**
  * VIEWER_LABEL_RE is the SAME regex the edge assigns against, and this client
  * RE-VALIDATES rather than trusting the edge. That is closure (c) of the three
@@ -39,6 +48,11 @@ export interface OpenPayload {
     method: string;
     path: string;
     headers: [string, string][];
+    /**
+     * Whether a request body follows. Present on every non-upgrade OPEN iff the
+     * connection agreed `open-body`; never present with `upgrade`.
+     */
+    body?: boolean;
     upgrade?: string;
 }
 export interface HeadPayload {
@@ -46,26 +60,39 @@ export interface HeadPayload {
     headers: [string, string][];
 }
 /**
- * `viewer_gone` is the ONE non-terminal kind: the other three mean the session
- * is ending, this one means a viewer's connection closed while the session
- * continues. It is also the only kind carrying a second key.
+ * A closed enum of five. `viewer_gone` is the ONE non-terminal kind: the others
+ * mean the session is ending, this one means a viewer's connection closed while
+ * the session continues. It is also the only kind carrying a second key.
+ * `authz_expired` exists only on a connection that agreed
+ * `control-authz-expired`.
  */
-export type ControlKind = "revoke" | "expiring" | "superseded" | "viewer_gone";
+export type ControlKind = "revoke" | "expiring" | "superseded" | "authz_expired" | "viewer_gone";
 /** A decoded CONTROL payload. `viewerLabel` is present only on `viewer_gone`. */
 export interface ControlPayload {
     kind: ControlKind;
     viewerLabel?: string;
 }
-export declare function decodeOpen(b: Uint8Array): OpenPayload;
+/**
+ * Decode an OPEN under the connection's agreed set. `body` on a connection that
+ * did not agree `open-body`, its absence on a non-upgrade OPEN that did, and
+ * `body` beside `upgrade` are all fatal: only the edge writes that key.
+ */
+export declare function decodeOpen(b: Uint8Array, caps?: CapSet): OpenPayload;
 export declare function decodeHead(b: Uint8Array): HeadPayload;
 /**
- * The map arity is asserted AGAINST THE KIND, so a payload claiming `revoke`
- * with a trailing label is refused as malformed rather than quietly accepted
- * with the extra key ignored.
+ * Decode a CONTROL under the connection's agreed set. EVERY failure is fatal:
+ * CONTROL rides stream 0, so there is no stream to reset, and a CONTROL the
+ * client cannot read is the edge misbehaving. The map arity is asserted
+ * AGAINST THE KIND, so a payload claiming `revoke` with a trailing label is
+ * refused rather than quietly accepted with the extra key ignored.
+ */
+export declare function decodeControl(b: Uint8Array, caps?: CapSet): ControlPayload;
+/**
+ * Canonical key order: viewerLabel, method, path, headers, [body], [upgrade].
+ * The client never sends an OPEN; this is the mirror of the edge's encoder for
+ * the fixture round trip, and it refuses an element outside `caps` the same way.
  */
-export declare function decodeControl(b: Uint8Array): ControlPayload;
-/** Canonical key order: viewerLabel, method, path, headers, [upgrade]. */
-export declare function encodeOpen(p: OpenPayload): Uint8Array;
+export declare function encodeOpen(p: OpenPayload, caps?: CapSet): Uint8Array;
 /** Canonical key order: status, headers. */
 export declare function encodeHead(p: HeadPayload): Uint8Array;
-export declare function encodeControl(kind: ControlKind, viewerLabel?: string): Uint8Array;
+export declare function encodeControl(kind: ControlKind, viewerLabel?: string, caps?: CapSet): Uint8Array;

package/dist/tunnel/cbor.js

@@ -18,10 +18,25 @@
 import { MAX_CBOR_DEPTH, MAX_HEADERS, MAX_HEADER_BYTES, MAX_OPEN_PAYLOAD, MAX_PATH_LEN, ProtocolError, } from "./frame.js";
 const MAX_METHOD_LEN = 16;
 const MAX_VIEWER_LABEL_LEN = 11;
-/** Every CBOR error is STREAM-level: the stream dies, the tunnel SURVIVES. */
+/** A CBOR shape error is STREAM-level: the stream dies, the tunnel SURVIVES. */
 function fail(code) {
     throw new ProtocolError(code, false);
 }
+/**
+ * An element outside the connection's agreed set, or a violation of what the
+ * agreement promises, closes the TUNNEL: only the edge writes these keys, so a
+ * wrong one is the edge misbehaving, not a viewer.
+ */
+function fatal(code) {
+    throw new ProtocolError(code, true);
+}
+/**
+ * The optional protocol elements a connection may agree on the upgrade (f3
+ * §2.2.2). Each changes one disjoint grammar element.
+ */
+export const TUNNEL_CAPS = ["open-body", "control-authz-expired"];
+/** The agreed-nothing grammar: exactly the pre-negotiation protocol. */
+export const BASE_CAPS = new Set();
 /**
  * VIEWER_LABEL_RE is the SAME regex the edge assigns against, and this client
  * RE-VALIDATES rather than trusting the edge. That is closure (c) of the three
@@ -61,8 +76,13 @@ const CONTROL_ARITY = new Map([
     ["revoke", 1],
     ["expiring", 1],
     ["superseded", 1],
+    ["authz_expired", 1],
     ["viewer_gone", 2],
 ]);
+/** The kinds a connection may receive only when it agreed the named element. */
+const NEGOTIATED_KIND = new Map([
+    ["authz_expired", "control-authz-expired"],
+]);
 // ---- decoding ---------------------------------------------------------------
 class Reader {
     b;
@@ -140,6 +160,13 @@ class Reader {
             fail("cbor_malformed");
         return arg;
     }
+    /** CBOR simple values 20 (false) and 21 (true); nothing else. */
+    bool() {
+        const { major, arg } = this.head();
+        if (major !== 7 || (arg !== 20 && arg !== 21))
+            fail("cbor_malformed");
+        return arg === 21;
+    }
     /**
      * headerPairs reads a map of text->text, enforcing MAX_HEADERS and
      * MAX_HEADER_BYTES as it goes. The COUNT bound is checked against the
@@ -173,7 +200,12 @@ class Reader {
         }
     }
 }
-export function decodeOpen(b) {
+/**
+ * Decode an OPEN under the connection's agreed set. `body` on a connection that
+ * did not agree `open-body`, its absence on a non-upgrade OPEN that did, and
+ * `body` beside `upgrade` are all fatal: only the edge writes that key.
+ */
+export function decodeOpen(b, caps = BASE_CAPS) {
     if (b.length > MAX_OPEN_PAYLOAD)
         fail("open_payload_too_large");
     const r = new Reader(b);
@@ -184,6 +216,7 @@ export function decodeOpen(b) {
     let method;
     let path;
     let headers = [];
+    let body;
     let upgrade;
     for (let k = 0; k < arg; k++) {
         const key = r.text(32);
@@ -210,6 +243,11 @@ export function decodeOpen(b) {
             case "headers":
                 headers = r.headerPairs();
                 break;
+            case "body":
+                if (!caps.has("open-body"))
+                    fatal("not_negotiated");
+                body = r.bool();
+                break;
             case "upgrade":
                 upgrade = r.text(32);
                 break;
@@ -227,7 +265,15 @@ export function decodeOpen(b) {
     // frame.
     if (r.i !== b.length)
         fail("cbor_malformed");
+    if (caps.has("open-body")) {
+        if (upgrade !== undefined && body !== undefined)
+            fatal("open_body_with_upgrade");
+        if (upgrade === undefined && body === undefined)
+            fatal("open_body_missing");
+    }
     const out = { viewerLabel, method, path, headers };
+    if (body !== undefined)
+        out.body = body;
     if (upgrade !== undefined)
         out.upgrade = upgrade;
     return out;
@@ -267,11 +313,23 @@ export function decodeHead(b) {
     return { status, headers };
 }
 /**
- * The map arity is asserted AGAINST THE KIND, so a payload claiming `revoke`
- * with a trailing label is refused as malformed rather than quietly accepted
- * with the extra key ignored.
+ * Decode a CONTROL under the connection's agreed set. EVERY failure is fatal:
+ * CONTROL rides stream 0, so there is no stream to reset, and a CONTROL the
+ * client cannot read is the edge misbehaving. The map arity is asserted
+ * AGAINST THE KIND, so a payload claiming `revoke` with a trailing label is
+ * refused rather than quietly accepted with the extra key ignored.
  */
-export function decodeControl(b) {
+export function decodeControl(b, caps = BASE_CAPS) {
+    try {
+        return decodeControlShape(b, caps);
+    }
+    catch (err) {
+        if (err instanceof ProtocolError && !err.fatal)
+            fatal(err.code);
+        throw err;
+    }
+}
+function decodeControlShape(b, caps) {
     if (b.length > MAX_OPEN_PAYLOAD)
         fail("open_payload_too_large");
     const r = new Reader(b);
@@ -281,6 +339,9 @@ export function decodeControl(b) {
     if (r.text(32) !== "kind")
         fail("cbor_malformed");
     const v = r.text(32);
+    const needs = NEGOTIATED_KIND.get(v);
+    if (needs !== undefined && !caps.has(needs))
+        fatal("not_negotiated");
     const want = CONTROL_ARITY.get(v);
     if (want === undefined || arg !== want)
         fail("cbor_malformed");
@@ -347,20 +408,30 @@ function headerMap(h) {
         out = out.concat(text(k), text(v));
     return out;
 }
-/** Canonical key order: viewerLabel, method, path, headers, [upgrade]. */
-export function encodeOpen(p) {
+/**
+ * Canonical key order: viewerLabel, method, path, headers, [body], [upgrade].
+ * The client never sends an OPEN; this is the mirror of the edge's encoder for
+ * the fixture round trip, and it refuses an element outside `caps` the same way.
+ */
+export function encodeOpen(p, caps = BASE_CAPS) {
     if (parseViewerLabel(p.viewerLabel) === null)
         fail("cbor_viewer");
     if (p.path.length > MAX_PATH_LEN)
         fail("cbor_path_len");
     if (p.headers.length > MAX_HEADERS)
         fail("cbor_headers");
-    const n = p.upgrade ? 5 : 4;
+    if (p.body !== undefined && !caps.has("open-body"))
+        fatal("not_negotiated");
+    if (p.body !== undefined && p.upgrade)
+        fatal("open_body_with_upgrade");
+    const n = 4 + (p.body !== undefined ? 1 : 0) + (p.upgrade ? 1 : 0);
     let out = head(5, n);
     out = out.concat(text("viewerLabel"), text(p.viewerLabel));
     out = out.concat(text("method"), text(p.method));
     out = out.concat(text("path"), text(p.path));
     out = out.concat(text("headers"), headerMap(p.headers));
+    if (p.body !== undefined)
+        out = out.concat(text("body"), [p.body ? 0xf5 : 0xf4]);
     if (p.upgrade)
         out = out.concat(text("upgrade"), text(p.upgrade));
     const b = new Uint8Array(out);
@@ -382,10 +453,13 @@ export function encodeHead(p) {
         fail("open_payload_too_large");
     return b;
 }
-export function encodeControl(kind, viewerLabel) {
+export function encodeControl(kind, viewerLabel, caps = BASE_CAPS) {
     const arity = CONTROL_ARITY.get(kind);
     if (arity === undefined)
         fail("cbor_malformed");
+    const needs = NEGOTIATED_KIND.get(kind);
+    if (needs !== undefined && !caps.has(needs))
+        fatal("not_negotiated");
     if (kind === "viewer_gone") {
         if (viewerLabel === undefined || parseViewerLabel(viewerLabel) === null) {
             fail("cbor_viewer");

package/dist/tunnel/client.d.ts

@@ -14,7 +14,7 @@
  */
 import { WebSocket } from "ws";
 import { encodeCredit } from "./frame.js";
-import { type ControlKind, type UAClass } from "./cbor.js";
+import { type CapSet, type ControlKind, type OpenPayload, type UAClass } from "./cbor.js";
 import { type ForwardTarget } from "./forwardTarget.js";
 /**
  * VIEWER_STAMP_HEADER carries the VALIDATED label to the creator's own local
@@ -59,6 +59,15 @@ export declare const RESUME_HEADER = "x-vincentt-resume";
 export declare const SESSION_HEADER = "x-vincentt-session";
 /** The Authorization header, named once so the never-send-both rule cites it. */
 export declare 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 declare const REFUSAL_HEADER = "x-vincentt-refusal";
+export declare const CLI_MINIMUM_HEADER = "x-vincentt-cli-minimum";
+export declare const CLI_DECLARED_HEADER = "x-vincentt-cli-declared";
+export declare const UPGRADE_REQUIRED_REFUSAL = "cli_upgrade_required";
 /**
  * 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
@@ -113,8 +122,17 @@ export interface TunnelClientOptions {
      * client nothing, so a phone refreshing read as an arriving crowd.
      */
     readonly onViewerGone?: (label: string) => void;
-    /** onControl carries revoke/expiring/superseded so the CLI prints the right ending. */
+    /**
+     * onControl carries revoke/expiring/superseded/authz_expired so the CLI prints
+     * the right ending. `authz_expired` arrives only on a connection that agreed
+     * it, and the client has already stopped redialling when it fires.
+     */
     readonly onControl?: (kind: ControlKind) => void;
+    /**
+     * The edge refused the dial for this CLI's version. Raw header values: the
+     * caller validates them. The client makes no further dial after this.
+     */
+    readonly onRefused?: (reason: "upgrade_required", minimum: string | undefined, declared: string | undefined) => void;
     /** onOriginError is the creator-facing detail the 502 page must never carry. */
     readonly onOriginError?: (label: string, code: string) => void;
     readonly onStateChange?: (state: TunnelState) => void;
@@ -143,6 +161,27 @@ export interface TunnelClientOptions {
     readonly connect?: (url: string, headers: Record<string, string>) => WebSocket;
 }
 export type TunnelState = "connecting" | "live" | "reconnecting" | "closed";
+/**
+ * What to do with a request's body. `reset` is a disagreement a viewer can
+ * cause, so it ends that stream and never the tunnel.
+ */
+export type BodyPlan = {
+    kind: "none";
+} | {
+    kind: "declared";
+    length: number;
+} | {
+    kind: "chunked";
+} | {
+    kind: "reset";
+};
+/**
+ * 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.
+ */
+export declare function bodyPlan(open: OpenPayload, caps: CapSet): BodyPlan;
 export declare class TunnelClient {
     private readonly opts;
     private ws;
@@ -155,6 +194,8 @@ export declare class TunnelClient {
      * is a credential in a log.
      */
     private resumeToken;
+    /** This connection's agreed set. Fixed at its 101, reset on every dial. */
+    private caps;
     private attempt;
     private closed;
     private state;
@@ -190,6 +231,11 @@ export declare class TunnelClient {
     private dialHeaders;
     private open;
     private onClosed;
+    /**
+     * Close this connection for a violation the edge alone could cause. The
+     * ordinary close path then decides whether to redial.
+     */
+    private protocolViolation;
     private startPing;
     private stopPing;
     private send;