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:
2025-11-22 17:46:38 -07:00
parent bf69588426
commit 1ef5cd9229
5 changed files with 548 additions and 5 deletions

View 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