vpndetection 5.5.2 → 5.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3584c477f32b65c669b40d04c312331a8cdd4d63b0111a68678af8ce5dada04
-  data.tar.gz: 474a44c82285715665b11ec0330473d7ba84b69f9ef0f32e5bc6e5b864f497df
+  metadata.gz: af30c794b9bdfb02657775e5e1fd768fa77855d97b1c4f8c2ea3ee4b9319380f
+  data.tar.gz: dab0d13a90c8f25adb6d6e2ecbafa524d62f1629bcb65e1e4cc55101fe81321d
 SHA512:
-  metadata.gz: 85aba300ca2689f0b1ca57b377bc6719158c33cbf1b200aaed8a5aa0f618532ea5eda0e65ad9b78479120c64718ecc439c0f3f5a987ea860602eb7c43dda390c
-  data.tar.gz: a4e4f33038fd342ed73c0ca1c8f9fab03f6e181d1aaedf0c4cc643c853ce73e8a545d7e6471a6a4f950f996d4092205f2b0f9f4416be2c44f61ef05ce62f5788
+  metadata.gz: 3432eaf4c3bed7d1659898e61a2ce8d9918035e84a39c721e31958cafc97703cb3222c87ab0ed083f2ab02c422b0c737931da0a81b13950877fcb070e5c7df0f
+  data.tar.gz: 8152326e9e5b8e8e20d170be7dbd950b8ff5bd077eb6327857e4697898a4a87ebc642a5e104bdcd4d78d579ff785315bb7501f8001ecc3ccf91d042c80781f91

data/README.md

@@ -203,6 +203,23 @@ keyed = VPNDetection::Client.new(api_key: token.apikey)
 
 `poll_device_token` raises `VPNDetection::OauthAccessDeniedError` when the person refuses and `VPNDetection::OauthExpiredTokenError` when the code expires first. Client IDs are issued on request from support@vpndetection.io, and `client.oauth.revoke('your-client-id', token.refresh_token)` signs the machine out.
 
+### Sign in with OAuth (authorization code)
+
+An app that can take a browser redirect signs the person in there instead, with a PKCE pair made for that one sign-in:
+
+```ruby
+client = VPNDetection::Client.new
+redirect_uri = 'http://127.0.0.1:8765/callback'
+pkce = client.oauth.create_pkce
+
+url = client.oauth.authorization_url('your-client-id', redirect_uri, pkce.challenge,
+                                     scope: 'apikeys.use', state: 'your-state')
+# Open url in the browser. Its redirect to redirect_uri carries code and state.
+token = client.oauth.exchange_authorization_code('your-client-id', code, pkce.verifier, redirect_uri)
+```
+
+Check that `state` came back as you sent it before you exchange `code`, which works once. The client ID can also be the https URL of a client metadata document your app serves, and such an app is never handed a key, so `token.apikey` stays `nil`.
+
 ### Absent is not false
 
 Every field beyond `ip` and `is_vpn` is present when your plan includes it and `nil` when it does not. `nil` means "not in your plan"; `false` means "we checked, and no".

data/lib/vpndetection/oauth_api.rb

@@ -1,6 +1,21 @@
 # frozen_string_literal: true
 
+require 'digest'
+require 'securerandom'
+
 module VPNDetection
+  # One sign-in's PKCE pair: `challenge` goes in the authorization URL, and
+  # `verifier` to {OauthApi#exchange_authorization_code}.
+  # `code_challenge_method` is always `S256`, the only method the server
+  # accepts; a reader called `method` would hide Object#method. The verifier is
+  # left out of `inspect`, so logging the pair does not leak it.
+  Pkce = Data.define(:verifier, :challenge, :code_challenge_method) do
+    def inspect
+      "#<data VPNDetection::Pkce challenge=#{challenge.inspect} code_challenge_method=#{code_challenge_method.inspect}>"
+    end
+    alias_method :to_s, :inspect
+  end
+
   # 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
@@ -9,13 +24,18 @@ module VPNDetection
   # 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.
