authnz_eleven 0.1.0

data/lib/generators/authnz_eleven/templates/models/concerns/authenticatable.rb.tt

@@ -0,0 +1,151 @@
+module <%= identity.class_name %>::Authenticatable
+  extend ActiveSupport::Concern
+
+  included do
+    has_many :sessions, dependent: :destroy
+<%- if api_tokens? -%>
+    has_many :api_tokens, dependent: :destroy
+<%- end -%>
+<%- if webauthn_credentials? -%>
+    has_many :webauthn_credentials, dependent: :destroy
+<%- end -%>
+<%- if omniauth? -%>
+    has_many :omniauth_identities, dependent: :destroy
+<%- end -%>
+<%- if webauthn_credentials? -%>
+
+    before_create do
+      self.webauthn_handle ||= WebAuthn.generate_user_id
+    end
+<%- end -%>
+<%- if password? -%>
+
+    scope :with_password, -> { where.not(password_digest: nil) }
+
+    after_update if: :password_digest_previously_changed? do
+      sessions.where.not(id: <%= identity.current_class %>.session).delete_all
+    end
+<%- if trackable? -%>
+
+    after_update if: :password_digest_previously_changed? do
+      record_event("<%= identity.singular %>.password_changed")
+    end
+<%- end -%>
+<%- end -%>
+  end
+<%- if multi_login? || password? || sms_code? -%>
+
+  class_methods do
+<%- if password? -%>
+    def authenticate_with_password(identifier, password)
+      identifier = identifier.to_s.strip
+<%- keys = principals.login_dispatch_principals -%>
+<%- if keys.size == 1 -%>
+      user = <%= keys.first.authenticate_lookup %>
+<%- else -%>
+      user =
+<%- keys.each_with_index do |principal, i| -%>
+<%- if i.zero? -%>
+        if <%= principal.login_dispatch_test %>
+<%- elsif i < keys.size - 1 -%>
+        elsif <%= principal.login_dispatch_test %>
+<%- else -%>
+        else
+<%- end -%>
+          <%= principal.authenticate_lookup %>
+<%- end -%>
+        end
+<%- end -%>
+
+<%- if deadboltable? -%>
+      user unless user&.deadbolted?
+<%- else -%>
+      user
+<%- end -%>
+    end
+<%- end -%>
+<%- if multi_login? && password? -%>
+
+<%- end -%>
+<%- if multi_login? -%>
+    def find_by_login(identifier)
+      identifier = identifier.to_s.strip
+<%- keys = principals.login_dispatch_principals -%>
+<%- keys.each_with_index do |principal, i| -%>
+<%- lookup = principal.find_by_login_lookup -%>
+<%- if i < keys.size - 1 -%>
+      return <%= lookup %> if <%= principal.login_dispatch_test %>
+<%- else -%>
+      <%= lookup %>
+<%- end -%>
+<%- end -%>
+    end
+<%- end -%>
+<%- if sms_code? -%>
+<%- if multi_login? || password? -%>
+
+<%- end -%>
+    def issue_sms_sign_in_code(phone)
+      find_by(phone:)&.tap(&:issue_sms_challenge)
+    end
+<%- end -%>
+  end
+<%- end -%>
+<%- if password_nullable? && !password_blank_rows_all? -%>
+
+  def password_may_be_blank? = <%= password_blank_rows_expression %>
+<%- end -%>
+<%- if removable_credentials? -%>
+
+  def sign_in_methods
+    methods = []
+<%- if password? -%>
+    methods << :password if password_set?
+<%- end -%>
+<%- if passkey? -%>
+    methods << :passkey if webauthn_credentials<%= ".passkeys" if passkey_and_security_keys? %>.any?
+<%- end -%>
+<%- if omniauth? -%>
+    methods << :omniauth if omniauth_identities.any?
+<%- end -%>
+<%- if magic_link? -%>
+    methods << :magic_link if email.present?
+<%- end -%>
+<%- if sms_code? -%>
+    methods << :sms_code if phone.present?
+<%- end -%>
+    methods
+  end
+
+  def last_sign_in_method?(kind)
+    return false if (sign_in_methods - [ kind ]).any?
+
+<%- if passkey? || omniauth? -%>
+    case kind
+<%- if passkey? -%>
+    when :passkey then webauthn_credentials<%= ".passkeys" if passkey_and_security_keys? %>.count <= 1
+<%- end -%>
+<%- if omniauth? -%>
+    when :omniauth then omniauth_identities.count <= 1
+<%- end -%>
+    else true
+    end
+<%- else -%>
+    true
+<%- end -%>
+  end
+<%- end -%>
+<%- if max_sessions_prompt? -%>
+
+  def within_session_limit?
+    limit = <%= identity.config_reference %>.session.concurrent_limit
+    limit.nil? || sessions.count <= limit
+  end
+<%- end -%>
+<%- if last_seenable? -%>
+
+  def mark_last_seen!
+    update_column(:last_seen_at, Time.current)
+  end
+<%- end -%>
+end

