authnz_eleven 0.1.0

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

@@ -0,0 +1,20 @@
+module <%= identity.class_name %>::TeamMember
+  extend ActiveSupport::Concern
+
+  included do
+    has_many :memberships, dependent: :destroy
+    has_many :teams, through: :memberships
+  end
+
+  def on_a_team?
+    memberships.any?
+  end
+
+  def primary_team
+    teams.first
+  end
+
+  def member_of?(team)
+    memberships.exists?(team:)
+  end
+end

data/lib/generators/authnz_eleven/templates/models/current.rb.tt

@@ -0,0 +1,28 @@
+class <%= identity.current_class %> < ActiveSupport::CurrentAttributes
+  attribute :session
+  attribute :user_agent, :ip_address, :request_id
+<%- if impersonatable? -%>
+  attribute :impersonated_user
+
+  def true_user
+    session&.<%= identity.singular %>
+  end
+
+  def user
+    impersonated_user || true_user
+  end
+
+  def user=(user)
+    self.impersonated_user = user
+  end
+<%- else -%>
+
+  def user
+    session&.<%= identity.singular %>
+  end
+<%- end -%>
+<%- if teams? -%>
+
+  attribute :team
+<%- end -%>
+end

data/lib/generators/authnz_eleven/templates/models/event.rb.tt

@@ -0,0 +1,32 @@
+class <%= identity.event_class %> < ApplicationRecord
+  belongs_to :subject, polymorphic: true
+  belongs_to :actor, polymorphic: true, optional: true
+  belongs_to :context, polymorphic: true, optional: true
+
+  scope :chronological, -> { order(occurred_at: :asc, id: :asc) }
+  scope :recent_first, -> { order(occurred_at: :desc, id: :desc) }
+
+  def self.record!(
+    event_type:,
+    subject:,
+    actor: nil,
+    context: nil,
+    occurred_at: nil,
+    data: nil,
+    ip_address: nil,
+    user_agent: nil,
+    request_id: nil
+  )
+    create!(
+      event_type: event_type,
+      subject: subject,
+      actor: actor || <%= identity.current_class %>.user,
+      context: context || subject.try(:event_context) || subject,
+      occurred_at: occurred_at || Time.current,
+      data: data || {},
+      ip_address: ip_address || <%= identity.current_class %>.ip_address,
+      user_agent: user_agent || <%= identity.current_class %>.user_agent,
+      request_id: request_id || <%= identity.current_class %>.request_id
+    )
+  end
+end

data/lib/generators/authnz_eleven/templates/models/invitation.rb.tt

