@portaidentity/server 1.7.0

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

@@ -0,0 +1,43 @@
+/**
+ * Email OTP code utilities.
+ *
+ * Generates, hashes, and verifies 6-digit one-time passwords sent via email.
+ * Codes are cryptographically random (not sequential) and stored as SHA-256
+ * hashes — the plaintext is only ever sent to the user's email and never
+ * persisted in the database.
+ *
+ * SHA-256 is appropriate here (rather than Argon2id) because OTP codes are
+ * short-lived (10 minutes) and brute-forcing a 6-digit code against a fast
+ * hash is still rate-limited at the application level.
+ */
+/**
+ * Generate a cryptographically random 6-digit OTP code.
+ *
+ * Uses Node.js `crypto.randomInt()` for uniform random distribution.
+ * The result is zero-padded to always be exactly 6 characters.
+ *
+ * @returns A 6-digit string (e.g., "042819", "123456")
+ */
+export declare function generateOtpCode(): string;
+/**
+ * Hash an OTP code with SHA-256 for database storage.
+ *
+ * @param code - The 6-digit OTP code to hash
+ * @returns Hex-encoded SHA-256 hash (64 characters)
+ */
+export declare function hashOtpCode(code: string): string;
+/**
+ * Verify an OTP code against its SHA-256 hash.
+ *
+ * Performs a constant-time-equivalent comparison by computing the hash
+ * of the provided code and comparing hex strings. While timing attacks
+ * on SHA-256 hex comparisons are extremely unlikely to be practical for
+ * 6-digit codes, we hash-then-compare rather than using the raw input
+ * to avoid any theoretical leakage.
+ *
+ * @param code - The OTP code to verify
+ * @param hash - The stored SHA-256 hash to verify against
+ * @returns True if the code matches the hash
+ */
+export declare function verifyOtpCode(code: string, hash: string): boolean;
+//# sourceMappingURL=otp.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"otp.d.ts","sourceRoot":"","sources":["../../src/two-factor/otp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAUH;;;;;;;GAOG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAIxC;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAGjE"}

package/dist/two-factor/otp.js

@@ -0,0 +1,57 @@
+/**
+ * Email OTP code utilities.
+ *
+ * Generates, hashes, and verifies 6-digit one-time passwords sent via email.
+ * Codes are cryptographically random (not sequential) and stored as SHA-256
+ * hashes — the plaintext is only ever sent to the user's email and never
+ * persisted in the database.
+ *
+ * SHA-256 is appropriate here (rather than Argon2id) because OTP codes are
+ * short-lived (10 minutes) and brute-forcing a 6-digit code against a fast
+ * hash is still rate-limited at the application level.
+ */
+import { createHash, randomInt } from 'node:crypto';
+/** OTP code length — 6 digits, zero-padded. */
+const OTP_CODE_LENGTH = 6;
+/** Maximum value for a 6-digit code (exclusive). */
+const OTP_MAX_VALUE = 1_000_000;
+/**
+ * Generate a cryptographically random 6-digit OTP code.
+ *
+ * Uses Node.js `crypto.randomInt()` for uniform random distribution.
+ * The result is zero-padded to always be exactly 6 characters.
+ *
+ * @returns A 6-digit string (e.g., "042819", "123456")
+ */
+export function generateOtpCode() {
+    // randomInt(max) returns a uniform random integer in [0, max)
+    const code = randomInt(OTP_MAX_VALUE);
+    return code.toString().padStart(OTP_CODE_LENGTH, '0');
+}
+/**
+ * Hash an OTP code with SHA-256 for database storage.
+ *
+ * @param code - The 6-digit OTP code to hash
+ * @returns Hex-encoded SHA-256 hash (64 characters)
+ */
+export function hashOtpCode(code) {
+    return createHash('sha256').update(code).digest('hex');
+}
+/**
+ * Verify an OTP code against its SHA-256 hash.
+ *
+ * Performs a constant-time-equivalent comparison by computing the hash
+ * of the provided code and comparing hex strings. While timing attacks
+ * on SHA-256 hex comparisons are extremely unlikely to be practical for
+ * 6-digit codes, we hash-then-compare rather than using the raw input
+ * to avoid any theoretical leakage.
+ *
+ * @param code - The OTP code to verify
+ * @param hash - The stored SHA-256 hash to verify against
+ * @returns True if the code matches the hash
+ */
+export function verifyOtpCode(code, hash) {
+    const computedHash = hashOtpCode(code);
+    return computedHash === hash;
+}
+//# sourceMappingURL=otp.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"otp.js","sourceRoot":"","sources":["../../src/two-factor/otp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAEpD,+CAA+C;AAC/C,MAAM,eAAe,GAAG,CAAC,CAAC;AAE1B,oDAAoD;AACpD,MAAM,aAAa,GAAG,SAAS,CAAC;AAEhC;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe;IAC7B,8DAA8D;IAC9D,MAAM,IAAI,GAAG,SAAS,CAAC,aAAa,CAAC,CAAC;IACtC,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,eAAe,EAAE,GAAG,CAAC,CAAC;AACxD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,IAAY;IACtD,MAAM,YAAY,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IACvC,OAAO,YAAY,KAAK,IAAI,CAAC;AAC/B,CAAC"}

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

