padlock_auth 0.1.0

data/lib/padlock_auth/config.rb

@@ -0,0 +1,211 @@
+require "padlock_auth/config/option"
+require "padlock_auth/config/scopes"
+
+module PadlockAuth
+  # Configuration for PadlockAuth.
+  #
+  # @example
+  #   PadlockAuth.configure do |config|
+  #     config.secure_with :token do
+  #       secret_key "my_secret_key"
+  #     end
+  #
+  #     config.default_scopes :read, :write
+  #     config.access_token_methods :from_bearer_authorization, :from_access_token_param
+  #     config.raise_on_errors!
+  #   end
+  #
+  class Config
+    include PadlockAuth::Mixins::BuildWith
+
+    # The configuration builder for `PadlockAuth::Config`.
+    #
+    # @see PadlockAuth::Utils::AbstractBuilder
+    #
+    class Builder < PadlockAuth::Utils::AbstractBuilder
+      # Configure the strategy to use for authentication.
+      #
+      # Strategies are responsible for building access tokens and authenticating them.
+      # PadlockAuth comes with a default strategy, `PadlockAuth::Token::Strategy`,
+      # which uses a shared secret key to build and authenticate access tokens.
+      #
+      # A strategy can be provided as:
+      # - an instance of `PadlockAuth::AbstractStrategy`, or one matching its interface,
+      # - a class that responds to `.build` and returns an instance of `PadlockAuth::AbstractStrategy`, or
+      # - a string or symbol representing a built-in strategy (e.g. `:token`)
+      #
+      # The string or symbol strategy will be resolved to a class in the `PadlockAuth` namespace
+      # by appending `::Strategy` to the string and looking up the constant in the `PadlockAuth`
+      # namespace. For example, `:token` will resolve to `PadlockAuth::Token::Strategy`.
+      #
+      # You can define your own strategy by subclassing `PadlockAuth::AbstractStrategy`,
+      # and passing an instance of your strategy to `secure_with`, or by using the naming convention
+      # and passing a string or symbol.
+      #
+      # @param strategy [PadlockAuth::AbstractStrategy, Class, String, Symbol] The strategy to use for authentication
+      #
+      # @yield A block to configure the strategy (yielded by the strategy's `build` method)
+      #
+      # @return [PadlockAuth::AbstractStrategy] The strategy instance
+      def secure_with(strategy, &)
+        strategy = case strategy
+        when String, Symbol
+          strategy_klass = "PadlockAuth::#{strategy.to_s.camelize}::Strategy".safe_constantize
+          raise ArgumentError, "unknown strategy: #{strategy}" unless strategy_klass
+          strategy_klass.build(&)
+        when Class
+          strategy.build(&)
+        else
+          strategy
+        end
+        config.instance_variable_set(:@strategy, strategy)
+      end
+
+      # Define default access token scopes for your endpoint.
+      #
+      # Scopes are used to limit access to certain parts of your API. When a token
+      # is created, it is assigned a set of scopes that define what it can access.
+      #
+      # Calls to `padlock_authorize!` will check that the token has the required scopes,
+      # if no scopes are provided, the default scopes will be used.
+      #
+      # @param scopes [Array] Default set of access (PadlockAuth::Config::Scopes.new)
+      # token scopes
+      #
+      def default_scopes(*scopes)
+        config.instance_variable_set(:@default_scopes, PadlockAuth::Config::Scopes.from_array(*scopes))
+      end
+
+      # Change the way access token is authenticated from the request object.
+      #
+      # By default it retrieves a Bearer token from the `HTTP_AUTHORIZATION` header, then
+      # falls back to the `:access_token` or `:bearer_token` params from the
+      # `params` object.
+      #
+      # Available methods:
+      # - `:from_bearer_authorization` - Extracts a Bearer token from the `HTTP_AUTHORIZATION` header
+      # - `:from_access_token_param` - Extracts the token from the `:access_token` param
+      # - `:from_bearer_param` - Extracts the token from the `:bearer_token` param
+      # - `:from_basic_authorization` - Extracts Basic Auth credentials from the `HTTP_AUTHORIZATION` header
+      #
+      # @param methods [Array<Symbol>] Define access token methods, in order of preference
+      #
+      def access_token_methods(*methods)
+        config.instance_variable_set(:@access_token_methods, methods.flatten.compact)
+      end
+
+      # Calls to `padlock_authorize!` will raise an exception when authentication fails.
+      #
+      def raise_on_errors!
+        handle_auth_errors(:raise)
+      end
+
+      # Calls to `padlock_authorize!` will render an error response when authentication fails.
+      #
+      # This is the default behavior.
+      #
+      def render_on_errors!
+        handle_auth_errors(:render)
+      end
+    end
+
+    # @!method build(&)
+    # @!scope class
+    #
+    # Builds the configuration instance using the builder.
+    #
+    # @yield block to configure the configuration
+    #
+    # @return [PadlockAuth::Config] the configuration instance
+    #
+    # @see PadlockAuth::Config::Builder
+    build_with Builder
+
+    extend PadlockAuth::Config::Option
+
+    # @!attribute [r] realm
+    #
+    # The strategy to use for authentication.
+    #
+    # @return [PadlockAuth::AbstractStrategy] The authentication strategy
+    #
+    attr_reader :strategy
+
+    # @!attribute [r] realm
+    #
+    # WWW-Authenticate Realm (default "PadlockAuth").
+    #
+    # @return [String] The Authentication realm
+    #
+    option :realm, default: "PadlockAuth"
+
+    # @!attribute [r] default_scopes
+    #
+    # Default required scopes, used whenever `padlock_authorize!` is called without arguments.
+    #
+    # Empty by default.
+    #
+    # @return [PadlockAuth::Config::Scopes] Default required scopes
+    #
+    def default_scopes
+      @default_scopes ||= PadlockAuth::Config::Scopes.new
+    end
+
+    # @!attribute [r] access_token_methods
+    #
+    # Methods to extract the access token from the request.
+    #
+    # @see PadlockAuth::Rails::TokenExtractor for available methods
+    #
+    # @return [Array<Symbol>] Methods to extract the access token
+    #
+    def access_token_methods
+      @access_token_methods ||= %i[
+        from_bearer_authorization
+        from_access_token_param
+        from_bearer_param
+      ]
+    end
+
+    # @!attribute [r] handle_auth_errors
+    #
+    # How to handle authentication errors.
+    #
+    # - `:raise` - Raise an exception when authentication fails
+    # - `:render` - Render an error response when authentication fails
+    #
+    # @return [Symbol] The error handling method
+    #
+    option :handle_auth_errors, default: :render
+
+    # @return [Boolean] Whether to render an error response when authentication fails
+    #
+    def render_on_errors?
+      handle_auth_errors == :render
+    end
+
+    # @return [Boolean] Whether to raise an exception when authentication fails
+    #
+    def raise_on_errors?
+      handle_auth_errors == :raise
+    end
+
+    # @api private
+    #
+    # Called by PadlockAuth::Utils::AbstractBuilder#build to validate the configuration.
+    #
+    # @raise [ArgumentError] If the configuration is invalid
+    #
+    def validate!
+      raise ArgumentError, "strategy has not been configured via secure_with" if strategy.nil?
+
+      raise ArgumentError, "realm is required" if realm.blank?
+
+      unless handle_auth_errors.in? %i[raise render]
+        raise ArgumentError, "handle_auth_errors must be :raise, or :render"
+      end
+
+      true
+    end
+  end
+end

