padlock_auth 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 295f953fb3b0a6a821cca2f2f18ac16a773d140612d337442bed3f5108400777
+  data.tar.gz: c50bbeb53da5386be9305875c842beae00583af59a5fe488dd271c057eaee943
+SHA512:
+  metadata.gz: 7e1d4cf307d4d63bf7a44026b209fc26c4cfe839476560da5cab65224285da2f3966a68073a38b7fbab907d878f5725ea1c254a08477fcdc80f8272e0a77756b
+  data.tar.gz: 2689fe7dd1d69bff8933967ee33523235041aa34b5ec84714ec87f26ac6dc3ff22886ebf6c92eea34c5e3305831ca3192800415d7717173e9368b46e28b8a4f4

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Ben Morrall
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,275 @@
+# PadlockAuth
+
+PadlockAuth allows you to secure your Rails application using access tokens provided by an external provider.
+
+## Usage
+
+PadlockAuth separates the __how__ of token verification from the __where__ authentication occurs. You configure an authentication strategy in an initializer and use callbacks in controllers to secure endpoints, allowing strategy changes without modifying your controllers.
+
+Designed for lightweight use, PadlockAuth is ideal for microservices or high-volume APIs, with support ranging from simple token matching to more complex JWT-based authentication. Unlike [Devise](https://github.com/heartcombo/devise) or [Doorkeeper](https://github.com/doorkeeper-gem/doorkeeper), PadlockAuth doesn't require a database, making it more suitable for microservices and lightweight scenarios.
+
+### Configuring a Basic Token Strategy
+
+The Basic Token Strategy is a simple authentication mechanism where the token received in the request is compared with a pre-configured secret key. This strategy is ideal for straightforward use cases where you only need to validate the presence of a valid token. It does not provide any scopes to be authenticated against.
+
+#### Example Configuration
+
+```ruby
+# config/initializers/padlock_auth.rb
+PadlockAuth.configure do
+  secure_with :token do
+    secret_key "MySecretKey"
+  end
+end
+```
+
+In this example:
+
+- The `:token` strategy validates the request's token by comparing it with the configured `secret_key`.
+
+### Configuring a Custom Strategy
+
+A Custom Strategy in PadlockAuth allows you to implement your own authentication logic. This requires creating a custom Strategy class that generates an Access Token class.
+
+#### 1. Define the Strategy Class
+
+The Strategy class should inherit from `PadlockAuth::AbstractStrategy` and implement the following methods:
+
+- `build_access_token`: Builds an access token from a provided String access token.
+- `build_access_token_from_credentials`: Builds an access token from provided username and password.
+
+Both methods should return an `AccessToken` object.
+
+```ruby
+class MyCustomStrategy < PadlockAuth::AbstractStrategy
+  def build_access_token(token_string)
+    # Logic to build an access token from a string token
+    MyAccessToken.new(token_string)
+  end
+
+  def build_access_token_from_credentials(username, password)
+    # Logic to build an access token from provided credentials
+    MyAccessToken.new(generate_token_from_credentials(username, password))
+  end
+end
+```
+
+#### 2. Define the AccessToken Class
+
+The `AccessToken` class should inherit from `PadlockAuth::AbstractAccessToken` and implement the following methods:
+
+- `accessible?`: Returns `true` if the access token is valid. This means the token:
+  - Matches the expected token value, and
+  - Contains any required attributes, and
+  - Has not expired.
+- `includes_scope?`: Returns `true` if the access token matches at least one of the provided scope values.
+
+```ruby
+class MyAccessToken < PadlockAuth::AbstractAccessToken
+  def accessible?
+    # Check token validity logic
+    valid_token? && required_attributes_present? && not_expired?
+  end
+
+  def includes_scope?(scopes)
+    # Check if the token includes at least one of the provided scopes
+    (scopes & token_scopes).any?
+  end
+end
+```
+
+#### 3. Configure the Custom Strategy
+
+Finally, configure PadlockAuth to use your custom strategy within the initializer:
+
+```ruby
+# config/initializers/padlock_auth.rb
+PadlockAuth.configure do
+  secure_with MyCustomStrategy.new
+end
+```
+
+This configuration allows you to implement a fully custom authentication strategy that integrates with PadlockAuth.
+
+### Securing a Rails Controller
+
+The `padlock_authorize!` method secures your API endpoints and optionally enforces scope requirements. The verification of scopes is managed by the configured authentication strategy.
+
+#### Example: Specifying Scopes
+
+You can specify multiple scopes in a single call:
+
+```ruby
+before_action { padlock_authorize! :read, :write }
+```
+
+In this example:
+
+- The action requires the access token to include either the :read **or** :write scope.
+
+Alternatively, you can require multiple scopes by calling padlock_authorize! separately for each:
+
+```ruby
+before_action :require_read_and_write_scopes
+
+private
+
+def require_read_and_write_scopes
+  padlock_authorize! :read
+  padlock_authorize! :write
+end
+```
+
+In this case:
+
+The action requires the access token to include **both** the :read and :write scopes.
+
+#### Example: Using Default Scopes
+
+When no scopes are provided to `padlock_authorize!`, the default_scopes configuration will be applied. You can configure the default_scopes value during setup:
+
+```ruby
+PadlockAuth.configure do
+  secure_with MyCustomStrategy
+  default_scopes [:read] # Optional, defines the default required scopes
+end
+```
+
+In this case:
+
+If `padlock_authorize!` is called without explicit scopes, the `:read` scope will be enforced by default.
+
+For example:
+
+```ruby
+before_action :padlock_authorize!
+```
+
+- If the token includes the `:read` scope, the action will proceed.
+- If `default_scopes` is not set, no scopes are enforced by default when padlock_authorize! is called without scopes..
+
+### Providing Access Token Credentials
+
+You can configure PadlockAuth to support different ways of extracting a single access token by specifying an array of access_token_methods:
+
+```ruby
+PadlockAuth.configure do
+  access_token_methods [
+    :from_bearer_authorization, # Extracts token from Authorization header with Bearer token
+    :from_access_token_param,   # Extracts token from access_token param
+    :from_bearer_param          # Extracts token from bearer param
+  ]
+end
+```
+
+#### Token Extraction Methods
+
+- `from_bearer_authorization`: Extracts the token from an `Authorization` header with a Bearer token (i.e. Bearer VALID_ACCESS_TOKEN).
+- `from_access_token_param`: Extracts the token from an `access_token` parameter in the query string or form data.
+- `from_bearer_param`: Extracts the token from a `bearer` parameter in the query string or form data.
+
+These methods will call `build_access_token` with the provided strategy to create an AccessToken object.
+
+#### Example: Calling an Endpoint with a Bearer Token
+
+Here’s an example of how to call an endpoint with an access token using the `from_bearer_authorization` method. The token will be extracted from the Authorization header:
+
+```ruby
+require 'net/http'
+require 'uri'
+
+uri = URI.parse("http://example.com/api/endpoint")
+http = Net::HTTP.new(uri.host, uri.port)
+
+request = Net::HTTP::Get.new(uri)
+request["Authorization"] = "Bearer VALID_ACCESS_TOKEN"
+
+response = http.request(request)
+puts response.body
+```
+
+In this example:
+
+- The Bearer token `VALID_ACCESS_TOKEN` is passed in the Authorization header.
+- PadlockAuth will extract the token using the `from_bearer_authorization` method and validate it
+
+#### Example: Calling an Endpoint with a Token Parameter
+
+You can also pass the token as a query parameter. Here’s an example of how to call the same endpoint with the token passed in the `access_token` parameter:
+
+```ruby
+uri = URI.parse("http://example.com/api/endpoint?access_token=VALID_ACCESS_TOKEN")
+http = Net::HTTP.new(uri.host, uri.port)
+
+request = Net::HTTP::Get.new(uri)
+response = http.request(request)
+puts response.body
+```
+
+PadlockAuth will extract the token from the `access_token` parameter and validate it.
+
+### Providing Credentials with Username and Password
+
+ You can also provide username and password credentials by adding the `from_basic_authorization` method:
+
+ ```ruby
+PadlockAuth.configure do
+  access_token_methods [
+    :from_basic_authorization # Extracts token from a HTTP BASIC AUTHORIZATION header
+  ]
+end
+```
+
+- `from_basic_authorization`: Extracts the Username and Password from a Basic Authorization header.
+
+#### Example: Calling an Endpoint with Basic Authentication
+
+If you need to authenticate with a username and password, you can send the credentials in the `Authorization` header using Basic Authentication:
+
+```ruby
+uri = URI.parse("http://example.com/api/endpoint")
+http = Net::HTTP.new(uri.host, uri.port)
+
+request = Net::HTTP::Get.new(uri)
+request.basic_auth 'username', 'secret'
+
+response = http.request(request)
+puts response.body
+```
+
+PadlockAuth will extract the username and password using the `from_basic_authorization` method and use them to generate an access token.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "padlock_auth"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install padlock_auth
+```
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `rake` to run the tests and code quality checks.
+
+Generate documentaion using `rake yard`, which can be found in the `/doc` directory.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/bmorrall/padlock_auth. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/bmorrall/padlock_auth/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the PadlockAuth project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/bmorrall/padlock_auth/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,18 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"
+
+require "yard"
+YARD::Rake::YardocTask.new do |t|
+  t.files = ["lib/**/*.rb"]
+end
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task default: %i[
+  spec
+  standard
+]

data/config/locales/padlock_auth.en.yml

@@ -0,0 +1,14 @@
+en:
+  padlock_auth:
+    errors:
+      messages:
+        server_error: "An error occurred while processing your request."
+
+        invalid_token:
+          revoked: "The access token was revoked."
+          expired: "The access token has expired."
+          unknown: "The access token is invalid."
+
+        forbidden_token:
+          missing_scope: 'Access to this resource requires scope "%{oauth_scopes}".'
+          unknown: "The access token is forbidden."

data/lib/padlock_auth/abstract_access_token.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module PadlockAuth
+  # @abstract
+  #
+  # AbstractAccessToken is a base class for all access token classes.
+  #
+  # It provides all methods that are required for an access token to be
+  # compatible with PadlockAuth.
+  #
+  # All implemented methods will default to returning false or nil, so that
+  # any authentication/authorisation attempt will fail unless the methods are implemented.
+  class AbstractAccessToken
+    # Indicates if token is acceptable for specific scopes.
+    #
+    # @param scopes [Array<String>] scopes
+    #
+    # @return [Boolean] true if record is accessible and includes scopes, or false in other cases
+    #
+    def acceptable?(scopes)
+      accessible? && includes_scope?(scopes)
+    end
+
+    # Indicates the access token matches the specific criteria of the strategy to
+    # be considered a valid access token.
+    #
+    # Tokens failing to be accessible will be rejected as an invalid grant request,
+    # with a 401 Unauthorized response.
+    #
+    # @abstract Implement this method in your access token class
+    #
+    # @return [Boolean] true if the token is accessible, false otherwise
+    #
+    def accessible?
+      Kernel.warn "[PADLOCK_AUTH] #accessible? not implemented for #{self.class}"
+      false
+    end
+
+    # Provides a lookup key for the reason the token is invalid.
+    #
+    # Messages will use the i18n scope `padlock_auth.errors.messages.invalid_token`,
+    # with the default key of :unknown, providing a generic error message.
+    #
+    # @return [Symbol] the reason the token is invalid
+    #
+    def invalid_token_reason
+      :unknown
+    end
+
+    # Indicates if the token includes the required scopes/audience.
+    #
+    # Tokens failing to include the required scopes will be rejected as an invalid scope request,
+    # with a 403 Forbidden response.
+    #
+    # @abstract Implement this method in your access token class
+    #
+    # @param _required_scopes [Boolean] true if the token includes the required scopes, false otherwise
+    #
+    def includes_scope?(_required_scopes)
+      Kernel.warn "[PADLOCK_AUTH] #includes_scope? not implemented for #{self.class}"
+      false
+    end
+
+    # Provides a lookup key for the reason the token is forbidden.
+    #
+    # Messages will use the i18n scope `padlock_auth.errors.messages.forbidden_token`,
+    # with the default key of :missing_scope, providing a generic error message.
+    #
+    # The required scopes are passed as an argument to the i18n for some user feedback as required.
+    #
+    # @return [Symbol] the reason the token is forbidden
+    #
+    def forbidden_token_reason
+      :unknown
+    end
+  end
+end

data/lib/padlock_auth/abstract_strategy.rb

@@ -0,0 +1,52 @@
+module PadlockAuth
+  # @abstract
+  #
+  # Abstract strategy for building and authenticating access tokens.
+  #
+  # Strategies are responsible for building access tokens and authenticating them.
+  class AbstractStrategy
+    # Build an access token from a raw token.
+    #
+    # @param _raw_token [String] The raw token
+    #
+    # @return [PadlockAuth::AbstractAccessToken, nil] The access token
+    def build_access_token(_raw_token)
+      Kernel.warn "[PADLOCK_AUTH] #build_access_token not implemented for #{self.class}"
+      nil
+    end
+
+    # Build an access token from credentials.
+    #
+    # @param _username [String] The username
+    # @param _password [String] The password
+    #
+    # @return [PadlockAuth::AbstractAccessToken, nil] The access token
+    def build_access_token_from_credentials(_username, _password)
+      Kernel.warn "[PADLOCK_AUTH] #build_access_token_from_credentials not implemented for #{self.class}"
+      nil
+    end
+
+    # Build an invalid token response.
+    #
+    # Used to indicate that a token is invalid.
+    #
+    # @param access_token [PadlockAuth::AbstractAccessToken] The access token
+    #
+    # @return [PadlockAuth::Http::InvalidTokenResponse] The response
+    def build_invalid_token_response(access_token)
+      Http::InvalidTokenResponse.from_access_token(access_token)
+    end
+
+    # Build a forbidden token response.
+    #
+    # Used to indicate that a token does not have the required scopes.
+    #
+    # @param access_token [PadlockAuth::AbstractAccessToken] The access token
+    # @param scopes [PadlockAuth::Config::Scopes] The required scopes
+    #
+    # @return [PadlockAuth::Http::ForbiddenTokenResponse] The response
+    def build_forbidden_token_response(access_token, scopes)
+      Http::ForbiddenTokenResponse.from_access_token(access_token, scopes)
+    end
+  end
+end

data/lib/padlock_auth/config/option.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module PadlockAuth
+  class Config
+    ##
+    # PadlockAuth configuration option DSL.
+    #
+    # Adds configuration methods to a builder class which will be used to configure the object.
+    #
+    # Adds accessor methods to the object being configured.
+    #
+    # @example
+    #  class MyConfig
+    #    class Builder < PadlockAuth::Config::AbstractBuilder; end
+    #
+    #    mattr_reader(:builder_class) { Builder }
+    #
+    #    extend PadlockAuth::Config::Option
+    #
+    #    option :name
+    #  end
+    #
+    #  config = MyConfig.builder_class.build do
+    #    name 'My Name'
+    #  end
+    #  config.name # => 'My Name'
+    #
+    module Option
+      # Defines configuration option
+      #
+      # When you call option, it defines two methods. One method will take place
+      # in the +Config+ class and the other method will take place in the
+      # +Builder+ class.
+      #
+      # The +name+ parameter will set both builder method and config attribute.
+      # If the +:as+ option is defined, the builder method will be the specified
+      # option while the config attribute will be the +name+ parameter.
+      #
+      # If you want to introduce another level of config DSL you can
+      # define +builder_class+ parameter.
+      # Builder should take a block as the initializer parameter and respond to function +build+
+      # that returns the value of the config attribute.
+      #
+      # @param name [Symbol] The name of the configuration option
+      # @param options [Hash] The options hash which can contain:
+      #   - as [String] Set the builder method that goes inside +configure+ block
+      #   - default [Object] The default value in case no option was set
+      #   - builder_class [Class] Configuration option builder class
+      #
+      #
+      # @example
+      #   option :name
+      #
+      # @example
+      #   option :name, as: :set_name
+      #
+      # @example
+      #   option :name, default: 'My Name'
+      #
+      # @example
+      #   option :scopes, builder_class: ScopesBuilder
+      #
+      #
+      def option(name, options = {})
+        attribute = options[:as] || name
+
+        builder_class.instance_eval do
+          if method_defined?(name)
+            Kernel.warn "[PADLOCK_AUTH] Option #{self.name}##{name} already defined and will be overridden"
+            remove_method name
+          end
+
+          define_method name do |*args, &block|
+            if (deprecation_opts = options[:deprecated])
+              warning = "[PADLOCK_AUTH] #{self.class.name}##{name} has been deprecated and will soon be removed"
+              warning = "#{warning}\n#{deprecation_opts.fetch(:message)}" if deprecation_opts.is_a?(Hash)
+
+              Kernel.warn(warning)
+            end
+
+            value = block || args.first
+
+            config.instance_variable_set(:"@#{attribute}", value)
+          end
+        end
+
+        define_method attribute do |*_args|
+          if instance_variable_defined?(:"@#{attribute}")
+            instance_variable_get(:"@#{attribute}")
+          else
+            options[:default]
+          end
+        end
+
+        public attribute
+      end
+
+      # Uses extended hook to ensure builder_class is defined.
+      #
+      # Implementing classes should define a +builder_class+ method that returns a builder class.
+      #
+      def self.extended(base)
+        return if base.respond_to?(:builder_class)
+
+        raise NotImplementedError,
+          "Define `self.builder_class` method for #{base} that returns your custom Builder class to use options DSL!"
+      end
+    end
+  end
+end

data/lib/padlock_auth/config/scopes.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module PadlockAuth
+  class Config
+    # Represents a collection of scopes.
+    #
+    class Scopes
+      include Enumerable
+      include Comparable
+
+      # Create a new Scopes instance from a string.
+      #
+      # @param string [String] A space-separated string of scopes
+      #
+      # @return [PadlockAuth::Config::Scopes] A new Scopes instance
+      def self.from_string(string)
+        string ||= ""
+        new.tap do |scope|
+          scope.add(*string.split(/\s+/))
+        end
+      end
+
+      # Create a new Scopes instance from an array.
+      #
+      # @param array [Array<String>] An array of scopes
+      #
+      # @return [PadlockAuth::Config::Scopes] A new Scopes instance
+      #
+      def self.from_array(*array)
+        new.tap do |scope|
+          scope.add(*array)
+        end
+      end
+
+      delegate :each, :empty?, to: :@scopes
+
+      # Initialize a new Scopes instance.
+      def initialize
+        @scopes = []
+      end
+
+      # Check if a scope exists in the collection.
+      #
+      # @param scope [String] The scope to check
+      #
+      # @return [Boolean] True if the scope exists
+      #
+      def exists?(scope)
+        @scopes.include? scope.to_s
+      end
+
+      # Add a scope to the collection.
+      #
+      # @param scopes [Array<String>] The scopes to add
+      #
+      def add(*scopes)
+        @scopes.push(*scopes.flatten.compact.map(&:to_s))
+        @scopes.uniq!
+      end
+
+      # Returns all scopes in the collection.
+      #
+      # @return [Array<String>] All scopes
+      def all
+        @scopes
+      end
+
+      # Returns all scopes as a string.
+      #
+      # @return [String] All scopes as a space-joined string
+      def to_s
+        @scopes.join(" ")
+      end
+
+      # Returns true if all scopes exist in the collection.
+      #
+      # @param scopes [Array<String>] The scopes to check
+      #
+      # @return [Boolean] True if all scopes exist
+      def scopes?(scopes)
+        scopes.all? { |scope| exists?(scope) }
+      end
+
+      alias_method :has_scopes?, :scopes?
+
+      # Adds two collections of scopes together.
+      #
+      def +(other)
+        self.class.from_array(all + to_array(other))
+      end
+
+      # Compares two collections of scopes.
+      #
+      # @param other [PadlockAuth::Config::Scopes, Array<String>] The other collection
+      #
+      def <=>(other)
+        if other.respond_to?(:map)
+          map(&:to_s).sort <=> other.map(&:to_s).sort
+        else
+          super
+        end
+      end
+
+      # Returns a scopes array with elements contained in both collections.
+      #
+      # @param other [PadlockAuth::Config::Scopes, Array<String>] The other collection
+      #
+      def &(other)
+        self.class.from_array(all & to_array(other))
+      end
+
+      private
+
+      def to_array(other)
+        case other
+        when Scopes
+          other.all
+        else
+          other.to_a
+        end
+      end
+    end
+  end
+end