rails-auth 1.3.0 → 2.0.1

data/lib/rails/auth.rb

@@ -3,5 +3,8 @@
 # Pull in core library components that work with any Rack application
 require "rails/auth/rack"
 
+# Rails configuration builder
+require "rails/auth/config_builder"
+
 # Rails controller method support
 require "rails/auth/controller_methods"

data/lib/rails/auth/acl.rb

@@ -1,4 +1,4 @@
-# Pull in default predicate matchers
+# Pull in default matchers
 require "rails/auth/acl/matchers/allow_all"
 
 module Rails
@@ -7,7 +7,7 @@ module Rails
     class ACL
       attr_reader :resources
 
-      # Predicate matchers available by default in ACLs
+      # Matchers available by default in ACLs
       DEFAULT_MATCHERS = {
         allow_all: Matchers::AllowAll
       }.freeze
@@ -21,7 +21,7 @@ module Rails
       end
 
       # @param [Array<Hash>] :acl Access Control List configuration
-      # @param [Hash] :matchers predicate matchers for use with this ACL
+      # @param [Hash] :matchers authorizers use with this ACL
       #
       def initialize(acl, matchers: {})
         raise TypeError, "expected Array for acl, got #{acl.class}" unless acl.is_a?(Array)
@@ -34,32 +34,37 @@ module Rails
           resources = entry["resources"]
           raise ParseError, "no 'resources' key present in entry: #{entry.inspect}" unless resources
 
-          predicates = parse_predicates(entry, matchers.merge(DEFAULT_MATCHERS))
+          matcher_instances = parse_matchers(entry, matchers.merge(DEFAULT_MATCHERS))
 
           resources.each do |resource|
-            @resources << Resource.new(resource, predicates).freeze
+            @resources << Resource.new(resource, matcher_instances).freeze
           end
         end
 
         @resources.freeze
       end
 
-      # Match the Rack environment against the ACL, checking all predicates
+      # Match the Rack environment against the ACL, checking all matchers
       #
       # @param [Hash] :env Rack environment
       #
-      # @return [Boolean] is the request authorized?
+      # @return [String, nil] name of the first matching matcher, or nil if unauthorized
       #
       def match(env)
-        @resources.any? { |resource| resource.match(env) }
+        @resources.each do |resource|
+          matcher_name = resource.match(env)
+          return matcher_name if matcher_name
+        end
+
+        nil
       end
 
-      # Find all resources that match the ACL. Predicates are *NOT* checked,
+      # Find all resources that match the ACL. Matchers are *NOT* checked,
       # instead only the initial checks for the "resources" section of the ACL
-      # are performed. Use the `#match` method to validate predicates.
+      # are performed. Use the `#match` method to validate matchers.
       #
       # This method is intended for debugging AuthZ failures. It can find all
-      # resources that match the given request so the corresponding predicates
+      # resources that match the given request so the corresponding matchers
       # can be introspected.
       #
       # @param [Hash] :env Rack environment
@@ -72,8 +77,8 @@ module Rails
 
       private
 
-      def parse_predicates(entry, matchers)
-        predicates = {}
+      def parse_matchers(entry, matchers)
+        matcher_instances = {}
 
         entry.each do |name, options|
           next if name == "resources"
@@ -82,10 +87,10 @@ module Rails
           raise ArgumentError, "no matcher for #{name}" unless matcher_class
           raise TypeError, "expected Class for #{name}" unless matcher_class.is_a?(Class)
 
-          predicates[name.freeze] = matcher_class.new(options.freeze).freeze
+          matcher_instances[name.freeze] = matcher_class.new(options.freeze).freeze
         end
 
-        predicates.freeze
+        matcher_instances.freeze
       end
     end
   end

data/lib/rails/auth/acl/matchers/allow_all.rb

@@ -1,7 +1,7 @@
 module Rails
   module Auth
     class ACL
-      # Built-in predicate matchers
+      # Built-in matchers
       module Matchers
         # Allows unauthenticated clients to access to a given resource
         class AllowAll

data/lib/rails/auth/acl/middleware.rb

@@ -22,7 +22,12 @@ module Rails
         end
 
         def call(env)
-          raise NotAuthorizedError, "unauthorized request" unless Rails::Auth.authorized?(env) || @acl.match(env)
+          unless Rails::Auth.authorized?(env)
+            matcher_name = @acl.match(env)
+            raise NotAuthorizedError, "unauthorized request" unless matcher_name
+            Rails::Auth.set_allowed_by(env, "matcher:#{matcher_name}")
+          end
+
           @app.call(env)
         end
       end

data/lib/rails/auth/acl/resource.rb

@@ -5,7 +5,7 @@ module Rails
     class ACL
       # Rules for a particular route
       class Resource
