@lock-dev/payload-guard/dist/index.d.ts

Payload guard detection module for lock.dev security framework

import * as _lock_dev_core from '@lock-dev/core';

declare enum PayloadGuardEventType {
    XSS_DETECTED = "xss-detected",
    SQL_INJECTION_DETECTED = "sql-injection-detected",
    COMMAND_INJECTION_DETECTED = "command-injection-detected",
    PATH_TRAVERSAL_DETECTED = "path-traversal-detected",
    GENERAL_INJECTION_DETECTED = "general-injection-detected",
    SSRF_DETECTED = "ssrf-detected"
}
/**
 * Configuration options
 */
interface PayloadGuardConfig {
    /**
     * Block mode: 'detect' only logs, 'block' prevents the request
     * @default 'block'
     */
    mode: 'detect' | 'block';
    /**
     * Custom status code to return when blocking a request
     * @default 403
     */
    blockStatusCode?: number;
    /**
     * Custom message to return when blocking a request
     * @default 'Request blocked due to potential security threat'
     */
    blockMessage?: string;
    /**
     * What to check in the request
     * @default ['params', 'query', 'body', 'headers']
     */
    checkParts?: Array<'params' | 'query' | 'body' | 'headers' | 'cookies'>;
    /**
     * Request headers to exclude from checking
     * @default ['authorization', 'cookie', 'set-cookie']
     */
    excludeHeaders?: string[];
    /**
     * Fields to exclude from checking
     * @default []
     */
    excludeFields?: string[];
    /**
     * Whether to check for XSS attacks
     * @default true
     */
    detectXSS?: boolean;
    /**
     * Whether to check for SSRF attacks
     * @default true
     */
    detectSSRF?: boolean;
    /**
     * Whether to check for SQL injection attacks
     * @default true
     */
    detectSQLi?: boolean;
    /**
     * Whether to check for command injection attacks
     * @default true
     */
    detectCommandInjection?: boolean;
    /**
     * Whether to check for path traversal attacks
     * @default true
     */
    detectPathTraversal?: boolean;
    /**
     * Enable result caching to improve performance
     * @default true
     */
    enableCaching?: boolean;
    /**
     * Cache TTL in milliseconds
     * @default 3600000 (1 hour)
     */
    cacheTtl?: number;
    /**
     * Cache size (max number of entries)
     * @default 10000
     */
    cacheSize?: number;
    /**
     * Behavior when a check fails
     * @default 'open' - allow request on failure
     */
    failBehavior?: 'open' | 'closed';
}
/**
 * Result of a payload security check
 */
interface PayloadCheckResult {
    /**
     * Whether an injection attack was detected
     */
    detected: boolean;
    /**
     * Type of injection if detected
     */
    type?: PayloadGuardEventType;
    /**
     * Path where the injection was detected
     */
    path?: string;
    /**
     * Value that triggered the detection
     */
    value?: string;
    /**
     * Pattern that matched
     */
    pattern?: RegExp;
}

/**
 * Recursively traverses an object to check each string value for injection attacks
 * @param obj The object to check
 * @param path Current path in the object (for reporting)
 * @param detectors Array of detector functions to run
 * @param excludeFields Fields to exclude from checking
 */
declare function traverseAndCheck(obj: any, path: string | undefined, detectors: Array<(value: string) => PayloadCheckResult>, excludeFields?: string[]): PayloadCheckResult;

/**
 * Checks if a value contains a command injection attack
 */
declare function detectCommandInjection(value: string): PayloadCheckResult;

/**
 * Generate a hash for a string value
 * Used for caching detection results
 */
declare function generateHash(str: string): string;

/**
 * Checks if a value contains a NoSQL injection attack
 */
declare function detectNoSQLi(value: string): PayloadCheckResult;

/**
 * Checks if a value contains a path traversal attack
 */
declare function detectPathTraversal(value: string): PayloadCheckResult;

/**
 * Checks if a value contains an SQL injection attack
 */
declare function detectSQLi(value: string): PayloadCheckResult;

declare function detectSSRF(value: string): PayloadCheckResult;

declare function detectTemplateInjection(value: string): PayloadCheckResult;

/**
 * Checks if a value contains an XSS attack
 */
declare function detectXSS(value: string): PayloadCheckResult;

declare const PATTERNS: {
    xss: RegExp[];
    sqli: RegExp[];
    commandInjection: RegExp[];
    pathTraversal: RegExp[];
    nosql: RegExp[];
    templateInjection: RegExp[];
};

/**
 * Create a PayloadGuard security module to protect against injection attacks
 * @param config Module configuration
 */
declare const payloadGuard: (config?: Partial<PayloadGuardConfig> | undefined) => _lock_dev_core.SecurityModule;

export { PATTERNS, type PayloadCheckResult, type PayloadGuardConfig, PayloadGuardEventType, detectCommandInjection, detectNoSQLi, detectPathTraversal, detectSQLi, detectSSRF, detectTemplateInjection, detectXSS, generateHash, payloadGuard, traverseAndCheck };