talis 0.12.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e8926e08a42d050d4b27917867150635361762ac
+  data.tar.gz: 46819d589a371999e95e6a39a8747162244751ae
+SHA512:
+  metadata.gz: 437793795a8103843222cef1ca78ac7b70381315e4a179059b98edf80bf4706e9e7ab30778a7c38c42c3cb1fe76e4461f16c82c44d5c976661438e0596785b11
+  data.tar.gz: 016d3734dbd71a3b643c4041e65edd683a7c3a40d0b4ef3e5826c737695f3f9e01577e02bd63d1b654a30046cd820f53c7203d13557930bf08ffdc8631ca8b6b

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+.env
+.idea/
+*.gem

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,2 @@
+AllCops:
+  TargetRubyVersion: 2.2

data/.travis.yml

@@ -0,0 +1,24 @@
+language: ruby
+rvm:
+- 2.2.5
+- 2.3.1
+before_install: gem install bundler -v 1.11.2
+notifications:
+  hipchat:
+    on_pull_requests: false
+    rooms:
+      secure: KPz9FpSupvzP2ts8BOeAp0rZe+E5VyqbfzPX5Ho46+ctj41tppO2ufYFg2eBdKpBtA1d3KqgAGZaXWtH03rq7lp9NdgTjIzt2Y1qpv3lKTKLs3BPm4JUEBLJZ9Udzatp3W+sDlF3Or8cLgsgvZ4Jx9tehI4TlI4bQn3u7Iyy38Ssgzdw13U5p7SgFnOMU3i+/L6Ki1uzB5wVi0Nvf/5f8/MVRjqXLO0HyLxUzM1g7RtWxqd3B4SzpQS1jndfXuXD0bndlOSQxODz1D6umCk0H0tGtESzMQeMZi0EiKTTTlYyJhvw9U9xZrIdz+Ecd+Sgf3N5dIzKzi6xNZm/B+YONrhvMOClgyUFk0kzOScGASlGxIlgz6uMEc9L1kGB8Y72ezEPkr5RtCjC7+MCnnJN+J2ChWiqDnTRkjshStpKRbQxRx6f3Rj7iItJcfTx1iKOxGw53xoh5OaqPVkqvbVmEMsnObg9kVFpHeTKDXzbqEuOgPmNC/9y1b32DASCU3VIISr9nN1parEthgkYuVE4s50FU2IGHBIu+1ch7J2uKg8wkYGiLxAvZlKxRl/zUCjD/XndfTWa73mY0ykN0y18TJEHgvUrFcQfveetNmMLcYF1cqXhbcCRRG2b92+2ZD9wJf2RfmSys+p33Jvu7FGtnPs1ol+a/JWg/7WVGcgoEXU=
+    template:
+    - "%{repository}#%{build_number} (%{branch} - %{commit} : %{author}): %{message}"
+    notify: true
+env:
+  global:
+  - PERSONA_TEST_HOST: https://staging-users.talis.com
+  - BLUEPRINT_TEST_HOST: https://staging-hierarchy.talis.com
+  - METATRON_OAUTH_HOST: https://users.talis.com
+  - ECHO_TEST_HOST: https://staging-analytics.talis.com
+  - BABEL_TEST_HOST: https://staging-feeds.talis.com
+  - secure: BE2l30U/CLy50vFGV33JCu8t5sr3S0tjCVHcyvby9ChLj7SbceiL7oFhdInCfUFP5uOn9JoyAeULq0JSJK+j5tPsWVGXW0j1hJGvOjcDPA9gsvA4IpgH0WNs6eX5GZkYJIMioJB1MrRP8Hq6teUIC8fb51DQOkL8IRydD1qJsLOgebKfJHLB1hEXHUO0O4Mn3lZrJNjthZrNJG4bhBLvTnki4dmBu+vzEVBb8QMxpnNbBVUI8P3Uo4WlygOnirnW6naxBizHK7EAV6Hk221eTyarepe9u0CpWPXVG5XiHtedUDUU6SdT9XW0lgk26jC78qjf4+VbKIq7Xnmet9bO0K25A8A9ggwEbYv60KPhSeVbTlFt8a1cvthxmfhcgTBdX1JuZ+QbTt6Ex1Pq5efDM1XTKM9wDa1fEz2/+JTIAD6t6nOP8I45M7bRY/WyBXD1TNEU3XWDuJHRf9RlHgfALbc+GD4PHa6/QvWv6gmAAfeGMWbTnl/bDIk6zghfLcM9NhiZErz9V+AX7uQPlKSzqsz/WtjCthz4nFltNVisKftFLZieOR0QOJNDo10KPAbMnRk5R/5znlMd/zyH7C2oGlMCAjVK5GETJnRyw26/y0S5PWwxovf3p+IjXeNrRiHmsiSiVUK/e9EPiSya5n/GPRR9x9VoYEmo9fS88g8+Buo=
+  - secure: ndyBRplFd1IKVlabpPm/YxLKcD18MPflgtIjmhsEHzEQdvBlviwL7zXjpcISlrSLD5y7s4VMookrSXSWMMve4pFonjKUEOXS8yH8ARKe40i2PcdKuiGvD5DWKZXJvNfmOKoWFgG0uK/v8PJcniW/NyLjAJ915MAEvI0fBUjq4B6ZZYHd3oEIpDctDxN3jF/xK9058LCgT68IDAun16F+UnqdNdWj6I4BDM2ljhIZpsCYjVQAgPvYE85AYdJpPJUlO28MMj+iJzS2ZlubDngligtu4OWyDzTua8aez3V9OobPLNEfoCIW+a+9IiBM8QrUfomIUlccQ9j2B2u5i7n6w6KqfKi3PZd3jtkoG+nScWHnCCovTi8w9Dw5umiQrAr4y80XgQclWhi3HpTuzb/jKinec6Q7kXpdwIem+LEhX0Gp54azuJna51nw1Pf0sym3Ic096/SLgvxgtMi3JDUFu/VCHrHYnCAkjy42c7SKoMWzQ69dyTTK3+X32xasP8FT+F7CSEKbPS0D1zhpR9xpNDFmQkQklccBa9nY9CzFPe7YsvtaP7fW739lH8NfrD8faD7/BPoVIgX8/7ZKRKj1mXGDukvg4pizrd+U4O6iDkqQUfPkQE6+PLvdb2FZS+WjeR7xtXReH3dAk8D2sqZVoGl6nbDAKcxJUABKozPNl6s=
+  - secure: kfPQchN+t2fsbOPuxTYfpAwamguynuebLHwq/qD7dglz/aBhF8kPtBOQxtaMBfth1FQ+Xx0d73G9nW1TkIsCj1fYVZkNC2JhRojIUiKaKQoTj0anw04YOvvnX6AUnyx6+Sov8M5rf6EAprKKLh2lPXxXmrDtGxXVACA/EDyQNDYNeIy+TVJ1kzI8KQ//lbnc9EhISPgnYLe/HETi1v7abKm18pmIw5fATOszou2a/ziH1TW1Io8iX3Z1wUQ60WaXgL7+y/pEs6JHy3UXl3zNSYW5EeeloRmob71HlZ01xAQSLyqW8UUFnnCuxln23TmQXOEULMjy35kino+3wMDsx8GZCOA0YqZG4k+OXFsV5/gjgIEE7NzzYwbOzTx/us3B1Z9QIHe0S7k8HbFwnhD64Sma/Id++HhWUz+lBtJ/tbk5TyrEZwRxWC2vhWoyfAcepCTZYdRo76PAQlgjxywmdasRmTLUCPzrGBhwg2IHoHkmBFvMMVN6+mWwSJ8u5QC5lTuh4pXvHY4xMOZ/jw5wjQUucMGK2VTkRd6rveQcro7GkJMe6rvF3JTYqa6mjDt+CbZHX+17GQVmnX5D9a1/RhyRbYOsHtFv5ojiKIzBmVNxf3Nfmy3MtPu99NFhJNPostbaOSECCPfE7NJ1H/+cc2LdEaz5rghTpjdoE8bAIIM=
+  - secure: foSVBXRpbEdgD3Xvm8hy1KcsRLlqlAiH3Vwq6ZwvwWmvt/la8/iaDKOym0YNIL1hB+tMfRhHeKtD6ruPuag+MVbj8veE89pbzztHTinY/3J9TXoYNuC98xvEtWm3Vqgvb9XMvo1O0mN2jIlTRAdLmHC6So6/3tXWnfZLJrU+wfX5BuCHAuileUX08LX1GQGs1lCIh4r9G3PL7QzITzacI7PPw3tPkgTwAqwvsyS2g9E8nc+lGBLL6Y8VXo9F/63phRJf1fpK0obXJqwJluoiVO38QxlWa188aLBOCZjBoAA3p8gOcYlYoFT86RI6ZINdqqqbCKTqgCGtLEUIeVXNG0c4EPecoD2W7MUHNEwCl3Ee1o/QD2+4drPMQwWyQAKtdQTVKS+kwwW23DJDMiCWD882IL7LJ7DCZcx+5FgIEWdXJBr+ZGsQ0K6AIZRdiNe93GAr7cuZGJgF6u3vNLMD9g5VLA5WirxIJBoVF3WyEp7fLop0OqaCpwsjPo6t8tzhft9OXts3rmMHOFeJnOK2S3zwxGPb5YFDO7TEWqX3oDuI1Pzt7Rky0T0wEFQgyb+WMoijg+ic+H3yXOfKoOhymr2+UHO5vzTdfVbdXF2gR+atU5yv3mhZlLSc2tJdKErLQRQM5kSMIpJHFd8EEeC7XjJ+6zGho+EH3f4jwsLHNiM=

