TypeDialog/docs/encryption/README.md

TypeDialog Encryption

Complete guide to encryption and secure field handling in TypeDialog.

Overview

TypeDialog provides comprehensive encryption support for sensitive data across all backends (CLI, TUI, Web). Encrypt fields at rest, in transit, and during processing with multiple encryption providers.

Documentation

Document	Purpose
encryption-quick-start.md	Get started with encryption in 5 minutes
encryption-services-setup.md	Configure encryption services (AWS KMS, GCP KMS, Vault)
encryption-unified-architecture.md	Architecture and design decisions

Quick Start

1. Mark Sensitive Fields

[[fields]]
name = "password"
field_type = "Password"
encrypted = true
```text

### 2. Choose Encryption Provider

```toml
[encryption]
provider = "aws_kms"  # or "gcp_kms", "vault", "local"
key_id = "arn:aws:kms:us-east-1:..."
```text

### 3. Run with Encryption Enabled

```bash
typedialog form config.toml --encrypt
```text

## Supported Backends

| Backend | Encryption Support | Notes |
 | --------- | ------------------- | ------- |
| **CLI** | ✅ Full | Encrypts before output |
| **TUI** | ✅ Full | Masked input, encrypted storage |
| **Web** | ✅ Full | HTTPS required, encrypted at rest |

## Encryption Providers

### AWS KMS

Enterprise-grade encryption with AWS Key Management Service.

- Automatic key rotation
- CloudTrail audit logging
- FIPS 140-2 validated

### GCP Cloud KMS

Google Cloud's managed encryption service.

- Hardware Security Module (HSM) support
- Automatic key versioning
- IAM integration

### HashiCorp Vault

Self-hosted secret management and encryption.

- Dynamic secrets
- Fine-grained access control
- Audit logging

### Local (Development)

Local encryption for development and testing.

- No external dependencies
- Not recommended for production

## Features

- **Field-level encryption** - Encrypt specific fields, not entire forms
- **Multiple providers** - Choose the right provider for your environment
- **Automatic decryption** - Transparent decryption when authorized
- **Audit logging** - Track all encryption/decryption operations
- **Key rotation** - Automatic key rotation support (AWS KMS, GCP KMS)

## Use Cases

### 1. PII Protection

Encrypt personally identifiable information (names, emails, SSNs).

### 2. Credential Management

Secure API keys, passwords, and tokens.

### 3. Compliance

Meet GDPR, HIPAA, SOC 2 requirements.

### 4. Multi-tenant SaaS

Isolate customer data with separate encryption keys.

## Security Best Practices

1. **Use managed services** - Prefer AWS KMS or GCP KMS over local encryption
2. **Enable key rotation** - Rotate encryption keys regularly
3. **Audit access** - Monitor who accesses encrypted data
4. **Encrypt in transit** - Always use HTTPS for web backend
5. **Validate inputs** - Sanitize before encryption to prevent injection

## Examples

See [examples/08-encryption/](../../examples/08-encryption/) for working examples:

- Basic field encryption
- Multiple encryption providers
- Key rotation
- Compliance scenarios

## Related Documentation

- [Field Types](../field-types.md) - Field type reference including `encrypted` attribute
- [Configuration](../configuration.md) - Backend configuration with encryption
- [Web Backend](../web/) - HTTPS and transport security

## Troubleshooting

### "Encryption provider not configured"

Set provider in config:

```toml
[encryption]
provider = "aws_kms"
key_id = "..."
```text

### "Failed to decrypt"

- Check key permissions
- Verify key ID is correct
- Ensure provider credentials are set

### "HTTPS required for encrypted fields"

Web backend requires HTTPS when encryption is enabled. Configure TLS certificates.

---

**Next Steps:**

1. Read [encryption-quick-start.md](encryption-quick-start.md)
2. Configure your provider: [encryption-services-setup.md](encryption-services-setup.md)
3. Review architecture: [encryption-unified-architecture.md](encryption-unified-architecture.md)