d2l-valence 0.0.1

data/lib/d2l/valence.rb

@@ -0,0 +1,15 @@
+require 'uri'
+require 'cgi'
+require 'base64'
+require 'openssl'
+require 'restclient'
+
+require 'd2l/valence/version'
+require 'd2l/valence/host'
+require 'd2l/valence/app_context'
+require 'd2l/valence/encrypt'
+require 'd2l/valence/timestamp_error'
+require 'd2l/valence/response'
+require 'd2l/valence/user_context'
+require 'd2l/valence/auth_tokens'
+require 'd2l/valence/request'

data/lib/d2l/valence/app_context.rb

@@ -0,0 +1,49 @@
+module D2L
+  module Valence
+    # == AppContext
+    # Class with contextual detail for the application (the ruby client)
+    class AppContext
+      APP_ID_PARAM = 'x_a'.freeze
+      AUTH_KEY_PARAM = 'x_b'.freeze
+      CALLBACK_URL_PARAM = 'x_target'.freeze
+      AUTH_SERVICE_URI_PATH = '/d2l/auth/api/token'.freeze
+
+      attr_reader :brightspace_host,
+                  :app_id,
+                  :app_key,
+                  :api_version
+
+      # @param [Valence::Host] brightspace_host Authenticating D2L Brightspace Instance
+      # @param [String] app_id Application ID provided by your D2L admin
+      # @param [String] app_key Application Key provided by your D2L admin
+      # @param [String] api_version Version of the Valence API is use
+      def initialize(brightspace_host:, app_id:, app_key:, api_version: '1.0')
+        @brightspace_host = brightspace_host
+        @app_id = app_id
+        @app_key = app_key
+        @api_version = api_version
+      end
+
+      # Generates a URL for authentication
+      #
+      # @param [URI::Generic] callback_uri URI to redirect to post authentication
+      # @return [String] URL for authentication
+      def auth_url(callback_uri)
+        @brightspace_host.to_uri(
+          path: AUTH_SERVICE_URI_PATH,
+          query: query_params_using(callback_url: callback_uri.to_s)
+        ).to_s
+      end
+
+      private
+
+      def query_params_using(callback_url:)
+        {
+          APP_ID_PARAM => @app_id,
+          AUTH_KEY_PARAM => Encrypt.generate_from(@app_key, callback_url),
+          CALLBACK_URL_PARAM => CGI.escape(callback_url)
+        }.map { |p, v| "#{p}=#{v}" }.join('&')
+      end
+    end
+  end
+end

data/lib/d2l/valence/auth_tokens.rb

@@ -0,0 +1,60 @@
+module D2L
+  module Valence
+    # == AuthTokens
+    # Class to generate authentication tokens for D2L Valance API calls
+    class AuthTokens
+      APP_ID_PARAM = 'x_a'.freeze
+      USER_ID_PARAM = 'x_b'.freeze
+      SIGNATURE_BY_APP_KEY_PARAM = 'x_c'.freeze
+      SIGNATURE_BY_USER_KEY_PARAM = 'x_d'.freeze
+      TIMESTAMP_PARAM = 'x_t'.freeze
+
+      # @param [D2L::Valence::Request] request the authenticated request that the auth tokens are for
+      def initialize(request:)
+        @call = request
+        @user_context = @call.user_context
+        @app_context = @user_context.app_context
+      end
+
+      # Generates the auth tokens as a Hash for inclusion in the final URI query string
+      # @return [Hash] tokens for authenticated call
+      def generate
+        @tokens = {}
+        add_app_tokens
+        add_user_tokens
+        add_timestamp_token
+        @tokens
+      end
+
+      # Generates a timestamp with time skew between server and client taken into consideration
+      #
+      # @return [Integer] Server skew adjusted timestamp in seconds
+      def adjusted_timestamp
+        @adjusted_timestamp ||= Time.now.to_f.to_i + @user_context.server_skew
+      end
+
+      private
+
+      def add_app_tokens
+        @tokens[APP_ID_PARAM] = @app_context.app_id
+        @tokens[SIGNATURE_BY_APP_KEY_PARAM] = Encrypt.generate_from(@app_context.app_key, signature)
+      end
+
+      def add_user_tokens
+        return if @user_context.user_id.nil?
+
+        @tokens[USER_ID_PARAM] = @user_context.user_id
+        @tokens[SIGNATURE_BY_USER_KEY_PARAM] = Encrypt.generate_from(@user_context.user_key, signature)
+      end
+
+      def add_timestamp_token
+        @tokens[TIMESTAMP_PARAM] = adjusted_timestamp
+      end
+
+      # Generates a signature requite by the D2L Valence API
+      def signature
+        @signature ||= "#{@call.http_method}&#{CGI.unescape(@call.path).downcase}&#{adjusted_timestamp}"
+      end
+    end
+  end
+end