@@ -0,0 +1,122 @@
+class <%= identity.invitation_class %> < ApplicationRecord
+  belongs_to :inviter, class_name: "<%= identity.class_name %>", inverse_of: :sent_invitations
+  belongs_to :invitee, class_name: "<%= identity.class_name %>", optional: true, inverse_of: :<%= teams? ? "accepted_invitations" : "invitation" %>
+<%- if teams? -%>
+  belongs_to :team, optional: true
+<%- end -%>
+
+  generates_token_for :invitation, expires_in: <%= identity.config_reference %>.tokens.invitation do
+<%- if multi_channel_invitable? -%>
+    [ sent_to, sent_to_channel, accepted_at ]
+<%- else -%>
+    [ sent_to, accepted_at ]
+<%- end -%>
+  end
+
+<%- if multi_channel_invitable? -%>
+  normalizes :sent_to, with: -> {
+    it.include?("@") ? it.strip.downcase : Phonelib.parse(it, <%= identity.config_reference %>.phone.default_country).to_s
+  }
+
+  before_validation do
+    self.sent_to_channel = sent_to&.include?("@") ? "email" : "phone" if will_save_change_to_sent_to?
+  end
+
+  validates :sent_to, presence: true
+  validates :sent_to_channel, inclusion: { in: %w[email phone] }
+  validates :sent_to, <%= principals.email.validation %>, if: :email_addressed?
+  validates :sent_to, phone: { countries: <%= identity.config_reference %>.phone.allowed_countries, format: :e164 }, if: :phone_addressed?
+<%- elsif email_invitable? -%>
+  normalizes :sent_to, with: <%= principals.email.normalization(config_reference: identity.config_reference) %>
+  validates :sent_to, presence: true, <%= principals.email.validation %>
+<%- else -%>
+  normalizes :sent_to, with: <%= principals.phone.normalization(config_reference: identity.config_reference) %>
+  validates :sent_to, presence: true
+  validates :sent_to, phone: { countries: <%= identity.config_reference %>.phone.allowed_countries, format: :e164 }
+<%- end -%>
+<%- if encrypted_pii? -%>
+
+  encrypts :sent_to, deterministic: true
+<%- end -%>
+<%- if coy? -%>
+
+  def offer_unless_redundant
+    offer unless redundant?
+  end
+<%- else -%>
+
+  validate on: :create do
+<%- if teams? -%>
+    errors.add(:base, team ? "#{sent_to} is already a member of #{team.name}." : "#{sent_to} already has an account.") if redundant?
+<%- else -%>
+    errors.add(:base, "#{sent_to} already has an account.") if redundant?
+<%- end -%>
+  end
+<%- end -%>
+
+  def offer
+    update!(expires_at: <%= identity.config_reference %>.tokens.invitation.from_now)
+    signed_id = generate_token_for(:invitation)
+<%- if multi_channel_invitable? -%>
+
+    if email_addressed?
+      <%= identity.mailer_class %>.with(invitation: self, signed_id:, to: sent_to).invitation.deliver_later
+    else
+      Sms.deliver_later(to: sent_to, body: sms_message(signed_id))
+    end
+<%- elsif email_invitable? -%>
+    <%= identity.mailer_class %>.with(invitation: self, signed_id:, to: sent_to).invitation.deliver_later
+<%- else -%>
+    Sms.deliver_later(to: sent_to, body: sms_message(signed_id))
+<%- end -%>
+    signed_id
+  end
+
+  def accepted?
+    accepted_at.present?
+  end
+
+<%- unless multi_channel_invitable? -%>
+  def sent_to_channel = "<%= email_invitable? ? "email" : "phone" %>"
+
+<%- end -%>
+  def email_addressed? = sent_to_channel == "email"
+  def phone_addressed? = sent_to_channel == "phone"
+
+  def addressed_to?(user)
+    sent_to == user[sent_to_channel]
+  end
+
+  def redundant?
+<%- if teams? -%>
+    (team ? team.<%= identity.plural %> : <%= identity.class_name %>).exists?(sent_to_channel => sent_to)
+<%- else -%>
+    <%= identity.class_name %>.exists?(sent_to_channel => sent_to)
+<%- end -%>
+  end
+
+  def accept(user)
+    return false unless addressed_to?(user)
+
+    with_lock do
+      return false if accepted?
+
+      update!(invitee: user, accepted_at: Time.current)
+<%- if teams? -%>
+      team.memberships.find_or_create_by!(<%= identity.singular %>: user) if team
+<%- end -%>
+    end
+
+    true
+  end
+<%- if phone_invitable? -%>
+
+  private
+
+  def sms_message(signed_id)
+    url = Rails.application.routes.url_helpers.<%= identity.namespaced? ? "#{identity.route_scope}_accept_invitation_url" : "accept_invitation_url" %>(
+      token: signed_id, **Rails.application.config.action_mailer.default_url_options)
+    "#{inviter.<%= principals.display.column %>} invited you to #{<%= identity.config_reference %>.app_name}: #{url}"
+  end
+<%- end -%>
+end

data/lib/generators/authnz_eleven/templates/models/membership.rb.tt

@@ -0,0 +1,16 @@
+class <%= identity.membership_class %> < ApplicationRecord
+  belongs_to :<%= identity.singular %>
+  belongs_to :team
+
+  validates :<%= identity.foreign_key %>, uniqueness: { scope: :team_id }
+<%- if session_carries_team? -%>
+
+  after_destroy :clear_active_team_from_sessions
+
+  private
+
+  def clear_active_team_from_sessions
+    <%= identity.session_class %>.where(<%= identity.foreign_key %>:, team_id:).update_all(team_id: nil)
+  end
+<%- end -%>
+end

data/lib/generators/authnz_eleven/templates/models/omniauth_identity.rb.tt

