WebFinger JRD Builder (RFC 7033)

WebFinger e JRD: como o Fediverse encontra pessoas

WebFinger é o protocolo de descoberta definido pela RFC 7033 (setembro de 2013) que transforma um identificador amigável — [email protected] — em uma descrição legível por máquina de onde aquele usuário realmente vive na web. É o substrato sobre o qual o Fediverse roda: Mastodon, Pleroma, Pixelfed, GoToSocial, Misskey, Akkoma e os previews federados do Meta Threads caminham por WebFinger para resolver @[email protected] antes que a primeira mensagem ActivityPub possa ser entregue. Sem WebFinger não há federação.

Uma resposta WebFinger é um JRD (JSON Resource Descriptor) servido em um endpoint fixo com content type específico:

GET /.well-known/webfinger?resource=acct:[email protected] HTTP/1.1
Host: example.com
Accept: application/jrd+json

200 OK
Content-Type: application/jrd+json
Access-Control-Allow-Origin: *

{
  "subject": "acct:[email protected]",
  "aliases": [
    "https://example.com/@alice",
    "https://example.com/users/alice"
  ],
  "links": [
    { "rel": "self",
      "type": "application/activity+json",
      "href": "https://example.com/users/alice" },
    { "rel": "http://webfinger.net/rel/profile-page",
      "type": "text/html",
      "href": "https://example.com/@alice" },
    { "rel": "http://ostatus.org/schema/1.0/subscribe",
      "template": "https://example.com/authorize_interaction?uri={uri}" }
  ]
}

O esquema acct: e o caminho .well-known

O esquema URI acct: (RFC 7565) foi desenhado especificamente para isso — acct:[email protected] significa "a conta chamada alice em example.com" sem se comprometer com email, ActivityPub ou qualquer outro protocolo. O caminho /.well-known/ vem da RFC 8615; o endpoint WebFinger é uma das entradas mais implantadas lá, ao lado de /.well-known/openid-configuration e /.well-known/security.txt. WebFinger substitui o formato XML legado XRD do OpenID 2.0 — o formato só-JSON é dramaticamente mais simples de servir como arquivo estático.

Relações de link obrigatórias e CORS

Para interoperabilidade Fediverse as relações de link essenciais são:

• self com application/activity+json — URL do actor ActivityPub
• http://webfinger.net/rel/profile-page — perfil HTML humano
• http://ostatus.org/schema/1.0/subscribe — template para follow remoto
• http://schemas.google.com/g/2010#updates-from — feed Atom (legado OStatus)

CORS não é opcional: sirva Access-Control-Allow-Origin: * ou clientes web do Fediverse falham silenciosamente. O endpoint também precisa aceitar o parâmetro de query resource que pode URL-encodar o dois-pontos como %3A.

Operação, cache e privacidade

Instâncias reais cacheiam respostas WebFinger por horas — Cache-Control: max-age=3600 é típico. O Mastodon limita agressivamente requisições entrantes (o rollout de federação Threads–Mastodon em 2024 estressou isso). Preocupação de privacidade: um endpoint WebFinger público confirma a existência da conta — útil para descoberta legítima, mas vira superfície de enumeração para assédio. Algumas instâncias (sharkey, akkoma) permitem authorized fetch: requisições HTTP assinadas obrigatórias até para WebFinger. Os hubs brasileiros do Fediverse (mastodon.com.br, ursal.zone, bolha.us) expõem WebFinger padrão.

FAQ

Preciso de WebFinger se eu rodo um servidor ActivityPub? Sim. O próprio ActivityPub não define lookup de nome para actor — WebFinger é a ponte de facto entre handles e URLs de actor.

Dá para desabilitar WebFinger por privacidade? Alguns softwares de instância permitem exigir autenticação (AUTHORIZED_FETCH=true). Desabilitar completamente quebra federação — você pode ser seguido, mas só por quem já conhece a URL do actor.

Por que application/jrd+json e não application/json puro? A RFC 7033 obriga o media type JRD — clientes estritos rejeitam respostas servidas como JSON cru.

O Meta Threads usa WebFinger? Sim — o gateway de federação do Threads expõe WebFinger para contas Threads que optaram in desde 2024, retornando links self ActivityPub.