@vincentt-xr/cli 0.22.0 → 0.24.0

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.22.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.0.0"
+    "@vincentt-xr/harness": "3.2.0"
   },
   "devDependencies": {
     "@types/qrcode": "^1.5.5",