@weatherboard/annotation 0.1.0 → 0.2.1

package/ADOPTING.md

@@ -128,6 +128,42 @@ Four details, each of which has cost somebody a day:
   plain http — so a local `next dev` would set a cookie the browser silently
   discards. Fall back to `Lax`, which is same-origin anyway.
 
+### First-party, the cookie is an ordinary one — use `armedCookie()` (A-241)
+
+Everything above describes the **framed** surface. When the console links out to
+your product instead of framing it, the reviewer is top-level at your own origin
+and none of the cross-site reasoning applies: `SameSite=None` is wrong there,
+and it is the spelling that would break on its own under Chrome's third-party
+cookie work.
+
+Do not re-derive the attributes. `@weatherboard/annotation/protocol` exports the
+cookie itself, so the two halves cannot disagree:
+
+```ts
+import { armedCookie, clearedCookie, ANNOTATION_ARMED_COOKIE } from "@weatherboard/annotation/protocol";
+
+// after YOUR comparison against YOUR secret has succeeded, and only then:
+response.headers.append("set-cookie", armedCookie());
+```
+
+It takes no value argument on purpose — the cookie holds a marker, never the
+token, and the first bullet above is the reason. The page half calls
+`readArming()`, which reads that cookie, strips the tokens out of the URL with
+`replaceState`, and hands the capture token to `httpTransport`.
+
+*Done* is a full teardown, not just a disarm: it writes
+`clearedCookie(...)` for both spellings, drops the stored capture token, removes
+the toolbar host and the SDK's overlay from your DOM, and leaves nothing on the
+page that can capture again without re-arming through the deep link. Mount it
+once per page load and let *Done* end the session; there is nothing for you to
+clean up.
+
+**Send `Referrer-Policy: strict-origin` too.** `readArming` strips the query as
+early as script can run, and there is a window before that: anything in your
+document's `<head>` is requested first and carries the full token-bearing URL to
+your own origin as `Referer`. Measured, not assumed — see the header of
+`arming.ts`. Only a response header closes it, and only you can send one.
+
 `readAnnotationToken` returns the **value**, not a boolean, and returns `null`
 for an absent *or empty* parameter. Compare it yourself: only you hold the
 secret.

package/COMPATIBILITY.md

@@ -0,0 +1,97 @@
+# Compatibility
+
+**At one consumer, a protocol change is a coordinated deploy. At a hundred, it is
+a hundred upgrades that will not happen at the same time — and some that will not
+happen at all.**
+
+This page is the promise that makes that survivable, and the rules are enforced
+by tests rather than by good intentions. See `fixtures/README.md`.
+
+---
+
+## The four rules
+
+### 1. Fields are added, never repurposed
+
+A new field is **optional**, and **absent means what every existing capture
+already meant**.
+
+```ts
+selection?: "element" | "region";   // absent === "element"
+```
+
+Required-with-a-default has the same shape and a worse failure: an older bundle
+omits it, the type says it is there, and every reader believes a value nobody
+sent. That is not a bug anyone catches — it is a confident wrong answer.
+
+Changing what an existing field *means*, while leaving its type alone, is the
+same violation wearing a disguise. It is invisible to a type checker, which is
+why the fixtures exist.
+
+### 2. A reader accepts every version it has ever accepted
+
+Until a deliberate, separate removal — its own change, with its own argument.
+
+Dropping support is not a side effect of adding something.
+
+### 3. A writer emits both spellings during a migration, never only the new one
+
+Until every consumer is known to be past it. "Known", not assumed: for a
+published package that means evidence, and for anything less than evidence it
+means keep writing both.
+
+`ANNOTATION_TOKEN_PARAMS` and `ANNOTATION_ARMED_COOKIES` are this rule in code —
+ordered lists, current first, and readers take the first match.
+
+### 4. `schemaVersion` bumps only for what the rules above cannot express
+
+And a bump is an **event**, not a routine. A consumer on the old version is
+refused rather than guessed at — see `validateCapture`, which fails a mismatched
+version *before reading any field*, because a newer payload may have moved the
+one field the capture exists to carry.
+
+If you are reaching for a bump, check first that you are not really reaching for
+rule 1.
+
+---
+
+## The rename that is not happening again
+
+`ai_annotate` and `ai_annotate_armed` replaced a product-specific spelling, and
+readers still accept the old one. **There will not be a third.**
+
+Publishing as `@weatherboard/annotation` makes it tempting to match the names to
+the package. A third spelling does not *replace* the second while the migration
+is unfinished — it **joins** it. Three names accepted, three emitted, and the
+window in which a consumer can be on any of them widens instead of closing.
+
+Two is a migration. Three is a habit, and the third would be paid for by
+consumers who never asked for either. A published package needs names that name
+no product; it does not need names that name the package.
+
+There is a test asserting both lists are exactly two entries long, so a third
+fails there — with this argument attached — rather than in somebody's bundle six
+weeks later.
+
+---
+
+## Why this is enforced with fixtures
+
+Every failure in this protocol is silent. A reader that stops accepting a shape
+does not throw: the page never announces itself, the frame waits forever, and
+nothing anywhere says why.
+
+So the enforcement is a **recorded payload per shipped shape**, replayed through
+every reader on every change. A type checker cannot see a meaning change that
+keeps the shape; a fixture that stops parsing can only mean one thing.
+
+Removing a legacy name fails those tests until its fixture is deliberately
+retired — which is the point. The cost of dropping support should be paid by
+whoever drops it, in the same change, and not by whoever finds out.
+
+---
+
+## Versioning
+
+`0.x` while the wire protocol is still moving. **1.0 is the statement that a
+hundred consumers can rely on it**, not a way to look finished.

