@nauth-toolkit/mfa-totp 0.1.13 → 0.1.17

package/dist/src/totp-mfa-provider.service.d.ts

@@ -3,12 +3,92 @@ import { BaseMFADevice, BaseUser, IUser, NAuthConfig, NAuthLogger, MFAMethod } f
 import { BaseMFAProviderService } from '@nauth-toolkit/core/internal';
 import { TOTPService } from './totp.service';
 import { SetupTOTPResponseDTO } from './dto/mfa.dto';
+/**
+ * TOTP MFA Provider Service
+ *
+ * Implements TOTP (Time-based One-Time Password) MFA method.
+ * Extends BaseMFAProviderService to provide TOTP-specific functionality.
+ *
+ * This service handles:
+ * - TOTP secret generation and QR code creation
+ * - TOTP code verification during setup and authentication
+ * - MFA device creation for TOTP
+ *
+ * @example
+ * ```typescript
+ * @Module({
+ *   imports: [TOTPMFAModule],
+ * })
+ * export class AppModule {}
+ * ```
+ */
 export declare class TOTPMFAProviderService extends BaseMFAProviderService {
     private readonly totpService;
     readonly methodName = MFAMethod.TOTP;
-    constructor(mfaDeviceRepository: Repository<BaseMFADevice>, userRepository: Repository<BaseUser>, config: NAuthConfig, logger: NAuthLogger, passwordService: unknown, totpService: TOTPService, challengeService?: unknown, auditService?: unknown, clientInfoService?: unknown);
+    constructor(mfaDeviceRepository: Repository<BaseMFADevice>, userRepository: Repository<BaseUser>, config: NAuthConfig, logger: NAuthLogger, passwordService: unknown, totpService: TOTPService, challengeService?: unknown, // ChallengeService (optional)
+    auditService?: unknown, // AuthAuditService (optional)
+    clientInfoService?: unknown);
+    /**
+     * Setup TOTP for user
+     *
+     * Generates TOTP secret and QR code for authenticator app setup.
+     * User must scan QR code and verify with a code to complete setup.
+     *
+     * @param user - User setting up TOTP
+     * @param _setupData - Not used for TOTP
+     * @returns TOTP setup information (secret, QR code, manual entry key)
+     * @throws {NAuthException} If TOTP is not enabled
+     *
+     * @example
+     * ```typescript
+     * const setup = await provider.setup(user);
+     * // Client displays setup.qrCode and setup.manualEntryKey
+     * ```
+     */
     setup(user: IUser, _setupData?: unknown): Promise<SetupTOTPResponseDTO>;
+    /**
+     * Verify and complete TOTP setup
+     *
+     * Validates the TOTP code and stores the device if valid.
+     * Enables MFA for user if this is their first device.
+     *
+     * **Race Condition Safety:**
+     * Device creation uses transaction with pessimistic locking to prevent duplicates.
+     * If device already exists (e.g., from concurrent request), returns existing device.
+     * Database unique constraint (userId, type) provides final safety net.
+     *
+     * @param user - User completing TOTP setup
+     * @param verificationData - Verification data (must be VerifyTOTPSetupDTO)
+     * @param deviceName - Optional device name override
+     * @returns MFA device ID (created or existing)
+     * @throws {NAuthException} If code is invalid
+     *
+     * @example
+     * ```typescript
+     * const deviceId = await provider.verifySetup(user, {
+     *   secret: 'base32secret',
+     *   code: '123456',
+     *   deviceName: 'Google Authenticator'
+     * });
+     * ```
+     */
     verifySetup(user: IUser, verificationData: unknown, deviceName?: string): Promise<number>;
+    /**
+     * Verify TOTP code during authentication
+     *
+     * Validates the TOTP code for an existing device.
+     *
+     * @param user - User being authenticated
+     * @param code - TOTP code (string)
+     * @param deviceId - Optional device ID to verify against
+     * @returns True if verification succeeds
+     * @throws {NAuthException} If device not found or verification fails
+     *
+     * @example
+     * ```typescript
+     * const isValid = await provider.verify(user, '123456');
+     * ```
+     */
     verify(user: IUser, code: unknown, deviceId?: number): Promise<boolean>;
 }
 //# sourceMappingURL=totp-mfa-provider.service.d.ts.map