data/.yardopts

@@ -0,0 +1 @@
+--no-private

data/CONTRIBUTING.md

@@ -0,0 +1,28 @@
+Firstly, thank you for contributing! Please read our [Engineering Handbook]
+(http://talis.github.io/) for some guidelines.
+
+# Local Development
+
+## Setup
+
+    bundle install
+    
+Create a `.env` file and add the following:
+
+    PERSONA_TEST_HOST=<your local persona host>
+    PERSONA_OAUTH_CLIENT=<your local persona client ID (with su scope)>
+    PERSONA_OAUTH_SECRET=<your local persona client secret (with su scope)>
+    BLUEPRINT_TEST_HOST=<your local blueprint host>
+    METATRON_TEST_HOST=<your local metatron host>
+    METATRON_BASE_PATH=<if not a production env, use /development>
+
+If these variables are not set, the production primitives are used.
+
+## Running Tests
+
+    bundle exec rspec
+    
+## Versioning
+
+Please use [semantic versioning](http://semver.org/) and bump 
+`lib/talis/version.rb` when submitting a pull request.

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in talis.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,5 @@
+guard :rspec, cmd: 'bundle exec rspec' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/.+\.rb$}) { 'spec' }
+  watch('spec/spec_helper.rb') { 'spec' }
+end

