masks 0.2.0

data/lib/masks/configuration.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require "set"
+require "recursive-open-struct"
+
+module Masks
+  # Container for masks configuration data.
+  class Configuration
+    include ActiveModel::Model
+    include ActiveModel::Validations
+    include ActiveModel::Attributes
+    include ActiveModel::Serializers::JSON
+
+    attribute :data
+    attribute :name
+    attribute :adapter, default: "Masks::Adapters::ActiveRecord"
+    attribute :theme
+    attribute :site_name
+    attribute :site_url
+    attribute :site_links
+    attribute :site_logo
+    attribute :lifetimes
+    attribute :masks
+    attribute :models
+    attribute :version
+
+    # Returns all configuration data as +RecursiveOpenStruct+.
+    #
+    # @return RecursiveOpenStruct
+    def dat
+      RecursiveOpenStruct.new(data)
+    end
+
+    # Returns a string to use as the "issuer" for various secrets—TOTP, JWT, etc.
+    # @return [String]
+    def issuer
+      data.fetch(:name, "masks").parameterize
+    end
+
+    # Returns a site theme to use on the frontend.
+    # @return [String]
+    def theme
+      super || data.fetch(:theme, "dark")
+    end
+
+    # Returns the site logo, used for visual identification of the site.
+    # @return [String]
+    def site_logo
+      super || data.fetch(:logo, nil)
+    end
+
+    # Returns the site name, used for referring to the site (e.g. in the logo).
+    # @return [String]
+    def site_name
+      super || data.fetch(:name, "masks")
+    end
+
+    # Returns the site title, used primarily in meta tags.
+    # @return [String]
+    def site_title
+      super || data.fetch(:title, "")
+    end
+
+    # Returns the canonical url for the site.
+    # @return [String]
+    def site_url
+      super || data.fetch(:url, nil)
+    end
+
+    # A hash of links—urls to various places on the frontend.
+    #
+    # These default to generated rails routes, but can be overridden
+    # where necessary.
+    #
+    # @return [Hash]
+    def site_links
+      {
+        root: rails_url.try(:root_path) || "/",
+        recover: rails_url.recover_path,
+        login: rails_url.session_path,
+        after_login: rails_url.session_path,
+        after_logout: rails_url.session_path
+      }.merge(super || data.fetch(:links, {}))
+    end
+
+    # Returns the current global session key.
+    # @return [String]
+    def version
+      super || "v1"
+    end
+
+    # A hash of expiration times for various resources.
+    #
+    # These values are used to override expiration times for things like
+    # password reset emails and other time-based authentication methods.
+    #
+    # @return [Hash]
+    def lifetimes
+      (super || dat.lifetimes&.to_h || {}).transform_values do |seconds|
+        seconds.to_i.seconds
+      end
+    end
+
+    # A hash of default models the app relies on.
+    #
+    # The following keys are available:
+    #
+    #   actor: +Masks::Rails::Actor+
+    #   role: +Masks::Rails::Role+
+    #   scope: +Masks::Rails::Scope+
+    #   email: +Masks::Rails::Email+
+    #   recovery: +Masks::Rails::Recovery+
+    #
+    # This makes it easy to provide a substitute for key models
+    # while still relying on the base active record implementation.
+    #
+    # @return [Hash{Symbol => String}]
+    def models
+      {
+        actor: "Masks::Rails::Actor",
+        scope: "Masks::Rails::Scope",
+        role: "Masks::Rails::Role",
+        email: "Masks::Rails::Email",
+        recovery: "Masks::Rails::Recovery",
+        device: "Masks::Rails::Device",
+        key: "Masks::Rails::Key",
+        session_json: "Masks::SessionResource",
+        request: "Masks::Sessions::Request",
+        inline: "Masks::Sessions::Inline",
+        access: "Masks::Sessions::Access"
+      }.merge(super || data.fetch(:models, {}))
+    end
+
+    # Returns a model +Class+.
+    #
+    # @return [Class]
+    def model(name)
+      models[name]&.constantize
+    end
+
+    # Returns configuration data for a given mask type.
+    #
+    # @param [String] type
+    # @return [Hash]
+    def mask(type)
+      config = data.dig(:types, type.to_sym)
+      raise Masks::Error::InvalidConfiguration, type unless config
+
+      config
+    end
+
+    # Returns all configured masks.
+    #
+    # @return [Array<Masks::Mask>]
+    def masks
+      @masks ||=
+        begin
+          masks = super || data.fetch(:masks, [])
+          masks.map do |opts|
+            case opts
+            when Masks::Mask
+              opts
+            when Hash
+              Masks::Mask.new(opts.merge(config: self))
+            end
+          end
+        end
+    end
+
+    # Returns configuration data for the given access name.
+    # @param [String] name
+    # @return [Hash]
+    def access(name)
+      defaults = Masks::Access.defaults(name)
+      raise Masks::Error::UnknownAccess, name unless defaults
+
+      defaults.deep_merge(access_types&.fetch(name, {}))
+    end
+
+    # Returns configuration data for all access types.
+    #
+    # This does not include defaults created with +Masks::Access.access+.
+    #
+    # @return [Hash]
+    def access_types
+      data
+        .fetch(:access, {})
+        .to_h do |name, opts|
+          [name, opts.merge(name:, cls: opts[:cls]&.constantize)]
+        end
+    end
+
+    # Setter for whether or not sigups are allowed.
+    #
+    # @param [Boolean] value
+    def signups=(value)
+      data[:signups] = value
+    end
+
+    # Whether or not sigups are allowed.
+    #
+    # @return [Boolean]
+    def signups?
+      data[:signups]
+    end
+
+    delegate :find_key,
+             :find_actor,
+             :find_actors,
+             :build_actor,
+             :find_device,
+             :find_recovery,
+             :build_recovery,
+             :expire_actors,
+             :expire_recoveries,
+             to: :adapt
+
+    private
+
+    def rails_url
+      Masks::Engine.routes.url_helpers
+    end
+
+    def adapt
+      @adapt =
+        case adapter
+        when String
+          adapter.constantize.new(self)
+        when Class
+          adapter.new(self)
+        else
+          raise Masks::Error::InvalidConfiguration, adapter
+        end
+    end
+  end
+end

