haveapi 0.18.2 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16eef5420692ea73c7b4969ec61c7efc26c74692c7a9a403d8f664fdf2dafbf8
-  data.tar.gz: 26e5cf981901ca19dc5c0d60c5b567f2cd81e66df2cf70c5333c24b920136554
+  metadata.gz: b96b662c6e3b7319b0f2eb1c2e75ad7272f5727f5763840d9db8eaa62b83472c
+  data.tar.gz: 7c1865a1dd86d6b0a64b3856ef846f66abb10919d153ff985f020dc31270ca5b
 SHA512:
-  metadata.gz: '0876a3b9b10ad452c89a62e06fc56e29cfb6aff188e4943274adf4e4180464b90daa420e4ab0953faba1f1ae9a5df0a8a19ae0362acd7290043efefd050f8b19'
-  data.tar.gz: cddc8f6c09dea69afc3a359ab18cd947a5a338ec9413d2f16eb600fa4893c88f0cbe3e3224b9ae58ac0d3de5707b96ec0e0891162d3d0ee9c97e906bff0c8e44
+  metadata.gz: 21ec1c16ae453630a70318ea92a80cdabf85b72e1d8eb53b6c074963c1c307dadd29b1af21607181b663e594481a2a1840399336d345dccb869dea9c61d92da9
+  data.tar.gz: af8c317576b3320bc3f184552de9cd67d96fd5c91f8c8395ec290f52fe8ac9f95f67ce04ddb06aeb2395feee011384561d61629d4db4834cefe6226e06270634

data/haveapi.gemspec

@@ -18,12 +18,13 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency 'json'
   s.add_runtime_dependency 'activesupport', '>= 7.0'
   s.add_runtime_dependency 'sinatra', '~> 3.1.0'
+  s.add_runtime_dependency 'sinatra-contrib', '~> 3.1.0'
   s.add_runtime_dependency 'tilt', '~> 2.3.0'
   s.add_runtime_dependency 'redcarpet', '~> 3.6'
   s.add_runtime_dependency 'rake'
   s.add_runtime_dependency 'github-markdown'
   s.add_runtime_dependency 'nesty', '~> 1.0'
-  s.add_runtime_dependency 'haveapi-client', '~> 0.18.2'
+  s.add_runtime_dependency 'haveapi-client', '~> 0.19.0'
   s.add_runtime_dependency 'mail'
   s.add_runtime_dependency 'rack-oauth2', '~> 2.2.0'
 end

data/lib/haveapi/action.rb

@@ -16,6 +16,18 @@ module HaveAPI
 
     include Hookable
 
