@roboteby/parry 1.1.0-rc.1

package/src/admin/ban-normalizer.js

@@ -0,0 +1,98 @@
+'use strict';
+
+const { sanitizeEvent } = require('../events/sanitize-event');
+
+function normalizeAdminBanEntry(entry = {}, source = 'ban', now = Date.now()) {
+  const sanitized = sanitizeEvent(entry) || {};
+  const metadata = sanitizeEvent(sanitized.metadata || {}) || {};
+  const rawKey = String(sanitized.key || 'unknown');
+  const type = inferType(rawKey, metadata, source);
+  const expiresAtMs = pickNumber(
+    sanitized.expiresAt,
+    sanitized.banExpiresAt,
+    sanitized.blockExpiresAt
+  );
+  const ttlMs =
+    pickNumber(sanitized.ttlMs) ?? (expiresAtMs ? Math.max(0, expiresAtMs - now) : null);
+  const createdAtMs =
+    pickNumber(sanitized.createdAt, metadata.createdAt) ??
+    (expiresAtMs && ttlMs ? expiresAtMs - ttlMs : now);
+
+  return {
+    key: normalizePublicKey(rawKey, type),
+    type,
+    reason: String(metadata.reason || sanitized.reason || defaultReason(source)),
+    policyName: metadata.policyName || sanitized.policyName || inferPolicyName(rawKey) || null,
+    createdAt: toIso(createdAtMs),
+    expiresAt: expiresAtMs ? toIso(expiresAtMs) : null,
+    ttlMs,
+  };
+}
+
+async function listAdminBanEntries(store, options = {}) {
+  const now = Date.now();
+  const bans = store && typeof store.listBans === 'function' ? await store.listBans(options) : [];
+  const blocks =
+    store && typeof store.listBlocks === 'function' ? await store.listBlocks(options) : [];
+
+  return [
+    ...bans.map((entry) => normalizeAdminBanEntry(entry, 'ban', now)),
+    ...blocks.map((entry) => normalizeAdminBanEntry(entry, 'block', now)),
+  ];
+}
+
+function inferType(key, metadata, source) {
+  if (source === 'block' && key.startsWith('bf:')) return 'brute-force';
+  if (String(metadata.keyType || '').startsWith('body.email')) return 'identity';
+  if (key.startsWith('ip:') || isIpLike(key)) return 'ip';
+  if (key.includes('body.email') || looksLikeEmail(key)) return 'identity';
+  if (source === 'block') return 'brute-force';
+  return 'generic';
+}
+
+function normalizePublicKey(key, type) {
+  if (type === 'ip' && !key.startsWith('ip:')) return `ip:${key}`;
+  return key;
+}
+
+function inferPolicyName(key) {
+  const parts = String(key || '').split(':');
+  if (parts[0] === 'bf' && parts[1]) return parts[1];
+  if (parts[0] === 'route-rl' && parts[1]) return parts[1];
+  return null;
+}
+
+function defaultReason(source) {
+  return source === 'block'
+    ? 'Temporary application-layer block'
+    : 'Temporary application-layer ban';
+}
+
+function pickNumber(...values) {
+  for (const value of values) {
+    if (value == null || value === '') continue;
+    const parsed =
+      typeof value === 'string' && Number.isNaN(Number(value)) ? Date.parse(value) : Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return null;
+}
+
+function toIso(value) {
+  const parsed = pickNumber(value) || Date.now();
+  return new Date(parsed).toISOString();
+}
+
+function isIpLike(value) {
+  return /^(?:\d{1,3}\.){3}\d{1,3}$/.test(value) || /^[0-9a-f:]+$/i.test(value);
+}
+
+function looksLikeEmail(value) {
+  return /[^\s:@]+@[^\s:@]+\.[^\s:@]+/.test(value);
+}
+
+module.exports = {
+  listAdminBanEntries,
+  normalizeAdminBanEntry,
+  inferType,
+};

package/src/admin/index.js

@@ -0,0 +1,12 @@
+'use strict';
+
+const { createParryAdminRouter, resolveParryContext } = require('./admin-router');
+const { createAdminAuthMiddleware, authenticateAdminRequest, requireAdminAuth } = require('./auth');
+
+module.exports = {
+  createParryAdminRouter,
+  resolveParryContext,
+  createAdminAuthMiddleware,
+  authenticateAdminRequest,
+  requireAdminAuth,
+};

package/src/admin/response.js

@@ -0,0 +1,41 @@
+'use strict';
+
+function json(res, statusCode, body) {
+  return res.status(statusCode).json(body);
+}
+
+function ok(res, body) {
+  return json(res, 200, body);
+}
+
+function unauthorized(res) {
+  return json(res, 401, {
+    error: {
+      code: 'ADMIN_UNAUTHORIZED',
+      message: 'Admin API authentication required',
+    },
+    code: 'ADMIN_UNAUTHORIZED',
+    message: 'Admin API authentication required',
+  });
+}
+
+function forbidden(res) {
+  return json(res, 403, {
+    error: {
+      code: 'ADMIN_FORBIDDEN',
+      message: 'Admin API access denied',
+    },
+    code: 'ADMIN_FORBIDDEN',
+    message: 'Admin API access denied',
+  });
+}
+
+function notFound(res) {
+  return json(res, 404, {
+    error: 'Not found',
+    code: 'ADMIN_NOT_FOUND',
+    message: 'Not found',
+  });
+}
+
+module.exports = { json, ok, unauthorized, forbidden, notFound };

package/src/brute-force/brute-force-guard.js

@@ -0,0 +1,268 @@
+'use strict';
+
+const { buildBruteForceKeys } = require('./key-builder');
+const { createAllowedResult, createBlockedResult } = require('./result');
+
+function createBruteForceContext({
+  policy,
+  requestData,
+  req,
+  res,
+  store,
+  config,
+  logger,
+  eventBus,
+}) {
+  const enabled = Boolean(policy?.bruteForce?.enabled);
+  const keys = enabled ? buildBruteForceKeys(policy, requestData) : [];
+  const state = {
+    manualAction: null,
+    manualReason: null,
+    processed: false,
+  };
+
+  return { policy, requestData, req, res, store, config, logger, eventBus, enabled, keys, state };
+}
+
+function attachParryRequestApi(req, context) {
+  const existing = req.parry && typeof req.parry === 'object' ? req.parry : {};
+  req.parry = {
+    ...existing,
+    recordAuthFailure(reason) {
+      context.state.manualAction = 'failure';
+      context.state.manualReason = reason || 'manual_failure';
+    },
+    recordAuthSuccess() {
+      context.state.manualAction = 'success';
+      context.state.manualReason = 'manual_success';
+    },
+  };
+}
+
+async function checkBruteForceBlock(context) {
+  if (!context.enabled || context.keys.length === 0) return createAllowedResult();
+
+  try {
+    for (const key of context.keys) {
+      const blocked = await context.store.isBlocked(key.key);
+      if (blocked.blocked) {
+        const event = createBruteForceEvent(context, 'BRUTE_FORCE_BLOCK', {
+          reason: 'Authentication attempts temporarily blocked',
+          severity: 'high',
+          keyTypes: context.keys.map((item) => item.type),
+        });
+        emitEvent(context, event);
+
+        return createBlockedResult({
+          statusCode: context.policy.bruteForce.blockedStatusCode,
+          blockExpiresAt: blocked.blockExpiresAt,
+          retryAfterMs: Math.max(0, blocked.blockExpiresAt - Date.now()),
+          event,
+        });
+      }
+    }
+  } catch (error) {
+    return handleStoreFailure(context, error);
+  }
+
+  return createAllowedResult();
+}
+
+function observeAuthenticationResult(context) {
+  if (
+    !context.enabled ||
+    context.keys.length === 0 ||
+    !context.res ||
+    typeof context.res.on !== 'function'
+  ) {
+    return;
+  }
+
+  context.res.on('finish', () => {
+    finalizeAuthenticationResult(context).catch((error) => {
+      const event = createStoreFailureEvent(context, error);
+      if (context.logger && typeof context.logger.logStoreError === 'function') {
+        context.logger.logStoreError(error, event);
+      }
+    });
+  });
+}
+
+async function finalizeAuthenticationResult(context) {
+  if (context.state.processed) return;
+  context.state.processed = true;
+
+  const action = resolveAction(context);
+  if (action === 'failure') {
+    await recordFailure(context, context.state.manualReason || 'status_failure');
+  } else if (action === 'success' && context.policy.bruteForce.resetOnSuccess) {
+    await resetCounters(context);
+  }
+}
+
+function resolveAction(context) {
+  if (context.state.manualAction) return context.state.manualAction;
+
+  const status = getResponseStatus(context.res);
+  if (context.policy.bruteForce.failureStatusCodes.includes(status)) return 'failure';
+  if (context.policy.bruteForce.successStatusCodes.includes(status)) return 'success';
+  return null;
+}
+
+async function recordFailure(context, reason) {
+  const attempts = [];
+  for (const key of context.keys) {
+    const attempt = await context.store.incrementCounter(
+      key.key,
+      context.policy.bruteForce.windowMs,
+      {
+        policyName: context.policy.name,
+        keyType: key.type,
+        reason,
+      }
+    );
+    attempts.push({ key, attempt });
+  }
+
+  emitEvent(
+    context,
+    createBruteForceEvent(context, 'BRUTE_FORCE_ATTEMPT', {
+      reason,
+      severity: 'medium',
+      keyTypes: context.keys.map((item) => item.type),
+    })
+  );
+
+  const shouldBlock = attempts.some(
+    ({ attempt }) => attempt.count >= context.policy.bruteForce.maxAttempts
+  );
+  if (!shouldBlock) return;
+
+  for (const key of context.keys) {
+    await context.store.blockKey(key.key, context.policy.bruteForce.blockDurationMs, {
+      policyName: context.policy.name,
+      keyType: key.type,
+      reason: 'max_attempts_exceeded',
+    });
+  }
+
+  emitEvent(
+    context,
+    createBruteForceEvent(context, 'BRUTE_FORCE_BLOCK', {
+      reason: 'max_attempts_exceeded',
+      severity: 'high',
+      keyTypes: context.keys.map((item) => item.type),
+    })
+  );
+}
+
+async function resetCounters(context) {
+  for (const key of context.keys) {
+    await context.store.resetCounter(key.key);
+  }
+
+  emitEvent(
+    context,
+    createBruteForceEvent(context, 'BRUTE_FORCE_RESET', {
+      reason: context.state.manualReason || 'auth_success',
+      severity: 'low',
+      keyTypes: context.keys.map((item) => item.type),
+    })
+  );
+}
+
+function handleStoreFailure(context, error) {
+  const mode = context.config.storeFailureMode === 'fail-closed' ? 'fail-closed' : 'fail-open';
+  const event = createStoreFailureEvent(context, error, mode);
+  if (context.logger && typeof context.logger.logStoreError === 'function') {
+    context.logger.logStoreError(error, event);
+  }
+
+  if (mode === 'fail-open') return createAllowedResult();
+
+  return createBlockedResult({
+    statusCode: 503,
+    storeFailure: true,
+    event,
+  });
+}
+
+function createBruteForceEvent(context, type, details = {}) {
+  return {
+    type,
+    module: 'brute-force',
+    detector: 'BRUTE_FORCE',
+    policyName: context.policy.name,
+    ip: context.requestData.ip,
+    method: context.requestData.method,
+    path: context.requestData.path,
+    keyTypes: details.keyTypes || [],
+    severity: details.severity || 'medium',
+    reason: details.reason,
+    timestamp: new Date().toISOString(),
+    requestId:
+      context.requestData.requestId || getHeader(context.requestData.headers, 'x-request-id'),
+    userAgent:
+      context.requestData.userAgent || getHeader(context.requestData.headers, 'user-agent'),
+  };
+}
+
+function createStoreFailureEvent(context, error, mode) {
+  return {
+    type: 'STORE_FAILURE',
+    module: 'brute-force',
+    policyName: context.policy?.name,
+    ip: context.requestData.ip,
+    method: context.requestData.method,
+    path: context.requestData.path,
+    timestamp: new Date().toISOString(),
+    reason: error && error.message ? error.message : String(error),
+    mode: mode || context.config.storeFailureMode || 'fail-open',
+    requestId:
+      context.requestData.requestId || getHeader(context.requestData.headers, 'x-request-id'),
+    userAgent:
+      context.requestData.userAgent || getHeader(context.requestData.headers, 'user-agent'),
+  };
+}
+
+function emitEvent(context, event) {
+  if (context.eventBus && typeof context.eventBus.emitThreat === 'function') {
+    context.eventBus.emitThreat(event, { req: context.req, res: context.res });
+    return;
+  }
+
+  if (context.logger && typeof context.logger.log === 'function') context.logger.log(event);
+
+  if (context.config.onThreat) {
+    try {
+      context.config.onThreat(event, context.req, context.res);
+    } catch (error) {
+      if (context.logger && typeof context.logger.logHookError === 'function') {
+        context.logger.logHookError(error, event);
+      }
+    }
+  }
+}
+
+function getResponseStatus(res) {
+  return Number(res.statusCode || res._status || 200);
+}
+
+function getHeader(headers, name) {
+  if (!headers) return undefined;
+  const lower = name.toLowerCase();
+  return (
+    headers[lower] ||
+    headers[name] ||
+    headers[Object.keys(headers).find((key) => key.toLowerCase() === lower)]
+  );
+}
+
+module.exports = {
+  createBruteForceContext,
+  attachParryRequestApi,
+  checkBruteForceBlock,
+  observeAuthenticationResult,
+  finalizeAuthenticationResult,
+  createBruteForceEvent,
+};

package/src/brute-force/index.js

@@ -0,0 +1,32 @@
+'use strict';
+
+const {
+  createBruteForceContext,
+  attachParryRequestApi,
+  checkBruteForceBlock,
+  observeAuthenticationResult,
+  finalizeAuthenticationResult,
+  createBruteForceEvent,
+} = require('./brute-force-guard');
+const {
+  buildBruteForceKeys,
+  buildRouteRateLimitKey,
+  buildKey,
+  resolveValue,
+} = require('./key-builder');
+const { createBlockedResponse, retryAfterSeconds } = require('./result');
+
+module.exports = {
+  createBruteForceContext,
+  attachParryRequestApi,
+  checkBruteForceBlock,
+  observeAuthenticationResult,
+  finalizeAuthenticationResult,
+  createBruteForceEvent,
+  buildBruteForceKeys,
+  buildRouteRateLimitKey,
+  buildKey,
+  resolveValue,
+  createBlockedResponse,
+  retryAfterSeconds,
+};

package/src/brute-force/key-builder.js

@@ -0,0 +1,164 @@
+'use strict';
+
+const FORBIDDEN_SEGMENTS = new Set([
+  'password',
+  'pass',
+  'token',
+  'authorization',
+  'cookie',
+  'secret',
+]);
+
+function buildBruteForceKeys(policy, requestData) {
+  const bruteForce = policy?.bruteForce || {};
+  return buildKeys({
+    policyName: policy.name,
+    specs: bruteForce.keys || [],
+    requestData,
+    namespace: 'bf',
+  });
+}
+
+function buildRouteRateLimitKey(policy, requestData) {
+  const spec = policy?.rateLimit?.key || 'ip';
+  const keys = buildKeys({
+    policyName: policy.name,
+    specs: [spec],
+    requestData,
+    namespace: 'route-rl',
+  });
+
+  return keys[0] || null;
+}
+
+function buildKeys({ policyName, specs, requestData, namespace }) {
+  const result = [];
+  for (const spec of specs) {
+    const key = buildKey(policyName, spec, requestData, namespace);
+    if (key) result.push(key);
+  }
+  return result;
+}
+
+function buildKey(policyName, spec, requestData, namespace) {
+  if (typeof spec === 'function') {
+    return buildCustomKey(policyName, spec, requestData, namespace);
+  }
+
+  const type = String(spec || '').trim();
+  if (!type || containsForbiddenSegment(type)) return null;
+
+  const parts = type
+    .split('+')
+    .map((part) => part.trim())
+    .filter(Boolean);
+  const values = [];
+
+  for (const part of parts) {
+    const value = resolveValue(part, requestData);
+    if (!value) return null;
+    values.push(value);
+  }
+
+  const normalizedValue = values.join(':');
+  return createKey(namespace, policyName, type, normalizedValue);
+}
+
+function buildCustomKey(policyName, spec, requestData, namespace) {
+  const value = spec(requestData);
+  if (value == null) return null;
+
+  if (typeof value === 'object') {
+    const type = sanitizeType(value.type || value.keyType || spec.name || 'custom');
+    const normalizedValue = normalizeScalar(value.value);
+    if (!normalizedValue) return null;
+    return createKey(namespace, policyName, type, normalizedValue);
+  }
+
+  const normalizedValue = normalizeScalar(value);
+  if (!normalizedValue) return null;
+  return createKey(namespace, policyName, sanitizeType(spec.name || 'custom'), normalizedValue);
+}
+
+function createKey(namespace, policyName, type, value) {
+  const keyType = sanitizeType(type);
+  return {
+    type: keyType,
+    value,
+    key: `${namespace}:${sanitizeType(policyName)}:${keyType}:${value}`,
+  };
+}
+
+function resolveValue(path, requestData) {
+  switch (path) {
+    case 'ip':
+      return normalizeScalar(requestData.ip);
+    case 'userAgent':
+      return normalizeScalar(
+        requestData.headers?.['user-agent'] || requestData.headers?.['User-Agent']
+      );
+    case 'method':
+      return normalizeScalar(requestData.method).toUpperCase();
+    case 'path':
+      return normalizePath(requestData.path || requestData.url);
+    default:
+      return resolvePathValue(path, requestData);
+  }
+}
+
+function resolvePathValue(path, requestData) {
+  if (containsForbiddenSegment(path)) return null;
+
+  const segments = String(path || '').split('.');
+  if (segments.length < 2) return null;
+
+  let current = requestData[segments[0]];
+  for (const segment of segments.slice(1)) {
+    if (current == null || typeof current !== 'object') return null;
+    current = current[segment];
+  }
+
+  return normalizeValueForPath(path, current);
+}
+
+function normalizeValueForPath(path, value) {
+  const normalized = normalizeScalar(value);
+  if (!normalized) return null;
+
+  if (/(email|username|login)$/i.test(path)) return normalized.toLowerCase();
+  return normalized;
+}
+
+function normalizeScalar(value) {
+  if (value == null) return null;
+  if (Array.isArray(value)) return normalizeScalar(value[0]);
+  if (typeof value === 'object') return null;
+
+  const normalized = String(value).trim();
+  return normalized.length > 0 ? normalized : null;
+}
+
+function normalizePath(value) {
+  const normalized = normalizeScalar(value) || '/';
+  const queryIndex = normalized.indexOf('?');
+  return queryIndex === -1 ? normalized : normalized.slice(0, queryIndex);
+}
+
+function containsForbiddenSegment(path) {
+  return String(path || '')
+    .split(/[.+]/)
+    .some((segment) => FORBIDDEN_SEGMENTS.has(segment.toLowerCase()));
+}
+
+function sanitizeType(value) {
+  return String(value || 'unknown')
+    .trim()
+    .replace(/[^a-zA-Z0-9_.+-]/g, '-');
+}
+
+module.exports = {
+  buildBruteForceKeys,
+  buildRouteRateLimitKey,
+  buildKey,
+  resolveValue,
+};

package/src/brute-force/result.js

@@ -0,0 +1,35 @@
+'use strict';
+
+function createBlockedResponse(blocked) {
+  const retryAfter = retryAfterSeconds(blocked);
+  return {
+    statusCode: blocked.statusCode || 429,
+    headers: { 'Retry-After': retryAfter },
+    body: {
+      error: 'Too many authentication attempts',
+      code: 'BRUTE_FORCE_BLOCKED',
+      retryAfter,
+    },
+  };
+}
+
+function retryAfterSeconds(blocked) {
+  const now = Date.now();
+  const until = blocked.blockExpiresAt || blocked.banExpiresAt || now;
+  return Math.max(1, Math.ceil((until - now) / 1000));
+}
+
+function createAllowedResult(context = {}) {
+  return { allowed: true, blocked: false, ...context };
+}
+
+function createBlockedResult(context) {
+  return { allowed: false, blocked: true, ...context };
+}
+
+module.exports = {
+  createBlockedResponse,
+  createAllowedResult,
+  createBlockedResult,
+  retryAfterSeconds,
+};