legion-crypt 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8dc8ac30453ea23fbdd8f8b2a11b0168fcd1d5d2d1bb8cfd289f96bd6fdc2620
-  data.tar.gz: fa52ef3ddeb5da0f0ea151c178612832f46da404fd1c5c145dcc86f53570250c
+  metadata.gz: 3bf2e0f0673b2c963e56d71c586d299a39c3711b0d3f49fe851375d78cebe07e
+  data.tar.gz: 194d4c8b64922f5634dcf75607af87a0d83ba10efcb1c83421456bf7a3fddfc6
 SHA512:
-  metadata.gz: a538b27d572615fc9a14dcb026b8641a4459438c24e689584166a82c97fd234ea19d5d55600b60c0e7c5eb688cb8c28838b1c1b30bb275691a124544ce93ea50
-  data.tar.gz: 1cfd861ed4f57d538dc25640e69178cfa638c1e529dab1b24402b202173488f42447fb3553e08516593b64ff7f39be6bfdf1f944683d7a2a5c22f3d59f7692a4
+  metadata.gz: 33e4ea2d0ca6413f24099181f5ccf3b61ced2c33f079dd11029ded41095ceaedaf419b315e097ede586560e5478cec5be946dbe627d0ab68763c5354baa3617f
+  data.tar.gz: 8985763ca6ee45362527ec0368175125ed95d6001dc4d0f43759017fe1c7de33f7c194be7501e8c9c19a12fe72ac3fa1ce2aca5e6c5fde8d39c2bc76999ec925

data/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    uses: LegionIO/.github/.github/workflows/ci.yml@main
+
+  release:
+    needs: ci
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    uses: LegionIO/.github/.github/workflows/release.yml@main
+    secrets:
+      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}

data/.rubocop.yml

@@ -1,26 +1,53 @@
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+  SuggestExtensions: false
+
 Layout/LineLength:
-  Max: 140
+  Max: 160
+
+Layout/SpaceAroundEqualsInParameterDefault:
+  EnforcedStyle: space
+
+Layout/HashAlignment:
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+
 Metrics/MethodLength:
   Max: 50
+
 Metrics/ClassLength:
   Max: 1500
+
+Metrics/ModuleLength:
+  Max: 1500
+
 Metrics/BlockLength:
-  Max: 50
-Metrics/CyclomaticComplexity:
-  Max: 14
+  Max: 40
+  Exclude:
+    - 'spec/**/*'
+
 Metrics/AbcSize:
-  Max: 17
+  Max: 60
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+
 Metrics/PerceivedComplexity:
-  Max: 16
-Naming/MethodParameterName:
-  Enabled: false
+  Max: 17
+
 Style/Documentation:
   Enabled: false
-AllCops:
-  TargetRubyVersion: 2.6
-  NewCops: enable
-  SuggestExtensions: false
+
+Style/SymbolArray:
+  Enabled: true
+
 Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Naming/FileName:
+  Enabled: false
+
+Naming/PredicateMethod:
   Enabled: false
-Gemspec/RequiredRubyVersion:
-  Enabled: false

data/CHANGELOG.md

@@ -1,4 +1,40 @@
 # Legion::Crypt
 
+## [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
+- `LeaseManager` singleton for dynamic Vault secret lease management
+- Named lease definitions in `crypt.vault.leases` settings
+- Boot-time lease fetch with data caching
+- Background renewal thread with rotation detection
+- Settings push-back on credential rotation via reverse index
+- `lease://name#key` URI references resolved by Settings resolver
+
+## v1.2.1
+
+### Fixed
+- `validate_hex` and `set_cluster_secret` now handle leading zeros correctly by padding the
+  base-32 round-trip result back to the original string length. Previously, secrets whose
+  hex representation started with one or more zero bytes would fail validation and cause
+  `find_cluster_secret` to return nil non-deterministically.
+
+### Added
+- Comprehensive spec coverage for `Legion::Crypt::VaultJwtAuth` (`.login`, `.login!`,
+  `.worker_login`, `AuthError`, constants).
+- `after` hook in `cluster_secret_spec` to restore `Legion::Settings[:crypt][:cluster_secret]`
+  between examples, eliminating ordering-dependent state pollution.
+- TODO comments in `vault_spec` for tests that require live Vault connectivity.
+
 ## v1.2.0
