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 una cuenta Atmosphere. Una cuenta Atmosphere es una identidad portable, propiedad del usuario, que se usa en Bluesky y en otras apps 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.

Es una buena opción cuando:

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

Instalar

Instala el paquete del proveedor:

pnpm add @emdash-cms/auth-atproto

Añade 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({
	server: {
		host: "127.0.0.1", // required for local development; see below
	},
	integrations: [
		emdash({
			authProviders: [atproto()],
		}),
	],
});

Con eso basta para mostrar Sign in with Atmosphere en la página de inicio de sesión y en el asistente de configuración. Si no se configura ninguna lista de permitidos, el primer usuario se convierte en Admin y el registro propio se cierra para todos los demás — consulta las 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, así que funciona solo con la configuración anterior — no hay variables de entorno, secreto de cliente ni registro de una app de OAuth que configurar.

Configurar acceso

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
});

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

Listas de permitidos

Si no se define ni allowedDIDs ni allowedHandles, solo el primer usuario puede registrarse. Las cuentas que ya están vinculadas a un usuario de EmDash pueden seguir iniciando sesión, mientras que una cuenta nueva se rechaza con signup_not_allowed.

Cuando se configura al menos una lista de permitidos, cada inicio de sesión debe coincidir con ella, incluidos los de usuarios existentes. Si eliminas el DID y el handle de un usuario existente de las listas configuradas, esa cuenta deja de poder iniciar sesión. Un usuario es admitido si coincide cualquiera de las dos listas:

• Coincidencia de DID. El identificador de cuenta estable del usuario coincide exactamente con un valor de allowedDIDs.
• Coincidencia de handle. El handle del usuario coincide con una entrada de allowedHandles, de forma 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 de permitidos de handles son seguras aunque los handles sean mutables. Antes de admitir a un usuario por una coincidencia de handle, EmDash resuelve de forma independiente el registro DNS/HTTP del handle y verifica que apunte al mismo DID que afirma el proveedor. Un proveedor que se comporte mal no puede limitarse a afirmar que es dueño de you.yourcompany.com.

Rol por defecto

Los usuarios permitidos reciben el rol que establezcas en defaultRole. Solo el primer usuario — el que completa la configuración — queda forzado como Admin. No hay asignación de grupos ni roles para las cuentas Atmosphere; si necesitas roles más granulares, cambia el rol del usuario en la página Users de la barra lateral del administrador después de que haya iniciado sesión una vez.

Configurar el primer usuario

Cuando inicias 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.

Los inicios de sesión posteriores empiezan con el handle, continúan en el proveedor de la cuenta y regresan con una sesión de EmDash. El estado de OAuth y los tokens del proveedor se almacenan por separado de esa sesión de EmDash, de modo que el callback de OAuth pueda completarse y el proveedor pueda renovar su propia sesión.

Desarrollo local

El perfil OAuth de AT Protocol exige que los URI de redirección de 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 el URI de redirección, pero eso significa que tu sesión de desarrollo también debe empezar 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 usa Vite, que de forma predeterminada se enlaza a localhost. Establece la opción server.host de nivel superior de Astro con la IP de loopback:

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

Después 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 el URI de redirección del cliente. Asegúrate de que la URL del sitio de tu despliegue sea accesible desde internet público mediante HTTPS — los despliegues solo internos 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 el URI de redirección correcto. Sin esto, las solicitudes parecen http://internal-host:4321 y los metadatos no coincidirán con lo que ve el servidor de autorización.

Solución de problemas

”Account is not in the allowlist”

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

”Self-signup is not allowed”

Llegaste correctamente al callback, pero no hay ninguna lista de permitidos configurada y no eres el primer usuario. Añade el DID de la cuenta a allowedDIDs o su handle verificado a allowedHandles. Una invitación por correo electrónico no vincula un DID de Atmosphere con un usuario de EmDash.

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

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

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

El proveedor verifica los handles haciendo competir DNS-over-HTTPS (el endpoint DoH de Cloudflare) y una consulta HTTP a /.well-known/atproto-did. Los handles auto-hospedados necesitan al menos uno de estos:

• Un registro TXT de DNS _atproto.<handle> que contenga did=<your-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 aunque la cuenta subyacente sea válida. Los DID de allowedDIDs no se ven afectados — se comparan directamente.