@@ -0,0 +1,45 @@
+/**
+ * Recovery code utilities.
+ *
+ * Generates, hashes, and verifies single-use recovery codes for 2FA backup.
+ * Users receive 10 codes during 2FA setup, each in XXXX-XXXX format
+ * (8 alphanumeric characters). Codes are hashed with Argon2id before storage
+ * because they are long-lived and relatively high-entropy — they must resist
+ * offline brute-force attacks if the database is compromised.
+ *
+ * Uses the same Argon2id parameters as password hashing (via the `argon2`
+ * library's defaults) for consistency and security.
+ */
+/**
+ * Generate a set of recovery codes in XXXX-XXXX format.
+ *
+ * Each code is 8 characters (split into two 4-character groups with a
+ * dash separator) drawn from an unambiguous alphanumeric alphabet.
+ * The dash is cosmetic and stripped during verification.
+ *
+ * @param count - Number of codes to generate (default: 10)
+ * @returns Array of plaintext recovery codes
+ */
+export declare function generateRecoveryCodes(count?: number): string[];
+/**
+ * Hash a recovery code with Argon2id for database storage.
+ *
+ * The code is normalized (uppercase, dash stripped) before hashing
+ * so that verification is case-insensitive and dash-insensitive.
+ *
+ * @param code - Plaintext recovery code (e.g., "ABCD-1234")
+ * @returns Argon2id hash string
+ */
+export declare function hashRecoveryCode(code: string): Promise<string>;
+/**
+ * Verify a recovery code against an Argon2id hash.
+ *
+ * The code is normalized before verification so that "abcd-1234",
+ * "ABCD1234", and "ABCD-1234" are all equivalent.
+ *
+ * @param code - Plaintext recovery code to verify
+ * @param codeHash - Stored Argon2id hash
+ * @returns True if the code matches the hash
+ */
+export declare function verifyRecoveryCode(code: string, codeHash: string): Promise<boolean>;
+//# sourceMappingURL=recovery.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.d.ts","sourceRoot":"","sources":["../../src/two-factor/recovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAiBH;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,GAAE,MAAoC,GAAG,MAAM,EAAE,CAQ3F;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGpE;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQzF"}

package/dist/two-factor/recovery.js

