yt-auth 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: afed44e061a6b8add2141e57e0df78187b79e368
-  data.tar.gz: af818f5dd4c4a129d835887403c44315cb9e133e
+  metadata.gz: 90acfd2ff7bdc68980c0c12c9e72761981cecb55
+  data.tar.gz: 863100fe5cfcf1429428980fd18f0df8c8b1c2c5
 SHA512:
-  metadata.gz: 77fd0226d1aa626a4e82a9245fa1a5a8c6a86303f1deca4d46b5bc29bedf6571e2568737019e2361dd9c1fbe73f009037bfc9fe730a09a99080e87525322b89b
-  data.tar.gz: 0b7b546dcaa6f80dc4e25524b7c5cc65860860bb16466a3e65240ba0adff94f26f1062e7c7990985075500baa7114b423b6d6070521c5d5c5545ddadd2c837e2
+  metadata.gz: 21301ea2bd24299adc34767cdbc33d21fd96c622bd562ded4c420a4ccfd237a32b3c5b708a9e64ae2dffdd1e1296fcb3ff041eff71db8e5ef0da564f0299f2b8
+  data.tar.gz: 1da658c63db79a7908f6ba1ba11052e1835eb6bc1b82b5753be318b4d5c2a002beb547406f73280094e4ee405af622dd74d3ca87948f2f9d1efcb66d050d3cb0

data/CHANGELOG.md

