@roboteby/parry 1.1.1 → 2.0.1

package/CHANGELOG.md

@@ -1,33 +1,66 @@
 # 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.
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/) and the project follows Semantic
+Versioning for public APIs and documented runtime behavior.
 
 ## [Unreleased]
 
+## [2.0.0] - 2026-09-01
+
+### Added
+
+- Added exact-path NoSQL operator allowlists through
+  `nosql.allowedOperators`, configurable scalar header scanning, internal option
+  validation, typed advanced subpaths, TypeScript declaration tests, and 75
+  benign false-positive controls.
+- Added security, contribution, issue, pull-request, testing, deployment,
+  architecture, and release guidance.
+
+### Changed
+
+- Raised the minimum supported Node.js version from `>=18` to `>=22`. The package
+  remains CommonJS and keeps Express `^5.2.1` as its peer dependency.
+- Made `createParry` and `ParryOptions` the recommended API names while retaining
+  every existing public export and the deprecated `Parry_DDoS`/
+  `Parry_DDoSOptions` aliases.
+- Reordered scanning so Request Shape runs first, structured guards inspect each
+  surface once, scalar leaves are serialized once, duplicate findings are
+  removed, and aggregate severity uses the most severe finding.
+- Resolved trusted proxy chains from right to left and changed generated request
+  IDs to `req_${crypto.randomUUID()}`.
+- Migrated tests to `node:test`/`node:assert`, ESLint flat configuration, full
+  Prettier checks, GitHub Actions npm publishing with provenance, and an optional
+  Terraform example under `infra/examples/aws`.
+- Updated repository metadata and links to `RobotEby/parry`.
+
+### Security
+
+- **Breaking change:** `createParryAdminRouter` no longer permits
+  anonymous access by default. It fails during construction unless real auth is
+  configured or insecure access is explicitly selected outside production.
+- In production, `allowInsecureAdminApi`, `auth.mode: "none"`, and legacy
+  `requireAuth: false` are always rejected. Empty tokens and invalid IP/CIDR
+  boundaries are rejected, and `verifyJwt: true` continues to fail explicitly.
+- Removed stale monitor-only fixtures for Command Injection and SSRF because
+  Parry does not implement those detectors.
+
+## [1.1.1] - 2026-07-02
+
+### Changed
+
+- Published `@roboteby/parry@1.1.1` to the stable `latest` npm dist-tag.
+
 ## [1.1.0-rc.1] - 2026-07-02
 
 ### Added
 
-- Published the first npm release candidate as `@roboteby/parry@1.1.0-rc.1`
-  under the `rc` dist-tag.
-- Documented the release candidate installation path with
-  `npm install @roboteby/parry@rc`.
-- Added package hardening, release workflow documentation, and package tarball
-  validation scripts.
-- Included the current application-layer protection surface: route policies,
-  distributed rate limiting, BruteForceGuard, Threat Events, metrics, and the
-  read-only Admin API.
-- Added documentation for Admin API authentication modes, payload regression
-  testing, Docker demo usage, AWS reference infrastructure, and CI/CD.
+- Published the first release candidate under the `rc` npm dist-tag.
+- Added route policies, distributed rate limiting, brute-force protection,
+  Threat Events, metrics, the read-only Admin API, Docker demonstration, and AWS
+  reference infrastructure.
 
 ### Security
 
-- Documented npm publishing and supply-chain hardening with Trusted
-  Publishing/OIDC.
 - Clarified that Parry is application-layer Express middleware and does not
-  replace CloudFront, AWS WAF, Shield, Cloudflare, CDN, ALB, or edge-layer
-  volumetric DDoS protection.
+  replace CDN/WAF, load-balancer, or volumetric DDoS controls.

package/README.md

@@ -1,299 +1,160 @@
 # Parry
 
