masks 0.2.0

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

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

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

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

@@ -0,0 +1,38 @@
+# 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.scoped.touch(:accessed_at) if session&.passed? && accessed
+      end
+    end
+  end
+end

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

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

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

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Masks
+  module Credentials
+    # Checks for an :actor given a matching nickname.
+    class Nickname < Masks::Credential
+      checks :actor
+
+      delegate :actor_id, :nickname, to: :actor, allow_nil: true
+
+      validates :nickname, :actor, presence: true
+      validate :validates_custom, if: :nickname
+
+      def lookup
+        return if actor
+
+        actor =
+          (
+            if nickname_param
+              config.find_actor(session, nickname: nickname_param)
+            end
+          )
+        actor ||=
+          if nickname_param
+            config
+              .build_actor(session, nickname: nickname_param)
+              .tap { |actor| actor.signup = true }
+          end
+
+        if actor&.new_record?
+          actor.nickname =
+            prefix_nickname(actor.nickname, default: actor.nickname)
+        end
+
+        actor
+      end
+
+      def maskup
+        approve! if valid?
+      end
+
+      private
+
+      def nickname_param
+        @nickname_param ||=
+          prefix_nickname(
+            session_params[:nickname],
+            default: session_params[:nickname]
+          )
+      end
+
+      def validates_custom
+        return unless nickname
+
+        validates_length :nickname, nickname_config&.length
+
+        return unless nickname_format
+
+        errors.add(:nickname, :format) unless nickname_format.match?(nickname)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Masks
+  module Credentials
+    # Checks :factor2 for a valid one-time code.
+    class OneTimeCode < Masks::Credential
+      include Factor2
+
+      private
+
+      def param
+        :one_time_code
+      end
+
+      def secret
+        actor&.totp_secret
+      end
+
+      def verify(code)
+        valid_code?(code, secret)
+      end
+
+      def valid_code?(code, secret)
+        if code && secret
+          actor.totp.verify(code)
+        else
+          false
+        end
+      rescue OpenSSL::HMACError
+        false
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Masks
+  module Credentials
+    # Checks :password for a match.
+    class Password < Masks::Credential
+      checks :password
+
+      def lookup
+        actor.password = password if actor&.new_record? && password
+
+        nil
+      end
+
+      def maskup
+        return unless password
+
+        actor&.authenticate(password) && actor&.valid? ? approve! : deny!
+      end
+
+      private
+
+      def password
+        session_params[:password]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Masks
+  module Credentials
+    # Checks for a :recovery on the session.
+    class Recovery < Masks::Credential
+      checks :recovery
+
+      def lookup
+        return if actor
+
+        @recovery =
+          if recovery_key
+            config.find_recovery(session, token: recovery_key)
+          else
+            config.build_recovery(
+              session,
+              nickname: nickname_param,
+              email: email_param,
+              phone: phone_param,
+              value: recovery_value
+            )
+          end
+
+        session.extras(recovery: @recovery)
+
+        @recovery&.actor
+      end
+
+      def maskup
+        return unless valid? && actor
+
+        if recovery_key
+          if recovery_password && @recovery&.valid?
+            @recovery.reset_password!(recovery_password)
+            approve!
+          end
+        elsif recovery_value && @recovery&.valid?
+          @recovery.notify!
+        end
+      end
+
+      private
+
+      def recovery_value
+        params.dig(:recover, :value) if writable?
+      end
+
+      def recovery_key
+        params[:token]
+      end
+
+      def recovery_password
+        params.dig(:recover, :password) if writable?
+      end
+
+      def phone_param
+        @phone_param ||= Phonelib.valid?(recovery_value) ? recovery_value : nil
+      end
+
+      def email_param
+        @email_param ||=
+          ValidateEmail.valid?(recovery_value) ? recovery_value : nil
+      end
+
+      def nickname_param
+        @nickname_param ||= prefix_nickname(recovery_value, default: nil)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Masks
+  module Credentials
+    # Checks for past :actor(s) on a session.
+    #
+    # This can be used in lieu of supplying identifying details like an
+    # email/nickname (usually provided they were supplied in the past).
+    class Session < Masks::Credential
+      checks :actor
+
+      def lookup
+        return if session_params[:actor_id]
+
+        actor_ids = session.data[:actors]&.keys || []
+        actor_id = session.data[:actor]
+        actors = (actor_ids.any? ? config.find_actors(session, actor_ids) : [])
+
+        # only lookup and return the current actor if
+        # it's not provided via a param (e.g. someone
+        # is trying to login)
+        actor =
+          if actor_id
+            actors.find do |a|
+              a.actor_id == actor_id &&
+                a.session_key == session.data[:actors][a.actor_id]
+            end
+          end
+
+        actor = Actors::Anonymous.new(session:) if optional? && !actors.present?
+
+        actor
+      end
+
+      def maskup
+        return approve! if optional? && actor&.anonymous?
+
+        actor_id = actor&.actor_id
+
+        return unless actor_id && session.data[:actors]&.fetch(actor_id, nil)
+        return unless session.data[:actor] == actor_id
+
+        if session.data.dig(:actors, actor_id) == actor.session_key
+          approve!
+        else
+          cleanup
+        end
+      end
+
+      def backup
+        return unless actor && passed?
+
+        session.data[:actors] ||= {}
+        session.data[:actors][actor.actor_id] = actor.session_key
+        session.data[:actor] = actor.actor_id
+      end
+
+      def cleanup
+        actor_id = actor&.actor_id || session.data[:actor]
+
+        session.data[:actor] = nil
+        session.data[:actors] ||= {}
+        session.data[:actors].delete(actor_id)
+      end
+    end
+  end
+end