package/dist/src/totp-mfa-provider.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"totp-mfa-provider.service.d.ts","sourceRoot":"","sources":["../../src/totp-mfa-provider.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,EACL,aAAa,EACb,QAAQ,EACR,KAAK,EACL,WAAW,EACX,WAAW,EAGX,SAAS,EACV,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,oBAAoB,EAAsB,MAAM,eAAe,CAAC;AAsBzE,qBAAa,sBAAuB,SAAQ,sBAAsB;IAS9D,OAAO,CAAC,QAAQ,CAAC,WAAW;IAR9B,QAAQ,CAAC,UAAU,kBAAkB;gBAGnC,mBAAmB,EAAE,UAAU,CAAC,aAAa,CAAC,EAC9C,cAAc,EAAE,UAAU,CAAC,QAAQ,CAAC,EACpC,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,WAAW,EACnB,eAAe,EAAE,OAAO,EACP,WAAW,EAAE,WAAW,EACzC,gBAAgB,CAAC,EAAE,OAAO,EAC1B,YAAY,CAAC,EAAE,OAAO,EACtB,iBAAiB,CAAC,EAAE,OAAO;IA+BvB,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,UAAU,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,oBAAoB,CAAC;IA0CvE,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA0DzF,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAoC9E"}
+{"version":3,"file":"totp-mfa-provider.service.d.ts","sourceRoot":"","sources":["../../src/totp-mfa-provider.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,EACL,aAAa,EACb,QAAQ,EACR,KAAK,EACL,WAAW,EACX,WAAW,EAGX,SAAS,EACV,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,oBAAoB,EAAsB,MAAM,eAAe,CAAC;AAEzE;;;;;;;;;;;;;;;;;;GAkBG;AAEH,qBAAa,sBAAuB,SAAQ,sBAAsB;IAS9D,OAAO,CAAC,QAAQ,CAAC,WAAW;IAR9B,QAAQ,CAAC,UAAU,kBAAkB;gBAGnC,mBAAmB,EAAE,UAAU,CAAC,aAAa,CAAC,EAC9C,cAAc,EAAE,UAAU,CAAC,QAAQ,CAAC,EACpC,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,WAAW,EACnB,eAAe,EAAE,OAAO,EACP,WAAW,EAAE,WAAW,EACzC,gBAAgB,CAAC,EAAE,OAAO,EAAE,8BAA8B;IAC1D,YAAY,CAAC,EAAE,OAAO,EAAE,8BAA8B;IACtD,iBAAiB,CAAC,EAAE,OAAO;IAc7B;;;;;;;;;;;;;;;;OAgBG;IACG,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,UAAU,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAgB7E;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACG,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA0C/F;;;;;;;;;;;;;;;OAeG;IACG,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAoC9E"}

package/dist/src/totp-mfa-provider.service.js

@@ -1,47 +1,141 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TOTPMFAProviderService = void 0;
+// Public API imports
 const core_1 = require("@nauth-toolkit/core");
+// Internal API imports (for provider implementations)
 const internal_1 = require("@nauth-toolkit/core/internal");
+/**
+ * TOTP MFA Provider Service
+ *
+ * Implements TOTP (Time-based One-Time Password) MFA method.
+ * Extends BaseMFAProviderService to provide TOTP-specific functionality.
+ *
+ * This service handles:
+ * - TOTP secret generation and QR code creation
+ * - TOTP code verification during setup and authentication
+ * - MFA device creation for TOTP
+ *
+ * @example
+ * ```typescript
+ * @Module({
+ *   imports: [TOTPMFAModule],
+ * })
+ * export class AppModule {}
+ * ```
+ */
 class TOTPMFAProviderService extends internal_1.BaseMFAProviderService {
     totpService;
     methodName = core_1.MFAMethod.TOTP;
-    constructor(mfaDeviceRepository, userRepository, config, logger, passwordService, totpService, challengeService, auditService, clientInfoService) {
+    constructor(mfaDeviceRepository, userRepository, config, logger, passwordService, totpService, challengeService, // ChallengeService (optional)
+    auditService, // AuthAuditService (optional)
+    clientInfoService) {
         super(mfaDeviceRepository, userRepository, config, logger, passwordService, challengeService, auditService, clientInfoService);
         this.totpService = totpService;
     }
+    /**
+     * Setup TOTP for user
+     *
+     * Generates TOTP secret and QR code for authenticator app setup.
+     * User must scan QR code and verify with a code to complete setup.
+     *
+     * @param user - User setting up TOTP
+     * @param _setupData - Not used for TOTP
+     * @returns TOTP setup information (secret, QR code, manual entry key)
+     * @throws {NAuthException} If TOTP is not enabled
+     *
+     * @example
+     * ```typescript
+     * const setup = await provider.setup(user);
+     * // Client displays setup.qrCode and setup.manualEntryKey
+     * ```
+     */
     async setup(user, _setupData) {
         this.logger?.log?.(`Setting up TOTP for user: ${user.sub}`);
+        // Check if TOTP is allowed
         if (!this.isMethodAllowed()) {
             throw new core_1.NAuthException(core_1.AuthErrorCode.VALIDATION_FAILED, 'TOTP is not enabled', { feature: 'totp' });
         }
+        // Generate secret and QR code
         const setup = await this.totpService.generateSecret(user.email);
         this.logger?.log?.(`TOTP setup initiated for user: ${user.sub}`);
         return setup;
     }
+    /**
+     * Verify and complete TOTP setup
+     *
+     * Validates the TOTP code and stores the device if valid.
+     * Enables MFA for user if this is their first device.
+     *
+     * **Race Condition Safety:**
+     * Device creation uses transaction with pessimistic locking to prevent duplicates.
+     * If device already exists (e.g., from concurrent request), returns existing device.
+     * Database unique constraint (userId, type) provides final safety net.
+     *
+     * @param user - User completing TOTP setup
+     * @param verificationData - Verification data (must be VerifyTOTPSetupDTO)
+     * @param deviceName - Optional device name override
+     * @returns MFA device ID (created or existing)
+     * @throws {NAuthException} If code is invalid
+     *
+     * @example
+     * ```typescript
+     * const deviceId = await provider.verifySetup(user, {
+     *   secret: 'base32secret',
+     *   code: '123456',
+     *   deviceName: 'Google Authenticator'
+     * });
+     * ```
+     */
     async verifySetup(user, verificationData, deviceName) {
         this.logger?.log?.(`Verifying TOTP setup for user: ${user.sub}`);
         const dto = verificationData;
+        // Validate secret format
         if (!this.totpService.isValidSecret(dto.secret)) {
             throw new core_1.NAuthException(core_1.AuthErrorCode.VALIDATION_FAILED, 'Invalid TOTP secret', { field: 'secret' });
         }
+        // Verify code
         const result = this.totpService.verifyCodeWithDetails(dto.secret, dto.code);
         if (!result.valid) {
             throw new core_1.NAuthException(core_1.AuthErrorCode.VERIFICATION_CODE_INVALID, result.error || 'Invalid TOTP code');
         }
+        // Get user entity for MFA status check
         const userEntity = user;
         const userId = userEntity.id;
         const userMfaEnabled = userEntity.mfaEnabled || false;
+        // ============================================================================
+        // Create MFA device (transaction-safe with duplicate prevention)
+        // ============================================================================
+        // createDevice() uses pessimistic locking to prevent race conditions
+        // If device already exists, returns existing device instead of creating duplicate
+        // Database unique constraint (userId, type) provides additional safety
         const device = await this.createDevice(userId, {
             name: deviceName || dto.deviceName || 'Authenticator App',
-            secret: dto.secret,
+            secret: dto.secret, // TODO: Encrypt at rest in production
             isActive: true,
-            isPrimary: !userMfaEnabled,
+            isPrimary: !userMfaEnabled, // First device becomes primary
         });
+        // Enable MFA if not already enabled
         await this.enableMFAForUser(user);
         this.logger?.log?.(`TOTP setup completed for user: ${user.sub}`);
         return device.id;
     }
+    /**
+     * Verify TOTP code during authentication
+     *
+     * Validates the TOTP code for an existing device.
+     *
+     * @param user - User being authenticated
+     * @param code - TOTP code (string)
+     * @param deviceId - Optional device ID to verify against
+     * @returns True if verification succeeds
+     * @throws {NAuthException} If device not found or verification fails
+     *
+     * @example
+     * ```typescript
+     * const isValid = await provider.verify(user, '123456');
+     * ```
+     */
     async verify(user, code, deviceId) {
         this.logger?.log?.(`Verifying TOTP code for user: ${user.sub}`);
         const totpCode = code;
@@ -49,15 +143,19 @@ class TOTPMFAProviderService extends internal_1.BaseMFAProviderService {
             this.logger?.warn?.('Invalid TOTP code format');
             return false;
         }
+        // Get user entity
         const userEntity = user;
         const userId = userEntity.id;
+        // Find device
         const device = await this.findDevice(userId, deviceId);
         if (!device || !device.secret) {
             this.logger?.warn?.(`No active TOTP device found for user: ${user.sub}`);
             return false;
         }
+        // Verify code
         const isValid = this.totpService.verifyCode(device.secret, totpCode);
         if (isValid) {
+            // Update device usage
             await this.updateDeviceUsage(device.id);
             this.logger?.log?.(`TOTP code verified successfully for user: ${user.sub}`);
         }

package/dist/src/totp-mfa-provider.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"totp-mfa-provider.service.js","sourceRoot":"","sources":["../../src/totp-mfa-provider.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"totp-mfa-provider.service.js","sourceRoot":"","sources":["../../src/totp-mfa-provider.service.ts"],"names":[],"mappings":"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"}

package/dist/src/totp.service.d.ts

@@ -1,22 +1,180 @@
 import { NAuthConfig, NAuthLogger } from '@nauth-toolkit/core';
 import { SetupTOTPResponseDTO } from './dto/mfa.dto';
+/**
+ * TOTP (Time-based One-Time Password) Service
+ *
+ * Handles authenticator app functionality including:
+ * - Secret generation for new TOTP devices
+ * - QR code generation for easy setup
+ * - TOTP code validation with time window
+ * - Compatible with Google Authenticator, Authy, 1Password, etc.
+ *
+ * Uses industry-standard TOTP (RFC 6238) with configurable parameters.
+ *
+ * @example
+ * ```typescript
+ * // Generate TOTP setup
+ * const setup = await totpService.generateSecret('user@example.com');
+ * // Returns: { secret, qrCode, manualEntryKey, issuer, accountName }
+ *
+ * // Verify TOTP code
+ * const isValid = totpService.verifyCode('base32secret', '123456');
+ * // Returns: true if code is valid
+ * ```
+ */
 export declare class TOTPService {
     private readonly config;
     private readonly logger;
     private readonly defaultConfig;
     constructor(config: NAuthConfig, logger: NAuthLogger);
+    /**
+     * Configure otplib authenticator with config settings
+     *
+     * Applies TOTP configuration from NAuthConfig or uses defaults.
+     * Called during service initialization.
+     *
+     * @private
+     */
     private configureAuthenticator;
+    /**
+     * Get TOTP configuration with defaults
+     *
+     * @returns Complete TOTP configuration
+     * @private
+     */
     private getTOTPConfig;
+    /**
+     * Get issuer name for TOTP URIs
+     *
+     * @returns Issuer name from config or default
+     * @private
+     */
     private getIssuer;
+    /**
+     * Generate TOTP secret and QR code for user setup
+     *
+     * Creates a new TOTP secret, generates QR code and manual entry key.
+     * User must scan QR code with authenticator app to complete setup.
+     *
+     * @param accountName - User's email or username (displayed in authenticator app)
+     * @returns Setup information including QR code and secret
+     * @throws {BadRequestException} If QR code generation fails
+     *
+     * @example
+     * ```typescript
+     * const setup = await totpService.generateSecret('user@example.com');
+     * // Client displays QR code and manual entry key
+     * // User scans QR with Google Authenticator, Authy, etc.
+     * ```
+     */
     generateSecret(accountName: string): Promise<SetupTOTPResponseDTO>;
+    /**
+     * Format secret for manual entry
+     *
+     * Converts base32 secret into groups of 4 characters for easy manual input.
+     *
+     * @param secret - Base32-encoded secret
+     * @returns Formatted secret (e.g., 'ABCD EFGH IJKL MNOP')
+     * @private
+     *
+     * @example
+     * ```typescript
+     * formatSecretForManualEntry('ABCDEFGHIJKLMNOP')
+     * // Returns: 'ABCD EFGH IJKL MNOP'
+     * ```
+     */
     private formatSecretForManualEntry;
+    /**
+     * Verify TOTP code against secret
+     *
+     * Validates a 6-digit TOTP code using time-based verification.
+     * Checks current time step plus configured window (before/after).
+     *
+     * SECURITY: Uses time window to account for clock drift and user delay.
+     * Default window of 1 checks 3 time steps (current, ±1).
+     *
+     * @param secret - Base32-encoded TOTP secret
+     * @param code - 6-digit TOTP code from authenticator app
+     * @returns True if code is valid within time window
+     *
+     * @example
+     * ```typescript
+     * // User enters code from Google Authenticator
+     * const isValid = totpService.verifyCode(user.totpSecret, '123456');
+     * if (isValid) {
+     *   // Grant access
+     * }
+     * ```
+     */
     verifyCode(secret: string, code: string): boolean;
+    /**
+     * Verify TOTP code with additional validation
+     *
+     * Extended verification that checks code format and provides detailed error messages.
+     *
+     * @param secret - Base32-encoded TOTP secret
+     * @param code - TOTP code to verify
+     * @returns Verification result with error message if invalid
+     *
+     * @example
+     * ```typescript
+     * const result = totpService.verifyCodeWithDetails(secret, '123456');
+     * if (!result.valid) {
+     *   throw new BadRequestException(result.error);
+     * }
+     * ```
+     */
     verifyCodeWithDetails(secret: string, code: string): {
         valid: boolean;
         error?: string;
     };
+    /**
+     * Generate current TOTP code for secret
+     *
+     * FOR TESTING ONLY - Do not use in production authentication flow.
+     * This method generates the current valid code for a secret.
+     *
+     * @param secret - Base32-encoded TOTP secret
+     * @returns Current 6-digit TOTP code
+     *
+     * @example
+     * ```typescript
+     * // Testing only
+     * const code = totpService.generateCode(secret);
+     * // Returns: '123456'
+     * ```
+     */
     generateCode(secret: string): string;
+    /**
+     * Validate secret format
+     *
+     * Checks if a secret is valid base32 and has sufficient length.
+     *
+     * @param secret - Secret to validate
+     * @returns True if secret is valid
+     *
+     * @example
+     * ```typescript
+     * if (!totpService.isValidSecret(secret)) {
+     *   throw new BadRequestException('Invalid TOTP secret');
+     * }
+     * ```
+     */
     isValidSecret(secret: string): boolean;
+    /**
+     * Get time remaining until next code
+     *
+     * Returns seconds until the current TOTP code expires.
+     * Useful for UI countdowns.
+     *
+     * @returns Seconds remaining (0-30 for default 30s step)
+     *
+     * @example
+     * ```typescript
+     * const remaining = totpService.getTimeRemaining();
+     * // Returns: 15 (seconds until code changes)
+     * ```
+     */
     getTimeRemaining(): number;
 }
 //# sourceMappingURL=totp.service.d.ts.map

package/dist/src/totp.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"totp.service.d.ts","sourceRoot":"","sources":["../../src/totp.service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAc,WAAW,EAAiC,MAAM,qBAAqB,CAAC;AAC1G,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAyBrD,qBAAa,WAAW;IASpB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IATzB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAK5B;gBAGiB,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,WAAW;IAkBtC,OAAO,CAAC,sBAAsB;IAqB9B,OAAO,CAAC,aAAa;IAarB,OAAO,CAAC,SAAS;IAyBX,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAkDxE,OAAO,CAAC,0BAA0B;IA8BlC,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO;IA8CjD,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;IA+CvF,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAmBpC,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAgCtC,gBAAgB,IAAI,MAAM;CAM3B"}
+{"version":3,"file":"totp.service.d.ts","sourceRoot":"","sources":["../../src/totp.service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAc,WAAW,EAAiC,MAAM,qBAAqB,CAAC;AAC1G,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,qBAAa,WAAW;IASpB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IATzB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAK5B;gBAGiB,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,WAAW;IAUtC;;;;;;;OAOG;IACH,OAAO,CAAC,sBAAsB;IAe9B;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAOrB;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IAQjB;;;;;;;;;;;;;;;;OAgBG;IACG,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAmCxE;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,0BAA0B;IAQlC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO;IA6BjD;;;;;;;;;;;;;;;;OAgBG;IACH,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;IA+BvF;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAIpC;;;;;;;;;;;;;;OAcG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAkBtC;;;;;;;;;;;;;OAaG;IACH,gBAAgB,IAAI,MAAM;CAM3B"}