mauth-client 4.2.1 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a4124d677e7aee9626ea7e796bd5f92c695146cdadc125c2f05f3138d471758
-  data.tar.gz: 4eda569778ce91ced2cedfd14a231281e35ec068b86d2e551d52541d05b3f795
+  metadata.gz: fb397d4c368ae894af1012c2305891bdfe4c85269e75e54167d4a7482a034f5a
+  data.tar.gz: 8dc255a280b8304360b305be500b00bf1a8205293a7061af866a99f2eb69ca10
 SHA512:
-  metadata.gz: 6118dc54acd81a9dc16d1364fab960dee75c5a5e055fc79bb2517d6eb48e3dbf033078b913b231f430fc9ae953be5f56ab727664bc147b0e90f0f71203ec9f14
-  data.tar.gz: fa8e3328ef7e779322e8ad0c7f4a3520f53370838a10e4cf1d0b8710ee0031fc37f4d5d31f080d39d7134c0dfa2a263a131c1323269e988a79978bcf21efd775
+  metadata.gz: 8e519a163cba44ca112f31d91a2da679601cebeac172eac15704f0ff93cc3ea5a3eba6e654d15cce3cbd2c587cc5bc3e6ae88a1042b84bdaa77f3e71fda01a96
+  data.tar.gz: 18e5b9888c5c56ffa2f78197cdca887958e220f6f63e71807393d043508b5cd013ded15031d29230262cdfeb0de86f1f71f18cffd62a64c5719da030a59915d8

data/.gitignore

@@ -7,3 +7,4 @@
 /log
 
 /Gemfile.lock
+.byebug_history

data/.travis.yml

@@ -13,23 +13,19 @@ before_install:
 
 install:
   - bundle install --jobs=3 --retry=3
-  - >-
-    curl -H 'Cache-Control: no-cache'
-    https://raw.githubusercontent.com/mdsol/fossa_ci_scripts/main/travis_ci/fossa_install.sh |
-    bash -s -- -b $TRAVIS_BUILD_DIR
+  - |-
+    curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/mdsol/fossa_ci_scripts/master/travis_ci/fossa_install.sh | bash -s -- -b $TRAVIS_BUILD_DIR
 
 script:
   - bundle exec rspec
-  - >-
-    curl -H 'Cache-Control: no-cache'
-    https://raw.githubusercontent.com/mdsol/fossa_ci_scripts/main/travis_ci/fossa_run.sh |
-    bash -s -- -b $TRAVIS_BUILD_DIR
+  - |-
+    curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/mdsol/fossa_ci_scripts/master/travis_ci/fossa_run.sh | bash -s -- -b $TRAVIS_BUILD_DIR
 
 deploy:
   provider: rubygems
   gem: mauth-client
   api_key:
-    secure: QDp0P/lMGLYc4+A3M6VD9y551X6GrGwOSBE6xSG4lE6mPXoSISK5Yj18vNWQRQuQ4BsE6CdfZ/xsPjSRDda6b+yUQbgisjJ+Ry6jUVE1v9UKTZ0VHgHyXcsaJFC29tBKBeuGCj0AD5qhbTO1+ybeZSUfdSeVVoidD4W/bSnvzlT1Lht7IE8jbHbR57LsJKoEaDxKu33dg4CYV96xrlYGxHAS2UgEgi5Ve3ohzBWkX9RWF/wWoGCzIYhJBzXgCEEFw8iWkspjTePgv9yjD2HIMtF44aiSTHM5iqBBsYJ7A8+kUwoq7+srsashHZ1wZz1YulsCSkjwM9AXZ4E0f9AnERw/RQ5gG7bCuHZtSG9g/0SWBQeNfkAF3An6eTSS24KVfnarGdH2bk0G28k2oP26MWiDKz8nlQxNAY4rH+dITael18bgf45H4KccQqiooBEGnuYpUAuIPB+1l+BsIcRQnrU3LDtmtZn0KrCHHJ7EHOdogOG+/Pxof8ht1xF7V+HYhhzSRJs2JkvmZsp4q2T7W6b6kfi59Cz3LpqA1HHYcL5/OFZeLA/TlCNke0CRMxG8k3udDKj50jqFATXEa8lNyGLjmWh7tL9Bb/uy+CU47qUdx+V4K+kheAvNFtHfpxmyUGJSY0FH02H1VBPWm10DZ7kH+6jgCKyXuql+yWDw62s=
+    secure: J0aPDp4+Ev2L+ZDcgpF+hAG95S4IsD6pCiDRxDWnrk79P5hq1rXoD3S39ANyqtQEQqkoVjsgoSP5JLi420aL2lYj7mhvaEOty9fK+flwUhI4nw+Gztm7EKNDNX8WKvk4fl4Zc7noIeI0uyes867hDjRQfyYvUuma7aK5H9NWzNUV9Q+KrVAoneVDGnNydxwkuuIpOFdjbVQgNpxVhVBV7Q4OLsB1KtWB9lptMwhqnyqZKex7JZ+37sojaj3oVT5ijrnAm+bR1QO1hGIOwuBako2iz+MBZHPccM4BEFsZme/7olypxv0JfeCuhqDnH1VWIFh6IZRDeLnZuX3qOhkdx4HLwxB//5O5+iapK0wh1zbnLvXqkE1dalUHyaZzStKH9xchIWl5I77Ica232OJYrpj9hhroae0p3VARF0IoZceKaH8NnMpq+nBAW4REcWrqPpe9xkRLDTNibkpaAy08vGOF2kPZkWw4lfkVBM1+wjY2xDn6wJ7VgQ1BeosbeTXbmny2TUeI22beihn894tzpCPPHiTRvKu0lV3jBfeoOAXzE333PrGm3zF9MDhg+1/iBwXVhdoOwEwBPQ/3Hu37xJn0AfRneni4StYnIkZ1Ur9Vub03J/3C3Aw6it99rQSWvC+2PzHqQhsG22VprvxlozFe1jFzdqKgvDkbkn44ltI=
   on:
     tags: true
     repo: mdsol/mauth-client-ruby

data/CHANGELOG.md

@@ -1,8 +1,8 @@
-## v4.2.1
-* Fix SecurityTokenCacher to not cache tokens forever.
-
-## v4.2.0
-* Drop legacy security token expiry in favor of honoring server cache headers via Faraday HTTP Cache Middleware.
+## v5.0.0
+- Add support for MWSV2 protocol.
+- Change request signing to sign with both V1 and V2 protocols by default.
+- Update log message for authentication request to include protocol version used.
+- Added `benchmark` rake task to benchmark request signing and authentication.
 
 ## v4.1.1
 - Use warning level instead of error level for logs about missing mauth header.

data/CONTRIBUTING.md

@@ -18,3 +18,11 @@ Next, run the tests:
 ```
 bundle exec rspec
 ```
+
+## Running Benchmark
+
+If you make changes which could affect performance, please run the benchmark before and after the change as a sanity check.
+
+```
+bundle exec rake benchmark
+```

data/README.md