-        attr_reader :http_methods, :path, :host, :predicates
+        attr_reader :http_methods, :path, :host, :matchers
 
         # Valid HTTP methods
         HTTP_METHODS = %w(GET HEAD PUT POST DELETE OPTIONS PATCH LINK UNLINK).freeze
@@ -15,11 +15,11 @@ module Rails
 
         # @option :options [String] :method HTTP method allowed ("ALL" for all methods)
         # @option :options [String] :path path to the resource (regex syntax allowed)
-        # @param [Hash] :predicates matchers for this resource
+        # @param [Hash] :matchers which matchers are used for this resource
         #
-        def initialize(options, predicates)
-          raise TypeError, "expected Hash for options"    unless options.is_a?(Hash)
-          raise TypeError, "expected Hash for predicates" unless predicates.is_a?(Hash)
+        def initialize(options, matchers)
+          raise TypeError, "expected Hash for options"  unless options.is_a?(Hash)
+          raise TypeError, "expected Hash for matchers" unless matchers.is_a?(Hash)
 
           unless (extra_keys = options.keys - VALID_OPTIONS).empty?
             raise ParseError, "unrecognized key in ACL resource: #{extra_keys.first}"
@@ -30,7 +30,7 @@ module Rails
 
           @http_methods = extract_methods(methods)
           @path         = /\A#{path}\z/
-          @predicates   = predicates.freeze
+          @matchers     = matchers.freeze
 
           # Unlike method and path, host is optional
           host = options["host"]
@@ -38,19 +38,20 @@ module Rails
         end
 
         # Match this resource against the given Rack environment, checking all
-        # predicates to ensure at least one of them matches
+        # matchers to ensure at least one of them matches
         #
         # @param [Hash] :env Rack environment
         #
-        # @return [Boolean] resource and predicates match the given request
+        # @return [String, nil] name of the matcher which matched, or nil if none matched
         #
         def match(env)
-          return false unless match!(env)
-          @predicates.any? { |_name, predicate| predicate.match(env) }
+          return nil unless match!(env)
+          name, = @matchers.find { |_name, matcher| matcher.match(env) }
+          name
         end
 
         # Match *only* the request method/path/host against the given Rack environment.
-        # Predicates are NOT checked.
+        # matchers are NOT checked.
         #
         # @param [Hash] :env Rack environment
         #

data/lib/rails/auth/config_builder.rb

@@ -0,0 +1,83 @@
+module Rails
+  module Auth
+    # Configures Rails::Auth middleware for use in a Rails application
+    module ConfigBuilder
+      extend self
+
+      # Application-level configuration (i.e. config/application.rb)
+      def application(config, acl_file: Rails.root.join("config/acl.yml"), matchers: {})
+        config.x.rails_auth.acl = Rails::Auth::ACL.from_yaml(
+          File.read(acl_file.to_s),
+          matchers: matchers
+        )
+
+        config.middleware.use Rails::Auth::ACL::Middleware, acl: config.x.acl
+      end
+
+      # Development configuration (i.e. config/environments/development.rb)
+      def development(config, development_credentials: {}, error_page: :debug)
+        error_page_middleware(config, error_page)
+        credential_injector_middleware(config, development_credentials) unless development_credentials.empty?
+      end
+
+      # Test configuration (i.e. config/environments/test.rb)
+      def test(config)
+        # Simulated credentials to be injected with InjectorMiddleware
+        credential_injector_middleware(config, config.x.rails_auth.test_credentials ||= {})
+      end
+
+      def production(
+        config,
+        cert_filters: nil,
+        require_cert: false,
+        ca_file: nil,
+        error_page: Rails.root.join("public/403.html"),
+        monitor: nil
+      )
+        raise ArgumentError, "no cert_filters given but require_cert is true" if require_cert && !cert_filters
+        raise ArgumentError, "no ca_file given but cert_filters were set"     if cert_filters && !ca_file
+
+        error_page_middleware(config, error_page)
+
+        if cert_filters
+          config.middleware.insert_before Rails::Auth::ACL::Middleware,
+                                          Rails::Auth::X509::Middleware,
+                                          require_cert: require_cert,
+                                          cert_filters: cert_filters,
+                                          ca_file:      ca_file,
+                                          logger:       Rails.logger
+        end
+
+        return unless monitor
+        config.middleware.insert_before Rails::Auth::ACL::Middleware,
+                                        Rails::Auth::Monitor::Middleware,
+                                        monitor
+      end
+
+      private
+
+      # Adds error page middleware to the chain
+      def error_page_middleware(config, error_page)
+        case error_page
+        when :debug
+          config.middleware.insert_before Rails::Auth::ACL::Middleware,
+                                          Rails::Auth::ErrorPage::DebugMiddleware,
+                                          acl: config.x.rails_auth.acl
+        when Pathname, String
+          config.middleware.insert_before Rails::Auth::ACL::Middleware,
+                                          Rails::Auth::ErrorPage::Middleware,
+                                          page_body: Pathname(error_page).read
+        when FalseClass, NilClass
+        else raise TypeError, "bad error page mode: #{mode.inspect}"
+        end
+      end
+
+      # Adds Rails::Auth::Credentials::InjectorMiddleware to the chain with the given credentials
+      def credential_injector_middleware(config, credentials)
+        config.middleware.insert_before Rails::Auth::ACL::Middleware,
+                                        Rails::Auth::Credentials::InjectorMiddleware,
+                                        credentials
+      end
+    end
+  end
+end

