@vincentt-xr/harness 1.0.0 → 1.1.0

package/dist/client/HarnessProvider.d.ts

@@ -12,7 +12,13 @@ export interface HarnessProviderProps {
      * app). Override for the production review-service sink.
      */
     relayUrl?: string;
-    /** Session id grouping this preview run's events. Defaults to a per-load id. */
+    /**
+     * The key grouping this tab's events into one TESTER. Defaults to a per-tab
+     * CSPRNG id in `sessionStorage`, which is what you want; override only for the
+     * production review-service path. A value passed here is client-supplied input
+     * like any other — the relay validates it and never renders it, and passing
+     * another tab's value merges the two into one tester.
+     */
     sessionId?: string;
     captureConsole?: boolean;
     captureNetwork?: boolean;
@@ -23,4 +29,35 @@ export interface HarnessProviderProps {
      */
     feedback?: boolean;
 }
+/**
+ * 128 bits of CSPRNG, hex, as `s2_<32 hex>`.
+ *
+ * There is deliberately NO Math.random fallback. The previous generator's ~10^6
+ * space is exactly what this replaces, and a fallback reintroducing it would be
+ * the branch that actually runs on the oldest phone in the room. Both paths here
+ * are Web Crypto: randomUUID where it exists, getRandomValues otherwise — and
+ * getRandomValues has been in every browser that can run this app for a decade.
+ * If neither exists we throw rather than guess, because a weak id is a SILENT
+ * merge of two testers' streams, and no id at all is merely un-attributed.
+ */
+export declare function generateClientSessionId(): string;
+/** The slice of Storage this needs — so the rule below is testable without a DOM. */
+export interface SessionIdStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+/**
+ * The key the relay groups this tab's events by — one TESTER.
+ *
+ * `sessionStorage`, not `localStorage`, and the choice is load-bearing on both
+ * ends: it is per TAB (so one QR scan is one tester even though the tab opens a
+ * second connection for assets) and it DIES WITH THE TAB (so the grouping is
+ * bounded by construction rather than by a rule someone has to remember, and
+ * cannot outlive the session's terminal window).
+ *
+ * A stored value that misses the current grammar is OVERWRITTEN, not migrated:
+ * it was minted at the entropy this replaces. The rewrite happens here at mount,
+ * before the first batch, so no id is ever renumbered mid-run.
+ */
+export declare function resolveClientSessionId(storage: SessionIdStorage | undefined): string;
 export declare function HarnessProvider(props: HarnessProviderProps): ReactNode;

package/dist/client/HarnessProvider.js

@@ -8,6 +8,7 @@
 // accident. The relay URL and session id default to what the preview loop sets,
 // but both are overridable for the production review-service path later.
 import { useEffect } from "react";
+import { CLIENT_SESSION_ID_RE } from "../shared/events.js";
 function defaultRelayUrl() {
     if (typeof window === "undefined")
         return "ws://localhost:7331";
@@ -16,19 +17,56 @@ function defaultRelayUrl() {
     // so one cloudflared tunnel carries both. The relay CLI serves this path.
     return `${proto}://${window.location.host}/__harness`;
 }
+const SESSION_STORAGE_KEY = "__vincentt_harness_session";
+/**
+ * 128 bits of CSPRNG, hex, as `s2_<32 hex>`.
+ *
+ * There is deliberately NO Math.random fallback. The previous generator's ~10^6
+ * space is exactly what this replaces, and a fallback reintroducing it would be
+ * the branch that actually runs on the oldest phone in the room. Both paths here
+ * are Web Crypto: randomUUID where it exists, getRandomValues otherwise — and
+ * getRandomValues has been in every browser that can run this app for a decade.
+ * If neither exists we throw rather than guess, because a weak id is a SILENT
+ * merge of two testers' streams, and no id at all is merely un-attributed.
+ */
+export function generateClientSessionId() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return `s2_${c.randomUUID().replace(/-/g, "")}`;
+    if (c?.getRandomValues) {
+        const bytes = c.getRandomValues(new Uint8Array(16));
+        let hex = "";
+        for (const b of bytes)
+            hex += b.toString(16).padStart(2, "0");
+        return `s2_${hex}`;
+    }
+    throw new Error("harness: Web Crypto unavailable; cannot mint a session id");
+}
+/**
+ * The key the relay groups this tab's events by — one TESTER.
+ *
+ * `sessionStorage`, not `localStorage`, and the choice is load-bearing on both
+ * ends: it is per TAB (so one QR scan is one tester even though the tab opens a
+ * second connection for assets) and it DIES WITH THE TAB (so the grouping is
+ * bounded by construction rather than by a rule someone has to remember, and
+ * cannot outlive the session's terminal window).
+ *
+ * A stored value that misses the current grammar is OVERWRITTEN, not migrated:
+ * it was minted at the entropy this replaces. The rewrite happens here at mount,
+ * before the first batch, so no id is ever renumbered mid-run.
+ */
+export function resolveClientSessionId(storage) {
+    const existing = storage?.getItem(SESSION_STORAGE_KEY);
+    if (existing && CLIENT_SESSION_ID_RE.test(existing))
+        return existing;
+    const id = generateClientSessionId();
+    storage?.setItem(SESSION_STORAGE_KEY, id);
+    return id;
+}
 function defaultSessionId() {
     if (typeof window === "undefined")
         return "server";
-    const key = "__vincentt_harness_session";
-    const existing = window.sessionStorage?.getItem(key);
-    if (existing)
-        return existing;
-    // Per-load id; not security-sensitive, just needs to be distinct enough that
-    // two phones on one relay don't collide. No Math.random dependency in the
-    // pure layer — this imperative shell may use it.
-    const id = `s_${Date.now().toString(36)}_${Math.floor(Math.random() * 1e6).toString(36)}`;
-    window.sessionStorage?.setItem(key, id);
-    return id;
+    return resolveClientSessionId(window.sessionStorage);
 }
 const DEV = typeof import.meta !== "undefined" &&
     import.meta.env?.DEV;
