@vincentt-xr/harness 1.0.0 → 1.2.0

package/dist/tunnel/client.js

@@ -0,0 +1,620 @@
+/**
+ * The tunnel client: the creator's side of the wire.
+ *
+ * It opens ONE outbound WSS connection to the edge and multiplexes every
+ * viewer's request onto it. Nothing dials INTO the creator's machine; the
+ * client never opens a stream, and the edge rejects an even streamId from it as
+ * a protocol violation.
+ *
+ * What this file does NOT do, deliberately:
+ *   - it does not parse a DATA payload (they are opaque here too);
+ *   - it does not follow a redirect on the creator's behalf;
+ *   - it does not trust the edge's viewerLabel or ua-class without
+ *     re-validating both against the same regex and the same closed enum.
+ */
+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, TUNNEL_PING_INTERVAL_MS, TUNNEL_PING_TIMEOUT_MS, decodeCredit, encodeCredit, encodeFrame, } from "./frame.js";
+import { decodeControl, decodeOpen, encodeHead, parseUAClass, parseViewerLabel, } from "./cbor.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;
+const BACKOFF_MAX_MS = 8_000;
+/**
+ * The dial statuses no retry can fix, so the client stops rather than looping.
+ *
+ *   401  the resume token was refused (consumed, expired, or the spend window
+ *        is shut) — `preview.resume_token_rejected` fired at the edge
+ *   409  another tunnel holds this preview, or the grace cap is spent
+ *   410  the session is gone
+ *
+ * A 503 is deliberately ABSENT: it is the edge's admission refusal
+ * (`ingress.go:152-156`, the 2001st session) and it is genuinely transient, so
+ * it keeps the backoff. Treating it as terminal would kill a healthy preview
+ * over a momentarily full edge.
+ */
+const TERMINAL_DIAL_STATUS = new Set([401, 409, 410]);
+/**
+ * VIEWER_STAMP_HEADER carries the VALIDATED label to the creator's own local
+ * server, so the relay can key its ring buffer by viewer.
+ *
+ * The stamp happens HERE, on the creator's side of the wire, which is the whole
+ * point of 2.8: the device never chooses its own label, and the value written
+ * has already passed parseViewerLabel. It is added AFTER sanitizeHeaders, so a
+ * viewer-supplied header of the same name cannot survive to shadow it.
+ */
+export const VIEWER_STAMP_HEADER = "x-vincentt-viewer";
+export const UA_CLASS_STAMP_HEADER = "x-vincentt-ua-class";
+/**
+ * RESUME_HEADER is ONE spelling for both halves of the wire: the edge writes it
+ * on the 101 (`ResumeHeader` in `internal/edge/websocket.go`), and this client
+ * sends it back on the next dial.
+ *
+ * It is lower-case here because Node lower-cases every response header name,
+ * and `res.headers["X-Vincentt-Resume"]` is silently `undefined`. That mistake
+ * would reproduce the exact defect this constant exists to fix — a client that
+ * never learns its next credential — with a fully green suite, so the casing is
+ * asserted by a test rather than trusted.
+ */
+export const RESUME_HEADER = "x-vincentt-resume";
+/**
+ * SESSION_HEADER carries the sessionId hex on the RECONNECT dial only.
+ *
+ * It exists because the reconnect path carries NO GRANT
+ * (`D-The-reconnect-path-carries-no-grant`), and the grant is what used to carry
+ * the session id in its signed `sid` claim. With the grant gone the edge has no
+ * other way to name the row, so the id travels as its own header.
+ *
+ * It is NOT a secret — it is an ObjectID the edge immediately parses with
+ * `primitive.ObjectIDFromHex` before it touches anything (`ingress.go:288`) —
+ * but exactly one must be sent: the edge refuses duplicates on all three
+ * credential-bearing headers with `Header.Values()` rather than `Get`, because
+ * `Get` silently returns the first value and that is the bypass being closed
+ * (`ingress.go:120-126`).
+ *
+ * Lower-case for the same reason as RESUME_HEADER: Node normalizes header names.
+ */
+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";
+/**
+ * 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
+ * fact rather than each carrying a magic number.
+ */
+export const RESUME_TOKEN_LEN = 43;
+const RESUME_TOKEN_RE = /^[A-Za-z0-9_-]{43}$/;
+/**
+ * parseResumeToken accepts only the grammar the API's issuer produces.
+ *
+ * ABSENCE IS LEGITIMATE, not an error: the edge OMITS the header rather than
+ * emitting it empty when it has no token to hand over, and the handshake still
+ * succeeds. The cost is one reconnect, which is recoverable — treating it as
+ * fatal would turn a token problem into a dead preview.
+ *
+ * A malformed value is discarded for the same reason it is validated at the
+ * edge before being written: this value is concatenated into an outbound header
+ * on the next dial, and a CR or LF in it would not be a bad credential, it
+ * would be a second request.
+ */
+export function parseResumeToken(raw) {
+    if (typeof raw !== "string")
+        return null;
+    return RESUME_TOKEN_RE.test(raw) ? raw : null;
+}
+export class TunnelClient {
+    opts;
+    ws = null;
+    decoder = new FrameDecoder(true);
+    streams = new Map();
+    /**
+     * resumeToken is 32 random bytes, single-use, rotated on every attach, bound
+     * to the session, 5-minute TTL. It is held in memory only and NEVER logged:
+     * "single-use" is enforced by the API's atomic consume, and a token in a log
+     * is a credential in a log.
+     */
+    resumeToken = null;
+    attempt = 0;
+    closed = false;
+    state = "connecting";
+    pingTimer = null;
+    lastPong = Date.now();
+    constructor(opts) {
+        this.opts = opts;
+    }
+    start() {
+        this.closed = false;
+        this.open();
+    }
+    close() {
+        this.closed = true;
+        this.setState("closed");
+        this.stopPing();
+        this.ws?.close();
+        this.ws = null;
+    }
+    setState(s) {
+        if (this.state === s)
+            return;
+        this.state = s;
+        this.opts.onStateChange?.(s);
+    }
+    /**
+     * THE DIAL RULE. One boolean, two disjoint states, one credential each.
+     *
+     *   first dial   (resumeToken === null):  Authorization: Bearer <mint grant>
+     *   every redial (resumeToken !== null):  X-Vincentt-Resume + X-Vincentt-Session
+     *
+     * This function is the WIRING of `D-Client-holds-one-credential-per-state`:
+     * every dial's header set is built here and nowhere else, so the never-send-both
+     * rule is a property of one `if/else` rather than of a convention.
+     *
+     * NEVER BOTH, and this is the rule most likely to be "helpfully" broken later.
+     * The edge REFUSES a request carrying a grant alongside a valid resume token
+     * (`ingress.go:144-148`) — it does not ignore the grant — so adding
+     * `Authorization` here "for robustness" would break every reconnect while
+     * passing every functional test in the suite except the negative that exists
+     * for exactly this. The reason it is a refusal rather than a preference: a
+     * header that is sometimes meaningful and sometimes ignored is a branch waiting
+     * to be written.
+     *
+     * There is no per-door judgement to get wrong because the states are disjoint:
+     * the grant is spent by the attach CAS the moment the first dial succeeds, and
+     * a resume token only ever exists after a 101 has delivered one.
+     */
+    dialHeaders() {
+        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}` };
+        }
+        // RECONNECT. The resume pair, and no Authorization header at all.
+        return {
+            [RESUME_HEADER]: this.resumeToken,
+            [SESSION_HEADER]: this.opts.sessionId,
+        };
+    }
+    open() {
+        const headers = this.dialHeaders();
+        const ws = this.opts.connect
+            ? this.opts.connect(this.opts.edgeUrl, headers)
+            : new WebSocket(this.opts.edgeUrl, { headers, maxPayload: MAX_FRAME_LEN + 64 });
+        this.ws = ws;
+        this.decoder = new FrameDecoder(true);
+        // `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
+        // inverts into an accelerating storm against the platform's only
+        // unauthenticated listener. Observed against a real edge, not theorised.
+        const closeOnce = () => this.onClosed(ws);
+        /**
+         * THE ROTATION. `ws` hands us the raw 101 here, which is the only place the
+         * edge's next resume token is available.
+         *
+         * Without this assignment the field stayed `null` forever, the request
+         * header above was never sent, and every reconnect presented its
+         * already-consumed single-use grant — so the edge refused it at grant
+         * verification and `/reattached` was never reached. Both repos' suites
+         * stayed green across that gap for the whole build, because each asserted
+         * its own half: the Go side that `/reattached` works when a token arrives,
+         * this side that the header is sent when the field is set. Nothing asserted
+         * that the field is ever ASSIGNED.
+         */
+        ws.on("upgrade", (res) => {
+            const next = parseResumeToken(res.headers[RESUME_HEADER]);
+            // A missing or malformed token leaves the PREVIOUS one in place rather
+            // than clearing it: the old token is already spent after a successful
+            // attach, but keeping it costs nothing and dropping a good one because a
+            // later handshake omitted the header would forfeit a working reconnect.
+            if (next !== null)
+                this.resumeToken = next;
+        });
+        /**
+         * A REFUSED RECONNECT — the edge answered with a status instead of a 101.
+         *
+         * This is a REAL SIGNAL, not routine noise. The edge emits
+         * `preview.resume_token_rejected` here, which QA and security made an
+         * alertable theft detector, and an honest client is not supposed to fire it.
+         * Retrying silently forever against a 401/409/410 both buries that signal
+         * under the client's own backoff and leaves the creator watching
+         * "Reconnecting…" for a preview that can never come back.
+         *
+         * The statuses are NOT collapsed, because the creator's action differs:
+         * 409 means another tunnel holds this preview, 410 means it is gone.
+         *
+         * REGISTERING THIS LISTENER CHANGES `ws`'s BEHAVIOUR, which is why the
+         * retry is scheduled here explicitly. With no `unexpected-response` handler
+         * `ws` emits `error` and the close path below schedules the next dial; with
+         * one, it emits NEITHER `error` NOR `close` and hands the response over
+         * instead. Adding this handler without the `closeOnce()` below therefore
+         * silently kills the backoff for EVERY non-101 status — including the
+         * transient ones — which is a worse failure than the one it fixes, and it
+         * was caught by asserting the dial COUNT rather than the callback.
+         */
+        ws.on("unexpected-response", (_req, res) => {
+            const status = res.statusCode ?? 0;
+            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
+            // one theft signal into an unbounded stream of them.
+            if (TERMINAL_DIAL_STATUS.has(status))
+                this.closed = true;
+            res.destroy?.();
+            // A transient status (503 admission refusal, 502) still gets the
+            // backoff; a terminal one lands on the `this.closed` guard inside.
+            closeOnce();
+        });
+        ws.on("open", () => {
+            this.attempt = 0;
+            this.lastPong = Date.now();
+            this.setState("live");
+            this.startPing();
+        });
+        ws.on("message", (data) => this.onBytes(new Uint8Array(data)));
+        ws.on("close", closeOnce);
+        ws.on("error", (err) => {
+            // The CODE only, never the message or the stack: an error string from a
+            // TLS or HTTP layer can carry a URL, and this URL is the capability.
+            //
+            // It is surfaced at all because a tunnel that cannot re-establish
+            // otherwise produces NOTHING — not for the creator, not for triage. That
+            // silence cost a full rig investigation: "the client stopped dialling"
+            // with no reason attached is the least actionable failure in the feature.
+            this.opts.onTunnelError?.(err.code ?? "tunnel_error");
+            closeOnce();
+        });
+    }
+    onClosed(ws) {
+        // A late event from a socket we have already replaced must not schedule a
+        // second retry, nor tear down the stream table of its successor.
+        if (this.ws !== ws)
+            return;
+        this.stopPing();
+        // Streams do NOT survive a reconnect: in-flight requests are RESET and the
+        // browser retries. That is the correct trade — an AR page reload is already
+        // the accepted cost of this loop.
+        for (const s of this.streams.values())
+            s.abort?.();
+        this.streams.clear();
+        this.ws = null;
+        if (this.closed)
+            return;
+        this.setState("reconnecting");
+        // 0.5s -> 8s with jitter.
+        const base = Math.min(BACKOFF_BASE_MS * 2 ** this.attempt, BACKOFF_MAX_MS);
+        const delay = base / 2 + Math.random() * (base / 2);
+        this.attempt++;
+        setTimeout(() => {
+            if (!this.closed)
+                this.open();
+        }, delay);
+    }
+    startPing() {
+        this.stopPing();
+        this.pingTimer = setInterval(() => {
+            if (Date.now() - this.lastPong > TUNNEL_PING_TIMEOUT_MS) {
+                // A dead tunnel is detected BEFORE the edge's grace window opens.
+                this.ws?.terminate?.();
+                return;
+            }
+            this.send(FrameType.PING, 0);
+        }, TUNNEL_PING_INTERVAL_MS);
+    }
+    stopPing() {
+        if (this.pingTimer !== null)
+            clearInterval(this.pingTimer);
+        this.pingTimer = null;
+    }
+    send(type, streamId, payload) {
+        const ws = this.ws;
+        if (ws === null || ws.readyState !== WebSocket.OPEN)
+            return;
+        try {
+            ws.send(encodeFrame(type, streamId, payload));
+        }
+        catch {
+            // An encode refusal is our own bug, not the peer's. Drop the frame rather
+            // than crashing the tunnel; the stream's idle timeout collects it.
+        }
+    }
+    onBytes(chunk) {
+        let frames;
+        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;
+            }
+            this.ws?.close();
+            return;
+        }
+        for (const f of frames)
+            this.dispatch(f.type, f.streamId, f.payload);
+    }
+    dispatch(type, streamId, payload) {
+        switch (type) {
+            case FrameType.PING:
+                this.send(FrameType.PONG, 0);
+                return;
+            case FrameType.PONG:
+                this.lastPong = Date.now();
+                return;
+            case FrameType.CONTROL: {
+                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);
+                    }
+                }
+                catch {
+                    // A malformed CONTROL is a stream-level fault on stream 0, which
+                    // means it is simply ignored rather than killing a live tunnel.
+                }
+                return;
+            }
+            case FrameType.OPEN: {
+                let open;
+                try {
+                    open = decodeOpen(payload);
+                }
+                catch {
+                    this.send(FrameType.RESET, streamId, new Uint8Array([ResetReason.PROTOCOL_ERROR]));
+                    return;
+                }
+                void this.serveOpen(streamId, open);
+                return;
+            }
+            case FrameType.DATA: {
+                const s = this.streams.get(streamId);
+                if (s === undefined) {
+                    this.send(FrameType.RESET, streamId, new Uint8Array([ResetReason.STREAM_CLOSED]));
+                    return;
+                }
+                // OPAQUE. Written straight through to the local server; nothing here
+                // reads it, branches on it, or keeps it.
+                s.writeBody?.(payload);
+                return;
+            }
+            case FrameType.END: {
+                const s = this.streams.get(streamId);
+                if (s === undefined)
+                    return;
+                if (payload.length === 3) {
+                    // A credit replenishment for bytes we sent.
+                    s.credit = Math.min(s.credit + decodeCredit(payload), MAX_FRAME_LEN);
+                    const w = s.waiters.shift();
+                    w?.();
+                    return;
+                }
+                s.ended = true;
+                return;
+            }
+            case FrameType.RESET:
+                this.streams.get(streamId)?.abort?.();
+                this.streams.delete(streamId);
+                return;
+        }
+    }
+    /**
+     * serveOpen forwards ONE viewer request to the single configured target.
+     *
+     * Every 2.15.4 rule executes here, in order: the target is the configured one
+     * (never from the request), the request target is normalized-then-checked,
+     * the viewer's routing headers are dropped, loopback is RE-CHECKED at connect,
+     * and no redirect is followed.
+     */
+    async serveOpen(streamId, open) {
+        // RE-VALIDATE the label and the class before either reaches the relay
+        // handshake. This is the second of three closures, and a Go-only check
+        // would pass on a client that trusted the edge.
+        const label = parseViewerLabel(open.viewerLabel);
+        if (label === null) {
+            this.send(FrameType.RESET, streamId, new Uint8Array([ResetReason.PROTOCOL_ERROR]));
+            return;
+        }
+        const uaClass = parseUAClass(open.headers.find(([k]) => k.toLowerCase() === "x-vincentt-ua-class")?.[1] ??
+            "unknown");
+        this.opts.onViewer?.(label, uaClass);
+        let path;
+        try {
+            path = normalizeRequestTarget(open.path);
+            await assertStillLoopback(this.opts.target);
+        }
+        catch (err) {
+            const code = err instanceof ForwardTargetError ? err.code : "invalid_target";
+            // The DETAIL goes to the creator's terminal, which is the only safe place
+            // for it and the place the person who can fix it is already looking. The
+            // viewer gets the edge's fixed 502.
+            this.opts.onOriginError?.(label, code);
+            this.send(FrameType.RESET, streamId, new Uint8Array([ResetReason.PROTOCOL_ERROR]));
+            return;
+        }
+        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]);
+        const stream = {
+            id: streamId,
+            label,
+            credit: MAX_FRAME_LEN,
+            waiters: [],
+            ended: false,
+        };
+        this.streams.set(streamId, stream);
+        if (open.upgrade !== undefined) {
+            // `upgrade` is CARRIED, NOT INTERPRETED, by the protocol — but the local
+            // hop still has to BE an upgrade, or the diagnostics WebSocket for
+            // /__harness never establishes and the whole diagnostics half of the
+            // feature is dead. The bytes stay opaque on both sides of this splice.
+            this.serveUpgrade(streamId, stream, open, path, headers);
+            return;
+        }
+        const req = httpRequest({
+            host: this.opts.target.address,
+            port: this.opts.target.port,
+            method: open.method,
+            path,
+            headers: Object.fromEntries(headers),
+            // The BROWSER follows a redirect, on the viewer's own origin. There is
+            // no option to change this.
+            ...(FOLLOW_REDIRECTS ? {} : {}),
+        }, (res) => {
+            const respHeaders = [];
+            for (const [k, v] of Object.entries(res.headers)) {
+                if (v === undefined)
+                    continue;
+                for (const one of Array.isArray(v) ? v : [v])
+                    respHeaders.push([k, one]);
+            }
+            try {
+                this.send(FrameType.HEAD, streamId, encodeHead({ status: res.statusCode ?? 502, headers: respHeaders }));
+            }
+            catch {
+                this.send(FrameType.RESET, streamId, new Uint8Array([ResetReason.PROTOCOL_ERROR]));
+                res.destroy();
+                return;
+            }
+            res.on("data", (chunk) => {
+                // Chunked at MAX_FRAME_LEN so one frame can never exceed the window.
+                for (let off = 0; off < chunk.length; off += RELAY_BUF_SIZE) {
+                    this.send(FrameType.DATA, streamId, new Uint8Array(chunk.subarray(off, Math.min(off + RELAY_BUF_SIZE, chunk.length))));
+                }
+            });
+            res.on("end", () => {
+                this.send(FrameType.END, streamId);
+                this.streams.delete(streamId);
+            });
+        });
+        stream.abort = () => req.destroy();
+        stream.writeBody = (b) => {
+            req.write(b);
+            // Replenish the edge's window on DRAIN — the write returned, so the local
+            // server has taken the bytes.
+            this.send(FrameType.END, streamId, encodeCredit(b.length));
+        };
+        req.on("error", (e) => {
+            // The creator's dev server is down. The code goes to THEIR terminal; the
+            // viewer gets a fixed 502 generated by the edge with no upstream detail.
+            this.opts.onOriginError?.(label, e.code ?? "origin_error");
+            this.send(FrameType.RESET, streamId, new Uint8Array([ResetReason.PROTOCOL_ERROR]));
+            this.streams.delete(streamId);
+        });
+        req.end();
+    }
+    /**
+     * serveUpgrade splices ONE viewer's WebSocket to the creator's local server.
+     *
+     * It re-issues the handshake over a raw socket rather than using an HTTP
+     * client, because Node's `http` module owns the connection after a 101 and
+     * will not hand back a usable duplex without the same hijack this does
+     * explicitly. The response's status line and headers are parsed only far
+     * enough to build the HEAD frame; every byte after the blank line is OPAQUE
+     * and is forwarded without being read.
+     */
+    serveUpgrade(streamId, stream, open, path, headers) {
+        const sock = netConnect(this.opts.target.port, this.opts.target.address);
+        let handshakeDone = false;
+        let buffered = Buffer.alloc(0);
+        stream.abort = () => sock.destroy();
+        stream.writeBody = (b) => {
+            sock.write(b);
+            this.send(FrameType.END, streamId, encodeCredit(b.length));
+        };
+        sock.on("connect", () => {
+            const lines = [`${open.method} ${path} HTTP/1.1`];
+            for (const [k, v] of headers)
+                lines.push(`${k}: ${v}`);
+            // The hop-by-hop pair sanitizeHeaders dropped has to be reinstated here,
+            // because on THIS hop the upgrade is real rather than relayed.
+            lines.push(`Upgrade: ${open.upgrade ?? "websocket"}`, "Connection: Upgrade", "", "");
+            sock.write(lines.join("\r\n"));
+        });
+        sock.on("data", (chunk) => {
+            if (handshakeDone) {
+                for (let off = 0; off < chunk.length; off += RELAY_BUF_SIZE) {
+                    this.send(FrameType.DATA, streamId, new Uint8Array(chunk.subarray(off, Math.min(off + RELAY_BUF_SIZE, chunk.length))));
+                }
+                return;
+            }
+            buffered = Buffer.concat([buffered, chunk]);
+            const end = buffered.indexOf("\r\n\r\n");
+            if (end === -1) {
+                // A response head larger than one control payload is not a handshake
+                // this client will complete; refusing bounds the buffer.
+                if (buffered.length > MAX_FRAME_LEN) {
+                    this.send(FrameType.RESET, streamId, new Uint8Array([ResetReason.PROTOCOL_ERROR]));
+                    sock.destroy();
+                }
+                return;
+            }
+            const head = parseResponseHead(buffered.subarray(0, end).toString("latin1"));
+            if (head === null) {
+                this.send(FrameType.RESET, streamId, new Uint8Array([ResetReason.PROTOCOL_ERROR]));
+                sock.destroy();
+                return;
+            }
+            handshakeDone = true;
+            try {
+                this.send(FrameType.HEAD, streamId, encodeHead(head));
+            }
+            catch {
+                this.send(FrameType.RESET, streamId, new Uint8Array([ResetReason.PROTOCOL_ERROR]));
+                sock.destroy();
+                return;
+            }
+            const rest = buffered.subarray(end + 4);
+            buffered = Buffer.alloc(0);
+            for (let off = 0; off < rest.length; off += RELAY_BUF_SIZE) {
+                this.send(FrameType.DATA, streamId, new Uint8Array(rest.subarray(off, Math.min(off + RELAY_BUF_SIZE, rest.length))));
+            }
+        });
+        sock.on("error", (e) => {
+            this.opts.onOriginError?.(stream.label, e.code ?? "origin_error");
+            this.send(FrameType.RESET, streamId, new Uint8Array([ResetReason.PROTOCOL_ERROR]));
+            this.streams.delete(streamId);
+        });
+        sock.on("close", () => {
+            this.send(FrameType.END, streamId);
+            this.streams.delete(streamId);
+        });
+    }
+}
+/**
+ * parseResponseHead reads a status line and headers. It returns null rather
+ * than throwing on anything it does not recognise, because the caller's only
+ * response is a RESET either way and an exception here would carry the
+ * creator's server's bytes into a stack trace.
+ */
+function parseResponseHead(raw) {
+    const lines = raw.split("\r\n");
+    const statusLine = lines[0] ?? "";
+    const m = /^HTTP\/1\.[01] (\d{3})/.exec(statusLine);
+    if (m === null)
+        return null;
+    const status = Number(m[1]);
+    if (status < 100 || status > 599)
+        return null;
+    const headers = [];
+    for (const line of lines.slice(1)) {
+        const i = line.indexOf(":");
+        if (i <= 0)
+            continue;
+        headers.push([line.slice(0, i).trim(), line.slice(i + 1).trim()]);
+    }
+    return { status, headers };
+}
+export { encodeCredit };

