padlock_auth 0.1.0

data/lib/padlock_auth/rails/token_factory.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module PadlockAuth
+  module Rails
+    ##
+    # Responsible for extracting access tokens from requests,
+    # and delgating the creation of access tokens to the configured strategy.
+    class TokenFactory
+      class << self
+        # Retreives the access token from the request using the configured methods.
+        def from_request(request, *methods)
+          methods.inject(nil) do |_, method|
+            method = self.method(method) if method.is_a?(Symbol)
+            credentials = method.call(request)
+            break credentials if credentials.present?
+          end
+        end
+
+        # Retreives the access token from the request, and builds an access token object.
+        def authenticate(request)
+          if (token = from_request(request, *PadlockAuth.config.access_token_methods))
+            if token.is_a?(Array)
+              PadlockAuth.build_access_token_from_credentials(*token)
+            else
+              PadlockAuth.build_access_token(token)
+            end
+          end
+        end
+
+        # Extracts the access token from the `access_token` parameter.
+        #
+        # @param request [ActionDispatch::Request] request
+        #
+        # @return [String, nil] Access token
+        #
+        def from_access_token_param(request)
+          request.parameters[:access_token]
+        end
+
+        # Extracts the access token from the `bearer_token` parameter.
+        #
+        # @param request [ActionDispatch::Request] request
+        #
+        # @return [String, nil] Access token
+        #
+        def from_bearer_param(request)
+          request.parameters[:bearer_token]
+        end
+
+        # Extracts a Bearer access token from the `Authorization` header.
+        #
+        # @param request [ActionDispatch::Request] request
+        #
+        # @return [String, nil] Access token
+        #
+        def from_bearer_authorization(request)
+          pattern = /^Bearer /i
+          header = request.authorization
+          token_from_header(header, pattern) if match?(header, pattern)
+        end
+
+        # Extracts Basic Auth credentials from the `Authorization` header.
+        #
+        # @param request [ActionDispatch::Request] request
+        #
+        # @return [Array, nil] Username and password
+        #
+        def from_basic_authorization(request)
+          pattern = /^Basic /i
+          header = request.authorization
+          token_from_basic_header(header, pattern) if match?(header, pattern)
+        end
+
+        private
+
+        def token_from_basic_header(header, pattern)
+          encoded_header = token_from_header(header, pattern)
+          decode_basic_credentials_token(encoded_header)
+        end
+
+        def decode_basic_credentials_token(encoded_header)
+          Base64.decode64(encoded_header).split(":", 2)
+        end
+
+        def token_from_header(header, pattern)
+          header.gsub(pattern, "")
+        end
+
+        def match?(header, pattern)
+          header&.match(pattern)
+        end
+      end
+    end
+  end
+end

data/lib/padlock_auth/railtie.rb

@@ -0,0 +1,22 @@
+module PadlockAuth
+  ##
+  # Railtie for PadlockAuth.
+  #
+  # Provides `padlock_authorize!` and `padlock_auth_token` methods to Rails controllers.
+  #
+  # Also adds PadlockAuth's locales to I18n.load_path.
+  #
+  class Railtie < ::Rails::Railtie
+    initializer "padlock_auth.helpers" do
+      ActiveSupport.on_load(:action_controller) do
+        include PadlockAuth::Rails::Helpers
+      end
+    end
+
+    initializer "padlock_auth.i18n" do
+      Dir.glob(File.join(File.dirname(__FILE__), "..", "..", "config", "locales", "*.yml")).each do |file|
+        I18n.load_path << File.expand_path(file)
+      end
+    end
+  end
+end

data/lib/padlock_auth/rspec_support.rb

