@pawells/nestjs-shared 1.0.0-dev.4c8c698

package/build/common/services/audit-logger.service.d.ts

@@ -0,0 +1,91 @@
+import { ModuleRef } from '@nestjs/core';
+import { LazyModuleRefService } from '../utils/lazy-getter.types.js';
+import { AppLogger } from './logger.service.js';
+/**
+ * Audit log entry for security events.
+ */
+export interface AuditLogEntry {
+    timestamp: Date;
+    userId?: string;
+    action: string;
+    resource: string;
+    result: 'success' | 'failure';
+    details?: Record<string, any>;
+    ipAddress?: string;
+    userAgent?: string;
+}
+/**
+ * Audit Logger Service.
+ * Specialized logging for security-related events: authentication, authorization, token operations,
+ * CSRF violations, rate limiting, and configuration changes.
+ *
+ * All audit events are logged at INFO level (or WARN for failures) with structured JSON data
+ * for easy parsing by log aggregation systems (Loki, Splunk, etc.).
+ *
+ * @remarks
+ * - Automatically redacts sensitive fields (passwords, tokens) via AppLogger
+ * - All events include ISO timestamps and structured event data
+ * - Integrates with log aggregation for compliance and forensics
+ * - Available globally via CommonModule
+ *
+ * @example
+ * ```typescript
+ * // Log authentication attempt
+ * auditLogger.logAuthenticationAttempt('user@example.com', true, '192.168.1.1');
+ *
+ * // Log CSRF violation
+ * auditLogger.logCsrfViolation('192.168.1.1', '/api/users');
+ *
+ * // Log custom security event
+ * auditLogger.logSecurityEvent({
+ *   userId: 'user-123',
+ *   action: 'delete_user',
+ *   resource: 'users/456',
+ *   result: 'failure',
+ *   ipAddress: '192.168.1.1'
+ * });
+ * ```
+ */
+export declare class AuditLoggerService implements LazyModuleRefService {
+    private _contextualLogger;
+    readonly Module: ModuleRef;
+    constructor(module: ModuleRef);
+    get Logger(): AppLogger;
+    /**
+     * Log authentication attempt
+     */
+    logAuthenticationAttempt(email: string, success: boolean, ipAddress?: string, reason?: string): void;
+    /**
+     * Log authorization failure
+     */
+    logAuthorizationFailure(userId: string, resource: string, action: string, ipAddress?: string): void;
+    /**
+     * Log token generation
+     */
+    logTokenGeneration(userId: string, tokenType: 'access' | 'refresh'): void;
+    /**
+     * Log token revocation
+     */
+    logTokenRevocation(userId: string, reason: string): void;
+    /**
+     * Log rate limit violation
+     */
+    logRateLimitViolation(endpoint: string, ipAddress: string, limit: number): void;
+    /**
+     * Log CSRF violation
+     */
+    logCsrfViolation(ipAddress: string, endpoint: string): void;
+    /**
+     * Log security configuration change
+     */
+    logConfigurationChange(userId: string, config: string, oldValue: any, newValue: any): void;
+    /**
+     * Log data access
+     */
+    logDataAccess(userId: string, resource: string, action: string): void;
+    /**
+     * Log security event
+     */
+    logSecurityEvent(entry: AuditLogEntry): void;
+}
+//# sourceMappingURL=audit-logger.service.d.ts.map

package/build/common/services/audit-logger.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-logger.service.d.ts","sourceRoot":"","sources":["../../../src/common/services/audit-logger.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAGhD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,SAAS,EAAE,IAAI,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,SAAS,GAAG,SAAS,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBACa,kBAAmB,YAAW,oBAAoB;IAC9D,OAAO,CAAC,iBAAiB,CAAwB;IAEjD,SAAgB,MAAM,EAAE,SAAS,CAAC;gBAEtB,MAAM,EAAE,SAAS;IAI7B,IAAW,MAAM,IAAI,SAAS,CAM7B;IAED;;OAEG;IACI,wBAAwB,CAC9B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,OAAO,EAChB,SAAS,CAAC,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,GACb,IAAI;IAeP;;OAEG;IACI,uBAAuB,CAC7B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,MAAM,GAChB,IAAI;IAeP;;OAEG;IACI,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,GAAG,SAAS,GAAG,IAAI;IAahF;;OAEG;IACI,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAa/D;;OAEG;IACI,qBAAqB,CAC3B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACX,IAAI;IAcP;;OAEG;IACI,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAalE;;OAEG;IACI,sBAAsB,CAC5B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,GAAG,EACb,QAAQ,EAAE,GAAG,GACX,IAAI;IAeP;;OAEG;IACI,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAc5E;;OAEG;IACI,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;CAUnD"}