@@ -0,0 +1,12 @@
+class <%= identity.omniauth_identity_class %> < ApplicationRecord
+  belongs_to :<%= identity.singular %>
+
+  validates :provider, presence: true
+  validates :uid, presence: true, uniqueness: { scope: :provider }
+
+  # The provider named by a sign-in, e.g. :google for google_oauth2.
+  def self.via(provider) = provider.to_s.split("_").first.downcase.to_sym
+
+  def via = self.class.via(provider)
+  def provider_name = via.to_s.titleize
+end

data/lib/generators/authnz_eleven/templates/models/password_history.rb.tt

@@ -0,0 +1,3 @@
+class <%= identity.password_history_class %> < ApplicationRecord
+  belongs_to :<%= identity.singular %>
+end

data/lib/generators/authnz_eleven/templates/models/pending_registration.rb.tt

@@ -0,0 +1,216 @@
+class <%= identity.pending_registration_class %> < ApplicationRecord
+  include <%= identity.principals_concern %>
+<%- if password? -%>
+  include <%= identity.password_policy_concern %>
+<%- end -%>
+<%- if sms? -%>
+  include <%= identity.class_name %>::SmsChallengeable
+<%- end -%>
+<%- if invitable? -%>
+
+  belongs_to :invitation<%= invite_only? ? "" : ", optional: true" %>
+<%- end -%>
+
+  Completion = Struct.new(:status, :user, :via)
+<%- if pre_account_passkey_enrollment? -%>
+
+  attr_accessor :passkey
+<%- end -%>
+
+<%- if email_gated_registration? -%>
+  generates_token_for :registration_email_verification, expires_in: <%= identity.config_reference %>.tokens.registration_email_verification do
+    [ email, email_verified_at ]
+  end
+<%- end -%>
+
+  scope :expired, -> { where(updated_at: ...<%= identity.config_reference %>.tokens.pending_registration.ago) }
+  scope :unexpired, -> { where(updated_at: <%= identity.config_reference %>.tokens.pending_registration.ago..) }
+<%- if pre_account_passkey_enrollment? -%>
+
+  before_validation on: :create do
+    self.webauthn_handle ||= WebAuthn.generate_user_id
+  end
+<%- end -%>
+<%- if invitable? && (email_verifiable? || phone_verifiable?) -%>
+
+  before_create :verify_invited_channel
+<%- end -%>
+<%- if principals.username -%>
+
+  validate :username_not_taken
+<%- end -%>
+<%- if guest_excused_from_phone? -%>
+
+  def guest? = false
+<%- end -%>
+<%- if password_nullable? && !password_blank_rows_all? -%>
+
+  def password_may_be_blank? = <%= staged_password_blank_rows_expression %>
+<%- end -%>
+
+  def next_step
+<%- if omniauth_registration? -%>
+    return :complete_profile if <%= omniauth_profile_missing_condition %>
+<%- end -%>
+<%- if email_verifiable? -%>
+    return :verify_email if email.present? && email_verified_at.blank?
+<%- end -%>
+<%- if phone_gated_registration? -%>
+    return :verify_phone if phone.present? && phone_verified_at.blank?
+<%- end -%>
+<%- if credential_staged_registration? -%>
+    return :enroll_credential unless sign_in_methods.any?
+<%- end -%>
+    :complete
+  end
+
+  def sign_in_methods
+    methods = []
+<%- if password? -%>
+    methods << :password if password_digest.present?
+<%- end -%>
+<%- if pre_account_passkey_enrollment? -%>
+    methods << :passkey if passkey
+<%- end -%>
+<%- if pending_registration_holds_provider? -%>
+    methods << :omniauth if provider.present?
+<%- end -%>
+<%- if magic_link? -%>
+    methods << :magic_link if email.present?<%= email_verifiable? ? " && email_verified_at.present?" : "" %>
+<%- end -%>
+<%- if sms_code? -%>
+    methods << :sms_code if phone.present?<%= phone_verifiable? ? " && phone_verified_at.present?" : "" %>
+<%- end -%>
+    methods
+  end
+
+  def complete
+    return Completion.new(:invalid) unless valid?
+
+    user = <%= identity.class_name %>.new(account_attributes)
+<%- if pre_account_passkey_enrollment? -%>
+    user.webauthn_credentials.build(**passkey, name: "Passkey"<%= factor_attr(:first_factor) %>) if passkey
+<%- end -%>
+<%- if pending_registration_holds_provider? -%>
+    user.omniauth_identities.build(provider:, uid:) if provider
+<%- end -%>
+
+    unless user.save
+      errors.merge!(user.errors)
+      return collision_result || Completion.new(:invalid)
+    end
+
+<%- if invitable? -%>
+    invitation&.accept(user)
+<%- end -%>
+    destroy!
+<%- if pending_registration_holds_provider? -%>
+    Completion.new(:created, user, provider ? <%= identity.omniauth_identity_class %>.via(provider) : :registration)
+<%- else -%>
+    Completion.new(:created, user, :registration)
+<%- end -%>
+  rescue ActiveRecord::RecordNotUnique
+    collision_result || raise
+  end
+<%- if email_gated_registration? -%>
+
+  def request_email_verification
+    touch # keeps :expired from reaping this while verification is in progress
+    return if <%= identity.class_name %>.exists?(email: email)
+
+    signed_id = generate_token_for(:registration_email_verification)
+    <%= identity.mailer_class %>.with(signed_id: signed_id, to: email).registration_email_verification.deliver_later
+  end
+<%- end -%>
+<%- if phone_gated_registration? -%>
+
+  def request_phone_verification
+    touch # keeps :expired from reaping this while verification is in progress
+    return if <%= identity.class_name %>.exists?(phone: phone)
+
+    issue_sms_challenge
+  end
+<%- end -%>
+
+  private
+<%- if invitable? && (email_verifiable? || phone_verifiable?) -%>
+
+  def verify_invited_channel
+    return unless invitation&.addressed_to?(self)
+
+<%- if multi_channel_invitable? && email_verifiable? && phone_verifiable? -%>
+    if invitation.email_addressed?
+      self.email_verified_at = Time.current
+<%- if principals.phone.optional? -%>
+      self.phone = nil
+<%- end -%>
+    else
+      self.phone_verified_at = Time.current
+<%- if principals.email.optional? -%>
+      self.email = nil
+<%- end -%>
+    end
+<%- elsif email_invitable? && email_verifiable? -%>
+    self.email_verified_at = Time.current
+<%- elsif phone_invitable? && phone_verifiable? -%>
+    self.phone_verified_at = Time.current
+<%- end -%>
+  end
+<%- end -%>
+
+  def account_attributes
+    attributes = {}
+<%- principals.each do |principal| -%>
+<%- if principal.type == :email && email_verifiable? -%>
+    attributes[:email] = email if email_verified_at.present?
+<%- elsif principal.type == :phone && phone_verifiable? -%>
+    attributes[:phone] = phone if phone_verified_at.present?
+<%- else -%>
+    attributes[:<%= principal.column %>] = <%= principal.column %>
+<%- end -%>
+<%- end -%>
+<%- if password? -%>
+    attributes[:password_digest] = password_digest
+<%- end -%>
+<%- if pre_account_passkey_enrollment? -%>
+    attributes[:webauthn_handle] = webauthn_handle
+<%- end -%>
+    attributes
+  end
+
+  def collision_result
+<%- if pending_registration_holds_provider? -%>
+    if provider.present? && <%= identity.omniauth_identity_class %>.exists?(provider:, uid:)
+      destroy!
+      return Completion.new(:taken)
+    end
+<%- end -%>
+<%- if principals.username -%>
+    if username.present? && <%= identity.class_name %>.where("LOWER(username) = ?", username.downcase).exists?
+      errors.add(:username, "has already been taken")
+      return Completion.new(:invalid)
+    end
+<%- end -%>
+<%- if principals.email -%>
+    if email.present? && <%= identity.class_name %>.exists?(email: email)
+      destroy!
+      return Completion.new(:taken)
+    end
+<%- end -%>
+<%- if principals.phone -%>
+    if <%= phone_verifiable? ? "phone_verified_at.present?" : "phone.present?" %> && <%= identity.class_name %>.exists?(phone: phone)
+      destroy!
+      return Completion.new(:taken)
+    end
+<%- end -%>
+    nil
+  end
+<%- if principals.username -%>
+
+  def username_not_taken
+    return if username.blank?
+
+    errors.add(:username, "has already been taken") if <%= identity.class_name %>.where("LOWER(username) = ?", username.downcase).exists?
+  end
+<%- end -%>
+end

