keycard 0.3.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95ea37a28c7738e482b571188cfbd96e376363903e7a8888ef643484e6da854e
-  data.tar.gz: 5279c715a7b837aafd75d8cd224f21318544862be2f42805bf19e1d951b04ec5
+  metadata.gz: 5a73c4a3d99e36a4126bde8248bc3050037dc333a9a264b3169dff4a715d9a67
+  data.tar.gz: 320cec317aa2b0fdf3d85bf02506db09267954484898e1b351d4bd69de2d7253
 SHA512:
-  metadata.gz: '095c01d740d69c8cf58cb708ae65ed5fce8533e22c26be9cd96fb030966e766800aa3fdd81923b31ec6662d09296f292c2fd3f20d0aff4f793651616f4eeaf12'
-  data.tar.gz: f91616faf6c27cbee76a455c998c171794fa7ce3fb00d59a44d58811af42edd9946c9aa07c764822e7d9ac14e40c7d557e020859b7111e3133e2078b0f6ce4b9
+  metadata.gz: fa1c61ee6513b56dd213229ee7df793076b095a54b52865f31b07d293a4bc235e72a563900f1fee5aff693de0136ad30b8be7b8345e47606d760ca5474d8ad5a
+  data.tar.gz: 86f727073283be6c122c3d4a0aaf7c5e738223306b08331779528087aecbe6bec1759b9fbaaa4819f033d1a3dc1fd0a4fd370d1107c4d5e068c9ec678fea9334

data/keycard.gemspec

@@ -33,6 +33,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rspec"
   spec.add_development_dependency "rubocop"
   spec.add_development_dependency "rubocop-rspec"
-  spec.add_development_dependency "sqlite3"
+  spec.add_development_dependency "sqlite3", "~> 1.3.13"
   spec.add_development_dependency "yard"
 end

data/lib/keycard/authentication/auth_token.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Keycard
+  module Authentication
+    # Identity verification based on an authorization token.
+    #
+    # The bound finder method is expected to take one parameter, the token as
+    # presented by the user. This will typically need to be digested for
+    # comparison with a stored version.
+    class AuthToken < Method
+      def apply
+        if token.nil?
+          skipped("No auth_token found in request attributes")
+        elsif (account = finder.call(token))
+          succeeded(account, "Account found for supplied Authorization Token", csrf_safe: true)
+        else
+          failed("Account not found for supplied Authorization Token")
+        end
+      end
+
+      private
+
+      def token
+        attributes.auth_token
+      end
+    end
+  end
+end

