@roboteby/parry 1.1.0-rc.1 → 2.0.0

package/CHANGELOG.md

@@ -1,19 +1,64 @@
 # 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
+
+- 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 9 flat configuration, full
+  Prettier checks, Node 18/20/22/24 CI, OIDC-only npm publishing, and an optional
+  Terraform example under `infra/examples/aws`.
+- Updated repository metadata and links to `RobotEby/parry`.
+
+### Security
+
+- **Intentional breaking behavior:** `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 1.x 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
 
-- Release workflow preparation.
-- npm package hardening.
-- Package tarball validation scripts.
+- 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 CDN/WAF, load-balancer, or volumetric DDoS controls.

package/README.md

@@ -1,284 +1,148 @@
-# parry-express-security-middleware
+# Parry
 
-Application-layer security middleware for Express.js.
+[![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)
 
-## Overview
+Application-layer security middleware for Express 5.
 
-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 combines request-shape limits, heuristic SQL injection/XSS/NoSQL checks,
+HTTP parameter pollution and prototype/path traversal guards with rate limiting,
+route policies, brute-force protection, sanitized Threat Events, and an optional
+read-only Admin API. It is CommonJS and has no mandatory Redis dependency.
 
-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.
+The stable npm release is `1.1.1` on `latest`. The earlier `1.1.0-rc.1` remains
+available on the `rc` dist-tag; it is not the recommended installation.
 
-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
 ```
 
-Parry expects Express to be installed by your application.
-
-## Quick Start
+Express `^5.2.1` is a peer dependency.
 
 ```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
-
-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();
+Body parsers must run before Parry if request bodies should be inspected. Mount
+Parry before the routes it protects.
 
-const parry = createParry({
-  store: new RedisStore({ client: redis, prefix: 'parry' }),
-  rateLimit: {
-    enabled: true,
-    max: 100,
-    windowMs: 60_000,
-    headers: true,
-  },
-});
-```
+## Security boundaries
 
-If your service runs behind multiple instances, containers, or load balancers, use a shared store. `MemoryStore` protects only the current Node.js process.
+Parry is one application-layer control. It does not replace validation and
+parameterized queries in the application, output encoding and CSP in the browser,
+authentication/authorization, a reverse proxy, CDN/WAF, load balancer, or
+volumetric L3/L4 DDoS protection.
 
-## Brute-Force Protection
+SQLi and XSS detection is heuristic. The patterns are intentionally bounded and
+the Request Shape guard runs before heavier scans, but applications still need
+tests for their own traffic and false-positive profile. A clean Parry decision is
+not proof that input is safe for every downstream interpreter.
 
-Route policies can protect sensitive authentication endpoints without making the global rate limit too aggressive:
+When `MemoryStore` is used, counters and bans exist only inside one Node.js
+process. `RedisStore` shares rate-limit and brute-force state across instances.
+Threat Events, the in-memory event buffer, and metrics remain local to each
+process unless the application exports them through `onEvent` or another
+observability integration.
 
-```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,
-      },
-    },
-  ],
-});
-```
+See [the security model](./docs/security-model.md) and [configuration](./docs/configuration.md).
 
-Routes can also report authentication outcomes manually:
+## Public API
 
-```js
-app.post('/login', async (req, res) => {
-  const user = await authService.validate(req.body.email, req.body.password);
+The four recommended stable exports are:
 
-  if (!user) {
-    req.parry?.recordAuthFailure('invalid_credentials');
-    return res.status(200).json({ success: false });
-  }
+- `createParry(options)` — create a middleware instance and observability context;
+- `createParryAdminRouter(parry, options)` — create the optional read-only Admin router;
+- `MemoryStore` — single-process state store;
+- `RedisStore` — adapter for an application-owned Redis client.
 
-  req.parry?.recordAuthSuccess();
-  return res.json({ success: true });
-});
-```
+All existing exports remain available. `Parry_DDoS(options)` is deprecated but
+kept as a compatibility wrapper around `createParry(options).middleware()`.
+`Parry_DDoSOptions` remains a deprecated TypeScript alias for `ParryOptions`.
 
-## Threat Events and Admin API
+Advanced APIs have typed subpaths: `/core`, `/detectors`, `/stores`, `/policies`,
+`/brute-force`, `/events`, `/observability`, and `/admin`.
 
-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.
+## Admin API is fail-closed
 
-The optional Admin API is read-only and is never mounted automatically:
+The Admin router now throws during construction when no authentication strategy
+is configured:
 
 ```js
-const { createParry, createParryAdminRouter } = require('@roboteby/parry');
+const { 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:
+`allowInsecureAdminApi: true`, `auth.mode: 'none'`, and the legacy
+`requireAuth: false` alias are explicit local-development opt-ins. They warn and
+are rejected whenever `NODE_ENV=production`, even if an override is present.
+An empty token is invalid. External Cloudflare/ALB modes validate a trusted
+boundary but do not pretend that decoding a JWT is cryptographic verification;
+`verifyJwt: true` fails explicitly in this 1.x implementation.
 
-- `GET /_parry/health`
-- `GET /_parry/metrics`
-- `GET /_parry/events`
-- `GET /_parry/events/:id`
-- `GET /_parry/bans`
-- `GET /_parry/policies`
+Full configuration and deployment patterns are in [Admin API](./docs/admin-api.md).
 
-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.
+## Redis
 
-## Parry Security Console
+Create and connect the Redis client in the application; Parry never installs or
+owns a Redis package implicitly.
 
-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
+```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.
-
-## 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.
+## Runtime support
 
-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.
+The 1.x package keeps `engines.node >=18` and CI covers Node 18, 20, 22, and 24.
+Node 18 and 20 are legacy/EOL compatibility targets. Use Node 22 or 24 for new
+production deployments. Raising the minimum to Node 22 is reserved for v2. See
+the [official Node.js release schedule](https://nodejs.org/en/about/previous-releases).
 
 ## 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:
+- [Configuration](./docs/configuration.md)
+- [Security model](./docs/security-model.md)
+- [Admin API](./docs/admin-api.md)
+- [Testing](./docs/testing.md)
+- [Deployment](./docs/deployment.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 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 };