@vincentt-xr/cli 0.18.2 → 0.18.3

package/MIGRATION.md

@@ -3,6 +3,14 @@
 Per version, newest first. Read by the platform's own version surface and served to
 creators' agents. Accurate or absent, never speculative (B-F5-2).
 
+## 0.18.3
+
+required: false
+No action required when the preview and the commands reading it (`logs`, `feedback`, `preview --stop`) come from the same CLI version. Behaviour that changed:
+- The local preview relay refuses web pages other than the preview itself. It answers only requests whose Host is `127.0.0.1:<port>` or `localhost:<port>`, accepts the diagnostics socket and feedback posts only from the preview's own address (or from a client that sends no Origin), and refuses a POST that is not `application/json` with 415.
+- The relay's diagnostics read and feedback long-poll now require a per-session token, which the preview writes to `.vincentt/relay.json` (now readable by the owner only). The CLI's own commands send it; a direct request to `/query` or `feedback/next` without the `x-vincentt-relay-token` header is refused with 401. A command from CLI 0.18.2 or older cannot read a preview started by this version, and the reverse still works.
+- `vincentt relay` prints the token it requires and accepts `--origin <url>` for a page it should accept; without it, only pages served from localhost or 127.0.0.1 can connect.
+
 ## 0.18.2
 
 required: false

package/dist/cli/index.js

@@ -727,7 +727,7 @@ async function followPreview(info, ui, filterTester, filterViewer) {
         console.log("✓ Following this preview");
     }
     console.log("");
-    const relay = httpRelayClient(`http://127.0.0.1:${info.relayPort}`);
+    const relay = httpRelayClient(`http://127.0.0.1:${info.relayPort}`, info.token);
     let since = -1;
     let warnedMissing = false;
     let stop = false;
