masks 0.4.0 → 0.5.0

data/app/mailers/masks/application_mailer.rb

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

@@ -1,162 +0,0 @@
-# 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.actor
-      end
-
-      delegate :config,
-               :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

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

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

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

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

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

@@ -1,21 +0,0 @@
-# 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, **opts)
-        actor = opts[:actor] || self.actor
-        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

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

@@ -1,21 +0,0 @@
-# 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 = config.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

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

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

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

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

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