standard_id 0.2.7 → 0.2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dbef18f1449e29f9a2634d4ac069294555d068b0c645e187935bd88133649d49
-  data.tar.gz: fceb6cf31ca8a240ea7969255b3d6954547bfc5f69f620ba4cae1d301b6c6981
+  metadata.gz: fa6edd707d2fbe2489dfdebfade37312811fd607aaae48bcc62d973db1e66086
+  data.tar.gz: 433da88bb0da62c2af3fe3fe988dcbef5262a3ad3f079877fe611d8b0cb670bc
 SHA512:
-  metadata.gz: 9f2ee859ac9c6a41f6fc5839cb597e2940d95ae0919e0a86233202f34ecc0f99d94ca4e574b6c9b790ee31e4c42003d358dc0fc5a997a3874f2de0b1b72f57fe
-  data.tar.gz: fab39f1f052246162a6fece0aa612bc8871fccb54e095d58f7d52d0b62b8307c927444043fcddf7b3b54a07da0ffcbceacb0be419379097261eeae8c59c45b24
+  metadata.gz: 4e7ddc6f377761c1d3f87a32bd2eaeb692b01b3c30140d90403258885606e6220f0047ea29c2e92ddf0568a1e6a5cf580f9a1f2d60c33aba1e6fd2c003575aeb
+  data.tar.gz: 4c89ea4e20d364ebbd57c00eebd19bd06da11231ccc6eaf8b8d596709c3fbe09e0f14e016f1f51c615112f062bf4d0790c2c7c3c281b7511b74a4b16fd720eb7

data/lib/generators/standard_id/install/templates/standard_id.rb

@@ -80,6 +80,23 @@ StandardId.configure do |c|
   # Option 3: File path
   # c.oauth.signing_algorithm = :es256
   # c.oauth.signing_key = Rails.root.join("config/signing_key.pem")
+  #
+  # Key Rotation:
+  # To rotate signing keys with zero downtime:
+  #   1. Generate a new key
+  #   2. Move the current signing_key into previous_signing_keys
+  #   3. Set signing_key to the new key
+  #   4. After the grace period (longest token lifetime), remove the old key
+  #
+  # Same algorithm rotation (plain PEM strings):
+  # c.oauth.previous_signing_keys = [
+  #   Rails.application.credentials.dig(:standard_id, :previous_signing_key)
+  # ]
+  #
+  # Cross-algorithm rotation (e.g., RS256 -> ES256):
+  # c.oauth.previous_signing_keys = [
+  #   { key: Rails.application.credentials.dig(:standard_id, :old_rsa_key), algorithm: :rs256 }
+  # ]
 
   # Events
   # Enable or disable logging emitted via the internal event system

data/lib/standard_id/config/schema.rb

@@ -56,6 +56,11 @@ StandardConfig.schema.draw do
     # If nil, uses HS256 with Rails.application.secret_key_base
     field :signing_key, type: :any, default: nil
 
+    # Previous signing keys for key rotation (array of PEM strings or Pathnames)
+    # During rotation, move the old signing_key here so tokens signed with it
+    # can still be verified. Remove after the grace period.
+    field :previous_signing_keys, type: :array, default: -> { [] }
+
     # Signing algorithm (see JwtService::SUPPORTED_ALGORITHMS for full list)
     # Symmetric (HMAC): :hs256, :hs384, :hs512
     # Asymmetric (RSA): :rs256, :rs384, :rs512

data/lib/standard_id/jwt_service.rb

@@ -77,9 +77,26 @@ module StandardId
       @key_id ||= Digest::SHA256.hexdigest(signing_key.public_to_pem)[0..7]
     end
 
+    def self.previous_keys
+      return [] unless asymmetric?
+
+      @previous_keys_cache ||= Array(StandardId.config.oauth.previous_signing_keys).filter_map do |entry|
+        parse_previous_key_entry(entry)
+      rescue StandardError
+        nil
+      end
+    end
+
+    def self.all_verification_keys
+      return [] unless asymmetric?
+
+      [{ kid: key_id, key: verification_key }] + previous_keys
+    end
+
     def self.reset_cached_key!
       @key_id = nil
       @signing_key_cache = nil
