guardian-risk-express 0.1.1 → 0.2.0

package/README.md

@@ -6,34 +6,57 @@
 npm install guardian-risk guardian-risk-express
 ```
 
-> **Stub package** — API may change before `1.0.0`.
+Express integration for [guardian-risk](https://www.npmjs.com/package/guardian-risk). Validates client IP, reads HTTP metadata, and provides production middleware.
 
-Express integration for [guardian-risk](https://www.npmjs.com/package/guardian-risk). Reads HTTP request data and adds risk signals.
-
-## Planned signals
+## Signals
 
 | Signal | Source |
 |--------|--------|
-| `clientIp` | `req.ip` / forwarded headers |
-| `userAgent` | `User-Agent` header |
+| `clientIp` | Validated `req.ip` / `req.ips` (trust proxy aware) |
+| `userAgent` | `User-Agent` header (truncated) |
 | `requestMethod` | `req.method` |
-| `requestsPerMinute` | Rate counter (with Redis plugin) |
+| `requestPath` | `req.path` |
 
-## Usage (stub)
+## Production usage
 
 ```typescript
+import express from 'express';
 import { Guardian } from 'guardian-risk';
-import { expressPlugin, fromRequest } from 'guardian-risk-express';
+import { expressPlugin, guardianMiddleware } from 'guardian-risk-express';
+import { redisPlugin } from 'guardian-risk-redis';
+
+const app = express();
+app.set('trust proxy', 1); // required behind load balancers
+
+const template = new Guardian()
+  .use(expressPlugin({ trustProxy: true }))
+  .use(redisPlugin({ url: process.env.REDIS_URL }))
+  .rule({ name: 'HighRate', when: (s) => (s.requestsPerMinute ?? 0) > 120, score: 40 });
+
+app.get('/health', (_req, res) => res.json({ ok: true }));
+
+app.use(
+  guardianMiddleware(template, {
+    blockAboveScore: 70,
+    onAnalyzeError: 'block', // fail closed when hooks fail
+    exposeBlockDetails: false, // never leak reasons to clients
+  }),
+);
+```
 
-const guardian = new Guardian().use(expressPlugin({ trustProxy: true }));
+## Security notes
 
-// Future: per-request signal injection
-// app.use((req, res, next) => {
-//   fromRequest(req, guardian);
-//   next();
-// });
-```
+- Set **`app.set('trust proxy', N)`** when behind a reverse proxy — otherwise `clientIp` reflects the proxy, not the user.
+- **`clientIp` is validated** — malformed `X-Forwarded-For` values are rejected.
+- Use **`onAnalyzeError: 'block'`** in production when `blockAboveScore` is set.
+- Use **`template.fork()`** or `guardianMiddleware` — never share one `Guardian` across requests.
+- Headers and user agents are **spoofable** — treat as hints, not proof.
+
+## API
 
-## Status
+- `expressPlugin(options)` — registers `beforeAnalyze` hook
+- `fromRequest(req, guardian, options)` — manual per-request signal injection
+- `guardianMiddleware(template, options)` — Express middleware with optional blocking
+- `analyzeRequest(template, req, options)` — programmatic analyze helper
 
-Not yet published. Implementation in progress.
+See [SECURITY.md](../../SECURITY.md) and [MIGRATION.md](../../MIGRATION.md).

package/dist/index.cjs

@@ -1,17 +1,141 @@
 'use strict';
 
