masks 0.2.0

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

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Masks
+  module Rails
+    class Recovery < ApplicationRecord
+      self.table_name = "recoveries"
+
+      scope :recent,
+            lambda {
+              where(
+                "created_at >= ?",
+                Masks.configuration.lifetimes[:recovery_email]&.ago ||
+                  1.hour.ago
+              )
+            }
+      scope :expired,
+            lambda {
+              where(
+                "created_at < ?",
+                Masks.configuration.lifetimes[:recovery_email]&.ago ||
+                  1.hour.ago
+              )
+            }
+
+      belongs_to :actor, class_name: Masks.configuration.models[:actor]
+
+      validates :token, presence: true, uniqueness: { scope: :actor_id }
+      validates :contact, presence: true, if: :actor
+      validate :validates_actor
+
+      attribute :configuration
+      attribute :session
+      attribute :value
+
+      after_initialize :generate_token
+      after_initialize :load_actor, unless: :actor_id
+
+      def to
+        case contact
+        when Email
+          contact.email
+        end
+      end
+
+      def notified?
+        notified_at.present?
+      end
+
+      def reset_password!(password)
+        return unless actor && persisted?
+
+        actor.password = password
+
+        return unless actor.valid?
+
+        actor.save!
+        destroy!
+      end
+
+      def notify!
+        return if !valid? || notified?
+
+        self.notified_at = Time.current
+        save!
+
+        case contact
+        when Email
+          ActorMailer.with(recovery: id).recover_credentials.deliver_later
+        end
+      end
+
+      def contact
+        return unless actor
+
+        @contact ||=
+          begin
+            contact =
+              if email
+                actor.emails.find_by(verified: true, email:)
+              elsif phone
+                # TODO
+              end
+
+            contact ||= actor.emails.where(verified: true).first
+            contact
+          end
+      end
+
+      def to_param
+        token
+      end
+
+      private
+
+      def generate_token
+        self.token ||= SecureRandom.hex(64)
+      end
+
+      def validates_actor
+        return if !actor || actor.valid?
+
+        actor.errors.full_messages.each { |error| errors.add(:base, error) }
+      end
+
+      def load_actor
+        return unless value
+
+        loaded =
+          self.actor = configuration.find_actor(session, email:, nickname:)
+
+        loaded.recoveries << self if loaded
+        loaded
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Masks
+  module Rails
+    class Role < ApplicationRecord
+      include Masks::Role
+
+      self.table_name = "roles"
+
+      belongs_to :actor, polymorphic: true, autosave: true
+      belongs_to :record, polymorphic: true, autosave: true
+
+      validates :type,
+                presence: true,
+                uniqueness: {
+                  scope: %i[actor_id actor_type record_id record_type]
+                }
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Masks
+  module Rails
+    class Scope < ApplicationRecord
+      self.table_name = "scopes"
+
+      validates :name, presence: true, uniqueness: { scope: :actor_id }
+
+      belongs_to :actor,
+                 polymorphic: true,
+                 class_name: Masks.configuration.models[:actor]
+    end
+  end
+end

data/app/models/masks/session.rb

