legionio 1.4.62 → 1.4.63

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c95080366554474379f7f8ad23dac75cc86125bfbd1081494f9c7a7d9bdde02
-  data.tar.gz: 8e47342c47b50b7040456f83d46a0ba1fdd4bbe4d28315e3ea16acb5649c7a34
+  metadata.gz: 577e7caee9c14f38ce12e36d35f8a92fe4d66d33c7d62dbde89c8581575dc961
+  data.tar.gz: 0165ac8ccd3b32b48cce36a7188669ceb4254b344be99243a1e08fca77235a9f
 SHA512:
-  metadata.gz: f29c940730a19e2119b343da7022511b08691d752af0663669880ad0b1cfcd8d3f5606abe14a215e7222d5cb4cc8bb7fd905c19b7035dfda275beae38bc55aa1
-  data.tar.gz: 064c2b10a5d6c94b54e70fcb54275bf49026aea5b678087dc387d54613703c3cd473d51ce62671d1340d7c41b9e471eaee49a317965693eb5c1b47d086237c64
+  metadata.gz: 8192110eaf2b6f11cc38852448feade2999655706c657f2ed0ff78cd8fe698994c78443f90444d4ea0510060d66d6f679ebd6f58a9f9b46d42ef66352413434f
+  data.tar.gz: e807e335d274d228fac57bd6761380af2508f5c98cb40b8d4285ae9da9740cd10b1b592b3d3cad21e6a961f9f8cda05196fb5a35dee0a0ae18d6a6b969ddeb7f

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Legion Changelog
 
+## [1.4.63] - 2026-03-18
+
+### Added
+- `legionio config import SOURCE` command for importing config from URL or local file
+- Supports raw JSON and base64-encoded JSON payloads
+- Deep merges with existing `~/.legionio/settings/imported.json` (or `--force` to overwrite)
+- Displays imported sections and vault cluster count
+
 ## [1.4.62] - 2026-03-18
 
 ### Added

data/docs/plans/2026-03-18-config-import-vault-multicluster-design.md

