masks 0.2.0

data/app/controllers/masks/one_time_code_controller.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Masks
+  # @visibility private
+  class OneTimeCodeController < ApplicationController
+    require_mask type: :session, only: :new
+
+    before_action only: %i[create destroy] do
+      require_sudo(one_time_code_path)
+    end
+
+    def new
+      respond_to { |format| format.html { render(:new) } }
+    end
+
+    def create
+      if secret_param && code_param
+        @actor.totp_secret = secret_param
+        @actor.totp_code = code_param
+        @actor.save if @actor.valid?
+
+        flash[:errors] = @actor.errors.full_messages unless @actor.valid?
+      end
+
+      respond_to { |format| format.html { redirect_to one_time_code_path } }
+    end
+
+    def destroy
+      @actor.totp_secret = nil
+      @actor.save if @actor.valid?
+
+      respond_to { |format| format.html { redirect_to one_time_code_path } }
+    end
+
+    private
+
+    def create_params
+      params.require(:one_time_code).permit(:code, :secret)
+    end
+
+    def code_param
+      create_params[:code]
+    end
+
+    def secret_param
+      create_params[:secret]
+    end
+  end
+end

data/app/controllers/masks/passwords_controller.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Masks
+  # @visibility private
+  class PasswordsController < ApplicationController
+    require_mask type: :session, only: :edit
+    require_access "actor.password", only: :update
+
+    before_action only: %i[update] do
+      require_sudo(password_path)
+    end
+
+    def edit
+      respond_to { |format| format.html { render(:edit) } }
+    end
+
+    def update
+      if password_param
+        current_access.change_password(password_param)
+
+        flash[:errors] = @actor.errors.full_messages unless @actor.valid?
+      end
+
+      respond_to { |format| format.html { redirect_to password_path } }
+    end
+
+    private
+
+    def password_param
+      params.dig(:password, :change)
+    end
+  end
+end

data/app/controllers/masks/recoveries_controller.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Masks
+  # @visibility private
+  class RecoveriesController < ApplicationController
+    before_action :redirect_if_logged_in, only: %i[new]
+
+    def new
+      respond_to { |format| format.html { render(:new) } }
+    end
+
+    def create
+      flash[:recovery] = true
+
+      respond_to { |format| format.html { redirect_to recover_path } }
+    end
+
+    def password
+      @recovery = masked_session.extra(:recovery)
+
+      respond_to { |format| format.html { render(:password) } }
+    end
+
+    def reset
+      @recovery = masked_session.extra(:recovery)
+
+      flash[:reset] = true if @recovery&.destroyed?
+      flash[:errors] = @recovery.errors.full_messages if @recovery &&
+        !@recovery&.valid?
+
+      redirect =
+        @recovery ? recover_password_path(token: @recovery.token) : recover_path
+
+      respond_to { |format| format.html { redirect_to redirect } }
+    end
+
+    private
+
+    def redirect_if_logged_in
+      redirect_to Masks.configuration.site_links[:root] if current_actor
+    end
+  end
+end

data/app/controllers/masks/sessions_controller.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Masks
+  # @visibility private
+  class SessionsController < ApplicationController
+    def new
+      respond_to do |format|
+        format.json { render json: resource_cls.new(masked_session) }
+        format.html { render(:new) }
+      end
+    end
+
+    def create
+      flash[
+        :errors
+      ] = masked_session.errors.full_messages unless request.format == :json
+
+      respond_to do |format|
+        format.json { render json: resource_cls.new(masked_session) }
+        format.html do
+          path =
+            (
+              if masked_session.passed?
+                masked_session.mask.pass ||
+                  Masks.configuration.site_links[:after_login]
+              else
+                masked_session.mask.fail ||
+                  Masks.configuration.site_links[:login]
+              end
+            )
+          redirect_to path
+        end
+      end
+    end
+
+    def destroy
+      masked_session.cleanup!
+
+      respond_to do |format|
+        format.json { render json: resource_cls.new(masked_session) }
+        format.html do
+          redirect_to Masks.configuration.site_links[:after_logout]
+        end
+      end
+    end
+
+    private
+
+    def resource_cls
+      Masks.configuration.model(:session_json)
+    end
+  end
+end

