vpndetection 5.1.0 → 5.2.0

data/lib/vpndetection/oauth_api.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module VPNDetection
+  # Signing a person in with OAuth, reached as `client.oauth`.
+  #
+  # A program on the person's own machine starts a device sign-in, shows them a
+  # code to approve in their browser, and waits for the tokens, which can carry
+  # one of their API keys so nobody pastes a key by hand. Only a registered
+  # client ID works; they are issued on request from support@vpndetection.io.
+  #
+  # No request made here carries the API key this client was built with, and a
+  # client built without one works exactly the same. Every method takes
+  # `timeout:`, seconds per attempt, for that call alone.
+  class OauthApi
+    METADATA_PATH = '/.well-known/oauth-authorization-server'
+    DEVICE_AUTHORIZATION_PATH = '/oauth/device_authorization'
+    TOKEN_PATH = '/oauth/token'
+    REVOKE_PATH = '/oauth/revoke'
+    DEVICE_CODE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code'
+
+    # The members a 2xx must carry for its type to mean anything.
+    REQUIRED = {
+      OauthMetadata => %i[issuer authorization_endpoint token_endpoint],
+      DeviceAuthorization => %i[device_code user_code verification_uri expires_in interval],
+      TokenResponse => %i[access_token token_type expires_in],
+    }.freeze
+
+    def initialize(transport, retries:)
+      @transport = transport
+      @retries = retries
+      # The poll's wait and its monotonic clock, which a test replaces together.
+      @wait = ->(seconds) { sleep(seconds) }
+      @now = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+    end
+
+    # The authorization server's discovery document.
+    #
+    # @return [OauthMetadata]
+    def metadata(timeout: nil)
+      Retries.with_retries(@retries) do
+        decode(OauthMetadata, @transport.oauth_request(:GET, METADATA_PATH, timeout: timeout).run)
+      end
+    end
+
+    # Start a device sign-in: show the person `user_code` and `verification_uri`,
+    # then {#poll_device_token}.
+    #
+    # @param scope [String, nil] space-delimited, sent as given; the server grants
+    #   what this client may ask for and silently drops the rest.
+    # @param resource [String, nil] the API the tokens are for.
+    # @return [DeviceAuthorization]
+    def device_authorization(client_id, scope: nil, resource: nil, timeout: nil)
+      form = { 'client_id' => client_id, 'scope' => scope, 'resource' => resource }.compact
+      Retries.with_retries(@retries) do
+        request = @transport.oauth_request(:POST, DEVICE_AUTHORIZATION_PATH, form: form, timeout: timeout)
+        decode(DeviceAuthorization, request.run)
+      end
+    end
+
+    # Exchange a device code for tokens, once. Until the person approves this
+    # raises {OauthRequestError} coded `authorization_pending`;
+    # {#poll_device_token} is the loop that waits for them.
+    #
+    # Never retried: the server spends the code when it answers, so a retry after
+    # a lost success could only fail and lose the tokens.
+    #
+    # @return [TokenResponse] with `apikey_id` and `apikey` when the person picked a key.
+    def exchange_device_code(client_id, device_code, timeout: nil)
+      form = { 'grant_type' => DEVICE_CODE_GRANT, 'device_code' => device_code, 'client_id' => client_id }
+      exchange(form, timeout)
+    end
+
+    # Exchange a refresh token for a new pair. The token presented is spent, so
+    # keep the `refresh_token` this returns. Never retried, for the same reason as
+    # {#exchange_device_code}.
+    #
+    # @return [TokenResponse] which may name the key in `apikey_id`, but never carries `apikey`.
+    def exchange_refresh_token(client_id, refresh_token, timeout: nil)
+      form = { 'grant_type' => 'refresh_token', 'refresh_token' => refresh_token, 'client_id' => client_id }
+      exchange(form, timeout)
+    end
+
+    # Revoke an access or refresh token. A refresh token ends the whole grant and
+    # every token it issued, which is how a machine signs out.
+    #
+    # @return [nil]
+    def revoke(client_id, token, timeout: nil)
+      form = { 'token' => token, 'client_id' => client_id }
+      Retries.with_retries(@retries) do
+        request = @transport.oauth_request(:POST, REVOKE_PATH, form: form, timeout: timeout)
+        Transport.oauth_success!(request.run)
+      end
+      nil
+    end
+
+    # Wait for the person to approve a device sign-in, and return its tokens.
+    #
+    # Waits `device.interval` seconds before EVERY exchange, the first included,
+    # and five seconds longer for good each time the server answers `slow_down`.
+    # Raises {OauthAccessDeniedError} when the person refuses and
+    # {OauthExpiredTokenError} when the code expires, including locally, with no
+    # status, once `device.expires_in` seconds have passed since this call. Any
+    # other failure, a timeout or an outage included, ends the wait unchanged;
+    # calling again with the same device is safe until the code expires.
+    #
+    # There is no way to cancel it from outside: it blocks until one of those
+    # outcomes, so run it where blocking is acceptable.
+    #
+    # @param timeout [Numeric, nil] bounds each exchange, never the whole wait.
+    # @return [TokenResponse]
+    def poll_device_token(client_id, device, timeout: nil)
+      interval = device.interval >= 1 ? device.interval : 5
+      deadline = @now.call + device.expires_in
+      loop do
+        @wait.call(interval)
+        raise OauthExpiredTokenError, 'expired_token' if @now.call >= deadline
+
+        begin
+          return exchange_device_code(client_id, device.device_code, timeout: timeout)
+        rescue OauthRequestError => e
+          case e.error_code
+          when 'slow_down' then interval += 5
+          when 'authorization_pending' then next
+          else raise
+          end
+        end
+      end
+    end
+
+    private
+
+    def exchange(form, timeout)
+      decode(TokenResponse, @transport.oauth_request(:POST, TOKEN_PATH, form: form, timeout: timeout).run)
+    end
+
+    # Only the members the type declares are read, each checked against the type
+    # the spec gives it, so an absent member stays nil and an empty `scope` stays
+    # an empty string. A 2xx that is not the type is the server's fault.
+    def decode(type, response)
+      body = Transport.oauth_object(response)
+      type.attribute_map.each do |member, wire|
+        value = body[wire.to_s]
+        if value.nil?
+          next unless REQUIRED.fetch(type).include?(member)
+
+          raise Error.new(:server_error, "the answer carried no #{wire}", status: response.code)
+        end
+        next if typed?(type.openapi_types.fetch(member), value)
+
+        raise Error.new(:server_error, "the answer's #{wire} is not a #{type.openapi_types[member]}",
+                        status: response.code)
+      end
+      type.build_from_hash(body)
+    end
+
+    def typed?(type, value)
+      case type
+      when :String then value.is_a?(String)
+      when :Integer then value.is_a?(Integer)
+      when :Boolean then [true, false].include?(value)
+      when :'Array<String>' then value.is_a?(Array) && value.all?(String)
+      else raise ArgumentError, "no check for a member typed #{type}"
+      end
+    end
+  end
+end