+    has_hook :pre_authorize,
+      desc: 'Called to provide additional authorization blocks. These blocks are '+
+            'called before action\'s own authorization block. Note that if any '+
+            'of the blocks uses allow/deny rule, it will be the final authorization '+
+            'decision and even action\'s own authorization block will not be called.',
+      args: {
+        context: 'HaveAPI::Context instance',
+      },
+      ret: {
+        blocks: 'array of authorization blocks',
+      }
+
     has_hook :exec_exception,
         desc: 'Called when unhandled exceptions occurs during Action.exec',
         args: {
@@ -207,7 +219,10 @@ module HaveAPI
       def describe(context)
         authorization = (@authorization && @authorization.clone) || Authorization.new
 
-        return false if (context.endpoint || context.current_user) && !authorization.authorized?(context.current_user)
+        if (context.endpoint || context.current_user) \
+            && !authorization.authorized?(context.current_user, context.path_params_from_args)
+          return false
+        end
 
         route_method = context.action.http_method.to_s.upcase
         context.authorization = authorization
@@ -223,17 +238,18 @@ module HaveAPI
         end
 
         {
-            auth: @auth,
-            description: @desc,
-            aliases: @aliases,
-            blocking: @blocking ? true : false,
-            input: @input ? @input.describe(context) : {parameters: {}},
-            output: @output ? @output.describe(context) : {parameters: {}},
-            meta: @meta ? @meta.merge(@meta) { |_, v| v && v.describe(context) } : nil,
-            examples: @examples ? @examples.describe(context) : [],
-            path: context.resolved_path,
-            method: route_method,
-            help: "#{context.path}?method=#{route_method}"
+          auth: @auth,
+          description: @desc,
+          aliases: @aliases,
+          blocking: @blocking ? true : false,
+          input: @input ? @input.describe(context) : {parameters: {}},
+          output: @output ? @output.describe(context) : {parameters: {}},
+          meta: @meta ? @meta.merge(@meta) { |_, v| v && v.describe(context) } : nil,
+          examples: @examples ? @examples.describe(context) : [],
+          scope: context.action_scope,
+          path: context.resolved_path,
+          method: route_method,
+          help: "#{context.path}?method=#{route_method}",
         }
       end
 
@@ -291,6 +307,17 @@ module HaveAPI
       else
         @authorization = Authorization.new {}
       end
+
+      ret = call_class_hooks_as_for(
+        Action,
+        :pre_authorize,
+        args: [@context],
+        initial: {blocks: []},
+      )
+
+      ret[:blocks].reverse_each do |block|
+        @authorization.prepend_block(block)
+      end
     end
 
     def validate!
@@ -303,7 +330,7 @@ module HaveAPI
 
     def authorized?(user)
       @current_user = user
-      @authorization.authorized?(user)
+      @authorization.authorized?(user, extract_path_params)
     end
 
     def current_user
@@ -412,9 +439,9 @@ module HaveAPI
             when :object
               out = adapter.output(@context, ret)
               safe_ret = @authorization.filter_output(
-                  out_params,
-                  out,
-                  true
+                out_params,
+                out,
+                true
               )
               @reply_meta[:global].update(out.meta)
 
@@ -425,27 +452,27 @@ module HaveAPI
                 out = adapter.output(@context, obj)
 
                 safe_ret << @authorization.filter_output(
-                    out_params,
-                    out,
-                    true
+                  out_params,
+                  out,
+                  true
                 )
                 safe_ret.last.update({Metadata.namespace => out.meta}) unless meta[:no]
               end
 
             when :hash
               safe_ret = @authorization.filter_output(
-                  out_params,
-                  adapter.output(@context, ret),
-                  true
+                out_params,
+                adapter.output(@context, ret),
+                true
               )
 
             when :hash_list
               safe_ret = ret
               safe_ret.map! do |hash|
                 @authorization.filter_output(
-                    out_params,
-                    adapter.output(@context, hash),
-                    true
+                  out_params,
+                  adapter.output(@context, hash),
+                  true
                 )
               end
 
@@ -574,14 +601,16 @@ module HaveAPI
           when :object_list, :hash_list
             @safe_params[input.namespace].map! do |obj|
               @authorization.filter_input(
-                  self.class.input.params,
-                  self.class.model_adapter(self.class.input.layout).input(obj))
+                self.class.input.params,
+                self.class.model_adapter(self.class.input.layout).input(obj)
+              )
             end
 
           else
             @safe_params[input.namespace] = @authorization.filter_input(
-                self.class.input.params,
-                self.class.model_adapter(self.class.input.layout).input(@safe_params[input.namespace]))
+              self.class.input.params,
+              self.class.model_adapter(self.class.input.layout).input(@safe_params[input.namespace])
+            )
         end
 
         # Now check required params, convert types and set defaults
@@ -605,8 +634,8 @@ module HaveAPI
           next unless params
 
           raw_meta = auth.filter_input(
-              meta.input.params,
-              self.class.model_adapter(meta.input.layout).input(params)
+            meta.input.params,
+            self.class.model_adapter(meta.input.layout).input(params)
           )
 
           break if raw_meta
@@ -617,5 +646,17 @@ module HaveAPI
         @metadata.update(meta.input.validate(raw_meta))
       end
     end
