Finger

Webfinger server written in Go.

Features

🍰 Easy YAML configuration
🪶 Single 8MB binary / 0% idle CPU / 4MB idle RAM
⚡️ Sub millisecond responses at 10,000 request per second
🐳 10MB Docker image

Install

Via go install:

go install git.maronato.dev/maronato/finger@latest

Via Docker:

docker run --name finger /
    -p 8080:8080 /
    git.maronato.dev/maronato/finger

Usage

If you installed it using go install, run

finger serve

To start the server on port 8080. Your resources will be queryable via locahost:8080/.well-known/webfinger?resource=<your-resource>

If you're using Docker, the use the same command in the install section.

By default, no resources will be exposed. You can create resources via a fingers.yml file. It should contain a collection of resources as keys and their attributes as their objects.

Some default URN aliases are provided via the built-in mapping (urns.yml). You can replace that with your own or use URNs directly in the fingers.yml file.

Here's an example:

# fingers.yml

# Resources go in the root of the file. Email address will have the acct: 
# prefix added automatically.
alice@example.com:
  # "avatar" is an alias of "http://webfinger.net/rel/avatar"
  # (see urns.yml for more)
  avatar: "https://example.com/alice-pic"

  # If the value is a URI, it'll be exposed as a webfinger link
  openid: "https://sso.example.com/"

  # If the value of the attribute is not a URI, it will be exposed as a
  # webfinger property
  name: "Alice Doe"

  # You can also specify URN's directly instead of the aliases
  http://webfinger.net/rel/profile-page: "https://example.com/user/alice"

bob@example.com:
  name: Bob Foo
  openid: "https://sso.example.com/"

# Resources can also be URIs
https://example.com/user/charlie:
  name: Charlie Baz
  profile: https://example.com/user/charlie

Example queries

Query Alice

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

{
  "subject": "acct:alice@example.com",
  "links": [
    {
      "rel": "avatar",
      "href": "https://example.com/alice-pic"
    },
    {
      "rel": "openid",
      "href": "https://sso.example.com/"
    },
    {
      "rel": "http://webfinger.net/rel/profile-page",
      "href": "https://example.com/user/alice"
    }
  ],
  "properties": {
    "name": "Alice Doe"
  }
}

Query Bob

GET http://localhost:8080/.well-known/webfinger?resource=acct:bob@example.com

{
  "subject": "acct:bob@example.com",
  "links": [
    {
      "rel": "http://openid.net/specs/connect/1.0/issuer",
      "href": "https://sso.example.com/"
    }
  ],
  "properties": {
    "http://schema.org/name": "Bob Foo"
  }
}

Query Charlie

GET http://localhost:8080/.well-known/webfinger?resource=https://example.com/user/charlie

{
  "subject": "https://example.com/user/charlie",
  "links": [
    {
      "rel": "http://webfinger.net/rel/profile-page",
      "href": "https://example.com/user/charlie"
    }
  ],
  "properties": {
    "http://schema.org/name": "Charlie Baz"
  }
}

Commands

Finger exposes two commands: serve and healthcheck. serve is the default command and starts the server. healthcheck is used by the Docker healthcheck to check if the server is up.

Configs

Here are the config options available. You can change them via command line flags or environment variables:

CLI flag	Env variable	Default	Description
`-p, --port`	`WF_PORT`	`8080`	Port where the server listens to
`-h, --host`	`WF_HOST`	`localhost` (`0.0.0.0` when in Docker)	Host where the server listens to
`-f, --finger-file`	`WF_FINGER_FILE`	`fingers.yml`	Path to the webfingers definition file
`-u, --urn-file`	`WF_URN_FILE`	`urns.yml`	Path to the URNs alias file
`-d, --debug`	`WF_DEBUG`	`false`	Enable debug logging

Development

You need to have Go installed to build the project.

Clone the repo and run make build to build the binary. You can then run ./finger serve to start the server.

A few other commands are:

make run to run the server
make test to run the tests
make lint to run the linter
make clean to clean the build files

License

This project is licensed under the MIT License - see the LICENSE file for details.

4.9 KiB Raw Blame History Unescape Escape