data/lib/generators/authnz_eleven/templates/models/concerns/bannable.rb.tt

@@ -0,0 +1,24 @@
+module <%= identity.class_name %>::Bannable
+  def banned?
+    banned_at.present? && (banned_until.nil? || banned_until.future?)
+  end
+
+  def ban!(expires_at: nil)
+    return if banned?
+    update!(banned_at: Time.current, banned_until: expires_at)
+<%- if trackable? -%>
+    record_event("<%= identity.singular %>.banned")
+<%- end -%>
+    sessions.destroy_all
+<%- if api_tokens? -%>
+    api_tokens.destroy_all
+<%- end -%>
+  end
+
+  def unban!
+    update!(banned_at: nil, banned_until: nil)
+<%- if trackable? -%>
+    record_event("<%= identity.singular %>.unbanned")
+<%- end -%>
+  end
+end

data/lib/generators/authnz_eleven/templates/models/concerns/deadboltable.rb.tt

@@ -0,0 +1,39 @@
+module <%= identity.class_name %>::Deadboltable
+  extend ActiveSupport::Concern
+
+  class_methods do
+    def register_failed_attempt(identifier)
+      <%= multi_login? ? "find_by_login(identifier)" : "find_by(#{login_field}: identifier)" %>&.tap(&:register_failed_attempt!)
+    end
+  end
+
+  def deadbolted?
+    deadbolted_at.present? && deadbolted_at > <%= identity.config_reference %>.deadbolt.duration.ago
+  end
+
+  def deadbolt!
+    update!(deadbolted_at: Time.current, failed_attempts: 0)
+<%- if trackable? -%>
+    record_event("<%= identity.singular %>.deadbolted")
+<%- end -%>
+  end
+
+  def undeadbolt!
+    update!(deadbolted_at: nil, failed_attempts: 0)
+<%- if trackable? -%>
+    record_event("<%= identity.singular %>.undeadbolted")
+<%- end -%>
+  end
+
+  def register_failed_attempt!
+    return if deadbolted?
+    increment!(:failed_attempts)
+
+    maximum_attempts = <%= identity.config_reference %>.deadbolt.maximum_attempts
+    deadbolt! if maximum_attempts && failed_attempts >= maximum_attempts
+  end
+
+  def reset_failed_attempts!
+    update_column(:failed_attempts, 0) if failed_attempts.positive?
+  end
+end

data/lib/generators/authnz_eleven/templates/models/concerns/email_verifiable.rb.tt

