legion-crypt 1.5.38 → 1.5.42

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d7d1cbd214ebc5bc7f8d109b958e3d307e3a4faaa81fdb2c47b527670ab720f
-  data.tar.gz: 4ea67b85552ddae267d4945be1586e7248a30b3dc38dfa2f280ae59311524614
+  metadata.gz: bfa9ecbf9d8e83066a57605aa0535a3b529a0a43cfaf3bca6efef509a9d2754a
+  data.tar.gz: 8e9107d222b6c35bc269c9d8d52f3c356a64e42b76b8108f9139286e42daa1c3
 SHA512:
-  metadata.gz: 2af577b9a0c3c7e464e79f11bbd13e044d9e3e76520c2b4ee6ad27949135c0e873aa8aadfca33d67324061dd55d1f7f5f21ceb1715aa9a7d1d0f1fac77d74852
-  data.tar.gz: 4226e44bc08ebdc1928ce91630125db8e9a3c674e5ce64cf47ed7375706876388f9aeb3e93816402e41b10c0961bb7f19bd57dc6f64e826289333b27f558c36e
+  metadata.gz: 2a94e249cae525b2298465a0f9b2db67c16c75d517cd9a011675a63c63d532d3d128e671762847e32fc71fa18b9466883e7cfac0b12056260a6b22395e4b15e6
+  data.tar.gz: 511104bdfec4843ece4157715128f3d38a450194a401086f0626a8670cb0c27a62ca764e892eb4e6fd7cf28ada63c2c19c83e56000daf6d800113b20356a8085

data/.github/workflows/ci.yml

@@ -6,29 +6,56 @@ on:
   schedule:
     - cron: '0 9 * * 1'
 
+permissions: {}
+
 jobs:
   ci:
-    uses: LegionIO/.github/.github/workflows/ci.yml@main
+    permissions:
+      contents: read
+    uses: LegionIO/.github/.github/workflows/ci.yml@e0fc7364b73f446d4cb9bdc162a66ed34bf0daa7
+    with:
+      companion-gems: ${{ github.event_name == 'pull_request' && '{"legion-settings":{"repository":"LegionIO/legion-settings","ref":"8e73a9ef3c13958e3e1e7fc98532e41283159706"}}' || '{}' }}
 
   lint:
+    permissions:
+      checks: write
+      contents: read
+      pull-requests: read
     uses: LegionIO/.github/.github/workflows/lint-patterns.yml@main
 
   security:
-    uses: LegionIO/.github/.github/workflows/security-scan.yml@main
+    permissions:
+      contents: read
+      security-events: write
+    uses: LegionIO/.github/.github/workflows/security-scan.yml@e0fc7364b73f446d4cb9bdc162a66ed34bf0daa7
+    with:
+      companion-gems: ${{ github.event_name == 'pull_request' && '{"legion-settings":{"repository":"LegionIO/legion-settings","ref":"8e73a9ef3c13958e3e1e7fc98532e41283159706"}}' || '{}' }}
 
   version-changelog:
+    permissions:
+      contents: read
+      pull-requests: read
     uses: LegionIO/.github/.github/workflows/version-changelog.yml@main
 
   dependency-review:
+    permissions:
+      contents: read
+      pull-requests: write
     uses: LegionIO/.github/.github/workflows/dependency-review.yml@main
 
   stale:
     if: github.event_name == 'schedule'
+    permissions:
+      issues: write
+      pull-requests: write
     uses: LegionIO/.github/.github/workflows/stale.yml@main
 
   release:
     needs: [ci, lint]
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    permissions:
+      contents: write
+      packages: write
     uses: LegionIO/.github/.github/workflows/release.yml@main
     secrets:
-      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}
+      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}

data/.rspec

@@ -0,0 +1,2 @@
+--require ./spec/spec_helper
+--pattern spec/legion/**/*.rb

data/AGENTS.md

@@ -19,6 +19,7 @@ bundle exec rubocop
 - `lib/legion/crypt/jwt.rb`
 - `lib/legion/crypt/jwks_client.rb`
 - `lib/legion/crypt/vault.rb`
