@roboteby/parry 1.1.0-rc.1 → 2.0.0

package/config/validate.js

@@ -0,0 +1,255 @@
+'use strict';
+
+const ipaddr = require('ipaddr.js');
+const { NOSQL_DANGEROUS_OPERATORS, NOSQL_SUSPICIOUS_OPERATORS } = require('../constants/patterns');
+
+const HEADER_NAME_PATTERN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const NOSQL_PATH_PATTERN = /^(?:body|query|params)(?:\.|\[|$)/;
+
+function assertObject(value, name) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError(`${name} must be an object`);
+  }
+}
+
+function assertPositive(value, name, { integer = false, allowZero = false } = {}) {
+  if (value === undefined) return;
+  if (
+    typeof value !== 'number' ||
+    !Number.isFinite(value) ||
+    (integer && !Number.isInteger(value)) ||
+    (allowZero ? value < 0 : value <= 0)
+  ) {
+    throw new TypeError(
+      `${name} must be a ${allowZero ? 'non-negative' : 'positive'}${integer ? ' integer' : ' number'}`
+    );
+  }
+}
+
+function validateIpOrCidr(value, name) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new TypeError(`${name} must be a non-empty IP address or CIDR`);
+  }
+
+  try {
+    if (value.includes('/')) ipaddr.parseCIDR(value);
+    else ipaddr.parse(value);
+  } catch {
+    throw new TypeError(`${name} contains an invalid IP address or CIDR: ${value}`);
+  }
+}
+
+function validateTrustedProxies(value, name = 'trustedProxies') {
+  if (value === undefined) return;
+  if (!Array.isArray(value)) throw new TypeError(`${name} must be an array`);
+  value.forEach((entry, index) => validateIpOrCidr(entry, `${name}[${index}]`));
+}
+
+function normalizeHeadersConfig(value) {
+  const defaultHeaders = ['user-agent', 'referer', 'x-forwarded-for', 'cookie'];
+  if (value === undefined) return { scan: defaultHeaders };
+  assertObject(value, 'headers');
+  const scan = value.scan === undefined ? defaultHeaders : value.scan;
+  if (!Array.isArray(scan)) throw new TypeError('headers.scan must be an array');
+
+  const normalized = [];
+  const seen = new Set();
+  for (const header of scan) {
+    validateHeaderName(header, 'headers.scan');
+    const name = header.toLowerCase();
+    if (!seen.has(name)) {
+      seen.add(name);
+      normalized.push(name);
+    }
+  }
+  return { scan: normalized };
+}
+
+function validateHeaderName(value, name = 'header') {
+  if (typeof value !== 'string' || !HEADER_NAME_PATTERN.test(value)) {
+    throw new TypeError(`${name} contains an invalid header name: ${String(value)}`);
+  }
+}
+
+function normalizeNoSQLConfig(value) {
+  if (value === undefined) return { enabled: true, allowedOperators: {} };
+  if (typeof value === 'boolean') return { enabled: value, allowedOperators: {} };
+  assertObject(value, 'nosql');
+
+  if (value.enabled !== undefined && typeof value.enabled !== 'boolean') {
+    throw new TypeError('nosql.enabled must be a boolean');
+  }
+  const allowedOperators = value.allowedOperators || {};
+  assertObject(allowedOperators, 'nosql.allowedOperators');
+
+  const normalized = Object.create(null);
+  for (const [path, operators] of Object.entries(allowedOperators)) {
+    if (!NOSQL_PATH_PATTERN.test(path)) {
+      throw new TypeError(`nosql.allowedOperators contains an invalid exact path: ${path}`);
+    }
+    if (!Array.isArray(operators)) {
+      throw new TypeError(`nosql.allowedOperators.${path} must be an array`);
+    }
+
+    normalized[path] = [];
+    const seen = new Set();
+    for (const operator of operators) {
+      if (typeof operator !== 'string' || !operator.startsWith('$')) {
+        throw new TypeError(`nosql.allowedOperators.${path} contains an invalid operator`);
+      }
+      if (NOSQL_DANGEROUS_OPERATORS.has(operator)) {
+        throw new TypeError(`NoSQL operator ${operator} can never be allowlisted`);
+      }
+      if (!NOSQL_SUSPICIOUS_OPERATORS.has(operator)) {
+        throw new TypeError(`Only suspicious NoSQL operators may be allowlisted: ${operator}`);
+      }
+      if (!seen.has(operator)) {
+        seen.add(operator);
+        normalized[path].push(operator);
+      }
+    }
+  }
+
+  return {
+    enabled: value.enabled !== false,
+    allowedOperators: normalized,
+  };
+}
+
+function validateRateConfig(rate, name) {
+  if (rate === undefined) return;
+  assertObject(rate, name);
+  assertPositive(rate.maxRequests, `${name}.maxRequests`, { integer: true });
+  assertPositive(rate.windowMs, `${name}.windowMs`, { integer: true });
+}
+
+function validateMatch(match, name) {
+  assertObject(match, name);
+  if (match.method === undefined && match.path === undefined) {
+    throw new TypeError(`${name} must define method or path`);
+  }
+  const validateList = (value, field, validateEntry) => {
+    const values = Array.isArray(value) ? value : [value];
+    if (values.length === 0 || values.some((entry) => !validateEntry(entry))) {
+      throw new TypeError(`${name}.${field} is invalid`);
+    }
+  };
+  if (match.method !== undefined) {
+    validateList(
+      match.method,
+      'method',
+      (entry) => typeof entry === 'string' && entry.trim() !== ''
+    );
+  }
+  if (match.path !== undefined) {
+    validateList(
+      match.path,
+      'path',
+      (entry) => entry instanceof RegExp || (typeof entry === 'string' && entry.trim() !== '')
+    );
+  }
+}
+
+function validateParryOptions(options) {
+  if (options === undefined) return;
+  assertObject(options, 'options');
+
+  assertPositive(options.maxRequests, 'maxRequests', { integer: true });
+  assertPositive(options.windowMs, 'windowMs', { integer: true });
+  assertPositive(options.banDurationMs, 'banDurationMs', { integer: true });
+  assertPositive(options.suspiciousThreshold, 'suspiciousThreshold', { integer: true });
+  assertPositive(options.maxObjectDepth, 'maxObjectDepth', { integer: true, allowZero: true });
+  if (options.rateLimit && typeof options.rateLimit === 'object') {
+    assertPositive(options.rateLimit.max, 'rateLimit.max', { integer: true });
+    assertPositive(options.rateLimit.maxRequests, 'rateLimit.maxRequests', { integer: true });
+    assertPositive(options.rateLimit.windowMs, 'rateLimit.windowMs', { integer: true });
+  }
+
+  if (options.requestShape !== undefined) {
+    assertObject(options.requestShape, 'requestShape');
+    assertPositive(options.requestShape.maxDepth, 'requestShape.maxDepth', {
+      integer: true,
+      allowZero: true,
+    });
+    assertPositive(options.requestShape.maxKeys, 'requestShape.maxKeys', { integer: true });
+    assertPositive(options.requestShape.maxArrayLength, 'requestShape.maxArrayLength', {
+      integer: true,
+    });
+    assertPositive(options.requestShape.maxStringLength, 'requestShape.maxStringLength', {
+      integer: true,
+    });
+  }
+
+  if (options.events !== undefined) {
+    assertObject(options.events, 'events');
+    assertPositive(options.events.maxEvents, 'events.maxEvents', { integer: true });
+  }
+
+  if (options.requestId !== undefined) {
+    assertObject(options.requestId, 'requestId');
+    if (options.requestId.header !== undefined) {
+      validateHeaderName(options.requestId.header, 'requestId.header');
+    }
+    if (
+      options.requestId.responseHeader !== undefined &&
+      options.requestId.responseHeader !== false
+    ) {
+      validateHeaderName(options.requestId.responseHeader, 'requestId.responseHeader');
+    }
+  }
+
+  if (options.admin !== undefined) {
+    assertObject(options.admin, 'admin');
+    if (options.admin.path !== undefined && !String(options.admin.path).startsWith('/')) {
+      throw new TypeError('admin.path must start with /');
+    }
+  }
+
+  if (options.bruteForce !== undefined) {
+    assertObject(options.bruteForce, 'bruteForce');
+  }
+
+  if (options.policies !== undefined) {
+    if (!Array.isArray(options.policies)) throw new TypeError('policies must be an array');
+    options.policies.forEach((policy, index) => {
+      assertObject(policy, `policies[${index}]`);
+      if (typeof policy.name !== 'string' || policy.name.trim() === '') {
+        throw new TypeError(`policies[${index}].name must be a non-empty string`);
+      }
+      validateMatch(policy.match, `policies[${index}].match`);
+      validateRateConfig(policy.rateLimit, `policies[${index}].rateLimit`);
+      if (policy.rateLimit) {
+        assertPositive(policy.rateLimit.max, `policies[${index}].rateLimit.max`, {
+          integer: true,
+        });
+      }
+      if (policy.bruteForce) {
+        assertObject(policy.bruteForce, `policies[${index}].bruteForce`);
+        assertPositive(policy.bruteForce.maxAttempts, `policies[${index}].bruteForce.maxAttempts`, {
+          integer: true,
+        });
+        assertPositive(policy.bruteForce.windowMs, `policies[${index}].bruteForce.windowMs`, {
+          integer: true,
+        });
+        assertPositive(
+          policy.bruteForce.blockDurationMs,
+          `policies[${index}].bruteForce.blockDurationMs`,
+          { integer: true }
+        );
+      }
+    });
+  }
+
+  validateTrustedProxies(options.trustedProxies);
+  normalizeHeadersConfig(options.headers);
+  normalizeNoSQLConfig(options.nosql);
+}
+
+module.exports = {
+  normalizeHeadersConfig,
+  normalizeNoSQLConfig,
+  validateHeaderName,
+  validateIpOrCidr,
+  validateParryOptions,
+  validateTrustedProxies,
+};