@@ -0,0 +1,52 @@
+module <%= identity.class_name %>::EmailVerifiable
+  extend ActiveSupport::Concern
+
+  included do
+    normalizes :pending_email, with: -> { it.strip.downcase.presence }
+<%- if email_encrypted? -%>
+    encrypts :pending_email
+<%- end -%>
+    validates :pending_email, <%= principals.email.validation %>, allow_nil: true
+<%- unless coy? -%>
+    validate { errors.add(:pending_email, :taken) if pending_email_taken? }
+<%- end -%>
+
+    generates_token_for :email_change_verification, expires_in: <%= identity.config_reference %>.tokens.email_change_verification do
+      pending_email
+    end
+<%- if trackable? -%>
+
+    after_update if: :email_previously_changed? do
+      record_event("<%= identity.singular %>.email_changed")
+    end
+<%- end -%>
+  end
+
+  def stage_email(address)
+    self.pending_email = address
+
+    if pending_email.blank?
+      self.email = nil
+    elsif pending_email == email
+      self.pending_email = nil
+    end
+    self
+  end
+
+  def pending_email_taken?
+    pending_email.present? && <%= identity.class_name %>.exists?(email: pending_email)
+  end
+
+  def verify_pending_email
+    update(email: pending_email, pending_email: nil)
+  rescue ActiveRecord::RecordNotUnique
+    errors.add(:email, :taken)
+    false
+  end
+
+  def send_email_change_verification
+    return if pending_email.nil? || pending_email_taken?
+
+    <%= identity.mailer_class %>.with(signed_id: generate_token_for(:email_change_verification), to: pending_email).email_change_verification.deliver_later
+  end
+end

data/lib/generators/authnz_eleven/templates/models/concerns/eventable.rb.tt

@@ -0,0 +1,22 @@
+module <%= identity.namespaced_class("Eventable") %>
+  extend ActiveSupport::Concern
+
+  included do
+    has_many :events, as: :subject, dependent: :destroy
+  end
+
+  def record_event(event_type, actor: nil, context: nil, occurred_at: nil, data: nil)
+    <%= identity.event_class %>.record!(
+      event_type: event_type,
+      subject: self,
+      actor: actor,
+      context: context,
+      occurred_at: occurred_at,
+      data: data
+    )
+  end
+
+  def event_context
+    self
+  end
+end

data/lib/generators/authnz_eleven/templates/models/concerns/guestable.rb.tt

@@ -0,0 +1,30 @@
+module <%= identity.class_name %>::Guestable
+  extend ActiveSupport::Concern
+
+  included do
+    scope :guests, -> { where(guest: true) }
+
+    scope :expired_guests, -> { guests.where(created_at: ...<%= identity.config_reference %>.guest.ttl.ago) }
+  end
+
+  class_methods do
+    def create_guest!
+      create! do |user|
+<%- if principals.email -%>
+        user.email = "guest_#{SecureRandom.uuid}@example.com"
+<%- end -%>
+<%- if principals.username -%>
+        user.username = "guest_#{SecureRandom.base58(12)}"
+<%- end -%>
+        user.guest = true
+      end
+    end
+  end
+
+  def absorb_guest(guest)
+    transaction do
+      # Extension point: move any guest-owned state onto this account before the guest row goes.
+      guest.destroy
+    end
+  end
+end

data/lib/generators/authnz_eleven/templates/models/concerns/invitable.rb.tt

@@ -0,0 +1,12 @@
+module <%= identity.class_name %>::Invitable
+  extend ActiveSupport::Concern
+
+  included do
+<%- if teams? -%>
+    has_many :accepted_invitations, class_name: "<%= identity.invitation_class %>", foreign_key: :invitee_id, inverse_of: :invitee, dependent: :destroy
+<%- else -%>
+    has_one :invitation, foreign_key: :invitee_id, inverse_of: :invitee, dependent: :destroy
+<%- end -%>
+    has_many :sent_invitations, class_name: "<%= identity.invitation_class %>", foreign_key: :inviter_id, inverse_of: :inviter, dependent: :destroy
+  end
+end

data/lib/generators/authnz_eleven/templates/models/concerns/magic_linkable.rb.tt

@@ -0,0 +1,34 @@
+module <%= identity.class_name %>::MagicLinkable
+  extend ActiveSupport::Concern
+
+  included do
+    generates_token_for :magic_link, expires_in: <%= identity.config_reference %>.tokens.magic_link do
+      [ email, Rails.cache.read(magic_link_nonce_key) ] # nonce makes magic links single-use
+    end
+  end
+
+  class_methods do
+    def request_magic_link(email)
+      find_by(email:)&.tap(&:send_magic_link)
+    end
+
+    def consume_magic_link(token)
+      if (user = find_by_token_for(:magic_link, token)) && Rails.cache.delete(user.magic_link_nonce_key)
+        user
+      end
+    end
+  end
+
+  def generate_magic_link
+    Rails.cache.write(magic_link_nonce_key, SecureRandom.hex(16), expires_in: <%= identity.config_reference %>.tokens.magic_link)
+    generate_token_for(:magic_link)
+  end
+
+  def magic_link_nonce_key
+    "<%= identity.singular %>:magic_link_nonce:#{id}"
+  end
+
+  def send_magic_link
+    <%= identity.mailer_class %>.with(signed_id: generate_magic_link, to: email).magic_link.deliver_later
+  end
+end