data/lib/generators/authnz_eleven/templates/models/recovery_code.rb.tt

@@ -0,0 +1,41 @@
+class <%= identity.recovery_code_class %> < ApplicationRecord
+  belongs_to :<%= identity.singular %>
+
+  class << self
+    def regenerate_for(user)
+      codes = Array.new(<%= identity.config_reference %>.second_factor.recovery_code_count) { generate_code }
+
+      transaction do
+        user.recovery_codes.delete_all
+        user.recovery_codes.create!(codes.map { |code| { code: code } })
+      end
+
+      codes
+    end
+
+    def redeem(user:, code:)
+      return false unless user.recovery_codes.where(code_digest: digest(code)).delete_all == 1
+
+<%- if trackable? -%>
+      user.record_event(
+        "<%= identity.singular %>.recovery_code_used",
+        actor: user,
+        data: { remaining: user.recovery_codes.count }
+      )
+<%- end -%>
+      true
+    end
+
+    def generate_code
+      SecureRandom.alphanumeric(<%= identity.config_reference %>.second_factor.recovery_code_length).downcase
+    end
+
+    def digest(code)
+      OpenSSL::HMAC.hexdigest("SHA256", Rails.application.secret_key_base, code.to_s) # An HMAC prevents a database leak from exposing recovery codes that can be used to bypass the second factor.
+    end
+  end
+
+  def code=(plaintext)
+    self.code_digest = self.class.digest(plaintext)
+  end
+end

