@revealui/security 0.2.3 → 0.2.5

package/dist/index.d.ts

@@ -54,6 +54,11 @@ declare class AuditSystem {
     private storage;
     private filters;
     constructor(storage: AuditStorage);
+    /**
+     * Replace the backing storage (e.g. swap InMemory for Postgres at startup).
+     * Events already written to the old storage are NOT migrated.
+     */
+    setStorage(storage: AuditStorage): void;
     /**
      * Log audit event
      */
@@ -181,11 +186,154 @@ declare class AuditReportGenerator {
      */
     private checkAuditTrailContinuity;
 }
+/** Fields included in the HMAC signature for tamper detection. */
+interface SignableFields {
+    timestamp: string;
+    eventType: string;
+    severity: string;
+    agentId: string;
+    payload: unknown;
+}
+/**
+ * Compute an HMAC-SHA256 signature over the canonical fields of an audit entry.
+ *
+ * The signature covers `timestamp`, `eventType`, `severity`, `agentId`, and
+ * `payload` — the immutable core of every audit record. Changing any of
+ * these fields after signing will cause verification to fail.
+ *
+ * @param entry - The audit entry fields to sign
+ * @param secret - The HMAC secret key
+ * @returns Hex-encoded HMAC-SHA256 signature
+ */
+declare function signAuditEntry(entry: SignableFields, secret: string): Promise<string>;
+/**
+ * Verify an HMAC-SHA256 signature against the canonical fields of an audit entry.
+ *
+ * Uses timing-safe comparison to prevent timing attacks.
+ *
+ * @param entry - The audit entry fields to verify
+ * @param signature - The hex-encoded HMAC-SHA256 signature to verify
+ * @param secret - The HMAC secret key
+ * @returns True if the signature is valid
+ */
+declare function verifyAuditEntry(entry: SignableFields, signature: string, secret: string): Promise<boolean>;
 /**
  * Global audit system
  */
 declare const audit: AuditSystem;
 
+/**
+ * Security Alerting Service
+ *
+ * Evaluates audit events against configurable threshold rules and
+ * dispatches alerts through pluggable handlers (logging, audit trail,
+ * webhook / SIEM integration).
+ */
+
+/** A security alert produced when a threshold is breached. */
+interface SecurityAlert {
+    /** Alert rule that triggered (e.g. 'failedLogins', 'accountLockout'). */
+    type: string;
+    /** Severity of the alert. */
+    severity: AuditSeverity;
+    /** Human-readable description. */
+    message: string;
+    /** Contextual data attached to the alert. */
+    context: Record<string, unknown>;
+    /** When the alert was raised (ISO-8601). */
+    timestamp: string;
+}
+/** Handler that receives dispatched security alerts. */
+interface AlertHandler {
+    /** Process a single alert. */
+    handle(alert: SecurityAlert): Promise<void>;
+}
+/** Configuration for a single threshold rule. */
+interface ThresholdRule {
+    /** Maximum event count before an alert fires. */
+    maxCount: number;
+    /** Sliding window duration in milliseconds. */
+    windowMs: number;
+    /** Severity assigned to alerts from this rule. */
+    severity: AuditSeverity;
+    /** Human-readable message template — `{count}` is replaced at runtime. */
+    messageTemplate: string;
+}
+/** Top-level configuration for the alerting service. */
+interface AlertingConfig {
+    /** Threshold rules keyed by rule name. */
+    thresholds: Record<string, ThresholdRule>;
+    /** Handlers that receive dispatched alerts. */
+    handlers: AlertHandler[];
+}
+/** Default threshold rules aligned with SOC2 6.2 requirements. */
+declare const DEFAULT_THRESHOLDS: Record<string, ThresholdRule>;
+/**
+ * Logs alerts to the structured security logger.
+ */
+declare class LogAlertHandler implements AlertHandler {
+    /** Write alert details to the configured security logger. */
+    handle(alert: SecurityAlert): Promise<void>;
+}
+/**
+ * Writes alerts as critical audit events into the audit log.
+ */
+declare class AuditAlertHandler implements AlertHandler {
+    /** Record the alert in the audit trail with severity 'critical'. */
+    handle(alert: SecurityAlert): Promise<void>;
+}
+/**
+ * POSTs alerts to a configurable webhook URL for SIEM integration.
+ */
+declare class WebhookAlertHandler implements AlertHandler {
+    private url;
+    private headers;
+    /**
+     * Create a webhook alert handler.
+     *
+     * @param url - The webhook endpoint URL
+     * @param headers - Additional HTTP headers (e.g. authorization)
+     */
+    constructor(url: string, headers?: Record<string, string>);
+    /** POST the alert payload to the configured webhook URL. */
+    handle(alert: SecurityAlert): Promise<void>;
+}
+/**
+ * Evaluates audit events against threshold rules and dispatches alerts.
+ *
+ * Maintains an in-memory sliding window per rule/group key. When the
+ * event count within the window exceeds the threshold, an alert is
+ * dispatched to all configured handlers.
+ */
+declare class SecurityAlertService {
+    private config;
+    private windows;
+    /**
+     * Create a new SecurityAlertService.
+     *
+     * @param config - Alerting configuration with thresholds and handlers
+     */
+    constructor(config: AlertingConfig);
+    /**
+     * Evaluate a single audit event against all threshold rules.
+     * If a threshold is breached, dispatches alerts to all handlers.
+     *
+     * @param event - The audit event to evaluate
+     * @returns The alert that was dispatched, or null if no threshold was breached
+     */
+    evaluateEvent(event: AuditEvent): Promise<SecurityAlert | null>;
+    /**
+     * Clear all sliding window state. Useful for testing.
+     */
+    reset(): void;
+    /**
+     * Dispatch an alert to all configured handlers.
+     * Errors in individual handlers are logged but do not prevent
+     * other handlers from receiving the alert.
+     */
+    private dispatchAlert;
+}
+
 /**
  * Authentication Utilities
  *
@@ -1356,4 +1504,4 @@ interface SecurityLogger {
  */
 declare function configureSecurityLogger(logger: SecurityLogger): void;
 
-export { type AuditEvent, type AuditEventType, type AuditQuery, AuditReportGenerator, type AuditSeverity, type AuditStorage, AuditSystem, AuditTrail, type AuthorizationContext, AuthorizationSystem, type BreachStorage, type CORSConfig, CORSManager, CORSPresets, CommonRoles, ConsentManager, type ConsentRecord, type ConsentType, type ContentSecurityPolicyConfig, type CookieConsentConfig, CookieConsentManager, DataAnonymization, type DataBreach, DataBreachManager, type DataCategory, type DataDeletionRequest, DataDeletionSystem, DataExportSystem, DataMasking, type DataProcessingPurpose, type EncryptedData, type EncryptionConfig, EncryptionSystem, EnvelopeEncryption, FieldEncryption, type GDPRStorage, type HSTSConfig, InMemoryAuditStorage, InMemoryBreachStorage, InMemoryGDPRStorage, KeyRotationManager, OAuthClient, type OAuthConfig, OAuthProviders, PasswordHasher, type Permission, PermissionBuilder, PermissionCache, type PermissionsPolicyConfig, type PersonalDataExport, type Policy, PolicyBuilder, type PolicyCondition, PrivacyPolicyManager, type ReferrerPolicyValue, RequirePermission, RequireRole, type Role, SecurityHeaders, type SecurityHeadersConfig, type SecurityLogger, SecurityPresets, TokenGenerator, TwoFactorAuth, type User, audit, authorization, canAccessResource, checkAttributeAccess, configureSecurityLogger, cookieConsentManager, createAuditMiddleware, createAuthorizationMiddleware, createConsentManager, createDataBreachManager, createDataDeletionSystem, createSecurityMiddleware, dataExportSystem, encryption, permissionCache, privacyPolicyManager, setRateLimitHeaders };
+export { type AlertHandler, type AlertingConfig, AuditAlertHandler, type AuditEvent, type AuditEventType, type AuditQuery, AuditReportGenerator, type AuditSeverity, type AuditStorage, AuditSystem, AuditTrail, type AuthorizationContext, AuthorizationSystem, type BreachStorage, type CORSConfig, CORSManager, CORSPresets, CommonRoles, ConsentManager, type ConsentRecord, type ConsentType, type ContentSecurityPolicyConfig, type CookieConsentConfig, CookieConsentManager, DEFAULT_THRESHOLDS, DataAnonymization, type DataBreach, DataBreachManager, type DataCategory, type DataDeletionRequest, DataDeletionSystem, DataExportSystem, DataMasking, type DataProcessingPurpose, type EncryptedData, type EncryptionConfig, EncryptionSystem, EnvelopeEncryption, FieldEncryption, type GDPRStorage, type HSTSConfig, InMemoryAuditStorage, InMemoryBreachStorage, InMemoryGDPRStorage, KeyRotationManager, LogAlertHandler, OAuthClient, type OAuthConfig, OAuthProviders, PasswordHasher, type Permission, PermissionBuilder, PermissionCache, type PermissionsPolicyConfig, type PersonalDataExport, type Policy, PolicyBuilder, type PolicyCondition, PrivacyPolicyManager, type ReferrerPolicyValue, RequirePermission, RequireRole, type Role, type SecurityAlert, SecurityAlertService, SecurityHeaders, type SecurityHeadersConfig, type SecurityLogger, SecurityPresets, type ThresholdRule, TokenGenerator, TwoFactorAuth, type User, WebhookAlertHandler, audit, authorization, canAccessResource, checkAttributeAccess, configureSecurityLogger, cookieConsentManager, createAuditMiddleware, createAuthorizationMiddleware, createConsentManager, createDataBreachManager, createDataDeletionSystem, createSecurityMiddleware, dataExportSystem, encryption, permissionCache, privacyPolicyManager, setRateLimitHeaders, signAuditEntry, verifyAuditEntry };