@magield/collectors 0.0.0-stage → 0.7.1

package/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2026 MagicShield. All rights reserved.
+
+MAGIC SHIELD SDK LICENCE
+
+This package is published to a public registry so that licensed customers can
+install it with ordinary tooling. Being able to download it does not grant any
+right to use it.
+
+You may install, use and redistribute this package, unmodified and only as part
+of your own application, solely to integrate that application with a Magic
+Shield deployment that you are licensed to use under a written agreement with
+MagicShield ("your Agreement"), and only for the term of your Agreement.
+
+Except as your Agreement expressly allows, you may not:
+
+  - use this package for any other purpose, including to build, benchmark or
+    assist a competing product;
+  - modify it, or reverse engineer, decompile, deobfuscate or disassemble it,
+    except to the extent this restriction is unenforceable under applicable law;
+  - remove or alter this notice or any copyright or attribution in it.
+
+THE PACKAGE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXCEPT AS YOUR
+AGREEMENT PROVIDES. IN NO EVENT SHALL MAGICSHIELD BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY ARISING FROM THE PACKAGE OR ITS USE, EXCEPT AS YOUR
+AGREEMENT PROVIDES.
+
+Your Agreement governs if it conflicts with this notice.

package/dist/behavior/recorder.d.ts

@@ -0,0 +1,33 @@
+import type { SignalValue } from '../types.js';
+export interface BehaviorSummary {
+    readonly [key: string]: SignalValue;
+}
+export interface RecorderTarget {
+    addEventListener(type: string, listener: (event: Event) => void, options?: unknown): void;
+    removeEventListener(type: string, listener: (event: Event) => void, options?: unknown): void;
+}
+export interface RecorderOptions {
+    readonly now?: () => number;
+}
+/**
+ * Accumulates behavioural statistics from a target's input events.
+ *
+ * Constructed once per page and attached to the document; `stop()` detaches
+ * everything, so an SPA that mounts and unmounts a form does not leak listeners.
+ */
+export declare class BehaviorRecorder {
+    #private;
+    constructor(options?: RecorderOptions);
+    /**
+     * Attaches to a target.
+     *
+     * Passive and capturing: passive so the page's scrolling is never blocked by
+     * us, capturing so a form that calls `stopPropagation` on its own inputs does
+     * not silently blind the recorder. A fingerprinting library that degrades a
+     * host page's scroll performance has failed at being a guest.
+     */
+    attach(target: RecorderTarget): void;
+    stop(): void;
+    /** Derived statistics only. Safe to call repeatedly. */
+    summary(): BehaviorSummary;
+}

package/dist/behavior/recorder.js