data/lib/generators/authnz_eleven/templates/models/session.rb.tt

@@ -0,0 +1,46 @@
+class <%= identity.session_class %> < ApplicationRecord
+  belongs_to :<%= identity.singular %>
+<%- if session_carries_team? -%>
+  belongs_to :team, optional: true
+<%- end -%>
+<%- if identity.namespaced? -%>
+
+  alias_method :user, :<%= identity.singular %>
+<%- end -%>
+<%- if timeoutable? -%>
+
+  def self.idle_timeout
+    <%= identity.config_reference %>.session.idle_timeout
+  end
+
+  scope :active,    -> { where(updated_at: idle_timeout.ago..) }
+<%- if guestable? -%>
+  scope :timed_out, -> { where(updated_at: ...idle_timeout.ago).where.not(<%= identity.singular %>: <%= identity.class_name %>.guests) }
+<%- else -%>
+  scope :timed_out, -> { where(updated_at: ...idle_timeout.ago) }
+<%- end -%>
+<%- end -%>
+
+  before_create do
+    self.user_agent = <%= identity.current_class %>.user_agent
+    self.ip_address = <%= identity.current_class %>.ip_address
+  end
+<%- if trackable? -%>
+
+  after_create do
+<%- if guestable? -%>
+    <%= identity.singular %>.record_event("<%= identity.singular %>.signed_in", actor: <%= identity.singular %>, data: { via:, user_agent:, ip_address: }) unless <%= identity.singular %>.guest?
+<%- else -%>
+    <%= identity.singular %>.record_event("<%= identity.singular %>.signed_in", actor: <%= identity.singular %>, data: { via:, user_agent:, ip_address: })
+<%- end -%>
+  end
+
+  after_destroy do
+<%- if guestable? -%>
+    <%= identity.singular %>.record_event("<%= identity.singular %>.signed_out", actor: <%= identity.singular %>, data: { via:, user_agent:, ip_address: }) unless <%= identity.singular %>.guest?
+<%- else -%>
+    <%= identity.singular %>.record_event("<%= identity.singular %>.signed_out", actor: <%= identity.singular %>, data: { via:, user_agent:, ip_address: })
+<%- end -%>
+  end
+<%- end -%>
+end

data/lib/generators/authnz_eleven/templates/models/team.rb.tt

@@ -0,0 +1,12 @@
+class <%= identity.team_class %> < ApplicationRecord
+  has_many :memberships, dependent: :destroy
+  has_many :<%= identity.plural %>, through: :memberships
+<%- if invitable? -%>
+  has_many :invitations, dependent: :destroy
+<%- end -%>
+<%- if session_carries_team? -%>
+  has_many :sessions, dependent: :nullify
+<%- end -%>
+
+  validates :name, presence: true
+end