package/constants/patterns.js

@@ -17,8 +17,7 @@ const SQL_PATTERNS = [
 ];
 
 const XSS_PATTERNS = [
-  /<\s*script[\s\S]*?>[\s\S]*?<\s*\/\s*script\s*>/i,
-  /<\s*script\b[^>]*>/i,
+  /<\s*script\b[^>]{0,500}>/i,
   /\bon\w+\s*=\s*["']?[^"'>]*/i,
   /javascript\s*:/i,
   /vbscript\s*:/i,
@@ -27,8 +26,8 @@ const XSS_PATTERNS = [
   /<\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}\}/,
+  /\{\{[^{}]{0,200}(?:constructor(?:\.constructor)?|alert\s*\(|document\.|window\.)[^{}]{0,200}\}\}/i,
+  /\$\{[^{}]{0,200}(?:constructor(?:\.constructor)?|alert\s*\(|document\.|window\.)[^{}]{0,200}\}/i,
   /<\s*(base|link|meta|style)\b[^>]*(http-equiv|href|content)\s*=\s*["']?[^"'>]*script/i,
   /\0|%00/,
   /autofocus.{0,30}onfocus/i,

package/package.json

@@ -1,39 +1,65 @@
 {
   "name": "@roboteby/parry",
-  "version": "1.1.0-rc.1",
+  "version": "2.0.0",
   "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": "node --test tests/unit/*.test.js tests/integration/*.test.js tests/package/*.test.js",
+    "test:unit": "node --test tests/unit/*.test.js",
+    "test:integration": "node --test tests/integration/*.test.js",
+    "test:integ": "npm run test:integration",
+    "test:package": "node --test tests/package/*.test.js",
+    "test:types": "tsc -p tests/types/tsconfig.json",
     "test:fixtures": "node scripts/payloads/validate-fixtures.js",
-    "test:payload-regression": "node tests/regression/index.js",
+    "test:payload-regression": "node --test tests/regression/*.test.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\""
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
   },
   "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",
+    "./core": {
+      "require": "./src/core/index.js",
+      "types": "./types/core.d.ts"
+    },
+    "./detectors": {
+      "require": "./src/detectors/index.js",
+      "types": "./types/detectors.d.ts"
+    },
+    "./stores": {
+      "require": "./src/stores/index.js",
+      "types": "./types/stores.d.ts"
+    },
+    "./policies": {
+      "require": "./src/policies/index.js",
+      "types": "./types/policies.d.ts"
+    },
+    "./brute-force": {
+      "require": "./src/brute-force/index.js",
+      "types": "./types/brute-force.d.ts"
+    },
+    "./events": {
+      "require": "./src/events/index.js",
+      "types": "./types/events.d.ts"
+    },
+    "./observability": {
+      "require": "./src/observability/index.js",
+      "types": "./types/observability.d.ts"
+    },
+    "./admin": {
+      "require": "./src/admin/index.js",
+      "types": "./types/admin.d.ts"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -66,24 +92,29 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+ssh://git@github.com/RobotEby/parry-express-security-middleware.git"
+    "url": "git+https://github.com/RobotEby/parry.git"
   },
   "bugs": {
-    "url": "https://github.com/RobotEby/parry-express-security-middleware/issues"
+    "url": "https://github.com/RobotEby/parry/issues"
   },
-  "homepage": "https://github.com/RobotEby/parry-express-security-middleware#readme",
+  "homepage": "https://github.com/RobotEby/parry#readme",
   "peerDependencies": {
     "express": "^5.2.1"
   },
   "devDependencies": {
-    "eslint-config-prettier": "^10.1.8",
+    "@eslint/js": "^10.0.1",
+    "@types/express": "^5.0.6",
+    "@types/node": "^26.4.0",
+    "eslint": "^10.9.1",
     "express": "^5.2.1",
-    "prettier": "^3.8.1"
+    "globals": "^17.11.0",
+    "prettier": "^3.9.6",
+    "typescript": "^7.0.2"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "dependencies": {
-    "ipaddr.js": "^2.4.0"
+    "ipaddr.js": "^2.5.0"
   }
 }

package/src/admin/auth/admin-auth.js

@@ -5,27 +5,59 @@ const { authenticateToken } = require('./strategies/token');
 const { authenticateIpAllowlist } = require('./strategies/ip-allowlist');
 const { authenticateTrustedProxy } = require('./strategies/trusted-proxy');
 const { authenticateCombined } = require('./strategies/combined');
-const { authenticateNone } = require('./strategies/none');
+const { authenticateNone, warnInsecureAdminApi } = require('./strategies/none');
 const { authenticateCloudflareAccess } = require('./strategies/cloudflare-access');
 const { authenticateAlbAuth } = require('./strategies/alb-auth');
+const { validateHeaderName, validateTrustedProxies } = require('../../../config/validate');
+
+const SUPPORTED_MODES = new Set([
+  'token',
+  'ip-allowlist',
+  'trusted-proxy',
+  'cloudflare-access',
+  'alb-auth',
+  'cognito-alb',
+  'combined',
+  'none',
+]);
 
 function requireAdminAuth(options = {}, context = null) {
   if (typeof options.auth === 'function') return createLegacyCallbackMiddleware(options.auth);
 
-  if (options.requireAuth && !options.auth) {
+  const contextAuth = context?.config?.admin?.auth;
+  const authConfig = isAuthConfig(options.auth) ? options.auth : contextAuth;
+  if (authConfig) {
+    return createAdminAuthMiddleware(authConfig, {
+      ...context,
+      admin: context?.config?.admin,
+    });
+  }
+
+  const insecureOptIn =
+    options.allowInsecureAdminApi === true ||
+    options.requireAuth === false ||
+    context?.config?.admin?.allowInsecureAdminApi === true;
+
+  if (insecureOptIn) {
+    return createAdminAuthMiddleware(
+      { mode: 'none', allowInsecureAdminApi: true },
+      { ...context, admin: context?.config?.admin }
+    );
+  }
+
+  if (process.env.NODE_ENV === 'production') {
+    throw new Error('Admin API requires an authentication strategy in production.');
+  }
+
+  if (options.requireAuth === true) {
     return function missingAuthMiddleware(_req, res) {
       return unauthorized(res);
     };
   }
 
-  const contextAuth = context?.config?.admin?.auth;
-  const authConfig = isAuthConfig(options.auth) ? options.auth : contextAuth;
-  if (!authConfig) return (_req, _res, next) => next();
-
-  return createAdminAuthMiddleware(authConfig, {
-    ...context,
-    admin: context?.config?.admin,
-  });
+  throw new Error(
+    'Admin API requires authentication. Configure auth or explicitly allow insecure local access.'
+  );
 }
 
 function createAdminAuthMiddleware(config, context = {}) {
@@ -67,17 +99,51 @@ async function authenticateAdminRequest(req, config, context = {}) {
 function validateAdminAuthConfig(config, context = {}) {
   const mode = normalizeMode(config?.mode);
 
+  if (!SUPPORTED_MODES.has(mode)) {
+    throw new Error(`Unsupported Admin API auth mode: ${mode}`);
+  }
+
   if (mode === 'token' && !hasNonEmptyString(config.token)) {
     throw new Error('Admin API token auth requires a non-empty token.');
   }
+  if (mode === 'token' && config.header !== undefined) {
+    validateHeaderName(config.header, 'auth.header');
+  }
 
   if (mode === 'ip-allowlist' && !hasNonEmptyArray(config.allowedIps)) {
     throw new Error('Admin API ip-allowlist auth requires allowedIps.');
   }
+  if (mode === 'ip-allowlist') validateTrustedProxies(config.allowedIps, 'auth.allowedIps');
 
   if (mode === 'trusted-proxy' && !hasNonEmptyArray(config.trustedProxies)) {
     throw new Error('Admin API trusted-proxy auth requires trustedProxies.');
   }
+  if (config.trustedProxies !== undefined) {
+    validateTrustedProxies(config.trustedProxies, 'auth.trustedProxies');
+  }
+
+  for (const field of [
+    'proxySharedSecretHeader',
+    'userHeader',
+    'emailHeader',
+    'rolesHeader',
+    'jwtHeader',
+    'dataHeader',
+  ]) {
+    if (config[field] !== undefined) validateHeaderName(config[field], `auth.${field}`);
+  }
+  if (config.requiredHeaders !== undefined) {
+    if (
+      !config.requiredHeaders ||
+      typeof config.requiredHeaders !== 'object' ||
+      Array.isArray(config.requiredHeaders)
+    ) {
+      throw new TypeError('auth.requiredHeaders must be an object');
+    }
+    for (const header of Object.keys(config.requiredHeaders)) {
+      validateHeaderName(header, 'auth.requiredHeaders');
+    }
+  }
 
   if (mode === 'cloudflare-access' || mode === 'alb-auth' || mode === 'cognito-alb') {
     validateExternalAuthConfig(mode, config);
@@ -101,13 +167,11 @@ function validateAdminAuthConfig(config, context = {}) {
     }
   }
 
-  if (
-    mode === 'none' &&
-    process.env.NODE_ENV === 'production' &&
-    !config.allowInsecureAdminApi &&
-    !context?.admin?.allowInsecureAdminApi
-  ) {
-    throw new Error('Admin API auth mode "none" is not allowed in production.');
+  if (mode === 'none') {
+    if (process.env.NODE_ENV === 'production') {
+      throw new Error('Admin API auth mode "none" is not allowed in production.');
+    }
+    warnInsecureAdminApi();
   }
 }
 

package/src/admin/auth/strategies/none.js

@@ -5,16 +5,20 @@ const { success } = require('../utils/result');
 
 let warned = false;
 
-function authenticateNone(req, config) {
+function warnInsecureAdminApi() {
   if (!warned) {
     warned = true;
     console.warn(
       '[parry] Admin API auth mode "none" is insecure and intended only for local development.'
     );
   }
+}
+
+function authenticateNone(req, config) {
+  warnInsecureAdminApi();
 
   const ip = getClientIp(req, config);
   return success(req, 'none', { subject: 'insecure-none', ip }, config);
 }
 
-module.exports = { authenticateNone };
+module.exports = { authenticateNone, warnInsecureAdminApi };