@vectoral-labs/browser 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,189 @@
+interface DeviceFingerprintOptions {
+    /** Your publishable site key (`pk_live_…`). Scopes the value to your tenant. */
+    siteKey: string;
+}
+interface DeviceFingerprint {
+    /** `fp_` + 32 hex chars. Send as `device_fingerprint`. */
+    fingerprint: string;
+    /**
+     * False when SubtleCrypto was unavailable (an insecure context) and a
+     * non-cryptographic fallback hash was used. The value is still stable and
+     * still comparable — it is just cheaper to reverse, so do not treat it as a
+     * privacy boundary.
+     */
+    strong: boolean;
+    /**
+     * How many of the components actually resolved, out of the total attempted.
+     * A very low count means a hardened or headless browser, which is itself
+     * worth forwarding.
+     */
+    coverage: {
+        present: number;
+        total: number;
+    };
+    /** The raw components, for debugging. Never send these anywhere. */
+    components: Record<string, string | null>;
+}
+/**
+ * Compute this browser's device fingerprint.
+ *
+ * Async because canvas and WebGL probing are, and because SubtleCrypto is.
+ * Call it once per page and reuse the result; it does not change within a
+ * session.
+ *
+ * Send the `fingerprint` to YOUR backend, which forwards it as
+ * `device_fingerprint`. It is the single highest-value optional field on a
+ * registration: one device across many signups is the strongest farm signal
+ * that exists, and it is invisible to Vectoral without it.
+ */
+declare function deviceFingerprint(opts: DeviceFingerprintOptions): Promise<DeviceFingerprint>;
+
+interface AutomationResult {
+    /** Noisy-OR combination of the weights that fired, in [0,1]. */
+    score: number;
+    /** `score >= threshold`. */
+    automated: boolean;
+    /** Names of the tells that fired, strongest first. */
+    reasons: string[];
+    /** Every tell that was evaluated, whether it fired or not. */
+    signals: Record<string, boolean>;
+    /**
+     * The environment-inconsistency subscore in [0,1] — the part of the evidence
+     * that comes from the browser contradicting itself rather than from an
+     * injected global. Send this as `client.fingerprint_anomaly`.
+     */
+    fingerprintAnomaly: number;
+}
+interface DetectAutomationOptions {
+    /** Decision point for `automated`. Default 0.6. */
+    threshold?: number;
+}
+/**
+ * Evaluate every automation tell against the current browser. Synchronous and
+ * cheap — safe to call on every protected action.
+ */
+declare function detectAutomation(opts?: DetectAutomationOptions): AutomationResult;
+
+interface FormFieldTelemetry {
+    pasted: boolean;
+    keystrokes: number;
+    corrections: number;
+    focus_ms: number;
+}
+interface FormTelemetrySnapshot {
+    load_to_submit_ms: number;
+    fields: Record<string, FormFieldTelemetry>;
+}
+interface FormTelemetryOptions {
+    /** Clock, in ms since page load. Defaults to `performance.now()`. */
+    now?: () => number;
+    /**
+     * Field names to report. When omitted, every field that received an event is
+     * reported. Never include a field whose NAME would reveal something you would
+     * not log — only names are sent, never values.
+     */
+    fields?: string[];
+}
+/**
+ * Accumulates fill behaviour for one form. Transport-free and DOM-free so it
+ * can be driven directly — `trackForm()` is the thin DOM wiring over it.
+ */
+declare class FormTelemetry {
+    private readonly fields;
+    private readonly now;
+    private readonly allowed;
+    constructor(opts?: FormTelemetryOptions);
+    private state;
+    focus(field: string): void;
+    blur(field: string): void;
+    keystroke(field: string, key: string): void;
+    paste(field: string): void;
+    /**
+     * Current telemetry. Call at submit. Fields still focused have their
+     * in-progress focus time included without ending the focus, so calling this
+     * twice is safe.
+     */
+    snapshot(): FormTelemetrySnapshot;
+}
+interface ListenerTarget {
+    addEventListener(type: string, listener: (e: never) => void, options?: {
+        capture?: boolean;
+        passive?: boolean;
+    }): void;
+    removeEventListener(type: string, listener: (e: never) => void, options?: unknown): void;
+}
+interface FormTracker {
+    /** Telemetry so far. Call at submit and send it as the `form` block. */
+    snapshot(): FormTelemetrySnapshot;
+    /** Detach listeners. Safe to call twice. */
+    stop(): void;
+}
+/**
+ * Attach fill tracking to a form.
+ *
+ * Only field NAMES and the counts above are recorded — never values. Listeners
+ * are passive and capturing, so they never block typing.
+ *
+ * Buttons are not fields: submit, reset, plain and image buttons are skipped, so
+ * they never appear in `fields`. For tighter control over what is reported, pass
+ * an explicit `fields` allowlist.
+ *
+ * ```js
+ * const tracker = trackForm(document.querySelector("#signup"));
+ * // at submit:
+ * body.form = tracker.snapshot();
+ * ```
+ */
+declare function trackForm(form: ListenerTarget, opts?: FormTelemetryOptions): FormTracker;
+
+interface SignupSignalsOptions {
+    /** Your publishable site key (`pk_live_…`). */
+    siteKey: string;
+    /** A tracker from `trackForm()`, if you wired one up. */
+    form?: FormTracker;
+    /** Threshold for `automation.automated`. Does not affect the score. */
+    automationThreshold?: number;
+}
+/**
+ * Exactly the shape `registrations.score()` accepts for these fields — post it
+ * to your own endpoint and spread it into the request there.
+ */
+interface SignupSignals {
+    device_fingerprint: string;
+    client: {
+        /** Present only when the browser actually reported `navigator.webdriver`. */
+        webdriver?: boolean;
+        fingerprint_anomaly: number;
+        load_to_submit_ms?: number;
+        timezone?: string;
+    };
+    form?: FormTelemetrySnapshot;
+    /** Diagnostics for your own logging. Not part of the wire contract. */
+    diagnostics: {
+        automation_score: number;
+        automation_reasons: string[];
+        fingerprint_strong: boolean;
+        fingerprint_coverage: {
+            present: number;
+            total: number;
+        };
+    };
+}
+/**
+ * Collect every signup signal available in the browser.
+ *
+ * **Post this to your own backend, not to Vectoral.** The API key is a secret
+ * and the IP must be read server-side. Your backend should also sanity-check
+ * what arrives — clamp `fingerprint_anomaly` to [0,1] and ignore absent fields
+ * — rather than trusting the client blindly.
+ *
+ * ```js
+ * const tracker = trackForm(formEl);
+ * // at submit:
+ * const signals = await signupSignals({ siteKey: "pk_live_…", form: tracker });
+ * await fetch("/api/signup", { method: "POST", body: JSON.stringify({ email, signals }) });
+ * ```
+ */
+declare function signupSignals(opts: SignupSignalsOptions): Promise<SignupSignals>;
+
+export { type AutomationResult, type DetectAutomationOptions, type DeviceFingerprint, type DeviceFingerprintOptions, type FormFieldTelemetry, FormTelemetry, type FormTelemetryOptions, type FormTelemetrySnapshot, type FormTracker, type SignupSignals, type SignupSignalsOptions, detectAutomation, deviceFingerprint, signupSignals, trackForm };