data/lib/generators/authnz_eleven/templates/models/user.rb.tt

@@ -0,0 +1,59 @@
+class <%= identity.class_name %> < ApplicationRecord
+  include <%= identity.principals_concern %>
+  include Authenticatable
+<%- if password? -%>
+  include <%= identity.password_policy_concern %>
+<%- end -%>
+<%- if password_rotatable? -%>
+  include PasswordRotatable
+<%- end -%>
+<%- if password_historical? -%>
+  include PasswordHistorical
+<%- end -%>
+<%- if recoverable? -%>
+  include Recoverable
+<%- end -%>
+<%- if magic_link? -%>
+  include MagicLinkable
+<%- end -%>
+<%- if second_factor? -%>
+  include SecondFactor
+<%- end -%>
+<%- if deadboltable? -%>
+  include Deadboltable
+<%- end -%>
+<%- if bannable? -%>
+  include Bannable
+<%- end -%>
+<%- if sms? -%>
+  include SmsChallengeable
+<%- end -%>
+<%- if email_change_verification? -%>
+  include EmailVerifiable
+<%- end -%>
+<%- if phone_change_verification? -%>
+  include PhoneVerifiable
+<%- end -%>
+<%- if teams? -%>
+  include TeamMember
+<%- end -%>
+<%- if adminable? -%>
+  include Adminable
+<%- end -%>
+<%- if trackable? -%>
+  include Eventable
+<%- end -%>
+<%- if guestable? -%>
+  include Guestable
+<%- end -%>
+<%- if invitable? -%>
+  include Invitable
+<%- end -%>
+<%- unique_principals = principals.reject { |principal| principal.channel? && coy? } -%>
+<%- if unique_principals.any? -%>
+
+<%- unique_principals.each do |principal| -%>
+  validates :<%= principal.column %>, uniqueness: <%= principal.channel? ? "true, allow_nil: true" : "{ case_sensitive: false }" %>
+<%- end -%>
+<%- end -%>
+end

data/lib/generators/authnz_eleven/templates/models/webauthn_credential.rb.tt

@@ -0,0 +1,12 @@
+class <%= identity.webauthn_credential_class %> < ApplicationRecord
+  belongs_to :<%= identity.singular %>
+
+  validates :name, presence: true
+<%- if passkey_and_security_keys? -%>
+
+  enum :authentication_factor, { first_factor: 0, second_factor: 1 }
+
+  scope :passkeys,       -> { first_factor }
+  scope :second_factors, -> { second_factor }
+<%- end -%>
+end

data/lib/generators/authnz_eleven/templates/tasks/authnz_eleven.rake.tt

@@ -0,0 +1,41 @@
+namespace :authnz_eleven do
+<%- if identity.namespaced? -%>
+  namespace :<%= identity.task_namespace %> do
+<%- end -%>
+<%- if guestable? -%>
+  desc "Delete stale guest users (and their sessions) older than config.guest.ttl"
+  task delete_expired_guests: :environment do
+    scope = <%= identity.class_name %>.expired_guests
+
+    count = scope.count
+    scope.find_each(&:destroy)
+
+    puts "Deleted #{count} expired guest user(s)."
+  end
+<%- end -%>
+<%- if guestable? && timeoutable? -%>
+
+<%- end -%>
+<%- if pending_registration? -%>
+  desc "Delete sign-ups abandoned for longer than config.tokens.pending_registration"
+  task delete_expired_pending_registrations: :environment do
+    count = <%= identity.pending_registration_class %>.expired.destroy_all.size
+
+    puts "Deleted #{count} expired pending registration(s)."
+  end
+<%- end -%>
+<%- if pending_registration? && timeoutable? -%>
+
+<%- end -%>
+<%- if timeoutable? -%>
+  desc "Delete sessions that have timed out (idle past config.session.idle_timeout)"
+  task delete_timed_out_sessions: :environment do
+    count = <%= identity.session_class %>.timed_out.delete_all
+
+    puts "Deleted #{count} timed-out session(s)."
+  end
+<%- end -%>
+<%- if identity.namespaced? -%>
+  end
+<%- end -%>
+end