Exportar Tokens OAuth do Mastodon: Backup e Restauração

Ao fazer login em um aplicativo cliente Mastodon como Tusky, Fedilab ou o aplicativo oficial do Mastodon, o app recebe um token OAuth que concede permissão para agir em seu nome. Se você perder o acesso à sua conta ou precisar trocar de dispositivo sem reautorizar cada aplicativo, fazer backup desses tokens economiza tempo e evita interrupções no serviço. Os tokens OAuth são armazenados localmente no seu dispositivo e não são sincronizados entre dispositivos por padrão. Este artigo explica como exportar tokens OAuth do banco de dados do Mastodon, fazer backup com segurança e restaurá-los em uma nova instalação ou dispositivo.

Entendendo os Tokens OAuth no Mastodon

OAuth 2.0 é o framework de autorização que o Mastodon usa para permitir que aplicativos de terceiros acessem sua conta sem compartilhar sua senha. Quando você autoriza um aplicativo, o Mastodon emite um token de acesso — uma string de caracteres — que o app envia em cada requisição à API. O token define o escopo do acesso, como ler postagens, publicar em seu nome ou seguir contas.

O token é armazenado em dois lugares. No servidor Mastodon, ele fica na tabela oauth_access_tokens do banco de dados PostgreSQL. No lado do cliente, o app salva o token em seu armazenamento local — geralmente um arquivo no diretório de dados do aplicativo no desktop ou no chaveiro do sistema no celular. Fazer backup do token significa salvá-lo de qualquer um desses locais para que você possa reutilizá-lo depois sem reautorizar o aplicativo.

Por que Você Pode Precisar Exportar Tokens

Você pode precisar exportar tokens OAuth ao migrar para uma nova instância do Mastodon, trocar de aplicativo cliente ou reinstalar seu sistema operacional. Sem um backup, cada aplicativo precisa ser reautorizado individualmente, o que pode ser tedioso se você usa vários apps. Além disso, alguns apps perdem o token se você limpar os dados do aplicativo, e você teria que fazer login novamente.

Como Exportar Tokens OAuth do Mastodon

Existem dois métodos principais para exportar tokens OAuth: a partir do banco de dados do servidor e a partir dos dados do aplicativo cliente. Escolha o método que corresponde ao seu nível de acesso e conforto técnico.

Método 1: Exportar do Banco de Dados do Servidor Mastodon

Este método requer acesso ao banco de dados PostgreSQL do servidor Mastodon. Você precisa das credenciais do banco de dados, que geralmente estão no arquivo .env.production da sua instalação do Mastodon.

1. Conecte-se ao servidor Mastodon via SSH
   Faça login no servidor usando SSH. Navegue até o diretório do Mastodon, geralmente /home/mastodon/live.
2. Acesse o console Rails
   Execute RAILS_ENV=production bin/rails c para abrir o console Rails. Isso dá acesso direto aos modelos da aplicação.
3. Consulte a tabela de tokens de acesso OAuth
   No prompt do console, digite Doorkeeper::AccessToken.all.each { |token| puts token.token }. Isso imprime todos os tokens de acesso no banco de dados. Para filtrar por usuário, use Doorkeeper::AccessToken.where(resource_owner_id: USER_ID).each { |token| puts token.token }.
4. Salve a saída em um arquivo
   Copie os tokens impressos e cole-os em um arquivo de texto seguro, por exemplo mastodon_tokens_backup.txt. Armazene este arquivo em um local criptografado.
5. Saia do console Rails
   Digite exit e feche a sessão SSH.

Método 2: Exportar dos Dados do Aplicativo Cliente

Para aplicativos de desktop como TheDesk ou Whalebird, o token geralmente é armazenado em um arquivo de configuração JSON na pasta de dados do aplicativo do usuário. Aplicativos móveis normalmente armazenam tokens no chaveiro do sistema, que não é facilmente exportável sem jailbreak ou root no dispositivo.

1. Localize o diretório de configuração do aplicativo
   No Windows, verifique %APPDATA%\AppName. No macOS, procure em ~/Library/Application Support/AppName. No Linux, verifique ~/.config/AppName.
2. Encontre o arquivo que contém o token
   Procure por arquivos chamados config.json, settings.json ou tokens.json. Abra o arquivo em um editor de texto e procure por uma chave chamada access_token ou token.
