legion-crypt 1.4.0 → 1.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3bf2e0f0673b2c963e56d71c586d299a39c3711b0d3f49fe851375d78cebe07e
-  data.tar.gz: 194d4c8b64922f5634dcf75607af87a0d83ba10efcb1c83421456bf7a3fddfc6
+  metadata.gz: 171a3a22eeb730be2a47dccb7f96ec1b4ffcf4df03792eae594f63b61106224a
+  data.tar.gz: 597ca3ea73e5864a572621312cf7ff0efea424c4e3e05c22e16f0044deb97753
 SHA512:
-  metadata.gz: 33e4ea2d0ca6413f24099181f5ccf3b61ced2c33f079dd11029ded41095ceaedaf419b315e097ede586560e5478cec5be946dbe627d0ab68763c5354baa3617f
-  data.tar.gz: 8985763ca6ee45362527ec0368175125ed95d6001dc4d0f43759017fe1c7de33f7c194be7501e8c9c19a12fe72ac3fa1ce2aca5e6c5fde8d39c2bc76999ec925
+  metadata.gz: fb76b8b671a10380aaccb82eb62f611f9998112bd95ec8a5b184679b1694204d3b7adb14b3c7f141ae072254671728bf2b8b1701c94291f0b285ccb335d0e15e
+  data.tar.gz: 8d0d58cb2c9d4fc543fc7d3be4628142405c388e1436211df59d1d26614c18d49f6e158ab25e440b643401c8c527de1160470a0623536a4f79040fb2f475a6fc

data/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## [1.4.2] - 2026-03-16
+
+### Added
+- `Legion::Crypt::Ed25519`: Ed25519 key generation, signing, verification, Vault key storage
+- `Legion::Crypt::PartitionKeys`: HKDF-based per-tenant key derivation with AES-256-GCM encrypt/decrypt
+- `Legion::Crypt::Erasure`: cryptographic erasure via Vault master key deletion with event emission
+- `Legion::Crypt::Attestation`: signed identity claims with Ed25519 signatures and freshness checking
+- Dependency: `ed25519` gem ~> 1.3
+
+## [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
 │
@@ -45,7 +51,12 @@ Legion::Crypt (singleton module)
 │   └── .worker_login  # Issue a Legion JWT and authenticate to Vault in one step
 │
 ├── VaultRenewer       # Background Vault token renewal thread
+├── Ed25519            # Ed25519 key generation, signing, verification, Vault storage
+├── PartitionKeys      # HKDF per-tenant key derivation, AES-256-GCM encrypt/decrypt
+├── Erasure            # Cryptographic erasure via Vault master key deletion
+├── Attestation        # Signed identity claims with Ed25519, freshness checking
 ├── 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 +68,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
 
@@ -83,6 +95,7 @@ Legion::Crypt (singleton module)
 
 | Gem | Purpose |
 |-----|---------|
+| `ed25519` (~> 1.3) | Ed25519 key operations (pure Ruby) |
 | `jwt` (>= 2.7) | JSON Web Token encoding/decoding |
 | `vault` (>= 0.17) | HashiCorp Vault Ruby client |
 
@@ -94,13 +107,18 @@ 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 |
 | `lib/legion/crypt/vault_renewer.rb` | Background Vault token renewal |
 | `lib/legion/crypt/lease_manager.rb` | Dynamic Vault lease lifecycle management |
 | `lib/legion/crypt/settings.rb` | Default configuration |
+| `lib/legion/crypt/ed25519.rb` | Ed25519 key generation, signing, verification, Vault storage |
+| `lib/legion/crypt/partition_keys.rb` | HKDF per-tenant key derivation with AES-256-GCM |
+| `lib/legion/crypt/erasure.rb` | Cryptographic erasure via Vault master key deletion |
+| `lib/legion/crypt/attestation.rb` | Signed identity claims with Ed25519 signatures |
 | `lib/legion/crypt/version.rb` | VERSION constant |
 
 ## Role in LegionIO
@@ -110,6 +128,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 +163,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/legion-crypt.gemspec

@@ -25,6 +25,7 @@ Gem::Specification.new do |spec|
     'rubygems_mfa_required' => 'true'
   }
 
+  spec.add_dependency 'ed25519', '~> 1.3'
   spec.add_dependency 'jwt', '>= 2.7'
   spec.add_dependency 'vault', '>= 0.17'
 end

data/lib/legion/crypt/attestation.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Crypt
+    module Attestation
+      class << self
+        def create(agent_id:, capabilities:, state:, private_key:)
+          claim = {
+            agent_id:     agent_id,
+            capabilities: Array(capabilities),
+            state:        state.to_s,
+            timestamp:    Time.now.utc.iso8601,
+            nonce:        SecureRandom.hex(16)
+          }
+
+          payload = Legion::JSON.dump(claim)
+          signature = Legion::Crypt::Ed25519.sign(payload, private_key)
+
+          { claim: claim, signature: signature.unpack1('H*'), payload: payload }
+        end
+
+        def verify(claim_hash:, signature_hex:, public_key:)
+          payload = Legion::JSON.dump(claim_hash)
+          signature = [signature_hex].pack('H*')
+          Legion::Crypt::Ed25519.verify(payload, signature, public_key)
+        end
+
+        def fresh?(claim_hash, max_age_seconds: 300)
+          timestamp = Time.parse(claim_hash[:timestamp])
+          Time.now.utc - timestamp < max_age_seconds
+        rescue StandardError
+          false
+        end
+      end
+    end
+  end
+end