@@ -1,10 +1,10 @@
-# MAuth Client
+# MAuth-Client
 [![Build Status](https://travis-ci.org/mdsol/mauth-client-ruby.svg?branch=master)](https://travis-ci.org/mdsol/mauth-client-ruby)
 
 This gem consists of MAuth::Client, a class to manage the information needed to both sign and authenticate requests
 and responses, and middlewares for Rack and Faraday which leverage the client's capabilities.
 
-MAuth Client exists in a variety of languages (.Net, Go, R etc.), see the [implementations list](doc/implementations.md) for more info.
+MAuth-Client exists in a variety of languages (.Net, Go, R etc.), see the [implementations list](doc/implementations.md) for more info.
 
 ## Installation
 
@@ -47,12 +47,19 @@ Remote authentication therefore requires more time than local authentication.
 You will not be able to sign your responses without an `app_uuid` and a private key, so `MAuth::Rack::ResponseSigner` cannot be used.
 
 The `mauth_baseurl` and `mauth_api_version` are required in mauth.yml.
-These tell the MAuth Client where and how to communicate with the MAuth service.
+These tell the MAuth-Client where and how to communicate with the MAuth service.
 
+The `v2_only_sign_requests` and `v2_only_authenticate` flags were added to facilitate conversion from the MAuth V1 protocol to the MAuth
+V2 protocol. By default both of these flags are false. See [Protocol Versions](#protocol-versions) below for more information about the different versions.
+
+|       | v2_only_sign_requests         | v2_only_authenticate                                                            |
+|-------|------------------------------------|--------------------------------------------------------------------------------------|
+| true  | requests are signed with only V2   | requests and responses are authenticated with only V2                                |
+| false | requests are signed with V1 and V2 | requests and responses are authenticated with the highest available protocol version |
 
 ## Rack Middleware Usage
 
-MAuth Client provides a middleware for request authentication and response verification in mauth/rack.
+MAuth-Client provides a middleware for request authentication and response verification in mauth/rack.
 
 ```ruby
 require 'mauth/rack'
@@ -212,13 +219,13 @@ Create a `MAuth::Request` object from the information in your HTTP request, what
 
 ```ruby
 require 'mauth/request_and_response'
-request = MAuth::Request.new(verb: my_verb, request_url: my_request_url, body: my_body)
+request = MAuth::Request.new(verb: my_verb, request_url: my_request_url, body: my_body, query_string: my_query_string)
 ```
 `mauth_client.signed_headers(request)` will then return mauth headers which you can apply to your request.
 
 ## Local Authentication
 
-When doing local authentication, the mauth client will periodically fetch and cache public keys from MAuth.
+When doing local authentication, the MAuth-Client will periodically fetch and cache public keys from MAuth.
 Each public key will be cached locally for 60 seconds.
 Applications which connect frequently to the app will benefit most from this caching strategy.
 When fetching public keys from MAuth, the following rules apply:
@@ -233,3 +240,8 @@ When fetching public keys from MAuth, the following rules apply:
 During development classes are typically not cached in Rails applications.
 If this is the case, be aware that the MAuth-Client middleware object will be instantiated anew for each request;
 this will cause applications performing local authentication to fetch public keys before each request is authenticated.
+
+## Protocol Versions
+
+The mauth V2 protocol was added as of v5.0.0. This protocol updates the string_to_sign to include query parameters, uses different authentication header names, and has a few other changes. See this document for more information: (DOC?). By default MAuth-Client will authenticate incoming requests with only the highest version of the protocol present, and sign their outgoing responses with only the version used to authenticate the request. By default MAuth-Client will sign outgoing requests with both the V1 and V2 protocols, and authenticate their incoming responses with only the highest version of the protocol present.
+If the `v2_only_sign_requests` flag is true all outgoing requests will be signed with only the V2 protocol (outgoing responses will still be signed with whatever protocol used to authenticate the request). If the `v2_only_authenticate` flag is true then MAuth-Client will reject any incoming request or incoming response that does not use the V2 protocol.

data/Rakefile

@@ -1,6 +1,113 @@
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
+require 'mauth/request_and_response'
+require 'mauth/client'
+require 'securerandom'
+require 'benchmark/ips'
+require 'faraday'
+require 'rspec/mocks/standalone'
 
 RSpec::Core::RakeTask.new(:spec)
 
 task default: :spec
+
+class TestSignableRequest < MAuth::Request
+  include MAuth::Signed
+  attr_accessor :headers
+
+  def merge_headers(headers)
+    self.class.new(@attributes_for_signing).tap{|r| r.headers = (@headers || {}).merge(headers) }
+  end
+
+  def x_mws_time
+    headers['X-MWS-Time']
+  end
+
+  def x_mws_authentication
+    headers['X-MWS-Authentication']
+  end
+
+  def mcc_time
+    headers['MCC-Time']
+  end
+
+  def mcc_authentication
+    headers['MCC-Authentication']
+  end
+end
+
+desc 'Runs benchmarks for the library.'
+task :benchmark do
+  mc = MAuth::Client.new(
+    private_key: OpenSSL::PKey::RSA.generate(2048),
+    app_uuid: SecureRandom.uuid,
+    v2_only_sign_requests: false
+  )
+  authenticating_mc = MAuth::Client.new(mauth_baseurl: 'http://whatever', mauth_api_version: 'v1')
+
+  stubs = Faraday::Adapter::Test::Stubs.new
+  test_faraday = ::Faraday.new do |builder|
+    builder.adapter(:test, stubs)
+  end
+  stubs.post('/mauth/v1/authentication_tickets.json') { [204, {}, []] }
+  allow(Faraday).to receive(:new).and_return(test_faraday)
+
+  short_body = 'Somewhere in La Mancha, in a place I do not care to remember'
+  average_body = short_body * 1_000
+  huge_body = average_body * 100
+
+  qs = 'don=quixote&quixote=don'
+
+  puts <<-MSG
+
+    A short request has a body of 60 chars.
+    An average request has a body of 60,000 chars.
+    A huge request has a body of 6,000,000 chars.
+    A qs request has a body of 60 chars and a query string with two k/v pairs.
+
+  MSG
+
+  short_request = TestSignableRequest.new(verb: 'PUT', request_url: '/', body: short_body)
+  qs_request = TestSignableRequest.new(verb: 'PUT', request_url: '/', body: short_body, query_string: qs)
+  average_request = TestSignableRequest.new(verb: 'PUT', request_url: '/', body: average_body)
+  huge_request = TestSignableRequest.new(verb: 'PUT', request_url: '/', body: huge_body)
+
+  v1_short_signed_request = mc.signed_v1(short_request)
+  v1_average_signed_request = mc.signed_v1(average_request)
+  v1_huge_signed_request = mc.signed_v1(huge_request)
+
+  v2_short_signed_request = mc.signed_v2(short_request)
+  v2_qs_signed_request = mc.signed_v1(qs_request)
+  v2_average_signed_request = mc.signed_v2(average_request)
+  v2_huge_signed_request = mc.signed_v1(huge_request)
+
+  Benchmark.ips do |bm|
+    bm.report('v1-sign-short') { mc.signed_v1(short_request) }
+    bm.report('v2-sign-short') { mc.signed_v2(short_request) }
+    bm.report('both-sign-short') { mc.signed(short_request) }
+    bm.report('v2-sign-qs') { mc.signed_v2(qs_request) }
+    bm.report('both-sign-qs') { mc.signed(qs_request) }
+    bm.report('v1-sign-average') { mc.signed_v1(average_request) }
+    bm.report('v2-sign-average') { mc.signed_v2(average_request) }
+    bm.report('both-sign-average') { mc.signed(average_request) }
+    bm.report('v1-sign-huge') { mc.signed_v1(huge_request) }
+    bm.report('v2-sign-huge') { mc.signed_v2(huge_request) }
+    bm.report('both-sign-huge') { mc.signed(huge_request) }
+    bm.compare!
+  end
+
+  puts "i/s means the number of signatures of a message per second.\n\n\n"
+
+  Benchmark.ips do |bm|
+    bm.report('v1-authenticate-short') { authenticating_mc.authentic?(v1_short_signed_request) }
+    bm.report('v2-authenticate-short') { authenticating_mc.authentic?(v2_short_signed_request) }
+    bm.report('v2-authenticate-qs') { authenticating_mc.authentic?(v2_qs_signed_request) }
+    bm.report('v1-authenticate-average') { authenticating_mc.authentic?(v1_average_signed_request) }
+    bm.report('v2-authenticate-average') { authenticating_mc.authentic?(v2_average_signed_request) }
+    bm.report('v1-authenticate-huge') { authenticating_mc.authentic?(v1_huge_signed_request) }
+    bm.report('v2-authenticate-huge') { authenticating_mc.authentic?(v2_huge_signed_request) }
+    bm.compare!
+  end
+
+  puts 'i/s means the number of authentication checks of signatures per second.'
+end

data/exe/mauth-client

@@ -11,7 +11,7 @@ require 'mauth/faraday'
 require 'yaml'
 require 'term/ansicolor'
 
-# OPTION PARSER 
+# OPTION PARSER
 
 require 'optparse'
 
@@ -53,10 +53,10 @@ end
 opt_parser.parse!
 abort(opt_parser.help) unless (2..3).include?(ARGV.size)
 
-# FIND MAUTH CONFIG 
+# FIND MAUTH CONFIG
 
 possible_mauth_config_files = [
-  # whoops, I called this MAUTH_CONFIG_YML in one place and MAUTH_CONFIG_YAML in another. supporting both for now. 
+  # whoops, I called this MAUTH_CONFIG_YML in one place and MAUTH_CONFIG_YAML in another. supporting both for now.
   ENV['MAUTH_CONFIG_YML'],
   ENV['MAUTH_CONFIG_YAML'],
   '~/.mauth_config.yml',
@@ -76,14 +76,14 @@ end
 
 mauth_config = MAuth::Client.default_config(:mauth_config_yml => File.expand_path(mauth_config_yml))
 
-# INSTANTIATE MAUTH CLIENT 
+# INSTANTIATE MAUTH CLIENT
 
 logger = Logger.new(STDERR)
 mauth_client = MAuth::Client.new(mauth_config.merge('logger' => logger))
 
-# OUTPUTTERS FOR FARADAY THAT SHOULD MOVE TO A LIB SOMEWHERE 
+# OUTPUTTERS FOR FARADAY THAT SHOULD MOVE TO A LIB SOMEWHERE
 
-# outputs the response body to the given output device (defaulting to STDOUT) 
+# outputs the response body to the given output device (defaulting to STDOUT)
 class FaradayOutputter < Faraday::Middleware
   def initialize(app, outdev=STDOUT)
     @app=app
@@ -97,12 +97,12 @@ class FaradayOutputter < Faraday::Middleware
   end
 end
 
-# this is to approximate `curl -v`s output. but it's all faked, whereas curl gives you 
-# the real text written and read for request and response. whatever, close enough. 
+# this is to approximate `curl -v`s output. but it's all faked, whereas curl gives you
+# the real text written and read for request and response. whatever, close enough.
 class FaradayCurlVOutputter < FaradayOutputter
 
-  # defines a method with the given name, applying coloring defined by any additional arguments. 
-  # if $options[:color] is set, respects that; otherwise, applies color if the output device is a tty. 
+  # defines a method with the given name, applying coloring defined by any additional arguments.
+  # if $options[:color] is set, respects that; otherwise, applies color if the output device is a tty.
   def self.color(name, *color_args)
     define_method(name) do |arg|
       if color?
@@ -159,8 +159,8 @@ class FaradayCurlVOutputter < FaradayOutputter
     $options[:color].nil? ? @outdev.tty? : $options[:color]
   end
 
-  # a mapping for each registered CodeRay scanner to the Media Types which represent 
-  # that language. extremely incomplete! 
+  # a mapping for each registered CodeRay scanner to the Media Types which represent
+  # that language. extremely incomplete!
   CodeRayForMediaTypes = {
     :c => [],
     :cpp => [],
@@ -184,7 +184,7 @@ class FaradayCurlVOutputter < FaradayOutputter
   }
 
   # takes a body and a content type; returns the body, with coloring (ansi colors for terminals)
-  # possibly added, if it's a recognized content type and #color? is true 
+  # possibly added, if it's a recognized content type and #color? is true
   def color_body_by_content_type(body, content_type)
     if body && color?
       # kinda hacky way to get the media_type. faraday should supply this ...
@@ -207,7 +207,7 @@ class FaradayCurlVOutputter < FaradayOutputter
   end
 end
 
-# CONFIGURE THE FARADAY CONNECTION 
+# CONFIGURE THE FARADAY CONNECTION
 faraday_options = {}
 if $options[:no_ssl_verify]
   faraday_options[:ssl] = {:verify => false}
@@ -233,8 +233,8 @@ if $options[:content_type]
   headers['Content-Type'] = $options[:content_type]
 else
   if body
-    # I'd rather not have a default content-type, but if none is set then the HTTP adapter sets this to 
-    # application/x-www-form-urlencoded anyway. application/json is a better default for our purposes. 
+    # I'd rather not have a default content-type, but if none is set then the HTTP adapter sets this to
+    # application/x-www-form-urlencoded anyway. application/json is a better default for our purposes.
     headers['Content-Type'] = 'application/json'
   end
 end
@@ -251,10 +251,10 @@ end
 
 begin
   response = connection.run_request(httpmethod.downcase.to_sym, url, body, headers)
-rescue MAuth::InauthenticError, MAuth::UnableToAuthenticateError => e
+rescue MAuth::InauthenticError, MAuth::UnableToAuthenticateError, MAuth::MAuthNotPresent, MAuth::MissingV2Error => e
   if $options[:color].nil? ? STDERR.tty? : $options[:color]
-    class_color = Term::ANSIColor.method(e.is_a?(MAuth::InauthenticError) ? :intense_red : :intense_yellow)
-    message_color = Term::ANSIColor.method(e.is_a?(MAuth::InauthenticError) ? :red : :yellow)
+    class_color = Term::ANSIColor.method(e.is_a?(MAuth::UnableToAuthenticateError) ? :intense_yellow : :intense_red)
+    message_color = Term::ANSIColor.method(e.is_a?(MAuth::UnableToAuthenticateError) ? :yellow : :red)
   else
     class_color = proc{|s| s }
     message_color = proc{|s| s }

data/lib/mauth/client/authenticator_base.rb

@@ -0,0 +1,118 @@
+# methods common to RemoteRequestAuthenticator and LocalAuthenticator
+
+module MAuth
+  class Client
+    module AuthenticatorBase
+      ALLOWED_DRIFT_SECONDS = 300
+
+      # takes an incoming request or response object, and returns whether
+      # the object is authentic according to its signature.
+      def authentic?(object)
+        log_authentication_request(object)
+        begin
+          authenticate!(object)
+          true
+        rescue InauthenticError, MAuthNotPresent, MissingV2Error
+          false
+        end
+      end
+
+      # raises InauthenticError unless the given object is authentic. Will only
+      # authenticate with v2 if the environment variable V2_ONLY_AUTHENTICATE
+      # is set. Otherwise will authenticate with only the highest protocol version present
+      def authenticate!(object)
+        if object.protocol_version == 2
+          authenticate_v2!(object)
+        elsif object.protocol_version == 1
+          if v2_only_authenticate?
+            # If v2 is required but not present and v1 is present we raise MissingV2Error
+            msg = 'This service requires mAuth v2 mcc-authentication header but only v1 x-mws-authentication is present'
+            logger.error(msg)
+            raise MissingV2Error, msg
+          end
+
+          authenticate_v1!(object)
+        else
+          sub_str = v2_only_authenticate? ? '' : 'X-MWS-Authentication header is blank, '
+          msg = "Authentication Failed. No mAuth signature present; #{sub_str}MCC-Authentication header is blank."
+          logger.warn("mAuth signature not present on #{object.class}. Exception: #{msg}")
+          raise MAuthNotPresent, msg
+        end
+      end
+
+      private
+
+      # Note: This log is likely consumed downstream and the contents SHOULD NOT
+      # be changed without a thorough review of downstream consumers.
+      def log_authentication_request(object)
+        object_app_uuid = object.signature_app_uuid || '[none provided]'
+        object_token = object.signature_token || '[none provided]'
+        logger.info(
+          "Mauth-client attempting to authenticate request from app with mauth" \
+          " app uuid #{object_app_uuid} to app with mauth app uuid #{client_app_uuid}" \
+          " using version #{object_token}."
+        )
+      end
+
+      def log_inauthentic(object, message)
+        logger.error("mAuth signature authentication failed for #{object.class}. Exception: #{message}")
+      end
+
+      def time_within_valid_range!(object, time_signed, now = Time.now)
+        return if  (-ALLOWED_DRIFT_SECONDS..ALLOWED_DRIFT_SECONDS).cover?(now.to_i - time_signed)
+
+        msg = "Time verification failed. #{time_signed} not within #{ALLOWED_DRIFT_SECONDS} of #{now}"
+        log_inauthentic(object, msg)
+        raise InauthenticError, msg
+      end
+
+      # V1 helpers
+      def authenticate_v1!(object)
+        time_valid_v1!(object)
+        token_valid_v1!(object)
+        signature_valid_v1!(object)
+      end
+
+      def time_valid_v1!(object)
+        if object.x_mws_time.nil?
+          msg = 'Time verification failed. No x-mws-time present.'
+          log_inauthentic(object, msg)
+          raise InauthenticError, msg
+        end
+        time_within_valid_range!(object, object.x_mws_time.to_i)
+      end
+
+      def token_valid_v1!(object)
+        return if object.signature_token == MWS_TOKEN
+
+        msg = "Token verification failed. Expected #{MWS_TOKEN}; token was #{object.signature_token}"
+        log_inauthentic(object, msg)
+        raise InauthenticError, msg
+      end
+
+      # V2 helpers
+      def authenticate_v2!(object)
+        time_valid_v2!(object)
+        token_valid_v2!(object)
+        signature_valid_v2!(object)
+      end
+
+      def time_valid_v2!(object)
+        if object.mcc_time.nil?
+          msg = 'Time verification failed. No MCC-Time present.'
+          log_inauthentic(object, msg)
+          raise InauthenticError, msg
+        end
+        time_within_valid_range!(object, object.mcc_time.to_i)
+      end
+
+      def token_valid_v2!(object)
+        return if object.signature_token == MWSV2_TOKEN
+
+        msg = "Token verification failed. Expected #{MWSV2_TOKEN}; token was #{object.signature_token}"
+        log_inauthentic(object, msg)
+        raise InauthenticError, msg
+      end
+    end
+  end
+end

data/lib/mauth/client/local_authenticator.rb

@@ -0,0 +1,137 @@
+require 'mauth/client/security_token_cacher'
+require 'mauth/client/signer'
+require 'openssl'
+
+# methods to verify the authenticity of signed requests and responses locally, retrieving
+# public keys from the mAuth service as needed
+
+module MAuth
+  class Client
+    module LocalAuthenticator
+      private
+
+      def signature_valid_v1!(object)
+        # We are in an unfortunate situation in which Euresource is percent-encoding parts of paths, but not
+        # all of them.  In particular, Euresource is percent-encoding all special characters save for '/'.
+        # Also, unfortunately, Nginx unencodes URIs before sending them off to served applications, though
+        # other web servers (particularly those we typically use for local testing) do not.  The various forms
+        # of the expected string to sign are meant to cover the main cases.
+        # TODO:  Revisit and simplify this unfortunate situation.
+
+        original_request_uri = object.attributes_for_signing[:request_url]
+
+        # craft an expected string-to-sign without doing any percent-encoding
+        expected_no_reencoding = object.string_to_sign_v1(time: object.x_mws_time, app_uuid: object.signature_app_uuid)
+
+        # do a simple percent reencoding variant of the path
+        object.attributes_for_signing[:request_url] = CGI.escape(original_request_uri.to_s)
+        expected_for_percent_reencoding = object.string_to_sign_v1(time: object.x_mws_time, app_uuid: object.signature_app_uuid)
+
+        # do a moderately complex Euresource-style reencoding of the path
+        object.attributes_for_signing[:request_url] = euresource_escape(original_request_uri.to_s)
+        expected_euresource_style_reencoding = object.string_to_sign_v1(time: object.x_mws_time, app_uuid: object.signature_app_uuid)
+
+        # reset the object original request_uri, just in case we need it again
+        object.attributes_for_signing[:request_url] = original_request_uri
+
+        begin
+          pubkey = OpenSSL::PKey::RSA.new(retrieve_public_key(object.signature_app_uuid))
+          actual = pubkey.public_decrypt(Base64.decode64(object.signature))
+        rescue OpenSSL::PKey::PKeyError => e
+          msg = "Public key decryption of signature failed! #{e.class}: #{e.message}"
+          log_inauthentic(object, msg)
+          raise InauthenticError, msg
+        end
+
+        unless verify_signature_v1!(actual, expected_no_reencoding) ||
+           verify_signature_v1!(actual, expected_euresource_style_reencoding) ||
+           verify_signature_v1!(actual, expected_for_percent_reencoding)
+          msg = "Signature verification failed for #{object.class}"
+          log_inauthentic(object, msg)
+          raise InauthenticError, msg
+        end
+      end
+
+      def verify_signature_v1!(actual, expected_str_to_sign)
+        actual == Digest::SHA512.hexdigest(expected_str_to_sign)
+      end
+
+      def signature_valid_v2!(object)
+        # We are in an unfortunate situation in which Euresource is percent-encoding parts of paths, but not
+        # all of them.  In particular, Euresource is percent-encoding all special characters save for '/'.
+        # Also, unfortunately, Nginx unencodes URIs before sending them off to served applications, though
+        # other web servers (particularly those we typically use for local testing) do not.  The various forms
+        # of the expected string to sign are meant to cover the main cases.
+        # TODO:  Revisit and simplify this unfortunate situation.
+
+        original_request_uri = object.attributes_for_signing[:request_url]
+        original_query_string = object.attributes_for_signing[:query_string]
+
+        # craft an expected string-to-sign without doing any percent-encoding
+        expected_no_reencoding = object.string_to_sign_v2(
+          time: object.mcc_time,
+          app_uuid: object.signature_app_uuid
+        )
+
+        # do a simple percent reencoding variant of the path
+        expected_for_percent_reencoding = object.string_to_sign_v2(
+          time: object.mcc_time,
+          app_uuid: object.signature_app_uuid,
+          request_url: CGI.escape(original_request_uri.to_s),
+          query_string: CGI.escape(original_query_string.to_s)
+        )
+
+        # do a moderately complex Euresource-style reencoding of the path
+        expected_euresource_style_reencoding = object.string_to_sign_v2(
+          time: object.mcc_time,
+          app_uuid: object.signature_app_uuid,
+          request_url: euresource_escape(original_request_uri.to_s),
+          query_string: euresource_escape(original_query_string.to_s)
+        )
+
+        pubkey = OpenSSL::PKey::RSA.new(retrieve_public_key(object.signature_app_uuid))
+        actual = Base64.decode64(object.signature)
+
+        unless verify_signature_v2!(object, actual, pubkey, expected_no_reencoding) ||
+           verify_signature_v2!(object, actual, pubkey, expected_euresource_style_reencoding) ||
+           verify_signature_v2!(object, actual, pubkey, expected_for_percent_reencoding)
+          msg = "Signature inauthentic for #{object.class}"
+          log_inauthentic(object, msg)
+          raise InauthenticError, msg
+        end
+      end
+
+      def verify_signature_v2!(object, actual, pubkey, expected_str_to_sign)
+        pubkey.verify(
+          MAuth::Client::SIGNING_DIGEST,
+          actual,
+          expected_str_to_sign
+        )
+      rescue OpenSSL::PKey::PKeyError => e
+        msg = "RSA verification of signature failed! #{e.class}: #{e.message}"
+        log_inauthentic(object, msg)
+        raise InauthenticError, msg
+      end
+
+      # Note: RFC 3986 (https://www.ietf.org/rfc/rfc3986.txt) reserves the forward slash "/"
+      #   and number sign "#" as component delimiters. Since these are valid URI components,
+      #   they are decoded back into characters here to avoid signature invalidation
+      def euresource_escape(str)
+        CGI.escape(str).gsub(/%2F|%23/, '%2F' => '/', '%23' => '#')
+      end
+
+      def retrieve_public_key(app_uuid)
+        retrieve_security_token(app_uuid)['security_token']['public_key_str']
+      end
+
+      def retrieve_security_token(app_uuid)
+        security_token_cacher.get(app_uuid)
+      end
+
+      def security_token_cacher
+        @security_token_cacher ||= SecurityTokenCacher.new(self)
+      end
+
+    end
+  end
+end