apira-guard 0.1.0

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAoC,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAE9E,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAiBnE,MAAM,MAAM,oBAAoB,GAC5B,QAAQ,GACR,UAAU,GACV,cAAc,GACd,UAAU,GACV,cAAc,GACd,eAAe,GACf,QAAQ,CAAC;AAEb,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,iDAAiD;IACjD,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,CAAC;CAC7C,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,4CAA4C;IAC5C,YAAY,EAAE,MAAM,CAAC;IACrB,kDAAkD;IAClD,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,8CAA8C;IAC9C,cAAc,EAAE,MAAM,CAAC;IACvB,kDAAkD;IAClD,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAC/C,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,UAAU,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,4CAA4C;IAC5C,YAAY,EAAE,MAAM,CAAC;IACrB,kDAAkD;IAClD,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AA8CF,wBAAgB,YAAY,CAAC,OAAO,GAAE,IAAI,CAAC,iBAAiB,EAAE,QAAQ,CAAM,GAAG,oBAAoB,CAElG;AAED,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,oBAAoB,CAuChF;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,sBAAsB,CAiDjF;AAED,wBAAgB,YAAY,CAAC,IAAI,GAAE,UAAqB,GAAG,sBAAsB,CAmDhF"}

package/dist/index.js

@@ -0,0 +1,348 @@
+import { createEngine } from "./engine.js";
+import { buildRiskResult } from "./risk.js";
+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();
+const watchedFormListeners = new WeakMap();
+const watchedActionListeners = new WeakMap();
+export function watchSignups(options = {}) {
+    return watchForms({ ...options, intent: "signup" });
+}
+export function watchForms(options = {}) {
+    const root = options.root ?? document;
+    const intent = options.intent ?? "signup";
+    const attachedForms = [];
+    for (const form of Array.from(root.querySelectorAll("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) {
+    const root = options.root ?? document;
+    const { action } = options;
+    const attachTime = Date.now();
+    const attachedForms = [];
+    // 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();
+    let nextKey = 0;
+    for (const form of Array.from(root.querySelectorAll("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 = { 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 = document) {
+    const forms = Array.from(root.querySelectorAll("form"));
+    const attachedForms = [];
+    for (const form of forms) {
+        if (protectedFormListeners.has(form) || !shouldProtectForm(form)) {
+            continue;
+        }
+        const onSubmit = (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) {
+    return !hasFormAttribute(form, SIGNUP_GUARD_IGNORE_ATTRIBUTE) &&
+        (hasFormAttribute(form, SIGNUP_GUARD_FORM_ATTRIBUTE) || Boolean(detectSignupFields(form)));
+}
+function shouldWatchForm(form, intent) {
+    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, action) {
+    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).some((kw) => formText(form).includes(kw));
+}
+function hasFormAttribute(form, name) {
+    return typeof form.hasAttribute === "function" && form.hasAttribute(name);
+}
+function getFormAttribute(form, name) {
+    if (!hasFormAttribute(form, name) || typeof form.getAttribute !== "function") {
+        return null;
+    }
+    return form.getAttribute(name);
+}
+function formText(form) {
+    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) {
+    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, risk) {
+    const doc = form.ownerDocument;
+    if (!doc)
+        return;
+    const FIELD_NAME = "signupGuardRisk";
+    let field = form.querySelector(`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);
+}
+function detectSignupFields(form) {
+    const email = findEmailField(form);
+    const phone = findPhoneField(form);
+    if (!email && !phone) {
+        return null;
+    }
+    return { email, phone };
+}
+function findEmailField(form) {
+    return form.querySelector(EMAIL_FIELD_SELECTOR) ?? undefined;
+}
+function findPhoneField(form) {
+    const directMatch = form.querySelector(PHONE_FIELD_SELECTOR);
+    if (directMatch) {
+        return directMatch;
+    }
+    return Array.from(form.querySelectorAll("input")).find((field) => isPhoneField(field));
+}
+function isPhoneField(field) {
+    const text = fieldText(field);
+    return PHONE_FIELD_WORDS.some((word) => text.includes(word)) ||
+        PHONE_FIELD_PHRASES.some((phrase) => text.includes(phrase));
+}
+function fieldText(field) {
+    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) {
+    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) {
+    const domain = String(email).trim().toLowerCase().split("@").pop();
+    return Boolean(domain && DISPOSABLE_EMAIL_DOMAINS.has(domain));
+}
+function getPhoneFormatReason(phone, digits) {
+    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) {
+    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, fields, reason) {
+    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) {
+    field?.setCustomValidity("");
+}
+function messageForReason(reason) {
+    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.";
+}

package/dist/risk.d.ts

@@ -0,0 +1,9 @@
+export type RiskReason = "velocity" | "spike" | "fast_action" | "retry" | "enumeration" | "endpoint_concentration" | "probing" | "flow_anomaly";
+export type RiskLevel = "low" | "medium" | "high";
+export type RiskResult = {
+    riskScore: number;
+    riskLevel: RiskLevel;
+    reasons: RiskReason[];
+};
+export declare function buildRiskResult(reasons: RiskReason[]): RiskResult;
+//# sourceMappingURL=risk.d.ts.map

package/dist/risk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"risk.d.ts","sourceRoot":"","sources":["../src/risk.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAClB,UAAU,GACV,OAAO,GACP,aAAa,GACb,OAAO,GACP,aAAa,GACb,wBAAwB,GACxB,SAAS,GACT,cAAc,CAAC;AAEnB,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AAElD,MAAM,MAAM,UAAU,GAAG;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,SAAS,CAAC;IACrB,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB,CAAC;AAcF,wBAAgB,eAAe,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,UAAU,CAKjE"}

package/dist/risk.js

@@ -0,0 +1,17 @@
+// Weights per spec: velocity +30, retry +25, fast_action +20
+const REASON_SCORES = {
+    velocity: 30,
+    spike: 40,
+    fast_action: 20,
+    retry: 25,
+    enumeration: 50,
+    endpoint_concentration: 35,
+    probing: 40,
+    flow_anomaly: 30
+};
+export function buildRiskResult(reasons) {
+    const unique = [...new Set(reasons)];
+    const riskScore = Math.min(100, unique.reduce((sum, r) => sum + REASON_SCORES[r], 0));
+    const riskLevel = riskScore >= 70 ? "high" : riskScore >= 40 ? "medium" : "low";
+    return { riskScore, riskLevel, reasons: unique };
+}

package/dist/server.d.ts

@@ -0,0 +1,37 @@
+import { type EngineOptions } from "./engine.js";
+export type { RiskReason, RiskLevel, RiskResult } from "./risk.js";
+type IncomingHeaders = Record<string, string | string[] | undefined>;
+/** Request shape — compatible with Express, Next.js, and plain Node IncomingMessage. */
+export type SignupGuardRequest = {
+    method?: string;
+    url?: string;
+    ip?: string;
+    headers?: IncomingHeaders;
+    signupGuardRisk?: import("./risk.js").RiskResult;
+    [key: string]: unknown;
+};
+export type WatchAccessOptions = EngineOptions & {
+    /** Max requests per velocityWindowMs before "velocity" fires. Default: 60. */
+    velocityThreshold?: number;
+    /** Max requests per 10 s before "spike" fires. Default: 20. */
+    spikeThreshold?: number;
+    /** Max requests to same normalised endpoint before "endpoint_concentration" fires. Default: 20. */
+    concThreshold?: number;
+};
+export type WatchAccessMiddleware = (req: SignupGuardRequest, res: unknown, next: () => void) => void;
+/**
+ * Express / Node middleware.
+ * Attaches req.signupGuardRisk = { riskScore, riskLevel, reasons } to every request.
+ *
+ * Detected signals (all O(1), in-memory, zero external calls):
+ *   velocity              — too many requests from this IP in the window
+ *   spike                 — burst of requests in 10 s
+ *   enumeration           — sequential numeric IDs in URL path
+ *   endpoint_concentration — same endpoint hit repeatedly (scraping)
+ *   probing               — high 4xx rate (directory / param probing)
+ *   flow_anomaly          — write request with no prior read (bot shortcut)
+ *
+ * Mount it narrowly: app.use("/api/checkout", watchAccess()) rather than globally.
+ */
+export declare function watchAccess(options?: WatchAccessOptions): WatchAccessMiddleware;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAG/D,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEnE,KAAK,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;AAErE,wFAAwF;AACxF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,WAAW,EAAE,UAAU,CAAC;IACjD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,aAAa,GAAG;IAC/C,8EAA8E;IAC9E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,+DAA+D;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mGAAmG;IACnG,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG,CAClC,GAAG,EAAE,kBAAkB,EACvB,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,MAAM,IAAI,KACb,IAAI,CAAC;AAEV;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,qBAAqB,CAuBnF"}

package/dist/server.js

@@ -0,0 +1,42 @@
+import { createEngine } from "./engine.js";
+import { buildRiskResult } from "./risk.js";
+/**
+ * Express / Node middleware.
+ * Attaches req.signupGuardRisk = { riskScore, riskLevel, reasons } to every request.
+ *
+ * Detected signals (all O(1), in-memory, zero external calls):
+ *   velocity              — too many requests from this IP in the window
+ *   spike                 — burst of requests in 10 s
+ *   enumeration           — sequential numeric IDs in URL path
+ *   endpoint_concentration — same endpoint hit repeatedly (scraping)
+ *   probing               — high 4xx rate (directory / param probing)
+ *   flow_anomaly          — write request with no prior read (bot shortcut)
+ *
+ * Mount it narrowly: app.use("/api/checkout", watchAccess()) rather than globally.
+ */
+export function watchAccess(options = {}) {
+    const engine = createEngine(options);
+    return function watchAccessMiddleware(req, res, next) {
+        const ip = resolveIp(req);
+        const url = req.url ?? "";
+        const method = req.method ?? "GET";
+        const reasons = engine.track(ip, { url, method });
+        // Capture response status asynchronously for probing detection.
+        // Safe cast: a no-op when res has no 'on' method (plain object, tests).
+        const resObj = res;
+        resObj.on?.("finish", () => {
+            if (typeof resObj.statusCode === "number" && resObj.statusCode >= 400) {
+                engine.reportError(ip);
+            }
+        });
+        req.signupGuardRisk = buildRiskResult(reasons);
+        next();
+    };
+}
+function resolveIp(req) {
+    const forwarded = req.headers?.["x-forwarded-for"];
+    if (forwarded) {
+        return Array.isArray(forwarded) ? forwarded[0] : forwarded.split(",")[0].trim();
+    }
+    return typeof req.ip === "string" ? req.ip : "unknown";
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "apira-guard",
+  "version": "0.1.0",
+  "description": "Catches bots, abuse, and broken flows after Cloudflare, before PostHog.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "demo",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test"
+  },
+  "keywords": [
+    "apira-guard",
+    "signup",
+    "guard",
+    "forms",
+    "spam-prevention",
+    "email-validation",
+    "phone-validation",
+    "disposable-email"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3"
+  }
+}