masks 0.4.0 → 0.6.0

data/app/models/masks/check.rb

@@ -1,192 +0,0 @@
-# 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

@@ -1,166 +0,0 @@
-# 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/access_token.rb

@@ -1,60 +0,0 @@
-# frozen_string_literal: true
-
-module Masks
-  module Credentials
-    # Checks :key given a valid Authorization header.
-    class AccessToken < Masks::Credential
-      checks :access_token
-
-      def lookup
-        access_token =
-          session.config.model(:openid_access_token).valid.find_by(token:)
-
-        return unless access_token&.actor
-
-        session.extras(access_token:)
-        session.scoped = access_token
-
-        access_token.actor
-      end
-
-      def maskup
-        access_token = session.extra(:access_token)
-
-        if access_token&.actor && access_token&.actor == session&.actor &&
-             session.scoped == access_token
-          approve!
-        else
-          deny!
-        end
-      end
-
-      private
-
-      def token
-        return if [header_token, param_token].uniq.compact.length != 1
-
-        header_token || param_token
-      end
-
-      def header_token
-        unless auth_header.provided? && !auth_header.parts.first.nil? &&
-                 auth_header.scheme.to_s == "bearer"
-          return
-        end
-
-        auth_header.params
-      end
-
-      def param_token
-        params[:access_token]
-      end
-
-      def auth_header
-        return unless session.try(:request)
-
-        @auth_header = Rack::Auth::AbstractRequest.new(session.request.env)
-      end
-    end
-  end
-end

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

@@ -1,30 +0,0 @@
-# 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

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

@@ -1,59 +0,0 @@
-# frozen_string_literal: true
-
-module Masks
-  module Credentials
-    # Checks for a known, valid :device.
-    #
-    # If the device is not associated with the session's actor, it will be.
-    # Identification is based on the +user_agent+ and a few other facets.
-    class Device < Masks::Credential
-      checks :device
-
-      def lookup
-        return unless actor
-
-        device = config.find_device(session, actor:)
-
-        session.extras(device:)
-
-        nil
-      end
-
-      def maskup
-        device = session.extra(:device)
-
-        return deny! unless device
-
-        session_key = session.data[:device_key]
-
-        # ensure devices match across sessions, which would only happen if a
-        # session cookie happened is shared across machines. this destroys
-        # the entire session and cleans up everything involved.
-        if session_key && device.session_key != session_key
-          raise "invalid device"
-        end
-
-        # store devices that are found in a database of known devices
-        if device.known?
-          session.data[:device_key] = device.session_key
-          actor.devices << device
-          approve!
-        else
-          cleanup
-          deny!
-        end
-      end
-
-      def backup
-        session.extra(:device)&.touch(:accessed_at) if session&.passed?
-      end
-
-      def cleanup
-        device = session.extra(:device)
-        device&.reset_version
-
-        session.data[:device_key] = nil
-      end
-    end
-  end
-end

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

@@ -1,48 +0,0 @@
-# frozen_string_literal: true
-
-module Masks
-  module Credentials
-    # Checks for an :actor given a matching email.
-    class Email < Masks::Credential
-      checks :actor
-
-      def lookup
-        return if actor || !email
-
-        actor = config.find_actor(session, email:)
-        actor ||=
-          config.build_actor(
-            session,
-            email:,
-            nickname: generate_nickname(email)
-          )
-        actor.signup = true
-        actor
-      end
-
-      def maskup
-        approve! if actor && email && valid?
-      end
-
-      private
-
-      def email
-        @email ||=
-          [session_params[:email], session_params[:nickname]].find do |param|
-            ValidateEmail.valid?(param)
-          end
-      end
-
-      def generate_nickname(email)
-        return email if !nickname_format || nickname_format.match?(email)
-
-        parts = email.split("@")
-        name = parts[0].gsub(/[^\w\d]/, "")
-
-        prefix_nickname(
-          "#{name.downcase.slice(0, 16)}#{SecureRandom.hex.slice(0, 8)}"
-        )
-      end
-    end
-  end
-end

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

@@ -1,71 +0,0 @@
-# frozen_string_literal: true
-
-module Masks
-  module Credentials
-    # Base class for factor2 credentials.
-    module Factor2
-      extend ActiveSupport::Concern
-
-      included do
-        validates :secret, presence: true, if: :enabled?
-        validates :code, presence: { allow_nil: true }
-
-        attribute :code
-
-        checks :factor2
-      end
-
-      def lookup
-        # nothing to do here
-      end
-
-      def maskup
-        check.optional = false if actor&.factor2?
-
-        return unless enabled?
-
-        code_param = session_params&.fetch(param, nil)&.presence
-
-        self.code = verify(code_param) if code_param
-
-        if code
-          approve!
-        elsif code_param
-          deny!
-        end
-      end
-
-      def verified?
-        code
-      end
-
-      def enabled?
-        secret.present?
-      end
-
-      def param
-        raise NotImplementedError
-      end
-
-      def secret
-        raise NotImplementedError
-      end
-
-      def enable(code, secret:)
-        raise NotImplementedError
-      end
-
-      def verify(code)
-        raise NotImplementedError
-      end
-
-      def verify_on_enable?
-        false
-      end
-
-      def generate_secret
-        nil
-      end
-    end
-  end
-end

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

@@ -1,38 +0,0 @@
-# frozen_string_literal: true
-
-module Masks
-  module Credentials
-    # Checks :key given a valid Authorization header.
-    class Key < Masks::Credential
-      checks :key
-
-      attribute :accessed
-
-      def lookup
-        secret = session.request.authorization&.split&.last
-        key = session.config.find_key(session, secret:)
-
-        return unless key
-
-        session.extras(key:)
-        session.scoped = key
-        self.accessed = true
-        key.actor
-      end
-
-      def maskup
-        key = session.extra(:key)
-
-        if key&.actor == session&.actor && session.scoped == key
-          approve!
-        else
-          deny!
-        end
-      end
-
-      def backup
-        session.extra(:key).touch(:accessed_at) if session&.passed? && accessed
-      end
-    end
-  end
-end

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

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-module Masks
-  module Credentials
-    # As of now, simply keeps track of +last_login+ times on the actor.
-    class LastLogin < Masks::Credential
-      def backup
-        actor&.touch(:last_login_at) if session&.passed?
-      end
-    end
-  end
-end

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

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-module Masks
-  module Credentials
-    # Checks for an :actor to masquerade as.
-    class Masquerade < Masks::Credential
-      checks :actor
-
-      def lookup
-        return if session.actor
-
-        value = session.data[:as]
-
-        @loaded =
-          case value
-          when Masks::ANON
-            Actors::Anonymous.new(session:) if session.mask&.allow_anonymous?
-          when session.mask.actor_scope
-            value
-          when ValidateEmail.valid?(value)
-            config.find_actor(session, email: value)
-          when String
-            config.find_actor(session, nickname: prefix_nickname(value))
-          end
-      end
-
-      def maskup
-        approve! if @loaded
-      end
-    end
-  end
-end