webfinger-handler v1.1.0

Webfinger Handler

A library that generates a handler for webfinger requests. The created handler works with Node JS HTTP request and response objects, and is otherwise framework agnostic.

import WebfingerHandler from 'webfinger-handler';

// Handle requests for `[username]@my-website.example`
// This example is synchronous, but you can make it async if you need to e.g. access a database
const webfinger = WebfingerHandler(resource => {
    if(resource.host !== 'my-website.example') {
        // Return null if there are no links for this resource
        return null;
    }

    // Either return the whole json-rd response object or just the links array
    return [
        {
            rel: 'http://webfinger.net/rel/profile-page',
            href: `https://my-website.example/profile/${resource.user}`
        },
    ]
});

// This is the standard httpServer.listen callback
export default async function onRequest(req, res) {
    if(await webfinger(req, res)) {
        // The handler will return true if it has handled the request,
        // and false if not (i.e. the req.url path is not '/.well-known/webfinger')
        return;
    }

    // Not a webfinger request - run whatever site code you need to
    res.end('Welcome to my website!');
}

ActivityPub

If you're only using webfinger for ActivityPub, you can use the ActivitypubWebfinger method:

import { ActivitypubWebfinger } from 'webfinger-handler';

const webfinger = ActivitypubWebfinger(resource => {
    if(resource.host !== 'my-website.example') {
        // Return null if there are no actors for this resource
        return null;
    }

    // You just have to return the Actor URL, the rest of the response is constructed automatically
    return `https://my-website.example/@${resource.user}`
});

// Then use `webfinger` the same way as the above examples

Express usage

For use with Express or Connect, you'll need to wrap your function like so:

// Assuming app is your Express instance
app.use(async function webfingerExpress(req, res, next) {
	try {
		if(!await webfinger(req, res)) {
			next();
		}
	} catch(e) {
		next(e);
	}
});

Advanced use

If you have more specialist use cases you can export the constituent functions for request parsing, response sending, etc - take a look at the API.

Dependencies

None

webfinger-handler

Webfinger

See: module:webfinger-handler.default

• webfinger-handler
  • module.exports(getDescriptor) ⇒ webfingerHandler ⏏
    • static
      • .WebfingerError
      • .WebfingerMethodError
      • .WebfingerResourceError
      • .AcctUri
        • new exports.AcctUri(options, user, host)
        • instance
          • .scheme
          • .userpart
          • .account
          • .uri
        • static
          • .parse(resource) ⇒ AcctUri
      • .parse(req) ⇒ false | AcctUri
      • .sendError(res, error)
      • .send(res, body)
      • .getActivitypubDescriptor(getActivitypubLink) ⇒ getDescriptor
      • .ActivitypubWebfinger(getHref) ⇒ webfingerHandler
    • inner
      • ~getDescriptor ⇒ object | Array | null
      • ~webfingerHandler ⇒ Boolean
      • ~getActorLink ⇒ string | object
      • ~IncomingMessage
      • ~OutgoingMessage

module.exports(getDescriptor) ⇒ webfingerHandler ⏏

Create a handler for incoming webfinger requests

Kind: Exported function
Returns: webfingerHandler - Method for handling webifinger requests

module.exports.WebfingerError

An error encountered while processing a webfinger request

Kind: static class of module.exports

module.exports.WebfingerMethodError

An error thrown when the incomming Webfinger request uses the wrong HTTP method

Kind: static class of module.exports

module.exports.WebfingerResourceError

An error thrown when the webfinger resource paramter is incorrectly formatted

Kind: static class of module.exports

module.exports.AcctUri

An object representing an acct: URI

Kind: static class of module.exports

• .AcctUri
  • new exports.AcctUri(options, user, host)
  • instance
    • .scheme
    • .userpart
    • .account
    • .uri
  • static
    • .parse(resource) ⇒ AcctUri

new exports.AcctUri(options, user, host)

Construct an instance of AcctUri

acctUri.scheme

The scheme of the URI. This is always acct:.

Kind: instance property of AcctUri

acctUri.userpart

Alias for user

Kind: instance property of AcctUri

acctUri.account

The account string Made of the user and host concatenated with the @ symbol

Kind: instance property of AcctUri

acctUri.uri

The full URI including the scheme

Kind: instance property of AcctUri

AcctUri.parse(resource) ⇒ AcctUri

Parse a string into an AcctUri object

Kind: static method of AcctUri

module.exports.parse(req) ⇒ false | AcctUri

Parses an incoming http request for the requested acct: URI

Kind: static method of module.exports
Returns: false - If the request is not for the webfinger endpointAcctUri - An object representing the requested account
Throws:

• WebfingerMethodError If the GET method is not used in the request

module.exports.sendError(res, error)

Informs the user about an error that occured with the webfinger request

Kind: static method of module.exports

module.exports.send(res, body)

Sends a JSON RD response body to the client

Kind: static method of module.exports

module.exports.getActivitypubDescriptor(getActivitypubLink) ⇒ getDescriptor

Generates a getDescriptor method specifically for activitypub resource

Kind: static method of module.exports
Returns: getDescriptor - Method that can be used as the Webfinger descriptor getter

module.exports.ActivitypubWebfinger(getHref) ⇒ webfingerHandler

Creates a webfinger handler specifically for Activitypub use

Kind: static method of module.exports
Returns: webfingerHandler - Webfinger resource request handler

module.exports~getDescriptor ⇒ object | Array | null

Return a JRD descriptor object for agiven acct: URI

Kind: inner typedef of module.exports
Returns: object | Array | null - Either: a JRD descriptor object, a JRD links array, or null if no resource was found

module.exports~webfingerHandler ⇒ Boolean

Webfinger handler

Kind: inner typedef of module.exports
Returns: Boolean - True if the request was handled, false if the request path did not match the webfinger endpoint

module.exports~getActorLink ⇒ string | object

Get a link for an activitypub actor

Kind: inner typedef of module.exports
Returns: string | object - Either the href of the actor, or the JRD link representation of the actor

module.exports~IncomingMessage

Incoming http request

Kind: inner external of module.exports
See: https://nodejs.org/api/http.html#http_class_http_incomingmessage

module.exports~OutgoingMessage

Outgoing http response

Kind: inner external of module.exports
See: https://nodejs.org/api/http.html#http_class_http_incomingmessage