-[![npm rc version](https://img.shields.io/npm/v/@roboteby/parry/rc?label=npm%20rc)](https://www.npmjs.com/package/@roboteby/parry)
-[![license](https://img.shields.io/npm/l/@roboteby/parry)](https://github.com/RobotEby/parry-express-security-middleware/blob/main/LICENSE)
+[![npm version](https://img.shields.io/npm/v/@roboteby/parry)](https://www.npmjs.com/package/@roboteby/parry)
+[![license](https://img.shields.io/npm/l/@roboteby/parry)](./LICENSE)
 [![node](https://img.shields.io/node/v/@roboteby/parry)](https://www.npmjs.com/package/@roboteby/parry)
 
-Application-layer security middleware for Express.js.
+Application-layer security middleware for Express that combines abuse detection,
+request guards, rate limiting, brute-force protection and security observability.
 
-## Overview
+The current stable release is `@roboteby/parry@2.0.0` on the npm `latest`
+dist-tag.
 
-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
+## Install
 
 ```bash
-npm install @roboteby/parry@rc
+npm install @roboteby/parry express@^5.2.1
 ```
 
-Parry expects Express to be installed by your application.
-
-## Release Candidate
+Parry 2 requires Node.js `>=22` and Express `^5.2.1`.
 
-`@roboteby/parry@1.1.0-rc.1` is published on npm under the `rc` tag for validation before promotion to the stable `latest` channel. Use `npm install @roboteby/parry@rc` to test the release candidate, review detector behavior and Admin API configuration in your environment, and pin the exact version if you need reproducible rollout testing.
-
-## Quick Start
+## Minimal example
 
 ```js
 const express = require('express');
 const { createParry } = require('@roboteby/parry');
 
 const app = express();
+app.use(express.json({ limit: '64kb' }));
 
-const parry = createParry({
-  preset: 'recommended',
-});
-
-app.use(express.json());
+const parry = createParry({ preset: 'recommended' });
 app.use(parry.middleware());
 
-app.get('/health', (_req, res) => {
-  res.json({ ok: true });
-});
-
+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
+Body parsers must run before Parry when request bodies should be inspected.
+Mount Parry before the routes it protects.
 
-Parry supports conservative presets for common application-layer protection:
+## Main capabilities
 
-- `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.
+- Request Shape limits for depth, key count, array length and string length.
+- Heuristic SQL injection and XSS detection, plus NoSQL operator guards.
+- HTTP parameter pollution, prototype pollution and path traversal guards.
+- Global and route-specific rate limiting.
+- Brute-force counters and temporary blocks for authentication routes.
+- Sanitized Threat Events, process-local metrics and an optional read-only Admin
+  API.
+- In-memory state by default, with an optional `RedisStore` for shared protection
+  state.
 
-Every option can still be configured explicitly. Prefer starting with `recommended`, reviewing logs and events, then tightening route policies where needed.
+## Security boundaries
 
-## Stores
+Parry is a defense-in-depth control for the Express application layer. It is not
+a WAF and does not replace a CDN, reverse proxy, load balancer or volumetric
+L3/L4 DDoS protection. It also does not replace authentication, authorization,
+schema validation, parameterized queries, context-aware escaping/output
+encoding or CSP.
 
-`MemoryStore` is the default store. It is suitable for tests, demos, local development, and single-process deployments.
+SQLi and XSS detection is heuristic, so false positives and false negatives are
+possible. Request Shape runs before heavier scans to bound their cost, but an
+allowed request is not proof that its input is safe for downstream use.
 
-For distributed deployments, use `RedisStore` with a Redis client created by your application:
+Trusted proxy handling depends on narrow, correct `trustedProxies`
+configuration. See the [security model](./docs/security-model.md) before enabling
+forwarded-header trust.
 
-```js
-const { createClient } = require('redis');
-const { createParry, RedisStore } = require('@roboteby/parry');
+## Public API
 
-const redis = createClient({ url: process.env.REDIS_URL });
-await redis.connect();
+The recommended root exports are:
 
-const parry = createParry({
-  store: new RedisStore({ client: redis, prefix: 'parry' }),
-  rateLimit: {
-    enabled: true,
-    max: 100,
-    windowMs: 60_000,
-    headers: true,
-  },
-});
-```
+- `createParry(options)` — creates the middleware and its observability context.
+- `createParryAdminRouter(parry, options)` — creates the optional Admin router.
+- `MemoryStore` — keeps protection state in one process.
+- `RedisStore` — uses an application-owned Redis client for shared protection
+  state.
 
-If your service runs behind multiple instances, containers, or load balancers, use a shared store. `MemoryStore` protects only the current Node.js process.
+Existing exports remain available. `Parry_DDoS(options)` is a deprecated
+compatibility wrapper around `createParry(options).middleware()`, and
+`Parry_DDoSOptions` is a deprecated TypeScript alias for `ParryOptions`.
 
-## Brute-Force Protection
+Advanced typed exports are available from `/core`, `/detectors`, `/stores`,
+`/policies`, `/brute-force`, `/events`, `/observability` and `/admin`.
 
-Route policies can protect sensitive authentication endpoints without making the global rate limit too aggressive:
+## Admin API
 
-```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:
+The Admin API exposes health, process metrics, recent sanitized events, active
+bans and normalized policies. It is never mounted automatically and fails during
+construction unless authentication is configured:
 
 ```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 });
-});
-```
+const { createParryAdminRouter } = require('@roboteby/parry');
 
-## 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,
+app.use(
+  '/_parry',
+  createParryAdminRouter(parry, {
     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`
+Anonymous Admin access is an explicit local-development opt-in and is rejected
+in production. External identity modes depend on a configured trusted boundary;
+Parry does not perform cryptographic JWT/JWKS verification, and `verifyJwt: true`
+fails explicitly.
 
-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.
+See [Admin API](./docs/admin-api.md) for authentication modes and deployment
+guidance.
 
-## Parry Security Console
+## Redis
 
-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.
+The application creates and connects the Redis client. Parry does not install or
+own a Redis package implicitly.
 
-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
+```js
+const { createClient } = require('redis');
+const { createParry, RedisStore } = require('@roboteby/parry');
 
-curl http://localhost:3000/_parry/health \
-  -H "x-parry-admin-token: change-me"
+const client = createClient({ url: process.env.REDIS_URL });
+await client.connect();
 
-curl -X POST http://localhost:3000/echo \
-  -H "Content-Type: application/json" \
-  -d '{"message":"hello"}'
+const parry = createParry({
+  store: new RedisStore({ client, prefix: 'parry' }),
+  storeFailureMode: 'fail-closed',
+});
 ```
 
-The `change-me` token is for local demos only.
-
-## cURL Guide
-
-The demo API can be validated with a set of local cURL examples covering health checks, Admin API authentication, Threat Events, brute-force blocks, active bans, CORS, request IDs, and frontend proxy checks.
-
-See [docs/curl-guide.md](https://github.com/RobotEby/parry-express-security-middleware/blob/main/docs/curl-guide.md).
-
-## 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.
+`RedisStore` shares rate-limit state, brute-force state, counters and related
+bans/blocks across instances. Threat Events, the default event buffer and
+metrics remain local to each process unless the application exports them.
 
-Production deployments should account for:
+## Runtime support
 
-- 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.
+- Node.js `>=22`
+- Express `^5.2.1`
+- CommonJS
 
-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.
+CI covers Node.js 22 and 24. Parry 2 does not imply or announce an ESM migration.
 
 ## 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)
-- [cURL guide](https://github.com/RobotEby/parry-express-security-middleware/blob/main/docs/curl-guide.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:
+- [Configuration](./docs/configuration.md)
+- [Security model](./docs/security-model.md)
+- [Admin API](./docs/admin-api.md)
+- [Deployment](./docs/deployment.md)
+- [Testing](./docs/testing.md)
+- [Architecture](./docs/architecture.md)
+- [Releasing](./docs/releasing.md)
+- [OpenAPI contract](./docs/openapi/parry-admin-api.yaml)
+- [Generated payload regression report](./docs/payload-regression-report.md)
 
-- 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
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the development workflow and
+[SECURITY.md](./SECURITY.md) for vulnerability reporting.
 
 ## License
 
-MIT
+[MIT](./LICENSE)

package/config/defaults.js

@@ -50,6 +50,9 @@ const DEFAULTS = {
   },
   trustProxyHeaders: false,
   trustedProxies: [],
+  headers: {
+    scan: ['user-agent', 'referer', 'x-forwarded-for', 'cookie'],
+  },
   debug: false,
 
   suspiciousThreshold: 5,
@@ -59,7 +62,7 @@ const DEFAULTS = {
 
   onThreat: null,
 
-  maxObjectDepth: 5,
+  maxObjectDepth: 8,
 };
 
 module.exports = { DEFAULTS };