Telegram prepara a conexão da carteira a um site diretamente na janela de login do Telegram

No código do Telegram Desktop, a conexão da carteira a um site diretamente na janela de login do Telegram está pronta. O site no qual você faz login com sua conta Telegram poderá, na mesma solicitação, pedir o endereço da carteira integrada, e uma única confirmação permitirá que você acesse o site e conecte a carteira a ele via TON Connect. O código está na branch de desenvolvimento do cliente desde 12-13 de outubro, e o mesmo tipo de dado está presente na beta do Telegram para macOS de 20 de outubro. Nas versões lançadas e na documentação da API, a função ainda não está disponível.

Como isso vai parecer

A janela de confirmação de login atualmente mostra qual site está solicitando acesso, de qual dispositivo a solicitação veio e o toggle switch “Allow Messages” — para permitir que o bot do site envie mensagens para você. De acordo com o código do cliente, se o site solicitou a carteira, abaixo disso aparecem:

• a linha “Wallet” com o endereço da sua carteira Telegram, dividido em duas metades (clicar copia o endereço);
• o toggle switch “Connect Wallet”, ativado por padrão;
• a explicação: “{bot} está pedindo para conectar sua carteira a este site. O site verá seu endereço TON, saldo e transações, mas não poderá transferir fundos sem sua permissão. A conexão assina uma prova de login, não uma transação.”

Todas as seis novas linhas da interface foram adicionadas em um único commit em 12 de outubro com a descrição “Grant site wallet access from the login confirmation”. Se o toggle switch for deixado ativado, após a confirmação do login, o cliente pedirá para desbloquear a carteira e só então enviará a concordância para o servidor.

A carteira é solicitada apenas no login via link, quando o site o envia para confirmação no Telegram. Os botões de login abaixo das mensagens de bots em chats não carregam essa solicitação: em sua branch de código, o campo da carteira é enviado vazio.

O que o site recebe

A conexão ocorre via TON Connect — o protocolo que sites e mini apps usam para conectar carteiras TON. No cenário usual, o site mostra uma lista de carteiras, o usuário escolhe a sua e confirma a conexão já na carteira. Aqui, essa etapa é integrada à janela de login: junto com a solicitação de login, o servidor do Telegram transmite ao cliente o número da sessão TON Connect e o identificador do site nela.

Ao confirmar o login, o cliente cria uma sessão no lado da carteira, assina um ton_proof para ela e envia a assinatura junto com a concordância para o login. ton_proof é uma assinatura pela qual a carteira prova ao site que o endereço pertence a ela; ela não autoriza transferências. O texto da assinatura é composto por três valores: o identificador do bot do site, o identificador do site no TON Connect e o número da sessão, com o prefixo tc-login. Assim, a assinatura fica vinculada a um login específico e não serve para outro login.

No esquema da API, três campos foram adicionados para isso na resposta à solicitação de login (a flag “carteira necessária”, o número da sessão, o identificador do site) e um campo na confirmação de login — tonconnect_session com a prova de posse da carteira. De acordo com o histórico do esquema, este é o layer 231 de 12 de outubro. Em core.telegram.org, o layer 225 é descrito, e os campos da carteira não estão lá.

Cadeia de chamadas no código do cliente

1. O servidor responde à solicitação de login urlAuthResultRequest com a flag request_wallet e os campos tc_session_id, tc_client_id.
2. Após clicar em “Entrar”, o cliente chama wallet.tonConnectCreateSession com o identificador do site e o endereço do manifest.
3. Aguarda o servidor ler o manifest: pesquisa wallet.tonConnectGetPending a cada 5 segundos, no máximo 12 vezes, ou seja, até um minuto.
4. Registra a chave da sessão (wallet.tonConnectRegisterKey), recebe a chamada e assina a resposta junto com o ton_proof.
5. Envia messages.acceptUrlAuth com o campo tonconnect_session — número da sessão, resposta à chamada, corpo e prova de posse da carteira.

Quais sites não receberão a carteira

O cliente não pega o endereço do manifest do site, mas o constrói sozinho: https://<domain>/tonconnect-manifest.json. O manifest é um pequeno arquivo com o nome e o ícone do site que o TON Connect mostra na carteira. Se o servidor retornar um manifest de outro host, o cliente recusa com um erro sobre manifest inválido. O site no qual você faz login e o site que recebe a carteira, dessa forma, sempre coincidem.

Para dois domínios, a carteira não é fornecida de forma alguma, e a janela exibe “Wallet access can't be granted to this site”. O primeiro é telegram.org. O segundo o cliente descobre do servidor: é o domínio que o próprio Telegram usa para verificar a posse da carteira na resposta wallet.getProofChallenge. Pelo código, a assinatura pela qual a carteira confirma a posse ao próprio Telegram não pode ser obtida através de um site de terceiros.

Se a carteira foi criada em outro dispositivo

A carteira integrada do Telegram mantém a chave no dispositivo. Se a chave atual não estiver neste computador, a janela de login mostrará “This device doesn't hold the current key of this wallet” e um link “Restore the key”: a chave pode ser restaurada sem fechar a janela de login. Sem a chave, o toggle switch fica inativo, e o login no site ocorre normalmente, sem a carteira.

Onde isso já está disponível

Se a solicitação da carteira está ativada no servidor, não é visível pelos clientes: a janela aparecerá somente quando o site a solicitar, e o Telegram não publicou instruções para sites. Até agora, muitos sites não conseguiam verificar a assinatura ton_proof ao conectar via TON Connect com a carteira integrada do Telegram — para isso, a partir da versão TON Connect 5.0, é necessária uma branch de verificação separada.