# Authentication Chain Muitas ações no protocolo Decentraland exigem ou se beneficiam da autorização com uma assinatura da conta Ethereum do usuário. Por exemplo: 1. Enviar uma nova versão de qualquer [Entidade](https://github.com/decentraland/docs/blob/main/content/entities.md) que eles possuam (como seu perfil). 2. Autenticar-se em serviços de terceiros. 3. Autorizar delegados a agir em seu nome. Para executar essas ações, usuários e delegados devem assinar cargas úteis que descrevam sua intenção e produzir um *auth\_chain*. ## Introdução Cadeias de autenticação encapsulam uma série de etapas de verificação, com cada etapa dependendo da verificação bem-sucedida da anterior. Todas as etapas devem ser consideradas válidas pelo verificador para que qualquer ação restrita ocorra. Toda cadeia começa identificando o usuário e termina com uma carga útil assinada que representa a ação solicitada. A menor cadeia contém assim dois elementos, que indicam: ```md 1. A autoridade é a conta Ethereum 2. A carga útil é , autorizada por ``` Essa cadeia básica pode ser avaliada verificando que a chave pública da assinatura corresponde ao endereço. Nesse caso, é equivalente a uma assinatura simples. Quando usuários autorizam delegados a agir em seu nome, aparecem etapas intermediárias na cadeia. Por exemplo, uma cadeia com uma única delegação indicaria: ```md 1. A autoridade é a conta Ethereum 2. O delegado é , autorizado por até 3. A carga útil é , autorizada por ``` As cadeias são mais longas quando delegados autorizam seus próprios delegados. Em outras palavras, a autorização é transitiva. {% hint style="info" %} Você pode pensar nas cadeias de autenticação como análogas às cadeias de certificados TLS usadas em HTTPS, com o usuário como o equivalente à autoridade raiz. {% endhint %} Essa cadeia com um único delegado é a forma mais comum de autorização usada no Decentraland, já que os usuários autorizam uma chave para seu World Explorer para evitar ter que assinar cada ação individual com sua conta Ethereum. ### Construindo uma Cadeia Cada etapa na cadeia de autenticação contém três informações: um `type`, um `payload` e uma `assinatura`. | Campo | Valor | | ------------ | ------------------------------------------------------------------------- | | `type` | O nome de um tipo ([veja abaixo](#types)). | | `payload` | Uma string dependente do tipo. | | `assinatura` | A assinatura Ethereum codificada em hex de `payload`, começando com `0x`. | {% hint style="info" %} Como a serialização mais comum de uma cadeia de autenticação é um array JSON, os exemplos abaixo são apresentados nessa forma. Veja [Transmitindo uma Cadeia](#transmitting) para mais detalhes. {% endhint %} ### Primeira Etapa: Identificação A primeira etapa, que identifica a autoridade original (i.e. o usuário), deve satisfazer estas condições: 1. O `type` estiver [`SIGNER`](#SIGNER) 2. O `payload` é a conta Ethereum codificada. 3. O `assinatura` está vazia. Por exemplo: ```json // Primeira etapa em qualquer cadeia de autenticação: { "type": "SIGNER", "payload": "0xdB055877e6c13b6A6B25aBcAA29B393777dD0a73", "signature": "" } ``` A segunda etapa deve conter uma `assinatura` dessa conta para seu `payload`. ### Etapas Intermediárias: Delegação Quando delegados estão agindo em nome do usuário, um item é adicionado no meio da cadeia para cada um deles. As condições para essas etapas são: 1. O tipo é [`ECDSA_EPHEMERAL`](#ECDSA_EPHEMERAL) 2. O `payload` é um texto especialmente elaborado (veja abaixo). O `payload` é projetado para ser fácil de ler e fácil de analisar, já que tanto humanos (ao usar a interface da carteira) quanto programas (ao criar e validar) devem trabalhar com ele. Contém exatamente 3 linhas de texto simples sensível a maiúsculas/minúsculas: ```md Endereço efêmero: Expiração: ``` Por exemplo, esta é uma carga útil típica usada pelos World Explorers durante o login, quando eles geram sua chave delegada temporária para o usuário aprovar: ``` Decentraland Login Endereço efêmero: 0xBB9aDF0183b1742196A4Aa55622D5838f4f483a7 Expiração: 2023-02-25T13:00:19.730Z ``` Note que: 1. O `Endereço efêmero` não precisa ser uma conta Ethereum real com fundos na blockchain. O campo pode apenas representar uma chave pública temporária. 2. O `Expiração` é uma data/hora serializada em [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) formato. Não precisa ser UTC. 3. A chave delegada deve ser renovada periodicamente com uma nova assinatura do usuário, devido a essa data de expiração. {% hint style="info" %} É prática padrão (e altamente recomendada) gerar uma nova chave para cada renovação (daí o nome `ECDSA_EPHEMERAL`). {% endhint %} Um exemplo de etapa de delegação (valores abreviados para clareza): ```json { "type": "ECDSA_EPHEMERAL", "payload": "Decentraland Login\nEphemeral address: 0xBBa7...\nExpiration: 2021-01-25T...", "signature": "0x1370a4120a7cb0d2f6e4a5..." } ``` A próxima etapa, seja outra delegação ou a autorização final, carrega uma assinatura da chave deste delegado. ### Última Etapa: Autorização Após o `SIGNER` ter sido especificado e todas as `ECDSA_EPHEMERAL` chaves delegadas terem sido validadas verificando a cadeia de assinaturas intermediárias, a etapa final é a ação real que precisa ser autorizada. O `payload` depende do `type` da etapa. Por exemplo, se um usuário está enviando um novo perfil (ou qualquer entidade que possua) para um servidor de conteúdo, o último elemento terá esta forma: ```json { // O tipo indica que `payload` é um ID de entidade (detalhes na seção Content): "type": "ECDSA_SIGNED_ENTITY", // O payload é a string bruta do ID: "payload": "bafkreicfbg7ybpuoslkcf6x2vfnvzl5vwgqtb2pnheqiut2i4sgpblicqi", // A assinatura é produzida pela conta na etapa anterior (usuário ou delegado): "signature": "0x7e71dbbab..." } ``` Se essa última assinatura também for válida, a ação pode prosseguir. ### Transmitindo uma Cadeia Como mencionado acima, a serialização mais comum de uma cadeia de autenticação é um array JSON. Esta é a abordagem recomendada. No entanto, o protocolo não impõe isso. Desenvolvedores podem usar uma estratégia de serialização alternativa se for mais conveniente para um caso de uso particular, como YAML, arquivos CSV, formatos binários otimizados ou strings simples com campos delimitados. Um exemplo de serialização alternativa dentro do próprio protocolo pode ser encontrado no [`SignedFetch`](https://github.com/decentraland/docs/blob/main/runtime/modules/signed_fetch.md) módulo, que usa uma sequência de cabeçalhos HTTP em vez de um array JSON. ### Escolhendo uma Data de Expiração Ao selecionar a duração válida para uma chave delegada, há um trade-off: expirações mais curtas aumentam a segurança, mas expirações mais longas melhoram a experiência do usuário (já que delegados precisam ser renovados com interação humana com menor frequência). Não existe uma estratégia universal para decidir qual deve ser a janela de tempo válida. O World Explorer da Foundation, para referência, solicita autorização para sua chave delegada por um mês. {% hint style="info" %} Chaves efêmeras nunca devem conter fundos nem possuir a capacidade de transferir ativos digitais. É muito mais seguro para usuários finais se o vazamento de uma chave efêmera não puder resultar em perdas financeiras. {% endhint %} ## Formalização O que segue é uma definição mais formal e precisa dos processos envolvidos. Siga estas instruções para lidar com cadeias de autenticação com sucesso. ### Criação Clientes que criam uma cadeia de autenticação para o usuário seguem estes passos: 1. Adicione a etapa de identificação: 1. Defina o `type` para `SIGNER`. 2. Defina o `payload` para o endereço Ethereum do usuário. 3. Defina o `assinatura` para uma string vazia. 2. Adicione etapas de delegação: 1. Gere ou use uma chave privada delegada existente (pode exigir interação). 2. Calcule o endereço Ethereum do delegado derivado da correspondente chave pública. 3. Defina o `type` para `ECDSA_EPHEMERAL`. 4. Defina o `expiração` para uma data no futuro. 5. Escolha um `propósito` para esta chave. 6. Defina o `payload` para esta forma exata: ```md Endereço efêmero: Expiração: ``` 7. Defina o `assinatura` campo para a `payload` assinatura da chave anterior (usuário ou delegado). 8. Repita para todos os delegados sucessivos. 3. Adicione a etapa de autorização da ação: 1. Defina o `type` para um valor válido ([veja abaixo](#types)) 2. Defina o `payload` para o valor específico do tipo (como o ID da entidade). 3. Defina o `assinatura` campo para a `payload` assinatura da chave anterior (usuário ou delegado). 4. Envie a cadeia de autenticação ao verificador. ### Verificação Servidores de conteúdo e serviços de terceiros que implementam verificação seguem estes passos: 1. Verificar identificação: 1. Verifique se o `type` estiver `SIGNER`. 2. Verifique se o `payload` é o endereço Ethereum do usuário. 3. Verifique se o `assinatura` é uma string vazia. 2. Verificar delegados: 1. Verifique se o `type` estiver `ECDSA_EPHEMERAL`. 2. Verifique se o `payload` está nesta forma e extraia os campos: ```md Endereço efêmero: Expiração: ``` 3. Verifique se o `data` ainda está no futuro. 4. Verifique se o `propósito` é suportado pelo seu serviço. 5. Verifique se o `assinatura` é válido para o dado `payload` e a chave pública anterior. 6. Repita para todos os delegados sucessivos. 3. Verificar autorização da ação: 1. Verifique se o `type` é um valor válido ([veja abaixo](#types)). 2. Verifique se o `payload` é válido para este `type`. 3. Verifique se o `assinatura` é válido para o dado `payload` e a chave pública anterior. 4. Aceite a cadeia de autenticação. ### Tipos de Ação e Propósitos Padrão O `type` e `payload` valores para identificação e delegação são padrão e devem ser verificados conforme descrito acima, mas clientes e serviços podem concordar em qualquer `type`, e sua `payload` estrutura, bem como definir um `propósito` para suas chaves delegadas que considerem válido. O protocolo define três tipos padrão e um propósito padrão: **Tipo `SIGNER`** **Deve** ser o `type` inicial na cadeia, onde `payload` é o endereço Ethereum do usuário e `assinatura` é uma string vazia. **Tipo `ECDSA_EPHEMERAL`** **Deve** ser o `type` para etapas intermediárias na cadeia, onde `payload` está na forma descrita acima. **Tipo `ECDSA_SIGNED_ENTITY`** O `type` final na cadeia para autorizar implantações de entidades, onde `payload` é o ID de uma entidade pertencente ao usuário. **Propósito `Decentraland Login`** O usual `propósito` para World Explorers, assinado tanto ao entrar no mundo quanto ao renovar sua chave delegada. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.decentraland.org/contributor/contributor-pt/authentication/authchain.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.