TypeDialog/examples/08-encryption/README.md

# Encryption Examples

This directory contains example forms demonstrating typedialog's encryption and redaction features.

## Quick Test (No Setup Required)

```bash
# Redaction: Replace sensitive values with [REDACTED]
typedialog form examples/08-encryption/simple-login.toml --redact --format json

# Expected output:
# {
#   "username": "alice",
#   "password": "[REDACTED]"
# }
```

## Setup Required

Before running encryption tests, set up encryption services:

```bash
./scripts/encryption-test-setup.sh
source /tmp/typedialog-env.sh
```

## Forms Included

### 1. `simple-login.toml` - Minimal Example

**Purpose**: Quick verification of redaction and encryption

**Fields**:
- `username` (plaintext)
- `password` (sensitive, auto-detected from type)

**Test Cases**:

```bash
# Redaction (no service required)
typedialog form examples/08-encryption/simple-login.toml \
  --redact --format json

# Age encryption (requires ~/.age/key.txt)
typedialog form examples/08-encryption/simple-login.toml \
  --encrypt --backend age --key-file ~/.age/key.txt \
  --format json
```

**Expected Behavior**:
- Redaction: `password` shows `[REDACTED]`
- Age encryption: `password` shows `age1-...` (Age ciphertext)

---

### 2. `credentials.toml` - Full Example

**Purpose**: Comprehensive demonstration of encryption features

**Fields**:
- **Non-sensitive**: username, email, company
- **Auto-detected**: password, confirm_password (type=password)
- **Explicitly sensitive**: api_token, ssh_key, database_url, vault_token
- **Override**: demo_password (type=password but sensitive=false)

**Features Demonstrated**:
- Sensitive field auto-detection from FieldType
- Explicit sensitivity marking
- Field-level encryption backend specification
- Encryption config per field (vault_addr, key_path)

**Test Cases**:

```bash
# Show all sensitive fields redacted
typedialog form examples/08-encryption/credentials.toml \
  --redact --format json

# Output format:
# {
#   "username": "alice",
#   "email": "alice@example.com",
#   "company": "Acme Corp",
#   "password": "[REDACTED]",
#   "confirm_password": "[REDACTED]",
#   "api_token": "[REDACTED]",
#   "ssh_key": "[REDACTED]",
#   "database_url": "[REDACTED]",
#   "vault_token": "[REDACTED]",
#   "demo_password": "demo123"  <- Not redacted (explicit sensitive=false)
# }
```

```bash
# Encrypt with Age backend
typedialog form examples/08-encryption/credentials.toml \
  --encrypt --backend age \
  --key-file ~/.age/key.txt \
  --format json

# Output format:
# {
#   "username": "alice",
#   "email": "alice@example.com",
#   "password": "age1muz6ah54ew9am7mzmy0m4w5arcegt056l9448sqy5ju27q5qaf3qjv35tr",
#   "api_token": "age1muz6ah54ew9am7mzmy0m4w5arcegt056l9448sqy5ju27q5qaf3qjv35tr",
#   ...
# }
```

```bash
# Encrypt with SOPS (supports AWS KMS, GCP KMS, Azure Key Vault)
# First, create .sops.yaml in project root:
cat > .sops.yaml << 'EOF'
creation_rules:
  - path_regex: .*
    kms: arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012
EOF

# Then run:
export AWS_REGION=us-east-1
typedialog form examples/08-encryption/credentials.toml \
  --encrypt --backend sops \
  --format json

# Output format:
# {
#   "username": "alice",
#   "password": "sops:v1:4f5...",
#   ...
# }
```

```bash
# Or use SecretumVault Transit Engine (post-quantum cryptography ready)
export VAULT_ADDR="https://vault.internal:8200"
export VAULT_TOKEN="hvs.CAAA..."

typedialog form examples/08-encryption/credentials.toml \
  --encrypt --backend secretumvault \
  --vault-key-name "app-encryption-key" \
  --format json

# Output format:
# {
#   "username": "alice",
#   "password": "vault:v1:K8...",
#   ...
# }
```

---

### 3. `nickel-secrets.ncl` - Nickel Schema Definition

**Purpose**: Define encryption in Nickel schema language

**Syntax**:
```nickel
# Basic sensitive field (uses CLI backend)
password | Sensitive = ""

# Age encryption (local X25519)
password | Sensitive Backend="age" Key="~/.age/key.txt" = ""

# SOPS (multi-KMS via .sops.yaml)
database_password | Sensitive Backend="sops" = ""

# SecretumVault (post-quantum cryptography)
api_key | Sensitive Backend="secretumvault" Vault="https://vault:8200" Key="app-key" = ""

# AWS KMS (direct integration)
vault_token | Sensitive Backend="awskms" Region="us-east-1" KeyId="arn:aws:kms:..." = ""
```