data/app/helpers/masks/application_helper.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Masks
+  # @visibility private
+  module ApplicationHelper
+    include Pagy::Frontend
+
+    def totp_svg(uri, **opts)
+      qrcode = RQRCode::QRCode.new(uri)
+      raw qrcode.as_svg(**opts)
+    end
+
+    def device_icon(device)
+      case device.device_type
+      when "desktop"
+        "computer"
+      when "smartphone", "feature phone"
+        "smartphone"
+      when "tablet", "phablet", "portable media player"
+        "tablet"
+      when "console"
+        "gamepad"
+      when "tv", "smart display"
+        "tv-2"
+      when "car browser"
+        "car"
+      when "camera"
+        "camera"
+      when "smart speaker", "wearable", "peripheral"
+        "bluetooth"
+      else
+        "question-circle"
+      end
+    end
+
+    def logged_in?
+      @session&.passed? && @session&.actor && !@session.actor.anonymous?
+    end
+
+    def factor2_required?
+      checks = @session.checks_for(:session)
+
+      return false unless checks
+
+      checks[:factor2] && !checks[:factor2]&.passed? &&
+        checks[:actor]&.passed? && checks[:password]&.passed?
+    end
+  end
+end

data/app/jobs/masks/application_job.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Masks
+  # @visibility private
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/jobs/masks/expire_actors_job.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Masks
+  # Job for deleting actors that have passed their expiration time.
+  #
+  # This job effectively delegates its work to the configured
+  # +Masks::Adapter+, specifically calling +#expire_actors+.
+  #
+  # @see Masks::Adapter Masks::Adapter
+  class ExpireActorsJob < ApplicationJob
+    def perform
+      Masks.configuration.expire_actors
+    end
+  end
+end

data/app/jobs/masks/expire_recoveries_job.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Masks
+  # Job for deleting recovies requests that passed their expiration time.
+  #
+  # This job delegates its work to the configured
+  # +Masks::Adapter+, specifically calling +#expire_recoveries+.
+  #
+  # @see Masks::Adapter Masks::Adapter
+  class ExpireRecoveriesJob < ApplicationJob
+    def perform
+      Masks.configuration.expire_recoveries
+    end
+  end
+end

data/app/mailers/masks/actor_mailer.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Masks
+  # @visibility private
+  class ActorMailer < ApplicationMailer
+    layout "masks/mailer"
+
+    def verify_email
+      @config = Masks.configuration
+      @email = params[:email]
+
+      mail(to: @email.email, subject: t(".subject"))
+    end
+
+    def recover_credentials
+      @config = Masks.configuration
+      @recovery = @config.find_recovery(nil, id: params[:recovery])
+
+      mail(to: @recovery.to, subject: t(".subject"))
+    end
+  end
+end

