# Dynamic Secrets Guide

This guide covers generating and managing temporary credentials (dynamic secrets) instead of using static secrets. See the Quick Reference section below for fast lookup.

## Quick Reference

**Quick Start**: Generate temporary credentials instead of using static secrets

### Quick Commands

#### Generate AWS Credentials (1 hour)

```nushell
secrets generate aws --role deploy --workspace prod --purpose "deployment"
```

#### Generate SSH Key (2 hours)

```nushell
secrets generate ssh --ttl 2 --workspace dev --purpose "server access"
```

#### Generate UpCloud Subaccount (2 hours)

```nushell
secrets generate upcloud --workspace staging --purpose "testing"
```

#### List Active Secrets

```nushell
secrets list
```

#### Revoke Secret

```nushell
secrets revoke <secret-id> --reason "no longer needed"
```

#### View Statistics

```nushell
secrets stats
```

---

## Secret Types

| Type | TTL Range | Renewable | Use Case |
|------|-----------|-----------|----------|
| AWS STS | 15 min - 12 h | ✅ Yes | Cloud resource provisioning |
| SSH Keys | 10 min - 24 h | ❌ No | Temporary server access |
| UpCloud | 30 min - 8 h | ❌ No | UpCloud API operations |
| Vault | 5 min - 24 h | ✅ Yes | Any Vault-backed secret |

---

## REST API Endpoints

**Base URL**: `http://localhost:9090/api/v1/secrets`

```bash
# Generate secret
POST /generate

# Get secret
GET /{id}

# Revoke secret
POST /{id}/revoke

# Renew secret
POST /{id}/renew

# List secrets
GET /list

# List expiring
GET /expiring

# Statistics
GET /stats
```

---

## AWS STS Example

```nushell
# Generate
let creds = secrets generate aws `
    --role deploy `
    --region us-west-2 `
    --workspace prod `
    --purpose "Deploy servers"

# Export to environment
export-env {
    AWS_ACCESS_KEY_ID: ($creds.credentials.access_key_id)
    AWS_SECRET_ACCESS_KEY: ($creds.credentials.secret_access_key)
    AWS_SESSION_TOKEN: ($creds.credentials.session_token)
}

# Use credentials
provisioning server create

# Cleanup
secrets revoke ($creds.id) --reason "done"
```

---

## SSH Key Example

```nushell
# Generate
let key = secrets generate ssh `
    --ttl 4 `
    --workspace dev `
    --purpose "Debug issue"

# Save key
$key.credentials.private_key | save ~/.ssh/temp_key
chmod 600 ~/.ssh/temp_key

# Use key
ssh -i ~/.ssh/temp_key user@server

# Cleanup
rm ~/.ssh/temp_key
secrets revoke ($key.id) --reason "fixed"
```

---

## Configuration

**File**: `provisioning/platform/orchestrator/config.defaults.toml`

```toml
[secrets]
default_ttl_hours = 1
max_ttl_hours = 12
auto_revoke_on_expiry = true
warning_threshold_minutes = 5

aws_account_id = "123456789012"
aws_default_region = "us-east-1"

upcloud_username = "${UPCLOUD_USER}"
upcloud_password = "${UPCLOUD_PASS}"
```

---

## Troubleshooting

### "Provider not found"

→ Check service initialization

### "TTL exceeds maximum"

→ Reduce TTL or configure higher max

### "Secret not renewable"

→ Generate new secret instead

### "Missing required parameter"

→ Check provider requirements (for example, AWS needs 'role')

---

## Security Features

- ✅ No static credentials stored
- ✅ Automatic expiration (1-12 hours)
- ✅ Auto-revocation on expiry
- ✅ Full audit trail
- ✅ Memory-only storage
- ✅ TLS in transit

---

## Support

**Orchestrator logs**: `provisioning/platform/orchestrator/data/orchestrator.log`

**Debug secrets**: `secrets list | where is_expired == true`