3. Copie a string do token
   Selecione o valor do token — uma longa string alfanumérica — e copie para a área de transferência. Cole em um arquivo de backup seguro.
4. Copie também o client_id e client_secret, se presentes
   Alguns aplicativos armazenam as credenciais do cliente junto com o token. Salve-os também, pois são necessários para restaurar o registro do aplicativo em um novo dispositivo.

Como Restaurar Tokens OAuth no Mastodon

Restaurar um token depende se você está restaurando para a mesma instância do Mastodon ou para uma diferente. Os tokens estão vinculados a uma URL de instância específica e a uma conta de usuário. Você não pode reutilizar um token da instância A na instância B.

Restaurando na Mesma Instância via Console Rails

1. Abra o console Rails
   Execute RAILS_ENV=production bin/rails c no servidor.
2. Crie um novo registro de token de acesso
   Digite token = Doorkeeper::AccessToken.new(resource_owner_id: USER_ID, application_id: APP_ID, token: 'SEU_TOKEN_BACKUP', scopes: 'read write follow', expires_in: nil). Substitua USER_ID pelo ID do usuário no banco de dados, APP_ID pelo ID do aplicativo OAuth e a string do token pelo seu backup.
3. Salve o token
   Digite token.save! para persistir o token no banco de dados.
4. Verifique se o token funciona
   Use uma ferramenta como curl para testar o token: curl -H "Authorization: Bearer SEU_TOKEN_BACKUP" https://suainstancia.com/api/v1/accounts/verify_credentials. Você deve receber uma resposta JSON com os detalhes da sua conta.

Restaurando em um Aplicativo Cliente

1. Localize o diretório de configuração do aplicativo no novo dispositivo
   Instale o aplicativo e execute-o uma vez para criar a pasta de configuração. Em seguida, feche o app.
2. Substitua o token no arquivo de configuração
   Abra o arquivo de configuração do backup e cole o token no campo correspondente. Se o arquivo também contiver client_id e client_secret, substitua-os também.
3. Reinicie o aplicativo
   Inicie o app. Ele agora deve autenticar usando o token restaurado sem solicitar login.

Problemas Comuns ao Fazer Backup e Restaurar Tokens OAuth

Token Expirado ou Revogado

Os tokens do Mastodon podem expirar se o administrador do servidor configurou um tempo de expiração. Além disso, os tokens são revogados quando o usuário altera a senha ou desautoriza o aplicativo em Preferências > Conta > Aplicativos autorizados. Se o token não funcionar mais, você deve reautorizar o aplicativo normalmente.

Incompatibilidade de ID do Aplicativo

Ao restaurar um token para um registro de aplicativo diferente, o application_id deve corresponder ao ID do aplicativo original. Se você registrou um novo aplicativo no servidor, o token antigo não funcionará com o novo app. Sempre salve o client_id e client_secret junto com o token.

Alterações de Escopo

Se você restaurar um token com um escopo que não corresponde mais aos escopos solicitados pelo aplicativo, a API pode rejeitar as requisições. Por exemplo, se o token original tinha escopo read mas o app agora requer write, você precisa criar um novo token com os escopos corretos.

Item	Backup no Servidor	Backup no Cliente
Acesso necessário	SSH e credenciais do banco de dados	Acesso ao sistema de arquivos do dispositivo
Localização do token	Tabela oauth_access_tokens no PostgreSQL	Arquivo de configuração local ou chaveiro
Melhor para	Administradores de servidor gerenciando muitos usuários	Usuários individuais fazendo backup de seus próprios apps
Risco de roubo do token	Alto se o arquivo de backup não for criptografado	Moderado — depende da segurança do dispositivo
Portabilidade entre instâncias	Não portável	Não portável

Os tokens OAuth estão vinculados a uma instância específica do Mastodon e a uma conta de usuário. Eles não podem ser transferidos entre instâncias. Sempre armazene os arquivos de backup em um contêiner criptografado ou gerenciador de senhas. Para a maioria dos usuários, o método mais fácil é salvar o token do arquivo de configuração do aplicativo cliente. Administradores de servidor devem usar o método do console Rails para operações em lote. Após restaurar um token, teste-o com uma chamada simples à API para confirmar que funciona antes de depender dele.