webfinger.js prioritizes security and includes comprehensive protection against common attack vectors that can affect WebFinger implementations.

This library includes robust protection against Server-Side Request Forgery (SSRF) attacks by default:

• Private address blocking: Prevents requests to localhost, private IP ranges, and internal networks
• DNS resolution protection: Resolves domain names in Node.js environments to block domains that resolve to private IPs
• Path injection prevention: Validates host formats to prevent directory traversal attacks
• Redirect validation: Prevents redirect-based SSRF attacks to private networks
• ActivityPub compliance: Follows ActivityPub security guidelines (Section B.3)

The following address ranges are blocked by default to prevent SSRF attacks:

• localhost, localhost.localdomain
• 127.x.x.x (IPv4 loopback)
• ::1 (IPv6 loopback)

• 10.x.x.x (Class A private)
• 172.16.x.x - 172.31.x.x (Class B private)
• 192.168.x.x (Class C private)

• 169.254.x.x (IPv4 link-local)
• fe80::/10 (IPv6 link-local)

• 224.x.x.x - 239.x.x.x (IPv4 multicast)
• ff00::/8 (IPv6 multicast)

In Node.js environments, the library performs DNS resolution to prevent attacks using domains that resolve to private IP addresses:

• Domain resolution: All domain names are resolved to IP addresses before making requests
• Private IP detection: Resolved IPs are checked against the private address blacklist
• Attack prevention: Blocks requests to public domains like localtest.me that resolve to 127.0.0.1
• Browser compatibility: DNS resolution is skipped in browser environments where it's not available

Example blocked domains:

• localtest.me → 127.0.0.1 (blocked)
• 10.0.0.1.nip.io → 10.0.0.1 (blocked)
• Custom domains configured to resolve to private networks

Note: This protection only applies in Node.js and Bun environments. Browser environments rely on the browser's built-in protections against private network access.

Runtime requirements: DNS resolution protection uses process.getBuiltinModule, available in Node.js >= 20.16 / 22.3 and Bun (see the engines field in package.json). On older Node.js versions this check is skipped and the library falls back to the address blocklist validation above — direct private IPs and hostnames are still blocked, but domains that resolve to private IPs are not.

The library implements manual redirect handling to validate redirect destinations through the same canonical validation pipeline used for the initial address:

• Redirect limits: Maximum of 3 redirects to prevent redirect loops
• Destination validation: All redirect targets are checked against the private address blacklist
• DNS resolution: In Node.js/Bun, redirect hostnames are resolved and their IPs checked against the private blacklist — closing DNS-rebind style redirect attacks
• Malformed response handling: Invalid or missing Location headers are rejected
• URL validation: Redirect URLs are parsed and validated before following

This prevents attacks where a public domain's WebFinger endpoint redirects to private network resources — either via IP literal or via a hostname whose DNS records point inside the network.

⚠️ CAUTION: The following configuration should ONLY be used in development or testing environments!

const webfinger = new WebFinger({
  allow_private_addresses: true  // Disables SSRF protection - DANGEROUS in production!
});

// This will now work (but should never be used in production)
await webfinger.lookup('user@localhost:3000');

• Local development: Testing against localhost services
• Internal testing: Validating against private network services
• Unit testing: Creating controlled test environments

Never set allow_private_addresses: true in production environments. This completely disables SSRF protection and opens your application to serious security vulnerabilities.

When integrating webfinger.js into your application:

1. Keep defaults: Use the default secure configuration in production
2. Validate inputs: Always validate user-provided addresses before lookup
3. Handle errors gracefully: Don't expose internal network details in error messages
4. Monitor requests: Log WebFinger lookups for security monitoring
5. Update regularly: Keep the library updated to receive security patches

If you discover a security vulnerability in webfinger.js, please report it responsibly:

1. Do not create a public GitHub issue
2. Email security concerns to the maintainer
3. Include detailed reproduction steps
4. Allow reasonable time for fixes before public disclosure

This library's security implementation follows:

• ActivityPub Security Considerations (Section B.3)
• RFC 7033 WebFinger security guidelines
• Common SSRF prevention best practices

The security model is designed to be safe by default while providing necessary flexibility for legitimate use cases.