authlete_ruby_test 0.0.1.beta

data/lib/authlete/introspection.rb

@@ -0,0 +1,540 @@
+# Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+
+# typed: true
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/multipart'
+require 'faraday/retry'
+require 'sorbet-runtime'
+require_relative 'sdk_hooks/hooks'
+require_relative 'utils/retries'
+
+module Authlete
+  extend T::Sig
+  class Introspection
+    extend T::Sig
+    
+
+
+    sig { params(sdk_config: SDKConfiguration).void }
+    def initialize(sdk_config)
+      @sdk_configuration = sdk_config
+      
+    end
+
+    sig { params(base_url: String, url_variables: T.nilable(T::Hash[Symbol, T.any(String, T::Enum)])).returns(String) }
+    def get_url(base_url:, url_variables: nil)
+      sd_base_url, sd_options = @sdk_configuration.get_server_details
+
+      if base_url.nil?
+        base_url = sd_base_url
+      end
+
+      if url_variables.nil?
+        url_variables = sd_options
+      end
+
+      return Utils.template_url base_url, url_variables
+    end
+
+
+    sig { params(introspection_request: Models::Components::IntrospectionRequest, service_id: ::String, timeout_ms: T.nilable(Integer)).returns(Models::Operations::AuthIntrospectionApiResponse) }
+    def process_request(introspection_request:, service_id:, timeout_ms: nil)
+      # process_request - Process Introspection Request
+      # This API gathers information about an access token.
+      # ### Description
+      # This API is supposed to be called from within the implementations of protected resource endpoints
+      # of the authorization server implementation in order to get information about the access token which
+      # was presented by the client application.
+      # In general, a client application accesses a protected resource endpoint of a service with an access
+      # token, and the implementation of the endpoint checks whether the presented access token has enough
+      # privileges (= scopes) to access the protected resource before returning the protected resource to
+      # the client application. To achieve this flow, the endpoint implementation has to know detailed
+      # information about the access token. Authlete `/auth/introspection` API can be used to get such information.
+      # The response from `/auth/introspection` API has some parameters. Among them, it is `action` parameter
+      # that the authorization server implementation should check first because it denotes the next action
+      # that the authorization server implementation should take. According to the value of `action`, the
+      # authorization server implementation must take the steps described below.
+      # **INTERNAL\_SERVER\_ERROR**
+      # When the value of `action` is `INTERNAL\_SERVER\_ERROR`, it means that the request from the authorization
+      # server implementation was wrong or that an error occurred in Authlete.
+      # In either case, from the viewpoint of the client application, it is an error on the server side.
+      # Therefore, the service implementation should generate a response to the client application with
+      # HTTP status of "500 Internal Server Error". Authlete recommends `application/json` as the content
+      # type although OAuth 2.0 specification does not mention the format of the error response when the
+      # redirect URI is not usable.
+      # The value of `responseContent` is a string which describes the error in the format of
+      # [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage), so if
+      # the protected resource of the service implementation wants to return an error response to the client
+      # application in the way that complies with RFC 6750 (in other words, if `accessTokenType` configuration
+      # parameter of the service is Bearer), the value of `responseContent` can be used as the value of
+      # `WWW-Authenticate` header.
+      # The following is an example response which complies with RFC 6750.
+      # ```
+      # HTTP/1.1 500 Internal Server Error
+      # Content-Type: application/json
+      # Cache-Control: no-store
+      # Pragma: no-cache
+      # {responseContent}
+      # ```
+      # **BAD\_REQUEST**
+      # When the value of `action` is `BAD\_REQUEST`, it means that the request from the client application
+      # does not contain an access token (= the request from the authorization server implementation to
+      # Authlete does not contain `token` request parameter).
+      # A response with HTTP status of "400 Bad Request" must be returned to the client application and
+      # the content type must be `application/json`.
+      # The value of `responseContent` is a string which describes the error in the format of [RFC
+      # 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage), so if the
+      # protected resource of the service implementation wants to return an error response to the client
+      # application in the way that complies with RFC 6750 (in other words, if `accessTokenType` configuration
+      # parameter of the service is `Bearer`), the value of `responseContent` can be used as the value of
+      # `WWW-Authenticate` header.
+      # The following is an example response which complies with RFC 6750.
+      # ```
+      # HTTP/1.1 400 Bad Request
+      # WWW-Authenticate: {responseContent}
+      # Cache-Control: no-store
+      # Pragma: no-cache
+      # ```
+      # **UNAUTHORIZED**
+      # When the value of `action` is `UNAUTHORIZED`, it means that the access token does not exist or has
+      # expired.
+      # The value of `responseContent` is a string which describes the error in the format of RFC
+      # 6750 (OAuth 2.0 Bearer Token Usage), so if the protected resource of the service implementation
+      # wants to return an error response to the client application in the way that complies with [RFC
+      # 6750](https://datatracker.ietf.org/doc/html/rfc6750) (in other words, if `accessTokenType` configuration
+      # parameter of the service is `Bearer`), the value of `responseContent` can be used as the value of
+      # `WWW-Authenticate` header.
+      # The following is an example response which complies with RFC 6750.
+      # ```
+      # HTTP/1.1 401 Unauthorized
+      # WWW-Authenticate: {responseContent}
+      # Cache-Control: no-store
+      # Pragma: no-cache
+      # ```
+      # **FORBIDDEN**
+      # When the value of `action` is `FORBIDDEN`, it means that the access token does not cover the required
+      # scopes or that the subject associated with the access token is different from the subject contained
+      # in the request.
+      # A response with HTTP status of "400 Bad Request" must be returned to the client application and
+      # the content type must be `application/json`.
+      # The value of `responseContent` is a string which describes the error in the format of [RFC
+      # 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage), so if the
+      # protected resource of the service implementation wants to return an error response to the client
+      # application in the way that complies with RFC 6750 (in other words, if `accessTokenType` configuration
+      # parameter of the service is Bearer), the value of `responseContent` can be used as the value of
+      # `WWW-Authenticate` header.
+      # The following is an example response which complies with RFC 6750.
+      # ```
+      # HTTP/1.1 403 Forbidden
+      # WWW-Authenticate: {responseContent}
+      # Cache-Control: no-store
+      # Pragma: no-cache
+      # ```
+      # **OK**
+      # When the value of `action` is `OK`, it means that the access token which the client application
+      # presented is valid (= exists and has not expired).
+      # The implementation of the protected resource endpoint is supposed to return the protected resource
+      # to the client application.
+      # When action is `OK`, the value of `responseContent` is `"Bearer error=\"invalid\_request\""`. This
+      # is the simplest string which can be used as the value of `WWW-Authenticate` header to indicate
+      # "400 Bad Request". The implementation of the protected resource endpoint may use this string to
+      # tell the client application that the request was bad (e.g. in case necessary request parameters
+      # for the protected resource endpoint are missing). However, in such a case, the implementation
+      # should generate a more informative error message to help developers of client applications.
+      # The following is an example error response which complies with RFC 6750.
+      # ```
+      # HTTP/1.1 400 Bad Request
+      # WWW-Authenticate: {responseContent}
+      # Cache-Control: no-store
+      # Pragma: no-cache
+      # ```
+      # Basically, The value of `responseContent` is a string which describes the error in the format of
+      # [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) (OAuth 2.0 Bearer Token Usage). So, if
+      # the service has selected `Bearer` as the value of `accessTokenType` configuration parameter, the
+      # value of `responseContent` can be used directly as the value of `WWW-Authenticate` header. However,
+      # if the service has selected another different token type, the service has to generate error messages
+      # for itself.
+      # \_**JWT-based access token**\_
+      # Since version 2.1, Authlete provides a feature to issue access tokens in JWT format. This feature
+      # can be enabled by setting a non-null value to the `accessTokenSignAlg` property of the service
+      # (see the description of the Service class for details). `/api/auth/introspection` API can accept
+      # access tokens in JWT format. However, note that the API does not return information contained in
+      # a given JWT-based access token but returns information stored in the database record which corresponds
+      # to the given JWT-based access token. Because attributes of the database record can be modified
+      # after the access token is issued (for example, by using `/api/auth/token/update` API), information
+      # returned by `/api/auth/introspection` API and information the given JWT-based access token holds
+      # may be different.
+      # 
+      request = Models::Operations::AuthIntrospectionApiRequest.new(
+        service_id: service_id,
+        introspection_request: introspection_request
+      )
+      url, params = @sdk_configuration.get_server_details
+      base_url = Utils.template_url(url, params)
+      url = Utils.generate_url(
+        Models::Operations::AuthIntrospectionApiRequest,
+        base_url,
+        '/api/{serviceId}/auth/introspection',
+        request
+      )
+      headers = {}
+      headers = T.cast(headers, T::Hash[String, String])
+      req_content_type, data, form = Utils.serialize_request_body(request, false, false, :introspection_request, :json)
+      headers['content-type'] = req_content_type
+      raise StandardError, 'request body is required' if data.nil? && form.nil?
+
+      if form
+        body = Utils.encode_form(form)
+      elsif Utils.match_content_type(req_content_type, 'application/x-www-form-urlencoded')
+        body = URI.encode_www_form(T.cast(data, T::Hash[Symbol, Object]))
+      else
+        body = data
+      end
+      headers['Accept'] = 'application/json'
+      headers['user-agent'] = @sdk_configuration.user_agent
+
+      security = @sdk_configuration.security_source&.call
+
+      timeout = (timeout_ms.to_f / 1000) unless timeout_ms.nil?
+      timeout ||= @sdk_configuration.timeout
+      
+
+      connection = @sdk_configuration.client
+
+      hook_ctx = SDKHooks::HookContext.new(
+        config: @sdk_configuration,
+        base_url: base_url,
+        oauth2_scopes: [],
+        operation_id: 'auth_introspection_api',
+        security_source: @sdk_configuration.security_source
+      )
+
+      error = T.let(nil, T.nilable(StandardError))
+      http_response = T.let(nil, T.nilable(Faraday::Response))
+      
+      
+      begin
+        http_response = T.must(connection).post(url) do |req|
+          req.body = body
+          req.headers.merge!(headers)
+          req.options.timeout = timeout unless timeout.nil?
+          Utils.configure_request_security(req, security)
+
+          @sdk_configuration.hooks.before_request(
+            hook_ctx: SDKHooks::BeforeRequestHookContext.new(
+              hook_ctx: hook_ctx
+            ),
+            request: req
+          )
+        end
+      rescue StandardError => e
+        error = e
+      ensure
+        if http_response.nil? || Utils.error_status?(http_response.status)
+          http_response = @sdk_configuration.hooks.after_error(
+            error: error,
+            hook_ctx: SDKHooks::AfterErrorHookContext.new(
+              hook_ctx: hook_ctx
+            ),
+            response: http_response
+          )
+        else
+          http_response = @sdk_configuration.hooks.after_success(
+            hook_ctx: SDKHooks::AfterSuccessHookContext.new(
+              hook_ctx: hook_ctx
+            ),
+            response: http_response
+          )
+        end
+        
+        if http_response.nil?
+          raise error if !error.nil?
+          raise 'no response'
+        end
+      end
+      
+      content_type = http_response.headers.fetch('Content-Type', 'application/octet-stream')
+      if Utils.match_status_code(http_response.status, ['200'])
+        if Utils.match_content_type(content_type, 'application/json')
+          http_response = @sdk_configuration.hooks.after_success(
+            hook_ctx: SDKHooks::AfterSuccessHookContext.new(
+              hook_ctx: hook_ctx
+            ),
+            response: http_response
+          )
+          response_data = http_response.env.response_body
+          obj = Crystalline.unmarshal_json(JSON.parse(response_data), Models::Components::IntrospectionResponse)
+          response = Models::Operations::AuthIntrospectionApiResponse.new(
+            status_code: http_response.status,
+            content_type: content_type,
+            raw_response: http_response,
+            introspection_response: T.unsafe(obj)
+          )
+
+          return response
+        else
+          raise ::Authlete::Models::Errors::APIError.new(status_code: http_response.status, body: http_response.env.response_body, raw_response: http_response), 'Unknown content type received'
+        end
+      elsif Utils.match_status_code(http_response.status, ['400', '401', '403'])
+        if Utils.match_content_type(content_type, 'application/json')
+          http_response = @sdk_configuration.hooks.after_success(
+            hook_ctx: SDKHooks::AfterSuccessHookContext.new(
+              hook_ctx: hook_ctx
+            ),
+            response: http_response
+          )
+          response_data = http_response.env.response_body
+          obj = Crystalline.unmarshal_json(JSON.parse(response_data), Models::Errors::ResultError)
+          obj.raw_response = http_response
+          throw obj
+        else
+          raise ::Authlete::Models::Errors::APIError.new(status_code: http_response.status, body: http_response.env.response_body, raw_response: http_response), 'Unknown content type received'
+        end
+      elsif Utils.match_status_code(http_response.status, ['500'])
+        if Utils.match_content_type(content_type, 'application/json')
+          http_response = @sdk_configuration.hooks.after_success(
+            hook_ctx: SDKHooks::AfterSuccessHookContext.new(
+              hook_ctx: hook_ctx
+            ),
+            response: http_response
+          )
+          response_data = http_response.env.response_body
+          obj = Crystalline.unmarshal_json(JSON.parse(response_data), Models::Errors::ResultError)
+          obj.raw_response = http_response
+          throw obj
+        else
+          raise ::Authlete::Models::Errors::APIError.new(status_code: http_response.status, body: http_response.env.response_body, raw_response: http_response), 'Unknown content type received'
+        end
+      elsif Utils.match_status_code(http_response.status, ['4XX'])
+        raise ::Authlete::Models::Errors::APIError.new(status_code: http_response.status, body: http_response.env.response_body, raw_response: http_response), 'API error occurred'
+      elsif Utils.match_status_code(http_response.status, ['5XX'])
+        raise ::Authlete::Models::Errors::APIError.new(status_code: http_response.status, body: http_response.env.response_body, raw_response: http_response), 'API error occurred'
+      else
+        raise ::Authlete::Models::Errors::APIError.new(status_code: http_response.status, body: http_response.env.response_body, raw_response: http_response), 'Unknown status code received'
+
+      end
+    end
+
+
+    sig { params(standard_introspection_request: Models::Components::StandardIntrospectionRequest, service_id: ::String, timeout_ms: T.nilable(Integer)).returns(Models::Operations::AuthIntrospectionStandardApiResponse) }
+    def standard_process(standard_introspection_request:, service_id:, timeout_ms: nil)
+      # standard_process - Process OAuth 2.0 Introspection Request
+      # This API exists to help your authorization server provide its own introspection API which complies
+      # with [RFC 7662](https://tools.ietf.org/html/rfc7662) (OAuth 2.0 Token Introspection).
+      # ### Description
+      # This API is supposed to be called from within the implementations of the introspection endpoint
+      # of your service. The authorization server implementation should retrieve the value of `action` from
+      # the response and take the following steps according to the value.
+      # In general, a client application accesses a protected resource endpoint of a service with an access
+      # token, and the implementation of the endpoint checks whether the presented access token has enough
+      # privileges (= scopes) to access the protected resource before returning the protected resource to
+      # the client application. To achieve this flow, the endpoint implementation has to know detailed
+      # information about the access token. Authlete `/auth/introspection` API can be used to get such information.
+      # The response from `/auth/introspection` API has some parameters. Among them, it is `action` parameter
+      # that the authorization server implementation should check first because it denotes the next action
+      # that the authorization server implementation should take. According to the value of `action`, the
+      # authorization server implementation must take the steps described below.
+      # **INTERNAL\_SERVER\_ERROR**
+      # When the value of `action` is `INTERNAL\_SERVER\_ERROR`, it means that the request from the authorization
+      # server implementation was wrong or that an error occurred in Authlete.
+      # In either case, from the viewpoint of the client application, it is an error on the server side.
+      # Therefore, the service implementation should generate a response to the client application with
+      # HTTP status of "500 Internal Server Error".
+      # The value of `responseContent` is a JSON string which describes the error, so it can be used
+      # as the entity body of the response if you want. Note that, however, [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662) does not mention anything about the response
+      # body of error responses.
+      # The following illustrates an example response which the introspection endpoint of the authorization
+      # server implementation generates and returns to the client application.
+      # ```
+      # HTTP/1.1 500 Internal Server Error
+      # Content-Type: application/json
+      # {responseContent}
+      # ```
+      # **BAD\_REQUEST**
+      # When the value of `action` is `BAD\_REQUEST`, it means that the request from the client application
+      # is invalid. This happens when the request from the client did not include the token request parameter.
+      # See "[2.1. Introspection Request](https://datatracker.ietf.org/doc/html/rfc7662#section-2.1)" in
+      # RFC 7662 for details about requirements for introspection requests.
+      # The HTTP status of the response returned to the client application should be "400 Bad Request".
+      # The value of `responseContent` is a JSON string which describes the error, so it can be used
+      # as the entity body of the response if you want. Note that, however, [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662)
+      # does not mention anything about the response body of error responses.
+      # The following illustrates an example response which the introspection endpoint of the authorization
+      # server implementation generates and returns to the client application.
+      # ```
+      # HTTP/1.1 400 Bad Request
+      # Content-Type: application/json
+      # {responseContent}
+      # ```
+      # **OK**
+      # When the value of `action` is `OK`, the request from the client application is valid.
+      # The HTTP status of the response returned to the client application must be "200 OK" and its content
+      # type must be `application/json`.
+      # The value of `responseContent` is a JSON string which complies with the introspection response
+      # defined in "2.2. Introspection Response" in RFC7662.
+      # The following illustrates the response which the introspection endpoint of your authorization server
+      # implementation should generate and return to the client application.
+      # ```
+      # HTTP/1.1 200 OK
+      # Content-Type: application/json
+      # {responseContent}
+      # ```
+      # Note that RFC 7662 says \_"To prevent token scanning attacks, **the endpoint MUST also require some
+      # form of authorization to access this endpoint**"\_. This means that you have to protect your introspection
+      # endpoint in some way or other. Authlete does not care about how your introspection endpoint is protected.
+      # In most cases, as mentioned in RFC 7662, "401 Unauthorized" is a proper response when an introspection
+      # request does not satisfy authorization requirements imposed by your introspection endpoint.
+      # 
+      request = Models::Operations::AuthIntrospectionStandardApiRequest.new(
+        service_id: service_id,
+        standard_introspection_request: standard_introspection_request
+      )
+      url, params = @sdk_configuration.get_server_details
+      base_url = Utils.template_url(url, params)
+      url = Utils.generate_url(
+        Models::Operations::AuthIntrospectionStandardApiRequest,
+        base_url,
+        '/api/{serviceId}/auth/introspection/standard',
+        request
+      )
+      headers = {}
+      headers = T.cast(headers, T::Hash[String, String])
+      req_content_type, data, form = Utils.serialize_request_body(request, false, false, :standard_introspection_request, :json)
+      headers['content-type'] = req_content_type
+      raise StandardError, 'request body is required' if data.nil? && form.nil?
+
+      if form
+        body = Utils.encode_form(form)
+      elsif Utils.match_content_type(req_content_type, 'application/x-www-form-urlencoded')
+        body = URI.encode_www_form(T.cast(data, T::Hash[Symbol, Object]))
+      else
+        body = data
+      end
+      headers['Accept'] = 'application/json'
+      headers['user-agent'] = @sdk_configuration.user_agent
+
+      security = @sdk_configuration.security_source&.call
+
+      timeout = (timeout_ms.to_f / 1000) unless timeout_ms.nil?
+      timeout ||= @sdk_configuration.timeout
+      
+
+      connection = @sdk_configuration.client
+
+      hook_ctx = SDKHooks::HookContext.new(
+        config: @sdk_configuration,
+        base_url: base_url,
+        oauth2_scopes: [],
+        operation_id: 'auth_introspection_standard_api',
+        security_source: @sdk_configuration.security_source
+      )
+
+      error = T.let(nil, T.nilable(StandardError))
+      http_response = T.let(nil, T.nilable(Faraday::Response))
+      
+      
+      begin
+        http_response = T.must(connection).post(url) do |req|
+          req.body = body
+          req.headers.merge!(headers)
+          req.options.timeout = timeout unless timeout.nil?
+          Utils.configure_request_security(req, security)
+
+          @sdk_configuration.hooks.before_request(
+            hook_ctx: SDKHooks::BeforeRequestHookContext.new(
+              hook_ctx: hook_ctx
+            ),
+            request: req
+          )
+        end
+      rescue StandardError => e
+        error = e
+      ensure
+        if http_response.nil? || Utils.error_status?(http_response.status)
+          http_response = @sdk_configuration.hooks.after_error(
+            error: error,
+            hook_ctx: SDKHooks::AfterErrorHookContext.new(
+              hook_ctx: hook_ctx
+            ),
+            response: http_response
+          )
+        else
+          http_response = @sdk_configuration.hooks.after_success(
+            hook_ctx: SDKHooks::AfterSuccessHookContext.new(
+              hook_ctx: hook_ctx
+            ),
+            response: http_response
+          )
+        end
+        
+        if http_response.nil?
+          raise error if !error.nil?
+          raise 'no response'
+        end
+      end
+      
+      content_type = http_response.headers.fetch('Content-Type', 'application/octet-stream')
+      if Utils.match_status_code(http_response.status, ['200'])
+        if Utils.match_content_type(content_type, 'application/json')
+          http_response = @sdk_configuration.hooks.after_success(
+            hook_ctx: SDKHooks::AfterSuccessHookContext.new(
+              hook_ctx: hook_ctx
+            ),
+            response: http_response
+          )
+          response_data = http_response.env.response_body
+          obj = Crystalline.unmarshal_json(JSON.parse(response_data), Models::Components::StandardIntrospectionResponse)
+          response = Models::Operations::AuthIntrospectionStandardApiResponse.new(
+            status_code: http_response.status,
+            content_type: content_type,
+            raw_response: http_response,
+            standard_introspection_response: T.unsafe(obj)
+          )
+
+          return response
+        else
+          raise ::Authlete::Models::Errors::APIError.new(status_code: http_response.status, body: http_response.env.response_body, raw_response: http_response), 'Unknown content type received'
+        end
+      elsif Utils.match_status_code(http_response.status, ['400', '401', '403'])
+        if Utils.match_content_type(content_type, 'application/json')
+          http_response = @sdk_configuration.hooks.after_success(
+            hook_ctx: SDKHooks::AfterSuccessHookContext.new(
+              hook_ctx: hook_ctx
+            ),
+            response: http_response
+          )
+          response_data = http_response.env.response_body
+          obj = Crystalline.unmarshal_json(JSON.parse(response_data), Models::Errors::ResultError)
+          obj.raw_response = http_response
+          throw obj
+        else
+          raise ::Authlete::Models::Errors::APIError.new(status_code: http_response.status, body: http_response.env.response_body, raw_response: http_response), 'Unknown content type received'
+        end
+      elsif Utils.match_status_code(http_response.status, ['500'])
+        if Utils.match_content_type(content_type, 'application/json')
+          http_response = @sdk_configuration.hooks.after_success(
+            hook_ctx: SDKHooks::AfterSuccessHookContext.new(
+              hook_ctx: hook_ctx
+            ),
+            response: http_response
+          )
+          response_data = http_response.env.response_body
+          obj = Crystalline.unmarshal_json(JSON.parse(response_data), Models::Errors::ResultError)
+          obj.raw_response = http_response
+          throw obj
+        else
+          raise ::Authlete::Models::Errors::APIError.new(status_code: http_response.status, body: http_response.env.response_body, raw_response: http_response), 'Unknown content type received'
+        end
+      elsif Utils.match_status_code(http_response.status, ['4XX'])
+        raise ::Authlete::Models::Errors::APIError.new(status_code: http_response.status, body: http_response.env.response_body, raw_response: http_response), 'API error occurred'
+      elsif Utils.match_status_code(http_response.status, ['5XX'])
+        raise ::Authlete::Models::Errors::APIError.new(status_code: http_response.status, body: http_response.env.response_body, raw_response: http_response), 'API error occurred'
+      else
+        raise ::Authlete::Models::Errors::APIError.new(status_code: http_response.status, body: http_response.env.response_body, raw_response: http_response), 'Unknown status code received'
+
+      end
+    end
+  end
+end