legion-crypt 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8dc8ac30453ea23fbdd8f8b2a11b0168fcd1d5d2d1bb8cfd289f96bd6fdc2620
-  data.tar.gz: fa52ef3ddeb5da0f0ea151c178612832f46da404fd1c5c145dcc86f53570250c
+  metadata.gz: a7018b9c084879712ba6a2fdf0b64f19b1c78de8cb8b9377063f824a0f43314c
+  data.tar.gz: 0d449cbe402ffbe5a45256801ea442ac03d7663f234f4678f52147e55214c0c0
 SHA512:
-  metadata.gz: a538b27d572615fc9a14dcb026b8641a4459438c24e689584166a82c97fd234ea19d5d55600b60c0e7c5eb688cb8c28838b1c1b30bb275691a124544ce93ea50
-  data.tar.gz: 1cfd861ed4f57d538dc25640e69178cfa638c1e529dab1b24402b202173488f42447fb3553e08516593b64ff7f39be6bfdf1f944683d7a2a5c22f3d59f7692a4
+  metadata.gz: 64e62d71d928dbd378aa7ce371af98b79c0a70cd6724461db87c7753f073014e8d0973975b947c31cdcda34f138f473afcf11d5026ec5332e7b5d619b91e72f8
+  data.tar.gz: 42b44f3d2b203db36197dc399732790fe3e6cc6f9f00b9e3c3660fc1283cf6bbd519fbaab718ddaa44a404f5332e3d8f0eb24120d17ac41f2071df637fc61634

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,31 @@
 # Legion::Crypt
 
+## [Unreleased]
+
+## [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,47 @@ 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"
+  },
+  "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
 }
 ```
 
-Authors
-----------
+### 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.
+
+## 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

data/lib/legion/crypt/jwt.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'jwt'
+require 'securerandom'
+
+module Legion
+  module Crypt
+    module JWT
+      class Error < StandardError; end
+      class ExpiredTokenError < Error; end
+      class InvalidTokenError < Error; end
+      class DecodeError < Error; end
+
+      SUPPORTED_ALGORITHMS = %w[HS256 RS256].freeze
+
+      def self.issue(payload, signing_key:, algorithm: 'HS256', ttl: 3600, issuer: 'legion')
+        validate_algorithm!(algorithm)
+
+        now = Time.now.to_i
+        claims = {
+          iss: issuer,
+          iat: now,
+          exp: now + ttl,
+          jti: SecureRandom.uuid
+        }.merge(payload)
+
+        ::JWT.encode(claims, signing_key, algorithm)
+      end
+
+      def self.verify(token, verification_key:, **opts)
+        algorithm = opts.fetch(:algorithm, 'HS256')
+        verify_expiration = opts.fetch(:verify_expiration, true)
+        verify_issuer = opts.fetch(:verify_issuer, true)
+        issuer = opts.fetch(:issuer, 'legion')
+
+        validate_algorithm!(algorithm)
+
+        decode_opts = {
+          algorithm:         algorithm,
+          verify_expiration: verify_expiration,
+          verify_iss:        verify_issuer
+        }
+        decode_opts[:iss] = issuer if verify_issuer
+
+        payload, _header = ::JWT.decode(token, verification_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::DecodeError => e
+        raise DecodeError, "failed to decode token: #{e.message}"
+      end
+
+      def self.decode(token)
+        payload, _header = ::JWT.decode(token, nil, false)
+        symbolize_keys(payload)
+      rescue ::JWT::DecodeError => e
+        raise DecodeError, "failed to decode token: #{e.message}"
+      end
+
+      def self.validate_algorithm!(algorithm)
+        return if SUPPORTED_ALGORITHMS.include?(algorithm)
+
+        raise ArgumentError, "unsupported algorithm: #{algorithm}. Supported: #{SUPPORTED_ALGORITHMS.join(', ')}"
+      end
+
+      def self.symbolize_keys(hash)
+        hash.transform_keys(&:to_sym)
+      end
+
+      private_class_method :validate_algorithm!, :symbolize_keys
+    end
+  end
+end