webfinger.js

A modern, TypeScript-based WebFinger client that runs in both browsers and Node.js environments.

Features

✨ 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.

Installation

# Using bun (recommended)
bun add webfinger.js

# Using npm
npm install webfinger.js

# Using yarn
yarn add webfinger.js

Quick Start

import WebFinger from 'webfinger.js';

const webfinger = new WebFinger({
  tls_only: true  // Security-first: HTTPS only
});

const result = await webfinger.lookup('[email protected]');
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

bun run test        # Run complete test suite
bun run lint        # Code linting

See the Development Guide for detailed testing information and individual test commands.

Security

webfinger.js includes comprehensive SSRF protection, blocking private networks and validating redirects by default. For detailed security information, see Security Documentation.

Contributing

Contributions are welcome! Please see the Development Guide for setup instructions, coding guidelines, and contribution workflow.

License

This project is licensed under the AGPL License - see the license file for details.