guardian-risk-browser 0.1.1 → 0.2.1

package/README.md

@@ -6,31 +6,44 @@
 npm install guardian-risk guardian-risk-browser
 ```
 
-> **Stub package** — API may change before `1.0.0`.
+Browser-side behavioral signal collection for [guardian-risk](https://www.npmjs.com/package/guardian-risk).
 
-Browser integration for [guardian-risk](https://www.npmjs.com/package/guardian-risk). Collects client-side behavioral and fingerprint signals.
-
-## Planned signals
+## Signals
 
 | Signal | Source |
 |--------|--------|
-| `mouseLinearity` | Mouse movement patterns |
-| `keystrokeInterval` | Typing rhythm |
-| `headlessUA` | User agent heuristics |
-| `canvasFingerprint` | Canvas hash |
+| `mouseLinearity` | Pointer movement linearity (0–1) |
+| `hasPointerActivity` | Mouse or touch activity detected |
+| `keystrokeCount` | Key events in sample window |
+| `headlessUA` | User-agent heuristics |
 
-## Usage (stub)
+## Usage
 
 ```typescript
 import { Guardian } from 'guardian-risk';
-import { browserPlugin, collectSignals } from 'guardian-risk-browser';
+import { browserPlugin, BrowserCollector } from 'guardian-risk-browser';
 
 const guardian = new Guardian().use(browserPlugin());
 
