@vincentt-xr/cli 0.18.1 → 0.18.3

package/MIGRATION.md

@@ -3,6 +3,23 @@
 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
+No action required. Behaviour that changed:
+- `init` and `create` read the public release list once and clone the template version it names, then check the cloned commit against the platform's record. A commit that does not match exits 1 and writes nothing. When the platform cannot be reached, or has no commit on record, they clone the `latest` tag as before and print one warning on stderr. Plain `init` still needs no account.
+- `vincentt create` in a folder that already holds an app, with no account and no terminal, now exits 4 (not signed in) with the `vincentt login` remedy, where it exited 1. Every not-signed-in path now exits 4.
+- The six preview ending lines no longer use em-dashes: each reads `✓ Preview stopped.` or `✗ Preview ended.` followed by its cause, for example `✗ Preview ended. It reached the 5 GB ceiling.` A script matching the old wording exactly needs updating.
+- `preview --stop` no longer signals a process that merely reuses the preview's old process id: the preview records its start time, and when the process now holding that id started at a different time, nothing is signalled and the command exits 1 as "nothing stopped", clearing the stale record. A preview started by an older CLI, or on Windows, has no start time on record and stops as before.
+
 ## 0.18.1
 
 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/initCommand.js

@@ -1,5 +1,7 @@
 // `vincentt init [dir]` — scaffold a Vincentt XR app. On the BARE path: NO
-// account, NO network call to the API, NO binding written.
+// account, NO binding written, and no API call beyond the scaffold's anonymous
+// read of the public release list (to verify the template commit; its failure
+// only warns).
 //
 // This is the acquisition wedge: local-first is a smaller room, not a wall, so the
 // template must be reachable without ever touching the auth gate. `create` (which

package/dist/lib/initFrom.js

@@ -93,7 +93,7 @@ export async function registerAfterScaffold(deps, opts = {}) {
             }
             deps.print("");
             deps.print(closing);
-            return scaffolded ? EXIT.DELIVERED_NOT_REGISTERED : EXIT.FAILED;
+            return scaffolded ? EXIT.DELIVERED_NOT_REGISTERED : EXIT.NOT_AUTHENTICATED;
         }
         deps.print("");
         deps.print("→ Now registering the project so it gets an address.");

package/dist/lib/lifecycle.d.ts

@@ -2,6 +2,7 @@ import type { OrgSource } from "./initFrom.js";
 import type { Ask } from "../publish/prompt.js";
 import { type ResolvedOrg } from "./org.js";
 import { type RelayClient } from "./diagnostics.js";
+import { type ProcessStartTimeReader } from "./processStartTime.js";
 import { type ResolvedConfig } from "../shared/config.js";
 import { type RunningPreview, type StartPreviewOptions } from "../preview/index.js";
 import type { DiagEventKind, RelayResult } from "@vincentt-xr/harness/events";
@@ -125,6 +126,8 @@ export interface PreviewStopDeps {
     relay?: RelayClient;
     /** Injected so the SIGTERM is observable without signalling a real process. */
     kill?: (pid: number, signal: NodeJS.Signals) => void;
+    /** Injected so a recycled pid can be simulated without a real process. */
+    processStartTime?: ProcessStartTimeReader;
 }
 /**
  * Stop a preview started by a *different* process (the common case: `vincentt

package/dist/lib/lifecycle.js

@@ -10,6 +10,7 @@ import { publishCommand } from "../publish/command.js";
 import { activeOrgSlug, resolveActiveOrg } from "./org.js";
 import { filterErrors, httpRelayClient, renderResult, } from "./diagnostics.js";
 import { clearRelayInfo, readLivePreview, readRelayInfo, writeRelayInfo, } from "./relayInfo.js";
+import { readProcessStartTime } from "./processStartTime.js";
 import { loadMachineConfig, locateProjectBinding, resolveConfig, } from "../shared/config.js";
 import { startPreview, } from "../preview/index.js";
 // The SHIPPED stopping line, reused rather than reworded: the interrupt path and
@@ -173,6 +174,8 @@ export async function previewStart(projectCwd, onLog, extra = {}) {
         pid: process.pid,
         harnessPath: "/__harness",
         expiresAt: preview.expiresAt,
+        pidStartTime: await readProcessStartTime(process.pid),
+        token: preview.relayToken,
     });
     return { preview, started: true };
 }
@@ -199,6 +202,19 @@ function isAlive(pid) {
 }
 /** The bound the caller is held to: one query, no retry, isRelayResponding's window. */
 const PRESENCE_TIMEOUT_MS = 700;