package/README.md

@@ -98,12 +98,18 @@ captures all report no source ref, the transform is not running.
 
 ## Compatibility
 
+**[COMPATIBILITY.md](./COMPATIBILITY.md)** is the policy, and it is enforced by
+tests rather than by good intentions: fields are added and never repurposed, a
+reader accepts every version it has ever accepted, a writer emits both spellings
+through a migration, and `schemaVersion` bumps only for what those rules cannot
+express.
+
+Every shape ever sent is recorded in `fixtures/` — shipped in this package, so
+if you write your own reader you can replay them too.
+
 `0.x`. The wire protocol is still moving, and the version says so. The move to
 1.0 will be the statement that it has stopped — not a decision to look finished.
 
-Two of the wire names have a legacy spelling that readers still accept. See
-`protocol.ts`; they are not changing again.
-
 ## Licence
 
 MIT.

package/dist/arming.d.cts

@@ -0,0 +1,145 @@
+import { type BuildInfo } from "./protocol.cjs";
+/**
+ * Arming, and the production kill-switch (A-241).
+ *
+ * ===========================================================================
+ * THE SEQUENCE THIS FILE IS
+ * ===========================================================================
+ *
+ * The reviewer lands on `?ai_annotate=<arming>&ai_capture=<signed>&ai_run=<id>`
+ * from the console's *Request changes* button. This module is what happens in
+ * the first few milliseconds after that:
+ *
+ *   1. read the three parameters
+ *   2. **strip them from the URL** with `replaceState`, before anything else
+ *   3. answer *is this page armed* — from the COOKIE, never from the URL
+ *   4. only then, and only if armed, keep the capture token for the tab
+ *
+ * Step 3 is the runtime half of the kill-switch and step 2 is not decoration;
+ * both are argued at length below. Steps 3 and 4 were the other way round
+ * until A-254, which is how an unarmed page came to persist an
+ * attacker-supplied token — the argument, and the measurement that settled it,
+ * are at the gate itself in `readArming`.
+ *
+ * ===========================================================================
+ * TWO CREDENTIALS, AND THIS FILE TOUCHES THEM DIFFERENTLY ON PURPOSE
+ * ===========================================================================
+ *
+ * `docs/plans/first-party-annotation.md` § *Authentication* is the argument;
+ * what it means for this file is a table:
+ *
+ * | | who verifies it | what this module does with it |
+ * | --- | --- | --- |
+ * | arming token (`ai_annotate`) | the product's own middleware, against its `ANNOTATION_TOKEN_<PRODUCT>` | **nothing.** Reads the middleware's answer out of the cookie and drops the token |
+ * | capture token (`ai_capture`) | the console, on the way back in | couriers it: keeps it for the tab, hands it to `httpTransport` |
+ *
+ * **The URL parameter is not arming and this module never treats it as such.**
+ * That is the runtime gate, stated as a single sentence, and it is the reason
+ * `readArming` does not compare anything: page script holds no secret, so a
+ * page that armed itself because a token-shaped string was in its own query
+ * string would be armed by anyone who could type one. The middleware compares
+ * and sets a cookie; this reads the cookie. A wrong token therefore produces no
+ * cookie, and no cookie produces no toolbar — `arming.test.ts` asserts exactly
+ * that, and asserts it with a token-bearing URL present so it cannot pass by
+ * accident.
+ *
+ * ===========================================================================
+ * WHY THE TOKENS COME OUT OF THE URL IMMEDIATELY
+ * ===========================================================================
+ *
+ * A capture token in an address bar is a capture token in a screenshot, a
+ * `Referer` header, a pasted link and a server access log — and this one
+ * authorises filing issues as the reviewer it was minted for. `replaceState`
+ * rewrites the entry in place: no navigation and no new history entry.
+ *
+ * **MEASURED, not assumed** — chromium 151.0.7922.34 driven by playwright
+ * against a loopback server that logged every `Referer` it received. The page
+ * did the same `searchParams.delete` + `replaceState` this module does, with
+ * one stylesheet in the initial `<head>` and a second appended by script
+ * afterwards:
+ *
+ * ```
+ * /early.css   Referer: http://…/page?tab=menu&ai_annotate=…&ai_capture=…&ai_run=…
+ * /late.css    Referer: http://…/page?tab=menu
+ * ```
+ *
+ * Two things come out of that run, and both are the point:
+ *
+ * 1. **The residual window is real, and it is bounded.** Anything the page
+ *    requests before this function runs — the document's own scripts,
+ *    stylesheets, fonts, images — is a SAME-ORIGIN subresource, and under the
+ *    default `Referrer-Policy` (`strict-origin-when-cross-origin`) a
+ *    same-origin request carries the FULL URL, query string included. It
+ *    reaches only the product's own origin, which has already seen the tokens
+ *    on the request line of the navigation itself, and everything requested
+ *    after this call sees the stripped URL. That is the case a reviewer of
+ *    A-244 named and deferred to this slice, answered with a measurement.
+ * 2. **Back does not restore the tokens.** The same run then called
+ *    `goBack()` and landed on the URL from BEFORE the deep link rather than on
+ *    the token-bearing one — which is what `replaceState` rather than
+ *    `pushState` buys, and is why that choice is not stylistic.
+ *
+ * Closing the window entirely is a RESPONSE HEADER on the product
+ * (`Referrer-Policy: strict-origin`, which drops path and query for same-origin
+ * requests too), so it belongs to the mount in the product's own repository —
+ * N-905, not this package. **This module cannot close it**: by the time any
+ * bundled script runs, the head's subresources are already in flight. What is
+ * ours is being callable early, which is why nothing here awaits anything and
+ * the strip happens before the token is stored or the cookie is read.
+ *
+ * ===========================================================================
+ * SESSION STORAGE FOR THE CAPTURE TOKEN, AND NOT A COOKIE
+ * ===========================================================================
+ *
+ * The arming marker is a cookie because the product's MIDDLEWARE sets it, on
+ * the server, before any script runs. The capture token is deliberately not
+ * one: a cookie is attached to every request the browser makes to that origin,
+ * so it would put the credential into the product's own access logs on every
+ * page, image and API call for the rest of the session — the exact exposure
+ * step 2 exists to end. `sessionStorage` is per-tab, survives internal
+ * navigation (which is what arming has to survive), is never sent anywhere by
+ * the browser, and is gone when the tab closes.
+ *
+ * The cost, stated: a link opened in a NEW tab has no stored token, so a
+ * reviewer who middle-clicks their way around the app gets a toolbar that
+ * cannot send. That is the correct failure — `httpTransport` refuses to
+ * construct without a token — and it is recoverable by using the deep link
+ * again.
+ */
+/** Per-tab, never sent anywhere by the browser. Namespaced, not product-named. */
+export declare const CAPTURE_TOKEN_STORAGE_KEY = "ai.annotation.capture";
+export declare const REVIEW_RUN_STORAGE_KEY = "ai.annotation.run";
+/** The subset of `Storage` this needs. `null` disables persistence entirely. */
+export type StorageLike = Pick<Storage, "getItem" | "setItem" | "removeItem">;
+export interface ArmingOptions {
+    /** Defaults to the ambient `document`. Needs `cookie`, `URL` and `defaultView`. */
+    doc?: Document;
+    /** Defaults to `doc.defaultView.history`. Only `replaceState` is used. */
+    history?: Pick<History, "replaceState">;
+    /**
+     * Defaults to `sessionStorage`. Pass `null` for a tab that should keep
+     * nothing — arming then lasts exactly as long as the query string does.
+     */
+    storage?: StorageLike | null;
+    /** Overrides the URL read from the document. Tests and server renders only. */
+    url?: string;
+}
+export interface Arming {
+    /** May this page offer an annotation UI at all? */
+    armed: boolean;
+    /** The console's signed token, for `httpTransport`. Never validated here. */
+    captureToken: string | null;
+    /** The run under review, unsigned, couriered. */
+    runId: string | null;
+    /** *Done*, or an explicit stop. Clears the cookie and the stored token. */
+    disarm: () => void;
+}
+/**
+ * Read the deep link, strip it, and answer whether this page is armed.
+ *
+ * Safe to call more than once and safe to call on a page that was never
+ * linked to: with no parameters and no cookie it does nothing at all, touches
+ * no history entry, and returns `armed: false`.
+ */
+export declare function readArming(options?: ArmingOptions): Arming;
+export declare function isAnnotatableBuild(build: Pick<BuildInfo, "env">): boolean;