@@ -0,0 +1,303 @@
+/**
+ * Behavioural observation.
+ *
+ * Every other collector takes a snapshot: it reads a property and returns. This
+ * one cannot — human-ness is in how input arrives over time, so something has
+ * to be listening from page load, long before anyone submits a form.
+ *
+ * **Raw event streams never leave the page, and are never even retained.**
+ * Statistics are folded in as events arrive and the events are dropped, which
+ * is both the privacy position and the reason memory is bounded regardless of
+ * how long a tab stays open. A pointer trail is a biometric and a keystroke
+ * sequence leaks the text; neither is worth having on a server to decide
+ * whether one login looks automated.
+ *
+ * What is deliberately NOT captured, though the plan lists it: key identity of
+ * any kind, and `beh.key.digraph_profile`. Per-user typing rhythm at that
+ * resolution identifies people across sessions, which is a different product
+ * from deciding whether this request is a script.
+ */
+/** Past this, the distribution is established and more samples buy nothing. */
+const MAX_SAMPLES = 256;
+/** Listeners we attach. All passive: the page's own handling is never affected. */
+const POINTER_EVENTS = ['pointermove', 'pointerdown', 'pointerup'];
+const KEY_EVENTS = ['keydown', 'keyup'];
+function push(w, x) {
+    w.n += 1;
+    const delta = x - w.mean;
+    w.mean += delta / w.n;
+    w.m2 += delta * (x - w.mean);
+}
+function sd(w) {
+    return w.n < 2 ? null : Math.sqrt(w.m2 / (w.n - 1));
+}
+function mean(w) {
+    return w.n === 0 ? null : w.mean;
+}
+const DIRECTION_BUCKETS = 8;
+/**
+ * Accumulates behavioural statistics from a target's input events.
+ *
+ * Constructed once per page and attached to the document; `stop()` detaches
+ * everything, so an SPA that mounts and unmounts a form does not leak listeners.
+ */
+export class BehaviorRecorder {
+    #now;
+    #started;
+    // Pointer.
+    #moveInterval = { n: 0, mean: 0, m2: 0 };
+    #speed = { n: 0, mean: 0, m2: 0 };
+    #curvature = { n: 0, mean: 0, m2: 0 };
+    #directions = new Array(DIRECTION_BUCKETS).fill(0);
+    #pointerSamples = 0;
+    #lastPoint;
+    #lastAngle;
+    #lastMoveAt;
+    // Keyboard. Dwell is press-to-release of one key; flight is release-to-press
+    // between keys. Neither records which key.
+    #dwell = { n: 0, mean: 0, m2: 0 };
+    #flight = { n: 0, mean: 0, m2: 0 };
+    #downAt = new Map();
+    #lastUpAt;
+    #keySamples = 0;
+    // Everything else.
+    #pasteEvents = 0;
+    #scrollEvents = 0;
+    #wheelDeltaModes = new Set();
+    #touchPoints = 0;
+    #maxTouchRadius = 0;
+    #touchForceSeen = false;
+    #focusChanges = 0;
+    #fieldsFocused = new Set();
+    #focusOrder = [];
+    #trustedEvents = 0;
+    #untrustedEvents = 0;
+    #firstInteractionAt;
+    #lastPointerDownAt;
+    #dwellBeforeClick;
+    #detach = [];
+    constructor(options = {}) {
+        this.#now = options.now ?? (() => Date.now());
+        this.#started = this.#now();
+    }
+    /**
+     * Attaches to a target.
+     *
+     * Passive and capturing: passive so the page's scrolling is never blocked by
+     * us, capturing so a form that calls `stopPropagation` on its own inputs does
+     * not silently blind the recorder. A fingerprinting library that degrades a
+     * host page's scroll performance has failed at being a guest.
+     */
+    attach(target) {
+        const options = { passive: true, capture: true };
+        const on = (type, handler) => {
+            target.addEventListener(type, handler, options);
+            this.#detach.push(() => target.removeEventListener(type, handler, options));
+        };
+        for (const type of POINTER_EVENTS)
+            on(type, (e) => this.#onPointer(e, type));
+        for (const type of KEY_EVENTS)
+            on(type, (e) => this.#onKey(e, type));
+        on('paste', (e) => this.#onPaste(e));
+        on('wheel', (e) => this.#onWheel(e));
+        on('scroll', () => {
+            this.#scrollEvents += 1;
+        });
+        on('touchstart', (e) => this.#onTouch(e));
+        on('focusin', (e) => this.#onFocus(e));
+    }
+    stop() {
+        for (const off of this.#detach)
+            off();
+        this.#detach = [];
+    }
+    #mark(event) {
+        // `isTrusted` is false for anything a page dispatched itself, which catches
+        // naive `element.click()` automation. It is true for CDP-driven input, so a
+        // high ratio proves nothing — only a low one is informative.
+        if (event.isTrusted === true)
+            this.#trustedEvents += 1;
+        else
+            this.#untrustedEvents += 1;
+        this.#firstInteractionAt ??= this.#now();
+    }
+    #onPointer(event, type) {
+        this.#mark(event);
+        if (type === 'pointerdown') {
+            this.#lastPointerDownAt = this.#now();
+            // Zero movement before a click is the classic scripted submit. Recorded
+            // as the gap since the last observed move, not as a verdict.
+            this.#dwellBeforeClick =
+                this.#lastMoveAt === undefined ? undefined : Math.round(this.#lastPointerDownAt - this.#lastMoveAt);
+            return;
+        }
+        if (type === 'pointerup')
+            return;
+        if (this.#pointerSamples >= MAX_SAMPLES)
+            return;
+        const t = this.#now();
+        const x = event.clientX;
+        const y = event.clientY;
+        if (typeof x !== 'number' || typeof y !== 'number')
+            return;
+        const previous = this.#lastPoint;
+        this.#lastPoint = { x, y, t };
+        this.#lastMoveAt = t;
+        this.#pointerSamples += 1;
+        if (previous === undefined)
+            return;
+        const dx = x - previous.x;
+        const dy = y - previous.y;
+        const dt = t - previous.t;
+        const distance = Math.hypot(dx, dy);
+        if (dt > 0) {
+            push(this.#moveInterval, dt);
+            push(this.#speed, distance / dt);
+        }
+        if (distance === 0)
+            return;
+        const angle = Math.atan2(dy, dx);
+        // Direction histogram, for entropy. A straight programmatic path fills one
+        // bucket; a hand filling a form fills most of them.
+        const bucket = Math.min(DIRECTION_BUCKETS - 1, Math.max(0, Math.floor(((angle + Math.PI) / (2 * Math.PI)) * DIRECTION_BUCKETS)));
+        this.#directions[bucket] = (this.#directions[bucket] ?? 0) + 1;
+        if (this.#lastAngle !== undefined) {
+            let turn = angle - this.#lastAngle;
+            while (turn > Math.PI)
+                turn -= 2 * Math.PI;
+            while (turn < -Math.PI)
+                turn += 2 * Math.PI;
+            push(this.#curvature, Math.abs(turn));
+        }
+        this.#lastAngle = angle;
+    }
+    #onKey(event, type) {
+        this.#mark(event);
+        if (this.#keySamples >= MAX_SAMPLES)
+            return;
+        // `event.code` is the physical key position, used only as a correlation
+        // handle to pair a keyup with its keydown, and never recorded.
+        const handle = event.code || event.key || 'k';
+        const t = this.#now();
+        if (type === 'keydown') {
+            if (!this.#downAt.has(handle))
+                this.#downAt.set(handle, t);
+            if (this.#lastUpAt !== undefined)
+                push(this.#flight, t - this.#lastUpAt);
+            return;
+        }
+        const downAt = this.#downAt.get(handle);
+        if (downAt !== undefined) {
+            push(this.#dwell, t - downAt);
+            this.#downAt.delete(handle);
+            this.#keySamples += 1;
+        }
+        this.#lastUpAt = t;
+    }
+    #onPaste(event) {
+        this.#mark(event);
+        this.#pasteEvents += 1;
+    }
+    #onWheel(event) {
+        this.#mark(event);
+        this.#scrollEvents += 1;
+        // A trackpad emits pixel deltas, a wheel emits lines. Which one is present
+        // says something about the device that the user agent does not.
+        if (typeof event.deltaMode === 'number')
+            this.#wheelDeltaModes.add(event.deltaMode);
+    }
+    #onTouch(event) {
+        this.#mark(event);
+        const touches = event.touches;
+        if (touches === undefined || touches.length === 0)
+            return;
+        this.#touchPoints = Math.max(this.#touchPoints, touches.length);
+        for (let i = 0; i < touches.length; i++) {
+            const touch = touches.item(i);
+            if (touch === null)
+                continue;
+            const radius = Math.max(touch.radiusX ?? 0, touch.radiusY ?? 0);
+            if (radius > this.#maxTouchRadius)
+                this.#maxTouchRadius = radius;
+            // A real finger reports a varying force; a synthesised touch reports 0.
+            if (typeof touch.force === 'number' && touch.force > 0)
+                this.#touchForceSeen = true;
+        }
+    }
+    #onFocus(event) {
+        this.#mark(event);
+        this.#focusChanges += 1;
+        const target = event.target;
+        if (target === null)
+            return;
+        // A stable handle for the field, never its value and never its label. Used
+        // only to see whether fields were filled in DOM order.
+        const handle = target.id ?? target.name ?? target.tagName ?? '';
+        if (handle === '')
+            return;
+        this.#fieldsFocused.add(handle);
+        if (this.#focusOrder.length < 32)
+            this.#focusOrder.push(handle);
+    }
+    /** Derived statistics only. Safe to call repeatedly. */
+    summary() {
+        const now = this.#now();
+        const observed = this.#trustedEvents + this.#untrustedEvents;
+        const out = {};
+        out['beh.observed'] = observed > 0;
+        out['beh.pointer.samples'] = this.#pointerSamples;
+        out['beh.pointer.entropy'] = this.#pointerSamples === 0 ? null : round(entropy(this.#directions), 3);
+        out['beh.pointer.curvature'] = roundOrNull(mean(this.#curvature), 4);
+        out['beh.pointer.curvature_sd'] = roundOrNull(sd(this.#curvature), 4);
+        out['beh.pointer.speed_mean'] = roundOrNull(mean(this.#speed), 4);
+        out['beh.pointer.speed_sd'] = roundOrNull(sd(this.#speed), 4);
+        out['beh.pointer.interval_mean'] = roundOrNull(mean(this.#moveInterval), 2);
+        out['beh.pointer.interval_sd'] = roundOrNull(sd(this.#moveInterval), 2);
+        out['beh.pointer.dwell_before_click'] = this.#dwellBeforeClick ?? null;
+        out['beh.key.samples'] = this.#keySamples;
+        out['beh.key.dwell_mean'] = roundOrNull(mean(this.#dwell), 2);
+        out['beh.key.dwell_sd'] = roundOrNull(sd(this.#dwell), 2);
+        out['beh.key.flight_mean'] = roundOrNull(mean(this.#flight), 2);
+        out['beh.key.flight_sd'] = roundOrNull(sd(this.#flight), 2);
+        out['beh.paste_events'] = this.#pasteEvents;
+        out['beh.scroll.events'] = this.#scrollEvents;
+        out['beh.scroll.signature'] = this.#scrollEvents === 0 ? null : [...this.#wheelDeltaModes].sort().join(',');
+        out['beh.touch.points'] = this.#touchPoints;
+        out['beh.touch.radius_max'] = this.#maxTouchRadius === 0 ? null : round(this.#maxTouchRadius, 1);
+        out['beh.touch.force_seen'] = this.#touchPoints === 0 ? null : this.#touchForceSeen;
+        out['beh.focus_changes'] = this.#focusChanges;
+        out['beh.fields_focused'] = this.#fieldsFocused.size;
+        out['beh.focus_sequence'] = this.#focusOrder.length === 0 ? null : this.#focusOrder.join('>');
+        out['beh.is_trusted_ratio'] = observed === 0 ? null : round(this.#trustedEvents / observed, 3);
+        out['beh.time_to_first_interaction'] =
+            this.#firstInteractionAt === undefined ? null : Math.round(this.#firstInteractionAt - this.#started);
+        out['beh.total_dwell'] = Math.round(now - this.#started);
+        return out;
+    }
+}
+/**
+ * Shannon entropy over the direction histogram, normalised to 0..1.
+ *
+ * Normalised so the number means the same thing however many buckets there are:
+ * 0 is one direction only, 1 is uniform. A raw bit count would silently change
+ * meaning if the bucket count were ever tuned.
+ */
+function entropy(counts) {
+    const total = counts.reduce((sum, n) => sum + n, 0);
+    if (total === 0)
+        return 0;
+    let h = 0;
+    for (const count of counts) {
+        if (count === 0)
+            continue;
+        const p = count / total;
+        h -= p * Math.log2(p);
+    }
+    return h / Math.log2(counts.length);
+}
+function round(value, places) {
+    return Number(value.toFixed(places));
+}
+function roundOrNull(value, places) {
+    return value === null ? null : round(value, places);
+}

package/dist/hash.d.ts

@@ -0,0 +1,15 @@
+/**
+ * FNV-1a, 32-bit, rendered as 8 hex characters.
+ *
+ * Not a security hash and never used as one: these values identify a rendering
+ * stack, not a person, and they are re-hashed with a per-tenant salt server-side
+ * before they are stored. A cryptographic hash in the browser would cost bundle
+ * size and async plumbing for no benefit here.
+ */
+export declare function hash(input: string): string;
+/**
+ * Stable across key insertion order, so the same environment always produces
+ * the same hash. JSON of the sorted pairs also makes the separator
+ * unambiguous — a value containing the delimiter cannot forge a collision.
+ */
+export declare function hashRecord(record: Record<string, unknown>): string;

package/dist/hash.js

@@ -0,0 +1,27 @@
+/**
+ * FNV-1a, 32-bit, rendered as 8 hex characters.
+ *
+ * Not a security hash and never used as one: these values identify a rendering
+ * stack, not a person, and they are re-hashed with a per-tenant salt server-side
+ * before they are stored. A cryptographic hash in the browser would cost bundle
+ * size and async plumbing for no benefit here.
+ */
+export function hash(input) {
+    let value = 0x811c9dc5;
+    for (let i = 0; i < input.length; i++) {
+        value ^= input.charCodeAt(i);
+        value = Math.imul(value, 0x01000193);
+    }
+    return (value >>> 0).toString(16).padStart(8, '0');
+}
+/**
+ * Stable across key insertion order, so the same environment always produces
+ * the same hash. JSON of the sorted pairs also makes the separator
+ * unambiguous — a value containing the delimiter cannot forge a collision.
+ */
+export function hashRecord(record) {
+    const entries = Object.entries(record)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([key, value]) => [key, String(value)]);
+    return hash(JSON.stringify(entries));
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { runCollectors, type RunOptions } from './run.js';
+export { ALL_COLLECTORS, COLLECTOR_IDS, INVASIVE_COLLECTORS } from './registry.js';
+export { hash, hashRecord } from './hash.js';
+export { WAVE_BUDGET_MS, type CollectionResult, type Collector, type CollectorEnv, type SignalValue, type Wave, } from './types.js';
+export { stableCore, hardwareCore, browserCore, STABLE_KEYS, HARDWARE_KEYS, BROWSER_KEYS, EXCLUDED_FROM_CORE, type StableCore, type CoreTier, } from './stable-core.js';
+export { BehaviorRecorder, type BehaviorSummary, type RecorderOptions, type RecorderTarget, } from './behavior/recorder.js';
+export { behaviorCollector } from './signals/behavior.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+export { runCollectors } from './run.js';
+export { ALL_COLLECTORS, COLLECTOR_IDS, INVASIVE_COLLECTORS } from './registry.js';
+export { hash, hashRecord } from './hash.js';
+export { WAVE_BUDGET_MS, } from './types.js';
+export { stableCore, hardwareCore, browserCore, STABLE_KEYS, HARDWARE_KEYS, BROWSER_KEYS, EXCLUDED_FROM_CORE, } from './stable-core.js';
+export { BehaviorRecorder, } from './behavior/recorder.js';
+export { behaviorCollector } from './signals/behavior.js';

package/dist/native.d.ts

@@ -0,0 +1,39 @@
+export declare function isNativeSource(source: string): boolean;
+/**
+ * Whether a native stub carries the name its function claims to have.
+ *
+ * A `Proxy` around a native function is still reported as native — V8 hands
+ * back a native stub for any callable proxy — so a source check alone cannot
+ * see a proxy-wrapped intrinsic. It does lose the *name*, which is the tell.
+ * Measured on Chrome 141:
+ *
+ *   Function.prototype.toString              function toString() { [native code] }
+ *   new Proxy(Function.prototype.toString)   function () { [native code] }
+ *
+ * `.name` reports `toString` in both cases, because the proxy forwards the
+ * property. So the contradiction is between the name the function claims and
+ * the name the engine prints for it, and every intrinsic this package probes
+ * prints its name in a clean realm — verified in a browser, not assumed.
+ *
+ * Bound functions print anonymously too, and legitimately. Their names start
+ * with `bound `, which is the documented exemption rather than a guess.
+ */
+export declare function nameMatchesSource(name: string, source: string): boolean;
+/**
+ * Whether a function has a proxy standing in front of it.
+ *
+ * `undefined` means the question could not be asked — the call did not throw, or
+ * the engine gave us no stack — and is never reported as clean.
+ */
+export declare function interposesApplyTrap(target: unknown): boolean | undefined;
+/**
+ * Whether this engine names a proxy's `apply` trap on a stack at all.
+ *
+ * The positive control for `interposesApplyTrap`, given a native that throws on
+ * an illegal receiver. Wraps it in a proxy of its own — never installed
+ * anywhere, so nothing observable changes — and checks that the technique sees
+ * it. A caller that gets `false` here must report "cannot tell" rather than
+ * "clean", because a silent failure of this technique looks exactly like a
+ * browser with nothing to hide.
+ */
+export declare function applyTrapIsObservable(native: (...args: unknown[]) => unknown): boolean;

package/dist/native.js

@@ -0,0 +1,142 @@
+/**
+ * Whether a function's source is a genuine native stub.
+ *
+ * `String.includes('[native code]')` is the obvious test and it is wrong: it
+ * asks whether the text appears *anywhere*, so any replacement whose own source
+ * happens to contain those fifteen characters passes. That is not a theoretical
+ * evasion — a replacement only has to mention the string to be waved through:
+ *
+ *   const patched = () => 'function () { [native code] }'
+ *
+ * stringifies to its own source, which contains `[native code]`, and a
+ * substring test calls it native.
+ *
+ * Engines emit a fixed shape instead, and it is worth matching properly:
+ *
+ *   function max() { [native code] }          V8, ordinary native
+ *   function () { [native code] }             V8, bound function
+ *   function get webdriver() { [native code] } V8, accessor
+ *   function max() {\n    [native code]\n}    SpiderMonkey / JavaScriptCore
+ *
+ * Anchored at both ends, so the text has to *be* the stub rather than contain
+ * it. Whitespace is loose because engines disagree about newlines, and the name
+ * is loose because it carries `get`/`set`/`bound` prefixes and can be empty.
+ */
+const NATIVE_SOURCE = /^\s*function[\s\w$]*\([^)]*\)\s*\{\s*\[native code\]\s*\}\s*$/;
+export function isNativeSource(source) {
+    return NATIVE_SOURCE.test(source);
+}
+/**
+ * Whether a native stub carries the name its function claims to have.
+ *
+ * A `Proxy` around a native function is still reported as native — V8 hands
+ * back a native stub for any callable proxy — so a source check alone cannot
+ * see a proxy-wrapped intrinsic. It does lose the *name*, which is the tell.
+ * Measured on Chrome 141:
+ *
+ *   Function.prototype.toString              function toString() { [native code] }
+ *   new Proxy(Function.prototype.toString)   function () { [native code] }
+ *
+ * `.name` reports `toString` in both cases, because the proxy forwards the
+ * property. So the contradiction is between the name the function claims and
+ * the name the engine prints for it, and every intrinsic this package probes
+ * prints its name in a clean realm — verified in a browser, not assumed.
+ *
+ * Bound functions print anonymously too, and legitimately. Their names start
+ * with `bound `, which is the documented exemption rather than a guess.
+ */
+export function nameMatchesSource(name, source) {
+    if (name === '' || name.startsWith('bound '))
+        return true;
+    return new RegExp(`^\\s*function\\s+${escapeName(name)}\\s*\\(`).test(source);
+}
+/** A function name can contain `$`, which is a regex metacharacter. */
+function escapeName(name) {
+    return name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * The frame an engine prints for a proxy's `apply` trap.
+ *
+ * V8 describes the trap rather than the wrapper, so this text comes from the
+ * engine and not from anything the page controls — it survives minification of
+ * the probe and cannot be renamed by the plugin. Measured shapes:
+ *
+ *   at Object.apply                                          a bare Proxy handler
+ *   at newHandler.<computed> [as apply] (eval at <anonymous>) stealth's own
+ *
+ * Deliberately not matched against the probe's own call frame: the probe invokes
+ * through `.call`, never `.apply`, so its own frames cannot contain this word.
+ */
+const APPLY_TRAP = /\bapply\b/;
+/**
+ * How many frames from the top may hold the trap.
+ *
+ * Not one, which a first version of this assumed and measurement disproved. V8
+ * prints the native's *own* frame for a JavaScript builtin and omits it for a
+ * Blink DOM method, so the trap sits one place lower in the first case:
+ *
+ *   Map.prototype.size through a proxy    [0] at get size   [1] at Object.apply
+ *   canvas.toDataURL through a proxy      [0] at Object.apply
+ *
+ * Three covers both, plus a handler that calls through `Reflect.apply`. It stays
+ * small because the frames below belong to the caller, and a page that reached
+ * this collector through something of its own named `apply` would otherwise
+ * accuse itself.
+ *
+ * The window does not have to be right by argument, which is the point of
+ * `applyTrapIsObservable`: the control runs this same rule at this same stack
+ * depth, so an engine where the indexing does not hold fails the control and the
+ * caller abstains instead of reporting everyone clean.
+ */
+const TRAP_WINDOW = 3;
+/**
+ * Whether a function has a proxy standing in front of it.
+ *
+ * `undefined` means the question could not be asked — the call did not throw, or
+ * the engine gave us no stack — and is never reported as clean.
+ */
+export function interposesApplyTrap(target) {
+    if (typeof target !== 'function')
+        return undefined;
+    try {
+        // An illegal receiver. Every candidate this is used on validates `this`
+        // before it looks at its arguments, so one call with no arguments is enough
+        // and nothing observable happens on the way.
+        ;
+        target.call(null);
+        return undefined;
+    }
+    catch (error) {
+        const stack = error instanceof Error ? error.stack : undefined;
+        if (typeof stack !== 'string' || stack === '')
+            return undefined;
+        const frames = stack
+            .split('\n')
+            .filter((line) => /^\s*at\s/.test(line))
+            .slice(0, TRAP_WINDOW);
+        if (frames.length === 0)
+            return undefined;
+        return frames.some((line) => APPLY_TRAP.test(line));
+    }
+}
+/**
+ * Whether this engine names a proxy's `apply` trap on a stack at all.
+ *
+ * The positive control for `interposesApplyTrap`, given a native that throws on
+ * an illegal receiver. Wraps it in a proxy of its own — never installed
+ * anywhere, so nothing observable changes — and checks that the technique sees
+ * it. A caller that gets `false` here must report "cannot tell" rather than
+ * "clean", because a silent failure of this technique looks exactly like a
+ * browser with nothing to hide.
+ */
+export function applyTrapIsObservable(native) {
+    try {
+        const wrapped = new Proxy(native, {
+            apply: (fn, self, args) => Reflect.apply(fn, self, args),
+        });
+        return interposesApplyTrap(wrapped) === true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/registry.d.ts

@@ -0,0 +1,57 @@
+import type { Collector } from './types.js';
+/**
+ * Order within a wave is the order they run, so the cheapest and most
+ * universally available come first: when a budget runs out, what survives
+ * should be the signals present on every device rather than the exotic ones.
+ */
+export declare const ALL_COLLECTORS: readonly Collector[];
+export declare const COLLECTOR_IDS: readonly string[];
+/**
+ * Collectors a deployment must ask for by name.
+ *
+ * Deliberately absent from `ALL_COLLECTORS`, so no default enables them and no
+ * tenant gets them by forgetting to opt out. Everything here reads something
+ * about the person rather than about their browser, which makes enabling it a
+ * decision somebody has to make on purpose and be able to point at a consent
+ * for.
+ *
+ * Pass them explicitly:
+ *
+ *   runCollectors(env, { collectors: [...ALL_COLLECTORS, ...INVASIVE_COLLECTORS] })
+ *
+ * The split is the product position, not a technical one. `docs/` says what
+ * Magic Shield collects by default, and this is the list that is not in it.
+ */
+export declare const INVASIVE_COLLECTORS: readonly Collector[];
+/**
+ * Removed: localPortsCollector.
+ *
+ * It probed nine loopback ports for automation drivers, remote-control tools
+ * and anti-detect control APIs, and it was measured from the wrong place. The
+ * fp-lab page is served from `127.0.0.1`, so the probe was local reaching
+ * local — the one case Chrome does not gate — and it reported nine ports
+ * cleanly probed.
+ *
+ * From a public origin, which is every real deployment, Chrome 153 answers
+ * `navigator.permissions.query({ name: 'local-network-access' })` with
+ * **prompt**. Measured from `https://example.com` against known ports:
+ *
+ *   8791  open    hung until aborted at 1.5 s
+ *   9515  closed  Failed to fetch in 10 ms
+ *   18123 closed  hung until aborted at 2.0 s
+ *
+ * So it does not work, and the way it fails is worse than not working. The
+ * open port did not complete and two results were indistinguishable hangs, so
+ * the answers are noise; and a pending permission decision blocks, which on a
+ * login page means burning the deep wave and showing the visitor a prompt
+ * asking to access their local network. Nobody accepts that prompt, and asking
+ * is itself the harm.
+ *
+ * Not kept behind a flag. A collector that prompts cannot be enabled by a
+ * deployment without the person seeing it, which is the line this set does not
+ * cross — every other member runs silently.
+ *
+ * If it ever comes back it needs the permission requested honestly, at a
+ * moment the person understands, which is a product decision rather than a
+ * collector.
+ */