Skip to content

API.md

Latest commit

 

History

History
542 lines (312 loc) · 12.2 KB

API.md

File metadata and controls

542 lines (312 loc) · 12.2 KB
Raw

webfinger.js v3.0.6

webfinger.js v3.0.6

Classes

default

Defined in: src/webfinger.ts:233

WebFinger client for discovering user information across domains.

Constructor

new WebFinger(cfg?)

Creates a new WebFinger client instance.

Parameters

  • cfg Partial<WebFingerConfig> (optional) - Configuration options for the WebFinger client
    • tls_only boolean (default: true) - Use HTTPS only. When false, allows HTTP fallback for localhost
    • uri_fallback boolean (default: false) - Enable host-meta and host-meta.json fallback endpoints
    • request_timeout number (default: 10000) - Request timeout in milliseconds
    • allow_private_addresses boolean (default: false) - Allow private/internal addresses (DANGEROUS - only for development)

Example

const webfinger = new WebFinger({
  tls_only: true
});

const result = await webfinger.lookup('user@domain.com');
console.log(result.idx.properties.name);

Methods

lookup()

lookup(address): Promise<WebFingerResult>

Defined in: src/webfinger.ts:739

Performs a WebFinger lookup for the given address with comprehensive SSRF protection.

This method includes comprehensive security measures:

  • Blocks private/internal IP addresses by default
  • Validates host format to prevent path injection
  • Validates DNS resolution to block domains that resolve to private IPs
  • Validates redirect destinations to prevent redirect-based SSRF attacks
  • Follows ActivityPub security guidelines
  • Limits redirect chains to prevent redirect loops
Parameters
address

string

Email-like address (user@domain.com) or full URI to look up

Returns

Promise<WebFingerResult>

Promise resolving to WebFinger result with indexed links and properties

Throws

When lookup fails, address is invalid, or SSRF protection blocks the request

Examples
try {
  const result = await webfinger.lookup('nick@silverbucket.net');
  console.log('Name:', result.idx.properties.name);
  console.log('Avatar:', result.idx.links.avatar?.[0]?.href);
} catch (error) {
  console.error('Lookup failed:', error.message);
}
// These will throw WebFingerError due to SSRF protection:
await webfinger.lookup('user@localhost');     // Direct access blocked
await webfinger.lookup('user@127.0.0.1');    // Direct access blocked
await webfinger.lookup('user@192.168.1.1');  // Direct access blocked
// Domains that resolve to private IPs are blocked via DNS resolution (Node.js/Bun)
// Redirects to private addresses are also blocked automatically
lookupLink()

lookupLink(address, rel): Promise<LinkObject>

Defined in: src/webfinger.ts:811

Looks up a specific link relation for the given address.

Parameters
address

string

Email-like address (user@domain.com) or full URI

rel

string

Link relation type (e.g., 'avatar', 'blog', 'remotestorage')

Returns

Promise<LinkObject>

Promise resolving to the first matching link object

Throws

When lookup fails

Throws

When no links found for the specified relation

Example
try {
  const storage = await webfinger.lookupLink('user@example.com', 'remotestorage');
  console.log('Storage endpoint:', storage.href);
} catch (error) {
  console.log('No RemoteStorage found');
}

WebFingerError

Defined in: src/webfinger.ts:189

Custom error class for WebFinger-specific errors.

This error is thrown for various WebFinger-related failures including:

  • Network errors (timeouts, DNS failures)
  • HTTP errors (404, 500, etc.)
  • Security violations (SSRF protection, invalid hosts)
  • Invalid response formats (malformed JSON, missing data)
  • Input validation failures (invalid addresses, formats)

Example

try {
  await webfinger.lookup('user@localhost');
} catch (error) {
  if (error instanceof WebFingerError) {
    console.log('WebFinger error:', error.message);
    console.log('HTTP status:', error.status); // May be undefined
  }
}

Extends

  • Error

Constructors

Constructor

new WebFingerError(message, status?): WebFingerError

Defined in: src/webfinger.ts:199

Creates a new WebFingerError instance.

Parameters
message

string

Error message describing what went wrong

status?

number

Optional HTTP status code if applicable

Returns

WebFingerError

Overrides

Error.constructor

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void

Defined in: node_modules/@types/node/globals.d.ts:51

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
Parameters
targetObject

object

constructorOpt?

Function

Returns

void

Inherited from

Error.captureStackTrace

prepareStackTrace()

static prepareStackTrace(err, stackTraces): any

Defined in: node_modules/@types/node/globals.d.ts:55

Parameters
err

Error

stackTraces

CallSite[]

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

Error.prepareStackTrace

Properties

cause?

optional cause?: unknown

Defined in: node_modules/typescript/lib/lib.es2022.error.d.ts:24

Inherited from

Error.cause

message

message: string

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1075

Inherited from

Error.message

name

name: string

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1074

Inherited from

Error.name

stack?

optional stack?: string

Defined in: node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from

Error.stack

status?

optional status?: number

Defined in: src/webfinger.ts:191

HTTP status code if the error originated from an HTTP response

stackTraceLimit

static stackTraceLimit: number

Defined in: node_modules/@types/node/globals.d.ts:67

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Inherited from

Error.stackTraceLimit

Type Aliases

JRD

JRD = object

Defined in: src/webfinger.ts:131

JSON Resource Descriptor - Raw WebFinger response format

Properties

error?

optional error?: string

Defined in: src/webfinger.ts:135

links

links: Record<string, unknown>[]

Defined in: src/webfinger.ts:133

properties?

optional properties?: Record<string, unknown>

Defined in: src/webfinger.ts:134

subject?

optional subject?: string

Defined in: src/webfinger.ts:132

LinkObject

LinkObject = object

Defined in: src/webfinger.ts:154

Individual link object in WebFinger response

Indexable

[key: string]: string | Record<string, string | null> | undefined

Additional properties

Properties

href

href: string

Defined in: src/webfinger.ts:156

Target URL

properties?

optional properties?: Record<string, string | null>

Defined in: src/webfinger.ts:162

RFC 7033 link properties

rel

rel: string

Defined in: src/webfinger.ts:158

Link relation type

type?

optional type?: string

Defined in: src/webfinger.ts:160

MIME type (optional)

WebFingerConfig

WebFingerConfig = object

Defined in: src/webfinger.ts:113

Configuration options for WebFinger client

Properties

allow_private_addresses

allow_private_addresses: boolean

Defined in: src/webfinger.ts:125

Allow private/internal addresses (DANGEROUS - only for development).

request_timeout

request_timeout: number

Defined in: src/webfinger.ts:123

Request timeout in milliseconds. Applied per HTTP attempt: each redirect hop and fallback URI gets a fresh budget, so the worst-case wall time is roughly (timeout) × (redirects + 1) × (URIs) × (protocols).

tls_only

tls_only: boolean

Defined in: src/webfinger.ts:115

Use HTTPS only. When false, allows HTTP fallback for localhost.

uri_fallback

uri_fallback: boolean

Defined in: src/webfinger.ts:117

Enable host-meta and host-meta.json fallback endpoints.

WebFingerResult

WebFingerResult = object

Defined in: src/webfinger.ts:141

Complete WebFinger lookup result with processed data

Properties

idx

idx: object

Defined in: src/webfinger.ts:143

links

links: object

Index Signature

[key: string]: LinkObject[]

properties

properties: Record<string, unknown>

object

object: JRD

Defined in: src/webfinger.ts:142