internetdata 2.4.1 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e04a226b5ebdcdaf6dc01178b331e40a3aa834facc43f289a844fe1c772aa687
-  data.tar.gz: 995b7691fffb03bfbe5b66f95f9341842809f71c8a3f0d8ee53d8429abef0288
+  metadata.gz: 960ec5836038e70272ff2f5b29b23d2604fe320fb5a143f1647f72c0b66028ab
+  data.tar.gz: 26d3bfca65b7246fc6291b38ebefea5e4496cedba7bff94fe662a0a5e395d704
 SHA512:
-  metadata.gz: 72f3070388c1b5feee4f5ac8e562c3fc853d46ee345cde838556ba784b49fbb27e96bb03ba997b9581f3bfa1894457eff692b808772388dc8d6f38cb1b57469e
-  data.tar.gz: b047915dc0afa14375c651cc016b385a97f5bd24c3e8e09a0192e7dbdea2b9a91f987bd9ca1a0198d6202ffff03273afdaaa1d710dce1324ebb7f97391a25441
+  metadata.gz: aa039d9cad48377cee2dccafc75220a202f1731078b091a5f70bcfefacdec9e2c1bfd121c83b41c384173a136dd23fe6e6de8f77440ca14c06fa65b6c8f84c13
+  data.tar.gz: a9d1ec2c94f7c1828cfb78f2c552090eefb2a183075a1f6b84f40613c6efe45f03cec1ff0b4d3b70e04f8ab17d027b6c573d9d25da11fc44e3b6494a30bbb22f

data/README.md

@@ -137,6 +137,23 @@ keyed = InternetData::Client.new(api_key: token.apikey)
 
 `poll_device_token` raises `InternetData::OauthAccessDeniedError` when the person refuses and `InternetData::OauthExpiredTokenError` when the code expires first. Client IDs are issued on request from support@internetdata.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 = InternetData::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`.
+
 ## Other Libraries
 
 There are official InternetData client libraries available for many languages including PHP, Python, Go, Java, Ruby, and many popular frameworks such as Django, Rails, and Laravel. See our GitHub at https://github.com/internetdata for more.

data/lib/internetdata/oauth_api.rb

@@ -1,6 +1,21 @@
 # frozen_string_literal: true
 
+require 'digest'
+require 'securerandom'
+
 module InternetData
+  # 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 InternetData::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 InternetData
   # client ID works; they are issued on request from support@internetdata.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 InternetData
       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 InternetData
       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/internetdata/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module InternetData
-  VERSION = '2.4.1'
+  VERSION = '2.5.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: internetdata
 version: !ruby/object:Gem::Version
-  version: 2.4.1
+  version: 2.5.0
 platform: ruby
 authors:
 - Mslm Dev