data/lib/vpndetection/retries.rb

@@ -11,12 +11,14 @@ module VPNDetection
 
     module_function
 
-    def with_retries(retries)
+    # `retry_if`, when given, is asked after each retryable failure, and a false
+    # answer ends the attempts there.
+    def with_retries(retries, retry_if: nil)
       attempt = 0
       begin
         yield
       rescue Error => e
-        raise unless e.retryable? && attempt < retries
+        raise unless e.retryable? && attempt < retries && (retry_if.nil? || retry_if.call)
 
         attempt += 1
         sleep(delay_for(e, attempt))

data/lib/vpndetection/transport.rb

@@ -53,9 +53,13 @@ module VPNDetection
     # is true for every value it can be given, so the database download's 302
     # would be chased and a multi-gigabyte dataset read into memory. Nothing
     # this API serves is meant to be followed.
+    #
+    # `opts[:timeout]` is a per-call override of the configured bound, which the
+    # generated client would otherwise apply to every request it builds.
     def build_request(http_method, path, opts = {})
       request = super
       request.options[:followlocation] = false
+      request.options[:timeout] = opts[:timeout] unless opts[:timeout].nil?
       request
     end
 
@@ -84,37 +88,56 @@ module VPNDetection
       Typhoeus::Request.new(url, options)
     end
 
-    def lookup_request(ip)
+    def lookup_request(ip, timeout: nil)
       build_request(
         :GET, LOOKUP_PATH.sub('{ip}', CGI.escape(ip.to_s)),
         header_params: { 'Accept' => 'application/json' },
         auth_names: %w[bearerAuth apiKeyHeader apiKeyQuery],
+        timeout: timeout,
       )
     end
 
