@osqd/bothandlerjs 0.3.0

package/dist/client/index.cjs

@@ -0,0 +1,139 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/client/index.ts
+var client_exports = {};
+__export(client_exports, {
+  clientScriptSource: () => clientScriptSource,
+  parseClientSignals: () => parseClientSignals,
+  renderClientScript: () => renderClientScript
+});
+module.exports = __toCommonJS(client_exports);
+function clientScriptSource(options) {
+  const endpoint = JSON.stringify(options.endpoint);
+  const windowMs = Math.max(0, options.interactionWindowMs ?? 8e3);
+  return `(function () {
+  "use strict";
+  function safe(fn) { try { return fn(); } catch (e) { return undefined; } }
+  var nav = window.navigator || {};
+  var started = Date.now();
+  var sent = false;
+
+  // Property *names* no ordinary browser defines. Membership is tested with \`in\`, so
+  // every entry has to be non-standard \u2014 \`webdriver\` was on this list and is not:
+  // \`navigator.webdriver\` is a standard property that exists, set to false, in every
+  // current browser. Testing for its presence therefore reported an automation global
+  // for every real visitor, which is the exact population this script exists to clear.
+  // Its value is what matters, and \`signals.webdriver\` below reads it properly.
+  var globals = [];
+  var suspects = ["__webdriver_script_fn", "__selenium_unwrapped", "__playwright", "__puppeteer_evaluation_script__", "_phantom", "callPhantom", "__nightmare", "cdc_adoQpoasnfa76pfcZLmcfl_Array"];
+  for (var i = 0; i < suspects.length; i++) {
+    if (safe(function () { return suspects[i] in window || suspects[i] in nav; })) globals.push(suspects[i]);
+  }
+
+  // "Absent" and "zero" have to stay distinguishable, and \`|| 1\` did not keep them
+  // apart: zero is falsy, so the sentinel meant to stand in for an unreadable value
+  // replaced the exact value being tested for. Both of these could therefore never be
+  // true \u2014 an empty language list and a zero-width screen, the two clearest marks of a
+  // headless environment, reported the same as a normal browser. Undefined means we
+  // could not look; a number means we did.
+  var languageCount = safe(function () { return nav.languages ? nav.languages.length : undefined; });
+  var screenWidth = safe(function () { return window.screen ? window.screen.width : undefined; });
+
+  var signals = {
+    webdriver: safe(function () { return nav.webdriver === true; }) === true,
+    noLanguages: languageCount === 0,
+    zeroDimensions: screenWidth === 0,
+    inconsistentPlatform: false,
+    interacted: false,
+    automationGlobals: globals
+  };
+
+  var hinted = safe(function () { return nav.userAgentData && nav.userAgentData.platform; });
+  var ua = safe(function () { return nav.userAgent; }) || "";
+  if (hinted) {
+    var lower = ua.toLowerCase();
+    var expected = hinted.toLowerCase().replace(/\\s+/g, "");
+    var agrees =
+      (expected.indexOf("win") === 0 && lower.indexOf("windows") >= 0) ||
+      (expected.indexOf("mac") === 0 && lower.indexOf("mac os") >= 0) ||
+      (expected === "linux" && lower.indexOf("linux") >= 0) ||
+      (expected === "android" && lower.indexOf("android") >= 0) ||
+      (expected === "ios" && (lower.indexOf("iphone") >= 0 || lower.indexOf("ipad") >= 0)) ||
+      (expected.indexOf("chrome") === 0 && lower.indexOf("cros") >= 0);
+    signals.inconsistentPlatform = !agrees;
+  }
+
+  function send() {
+    if (sent) return;
+    sent = true;
+    var body = JSON.stringify(signals);
+    // sendBeacon survives the page being navigated away from, which is exactly when
+    // a short visit reports. Falling back to fetch keepalive for older browsers.
+    if (navigator.sendBeacon) {
+      try { navigator.sendBeacon(${endpoint}, new Blob([body], { type: "application/json" })); return; } catch (e) { /* fall through */ }
+    }
+    try { fetch(${endpoint}, { method: "POST", headers: { "content-type": "application/json" }, body: body, keepalive: true, credentials: "same-origin" }); } catch (e) { /* best effort */ }
+  }
+
+  function onInteraction(event) {
+    // isTrusted distinguishes real input from an event a script dispatched. It is
+    // the single most informative bit on this page, and it is still forgeable by a
+    // framework driving a real browser.
+    if (!event || event.isTrusted !== true) return;
+    signals.interacted = true;
+    signals.msToInteraction = Date.now() - started;
+    send();
+  }
+
+  var types = ["pointerdown", "keydown", "touchstart", "wheel"];
+  for (var t = 0; t < types.length; t++) {
+    window.addEventListener(types[t], onInteraction, { once: true, capture: true, passive: true });
+  }
+
+  setTimeout(send, ${windowMs});
+  window.addEventListener("pagehide", send, { once: true });
+})();`;
+}
+function renderClientScript(options) {
+  const nonce = options.nonce !== void 0 ? ` nonce="${options.nonce.replace(/[^A-Za-z0-9+/=_-]/g, "")}"` : "";
+  return `<script${nonce}>${clientScriptSource(options)}</script>`;
+}
+function parseClientSignals(payload) {
+  if (typeof payload !== "object" || payload === null) return void 0;
+  const input = payload;
+  const signals = {};
+  for (const key of ["webdriver", "noLanguages", "zeroDimensions", "inconsistentPlatform", "interacted"]) {
+    if (typeof input[key] === "boolean") signals[key] = input[key];
+  }
+  if (typeof input["msToInteraction"] === "number" && Number.isFinite(input["msToInteraction"]) && input["msToInteraction"] >= 0) {
+    signals.msToInteraction = Math.min(input["msToInteraction"], 36e5);
+  }
+  if (Array.isArray(input["automationGlobals"])) {
+    signals.automationGlobals = input["automationGlobals"].filter((entry) => typeof entry === "string").slice(0, 16).map((entry) => entry.slice(0, 64));
+  }
+  return Object.keys(signals).length > 0 ? signals : void 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  clientScriptSource,
+  parseClientSignals,
+  renderClientScript
+});
+//# sourceMappingURL=index.cjs.map