+
+    # @return <Hash<Symbol, String>> path parameters and their values
+    def extract_path_params
+      ret = {}
+
+      @context.path.scan(/\{([a-zA-Z\-_]+)\}/) do |match|
+        path_param = match.first
+        ret[path_param] = @params[path_param]
+      end
+
+      ret
+    end
   end
 end

data/lib/haveapi/authentication/base.rb

@@ -39,7 +39,7 @@ module HaveAPI
       end
 
       # Reimplement this method in your authentication provider.
-      # +request+ is passed directly from Sinatra.
+      # `request` is passed directly from Sinatra.
       def authenticate(request)
 
       end

data/lib/haveapi/authentication/basic/provider.rb

@@ -36,8 +36,8 @@ module HaveAPI::Authentication
 
       def describe
         {
-            description: "Authentication using HTTP basic. Username and password is passed "+
-                         "via HTTP header. Its use is forbidden from web browsers."
+          description: "Authentication using HTTP basic. Username and password is passed "+
+                       "via HTTP header. Its use is forbidden from web browsers."
         }
       end
 

data/lib/haveapi/authentication/chain.rb

@@ -31,7 +31,7 @@ module HaveAPI::Authentication
       # end
     end
 
-    # Iterate through authentication providers registered for version +v+
+    # Iterate through authentication providers registered for version `v`
     # until authentication is successful or the end is reached and user
     # is not authenticated.
     # Authentication provider can deny the user access by calling Base#deny.
@@ -68,7 +68,7 @@ module HaveAPI::Authentication
       ret
     end
 
-    # Return provider list for version +v+.
+    # Return provider list for version `v`.
     # Used for registering providers to specific version, e.g.
     #   api.auth_chain[1] << MyAuthProvider
     def [](v)
@@ -76,8 +76,8 @@ module HaveAPI::Authentication
       @chain[v]
     end
 
-    # Register authentication +provider+ for all available API versions.
-    # +provider+ may also be an Array of providers.
+    # Register authentication `provider` for all available API versions.
+    # `provider` may also be an Array of providers.
     def <<(provider)
       @chain[:all] ||= []
 

data/lib/haveapi/authentication/oauth2/config.rb

@@ -6,7 +6,7 @@ module HaveAPI::Authentication
     # The created provider can then be added to authentication chain.
     #
     # In general, it is up to the implementation to provide the authentication flow
-    # -- render HTML page in {#render_authorize_page} and then process it in
+    # -- render HTML page in {#handle_get_authorize} and then process it in
     # {#handle_post_authorize}. The implementation must also handle generation
     # of all needed tokens, their persistence and validity checking.
     class Config
@@ -16,36 +16,39 @@ module HaveAPI::Authentication
         @version = v
       end
 
-      # Render authorization page
+      # Handle GET authorize requests
       #
-      # This method can be called on both GET and POST requests, e.g. if the user
-      # provided incorrect credentials or if there are multiple authentication
-      # steps.
+      # This method usually writes HTML to `oauth2_response`, you must also set
+      # content type.
       #
-      # It should return full HTML page that will be sent to the user. The page
-      # usually contains a login form.
-      #
-      # @param oauth2_request [Rack::OAuth2::Server::Authorize::Request]
+      # @param sinatra_handler [Object]
+      # @param sinatra_request [Sinatra::Request]
       # @param sinatra_params [Hash] request params
+      # @param oauth2_request [Rack::OAuth2::Server::Authorize::Request]
+      # @param oauth2_response [Rack::OAuth2::Server::Authorize::Response]
       # @param client [Client]
-      # @param auth_result [AuthResult, nil]
-      # @return [String] HTML
-      def render_authorize_page(oauth2_request, sinatra_params, client, auth_result: nil)
+      # @return [AuthResult, nil]
+      def handle_get_authorize(sinatra_handler:, sinatra_request:, sinatra_params:, oauth2_request:, oauth2_response:, client:)
 
       end
 