@@ -0,0 +1,104 @@
+/**
+ * Recovery code utilities.
+ *
+ * Generates, hashes, and verifies single-use recovery codes for 2FA backup.
+ * Users receive 10 codes during 2FA setup, each in XXXX-XXXX format
+ * (8 alphanumeric characters). Codes are hashed with Argon2id before storage
+ * because they are long-lived and relatively high-entropy — they must resist
+ * offline brute-force attacks if the database is compromised.
+ *
+ * Uses the same Argon2id parameters as password hashing (via the `argon2`
+ * library's defaults) for consistency and security.
+ */
+import { hash, verify } from 'argon2';
+import { randomBytes } from 'node:crypto';
+/** Default number of recovery codes to generate. */
+const DEFAULT_RECOVERY_CODE_COUNT = 10;
+/**
+ * Characters used in recovery codes — uppercase alphanumeric, excluding
+ * visually ambiguous characters (0/O, 1/I/L) for easier manual entry.
+ */
+const CODE_CHARS = 'ABCDEFGHJKMNPQRSTUVWXYZ23456789';
+/** Length of each half of a recovery code (XXXX-XXXX). */
+const HALF_LENGTH = 4;
+/**
+ * Generate a set of recovery codes in XXXX-XXXX format.
+ *
+ * Each code is 8 characters (split into two 4-character groups with a
+ * dash separator) drawn from an unambiguous alphanumeric alphabet.
+ * The dash is cosmetic and stripped during verification.
+ *
+ * @param count - Number of codes to generate (default: 10)
+ * @returns Array of plaintext recovery codes
+ */
+export function generateRecoveryCodes(count = DEFAULT_RECOVERY_CODE_COUNT) {
+    const codes = [];
+    for (let i = 0; i < count; i++) {
+        codes.push(generateSingleCode());
+    }
+    return codes;
+}
+/**
+ * Hash a recovery code with Argon2id for database storage.
+ *
+ * The code is normalized (uppercase, dash stripped) before hashing
+ * so that verification is case-insensitive and dash-insensitive.
+ *
+ * @param code - Plaintext recovery code (e.g., "ABCD-1234")
+ * @returns Argon2id hash string
+ */
+export async function hashRecoveryCode(code) {
+    const normalized = normalizeCode(code);
+    return hash(normalized);
+}
+/**
+ * Verify a recovery code against an Argon2id hash.
+ *
+ * The code is normalized before verification so that "abcd-1234",
+ * "ABCD1234", and "ABCD-1234" are all equivalent.
+ *
+ * @param code - Plaintext recovery code to verify
+ * @param codeHash - Stored Argon2id hash
+ * @returns True if the code matches the hash
+ */
+export async function verifyRecoveryCode(code, codeHash) {
+    const normalized = normalizeCode(code);
+    try {
+        return await verify(codeHash, normalized);
+    }
+    catch {
+        // Argon2id verify throws on malformed hashes — treat as non-match
+        return false;
+    }
+}
+/**
+ * Generate a single recovery code in XXXX-XXXX format.
+ *
+ * Uses crypto.randomBytes to generate random indices into the
+ * character set, then formats as two 4-character groups.
+ */
+function generateSingleCode() {
+    const totalLength = HALF_LENGTH * 2;
+    const bytes = randomBytes(totalLength);
+    let code = '';
+    for (let i = 0; i < totalLength; i++) {
+        // Use modulo to map each random byte to a character index.
+        // Slight bias is negligible for this use case (recovery codes
+        // don't need perfectly uniform distribution).
+        code += CODE_CHARS[bytes[i] % CODE_CHARS.length];
+    }
+    // Insert dash between halves: "ABCD1234" → "ABCD-1234"
+    return `${code.slice(0, HALF_LENGTH)}-${code.slice(HALF_LENGTH)}`;
+}
+/**
+ * Normalize a recovery code for hashing/verification.
+ * Converts to uppercase and strips dashes so that entry format
+ * doesn't matter ("abcd-1234" === "ABCD1234" === "ABCD-1234").
+ *
+ * @param code - Raw recovery code input
+ * @returns Normalized uppercase string without dashes
+ */
+function normalizeCode(code) {
+    return code.toUpperCase().replace(/-/g, '');
+}
+//# sourceMappingURL=recovery.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.js","sourceRoot":"","sources":["../../src/two-factor/recovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,oDAAoD;AACpD,MAAM,2BAA2B,GAAG,EAAE,CAAC;AAEvC;;;GAGG;AACH,MAAM,UAAU,GAAG,iCAAiC,CAAC;AAErD,0DAA0D;AAC1D,MAAM,WAAW,GAAG,CAAC,CAAC;AAEtB;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAK,GAAW,2BAA2B;IAC/E,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/B,KAAK,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC,CAAC;IACnC,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAY;IACjD,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACvC,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,IAAY,EAAE,QAAgB;IACrE,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,CAAC;QACH,OAAO,MAAM,MAAM,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,kEAAkE;QAClE,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAS,kBAAkB;IACzB,MAAM,WAAW,GAAG,WAAW,GAAG,CAAC,CAAC;IACpC,MAAM,KAAK,GAAG,WAAW,CAAC,WAAW,CAAC,CAAC;IACvC,IAAI,IAAI,GAAG,EAAE,CAAC;IAEd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,2DAA2D;QAC3D,8DAA8D;QAC9D,8CAA8C;QAC9C,IAAI,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IACnD,CAAC;IAED,uDAAuD;IACvD,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC;AACpE,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,aAAa,CAAC,IAAY;IACjC,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;AAC9C,CAAC"}

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

