otp-jwt 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 21a9ead6fc616488ac4b250bddf20522ed33d38b
+  data.tar.gz: d2f7ebaf6e27df53693ca7ce9cb733967ede96e7
+SHA512:
+  metadata.gz: d6b0faa09edf95831f1874200b28e87bf7da8d156f6f7af28940f28afe5e04b1ecb869d78278d88de2b4a6ae62ffb37dab31cea7110ae42d86f0497155e6f98e
+  data.tar.gz: 1983f079088fc8b7b3a222ec6df065483f84d3ca072f369284b643ee024271b20cc865f7aa39ddbf2d84eadb90cbc8120748b69e1624ac0c75556f04e8e4e64e

data/.github/main.workflow

@@ -0,0 +1,30 @@
+workflow "Tests" {
+  on = "push"
+  resolves = [
+    "rspec-ruby2.6_rails4",
+    "rspec-ruby2.6_rails5"
+  ]
+}
+
+action "rspec-ruby2.6_rails4" {
+  uses = "docker://ruby:2.6-alpine"
+  env = {
+    RAILS_VERSION = "~> 4"
+  }
+  args = [
+    "sh", "-c",
+    "apk add -U git build-base sqlite-dev && rm Gemfile.lock && bundle install && rake"
+  ]
+}
+
+action "rspec-ruby2.6_rails5" {
+  uses = "docker://ruby:2.6-alpine"
+  needs = ["rspec-ruby2.6_rails4"]
+  env = {
+    RAILS_VERSION = "~> 5"
+  }
+  args = [
+    "sh", "-c",
+    "apk add -U git build-base sqlite-dev && rm Gemfile.lock && bundle install && rake"
+  ]
+}

data/.gitignore

@@ -0,0 +1,2 @@
+coverage
+pkg

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,46 @@
+inherit_gem:
+  rubocop-rails_config:
+    - config/rails.yml
+
+require:
+  - rubocop-performance
+  - rubocop-rspec
+
+Rails:
+  Enabled: true
+
+RSpec:
+  Enabled: true
+
+RSpec/MultipleExpectations:
+  Enabled: false
+
+Performance:
+  Enabled: true
+
+Bundler:
+  Enabled: true
+
+Gemspec:
+  Enabled: true
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: single_quotes
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Metrics/LineLength:
+  Max: 80
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*_spec.rb'
+    - '**/*.gemspec'
+
+Layout/IndentationConsistency:
+  EnforcedStyle: normal
+
+Style/BlockDelimiters:
+  Enabled: true

data/.yardstick.yml

@@ -0,0 +1,29 @@
+---
+path: ['lib/**/*.rb']
+threshold: 100
+rules:
+  ApiTag::Presence:
+    enabled: false
+  ApiTag::Inclusion:
+    enabled: false
+  ApiTag::ProtectedMethod:
+    enabled: false
+  ApiTag::PrivateMethod:
+    enabled: false
+  ExampleTag:
+    enabled: false
+  ReturnTag:
+    enabled: true
+    exclude: []
+  Summary::Presence:
+    enabled: true
+    exclude: []
+  Summary::Length:
+    enabled: true
+    exclude: []
+  Summary::Delimiter:
+    enabled: true
+    exclude: []
+  Summary::SingleLine:
+    enabled: true
+    exclude: []

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in otp-jwt.gemspec
+gemspec
+
+gem 'rails', ENV['RAILS_VERSION']

data/Gemfile.lock