data/lib/padlock_auth/errors.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module PadlockAuth
+  # Errors for PadlockAuth.
+  module Errors
+    # A generic error for PadlockAuth.
+    class PadlockAuthError < StandardError; end
+
+    # An error with a HTTP response.
+    class ResponseError < PadlockAuthError
+      attr_reader :response
+
+      # Initialize a new response error.
+      #
+      # @param response [PadlockAuth::Http::ErrorResponse] The response
+      def initialize(response)
+        @response = response
+      end
+    end
+
+    # The token is invalid.
+    class InvalidToken < ResponseError; end
+
+    # The token has expired.
+    class TokenExpired < InvalidToken; end
+
+    # The token has been revoked.
+    class TokenRevoked < InvalidToken; end
+
+    # The token is invalid for an unknown reason.
+    class TokenUnknown < InvalidToken; end
+
+    # The token is forbidden for the requested resource.
+    class TokenForbidden < InvalidToken; end
+  end
+end

data/lib/padlock_auth/http/error_response.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module PadlockAuth
+  module Http
+    ##
+    # A generic error response for PadlockAuth.
+    #
+    # This class is intended to be extended by specific error responses.
+    #
+    class ErrorResponse
+      # @param attributes [Hash] error attributes
+      #
+      def initialize(attributes = {})
+        @name = attributes[:name]
+        @status = attributes[:status] || :bad_request
+      end
+
+      # @return [Symbol] The error name
+      attr_reader :name
+
+      # @return [Symbol] The HTTP status code
+      attr_reader :status
+
+      # @!attribute [r] description
+      # @return [String] A human-readable description of the error
+      def description
+        I18n.translate(
+          name,
+          scope: %i[padlock_auth errors messages],
+          default: :server_error
+        )
+      end
+
+      # @return [Hash] JSON response body
+      #
+      def body
+        {
+          error: name,
+          error_description: description
+        }.reject { |_, v| v.blank? }
+      end
+
+      # @return [Hash] HTTP headers
+      #
+      def headers
+        {
+          "Cache-Control" => "no-store, no-cache",
+          "Content-Type" => "application/json; charset=utf-8",
+          "WWW-Authenticate" => authenticate_info
+        }
+      end
+
+      # Raise an exception based on the error response.
+      #
+      # @raise [PadlockAuth::Errors::ResponseError] with the error response
+      def raise_exception!
+        raise exception_class.new(self), description
+      end
+
+      protected
+
+      # @return [Class<ResponseError>] Exception class to raise
+      #
+      def exception_class
+        raise NotImplementedError, "error response must define #exception_class"
+      end
+
+      private
+
+      def authenticate_info
+        %(Bearer realm="#{PadlockAuth.config.realm}", error="#{name}", error_description="#{description}")
+      end
+    end
+  end
+end