data/lib/masks/engine.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "middleware"
+module Masks
+  # The Rails engine/railtie for Masks.
+  #
+  # Adds two initializers:
+  #
+  # - masks.assets.precompile - ensures masks assets are precompiled and added to the Rails asset pipeline
+  # - masks.middleware - appends +Masks::Middleware+ to the middleware chain
+  #
+  class Engine < ::Rails::Engine
+    isolate_namespace Masks
+
+    initializer "masks.assets.precompile" do |app|
+      app.config.assets.precompile += %w[masks_manifest.js] if app.config.try(
+        :assets
+      )
+    end
+
+    initializer "masks.middleware" do |app|
+      app.config.app_middleware.use Masks::Middleware
+    end
+  end
+end

data/lib/masks/middleware.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Masks
+  # Integrate masks with Rails, via middleware.
+  #
+  # This middleware creates a new session for every request using
+  # +Masks.request+. If the session is +passed?+ the middleware
+  # chain is allowed to continue.
+  #
+  # The middleware uses the +fail+ value on the session's mask to
+  # determine what to do otherwise. If +false+ the chain is allowed
+  # to continue regardless of pass/fail status. It will also accept
+  # a URI or path for redirects, an HTTP status code, or a controller
+  # action in the form of +ControllerClass#action_name+.
+  #
+  # The session is stored in the rack environment under the name
+  # +Mask::Middleware::SESSION_KEY+, which is how it is made available to
+  # controllers in +Masks::Controller#masked_session+.
+  #
+  # @see Masks.request Masks.request
+  # @see Masks::Session Masks::Session
+  # @see Masks::Controller Masks::Controller
+  class Middleware
+    SESSION_KEY = "masks.session"
+
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      request = ActionDispatch::Request.new(env)
+      session = Masks.request(request)
+
+      ::Rails.logger.info(
+        [
+          "Mask #{session.passed? ? "allowed" : "blocked"}",
+          "by type=#{session.mask.type}",
+          session.mask.name ? "name=#{session.mask.name}" : ""
+        ].join(" ")
+      )
+
+      env[SESSION_KEY] = session
+      app = @app
+      app = (session.passed? ? app : error_app(session, app))
+
+      app.call(env)
+    end
+
+    private
+
+    def error_app(session, app)
+      value = session.mask.fail
+      case value
+      when false
+        app
+      when /.+\#.+/
+        controller, action = value.split("#")
+        controller.constantize.action(action)
+      when %r{/.*}, %r{https?://.+}
+        Masks::ErrorController.action(:redirect)
+      when /\d+/
+        Masks::ErrorController.action("render_#{value}")
+      when /\w+/
+        Masks::ErrorController.action(value)
+      else
+        Masks::ErrorController.action(:render_unauthorized)
+      end
+    end
+  end
+end

data/lib/masks/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Masks
+  VERSION = Gem::Version.new("0.2.0")
+end

data/lib/masks.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "masks/version"
+require "masks/engine"
+require "masks/configuration"
+require "fuzzyurl"
+require "valid_email"
+require "phonelib"
+require "rqrcode"
+require "rotp"
+require "alba"
+require "pagy"
+require "device_detector"
+require "active_model"
+
+# Top-level module for masks.
+#
+# Includes helper methods for managing configuration and building
+# sessions, access, etc.
+module Masks
+  # @visibility private
+  ANON = :anon
+
+  class << self
+    # Returns an access instance based on the type & session passed.
+    #
+    # @param [Symbol|String] name
+    # @param [Masks::Session] session
+    # @return [Masks::Access]
+    # @raise [Masks::Error::Unauthorized] if access cannot be granted to the session passed
+    # @raise [Masks::UnknownAccess] if the access type cannot be found
+    def access(name, session, **_opts)
+      configuration.access(name).fetch(:cls).build(session)
+    end
+
+    # Returns a masked session based on the request passed.
+    #
+    # @param [ActionDispatch::Request] request
+    # @return [Masks::Sessions::Request] session
+    def request(request)
+      model = configuration.model(:request)
+      session = model.new(config: configuration, request:)
+      session.mask!
+      session
+    end
+
+    # Returns a masked session based on the params and data passed.
+    #
+    # This method is useful for creating masks directly, outside of a
+    # specific context like a web request.
+    #
+    # @param params [Hash]
+    # @param data [Hash]
+    # @yield [Masks::Sessions::Inline]
+    # @return [Masks::Sessions::Inline] session
+    def mask(name, params: {}, **data)
+      model = configuration.model(:inline)
+      session = model.new(name:, config: configuration, params:, data:)
+      session.mask!
+      yield session if session.passed? && block_given?
+      session
+    end
+
+    # Yields the global masks configuration object.
+    # @return [Masks::Configuration]
+    # @yield [Masks::Configuration]
+    def configure
+      yield configuration
+    end
+
+    # Returns the global configuration object for masks.
+    # @return [Masks::Configuration]
+    def configuration
+      @configuration ||= Masks::Configuration.new(data: config.dup)
+    end
+
+    # @visibility private
+    def event(name, **opts, &block)
+      ActiveSupport::Notifications.instrument("masks.#{name}", **opts) do
+        block.call
+      end
+    end
+
+    # @visibility private
+    def config
+      @config ||=
+        begin
+          config = load_config(config_path)
+
+          defaults =
+            if config[:extend]
+              # extend a "masks.json" from a gem
+              load_config(gem_path(config[:extend]))
+            else
+              {}
+            end
+
+          config = defaults.except(:masks).deep_merge(config)
+          config[:masks] = [*config[:masks], *defaults[:masks]] if defaults[
+            :masks
+          ]
+          config
+        end
+    end
+
+    # @visibility private
+    def with_config(path_or_config)
+      previous_config = @config
+      previous_path = @config_path
+
+      case path_or_config
+      when String
+        @config_path = Pathname.new(path_or_config)
+      when Pathname
+        @config_path = path_or_config
+      when Hash
+        @config_path = :custom
+        @config = path_or_config
+      else
+        raise Error::InvalidConfiguration, path_or_config
+      end
+
+      result = yield
+    ensure
+      @config = previous_config
+      @config_path = previous_path
+
+      result
+    end
+
+    # @visibility private
+    def config_path
+      path =
+        [
+          @config_path,
+          ENV["MASKS_DIR"] ? Pathname.new(ENV["MASKS_DIR"]) : nil,
+          Pathname.new(Dir.pwd),
+          defined?(ENGINE_ROOT) ? Pathname.new(ENGINE_ROOT) : nil
+        ].find do |p|
+          p.is_a?(Symbol) || (p && File.exist?(p.join("masks.json")))
+        end
+
+      raise Error::ConfigurationNotFound unless path
+
+      path
+    end
+
+    # @visibility private
+    def config_path=(value)
+      @config_path =
+        case value
+        when String
+          Pathname.new(value)
+        when Pathname
+          value
+        else
+          raise Error::InvalidConfiguration, value
+        end
+    end
+
+    # @visibility private
+    def reset!
+      @configuration = @config = @config_path = nil
+    end
+
+    def load_config(dir)
+      JSON.parse(File.read(dir.join("masks.json")), symbolize_names: true)
+    end
+
+    def gem_path(gem_name)
+      begin
+        # Try to require the gem
+        require gem_name
+      rescue LoadError
+        return nil
+      end
+
+      # Get the gem specification
+      spec = Gem::Specification.find_by_name(gem_name)
+      Pathname.new(spec.gem_dir) if spec
+    end
+  end
+end

data/lib/tasks/masks_tasks.rake

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+def cli_access(access_name, **opts)
+  access = nil
+  actor = opts.delete(:as) || ENV["ACTOR"] || Masks::ANON
+
+  Masks.mask("cli", as: actor, **opts) do |session|
+    access = session.access(access_name)
+  end
+
+  access
+end
+
+namespace :masks do
+  task boot: :environment do
+    # required to ensure access classes (and others) are registered properly
+    Rails.application.eager_load!
+  end
+
+  task :signup, %i[nickname password] => :boot do |_task, args|
+    access = cli_access("actor.signup", args:)
+    signup = access.signup(**args) if access
+
+    if !access
+      puts "could not find actor..."
+    elsif signup.invalid?
+      puts "failed to signup '#{signup.nickname}'"
+      puts "error: #{signup.errors.full_messages.join(", ")}"
+    else
+      puts "created '#{signup.nickname}'!"
+    end
+  end
+
+  task :assign_scopes, %i[actor scopes] => :boot do |_task, args|
+    if !args[:actor] || !args[:scopes]
+      puts "specify an actor and scopes, e.g. masks:assign_scopes[@foo,scope1;scope2;scope3]"
+      exit 1
+    end
+
+    access = cli_access("actor.scopes", as: args[:actor])
+    access&.assign_scopes(args[:scopes].split(";"))
+
+    if !access
+      puts "could not find actor..."
+    elsif access.actor.invalid?
+      puts "failed to assign scopes to '#{access.actor.nickname}'"
+      puts "error: #{access.actor.errors.full_messages.join(", ")}"
+    else
+      puts "assigned scopes to '#{access.actor.nickname}'"
+    end
+  end
+
+  task :change_password, %i[actor password] => :boot do |_task, args|
+    if !args[:actor] || !args[:password]
+      puts "specify an actor and password, e.g. masks:change_password[@foo,password]"
+      exit 1
+    end
+
+    access = cli_access("actor.password", as: args[:actor])
+    access&.change_password(args[:password])
+
+    if !access
+      puts "could not find actor..."
+    elsif access.actor.invalid?
+      puts "failed to change password for '#{access.actor.nickname}'"
+      puts "error: #{access.actor.errors.full_messages.join(", ")}"
+    else
+      puts "changed password for '#{access.actor.nickname}'"
+    end
+  end
+end