data/app/mailers/masks/application_mailer.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Masks
+  # @visibility private
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+
+    helper do
+      def logged_in?
+        false
+      end
+    end
+  end
+end

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

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Masks
+  # Concern to help with building access classes.
+  #
+  # Access classes must include this module, which will result in the class
+  # behaving like an +ActiveModel+ instance, with attributes, validations, and
+  # json serialization available by default.
+  #
+  # After including the module, classes must call +access+ to register the
+  # class and its canonical name.
+  #
+  # @example
+  #     class ExampleAccess
+  #       include Masks::Access
+  #
+  #       access 'example'
+  #
+  #       def say_hi
+  #         puts 'hello world!'
+  #       end
+  #     end
+  #
+  #     # Later, this class can be accessed with a valid session,
+  #     # provided there is a corresponding mask that allows it.
+  #     access = Masks.access('example', session)
+  #     access.say_hi if access
+  #
+  # @see Masks::Access::ClassMethods
+  module Access
+    extend ActiveSupport::Concern
+
+    class << self
+      # @visibility private
+      def classes
+        @classes ||= {}
+      end
+
+      # @visibility private
+      def register(name, **defaults)
+        classes[name.to_s] = defaults
+      end
+
+      # @visibility private
+      def defaults(name)
+        classes.fetch(name.to_s, nil)
+      end
+    end
+
+    included do
+      attr_accessor :session
+
+      def actor
+        raise Masks::Error::InvalidSession unless session
+
+        session.scoped || session.actor
+      end
+
+      delegate :configuration,
+               :roles,
+               :role?,
+               :role_records,
+               :scopes,
+               :scope?,
+               :params,
+               to: :session
+
+      delegate :access_config, to: :class
+    end
+
+    # Class methods for classes that include +Masks::Access+.
+    module ClassMethods
+      # Overrides `new` to ensure classes are constructed with proper access.
+      # @visibility private
+      def new(*args, **opts)
+        original =
+          if args[0].is_a?(Masks::Session)
+            args.delete_at(0)
+          elsif opts[:session]
+            opts.delete(:session)
+          else
+            raise Masks::Error::InvalidSession
+          end
+
+        model = original.config.model(:access)
+        session = model.new(name: access_name, original:)
+        session.mask!
+
+        raise Masks::Error::Unauthorized unless session.passed?
+
+        instance = super(*args, **opts)
+        instance.session = session
+        instance
+      end
+
+      # Returns the canonical access name for the class.
+      #
+      # @return [String]
+      def access_name
+        @access_name
+      end
+
+      # Registers the class by the supplied name.
+      #
+      # Any +opts+ provided will be used as defaults for instances,
+      # in addition to the data supplied in the app's configuration.
+      #
+      # This can be called multiple times. If names are the same, +opts+
+      # will be deep merged together. Different names can be supplied as
+      # well.
+      #
+      # @param [String] name
+      # @param [Hash] opts
+      # @return [nil]
+      def access(name, **opts)
+        @access_name = name
+
+        Masks::Access.register(access_name, **opts.merge(cls: self))
+
+        nil
+      end
+
+      # Returns the configuration for the class.
+      #
+      # This is a combination of data provided to +access+ along with whatever
+      # is specifed in the configuration object for the access class.
+      #
+      # @return [String]
+      def access_config
+        Masks.configuration.access(access_name)
+      end
+
+      # Builds a new access class, given a variety of arguments.
+      #
+      # @overload  build(request)
+      #   @param [ActionDispatch::Request] request
+      # @overload  build(controller)
+      #   @param [ActionController::Metal] controller
+      # @overload  build(session)
+      #   @param [Masks::Session] session
+      # @overload  build(actor)
+      #   @param [Masks::Actor] actor
+      # @overload  build(**attrs)
+      #   @param [ActionController::Metal] controller
+      # @return [Masks::Access]
+      def build(arg1 = nil, **args)
+        case arg1
+        when ActionDispatch::Request
+          new(session: Masks::Sessions::Request.new(session: arg1))
+        when ActionController::Metal
+          new(session: arg1.send(:masked_session))
+        when Masks::Session
+          new(session: arg1, **args)
+        when Masks::Actor
+          new(session: Masks::Sessions::Actor.new(arg1, **opts))
+        when nil
+          new(**opts)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Masks
+  # An interface that all masked actors should adhere to.
+  #
+  # @see Masks::Scoped Masks::Scoped
+  # @see Masks::Rails::Actor Masks::Rails::Actor
+  # @see Actors::Anonymous
+  # @see Actors::System
+  module Actor
+    include Scoped
+
+    # A unique identifier for the actor.
+    #
+    # This value is used for internal references to actors, e.g. when they are
+    # stored in the rails session.
+    #
+    # @return [String]
+    def actor_id
+      nickname
+    end
+
+    # A session identifier for the actor.
+    #
+    # This value is used for internal references to actors, e.g. when they are
+    # stored in the rails session.
+    #
+    # @return [String]
+    def session_key
+      Digest::MD5.hexdigest(
+        [Masks.configuration.version, version, actor_id].join("-")
+      )
+    end
+
+    # An internal version counter for the actor.
+    #
+    # Session keys use this value so they automatically expire when it changes.
+    #
+    # @return [String]
+    def version
+      raise NotImplementedError unless defined?(super)
+
+      super
+    end
+
+    # A nickname for the actor.
+    #
+    # @return [String]
+    def nickname
+      raise NotImplementedError unless defined?(super)
+
+      super
+    end
+
+    # Sets a password for the actor.
+    #
+    # @param [String] password
+    # @return [String]
+    def password=(password)
+      raise NotImplementedError unless defined?(super)
+
+      super
+    end
+
+    # Sets the current session on the actor.
+    #
+    # @param [Masks::Session] session
+    # @return [String]
+    def session=(session)
+      raise NotImplementedError unless defined?(super)
+
+      super
+    end
+
+    # Validates the given password.
+    #
+    # @param [String] password
+    # @return [Boolean]
+    def authenticate(password)
+      raise NotImplementedError unless defined?(super)
+
+      super
+    end
+
+    # Returns a list of scopes granted to the actor.
+    #
+    # @return [Array<String>] An array of scopes (as strings)
+    def scopes
+      raise NotImplementedError
+    end
+
+    # A callback that is invoked for masked sessions involving this actor.
+    #
+    # This method is only called when everything else—credentials, checks,
+    # and other mask rules—have passed. If this method returns a truthy value
+    # the session will pass, otherwise it will fail.
+    #
+    # This is a great place to add final checks, validations, and onboarding
+    # data to the actor before saving it.
+    #
+    # @return [Boolean]
+    def mask!
+      raise NotImplementedError
+    end
+
+    # Whether or not the actor requires a second layer of authentication.
+    #
+    # @return [Boolean]
+    def factor2?
+      false
+    end
+
+    # Whether or not the actor is anonymous, e.g. instantiated but un-identified.
+    #
+    # @return [Boolean]
+    def anonymous?
+      false
+    end
+
+    # Whether or not to save the results of any masked sessions involving this actor.
+    #
+    # Typically this is best controlled at the mask level, but there are some cases
+    # where it is useful to control at the actor-level. For example, the implementation
+    # for anonymous actors always returns `true` for this method, so that anonymous
+    # actors never end up in the rails session or other databases.
+    #
+    # @return [Boolean]
+    def backup?
+      !anonymous?
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Masks
+  # An interface that all configuration adapters should adhere to.
+  #
+  # @see Masks::Adapters::ActiveRecord
+  module Adapter
+    # Creates a new adapter.
+    #
+    # @param [Masks::Configuration] config
+    # @return [Masks::Adapter]
+    def initialize(config)
+      @config = config
+    end
+
+    # Returns an actor given the passed options, which may
+    # contain a nickname and/or an email.
+    #
+    # @param [Masks::Session] session
+    # @param [Hash] opts
+    # @return [Masks::Actor] or nil if not found
+    def find_actor(session, **opts)
+      raise NotImplementedError
+    end
+
+    # Returns a list of actors matching the passed actor_ids.
+    #
+    # @param [Masks::Session] session
+    # @param [Array] actor_ids
+    # @return [Array<Masks::Actor>]
+    def find_actors(session, actor_ids)
+      raise NotImplementedError
+    end
+
+    # Expires any outdated or invalid actors.
+    #
+    # @return
+    def expire_actors
+      raise NotImplementedError
+    end
+
+    # Builds an actor from the passed options, which may contain
+    # a nickname or email. Additional attributes, like a password,
+    # will not be supplied.
+    #
+    # @param [Masks::Session] session
+    # @param [Hash] opts
+    # @return [Masks::Actor]
+    def build_actor(session, **opts)
+      raise NotImplementedError
+    end
+
+    # @visibility private
+    def find_recovery(session, **opts)
+      raise NotImplementedError
+    end
+
+    # @visibility private
+    def build_recovery(session, **opts)
+      raise NotImplementedError
+    end
+
+    # @visibility private
+    def expire_recoveries
+      raise NotImplementedError
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Masks
+  # An interface that all roles should adhere to.
+  #
+  # @see Masks::Rails::Role Masks::Rails::Role
+  module Role
+  end
+end