@bitvea/feedback-cli 1.0.1 → 1.2.0

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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"}

package/dist/dev/server.d.ts

@@ -0,0 +1,35 @@
+/** The only address this receiver ever binds. */
+export declare const DEV_HOST = "127.0.0.1";
+/**
+ * The port the toolbar posts to when nothing says otherwise. Copy of
+ * `DEFAULT_LOOPBACK_PORT` in `packages/toolbar/src/gating.ts`.
+ */
+export declare const DEV_DEFAULT_PORT = 4477;
+export declare const ANNOTATIONS_PATH = "/v1/annotations";
+export interface DevReceiverOptions {
+    /** The repository root; files go under `<root>/.bitvea/feedback`. */
+    root: string;
+    /** The port to listen on. 0 picks a free one, which is what tests use. */
+    port?: number;
+    /** Origins beyond this machine's that may send, already normalised. */
+    allowOrigins?: Iterable<string>;
+    /** The body limit in bytes. Defaults to the contract's. */
+    maxBytes?: number;
+    /** Where one line per event goes. Defaults to silence. */
+    log?: (line: string) => void;
+    /** Where refusals go. Defaults to silence. */
+    warn?: (line: string) => void;
+}
+export interface DevReceiver {
+    /** `http://127.0.0.1:<port>`. */
+    origin: string;
+    /** The collection URL, which is the toolbar's sink URL. */
+    sinkUrl: string;
+    port: number;
+    /** The absolute directory annotations are written to. */
+    dir: string;
+    close(): Promise<void>;
+}
+/** Start the receiver. Resolves once it is listening. */
+export declare function startDevReceiver(options: DevReceiverOptions): Promise<DevReceiver>;
+//# sourceMappingURL=server.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/dev/server.ts"],"names":[],"mappings":"AAgDA,iDAAiD;AACjD,eAAO,MAAM,QAAQ,cAAc,CAAC;AAEpC;;;GAGG;AACH,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC,eAAO,MAAM,gBAAgB,oBAAoB,CAAC;AAIlD,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAChC,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,8CAA8C;IAC9C,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,WAAW;IAC1B,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAsED,yDAAyD;AACzD,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,WAAW,CAAC,CA8KtB"}