Skip to main content

Webfinger

This service implements the Webfinger protocol, which allows remote services to discover local users.

Features

  • Automatically find ActivityPub actors through their username
  • Returns a 404 error if the actor doesn't exist

Dependencies

Install

$ yarn add @semapps/webfinger

Usage

const { WebfingerService } = require('@semapps/webfinger');

module.exports = {
mixins: [WebfingerService],
settings: {
baseUrl: 'https://mydomain.com',
domainName: 'mydomain.com' // Not necessary if it is the same as usersContainer
}
};

Discovering an user with Webfinger

In the Webfinger protocol, users are identified by their username and the domain name where they are hosted: username@domain. This is similar to email addresses, except services like Mastodon add a @ at the beginning.

To find an user, a simple GET is enough:

GET /.well-known/webfinger?resource=acct:simon@localhost HTTP/1.1
Host: localhost:3000
Accept: application/json

If the user exists locally, it will return a JSON like this:

{
"subject": "acct:simon@localhost",
"aliases": ["http://localhost:3000/actors/simon"],
"links": [
{
"rel": "self",
"type": "application/activity+json",
"href": "http://localhost:3000/actors/simon"
}
]
}

Settings

PropertyTypeDefaultDescription
baseUrlStringBase URL of the server. Used to find the domain name if it is not set.
domainNameStringDomain name used for the user@domain webfinger identifier. If not set, the domain name will be guessed from the users' container.

Actions

get

Return the Webfinger information for a local actor.

Parameters
PropertyTypeDefaultDescription
resourceStringrequiredResource in the format acct:user@server.com
Return value

Object formatted like above.

getRemoteUri

Return the URI of a remote actor through the Webfinger protocol.

Parameters
PropertyTypeDefaultDescription
accountStringrequiredAccount in the format user@server.com or @user@server.com
Return value

String URI of the remote actor. Null if no actor found.

Additional resources about the protocol