|
| 1 | +# frozen_string_literal: true |
| 2 | + |
| 3 | +# Time-based one-time passwords (TOTP) for web sign-in, with backup recovery codes. |
| 4 | +# `last_otp_timestep` stores the Unix timestamp returned by ROTP on the last successful |
| 5 | +# TOTP verification (used as ROTP's `after:` to prevent token reuse). |
| 6 | +# `otp_secret` is encrypted at rest (Lockbox). Backup codes are stored as HMAC digests only; |
| 7 | +# plaintext codes are shown once via session (see Users::TwoFactorController). |
| 8 | +module User::TotpAuthentication |
| 9 | + extend ActiveSupport::Concern |
| 10 | + |
| 11 | + included do |
| 12 | + has_encrypted :otp_secret |
| 13 | + |
| 14 | + serialize :otp_backup_code_digests, coder: ActiveRecord::Coders::JSON.new, type: Array |
| 15 | + end |
| 16 | + |
| 17 | + class_methods do |
| 18 | + # Used by tests and to build digests; same algorithm as instance digesting. |
| 19 | + def digest_otp_backup_code(user_id, code) |
| 20 | + OpenSSL::HMAC.hexdigest( |
| 21 | + "SHA256", |
| 22 | + Rails.application.secret_key_base, |
| 23 | + "#{user_id}:#{code.to_s.strip.downcase}" |
| 24 | + ) |
| 25 | + end |
| 26 | + end |
| 27 | + |
| 28 | + def totp_issuer |
| 29 | + Settings.brand&.title.presence || "Password Pusher" |
| 30 | + end |
| 31 | + |
| 32 | + def ensure_otp_secret! |
| 33 | + return if otp_secret.present? |
| 34 | + |
| 35 | + update!(otp_secret: ROTP::Base32.random) |
| 36 | + end |
| 37 | + |
| 38 | + def enable_totp! |
| 39 | + update!(otp_required_for_login: true) |
| 40 | + end |
| 41 | + |
| 42 | + def disable_totp! |
| 43 | + update!( |
| 44 | + otp_required_for_login: false, |
| 45 | + otp_secret: nil, |
| 46 | + otp_backup_code_digests: [], |
| 47 | + last_otp_timestep: nil |
| 48 | + ) |
| 49 | + end |
| 50 | + |
| 51 | + def totp |
| 52 | + raise ArgumentError, "otp_secret is blank" if otp_secret.blank? |
| 53 | + |
| 54 | + ROTP::TOTP.new(otp_secret, issuer: totp_issuer) |
| 55 | + end |
| 56 | + |
| 57 | + def totp_provisioning_uri |
| 58 | + totp.provisioning_uri(email) |
| 59 | + end |
| 60 | + |
| 61 | + def totp_manual_entry_secret |
| 62 | + otp_secret |
| 63 | + end |
| 64 | + |
| 65 | + # Verifies a 6-digit TOTP or a backup code, then consumes it (single-use). |
| 66 | + def verify_and_consume_otp!(code) |
| 67 | + return false if code.blank? |
| 68 | + |
| 69 | + normalized = code.to_s.strip |
| 70 | + |
| 71 | + if otp_secret.present? |
| 72 | + with_lock do |
| 73 | + reload # fresh last_otp_timestep; lock prevents concurrent TOTP replays |
| 74 | + token_time = totp.verify(normalized, after: last_otp_timestep, drift_behind: 15) |
| 75 | + if token_time |
| 76 | + update!(last_otp_timestep: token_time.to_i) |
| 77 | + return true |
| 78 | + end |
| 79 | + end |
| 80 | + end |
| 81 | + |
| 82 | + consume_backup_code!(normalized) |
| 83 | + end |
| 84 | + |
| 85 | + # Returns plaintext codes once; persists only digests. Caller should stash plaintext in session for display. |
| 86 | + def generate_otp_backup_codes! |
| 87 | + plaintexts = 16.times.map { SecureRandom.hex(5) } |
| 88 | + digests = plaintexts.map { |p| self.class.digest_otp_backup_code(id, p) } |
| 89 | + update!(otp_backup_code_digests: digests) |
| 90 | + plaintexts |
| 91 | + end |
| 92 | + |
| 93 | + private |
| 94 | + |
| 95 | + def consume_backup_code!(code) |
| 96 | + normalized = code.to_s.strip.downcase |
| 97 | + candidate = self.class.digest_otp_backup_code(id, normalized) |
| 98 | + digests = Array(otp_backup_code_digests) |
| 99 | + match_index = nil |
| 100 | + digests.each_with_index do |stored, i| |
| 101 | + next unless stored.bytesize == candidate.bytesize |
| 102 | + |
| 103 | + if ActiveSupport::SecurityUtils.secure_compare(stored, candidate) |
| 104 | + match_index = i |
| 105 | + break |
| 106 | + end |
| 107 | + end |
| 108 | + return false unless match_index |
| 109 | + |
| 110 | + digests.delete_at(match_index) |
| 111 | + update!(otp_backup_code_digests: digests) |
| 112 | + true |
| 113 | + end |
| 114 | +end |
0 commit comments