legion-crypt 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7018b9c084879712ba6a2fdf0b64f19b1c78de8cb8b9377063f824a0f43314c
-  data.tar.gz: 0d449cbe402ffbe5a45256801ea442ac03d7663f234f4678f52147e55214c0c0
+  metadata.gz: 3bf2e0f0673b2c963e56d71c586d299a39c3711b0d3f49fe851375d78cebe07e
+  data.tar.gz: 194d4c8b64922f5634dcf75607af87a0d83ba10efcb1c83421456bf7a3fddfc6
 SHA512:
-  metadata.gz: 64e62d71d928dbd378aa7ce371af98b79c0a70cd6724461db87c7753f073014e8d0973975b947c31cdcda34f138f473afcf11d5026ec5332e7b5d619b91e72f8
-  data.tar.gz: 42b44f3d2b203db36197dc399732790fe3e6cc6f9f00b9e3c3660fc1283cf6bbd519fbaab718ddaa44a404f5332e3d8f0eb24120d17ac41f2071df637fc61634
+  metadata.gz: 33e4ea2d0ca6413f24099181f5ccf3b61ced2c33f079dd11029ded41095ceaedaf419b315e097ede586560e5478cec5be946dbe627d0ab68763c5354baa3617f
+  data.tar.gz: 8985763ca6ee45362527ec0368175125ed95d6001dc4d0f43759017fe1c7de33f7c194be7501e8c9c19a12fe72ac3fa1ce2aca5e6c5fde8d39c2bc76999ec925

data/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-03-16
+
+### Added
+- `JwksClient` module: fetch, parse, and cache public keys from JWKS endpoints (TTL 3600s, thread-safe)
+- `JWT.verify_with_jwks` for RS256 token verification against external identity providers (Entra ID, Bot Framework)
+- Multi-issuer support via `issuers:` array parameter
+- Audience validation via `audience:` parameter
+- `Crypt.verify_external_token` convenience method
+
 ## [1.3.0] - 2026-03-16
 
 ### Added

data/README.md

@@ -56,7 +56,8 @@ decoded = Legion::Crypt::JWT.decode(token)
     "renewer": true,
     "push_cluster_secret": true,
     "read_cluster_secret": true,
