@roboteby/parry 1.1.0-rc.1

package/src/policies/matcher.js

@@ -0,0 +1,48 @@
+'use strict';
+
+function matchesPolicy(policy, requestData) {
+  if (!policy || !policy.match) return false;
+
+  return (
+    matchesMethod(policy.match.method, requestData.method) &&
+    matchesPath(policy.match.path, requestData.path || requestData.url || '/')
+  );
+}
+
+function findMatchingPolicy(policies, requestData) {
+  return (policies || []).find((policy) => matchesPolicy(policy, requestData)) || null;
+}
+
+function matchesMethod(expected, method) {
+  if (!expected) return true;
+
+  const actual = String(method || '').toUpperCase();
+  const methods = Array.isArray(expected) ? expected : [expected];
+  return methods.some((item) => String(item || '').toUpperCase() === actual);
+}
+
+function matchesPath(expected, path) {
+  if (!expected) return true;
+
+  const actual = stripQuery(path || '/');
+  const paths = Array.isArray(expected) ? expected : [expected];
+
+  return paths.some((item) => {
+    if (item instanceof RegExp) return item.test(actual);
+
+    const pattern = String(item || '');
+    if (pattern.endsWith('*')) {
+      return actual.startsWith(pattern.slice(0, -1));
+    }
+
+    return actual === pattern;
+  });
+}
+
+function stripQuery(value) {
+  const path = String(value || '/');
+  const index = path.indexOf('?');
+  return index === -1 ? path : path.slice(0, index);
+}
+
+module.exports = { findMatchingPolicy, matchesPolicy, matchesMethod, matchesPath, stripQuery };

package/src/policies/normalize-policy.js

@@ -0,0 +1,94 @@
+'use strict';
+
+const { getPresetPolicies } = require('./presets');
+
+const BRUTE_FORCE_DEFAULTS = {
+  enabled: false,
+  maxAttempts: 5,
+  windowMs: 15 * 60_000,
+  blockDurationMs: 10 * 60_000,
+  keys: ['ip'],
+  failureStatusCodes: [400, 401, 403],
+  successStatusCodes: [200, 201, 204],
+  blockedStatusCode: 429,
+  resetOnSuccess: true,
+};
+
+function buildPolicies(options = {}) {
+  const presetName = options.preset || 'off';
+  const presetPolicies = options.bruteForce === false ? [] : getPresetPolicies(presetName);
+  const explicitPolicies = Array.isArray(options.policies) ? options.policies : [];
+  const merged = mergePolicies(presetPolicies, explicitPolicies);
+
+  return merged.map((policy) => normalizePolicy(policy, options));
+}
+
+function normalizePolicy(policy, options = {}) {
+  if (!policy || !policy.name) {
+    throw new Error('Parry policy requires a name.');
+  }
+
+  const bruteForceDisabled =
+    options.bruteForce === false ||
+    (options.bruteForce &&
+      typeof options.bruteForce === 'object' &&
+      options.bruteForce.enabled === false);
+
+  return {
+    name: String(policy.name),
+    match: policy.match || {},
+    inheritGlobalRateLimit: policy.inheritGlobalRateLimit !== false,
+    rateLimit: normalizeRateLimit(policy.rateLimit),
+    bruteForce: normalizeBruteForce(policy.bruteForce, bruteForceDisabled),
+  };
+}
+
+function normalizeRateLimit(rateLimit) {
+  if (!rateLimit || rateLimit.enabled === false) return { enabled: false };
+
+  return {
+    enabled: true,
+    max: rateLimit.max || rateLimit.maxRequests || 10,
+    windowMs: rateLimit.windowMs || 60_000,
+    key: rateLimit.key || 'ip',
+  };
+}
+
+function normalizeBruteForce(bruteForce, forceDisabled) {
+  if (forceDisabled || !bruteForce || bruteForce.enabled === false) {
+    return { ...BRUTE_FORCE_DEFAULTS, enabled: false };
+  }
+
+  return {
+    ...BRUTE_FORCE_DEFAULTS,
+    ...bruteForce,
+    enabled: true,
+    keys:
+      Array.isArray(bruteForce.keys) && bruteForce.keys.length > 0
+        ? bruteForce.keys
+        : BRUTE_FORCE_DEFAULTS.keys,
+    failureStatusCodes: normalizeStatusList(
+      bruteForce.failureStatusCodes,
+      BRUTE_FORCE_DEFAULTS.failureStatusCodes
+    ),
+    successStatusCodes: normalizeStatusList(
+      bruteForce.successStatusCodes,
+      BRUTE_FORCE_DEFAULTS.successStatusCodes
+    ),
+    resetOnSuccess: bruteForce.resetOnSuccess !== false,
+  };
+}
+
+function normalizeStatusList(value, fallback) {
+  if (!Array.isArray(value) || value.length === 0) return fallback;
+  return value.map((status) => Number(status)).filter((status) => Number.isInteger(status));
+}
+
+function mergePolicies(presetPolicies, explicitPolicies) {
+  const byName = new Map();
+  for (const policy of presetPolicies) byName.set(policy.name, policy);
+  for (const policy of explicitPolicies) byName.set(policy.name, policy);
+  return [...byName.values()];
+}
+
+module.exports = { buildPolicies, normalizePolicy, BRUTE_FORCE_DEFAULTS };