@@ -0,0 +1,447 @@
+# frozen_string_literal: true
+
+module Masks
+  # Interface for sessions, which keep track of attempts to access resources.
+  #
+  # The helper methods provided by the +Masks+ module are wrappers around
+  # the +Masks::Session+ class. Masks creates different types of sessions
+  # dependending on the context, calls their +mask!+ method, and records
+  # the results.
+  #
+  # This class is designed to be sub-classed. Sub-classes must provide a +data+,
+  # +params+, and +matches_mask?+ method. The latter method is how a session
+  # is able to find a suitable mask from the configuration.
+  #
+  # After a session's +mask!+ method is called, it will report an +actor+,
+  # whether or not the checks it ran have +passed?+, and any +errors+ (just like
+  # an +ActiveRecord+ model).
+  #
+  # @see Masks::Check Masks::Check
+  # @see Masks::Credentials Masks::Credentials
+  # @see Masks::Sessions Masks::Sessions
+  # @see Masks::Mask Masks::Mask
+  class Session < ApplicationModel
+    CHECK_KEY = :masks
+
+    attribute :name
+    attribute :actor
+    attribute :scopes
+    attribute :scoped
+    attribute :credentials
+    attribute :checks, default: -> { {} }
+    attribute :config
+    attribute :error_messages
+
+    validates :actor, presence: true
+
+    class << self
+      def mask!(*args, **opts)
+        new(*args, **opts).tap(&:mask!)
+      end
+    end
+
+    # Returns an identifier for the session.
+    #
+    # This value can be used to reference the session in backend processes.
+    #
+    # @return [String]
+    def id
+      data[:session_id] || "anonymous"
+    end
+
+    # Returns the session's IP address or nil in cases where no IP is present.
+    #
+    # @return [String] or nil
+    def ip_address
+      nil
+    end
+
+    # Returns the session's user agent.
+    #
+    # Ideally this is always specified, but there are contexts where it cannot be supplied.
+    #
+    # @return [String] or nil
+    def user_agent
+      nil
+    end
+
+    # Returns a user-supplied "fingerprint" for the session.
+    #
+    # Generally speaking, this is a low-trust value.
+    #
+    # @return [String] or nil
+    def fingerprint
+      nil
+    end
+
+    # Returns a detected device based on the +user_agent+.
+    #
+    # If the user agent isn't present a detected device is still returned, but
+    # it's attributes will return nil and its +known?+ method will return false.
+    #
+    # @return [DeviceDetector]
+    def device
+      @device ||= DeviceDetector.new(user_agent)
+    end
+
+    # Whether or not the session's actor is anonymous?
+    delegate :anonymous?, to: :actor, allow_nil: true
+
+    # A hash of persisted session data.
+    #
+    # @return [Hash]
+    def data
+      raise NotImplementedError
+    end
+
+    # Incoming "request" params that could affect the session.
+    #
+    # @return [Hash]
+    def params
+      raise NotImplementedError
+    end
+
+    # Normalizes +params[:session]+ and returns it.
+    #
+    # Paramaters intended for the session should be nested under the +session+ key.
+    #
+    # @return [Hash]
+    def session_params
+      (params[:session] || {}).deep_symbolize_keys
+    end
+
+    # Additional short-lived data (not session or request data)
+    #
+    # @param [Hash] opts a hash of extra data to merge
+    def extras(**opts)
+      @extras ||= {}
+      @extras.merge!(**opts.stringify_keys) if opts.keys
+      @extras
+    end
+
+    # Returns a specific key from the session +extras+ or nil.
+    #
+    # @param [Symbol|String] key the name of the key
+    # @return [any]
+    def extra(key)
+      @extras&.fetch(key.to_s, nil)
+    end
+
+    # Sets the actor on the session.
+    #
+    # If the actor is already set then an error will be
+    # added to the session, preventing it from passing.
+    #
+    # @param [Masks::Actor] actor
+    def actor=(actor)
+      if self.actor && actor != self.actor
+        errors.add(:base, :multiple_actors)
+      else
+        super(actor)
+      end
+    end
+
+    delegate :scopes,
+             :scope?,
+             :role?,
+             :roles_for,
+             :role_records,
+             to: :scoped,
+             allow_nil: true
+
+    # Returns the "scoped" actor, which may be different from the actor itself.
+    #
+    # For example, in some cases access is gained via an API key or some
+    # person/system with "admin" rights. In both cases there is an agent
+    # agent operating the system that is granted the ability to behave
+    # as someone else.
+    #
+    # This scoped actor may respond to the methods available for interrogating
+    # scopes and roles differently than the actor itself—e.g. an access key may
+    # return a smaller set of scopes than the actor. An admin may temporarily
+    # allow additional scopes...
+    #
+    # @return [Masks::Scoped]
+    def scoped
+      super || actor
+    end
+
+    # Returns a check by the name provided.
+    #
+    # @param [Symbol|String] key
+    # @return [Masks::Check]
+    def find_check(key)
+      return unless key&.present?
+
+      id = key.to_sym
+
+      unless checks[id]
+        defaults = mask.checks[id] || {}
+        checks[id] = Check.new(key: id, **defaults)
+      end
+
+      checks.fetch(id)
+    end
+
+    # Masks the session.
+
+    # @return [self]
+    def mask!
+      Masks.event "session", session: self do
+        return if mask&.skip?
+
+        self.credentials =
+          mask.credentials.map do |cls|
+            cred = cls.new(session: self)
+
+            # give credentials a chance to populate the session...
+            # typically this is by providing an actor to validate
+            if (actor = cred.lookup)
+              self.actor = actor
+            end
+
+            cred
+          end
+
+        self.checks = load_checks(mask.checks)
+
+        # session data can reveal checks that are still valid
+        # based on duration. skip checking again in this case.
+        return if passed?
+
+        transaction do
+          # each credential is given a chance to mask the session
+          credentials.each do |cred|
+            cred.mask!
+
+            if cred.errors.any?
+              cred.errors.full_messages.each do |message|
+                errors.add(:base, message)
+              end
+            end
+          rescue RuntimeError
+            return cleanup!
+          end
+
+          actor&.session = self
+
+          # to ensure that we are going to be passed?
+          if actor && !actor.valid?(:mask)
+            actor.errors.full_messages.each do |message|
+              errors.add(:base, message)
+            end
+          elsif !passed_checks?
+            errors.add(:base, :credentials)
+          elsif !passed?
+            errors.add(:base, :access)
+          elsif !actor&.mask!
+            errors.add(:base, actor.errors.full_messages.first || :credentials)
+          end
+
+          credentials.each(&:backup!)
+          commit_to_session
+        end
+
+        self
+      end
+    end
+
+    # Cleans up all session data, akin to logout.
+    #
+    # @return [self]
+    def cleanup!
+      Masks.event "cleanup", session: self do
+        mask.credentials.each do |cls|
+          cred = cls.new(session: self)
+          cred.cleanup!
+        end
+
+        if actor
+          data[:masks] ||= {}
+          data[:masks].delete(actor.session_key)
+        end
+
+        self
+      end
+    end
+
+    # Returns an access class based on this session.
+    #
+    # @param [String] name
+    # @raise [Masks::Error]
+    # @return [Masks::Access]
+    def access(name)
+      Masks.access(name, self)
+    end
+
+    # Whether or not the session is "writable".
+    #
+    # Some credentials only allow certain operations when in
+    # this state, which is akin to the difference between
+    # GET and POST.
+    #
+    # @return [Boolean]
+    def writable?
+      # certain operations should only happen when the credential is in writable
+      # mode, e.g. GET vs POST requests. override this method to customize the behaviour
+      true
+    end
+
+    # Whether or not to allow access to the actor identified by the session.
+    #
+    # This method aims to be a simple test to determine whether or not
+    # a session has passed all checks.
+    #
+    # @return [Boolean]
+    def passed?
+      return true if mask&.skip?
+      return false if !passed_checks? || errors.any?
+      return false unless matches_mask?(mask)
+      return false unless actor
+      return false unless mask.matches_session?(self)
+      return false unless pass?
+
+      true
+    end
+
+    # Returns the time the session passed all checks, provided they have.
+    #
+    # This method may return a time in the past—for example when credential
+    # checks passed in that past, but within their configured lifetime.
+    #
+    # @return [Datetime]
+    def passed_at
+      return unless passed?
+
+      checks.values.map(&:passed_at).compact.max
+    end
+
+    # Returns a hash of all checks that happened in the past.
+    #
+    # These checks are stored in the session data, under +CHECK_KEY+.
+    #
+    # @return [Hash]
+    def past_checks
+      @past_checks ||= data[CHECK_KEY]&.clone || {}
+    end
+
+    # Returns a hash of checks for a given type.
+    #
+    # If any of the checks in the type exist on the session, it will be
+    # returned. Otherwise a new check is constructed and included in the
+    # set.
+    #
+    # This is useful for introspecting the state of a session according
+    # to the rules of another type, but keep in mind that this does not
+    # allow the credentials configured on the type to run, so checks
+    # may report a passing status despite being stale.
+    #
+    # @return [Hash]
+    def checks_for(type)
+      return false unless actor_checks
+
+      load_checks(config.data.dig(:types, type.to_sym, :checks))
+    end
+
+    # Returns whether or not the session checks report a passing status.
+    #
+    # Pass an optional type to see if the session's checks pass according
+    # to the type's checks, useful for determining the potential state of
+    # a session.
+    #
+    # @param [String] type
+    # @return [Boolean]
+    def passed_checks?(type = nil)
+      return true unless checks.any?
+      return false unless actor_checks
+
+      to_check =
+        (
+          if type
+            load_checks(config.data.dig(:types, type.to_sym, :checks))
+          else
+            checks.slice(*mask.checks.keys)
+          end
+        )
+      to_check.values.all?(&:passed?)
+    end
+
+    # A single error message for the session, as opposed to a list of errors
+    #
+    # @return [String] or nil
+    def error_message
+      errors.full_messages.last
+    end
+
+    # The mask the session will use.
+    #
+    # @return [Masks::Mask]
+    # @raise [Masks::Error::UnknownMask]
+    def mask
+      @mask ||=
+        begin
+          mask = config.masks.find { |m| matches_mask?(m) }
+          raise Error::UnknownMask, self unless mask
+          mask
+        end
+    end
+
+    protected
+
+    # Whether or not the given mask matches the session.
+    #
+    # Sub-classes must implement this method, which is used to match the session
+    # itself to a mask from +Masks.configuration+.
+    #
+    # @return [Boolean]
+    def matches_mask?(mask)
+      raise NotImplementedError
+    end
+
+    # Sub-classes can return a falsey value to fail the session for any reason.
+    #
+    # @return [Boolean]
+    def pass?
+      true
+    end
+
+    private
+
+    def transaction(&block)
+      if actor.respond_to?(:transaction)
+        actor.transaction(&block)
+      elsif actor&.class.respond_to?(:transaction)
+        actor.class.transaction(&block)
+      else
+        block.call
+      end
+    end
+
+    def commit_to_session
+      return unless mask&.backup?
+      return unless actor&.backup?
+
+      data[:masks] ||= {}
+      data[:masks][actor.session_key] ||= {}
+      checks.each do |id, check|
+        data[:masks][actor.session_key][id.to_s] = check.to_session
+      end
+    end
+
+    def load_checks(defaults)
+      defaults ||= {}
+      past = actor_checks || {}
+
+      defaults
+        .deep_merge(past.deep_symbolize_keys)
+        .to_h { |key, opts| [key, Check.new(opts.merge(key:))] }
+        .slice(*defaults.keys)
+    end
+
+    def actor_checks
+      return unless actor&.session_key
+
+      past_checks[actor.session_key] ||= {}
+    end
+  end
+end

