activitypub-webfinger

Internationalized Webfinger Handle Adoption

This document tracks adoption of non-ASCII characters in Webfinger handles in ActivityPub.

Background

Most ActivityPub servers implement Webfinger for providing readable localpart@domain.example account identifiers. The ActivityPub and Webfinger Report outlines how Webfinger is implemented in the ActivityPub network.

For the top human languages, only 3 primarily use only ASCII characters (English, Malaysian, Indonesian), for a total of about 500 million people. That means about 90% of humans use languages with non-Latin, or accented, character sets.

Webfinger supports non-ASCII characters in both the local part (user name) and domain. In this document, we call Webfinger handles with non-ASCII characters internationalized Webfinger handles, inclusive handles, or non-ASCII handles. This document tracks adoption of non-ASCII characters in Webfinger handles in ActivityPub.

Implementation notes

Webfinger is defined in RFC 7033. It uses the acct: URI format, among others, defined in RFC 7565.

An acct: URI has the form userpart@host. Per the internationalization considerations, these parts have the following restrictions.

userpart

userpart must match the PRECIS IdentifierClass. This includes “letters”, “numbers”, and a few ASCII punctuation marks.

Some example userpart values (see also Sample data below):

Not every implementation will support every form of userpart described here.

host

host must match the Internationalized Domain Names for Applications (IDNA) requirements for the Unicode form of a hostname in RFC 5892.

Some example host values (see also Sample data below):

acct: URI

In acct: URIs, the userpart is percent-encoded, and the host is encoded as an A-label per IDNA.

Some examples:

Webfinger handle lookup

Looking up a handle requires converting it to an acct: URI and passing it as the resource parameter to the well-known URL for Webfinger for the host domain.

As an example, start with the handle ελπίδα@ఉదాహరణ.example. Its hostname in IDNA A-label form is xn--noc6ci4b4b3a.example. The acct: URI is:

acct:%CE%B5%CE%BB%CF%80%CE%AF%CE%B4%CE%B1@xn--noc6ci4b4b3a.example

The resulting URI for WebFinger lookup is:

https://xn--noc6ci4b4b3a.example/.well-known/webfinger?resource=acct%3A%25CE%25B5%25CE%25BB%25CF%2580%25CE%25AF%25CE%25B4%25CE%25B1%40xn--noc6ci4b4b3a.example

Note that the % characters in the acct: URI are themselves percent-encoded in the HTTPS URL, as parameter values.

ActivityPub object IDs

ActivityPub objects, including actors, activities, and collections, use HTTPS IRIs as identifiers. These IRIs can include non-ASCII characters, or they can use URI-encoded form; it’s up to the publisher. ActivityPub object ids are opaque and immutable, so consumers should not modify them for comparison or retrieval.

This object has an A-label form of the hostname as part of the id.

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "id": "https://xn--d5b6ci4b4b3a.example/object/35",
  "type": "Object",
  "summary": "An ActivityPub object with A-label form for the hostname in the id"
}

The following collection uses non-ASCII characters in the ID, both for the hostname and in the pathname of the HTTPS IRI.

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "id": "https://எடுத்துக்காட்டு.example/user/иван/followers",
  "type": "OrderedCollection",
  "summary": "Followers of иван@எடுத்துக்காட்டு.example"
}

Most high-level HTTP client interfaces, like fetch(), requests or the URL API, can transparently handle HTTPS IRIs.

preferredUsername

The preferredUsername of an actor should match the unencoded version of the userpart.

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "id": "https://xn--caf-dma.example/user/%E3%81%95%E3%81%8F%E3%82%89",
  "type": "Person",
  "preferredUsername": "さくら"
}

webfinger property

FEP 2c59 defines a webfinger property for an actor. This should be in the unencoded format of both the userpart and the host:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "id": "https://xn--mxd7a1d.example/user/D9%8A%D9%84%D9%89",
  "type": "Person",
  "webfinger": "ليلى@ምሳሌ.example"
}

If the publisher uses the (less preferred) acct: URI format, it should be encoded:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "id": "https://xn--mxd7a1d.example/user/D9%8A%D9%84%D9%89",
  "type": "Person",
  "webfinger": "acct:%D9%84%D9%8A%D9%84%D9%89@xn--mxd7a1d.example"
}

Sample data

It is helpful to test handles which include a variety of realistic characters and scripts. Bugs may exist which are triggered only by certain character features. For instance, code which works with handles containing left-to-right scripts, like Chinese, might not work with right-to-left scripts like Arabic.

The text file UASG004A Test Cases for UA Readiness Evaluation - Data EN contains over 80 email addresses and domain names in about 30 scripts. It is CSV-structured for reliable machine parsing. The accompanying document UASG 004 Test Cases for UA Readiness Evaluation EN explains the intention for the data. These can be adapted as webfinger handles, and as userparts and hosts. They originate from ICANN’s Universal Acceptance project c. 2021. As of 2026, most of these domain names host live HTTP servers with placeholder pages, and the email addresses reach automated responders, operated by ICANN. There are not Fediverse servers hosted at these domains, however.

Server and client matrix

This matrix is for tracking ActivityPub software implementation status of non-ASCII Webfinger handles.

It includes ActivityPub servers, ActivityPub server frameworks, Mastodon API clients, and ActivityPub API clients.

The table has the following columns:

Thanks to FediDB for the seed version of the software list.

