txt-domain-verification

A production-ready Node.js package for verifying domain ownership through DNS TXT records with authoritative nameserver queries, security features, and comprehensive error handling.

🚀 New in v2.0.0

• Authoritative Nameserver Queries: Queries domain nameservers directly instead of relying on OS/ISP resolvers
• Secure Token Generation: HMAC-based tokens with user binding and expiration
• Domain Normalization: Handles punycode, casing, and trailing dots consistently
• Retry Logic: Exponential backoff with configurable retry attempts
• Partial Propagation Detection: Reports when verification records are still propagating
• TypeScript Support: Full type definitions included
• Dual Build: Both CommonJS and ESM modules supported

🔒 Security Features

• Fixed TXT Record Name: Uses _verify.example.com for actual verification
• HMAC Tokens: Cryptographically secure tokens bound to user, domain, and timestamp
• Token Expiration: Configurable expiry (default: 72 hours)
• Single-Use Tokens: Designed for one-time verification
• DNS-Only Verification: No HTTP/HTTPS requests to prevent SSRF attacks

📦 Installation

npm install txt-domain-verification

yarn add txt-domain-verification

pnpm add txt-domain-verification

bun add txt-domain-verification

🛠️ Usage

Basic Verification Flow

const {
  generateVerificationCode,
  verifyDomain,
  CONFIG,
} = require('txt-domain-verification');

// 1. Generate verification code
const verificationCode = generateVerificationCode(
  'example.com', // Domain to verify
  'your-secret-key', // Secret for HMAC
  'user123', // User identifier
  'AcmeCorp', // Business name (optional)
  '{{businessName}} Verification: {{token}}' // Custom format
);

console.log(verificationCode.instructions);
// Output: Please add the following TXT record to your DNS settings for example.com:
// Name: _verify
// Value: AcmeCorp Verification: eyJ0b2tlbiI6ImFiY2RlZiJ9...

// 2. User adds TXT record to DNS
// 3. Verify domain ownership
const result = await verifyDomain('example.com', verificationCode.token);

if (result.verified) {
  console.log('Domain verified successfully!');
} else if (result.partialPropagation) {
  console.log(
    `Partial propagation: ${result.successfulQueries}/${result.totalNameservers} nameservers responding`
  );
}

Advanced Verification with Options

const result = await verifyDomain(
  'example.com',
  verificationCode.token,
  '_verify', // Custom verification prefix
  {
    maxRetries: 5, // Maximum retry attempts
    retryDelay: 2000, // Base delay between retries (ms)
  }
);

console.log('Verification result:', {
  verified: result.verified,
  domain: result.domain,
  totalNameservers: result.totalNameservers,
  successfulQueries: result.successfulQueries,
  partialPropagation: result.partialPropagation,
  timestamp: result.timestamp,
});

Domain Normalization

const { normalizeDomain } = require('txt-domain-verification');

const normalized = normalizeDomain('  EXAMPLE.COM.  ');
console.log(normalized); // 'example.com'

Secure Token Generation

const { generateSecureToken } = require('txt-domain-verification');

const token = generateSecureToken(
  'secret-key',
  'user123',
  'example.com',
  new Date()
);

🔧 Configuration

const { CONFIG } = require('txt-domain-verification');

console.log(CONFIG);
// {
//   VERIFICATION_PREFIX: '_verify',
//   TOKEN_EXPIRY_HOURS: 72,
//   MAX_RETRIES: 3,
//   RETRY_DELAY_MS: 1000,
//   DNS_TIMEOUT_MS: 10000,
//   MIN_NAMESERVERS_VERIFIED: 1
// }

📊 Verification Results

The verifyDomain function returns detailed information about the verification process:

{
  verified: boolean,           // Whether verification succeeded
  domain: string,              // Normalized domain name
  attempt: number,             // Current attempt number
  totalNameservers: number,    // Total nameservers found
  successfulQueries: number,   // Successfully queried nameservers
  failedQueries: number,       // Failed nameserver queries
  matchingRecords: Array,      // Records containing the token
  partialPropagation: boolean, // Whether some nameservers are still propagating
  nameserverResults: Array,    // Detailed results from each nameserver
  timestamp: Date              // When verification was performed
}

🌐 How It Works

1. Nameserver Resolution: Queries the domain's authoritative nameservers
2. Direct DNS Queries: Sends DNS queries directly to each nameserver
3. Token Verification: Checks TXT records for the secure verification token
4. Propagation Detection: Reports partial propagation status
5. Retry Logic: Implements exponential backoff for failed queries

🧪 Testing

npm test
npm run test:coverage

📦 Building

npm run build

This creates both CommonJS (dist/index.js) and ESM (dist/index.mjs) builds.

🔄 Migration from v1.x

Old API (Deprecated)

const {
  generateVerificationCode,
  verifyDomain,
} = require('txt-domain-verification');

// Old: Random hex codes
const result = generateVerificationCode('example.com', 'business');
const isVerified = await verifyDomain('example.com', result.formattedString);

New API (Recommended)

const {
  generateVerificationCode,
  verifyDomain,
} = require('txt-domain-verification');

// New: Secure HMAC tokens
const verificationCode = generateVerificationCode(
  'example.com',
  'your-secret-key',
  'user123',
  'business'
);

const result = await verifyDomain('example.com', verificationCode.token);

🚨 Important Notes

• Secret Management: Store your secret key securely (environment variables, secret management service)
• Token Expiry: Tokens expire after 72 hours by default
• DNS Propagation: Allow 5-60 minutes for DNS changes to propagate
• Nameserver Queries: The library queries authoritative nameservers directly for accuracy
• Rate Limiting: Implement rate limiting in your application for production use

📄 License

CC BY-SA

🤝 Contributing

Contributions are welcome! Please ensure all tests pass and add tests for new features.

📚 Examples

See example-new.js for comprehensive usage examples.