legion-crypt 1.4.0 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3bf2e0f0673b2c963e56d71c586d299a39c3711b0d3f49fe851375d78cebe07e
-  data.tar.gz: 194d4c8b64922f5634dcf75607af87a0d83ba10efcb1c83421456bf7a3fddfc6
+  metadata.gz: 13bcc3fe80b97d57f54b1e5449f0319865ee5b05c5402ce9a5f3b3a30f89ad88
+  data.tar.gz: 1ba4f54c017ec83868defedd3fe4d7a3659b5d84f3afa030722dce9d9bb1211c
 SHA512:
-  metadata.gz: 33e4ea2d0ca6413f24099181f5ccf3b61ced2c33f079dd11029ded41095ceaedaf419b315e097ede586560e5478cec5be946dbe627d0ab68763c5354baa3617f
-  data.tar.gz: 8985763ca6ee45362527ec0368175125ed95d6001dc4d0f43759017fe1c7de33f7c194be7501e8c9c19a12fe72ac3fa1ce2aca5e6c5fde8d39c2bc76999ec925
+  metadata.gz: 6f120ed5f85a929fe22e750e482253550000888afbc6633c989df680c7acdc93673303014d911871642a48f66ab05e6899ab773319b1a195c64736eb052fc204
+  data.tar.gz: 8a4d154360dca522f05982d986eb28d25212038c7ca37e94253a4a1a89b03a9a51a15e46e2dedc77f382b5b7f84fcca3c8924332c9dae230858a3c154e3e8b15

data/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## [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

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

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.4.0'
+    VERSION = '1.4.1'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-crypt
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.4.1
 platform: ruby
 authors:
 - Esity
@@ -62,6 +62,7 @@ files:
 - 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