package/dist/client/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/client/index.ts"],"sourcesContent":["/**\n * The browser half.\n *\n * Everything here runs on the page, and everything it produces is **client-asserted**\n * — which is the single most important thing to hold on to when reading it. A page\n * script can report that `navigator.webdriver` is false; it cannot prove it, because\n * the automation framework driving the page can rewrite the property before your\n * script ever runs, in one line.\n *\n * So these signals are not proof of anything, in either direction. What they are good\n * at is catching the enormous middle of the distribution: automation that is not\n * trying to hide, which is most of it. Treat what comes back as `moderate` evidence\n * at best — the {@link clientSignalsDetector} does exactly that, and deliberately\n * gives you no way to make it stronger.\n *\n * This module is published separately (`@osqd/bothandlerjs/client`) so that a page can\n * embed the script without pulling the server engine into a browser bundle.\n */\n\nexport interface ClientSignals {\n  /** `navigator.webdriver`. Standard, and removed by any framework that cares. */\n  webdriver?: boolean;\n  /** The browser reported an empty language list, which real browsers do not. */\n  noLanguages?: boolean;\n  /** Screen dimensions are zero or absent, typical of a headless environment. */\n  zeroDimensions?: boolean;\n  /** Client Hints platform disagrees with the User-Agent's platform. */\n  inconsistentPlatform?: boolean;\n  /** A trusted input event was observed. */\n  interacted?: boolean;\n  /** Milliseconds from load to the first trusted interaction. */\n  msToInteraction?: number;\n  /** Automation properties found on `window`, e.g. a CDP or driver hook. */\n  automationGlobals?: string[];\n}\n\nexport interface ClientScriptOptions {\n  /** Where signals are POSTed. Your route; it should be cheap and rate-limited. */\n  endpoint: string;\n  /** CSP nonce for the inline script. Supply one if your policy needs it. */\n  nonce?: string;\n  /**\n   * Wait for a trusted interaction before reporting, up to this many ms, so a single\n   * request carries both the passive signals and the interaction result. Default 8000.\n   */\n  interactionWindowMs?: number;\n}\n\n/**\n * The script source, as a string.\n *\n * Deliberately dependency-free, defensive about every property it touches (a hardened\n * browser throws on several), and fire-and-forget — it uses `sendBeacon` where\n * available so that reporting never delays a navigation.\n */\nexport function clientScriptSource(options: ClientScriptOptions): string {\n  const endpoint = JSON.stringify(options.endpoint);\n  const windowMs = Math.max(0, options.interactionWindowMs ?? 8000);\n\n  return `(function () {\n  \"use strict\";\n  function safe(fn) { try { return fn(); } catch (e) { return undefined; } }\n  var nav = window.navigator || {};\n  var started = Date.now();\n  var sent = false;\n\n  // Property *names* no ordinary browser defines. Membership is tested with \\`in\\`, so\n  // every entry has to be non-standard — \\`webdriver\\` was on this list and is not:\n  // \\`navigator.webdriver\\` is a standard property that exists, set to false, in every\n  // current browser. Testing for its presence therefore reported an automation global\n  // for every real visitor, which is the exact population this script exists to clear.\n  // Its value is what matters, and \\`signals.webdriver\\` below reads it properly.\n  var globals = [];\n  var suspects = [\"__webdriver_script_fn\", \"__selenium_unwrapped\", \"__playwright\", \"__puppeteer_evaluation_script__\", \"_phantom\", \"callPhantom\", \"__nightmare\", \"cdc_adoQpoasnfa76pfcZLmcfl_Array\"];\n  for (var i = 0; i < suspects.length; i++) {\n    if (safe(function () { return suspects[i] in window || suspects[i] in nav; })) globals.push(suspects[i]);\n  }\n\n  // \"Absent\" and \"zero\" have to stay distinguishable, and \\`|| 1\\` did not keep them\n  // apart: zero is falsy, so the sentinel meant to stand in for an unreadable value\n  // replaced the exact value being tested for. Both of these could therefore never be\n  // true — an empty language list and a zero-width screen, the two clearest marks of a\n  // headless environment, reported the same as a normal browser. Undefined means we\n  // could not look; a number means we did.\n  var languageCount = safe(function () { return nav.languages ? nav.languages.length : undefined; });\n  var screenWidth = safe(function () { return window.screen ? window.screen.width : undefined; });\n\n  var signals = {\n    webdriver: safe(function () { return nav.webdriver === true; }) === true,\n    noLanguages: languageCount === 0,\n    zeroDimensions: screenWidth === 0,\n    inconsistentPlatform: false,\n    interacted: false,\n    automationGlobals: globals\n  };\n\n  var hinted = safe(function () { return nav.userAgentData && nav.userAgentData.platform; });\n  var ua = safe(function () { return nav.userAgent; }) || \"\";\n  if (hinted) {\n    var lower = ua.toLowerCase();\n    var expected = hinted.toLowerCase().replace(/\\\\s+/g, \"\");\n    var agrees =\n      (expected.indexOf(\"win\") === 0 && lower.indexOf(\"windows\") >= 0) ||\n      (expected.indexOf(\"mac\") === 0 && lower.indexOf(\"mac os\") >= 0) ||\n      (expected === \"linux\" && lower.indexOf(\"linux\") >= 0) ||\n      (expected === \"android\" && lower.indexOf(\"android\") >= 0) ||\n      (expected === \"ios\" && (lower.indexOf(\"iphone\") >= 0 || lower.indexOf(\"ipad\") >= 0)) ||\n      (expected.indexOf(\"chrome\") === 0 && lower.indexOf(\"cros\") >= 0);\n    signals.inconsistentPlatform = !agrees;\n  }\n\n  function send() {\n    if (sent) return;\n    sent = true;\n    var body = JSON.stringify(signals);\n    // sendBeacon survives the page being navigated away from, which is exactly when\n    // a short visit reports. Falling back to fetch keepalive for older browsers.\n    if (navigator.sendBeacon) {\n      try { navigator.sendBeacon(${endpoint}, new Blob([body], { type: \"application/json\" })); return; } catch (e) { /* fall through */ }\n    }\n    try { fetch(${endpoint}, { method: \"POST\", headers: { \"content-type\": \"application/json\" }, body: body, keepalive: true, credentials: \"same-origin\" }); } catch (e) { /* best effort */ }\n  }\n\n  function onInteraction(event) {\n    // isTrusted distinguishes real input from an event a script dispatched. It is\n    // the single most informative bit on this page, and it is still forgeable by a\n    // framework driving a real browser.\n    if (!event || event.isTrusted !== true) return;\n    signals.interacted = true;\n    signals.msToInteraction = Date.now() - started;\n    send();\n  }\n\n  var types = [\"pointerdown\", \"keydown\", \"touchstart\", \"wheel\"];\n  for (var t = 0; t < types.length; t++) {\n    window.addEventListener(types[t], onInteraction, { once: true, capture: true, passive: true });\n  }\n\n  setTimeout(send, ${windowMs});\n  window.addEventListener(\"pagehide\", send, { once: true });\n})();`;\n}\n\n/** The script wrapped in a tag, ready to inline near the end of `<body>`. */\nexport function renderClientScript(options: ClientScriptOptions): string {\n  const nonce = options.nonce !== undefined ? ` nonce=\"${options.nonce.replace(/[^A-Za-z0-9+/=_-]/g, \"\")}\"` : \"\";\n  return `<script${nonce}>${clientScriptSource(options)}</script>`;\n}\n\n/**\n * Validates a posted signal payload.\n *\n * Every field is client-supplied, so nothing is trusted and nothing is coerced —\n * anything of the wrong type is dropped rather than interpreted. Returns `undefined`\n * for a payload that is not a plausible signal object at all.\n */\nexport function parseClientSignals(payload: unknown): ClientSignals | undefined {\n  if (typeof payload !== \"object\" || payload === null) return undefined;\n  const input = payload as Record<string, unknown>;\n  const signals: ClientSignals = {};\n\n  for (const key of [\"webdriver\", \"noLanguages\", \"zeroDimensions\", \"inconsistentPlatform\", \"interacted\"] as const) {\n    if (typeof input[key] === \"boolean\") signals[key] = input[key];\n  }\n  if (typeof input[\"msToInteraction\"] === \"number\" && Number.isFinite(input[\"msToInteraction\"]) && input[\"msToInteraction\"] >= 0) {\n    signals.msToInteraction = Math.min(input[\"msToInteraction\"], 3_600_000);\n  }\n  if (Array.isArray(input[\"automationGlobals\"])) {\n    signals.automationGlobals = input[\"automationGlobals\"].filter((entry): entry is string => typeof entry === \"string\").slice(0, 16).map((entry) => entry.slice(0, 64));\n  }\n  return Object.keys(signals).length > 0 ? signals : undefined;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAuDO,SAAS,mBAAmB,SAAsC;AACvE,QAAM,WAAW,KAAK,UAAU,QAAQ,QAAQ;AAChD,QAAM,WAAW,KAAK,IAAI,GAAG,QAAQ,uBAAuB,GAAI;AAEhE,SAAO;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mCA2D0B,QAAQ;AAAA;AAAA,kBAEzB,QAAQ;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,qBAkBL,QAAQ;AAAA;AAAA;AAG7B;AAGO,SAAS,mBAAmB,SAAsC;AACvE,QAAM,QAAQ,QAAQ,UAAU,SAAY,WAAW,QAAQ,MAAM,QAAQ,sBAAsB,EAAE,CAAC,MAAM;AAC5G,SAAO,UAAU,KAAK,IAAI,mBAAmB,OAAO,CAAC;AACvD;AASO,SAAS,mBAAmB,SAA6C;AAC9E,MAAI,OAAO,YAAY,YAAY,YAAY,KAAM,QAAO;AAC5D,QAAM,QAAQ;AACd,QAAM,UAAyB,CAAC;AAEhC,aAAW,OAAO,CAAC,aAAa,eAAe,kBAAkB,wBAAwB,YAAY,GAAY;AAC/G,QAAI,OAAO,MAAM,GAAG,MAAM,UAAW,SAAQ,GAAG,IAAI,MAAM,GAAG;AAAA,EAC/D;AACA,MAAI,OAAO,MAAM,iBAAiB,MAAM,YAAY,OAAO,SAAS,MAAM,iBAAiB,CAAC,KAAK,MAAM,iBAAiB,KAAK,GAAG;AAC9H,YAAQ,kBAAkB,KAAK,IAAI,MAAM,iBAAiB,GAAG,IAAS;AAAA,EACxE;AACA,MAAI,MAAM,QAAQ,MAAM,mBAAmB,CAAC,GAAG;AAC7C,YAAQ,oBAAoB,MAAM,mBAAmB,EAAE,OAAO,CAAC,UAA2B,OAAO,UAAU,QAAQ,EAAE,MAAM,GAAG,EAAE,EAAE,IAAI,CAAC,UAAU,MAAM,MAAM,GAAG,EAAE,CAAC;AAAA,EACrK;AACA,SAAO,OAAO,KAAK,OAAO,EAAE,SAAS,IAAI,UAAU;AACrD;","names":[]}