data/README.md

@@ -0,0 +1,76 @@
+# Talis Ruby Client
+
+[![Build Status](https://travis-ci.org/talis/talis_rb.svg?branch=master)](https://travis-ci.org/talis/talis_rb)
+[![Dependency Status](https://dependencyci.com/github/talis/talis_rb/badge)](https://dependencyci.com/github/talis/talis_rb)
+
+A ruby gem that provides interactions with Talis primitives.
+
+## Ubuntu Prerequisites
+
+    sudo apt-get install libgmp-dev
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'talis', github: talis/talis_rb
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install talis
+
+## Usage
+
+### Security Configuration
+
+Many client operations require an OAuth token. 
+In order to carry out these operations, configure the OAuth client:
+
+    require 'talis/authentication'
+
+    Talis::Authentication.client_id = 'client_id'
+    Talis::Authentication.client_secret = 'client_secret'
+
+See the code for each class for specific usage:
+* `lib/talis/authentication/login.rb` For server-side login workflow.
+* `lib/talis/authentication/token.rb` For OAuth token generation and validation.
+* `lib/talis/hierarchy/node.rb` For managing hierarchies.
+* `lib/talis/hierarchy/asset.rb` For managing hierarchy assets.
+* `lib/talis/user.rb` For managing Talis users.
+* `lib/talis/bibliography/work.rb` For querying works.
+* `lib/talis/analytics.rb` For sending analytical data.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. 
+
+Create a `.env` file in the project root and configure the following variables:
+
+    PERSONA_TEST_HOST=http://persona
+    PERSONA_OAUTH_CLIENT=<client ID>
+    PERSONA_OAUTH_SECRET=<client secret>
+    BLUEPRINT_TEST_HOST=http://blueprint
+    ECHO_TEST_HOST=http://echo
+    
+    METATRON_TEST_HOST=<Metatron host>
+    METATRON_BASE_PATH=<set this to /env_name/2 if not using production>
+    METATRON_OAUTH_HOST=<Persona host the Metatron host uses>
+    METATRON_OAUTH_CLIENT=<client ID associated with oauth host above>
+    METATRON_OAUTH_SECRET=<client secret associated with oauth host above>
+    TEST_USER_GUID=<The GUID of the Talis test user (test.tn@talis.com)>
+
+    
+Adjust the values according to the primitives you want to test against (local or remote).
+If testing locally then make sure the host names are in `/etc/hosts`.
+
+Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+This project enforces style and lint rules via [Rubocop](https://github.com/bbatsov/rubocop). Run `rake rubocop` to check for violations.
+
+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).

data/Rakefile

@@ -0,0 +1,8 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: [:rubocop, :spec]

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'talis'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require 'pry'
+# Pry.start
+
+require 'irb'
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/talis.rb

@@ -0,0 +1,25 @@
+require 'talis/version'
+require 'talis/constants'
+require 'talis/errors'
+require 'talis/extensions/object'
+require 'talis/resource'
+require 'talis/authentication'
+require 'talis/oauth_service'
+require 'talis/analytics'
+require 'talis/hierarchy'
+require 'talis/feeds'
+require 'talis/user'
+require 'talis/bibliography'
+require 'bundler/setup'
+require 'httparty'
+require 'json'
+
+# Main entry point
+module Talis
+  class << self
+    def new(opts = {})
+      token = Talis::Authentication::Token.generate(opts)
+      Talis::Authentication::Client.new(token, opts)
+    end
+  end
+end

data/lib/talis/analytics.rb

@@ -0,0 +1,31 @@
+require_relative 'analytics/event'
+
+module Talis
+  # Use this as a mixin within your classes to be able to send analytics events.
+  module Analytics
+    # Create a single analytics event.
+    # In order to send events, the client must be configured with a
+    # valid OAuth client that is allowed to search for users:
+    #
+    #  Talis::Authentication.client_id = 'client_id'
+    #  Talis::Authentication.client_secret = 'client_secret'
+    #
+    # @param event [Hash] The event to send. It must contain the
+    #  minimum keys:
+    #     {
+    #       class: 'my.class.name',
+    #       source: 'my.source.name'
+    #     }
+    #  Other valid keys include: timestamp, user and props. Props can
+    #  contain any key-value pair of custom data. All other keys will be
+    #  ignored.
+    # @param request_id [String] ('uuid') unique ID for the remote request.
+    # @raise [Talis::ClientError] if the request was invalid.
+    # @raise [Talis::ServerError] if the search failed on the
+    #   server.
+    # @raise [Talis::ServerCommunicationError] for network issues.
+    def send_analytics_event(event, request_id: nil)
+      Event.create(request_id: request_id, event: event)
+    end
+  end
+end

data/lib/talis/analytics/event.rb

@@ -0,0 +1,67 @@
+module Talis
+  module Analytics
+    # Represents an event for analytical purposes.
+    class Event < Talis::Resource
+      base_uri Talis::ECHO_HOST
+
+      class << self
+        # Create a single analytics event.
+        # In order to send events, the client must be configured with a
+        # valid OAuth client that is allowed to search for users:
+        #
+        #  Talis::Authentication.client_id = 'client_id'
+        #  Talis::Authentication.client_secret = 'client_secret'
+        #
+        # @param request_id [String] ('uuid') unique ID for the remote request.
+        # @param event [Hash] The event to send. It must contain the
+        #  minimum keys:
+        #     {
+        #       class: 'my.class.name',
+        #       source: 'my.source.name'
+        #     }
+        #  Other valid keys include: timestamp, user and props. Props can
+        #  contain any key-value pair of custom data. All other keys will be
+        #  ignored.
+        # @raise [Talis::ClientError] if the request was invalid.
+        # @raise [Talis::ServerError] if the search failed on the
+        #   server.
+        # @raise [Talis::ServerCommunicationError] for network issues.
+        def create(request_id: new_req_id, event:)
+          request_id = new_req_id unless request_id
+          validate_event event
+          payload = whitelist_event event
+          begin
+            response = post_event(request_id, payload)
+            handle_response(response, 204)
+          rescue SocketError
+            raise Talis::ServerCommunicationError
+          end
+        end
+
+        private
+
+        def post_event(request_id, payload)
+          post('/1/events',
+               headers: {
+                 'Content-Type' => 'application/json',
+                 'X-Request-Id' => request_id,
+                 'Authorization' => "Bearer #{token}"
+               },
+               body: [payload].to_json)
+        end
+
+        def validate_event(event)
+          error_message = 'event must contain class and source'
+          required = [:class, :source]
+          provided = event.select { |attr| required.include? attr }.keys
+          raise ArgumentError, error_message unless required == provided
+        end
+
+        def whitelist_event(event)
+          valid = [:class, :source, :timestamp, :user, :props]
+          event.select { |attribute| valid.include? attribute }
+        end
+      end
+    end
+  end
+end

data/lib/talis/authentication.rb

@@ -0,0 +1,14 @@
+require_relative 'authentication/client'
+require_relative 'authentication/public_key'
+require_relative 'authentication/token'
+require_relative 'authentication/login'
+
+module Talis
+  # Encompasses all classes associated with user authentication
+  module Authentication
+    # The ID of the OAuth client to allow requests for asset resources.
+    cattr_accessor :client_id
+    # The secret of the OAuth client to allow requests for asset resources.
+    cattr_accessor :client_secret
+  end
+end

data/lib/talis/authentication/client.rb

@@ -0,0 +1,82 @@
+require 'httparty'
+
+module Talis
+  module Authentication
+    # Represents an OAuth client
+    class Client
+      include HTTParty
+
+      attr_reader :host, :client_id, :client_secret, :token, :scopes
+      def initialize(token, opts = {})
+        @token = token
+        acquire_host!(opts)
+        acquire_credentials!
+
+        response = authenticate!
+        body = JSON.parse response.body
+        @scopes = body['scope']
+        raise Talis::AuthenticationFailedError unless
+            response.code == 200
+      end
+
+      def add_scope(scope)
+        if scope.is_a? String
+          response = modify_scope(:add, scope)
+          @scopes << scope if response.code == 204
+        end
+      end
+
+      def remove_scope(scope)
+        if scope.is_a? String
+          response = modify_scope(:remove, scope)
+          @scopes.delete(scope) if response.code == 204
+        end
+      end
+
+      def modify_scope(action, scope)
+        action = case action
+                 when :add
+                   '$add'
+                 when :remove
+                   '$remove'
+                 else
+                   raise 'Unknown action'
+                 end
+        patch_client_scope(action, scope)
+      end
+
+      private
+
+      def authenticate!
+        self.class.get("/clients/#{client_id}",
+                       headers: { 'Authorization' => bearer_token })
+      end
+
+      def bearer_token
+        "Bearer #{token}"
+      end
+
+      def patch_client_scope(action, scope)
+        self.class.patch("/clients/#{client_id}",
+                         headers: {
+                           'Content-Type' => 'application/json',
+                           'Authorization' => bearer_token
+                         },
+                         body: { scope: { action => scope } }.to_json)
+      end
+
+      def acquire_host!(opts)
+        if opts[:host].present?
+          self.class.base_uri(opts[:host])
+        else
+          self.class.base_uri(PERSONA_HOST)
+        end
+      end
+
+      def acquire_credentials!
+        @client_id     = ENV['PERSONA_OAUTH_CLIENT']
+        @client_secret = ENV['PERSONA_OAUTH_SECRET']
+      end
+    end
+  end
+end

data/lib/talis/authentication/login.rb

@@ -0,0 +1,169 @@
+require 'base64'
+require 'date'
+require 'digest'
+require 'multi_json'
+require 'uuid'
+
+module Talis
+  module Authentication
+    # Represents the user login flow for server-side applications.
+    # A prerequisite to using this class is having an application registered
+    # with Persona in order to obtain an app ID and secret. Application
+    # registration also provides Persona a callback URL to POST the login
+    # response back to the application.
+    # @example Redirect user to authentication provider.
+    #  # First create a login object and redirect the user, storing the state:
+    #  options = {
+    #    app_id: 'my_app',
+    #    app_secret: 'my_secret',
+    #    provider: 'google',
+    #    redirect_uri: 'https://my_app/secret_area'
+    #  }
+    #  login = Talis::Authentication::Login.new(options)
+    #  url = login.generate_url
+    #  session[:state] = login.state
+    #  redirect_to url
+    # @example Handle data after user has logged in.
+    #  # After the user has logged in, handle the POST callback:
+    #  state = session.delete(:state)
+    #  login.validate!(payload: params, state: state)
+    #  if login.valid?
+    #    session[:current_user_id] = login.user.guid
+    #    redirect_to login.redirect_uri
+    #  else
+    #    # handle invalid login
+    #    puts login.error
+    #  end
+    # @example Logging out a user.
+    #  # When a user logs out, make sure to clean up the session:
+    #  session.delete(:current_user_id)
+    #  redirect_to login.logout_url('some/logout/path')
+    class Login
+      include HTTParty
+      # @return [String] a non-guessable alphanumeric string used to prevent
+      #   CSRF attacks. Store this in the user session after generating a
+      #   login URL.
+      attr_reader :state
+      # @return [Talis::User] the logged-in user. This will be nil unless
+      #   validation has passed.
+      attr_reader :user
+      # @return [String] if present, this will be the reason why the login
+      #   failed.
+      attr_reader :error
+
+      base_uri Talis::PERSONA_HOST
+
+      # Creates a new login object to manage the login flow.
+      # @param app_id [String] ID of the application registered to Persona.
+      # @param secret [String] secret of the application registered to Persona.
+      # @param provider [String] name of the auth provider to use for login.
+      # @param redirect_uri [String] where to redirect back to after login.
+      def initialize(app_id:, secret:, provider:, redirect_uri:)
+        @uuid = UUID.new
+
+        @app = app_id
+        @secret = secret
+        @provider = provider
+        @redirect_uri = redirect_uri
+      end
+
+      # Use this URL to redirect the user wishing to login to their auth
+      # provider. After generating the URL the state will be available to
+      # store in a session.
+      # @param require [Symbol] (nil) If :profile, upon successful
+      #   login, the user will be redirected to a profile form if they do not
+      #   have one.
+      # @return [String] the generated URL.
+      def generate_url(require: nil)
+        @state = Digest::MD5.hexdigest("#{@app}::#{@uuid.generate}")
+        params = {
+          app: @app,
+          state: @state,
+          redirectUri: @redirect_uri
+        }
+        params = params.merge(require: 'profile') if require == :profile
+        params = params.to_query
+        "#{self.class.base_uri}/auth/providers/#{@provider}/login?#{params}"
+      end
+
+      # Validate a login request after the user has logged in to their auth
+      # provider. Validation will fail if the provided payload:
+      # - Is not a hash.
+      # - When decoded, contains invalid JSON.
+      # - Has no state or the state it contains does not match the param state.
+      # - Has an invalid signature.
+      # If validation succeeds, the #user attribute will return the
+      # logged-in user. If it fails, check the #error attribute for the
+      # reason why.
+      # @param payload [Hash] the payload POSTed to the application server.
+      # @param state [String] use the value stored at the start of the session.
+      def validate!(payload:, state:)
+        return @error = 'payload is not a hash' unless payload.is_a? Hash
+
+        key = 'persona:payload'
+        return @error = "payload missing key #{key}" unless payload.key? key
+
+        @payload = decode_and_parse_payload(payload)
+        return @error = 'payload is not valid JSON' if @payload.nil?
+
+        state_error = 'payload state does not match provided'
+        return @error = state_error if @payload['state'] != state
+
+        signature_error = 'payload signature does not match expected'
+        return @error = signature_error unless signature_valid?(@payload)
+
+        @user = build_user(@payload)
+      end
+
+      # Indicate whether or not the login succeeded.
+      # @return [Boolean] true if the login is valid, otherwise false.
+      def valid?
+        @error.nil?
+      end
+
+      # The redirect to follow once login has successfully completed.
+      # @return [String] the URL to redirect to.
+      def redirect_uri
+        @payload.present? ? @payload['redirect'] : @redirect_uri
+      end
+
+      # Logs a user out by terminating the session with Persona.
+      # @param redirect_url [String] where to return the user on logout.
+      # @return [String] the URL to redirect the user to when logging out.
+      def logout_url(redirect_url)
+        "#{self.class.base_uri}/auth/logout?redirectUri=#{redirect_url}"
+      end
+
+      private
+
+      def build_user(data)
+        profile = data['profile'] || {}
+        Talis::User.build(guid: data['guid'],
+                          first_name: profile['first_name'],
+                          surname: profile['surname'],
+                          email: profile['email'],
+                          access_token: data.fetch('token', {})['access_token'])
+      end
+
+      def decode_and_parse_payload(payload)
+        begin
+          json = MultiJson.load(Base64.decode64(payload['persona:payload']))
+        rescue MultiJson::LoadError
+          return nil
+        end
+        json
+      end
+
+      def signature_valid?(payload)
+        received_signature = payload.delete('signature')
+
+        # Persona PHP code escapes forward slashes when encoding JSON
+        json_payload = payload.to_json.gsub('/', '\/')
+
+        digest = OpenSSL::Digest.new('sha256')
+        signature = OpenSSL::HMAC.hexdigest(digest, @secret, json_payload)
+        received_signature == signature
+      end
+    end
+  end
+end