Saltar al contenido principal

Autenticación Stellar para Cuentas de Contrato (SEP-45)

Descripción general​

SEP-45 (Autenticación Web Stellar para Cuentas de Contrato) permite a las aplicaciones de billeteras inteligentes crear sesiones autenticadas con anclas Stellar demostrando control sobre una cuenta de contrato (C...). Una vez autenticadas, las billeteras reciben un Token Web JSON (JWT) que utilizan en solicitudes posteriores a los servicios estandarizados del ancla.

Para la especificación completa, consulta SEP-0045: Autenticación Web Stellar para Cuentas de Contrato.

La Plataforma Anchor implementa SEP-45 con soporte para:

  • Flujo Desafío/Respuesta: GET /sep45/auth para solicitar entradas de autorización, POST /sep45/auth para validar y recibir un JWT
  • Autenticación de Cuenta de Contrato: Soporte para cuentas de contrato (C...) usando entradas de autorización Soroban
  • Simulación de Transacciones: Simulación automática de transacciones para verificar entradas de autorización
  • Múltiples Dominios Principales: Soporte para múltiples dominios y patrones comodín
información

SEP-45 vs SEP-10: SEP-45 no reemplaza a SEP-10. SEP-45 soporta cuentas de contrato (C...), mientras que SEP-10 soporta cuentas clásicas (G...) y cuentas multiplexadas (M...). Los servicios que deseen soportar todos los tipos de cuentas deben implementar ambos SEPs.

Flujo Típico de Autenticación​

  1. El Cliente solicita un desafío único al Servidor
  2. El Cliente verifica y firma el desafío
  3. El Cliente envía el desafío firmado al Servidor
  4. El Servidor verifica el desafío y responde con un token de sesión JWT

Se proporciona una implementación del contrato SEP-45 en el repositorio Platform Anchor. Una instancia de este contrato está desplegada en CD3LA6RKF5D2FN2R2L57MWXLBRSEWWENE74YBEFZSSGNJRJGICFGQXMX en testnet.

Activar SEP-45​

SEP-45 requiere integración con Stellar RPC para simular transacciones. La Plataforma Anchor puede conectarse al servidor Stellar RPC de tu elección. Puedes usar un proveedor público de Stellar RPC, o ejecutar el tuyo propio. Una lista de proveedores públicos se encuentra aquí.

Para activar SEP-45, configura las siguientes variables de entorno en tu archivo dev.env.

# dev.env
STELLAR_NETWORK_TYPE=rpc
STELLAR_NETWORK_RPC_URL=https://soroban-testnet.stellar.org
SEP45_ENABLED=true
SEP45_HOME_DOMAINS=localhost:8080
SEP45_WEB_AUTH_CONTRACT_ID="CD3LA6RKF5D2FN2R2L57MWXLBRSEWWENE74YBEFZSSGNJRJGICFGQXMX"
SECRET_SEP10_SIGNING_SEED="a Stellar private key"
SECRET_SEP45_JWT_SECRET="a secret encryption key"

Configuración requerida (si está habilitado)​

VariablePor defectoDescripción
STELLAR_NETWORK_TYPERequeridoDebe establecerse en rpc para SEP-45. Esto habilita el modo RPC para la Plataforma Anchor.
STELLAR_NETWORK_RPC_URLRequeridoLa URL del servidor Stellar RPC utilizado para simular transacciones. Puedes usar un proveedor público o ejecutar el tuyo propio. Una lista de proveedores públicos se encuentra aquí.
SEP45_ENABLEDfalseEstablece en true para habilitar la autenticación SEP-45
SEP45_HOME_DOMAINSRequeridoLista de dominios principales (separados por comas). Soporta patrones comodín como *.stellar.org. El home_domain debe coincidir con el host donde se sirve tu archivo stellar.toml.
SEP45_WEB_AUTH_CONTRACT_IDRequeridoEl ID del contrato del contrato SEP-45. Este contrato debe implementar la función web_auth_verify como se describe en la especificación SEP-45.
SECRET_SEP10_SIGNING_SEEDRequeridoLa clave privada correspondiente a la SIGNING_KEY en tu archivo stellar.toml. SEP-45 usa la misma clave de firma que SEP-10. Usada para firmar desafíos de autenticación.
SECRET_SEP45_JWT_SECRETRequeridoLa clave de cifrado usada para firmar y verificar los tokens JWT emitidos a las billeteras autenticadas.
important
  • Requisito RPC: SEP-45 requiere Stellar RPC para simular transacciones. Debes establecer STELLAR_NETWORK_TYPE=rpc y proporcionar una STELLAR_NETWORK_RPC_URL válida.
  • ID del Contrato: El SEP45_WEB_AUTH_CONTRACT_ID debe coincidir con el contrato desplegado en la dirección especificada en el campo WEB_AUTH_CONTRACT_ID de tu archivo stellar.toml.
  • Clave de Firma: La SIGNING_KEY en tu archivo stellar.toml debe ser la clave pública derivada de SECRET_SEP10_SIGNING_SEED.