package/src/policies/presets.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const COMMON_AUTH_PATHS = ['/login', '/signin', '/auth/login', '/api/login', '/api/auth/login'];
+
+function getPresetPolicies(name) {
+  if (!name || name === 'off') return [];
+  if (name === 'recommended') return createAuthPolicies('recommended', 10, 10 * 60_000, 20);
+  if (name === 'strict') return createAuthPolicies('strict', 5, 15 * 60_000, 10);
+
+  throw new Error(`Unknown Parry preset: ${name}`);
+}
+
+function createAuthPolicies(prefix, maxAttempts, blockDurationMs, routeMax) {
+  return COMMON_AUTH_PATHS.map((path) => ({
+    name: `${prefix}-auth-${path.replace(/[^a-z0-9]+/gi, '-').replace(/^-|-$/g, '')}`,
+    match: { method: 'POST', path },
+    rateLimit: {
+      enabled: true,
+      max: routeMax,
+      windowMs: 60_000,
+      key: 'ip',
+    },
+    bruteForce: {
+      enabled: true,
+      maxAttempts,
+      windowMs: 15 * 60_000,
+      blockDurationMs,
+      keys: ['ip', 'body.email', 'ip+body.email', 'body.username', 'ip+body.username'],
+      resetOnSuccess: true,
+    },
+  }));
+}
+
+module.exports = { getPresetPolicies };

package/src/rate-limit/keys.js

@@ -0,0 +1,7 @@
+'use strict';
+
+function normalizeRateLimitKey(value) {
+  return String(value || 'unknown');
+}
+
+module.exports = { normalizeRateLimitKey };

package/src/rate-limit/limiter.js

