Inicio de sesión con Atmosphere

El paquete @emdash-cms/auth-atproto añade a EmDash una opción de inicio de sesión con cuenta de Atmosphere. Una cuenta de Atmosphere es una identidad portable y propiedad del usuario que se usa en Bluesky y otras aplicaciones de la red AT Protocol. Los usuarios inician sesión con su handle (p. ej. alice.bsky.social) y se autentican en su propio proveedor — EmDash nunca ve una contraseña.

Encaja bien cuando:

Tus colaboradores ya tienen una cuenta de Atmosphere.
Quieres restringir un dominio controlado por la organización (*.tuempresa.com) sin gestionar aplicaciones OAuth ni invitaciones.
Estás construyendo algo que forma parte del ecosistema Atmosphere y quieres una identidad coherente con el resto de tu stack.

Instalación

pnpm add @emdash-cms/auth-atproto

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { atproto } from "@emdash-cms/auth-atproto";

export default defineConfig({
	integrations: [
		emdash({
			authProviders: [atproto()],
			server: {
				host: "127.0.0.1", // obligatorio en desarrollo local — véase «Desarrollo local» más abajo
			},
		}),
	],
});

Con eso aparece Iniciar sesión con Atmosphere en la página de login y en el asistente de configuración. Sin lista de permitidos configurada, el primer usuario pasa a ser administrador y el registro abierto se cierra para el resto — consulta listas de permitidos para abrirlo.

No hace falta variables de entorno, secreto de cliente ni registro de aplicación OAuth. El proveedor es un cliente OAuth público y sirve su propio documento de metadatos en /.well-known/atproto-client-metadata.json.

Configuración

atproto({
	allowedDIDs: ["did:plc:abc123..."],
	allowedHandles: ["*.example.com", "alice.bsky.social"],
	defaultRole: 30, // Autor
});

Opción	Tipo	Valor predeterminado	Descripción
`allowedDIDs`	`string[]`	ninguno (todos en el primero)	Lista de permitidos por DID. Los DIDs son permanentes y no se pueden falsificar.
`allowedHandles`	`string[]`	ninguno (todos en el primero)	Lista de permitidos por handle. Admite comodines (`*.example.com`).
`defaultRole`	`number`	`10` (Suscriptor)	Rol asignado a usuarios permitidos después del primero. El primero siempre es Admin.

La escalera completa de roles está documentada en la guía principal de autenticación.

Listas de permitidos

Si no se configuran ni allowedDIDs ni allowedHandles, solo el primer usuario puede registrarse — cualquier otro intento de inicio de sesión se rechaza con signup_not_allowed. Los usuarios existentes siempre pueden volver a entrar con independencia de la lista (así que quitarte de la lista no te bloquea, pero tampoco deja entrar a gente nueva).

Cuando hay al menos una lista configurada, se admite a un usuario si coincide con cualquiera de las dos:

Coincidencia por DID. El DID del usuario está en allowedDIDs. Los DIDs son identificadores criptográficos que no se pueden mover ni suplantar; es la forma más estricta de filtrado.
Coincidencia por handle. El handle del usuario coincide con una entrada de allowedHandles, exacta o mediante un patrón con comodín al inicio (*.example.com coincide con alice.example.com y bob.team.example.com).

Las listas por handle son seguras aunque los handles cambien. Antes de admitir por handle, EmDash resuelve de forma independiente el registro DNS/HTTP del handle y comprueba que apunta al mismo DID que declara el proveedor. Un proveedor malintencionado no puede afirmar por arte de magia que posee [email protected].

Rol predeterminado

Los usuarios permitidos reciben el rol que definas en defaultRole. Solo el primer usuario — quien completa la configuración — queda obligado a ser Admin. No hay mapeo de grupos o roles para cuentas Atmosphere; si necesitas roles más finos, cambia el rol del usuario en Ajustes → Usuarios después de que haya iniciado sesión al menos una vez.

Configuración del primer usuario

Al iniciar un sitio nuevo con el proveedor Atmosphere configurado, el asistente de configuración lo ofrece como opción para crear la cuenta de administrador inicial.

Visita /_emdash/admin. El asistente te guía por el título del sitio, el eslogan y el correo del administrador.
En el paso «Crear cuenta de administrador», elige Atmosphere e introduce tu handle (p. ej. alice.bsky.social).
Serás redirigido a la página de autorización de tu cuenta, donde iniciarás sesión como permita tu proveedor — contraseña, passkey u otro método.
Tras aprobar, volverás a EmDash; se crea el usuario administrador con rol 50 (Admin) y el correo del paso 1 queda guardado en tu cuenta.

El mismo flujo se repite en cada inicio de sesión posterior: handle, redirección al proveedor, vuelta, sesión iniciada.

Desarrollo local

El perfil OAuth del AT Protocol exige que las URI de redirección en loopback usen un literal IP (127.0.0.1 o [::1]), no localhost. EmDash reescribe de forma transparente ://localhost a ://127.0.0.1 al generar la URI de redirección, pero eso implica que tu sesión de desarrollo también debe empezar en 127.0.0.1; si no, la cookie de sesión establecida en localhost no será visible cuando la redirección te lleve a 127.0.0.1.

El servidor de desarrollo de Astro es el de Vite, y Vite escucha en localhost por defecto. Indícale que también escuche en la IP de loopback:

export default defineConfig({
	server: {
		host: "127.0.0.1",
	},
	// ...
});

Luego abre http://127.0.0.1:4321/_emdash/admin para todo el flujo.

Producción

No hay nada extra que configurar en producción. El proveedor sirve sus metadatos de cliente en:

https://tu-sitio.example.com/.well-known/atproto-client-metadata.json

Los servidores de autorización obtienen esta URL durante el proceso de login para verificar la URI de redirección del cliente. Asegúrate de que la URL pública del despliegue sea accesible por Internet con HTTPS — los despliegues solo internos detrás de una VPN no podrán completar el inicio de sesión porque el servidor de autorización del usuario no podrá obtener el documento de metadatos.

Si EmDash está detrás de un proxy inverso que termina TLS, configura siteUrl para que EmDash construya la URI de redirección correcta. Sin ello, las peticiones parecen http://internal-host:4321 y los metadatos no coincidirán con lo que ve el servidor de autenticación.

Solución de problemas

«Account is not in the allowlist»

El handle o DID con el que entraste no está en allowedDIDs / allowedHandles. Revisa el patrón con comodín (debe empezar por *.) y recuerda que la coincidencia por handle se verifica contra DNS/HTTP: si el registro DID del handle no resuelve actualmente al mismo DID que devolvió el proveedor, se rechaza la coincidencia.

Llegaste al callback correctamente pero no hay lista de permitidos y no eres el primer usuario. Añádete a allowedDIDs/allowedHandles o pide a un admin existente que te invite para que el usuario ya exista al iniciar sesión.

Casi siempre es el problema de cookie en loopback descrito en Desarrollo local. Abre el admin en http://127.0.0.1:4321 (tras poner server.host: "127.0.0.1") e inténtalo de nuevo.

Falla la resolución del handle con handle autohospedado

El proveedor verifica los handles compitiendo entre DNS sobre HTTPS (punto de acceso DoH de Cloudflare) y una petición HTTP a /.well-known/atproto-did. Los handles autohospedados necesitan al menos uno de los siguientes:

Un registro TXT DNS _atproto.<handle> con did=<tu-did>, o
Un archivo https://<handle>/.well-known/atproto-did que contenga el DID.

Si ambos métodos fallan, se rechaza la coincidencia por handle aunque la cuenta sea válida. Los DIDs en allowedDIDs no se ven afectados: se comparan directamente.