package/build/common/services/audit-logger.service.js

@@ -0,0 +1,180 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var AuditLoggerService_1;
+import { Injectable } from '@nestjs/common';
+import { ModuleRef } from '@nestjs/core';
+import { AppLogger } from './logger.service.js';
+import { escapeNewlines } from '../utils/sanitization.utils.js';
+/**
+ * Audit Logger Service.
+ * Specialized logging for security-related events: authentication, authorization, token operations,
+ * CSRF violations, rate limiting, and configuration changes.
+ *
+ * All audit events are logged at INFO level (or WARN for failures) with structured JSON data
+ * for easy parsing by log aggregation systems (Loki, Splunk, etc.).
+ *
+ * @remarks
+ * - Automatically redacts sensitive fields (passwords, tokens) via AppLogger
+ * - All events include ISO timestamps and structured event data
+ * - Integrates with log aggregation for compliance and forensics
+ * - Available globally via CommonModule
+ *
+ * @example
+ * ```typescript
+ * // Log authentication attempt
+ * auditLogger.logAuthenticationAttempt('user@example.com', true, '192.168.1.1');
+ *
+ * // Log CSRF violation
+ * auditLogger.logCsrfViolation('192.168.1.1', '/api/users');
+ *
+ * // Log custom security event
+ * auditLogger.logSecurityEvent({
+ *   userId: 'user-123',
+ *   action: 'delete_user',
+ *   resource: 'users/456',
+ *   result: 'failure',
+ *   ipAddress: '192.168.1.1'
+ * });
+ * ```
+ */
+let AuditLoggerService = AuditLoggerService_1 = class AuditLoggerService {
+    _contextualLogger;
+    Module;
+    constructor(module) {
+        this.Module = module;
+    }
+    get Logger() {
+        if (!this._contextualLogger) {
+            const baseLogger = this.Module.get(AppLogger);
+            this._contextualLogger = baseLogger.createContextualLogger(AuditLoggerService_1.name);
+        }
+        return this._contextualLogger;
+    }
+    /**
+     * Log authentication attempt
+     */
+    logAuthenticationAttempt(email, success, ipAddress, reason) {
+        const auditData = {
+            event: 'authentication',
+            email,
+            success,
+            ipAddress,
+            reason,
+            timestamp: new Date().toISOString(),
+        };
+        this.Logger.info(`Authentication ${success ? 'SUCCESS' : 'FAILURE'}: ${escapeNewlines(email)}${reason ? ` - ${escapeNewlines(reason)}` : ''} | ${JSON.stringify(auditData)}`, 'AuditLogger');
+    }
+    /**
+     * Log authorization failure
+     */
+    logAuthorizationFailure(userId, resource, action, ipAddress) {
+        const auditData = {
+            event: 'authorization_failure',
+            userId,
+            resource,
+            action,
+            ipAddress,
+            timestamp: new Date().toISOString(),
+        };
+        this.Logger.warn(`Authorization FAILURE: User ${escapeNewlines(userId)} attempted ${escapeNewlines(action)} on ${escapeNewlines(resource)} | ${JSON.stringify(auditData)}`, 'AuditLogger');
+    }
+    /**
+     * Log token generation
+     */
+    logTokenGeneration(userId, tokenType) {
+        const auditData = {
+            event: 'token_generation',
+            userId,
+            tokenType,
+            timestamp: new Date().toISOString(),
+        };
+        this.Logger.info(`Token GENERATED: ${tokenType} token for user ${escapeNewlines(userId)} | ${JSON.stringify(auditData)}`, 'AuditLogger');
+    }
+    /**
+     * Log token revocation
+     */
+    logTokenRevocation(userId, reason) {
+        const auditData = {
+            event: 'token_revocation',
+            userId,
+            reason,
+            timestamp: new Date().toISOString(),
+        };
+        this.Logger.info(`Token REVOCATION: User ${escapeNewlines(userId)} - ${escapeNewlines(reason)} | ${JSON.stringify(auditData)}`, 'AuditLogger');
+    }
+    /**
+     * Log rate limit violation
+     */
+    logRateLimitViolation(endpoint, ipAddress, limit) {
+        const auditData = {
+            event: 'rate_limit_violation',
+            endpoint,
+            ipAddress,
+            limit,
+            timestamp: new Date().toISOString(),
+        };
+        this.Logger.warn(`Rate LIMIT VIOLATION: ${escapeNewlines(endpoint)} from ${escapeNewlines(ipAddress)} (limit: ${limit}/min) | ${JSON.stringify(auditData)}`, 'AuditLogger');
+    }
+    /**
+     * Log CSRF violation
+     */
+    logCsrfViolation(ipAddress, endpoint) {
+        const auditData = {
+            event: 'csrf_violation',
+            ipAddress,
+            endpoint,
+            timestamp: new Date().toISOString(),
+        };
+        this.Logger.warn(`CSRF VIOLATION: ${escapeNewlines(endpoint)} from ${escapeNewlines(ipAddress)} | ${JSON.stringify(auditData)}`, 'AuditLogger');
+    }
+    /**
+     * Log security configuration change
+     */
+    logConfigurationChange(userId, config, oldValue, newValue) {
+        const auditData = {
+            event: 'config_change',
+            userId,
+            config,
+            oldValue,
+            newValue,
+            timestamp: new Date().toISOString(),
+        };
+        this.Logger.info(`Configuration CHANGE: ${escapeNewlines(config)} modified by ${escapeNewlines(userId)} | ${JSON.stringify(auditData)}`, 'AuditLogger');
+    }
+    /**
+     * Log data access
+     */
+    logDataAccess(userId, resource, action) {
+        const auditData = {
+            event: 'data_access',
+            userId,
+            resource,
+            action,
+            timestamp: new Date().toISOString(),
+        };
+        this.Logger.info(`Data ACCESS: User ${escapeNewlines(userId)} ${escapeNewlines(action)} ${escapeNewlines(resource)} | ${JSON.stringify(auditData)}`, 'AuditLogger');
+    }
+    /**
+     * Log security event
+     */
+    logSecurityEvent(entry) {
+        const auditData = {
+            ...entry,
+            timestamp: new Date().toISOString(),
+        };
+        this.Logger.info(`Security EVENT: ${escapeNewlines(entry.action)} on ${escapeNewlines(entry.resource)} - ${entry.result} | ${JSON.stringify(auditData)}`, 'AuditLogger');
+    }
+};
+AuditLoggerService = AuditLoggerService_1 = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [ModuleRef])
+], AuditLoggerService);
+export { AuditLoggerService };
+//# sourceMappingURL=audit-logger.service.js.map