package/dist/arming.d.mts

@@ -0,0 +1,145 @@
+import { type BuildInfo } from "./protocol.mjs";
+/**
+ * Arming, and the production kill-switch (A-241).
+ *
+ * ===========================================================================
+ * THE SEQUENCE THIS FILE IS
+ * ===========================================================================
+ *
+ * The reviewer lands on `?ai_annotate=<arming>&ai_capture=<signed>&ai_run=<id>`
+ * from the console's *Request changes* button. This module is what happens in
+ * the first few milliseconds after that:
+ *
+ *   1. read the three parameters
+ *   2. **strip them from the URL** with `replaceState`, before anything else
+ *   3. answer *is this page armed* — from the COOKIE, never from the URL
+ *   4. only then, and only if armed, keep the capture token for the tab
+ *
+ * Step 3 is the runtime half of the kill-switch and step 2 is not decoration;
+ * both are argued at length below. Steps 3 and 4 were the other way round
+ * until A-254, which is how an unarmed page came to persist an
+ * attacker-supplied token — the argument, and the measurement that settled it,
+ * are at the gate itself in `readArming`.
+ *
+ * ===========================================================================
+ * TWO CREDENTIALS, AND THIS FILE TOUCHES THEM DIFFERENTLY ON PURPOSE
+ * ===========================================================================
+ *
+ * `docs/plans/first-party-annotation.md` § *Authentication* is the argument;
+ * what it means for this file is a table:
+ *
+ * | | who verifies it | what this module does with it |
+ * | --- | --- | --- |
+ * | arming token (`ai_annotate`) | the product's own middleware, against its `ANNOTATION_TOKEN_<PRODUCT>` | **nothing.** Reads the middleware's answer out of the cookie and drops the token |
+ * | capture token (`ai_capture`) | the console, on the way back in | couriers it: keeps it for the tab, hands it to `httpTransport` |
+ *
+ * **The URL parameter is not arming and this module never treats it as such.**
+ * That is the runtime gate, stated as a single sentence, and it is the reason
+ * `readArming` does not compare anything: page script holds no secret, so a
+ * page that armed itself because a token-shaped string was in its own query
+ * string would be armed by anyone who could type one. The middleware compares
+ * and sets a cookie; this reads the cookie. A wrong token therefore produces no
+ * cookie, and no cookie produces no toolbar — `arming.test.ts` asserts exactly
+ * that, and asserts it with a token-bearing URL present so it cannot pass by
+ * accident.
+ *
+ * ===========================================================================
+ * WHY THE TOKENS COME OUT OF THE URL IMMEDIATELY
+ * ===========================================================================
+ *
+ * A capture token in an address bar is a capture token in a screenshot, a
+ * `Referer` header, a pasted link and a server access log — and this one
+ * authorises filing issues as the reviewer it was minted for. `replaceState`
+ * rewrites the entry in place: no navigation and no new history entry.
+ *
+ * **MEASURED, not assumed** — chromium 151.0.7922.34 driven by playwright
+ * against a loopback server that logged every `Referer` it received. The page
+ * did the same `searchParams.delete` + `replaceState` this module does, with
+ * one stylesheet in the initial `<head>` and a second appended by script
+ * afterwards:
+ *
+ * ```
+ * /early.css   Referer: http://…/page?tab=menu&ai_annotate=…&ai_capture=…&ai_run=…
+ * /late.css    Referer: http://…/page?tab=menu
+ * ```
+ *
+ * Two things come out of that run, and both are the point:
+ *
+ * 1. **The residual window is real, and it is bounded.** Anything the page
+ *    requests before this function runs — the document's own scripts,
+ *    stylesheets, fonts, images — is a SAME-ORIGIN subresource, and under the
+ *    default `Referrer-Policy` (`strict-origin-when-cross-origin`) a
+ *    same-origin request carries the FULL URL, query string included. It
+ *    reaches only the product's own origin, which has already seen the tokens
+ *    on the request line of the navigation itself, and everything requested
+ *    after this call sees the stripped URL. That is the case a reviewer of
+ *    A-244 named and deferred to this slice, answered with a measurement.
+ * 2. **Back does not restore the tokens.** The same run then called
+ *    `goBack()` and landed on the URL from BEFORE the deep link rather than on
+ *    the token-bearing one — which is what `replaceState` rather than
+ *    `pushState` buys, and is why that choice is not stylistic.
+ *
+ * Closing the window entirely is a RESPONSE HEADER on the product
+ * (`Referrer-Policy: strict-origin`, which drops path and query for same-origin
+ * requests too), so it belongs to the mount in the product's own repository —
+ * N-905, not this package. **This module cannot close it**: by the time any
+ * bundled script runs, the head's subresources are already in flight. What is
+ * ours is being callable early, which is why nothing here awaits anything and
+ * the strip happens before the token is stored or the cookie is read.
+ *
+ * ===========================================================================
+ * SESSION STORAGE FOR THE CAPTURE TOKEN, AND NOT A COOKIE
+ * ===========================================================================
+ *
+ * The arming marker is a cookie because the product's MIDDLEWARE sets it, on
+ * the server, before any script runs. The capture token is deliberately not
+ * one: a cookie is attached to every request the browser makes to that origin,
+ * so it would put the credential into the product's own access logs on every
+ * page, image and API call for the rest of the session — the exact exposure
+ * step 2 exists to end. `sessionStorage` is per-tab, survives internal
+ * navigation (which is what arming has to survive), is never sent anywhere by
+ * the browser, and is gone when the tab closes.
+ *
+ * The cost, stated: a link opened in a NEW tab has no stored token, so a
+ * reviewer who middle-clicks their way around the app gets a toolbar that
+ * cannot send. That is the correct failure — `httpTransport` refuses to
+ * construct without a token — and it is recoverable by using the deep link
+ * again.
+ */
+/** Per-tab, never sent anywhere by the browser. Namespaced, not product-named. */
+export declare const CAPTURE_TOKEN_STORAGE_KEY = "ai.annotation.capture";
+export declare const REVIEW_RUN_STORAGE_KEY = "ai.annotation.run";
+/** The subset of `Storage` this needs. `null` disables persistence entirely. */
+export type StorageLike = Pick<Storage, "getItem" | "setItem" | "removeItem">;
+export interface ArmingOptions {
+    /** Defaults to the ambient `document`. Needs `cookie`, `URL` and `defaultView`. */
+    doc?: Document;
+    /** Defaults to `doc.defaultView.history`. Only `replaceState` is used. */
+    history?: Pick<History, "replaceState">;
+    /**
+     * Defaults to `sessionStorage`. Pass `null` for a tab that should keep
+     * nothing — arming then lasts exactly as long as the query string does.
+     */
+    storage?: StorageLike | null;
+    /** Overrides the URL read from the document. Tests and server renders only. */
+    url?: string;
+}
+export interface Arming {
+    /** May this page offer an annotation UI at all? */
+    armed: boolean;
+    /** The console's signed token, for `httpTransport`. Never validated here. */
+    captureToken: string | null;
+    /** The run under review, unsigned, couriered. */
+    runId: string | null;
+    /** *Done*, or an explicit stop. Clears the cookie and the stored token. */
+    disarm: () => void;
+}
+/**
+ * Read the deep link, strip it, and answer whether this page is armed.
+ *
+ * Safe to call more than once and safe to call on a page that was never
+ * linked to: with no parameters and no cookie it does nothing at all, touches
+ * no history entry, and returns `armed: false`.
+ */
+export declare function readArming(options?: ArmingOptions): Arming;
+export declare function isAnnotatableBuild(build: Pick<BuildInfo, "env">): boolean;