+- `lib/legion/crypt/vault/` — `Legion::Crypt::Vault::{Client, Cluster, Operation, Entity, JwtAuth, KerberosAuth, Renewer}`
 - `lib/legion/crypt/lease_manager.rb`
 - `lib/legion/crypt/token_renewer.rb`
 - `lib/legion/crypt/mtls.rb`
@@ -30,6 +31,7 @@ bundle exec rubocop
 - 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.
+- Vault components are nested under `Legion::Crypt::Vault`; core `Legion::Crypt::KerberosAuth` handles SPNEGO acquisition and `Legion::Crypt::TokenRenewer` remains outside that namespace.
 - Cryptographic defaults and key lifecycle behavior are contract-sensitive; change only with test coverage.
 
 ## Known Risks

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Legion::Crypt
 
+## [1.5.42] - 2026-11-08
+
+### Changed
+- Move Vault client, cluster routing, operation deadlines, entity management, JWT/Kerberos authentication, and the legacy renewal actor into `lib/legion/crypt/vault/` with matching `Legion::Crypt::Vault::*` namespaces.
+- Update library consumers, specs, and current documentation to the nested require paths and constants; remove the old flat paths without compatibility aliases. Core SPNEGO acquisition and `TokenRenewer` remain in their existing locations.
+- Mirror implementation paths and literal filenames under `spec/`, consolidating root Crypt API examples without dropping coverage. Configure RSpec discovery for the mirrored layout and prioritize `lib/` on the load path to prevent spec files from shadowing production requires.
+
+## [1.5.41] - 2026-11-07
+
+### Fixed
+- Propagate programming errors from Vault connectivity, bootstrap credential acquisition/revocation, lease and SPIFFE startup orchestration, and mTLS interface discovery instead of concealing them as disconnected or fallback states.
+- Handle declared operational failures through structured warning-level exceptions without duplicate raw exception logs; report invalid SPIFFE IDs at warning level.
+
+### Changed
+- Accept extra keyword context on touched startup, credential, and SVID APIs and fully qualify sibling Crypt constants. Preserve mode-specific credential selection and certificate SAN/TTL behavior; fixed role mappings remain frozen constants.
+
+## [1.5.40] - 2026-11-07
+
+### Fixed
+- Use direct core settings reads for Vault connectivity, lease startup, JWT operations, and mTLS PKI paths; remove settings-only JWT/PKI accessors and preserve complete, isolated defaults in their specs.
+- Exercise the real `legion-settings` dependency throughout specs, including resolver and loader rebuild behavior; isolate mutable settings between examples instead of mocking the dependency.
+
+## [1.5.39] - 2026-11-01
+
+### Fixed
+- Read crypto runtime configuration from live `Legion::Settings` instead of fallback settings wrappers; register Crypt defaults at boot and require Settings >= 1.4.2 without changing lease-reference publication.
+- Honor live JWT verification flags, key-derivation configuration, Vault operation budgets, and mTLS/SPIFFE policy; reject invalid renewal windows rather than silently substituting defaults. Vault environment tokens supply boot defaults only, never overwrite explicit runtime configuration.
+
 ## [1.5.38] - 2026-10-31
 
 ### Fixed

data/CLAUDE.md

@@ -1,216 +1,88 @@
-# legion-crypt: Encryption and Vault Integration for LegionIO
+# legion-crypt
 
-**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
-**Version**: 1.5.7
-**License**: Apache-2.0
+Core encryption, secrets management, JWT, and HashiCorp Vault integration for LegionIO. Follow [LegionIO coding standards](../docs/legionio-standards.md); this file adds Crypt-specific guidance.
 
 ## 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