data/lib/keycard/authentication/method.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Keycard
+  module Authentication
+    # An abstract identity authentication method. Subclasses will inspect the
+    # attributes and session for a request, attempting to match an account, and
+    # recording the results on a {Result}.
+    #
+    # The general operation is that each authentication method will have its
+    # {#apply} method called. It should examine the attributes, session, or
+    # credentials, and decide whether the required information is present. Then:
+    #
+    # 1. If the method is not applicable, call {#skipped} with a message naming
+    #    the authentication method and why it was not applicable.
+    # 2. If the method is applicable, call the finder to attempt to locate the
+    #    user/account and verify the method-specific information. For example,
+    #    some methods will trust a username attribute that arrived by way of
+    #    a reverse proxy, and the finder will only need to verify that a user
+    #    exists with the given username. Other methods will need to verify that
+    #    a token or password supplied hashes to the correct value.
+    # 3. Depending on whether a user/account is identified and authenticated,
+    #    call {#succeeded} with the account and a message, or {#failed} with
+    #    a message.
+    #
+    # Each of the status methods appends to a result for diagnostic or audit
+    # purposes and affects whether the chain of authentication should continue or
+    # be terminated. If a authentication method is skipped, the next one will be
+    # attempted. If it succeeds, or fails, the chain will be terminated. If it
+    # succeeds, the identity attributes will be assigned to the account, and it
+    # will be set as the account on the result.
+    #
+    # For integration with larger-scale configuration (like how request
+    # attributes should be extracted and which authentication methods should be
+    # used, in what order), see {Keycard::Notary}.
+    #
+    # For stateful integration with controllers (like the notions of a "current
+    # user" and logging in and out), see {Keycard::ControllerMethods}.
+    class Method
+      def initialize(attributes:, session:, result:, finder:, **credentials)
+        @attributes = attributes
+        @session = session
+        @result = result
+        @finder = finder
+        @credentials = credentials
+      end
+
+      # Bind a finder callable and yield a factory lambda to create a
+      # Verification with all of the other parameters. This allows for
+      # configuring a prototype at the system level and applying items that vary
+      # per request more conveniently.
+      def self.bind(finder)
+        lambda do |attributes, session, result, **credentials|
+          new(
+            attributes: attributes,
+            session: session,
+            result: result,
+            finder: finder,
+            credentials: credentials
+          )
+        end
+      end
+
+      # Bind a class method as a finder. This is more convenient form than
+      # {::bind} because it uses a {Keycard::ReloadableProxy}, making it easier
+      # to work with finder methods on ActiveRecord models, which are reloaded in
+      # development on each change, without restarting the server.
+      def self.bind_class_method(finder_class, method)
+        bind(ReloadableProxy.new(finder_class, method))
+      end
+
+      # Attempt to apply this authentication method and record the status on the
+      # result.
+      def apply
+        skipped("Base Verification is always skipped; it should not be used directly.")
+      end
+
+      private
+
+      def skipped(message)
+        result.skipped(message)
+      end
+
+      def succeeded(account, message, csrf_safe: false)
+        account.identity = attributes.identity
+        result.succeeded(account, message, csrf_safe: csrf_safe)
+      end
+
+      def failed(message)
+        result.failed(message)
+      end
+
+      attr_reader :attributes
+      attr_reader :session
+      attr_reader :result
+      attr_reader :finder
+      attr_reader :credentials
+    end
+  end
+end

data/lib/keycard/authentication/result.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Keycard
+  module Authentication
+    # A Result is the central point of information about an authentication
+    # attempt. It logs the authentication methods attempted with their statuses
+    # and reports the overall status. When authentication is successful, it holds
+    # the user/account that was verified.
+    class Result
+      attr_reader :account
+      attr_reader :log
+
+      def initialize
+        @account = nil
+        @log = []
+        @failed = false
+        @csrf_safe = false
+      end
+
+      # Has this authentication completed successfully?
+      def authenticated?
+        !account.nil?
+      end
+
+      # Was there a failure for an attempted authentication method?
+      def failed?
+        @failed
+      end
+
+      # Does a completed verification protect from Cross-Site Request Forgery?
+      #
+      # This should be true in cases where the client presents authentication
+      # that is not automatic, like an authentication token, rather than
+      # automatic credentials like cookies or proxy-applied headers.
+      def csrf_safe?
+        @csrf_safe
+      end
+
+      # Log that the authentication method was not applicable; continue the chain.
+      #
+      # @param message [String] a message about why the authentication method was skipped
+      # @return [Boolean] false, indicating that the authentication method was inconclusive
+      def skipped(message)
+        log << "[SKIPPED] #{message}"
+        false
+      end
+
+      # Log that the authentication method failed; terminate the chain.
+      #
+      # @param message [String] a message about how the authentication method failed
+      # @return [Boolean] true, indicating that further authentication should not occur
+      def failed(message)
+        log << "[FAILURE] #{message}"
+        @failed = true
+      end
+
+      # Log that the authentication method succeeded; terminate the chain.
+      #
+      # @param account [User|Account] Object/model representing the authenticated account
+      # @param message [String] a message about how the authentication method succeeded
+      # @param csrf_safe [Boolean] set to true if this authentication method precludes
+      #   Cross-Site Request Forgery, as with a non-cookie token sent with the request
+      # @return [Boolean] true, indicating that further authentication should not occur
+      def succeeded(account, message, csrf_safe: false)
+        @account = account
+        @csrf_safe ||= csrf_safe
+        log << "[SUCCESS] #{message}"
+        true
+      end
+    end
+  end
+end

