legion-crypt 1.5.12 → 1.5.37

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4af81549d8e946acfc92ec4036496fce4af3d1be6fc10cba534298434f0c94a
-  data.tar.gz: 7e70028fa24e9760ff791f49f88817b37c9ee009b21fdc7dae9382a49306e8ca
+  metadata.gz: 9037b8b6b87bdff6a7e839f7223a825984786e5be4a323c20ce2673eccf3e93a
+  data.tar.gz: 1548b784a608b1c9b71794d937bb5bd0f0bfcd74e8337b31132bc817909926d5
 SHA512:
-  metadata.gz: 96269db0a9859015418df236468d0eff5b08490e1eb7bc55c7507199dda579924273979405d9e724b3d1237b7855ecc7b949fabdbc15dc378994ad19930112c9
-  data.tar.gz: b112f3eb47b538549e842eaa8a766e15c1934650f010082ec892a4b05fa995746dcff25ffeed90a2e625e09ee4d38d21a9d399d9787c6fd6dd1598f6895fc28f
+  metadata.gz: da7ae3fb308f8ccd82687707d0e28954d208dfe4f874d37287df46c05d7e7cf3bb3e3b22e9793fd4fdcf9cf8c71bd07d0c331b6a579dc3dc39e15ec31ce24865
+  data.tar.gz: 20a76900d62030ace417f135ba1666d05cd8304bee62f4bac1fa1cb7cd4451a06e634e29220ea0c4b105e6b30e5fdb3187d8a7db5bef1c75a1e33bee258bb4fa

data/.rubocop.yml

@@ -16,6 +16,9 @@ Layout/HashAlignment:
 Metrics/MethodLength:
   Max: 50
 
+Metrics/ParameterLists:
+  CountKeywordArgs: false
+
 Metrics/ClassLength:
   Max: 1500
 

data/CHANGELOG.md

@@ -1,6 +1,151 @@
 # Legion::Crypt
 