-│   ├── .verify_with_jwks  # Verify RS256 token via external JWKS endpoint (Entra ID, etc.)
-│   └── .decode        # Decode without verification (inspection)
-│
-├── JwksClient         # External JWKS endpoint integration (thread-safe)
-│   ├── .fetch_keys    # Fetch and parse JWKS from a URL
-│   ├── .find_key      # Lookup key by kid (cache-first, re-fetch on miss)
-│   └── .clear_cache   # Clear the key cache
-│
-├── ClusterSecret      # Cluster-wide shared secret management
-│   └── .cs            # Generate/distribute cluster secret
-│
-├── 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
-├── Ed25519            # Ed25519 key generation, signing, verification, Vault storage
-├── PartitionKeys      # HKDF per-tenant key derivation, AES-256-GCM encrypt/decrypt
-├── Erasure            # Cryptographic erasure via Vault master key deletion
-├── Attestation        # Signed identity claims with Ed25519, freshness checking
-├── LeaseManager       # Dynamic Vault lease lifecycle: fetch, cache, renew, rotate, push-back
-├── KerberosAuth       # GSSAPI SPNEGO token acquisition; `disable_gssapi_finalizers` prevents GC segfault on macOS
-├── VaultKerberosAuth  # Vault Kerberos auth: SPNEGO as `Authorization` header, namespace clear/restore, TokenRenewer wiring
-├── LdapAuth           # Vault LDAP auth backend
-├── Tls                # TLS settings (cert/key/CA/verify_peer/Vault PKI)
-├── Mtls               # mTLS cert issuance (Vault PKI) + CertRotation background thread (50% TTL renewal)
-├── TokenRenewer       # Background renewal thread: 75% TTL renew, Kerberos re-auth on failure, exponential backoff
-├── Spiffe             # SPIFFE identity support: parse_id, valid_id?, X509Svid, JwtSvid structs; reads security.spiffe settings
-├── Spiffe::IdentityHelpers  # Mixin for SPIFFE identity operations
-├── Spiffe::SvidRotation     # Background SVID renewal at 50% TTL
-├── Spiffe::WorkloadApiClient # gRPC workload API client for SPIRE agent (unix socket)
-├── VaultEntity        # Vault entity/alias lifecycle (ensure_entity, ensure_alias, find_by_name); all non-fatal
-├── MockVault          # In-memory Vault mock for local development mode
-├── Settings           # Default crypt config
-└── Version
+Legion::Crypt
+├── Cipher          # AES-256-GCM encryption; legacy CBC decryption; RSA key pair
+├── Vault           # read/write/connect/session renewal through Vault::Client
+│   ├── Client      # core-owned HTTP client using Faraday and Legion::JSON
+│   ├── Cluster     # client selection, caching, authentication grant publication
+│   ├── Operation   # bounded operations and shared shutdown deadlines
+│   ├── Entity      # entity and alias lookup
+│   ├── JwtAuth     # .login / .login! / .worker_login
+│   ├── KerberosAuth # SPNEGO as Authorization header; preserves namespace
+│   └── Renewer     # legacy Every actor for session renewal
+├── JWT             # issue/verify/decode (HS256 cluster-secret or RS256 RSA)
+├── JwksClient      # external JWKS endpoint, 1hr TTL cache, thread-safe
+├── ClusterSecret   # shared AES key distributed across nodes
+├── LeaseManager    # dynamic Vault lease lifecycle
+├── KerberosAuth    # SPNEGO acquisition through the optional lex-kerberos helper
+├── LdapAuth        # cluster-scoped LDAP login and token maintenance
+├── TokenRenewer    # 75% TTL renewal; Kerberos-only re-auth; retry backoff
+├── Ed25519         # key gen, sign, verify, Vault storage
+├── PartitionKeys   # HKDF per-tenant key derivation, AES-256-GCM
+├── TLS             # TLS configuration and Vault-backed material resolution
+├── Mtls            # Vault PKI certificate issuance using crypt.mtls settings
+├── CertRotation    # background renewal using the configured renewal window
+├── Spiffe          # SPIFFE ID parse/validate, X509Svid/JwtSvid, SPIRE workload API
+├── Attestation     # signed identity claims with Ed25519
+├── Erasure         # cryptographic erasure via Vault master key deletion
+└── MockVault       # in-memory mock for local dev
 ```
 
-### 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
-- **JWKS External Validation**: `JwksClient` fetches public keys from external identity provider JWKS endpoints (Entra ID, Bot Framework). Keys cached for 1 hour (CACHE_TTL=3600s), thread-safe via Mutex, automatic re-fetch on cache miss handles key rotation
-
-## Default Settings
-
-```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
-}
-```
+Vault components live under `lib/legion/crypt/vault/`: `client.rb`, `cluster.rb`, `operation.rb`, `entity.rb`, `jwt_auth.rb`, `kerberos_auth.rb`, and `renewer.rb`. Core `KerberosAuth` and `TokenRenewer` remain directly under `Legion::Crypt`.
 
-## Dependencies
-
-| Gem | Purpose |
-|-----|---------|
-| `ed25519` (~> 1.3) | Ed25519 key operations (pure Ruby) |
-| `jwt` (>= 2.7) | JSON Web Token encoding/decoding |
-| `vault` (>= 0.17) | HashiCorp Vault Ruby client |
-
-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/verify_with_jwks operations |
-| `lib/legion/crypt/jwks_client.rb` | JWKS endpoint fetch, parse, cache (thread-safe, 1hr TTL) |
-| `lib/legion/crypt/vault.rb` | Vault read/write/connect/renew operations |
-| `lib/legion/crypt/cluster_secret.rb` | Cluster-wide shared secret management |
-| `lib/legion/crypt/vault_jwt_auth.rb` | Vault JWT auth backend: `.login`, `.login!`, `.worker_login`; raises `AuthError` on failure |
-| `lib/legion/crypt/vault_renewer.rb` | Background Vault token renewal |
-| `lib/legion/crypt/lease_manager.rb` | Dynamic Vault lease lifecycle management |
-| `lib/legion/crypt/settings.rb` | Default configuration |
-| `lib/legion/crypt/ed25519.rb` | Ed25519 key generation, signing, verification, Vault storage |
-| `lib/legion/crypt/partition_keys.rb` | HKDF per-tenant key derivation with AES-256-GCM |
-| `lib/legion/crypt/erasure.rb` | Cryptographic erasure via Vault master key deletion |
-| `lib/legion/crypt/attestation.rb` | Signed identity claims with Ed25519 signatures |
-| `lib/legion/crypt/kerberos_auth.rb` | GSSAPI/Kerberos token acquisition; `obtain_spnego_token`, `disable_gssapi_finalizers` (prevents GC segfault on macOS) |
-| `lib/legion/crypt/vault_kerberos_auth.rb` | Vault Kerberos auth backend: sends SPNEGO token as `Authorization` HTTP header, clears/restores namespace, wires `TokenRenewer` |
-| `lib/legion/crypt/ldap_auth.rb` | Vault LDAP auth backend integration |
-| `lib/legion/crypt/tls.rb` | TLS settings module (cert, key, CA paths, verify_peer, Vault PKI flag) |
-| `lib/legion/crypt/mtls.rb` | mTLS certificate issuance from Vault PKI; `CertRotation` background renewal thread (50% TTL) |
-| `lib/legion/crypt/token_renewer.rb` | Plain Thread renewer: renews at 75% TTL, re-auths via Kerberos on failure, exponential backoff |
-| `lib/legion/crypt/spiffe.rb` | SPIFFE identity: parse/validate SPIFFE IDs, X509Svid/JwtSvid structs, settings helpers |
-| `lib/legion/crypt/spiffe/identity_helpers.rb` | Mixin for SPIFFE identity operations |
-| `lib/legion/crypt/spiffe/svid_rotation.rb` | Background SVID renewal thread (50% TTL) |
-| `lib/legion/crypt/spiffe/workload_api_client.rb` | gRPC workload API client for SPIRE agent |
-| `lib/legion/crypt/vault_entity.rb` | Vault entity/alias lifecycle: `ensure_entity`, `ensure_alias`, `find_by_name`; all operations non-fatal |
-| `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
-5. External token verification for identity providers (Entra ID OIDC via JWKS)
-
-### Vault JWT Auth Usage
+## Key Design Decisions
 
