quickseal 0.1.4

# Seal 🔐

[![CI](https://github.com/startappdev/seal/actions/workflows/ci.yml/badge.svg)](https://github.com/startappdev/seal/actions/workflows/ci.yml)
[![Security Audit](https://github.com/startappdev/seal/actions/workflows/security.yml/badge.svg)](https://github.com/startappdev/seal/actions/workflows/security.yml)
[![codecov](https://codecov.io/gh/startappdev/seal/branch/main/graph/badge.svg)](https://codecov.io/gh/startappdev/seal)
[![Crates.io](https://img.shields.io/crates/v/quickseal.svg)](https://crates.io/crates/quickseal)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Create Kubernetes SealedSecrets with a single secure command.**

Seal is a CLI tool that simplifies creating [Kubernetes SealedSecrets](https://github.com/bitnami-labs/sealed-secrets). Instead of manually running multiple commands and worrying about plaintext secret cleanup, Seal does it all in one secure, atomic operation.

---

## ✨ Features

- **🚀 Single Command**: Create sealed secrets without manual multi-step workflows
- **🔒 Secure by Default**: Automatic cleanup of plaintext secrets and temp files
- **🎯 Context Aware**: Displays cluster context before sealing to prevent mistakes
- **🔄 Signal Handling**: Graceful cleanup on interruption (Ctrl+C, SIGTERM, SIGHUP)
- **💾 Memory Safety**: Uses `zeroize` to clear sensitive data from memory
- **✅ Input Validation**: Validates Kubernetes naming conventions (DNS-1123)
- **📤 Multiple Formats**: Outputs YAML or JSON
- **🌐 Cross-Platform**: Works on Linux, macOS, and Windows

---

## 🤔 Why Seal?

### Without Seal (4+ manual steps)
```bash
# Step 1: Create plaintext secret YAML
kubectl create secret generic db-creds \
  --from-literal=username=admin \
  --from-literal=password=secret123 \
  --dry-run=client -o yaml > secret.yaml

# Step 2: Seal the secret
kubeseal --format yaml < secret.yaml > sealed-secret.yaml

# Step 3: Delete plaintext file (CRITICAL - often forgotten!)
rm secret.yaml

# Step 4: Apply sealed secret
kubectl apply -f sealed-secret.yaml
```

### With Seal (1 command)
```bash
seal create -n db-creds -N production \
  -l username=admin -l password=secret123 | kubectl apply -f -
```

**Benefits:**
- ✅ No plaintext files left on disk
- ✅ No manual cleanup needed
- ✅ Cluster context displayed before sealing
- ✅ Automatic error handling and cleanup
- ✅ Memory-safe secret handling

---

## 📋 Prerequisites

### Required

1. **Kubernetes cluster** with [sealed-secrets controller](https://github.com/bitnami-labs/sealed-secrets) installed:
   ```bash
   kubectl get pods -n kube-system -l name=sealed-secrets-controller
   ```

2. **kubectl** configured with active context:
   ```bash
   kubectl config current-context
   ```

3. **kubeseal** binary installed:
   ```bash
   # macOS
   brew install kubeseal

   # Linux (example for v0.24.0)
   KUBESEAL_VERSION=0.24.0
   wget "https://github.com/bitnami-labs/sealed-secrets/releases/download/v${KUBESEAL_VERSION}/kubeseal-${KUBESEAL_VERSION}-linux-amd64.tar.gz"
   tar -xvzf kubeseal-${KUBESEAL_VERSION}-linux-amd64.tar.gz kubeseal
   sudo install -m 755 kubeseal /usr/local/bin/kubeseal

   # Windows
   choco install kubeseal

   # Verify installation
   kubeseal --version
   ```

---

## 🚀 Installation

### From Releases (Recommended)

Download the latest binary for your platform from [GitHub Releases](https://github.com/startappdev/seal/releases):

```bash
# Linux (x86_64)
curl -LO https://github.com/startappdev/seal/releases/latest/download/seal-linux-amd64
chmod +x seal-linux-amd64
sudo mv seal-linux-amd64 /usr/local/bin/seal

# macOS (Apple Silicon)
curl -LO https://github.com/startappdev/seal/releases/latest/download/seal-darwin-arm64
chmod +x seal-darwin-arm64
sudo mv seal-darwin-arm64 /usr/local/bin/seal

# macOS (Intel)
curl -LO https://github.com/startappdev/seal/releases/latest/download/seal-darwin-amd64
chmod +x seal-darwin-amd64
sudo mv seal-darwin-amd64 /usr/local/bin/seal

# Windows (PowerShell)
Invoke-WebRequest -Uri "https://github.com/startappdev/seal/releases/latest/download/seal-windows-amd64.exe" -OutFile "seal.exe"
# Move to a directory in your PATH
```

### From Crates.io (Rust Users)

```bash
cargo install quickseal
```

> **Note**: The package name on crates.io is `quickseal` (since `seal` was already taken), but the binary is still called `seal`.

### From Source

```bash
# Clone the repository
git clone https://github.com/startappdev/seal.git
cd seal

# Build and install
cargo install --path .

# Verify installation
seal --version
```

---

## 📖 Usage

### Basic Usage

Create a sealed secret with key-value pairs:

```bash
seal create \
  --name my-secret \
  --namespace production \
  --from-literal username=admin \
  --from-literal password=secret123
```

**Output:**
```
Current Kubernetes context: production-cluster (https://k8s.example.com)

Sealing secret...
✓ SealedSecret created successfully!

apiVersion: bitnami.com/v1alpha1
kind: SealedSecret
metadata:
  name: my-secret
  namespace: production
spec:
  encryptedData:
    username: AgB7x...
    password: AgC9y...
```

### Pipe to kubectl

Apply the sealed secret directly:

```bash
seal create -n my-secret -N production \
  -l username=admin -l password=secret123 \
  | kubectl apply -f -
```

### Save to File

```bash
seal create -n my-secret -N production \
  -l username=admin -l password=secret123 \
  > sealed-secret.yaml
```

### JSON Output

```bash
seal create -n my-secret -N production \
  -l username=admin -l password=secret123 \
  --output json
```

### With Labels and Annotations

```bash
seal create \
  --name my-secret \
  --namespace production \
  --from-literal token=abc123 \
  --label app=myapp \
  --label env=prod \
  --annotation managed-by=seal
```

### Multiple Key-Value Pairs

```bash
seal create -n db-creds -N production \
  -l DB_HOST=postgres.example.com \
  -l DB_PORT=5432 \
  -l DB_USER=admin \
  -l DB_PASSWORD=super-secret \
  -l DB_NAME=myapp
```

---

## 🎮 Command Reference

### Global Flags

```
  -v, --verbose    Enable verbose logging
  -h, --help       Print help information
  -V, --version    Print version information
```

### `seal create` Command

Create a sealed secret.

**Required Flags:**
```
  -n, --name <NAME>              Secret name (DNS-1123 subdomain)
  -N, --namespace <NAMESPACE>    Kubernetes namespace
  -l, --from-literal <KEY=VALUE> Secret key-value pairs (can be used multiple times)
```

**Optional Flags:**
```
  -L, --label <KEY=VALUE>        Labels to add to the sealed secret (can be used multiple times)
  -A, --annotation <KEY=VALUE>   Annotations to add to the sealed secret (can be used multiple times)
  -o, --output <FORMAT>          Output format: yaml (default) or json
  -i, --interactive              Interactive mode with guided prompts
```

**Examples:**
```bash
# Basic usage
seal create -n my-secret -N production -l key1=value1 -l key2=value2

# With labels
seal create -n my-secret -N production -l token=abc123 -L app=myapp -L env=prod

# JSON output
seal create -n my-secret -N production -l token=abc123 --output json

# Pipe to kubectl
seal create -n my-secret -N production -l token=abc123 | kubectl apply -f -

# Save to file
seal create -n my-secret -N production -l token=abc123 > sealed-secret.yaml
```

---

## 🛡️ Security Features

### Memory Safety

Seal uses the [`zeroize`](https://docs.rs/zeroize/) crate to automatically clear sensitive data from memory when it goes out of scope:

```rust
pub struct SecretKeyValue {
    pub key: String,
    pub value: Zeroizing<String>, // Automatically zeroed on drop
}
```

### Secure Temporary Files

All temporary files are created with `0600` permissions (owner read/write only) and are automatically overwritten with zeros before deletion:

```rust
impl Drop for SecureTempFile {
    fn drop(&mut self) {
        // Overwrite with zeros before deletion
        let zeros = vec![0u8; file_size];
        file.write_all(&zeros);
    }
}
```

### Signal Handling

Seal registers signal handlers to ensure cleanup happens even if the process is interrupted:

- **SIGINT** (Ctrl+C): Graceful cleanup and exit
- **SIGTERM**: Graceful cleanup and exit
- **SIGHUP** (Unix): Graceful cleanup and exit

### Input Validation

All inputs are validated against Kubernetes naming conventions (DNS-1123):

- **Secret names**: lowercase alphanumeric, hyphens, dots (1-253 chars)
- **Namespaces**: lowercase alphanumeric, hyphens (1-63 chars)
- **Keys**: alphanumeric, underscores, hyphens, dots

---

## 🏗️ Architecture

```
src/
├── cli/          # Command-line interface (clap v4)
│   ├── args.rs   # CLI argument parsing
│   └── commands.rs # Command implementations
├── error/        # Structured error types (thiserror)
├── k8s/          # Kubernetes integration
│   ├── context.rs  # Kubeconfig loading (kube-rs)
│   ├── kubeseal.rs # kubeseal integration
│   └── secret.rs   # Secret manifest generation
├── models/       # Data structures and validation
│   ├── context.rs     # Cluster context
│   └── secret_data.rs # Secret models
└── security/     # Security utilities
    ├── cleanup.rs   # Signal handlers
    ├── memory.rs    # Secure memory handling
    └── tempfile.rs  # Secure temporary files
```

---

## 🔧 Development

### Prerequisites

- Rust 1.75+ (stable channel)
- Cargo

### Build

```bash
# Debug build
cargo build

# Release build
cargo build --release

# Run
cargo run -- create -n test -N default -l key=value
```

### Test

```bash
# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Run specific test
cargo test test_name

# Check code coverage
cargo install cargo-llvm-cov
cargo llvm-cov --html
# Open target/llvm-cov/html/index.html
```

### Lint

```bash
# Format code
cargo fmt

# Check formatting
cargo fmt --check

# Run clippy
cargo clippy --all-targets --all-features -- -D warnings
```

### Local Development Workflow

```bash
# 1. Make changes
# 2. Run tests
cargo test

# 3. Check formatting and lints
cargo fmt && cargo clippy

# 4. Build release
cargo build --release

# 5. Test the binary
./target/release/seal create -n test -N default -l foo=bar
```

---

## 🤝 Contributing

Contributions are welcome! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.

### Development Principles

This project follows the [Rust CLI Development Constitution](rust_speckit_constitution.md):

1. **Branching**: Feature branches with descriptive names
2. **Security-First**: Zero plaintext persistence, memory safety
3. **Code Quality**: Clippy with strict settings, rustfmt enforcement
4. **Testing**: Unit tests, integration tests, 70%+ code coverage
5. **Cross-Platform**: Tested on Linux, macOS, Windows

### Reporting Issues

Please use [GitHub Issues](https://github.com/startappdev/seal/issues) to report bugs or request features.

---

## 🗺️ Roadmap

### v0.1.0 (Current - MVP)
- ✅ Quick secret creation with flags
- ✅ Cluster context awareness
- ✅ Interactive mode with guided prompts
- ✅ Enhanced help system with examples
- ✅ Secure memory handling and cleanup
- ✅ Multi-platform support
- ✅ Comprehensive error handling

### v0.2.0 (Planned)
- ⏳ Shell completion (bash, zsh, fish)
- ⏳ Read secrets from files (`--from-file`)

### v0.3.0 (Future)
- 📋 Support for secret types (Opaque, TLS, Docker config)
- 📋 Dry-run mode (`--dry-run`)
- 📋 Diff mode (compare with existing secret)

### v1.0.0 (Future)
- 📋 Integration tests with real clusters
- 📋 Performance benchmarks
- 📋 Plugin system for custom secret sources

---

## 📊 Project Status

| Metric | Status |
|--------|--------|
| Build | ✅ Passing |
| Tests | ✅ 41 tests passing |
| Coverage | ✅ 75.94% |
| Security Audit | ✅ No vulnerabilities |
| License Compliance | ✅ All dependencies checked |
| Platforms | ✅ Linux, macOS, Windows |

---

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 🙏 Acknowledgments

- [Bitnami Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) - The sealed-secrets controller
- [clap](https://github.com/clap-rs/clap) - Command-line argument parsing
- [kube-rs](https://github.com/kube-rs/kube) - Kubernetes client library
- [zeroize](https://github.com/RustCrypto/utils/tree/master/zeroize) - Secure memory zeroing

---

## 🚀 Contributing & Releases

### Automated Releases

This project uses automated semantic versioning based on conventional commits. When you merge to `main`, a new release is automatically created if your commits include:

- `feat:` → Minor version bump (0.x.0) - New features
- `fix:` → Patch version bump (0.0.x) - Bug fixes
- `BREAKING CHANGE:` or `!:` → Major version bump (x.0.0) - Breaking changes

**Example:**
```bash
git commit -m "feat(cli): add --output flag for custom file paths"
# When merged to main → triggers release 0.2.0 (if current is 0.1.0)
```

Releases are automatically published to:
- [GitHub Releases](https://github.com/startappdev/seal/releases) - with binaries for all platforms
- [crates.io](https://crates.io/crates/quickseal) - for `cargo install`

**Note:** Commits with `docs:`, `chore:`, `style:`, `refactor:`, or `test:` do NOT trigger releases.

For more details, see [Release Process Documentation](specs/007-fix-release-automation/quickstart.md).

---

## 📚 Documentation

- [User Guide](specs/001-sealedsecret-cli/quickstart.md) - Detailed usage examples
- [CI/CD Setup](CI_CD_SETUP.md) - CI/CD infrastructure documentation
- [Architecture](specs/001-sealedsecret-cli/plan.md) - Technical implementation details
- [Specification](specs/001-sealedsecret-cli/spec.md) - Full feature specification

---

## 💬 Support

- 📖 [Documentation](https://github.com/startappdev/seal/tree/main/specs)
- 🐛 [Issue Tracker](https://github.com/startappdev/seal/issues)
- 💡 [Feature Requests](https://github.com/startappdev/seal/issues/new?template=feature_request.md)
- 🔒 [Security Issues](https://github.com/startappdev/seal/security/advisories)

---

<p align="center">Made with ❤️ by the Seal Contributors</p>
<p align="center">
  <a href="https://github.com/startappdev/seal/stargazers">⭐ Star on GitHub</a> •
  <a href="https://github.com/startappdev/seal/issues">🐛 Report Bug</a> •
  <a href="https://github.com/startappdev/seal/issues">💡 Request Feature</a>
</p>