-Moving from BitBucket to GitHub inside the Optum org. All git history is reset from this point on
+Moving from BitBucket to GitHub. All git history is reset from this point on

data/CLAUDE.md

@@ -0,0 +1,149 @@
+# legion-crypt: Encryption and Vault Integration for LegionIO
+
+**Repository Level 3 Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/CLAUDE.md`
+
+## Purpose
+
+Handles encryption, decryption, secrets management, JWT token management, and HashiCorp Vault connectivity for the LegionIO framework. Provides AES-256-CBC message encryption, RSA key pair generation, cluster secret management, JWT issue/verify operations, and Vault token lifecycle management.
+
+**GitHub**: https://github.com/LegionIO/legion-crypt
+**License**: Apache-2.0
+
+## Architecture
+
+```
+Legion::Crypt (singleton module)
+├── .start             # Initialize: generate keys, connect to Vault
+├── .encrypt(string)   # AES-256-CBC encryption
+├── .decrypt(message)  # AES-256-CBC decryption
+├── .shutdown          # Stop Vault renewer, close sessions
+│
+├── Cipher             # OpenSSL cipher operations (AES-256-CBC)
+│   ├── .encrypt       # Encrypt with cluster secret
+│   ├── .decrypt       # Decrypt with cluster secret
+│   ├── .private_key   # RSA private key (generated or loaded)
+│   └── .public_key    # RSA public key
+│
+├── Vault              # HashiCorp Vault integration
+│   ├── .connect_vault # Establish Vault session
+│   ├── .read(path)    # Read secret from Vault
+│   ├── .write(path)   # Write secret to Vault
+│   └── .renew_token   # Token renewal
+│
+├── JWT                # JSON Web Token operations
+│   ├── .issue         # Create signed JWT (HS256 or RS256)
+│   ├── .verify        # Verify and decode JWT
+│   └── .decode        # Decode without verification (inspection)
+│
+├── ClusterSecret      # Cluster-wide shared secret management
+│   └── .cs            # Generate/distribute cluster secret
+│
+├── VaultJwtAuth       # Vault JWT auth backend integration
+│   ├── .login         # Authenticate to Vault using a JWT token, returns Vault token hash
+│   ├── .login!        # Authenticate and set ::Vault.token for subsequent operations
+│   └── .worker_login  # Issue a Legion JWT and authenticate to Vault in one step
+│
+├── VaultRenewer       # Background Vault token renewal thread
+├── LeaseManager       # Dynamic Vault lease lifecycle: fetch, cache, renew, rotate, push-back
+├── Settings           # Default crypt config
+└── Version
+```
+
+### Key Design Patterns
+
+- **Dynamic Keys**: By default, generates new RSA key pair per process start (no persistent keys)
+- **Cluster Secret**: Shared AES key distributed across Legion nodes for inter-node encrypted communication
+- **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
+
+## Default Settings
+
+```json
+{
+  "vault": { "..." : "see vault settings" },
+  "jwt": {
+    "enabled": true,
+    "default_algorithm": "HS256",
+    "default_ttl": 3600,
+    "issuer": "legion",
+    "verify_expiration": true,
+    "verify_issuer": true
+  },
+  "cs_encrypt_ready": false,
+  "dynamic_keys": true,
+  "cluster_secret": null,
+  "save_private_key": true,
+  "read_private_key": true
+}
+```
+
+## Dependencies
+
+| Gem | Purpose |
+|-----|---------|
+| `jwt` (>= 2.7) | JSON Web Token encoding/decoding |
+| `vault` (>= 0.17) | HashiCorp Vault Ruby client |
+
+Dev dependencies: `legion-logging`, `legion-settings`
+
+## File Map
+
+| Path | Purpose |
+|------|---------|
+| `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/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/version.rb` | VERSION constant |
+
+## Role in LegionIO
+
+First service-level module initialized during `Legion::Service` startup (before transport). Provides:
+1. Vault token for `legion-transport` to fetch RabbitMQ credentials
+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
+
+### Vault JWT Auth Usage
+
+```ruby
+# Authenticate to Vault using a JWT (Vault must have JWT auth method enabled)
+result = Legion::Crypt::VaultJwtAuth.login(jwt: token, role: 'legion-worker')
+# => { token: '...', lease_duration: 3600, renewable: true, policies: [...], metadata: {} }
+
+# Authenticate and set Vault client token in one step
+Legion::Crypt::VaultJwtAuth.login!(jwt: token)
+
+# Issue a Legion JWT and use it to authenticate to Vault (convenience for workers)
+result = Legion::Crypt::VaultJwtAuth.worker_login(worker_id: 'abc', owner_msid: 'user@example.com')
+```
+
+Vault prerequisites: `vault auth enable jwt` + configure `auth/jwt/config` with JWKS URL or bound issuer.
+
+### JWT Usage
+
+```ruby
+# Convenience methods (auto-selects keys from settings)
+token = Legion::Crypt.issue_token({ node_id: 'abc' }, ttl: 3600)
+claims = Legion::Crypt.verify_token(token)
+
+# Direct module usage (explicit keys)
+token = Legion::Crypt::JWT.issue(payload, signing_key: key, algorithm: 'RS256')
+claims = Legion::Crypt::JWT.verify(token, verification_key: pub_key, algorithm: 'RS256')
+decoded = Legion::Crypt::JWT.decode(token) # no verification, inspection only
+```
+
+**Algorithms:**
+- `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.
+
+---
+
+**Maintained By**: Matthew Iverson (@Esity)