-```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: {} }
+- RSA keys are memoized per process. `read_private_key` loads an existing `./legionio.key`; otherwise a key is generated. `save_private_key` persists it with owner-only permissions.
+- HS256 (cluster secret) for intra-cluster tokens; RS256 (RSA keypair) for externally-verifiable tokens
+- `JwksClient` caches keys for one hour, shares concurrent refreshes, and throttles repeated unknown-key refreshes.
+- Vault connectivity uses the core client; the `vault` gem is not required. Kerberos SPNEGO acquisition requires the optional `lex-kerberos` helper, and authentication preserves the configured Vault namespace.
+- JWT/LDAP token renewal never falls back to Kerberos. Expiry or terminal rejection requires login again; Kerberos grants alone can automatically reauthenticate.
 
-# Authenticate and set Vault client token in one step
-Legion::Crypt::VaultJwtAuth.login!(jwt: token)
+## Framework Contracts
 
-# 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')
-```
+- Defaults live in `lib/legion/crypt/settings.rb` and are registered when `legion/crypt` is required. Core code reads `Legion::Settings[:crypt][...]` directly: no settings-only accessor wrappers, duplicated defaults, or nil guards around registered keys.
+- mTLS uses `crypt.mtls`; SPIFFE still reads the optional Core-owned `security.spiffe` section. Do not treat the two settings paths as interchangeable.
+- Include `Legion::Logging::Helper` explicitly in core modules/classes that need logging. Rescues must re-raise or call `handle_exception` at `:warn` or higher. Programming errors must propagate; narrow recovery to known operational failures.
+- Use fully qualified Legion constants across module boundaries. New public APIs use kwargs and trailing `**`; preserve existing positional contracts unless all callers are migrated.
+- Use `Legion::JSON.load` / `dump`; loaded JSON has symbol keys. Never log tokens, passwords, private keys, or decrypted plaintext.
+- `start(mode: nil, **)` selects `postgresql/creds/infra` for an existing `postgresql` lease in infra mode without mutating configured leases. Fixed mode-to-role mappings remain frozen constants.
+- `Legion::Crypt::Mtls.issue_cert(common_name:, alt_names: '', ttl: nil, **)` preserves explicit SAN/TTL inputs; absent TTL uses the registered default. Interface-discovery programming errors must not become loopback fallback.
+- Preserve bounded shutdown, lease ownership, and generation checks: late worker results must not reinstall credentials after shutdown.
 