@@ -0,0 +1,272 @@
+# Config Import + Multi-Cluster Vault Design
+
+## Problem
+
+LegionIO currently supports a single Vault cluster (`crypt.vault.address/port/token`). In enterprise environments, engineers work with multiple Vault clusters (dev, test, stage, production) and need different tokens for each. There's also no way to bootstrap a new developer's environment from a shared config — they must manually create JSON files in `~/.legionio/settings/`.
+
+## Solution
+
+Three changes across three repos:
+
+### 1. legion-crypt: Multi-Cluster Vault Support
+
+Upgrade `crypt.vault` from a single cluster to a named clusters hash with a `default` pointer.
+
+#### Settings Schema
+
+```json
+{
+  "crypt": {
+    "vault": {
+      "default": "prod",
+      "clusters": {
+        "dev": {
+          "address": "vault-dev.example.com",
+          "port": 8200,
+          "protocol": "https",
+          "namespace": "myapp",
+          "token": null,
+          "auth_method": "ldap"
+        },
+        "stage": {
+          "address": "vault-stage.example.com",
+          "port": 8200,
+          "protocol": "https",
+          "namespace": "myapp",
+          "token": null,
+          "auth_method": "ldap"
+        },
+        "prod": {
+          "address": "vault.example.com",
+          "port": 8200,
+          "protocol": "https",
+          "namespace": "myapp",
+          "token": null,
+          "auth_method": "ldap"
+        }
+      }
+    }
+  }
+}
+```
+
+#### Backward Compatibility
+
+If `crypt.vault.clusters` is absent but `crypt.vault.address` is present, treat it as a single unnamed cluster (current behavior). The migration path is:
+
+```ruby
+# Old style (still works)
+Legion::Settings[:crypt][:vault][:address]  # => "vault.example.com"
+
+# New style
+Legion::Crypt.cluster(:prod)    # => cluster config hash
+Legion::Crypt.cluster            # => default cluster config hash
+Legion::Crypt.default_cluster    # => "prod"
+```
+
+#### New Module: `Legion::Crypt::VaultCluster`
+
+Manages per-cluster Vault connections:
+
+```ruby
+module Legion::Crypt
+  module VaultCluster
+    # Get a configured ::Vault client for a named cluster
+    def vault_client(name = nil)
+      name ||= default_cluster_name
+      @vault_clients ||= {}
+      @vault_clients[name] ||= build_client(clusters[name])
+    end
+
+    # Cluster config hash
+    def cluster(name = nil)
+      name ||= default_cluster_name
+      clusters[name]
+    end
+
+    def default_cluster_name
+      vault_settings[:default] || clusters.keys.first
+    end
+
+    def clusters
+      vault_settings[:clusters] || {}
+    end
+
+    # Connect to all clusters that have tokens
+    def connect_all
+      clusters.each do |name, config|
+        next unless config[:token]
+        connect_cluster(name)
+      end
+    end
+
+    private
+
+    def build_client(config)
+      client = ::Vault::Client.new(
+        address: "#{config[:protocol]}://#{config[:address]}:#{config[:port]}",
+        token:   config[:token]
+      )
+      client.namespace = config[:namespace] if config[:namespace]
+      client
+    end
+  end
+end
+```
+
+#### New Module: `Legion::Crypt::LdapAuth`
+
+LDAP authentication against Vault's LDAP auth method (HTTP API, no vault CLI):
+
+```ruby
+module Legion::Crypt
+  module LdapAuth
+    # Authenticate to a single cluster via LDAP
+    # POST /v1/auth/ldap/login/:username
+    # Returns: { token:, lease_duration:, renewable:, policies: }
+    def ldap_login(cluster_name:, username:, password:)
+      client = vault_client(cluster_name)
+      # Or raw HTTP if ::Vault gem doesn't expose ldap auth:
+      response = client.post("/v1/auth/ldap/login/#{username}", password: password)
+      token = response.auth.client_token
+      # Store token in cluster config (in-memory only, not written to disk with password)
+      clusters[cluster_name][:token] = token
+      clusters[cluster_name][:connected] = true
+      { token: token, lease_duration: response.auth.lease_duration,
+        renewable: response.auth.renewable, policies: response.auth.policies }
+    end
+
+    # Authenticate to ALL configured clusters with same credentials
+    def ldap_login_all(username:, password:)
+      results = {}
+      clusters.each do |name, config|
+        next unless config[:auth_method] == 'ldap'
+        results[name] = ldap_login(cluster_name: name, username: username, password: password)
+      rescue StandardError => e
+        results[name] = { error: e.message }
+      end
+      results
+    end
+  end
+end
+```
+
+#### Existing Code Changes
+
+- `Legion::Crypt.start` — if `clusters` present, call `connect_all` instead of `connect_vault`
+- `Legion::Crypt::Vault.read/write/get` — route through `vault_client(name)` for cluster-aware reads
+- `Legion::Crypt::Vault.connect_vault` — still works for legacy single-cluster config
+- `Legion::Crypt::VaultRenewer` — renew tokens for ALL connected clusters
+- `Legion::Settings::Resolver` — `vault://` refs gain optional cluster prefix: `vault://prod/secret/data/myapp#password` (falls back to default cluster if no prefix)
+
+### 2. LegionIO: `legion config import` / `legionio config import` CLI Command
+
+New subcommand under `Config`:
+
+```
+legionio config import <source>     # URL or local file path
+legion config import <source>       # same command available in interactive binary
+```
+
+#### Behavior
+
+1. **Fetch source:**
+   - If `source` starts with `http://` or `https://` — HTTP GET, follow redirects
+   - Otherwise — read local file
+2. **Decode payload:**
+   - Try `JSON.parse(body)` first
+   - If that fails, try `JSON.parse(Base64.decode64(body))`
+   - If both fail, error with "not valid JSON or base64-encoded JSON"
+3. **Validate structure:**
+   - Must be a Hash
+   - Warn on unrecognized top-level keys (not in known settings keys)
+4. **Write to `~/.legionio/settings/imported.json`:**
+   - Deep merge with existing imported.json if present
+   - Or overwrite with `--force`
+5. **Display summary:**
+   - Which settings sections were imported (crypt, transport, cache, etc.)
+   - How many vault clusters configured
+   - Remind user to run `legion` for onboarding vault auth
+
+#### Example Config File
+
+```json
+{
+  "crypt": {
+    "vault": {
+      "default": "prod",
+      "clusters": {
+        "dev":   { "address": "vault-dev.uhg.com",   "port": 8200, "protocol": "https", "auth_method": "ldap" },
+        "test":  { "address": "vault-test.uhg.com",  "port": 8200, "protocol": "https", "auth_method": "ldap" },
+        "stage": { "address": "vault-stage.uhg.com", "port": 8200, "protocol": "https", "auth_method": "ldap" },
+        "prod":  { "address": "vault.uhg.com",       "port": 8200, "protocol": "https", "auth_method": "ldap" }
+      }
+    }
+  },
+  "transport": {
+    "host": "rabbitmq.uhg.com",
+    "port": 5672,
+    "vhost": "legion"
+  },
+  "cache": {
+    "driver": "dalli",
+    "servers": ["memcached.uhg.com:11211"]
+  }
+}
+```
+
+### 3. legion-tty: Onboarding Vault Auth Step
+
+After the wizard (name + LLM providers), before the reveal box:
+
+```
+[digital rain]
+[intro - kerberos identity, github quick]
+[wizard - name, LLM providers]
+[NEW: vault auth prompt]
+[reveal box - now includes vault cluster status]
+```
+
+#### Flow
+
+1. Check if any vault clusters are configured in settings
+2. If none, skip entirely
+3. If clusters exist, ask: "I found N Vault clusters. Connect now?" (TTY::Prompt confirm)
+4. If yes:
+   - Default username = kerberos `samaccountname` (from `@kerberos_identity[:samaccountname]`), fallback to `ENV['USER']`
+   - Ask: "Username:" with default pre-filled (TTY::Prompt ask)
+   - Ask: "Password:" with `echo: false` (hidden input)
+   - For each LDAP-configured cluster, attempt `Legion::Crypt.ldap_login`
+   - Show green checkmark / red X per cluster with name
+5. Store tokens in memory (settings hash), NOT on disk with the password
+6. Reveal box now shows vault cluster connection status
+
+#### New Background Probe: Not Needed
+
+Vault auth requires user interaction (password prompt), so it runs inline after the wizard, not in a background thread.
+
+## Alternatives Considered
+
+**Use lex-vault instead of vault gem for multi-cluster:** lex-vault's Faraday-based client is simpler and already supports per-instance address/token/namespace. Could replace the `vault` gem dependency in legion-crypt entirely. Deferred — not a requirement for this iteration but a good future optimization.
+
+**Kerberos auth for Vault:** Not a default Vault auth method. Would require a custom Vault plugin. Deferred.
+
+**Store tokens on disk:** Vault tokens are renewable and short-lived. Storing them risks stale tokens. Better to re-auth on each `legion` startup if needed. Could add optional token caching later.
+
+## Constraints
+
+- LDAP password is NEVER written to disk or settings files
+- Vault tokens are stored in-memory only during the session
+- `vault://` resolver must remain backward compatible (no cluster prefix = default cluster)
+- Single-cluster config (`crypt.vault.address`) must continue to work unchanged
+- Config import file is plain JSON, no wrapper format
+- HTTP sources must handle both raw JSON and base64-encoded JSON
+
+## Repos Affected
+
+| Repo | Changes |
+|------|---------|
+| `legion-crypt` | `VaultCluster` module, `LdapAuth` module, multi-cluster settings, `VaultRenewer` update, backward compat |
+| `LegionIO` | `config import` CLI command (both binaries), HTTP fetch + base64 detection |
+| `legion-tty` | Onboarding vault auth step after wizard |
+| `legion-settings` | `Resolver` update for cluster-prefixed `vault://` refs (optional, can defer) |