data/lib/rails/auth/credentials.rb

@@ -1,45 +1,30 @@
 # frozen_string_literal: true
 
+require "forwardable"
+
 module Rails
   # Modular resource-based authentication and authorization for Rails/Rack
   module Auth
-    # Rack environment key for all rails-auth credentials
-    CREDENTIALS_ENV_KEY = "rails-auth.credentials".freeze
-
-    # Functionality for storing credentials in the Rack environment
-    module Credentials
-      # Obtain credentials from a Rack environment
-      #
-      # @param [Hash] :env Rack environment
-      #
-      def credentials(env)
-        env.fetch(CREDENTIALS_ENV_KEY, {})
-      end
-
-      # Add a credential to the Rack environment
-      #
-      # @param [Hash] :env Rack environment
-      # @param [String] :type credential type to add to the environment
-      # @param [Object] :credential object to add to the environment
-      #
-      def add_credential(env, type, credential)
-        credentials = env[CREDENTIALS_ENV_KEY] ||= {}
+    # Stores a set of credentials
+    class Credentials
+      extend Forwardable
 
-        # Adding a credential is idempotent, so attempting to reregister
-        # the same credential should be harmless
-        return env if credentials.key?(type) && credentials[type] == credential
+      def_delegators :@credentials, :[], :fetch, :empty?, :key?, :to_hash
 
-        # raise if we already have a cred, but it didn't short-circuit as
-        # being == to the one supplied
-        raise ArgumentError, "credential #{type} already added to request" if credentials.key?(type)
+      def self.from_rack_env(env)
+        new(env.fetch(Rails::Auth::Env::CREDENTIALS_ENV_KEY, {}))
+      end
 
-        credentials[type] = credential
+      def initialize(credentials = {})
+        raise TypeError, "expected Hash, got #{credentials.class}" unless credentials.is_a?(Hash)
+        @credentials = credentials
+      end
 
-        env
+      def []=(type, value)
+        raise TypeError, "expected String for type, got #{type.class}" unless type.is_a?(String)
+        raise AlreadyAuthorizedError, "credential '#{type}' has already been set" if @credentials.key?(type)
+        @credentials[type] = value
       end
     end
-
-    # Include these functions in Rails::Auth for convenience
-    extend Credentials
   end
 end

data/lib/rails/auth/credentials/injector_middleware.rb

@@ -1,6 +1,6 @@
 module Rails
   module Auth
-    module Credentials
+    class Credentials
       # A middleware for injecting an arbitrary credentials hash into the Rack environment
       # This is intended for development and testing purposes where you would like to
       # simulate a given X.509 certificate being used in a request or user logged in
@@ -11,7 +11,7 @@ module Rails
         end
 
         def call(env)
-          env[Rails::Auth::CREDENTIALS_ENV_KEY] = @credentials
+          env[Rails::Auth::Env::CREDENTIALS_ENV_KEY] = @credentials
           @app.call(env)
         end
       end