-Vault prerequisites: `vault auth enable jwt` + configure `auth/jwt/config` with JWKS URL or bound issuer.
+## Specs and Verification
 
-### JWT Usage
+- Mirror literal library paths and filenames in specs: `lib/legion/crypt/vault/client.rb` maps to `spec/legion/crypt/vault/client.rb`, not an `_spec.rb` file. Keep examples with the implementation they exercise; root Crypt API groups share `spec/legion/crypt.rb`.
+- `.rspec` discovers `spec/legion/**/*.rb` and explicitly loads `spec/spec_helper.rb`. Preserve `lib/` precedence over `spec/` on `$LOAD_PATH` to prevent mirrored files from shadowing production requires. Keep support files outside the discovered tree.
+- Require and use gemspec dependencies; do not mock them. In particular, never stub `Legion::Settings`, its loader, resolver, or returned settings hashes.
+- `spec/spec_helper.rb` loads the real Settings/Resolver, isolates the settings root, installs full Crypt defaults for each example, and restores the original state afterward.
+- Configure values through real bracket access or `Legion::Settings.set_prop`. Replacement Crypt configurations must retain full defaults, including nested Vault settings. Raw loader-root mutation is permitted in test setup for publication/rebuild scenarios, not as a new production access pattern.
+- Prefer real libraries and local service fixtures or supported test adapters at external I/O boundaries. Cover behavior, failure propagation, and state transitions rather than forwarding calls or implementation details.
 
-```ruby
-# Convenience methods (auto-selects keys from settings)
-token = Legion::Crypt.issue_token({ node_id: 'abc' }, ttl: 3600)
-claims = Legion::Crypt.verify_token(token)
+Run from this checkout:
 
-# 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
+```bash
+bundle exec rubocop -A
+bundle exec rspec --format json --out tmp/rspec_results.json --format progress --out tmp/rspec_progress.txt
 ```
 
-**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.
-
-### External Token Verification (JWKS)
+Use the full suite. After lint autocorrections, verify the corrected code; read failure details from the JSON report if specs fail.
 
-Verify tokens from external identity providers using their public JWKS endpoints:
+## JWT Usage
 
 ```ruby