@@ -0,0 +1,124 @@
+'use strict';
+
+const { MemoryStore } = require('../stores/memory-store');
+const { createRateLimitResult } = require('../core/rate-limit-result');
+const { normalizeRateLimitKey } = require('./keys');
+
+class RateLimiter {
+  /**
+   * @param {{
+   *   rateLimit?: boolean | { enabled?: boolean, max?: number, maxRequests?: number, windowMs?: number, headers?: boolean },
+   *   maxRequests?: number,
+   *   windowMs?: number,
+   *   suspiciousThreshold?: number,
+   *   banDurationMs?: number,
+   *   store?: import('../stores/memory-store').MemoryStore
+   * }} config
+   * @param {object} [store]
+   */
+  constructor(config, store) {
+    const rateLimit = normalizeRateLimitOptions(config);
+
+    this.enabled = rateLimit.enabled;
+    this.maxRequests = rateLimit.maxRequests;
+    this.windowMs = rateLimit.windowMs;
+    this.headers = rateLimit.headers;
+    this.suspiciousThreshold = config.suspiciousThreshold;
+    this.banDurationMs = config.banDurationMs;
+    this.suspiciousTtlMs = Math.max(this.windowMs, this.banDurationMs, 600_000);
+    this.store = store || config.store || new MemoryStore();
+
+    this._cleanupInterval = setInterval(() => this._cleanup(), 600_000);
+    if (this._cleanupInterval.unref) this._cleanupInterval.unref();
+  }
+
+  async check(ip) {
+    const key = normalizeRateLimitKey(ip);
+    const ban = await this.store.isBanned(key);
+
+    if (ban.banned) {
+      return createRateLimitResult({
+        limited: false,
+        banned: true,
+        remaining: 0,
+        resetAt: ban.banExpiresAt,
+        banExpiresAt: ban.banExpiresAt,
+      });
+    }
+
+    const counter = await this.store.incrementRateLimit(key, this.windowMs);
+    const remaining = Math.max(0, this.maxRequests - counter.count);
+
+    if (counter.count > this.maxRequests) {
+      return createRateLimitResult({
+        limited: true,
+        banned: false,
+        remaining: 0,
+        resetAt: counter.resetAt,
+        banExpiresAt: null,
+      });
+    }
+
+    return createRateLimitResult({
+      limited: false,
+      banned: false,
+      remaining,
+      resetAt: counter.resetAt,
+      banExpiresAt: null,
+    });
+  }
+
+  async recordSuspicious(ip) {
+    const key = normalizeRateLimitKey(ip);
+    const suspicious = await this.store.recordSuspicious(key, this.suspiciousTtlMs, {
+      reason: 'Threat detected',
+    });
+
+    if (suspicious.count >= this.suspiciousThreshold) {
+      return this.store.ban(key, this.banDurationMs, {
+        reason: 'Suspicious activity threshold reached',
+        suspiciousCount: suspicious.count,
+      });
+    }
+
+    return suspicious;
+  }
+
+  async unban(ip) {
+    return this.store.unban(normalizeRateLimitKey(ip));
+  }
+
+  async snapshot() {
+    if (typeof this.store.snapshot === 'function') {
+      return this.store.snapshot(this.windowMs);
+    }
+
+    return [];
+  }
+
+  async _cleanup() {
+    if (typeof this.store.cleanup === 'function') {
+      await this.store.cleanup();
+    }
+  }
+
+  destroy() {
+    clearInterval(this._cleanupInterval);
+    if (typeof this.store.close === 'function') return this.store.close();
+    if (typeof this.store.clear === 'function') return this.store.clear();
+  }
+}
+
+function normalizeRateLimitOptions(config) {
+  const option = config.rateLimit;
+  const objectConfig = option && typeof option === 'object' ? option : {};
+
+  return {
+    enabled: option !== false && objectConfig.enabled !== false,
+    maxRequests: objectConfig.max || objectConfig.maxRequests || config.maxRequests || 100,
+    windowMs: objectConfig.windowMs || config.windowMs || 60_000,
+    headers: objectConfig.headers !== false,
+  };
+}
+
+module.exports = { RateLimiter, normalizeRateLimitOptions };

package/src/stores/README.md

@@ -0,0 +1,51 @@
+# Store Contract
+
+Stores keep rate limit, temporary ban, and suspicious activity state for Parry.
+Methods may return values directly or return Promises.
+
+```js
+store.incrementRateLimit(key, windowMs);
+// -> { key, count, resetAt, ttlMs }
+
+store.getRateLimit(key);
+// -> { key, count, resetAt, ttlMs }
+
+store.resetRateLimit(key);
+store.ban(key, ttlMs, metadata);
+store.isBanned(key);
+// -> { key, banned, banExpiresAt, metadata }
+
+store.unban(key);
+store.recordSuspicious(key, ttlMs, metadata);
+// -> { key, count, resetAt, ttlMs }
+
+store.incrementCounter(key, ttlMs, metadata);
+// -> { key, count, resetAt, ttlMs }
+
+store.getCounter(key);
+// -> { key, count, resetAt, ttlMs }
+
+store.resetCounter(key);
+store.blockKey(key, ttlMs, metadata);
+store.isBlocked(key);
+// -> { key, blocked, blockExpiresAt, metadata }
+
+store.unblockKey(key);
+
+store.listBans?.({ limit, offset });
+// -> [{ key, createdAt, banExpiresAt, ttlMs, metadata }]
+
+store.listBlocks?.({ limit, offset });
+// -> [{ key, createdAt, blockExpiresAt, ttlMs, metadata }]
+
+store.getStoreInfo?.();
+// -> { type, supportsAdminListing, ...metadata }
+
+store.close?.();
+```
+
+`key` is produced by the rate limiter, route policy, or brute force key builder.
+Stores are responsible for TTL handling, cleanup, and any backend-specific
+namespacing. Custom stores should avoid persisting sensitive request data.
+Administrative listing methods are optional, but stores that implement them must
+return only sanitized metadata suitable for a read-only operations dashboard.

package/src/stores/index.js

@@ -0,0 +1,6 @@
+'use strict';
+
+const { MemoryStore } = require('./memory-store');
+const { RedisStore } = require('./redis-store');
+
+module.exports = { MemoryStore, RedisStore };

package/src/stores/memory-store.js