data/lib/d2l/valence/encrypt.rb

@@ -0,0 +1,34 @@
+module D2L
+  module Valence
+    # == Encrypt
+    # Class encrypt and encode data for transmission in a URL
+    class Encrypt
+      # Encrypt and encode data with provided key
+      #
+      # @param [String] key the key to encrypt with
+      # @param [String] data data to encrypt and encode
+      def self.generate_from(key, data)
+        encode(sign(key, data))
+      end
+
+      def self.sign(key, data)
+        OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha256'), key, data)
+      end
+
+      def self.encode(digest)
+        Base64.urlsafe_encode64(digest, padding: false).strip
+      rescue
+        old_encode digest
+      end
+
+      # support for older versions of ruby
+      def self.old_encode(digest)
+        remove_unwanted_chars Base64.encode64(digest).strip
+      end
+
+      def self.remove_unwanted_chars(string)
+        string.delete('=').tr('+', '-').tr('/', '_').strip
+      end
+    end
+  end
+end

data/lib/d2l/valence/host.rb

@@ -0,0 +1,43 @@
+module D2L
+  module Valence
+    # == Host
+    # Class for the creation of URIs for communication with the D2L Valence API
+    class Host
+      attr_accessor :scheme, :host, :port
+
+      # @param [Symbol] scheme URI scheme to be used (either :http or :https)
+      # @param [String] host host name for D2L server (e.g. d2l.myinstitution.com)
+      # @param [Integer] port specific port for transmission (optional)
+      def initialize(scheme:, host:, port: nil)
+        self.scheme = scheme
+        self.host = host
+        self.port = port
+      end
+
+      def host=(value)
+        raise 'Host cannot be nil' if value.nil?
+        @host = value
+      end
+
+      def scheme=(value)
+        return if value.nil?
+        value = value.downcase.to_sym if value.is_a? String
+        raise "#{value} is an unsupported scheme. Please use either HTTP or HTTPS" unless supported_scheme? value
+        @scheme = value
+      end
+
+      def to_uri(path: nil, query: nil)
+        {
+          http: URI::HTTP.build(host: host, port: port, path: path, query: query),
+          https: URI::HTTPS.build(host: host, port: port, path: path, query: query)
+        }[scheme]
+      end
+
+      private
+
+      def supported_scheme?(value)
+        [:http, :https].include? value
+      end
+    end
+  end
+end

data/lib/d2l/valence/request.rb