-      # Handle POST requests made from {#render_authorize_page}
+      # Handle POST authorize requests
       #
       # Process form data and return {AuthResult} or nil. When nil is returned
       # the authorization process is aborted and the user is redirected back
       # to the client.
       #
+      # If the authentication is incomplete, this method must also write output
+      # to `oauth2_response`, usually HTML. Content type must be set.
+      #
+      # @param sinatra_handler [Object]
       # @param sinatra_request [Sinatra::Request]
       # @param sinatra_params [Hash] request params
       # @param oauth2_request [Rack::OAuth2::Server::Authorize::Request]
+      # @param oauth2_response [Rack::OAuth2::Server::Authorize::Response]
       # @param client [Client]
       # @return [AuthResult, nil]
-      def handle_post_authorize(sinatra_request, sinatra_params, oauth2_request, client)
+      def handle_post_authorize(sinatra_handler:, sinatra_request:, sinatra_params:, oauth2_request:, oauth2_response:, client:)
 
       end
 
@@ -86,6 +89,19 @@ module HaveAPI::Authentication
 
       end
 
+      # Revoke access or refresh token
+      #
+      # Note that even if the token is not found, this method should return
+      # `:revoked`.
+      #
+      # @param sinatra_request [Sinatra::Request]
+      # @param token [String]
+      # @param token_type_hint [nil, 'access_token', 'refresh_token']
+      # @return [:revoked, :unsupported]
+      def handle_post_revoke(sinatra_request, token, token_type_hint: nil)
+
+      end
+
       # Find client by ID
       # @param client_id [String]
       # @return [Client, nil]
@@ -117,12 +133,34 @@ module HaveAPI::Authentication
 
       end
 
+      # Base URL of the authorization server, including protocol
+      #
+      # This should in general be the same URL at which your API is located.
+      # It can be useful if you wish to have a separate domain for authentication.
+      #
+      # Example: `https://api.domain.tld`
+      #
+      # @return [String]
+      def base_url
+        raise NotImplementedError
+      end
+
       # Path to the authorization endpoint on this API
       # @return [String]
       def authorize_path
         @provider.authorize_path
       end
 
+      # Custom HTTP header that is searched for the access token
+      #
+      # The authorization header is not feasible from web browsers, so we optionally
+      # use our own header for the purpose.
+      #
+      # @return [String]
+      def http_header
+        'X-HaveAPI-OAuth2-Token'
+      end
+
       # Parameters needed for the authorization process
       #
       # Use these in {#render_authorization_page}, put them e.g. in hidden form

data/lib/haveapi/authentication/oauth2/provider.rb

@@ -78,9 +78,21 @@ module HaveAPI::Authentication
         super(server, v)
       end
 
+      def setup
+        @server.allow_header(config.http_header)
+      end
+
       def register_routes(sinatra, prefix)
         @authorize_path = File.join(prefix, 'authorize')
         @token_path = File.join(prefix, 'token')
+        @revoke_path = File.join(prefix, 'revoke')
+
+        base_url = config.base_url
+
+        @authorize_url = File.join(base_url, @authorize_path)
+        @token_url = File.join(base_url, @token_path)
+        @revoke_url = File.join(base_url, @revoke_path)
+
         that = self
 
         sinatra.get @authorize_path do
@@ -94,12 +106,17 @@ module HaveAPI::Authentication
         sinatra.post @token_path do
           that.token_endpoint(self).call(request.env)
         end
+
+        sinatra.post @revoke_path do
+          that.revoke_endpoint(self).call(request.env)
+        end
       end
 
       def authenticate(request)
         tokens = [
           request['access_token'],
-          token_from_header(request)
+          token_from_authorization_header(request),
+          token_from_haveapi_header(request),
         ].compact
 
         token =
@@ -115,7 +132,7 @@ module HaveAPI::Authentication
         token && config.find_user_by_access_token(request, token)
       end
 