@@ -0,0 +1,278 @@
+'use strict';
+
+class MemoryStore {
+  constructor() {
+    this.rateLimits = new Map();
+    this.bans = new Map();
+    this.suspicious = new Map();
+    this.counters = new Map();
+    this.blocks = new Map();
+  }
+
+  incrementRateLimit(key, windowMs) {
+    const now = Date.now();
+    const normalizedKey = normalizeKey(key);
+    const windowStart = now - windowMs;
+    const entry = this.rateLimits.get(normalizedKey) || { timestamps: [] };
+
+    entry.timestamps = entry.timestamps.filter((timestamp) => timestamp > windowStart);
+    entry.timestamps.push(now);
+    entry.resetAt = entry.timestamps[0] + windowMs;
+    this.rateLimits.set(normalizedKey, entry);
+
+    return formatCounterResult(normalizedKey, entry.timestamps.length, entry.resetAt, now);
+  }
+
+  getRateLimit(key) {
+    const now = Date.now();
+    const normalizedKey = normalizeKey(key);
+    const entry = this.rateLimits.get(normalizedKey);
+    if (!entry) return emptyCounterResult(normalizedKey);
+
+    const resetAt = entry.resetAt || now;
+    if (entry.timestamps.length === 0 || resetAt <= now) {
+      this.rateLimits.delete(normalizedKey);
+      return emptyCounterResult(normalizedKey);
+    }
+
+    return formatCounterResult(normalizedKey, entry.timestamps.length, resetAt, now);
+  }
+
+  resetRateLimit(key) {
+    return this.rateLimits.delete(normalizeKey(key));
+  }
+
+  ban(key, ttlMs, metadata = {}) {
+    const normalizedKey = normalizeKey(key);
+    const createdAt = Date.now();
+    const expiresAt = Date.now() + ttlMs;
+    this.bans.set(normalizedKey, { createdAt, expiresAt, metadata });
+    return { key: normalizedKey, banned: true, createdAt, banExpiresAt: expiresAt, metadata };
+  }
+
+  isBanned(key) {
+    const normalizedKey = normalizeKey(key);
+    const entry = this.bans.get(normalizedKey);
+    if (!entry) return { key: normalizedKey, banned: false, banExpiresAt: null, metadata: null };
+
+    const now = Date.now();
+    if (entry.expiresAt <= now) {
+      this.bans.delete(normalizedKey);
+      this.suspicious.delete(normalizedKey);
+      this.rateLimits.delete(normalizedKey);
+      return { key: normalizedKey, banned: false, banExpiresAt: null, metadata: null };
+    }
+
+    return {
+      key: normalizedKey,
+      banned: true,
+      createdAt: entry.createdAt || null,
+      banExpiresAt: entry.expiresAt,
+      metadata: entry.metadata || null,
+    };
+  }
+
+  unban(key) {
+    const normalizedKey = normalizeKey(key);
+    this.suspicious.delete(normalizedKey);
+    return this.bans.delete(normalizedKey);
+  }
+
+  recordSuspicious(key, ttlMs, metadata = {}) {
+    const now = Date.now();
+    const normalizedKey = normalizeKey(key);
+    const current = this.suspicious.get(normalizedKey);
+    const entry =
+      current && current.resetAt > now
+        ? current
+        : { count: 0, resetAt: now + ttlMs, metadata: null };
+
+    entry.count += 1;
+    entry.metadata = metadata;
+    this.suspicious.set(normalizedKey, entry);
+
+    return formatCounterResult(normalizedKey, entry.count, entry.resetAt, now);
+  }
+
+  incrementCounter(key, ttlMs, metadata = {}) {
+    const now = Date.now();
+    const normalizedKey = normalizeKey(key);
+    const current = this.counters.get(normalizedKey);
+    const entry =
+      current && current.resetAt > now
+        ? current
+        : { count: 0, resetAt: now + ttlMs, metadata: null };
+
+    entry.count += 1;
+    entry.metadata = metadata;
+    this.counters.set(normalizedKey, entry);
+
+    return formatCounterResult(normalizedKey, entry.count, entry.resetAt, now);
+  }
+
+  getCounter(key) {
+    const now = Date.now();
+    const normalizedKey = normalizeKey(key);
+    const entry = this.counters.get(normalizedKey);
+    if (!entry || entry.resetAt <= now) {
+      this.counters.delete(normalizedKey);
+      return emptyCounterResult(normalizedKey);
+    }
+
+    return formatCounterResult(normalizedKey, entry.count, entry.resetAt, now);
+  }
+
+  resetCounter(key) {
+    return this.counters.delete(normalizeKey(key));
+  }
+
+  blockKey(key, ttlMs, metadata = {}) {
+    const normalizedKey = normalizeKey(key);
+    const createdAt = Date.now();
+    const blockExpiresAt = Date.now() + ttlMs;
+    this.blocks.set(normalizedKey, { createdAt, blockExpiresAt, metadata });
+    return { key: normalizedKey, blocked: true, createdAt, blockExpiresAt, metadata };
+  }
+
+  isBlocked(key) {
+    const normalizedKey = normalizeKey(key);
+    const entry = this.blocks.get(normalizedKey);
+    if (!entry) return { key: normalizedKey, blocked: false, blockExpiresAt: null, metadata: null };
+
+    const now = Date.now();
+    if (entry.blockExpiresAt <= now) {
+      this.blocks.delete(normalizedKey);
+      return { key: normalizedKey, blocked: false, blockExpiresAt: null, metadata: null };
+    }
+
+    return {
+      key: normalizedKey,
+      blocked: true,
+      createdAt: entry.createdAt || null,
+      blockExpiresAt: entry.blockExpiresAt,
+      metadata: entry.metadata || null,
+    };
+  }
+
+  unblockKey(key) {
+    return this.blocks.delete(normalizeKey(key));
+  }
+
+  cleanup(now = Date.now()) {
+    for (const [key, entry] of this.rateLimits.entries()) {
+      if (!entry.timestamps.length) {
+        this.rateLimits.delete(key);
+        continue;
+      }
+
+      if (entry.resetAt <= now) this.rateLimits.delete(key);
+    }
+
+    for (const [key, entry] of this.bans.entries()) {
+      if (entry.expiresAt <= now) this.bans.delete(key);
+    }
+
+    for (const [key, entry] of this.suspicious.entries()) {
+      if (entry.resetAt <= now) this.suspicious.delete(key);
+    }
+
+    for (const [key, entry] of this.counters.entries()) {
+      if (entry.resetAt <= now) this.counters.delete(key);
+    }
+
+    for (const [key, entry] of this.blocks.entries()) {
+      if (entry.blockExpiresAt <= now) this.blocks.delete(key);
+    }
+  }
+
+  snapshot(windowMs) {
+    const now = Date.now();
+    const ips = new Set([
+      ...this.rateLimits.keys(),
+      ...this.suspicious.keys(),
+      ...this.bans.keys(),
+    ]);
+
+    return [...ips].map((ip) => {
+      const rateLimitEntry = this.rateLimits.get(ip);
+      const suspiciousEntry = this.suspicious.get(ip);
+      const ban = this.isBanned(ip);
+      const windowStart = now - windowMs;
+      const requests = rateLimitEntry
+        ? rateLimitEntry.timestamps.filter((timestamp) => timestamp > windowStart).length
+        : 0;
+
+      return {
+        ip,
+        requests,
+        suspicious: suspiciousEntry && suspiciousEntry.resetAt > now ? suspiciousEntry.count : 0,
+        banned: ban.banned,
+        banExpiresAt: ban.banExpiresAt,
+      };
+    });
+  }
+
+  listBans() {
+    const now = Date.now();
+    this.cleanup(now);
+
+    return [...this.bans.entries()].map(([key, entry]) => ({
+      key,
+      createdAt: entry.createdAt || null,
+      banExpiresAt: entry.expiresAt,
+      ttlMs: Math.max(0, entry.expiresAt - now),
+      metadata: entry.metadata || null,
+    }));
+  }
+
+  listBlocks() {
+    const now = Date.now();
+    this.cleanup(now);
+
+    return [...this.blocks.entries()].map(([key, entry]) => ({
+      key,
+      createdAt: entry.createdAt || null,
+      blockExpiresAt: entry.blockExpiresAt,
+      ttlMs: Math.max(0, entry.blockExpiresAt - now),
+      metadata: entry.metadata || null,
+    }));
+  }
+
+  getStoreInfo() {
+    return {
+      type: 'memory',
+      supportsAdminListing: true,
+    };
+  }
+
+  clear() {
+    this.rateLimits.clear();
+    this.bans.clear();
+    this.suspicious.clear();
+    this.counters.clear();
+    this.blocks.clear();
+  }
+
+  close() {
+    this.clear();
+  }
+}
+
+function normalizeKey(key) {
+  return String(key || 'unknown');
+}
+
+function emptyCounterResult(key) {
+  return { key, count: 0, resetAt: null, ttlMs: 0 };
+}
+
+function formatCounterResult(key, count, resetAt, now) {
+  return {
+    key,
+    count,
+    resetAt,
+    ttlMs: Math.max(0, resetAt - now),
+  };
+}
+
+module.exports = { MemoryStore };