package/dist/arming.d.ts

@@ -0,0 +1,145 @@
+import { type BuildInfo } from "./protocol.js";
+/**
+ * Arming, and the production kill-switch (A-241).
+ *
+ * ===========================================================================
+ * THE SEQUENCE THIS FILE IS
+ * ===========================================================================
+ *
+ * The reviewer lands on `?ai_annotate=<arming>&ai_capture=<signed>&ai_run=<id>`
+ * from the console's *Request changes* button. This module is what happens in
+ * the first few milliseconds after that:
+ *
+ *   1. read the three parameters
+ *   2. **strip them from the URL** with `replaceState`, before anything else
+ *   3. answer *is this page armed* — from the COOKIE, never from the URL
+ *   4. only then, and only if armed, keep the capture token for the tab
+ *
+ * Step 3 is the runtime half of the kill-switch and step 2 is not decoration;
+ * both are argued at length below. Steps 3 and 4 were the other way round
+ * until A-254, which is how an unarmed page came to persist an
+ * attacker-supplied token — the argument, and the measurement that settled it,
+ * are at the gate itself in `readArming`.
+ *
+ * ===========================================================================
+ * TWO CREDENTIALS, AND THIS FILE TOUCHES THEM DIFFERENTLY ON PURPOSE
+ * ===========================================================================
+ *
+ * `docs/plans/first-party-annotation.md` § *Authentication* is the argument;
+ * what it means for this file is a table:
+ *
+ * | | who verifies it | what this module does with it |
+ * | --- | --- | --- |
+ * | arming token (`ai_annotate`) | the product's own middleware, against its `ANNOTATION_TOKEN_<PRODUCT>` | **nothing.** Reads the middleware's answer out of the cookie and drops the token |
+ * | capture token (`ai_capture`) | the console, on the way back in | couriers it: keeps it for the tab, hands it to `httpTransport` |
+ *
+ * **The URL parameter is not arming and this module never treats it as such.**
+ * That is the runtime gate, stated as a single sentence, and it is the reason
+ * `readArming` does not compare anything: page script holds no secret, so a
+ * page that armed itself because a token-shaped string was in its own query
+ * string would be armed by anyone who could type one. The middleware compares
+ * and sets a cookie; this reads the cookie. A wrong token therefore produces no
+ * cookie, and no cookie produces no toolbar — `arming.test.ts` asserts exactly
+ * that, and asserts it with a token-bearing URL present so it cannot pass by
+ * accident.
+ *
+ * ===========================================================================
+ * WHY THE TOKENS COME OUT OF THE URL IMMEDIATELY
+ * ===========================================================================
+ *
+ * A capture token in an address bar is a capture token in a screenshot, a
+ * `Referer` header, a pasted link and a server access log — and this one
+ * authorises filing issues as the reviewer it was minted for. `replaceState`
+ * rewrites the entry in place: no navigation and no new history entry.
+ *
+ * **MEASURED, not assumed** — chromium 151.0.7922.34 driven by playwright
+ * against a loopback server that logged every `Referer` it received. The page
+ * did the same `searchParams.delete` + `replaceState` this module does, with
+ * one stylesheet in the initial `<head>` and a second appended by script
+ * afterwards:
+ *
+ * ```
+ * /early.css   Referer: http://…/page?tab=menu&ai_annotate=…&ai_capture=…&ai_run=…
+ * /late.css    Referer: http://…/page?tab=menu
+ * ```
+ *
+ * Two things come out of that run, and both are the point:
+ *
+ * 1. **The residual window is real, and it is bounded.** Anything the page
+ *    requests before this function runs — the document's own scripts,
+ *    stylesheets, fonts, images — is a SAME-ORIGIN subresource, and under the
+ *    default `Referrer-Policy` (`strict-origin-when-cross-origin`) a
+ *    same-origin request carries the FULL URL, query string included. It
+ *    reaches only the product's own origin, which has already seen the tokens
+ *    on the request line of the navigation itself, and everything requested
+ *    after this call sees the stripped URL. That is the case a reviewer of
+ *    A-244 named and deferred to this slice, answered with a measurement.
+ * 2. **Back does not restore the tokens.** The same run then called
+ *    `goBack()` and landed on the URL from BEFORE the deep link rather than on
+ *    the token-bearing one — which is what `replaceState` rather than
+ *    `pushState` buys, and is why that choice is not stylistic.
+ *
+ * Closing the window entirely is a RESPONSE HEADER on the product
+ * (`Referrer-Policy: strict-origin`, which drops path and query for same-origin
+ * requests too), so it belongs to the mount in the product's own repository —
+ * N-905, not this package. **This module cannot close it**: by the time any
+ * bundled script runs, the head's subresources are already in flight. What is
+ * ours is being callable early, which is why nothing here awaits anything and
+ * the strip happens before the token is stored or the cookie is read.
+ *
+ * ===========================================================================
+ * SESSION STORAGE FOR THE CAPTURE TOKEN, AND NOT A COOKIE
+ * ===========================================================================
+ *
+ * The arming marker is a cookie because the product's MIDDLEWARE sets it, on
+ * the server, before any script runs. The capture token is deliberately not
+ * one: a cookie is attached to every request the browser makes to that origin,
+ * so it would put the credential into the product's own access logs on every
+ * page, image and API call for the rest of the session — the exact exposure
+ * step 2 exists to end. `sessionStorage` is per-tab, survives internal
+ * navigation (which is what arming has to survive), is never sent anywhere by
+ * the browser, and is gone when the tab closes.
+ *
+ * The cost, stated: a link opened in a NEW tab has no stored token, so a
+ * reviewer who middle-clicks their way around the app gets a toolbar that
+ * cannot send. That is the correct failure — `httpTransport` refuses to
+ * construct without a token — and it is recoverable by using the deep link
+ * again.
+ */
+/** Per-tab, never sent anywhere by the browser. Namespaced, not product-named. */
+export declare const CAPTURE_TOKEN_STORAGE_KEY = "ai.annotation.capture";
+export declare const REVIEW_RUN_STORAGE_KEY = "ai.annotation.run";
+/** The subset of `Storage` this needs. `null` disables persistence entirely. */
+export type StorageLike = Pick<Storage, "getItem" | "setItem" | "removeItem">;
+export interface ArmingOptions {
+    /** Defaults to the ambient `document`. Needs `cookie`, `URL` and `defaultView`. */
+    doc?: Document;
+    /** Defaults to `doc.defaultView.history`. Only `replaceState` is used. */
+    history?: Pick<History, "replaceState">;
+    /**
+     * Defaults to `sessionStorage`. Pass `null` for a tab that should keep
+     * nothing — arming then lasts exactly as long as the query string does.
+     */
+    storage?: StorageLike | null;
+    /** Overrides the URL read from the document. Tests and server renders only. */
+    url?: string;
+}
+export interface Arming {
+    /** May this page offer an annotation UI at all? */
+    armed: boolean;
+    /** The console's signed token, for `httpTransport`. Never validated here. */
+    captureToken: string | null;
+    /** The run under review, unsigned, couriered. */
+    runId: string | null;
+    /** *Done*, or an explicit stop. Clears the cookie and the stored token. */
+    disarm: () => void;
+}
+/**
+ * Read the deep link, strip it, and answer whether this page is armed.
+ *
+ * Safe to call more than once and safe to call on a page that was never
+ * linked to: with no parameters and no cookie it does nothing at all, touches
+ * no history entry, and returns `armed: false`.
+ */
+export declare function readArming(options?: ArmingOptions): Arming;
+export declare function isAnnotatableBuild(build: Pick<BuildInfo, "env">): boolean;

