masks 0.2.0

data/app/models/concerns/masks/scoped.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Masks
+  # A smaller interface that all scoped actors should adhere to.
+  #
+  # @see Masks::Rails::Actor Masks::Rails::Actor
+  # @see Masks::Actor Masks::Actor
+  module Scoped
+    # Returns a list of scopes granted to the actor.
+    #
+    # @return [Array<String>] An array of scopes (as strings)
+    def scopes
+      raise NotImplementedError
+    end
+
+    # Returns whether or not a scope is available.
+    #
+    # In practice this is similar to calling +scopes.include?(scope)+,
+    # but implementations may provide faster implementations.
+    #
+    # @param [String] scope
+    # @return [Boolean]
+    def scope?(scope)
+      scopes.include?(scope.to_s)
+    end
+
+    # Returns a list of Masks::Role records for the scoped actor.
+    #
+    # @param [String|Object] record or type
+    # @param [Hash] opts to use for additional filtering
+    # @return [Masks::Role]
+    def roles(record, **opts)
+      raise NotImplementedError
+    end
+
+    # Returns whether or not a role is available to the scoped actor.
+    #
+    # @param [String|Object] record or type
+    # @param [Hash] opts to use for additional filtering
+    # @return [Boolean]
+    def role?(record, **opts)
+      roles(record, **opts).any?
+    end
+
+    # Similar to roles_for, except all _records_ are returned instead of the role.
+    #
+    # @param [String|Object] record_type record or type
+    # @param [Hash] opts to use for additional filtering
+    # @return [Object] a list of records, duplicates removed
+    def role_records(record_type, **opts)
+      roles(record_type, **opts).map(&:record).uniq
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Masks
+  module Access
+    # Access class for +actor.password+
+    #
+    # This access class can change that actor's password.
+    class ActorPassword
+      include Access
+
+      access "actor.password"
+
+      def change_password(password)
+        actor.changed_password_at = Time.current
+        actor.password = password
+        actor.save if actor.valid?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Masks
+  module Access
+    # Access class for +actor.scopes+
+    #
+    # This access class can add or remove scopes from an actor.
+    class ActorScopes
+      include Access
+
+      access "actor.scopes"
+
+      def assign_scopes(scopes)
+        actor.assign_scopes!(*scopes)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Masks
+  module Access
+    # Access class for +actor.signup+.
+    #
+    # This access class creates a new actor.
+    class ActorSignup
+      include Access
+
+      access "actor.signup"
+
+      def signup(**opts)
+        actor =
+          configuration.build_actor(session, **opts.slice(:nickname, :email))
+        actor.password = opts[:password]
+        actor.save if actor.valid?
+        actor
+      end
+    end
+  end
+end

data/app/models/masks/actors/anonymous.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Masks
+  module Actors
+    # An anonymous actor, used for cases where deemed acceptable.
+    #
+    # @see Masks::Actor
+    class Anonymous < ApplicationModel
+      include Masks::Actor
+
+      attribute :session
+
+      # Generates and returns random nickname for the actor.
+      #
+      # @return [String]
+      def nickname
+        @nickname ||= "anon:#{SecureRandom.hex}"
+      end
+
+      # @return [Array] an empty array, since no scopes are available to anonymous actors
+      def scopes
+        []
+      end
+
+      # This is a no-op for anonymous actors. It always returns true.
+      #
+      # @return [Boolean]
+      def mask!
+        true
+      end
+
+      # Mark this actor as anonymous.
+      #
+      # @return [Boolean]
+      def anonymous?
+        true
+      end
+    end
+  end
+end

data/app/models/masks/actors/system.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Masks
+  module Actors
+    # Actor for system tasks.
+    class System < ApplicationModel
+      include Masks::Actor
+
+      attribute :session
+
+      def nickname
+        @nickname ||= "system:#{SecureRandom.hex}"
+      end
+
+      def scopes
+        []
+      end
+
+      def mask!
+        true
+      end
+    end
+  end
+end