@@ -0,0 +1,46 @@
+# This module provides matchers for testing PadlockAuth access_token and strategy
+# classes.
+#
+# In your implementations, use these shared examples to ensure that your classes
+# are compliant with the PadlockAuth API.
+#
+# @example
+#   require "padlock_auth/rspec_support"
+#
+#   RSpec.describe MyAccessToken do
+#     it { is_expected.to be_a_padlock_auth_access_token }
+#   end
+#
+# @example
+#   require "padlock_auth/rspec_support"
+#
+#   RSpec.describe MyStrategy do
+#     it { is_expected.to be_a_padlock_auth_strategy }
+#   end
+module PadlockAuth::Matchers
+  # Asserts that the subject matches the expected interface for a PadlockAuth access token.
+  #
+  # @return [RSpec::Matchers::BuiltIn::BaseMatcher]
+  #
+  def be_a_padlock_auth_access_token
+    respond_to(:acceptable?).with(1).arguments
+      .and(respond_to(:accessible?).with(0).arguments)
+      .and(respond_to(:includes_scope?).with(1).arguments)
+      .and(respond_to(:invalid_token_reason).with(0).arguments)
+      .and(respond_to(:forbidden_token_reason).with(0).arguments)
+  end
+
+  # Asserts that the subject matches the expected interface for a PadlockAuth strategy.
+  #
+  # @return [RSpec::Matchers::BuiltIn::BaseMatcher]
+  #
+  def be_a_padlock_auth_strategy
+    respond_to(:build_access_token).with(1).arguments
+      .and(respond_to(:build_invalid_token_response).with(1).arguments)
+      .and(respond_to(:build_forbidden_token_response).with(2).arguments)
+  end
+end
+
+RSpec.configure do |config|
+  config.include(PadlockAuth::Matchers)
+end

data/lib/padlock_auth/token/access_token.rb

@@ -0,0 +1,55 @@
+module PadlockAuth
+  module Token
+    ##
+    # Access token for simple token authentication.
+    #
+    # Represents a string token that is compared to a secret key.
+    #
+    # Does not allow for scopes, so it will always return false for any required
+    class AccessToken < PadlockAuth::AbstractAccessToken
+      include PadlockAuth::Mixins::HideAttribute
+
+      hide_attribute :token
+      hide_attribute :secret_key
+
+      # Initialize the access token with a token and secret key.
+      #
+      # @param token [String] The token
+      #
+      # @param secret_key [String] The secret key
+      #
+      def initialize(token, secret_key)
+        @token = token
+        @secret_key = secret_key
+      end
+
+      # Check if the token matches the secret key.
+      #
+      # @return [Boolean] true if the token matches the secret key
+      #
+      def accessible?
+        # Compare the tokens in a time-constant manner, to mitigate timing attacks.
+        ActiveSupport::SecurityUtils.secure_compare(@token, @secret_key)
+      end
+
+      # Check if the token includes the required scopes.
+      #
+      # Simple tokens do not include scopes, so this method will return false
+      # for any required scopes.
+      #
+      # @return [Boolean] true if the token includes the required scopes
+      #
+      def includes_scope?(required_scopes)
+        required_scopes.none?.tap do |result|
+          Kernel.warn "[PADLOCK_AUTH] #{self.class} does not permit any required scopes" unless result
+        end
+      end
+
+      # The token secret_key does not permit any required scopes, so display a generic message
+      #
+      def forbidden_token_reason
+        :unknown
+      end
+    end
+  end
+end

data/lib/padlock_auth/token/strategy.rb