data/lib/keycard/authentication/session_user_id.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Keycard
+  module Authentication
+    # Identity verification based on a user_id present in the session.
+    #
+    # A user_id in the session would typically be placed there after some other
+    # login process, after which it is sufficient to authenticate the session.
+    # The finder, then, takes only one parameter, the ID as on the account's #id
+    # property.
+    class SessionUserId < Method
+      def apply
+        if user_id.nil?
+          skipped("No user_id found in session")
+        elsif (account = finder.call(user_id))
+          succeeded(account, "Account found for user_id '#{user_id}' in session")
+        else
+          failed("Account not found for user_id '#{user_id}' in session")
+        end
+      end
+
+      private
+
+      def user_id
+        session[:user_id]
+      end
+    end
+  end
+end

data/lib/keycard/authentication/user_eid.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Keycard
+  module Authentication
+    # Identity verification based on the user EID request attribute.
+    #
+    # The EID will typically be present in single sign-on scenarios, where
+    # there is a proxy in place to set secure headers. The finder is expected
+    # to take one paramter, the user_eid itself.
+    class UserEid < Method
+      def apply
+        if user_eid.nil?
+          skipped("No user_eid found in request attributes")
+        elsif (account = finder.call(user_eid))
+          succeeded(account, "Account found for user_eid '#{user_eid}'")
+        else
+          failed("Account not found for user_eid '#{user_eid}'")
+        end
+      end
+
+      private
+
+      def user_eid
+        attributes.user_eid
+      end
+    end
+  end
+end

data/lib/keycard/controller_methods.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Keycard
+  # Mixin for conveniences in controllers.
+  #
+  # These methods depend on a `notary` method in your controller that returns a
+  # configured {Keycard::Notary} instance.
+  module ControllerMethods
+    # The default session timeout is 24 hours, in seconds.
+    DEFAULT_SESSION_TIMEOUT = 60 * 60 * 24
+
+    # Check whether the current request is authenticated as coming from a known
+    # person or account.
+    #
+    # @return [Boolean] true if any of the {Notary}'s configured authentication
+    #   methods succeeds
+    def logged_in?
+      authentication.authenticated?
+    end
+
+    # Retrieve the user/account to which the current request is attributed.
+    #
+    # @return [User/Account] the user/account that has been authenticated; nil
+    #   if no one is logged in
+    def current_user
+      authentication.account
+    end
+
+    # Validate the session, resetting it if expired.
+    #
+    # This should be called as a before_action before {#authenticate!} when
+    # working with session-based logins. It preserves a CSRF token, if present,
+    # so login forms and the like will pass forgery protection.
+    def validate_session
+      csrf_token = session[:_csrf_token]
+      elapsed = begin
+                  Time.now - (session[:timestamp] || Time.at(0))
+                rescue StandardError
+                  session_timeout
+                end
+      reset_session if elapsed >= session_timeout
+      session[:_csrf_token] = csrf_token
+      session[:timestamp] = Time.now if session.key?(:timestamp)
+    end
+
+    # Require that some authentication method successfully identifies a user/account,
+    # raising an exception if there is a failure for active credentials or no
+    # applicable credentials are presented.
+    #
+    # @raise [AuthenticationFailed] if credentials for an attempted
+    #   authentication method are incorrect
+    # @raise [AuthenticationRequired] if all authentication methods are skipped
+    #   and authentication could not be attempted
+    # @return nil
+    def authenticate!
+      raise AuthenticationFailed if authentication.failed?
+      raise AuthenticationRequired unless authentication.authenticated?
+    end
+
+    # Attempt to authenticate, optionally with user-supplied credentials, and
+    # establish a session.
+    #
+    # @param credentials [Hash|kwargs] user-supplied credentials that will be
+    #   passed to each authentication method
+    # @return [Boolean] whether the login attempt was successful
+    def login(**credentials)
+      authentication(credentials).authenticated?.tap do |success|
+        setup_session if success
+      end
+    end
+
+    # Log an account in without checking any credentials, starting a session.
+    #
+    # @param account [User|Account] the user/account object to consider current;
+    #   must have an #id property.
+    def auto_login(account)
+      request.env["keycard.authentication"] = notary.waive(account)
+      setup_session
+    end
+
+    # Clear authentication status and terminate any open session.
+    def logout
+      request.env["keycard.authentication"] = notary.reject
+      reset_session
+    end
+
+    private
+
+    def authentication(**credentials)
+      request.env["keycard.authentication"] ||=
+        notary.authenticate(request, session, credentials)
+    end
+
+    # The session timeout, in seconds. Sessions will be cleared before any
+    # further authentication unless there is a timestamp younger than this many
+    # seconds old. The default is 24 hours.
+    #
+    # @return [Integer] session timeout, in seconds
+    def session_timeout
+      DEFAULT_SESSION_TIMEOUT
+    end
+
+    def setup_session
+      return_url = session[:return_to]
+      reset_session
+      session[:return_to] = return_url
+      session[:user_id] = current_user.id
+      session[:timestamp] = Time.now
+    end
+  end
+end

