Add duplicate claim name detection per RFC 7519 Section 4

Implements duplicate claim name detection as specified in RFC 7519 Section 4, which states:

> The Claim Names within a JWT Claims Set MUST be unique; JWT parsers MUST either reject JWTs with duplicate Claim Names or use a JSON parser that returns only the lexically last duplicate member name.

This feature allows users to reject JWTs that contain duplicate keys in the header or payload, which is recommended for security-sensitive applications to prevent claim confusion attacks.

Author: ydah

CHANGELOG.md

@@ -6,7 +6,7 @@
 
 **Features:**
 
-- Your contribution here
+- Add duplicate claim name detection per RFC 7519 Section 4 [#713](https://github.com/jwt/ruby-jwt/pull/713) ([@ydah](https://github.com/ydah))
 
 **Fixes and enhancements:**
 

README.md

@@ -325,6 +325,35 @@ encoded_token.verify_signature!(algorithm: 'HS256', key: "secret")
 encoded_token.payload # => {"pay"=>"load"}
 ```
 
+## Duplicate Claim Name Detection
+
+RFC 7519 Section 4 specifies that claim names within a JWT Claims Set MUST be unique. By default, ruby-jwt follows ECMAScript 5.1 behavior and uses the last value for duplicate keys. You can enable strict duplicate key detection to reject JWTs with duplicate claim names.
+
+### Rejecting Duplicate Keys
+
+```ruby
+# Reject JWTs with duplicate keys in header or payload
+begin
+  JWT.decode(token, secret, true, algorithm: 'HS256', allow_duplicate_keys: false)
+rescue JWT::DuplicateKeyError => e
+  puts "Duplicate key detected: #{e.message}"
+end
+```
+
+### Global Configuration
+
+```ruby
+# Globally reject duplicate keys
+JWT.configure do |config|
+  config.decode.allow_duplicate_keys = false
+end
+
+# Per-decode override
+JWT.decode(token, secret, true, algorithm: 'HS256', allow_duplicate_keys: true)
+```
+
+This is recommended for security-sensitive applications to prevent attacks that exploit different systems reading different values from the same JWT.
+
 ## Claims
 
 JSON Web Token defines some reserved claim names and defines how they should be

lib/jwt/configuration/decode_configuration.rb

@@ -24,6 +24,8 @@ class DecodeConfiguration
       #   @return [Array<String>] the list of acceptable algorithms.
       # @!attribute [rw] required_claims
       #   @return [Array<String>] the list of required claims.
+      # @!attribute [rw] allow_duplicate_keys
+      #   @return [Boolean] whether to allow duplicate keys in JWT header and payload.
 
       attr_accessor :verify_expiration,
                     :verify_not_before,
@@ -34,7 +36,8 @@ class DecodeConfiguration
                     :verify_sub,
                     :leeway,
                     :algorithms,
-                    :required_claims
+                    :required_claims,
+                    :allow_duplicate_keys
 
       # Initializes a new DecodeConfiguration instance with default settings.
       def initialize
@@ -48,6 +51,7 @@ def initialize
         @leeway = 0
         @algorithms = ['HS256']
         @required_claims = []
+        @allow_duplicate_keys = true
       end
 
       # @api private
@@ -62,7 +66,8 @@ def to_h
           verify_sub: verify_sub,
           leeway: leeway,
           algorithms: algorithms,
-          required_claims: required_claims
+          required_claims: required_claims,
+          allow_duplicate_keys: allow_duplicate_keys
         }
       end
     end

lib/jwt/decode.rb

@@ -22,7 +22,7 @@ class Decode
     def initialize(jwt, key, verify, options, &keyfinder)
       raise JWT::DecodeError, 'Nil JSON web token' unless jwt
 
-      @token = EncodedToken.new(jwt)
+      @token = EncodedToken.new(jwt, allow_duplicate_keys: allow_duplicate_keys?(options))
       @key = key
       @options = options
       @verify = verify
@@ -119,5 +119,11 @@ def none_algorithm?
     def alg_in_header
       token.header['alg']
     end
+
+    def allow_duplicate_keys?(options)
+      return options[:allow_duplicate_keys] if options.key?(:allow_duplicate_keys)
+
+      JWT.configuration.decode.allow_duplicate_keys
+    end
   end
 end

lib/jwt/encoded_token.rb

@@ -11,7 +11,7 @@ module JWT
   #   encoded_token = JWT::EncodedToken.new(token.jwt)
   #   encoded_token.verify_signature!(algorithm: 'HS256', key: 'secret')
   #   encoded_token.payload # => {'pay' => 'load'}
-  class EncodedToken
+  class EncodedToken # rubocop:disable Metrics/ClassLength
     # @private
     # Allow access to the unverified payload for claim verification.
     class ClaimsContext
@@ -39,11 +39,14 @@ def payload
     # Initializes a new EncodedToken instance.
     #
     # @param jwt [String] the encoded JWT token.
+    # @param allow_duplicate_keys [Boolean] whether to allow duplicate keys in header/payload (default: true).
     # @raise [ArgumentError] if the provided JWT is not a String.
-    def initialize(jwt)
+    # @raise [JWT::DuplicateKeyError] if allow_duplicate_keys is false and duplicate keys are found.
+    def initialize(jwt, allow_duplicate_keys: true)
       raise ArgumentError, 'Provided JWT must be a String' unless jwt.is_a?(String)
 
       @jwt = jwt
+      @allow_duplicate_keys = allow_duplicate_keys
       @signature_verified = false
       @claims_verified    = false
 
@@ -224,7 +227,7 @@ def parse_unencoded(segment)
     end
 
     def parse(segment)
-      JWT::JSON.parse(segment)
+      JWT::JSON.parse(segment, allow_duplicate_keys: @allow_duplicate_keys)
     rescue ::JSON::ParserError
       raise JWT::DecodeError, 'Invalid segment encoding'
     end

lib/jwt/error.rb

@@ -51,4 +51,8 @@ class Base64DecodeError < DecodeError; end
 
   # The JWKError class is raised when there is an error with the JSON Web Key (JWK).
   class JWKError < DecodeError; end
+
+  # The DuplicateKeyError class is raised when a JWT contains duplicate keys in the header or payload.
+  # @see https://datatracker.ietf.org/doc/html/rfc7519#section-4 RFC 7519 Section 4
+  class DuplicateKeyError < DecodeError; end
 end

lib/jwt/json.rb

@@ -1,18 +1,127 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'strscan'
 
 module JWT
+  # JSON parsing utilities with duplicate key detection support
   # @api private
   class JSON
     class << self
+      # Generates a JSON string from the given data
+      # @param data [Object] the data to serialize
+      # @return [String] the JSON string
       def generate(data)
         ::JSON.generate(data)
       end
 
-      def parse(data)
+      # Parses a JSON string with optional duplicate key detection
+      #
+      # @param data [String] the JSON string to parse
+      # @param allow_duplicate_keys [Boolean] whether to allow duplicate keys (default: true)
+      # @return [Hash] the parsed JSON object
+      # @raise [JWT::DuplicateKeyError] if allow_duplicate_keys is false and duplicate keys are found
+      #
+      # @example Default behavior (allows duplicates, uses last value)
+      #   JWT::JSON.parse('{"a":1,"a":2}') # => {"a" => 2}
+      #
+      # @example Strict mode (rejects duplicates)
+      #   JWT::JSON.parse('{"a":1,"a":2}', allow_duplicate_keys: false)
+      #   # => raises JWT::DuplicateKeyError
+      def parse(data, allow_duplicate_keys: true)
+        DuplicateKeyChecker.check!(data) unless allow_duplicate_keys
         ::JSON.parse(data)
       end
     end
+
+    # @api private
+    # Checks for duplicate keys in a JSON string using a StringScanner-based tokenizer
+    class DuplicateKeyChecker
+      def self.check!(json_str)
+        new(json_str).check!
+      end
+
+      def initialize(json_str)
+        @scanner = StringScanner.new(json_str)
+        @seen_keys_stack = [[]]
+        @depth = 0
+        @in_array_stack = [false]
+      end
+
+      def check!
+        scan_tokens until @scanner.eos?
+      end
+
+      private
+
+      def scan_tokens # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        skip_whitespace
+        return if @scanner.eos?
+
+        if @scanner.scan('{')
+          handle_object_start
+        elsif @scanner.scan('}')
+          handle_container_end
+        elsif @scanner.scan('[')
+          handle_array_start
+        elsif @scanner.scan(']')
+          @depth -= 1
+        elsif @scanner.scan(',') || @scanner.scan(':')
+          # skip comma and colon
+        elsif @scanner.scan('"')
+          handle_string
+        elsif @scanner.scan(/-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/)
+          # skip number
+        elsif @scanner.scan(/true|false|null/)
+          # skip literal
+        else
+          @scanner.getch
+        end
+      end
+
+      def skip_whitespace
+        @scanner.scan(/\s+/)
+      end
+
+      def handle_object_start
+        @depth += 1
+        @seen_keys_stack[@depth] = []
+        @in_array_stack[@depth] = false
+      end
+
+      def handle_array_start
+        @depth += 1
+        @seen_keys_stack[@depth] = []
+        @in_array_stack[@depth] = true
+      end
+
+      def handle_container_end
+        @depth -= 1
+      end
+
+      def handle_string
+        str = scan_string_content
+        check_if_key(str)
+      end
+
+      def scan_string_content
+        str = +''
+        str << (@scanner.getch || '') until @scanner.scan('"')
+        str
+      end
+
+      def check_if_key(str)
+        return if @in_array_stack[@depth]
+
+        pos = @scanner.pos
+        skip_whitespace
+        if @scanner.peek(1) == ':'
+          raise JWT::DuplicateKeyError, "Duplicate key detected: #{str}" if @seen_keys_stack[@depth].include?(str)
+
+          @seen_keys_stack[@depth] << str
+        end
+        @scanner.pos = pos
+      end
+    end
   end
 end

spec/jwt/claims/duplicate_key_spec.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+RSpec.describe 'Duplicate Claim Name Detection' do
+  let(:secret) { 'test_secret' }
+  let(:algorithm) { 'HS256' }
+
+  def sign_jwt(signing_input, secret)
+    signature = OpenSSL::HMAC.digest('SHA256', secret, signing_input)
+    JWT::Base64.url_encode(signature)
+  end
+
+  def build_jwt_with_duplicate_payload(duplicate_payload_json)
+    header = JWT::Base64.url_encode('{"alg":"HS256"}')
+    payload = JWT::Base64.url_encode(duplicate_payload_json)
+    signing_input = "#{header}.#{payload}"
+    signature = sign_jwt(signing_input, secret)
+    "#{signing_input}.#{signature}"
+  end
+
+  def build_jwt_with_duplicate_header(duplicate_header_json, payload_json = '{"sub":"user"}')
+    header = JWT::Base64.url_encode(duplicate_header_json)
+    payload = JWT::Base64.url_encode(payload_json)
+    signing_input = "#{header}.#{payload}"
+    signature = sign_jwt(signing_input, secret)
+    "#{signing_input}.#{signature}"
+  end
+
+  describe 'payload with duplicate keys' do
+    let(:duplicate_payload_jwt) { build_jwt_with_duplicate_payload('{"sub":"user","sub":"admin"}') }
+
+    context 'with default configuration' do
+      it 'uses the last value (backward compatible)' do
+        payload, = JWT.decode(duplicate_payload_jwt, secret, true, algorithm: algorithm)
+        expect(payload['sub']).to eq('admin')
+      end
+    end
+
+    context 'with allow_duplicate_keys: true' do
+      it 'uses the last value' do
+        payload, = JWT.decode(duplicate_payload_jwt, secret, true, algorithm: algorithm, allow_duplicate_keys: true)
+        expect(payload['sub']).to eq('admin')
+      end
+    end
+
+    context 'with allow_duplicate_keys: false' do
+      it 'raises DuplicateKeyError' do
+        expect do
+          JWT.decode(duplicate_payload_jwt, secret, true, algorithm: algorithm, allow_duplicate_keys: false)
+        end.to raise_error(JWT::DuplicateKeyError, /Duplicate key detected: sub/)
+      end
+    end
+  end
+
+  describe 'header with duplicate keys' do
+    let(:duplicate_header_jwt) { build_jwt_with_duplicate_header('{"alg":"HS256","alg":"none"}') }
+
+    context 'with default configuration' do
+      it 'uses the last value (backward compatible)' do
+        _, header = JWT.decode(duplicate_header_jwt, nil, false)
+        expect(header['alg']).to eq('none')
+      end
+    end
+
+    context 'with allow_duplicate_keys: false' do
+      it 'raises DuplicateKeyError for header' do
+        expect do
+          JWT.decode(duplicate_header_jwt, nil, false, allow_duplicate_keys: false)
+        end.to raise_error(JWT::DuplicateKeyError, /Duplicate key detected: alg/)
+      end
+    end
+  end
+
+  describe 'global configuration' do
+    around do |example|
+      original = JWT.configuration.decode.allow_duplicate_keys
+      example.run
+      JWT.configuration.decode.allow_duplicate_keys = original
+    end
+
+    let(:duplicate_payload_jwt) { build_jwt_with_duplicate_payload('{"sub":"user","sub":"admin"}') }
+
+    it 'respects global configuration when set to false' do
+      JWT.configuration.decode.allow_duplicate_keys = false
+
+      expect do
+        JWT.decode(duplicate_payload_jwt, secret, true, algorithm: algorithm)
+      end.to raise_error(JWT::DuplicateKeyError)
+    end
+
+    it 'allows per-decode override of global configuration' do
+      JWT.configuration.decode.allow_duplicate_keys = false
+
+      payload, = JWT.decode(
+        duplicate_payload_jwt,
+        secret,
+        true,
+        algorithm: algorithm,
+        allow_duplicate_keys: true
+      )
+      expect(payload['sub']).to eq('admin')
+    end
+
+    it 'defaults to allowing duplicate keys' do
+      expect(JWT.configuration.decode.allow_duplicate_keys).to be(true)
+    end
+  end
+
+  describe 'multiple duplicate keys' do
+    let(:multiple_duplicates_jwt) { build_jwt_with_duplicate_payload('{"a":1,"b":2,"a":3,"b":4}') }
+
+    context 'with allow_duplicate_keys: false' do
+      it 'raises DuplicateKeyError for the first duplicate found' do
+        expect do
+          JWT.decode(multiple_duplicates_jwt, secret, true, algorithm: algorithm, allow_duplicate_keys: false)
+        end.to raise_error(JWT::DuplicateKeyError, /Duplicate key detected: a/)
+      end
+    end
+  end
+end