legion-crypt 1.4.23 → 1.4.25

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc1b26f800d0d5512ee35965b6700750bcfcacc5265042f749c3e56a973140c6
-  data.tar.gz: cb154b6f1c44688b9a7d4d41e4c125279c9c945b8b162da448c1b2f7b0bacb67
+  metadata.gz: 37fe457155877f451f702c4de046bcf9bd5cabd8a86d9bbf51cd3c4484ab10ce
+  data.tar.gz: 642f9ddda00b7566be3001a847687bded7fc196a0e2330936f909b4753cb9eb3
 SHA512:
-  metadata.gz: 4bf5a0be9d6c724dc0011508e7ce3ab23a8a9af46c7800fdd8a45711fa75e3569635bec16467d942306124c17c3a14c45bd161082b0e1c62a80c6172e9f050d9
-  data.tar.gz: cd5269888634c81cda229646c13db9a61a67c687430bda6b5202047a73f84fb480b55e1e39534fcadec348b34ee62f0c913723338b20c3ffba6e31943fa38922
+  metadata.gz: b98e831598f7a901502b59950e2ae46f4393ec2fb6fab9f2d576295905ebdad31187c170fdc70f304ce4ef1d3fd14470a0001b24000869c6e96ee3ab8ee269a8
+  data.tar.gz: 593f3909d5374c15cda3f69ae1697a59bb1b3c9a5f713aa91fde5d77656bb7a8b7b2062e618652afe7554a518e6251b219d8c3831bc9c82ddf5a6784cca1f56b

data/AGENTS.md

@@ -0,0 +1,38 @@
+# legion-crypt Agent Notes
+
+## Scope
+
+`legion-crypt` handles cryptography and secret workflows for Legion: cipher ops, Vault integration, JWT/JWKS verification, key lifecycle, mTLS, and lease/token renewers.
+
+## Fast Start
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## Primary Entry Points
+
+- `lib/legion/crypt.rb`
+- `lib/legion/crypt/cipher.rb`
+- `lib/legion/crypt/jwt.rb`
+- `lib/legion/crypt/jwks_client.rb`
+- `lib/legion/crypt/vault.rb`
+- `lib/legion/crypt/lease_manager.rb`
+- `lib/legion/crypt/token_renewer.rb`
+- `lib/legion/crypt/mtls.rb`
+
+## Guardrails
+
+- Treat all changes as security-sensitive. Never log secrets, tokens, private keys, or decrypted plaintext.
+- Preserve JWT behavior across HS256/RS256 and external JWKS validation.
+- Keep Vault-dependent logic optional and safely guarded for environments without Vault.
+- Background renewal/rotation threads must stop cleanly on shutdown and handle failure with bounded retry.
+- Maintain compatibility for Kerberos, LDAP, and JWT Vault auth paths.
+- Cryptographic defaults and key lifecycle behavior are contract-sensitive; change only with test coverage.
+
+## Validation
+
+- Run targeted specs for changed auth/crypto paths first.
+- Before handoff, run full `bundle exec rspec` and `bundle exec rubocop`.

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Legion::Crypt
 