-# Convenience method
-claims = Legion::Crypt.verify_external_token(
-  token,
+token  = Legion::Crypt.issue_token({ node_id: 'abc' }, ttl: 3600)
+claims = Legion::Crypt.verify_token(token)
+
+# External provider (Entra ID)
+claims = Legion::Crypt.verify_external_token(token,
   jwks_url: 'https://login.microsoftonline.com/TENANT/discovery/v2.0/keys',
   issuers:  ['https://login.microsoftonline.com/TENANT/v2.0'],
-  audience: 'app-client-id'
-)
-
-# Direct module usage
-claims = Legion::Crypt::JWT.verify_with_jwks(token, jwks_url: jwks_url)
+  audience: 'app-client-id')
 ```
 
-**Flow:** decode JWT header (unverified) to extract `kid` -> `JwksClient.find_key` fetches the matching public key from cache or JWKS endpoint -> verify JWT signature with the public key.
-
-**Options:** `issuers:` (array, multi-issuer support), `audience:` (string), `verify_expiration:` (bool, default true).
-
-**Error hierarchy:** `ExpiredTokenError`, `InvalidTokenError` (bad signature, wrong issuer, wrong audience), `DecodeError` (malformed token) — all inherit from `Legion::Crypt::JWT::Error`.
-
-**Used by:** `lex-identity` Entra runner for Digital Worker OIDC token validation.
-
----
-
-**Maintained By**: Matthew Iverson (@Esity)
+Error hierarchy: `ExpiredTokenError`, `InvalidTokenError`, `DecodeError` — all inherit `Legion::Crypt::JWT::Error`.

data/CODEOWNERS

@@ -11,9 +11,9 @@
 
 # Vault integration
 # lib/legion/crypt/vault.rb @Esity @future-security-team
-# lib/legion/crypt/vault_jwt_auth.rb @Esity @future-security-team
-# lib/legion/crypt/vault_renewer.rb @Esity @future-security-team
-# lib/legion/crypt/vault_cluster.rb @Esity @future-security-team
+# lib/legion/crypt/vault/jwt_auth.rb @Esity @future-security-team
+# lib/legion/crypt/vault/renewer.rb @Esity @future-security-team
+# lib/legion/crypt/vault/cluster.rb @Esity @future-security-team
 # lib/legion/crypt/lease_manager.rb @Esity @future-security-team
 
 # JWT and JWKS
@@ -22,7 +22,7 @@
 
 # Auth integrations
 # lib/legion/crypt/ldap_auth.rb @Esity @future-security-team
-# lib/legion/crypt/vault_kerberos_auth.rb @Esity @future-security-team
+# lib/legion/crypt/vault/kerberos_auth.rb @Esity @future-security-team
 
 # Cluster secret
 # lib/legion/crypt/cluster_secret.rb @Esity @future-security-team

data/Gemfile

@@ -4,6 +4,7 @@ source 'https://rubygems.org'
 
 gemspec
 group :test do
+  gem 'legionio', '~> 1.9.52', require: false
   gem 'rake'
   gem 'rspec'
   gem 'rspec_junit_formatter'
@@ -12,4 +13,6 @@ group :test do
   gem 'simplecov'
 end
 gem 'legion-logging'
-gem 'legion-settings'
+companion_root = File.directory?(File.expand_path('.ci-dependencies', __dir__)) ? '.ci-dependencies' : '..'
+settings_path = File.expand_path("#{companion_root}/legion-settings", __dir__)
+gem 'legion-settings', **(File.directory?(settings_path) ? { path: settings_path } : {})

data/README.md

@@ -26,6 +26,10 @@ 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.
 
+`Legion::Crypt.start(mode: nil, **)` accepts extra keyword context. With `mode: :infra`, an existing PostgreSQL lease uses `postgresql/creds/infra` without mutating its configured path; other modes preserve the configured path. The mode-to-role mapping is a fixed framework convention, not an operator setting.
+
+Vault connectivity inspection propagates errors rather than reporting broken configuration as disconnected. Startup orchestration and bootstrap credential handling recover only from their declared operational failures, using `handle_exception` at warning level; programming errors propagate to callers.
+
 ### 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.
@@ -72,10 +76,16 @@ Public keys are cached for 1 hour. Concurrent misses for one URL share a refresh
 
 ## Configuration
 
+Crypt requires `legion-settings` >= 1.4.2. Requiring `legion/crypt` registers its defaults once; runtime reads use the live `Legion::Settings[:crypt]` tree, including replacement trees and request overlays. The partial configuration example below shows the `crypt` section; `lib/legion/crypt/settings.rb` is the authoritative source for all defaults. Configure it through `Legion::Settings`, not the removed `Legion::Crypt.settings`, `.vault_settings`, or `.jwt_settings` accessors. `VAULT_DEV_ROOT_TOKEN_ID` and `VAULT_TOKEN_ID` provide boot defaults; they do not overwrite an explicit live Vault token.
+
+`crypt.mtls` owns the mTLS defaults registered by this gem. Certificate issuance reads `Legion::Settings[:crypt][:mtls][:vault_pki_path]` directly; the `Legion::Crypt::Mtls.pki_path` accessor is removed. `security.spiffe` remains Core-owned optional configuration with its existing absent-field defaults. Explicit false policy is never replaced by a truthy fallback. Renewal windows must be finite numbers from zero (inclusive) to one (exclusive).
+
+After an explicit full `Legion::Settings.reset!`, standalone callers and tests must bootstrap again with `Legion::Settings.register_library(:crypt, Legion::Crypt::Settings.default)` before using configured crypto APIs. Runtime reads do not repair missing registration. Lease binding transactions and credential publication continue to mutate their intended raw settings roots, not request-overlay copies.
+
 ```json
 {
   "vault": {
-    "enabled": false,
+    "enabled": true,
     "protocol": "http",
     "address": "localhost",
     "port": 8200,
@@ -84,8 +94,8 @@ Public keys are cached for 1 hour. Concurrent misses for one URL share a refresh
     "renewer_time": 5,
     "renewer": true,
     "operation_timeout": 5,
-    "push_cluster_secret": true,
-    "read_cluster_secret": true,
+    "push_cluster_secret": false,
+    "read_cluster_secret": false,
     "kv_path": "legion",
     "leases": {}
   },
@@ -97,6 +107,12 @@ Public keys are cached for 1 hour. Concurrent misses for one URL share a refresh
     "verify_expiration": true,
     "verify_issuer": true
   },