-      def token_from_header(request)
+      def token_from_authorization_header(request)
         auth_header = Rack::Auth::AbstractRequest.new(request.env)
 
         if auth_header.provided? && !auth_header.parts.first.nil? && auth_header.scheme.to_s == 'bearer'
@@ -125,22 +142,36 @@ module HaveAPI::Authentication
         end
       end
 
+      def token_from_haveapi_header(request)
+        request.env[header_to_env(config.http_header)]
+      end
+
       def describe
         desc = <<-END
-        OAuth2 authorization provider. While OAuth2 is not supported by HaveAPI
-        clients, it is possible to use your API as an authentication source.
+        OAuth2 authorization provider. While OAuth2 support in HaveAPI clients
+        is limited, it is possible to use your API as an authentication source
+        and to use OAuth2 tokens to access the API.
 
         HaveAPI partially implements RFC 6749: authorization response type "code"
         and token grant types "authorization_code" and "refresh_token". Other
         response and grant types are not supported at this time.
 
-        The access token can be passed as bearer token according to RFC 6750.
+        The access token can be passed as bearer token according to RFC 6750,
+        or using a custom HTTP header when the Authorization header is not
+        practical.
+
+        The access and refresh tokens can be revoked as per RFC 7009.
         END
 
         {
           description: desc,
+          http_header: config.http_header,
+          authorize_url: @authorize_url,
           authorize_path: @authorize_path,
+          token_url: @token_url,
           token_path: @token_path,
+          revoke_url: @revoke_url,
+          revoke_path: @revoke_path,
         }
       end
 
@@ -152,7 +183,14 @@ module HaveAPI::Authentication
           res.redirect_uri = req.verify_redirect_uri!(client.redirect_uri)
 
           if req.post?
-            auth_res = config.handle_post_authorize(handler.request, handler.params, req, client)
+            auth_res = config.handle_post_authorize(
+              sinatra_handler: handler,
+              sinatra_request: handler.request,
+              sinatra_params: handler.params,
+              oauth2_request: req,
+              oauth2_response: res,
+              client:,
+            )
 
             if auth_res.nil?
               # Authentication failed
@@ -170,18 +208,33 @@ module HaveAPI::Authentication
               end
 
               res.approve!
-            elsif auth_res.authenticated && !auth_res.complete
-              # Continue with another authentication step
-              res.content_type = 'text/html'
-              res.write(config.render_authorize_page(req, handler.params, client, auth_result: auth_res))
-            else
-              # Authentication failed, report errors and let the user retry
-              res.content_type = 'text/html'
-              res.write(config.render_authorize_page(req, handler.params, client, auth_result: auth_res))
             end
           else
-            res.content_type = 'text/html'
-            res.write(config.render_authorize_page(req, handler.params, client))
+            auth_res = config.handle_get_authorize(
+              sinatra_handler: handler,
+              sinatra_request: handler.request,
+              sinatra_params: handler.params,
+              oauth2_request: req,
+              oauth2_response: res,
+              client:,
+            )
+
+            if auth_res.nil?
+              # We expect `config.handle_get_authorize` has sent response body
+            elsif auth_res.cancel
+              # Cancel the process
+              req.access_denied!
+            elsif auth_res.authenticated && auth_res.complete
+              # Authentication was successful
+              case req.response_type
+              when :code
+                res.code = config.get_authorization_code(auth_res)
+              when :token
+                req.unsupported_response_type!
+              end
+
+              res.approve!
+            end
           end
         end
       end
@@ -223,7 +276,11 @@ module HaveAPI::Authentication
               req.unsupported_grant_type!
 
             when :refresh_token
-              config.find_authorization_by_refresh_token(client, req.refresh_token)
+              authorization = config.find_authorization_by_refresh_token(client, req.refresh_token)
+
+              if authorization.nil?
+                req.invalid_grant!
+              end
 
               access_token, expires_at, refresh_token = config.refresh_tokens(authorization, handler.request)
 
@@ -239,6 +296,30 @@ module HaveAPI::Authentication
             end
         end
       end