data/lib/legion/crypt/ed25519.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'ed25519'
+
+module Legion
+  module Crypt
+    module Ed25519
+      class << self
+        def generate_keypair
+          signing_key = ::Ed25519::SigningKey.generate
+          {
+            private_key:    signing_key.to_bytes,
+            public_key:     signing_key.verify_key.to_bytes,
+            public_key_hex: signing_key.verify_key.to_bytes.unpack1('H*')
+          }
+        end
+
+        def sign(message, private_key_bytes)
+          signing_key = ::Ed25519::SigningKey.new(private_key_bytes)
+          signing_key.sign(message)
+        end
+
+        def verify(message, signature, public_key_bytes)
+          verify_key = ::Ed25519::VerifyKey.new(public_key_bytes)
+          verify_key.verify(signature, message)
+          true
+        rescue ::Ed25519::VerifyError
+          false
+        end
+
+        def store_keypair(agent_id:, keypair: nil)
+          keypair ||= generate_keypair
+          vault_path = "#{key_prefix}/#{agent_id}"
+          if defined?(Legion::Crypt::Vault)
+            Legion::Crypt::Vault.write(vault_path, {
+                                         private_key: keypair[:private_key].unpack1('H*'),
+                                         public_key:  keypair[:public_key_hex]
+                                       })
+          end
+          keypair
+        end
+
+        def load_private_key(agent_id:)
+          vault_path = "#{key_prefix}/#{agent_id}"
+          data = Legion::Crypt::Vault.read(vault_path)
+          [data[:private_key]].pack('H*') if data&.dig(:private_key)
+        rescue StandardError
+          nil
+        end
+
+        private
+
+        def key_prefix
+          begin
+            Legion::Settings[:crypt][:ed25519][:vault_key_prefix]
+          rescue StandardError
+            nil
+          end || 'secret/data/legion/keys'
+        end
+      end
+    end
+  end
+end

data/lib/legion/crypt/erasure.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Legion
+  module Crypt
+    module Erasure
+      class << self
+        def erase_tenant(tenant_id:)
+          key_path = "#{tenant_prefix}/#{tenant_id}/master_key"
+
+          delete_vault_key(key_path) if defined?(Legion::Crypt::Vault)
+          Legion::Events.emit('crypt.tenant_erased', { tenant_id: tenant_id, erased_at: Time.now.utc }) if defined?(Legion::Events)
+          Legion::Logging.warn "[crypt] Tenant #{tenant_id} cryptographically erased" if defined?(Legion::Logging)
+
+          { erased: true, tenant_id: tenant_id, path: key_path }
+        rescue StandardError => e
+          { erased: false, tenant_id: tenant_id, error: e.message }
+        end
+
+        def verify_erasure(tenant_id:)
+          key_path = "#{tenant_prefix}/#{tenant_id}/master_key"
+          data = Legion::Crypt::Vault.read(key_path)
+          { erased: data.nil?, tenant_id: tenant_id }
+        rescue StandardError
+          { erased: true, tenant_id: tenant_id }
+        end
+
+        private
+
+        def delete_vault_key(path)
+          ::Vault.logical.delete(path)
+        end
+
+        def tenant_prefix
+          begin
+            Legion::Settings[:crypt][:partition_keys][:vault_tenant_prefix]
+          rescue StandardError
+            nil
+          end || 'secret/data/legion/tenants'
+        end
+      end
+    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/partition_keys.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module Legion
+  module Crypt
+    module PartitionKeys
+      class << self
+        def derive_key(master_key:, tenant_id:, context: nil)
+          context ||= begin
+            Legion::Settings[:crypt][:partition_keys][:derivation_context]
+          rescue StandardError
+            nil
+          end || 'legion-partition'
+          salt = OpenSSL::Digest::SHA256.digest(tenant_id.to_s)
+          OpenSSL::KDF.hkdf(master_key, salt: salt, info: context, length: 32, hash: 'SHA256')
+        end
+
+        def encrypt_for_tenant(plaintext:, tenant_id:, master_key:)
+          key = derive_key(master_key: master_key, tenant_id: tenant_id)
+          cipher = OpenSSL::Cipher.new('aes-256-gcm')
+          cipher.encrypt
+          cipher.key = key
+          iv = cipher.random_iv
+          ciphertext = cipher.update(plaintext) + cipher.final
+          auth_tag = cipher.auth_tag
+
+          { ciphertext: ciphertext, iv: iv, auth_tag: auth_tag }
+        end
+
+        def decrypt_for_tenant(ciphertext:, init_vector:, auth_tag:, tenant_id:, master_key:)
+          key = derive_key(master_key: master_key, tenant_id: tenant_id)
+          decipher = OpenSSL::Cipher.new('aes-256-gcm')
+          decipher.decrypt
+          decipher.key = key
+          decipher.iv = init_vector
+          decipher.auth_tag = auth_tag
+          decipher.update(ciphertext) + decipher.final
+        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.2'
   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.2
 platform: ruby
 authors:
 - Esity
@@ -9,6 +9,20 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: ed25519
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
 - !ruby/object:Gem::Dependency
   name: jwt
   requirement: !ruby/object:Gem::Requirement
@@ -57,11 +71,16 @@ files:
 - README.md
 - legion-crypt.gemspec
 - lib/legion/crypt.rb
+- lib/legion/crypt/attestation.rb
 - lib/legion/crypt/cipher.rb
 - lib/legion/crypt/cluster_secret.rb
+- lib/legion/crypt/ed25519.rb
+- lib/legion/crypt/erasure.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/partition_keys.rb
 - lib/legion/crypt/settings.rb
 - lib/legion/crypt/vault.rb
 - lib/legion/crypt/vault_jwt_auth.rb