+/**
+ * True only when the marker recorded a start time and the live process holding
+ * that pid PROVABLY started at a different time. A marker from an older CLI, or
+ * a start time that cannot be read, proves nothing, so the stop goes ahead as it
+ * always did. The relay is deliberately not consulted: QA-F14-06 requires the
+ * stop to happen whatever the relay answers.
+ */
+async function isRecycledPid(info, read) {
+    if (info.pidStartTime === undefined)
+        return false;
+    const live = await read(info.pid);
+    return live !== undefined && live !== info.pidStartTime;
+}
 /**
  * How many connections are attached, or UNDEFINED when that cannot be
  * established — and undefined is a first-class answer here, not an error.
@@ -259,7 +275,11 @@ export async function previewStopSignal(projectCwd, deps = {}) {
     if (!info) {
         return { stopped: false, message: "No preview is running for this directory." };
     }
-    const previewAlive = info.pid !== undefined && isAlive(info.pid);
+    // A recycled pid is treated exactly like a dead one: nothing is signalled, the
+    // relay is not asked, and the stale marker is cleared.
+    const previewAlive = info.pid !== undefined &&
+        isAlive(info.pid) &&
+        !(await isRecycledPid(info, deps.processStartTime ?? readProcessStartTime));
     if (previewAlive) {
         // PRESENCE IS READ BEFORE THE SIGNAL, and the order is the feature. The
         // creator is about to blank someone's screen, so the count has to describe
@@ -267,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");
@@ -314,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/processStartTime.d.ts

@@ -0,0 +1,12 @@
+export type ProcessStartTimeReader = (pid: number) => Promise<string | undefined>;
+/**
+ * macOS and Linux both answer `ps -o lstart= -p <pid>` (BSD ps and procps), run
+ * under the C locale so the text does not vary with the creator's language.
+ * One-second resolution is enough: the process that held the pid had to exit
+ * before it could be reused. Windows returns undefined: no marker then carries
+ * a start time, and `preview --stop` behaves as it did before the check.
+ *
+ * Undefined also means "could not read" (no `ps`, a ps without `lstart`), never
+ * "different".
+ */
+export declare function readProcessStartTime(pid: number, platform?: NodeJS.Platform): Promise<string | undefined>;

package/dist/lib/processStartTime.js

