@vincentt-xr/cli 0.22.0 → 0.24.0

package/dist/editor/reads.js

@@ -0,0 +1,269 @@
+// `vincentt editor --selection [--json]` and `--status --json`: read the editor's local files
+// and print them. A read flag never talks to the running app; when none runs for the folder it
+// says so on stderr, still prints one JSON object on stdout, and exits 1. A file in a schema
+// major this CLI does not know is refused whole ("too new"), never printed in part.
+import { pidAlive } from "./app.js";
+import { NOT_RUNNING, tooNew } from "./copy.js";
+import { realpath } from "node:fs/promises";
+import { lastHandoff } from "./handoffs.js";
+import { parsePidFile, readLocalFile, readLocalFileStat, } from "./localFiles.js";
+import { agentSafe, agentSafeValue } from "./text.js";
+export const SELECTION_SCHEMA = "vincentt.editor-selection/1";
+export const STATE_SCHEMA = "vincentt.editor-state/1";
+/**
+ * True when the code `pid` is running meets the requirement, from any path. Checked on the
+ * running process itself, so no path the OS reports for it is trusted.
+ */
+export async function isVerifiedEditor(pid, p) {
+    const verdict = await p.system.verifyPid(pid, p.requirement).catch(() => undefined);
+    return verdict?.ok === true;
+}
+/** `ps` reports whole seconds and the app writes whole seconds. */
+const START_SLACK_MS = 1_000;
+/**
+ * True when the process now holding `pid` was already running when the record was written. A
+ * process that started after `startedAt` reused the pid of the editor that wrote it.
+ */
+export function startedBeforeRecord(processStart, rec) {
+    return processStart !== undefined && processStart <= rec.startedAt + START_SLACK_MS;
+}
+/** The editor recorded in `pid`, when that process is live, is that record's process, and is a verified editor. */
+export async function runningEditor(root, p) {
+    const text = await readLocalFile(root, "pid").catch(() => undefined);
+    const rec = text === undefined ? undefined : parsePidFile(text);
+    if (rec === undefined || !(p.isAlive ?? pidAlive)(rec.pid))
+        return undefined;
+    const start = await p.system.startTime(rec.pid).catch(() => undefined);
+    if (!startedBeforeRecord(start, rec))
+        return undefined;
+    return (await isVerifiedEditor(rec.pid, p)) ? rec : undefined;
+}
+/** Whether `schema` is `<family>/1`, a later major of the family, or something else. */
+export function schemaMajor(schema, family) {
+    if (typeof schema !== "string")
+        return "foreign";
+    const m = /^(.+)\/(\d+)$/.exec(schema);
+    if (m === null || m[1] !== family)
+        return "foreign";
+    const major = Number(m[2]);
+    if (major === 1)
+        return "known";
+    return major > 1 ? { newer: schema } : "foreign";
+}
+const SELECTION_FAMILY = "vincentt.editor-selection";
+const STATE_FAMILY = "vincentt.editor-state";
+async function readJson(root, name) {
+    return (await readJsonStat(root, name))?.value;
+}
+async function readJsonStat(root, name) {
+    const file = await readLocalFileStat(root, name).catch(() => undefined);
+    if (file === undefined)
+        return undefined;
+    try {
+        const v = JSON.parse(file.text);
+        return typeof v === "object" && v !== null && !Array.isArray(v)
+            ? { value: v, mtimeMs: file.mtimeMs }
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * A snapshot belongs to the running editor when it carries the pid record's session and, when it
+ * names a pid, that pid.
+ */
+function sameEditor(file, rec) {
+    if (typeof file.session !== "string" || file.session !== rec.session)
+        return false;
+    return typeof file.pid !== "number" || file.pid === rec.pid;
+}
+/** Fields the CLI states itself; file content never supplies them. */
+const RESERVED_STATE_KEYS = ["schema", "running", "pid", "session"];
+const num = (v) => typeof v === "number" && Number.isFinite(v) ? v : undefined;
+/** A string field, sanitised; anything that is not a string reads as empty. */
+const str = (v, max) => typeof v === "string" ? agentSafe(v, max) : "";
+/** The selection as the agent may read it: an allowlist of fields, every string sanitised. */
+export function shapeSelection(sel) {
+    if (typeof sel !== "object" || sel === null)
+        return null;
+    const s = sel;
+    const src = (typeof s.source === "object" && s.source !== null ? s.source : {});
+    const values = Array.isArray(s.values) ? s.values : [];
+    return {
+        objectKey: str(s.objectKey, 400),
+        label: str(s.label, 200),
+        type: str(s.type, 80),
+        kind: str(s.kind, 20),
+        source: {
+            file: str(src.file, 400),
+            line: num(src.line) ?? null,
+            column: num(src.column) ?? null,
+        },
+        values: values.slice(0, 256).map((raw) => {
+            const v = (typeof raw === "object" && raw !== null ? raw : {});
+            const out = {
+                path: str(v.path, 200),
+                type: str(v.type, 20),
+                value: agentSafeValue(v.value),
+            };
+            if (typeof v.unit === "string")
+                out.unit = agentSafe(v.unit, 10);
+            out.editable =
+                v.editable === true
+                    ? true
+                    : agentSafeValue(v.editable ?? { readonly: "unsupported" }, 40);
+            if (typeof v.decl === "string")
+                out.decl = agentSafe(v.decl, 200);
+            if (num(v.sharedBy) !== undefined)
+                out.sharedBy = num(v.sharedBy);
+            return out;
+        }),
+    };
+}
+function tooNewResult(schema) {
+    return { stdout: [], stderr: tooNew(schema), exitCode: 1, reason: "too_new" };
+}
+export async function selectionRead(root, json, p) {
+    const file = await readJson(root, "selection.json");
+    const major = schemaMajor(file?.schema, SELECTION_FAMILY);
+    if (typeof major === "object")
+        return tooNewResult(major.newer);
+    const rec = await runningEditor(root, p);
+    if (rec === undefined) {
+        return {
+            stdout: json
+                ? [JSON.stringify({ schema: SELECTION_SCHEMA, running: false, selection: null })]
+                : [],
+            stderr: [NOT_RUNNING],
+            exitCode: 1,
+            reason: "not_running",
+        };
+    }
+    const selection = file && major === "known" && sameEditor(file, rec)
+        ? shapeSelection(file.selection)
+        : null;
+    if (json) {
+        return {
+            stdout: [JSON.stringify({ schema: SELECTION_SCHEMA, running: true, selection })],
+            stderr: [],
+            exitCode: 0,
+        };
+    }
+    return { stdout: humanSelection(selection), stderr: [], exitCode: 0 };
+}
+function display(v) {
+    if (Array.isArray(v))
+        return v.map(display).join(", ");
+    if (v !== null && typeof v === "object") {
+        return Object.entries(v)
+            .map(([k, x]) => `${k}: ${display(x)}`)
+            .join(", ");
+    }
+    return String(v);
+}
+export function humanSelection(sel) {
+    if (sel === null)
+        return ["Nothing is selected in the editor."];
+    const src = sel.source;
+    const kind = sel.kind === "sdk" ? " (Vincentt SDK)" : "";
+    const out = [
+        `${sel.label}  ${sel.type}${kind}  ${src.file}${src.line !== null ? `:${src.line}` : ""}`,
+    ];
+    for (const v of sel.values) {
+        const unit = typeof v.unit === "string" ? ` ${v.unit}` : "";
+        const ro = v.editable === true
+            ? ""
+            : `   (read-only: ${display(v.editable?.readonly ?? "unsupported")})`;
+        out.push(`  ${String(v.path).padEnd(26)} ${display(v.value)}${unit}${ro}`);
+    }
+    return out;
+}
+const APP_VERSION = /^\d+\.\d+\.\d+([-+][0-9A-Za-z.-]{1,32})?$/;
+const LAST_OPEN = /^(opened|awaiting_trust|cancelled|refused:[A-Za-z0-9_-]{1,16})$/;
+/**
+ * `app` as the agent may read it: exactly `{version, lastOpen}`, each null unless it is one of
+ * the shapes the app writes. `trustLastOpen` false nulls `lastOpen` whatever the file says.
+ */
+export function shapeApp(app, trustLastOpen) {
+    const a = (typeof app === "object" && app !== null ? app : {});
+    const version = typeof a.version === "string" && APP_VERSION.test(a.version) ? a.version : null;
+    const lastOpen = trustLastOpen && typeof a.lastOpen === "string" && LAST_OPEN.test(a.lastOpen)
+        ? a.lastOpen
+        : null;
+    return { version, lastOpen };
+}
+/**
+ * A state file no running editor vouches for is believed about the last open only when it
+ * changed after this machine's last hand-off of this folder: a committed or copied state.json
+ * predates it, and a folder never handed over has no open to report. A time in the future (an
+ * unpacked archive keeps whatever mtime it was given) is not after anything.
+ */
+async function lastOpenTrusted(root, mtimeMs) {
+    const project = await realpath(root).catch(() => undefined);
+    if (project === undefined)
+        return false;
+    const at = await lastHandoff(project).catch(() => undefined);
+    return at !== undefined && mtimeMs > at && mtimeMs <= Date.now() + 5_000;
+}
+function appField(file, trustLastOpen) {
+    return file !== undefined && file.app !== undefined
+        ? { app: shapeApp(file.app, trustLastOpen) }
+        : {};
+}
+export async function statusRead(root, p) {
+    const read = await readJsonStat(root, "state.json");
+    const file = read?.value;
+    const major = schemaMajor(file?.schema, STATE_FAMILY);
+    if (typeof major === "object")
+        return tooNewResult(major.newer);
+    const known = major === "known" ? file : undefined;
+    const rec = await runningEditor(root, p);
+    if (known && rec && known.running === true && sameEditor(known, rec)) {
+        // The running, verified editor wrote this file. Sanitised first, so a key that only
+        // becomes `pid` once its control characters are stripped is removed too.
+        const shaped = agentSafeValue(known, 400);
+        for (const k of RESERVED_STATE_KEYS)
+            delete shaped[k];
+        if (known.app !== undefined)
+            shaped.app = shapeApp(known.app, true);
+        return {
+            stdout: [
+                JSON.stringify({ schema: STATE_SCHEMA, running: true, pid: rec.pid, ...shaped }),
+            ],
+            stderr: [],
+            exitCode: 0,
+        };
+    }
+    const trusted = known !== undefined &&
+        read !== undefined &&
+        (await lastOpenTrusted(root, read.mtimeMs));
+    if (rec === undefined) {
+        // A refused or cancelled open leaves no running editor behind, so the outcome of the last
+        // hand-off is reported here too, when the file is believed.
+        return {
+            stdout: [
+                JSON.stringify({
+                    schema: STATE_SCHEMA,
+                    running: false,
+                    ...appField(known, trusted),
+                }),
+            ],
+            stderr: [NOT_RUNNING],
+            exitCode: 1,
+            reason: "not_running",
+        };
+    }
+    return {
+        stdout: [
+            JSON.stringify({
+                schema: STATE_SCHEMA,
+                running: true,
+                pid: rec.pid,
+                ...appField(known, trusted),
+            }),
+        ],
+        stderr: [],
+        exitCode: 0,
+    };
+}

package/dist/editor/text.d.ts

@@ -0,0 +1,7 @@
+export declare function isUnsafeChar(ch: string): boolean;
+/** Unsafe characters removed and the result capped at `max` code points. */
+export declare function agentSafe(s: string, max: number): string;
+/** Nesting kept in a value an agent reads; anything deeper is dropped (null). */
+export declare const MAX_DEPTH = 8;
+/** A JSON value with every string (keys included) made agent-safe, depth- and size-capped. */
+export declare function agentSafeValue(v: unknown, max?: number, depth?: number): unknown;

package/dist/editor/text.js

@@ -0,0 +1,58 @@
+// Text that reaches the creator's terminal or their agent from the editor's files. The app
+// already strips these characters (B-F21-8); the CLI strips them again because it is the last
+// step before a shell, and a stale or planted file never passed the app.
+// C0 and C1 controls, DEL, the Arabic letter mark, zero-width characters and direction marks,
+// line and paragraph separators, bidi embeddings, overrides and isolates, the word joiner,
+// invisible operators, the byte order mark, the soft hyphen, the combining grapheme joiner,
+// the Mongolian vowel separator, variation selectors and tag characters. Code points rather
+// than a character class, so no bidi character sits in source.
+const UNSAFE = [
+    [0x0000, 0x001f],
+    [0x007f, 0x009f],
+    [0x00ad, 0x00ad],
+    [0x034f, 0x034f],
+    [0x061c, 0x061c],
+    [0x180e, 0x180e],
+    [0x200b, 0x200f],
+    [0x2028, 0x2029],
+    [0x2060, 0x2064],
+    [0xfe00, 0xfe0f],
+    [0xfeff, 0xfeff],
+    [0x202a, 0x202e],
+    [0x2066, 0x2069],
+    [0xe0000, 0xe007f],
+    [0xe0100, 0xe01ef],
+];
+export function isUnsafeChar(ch) {
+    const cp = ch.codePointAt(0) ?? 0;
+    return UNSAFE.some(([lo, hi]) => cp >= lo && cp <= hi);
+}
+// CSI and OSC sequences, removed whole so no `[31m` residue is left behind.
+// eslint-disable-next-line no-control-regex
+const ANSI_G = /\u001b\[[0-?]*[ -/]*[@-~]|\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)?|\u009b[0-?]*[ -/]*[@-~]/g;
+/** Unsafe characters removed and the result capped at `max` code points. */
+export function agentSafe(s, max) {
+    return Array.from(s.replace(ANSI_G, ""))
+        .filter((ch) => !isUnsafeChar(ch))
+        .slice(0, max)
+        .join("");
+}
+/** Nesting kept in a value an agent reads; anything deeper is dropped (null). */
+export const MAX_DEPTH = 8;
+/** A JSON value with every string (keys included) made agent-safe, depth- and size-capped. */
+export function agentSafeValue(v, max = 200, depth = 0) {
+    if (typeof v === "string")
+        return agentSafe(v, max);
+    if (depth >= MAX_DEPTH && v !== null && typeof v === "object")
+        return null;
+    if (Array.isArray(v))
+        return v.slice(0, 64).map((x) => agentSafeValue(x, max, depth + 1));
+    if (v !== null && typeof v === "object") {
+        const out = {};
+        for (const [k, x] of Object.entries(v).slice(0, 256)) {
+            out[agentSafe(k, 80)] = agentSafeValue(x, max, depth + 1);
+        }
+        return out;
+    }
+    return v;
+}

package/dist/editor/tools.d.ts

@@ -0,0 +1,5 @@
+export type Tool = "codesign" | "open" | "sw_vers" | "plutil" | "lsappinfo" | "ps";
+/** Where each tool lives, most likely first. Never a relative path; none off macOS. */
+export declare function toolCandidates(tool: Tool, platform?: NodeJS.Platform): string[];
+/** The tool's absolute path, or undefined when it is not where the OS keeps it. */
+export declare function toolPath(tool: Tool, platform?: NodeJS.Platform, exists?: (p: string) => boolean): string | undefined;

package/dist/editor/tools.js

@@ -0,0 +1,20 @@
+// The macOS tools the launcher runs, by absolute path only. A bare name would be resolved from
+// PATH, so a project (or anything earlier on PATH) could plant a `codesign` that answers "this
+// app is signed by Vincentt".
+import { existsSync } from "node:fs";
+const DARWIN = {
+    ps: ["/bin/ps"],
+    codesign: ["/usr/bin/codesign"],
+    open: ["/usr/bin/open"],
+    sw_vers: ["/usr/bin/sw_vers"],
+    plutil: ["/usr/bin/plutil"],
+    lsappinfo: ["/usr/bin/lsappinfo"],
+};
+/** Where each tool lives, most likely first. Never a relative path; none off macOS. */
+export function toolCandidates(tool, platform = process.platform) {
+    return platform === "darwin" ? DARWIN[tool] : [];
+}
+/** The tool's absolute path, or undefined when it is not where the OS keeps it. */
+export function toolPath(tool, platform = process.platform, exists = existsSync) {
+    return toolCandidates(tool, platform).find((p) => exists(p));
+}

package/dist/preview/copy.d.ts

@@ -11,6 +11,13 @@ export interface StartBlockInput {
      * project is worse than no link.
      */
     consoleUrl?: string;
+    /**
+     * The console origin the relay accepts feedback from, passed ONLY when it is
+     * not the production console. A flag or environment variable can point the
+     * CLI at another console, and the creator sees which one before any feedback
+     * arrives from it.
+     */
+    feedbackOrigin?: string;
     /** Pre-rendered QR rows, or undefined for non-TTY / piped / --no-qr. */
     qr?: string[];
     expiresInHours: number;

package/dist/preview/copy.js

@@ -48,6 +48,9 @@ export function startBlock(i) {
     if (i.consoleUrl) {
         out.push("  In the console:", "", `    ${i.consoleUrl}`, "");
     }
+    if (i.feedbackOrigin) {
+        out.push(`  Feedback is accepted from the console at ${terminalSafe(i.feedbackOrigin)}`, "");
+    }
     out.push("  Waiting for a device…", "");
     return out;
 }

package/dist/preview/runner.d.ts

@@ -101,6 +101,11 @@ export interface StartPreviewOptions {
     appReadyTimeoutMs?: number;
     /** Progress sink. Never write app stdout to an MCP server's stdout. */
     onLog?: (message: string) => void;
+    /**
+     * The console this CLI signs in through, from the creator's own configuration.
+     * Its origin, if valid, may send feedback to the relay's annotation route.
+     */
+    consoleUrl?: string;
     /**
      * A viewer label appearing on a stream. Fires per OPEN, so the roster's
      * per-label idempotence is what keeps one device from announcing itself once
@@ -171,6 +176,8 @@ export interface RunningPreview {
     appPort: number;
     /** Whether the app was responding when we returned. */
     appReady: boolean;
+    /** The console origin the relay admits on its annotation route, if any. */
+    consoleOrigin?: string;
     /** Tear down the tunnel, the app dev serve, the front proxy and the relay. */
     stop: () => Promise<void>;
 }

package/dist/preview/runner.js

@@ -17,6 +17,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { realpath } from "node:fs/promises";
 import { createServer } from "node:http";
 import { TunnelClient, resolveForwardTarget, } from "../tunnel/index.js";
+import { consoleOriginOf } from "../relay/consoleOrigin.js";
 import { startRelay } from "../relay/server.js";
 import { mintRelayToken } from "../relay/guard.js";
 import { isHiddenAppPath, proxyWeb, proxyWs, relayRoute } from "./proxy.js";
@@ -168,10 +169,12 @@ export async function startPreview(opts) {
         }
         // Fixed here, from the server-computed URL, and never from a request.
         const previewOrigin = new URL(minted.url).origin;
+        const consoleOrigin = consoleOriginOf(opts.consoleUrl);
         relay = startRelay({
             port: relayPort,
             path: harnessPath,
             allowedOrigins: [previewOrigin],
+            consoleOrigin,
             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
@@ -293,6 +296,7 @@ export async function startPreview(opts) {
             relayToken,
             appPort,
             appReady,
+            consoleOrigin,
             stop,
         };
     }

package/dist/relay/consoleOrigin.d.ts

@@ -0,0 +1,12 @@
+/** The console origin to admit for `consoleUrl`, or undefined to admit none. */
+export declare function consoleOriginOf(consoleUrl: string | undefined): string | undefined;
+/**
+ * Is this preflight one the relay answers? The Origin was already matched
+ * exactly. The method must be exactly POST, and the requested headers, parsed
+ * as a comma list, trimmed and lowercased, a subset of `content-type`.
+ */
+export declare function isConsolePreflight(method: string | string[] | undefined, requestHeaders: string | string[] | undefined): boolean;
+/** The CORS headers on a preflight the relay answers. Nothing else, ever. */
+export declare function preflightHeaders(consoleOrigin: string): Record<string, string>;
+/** The CORS headers on the probe and on every POST response to the console. */
+export declare function responseHeaders(consoleOrigin: string): Record<string, string>;

package/dist/relay/consoleOrigin.js

@@ -0,0 +1,68 @@
+// The one browser origin the relay admits besides the preview's own: the console
+// this CLI signs in through, and only on the annotation route.
+//
+// It comes from the creator's own configuration (flag, env, machine config),
+// never from a request and never from the folder's binding. A value that is not
+// exactly an https origin, or an http origin on this machine's loopback, grants
+// nothing, and the relay then behaves as one with no console origin at all.
+import { isLoopbackOrigin } from "./guard.js";
+/** The console origin to admit for `consoleUrl`, or undefined to admit none. */
+export function consoleOriginOf(consoleUrl) {
+    if (consoleUrl === undefined)
+        return undefined;
+    let url;
+    try {
+        url = new URL(consoleUrl.trim());
+    }
+    catch {
+        return undefined;
+    }
+    // `origin` is the literal "null" for every scheme without a host, so this one
+    // check refuses `javascript:`, `data:`, `file:` and a blob URL alike.
+    const origin = url.origin;
+    if (origin === "null" || origin === "*")
+        return undefined;
+    if (url.username !== "" || url.password !== "")
+        return undefined;
+    if (url.protocol === "https:")
+        return origin;
+    if (url.protocol === "http:" && isLoopbackOrigin(origin))
+        return origin;
+    return undefined;
+}
+/**
+ * Is this preflight one the relay answers? The Origin was already matched
+ * exactly. The method must be exactly POST, and the requested headers, parsed
+ * as a comma list, trimmed and lowercased, a subset of `content-type`.
+ */
+export function isConsolePreflight(method, requestHeaders) {
+    if (method !== "POST")
+        return false;
+    if (requestHeaders === undefined)
+        return true;
+    if (typeof requestHeaders !== "string")
+        return false;
+    if (requestHeaders.trim() === "")
+        return true;
+    return requestHeaders
+        .split(",")
+        .map((h) => h.trim().toLowerCase())
+        .every((h) => h === "content-type");
+}
+/** The CORS headers on a preflight the relay answers. Nothing else, ever. */
+export function preflightHeaders(consoleOrigin) {
+    return {
+        "access-control-allow-origin": consoleOrigin,
+        "access-control-allow-methods": "POST",
+        "access-control-allow-headers": "content-type",
+        "access-control-max-age": "600",
+        vary: "Origin",
+    };
+}
+/** The CORS headers on the probe and on every POST response to the console. */
+export function responseHeaders(consoleOrigin) {
+    return {
+        "access-control-allow-origin": consoleOrigin,
+        vary: "Origin",
+    };
+}

package/dist/relay/guard.d.ts

@@ -16,8 +16,9 @@ export declare function isAllowedOrigin(raw: string | string[] | undefined, allo
 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.
+ * multipart bodies without a preflight. Requiring JSON forces a preflight, and
+ * the relay answers one only for the configured console origin, only on the
+ * annotation route.
  */
 export declare function isJsonContentType(raw: string | undefined): boolean;
 export declare function hasRelayToken(raw: string | string[] | undefined, token: string): boolean;

package/dist/relay/guard.js

@@ -1,8 +1,9 @@
 // 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.
+// The one exception is the creator's console, admitted on the annotation route
+// only (see consoleOrigin.ts). 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";
@@ -55,8 +56,9 @@ export function isLoopbackOrigin(raw) {
 }
 /**
  * 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.
+ * multipart bodies without a preflight. Requiring JSON forces a preflight, and
+ * the relay answers one only for the configured console origin, only on the
+ * annotation route.
  */
 export function isJsonContentType(raw) {
     if (raw === undefined)

package/dist/relay/server.d.ts

@@ -64,6 +64,15 @@ export interface RelayOptions {
      * loopback pass, which is what a standalone `vincentt relay` serves.
      */
     allowedOrigins?: readonly string[];
+    /**
+     * The console this CLI signs in through, already validated (`consoleOriginOf`).
+     * Admitted on the annotation route ONLY: its preflight and probe are answered
+     * there and its POST carries CORS headers. It is never added to
+     * `allowedOrigins`, which also gates the WebSocket, so the diagnostics socket,
+     * `/query` and `feedback/next` refuse it like any foreign origin. Omitted, the
+     * relay admits no console.
+     */
+    consoleOrigin?: string;
     /**
      * The per-session secret `/query` and `feedback/next` require in
      * `x-vincentt-relay-token`. The preview always sets it; without it those
@@ -136,3 +145,9 @@ export declare function isUnsafeRelayPath(rawUrl: string): boolean;
  * number before it reaches a timer.
  */
 export declare function feedbackTimeoutMs(raw: string | null): number;
+/**
+ * The body as UTF-8, decoded ONCE from the joined bytes: decoding each chunk on
+ * its own turns a multi-byte character split across two chunks into U+FFFD.
+ * The size limit is in bytes.
+ */
+export declare function readBody(req: IncomingMessage, maxBytes?: number): Promise<string>;