masks 0.2.0

data/app/models/masks/mask.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module Masks
+  # Represents an individual mask, its properties, and methods for interpreting them.
+  #
+  # When a session is created it finds the first matching mask to use for
+  # dictating how to control access. A Mask contains rules that allow sessions
+  # to match them.
+  #
+  # @see Masks::Check Masks::Check
+  # @see Masks::Credentials Masks::Credentials
+  class Mask < ApplicationModel
+    # @!attribute [rw] name
+    #   a unique name for the mask
+    #   @return [String]
+    attribute :name
+    # @!attribute [rw] skip
+    #   Whether or not to skip processing by masks
+    #   @return [Boolean]
+    attribute :skip, default: false
+    # @!attribute [rw] type
+    #   A type name to inherit configuration from
+    #   @return [String]
+    attribute :type
+    # @!attribute [rw] types
+    #   A list of required type names
+    #   @return [String]
+    attribute :types
+    # @!attribute [rw] checks
+    #   A hash of checks required to pass the session
+    #   @return [Hash]
+    attribute :checks
+    # @!attribute [rw] credentials
+    #   An array of credentials that will check the session
+    #   @return [Array<Class>]
+    attribute :credentials
+    # @!attribute [rw] scopes
+    #   An array of scopes required to access the session
+    #   @return [Array<String>]
+    attribute :scopes
+    # @!attribute [rw] request
+    #   A hash of properties an HTTP request must match to use this mask
+    #   @return [Hash]
+    attribute :request
+    # @!attribute [rw] access
+    #   A list of access classes allowed during this session
+    #   @return [Array<String>]
+    attribute :access
+    # @!attribute [rw] actor
+    #   The expected class name of the actor using the sesssion, as a string
+    #   @return [String]
+    attribute :actor
+    # @!attribute [rw] anon
+    #   Whether or not to allow "anonymous" actors
+    #   @return [Boolean]
+    attribute :anon
+    # @!attribute [rw] pass
+    #   What to do when the session passes, typically a redirect uri
+    #   @return [String]
+    attribute :pass, default: "/"
+    # @!attribute [rw] fail
+    #   What to do when the session is failed by checks, credentials, or another error
+    #   @return [String|Boolean]
+    attribute :fail, default: true
+    # @!attribute [rw] backup
+    #   Whether or not to save results of masks
+    #   @return [Boolean]
+    attribute :backup, default: true
+
+    # @visibility private
+    attribute :config
+
+    # @visibility private
+    def initialize(attrs = {})
+      if attrs[:type]
+        type = attrs[:config].mask(attrs[:type])
+        attrs = type.deep_merge(**attrs)
+      end
+
+      super(attrs)
+    end
+
+    # Returns the class name expected for any actor attached to this session.
+    #
+    # @return [String]
+    def actor
+      super || config.models[:actor]
+    end
+
+    # Returns the constantized version of +#actor+.
+    #
+    # @return [String]
+    def actor_scope
+      (actor.constantize unless skip?)
+    end
+
+    # Whether or not sessions matching this mask should skip all work.
+    #
+    # @return [Boolean]
+    def skip?
+      !!skip
+    end
+
+    # Whether or not anonymous actors are allowed in the session.
+    #
+    # @return [Boolean]
+    def allow_anonymous?
+      anon
+    end
+
+    # Whether or not sessions using this mask should be saved.
+    #
+    # Some masks definitely want this enabled, as it is what stores the results
+    # of masks, credentials, and checks in the rails session. In other cases, it
+    # is not necessary, for example when verifying an API key.
+    def backup?
+      return false if skip?
+
+      !!backup
+    end
+
+    # A hash of check configuration, keyed by their name.
+    #
+    # @return [Hash]
+    def checks
+      return {} if skip?
+
+      (type_config&.fetch(:checks, {}) || {}).merge(super || {})
+    end
+
+    # Converts credentials to classes before returning the list.
+    #
+    # @return [Array<Class>]
+    # @raise Masks::Error::InvalidConfiguration
+    def credentials
+      return [] if skip?
+
+      merged = [
+        *(type_config&.fetch(:credentials, []) || []),
+        *(super || [])
+      ].uniq
+      merged.map do |cls|
+        case cls
+        when Class
+          cls
+        when /:+/
+          cls.constantize
+        when String
+          "Masks::Credentials::#{cls}".constantize
+        else
+          raise Masks::Error::InvalidConfiguration, cls
+        end
+      end
+    end
+
+    # Returns whether or not the mask matches the passed session.
+    #
+    # The behaviour of this method depends on the mask's configuration.  For
+    # example, a session with an anonymous actor will return true only if the
+    # mask's +#allow_anonymous?+ method returns true.
+    #
+    # @param [Masks::Session] session
+    # @return [Boolean]
+    def matches_session?(session)
+      actor = session.actor
+
+      return false unless actor
+      return true if actor.anonymous? && allow_anonymous?
+
+      case self.actor
+      when String
+        return false unless actor.is_a?(self.actor.constantize)
+      when Class
+        return false unless actor.is_a?(self.actor)
+      else
+        return false unless actor.is_a?(config.model(:actor))
+      end
+
+      matches_scopes?(session.scopes)
+    end
+
+    # Returns whether or not the mask's request confiig matches the request passed.
+    #
+    # The following parameters are supported in the +request+ hash:
+    #
+    # - +path+ - if specified, the request path must be in this list.
+    # - +method+ - if specified, the request method must be in this list.
+    # - +param+ - if specified, the key must exist in the session params.
+    # - +header+ - if specified, the header must be present in the request.
+    #
+    # @return [Boolean]
+    def matches_request?(request)
+      return false unless self.request
+      return false unless matches_path?(request)
+      return false unless matches_method?(request)
+
+      param = self.request.fetch(:param, nil)
+
+      if param && param != "*" && !request.params&.fetch(param.to_sym, nil)
+        return false
+      end
+
+      header = self.request.fetch(:header, nil)
+
+      return false if header && !request.headers[header]
+
+      true
+    end
+
+    private
+
+    # Returns whether or not the mask's allowed scopes includes one of the scopes passed.
+    #
+    # @return [Boolean]
+    def matches_scopes?(scopes)
+      return true if self.scopes.blank?
+
+      # the mask scopes and scopes passed should have at least one match
+      # otherwise this will return false because the intersection is blank
+      (Array.wrap(self.scopes) & (scopes || [])).present?
+    end
+
+    def matches_path?(request)
+      return true unless (paths = self.request.fetch(:path, nil))
+
+      Array
+        .wrap(paths)
+        .any? do |path|
+          case path
+          when /^r.+/
+            Regexp.new(path.slice(1..)).match?(request.url)
+          else
+            Fuzzyurl.matches?(Fuzzyurl.mask(path:), request.url)
+          end
+        end
+    end
+
+    def matches_method?(request)
+      return true unless (methods = self.request&.fetch(:method, nil))
+      return true if !methods || methods == "*"
+
+      Array
+        .wrap(methods)
+        .map(&:upcase)
+        .any? do |m|
+          m == request.method ||
+            (request.method == "POST" && request.params[:_method]&.upcase == m)
+        end
+    end
+
+    def type_config
+      @type_config ||= config.mask(type) if type
+    end
+  end
+end

