/**
 * File Organizer MCP Server v3.4.2
 * Audit Logger Service
 *
 * Comprehensive audit logging for all file read operations.
 * SECURITY: Every file read MUST be logged through this service.
 *
 * @module readers/security/audit-logger.service
 * @security Shepherd-Gamma Approved
 */
/**
 * Valid audit log operation types
 */
export type AuditOperation = "FILE_READ" | "FILE_READ_CHUNK" | "FILE_STAT" | "FILE_VALIDATE" | "FILE_ACCESS_CHECK" | "DIRECTORY_LIST" | "VALIDATION_FAILURE" | "RATE_LIMIT_EXCEEDED";
/**
 * Valid audit log result statuses
 */
export type AuditResult = "SUCCESS" | "FAILURE" | "BLOCKED" | "RATE_LIMITED" | "ERROR";
/**
 * Audit log entry structure.
 * All file read operations must create and log one of these entries.
 */
export interface AuditLogEntry {
    /** ISO 8601 timestamp of the operation */
    readonly timestamp: string;
    /** Type of operation performed */
    readonly operation: AuditOperation;
    /** File or directory path (sanitized for sensitive patterns) */
    readonly path: string;
    /** User or session identifier */
    readonly userId: string;
    /** Result status of the operation */
    readonly result: AuditResult;
    /** Number of bytes read (0 for non-read operations) */
    readonly bytesRead: number;
    /** SHA-256 checksum of file content (if applicable) */
    readonly checksum?: string;
    /** Additional context and metadata */
    readonly metadata?: Record<string, unknown>;
    /** Error message if result is FAILURE or ERROR */
    readonly errorMessage?: string;
    /** Duration of operation in milliseconds */
    readonly durationMs?: number;
    /** Session identifier for grouping related operations */
    readonly sessionId?: string;
    /** Client IP or identifier */
    readonly clientId?: string;
}
/**
 * Interface for audit logger implementations.
 * All file readers must use an implementation of this interface.
 */
export interface IAuditLogger {
    /**
     * Log a file read operation.
     * This method MUST be called for every file read.
     *
     * @param entry - Complete audit log entry
     */
    logFileRead(entry: AuditLogEntry): void;
    /**
     * Log a validation failure.
     * Convenience method for logging security validation failures.
     *
     * @param path - The path that failed validation
     * @param reason - Human-readable failure reason
     * @param metadata - Additional context
     */
    logValidationFailure(path: string, reason: string, metadata?: Record<string, unknown>): void;
    /**
     * Log a rate limit exceeded event.
     *
     * @param identifier - The rate limit identifier (user/session)
     * @param resetIn - Seconds until rate limit resets
     */
    logRateLimitExceeded(identifier: string, resetIn: number): void;
    /**
     * Create a new audit log entry with current timestamp.
     * Utility method for building entries.
     *
     * @param partialEntry - Partial entry without timestamp
     * @returns Complete audit log entry
     */
    createEntry(partialEntry: Omit<AuditLogEntry, "timestamp">): AuditLogEntry;
}
/**
 * Audit Logger Service implementation.
 * Provides structured JSON logging for all file operations.
 *
 * @example
 * ```typescript
 * const auditLogger = new AuditLoggerService();
 *
 * // Log a successful file read
 * auditLogger.logFileRead(auditLogger.createEntry({
 *   operation: 'FILE_READ',
 *   path: '/docs/report.pdf',
 *   userId: 'user123',
 *   result: 'SUCCESS',
 *   bytesRead: 1024,
 *   checksum: 'abc123...'
 * }));
 *
 * // Log a validation failure
 * auditLogger.logValidationFailure('/etc/shadow', 'Sensitive file access blocked');
 * ```
 */
export declare class AuditLoggerService implements IAuditLogger {
    private readonly component;
    private readonly options;
    private readonly defaultUserId;
    private readonly sessionId;
    constructor(component?: string, options?: {
        /** Include full stack traces in error logs */
        includeStackTrace?: boolean;
        /** Redact sensitive paths in logs */
        redactSensitivePaths?: boolean;
    });
    /**
     * Generate a unique session identifier.
     */
    private generateSessionId;
    /**
     * Log a complete audit entry.
     * All file read operations MUST call this method.
     *
     * @param entry - The audit log entry to record
     */
    logFileRead(entry: AuditLogEntry): void;
    /**
     * Log a validation failure event.
     * Use this when security validation prevents a file operation.
     *
     * @param path - The path that failed validation
     * @param reason - Human-readable failure reason
     * @param metadata - Additional context
     */
    logValidationFailure(path: string, reason: string, metadata?: Record<string, unknown>): void;
    /**
     * Log a rate limit exceeded event.
     *
     * @param identifier - The rate limit identifier (user/session)
     * @param resetIn - Seconds until rate limit resets
     */
    logRateLimitExceeded(identifier: string, resetIn: number): void;
    /**
     * Create a new audit log entry with current timestamp.
     * Helper method for building complete entries.
     *
     * @param partialEntry - Entry data without timestamp
     * @returns Complete audit log entry with timestamp
     */
    createEntry(partialEntry: Omit<AuditLogEntry, "timestamp">): AuditLogEntry;
    /**
     * Log file read start (async operations).
     * Use for long-running operations to track start time.
     *
     * @param path - File being read
     * @param operation - Type of operation
     * @returns Start time marker for calculating duration
     */
    logOperationStart(path: string, operation: AuditOperation): number;
    /**
     * Log file read completion with duration.
     * Use with logOperationStart for accurate timing.
     *
     * @param startTime - Value returned by logOperationStart
     * @param entry - Complete audit entry
     */
    logOperationComplete(startTime: number, entry: Omit<AuditLogEntry, "timestamp" | "durationMs">): void;
    /**
     * Log file read error with full context.
     *
     * @param path - File path
     * @param error - Error that occurred
     * @param operation - Type of operation that failed
     */
    logError(path: string, error: Error | unknown, operation?: AuditOperation): void;
    /**
     * Get current session ID for correlation.
     */
    getSessionId(): string;
}
/**
 * Singleton audit logger instance for default use.
 * Applications can create custom instances for different components.
 */
export declare const defaultAuditLogger: AuditLoggerService;
/**
 * Factory function for creating component-specific audit loggers.
 *
 * @param component - Component name for log attribution
 * @param options - Logger configuration options
 * @returns Configured AuditLoggerService instance
 */
export declare function createAuditLogger(component: string, options?: {
    includeStackTrace?: boolean;
    redactSensitivePaths?: boolean;
}): AuditLoggerService;
//# sourceMappingURL=audit-logger.service.d.ts.map