nushell-plugins/nu_plugin_kms/IMPLEMENTATION_STATUS.md

nu_plugin_kms Implementation Status

Phase 1: Base Structure (COMPLETED ✅)

Date: 2025-10-08 Agent: Agente 4 (Base Structure)

Files Created

File	Lines	Status	Description
Cargo.toml	23	✅ Complete	Dependencies with path references
src/main.rs	194	✅ Complete	Plugin entry point with 4 commands
src/helpers.rs	23	🟡 Stub	Backend implementations (for Agente 5)
src/tests.rs	7	🟡 Stub	Test suite (for Agente 5)
README.md	24	✅ Complete	Basic documentation
Total	271	-	-

Build Verification

✅ cargo check: PASSED (5 non-critical warnings)
✅ cargo build: PASSED (32.18s)
✅ Binary created: target/debug/nu_plugin_kms (23MB)
✅ Protocol handshake: SUCCESS
✅ MsgPack serialization: Working

Commands Implemented (Placeholder)

1. kms encrypt

kms encrypt <data> --backend <backend> --key <key>

• Input: String
• Output: String (placeholder: "ENCRYPTED_PLACEHOLDER")
• Backends: rustyvault, age, cosmian
• Status: Stub implementation

2. kms decrypt

kms decrypt <encrypted> --backend <backend> --key <key>

• Input: String
• Output: String (placeholder: "DECRYPTED_PLACEHOLDER")
• Backends: rustyvault, age, cosmian
• Status: Stub implementation

3. kms generate-key

kms generate-key --spec <AES256|AES128> --backend <backend>

• Input: Nothing
• Output: Record {plaintext: string, ciphertext: string}
• Key Specs: AES128, AES256
• Status: Stub implementation

4. kms status

kms status

• Input: Nothing
• Output: Record {backend: string, available: bool}
• Status: Stub implementation

Dependencies Configured

Path Dependencies (Nushell Integration)

nu-plugin = { version = "0.107.1", path = "../nushell/crates/nu-plugin" }
nu-protocol = { version = "0.107.1", path = "../nushell/crates/nu-protocol", features = ["plugin"] }

External Dependencies (KMS Backends)

rusty_vault = "0.2.1"          # RustyVault client
age = "0.10"                   # Age encryption
base64 = "0.22"                # Base64 encoding
serde = "1.0"                  # Serialization
serde_json = "1.0"             # JSON support
reqwest = "0.12"               # HTTP client (fallback)
tokio = "1.40"                 # Async runtime
tempfile = "3.10"              # Temporary files

Helper Functions (Stub)

// src/helpers.rs
pub enum Backend {
    RustyVault,
    Age,
    Cosmian,
    Fallback,
}

pub fn detect_backend() -> Backend
pub fn encode_base64(data: &[u8]) -> String
pub fn decode_base64(data: &str) -> Result<Vec<u8>, String>

Pattern Compliance

✅ Follows nu_plugin_tera structure exactly:

• Same Cargo.toml pattern (path dependencies to ../nushell/)
• Same Plugin trait implementation
• Same SimplePluginCommand pattern
• Same module organization (helpers.rs, tests.rs)
• Same category: Custom("provisioning".into())
• Same serializer: MsgPackSerializer

Phase 2: Backend Implementation (PENDING 🟡)

Assigned To: Agente 5 (KMS Backend Implementation)

Tasks for Agente 5

1. RustyVault Backend

• Implement encrypt_with_rustyvault(data, key) -> Result<String>
• Implement decrypt_with_rustyvault(encrypted, key) -> Result<String>
• Implement generate_key_rustyvault(spec) -> Result<(Vec<u8>, Vec<u8>)>
• Add RustyVault client initialization
• Add error handling and retries
• Add connection pooling

2. Age Backend

• Implement encrypt_with_age(data, recipient) -> Result<String>
• Implement decrypt_with_age(encrypted, identity_path) -> Result<String>
• Implement generate_age_keypair() -> Result<(String, String)>
• Add age recipient handling
• Add identity file management
• Add age armor format support

3. Cosmian Backend

• Implement encrypt_with_cosmian(data, key) -> Result<String>
• Implement decrypt_with_cosmian(encrypted, key) -> Result<String>
• Add Cosmian client initialization
• Add CoverCrypt support
• Add policy-based encryption

4. HTTP Fallback Backend

• Implement encrypt_via_http(data, endpoint) -> Result<String>
• Implement decrypt_via_http(encrypted, endpoint) -> Result<String>
• Add HTTP client with retry logic
• Add authentication (API keys, JWT)
• Add TLS certificate validation

