Atmosphere Login

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

Esto es una buena opción cuando:

Tus colaboradores ya tienen una cuenta Atmosphere.
Quieres controlar el acceso a un dominio controlado por la organización (*.tuempresa.com) sin gestionar aplicaciones OAuth o invitaciones.
Estás construyendo algo que es parte del Atmosphere más amplio y quieres una identidad consistente con el resto de tu stack.

Instalación

Instala el paquete del proveedor:

pnpm add @emdash-cms/auth-atproto

Agrega el proveedor a la integración de EmDash:

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", // required for local dev — see "Local development" below
			},
		}),
	],
});

Eso es suficiente para mostrar Iniciar sesión con Atmosphere en la página de inicio de sesión y el asistente de configuración. Sin una lista de permitidos configurada, el primer usuario se convierte en Admin y el autoregistro se cierra para todos los demás — consulta listas de permitidos para abrirlo.

El proveedor es un cliente OAuth público y sirve su propio documento de metadatos en /.well-known/atproto-client-metadata.json, por lo que funciona solo con la configuración anterior — no se necesitan variables de entorno, secreto de cliente ni registro de aplicación OAuth.

Configuración

El proveedor atproto() acepta una lista de permitidos y un rol predeterminado:

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

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

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

Listas de permitidos

Si ni allowedDIDs ni allowedHandles están configurados, solo el primer usuario puede registrarse — cualquier otra persona que intente iniciar sesión será rechazada con signup_not_allowed. Los usuarios existentes siempre pueden volver a iniciar sesión independientemente de la lista de permitidos (por lo que eliminarte de la lista no te bloqueará, pero tampoco permitirá que entren nuevas personas).

Cuando al menos una lista de permitidos está configurada, se admite a un usuario si cualquiera de las listas coincide:

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

Las listas de permitidos de handles son seguras aunque los handles son mutables. Antes de admitir a un usuario mediante una coincidencia de handle, EmDash resuelve independientemente el registro DNS/HTTP del handle y verifica que apunta al mismo DID que reclama el proveedor. Un proveedor malintencionado no puede simplemente afirmar que posee tu@tuempresa.com.

Rol predeterminado

Los usuarios permitidos aterrizan en el rol que estableces en defaultRole. Solo el primer usuario — el que completa la configuración — se ve forzado a Admin. No hay mapeo de grupo/rol para cuentas Atmosphere; si necesitas roles más detallados, cambia el rol del usuario desde Configuración → Usuarios después de que hayan iniciado sesión una vez.

Configuración del primer usuario

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

Visita /_emdash/admin. El asistente de configuración te guiará a través del título del sitio, eslogan y correo electrónico del administrador.
En el paso “Crear cuenta de administrador”, elige Atmosphere e ingresa tu handle (ej. alice.bsky.social).
Serás redirigido a la página de autorización de tu cuenta, donde inicias sesión como lo soporte tu proveedor — contraseña, passkey o lo que sea.
Después de la aprobación, serás enviado de vuelta a EmDash, se crea el usuario administrador con rol 50 (Admin), y el correo electrónico que ingresaste en el paso 1 se almacena contra tu cuenta.

El mismo flujo se ejecuta para cada inicio de sesión posterior: ingresa tu handle, autentica en tu proveedor y regresa a EmDash con la sesión iniciada.

Desarrollo local

El perfil OAuth del protocolo AT requiere que las URIs de redirección de loopback usen un literal IP (127.0.0.1 o [::1]), no localhost. EmDash reescribe transparentemente ://localhost a ://127.0.0.1 al generar la URI de redirección, pero eso significa que tu sesión de desarrollo también necesita iniciarse en 127.0.0.1 — de lo contrario, la cookie de sesión establecida en localhost no será visible después de que la redirección te lleve a 127.0.0.1.

El servidor de desarrollo de Astro es el servidor de desarrollo de Vite, y Vite se vincula a localhost por defecto. Dile que escuche también 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

La misma configuración funciona en producción. El proveedor sirve sus propios metadatos de cliente en:

https://your-site.example.com/.well-known/atproto-client-metadata.json

Los servidores de autorización obtienen esta URL durante el inicio de sesión para verificar la URI de redirección del cliente. Asegúrate de que la URL del sitio de tu implementación sea accesible en internet pública a través de HTTPS — las implementaciones solo internas detrás de una VPN no podrán completar un inicio de sesión porque el servidor de autorización del usuario no puede obtener el documento de metadatos.

Si ejecutas EmDash detrás de un proxy inverso que termina TLS, establece siteUrl para que EmDash construya la URI de redirección correcta. Sin él, las solicitudes se ven como 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 iniciaste sesión no está en allowedDIDs / allowedHandles. Verifica el patrón de comodín (debe comenzar con *.) y recuerda que la coincidencia de handle se verifica contra DNS/HTTP — si el registro DID del handle no se resuelve actualmente al mismo DID que devolvió el proveedor, la coincidencia se rechaza.

Llegaste al callback exitosamente pero no hay lista de permitidos configurada y no eres el primer usuario. O agrégate a allowedDIDs/allowedHandles, o haz que un administrador existente te invite para que el usuario ya exista cuando inicies sesión.

El inicio de sesión redirige a la página de inicio de sesión sin error

Esto es casi siempre el problema de cookie de loopback descrito en Desarrollo local. Abre el administrador en http://127.0.0.1:4321 (después de establecer server.host: "127.0.0.1") e intenta de nuevo.

La resolución de handle falla para un handle auto-hospedado

El proveedor verifica handles compitiendo entre DNS-over-HTTPS (endpoint DoH de Cloudflare) y una búsqueda HTTP /.well-known/atproto-did. Los handles auto-hospedados necesitan al menos uno de:

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

Si ambos métodos fallan, la coincidencia de handle se rechaza incluso cuando la cuenta subyacente es válida. Los DIDs en allowedDIDs no se ven afectados — se coinciden directamente.