+  # client built without one works exactly the same. Every method that makes a
+  # request takes `timeout:`, seconds per attempt, for that call alone.
+  #
+  # An app that can take a browser redirect signs the person in with the
+  # authorization code flow instead: {#authorization_url} with a {#create_pkce}
+  # pair, then {#exchange_authorization_code}.
   class OauthApi
     METADATA_PATH = '/.well-known/oauth-authorization-server'
     DEVICE_AUTHORIZATION_PATH = '/oauth/device_authorization'
     TOKEN_PATH = '/oauth/token'
     REVOKE_PATH = '/oauth/revoke'
+    AUTHORIZE_PATH = '/oauth/authorize'
     DEVICE_CODE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code'
     # The longest single `sleep` the poll asks Ruby for, in seconds.
     LONGEST_SLEEP = 2**31 - 1
@@ -82,6 +102,55 @@ module VPNDetection
       exchange(form, timeout)
     end
 
+    # Exchange the `code` a sign-in's redirect brought back for tokens.
+    # `code_verifier` is the PKCE verifier whose challenge went into the
+    # authorization URL, and `redirect_uri` that URL's, exactly.
+    #
+    # Never retried: the server spends the code on first read, before it checks
+    # the verifier, so a retry could only be refused.
+    #
+    # @return [TokenResponse]
+    def exchange_authorization_code(client_id, code, code_verifier, redirect_uri, timeout: nil)
+      form = {
+        'grant_type' => 'authorization_code', 'code' => code, 'redirect_uri' => redirect_uri,
+        'client_id' => client_id, 'code_verifier' => code_verifier
+      }
+      exchange(form, timeout)
+    end
+
+    # The URL to open in the person's browser for the authorization code flow.
+    # Makes no request. Once they decide, the server redirects to `redirect_uri`
+    # with a `code` for {#exchange_authorization_code} (and `state`, when one was
+    # given), or with an `error`. An option given empty is left out; a required
+    # value that is empty or not UTF-8 raises ArgumentError.
+    #
+    # @return [String]
+    def authorization_url(client_id, redirect_uri, code_challenge, scope: nil, state: nil, resource: nil)
+      required = { 'client_id' => client_id, 'redirect_uri' => redirect_uri, 'code_challenge' => code_challenge }
+      required.each do |name, value|
+        raise ArgumentError, "#{name} must be a non-empty String" unless value.is_a?(String) && !value.empty?
+      end
+      optional = { 'scope' => scope, 'state' => state, 'resource' => resource }.reject { |_, v| v.nil? || v.empty? }
+      params = { 'response_type' => 'code', **required, 'code_challenge_method' => 'S256', **optional }
+      query = params.map { |name, value| "#{name}=#{percent_encode(name, value)}" }.join('&')
+      "#{@transport.config.base_url}#{AUTHORIZE_PATH}?#{query}"
+    end
+
+    # A fresh PKCE pair for one sign-in, from 32 bytes of SecureRandom.
+    #
+    # @return [Pkce]
+    def create_pkce
+      verifier = SecureRandom.urlsafe_base64(32)
+      Pkce.new(verifier: verifier, challenge: pkce_challenge(verifier), code_challenge_method: 'S256')
+    end
+
+    # The `S256` challenge for a PKCE verifier: its SHA-256, as unpadded base64url.
+    #
+    # @return [String]
+    def pkce_challenge(verifier)
+      [Digest::SHA256.digest(verifier)].pack('m0').tr('+/', '-_').delete('=')
+    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.
     #
@@ -147,6 +216,16 @@ module VPNDetection
       end
     end
 
+    # Every byte of the UTF-8 but A-Z a-z 0-9 - . _ ~ as %XX, so a space is %20
+    # and never +.
+    def percent_encode(name, value)
+      raise ArgumentError, "#{name} is not valid UTF-8" unless value.encode(Encoding::UTF_8).valid_encoding?
+
+      value.encode(Encoding::UTF_8).b.gsub(/[^A-Za-z0-9\-._~]/n) { |byte| format('%%%02X', byte.ord) }
+    rescue EncodingError
+      raise ArgumentError, "#{name} is not valid UTF-8"
+    end
+
     def exchange(form, timeout)
       decode(TokenResponse, @transport.oauth_request(:POST, TOKEN_PATH, form: form, timeout: timeout).run)
     end

data/lib/vpndetection/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vpndetection
 version: !ruby/object:Gem::Version
-  version: 5.5.2
+  version: 5.6.0
 platform: ruby
 authors:
 - Mslm Dev