data/app/models/masks/rails/actor.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module Masks
+  module Rails
+    class Actor < ApplicationRecord
+      include Masks::Actor
+
+      self.table_name = "actors"
+
+      scope :expired,
+            lambda {
+              where(
+                "last_login_at < ?",
+                Masks.configuration.lifetimes[:expired_actor]&.ago ||
+                  6.months.ago
+              )
+            }
+
+      has_many :saved_scopes,
+               class_name: Masks.configuration.models[:scope],
+               autosave: true
+      has_many :saved_roles,
+               class_name: Masks.configuration.models[:role],
+               autosave: true
+      has_many :recoveries,
+               class_name: Masks.configuration.models[:recovery],
+               autosave: true
+      has_many :emails, class_name: Masks.configuration.models[:email]
+      has_many :devices,
+               class_name: Masks.configuration.models[:device],
+               autosave: true
+      has_many :keys,
+               class_name: Masks.configuration.models[:key],
+               autosave: true
+
+      has_secure_password
+
+      attribute :signup
+      attribute :session
+      attribute :totp_code
+
+      before_validation :reset_version, unless: :version
+
+      validates :nickname, uniqueness: { case_sensitive: false }
+      validates :totp_secret, presence: true, if: :totp_code
+      validates :version, presence: true
+      validate :validates_totp, if: :totp_code
+      validate :validates_password, if: :password
+      validate :validates_signup
+
+      before_save :regenerate_backup_codes
+
+      serialize :backup_codes, coder: JSON
+
+      def email_addresses
+        emails.pluck(:email)
+      end
+
+      def factor2?
+        phone_number || totp_secret
+      end
+
+      def remove_factor2!
+        self.added_totp_secret_at = nil
+        saved_backup_codes_at
+        self.totp_secret = nil
+        self.backup_codes = nil
+        save!
+      end
+
+      def totp_uri
+        (totp || random_totp).provisioning_uri(nickname)
+      end
+
+      def totp_svg(**opts)
+        qrcode = RQRCode::QRCode.new(totp_uri)
+        qrcode.as_svg(**opts)
+      end
+
+      def totp
+        return unless totp_secret
+
+        ROTP::TOTP.new(totp_secret, issuer: Masks.configuration.issuer)
+      end
+
+      def random_totp
+        ROTP::TOTP.new(random_totp_secret, issuer: Masks.configuration.issuer)
+      end
+
+      def random_totp_secret
+        @random_totp_secret ||= ROTP::Base32.random
+      end
+
+      def assign_scopes(*list)
+        list.map { |scope| saved_scopes.find_or_initialize_by(name: scope) }
+      end
+
+      def assign_scopes!(*list)
+        list.map { |scope| saved_scopes.find_or_create_by(name: scope) }
+      end
+
+      def remove_scopes!(*list)
+        saved_scopes.where(name: list).destroy_all
+      end
+
+      def assign_role(record, **opts)
+        saved_roles
+          .find_by!(record:)
+          .tap { |role| role.assign_attributes(**opts) }
+      rescue ActiveRecord::RecordNotFound
+        saved_roles.build(record:, **opts)
+      end
+
+      def assign_role!(record, **opts)
+        assign_role(record, **opts).save!
+      end
+
+      def remove_role!(record)
+        saved_roles.where(record:).destroy_all
+      end
+
+      def scopes
+        @scopes ||= saved_scopes.order(created_at: :desc).pluck(:name)
+      end
+
+      def roles(record, **opts)
+        case record
+        when Class, String
+          saved_roles.where(record_type: record.to_s, **opts).includes(:record)
+        else
+          saved_roles.where(record:, **opts)
+        end
+      end
+
+      def mask!
+        save # sub-classes are encouraged to override
+      end
+
+      def should_save_backup_codes?
+        factor2? && saved_backup_codes_at.blank?
+      end
+
+      def saved_backup_codes?
+        factor2? && saved_backup_codes_at.present?
+      end
+
+      def changed_during_mask?
+        changed? && changes.keys != ["session"]
+      end
+
+      private
+
+      def validates_totp
+        errors.add(:totp_code, :invalid) unless totp.verify(totp_code)
+      end
+
+      def validates_password
+        opts = Masks.configuration.dat.password&.length&.to_h
+
+        return unless password && opts
+
+        if opts[:min] && password.length < opts[:min]
+          errors.add(:password, :too_short, count: opts[:min])
+        elsif opts[:max] && password.length > opts[:max]
+          errors.add(key, :too_long, count: opts[:max])
+        end
+      end
+
+      def validates_signup
+        return unless !persisted? && !Masks.configuration.signups? && signup
+
+        errors.add(:signup, :disabled)
+      end
+
+      def reset_version
+        self.version = SecureRandom.hex
+      end
+
+      def regenerate_backup_codes
+        if factor2?
+          self.backup_codes ||=
+            (1..12).to_h { |_i| [SecureRandom.base58(10), true] }
+        else
+          self.backup_codes = nil
+          self.saved_backup_codes_at = nil
+        end
+      end
+    end
+  end
+end