5. Backend Detection

• Implement detect_backend() -> Backend
  • Check environment variables (KMS_BACKEND)
  • Check RustyVault connectivity
  • Check Age key availability
  • Check Cosmian configuration
  • Fallback to HTTP endpoint
• Add backend health checks
• Add backend failover logic

6. Command Implementation

• Update KmsEncrypt::run() with real encryption
• Update KmsDecrypt::run() with real decryption
• Update KmsGenerateKey::run() with real key generation
• Update KmsStatus::run() with real health checks
• Add proper error handling (LabeledError)
• Add input validation

7. Testing

• Unit tests for each backend
• Integration tests with mock KMS services
• Error case testing
• Performance benchmarks
• Documentation tests (examples)

8. Documentation

• Add command examples to README
• Add backend configuration guide
• Add troubleshooting section
• Add performance considerations
• Add security best practices

Expected File Structure After Phase 2

nu_plugin_kms/
├── Cargo.toml
├── README.md
├── src/
│   ├── main.rs (commands)
│   ├── helpers.rs (→ backends/)
│   ├── backends/
│   │   ├── mod.rs
│   │   ├── rustyvault.rs
│   │   ├── age.rs
│   │   ├── cosmian.rs
│   │   ├── http.rs
│   │   └── common.rs
│   ├── tests.rs
│   └── lib.rs (optional)
├── tests/
│   ├── integration_tests.rs
│   ├── backend_tests.rs
│   └── fixtures/
├── examples/
│   ├── basic_encryption.rs
│   ├── key_generation.rs
│   └── backend_selection.rs
└── benches/
    └── encryption_benchmarks.rs

Integration Points

1. Config System Integration

Plugin should read configuration from provisioning config:

[kms]
backend = "rustyvault"  # or "age", "cosmian", "http"
rustyvault_addr = "http://localhost:8200"
age_recipients_file = "~/.config/provisioning/age/recipients.txt"
cosmian_endpoint = "https://cosmian.example.com"
http_fallback_url = "http://localhost:8080/kms"

2. Environment Variables

KMS_BACKEND=rustyvault|age|cosmian|http
VAULT_ADDR=http://localhost:8200
VAULT_TOKEN=...
AGE_RECIPIENTS_FILE=...
AGE_IDENTITY_FILE=...
COSMIAN_ENDPOINT=...
KMS_HTTP_ENDPOINT=...

3. Nushell Integration

After building, register the plugin:

plugin add target/release/nu_plugin_kms
plugin use kms

Usage examples:

# Encrypt data
"my secret" | kms encrypt --backend rustyvault

# Decrypt data
"ENCRYPTED_DATA" | kms decrypt --backend rustyvault

# Generate key
kms generate-key --spec AES256

# Check status
kms status

4. CLI Integration

The provisioning CLI can use this plugin for:

• Config file encryption (provisioning config encrypt)
• Secret management (provisioning secrets encrypt)
• Dynamic secret generation
• KMS health monitoring

Success Criteria

Phase 1 (Completed ✅)

• Plugin structure created following nu_plugin_tera pattern
• All 4 commands defined with proper signatures
• Plugin compiles without errors
• Plugin responds to protocol handshake
• Dependencies configured with path references
• README documentation complete

Phase 2 (Pending 🟡)

• All 4 backends implemented (RustyVault, Age, Cosmian, HTTP)
• Backend auto-detection working
• All commands perform real encryption/decryption
• Comprehensive test suite (unit + integration)
• Error handling complete
• Documentation with examples
• Performance benchmarks passing
• Security audit passed

Timeline Estimate

Phase	Tasks	Estimated Time
Phase 1: Base Structure	5 files, basic structure	✅ Completed
Phase 2: Backend Implementation	4 backends, tests, docs	~8-12 hours
Phase 3: Integration Testing	End-to-end testing	~2-4 hours
Phase 4: Documentation	User guide, examples	~2-3 hours
Total	-	12-19 hours

References

Similar Plugins

• nu_plugin_tera - Template rendering (structure pattern)
• Existing KMS service - HTTP API reference
• Config encryption module - Use case examples

External Documentation

• RustyVault API
• Age Encryption
• Cosmian KMS
• Nushell Plugin Guide

---

Status: Ready for Agente 5 (Backend Implementation) Last Updated: 2025-10-08 Next Agent: Agente 5 - KMS Backend Implementation