json_web_token 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 59b01a64cc639bdaeeac72c076ba017f0f587d96
-  data.tar.gz: 1d751ccca27d4693dedc63fb45c4ed7139a66abf
+  metadata.gz: c926ffcdb482f32a80eb5e1d15100d5e03be4101
+  data.tar.gz: f64c2145334ff5c4df4d65816b2295de71a87ead
 SHA512:
-  metadata.gz: 85411ccec175d81fa600fcb85a67d4848e87b74f4a2b724550d39da8b0c48610709a75453ceee620de4bbeb109d48c06f996288cbe9fff937a92496fb38d1d11
-  data.tar.gz: f128850d5fd8d57a325778d0d21a5ae96ace9d198670d2ae01a905061becf8d7643e848ed2aa23b905193e18875ab5316cab56ba3db341f7b5a60f16cab27fd1
+  metadata.gz: d6b6b657427e96afc712ff7fcb2af970a1a77ceba8d3579491076ea3fe2b139c51341518778d89475d1e8a1db54fec1046d89f5577ed86fcbcd10149d451ddd0
+  data.tar.gz: 4f658d73cfc3efd1a4f80aa96e93a7884d6a05a1e83fd6d7ad346a6407eb697c04882b8dd5900c71c8c2094785cdac0a8bbfc23f50b33d8d2946e15ca3a0914f

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## Changelog
 
+### v0.3.0 (2015-08-25)
+
+* backward incompatible changes
+  * JsonWebToken, Jwt, and Jws #verify return values
+
 ### v0.2.2 (2015-08-06)
 
 * enhancements

data/README.md

@@ -64,9 +64,9 @@ jwt = JsonWebToken.sign({foo: 'bar'}, alg: 'none')
 
 ### JsonWebToken.verify(jwt, options)
 
-Returns either:
-* a JWT claims set string or hash, if the Message Authentication Code (MAC), or signature, is verified
-* a hash, error: 'invalid', otherwise
+Returns a hash:
+* \{ok: < JWT claims set >\}, if the Message Authentication Code (MAC), or signature, is verified
+* \{error: 'invalid'\}, otherwise
 
 `jwt` (required) is a JSON web token string
 
@@ -83,7 +83,7 @@ require 'json_web_token'
 secure_jwt_example = 'eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt.cGxlLmNvbS9pc19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk'
 
 # verify with default algorithm, HMAC SHA256