@@ -1357,13 +1357,19 @@ async function domain() {
 // ---- servers ----------------------------------------------------------------
 async function relay() {
     const { startRelay } = await import("../relay/server.js");
+    const { mintRelayToken, RELAY_TOKEN_HEADER } = await import("../relay/guard.js");
     const port = numFlag("--port") ?? 7331;
     const dir = flag("--dir");
+    const origin = flag("--origin");
+    const token = mintRelayToken();
     startRelay({
         port,
         projectDir: dir ? path.resolve(dir) : undefined,
+        allowedOrigins: origin ? [origin] : undefined,
+        token,
         onLog: (m) => console.log(`[relay] ${m}`),
     });
+    console.log(`[relay] /query and feedback/next require ${RELAY_TOKEN_HEADER}: ${token}`);
 }
 // ---- dispatch ---------------------------------------------------------------
 export function usage() {

package/dist/lib/diagnostics.d.ts

@@ -1,9 +1,10 @@
 import type { DiagEvent, LogEvent, NetworkEvent, RelayQuery, RelayResult, TraceEvent } from "@vincentt-xr/harness/events";
+export declare function relayAuthHeaders(token: string | undefined): Record<string, string>;
 export interface RelayClient {
     query(q: RelayQuery): Promise<RelayResult>;
 }
 /** A RelayClient backed by the relay's HTTP /query endpoint. */
-export declare function httpRelayClient(baseUrl: string): RelayClient;
+export declare function httpRelayClient(baseUrl: string, token?: string): RelayClient;
 export declare function formatLog(e: LogEvent, now: number): string;
 export declare function formatNetwork(e: NetworkEvent, now: number): string;
 export declare function formatTrace(e: TraceEvent, now: number): string;

package/dist/lib/diagnostics.js

@@ -2,13 +2,17 @@
 // the relay and format them into the compact text an agent reads. Kept separate
 // from the SDK wiring (server.ts) so the formatting is unit-testable and the SDK
 // version can churn without touching this.
+import { RELAY_TOKEN_HEADER } from "../relay/guard.js";
+export function relayAuthHeaders(token) {
+    return token === undefined ? {} : { [RELAY_TOKEN_HEADER]: token };
+}
 /** A RelayClient backed by the relay's HTTP /query endpoint. */
-export function httpRelayClient(baseUrl) {
+export function httpRelayClient(baseUrl, token) {
     return {
         async query(q) {
             const res = await fetch(`${baseUrl}/query`, {
                 method: "POST",
-                headers: { "content-type": "application/json" },
+                headers: { "content-type": "application/json", ...relayAuthHeaders(token) },
                 body: JSON.stringify(q),
             });
             if (!res.ok)

package/dist/lib/feedback.js

@@ -11,6 +11,7 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { isProcessAlive, isRelayResponding, readRelayInfo, relayInfoDir, } from "./relayInfo.js";
+import { relayAuthHeaders } from "./diagnostics.js";
 const CURSOR_FILE = ".vincentt/annotations/offset";
 /**
  * A cursor that reads too LOW re-delivers, which is the accepted cost of
@@ -96,13 +97,13 @@ export async function fetchNext(cwd, opts) {
     u.searchParams.set("timeout", String(opts.timeoutMs));
     let res;
     try {
-        res = await fetch(u);
+        res = await fetch(u, { headers: relayAuthHeaders(info.token) });
     }
     catch {
         // The socket died under us. The pid gate + relay-identity probe is what
         // separates "the preview ended" from "the request failed but a relay is
         // still there" — only the latter is a fault worth an exit 1.
-        if (await relayGone(info.pid, info.relayPort)) {
+        if (await relayGone(info.pid, info.relayPort, info.token)) {
             return { kind: "closed", reason: "unreachable" };
         }
         throw new Error(`Could not reach the preview relay on :${info.relayPort}. The relay is answering, so this is not a session end.`);
@@ -117,8 +118,8 @@ export async function fetchNext(cwd, opts) {
         throw new Error(`relay feedback/next returned ${res.status}`);
     return { kind: "annotation", annotation: (await res.json()) };
 }
-async function relayGone(pid, port) {
+async function relayGone(pid, port, token) {
     if (pid !== undefined && !isProcessAlive(pid))
         return true;
-    return !(await isRelayResponding(port));
+    return !(await isRelayResponding(port, undefined, undefined, token));
 }

package/dist/lib/lifecycle.js

@@ -175,6 +175,7 @@ export async function previewStart(projectCwd, onLog, extra = {}) {
         harnessPath: "/__harness",
         expiresAt: preview.expiresAt,
         pidStartTime: await readProcessStartTime(process.pid),
+        token: preview.relayToken,
     });
     return { preview, started: true };
 }
@@ -286,7 +287,7 @@ export async function previewStopSignal(projectCwd, deps = {}) {
         // relay's own teardown and print a number that was true of a preview which
         // no longer exists. A dead pid is never queried at all — the marker is stale
         // and there is nothing on that port to ask.
-        const relay = deps.relay ?? httpRelayClient(`http://127.0.0.1:${info.relayPort}`);
+        const relay = deps.relay ?? httpRelayClient(`http://127.0.0.1:${info.relayPort}`, info.token);
         const connected = await readLiveConnections(relay);
         try {
             (deps.kill ?? ((pid, sig) => process.kill(pid, sig)))(info.pid, "SIGTERM");
@@ -333,7 +334,7 @@ async function relayForProject(projectCwd, override) {
         throw new Error("No running preview for this project. Run `vincentt preview` first.");
     }
     // The relay listens on 127.0.0.1 only; `localhost` may resolve to ::1 first.
-    return httpRelayClient(`http://127.0.0.1:${info.relayPort}`);
+    return httpRelayClient(`http://127.0.0.1:${info.relayPort}`, info.token);
 }
 /** Raw diagnostics query against the running relay (used by CLI --json). */
 export async function diagQuery(projectCwd, kind, opts = {}, relay) {

package/dist/lib/relayInfo.d.ts

@@ -24,6 +24,12 @@ export interface RelayInfo {
      * written by an older CLI or on a platform with no reader.
      */
     pidStartTime?: string;
+    /**
+     * The relay's per-session secret for `/query` and `feedback/next`. The marker
+     * is written 0600 because of it. Absent from markers written by an older CLI,
+     * whose relay asks for none.
+     */
+    token?: string;
 }
 export declare function relayInfoPath(cwd: string): string;
 /**
@@ -64,7 +70,7 @@ export declare function isProcessAlive(pid: number): boolean;
  * runs fifty times a day, and the fallback (mint a preview) is what they asked
  * for anyway.
  */
-export declare function isRelayResponding(port: number, timeoutMs?: number, fetchImpl?: typeof fetch): Promise<boolean>;
+export declare function isRelayResponding(port: number, timeoutMs?: number, fetchImpl?: typeof fetch, token?: string): Promise<boolean>;
 /**
  * readLivePreview returns the marker ONLY when it still describes a preview that
  * is genuinely running, and CLEARS it otherwise.
@@ -81,5 +87,5 @@ export declare function isRelayResponding(port: number, timeoutMs?: number, fetc
  */
 export declare function readLivePreview(cwd: string, deps?: {
     processAlive?: (pid: number) => boolean;
-    relayResponding?: (port: number) => Promise<boolean>;
+    relayResponding?: (port: number, token?: string) => Promise<boolean>;
 }): Promise<RelayInfo | undefined>;

package/dist/lib/relayInfo.js

@@ -5,6 +5,7 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { locateProjectBinding } from "../shared/config.js";
+import { relayAuthHeaders } from "./diagnostics.js";
 const RELAY_INFO_FILE = "relay.json";
 const VINCENTT_DIR = ".vincentt";
 export function relayInfoPath(cwd) {
@@ -28,7 +29,15 @@ export async function relayInfoDir(cwd) {
 export async function writeRelayInfo(cwd, info) {
     const p = relayInfoPath(cwd);
     await fs.mkdir(path.dirname(p), { recursive: true });
-    await fs.writeFile(p, JSON.stringify(info, null, 2) + "\n", "utf8");
+    // Removed first so an older 0644 marker is not rewritten in place: `mode`
+    // only applies when the file is created, and the token must never be
+    // readable by another user.
+    await fs.rm(p, { force: true });
+    await fs.writeFile(p, JSON.stringify(info, null, 2) + "\n", {
+        encoding: "utf8",
+        mode: 0o600,
+        flag: "wx",
+    });
     return p;
 }
 /** Reads the marker for the TREE containing cwd, not only the folder itself. */
@@ -83,7 +92,7 @@ export function isProcessAlive(pid) {
  * runs fifty times a day, and the fallback (mint a preview) is what they asked
  * for anyway.
  */
-export async function isRelayResponding(port, timeoutMs = 700, fetchImpl = fetch) {
+export async function isRelayResponding(port, timeoutMs = 700, fetchImpl = fetch, token) {
     if (!Number.isInteger(port) || port <= 0 || port > 65535)
         return false;
     const ac = new AbortController();
@@ -91,7 +100,7 @@ export async function isRelayResponding(port, timeoutMs = 700, fetchImpl = fetch
     try {
         const res = await fetchImpl(`http://127.0.0.1:${port}/query`, {
             method: "POST",
-            headers: { "content-type": "application/json" },
+            headers: { "content-type": "application/json", ...relayAuthHeaders(token) },
             body: JSON.stringify({ kind: "log", limit: 0 }),
             signal: ac.signal,
         });
@@ -132,14 +141,15 @@ export async function readLivePreview(cwd, deps = {}) {
     if (!info)
         return undefined;
     const processAlive = deps.processAlive ?? isProcessAlive;
-    const relayResponding = deps.relayResponding ?? ((p) => isRelayResponding(p));
+    const relayResponding = deps.relayResponding ??
+        ((p, t) => isRelayResponding(p, undefined, undefined, t));
     // The cheap gate first: a dead pid needs no network round trip.
     if (info.pid !== undefined && !processAlive(info.pid)) {
         await clearRelayInfo(cwd);
         return undefined;
     }
     // The identity gate: alive-but-not-ours (a recycled pid) fails here.
-    if (!(await relayResponding(info.relayPort))) {
+    if (!(await relayResponding(info.relayPort, info.token))) {
         await clearRelayInfo(cwd);
         return undefined;
     }

package/dist/preview/runner.d.ts

@@ -136,6 +136,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

@@ -18,6 +18,7 @@ import { realpath } from "node:fs/promises";
 import { createServer } from "node:http";
 import { TunnelClient, resolveForwardTarget, } from "@vincentt-xr/harness/tunnel";
 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";
@@ -37,6 +38,7 @@ export async function startPreview(opts) {
     const relayPort = opts.relayPort ?? (await getFreePort());
     const frontPort = opts.frontPort ?? (await getFreePort());
     const reuseApp = await isPortListening(appPort);
+    const relayToken = mintRelayToken();
     const hiddenRoot = await realpath(projectRoot).catch(() => projectRoot);
     let app;
     let killApp;
@@ -136,9 +138,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 +155,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 +257,7 @@ export async function startPreview(opts) {
             sessionId: minted.sessionId,
             expiresAt: minted.expiresAt,
             relayPort,
+            relayToken,
             appPort,
             appReady,
             stop,

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,6 +9,7 @@ import { WebSocketServer } from "ws";
 import { EventStore } from "./store.js";
 import { TesterRegistry, isTesterId } from "./testers.js";
 import { AnnotationStore } from "./annotations.js";
+import { RELAY_TOKEN_HEADER, hasRelayToken, isAllowedHost, isAllowedOrigin, isJsonContentType, } from "./guard.js";
 import { VIEWER_LABEL_RE, VIEWER_STAMP_HEADER } from "@vincentt-xr/harness/tunnel";
 /** Cap an annotation POST body so a bad/huge upload can't exhaust memory. */
 const MAX_ANNOTATION_BYTES = 25 * 1024 * 1024;
@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincentt-xr/cli",
-  "version": "0.18.2",
+  "version": "0.18.3",
   "description": "Vincentt CLI — the vincentt command-line dev loop (login, create, publish, preview, diagnostics, feedback, relay)",
   "license": "UNLICENSED",
   "type": "module",