package/dist/tunnel/forwardTarget.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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.
+ */
+export declare class ForwardTargetError extends Error {
+    readonly code: ForwardTargetErrorCode;
+    constructor(code: ForwardTargetErrorCode);
+}
+export type ForwardTargetErrorCode = "absolute_form_target" | "path_traversal" | "non_loopback_target" | "invalid_target";
+export interface ForwardTarget {
+    readonly host: string;
+    readonly port: number;
+    /** The resolved address asserted at start. Re-checked at connect. */
+    readonly address: string;
+}
+/**
+ * Resolver is the DNS seam. It is injectable so a unit test can drive the
+ * rebind case — the same name resolving to loopback at start and to a public
+ * address at connect — which is the whole point of rule 5's re-check and is
+ * unreachable against the real resolver.
+ */
+export type Resolver = (host: string) => Promise<string>;
+/**
+ * resolveForwardTarget captures the ONE configured target at
+ * `vincentt preview` start, from the creator's own flag or config — NEVER from
+ * a request.
+ */
+export declare function resolveForwardTarget(host: string, port: number, resolve?: Resolver): Promise<ForwardTarget>;
+/**
+ * assertStillLoopback is the CONNECT-TIME re-check. Resolving once at start and
+ * trusting it forever is exactly the window a DNS rebind uses.
+ */
+export declare function assertStillLoopback(t: ForwardTarget, resolve?: Resolver): Promise<void>;
+/**
+ * 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 declare function normalizeRequestTarget(target: string): string;
+/**
+ * sanitizeHeaders drops the viewer's routing headers and every hop-by-hop
+ * header, and substitutes the client's own Host.
+ */
+export declare function sanitizeHeaders(headers: [string, string][], target: ForwardTarget): [string, string][];
+/**
+ * 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 declare const FOLLOW_REDIRECTS: false;