data/lib/rails/auth/env.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Rails
+  module Auth
+    # Wrapper for Rack environments with Rails::Auth helpers
+    class Env
+      # Rack environment key for marking external authorization
+      AUTHORIZED_ENV_KEY = "rails-auth.authorized".freeze
+
+      # Rack environment key for storing what allowed the request
+      ALLOWED_BY_ENV_KEY = "rails-auth.allowed-by".freeze
+
+      # Rack environment key for all rails-auth credentials
+      CREDENTIALS_ENV_KEY = "rails-auth.credentials".freeze
+
+      attr_reader :allowed_by, :credentials
+
+      # @param [Hash] :env Rack environment
+      def initialize(env, credentials: {}, authorized: false, allowed_by: nil)
+        raise TypeError, "expected Hash for credentials, got #{credentials.class}" unless credentials.is_a?(Hash)
+
+        @env         = env
+        @credentials = Credentials.new(credentials.merge(@env.fetch(CREDENTIALS_ENV_KEY, {})))
+        @authorized  = env.fetch(AUTHORIZED_ENV_KEY, authorized)
+        @allowed_by  = env.fetch(ALLOWED_BY_ENV_KEY, allowed_by)
+      end
+
+      # Check whether a request has been authorized
+      def authorized?
+        @authorized
+      end
+
+      # Mark the environment as authorized to access the requested resource
+      #
+      # @param [String] :allowed_by label of what allowed the request
+      def authorize(allowed_by)
+        self.allowed_by = allowed_by
+        @authorized = true
+      end
+
+      # Set the name of the authority which authorized the request
+      #
+      # @param [String] :allowed_by label of what allowed the request
+      def allowed_by=(allowed_by)
+        raise AlreadyAuthorizedError, "already allowed by #{@allowed_by.ispect}" if @allowed_by
+        raise TypeError, "expected String for allowed_by, got #{allowed_by.class}" unless allowed_by.is_a?(String)
+        @allowed_by = allowed_by
+      end
+
+      # Return a Rack environment
+      #
+      # @return [Hash] Rack environment
+      def to_rack
+        credentials = @env[CREDENTIALS_ENV_KEY] ||= {}
+        credentials.merge!(@credentials.to_hash)
+
+        @env[AUTHORIZED_ENV_KEY] = @authorized if @authorized
+        @env[ALLOWED_BY_ENV_KEY] = @allowed_by if @allowed_by
+
+        @env
+      end
+    end
+  end
+end

data/lib/rails/auth/error_page/debug_page.html.erb

@@ -113,8 +113,8 @@
           <td class="label"><%= h((resource.http_methods || "ALL").join(" ")) %> <%= h(format_path(resource.path)) %></td>
           <td>
             <ul>
-              <% resource.predicates.each do |name, predicate| %>
-              <li><%= h(name) %>: <%= h(format_attributes(predicate)) %></li>
+              <% resource.matchers.each do |name, matcher| %>
+              <li><%= h(name) %>: <%= h(format_attributes(matcher)) %></li>
               <% end %>
             </ul>
           </td>

data/lib/rails/auth/exceptions.rb

@@ -1,9 +1,15 @@
 module Rails
   module Auth
+    # Base class of all Rails::Auth errors
+    Error = Class.new(StandardError)
+
     # Unauthorized!
-    NotAuthorizedError = Class.new(StandardError)
+    NotAuthorizedError = Class.new(Error)
 
     # Error parsing e.g. an ACL
-    ParseError = Class.new(StandardError)
+    ParseError = Class.new(Error)
+
+    # Internal errors involving authorizing things that are already authorized
+    AlreadyAuthorizedError = Class.new(Error)
   end
 end

data/lib/rails/auth/helpers.rb

@@ -0,0 +1,64 @@
+module Rails
+  # Modular resource-based authentication and authorization for Rails/Rack
+  module Auth
+    module_function
+
+    # Mark a request as externally authorized. Causes ACL checks to be skipped.
+    #
+    # @param [Hash] :rack_env Rack environment
+    # @param [String] :allowed_by what allowed the request
+    #
+    def authorized!(rack_env, allowed_by)
+      Env.new(rack_env).tap do |env|
+        env.authorize(allowed_by)
+      end.to_rack
+    end
+
+    # Check whether a request has been authorized
+    #
+    # @param [Hash] :rack_env Rack environment
+    #
+    def authorized?(rack_env)
+      Env.new(rack_env).authorized?
+    end
+
+    # Mark what authorized the request in the Rack environment
+    #
+    # @param [Hash] :env Rack environment
+    # @param [String] :allowed_by what allowed this request
+    def set_allowed_by(rack_env, allowed_by)
+      Env.new(rack_env).tap do |env|
+        env.allowed_by = allowed_by
+      end.to_rack
+    end
+
+    # Read what authorized the request
+    #
+    # @param [Hash] :rack_env Rack environment
+    #
+    # @return [String, nil] what authorized the request
+    def allowed_by(rack_env)
+      Env.new(rack_env).allowed_by
+    end
+
+    # Obtain credentials from a Rack environment
+    #
+    # @param [Hash] :rack_env Rack environment
+    #
+    def credentials(rack_env)
+      Credentials.from_rack_env(rack_env)
+    end
+
+    # Add a credential to the Rack environment
+    #
+    # @param [Hash] :rack_env Rack environment
+    # @param [String] :type credential type to add to the environment
+    # @param [Object] :credential object to add to the environment
+    #
+    def add_credential(rack_env, type, credential)
+      Env.new(rack_env).tap do |env|
+        env.credentials[type] = credential
+      end.to_rack
+    end
+  end
+end