apira-guard 0.1.0

package/src/risk.ts

@@ -0,0 +1,36 @@
+export type RiskReason =
+  | "velocity"               // too many attempts / requests in the window
+  | "spike"                  // sudden burst (API: > N req in 10 s)
+  | "fast_action"            // submitted unrealistically fast after page load
+  | "retry"                  // same form submitted more than once
+  | "enumeration"            // sequential numeric IDs in URL path
+  | "endpoint_concentration" // one endpoint hit repeatedly (scraping / extraction)
+  | "probing"                // high 4xx rate from this IP (directory / param probing)
+  | "flow_anomaly";          // write request with no prior read (bot / agent shortcut)
+
+export type RiskLevel = "low" | "medium" | "high";
+
+export type RiskResult = {
+  riskScore: number;
+  riskLevel: RiskLevel;
+  reasons: RiskReason[];
+};
+
+// Weights per spec: velocity +30, retry +25, fast_action +20
+const REASON_SCORES: Record<RiskReason, number> = {
+  velocity: 30,
+  spike: 40,
+  fast_action: 20,
+  retry: 25,
+  enumeration: 50,
+  endpoint_concentration: 35,
+  probing: 40,
+  flow_anomaly: 30
+};
+
+export function buildRiskResult(reasons: RiskReason[]): RiskResult {
+  const unique = [...new Set(reasons)];
+  const riskScore = Math.min(100, unique.reduce((sum, r) => sum + REASON_SCORES[r], 0));
+  const riskLevel: RiskLevel = riskScore >= 70 ? "high" : riskScore >= 40 ? "medium" : "low";
+  return { riskScore, riskLevel, reasons: unique };
+}

package/src/server.ts

@@ -0,0 +1,80 @@
+import { createEngine, type EngineOptions } from "./engine.js";
+import { buildRiskResult } from "./risk.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 function watchAccess(options: WatchAccessOptions = {}): WatchAccessMiddleware {
+  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 as { on?: (event: string, cb: () => void) => void; statusCode?: unknown };
+    resObj.on?.("finish", () => {
+      if (typeof resObj.statusCode === "number" && resObj.statusCode >= 400) {
+        engine.reportError(ip);
+      }
+    });
+
+    req.signupGuardRisk = buildRiskResult(reasons);
+
+    next();
+  };
+}
+
+function resolveIp(req: SignupGuardRequest): string {
+  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";
+}