@bitvea/feedback-cli 1.1.0 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @bitvea/feedback-cli
 
-The installer for [BitVea Feedback](https://github.com/bitvea/feedback-toolbar): it installs the toolbar into an app, and it registers a deployment as a project.
+The installer for [BitVea Feedback](https://github.com/bitvea/feedback-toolbar): it installs the toolbar into an app, it registers a deployment as a project, and it runs the local-mode receiver.
 
 You are not expected to type this package's name.
 The command everybody uses is the toolbar's:
@@ -20,6 +20,11 @@ Re-running it changes nothing, and a run that cannot find a root layout changes
 It is what the `prebuild` line runs, and it is a command of its own because a script-tag install has no build to hook.
 `--optional` reports a failure and exits 0, so a registration problem can never fail somebody's deploy.
 
+`dev` is the receiver for the toolbar's local mode.
+It listens on `127.0.0.1:4477` and nowhere wider, answers only pages on this machine and origins named with `--allow-origin`, and writes each annotation to `.bitvea/feedback/<id>.json` with its screenshot beside it as `<id>.png` and a regenerated `inbox.md` for a person or a coding agent to read.
+It needs no account and no key, and it sends nothing anywhere.
+`--port` and `--dir` move the port and the repository it writes into.
+
 `help` and `--version` print usage and the versions in play.
 
 ## Which toolbar version does `init` pin?

package/dist/commands/dev.d.ts

@@ -0,0 +1,9 @@
+export interface RunDevOptions {
+    /**
+     * Resolves when the receiver should stop. Defaults to the first SIGINT or
+     * SIGTERM, which is what a person pressing Ctrl-C sends.
+     */
+    until?: Promise<void>;
+}
+export declare function runDev(argv: string[], options?: RunDevOptions): Promise<number>;
+//# sourceMappingURL=dev.d.ts.map

package/dist/commands/dev.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/commands/dev.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAsBD,wBAAsB,MAAM,CAC1B,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,MAAM,CAAC,CAmEjB"}

package/dist/commands/dev.js

@@ -0,0 +1,97 @@
+// `npx @bitvea/feedback-toolbar dev`: the loopback receiver, in the foreground
+// until Ctrl-C.
+//
+// This is the terminal half: flags in, a banner out, one line per annotation,
+// and an exit code. Everything a test needs to drive is in ../dev/server.ts,
+// which this only starts and stops.
+//
+// `node:util`'s `parseArgs` rather than the hand-rolled reader `init` and
+// `register` share, because `--allow-origin` repeats and because a typo in a
+// flag here should be refused rather than ignored: a mistyped
+// `--allow-orgin https://preview.example.com` that silently allowed nothing
+// would read as the toolbar being broken.
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { parseAllowedOrigin } from "../dev/origins.js";
+import { DEV_DEFAULT_PORT, DEV_HOST, startDevReceiver, } from "../dev/server.js";
+function untilSignalled() {
+    return new Promise((done) => {
+        const stop = () => {
+            process.off("SIGINT", stop);
+            process.off("SIGTERM", stop);
+            done();
+        };
+        process.on("SIGINT", stop);
+        process.on("SIGTERM", stop);
+    });
+}
+function parsePort(raw) {
+    if (raw === undefined)
+        return DEV_DEFAULT_PORT;
+    if (!/^\d{1,5}$/.test(raw) || Number(raw) > 65535) {
+        throw new Error(`--port ${JSON.stringify(raw)} is not a port number.`);
+    }
+    return Number(raw);
+}
+export async function runDev(argv, options = {}) {
+    let port;
+    let root;
+    let allowOrigins;
+    try {
+        const { values } = parseArgs({
+            args: argv.slice(1),
+            options: {
+                port: { type: "string" },
+                dir: { type: "string" },
+                "allow-origin": { type: "string", multiple: true },
+            },
+            strict: true,
+            allowPositionals: false,
+        });
+        port = parsePort(values.port);
+        root = resolve(values.dir ?? process.cwd());
+        allowOrigins = (values["allow-origin"] ?? []).map(parseAllowedOrigin);
+    }
+    catch (err) {
+        console.error(`Could not start: ${err instanceof Error ? err.message : String(err)}\n` +
+            "Run `npx @bitvea/feedback-toolbar help` for the flags.");
+        return 1;
+    }
+    let receiver;
+    try {
+        receiver = await startDevReceiver({
+            root,
+            port,
+            allowOrigins,
+            log: (line) => console.log(line),
+            warn: (line) => console.warn(line),
+        });
+    }
+    catch (err) {
+        const code = err.code;
+        console.error(code === "EADDRINUSE"
+            ? `Could not start: ${DEV_HOST}:${port} is already in use. ` +
+                "Is another `dev` receiver running? Stop it, or pass --port and " +
+                "point the page's data-sink-url at the same port."
+            : `Could not start: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+    const lines = [
+        `BitVea Feedback local mode: listening on ${receiver.origin} (this machine only).`,
+        `Annotations are written to ${receiver.dir}`,
+        "Read inbox.md there, or point your coding agent at it.",
+    ];
+    if (receiver.port !== DEV_DEFAULT_PORT) {
+        lines.push(`The toolbar looks on port ${DEV_DEFAULT_PORT} by default; add ` +
+            `data-sink-url="${receiver.sinkUrl}" (or the sinkUrl prop) to the page.`);
+    }
+    if (allowOrigins.length > 0) {
+        lines.push(`Also accepting annotations from: ${allowOrigins.join(", ")}`);
+    }
+    lines.push("Nothing is sent anywhere else. Press Ctrl-C to stop.");
+    console.log(lines.join("\n"));
+    await (options.until ?? untilSignalled());
+    await receiver.close();
+    return 0;
+}
+//# sourceMappingURL=dev.js.map

package/dist/commands/dev.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.js","sourceRoot":"","sources":["../../src/commands/dev.ts"],"names":[],"mappings":"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"}

package/dist/dev/contract.d.ts

@@ -0,0 +1,94 @@
+/** The contract version. A version this receiver does not know is refused. */
+export declare const LOCAL_ANNOTATION_VERSION: 1;
+/** Copy of `FEEDBACK_BODY_MAX` in `packages/types/src/feedback.ts`. */
+export declare const ANNOTATION_TEXT_MAX = 5000;
+/** Copy of `SCREENSHOT_DATA_URL_MAX` in `packages/types/src/feedback.ts`. */
+export declare const SCREENSHOT_DATA_URL_MAX = 4000000;
+/**
+ * The largest request body the receiver reads, in bytes.
+ *
+ * Copy of `LOCAL_ANNOTATION_MAX_BYTES` in the toolbar's contract: the largest
+ * picture the toolbar will send plus headroom for the words. Refusing less
+ * than this would refuse screenshots the toolbar considers ordinary; the
+ * toolbar reads a 413 as "the picture was too big" and retries with the text.
+ */
+export declare const LOCAL_ANNOTATION_MAX_BYTES: number;
+/** How many owners the component chain may carry, nearest first. */
+export declare const COMPONENT_OWNERS_MAX = 10;
+/**
+ * An annotation id. It is also the file name on disk, so this pattern is the
+ * whole of the path-traversal defence: no dot, no slash, nothing else.
+ */
+export declare const ANNOTATION_ID_PATTERN: RegExp;
+/** The only picture a sink is sent: a PNG, inline. */
+export declare const PNG_DATA_URL_PREFIX = "data:image/png;base64,";
+export type LocalAnnotationKind = "pin" | "note";
+export interface LocalAnnotationBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface LocalAnnotationPin {
+    offsetX: number;
+    offsetY: number;
+    box: LocalAnnotationBox | null;
+}
+export interface LocalAnnotationComponent {
+    name: string;
+    owners: string[];
+}
+export interface LocalAnnotation {
+    v: typeof LOCAL_ANNOTATION_VERSION;
+    id: string;
+    kind: LocalAnnotationKind;
+    text: string;
+    url: string;
+    selector: string | null;
+    pin: LocalAnnotationPin | null;
+    viewport: {
+        width: number;
+        height: number;
+        devicePixelRatio: number;
+    };
+    timestamp: string;
+    userAgent: string;
+    /**
+     * A PNG data URL on the way in; on disk, the sibling file's name; in a list
+     * response, the root-relative path this receiver serves it from.
+     */
+    screenshot: string | null;
+    component?: LocalAnnotationComponent;
+}
+/**
+ * A C0 control character or DEL.
+ *
+ * Refused in every one-line field, because those fields end up on one line of
+ * `inbox.md` and of the receiver's terminal, and a newline or an ESC there is
+ * a way to write markup or escape sequences that read as the receiver's own.
+ * `new URL()` is no check on it: the WHATWG parser silently STRIPS tabs and
+ * newlines before parsing, so the raw string validates with them inside.
+ */
+export declare function isControlCharacter(code: number): boolean;
+/**
+ * `value` with every control character replaced, except the ones in `keep`.
+ * For the two places the receiver writes somebody else's prose: the terminal
+ * and `inbox.md`.
+ */
+export declare function replaceControlCharacters(value: string, replacement: string, keep?: string): string;
+/**
+ * Every problem with `value` as an incoming annotation, or an empty list when
+ * it is one. The same rules, in the same order, as the toolbar's
+ * `validateLocalAnnotation(value, "send")`.
+ */
+export declare function validateAnnotation(value: unknown): string[];
+/**
+ * The PNG a validated screenshot data URL carries, or null when the bytes are
+ * not a PNG.
+ *
+ * The prefix alone is a claim, not a fact: this is about to become a file in
+ * somebody's repository with a `.png` name, so the bytes are checked for the
+ * signature rather than trusted to match the label.
+ */
+export declare function decodePngDataUrl(dataUrl: string): Buffer | null;
+//# sourceMappingURL=contract.d.ts.map

package/dist/dev/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/dev/contract.ts"],"names":[],"mappings":"AAuBA,8EAA8E;AAC9E,eAAO,MAAM,wBAAwB,EAAG,CAAU,CAAC;AAEnD,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC,6EAA6E;AAC7E,eAAO,MAAM,uBAAuB,UAAY,CAAC;AAEjD;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,QAAoC,CAAC;AAE5E,oEAAoE;AACpE,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC;;;GAGG;AACH,eAAO,MAAM,qBAAqB,QAA0B,CAAC;AAE7D,sDAAsD;AACtD,eAAO,MAAM,mBAAmB,2BAA2B,CAAC;AAE5D,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG,MAAM,CAAC;AAEjD,MAAM,WAAW,kBAAkB;IACjC,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,kBAAkB,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,CAAC,EAAE,OAAO,wBAAwB,CAAC;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,mBAAmB,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,GAAG,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC/B,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,CAAC,EAAE,wBAAwB,CAAC;CACtC;AA6BD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AASD;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,IAAI,SAAK,GACR,MAAM,CASR;AAeD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAuI3D;AAOD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAW/D"}

package/dist/dev/contract.js

@@ -0,0 +1,260 @@
+// The local-mode annotation, as the `dev` receiver accepts it.
+//
+// This is the RECEIVING copy of a contract whose sending copy lives in
+// `packages/toolbar/src/local/contract.ts`. Two copies rather than one import,
+// and both halves of that are forced rather than chosen:
+//
+//   - this package may not import the toolbar, because the toolbar depends on
+//     this package and never the reverse (CLAUDE.md section 1); and
+//   - this package has ZERO runtime dependencies, which its publishable check
+//     enforces, so the Zod schema a receiver would normally reach for is not
+//     available either. The validator is written out by hand, exactly as the
+//     browser's is, for the opposite reason: the browser bundle refuses Zod.
+//
+// What holds the two together is the version field, which is what a receiver
+// branches on the day the shape changes, and `contract.test.ts` here, which
+// feeds this validator the same shapes the toolbar's own tests assert it
+// produces. The numbers below are copies too, and each names its original.
+//
+// STRICT ABOUT UNKNOWN FIELDS, on purpose and on both ends: the toolbar's
+// promise is that an annotation carries only what the page itself holds, and a
+// receiver that quietly accepted an extra field would be the half of the
+// contract that stopped noticing when that promise broke.
+/** The contract version. A version this receiver does not know is refused. */
+export const LOCAL_ANNOTATION_VERSION = 1;
+/** Copy of `FEEDBACK_BODY_MAX` in `packages/types/src/feedback.ts`. */
+export const ANNOTATION_TEXT_MAX = 5000;
+/** Copy of `SCREENSHOT_DATA_URL_MAX` in `packages/types/src/feedback.ts`. */
+export const SCREENSHOT_DATA_URL_MAX = 4_000_000;
+/**
+ * The largest request body the receiver reads, in bytes.
+ *
+ * Copy of `LOCAL_ANNOTATION_MAX_BYTES` in the toolbar's contract: the largest
+ * picture the toolbar will send plus headroom for the words. Refusing less
+ * than this would refuse screenshots the toolbar considers ordinary; the
+ * toolbar reads a 413 as "the picture was too big" and retries with the text.
+ */
+export const LOCAL_ANNOTATION_MAX_BYTES = SCREENSHOT_DATA_URL_MAX + 500_000;
+/** How many owners the component chain may carry, nearest first. */
+export const COMPONENT_OWNERS_MAX = 10;
+/**
+ * An annotation id. It is also the file name on disk, so this pattern is the
+ * whole of the path-traversal defence: no dot, no slash, nothing else.
+ */
+export const ANNOTATION_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+/** The only picture a sink is sent: a PNG, inline. */
+export const PNG_DATA_URL_PREFIX = "data:image/png;base64,";
+const KNOWN_KEYS = new Set([
+    "v",
+    "id",
+    "kind",
+    "text",
+    "url",
+    "selector",
+    "pin",
+    "viewport",
+    "timestamp",
+    "userAgent",
+    "screenshot",
+    "component",
+]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+function isFraction(value) {
+    return isFiniteNumber(value) && value >= 0 && value <= 1;
+}
+/**
+ * A C0 control character or DEL.
+ *
+ * Refused in every one-line field, because those fields end up on one line of
+ * `inbox.md` and of the receiver's terminal, and a newline or an ESC there is
+ * a way to write markup or escape sequences that read as the receiver's own.
+ * `new URL()` is no check on it: the WHATWG parser silently STRIPS tabs and
+ * newlines before parsing, so the raw string validates with them inside.
+ */
+export function isControlCharacter(code) {
+    return code <= 0x1f || code === 0x7f;
+}
+function isOneLine(value) {
+    for (let i = 0; i < value.length; i += 1) {
+        if (isControlCharacter(value.charCodeAt(i)))
+            return false;
+    }
+    return true;
+}
+/**
+ * `value` with every control character replaced, except the ones in `keep`.
+ * For the two places the receiver writes somebody else's prose: the terminal
+ * and `inbox.md`.
+ */
+export function replaceControlCharacters(value, replacement, keep = "") {
+    let out = "";
+    for (const char of value) {
+        out +=
+            isControlCharacter(char.charCodeAt(0)) && !keep.includes(char)
+                ? replacement
+                : char;
+    }
+    return out;
+}
+function isHttpUrl(value) {
+    if (typeof value !== "string" || value.length === 0 || value.length > 4096) {
+        return false;
+    }
+    if (!isOneLine(value))
+        return false;
+    try {
+        const url = new URL(value);
+        return url.protocol === "http:" || url.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Every problem with `value` as an incoming annotation, or an empty list when
+ * it is one. The same rules, in the same order, as the toolbar's
+ * `validateLocalAnnotation(value, "send")`.
+ */
+export function validateAnnotation(value) {
+    const errors = [];
+    if (!isRecord(value))
+        return ["annotation: must be an object"];
+    for (const key of Object.keys(value)) {
+        if (!KNOWN_KEYS.has(key))
+            errors.push(`${key}: unknown field`);
+    }
+    if (value["v"] !== LOCAL_ANNOTATION_VERSION) {
+        errors.push(`v: must be ${LOCAL_ANNOTATION_VERSION}`);
+    }
+    const id = value["id"];
+    if (typeof id !== "string" || !ANNOTATION_ID_PATTERN.test(id)) {
+        errors.push("id: must be 1-64 characters of A-Z, a-z, 0-9, _ or -");
+    }
+    const kind = value["kind"];
+    if (kind !== "pin" && kind !== "note") {
+        errors.push('kind: must be "pin" or "note"');
+    }
+    const text = value["text"];
+    if (typeof text !== "string" ||
+        text.trim().length === 0 ||
+        text.length > ANNOTATION_TEXT_MAX) {
+        errors.push(`text: must be 1-${ANNOTATION_TEXT_MAX} characters`);
+    }
+    if (!isHttpUrl(value["url"]))
+        errors.push("url: must be an http(s) URL");
+    const selector = value["selector"];
+    const pin = value["pin"];
+    if (selector === null) {
+        if (pin !== null)
+            errors.push("pin: must be null when selector is null");
+        if (kind === "pin")
+            errors.push("selector: a pin must carry a selector");
+    }
+    else if (typeof selector !== "string" ||
+        selector.length === 0 ||
+        selector.length > 2000 ||
+        !isOneLine(selector)) {
+        errors.push("selector: must be a 1-2000 character string or null");
+    }
+    else {
+        if (kind === "note")
+            errors.push("selector: a note must not carry one");
+        if (!isRecord(pin)) {
+            errors.push("pin: must be an object when selector is set");
+        }
+        else {
+            if (!isFraction(pin["offsetX"]) || !isFraction(pin["offsetY"])) {
+                errors.push("pin: offsetX and offsetY must be between 0 and 1");
+            }
+            const box = pin["box"];
+            if (box !== null &&
+                !(isRecord(box) &&
+                    isFiniteNumber(box["x"]) &&
+                    isFiniteNumber(box["y"]) &&
+                    isFiniteNumber(box["width"]) &&
+                    box["width"] >= 0 &&
+                    isFiniteNumber(box["height"]) &&
+                    box["height"] >= 0)) {
+                errors.push("pin.box: must be null or {x, y, width, height}");
+            }
+        }
+    }
+    const viewport = value["viewport"];
+    if (!(isRecord(viewport) &&
+        isFiniteNumber(viewport["width"]) &&
+        viewport["width"] > 0 &&
+        isFiniteNumber(viewport["height"]) &&
+        viewport["height"] > 0 &&
+        isFiniteNumber(viewport["devicePixelRatio"]) &&
+        viewport["devicePixelRatio"] > 0)) {
+        errors.push("viewport: must be {width, height, devicePixelRatio}");
+    }
+    const timestamp = value["timestamp"];
+    if (typeof timestamp !== "string" ||
+        !isOneLine(timestamp) ||
+        Number.isNaN(Date.parse(timestamp))) {
+        errors.push("timestamp: must be an ISO 8601 date");
+    }
+    const userAgent = value["userAgent"];
+    if (typeof userAgent !== "string" ||
+        userAgent.length > 1000 ||
+        !isOneLine(userAgent)) {
+        errors.push("userAgent: must be a string of at most 1000 characters");
+    }
+    const screenshot = value["screenshot"];
+    if (screenshot !== null &&
+        (typeof screenshot !== "string" ||
+            !screenshot.startsWith(PNG_DATA_URL_PREFIX) ||
+            screenshot.length > SCREENSHOT_DATA_URL_MAX)) {
+        errors.push("screenshot: must be null or a PNG data URL");
+    }
+    const component = value["component"];
+    if (component !== undefined) {
+        const owners = isRecord(component) ? component["owners"] : undefined;
+        if (!(isRecord(component) &&
+            typeof component["name"] === "string" &&
+            component["name"].length > 0 &&
+            component["name"].length <= 200 &&
+            isOneLine(component["name"]) &&
+            Array.isArray(owners) &&
+            owners.length <= COMPONENT_OWNERS_MAX &&
+            owners.every((owner) => typeof owner === "string" &&
+                owner.length > 0 &&
+                owner.length <= 200 &&
+                isOneLine(owner)))) {
+            errors.push("component: must be {name, owners[]}");
+        }
+    }
+    return errors;
+}
+/** The eight bytes every PNG starts with. */
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const BASE64 = /^[A-Za-z0-9+/]*={0,2}$/;
+/**
+ * The PNG a validated screenshot data URL carries, or null when the bytes are
+ * not a PNG.
+ *
+ * The prefix alone is a claim, not a fact: this is about to become a file in
+ * somebody's repository with a `.png` name, so the bytes are checked for the
+ * signature rather than trusted to match the label.
+ */
+export function decodePngDataUrl(dataUrl) {
+    if (!dataUrl.startsWith(PNG_DATA_URL_PREFIX))
+        return null;
+    const payload = dataUrl.slice(PNG_DATA_URL_PREFIX.length);
+    if (payload.length === 0 || payload.length % 4 !== 0 || !BASE64.test(payload)) {
+        return null;
+    }
+    const bytes = Buffer.from(payload, "base64");
+    if (bytes.length < PNG_SIGNATURE.length)
+        return null;
+    return bytes.subarray(0, PNG_SIGNATURE.length).equals(PNG_SIGNATURE)
+        ? bytes
+        : null;
+}
+//# sourceMappingURL=contract.js.map

package/dist/dev/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/dev/contract.ts"],"names":[],"mappings":"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"}

package/dist/dev/origins.d.ts

@@ -0,0 +1,17 @@
+/** Whether a URL hostname (as `new URL().hostname` spells it) is this machine. */
+export declare function isLoopbackHostname(hostname: string): boolean;
+/**
+ * Normalise an origin the developer typed for --allow-origin, or throw a
+ * message that says what was wrong with it.
+ *
+ * An origin is a scheme, a host and a port and nothing else: a path would be
+ * silently ignored by the comparison below, which is how somebody believes they
+ * allowed one page and in fact allowed a whole site. `*` is refused by name,
+ * because this receiver writes files into a repository.
+ */
+export declare function parseAllowedOrigin(raw: string): string;
+/** Whether a request's `Origin` header names a page allowed to send here. */
+export declare function isAllowedOrigin(origin: string, extra: ReadonlySet<string>): boolean;
+/** Whether a request's `Host` header addresses this machine. */
+export declare function isLoopbackHostHeader(host: string | undefined): boolean;
+//# sourceMappingURL=origins.d.ts.map

package/dist/dev/origins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"origins.d.ts","sourceRoot":"","sources":["../../src/dev/origins.ts"],"names":[],"mappings":"AAoBA,kFAAkF;AAClF,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA8BtD;AAED,6EAA6E;AAC7E,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,GACzB,OAAO,CAaT;AAED,gEAAgE;AAChE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAStE"}

package/dist/dev/origins.js

@@ -0,0 +1,90 @@
+// Who may talk to the `dev` receiver, asked two ways.
+//
+// A process listening on a loopback port is reachable from EVERY page open in
+// the developer's browser, not only from the app they are building: any site
+// can `fetch("http://127.0.0.1:4477/...")`. So binding to 127.0.0.1 keeps the
+// room out and does nothing about the tabs. These two checks are what does.
+//
+//   - ORIGIN is the page asking. It must be this machine (localhost,
+//     127.0.0.1 or [::1], any port and either scheme) or one the developer
+//     named with --allow-origin. Everything else is refused before a byte of
+//     the body is read, and gets no CORS headers, so a browser will not hand
+//     the page the answer either.
+//   - HOST is the name the request was addressed to. It must be a loopback
+//     name. That closes DNS rebinding: a hostile page that re-points its own
+//     domain at 127.0.0.1 becomes same-origin with this receiver and sends no
+//     Origin on a GET, but it still addresses the request to its own domain,
+//     and that is the name this check refuses.
+const LOOPBACK_HOSTNAMES = new Set(["localhost", "127.0.0.1", "[::1]"]);
+/** Whether a URL hostname (as `new URL().hostname` spells it) is this machine. */
+export function isLoopbackHostname(hostname) {
+    return LOOPBACK_HOSTNAMES.has(hostname.toLowerCase().replace(/\.$/, ""));
+}
+/**
+ * Normalise an origin the developer typed for --allow-origin, or throw a
+ * message that says what was wrong with it.
+ *
+ * An origin is a scheme, a host and a port and nothing else: a path would be
+ * silently ignored by the comparison below, which is how somebody believes they
+ * allowed one page and in fact allowed a whole site. `*` is refused by name,
+ * because this receiver writes files into a repository.
+ */
+export function parseAllowedOrigin(raw) {
+    const value = raw.trim();
+    if (value === "*" || value === "null") {
+        throw new Error(`--allow-origin ${value} is refused: name the one origin that may send ` +
+            "annotations, such as https://preview.example.com.");
+    }
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`--allow-origin ${JSON.stringify(raw)} is not a URL.`);
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new Error(`--allow-origin ${JSON.stringify(raw)} must be http(s).`);
+    }
+    if (url.username !== "" ||
+        url.password !== "" ||
+        (url.pathname !== "/" && url.pathname !== "") ||
+        url.search !== "" ||
+        url.hash !== "") {
+        throw new Error(`--allow-origin ${JSON.stringify(raw)} must be an origin only ` +
+            `(scheme, host and port), such as ${url.origin}.`);
+    }
+    return url.origin;
+}
+/** Whether a request's `Origin` header names a page allowed to send here. */
+export function isAllowedOrigin(origin, extra) {
+    if (extra.has(origin))
+        return true;
+    let url;
+    try {
+        url = new URL(origin);
+    }
+    catch {
+        return false;
+    }
+    // `new URL("http://x").origin` round-trips a real Origin header exactly; a
+    // header with a path or credentials in it is not one a browser sent.
+    if (url.origin !== origin)
+        return false;
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        return false;
+    return isLoopbackHostname(url.hostname);
+}
+/** Whether a request's `Host` header addresses this machine. */
+export function isLoopbackHostHeader(host) {
+    if (!host || /[@/\\?#\s]/.test(host))
+        return false;
+    let url;
+    try {
+        url = new URL(`http://${host}`);
+    }
+    catch {
+        return false;
+    }
+    return isLoopbackHostname(url.hostname);
+}
+//# sourceMappingURL=origins.js.map

package/dist/dev/origins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"origins.js","sourceRoot":"","sources":["../../src/dev/origins.ts"],"names":[],"mappings":"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"}