data/app/models/masks/rails/actor_role.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Masks
+  module Rails
+    class ActorRole < ApplicationRecord
+      self.table_name = "actor_roles"
+
+      belongs_to :actor, class_name: Masks.configuration.models[:actor]
+      belongs_to :role, class_name: Masks.configuration.models[:role]
+    end
+  end
+end

data/app/models/masks/rails/device.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Masks
+  module Rails
+    class Device < ApplicationRecord
+      self.table_name = "devices"
+
+      attribute :session
+
+      belongs_to :actor, class_name: Masks.configuration.models[:actor]
+
+      validates :key, presence: true, uniqueness: { scope: :actor_id }
+      validates :known?, presence: true
+
+      after_initialize :reset_version, unless: :version
+      before_validation :copy_session, if: :session
+
+      def known?
+        session.device&.known?
+      end
+
+      def session_key
+        Digest::SHA512.hexdigest([key, version].join("-"))
+      end
+
+      def reset_version
+        self.version = SecureRandom.hex
+      end
+
+      delegate :name, :device_type, :device_name, :os_name, to: :detected
+
+      private
+
+      def detected
+        @detected ||= DeviceDetector.new(user_agent || session&.user_agent)
+      end
+
+      def copy_session
+        return unless known?
+
+        self.user_agent ||= session.user_agent
+        self.ip_address ||= session.ip_address
+        self.fingerprint ||= session.fingerprint
+      end
+    end
+  end
+end

