@roboteby/parry 1.1.0-rc.1

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows [Semantic Versioning](https://semver.org/) for public API and
+runtime behavior. The format is based on [Keep a Changelog](https://keepachangelog.com/),
+without adding a changelog generation dependency.
+
+## [Unreleased]
+
+### Added
+
+- Release workflow preparation.
+- npm package hardening.
+- Package tarball validation scripts.
+
+### Security
+
+- Documented npm publishing and supply-chain hardening with Trusted Publishing/OIDC.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RobotEby
+
+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,284 @@
+# parry-express-security-middleware
+
+Application-layer security middleware for Express.js.
+
+## Overview
+
+Parry is a CommonJS security middleware for Express applications. It helps block common application-layer abuse before requests reach route handlers, while keeping the public API small and compatible with standard Express middleware usage.
+
+Parry detects and blocks patterns associated with SQL injection, XSS, NoSQL injection, HTTP parameter pollution, prototype pollution, path traversal, rate abuse, and brute-force authentication attempts. It also emits structured Threat Events and metrics that can be inspected through an optional read-only Admin API.
+
+Parry is not a complete volumetric DDoS protection product. Network floods, L3/L4 abuse, TLS exhaustion, CDN filtering, and edge rate controls should be handled by CloudFront, AWS WAF, Shield, a CDN, an ALB/load balancer, or equivalent infrastructure controls.
+
+## Why Parry
+
+Parry centralizes application-layer security policy in one Express middleware. That gives backend teams a consistent place to tune detector behavior, route-based limits, brute-force protection, event logging, and distributed rate limiting.
+
+It is designed for development and production-like deployments:
+
+- use `MemoryStore` for local development and single-process services;
+- use `RedisStore` for multiple instances, containers, ECS, Kubernetes, PM2 cluster, or load-balanced services;
+- expose the Admin API only behind authentication, private networking, VPN, or a trusted reverse proxy.
+
+## Features
+
+- SQL injection detection
+- XSS detection
+- NoSQL injection detection
+- HTTP parameter pollution checks
+- Prototype pollution checks
+- Path traversal checks
+- Request shape guard
+- Global and route-based rate limiting
+- BruteForceGuard for authentication routes
+- `MemoryStore` and optional `RedisStore`
+- Structured Threat Events
+- Metrics and observability helpers
+- Optional read-only Admin API
+- Route-based policies and presets
+- Docker demo API
+- AWS reference infrastructure
+
+## Installation
+
+```bash
+npm install @roboteby/parry
+```
+
+Parry expects Express to be installed by your application.
+
+## Quick Start
+
+```js
+const express = require('express');
+const { createParry } = require('@roboteby/parry');
+
+const app = express();
+
+const parry = createParry({
+  preset: 'recommended',
+});
+
+app.use(express.json());
+app.use(parry.middleware());
+
+app.get('/health', (_req, res) => {
+  res.json({ ok: true });
+});
+
+app.listen(3000);
+```
+
+Parse JSON and URL-encoded bodies before Parry when you want Parry to inspect request bodies. Keep Parry before routes that should be protected.
+
+The legacy `Parry_DDoS(options)` export remains available for existing CommonJS integrations:
+
+```js
+const { Parry_DDoS } = require('@roboteby/parry');
+
+app.use(express.json());
+app.use(Parry_DDoS({ preset: 'recommended' }));
+```
+
+## Presets
+
+Parry supports conservative presets for common application-layer protection:
+
+- `off`: no route-policy preset is added.
+- `recommended`: enables practical defaults for common auth routes and low-noise application-layer checks.
+- `strict`: uses more restrictive brute-force and route rate-limit defaults for sensitive environments.
+
+Every option can still be configured explicitly. Prefer starting with `recommended`, reviewing logs and events, then tightening route policies where needed.
+
+## Stores
+
+`MemoryStore` is the default store. It is suitable for tests, demos, local development, and single-process deployments.
+
+For distributed deployments, use `RedisStore` with a Redis client created by your application:
+
+```js
+const { createClient } = require('redis');
+const { createParry, RedisStore } = require('@roboteby/parry');
+
+const redis = createClient({ url: process.env.REDIS_URL });
+await redis.connect();
+
+const parry = createParry({
+  store: new RedisStore({ client: redis, prefix: 'parry' }),
+  rateLimit: {
+    enabled: true,
+    max: 100,
+    windowMs: 60_000,
+    headers: true,
+  },
+});
+```
+
+If your service runs behind multiple instances, containers, or load balancers, use a shared store. `MemoryStore` protects only the current Node.js process.
+
+## Brute-Force Protection
+
+Route policies can protect sensitive authentication endpoints without making the global rate limit too aggressive:
+
+```js
+const parry = createParry({
+  policies: [
+    {
+      name: 'auth-login',
+      match: { method: 'POST', path: '/login' },
+      rateLimit: {
+        enabled: true,
+        max: 20,
+        windowMs: 60_000,
+        key: 'ip',
+      },
+      bruteForce: {
+        enabled: true,
+        maxAttempts: 5,
+        windowMs: 15 * 60_000,
+        blockDurationMs: 10 * 60_000,
+        keys: ['ip', 'body.email', 'ip+body.email'],
+        failureStatusCodes: [400, 401, 403],
+        resetOnSuccess: true,
+      },
+    },
+  ],
+});
+```
+
+Routes can also report authentication outcomes manually:
+
+```js
+app.post('/login', async (req, res) => {
+  const user = await authService.validate(req.body.email, req.body.password);
+
+  if (!user) {
+    req.parry?.recordAuthFailure('invalid_credentials');
+    return res.status(200).json({ success: false });
+  }
+
+  req.parry?.recordAuthSuccess();
+  return res.json({ success: true });
+});
+```
+
+## Threat Events and Admin API
+
+Parry emits structured Threat Events for blocked requests, rate limits, brute-force blocks, store errors, and hook errors. Events are sanitized before reaching logs, hooks, metrics, or the Admin API.
+
+The optional Admin API is read-only and is never mounted automatically:
+
+```js
+const { createParry, createParryAdminRouter } = require('@roboteby/parry');
+
+const parry = createParry({
+  admin: {
+    enabled: true,
+    auth: {
+      mode: 'token',
+      token: process.env.PARRY_ADMIN_TOKEN,
+    },
+  },
+});
+
+app.use(parry.middleware());
+app.use('/_parry', createParryAdminRouter(parry));
+```
+
+Main endpoints:
+
+- `GET /_parry/health`
+- `GET /_parry/metrics`
+- `GET /_parry/events`
+- `GET /_parry/events/:id`
+- `GET /_parry/bans`
+- `GET /_parry/policies`
+
+Protect the Admin API with token auth for local demos, or with VPN, private networking, Cloudflare Access, AWS ALB/Cognito auth, trusted proxy auth, or IP allowlists in production.
+
+## Parry Security Console
+
+The separate `parry-security-console` repository provides a read-only dashboard for the Parry Admin API. It displays health, metrics, Threat Events, bans/blocks, and route policies. It does not contain middleware logic, does not execute payloads, and is not a scanner.
+
+For local development, the console can use Vite proxying with `VITE_PARRY_API_URL=/api/parry`.
+
+## Docker Demo
+
+The repository includes a demo Express API with Redis:
+
+```bash
+docker compose up --build
+```
+
+Useful local checks:
+
+```bash
+curl http://localhost:3000/health
+
+curl http://localhost:3000/_parry/health \
+  -H "x-parry-admin-token: change-me"
+
+curl -X POST http://localhost:3000/echo \
+  -H "Content-Type: application/json" \
+  -d '{"message":"hello"}'
+```
+
+The `change-me` token is for local demos only.
+
+## Security Model
+
+Parry operates inside the Express application. It helps identify and block suspicious application-layer requests, but it does not replace edge and infrastructure controls.
+
+Production deployments should account for:
+
+- CloudFront, AWS WAF, Shield, CDN, ALB, or equivalent edge protection for volumetric DDoS and network-layer abuse.
+- RedisStore or another shared store for distributed rate limits and brute-force counters.
+- Admin API authentication and network restrictions.
+- Trusted proxy configuration before accepting `x-forwarded-for`, Cloudflare Access, ALB/Cognito, or reverse-proxy identity headers.
+- Generic authentication responses that do not reveal whether a username or email exists.
+
+Browser-visible Admin API tokens are appropriate only for local development and demos. Production consoles should be protected by VPN, private networking, Cloudflare Access, ALB/Cognito, reverse proxy auth, or a backend/admin gateway.
+
+## Documentation
+
+Additional documentation is available in the repository:
+
+- [Admin API](https://github.com/RobotEby/parry-express-security-middleware/blob/main/docs/admin-api.md)
+- [Admin API authentication](https://github.com/RobotEby/parry-express-security-middleware/blob/main/docs/admin-api-auth.md)
+- [AWS Admin API authentication](https://github.com/RobotEby/parry-express-security-middleware/blob/main/docs/aws-admin-auth.md)
+- [Docker demo](https://github.com/RobotEby/parry-express-security-middleware/blob/main/docs/docker-demo.md)
+- [AWS infrastructure notes](https://github.com/RobotEby/parry-express-security-middleware/blob/main/docs/aws-infra.md)
+- [CI/CD](https://github.com/RobotEby/parry-express-security-middleware/blob/main/docs/ci-cd.md)
+- [Release process](https://github.com/RobotEby/parry-express-security-middleware/blob/main/docs/release.md)
+- [Payload regression testing](https://github.com/RobotEby/parry-express-security-middleware/blob/main/docs/testing-payloads.md)
+- [Architecture](https://github.com/RobotEby/parry-express-security-middleware/blob/main/docs/architecture.md)
+
+The npm package keeps `docs/`, infrastructure, Docker demo files, and tests out of the published runtime package.
+
+## Development
+
+```bash
+npm ci
+npm test
+npm run test:fixtures
+npm run test:payload-regression
+npm run package:check
+npm pack --dry-run
+```
+
+`npm test` uses local mocks and fake stores. It does not require Redis, AWS, Cloudflare, or external services.
+
+## Roadmap
+
+Planned areas for future work:
+
+- Redis-backed event persistence
+- OpenTelemetry and Prometheus export
+- Express 4 compatibility matrix
+- Optional hashing/redaction for store keys
+- Additional detector tuning with benign counterexamples
+- Admin API hardening and deployment guides
+
+## License
+
+MIT

package/config/defaults.js

@@ -0,0 +1,65 @@
+'use strict';
+
+const DEFAULTS = {
+  sql: true,
+  xss: true,
+  nosql: true,
+
+  hpp: {
+    enabled: false,
+    allowDuplicateParamsFor: [],
+  },
+  prototypePollution: {
+    enabled: true,
+  },
+  pathTraversal: {
+    enabled: true,
+  },
+  requestShape: {
+    enabled: true,
+    maxDepth: 8,
+    maxKeys: 500,
+    maxArrayLength: 100,
+    maxStringLength: 10_000,
+  },
+
+  rateLimit: true,
+  maxRequests: 100,
+  windowMs: 60_000,
+  store: null,
+  storeFailureMode: 'fail-open',
+  policies: [],
+  preset: 'off',
+  bruteForce: {
+    enabled: false,
+  },
+  events: {
+    maxEvents: 500,
+  },
+  admin: {
+    enabled: false,
+    path: '/_parry',
+    allowMutations: false,
+    allowInsecureAdminApi: false,
+    auth: null,
+  },
+  requestId: {
+    enabled: true,
+    header: 'x-request-id',
+    responseHeader: false,
+  },
+  trustProxyHeaders: false,
+  trustedProxies: [],
+  debug: false,
+
+  suspiciousThreshold: 5,
+  banDurationMs: 300_000,
+
+  logThreats: true,
+
+  onThreat: null,
+
+  maxObjectDepth: 5,
+};
+
+module.exports = { DEFAULTS };

package/constants/patterns.js

@@ -0,0 +1,77 @@
+'use strict';
+
+const SQL_PATTERNS = [
+  /\b(union)\b.{0,30}\b(select)\b/i,
+  /\b(or|and)\b\s+[\w'"]{1,20}\s*=\s*[\w'"]{1,20}/i,
+  /(['"`]\s*(--|#|\/\*)|(--|#|\/\*)\s*$)/,
+  /;\s*(drop|alter|truncate|delete|insert|update|create|exec|execute)\b/i,
+  /\b(sleep|benchmark|pg_sleep|waitfor\s+delay)\s*\(/i,
+  /\b(select|insert|update|delete|drop|alter)\b.{0,80}\b(from|into|table|where)\b/i,
+  /'?\s*\bor\b\s+'?1'?\s*=\s*'?1/i,
+  /'?\s*\band\b\s+'?1'?\s*=\s*'?1/i,
+  /information_schema|sys\.tables|sysobjects|pg_catalog/i,
+  /\bchar\s*\(\s*\d+/i,
+  /0x[0-9a-f]{2,}/i,
+  /\b(load_file|into\s+outfile|into\s+dumpfile)\b/i,
+  /\b(exec\s*\(|xp_cmdshell|sp_executesql)\b/i,
+];
+
+const XSS_PATTERNS = [
+  /<\s*script[\s\S]*?>[\s\S]*?<\s*\/\s*script\s*>/i,
+  /<\s*script\b[^>]*>/i,
+  /\bon\w+\s*=\s*["']?[^"'>]*/i,
+  /javascript\s*:/i,
+  /vbscript\s*:/i,
+  /data\s*:\s*[^,]*script/i,
+  /<\s*(img|iframe|object|embed|svg|video|audio|source|track|input)\b[^>]*\s(src|data|href)\s*=\s*["']?\s*javascript/i,
+  /<\s*svg\b[^>]*>[\s\S]*?(script|onload|onerror)/i,
+  /expression\s*\(/i,
+  /url\s*\(\s*["']?\s*javascript/i,
+  /\{\{[\s\S]{0,200}\}\}/,
+  /\$\{[\s\S]{0,200}\}/,
+  /<\s*(base|link|meta|style)\b[^>]*(http-equiv|href|content)\s*=\s*["']?[^"'>]*script/i,
+  /\0|%00/,
+  /autofocus.{0,30}onfocus/i,
+];
+
+const NOSQL_DANGEROUS_OPERATORS = new Set(['$where', '$expr', '$function', '$accumulator']);
+
+const NOSQL_SUSPICIOUS_OPERATORS = new Set([
+  '$gt',
+  '$gte',
+  '$lt',
+  '$lte',
+  '$ne',
+  '$in',
+  '$nin',
+  '$or',
+  '$and',
+  '$not',
+  '$nor',
+  '$exists',
+  '$type',
+  '$regex',
+  '$options',
+  '$elemMatch',
+  '$size',
+  '$slice',
+  '$meta',
+]);
+
+const NOSQL_STRING_PATTERNS = [
+  /"\$\w+"?\s*:/,
+  /\$where\s*[:=]\s*["'`]?(function|this\.|sleep|db\.)/i,
+  /\b(mapReduce|runCommand|eval)\s*\(/i,
+  /db\.(getCollection|find|update|insert|remove|drop)\s*\(/i,
+];
+
+const SENSITIVE_HEADERS = ['user-agent', 'referer', 'x-forwarded-for', 'cookie'];
+
+module.exports = {
+  SQL_PATTERNS,
+  XSS_PATTERNS,
+  NOSQL_DANGEROUS_OPERATORS,
+  NOSQL_SUSPICIOUS_OPERATORS,
+  NOSQL_STRING_PATTERNS,
+  SENSITIVE_HEADERS,
+};

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@roboteby/parry",
+  "version": "1.1.0-rc.1",
+  "description": "Application-layer security middleware for Express.js with injection detection, abuse mitigation, brute-force protection and distributed rate limiting.",
+  "main": "./src/index.js",
+  "types": "./types/index.d.ts",
+  "scripts": {
+    "test": "node tests/index.js",
+    "test:unit": "node -e \"(async()=>{ await require('./tests/unit/detectors.test'); await require('./tests/unit/rateLimiter.test'); await require('./tests/unit/memoryStore.test'); await require('./tests/unit/redisStore.test'); await require('./tests/unit/policyMatcher.test'); await require('./tests/unit/keyBuilder.test'); await require('./tests/unit/bruteForceGuard.test'); await require('./tests/unit/engine.test'); await require('./tests/unit/applicationGuards.test'); await require('./tests/unit/observability.test'); await require('./tests/unit/adminAuth.test'); })().catch((err)=>{ console.error(err); process.exit(1); })\"",
+    "test:integ": "node tests/integration/middleware.test.js",
+    "test:fixtures": "node scripts/payloads/validate-fixtures.js",
+    "test:payload-regression": "node tests/regression/index.js",
+    "test:payload-report": "node scripts/payloads/generate-payload-report.js",
+    "package:check": "node scripts/package/check-package.js",
+    "package:check-tag": "node scripts/package/check-version-tag.js",
+    "package:dry-run": "npm pack --dry-run",
+    "example": "node examples/express-basic.js",
+    "test:http": "node scripts/run-tests.js",
+    "start:test": "node scripts/test-server.js",
+    "docker:build:demo": "docker build -f docker/demo-api/Dockerfile -t parry-demo-api .",
+    "format": "prettier --write \"src/**/*.js\"",
+    "format:check": "prettier --check \"src/**/*.js\""
+  },
+  "exports": {
+    ".": {
+      "require": "./src/index.js",
+      "types": "./types/index.d.ts"
+    },
+    "./core": "./src/core/index.js",
+    "./detectors": "./src/detectors/index.js",
+    "./stores": "./src/stores/index.js",
+    "./policies": "./src/policies/index.js",
+    "./brute-force": "./src/brute-force/index.js",
+    "./events": "./src/events/index.js",
+    "./observability": "./src/observability/index.js",
+    "./admin": "./src/admin/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "config",
+    "constants",
+    "types",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "package.json"
+  ],
+  "keywords": [
+    "express",
+    "middleware",
+    "security",
+    "application-security",
+    "appsec",
+    "rate-limit",
+    "brute-force",
+    "xss",
+    "sql-injection",
+    "nosql-injection",
+    "redis",
+    "nodejs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/RobotEby/parry-express-security-middleware.git"
+  },
+  "bugs": {
+    "url": "https://github.com/RobotEby/parry-express-security-middleware/issues"
+  },
+  "homepage": "https://github.com/RobotEby/parry-express-security-middleware#readme",
+  "peerDependencies": {
+    "express": "^5.2.1"
+  },
+  "devDependencies": {
+    "eslint-config-prettier": "^10.1.8",
+    "express": "^5.2.1",
+    "prettier": "^3.8.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "ipaddr.js": "^2.4.0"
+  }
+}

package/src/admin/admin-router.js

@@ -0,0 +1,106 @@
+'use strict';
+
+const express = require('express');
+const pkg = require('../../package.json');
+const { requireAdminAuth } = require('./auth');
+const { ok, notFound } = require('./response');
+const { listAdminBanEntries } = require('./ban-normalizer');
+const { describeStore, sanitizePolicies } = require('../observability');
+
+function createParryAdminRouter(parry, options = {}) {
+  const context = resolveParryContext(parry);
+  if (!context) {
+    throw new Error('createParryAdminRouter requires a Parry instance or middleware.');
+  }
+
+  const router = express.Router();
+  router.use(requireAdminAuth(options, context));
+
+  router.get('/health', (_req, res) =>
+    ok(res, {
+      ok: true,
+      name: 'parry',
+      version: pkg.version,
+      uptimeMs: context.metrics.snapshot().uptimeMs,
+      store: describeStore(context.store),
+    })
+  );
+
+  router.get(
+    '/metrics',
+    asyncRoute(async (_req, res) => {
+      const activeBans = (await listAdminBanEntries(context.store)).length;
+      return ok(res, context.metrics.snapshot({ activeBans }));
+    })
+  );
+
+  router.get('/events', (req, res) => {
+    const result = context.eventBus.getRecentEvents({
+      limit: req.query.limit,
+      offset: req.query.offset,
+      type: req.query.type,
+      severity: req.query.severity,
+      action: req.query.action,
+      detector: req.query.detector,
+      ip: req.query.ip,
+      path: req.query.path,
+      policyName: req.query.policyName,
+    });
+    return ok(res, result);
+  });
+
+  router.get('/events/:id', (req, res) => {
+    const event = context.eventBus.getEventById(req.params.id);
+    if (!event) return notFound(res);
+    return ok(res, event);
+  });
+
+  router.get(
+    '/bans',
+    asyncRoute(async (req, res) => {
+      const data = await listAdminBanEntries(context.store, req.query);
+      return ok(res, paginateList(data, req.query));
+    })
+  );
+
+  router.get('/policies', (req, res) =>
+    ok(res, paginateList(sanitizePolicies(context.policies || []), req.query))
+  );
+
+  return router;
+}
+
+function resolveParryContext(parry) {
+  if (!parry) return null;
+  if (typeof parry.getContext === 'function') return parry.getContext();
+  if (parry.__parryContext) return parry.__parryContext;
+  return null;
+}
+
+function paginateList(data, query = {}) {
+  const limit = clampNumber(query.limit, 50, 1, 500);
+  const offset = clampNumber(query.offset, 0, 0, data.length);
+
+  return {
+    data: data.slice(offset, offset + limit),
+    pagination: {
+      limit,
+      offset,
+      total: data.length,
+    },
+  };
+}
+
+function clampNumber(value, fallback, min, max) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.min(max, Math.max(min, Math.floor(parsed)));
+}
+
+function asyncRoute(handler) {
+  return function routeHandler(req, res, next) {
+    Promise.resolve(handler(req, res, next)).catch(next);
+  };
+}
+
+module.exports = { createParryAdminRouter, resolveParryContext };