800 lines
32 KiB
Markdown
800 lines
32 KiB
Markdown
# DNS Providers — Implementation Spec
|
||
|
||
This document was relocated from the former multi-topic [docs/plans/current_spec.md](../plans/current_spec.md) to keep the current plan index SSRF-only.
|
||
|
||
----
|
||
|
||
## 2. Scope & Acceptance Criteria
|
||
|
||
### In Scope
|
||
|
||
- DNSProvider model with encrypted credential storage
|
||
- API endpoints for DNS provider CRUD operations
|
||
- Provider connectivity testing (pre-save and post-save)
|
||
- Caddy DNS challenge configuration generation
|
||
- Frontend management UI for DNS providers
|
||
- Integration with proxy host creation (wildcard detection)
|
||
- Support for major DNS providers: Cloudflare, Route53, DigitalOcean, Google Cloud DNS, Namecheap, GoDaddy, Azure DNS, Hetzner, Vultr, DNSimple
|
||
|
||
### Out of Scope (Future Iterations)
|
||
|
||
- Multi-credential per provider (zone-specific credentials)
|
||
- Key rotation automation
|
||
- DNS provider auto-detection
|
||
- Custom DNS provider plugins
|
||
|
||
### Acceptance Criteria
|
||
|
||
- [ ] Users can add, edit, delete, and test DNS provider configurations
|
||
- [ ] Credentials are encrypted at rest using AES-256-GCM
|
||
- [ ] Credentials are **never** exposed in API responses (masked or omitted)
|
||
- [ ] Proxy hosts with wildcard domains can select a DNS provider
|
||
- [ ] Caddy successfully obtains wildcard certificates using DNS-01 challenge
|
||
- [ ] Backend unit test coverage ≥ 85%
|
||
- [ ] Frontend unit test coverage ≥ 85%
|
||
- [ ] User documentation completed
|
||
- [ ] All translations added for new UI strings
|
||
|
||
----
|
||
|
||
## 3. Technical Architecture
|
||
|
||
### Component Diagram
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ FRONTEND │
|
||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────────┐ │
|
||
│ │ DNSProviders │ │ DNSProviderForm │ │ ProxyHostForm │ │
|
||
│ │ Page │ │ (Add/Edit) │ │ (Wildcard + Provider Select)│ │
|
||
│ └────────┬────────┘ └────────┬────────┘ └─────────────┬───────────────┘ │
|
||
│ │ │ │ │
|
||
│ └────────────────────┼─────────────────────────┘ │
|
||
│ ▼ │
|
||
│ ┌───────────────────────┐ │
|
||
│ │ api/dnsProviders.ts │ │
|
||
│ │ hooks/useDNSProviders │ │
|
||
│ └───────────┬───────────┘ │
|
||
└────────────────────────────────┼─────────────────────────────────────────────┘
|
||
│ HTTP/JSON
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ BACKEND │
|
||
│ ┌────────────────────────────────────────────────────────────────────────┐ │
|
||
│ │ API Layer (Gin Router) │ │
|
||
│ │ /api/v1/dns-providers/* → dns_provider_handler.go │ │
|
||
│ └────────────────────────────────┬───────────────────────────────────────┘ │
|
||
│ ▼ │
|
||
│ ┌────────────────────────────────────────────────────────────────────────┐ │
|
||
│ │ Service Layer │
|
||
│ │ dns_provider_service.go ←→ crypto/encryption.go (AES-256-GCM) │
|
||
│ └────────────────────────────────┬───────────────────────────────────────┘ │
|
||
│ ▼ │
|
||
│ ┌────────────────────────────────────────────────────────────────────────┐ │
|
||
│ │ Data Layer (GORM) │
|
||
│ │ models/dns_provider.go │ models/proxy_host.go (extended) │
|
||
│ └────────────────────────────────┬───────────────────────────────────────┘ │
|
||
│ ▼ │
|
||
│ ┌────────────────────────────────────────────────────────────────────────┐ │
|
||
│ │ Caddy Integration │
|
||
│ │ caddy/config.go → DNS Challenge Issuer Config → Caddy Admin API │ │
|
||
│ └────────────────────────────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ DNS PROVIDER │
|
||
│ (Cloudflare, Route53, etc.) │
|
||
│ TXT Record: _acme-challenge.example.com │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Data Flow for DNS Challenge
|
||
|
||
```
|
||
1. User creates ProxyHost with *.example.com + selects DNSProvider
|
||
│
|
||
▼
|
||
2. Backend validates request, fetches DNSProvider credentials (decrypted)
|
||
│
|
||
▼
|
||
3. Caddy Manager generates config with DNS challenge issuer:
|
||
{
|
||
"module": "acme",
|
||
"challenges": {
|
||
"dns": {
|
||
"provider": { "name": "cloudflare", "api_token": "..." }
|
||
}
|
||
}
|
||
}
|
||
│
|
||
▼
|
||
4. Caddy applies config → initiates ACME order → requests DNS challenge
|
||
│
|
||
▼
|
||
5. Caddy's DNS provider module creates TXT record via DNS API
|
||
│
|
||
▼
|
||
6. ACME server validates TXT record → issues certificate
|
||
│
|
||
▼
|
||
7. Caddy stores certificate → serves HTTPS for *.example.com
|
||
```
|
||
|
||
----
|
||
|
||
## 4. Database Schema
|
||
|
||
### DNSProvider Model
|
||
|
||
```go
|
||
// File: backend/internal/models/dns_provider.go
|
||
|
||
// DNSProvider represents a DNS provider configuration for ACME DNS-01 challenges.
|
||
type DNSProvider struct {
|
||
ID uint `json:"id" gorm:"primaryKey"`
|
||
UUID string `json:"uuid" gorm:"uniqueIndex;size:36"`
|
||
Name string `json:"name" gorm:"index;not null;size:255"`
|
||
ProviderType string `json:"provider_type" gorm:"index;not null;size:50"`
|
||
Enabled bool `json:"enabled" gorm:"default:true;index"`
|
||
IsDefault bool `json:"is_default" gorm:"default:false"`
|
||
|
||
// Encrypted credentials (JSON blob, encrypted with AES-256-GCM)
|
||
CredentialsEncrypted string `json:"-" gorm:"type:text;column:credentials_encrypted"`
|
||
|
||
// Propagation settings
|
||
PropagationTimeout int `json:"propagation_timeout" gorm:"default:120"` // seconds
|
||
PollingInterval int `json:"polling_interval" gorm:"default:5"` // seconds
|
||
|
||
// Usage tracking
|
||
LastUsedAt *time.Time `json:"last_used_at,omitempty"`
|
||
SuccessCount int `json:"success_count" gorm:"default:0"`
|
||
FailureCount int `json:"failure_count" gorm:"default:0"`
|
||
LastError string `json:"last_error,omitempty" gorm:"type:text"`
|
||
|
||
CreatedAt time.Time `json:"created_at"`
|
||
UpdatedAt time.Time `json:"updated_at"`
|
||
}
|
||
|
||
// TableName specifies the database table name
|
||
func (DNSProvider) TableName() string {
|
||
return "dns_providers"
|
||
}
|
||
```
|
||
|
||
### ProxyHost Extensions
|
||
|
||
```go
|
||
// File: backend/internal/models/proxy_host.go (additions)
|
||
|
||
type ProxyHost struct {
|
||
// ... existing fields ...
|
||
|
||
// DNS Challenge configuration
|
||
DNSProviderID *uint `json:"dns_provider_id,omitempty" gorm:"index"`
|
||
DNSProvider *DNSProvider `json:"dns_provider,omitempty" gorm:"foreignKey:DNSProviderID"`
|
||
UseDNSChallenge bool `json:"use_dns_challenge" gorm:"default:false"`
|
||
}
|
||
```
|
||
|
||
### Supported Provider Types
|
||
|
||
| Provider Type | Credential Fields | Caddy DNS Module |
|
||
|---------------|-------------------|------------------|
|
||
| `cloudflare` | `api_token` OR (`api_key`, `email`) | `cloudflare` |
|
||
| `route53` | `access_key_id`, `secret_access_key`, `region` | `route53` |
|
||
| `digitalocean` | `auth_token` | `digitalocean` |
|
||
| `googleclouddns` | `service_account_json`, `project` | `googleclouddns` |
|
||
| `namecheap` | `api_user`, `api_key`, `client_ip` | `namecheap` |
|
||
| `godaddy` | `api_key`, `api_secret` | `godaddy` |
|
||
| `azure` | `tenant_id`, `client_id`, `client_secret`, `subscription_id`, `resource_group` | `azuredns` |
|
||
| `hetzner` | `api_key` | `hetzner` |
|
||
| `vultr` | `api_key` | `vultr` |
|
||
| `dnsimple` | `oauth_token`, `account_id` | `dnsimple` |
|
||
|
||
----
|
||
|
||
## 5. API Specification
|
||
|
||
### Endpoints
|
||
|
||
| Method | Endpoint | Description |
|
||
|--------|----------|-------------|
|
||
| `GET` | `/api/v1/dns-providers` | List all DNS providers |
|
||
| `POST` | `/api/v1/dns-providers` | Create new DNS provider |
|
||
| `GET` | `/api/v1/dns-providers/:id` | Get provider details |
|
||
| `PUT` | `/api/v1/dns-providers/:id` | Update provider |
|
||
| `DELETE` | `/api/v1/dns-providers/:id` | Delete provider |
|
||
| `POST` | `/api/v1/dns-providers/:id/test` | Test saved provider |
|
||
| `POST` | `/api/v1/dns-providers/test` | Test credentials (pre-save) |
|
||
| `GET` | `/api/v1/dns-providers/types` | List supported provider types |
|
||
|
||
### Request/Response Schemas
|
||
|
||
#### Create DNS Provider
|
||
|
||
**Request:** `POST /api/v1/dns-providers`
|
||
|
||
```json
|
||
{
|
||
"name": "Production Cloudflare",
|
||
"provider_type": "cloudflare",
|
||
"credentials": {
|
||
"api_token": "xxxxxxxxxxxxxxxxxxxxxxxxxx"
|
||
},
|
||
"propagation_timeout": 120,
|
||
"polling_interval": 5,
|
||
"is_default": true
|
||
}
|
||
```
|
||
|
||
**Response:** `201 Created`
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"uuid": "550e8400-e29b-41d4-a716-446655440000",
|
||
"name": "Production Cloudflare",
|
||
"provider_type": "cloudflare",
|
||
"enabled": true,
|
||
"is_default": true,
|
||
"has_credentials": true,
|
||
"propagation_timeout": 120,
|
||
"polling_interval": 5,
|
||
"success_count": 0,
|
||
"failure_count": 0,
|
||
"created_at": "2026-01-01T12:00:00Z",
|
||
"updated_at": "2026-01-01T12:00:00Z"
|
||
}
|
||
```
|
||
|
||
#### List DNS Providers
|
||
|
||
**Response:** `GET /api/v1/dns-providers` → `200 OK`
|
||
|
||
```json
|
||
{
|
||
"providers": [
|
||
{
|
||
"id": 1,
|
||
"uuid": "550e8400-e29b-41d4-a716-446655440000",
|
||
"name": "Production Cloudflare",
|
||
"provider_type": "cloudflare",
|
||
"enabled": true,
|
||
"is_default": true,
|
||
"has_credentials": true,
|
||
"propagation_timeout": 120,
|
||
"polling_interval": 5,
|
||
"last_used_at": "2026-01-01T10:30:00Z",
|
||
"success_count": 15,
|
||
"failure_count": 0,
|
||
"created_at": "2025-12-01T08:00:00Z",
|
||
"updated_at": "2026-01-01T10:30:00Z"
|
||
}
|
||
],
|
||
"total": 1
|
||
}
|
||
```
|
||
|
||
#### Test DNS Provider
|
||
|
||
**Request:** `POST /api/v1/dns-providers/:id/test`
|
||
|
||
**Response:** `200 OK`
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "DNS provider credentials validated successfully",
|
||
"propagation_time_ms": 2340
|
||
}
|
||
```
|
||
|
||
**Error Response:** `400 Bad Request`
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": "Authentication failed: invalid API token",
|
||
"code": "INVALID_CREDENTIALS"
|
||
}
|
||
```
|
||
|
||
#### Get Provider Types
|
||
|
||
**Response:** `GET /api/v1/dns-providers/types` → `200 OK`
|
||
|
||
```json
|
||
{
|
||
"types": [
|
||
{
|
||
"type": "cloudflare",
|
||
"name": "Cloudflare",
|
||
"fields": [
|
||
{ "name": "api_token", "label": "API Token", "type": "password", "required": true, "hint": "Token with Zone:DNS:Edit permissions" }
|
||
],
|
||
"documentation_url": "https://developers.cloudflare.com/api/tokens/"
|
||
},
|
||
{
|
||
"type": "route53",
|
||
"name": "Amazon Route 53",
|
||
"fields": [
|
||
{ "name": "access_key_id", "label": "Access Key ID", "type": "text", "required": true },
|
||
{ "name": "secret_access_key", "label": "Secret Access Key", "type": "password", "required": true },
|
||
{ "name": "region", "label": "AWS Region", "type": "text", "required": true, "default": "us-east-1" }
|
||
],
|
||
"documentation_url": "https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/dns-routing-traffic.html"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
----
|
||
|
||
## 6. Backend Implementation
|
||
|
||
### Phase 1: Encryption Package + DNSProvider Model (~2-3 hours)
|
||
|
||
**Objective:** Create secure credential storage foundation
|
||
|
||
#### Files to Create
|
||
|
||
| File | Description | Complexity |
|
||
|------|-------------|------------|
|
||
| `backend/internal/crypto/encryption.go` | AES-256-GCM encryption service | Medium |
|
||
| `backend/internal/crypto/encryption_test.go` | Encryption unit tests | Low |
|
||
| `backend/internal/models/dns_provider.go` | DNSProvider model + validation | Medium |
|
||
|
||
#### Implementation Details
|
||
|
||
**Encryption Service:**
|
||
|
||
```go
|
||
// backend/internal/crypto/encryption.go
|
||
package crypto
|
||
|
||
type EncryptionService struct {
|
||
key []byte // 32 bytes for AES-256
|
||
}
|
||
|
||
func NewEncryptionService(keyBase64 string) (*EncryptionService, error)
|
||
func (s *EncryptionService) Encrypt(plaintext []byte) (string, error)
|
||
func (s *EncryptionService) Decrypt(ciphertextB64 string) ([]byte, error)
|
||
```
|
||
|
||
**Configuration Extension:**
|
||
|
||
```go
|
||
// backend/internal/config/config.go (add)
|
||
EncryptionKey string `env:"CHARON_ENCRYPTION_KEY"`
|
||
```
|
||
|
||
### Phase 2: Service Layer + Handlers (~2-3 hours)
|
||
|
||
**Objective:** Build DNS provider CRUD operations
|
||
|
||
#### Files to Create
|
||
|
||
| File | Description | Complexity |
|
||
|------|-------------|------------|
|
||
| `backend/internal/services/dns_provider_service.go` | DNS provider CRUD + crypto integration | High |
|
||
| `backend/internal/services/dns_provider_service_test.go` | Service unit tests | Medium |
|
||
| `backend/internal/api/handlers/dns_provider_handler.go` | HTTP handlers | Medium |
|
||
| `backend/internal/api/handlers/dns_provider_handler_test.go` | Handler unit tests | Medium |
|
||
|
||
#### Service Interface
|
||
|
||
```go
|
||
type DNSProviderService interface {
|
||
List(ctx context.Context) ([]DNSProvider, error)
|
||
Get(ctx context.Context, id uint) (*DNSProvider, error)
|
||
Create(ctx context.Context, req CreateDNSProviderRequest) (*DNSProvider, error)
|
||
Update(ctx context.Context, id uint, req UpdateDNSProviderRequest) (*DNSProvider, error)
|
||
Delete(ctx context.Context, id uint) error
|
||
Test(ctx context.Context, id uint) (*TestResult, error)
|
||
TestCredentials(ctx context.Context, req CreateDNSProviderRequest) (*TestResult, error)
|
||
GetDecryptedCredentials(ctx context.Context, id uint) (map[string]string, error)
|
||
}
|
||
```
|
||
|
||
### Phase 3: Caddy Integration (~2 hours)
|
||
|
||
**Objective:** Generate DNS challenge configuration for Caddy
|
||
|
||
#### Files to Modify
|
||
|
||
| File | Changes | Complexity |
|
||
|------|---------|------------|
|
||
| `backend/internal/caddy/types.go` | Add `DNSChallengeConfig`, `ChallengesConfig` types | Low |
|
||
| `backend/internal/caddy/config.go` | Add DNS challenge issuer generation logic | High |
|
||
| `backend/internal/caddy/manager.go` | Fetch DNS providers when applying config | Medium |
|
||
| `backend/internal/api/routes/routes.go` | Register DNS provider routes | Low |
|
||
|
||
#### Caddy Types Addition
|
||
|
||
```go
|
||
// backend/internal/caddy/types.go
|
||
|
||
type DNSChallengeConfig struct {
|
||
Provider map[string]any `json:"provider"`
|
||
PropagationTimeout int64 `json:"propagation_timeout,omitempty"` // nanoseconds
|
||
Resolvers []string `json:"resolvers,omitempty"`
|
||
}
|
||
|
||
type ChallengesConfig struct {
|
||
DNS *DNSChallengeConfig `json:"dns,omitempty"`
|
||
}
|
||
```
|
||
|
||
----
|
||
|
||
## 7. Frontend Implementation
|
||
|
||
### Phase 1: API Client + Hooks (~1-2 hours)
|
||
|
||
**Objective:** Establish data layer for DNS providers
|
||
|
||
#### Files to Create
|
||
|
||
| File | Description | Complexity |
|
||
|------|-------------|------------|
|
||
| `frontend/src/api/dnsProviders.ts` | API client functions | Low |
|
||
| `frontend/src/hooks/useDNSProviders.ts` | React Query hooks | Low |
|
||
| `frontend/src/data/dnsProviderSchemas.ts` | Provider field definitions | Low |
|
||
|
||
### Phase 2: DNS Providers Page (~2-3 hours)
|
||
|
||
**Objective:** Complete management UI for DNS providers
|
||
|
||
#### Files to Create
|
||
|
||
| File | Description | Complexity |
|
||
|------|-------------|------------|
|
||
| `frontend/src/pages/DNSProviders.tsx` | DNS providers list page | Medium |
|
||
| `frontend/src/components/DNSProviderForm.tsx` | Add/edit provider form | High |
|
||
| `frontend/src/components/DNSProviderCard.tsx` | Provider card component | Low |
|
||
|
||
#### UI Wireframe
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ DNS Providers [+ Add Provider] │
|
||
│ Configure DNS providers for wildcard certificate issuance │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||
│ │ ℹ️ DNS providers are required to issue wildcard certificates │ │
|
||
│ │ (e.g., *.example.com) via Let's Encrypt. │ │
|
||
│ └─────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌─────────────────────────┐ ┌─────────────────────────┐ │
|
||
│ │ ☁️ Cloudflare │ │ 🔶 Route 53 │ │
|
||
│ │ Production Account │ │ AWS Dev Account │ │
|
||
│ │ ⭐ Default ✅ Active │ │ ✅ Active │ │
|
||
│ │ Last used: 2 hours ago │ │ Never used │ │
|
||
│ │ Success: 15 | Failed: 0 │ │ Success: 0 | Failed: 0 │ │
|
||
│ │ [Edit] [Test] [Delete] │ │ [Edit] [Test] [Delete] │ │
|
||
│ └─────────────────────────┘ └─────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Phase 3: Integration with Certificates/Proxy Hosts (~1-2 hours)
|
||
|
||
**Objective:** Connect DNS providers to certificate workflows
|
||
|
||
#### Files to Create
|
||
|
||
| File | Description | Complexity |
|
||
|------|-------------|------------|
|
||
| `frontend/src/components/DNSProviderSelector.tsx` | Dropdown selector | Low |
|
||
|
||
#### Files to Modify
|
||
|
||
| File | Changes | Complexity |
|
||
|------|---------|------------|
|
||
| `frontend/src/App.tsx` | Add `/dns-providers` route | Low |
|
||
| `frontend/src/components/layout/Layout.tsx` | Add navigation link | Low |
|
||
| `frontend/src/components/ProxyHostForm.tsx` | Add DNS provider selector for wildcards | Medium |
|
||
| `frontend/src/locales/en/translation.json` | Add translation keys | Low |
|
||
|
||
----
|
||
|
||
## 8. Security Requirements
|
||
|
||
### Encryption at Rest
|
||
|
||
- **Algorithm:** AES-256-GCM (authenticated encryption)
|
||
- **Key:** 32-byte key loaded from `CHARON_ENCRYPTION_KEY` environment variable
|
||
- **Format:** Base64-encoded ciphertext with prepended nonce
|
||
|
||
### Key Management
|
||
|
||
```bash
|
||
# Generate key (one-time setup)
|
||
openssl rand -base64 32
|
||
|
||
# Set environment variable
|
||
export CHARON_ENCRYPTION_KEY="<base64-encoded-32-byte-key>"
|
||
```
|
||
|
||
- Key MUST be stored in environment variable or secrets manager
|
||
- Key MUST NOT be committed to version control
|
||
- Key rotation support via `key_version` field (future)
|
||
|
||
### API Security
|
||
|
||
- Credentials **NEVER** returned in API responses
|
||
- Response includes only `has_credentials: true/false` indicator
|
||
- Update requests with empty `credentials` preserve existing values
|
||
- Audit logging for all credential access (create, update, decrypt for Caddy)
|
||
|
||
### Database Security
|
||
|
||
- `credentials_encrypted` column excluded from JSON serialization (`json:"-"`)
|
||
- Database backups should be encrypted separately
|
||
- Consider column-level encryption for additional defense-in-depth
|
||
|
||
----
|
||
|
||
## 9. Testing Strategy
|
||
|
||
### Backend Unit Tests (>85% Coverage)
|
||
|
||
| Test File | Coverage Target | Key Test Cases |
|
||
|-----------|-----------------|----------------|
|
||
| `crypto/encryption_test.go` | 100% | Encrypt/decrypt roundtrip, invalid key, tampered ciphertext |
|
||
| `models/dns_provider_test.go` | 90% | Model validation, table name |
|
||
| `services/dns_provider_service_test.go` | 85% | CRUD operations, encryption integration, error handling |
|
||
| `handlers/dns_provider_handler_test.go` | 85% | HTTP methods, validation errors, auth required |
|
||
|
||
### Frontend Unit Tests (>85% Coverage)
|
||
|
||
| Test File | Coverage Target | Key Test Cases |
|
||
|-----------|-----------------|----------------|
|
||
| `api/dnsProviders.test.ts` | 90% | API calls, error handling |
|
||
| `hooks/useDNSProviders.test.ts` | 85% | Query/mutation behavior |
|
||
| `pages/DNSProviders.test.tsx` | 80% | Render states, user interactions |
|
||
| `components/DNSProviderForm.test.tsx` | 85% | Form validation, submission |
|
||
|
||
### Integration Tests
|
||
|
||
| Test | Description |
|
||
|------|-------------|
|
||
| `integration/dns_provider_test.go` | Full CRUD flow with database |
|
||
| `integration/caddy_dns_challenge_test.go` | Config generation with DNS provider |
|
||
|
||
### Manual Test Scenarios
|
||
|
||
1. **Happy Path:**
|
||
- Create Cloudflare provider with valid API token
|
||
- Test connection (expect success)
|
||
- Create proxy host with `*.example.com`
|
||
- Verify Caddy requests DNS challenge
|
||
- Confirm certificate issued
|
||
|
||
2. **Error Handling:**
|
||
- Create provider with invalid credentials → test fails
|
||
- Delete provider in use by proxy host → error message
|
||
- Attempt wildcard without DNS provider → validation error
|
||
|
||
3. **Security:**
|
||
- GET provider → credentials NOT in response
|
||
- Update provider without credentials → preserves existing
|
||
- Audit log contains credential access events
|
||
|
||
----
|
||
|
||
## 10. Documentation Deliverables
|
||
|
||
### User Guide: DNS Providers
|
||
|
||
**Location:** `docs/guides/dns-providers.md`
|
||
|
||
**Contents:**
|
||
|
||
- What are DNS providers and why they're needed
|
||
- Setting up your first DNS provider
|
||
- Managing multiple providers
|
||
- Troubleshooting common issues
|
||
|
||
### Provider-Specific Setup Guides
|
||
|
||
**Location:** `docs/guides/dns-providers/`
|
||
|
||
| File | Provider |
|
||
|------|----------|
|
||
| `cloudflare.md` | Cloudflare (API token creation, permissions) |
|
||
| `route53.md` | AWS Route 53 (IAM policy, credentials) |
|
||
| `digitalocean.md` | DigitalOcean (token generation) |
|
||
| `google-cloud-dns.md` | Google Cloud DNS (service account setup) |
|
||
| `azure-dns.md` | Azure DNS (app registration, permissions) |
|
||
|
||
### Troubleshooting Guide
|
||
|
||
**Location:** `docs/troubleshooting/dns-challenges.md`
|
||
|
||
**Contents:**
|
||
|
||
- DNS propagation delays
|
||
- Permission/authentication errors
|
||
- Firewall considerations
|
||
- Debug logging
|
||
|
||
----
|
||
|
||
## 11. Risk Assessment
|
||
|
||
### Technical Risks
|
||
|
||
| Risk | Likelihood | Impact | Mitigation |
|
||
|------|------------|--------|------------|
|
||
| Encryption key loss | Low | Critical | Document key backup procedures, test recovery |
|
||
| DNS provider API changes | Medium | Medium | Abstract provider logic, version-specific adapters |
|
||
| Caddy DNS module incompatibility | Low | High | Test against specific Caddy version, pin dependencies |
|
||
| Credential exposure in logs | Medium | High | Audit all logging, mask sensitive fields |
|
||
| Performance impact of encryption | Low | Low | AES-NI hardware acceleration, minimal overhead |
|
||
|
||
### Mitigations
|
||
|
||
1. **Key Loss:** Require key backup during initial setup, document recovery procedures
|
||
2. **API Changes:** Use provider abstraction layer, monitor upstream changes
|
||
3. **Caddy Compatibility:** Pin Caddy version, comprehensive integration tests
|
||
4. **Log Exposure:** Structured logging with field masking, security audit
|
||
5. **Performance:** Benchmark encryption operations, consider caching decrypted creds briefly
|
||
|
||
----
|
||
|
||
## 12. Phased Delivery Timeline
|
||
|
||
| Phase | Description | Estimated Time | Dependencies |
|
||
|-------|-------------|----------------|--------------|
|
||
| **Phase 1** | Foundation (Encryption pkg, DNSProvider model, migrations) | 2-3 hours | None |
|
||
| **Phase 2** | Backend Service + API (CRUD handlers, validation) | 2-3 hours | Phase 1 |
|
||
| **Phase 3** | Caddy Integration (DNS challenge config generation) | 2 hours | Phase 2 |
|
||
| **Phase 4** | Frontend UI (Pages, forms, integration) | 3-4 hours | Phase 2 API |
|
||
| **Phase 5** | Testing & Documentation (Unit tests, guides) | 2-3 hours | All phases |
|
||
|
||
**Total Estimated Time: 11-15 hours**
|
||
|
||
### Dependency Graph
|
||
|
||
```
|
||
Phase 1 (Foundation)
|
||
│
|
||
├──► Phase 2 (Backend API)
|
||
│ │
|
||
│ ├──► Phase 3 (Caddy Integration)
|
||
│ │
|
||
│ └──► Phase 4 (Frontend UI)
|
||
│ │
|
||
└─────────────────┴──► Phase 5 (Testing & Docs)
|
||
```
|
||
|
||
----
|
||
|
||
## 13. Files to Create
|
||
|
||
### Backend
|
||
|
||
| Path | Description |
|
||
|------|-------------|
|
||
| `backend/internal/crypto/encryption.go` | AES-256-GCM encryption service |
|
||
| `backend/internal/crypto/encryption_test.go` | Encryption unit tests |
|
||
| `backend/internal/models/dns_provider.go` | DNSProvider model definition |
|
||
| `backend/internal/services/dns_provider_service.go` | DNS provider business logic |
|
||
| `backend/internal/services/dns_provider_service_test.go` | Service unit tests |
|
||
| `backend/internal/api/handlers/dns_provider_handler.go` | HTTP handlers |
|
||
| `backend/internal/api/handlers/dns_provider_handler_test.go` | Handler unit tests |
|
||
| `backend/integration/dns_provider_test.go` | Integration tests |
|
||
|
||
### Frontend
|
||
|
||
| Path | Description |
|
||
|------|-------------|
|
||
| `frontend/src/api/dnsProviders.ts` | API client functions |
|
||
| `frontend/src/hooks/useDNSProviders.ts` | React Query hooks |
|
||
| `frontend/src/data/dnsProviderSchemas.ts` | Provider field definitions |
|
||
| `frontend/src/pages/DNSProviders.tsx` | DNS providers page |
|
||
| `frontend/src/components/DNSProviderForm.tsx` | Add/edit form |
|
||
| `frontend/src/components/DNSProviderCard.tsx` | Provider card component |
|
||
| `frontend/src/components/DNSProviderSelector.tsx` | Dropdown selector |
|
||
|
||
### Documentation
|
||
|
||
| Path | Description |
|
||
|------|-------------|
|
||
| `docs/guides/dns-providers.md` | User guide |
|
||
| `docs/guides/dns-providers/cloudflare.md` | Cloudflare setup |
|
||
| `docs/guides/dns-providers/route53.md` | AWS Route 53 setup |
|
||
| `docs/guides/dns-providers/digitalocean.md` | DigitalOcean setup |
|
||
| `docs/troubleshooting/dns-challenges.md` | Troubleshooting guide |
|
||
|
||
----
|
||
|
||
## 14. Files to Modify
|
||
|
||
### Backend
|
||
|
||
| Path | Changes |
|
||
|------|---------|
|
||
| `backend/internal/config/config.go` | Add `EncryptionKey` field |
|
||
| `backend/internal/models/proxy_host.go` | Add `DNSProviderID`, `UseDNSChallenge` fields |
|
||
| `backend/internal/caddy/types.go` | Add `DNSChallengeConfig`, `ChallengesConfig` types |
|
||
| `backend/internal/caddy/config.go` | Add DNS challenge issuer generation |
|
||
| `backend/internal/caddy/manager.go` | Load DNS providers when applying config |
|
||
| `backend/internal/api/routes/routes.go` | Register DNS provider routes |
|
||
| `backend/internal/api/handlers/proxyhost_handler.go` | Handle DNS provider association |
|
||
| `backend/cmd/server/main.go` | Initialize encryption service |
|
||
|
||
### Frontend
|
||
|
||
| Path | Changes |
|
||
|------|---------|
|
||
| `frontend/src/App.tsx` | Add `/dns-providers` route |
|
||
| `frontend/src/components/layout/Layout.tsx` | Add navigation link to DNS Providers |
|
||
| `frontend/src/components/ProxyHostForm.tsx` | Add DNS provider selector for wildcard domains |
|
||
| `frontend/src/locales/en/translation.json` | Add `dnsProviders.*` translation keys |
|
||
|
||
----
|
||
|
||
## 15. Definition of Done Checklist
|
||
|
||
### Backend
|
||
|
||
- [ ] `crypto/encryption.go` implemented with AES-256-GCM
|
||
- [ ] `DNSProvider` model created with all fields
|
||
- [ ] Database migration created and tested
|
||
- [ ] `DNSProviderService` implements full CRUD
|
||
- [ ] Credentials encrypted on save, decrypted on demand
|
||
- [ ] API handlers for all endpoints
|
||
- [ ] Input validation on all endpoints
|
||
- [ ] Credentials never exposed in API responses
|
||
- [ ] Unit tests pass with ≥85% coverage
|
||
- [ ] Integration tests pass
|
||
|
||
### Caddy Integration
|
||
|
||
- [ ] DNS challenge config generated correctly
|
||
- [ ] ProxyHost correctly associated with DNSProvider
|
||
- [ ] Wildcard domains use DNS-01 challenge
|
||
- [ ] Non-wildcard domains continue using HTTP-01
|
||
|
||
### Frontend
|
||
|
||
- [ ] API client functions implemented
|
||
- [ ] React Query hooks working
|
||
- [ ] DNS Providers page lists all providers
|
||
- [ ] Add/Edit form with dynamic fields per provider
|
||
- [ ] Test connection button functional
|
||
- [ ] Provider selector in ProxyHost form
|
||
- [ ] Wildcard domain detection triggers DNS provider requirement
|
||
- [ ] All translations added
|
||
- [ ] Unit tests pass with ≥85% coverage
|
||
|
||
### Security
|
||
|
||
- [ ] Encryption key documented in setup guide
|
||
- [ ] Credentials encrypted at rest verified
|
||
- [ ] API responses verified to exclude credentials
|
||
- [ ] Audit logging for credential operations
|
||
- [ ] Security review completed
|
||
|
||
### Documentation
|
||
|
||
- [ ] User guide written
|
||
- [ ] Provider-specific guides written (at least Cloudflare, Route53)
|
||
- [ ] Troubleshooting guide written
|
||
- [ ] API documentation updated
|
||
- [ ] CHANGELOG updated
|
||
|
||
### Final Validation
|
||
|
||
- [ ] End-to-end test: Create DNS provider → Create wildcard proxy → Certificate issued
|
||
- [ ] Error scenarios tested (invalid creds, deleted provider)
|
||
- [ ] UI reviewed for accessibility
|
||
- [ ] Performance acceptable (no noticeable delays)
|
||
|
||
----
|
||
|
||
*Consolidated from backend and frontend research documents*
|
||
*Ready for implementation*
|