secure-api-guard 0.0.0-stage → 1.0.0

package/src/stores/redisStore.js

@@ -0,0 +1,222 @@
+'use strict';
+
+const { defaultLogger } = require('../utils/logger');
+
+const LUA_INCR_SCRIPT = `
+local key = KEYS[1]
+local windowMs = tonumber(ARGV[1])
+local current = redis.call('INCR', key)
+if current == 1 then
+  redis.call('PEXPIRE', key, windowMs)
+end
+local ttl = redis.call('PTTL', key)
+if ttl < 0 then
+  redis.call('PEXPIRE', key, windowMs)
+  ttl = windowMs
+end
+return { current, ttl }
+`;
+
+/**
+ * Distributed Redis store for rate limiting across multiple instances.
+ */
+class RedisStore {
+  /**
+   * @param {Object} options
+   * @param {any} options.client - Redis client (ioredis or node-redis v4+).
+   * @param {string} [options.prefix='sag:rl:'] - Key prefix for rate limiting.
+   * @param {number} [options.windowMs=60000] - Rate limit window in milliseconds.
+   * @param {boolean} [options.passOnConnectionError=true] - If Redis fails, fail open to avoid taking down API.
+   * @param {import('../utils/logger').SecurityLogger} [options.logger] - Logger instance.
+   */
+  constructor(options = {}) {
+    if (!options.client) {
+      throw new Error('RedisStore requires a "client" instance (ioredis or redis).');
+    }
+
+    this.client = options.client;
+    this.prefix = options.prefix || 'sag:rl:';
+    this.windowMs = options.windowMs || 60000;
+    this.passOnConnectionError = options.passOnConnectionError !== false;
+    this.logger = options.logger || defaultLogger;
+  }
+
+  /**
+   * Called by express-rate-limit with middleware options.
+   * @param {Object} options
+   */
+  init(options) {
+    if (options && options.windowMs) {
+      this.windowMs = options.windowMs;
+    }
+  }
+
+  /**
+   * Prefix a rate limit key.
+   * @param {string} key
+   * @returns {string}
+   */
+  _prefixKey(key) {
+    return `${this.prefix}${key}`;
+  }
+
+  /**
+   * Execute Lua script across ioredis or node-redis v4+.
+   *
+   * @param {string} key
+   * @param {number} windowMs
+   * @returns {Promise<[number, number]>} [currentHits, ttlMs]
+   */
+  async _evalLua(key, windowMs) {
+    const fullKey = this._prefixKey(key);
+
+    // Node-redis v4+ client.eval syntax
+    if (typeof this.client.eval === 'function') {
+      try {
+        // Attempt node-redis v4 object parameters
+        const res = await this.client.eval(LUA_INCR_SCRIPT, {
+          keys: [fullKey],
+          arguments: [String(windowMs)]
+        });
+        return res;
+      } catch (err) {
+        // If node-redis object parameter syntax failed, try ioredis positional syntax:
+        // eval(script, numkeys, key1, ..., arg1, ...)
+        const res = await this.client.eval(LUA_INCR_SCRIPT, 1, fullKey, String(windowMs));
+        return res;
+      }
+    }
+
+    throw new Error('Provided Redis client does not support eval command.');
+  }
+
+  /**
+   * Increment hits for a key.
+   *
+   * @param {string} key
+   * @returns {Promise<{ totalHits: number, resetTime: Date }>}
+   */
+  async increment(key) {
+    try {
+      const result = await this._evalLua(key, this.windowMs);
+      const totalHits = Number(result[0]);
+      const ttlMs = Number(result[1]);
+      const resetTime = new Date(Date.now() + Math.max(0, ttlMs));
+
+      return {
+        totalHits,
+        resetTime
+      };
+    } catch (err) {
+      this.logger.error('REDIS_STORE_ERROR', `Redis rate-limiter store failure: ${err.message}`, {
+        details: { key, error: err.message }
+      });
+
+      if (!this.passOnConnectionError) {
+        throw err;
+      }
+
+      // Fail open: return non-blocking hit count
+      return {
+        totalHits: 1,
+        resetTime: new Date(Date.now() + this.windowMs)
+      };
+    }
+  }
+
+  /**
+   * Decrement hits for a key.
+   *
+   * @param {string} key
+   * @returns {Promise<void>}
+   */
+  async decrement(key) {
+    try {
+      const fullKey = this._prefixKey(key);
+      if (typeof this.client.decr === 'function') {
+        await this.client.decr(fullKey);
+      }
+    } catch (err) {
+      this.logger.warn('REDIS_STORE_ERROR', `Redis decrement failed: ${err.message}`, {
+        details: { key }
+      });
+    }
+  }
+
+  /**
+   * Reset hits for a single key.
+   *
+   * @param {string} key
+   * @returns {Promise<void>}
+   */
+  async resetKey(key) {
+    try {
+      const fullKey = this._prefixKey(key);
+      if (typeof this.client.del === 'function') {
+        await this.client.del(fullKey);
+      }
+    } catch (err) {
+      this.logger.warn('REDIS_STORE_ERROR', `Redis resetKey failed: ${err.message}`, {
+        details: { key }
+      });
+    }
+  }
+
+  /**
+   * Reset all keys matching prefix.
+   *
+   * @returns {Promise<void>}
+   */
+  async resetAll() {
+    try {
+      const pattern = `${this.prefix}*`;
+      let keys = [];
+
+      if (typeof this.client.keys === 'function') {
+        keys = await this.client.keys(pattern);
+      }
+
+      if (keys && keys.length > 0 && typeof this.client.del === 'function') {
+        await this.client.del(...keys);
+      }
+    } catch (err) {
+      this.logger.warn('REDIS_STORE_ERROR', `Redis resetAll failed: ${err.message}`);
+    }
+  }
+
+  /**
+   * Retrieve current hits for a key without incrementing.
+   *
+   * @param {string} key
+   * @returns {Promise<{ totalHits: number, resetTime: Date } | undefined>}
+   */
+  async get(key) {
+    try {
+      const fullKey = this._prefixKey(key);
+      const [hits, ttl] = await Promise.all([
+        this.client.get ? this.client.get(fullKey) : null,
+        this.client.pttl ? this.client.pttl(fullKey) : null
+      ]);
+
+      if (!hits) {
+        return undefined;
+      }
+
+      const totalHits = parseInt(hits, 10);
+      const ttlMs = parseInt(ttl, 10) || this.windowMs;
+
+      return {
+        totalHits,
+        resetTime: new Date(Date.now() + Math.max(0, ttlMs))
+      };
+    } catch (err) {
+      this.logger.warn('REDIS_STORE_ERROR', `Redis get failed: ${err.message}`);
+      return undefined;
+    }
+  }
+}
+
+module.exports = {
+  RedisStore
+};
+

