fix(dns): query _gondulf subdomain for domain verification
The DNS TXT verification was querying the base domain instead of
_gondulf.{domain}, causing verification to always fail even when
users had correctly configured their DNS records.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
76
docs/decisions/ADR-011-dns-txt-subdomain-prefix.md
Normal file
76
docs/decisions/ADR-011-dns-txt-subdomain-prefix.md
Normal file
@@ -0,0 +1,76 @@
|
||||
# ADR-011. DNS TXT Record Subdomain Prefix
|
||||
|
||||
Date: 2024-11-22
|
||||
|
||||
## Status
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
For DNS-based domain verification, we need users to prove they control a domain by setting a TXT record. There are two common approaches:
|
||||
|
||||
1. **Direct domain TXT record**: Place the verification value directly on the domain (e.g., TXT record on `example.com`)
|
||||
2. **Subdomain prefix**: Use a specific subdomain for verification (e.g., TXT record on `_gondulf.example.com`)
|
||||
|
||||
The direct approach seems simpler but has significant drawbacks:
|
||||
- Conflicts with existing TXT records (SPF, DKIM, DMARC, domain verification for other services)
|
||||
- Clutters the main domain's DNS records
|
||||
- Makes it harder to identify which TXT record is for which service
|
||||
- Some DNS providers limit the number of TXT records on the root domain
|
||||
|
||||
The subdomain approach is widely used by major services:
|
||||
- Google uses `_domainkey` for DKIM
|
||||
- Various services use `_acme-challenge` for Let's Encrypt domain validation
|
||||
- GitHub uses `_github-challenge` for domain verification
|
||||
- Many OAuth/OIDC providers use service-specific prefixes
|
||||
|
||||
## Decision
|
||||
|
||||
We will use the subdomain prefix approach with `_gondulf.{domain}` for DNS TXT record verification.
|
||||
|
||||
The TXT record requirements:
|
||||
- **Location**: `_gondulf.{domain}` (e.g., `_gondulf.example.com`)
|
||||
- **Value**: `gondulf-verify-domain`
|
||||
- **Type**: TXT record
|
||||
|
||||
This approach follows industry best practices and RFC conventions for using underscore-prefixed subdomains for protocol-specific purposes.
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive Consequences
|
||||
|
||||
1. **No Conflicts**: Won't interfere with existing TXT records on the main domain
|
||||
2. **Clear Purpose**: The `_gondulf` prefix clearly identifies this as Gondulf-specific
|
||||
3. **Industry Standard**: Follows the same pattern as DKIM, ACME, and other protocols
|
||||
4. **Clean DNS**: Keeps the main domain's DNS records uncluttered
|
||||
5. **Multiple Services**: Users can have multiple IndieAuth servers verified without conflicts
|
||||
6. **Easy Removal**: Users can easily identify and remove Gondulf verification when needed
|
||||
|
||||
### Negative Consequences
|
||||
|
||||
1. **Slightly More Complex**: Users must understand subdomain DNS records (though this is standard)
|
||||
2. **Documentation Critical**: Must clearly document the exact subdomain format
|
||||
3. **DNS Propagation**: Subdomain records may propagate differently than root domain records
|
||||
4. **Wildcard Conflicts**: May conflict with wildcard DNS records (though underscore prefix minimizes this)
|
||||
|
||||
### Implementation Considerations
|
||||
|
||||
1. **Clear Instructions**: The error messages and documentation must clearly show `_gondulf.{domain}` format
|
||||
2. **DNS Query Logic**: The code must prefix the domain with `_gondulf.` before querying
|
||||
3. **Validation**: Must handle cases where users accidentally set the record on the wrong location
|
||||
4. **Debugging**: Logs should clearly show which domain was queried to aid troubleshooting
|
||||
|
||||
## Alternative Considered
|
||||
|
||||
**Direct TXT on root domain** was considered but rejected due to:
|
||||
- High likelihood of conflicts with existing TXT records
|
||||
- Poor service isolation
|
||||
- Difficulty in identifying ownership of TXT records
|
||||
- Goes against industry best practices
|
||||
|
||||
## References
|
||||
|
||||
- RFC 8552: Scoped Interpretation of DNS Resource Records through "Underscored" Naming
|
||||
- DKIM (RFC 6376): Uses `_domainkey` subdomain
|
||||
- ACME (RFC 8555): Uses `_acme-challenge` subdomain
|
||||
- Industry examples: GitHub (`_github-challenge`), various OAuth providers
|
||||
Reference in New Issue
Block a user