Gondulf/docs/decisions/ADR-011-dns-txt-subdomain-prefix.md

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