+var guardianRisk = require('guardian-risk');
+
+// src/request.ts
+var MAX_HEADER_LENGTH = 512;
+function fromRequest(req, guardian, options = {}) {
+  const { trustProxy = false } = options;
+  const clientIp = resolveClientIp(req, trustProxy);
+  const userAgent = truncate(readHeader(req, "user-agent") ?? "unknown", MAX_HEADER_LENGTH);
+  const contentLength = Number(readHeader(req, "content-length") ?? 0);
+  const acceptLanguage = truncate(
+    readHeader(req, "accept-language") ?? "unknown",
+    MAX_HEADER_LENGTH
+  );
+  return guardian.signal("clientIp", clientIp).signal("userAgent", userAgent).signal("requestMethod", req.method ?? "UNKNOWN").signal("requestPath", truncate(req.path ?? req.originalUrl ?? "/", MAX_HEADER_LENGTH)).signal("contentLength", Number.isFinite(contentLength) ? contentLength : 0).signal("acceptLanguage", acceptLanguage).signal("requestSource", "express");
+}
+function expressBeforeAnalyze(options = {}) {
+  return ({ data: req, guardian }) => {
+    fromRequest(req, guardian, options);
+  };
+}
+function resolveClientIp(req, trustProxy) {
+  if (trustProxy) {
+    if (req.ips && req.ips.length > 0) {
+      for (const candidate of req.ips) {
+        const parsed = guardianRisk.parseIpAddress(candidate);
+        if (parsed) {
+          return parsed;
+        }
+      }
+    }
+    const forwarded = readHeader(req, "x-forwarded-for");
+    if (forwarded) {
+      for (const part of forwarded.split(",")) {
+        const parsed = guardianRisk.parseIpAddress(part);
+        if (parsed) {
+          return parsed;
+        }
+      }
+    }
+  }
+  const fromReqIp = req.ip ? guardianRisk.parseIpAddress(req.ip) : null;
+  if (fromReqIp) {
+    return fromReqIp;
+  }
+  const fromSocket = req.socket?.remoteAddress ? guardianRisk.parseIpAddress(req.socket.remoteAddress) : null;
+  if (fromSocket) {
+    return fromSocket;
+  }
+  return "unknown";
+}
+function readHeader(req, name) {
+  const fromGetter = req.get?.(name);
+  if (fromGetter) {
+    return fromGetter;
+  }
+  const value = req.headers[name.toLowerCase()] ?? req.headers[name];
+  if (Array.isArray(value)) {
+    return value[0];
+  }
+  return value;
+}
+function truncate(value, max) {
+  return value.length > max ? value.slice(0, max) : value;
+}
+
+// src/middleware.ts
+async function analyzeRequest(template, req, options = {}) {
+  const guardian = template.fork();
+  if (!template.getInstalledPlugins().includes("guardian-risk-express")) {
+    fromRequest(req, guardian, options);
+  }
+  const report = await guardian.analyzeAsync(req);
+  return { guardian, report };
+}
+function guardianMiddleware(template, options = {}) {
+  const {
+    attachToRequest = true,
+    blockAboveScore,
+    trustProxy = false,
+    exposeBlockDetails = false
+  } = options;
+  const onAnalyzeError = options.onAnalyzeError ?? (blockAboveScore !== void 0 ? "block" : "pass");
+  return (req, res, next) => {
+    void (async () => {
+      try {
+        const guardian = template.fork();
+        if (!template.getInstalledPlugins().includes("guardian-risk-express")) {
+          fromRequest(req, guardian, { trustProxy });
+        }
+        const report = await guardian.analyzeAsync(req);
+        if (attachToRequest) {
+          req.guardian = guardian;
+          req.riskReport = report;
+        }
+        if (blockAboveScore !== void 0 && report.score >= blockAboveScore) {
+          sendBlocked(res, report, exposeBlockDetails);
+          return;
+        }
+        next();
+      } catch (error) {
+        if (onAnalyzeError === "block") {
+          res.status(503).json({ error: "Risk analysis unavailable" });
+          return;
+        }
+        next(error);
+      }
+    })();
+  };
+}
+function sendBlocked(res, report, exposeDetails) {
+  if (exposeDetails) {
+    res.status(403).json({
+      error: "Request blocked",
+      score: report.score,
+      level: report.level,
+      reasons: report.reasons
+    });
+    return;
+  }
+  res.status(403).json({ error: "Request blocked" });
+}
+
 // src/index.ts
 function expressPlugin(options = {}) {
-  const { trustProxy = false } = options;
+  const hook = expressBeforeAnalyze(options);
   return {
     name: "guardian-risk-express",
-    install(_guardian) {
+    install(guardian) {
+      guardian.beforeAnalyze(hook);
     }
   };
 }
-function fromRequest(_req, guardian) {
-  return guardian.signal("requestSource", "express").signal("expressPlugin", "stub");
-}
 
+exports.analyzeRequest = analyzeRequest;
+exports.expressBeforeAnalyze = expressBeforeAnalyze;
 exports.expressPlugin = expressPlugin;
 exports.fromRequest = fromRequest;
+exports.guardianMiddleware = guardianMiddleware;
+exports.resolveClientIp = resolveClientIp;

package/dist/index.d.cts

@@ -1,22 +1,85 @@
 import * as guardian_risk from 'guardian-risk';
-import { Plugin } from 'guardian-risk';
+import { RiskReport, Guardian, Plugin } from 'guardian-risk';
 
-/** Options for the Express plugin (stub). */
+/** Minimal Express request shape — no express import required at runtime. */
+interface ExpressRequestLike {
+    readonly ip?: string;
+    readonly ips?: readonly string[];
+    readonly method?: string;
+    readonly path?: string;
+    readonly originalUrl?: string;
+    readonly headers: Record<string, string | string[] | undefined>;
+    readonly socket?: {
+        readonly remoteAddress?: string;
+    };
+    get?(name: string): string | undefined;
+}
+/** Options for reading request signals. */
 interface ExpressPluginOptions {
-    /** Trust X-Forwarded-* headers when reading client IP. */
+    /**
+     * Trust proxy-forwarded IPs (requires `app.set('trust proxy', ...)` in Express).
+     */
     readonly trustProxy?: boolean;
 }
 /**
- * Express plugin for guardian-risk.
- *
- * @stub This plugin is a stub. Future versions will read Express requests
- * and add signals such as `clientIp`, `userAgent`, `requestMethod`, and
- * `requestsPerMinute`.
+ * Extract HTTP request signals and attach them to a Guardian instance.
+ */
+declare function fromRequest(req: ExpressRequestLike, guardian: guardian_risk.Guardian, options?: ExpressPluginOptions): guardian_risk.Guardian;
+/**
+ * Returns a beforeAnalyze hook that enriches signals from an Express request.
  */
-declare function expressPlugin(options?: ExpressPluginOptions): Plugin;
+declare function expressBeforeAnalyze(options?: ExpressPluginOptions): guardian_risk.BeforeAnalyzeHook<ExpressRequestLike>;
 /**
- * @stub Future middleware that enriches a Guardian instance from an Express request.
+ * Resolve client IP with validation. Spoofed or invalid values are rejected.
+ */
+declare function resolveClientIp(req: ExpressRequestLike, trustProxy: boolean): string;
+
+/** Express-compatible middleware types (optional peer). */
+interface ExpressRequest extends ExpressRequestLike {
+    riskReport?: RiskReport;
+    guardian?: Guardian;
+}
+type ExpressNextFunction = (error?: unknown) => void;
+interface ExpressResponse {
+    status(code: number): ExpressResponse;
+    json(body: unknown): void;
+}
+type ExpressRequestHandler = (req: ExpressRequest, res: ExpressResponse, next: ExpressNextFunction) => void;
+type AnalyzeErrorPolicy = 'pass' | 'block';
+interface GuardianMiddlewareOptions extends ExpressPluginOptions {
+    readonly attachToRequest?: boolean;
+    /** Block when score is greater than or equal to this threshold. */
+    readonly blockAboveScore?: number;
+    /**
+     * When analysis fails (hook timeout, VPN error), `block` returns 503.
+     * Defaults to `block` when `blockAboveScore` is set, otherwise `pass`.
+     */
+    readonly onAnalyzeError?: AnalyzeErrorPolicy;
+    /** Include score/reasons in block response (default: false). */
+    readonly exposeBlockDetails?: boolean;
+}
+declare function analyzeRequest(template: Guardian, req: ExpressRequestLike, options?: ExpressPluginOptions): Promise<{
+    guardian: Guardian;
+    report: RiskReport;
+}>;
+declare function guardianMiddleware(template: Guardian, options?: GuardianMiddlewareOptions): ExpressRequestHandler;
+
+/** Options for the Express plugin. */
+type ExpressPluginConfig = ExpressPluginOptions;
+/**
+ * Express plugin — registers a beforeAnalyze hook for request signal collection.
+ *
+ * Usage with middleware (recommended):
+ * ```typescript
+ * app.use(guardianMiddleware(template, { trustProxy: true }));
+ * ```
+ *
+ * Or manual:
+ * ```typescript
+ * const g = template.fork().use(expressPlugin({ trustProxy: true }));
+ * const report = await g.analyzeAsync(req);
+ * ```
  */
-declare function fromRequest(_req: unknown, guardian: guardian_risk.Guardian): guardian_risk.Guardian;
+declare function expressPlugin(options?: ExpressPluginConfig): Plugin;
 
-export { type ExpressPluginOptions, expressPlugin, fromRequest };
+export { type AnalyzeErrorPolicy, type ExpressNextFunction, type ExpressPluginConfig, type ExpressPluginOptions, type ExpressRequest, type ExpressRequestHandler, type ExpressRequestLike, type ExpressResponse, type GuardianMiddlewareOptions, analyzeRequest, expressBeforeAnalyze, expressPlugin, fromRequest, guardianMiddleware, resolveClientIp };

package/dist/index.d.ts

@@ -1,22 +1,85 @@
 import * as guardian_risk from 'guardian-risk';
-import { Plugin } from 'guardian-risk';
+import { RiskReport, Guardian, Plugin } from 'guardian-risk';
 
-/** Options for the Express plugin (stub). */
+/** Minimal Express request shape — no express import required at runtime. */
+interface ExpressRequestLike {
+    readonly ip?: string;
+    readonly ips?: readonly string[];
+    readonly method?: string;
+    readonly path?: string;
+    readonly originalUrl?: string;
+    readonly headers: Record<string, string | string[] | undefined>;
+    readonly socket?: {
+        readonly remoteAddress?: string;
+    };
+    get?(name: string): string | undefined;
+}
+/** Options for reading request signals. */
 interface ExpressPluginOptions {
-    /** Trust X-Forwarded-* headers when reading client IP. */
+    /**
+     * Trust proxy-forwarded IPs (requires `app.set('trust proxy', ...)` in Express).
+     */
     readonly trustProxy?: boolean;
 }
 /**
- * Express plugin for guardian-risk.
- *
- * @stub This plugin is a stub. Future versions will read Express requests
- * and add signals such as `clientIp`, `userAgent`, `requestMethod`, and
- * `requestsPerMinute`.
+ * Extract HTTP request signals and attach them to a Guardian instance.
+ */
+declare function fromRequest(req: ExpressRequestLike, guardian: guardian_risk.Guardian, options?: ExpressPluginOptions): guardian_risk.Guardian;
+/**
+ * Returns a beforeAnalyze hook that enriches signals from an Express request.
  */
-declare function expressPlugin(options?: ExpressPluginOptions): Plugin;
+declare function expressBeforeAnalyze(options?: ExpressPluginOptions): guardian_risk.BeforeAnalyzeHook<ExpressRequestLike>;
 /**
- * @stub Future middleware that enriches a Guardian instance from an Express request.
+ * Resolve client IP with validation. Spoofed or invalid values are rejected.
+ */
+declare function resolveClientIp(req: ExpressRequestLike, trustProxy: boolean): string;
+
+/** Express-compatible middleware types (optional peer). */
+interface ExpressRequest extends ExpressRequestLike {
+    riskReport?: RiskReport;
+    guardian?: Guardian;
+}
+type ExpressNextFunction = (error?: unknown) => void;
+interface ExpressResponse {
+    status(code: number): ExpressResponse;
+    json(body: unknown): void;
+}
+type ExpressRequestHandler = (req: ExpressRequest, res: ExpressResponse, next: ExpressNextFunction) => void;
+type AnalyzeErrorPolicy = 'pass' | 'block';
+interface GuardianMiddlewareOptions extends ExpressPluginOptions {
+    readonly attachToRequest?: boolean;
+    /** Block when score is greater than or equal to this threshold. */
+    readonly blockAboveScore?: number;
+    /**
+     * When analysis fails (hook timeout, VPN error), `block` returns 503.
+     * Defaults to `block` when `blockAboveScore` is set, otherwise `pass`.
+     */
+    readonly onAnalyzeError?: AnalyzeErrorPolicy;
+    /** Include score/reasons in block response (default: false). */
+    readonly exposeBlockDetails?: boolean;
+}
+declare function analyzeRequest(template: Guardian, req: ExpressRequestLike, options?: ExpressPluginOptions): Promise<{
+    guardian: Guardian;
+    report: RiskReport;
+}>;
+declare function guardianMiddleware(template: Guardian, options?: GuardianMiddlewareOptions): ExpressRequestHandler;
+
+/** Options for the Express plugin. */
+type ExpressPluginConfig = ExpressPluginOptions;
+/**
+ * Express plugin — registers a beforeAnalyze hook for request signal collection.
+ *
+ * Usage with middleware (recommended):
+ * ```typescript
+ * app.use(guardianMiddleware(template, { trustProxy: true }));
+ * ```
+ *
+ * Or manual:
+ * ```typescript
+ * const g = template.fork().use(expressPlugin({ trustProxy: true }));
+ * const report = await g.analyzeAsync(req);
+ * ```
  */
-declare function fromRequest(_req: unknown, guardian: guardian_risk.Guardian): guardian_risk.Guardian;
+declare function expressPlugin(options?: ExpressPluginConfig): Plugin;
 
-export { type ExpressPluginOptions, expressPlugin, fromRequest };
+export { type AnalyzeErrorPolicy, type ExpressNextFunction, type ExpressPluginConfig, type ExpressPluginOptions, type ExpressRequest, type ExpressRequestHandler, type ExpressRequestLike, type ExpressResponse, type GuardianMiddlewareOptions, analyzeRequest, expressBeforeAnalyze, expressPlugin, fromRequest, guardianMiddleware, resolveClientIp };

package/dist/index.js

@@ -1,14 +1,134 @@
+import { parseIpAddress } from 'guardian-risk';
+
+// src/request.ts
+var MAX_HEADER_LENGTH = 512;
+function fromRequest(req, guardian, options = {}) {
+  const { trustProxy = false } = options;
+  const clientIp = resolveClientIp(req, trustProxy);
+  const userAgent = truncate(readHeader(req, "user-agent") ?? "unknown", MAX_HEADER_LENGTH);
+  const contentLength = Number(readHeader(req, "content-length") ?? 0);
+  const acceptLanguage = truncate(
+    readHeader(req, "accept-language") ?? "unknown",
+    MAX_HEADER_LENGTH
+  );
+  return guardian.signal("clientIp", clientIp).signal("userAgent", userAgent).signal("requestMethod", req.method ?? "UNKNOWN").signal("requestPath", truncate(req.path ?? req.originalUrl ?? "/", MAX_HEADER_LENGTH)).signal("contentLength", Number.isFinite(contentLength) ? contentLength : 0).signal("acceptLanguage", acceptLanguage).signal("requestSource", "express");
+}
+function expressBeforeAnalyze(options = {}) {
+  return ({ data: req, guardian }) => {
+    fromRequest(req, guardian, options);
+  };
+}
+function resolveClientIp(req, trustProxy) {
+  if (trustProxy) {
+    if (req.ips && req.ips.length > 0) {
+      for (const candidate of req.ips) {
+        const parsed = parseIpAddress(candidate);
+        if (parsed) {
+          return parsed;
+        }
+      }
+    }
+    const forwarded = readHeader(req, "x-forwarded-for");
+    if (forwarded) {
+      for (const part of forwarded.split(",")) {
+        const parsed = parseIpAddress(part);
+        if (parsed) {
+          return parsed;
+        }
+      }
+    }
+  }
+  const fromReqIp = req.ip ? parseIpAddress(req.ip) : null;
+  if (fromReqIp) {
+    return fromReqIp;
+  }
+  const fromSocket = req.socket?.remoteAddress ? parseIpAddress(req.socket.remoteAddress) : null;
+  if (fromSocket) {
+    return fromSocket;
+  }
+  return "unknown";
+}
+function readHeader(req, name) {
+  const fromGetter = req.get?.(name);
+  if (fromGetter) {
+    return fromGetter;
+  }
+  const value = req.headers[name.toLowerCase()] ?? req.headers[name];
+  if (Array.isArray(value)) {
+    return value[0];
+  }
+  return value;
+}
+function truncate(value, max) {
+  return value.length > max ? value.slice(0, max) : value;
+}
+
+// src/middleware.ts
+async function analyzeRequest(template, req, options = {}) {
+  const guardian = template.fork();
+  if (!template.getInstalledPlugins().includes("guardian-risk-express")) {
+    fromRequest(req, guardian, options);
+  }
+  const report = await guardian.analyzeAsync(req);
+  return { guardian, report };
+}
+function guardianMiddleware(template, options = {}) {
+  const {
+    attachToRequest = true,
+    blockAboveScore,
+    trustProxy = false,
+    exposeBlockDetails = false
+  } = options;
+  const onAnalyzeError = options.onAnalyzeError ?? (blockAboveScore !== void 0 ? "block" : "pass");
+  return (req, res, next) => {
+    void (async () => {
+      try {
+        const guardian = template.fork();
+        if (!template.getInstalledPlugins().includes("guardian-risk-express")) {
+          fromRequest(req, guardian, { trustProxy });
+        }
+        const report = await guardian.analyzeAsync(req);
+        if (attachToRequest) {
+          req.guardian = guardian;
+          req.riskReport = report;
+        }
+        if (blockAboveScore !== void 0 && report.score >= blockAboveScore) {
+          sendBlocked(res, report, exposeBlockDetails);
+          return;
+        }
+        next();
+      } catch (error) {
+        if (onAnalyzeError === "block") {
+          res.status(503).json({ error: "Risk analysis unavailable" });
+          return;
+        }
+        next(error);
+      }
+    })();
+  };
+}
+function sendBlocked(res, report, exposeDetails) {
+  if (exposeDetails) {
+    res.status(403).json({
+      error: "Request blocked",
+      score: report.score,
+      level: report.level,
+      reasons: report.reasons
+    });
+    return;
+  }
+  res.status(403).json({ error: "Request blocked" });
+}
+
 // src/index.ts
 function expressPlugin(options = {}) {
-  const { trustProxy = false } = options;
+  const hook = expressBeforeAnalyze(options);
   return {
     name: "guardian-risk-express",
-    install(_guardian) {
+    install(guardian) {
+      guardian.beforeAnalyze(hook);
     }
   };
 }
-function fromRequest(_req, guardian) {
-  return guardian.signal("requestSource", "express").signal("expressPlugin", "stub");
-}
 
-export { expressPlugin, fromRequest };
+export { analyzeRequest, expressBeforeAnalyze, expressPlugin, fromRequest, guardianMiddleware, resolveClientIp };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "guardian-risk-express",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Express middleware plugin for guardian-risk — adds request signals",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -54,7 +54,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "guardian-risk": "^0.2.0",
+    "guardian-risk": "^0.3.0",
     "express": ">=4"
   },
   "peerDependenciesMeta": {
@@ -65,10 +65,12 @@
   "devDependencies": {
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
-    "guardian-risk": "0.2.1"
+    "vitest": "^4.1.9",
+    "guardian-risk": "0.3.0"
   },
   "scripts": {
     "build": "tsup",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }
 }