Configuración Opcional​

# dev.env
# Optional: Specify web_auth_domain (default: first home_domain if only one is specified)
SEP45_WEB_AUTH_DOMAIN=localhost:8080

# Optional: Challenge timeout in seconds (default: 900)
SEP45_AUTH_TIMEOUT=900

# Optional: JWT token timeout in seconds (default: 86400 = 24 hours)
SEP45_JWT_TIMEOUT=86400
VariablePor defectoDescripción
SEP45_WEB_AUTH_DOMAINPrimer home_domain si solo se especifica uno, de lo contrario vacíoLa propiedad web_auth_domain usada en las respuestas de SEP-45. Requerido si tienes múltiples home_domains o usas patrones comodín. Debe coincidir con el host del servidor SEP.
SEP45_AUTH_TIMEOUT900Tiempo en segundos que un desafío permanece válido. Los clientes deben firmar y enviar las entradas de autorización dentro de esta ventana.
SEP45_JWT_TIMEOUT86400Tiempo en segundos que un token JWT emitido permanece válido. Después de la expiración, los clientes deben reautenticarse.
consejo

Múltiples Dominios Principales: Si especificas múltiples home_domains (ej., ap.stellar.org,*.sdp.stellar.org), también debes establecer SEP45_WEB_AUTH_DOMAIN para especificar qué dominio aloja el endpoint de autenticación.

Configurar stellar.toml​

Actualiza tu archivo stellar.toml para publicitar soporte para SEP-45. Las billeteras descubren tu endpoint de autenticación a través de este archivo.

# dev.stellar.toml

ACCOUNTS = ["add your public keys for your distribution accounts here"]
SIGNING_KEY = "add your signing key here (public key from SECRET_SEP10_SIGNING_SEED)"
WEB_AUTH_FOR_CONTRACTS_ENDPOINT = "http://localhost:8080/sep45/auth"
WEB_AUTH_CONTRACT_ID = "CD3LA6RKF5D2FN2R2L57MWXLBRSEWWENE74YBEFZSSGNJRJGICFGQXMX"

Estos campos deben coincidir con las opciones de configuración establecidas en la sección Activar SEP-45 arriba.

WEB_AUTH_FOR_CONTRACTS_ENDPOINT - La URL donde se ejecuta el servicio de autenticación. Esta es la URL que los clientes usarán para autenticarse con el ancla. El endpoint debe soportar:

  • GET <WEB_AUTH_FOR_CONTRACTS_ENDPOINT> - Solicitar entradas de autorización
  • POST <WEB_AUTH_FOR_CONTRACTS_ENDPOINT> - Intercambiar entradas de autorización firmadas por un JWT de sesión

WEB_AUTH_CONTRACT_ID - El ID del contrato del contrato SEP-45. Este es el contrato que se usará para construir el desafío. El contrato debe implementar la función web_auth_verify como se describe en la especificación SEP-45. Esto debe coincidir con SEP45_WEB_AUTH_CONTRACT_ID.

important
  • SIGNING_KEY: Debe ser la clave pública derivada de SECRET_SEP10_SIGNING_SEED
  • WEB_AUTH_FOR_CONTRACTS_ENDPOINT: Usa https:// en producción. El path /sep45/auth es el endpoint estándar SEP-45.
  • Coincidencia de Host: El host en WEB_AUTH_FOR_CONTRACTS_ENDPOINT debe coincidir con uno de tus SEP45_HOME_DOMAINS (o el SEP45_WEB_AUTH_DOMAIN si se especifica).