@vincentt-xr/cli 0.18.2 → 0.19.0

package/dist/preview/proxy.js

@@ -138,23 +138,34 @@ export function relayRoute(url, harnessPath, kind) {
 }
 /**
  * Whether the front proxy must answer 404 itself for this app-route URL, so a
- * file-server dev tool serving the repo root cannot hand `/.env`, `/.git/config`
- * or the binding to any holder of a preview link.
+ * file-server dev tool serving the repo root cannot hand `/.env`, `/.git/config`,
+ * the binding or a credential file to any holder of a preview link.
  *
  * The path is decoded once, and an encoded `/` or `\` is refused outright (a
- * separator the dev server would split on and this check would not). A segment
- * still carrying an encoded dot after that one decode is judged as the dev
- * server would read it after a second decode, so `%252eenv` cannot slip past.
- * `.` and `..` segments are always refused, which is what makes the `/@fs/`
- * text containment below real containment.
+ * separator the dev server would split on and this check would not). The query
+ * and fragment may not carry a traversal or a separator either, because some
+ * dev servers resolve a file from a query parameter. A segment still carrying
+ * an encoded character after that one decode is judged as the dev server would
+ * read it after a second decode, so `%252eenv` cannot slip past; a second decode
+ * that throws is done leniently, never treated as "not hidden". `.` and `..`
+ * segments are always refused, which is what makes the `/@fs/` text containment
+ * below real containment.
  *
- * `projectRoot` is the realpath of the binding directory, taken once at preview
- * start; inside-ness is a segment-aligned text prefix, with no disk call.
+ * Three rules read the checked segments: the dot rule (raw name), and the
+ * short-name and credential-name rules (normalized name, see `normalizedName`).
+ *
+ * `projectRoot` is the realpath of the binding directory with forward slashes,
+ * taken once at preview start; inside-ness is a segment-aligned text prefix,
+ * with no disk call.
  */
 export function isHiddenAppPath(url, projectRoot) {
-    const raw = (url.split("#")[0] ?? "").split("?")[0] ?? "";
+    const [beforeHash = "", ...hash] = url.split("#");
+    const [raw = "", ...query] = beforeHash.split("?");
     if (/%(2f|5c)/i.test(raw) || raw.includes("\\"))
         return true;
+    const tail = [...query, ...hash].join("?");
+    if (/%(2f|5c)/i.test(tail) || tail.includes("\\") || tail.includes("/.."))
+        return true;
     let decoded;
     try {
         decoded = decodeURIComponent(raw);
@@ -168,22 +179,93 @@ export function isHiddenAppPath(url, projectRoot) {
     const checked = checkedSegmentIndexes(segments, projectRoot);
     for (const i of checked) {
         const seg = segments[i];
-        if (!startsWithDot(seg))
-            continue;
-        if (isAllowedDotSegment(segments, i))
-            continue;
-        return true;
+        const spellings = [seg, secondDecode(seg)];
+        if (spellings.some((s) => s.startsWith(".")) && !isAllowedDotSegment(segments, i)) {
+            return true;
+        }
+        for (const s of spellings) {
+            const name = normalizedName(s);
+            if (name === REFUSE)
+                return true;
+            if (SHORT_NAME.test(name) || isCredentialName(name))
+                return true;
+        }
     }
     return false;
 }
-function startsWithDot(segment) {
-    if (segment.startsWith("."))
-        return true;
+/** The segment as a second decode would read it; lenient when that decode throws. */
+function secondDecode(segment) {
+    if (!/%[0-9a-f]{2}/i.test(segment))
+        return segment;
     try {
-        return decodeURIComponent(segment).startsWith(".");
+        return decodeURIComponent(segment);
     }
     catch {
-        return false;
+        return segment.replace(/(?:%[0-9a-f]{2})+/gi, (run) => {
+            try {
+                return decodeURIComponent(run);
+            }
+            catch {
+                return run.replace(/%([0-9a-f]{2})/gi, (_, h) => String.fromCharCode(parseInt(h, 16)));
+            }
+        });
+    }
+}
+const REFUSE = Symbol("refuse");
+/**
+ * The name a Windows or case-insensitive file system would open for this
+ * segment: a stream suffix (`:$`) is refused outright, the rest is cut at the
+ * first colon (so `/@fs/C:/...` and `virtual:` modules still work), trailing
+ * dots and spaces are dropped (Windows resolves `server.pem. .` to `server.pem`),
+ * and compatibility and case forms are folded.
+ */
+function normalizedName(segment) {
+    if (segment.includes(":$"))
+        return REFUSE;
+    const beforeColon = segment.split(":")[0] ?? "";
+    return beforeColon.replace(/[. ]+$/, "").normalize("NFKC").toUpperCase().toLowerCase();
+}
+/**
+ * A Windows 8.3 short name (`GIT~1`, `CREDEN~1.JSO`) opens the long-named file
+ * it stands for, and its short form carries no leading dot, so `/GIT~1/config`
+ * would read `.git/config` past the dot rule. Refused on every platform: the
+ * proxy can front a Windows file system from any client.
+ */
+const SHORT_NAME = /^[^~]{1,6}~[0-9]/;
+/** D-Preview-hides-credential-files: hard-coded, no opt-out. `*` is any run of characters. */
+const CREDENTIAL_NAMES = Object.freeze([
+    "credentials.json",
+    "service-account*.json",
+    "*firebase-adminsdk*.json",
+    "*.pem",
+    "*.key",
+    "*.p12",
+    "*.pfx",
+    "*.p8",
+    "*.ppk",
+    "id_rsa*",
+    "id_dsa*",
+    "id_ed25519*",
+    "id_ecdsa*",
+    "*.jks",
+    "*.keystore",
+    "*.env",
+    "*.tfstate",
+    "*.tfvars",
+].map((glob) => new RegExp(`^${glob
+    .split("*")
+    .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+    .join(".*")}$`, "s")));
+/** A listed name, or one with backup endings (`~`, `.bak`) added, any number of times. */
+function isCredentialName(name) {
+    let candidate = name;
+    for (;;) {
+        if (CREDENTIAL_NAMES.some((re) => re.test(candidate)))
+            return true;
+        const stripped = candidate.replace(/(?:~|\.bak)$/, "");
+        if (stripped === candidate)
+            return false;
+        candidate = stripped;
     }
 }
 function checkedSegmentIndexes(segments, projectRoot) {

package/dist/preview/runner.d.ts

@@ -1,9 +1,15 @@
-import { type ControlKind, type TunnelState, type UAClass } from "@vincentt-xr/harness/tunnel";
+import { type ControlKind, type TunnelState, type UAClass } from "../tunnel/index.js";
 import type { DiagEvent } from "@vincentt-xr/harness/events";
 import { type EventTags } from "../relay/server.js";
 import { type ResolvedConfig } from "../shared/config.js";
 /** The path a 404 advisory names: the request's own path, without its query. */
 export declare function requestPathOf(url: string | undefined): string;
+/**
+ * The project root as the `/@fs/` check compares it: Vite writes `/@fs/C:/...`
+ * with forward slashes, so a Windows root holding backslashes would never match
+ * as inside, and a project under a dotted parent folder would get false 404s.
+ */
+export declare function hiddenPathRoot(realRoot: string): string;
 /** Why a preview ended. Each maps to exactly one screen (Flow L20/L21). */
 export type PreviewEndReason = "stopped"
 /**
@@ -57,8 +63,10 @@ export interface StartPreviewOptions {
     /** The API host + PAT. Resolved by the caller so the runner makes no policy. */
     config: ResolvedConfig;
     projectId: string;
-    /** App dev-serve port (default 5173). A server already here is REUSED. */
+    /** App dev-serve port (default 5173). A server already here is REUSED unless `appPortFresh`. */
     appPort?: number;
+    /** appPort was picked for this preview, so the dev command always starts there. */
+    appPortFresh?: boolean;
     relayPort?: number;
     frontPort?: number;
     /** Path routed to the relay instead of the app (default /__harness). */
@@ -136,6 +144,8 @@ export interface RunningPreview {
     /** ISO8601, the hard max. Never extended by a heartbeat. */
     expiresAt: string;
     relayPort: number;
+    /** The relay's `/query` and `feedback/next` secret. Goes only into the 0600 marker. */
+    relayToken: string;
     appPort: number;
     /** Whether the app was responding when we returned. */
     appReady: boolean;

package/dist/preview/runner.js

@@ -16,8 +16,9 @@
 import { spawn, spawnSync } from "node:child_process";
 import { realpath } from "node:fs/promises";
 import { createServer } from "node:http";
-import { TunnelClient, resolveForwardTarget, } from "@vincentt-xr/harness/tunnel";
+import { TunnelClient, resolveForwardTarget, } from "../tunnel/index.js";
 import { startRelay } from "../relay/server.js";
+import { mintRelayToken } from "../relay/guard.js";
 import { isHiddenAppPath, proxyWeb, proxyWs, relayRoute } from "./proxy.js";
 import { getFreePort, isPortListening, waitForApp } from "./net.js";
 import { endPreviewSession, heartbeatPreviewSession, mintPreviewSession, workingTreeKey, PreviewEndedError, } from "./api.js";
@@ -25,19 +26,35 @@ import { withoutCliCredentials } from "../shared/config.js";
 import { ProjectUnreachableError } from "../lib/backend.js";
 import { AuthExpiredError } from "../shared/authError.js";
 import { apiFetch } from "../shared/http.js";
+import { terminalSafe } from "../lib/terminalText.js";
 /** The path a 404 advisory names: the request's own path, without its query. */
 export function requestPathOf(url) {
-    const raw = (url ?? "/").split("?")[0] ?? "/";
-    // Control characters never reach the terminal from a request line.
-    return raw.replace(/[\u0000-\u001f\u007f-\u009f]/g, "");
+    const raw = ((url ?? "/").split("#")[0] ?? "/").split("?")[0] ?? "/";
+    let decoded = raw;
+    try {
+        decoded = decodeURIComponent(raw);
+    }
+    catch {
+        /* an undecodable path is printed as sent */
+    }
+    return terminalSafe(decoded);
+}
+/**
+ * The project root as the `/@fs/` check compares it: Vite writes `/@fs/C:/...`
+ * with forward slashes, so a Windows root holding backslashes would never match
+ * as inside, and a project under a dotted parent folder would get false 404s.
+ */
+export function hiddenPathRoot(realRoot) {
+    return realRoot.replaceAll("\\", "/");
 }
 export async function startPreview(opts) {
     const { projectCwd, projectRoot = projectCwd, config, projectId, harnessPath = "/__harness", devCommand = ["npm", "run", "dev"], appStdio = "ignore", appReadyTimeoutMs = 8_000, onLog = () => undefined, fetchImpl = apiFetch, } = opts;
     const appPort = opts.appPort ?? 5173;
     const relayPort = opts.relayPort ?? (await getFreePort());
     const frontPort = opts.frontPort ?? (await getFreePort());
-    const reuseApp = await isPortListening(appPort);
-    const hiddenRoot = await realpath(projectRoot).catch(() => projectRoot);
+    const reuseApp = opts.appPortFresh ? false : await isPortListening(appPort);
+    const relayToken = mintRelayToken();
+    const hiddenRoot = hiddenPathRoot(await realpath(projectRoot).catch(() => projectRoot));
     let app;
     let killApp;
     let relay;
@@ -136,9 +153,13 @@ export async function startPreview(opts) {
                 process.once("exit", killApp);
             }
         }
+        // Fixed here, from the server-computed URL, and never from a request.
+        const previewOrigin = new URL(minted.url).origin;
         relay = startRelay({
             port: relayPort,
             path: harnessPath,
+            allowedOrigins: [previewOrigin],
+            token: relayToken,
             // Annotations land beside the binding, so `vincentt feedback` finds them
             // from anywhere in the tree rather than only from the folder that started
             // the preview.
@@ -149,8 +170,6 @@ export async function startPreview(opts) {
             onCapReached: opts.onCapReached,
             onAnnotation: opts.onAnnotation,
         });
-        // Fixed here, from the server-computed URL, and never from a request.
-        const previewOrigin = new URL(minted.url).origin;
         front = createServer((req, res) => {
             const route = relayRoute(req.url ?? "/", harnessPath, "http");
             if (route === "refuse") {
@@ -253,6 +272,7 @@ export async function startPreview(opts) {
             sessionId: minted.sessionId,
             expiresAt: minted.expiresAt,
             relayPort,
+            relayToken,
             appPort,
             appReady,
             stop,

package/dist/preview/stream.d.ts

@@ -1,5 +1,5 @@
 import type { DiagEvent, LogEvent, NetworkEvent, TraceEvent } from "@vincentt-xr/harness/events";
-import type { UAClass } from "@vincentt-xr/harness/tunnel";
+import type { UAClass } from "../tunnel/index.js";
 /** One line per viewer per 5s on the terminal. The agent's pull is unthrottled. */
 export declare const PERF_THROTTLE_MS = 5000;
 export declare function uaLabel(c: UAClass): string;

package/dist/preview/viewers.d.ts

@@ -1,4 +1,4 @@
-import type { UAClass } from "@vincentt-xr/harness/tunnel";
+import type { UAClass } from "../tunnel/index.js";
 /** The roster block prints once, on the FOURTH TESTER's arrival, and never again. */
 export declare const ROSTER_AT = 4;
 /**

package/dist/relay/guard.d.ts

@@ -0,0 +1,23 @@
+/** The header carrying the per-session token on the local-only routes. */
+export declare const RELAY_TOKEN_HEADER = "x-vincentt-relay-token";
+export declare function mintRelayToken(): string;
+/**
+ * Host must name the loopback socket the relay bound. A DNS-rebinding page
+ * reaches the same socket under its own hostname, and this is where it stops.
+ */
+export declare function isAllowedHost(raw: string | string[] | undefined, port: number, bindHost?: string): boolean;
+/**
+ * No Origin is a non-browser caller (the CLI, the tunnel's own requests).
+ * Otherwise only an exact configured origin passes, or, when none is
+ * configured, a page served from this machine's loopback. The literal `null`
+ * origin (sandboxed frames, file pages) is a browser and is always refused.
+ */
+export declare function isAllowedOrigin(raw: string | string[] | undefined, allowed: readonly string[] | undefined): boolean;
+export declare function isLoopbackOrigin(raw: string): boolean;
+/**
+ * A cross-site form or `no-cors` fetch can only send `text/plain`, form or
+ * multipart bodies without a preflight. Requiring JSON forces a preflight the
+ * relay never answers.
+ */
+export declare function isJsonContentType(raw: string | undefined): boolean;
+export declare function hasRelayToken(raw: string | string[] | undefined, token: string): boolean;

package/dist/relay/guard.js

@@ -0,0 +1,73 @@
+// The relay's request gate. Every caller the relay serves is on this machine:
+// the CLI (no Origin), the tunnel client and the front proxy (both rewrite Host
+// to the loopback target), and the preview page itself (its own minted origin).
+// A web page the creator happens to have open is none of those, and these checks
+// are what tell it apart.
+import { randomBytes, timingSafeEqual } from "node:crypto";
+/** The header carrying the per-session token on the local-only routes. */
+export const RELAY_TOKEN_HEADER = "x-vincentt-relay-token";
+export function mintRelayToken() {
+    return randomBytes(32).toString("base64url");
+}
+/**
+ * Host must name the loopback socket the relay bound. A DNS-rebinding page
+ * reaches the same socket under its own hostname, and this is where it stops.
+ */
+export function isAllowedHost(raw, port, bindHost = "127.0.0.1") {
+    if (typeof raw !== "string")
+        return false;
+    const host = raw.toLowerCase();
+    const allowed = new Set([`127.0.0.1:${port}`, `localhost:${port}`]);
+    if (bindHost === "::1")
+        allowed.add(`[::1]:${port}`);
+    else
+        allowed.add(`${bindHost.toLowerCase()}:${port}`);
+    return allowed.has(host);
+}
+/**
+ * No Origin is a non-browser caller (the CLI, the tunnel's own requests).
+ * Otherwise only an exact configured origin passes, or, when none is
+ * configured, a page served from this machine's loopback. The literal `null`
+ * origin (sandboxed frames, file pages) is a browser and is always refused.
+ */
+export function isAllowedOrigin(raw, allowed) {
+    if (raw === undefined)
+        return true;
+    if (typeof raw !== "string")
+        return false;
+    if (allowed !== undefined)
+        return allowed.includes(raw);
+    return isLoopbackOrigin(raw);
+}
+export function isLoopbackOrigin(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return false;
+    }
+    if (url.origin !== raw)
+        return false;
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        return false;
+    return ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+}
+/**
+ * A cross-site form or `no-cors` fetch can only send `text/plain`, form or
+ * multipart bodies without a preflight. Requiring JSON forces a preflight the
+ * relay never answers.
+ */
+export function isJsonContentType(raw) {
+    if (raw === undefined)
+        return false;
+    const type = raw.split(";")[0]?.trim().toLowerCase();
+    return type === "application/json";
+}
+export function hasRelayToken(raw, token) {
+    if (typeof raw !== "string")
+        return false;
+    const a = Buffer.from(raw);
+    const b = Buffer.from(token);
+    return a.length === b.length && timingSafeEqual(a, b);
+}

package/dist/relay/server.d.ts

@@ -57,6 +57,19 @@ export interface RelayOptions {
     onAnnotation?: (tags: EventTags) => void;
     /** Injected for tests, so cap behavior is drivable without 64 real clients. */
     testerRegistry?: TesterRegistry;
+    /**
+     * Browser origins allowed on the WebSocket and the annotation POST: the
+     * preview's own minted origin. A request with no Origin (the CLI) always
+     * passes; any other origin is refused. Omitted, only pages served from
+     * loopback pass, which is what a standalone `vincentt relay` serves.
+     */
+    allowedOrigins?: readonly string[];
+    /**
+     * The per-session secret `/query` and `feedback/next` require in
+     * `x-vincentt-relay-token`. The preview always sets it; without it those
+     * routes are still loopback-Host and no-Origin only.
+     */
+    token?: string;
 }
 /** Who produced a batch: the connection's viewer label and its resolved tester. */
 export interface EventTags {

package/dist/relay/server.js

@@ -9,7 +9,8 @@ import { WebSocketServer } from "ws";
 import { EventStore } from "./store.js";
 import { TesterRegistry, isTesterId } from "./testers.js";
 import { AnnotationStore } from "./annotations.js";
-import { VIEWER_LABEL_RE, VIEWER_STAMP_HEADER } from "@vincentt-xr/harness/tunnel";
+import { RELAY_TOKEN_HEADER, hasRelayToken, isAllowedHost, isAllowedOrigin, isJsonContentType, } from "./guard.js";
+import { VIEWER_LABEL_RE, VIEWER_STAMP_HEADER } from "../tunnel/index.js";
 /** Cap an annotation POST body so a bad/huge upload can't exhaust memory. */
 const MAX_ANNOTATION_BYTES = 25 * 1024 * 1024;
 /** Clamp the long-poll hold so a request can't park forever. */
@@ -45,7 +46,17 @@ export function startRelay(opts = {}) {
         }
         return { connections, testers: open.size };
     };
+    const host = opts.host ?? "127.0.0.1";
+    const allowedOrigins = opts.allowedOrigins;
+    const boundPort = () => {
+        const addr = http.address();
+        return typeof addr === "object" && addr !== null ? addr.port : port;
+    };
     const http = createServer((req, res) => handleHttp(req, res, {
+        host,
+        port: boundPort(),
+        allowedOrigins,
+        token: opts.token,
         store,
         annotations,
         testers,
@@ -56,7 +67,23 @@ export function startRelay(opts = {}) {
         onCapReached: opts.onCapReached,
         onAnnotation: opts.onAnnotation,
     }));
-    const wss = new WebSocketServer({ server: http, path: wsPath });
+    const wss = new WebSocketServer({
+        server: http,
+        path: wsPath,
+        verifyClient: ({ req }, done) => {
+            if (!isAllowedHost(req.headers.host, boundPort(), host)) {
+                log("refused a WebSocket with a foreign Host");
+                done(false, 403);
+                return;
+            }
+            if (!isAllowedOrigin(req.headers.origin, allowedOrigins)) {
+                log("refused a WebSocket from a foreign Origin");
+                done(false, 403);
+                return;
+            }
+            done(true);
+        },
+    });
     wss.on("connection", (ws, req) => {
         // The label comes from the CONNECTION, stamped by the tunnel client on this
         // machine after it re-validated the edge's value. It is re-validated ONCE
@@ -117,7 +144,6 @@ export function startRelay(opts = {}) {
         });
         ws.on("close", () => log("client disconnected"));
     });
-    const host = opts.host ?? "127.0.0.1";
     http.listen(port, host, () => log(`relay listening on ${host}:${port} (ws ${wsPath}, http /query)`));
     return {
         store,
@@ -177,6 +203,28 @@ function handleHttp(req, res, ctx) {
         res.writeHead(404).end();
         return;
     }
+    if (!isAllowedHost(req.headers.host, ctx.port, ctx.host)) {
+        ctx.log("refused a request with a foreign Host");
+        res.writeHead(403).end();
+        return;
+    }
+    // The local-only routes have no browser caller at all, so any Origin is foreign.
+    const origins = localOnly ? [] : ctx.allowedOrigins;
+    if (!isAllowedOrigin(req.headers.origin, origins)) {
+        ctx.log("refused a request from a foreign Origin");
+        res.writeHead(403).end();
+        return;
+    }
+    if (localOnly && ctx.token !== undefined) {
+        if (!hasRelayToken(req.headers[RELAY_TOKEN_HEADER], ctx.token)) {
+            res.writeHead(401).end();
+            return;
+        }
+    }
+    if (req.method === "POST" && !isJsonContentType(req.headers["content-type"])) {
+        res.writeHead(415).end();
+        return;
+    }
     if (p === "/query") {
         handleQuery(req, res, url, ctx);
         return;
@@ -191,8 +239,8 @@ function handleHttp(req, res, ctx) {
     }
     res.writeHead(404).end();
 }
-// The MCP server / CLI (same laptop) GETs/POSTs /query with a RelayQuery. Localhost
-// only; no auth in the local dev loop (the platform phase adds it).
+// The CLI (same laptop) GETs/POSTs /query with a RelayQuery, carrying the
+// session token from the 0600 relay marker.
 function handleQuery(req, res, url, ctx) {
     readQuery(req, url)
         .then((q) => {

package/dist/tunnel/cbor.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The CBOR SUBSET, Node half. It mirrors `api/internal/edge/cbor.go` decision
+ * for decision, because two implementations of one wire format that were
+ * written independently are two implementations that drift.
+ *
+ * It decodes CONTROL payloads only — OPEN and HEAD. It NEVER touches a DATA
+ * payload.
+ *
+ * It is hand-written rather than a library for the same reason the Go one is: a
+ * general CBOR library's allocation behavior on hostile input would be someone
+ * else's decision, and the limits below are the whole point.
+ *
+ * Everything indefinite-length, every tag, every float, every byte string and
+ * every negative integer is REFUSED — not because they are dangerous in
+ * 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.
+ */
+/**
+ * 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
+ * that keep viewer-supplied bytes out of the creator's agent's context: the
+ * label flows viewerLabel -> the relay ring-buffer key -> CLI terminal output
+ * and MCP tool output, which is a terminal/log-injection path INTO the agent,
+ * and a Go-only check would pass on a client that trusted the edge.
+ */
+export declare const VIEWER_LABEL_RE: RegExp;
+export declare function parseViewerLabel(s: string): string | null;
+/**
+ * UA_CLASSES is the CLOSED ENUM OF SIX, mirroring the Go edge. `unknown` is the
+ * TOTAL fallback. This client validates the class it receives against this set
+ * before stamping the relay handshake, so an unmatched or forged class becomes
+ * `unknown` rather than an echo.
+ */
+export declare const UA_CLASSES: readonly ["ios_safari", "android_chrome", "desktop_chrome", "desktop_safari", "desktop_firefox", "unknown"];
+export type UAClass = (typeof UA_CLASSES)[number];
+export declare function parseUAClass(s: string): UAClass;
+export interface OpenPayload {
+    viewerLabel: string;
+    method: string;
+    path: string;
+    headers: [string, string][];
+    upgrade?: string;
+}
+export interface HeadPayload {
+    status: number;
+    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.
+ */
+export type ControlKind = "revoke" | "expiring" | "superseded" | "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;
+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.
+ */
+export declare function decodeControl(b: Uint8Array): ControlPayload;
+/** Canonical key order: viewerLabel, method, path, headers, [upgrade]. */
+export declare function encodeOpen(p: OpenPayload): Uint8Array;
+/** Canonical key order: status, headers. */
+export declare function encodeHead(p: HeadPayload): Uint8Array;
+export declare function encodeControl(kind: ControlKind, viewerLabel?: string): Uint8Array;