-    "kv_path": "legion"
+    "kv_path": "legion",
+    "leases": {}
   },
   "jwt": {
     "enabled": true,
@@ -85,6 +86,47 @@ decoded = Legion::Crypt::JWT.decode(token)
 
 When `vault.token` is set (or via `VAULT_TOKEN_ID` env var), Crypt connects to Vault on `start`. The background `VaultRenewer` thread keeps the token alive. Vault is an optional runtime dependency — the Vault module is only included if the `vault` gem is available.
 
+### Dynamic Vault Leases
+
+The `LeaseManager` handles dynamic secrets from any Vault secrets engine (database, RabbitMQ, AWS, PKI, etc.). Define named leases in crypt settings — each lease maps a stable name to a Vault path:
+
+```json
+{
+  "crypt": {
+    "vault": {
+      "leases": {
+        "rabbitmq": { "path": "rabbitmq/creds/legion-role" },
+        "bedrock":  { "path": "aws/creds/bedrock-role" },
+        "postgres": { "path": "database/creds/apollo-rw" }
+      }
+    }
+  }
+}
+```
+
+Other settings files reference lease data using `lease://name#key`:
+
+```json
+{
+  "transport": {
+    "connection": {
+      "username": "lease://rabbitmq#username",
+      "password": "lease://rabbitmq#password"
+    }
+  }
+}
+```
+
+Both `username` and `password` come from a single Vault read — one lease, one credential pair. The `LeaseManager`:
+
+- Fetches all leases at boot (during `Crypt.start`, before `resolve_secrets!`)
+- Caches response data and lease metadata
+- Renews leases in the background at 50% TTL
+- Detects credential rotation and pushes new values into `Legion::Settings` in-place
+- Revokes all leases on `Crypt.shutdown`
+
+Lease names are stable across environments. The actual Vault paths are deployment-specific config.
+
 ## Requirements
 
 - Ruby >= 3.4

data/lib/legion/crypt/jwks_client.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+require 'openssl'
+require 'jwt'
+
+module Legion
+  module Crypt
+    module JwksClient
+      CACHE_TTL = 3600
+
+      @cache = {}
+      @mutex = Mutex.new
+
+      class << self
+        def fetch_keys(jwks_url)
+          @mutex.synchronize do
+            response = http_get(jwks_url)
+            jwks_data = parse_response(response)
+            keys = parse_jwks(jwks_data)
+
+            @cache[jwks_url] = { keys: keys, fetched_at: Time.now }
+            keys
+          end
+        end
+
+        def find_key(jwks_url, kid)
+          cached = @mutex.synchronize { @cache[jwks_url] }
+
+          if cached && !expired?(cached[:fetched_at])
+            key = cached[:keys][kid]
+            return key if key
+          end
+
+          # Re-fetch once on cache miss or expiry
+          keys = fetch_keys(jwks_url)
+          key = keys[kid]
+          return key if key
+
+          raise Legion::Crypt::JWT::InvalidTokenError, "signing key not found: #{kid}"
+        end
+
+        def clear_cache
+          @mutex.synchronize { @cache = {} }
+        end
+
+        private
+
+        def expired?(fetched_at)
+          Time.now - fetched_at > CACHE_TTL
+        end
+
+        def http_get(url)
+          uri = URI.parse(url)
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = uri.scheme == 'https'
+          http.open_timeout = 10
+          http.read_timeout = 10
+
+          request = Net::HTTP::Get.new(uri.request_uri)
+          response = http.request(request)
+
+          raise Legion::Crypt::JWT::Error, "failed to fetch JWKS: HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+          response.body
+        rescue StandardError => e
+          raise Legion::Crypt::JWT::Error, "failed to fetch JWKS: #{e.message}" unless e.is_a?(Legion::Crypt::JWT::Error)
+
+          raise
+        end
+
+        def parse_response(body)
+          parsed = ::JSON.parse(body)
+          raise Legion::Crypt::JWT::Error, 'invalid JWKS response: missing keys' unless parsed.is_a?(Hash) && parsed['keys'].is_a?(Array)
+
+          parsed
+        rescue ::JSON::ParserError => e
+          raise Legion::Crypt::JWT::Error, "invalid JWKS response: #{e.message}"
+        end
+
+        def parse_jwks(jwks_data)
+          keys = {}
+
+          jwks_data['keys'].each do |jwk_hash|
+            kid = jwk_hash['kid']
+            next unless kid
+
+            jwk = ::JWT::JWK.new(jwk_hash)
+            keys[kid] = jwk.public_key
+          rescue StandardError
+            # Skip malformed keys, continue with valid ones
+            next
+          end
+
+          keys
+        end
+      end
+    end
+  end
+end

data/lib/legion/crypt/jwt.rb

@@ -2,6 +2,7 @@
 
 require 'jwt'
 require 'securerandom'
+require 'legion/crypt/jwks_client'
 
 module Legion
   module Crypt
@@ -59,6 +60,60 @@ module Legion
         raise DecodeError, "failed to decode token: #{e.message}"
       end
 
+      def self.verify_with_jwks(token, jwks_url:, **opts)
+        header = decode_header(token)
+        kid = header['kid']
+        algorithm = header['alg'] || 'RS256'
+
+        raise InvalidTokenError, 'token header missing kid' unless kid
+
+        validate_algorithm!(algorithm)
+
+        public_key = Legion::Crypt::JwksClient.find_key(jwks_url, kid)
+
+        verify_expiration = opts.fetch(:verify_expiration, true)
+        issuers = opts[:issuers]
+        audience = opts[:audience]
+
+        decode_opts = {
+          algorithm:         algorithm,
+          verify_expiration: verify_expiration
+        }
+
+        if issuers
+          decode_opts[:verify_iss] = true
+          decode_opts[:iss] = issuers
+        end
+
+        if audience
+          decode_opts[:verify_aud] = true
+          decode_opts[:aud] = audience
+        end
+
+        payload, _header = ::JWT.decode(token, public_key, true, decode_opts)
+        symbolize_keys(payload)
+      rescue ::JWT::ExpiredSignature
+        raise ExpiredTokenError, 'token has expired'
+      rescue ::JWT::VerificationError, ::JWT::IncorrectAlgorithm
+        raise InvalidTokenError, 'token signature verification failed'
+      rescue ::JWT::InvalidIssuerError
+        raise InvalidTokenError, 'token issuer not allowed'
+      rescue ::JWT::InvalidAudError
+        raise InvalidTokenError, 'token audience mismatch'
+      rescue ::JWT::DecodeError => e
+        raise DecodeError, "failed to decode token: #{e.message}"
+      end
+
+      def self.decode_header(token)
+        parts = token.to_s.split('.')
+        raise DecodeError, 'invalid token format' unless parts.size == 3
+
+        header_json = Base64.urlsafe_decode64(parts[0])
+        ::JSON.parse(header_json)
+      rescue ::JSON::ParserError, ArgumentError => e
+        raise DecodeError, "failed to decode token header: #{e.message}"
+      end
+
       def self.validate_algorithm!(algorithm)
         return if SUPPORTED_ALGORITHMS.include?(algorithm)
 
@@ -69,7 +124,7 @@ module Legion
         hash.transform_keys(&:to_sym)
       end
 
-      private_class_method :validate_algorithm!, :symbolize_keys
+      private_class_method :validate_algorithm!, :symbolize_keys, :decode_header
     end
   end
 end

data/lib/legion/crypt/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Crypt
-    VERSION = '1.3.0'
+    VERSION = '1.4.0'
   end
 end

data/lib/legion/crypt.rb

@@ -64,6 +64,10 @@ module Legion
                                          issuer: jwt[:issuer])
       end
 
+      def verify_external_token(token, jwks_url:, **)
+        Legion::Crypt::JWT.verify_with_jwks(token, jwks_url: jwks_url, **)
+      end
+
       def shutdown
         Legion::Crypt::LeaseManager.instance.shutdown
         shutdown_renewer

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-crypt
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Esity
@@ -59,6 +59,7 @@ files:
 - lib/legion/crypt.rb
 - lib/legion/crypt/cipher.rb
 - lib/legion/crypt/cluster_secret.rb
+- lib/legion/crypt/jwks_client.rb
 - lib/legion/crypt/jwt.rb
 - lib/legion/crypt/lease_manager.rb
 - lib/legion/crypt/settings.rb