rails-auth 0.0.0 → 0.0.1

data/Rakefile

@@ -1,6 +1,8 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
+require "rubocop/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
 
-task :default => :spec
+task default: %w(spec rubocop)

data/lib/rails/auth.rb

@@ -1,7 +1,4 @@
-require "rails/auth/version"
+# frozen_string_literal: true
 
-module Rails
-  module Auth
-    # Your code goes here...
-  end
-end
+# Pull in core library components that work with any Rack application
+require "rails/auth/rack"

data/lib/rails/auth/acl.rb

@@ -0,0 +1,88 @@
+module Rails
+  module Auth
+    # Route-based access control lists
+    class ACL
+      # Predicate matchers available by default in ACLs
+      # These are added by the individual files in lib/rails/auth/acl/matchers
+      # at the time they're loaded.
+      DEFAULT_MATCHERS = {} # rubocop:disable Style/MutableConstant
+
+      # Pull in default predicate matchers
+      require "rails/auth/acl/matchers/allow_all"
+
+      DEFAULT_MATCHERS.freeze
+
+      # Create a Rails::Auth::ACL from a YAML representation of an ACL
+      #
+      # @param [String] :yaml serialized YAML to load an ACL from
+      def self.from_yaml(yaml, **args)
+        require "yaml"
+        new(YAML.load(yaml), **args)
+      end
+
+      # @param [Array<Hash>] :acl Access Control List configuration
+      # @param [Hash] :matchers predicate matchers for use with this ACL
+      #
+      def initialize(acl, matchers: {})
+        @resources = []
+
+        acl.each_with_index do |entry|
+          resources = entry["resources"]
+          fail ParseError, "no 'resources' key present in entry: #{entry.inspect}" unless resources
+
+          predicates = parse_predicates(entry, matchers.merge(DEFAULT_MATCHERS))
+
+          resources.each do |resource|
+            @resources << Resource.new(resource, predicates).freeze
+          end
+        end
+
+        @resources.freeze
+      end
+
+      # Match the Rack environment against the ACL, checking all predicates
+      #
+      # @param [Hash] :env Rack environment
+      #
+      # @return [Boolean] is the request authorized?
+      #
+      def match(env)
+        @resources.any? { |resource| resource.match(env) }
+      end
+
+      # Find all resources that match the ACL. Predicates are *NOT* checked,
+      # instead only the initial checks for the "resources" section of the ACL
+      # are performed. Use the `#match` method to validate predicates.
+      #
+      # This method is intended for debugging AuthZ failures. It can find all
+      # resources that match the given request so the corresponding predicates
+      # can be introspected.
+      #
+      # @param [Hash] :env Rack environment
+      #
+      # @return [Array<Rails::Auth::ACL::Resource>] matching resources
+      #
+      def matching_resources(env)
+        @resources.find_all { |resource| resource.match_method_and_path(env) }
+      end
+
+      private
+
+      def parse_predicates(entry, matchers)
+        predicates = {}
+
+        entry.each do |name, options|
+          next if name == "resources"
+
+          matcher_class = matchers[name.to_sym]
+          fail ArgumentError, "no matcher for #{name}" unless matcher_class
+          fail TypeError, "expected Class for #{name}" unless matcher_class.is_a?(Class)
+
+          predicates[name.freeze] = matcher_class.new(options.freeze).freeze
+        end
+
+        predicates.freeze
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+module Rails
+  module Auth
+    class ACL
+      # Built-in predicate matchers
+      module Matchers
+        # Allows all principals access to a given resource
+        class AllowAll
+          def initialize(enabled)
+            fail ArgumentError, "enabled must be true/false" unless [true, false].include?(enabled)
+            @enabled = enabled
+          end
+
+          def match(_env)
+            @enabled
+          end
+        end
+
+        # Make `allow_all` available by default as an ACL matcher
+        ACL::DEFAULT_MATCHERS[:allow_all] = AllowAll
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+module Rails
+  module Auth
+    class ACL
+      # Authorizes requests by matching them against the given ACL
+      class Middleware
+        # Create Rails::Auth::ACL::Middleware from the args you'd pass to Rails::Auth::ACL's constructor
+        def self.from_acl_config(app, **args)
+          new(app, acl: Rails::Auth::ACL.new(**args))
+        end
+
+        # Create a new ACL Middleware object
+        #
+        # @param [Object] app next app in the Rack middleware chain
+        # @param [Hash]   acl Rails::Auth::ACL object to authorize the request with
+        #
+        # @return [Rails::Auth::ACL::Middleware] new ACL middleware instance
+        def initialize(app, acl: nil)
+          fail ArgumentError, "no acl given" unless acl
+
+          @app = app
+          @acl = acl
+        end
+
+        def call(env)
+          fail NotAuthorizedError, "unauthorized request" unless @acl.match(env)
+          @app.call(env)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Rails
+  module Auth
+    class ACL
+      # Rules for a particular route
+      class Resource
+        attr_reader :http_methods, :path, :predicates
+
+        # Valid HTTP methods
+        HTTP_METHODS = %w(GET HEAD PUT POST DELETE OPTIONS PATCH LINK UNLINK).freeze
+
+        # Options allowed for resource matchers
+        VALID_OPTIONS = %w(method path).freeze
+
+        # @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
+        #
+        def initialize(options, predicates)
+          fail TypeError, "expected Hash for options"    unless options.is_a?(Hash)
+          fail TypeError, "expected Hash for predicates" unless predicates.is_a?(Hash)
+
+          unless (extra_keys = options.keys - VALID_OPTIONS).empty?
+            fail ParseError, "unrecognized key in ACL resource: #{extra_keys.first}"
+          end
+
+          @http_methods = extract_methods(options["method"])
+          @path         = /\A#{options.fetch("path")}\z/
+          @predicates   = predicates.freeze
+        end
+
+        # Match this resource against the given Rack environment, checking all
+        # predicates to ensure at least one of them matches
+        #
+        # @param [Hash] :env Rack environment
+        #
+        # @return [Boolean] resource and predicates match the given request
+        #
+        def match(env)
+          return false unless match_method_and_path(env)
+          @predicates.any? { |_name, predicate| predicate.match(env) }
+        end
+
+        # Match *only* the request method/path against the given Rack environment.
+        # Predicates are NOT checked.
+        #
+        # @param [Hash] :env Rack environment
+        #
+        # @return [Boolean] method and path *only* match the given environment
+        #
+        def match_method_and_path(env)
+          return false unless @http_methods.nil? || @http_methods.include?(env["REQUEST_METHOD".freeze])
+          return false unless @path =~ env["REQUEST_PATH".freeze]
+          true
+        end
+
+        private
+
+        def extract_methods(methods)
+          methods = Array(methods)
+
+          return nil if methods.include?("ALL")
+
+          methods.each do |method|
+            fail ParseError, "invalid HTTP method: #{method}" unless HTTP_METHODS.include?(method)
+          end
+
+          methods.freeze
+        end
+      end
+    end
+  end
+end

