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

CDN

Replace the version 3.0.0 with the version of your choice:

https://cdn.jsdelivr.net/npm/webfinger.js@3.0.0/dist/webfinger.min.js

Quick Start

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

🚀 Usage Examples - Comprehensive examples and patterns
🎮 Live Demo - Interactive WebFinger lookup 📚 Complete API Reference - Auto-generated from TypeScript source 🛠️ Development Guide - Contributing and development setup

Testing

bun run test         # Dev loop: unit + integration + browser
bun run test:release # Release gate: test + import smoke tests (Bun, Node ESM, Node CJS)
bun run lint         # Code linting

Use bun run test for day-to-day work. Run bun run test:release before shipping changes that touch package.json exports, build config, or dist/ output — it rebuilds dist/ and exercises every supported import mode. See the Development Guide for details.

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 MIT License.