Software Receive Send Link Search Domain Username Issue(s)
Activity-Relay ? ? ? ? ? ? ?
activitypub.bot1 ✅ Y ✅ Y ✅ Y ✅ Y ✅ Y ✅ Y #282
Activityrelay ? ? ? ? ? ? ?
Akkoma ? ? ? ? ? ? ?
BadgeFed ? ? ? ? ? ? ?
Betula ? ? ? ? ? ? ?
Bonfire ✅ Y ✅ Y ✅ Y ✅ Y ✅ Y ✅ Y 2
Bookwyrm ? ? ? ? ? ? ?
Bridgy-fed ? ? ? ? ? ? ?
browser.pub ? ? ? ? ? ? ?
Cherrypick ? ? ? ? ? ? ?
Drupal ? ? ? ? ? ? ?
Ecko ? ? ? ? ? ? ?
Emissary ? ? ? ? ? ? ?
Fedibird ? ? ? ? ? ? ?
Firefish ? ? ? ? ? ? ?
Forgejo ? ? ? ? ? ? ?
Forte ✅ Y ✅ Y ✅ Y ✅ Y ✅ Y ✅ Y 3
Foundkey ? ? ? ? ? ? ?
frequency ? ? ? ? ? ? ?
Friendica ? ? ? ? ? ? ?
Funkwhale ? ? ? ? ? ? ?
Gancio ? ? ? ? ? ? ?
Ghost ? ? ? ? ? ? ?
GNU social ? ? ? ? ? ? ?
Gotosocial ? ? ? ? ? ? ?
Hackers’ Pub ? ? ? ? ? ? ?
Hollo ? ? ? ? ? ? ?
Hometown ? ? ? ? ? ? ?
Honk ? ? ? ? ? ? ?
Hubzilla ? ? ? ? ? ? ?
Iceshrimp ? ? ? ? ? ? ?
irwin ? ? ? ? ? ? ?
Kmyblue ? ? ? ? ? ? ?
Ktistec ? ? ? ? ? ? ?
Lemmy ? ? ? ? ? ? ?
Loops ? ? ? ? ? ? ?
Lotide ? ? ? ? ? ? ?
Manyfold ? ? ? ? ? ? #7310 + Fedipub support
Mastodon ? ? ? ? ? ? #8417
Mbin ? ? ? ? ? ? ?
Meisskey ? ? ? ? ? ? ?
Microblogpub ? ? ? ? ? ? ?
Microdotblog ? ? ? ? ? ? ?
Misskey ? ? ? ? ? ? ?
Mitra ? ? ? ? ? ? ?
Mobilizon ? ? ? ? ? ? ?
murlog ? ? ? ? ? ? ?
NeoDB ? ? ? ? ? ? ?
NodeBB ✅ Y ✅ Y ✅ Y ✅ Y ✅ Y ✅ Y  
onepage.pub ? ? ? ? ? ? #287
Owncast ? ? ? ? ? ? ?
PeerTube ? ? ? ? ? ? ?
Piefed ? ? ? ? ? ? ?
Pixelfed ? ? ? ? ? ? ?
Pleroma ? ? ? ? ? ? ?
Plume ? ? ? ? ? ? ?
Postmarks ? ? ? ? ? ? ?
Sharkey ? ? ? ? ? ? ?
Smithereen ? ? ? ? ? ? ?
Snac ? ? ? ? ? ? ?
stegodon ? ? ? ? ? ? ?
streams repository ✅ Y 4 ✅ Y ✅ Y ✅ Y ✅ Y ?
Takahe ? ? ? ? ? ? ?
Threads ? ? ? ? ? ? ?
tootik ? ? ? ? ? ? ?
Vernissage ? ? ? ? ? ? ?
wafrn ? ? ? ? ? ? ?
WebFinger for WordPress5 N/A N/A N/A N/A ✅ Y ✅ Y #62
Webfinger Browser N/A N/A N/A ✅ Y N/A N/A #35
Welley ? ? ? ? ? ? ?
WordPress ? ? ? ? ? ? ?
WriteFreely ? ? ? ? ? ? ?

Library matrix

This matrix is for tracking ActivityPub software library support for non-ASCII Webfinger handles.

The table has the following columns:

Software Forward Reverse Issue(s)
activity_pub (Elixir) ✅ Y ✅ Y 6
activitypub-webfinger ✅ Y 7 ✅ Y 7 #1
Fedipub ? ? #62
webfinger.js ✅ Y 8 N/A #179

Submitting data

To share data about new ActivityPub and Webfinger implementations and their support for non-ASCII Webfinger handles, make a new pull request to https://github.com/swicg/activitypub-webfinger/.

  1. tags.pub, groups.pub, activitypub.bot ↩

  2. From 1.0.8. Hosts are IDNA (punycode) encoded for WebFinger and federation. Creating non-ASCII local usernames is opt-in per instance (UNICODE_USERNAMES=true in env), since some software can’t yet find or mention them. ↩

  3. Both UTF-8 and IDNA (punycode) forms are supported and are considered interchangeable when referring to local usernames. Site configuration determines which form is sent to other sites. Default is IDNA (punycode). ↩

  4. IDN (punycode) encoded for federation and translated internally for display, as Mastodon currently rejects actor records with non-ASCII usernames; and these also violate other protocol specifications which this software traditionally federates with. Remote usernames which use either form (UTF-8 or IDN) are handled correctly. Uses ‘petnames’ for easier mentioning and searching. ↩

  5. Standalone WebFinger plugin. WordPress logins are ASCII only, so a non-ASCII username is set as a custom WebFinger resource on the profile page. ↩

  6. Lookups send the userpart percent-encoded and the host as an A-label. Handles built from an actor use its unencoded preferredUsername (or the decoded last segment of its id) with the host’s A-label. ↩

  7. From version 0.3.0 ↩ ↩2

  8. v3.1.0+ ↩