legion-crypt 1.3.0 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7018b9c084879712ba6a2fdf0b64f19b1c78de8cb8b9377063f824a0f43314c
-  data.tar.gz: 0d449cbe402ffbe5a45256801ea442ac03d7663f234f4678f52147e55214c0c0
+  metadata.gz: 13bcc3fe80b97d57f54b1e5449f0319865ee5b05c5402ce9a5f3b3a30f89ad88
+  data.tar.gz: 1ba4f54c017ec83868defedd3fe4d7a3659b5d84f3afa030722dce9d9bb1211c
 SHA512:
-  metadata.gz: 64e62d71d928dbd378aa7ce371af98b79c0a70cd6724461db87c7753f073014e8d0973975b947c31cdcda34f138f473afcf11d5026ec5332e7b5d619b91e72f8
-  data.tar.gz: 42b44f3d2b203db36197dc399732790fe3e6cc6f9f00b9e3c3660fc1283cf6bbd519fbaab718ddaa44a404f5332e3d8f0eb24120d17ac41f2071df637fc61634
+  metadata.gz: 6f120ed5f85a929fe22e750e482253550000888afbc6633c989df680c7acdc93673303014d911871642a48f66ab05e6899ab773319b1a195c64736eb052fc204
+  data.tar.gz: 8a4d154360dca522f05982d986eb28d25212038c7ca37e94253a4a1a89b03a9a51a15e46e2dedc77f382b5b7f84fcca3c8924332c9dae230858a3c154e3e8b15

data/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## [1.4.1] - 2026-03-16
+
+### Added
+- `Legion::Crypt::MockVault` in-memory Vault mock for local development mode
+
+## [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/CLAUDE.md

@@ -34,8 +34,14 @@ Legion::Crypt (singleton module)
 ├── JWT                # JSON Web Token operations
 │   ├── .issue         # Create signed JWT (HS256 or RS256)
 │   ├── .verify        # Verify and decode JWT
+│   ├── .verify_with_jwks  # Verify RS256 token via external JWKS endpoint (Entra ID, etc.)
 │   └── .decode        # Decode without verification (inspection)
 │
+├── JwksClient         # External JWKS endpoint integration (thread-safe)
+│   ├── .fetch_keys    # Fetch and parse JWKS from a URL
+│   ├── .find_key      # Lookup key by kid (cache-first, re-fetch on miss)
+│   └── .clear_cache   # Clear the key cache
+│
 ├── ClusterSecret      # Cluster-wide shared secret management
 │   └── .cs            # Generate/distribute cluster secret
 │
@@ -46,6 +52,7 @@ Legion::Crypt (singleton module)
 │
 ├── VaultRenewer       # Background Vault token renewal thread
 ├── LeaseManager       # Dynamic Vault lease lifecycle: fetch, cache, renew, rotate, push-back