package/src/types/index.d.ts

@@ -0,0 +1,313 @@
+import { Request, Response, NextFunction, RequestHandler } from 'express';
+
+declare global {
+  namespace Express {
+    interface Request {
+      apiKey?: {
+        id: string;
+        name?: string;
+        permissions: string[];
+        metadata: Record<string, any>;
+      };
+      clientIp?: string;
+      validated?: {
+        body?: any;
+        query?: any;
+        params?: any;
+        headers?: any;
+      };
+      detectedThreats?: Array<{
+        ruleId: string;
+        ruleName: string;
+        path: string;
+        snippet: string;
+        severity: string;
+      }>;
+      id?: string;
+    }
+  }
+}
+
+export interface SecurityErrorPayload {
+  success: false;
+  error: {
+    code: string;
+    message: string;
+    details?: any;
+  };
+}
+
+export class SecurityError extends Error {
+  statusCode: number;
+  code: string;
+  details: any;
+  constructor(message: string, statusCode?: number, code?: string, details?: any);
+  toJSON(): SecurityErrorPayload;
+}
+
+export class RateLimitError extends SecurityError {
+  constructor(message?: string, details?: any);
+}
+
+export class AuthenticationError extends SecurityError {
+  constructor(message?: string, details?: any);
+}
+
+export class ForbiddenError extends SecurityError {
+  constructor(message?: string, details?: any);
+}
+
+export class PayloadTooLargeError extends SecurityError {
+  constructor(message?: string, details?: any);
+}
+
+export class ValidationError extends SecurityError {
+  constructor(message?: string, details?: any);
+}
+
+export class ThreatDetectedError extends SecurityError {
+  constructor(message?: string, statusCode?: number, details?: any);
+}
+
+export class ConfigurationError extends SecurityError {
+  constructor(message: string, details?: any);
+}
+
+// Stores
+export interface RateLimitStoreRecord {
+  totalHits: number;
+  resetTime: Date;
+}
+
+export class MemoryStore {
+  constructor(options?: { windowMs?: number; cleanupIntervalMs?: number });
+  init(options: { windowMs?: number }): void;
+  increment(key: string): Promise<RateLimitStoreRecord>;
+  decrement(key: string): Promise<void>;
+  resetKey(key: string): Promise<void>;
+  resetAll(): Promise<void>;
+  get(key: string): Promise<RateLimitStoreRecord | undefined>;
+  shutdown(): void;
+}
+
+export class RedisStore {
+  constructor(options: {
+    client: any;
+    prefix?: string;
+    windowMs?: number;
+    passOnConnectionError?: boolean;
+    logger?: SecurityLogger;
+  });
+  init(options: { windowMs?: number }): void;
+  increment(key: string): Promise<RateLimitStoreRecord>;
+  decrement(key: string): Promise<void>;
+  resetKey(key: string): Promise<void>;
+  resetAll(): Promise<void>;
+  get(key: string): Promise<RateLimitStoreRecord | undefined>;
+}
+
+// Logger
+export interface SecurityLogEvent {
+  timestamp: string;
+  level: string;
+  eventType: string;
+  message: string;
+  requestId: string;
+  ip: string;
+  method?: string;
+  path?: string;
+  details?: Record<string, any>;
+}
+
+export class SecurityLogger {
+  constructor(options?: {
+    enabled?: boolean;
+    level?: 'debug' | 'info' | 'warn' | 'error' | 'silent';
+    customLogger?: (event: SecurityLogEvent) => void;
+    redactFields?: string[];
+  });
+  log(level: 'debug' | 'info' | 'warn' | 'error', eventType: string, message: string, context?: any): void;
+  debug(eventType: string, message: string, context?: any): void;
+  info(eventType: string, message: string, context?: any): void;
+  warn(eventType: string, message: string, context?: any): void;
+  error(eventType: string, message: string, context?: any): void;
+}
+
+export const defaultLogger: SecurityLogger;
+export function redact(value: any, customSensitiveKeys?: string[]): any;
+export function getRequestId(req: Request): string;
+export const DEFAULT_SENSITIVE_KEYS: string[];
+
+// Rate Limiter
+export interface RateLimiterOptions {
+  windowMs?: number;
+  maxRequests?: number;
+  max?: number;
+  statusCode?: number;
+  message?: string;
+  keyGenerator?: (req: Request) => string;
+  skip?: (req: Request) => boolean;
+  store?: 'memory' | 'redis' | any;
+  redisClient?: any;
+  redisPrefix?: string;
+  passOnRedisError?: boolean;
+  handler?: (req: Request, res: Response, error: RateLimitError) => void;
+  logger?: SecurityLogger;
+  standardHeaders?: boolean | 'draft-6' | 'draft-7';
+  legacyHeaders?: boolean;
+}
+
+export function rateLimiter(options?: RateLimiterOptions): RequestHandler;
+export function createRateLimiter(options?: RateLimiterOptions): RequestHandler;
+export function defaultKeyGenerator(req: Request): string;
+
+// API Key Auth
+export interface ApiKeyRecord {
+  id?: string;
+  name?: string;
+  key?: string;
+  hash?: string;
+  expiresAt?: string | Date | number | null;
+  permissions?: string[];
+  metadata?: Record<string, any>;
+}
+
+export interface ApiKeyAuthOptions {
+  headerName?: string;
+  queryParam?: string | null;
+  allowBearer?: boolean;
+  hashAlgorithm?: string;
+  keys?: Array<string | ApiKeyRecord>;
+  getKey?: (hash: string, req: Request) => Promise<ApiKeyRecord | null | undefined>;
+  verifyKey?: (rawKey: string, req: Request) => Promise<boolean | ApiKeyRecord>;
+  requiredPermissions?: string[];
+  statusCode?: number;
+  forbiddenStatusCode?: number;
+  message?: string;
+  forbiddenMessage?: string;
+  handler?: (req: Request, res: Response, error: SecurityError) => void;
+  logger?: SecurityLogger;
+}
+
+export function apiKeyAuth(options?: ApiKeyAuthOptions): RequestHandler;
+export function createApiKeyAuth(options?: ApiKeyAuthOptions): RequestHandler;
+export function extractApiKey(req: Request, options: ApiKeyAuthOptions): string | null;
+export function generateApiKey(options?: { prefix?: string; bytes?: number; algorithm?: string }): { key: string; hash: string; prefix: string };
+export function hashApiKey(rawKey: string, algorithm?: string): string;
+export function secureCompare(a: string, b: string): boolean;
+export function isKeyExpired(keyRecord: any): boolean;
+
+// IP Filter
+export interface IpFilterOptions {
+  mode?: 'allowlist' | 'blocklist';
+  allowlist?: string[];
+  blocklist?: string[];
+  trustProxy?: boolean | string[] | number;
+  getIp?: (req: Request) => string;
+  statusCode?: number;
+  message?: string;
+  handler?: (req: Request, res: Response, error: ForbiddenError) => void;
+  logger?: SecurityLogger;
+}
+
+export function ipFilter(options?: IpFilterOptions): RequestHandler;
+export function createIpFilter(options?: IpFilterOptions): RequestHandler;
+export function parseIp(ipString: string): any;
+export function parseRule(ruleString: string): any;
+export function matchesRule(clientIp: any, rule: any): boolean;
+export function isIpInRules(clientIpStr: string, compiledRules: any[]): boolean;
+export function compileRules(ruleStrings: string[]): any[];
+export function getClientIp(req: Request, options?: any): string;
+
+// Request Size
+export interface RequestSizeOptions {
+  maxSize?: string | number;
+  statusCode?: number;
+  message?: string;
+  handler?: (req: Request, res: Response, error: PayloadTooLargeError) => void;
+  logger?: SecurityLogger;
+}
+
+export function requestSize(options?: RequestSizeOptions): RequestHandler;
+export function createRequestSize(options?: RequestSizeOptions): RequestHandler;
+export function parseContentLength(req: Request): { length: number | null; error: string | null };
+
+// Security Headers
+export interface SecurityHeadersOptions {
+  contentSecurityPolicy?: boolean | any;
+  hsts?: boolean | any;
+  frameguard?: boolean | any;
+  noSniff?: boolean;
+  referrerPolicy?: boolean | any;
+  noIndex?: boolean;
+  permissionsPolicy?: boolean | string;
+  [key: string]: any;
+}
+
+export function securityHeaders(options?: SecurityHeadersOptions): RequestHandler;
+export function createSecurityHeaders(options?: SecurityHeadersOptions): RequestHandler;
+
+// Request Validator
+export interface ValidationSchemas {
+  body?: any;
+  query?: any;
+  params?: any;
+  headers?: any;
+}
+
+export interface RequestValidatorOptions {
+  assignToReq?: boolean;
+  statusCode?: number;
+  message?: string;
+  handler?: (req: Request, res: Response, error: ValidationError) => void;
+  logger?: SecurityLogger;
+}
+
+export function requestValidator(schemas: ValidationSchemas | any, options?: RequestValidatorOptions): RequestHandler;
+export function createRequestValidator(schemas: ValidationSchemas | any, options?: RequestValidatorOptions): RequestHandler;
+
+// Threat Detector
+export interface ThreatRule {
+  id: string;
+  name: string;
+  pattern: RegExp | ((val: any, path: string) => boolean);
+  severity: 'high' | 'medium' | 'low';
+}
+
+export interface ThreatMatch {
+  ruleId: string;
+  ruleName: string;
+  path: string;
+  snippet: string;
+  severity: string;
+}
+
+export interface ThreatDetectorOptions {
+  action?: 'reject' | 'log' | 'pass';
+  statusCode?: number;
+  message?: string;
+  inspectUrl?: boolean;
+  inspectQuery?: boolean;
+  inspectBody?: boolean;
+  inspectHeaders?: boolean;
+  whitelistedPaths?: Array<string | RegExp>;
+  whitelistedKeys?: string[];
+  customRules?: ThreatRule[];
+  handler?: (req: Request, res: Response, error: ThreatDetectedError) => void;
+  logger?: SecurityLogger;
+}
+
+export function threatDetector(options?: ThreatDetectorOptions): RequestHandler;
+export function createThreatDetector(options?: ThreatDetectorOptions): RequestHandler;
+export const DEFAULT_THREAT_PATTERNS: ThreatRule[];
+export function scanValue(value: any, rules: ThreatRule[], currentPath?: string, whitelistedKeys?: string[]): ThreatMatch[];
+
+// Helper
+export function sendSecurityResponse(
+  req: Request,
+  res: Response,
+  error: SecurityError | Error | string,
+  statusCode?: number,
+  customHandler?: (req: Request, res: Response, error: any) => void
+): void;
+

