@portaidentity/server 1.7.0

package/dist/two-factor/repository.js.map

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

package/dist/two-factor/service.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Two-factor authentication service — business logic orchestrator.
+ *
+ * Composes the repository, cache, crypto utilities, and audit log
+ * to provide the complete 2FA management API. Functions are grouped by:
+ *
+ *   - **Setup**: Initialize email OTP or TOTP, confirm TOTP enrollment
+ *   - **Verification**: Verify OTP codes, TOTP codes, recovery codes
+ *   - **Sending**: Generate and send OTP codes via email
+ *   - **Management**: Get status, disable 2FA, regenerate recovery codes
+ *   - **Policy**: Check org policy requirements, determine required method
+ *
+ * All write operations follow the pattern:
+ *   1. Validate preconditions (user state, existing 2FA, etc.)
+ *   2. Perform DB operations (via repository)
+ *   3. Update user 2FA state (via user repository)
+ *   4. Invalidate cache
+ *   5. Write audit log (fire-and-forget)
+ */
+import type { TwoFactorMethod, TwoFactorSetupResult, TwoFactorStatus, TwoFactorPolicy } from './types.js';
+/**
+ * Set up email OTP as the 2FA method for a user.
+ *
+ * Enables 2FA with the 'email' method, generates recovery codes, and
+ * marks the user as 2FA-enabled in the users table. No TOTP config
+ * is created — email OTP codes are generated on-demand during login.
+ *
+ * @param userId - User UUID
+ * @param orgId - Organization UUID (for audit logging)
+ * @returns Setup result with recovery codes
+ * @throws TwoFactorAlreadyEnabledError if 2FA is already enabled
+ */
+export declare function setupEmailOtp(userId: string, orgId: string): Promise<TwoFactorSetupResult>;
+/**
+ * Start TOTP setup for a user.
+ *
+ * Generates a TOTP secret, encrypts it, stores it as unverified,
+ * and returns the otpauth:// URI and QR code for the user to scan.
+ * The setup is not complete until the user confirms with a valid
+ * TOTP code via `confirmTotpSetup()`.
+ *
+ * @param userId - User UUID
+ * @param email - User email (for TOTP URI display)
+ * @param orgSlug - Organization slug (used as TOTP issuer)
+ * @returns Setup result with TOTP URI, QR code, and recovery codes
+ * @throws TwoFactorAlreadyEnabledError if 2FA is already enabled
+ */
+export declare function setupTotp(userId: string, email: string, orgSlug: string): Promise<TwoFactorSetupResult>;
+/**
+ * Retrieve existing pending (unverified) TOTP setup info.
+ *
+ * If a user has a pending TOTP setup (unverified record in DB), this
+ * decrypts the secret and regenerates the QR code for display.
+ * Does NOT regenerate the secret — preserves the existing one.
+ *
+ * Returns null if no pending setup exists.
+ *
+ * @param userId - User UUID
+ * @param email - User email (for TOTP URI display)
+ * @param orgSlug - Organization slug (used as TOTP issuer)
+ * @returns Setup info with QR code and secret, or null if no pending setup
+ */
+export declare function getPendingTotpSetupInfo(userId: string, email: string, orgSlug: string): Promise<{
+    totpUri: string;
+    qrCodeDataUri: string;
+    totpSecret: string;
+} | null>;
+/**
+ * Confirm TOTP setup by verifying the user's first TOTP code.
+ *
+ * Called after the user scans the QR code and enters a TOTP code
+ * from their authenticator app. This confirms the setup is correct
+ * and enables 2FA on the user record.
+ *
+ * @param userId - User UUID
+ * @param code - 6-digit TOTP code from the authenticator app
+ * @returns true if the code is valid and setup is confirmed
+ * @throws TotpNotConfiguredError if no pending TOTP setup exists
+ */
+export declare function confirmTotpSetup(userId: string, code: string): Promise<boolean>;
+/**
+ * Generate and send an OTP code via email.
+ *
+ * Creates a 6-digit code, hashes it, stores the hash in the database
+ * with a 10-minute expiry, and sends the plaintext code via email.
+ * Rate-limited to MAX_ACTIVE_OTP_CODES active codes per user.
+ *
+ * Note: This function generates the code and stores it. The actual email
+ * sending is handled by the auth email service (Phase 8). For now, this
+ * function prepares the code — the route layer will call the email service.
+ *
+ * @param userId - User UUID
+ * @param email - User email to send the code to
+ * @param orgId - Organization UUID (for audit logging)
+ * @returns The plaintext OTP code (caller sends via email service)
+ * @throws Error if too many active codes exist (rate limiting)
+ */
+export declare function sendOtpCode(userId: string, email: string, orgId: string): Promise<string>;
+/**
+ * Verify an email OTP code.
+ *
+ * Checks all active (unused, not expired) OTP codes for the user,
+ * verifying the provided code against each hash. If a match is found,
+ * the code is marked as used.
+ *
+ * @param userId - User UUID
+ * @param code - 6-digit OTP code to verify
+ * @returns true if the code is valid
+ * @throws OtpInvalidError if no matching code is found
+ */
+export declare function verifyOtp(userId: string, code: string): Promise<boolean>;
+/**
+ * Verify a TOTP code from an authenticator app.
+ *
+ * Decrypts the user's TOTP secret from the database and verifies
+ * the code with a ±1 step time window.
+ *
+ * @param userId - User UUID
+ * @param code - 6-digit TOTP code to verify
+ * @returns true if the code is valid
+ * @throws TotpNotConfiguredError if no verified TOTP config exists
+ */
+export declare function verifyTotp(userId: string, code: string): Promise<boolean>;
+/**
+ * Verify a recovery code.
+ *
+ * Recovery codes use Argon2id hashing with random salt, so we must
+ * iterate all unused codes and verify against each hash. If a match
+ * is found, the code is marked as used (single-use).
+ *
+ * @param userId - User UUID
+ * @param code - Recovery code in XXXX-XXXX format (case-insensitive)
+ * @returns true if the code is valid
+ * @throws RecoveryCodesExhaustedError if no unused codes remain
+ * @throws RecoveryCodeInvalidError if the code doesn't match any hash
+ */
+export declare function verifyRecoveryCode(userId: string, code: string): Promise<boolean>;
+/**
+ * Get the current 2FA status for a user.
+ *
+ * Checks Redis cache first, falls back to building the status from
+ * the database. The status includes whether 2FA is enabled, the method,
+ * whether TOTP is configured (and verified), and remaining recovery codes.
+ *
+ * @param userId - User UUID
+ * @returns Current 2FA status
+ */
+export declare function getTwoFactorStatus(userId: string): Promise<TwoFactorStatus>;
+/**
+ * Disable 2FA for a user.
+ *
+ * Removes all 2FA data: TOTP config, active OTP codes, and recovery codes.
+ * Resets the user's 2FA flags in the users table.
+ *
+ * @param userId - User UUID
+ * @throws TwoFactorNotEnabledError if 2FA is not enabled
+ */
+export declare function disableTwoFactor(userId: string): Promise<void>;
+/**
+ * Regenerate recovery codes for a user.
+ *
+ * Deletes all existing recovery codes and generates a fresh set of 10.
+ * The user must have 2FA enabled to regenerate codes.
+ *
+ * @param userId - User UUID
+ * @returns Array of new plaintext recovery codes (shown once to the user)
+ * @throws TwoFactorNotEnabledError if 2FA is not enabled
+ */
+export declare function regenerateRecoveryCodes(userId: string): Promise<string[]>;
+/**
+ * Minimal organization shape needed for policy checks.
+ * Uses a local interface to avoid importing the full Organization type
+ * (which would create a circular dependency).
+ */
+interface OrgForPolicy {
+    twoFactorPolicy: TwoFactorPolicy;
+}
+/**
+ * Minimal user shape needed for policy checks.
+ */
+interface UserForPolicy {
+    twoFactorEnabled: boolean;
+    twoFactorMethod: TwoFactorMethod | null;
+}
+/**
+ * Check if the organization's 2FA policy requires 2FA for a user.
+ *
+ * Returns true if the org policy is anything other than 'optional'
+ * AND the user has not yet enabled 2FA.
+ *
+ * @param org - Organization with twoFactorPolicy field
+ * @param user - User with 2FA state fields
+ * @returns true if 2FA is required but not yet set up
+ */
+export declare function requiresTwoFactor(org: OrgForPolicy, user: UserForPolicy): boolean;
+/**
+ * Determine which 2FA method the user should use based on org policy.
+ *
+ * If the user has 2FA enabled, returns their configured method.
+ * If the org requires a specific method, returns that method.
+ * If the org requires 'any', returns null (user chooses).
+ * If the policy is optional, returns null.
+ *
+ * @param org - Organization with twoFactorPolicy field
+ * @param user - User with 2FA state fields
+ * @returns The 2FA method to use, or null if no method is required/configured
+ */
+export declare function determineTwoFactorMethod(org: OrgForPolicy, user: UserForPolicy): TwoFactorMethod | null;
+/**
+ * 2FA enrollment summary for an organization.
+ * Used by the GET /summary admin endpoint (SH-3).
+ */
+export interface TwoFactorSummary {
+    totalUsers: number;
+    enabledCount: number;
+    disabledCount: number;
+    totpCount: number;
+    emailCount: number;
+    complianceRate: number;
+}
+/**
+ * Get an aggregate 2FA enrollment summary for an organization.
+ *
+ * Runs a single SQL query with conditional aggregation to count
+ * users by 2FA status, method, and calculate compliance rate.
+ *
+ * @param orgId - Organization UUID
+ * @returns Aggregate summary with counts and compliance rate
+ */
+export declare function getTwoFactorSummary(orgId: string): Promise<TwoFactorSummary>;
+export {};
+//# sourceMappingURL=service.d.ts.map

package/dist/two-factor/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/two-factor/service.ts"],"names":[],"mappings":"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"}