@@ -0,0 +1,156 @@
+/**
+ * Two-factor authentication repository — PostgreSQL data access layer.
+ *
+ * Provides CRUD operations for the three 2FA tables:
+ *   - user_totp: TOTP configuration per user (encrypted secrets)
+ *   - two_factor_otp_codes: Email OTP codes (SHA-256 hashed, short-lived)
+ *   - two_factor_recovery_codes: Single-use recovery codes (Argon2id hashed)
+ *
+ * Each function acquires the pool via `getPool()` and returns mapped
+ * objects using the mapping functions from types.ts. Follows the same
+ * patterns as the organization and user repositories.
+ */
+import type { UserTotp, OtpCode, RecoveryCode, InsertTotpData } from './types.js';
+/**
+ * Insert a new TOTP configuration for a user.
+ *
+ * The encrypted secret, IV, and auth tag are stored as-is (hex-encoded
+ * strings from the crypto module). The UNIQUE constraint on user_id
+ * ensures only one TOTP config per user.
+ *
+ * @param data - TOTP configuration data (secrets already encrypted)
+ * @returns The newly created TOTP configuration
+ * @throws If user already has a TOTP config (unique constraint violation)
+ */
+export declare function insertTotp(data: InsertTotpData): Promise<UserTotp>;
+/**
+ * Find TOTP configuration for a user.
+ *
+ * Returns the encrypted TOTP config if one exists, or null.
+ * The caller must decrypt the secret using the crypto module.
+ *
+ * @param userId - User UUID
+ * @returns TOTP configuration or null if not configured
+ */
+export declare function findTotpByUserId(userId: string): Promise<UserTotp | null>;
+/**
+ * Mark a user's TOTP configuration as verified.
+ *
+ * Called after the user successfully enters their first TOTP code
+ * during setup. This confirms that the user's authenticator app
+ * is correctly configured.
+ *
+ * @param userId - User UUID
+ */
+export declare function markTotpVerified(userId: string): Promise<void>;
+/**
+ * Delete a user's TOTP configuration.
+ *
+ * Called when disabling 2FA or resetting TOTP setup.
+ * The CASCADE on user_id means this is also cleaned up if the user is deleted.
+ *
+ * @param userId - User UUID
+ */
+export declare function deleteTotp(userId: string): Promise<void>;
+/**
+ * Insert a new email OTP code.
+ *
+ * The code is stored as a SHA-256 hash — the plaintext is only sent
+ * via email. The expires_at timestamp determines when the code becomes
+ * invalid (typically 10 minutes from creation).
+ *
+ * @param userId - User UUID
+ * @param codeHash - SHA-256 hex hash of the 6-digit OTP code
+ * @param expiresAt - Expiration timestamp
+ * @returns The newly created OTP code record
+ */
+export declare function insertOtpCode(userId: string, codeHash: string, expiresAt: Date): Promise<OtpCode>;
+/**
+ * Find all active (unused, not expired) OTP codes for a user.
+ *
+ * Returns codes that are both unused (used_at IS NULL) and not yet
+ * expired (expires_at > NOW()). Ordered by creation time descending
+ * so the most recent code is first.
+ *
+ * @param userId - User UUID
+ * @returns Array of active OTP codes (may be empty)
+ */
+export declare function findActiveOtpCodes(userId: string): Promise<OtpCode[]>;
+/**
+ * Mark an OTP code as used.
+ *
+ * Sets the used_at timestamp to the current time, preventing reuse.
+ * Called after successful verification.
+ *
+ * @param codeId - OTP code UUID
+ */
+export declare function markOtpCodeUsed(codeId: string): Promise<void>;
+/**
+ * Delete expired OTP codes for a user.
+ *
+ * Cleans up codes that have passed their expires_at timestamp or
+ * have already been used. Prevents table bloat over time.
+ *
+ * @param userId - User UUID
+ * @returns Number of codes deleted
+ */
+export declare function deleteExpiredOtpCodes(userId: string): Promise<number>;
+/**
+ * Count active (unused, not expired) OTP codes for a user.
+ *
+ * Used for rate limiting — prevents generating too many codes
+ * in a short time period.
+ *
+ * @param userId - User UUID
+ * @returns Number of active OTP codes
+ */
+export declare function countActiveOtpCodes(userId: string): Promise<number>;
+/**
+ * Insert a batch of recovery codes for a user.
+ *
+ * Inserts all code hashes in a single query using a multi-row VALUES
+ * clause for efficiency. Called during 2FA setup and regeneration.
+ *
+ * @param userId - User UUID
+ * @param codeHashes - Array of Argon2id hashes of recovery codes
+ */
+export declare function insertRecoveryCodes(userId: string, codeHashes: string[]): Promise<void>;
+/**
+ * Find all unused recovery codes for a user.
+ *
+ * Returns codes where used_at IS NULL. The caller iterates these
+ * and verifies each hash to find a match (since Argon2id hashes
+ * include random salt, we can't do a direct DB lookup).
+ *
+ * @param userId - User UUID
+ * @returns Array of unused recovery codes (may be empty)
+ */
+export declare function findUnusedRecoveryCodes(userId: string): Promise<RecoveryCode[]>;
+/**
+ * Mark a recovery code as used.
+ *
+ * Sets the used_at timestamp to the current time, preventing reuse.
+ * Recovery codes are single-use — once used, they cannot be used again.
+ *
+ * @param codeId - Recovery code UUID
+ */
+export declare function markRecoveryCodeUsed(codeId: string): Promise<void>;
+/**
+ * Delete all recovery codes for a user.
+ *
+ * Called when disabling 2FA or regenerating recovery codes
+ * (old codes are deleted, then new ones are inserted).
+ *
+ * @param userId - User UUID
+ */
+export declare function deleteAllRecoveryCodes(userId: string): Promise<void>;
+/**
+ * Count unused recovery codes for a user.
+ *
+ * Used in the 2FA status response to show how many codes remain.
+ *
+ * @param userId - User UUID
+ * @returns Number of unused recovery codes
+ */
+export declare function countUnusedRecoveryCodes(userId: string): Promise<number>;
+//# sourceMappingURL=repository.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../src/two-factor/repository.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EACV,QAAQ,EAER,OAAO,EAEP,YAAY,EAEZ,cAAc,EACf,MAAM,YAAY,CAAC;AAWpB;;;;;;;;;;GAUG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC,CAsBxE;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAU/E;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOpE;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO9D;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,IAAI,GACd,OAAO,CAAC,OAAO,CAAC,CAWlB;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAW3E;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOnE;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAU3E;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAUzE;AAMD;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAAE,GACnB,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAWrF;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOxE;AAED;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO1E;AAED;;;;;;;GAOG;AACH,wBAAsB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAU9E"}