data/app/models/masks/rails/email.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Masks
+  module Rails
+    class Email < ApplicationRecord
+      self.table_name = "emails"
+
+      belongs_to :actor, class_name: Masks.configuration.models[:actor]
+
+      validates :token, presence: true, uniqueness: true
+      validates :email, presence: true, email: true
+      validates :expired?, absence: true
+
+      validate :validates_verified_email
+
+      after_initialize :generate_token
+      before_validation :downcase_email
+
+      def notify!(session)
+        return if verified?
+
+        if expired? && !verified?
+          self.notified_at = nil
+          self.token = nil
+
+          generate_token
+        end
+
+        return if notified?
+
+        self.notified_at = Time.current
+
+        return unless valid?
+
+        save
+        ActorMailer.with(session:, email: self).verify_email.deliver_now
+      end
+
+      def verify!
+        return if verified?
+
+        self.verified_at = Time.current
+        self.verified = true
+        save!
+      end
+
+      def to_param
+        token
+      end
+
+      def notified?
+        notified_at.present?
+      end
+
+      def expired?
+        return false unless notified?
+
+        notified_at <=
+          (Masks.configuration.lifetimes[:verification_email] || 1.hour).ago
+      end
+
+      def taken?
+        self.class.where(email:, verified: true).any?
+      end
+
+      private
+
+      def validates_verified_email
+        # not sure how to check this with uniqueness conditions,
+        # so using a custom validation
+        query =
+          self.class.where(
+            [
+              persisted? ? "id != :id AND (" : "(",
+              "(email = :email AND verified) OR",
+              "(actor_id = :actor_id AND email = :email)",
+              ")"
+            ].compact.join(" "),
+            actor_id: actor.id,
+            email: email.downcase,
+            id:
+          )
+
+        errors.add(:email, :taken) if query.any?
+      end
+
+      def generate_token
+        self.token ||= SecureRandom.hex
+      end
+
+      def downcase_email
+        self.email = email&.downcase
+      end
+    end
+  end
+end

data/app/models/masks/rails/key.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Masks
+  module Rails
+    class Key < ApplicationRecord
+      include Masks::Scoped
+
+      self.table_name = "keys"
+
+      class << self
+        def sha(secret)
+          Digest::SHA512.hexdigest(secret)
+        end
+      end
+
+      scope :latest, -> { order(created_at: :desc) }
+
+      attribute :session
+      attribute :secret
+
+      serialize :scopes, coder: JSON
+
+      belongs_to :actor, class_name: Masks.configuration.models[:actor]
+
+      after_initialize :generate_hash
+
+      validates :name, presence: true, length: { maximum: 32 }
+      validates :sha, presence: true, uniqueness: true
+
+      def nickname
+        [name.parameterize, sha.slice(0...32)].join("-")
+      end
+
+      alias slug nickname
+
+      def scopes
+        value = self[:scopes]
+
+        return [] unless value
+
+        value & (actor&.scopes || [])
+      end
+
+      def roles_for(_record, **_opts)
+        []
+      end
+
+      private
+
+      def generate_secret
+        self.secret ||= SecureRandom.uuid
+      end
+
+      def generate_hash
+        self.secret ||= SecureRandom.uuid
+
+        self.sha = self.class.sha(secret) if self.secret
+      end
+    end
+  end
+end