+
+      def revoke_endpoint(handler)
+        RevokeEndpoint.new do |req, res|
+          ret = config.handle_post_revoke(
+            handler.request,
+            req.token,
+            token_type_hint: req.token_type_hint,
+          )
+
+          case ret
+          when :revoked
+            # ok
+          when :unsupported
+            req.unsupported_token_type!
+          else
+            raise Rack::OAuth2::Server::Abstract::ServerError
+          end
+        end
+      end
+
+      private
+      def header_to_env(header)
+        "HTTP_#{header.upcase.gsub(/\-/, '_')}"
+      end
     end
   end
 end

data/lib/haveapi/authentication/oauth2/revoke_endpoint.rb

@@ -0,0 +1,36 @@
+require 'rack/oauth2'
+
+module HaveAPI::Authentication
+  module OAuth2
+    class RevokeEndpoint < Rack::OAuth2::Server::Abstract::Handler
+      def _call(env)
+        @request  = Request.new(env)
+        @response = Response.new(request)
+        super
+      end
+
+      class Request < Rack::OAuth2::Server::Abstract::Request
+        attr_required :token
+        attr_optional :token_type_hint
+
+        def initialize(env)
+          super
+          @token = params['token']
+          @token_type_hint = params['token_type_hint']
+        end
+
+        def unsupported_token_type!(description = nil, options = {})
+          raise Rack::OAuth2::Server::Abstract::BadRequest.new(
+            :unsupported_token_type,
+            description,
+            options,
+          )
+        end
+      end
+
+      class Response < Rack::OAuth2::Server::Abstract::Response
+
+      end
+    end
+  end
+end

data/lib/haveapi/authentication/token/config.rb

@@ -75,6 +75,7 @@ module HaveAPI::Authentication
             input do
               string :user, label: 'User', required: true
               password :password, label: 'Password', required: true
+              string :scope, label: 'Scope', default: 'all', fill: true
             end
 
             handle do

data/lib/haveapi/authorization.rb

@@ -1,20 +1,27 @@
 module HaveAPI
   class Authorization
     def initialize(&block)
-      @block = block
+      @blocks = [block]
     end
 
     # Returns true if user is authorized.
     # Block must call allow to authorize user, default rule is deny.
-    def authorized?(user)
+    def authorized?(user, path_params)
       @restrict = []
 
       catch(:rule) do
-        instance_exec(user, &@block) if @block
-        deny # will not be called if block throws allow
+        @blocks.each do |block|
+          instance_exec(user, path_params, &block)
+        end
+
+        deny # will not be called if some block throws allow
       end
     end
 
+    def prepend_block(block)
+      @blocks.insert(0, block)
+    end
+
     # Apply restrictions on query which selects objects from database.
     # Most common usage is restrict user to access only objects he owns.
     def restrict(**kwargs)
@@ -22,22 +29,22 @@ module HaveAPI
     end
 
     # Restrict parameters client can set/change.
-    # [whitelist]  allow only listed parameters
-    # [blacklist]  allow all parameters except listed ones
+    # @param whitelist [Array<Symbol>] allow only listed parameters
+    # @param blacklist [Array<Symbol>] allow all parameters except listed ones
     def input(whitelist: nil, blacklist: nil)
       @input = {
-          whitelist: whitelist,
-          blacklist: blacklist,
+        whitelist: whitelist,
+        blacklist: blacklist,
       }
     end
 
     # Restrict parameters client can retrieve.
-    # [whitelist]  allow only listed parameters
-    # [blacklist]  allow all parameters except listed ones
+    # @param whitelist [Array<Symbol>] allow only listed parameters
+    # @param blacklist [Array<Symbol>] allow all parameters except listed ones
     def output(whitelist: nil, blacklist: nil)
       @output = {
-          whitelist: whitelist,
-          blacklist: blacklist,
+        whitelist: whitelist,
+        blacklist: blacklist,
       }
     end