@vincentt-xr/cli 0.18.3 → 0.19.0

package/dist/tunnel/client.d.ts

@@ -0,0 +1,225 @@
+/**
+ * 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 { WebSocket } from "ws";
+import { encodeCredit } from "./frame.js";
+import { type ControlKind, type UAClass } from "./cbor.js";
+import { type ForwardTarget } from "./forwardTarget.js";
+/**
+ * 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 declare const VIEWER_STAMP_HEADER = "x-vincentt-viewer";
+export declare 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 declare 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 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";
+/**
+ * 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 declare const RESUME_TOKEN_LEN = 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 declare function parseResumeToken(raw: unknown): string | null;
+export interface TunnelClientOptions {
+    /** The edge's tunnel ingress: wss://edge-<env>.vincentt.studio/tunnel. */
+    readonly edgeUrl: string;
+    /**
+     * The opaque JWS the API minted. THE CLIENT NEVER PARSES IT.
+     *
+     * READONLY AND SINGLE-ASSIGNMENT, and that is a design property rather than
+     * style (`D-Client-holds-one-credential-per-state`). It is a FIRST-ATTACH
+     * credential and nothing else: 10-minute TTL, spent by the attach CAS, and
+     * never presented again. Two withdrawn designs needed a mutable grant field so
+     * the client could hold a second, longer-lived grant for the reconnect path;
+     * both were falsified, and the field staying readonly is what makes the
+     * "which credential for which door" question unaskable here.
+     */
+    readonly grant: string;
+    /**
+     * The session id hex from the MINT response, sent as X-Vincentt-Session on
+     * every redial. Not a credential — the reconnect path's two conditions are the
+     * resume token's single-use consume and the tunnel-slot CAS, both enforced by
+     * state at the API.
+     */
+    readonly sessionId: string;
+    readonly target: ForwardTarget;
+    /** onViewer is the CLI's connect line. It receives only VALIDATED values. */
+    readonly onViewer?: (label: string, uaClass: UAClass) => void;
+    /**
+     * onViewerGone is the CLI's disconnect line — the other half of onViewer.
+     *
+     * onViewer fires per OPEN frame (so the roster dedupes by label); this fires
+     * ONCE, when the viewer's connection closes. Without it the roster only ever
+     * grows: for a long time the edge logged the detach server-side and told the
+     * 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. */
+    readonly onControl?: (kind: ControlKind) => 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;
+    /**
+     * onTunnelError carries the error CODE of a failed dial (`ECONNREFUSED`,
+     * `CERT_HAS_EXPIRED`, …). Never the message: an error string from a TLS or
+     * HTTP layer can carry the URL, and the URL is the capability.
+     */
+    readonly onTunnelError?: (code: string) => void;
+    /**
+     * onReconnectRefused fires when the EDGE ANSWERED and refused a reconnect —
+     * a real HTTP status on the upgrade, not a transport failure.
+     *
+     * It exists because a refused reconnect stopped being routine noise: the edge
+     * emits `preview.resume_token_rejected` on it, which QA and security made an
+     * alertable theft signal, and the honest client is not supposed to trigger it.
+     * Without this callback the client retried silently forever and the creator
+     * watched "Reconnecting…" for a session that was already unrecoverable.
+     *
+     * The three statuses are deliberately distinguishable rather than collapsed
+     * (`ingress.go:299-310`): 401 the token was refused, 409 another tunnel holds
+     * this preview, 410 the session is gone. They map to different creator actions.
+     */
+    readonly onReconnectRefused?: (status: number) => void;
+    /** Injectable for tests; never a real socket in a unit test. */
+    readonly connect?: (url: string, headers: Record<string, string>) => WebSocket;
+}
+export type TunnelState = "connecting" | "live" | "reconnecting" | "closed";
+export declare class TunnelClient {
+    private readonly opts;
+    private ws;
+    private decoder;
+    private readonly streams;
+    /**
+     * 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.
+     */
+    private resumeToken;
+    private attempt;
+    private closed;
+    private state;
+    private pingTimer;
+    private lastPong;
+    constructor(opts: TunnelClientOptions);
+    start(): void;
+    close(): void;
+    private setState;
+    /**
+     * 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.
+     */
+    private dialHeaders;
+    private open;
+    private onClosed;
+    private startPing;
+    private stopPing;
+    private send;
+    private onBytes;
+    private dispatch;
+    /**
+     * End a stream on purpose: return any credit owed, RESET it, and tear the
+     * local request down WITHOUT the origin-error advisory, which is reserved for
+     * the creator's dev server actually failing.
+     */
+    private quietReset;
+    /**
+     * 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.
+     */
+    private serveOpen;
+    /**
+     * 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.
+     */
+    private serveUpgrade;
+}
+export { encodeCredit };