+├── MockVault          # In-memory Vault mock for local development mode
 ├── Settings           # Default crypt config
 └── Version
 ```
@@ -57,6 +64,7 @@ Legion::Crypt (singleton module)
 - **Vault Conditional**: Vault module is only included if the `vault` gem is available
 - **Token Lifecycle**: VaultRenewer runs background thread for automatic token renewal
 - **JWT Dual Algorithm**: HS256 (symmetric, cluster secret) for intra-cluster tokens; RS256 (asymmetric, RSA keypair) for tokens verifiable without sharing the signing key
+- **JWKS External Validation**: `JwksClient` fetches public keys from external identity provider JWKS endpoints (Entra ID, Bot Framework). Keys cached for 1 hour (CACHE_TTL=3600s), thread-safe via Mutex, automatic re-fetch on cache miss handles key rotation
 
 ## Default Settings
 
@@ -94,7 +102,8 @@ Dev dependencies: `legion-logging`, `legion-settings`
 |------|---------|
 | `lib/legion/crypt.rb` | Module entry, start/shutdown lifecycle |
 | `lib/legion/crypt/cipher.rb` | AES-256-CBC encrypt/decrypt, RSA key generation |
-| `lib/legion/crypt/jwt.rb` | JWT issue/verify/decode operations |
+| `lib/legion/crypt/jwt.rb` | JWT issue/verify/decode/verify_with_jwks operations |
+| `lib/legion/crypt/jwks_client.rb` | JWKS endpoint fetch, parse, cache (thread-safe, 1hr TTL) |
 | `lib/legion/crypt/vault.rb` | Vault read/write/connect/renew operations |
 | `lib/legion/crypt/cluster_secret.rb` | Cluster-wide shared secret management |
 | `lib/legion/crypt/vault_jwt_auth.rb` | Vault JWT auth backend: `.login`, `.login!`, `.worker_login`; raises `AuthError` on failure |
@@ -110,6 +119,7 @@ First service-level module initialized during `Legion::Service` startup (before
 2. Message encryption for `legion-transport` (optional `transport.messages.encrypt`)
 3. Cluster secret for inter-node encrypted communication
 4. JWT tokens for node authentication and task authorization
+5. External token verification for identity providers (Entra ID OIDC via JWKS)
 
 ### Vault JWT Auth Usage
 
@@ -144,6 +154,31 @@ decoded = Legion::Crypt::JWT.decode(token) # no verification, inspection only
 - `HS256` (default): Uses cluster secret. All cluster nodes can issue and verify.
 - `RS256`: Uses RSA keypair. Only the issuing node can sign; anyone with the public key can verify.
 
+### External Token Verification (JWKS)
+
+Verify tokens from external identity providers using their public JWKS endpoints:
+
+```ruby
+# Convenience method
+claims = Legion::Crypt.verify_external_token(
+  token,
+  jwks_url: 'https://login.microsoftonline.com/TENANT/discovery/v2.0/keys',
+  issuers:  ['https://login.microsoftonline.com/TENANT/v2.0'],
+  audience: 'app-client-id'
+)
+
+# Direct module usage
+claims = Legion::Crypt::JWT.verify_with_jwks(token, jwks_url: jwks_url)
+```
+
+**Flow:** decode JWT header (unverified) to extract `kid` -> `JwksClient.find_key` fetches the matching public key from cache or JWKS endpoint -> verify JWT signature with the public key.
+
+**Options:** `issuers:` (array, multi-issuer support), `audience:` (string), `verify_expiration:` (bool, default true).
+
+**Error hierarchy:** `ExpiredTokenError`, `InvalidTokenError` (bad signature, wrong issuer, wrong audience), `DecodeError` (malformed token) — all inherit from `Legion::Crypt::JWT::Error`.
+
+**Used by:** `lex-identity` Entra runner for Digital Worker OIDC token validation.
+
 ---
 
 **Maintained By**: Matthew Iverson (@Esity)

data/README.md

@@ -41,6 +41,25 @@ claims = Legion::Crypt.verify_token(token, algorithm: 'RS256')
 decoded = Legion::Crypt::JWT.decode(token)
 ```
 
+### External Token Verification (JWKS)
+
+Verify tokens from external identity providers (Entra ID, Bot Framework) using their public JWKS endpoints:
+
+```ruby
+# Verify an Entra ID OIDC token
+claims = Legion::Crypt.verify_external_token(
+  token,
+  jwks_url: 'https://login.microsoftonline.com/TENANT/discovery/v2.0/keys',
+  issuers:  ['https://login.microsoftonline.com/TENANT/v2.0'],
+  audience: 'app-client-id'
+)
+
+# Or use the JWT module directly
+claims = Legion::Crypt::JWT.verify_with_jwks(token, jwks_url: jwks_url)
+```
+
+Public keys are cached for 1 hour and automatically re-fetched on cache miss (handles key rotation).
+
 ## Configuration
 
 ```json
@@ -56,7 +75,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 +105,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/mock_vault.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Legion
+  module Crypt
+    module MockVault
+      @store = {}
+      @mutex = Mutex.new
+
+      class << self
+        def read(path)
+          @mutex.synchronize { @store[path]&.dup }
+        end
+
+        def write(path, data)
+          @mutex.synchronize { @store[path] = data.dup }
+          true
+        end
+
+        def delete(path)
+          @mutex.synchronize { @store.delete(path) }
+          true
+        end
+
+        def list(prefix)
+          @mutex.synchronize do
+            @store.keys.select { |k| k.start_with?(prefix) }
+          end
+        end
+
+        def reset!
+          @mutex.synchronize { @store.clear }
+        end
+
+        def connected?
+          true
+        end
+      end
+    end
+  end
+end

data/lib/legion/crypt/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Crypt
-    VERSION = '1.3.0'
+    VERSION = '1.4.1'
   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.1
 platform: ruby
 authors:
 - Esity
@@ -59,8 +59,10 @@ 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/mock_vault.rb
 - lib/legion/crypt/settings.rb
 - lib/legion/crypt/vault.rb
 - lib/legion/crypt/vault_jwt_auth.rb