package/dist/two-factor/repository.js

@@ -0,0 +1,251 @@
+/**
+ * Two-factor authentication repository — PostgreSQL data access layer.
+ *
+ * Provides CRUD operations for the three 2FA tables:
+ *   - user_totp: TOTP configuration per user (encrypted secrets)
+ *   - two_factor_otp_codes: Email OTP codes (SHA-256 hashed, short-lived)
+ *   - two_factor_recovery_codes: Single-use recovery codes (Argon2id hashed)
+ *
+ * Each function acquires the pool via `getPool()` and returns mapped
+ * objects using the mapping functions from types.ts. Follows the same
+ * patterns as the organization and user repositories.
+ */
+import { getPool } from '../lib/database.js';
+import { mapRowToUserTotp, mapRowToOtpCode, mapRowToRecoveryCode, } from './types.js';
+// ===========================================================================
+// TOTP operations
+// ===========================================================================
+/**
+ * Insert a new TOTP configuration for a user.
+ *
+ * The encrypted secret, IV, and auth tag are stored as-is (hex-encoded
+ * strings from the crypto module). The UNIQUE constraint on user_id
+ * ensures only one TOTP config per user.
+ *
+ * @param data - TOTP configuration data (secrets already encrypted)
+ * @returns The newly created TOTP configuration
+ * @throws If user already has a TOTP config (unique constraint violation)
+ */
+export async function insertTotp(data) {
+    const pool = getPool();
+    const result = await pool.query(`INSERT INTO user_totp (
+       user_id, encrypted_secret, encryption_iv, encryption_tag,
+       algorithm, digits, period
+     )
+     VALUES ($1, $2, $3, $4, $5, $6, $7)
+     RETURNING *`, [
+        data.userId,
+        data.encryptedSecret,
+        data.encryptionIv,
+        data.encryptionTag,
+        data.algorithm ?? 'SHA1',
+        data.digits ?? 6,
+        data.period ?? 30,
+    ]);
+    return mapRowToUserTotp(result.rows[0]);
+}
+/**
+ * Find TOTP configuration for a user.
+ *
+ * Returns the encrypted TOTP config if one exists, or null.
+ * The caller must decrypt the secret using the crypto module.
+ *
+ * @param userId - User UUID
+ * @returns TOTP configuration or null if not configured
+ */
+export async function findTotpByUserId(userId) {
+    const pool = getPool();
+    const result = await pool.query('SELECT * FROM user_totp WHERE user_id = $1', [userId]);
+    if (result.rows.length === 0)
+        return null;
+    return mapRowToUserTotp(result.rows[0]);
+}
+/**
+ * Mark a user's TOTP configuration as verified.
+ *
+ * Called after the user successfully enters their first TOTP code
+ * during setup. This confirms that the user's authenticator app
+ * is correctly configured.
+ *
+ * @param userId - User UUID
+ */
+export async function markTotpVerified(userId) {
+    const pool = getPool();
+    await pool.query('UPDATE user_totp SET verified = true WHERE user_id = $1', [userId]);
+}
+/**
+ * Delete a user's TOTP configuration.
+ *
+ * Called when disabling 2FA or resetting TOTP setup.
+ * The CASCADE on user_id means this is also cleaned up if the user is deleted.
+ *
+ * @param userId - User UUID
+ */
+export async function deleteTotp(userId) {
+    const pool = getPool();
+    await pool.query('DELETE FROM user_totp WHERE user_id = $1', [userId]);
+}
+// ===========================================================================
+// OTP code operations
+// ===========================================================================
+/**
+ * Insert a new email OTP code.
+ *
+ * The code is stored as a SHA-256 hash — the plaintext is only sent
+ * via email. The expires_at timestamp determines when the code becomes
+ * invalid (typically 10 minutes from creation).
+ *
+ * @param userId - User UUID
+ * @param codeHash - SHA-256 hex hash of the 6-digit OTP code
+ * @param expiresAt - Expiration timestamp
+ * @returns The newly created OTP code record
+ */
+export async function insertOtpCode(userId, codeHash, expiresAt) {
+    const pool = getPool();
+    const result = await pool.query(`INSERT INTO two_factor_otp_codes (user_id, code_hash, expires_at)
+     VALUES ($1, $2, $3)
+     RETURNING *`, [userId, codeHash, expiresAt]);
+    return mapRowToOtpCode(result.rows[0]);
+}
+/**
+ * Find all active (unused, not expired) OTP codes for a user.
+ *
+ * Returns codes that are both unused (used_at IS NULL) and not yet
+ * expired (expires_at > NOW()). Ordered by creation time descending
+ * so the most recent code is first.
+ *
+ * @param userId - User UUID
+ * @returns Array of active OTP codes (may be empty)
+ */
+export async function findActiveOtpCodes(userId) {
+    const pool = getPool();
+    const result = await pool.query(`SELECT * FROM two_factor_otp_codes
+     WHERE user_id = $1 AND used_at IS NULL AND expires_at > NOW()
+     ORDER BY created_at DESC`, [userId]);
+    return result.rows.map(mapRowToOtpCode);
+}
+/**
+ * Mark an OTP code as used.
+ *
+ * Sets the used_at timestamp to the current time, preventing reuse.
+ * Called after successful verification.
+ *
+ * @param codeId - OTP code UUID
+ */
+export async function markOtpCodeUsed(codeId) {
+    const pool = getPool();
+    await pool.query('UPDATE two_factor_otp_codes SET used_at = NOW() WHERE id = $1', [codeId]);
+}
+/**
+ * Delete expired OTP codes for a user.
+ *
+ * Cleans up codes that have passed their expires_at timestamp or
+ * have already been used. Prevents table bloat over time.
+ *
+ * @param userId - User UUID
+ * @returns Number of codes deleted
+ */
+export async function deleteExpiredOtpCodes(userId) {
+    const pool = getPool();
+    const result = await pool.query(`DELETE FROM two_factor_otp_codes
+     WHERE user_id = $1 AND (expires_at <= NOW() OR used_at IS NOT NULL)`, [userId]);
+    return result.rowCount ?? 0;
+}
+/**
+ * Count active (unused, not expired) OTP codes for a user.
+ *
+ * Used for rate limiting — prevents generating too many codes
+ * in a short time period.
+ *
+ * @param userId - User UUID
+ * @returns Number of active OTP codes
+ */
+export async function countActiveOtpCodes(userId) {
+    const pool = getPool();
+    const result = await pool.query(`SELECT COUNT(*) as count FROM two_factor_otp_codes
+     WHERE user_id = $1 AND used_at IS NULL AND expires_at > NOW()`, [userId]);
+    return parseInt(result.rows[0].count, 10);
+}
+// ===========================================================================
+// Recovery code operations
+// ===========================================================================
+/**
+ * Insert a batch of recovery codes for a user.
+ *
+ * Inserts all code hashes in a single query using a multi-row VALUES
+ * clause for efficiency. Called during 2FA setup and regeneration.
+ *
+ * @param userId - User UUID
+ * @param codeHashes - Array of Argon2id hashes of recovery codes
+ */
+export async function insertRecoveryCodes(userId, codeHashes) {
+    if (codeHashes.length === 0)
+        return;
+    const pool = getPool();
+    // Build multi-row VALUES clause: ($1, $2), ($1, $3), ($1, $4), ...
+    // $1 is always the userId; each hash gets its own parameter
+    const valuePlaceholders = [];
+    const params = [userId];
+    for (let i = 0; i < codeHashes.length; i++) {
+        valuePlaceholders.push(`($1, $${i + 2})`);
+        params.push(codeHashes[i]);
+    }
+    await pool.query(`INSERT INTO two_factor_recovery_codes (user_id, code_hash)
+     VALUES ${valuePlaceholders.join(', ')}`, params);
+}
+/**
+ * Find all unused recovery codes for a user.
+ *
+ * Returns codes where used_at IS NULL. The caller iterates these
+ * and verifies each hash to find a match (since Argon2id hashes
+ * include random salt, we can't do a direct DB lookup).
+ *
+ * @param userId - User UUID
+ * @returns Array of unused recovery codes (may be empty)
+ */
+export async function findUnusedRecoveryCodes(userId) {
+    const pool = getPool();
+    const result = await pool.query(`SELECT * FROM two_factor_recovery_codes
+     WHERE user_id = $1 AND used_at IS NULL
+     ORDER BY created_at ASC`, [userId]);
+    return result.rows.map(mapRowToRecoveryCode);
+}
+/**
+ * Mark a recovery code as used.
+ *
+ * Sets the used_at timestamp to the current time, preventing reuse.
+ * Recovery codes are single-use — once used, they cannot be used again.
+ *
+ * @param codeId - Recovery code UUID
+ */
+export async function markRecoveryCodeUsed(codeId) {
+    const pool = getPool();
+    await pool.query('UPDATE two_factor_recovery_codes SET used_at = NOW() WHERE id = $1', [codeId]);
+}
+/**
+ * Delete all recovery codes for a user.
+ *
+ * Called when disabling 2FA or regenerating recovery codes
+ * (old codes are deleted, then new ones are inserted).
+ *
+ * @param userId - User UUID
+ */
+export async function deleteAllRecoveryCodes(userId) {
+    const pool = getPool();
+    await pool.query('DELETE FROM two_factor_recovery_codes WHERE user_id = $1', [userId]);
+}
+/**
+ * Count unused recovery codes for a user.
+ *
+ * Used in the 2FA status response to show how many codes remain.
+ *
+ * @param userId - User UUID
+ * @returns Number of unused recovery codes
+ */
+export async function countUnusedRecoveryCodes(userId) {
+    const pool = getPool();
+    const result = await pool.query(`SELECT COUNT(*) as count FROM two_factor_recovery_codes
+     WHERE user_id = $1 AND used_at IS NULL`, [userId]);
+    return parseInt(result.rows[0].count, 10);
+}
+//# sourceMappingURL=repository.js.map