+## [1.4.25] - 2026-03-28
+
+### Fixed
+- `kv_client` and `logical_client` now route through the default cluster `Vault::Client` when multi-cluster is configured, preventing 403 errors caused by the un-initialized global `::Vault` singleton (closes #1)
+- `WorkloadApiClient#decode_varint`: returns `[value, bytes_consumed]` correctly; previous implementation returned `[value, start_pos]` causing the protobuf field scanner to never advance past the first tag, breaking `extract_proto_field` for any non-empty input
+- `WorkloadApiClient#self_signed_fallback`: Subject CN is now a plain string (`legion-fallback-svid`) instead of the full `spiffe://` URI, preventing `TypeError: no implicit conversion of nil into String` from `OpenSSL::X509::Name.parse` on Ruby 3.4
+- `spiffe_identity_helpers_spec.rb`: test cert helper uses plain CN for the same reason
+
+### Added
+- Specs for `kv_client`/`logical_client` routing: 20 examples covering multi-cluster path (cluster client used, global singleton not touched) and single-server fallback path (global singleton used, `vault_client` not called) for `get`, `write`, `exist?`, `delete`, and `read` methods
+- SPIFFE/SVID support implementing GitHub issue #8: `Spiffe::WorkloadApiClient` (Unix-domain gRPC for x509/JWT SVIDs with self-signed fallback), `Spiffe::SvidRotation` (background renewal at configurable window), `Spiffe::IdentityHelpers` mixin (sign/verify/extract/trust helpers); wired into `Crypt.start`/`shutdown` behind `spiffe.enabled: false` feature flag
+- `spiffe` default settings block with `enabled`, `socket_path`, `trust_domain`, `workload_id`, `renewal_window`
+- 82 specs covering SPIFFE ID parsing, SVID lifecycle, Workload API client (with mocked socket), self-signed fallback, protobuf field decoding, signing/verification, SAN extraction, and trust chain validation (closes #8)
+
+## [1.4.24] - 2026-03-28
+
+### Fixed
+- `LeaseManager#start`: no longer creates new Vault dynamic credentials when a valid cached lease already exists, preventing orphaned RabbitMQ users on repeated `start` calls (closes #6)
+- `LeaseManager#start`: expired leases are now revoked before re-fetching, ensuring clean credential rotation
+
+### Added
+- `LeaseManager#lease_valid?`: returns true when a named lease is cached and its `expires_at` is in the future
+- `LeaseManager#revoke_expired_lease`: revokes and clears a stale cached lease entry before a re-fetch
+- Specs for repeated `start` idempotency, expired-lease re-fetch, `lease_valid?` edge cases
+
 ## [1.4.23] - 2026-03-27
 
 ### Fixed

data/lib/legion/crypt/lease_manager.rb

@@ -25,6 +25,13 @@ module Legion
           path = opts['path'] || opts[:path]
           next unless path
 
+          if lease_valid?(name)
+            log_debug("LeaseManager: reusing valid cached lease for '#{name}'")
+            next
+          end
+
+          revoke_expired_lease(name)
+
           begin
             response = logical.read(path)
             unless response
@@ -174,6 +181,34 @@ module Legion
         log_warn("LeaseManager: failed to renew lease '#{name}': #{e.message}")
       end
 
+      def lease_valid?(name)
+        meta = @active_leases[name]
+        return false unless meta
+
+        expires_at = meta[:expires_at]
+        return false unless expires_at
+
+        expires_at > Time.now
+      end
+
+      def revoke_expired_lease(name)
+        meta = @active_leases[name]
+        return unless meta
+
+        lease_id = meta[:lease_id]
+        return if lease_id.nil? || lease_id.empty?
+
+        begin
+          sys.revoke(lease_id)
+          log_debug("LeaseManager: revoked expired lease '#{name}' (#{lease_id}) before re-fetch")
+        rescue StandardError => e
+          log_warn("LeaseManager: failed to revoke expired lease '#{name}' (#{lease_id}): #{e.message}")
+        ensure
+          @active_leases.delete(name)
+          @lease_cache.delete(name)
+        end
+      end
+
       def approaching_expiry?(lease)
         expires_at = lease[:expires_at]
         lease_duration = lease[:lease_duration]

data/lib/legion/crypt/settings.rb

@@ -13,6 +13,16 @@ module Legion
         }
       end
 
+      def self.spiffe
+        {
+          enabled:        false,
+          socket_path:    '/tmp/spire-agent/public/api.sock',
+          trust_domain:   'legion.internal',
+          workload_id:    nil,
+          renewal_window: 0.5
+        }
+      end
+
       def self.default
         {
           vault:            vault,

data/lib/legion/crypt/spiffe/identity_helpers.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'base64'
+
+module Legion
+  module Crypt
+    module Spiffe
+      # Helpers for signing, verifying, and inspecting SPIFFE SVIDs.
+      #
+      # These methods work directly with X509Svid and JwtSvid structs
+      # returned by WorkloadApiClient.  No external gem is required —
+      # all operations use the Ruby stdlib OpenSSL bindings.
+      module IdentityHelpers
+        # Sign arbitrary data with the private key from an X.509 SVID.
+        # Returns the signature as a Base64-encoded string.
+        #
+        # @param data [String] The bytes to sign (any encoding; treated as binary).
+        # @param svid [X509Svid] An X509Svid whose key_pem is populated.
+        # @return [String] Base64-encoded DER signature.
+        def sign_with_svid(data, svid:)
+          raise SvidError, 'Cannot sign: SVID is nil' if svid.nil?
+          raise SvidError, "Cannot sign: SVID '#{svid.spiffe_id}' has expired" if svid.expired?
+          raise SvidError, 'Cannot sign: SVID private key is missing' if svid.key_pem.nil?
+
+          key       = OpenSSL::PKey.read(svid.key_pem)
+          digest    = OpenSSL::Digest.new('SHA256')
+          signature = key.sign(digest, data.b)
+          Base64.strict_encode64(signature)
+        end
+
+        # Verify a Base64-encoded signature produced by sign_with_svid.
+        #
+        # @param data [String] Original data that was signed.
+        # @param signature_b64 [String] Base64-encoded signature from sign_with_svid.
+        # @param svid [X509Svid] The SVID whose public certificate is used for verification.
+        # @return [Boolean] true if the signature is valid.
+        def verify_svid_signature(data, signature_b64:, svid:)
+          raise SvidError, 'Cannot verify: SVID is nil' if svid.nil?
+          raise SvidError, "Cannot verify: SVID '#{svid.spiffe_id}' has expired" if svid.expired?
+          raise SvidError, 'Cannot verify: SVID certificate is missing' if svid.cert_pem.nil?
+
+          cert      = OpenSSL::X509::Certificate.new(svid.cert_pem)
+          digest    = OpenSSL::Digest.new('SHA256')
+          signature = Base64.strict_decode64(signature_b64)
+          cert.public_key.verify(digest, signature, data.b)
+        rescue OpenSSL::PKey::PKeyError, OpenSSL::X509::CertificateError, ArgumentError => e
+          log_spiffe_warn("SVID signature verification error: #{e.message}")
+          false
+        end
+
+        # Extract the SPIFFE ID embedded in an X.509 certificate's SAN URI extension.
+        # Returns a SpiffeId struct or nil if none is found.
+        #
+        # @param cert_pem [String] PEM-encoded X.509 certificate.
+        # @return [SpiffeId, nil]
+        def extract_spiffe_id_from_cert(cert_pem)
+          cert = OpenSSL::X509::Certificate.new(cert_pem)
+          san  = cert.extensions.find { |e| e.oid == 'subjectAltName' }
+          return nil unless san
+
+          san.value.split(',').each do |entry|
+            entry = entry.strip
+            next unless entry.start_with?('URI:spiffe://')
+
+            uri = entry.sub('URI:', '')
+            return Legion::Crypt::Spiffe.parse_id(uri)
+          rescue InvalidSpiffeIdError
+            next
+          end
+
+          nil
+        rescue OpenSSL::X509::CertificateError
+          nil
+        end
+
+        # Validate that a certificate chain is trusted by the bundle embedded
+        # in the given SVID.  Returns true if the leaf cert chains up to the
+        # bundle CA, false otherwise.
+        #
+        # @param cert_pem [String] PEM-encoded leaf certificate to validate.
+        # @param svid [X509Svid] SVID whose bundle_pem contains the trust anchor.
+        # @return [Boolean]
+        def trusted_cert?(cert_pem, svid:)
+          raise SvidError, 'Cannot check trust: SVID is nil' if svid.nil?
+          return false if svid.bundle_pem.nil?
+
+          store = OpenSSL::X509::Store.new
+          store.add_cert(OpenSSL::X509::Certificate.new(svid.bundle_pem))
+
+          leaf = OpenSSL::X509::Certificate.new(cert_pem)
+          store.verify(leaf)
+        rescue OpenSSL::X509::CertificateError, OpenSSL::X509::StoreError
+          false
+        end
+
+        # Return a hash of identity information extracted from an SVID.
+        #
+        # @param svid [X509Svid, JwtSvid] Any SVID type.
+        # @return [Hash]
+        def svid_identity(svid)
+          return {} if svid.nil?
+
+          base = {
+            spiffe_id:     svid.spiffe_id.to_s,
+            trust_domain:  svid.spiffe_id.trust_domain,
+            workload_path: svid.spiffe_id.path,
+            expiry:        svid.expiry,
+            expired:       svid.expired?
+          }
+
+          case svid
+          when X509Svid
+            base.merge(type: :x509, ttl_seconds: svid.ttl.to_i)
+          when JwtSvid
+            base.merge(type: :jwt, audience: svid.audience)
+          else
+            base
+          end
+        end
+
+        private
+
+        def log_spiffe_warn(message)
+          Legion::Logging.warn("[SPIFFE] #{message}") if defined?(Legion::Logging)
+        end
+      end
+    end
+  end
+end

data/lib/legion/crypt/spiffe/svid_rotation.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Legion
+  module Crypt
+    module Spiffe
+      # Background thread that keeps the current X.509 SVID fresh.
+      #
+      # Mirrors the pattern used by CertRotation (mTLS) but targets the
+      # SPIFFE Workload API instead of Vault PKI.  The check interval
+      # defaults to 60 seconds; renewal fires when the SVID is past 50%
+      # of its lifetime (configurable via security.spiffe.renewal_window).
+      class SvidRotation
+        DEFAULT_CHECK_INTERVAL = 60
+
+        attr_reader :check_interval, :current_svid
+
+        def initialize(check_interval: DEFAULT_CHECK_INTERVAL, client: nil)
+          @check_interval = check_interval
+          @client         = client || WorkloadApiClient.new
+          @current_svid   = nil
+          @issued_at      = nil
+          @running        = false
+          @thread         = nil
+          @mutex          = Mutex.new
+        end
+
+        def start
+          return unless Legion::Crypt::Spiffe.enabled?
+          return if running?
+
+          @running = true
+          @thread  = Thread.new { rotation_loop }
+          @thread.name = 'spiffe-svid-rotation'
+          log_info('[SPIFFE] SvidRotation started')
+        end
+
+        def stop
+          @running = false
+          begin
+            @thread&.wakeup
+          rescue ThreadError
+            nil
+          end
+          @thread&.join(3)
+          @thread = nil
+          log_debug('[SPIFFE] SvidRotation stopped')
+        end
+
+        def running?
+          (@running && @thread&.alive?) || false
+        end
+
+        def rotate!
+          svid = @client.fetch_x509_svid
+          @mutex.synchronize do
+            @current_svid = svid
+            @issued_at    = Time.now
+          end
+          log_info("[SPIFFE] SVID rotated: id=#{svid.spiffe_id} expiry=#{svid.expiry}")
+          svid
+        end
+
+        def needs_renewal?
+          svid      = nil
+          issued_at = nil
+          @mutex.synchronize do
+            svid      = @current_svid
+            issued_at = @issued_at
+          end
+
+          return true if svid.nil? || issued_at.nil?
+          return true if svid.expired?
+
+          total = svid.expiry - issued_at
+          return true if total <= 0
+
+          remaining = svid.expiry - Time.now
+          fraction  = remaining / total
+          fraction < renewal_window
+        end
+
+        private
+
+        def rotation_loop
+          begin
+            rotate!
+          rescue StandardError => e
+            log_warn("[SPIFFE] Initial SVID fetch failed: #{e.message}")
+          end
+          loop_check
+        end
+
+        def loop_check
+          while @running
+            interruptible_sleep(@check_interval)
+            next unless @running && needs_renewal?
+
+            begin
+              rotate!
+            rescue StandardError => e
+              log_warn("[SPIFFE] SVID rotation failed: #{e.message}")
+            end
+          end
+        rescue StandardError => e
+          log_warn("[SPIFFE] SvidRotation 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
+
+            sleep([remaining, 1.0].min)
+          end
+        end
+
+        def renewal_window
+          return SVID_RENEWAL_RATIO unless defined?(Legion::Settings)
+
+          security = Legion::Settings[:security]
+          return SVID_RENEWAL_RATIO if security.nil?
+
+          spiffe = security[:spiffe] || security['spiffe'] || {}
+          spiffe[:renewal_window] || spiffe['renewal_window'] || SVID_RENEWAL_RATIO
+        rescue StandardError
+          SVID_RENEWAL_RATIO
+        end
+
+        def log_info(msg)
+          if defined?(Legion::Logging)
+            Legion::Logging.info(msg)
+          else
+            $stdout.puts(msg)
+          end
+        end
+
+        def log_debug(msg)
+          if defined?(Legion::Logging)
+            Legion::Logging.debug(msg)
+          else
+            $stdout.puts("[DEBUG] #{msg}")
+          end
+        end
+
+        def log_warn(msg)
+          if defined?(Legion::Logging)
+            Legion::Logging.warn(msg)
+          else
+            warn("[WARN] #{msg}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/crypt/spiffe/workload_api_client.rb

@@ -0,0 +1,391 @@
+# frozen_string_literal: true
+
+require 'socket'
+require 'openssl'
+
+module Legion
+  module Crypt
+    module Spiffe
+      # Minimal SPIFFE Workload API client.
+      #
+      # The SPIFFE Workload API is served over a Unix domain socket by a local
+      # SPIRE agent.  The wire protocol is gRPC/HTTP2, but we avoid pulling in
+      # a full gRPC stack by implementing just enough of the HTTP/2 framing to
+      # send a single unary RPC call and parse a single response.
+      #
+      # For environments that cannot make a real SPIRE call (CI, lite mode,
+      # no socket present) the client returns a self-signed fallback SVID so
+      # that callers never have to special-case the nil case.
+      class WorkloadApiClient
+        # gRPC content-type and method path for the Workload API FetchX509SVID RPC.
+        GRPC_CONTENT_TYPE = 'application/grpc'
+        FETCH_X509_METHOD = '/spiffe.workload.SpiffeWorkloadAPI/FetchX509SVID'
+        FETCH_JWT_METHOD  = '/spiffe.workload.SpiffeWorkloadAPI/FetchJWTSVID'
+
+        # Handshake + settings frames required to open an HTTP/2 connection.
+        HTTP2_PREFACE = "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n"
+        HTTP2_SETTINGS_FRAME = [0, 4, 0, 0, 0, 0].pack('NnCCNN')
+
+        CONNECT_TIMEOUT = 5
+        READ_TIMEOUT    = 10
+
+        def initialize(socket_path: nil, trust_domain: nil)
+          @socket_path  = socket_path  || Legion::Crypt::Spiffe.socket_path
+          @trust_domain = trust_domain || Legion::Crypt::Spiffe.trust_domain
+        end
+
+        # Fetch an X.509 SVID from the SPIRE Workload API.
+        # Returns a populated X509Svid struct.
+        # Falls back to a self-signed certificate when the Workload API is unavailable.
+        def fetch_x509_svid
+          raw = call_workload_api(FETCH_X509_METHOD, '')
+          parse_x509_svid_response(raw)
+        rescue WorkloadApiError, IOError, Errno::ENOENT, Errno::ECONNREFUSED, Errno::EPIPE => e
+          log_warn("[SPIFFE] Workload API unavailable (#{e.message}); using self-signed fallback")
+          self_signed_fallback
+        end
+
+        # Fetch a JWT SVID from the SPIRE Workload API for the given audience.
+        def fetch_jwt_svid(audience:)
+          payload  = encode_jwt_request(audience)
+          raw      = call_workload_api(FETCH_JWT_METHOD, payload)
+          parse_jwt_svid_response(raw, audience)
+        rescue WorkloadApiError, IOError, Errno::ENOENT, Errno::ECONNREFUSED, Errno::EPIPE => e
+          log_warn("[SPIFFE] JWT SVID fetch failed (#{e.message})")
+          raise SvidError, "Failed to fetch JWT SVID for audience '#{audience}': #{e.message}"
+        end
+
+        # Returns true when the SPIRE agent socket exists and is reachable.
+        def available?
+          return false unless ::File.exist?(@socket_path)
+
+          sock = UNIXSocket.new(@socket_path)
+          sock.close
+          true
+        rescue StandardError
+          false
+        end
+
+        private
+
+        # Minimal HTTP/2 + gRPC unary call over a Unix domain socket.
+        # This is intentionally simple: one request frame, one response frame.
+        def call_workload_api(method_path, request_body)
+          sock = connect_socket
+          begin
+            send_grpc_request(sock, method_path, request_body)
+            read_grpc_response(sock)
+          ensure
+            sock.close rescue nil # rubocop:disable Style/RescueModifier
+          end
+        end
+
+        def connect_socket
+          raise WorkloadApiError, "SPIRE agent socket not found at '#{@socket_path}'" unless ::File.exist?(@socket_path)
+
+          sock = UNIXSocket.new(@socket_path)
+          # Write HTTP/2 connection preface and initial SETTINGS frame.
+          sock.write(HTTP2_PREFACE)
+          sock.write(HTTP2_SETTINGS_FRAME)
+          sock.flush
+          sock
+        rescue Errno::ENOENT
+          raise WorkloadApiError, "SPIRE agent socket not found at '#{@socket_path}'"
+        rescue Errno::ECONNREFUSED, Errno::EACCES => e
+          raise WorkloadApiError, "Cannot connect to SPIRE agent socket: #{e.message}"
+        end
+
+        # Build and send a minimal gRPC/HTTP2 HEADERS + DATA frame.
+        # We encode only the fields the SPIRE agent needs to accept the request.
+        def send_grpc_request(sock, method_path, body)
+          headers = build_grpc_headers(method_path)
+          headers_frame = encode_http2_frame(type: 0x01, flags: 0x04, stream_id: 1, payload: headers)
+          data_frame    = encode_grpc_data_frame(body)
+          sock.write(headers_frame + data_frame)
+          sock.flush
+        end
+
+        def build_grpc_headers(method_path)
+          # Minimal set of pseudo-headers and gRPC headers encoded as HPACK literals.
+          # We use the no-indexing literal representation for simplicity.
+          encode_header(':method', 'POST') +
+            encode_header(':path', method_path) +
+            encode_header(':scheme', 'http') +
+            encode_header(':authority', 'localhost') +
+            encode_header('content-type', GRPC_CONTENT_TYPE) +
+            encode_header('te', 'trailers')
+        end
+
+        # Encode a single HPACK literal header field (no indexing).
+        def encode_header(name, value)
+          name_bytes  = name.b
+          value_bytes = value.b
+          [0x00].pack('C') +
+            encode_hpack_string(name_bytes) +
+            encode_hpack_string(value_bytes)
+        end
+
+        def encode_hpack_string(bytes)
+          # Length prefix (non-Huffman).
+          len = bytes.bytesize
+          if len < 128
+            [len].pack('C') + bytes
+          else
+            # Multi-byte length encoding (RFC 7541 §5.1).
+            parts = [0x80 | (len & 0x7F)].pack('C')
+            len >>= 7
+            parts += [(len.positive? ? 0x80 : 0x00) | (len & 0x7F)].pack('C')
+            parts + bytes
+          end
+        end
+
+        # Encode a gRPC message as a DATA frame (5-byte gRPC header + body).
+        def encode_grpc_data_frame(body)
+          grpc_header = [0, body.bytesize].pack('CN') # compressed-flag + length
+          payload     = grpc_header + body.b
+          encode_http2_frame(type: 0x00, flags: 0x01, stream_id: 1, payload: payload)
+        end
+
+        # Build an HTTP/2 frame (RFC 7540 §4.1).
+        def encode_http2_frame(type:, flags:, stream_id:, payload:)
+          length = payload.bytesize
+          # 3-byte length + 1-byte type + 1-byte flags + 4-byte stream_id (MSB=0)
+          [length >> 16, (length >> 8) & 0xFF, length & 0xFF, type, flags].pack('CCCCC') +
+            [stream_id & 0x7FFFFFFF].pack('N') +
+            payload.b
+        end
+
+        def read_grpc_response(sock)
+          # Read until we see a DATA frame containing a gRPC message or timeout.
+          deadline = Time.now + READ_TIMEOUT
+          buffer   = ''.b
+
+          loop do
+            raise WorkloadApiError, 'Workload API read timeout' if Time.now > deadline
+
+            ready = sock.wait_readable(1.0)
+            next unless ready
+
+            chunk = sock.read_nonblock(4096, exception: false)
+            break if chunk == :wait_readable || chunk.nil?
+
+            buffer += chunk.b
+            result  = extract_grpc_body(buffer)
+            return result if result
+          end
+
+          raise WorkloadApiError, 'No valid gRPC response received from Workload API'
+        end
+
+        # Scan the raw HTTP/2 buffer for a DATA frame (type=0x00) that contains
+        # a non-empty gRPC message and return the message body bytes.
+        def extract_grpc_body(buffer)
+          pos = 0
+          while pos + 9 <= buffer.bytesize
+            frame_length = (buffer.getbyte(pos) << 16) | (buffer.getbyte(pos + 1) << 8) | buffer.getbyte(pos + 2)
+            frame_type   = buffer.getbyte(pos + 3)
+            pos         += 9 # skip frame header
+
+            if pos + frame_length > buffer.bytesize
+              # Incomplete frame — need more data.
+              return nil
+            end
+
+            payload = buffer.byteslice(pos, frame_length)
+            pos    += frame_length
+
+            next unless frame_type.zero? && payload && payload.bytesize >= 5
+
+            # gRPC message: 1-byte compressed flag + 4-byte length + body
+            compressed = payload.getbyte(0)
+            msg_length = (payload.getbyte(1) << 24) | (payload.getbyte(2) << 16) |
+                         (payload.getbyte(3) << 8)  | payload.getbyte(4)
+            next if msg_length.zero?
+
+            msg_body = payload.byteslice(5, msg_length)
+            next if msg_body.nil? || msg_body.bytesize < msg_length
+
+            # Compressed gRPC responses are not expected from SPIRE; skip them.
+            next unless compressed.zero?
+
+            return msg_body
+          end
+          nil
+        end
+
+        # Minimal protobuf encoding for JWTSVIDParams { audience: [string], id: SpiffeID }.
+        # We only need field 1 (audience, repeated string).
+        def encode_jwt_request(audience)
+          audience_bytes = audience.b
+          # Field 1, wire type 2 (length-delimited) = tag 0x0A
+          "\n#{[audience_bytes.bytesize].pack('C')}#{audience_bytes}"
+        end
+
+        # Parse the raw protobuf bytes from FetchX509SVIDResponse into an X509Svid.
+        # Field layout (spiffe.workload.X509SVIDResponse.svids[0]):
+        #   svids: repeated X509SVID (field 1)
+        #     spiffe_id: string (field 1)
+        #     x509_svid: bytes (field 2) — DER-encoded cert chain
+        #     x509_svid_key: bytes (field 3) — DER-encoded private key (PKCS8)
+        #     bundle: bytes (field 4) — DER-encoded CA bundle
+        def parse_x509_svid_response(raw)
+          svid_bytes = extract_proto_field(raw, field_number: 1)
+          raise SvidError, 'Empty X.509 SVID response from Workload API' if svid_bytes.nil? || svid_bytes.empty?
+
+          spiffe_id_str = extract_proto_string(svid_bytes, field_number: 1)
+          cert_der      = extract_proto_bytes(svid_bytes, field_number: 2)
+          key_der       = extract_proto_bytes(svid_bytes, field_number: 3)
+          bundle_der    = extract_proto_bytes(svid_bytes, field_number: 4)
+
+          raise SvidError, 'X.509 SVID missing certificate data' if cert_der.nil? || cert_der.empty?
+          raise SvidError, 'X.509 SVID missing private key data' if key_der.nil? || key_der.empty?
+
+          cert       = OpenSSL::X509::Certificate.new(cert_der)
+          key        = OpenSSL::PKey.read(key_der)
+          bundle_pem = bundle_der ? OpenSSL::X509::Certificate.new(bundle_der).to_pem : nil
+          spiffe_id  = Legion::Crypt::Spiffe.parse_id(spiffe_id_str)
+
+          X509Svid.new(
+            spiffe_id:  spiffe_id,
+            cert_pem:   cert.to_pem,
+            key_pem:    key.private_to_pem,
+            bundle_pem: bundle_pem,
+            expiry:     cert.not_after
+          )
+        rescue OpenSSL::X509::CertificateError, OpenSSL::PKey::PKeyError => e
+          raise SvidError, "Failed to parse X.509 SVID: #{e.message}"
+        end
+
+        # Parse the raw protobuf bytes from FetchJWTSVIDResponse into a JwtSvid.
+        # Field layout:
+        #   svids: repeated JWTSVID (field 1)
+        #     spiffe_id: string (field 1)
+        #     svid: string (field 2) — the JWT token
+        def parse_jwt_svid_response(raw, audience)
+          svid_bytes = extract_proto_field(raw, field_number: 1)
+          raise SvidError, 'Empty JWT SVID response from Workload API' if svid_bytes.nil? || svid_bytes.empty?
+
+          spiffe_id_str = extract_proto_string(svid_bytes, field_number: 1)
+          token         = extract_proto_string(svid_bytes, field_number: 2)
+
+          raise SvidError, 'JWT SVID missing token' if token.nil? || token.empty?
+
+          expiry    = extract_jwt_expiry(token)
+          spiffe_id = Legion::Crypt::Spiffe.parse_id(spiffe_id_str)
+
+          JwtSvid.new(
+            spiffe_id: spiffe_id,
+            token:     token,
+            audience:  audience,
+            expiry:    expiry
+          )
+        end
+
+        # Build a self-signed X.509 SVID for use when SPIRE is not available.
+        # The SPIFFE ID is placed in the SAN URI extension per the SPIFFE spec.
+        # The Subject CN is a plain workload name (no URI) so OpenSSL parses cleanly.
+        def self_signed_fallback
+          key  = OpenSSL::PKey::EC.generate('prime256v1')
+          cert = OpenSSL::X509::Certificate.new
+          cert.version    = 2
+          cert.serial     = OpenSSL::BN.rand(128)
+          cert.not_before = Time.now
+          cert.not_after  = Time.now + 3600
+
+          spiffe_id_str = "#{SPIFFE_SCHEME}://#{@trust_domain}/workload/legion"
+          subject         = OpenSSL::X509::Name.parse('/CN=legion-fallback-svid')
+          cert.subject    = subject
+          cert.issuer     = subject
+          cert.public_key = key
+
+          ext_factory = OpenSSL::X509::ExtensionFactory.new(cert, cert)
+          cert.add_extension(ext_factory.create_extension('subjectAltName', "URI:#{spiffe_id_str}", false))
+          cert.add_extension(ext_factory.create_extension('basicConstraints', 'CA:FALSE', true))
+          cert.sign(key, OpenSSL::Digest.new('SHA256'))
+
+          X509Svid.new(
+            spiffe_id:  Legion::Crypt::Spiffe.parse_id(spiffe_id_str),
+            cert_pem:   cert.to_pem,
+            key_pem:    key.private_to_pem,
+            bundle_pem: nil,
+            expiry:     cert.not_after
+          )
+        end
+
+        # --- Minimal protobuf decoder ---
+        # Only handles wire types 0 (varint) and 2 (length-delimited).
+
+        def extract_proto_field(bytes, field_number:)
+          pos = 0
+          while pos < bytes.bytesize
+            tag, consumed = decode_varint(bytes, pos)
+            pos          += consumed
+            wire_type     = tag & 0x07
+            field         = tag >> 3
+
+            case wire_type
+            when 0 # varint — skip
+              _, consumed = decode_varint(bytes, pos)
+              pos        += consumed
+            when 2 # length-delimited
+              len, consumed = decode_varint(bytes, pos)
+              pos          += consumed
+              data          = bytes.byteslice(pos, len)
+              pos          += len
+              return data if field == field_number
+            else
+              break # Unknown wire type — stop parsing
+            end
+          end
+          nil
+        end
+
+        def extract_proto_string(bytes, field_number:)
+          raw = extract_proto_field(bytes, field_number: field_number)
+          raw&.force_encoding('UTF-8')
+        end
+
+        alias extract_proto_bytes extract_proto_field
+
+        # Decode a protobuf varint starting at +start+ in +bytes+.
+        # Returns [decoded_value, bytes_consumed].
+        def decode_varint(bytes, start)
+          result  = 0
+          shift   = 0
+          current = start
+          loop do
+            byte = bytes.getbyte(current)
+            return [result, 0] if byte.nil?
+
+            current += 1
+            result  |= (byte & 0x7F) << shift
+            shift   += 7
+            break unless (byte & 0x80).nonzero?
+          end
+          [result, current - start]
+        end
+
+        # Extract the `exp` claim from the JWT payload without verifying the signature.
+        def extract_jwt_expiry(token)
+          parts = token.split('.')
+          return Time.now + 3600 unless parts.length >= 2
+
+          payload_json = Base64.urlsafe_decode64("#{parts[1]}==")
+          claims = begin
+            Legion::JSON.parse(payload_json)
+          rescue StandardError
+            {}
+          end
+          exp = claims['exp'] || claims[:exp]
+          exp ? Time.at(exp.to_i) : Time.now + 3600
+        rescue StandardError
+          Time.now + 3600
+        end
+
+        def log_warn(message)
+          Legion::Logging.warn(message) if defined?(Legion::Logging)
+        end
+      end
+    end
+  end
+end

data/lib/legion/crypt/spiffe.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require 'uri'
+require 'openssl'
+
+module Legion
+  module Crypt
+    module Spiffe
+      SPIFFE_SCHEME = 'spiffe'
+      DEFAULT_SOCKET_PATH = '/tmp/spire-agent/public/api.sock'
+      DEFAULT_TRUST_DOMAIN = 'legion.internal'
+      SVID_RENEWAL_RATIO   = 0.5
+
+      class Error < StandardError; end
+      class InvalidSpiffeIdError < Error; end
+      class WorkloadApiError < Error; end
+      class SvidError < Error; end
+
+      # Parsed representation of a SPIFFE ID.
+      # A SPIFFE ID has the form: spiffe://<trust-domain>/<workload-path>
+      SpiffeId = Struct.new(:trust_domain, :path) do
+        def to_s
+          "#{SPIFFE_SCHEME}://#{trust_domain}#{path}"
+        end
+
+        def ==(other)
+          other.is_a?(SpiffeId) && trust_domain == other.trust_domain && path == other.path
+        end
+      end
+
+      # Parsed X.509 SVID (SPIFFE Verifiable Identity Document).
+      X509Svid = Struct.new(:spiffe_id, :cert_pem, :key_pem, :bundle_pem, :expiry) do
+        def expired?
+          Time.now >= expiry
+        end
+
+        def valid?
+          !cert_pem.nil? && !key_pem.nil? && !expired?
+        end
+
+        # Seconds remaining until expiry (negative if already expired).
+        def ttl
+          expiry - Time.now
+        end
+      end
+
+      # Parsed JWT SVID.
+      JwtSvid = Struct.new(:spiffe_id, :token, :audience, :expiry) do
+        def expired?
+          Time.now >= expiry
+        end
+
+        def valid?
+          !token.nil? && !expired?
+        end
+      end
+
+      class << self
+        # Parse a SPIFFE ID string into a SpiffeId struct.
+        # Raises InvalidSpiffeIdError on malformed input.
+        def parse_id(spiffe_id_string)
+          raise InvalidSpiffeIdError, 'SPIFFE ID must be a non-empty string' if spiffe_id_string.nil? || spiffe_id_string.empty?
+
+          uri = URI.parse(spiffe_id_string)
+          validate_uri!(uri, spiffe_id_string)
+
+          SpiffeId.new(
+            trust_domain: uri.host,
+            path:         uri.path.empty? ? '/' : uri.path
+          )
+        rescue URI::InvalidURIError => e
+          raise InvalidSpiffeIdError, "Invalid SPIFFE ID '#{spiffe_id_string}': #{e.message}"
+        end
+
+        def valid_id?(spiffe_id_string)
+          parse_id(spiffe_id_string)
+          true
+        rescue InvalidSpiffeIdError
+          false
+        end
+
+        def enabled?
+          security = safe_security_settings
+          return false if security.nil?
+
+          spiffe = security[:spiffe] || security['spiffe']
+          return false if spiffe.nil?
+
+          spiffe[:enabled] || spiffe['enabled'] || false
+        end
+
+        def socket_path
+          security = safe_security_settings
+          return DEFAULT_SOCKET_PATH if security.nil?
+
+          spiffe = security[:spiffe] || security['spiffe'] || {}
+          spiffe[:socket_path] || spiffe['socket_path'] || DEFAULT_SOCKET_PATH
+        end
+
+        def trust_domain
+          security = safe_security_settings
+          return DEFAULT_TRUST_DOMAIN if security.nil?
+
+          spiffe = security[:spiffe] || security['spiffe'] || {}
+          spiffe[:trust_domain] || spiffe['trust_domain'] || DEFAULT_TRUST_DOMAIN
+        end
+
+        def workload_id
+          security = safe_security_settings
+          return nil if security.nil?
+
+          spiffe = security[:spiffe] || security['spiffe'] || {}
+          spiffe[:workload_id] || spiffe['workload_id']
+        end
+
+        private
+
+        def validate_uri!(uri, raw)
+          unless uri.scheme == SPIFFE_SCHEME
+            raise InvalidSpiffeIdError,
+                  "SPIFFE ID must use 'spiffe://' scheme, got '#{uri.scheme}://'"
+          end
+          raise InvalidSpiffeIdError, "SPIFFE ID missing trust domain in '#{raw}'" if uri.host.nil? || uri.host.empty?
+          return unless uri.userinfo || uri.port || (uri.query && !uri.query.empty?) || (uri.fragment && !uri.fragment.empty?)
+
+          raise InvalidSpiffeIdError, "SPIFFE ID must not contain userinfo, port, query, or fragment in '#{raw}'"
+        end
+
+        def safe_security_settings
+          return nil unless defined?(Legion::Settings)
+
+          Legion::Settings[:security]
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/legion/crypt/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Crypt
-    VERSION = '1.4.23'
+    VERSION = '1.4.25'
   end
 end

data/lib/legion/crypt.rb

@@ -14,6 +14,10 @@ require 'legion/crypt/token_renewer'
 require 'legion/crypt/helper'
 require 'legion/crypt/mtls'
 require 'legion/crypt/cert_rotation'
+require 'legion/crypt/spiffe'
+require 'legion/crypt/spiffe/workload_api_client'
+require 'legion/crypt/spiffe/svid_rotation'
+require 'legion/crypt/spiffe/identity_helpers'
 
 module Legion
   module Crypt
@@ -38,6 +42,20 @@ module Legion
         KerberosAuth.kerberos_principal
       end
 
+      def spiffe_svid
+        @svid_rotation&.current_svid
+      end
+
+      def fetch_svid
+        @workload_client ||= Spiffe::WorkloadApiClient.new
+        @workload_client.fetch_x509_svid
+      end
+
+      def fetch_jwt_svid(audience:)
+        @workload_client ||= Spiffe::WorkloadApiClient.new
+        @workload_client.fetch_jwt_svid(audience: audience)
+      end
+
       def start
         Legion::Logging.debug 'Legion::Crypt is running start'
         ::File.write('./legionio.key', private_key) if settings[:save_private_key]
@@ -50,6 +68,7 @@ module Legion
           connect_vault unless settings[:vault][:token].nil?
         end
         start_lease_manager
+        start_svid_rotation
       end
 
       def settings
@@ -96,6 +115,7 @@ module Legion
         stop_token_renewers
         shutdown_renewer
         close_sessions
+        stop_svid_rotation
       end
 
       private
@@ -154,6 +174,22 @@ module Legion
         @token_renewers.each(&:stop)
         @token_renewers.clear
       end
+
+      def start_svid_rotation
+        return unless Spiffe.enabled?
+
+        @svid_rotation = Spiffe::SvidRotation.new
+        @svid_rotation.start
+      rescue StandardError => e
+        Legion::Logging.warn "SPIFFE SvidRotation startup failed: #{e.message}" if defined?(Legion::Logging)
+      end
+
+      def stop_svid_rotation
+        return unless @svid_rotation
+
+        @svid_rotation.stop
+        @svid_rotation = nil
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-crypt
 version: !ruby/object:Gem::Version
-  version: 1.4.23
+  version: 1.4.25
 platform: ruby
 authors:
 - Esity
@@ -66,6 +66,7 @@ files:
 - ".github/workflows/ci.yml"
 - ".gitignore"
 - ".rubocop.yml"
+- AGENTS.md
 - CHANGELOG.md
 - CLAUDE.md
 - CODEOWNERS
@@ -90,6 +91,10 @@ files:
 - lib/legion/crypt/mtls.rb
 - lib/legion/crypt/partition_keys.rb
 - lib/legion/crypt/settings.rb
+- lib/legion/crypt/spiffe.rb
+- lib/legion/crypt/spiffe/identity_helpers.rb
+- lib/legion/crypt/spiffe/svid_rotation.rb
+- lib/legion/crypt/spiffe/workload_api_client.rb
 - lib/legion/crypt/tls.rb
 - lib/legion/crypt/token_renewer.rb
 - lib/legion/crypt/vault.rb