@@ -0,0 +1,80 @@
+module PadlockAuth
+  module Token
+    ##
+    # Strategy for token-based authentication.
+    #
+    # This strategy compares a token from the request to a secret key.
+    #
+    # It does not allow for scopes, so it will always return false for any required scopes.
+    #
+    class Strategy < PadlockAuth::AbstractStrategy
+      include PadlockAuth::Mixins::BuildWith
+      include PadlockAuth::Mixins::HideAttribute
+
+      # The configuration builder for `PadlockAuth::Token::Strategy`.
+      class Builder < PadlockAuth::Utils::AbstractBuilder; end
+
+      # @!method build
+      # @!scope class
+      #
+      # Builds the stratey instance.
+      #
+      # @yield block to configure the strategy
+      #
+      # @return [PadlockAuth::Token::Strategy] the strategy instance
+      #
+      # @example
+      #   PadlockAuth::Token::Strategy.build do
+      #     secret_key "my_secret_key"
+      #   end
+      #
+      # @see PadlockAuth::Config::Builder#secure_with
+      build_with Builder
+
+      extend PadlockAuth::Config::Option
+
+      # @!attribute [r] secret_key
+      #
+      # The secret key used to build and authenticate access tokens.
+      #
+      # @return [String] the secret key
+      option :secret_key
+
+      hide_attribute :secret_key
+
+      # Builds an access token from a raw token.
+      #
+      # @param raw_token [String] The raw token from the request
+      #
+      # @return [PadlockAuth::Token::AccessToken] The access token
+      #
+      def build_access_token(raw_token)
+        PadlockAuth::Token::AccessToken.new(raw_token, secret_key)
+      end
+
+      # Builds an access token from username and password credentials.
+      #
+      # Only the password is required for this strategy, so the username is ignored.
+      #
+      # @param _username [String] The (ignored) username
+      #
+      # @param password [String] The password
+      #
+      # @return [PadlockAuth::Token::AccessToken] The access token
+      #
+      def build_access_token_from_credentials(_username, password)
+        PadlockAuth::Token::AccessToken.new(password, secret_key)
+      end
+
+      # @api private
+      #
+      # Called by the builder to validate the configuration.
+      #
+      # @raise [ArgumentError] If the secret key is missing
+      #
+      def validate!
+        raise ArgumentError, "secret_key is required" unless secret_key.present?
+      end
+    end
+  end
+end

data/lib/padlock_auth/utils/abstract_builder.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module PadlockAuth
+  module Utils
+    # Abstract base class for implementing configuration builders.
+    #
+    # Define a `validate!` method on the configuration instance to validate the configuration.
+    #
+    # @abstract
+    #
+    # @example
+    #   class MyConfig
+    #     class Builder < PadlockAuth::Utils::AbstractBuilder
+    #       def name(value)
+    #         config.instance_variable_set(:@name, value)
+    #       end
+    #     end
+    #
+    #     def self.build(&block)
+    #       Builder.new(self, &block).build
+    #     end
+    #
+    #     attr_reader :name
+    #   end
+    #
+    #   config = MyConfig.build do
+    #     name 'My Name'
+    #   end
+    #
+    class AbstractBuilder
+      # @return [Object] the instance being configured
+      attr_reader :config
+
+      # @param [Class] config instance
+      #
+      # @yield block to configure the instance
+      #
+      def initialize(config, &)
+        @config = config
+        instance_eval(&) if block_given?
+      end
+
+      # Builds and validates configuration.
+      #
+      # Invokes `validate!` on the configuration instance if it responds to it.
+      #
+      # @return [Object] the config instance
+      #
+      def build
+        @config.validate! if @config.respond_to?(:validate!)
+        @config
+      end
+    end
+  end
+end

data/lib/padlock_auth/version.rb

@@ -0,0 +1,4 @@
+module PadlockAuth
+  # PadlockAuth version.
+  VERSION = "0.1.0"
+end

data/lib/padlock_auth.rb

