Login Atmosphere

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

Isso é adequado quando:

• Seus colaboradores já têm uma conta Atmosphere.
• Você quer controlar o acesso por um domínio controlado pela organização (*.suaempresa.com) sem gerenciar apps OAuth ou convites.
• Você está construindo algo que faz parte da Atmosphere mais ampla e quer identidade consistente com o restante do seu stack.

Instalar

Instale o pacote do provedor:

pnpm add @emdash-cms/auth-atproto

Adicione o provedor à integração 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", // necessário para desenvolvimento local; veja abaixo
	},
	integrations: [
		emdash({
			authProviders: [atproto()],
		}),
	],
});

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

O provedor é um cliente OAuth público e serve seu próprio documento de metadados em /.well-known/atproto-client-metadata.json, então funciona apenas com a configuração acima — sem variáveis de ambiente, client secret ou 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, // Autor
});

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

Listas de permissão

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

Quando pelo menos uma lista de permissão é configurada, todo login deve corresponder a ela, incluindo logins de usuários existentes. Remover o DID e o handle de um usuário existente das listas configuradas impede essa conta de fazer login. Um usuário é admitido se qualquer uma das listas corresponder:

• Correspondência de DID. O identificador estável da conta 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 via padrão curinga inicial (*.example.com corresponde a alice.example.com e bob.team.example.com).

Listas de permissão de handles são seguras mesmo que handles sejam mutáveis. Antes de admitir um usuário via correspondência de handle, o EmDash resolve independentemente o registro DNS/HTTP do handle e verifica que aponta para o mesmo DID que o provedor alega. Um provedor malicioso não pode simplesmente afirmar que possui voce.suaempresa.com.

Papel padrão

Usuários permitidos chegam com o papel definido em defaultRole. Apenas o primeiro usuário — aquele que completa a configuração — é forçado a Admin. Não há mapeamento grupo/papel para contas Atmosphere; se você precisa de papéis mais granulares, altere o papel do usuário em Configurações → Usuários após ele ter feito login uma vez.

Configurar o primeiro usuário

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

Logins posteriores começam com o handle, continuam no provedor de conta e retornam com uma sessão EmDash. O estado OAuth e os tokens do provedor são armazenados separadamente da sessão EmDash para que o callback OAuth possa ser concluído e o provedor possa atualizar sua própria sessão.

Desenvolvimento local

O perfil OAuth do AT Protocol exige que URIs de redirecionamento loopback usem um literal IP (127.0.0.1 ou [::1]), não localhost. O EmDash reescreve transparentemente ://localhost para ://127.0.0.1 ao gerar o URI de redirecionamento, mas isso significa que sua sessão de desenvolvimento precisa iniciar em 127.0.0.1 também — caso contrário, o cookie de sessão definido em localhost não será visível após o redirecionamento levá-lo para 127.0.0.1.

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

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

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

Produção

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

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

Servidores de autorização buscam esta URL durante o login para verificar o URI de redirecionamento do cliente. Certifique-se de que a URL do site do seu deployment é acessível na internet pública via HTTPS — deployments apenas internos atrás de uma VPN não poderão completar 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://host-interno:4321 e os metadados não corresponderão ao que o servidor de autenticação vê.

Solução de problemas

”Account is not in the allowlist”

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

”Self-signup is not allowed”

Você alcançou o 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 seu handle verificado a allowedHandles. Um convite por email não vincula um DID Atmosphere a um usuário EmDash.

Login redireciona para a página de login sem erro

Isso é quase sempre o problema de cookie loopback descrito em Desenvolvimento local. Abra o admin em http://127.0.0.1:4321 (após definir server.host: "127.0.0.1") e tente novamente.

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

O provedor verifica handles testando em paralelo DNS-over-HTTPS (endpoint DoH do Cloudflare) e uma consulta HTTP /.well-known/atproto-did. Handles auto-hospedados precisam de pelo menos um dos seguintes:

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

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