data/lib/keycard/notary.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Keycard
+  # A Notary is the primary entry point for authentication needs. It will
+  # examine the request, session, and user-supplied credentials and provide
+  # a {Result} with the results of identity verification.
+  #
+  # It relies on configuration to extract the correct attributes from each
+  # request and to use the appropriate identity {AuthenticationMethod}. Each
+  # authentication method will attempt to locate a matching account and, for
+  # those methods that involve user-supplied credentials, verify that are
+  # correct for that account.
+  class Notary
+    # Create a Notary, which authenticates requests, verifying the identity of
+    # the requester and issuing an {Authentication::Result}.
+    #
+    # @param attributes_factory [Request::AttributesFactory] the factory to create
+    #   {Request::Attributes} from the current request.
+    # @param methods [Array<callable>] the list of {AuthenticationMethod}s to
+    #   use, in order, each wrapped as a callable initializer. Each factory
+    #   should take (attributes, session, result, **credentials) and
+    #   instantiate an AuthenticationMethod with a bound account/user finder.
+    def initialize(attributes_factory:, methods:)
+      @attributes_factory = attributes_factory
+      @methods = methods
+    end
+
+    # Create a default Notary instance, using common authenticaiton methods and
+    # the default AttributesFactory that creates request attributes based on
+    # the Keycard.config.access value.
+    #
+    # This instance assumes that there is a `User` model with class methods
+    # called `authenticate_by_auth_token`, `authenticate_by_id`, and
+    # `authenticate_by_user_eid`. These should find the user with the given
+    # id, authorization token, and EID/username. This is the order of
+    # precedence, as well, corresponding to the following {AuthenticationMethod}s:
+    #
+    # 1. {Keycard::Authentication::AuthToken}
+    # 2. {Keycard::Authentication::SessionUserId}
+    # 3. {Keycard::Authentication::UserEid}
+    #
+    # @return [Keycard::Notary] a default Notary instance, bound to conventional
+    #   authentication methods on a User class.
+    def self.default
+      new(
+        attributes_factory: Keycard::Request::AttributesFactory.new,
+        methods: [
+          Keycard::Authentication::AuthToken.bind_class_method(:User, :authenticate_by_auth_token),
+          Keycard::Authentication::SessionUserId.bind_class_method(:User, :authenticate_by_id),
+          Keycard::Authentication::UserEid.bind_class_method(:User, :authenticate_by_user_eid)
+        ]
+      )
+    end
+
+    # Authenticate a request, giving a Result of the result.
+    #
+    # @param request [Rack::Request] the active request, used to extract attributes
+    # @param session [Session] the active session, to be inspected with #[]
+    # @return [Authentication::Result] the result of this authentication
+    def authenticate(request, session, **credentials)
+      attributes = attributes_factory.for(request)
+      Authentication::Result.new.tap do |result|
+        methods.find do |factory|
+          factory.call(attributes, session, result, credentials).apply
+        end
+      end
+    end
+
+    # Bypass normal authentication and create a Result for the given
+    # user/account. This would typically only be used in development or other
+    # administrative scenarios where it is appropriate to allow impersonation.
+    def waive(account)
+      Authentication::Result.new.tap do |result|
+        result.succeeded(account, "Administrative waiver for #{account}")
+      end
+    end
+
+    # Issue an unconditional rejection Result. This is useful for a logout
+    # workflow, where authenticating again yield a passing result. The
+    # notion here is that the rejection would be cached just like any other
+    # result, rather than simply clearing it for the request.
+    #
+    # A logout would typically be followed by an immediate redirect, but this
+    # is a provision to ensure that the current request stays unauthenticated.
+    #
+    # @see {Keycard::ControllerMethods#logout} for how this is used in the
+    #   context of the state of the current request.
+    def reject
+      Authentication::Result.new.tap do |result|
+        result.failed("Authentication rejected; session terminated")
+      end
+    end
+
+    private
+
+    attr_reader :attributes_factory
+    attr_reader :methods
+  end
+end