-    def myip_request
+    def myip_request(timeout: nil)
       build_request(
         :GET, MYIP_PATH,
         header_params: { 'Accept' => 'application/json' },
         auth_names: %w[bearerAuth apiKeyHeader apiKeyQuery],
+        timeout: timeout,
       )
     end
 
-    def entitlement_request
+    def entitlement_request(timeout: nil)
       build_request(
         :GET, ENTITLEMENT_PATH,
         header_params: { 'Accept' => 'application/json' },
         auth_names: %w[bearerAuth apiKeyHeader apiKeyQuery],
+        timeout: timeout,
       )
     end
 
+    # A request to the authorization server, which carries NO credential whatever
+    # this client was built with: these endpoints have no use for the API key, and
+    # on the token endpoint an `Authorization` header reads as client
+    # authentication, which a public client does not have.
+    #
+    # The form is encoded here rather than by curl, so a `+` in a value leaves as
+    # `%2B` and never arrives as a space.
+    def oauth_request(http_method, path, form: nil, timeout: nil)
+      headers = { 'Accept' => 'application/json' }
+      headers['Content-Type'] = 'application/x-www-form-urlencoded' unless form.nil?
+      request = build_request(http_method, path, header_params: headers, auth_names: [], timeout: timeout)
+      request.options[:body] = URI.encode_www_form(form) unless form.nil?
+      request
+    end
+
     # The one request with a body: the batch.
-    def batch_request(ips)
+    def batch_request(ips, timeout: nil)
       build_request(
         :POST, BATCH_PATH,
         header_params: { 'Accept' => 'application/json', 'Content-Type' => 'application/json' },
         body: { ips: ips },
         auth_names: %w[bearerAuth apiKeyHeader apiKeyQuery],
+        timeout: timeout,
       )
     end
 
@@ -144,6 +167,36 @@ module VPNDetection
       }
     end
 
+    # The JSON object a 2xx OAuth answer carries. A refusal the authorization
+    # server words as an RFC 6749 error raises that; anything else that is not a
+    # 2xx raises the ordinary error its status maps to.
+    def self.oauth_object(response)
+      oauth_success!(response)
+      parse_object(response)
+    end
+
+    def self.oauth_success!(response)
+      raise Error.from_transport(response) if transport_failure?(response)
+      return if response.success?
+
+      raise oauth_refusal(response) || Error.from_status(response.code, response.headers, response.body)
+    end
+
+    # Only a 4xx whose body is a JSON object with a STRING `error` is the
+    # authorization server's own refusal. A 5xx is an outage whatever its body
+    # says, and a gateway's page names no OAuth code at all.
+    def self.oauth_refusal(response)
+      return nil unless (400..499).cover?(response.code)
+
+      body = JSON.parse(response.body.to_s)
+      return nil unless body.is_a?(Hash) && body['error'].is_a?(String)
+
+      description = body['error_description'].is_a?(String) ? body['error_description'] : nil
+      OauthRequestError.for_code(body['error'], description, status: response.code, headers: response.headers)
+    rescue JSON::ParserError
+      nil
+    end
+
     def self.transport_failure?(response)
       response.timed_out? || response.code.to_i.zero?
     end
@@ -159,6 +212,6 @@ module VPNDetection
                       status: response.code)
     end
 
-    private_class_method :transport_failure?, :parse_object
+    private_class_method :transport_failure?, :parse_object, :oauth_refusal
   end
 end

data/lib/vpndetection/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module VPNDetection
-  VERSION = '5.1.0'
+  VERSION = '5.2.0'
 end

data/lib/vpndetection.rb

@@ -20,6 +20,7 @@ require 'vpndetection/cache'
 require 'vpndetection/retries'
 require 'vpndetection/transport'
 require 'vpndetection/database_api'
+require 'vpndetection/oauth_api'
 require 'vpndetection/client'
 
 # The official Ruby client library for the VPNDetection API.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vpndetection
 version: !ruby/object:Gem::Version
-  version: 5.1.0
+  version: 5.2.0
 platform: ruby
 authors:
 - Mslm Dev
@@ -109,6 +109,7 @@ files:
 - lib/vpndetection/models/standing.rb
 - lib/vpndetection/models/token_response.rb
 - lib/vpndetection/models/vpn_detail.rb
+- lib/vpndetection/oauth_api.rb
 - lib/vpndetection/result.rb
 - lib/vpndetection/retries.rb
 - lib/vpndetection/transport.rb