# 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