@@ -59,7 +97,14 @@ export function HarnessProvider(props) {
             void import("./annotate.js").then(({ mountFeedbackButton }) => {
                 if (cancelled)
                     return;
-                unmountFeedback = mountFeedbackButton({ sessionId: props.sessionId });
+                // The SAME resolved key the instrumentation sends, not the bare prop.
+                // The prop is undefined for every app that does not set it — i.e. the
+                // default — so passing it through left every real annotation
+                // un-attributed while the tests, which build the input by hand, never
+                // exercised this line.
+                unmountFeedback = mountFeedbackButton({
+                    sessionId: props.sessionId ?? defaultSessionId(),
+                });
             });
         }
         return () => {

package/dist/shared/events.d.ts

@@ -1,5 +1,30 @@
 /** Monotonic-ish wall-clock ms since epoch, stamped by the client at capture. */
 export type Timestamp = number;
+/**
+ * The grammar of the client's session id — the key the relay groups a TESTER by.
+ *
+ * It lives here, in the file all three parts import, for the same reason
+ * VIEWER_LABEL_RE lives beside the codec that produces the label: the party that
+ * mints the value and the party that validates it must not be able to disagree
+ * about its shape. The client writes this shape; the relay accepts this shape and
+ * nothing else, with no sanitize-and-keep branch.
+ *
+ * `s2_` is generation two. Generation one was `s_<base36 time>_<base36 rand>` over
+ * ~10^6 of Math.random, which grouped a RUN. Grouping a TESTER makes a collision a
+ * silent merge of two people's streams, so the space is now 128 bits and the
+ * prefix is what lets a relay tell the two generations apart on sight.
+ */
+export declare const CLIENT_SESSION_ID_RE: RegExp;
+/**
+ * A relay-assigned tester id: `t1`, `t2`, … Minted on the CREATOR'S machine and
+ * never on the wire from the device — it is a local relabeling of a key the
+ * device supplied, which is what keeps the platform free of a correlator (B22).
+ *
+ * No leading zero. Ids are counted from 1 and never zero-padded, so `t01` is a
+ * string the registry cannot have produced; accepting it at the filter boundary
+ * would admit a second spelling for a value with one canonical form.
+ */
+export declare const TESTER_ID_RE: RegExp;
 /** Kinds of thing the diagnostics limb observes. */
 export type DiagEventKind = "log" | "network" | "trace";
 interface DiagEventBase {
@@ -62,18 +87,69 @@ export interface ClientToRelay {
 }
 /** What the MCP server asks the relay for. `since` is an exclusive seq cursor. */
 export interface RelayQuery {
-    sessionId?: string;
     kind?: DiagEventKind;
     since?: number;
     /** Cap the returned count (newest-biased); relay clamps to its buffer size. */
     limit?: number;
+    /**
+     * Filter to one TESTER — one browser tab, recognised across refreshes. This is
+     * the filter that answers "it breaks on their phone but not mine", because it
+     * survives the reload the tester does first.
+     *
+     * A malformed id filters to NOTHING rather than being ignored: silently
+     * widening a filter shows the creator several testers' events under a heading
+     * naming one.
+     */
+    tester?: string;
+    /**
+     * Filter to one viewer — one CONNECTION (2.8), not an identity (B22). The
+     * sub-coordinate below the tester: a single tab opens several of these under
+     * HTTP/1.1, so this narrows to one of them and is for connection-level
+     * debugging rather than for "whose phone".
+     */
+    viewer?: string;
 }
 export interface RelayResult {
     events: DiagEvent[];
+    /**
+     * `eventViewers[i]` is the label that produced `events[i]`, or undefined when
+     * the relay could not attribute it.
+     *
+     * It rides ALONGSIDE the events rather than on them because a viewer label is
+     * a fact about the CONNECTION that carried an observation, not a property of
+     * the observation — putting it on the event would make it look like something
+     * the device reported about itself, which is the identity promotion B22
+     * forbids.
+     */
+    eventViewers?: (string | undefined)[];
+    /**
+     * `eventTesters[i]` is the tester that produced `events[i]`, or undefined when
+     * the relay could not attribute it (the pre-mount window, a crashed app, a
+     * non-app request, or a session past the cap).
+     *
+     * Rides alongside for the same reason as `eventViewers`: which tester an
+     * observation came from is a fact about the CONNECTION that carried it, not a
+     * property of the observation.
+     */
+    eventTesters?: (string | undefined)[];
     /** Highest seq the relay currently holds, so the caller can advance `since`. */
     latestSeq: number;
-    /** Sessions the relay has seen events for (so the agent can disambiguate). */
-    sessions: string[];
+    /**
+     * Tester ids the relay has assigned, in arrival order. Every member matches
+     * TESTER_ID_RE.
+     *
+     * This REPLACED a `sessions` array that carried the raw client-supplied key to
+     * the terminal and to MCP tool output. That was a viewer-controlled string
+     * with no validation reaching the creator's coding agent — do not reintroduce
+     * it. The raw key is an opaque map key inside the relay and nothing else.
+     */
+    testers: string[];
+    /**
+     * Viewer labels the relay has seen. Labels churn — a reconnecting device gets
+     * a NEW label and the old one is never reused — so the caller needs the live
+     * set rather than remembering one.
+     */
+    viewers: string[];
 }
 /** A freehand stroke over the frame, in normalized [0,1] frame coordinates. */
 export interface AnnotationStroke {
@@ -105,7 +181,12 @@ export interface AnnotationInput {
     /** Annotated frame as a data URL (image/png). */
     screenshot: string;
     spec?: AnnotationSpec;
-    /** Optional preview session id, to correlate with diag events. */
+    /**
+     * The client's session key, so the annotation can be correlated with the diag
+     * events from the same tab. Client-supplied and therefore hostile input: the
+     * relay REPLACES it with the tester id it resolves to, or drops it. It is
+     * never persisted or forwarded verbatim — this record reaches an agent.
+     */
     sessionId?: string;
 }
 /** A persisted annotation the agent consumes (via `vincentt feedback --wait`). */
@@ -123,6 +204,10 @@ export interface Annotation {
     /** Absolute path to the full-res annotated screenshot on disk. */
     screenshotPath: string;
     spec: AnnotationSpec;
+    /**
+     * The TESTER this annotation came from, or absent when the relay could not
+     * attribute it. Never the raw client key — see AnnotationInput.sessionId.
+     */
     sessionId?: string;
 }
 export {};

package/dist/shared/events.js

@@ -3,4 +3,28 @@
 // server (which serves them to the agent). All three import THIS file, so the
 // three can never drift on the shape of an event. Nothing here imports React,
 // node, or MCP — it is pure data.
-export {};
+/**
+ * The grammar of the client's session id — the key the relay groups a TESTER by.
+ *
+ * It lives here, in the file all three parts import, for the same reason
+ * VIEWER_LABEL_RE lives beside the codec that produces the label: the party that
+ * mints the value and the party that validates it must not be able to disagree
+ * about its shape. The client writes this shape; the relay accepts this shape and
+ * nothing else, with no sanitize-and-keep branch.
+ *
+ * `s2_` is generation two. Generation one was `s_<base36 time>_<base36 rand>` over
+ * ~10^6 of Math.random, which grouped a RUN. Grouping a TESTER makes a collision a
+ * silent merge of two people's streams, so the space is now 128 bits and the
+ * prefix is what lets a relay tell the two generations apart on sight.
+ */
+export const CLIENT_SESSION_ID_RE = /^s2_[0-9a-f]{32}$/;
+/**
+ * A relay-assigned tester id: `t1`, `t2`, … Minted on the CREATOR'S machine and
+ * never on the wire from the device — it is a local relabeling of a key the
+ * device supplied, which is what keeps the platform free of a correlator (B22).
+ *
+ * No leading zero. Ids are counted from 1 and never zero-padded, so `t01` is a
+ * string the registry cannot have produced; accepting it at the filter boundary
+ * would admit a second spelling for a value with one canonical form.
+ */
+export const TESTER_ID_RE = /^t[1-9][0-9]{0,2}$/;

package/dist/tunnel/cbor.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The CBOR SUBSET, Node half. It mirrors `api/internal/edge/cbor.go` decision
+ * for decision, because two implementations of one wire format that were
+ * written independently are two implementations that drift.
+ *
+ * It decodes CONTROL payloads only — OPEN and HEAD. It NEVER touches a DATA
+ * payload.
+ *
+ * It is hand-written rather than a library for the same reason the Go one is: a
+ * general CBOR library's allocation behavior on hostile input would be someone
+ * else's decision, and the limits below are the whole point.
+ *
+ * Everything indefinite-length, every tag, every float, every byte string and
+ * every negative integer is REFUSED — not because they are dangerous in
+ * themselves, but because the encoder we own never emits them, so accepting
+ * them would only widen the input this parser has to be correct about.
+ */
+/**
+ * VIEWER_LABEL_RE is the SAME regex the edge assigns against, and this client
+ * RE-VALIDATES rather than trusting the edge. That is closure (c) of the three
+ * that keep viewer-supplied bytes out of the creator's agent's context: the
+ * label flows viewerLabel -> the relay ring-buffer key -> CLI terminal output
+ * and MCP tool output, which is a terminal/log-injection path INTO the agent,
+ * and a Go-only check would pass on a client that trusted the edge.
+ */
+export declare const VIEWER_LABEL_RE: RegExp;
+export declare function parseViewerLabel(s: string): string | null;
+/**
+ * UA_CLASSES is the CLOSED ENUM OF SIX, mirroring the Go edge. `unknown` is the
+ * TOTAL fallback. This client validates the class it receives against this set
+ * before stamping the relay handshake, so an unmatched or forged class becomes
+ * `unknown` rather than an echo.
+ */
+export declare const UA_CLASSES: readonly ["ios_safari", "android_chrome", "desktop_chrome", "desktop_safari", "desktop_firefox", "unknown"];
+export type UAClass = (typeof UA_CLASSES)[number];
+export declare function parseUAClass(s: string): UAClass;
+export interface OpenPayload {
+    viewerLabel: string;
+    method: string;
+    path: string;
+    headers: [string, string][];
+    upgrade?: string;
+}
+export interface HeadPayload {
+    status: number;
+    headers: [string, string][];
+}
+/**
+ * `viewer_gone` is the ONE non-terminal kind: the other three mean the session
+ * is ending, this one means a viewer's connection closed while the session
+ * continues. It is also the only kind carrying a second key.
+ */
+export type ControlKind = "revoke" | "expiring" | "superseded" | "viewer_gone";
+/** A decoded CONTROL payload. `viewerLabel` is present only on `viewer_gone`. */
+export interface ControlPayload {
+    kind: ControlKind;
+    viewerLabel?: string;
+}
+export declare function decodeOpen(b: Uint8Array): OpenPayload;
+export declare function decodeHead(b: Uint8Array): HeadPayload;
+/**
+ * The map arity is asserted AGAINST THE KIND, so a payload claiming `revoke`
+ * with a trailing label is refused as malformed rather than quietly accepted
+ * with the extra key ignored.
+ */
+export declare function decodeControl(b: Uint8Array): ControlPayload;
+/** Canonical key order: viewerLabel, method, path, headers, [upgrade]. */
+export declare function encodeOpen(p: OpenPayload): Uint8Array;
+/** Canonical key order: status, headers. */
+export declare function encodeHead(p: HeadPayload): Uint8Array;
+export declare function encodeControl(kind: ControlKind, viewerLabel?: string): Uint8Array;