@trokky/trokky 2.0.3

package/dist/core/security/captcha/turnstile.js

@@ -0,0 +1,90 @@
+/**
+ * Cloudflare Turnstile CAPTCHA Service
+ *
+ * Implements the CaptchaProvider interface for Cloudflare Turnstile.
+ * https://developers.cloudflare.com/turnstile/
+ */
+import { createLogger } from '../../utils/logger.js';
+const logger = createLogger('security', 'Turnstile');
+const TURNSTILE_VERIFY_URL = 'https://challenges.cloudflare.com/turnstile/v0/siteverify';
+/**
+ * Cloudflare Turnstile Service
+ */
+export class TurnstileService {
+    name = 'turnstile';
+    config;
+    constructor(config) {
+        this.config = config;
+        logger.debug('TurnstileService initialized', { siteKey: config.siteKey });
+    }
+    /**
+     * Verify a Turnstile token with Cloudflare's API
+     */
+    async verify(token, remoteIp) {
+        logger.debug('Verifying Turnstile token');
+        const formData = new URLSearchParams({
+            secret: this.config.secretKey,
+            response: token,
+        });
+        if (remoteIp) {
+            formData.append('remoteip', remoteIp);
+        }
+        try {
+            const response = await fetch(TURNSTILE_VERIFY_URL, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                },
+                body: formData,
+            });
+            if (!response.ok) {
+                logger.error('Turnstile verification request failed', { status: response.status });
+                return {
+                    success: false,
+                    errorCodes: ['network-error'],
+                };
+            }
+            const data = (await response.json());
+            const result = {
+                success: data.success,
+                challengeTimestamp: data.challenge_ts,
+                hostname: data.hostname,
+                errorCodes: data['error-codes'],
+                action: data.action,
+            };
+            if (data.success) {
+                logger.debug('Turnstile verification successful', { hostname: data.hostname });
+            }
+            else {
+                logger.warn('Turnstile verification failed', { errorCodes: data['error-codes'] });
+            }
+            return result;
+        }
+        catch (error) {
+            logger.error('Turnstile verification error', error);
+            return {
+                success: false,
+                errorCodes: ['internal-error'],
+            };
+        }
+    }
+    /**
+     * Check if the service is properly configured
+     */
+    isConfigured() {
+        return !!(this.config.siteKey && this.config.secretKey);
+    }
+    /**
+     * Get the public site key
+     */
+    getSiteKey() {
+        return this.config.siteKey;
+    }
+}
+/**
+ * Factory function to create a TurnstileService
+ */
+export function createTurnstileService(config) {
+    return new TurnstileService(config);
+}
+//# sourceMappingURL=turnstile.js.map

package/dist/core/security/captcha/turnstile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turnstile.js","sourceRoot":"","sources":["../../../../src/core/security/captcha/turnstile.ts"],"names":[],"mappings":"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"}

