@vincentt-xr/cli 0.23.0 → 0.24.0

package/MIGRATION.md

@@ -3,16 +3,28 @@
 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.24.0
+
+required: false
+No action required. `vincentt preview` accepts feedback from the console the CLI signs in through, and the relay now refuses marks outside fixed bounds.
+- The relay admits one browser origin besides the preview's own: the origin of the console the CLI is configured with (https, or http on this machine's loopback; anything else admits none). It answers that console's preflight and probe only on the annotation route, with that exact origin, never `*` and never with credentials.
+- The diagnostics socket, the diagnostics query and the feedback drain refuse the console origin with 403, like any other browser origin.
+- An annotation from any sender is refused with 400 and stored nowhere when a coordinate is outside [-1, 2], it has more than 50 marks, a pen path has more than 500 points, a note is over 2,000 characters, the message is over 110,000 characters, or `frameInImage` does not fit inside the screenshot's PNG size.
+- Also refused with 400: a mark whose colour is not red, yellow or blue, or whose number is not 1 to 50; more than 50 legacy strokes, pins or labels; a stroke over 500 points or with a colour that is not a short colour token; a pin label or label over 2,000 characters.
+- The stored annotation's `spec` is rebuilt from the fields the relay checked, so a field it does not know is dropped and never reaches the agent.
+- An annotation sent from the console carries no tester.
+- When the configured console is not the production console (a flag, an environment variable or the machine config can change it), the preview start block prints `Feedback is accepted from the console at <origin>`.
+
 ## 0.23.0
 
 required: false
 No action required. New verb `vincentt editor`, which hands the project to the Vincentt Editor desktop app.
-- `vincentt editor` (macOS 14 or later, no account) finds `Vincentt Editor.app` in `/Applications`, then `~/Applications`, checks it is signed by Vincentt, hands it the project folder and exits 0 with `✓ Sent <name> to Vincentt Editor.` It does not wait for the app. The app is a separate download from https://vincentt.studio/editor; the CLI installs no editor binary and has no port option for it.
+- `vincentt editor` (macOS 14 or later, no account) finds the Vincentt Editor app in the Mac's Applications folder, then in the user's own Applications folder, checks it is signed by Vincentt, hands it the project folder and exits 0 with `✓ Sent <name> to Vincentt Editor.` It does not wait for the app. The app is a separate download from https://vincentt.studio/editor; the CLI installs no editor binary and has no port option for it.
 - It exits 1, last line `Nothing was opened.`, when the app is not installed, the installed copy is not signed by Vincentt, the Mac is not on macOS 14 or later, or another copy of the app is running from a different folder.
 - `vincentt editor --json` prints one `vincentt.editor-open/1` object: `{"schema","handedOff":true,"project","app","appVersion"}`, or `handedOff: false` with a `reason` (`not_installed`, `bad_signature`, `unsupported_os`, `other_copy_running`, `open_failed`) and, where known, `app` and `detail`. The sentence goes to stderr.
 - `vincentt editor --selection [--json]` prints what is selected in the editor (`vincentt.editor-selection/1`), and `vincentt editor --status --json` the editor's state for the folder (`vincentt.editor-state/1`, including `app.lastOpen`). Both work on any OS and exit 1, with one JSON object still on stdout, when no editor is running for the folder.
 - In `--status --json`, `app` is always `{"version","lastOpen"}`; when no editor is running, `lastOpen` is reported only for a folder this machine handed over with `vincentt editor`, from a state file written after that hand-off, and is `null` otherwise.
-- The CLI keeps those hand-offs in `~/.vincentt/editor-handoffs.json`, as a hash of each folder's path and a time, never the path itself. A file written in a newer format than this CLI reads is refused with an upgrade line on stderr and nothing on stdout.
+- The CLI keeps those hand-offs in a file in its own settings folder, as a hash of each folder's path and a time, never the path itself. A file written in a newer format than this CLI reads is refused with an upgrade line on stderr and nothing on stdout.
 
 ## 0.22.0
 

package/dist/cli/index.js