data/Gemfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 gemspec
@@ -8,3 +10,5 @@ group :test do
   gem 'rubocop'
   gem 'simplecov'
 end
+gem 'legion-logging'
+gem 'legion-settings'

data/LICENSE

@@ -1,6 +1,7 @@
+
                                  Apache License
                            Version 2.0, January 2004
-                        http://www.apache.org/licenses/
+                        https://www.apache.org/licenses/
 
    TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
@@ -175,27 +176,16 @@
 
    END OF TERMS AND CONDITIONS
 
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright 2021 Optum
+   Copyright 2021 Esity
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at
 
-       http://www.apache.org/licenses/LICENSE-2.0
+       https://www.apache.org/licenses/LICENSE-2.0
 
    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
-   limitations under the License.
+   limitations under the License.

data/README.md

@@ -1,26 +1,21 @@
-Legion::Crypt
-=====
+# legion-crypt
 
-Legion::Crypt is the class responsible for encryption, managing secrets and connecting with Vault
+Encryption, secrets management, JWT token management, and HashiCorp Vault integration for the [LegionIO](https://github.com/LegionIO/LegionIO) framework. Provides AES-256-CBC message encryption, RSA key pair generation, cluster secret management, JWT issue/verify operations, and Vault token lifecycle management.
 
-Supported Ruby versions and implementations
-------------------------------------------------
-
-Legion::Crypt should work identically on:
-
-* JRuby 9.2+
-* Ruby 2.4+
-
-
-Installation and Usage
-------------------------
-
-You can verify your installation using this piece of code:
+## Installation
 
 ```bash
 gem install legion-crypt
 ```
 
+Or add to your Gemfile:
+
+```ruby
+gem 'legion-crypt'
+```
+
+## Usage
+
 ```ruby
 require 'legion/crypt'
 
@@ -29,8 +24,24 @@ Legion::Crypt.encrypt('this is my string')
 Legion::Crypt.decrypt(message)
 ```
 
-Settings
-----------
+### JWT Tokens
+
+```ruby
+# Issue a token (defaults to HS256 using cluster secret)
+token = Legion::Crypt.issue_token({ node_id: 'abc' }, ttl: 3600)
+
+# Verify and decode a token
+claims = Legion::Crypt.verify_token(token)
+
+# Use RS256 (RSA keypair) instead
+token = Legion::Crypt.issue_token({ node_id: 'abc' }, algorithm: 'RS256')
+claims = Legion::Crypt.verify_token(token, algorithm: 'RS256')
+
+# Inspect a token without verification
+decoded = Legion::Crypt::JWT.decode(token)
+```
+
+## Configuration
 
 ```json
 {
@@ -40,17 +51,89 @@ Settings
     "address": "localhost",
     "port": 8200,
     "token": null,
-    "connected": false
+    "connected": false,
+    "renewer_time": 5,
+    "renewer": true,
+    "push_cluster_secret": true,
+    "read_cluster_secret": true,
+    "kv_path": "legion",
+    "leases": {}
+  },
+  "jwt": {
+    "enabled": true,
+    "default_algorithm": "HS256",
+    "default_ttl": 3600,
+    "issuer": "legion",
+    "verify_expiration": true,
+    "verify_issuer": true
   },
   "cs_encrypt_ready": false,
   "dynamic_keys": true,
   "cluster_secret": null,
-  "save_private_key": false,
-  "read_private_key": false
+  "save_private_key": true,
+  "read_private_key": true
+}
+```
+
+### JWT Algorithms
+
+| Algorithm | Key | Use Case |
+|-----------|-----|----------|
+| `HS256` (default) | Cluster secret (symmetric) | Intra-cluster tokens — all nodes can issue and verify |
+| `RS256` | RSA key pair (asymmetric) | Tokens verifiable by external services without sharing the signing key |
+
+### Vault Integration
+
+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"
+    }
+  }
 }
 ```
 
-Authors
-----------
+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
+- `jwt` gem (>= 2.7)
+- `vault` gem (>= 0.17, optional)
+- HashiCorp Vault (optional, for secrets management)
+
+## License
 
-* [Matthew Iverson](https://github.com/Esity) - current maintainer
+Apache-2.0

data/legion-crypt.gemspec

@@ -6,27 +6,25 @@ Gem::Specification.new do |spec|
   spec.name = 'legion-crypt'
   spec.version       = Legion::Crypt::VERSION
   spec.authors       = ['Esity']
-  spec.email         = %w[matthewdiverson@gmail.com ruby@optum.com]
+  spec.email         = ['matthewdiverson@gmail.com']
   spec.summary       = 'Handles requests for encrypt, decrypting, connecting to Vault, among other things'
   spec.description   = 'A gem used by the LegionIO framework for encryption'
-  spec.homepage      = 'https://github.com/Optum/legion-crypt'
+  spec.homepage      = 'https://github.com/LegionIO/legion-crypt'
   spec.license       = 'Apache-2.0'
   spec.require_paths = ['lib']
-  spec.required_ruby_version = '>= 2.4'
+  spec.required_ruby_version = '>= 3.4'
   spec.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
-  spec.test_files        = spec.files.select { |p| p =~ %r{^test/.*_test.rb} }
-  spec.extra_rdoc_files  = %w[README.md LICENSE CHANGELOG.md]
+  spec.extra_rdoc_files = %w[README.md LICENSE CHANGELOG.md]
   spec.metadata = {
-    'bug_tracker_uri' => 'https://github.com/Optum/legion-crypt/issues',
-    'changelog_uri' => 'https://github.com/Optum/legion-crypt/src/main/CHANGELOG.md',
-    'documentation_uri' => 'https://github.com/Optum/legion-crypt',
-    'homepage_uri' => 'https://github.com/Optum/LegionIO',
-    'source_code_uri' => 'https://github.com/Optum/legion-crypt',
-    'wiki_uri' => 'https://github.com/Optum/legion-crypt/wiki'
+    'bug_tracker_uri'       => 'https://github.com/LegionIO/legion-crypt/issues',
+    'changelog_uri'         => 'https://github.com/LegionIO/legion-crypt/blob/main/CHANGELOG.md',
+    'documentation_uri'     => 'https://github.com/LegionIO/legion-crypt',
+    'homepage_uri'          => 'https://github.com/LegionIO/LegionIO',
+    'source_code_uri'       => 'https://github.com/LegionIO/legion-crypt',
+    'wiki_uri'              => 'https://github.com/LegionIO/legion-crypt/wiki',
+    'rubygems_mfa_required' => 'true'
   }
 
-  spec.add_dependency 'vault', '>= 0.15.0'
-
-  spec.add_development_dependency 'legion-logging'
-  spec.add_development_dependency 'legion-settings'
+  spec.add_dependency 'jwt', '>= 2.7'
+  spec.add_dependency 'vault', '>= 0.17'
 end

data/lib/legion/crypt/cipher.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'securerandom'
 require 'legion/crypt/cluster_secret'
 
@@ -14,7 +16,7 @@ module Legion
         { enciphered_message: Base64.encode64(cipher.update(message) + cipher.final), iv: Base64.encode64(iv) }
       end
 
-      def decrypt(message, iv)
+      def decrypt(message, init_vector)
         until cs.is_a?(String) || Legion::Settings[:client][:shutting_down]
           Legion::Logging.debug('sleeping Legion::Crypt.decrypt due to CS not being set')
           sleep(0.5)
@@ -23,7 +25,7 @@ module Legion
         decipher = OpenSSL::Cipher.new('aes-256-cbc')
         decipher.decrypt
         decipher.key = cs
-        decipher.iv = Base64.decode64(iv)
+        decipher.iv = Base64.decode64(init_vector)
         message = Base64.decode64(message)
         decipher.update(message) + decipher.final
       end

data/lib/legion/crypt/cluster_secret.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'securerandom'
 
 module Legion
@@ -39,7 +41,7 @@ module Legion
       end
       alias cluster_secret from_settings
 
-      def from_transport # rubocop:disable Metrics/AbcSize
+      def from_transport
         return nil unless Legion::Settings[:transport][:connected]
 
         require 'legion/transport/messages/request_cluster_secret'
@@ -55,10 +57,11 @@ module Legion
 
         unless from_settings.nil?
           Legion::Logging.info "Received cluster secret in #{((Time.new - start) * 1000.0).round}ms"
-          from_settings
+          return from_settings
         end
 
         Legion::Logging.error 'Cluster secret is still unknown!'
+        nil
       rescue StandardError => e
         Legion::Logging.error e.message
         Legion::Logging.error e.backtrace[0..10]
@@ -79,7 +82,7 @@ module Legion
       end
 
       def set_cluster_secret(value, push_to_vault = true) # rubocop:disable Style/OptionalBooleanParameter
-        raise TypeError unless value.to_i(32).to_s(32) == value.downcase
+        raise TypeError unless value.to_i(32).to_s(32).rjust(value.length, '0') == value.downcase
 
         Legion::Settings[:crypt][:cs_encrypt_ready] = true
         push_cs_to_vault if push_to_vault && settings_push_vault
@@ -114,7 +117,10 @@ module Legion
       end
 
       def validate_hex(value, length = secret_length)
-        value.to_i(length).to_s(length) == value.downcase
+        return false unless value.is_a?(String)
+        return false if value.empty?
+
+        value.to_i(length).to_s(length).rjust(value.length, '0') == value.downcase
       end
     end
   end