apira-guard 0.1.0

package/src/engine.ts

@@ -0,0 +1,193 @@
+/**
+ * O(1) behaviour detection engine — shared by all surfaces.
+ *
+ * All counters use fixed-window arithmetic so every operation is constant time:
+ * no timestamp arrays, no filter/scan, no history queries.
+ */
+
+import type { RiskReason } from "./risk.js";
+
+// ─── public API ──────────────────────────────────────────────────────────────
+
+export type TrackEvent = {
+  now?: number;
+  /**
+   * Milliseconds since the watcher was attached (submit surface).
+   * Presence of this field marks the event as a submit-surface event:
+   *   - enables fast_action and retry signals
+   *   - disables enumeration / endpoint_concentration / flow_anomaly
+   */
+  elapsed?: number;
+  /**
+   * Request URL (access surface).
+   * Presence of this field marks the event as an access-surface event:
+   *   - enables enumeration, endpoint_concentration, flow_anomaly
+   *   - disables retry
+   */
+  url?: string;
+  /** HTTP method — required for flow_anomaly (access surface only). */
+  method?: string;
+};
+
+export type EngineOptions = {
+  /** Requests per velocityWindowMs before "velocity" fires. Default: 60. */
+  velocityThreshold?: number;
+  /** Sliding window for velocity. Default: 60 000 ms. */
+  velocityWindowMs?: number;
+  /** Requests per 10 s before "spike" fires. Default: 20. */
+  spikeThreshold?: number;
+  /** Requests to the same normalised endpoint before "endpoint_concentration" fires. Default: 20. */
+  concThreshold?: number;
+  /** Minimum error rate (0–1) before "probing" fires (needs ≥ 5 requests). Default: 0.5. */
+  errorRateThreshold?: number;
+  /** Elapsed ms threshold for "fast_action". Default: 3 000. */
+  fastActionMs?: number;
+};
+
+export type Engine = {
+  track(key: string, event: TrackEvent): RiskReason[];
+  /** Call after a 4xx / 5xx response to feed the probing detector. */
+  reportError(key: string): void;
+};
+
+// ─── internal state per tracked key ─────────────────────────────────────────
+
+type State = {
+  // Velocity — O(1) fixed window
+  winStart: number;
+  winCount: number;
+  // Spike — O(1) fixed 10 s window
+  spikeStart: number;
+  spikeCount: number;
+  // Total calls — never reset (retry on submit surface, flow-anomaly guard on access)
+  totalCount: number;
+  // Enumeration — O(1) sequential-run tracker
+  lastPathNum: number | null;
+  seqRun: number;
+  // Endpoint concentration — O(1) per-endpoint counter inside velocity window
+  epWinStart: number;
+  epCounts: Map<string, number>;
+  // Probing — O(1) error-rate tracker
+  reqCount: number;   // increments on track(); never reset
+  errCount: number;   // increments on reportError(); never reset
+  // Flow anomaly — has this key ever made a GET request?
+  hasGet: boolean;
+};
+
+const NUMERIC_ID_RE = /\/(\d+)(?:\/|$|\?)/u;
+
+function makeState(now: number): State {
+  return {
+    winStart: now, winCount: 0,
+    spikeStart: now, spikeCount: 0,
+    totalCount: 0,
+    lastPathNum: null, seqRun: 0,
+    epWinStart: now, epCounts: new Map(),
+    reqCount: 0, errCount: 0,
+    hasGet: false
+  };
+}
+
+// ─── factory ─────────────────────────────────────────────────────────────────
+
+export function createEngine(opts: EngineOptions = {}): Engine {
+  const velocityThreshold = opts.velocityThreshold ?? 60;
+  const velocityWindowMs = opts.velocityWindowMs ?? 60_000;
+  const spikeThreshold = opts.spikeThreshold ?? 20;
+  const concThreshold = opts.concThreshold ?? 20;
+  const errorRateThreshold = opts.errorRateThreshold ?? 0.5;
+  const fastActionMs = opts.fastActionMs ?? 3_000;
+
+  const store = new Map<string, State>();
+
+  function state(key: string, now: number): State {
+    let s = store.get(key);
+    if (!s) { s = makeState(now); store.set(key, s); }
+    return s;
+  }
+
+  return {
+    track(key, event) {
+      const now = event.now ?? Date.now();
+      const s = state(key, now);
+      const reasons: RiskReason[] = [];
+
+      // ── Velocity (O(1) fixed window) ───────────────────────────────────────
+      if (now - s.winStart >= velocityWindowMs) { s.winStart = now; s.winCount = 0; }
+      s.winCount++;
+      if (s.winCount > velocityThreshold) reasons.push("velocity");
+
+      // ── Spike (O(1) fixed 10 s window) ────────────────────────────────────
+      if (now - s.spikeStart >= 10_000) { s.spikeStart = now; s.spikeCount = 0; }
+      s.spikeCount++;
+      if (s.spikeCount > spikeThreshold) reasons.push("spike");
+
+      s.totalCount++;
+
+      // ── Fast action (submit surface) ───────────────────────────────────────
+      if (event.elapsed !== undefined && event.elapsed < fastActionMs) {
+        reasons.push("fast_action");
+      }
+
+      if (event.url !== undefined) {
+        // ── Access-surface signals ─────────────────────────────────────────
+
+        // Enumeration (O(1) sequential-run counter)
+        const m = NUMERIC_ID_RE.exec(event.url);
+        if (m) {
+          const num = parseInt(m[1], 10);
+          s.seqRun = (s.lastPathNum !== null && Math.abs(num - s.lastPathNum) <= 5)
+            ? s.seqRun + 1
+            : 1;
+          s.lastPathNum = num;
+        } else {
+          s.lastPathNum = null;
+          s.seqRun = 0;
+        }
+        if (s.seqRun >= 3) reasons.push("enumeration");
+
+        // Endpoint concentration (O(1) per-endpoint window counter)
+        if (now - s.epWinStart >= velocityWindowMs) { s.epCounts.clear(); s.epWinStart = now; }
+        const ep = normalizeEndpoint(event.url);
+        const epCount = (s.epCounts.get(ep) ?? 0) + 1;
+        s.epCounts.set(ep, epCount);
+        if (epCount > concThreshold) reasons.push("endpoint_concentration");
+
+        // Flow anomaly (O(1) method tracker — POST/PUT/DELETE with no prior GET)
+        if (event.method) {
+          const method = event.method.toUpperCase();
+          if (method === "GET") {
+            s.hasGet = true;
+          } else if (!s.hasGet && s.totalCount > 2) {
+            reasons.push("flow_anomaly");
+          }
+        }
+
+        // Probing (O(1) error rate — evaluated on next request after reportError calls)
+        s.reqCount++;
+        if (s.reqCount >= 5 && s.errCount / s.reqCount > errorRateThreshold) {
+          reasons.push("probing");
+        }
+      } else {
+        // ── Submit-surface signals ─────────────────────────────────────────
+
+        // Retry (second or later submit to the same form)
+        if (s.totalCount > 1) reasons.push("retry");
+      }
+
+      return reasons;
+    },
+
+    reportError(key) {
+      const s = store.get(key);
+      if (s) { s.errCount++; }
+    }
+  };
+}
+
+// ─── helpers ─────────────────────────────────────────────────────────────────
+
+function normalizeEndpoint(url: string): string {
+  // Strip query string, collapse numeric path segments to :id
+  return url.split("?")[0].replace(/\/\d+/gu, "/:id");
+}