@@ -0,0 +1,104 @@
+module D2L
+  module Valence
+    # == Request
+    # Class for authenticated calls to the D2L Valence API
+    class Request
+      attr_reader :user_context,
+                  :http_method,
+                  :response
+
+      #
+      # == API routes
+      # See D2L::Valence::UserContext.api_call for details on creating routes and route_params
+      #
+      # @param [D2L::Valance::UserContext] user_context the user context created after authentication
+      # @param [String] http_method the HTTP Method for the call (i.e. PUT, GET, POST, DELETE)
+      # @param [String] route the API method route (e.g. /d2l/api/lp/:version/users/whoami)
+      # @param [Hash] route_params the parameters for the API method route (option)
+      # @param [Hash] query_params the query parameters for the method call
+      def initialize(user_context:, http_method:, route:, route_params: {}, query_params: {})
+        @user_context = user_context
+        @app_context = user_context.app_context
+        @http_method = http_method.upcase
+        @route = route
+        @route_params = route_params
+        @query_params = query_params
+
+        raise "HTTP Method #{@http_method} is unsupported" unless %w(GET PUT POST DELETE).include? @http_method
+      end
+
+      # Generates an authenticated URI for a the Valence API method
+      #
+      # @return [URI::Generic] URI for the authenticated method call
+      def authenticated_uri
+        @app_context.brightspace_host.to_uri(
+          path: path,
+          query: query
+        )
+      end
+
+      # Sends the authenticated call on the Valence API
+      #
+      # @return [D2L::Valence::Response] URI for the authenticated methof call
+      def execute
+        raise "HTTP Method #{@http_method} is not implemented" if params.nil?
+
+        @response = execute_call
+        @user_context.server_skew = @response.server_skew
+        @response
+      end
+
+      # Generates the final path for the authenticated call
+      #
+      # @return [String] path for the authenticated call
+      def path
+        return @path unless @path.nil?
+
+        substitute_keys_with(@route_params)
+        substitute_keys_with(known_params)
+        @path = @route
+      end
+
+      private
+
+      def execute_call
+        Response.new RestClient.send(@http_method.downcase, *params)
+      rescue RestClient::Exception => e
+        Response.new e.response
+      end
+
+      def params
+        {
+          'GET' => [authenticated_uri.to_s],
+          'POST' => [authenticated_uri.to_s, @query_params.to_json, content_type: :json],
+          'PUT' => [authenticated_uri.to_s, @query_params.to_json, content_type: :json],
+          'DELETE' => [authenticated_uri.to_s, content_type: :json]
+        }[@http_method]
+      end
+
+      def substitute_keys_with(params)
+        params.each { |param, value| @route.gsub!(":#{param}", value.to_s) }
+      end
+
+      def known_params
+        {
+          version: @user_context.app_context.api_version
+        }
+      end
+
+      def query
+        return to_query_params(authenticated_tokens) unless @http_method == 'GET'
+
+        to_query_params @query_params.merge(authenticated_tokens)
+      end
+
+      def to_query_params(hash)
+        hash.map { |k, v| "#{k}=#{v}" }.join('&')
+      end
+
+      def authenticated_tokens
+        D2L::Valence::AuthTokens.new(request: self).generate
+      end
+    end
+  end
+end

data/lib/d2l/valence/response.rb

@@ -0,0 +1,66 @@
+module D2L
+  module Valence
+    # == Response
+    # Class for interpreting the response from the D2L Valence API
+    class Response
+      attr_reader :http_response
+
+      # @param [RestClient::Response] http_response response from a request against the Valance API
+      def initialize(http_response)
+        @http_response = http_response
+        @server_skew = 0
+      end
+
+      # @return [String] Plain text response from the D2L server
+      def body
+        @http_response.body
+      end
+
+      # Generates a hash based on a valid JSON response from the D2L server.  If the provided response is not in a
+      # value JSON format then an empty hash is returned
+      #
+      # @return [Hash] hash based on JSON body
+      def to_hash
+        @to_hash ||= JSON.parse(body)
+      rescue
+        @to_hash = {}
+      end
+
+      # @return [Symbol] the interpreted code for the Valance API response
+      def code
+        interpret_forbidden || http_code
+      end
+
+      # @return [Integer] the difference in D2L Valance API Server time and local time
+      def server_skew
+        return 0 unless timestamp_error.timestamp_out_of_range?
+
+        @server_skew = timestamp_error.server_skew
+      end
+
+      private
+
+      def http_code
+        "HTTP_#{@http_response.code}".to_sym
+      end
+
+      def interpret_forbidden
+        return unless @http_response.code == 403
+
+        invalid_timestamp || invalid_token
+      end
+
+      def invalid_timestamp
+        :INVALID_TIMESTAMP if timestamp_error.timestamp_out_of_range?
+      end
+
+      def timestamp_error
+        @timestamp_error ||= TimestampError.new(@http_response.body)
+      end
+
+      def invalid_token
+        :INVALID_TOKEN if @http_response.body.include? 'invalid token'
+      end
+    end
+  end
+end