package/build/common/services/audit-logger.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-logger.service.js","sourceRoot":"","sources":["../../../src/common/services/audit-logger.service.ts"],"names":[],"mappings":"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"}

package/build/common/services/csrf.service.d.ts

@@ -0,0 +1,202 @@
+import { OnModuleInit, OnModuleDestroy } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { Request, Response, NextFunction } from 'express';
+/**
+ * Configuration options for CSRF protection.
+ */
+export interface CSRFServiceOptions {
+    /**
+     * Whether to trust X-Forwarded-For header for client IP detection.
+     * Set to true when running behind a reverse proxy (nginx, Apache, load balancer, etc.)
+     * to correctly identify the real client IP for rate limiting.
+     *
+     * Security note: Only enable if your reverse proxy is trusted and properly configured
+     * to set X-Forwarded-For. Enabling this on an untrusted proxy allows IP spoofing attacks.
+     *
+     * Default: false (use direct socket IP)
+     */
+    trustProxy?: boolean;
+}
+/**
+ * CSRF Service.
+ * Provides CSRF token generation and validation using the Double Submit Cookie pattern.
+ * Uses cryptographic signing and per-session/IP binding for secure token verification.
+ *
+ * Features:
+ * - Double-CSRF token pattern (cookie + request header/body)
+ * - Per-IP rate limiting: 10 tokens per 60 seconds
+ * - Session binding (when available) or IP-based fallback
+ * - Automatic pruning of stale timestamps
+ * - Capacity monitoring with safety margin (80% threshold)
+ * - SSL-only, HTTPOnly cookies in production
+ *
+ * Configuration requirements:
+ * - CSRF_SECRET: Min 32 characters, cryptographically random, high entropy
+ * - Express app with cookie parser middleware
+ * - Optional: trustProxy for reverse proxy environments
+ *
+ * @remarks
+ * - In-memory rate limiting supports ~10,000 concurrent IPs per instance
+ * - For distributed deployments, use Redis-backed SharedThrottlerModule instead
+ * - Token generation timeout: 30 seconds (queue timeout)
+ * - Token timestamp pruning interval: 10 seconds
+ * - IP map capacity threshold: 80% (8,000 IPs) before pruning
+ * - Returns 503 Service Unavailable if at capacity after pruning
+ * - Returns 429 Too Many Requests if rate limit exceeded
+ *
+ * @example
+ * ```typescript
+ * // Generate token for form
+ * const token = await csrfService.generateToken(req, res);
+ * res.render('form', { csrfToken: token });
+ *
+ * // Validate incoming request (done automatically by CSRFGuard)
+ * const isValid = csrfService.validateToken(req);
+ *
+ * // Refresh token after sensitive operation (login, password change)
+ * const newToken = await csrfService.refreshToken(req, res);
+ * ```
+ */
+export declare class CSRFService implements OnModuleInit, OnModuleDestroy {
+    private readonly configService?;
+    private static readonly MIN_SECRET_LENGTH;
+    private static readonly MIN_CHARACTER_SET_DIVERSITY;
+    private static readonly ANONYMOUS_TOKEN_RANDOMNESS_BYTES;
+    private static readonly RATE_LIMIT_WINDOW_MS;
+    private static readonly RATE_LIMIT_COUNT;
+    /**
+     * Maximum number of unique IP addresses tracked for rate limiting.
+     * This in-memory strategy supports ~10,000 concurrent IPs per instance.
+     *
+     * **Scaling guidance**: For deployments exceeding 10,000 concurrent unique IPs,
+     * migrate to a Redis-backed rate limiting solution via SharedThrottlerModule:
+     * - Configure SharedThrottlerModule with Redis backend
+     * - Adjust limits and TTL for your traffic pattern
+     *
+     * **Memory management**: When the tracked IPs map reaches 80% capacity
+     * (8,000 IPs), the pruning logic removes stale entries (>60s old).
+     * If after pruning the map remains >= 10,000 IPs, token generation is
+     * rejected with HTTP 503 to prevent unbounded memory growth.
+     * The 80% threshold provides a safety margin before hard limits are hit.
+     *
+     * @see SharedThrottlerModule for Redis-backed distributed rate limiting
+     */
+    private static readonly MAX_TRACKED_IPS;
+    private static readonly TIMESTAMP_PRUNING_INTERVAL_MS;
+    private static readonly IP_LOCK_TIMEOUT_MS;
+    private static readonly CAPACITY_THRESHOLD_PERCENT;
+    private csrfProtection;
+    private readonly logger;
+    private readonly tokenGenTimestamps;
+    private readonly ipLocks;
+    private readonly trustProxy;
+    private capacityThresholdCrossedCount;
+    private pruneIntervalHandle;
+    private _isPruning;
+    constructor(configService?: ConfigService | undefined, options?: CSRFServiceOptions);
+    /**
+     * NestJS lifecycle hook: validate required CSRF_SECRET environment variable
+     * at application bootstrap time
+     */
+    onModuleInit(): void;
+    /**
+     * NestJS lifecycle hook: clear the pruning interval on module destroy
+     */
+    onModuleDestroy(): void;
+    /**
+     * Validate trust proxy configuration to detect mismatches early
+     * Checks if X-Forwarded-For header support is configured correctly in both directions:
+     * - If trustProxy=false but X-Forwarded-For is present: may miss real client IP
+     * - If trustProxy=true but X-Forwarded-For is absent: proxy may not be configured correctly
+     */
+    private validateTrustProxyConfiguration;
+    /**
+     * Calculate Shannon entropy of a string to measure randomness.
+     * Higher entropy indicates better randomness quality.
+     *
+     * The minimum threshold of 4.0 bits/char is chosen because:
+     * - A uniformly random string from a 16-character alphabet (hex: 0-9a-f) has log2(16) = 4.0 bits/char
+     * - This ensures the CSRF_SECRET has sufficient entropy for cryptographic purposes
+     * - Values below 4.0 bits/char indicate the secret uses a limited character set or has patterns
+     *
+     * @param str - Input string to analyze
+     * @returns Entropy in bits per character
+     */
+    private calculateEntropy;
+    /**
+     * Check if the secret contains obviously weak patterns
+     */
+    private isWeakSecret;
+    /**
+     * Get session identifier for CSRF token binding
+     * Prefers session ID if available, falls back to IP address
+     * @param req - Express request object
+     * @returns Session identifier
+     */
+    private getSessionIdentifier;
+    /**
+     * Extract client IP address from request, respecting trustProxy setting
+     *
+     * **Note on Express vs Fastify**: This implementation uses `req.ip` (Express-specific).
+     * For Fastify deployments, ensure the `trustProxy` option is properly configured:
+     * - In Fastify, use `app.register(require('@fastify/proxy'), { ...config })`
+     * - Or set the Fastify instance option: `fastify({ trustProxy: true })`
+     * - Without correct Fastify configuration, IP detection will fail
+     *
+     * @param req - Express request object
+     * @returns Client IP address or null if unavailable
+     */
+    private extractClientIp;
+    /**
+     * Prune old token generation timestamps to prevent unbounded map growth
+     * Removes entries older than 60 seconds and cleans up idle IPs from both
+     * tokenGenTimestamps and ipLocks to prevent memory accumulation.
+     */
+    private pruneTokenTimestamps;
+    /**
+     * Generate CSRF token with per-IP rate limiting
+     * Limits to 10 token generations per IP per 60 seconds
+     * Uses per-IP locking to serialize concurrent requests from the same IP,
+     * preventing race conditions in rate limit checks.
+     * @param req - Express request object
+     * @param res - Express response object
+     * @returns CSRF token
+     * @throws Error if CSRF_SECRET was not initialized in onModuleInit
+     * @throws {HttpException} 429 - When rate limit exceeded for this IP
+     * @throws {HttpException} 503 - When service is at capacity
+     */
+    generateToken(req: Request, res: Response): Promise<string>;
+    /**
+     * Perform rate-limited token generation for a single IP.
+     * This method is called within an IP-serialized lock to ensure atomicity.
+     * @param req - Express request object
+     * @param res - Express response object
+     * @returns CSRF token
+     * @throws HttpException with 429 status if rate limit exceeded
+     */
+    private performRateLimitedTokenGeneration;
+    /**
+     * Validate CSRF token
+     * @param req - Express request object
+     * @returns true if token is valid, false otherwise
+     * @throws Error if CSRF_SECRET was not initialized in onModuleInit
+     */
+    validateToken(req: Request): boolean;
+    /**
+     * Refresh CSRF token by invalidating the current one and generating a new one
+     * Use this after sensitive operations like login, password change, or privilege escalation
+     * to ensure the user has a fresh token that cannot be replayed from before the operation
+     * @param req - Express request object
+     * @param res - Express response object
+     * @returns New CSRF token
+     * @throws Error if CSRF_SECRET was not initialized in onModuleInit
+     */
+    refreshToken(req: Request, res: Response): Promise<string>;
+    /**
+     * Get CSRF middleware
+     * @returns CSRF protection middleware
+     * @throws Error if CSRF_SECRET was not initialized in onModuleInit
+     */
+    getMiddleware(): (req: Request, res: Response, next: NextFunction) => void;
+}
+//# sourceMappingURL=csrf.service.d.ts.map

