Os dois registros por trás de um handle de domínio personalizado no Bluesky

O que é um handle de domínio personalizado no Bluesky?

Um domínio que é seu vira o seu handle de domínio personalizado no Bluesky assim que você publica um registro provando que você o controla: ou um registro DNS TXT no subdomínio _atproto, ou um arquivo de texto puro servido em /.well-known/atproto-did. O Bluesky roda sobre o AT Protocol, e é a especificação de handles dele que decide se o seu registro funciona. Os artigos de ajuda descrevem os botões do app. A especificação descreve o que a rede confere depois.

Leia isto antes de mexer no DNS: "Handles are mutable and human-friendly account usernames, in the form of a DNS hostname." O seu handle é um nome de host, e por isso mozilla.org funciona e mozilla sozinho não: "'bare' top-level domains are not allowed as handles, even if valid 'hostnames' and 'DNS names.'"

Atrás de cada handle existe um DID, um dos que a especificação chama de "the long-term persistent identifiers for accounts in atproto". Você cola o seu DID no registro que escolher, então essa é a parte que interessa aqui. O resto do que é um DID cabe em uma página própria.

Qual registro você publica, e o que vai dentro dele?

Publique um destes dois, com o seu próprio DID no lugar do exemplo.

O prefixo é o erro de colagem mais comum, e nenhum dos dois métodos avisa você. Resolvedores de DNS ignoram "TXT records with values not starting with did=." Por HTTPS, esse mesmo prefixo quebra o corpo da resposta, que a especificação quer como "the DID... with no prefix or wrapper formatting".

O registro DNS para um handle no ápice de example.com:

Type:  TXT
Name:  _atproto
Value: did=did:plc:ewvi7nxzyoun6zhxrhs64oiz
TTL:   300

Para um handle em subdomínio como alice.example.com, o nome é _atproto.alice. A maioria dos painéis de DNS acrescenta a zona por você, então digitar o _atproto.alice.example.com completo produz _atproto.alice.example.com.example.com e uma falha silenciosa.

Só pode existir um registro: "If multiple valid records with different DIDs are present, resolution should fail." Um registro antigo de uma conta anterior quebra o novo.

A resposta HTTPS que a especificação pede, reproduzida exatamente:

HTTP/1.1 200 OK
Content-Length: 33
Content-Type: text/plain
Date: Wed, 14 Jun 2023 00:47:21 GMT

did:plc:ewvi7nxzyoun6zhxrhs64oiz

Um parágrafo depois, na mesma seção, a especificação afrouxa a própria exigência: "The response Content-Type header does not need to be strictly verified." Sirva text/plain mesmo assim, já que você não sabe qual resolvedor lê qual linha.

O seu DID sai do app. O tutorial do Bluesky dá o caminho como "Settings", depois "Account", depois "Handle", e mostra o host do registro como _atproto com o valor "did=did:plc:[your value here]".

Quais são as regras de sintaxe dos handles?

Sete regras, e um handle precisa cumprir todas elas:

1. O handle inteiro é só ASCII e tem no máximo 253 caracteres.
2. Os segmentos são separados por pontos ASCII, e precisa haver pelo menos dois.
3. Sem pontos no começo ou no fim, e sem a sintaxe de DNS com ponto final.
4. Cada segmento tem de 1 a 63 caracteres, tirados das letras ASCII a-z, dos dígitos 0-9 e do hífen -.
5. Um segmento não pode começar nem terminar com hífen.
6. O último segmento, o domínio de topo, não pode começar com um dígito.
7. Handles não diferenciam maiúsculas de minúsculas e são normalizados para minúsculas.

Sobre a última regra: "the handle input string BlueskyWeb.xyz should be normalized, stored, and displayed as blueskyweb.xyz." Se a sua marca leva maiúsculas, o handle não vai levar.

A expressão regular de referência da especificação:

/^([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$/

253 é o número de manchete e não é aquele em que você deve se basear. Enterrado nas diretrizes de implementação há um menor: "handles should be limited to at most 244 characters... because DNS verification works with the prefix _atproto., which adds 9 characters." Qualquer coisa entre 245 e 253 caracteres é legal pela seção de sintaxe e impossível de resolver por DNS, e a saída de emergência está em outra seção: "The HTTPS method will work for such handles."

Exemplos que a especificação marca como válidos, ao lado dos que ela rejeita:

Domínios internacionalizados funcionam só em forma codificada: "Such handles must be stored and transmitted in encoded ASCII form."

Quais TLDs nunca podem ser um handle do Bluesky?

Oito domínios de topo estão vetados de saída. Da especificação: "the initial list of disallowed TLDs includes: .alt, .arpa, .example, .internal, .invalid, .local, .localhost, .onion."

O modo de falha delas é deliberado e estranho. TLDs reservadas "should not fail syntax validation... but they must immediately fail any attempt at registration, resolution, etc." Então laptop.local e blah.arpa passam em uma checagem por regex e falham para sempre na resolução. Um validador que roda só a regex dá o handle como certo até a rede recusá-lo.

Três itens carregam condições extras:

• .onion está bloqueada por um motivo declarado, e não em definitivo: "Resolution of handles via Tor would require ecosystem-wide support, so they are currently disallowed." A seção de mudanças futuras acrescenta que ".onion handles would be allowed at some point in the future".
• .invalid está reservada para um único valor sentinela, handle.invalid, que a API devolve "to indicate that there is no bi-directionally valid handle for the given DID."
• .test não está na lista de vetadas e também não dá para usar. Ela "may be used in atproto development, but should fail in real-world environments."

Repare na palavra "initial". A lista não é apresentada como final, e a especificação linka a seção de domínios reservados da Wikipédia em vez de manter um registro próprio. Oito nomes são o que o protocolo assume por escrito, e a fronteira além disso é traçada em uma página que ninguém do projeto AT Protocol controla.

Como você resolve um handle até o DID dele?

Rode contra uma conta real e as duas metades da checagem acontecem na sua frente. Todos os valores abaixo foram resolvidos em 10 de setembro de 2026.

Comece pelo registro DNS de bsky.app, o handle do próprio Bluesky:

dig +short TXT _atproto.bsky.app

"did=did:plc:z72i7hdynmk6r22z27h6tvur"

Tire o prefixo did= e você tem o DID. O endpoint do próprio protocolo, que os clientes chamam em vez de fazer DNS por conta própria, devolve a mesma resposta:

curl -s "https://public.api.bsky.app/xrpc/com.atproto.identity.resolveHandle?handle=bsky.app"

{ "did": "did:plc:z72i7hdynmk6r22z27h6tvur" }

Agora busque o documento DID, que é a outra metade da checagem:

curl -s https://plc.directory/did:plc:z72i7hdynmk6r22z27h6tvur

{
  "@context": ["https://www.w3.org/ns/did/v1", "https://w3id.org/security/multikey/v1", "https://w3id.org/security/suites/secp256k1-2019/v1"],
  "id": "did:plc:z72i7hdynmk6r22z27h6tvur",
  "alsoKnownAs": ["at://bsky.app"],
  "verificationMethod": [
    {
      "id": "did:plc:z72i7hdynmk6r22z27h6tvur#atproto",
      "type": "Multikey",
      "controller": "did:plc:z72i7hdynmk6r22z27h6tvur",
      "publicKeyMultibase": "zQ3shQo6TF2moaqMTrUZEM1jeuYRQXeHEx4evX9751y2qPqRA"
    }
  ],
  "service": [
    {
      "id": "#atproto_pds",
      "type": "AtprotoPersonalDataServer",
      "serviceEndpoint": "https://puffball.us-east.host.bsky.network"
    }
  ]
}

O campo que decide tudo é alsoKnownAs, com at://bsky.app dentro. O handle apontava para o DID, e o documento DID aponta de volta. A especificação exige as duas direções: "The link between handle and DID must be confirmed bidirectionally, otherwise anybody could create handle aliases for third-party accounts." Publicar um registro TXT nomeando o DID de outra pessoa não rende nada, porque o documento DID dela não nomeia o seu domínio.

Quando um handle não resolve, o endpoint responde com uma única string:

{ "error": "InvalidRequest", "message": "Unable to resolve handle" }

Isso chega com HTTP 400, e é a mesma mensagem para um registro que falta, um handle válido em uma TLD reservada e um domínio que não existe. Diagnostique com dig e curl em vez de ler a resposta da API.

Quatro handles resolvidos naquele dia, todos confirmados nas duas direções contra o plc.directory:

Essa divisão é o desenho da especificação funcionando como foi escrito. Organizações com um painel de DNS usam o registro TXT. O handle que responde por HTTPS é um subdomínio bsky.social, o caso dos "large-scale web services which may not have the infrastructure to automate the registration of thousands or millions of DNS TXT records" para o qual o método foi criado.

Pedir https://mozilla.org/.well-known/atproto-did devolve uma página HTML 404, e theverge.com faz o mesmo. Os dois handles resolvem sem problema. Só um método precisa responder, e um 404 no caminho que você não usou não custa nada.

Onde os handles de domínio personalizado quebram?

Os redirecionamentos merecem uma nota, porque outras especificações well-known os proíbem e esta não: "HTTP redirects (eg, 301, 302) are allowed, up to a reasonable number of redirect hops." Um redirecionamento do ápice para www não tem problema. Um redirecionamento que cai em um 404 tem, e é o que acontece quando o ápice encaminha para www e o arquivo nunca foi publicado lá.

O que acontece com as suas publicações agendadas quando o handle muda?

Nada, e o motivo é estrutural. A sua conta é o DID, que o protocolo chama de persistente, enquanto o handle é um rótulo mutável resolvido do zero sempre que um cliente precisa dele. Sair de you.bsky.social para yourbrand.com deixa o DID intacto, então uma fila montada em um agendador de posts para Bluesky sobrevive à troca, e os números de uma ferramenta de analytics do Bluesky também. Isso é comportamento do protocolo, não algo que uma ferramenta de publicação concede ou tira.

Duas coisas mudam de fato. As publicações que você já publicou passam a aparecer sob o handle novo, porque os clientes renderizam o handle que resolvem e não um congelado no momento da publicação. E qualquer texto que cite o seu handle antigo agora está errado, o que dói mais quando você publica o mesmo post em várias redes de uma vez e o handle do Bluesky está em uma legenda que você compartilha com X, LinkedIn e Threads. Procure a string antiga nos seus rascunhos na fila antes de trocar. Cinco minutos em um calendário de conteúdo, contra um mês de publicações para corrigir depois.

Perguntas frequentes

Preciso do registro DNS e do arquivo well-known ao mesmo tempo?

Não. Um só basta, e a especificação chama o método DNS TXT de "the recommended and preferred resolution method for individual handle configuration." Se você publicar os dois e eles nomearem DIDs diferentes, os resolvedores preferem a resposta do DNS. Apague o desatualizado em vez de deixar o conflito de pé.

Por que o meu registro TXT precisa de did= e o arquivo HTTPS não?

Os dois métodos são interpretados de formas diferentes. O DNS segue a RFC-1464 para guardar atributos em registros TXT, então o valor é uma chave e um valor, e os resolvedores ignoram "TXT records with values not starting with did=." O método HTTPS devolve "the DID as the HTTP body with no prefix or wrapper formatting", então esse mesmo prefixo deixa o corpo impossível de interpretar.

Posso usar um domínio .local ou .internal para testar?

Não. As duas estão na lista de vetadas, e TLDs reservadas "must immediately fail any attempt at registration, resolution, etc." mesmo passando na validação de sintaxe. A TLD .test é a pensada para desenvolvimento, e a especificação ainda assim espera que ela "fail in real-world environments".

Qual é o tamanho máximo de um handle do Bluesky?

253 caracteres ASCII pelas regras de sintaxe, 244 na prática. O prefixo _atproto. usado na verificação por DNS "adds 9 characters, and that overall name needs to be valid." Acima de 244, só o método HTTPS resolve.

O que é handle.invalid e por que estou vendo isso?

É o valor que a API devolve quando um DID não tem handle funcionando, usado "to indicate that there is no bi-directionally valid handle for the given DID." Ele aparece depois que um handle que antes resolvia para de resolver. Republicar o registro correto limpa o estado.

Trocar o meu handle quebra os links que as pessoas já compartilharam?

Não. O tutorial do Bluesky afirma que "Any tags or mentions with your old handle will still point to your account", porque as menções guardam o DID e não o texto do handle. Desde dezembro de 2024 o seu nome de usuário .bsky.social anterior também fica reservado para você em vez de ser liberado.

Por que publicar o DID de outra pessoa no meu registro TXT não funciona?

O protocolo verifica o vínculo nos dois sentidos. Seu registro pode apontar para qualquer DID, mas o documento DID também precisa apontar de volta para o seu domínio no campo alsoKnownAs, com uma URI at://. O documento DID do bsky.app lista at://bsky.app exatamente por isso, e sem esse vínculo reverso qualquer pessoa poderia criar apelidos de handle para contas de terceiros, então um registro TXT com o DID de outra pessoa não leva a nada.

Posso começar a publicar com o meu handle de domínio personalizado logo após publicar o registro?

Nem sempre na hora. Os serviços armazenam em cache os resultados da resolução de handle por um tempo, então uma resposta antiga pode continuar aparecendo mesmo com o registro já correto. O TTL do registro de exemplo acima é de 300 segundos, e configurar um TTL curto antes da mudança e resolver de novo depois reduz essa espera.

O que acontece com o meu antigo nome de usuário .bsky.social depois de mudar para um domínio próprio?

Ele continua reservado para você. Desde dezembro de 2024, o Bluesky mantém o seu handle anterior em .bsky.social em vez de liberá-lo quando você muda para um domínio próprio, então ninguém mais pode ficar com ele.

Um redirecionamento do domínio raiz para o www quebra a verificação do handle?

Não por si só. A especificação permite redirecionamentos HTTP até um número razoável de saltos, então redirecionar do domínio raiz para o www no caminho well-known não é problema por si mesmo. Isso só quebra a verificação se o redirecionamento terminar em um lugar onde o arquivo nunca foi implantado, já que um redirecionamento que acaba em 404 não resolve.