-collectSignals(guardian);
-const report = guardian.analyze();
+const collector = new BrowserCollector();
+const stop = collector.start();
+// ... user interacts ...
+collector.applyTo(guardian);
+stop();
 ```
 
-## Status
+## Security notes
+
+- **All browser signals are client-controlled** — attackers can spoof or omit them.
+- Use for **defense in depth** only; never as sole auth or blocking factor.
+- Pair with server-side signals (IP rate limits, session age, VPN checks).
+- Mobile users: `hasPointerActivity` includes touch events.
+
+## API
+
+- `browserPlugin()` — registers default behavioral rules
+- `BrowserCollector` — tracks pointer/keyboard activity
+- `collectSignals(guardian, options?)` — timed sampling helper
+- `computeMouseLinearity(points)` — standalone metric
 
-Not yet published. Implementation in progress.
+See [SECURITY.md](../../SECURITY.md).

package/dist/index.cjs

@@ -1,17 +1,190 @@
 'use strict';
 
+// src/collector.ts
+function computeMouseLinearity(points) {
+  if (points.length < 3) {
+    return 0;
+  }
+  const first = points[0];
+  const last = points[points.length - 1];
+  const straightDistance = distance(first, last);
+  if (straightDistance === 0) {
+    return 1;
+  }
+  let pathDistance = 0;
+  for (let i = 1; i < points.length; i++) {
+    pathDistance += distance(points[i - 1], points[i]);
+  }
+  if (pathDistance === 0) {
+    return 0;
+  }
+  const linearity = straightDistance / pathDistance;
+  return Math.min(1, Math.max(0, linearity));
+}
+function distance(a, b) {
+  const dx = b.x - a.x;
+  const dy = b.y - a.y;
+  return Math.sqrt(dx * dx + dy * dy);
+}
+var BrowserCollector = class {
+  maxMouseSamples;
+  target;
+  mousePoints = [];
+  clickTimes = [];
+  keyStrokeCount = 0;
+  pointerActivity = false;
+  startedAt = 0;
+  listeners = [];
+  constructor(options = {}) {
+    this.maxMouseSamples = options.maxMouseSamples ?? 100;
+    this.target = options.target ?? getDefaultTarget();
+  }
+  /** Start listening for user events. Returns a stop function. */
+  start() {
+    if (!this.target) {
+      return () => {
+      };
+    }
+    this.startedAt = Date.now();
+    const onMouseMove = (event) => {
+      const e = event;
+      this.mousePoints.push({ x: e.clientX, y: e.clientY, t: Date.now() });
+      if (this.mousePoints.length > this.maxMouseSamples) {
+        this.mousePoints.shift();
+      }
+    };
+    const onClick = () => {
+      this.clickTimes.push(Date.now());
+    };
+    const onKeyDown = () => {
+      this.keyStrokeCount += 1;
+    };
+    const onPointer = () => {
+      this.pointerActivity = true;
+    };
+    this.addListener("mousemove", onMouseMove);
+    this.addListener("click", onClick);
+    this.addListener("keydown", onKeyDown);
+    this.addListener("pointerdown", onPointer);
+    this.addListener("touchstart", onPointer);
+    return () => this.stop();
+  }
+  stop() {
+    if (!this.target) {
+      return;
+    }
+    for (const { type, handler } of this.listeners) {
+      this.target.removeEventListener(type, handler);
+    }
+    this.listeners = [];
+  }
+  /** Build a snapshot of collected signals. */
+  getSnapshot() {
+    const intervals = [];
+    for (let i = 1; i < this.clickTimes.length; i++) {
+      intervals.push(this.clickTimes[i] - this.clickTimes[i - 1]);
+    }
+    const avgClickIntervalMs = intervals.length > 0 ? intervals.reduce((sum, n) => sum + n, 0) / intervals.length : 0;
+    return {
+      mouseSampleCount: this.mousePoints.length,
+      mouseLinearity: computeMouseLinearity(this.mousePoints),
+      clickCount: this.clickTimes.length,
+      avgClickIntervalMs,
+      keyStrokeCount: this.keyStrokeCount,
+      hasPointerActivity: this.pointerActivity || this.mousePoints.length > 0,
+      collectionDurationMs: this.startedAt > 0 ? Date.now() - this.startedAt : 0
+    };
+  }
+  /** Push collected signals onto a Guardian instance. */
+  applyTo(guardian) {
+    const snapshot = this.getSnapshot();
+    return guardian.signal("mouseSampleCount", snapshot.mouseSampleCount).signal("mouseLinearity", round(snapshot.mouseLinearity, 4)).signal("clickCount", snapshot.clickCount).signal("avgClickIntervalMs", Math.round(snapshot.avgClickIntervalMs)).signal("keyStrokeCount", snapshot.keyStrokeCount).signal("hasPointerActivity", snapshot.hasPointerActivity).signal("collectionDurationMs", snapshot.collectionDurationMs).signal("signalSource", "browser");
+  }
+  addListener(type, handler) {
+    if (!this.target) {
+      return;
+    }
+    this.target.addEventListener(type, handler, { passive: true });
+    this.listeners.push({ type, handler });
+  }
+};
+function getDefaultTarget() {
+  if (typeof document !== "undefined") {
+    return document;
+  }
+  return null;
+}
+function round(value, digits) {
+  const factor = 10 ** digits;
+  return Math.round(value * factor) / factor;
+}
+
 // src/index.ts
 function browserPlugin(options = {}) {
-  const { container = "document" } = options;
+  const { autoStart = false, ...collectorOptions } = options;
   return {
     name: "guardian-risk-browser",
-    install(_guardian) {
+    install(guardian) {
+      guardian.ruleGroup({
+        name: "behavior",
+        maxScore: 50,
+        rules: [
+          {
+            name: "LinearMouse",
+            reason: "Mouse movement is unnaturally linear",
+            when: (s) => s.mouseLinearity > 0.92,
+            score: 25
+          },
+          {
+            name: "NoMouseActivity",
+            reason: "No pointer or mouse activity detected before submit",
+            when: (s) => s.mouseSampleCount === 0 && s.hasPointerActivity !== true,
+            score: 20
+          },
+          {
+            name: "RoboticClicks",
+            reason: "Click timing is unnaturally regular",
+            when: (s) => {
+              const interval = s.avgClickIntervalMs;
+              const count = s.clickCount;
+              return count >= 3 && interval > 0 && interval < 50;
+            },
+            score: 30
+          }
+        ]
+      });
+      if (autoStart && typeof document !== "undefined") {
+        const collector = new BrowserCollector(collectorOptions);
+        const stop = collector.start();
+        guardian.beforeAnalyze(({ guardian: g }) => {
+          collector.applyTo(g);
+          stop();
+        });
+      }
     }
   };
 }
-function collectSignals(guardian) {
-  return guardian.signal("signalSource", "browser").signal("browserPlugin", "stub");
+function createBrowserCollector(options = {}) {
+  return new BrowserCollector(options);
+}
+function collectSignals(guardian, options = {}) {
+  const { durationMs = 0, ...collectorOptions } = options;
+  const collector = new BrowserCollector(collectorOptions);
+  const stop = collector.start();
+  const finish = () => {
+    stop();
+    return collector.applyTo(guardian);
+  };
+  if (durationMs <= 0) {
+    return Promise.resolve(finish());
+  }
+  return new Promise((resolve) => {
+    setTimeout(() => resolve(finish()), durationMs);
+  });
 }
 
+exports.BrowserCollector = BrowserCollector;
 exports.browserPlugin = browserPlugin;
 exports.collectSignals = collectSignals;
+exports.computeMouseLinearity = computeMouseLinearity;
+exports.createBrowserCollector = createBrowserCollector;

package/dist/index.d.cts

@@ -1,21 +1,75 @@
 import * as guardian_risk from 'guardian-risk';
 import { Plugin } from 'guardian-risk';
 
-/** Options for the browser plugin (stub). */
-interface BrowserPluginOptions {
-    /** DOM element to attach behavioral collectors. Defaults to document. */
-    readonly container?: string;
+/** Collected behavioral signals from the browser. */
+interface BrowserSignalSnapshot {
+    readonly mouseSampleCount: number;
+    readonly mouseLinearity: number;
+    readonly clickCount: number;
+    readonly avgClickIntervalMs: number;
+    readonly keyStrokeCount: number;
+    readonly hasPointerActivity: boolean;
+    readonly collectionDurationMs: number;
 }
+/** Options for browser signal collection. */
+interface BrowserCollectorOptions {
+    /** Max mouse samples to retain. */
+    readonly maxMouseSamples?: number;
+    /** Target element or document root. */
+    readonly target?: EventTarget;
+}
+interface Point {
+    x: number;
+    y: number;
+    t: number;
+}
+/**
+ * Compute how linear a mouse path is (0 = erratic, 1 = perfectly straight).
+ * High values often indicate scripted movement.
+ */
+declare function computeMouseLinearity(points: readonly Point[]): number;
 /**
- * Browser plugin for guardian-risk.
- *
- * @stub Future versions will collect mouse, keyboard, and fingerprint signals
- * in the page and add them to Guardian before analysis.
+ * Collects mouse, click, and keyboard behavioral signals in the browser.
+ */
+declare class BrowserCollector {
+    private readonly maxMouseSamples;
+    private readonly target;
+    private readonly mousePoints;
+    private readonly clickTimes;
+    private keyStrokeCount;
+    private pointerActivity;
+    private startedAt;
+    private listeners;
+    constructor(options?: BrowserCollectorOptions);
+    /** Start listening for user events. Returns a stop function. */
+    start(): () => void;
+    stop(): void;
+    /** Build a snapshot of collected signals. */
+    getSnapshot(): BrowserSignalSnapshot;
+    /** Push collected signals onto a Guardian instance. */
+    applyTo(guardian: guardian_risk.Guardian): guardian_risk.Guardian;
+    private addListener;
+}
+
+/** Options for the browser plugin. */
+interface BrowserPluginOptions extends BrowserCollectorOptions {
+    /** Auto-start collection on install (browser only). */
+    readonly autoStart?: boolean;
+}
+/**
+ * Browser plugin — behavioral rules with a capped `behavior` group.
+ * Use {@link createBrowserCollector} to collect signals before analyze.
  */
 declare function browserPlugin(options?: BrowserPluginOptions): Plugin;
 /**
- * @stub Future helper to start client-side signal collection.
+ * Create a browser signal collector. Call `start()`, then `applyTo(guardian)` before analyze.
+ */
+declare function createBrowserCollector(options?: BrowserCollectorOptions): BrowserCollector;
+/**
+ * Collect signals then apply to Guardian. Optional `durationMs` to wait before sampling.
  */
-declare function collectSignals(guardian: guardian_risk.Guardian): guardian_risk.Guardian;
+declare function collectSignals(guardian: guardian_risk.Guardian, options?: BrowserCollectorOptions & {
+    durationMs?: number;
+}): Promise<guardian_risk.Guardian>;
 
-export { type BrowserPluginOptions, browserPlugin, collectSignals };
+export { BrowserCollector, type BrowserCollectorOptions, type BrowserPluginOptions, type BrowserSignalSnapshot, browserPlugin, collectSignals, computeMouseLinearity, createBrowserCollector };

package/dist/index.d.ts

@@ -1,21 +1,75 @@
 import * as guardian_risk from 'guardian-risk';
 import { Plugin } from 'guardian-risk';
 
-/** Options for the browser plugin (stub). */
-interface BrowserPluginOptions {
-    /** DOM element to attach behavioral collectors. Defaults to document. */
-    readonly container?: string;
+/** Collected behavioral signals from the browser. */
+interface BrowserSignalSnapshot {
+    readonly mouseSampleCount: number;
+    readonly mouseLinearity: number;
+    readonly clickCount: number;
+    readonly avgClickIntervalMs: number;
+    readonly keyStrokeCount: number;
+    readonly hasPointerActivity: boolean;
+    readonly collectionDurationMs: number;
 }
+/** Options for browser signal collection. */
+interface BrowserCollectorOptions {
+    /** Max mouse samples to retain. */
+    readonly maxMouseSamples?: number;
+    /** Target element or document root. */
+    readonly target?: EventTarget;
+}
+interface Point {
+    x: number;
+    y: number;
+    t: number;
+}
+/**
+ * Compute how linear a mouse path is (0 = erratic, 1 = perfectly straight).
+ * High values often indicate scripted movement.
+ */
+declare function computeMouseLinearity(points: readonly Point[]): number;
 /**
- * Browser plugin for guardian-risk.
- *
- * @stub Future versions will collect mouse, keyboard, and fingerprint signals
- * in the page and add them to Guardian before analysis.
+ * Collects mouse, click, and keyboard behavioral signals in the browser.
+ */
+declare class BrowserCollector {
+    private readonly maxMouseSamples;
+    private readonly target;
+    private readonly mousePoints;
+    private readonly clickTimes;
+    private keyStrokeCount;
+    private pointerActivity;
+    private startedAt;
+    private listeners;
+    constructor(options?: BrowserCollectorOptions);
+    /** Start listening for user events. Returns a stop function. */
+    start(): () => void;
+    stop(): void;
+    /** Build a snapshot of collected signals. */
+    getSnapshot(): BrowserSignalSnapshot;
+    /** Push collected signals onto a Guardian instance. */
+    applyTo(guardian: guardian_risk.Guardian): guardian_risk.Guardian;
+    private addListener;
+}
+
+/** Options for the browser plugin. */
+interface BrowserPluginOptions extends BrowserCollectorOptions {
+    /** Auto-start collection on install (browser only). */
+    readonly autoStart?: boolean;
+}
+/**
+ * Browser plugin — behavioral rules with a capped `behavior` group.
+ * Use {@link createBrowserCollector} to collect signals before analyze.
  */
 declare function browserPlugin(options?: BrowserPluginOptions): Plugin;
 /**
- * @stub Future helper to start client-side signal collection.
+ * Create a browser signal collector. Call `start()`, then `applyTo(guardian)` before analyze.
+ */
+declare function createBrowserCollector(options?: BrowserCollectorOptions): BrowserCollector;
+/**
+ * Collect signals then apply to Guardian. Optional `durationMs` to wait before sampling.
  */
-declare function collectSignals(guardian: guardian_risk.Guardian): guardian_risk.Guardian;
+declare function collectSignals(guardian: guardian_risk.Guardian, options?: BrowserCollectorOptions & {
+    durationMs?: number;
+}): Promise<guardian_risk.Guardian>;
 
-export { type BrowserPluginOptions, browserPlugin, collectSignals };
+export { BrowserCollector, type BrowserCollectorOptions, type BrowserPluginOptions, type BrowserSignalSnapshot, browserPlugin, collectSignals, computeMouseLinearity, createBrowserCollector };

package/dist/index.js

@@ -1,14 +1,184 @@
+// src/collector.ts
+function computeMouseLinearity(points) {
+  if (points.length < 3) {
+    return 0;
+  }
+  const first = points[0];
+  const last = points[points.length - 1];
+  const straightDistance = distance(first, last);
+  if (straightDistance === 0) {
+    return 1;
+  }
+  let pathDistance = 0;
+  for (let i = 1; i < points.length; i++) {
+    pathDistance += distance(points[i - 1], points[i]);
+  }
+  if (pathDistance === 0) {
+    return 0;
+  }
+  const linearity = straightDistance / pathDistance;
+  return Math.min(1, Math.max(0, linearity));
+}
+function distance(a, b) {
+  const dx = b.x - a.x;
+  const dy = b.y - a.y;
+  return Math.sqrt(dx * dx + dy * dy);
+}
+var BrowserCollector = class {
+  maxMouseSamples;
+  target;
+  mousePoints = [];
+  clickTimes = [];
+  keyStrokeCount = 0;
+  pointerActivity = false;
+  startedAt = 0;
+  listeners = [];
+  constructor(options = {}) {
+    this.maxMouseSamples = options.maxMouseSamples ?? 100;
+    this.target = options.target ?? getDefaultTarget();
+  }
+  /** Start listening for user events. Returns a stop function. */
+  start() {
+    if (!this.target) {
+      return () => {
+      };
+    }
+    this.startedAt = Date.now();
+    const onMouseMove = (event) => {
+      const e = event;
+      this.mousePoints.push({ x: e.clientX, y: e.clientY, t: Date.now() });
+      if (this.mousePoints.length > this.maxMouseSamples) {
+        this.mousePoints.shift();
+      }
+    };
+    const onClick = () => {
+      this.clickTimes.push(Date.now());
+    };
+    const onKeyDown = () => {
+      this.keyStrokeCount += 1;
+    };
+    const onPointer = () => {
+      this.pointerActivity = true;
+    };
+    this.addListener("mousemove", onMouseMove);
+    this.addListener("click", onClick);
+    this.addListener("keydown", onKeyDown);
+    this.addListener("pointerdown", onPointer);
+    this.addListener("touchstart", onPointer);
+    return () => this.stop();
+  }
+  stop() {
+    if (!this.target) {
+      return;
+    }
+    for (const { type, handler } of this.listeners) {
+      this.target.removeEventListener(type, handler);
+    }
+    this.listeners = [];
+  }
+  /** Build a snapshot of collected signals. */
+  getSnapshot() {
+    const intervals = [];
+    for (let i = 1; i < this.clickTimes.length; i++) {
+      intervals.push(this.clickTimes[i] - this.clickTimes[i - 1]);
+    }
+    const avgClickIntervalMs = intervals.length > 0 ? intervals.reduce((sum, n) => sum + n, 0) / intervals.length : 0;
+    return {
+      mouseSampleCount: this.mousePoints.length,
+      mouseLinearity: computeMouseLinearity(this.mousePoints),
+      clickCount: this.clickTimes.length,
+      avgClickIntervalMs,
+      keyStrokeCount: this.keyStrokeCount,
+      hasPointerActivity: this.pointerActivity || this.mousePoints.length > 0,
+      collectionDurationMs: this.startedAt > 0 ? Date.now() - this.startedAt : 0
+    };
+  }
+  /** Push collected signals onto a Guardian instance. */
+  applyTo(guardian) {
+    const snapshot = this.getSnapshot();
+    return guardian.signal("mouseSampleCount", snapshot.mouseSampleCount).signal("mouseLinearity", round(snapshot.mouseLinearity, 4)).signal("clickCount", snapshot.clickCount).signal("avgClickIntervalMs", Math.round(snapshot.avgClickIntervalMs)).signal("keyStrokeCount", snapshot.keyStrokeCount).signal("hasPointerActivity", snapshot.hasPointerActivity).signal("collectionDurationMs", snapshot.collectionDurationMs).signal("signalSource", "browser");
+  }
+  addListener(type, handler) {
+    if (!this.target) {
+      return;
+    }
+    this.target.addEventListener(type, handler, { passive: true });
+    this.listeners.push({ type, handler });
+  }
+};
+function getDefaultTarget() {
+  if (typeof document !== "undefined") {
+    return document;
+  }
+  return null;
+}
+function round(value, digits) {
+  const factor = 10 ** digits;
+  return Math.round(value * factor) / factor;
+}
+
 // src/index.ts
 function browserPlugin(options = {}) {
-  const { container = "document" } = options;
+  const { autoStart = false, ...collectorOptions } = options;
   return {
     name: "guardian-risk-browser",
-    install(_guardian) {
+    install(guardian) {
+      guardian.ruleGroup({
+        name: "behavior",
+        maxScore: 50,
+        rules: [
+          {
+            name: "LinearMouse",
+            reason: "Mouse movement is unnaturally linear",
+            when: (s) => s.mouseLinearity > 0.92,
+            score: 25
+          },
+          {
+            name: "NoMouseActivity",
+            reason: "No pointer or mouse activity detected before submit",
+            when: (s) => s.mouseSampleCount === 0 && s.hasPointerActivity !== true,
+            score: 20
+          },
+          {
+            name: "RoboticClicks",
+            reason: "Click timing is unnaturally regular",
+            when: (s) => {
+              const interval = s.avgClickIntervalMs;
+              const count = s.clickCount;
+              return count >= 3 && interval > 0 && interval < 50;
+            },
+            score: 30
+          }
+        ]
+      });
+      if (autoStart && typeof document !== "undefined") {
+        const collector = new BrowserCollector(collectorOptions);
+        const stop = collector.start();
+        guardian.beforeAnalyze(({ guardian: g }) => {
+          collector.applyTo(g);
+          stop();
+        });
+      }
     }
   };
 }
-function collectSignals(guardian) {
-  return guardian.signal("signalSource", "browser").signal("browserPlugin", "stub");
+function createBrowserCollector(options = {}) {
+  return new BrowserCollector(options);
+}
+function collectSignals(guardian, options = {}) {
+  const { durationMs = 0, ...collectorOptions } = options;
+  const collector = new BrowserCollector(collectorOptions);
+  const stop = collector.start();
+  const finish = () => {
+    stop();
+    return collector.applyTo(guardian);
+  };
+  if (durationMs <= 0) {
+    return Promise.resolve(finish());
+  }
+  return new Promise((resolve) => {
+    setTimeout(() => resolve(finish()), durationMs);
+  });
 }
 
-export { browserPlugin, collectSignals };
+export { BrowserCollector, browserPlugin, collectSignals, computeMouseLinearity, createBrowserCollector };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "guardian-risk-browser",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Browser plugin for guardian-risk — collects behavioral and fingerprint signals",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -54,15 +54,17 @@
     "access": "public"
   },
   "peerDependencies": {
-    "guardian-risk": "^0.2.0"
+    "guardian-risk": "^0.3.1"
   },
   "devDependencies": {
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
-    "guardian-risk": "0.2.1"
+    "vitest": "^4.1.9",
+    "guardian-risk": "0.3.1"
   },
   "scripts": {
     "build": "tsup",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }
 }