package/dist/host.cjs

@@ -1,2 +1,2 @@
-"use strict";var s=Object.defineProperty;var c=Object.getOwnPropertyDescriptor;var p=Object.getOwnPropertyNames;var l=Object.prototype.hasOwnProperty;var g=(e,t)=>{for(var a in t)s(e,a,{get:t[a],enumerable:!0})},f=(e,t,a,o)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of p(t))!l.call(e,r)&&r!==a&&s(e,r,{get:()=>t[r],enumerable:!(o=c(t,r))||o.enumerable});return e};var m=e=>f(s({},"__esModule",{value:!0}),e);var T={};g(T,{createAnnotationHost:()=>A,isFrameMessage:()=>d});module.exports=m(T);function u(e){if(!e||e==="*")throw new Error("[annotation] a concrete parent origin is required; '*' would broadcast annotation payloads to any embedder.");return e}var y=new Set(["annotate:ready","annotate:hover","annotate:capture","annotate:cancel"]);function d(e){if(typeof e!="object"||e===null)return!1;let t=e.type;return typeof t=="string"&&y.has(t)}function A(e){let t=u(e.frameOrigin),a=!1,o=!1,r=n=>{o||e.frame.postMessage(n,t)},i=n=>{if(n.origin===t&&n.source===e.frame&&d(n.data))switch(n.data.type){case"annotate:ready":a=!0,e.onReady({sdkVersion:n.data.sdkVersion,build:n.data.build});return;case"annotate:hover":e.onHover(n.data.target);return;case"annotate:capture":e.onCapture(n.data.payload);return;case"annotate:cancel":e.onCancel();return}};return e.hostWindow.addEventListener("message",i),{enable:()=>r({type:"annotate:enable"}),disable:()=>r({type:"annotate:disable"}),ping:()=>r({type:"annotate:ping"}),isReady:()=>a,destroy(){o=!0,a=!1,e.hostWindow.removeEventListener("message",i)}}}
+"use strict";var i=Object.defineProperty;var p=Object.getOwnPropertyDescriptor;var d=Object.getOwnPropertyNames;var l=Object.prototype.hasOwnProperty;var g=(e,t)=>{for(var o in t)i(e,o,{get:t[o],enumerable:!0})},f=(e,t,o,a)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of d(t))!l.call(e,r)&&r!==o&&i(e,r,{get:()=>t[r],enumerable:!(a=p(t,r))||a.enumerable});return e};var m=e=>f(i({},"__esModule",{value:!0}),e);var T={};g(T,{createAnnotationHost:()=>A,isFrameMessage:()=>u});module.exports=m(T);function c(e){if(!e||e==="*")throw new Error("[annotation] a concrete parent origin is required; '*' would broadcast annotation payloads to any embedder.");return e}var y=new Set(["annotate:ready","annotate:hover","annotate:capture","annotate:cancel"]);function u(e){if(typeof e!="object"||e===null)return!1;let t=e.type;return typeof t=="string"&&y.has(t)}function A(e){let t=c(e.frameOrigin),o=!1,a=!1,r=n=>{a||e.frame.postMessage(n,t)},s=n=>{if(n.origin===t&&n.source===e.frame&&u(n.data))switch(n.data.type){case"annotate:ready":o=!0,e.onReady({sdkVersion:n.data.sdkVersion,build:n.data.build});return;case"annotate:hover":e.onHover(n.data.target);return;case"annotate:capture":e.onCapture(n.data.payload);return;case"annotate:cancel":e.onCancel();return}};return e.hostWindow.addEventListener("message",s),{enable:()=>r({type:"annotate:enable"}),disable:()=>r({type:"annotate:disable"}),ping:()=>r({type:"annotate:ping"}),isReady:()=>o,destroy(){a=!0,o=!1,e.hostWindow.removeEventListener("message",s)}}}
 //# sourceMappingURL=host.cjs.map