authify-api 0.3.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 034407bd9058f89a81db15e6d658f16f5d5a5365
-  data.tar.gz: af8a965cc5f481ba754ccd2c5fe79168e35daf68
+  metadata.gz: ee72e82c5e6c776b0cfc07e62c480ef59ecf24fe
+  data.tar.gz: b3dfd57c8aefb052282db076a842d15d6d75dbae
 SHA512:
-  metadata.gz: 3fb4dd7817c46abf6dc0a2342b48281a9f1862123e990f7c9f4af11baa6d408533fad7376eca7740f3fff865c6052ef63efc88f5b4059abdeb0b8c04f25a8375
-  data.tar.gz: ffafbf61deae31c0ae88c4d8d1333fca27464fd557b5876ddab461304f5fe50a84b31a645da7b948ba55925f9e43a0ce213a0957c77e08542b7e785455f81eb1
+  metadata.gz: 1fa30f55edc35e440b3d64522252d28fb90aee4c7b5e3d4c5a5a2df17d9c8e447db3083d8f314d80d01e3054ea1e852ecdd088d9b3fbdeb75e2da9618671f47a
+  data.tar.gz: 9695fdfe722fc53c3cd7741cbfdde9767acbe0c0c8981c77140a926b44f3f34e3db34d43df34b1e9211c77880942fc23d56ef21bc9ebe92d1f9455f748831bc1

data/README.md

