> 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-es/autenticacion/authchain.md). # Cadena de autenticación Muchas acciones en el protocolo de Decentraland requieren o se benefician de una autorización con una firma de la cuenta de Ethereum del usuario. Por ejemplo: 1. Subir una nueva versión de cualquier [Entity](https://github.com/decentraland/docs/tree/main/content/entities.md) que posean (como su perfil). 2. Autenticarse en servicios de terceros. 3. Autorizar a delegados para actuar en su nombre. Para realizar estas acciones, los usuarios y delegados deben firmar payloads que describan su intención y producir un *cadena de autenticación*. ## Introducción Las cadenas de autenticación encapsulan una serie de pasos de verificación, y cada paso depende de la verificación exitosa del anterior. Todos los pasos deben ser considerados válidos por el verificador para que cualquier acción restringida tenga lugar. Toda cadena comienza identificando al usuario y termina con un payload firmado que representa la acción solicitada. La cadena más pequeña contiene así dos elementos, que indican: ```md 1. La autoridad es la cuenta de Ethereum 2. El payload es , autorizado por ``` Esta cadena básica puede evaluarse verificando que la clave pública de la firma corresponde a la dirección. En este caso, es equivalente a una firma simple. Cuando los usuarios autorizan a delegados a actuar en su nombre, aparecen pasos intermedios en la cadena. Por ejemplo, una cadena con una sola delegación indicaría: ```md 1. La autoridad es la cuenta de Ethereum 2. El delegado es , autorizado por hasta 3. El payload es , autorizado por ``` Las cadenas son más largas cuando los delegados autorizan a sus propios delegados. En otras palabras, la autorización es transitiva. {% hint style="info" %} Puede pensar en las cadenas de autenticación como análogas a las cadenas de certificados TLS usadas en HTTPS, con el usuario como equivalente de la autoridad raíz. {% endhint %} Esta cadena de un solo delegado es la forma más común de autorización usada en Decentraland, ya que los usuarios autorizan una clave para su World Explorer para evitar tener que firmar cada acción individual con su cuenta de Ethereum. ### Construcción de una cadena Cada paso en la cadena de autenticación contiene tres piezas de información: un `tipo`, una `carga útil` y una correspondiente `firma`. | Campo | Valor | | ------------ | ------------------------------------------------------------------------------------ | | `tipo` | El nombre de un tipo ([véase abajo](#types)). | | `carga útil` | Una cadena dependiente del tipo. | | `firma` | La firma de Ethereum codificada en hexadecimal de `carga útil`, comenzando con `0x`. | {% hint style="info" %} Dado que la serialización más común de una cadena de autenticación es un arreglo JSON, los ejemplos a continuación se presentan en esa forma. Consulte [Transmisión de una cadena](#transmitting) para más detalles. {% endhint %} ### Primer paso: Identificación El primer paso, que identifica a la autoridad original (es decir, al usuario), debe cumplir estas condiciones: 1. El `tipo` está [`SIGNER`](#SIGNER) 2. El `carga útil` es la cuenta de Ethereum codificada. 3. El `firma` está vacío. Por ejemplo: ```json // Primer paso en cualquier cadena de autenticación: { "type": "SIGNER", "payload": "0xdB055877e6c13b6A6B25aBcAA29B393777dD0a73", "signature": "" } ``` El segundo paso debe llevar una `firma` de esta cuenta para su `carga útil`. ### Pasos intermedios: Delegación Cuando los delegados actúan en nombre del usuario, se añade un elemento en medio de la cadena por cada uno de ellos. Las condiciones para estos pasos son: 1. El tipo es [`ECDSA_EPHEMERAL`](#ECDSA_EPHEMERAL) 2. El `carga útil` es un texto especialmente elaborado (véase abajo). El `carga útil` está diseñado para ser fácil de leer y fácil de analizar, ya que tanto los humanos (al usar la UI de su wallet) como los programas (al crearlo y validarlo) deben trabajar con él. Contiene exactamente 3 líneas de texto plano sensible a mayúsculas y minúsculas: ```md Dirección efímera: Expiración: ``` Por ejemplo, este es un payload típico usado por World Explorers durante el inicio de sesión, cuando generan su clave temporal de delegado para que el usuario la apruebe: ``` Inicio de sesión en Decentraland Dirección efímera: 0xBB9aDF0183b1742196A4Aa55622D5838f4f483a7 Expiración: 2023-02-25T13:00:19.730Z ``` Tenga en cuenta lo siguiente: 1. El `Dirección efímera` no necesita ser una cuenta real de Ethereum con fondos en la blockchain. El campo puede representar solo una clave pública temporal. 2. El `Expiración` es una fecha y hora serializada en [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) formato. No necesita ser UTC. 3. La clave del delegado debe renovarse periódicamente con una firma nueva del usuario, debido a esta fecha de expiración. {% hint style="info" %} Es una práctica estándar (y muy recomendada) generar una nueva clave en cada renovación (de ahí el nombre `ECDSA_EPHEMERAL`). {% endhint %} Un ejemplo de paso de delegación (valores abreviados para mayor claridad): ```json { "type": "ECDSA_EPHEMERAL", "payload": "Inicio de sesión en Decentraland\nDirección efímera: 0xBBa7...\nExpiración: 2021-01-25T...", "signature": "0x1370a4120a7cb0d2f6e4a5..." } ``` El siguiente paso, ya sea otra delegación o la autorización final, lleva una firma de la clave de este delegado. ### Paso final: Autorización Después de que el `SIGNER` se haya especificado y todas las `ECDSA_EPHEMERAL` claves de delegado hayan sido validadas verificando la cadena de firmas intermedias, el paso final es la acción real que necesita ser autorizada. El `carga útil` depende de la `tipo` del paso. Por ejemplo, si un usuario está subiendo un nuevo perfil (o cualquier Entity que posea) a un servidor de contenido, el último elemento tendrá esta forma: ```json { // El tipo indica que `payload` es un ID de Entity (detalles en la sección de contenido): "type": "ECDSA_SIGNED_ENTITY", // El payload es la cadena de ID en bruto: "payload": "bafkreicfbg7ybpuoslkcf6x2vfnvzl5vwgqtb2pnheqiut2i4sgpblicqi", // La firma es producida por la cuenta del paso anterior (usuario o delegado): "signature": "0x7e71dbbab..." } ``` Si esta última firma también es válida, la acción puede continuar. ### Transmisión de una cadena Como se mencionó arriba, la serialización más común de una cadena de autenticación es un arreglo JSON. Este es el enfoque recomendado. Sin embargo, el protocolo no impone esto. Se permite a los desarrolladores usar una estrategia de serialización alternativa si resulta más conveniente para un caso de uso particular, como YAML, archivos CSV, formatos binarios optimizados o cadenas simples con campos delimitados. Un ejemplo de serialización alternativa dentro del propio protocolo puede encontrarse en el [`SignedFetch`](https://github.com/decentraland/docs/tree/main/runtime/modules/signed_fetch.md) módulo, que utiliza una secuencia de encabezados HTTP en lugar de un arreglo JSON. ### Elección de una fecha de expiración Al seleccionar la duración válida para una clave de delegado, hay un equilibrio: expiraciones más cortas aumentan la seguridad, pero expiraciones más largas mejoran la experiencia del usuario (ya que los delegados deben renovarse con interacción humana con menor frecuencia). No existe una estrategia universal para decidir cuál debe ser la ventana de tiempo válida. El World Explorer de la Foundation, como referencia, solicita autorización para su clave de delegado por un mes. {% hint style="info" %} Las claves efímeras nunca deben contener fondos ni tener la capacidad de transferir activos digitales. Es mucho más seguro para los usuarios finales si la filtración de una clave efímera no puede resultar en pérdidas financieras. {% endhint %} ## Formalización A continuación se presenta una definición más formal y precisa de los procesos involucrados. Siga estas instrucciones para manejar correctamente las cadenas de autenticación. ### Creación Los clientes que crean una cadena de autenticación para el usuario siguen estos pasos: 1. Añada el paso de identificación: 1. Establezca el `tipo` en `SIGNER`. 2. Establezca el `carga útil` a la dirección de Ethereum del usuario. 3. Establezca el `firma` a una cadena vacía. 2. Añada pasos de delegación: 1. Genere o use una clave privada de delegado existente (puede requerir interacción). 2. Calcule la dirección de Ethereum del delegado derivada de la clave pública correspondiente. 3. Establezca el `tipo` en `ECDSA_EPHEMERAL`. 4. Establezca el `expiración` a una fecha en el futuro. 5. Elija un `propósito` para esta clave. 6. Establezca el `carga útil` a esta forma exacta: ```md Dirección efímera: Expiración: ``` 7. Establezca el `firma` campo a la `carga útil` firma de la clave anterior (usuario o delegado). 8. Repita para todos los delegados sucesivos. 3. Añada el paso de autorización de la acción: 1. Establezca el `tipo` a un valor válido ([véase abajo](#types)) 2. Establezca el `carga útil` al valor específico del tipo (como el ID de la entidad). 3. Establezca el `firma` campo a la `carga útil` firma de la clave anterior (usuario o delegado). 4. Envíe la cadena de autenticación al verificador. ### Verificación Los servidores de contenido y los servicios de terceros que implementan la verificación siguen estos pasos: 1. Verifique la identificación: 1. Verifica que el `tipo` está `SIGNER`. 2. Verifica que el `carga útil` es la dirección de Ethereum del usuario. 3. Verifica que el `firma` es una cadena vacía. 2. Verifique los delegados: 1. Verifica que el `tipo` está `ECDSA_EPHEMERAL`. 2. Verifica que el `carga útil` está en esta forma y extraiga los campos: ```md Dirección efímera: Expiración: ``` 3. Verifica que el `fecha` sigue estando en el futuro. 4. Verifica que el `propósito` es compatible con su servicio. 5. Verifica que el `firma` es válido para la fecha dada `carga útil` y la clave pública anterior. 6. Repita para todos los delegados sucesivos. 3. Verifique la autorización de la acción: 1. Verifica que el `tipo` es un valor válido ([véase abajo](#types)). 2. Verifica que el `carga útil` es válido para esta `tipo`. 3. Verifica que el `firma` es válido para la fecha dada `carga útil` y la clave pública anterior. 4. Acepte la cadena de autenticación. ### Tipos y finalidades de acción estándar El `tipo` y `carga útil` Los valores para identificación y delegación son estándar y deben verificarse como se indica arriba, pero los clientes y servicios pueden acordar cualquier acción `tipo`, y su `carga útil` estructura, así como establecer una `propósito` para sus claves de delegado que consideren válida. El protocolo define tres tipos estándar y una finalidad estándar: **Tipo `SIGNER`** **Debe** ser el `tipo` inicial en la cadena, donde `carga útil` es la dirección de Ethereum del usuario y `firma` es una cadena vacía. **Tipo `ECDSA_EPHEMERAL`** **Debe** ser la `tipo` para los pasos intermedios en la cadena, donde `carga útil` está en la forma descrita arriba. **Tipo `ECDSA_SIGNED_ENTITY`** El `tipo` elemento final en la cadena para autorizar despliegues de Entity, donde `carga útil` es el ID de un Entity que pertenece al usuario. **Propósito `Inicio de sesión en Decentraland`** La forma habitual `propósito` para World Explorers, firmado tanto al iniciar sesión en el mundo como al renovar su clave 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-es/autenticacion/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.