package/build/common/services/csrf.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csrf.service.d.ts","sourceRoot":"","sources":["../../../src/common/services/csrf.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,YAAY,EAAE,eAAe,EAAuD,MAAM,gBAAgB,CAAC;AAChI,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAG1D;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBACa,WAAY,YAAW,YAAY,EAAE,eAAe;IAgD5B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;IA7CnE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAM;IAE/C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,2BAA2B,CAAK;IAExD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gCAAgC,CAAK;IAE7D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CAAU;IAEtD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAM;IAC9C;;;;;;;;;;;;;;;;OAgBG;IAEH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAS;IAEhD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,6BAA6B,CAAa;IAElE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAU;IAEpD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,0BAA0B,CAAO;IAEzD,OAAO,CAAC,cAAc,CAAkC;IACxD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IACpD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA+B;IAClE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAC/D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAU;IACrC,OAAO,CAAC,6BAA6B,CAAK;IAC1C,OAAO,CAAC,mBAAmB,CAA6C;IACxE,OAAO,CAAC,UAAU,CAAS;gBAG0B,aAAa,CAAC,EAAE,aAAa,YAAA,EACrE,OAAO,CAAC,EAAE,kBAAkB;IAOzC;;;OAGG;IACI,YAAY,IAAI,IAAI;IA2D3B;;OAEG;IACI,eAAe,IAAI,IAAI;IAU9B;;;;;OAKG;IACH,OAAO,CAAC,+BAA+B;IAyBvC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,gBAAgB;IAaxB;;OAEG;IACH,OAAO,CAAC,YAAY;IAsBpB;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAiB5B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,eAAe;IA4BvB;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAgB5B;;;;;;;;;;;OAWG;IACU,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC;IA6CxE;;;;;;;OAOG;IACH,OAAO,CAAC,iCAAiC;IAiEzC;;;;;OAKG;IACI,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO;IAa3C;;;;;;;;OAQG;IAEI,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC;IAWjE;;;;OAIG;IACI,aAAa,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,KAAK,IAAI;CAOjF"}