A client library to query WebFinger records
npm install webfinger.jsA modern, TypeScript-based WebFinger client that runs in both browsers and Node.js environments.




⨠Modern ES6+ support - Built with TypeScript, works with modern JavaScript
š Security-first - SSRF protection, blocks private/internal addresses by default
š”ļø Production-ready - Prevents localhost/LAN access per ActivityPub security guidelines
š Flexible fallbacks - Supports host-meta fallback mechanisms
š Universal - Works in browsers and Node.js
š¦ Zero dependencies - Lightweight and self-contained
ā” Fast - Efficient WebFinger discovery and caching
Try the Interactive Demo to see WebFinger lookups in action.
``bashUsing bun (recommended)
bun add webfinger.js
Quick Start
`typescript
import WebFinger from 'webfinger.js';const webfinger = new WebFinger({
tls_only: true // Security-first: HTTPS only
});
const result = await webfinger.lookup('user@example.org');
console.log('Name:', result.idx.properties.name);
console.log('Avatar:', result.idx.links.avatar?.[0]?.href);
`See Usage Examples for comprehensive examples including CommonJS, browser usage, TypeScript patterns, React hooks, and error handling.
Documentation
š Complete API Reference - Auto-generated from TypeScript source
š Usage Examples - Comprehensive examples and patterns
š ļø Development Guide - Contributing and development setup
š® Live Demo - Interactive WebFinger lookup
Testing
`bash
bun run test # Run complete test suite
bun run lint # Code linting
``See the Development Guide for detailed testing information and individual test commands.
webfinger.js includes comprehensive SSRF protection, blocking private networks and validating redirects by default. For detailed security information, see Security Documentation.
Contributions are welcome! Please see the Development Guide for setup instructions, coding guidelines, and contribution workflow.
This project is licensed under the AGPL License - see the license file for details.