guardian-risk-express 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guardian Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+# guardian-risk-express
+
+> **Requires:** [`guardian-risk`](https://www.npmjs.com/package/guardian-risk) (core)
+
+```bash
+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). Reads HTTP request data and adds risk signals.
+
+## Planned signals
+
+| Signal | Source |
+|--------|--------|
+| `clientIp` | `req.ip` / forwarded headers |
+| `userAgent` | `User-Agent` header |
+| `requestMethod` | `req.method` |
+| `requestsPerMinute` | Rate counter (with Redis plugin) |
+
+## Usage (stub)
+
+```typescript
+import { Guardian } from 'guardian-risk';
+import { expressPlugin, fromRequest } from 'guardian-risk-express';
+
+const guardian = new Guardian().use(expressPlugin({ trustProxy: true }));
+
+// Future: per-request signal injection
+// app.use((req, res, next) => {
+//   fromRequest(req, guardian);
+//   next();
+// });
+```
+
+## Status
+
+Not yet published. Implementation in progress.

package/dist/index.cjs

@@ -0,0 +1,19 @@
+'use strict';
+
+// src/index.ts
+function expressPlugin(options = {}) {
+  const { trustProxy = false } = options;
+  return {
+    name: "guardian-risk-express",
+    install(_guardian) {
+    }
+  };
+}
+function fromRequest(_req, guardian) {
+  return guardian.signal("requestSource", "express").signal("expressPlugin", "stub");
+}
+
+exports.expressPlugin = expressPlugin;
+exports.fromRequest = fromRequest;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;AAeO,SAAS,aAAA,CAAc,OAAA,GAAgC,EAAC,EAAW;AACxE,EAAA,MAAM,EAAE,UAAA,GAAa,KAAA,EAAM,GAAI,OAAA;AAE/B,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,uBAAA;AAAA,IACN,QAAQ,SAAA,EAAW;AACZ,IAEP;AAAA,GACF;AACF;AAKO,SAAS,WAAA,CACd,MACA,QAAA,EACkC;AAClC,EAAA,OAAO,SACJ,MAAA,CAAO,eAAA,EAAiB,SAAS,CAAA,CACjC,MAAA,CAAO,iBAAiB,MAAM,CAAA;AACnC","file":"index.cjs","sourcesContent":["import type { Plugin } from 'guardian-risk';\n\n/** Options for the Express plugin (stub). */\nexport interface ExpressPluginOptions {\n  /** Trust X-Forwarded-* headers when reading client IP. */\n  readonly trustProxy?: boolean;\n}\n\n/**\n * Express plugin for guardian-risk.\n *\n * @stub This plugin is a stub. Future versions will read Express requests\n * and add signals such as `clientIp`, `userAgent`, `requestMethod`, and\n * `requestsPerMinute`.\n */\nexport function expressPlugin(options: ExpressPluginOptions = {}): Plugin {\n  const { trustProxy = false } = options;\n\n  return {\n    name: 'guardian-risk-express',\n    install(_guardian) {\n      void trustProxy;\n      // Stub: middleware will attach signals from req before analyze()\n    },\n  };\n}\n\n/**\n * @stub Future middleware that enriches a Guardian instance from an Express request.\n */\nexport function fromRequest(\n  _req: unknown,\n  guardian: import('guardian-risk').Guardian,\n): import('guardian-risk').Guardian {\n  return guardian\n    .signal('requestSource', 'express')\n    .signal('expressPlugin', 'stub');\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,22 @@
+import * as guardian_risk from 'guardian-risk';
+import { Plugin } from 'guardian-risk';
+
+/** Options for the Express plugin (stub). */
+interface ExpressPluginOptions {
+    /** Trust X-Forwarded-* headers when reading client IP. */
+    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`.
+ */
+declare function expressPlugin(options?: ExpressPluginOptions): Plugin;
+/**
+ * @stub Future middleware that enriches a Guardian instance from an Express request.
+ */
+declare function fromRequest(_req: unknown, guardian: guardian_risk.Guardian): guardian_risk.Guardian;
+
+export { type ExpressPluginOptions, expressPlugin, fromRequest };

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import * as guardian_risk from 'guardian-risk';
+import { Plugin } from 'guardian-risk';
+
+/** Options for the Express plugin (stub). */
+interface ExpressPluginOptions {
+    /** Trust X-Forwarded-* headers when reading client IP. */
+    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`.
+ */
+declare function expressPlugin(options?: ExpressPluginOptions): Plugin;
+/**
+ * @stub Future middleware that enriches a Guardian instance from an Express request.
+ */
+declare function fromRequest(_req: unknown, guardian: guardian_risk.Guardian): guardian_risk.Guardian;
+
+export { type ExpressPluginOptions, expressPlugin, fromRequest };

package/dist/index.js

@@ -0,0 +1,16 @@
+// src/index.ts
+function expressPlugin(options = {}) {
+  const { trustProxy = false } = options;
+  return {
+    name: "guardian-risk-express",
+    install(_guardian) {
+    }
+  };
+}
+function fromRequest(_req, guardian) {
+  return guardian.signal("requestSource", "express").signal("expressPlugin", "stub");
+}
+
+export { expressPlugin, fromRequest };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";AAeO,SAAS,aAAA,CAAc,OAAA,GAAgC,EAAC,EAAW;AACxE,EAAA,MAAM,EAAE,UAAA,GAAa,KAAA,EAAM,GAAI,OAAA;AAE/B,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,uBAAA;AAAA,IACN,QAAQ,SAAA,EAAW;AACZ,IAEP;AAAA,GACF;AACF;AAKO,SAAS,WAAA,CACd,MACA,QAAA,EACkC;AAClC,EAAA,OAAO,SACJ,MAAA,CAAO,eAAA,EAAiB,SAAS,CAAA,CACjC,MAAA,CAAO,iBAAiB,MAAM,CAAA;AACnC","file":"index.js","sourcesContent":["import type { Plugin } from 'guardian-risk';\n\n/** Options for the Express plugin (stub). */\nexport interface ExpressPluginOptions {\n  /** Trust X-Forwarded-* headers when reading client IP. */\n  readonly trustProxy?: boolean;\n}\n\n/**\n * Express plugin for guardian-risk.\n *\n * @stub This plugin is a stub. Future versions will read Express requests\n * and add signals such as `clientIp`, `userAgent`, `requestMethod`, and\n * `requestsPerMinute`.\n */\nexport function expressPlugin(options: ExpressPluginOptions = {}): Plugin {\n  const { trustProxy = false } = options;\n\n  return {\n    name: 'guardian-risk-express',\n    install(_guardian) {\n      void trustProxy;\n      // Stub: middleware will attach signals from req before analyze()\n    },\n  };\n}\n\n/**\n * @stub Future middleware that enriches a Guardian instance from an Express request.\n */\nexport function fromRequest(\n  _req: unknown,\n  guardian: import('guardian-risk').Guardian,\n): import('guardian-risk').Guardian {\n  return guardian\n    .signal('requestSource', 'express')\n    .signal('expressPlugin', 'stub');\n}\n"]}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "guardian-risk-express",
+  "version": "0.1.0",
+  "description": "Express middleware plugin for guardian-risk — adds request signals",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "guardian-risk",
+    "guardian-risk-express",
+    "express",
+    "middleware",
+    "risk",
+    "security"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/himanshu6306singh/guardian-risk.git",
+    "directory": "packages/express"
+  },
+  "homepage": "https://github.com/himanshu6306singh/guardian-risk/tree/main/packages/express#readme",
+  "bugs": {
+    "url": "https://github.com/himanshu6306singh/guardian-risk/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "guardian-risk": "^0.2.0",
+    "express": ">=4"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "guardian-risk": "0.2.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}