Login Atmosphere

O pacote @emdash-cms/auth-atproto adiciona ao EmDash uma opção de login com uma conta Atmosphere. Uma conta Atmosphere é uma identidade portátil, pertencente ao usuário, usada no Bluesky e em outros apps da rede AT Protocol. Os usuários fazem login com o próprio handle (por exemplo, alice.bsky.social) e se autenticam no próprio provedor — o EmDash nunca vê uma senha.

É uma boa opção quando:

• Seus colaboradores já têm uma conta Atmosphere.
• Você quer restringir o acesso a um domínio controlado por uma organização (*.yourcompany.com) sem gerenciar apps OAuth ou convites.
• Você está construindo algo que faz parte da Atmosphere em geral e quer uma identidade consistente com o restante da sua stack.

Instalar

Instale o pacote do provedor:

pnpm add @emdash-cms/auth-atproto

Adicione o provedor à integração do 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()],
		}),
	],
});

Isso basta para exibir Sign in with Atmosphere na página de login e no assistente de configuração. Sem uma lista de permissão configurada, o primeiro usuário se torna Admin e a auto-inscrição é fechada para todos depois disso — veja as listas de permissão para abri-la.

O provedor é um cliente OAuth público e serve o próprio documento de metadados em /.well-known/atproto-client-metadata.json, de modo que funciona apenas com a configuração acima — não há variáveis de ambiente, client secret nem registro de app OAuth para configurar.

Configurar acesso

O provedor atproto() aceita uma lista de permissão e um papel padrão:

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

A escala completa de papéis está documentada no guia de autenticação principal.

Listas de permissão

Se nem allowedDIDs nem allowedHandles estiver definido, somente o primeiro usuário pode se cadastrar. Contas já vinculadas a um usuário do EmDash podem continuar fazendo login, enquanto uma conta nova é rejeitada com signup_not_allowed.

Quando pelo menos uma lista de permissão está configurada, todo login precisa corresponder a ela, inclusive os de usuários existentes. Remover o DID e o handle de um usuário existente das listas configuradas impede que essa conta faça login. Um usuário é admitido se qualquer uma das listas corresponder:

• Correspondência de DID. O identificador de conta estável do usuário corresponde exatamente a um valor em allowedDIDs.
• Correspondência de handle. O handle do usuário corresponde a uma entrada em allowedHandles, exatamente ou por um padrão com curinga no início (*.example.com corresponde a alice.example.com e bob.team.example.com).

As listas de permissão de handles são seguras, embora os handles sejam mutáveis. Antes de admitir um usuário por uma correspondência de handle, o EmDash resolve de forma independente o registro DNS/HTTP do handle e verifica se ele aponta para o mesmo DID que o provedor afirma. Um provedor que se comporte mal não pode simplesmente afirmar que é dono de you.yourcompany.com.

Papel padrão

Os usuários permitidos recebem o papel que você define em defaultRole. Somente o primeiro usuário — aquele que conclui a configuração — é forçado a Admin. Não há mapeamento de grupo/papel para contas Atmosphere; se você precisar de papéis mais granulares, altere o papel do usuário na página Users da barra lateral do administrador depois que ele fizer login uma vez.

Configurar o primeiro usuário

Quando você inicia um site novo com o provedor Atmosphere configurado, o assistente de configuração o oferece como opção para criar a conta de administrador inicial.

Os logins seguintes começam com o handle, continuam no provedor da conta e retornam com uma sessão do EmDash. O estado OAuth e os tokens do provedor são armazenados separadamente dessa sessão do EmDash, para que o callback OAuth possa ser concluído e o provedor possa renovar a própria sessão.

Desenvolvimento local

O perfil OAuth do AT Protocol exige que os URIs de redirecionamento de loopback usem um literal de IP (127.0.0.1 ou [::1]), e não localhost. O EmDash reescreve de forma transparente ://localhost para ://127.0.0.1 ao gerar o URI de redirecionamento, mas isso significa que a sua sessão de desenvolvimento também precisa começar em 127.0.0.1 — caso contrário, o cookie de sessão definido em localhost não ficará visível depois que o redirecionamento levar você para 127.0.0.1.

O servidor de desenvolvimento do Astro usa o Vite, que por padrão se vincula a localhost. Defina a opção server.host de nível superior do Astro como o IP de loopback:

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

Depois abra http://127.0.0.1:4321/_emdash/admin para todo o fluxo.

Produção

A mesma configuração funciona em produção. O provedor serve os próprios metadados do cliente em:

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

Os servidores de autorização buscam essa URL durante o login para verificar o URI de redirecionamento do cliente. Verifique se a URL do site da sua implantação está acessível na internet pública por HTTPS — implantações somente internas, atrás de uma VPN, não conseguirão concluir um login porque o servidor de autorização do usuário não consegue buscar o documento de metadados.

Se você executa o EmDash atrás de um proxy reverso que termina TLS, defina siteUrl para que o EmDash construa o URI de redirecionamento correto. Sem isso, as requisições parecem http://internal-host:4321 e os metadados não corresponderão ao que o servidor de autorização vê.

Solução de problemas

”Account is not in the allowlist”

O handle ou o DID com o qual você fez login não está em allowedDIDs / allowedHandles. Verifique o padrão do curinga (ele deve começar com *.) e lembre-se de que a correspondência de handle é verificada via DNS/HTTP — se o registro de DID do handle não resolver, neste momento, para o mesmo DID retornado pelo provedor, a correspondência é rejeitada.

”Self-signup is not allowed”

Você chegou ao callback com sucesso, mas nenhuma lista de permissão está configurada e você não é o primeiro usuário. Adicione o DID da conta a allowedDIDs ou o handle verificado dela a allowedHandles. Um convite por e-mail não vincula um DID Atmosphere a um usuário do EmDash.

Login redireciona para a página de login sem erro

Quase sempre é o problema do cookie de loopback descrito em Desenvolvimento local. Abra o admin em http://127.0.0.1:4321 (depois de definir server.host: "127.0.0.1") e tente novamente.

Resolução de handle falha para um handle auto-hospedado

O provedor verifica os handles fazendo competir o DNS-over-HTTPS (o endpoint DoH da Cloudflare) e uma consulta HTTP a /.well-known/atproto-did. Handles auto-hospedados precisam de pelo menos um dos seguintes:

• Um registro DNS TXT _atproto.<handle> contendo did=<your-did>, ou
• Um arquivo https://<handle>/.well-known/atproto-did contendo o DID.

Se os dois métodos falharem, a correspondência de handle é rejeitada mesmo quando a conta subjacente é válida. Os DIDs em allowedDIDs não são afetados — eles são comparados diretamente.