steppe 0.1.0

data/lib/steppe/auth/basic.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Steppe
+  module Auth
+    # HTTP Basic authentication security scheme.
+    # Validates username and password credentials from the Authorization header against a credentials store.
+    #
+    # @example Using a simple hash store
+    #   store = {
+    #     'joe' => 'secret123',
+    #     'anna' => 'password456'
+    #   }
+    #   basic_auth = Steppe::Auth::Basic.new('my_auth', store: store)
+    #
+    #   # In a service definition:
+    #   api.security_scheme basic_auth
+    #
+    #   # Or use the shortcut
+    #   api.basic_auth 'my_auth', store: { 'joe' => 'secret123' }
+    #
+    #   # Then in an endpoint in the service:
+    #   e.security 'my_auth'
+    #
+    # @example Using a custom credentials store
+    #   class DatabaseCredentialsStore
+    #     def lookup(username)
+    #       user = User.find_by(username: username)
+    #       user&.password_digest
+    #     end
+    #   end
+    #
+    #   store = DatabaseCredentialsStore.new
+    #   api.basic_auth 'my_auth', store: store
+    #
+    class Basic
+      include Responses
+
+      SCHEME = 'basic'
+      EXP = /^Basic\s+([A-Za-z0-9+\/=]+)\s*$/
+
+      # Interface for custom credentials store implementations.
+      # Required methods:
+      # - lookup(username): Returns the password for the given username, or nil if not found
+      CredentialsStoreInterface = Types::Interface[:lookup]
+
+      # Simple hash-based credentials store implementation.
+      # Stores username/password pairs in memory.
+      #
+      # @example
+      #   store = SimpleUserPasswordStore.new({
+      #     'joe' => 'secret123',
+      #     'anna' => 'password456'
+      #   })
+      class SimpleUserPasswordStore
+        # Interface for hash-based credentials stores (Hash[String => String]).
+        # Maps username strings to password strings.
+        HashInterface = Types::Hash[String, String]
+
+        # @param hash [Hash] Hash mapping usernames to passwords
+        def initialize(hash)
+          @lookup = hash
+        end
+
+        # Retrieve a password by username.
+        #
+        # @param username [String] The username to look up
+        # @return [String, nil] The password or nil if not found
+        def lookup(username) = @lookup[username.strip]
+      end
+
+      attr_reader :name
+
+      # @param name [String] The security scheme name (used in OpenAPI)
+      # @param store [CredentialsStoreInterface] Credentials store for validating username/password pairs
+      def initialize(name, store:)
+        @name = name
+        @scheme = SCHEME
+        @store = case store
+        when SimpleUserPasswordStore::HashInterface
+          SimpleUserPasswordStore.new(store)
+        when CredentialsStoreInterface
+          store
+        else
+          raise ArgumentError, "expected a CredentialsStoreInterface interface #{CredentialsStoreInterface}, but got #{store.inspect}"
+        end
+      end
+
+      # Handle authentication for a connection.
+      # Validates the Basic credentials from the Authorization header and checks username/password match.
+      #
+      # @param conn [Steppe::Result] The connection/result object
+      # @param _required_scopes [nil] Unused parameter (Basic auth does not support scopes)
+      # @return [Steppe::Result::Continue, Steppe::Result::Halt] The connection, or halted with 401/403 status
+      def handle(conn, _required_scopes = nil)
+        auth_str = conn.request.env[HTTP_AUTHORIZATION]
+        return unauthorized(conn) if auth_str.nil?
+
+        match = auth_str.match(EXP)
+        return unauthorized(conn) if match.nil?
+
+        username, password = decode(match[1])
+        return forbidden(conn) if @store.lookup(username) != password
+
+        conn
+      end
+
+      # Convert this security scheme to OpenAPI 3.0 format.
+      #
+      # @return [Hash] OpenAPI security scheme object
+      def to_openapi
+        {
+          'type' => 'http',
+          'scheme' => scheme
+        }
+      end
+
+      private
+
+      attr_reader :scheme
+
+      # Decode Base64-encoded Basic authentication credentials.
+      #
+      # @param auth_str [String] The Base64-encoded credentials string
+      # @return [Array<String>] Array containing [username, password]
+      def decode(auth_str)
+        auth_str.to_s.unpack1('m').split(':', 2)
+      end
+    end
+  end
+end

