An immutable Mastodon handle

Whether Twitter crumbles remains to be seen, though some signs are telling. Whatever happens, I'm continuing to invest a bit in Mastodon. Last week, I showed how to sync one's content between Twitter and Mastodon. This week, I've set up a Mastodon handle on my domain that redirects to my profile page: I want to explain how I achieved it and the problems I'm still having.

Mastodon 101

Mastodon is different from Twitter in that it's not centralized: it's a federation of Mastodon servers, run independently and connected - the Fediverse. To be precise, the Fediverse is more than Mastodon nodes, but let's not go that far. The first problem when one wants to create a Mastodon account is to choose the correct instance. My first choice was mastodon.social, but it was closed to new accounts at the time. I set my eyes on mastodon.top for no reason but that it was in the proposal list and was French.

The choice of a server is not that important since you can always move your account to another instance and keep your followers. Note that you'll leave (and lose) your content on the original server. In all cases, your profile is namespaced by the server; thus, your handle changes.

Currently, I'm @[e-mail]. But perhaps I'll join my friends at foojay.social or set up my own frankel.social in the future? In both cases, I'll need to change the suffix of my handle. Yet, I publish my handle on many sites and don't want to forget any updates when migrating. Hence, I require that the handle must be immutable.

I mentioned above that Mastodon nodes belong to a network named Fediverse. Fediverse nodes may be connected through several different protocols. Mastodon nodes uses ActivityPub. Underneath, ActivityPub relies on WebFinger to find the correct location of a handle.

WebFinger

Mastodon needs to translate @[e-mail] to https://mastodon.top/web/@frankel. The translation must happen on any Mastodon instance, regardless of its domain. The process is based on the WebFinger specification, aka RFC 7033:

WebFinger as described in RFC 7033 is a spec that defines a method for resolving links to a resource, given only a URI on a particular server. This allows anyone to look up where a resource is located without having to know its exact location beforehand; for example, by email or phone number. This lookup is directed at the endpoint /.well-known/webfinger, and a resource query parameter is passed along with the lookup. The resource URI used with Mastodon is the acct: URI as described in RFC 7565, with the username of a profile that is hosted on a particular domain.

-- What is WebFinger, and why is it used?

According to the above, when searching for my profile, the query is the following: https://mastodon.top/.well-known/webfinger?resource=acct:[e-mail]. You can check by going to a Mastodon instance you're logged in, searching for my handle, and watching the traffic via your preferred browser's developer tools.

The response is the following:

{
  "subject":"acct:[e-mail]",
  "aliases":[
    "https://mastodon.top/@frankel",                                        #1
    "https://mastodon.top/users/frankel"                                    #1
  ],
  "links":[
    {
      "rel":"http://webfinger.net/rel/profile-page",                        #2
      "type":"text/html",
      "href":"https://mastodon.top/@frankel"
    },
    {
      "rel":"self",
      "type":"application/activity+json",
      "href":"https://mastodon.top/users/frankel"
    },
    {
      "rel":"http://ostatus.org/schema/1.0/subscribe",
      "template":"https://mastodon.top/authorize_interaction?uri={uri}"
    }
  ]
}

1. URL to the profile
2. rel for Mastodon

The immutable Mastodon handle

It should work if I return the same response to the same query on a custom domain. That's what I did: https://blog.frankel.ch/.well-known/webfinger?resource=acct:[e-mail]. Because it's a static page and I'm the only account, we don't need the query parameter: https://blog.frankel.ch/.well-known/webfinger.

Given this, I can search on https://mastodon.top with @[e-mail] (or any handle @frankel.ch), and it returns the expected results:

I checked on other instances, e.g., https://mastodon.social/, but it doesn't work. The reason is simple. When searching on the instance you're logged in, the XHR is https://mastodon.top/api/v2/search?q=@[e-mail]&resolve=true&limit=5; when not, it's https://mastodon.top/api/v2/search?q=@[e-mail]&resolve=false&limit=5. Conclusion: you can only query handles on the same instance when you're not authenticated.

The documentation confirms that if resolve is false, then the query doesn't try to use WebFinger:

resolve

Boolean. Attempt WebFinger lookup? Defaults to false.

-- Perform a search

Conclusion

The theory behind Mastodon and WebFinger is fascinating. I've managed to configure my immutable mastodon handle @[e-mail]. That's the handle I can communicate to potential followers: if I move to another server, I'll update the webfinger with my new coordinates.

The trick works because I'm the only Mastodon user on my domain. If you have several, you'll need to go beyond a static page to return a different ID depending on the acct: parameter; the rest stays the same.

To go further:

• Steps toward the glory of REST
• JSON Hypertext Application Language
• RFC 8288 - Web Linking
• Choosing an HTTP Status Code — Stop Making It Hard

Originally published at A Java Geek on December 18^th, 2022