**Usage**:

```bash
# 1. Query Nickel schema to extract metadata
nickel query examples/08-encryption/nickel-secrets.ncl inputs

# 2. Parse to TypeDialogConfig/Form (generates TOML with encryption_config)
# (Requires nickel CLI and typedialog integration - future feature)

# 3. Or manually convert to TOML matching this structure
```

**Equivalent TOML representation**:
```toml
[[fields]]
name = "password"
type = "password"
sensitive = true
encryption_backend = "age"

[fields.encryption_config]
key = "~/.age/key.txt"
```

---

## Testing Checklist

### 1. Redaction (No Service)
- [ ] Run: `typedialog form examples/08-encryption/simple-login.toml --redact --format json`
- [ ] Verify: `password` field shows `[REDACTED]`
- [ ] Verify: `username` field shows entered value

### 2. Age Encryption (With Key File)
- [ ] Key file exists: `cat ~/.age/key.txt`
- [ ] Run: `typedialog form examples/08-encryption/simple-login.toml --encrypt --backend age --key-file ~/.age/key.txt --format json`
- [ ] Verify: `password` field shows `age1-...` (not plaintext)
- [ ] Verify: `username` field shows plaintext

### 3. SOPS Encryption (Optional, Requires .sops.yaml and KMS)
- [ ] Install sops: `brew install sops` or `apt-get install sops`
- [ ] Create `.sops.yaml` with KMS configuration
- [ ] Configure KMS credentials (AWS_REGION, AWS_PROFILE, etc.)
- [ ] Run: `typedialog form examples/08-encryption/simple-login.toml --encrypt --backend sops --format json`
- [ ] Verify: `password` field shows `sops:v1:...` (not plaintext)

### 4. SecretumVault (Optional, Requires Vault Service)
- [ ] Service running: `curl https://vault.internal:8200/v1/sys/health`
- [ ] Set environment: `export VAULT_ADDR=https://vault:8200 VAULT_TOKEN=token`
- [ ] Run: `typedialog form examples/08-encryption/simple-login.toml --encrypt --backend secretumvault --format json`
- [ ] Verify: `password` field shows `vault:v1:...` (not plaintext)

### 4. Field-Level Encryption Config
- [ ] Run with `credentials.toml`: Fields with explicit `encryption_backend` use their config
- [ ] Run with CLI `--backend age`: Fields without explicit config use Age
- [ ] Verify mixed backends work correctly

---

## Output Examples

### Redaction Output
```json
{
  "username": "alice",
  "email": "alice@example.com",
  "password": "[REDACTED]",
  "api_token": "[REDACTED]",
  "demo_password": "visible"
}
```

### Age Encryption Output
```json
{
  "username": "alice",
  "email": "alice@example.com",
  "password": "age1muz6ah54ew9am7mzmy0m4w5arcegt056l9448sqy5ju27q5qaf3qjv35tr",
  "api_token": "age1muz6ah54ew9am7mzmy0m4w5arcegt056l9448sqy5ju27q5qaf3qjv35tr",
  "demo_password": "visible"
}
```

### SOPS Encryption Output
```json
{
  "username": "alice",
  "email": "alice@example.com",
  "password": "sops:v1:4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f",
  "api_token": "sops:v1:5g6h7i8j9k0l1m2n3o4p5q6r7s8t9u0v1w2x3y4z5a6b7c8d9e0f1g2h3i4j5k",
  "demo_password": "visible"
}
```

### SecretumVault Encryption Output
```json
{
  "username": "alice",
  "email": "alice@example.com",
  "password": "vault:v1:KX1LZ8/PvEgMuKQBhDm8PQMLCMiSvE...",
  "api_token": "vault:v1:KX1LZ8/PvEgMuKQBhDm8PQMLCMiSvE...",
  "demo_password": "visible"
}
```

---

## Documentation References

- **Setup Guide**: See `docs/ENCRYPTION-SERVICES-SETUP.md`
- **Quick Start**: See `docs/ENCRYPTION-QUICK-START.md`
- **Implementation Status**: See `docs/ENCRYPTION-IMPLEMENTATION-STATUS.md`

---

## Integration with CI/CD

These examples can be used for automated testing:

```bash
# Integration test script
#!/bin/bash

# Test 1: Redaction
typedialog form examples/08-encryption/simple-login.toml --redact --format json | \
  jq -e '.password == "[REDACTED]"' || exit 1

# Test 2: Age encryption (if key exists)
if [ -f ~/.age/key.txt ]; then
  OUTPUT=$(typedialog form examples/08-encryption/simple-login.toml \
    --encrypt --backend age --key-file ~/.age/key.txt --format json)

  # Verify ciphertext format
  echo "$OUTPUT" | jq -e '.password | startswith("age1-")' || exit 1
fi

echo "All tests passed!"
```