@@ -6,6 +6,21 @@ For more information about changelogs, check
 [Keep a Changelog](http://keepachangelog.com) and
 [Vandamme](http://tech-angels.github.io/vandamme).
 
+## 0.3.0  - 2017-08-25
+
+**How to upgrade**
+
+If your code uses `Yt::Auth#url` then you must use `Yt::Auth.url_for` instead.
+If your code uses `Yt::Auth.new(code:)` then you must use `Yt::Auth.create(code:)` instead.
+If your code uses `Yt::Auth.new(refresh_token:)` then you must use `Yt::Auth.find_by(refresh_token:)` instead.
+
+* [ENHANCEMENT] Extract `Auth#url` into `Auth.url_for`
+* [ENHANCEMENT] Rename `Auth.new(code:)` into `Auth.create(code:)`
+* [ENHANCEMENT] Rename `Auth.new(refresh_token:)` into `Auth.create(refresh_token:)`
+* [FEATURE] Yt::Auth.url_for now accepts the scope to authenticate
+* [FEATURE] Yt::Auth.url_for now accepts an option to force re-authentication
+* [FEATURE] Add `Auth#revoke` to revoke a refresh token
+
 ## 0.2.3  - 2017-08-24
 
 * [FEATURE] Add the ability to generate access token from a refresh token

data/README.md

@@ -16,48 +16,83 @@ The **source code** is available on [GitHub](https://github.com/fullscreen/yt-au
 [![Online docs](http://img.shields.io/badge/docs-✓-green.svg)](http://www.rubydoc.info/gems/yt-auth/frames)
 [![Gem Version](http://img.shields.io/gem/v/yt-auth.svg)](http://rubygems.org/gems/yt-auth)
 
-The Yt::Auth class provides three public methods: `url`, `email`, and `access_token`.
+Yt::Auth.url_for
+----------------
 
-Yt::Auth#url
-------------
-
-With the `url` method, you can obtain a URL where to redirect users who need to
-authenticate with their Google account in order to use your application:
+With the `url_for` class method, you can obtain a URL where to redirect users
+who need to authenticate with their Google account in order to use your
+application:
 
 ```ruby
 redirect_uri = 'https://example.com/auth' # REPLACE WITH REAL ONE
-Yt::Auth.new(redirect_uri: redirect_uri).url
+scope = %i(yt-analytics.readonly youtube)
+Yt::Auth.url_for(redirect_uri: redirect_uri, scope: scope, force: true)
  # => https://accounts.google.com/o/oauth2/auth?client_id=...&scope=email&redirect_uri=https%3A%2F%2Fexample.com%2Fauth&response_type=code
 ```
 
-Yt::Auth#email
---------------
+Yt::Auth.create
+----------------
 
 After users have authenticated with their Google account, they will be
 redirected to the `redirect_uri` you indicated, with an extra `code` query
 parameter, e.g. `https://example.com/auth?code=1234`
 
-With the `email` method, you can obtain the verified email of the users:
+With the `create` class method, you can create an instance for that
+authentication:
 
 ```ruby
 redirect_uri = 'https://example.com/auth' # REPLACE WITH REAL ONE
-code = '1234' # REPLACE WITH REAL ONE
-Yt::Auth.new(redirect_uri: redirect_uri, code: code).email
+code = 'dfwe7r9djd234ffdjf3009dfknfd98re' # REPLACE WITH REAL ONE
+auth = Yt::Auth.create(redirect_uri: redirect_uri, code: code)
+ # => #<Yt::Auth:0x007fe61d…>
+```
+
+Yt::Auth#email
+--------------
+
+Once you have an instance of `Yt::Auth`, you can obtain the verified email
+of the authenticated user:
+
+```ruby
+auth.email
  # => "user@example.com"
 ```
 
 Yt::Auth#access_token
 ---------------------
 
-Similarly, with the `access_token` method, you can obtain an access token of the users:
+Once you have an instance of `Yt::Auth`, you can also obtain the access token
+of the authenticated user:
 
 ```ruby
-redirect_uri = 'https://example.com/auth' # REPLACE WITH REAL ONE
-code = '1234' # REPLACE WITH REAL ONE
-Yt::Auth.new(redirect_uri: redirect_uri, code: code).access_token
- # => "ya29.GltbBLXt74GrwX8S_xr70aX"
+auth.access_token
+ # => "ya29.df8er8e9r89er"
 ```
 
+Yt::Auth#refresh_token
+----------------------
+
+Once you have an instance of `Yt::Auth`, you can also obtain the refresh token
+of the authenticated user:
+
+```ruby
+auth.refresh_token
+ # => "sdf7f7erre98df"
+```
+
+Yt::Auth.find_by
+----------------
+
+If you already know the refresh token of a Google account, you can obtain its
+complete authentication object:
+
+```ruby
+auth = Auth.find_by(refresh_token: "sdf7f7erre98df")
+auth.email
+ # => "user@example.com"
+```
+
+
 Yt::HTTPError
 -------------
 

data/lib/yt/auth.rb

@@ -13,20 +13,48 @@ module Yt
     #   after they have completed the Google OAuth flow.
     # @option options [String] :code A single-use authorization code provided
     #   by Google OAuth to obtain an access token to access Google API.
-    def initialize(options = {})
-      @redirect_uri = options[:redirect_uri]
-      @code = options[:code]
-      @refresh_token = options[:refresh_token]
+    def self.create(options = {})
+      new options.merge(grant_type: :authorization_code)
+    end
+
+    # @param [Hash] options the options to initialize an instance of Yt::Auth.
+    # @option options [String] :refresh_token A multi-use refresh token to
+    #   obtain an access token to access Google API.
+    def self.find_by(options = {})
+      new options.merge(grant_type: :refresh_token)
     end
 
     # @return [String] the URL where to authenticate with a Google account.
-    def url
+    # @param [Hash] options the options to initialize an instance of Yt::Auth.
+    # @option options [String] :redirect_uri The URI to redirect users to
+    #   after they have completed the Google OAuth flow.
+    # @option options [Boolean] :force whether to force users to re-authenticate
+    #   an account that was previously authenticated.
+    # @option options [Array<String>] :scopes The list of scopes that users
+    #   are requested to authorize.
+    def self.url_for(options = {})
       host = 'accounts.google.com'
       path = '/o/oauth2/auth'
-      query = URI.encode_www_form url_params
+      query = URI.encode_www_form url_params(options)
       URI::HTTPS.build(host: host, path: path, query: query).to_s
     end
 
+    # @param [Hash] options the options to initialize an instance of Yt::Auth.
+    # @option options [String] :grant_type
+    # @option options [String] :redirect_uri
+    # @option options [String] :code
+    # @option options [String] :refresh_token
+    def initialize(options = {})
+      @tokens_body = options
+      @tokens_body[:client_id] = Yt.configuration.client_id
+      @tokens_body[:client_secret] = Yt.configuration.client_secret
+    end
+
+    # @return [Boolean] whether the authentication was revoked.
+    def revoke
+      !!HTTPRequest.new(revoke_params).run
+    end
+
     # @return [String] the email of an authenticated Google account.
     def email
       profile['email']
@@ -37,21 +65,33 @@ module Yt
       tokens['access_token']
     end
 
+    # @return [String] the refresh token of an authenticated Google account.
+    def refresh_token
+      tokens['refresh_token']
+    end
+
   private
 
-    def url_params
+    def self.url_params(options)
       {}.tap do |params|
         params[:client_id] = Yt.configuration.client_id
-        params[:scope] = :email
+        params[:scope] = scope_for(options.fetch :scopes, [])
         params[:access_type] = :offline
-        params[:redirect_uri] = @redirect_uri
+        params[:approval_prompt] = options[:force] ? :force : :auto
+        params[:redirect_uri] = options[:redirect_uri]
         params[:response_type] = :code
       end
     end
 
+    def self.scope_for(scopes)
+      ['userinfo.email'].concat(scopes).map do |scope|
+        "https://www.googleapis.com/auth/#{scope}"
+      end.join(' ')
+    end
+
     # @return [Hash] the tokens of an authenticated Google account.
     def tokens
-      HTTPRequest.new(tokens_params).run.body
+      @tokens ||= HTTPRequest.new(tokens_params).run.body
     end
 
     # @return [Hash] the profile of an authenticated Google account.
@@ -66,34 +106,22 @@ module Yt
         params[:path] = '/o/oauth2/token'
         params[:method] = :post
         params[:request_format] = :form
-        params[:body] = tokens_body
-        params[:error_message] = ->(body) {
-          JSON(body)['error_description'] || token_error_message
-        }
+        params[:body] = @tokens_body
+        params[:error_message] = ->(body) { error_message_for body }
       end
     end
 
-    def tokens_body
+    def revoke_params
       {}.tap do |params|
-        params[:client_id] = Yt.configuration.client_id
-        params[:client_secret] = Yt.configuration.client_secret
-        if @refresh_token
-          params[:refresh_token] = @refresh_token
-          params[:grant_type] = :refresh_token
-        else
-          params[:code] = @code
-          params[:redirect_uri] = @redirect_uri
-          params[:grant_type] = :authorization_code
-        end
+        params[:host] = 'accounts.google.com'
+        params[:path] = '/o/oauth2/revoke'
+        params[:params] = {token: refresh_token || access_token}
       end
     end
 
-    def token_error_message
-      if @refresh_token
-        'Invalid refresh token.'
-      else
-        'Invalid authorization code.'
-      end
+    def error_message_for(body)
+      key = @tokens_body[:grant_type].to_s.tr '_', ' '
+      JSON(body)['error_description'] || "Invalid #{key}."
     end
   end
 end

data/lib/yt/auth/version.rb

@@ -2,6 +2,6 @@ module Yt
   class Auth
     # @return [String] the SemVer-compatible gem version.
     # @see http://semver.org
-    VERSION = '0.2.3'
+    VERSION = '0.3.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yt-auth
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-08-24 00:00:00.000000000 Z
+date: 2017-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yt-support