+  "mtls": {
+    "enabled": false,
+    "vault_pki_path": "pki/issue/legion-internal",
+    "cert_ttl": "24h",
+    "renewal_window": 0.5
+  },
   "cs_encrypt_ready": false,
   "dynamic_keys": true,
   "cluster_secret": null,
@@ -114,9 +130,9 @@ Public keys are cached for 1 hour. Concurrent misses for one URL share a refresh
 
 ### Vault Integration
 
-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.
+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::Vault::Client`, 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:
+`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:
 
 ```ruby
 client = Legion::Crypt.vault_client
@@ -143,15 +159,17 @@ The `LeaseManager` handles dynamic secrets from any Vault secrets engine (databa
   "crypt": {
     "vault": {
       "leases": {
-        "rabbitmq": { "path": "rabbitmq/creds/legion-role" },
-        "bedrock":  { "path": "aws/creds/bedrock-role" },
-        "postgres": { "path": "database/creds/apollo-rw" }
+        "rabbitmq":   { "path": "rabbitmq/creds/legion-role" },
+        "bedrock":    { "path": "aws/creds/bedrock-role" },
+        "postgresql": { "path": "postgresql/creds/node" }
       }
     }
   }
 }
 ```
 
+`postgresql` is the lease name recognized by `Legion::Crypt.start(mode: :infra)` for role selection. Other lease names retain their configured paths.
+
 Other settings files reference lease data using `lease://name#key`:
 
 ```json
@@ -193,7 +211,7 @@ Release Crypt before Settings. Older `register_ref` callers remain supported, bu
 
 ## Multi-Cluster Vault
 
-`VaultCluster` supports connecting to multiple Vault clusters simultaneously. Each cluster has its own `Legion::Crypt::VaultClient` instance.
+`Legion::Crypt::Vault::Cluster` supports connecting to multiple Vault clusters simultaneously. Each cluster has its own `Legion::Crypt::Vault::Client` 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.
 
@@ -245,8 +263,7 @@ JWT and Kerberos `login!` use the same grant lifecycle: token, TTL, expiry, rene
 
 When `crypt.vault.auth_method` is set to `kerberos`, `Crypt.start` performs Kerberos auto-auth to Vault using `KerberosAuth`:
 
-```ruby
-# Settings
+```json
 {
   "crypt": {
     "vault": {
@@ -262,29 +279,56 @@ 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). 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.
+`Legion::Crypt::TokenRenewer` renews renewable tokens at 75% TTL and retries transient failures with backoff. Only Kerberos-authenticated grants can reauthenticate through Kerberos. JWT and LDAP grants require another login after expiry or terminal rejection.
 
 ## 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`.