data/lib/padlock_auth/http/forbidden_token_response.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module PadlockAuth
+  module Http
+    ##
+    # A response for a forbidden token.
+    #
+    # A forbidden token response is returned when a token is valid,
+    # but does not have the required scopes.
+    #
+    class ForbiddenTokenResponse < ErrorResponse
+      attr_reader :reason
+
+      ##
+      # Create a new forbidden token response from an access token.
+      #
+      # @param access_token [PadlockAuth::AbstractAccessToken] Access token
+      #
+      # @param scopes [Array<String>] Required scopes
+      #
+      # @param attributes [Hash] Additional attributes
+      #
+      def self.from_access_token(access_token, scopes, attributes = {})
+        new(attributes.merge(reason: access_token&.forbidden_token_reason, scopes: scopes))
+      end
+
+      # Create a new forbidden token response.
+      #
+      # @param attributes [Hash] Attributes
+      #
+      def initialize(attributes = {})
+        super(attributes.merge(name: :invalid_scope, status: :forbidden))
+        @reason = attributes[:reason] || :unknown
+        @scopes = attributes[:scopes]
+      end
+
+      # @!attribute [r] description
+      # @return [String] A translated description of the error
+      #
+      def description
+        @description ||=
+          I18n.translate(
+            @reason,
+            scope: %i[padlock_auth errors messages forbidden_token],
+            oauth_scopes: @scopes.map(&:to_s).join(" "),
+            default: :unknown
+          )
+      end
+
+      # @return [Hash] HTTP headers
+      #
+      def headers
+        headers = super
+        headers.delete "WWW-Authenticate" # Authentication was successful, so no need to display auth error info
+        headers
+      end
+
+      protected
+
+      # @return [Class<PadlockAuth::Errors::TokenForbidden>] Exception class
+      #
+      def exception_class
+        PadlockAuth::Errors::TokenForbidden
+      end
+    end
+  end
+end