package/src/utils/errors.js

@@ -0,0 +1,88 @@
+'use strict';
+
+/**
+ * Base security error class.
+ */
+class SecurityError extends Error {
+  /**
+   * @param {string} message - Human-readable error message.
+   * @param {number} [statusCode=500] - HTTP status code.
+   * @param {string} [code='SECURITY_ERROR'] - Machine-readable error code.
+   * @param {Record<string, any>} [details=null] - Optional structured error details.
+   */
+  constructor(message, statusCode = 500, code = 'SECURITY_ERROR', details = null) {
+    super(message);
+    this.name = this.constructor.name;
+    this.statusCode = statusCode;
+    this.code = code;
+    this.details = details;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+
+  toJSON() {
+    return {
+      success: false,
+      error: {
+        code: this.code,
+        message: this.message,
+        ...(this.details ? { details: this.details } : {})
+      }
+    };
+  }
+}
+
+class RateLimitError extends SecurityError {
+  constructor(message = 'Too many requests, please try again later.', details = null) {
+    super(message, 429, 'RATE_LIMIT_EXCEEDED', details);
+  }
+}
+
+class AuthenticationError extends SecurityError {
+  constructor(message = 'Unauthorized: Invalid or missing API key.', details = null) {
+    super(message, 401, 'UNAUTHORIZED', details);
+  }
+}
+
+class ForbiddenError extends SecurityError {
+  constructor(message = 'Forbidden: Access denied.', details = null) {
+    super(message, 403, 'FORBIDDEN', details);
+  }
+}
+
+class PayloadTooLargeError extends SecurityError {
+  constructor(message = 'Payload Too Large: Request body exceeds maximum allowed size.', details = null) {
+    super(message, 413, 'PAYLOAD_TOO_LARGE', details);
+  }
+}
+
+class ValidationError extends SecurityError {
+  constructor(message = 'Validation failed: Invalid request parameters.', details = null) {
+    super(message, 400, 'VALIDATION_ERROR', details);
+  }
+}
+
+class ThreatDetectedError extends SecurityError {
+  constructor(message = 'Forbidden: Suspicious request pattern detected.', statusCode = 403, details = null) {
+    super(message, statusCode, 'THREAT_DETECTED', details);
+  }
+}
+
+class ConfigurationError extends SecurityError {
+  constructor(message, details = null) {
+    super(message, 500, 'CONFIGURATION_ERROR', details);
+  }
+}
+
+module.exports = {
+  SecurityError,
+  RateLimitError,
+  AuthenticationError,
+  ForbiddenError,
+  PayloadTooLargeError,
+  ValidationError,
+  ThreatDetectedError,
+  ConfigurationError
+};
+