data/app/models/masks/adapters/active_record.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Masks
+  module Adapters
+    # ActiveRecord adapter for masks.
+    #
+    # Although this is designed for masks built-in models, any models
+    # adhering to the same interface can be used. It is also possible to
+    # override and extend the models used in the configuration.
+    #
+    # @see Masks::Adapter
+    class ActiveRecord
+      include Masks::Adapter
+
+      def find_key(_session, secret:)
+        Masks::Rails::Key.find_by(sha: Masks::Rails::Key.sha(secret))
+      end
+
+      def find_device(session, actor: nil, key: nil)
+        device = session.device
+        actor ||= session.actor
+
+        return unless device.known? && actor
+
+        key ||=
+          Digest::SHA512.hexdigest(
+            [
+              device.name,
+              device.os_name,
+              device.device_name,
+              device.device_type
+            ].compact.join("-")
+          )
+
+        record = Masks::Rails::Device.find_or_initialize_by(actor:, key:)
+        record.session = session
+        record
+      end
+
+      def find_actor(session, **opts)
+        if opts[:email]
+          session
+            .mask
+            .actor_scope
+            .includes(:emails)
+            .find_by(emails: { email: opts[:email]&.downcase, verified: true })
+        elsif opts[:nickname]
+          session.mask.actor_scope.find_by(nickname: opts[:nickname])
+        end
+      end
+
+      def find_actors(session, ids)
+        session.mask.actor_scope.where(nickname: ids).to_a
+      end
+
+      def build_actor(session, **opts)
+        opts[:session] = session
+        record =
+          session.mask.actor_scope.new(session:, nickname: opts[:nickname])
+        record.emails.build(email: opts[:email]) if opts[:email]
+        record
+      end
+
+      def expire_actors
+        @config.model(:actor).expired.destroy_all
+      end
+
+      def expire_recoveries
+        @config.model(:recovery).expired.destroy_all
+      end
+
+      def find_recovery(_session, **opts)
+        if opts[:token]
+          @config.model(:recovery).recent.find_by(token: opts[:token])
+        elsif opts[:id]
+          @config.model(:recovery).recent.find_by(id: opts[:id])
+        end
+      end
+
+      def build_recovery(session, **opts)
+        @config.model(:recovery).new(configuration: @config, session:, **opts)
+      end
+    end
+  end
+end

data/app/models/masks/application_model.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Masks
+  # Base model for synthetic +ActiveRecord+-style models in masks.
+  #
+  # Most models in masks use this in their inheritance tree, as it
+  # provides attributes, validations, and other features from
+  # +ActiveModel+.
+  class ApplicationModel
+    include ActiveModel::Model
+    include ActiveModel::Validations
+    include ActiveModel::Attributes
+    include ActiveModel::Serializers::JSON
+  end
+end

