README.md

Bridgetown Webfinger plugin

A Bridgetown plugin for handling Webfinger requests for the Fediverse and IndieWeb.

Whether you run a single-author, statically rendered site or a multi-author site with a dynamic backend, this is your one-stop shop for Webfinger support.

This plugin allows for hosting Webfinger lookups on your website for acct: URIs. This is the first step to giving your site the ability to post to Fediverse apps like Mastodon, Pleroma, or PeerTube. While not all Fediverse apps use Webfinger, enough do that adding Webfinger support will be necessary to have your site participate in the Fediverse.

Installation

Run this command to add this plugin to your site's Gemfile:

bundle add bridgetown-webfinger

Or you can use an automation script instead for guided setup:

bin/bt apply https://github.com/michaelherold/bridgetown-webfinger

Usage

This plugin runs in one of two modes: static mode or dynamic mode.

Static mode is for when you run a single-author, fully static website without using any of Bridgetown's Server-Side Rendering (SSR) capabilities. It is mildly non-compliant with the Webfinger specification, but is an accepted practice for static sites.

Dynamic mode uses a Roda plugin to serve author data for all accounts defined in your src/_data/authors.yml file.

Authors data file

Within your authors data file, each author requires a webfinger associative array with data about the account. For example, for the account bilbo, who has a Twitter account at https://twitter.com/bilbobaggins and hosts an avatar at https://bagend.com/bilbo.png, the authors data file entry might look like:

# src/_data/authors.yml
---
bilbo:
  webfinger:
    aliases:
      - https://twitter.com/bilbobaggins
    links:
      - href: https://bagend.com/bilbo.png
        rel: http://webfinger.net/rel/avatar
        type: image/png

You may configure any number of authors in this way, however static mode works with only a single author.

Static mode

To use static mode, configure your authors data file and add the following to your config/initializers.rb file:

# config/initializers.rb
Bridgetown.configure do
  init "bridgetown-webfinger", static: true
end

Bridgetown will now generate a .well-known/webfinger file using your first author's information when building the site.

Deploying to Netlify

To have the correct headers for your static file, add the following to your netlify.toml.

[[headers]]
for = "/.well-known/webfinger"

[headers.values]
Access-Control-Allow-Origin = "*"
Content-Type = "application/jrd+json"

See the allowed hosts section below for more information about the access control header.

Dynamic mode

To use dynamic mode, configure your authors data file and add the following to your config/initializers.rb file:

# config/initializers.rb
Bridgetown.configure do
  init "bridgetown-webfinger", static: false, allowed_hosts: "*"
end

Then, add the bridgetown_webfinger plugin to your RodaApp and call the bridgetown_webfinger request method:

# server/roda_app.rb
class RodaApp < Bridgetown::Rack::Roda
  plugin :bridgetown_ssr  # required
  plugin :bridgetown_webfinger
  
  route do |r|
    r.bridgetown_webfinger
  end
end

This generates a .well-known/webfinger route that serves acct: URI requests for authors on your site.

Allowed hosts

The Webfinger specification states that servers must include the Access-Control-Allow-Origin header to enable Cross-Origin Resource Sharing (CORS) requests and that they should use the least restrictive setting.

Unless you are hosting private Webfinger information — e.g. within a corporate network, to only authenticated followers, or for any other reason — you should set this to "*" using the configuration above.

If this is private information that you wish to restrict set the header value appropriately.

Contributing

So you're interested in contributing to Bridgetown Webfinger? Check out our contributing guidelines for more information on how to do that.