@@ -0,0 +1,197 @@
+PATH
+  remote: .
+  specs:
+    otp-jwt (0.1.0)
+      activesupport
+      jwt (~> 2.1)
+      rotp (~> 4.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actioncable (5.2.3)
+      actionpack (= 5.2.3)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+    actionmailer (5.2.3)
+      actionpack (= 5.2.3)
+      actionview (= 5.2.3)
+      activejob (= 5.2.3)
+      mail (~> 2.5, >= 2.5.4)
+      rails-dom-testing (~> 2.0)
+    actionpack (5.2.3)
+      actionview (= 5.2.3)
+      activesupport (= 5.2.3)
+      rack (~> 2.0)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.2)
+    actionview (5.2.3)
+      activesupport (= 5.2.3)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.3)
+    activejob (5.2.3)
+      activesupport (= 5.2.3)
+      globalid (>= 0.3.6)
+    activemodel (5.2.3)
+      activesupport (= 5.2.3)
+    activerecord (5.2.3)
+      activemodel (= 5.2.3)
+      activesupport (= 5.2.3)
+      arel (>= 9.0)
+    activestorage (5.2.3)
+      actionpack (= 5.2.3)
+      activerecord (= 5.2.3)
+      marcel (~> 0.3.1)
+    activesupport (5.2.3)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+    addressable (2.6.0)
+      public_suffix (>= 2.0.2, < 4.0)
+    arel (9.0.0)
+    ast (2.4.0)
+    builder (3.2.3)
+    concurrent-ruby (1.1.5)
+    crass (1.0.4)
+    diff-lcs (1.3)
+    docile (1.3.1)
+    erubi (1.8.0)
+    ffaker (2.10.0)
+    globalid (0.4.2)
+      activesupport (>= 4.2.0)
+    i18n (1.6.0)
+      concurrent-ruby (~> 1.0)
+    jaro_winkler (1.5.2)
+    json (2.2.0)
+    jwt (2.1.0)
+    loofah (2.2.3)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.5.9)
+    mail (2.7.1)
+      mini_mime (>= 0.1.1)
+    marcel (0.3.3)
+      mimemagic (~> 0.3.2)
+    method_source (0.9.2)
+    mimemagic (0.3.3)
+    mini_mime (1.0.1)
+    mini_portile2 (2.4.0)
+    minitest (5.11.3)
+    nio4r (2.3.1)
+    nokogiri (1.10.2)
+      mini_portile2 (~> 2.4.0)
+    parallel (1.16.2)
+    parser (2.6.2.0)
+      ast (~> 2.4.0)
+    psych (3.1.0)
+    public_suffix (3.0.3)
+    rack (2.0.6)
+    rack-test (1.1.0)
+      rack (>= 1.0, < 3)
+    rails (5.2.3)
+      actioncable (= 5.2.3)
+      actionmailer (= 5.2.3)
+      actionpack (= 5.2.3)
+      actionview (= 5.2.3)
+      activejob (= 5.2.3)
+      activemodel (= 5.2.3)
+      activerecord (= 5.2.3)
+      activestorage (= 5.2.3)
+      activesupport (= 5.2.3)
+      bundler (>= 1.3.0)
+      railties (= 5.2.3)
+      sprockets-rails (>= 2.0.0)
+    rails-dom-testing (2.0.3)
+      activesupport (>= 4.2.0)
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.0.4)
+      loofah (~> 2.2, >= 2.2.2)
+    railties (5.2.3)
+      actionpack (= 5.2.3)
+      activesupport (= 5.2.3)
+      method_source
+      rake (>= 0.8.7)
+      thor (>= 0.19.0, < 2.0)
+    rainbow (3.0.0)
+    rake (12.3.2)
+    rotp (4.1.0)
+      addressable (~> 2.5)
+    rspec-core (3.8.0)
+      rspec-support (~> 3.8.0)
+    rspec-expectations (3.8.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-mocks (3.8.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-rails (3.8.2)
+      actionpack (>= 3.0)
+      activesupport (>= 3.0)
+      railties (>= 3.0)
+      rspec-core (~> 3.8.0)
+      rspec-expectations (~> 3.8.0)
+      rspec-mocks (~> 3.8.0)
+      rspec-support (~> 3.8.0)
+    rspec-support (3.8.0)
+    rubocop (0.66.0)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.5, != 2.5.1.1)
+      psych (>= 3.1.0)
+      rainbow (>= 2.2.2, < 4.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 1.6)
+    rubocop-performance (1.0.0)
+      rubocop (>= 0.58.0)
+    rubocop-rails_config (0.4.4)
+      railties (>= 3.0)
+      rubocop (~> 0.58)
+    rubocop-rspec (1.32.0)
+      rubocop (>= 0.60.0)
+    ruby-progressbar (1.10.0)
+    simplecov (0.16.1)
+      docile (~> 1.1)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
+    sprockets (3.7.2)
+      concurrent-ruby (~> 1.0)
+      rack (> 1, < 3)
+    sprockets-rails (3.2.1)
+      actionpack (>= 4.0)
+      activesupport (>= 4.0)
+      sprockets (>= 3.0.0)
+    sqlite3 (1.3.13)
+    thor (0.20.3)
+    thread_safe (0.3.6)
+    tzinfo (1.2.5)
+      thread_safe (~> 0.1)
+    unicode-display_width (1.5.0)
+    websocket-driver (0.7.0)
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.3)
+    yard (0.9.18)
+    yardstick (0.9.9)
+      yard (~> 0.8, >= 0.8.7.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler
+  ffaker
+  otp-jwt!
+  rails (~> 5)
+  rspec-rails
+  rubocop-performance
+  rubocop-rails_config
+  rubocop-rspec
+  simplecov
+  sqlite3 (~> 1.3.6)
+  yardstick
+
+BUNDLED WITH
+   1.17.3

data/README.md

@@ -0,0 +1,265 @@
+# OTP JWT ⎆
+
+One time password (email, SMS) authentication support for HTTP APIs.
+
+> The man who wrote the book on password management has a confession to make:
+> He blew it.
+>
+>— [WSJ.com](https://www.wsj.com/articles/the-man-who-wrote-those-password-rules-has-a-new-tip-n3v-r-m1-d-1502124118)
+
+This project provides a couple of mixins to help you build
+applications/HTTP APIs without asking your users to provide passwords.
+
+## About
+
+The goal of this project is to provide support for one time passwords
+which are delivered via different channels (email, SMS), along with a
+simple and easy to use JWT authentication.
+
+Main goals:
+ * No _magic_ please
+ * No DSLs please
+ * Less code, less maintenance
+ * Good docs and test coverage
+ * Keep it up-to-date (or at least tell people this is no longer maintained)
+
+The available features include:
+ * Flexible models support for
+   [counter based OTP](https://github.com/mdp/rotp#counter-based-otps)
+ * Flexible JWT token generation helpers for models and arbitrary data
+ * Pluggable authentication based on the OTP and JWT
+ * Pluggable OTP mailer
+ * Pluggable OTP SMS background processing job
+
+
+This little project wouldn't be possible without the previous work on
+[ROTP](https://github.com/mdp/rotp)
+and [JWT](https://github.com/jwt/ruby-jwt/).
+
+Thanks to everyone who worked on these amazing projects!
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'otp-jwt'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install otp-jwt
+
+## Usage
+
+ * [OTP for Active Record models](#otp-for-active-record-models)
+   * [Mailer support](#mailer-support)
+   * [SMS delivery support](#sms-delivery-support)
+ * [JWT for Active Record models](#jwt-for-active-record-models)
+ * [JWT authorization](#jwt-authorization)
+ * [JWT authentication](#jwt-authentication)
+
+---
+
+To start using it with Rails, add this to an initializer and configure your
+keys:
+
+```ruby
+# config/initializers/otp-jwt.rb
+require 'otp'
+# To load the JWT related support.
+require 'otp/jwt'
+
+OTP::JWT::Token.jwt_signature_key = ENV['YOUR-SIGN-KEY']
+```
+### OTP for Active Record models
+
+To add support for OTP to your models, use the `OTP::ActiveRecord` concern:
+
+```ruby
+class User < ActiveRecord::Base
+  include OTP::ActiveRecord
+
+  ...
+end
+```
+
+This will provide two new methods which you can use to generate and verify
+one time passwords:
+ * `User#otp`
+ * `User#verify_otp`
+
+This concern expects two attributes to be provided by the model, the:
+ * `otp_secret`: of type string, used to store the OTP signature key
+ * `otp_counter`: of type integer, used to store the OTP counter
+
+A migration to add these two looks like this:
+```
+$ rails g migration add_otp_to_users otp_secret:string otp_counter:integer
+```
+
+#### Mailer support
+
+You can use the built-in mailer to deliver the OTP, just require it and
+overwrite the helper method:
+
+```ruby
+require 'otp/mailer'
+
+class User < ActiveRecord::Base
+  include OTP::ActiveRecord
+
+  def email_otp
+    OTP::Mailer.otp(email, otp, self).deliver_later
+  end
+end
+```
+
+#### SMS delivery support
+
+You can use the built-in job to deliver the OTP via SMS, just require it and
+overwrite the helper method:
+
+```ruby
+require 'otp/sms_otp_job'
+
+class User < ActiveRecord::Base
+  include OTP::ActiveRecord
+
+  def sms_otp
+    OTP::SMSOTPJob.perform_later(phone_number, otp) if phone_number.present?
+  end
+end
+```
+
+You will have to provide your model with the phone number attribute if you
+want to deliver the OTPs via SMS.
+
+This job requires `aws-sdk-sns` gem to work. You will have to add it manually
+and configure to use the correct keys. The SNS region is fetched from the
+environment variable `AWS_SMS_REGION`.
+
+### JWT for Active Record models
+
+To add support for JWT to your models, use the `OTP::JWT::ActiveRecord` concern:
+
+```ruby
+class User < ActiveRecord::Base
+  include OTP::JWT::ActiveRecord
+
+  ...
+end
+```
+
+This will provide two new methods which you can use to generate and verify JWT
+tokens:
+ * `User#from_jwt`
+ * `User#to_jwt`
+
+### JWT authorization
+
+To add support for JWT to your controllers,
+use the `OTP::JWT::ActionController` concern:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include OTP::JWT::ActionController
+
+  private
+
+  def current_user
+    @jwt_user ||= User.from_jwt(request_authorization_header)
+  end
+
+  def current_user!
+    current_user || raise('User authentication failed')
+  rescue
+    head(:unauthorized)
+  end
+end
+```
+
+The example from above includes helpers you can use interact with the
+currently authenticated user or just use as part of `before_action` callback.
+
+The `request_authorization_header` method is also provided by the concern and
+allows you to customize from where the token is received. A query parameter
+based alternative would look like this:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include OTP::JWT::ActionController
+
+  private
+
+  def current_user
+    @jwt_user ||= User.from_jwt(params[:token])
+  end
+
+  ...
+end
+```
+
+### JWT authentication
+
+The `OTP::JWT::ActionController` concern provides support for handling the
+authentication requests and token generation by using the `jwt_from_otp` method.
+
+Here's an example of a tokens controller:
+
+```ruby
+class TokensController < ApplicationController
+  def create
+    user = User.find_by(email: params[:email])
+
+    jwt_from_otp(user, params[:otp]) do |auth_user|
+      # Let's update the last login date before we send the token...
+      # auth_user.update_column(:last_login_at, DateTime.current)
+
+      render json: { token: auth_user.to_jwt }, status: :created
+    end
+  end
+end
+```
+
+The `jwt_from_otp` does a couple of things here:
+ * It will try to authenticate the user you found by email and respond with
+   a valid JWT token
+ * It will try to schedule an email or SMS delivery of the OTP and it will
+   respond with the 400 HTTP status
+ * It will respond with the 403 HTTP status if there's no user
+   or the OTP is wrong
+
+The OTP delivery is handled by the `User#deliver_otp` method
+and can be customized. By default it will call the `sms_otp` method and
+if nothing is returned, it will proceed with the `email_otp` method.
+
+## Development
+
+After checking out the repo, run `bundle` to install dependencies.
+
+Then, run `rake` to run the tests.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+To release a new version, update the version number in `version.rb`, and then
+run `bundle exec rake release`, which will create a git tag for the version,
+push git commits and tags, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/stas/otp-jwt
+
+This project is intended to be a safe, welcoming space for collaboration, and
+contributors are expected to adhere to the
+[Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+TBD

data/Rakefile

@@ -0,0 +1,30 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+require 'yaml'
+require 'yardstick'
+
+desc('Documentation stats and measurements')
+task('qa:docs') do
+  yaml = YAML.load_file(File.expand_path('../.yardstick.yml', __FILE__))
+  config = Yardstick::Config.coerce(yaml)
+  measure = Yardstick.measure(config)
+  measure.puts
+  coverage = Yardstick.round_percentage(measure.coverage * 100)
+  exit(1) if coverage < config.threshold
+end
+
+desc('Codestyle check and linter')
+RuboCop::RakeTask.new('qa:code') do |task|
+  task.fail_on_error = true
+  task.patterns = [
+    'lib/**/*.rb',
+    'spec/**/*.rb'
+  ]
+end
+
+desc('Run CI QA tasks')
+task(qa: ['qa:docs', 'qa:code'])
+
+RSpec::Core::RakeTask.new(spec: :qa)
+task(default: :spec)

data/lib/otp/active_record.rb

@@ -0,0 +1,81 @@
+require 'rotp'
+require 'active_support/concern'
+require 'active_support/configurable'
+
+module OTP
+  # [ActiveRecord] concern.
+  module ActiveRecord
+    include ActiveSupport::Configurable
+    extend ActiveSupport::Concern
+
+    # Length of the generated OTP, defaults to 4.
+    OTP_DIGITS = 4
+
+    included do
+      after_initialize :setup_otp
+    end
+
+    # Generates the OTP
+    #
+    # @return [String] or nil if no OTP is set
+    def otp
+      return nil unless valid? && persisted?
+      otp_digits = self.class.const_get(:OTP_DIGITS)
+      hotp = ROTP::HOTP.new(otp_secret, digits: otp_digits)
+
+      transaction do
+        increment!(:otp_counter)
+        hotp.at(otp_counter)
+      end
+    end
+
+    # Verifies the OTP
+    #
+    # @return true on success, false on failure
+    def verify_otp(otp)
+      hotp = ROTP::HOTP.new(otp_secret, digits: OTP_DIGITS)
+      transaction do
+        otp_status = hotp.verify(otp.to_s, otp_counter)
+        increment!(:otp_counter)
+        otp_status
+      end
+    end
+
+    # Helper to send the OTP using the SMS job
+    #
+    # Does nothing. Implement your own handler.
+    #
+    # @return [OTP::API::SMSOTPJob] instance of the job
+    def sms_otp
+    end
+
+    # Helper to email the OTP using a job
+    #
+    # Does nothing. Implement your own handler.
+    #
+    # @return [OTP::API::Mailer] instance of the job
+    def email_otp
+    end
+
+    # Helper to deliver the OTP
+    #
+    # Will use the SMS job if the phone number is available.
+    # Will default to the email delivery.
+    #
+    # @return [ActiveJob::Base] instance of the job
+    def deliver_otp
+      return unless persisted?
+      sms_otp || email_otp || raise(NotImplementedError, self)
+    end
+
+    private
+
+    # Provides a default value for the OTP secret attribute
+    #
+    # @return [String]
+    def setup_otp
+      self.otp_secret ||= ROTP::Base32.random_base32
+      self.otp_counter ||= 0
+    end
+  end
+end

data/lib/otp/jwt/action_controller.rb

@@ -0,0 +1,36 @@
+module OTP
+  module JWT
+    # [ActionController] concern.
+    module ActionController
+      private
+
+      # Authenticates a model and responds with a [JWT] token
+      #
+      # @return [String] with authentication token and country shop ID.
+      def jwt_from_otp(model, otp)
+        # Send the OTP if the model is trying to authenticate.
+        if model.present? && otp.blank?
+          job = model.deliver_otp
+          return render(json: { job_id: job.job_id }, status: :bad_request)
+        elsif model.present? && otp.present? && !model.verify_otp(otp)
+          return head(:forbidden)
+        elsif model.blank?
+          return head(:forbidden)
+        end
+
+        return yield(model) if block_given?
+
+        render json: { token: model.to_jwt }, status: :created
+      end
+
+      # Extracts a token from the authorization header
+      #
+      # @return [String] the token present in the header or nothing.
+      def request_authorization_header
+        return if request.headers['Authorization'].blank?
+
+        request.headers['Authorization'].split.last
+      end
+    end
+  end
+end

data/lib/otp/jwt/active_record.rb

@@ -0,0 +1,29 @@
+require 'active_support/concern'
+
+module OTP
+  module JWT
+    # [ActiveRecord] concern.
+    module ActiveRecord
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # Returns a record based on the [JWT] token subject
+        #
+        # @param token [String] representing a [JWT] token
+        # @return [ActiveRecord::Base] model
+        def from_jwt(token)
+          OTP::JWT::Token.decode(token) do |payload|
+            self.find_by(id: payload['sub'])
+          end
+        end
+      end
+
+      # Returns a [JWT] token for this record
+      #
+      # @return [ActiveRecord::Base] model
+      def to_jwt
+        OTP::JWT::Token.sign(sub: self.id)
+      end
+    end
+  end
+end

data/lib/otp/jwt/test_helpers.rb

@@ -0,0 +1,27 @@
+require 'json'
+
+module OTP
+  module JWT
+    # Helpers to help you test the [JWT] requests.
+    module TestHelpers
+      # Helper to handle authentication requests easier
+      #
+      # @return [Hash] the authorization headers
+      def jwt_auth_header(entity_or_subject)
+        return {} unless entity_or_subject.present?
+
+        token = entity_or_subject.try(:to_jwt)
+        token ||= OTP::JWT::Token.sign(sub: entity_or_subject)
+
+        { 'Authorization': "Bearer #{token}" }
+      end
+
+      # Parses and returns a deserialized JSON
+      #
+      # @return [Hash]
+      def response_json
+        JSON.parse(response.body)
+      end
+    end
+  end
+end

data/lib/otp/jwt/token.rb

@@ -0,0 +1,69 @@
+require 'jwt'
+require 'active_support/configurable'
+
+module OTP
+  module JWT
+    # A configurable set of token helpers to sign/verify an entity JWT token.
+    module Token
+      include ActiveSupport::Configurable
+
+      # Resolves possible JWT exception classes
+      #
+      # Can be removed once #255 is merged.
+      # See: https://github.com/jwt/ruby-jwt/pull/255
+      JWT_EXCEPTIONS = ::JWT.constants.map do |cname|
+        klass = ::JWT.const_get(cname)
+        klass if klass.is_a?(Class) && klass <= StandardError
+      end.compact
+
+      # The signature key used to sign the tokens.
+      config_accessor :jwt_signature_key, instance_accessor: false
+      # The signature key algorithm, defaults to HS256.
+      config_accessor(:jwt_algorithm, instance_accessor: false) { 'HS256' }
+      # The lifetime of the token, defaults to 1 day.
+      config_accessor(:jwt_lifetime, instance_accessor: false) { 60 * 60 * 24 }
+
+      # Generates a token based on a payload and optional overwritable claims
+      #
+      # @param payload [Hash], data to be encoded into the token.
+      # @param claims [Hash], extra claims to be encoded into the token.
+      #
+      # @return [String], a JWT token
+      def self.sign(payload, claims = {})
+        payload = payload.merge(claims)
+        claims[:exp] ||= self.jwt_lifetime if self.jwt_lifetime.present?
+
+        ::JWT.encode(payload, self.jwt_signature_key, self.jwt_algorithm)
+      end
+
+      # Verifies and returns decoded token data upon success
+      #
+      # @param token [String], token to be decoded.
+      # @param options [Hash], extra options to be used during verification.
+      #
+      # @return [Hash], JWT token payload
+      def self.verify(token, options = {})
+        lifetime = self.jwt_lifetime
+        opts = {}.merge(options)
+        opts[:verify_expiration] ||= lifetime if lifetime.present?
+
+        ::JWT.decode(token.to_s, self.jwt_signature_key, true, opts)
+      end
+
+      # Decodes a valid token into [Hash]
+      #
+      # Requires a block, yields JWT data. Will catch any JWT exception.
+      #
+      # @param token [String], token to be decoded.
+      # @param options [Hash], extra options to be used during verification.
+      # @return [Hash] upon success
+      def self.decode(token, options = nil)
+        return unless block_given?
+        verified, _ = self.verify(token, options || {})
+
+        yield verified
+      rescue *JWT_EXCEPTIONS
+      end
+    end
+  end
+end

data/lib/otp/jwt/version.rb

@@ -0,0 +1,5 @@
+module OTP
+  module JWT
+    VERSION = '0.1.0'
+  end
+end

data/lib/otp/jwt.rb

@@ -0,0 +1,10 @@
+require_relative 'jwt/token'
+require_relative 'jwt/active_record'
+require_relative 'jwt/action_controller'
+
+module OTP
+  # JWT
+  module JWT
+    # ...
+  end
+end

data/lib/otp/mailer/otp.text.erb

@@ -0,0 +1,6 @@
+Hi there 👋,
+
+Please use this magic password to access your account:
+<%= @otp_code %>
+
+Thank you!

data/lib/otp/mailer.rb

@@ -0,0 +1,25 @@
+require 'action_mailer/railtie'
+require_relative '../otp'
+
+module OTP
+  # OTP mailer.
+  class Mailer < ActionMailer::Base
+    append_view_path(OTP::PATH)
+
+    default subject: 'Your magic password 🗝️'
+
+    # Sends an email containing the OTP
+    #
+    # @param email [String] the email address to send to
+    # @param otp_code [String] the OTP code to include
+    # @param model [ActiveRecord::Base] model to expose
+    # @param mail_opts [Hash] arbitrary options to pass to `mail()` method
+    # @return [Mail] instance
+    def otp(email, otp_code, model, mail_opts = {})
+      @model = model
+      @otp_code = otp_code
+
+      mail(to: email, **mail_opts)
+    end
+  end
+end

data/lib/otp/sms_otp_job.rb

@@ -0,0 +1,28 @@
+require 'active_job/railtie'
+begin
+  require 'aws-sdk-sns'
+rescue LoadError => err
+  (Rails.logger || Logger.new(STDOUT)).error(err)
+end
+
+module OTP
+  # Uses the AWS SNS API to send the OTP SMS message.
+  class SMSOTPJob < ActiveJob::Base
+    # A generic template for the message body.
+    TEMPLATE = '%{otp} is your magic password 🗝️'
+    # Indicates if the messaging is disabled. Handy for testing purposes.
+    ENABLED = true
+
+    # Sends the SMS message with the OTP code
+    #
+    # @return nil
+    def perform(phone_number, otp_code, template = TEMPLATE)
+      message = template % { otp: otp_code }
+
+      Aws::SNS::Client.new(region: ENV['AWS_SMS_REGION']).publish(
+        message: message,
+        phone_number: phone_number
+      ) if ENABLED
+    end
+  end
+end

data/lib/otp.rb

@@ -0,0 +1,6 @@
+require_relative 'otp/active_record'
+
+# OTP
+module OTP
+  PATH = File.dirname(__FILE__)
+end

data/otp-jwt.gemspec

@@ -0,0 +1,36 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'otp/jwt/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'otp-jwt'
+  spec.version       = OTP::JWT::VERSION
+  spec.authors       = ['Stas Suscov']
+  spec.email         = ['stas@nerd.ro']
+
+  spec.summary       = 'Passwordless HTTP APIs'
+  spec.description   = 'OTP (email, SMS) JWT authentication for HTTP APIs.'
+  spec.homepage      = 'https://github.com/stas/otp-jwt'
+  spec.license       = 'TBD'
+
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(spec)/}) }
+  end
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'activesupport'
+  spec.add_dependency 'jwt', '~> 2.1'
+  spec.add_dependency 'rotp', '~> 4.1'
+
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'ffaker'
+  spec.add_development_dependency 'rails'
+  spec.add_development_dependency 'rspec-rails'
+  spec.add_development_dependency 'rubocop-performance'
+  spec.add_development_dependency 'rubocop-rails_config'
+  spec.add_development_dependency 'rubocop-rspec'
+  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'sqlite3', '~> 1.3.6'
+  spec.add_development_dependency 'yardstick'
+end

metadata

@@ -0,0 +1,247 @@
+--- !ruby/object:Gem::Specification
+name: otp-jwt
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Stas Suscov
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-03-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: rotp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.1'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ffaker
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails_config
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.6
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.6
+- !ruby/object:Gem::Dependency
+  name: yardstick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: OTP (email, SMS) JWT authentication for HTTP APIs.
+email:
+- stas@nerd.ro
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/main.workflow"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".yardstick.yml"
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- lib/otp.rb
+- lib/otp/active_record.rb
+- lib/otp/jwt.rb
+- lib/otp/jwt/action_controller.rb
+- lib/otp/jwt/active_record.rb
+- lib/otp/jwt/test_helpers.rb
+- lib/otp/jwt/token.rb
+- lib/otp/jwt/version.rb
+- lib/otp/mailer.rb
+- lib/otp/mailer/otp.text.erb
+- lib/otp/sms_otp_job.rb
+- otp-jwt.gemspec
+homepage: https://github.com/stas/otp-jwt
+licenses:
+- TBD
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.2.2
+signing_key: 
+specification_version: 4
+summary: Passwordless HTTP APIs
+test_files: []