data/docs/plans/2026-03-18-config-import-vault-multicluster-implementation.md

@@ -0,0 +1,833 @@
+# Config Import + Multi-Cluster Vault Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add multi-cluster Vault support to legion-crypt, a `config import` CLI command, and onboarding Vault LDAP auth in legion-tty.
+
+**Architecture:** Three repos changed independently. legion-crypt lands first (prerequisite), then LegionIO CLI and legion-tty can be done in parallel.
+
+**Tech Stack:** Ruby, vault gem, Faraday (for LDAP HTTP auth), TTY::Prompt (hidden password input)
+
+**Design Doc:** `docs/plans/2026-03-18-config-import-vault-multicluster-design.md`
+
+---
+
+## Phase 1: legion-crypt Multi-Cluster Vault (prerequisite)
+
+### Task 1: Multi-Cluster Settings Schema
+
+**Files:**
+- Modify: `legion-crypt/lib/legion/crypt/settings.rb`
+- Test: `legion-crypt/spec/legion/settings_spec.rb`
+
+**Step 1: Write the failing test**
+
+```ruby
+# spec/legion/settings_spec.rb
+describe 'vault defaults' do
+  it 'includes clusters hash' do
+    expect(vault[:clusters]).to eq({})
+  end
+
+  it 'includes default key' do
+    expect(vault[:default]).to be_nil
+  end
+end
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `cd legion-crypt && bundle exec rspec spec/legion/settings_spec.rb -v`
+Expected: FAIL — no `:clusters` or `:default` key in vault defaults
+
+**Step 3: Write minimal implementation**
+
+Add to `Legion::Crypt::Settings.vault`:
+```ruby
+def self.vault
+  {
+    enabled:             !Gem::Specification.find_by_name('vault').nil?,
+    protocol:            'http',
+    address:             'localhost',
+    port:                8200,
+    token:               ENV['VAULT_DEV_ROOT_TOKEN_ID'] || ENV['VAULT_TOKEN_ID'] || nil,
+    connected:           false,
+    renewer_time:        5,
+    renewer:             true,
+    push_cluster_secret: true,
+    read_cluster_secret: true,
+    kv_path:             ENV['LEGION_VAULT_KV_PATH'] || 'legion',
+    leases:              {},
+    default:             nil,
+    clusters:            {}
+  }
+end
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `cd legion-crypt && bundle exec rspec spec/legion/settings_spec.rb -v`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add lib/legion/crypt/settings.rb spec/legion/settings_spec.rb
+git commit -m "add clusters and default keys to vault settings schema"
+```
+
+### Task 2: VaultCluster Module
+
+**Files:**
+- Create: `legion-crypt/lib/legion/crypt/vault_cluster.rb`
+- Test: `legion-crypt/spec/legion/vault_cluster_spec.rb`
+
+**Step 1: Write the failing test**
+
+```ruby
+# spec/legion/vault_cluster_spec.rb
+require 'spec_helper'
+require 'legion/crypt/vault_cluster'
+
+RSpec.describe Legion::Crypt::VaultCluster do
+  let(:test_obj) { Object.new.extend(described_class) }
+
+  before do
+    allow(test_obj).to receive(:vault_settings).and_return({
+      default: 'prod',
+      clusters: {
+        dev:  { address: 'vault-dev.example.com', port: 8200, protocol: 'https', token: nil },
+        prod: { address: 'vault.example.com', port: 8200, protocol: 'https', token: 'hvs.abc123' }
+      }
+    })
+  end
+
+  describe '#default_cluster_name' do
+    it 'returns the configured default' do
+      expect(test_obj.default_cluster_name).to eq(:prod)
+    end
+  end
+
+  describe '#cluster' do
+    it 'returns default cluster when no name given' do
+      expect(test_obj.cluster[:address]).to eq('vault.example.com')
+    end
+
+    it 'returns named cluster' do
+      expect(test_obj.cluster(:dev)[:address]).to eq('vault-dev.example.com')
+    end
+
+    it 'returns nil for unknown cluster' do
+      expect(test_obj.cluster(:unknown)).to be_nil
+    end
+  end
+
+  describe '#clusters' do
+    it 'returns all clusters' do
+      expect(test_obj.clusters.keys).to contain_exactly(:dev, :prod)
+    end
+  end
+
+  describe '#vault_client' do
+    it 'returns a Vault::Client for the default cluster' do
+      client = test_obj.vault_client
+      expect(client).to be_a(::Vault::Client)
+      expect(client.address).to eq('https://vault.example.com:8200')
+      expect(client.token).to eq('hvs.abc123')
+    end
+
+    it 'returns a Vault::Client for a named cluster' do
+      client = test_obj.vault_client(:dev)
+      expect(client.address).to eq('https://vault-dev.example.com:8200')
+    end
+
+    it 'memoizes clients per cluster name' do
+      client1 = test_obj.vault_client(:prod)
+      client2 = test_obj.vault_client(:prod)
+      expect(client1).to equal(client2)
+    end
+  end
+
+  describe '#connected_clusters' do
+    it 'returns clusters that have tokens' do
+      expect(test_obj.connected_clusters.keys).to eq([:prod])
+    end
+  end
+end
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `cd legion-crypt && bundle exec rspec spec/legion/vault_cluster_spec.rb -v`
+Expected: FAIL — `Legion::Crypt::VaultCluster` not defined
+
+**Step 3: Write minimal implementation**
+
+```ruby
+# lib/legion/crypt/vault_cluster.rb
+# frozen_string_literal: true
+
+require 'vault'
+
+module Legion
+  module Crypt
+    module VaultCluster
+      def vault_client(name = nil)
+        name = (name || default_cluster_name).to_sym
+        @vault_clients ||= {}
+        @vault_clients[name] ||= build_vault_client(clusters[name])
+      end
+
+      def cluster(name = nil)
+        name = (name || default_cluster_name).to_sym
+        clusters[name]
+      end
+
+      def default_cluster_name
+        (vault_settings[:default] || clusters.keys.first).to_sym
+      end
+
+      def clusters
+        vault_settings[:clusters] || {}
+      end
+
+      def connected_clusters
+        clusters.select { |_, config| config[:token] }
+      end
+
+      def connect_all_clusters
+        results = {}
+        clusters.each do |name, config|
+          next unless config[:token]
+
+          client = vault_client(name)
+          config[:connected] = client.sys.health_status.initialized?
+          results[name] = config[:connected]
+        rescue StandardError => e
+          config[:connected] = false
+          results[name] = false
+          log_vault_error(name, e)
+        end
+        results
+      end
+
+      private
+
+      def build_vault_client(config)
+        return nil unless config.is_a?(Hash)
+
+        client = ::Vault::Client.new(
+          address: "#{config[:protocol]}://#{config[:address]}:#{config[:port]}",
+          token:   config[:token]
+        )
+        client.namespace = config[:namespace] if config[:namespace]
+        client
+      end
+
+      def log_vault_error(name, error)
+        if defined?(Legion::Logging)
+          Legion::Logging.error("Vault cluster #{name}: #{error.message}")
+        else
+          warn("Vault cluster #{name}: #{error.message}")
+        end
+      end
+    end
+  end
+end
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `cd legion-crypt && bundle exec rspec spec/legion/vault_cluster_spec.rb -v`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add lib/legion/crypt/vault_cluster.rb spec/legion/vault_cluster_spec.rb
+git commit -m "add VaultCluster module for multi-cluster vault connections"
+```
+
+### Task 3: LdapAuth Module
+
+**Files:**
+- Create: `legion-crypt/lib/legion/crypt/ldap_auth.rb`
+- Test: `legion-crypt/spec/legion/ldap_auth_spec.rb`
+
+**Step 1: Write the failing test**
+
+```ruby
+# spec/legion/ldap_auth_spec.rb
+require 'spec_helper'
+require 'legion/crypt/vault_cluster'
+require 'legion/crypt/ldap_auth'
+
+RSpec.describe Legion::Crypt::LdapAuth do
+  let(:test_obj) do
+    obj = Object.new
+    obj.extend(Legion::Crypt::VaultCluster)
+    obj.extend(described_class)
+    obj
+  end
+
+  let(:clusters_config) do
+    {
+      default: 'prod',
+      clusters: {
+        prod:  { address: 'vault.example.com', port: 8200, protocol: 'https', auth_method: 'ldap', token: nil },
+        stage: { address: 'vault-stage.example.com', port: 8200, protocol: 'https', auth_method: 'ldap', token: nil },
+        dev:   { address: 'vault-dev.example.com', port: 8200, protocol: 'https', auth_method: 'token', token: 'hvs.existing' }
+      }
+    }
+  end
+
+  before do
+    allow(test_obj).to receive(:vault_settings).and_return(clusters_config)
+  end
+
+  describe '#ldap_login' do
+    it 'authenticates to a cluster and stores the token' do
+      mock_auth = double(client_token: 'hvs.newtoken', lease_duration: 3600, renewable: true, policies: ['default'])
+      mock_secret = double(auth: mock_auth)
+      mock_logical = double(write: mock_secret)
+      mock_client = instance_double(::Vault::Client, logical: mock_logical)
+      allow(test_obj).to receive(:vault_client).with(:prod).and_return(mock_client)
+
+      result = test_obj.ldap_login(cluster_name: :prod, username: 'jdoe', password: 's3cret')
+      expect(result[:token]).to eq('hvs.newtoken')
+      expect(result[:lease_duration]).to eq(3600)
+      expect(clusters_config[:clusters][:prod][:token]).to eq('hvs.newtoken')
+    end
+  end
+
+  describe '#ldap_login_all' do
+    it 'authenticates to all LDAP clusters and skips non-LDAP ones' do
+      mock_auth = double(client_token: 'hvs.tok', lease_duration: 3600, renewable: true, policies: ['default'])
+      mock_secret = double(auth: mock_auth)
+      mock_logical = double(write: mock_secret)
+      mock_client = instance_double(::Vault::Client, logical: mock_logical)
+      allow(test_obj).to receive(:vault_client).and_return(mock_client)
+
+      results = test_obj.ldap_login_all(username: 'jdoe', password: 's3cret')
+      expect(results.keys).to contain_exactly(:prod, :stage)
+      expect(results[:prod][:token]).to eq('hvs.tok')
+      expect(results[:stage][:token]).to eq('hvs.tok')
+    end
+
+    it 'captures errors per cluster without stopping' do
+      allow(test_obj).to receive(:vault_client).and_raise(StandardError.new('connection refused'))
+
+      results = test_obj.ldap_login_all(username: 'jdoe', password: 's3cret')
+      expect(results[:prod][:error]).to eq('connection refused')
+      expect(results[:stage][:error]).to eq('connection refused')
+    end
+  end
+end
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `cd legion-crypt && bundle exec rspec spec/legion/ldap_auth_spec.rb -v`
+Expected: FAIL — `Legion::Crypt::LdapAuth` not defined
+
+**Step 3: Write minimal implementation**
+
+```ruby
+# lib/legion/crypt/ldap_auth.rb
+# frozen_string_literal: true
+
+module Legion
+  module Crypt
+    module LdapAuth
+      def ldap_login(cluster_name:, username:, password:)
+        client = vault_client(cluster_name)
+        secret = client.logical.write("auth/ldap/login/#{username}", password: password)
+        auth = secret.auth
+        token = auth.client_token
+
+        clusters[cluster_name][:token] = token
+        clusters[cluster_name][:connected] = true
+
+        { token: token, lease_duration: auth.lease_duration,
+          renewable: auth.renewable, policies: auth.policies }
+      end
+
+      def ldap_login_all(username:, password:)
+        results = {}
+        clusters.each do |name, config|
+          next unless config[:auth_method] == 'ldap'
+
+          results[name] = ldap_login(cluster_name: name, username: username, password: password)
+        rescue StandardError => e
+          results[name] = { error: e.message }
+        end
+        results
+      end
+    end
+  end
+end
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `cd legion-crypt && bundle exec rspec spec/legion/ldap_auth_spec.rb -v`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add lib/legion/crypt/ldap_auth.rb spec/legion/ldap_auth_spec.rb
+git commit -m "add LdapAuth module for vault LDAP authentication"
+```
+
+### Task 4: Wire Multi-Cluster into Legion::Crypt.start
+
+**Files:**
+- Modify: `legion-crypt/lib/legion/crypt.rb`
+- Modify: `legion-crypt/lib/legion/crypt/vault.rb`
+- Test: `legion-crypt/spec/legion/crypt_spec.rb`
+
+**Step 1: Write the failing test**
+
+```ruby
+# Add to spec/legion/crypt_spec.rb
+describe '.cluster' do
+  it 'delegates to VaultCluster#cluster' do
+    expect(Legion::Crypt).to respond_to(:cluster)
+  end
+end
+
+describe '.ldap_login_all' do
+  it 'delegates to LdapAuth#ldap_login_all' do
+    expect(Legion::Crypt).to respond_to(:ldap_login_all)
+  end
+end
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `cd legion-crypt && bundle exec rspec spec/legion/crypt_spec.rb -v`
+Expected: FAIL — `Legion::Crypt.cluster` not defined
+
+**Step 3: Write minimal implementation**
+
+In `lib/legion/crypt.rb`, add:
+```ruby
+require_relative 'crypt/vault_cluster'
+require_relative 'crypt/ldap_auth'
+
+module Legion
+  module Crypt
+    extend VaultCluster
+    extend LdapAuth
+
+    def self.vault_settings
+      Legion::Settings[:crypt][:vault]
+    end
+
+    # Update start to handle multi-cluster
+    def self.start
+      # ... existing code ...
+      if vault_settings[:clusters]&.any?
+        connect_all_clusters
+      else
+        connect_vault  # legacy single-cluster path
+      end
+    end
+  end
+end
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `cd legion-crypt && bundle exec rspec spec/legion/crypt_spec.rb -v`
+Expected: PASS
+
+**Step 5: Run full suite and commit**
+
+```bash
+cd legion-crypt && bundle exec rspec && bundle exec rubocop -A && bundle exec rubocop
+git add lib/legion/crypt.rb lib/legion/crypt/vault.rb spec/legion/crypt_spec.rb
+git commit -m "wire multi-cluster vault into Legion::Crypt.start with backward compat"
+```
+
+### Task 5: Update VaultRenewer for Multi-Cluster
+
+**Files:**
+- Modify: `legion-crypt/lib/legion/crypt/vault_renewer.rb`
+- Test: `legion-crypt/spec/legion/vault_renewer_spec.rb`
+
+Renewer must iterate `connected_clusters` and renew each token. If no clusters are configured, fall back to single-cluster renewal (existing behavior).
+
+### Task 6: Version Bump + Pipeline
+
+**Files:**
+- Modify: `legion-crypt/lib/legion/crypt/version.rb` (bump to 1.4.4)
+- Modify: `legion-crypt/CHANGELOG.md`
+
+Run full pre-push pipeline: rspec, rubocop -A, rubocop, version bump, changelog, push.
+
+---
+
+## Phase 2: LegionIO `config import` CLI Command
+
+### Task 7: Config Import Command
+
+**Files:**
+- Create: `LegionIO/lib/legion/cli/config_import.rb`
+- Modify: `LegionIO/lib/legion/cli/config_command.rb` (register subcommand)
+- Test: `LegionIO/spec/legion/cli/config_import_spec.rb`
+
+**Step 1: Write the failing test**
+
+```ruby
+# spec/legion/cli/config_import_spec.rb
+require 'spec_helper'
+require 'legion/cli/config_import'
+
+RSpec.describe Legion::CLI::ConfigImport do
+  describe '.parse_payload' do
+    it 'parses raw JSON' do
+      result = described_class.parse_payload('{"crypt": {"vault": {}}}')
+      expect(result).to eq({ crypt: { vault: {} } })
+    end
+
+    it 'parses base64-encoded JSON' do
+      encoded = Base64.strict_encode64('{"transport": {"host": "rmq.example.com"}}')
+      result = described_class.parse_payload(encoded)
+      expect(result[:transport][:host]).to eq('rmq.example.com')
+    end
+
+    it 'raises on invalid input' do
+      expect { described_class.parse_payload('not json at all %%%') }.to raise_error(Legion::CLI::Error)
+    end
+  end
+
+  describe '.fetch_source' do
+    it 'reads a local file' do
+      tmpfile = Tempfile.new(['config', '.json'])
+      tmpfile.write('{"cache": {"driver": "dalli"}}')
+      tmpfile.close
+      result = described_class.fetch_source(tmpfile.path)
+      expect(result).to include('"cache"')
+      tmpfile.unlink
+    end
+  end
+end
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `cd LegionIO && bundle exec rspec spec/legion/cli/config_import_spec.rb -v`
+Expected: FAIL — file doesn't exist
+
+**Step 3: Write minimal implementation**
+
+```ruby
+# lib/legion/cli/config_import.rb
+# frozen_string_literal: true
+
+require 'base64'
+require 'net/http'
+require 'uri'
+require 'fileutils'
+
+module Legion
+  module CLI
+    class ConfigImport
+      SETTINGS_DIR = File.expand_path('~/.legionio/settings')
+      IMPORT_FILE  = 'imported.json'
+
+      def self.fetch_source(source)
+        if source.match?(%r{\Ahttps?://})
+          fetch_http(source)
+        else
+          raise CLI::Error, "File not found: #{source}" unless File.exist?(source)
+
+          File.read(source)
+        end
+      end
+
+      def self.fetch_http(url)
+        uri = URI.parse(url)
+        response = Net::HTTP.get_response(uri)
+        raise CLI::Error, "HTTP #{response.code}: #{response.message}" unless response.is_a?(Net::HTTPSuccess)
+
+        response.body
+      end
+
+      def self.parse_payload(body)
+        # Try raw JSON first
+        parsed = ::JSON.parse(body, symbolize_names: true)
+        raise CLI::Error, 'Config must be a JSON object' unless parsed.is_a?(Hash)
+
+        parsed
+      rescue ::JSON::ParserError
+        # Try base64-decoded JSON
+        begin
+          decoded = Base64.decode64(body)
+          parsed = ::JSON.parse(decoded, symbolize_names: true)
+          raise CLI::Error, 'Config must be a JSON object' unless parsed.is_a?(Hash)
+
+          parsed
+        rescue ::JSON::ParserError
+          raise CLI::Error, 'Source is not valid JSON or base64-encoded JSON'
+        end
+      end
+
+      def self.write_config(config, force: false)
+        FileUtils.mkdir_p(SETTINGS_DIR)
+        path = File.join(SETTINGS_DIR, IMPORT_FILE)
+
+        if File.exist?(path) && !force
+          existing = ::JSON.parse(File.read(path), symbolize_names: true)
+          config = deep_merge(existing, config)
+        end
+
+        File.write(path, ::JSON.pretty_generate(config))
+        path
+      end
+
+      def self.deep_merge(base, overlay)
+        base.merge(overlay) do |_key, old_val, new_val|
+          if old_val.is_a?(Hash) && new_val.is_a?(Hash)
+            deep_merge(old_val, new_val)
+          else
+            new_val
+          end
+        end
+      end
+
+      def self.summary(config)
+        sections = config.keys.map(&:to_s)
+        vault_clusters = config.dig(:crypt, :vault, :clusters)&.keys&.map(&:to_s) || []
+        { sections: sections, vault_clusters: vault_clusters }
+      end
+    end
+  end
+end
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `cd LegionIO && bundle exec rspec spec/legion/cli/config_import_spec.rb -v`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add lib/legion/cli/config_import.rb spec/legion/cli/config_import_spec.rb
+git commit -m "add config import utility for URL and local file sources"
+```
+
+### Task 8: Wire Import into Config Subcommand
+
+**Files:**
+- Modify: `LegionIO/lib/legion/cli/config_command.rb`
+
+Add `import` subcommand to Config Thor class:
+```ruby
+desc 'import SOURCE', 'Import configuration from a URL or local file'
+option :force, type: :boolean, default: false, desc: 'Overwrite existing imported config'
+def import(source)
+  out = formatter
+  require_relative 'config_import'
+
+  out.info("Fetching config from #{source}...")
+  body = ConfigImport.fetch_source(source)
+  config = ConfigImport.parse_payload(body)
+  path = ConfigImport.write_config(config, force: options[:force])
+  summary = ConfigImport.summary(config)
+
+  out.success("Config written to #{path}")
+  out.info("Sections: #{summary[:sections].join(', ')}")
+  if summary[:vault_clusters].any?
+    out.info("Vault clusters: #{summary[:vault_clusters].join(', ')}")
+    out.info("Run 'legion' to authenticate via LDAP during onboarding")
+  end
+rescue CLI::Error => e
+  formatter.error(e.message)
+  raise SystemExit, 1
+end
+```
+
+**Step 1: Write test, Step 2: Verify fail, Step 3: Implement, Step 4: Verify pass**
+
+**Step 5: Commit**
+
+```bash
+git add lib/legion/cli/config_command.rb
+git commit -m "add 'config import' subcommand for URL and local file config import"
+```
+
+### Task 9: Version Bump + Pipeline for LegionIO
+
+Run full pre-push pipeline. Bump to 1.4.63.
+
+---
+
+## Phase 3: legion-tty Onboarding Vault Auth
+
+### Task 10: VaultAuth Background-Free Prompt
+
+**Files:**
+- Create: `legion-tty/lib/legion/tty/screens/vault_auth.rb` (extracted helper, not a full screen)
+- Modify: `legion-tty/lib/legion/tty/screens/onboarding.rb`
+- Test: `legion-tty/spec/legion/tty/screens/onboarding_spec.rb`
+
+**Step 1: Write the failing test**
+
+```ruby
+# Add to onboarding_spec.rb
+describe '#run_vault_auth' do
+  context 'when no vault clusters configured' do
+    it 'skips vault auth entirely' do
+      allow(screen).to receive(:vault_clusters_configured?).and_return(false)
+      expect(wizard).not_to receive(:confirm)
+      screen.send(:run_vault_auth)
+    end
+  end
+
+  context 'when vault clusters configured' do
+    before do
+      allow(screen).to receive(:vault_clusters_configured?).and_return(true)
+      allow(screen).to receive(:vault_cluster_count).and_return(3)
+    end
+
+    it 'asks user if they want to connect' do
+      allow(wizard).to receive(:confirm).and_return(false)
+      screen.send(:run_vault_auth)
+      expect(wizard).to have_received(:confirm).with(/3 Vault clusters/)
+    end
+  end
+end
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `cd legion-tty && bundle exec rspec spec/legion/tty/screens/onboarding_spec.rb -v`
+Expected: FAIL
+
+**Step 3: Write minimal implementation**
+
+Add to `onboarding.rb`:
+
+```ruby
+def run_vault_auth
+  return unless vault_clusters_configured?
+
+  count = vault_cluster_count
+  typed_output("I found #{count} Vault cluster#{'s' if count != 1}.")
+  @output.puts
+  return unless @wizard.confirm("Connect now?")
+
+  username = default_vault_username
+  username = @wizard.ask_with_default('Username:', username)
+  password = @wizard.ask_secret('Password:')
+
+  typed_output('Authenticating...')
+  @output.puts
+
+  results = Legion::Crypt.ldap_login_all(username: username, password: password)
+  display_vault_results(results)
+end
+
+def vault_clusters_configured?
+  return false unless defined?(Legion::Crypt)
+
+  clusters = Legion::Settings.dig(:crypt, :vault, :clusters)
+  clusters.is_a?(Hash) && clusters.any?
+rescue StandardError
+  false
+end
+
+def vault_cluster_count
+  Legion::Settings.dig(:crypt, :vault, :clusters)&.size || 0
+end
+
+def default_vault_username
+  if @kerberos_identity
+    @kerberos_identity[:samaccountname] || @kerberos_identity[:first_name]&.downcase
+  else
+    ENV.fetch('USER', 'unknown')
+  end
+end
+
+def display_vault_results(results)
+  results.each do |name, result|
+    if result[:error]
+      @output.puts "  #{Theme.c(:error, 'X')} #{name}: #{result[:error]}"
+    else
+      @output.puts "  #{Theme.c(:success, 'ok')} #{name}: connected (#{result[:policies]&.size || 0} policies)"
+    end
+  end
+  @output.puts
+  sleep 1
+end
+```
+
+Wire into `activate` method between `run_wizard` and `collect_background_results`:
+```ruby
+def activate
+  start_background_threads
+  run_rain unless @skip_rain
+  run_intro
+  config = run_wizard
+  run_vault_auth          # <-- NEW
+  scan_data, github_data = collect_background_results
+  # ...
+end
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `cd legion-tty && bundle exec rspec spec/legion/tty/screens/onboarding_spec.rb -v`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add lib/legion/tty/screens/onboarding.rb spec/legion/tty/screens/onboarding_spec.rb
+git commit -m "add vault LDAP auth step to onboarding wizard"
+```
+
+### Task 11: WizardPrompt Secret Input
+
+**Files:**
+- Modify: `legion-tty/lib/legion/tty/components/wizard_prompt.rb`
+- Test: `legion-tty/spec/legion/tty/components/wizard_prompt_spec.rb`
+
+Add `ask_secret` and `ask_with_default` methods to WizardPrompt:
+
+```ruby
+def ask_secret(question)
+  @prompt.mask(question)
+end
+
+def ask_with_default(question, default)
+  @prompt.ask(question, default: default)
+end
+```
+
+### Task 12: Vault Summary in Reveal Box
+
+**Files:**
+- Modify: `legion-tty/lib/legion/tty/screens/onboarding.rb`
+
+Add `vault_summary_lines` to `build_summary`, showing connected/disconnected vault clusters.
+
+### Task 13: Version Bump + Pipeline for legion-tty
+
+Bump to 0.2.3. Run full pre-push pipeline.
+
+---
+
+## Execution Order
+
+```
+Task 1-6  (legion-crypt)   — FIRST, prerequisite
+Task 7-9  (LegionIO)       — after Task 6, can parallel with Tasks 10-13
+Task 10-13 (legion-tty)    — after Task 6, can parallel with Tasks 7-9
+```
+
+## Recommended Execution: `1 → 2 → 3 → 4 → 5 → 6 → [7-9 || 10-13]`

data/lib/legion/cli/config_command.rb

@@ -182,6 +182,29 @@ module Legion
         raise SystemExit, exit_code if exit_code != 0
       end
 
+      desc 'import SOURCE', 'Import configuration from a URL or local file'
+      option :force, type: :boolean, default: false, desc: 'Overwrite existing imported config'
+      def import(source)
+        out = formatter
+        require_relative 'config_import'
+
+        out.info("Fetching config from #{source}...")
+        body = ConfigImport.fetch_source(source)
+        config = ConfigImport.parse_payload(body)
+        path = ConfigImport.write_config(config, force: options[:force])
+        summary = ConfigImport.summary(config)
+
+        out.success("Config written to #{path}")
+        out.info("Sections: #{summary[:sections].join(', ')}")
+        if summary[:vault_clusters].any?
+          out.info("Vault clusters: #{summary[:vault_clusters].join(', ')}")
+          out.info("Run 'legion' to authenticate via LDAP during onboarding")
+        end
+      rescue CLI::Error => e
+        formatter.error(e.message)
+        raise SystemExit, 1
+      end
+
       no_commands do # rubocop:disable Metrics/BlockLength
         def formatter
           @formatter ||= Output::Formatter.new(

data/lib/legion/cli/config_import.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'net/http'
+require 'uri'
+require 'fileutils'
+require 'json'
+
+module Legion
+  module CLI
+    module ConfigImport
+      SETTINGS_DIR = File.expand_path('~/.legionio/settings')
+      IMPORT_FILE  = 'imported.json'
+
+      module_function
+
+      def fetch_source(source)
+        if source.match?(%r{\Ahttps?://})
+          fetch_http(source)
+        else
+          raise CLI::Error, "File not found: #{source}" unless File.exist?(source)
+
+          File.read(source)
+        end
+      end
+
+      def fetch_http(url)
+        uri = URI.parse(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == 'https'
+        http.open_timeout = 10
+        http.read_timeout = 10
+        request = Net::HTTP::Get.new(uri)
+        response = http.request(request)
+        raise CLI::Error, "HTTP #{response.code}: #{response.message}" unless response.is_a?(Net::HTTPSuccess)
+
+        response.body
+      end
+
+      def parse_payload(body)
+        parsed = ::JSON.parse(body, symbolize_names: true)
+        raise CLI::Error, 'Config must be a JSON object' unless parsed.is_a?(Hash)
+
+        parsed
+      rescue ::JSON::ParserError
+        begin
+          decoded = Base64.decode64(body)
+          parsed = ::JSON.parse(decoded, symbolize_names: true)
+          raise CLI::Error, 'Config must be a JSON object' unless parsed.is_a?(Hash)
+
+          parsed
+        rescue ::JSON::ParserError
+          raise CLI::Error, 'Source is not valid JSON or base64-encoded JSON'
+        end
+      end
+
+      def write_config(config, force: false)
+        FileUtils.mkdir_p(SETTINGS_DIR)
+        path = File.join(SETTINGS_DIR, IMPORT_FILE)
+
+        if File.exist?(path) && !force
+          existing = ::JSON.parse(File.read(path), symbolize_names: true)
+          config = deep_merge(existing, config)
+        end
+
+        File.write(path, ::JSON.pretty_generate(config))
+        path
+      end
+
+      def deep_merge(base, overlay)
+        base.merge(overlay) do |_key, old_val, new_val|
+          if old_val.is_a?(Hash) && new_val.is_a?(Hash)
+            deep_merge(old_val, new_val)
+          else
+            new_val
+          end
+        end
+      end
+
+      def summary(config)
+        sections = config.keys.map(&:to_s)
+        vault_clusters = config.dig(:crypt, :vault, :clusters)&.keys&.map(&:to_s) || []
+        { sections: sections, vault_clusters: vault_clusters }
+      end
+    end
+  end
+end

data/lib/legion/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Legion
-  VERSION = '1.4.62'
+  VERSION = '1.4.63'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legionio
 version: !ruby/object:Gem::Version
-  version: 1.4.62
+  version: 1.4.63
 platform: ruby
 authors:
 - Esity
@@ -329,6 +329,8 @@ files:
 - completions/legionio.bash
 - docker_deploy.rb
 - docs/README.md
+- docs/plans/2026-03-18-config-import-vault-multicluster-design.md
+- docs/plans/2026-03-18-config-import-vault-multicluster-implementation.md
 - docs/plans/2026-03-18-legion-tty-default-cli-design.md
 - docs/plans/2026-03-18-legion-tty-default-cli-implementation.md
 - exe/legion
@@ -420,6 +422,7 @@ files:
 - lib/legion/cli/commit_command.rb
 - lib/legion/cli/completion_command.rb
 - lib/legion/cli/config_command.rb
+- lib/legion/cli/config_import.rb
 - lib/legion/cli/config_scaffold.rb
 - lib/legion/cli/connection.rb
 - lib/legion/cli/cost/data_client.rb