package/dist/client/index.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The browser half.
+ *
+ * Everything here runs on the page, and everything it produces is **client-asserted**
+ * — which is the single most important thing to hold on to when reading it. A page
+ * script can report that `navigator.webdriver` is false; it cannot prove it, because
+ * the automation framework driving the page can rewrite the property before your
+ * script ever runs, in one line.
+ *
+ * So these signals are not proof of anything, in either direction. What they are good
+ * at is catching the enormous middle of the distribution: automation that is not
+ * trying to hide, which is most of it. Treat what comes back as `moderate` evidence
+ * at best — the {@link clientSignalsDetector} does exactly that, and deliberately
+ * gives you no way to make it stronger.
+ *
+ * This module is published separately (`@osqd/bothandlerjs/client`) so that a page can
+ * embed the script without pulling the server engine into a browser bundle.
+ */
+export interface ClientSignals {
+    /** `navigator.webdriver`. Standard, and removed by any framework that cares. */
+    webdriver?: boolean;
+    /** The browser reported an empty language list, which real browsers do not. */
+    noLanguages?: boolean;
+    /** Screen dimensions are zero or absent, typical of a headless environment. */
+    zeroDimensions?: boolean;
+    /** Client Hints platform disagrees with the User-Agent's platform. */
+    inconsistentPlatform?: boolean;
+    /** A trusted input event was observed. */
+    interacted?: boolean;
+    /** Milliseconds from load to the first trusted interaction. */
+    msToInteraction?: number;
+    /** Automation properties found on `window`, e.g. a CDP or driver hook. */
+    automationGlobals?: string[];
+}
+export interface ClientScriptOptions {
+    /** Where signals are POSTed. Your route; it should be cheap and rate-limited. */
+    endpoint: string;
+    /** CSP nonce for the inline script. Supply one if your policy needs it. */
+    nonce?: string;
+    /**
+     * Wait for a trusted interaction before reporting, up to this many ms, so a single
+     * request carries both the passive signals and the interaction result. Default 8000.
+     */
+    interactionWindowMs?: number;
+}
+/**
+ * The script source, as a string.
+ *
+ * Deliberately dependency-free, defensive about every property it touches (a hardened
+ * browser throws on several), and fire-and-forget — it uses `sendBeacon` where
+ * available so that reporting never delays a navigation.
+ */
+export declare function clientScriptSource(options: ClientScriptOptions): string;
+/** The script wrapped in a tag, ready to inline near the end of `<body>`. */
+export declare function renderClientScript(options: ClientScriptOptions): string;
+/**
+ * Validates a posted signal payload.
+ *
+ * Every field is client-supplied, so nothing is trusted and nothing is coerced —
+ * anything of the wrong type is dropped rather than interpreted. Returns `undefined`
+ * for a payload that is not a plausible signal object at all.
+ */
+export declare function parseClientSignals(payload: unknown): ClientSignals | undefined;