-claims = JsonWebToken.verify(secure_jwt_example, key: 'gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr9C')
+\{ok: claims\} = JsonWebToken.verify(secure_jwt_example, key: 'gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr9C')
 
 # verify with RSA SHA256 algorithm
 opts = {
@@ -91,12 +91,12 @@ opts = {
   key: < RSA public key >
 }
 
-claims = JsonWebToken.verify(jwt, opts)
+\{ok: claims\} = JsonWebToken.verify(jwt, opts)
 
 # unsecured token (algorithm is 'none')
 unsecured_jwt_example = 'eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt.'
 
-claims = JsonWebToken.verify(unsecured_jwt_example, alg: 'none')
+\{ok: claims\} = JsonWebToken.verify(unsecured_jwt_example, alg: 'none')
 
 ```
 ### Supported encryption algorithms

data/lib/json_web_token.rb

@@ -20,12 +20,13 @@ module JsonWebToken
   
   # @param jwt [String] a JSON Web Token
   # @param options [Hash] specify the desired verifying algorithm and verifying key
-  # @return [Hash] a JWT claims set if the jwt verifies, or +error: 'Invalid'+ otherwise
+  # @return [Hash] +{ok: < the jwt claims set hash >}+ if the jwt verifies,
+  #   or +{error: 'Invalid'}+ otherwise
   # @example
   #   jwt = 'eyJhbGciOiJIUzI1NiJ9.cGF5bG9hZA.uVTaOdyzp_f4mT_hfzU8LnCzdmlVC4t2itHDEYUZym4'
   #   options = {alg: 'HS256', key: 'gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr9C'}
   #   JsonWebToken.verify(jwt, options)
-  #   # => {iss: 'joe', exp: 1300819380, :'http://example.com/is_root' => true}
+  #   # => {ok: {iss: 'joe', exp: 1300819380, :'http://example.com/is_root' => true}}
   def verify(jwt, options)
     Jwt.verify(jwt, options)
   end

data/lib/json_web_token/jws.rb

@@ -46,17 +46,18 @@ module JsonWebToken
     # @param algorithm [String] 'alg' header parameter value for JWS
     # @param key [String | OpenSSL::PKey::RSA | OpenSSL::PKey::EC] key used to verify
     #   a digital signature, or mac
-    # @return [String | Boolean] a JWS if the mac verifies, or +false+ otherwise
+    # @return [Hash] +{ok: <the jws string>}+ if the mac verifies,
+    #   or +{error: 'invalid'}+ otherwise
     # @example
     #   jws = 'eyJhbGciOiJIUzI1NiJ9.cGF5bG9hZA.uVTaOdyzp_f4mT_hfzU8LnCzdmlVC4t2itHDEYUZym4'
     #   key = 'gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr9C'
     #   Jws.verify(jws, 'HS256', key)
-    #   # => 'eyJhbGciOiJIUzI1NiJ9.cGF5bG9hZA.uVTaOdyzp_f4mT_hfzU8LnCzdmlVC4t2itHDEYUZym4'
+    #   # => {ok: 'eyJhbGciOiJIUzI1NiJ9.cGF5bG9hZA.uVTaOdyzp_f4mT_hfzU8LnCzdmlVC4t2itHDEYUZym4'}
     # @see http://tools.ietf.org/html/rfc7515#page-16
     def verify(jws, algorithm, key = nil)
-      compare_alg(jws, algorithm)
-      return jws if algorithm == 'none'
-      signature_verify?(jws, algorithm, key) ? jws : false
+      validate_alg_match(jws, algorithm)
+      return {ok: jws} if algorithm == 'none'
+      signature_verify?(jws, algorithm, key) ? {ok: jws} : {error: 'invalid'}
     end
 
     def alg_parameter(header)
@@ -73,7 +74,7 @@ module JsonWebToken
     end
 
     # http://tools.ietf.org/html/rfc7515#section-4.1.1
-    def compare_alg(jws, algorithm)
+    def validate_alg_match(jws, algorithm)
       header = decoded_header_json_to_hash(jws)
       unless alg_parameter(header) == algorithm
         fail("Algorithm not matching 'alg' header parameter")
@@ -95,7 +96,7 @@ module JsonWebToken
     private_class_method :alg_parameter,
       :encode_input,
       :signature,
-      :compare_alg,
+      :validate_alg_match,
       :decoded_header_json_to_hash,
       :signature_verify?
   end

data/lib/json_web_token/jwt.rb

@@ -34,17 +34,17 @@ module JsonWebToken
 
     # @param jwt [String] a JSON Web Token
     # @param options [Hash] specify the desired verifying algorithm and verifying key
-    # @return [Hash] a JWT claims set if the jwt verifies, or +error: 'Invalid'+ otherwise
+    # @return [Hash] +{ok: <the jwt claims set hash>}+ if the jwt verifies,
+    #   or +{error: 'Invalid'}+ otherwise
     # @example
     #   jwt = 'eyJhbGciOiJIUzI1NiJ9.cGF5bG9hZA.uVTaOdyzp_f4mT_hfzU8LnCzdmlVC4t2itHDEYUZym4'
     #   options = {alg: 'HS256', key: 'gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr9C'}
     #   Jwt.verify(jwt, options)
-    #   # => {iss: 'joe', exp: 1300819380, :'http://example.com/is_root' => true}
+    #   # => {ok: {iss: 'joe', exp: 1300819380, :'http://example.com/is_root' => true}}
     # @see see http://tools.ietf.org/html/rfc7519#section-7.2
     def verify(jwt, options)
       alg = options[:alg] || ALG_DEFAULT
-      jws = Jws.verify(jwt, alg, options[:key])
-      jws ? Util.symbolize_keys(decoded_message_json_to_hash jws) : {error: 'invalid'}
+      payload(Jws.verify(jwt, alg, options[:key]))
     end
 
     def validated_message(claims)
@@ -62,15 +62,22 @@ module JsonWebToken
       alg && !alg.empty? ? hsh : {}
     end
 
-    def decoded_message_json_to_hash(jws)
-      ary = jws.split('.')
-      return jws unless ary.length > 1 # invalid
-      JSON.parse(Format::Base64Url.decode ary[1])
+    def payload(hsh)
+      return {error: 'invalid'} if hsh[:error]
+      ary = hsh[:ok].split('.')
+      return {error: 'invalid JWS'} unless ary.length > 1
+      encoded_claims = ary[1]
+      {ok: payload_to_hash(encoded_claims)}
+    end
+
+    def payload_to_hash(encoded_claims)
+      Util.symbolize_keys(JSON.parse(Format::Base64Url.decode encoded_claims))
     end
 
     private_class_method :validated_message,
       :config_header,
       :alg_parameter_required,
-      :decoded_message_json_to_hash
+      :payload,
+      :payload_to_hash
   end
 end

data/lib/json_web_token/version.rb

@@ -1,3 +1,3 @@
 module JsonWebToken
-  VERSION = '0.2.2'
+  VERSION = '0.3.0'
 end

data/spec/json_web_token/jws_spec.rb

@@ -9,7 +9,7 @@ module JsonWebToken
         shared_examples_for 'does #verify' do
           it 'w a jws' do
             jws = Jws.sign(header, payload, signing_key)
-            expect(Jws.verify jws, algorithm, verifying_key).to eql jws
+            expect(Jws.verify jws, algorithm, verifying_key).to include({ok: jws})
           end
         end
 
@@ -23,17 +23,17 @@ module JsonWebToken
               it_behaves_like 'does #verify'
 
               describe 'w/o passing key to #verify' do
-                it 'returns false' do
+                it 'returns error' do
                   jws = Jws.sign(header, payload, signing_key)
-                  expect(Jws.verify jws, algorithm, nil).to be false
+                  expect(Jws.verify jws, algorithm, nil).to include({error: 'invalid'})
                 end
               end
 
               describe 'w passing a changed key to #verify' do
                 let(:changed_key) { 'gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr9Z' }
-                it 'returns false' do
+                it 'returns error' do
                   jws = Jws.sign(header, payload, signing_key)
-                  expect(Jws.verify jws, algorithm, changed_key).to be false
+                  expect(Jws.verify jws, algorithm, changed_key).to include({error: 'invalid'})
                 end
               end
             end
@@ -59,7 +59,7 @@ module JsonWebToken
               public_key = EcdsaKey.public_key_new('256', public_key_str)
 
               jws = Jws.sign(header, payload, private_key)
-              expect(Jws.verify jws, algorithm, public_key).to eql jws
+              expect(Jws.verify jws, algorithm, public_key).to include({ok: jws})
             end
           end
         end
@@ -91,7 +91,7 @@ module JsonWebToken
             let(:algorithm) { 'none' }
             it 'w a jws' do
               jws = Jws.unsecured_message(header, payload)
-              expect(Jws.verify jws, algorithm).to eql jws
+              expect(Jws.verify jws, algorithm).to include({ok: jws})
             end
           end
 

data/spec/json_web_token/jwt_spec.rb

@@ -8,7 +8,7 @@ module JsonWebToken
       shared_examples_for 'does #verify' do
         it 'w a claims set' do
           jwt = Jwt.sign(claims, sign_options)
-          expect(Jwt.verify jwt, verify_options).to include(claims)
+          expect(Jwt.verify(jwt, verify_options)[:ok]).to include(claims)
         end
       end
 
@@ -61,7 +61,7 @@ module JsonWebToken
 
         describe 'w/o key w default header alg' do
           it 'raises' do
-            expect { JsonWebToken.sign(claims, {}) }
+            expect { Jwt.sign(claims, {}) }
               .to raise_error(RuntimeError, 'Invalid shared key')
           end
         end
@@ -88,7 +88,7 @@ module JsonWebToken
               jwt = Jwt.sign(claims, sign_options)
 
               verify_options = {alg: algorithm, key: public_key}
-              expect(Jwt.verify jwt, verify_options).to include(claims)
+              expect(Jwt.verify(jwt, verify_options)[:ok]).to eql claims
 
               expect(plausible_message_signature? jwt, 64).to be true
             end
@@ -102,7 +102,7 @@ module JsonWebToken
               let(:verify_options) { {alg: 'none'} }
               it 'verifies a plausible unsecured jws' do
                 jwt = Jwt.sign(claims, sign_options)
-                expect(Jwt.verify jwt, verify_options).to include(claims)
+                expect(Jwt.verify(jwt, verify_options)[:ok]).to include(claims)
                 expect(plausible_unsecured_message? jwt).to be true
               end
             end

data/spec/json_web_token_spec.rb

@@ -6,7 +6,7 @@ describe JsonWebToken do
     shared_examples_for 'w #verify' do
       it 'w a claims set' do
         jwt = JsonWebToken.sign(claims, sign_options)
-        expect(JsonWebToken.verify jwt, verify_options).to include(claims)
+        expect(JsonWebToken.verify(jwt, verify_options)[:ok]).to include(claims)
       end
     end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: json_web_token
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Gary Fleshman
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-08-06 00:00:00.000000000 Z
+date: 2015-08-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json