data/lib/steppe/auth/bearer.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Steppe
+  module Auth
+    # HTTP Bearer token authentication security scheme.
+    # Validates Bearer tokens from the Authorization header and checks permissions against a token store.
+    #
+    # @example
+    #   store = Steppe::Auth::HashTokenStore.new({
+    #     'token123' => ['read:users', 'write:users']
+    #   })
+    #   bearer = Steppe::Auth::Bearer.new('my_auth', store: store)
+    #
+    #   # In a service definition:
+    #   api.security_scheme bearer
+    #
+    #   # Or use the shortcut
+    #   api.bearer_auth 'my_auth', store: { 'token123' => ['read:users'] }
+    #
+    #   # Then in an endpoint in the service:
+    #   e.security 'my_auth', ['read:users']
+    #
+    class Bearer
+      include Responses
+
+      # Interface for custom token store implementations.
+      # Required methods:
+      # - get(token): Returns an access token object or nil
+      TokenStoreInterface = Types::Interface[:get]
+
+      # Simple hash-based token store implementation.
+      # Stores tokens in memory with their associated scopes.
+      #
+      # @example
+      #   store = HashTokenStore.new({
+      #     'abc123' => ['read:users', 'write:users'],
+      #     'xyz789' => ['read:posts']
+      #   })
+      class HashTokenStore
+        # Interface for hash-based token stores (Hash[String => Array[String]]).
+        # Maps token strings to arrays of scope strings.
+        Interface = Types::Hash[String, Types::Array[String]]
+
+        # Represents an access token with associated permission scopes.
+        class AccessToken < Data.define(:scopes)
+          # Check if this token has any of the required scopes.
+          #
+          # @param required_scopes [Array<String>] Scopes to check against
+          # @return [Boolean] True if token has at least one required scope
+          def allows?(required_scopes)
+            (scopes & required_scopes).any?
+          end
+        end
+
+        # @param hash [Hash] Hash mapping token strings to scope arrays
+        def initialize(hash)
+          @lookup = hash.transform_values { |scopes| AccessToken.new(scopes) }
+        end
+
+        # Retrieve an access token by its token string.
+        #
+        # @param token [String] The token string to look up
+        # @return [AccessToken, nil] The access token or nil if not found
+        def get(token)
+          @lookup[token]
+        end
+      end
+
+      attr_reader :name, :format, :scheme, :header_schema
+
+      # Initialize a new Bearer authentication scheme.
+      #
+      # @param name [String] The security scheme name (used in OpenAPI)
+      # @param store [TokenStoreInterface] Token store for validating access tokens
+      # @param scheme [String] The authentication scheme (default: 'bearer')
+      # @param format [String, nil] Optional bearer format hint (e.g., 'JWT')
+      # @param header [String] The HTTP header to check (default: HTTP_AUTHORIZATION)
+      def initialize(name, store:, scheme: 'bearer', format: nil, header: HTTP_AUTHORIZATION)
+        @name = name
+        @store = case store
+        when HashTokenStore::Interface
+          HashTokenStore.new(store)
+        when TokenStoreInterface
+          store
+        else
+          raise ArgumentError, "expected a TokenStore interface #{TokenStoreInterface}, but got #{store.inspect}"
+        end
+
+        @format = format.to_s
+        @scheme = scheme.to_s
+        @header = header
+        # We mark the key as optional
+        # because we don't validate presence of the header and return a 422.
+        # (even though that'll most likely result in a 401 response after running #handle)
+        @header_schema = Types::Hash["#{@header}?" => String]
+        @matcher = %r{\A\s*#{Regexp.escape(@scheme)}\s+(.+?)\s*\z}i
+      end
+
+      # Convert this security scheme to OpenAPI 3.0 format.
+      #
+      # @return [Hash] OpenAPI security scheme object
+      def to_openapi
+        {
+          'type' => 'http',
+          'scheme' => scheme,
+          'bearerFormat' => format
+        }
+      end
+
+      # Handle authentication and authorization for a connection.
+      # Validates the Bearer token from the Authorization header and checks if it has required scopes.
+      #
+      # @param conn [Steppe::Result] The connection/result object
+      # @param required_scopes [Array<String>] The scopes required for this endpoint
+      # @return [Steppe::Result::Continue, Steppe::Result::Halt] The connection, or halted with 401/403 status
+      def handle(conn, required_scopes)
+        header_value = conn.request.get_header(@header).to_s.strip
+        return unauthorized(conn) if header_value.empty?
+
+        token = header_value[@matcher, 1]
+        return unauthorized(conn) if token.nil?
+
+        access_token = @store.get(token)
+        return forbidden(conn) unless access_token&.allows?(required_scopes)
+
+        conn
+      end
+    end
+  end
+end

data/lib/steppe/auth.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Steppe
+  # Authentication and authorization module for Steppe endpoints.
+  # Provides security schemes for protecting API endpoints and validating access tokens.
+  # Implements common security schemes supported by OpenAPI spec
+  # @see https://swagger.io/docs/specification/v3_0/authentication/
+  module Auth
+    WWW_AUTHENTICATE = 'www-authenticate'
+    HTTP_AUTHORIZATION = 'HTTP_AUTHORIZATION'
+
+    # Interface that security schemes must implement.
+    # Required methods:
+    # - name: Returns the security scheme name
+    # - handle: Processes authentication/authorization for a connection
+    SecuritySchemeInterface = Types::Interface[
+      :name,
+      :handle,
+      :to_openapi
+    ]
+  end
+
+  module Responses
+    private
+
+    def unauthorized(conn)
+      conn.response.add_header(Auth::WWW_AUTHENTICATE, %(#{scheme.capitalize} realm="#{name}"))
+      conn.respond_with(401).halt
+    end
+
+    def forbidden(conn)
+      conn.respond_with(403).halt
+    end
+
+    def name
+      raise NotImplementedError
+    end
+
+    def scheme
+      raise NotImplementedError
+    end
+  end
+end
+
+require 'steppe/auth/bearer'
+require 'steppe/auth/basic'

data/lib/steppe/content_type.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'rack/mime'
+
+module Steppe
+  class ContentType
+    TOKEN = /[!#$%&'*+\-.^_`|~0-9A-Z]+/i
+    MIME_TYPE = /(?<type>#{TOKEN})\/(?<subtype>#{TOKEN})/
+    QUOTED_STRING = /"(?:\\.|[^"\\])*"/
+    PARAMETER = /\s*;\s*(?<key>#{TOKEN})=(?<value>#{TOKEN}|#{QUOTED_STRING})/
+
+    def self.parse(str)
+      return str if str.is_a?(ContentType)
+
+      if str.is_a?(Symbol)
+        str = Rack::Mime.mime_type(".#{str}")
+      end
+
+      m = MIME_TYPE.match(str) or
+      raise ArgumentError, "invalid content type: #{str.inspect}"
+
+      params = {}
+      str.scan(PARAMETER) do
+        key, value = Regexp.last_match.values_at(:key, :value)
+        value = value[1..-2] if value&.start_with?('"') # unquote
+        params[key.downcase] = value
+      end
+
+      new(m[:type], m[:subtype], params)
+    end
+
+    def self.parse_accept(header)
+      header.split(/\s*,\s*/).map do |entry|
+        # Match the MIME type part
+        m = MIME_TYPE.match(entry)
+        next unless m
+
+        params = {}
+        # Iterate over all parameters
+        entry.scan(PARAMETER) do |match|
+          key, value = Regexp.last_match.values_at(:key, :value)
+          # Remove quotes if quoted
+          value = value[1..-2] if value&.start_with?('"')
+          params[key.downcase] = value
+        end
+
+        new(m[:type], m[:subtype], params)
+      end.compact.sort_by { |ct| -ct.quality }
+    end
+
+    attr_reader :type, :subtype, :params, :media_type
+
+    def initialize(type, subtype, params)
+      @type = type.downcase
+      @subtype = subtype.downcase
+      @params = params
+      @media_type = "#{type}/#{subtype}"
+      freeze
+    end
+
+    def qualified? = !(type == '*' && subtype == '*')
+
+    def to_s
+      param_str = params.map { |k, v| "#{k}=#{v}" }.join('; ')
+      [ media_type, param_str ].reject(&:empty?).join('; ')
+    end
+
+    def ==(other)
+      other.is_a?(ContentType) &&
+        type == other.type &&
+        subtype == other.subtype &&
+        params == other.params
+    end
+
+    alias eql? ==
+    def hash = [type, subtype, params].hash
+
+    def quality = params.fetch('q', 1.0).to_f
+  end
+end