WebFinger Extension (DRAFT)

Purpose

Users and clients can lookup the URL for a twtxt/yarn feed by using WebFinger. In this way the syntax @nick@domain can be resolved to a valid URL. This passes the business card test (REF NEEDED?)

Format

The syntax of webfinger looks like a email consitign of a username or nick and a domain seperarted by an @-sign: nick@example.net

To preforme a lookup a request it send to to: example.net/.well-know/webfinger?resource=acct%3Anick%40example.net

Based on how webfinger have been implemented in yarn already, a minimum viable respond whoud be the following JSON:

{
  "subject": "acct:nick@example.net",
  "aliases": [
    "https://example.net/twtxt.txt",
  ],
  "links": [
    {
      "rel": "self",
      "type": "text/plain",
      "href": "https://example.net/twtxt.txt"
    }
  ]
}

Since this does not really tell that the URL in href are to be processed as a twtxt/yarn file we suggest the following changes:

The type filed are change to

either application/twtxt+txt (in line with application/rss+xml and application/activity+json since twtxt is similar to these)
or text/twtxt (similar to text/plain, text/markdown or text/html)
text/plain shoud probablly be supported as well for backward compability)

The rel field chould also be change to a URI point to this page in line with the avatar and profile page descibed below.

Yarnd also extend the JSON with infomantion about profile page and avatar, which are both specified at: https://webfinger.net/rel

{
  "subject": "acct:nick@example.net",
  "aliases": [
    "https://example.net/user/nick/twtxt.txt",
    "https://example.net/user/nick/avatar.png",
    "https://example.net/user/nick/"
  ],
  "links": [
    {
      "rel": "self",
      "type": "text/plain",
      "href": "https://example.net/user/nick/twtxt.txt"
    },
    {
      "rel": "https://webfinger.net/rel/profile-page",
      "type": "text/html",
      "href": "https://example.net/user/nick/"
    },
    {
      "rel": "https://webfinger.net/rel/avatar",
      "type": "image/png",
      "href": "https://example.net/user/nick/avatar.png"
    }
  ]
}

Implemantation

Webfinger can be impemented with just a static JSON file for single user instances like descibed in Added WebFinger support to my email address using one rewrite rule and one static file, Setting Up a WebFinger Server or Mastodon instance with 6 files - Justin Garrison.

You can also add webfinger support to you site by simply putting a static JSON in place for .well-know/webfinger. This will make it so that any request to https://yoursite.com/.well-know/webfinger?resource=acct%3Anick%40yoursite.com will return the JSON no matter what the nick in the request are, so all request will be valid. (NOTE: This might break some webfinger resolvers!)

Yarn

(TODO)

Timeline

The Timeline - single user twtxt/yarn pod have support for both webfinger endpoint and lookup when adding a new feed to you following list.

Security Considerations

(TODO / any?)