+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 `Legion::Crypt::Spiffe::SvidError`.
 
 ## mTLS
 
-`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.
+`Legion::Crypt::Mtls` issues mTLS certificates from Vault PKI using `crypt.mtls` configuration. `issue_cert(common_name:, alt_names: '', ttl: nil, **)` preserves caller-supplied SANs and TTL overrides while accepting extra keyword context. `Legion::Crypt::CertRotation` renews at expiry minus the certificate lifetime multiplied by `crypt.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.
+`Legion::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
+- `concurrent-ruby` (~> 1.3)
 - `ed25519` (~> 1.3)
 - `jwt` gem (>= 2.7)
 - `faraday` gem (~> 2.0)
 - `legion-json` gem (>= 1.2.0; JSON 3 supported)
+- `legion-logging` (>= 1.5.0)
+- `legion-settings` (>= 1.4.2)
 - HashiCorp Vault (optional, for secrets management)
-- `gssapi` gem (optional, required for Kerberos auth)
+- `lex-kerberos` (optional, supplies the SPNEGO helper for Kerberos auth)
+
+## Development
+
+Use the existing checkout and the full repository checks:
+
+```bash
+bundle install
+bundle exec rubocop -A
+bundle exec rspec --format json --out tmp/rspec_results.json --format progress --out tmp/rspec_progress.txt
+```
+
+Run specs against the corrected code if RuboCop changes files. On failure, inspect the failing examples in `tmp/rspec_results.json`; do not substitute a narrower suite for the full check.
+
+Specs mirror implementation paths and filenames exactly: `lib/legion/crypt/vault/client.rb` is covered by `spec/legion/crypt/vault/client.rb`, without an `_spec` suffix. Keep each spec focused on its corresponding implementation; startup, JWT convenience, and credential-scoping groups belong in `spec/legion/crypt.rb`.
+
+`.rspec` explicitly loads `spec/spec_helper.rb` and discovers `spec/legion/**/*.rb`. The helper puts `lib/` ahead of `spec/` on Ruby's load path so production requires cannot resolve to mirrored spec files. Keep support files outside the discovered implementation-spec tree.
+
+Require and use real gemspec dependencies rather than mocking them. `spec/spec_helper.rb` requires `legion-settings` and its resolver, isolates the settings root, and installs complete Crypt defaults for each example. The original settings state is restored afterward, including when an example replaces the loader root.
+
+The test bundle also declares `legionio` for the legacy `Vault::Renewer` specs. Isolated Ruby subprocesses exercise the real periodic actor, cancellation lifecycle, and Vault HTTP client against a local service fixture without loading optional Core/transport components into unrelated examples. This is a development/test dependency only; Crypt's runtime gemspec does not depend on Core, and no running Vault service is required.
+
+Set individual properties through `Legion::Settings[:crypt][...]`. For replacement-tree scenarios, start from `Legion::Crypt::Settings.default`, modify the needed nested properties, then install it with `Legion::Settings.set_prop(:crypt, configuration)`. Do not replace nested defaults with partial hashes, or stub Settings, its loader, resolver, or returned settings hashes. Keep settings changes within the example lifecycle.
+
+Use real libraries with local service fixtures or supported test adapters for external I/O. Preserve security-sensitive behavior: test failure propagation and lifecycle transitions, never expose secrets in test output.
 
 ## License
 

data/legion-crypt.gemspec

@@ -31,4 +31,5 @@ Gem::Specification.new do |spec|
   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 'legion-settings', '>= 1.4.2'
 end