@axova/shared 1.0.0

package/src/lib/auditLogger.ts

@@ -0,0 +1,1117 @@
+import { performance } from "node:perf_hooks";
+import { createId } from "@paralleldrive/cuid2";
+
+// Re-export types from audit service for convenience
+export interface AuditLogEntry {
+	eventType:
+		| "CREATE"
+		| "UPDATE"
+		| "DELETE"
+		| "LOGIN"
+		| "LOGOUT"
+		| "ACCESS"
+		| "PERMISSION_CHANGE"
+		| "SYSTEM_ACTION"
+		| "COMPLIANCE_ACTION"
+		| "SECURITY_EVENT";
+	eventCategory:
+		| "USER_ACTION"
+		| "SYSTEM_ACTION"
+		| "ADMIN_ACTION"
+		| "COMPLIANCE_ACTION"
+		| "SECURITY_ACTION"
+		| "DATA_ACTION"
+		| "NOTIFICATION_ACTION";
+	action: string;
+	resource: string;
+	resourceId: string;
+	resourceType?:
+		| "STORE"
+		| "USER"
+		| "PRODUCT"
+		| "ORDER"
+		| "COMPLIANCE"
+		| "POLICY"
+		| "VIOLATION"
+		| "APPEAL"
+		| "NOTIFICATION"
+		| "SYSTEM"
+		| "OTHER";
+	performedBy: string;
+	performedByType:
+		| "USER"
+		| "SYSTEM"
+		| "ADMIN"
+		| "SERVICE"
+		| "AI"
+		| "AUTOMATION"
+		| "ANONYMOUS";
+	performedByName?: string;
+	sessionId?: string;
+	requestId?: string;
+	correlationId?: string;
+	ipAddress?: string;
+	userAgent?: string;
+	clientType?:
+		| "WEB"
+		| "MOBILE_APP"
+		| "API"
+		| "ADMIN_PANEL"
+		| "SYSTEM"
+		| "WEBHOOK"
+		| "CRON_JOB";
+	clientId?: string;
+	clientVersion?: string;
+	location?: {
+		country?: string;
+		region?: string;
+		city?: string;
+		coordinates?: { lat: number; lng: number };
+		timezone?: string;
+	};
+	changes?: {
+		before?: Record<string, unknown>;
+		after?: Record<string, unknown>;
+		fields?: string[];
+	};
+	metadata?: {
+		businessImpact?: string;
+		severity?: "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
+		tags?: string[];
+		department?: string;
+		project?: string;
+		feature?: string;
+		version?: string;
+		environment?: "DEVELOPMENT" | "STAGING" | "PRODUCTION";
+		customFields?: Record<string, unknown>;
+	};
+	success?: boolean;
+	errorCode?: string;
+	errorMessage?: string;
+	stackTrace?: string;
+	duration?: number;
+	size?: number;
+	sensitiveData?: boolean;
+	piiInvolved?: boolean;
+	complianceRelevant?: boolean;
+	retentionPeriod?: number;
+	riskLevel?: "NONE" | "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
+	securityImpact?: "NONE" | "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
+	workflowId?: string;
+	workflowStep?: string;
+	parentEventId?: string;
+	storeId?: string;
+	storeName?: string;
+	storeSubdomain?: string;
+}
+
+// Context interface for automatic enrichment
+export interface AuditContext {
+	serviceName: string;
+	serviceVersion?: string;
+	requestId?: string;
+	correlationId?: string;
+	sessionId?: string;
+	userId?: string;
+	userType?: "USER" | "ADMIN" | "SYSTEM" | "SERVICE";
+	ipAddress?: string;
+	userAgent?: string;
+	clientId?: string;
+	clientType?:
+		| "WEB"
+		| "MOBILE_APP"
+		| "API"
+		| "ADMIN_PANEL"
+		| "SYSTEM"
+		| "WEBHOOK"
+		| "CRON_JOB";
+	storeId?: string;
+	storeName?: string;
+	environment?: "DEVELOPMENT" | "STAGING" | "PRODUCTION";
+	features?: string[];
+	tags?: string[];
+	customMetadata?: Record<string, unknown>;
+}
+
+// Performance tracker for duration logging
+export interface PerformanceTracker {
+	start: number;
+	end(): number;
+	duration(): number;
+}
+
+// Audit logger configuration
+export interface AuditLoggerConfig {
+	serviceName: string;
+	serviceVersion?: string;
+	environment?: "DEVELOPMENT" | "STAGING" | "PRODUCTION";
+	auditServiceUrl?: string;
+	auditServiceApiKey?: string;
+	enableLocalLogging?: boolean;
+	enableRemoteLogging?: boolean;
+	bufferSize?: number;
+	flushInterval?: number;
+	defaultRetentionDays?: number;
+	autoEnrichment?: boolean;
+	sensitiveFieldMasking?: boolean;
+	geoLocationEnabled?: boolean;
+}
+
+// Quick action builders for common operations
+export interface QuickActionBuilders {
+	userLogin: (
+		userId: string,
+		additionalData?: Partial<AuditLogEntry>,
+	) => AuditLogEntry;
+	userLogout: (
+		userId: string,
+		additionalData?: Partial<AuditLogEntry>,
+	) => AuditLogEntry;
+	dataAccess: (
+		resource: string,
+		resourceId: string,
+		userId: string,
+		additionalData?: Partial<AuditLogEntry>,
+	) => AuditLogEntry;
+	dataCreate: (
+		resource: string,
+		resourceId: string,
+		userId: string,
+		data?: unknown,
+		additionalData?: Partial<AuditLogEntry>,
+	) => AuditLogEntry;
+	dataUpdate: (
+		resource: string,
+		resourceId: string,
+		userId: string,
+		changes?: unknown,
+		additionalData?: Partial<AuditLogEntry>,
+	) => AuditLogEntry;
+	dataDelete: (
+		resource: string,
+		resourceId: string,
+		userId: string,
+		additionalData?: Partial<AuditLogEntry>,
+	) => AuditLogEntry;
+	permissionChange: (
+		targetUserId: string,
+		changedBy: string,
+		changes: unknown,
+		additionalData?: Partial<AuditLogEntry>,
+	) => AuditLogEntry;
+	securityEvent: (
+		eventType: string,
+		description: string,
+		severity: "LOW" | "MEDIUM" | "HIGH" | "CRITICAL",
+		additionalData?: Partial<AuditLogEntry>,
+	) => AuditLogEntry;
+	complianceEvent: (
+		framework: string,
+		requirement: string,
+		status: "MET" | "NOT_MET",
+		additionalData?: Partial<AuditLogEntry>,
+	) => AuditLogEntry;
+	systemAction: (
+		action: string,
+		resource: string,
+		resourceId: string,
+		additionalData?: Partial<AuditLogEntry>,
+	) => AuditLogEntry;
+	storeAction: (
+		storeId: string,
+		action: string,
+		resource: string,
+		resourceId: string,
+		userId?: string,
+		additionalData?: Partial<AuditLogEntry>,
+	) => AuditLogEntry;
+}
+
+// Shared Audit Logger Class
+export class AuditLogger {
+	private config: AuditLoggerConfig;
+	private context: AuditContext;
+	private buffer: AuditLogEntry[] = [];
+	private flushTimer: NodeJS.Timeout | null = null;
+	private performanceTrackers = new Map<string, PerformanceTracker>();
+
+	constructor(
+		config: AuditLoggerConfig,
+		initialContext?: Partial<AuditContext>,
+	) {
+		this.config = {
+			bufferSize: 100,
+			flushInterval: 5000,
+			defaultRetentionDays: 2555,
+			autoEnrichment: true,
+			sensitiveFieldMasking: true,
+			geoLocationEnabled: false,
+			enableLocalLogging: true,
+			enableRemoteLogging: true,
+			...config,
+		};
+
+		this.context = {
+			serviceName: config.serviceName,
+			serviceVersion: config.serviceVersion,
+			environment:
+				config.environment ||
+				(process.env.NODE_ENV as "DEVELOPMENT" | "STAGING" | "PRODUCTION") ||
+				"DEVELOPMENT",
+			...initialContext,
+		};
+
+		this.setupAutoFlush();
+	}
+
+	// Update context (useful for request-scoped information)
+	updateContext(contextUpdate: Partial<AuditContext>): void {
+		this.context = { ...this.context, ...contextUpdate };
+	}
+
+	// Get current context
+	getContext(): AuditContext {
+		return { ...this.context };
+	}
+
+	// Log a custom audit event
+	async log(entry: Partial<AuditLogEntry>): Promise<string> {
+		try {
+			const enrichedEntry = await this.enrichEntry(entry);
+			const auditId = createId();
+
+			// Add to buffer
+			this.addToBuffer(enrichedEntry);
+
+			// Local logging
+			if (this.config.enableLocalLogging) {
+				this.logLocally(enrichedEntry, auditId);
+			}
+
+			// Check if immediate flush is needed for critical events
+			if (this.isCriticalEvent(enrichedEntry)) {
+				await this.flush();
+			}
+
+			return auditId;
+		} catch (error) {
+			console.error("Failed to log audit event:", error);
+			throw error;
+		}
+	}
+
+	// Performance tracking helpers
+	startPerformanceTracking(operationId?: string): string {
+		const id = operationId || createId();
+		const tracker: PerformanceTracker = {
+			start: performance.now(),
+			end: () => performance.now(),
+			duration: function () {
+				return this.end() - this.start;
+			},
+		};
+
+		this.performanceTrackers.set(id, tracker);
+		return id;
+	}
+
+	endPerformanceTracking(operationId: string): number {
+		const tracker = this.performanceTrackers.get(operationId);
+		if (tracker) {
+			const duration = tracker.duration();
+			this.performanceTrackers.delete(operationId);
+			return Math.round(duration);
+		}
+		return 0;
+	}
+
+	// Quick action builders
+	get quick(): QuickActionBuilders {
+		return {
+			userLogin: (userId: string, additionalData?: Partial<AuditLogEntry>) => ({
+				eventType: "LOGIN",
+				eventCategory: "USER_ACTION",
+				action: "user_login",
+				resource: "authentication",
+				resourceId: userId,
+				resourceType: "USER",
+				performedBy: userId,
+				performedByType: "USER",
+				riskLevel: "LOW",
+				complianceRelevant: true,
+				...additionalData,
+			}),
+
+			userLogout: (
+				userId: string,
+				additionalData?: Partial<AuditLogEntry>,
+			) => ({
+				eventType: "LOGOUT",
+				eventCategory: "USER_ACTION",
+				action: "user_logout",
+				resource: "authentication",
+				resourceId: userId,
+				resourceType: "USER",
+				performedBy: userId,
+				performedByType: "USER",
+				riskLevel: "NONE",
+				...additionalData,
+			}),
+
+			dataAccess: (
+				resource: string,
+				resourceId: string,
+				userId: string,
+				additionalData?: Partial<AuditLogEntry>,
+			) => ({
+				eventType: "ACCESS",
+				eventCategory: "DATA_ACTION",
+				action: "data_access",
+				resource,
+				resourceId,
+				performedBy: userId,
+				performedByType: "USER",
+				riskLevel: "LOW",
+				complianceRelevant: true,
+				...additionalData,
+			}),
+
+			dataCreate: (
+				resource: string,
+				resourceId: string,
+				userId: string,
+				data?: unknown,
+				additionalData?: Partial<AuditLogEntry>,
+			): AuditLogEntry => ({
+				eventType: "CREATE",
+				eventCategory: "DATA_ACTION",
+				action: "data_create",
+				resource,
+				resourceId,
+				performedBy: userId,
+				performedByType: "USER",
+				changes: data ? { after: data as Record<string, unknown> } : undefined,
+				riskLevel: "LOW",
+				...additionalData,
+			}),
+
+			dataUpdate: (
+				resource: string,
+				resourceId: string,
+				userId: string,
+				changes?: unknown,
+				additionalData?: Partial<AuditLogEntry>,
+			): AuditLogEntry => ({
+				eventType: "UPDATE",
+				eventCategory: "DATA_ACTION",
+				action: "data_update",
+				resource,
+				resourceId,
+				performedBy: userId,
+				performedByType: "USER",
+				changes: changes
+					? {
+							before: (changes as any)?.before,
+							after: (changes as any)?.after,
+							fields: (changes as any)?.fields,
+						}
+					: undefined,
+				riskLevel: "MEDIUM",
+				...additionalData,
+			}),
+
+			dataDelete: (
+				resource: string,
+				resourceId: string,
+				userId: string,
+				additionalData?: Partial<AuditLogEntry>,
+			) => ({
+				eventType: "DELETE",
+				eventCategory: "DATA_ACTION",
+				action: "data_delete",
+				resource,
+				resourceId,
+				performedBy: userId,
+				performedByType: "USER",
+				riskLevel: "HIGH",
+				complianceRelevant: true,
+				...additionalData,
+			}),
+
+			permissionChange: (
+				targetUserId: string,
+				changedBy: string,
+				changes: unknown,
+				additionalData?: Partial<AuditLogEntry>,
+			): AuditLogEntry => ({
+				eventType: "PERMISSION_CHANGE",
+				eventCategory: "ADMIN_ACTION",
+				action: "permission_change",
+				resource: "user_permissions",
+				resourceId: targetUserId,
+				performedBy: changedBy,
+				performedByType: "ADMIN",
+				changes: changes
+					? {
+							before: (changes as any)?.before,
+							after: (changes as any)?.after,
+							fields: (changes as any)?.fields,
+						}
+					: undefined,
+				riskLevel: "HIGH",
+				securityImpact: "MEDIUM",
+				...additionalData,
+			}),
+
+			securityEvent: (
+				eventType: string,
+				description: string,
+				severity: "LOW" | "MEDIUM" | "HIGH" | "CRITICAL",
+				additionalData?: Partial<AuditLogEntry>,
+			) => ({
+				eventType: "SECURITY_EVENT",
+				eventCategory: "SECURITY_ACTION",
+				action: eventType,
+				resource: "security",
+				resourceId: createId(),
+				performedBy: "SYSTEM",
+				performedByType: "SYSTEM",
+				riskLevel: severity,
+				securityImpact: severity,
+				metadata: {
+					severity,
+					description,
+					businessImpact:
+						severity === "CRITICAL"
+							? "Service disruption possible"
+							: "Monitoring required",
+				},
+				...additionalData,
+			}),
+
+			complianceEvent: (
+				framework: string,
+				requirement: string,
+				status: "MET" | "NOT_MET",
+				additionalData?: Partial<AuditLogEntry>,
+			) => ({
+				eventType: "COMPLIANCE_ACTION",
+				eventCategory: "COMPLIANCE_ACTION",
+				action: "compliance_check",
+				resource: "compliance_requirement",
+				resourceId: `${framework}_${requirement}`,
+				performedBy: "SYSTEM",
+				performedByType: "SYSTEM",
+				complianceRelevant: true,
+				riskLevel: status === "NOT_MET" ? "HIGH" : "LOW",
+				metadata: {
+					framework,
+					requirement,
+					status,
+					businessImpact:
+						status === "NOT_MET"
+							? "Compliance violation detected"
+							: "Compliance maintained",
+				},
+				...additionalData,
+			}),
+
+			systemAction: (
+				action: string,
+				resource: string,
+				resourceId: string,
+				additionalData?: Partial<AuditLogEntry>,
+			) => ({
+				eventType: "SYSTEM_ACTION",
+				eventCategory: "SYSTEM_ACTION",
+				action,
+				resource,
+				resourceId,
+				performedBy: this.context.serviceName,
+				performedByType: "SYSTEM",
+				riskLevel: "NONE",
+				...additionalData,
+			}),
+
+			storeAction: (
+				storeId: string,
+				action: string,
+				resource: string,
+				resourceId: string,
+				userId?: string,
+				additionalData?: Partial<AuditLogEntry>,
+			) => ({
+				eventType: "UPDATE",
+				eventCategory: userId ? "USER_ACTION" : "SYSTEM_ACTION",
+				action,
+				resource,
+				resourceId,
+				resourceType: "STORE",
+				performedBy: userId || this.context.serviceName,
+				performedByType: userId ? "USER" : "SYSTEM",
+				storeId,
+				riskLevel: "LOW",
+				...additionalData,
+			}),
+		};
+	}
+
+	// Convenience methods for common audit events
+	async logUserLogin(
+		userId: string,
+		additionalData?: Partial<AuditLogEntry>,
+	): Promise<string> {
+		return this.log(this.quick.userLogin(userId, additionalData));
+	}
+
+	async logUserLogout(
+		userId: string,
+		additionalData?: Partial<AuditLogEntry>,
+	): Promise<string> {
+		return this.log(this.quick.userLogout(userId, additionalData));
+	}
+
+	async logDataAccess(
+		resource: string,
+		resourceId: string,
+		userId: string,
+		additionalData?: Partial<AuditLogEntry>,
+	): Promise<string> {
+		return this.log(
+			this.quick.dataAccess(resource, resourceId, userId, additionalData),
+		);
+	}
+
+	async logDataCreate(
+		resource: string,
+		resourceId: string,
+		userId: string,
+		data?: unknown,
+		additionalData?: Partial<AuditLogEntry>,
+	): Promise<string> {
+		return this.log(
+			this.quick.dataCreate(resource, resourceId, userId, data, additionalData),
+		);
+	}
+
+	async logDataUpdate(
+		resource: string,
+		resourceId: string,
+		userId: string,
+		changes?: unknown,
+		additionalData?: Partial<AuditLogEntry>,
+	): Promise<string> {
+		return this.log(
+			this.quick.dataUpdate(
+				resource,
+				resourceId,
+				userId,
+				changes,
+				additionalData,
+			),
+		);
+	}
+
+	async logDataDelete(
+		resource: string,
+		resourceId: string,
+		userId: string,
+		additionalData?: Partial<AuditLogEntry>,
+	): Promise<string> {
+		return this.log(
+			this.quick.dataDelete(resource, resourceId, userId, additionalData),
+		);
+	}
+
+	async logSecurityEvent(
+		eventType: string,
+		description: string,
+		severity: "LOW" | "MEDIUM" | "HIGH" | "CRITICAL",
+		additionalData?: Partial<AuditLogEntry>,
+	): Promise<string> {
+		return this.log(
+			this.quick.securityEvent(
+				eventType,
+				description,
+				severity,
+				additionalData,
+			),
+		);
+	}
+
+	async logStoreAction(
+		storeId: string,
+		action: string,
+		resource: string,
+		resourceId: string,
+		userId?: string,
+		additionalData?: Partial<AuditLogEntry>,
+	): Promise<string> {
+		return this.log(
+			this.quick.storeAction(
+				storeId,
+				action,
+				resource,
+				resourceId,
+				userId,
+				additionalData,
+			),
+		);
+	}
+
+	// Wrapper for async operations with automatic audit logging
+	async auditedOperation<T>(
+		operationName: string,
+		operation: () => Promise<T>,
+		auditData: Partial<AuditLogEntry>,
+	): Promise<{ result: T; auditId: string; duration: number }> {
+		const trackingId = this.startPerformanceTracking();
+		const _startTime = Date.now();
+
+		try {
+			const result = await operation();
+			const duration = this.endPerformanceTracking(trackingId);
+
+			const _auditId = await this.log({
+				...auditData,
+				action: operationName,
+				success: true,
+				duration,
+			});
+
+			return { result, auditId: _auditId, duration };
+		} catch (error) {
+			const duration = this.endPerformanceTracking(trackingId);
+
+			const _auditId = await this.log({
+				...auditData,
+				action: operationName,
+				success: false,
+				duration,
+				errorMessage: error instanceof Error ? error.message : "Unknown error",
+				stackTrace: error instanceof Error ? error.stack : undefined,
+				riskLevel: "MEDIUM",
+			});
+
+			throw error;
+		}
+	}
+
+	// Bulk logging for batch operations
+	async logBatch(entries: Partial<AuditLogEntry>[]): Promise<string[]> {
+		try {
+			const enrichedEntries = await Promise.all(
+				entries.map((entry) => this.enrichEntry(entry)),
+			);
+
+			const auditIds = enrichedEntries.map(() => createId());
+
+			// Add all to buffer
+			enrichedEntries.forEach((entry) => this.addToBuffer(entry));
+
+			// Local logging
+			if (this.config.enableLocalLogging) {
+				enrichedEntries.forEach((entry, index) => {
+					this.logLocally(entry, auditIds[index]);
+				});
+			}
+
+			// Check if any critical events require immediate flush
+			const hasCriticalEvents = enrichedEntries.some((entry) =>
+				this.isCriticalEvent(entry),
+			);
+			if (hasCriticalEvents) {
+				await this.flush();
+			}
+
+			return auditIds;
+		} catch (error) {
+			console.error("Failed to log batch audit events:", error);
+			throw error;
+		}
+	}
+
+	// Flush buffer manually
+	async flush(): Promise<void> {
+		if (this.buffer.length === 0) return;
+
+		try {
+			const entriesToFlush = this.buffer.splice(0);
+
+			if (this.config.enableRemoteLogging) {
+				await this.sendToAuditService(entriesToFlush);
+			}
+
+			console.log(`✅ Flushed ${entriesToFlush.length} audit log entries`);
+		} catch (error) {
+			console.error("Failed to flush audit log buffer:", error);
+			// Re-add entries to buffer for retry
+			this.buffer.unshift(...this.buffer);
+			throw error;
+		}
+	}
+
+	// Private helper methods
+
+	private async enrichEntry(
+		entry: Partial<AuditLogEntry>,
+	): Promise<AuditLogEntry> {
+		const baseEntry: AuditLogEntry = {
+			eventType: entry.eventType || "SYSTEM_ACTION",
+			eventCategory: entry.eventCategory || "SYSTEM_ACTION",
+			action: entry.action || "unknown_action",
+			resource: entry.resource || "unknown_resource",
+			resourceId: entry.resourceId || createId(),
+			performedBy: entry.performedBy || this.context.serviceName,
+			performedByType: entry.performedByType || "SYSTEM",
+			success: entry.success ?? true,
+			riskLevel: entry.riskLevel || "NONE",
+			securityImpact: entry.securityImpact || "NONE",
+			retentionPeriod:
+				entry.retentionPeriod || this.config.defaultRetentionDays,
+			...entry,
+		};
+
+		// Auto-enrichment from context
+		if (this.config.autoEnrichment) {
+			if (this.context.requestId && !baseEntry.requestId) {
+				baseEntry.requestId = this.context.requestId;
+			}
+			if (this.context.correlationId && !baseEntry.correlationId) {
+				baseEntry.correlationId = this.context.correlationId;
+			}
+			if (this.context.sessionId && !baseEntry.sessionId) {
+				baseEntry.sessionId = this.context.sessionId;
+			}
+			if (this.context.ipAddress && !baseEntry.ipAddress) {
+				baseEntry.ipAddress = this.context.ipAddress;
+			}
+			if (this.context.userAgent && !baseEntry.userAgent) {
+				baseEntry.userAgent = this.context.userAgent;
+			}
+			if (this.context.clientId && !baseEntry.clientId) {
+				baseEntry.clientId = this.context.clientId;
+			}
+			if (this.context.clientType && !baseEntry.clientType) {
+				baseEntry.clientType = this.context.clientType;
+			}
+			if (this.context.storeId && !baseEntry.storeId) {
+				baseEntry.storeId = this.context.storeId;
+			}
+			if (this.context.storeName && !baseEntry.storeName) {
+				baseEntry.storeName = this.context.storeName;
+			}
+
+			// Enrich metadata
+			if (!baseEntry.metadata) {
+				baseEntry.metadata = {};
+			}
+
+			baseEntry.metadata.environment = this.context.environment;
+			baseEntry.metadata.version = this.context.serviceVersion;
+
+			if (this.context.features?.length) {
+				baseEntry.metadata.tags = [
+					...(baseEntry.metadata.tags || []),
+					...this.context.features,
+				];
+			}
+
+			if (this.context.tags?.length) {
+				baseEntry.metadata.tags = [
+					...(baseEntry.metadata.tags || []),
+					...this.context.tags,
+				];
+			}
+
+			if (this.context.customMetadata) {
+				baseEntry.metadata.customFields = {
+					...baseEntry.metadata.customFields,
+					...this.context.customMetadata,
+				};
+			}
+		}
+
+		// Mask sensitive data if enabled
+		if (this.config.sensitiveFieldMasking) {
+			baseEntry.changes = this.maskSensitiveData(
+				baseEntry.changes,
+			) as typeof baseEntry.changes;
+			baseEntry.metadata = this.maskSensitiveData(
+				baseEntry.metadata,
+			) as typeof baseEntry.metadata;
+		}
+
+		return baseEntry;
+	}
+
+	private addToBuffer(entry: AuditLogEntry): void {
+		this.buffer.push(entry);
+
+		if (this.buffer.length >= (this.config.bufferSize || 100)) {
+			setImmediate(() => this.flush());
+		}
+	}
+
+	private logLocally(entry: AuditLogEntry, auditId: string): void {
+		const logLevel = this.getLogLevel(entry);
+		const message = `AUDIT [${auditId}] ${entry.action} on ${entry.resource}:${entry.resourceId} by ${entry.performedBy}`;
+
+		switch (logLevel) {
+			case "error":
+				console.error(message, { auditEntry: entry });
+				break;
+			case "warn":
+				console.warn(message, { auditEntry: entry });
+				break;
+			default:
+				console.log(message, { auditEntry: entry });
+				break;
+		}
+	}
+
+	private getLogLevel(entry: AuditLogEntry): "error" | "warn" | "info" {
+		if (
+			!entry.success ||
+			entry.riskLevel === "CRITICAL" ||
+			entry.securityImpact === "CRITICAL"
+		) {
+			return "error";
+		}
+		if (entry.riskLevel === "HIGH" || entry.securityImpact === "HIGH") {
+			return "warn";
+		}
+		return "info";
+	}
+
+	private isCriticalEvent(entry: AuditLogEntry): boolean {
+		return (
+			entry.riskLevel === "CRITICAL" ||
+			entry.securityImpact === "CRITICAL" ||
+			entry.eventCategory === "SECURITY_ACTION" ||
+			(entry.success === false && entry.eventType === "LOGIN")
+		);
+	}
+
+	private async sendToAuditService(entries: AuditLogEntry[]): Promise<void> {
+		if (!this.config.auditServiceUrl) return;
+
+		try {
+			const response = await fetch(
+				`${this.config.auditServiceUrl}/audit/bulk`,
+				{
+					method: "POST",
+					headers: {
+						"Content-Type": "application/json",
+						...(this.config.auditServiceApiKey && {
+							Authorization: `Bearer ${this.config.auditServiceApiKey}`,
+						}),
+					},
+					body: JSON.stringify({ entries }),
+				},
+			);
+
+			if (!response.ok) {
+				throw new Error(
+					`Audit service responded with status: ${response.status}`,
+				);
+			}
+		} catch (error) {
+			console.error("Failed to send audit logs to audit service:", error);
+			throw error;
+		}
+	}
+
+	private maskSensitiveData(data: unknown): unknown {
+		if (!data || typeof data !== "object") {
+			return data;
+		}
+
+		const sensitiveKeys = [
+			"password",
+			"token",
+			"secret",
+			"key",
+			"ssn",
+			"credit",
+			"card",
+			"bank",
+			"account",
+		];
+
+		const masked = { ...(data as Record<string, unknown>) };
+
+		Object.keys(masked).forEach((key) => {
+			const lowerKey = key.toLowerCase();
+			if (sensitiveKeys.some((sensitive) => lowerKey.includes(sensitive))) {
+				masked[key] = "[MASKED]";
+			} else if (typeof masked[key] === "object" && masked[key] !== null) {
+				masked[key] = this.maskSensitiveData(masked[key]);
+			}
+		});
+
+		return masked;
+	}
+
+	private setupAutoFlush(): void {
+		if (this.config.flushInterval && this.config.flushInterval > 0) {
+			this.flushTimer = setInterval(() => {
+				if (this.buffer.length > 0) {
+					this.flush().catch((error) => {
+						console.error("Auto-flush failed:", error);
+					});
+				}
+			}, this.config.flushInterval);
+		}
+	}
+
+	// Cleanup
+	async shutdown(): Promise<void> {
+		try {
+			if (this.flushTimer) {
+				clearInterval(this.flushTimer);
+				this.flushTimer = null;
+			}
+
+			// Flush any remaining entries
+			if (this.buffer.length > 0) {
+				await this.flush();
+			}
+
+			console.log("✅ Audit Logger shutdown complete");
+		} catch (error) {
+			console.error("❌ Error during audit logger shutdown:", error);
+		}
+	}
+}
+
+// Factory function for creating audit logger instances
+export function createAuditLogger(
+	config: AuditLoggerConfig,
+	initialContext?: Partial<AuditContext>,
+): AuditLogger {
+	return new AuditLogger(config, initialContext);
+}
+
+// Middleware factory for Express/Fastify request context
+export function createAuditMiddleware(logger: AuditLogger) {
+	return (req: any, _res: unknown, next: () => void) => {
+		const requestId = req.headers?.["x-request-id"] || createId();
+		const correlationId = req.headers?.["x-correlation-id"];
+		const sessionId = req.headers?.["x-session-id"] || req.session?.id;
+
+		// Update audit context for this request
+		logger.updateContext({
+			requestId,
+			correlationId,
+			sessionId,
+			ipAddress: req.ip || req.connection?.remoteAddress,
+			userAgent: req.headers?.["user-agent"],
+			userId: req.user?.id,
+			userType: req.user?.type,
+			clientId: req.headers?.["x-client-id"],
+			clientType: req.headers?.["x-client-type"] as
+				| "WEB"
+				| "MOBILE_APP"
+				| "API"
+				| "ADMIN_PANEL"
+				| "SYSTEM"
+				| "WEBHOOK"
+				| "CRON_JOB"
+				| undefined,
+		});
+
+		// Attach audit logger to request for easy access
+		(req as any).audit = logger;
+
+		next();
+	};
+}
+
+// Export convenience functions
+export async function logAuditEvent(
+	serviceName: string,
+	entry: Partial<AuditLogEntry>,
+	context?: Partial<AuditContext>,
+): Promise<string> {
+	const logger = createAuditLogger({ serviceName }, context);
+	return logger.log(entry);
+}
+
+export async function logStoreAuditEvent(
+	serviceName: string,
+	storeId: string,
+	action: string,
+	resource: string,
+	resourceId: string,
+	userId?: string,
+	additionalData?: Partial<AuditLogEntry>,
+): Promise<string> {
+	const logger = createAuditLogger({ serviceName }, { storeId });
+	return logger.logStoreAction(
+		storeId,
+		action,
+		resource,
+		resourceId,
+		userId,
+		additionalData,
+	);
+}
+
+// Default audit logger instance (can be configured once and reused)
+let defaultLogger: AuditLogger | null = null;
+
+export function setDefaultAuditLogger(logger: AuditLogger): void {
+	defaultLogger = logger;
+}
+
+export function getDefaultAuditLogger(): AuditLogger {
+	if (!defaultLogger) {
+		throw new Error(
+			"Default audit logger not configured. Call setDefaultAuditLogger() first.",
+		);
+	}
+	return defaultLogger;
+}
+
+// Quick logging functions using default logger
+export async function quickLog(entry: Partial<AuditLogEntry>): Promise<string> {
+	return getDefaultAuditLogger().log(entry);
+}
+
+export async function quickLogUserAction(
+	action: string,
+	resource: string,
+	resourceId: string,
+	userId: string,
+	additionalData?: Partial<AuditLogEntry>,
+): Promise<string> {
+	return getDefaultAuditLogger().log({
+		eventType: "UPDATE",
+		eventCategory: "USER_ACTION",
+		action,
+		resource,
+		resourceId,
+		performedBy: userId,
+		performedByType: "USER",
+		...additionalData,
+	});
+}
+
+export async function quickLogSystemAction(
+	action: string,
+	resource: string,
+	resourceId: string,
+	additionalData?: Partial<AuditLogEntry>,
+): Promise<string> {
+	return getDefaultAuditLogger().log({
+		eventType: "SYSTEM_ACTION",
+		eventCategory: "SYSTEM_ACTION",
+		action,
+		resource,
+		resourceId,
+		performedBy: "SYSTEM",
+		performedByType: "SYSTEM",
+		...additionalData,
+	});
+}