data/lib/generators/authnz_eleven/templates/models/concerns/password_historical.rb.tt

@@ -0,0 +1,28 @@
+module <%= identity.class_name %>::PasswordHistorical
+  extend ActiveSupport::Concern
+
+  included do
+    has_many :password_histories, dependent: :delete_all
+
+    validate :password_not_recently_used, if: :will_save_change_to_password_digest?
+
+    after_update if: :password_digest_previously_changed? do
+      password_histories.create!(password_digest: password_digest_previously_was)
+      depth = <%= identity.config_reference %>.password.history_depth
+      password_histories.order(id: :desc).offset(depth).destroy_all if depth
+    end
+  end
+
+  private
+
+  def password_not_recently_used
+    depth = <%= identity.config_reference %>.password.history_depth
+    return if depth.nil?
+
+    recent = password_histories.order(id: :desc).limit(depth).pluck(:password_digest)
+    recent << password_digest_in_database if password_digest_in_database.present?
+    if recent.any? { |digest| self.class.new(password_digest: digest).authenticate(password) }
+      errors.add(:password, "was used recently. Please choose a different one")
+    end
+  end
+end

data/lib/generators/authnz_eleven/templates/models/concerns/password_policy.rb.tt

@@ -0,0 +1,38 @@
+module <%= identity.password_policy_concern %>
+  extend ActiveSupport::Concern
+
+  included do
+    has_secure_password
+
+<%- unless password_nullable? -%>
+    validates :password, presence: true, length: { minimum: <%= identity.config_reference %>.password.minimum_length }, allow_nil: true
+<%- else -%>
+    validates :password, length: { minimum: <%= identity.config_reference %>.password.minimum_length }, allow_nil: true
+<%- end -%>
+<%- if pwned? -%>
+    validates :password, not_pwned: { message: "was found in a data breach and can't be used" },
+      if: -> { <%= identity.config_reference %>.password.check_breaches }
+<%- end -%>
+<%- if strong_passwords? -%>
+    validate :password_strength, if: -> { password.present? }
+<%- end -%>
+  end
+
+  def password_set? = password_digest_in_database.present?
+<%- if password_nullable? -%>
+
+  def errors
+    super.tap { |errors| errors.delete(:password, :blank)<%= " if password_may_be_blank?" unless password_blank_rows_all? %> }
+  end
+<%- end -%>
+<%- if strong_passwords? -%>
+
+  private
+
+  def password_strength
+    return if Zxcvbn.test(password).score >= <%= identity.config_reference %>.password.minimum_strength
+
+    errors.add(:password, :too_weak, message: "is too weak. Try adding length or making it less predictable.")
+  end
+<%- end -%>
+end

data/lib/generators/authnz_eleven/templates/models/concerns/password_rotatable.rb.tt

@@ -0,0 +1,15 @@
+module <%= identity.class_name %>::PasswordRotatable
+  extend ActiveSupport::Concern
+
+  included do
+    before_save if: :will_save_change_to_password_digest? do
+      self.password_changed_at = Time.current
+    end
+  end
+
+  def password_fresh?
+    max_age = <%= identity.config_reference %>.password.maximum_age
+    return true if max_age.nil? || password_changed_at.nil?
+    password_changed_at > max_age.ago
+  end
+end

data/lib/generators/authnz_eleven/templates/models/concerns/phone_verifiable.rb.tt