data/app/models/masks/application_record.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Masks
+  # Base model for +ActiveRecord+-backed database tables in masks.
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/masks/check.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+module Masks
+  # Checks track attempts to verify one attribute of a session, like the actor
+  # or their password.
+  #
+  # Every session contains a list of checks that can be manipulated while it is
+  # masked.  Credentials associated with the session are typical consumers of
+  # checks, but direct manipulation is possible as well.
+  #
+  # Once a check's consumers have reported their status (approved, denied, or
+  # skipped) it will report an overall status based on the results, either:
+  #
+  # - +passed?+ - true if attempts were made and all were approved, not skipped, or the check is optional
+  # - +failed?+ - true if attempts were made and any were denied
+  #
+  # **Note**: Checks can exist in a middle state, neither passed or failed, in
+  # the case that no attempts were made.
+  #
+  # @see Masks::Credential Masks::Credential
+  class Check < ApplicationModel
+    attribute :key
+    attribute :lifetime
+    attribute :optional, default: false
+    attribute :attempted, default: -> { {} }
+    attribute :approved
+    attribute :skipped
+    attribute :denied
+
+    # Returns a hash of attempts for the check.
+    #
+    # Each key in the hash is the name of a specific attemptee, like a class or
+    # credential. The value is a hash of data about the attempt (like when it was
+    # attempted, approved, denied, and/or skipped).
+    #
+    # @return [Hash]
+    def attempts
+      attempted.deep_merge(@attempts || {}).deep_stringify_keys
+    end
+
+    # Whether or not the check is optional.
+    #
+    # Optional checks always return +true+ for +passed?+.
+    #
+    # @return Boolean
+    def optional?
+      optional
+    end
+
+    # Whether or not the check passed.
+    #
+    # +true+ if attempts were made and all were approved, not skipped, or the check is optional
+    #
+    # @return Boolean
+    def passed?
+      return true if optional? && !failed?
+      return false if attempts.keys.empty?
+
+      attempts.all? do |id, _opts|
+        attempt_approved?(id) || attempt_skipped?(id)
+      end
+    end
+
+    # Returns true if a specific attempt was approved.
+    # @param [String] id
+    # @return Boolean
+    def attempt_approved?(id)
+      opts = attempts.fetch(id.to_s, {})
+
+      return approved unless lifetime
+      return false if opts["skipped_at"]
+
+      time =
+        case opts["approved_at"]
+        when nil
+          return false
+        when String
+          Time.try(:parse, opts["approved_at"])
+        else
+          time
+        end
+
+      if time
+        time + ActiveSupport::Duration.parse(lifetime) > Time.current
+      else
+        false
+      end
+    end
+
+    # Returns true if a specific attempt was skipped.
+    # @param [String] id
+    # @return Boolean
+    def attempt_skipped?(id)
+      opts = attempts.fetch(id.to_s, {})
+      opts["skipped_at"] && optional
+    end
+
+    # Approves an attempt.
+    #
+    # Additional metadata can be passed as keyword arguments, and it will be
+    # saved alongside the attempt data.
+    #
+    # @param [String] id
+    # @param [Hash] opts
+    # @return Boolean
+    def approve!(id, **opts)
+      self.approved = true
+
+      merge_attempt(
+        id,
+        opts.merge(approved_at: Time.current.iso8601, skipped_at: nil)
+      )
+    end
+
+    # Skips an attempt. Skips count as approvals.
+    #
+    # Additional metadata can be passed as keyword arguments, and it will be
+    # saved alongside the attempt data.
+    #
+    # @param [String] id
+    # @param [Hash] opts
+    # @return Boolean
+    def skip!(id, **opts)
+      self.skipped = true
+
+      merge_attempt(
+        id,
+        opts.merge(approved_at: nil, skipped_at: Time.current.iso8601)
+      )
+    end
+
+    # Denies an attempt.
+    #
+    # Additional metadata can be passed as keyword arguments, and it will be
+    # saved alongside the attempt data.
+    #
+    # @param [String] id
+    # @param [Hash] opts
+    # @return Boolean
+    def deny!(id, **opts)
+      self.denied = true
+
+      merge_attempt(id, opts.merge(approved_at: nil, skipped_at: nil))
+    end
+
+    # Returns the time the check passed, if it did.
+    # @return [Datetime]
+    def passed_at
+      return unless passed?
+
+      attempts
+        .map do |_id, opts|
+          time = opts["approved_at"] || opts["skipped_at"]
+          Time.try(:parse, time) if time
+        end
+        .compact
+        .max
+    end
+
+    # Clears all data for attempts by the given +id+.
+    # @param [String] id
+    # @return [Datetime]
+    def clear!(id)
+      @attempts&.except!(id)
+      attempted.except!(id)
+    end
+
+    # Returns a version of the check intended for the rails session.
+    # @return [Hash]
+    def to_session
+      return { optional:, attempted: } unless lifetime
+
+      { optional:, attempted: attempts }
+    end
+
+    private
+
+    def failed?
+      return false if attempts.keys.empty?
+
+      attempts.any? do |id, _opts|
+        !attempt_approved?(id) && !attempt_skipped?(id)
+      end
+    end
+
+    def merge_attempt(id, data)
+      @attempts ||= {}
+      @attempts[id] ||= {}
+      @attempts[id].deep_merge!(data.deep_stringify_keys)
+    end
+  end
+end