data/lib/keycard/reloadable_proxy.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Keycard
+  # A proxy for class methods, as for authentication methods on User/Account
+  # models. This is useful primarily during development mode, where binding
+  # a finder into a Verfication factory can break because of code reloading.
+  #
+  # For example, something like this would fail across requests where the User
+  # model is saved (in development):
+  # `AuthToken.bind(User.public_method(:authenticate_by_auth_token))`.
+  #
+  # Instead, you can bind to a class method with a proxy that will catch the
+  # error from Rails thrown when using a stale reference, replace the target
+  # method, and retry the call transparently.
+  #
+  # @example
+  #   callable = ReloadableProxy.new(:User, :authenticate_by_auth_token)
+  class ReloadableProxy
+    attr_reader :classname, :methodname, :target
+
+    def initialize(classname, methodname)
+      @classname = classname
+      @methodname = methodname
+      lookup
+    end
+
+    # Call the proxied class method, looking it up again if the class has been
+    # reloaded (as signified byt he ArgumentError Rails raises).
+    def call(*args)
+      target.call(*args)
+    rescue ArgumentError
+      lookup
+      target.call(*args)
+    end
+
+    def lookup
+      @target = Object.const_get(classname).method(methodname)
+    end
+  end
+end

data/lib/keycard/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Keycard
-  VERSION = "0.3.2"
+  VERSION = "0.3.3"
 end

data/lib/keycard.rb

@@ -6,6 +6,9 @@ require "ostruct"
 
 # All of the Keycard components are contained within this top-level module.
 module Keycard
+  class AuthenticationRequired < StandardError; end
+  class AuthenticationFailed < StandardError; end
+
   def self.config
     @config ||= OpenStruct.new(
       access: :direct
@@ -19,3 +22,15 @@ require "keycard/railtie" if defined?(Rails)
 require "keycard/institution_finder"
 require "keycard/request"
 require "keycard/token"
+
+require "keycard/notary"
+
+require "keycard/authentication/method"
+require "keycard/authentication/result"
+
+require "keycard/authentication/auth_token"
+require "keycard/authentication/session_user_id"
+require "keycard/authentication/user_eid"
+
+require "keycard/reloadable_proxy"
+require "keycard/controller_methods"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keycard
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.3
 platform: ruby
 authors:
 - Noah Botimer
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-07-01 00:00:00.000000000 Z
+date: 2019-07-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sequel
@@ -127,16 +127,16 @@ dependencies:
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.3.13
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.3.13
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -182,10 +182,18 @@ files:
 - docs/runtime_context.rst
 - keycard.gemspec
 - lib/keycard.rb
+- lib/keycard/authentication/auth_token.rb
+- lib/keycard/authentication/method.rb
+- lib/keycard/authentication/result.rb
+- lib/keycard/authentication/session_user_id.rb
+- lib/keycard/authentication/user_eid.rb
+- lib/keycard/controller_methods.rb
 - lib/keycard/db.rb
 - lib/keycard/digest_key.rb
 - lib/keycard/institution_finder.rb
+- lib/keycard/notary.rb
 - lib/keycard/railtie.rb
+- lib/keycard/reloadable_proxy.rb
 - lib/keycard/request.rb
 - lib/keycard/request/attributes.rb
 - lib/keycard/request/attributes_factory.rb