data/lib/padlock_auth/http/invalid_token_response.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module PadlockAuth
+  module Http
+    ##
+    # A response for an invalid token.
+    #
+    # An invalid token response is returned when a token is invalid.
+    #
+    class InvalidTokenResponse < ErrorResponse
+      # Reason for the invalid token.
+      #
+      # Possible reasons are:
+      # - :revoked
+      # - :expired
+      # - :unknown
+      #
+      # @return [Symbol] The reason for the invalid token
+      attr_reader :reason
+
+      # Create a new invalid token response from an access token.
+      #
+      # @param access_token [PadlockAuth::AbstractAccessToken] Access token
+      #
+      # @param attributes [Hash] Additional attributes
+      #
+      def self.from_access_token(access_token, attributes = {})
+        new(attributes.merge(reason: access_token&.invalid_token_reason))
+      end
+
+      # Create a new invalid token response.
+      #
+      # @param attributes [Hash] Attributes
+      #
+      def initialize(attributes = {})
+        super(attributes.merge(name: :invalid_grant, status: :unauthorized))
+        @reason = attributes[:reason] || :unknown
+      end
+
+      # @!attribute [r] description
+      # @return [String] A translated description of the error
+      #
+      def description
+        @description ||=
+          I18n.translate(
+            reason,
+            scope: %i[padlock_auth errors messages invalid_token],
+            default: :unknown
+          )
+      end
+
+      protected
+
+      # Return the exception class for the error response.
+      #
+      # Depending on the reason, a different exception class will be raised.
+      #
+      # Defaults to `PadlockAuth::Errors::TokenUnknown`.
+      #
+      # @return [Class<InvalidToken>] Exception class
+      #
+      def exception_class
+        {
+          revoked: PadlockAuth::Errors::TokenRevoked,
+          expired: PadlockAuth::Errors::TokenExpired
+        }.fetch(reason, PadlockAuth::Errors::TokenUnknown)
+      end
+    end
+  end
+end

data/lib/padlock_auth/mixins/build_with.rb

@@ -0,0 +1,49 @@
+module PadlockAuth
+  module Mixins
+    # Provides a quick way to build configuration instances.
+    #
+    # Provide `PadlockAuth::Utils::AbstractBuilder` sub-class to the `build_with` class method,
+    # to define a build method that will take a block to configure the instance.
+    #
+    # @example
+    #   class MyConfig
+    #     include PadlockAuth::Mixins::BuildWith
+    #
+    #     class Builder < PadlockAuth::Utils::AbstractBuilder
+    #       def name(value)
+    #         config.instance_variable_set(:@name, value)
+    #       end
+    #     end
+    #
+    #     build_with Builder
+    #   end
+    #
+    #   config = MyConfig.build do
+    #     name 'My Name'
+    #   end
+    #   config.name # => 'My Name'
+    #
+    module BuildWith
+      extend ActiveSupport::Concern
+
+      included do
+        # Prevent direct instantiation of the class
+        private_class_method :new
+      end
+
+      class_methods do
+        # Define a builder class for the configuration.
+        #
+        # The builder class should accept a call to `new` with a new instance of the
+        # configuration class, and a block to configure the instance.
+        #
+        # @yield block to configure the builder class
+        #
+        def build_with(builder_class)
+          mattr_reader(:builder_class) { builder_class }
+          define_singleton_method(:build) { |&block| builder_class.new(new, &block).build }
+        end
+      end
+    end
+  end
+end

data/lib/padlock_auth/mixins/hide_attribute.rb

@@ -0,0 +1,31 @@
+module PadlockAuth
+  module Mixins
+    # Hide an attribute from inspection and JSON serialization.
+    #
+    # Prevents accidental exposure of sensitive data in logs or responses.
+    #
+    module HideAttribute
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # Hide an attribute from inspection and JSON serialization.
+        #
+        # @param attribute [Symbol, String] The attribute to hide
+        #
+        def hide_attribute(attribute)
+          mod = Module.new
+          mod.define_method(:inspect) do
+            super().gsub(instance_variable_get(:"@#{attribute}"), "[REDACTED]")
+          end
+          mod.define_method(:as_json) do |options = nil|
+            options ||= {}
+            options[:except] ||= []
+            options[:except] |= [attribute.to_s]
+            super(options)
+          end
+          include mod
+        end
+      end
+    end
+  end
+end

data/lib/padlock_auth/rails/helpers.rb