@@ -0,0 +1,33 @@
+// A process's start time, read as an opaque token that is only ever compared for
+// equality. Together with the pid it identifies ONE process: a recycled pid has
+// the same number and a different start time.
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileP = promisify(execFile);
+/**
+ * macOS and Linux both answer `ps -o lstart= -p <pid>` (BSD ps and procps), run
+ * under the C locale so the text does not vary with the creator's language.
+ * One-second resolution is enough: the process that held the pid had to exit
+ * before it could be reused. Windows returns undefined: no marker then carries
+ * a start time, and `preview --stop` behaves as it did before the check.
+ *
+ * Undefined also means "could not read" (no `ps`, a ps without `lstart`), never
+ * "different".
+ */
+export async function readProcessStartTime(pid, platform = process.platform) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return undefined;
+    if (platform === "win32")
+        return undefined;
+    try {
+        const { stdout } = await execFileP("ps", ["-o", "lstart=", "-p", String(pid)], {
+            env: { ...process.env, LC_ALL: "C" },
+            timeout: 2000,
+        });
+        const lstart = stdout.trim().replace(/\s+/g, " ");
+        return lstart === "" ? undefined : lstart;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/lib/relayInfo.d.ts

@@ -17,6 +17,19 @@ export interface RelayInfo {
      * only assumes is live. Optional: markers written by an older CLI lack it.
      */
     expiresAt?: string;
+    /**
+     * The preview process's start time (an opaque token from
+     * `readProcessStartTime`), so `preview --stop` can tell the preview from an
+     * unrelated process that was later given the same pid. Absent from markers
+     * 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;
 /**
@@ -57,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.
@@ -74,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/platform/releaseCache.d.ts

@@ -8,6 +8,13 @@ export interface ReleaseComponent {
      * cannot tell blank from forgotten, so the platform must say which one it is.
      */
     migration?: ReleaseMigration;
+    /**
+     * The released commit (40 lowercase hex). ABSENT for rows released before the
+     * platform recorded it, and for a value of any other shape: the scaffold
+     * verifies a clone against it, so a malformed value must read as "nothing to
+     * verify", never as a value to compare.
+     */
+    commit?: string;
 }
 export interface ReleaseMigration {
     required: boolean;

package/dist/platform/releaseCache.js

@@ -19,6 +19,7 @@ import path from "node:path";
 import { CHECK_TTL_MS } from "../dx/updateCheck.js";
 import { platformCheckEnabled } from "./offSwitch.js";
 const CACHE_FILE = "platform-release.json";
+const COMMIT_SHA = /^[0-9a-f]{40}$/;
 /**
  * Freshness, with a clock that moved backwards treated as STALE rather than as
  * fresh forever. Same rule and same TTL as the CLI update check — reused rather
@@ -75,13 +76,15 @@ export function readPlatformRelease(raw) {
     for (const [name, value] of Object.entries(components)) {
         if (typeof value !== "object" || value === null)
             continue;
-        const { version, migration } = value;
+        const { version, migration, commit } = value;
         if (typeof version !== "string" || version === "")
             continue;
         const component = { version };
         const note = readMigration(migration);
         if (note !== undefined)
             component.migration = note;
+        if (typeof commit === "string" && COMMIT_SHA.test(commit))
+            component.commit = commit;
         out[name] = component;
     }
     const parsed = { release, components: out };

package/dist/preview/copy.js

@@ -331,7 +331,7 @@ export function stoppedElsewhere() {
 export function endedDisconnected() {
     return [
         "",
-        "✗ Preview ended — the connection to Vincentt closed.",
+        "✗ Preview ended. The connection to Vincentt closed.",
         "",
         "  This window can't tell whether that was your network, your machine going to",
         "  sleep, or something on our side. Nothing is wrong with your project.",
@@ -375,7 +375,7 @@ export function hardMaxWarning(clockTime, minutesLeft) {
 export function hardMaxReached() {
     return [
         "",
-        "✓ Preview stopped — 12-hour maximum reached. The link no longer works.",
+        "✓ Preview stopped. 12-hour maximum reached. The link no longer works.",
         "",
         "  Start a new one:  vincentt preview",
         "  For an address that lasts, publish it:  vincentt publish",
@@ -435,7 +435,7 @@ export function supersededWinner() {
 export function endedUnreachable(orgName) {
     return [
         "",
-        "✗ Preview ended — this project is no longer available to you.",
+        "✗ Preview ended. This project is no longer available to you.",
         "",
         `  Your access to ${orgName} may have changed. Check who you are:  vincentt whoami`,
         "",
@@ -458,7 +458,7 @@ export function endedAuthExpired() {
 export function endedUnconfirmed() {
     return [
         "",
-        "✗ Preview ended — couldn't confirm your access to this project.",
+        "✗ Preview ended. Couldn't confirm your access to this project.",
         "",
         "  Try again:  vincentt preview",
         "",
@@ -498,7 +498,7 @@ export function endedUnconfirmed() {
 export function endedAbandoned() {
     return [
         "",
-        "✗ Preview ended — this machine stopped checking in with Vincentt.",
+        "✗ Preview ended. This machine stopped checking in with Vincentt.",
         "",
         "  The preview needed this computer to stay in touch and it went quiet, so the",
         "  link was released. Nothing is wrong with your project.",
@@ -526,7 +526,7 @@ export function egressSoft() {
 export function egressHard() {
     return [
         "",
-        "✗ Preview ended — it reached the 5 GB ceiling.",
+        "✗ Preview ended. It reached the 5 GB ceiling.",
         "",
         "  Start a new one:  vincentt preview",
         "",

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/dist/scaffold/index.d.ts

@@ -9,6 +9,11 @@ export declare const TEMPLATE_REPO = "https://github.com/vincentt-xr/v2-template
  *
  * A creator pins a known version with `--template 1.0.0`; version tags are
  * immutable, which is what makes that an escape hatch rather than a coin flip.
+ *
+ * Asked for this ref, the scaffold clones the platform's released version tag
+ * instead when the platform records that release's commit, and refuses a clone
+ * that lands anywhere else (see `releasedCommit.ts`). The moving tag is cloned
+ * only when there is nothing to check it against.
  */
 export declare const DEFAULT_TEMPLATE_REF = "latest";
 /**
@@ -51,6 +56,12 @@ export interface ScaffoldOptions {
     ref?: string;
     /** Test seam — defaults to spawning real git. */
     runGit?: GitRunner;
+    /** API origin for the release lookup. Defaults to the machine's configured one. */
+    apiUrl?: string;
+    /** Test seam for the release lookup — defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Where the unverified-template warning goes. Defaults to stderr. */
+    warn?: (line: string) => void;
 }
 /**
  * The concrete version tag the clone actually landed on, or `undefined` when the

package/dist/scaffold/index.js

@@ -8,6 +8,7 @@ import { promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
+import { TemplateCommitMismatchError, UNVERIFIED_TEMPLATE_WARNING, resolveTemplatePin, } from "./releasedCommit.js";
 const execFileAsync = promisify(execFile);
 export const TEMPLATE_REPO = "https://github.com/vincentt-xr/v2-template.git";
 /**
@@ -20,6 +21,11 @@ export const TEMPLATE_REPO = "https://github.com/vincentt-xr/v2-template.git";
  *
  * A creator pins a known version with `--template 1.0.0`; version tags are
  * immutable, which is what makes that an escape hatch rather than a coin flip.
+ *
+ * Asked for this ref, the scaffold clones the platform's released version tag
+ * instead when the platform records that release's commit, and refuses a clone
+ * that lands anywhere else (see `releasedCommit.ts`). The moving tag is cloned
+ * only when there is nothing to check it against.
  */
 export const DEFAULT_TEMPLATE_REF = "latest";
 const realGit = async (args) => {
@@ -128,10 +134,21 @@ export async function scaffoldFromTemplate(targetDir, opts = {}) {
     const repo = opts.repo ?? TEMPLATE_REPO;
     const ref = opts.ref ?? DEFAULT_TEMPLATE_REF;
     const runGit = opts.runGit ?? realGit;
+    // Only the built-in template has a platform release to check against; a
+    // gallery source (`init --from`) is another repository entirely.
+    const pin = repo === TEMPLATE_REPO
+        ? await resolveTemplatePin(ref, DEFAULT_TEMPLATE_REF, {
+            apiUrl: opts.apiUrl,
+            fetchImpl: opts.fetchImpl,
+        })
+        : { ref, unverified: false };
+    if (pin.unverified) {
+        (opts.warn ?? ((line) => process.stderr.write(`${line}\n`)))(UNVERIFIED_TEMPLATE_WARNING);
+    }
     const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "vincentt-tmpl-"));
     try {
         try {
-            await runGit(["clone", "--depth", "1", "--branch", ref, repo, tmp]);
+            await runGit(["clone", "--depth", "1", "--branch", pin.ref, repo, tmp]);
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
@@ -140,11 +157,26 @@ export async function scaffoldFromTemplate(targetDir, opts = {}) {
             // real cause is a typo'd version). git names the ref in this specific case,
             // so split on that rather than reporting one cause for both.
             if (/(remote branch|Remote branch).*not found|couldn't find remote ref/i.test(msg)) {
-                throw new ScaffoldRefError(`The template has no version "${ref}". ` +
-                    `Check the tag exists, or omit --template to use the latest release.`);
+                throw new ScaffoldRefError(pin.ref === ref
+                    ? `The template has no version "${ref}". ` +
+                        `Check the tag exists, or omit --template to use the latest release.`
+                    : `The template has no tag for its released version "${pin.ref}". ` +
+                        `Report this to the Vincentt team.`);
             }
             throw new Error(`Could not clone the ${repo} template (check your git access): ${msg}`);
         }
+        if (pin.expectedCommit !== undefined) {
+            let actual;
+            try {
+                actual = String((await runGit(["-C", tmp, "rev-parse", "HEAD"])) ?? "").trim();
+            }
+            catch {
+                actual = "";
+            }
+            if (actual !== pin.expectedCommit) {
+                throw new TemplateCommitMismatchError(pin.releasedVersion ?? pin.ref, pin.expectedCommit, actual || "(could not be read)");
+            }
+        }
         // BEFORE the strip below — `.git` is the only place the concrete tag is
         // readable, and the copy into the target deliberately does not carry it.
         // A failure here must not fail the scaffold: the files are correct either

package/dist/scaffold/releasedCommit.d.ts

@@ -0,0 +1,37 @@
+export interface TemplatePin {
+    /** The tag to clone. */
+    ref: string;
+    /** Present when the clone must be checked; the clone fails on any other commit. */
+    expectedCommit?: string;
+    /** The version the platform released, named in the mismatch error. */
+    releasedVersion?: string;
+    /** True when the default ref is cloned with nothing to check it against. */
+    unverified: boolean;
+}
+export interface PinOptions {
+    /** The API origin. Defaults to the machine's configured one. */
+    apiUrl?: string;
+    /** Test seam, passed through to `fetchRelease`. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Resolve the pin for a scaffold of the built-in template.
+ *
+ * `defaultRef` is the moving tag. Asked for it, the platform's release version
+ * is cloned in its place when that release carries a commit; otherwise the
+ * moving tag is cloned as before and the result says it went unverified. An
+ * explicit version is checked only when it is the version the platform
+ * released, since older version tags are protected by the tag ruleset and the
+ * platform holds no commit for them.
+ */
+export declare function resolveTemplatePin(requested: string, defaultRef: string, opts?: PinOptions): Promise<TemplatePin>;
+/** The one-line stderr warning for a default-ref scaffold with nothing to check. */
+export declare const UNVERIFIED_TEMPLATE_WARNING = "! The template could not be verified against the platform release; cloned the latest tag unchecked.";
+/**
+ * The cloned commit is not the one the platform released. Nothing is written
+ * and there is no fallback: a moved tag is exactly what this check exists to
+ * catch, and retrying `latest` would clone the same suspect tree unchecked.
+ */
+export declare class TemplateCommitMismatchError extends Error {
+    constructor(version: string, expected: string, actual: string);
+}

package/dist/scaffold/releasedCommit.js

@@ -0,0 +1,71 @@
+// Which template ref to clone, and which commit it must land on.
+//
+// The template's tags live in a public repo whose admins can move them by hand,
+// so the clone alone proves nothing. The platform records each template
+// release's commit independently (`GET /platform/versions`), and a scaffold of
+// the default ref clones THAT release's version tag and checks the commit.
+import { TEMPLATE_COMPONENT } from "../platform/allowlist.js";
+import { fetchRelease } from "../platform/releaseFetch.js";
+import { loadMachineConfig, machineApiUrl } from "../shared/config.js";
+/** Same shape the scaffold accepts as a concrete version tag. */
+const CONCRETE_VERSION = /^[0-9]+\.[0-9]+\.[0-9]+$/;
+/**
+ * Resolve the pin for a scaffold of the built-in template.
+ *
+ * `defaultRef` is the moving tag. Asked for it, the platform's release version
+ * is cloned in its place when that release carries a commit; otherwise the
+ * moving tag is cloned as before and the result says it went unverified. An
+ * explicit version is checked only when it is the version the platform
+ * released, since older version tags are protected by the tag ruleset and the
+ * platform holds no commit for them.
+ */
+export async function resolveTemplatePin(requested, defaultRef, opts = {}) {
+    const row = await fetchTemplateRow(opts);
+    const verifiable = row !== undefined && row.commit !== undefined && CONCRETE_VERSION.test(row.version);
+    if (requested === defaultRef) {
+        if (!verifiable)
+            return { ref: defaultRef, unverified: true };
+        return {
+            ref: row.version,
+            expectedCommit: row.commit,
+            releasedVersion: row.version,
+            unverified: false,
+        };
+    }
+    if (verifiable && requested === row.version) {
+        return {
+            ref: requested,
+            expectedCommit: row.commit,
+            releasedVersion: row.version,
+            unverified: false,
+        };
+    }
+    return { ref: requested, unverified: false };
+}
+async function fetchTemplateRow(opts) {
+    try {
+        const apiUrl = opts.apiUrl ?? machineApiUrl(await loadMachineConfig());
+        const fetched = await fetchRelease({ apiUrl, fetchImpl: opts.fetchImpl });
+        return fetched?.release.components[TEMPLATE_COMPONENT];
+    }
+    catch {
+        // An unreadable machine config is the same as an unreachable platform.
+        return undefined;
+    }
+}
+/** The one-line stderr warning for a default-ref scaffold with nothing to check. */
+export const UNVERIFIED_TEMPLATE_WARNING = "! The template could not be verified against the platform release; cloned the latest tag unchecked.";
+/**
+ * The cloned commit is not the one the platform released. Nothing is written
+ * and there is no fallback: a moved tag is exactly what this check exists to
+ * catch, and retrying `latest` would clone the same suspect tree unchecked.
+ */
+export class TemplateCommitMismatchError extends Error {
+    constructor(version, expected, actual) {
+        super(`The template did not match the released version ${version}.\n` +
+            `  Expected commit ${expected}\n` +
+            `  Actual commit   ${actual}\n\n` +
+            `  Nothing was written. Report this to the Vincentt team.`);
+        this.name = "TemplateCommitMismatchError";
+    }
+}

package/package.json

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