package/dist/index.d.ts

@@ -0,0 +1,189 @@
+interface DeviceFingerprintOptions {
+    /** Your publishable site key (`pk_live_…`). Scopes the value to your tenant. */
+    siteKey: string;
+}
+interface DeviceFingerprint {
+    /** `fp_` + 32 hex chars. Send as `device_fingerprint`. */
+    fingerprint: string;
+    /**
+     * False when SubtleCrypto was unavailable (an insecure context) and a
+     * non-cryptographic fallback hash was used. The value is still stable and
+     * still comparable — it is just cheaper to reverse, so do not treat it as a
+     * privacy boundary.
+     */
+    strong: boolean;
+    /**
+     * How many of the components actually resolved, out of the total attempted.
+     * A very low count means a hardened or headless browser, which is itself
+     * worth forwarding.
+     */
+    coverage: {
+        present: number;
+        total: number;
+    };
+    /** The raw components, for debugging. Never send these anywhere. */
+    components: Record<string, string | null>;
+}
+/**
+ * Compute this browser's device fingerprint.
+ *
+ * Async because canvas and WebGL probing are, and because SubtleCrypto is.
+ * Call it once per page and reuse the result; it does not change within a
+ * session.
+ *
+ * Send the `fingerprint` to YOUR backend, which forwards it as
+ * `device_fingerprint`. It is the single highest-value optional field on a
+ * registration: one device across many signups is the strongest farm signal
+ * that exists, and it is invisible to Vectoral without it.
+ */
+declare function deviceFingerprint(opts: DeviceFingerprintOptions): Promise<DeviceFingerprint>;
+
+interface AutomationResult {
+    /** Noisy-OR combination of the weights that fired, in [0,1]. */
+    score: number;
+    /** `score >= threshold`. */
+    automated: boolean;
+    /** Names of the tells that fired, strongest first. */
+    reasons: string[];
+    /** Every tell that was evaluated, whether it fired or not. */
+    signals: Record<string, boolean>;
+    /**
+     * The environment-inconsistency subscore in [0,1] — the part of the evidence
+     * that comes from the browser contradicting itself rather than from an
+     * injected global. Send this as `client.fingerprint_anomaly`.
+     */
+    fingerprintAnomaly: number;
+}
+interface DetectAutomationOptions {
+    /** Decision point for `automated`. Default 0.6. */
+    threshold?: number;
+}
+/**
+ * Evaluate every automation tell against the current browser. Synchronous and
+ * cheap — safe to call on every protected action.
+ */
+declare function detectAutomation(opts?: DetectAutomationOptions): AutomationResult;
+
+interface FormFieldTelemetry {
+    pasted: boolean;
+    keystrokes: number;
+    corrections: number;
+    focus_ms: number;
+}
+interface FormTelemetrySnapshot {
+    load_to_submit_ms: number;
+    fields: Record<string, FormFieldTelemetry>;
+}
+interface FormTelemetryOptions {
+    /** Clock, in ms since page load. Defaults to `performance.now()`. */
+    now?: () => number;
+    /**
+     * Field names to report. When omitted, every field that received an event is
+     * reported. Never include a field whose NAME would reveal something you would
+     * not log — only names are sent, never values.
+     */
+    fields?: string[];
+}
+/**
+ * Accumulates fill behaviour for one form. Transport-free and DOM-free so it
+ * can be driven directly — `trackForm()` is the thin DOM wiring over it.
+ */
+declare class FormTelemetry {
+    private readonly fields;
+    private readonly now;
+    private readonly allowed;
+    constructor(opts?: FormTelemetryOptions);
+    private state;
+    focus(field: string): void;
+    blur(field: string): void;
+    keystroke(field: string, key: string): void;
+    paste(field: string): void;
+    /**
+     * Current telemetry. Call at submit. Fields still focused have their
+     * in-progress focus time included without ending the focus, so calling this
+     * twice is safe.
+     */
+    snapshot(): FormTelemetrySnapshot;
+}
+interface ListenerTarget {
+    addEventListener(type: string, listener: (e: never) => void, options?: {
+        capture?: boolean;
+        passive?: boolean;
+    }): void;
+    removeEventListener(type: string, listener: (e: never) => void, options?: unknown): void;
+}
+interface FormTracker {
+    /** Telemetry so far. Call at submit and send it as the `form` block. */
+    snapshot(): FormTelemetrySnapshot;
+    /** Detach listeners. Safe to call twice. */
+    stop(): void;
+}
+/**
+ * Attach fill tracking to a form.
+ *
+ * Only field NAMES and the counts above are recorded — never values. Listeners
+ * are passive and capturing, so they never block typing.
+ *
+ * Buttons are not fields: submit, reset, plain and image buttons are skipped, so
+ * they never appear in `fields`. For tighter control over what is reported, pass
+ * an explicit `fields` allowlist.
+ *
+ * ```js
+ * const tracker = trackForm(document.querySelector("#signup"));
+ * // at submit:
+ * body.form = tracker.snapshot();
+ * ```
+ */
+declare function trackForm(form: ListenerTarget, opts?: FormTelemetryOptions): FormTracker;
+
+interface SignupSignalsOptions {
+    /** Your publishable site key (`pk_live_…`). */
+    siteKey: string;
+    /** A tracker from `trackForm()`, if you wired one up. */
+    form?: FormTracker;
+    /** Threshold for `automation.automated`. Does not affect the score. */
+    automationThreshold?: number;
+}
+/**
+ * Exactly the shape `registrations.score()` accepts for these fields — post it
+ * to your own endpoint and spread it into the request there.
+ */
+interface SignupSignals {
+    device_fingerprint: string;
+    client: {
+        /** Present only when the browser actually reported `navigator.webdriver`. */
+        webdriver?: boolean;
+        fingerprint_anomaly: number;
+        load_to_submit_ms?: number;
+        timezone?: string;
+    };
+    form?: FormTelemetrySnapshot;
+    /** Diagnostics for your own logging. Not part of the wire contract. */
+    diagnostics: {
+        automation_score: number;
+        automation_reasons: string[];
+        fingerprint_strong: boolean;
+        fingerprint_coverage: {
+            present: number;
+            total: number;
+        };
+    };
+}
+/**
+ * Collect every signup signal available in the browser.
+ *
+ * **Post this to your own backend, not to Vectoral.** The API key is a secret
+ * and the IP must be read server-side. Your backend should also sanity-check
+ * what arrives — clamp `fingerprint_anomaly` to [0,1] and ignore absent fields
+ * — rather than trusting the client blindly.
+ *
+ * ```js
+ * const tracker = trackForm(formEl);
+ * // at submit:
+ * const signals = await signupSignals({ siteKey: "pk_live_…", form: tracker });
+ * await fetch("/api/signup", { method: "POST", body: JSON.stringify({ email, signals }) });
+ * ```
+ */
+declare function signupSignals(opts: SignupSignalsOptions): Promise<SignupSignals>;
+
+export { type AutomationResult, type DetectAutomationOptions, type DeviceFingerprint, type DeviceFingerprintOptions, type FormFieldTelemetry, FormTelemetry, type FormTelemetryOptions, type FormTelemetrySnapshot, type FormTracker, type SignupSignals, type SignupSignalsOptions, detectAutomation, deviceFingerprint, signupSignals, trackForm };