/**
 * Security Scanner Types
 *
 * Types and interfaces for the automated security scanning system
 *
 * @module types/security-scanner
 */

/**
 * Severity levels for security vulnerabilities
 */
export type VulnerabilitySeverity = 'critical' | 'high' | 'medium' | 'low' | 'info';

/**
 * Status of a security check
 */
export type SecurityCheckStatus = 'pass' | 'fail' | 'warning' | 'error' | 'skipped' | 'info';

/**
 * Category of security check
 */
export type SecurityCheckCategory =
  | 'authentication'
  | 'authorization'
  | 'rate_limiting'
  | 'csrf'
  | 'headers'
  | 'ssl'
  | 'injection'
  | 'xss'
  | 'data_exposure'
  | 'configuration'
  | 'dependencies'
  | 'endpoints'
  | 'code_analysis'
  | 'cryptographic'
  | 'session'
  | 'ssrf';

/**
 * Individual security check result
 */
export interface SecurityCheckResult {
  /** Unique identifier for this check */
  id: string;
  /** Human-readable name of the check */
  name: string;
  /** Category of this security check */
  category: SecurityCheckCategory;
  /** Status of the check */
  status: SecurityCheckStatus;
  /** Severity if vulnerability is found */
  severity: VulnerabilitySeverity;
  /** Detailed description of the check */
  description: string;
  /** Remediation advice if failed */
  remediation?: string;
  /** Additional details or error message */
  details?: string;
  /** Affected endpoint or resource */
  affectedResource?: string;
  /** Time taken to run this check in ms */
  duration: number;
  /** Timestamp when check was performed */
  timestamp: Date;
}

/**
 * Vulnerability detected by the scanner
 */
export interface Vulnerability {
  /** Unique identifier */
  id: string;
  /** Title of the vulnerability */
  title: string;
  /** Severity level */
  severity: VulnerabilitySeverity;
  /** Category */
  category: SecurityCheckCategory;
  /** Detailed description */
  description: string;
  /** How to fix this vulnerability */
  remediation: string;
  /** Affected resources */
  affectedResources: string[];
  /** CVSS score if applicable (0-10) */
  cvssScore?: number;
  /** CVE identifier if known */
  cveId?: string;
  /** CWE identifier if known */
  cweId?: string;
  /** References for more information */
  references?: string[];
  /** When this was first detected */
  firstDetected: Date;
  /** When this was last seen */
  lastSeen: Date;
}

/**
 * Summary of a security scan
 */
export interface SecurityScanSummary {
  /** Total number of checks performed */
  totalChecks: number;
  /** Number of checks passed */
  passed: number;
  /** Number of checks failed */
  failed: number;
  /** Number of warnings */
  warnings: number;
  /** Number of errors (check couldn't run) */
  errors: number;
  /** Number of skipped checks */
  skipped: number;
  /** Vulnerability counts by severity */
  vulnerabilities: {
    critical: number;
    high: number;
    medium: number;
    low: number;
    info: number;
  };
  /** Overall security score (0-100) */
  securityScore: number;
  /** Risk level based on findings */
  riskLevel: 'critical' | 'high' | 'medium' | 'low' | 'minimal';
}

/**
 * Complete security scan result
 */
export interface SecurityScanResult {
  /** Unique scan identifier */
  scanId: string;
  /** When the scan started */
  startedAt: Date;
  /** When the scan completed */
  completedAt: Date;
  /** Duration in milliseconds */
  duration: number;
  /** Summary of findings */
  summary: SecurityScanSummary;
  /** All check results */
  checks: SecurityCheckResult[];
  /** Detected vulnerabilities */
  vulnerabilities: Vulnerability[];
  /** Environment scanned */
  environment: 'development' | 'staging' | 'production';
  /** Base URL that was scanned */
  baseUrl: string;
  /** Scanner version */
  scannerVersion: string;
}

/**
 * Configuration for the security scanner
 */
export interface SecurityScannerConfig {
  /** Base URL to scan */
  baseUrl: string;
  /** Categories to include (all if empty) */
  includeCategories?: SecurityCheckCategory[];
  /** Categories to exclude */
  excludeCategories?: SecurityCheckCategory[];
  /** Timeout for each check in ms */
  checkTimeout: number;
  /** Maximum concurrent checks */
  maxConcurrent: number;
  /** Whether to send email alerts */
  sendAlerts: boolean;
  /** Email addresses for alerts */
  alertEmails: string[];
  /** Minimum severity to trigger alerts */
  alertSeverityThreshold: VulnerabilitySeverity;
  /** Whether to store results in database */
  storeResults: boolean;
}

/**
 * Security alert email data
 */
export interface SecurityAlertEmailData {
  /** Recipient email */
  to: string;
  /** Scan result */
  scanResult: SecurityScanResult;
  /** Whether this is an immediate alert (critical) or summary */
  alertType: 'immediate' | 'summary';
  /** Previous scan for comparison */
  previousScan?: SecurityScanResult;
}

/**
 * Endpoint security check configuration
 */
export interface EndpointCheckConfig {
  /** Endpoint path */
  path: string;
  /** HTTP method */
  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
  /** Description of what this endpoint does */
  description: string;
  /** Expected authentication requirement */
  requiresAuth: boolean;
  /** Expected CSRF protection */
  requiresCSRF: boolean;
  /** Expected rate limiting */
  requiresRateLimit: boolean;
  /** Custom headers to send */
  headers?: Record<string, string>;
  /** Test payload for POST/PUT/PATCH */
  testPayload?: unknown;
}

/**
 * Rate limit test result
 */
export interface RateLimitTestResult {
  /** Endpoint tested */
  endpoint: string;
  /** Whether rate limiting is active */
  isRateLimited: boolean;
  /** Number of requests before limit */
  requestsBeforeLimit?: number;
  /** Time window in seconds */
  windowSeconds?: number;
  /** Whether limit headers are present */
  hasLimitHeaders: boolean;
}

/**
 * Header security check
 */
export interface HeaderSecurityResult {
  /** Header name */
  header: string;
  /** Whether it's present */
  present: boolean;
  /** Current value if present */
  value?: string;
  /** Expected/recommended value */
  expectedValue?: string;
  /** Whether the value is secure */
  isSecure: boolean;
  /** Recommendation */
  recommendation?: string;
}

/**
 * Stored security scan record for database
 */
export interface SecurityScanRecord {
  id: string;
  scanId: string;
  environment: string;
  baseUrl: string;
  startedAt: Date;
  completedAt: Date;
  duration: number;
  securityScore: number;
  riskLevel: string;
  totalChecks: number;
  passed: number;
  failed: number;
  criticalCount: number;
  highCount: number;
  mediumCount: number;
  lowCount: number;
  alertsSent: boolean;
  metadata: Record<string, unknown>;
  createdAt: Date;
}