data/lib/d2l/valence/timestamp_error.rb

@@ -0,0 +1,42 @@
+module D2L
+  module Valence
+    # == TimestampError
+    # This class is aimed at parsing and providing diagnostics for time based issues
+    # between the D2L Brightspace Server and Ruby Client
+    class TimestampError
+      # @param [String] D2L Brightspace Server Error Message
+      def initialize(error_message)
+        @error_message = error_message
+      end
+
+      # @return [Integer] difference in D2L Server timestamp in seconds
+      def server_skew
+        return 0 if server_time_in_seconds.nil?
+
+        @server_skew ||= server_time_in_seconds - now_in_seconds
+      end
+
+      # @return [Integer] true if our timestamp is out of range with the D2L Server
+      def timestamp_out_of_range?
+        server_time_in_seconds != nil
+      end
+
+      private
+
+      # @return [Integer] D2L Server timestamp
+      def server_time_in_seconds
+        @server_timestamp ||= parse_timestamp
+      end
+
+      # @return [Integer] local timestamp now in seconds
+      def now_in_seconds
+        Time.now.to_f.to_i
+      end
+
+      def parse_timestamp
+        match = Regexp.new(/Timestamp out of range\s*(\d+)/).match(@error_message)
+        match[1].to_i if !match.nil? && match.length >= 2
+      end
+    end
+  end
+end

data/lib/d2l/valence/user_context.rb

@@ -0,0 +1,58 @@
+module D2L
+  module Valence
+    # == UserContext
+    # Instances of this class are used to make D2L Valance API calls with the current user credentials
+    class UserContext
+      attr_reader :app_context,
+                  :user_id,
+                  :user_key
+
+      attr_accessor :server_skew # in seconds
+
+      # @param [D2L::Valence::AppContext] app_context
+      # @param [String] user_id User ID returned from the D2L Server in authentication process
+      # @param [String] user_key User Key returned the D2L Server in authentication process
+      def initialize(app_context:, user_id:, user_key:)
+        @app_context = app_context
+        @user_id = user_id
+        @user_key = user_key
+        @server_skew = 0
+      end
+
+      # Calls a API method on the Valance API
+      #
+      # == API routes
+      # When providing the route you can also provide the variables for the parameters in the route. For example, the
+      # following route will require `{org_unit_id: 1, group_category_id: 23}` for `route_params`:
+      #
+      # /d2l/api/lp/:version/:org_unit_id/groupcategories/:group_category_id
+      #
+      # The `to_uri` method will place the parameters in the route to make the final path.  For example:
+      #
+      # /d2l/api/lp/1.0/1/groupcategories/23
+      #
+      # There are known parameters such as `:version` which is provided when you create your initial AppContext
+      # instance.  This will mean that some routes will require no parameters for example:
+      #
+      # /d2l/api/lp/:version/users/whoami
+      #
+      # which becomes
+      # /d2l/api/lp/1.0/users/whoami
+      #
+      # @param [String] http_method the HTTP Method for the call (i.e. PUT, GET, POST, DELETE)
+      # @param [String] route the API method route (e.g. /d2l/api/lp/:version/users/whoami)
+      # @param [Hash] route_params the parameters for the API method route (option)
+      # @param [Hash] query_params the query parameters for the method call
+      # @return [D2L::Valence::RequestResult] returns a request
+      def api_call(http_method:, route:, route_params:, query_params:)
+        D2L::Valence::Request.new(
+          user_context: self,
+          http_method: http_method,
+          route: route,
+          route_params: route_params,
+          query_params: query_params
+        ).execute
+      end
+    end
+  end
+end