@@ -0,0 +1,50 @@
+module <%= identity.class_name %>::PhoneVerifiable
+  extend ActiveSupport::Concern
+
+  included do
+    normalizes :pending_phone, with: -> { Phonelib.parse(it, <%= identity.config_reference %>.phone.default_country).to_s.presence }
+<%- if phone_encrypted? -%>
+    encrypts :pending_phone
+<%- end -%>
+    validates :pending_phone, phone: { allow_blank: true, countries: <%= identity.config_reference %>.phone.allowed_countries, format: :e164 }
+<%- unless coy? -%>
+    validate { errors.add(:pending_phone, :taken) if pending_phone_taken? }
+<%- end -%>
+<%- if trackable? -%>
+
+    after_update if: :phone_previously_changed? do
+      record_event("<%= identity.singular %>.phone_changed")
+    end
+<%- end -%>
+  end
+
+  def stage_phone(number)
+    self.pending_phone = number
+
+    if pending_phone.blank?
+      self.phone = nil
+    elsif pending_phone == phone
+      self.pending_phone = nil
+    end
+    self
+  end
+
+  def pending_phone_taken?
+    pending_phone.present? && <%= identity.class_name %>.exists?(phone: pending_phone)
+  end
+
+  def request_phone_change_verification
+    if pending_phone_taken?
+      clear_sms_challenge
+    else
+      issue_sms_challenge(to: pending_phone)
+    end
+  end
+
+  def verify_pending_phone
+    update(phone: pending_phone, pending_phone: nil)
+  rescue ActiveRecord::RecordNotUnique
+    errors.add(:phone, :taken)
+    false
+  end
+end

data/lib/generators/authnz_eleven/templates/models/concerns/principals.rb.tt

@@ -0,0 +1,67 @@
+module <%= identity.principals_concern %>
+  extend ActiveSupport::Concern
+
+  included do
+<%- principals.each_with_index do |principal, index| -%>
+<%- unless index.zero? -%>
+
+<%- end -%>
+    normalizes :<%= principal.column %>, with: <%= principal.normalization(config_reference: identity.config_reference) %>
+<%- if principal.channel? && encrypted_pii? -%>
+    encrypts :<%= principal.column %>, deterministic: true # .find_by works, sorting, ranges, and %LIKE% will not.
+<%- end -%>
+<%- if principal.type == :email && coy? -%>
+    # Do not add a uniqueness validation for email or phone as this would reveal the existence of users. The database index enforces uniqueness.
+<%- end -%>
+<%- if principal.dedicated_validation? -%>
+<%- if guest_excused_from_phone? -%>
+    validates :phone, presence: true, unless: :guest?
+<%- elsif principal.required? -%>
+    validates :phone, presence: true
+<%- end -%>
+    validates :phone, phone: { allow_blank: true, countries: <%= identity.config_reference %>.phone.allowed_countries, format: :e164 }
+<%- else -%>
+    validates :<%= principal.column %>, <%= principal.validates_arguments %>
+<%- end -%>
+<%- if principal.type == :username -%>
+    validate :username_not_forbidden
+<%- end -%>
+<%- end -%>
+<%- if login_key_may_be_missing? -%>
+
+    validate :at_least_one_login_key
+<%- end -%>
+<%- if contactable_validation? -%>
+
+    validate :must_be_contactable
+<%- end -%>
+  end
+<%- if principals.username || login_key_may_be_missing? -%>
+
+  private
+<%- end -%>
+<%- if login_key_may_be_missing? -%>
+
+  def at_least_one_login_key
+    return if <%= login_principals.map { |p| "#{p.column}.present?" }.join(" || ") %>
+
+    errors.add(:base, "Enter <%= login_keys_article_phrase %>.")
+  end
+<%- end -%>
+<%- if contactable_validation? -%>
+
+  def must_be_contactable
+    return if <%= principals.select(&:channel?).map { |p| "#{p.column}.present?" }.join(" || ") %>
+
+    errors.add(:base, "Add <%= channel_keys_article_phrase %>.")
+  end
+<%- end -%>
+<%- if principals.username -%>
+
+  def username_not_forbidden
+    return if username.blank?
+
+    errors.add(:username, "is forbidden") if <%= identity.config_reference %>.username.forbidden.include?(username.downcase)
+  end
+<%- end -%>
+end

data/lib/generators/authnz_eleven/templates/models/concerns/recoverable.rb.tt

