LittleWebFinger

LittleWebFinger is a compact WebFinger gateway written in Rust with Axum. It stores each account in a small SQLite database and exposes a single endpoint at /.well-known/webfinger.

A GET request returns a JRD for the requested subject. A POST request creates or updates an entry. A DELETE request removes an entry. POST and DELETE require a static bearer token that you set in the configuration file or environment. If no secret is set, those endpoints are disabled and you use a CLI to add/update/remove resources from your database.

It can also handles static files for /.well-known paths, this features have been added in v0.3.0. It allows to easily set the mime-type so you can have 2 different files on the same URL served depending on the accept header of the request.

The project is intended for private projects, small laboratories, or personal domains. It is not tuned for very large installations but it can serve a handful of accounts without issue.

Building and running locally

Clone the repository. Install Rust and a recent SQLite development package. Run LWF_SECRET=mypasswd cargo run -- serve to start the server. By default it listens on port 8080 and reads lwf.toml from the working directory.

Create or update an entry with:

$ cat contact-example-com.json
{"subject":"acct:contact@example.com","links":[{"rel":"http://openid.net/specs/connect/1.0/issuer","href":"https://codeberg.org/"}]
$ cargo run -- remote webfinger-add https://example.com/.well-known/webfinger mypasswd @contact-example-com.json

Delete it with:

$ cargo run -- remote webfinger-delete https://example.com/.well-known/webfinger mypasswd acct:contact@example.com

Fetch it with:

curl "http://localhost:8080/.well-known/webfinger?resource=acct:alice@example.com"

Same goes for static well-known files.

Command line helper

The binary also provides a small helper CLI that can be used if you disable the protected routes. Use littlewebfinger (webfinger|static) (get|add|delete), the command lines provides a contextual help for each subcommands.

When starting as a container, use docker exec littlewebfinger /littlewebfinger get <subject> directly.

Docker image

A prebuilt image is published to the Codeberg image registry. Pull it with docker pull codeberg.org/Elyvi/littlewebfinger:latest and pass a mounted volume for the database and configuration.

Configuration

This projects can be configured by either passing a TOML file to the command line with the -c flag or using environement variables (easier when using docker):

docker run -e LWF_SECRET=helloworld -e LWF_DATABASE=/data/db.sqlite -v $PWD/lwf:/data codeberg.org/Elyvi/littlewebfinger:latest

Running behind a reverse proxy (Caddy)

Here is an exemple Caddyfile to forward the endpoint to littlewebfinger:

example.com {
	root * /srv/example.com
	file_server
	@littlewebfinger path /.well-known/*
	handle @littlewebfinger {
		reverse_proxy 127.0.0.1:8080
	}
}

Status

LittleWebFinger is a toy reference that I use on my private domain for OAuth. You can find more information on the motivation behind this project on my personal blog.