> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/contributor/contributor-pt/autenticacao/authchain.md). # Cadeia de autenticação Muitas ações no protocolo Decentraland exigem ou se beneficiam de autorização com uma assinatura da conta Ethereum do usuário. Por exemplo: 1. Enviar uma nova versão de qualquer [Entity](https://github.com/decentraland/docs/tree/main/content/entities.md) que pertençam a eles (como o perfil deles). 2. Autenticar-se em serviços de terceiros. 3. Autorizar delegados a agir em seu nome. Para realizar essas ações, usuários e delegados devem assinar payloads que descrevam sua intenção e produzir uma *serializada em JSON*. ## Introdução As cadeias de autenticação encapsulam uma série de etapas de verificação, sendo que cada etapa depende 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 um payload assinado representando a ação solicitada. Assim, a menor cadeia contém dois elementos, que indicam: ```md 1. A autoridade é a conta Ethereum 2. O payload é , autorizado por ``` Essa cadeia básica pode ser avaliada verificando-se se a chave pública da assinatura corresponde ao endereço. Nesse caso, ela é equivalente a uma assinatura simples. Quando os usuários autorizam delegados a agir em seu nome, etapas intermediárias aparecem 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. O payload é , autorizado 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 equivalente à autoridade raiz. {% endhint %} Essa cadeia de um único delegado é a forma mais comum de autorização usada no Decentraland, já que os usuários autorizam uma chave para o 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 `carga útil` e uma correspondente `assinatura`. | Campo | Valor | | ------------ | ------------------------------------------------------------------------------------ | | `type` | O nome de um tipo ([veja abaixo](#types)). | | `carga útil` | Uma string dependente do tipo. | | `assinatura` | A assinatura Ethereum codificada em hexadecimal de `carga útil`, 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 (ou seja, o usuário), deve atender a estas condições: 1. O `type` é [`SIGNER`](#SIGNER) 2. O `carga útil` é a conta Ethereum codificada. 3. O `assinatura` está vazio. Por exemplo: ```json // Primeira etapa em qualquer cadeia de autenticação: { "type": "SIGNER", "payload": "0xdB055877e6c13b6A6B25aBcAA29B393777dD0a73", "signature": "" } ``` A segunda etapa deve carregar uma `assinatura` assinatura desta conta para sua `carga útil`. ### Etapas Intermediárias: Delegação Quando delegados estão agindo em nome do usuário, um item é adicionado ao meio da cadeia para cada um deles. As condições para essas etapas são: 1. O tipo é [`ECDSA_EPHEMERAL`](#ECDSA_EPHEMERAL) 2. O `carga útil` é um texto especialmente elaborado (veja abaixo). O `carga útil` foi projetado para ser fácil de ler e fácil de analisar, já que tanto humanos (ao usar a UI da carteira) quanto programas (ao criar e validar) devem trabalhar com ele. Ele contém exatamente 3 linhas de texto simples, com distinção entre maiúsculas e minúsculas: ```md Endereço efêmero: Expiração: ``` Por exemplo, este é um payload típico usado pelos World Explorers durante o login, quando geram sua chave de delegado temporária para o usuário aprovar: ``` Decentraland Login Endereço efêmero: 0xBB9aDF0183b1742196A4Aa55622D5838f4f483a7 Expiração: 2023-02-25T13:00:19.730Z ``` Observe que: 1. O `Endereço efêmero` não precisa ser uma conta Ethereum real com fundos na blockchain. O campo pode representar apenas uma chave pública temporária. 2. O `Expiração` é uma data e hora serializada em [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) forma. Não precisa ser UTC. 3. A chave de delegado 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 maior clareza): ```json { "type": "ECDSA_EPHEMERAL", "payload": "Decentraland Login\nEndereço efêmero: 0xBBa7...\nExpiração: 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 Depois de o `SIGNER` ter sido especificado e todas as `ECDSA_EPHEMERAL` chaves de delegado terem sido validadas verificando a cadeia de assinaturas intermediárias, a etapa final é a ação real que precisa ser autorizada. O `carga útil` depende do `type` da etapa. Por exemplo, se um usuário estiver 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 de Conteúdo): "type": "ECDSA_SIGNED_ENTITY", // O payload é a string de ID bruta: "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. Essa é a abordagem recomendada. No entanto, o protocolo não impõe isso. Os desenvolvedores têm permissão para usar uma estratégia de serialização alternativa se for mais conveniente para um caso de uso específico, 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/tree/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 de delegado, há uma compensação: expirações mais curtas aumentam a segurança, mas expirações mais longas melhoram a experiência do usuário (já que os delegados precisam ser renovados com interação humana com menos 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, como referência, solicita autorização para sua chave de delegado por um mês. {% hint style="info" %} Chaves efêmeras nunca devem reter fundos nem possuir a capacidade de transferir ativos digitais. É muito mais seguro para os usuários finais se o vazamento de uma chave efêmera não puder resultar em perdas financeiras. {% endhint %} ## Formalização O que se segue é uma definição mais formal e precisa dos processos envolvidos. Siga estas instruções para lidar com sucesso com cadeias de autenticação. ### Criação Os clientes que criam uma cadeia de autenticação para o usuário seguem estas etapas: 1. Adicione a etapa de identificação: 1. Defina o `type` para `SIGNER`. 2. Defina o `carga útil` 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 de delegado existente (pode exigir interação). 2. Calcule o endereço Ethereum do delegado derivado da chave pública correspondente. 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 `carga útil` nesta forma exata: ```md Endereço efêmero: Expiração: ``` 7. Defina o `assinatura` campo para a `carga útil` 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 `carga útil` para o valor específico do tipo (como o ID da entidade). 3. Defina o `assinatura` campo para a `carga útil` 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 a verificação seguem estas etapas: 1. Verifique a identificação: 1. Verifique o `type` é `SIGNER`. 2. Verifique o `carga útil` é o endereço Ethereum do usuário. 3. Verifique o `assinatura` é uma string vazia. 2. Verifique os delegados: 1. Verifique o `type` é `ECDSA_EPHEMERAL`. 2. Verifique o `carga útil` está nesta forma e extraia os campos: ```md Endereço efêmero: Expiração: ``` 3. Verifique o `data` ainda está no futuro. 4. Verifique o `propósito` é suportado pelo seu serviço. 5. Verifique o `assinatura` é válido para o `carga útil` e a chave pública anterior. 6. Repita para todos os delegados sucessivos. 3. Verifique a autorização da ação: 1. Verifique o `type` é um valor válido ([veja abaixo](#types)). 2. Verifique o `carga útil` é válido para este `type`. 3. Verifique o `assinatura` é válido para o `carga útil` e a chave pública anterior. 4. Aceite a cadeia de autenticação. ### Tipos e Propósitos de Ação Padrão O `type` e `carga útil` 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 com qualquer ação `type`, e sua `carga útil` estrutura, bem como definir um `propósito` para suas chaves de delegado que considerem válidas. O protocolo define três tipos padrão e um propósito padrão: **Tipo `SIGNER`** **Deve** ser o `type` inicial `carga útil` é 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 `carga útil` está na forma descrita acima. **Tipo `ECDSA_SIGNED_ENTITY`** A final `type` na cadeia para autorizar implantações de entidades, onde `carga útil` é o ID de uma entidade pertencente ao usuário. **Objetivo `Decentraland Login`** O habitual `propósito` para World Explorers, assinado tanto ao entrar no mundo quanto ao renovar sua chave de delegado. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.decentraland.org/contributor/contributor-pt/autenticacao/authchain.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.