authy 2.7.5 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47e8f178518a9d550bc75f55f17ec06e1e984634977ed408db47a74916851300
-  data.tar.gz: 72c729ad9b44a3119aad7455c93d1029104b55c5099d3b7a358a2f80f2b73470
+  metadata.gz: '08aec3f3f8bccc8bb877ef1d515c45c2805fc7193104710d50dcaf35083d3b46'
+  data.tar.gz: d0016b8b9f0e3d6e6933d12df0b0e028df063ac882179c7c4212c332bb8b0261
 SHA512:
-  metadata.gz: a3e7f285b4b0f7e4ff5b0522726a0def7fdcc77df18b9214bc7e0434cdc8bc5fee6cfcc47149662c0d86935420cd67386d9d4eb5ac774721410150a9f85caf94
-  data.tar.gz: 00b0af3f2d778f1ed2d9c4424c7563ba8ac27718ad8164fe00283d0336f05f8238f5971b375eceecf64cb2de18f837d5e18e32d479b5372cbbbdb1545e7e38c1
+  metadata.gz: e6f18818888c63388541c56e048a87abb0faad1e4fc63cb49a6c69d54a14399698a193958d2c155471cbf60e1da395840a9dd1028642511feb4f008b69b6401e
+  data.tar.gz: 648994e063b3fb777137068fca315e344c84c1149eab9ba0fb5e9c2788cdfc27652efbc88b6918ca85f2e4fc1e63e3cc9540210120325890e20290e76f88aeb9

data/.github/workflows/build.yml