-## [Unreleased]
+## [1.5.37] - 2026-10-30
+
+### Changed
+- Use keyword arguments and accept unused extra keywords in methods introduced by this PR; migrate internal callers while preserving pre-existing method signatures and Ruby assignment protocols (#52).
+
+## [1.5.36] - 2026-10-30
+
+### Fixed
+- Reject and remove expired credential cache entries from lease reads, settings publication and initialized counts, allowing `lease://` fallback after failed reacquisition while retaining lease ownership for cleanup (#52).
+
+## [1.5.35] - 2026-10-30
+
+### Fixed
+- Skip unchanged settings destinations during lease handoff so TTL-only renewals preserve live consumer connections; credential changes still publish and reconnect transactionally (#52).
+
+## [1.5.34] - 2026-10-30
+
+### Fixed
+- Transition pending renewal retries to fresh acquisition after lease expiry, including renewal timeouts, while preserving backoff and last-known lease ownership (#52).
+- Revalidate captured lease ownership before reacquisition or retry publication so stale maintenance cannot replace a newer handoff (#52).
+
+## [1.5.33] - 2026-10-30
+
+### Fixed
+- Resolve Vault-backed TLS material outside the client-cache lock, then revalidate settings and lifecycle generation before publishing a candidate (#52).
+- Reject unresolved explicit trust/identity material and circular Vault TLS dependencies; close superseded or shutdown-interrupted client candidates (#52).
+
+## [1.5.32] - 2026-10-30
+
+### Fixed
+- Replace token, expiry, renewability, connectivity and authentication strategy as one grant when LDAP, JWT or Kerberos login succeeds; restart maintenance with the new grant instead of the previous token's lifetime (#52).
+- Reject authentication results from stopped lifecycles and resume managed JWT token renewal for both legacy and multi-cluster configurations (#52).
+
+## [1.5.31] - 2026-10-30
+
+### Fixed
+- Publish LDAP, JWT, Kerberos and reauthentication tokens together with client-cache signatures under one lock, rejecting late results for replaced clients or changed configuration (#52).
+- Reject token publication to clients that have already shut down (#52).
+
+## [1.5.30] - 2026-10-30
+
+### Fixed
+- Preserve replaced Vault clients while lease and token owners still reference them; weakly track displaced clients and permanently close all surviving clients only after lifecycle cleanup (#52).
+
+## [1.5.29] - 2026-10-30
+
+### Fixed
+- Revalidate pending lease operations under the per-lease lock and reject superseded retry publication, preventing stale acquisition or renewal work from undoing identity credential handoffs (#52).
+
+## [1.5.28] - 2026-10-30
+
+### Fixed
+- Bootstrap a confirmed empty cluster before waiting for a peer secret, preserving the bounded discovery deadline and refusing generation when membership is unknown (#52).
+
+## [1.5.27] - 2026-10-30
+
+### Changed
+- Replace vault-ruby with the core-owned Faraday and `Legion::JSON` Vault client, supporting JSON 3 without an extension dependency (#38).
+- Migrate legacy and multi-cluster secrets, auth, leases, token renewal, PKI, and entity tracking to the same cached client contract; retain configured Kerberos namespaces and captured lease ownership (#38).
+- Support peer and mutual TLS, current credential headers, typed HTTP errors, KV v2 envelopes, finite transport timeouts, and permanent client retirement (#38).
+
+### Fixed
+- Do not report tenant erasure or emit an erasure event when Vault deletion returns a failure result (#38).
+- Trim KV mount boundaries with single-character searches rather than a quantified suffix pattern, and initialize concurrency-spec cleanup state before setup can fail (#52).
+
+## [1.5.26] - 2026-10-29
+
+### Fixed
+- Bound SPIFFE socket connection, handshake, request writes, flushes, and response reads with shared monotonic deadlines; close sockets when setup or exchange fails (#43).
+- Reassemble gRPC prefixes and message bodies across HTTP/2 DATA frames and partial socket reads, returning only the declared message bytes (#43).
+- Encode JWT-SVID audience lengths as canonical protobuf varints, including lengths of 128 bytes and larger (#43).
+
+## [1.5.25] - 2026-10-29
+
+### Fixed
+- Start an expiry-aware renewal lifecycle immediately after LDAP login, retain token lifetime metadata, and renew through the authenticated cluster without retaining passwords or invoking Kerberos (#51).
+- Preserve nonrenewable tokens until expiry, bound renewal retries and requests by remaining lifetime, and expose disconnected/login-required state after expiry or terminal renewal rejection (#51).
+- Replace prior LDAP workers safely on repeated login, reject late login results after shutdown, and prevent expired multi-cluster credentials from falling back to the global Vault client (#51).
+
+## [1.5.24] - 2026-10-29
+
+### Fixed
+- Retry initial certificate issuance and failed renewals with capped exponential backoff while retaining the last installed certificate (#49).
+- Schedule certificate rotation from expiry and the configured renewal window, interrupt pending waits on shutdown, and discard late issuance from stopped workers (#49).
+
+## [1.5.23] - 2026-10-29
+
+### Fixed
+- Retain failed lease acquisitions for capped exponential-backoff retry and schedule maintenance against lease expiry, waking promptly for newly registered short-TTL leases (#50).
+- Make credential replacement transactional: preserve prior settings and lease ownership on failed reconnect, retire old IDs only after successful handoff, and retain failed cleanup for retry or shutdown (#50).
+- Capture each lease's issuing Vault client, deduplicate revocation, prevent retired candidates from being reinstalled, and keep late renewals from recreating revoked ownership (#50).
+- Scope timeout-spec cleanup to the override/example block so failed settings snapshots preserve the original error and leave settings unchanged (#52).
+
+## [1.5.22] - 2026-10-29
+
+### Fixed
+- Rotate every unique lease-reference destination, including nested arrays, without coercing typed paths or mutating invalid destinations; report actual successful writes (#45).
+
+## [1.5.21] - 2026-10-29
+
+### Fixed
+- Invalidate cached Vault clients when connection settings change, retire clients with bounded failure-isolated cleanup, and clear the cache across shutdown/start without discarding in-place token refreshes (#47).
+
+## [1.5.20] - 2026-10-29
+
+### Fixed
+- Bound Vault maintenance and shutdown, isolate failed leases and sessions, and permit restart after cleanup failures (#44).
+- Guard late lease, token, settings, and Kerberos-principal updates with lifecycle generations and cancellation-aware publication (#44).
+
+## [1.5.19] - 2026-10-29
+
+### Fixed
+- Coalesce concurrent JWKS misses, bound unknown-key and failed-upstream refreshes with a per-URL cooldown, and preserve immediate first-miss rotation checks and cache expiry (#42).
+
+## [1.5.18] - 2026-10-29
+
+### Fixed
+- Reject malformed JWT header shapes, key identifiers, and token algorithms through JWT-domain errors before JWKS lookup, while keeping caller configuration failures distinct (#46).
+
+## [1.5.17] - 2026-10-29
+
+### Fixed
+- Resolve KV mounts from the Vault settings subtree on the composed Crypt API for both clustered and legacy clients (#48).
+
+## [1.5.16] - 2026-10-29
+
+### Fixed
+- Gate cluster-secret generation on confirmed bootstrap eligibility, refresh derived keys when settings change, and terminate failed or cancelled initialization with bounded domain errors (#39).
+
+## [1.5.15] - 2026-10-29
+
+### Fixed
+- Create saved RSA private keys with owner-only permissions and repair existing file permissions before writing, without changing save-disabled behavior (#41).
+
+## [1.5.14] - 2026-10-29
+
+### Fixed
+- Require full 16-byte GCM authentication tags for message and tenant decryption, preventing truncated-tag forgery while preserving legacy ciphertext support (#40).
+
+## [1.5.13] - 2026-05-09
+
+### Removed
+- Logging compat shims (`lib/legion/logging.rb` and `lib/legion/logging/helper.rb`) that redefined `Legion::Logging::Helper#log` with a `CompatLogger`, preventing TaggedLogger segment tags from rendering in log output for all modules loaded after crypt
+
+### Added
+- `legion-json` gemspec dependency (was used but undeclared)
 
 ## [1.5.12] - 2026-04-27
 

data/README.md

@@ -1,8 +1,6 @@
 # legion-crypt
 
-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, Vault token lifecycle management, and multi-cluster Vault connectivity.
-
-**Version**: 1.5.6
+Encryption, secrets management, JWT token management, and HashiCorp Vault integration for the [LegionIO](https://github.com/LegionIO/LegionIO) framework. Provides AES-256-GCM message encryption with legacy AES-256-CBC decryption, RSA key pair generation, cluster secret management, JWT issue/verify operations, Vault token lifecycle management, and multi-cluster Vault connectivity.
 
 ## Installation
 
@@ -22,10 +20,20 @@ gem 'legion-crypt'
 require 'legion/crypt'
 
 Legion::Crypt.start
-Legion::Crypt.encrypt('this is my string')
-Legion::Crypt.decrypt(message)
+encrypted = Legion::Crypt.encrypt('this is my string')
+Legion::Crypt.decrypt(encrypted[:enciphered_message], encrypted[:iv])
 ```
 
+Authenticated ciphertext requires a full 16-byte GCM tag. Saved RSA private keys are created with `0600` permissions; existing files are restricted before writing.
+
+### Cluster secret readiness
+
+Discovery checks settings, Vault, and then peers. Random generation requires confirmed empty-cluster membership, the lite transport adapter, or standalone operation (no transport loaded or transport explicitly disabled). Disconnected or unknown cluster membership does not authorize a competing key.
+
+`crypt.cluster_secret_timeout` bounds initialization (default: 5 seconds; finite and positive). `crypt.cluster_length` must be a positive integer (default: 32 bytes). Invalid secrets, discovery failures, and shutdown cancellation raise `Legion::Crypt::ClusterSecret::InitializationError`; encryption and decryption do not proceed with a missing key.
+
+Use `Legion::Crypt.set_cluster_secret(secret)` to validate and install a received secret. Derived keys also detect settings replacement or mutation, so reloads cannot continue using the previous secret.
+
 ### JWT Tokens
 
 ```ruby
@@ -57,10 +65,10 @@ claims = Legion::Crypt.verify_external_token(
 )
 
 # Or use the JWT module directly
-claims = Legion::Crypt::JWT.verify_with_jwks(token, jwks_url: jwks_url)
+claims = Legion::Crypt::JWT.verify_with_jwks(token, jwks_url: jwks_url, issuers: issuers, audience: audience)
 ```
 
-Public keys are cached for 1 hour and automatically re-fetched on cache miss (handles key rotation).
+Public keys are cached for 1 hour. Concurrent misses for one URL share a refresh. The first unknown key ID triggers an immediate rotation check; subsequent missing-key lookups are throttled for 30 seconds per URL. Failed upstream lookups share the same cooldown, while still-valid cached keys remain usable. Expired caches and explicit `fetch_keys` calls refresh normally.
 
 ## Configuration
 
@@ -75,6 +83,7 @@ Public keys are cached for 1 hour and automatically re-fetched on cache miss (ha
     "connected": false,
     "renewer_time": 5,
     "renewer": true,
+    "operation_timeout": 5,
     "push_cluster_secret": true,
     "read_cluster_secret": true,
     "kv_path": "legion",
@@ -105,7 +114,25 @@ Public keys are cached for 1 hour and automatically re-fetched on cache miss (ha
 
 ### 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.
+When `vault.token` is set (or via `VAULT_TOKEN_ID` env var), Crypt connects to Vault on `start`. Vault requests use the core-owned `Legion::Crypt::VaultClient`, built on Faraday and `Legion::JSON`; neither vault-ruby nor a LEX extension is required. Responses have symbol keys, including with JSON 3.
+
+`Legion::Crypt.vault_client` returns the cached default client; pass a cluster name for an explicit client. Its logical, KV, and lease endpoints use keyword arguments and ignore extra keywords while still enforcing required arguments. Existing high-level Crypt and LeaseManager call signatures are unchanged:
+
+```ruby
+client = Legion::Crypt.vault_client
+lease = client.logical.read(path: 'database/creds/application')
+lease.data # symbol-keyed credentials
+client.sys.renew(lease_id: lease.lease_id)
+client.kv(mount: 'legion').write(path: 'application', data: { enabled: true })
+```
+
+The existing `Legion::Crypt.read`, `get`, `write`, and `delete` interfaces are unchanged. Logical reads preserve lease metadata; KV reads unwrap the KV v2 data envelope. Missing reads return `nil`, while HTTP failures raise `Legion::Crypt::Vault::HTTPClientError` (4xx), `HTTPServerError` (5xx), or their `HTTPError` base class with a numeric `code`. Redirects are not followed.
+
+Standalone clients accept `address:`, `token:`, `namespace:`, `timeout:`, and `tls:`. TLS uses the existing `verify: 'peer'`, `'none'`, or `'mutual'` configuration with `ca:`, `cert:`, and `key:` material. CA, certificate, and key values can be PEM or file paths; client identities also accept OpenSSL objects. `shutdown` permanently retires a client, including retained endpoint handles.
+
+Vault-backed TLS material can resolve through another connected cluster without holding the client-cache lock. Explicit `ca`, `cert`, or `key` references that cannot resolve fail client construction rather than silently falling back to system trust or dropping the identity. Circular TLS dependencies are rejected; bootstrap the source cluster with independently available trust material.
+
+Lease acquisition, renewal, reissue, token maintenance, and session revocation use the finite-positive `crypt.vault.operation_timeout` budget (default: 5 seconds). Failures are isolated per item. Shutdown shares a 10-second deadline, invalidates worker generations before external cleanup, and resets lifecycle state even when revocation fails. Late callbacks cannot restore credentials or settings after their lifecycle stops.
 
 ### Dynamic Vault Leases
 
@@ -146,11 +173,23 @@ Both `username` and `password` come from a single Vault read — one lease, one
 - 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.
+Failed acquisition remains pending with exponential backoff from 1 second to a 60-second cap. Maintenance wakes for the next renewal or retry deadline (10 ms minimum, 5 seconds maximum), rather than waiting five seconds before servicing short-TTL leases.
+
+TTL-only renewals update lease lifetime without reconnecting consumers whose credentials and settings are unchanged. A renewal that returns rotated credentials still publishes the new values and verifies the consumer reconnect before committing.
+
+Expired leases are reacquired rather than repeatedly renewed after timeout. `fetch`, `lease_data`, settings publication and initialized counts exclude expired cached credentials, so `lease://` fallback chains can proceed during an outage. Lease ownership remains tracked for cleanup even when expired credential data is discarded.
+
+Credential replacement installs settings and cache, confirms the required consumer reconnect, then retires the previous lease. Failed handoffs restore the previous settings and cache; old and unconfirmed candidate IDs remain owned until safe cleanup or shutdown. Failed revocations are retried, using the Vault client that issued the lease. RabbitMQ must report an open session; PostgreSQL must support and successfully complete `reconnect_with_fresh_creds`; Redis must reconnect successfully and report connected when that status is available.
+
+Lease names are stable across environments. The actual Vault paths are deployment-specific config. `active_leases` uses Symbol names; `fetch` and `lease_data` accept either Strings or Symbols.
+
+`LeaseManager#register_ref(name, key, path)` accepts typed destination paths: Symbols for existing Hash keys and nonnegative Integers for existing Array indexes. A lease-data key can target multiple destinations; duplicate registrations are ignored. `push_to_settings` updates valid destinations, including nested arrays, and returns the number of successful writes. Invalid, missing, frozen, or out-of-bounds destinations are not modified. Transactional credential handoff requires every referenced destination to be writable before changing any of them.
 
 ## Multi-Cluster Vault
 
-`VaultCluster` supports connecting to multiple Vault clusters simultaneously. Each cluster has its own `::Vault::Client` instance.
+`VaultCluster` supports connecting to multiple Vault clusters simultaneously. Each cluster has its own `Legion::Crypt::VaultClient` instance.
+
+Clients are reused only while their endpoint, namespace, TLS verification, and token match the current configuration. Connection changes replace the cached client without disabling lease or token owners retaining its predecessor. Displaced clients are weakly tracked, so the cache does not keep unused clients alive; shutdown permanently closes all surviving clients after owner cleanup. In-place authentication token refreshes preserve the current client.
 
 ```json
 {
@@ -182,7 +221,7 @@ Lease names are stable across environments. The actual Vault paths are deploymen
 Legion::Crypt.ldap_login_all(username: 'user', password: 'pass')
 
 # Read from specific cluster
-Legion::Crypt.read('secret/data/mykey', cluster: :secondary)
+Legion::Crypt.read('secret/data/mykey', cluster_name: :secondary)
 
 # Get a Vault client for a specific cluster
 client = Legion::Crypt.vault_client(:primary)
@@ -190,6 +229,12 @@ client = Legion::Crypt.vault_client(:primary)
 
 When `clusters` is empty, the legacy single-cluster path is used (backward compatible).
 
+LDAP login starts token maintenance immediately, including after `Crypt.start`. Cluster state retains `lease_duration`, `renewable`, `expires_at`, and `relogin_required`; passwords are used only for the login request. Renewable tokens renew at 75% of their lifetime through the same cluster client. Transient failures retry within the remaining lifetime; nonrenewable tokens remain available until expiry. Expiry or a terminal renewal rejection marks the cluster disconnected and sets `relogin_required: true`. Authenticate again with `ldap_login` or `ldap_login_all`; LDAP never falls back to Kerberos authentication.
+
+Repeated login stops the previous token worker before installing its replacement, and shutdown stops all token workers. With clusters configured, unavailable or expired clusters cannot fall back to the legacy global Vault client.
+
+JWT and Kerberos `login!` use the same grant lifecycle: token, TTL, expiry, renewability and authentication strategy replace the previous state together. Existing token workers stop before publication and replacement workers use the new grant's lifetime. JWT tokens renew without Kerberos fallback; a login result completing after shutdown is rejected.
+
 ## Kerberos Authentication
 
 When `crypt.vault.auth_method` is set to `kerberos`, `Crypt.start` performs Kerberos auto-auth to Vault using `KerberosAuth`:
@@ -209,20 +254,29 @@ When `crypt.vault.auth_method` is set to `kerberos`, `Crypt.start` performs Kerb
 }
 ```
 
-The SPNEGO token is sent as an HTTP `Authorization` header (not JSON body). The Vault namespace is cleared before auth (Kerberos mount is at root) and restored after. Requires Homebrew MIT Kerberos (`brew install krb5`) on macOS — the system Heimdal library is not compatible.
+The SPNEGO token is sent as an HTTP `Authorization` header (not JSON body). Kerberos auth uses the configured namespace, where the auth mount resides; configure the cluster with `"namespace": null` for a root-mounted auth method. The client namespace is not cleared or temporarily changed during authentication. Requires Homebrew MIT Kerberos (`brew install krb5`) on macOS — the system Heimdal library is not compatible.
 
 `TokenRenewer` keeps the Vault token alive: renews at 75% TTL, re-auths via Kerberos if renewal fails, uses exponential backoff.
 
+## SPIFFE Workload API
+
+The local Unix-socket Workload API exchange has a shared 10-second monotonic deadline. Connection, HTTP/2 handshake, request writes, and flushes additionally share a 5-second setup budget; response reads use the remaining operation time. Availability probes are bounded to 5 seconds, and failed exchanges close acquired sockets.
+
+Responses may split the gRPC prefix or body across HTTP/2 DATA frames and socket reads. JWT-SVID audiences use protobuf varint lengths, including audiences of 128 bytes or longer. X.509 fallback remains opt-in; JWT-SVID failures raise `Spiffe::SvidError`.
+
 ## mTLS
 
-`Crypt::Mtls` issues mTLS certificates from Vault PKI. `Crypt::CertRotation` runs a background thread renewing certs at 50% TTL. `Transport::Connection::Vault` applies tempfile-based Bunny mTLS. Feature-flagged via `security.mtls.enabled: false`.
+`Crypt::Mtls` issues mTLS certificates from Vault PKI. When `security.mtls.enabled` is true, `Legion::Service` owns a `Crypt::CertRotation` worker. The worker renews at expiry minus the certificate lifetime multiplied by `security.mtls.renewal_window` (default `0.5`), rather than waiting for a fixed polling interval. Initial issuance and renewal failures retry with exponential backoff from 1 to 60 seconds; a failed renewal retains the last installed certificate. Shutdown interrupts scheduled waits, bounds in-flight issuance with the Vault operation timeout, and prevents late results from replacing the certificate.
+
+`Transport::Connection::Vault` independently acquires and applies tempfile-based Bunny mTLS credentials. Certificate rotation does not itself close transport connections when a certificate expires. mTLS is disabled by default.
 
 ## Requirements
 
 - Ruby >= 3.4
 - `ed25519` (~> 1.3)
 - `jwt` gem (>= 2.7)
-- `vault` gem (>= 0.17, optional)
+- `faraday` gem (~> 2.0)
+- `legion-json` gem (>= 1.2.0; JSON 3 supported)
 - HashiCorp Vault (optional, for secrets management)
 - `gssapi` gem (optional, required for Kerberos auth)
 

data/legion-crypt.gemspec

@@ -27,7 +27,8 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency 'concurrent-ruby', '~> 1.3'
   spec.add_dependency 'ed25519', '~> 1.3'
+  spec.add_dependency 'faraday', '~> 2.0'
   spec.add_dependency 'jwt', '>= 2.7'
+  spec.add_dependency 'legion-json', '>= 1.2.0'
   spec.add_dependency 'legion-logging', '>= 1.5.0'
-  spec.add_dependency 'vault', '>= 0.17'
 end

data/lib/legion/crypt/cert_rotation.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'legion/logging/helper'
+require 'legion/crypt/vault_operation'
 
 module Legion
   module Crypt
@@ -8,115 +9,127 @@ module Legion
       include Legion::Logging::Helper
 
       DEFAULT_CHECK_INTERVAL = 43_200 # 12 hours
+      MINIMUM_SLEEP = 0.01
+      INITIAL_RETRY_DELAY = 1
+      MAX_RETRY_DELAY = 60
 
       attr_reader :check_interval, :current_cert, :issued_at
 
       def initialize(check_interval: DEFAULT_CHECK_INTERVAL)
+        unless check_interval.is_a?(Numeric) && check_interval.finite? && check_interval.positive?
+          raise ArgumentError, 'Certificate check interval must be finite and positive'
+        end
+
         @check_interval = check_interval
         @current_cert   = nil
         @issued_at      = nil
         @running        = false
         @thread         = nil
         @mutex          = Mutex.new
+        @wake          = ConditionVariable.new
+        @generation    = 0
+        @retry_delay   = INITIAL_RETRY_DELAY
+        @next_attempt  = 0
       end
 
       def start
         return unless Legion::Crypt::Mtls.enabled?
-        return if running?
 
-        @running = true
-        @thread  = Thread.new { rotation_loop }
+        @mutex.synchronize do
+          return if @thread&.alive?
+
+          @running = true
+          @generation += 1
+          generation = @generation
+          @thread = Thread.new { rotation_loop(generation: generation) }
+        end
         log.info('[mTLS] CertRotation started')
       end
 
-      def stop
-        @running = false
-        begin
-          @thread&.wakeup
-        rescue ThreadError => e
-          handle_exception(e, level: :debug, operation: 'crypt.cert_rotation.stop')
-          nil
-        end
-        @thread&.join(2)
-        if @thread&.alive?
-          log.warn '[mTLS] CertRotation thread did not stop within timeout'
-        else
-          @thread = nil
+      def stop(deadline: nil)
+        thread = @mutex.synchronize do
+          @running = false
+          @generation += 1
+          @wake.broadcast
+          @thread
         end
+        deadline ||= ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) + Legion::Crypt::VaultOperation::SHUTDOWN_TIMEOUT
+        Legion::Crypt::VaultOperation.with_timeout(deadline: deadline) { thread.join } if thread && thread != Thread.current
+        @mutex.synchronize { @thread = nil if @thread.equal?(thread) && !thread&.alive? }
         log.info('[mTLS] CertRotation stopped')
+      rescue StandardError => e
+        handle_exception(e, level: :warn, operation: 'crypt.cert_rotation.stop')
       end
 
       def running?
-        (@running && @thread&.alive?) || false
+        @mutex.synchronize { (@running && @thread&.alive?) || false }
       end
 
-      def rotate!
-        node_name = node_common_name
-        new_cert = Legion::Crypt::Mtls.issue_cert(common_name: node_name)
-        @mutex.synchronize do
+      def rotate!(generation: nil)
+        generation ||= @mutex.synchronize { @generation }
+        new_cert = Legion::Crypt::VaultOperation.with_timeout { Legion::Crypt::Mtls.issue_cert(common_name: node_common_name) }
+        issued_at = Time.now
+        raise 'Vault PKI returned an expired certificate' unless new_cert[:expiry] > issued_at
+
+        installed = @mutex.synchronize do
+          next false unless generation == @generation
+
           @current_cert = new_cert
-          @issued_at    = Time.now
+          @issued_at = issued_at
+          @retry_delay = INITIAL_RETRY_DELAY
+          @next_attempt = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) + MINIMUM_SLEEP
+          @wake.broadcast
+          true
         end
+        return unless installed
+
         log.info("[mTLS] Certificate rotated: serial=#{new_cert[:serial]} expiry=#{new_cert[:expiry]}")
         emit_rotated_event(new_cert)
         new_cert
       end
 
       def needs_renewal?
-        current_cert = nil
-        issued_at = nil
-        @mutex.synchronize do
-          current_cert = @current_cert
-          issued_at = @issued_at
-        end
-        return false if current_cert.nil? || issued_at.nil?
-
-        expiry = current_cert[:expiry]
-        total  = expiry - issued_at
-        return true if total <= 0
-
-        remaining = expiry - Time.now
-        fraction  = remaining / total
-        fraction < renewal_window
+        @mutex.synchronize { renewal_delay <= 0 }
       end
 
       private
 
-      def rotation_loop
-        rotate!
-      rescue StandardError => e
-        handle_exception(e, level: :error, operation: 'crypt.cert_rotation.rotation_loop')
-        log.error("[mTLS] Initial rotation failed: #{e.message}")
-      ensure
-        loop_check
-      end
-
-      def loop_check
-        while @running
-          interruptible_sleep(@check_interval)
-          next unless @running && needs_renewal?
+      def rotation_loop(generation:)
+        loop do
+          due = @mutex.synchronize do
+            return unless @running && generation == @generation
+
+            retry_wait = @next_attempt - ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+            wait = [retry_wait, renewal_delay].max
+            if wait.positive?
+              @wake.wait(@mutex, [wait, @check_interval].min.clamp(MINIMUM_SLEEP, Float::INFINITY))
+              false
+            else
+              true
+            end
+          end
+          next unless due
 
           begin
-            rotate!
+            rotate!(generation: generation)
           rescue StandardError => e
-            handle_exception(e, level: :error, operation: 'crypt.cert_rotation.loop_check')
-            log.error("[mTLS] Rotation check failed: #{e.message}")
+            handle_exception(e, level: :error, operation: 'crypt.cert_rotation.rotation_loop')
+            @mutex.synchronize do
+              next unless @running && generation == @generation
+
+              @next_attempt = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) + @retry_delay
+              @retry_delay = [@retry_delay * 2, MAX_RETRY_DELAY].min
+            end
           end
         end
-      rescue StandardError => e
-        handle_exception(e, level: :error, operation: 'crypt.cert_rotation.loop_check')
-        log.error("[mTLS] CertRotation loop error: #{e.message}")
-        retry if @running
       end
 
-      def interruptible_sleep(seconds)
-        deadline = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) + seconds
-        loop do
-          remaining = deadline - ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
-          break if remaining <= 0 || !@running
+      def renewal_delay
+        return 0 unless @current_cert && @issued_at
 
-          sleep([remaining, 1.0].min)
-        end
+        expiry = @current_cert[:expiry]
+        lifetime = expiry - @issued_at
+        expiry - Time.now - (lifetime * renewal_window)
       end
 
       def renewal_window
@@ -126,7 +139,12 @@ module Legion
         return 0.5 if security.nil?
 
         mtls = security[:mtls] || security['mtls'] || {}
-        mtls[:renewal_window] || mtls['renewal_window'] || 0.5
+        window = mtls[:renewal_window] || mtls['renewal_window'] || 0.5
+        unless window.is_a?(Numeric) && window.finite? && window >= 0 && window < 1
+          raise ArgumentError, 'Certificate renewal window must be finite and between zero and one (exclusive)'
+        end
+
+        window
       rescue StandardError => e
         handle_exception(e, level: :debug, operation: 'crypt.cert_rotation.renewal_window')
         0.5

data/lib/legion/crypt/cipher.rb

@@ -37,7 +37,7 @@ module Legion
       end
 
       def decrypt(message, init_vector)
-        secret = wait_for_cluster_secret
+        secret = cs
         result = if authenticated_ciphertext?(message)
                    decrypt_authenticated(message, init_vector, secret)
                  else
@@ -94,19 +94,6 @@ module Legion
 
       private
 
-      def wait_for_cluster_secret
-        loop do
-          secret = cs
-          return secret if secret.is_a?(String)
-          break if Legion::Settings[:client][:shutting_down]
-
-          log.debug('sleeping Legion::Crypt.decrypt due to CS not being set')
-          sleep(0.5)
-        end
-
-        cs
-      end
-
       def authenticated_ciphertext?(message)
         message.start_with?("#{AUTHENTICATED_PREFIX}:")
       end
@@ -121,11 +108,14 @@ module Legion
           message:            message
         )
 
+        auth_tag = Base64.strict_decode64(encoded_auth_tag)
+        raise ArgumentError, 'invalid GCM authentication tag length' unless auth_tag.bytesize == 16
+
         decipher = OpenSSL::Cipher.new(AUTHENTICATED_CIPHER)
         decipher.decrypt
         decipher.key = secret
         decipher.iv = Base64.strict_decode64(init_vector)
-        decipher.auth_tag = Base64.strict_decode64(encoded_auth_tag)
+        decipher.auth_tag = auth_tag
         decipher.update(Base64.strict_decode64(encoded_ciphertext)) + decipher.final
       end