nigerian-mobile-validator/dist/types/security/validator-security.d.ts

The most rigorous, up-to-date library for validating Nigerian mobile numbers. Fully NCC-compliant, and security-focused, with enterprise-grade features to prevent the business risks of validation failures in regulated industries.

import { ILogger } from '../logging/i-logger';
/**
 * Interface for a rolling window rate limiter.
 *
 * Concrete objects should provide a sophisticated rate limiting approach that:
 * 1. Uses a rolling time window instead of fixed windows
 * 2. Only tracks timestamps of recent requests to minimize memory usage
 * 3. Provides better protection against burst traffic
 */
export interface IRollingWindowRateLimiter {
    /**
     * Check if a new request should be allowed under the rate limit
     * @returns True if the request is allowed, false if it exceeds the rate limit
     */
    hasExceededLimit(): boolean;
    /**
     * Gets the number of requests in the current window
     */
    get currentCount(): number;
    /**
     * Gets the time in ms until the next request would be allowed
     * Returns 0 if requests are currently allowed
     */
    get timeUntilNextAllowed(): number;
}
/**
 * Security utilities for the Nigerian Mobile Number Validator
 *
 * This class provides security-focused utilities to enhance the validator's
 * resilience against potential security issues including input sanitization,
 * rate limiting, and logging protections.
 */
export declare class ValidatorSecurity {
    /**
     * Maximum allowed input length for phone numbers
     * This prevents excessive processing of extremely long inputs that could
     * cause performance issues or denial of service.
     */
    static readonly MAX_INPUT_LENGTH = 50;
    /**
     * Default maximum listeners for event emitter to prevent memory leaks
     * This limits the potential for memory leaks if many listeners are added
     * but not properly removed.
     */
    static readonly DEFAULT_MAX_LISTENERS = 10;
    /**
     * Sanitizes user input for secure processing
     *
     * This method:
     * 1. Limits input length to prevent resource exhaustion
     * 2. Removes control characters that could cause issues
     * 3. Handles standard phone number formatting characters
     * 4. Replaces 'o'/'O' with '0' which is a common user error
     *
     * @param userProvidedDigits Raw user input
     * @returns Sanitized input safe for further processing
     */
    static stripUnsafeInputs(userProvidedDigits: string): string;
    /**
     * Creates a rolling window rate limiter
     *
     * This implements a more sophisticated rate limiting approach that:
     * 1. Uses a rolling time window instead of fixed windows
     * 2. Only tracks timestamps of recent requests to minimize memory usage
     * 3. Provides better protection against burst traffic
     *
     * @param maxRequests Maximum number of requests allowed in the window
     * @param windowSizeMs Size of the rolling window in milliseconds (default: 60000ms = 1 minute)
     * @returns A rate limiter object with check() method to verify if a new request is allowed
     */
    static createRollingWindowRateLimiter(maxRequests: number, windowSizeMs?: number): IRollingWindowRateLimiter;
    /**
     * Masks a phone number for secure logging
     *
     * This prevents the full phone number from appearing in logs, which
     * could expose sensitive user information. It keeps only enough digits
     * to help with debugging while protecting privacy.
     *
     * @param phoneNumber The phone number to mask
     * @returns Masked version of the phone number with middle digits replaced by asterisks
     */
    static maskPhoneNumber(phoneNumber: string): string;
    /**
     * Creates a secure logger wrapper that masks sensitive information
     *
     * This wrapper ensures that phone numbers and other sensitive data are
     * automatically masked when logged, regardless of the log level.
     *
     * @param logger The original logger to wrap
     * @returns A secure logger with the same interface but with automatic masking
     */
    static createSecureLogger(logger: ILogger): ILogger;
    /**
     * Sanitizes a log message by masking potential phone numbers
     * @private
     */
    private static sanitizeLogMessage;
    /**
     * Sanitizes log metadata to mask sensitive information
     * @private
     */
    private static sanitizeLogMeta;
    /**
     * Recursively sanitizes an object to mask sensitive fields
     * @private
     */
    private static sanitizeLogObject;
    /**
     * Sanitizes an array's items
     * @private
     */
    private static sanitizeArray;
    /**
     * Sanitizes an object's properties
     * @private
     */
    private static sanitizeObjectProperties;
    /**
     * Fast, early rejection of obviously invalid inputs
     *
     * This method provides a quick check to reject inputs that are clearly not
     * valid phone numbers before doing more expensive processing. This improves
     * security by reducing the attack surface for crafted inputs.
     *
     * @param input The input to check
     * @returns true if the input should be rejected, false if it might be valid
     */
    static fastReject(input: string): boolean;
}