package/dist/client/index.js

@@ -0,0 +1,112 @@
+// src/client/index.ts
+function clientScriptSource(options) {
+  const endpoint = JSON.stringify(options.endpoint);
+  const windowMs = Math.max(0, options.interactionWindowMs ?? 8e3);
+  return `(function () {
+  "use strict";
+  function safe(fn) { try { return fn(); } catch (e) { return undefined; } }
+  var nav = window.navigator || {};
+  var started = Date.now();
+  var sent = false;
+
+  // Property *names* no ordinary browser defines. Membership is tested with \`in\`, so
+  // every entry has to be non-standard \u2014 \`webdriver\` was on this list and is not:
+  // \`navigator.webdriver\` is a standard property that exists, set to false, in every
+  // current browser. Testing for its presence therefore reported an automation global
+  // for every real visitor, which is the exact population this script exists to clear.
+  // Its value is what matters, and \`signals.webdriver\` below reads it properly.
+  var globals = [];
+  var suspects = ["__webdriver_script_fn", "__selenium_unwrapped", "__playwright", "__puppeteer_evaluation_script__", "_phantom", "callPhantom", "__nightmare", "cdc_adoQpoasnfa76pfcZLmcfl_Array"];
+  for (var i = 0; i < suspects.length; i++) {
+    if (safe(function () { return suspects[i] in window || suspects[i] in nav; })) globals.push(suspects[i]);
+  }
+
+  // "Absent" and "zero" have to stay distinguishable, and \`|| 1\` did not keep them
+  // apart: zero is falsy, so the sentinel meant to stand in for an unreadable value
+  // replaced the exact value being tested for. Both of these could therefore never be
+  // true \u2014 an empty language list and a zero-width screen, the two clearest marks of a
+  // headless environment, reported the same as a normal browser. Undefined means we
+  // could not look; a number means we did.
+  var languageCount = safe(function () { return nav.languages ? nav.languages.length : undefined; });
+  var screenWidth = safe(function () { return window.screen ? window.screen.width : undefined; });
+
+  var signals = {
+    webdriver: safe(function () { return nav.webdriver === true; }) === true,
+    noLanguages: languageCount === 0,
+    zeroDimensions: screenWidth === 0,
+    inconsistentPlatform: false,
+    interacted: false,
+    automationGlobals: globals
+  };
+
+  var hinted = safe(function () { return nav.userAgentData && nav.userAgentData.platform; });
+  var ua = safe(function () { return nav.userAgent; }) || "";
+  if (hinted) {
+    var lower = ua.toLowerCase();
+    var expected = hinted.toLowerCase().replace(/\\s+/g, "");
+    var agrees =
+      (expected.indexOf("win") === 0 && lower.indexOf("windows") >= 0) ||
+      (expected.indexOf("mac") === 0 && lower.indexOf("mac os") >= 0) ||
+      (expected === "linux" && lower.indexOf("linux") >= 0) ||
+      (expected === "android" && lower.indexOf("android") >= 0) ||
+      (expected === "ios" && (lower.indexOf("iphone") >= 0 || lower.indexOf("ipad") >= 0)) ||
+      (expected.indexOf("chrome") === 0 && lower.indexOf("cros") >= 0);
+    signals.inconsistentPlatform = !agrees;
+  }
+
+  function send() {
+    if (sent) return;
+    sent = true;
+    var body = JSON.stringify(signals);
+    // sendBeacon survives the page being navigated away from, which is exactly when
+    // a short visit reports. Falling back to fetch keepalive for older browsers.
+    if (navigator.sendBeacon) {
+      try { navigator.sendBeacon(${endpoint}, new Blob([body], { type: "application/json" })); return; } catch (e) { /* fall through */ }
+    }
+    try { fetch(${endpoint}, { method: "POST", headers: { "content-type": "application/json" }, body: body, keepalive: true, credentials: "same-origin" }); } catch (e) { /* best effort */ }
+  }
+
+  function onInteraction(event) {
+    // isTrusted distinguishes real input from an event a script dispatched. It is
+    // the single most informative bit on this page, and it is still forgeable by a
+    // framework driving a real browser.
+    if (!event || event.isTrusted !== true) return;
+    signals.interacted = true;
+    signals.msToInteraction = Date.now() - started;
+    send();
+  }
+
+  var types = ["pointerdown", "keydown", "touchstart", "wheel"];
+  for (var t = 0; t < types.length; t++) {
+    window.addEventListener(types[t], onInteraction, { once: true, capture: true, passive: true });
+  }
+
+  setTimeout(send, ${windowMs});
+  window.addEventListener("pagehide", send, { once: true });
+})();`;
+}
+function renderClientScript(options) {
+  const nonce = options.nonce !== void 0 ? ` nonce="${options.nonce.replace(/[^A-Za-z0-9+/=_-]/g, "")}"` : "";
+  return `<script${nonce}>${clientScriptSource(options)}</script>`;
+}
+function parseClientSignals(payload) {
+  if (typeof payload !== "object" || payload === null) return void 0;
+  const input = payload;
+  const signals = {};
+  for (const key of ["webdriver", "noLanguages", "zeroDimensions", "inconsistentPlatform", "interacted"]) {
+    if (typeof input[key] === "boolean") signals[key] = input[key];
+  }
+  if (typeof input["msToInteraction"] === "number" && Number.isFinite(input["msToInteraction"]) && input["msToInteraction"] >= 0) {
+    signals.msToInteraction = Math.min(input["msToInteraction"], 36e5);
+  }
+  if (Array.isArray(input["automationGlobals"])) {
+    signals.automationGlobals = input["automationGlobals"].filter((entry) => typeof entry === "string").slice(0, 16).map((entry) => entry.slice(0, 64));
+  }
+  return Object.keys(signals).length > 0 ? signals : void 0;
+}
+export {
+  clientScriptSource,
+  parseClientSignals,
+  renderClientScript
+};
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/client/index.ts"],"sourcesContent":["/**\n * The browser half.\n *\n * Everything here runs on the page, and everything it produces is **client-asserted**\n * — which is the single most important thing to hold on to when reading it. A page\n * script can report that `navigator.webdriver` is false; it cannot prove it, because\n * the automation framework driving the page can rewrite the property before your\n * script ever runs, in one line.\n *\n * So these signals are not proof of anything, in either direction. What they are good\n * at is catching the enormous middle of the distribution: automation that is not\n * trying to hide, which is most of it. Treat what comes back as `moderate` evidence\n * at best — the {@link clientSignalsDetector} does exactly that, and deliberately\n * gives you no way to make it stronger.\n *\n * This module is published separately (`@osqd/bothandlerjs/client`) so that a page can\n * embed the script without pulling the server engine into a browser bundle.\n */\n\nexport interface ClientSignals {\n  /** `navigator.webdriver`. Standard, and removed by any framework that cares. */\n  webdriver?: boolean;\n  /** The browser reported an empty language list, which real browsers do not. */\n  noLanguages?: boolean;\n  /** Screen dimensions are zero or absent, typical of a headless environment. */\n  zeroDimensions?: boolean;\n  /** Client Hints platform disagrees with the User-Agent's platform. */\n  inconsistentPlatform?: boolean;\n  /** A trusted input event was observed. */\n  interacted?: boolean;\n  /** Milliseconds from load to the first trusted interaction. */\n  msToInteraction?: number;\n  /** Automation properties found on `window`, e.g. a CDP or driver hook. */\n  automationGlobals?: string[];\n}\n\nexport interface ClientScriptOptions {\n  /** Where signals are POSTed. Your route; it should be cheap and rate-limited. */\n  endpoint: string;\n  /** CSP nonce for the inline script. Supply one if your policy needs it. */\n  nonce?: string;\n  /**\n   * Wait for a trusted interaction before reporting, up to this many ms, so a single\n   * request carries both the passive signals and the interaction result. Default 8000.\n   */\n  interactionWindowMs?: number;\n}\n\n/**\n * The script source, as a string.\n *\n * Deliberately dependency-free, defensive about every property it touches (a hardened\n * browser throws on several), and fire-and-forget — it uses `sendBeacon` where\n * available so that reporting never delays a navigation.\n */\nexport function clientScriptSource(options: ClientScriptOptions): string {\n  const endpoint = JSON.stringify(options.endpoint);\n  const windowMs = Math.max(0, options.interactionWindowMs ?? 8000);\n\n  return `(function () {\n  \"use strict\";\n  function safe(fn) { try { return fn(); } catch (e) { return undefined; } }\n  var nav = window.navigator || {};\n  var started = Date.now();\n  var sent = false;\n\n  // Property *names* no ordinary browser defines. Membership is tested with \\`in\\`, so\n  // every entry has to be non-standard — \\`webdriver\\` was on this list and is not:\n  // \\`navigator.webdriver\\` is a standard property that exists, set to false, in every\n  // current browser. Testing for its presence therefore reported an automation global\n  // for every real visitor, which is the exact population this script exists to clear.\n  // Its value is what matters, and \\`signals.webdriver\\` below reads it properly.\n  var globals = [];\n  var suspects = [\"__webdriver_script_fn\", \"__selenium_unwrapped\", \"__playwright\", \"__puppeteer_evaluation_script__\", \"_phantom\", \"callPhantom\", \"__nightmare\", \"cdc_adoQpoasnfa76pfcZLmcfl_Array\"];\n  for (var i = 0; i < suspects.length; i++) {\n    if (safe(function () { return suspects[i] in window || suspects[i] in nav; })) globals.push(suspects[i]);\n  }\n\n  // \"Absent\" and \"zero\" have to stay distinguishable, and \\`|| 1\\` did not keep them\n  // apart: zero is falsy, so the sentinel meant to stand in for an unreadable value\n  // replaced the exact value being tested for. Both of these could therefore never be\n  // true — an empty language list and a zero-width screen, the two clearest marks of a\n  // headless environment, reported the same as a normal browser. Undefined means we\n  // could not look; a number means we did.\n  var languageCount = safe(function () { return nav.languages ? nav.languages.length : undefined; });\n  var screenWidth = safe(function () { return window.screen ? window.screen.width : undefined; });\n\n  var signals = {\n    webdriver: safe(function () { return nav.webdriver === true; }) === true,\n    noLanguages: languageCount === 0,\n    zeroDimensions: screenWidth === 0,\n    inconsistentPlatform: false,\n    interacted: false,\n    automationGlobals: globals\n  };\n\n  var hinted = safe(function () { return nav.userAgentData && nav.userAgentData.platform; });\n  var ua = safe(function () { return nav.userAgent; }) || \"\";\n  if (hinted) {\n    var lower = ua.toLowerCase();\n    var expected = hinted.toLowerCase().replace(/\\\\s+/g, \"\");\n    var agrees =\n      (expected.indexOf(\"win\") === 0 && lower.indexOf(\"windows\") >= 0) ||\n      (expected.indexOf(\"mac\") === 0 && lower.indexOf(\"mac os\") >= 0) ||\n      (expected === \"linux\" && lower.indexOf(\"linux\") >= 0) ||\n      (expected === \"android\" && lower.indexOf(\"android\") >= 0) ||\n      (expected === \"ios\" && (lower.indexOf(\"iphone\") >= 0 || lower.indexOf(\"ipad\") >= 0)) ||\n      (expected.indexOf(\"chrome\") === 0 && lower.indexOf(\"cros\") >= 0);\n    signals.inconsistentPlatform = !agrees;\n  }\n\n  function send() {\n    if (sent) return;\n    sent = true;\n    var body = JSON.stringify(signals);\n    // sendBeacon survives the page being navigated away from, which is exactly when\n    // a short visit reports. Falling back to fetch keepalive for older browsers.\n    if (navigator.sendBeacon) {\n      try { navigator.sendBeacon(${endpoint}, new Blob([body], { type: \"application/json\" })); return; } catch (e) { /* fall through */ }\n    }\n    try { fetch(${endpoint}, { method: \"POST\", headers: { \"content-type\": \"application/json\" }, body: body, keepalive: true, credentials: \"same-origin\" }); } catch (e) { /* best effort */ }\n  }\n\n  function onInteraction(event) {\n    // isTrusted distinguishes real input from an event a script dispatched. It is\n    // the single most informative bit on this page, and it is still forgeable by a\n    // framework driving a real browser.\n    if (!event || event.isTrusted !== true) return;\n    signals.interacted = true;\n    signals.msToInteraction = Date.now() - started;\n    send();\n  }\n\n  var types = [\"pointerdown\", \"keydown\", \"touchstart\", \"wheel\"];\n  for (var t = 0; t < types.length; t++) {\n    window.addEventListener(types[t], onInteraction, { once: true, capture: true, passive: true });\n  }\n\n  setTimeout(send, ${windowMs});\n  window.addEventListener(\"pagehide\", send, { once: true });\n})();`;\n}\n\n/** The script wrapped in a tag, ready to inline near the end of `<body>`. */\nexport function renderClientScript(options: ClientScriptOptions): string {\n  const nonce = options.nonce !== undefined ? ` nonce=\"${options.nonce.replace(/[^A-Za-z0-9+/=_-]/g, \"\")}\"` : \"\";\n  return `<script${nonce}>${clientScriptSource(options)}</script>`;\n}\n\n/**\n * Validates a posted signal payload.\n *\n * Every field is client-supplied, so nothing is trusted and nothing is coerced —\n * anything of the wrong type is dropped rather than interpreted. Returns `undefined`\n * for a payload that is not a plausible signal object at all.\n */\nexport function parseClientSignals(payload: unknown): ClientSignals | undefined {\n  if (typeof payload !== \"object\" || payload === null) return undefined;\n  const input = payload as Record<string, unknown>;\n  const signals: ClientSignals = {};\n\n  for (const key of [\"webdriver\", \"noLanguages\", \"zeroDimensions\", \"inconsistentPlatform\", \"interacted\"] as const) {\n    if (typeof input[key] === \"boolean\") signals[key] = input[key];\n  }\n  if (typeof input[\"msToInteraction\"] === \"number\" && Number.isFinite(input[\"msToInteraction\"]) && input[\"msToInteraction\"] >= 0) {\n    signals.msToInteraction = Math.min(input[\"msToInteraction\"], 3_600_000);\n  }\n  if (Array.isArray(input[\"automationGlobals\"])) {\n    signals.automationGlobals = input[\"automationGlobals\"].filter((entry): entry is string => typeof entry === \"string\").slice(0, 16).map((entry) => entry.slice(0, 64));\n  }\n  return Object.keys(signals).length > 0 ? signals : undefined;\n}\n"],"mappings":";AAuDO,SAAS,mBAAmB,SAAsC;AACvE,QAAM,WAAW,KAAK,UAAU,QAAQ,QAAQ;AAChD,QAAM,WAAW,KAAK,IAAI,GAAG,QAAQ,uBAAuB,GAAI;AAEhE,SAAO;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mCA2D0B,QAAQ;AAAA;AAAA,kBAEzB,QAAQ;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,qBAkBL,QAAQ;AAAA;AAAA;AAG7B;AAGO,SAAS,mBAAmB,SAAsC;AACvE,QAAM,QAAQ,QAAQ,UAAU,SAAY,WAAW,QAAQ,MAAM,QAAQ,sBAAsB,EAAE,CAAC,MAAM;AAC5G,SAAO,UAAU,KAAK,IAAI,mBAAmB,OAAO,CAAC;AACvD;AASO,SAAS,mBAAmB,SAA6C;AAC9E,MAAI,OAAO,YAAY,YAAY,YAAY,KAAM,QAAO;AAC5D,QAAM,QAAQ;AACd,QAAM,UAAyB,CAAC;AAEhC,aAAW,OAAO,CAAC,aAAa,eAAe,kBAAkB,wBAAwB,YAAY,GAAY;AAC/G,QAAI,OAAO,MAAM,GAAG,MAAM,UAAW,SAAQ,GAAG,IAAI,MAAM,GAAG;AAAA,EAC/D;AACA,MAAI,OAAO,MAAM,iBAAiB,MAAM,YAAY,OAAO,SAAS,MAAM,iBAAiB,CAAC,KAAK,MAAM,iBAAiB,KAAK,GAAG;AAC9H,YAAQ,kBAAkB,KAAK,IAAI,MAAM,iBAAiB,GAAG,IAAS;AAAA,EACxE;AACA,MAAI,MAAM,QAAQ,MAAM,mBAAmB,CAAC,GAAG;AAC7C,YAAQ,oBAAoB,MAAM,mBAAmB,EAAE,OAAO,CAAC,UAA2B,OAAO,UAAU,QAAQ,EAAE,MAAM,GAAG,EAAE,EAAE,IAAI,CAAC,UAAU,MAAM,MAAM,GAAG,EAAE,CAAC;AAAA,EACrK;AACA,SAAO,OAAO,KAAK,OAAO,EAAE,SAAS,IAAI,UAAU;AACrD;","names":[]}