data/app/models/masks/sessions/access.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Masks
+  module Sessions
+    # Session for masking access classes.
+    class Access < Masks::Session
+      attribute :name
+      attribute :original
+
+      delegate :actor,
+               :config,
+               :params,
+               :data,
+               :writable?,
+               :extras,
+               :extra,
+               to: :original
+
+      def matches_mask?(mask)
+        return false unless mask.access == name.to_s
+
+        original.mask.access&.try(:include?, name.to_s) || original.mask.access
+      end
+    end
+  end
+end

data/app/models/masks/sessions/inline.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Masks
+  module Sessions
+    # Session for masking inline ruby code.
+    class Inline < Masks::Session
+      attribute :name
+      attribute :data
+      attribute :params
+
+      def matches_mask?(mask)
+        true if mask.name == name
+      end
+    end
+  end
+end

data/app/models/masks/sessions/request.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Masks
+  module Sessions
+    # Session for masking +ActionDispatch::Request+ and +Rack::Request+.
+    class Request < Masks::Session
+      attribute :request
+
+      def to_s
+        "mask(#{request.method.upcase} #{request.path})"
+      end
+
+      def ip_address
+        request.remote_ip
+      end
+
+      def user_agent
+        request.user_agent
+      end
+
+      def fingerprint
+        params[:_fingerprint]
+      end
+
+      def params
+        request.params
+      end
+
+      def data
+        request.session
+      end
+
+      def matches_mask?(mask)
+        mask.matches_request?(request)
+      end
+
+      def writable?
+        request.post?
+      end
+    end
+  end
+end

data/app/resources/masks/actor_resource.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Masks
+  class ActorResource
+    include Alba::Resource
+
+    attributes :nickname
+  end
+end

data/app/resources/masks/session_resource.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Masks
+  class SessionResource
+    include Alba::Resource
+
+    attributes :id, :ip_address, :user_agent, :fingerprint, :scopes
+
+    attribute :authorized, &:passed?
+
+    attribute :actor do |session|
+      ActorResource.new(session.actor).to_h
+    end
+  end
+end