@@ -0,0 +1,21 @@
+name: build
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: [2.5, 2.6, 2.7, head]
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Ruby ${{ matrix.ruby }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - name: Install dependencies
+        run: bundle install
+      - name: Run tests
+        run: bundle exec rspec

data/.gitignore

@@ -55,3 +55,4 @@ examples/db
 .ruby-gemset
 .rvmrc
 
+Gemfile.lock

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog for `Authy`
+
+## Ongoing [☰](https://github.com/twilio/authy-ruby/compare/v3.0.0...master)
+
+## 3.0.0 (14 December, 2020) [☰](https://github.com/twilio/authy-ruby/compare/v2.7.5...v3.0.0)
+
+* Major updates
+  * Removed Phone Intelligence APIs
+  * Deprecated Phone Verification APIs (use the Twilio Verify API instead: https://twil.io/verify-start-ruby)
+  * Mocked API requests in tests, removed Sandbox API
+* Minor updates
+  * Added API calls for requesting an email and updating a user's email address (#68)
+  * Removed polyfills for try_convert
+  * Updates to insecure dependencies
+
+## 2.7.5 and older
+
+Please check the [commit log](https://github.com/twilio/authy-ruby/compare/f9e9236...v2.7.5).

data/Gemfile

@@ -1,13 +1,3 @@
 source "https://rubygems.org"
 
-gem 'httpclient', ">= 2.5.3.3"
-
-group :development do
-  gem "rspec"
-  gem 'pry'
-  gem "yard", "~> 0.9.11"
-  gem "rdoc"
-  gem "jeweler"
-  gem "simplecov", ">= 0"
-  gem "reek"
-end
+gemspec

data/README.md

@@ -1,232 +1,76 @@
-# Authy [![Build Status](https://travis-ci.org/twilio/authy-ruby.png?branch=master)](https://travis-ci.org/twilio/authy-ruby) [![Code Climate](https://codeclimate.com/github/authy/authy-ruby.png)](https://codeclimate.com/github/authy/authy-ruby)
+[![Gem Version](https://badge.fury.io/rb/authy.svg)](https://rubygems.org/gems/authy/) [![Build Status](https://github.com/twilio/authy-ruby/workflows/build/badge.svg)](https://github.com/twilio/authy-ruby/actions) [![Code Climate](https://codeclimate.com/github/authy/authy-ruby.png)](https://codeclimate.com/github/authy/authy-ruby)
 
-Ruby library to access the Authy API
+# Ruby Client for Twilio Authy Two-Factor Authentication (2FA) API
 
-## Usage
-
-```ruby
-    require 'authy'
-
-    Authy.api_key = 'your-api-key'
-    Authy.api_uri = 'https://api.authy.com'
-```
-
-Using Ruby on Rails? _Put this in **config/initializers** and create a new file called **authy.rb**._
-
-## Registering a user
-
-__NOTE: User is matched based on cellphone and country code not e-mail.
-A cellphone is uniquely associated with an authy_id.__
-
-
-`Authy::API.register_user` requires the user e-mail address and cellphone. Optionally you can pass in the country_code or we will asume
-USA. The call will return you the authy id for the user that you need to store in your database.
-
-Assuming you have a `users` database with a `authy_id` field in the `users` database.
-
-```ruby
-    authy = Authy::API.register_user(:email => 'users@email.com', :cellphone => "111-111-1111", :country_code => "1")
-
-    if authy.ok?
-      self.authy_id = authy.id # this will give you the user authy id to store it in your database
-    else
-      authy.errors # this will return an error hash
-    end
-```
-
-## Verifying a user
-
-
-__NOTE: Token verification is only enforced if the user has completed registration. To change this behaviour see Forcing Verification section below.__
-
-   >*Registration is completed once the user installs and registers the Authy mobile app or logins once successfully using SMS.*
-
-`Authy::API.verify` takes the authy_id that you are verifying and the token that you want to verify. You should have the authy_id in your database
-
-```ruby
-    response = Authy::API.verify(:id => user.authy_id, :token => 'token-user-entered')
-
-    if response.ok?
-      # token was valid, user can sign in
-    else
-      # token is invalid
-    end
-```
-
-### Forcing Verification
-
-If you wish to verify tokens even if the user has not yet complete registration, pass force=true when verifying the token.
-
-```ruby
-    response = Authy::API.verify(:id => user.authy_id, :token => 'token-user-entered', :force => true)
-```
-
-## Requesting a SMS token
-
-`Authy::API.request_sms` takes the authy_id that you want to send a SMS token. This requires Authy SMS plugin to be enabled.
-
-```ruby
-    response = Authy::API.request_sms(:id => user.authy_id)
-
-    if response.ok?
-      # sms was sent
-    else
-      response.errors
-      #sms failed to send
-    end
-```
-
-This call will be ignored if the user is using the Authy Mobile App. If you still want to send
-the SMS pass force=true as an option
-
-```ruby
-    response = Authy::API.request_sms(:id => user.authy_id, :force => true)
-```
+Documentation for Ruby usage of the Authy API lives in the [official Twilio documentation](https://www.twilio.com/docs/authy/api/).
 
-If you wish to send SMS in a specific language, you can provide locale information in the params as shown below.
-
-```ruby
-    response = Authy::API.request_sms(:id => user.authy_id, :force => true, :locale => 'es')
-```
+The Authy API supports multiple channels of 2FA:
+* One-time passwords via SMS and voice.
+* Soft token ([TOTP](https://www.twilio.com/docs/glossary/totp) via the Authy App)
+* Push authentication via the Authy App
 
-If the locale that you provide is wrong or does not match, the SMS will be sent in english.
+If you only need SMS and Voice support for one-time passwords, we recommend using the [Twilio Verify API](https://www.twilio.com/docs/verify/api) instead.
 
-## Requesting token via a phone call
+[More on how to choose between Authy and Verify here.](https://www.twilio.com/docs/verify/authy-vs-verify)
 
-`Authy::API.request_phone_call` takes the authy_id that you want to deliver the token by a phone call. This requires Authy Calls addon, please contact us to support@authy.com to enable this addon.
+### Authy Quickstart
 
-```ruby
-    response = Authy::API.request_phone_call(:id => user.authy_id)
-
-    if response.ok?
-      # call was done
-    else
-      response.errors
-      # call failed
-    end
-```
+For a full tutorial, check out either of the Ruby Authy Quickstart in our docs:
+* [Ruby/Rails Authy Quickstart](https://www.twilio.com/docs/authy/quickstart/two-factor-authentication-ruby-rails)
 
-This call will be ignored if the user is using the Authy Mobile App. If you ensure that user receives the phone call, you must pass force=true as an option
+## Authy Ruby Installation
 
-```ruby
-    response = Authy::API.request_phone_call(:id => user.authy_id, :force => true)
 ```
-
-## Requesting QR code for authenticator apps like Google Authenticator
-
-`Authy::API.request_qr_code` takes authy_id that you want to deliver the qr code. This requires **Generic authenticator tokens** to be enabled in Authy console setting. Optinally, you can provide `qr_size` as a number to decide the output of qr image (For example: `qr_size: 400` will returns a 400x400 image) and `label` as a custom label to be shown by the authenticator app.  
-
-```ruby
-    response = Authy::API.request_qr_code(id: user.authy_id, qr_size: 500, label: "My Example App")
-    if response.ok?
-      # qr code was generated
-    else
-      response.errors
-    end
-
-    # You can access the iamge link with
-    link = response.qr_code
+gem install authy
 ```
 
-## Deleting users
+## Usage
 
-`Authy::API.delete_user` takes the authy_id of the user that you want to remove from your app.
+To use the Authy client, require the `authy` gem and initialize it with our API URI and your production API Key found in the [Twilio Console](https://www.twilio.com/console/authy/applications/):
 
 ```ruby
-    response = Authy::API.delete_user(:id => user.authy_id)
-
-    if response.ok?
-      # the user was deleted
-    else
-      response.errors
-      # we were unavailable to delete the user
-    end
-```
-
-## User status
-
-`Authy::API.user_status` takes the authy_id of the user that you want to get the status from your app.
+require 'authy'
 
-```ruby
-    response = Authy::API.user_status(:id => user.authy_id)
-
-    if response.ok?
-      # do something with user status
-    else
-      response.errors
-      # the user doesn't exist
-    end
+Authy.api_uri = 'https://api.authy.com'
+Authy.api_key = 'your-api-key'
 ```
 
-## Phone Verification
-
-### Starting a phone verification
-
-`Authy::PhoneVerification.start` takes a country code, phone number and a method (sms or call) to deliver the code.  You can also provide a custom_code but this feature needs to be enabled by support@twilio.com
-
-```ruby
-response = Authy::PhoneVerification.start(via: "sms", country_code: 1, phone_number: "111-111-1111")
-if response.ok?
-  # verification was started
-end
-```
+Rails users can put this in config/initializers and create a new file called `authy.rb`.
 
-### Checking a phone verification
+![authy api key in console](https://s3.amazonaws.com/com.twilio.prod.twilio-docs/images/account-security-api-key.width-800.png)
 
-`Authy::PhoneVerification.check` takes a country code, phone number and a verification code.
+## 2FA Workflow
 
-```ruby
-response = Authy::PhoneVerification.check(verification_code: "1234", country_code: 1, phone_number: "111-111-1111")
-if response.ok?
-  # verification was successful
-end
-```
+1. [Create a user](https://www.twilio.com/docs/authy/api/users#enabling-new-user)
+2. [Send a one-time password](https://www.twilio.com/docs/authy/api/one-time-passwords)
+3. [Verify a one-time password](https://www.twilio.com/docs/authy/api/one-time-passwords#verify-a-one-time-password)
 
-## OneTouch Verification
+**OR**
 
-Another way to provide Two_factor authentication with Authy is by using OneTouch feature. 
-Check the [official docs](http://docs.authy.com/onetouch_getting_started.html)
+1. [Create a user](https://www.twilio.com/docs/authy/api/users#enabling-new-user)
+2. [Send a push authentication](https://www.twilio.com/docs/authy/api/push-authentications)
+3. [Check a push authentication status](https://www.twilio.com/docs/authy/api/push-authentications#check-approval-request-status)
 
-`Authy::OneTouch.send_approval_request` takes the Authy user ID, a message to fill up the push notification
-body, an optional hash details for the user and another optional hash for hidden details for internal app
-control.
 
-```ruby
-one_touch = Authy::OneTouch.send_approval_request(
-        id: @user.authy_id,
-        message: "Request to Login",
-        details: {
-          'Email Address' => @user.email,
-        },
-        hidden_details: { ip: '1.1.1.1' }
-      )
-```
+## <a name="phone-verification"></a>Phone Verification
 
-As soon as the user approves or reject the push notification, Authy will hit a callback endpoint
-(set into Dashboard) updating user's `authy_status` flag. You might have an endpoint in a controller
-such as:
+[Phone verification now lives in the Twilio API](https://www.twilio.com/docs/verify/api) and has [Ruby support through the official Twilio helper libraries](https://www.twilio.com/docs/libraries/ruby).
 
-```ruby
-def callback
-    authy_id = params[:authy_id]
-    @user = User.find_by authy_id: authy_id
-    @user.update(authy_status: params[:status])
-  end
-```
+[Legacy (V1) documentation here.](verify-legacy-v1.md) **Verify V1 is not recommended for new development. Please consider using [Verify V2](https://www.twilio.com/docs/verify/api)**.
 
+## Demo
 
-## Contributing to authy
+See the [`./examples`](./examples) directory for a demo CLI application that uses the Authy API.
 
+## Contributing
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
 * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
 * Fork the project.
 * Start a feature/bugfix branch.
 * Commit and push until you are happy with your contribution.
-* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
-* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+* Add tests.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit.
 
-Copyright
-==
+## Copyright
 
-Copyright (c) 2011-2020 Authy Inc. See LICENSE.txt for
-further details.
+Copyright (c) 2011-2020 Authy Inc. See [LICENSE](https://github.com/twilio/authy-ruby/blob/master/LICENSE.txt) for further details.

data/authy.gemspec

@@ -13,8 +13,6 @@ Gem::Specification.new do |s|
   s.description = %q{Ruby library to access Authy services}
   s.license = 'MIT'
 
-  s.rubyforge_project = "authy"
-
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }

data/examples/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+gem "authy"
+gem "sqlite3"
+gem "activerecord"
+gem "highline"

data/examples/README.md

@@ -0,0 +1,48 @@
+# Demo
+
+In this `example` directory is a demo of using the Twilio Authy Two-Factor Authentication (2FA) API with the Authy gem.
+
+## How does it work?
+
+The demo works on the command line and allows you to register a user in your Authy application, request a token for that user and verify a token for a user. Registered users and their authy_id token are stored in a local SQLite database.
+
+## How to use the demo
+
+Change into the `examples` directory and install the dependencies with:
+
+```bash
+bundle install
+```
+
+Then, run the demo with:
+
+```bash
+./demo.rb
+```
+
+You will be asked for your Authy API key then presented a list of options.
+
+```bash
+$ ./demo.rb
+
+Enter your Authy API Key (won't be displayed):
+1. Register a user
+2. Request token
+3. Verify token
+What do you want to do?
+```
+
+On the first run, choose to register a user. This will ask you for an email address, country code and phone number. With those details a user will be registered with your Authy application and stored in your local database.
+
+Then you can run the application and either request a token, to have a token sent by SMS, or verify a token, you can use the token from an SMS or the Authy app to verify.
+
+### API keys
+
+You will be asked for your Authy API key each time you run the demo. You can avoid this by [adding your Authy API key to your environment variables](https://www.twilio.com/blog/2017/01/how-to-set-environment-variables.html).
+
+```
+export AUTHY_API_KEY=ABC123xxxxx
+./demo.rb
+```
+
+Check out the code in `./examples/demo.rb` to see how the API and this gem is used.

data/examples/demo.rb

@@ -5,12 +5,11 @@ require 'sqlite3'
 require 'active_record'
 require 'highline/import' # gem install highline
 
-Authy.api_url = "http://sandbox-api.authy.com"
-Authy.api_key = "a1ffc30aa2d775c7ebebe45585727fe0"
+trap("SIGINT") { exit! }
 
 # setup db
 ActiveRecord::Base.establish_connection(:adapter => "sqlite3", :database => "db")
-class AddUsers < ActiveRecord::Migration
+class AddUsers < ActiveRecord::Migration[6.0]
   def self.up
     create_table :users do |t|
       t.string :email
@@ -28,11 +27,15 @@ class User < ActiveRecord::Base
   validates_uniqueness_of :email
 end
 
+api_key = ENV["AUTHY_API_KEY"] || ask("Enter your Authy API Key (won't be displayed): "){ |q| q.echo = false }
+
+Authy.api_url = "https://api.authy.com"
+Authy.api_key = api_key
 
 choose do |menu|
-  menu.prompt = "what do you want to do? "
+  menu.prompt = "What do you want to do? "
 
-  menu.choice(:register) do
+  menu.choice("Register a user") do
     loop do
       email = ask("email: ")
       country_code = ask("country code: ")
@@ -55,9 +58,8 @@ choose do |menu|
     end
   end
 
-  menu.choice(:login) do
+  menu.choice("Request token") do
     email = ask("email: ")
-    token = ask("token: ")
 
     user = User.where(:email => email).first
     if !user
@@ -65,17 +67,18 @@ choose do |menu|
       return
     end
 
-    # verify if the given token is correct. `force` makes it validate the code even if the user has not confirmed its account
-    otp = Authy::API.verify(:id => user.authy_id, :token => token, :force => true)
+    # send sms to the user. `force` makes it send the sms even if the user uses a smartphone
+    # this api call will return an error if the account doesn't have the SMS addon enabled
+    response = Authy::API.request_sms(:id => user.authy_id, :force => true)
 
-    if otp.ok?
-      puts "Welcome back!"
+    if response.ok?
+      puts "Message was sent"
     else
-      puts "Wrong email or token :("
+      puts "Failed to send message: #{response.errors.inspect}"
     end
   end
 
-  menu.choice(:request_token) do
+  menu.choice("Verify token") do
     email = ask("email: ")
 
     user = User.where(:email => email).first
@@ -84,14 +87,15 @@ choose do |menu|
       return
     end
 
-    # send sms to the user. `force` makes it send the sms even if the user uses a smartphone
-    # this api call will return an error if the account doesn't have the SMS addon enabled
-    response = Authy::API.request_sms(:id => user.authy_id, :force => true)
+    token = ask("token: ")
 
-    if response.ok?
-      puts "Message was sent"
+    # verify if the given token is correct. `force` makes it validate the code even if the user has not confirmed its account
+    otp = Authy::API.verify(:id => user.authy_id, :token => token, :force => true)
+
+    if otp.ok?
+      puts "Welcome back!"
     else
-      puts "Failed to send message: #{response.errors.inspect}"
+      puts "Wrong email or token :("
     end
   end
 end