@@ -0,0 +1,76 @@
+require "rails"
+
+require "padlock_auth/version"
+require "padlock_auth/railtie"
+require "padlock_auth/errors"
+
+# PadlockAuth allows you to secure your Rails application using access tokens
+# provided by an external provider.
+#
+module PadlockAuth
+  # Abstract classes recommended for extension
+  autoload :AbstractAccessToken, "padlock_auth/abstract_access_token"
+  autoload :AbstractStrategy, "padlock_auth/abstract_strategy"
+
+  # Configuration classes
+  autoload :Config, "padlock_auth/config"
+
+  # Token stategy classes
+  module Token
+    autoload :AccessToken, "padlock_auth/token/access_token"
+    autoload :Strategy, "padlock_auth/token/strategy"
+  end
+
+  # Mixins for extending classes
+  module Mixins
+    autoload :BuildWith, "padlock_auth/mixins/build_with"
+    autoload :HideAttribute, "padlock_auth/mixins/hide_attribute"
+  end
+
+  module Utils
+    autoload :AbstractBuilder, "padlock_auth/utils/abstract_builder"
+  end
+
+  # HTTP response classes
+  module Http
+    autoload :ErrorResponse, "padlock_auth/http/error_response"
+    autoload :ForbiddenTokenResponse, "padlock_auth/http/forbidden_token_response"
+    autoload :InvalidTokenResponse, "padlock_auth/http/invalid_token_response"
+  end
+
+  # Rails-specific classes
+  module Rails
+    autoload :ConnectionHelpers, "padlock_auth/rails/connection_helpers"
+    autoload :Helpers, "padlock_auth/rails/helpers"
+    autoload :TokenFactory, "padlock_auth/rails/token_factory"
+  end
+
+  class << self
+    # Configure PadlockAuth.
+    #
+    # @yield [PadlockAuth::Config] configuration block
+    #
+    def configure(&)
+      @config = Config.build(&)
+    end
+
+    # @return [PadlockAuth::Config] configuration instance
+    #
+    def configuration
+      @config || configure
+    end
+
+    alias_method :config, :configuration
+
+    ### Strategy Delegation ###
+
+    delegate :build_access_token,
+      :build_access_token_from_credentials,
+      :build_invalid_token_response,
+      :build_forbidden_token_response,
+      to: :strategy
+
+    delegate :strategy, to: :config
+    private :strategy
+  end
+end

data/lib/tasks/padlock_auth_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :padlock_auth do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,143 @@
+--- !ruby/object:Gem::Specification
+name: padlock_auth
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ben Morrall
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-12-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.2.1
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.41.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.41.1
+description: PadlockAuth allows you to secure your Rails application using access
+  tokens provided by an external provider.
+email:
+- bemo56@hotmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- config/locales/padlock_auth.en.yml
+- lib/padlock_auth.rb
+- lib/padlock_auth/abstract_access_token.rb
+- lib/padlock_auth/abstract_strategy.rb
+- lib/padlock_auth/config.rb
+- lib/padlock_auth/config/option.rb
+- lib/padlock_auth/config/scopes.rb
+- lib/padlock_auth/errors.rb
+- lib/padlock_auth/http/error_response.rb
+- lib/padlock_auth/http/forbidden_token_response.rb
+- lib/padlock_auth/http/invalid_token_response.rb
+- lib/padlock_auth/mixins/build_with.rb
+- lib/padlock_auth/mixins/hide_attribute.rb
+- lib/padlock_auth/rails/helpers.rb
+- lib/padlock_auth/rails/token_factory.rb
+- lib/padlock_auth/railtie.rb
+- lib/padlock_auth/rspec_support.rb
+- lib/padlock_auth/token/access_token.rb
+- lib/padlock_auth/token/strategy.rb
+- lib/padlock_auth/utils/abstract_builder.rb
+- lib/padlock_auth/version.rb
+- lib/tasks/padlock_auth_tasks.rake
+homepage: http://github.com/bmorrall/padlock_auth
+licenses:
+- MIT
+metadata:
+  homepage_uri: http://github.com/bmorrall/padlock_auth
+  source_code_uri: https://github.com/bmorrall/padlock_auth
+  changelog_uri: https://github.com/bmorrall/padlock_auth/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.17
+signing_key:
+specification_version: 4
+summary: Secure your Rails application using access tokens provided by an external
+  provider.
+test_files: []