@@ -0,0 +1,19 @@
+module <%= identity.class_name %>::Recoverable
+  extend ActiveSupport::Concern
+
+  included do
+    generates_token_for :password_reset, expires_in: <%= identity.config_reference %>.tokens.password_reset do
+      [ password_salt&.last(10), email ]
+    end
+  end
+
+  class_methods do
+    def request_password_reset(email)
+      find_by(email:)&.tap(&:send_password_reset)
+    end
+  end
+
+  def send_password_reset
+    <%= identity.mailer_class %>.with(signed_id: generate_token_for(:password_reset), to: email).password_reset.deliver_later
+  end
+end

data/lib/generators/authnz_eleven/templates/models/concerns/second_factor.rb.tt

@@ -0,0 +1,52 @@
+module <%= identity.class_name %>::SecondFactor
+  extend ActiveSupport::Concern
+
+  included do
+    has_many :recovery_codes, dependent: :destroy
+
+<%- if password? -%>
+    generates_token_for :authentication_challenge, expires_in: <%= identity.config_reference %>.tokens.mfa_challenge do
+      password_salt
+    end
+<%- else -%>
+    generates_token_for :authentication_challenge, expires_in: <%= identity.config_reference %>.tokens.mfa_challenge
+<%- end -%>
+<%- if totp? -%>
+
+    encrypts :totp_secret
+
+    before_create do
+      self.totp_secret = ROTP::Base32.random
+    end
+<%- end -%>
+  end
+
+  def second_factor_enrolled?
+    <%= second_factor_enrolled_clauses.join(" || ") %>
+  end
+
+  def reset_second_factor!
+    transaction do
+<%- if totp? -%>
+      update!(totp_enrolled_at: nil, totp_secret: ROTP::Base32.random)
+<%- end -%>
+<%- if sms_second_factor? -%>
+      update!(sms_enrolled_at: nil)
+      clear_sms_challenge
+<%- end -%>
+<%- if security_keys? -%>
+      <%= second_factor_keys_expr %>.destroy_all
+<%- end -%>
+      discard_orphaned_recovery_codes!
+<%- if trackable? -%>
+      record_event("<%= identity.singular %>.second_factor_reset")
+<%- end -%>
+    end
+  end
+
+  # Recovery codes bypass the second factor as a whole, so they outlive any one
+  # of them and die with the last.
+  def discard_orphaned_recovery_codes!
+    recovery_codes.delete_all unless second_factor_enrolled?
+  end
+end

data/lib/generators/authnz_eleven/templates/models/concerns/sms_challengeable.rb.tt

@@ -0,0 +1,38 @@
+module <%= identity.class_name %>::SmsChallengeable
+  def issue_sms_challenge(to: phone)
+    return false if to.blank?
+
+    code = format("%06d", SecureRandom.random_number(1_000_000))
+    Rails.cache.write(sms_challenge_key(:code), { code: code, to: to }, expires_in: <%= identity.config_reference %>.tokens.sms_code)
+    Rails.cache.delete(sms_challenge_key(:tries))
+
+    Sms.deliver_later(to: to, body: "#{code} is your #{<%= identity.config_reference %>.app_name} verification code.")
+    true
+  end
+
+  def verify_sms_challenge(submitted, to: phone)
+    tries = Rails.cache.increment(sms_challenge_key(:tries), 1, expires_in: <%= identity.config_reference %>.tokens.sms_code)
+    challenge = Rails.cache.read(sms_challenge_key(:code))
+    return false if tries.nil? || tries > <%= identity.config_reference %>.sms.max_attempts
+    return false unless challenge && challenge[:to] == to
+    return false unless ActiveSupport::SecurityUtils.secure_compare(challenge[:code], submitted.to_s)
+
+    clear_sms_challenge
+    true
+  end
+
+  def sms_challenge?(to: phone)
+    to.present? && Rails.cache.read(sms_challenge_key(:code))&.fetch(:to) == to
+  end
+
+  def clear_sms_challenge
+    Rails.cache.delete(sms_challenge_key(:code))
+    Rails.cache.delete(sms_challenge_key(:tries))
+  end
+
+  private
+
+  def sms_challenge_key(kind)
+    "sms-#{kind}:#{self.class.name}:#{id}"
+  end
+end