package/dist/core/security/captcha/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * CAPTCHA Provider Types
+ *
+ * Defines the interface for CAPTCHA providers (Turnstile, hCaptcha, reCAPTCHA).
+ */
+/**
+ * Result of CAPTCHA verification
+ */
+export interface CaptchaVerificationResult {
+    /** Whether the CAPTCHA was successfully verified */
+    success: boolean;
+    /** ISO timestamp of when the challenge was solved */
+    challengeTimestamp?: string;
+    /** Hostname where the challenge was served */
+    hostname?: string;
+    /** Error codes if verification failed */
+    errorCodes?: string[];
+    /** Action name (reCAPTCHA v3) */
+    action?: string;
+    /** Bot score from 0.0 to 1.0 (reCAPTCHA v3) */
+    score?: number;
+}
+/**
+ * Configuration for a CAPTCHA provider
+ */
+export interface CaptchaProviderConfig {
+    /** Public site key for frontend widget */
+    siteKey: string;
+    /** Secret key for backend verification */
+    secretKey: string;
+    /** Provider-specific options */
+    options?: Record<string, unknown>;
+}
+/**
+ * Supported CAPTCHA provider types
+ */
+export type CaptchaProviderType = 'turnstile' | 'hcaptcha' | 'recaptcha';
+/**
+ * Protected endpoint types
+ */
+export type CaptchaProtectedEndpoint = 'login' | 'passwordResetRequest' | 'passwordResetVerify';
+/**
+ * CAPTCHA Provider Interface
+ *
+ * All CAPTCHA providers must implement this interface.
+ */
+export interface CaptchaProvider {
+    /** Provider name identifier */
+    readonly name: CaptchaProviderType;
+    /**
+     * Verify a CAPTCHA token
+     * @param token - The token from the frontend widget
+     * @param remoteIp - Optional client IP address for verification
+     * @returns Verification result
+     */
+    verify(token: string, remoteIp?: string): Promise<CaptchaVerificationResult>;
+    /**
+     * Check if the provider is properly configured
+     */
+    isConfigured(): boolean;
+    /**
+     * Get the public site key for frontend use
+     */
+    getSiteKey(): string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/security/captcha/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/core/security/captcha/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,oDAAoD;IACpD,OAAO,EAAE,OAAO,CAAA;IAChB,qDAAqD;IACrD,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAA;IACf,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAA;IACjB,gCAAgC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC;AAED;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG,UAAU,GAAG,WAAW,CAAA;AAExE;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG,OAAO,GAAG,sBAAsB,GAAG,qBAAqB,CAAA;AAE/F;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAA;IAElC;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAAA;IAE5E;;OAEG;IACH,YAAY,IAAI,OAAO,CAAA;IAEvB;;OAEG;IACH,UAAU,IAAI,MAAM,CAAA;CACrB"}

package/dist/core/security/captcha/types.js

@@ -0,0 +1,7 @@
+/**
+ * CAPTCHA Provider Types
+ *
+ * Defines the interface for CAPTCHA providers (Turnstile, hCaptcha, reCAPTCHA).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/security/captcha/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/core/security/captcha/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/core/security/mfa/email-otp.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Email OTP Service
+ *
+ * Implements email-based one-time password for MFA.
+ * Uses the existing Trokky mail system for email delivery.
+ */
+export interface EmailOTPConfig {
+    codeLength?: number;
+    expiryMinutes?: number;
+    maxAttempts?: number;
+}
+export interface EmailOTPResult {
+    code: string;
+    codeHash: string;
+    expiresAt: string;
+}
+export interface StoredEmailOTP {
+    codeHash: string;
+    expiresAt: string;
+    attempts: number;
+    createdAt: string;
+}
+export interface EmailOTPVerificationResult {
+    valid: boolean;
+    expired?: boolean;
+    maxAttemptsExceeded?: boolean;
+    attemptsRemaining?: number;
+}
+export declare class EmailOTPService {
+    private config;
+    constructor(config?: EmailOTPConfig);
+    /**
+     * Generate a new email OTP code
+     * Returns both the plain code (for email) and hashed code (for storage)
+     */
+    generateCode(): EmailOTPResult;
+    /**
+     * Verify an email OTP code
+     * Handles expiry and attempt counting
+     */
+    verifyCode(inputCode: string, stored: StoredEmailOTP): EmailOTPVerificationResult;
+    /**
+     * Check if a stored OTP has expired
+     */
+    isExpired(stored: StoredEmailOTP): boolean;
+    /**
+     * Check if max attempts have been exceeded
+     */
+    isMaxAttemptsExceeded(stored: StoredEmailOTP): boolean;
+    /**
+     * Get the time remaining until expiry (in seconds)
+     */
+    getTimeRemaining(stored: StoredEmailOTP): number;
+    /**
+     * Create a stored OTP object from a generated code result
+     */
+    createStoredOTP(result: EmailOTPResult): StoredEmailOTP;
+    /**
+     * Increment attempts for a stored OTP
+     */
+    incrementAttempts(stored: StoredEmailOTP): StoredEmailOTP;
+    /**
+     * Generate a random numeric code of specified length
+     */
+    private generateNumericCode;
+    /**
+     * Hash a code for secure storage
+     */
+    private hashCode;
+    /**
+     * Timing-safe hex string comparison
+     */
+    private timingSafeCompareHex;
+}
+/**
+ * Create a new Email OTP service instance
+ */
+export declare function createEmailOTPService(config?: EmailOTPConfig): EmailOTPService;
+/**
+ * Get subject line for OTP email
+ */
+export declare function getOTPEmailSubject(issuer: string): string;
+/**
+ * Get plain text body for OTP email
+ */
+export declare function getOTPEmailBody(code: string, issuer: string, expiryMinutes: number): string;
+/**
+ * Get HTML body for OTP email
+ */
+export declare function getOTPEmailHTML(code: string, issuer: string, expiryMinutes: number): string;
+//# sourceMappingURL=email-otp.d.ts.map

package/dist/core/security/mfa/email-otp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-otp.d.ts","sourceRoot":"","sources":["../../../../src/core/security/mfa/email-otp.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,OAAO,CAAA;IACd,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAC7B,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B;AAcD,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAA0B;gBAE5B,MAAM,GAAE,cAAmB;IAYvC;;;OAGG;IACH,YAAY,IAAI,cAAc;IAwB9B;;;OAGG;IACH,UAAU,CACR,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,cAAc,GACrB,0BAA0B;IA4C7B;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO;IAI1C;;OAEG;IACH,qBAAqB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO;IAItD;;OAEG;IACH,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM;IAKhD;;OAEG;IACH,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc;IASvD;;OAEG;IACH,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc;IAWzD;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAa3B;;OAEG;IACH,OAAO,CAAC,QAAQ;IAIhB;;OAEG;IACH,OAAO,CAAC,oBAAoB;CAa7B;AAMD;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,GAAE,cAAmB,GAC1B,eAAe,CAEjB;AAMD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,GACpB,MAAM,CAQR;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,GACpB,MAAM,CA4DR"}

package/dist/core/security/mfa/email-otp.js

@@ -0,0 +1,264 @@
+/**
+ * Email OTP Service
+ *
+ * Implements email-based one-time password for MFA.
+ * Uses the existing Trokky mail system for email delivery.
+ */
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { createLogger } from '../../utils/logger.js';
+const logger = createLogger('security', 'EmailOTP');
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+const DEFAULT_CODE_LENGTH = 6;
+const DEFAULT_EXPIRY_MINUTES = 10;
+const DEFAULT_MAX_ATTEMPTS = 5;
+// =============================================================================
+// EMAIL OTP SERVICE
+// =============================================================================
+export class EmailOTPService {
+    config;
+    constructor(config = {}) {
+        this.config = {
+            codeLength: config.codeLength || DEFAULT_CODE_LENGTH,
+            expiryMinutes: config.expiryMinutes || DEFAULT_EXPIRY_MINUTES,
+            maxAttempts: config.maxAttempts || DEFAULT_MAX_ATTEMPTS,
+        };
+        logger.debug('EmailOTPService initialized', {
+            codeLength: this.config.codeLength,
+            expiryMinutes: this.config.expiryMinutes,
+        });
+    }
+    /**
+     * Generate a new email OTP code
+     * Returns both the plain code (for email) and hashed code (for storage)
+     */
+    generateCode() {
+        // Generate random numeric code
+        const code = this.generateNumericCode(this.config.codeLength);
+        // Hash the code for secure storage
+        const codeHash = this.hashCode(code);
+        // Calculate expiry time
+        const expiresAt = new Date(Date.now() + this.config.expiryMinutes * 60 * 1000).toISOString();
+        logger.info('Generated email OTP', {
+            expiresAt,
+            codeLength: this.config.codeLength,
+        });
+        return {
+            code,
+            codeHash,
+            expiresAt,
+        };
+    }
+    /**
+     * Verify an email OTP code
+     * Handles expiry and attempt counting
+     */
+    verifyCode(inputCode, stored) {
+        // Check if expired
+        if (new Date(stored.expiresAt) < new Date()) {
+            logger.debug('Email OTP expired');
+            return {
+                valid: false,
+                expired: true,
+            };
+        }
+        // Check max attempts
+        if (stored.attempts >= this.config.maxAttempts) {
+            logger.debug('Email OTP max attempts exceeded');
+            return {
+                valid: false,
+                maxAttemptsExceeded: true,
+            };
+        }
+        // Clean input code (remove spaces, dashes)
+        const cleanCode = inputCode.replace(/[\s-]/g, '');
+        // Hash and compare
+        const inputHash = this.hashCode(cleanCode);
+        if (this.timingSafeCompareHex(inputHash, stored.codeHash)) {
+            logger.info('Email OTP verified successfully');
+            return {
+                valid: true,
+            };
+        }
+        // Invalid code
+        const attemptsRemaining = this.config.maxAttempts - (stored.attempts + 1);
+        logger.debug('Email OTP verification failed', { attemptsRemaining });
+        return {
+            valid: false,
+            attemptsRemaining,
+        };
+    }
+    /**
+     * Check if a stored OTP has expired
+     */
+    isExpired(stored) {
+        return new Date(stored.expiresAt) < new Date();
+    }
+    /**
+     * Check if max attempts have been exceeded
+     */
+    isMaxAttemptsExceeded(stored) {
+        return stored.attempts >= this.config.maxAttempts;
+    }
+    /**
+     * Get the time remaining until expiry (in seconds)
+     */
+    getTimeRemaining(stored) {
+        const remaining = new Date(stored.expiresAt).getTime() - Date.now();
+        return Math.max(0, Math.floor(remaining / 1000));
+    }
+    /**
+     * Create a stored OTP object from a generated code result
+     */
+    createStoredOTP(result) {
+        return {
+            codeHash: result.codeHash,
+            expiresAt: result.expiresAt,
+            attempts: 0,
+            createdAt: new Date().toISOString(),
+        };
+    }
+    /**
+     * Increment attempts for a stored OTP
+     */
+    incrementAttempts(stored) {
+        return {
+            ...stored,
+            attempts: stored.attempts + 1,
+        };
+    }
+    // ===========================================================================
+    // PRIVATE METHODS
+    // ===========================================================================
+    /**
+     * Generate a random numeric code of specified length
+     */
+    generateNumericCode(length) {
+        // Generate enough random bytes
+        const bytes = randomBytes(length);
+        let code = '';
+        for (let i = 0; i < length; i++) {
+            // Map each byte to 0-9
+            code += (bytes[i] % 10).toString();
+        }
+        return code;
+    }
+    /**
+     * Hash a code for secure storage
+     */
+    hashCode(code) {
+        return createHash('sha256').update(code).digest('hex');
+    }
+    /**
+     * Timing-safe hex string comparison
+     */
+    timingSafeCompareHex(a, b) {
+        if (a.length !== b.length) {
+            return false;
+        }
+        try {
+            const bufA = Buffer.from(a, 'hex');
+            const bufB = Buffer.from(b, 'hex');
+            return timingSafeEqual(bufA, bufB);
+        }
+        catch {
+            return false;
+        }
+    }
+}
+// =============================================================================
+// FACTORY FUNCTION
+// =============================================================================
+/**
+ * Create a new Email OTP service instance
+ */
+export function createEmailOTPService(config = {}) {
+    return new EmailOTPService(config);
+}
+// =============================================================================
+// EMAIL TEMPLATE HELPERS
+// =============================================================================
+/**
+ * Get subject line for OTP email
+ */
+export function getOTPEmailSubject(issuer) {
+    return `Your ${issuer} verification code`;
+}
+/**
+ * Get plain text body for OTP email
+ */
+export function getOTPEmailBody(code, issuer, expiryMinutes) {
+    return `Your ${issuer} verification code is: ${code}
+
+This code will expire in ${expiryMinutes} minutes.
+
+If you didn't request this code, please ignore this email or contact support if you have concerns.
+
+Do not share this code with anyone.`;
+}
+/**
+ * Get HTML body for OTP email
+ */
+export function getOTPEmailHTML(code, issuer, expiryMinutes) {
+    return `
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <style>
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+      line-height: 1.6;
+      color: #333;
+      max-width: 600px;
+      margin: 0 auto;
+      padding: 20px;
+    }
+    .code-container {
+      background: #f5f5f5;
+      border-radius: 8px;
+      padding: 20px;
+      text-align: center;
+      margin: 20px 0;
+    }
+    .code {
+      font-size: 32px;
+      font-weight: bold;
+      letter-spacing: 8px;
+      color: #333;
+      font-family: monospace;
+    }
+    .expiry {
+      color: #666;
+      font-size: 14px;
+      margin-top: 10px;
+    }
+    .warning {
+      color: #666;
+      font-size: 12px;
+      margin-top: 20px;
+      padding-top: 20px;
+      border-top: 1px solid #eee;
+    }
+  </style>
+</head>
+<body>
+  <h2>Your verification code</h2>
+  <p>Use the following code to verify your identity on ${issuer}:</p>
+
+  <div class="code-container">
+    <div class="code">${code}</div>
+    <div class="expiry">This code expires in ${expiryMinutes} minutes</div>
+  </div>
+
+  <p class="warning">
+    If you didn't request this code, please ignore this email or contact support if you have concerns.<br>
+    <strong>Do not share this code with anyone.</strong>
+  </p>
+</body>
+</html>
+`;
+}
+//# sourceMappingURL=email-otp.js.map

package/dist/core/security/mfa/email-otp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-otp.js","sourceRoot":"","sources":["../../../../src/core/security/mfa/email-otp.ts"],"names":[],"mappings":"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"}

package/dist/core/security/mfa/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * MFA (Multi-Factor Authentication) Services
+ *
+ * Provides TOTP and Email OTP authentication methods.
+ */
+export { TOTPService, createTOTPService, type TOTPConfig, type TOTPSecretResult, type BackupCodeVerificationResult, } from './totp.js';
+export { EmailOTPService, createEmailOTPService, getOTPEmailSubject, getOTPEmailBody, getOTPEmailHTML, type EmailOTPConfig, type EmailOTPResult, type StoredEmailOTP, type EmailOTPVerificationResult, } from './email-otp.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/security/mfa/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/core/security/mfa/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,4BAA4B,GAClC,MAAM,WAAW,CAAA;AAElB,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,0BAA0B,GAChC,MAAM,gBAAgB,CAAA"}

package/dist/core/security/mfa/index.js

@@ -0,0 +1,8 @@
+/**
+ * MFA (Multi-Factor Authentication) Services
+ *
+ * Provides TOTP and Email OTP authentication methods.
+ */
+export { TOTPService, createTOTPService, } from './totp.js';
+export { EmailOTPService, createEmailOTPService, getOTPEmailSubject, getOTPEmailBody, getOTPEmailHTML, } from './email-otp.js';
+//# sourceMappingURL=index.js.map

package/dist/core/security/mfa/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/core/security/mfa/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,WAAW,EACX,iBAAiB,GAIlB,MAAM,WAAW,CAAA;AAElB,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,kBAAkB,EAClB,eAAe,EACf,eAAe,GAKhB,MAAM,gBAAgB,CAAA"}

package/dist/core/security/mfa/totp.d.ts

@@ -0,0 +1,87 @@
+/**
+ * TOTP (Time-based One-Time Password) Service
+ *
+ * Implements RFC 6238 TOTP for authenticator app-based MFA.
+ * Uses the otpauth library for TOTP generation/verification.
+ */
+export interface TOTPConfig {
+    issuer: string;
+    algorithm?: 'SHA1' | 'SHA256' | 'SHA512';
+    digits?: number;
+    period?: number;
+}
+export interface TOTPSecretResult {
+    secret: string;
+    uri: string;
+    qrCodeDataUrl: string;
+    manualEntryKey: string;
+}
+export interface BackupCodeVerificationResult {
+    valid: boolean;
+    remainingCodes: string[];
+}
+export declare class TOTPService {
+    private config;
+    constructor(config: TOTPConfig);
+    /**
+     * Generate a new TOTP secret for a user
+     * Returns the secret, URI for QR code generation, and a data URL for the QR code
+     */
+    generateSecret(accountName: string): Promise<TOTPSecretResult>;
+    /**
+     * Verify a TOTP code against a secret
+     * Allows for time drift by checking adjacent time windows
+     */
+    verifyCode(secret: string, code: string, window?: number): boolean;
+    /**
+     * Generate backup codes for account recovery
+     * These are one-time use codes stored hashed
+     */
+    generateBackupCodes(count?: number): string[];
+    /**
+     * Hash a backup code for secure storage
+     * Uses SHA-256 for fast comparison while still being secure
+     */
+    hashBackupCode(code: string): string;
+    /**
+     * Verify a backup code against stored hashed codes
+     * Returns the updated list with the used code removed (consumed)
+     */
+    verifyBackupCode(hashedCodes: string[], code: string): BackupCodeVerificationResult;
+    /**
+     * Build otpauth:// URI for QR code
+     */
+    private buildTOTPUri;
+    /**
+     * Generate QR code as data URL
+     * Uses dynamic import to handle optional qrcode dependency
+     * If qrcode is not installed, returns the URI as base64 for client-side QR generation
+     */
+    private generateQRCode;
+    /**
+     * Generate TOTP code for a given time step
+     * Implements RFC 6238
+     */
+    private generateTOTP;
+    /**
+     * Base32 encode bytes
+     */
+    private base32Encode;
+    /**
+     * Base32 decode string to bytes
+     */
+    private base32Decode;
+    /**
+     * Timing-safe string comparison
+     */
+    private timingSafeCompare;
+    /**
+     * Timing-safe hex string comparison
+     */
+    private timingSafeCompareHex;
+}
+/**
+ * Create a new TOTP service instance
+ */
+export declare function createTOTPService(config: TOTPConfig): TOTPService;
+//# sourceMappingURL=totp.d.ts.map

package/dist/core/security/mfa/totp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"totp.d.ts","sourceRoot":"","sources":["../../../../src/core/security/mfa/totp.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAA;IACxC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,aAAa,EAAE,MAAM,CAAA;IACrB,cAAc,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,OAAO,CAAA;IACd,cAAc,EAAE,MAAM,EAAE,CAAA;CACzB;AAoBD,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAsB;gBAExB,MAAM,EAAE,UAAU;IAU9B;;;OAGG;IACG,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA0BpE;;;OAGG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,MAAU,GAAG,OAAO;IA4BrE;;;OAGG;IACH,mBAAmB,CAAC,KAAK,GAAE,MAA0B,GAAG,MAAM,EAAE;IAsBhE;;;OAGG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAMpC;;;OAGG;IACH,gBAAgB,CACd,WAAW,EAAE,MAAM,EAAE,EACrB,IAAI,EAAE,MAAM,GACX,4BAA4B;IAmC/B;;OAEG;IACH,OAAO,CAAC,YAAY;IAepB;;;;OAIG;YACW,cAAc;IA2B5B;;;OAGG;IACH,OAAO,CAAC,YAAY;IA2BpB;;OAEG;IACH,OAAO,CAAC,YAAY;IAsBpB;;OAEG;IACH,OAAO,CAAC,YAAY;IAuBpB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAWzB;;OAEG;IACH,OAAO,CAAC,oBAAoB;CAa7B;AAMD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,WAAW,CAEjE"}