package/src/index.ts

@@ -0,0 +1,507 @@
+import { createEngine } from "./engine.js";
+import { buildRiskResult, type RiskReason, type RiskResult } from "./risk.js";
+
+export type { RiskReason, RiskLevel, RiskResult } from "./risk.js";
+
+type BlockReason =
+  | "invalid_email_format"
+  | "disposable_email"
+  | "invalid_phone_format"
+  | "phone_too_short"
+  | "phone_too_long"
+  | "repeated_digit_phone"
+  | "sequential_phone"
+  | "reserved_test_phone";
+
+type SignupInput = {
+  email?: string | null;
+  phone?: string | null;
+};
+
+export type ConversionFormIntent =
+  | "signup"
+  | "checkout"
+  | "demo_request"
+  | "waitlist"
+  | "lead_capture"
+  | "contact_sales"
+  | "invite";
+
+export type WatchFormsEvent = {
+  intent: ConversionFormIntent;
+  timestamp: string;
+  metadata: Record<string, unknown>;
+};
+
+export type WatchFormsOptions = {
+  /** Root node to search. Defaults to document. */
+  root?: ParentNode;
+  /** Revenue-critical flow being watched. Defaults to signup. */
+  intent?: ConversionFormIntent;
+  /** Optional metadata copied into the submit event. */
+  metadata?: Record<string, unknown>;
+  /** Called when a watched form submits. */
+  onSubmit?: (event: WatchFormsEvent) => void;
+};
+
+export type WatchFormsController = {
+  /** Number of forms watched by this call. */
+  watchedForms: number;
+  /** Remove submit listeners added by this call. */
+  destroy: () => void;
+};
+
+export type ProtectFormsController = {
+  /** Number of forms protected by this call. */
+  protectedForms: number;
+  /** Remove submit listeners added by this call. */
+  destroy: () => void;
+};
+
+export type WatchActionsOptions = {
+  /** Action being watched — e.g. "checkout", "reset", "update". */
+  action: string;
+  /** Root node to search. Defaults to document. */
+  root?: ParentNode;
+  /** Called on each action with the risk result. */
+  onAction?: (event: WatchActionsEvent) => void;
+};
+
+export type WatchActionsEvent = {
+  action: string;
+  risk: RiskResult;
+  timestamp: string;
+};
+
+export type WatchActionsController = {
+  /** Number of forms watched by this call. */
+  watchedForms: number;
+  /** Remove submit listeners added by this call. */
+  destroy: () => void;
+};
+
+const DISPOSABLE_EMAIL_DOMAINS = new Set([
+  "10minutemail.com",
+  "anonaddy.com",
+  "dispostable.com",
+  "guerrillamail.com",
+  "mailinator.com",
+  "maildrop.cc",
+  "sharklasers.com",
+  "temp-mail.org",
+  "tempmail.com",
+  "throwawaymail.com",
+  "yopmail.com"
+]);
+
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]{2,}$/u;
+const SEQUENTIAL_PHONE_PATTERN = /(?:012345|123456|234567|345678|456789|987654|876543|765432|654321|543210)/u;
+const EMAIL_FIELD_SELECTOR = [
+  "input[type='email']",
+  "input[name*='email' i]",
+  "input[id*='email' i]",
+  "input[autocomplete='email' i]"
+].join(", ");
+const PHONE_FIELD_SELECTOR = [
+  "input[type='tel']",
+  "input[name*='phone' i]",
+  "input[id*='phone' i]",
+  "input[name*='mobile' i]",
+  "input[id*='mobile' i]",
+  "input[name*='telephone' i]",
+  "input[id*='telephone' i]",
+  "input[name*='tel' i]",
+  "input[id*='tel' i]",
+  "input[autocomplete='tel' i]"
+].join(", ");
+const PHONE_FIELD_WORDS = ["phone", "mobile", "telephone", "tel"];
+const PHONE_FIELD_PHRASES = ["contact number"];
+const FORM_LISTENER_OPTIONS = { capture: true };
+const SIGNUP_GUARD_FORM_ATTRIBUTE = "data-signup-guard-form";
+const SIGNUP_GUARD_IGNORE_ATTRIBUTE = "data-signup-guard-ignore";
+
+const protectedFormListeners = new WeakMap<HTMLFormElement, EventListener>();
+const watchedFormListeners = new WeakMap<HTMLFormElement, EventListener>();
+const watchedActionListeners = new WeakMap<HTMLFormElement, EventListener>();
+
+export function watchSignups(options: Omit<WatchFormsOptions, "intent"> = {}): WatchFormsController {
+  return watchForms({ ...options, intent: "signup" });
+}
+
+export function watchForms(options: WatchFormsOptions = {}): WatchFormsController {
+  const root = options.root ?? document;
+  const intent = options.intent ?? "signup";
+  const attachedForms: HTMLFormElement[] = [];
+
+  for (const form of Array.from(root.querySelectorAll<HTMLFormElement>("form"))) {
+    if (watchedFormListeners.has(form) || !shouldWatchForm(form, intent)) {
+      continue;
+    }
+
+    const onSubmit = () => {
+      const detail = {
+        intent,
+        timestamp: new Date().toISOString(),
+        metadata: options.metadata ?? {}
+      };
+
+      options.onSubmit?.(detail);
+      form.dispatchEvent(new CustomEvent("signupguard:submit", { detail }));
+    };
+
+    form.addEventListener("submit", onSubmit, FORM_LISTENER_OPTIONS);
+    watchedFormListeners.set(form, onSubmit);
+    attachedForms.push(form);
+  }
+
+  return {
+    watchedForms: attachedForms.length,
+    destroy: () => {
+      for (const form of attachedForms) {
+        const listener = watchedFormListeners.get(form);
+
+        if (listener) {
+          form.removeEventListener("submit", listener, FORM_LISTENER_OPTIONS);
+          watchedFormListeners.delete(form);
+        }
+      }
+    }
+  };
+}
+
+export function watchActions(options: WatchActionsOptions): WatchActionsController {
+  const root = options.root ?? document;
+  const { action } = options;
+  const attachTime = Date.now();
+  const attachedForms: HTMLFormElement[] = [];
+
+  // One engine per watchActions() call — isolated state, O(1) counters per form key.
+  const engine = createEngine({ velocityThreshold: 3, velocityWindowMs: 60_000 });
+  // Stable string key per form so the engine can track per-form state.
+  const formKeys = new Map<HTMLFormElement, string>();
+  let nextKey = 0;
+
+  for (const form of Array.from(root.querySelectorAll<HTMLFormElement>("form"))) {
+    if (watchedActionListeners.has(form) || !shouldWatchActionForm(form, action)) {
+      continue;
+    }
+
+    const key = String(nextKey++);
+    formKeys.set(form, key);
+
+    const onSubmit = () => {
+      const now = Date.now();
+      const reasons = engine.track(key, { now, elapsed: now - attachTime });
+      const risk = buildRiskResult(reasons);
+      injectRiskField(form, risk);
+
+      const detail: WatchActionsEvent = { action, risk, timestamp: new Date().toISOString() };
+      options.onAction?.(detail);
+      form.dispatchEvent(new CustomEvent("signupguard:action", { detail }));
+    };
+
+    form.addEventListener("submit", onSubmit, FORM_LISTENER_OPTIONS);
+    watchedActionListeners.set(form, onSubmit);
+    attachedForms.push(form);
+  }
+
+  return {
+    watchedForms: attachedForms.length,
+    destroy: () => {
+      for (const form of attachedForms) {
+        const listener = watchedActionListeners.get(form);
+
+        if (listener) {
+          form.removeEventListener("submit", listener, FORM_LISTENER_OPTIONS);
+          watchedActionListeners.delete(form);
+        }
+      }
+    }
+  };
+}
+
+export function protectForms(root: ParentNode = document): ProtectFormsController {
+  const forms = Array.from(root.querySelectorAll<HTMLFormElement>("form"));
+  const attachedForms: HTMLFormElement[] = [];
+
+  for (const form of forms) {
+    if (protectedFormListeners.has(form) || !shouldProtectForm(form)) {
+      continue;
+    }
+
+    const onSubmit = (event: Event) => {
+      const fields = detectSignupFields(form);
+
+      if (!fields) {
+        return;
+      }
+
+      clearSignupGuardMessage(fields.email);
+      clearSignupGuardMessage(fields.phone);
+
+      const blocked = getBlockedReason({
+        email: fields.email?.value ?? null,
+        phone: fields.phone?.value ?? null
+      });
+
+      if (!blocked) {
+        return;
+      }
+
+      event.preventDefault();
+      event.stopImmediatePropagation();
+      showSignupGuardMessage(form, fields, blocked);
+    };
+
+    form.addEventListener("submit", onSubmit, FORM_LISTENER_OPTIONS);
+    protectedFormListeners.set(form, onSubmit);
+    attachedForms.push(form);
+  }
+
+  return {
+    protectedForms: attachedForms.length,
+    destroy: () => {
+      for (const form of attachedForms) {
+        const listener = protectedFormListeners.get(form);
+
+        if (listener) {
+          form.removeEventListener("submit", listener, FORM_LISTENER_OPTIONS);
+          protectedFormListeners.delete(form);
+        }
+      }
+    }
+  };
+}
+
+
+function shouldProtectForm(form: HTMLFormElement): boolean {
+  return !hasFormAttribute(form, SIGNUP_GUARD_IGNORE_ATTRIBUTE) &&
+    (hasFormAttribute(form, SIGNUP_GUARD_FORM_ATTRIBUTE) || Boolean(detectSignupFields(form)));
+}
+
+function shouldWatchForm(form: HTMLFormElement, intent: ConversionFormIntent): boolean {
+  if (hasFormAttribute(form, SIGNUP_GUARD_IGNORE_ATTRIBUTE)) {
+    return false;
+  }
+
+  const explicitIntent = getFormAttribute(form, SIGNUP_GUARD_FORM_ATTRIBUTE);
+
+  if (explicitIntent !== null) {
+    return explicitIntent === "" || explicitIntent === "true" || explicitIntent === intent;
+  }
+
+  if (intent === "signup") {
+    return Boolean(detectSignupFields(form));
+  }
+
+  return formText(form).includes(intent.replace("_", " ")) ||
+    intentKeywords(intent).some((keyword) => formText(form).includes(keyword));
+}
+
+function shouldWatchActionForm(form: HTMLFormElement, action: string): boolean {
+  if (hasFormAttribute(form, SIGNUP_GUARD_IGNORE_ATTRIBUTE)) {
+    return false;
+  }
+
+  const explicitIntent = getFormAttribute(form, SIGNUP_GUARD_FORM_ATTRIBUTE);
+
+  if (explicitIntent !== null) {
+    return explicitIntent === "" || explicitIntent === "true" || explicitIntent === action;
+  }
+
+  const normalized = action.replace(/_/g, " ").toLowerCase();
+  return formText(form).includes(normalized) ||
+    intentKeywords(action as ConversionFormIntent).some((kw) => formText(form).includes(kw));
+}
+
+function hasFormAttribute(form: HTMLFormElement, name: string): boolean {
+  return typeof form.hasAttribute === "function" && form.hasAttribute(name);
+}
+
+function getFormAttribute(form: HTMLFormElement, name: string): string | null {
+  if (!hasFormAttribute(form, name) || typeof form.getAttribute !== "function") {
+    return null;
+  }
+
+  return form.getAttribute(name);
+}
+
+function formText(form: HTMLFormElement): string {
+  return [
+    form.getAttribute?.("id"),
+    form.getAttribute?.("name"),
+    form.getAttribute?.("aria-label"),
+    form.getAttribute?.(SIGNUP_GUARD_FORM_ATTRIBUTE),
+    form.textContent
+  ]
+    .filter(Boolean)
+    .join(" ")
+    .toLowerCase();
+}
+
+function intentKeywords(intent: ConversionFormIntent): string[] {
+  if (intent === "checkout") return ["checkout", "payment", "billing", "card"];
+  if (intent === "demo_request") return ["demo", "book a demo", "request demo"];
+  if (intent === "waitlist") return ["waitlist", "join waitlist"];
+  if (intent === "lead_capture") return ["lead", "contact", "work email"];
+  if (intent === "contact_sales") return ["contact sales", "sales"];
+  if (intent === "invite") return ["invite", "invitation"];
+
+  return ["signup", "sign up", "create account"];
+}
+
+function injectRiskField(form: HTMLFormElement, risk: RiskResult): void {
+  const doc = form.ownerDocument;
+  if (!doc) return;
+
+  const FIELD_NAME = "signupGuardRisk";
+  let field = form.querySelector<HTMLInputElement>(`input[name="${FIELD_NAME}"]`);
+
+  if (!field) {
+    field = doc.createElement("input");
+    field.type = "hidden";
+    field.name = FIELD_NAME;
+    form.appendChild(field);
+  }
+
+  field.value = JSON.stringify(risk);
+}
+
+type DetectedSignupFields = {
+  email?: HTMLInputElement;
+  phone?: HTMLInputElement;
+};
+
+function detectSignupFields(form: HTMLFormElement): DetectedSignupFields | null {
+  const email = findEmailField(form);
+  const phone = findPhoneField(form);
+
+  if (!email && !phone) {
+    return null;
+  }
+
+  return { email, phone };
+}
+
+function findEmailField(form: HTMLFormElement): HTMLInputElement | undefined {
+  return form.querySelector<HTMLInputElement>(EMAIL_FIELD_SELECTOR) ?? undefined;
+}
+
+function findPhoneField(form: HTMLFormElement): HTMLInputElement | undefined {
+  const directMatch = form.querySelector<HTMLInputElement>(PHONE_FIELD_SELECTOR);
+
+  if (directMatch) {
+    return directMatch;
+  }
+
+  return Array.from(form.querySelectorAll<HTMLInputElement>("input")).find((field) => isPhoneField(field));
+}
+
+function isPhoneField(field: HTMLInputElement): boolean {
+  const text = fieldText(field);
+
+  return PHONE_FIELD_WORDS.some((word) => text.includes(word)) ||
+    PHONE_FIELD_PHRASES.some((phrase) => text.includes(phrase));
+}
+
+function fieldText(field: HTMLInputElement): string {
+  const labels = Array.from(field.labels ?? [], (label) => label.textContent ?? "");
+
+  return [
+    field.name,
+    field.id,
+    field.type,
+    field.autocomplete,
+    field.placeholder,
+    field.getAttribute("aria-label"),
+    ...labels
+  ]
+    .filter(Boolean)
+    .join(" ")
+    .toLowerCase();
+}
+
+function getBlockedReason(input: SignupInput): BlockReason | null {
+  const email = String(input.email ?? "").trim().toLowerCase();
+  const phone = String(input.phone ?? "").trim();
+
+  if (email) {
+    if (!EMAIL_PATTERN.test(email)) {
+      return "invalid_email_format";
+    }
+
+    if (isDisposableEmail(email)) {
+      return "disposable_email";
+    }
+  }
+
+  if (!phone) {
+    return null;
+  }
+
+  const digits = phone.replace(/\D/gu, "");
+  const phoneFormatReason = getPhoneFormatReason(phone, digits);
+
+  if (phoneFormatReason) {
+    return phoneFormatReason;
+  }
+
+  return getFakePhoneReason(digits);
+}
+
+function isDisposableEmail(email: string): boolean {
+  const domain = String(email).trim().toLowerCase().split("@").pop();
+
+  return Boolean(domain && DISPOSABLE_EMAIL_DOMAINS.has(domain));
+}
+
+function getPhoneFormatReason(phone: string, digits: string): BlockReason | null {
+  const trimmed = phone.trim();
+
+  if (!/^[+()\-.\s\d]+$/u.test(trimmed)) return "invalid_phone_format";
+  if (digits.length < 7) return "phone_too_short";
+  if (digits.length > 15) return "phone_too_long";
+
+  return null;
+}
+
+function getFakePhoneReason(digits: string): BlockReason | null {
+  if (/^(\d)\1+$/u.test(digits)) return "repeated_digit_phone";
+  if (SEQUENTIAL_PHONE_PATTERN.test(digits)) return "sequential_phone";
+  if (/^55501\d{2}$/u.test(digits.slice(-7)) || /^555010\d$/u.test(digits.slice(-7))) return "reserved_test_phone";
+
+  return null;
+}
+
+function showSignupGuardMessage(
+  form: HTMLFormElement,
+  fields: DetectedSignupFields,
+  reason: BlockReason
+): void {
+  const field = reason.includes("email") ? fields.email : fields.phone;
+  const message = messageForReason(reason);
+
+  if (field && "setCustomValidity" in field && "reportValidity" in field) {
+    field.setCustomValidity(message);
+    field.reportValidity();
+    field.addEventListener("input", () => clearSignupGuardMessage(field), { once: true });
+  }
+
+  form.dispatchEvent(new CustomEvent("signupguard:block", { detail: { reason, message } }));
+}
+
+function clearSignupGuardMessage(field?: HTMLInputElement): void {
+  field?.setCustomValidity("");
+}
+
+function messageForReason(reason: BlockReason): string {
+  if (reason === "invalid_email_format") {
+    return "Please enter a valid email address.";
+  }
+
+  if (reason === "disposable_email") {
+    return "This email provider is not supported.";
+  }
+
+  return "Please enter a valid phone number.";
+}