data/lib/rails/auth/exceptions.rb

@@ -0,0 +1,9 @@
+module Rails
+  module Auth
+    # Unauthorized!
+    NotAuthorizedError = Class.new(StandardError)
+
+    # Error parsing e.g. an ACL
+    ParseError = Class.new(StandardError)
+  end
+end

data/lib/rails/auth/principals.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Rails
+  # Modular resource-based authentication and authorization for Rails/Rack
+  module Auth
+    # Rack environment key for all rails-auth principals
+    PRINCIPALS_ENV_KEY = "rails-auth.principals".freeze
+
+    # Functionality for storing principals in the Rack environment
+    module Principals
+      # Obtain principals from a Rack environment
+      #
+      # @param [Hash] :env Rack environment
+      #
+      def principals(env)
+        env.fetch(PRINCIPALS_ENV_KEY, {})
+      end
+
+      # Add a principal to the Rack environment
+      #
+      # @param [Hash] :env Rack environment
+      # @param [String] :type principal type to add to the environment
+      # @param [Object] :principal principal object to add to the environment
+      #
+      def add_principal(env, type, principal)
+        principals = env[PRINCIPALS_ENV_KEY] ||= {}
+
+        fail ArgumentError, "principal #{type} already added to request" if principals.key?(type)
+        principals[type] = principal
+      end
+    end
+
+    # Include these functions in Rails::Auth for convenience
+    extend Principals
+  end
+end

data/lib/rails/auth/rack.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Core library components that work with any Rack application
+require "rack"
+require "openssl"
+
+require "rails/auth/version"
+require "rails/auth/exceptions"
+require "rails/auth/principals"
+
+require "rails/auth/acl"
+require "rails/auth/acl/middleware"
+require "rails/auth/acl/resource"
+
+require "rails/auth/x509/filter/pem"
+require "rails/auth/x509/filter/java" if defined?(JRUBY_VERSION)
+require "rails/auth/x509/matcher"
+require "rails/auth/x509/middleware"
+require "rails/auth/x509/principal"

