Implements Nested JWT functionality as defined in RFC 7519 Section 5.2, 7.1, 7.2, and Appendix A.2.

Implements Nested JWT functionality as defined in RFC 7519 Section 5.2, 7.1, 7.2, and Appendix A.2.

A Nested JWT is a JWT used as the payload of another JWT, allowing multiple layers of signing with different keys/algorithms.

Author: ydah

CHANGELOG.md

@@ -6,7 +6,7 @@
 
 **Features:**
 
-- Your contribution here
+- Implements Nested JWT functionality as defined in RFC 7519 Section 5.2, 7.1, 7.2, and Appendix A.2. [#712](https://github.com/jwt/ruby-jwt/pull/712) ([@ydah](https://github.com/ydah))
 
 **Fixes and enhancements:**
 

README.md

@@ -325,6 +325,66 @@ encoded_token.verify_signature!(algorithm: 'HS256', key: "secret")
 encoded_token.payload # => {"pay"=>"load"}
 ```
 
+## Nested JWT
+
+A Nested JWT is a JWT that is used as the payload of another JWT, as defined in RFC 7519 Section 5.2. This allows for multiple layers of signing.
+
+### Creating a Nested JWT
+
+```ruby
+# Create the inner JWT
+inner_payload = { user_id: 123, role: 'admin' }
+inner_key = 'inner_secret'
+inner_jwt = JWT.encode(inner_payload, inner_key, 'HS256')
+
+# Wrap it in an outer JWT with a different key/algorithm
+outer_key = OpenSSL::PKey::RSA.generate(2048)
+nested_jwt = JWT::NestedToken.sign(
+  inner_jwt,
+  algorithm: 'RS256',
+  key: outer_key
+)
+```
+
+### Decoding a Nested JWT
+
+```ruby
+# Decode and verify all nesting levels
+tokens = JWT::NestedToken.decode(
+  nested_jwt,
+  keys: [
+    { algorithm: 'RS256', key: outer_key.public_key },
+    { algorithm: 'HS256', key: inner_key }
+  ]
+)
+
+inner_payload = tokens.last.payload
+# => { 'user_id' => 123, 'role' => 'admin' }
+```
+
+### Using JWT::Token.wrap
+
+You can also use `JWT::Token.wrap` to create nested tokens:
+
+```ruby
+inner = JWT::Token.new(payload: { sub: 'user' })
+inner.sign!(algorithm: 'HS256', key: 'inner_secret')
+
+outer = JWT::Token.wrap(inner)
+outer.sign!(algorithm: 'RS256', key: rsa_private_key)
+
+nested_jwt = outer.jwt
+```
+
+### Checking for Nested JWTs
+
+```ruby
+token = JWT::EncodedToken.new(nested_jwt)
+token.nested?     # => true
+token.inner_token # => JWT::EncodedToken of the inner JWT
+token.unwrap_all  # => [outer_token, inner_token]
+```
+
 ## Claims
 
 JSON Web Token defines some reserved claim names and defines how they should be

lib/jwt.rb

@@ -11,6 +11,7 @@
 require 'jwt/claims'
 require 'jwt/encoded_token'
 require 'jwt/token'
+require 'jwt/nested_token'
 
 # JSON Web Token implementation
 #

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
@@ -192,6 +192,58 @@ def valid_claims?(*options)
 
     alias to_s jwt
 
+    # Checks if this token is a Nested JWT.
+    # A token is considered nested if it has a `cty` header with value "JWT" (case-insensitive).
+    #
+    # @return [Boolean] true if this is a Nested JWT, false otherwise
+    #
+    # @example
+    #   token = JWT::EncodedToken.new(nested_jwt_string)
+    #   token.nested? # => true
+    #
+    # @see https://datatracker.ietf.org/doc/html/rfc7519#section-5.2 RFC 7519 Section 5.2
+    def nested?
+      cty = header['cty']
+      cty&.upcase == 'JWT'
+    end
+
+    # Returns the inner token if this is a Nested JWT.
+    # The inner token is created from the payload of this token.
+    #
+    # @return [JWT::EncodedToken, nil] the inner token if nested, nil otherwise
+    #
+    # @example
+    #   outer_token = JWT::EncodedToken.new(nested_jwt_string)
+    #   inner_token = outer_token.inner_token
+    #   inner_token.header # => { 'alg' => 'HS256' }
+    def inner_token
+      return nil unless nested?
+
+      EncodedToken.new(unverified_payload)
+    end
+
+    # Unwraps all nesting levels and returns an array of tokens.
+    # The array is ordered from outermost to innermost token.
+    #
+    # @return [Array<JWT::EncodedToken>] array of all tokens from outer to inner
+    #
+    # @example
+    #   token = JWT::EncodedToken.new(deeply_nested_jwt)
+    #   all_tokens = token.unwrap_all
+    #   all_tokens.first # => outermost token
+    #   all_tokens.last  # => innermost token
+    def unwrap_all
+      tokens = [self]
+      current = self
+
+      while current.nested?
+        current = current.inner_token
+        tokens << current
+      end
+
+      tokens
+    end
+
     private
 
     def claims_options(options)

lib/jwt/nested_token.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module JWT
+  # Provides functionality for creating and decoding Nested JWTs
+  # as defined in RFC 7519 Section 5.2, Section 7.1 Step 5, and Appendix A.2.
+  #
+  # A Nested JWT is a JWT that is used as the payload of another JWT,
+  # allowing for multiple layers of signing or encryption.
+  #
+  # @example Creating a Nested JWT
+  #   inner_jwt = JWT.encode({ user_id: 123 }, 'inner_secret', 'HS256')
+  #   nested_jwt = JWT::NestedToken.sign(
+  #     inner_jwt,
+  #     algorithm: 'RS256',
+  #     key: rsa_private_key
+  #   )
+  #
+  # @example Decoding a Nested JWT
+  #   tokens = JWT::NestedToken.decode(
+  #     nested_jwt,
+  #     keys: [
+  #       { algorithm: 'RS256', key: rsa_public_key },
+  #       { algorithm: 'HS256', key: 'inner_secret' }
+  #     ]
+  #   )
+  #   inner_payload = tokens.last.payload
+  #
+  # @see https://datatracker.ietf.org/doc/html/rfc7519#section-5.2 RFC 7519 Section 5.2
+  class NestedToken
+    # The content type header value for nested JWTs as per RFC 7519
+    CTY_JWT = 'JWT'
+
+    class << self
+      # Wraps an inner JWT with an outer JWS, creating a Nested JWT.
+      # Automatically sets the `cty` (content type) header to "JWT" as required by RFC 7519.
+      #
+      # @param inner_jwt [String] the inner JWT string to wrap
+      # @param algorithm [String] the signing algorithm for the outer JWS (e.g., 'RS256', 'HS256')
+      # @param key [Object] the signing key for the outer JWS
+      # @param header [Hash] additional header fields to include (cty is automatically set)
+      # @return [String] the Nested JWT string
+      #
+      # @raise [JWT::EncodeError] if signing fails
+      #
+      # @example Basic usage with HS256
+      #   inner_jwt = JWT.encode({ sub: 'user' }, 'secret', 'HS256')
+      #   nested = JWT::NestedToken.sign(inner_jwt, algorithm: 'HS256', key: 'outer_secret')
+      #
+      # @example With RSA and custom headers
+      #   nested = JWT::NestedToken.sign(
+      #     inner_jwt,
+      #     algorithm: 'RS256',
+      #     key: rsa_private_key,
+      #     header: { kid: 'my-key-id' }
+      #   )
+      def sign(inner_jwt, algorithm:, key:, header: {})
+        outer_header = header.merge('cty' => CTY_JWT)
+        token = Token.new(payload: inner_jwt, header: outer_header)
+        token.sign!(algorithm: algorithm, key: key)
+        token.jwt
+      end
+
+      # Decodes and verifies a Nested JWT, unwrapping all nesting levels.
+      # Each level's signature is verified using the corresponding key configuration.
+      #
+      # @param token [String] the Nested JWT string to decode
+      # @param keys [Array<Hash>] an array of key configurations for each nesting level,
+      #   ordered from outermost to innermost. Each hash should contain:
+      #   - `:algorithm` [String] the expected algorithm
+      #   - `:key` [Object] the verification key
+      # @return [Array<JWT::EncodedToken>] array of tokens from outermost to innermost
+      #
+      # @raise [JWT::DecodeError] if decoding fails at any level
+      # @raise [JWT::VerificationError] if signature verification fails at any level
+      #
+      # @example Decoding a two-level nested JWT
+      #   tokens = JWT::NestedToken.decode(
+      #     nested_jwt,
+      #     keys: [
+      #       { algorithm: 'RS256', key: rsa_public_key },
+      #       { algorithm: 'HS256', key: 'inner_secret' }
+      #     ]
+      #   )
+      #   inner_token = tokens.last
+      #   inner_token.payload # => { 'user_id' => 123 }
+      def decode(token, keys:)
+        tokens = []
+        current_token = token
+
+        keys.each_with_index do |key_config, index|
+          encoded_token = EncodedToken.new(current_token)
+          encoded_token.verify_signature!(
+            algorithm: key_config[:algorithm],
+            key: key_config[:key]
+          )
+
+          tokens << encoded_token
+
+          if encoded_token.nested?
+            current_token = encoded_token.unverified_payload
+          elsif index < keys.length - 1
+            raise JWT::DecodeError, 'Token is not nested but more keys were provided'
+          end
+        end
+
+        tokens.each(&:verify_claims!)
+        tokens
+      end
+    end
+  end
+end

lib/jwt/token.rb

@@ -127,5 +127,31 @@ def valid_claims?(*options)
     #
     # @return [String] the JWT token as a string.
     alias to_s jwt
+
+    class << self
+      # Wraps another JWT token, creating a Nested JWT.
+      # Sets the `cty` (content type) header to "JWT" as required by RFC 7519 Section 5.2.
+      #
+      # @param inner_token [JWT::Token, String] the token to wrap. Can be a JWT::Token instance
+      #   or a JWT string.
+      # @param header [Hash] additional header fields for the outer token
+      # @return [JWT::Token] a new token with the inner token as its payload and cty header set
+      #
+      # @example Wrapping a token
+      #   inner = JWT::Token.new(payload: { sub: 'user' })
+      #   inner.sign!(algorithm: 'HS256', key: 'secret')
+      #   outer = JWT::Token.wrap(inner)
+      #   outer.sign!(algorithm: 'RS256', key: rsa_private)
+      #
+      # @example Wrapping a JWT string
+      #   jwt_string = JWT.encode({ sub: 'user' }, 'secret', 'HS256')
+      #   outer = JWT::Token.wrap(jwt_string)
+      #
+      # @see https://datatracker.ietf.org/doc/html/rfc7519#section-5.2 RFC 7519 Section 5.2
+      def wrap(inner_token, header: {})
+        jwt_string = inner_token.is_a?(Token) ? inner_token.jwt : inner_token
+        new(payload: jwt_string, header: header.merge('cty' => 'JWT'))
+      end
+    end
   end
 end