data/app/models/masks/device.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Masks
+  # Represents a device, used for interacting with a session.
+  #
+  # Device detection is optionally added with the +Device+ credential,
+  # using the +device-detector+ gem.
+  #
+  # @see Masks::Credentials::Device Masks::Credentials::Device
+  class Device < ApplicationModel
+    attribute :session
+
+    def fingerprint
+      return unless detector.known?
+
+      input = [
+        detector.name,
+        detector.os_name,
+        detector.device_name,
+        detector.device_type
+      ].compact.join("-")
+
+      Digest::SHA512.hexdigest(input)
+    end
+
+    def detector
+      @detector ||= DeviceDetector.new(session.user_agent)
+    end
+  end
+end

data/app/models/masks/error.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Masks
+  module Error
+    # Base class for Masks errors
+    class Base < RuntimeError
+    end
+
+    # Thrown when a session is required but not provided
+    class InvalidSession < Base
+      def initialize
+        super("a session was expected, but none was provided")
+      end
+    end
+
+    # Thrown when invalid configuration is detected
+    class InvalidConfiguration < Base
+      def initialize(value)
+        super("cannot use '#{value}' for masks.json")
+      end
+    end
+
+    # Thrown when configuration is not found
+    class ConfigurationNotFound < Base
+      def initialize
+        super("cannot find masks.json")
+      end
+    end
+
+    # Thrown when Masks encounters an unauthorized session
+    class Unauthorized < Base
+      def initialize
+        super("unauthorized")
+      end
+    end
+
+    # Thrown when Masks cannot find a mask for a session
+    class UnknownMask < Base
+      def initialize(session)
+        super("could not determine mask for #{session}")
+      end
+    end
+
+    # Thrown when Masks cannot find an access class for the given name
+    class UnknownAccess < Base
+      def initialize(name)
+        super("could not determine access class for #{name}")
+      end
+    end
+  end
+end

data/app/models/masks/event.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Masks
+  # Publishes events using +ActiveSupport::Notifications+
+  class Event
+    class << self
+      def emit(name, **opts, &block)
+        ActiveSupport::Notifications.instrument("masks.#{name}", **opts) do
+          block.call
+        end
+      end
+    end
+  end
+end