data/lib/rails/auth/rspec.rb

@@ -0,0 +1,6 @@
+require "rails/auth/rspec/helper_methods"
+require "rails/auth/rspec/matchers/acl_matchers"
+
+RSpec.configure do |config|
+  config.include Rails::Auth::RSpec::HelperMethods, acl_spec: true
+end

data/lib/rails/auth/rspec/helper_methods.rb

@@ -0,0 +1,51 @@
+module Rails
+  module Auth
+    module RSpec
+      # RSpec helper methods
+      module HelperMethods
+        # Creates an Rails::Auth::X509::Principal instance double
+        def x509_principal(cn: nil, ou: nil)
+          subject = ""
+          subject << "CN=#{cn}" if cn
+          subject << "OU=#{ou}" if ou
+
+          instance_double(X509::Principal, subject, cn: cn, ou: ou).tap do |principal|
+            allow(principal).to receive(:[]) do |key|
+              {
+                "CN" => cn,
+                "OU" => ou
+              }[key.to_s.upcase]
+            end
+          end
+        end
+
+        # Creates a principals hash containing a single X.509 principal instance double
+        def x509_principal_hash(**args)
+          { "x509" => x509_principal(**args) }
+        end
+
+        Rails::Auth::ACL::Resource::HTTP_METHODS.each do |method|
+          define_method("#{method.downcase}_request") do |principals: {}|
+            path = self.class.description
+
+            # Warn if methods are improperly used
+            unless path.chars[0] == "/"
+              fail ArgumentError, "expected #{path} to start with '/'"
+            end
+
+            env = {
+              "REQUEST_METHOD" => method,
+              "REQUEST_PATH"   => self.class.description
+            }
+
+            principals.each do |type, value|
+              Rails::Auth.add_principal(env, type.to_s, value)
+            end
+
+            env
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails/auth/rspec/matchers/acl_matchers.rb

@@ -0,0 +1,13 @@
+RSpec::Matchers.define(:permit) do |env|
+  description do
+    method     = env["REQUEST_METHOD"]
+    principals = Rails::Auth.principals(env)
+    message    = "allow #{method}s by "
+
+    return message << "unauthenticated clients" if principals.count.zero?
+
+    message << principals.values.map(&:inspect).join(", ")
+  end
+
+  match { |acl| acl.match(env) }
+end

data/lib/rails/auth/version.rb

@@ -1,5 +1,8 @@
+# frozen_string_literal: true
+
 module Rails
+  # Pluggable authentication and authorization for Rack/Rails
   module Auth
-    VERSION = "0.0.0"
+    VERSION = "0.0.1".freeze
   end
 end

data/lib/rails/auth/x509/filter/java.rb

@@ -0,0 +1,25 @@
+require "java"
+require "stringio"
+
+module Rails
+  module Auth
+    module X509
+      module Filter
+        # Support for extracting X509::Principals from Java's sun.security.x509.X509CertImpl
+        class Java
+          def call(cert)
+            OpenSSL::X509::Certificate.new(extract_der(cert)).freeze
+          end
+
+          private
+
+          def extract_der(cert)
+            stringio = StringIO.new
+            cert.derEncode(stringio.to_outputstream)
+            stringio.string
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails/auth/x509/filter/pem.rb

@@ -0,0 +1,14 @@
+module Rails
+  module Auth
+    module X509
+      module Filter
+        # Support for extracting X509::Principals from Privacy Enhanced Mail (PEM) certificates
+        class Pem
+          def call(pem)
+            OpenSSL::X509::Certificate.new(pem).freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails/auth/x509/matcher.rb

@@ -0,0 +1,22 @@
+module Rails
+  module Auth
+    module X509
+      # Predicate matcher for making assertions about X.509 principals
+      class Matcher
+        # @option options [String] cn Common Name of the subject
+        # @option options [String] ou Organizational Unit of the subject
+        def initialize(options)
+          @options = options
+        end
+
+        # @param [Hash] env Rack environment
+        def match(env)
+          principal = Rails::Auth.principals(env)["x509"]
+          return false unless principal
+
+          @options.all? { |name, value| principal[name] == value }
+        end
+      end
+    end
+  end
+end