@@ -0,0 +1,142 @@
+module PadlockAuth
+  module Rails
+    ##
+    # Helpers for Rails controllers.
+    #
+    # Provides `padlock_authorize!` method to controllers.
+    module Helpers
+      protected
+
+      # @!visibility public
+      #
+      # Authorize the request with the given scopes.
+      #
+      # If the request is not authorized, an error response will be rendered
+      # or an exception will be raised, depending on the configuration.
+      #
+      # @param scopes [Array<String>] Scopes required for the request, defaults to the default scopes.
+      #
+      def padlock_authorize!(*scopes)
+        @_padlock_auth_scopes = scopes.presence || PadlockAuth.config.default_scopes
+
+        padlock_render_error unless valid_padlock_auth_token?
+      end
+
+      # Default render options for unauthorized requests.
+      #
+      # As the OAuth 2.0 specification does not explicitly define the error response
+      # for an invalid request to a protected resource, this method replicates  the
+      # error response for an invalid request access token request.
+      #
+      # @example
+      #   {
+      #     error: "invalid_grant",
+      #     error_description: "The access token is invalid."
+      #   }
+      #
+      # @see https://datatracker.ietf.org/doc/html/rfc6749#section-7.2
+      #
+      # @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
+      #
+      # @param error [PadlockAuth::Http::InvalidTokenResponse] Invalid grant response.
+      #
+      # @return [Hash] Render options, passed to `render`
+      #
+      def padlock_auth_unauthorized_render_options(error:, **)
+        {json: error.body, status: error.status}
+      end
+
+      # Default render options for forbidden requests.
+      #
+      # As the OAuth 2.0 specification does not explicitly define the error response
+      # for an invalid request to a protected resource, this method replicates  the
+      # error response for an invalid request access token request.
+      #
+      # @example
+      #   {
+      #     error: "invalid_scope",
+      #     error_description: 'Access to this resource requires scope "foo bar baz".'
+      #   }
+      #
+      # @see https://datatracker.ietf.org/doc/html/rfc6749#section-7.2
+      #
+      # @see https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
+      #
+      # @param error [PadlockAuth::Http::ForbiddenTokenResponse] Invalid scope response
+      #
+      # @return [Hash] Render options, passed to `render`
+      #
+      def padlock_auth_forbidden_render_options(error:, **)
+        {json: error.body, status: error.status}
+      end
+
+      # @!visibility public
+      #
+      # Retrieve the access token from the request.
+      #
+      # Does not check if the token is valid or matches the required scopes.
+      #
+      # @return [PadlockAuth::AbstractToken, nil] Access token
+      #
+      def padlock_auth_token
+        @padlock_auth_token ||= TokenFactory.authenticate(request)
+      end
+
+      private
+
+      def valid_padlock_auth_token?
+        padlock_auth_token&.acceptable?(@_padlock_auth_scopes)
+      end
+
+      def padlock_render_error
+        error = padlock_auth_error
+        error.raise_exception! if PadlockAuth.config.raise_on_errors?
+
+        headers.merge!(error.headers.reject { |k| k == "Content-Type" })
+        padlock_render_error_with(error)
+      end
+
+      def padlock_render_error_with(error)
+        options = padlock_auth_render_options(error) || {}
+        status = padlock_auth_status_for_error(
+          error, options.delete(:respond_not_found_when_forbidden)
+        )
+        if options.blank? || !respond_to?(:render)
+          head status
+        else
+          options[:status] = status
+          options[:layout] = false if options[:layout].nil?
+          render options
+        end
+      end
+
+      def padlock_auth_error
+        if padlock_auth_invalid_token_response?
+          PadlockAuth.build_invalid_token_response(padlock_auth_token)
+        else
+          PadlockAuth.build_forbidden_token_response(padlock_auth_token, @_padlock_auth_scopes)
+        end
+      end
+
+      def padlock_auth_render_options(error)
+        if padlock_auth_invalid_token_response?
+          padlock_auth_unauthorized_render_options(error: error)
+        else
+          padlock_auth_forbidden_render_options(error: error)
+        end
+      end
+
+      def padlock_auth_status_for_error(error, respond_not_found_when_forbidden)
+        if respond_not_found_when_forbidden && error.status == :forbidden
+          :not_found
+        else
+          error.status
+        end
+      end
+
+      def padlock_auth_invalid_token_response?
+        !padlock_auth_token || !padlock_auth_token.accessible?
+      end
+    end
+  end
+end