@@ -22,9 +22,9 @@ Nearly all API endpoints available via Authify implement the [{json:api}](http:/
 * `GET /jwt/key` - Returns Content Type: `application/json`. This endpoint returns a JSON Object with the key `data` whose value is a PEM-encoded ECDSA public key, which should be used to verify the signature made by the Authify service.
 * `GET /jwt/meta` - Returns Content Type: `application/json`. This endpoint returns a JSON Object with the keys `algorithm`, `issuer`, and `expiration` that describe the kind of JWTs produced by this service.
 * `POST /jwt/token` - Returns (and only accepts) Content Type: `application/json`. This endpoint is used to obtain a [JWT](https://en.wikipedia.org/wiki/JSON_Web_Token). This endpoint expects a JSON Object with either the keys `access_key` and `secret_key` _OR_ `email` and `password`. There is no firm requirement to use either pair for any particular purpose, but for scenarios where the credentials may be stored, the `access_key` and `secret_key` may be used since those can easily be revoked if necessary. Upon successful authentication, the endpoint provides a JSON Object with the key `jwt` and a signed JWT. There should be nothing highly sensitive embedded in the JWT. The JWT defaults to expiring every 15 minutes. This endpoint also allows optionally specifying a key called `inject` with a JSON object as a value. This JSON object will then be injected into a top-level `custom` key in the returned JWT _as is_.
-* `POST /registration/signup` - Returns (and only accepts) Content Type: `application/json`. This endpoint is used to signup for an account with Authify. This endpoint expects a JSON Object, requiring the keys `email` and `password`, with `name` and `via` being optional. If `via` is provided, then it must be a JSON Object with the keys `provider` and `uid`, otherwise it will be ignored. The `via` key is used to add an alternate identity (meaning they logged-in through an integration, like Github), and is only trusted from trusted delegates (meaning it will be ignored for anonymous calls to this endpoint). This endpoint returns a JSON Object with the keys `id`, `email`, and `verified`, on success. If the user is registered by a trusted delegate *and* `via` options were provided, the users is implicitly trusted and a `jwt` key will also be provided for authentication.
+* `POST /registration/signup` - Returns (and only accepts) Content Type: `application/json`. This endpoint is used to signup for an account with Authify. This endpoint expects a JSON Object, requiring the keys `email` and `password`, with `name` and `via` being optional. If `via` is provided, then it must be a JSON Object with the keys `provider` and `uid`, otherwise it will be ignored. The `via` key is used to add an alternate identity (meaning they logged-in through an integration, like Github), and is only trusted from trusted delegates (meaning it will be ignored for anonymous calls to this endpoint). This endpoint returns a JSON Object with the keys `id`, `email`, and `verified`, on success. If the user is registered by a trusted delegate *and* `via` options were provided, the users is implicitly trusted and a `jwt` key will also be provided for authentication. This endpoint allows customization of the emails sent for users requiring verification. For information on how this works, see the [Templating](#templating) section. The following template expressions are available: `token` and `valid_until`.
 * `POST /registration/verify` - Returns (and only accepts) Content Type: `application/json`. This endpoint is used to verify a registered user's email address. This endpoint expects a JSON Object, requiring the keys `email`, `password`, and `token`. This endpoint returns a JSON Object with the keys `id`, `email`, `verified`, and `jwt` on success.
-* `POST /registration/forgot_password` - Returns (and only accepts) Content Type: `application/json`. This endpoint serves two related purposes: it is used to trigger resetting a forgotten (or non-existent) password and it is used to actually set the value of a user's password. The difference in which operation is performed is based on the POST data. When provided a JSON Object with only the key `email`, the endpoint sends the user an email with a verification token, returning an empty JSON Object as a result. When provided a JSON Object with the keys `email`, `password`, and `token`, the endpoint verifies that the token matches, then sets the user's password, returning a JSON Object with the keys `id`, `email`, `verified`, and `jwt` on success.
+* `POST /registration/forgot_password` - Returns (and only accepts) Content Type: `application/json`. This endpoint serves two related purposes: it is used to trigger resetting a forgotten (or non-existent) password and it is used to actually set the value of a user's password. The difference in which operation is performed is based on the POST data. When provided a JSON Object with only the key `email`, the endpoint sends the user an email with a verification token, returning an empty JSON Object as a result. When provided a JSON Object with the keys `email`, `password`, and `token`, the endpoint verifies that the token matches, then sets the user's password, returning a JSON Object with the keys `id`, `email`, `verified`, and `jwt` on success. This endpoint allows customization of the emails sent for users requiring verification. For information on how this works, see the [Templating](#templating) section. The following template expressions are available: `token` and `valid_until`.
 
 All other endpoints adhere to the {json:api} specification and can be found at the following base paths:
 
@@ -109,7 +109,7 @@ curl \
   '{
     "name": "Some User",
     "email": "someuser@mycompany.com",
-    "password": "b@d!dea",
+    "password": "b@d!dea"
   }' \
   https://auth.mycompany.com/registration/signup
 ```
@@ -254,6 +254,70 @@ curl \
   https://auth.mycompany.com/organizations
 ```
 
+### Templating
+
+Some endpoints support custom templates (and other customizations) for communications sent out to users. This is most useful for services that integrate with Authify but wrap that integration in their own UI.
+
+If an endpoint declares that it supports templating (such as `/registration/signup`), what this means is that the JSON `POST` data can include an optional `templates` key. To customize the plaintext email body and subject, you can change a `POST` from something like this:
+
+```javascript
+{
+  "name": "Some User",
+  "email": "someuser@mycompany.com",
+  "password": "b@d!dea"
+}
+```
+
+to include a `templates` section like this:
+
+```javascript
+{
+  "name": "Some User",
+  "email": "someuser@mycompany.com",
+  "password": "b@d!dea",
+  "templates": {
+    "email": {
+      "body": "Your code is: '{{token}}' and it is valid until {{valid_until}}.",
+      "subject": "Verification Code"
+    }
+  }
+}
+```
+
+Authify's templating supports something that looks a bit like [Handlebars](http://handlebarsjs.com/) templating (though it doesn't yet support most of the Handlebars features). This is useful for allowing the injection of dynamic data into your templates. Available expressions should be declared in the README section that describes a template-capable endpoint.
+
+For some template data, escaping can be difficult or inconvenient. For these situations, Authify supports optional [Base64](https://en.wikipedia.org/wiki/Base64) encoding of values. To provide a Base64-encoded value, just declare it as such using `{base64}` followed by the data:
+
+```javascript
+{
+  "name": "Some User",
+  "email": "someuser@mycompany.com",
+  "password": "b@d!dea",
+  "templates": {
+    "email": {
+      "body": "{base64}WW91ciBjb2RlIGlzOiAne3t0b2tlbn19JyBhbmQgaXQgaXMgdmFsaWQgdW50aWwge3t2YWxpZF91bnRpbH19Lg==",
+      "subject": "Verification Code"
+    }
+  }
+}
+```
+
+Encoded template data still supports the Handlebars-style templating, but it must be applied _before_ the content is Base64-encoded.
+
+#### Template Types
+
+Currently, only email communications can be templated. The following keys are available for email templates:
+
+```javascript
+"templates": {
+  "email": {
+    "subject": "The subject of the email",
+    "body": "The plaintext body of the email",
+    "html_body": "<p>An <a href=\"https://en.wikipedia.org/wiki/HTML\">HTML</a> body.</p>"
+  }
+}
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/knuedge/authify-api.

data/lib/authify/api.rb

@@ -44,6 +44,9 @@ require 'authify/api/serializers/group_serializer'
 require 'authify/api/serializers/identity_serializer'
 require 'authify/api/serializers/user_serializer'
 require 'authify/api/serializers/organization_serializer'
+require 'authify/api/helpers/jwt_encryption'
+require 'authify/api/helpers/api_user'
+require 'authify/api/helpers/text_processing'
 require 'authify/api/models/apikey'
 require 'authify/api/models/group'
 require 'authify/api/models/identity'
@@ -51,8 +54,6 @@ require 'authify/api/models/organization'
 require 'authify/api/models/organization_membership'
 require 'authify/api/models/trusted_delegate'
 require 'authify/api/models/user'
-require 'authify/api/helpers/jwt_encryption'
-require 'authify/api/helpers/api_user'
 require 'authify/api/service'
 require 'authify/api/metrics'
 require 'authify/api/middleware/metrics'

data/lib/authify/api/helpers/text_processing.rb

@@ -0,0 +1,37 @@
+module Authify
+  module API
+    module Helpers
+      # Helper methods for working with different text formats
+      module TextProcessing
+        def valid_formats
+          [:base64]
+        end
+
+        def decoded_hash(hash)
+          hash.update(hash) { |_, v| v.is_a?(String) ? human_readable(v) : v }
+        end
+
+        # Interpolates handlebars-style templates
+        # OPTIMIZE: this can probably be faster
+        def dehandlebar(text, data = {})
+          text.gsub(/{{([a-z0-9_-]+)}}/) { data[Regexp.last_match[1].to_sym].to_s }
+        end
+
+        def human_readable(text)
+          if text =~ /^\{([a-zA-Z0-9]+)\}([^\n]+)$/
+            form, data = text.match(/^\{([a-zA-Z0-9]+)\}([^\n]+)$/)[1, 2]
+
+            raise "Invalid Conversion: #{form}" unless valid_formats.include?(form.downcase.to_sym)
+            send("from_#{form.downcase}".to_sym, data)
+          else
+            text
+          end
+        end
+
+        def from_base64(text)
+          Base64.decode64 text
+        end
+      end
+    end
+  end
+end

data/lib/authify/api/metrics.rb

@@ -5,15 +5,11 @@ module Authify
       include Singleton
 
       def update(key, value)
-        write_lock do
-          storage[key] = value
-        end
+        storage[key] = value
       end
 
       def increment(key, change = 1)
-        write_lock do
-          storage.key?(key) ? storage[key] += change : storage[key] = change
-        end
+        storage.key?(key) ? storage[key] += change : storage[key] = change
       end
 
       def decrement(key, change = 1)
@@ -39,13 +35,6 @@ module Authify
 
       private
 
-      def write_lock
-        @wlock ||= Mutex.new
-        @wlock.synchronize do
-          yield
-        end
-      end
-
       def storage
         # While not perfectly thread-safe, this works well enough for Metrics
         @storage ||= Concurrent::Map.new

data/lib/authify/api/middleware/metrics.rb

@@ -15,6 +15,7 @@ module Authify
           end
 
           @metrics.increment construct_metric_key('count', env)
+          @metrics.increment 'rack.request.count'
 
           [status, header, body]
         end

data/lib/authify/api/models/user.rb

@@ -5,6 +5,7 @@ module Authify
       class User < ActiveRecord::Base
         include Core::SecureHashing
         include JSONAPIUtils
+        include Helpers::TextProcessing
 
         attr_reader :password
 
@@ -49,22 +50,31 @@ module Authify
         end
 
         # Both sets a token in the DB *and* emails it to the user
-        def set_verification_token!
+        def add_verification_token!(opts = {})
           return false if verified?
           token = peppered_sha512(rand(999).to_s)[0...16]
-          valid_until = (Time.now + (15 * 60)).to_i
+          valid_time  = Time.now + (15 * 60)
+          valid_until = valid_time.to_i
           self.verification_token = "#{token}:#{valid_until}"
 
+          subdata = { token: token, valid_until: valid_time }
+
           email_opts = {
-            body: "Your verification token is: #{token}"
+            body: if opts.key?(:body)
+                    dehandlebar(opts[:body], subdata)
+                  else
+                    "Your verification token is: #{token}"
+                  end
           }
 
-          Resque.enqueue(
-            Authify::Core::Jobs::Email,
-            email,
-            'Authify Verification Email',
-            email_opts
-          )
+          email_opts[:html_body] = dehandlebar(opts[:html_body], subdata) if opts.key?(:html_body)
+          subject = if opts.key?(:subject)
+                      dehandlebar(opts[:subject], subdata)
+                    else
+                      'Authify Verification Email'
+                    end
+
+          Resque.enqueue Authify::Core::Jobs::Email, email, subject, email_opts
         end
 
         def admin_for?(organization)

data/lib/authify/api/services/api.rb

@@ -29,19 +29,40 @@ module Authify
           end
         end
 
-        before '*' do
-          # headers 'Access-Control-Allow-Origin' => '*',
-          #        'Access-Control-Allow-Methods' => %w(
-          #          OPTIONS
-          #          DELETE
-          #          GET
-          #          PATCH
-          #          POST
-          #          PUT
-          #        )
+        before do
           determine_roles
         end
 
+        after do
+          headers 'Access-Control-Allow-Origin' => '*',
+                  'Access-Control-Allow-Methods' => response['Allow'] || %w[
+                    OPTIONS
+                    GET
+                    POST
+                    PUT
+                    PATCH
+                    DELETE
+                    HEAD
+                  ],
+                  'Access-Control-Allow-Headers' => %w[
+                    Origin
+                    Accept
+                    Accept-Encoding
+                    Accept-Language
+                    Access-Control-Request-Headers
+                    Access-Control-Request-Method
+                    Authorization
+                    Connection
+                    Content-Type
+                    Host
+                    Referer
+                    User-Agent
+                    X-Requested-With
+                    X-Forwarded-For
+                    X-XSRF-Token
+                  ]
+        end
+
         resource :apikeys, &Controllers::APIKey
         resource :identities, &Controllers::Identity
         resource :groups, &Controllers::Group

data/lib/authify/api/services/jwt_provider.rb

@@ -11,14 +11,22 @@ module Authify
           set :protection, except: :http_origin
         end
 
-        before '*' do
+        before do
           content_type 'application/json'
+
+          begin
+            unless request.get? || request.options?
+              request.body.rewind
+              @parsed_body = JSON.parse(request.body.read, symbolize_names: true)
+            end
+          rescue => e
+            halt(400, { error: "Request must be valid JSON: #{e.message}" }.to_json)
+          end
+        end
+
+        after do
           headers 'Access-Control-Allow-Origin' => '*',
-                  'Access-Control-Allow-Methods' => %w[
-                    OPTIONS
-                    GET
-                    POST
-                  ],
+                  'Access-Control-Allow-Methods' => %w[OPTIONS GET POST],
                   'Access-Control-Allow-Headers' => %w[
                     Origin
                     Accept
@@ -26,6 +34,7 @@ module Authify
                     Accept-Language
                     Access-Control-Request-Headers
                     Access-Control-Request-Method
+                    Authorization
                     Connection
                     Content-Type
                     Host
@@ -33,16 +42,8 @@ module Authify
                     User-Agent
                     X-Requested-With
                     X-Forwarded-For
+                    X-XSRF-Token
                   ]
-
-          begin
-            unless request.get? || request.options?
-              request.body.rewind
-              @parsed_body = JSON.parse(request.body.read, symbolize_names: true)
-            end
-          rescue => e
-            halt(400, { error: "Request must be valid JSON: #{e.message}" }.to_json)
-          end
         end
 
         post '/token' do

data/lib/authify/api/services/monitoring.rb

@@ -7,14 +7,22 @@ module Authify
           set :protection, except: :http_origin
         end
 
-        before '*' do
+        before do
           content_type 'application/json'
+
+          begin
+            unless request.get? || request.options?
+              request.body.rewind
+              @parsed_body = JSON.parse(request.body.read, symbolize_names: true)
+            end
+          rescue => e
+            halt(400, { error: "Request must be valid JSON: #{e.message}" }.to_json)
+          end
+        end
+
+        after do
           headers 'Access-Control-Allow-Origin' => '*',
-                  'Access-Control-Allow-Methods' => %w[
-                    OPTIONS
-                    GET
-                    POST
-                  ],
+                  'Access-Control-Allow-Methods' => %w[OPTIONS GET POST],
                   'Access-Control-Allow-Headers' => %w[
                     Origin
                     Accept
@@ -22,6 +30,7 @@ module Authify
                     Accept-Language
                     Access-Control-Request-Headers
                     Access-Control-Request-Method
+                    Authorization
                     Connection
                     Content-Type
                     Host
@@ -29,16 +38,8 @@ module Authify
                     User-Agent
                     X-Requested-With
                     X-Forwarded-For
+                    X-XSRF-Token
                   ]
-
-          begin
-            unless request.get? || request.options?
-              request.body.rewind
-              @parsed_body = JSON.parse(request.body.read, symbolize_names: true)
-            end
-          rescue => e
-            halt(400, { error: "Request must be valid JSON: #{e.message}" }.to_json)
-          end
         end
 
         # Provide information about the JWTs generated by the server

data/lib/authify/api/services/registration.rb

@@ -5,19 +5,28 @@ module Authify
       class Registration < Service
         use Authify::API::Middleware::Metrics
         helpers Helpers::APIUser
+        helpers Helpers::TextProcessing
 
         configure do
           set :protection, except: :http_origin
         end
 
-        before '*' do
+        before do
           content_type 'application/json'
+
+          begin
+            unless request.get? || request.options?
+              request.body.rewind
+              @parsed_body = JSON.parse(request.body.read, symbolize_names: true)
+            end
+          rescue => e
+            halt(400, { error: "Request must be valid JSON: #{e.message}" }.to_json)
+          end
+        end
+
+        after do
           headers 'Access-Control-Allow-Origin' => '*',
-                  'Access-Control-Allow-Methods' => %w[
-                    OPTIONS
-                    GET
-                    POST
-                  ],
+                  'Access-Control-Allow-Methods' => %w[OPTIONS GET POST],
                   'Access-Control-Allow-Headers' => %w[
                     Origin
                     Accept
@@ -25,6 +34,7 @@ module Authify
                     Accept-Language
                     Access-Control-Request-Headers
                     Access-Control-Request-Method
+                    Authorization
                     Connection
                     Content-Type
                     Host
@@ -32,16 +42,8 @@ module Authify
                     User-Agent
                     X-Requested-With
                     X-Forwarded-For
+                    X-XSRF-Token
                   ]
-
-          begin
-            unless request.get? || request.options?
-              request.body.rewind
-              @parsed_body = JSON.parse(request.body.read, symbolize_names: true)
-            end
-          rescue => e
-            halt(400, { error: "Request must be valid JSON: #{e.message}" }.to_json)
-          end
         end
 
         post '/signup' do
@@ -49,6 +51,7 @@ module Authify
           via = @parsed_body[:via]
           password = @parsed_body[:password]
           name = @parsed_body[:name]
+          templates = @parsed_body[:templates]
 
           halt(422, 'Duplicate User') if Models::User.exists?(email: email)
           halt(403, 'Password Required') unless password || remote_app
@@ -58,12 +61,13 @@ module Authify
           new_user.password = password if password
           if via && via[:provider] && remote_app
             new_user.identities.build(
-              provider: via[:provider],
-              uid: via[:uid] ? via[:uid] : email
+              provider: via[:provider], uid: via[:uid] ? via[:uid] : email
             )
             new_user.verified = true
+          elsif templates && templates.key?(:email)
+            new_user.add_verification_token!(decoded_hash(templates[:email]))
           else
-            new_user.set_verification_token!
+            new_user.add_verification_token!
           end
 
           new_user.save
@@ -86,6 +90,8 @@ module Authify
         post '/forgot_password' do
           email = @parsed_body[:email]
           token = @parsed_body[:token]
+          templates = @parsed_body[:templates]
+
           halt(200, '{}') unless Models::User.exists?(email: email)
           halt(403, 'Missing Parameters') unless email
 
@@ -103,7 +109,11 @@ module Authify
             }.to_json
           else
             found_user.verified = false
-            found_user.set_verification_token!
+            if templates && templates.key?(:email)
+              found_user.add_verification_token!(decoded_hash(templates[:email]))
+            else
+              found_user.add_verification_token!
+            end
             found_user.save
             halt(200, '{}')
           end

data/lib/authify/api/version.rb

@@ -3,7 +3,7 @@ module Authify
     VERSION = [
       0, # Major
       3, # Minor
-      2  # Patch
+      3  # Patch
     ].join('.')
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: authify-api
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.3
 platform: ruby
 authors:
 - Jonathan Gnagy
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-05-19 00:00:00.000000000 Z
+date: 2017-06-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: authify-core
@@ -368,6 +368,7 @@ files:
 - lib/authify/api/controllers/user.rb
 - lib/authify/api/helpers/api_user.rb
 - lib/authify/api/helpers/jwt_encryption.rb
+- lib/authify/api/helpers/text_processing.rb
 - lib/authify/api/jsonapi_utils.rb
 - lib/authify/api/metrics.rb
 - lib/authify/api/middleware/metrics.rb