@@ -660,6 +660,7 @@ async function preview() {
             appPort: devPort,
             appPortFresh: devPortFresh,
             devCommand,
+            consoleUrl: (await resolveAuthUrls()).consoleUrl,
             onHiddenPath: (p) => ui.hiddenPath(p),
             appStdio: has("--verbose") ? "inherit" : "ignore",
             onViewer: (label, uaClass) => ui.viewerSeen(label, uaClass),
@@ -727,6 +728,10 @@ async function preview() {
         targetUrl: `http://localhost:${running.appPort}`,
         url: running.url,
         consoleUrl: await projectConsoleUrl(cwd, running.sessionId),
+        feedbackOrigin: running.consoleOrigin !== undefined &&
+            running.consoleOrigin !== new URL(DEFAULT_CONSOLE_URL).origin
+            ? running.consoleOrigin
+            : undefined,
         qr,
         expiresInHours: 12,
     })) {

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>;

package/dist/relay/server.js

@@ -10,6 +10,8 @@ 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 { isConsolePreflight, preflightHeaders, responseHeaders, } from "./consoleOrigin.js";
+import { boundedSpec } from "./specBounds.js";
 import { VIEWER_LABEL_RE, VIEWER_STAMP_HEADER } from "../tunnel/index.js";
 /** Cap an annotation POST body so a bad/huge upload can't exhaust memory. */
 const MAX_ANNOTATION_BYTES = 25 * 1024 * 1024;
@@ -56,6 +58,7 @@ export function startRelay(opts = {}) {
         host,
         port: boundPort(),
         allowedOrigins,
+        consoleOrigin: opts.consoleOrigin,
         token: opts.token,
         store,
         annotations,
@@ -208,9 +211,22 @@ function handleHttp(req, res, ctx) {
         res.writeHead(403).end();
         return;
     }
+    const annotationRoute = p === `${ctx.wsPath}/annotation`;
+    // The console origin is matched HERE, inside the annotation route, and never
+    // joins the origin list: that list also gates the WebSocket, and a console
+    // page reaching the diagnostics socket is the hole this placement closes.
+    // Exact string equality, so `null`, a duplicated header, a trailing slash and
+    // a case variant all miss.
+    const fromConsole = annotationRoute &&
+        ctx.consoleOrigin !== undefined &&
+        req.headers.origin === ctx.consoleOrigin;
+    if (annotationRoute && req.method === "OPTIONS") {
+        handlePreflight(req, res, ctx, fromConsole);
+        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)) {
+    if (!fromConsole && !isAllowedOrigin(req.headers.origin, origins)) {
         ctx.log("refused a request from a foreign Origin");
         res.writeHead(403).end();
         return;
@@ -221,6 +237,26 @@ function handleHttp(req, res, ctx) {
             return;
         }
     }
+    // On EVERY status from here, so the console can read a refusal as well as a
+    // 200 and never retries an annotation the relay already stored.
+    if (fromConsole) {
+        for (const [k, v] of Object.entries(responseHeaders(ctx.consoleOrigin))) {
+            res.setHeader(k, v);
+        }
+    }
+    if (annotationRoute && req.method === "GET") {
+        // The console's probe: presence only, and it writes nothing.
+        if (!fromConsole) {
+            res.writeHead(405).end();
+            return;
+        }
+        res.writeHead(ctx.annotations ? 204 : 503).end();
+        return;
+    }
+    if (annotationRoute && req.method !== "POST") {
+        res.writeHead(405).end();
+        return;
+    }
     if (req.method === "POST" && !isJsonContentType(req.headers["content-type"])) {
         res.writeHead(415).end();
         return;
@@ -229,7 +265,9 @@ function handleHttp(req, res, ctx) {
         handleQuery(req, res, url, ctx);
         return;
     }
-    if (p === `${ctx.wsPath}/annotation`) {
+    if (annotationRoute) {
+        if (fromConsole)
+            ctx.log("annotation from the console origin");
         handleAnnotationPost(req, res, ctx);
         return;
     }
@@ -239,6 +277,27 @@ function handleHttp(req, res, ctx) {
     }
     res.writeHead(404).end();
 }
+/**
+ * The console's CORS preflight on the annotation route. Answered only for the
+ * exact console origin asking for POST with at most `content-type`; anything
+ * else is 403 with no CORS header at all. Never `*`, never credentials, never a
+ * private-network grant.
+ */
+function handlePreflight(req, res, ctx, fromConsole) {
+    if (!fromConsole) {
+        ctx.log("refused a preflight from a foreign Origin");
+        res.writeHead(403).end();
+        return;
+    }
+    const ok = isConsolePreflight(req.headers["access-control-request-method"], req.headers["access-control-request-headers"]);
+    if (!ok) {
+        ctx.log("refused a console preflight for a method or header it does not allow");
+        res.writeHead(403).end();
+        return;
+    }
+    ctx.log("answered a console preflight");
+    res.writeHead(204, preflightHeaders(ctx.consoleOrigin)).end();
+}
 // 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) {
@@ -279,6 +338,16 @@ function handleAnnotationPost(req, res, ctx) {
             res.writeHead(400).end("annotation requires message + screenshot");
             return;
         }
+        // Refused, never clamped: the agent acts on these values, and a stored
+        // coordinate must be exactly the one that was sent.
+        // What is stored is the spec REBUILT from the checked fields, never the
+        // body's own object: an unknown key would otherwise ride to the agent.
+        const bounded = boundedSpec(input);
+        if (!bounded.ok) {
+            ctx.log("refused marks out of bounds");
+            res.writeHead(400).end("annotation marks out of bounds");
+            return;
+        }
         // The annotation's session key is RESOLVED, never assigned — `resolve`,
         // not `attribute`. This route is unauthenticated and reachable by anyone
         // holding the capability URL, so a door that minted here would let 64 bare
@@ -288,7 +357,12 @@ function handleAnnotationPost(req, res, ctx) {
         // The key is still hostile input either way: the record reaches an agent's
         // context on the consumer's stdout, so the raw string must never survive
         // onto it.
-        const annotation = await ctx.annotations.add({ ...input, sessionId: ctx.testers.resolve(input.sessionId) }, { now: Date.now(), id: ctx.makeId() });
+        const annotation = await ctx.annotations.add({
+            message: input.message,
+            screenshot: input.screenshot,
+            spec: bounded.spec,
+            sessionId: ctx.testers.resolve(input.sessionId),
+        }, { now: Date.now(), id: ctx.makeId() });
         // The live stream is told an annotation ARRIVED, with the resolved tester
         // and nothing else. It is a fact, not a directive: the consumer is the
         // long-poll, and a terminal line naming what to run would be the platform
@@ -299,7 +373,11 @@ function handleAnnotationPost(req, res, ctx) {
             .end(JSON.stringify({ id: annotation.id, seq: annotation.seq }));
     })
         .catch((err) => {
-        ctx.log(`annotation error: ${err}`);
+        // A fixed line, never the error's text: a JSON.parse message quotes the
+        // body, which is hostile input, and this log reaches the terminal.
+        ctx.log(err instanceof SyntaxError
+            ? "annotation error: the body is not JSON"
+            : "annotation error: not stored (too large, or the write failed)");
         if (!res.headersSent)
             res.writeHead(400).end();
     });
@@ -397,9 +475,14 @@ async function readQuery(req, url) {
         q.presence = true;
     return normalizeTester(q);
 }
-function readBody(req, maxBytes = Infinity) {
+/**
+ * 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 function readBody(req, maxBytes = Infinity) {
     return new Promise((resolve, reject) => {
-        let data = "";
+        const chunks = [];
         let bytes = 0;
         req.on("data", (c) => {
             bytes += c.length;
@@ -408,9 +491,9 @@ function readBody(req, maxBytes = Infinity) {
                 req.destroy();
                 return;
             }
-            data += c;
+            chunks.push(c);
         });
-        req.on("end", () => resolve(data));
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
         req.on("error", reject);
     });
 }

package/dist/relay/specBounds.d.ts

@@ -0,0 +1,39 @@
+import type { AnnotationInput, AnnotationSpec } from "@vincentt-xr/harness/events";
+export declare const COORD_MIN = -1;
+export declare const COORD_MAX = 2;
+export declare const MAX_SHAPES = 50;
+export declare const MAX_STROKES = 50;
+export declare const MAX_PINS = 50;
+export declare const MAX_LABELS = 50;
+export declare const MAX_PATH_POINTS = 500;
+export declare const MAX_NOTE_CHARS = 2000;
+export declare const MAX_MESSAGE_CHARS = 110000;
+/** The mark colours every sender draws with: the keys of the harness's MARK_COLORS. */
+export declare const MARK_COLOR_NAMES: ReadonlySet<string>;
+/**
+ * The width and height a PNG data URL's IHDR declares, or undefined when it is
+ * not a PNG data URL. Reads only the first 24 decoded bytes; never decodes the
+ * image.
+ */
+export declare function pngSize(dataUrl: string): {
+    width: number;
+    height: number;
+} | undefined;
+/** Refused, or in bounds with the `spec` to store (undefined when none was sent). */
+export type BoundedSpec = {
+    ok: false;
+} | {
+    ok: true;
+    spec?: AnnotationSpec;
+};
+/**
+ * Check an annotation's message and marks, and rebuild `spec` from the fields
+ * that passed. Assumes the caller already checked `message` and `screenshot` are
+ * strings.
+ *
+ * `spec` absent, `{}` and `{shapes: []}` are all in bounds. A field the relay
+ * does not know is not an error; it is simply not stored.
+ */
+export declare function boundedSpec(input: AnnotationInput): BoundedSpec;
+/** Whether an annotation's message and marks are within bounds. */
+export declare function isWithinBounds(input: AnnotationInput): boolean;

package/dist/relay/specBounds.js

@@ -0,0 +1,157 @@
+// The annotation's marks are hostile input the agent then acts on, from any
+// sender: the phone, the console, or anyone holding the preview address. The
+// relay refuses an annotation outside these bounds rather than clamping it, and
+// stores a `spec` REBUILT from the fields it checked: an unknown key is dropped,
+// so what reaches the agent is exactly what was validated, value for value.
+//
+// Coordinates are picture-relative: [0,1] spans the picture and a value outside
+// it is a point past the picture's edge. No sender's drawing margin reaches past
+// [-1, 2].
+export const COORD_MIN = -1;
+export const COORD_MAX = 2;
+export const MAX_SHAPES = 50;
+export const MAX_STROKES = 50;
+export const MAX_PINS = 50;
+export const MAX_LABELS = 50;
+export const MAX_PATH_POINTS = 500;
+export const MAX_NOTE_CHARS = 2_000;
+export const MAX_MESSAGE_CHARS = 110_000;
+/** The mark colours every sender draws with: the keys of the harness's MARK_COLORS. */
+export const MARK_COLOR_NAMES = new Set(["red", "yellow", "blue"]);
+/**
+ * A legacy stroke's colour, which an app could set itself: a mark colour name, a
+ * hex colour, or one short lowercase word. Never free text.
+ */
+const STROKE_COLOR_RE = /^(?:#[0-9a-fA-F]{3,8}|[a-z]{1,16})$/;
+const SHAPE_TYPES = new Set(["rect", "circle", "arrow", "pen"]);
+const PNG_PREFIX = "data:image/png;base64,";
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+/** Thrown inside the rebuild; never escapes `boundedSpec`. */
+class Refused extends Error {
+}
+const refuse = () => {
+    throw new Refused();
+};
+const isRec = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const coord = (v) => typeof v === "number" && Number.isFinite(v) && v >= COORD_MIN && v <= COORD_MAX
+    ? v
+    : refuse();
+const size = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : refuse();
+const point = (v) => isRec(v) ? { x: coord(v.x), y: coord(v.y) } : refuse();
+const text = (v) => typeof v === "string" && v.length <= MAX_NOTE_CHARS ? v : refuse();
+const list = (v, max) => Array.isArray(v) && v.length <= max ? v : refuse();
+const path = (v) => list(v, MAX_PATH_POINTS).map(point);
+function shape(v) {
+    if (!isRec(v))
+        return refuse();
+    if (typeof v.type !== "string" || !SHAPE_TYPES.has(v.type))
+        return refuse();
+    const n = typeof v.n === "number" && Number.isInteger(v.n) && v.n >= 1 && v.n <= MAX_SHAPES
+        ? v.n
+        : refuse();
+    const color = typeof v.color === "string" && MARK_COLOR_NAMES.has(v.color) ? v.color : refuse();
+    const base = { n, color, ...(v.note === undefined ? {} : { note: text(v.note) }) };
+    if (v.type === "arrow")
+        return { ...base, type: "arrow", from: point(v.from), to: point(v.to) };
+    if (v.type === "pen")
+        return { ...base, type: "pen", points: path(v.points) };
+    const [x, y, w, h] = [coord(v.x), coord(v.y), size(v.w), size(v.h)];
+    // The far corner is a coordinate too. Its sum carries float error, so it alone
+    // gets a hair of tolerance; every coordinate a sender wrote is checked exactly.
+    if (x + w > COORD_MAX + 1e-9 || y + h > COORD_MAX + 1e-9)
+        return refuse();
+    return { ...base, type: v.type, x, y, w, h };
+}
+function stroke(v) {
+    if (!isRec(v))
+        return refuse();
+    const out = { points: path(v.points) };
+    if (v.color !== undefined) {
+        if (typeof v.color !== "string" || !STROKE_COLOR_RE.test(v.color))
+            return refuse();
+        out.color = v.color;
+    }
+    return out;
+}
+function pin(v) {
+    if (!isRec(v))
+        return refuse();
+    const out = { x: coord(v.x), y: coord(v.y) };
+    if (v.label !== undefined)
+        out.label = text(v.label);
+    return out;
+}
+/**
+ * The width and height a PNG data URL's IHDR declares, or undefined when it is
+ * not a PNG data URL. Reads only the first 24 decoded bytes; never decodes the
+ * image.
+ */
+export function pngSize(dataUrl) {
+    if (!dataUrl.startsWith(PNG_PREFIX))
+        return undefined;
+    // 32 base64 characters decode to exactly the 24 header bytes.
+    const head = Buffer.from(dataUrl.slice(PNG_PREFIX.length, PNG_PREFIX.length + 32), "base64");
+    if (head.length < 24)
+        return undefined;
+    if (!PNG_SIGNATURE.every((b, i) => head[i] === b))
+        return undefined;
+    if (head.toString("latin1", 12, 16) !== "IHDR")
+        return undefined;
+    return { width: head.readUInt32BE(16), height: head.readUInt32BE(20) };
+}
+function frameInImage(v, screenshot) {
+    if (!isRec(v))
+        return refuse();
+    const { x, y, w, h } = v;
+    if (![x, y, w, h].every((n) => typeof n === "number" && Number.isInteger(n)))
+        return refuse();
+    const [fx, fy, fw, fh] = [x, y, w, h];
+    if (fx < 0 || fy < 0 || fw < 1 || fh < 1)
+        return refuse();
+    const image = pngSize(screenshot) ?? refuse();
+    if (fx + fw > image.width || fy + fh > image.height)
+        return refuse();
+    return { x: fx, y: fy, w: fw, h: fh };
+}
+/**
+ * Check an annotation's message and marks, and rebuild `spec` from the fields
+ * that passed. Assumes the caller already checked `message` and `screenshot` are
+ * strings.
+ *
+ * `spec` absent, `{}` and `{shapes: []}` are all in bounds. A field the relay
+ * does not know is not an error; it is simply not stored.
+ */
+export function boundedSpec(input) {
+    if (input.message.length > MAX_MESSAGE_CHARS)
+        return { ok: false };
+    const raw = input.spec;
+    if (raw === undefined)
+        return { ok: true };
+    try {
+        if (!isRec(raw))
+            return refuse();
+        const spec = {};
+        if (raw.shapes !== undefined)
+            spec.shapes = list(raw.shapes, MAX_SHAPES).map(shape);
+        if (raw.strokes !== undefined)
+            spec.strokes = list(raw.strokes, MAX_STROKES).map(stroke);
+        if (raw.pins !== undefined)
+            spec.pins = list(raw.pins, MAX_PINS).map(pin);
+        if (raw.labels !== undefined)
+            spec.labels = list(raw.labels, MAX_LABELS).map(text);
+        if (raw.note !== undefined)
+            spec.note = text(raw.note);
+        if (raw.frameInImage !== undefined)
+            spec.frameInImage = frameInImage(raw.frameInImage, input.screenshot);
+        return { ok: true, spec };
+    }
+    catch (err) {
+        if (err instanceof Refused)
+            return { ok: false };
+        throw err;
+    }
+}
+/** Whether an annotation's message and marks are within bounds. */
+export function isWithinBounds(input) {
+    return boundedSpec(input).ok;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincentt-xr/cli",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Vincentt CLI — the vincentt command-line dev loop (login, create, publish, preview, diagnostics, feedback, relay)",
   "license": "UNLICENSED",
   "type": "module",
@@ -28,7 +28,7 @@
     "qrcode": "^1.5.4",
     "ws": "^8.18.0",
     "zod": "^3.23.8",
-    "@vincentt-xr/harness": "3.1.0"
+    "@vincentt-xr/harness": "3.2.0"
   },
   "devDependencies": {
     "@types/qrcode": "^1.5.5",