data/app/models/masks/credential.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module Masks
+  # A base class for credentials, which identify actors and check their access.
+  #
+  # When a session is masked, a set of credentials are given the chance to
+  # inspect the session parameters, propose an actor, and approve or deny
+  # their access.
+  #
+  # There are a few lifecycle methods available to credentials:
+  #
+  # - +lookup+  - should return an identified actor if found
+  # - +maskup+  - validates the session, actor, and any other data
+  # - +backup+  - records the status of the credential's check(s), if necessary
+  # - +cleanup+ - deletes any recorded data for the credential
+  #
+  # Sessions expect credentials to use checks to record their results, so there
+  # are helper methods to approve, deny, or skip associated checks—+approve!+,
+  # +deny!+, and +skip!+ respectively.
+  #
+  # @see Masks::Check Masks::Check
+  # @see Masks::Credentials Masks::Credentials
+  class Credential < ApplicationModel
+    class << self
+      def checks(value = nil)
+        @checks ||= {}
+        @checks[self.class.name] = value.to_s if value
+        @checks[self.class.name]
+      end
+    end
+
+    attribute :session
+    attribute :masked_at
+    attribute :passed_at
+
+    delegate :config,
+             :actor,
+             :session_params,
+             :account_params,
+             :params,
+             :writable?,
+             to: :session
+
+    # return an actor if it's found and valid
+    def lookup
+      nil
+    end
+
+    def mask!
+      before_mask
+
+      # existing checks (found from the session) can be
+      # skipped when already present and not expired
+      return if check&.passed? && check.attempts[slug] && valid?
+
+      self.masked_at = Time.current
+
+      maskup
+    end
+
+    # verify the session and actor
+    def maskup
+      nil
+    end
+
+    def backup!
+      self.passed_at = Time.current if check&.passed? &&
+        check&.attempt_approved?(slug)
+
+      backup
+    end
+
+    # write any data after all credentials/checks have run
+    def backup
+      nil # but overridable
+    end
+
+    # cleanup data re: the mask
+    def cleanup
+      nil # but overridable
+    end
+
+    def cleanup!
+      cleanup
+      reset!
+    end
+
+    delegate :optional?,
+             :passed?,
+             :skipped?,
+             :invalidated?,
+             to: :check,
+             allow_nil: true
+
+    def slug
+      self.class.name.split("::").join("_").underscore
+    end
+
+    def name
+      I18n.t("auth.credentials.#{slug}.name")
+    end
+
+    def check
+      session&.find_check(self.class.checks)
+    end
+
+    def patch_params
+      session&.account_params&.fetch(slug, {})
+    end
+
+    private
+
+    def before_mask
+      nil
+    end
+
+    def approve!(**opts)
+      check&.approve!(slug, **opts)
+    end
+
+    def deny!(**opts)
+      check&.deny!(slug, **opts)
+    end
+
+    def skip!(**opts)
+      check&.skip!(slug, **opts)
+    end
+
+    def reset!
+      check&.clear!(slug)
+    end
+
+    def nickname_config
+      session.config.dat.nickname
+    end
+
+    def nickname_format
+      return unless nickname_config.format
+
+      Regexp.new(nickname_config.format)
+    end
+
+    def prefix_nickname(value, default: nil)
+      prefix = nickname_config&.prefix
+
+      return default unless value.present?
+
+      prefixed = value
+      prefixed = "#{prefix}#{value}" if prefix && !value.start_with?(prefix)
+
+      return default if nickname_format && !nickname_format.match?(prefixed)
+
+      prefixed
+    end
+
+    def validates_length(key, opts)
+      return unless opts
+
+      if opts[:min] && send(key).length < opts[:min]
+        errors.add(key, :too_short, count: opts[:min])
+      elsif opts[:max] && send(key).length > opts[:max]
+        errors.add(key, :too_long, count: opts[:max])
+      end
+    end
+  end
+end

data/app/models/masks/credentials/backup_code.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Masks
+  module Credentials
+    # Checks :factor2 for a valid backup code.
+    class BackupCode < Masks::Credential
+      include Factor2
+
+      private
+
+      def param
+        :backup_code
+      end
+
+      def secret
+        actor&.backup_codes if actor&.saved_backup_codes?
+      end
+
+      def verify(code)
+        code if secret&.fetch(code, false)
+      end
+
+      def backup
+        return unless verified?
+
+        actor.update_attribute("backup_codes", secret.merge(code => false))
+      end
+    end
+  end
+end