+      @previous_keys_cache = nil
       @jwks = nil
     end
 
@@ -95,13 +112,33 @@ module StandardId
     end
 
     def self.decode(token)
-      options = { algorithm: algorithm }
+      options = { algorithms: [algorithm] }
 
       if StandardId.config.issuer.present?
         options[:iss] = StandardId.config.issuer
         options[:verify_iss] = true
       end
 
+      if asymmetric? && previous_keys.any?
+        # Include algorithms from previous keys for cross-algorithm rotation
+        prev_algorithms = previous_keys.filter_map { |k| k[:algorithm] }
+        options[:algorithms] = ([algorithm] + prev_algorithms).uniq
+
+        # Build a JWKS set with all active keys for kid-based matching
+        jwk_set = JWT::JWK::Set.new
+        all_verification_keys.each do |entry|
+          jwk_set << JWT::JWK.new(entry[:key], kid: entry[:kid])
+        end
+        options[:jwks] = jwk_set
+
+        begin
+          decoded = JWT.decode(token, nil, true, options)
+          return decoded.first.with_indifferent_access
+        rescue JWT::DecodeError, JWT::ExpiredSignature, JWT::InvalidIatError, JWT::InvalidIssuerError
+          return nil
+        end
+      end
+
       decoded = JWT.decode(token, verification_key, true, options)
       decoded.first.with_indifferent_access
     rescue JWT::DecodeError, JWT::ExpiredSignature, JWT::InvalidIatError, JWT::InvalidIssuerError
@@ -132,16 +169,38 @@ module StandardId
       return nil unless asymmetric?
 
       @jwks ||= begin
-        jwk = JWT::JWK.new(verification_key, kid: key_id)
-        { keys: [jwk.export] }
+        exported_keys = all_verification_keys.map do |entry|
+          JWT::JWK.new(entry[:key], kid: entry[:kid]).export
+        end
+        { keys: exported_keys }
       end
     end
 
     private
 
-    def self.parse_private_key(key_source)
+    # Parses a previous_signing_keys entry into { kid:, key:, algorithm: }
+    # Accepts either:
+    #   - A PEM string or Pathname (uses current algorithm's key class)
+    #   - A Hash with :key (PEM/Pathname) and :algorithm (e.g. :rs256, :es256)
+    def self.parse_previous_key_entry(entry)
+      if entry.is_a?(Hash)
+        entry = entry.symbolize_keys
+        alg = entry[:algorithm].to_s.upcase
+        alg_config = SUPPORTED_ALGORITHMS[alg] || raise(ArgumentError, "Unsupported algorithm: #{alg}")
+        key = parse_private_key(entry[:key], key_class: alg_config[:key_class])
+      else
+        alg = algorithm
+        key = parse_private_key(entry)
+      end
+
+      vkey = key.is_a?(OpenSSL::PKey::EC) ? key : key.public_key
+      kid = Digest::SHA256.hexdigest(key.public_to_pem)[0..7]
+      { kid: kid, key: vkey, algorithm: alg }
+    end
+
+    def self.parse_private_key(key_source, key_class: nil)
       pem = key_source.is_a?(Pathname) ? File.read(key_source) : key_source
-      key_class = algorithm_config[:key_class]
+      key_class ||= algorithm_config[:key_class]
 
       key_class.new(pem)
     end

data/lib/standard_id/version.rb

@@ -1,3 +1,3 @@
 module StandardId
-  VERSION = "0.2.7"
+  VERSION = "0.2.8"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_id
 version: !ruby/object:Gem::Version
-  version: 0.2.7
+  version: 0.2.8
 platform: ruby
 authors:
 - Jaryl Sim