Atmosphere Login

O pacote @emdash-cms/auth-atproto adiciona uma opção de login com conta Atmosphere ao EmDash. Uma conta Atmosphere é uma identidade portátil de propriedade do usuário usada no Bluesky e outros aplicativos na rede do protocolo AT. 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 é uma boa opção quando:

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

Instalação

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

Isso é suficiente para exibir Entrar com Atmosphere na página de login e no assistente de configuração. Sem uma lista de permissões configurada, o primeiro usuário se torna Admin e o auto-cadastro é fechado para todos os outros — veja listas de permissões para abri-lo.

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, segredo do cliente ou registro de aplicativo OAuth para configurar.

Configuração

O provedor atproto() aceita uma lista de permissões e uma função padrão:

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

A escala completa de funções está documentada no guia de autenticação principal.

Listas de permissões

Se nem allowedDIDs nem allowedHandles estiverem definidos, apenas o primeiro usuário pode se cadastrar — qualquer outra pessoa que tentar fazer login será rejeitada com signup_not_allowed. Usuários existentes sempre podem fazer login novamente, independentemente da lista de permissões (então remover-se da lista não irá bloquear você, mas também não permitirá que novas pessoas entrem).

Quando pelo menos uma lista de permissões está configurada, um usuário é admitido se qualquer uma das listas corresponder:

• Correspondência de DID. O DID do usuário está em allowedDIDs. DIDs são identificadores criptográficos que não podem ser movidos ou representados, então esta é a forma mais estrita de controle de acesso.
• Correspondência de handle. O handle do usuário corresponde a uma entrada em allowedHandles, exatamente ou através de um padrão de curinga inicial (*.example.com corresponde a alice.example.com e bob.team.example.com).

Listas de permissões de handles são seguras mesmo que handles sejam mutáveis. Antes de admitir um usuário através de uma correspondência de handle, o EmDash resolve independentemente o registro DNS/HTTP do handle e verifica se aponta para o mesmo DID que o provedor afirma. Um provedor mal-intencionado não pode simplesmente afirmar que possui voce@suaempresa.com.

Função padrão

Usuários permitidos caem na função que você define em defaultRole. Apenas o primeiro usuário — aquele que completa a configuração — é forçado a Admin. Não há mapeamento de grupo/função para contas Atmosphere; se você precisar de funções mais granulares, altere a função do usuário em Configurações → Usuários depois que eles fizerem login uma vez.

Configuração do primeiro usuário

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

O mesmo fluxo é executado para cada login subsequente: insira seu handle, autentique no seu provedor e retorne ao EmDash logado.

Desenvolvimento local

O perfil OAuth do protocolo AT requer que URIs de redirecionamento de loopback usem um literal de IP (127.0.0.1 ou [::1]), não localhost. O EmDash reescreve transparentemente ://localhost para ://127.0.0.1 ao gerar a URI de redirecionamento, mas isso significa que sua sessão de desenvolvimento também precisa iniciar em 127.0.0.1 — 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 é o servidor de desenvolvimento do Vite, e o Vite se liga a localhost por padrão. Diga a ele para ouvir no IP de loopback também:

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

Em seguida, 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 seus próprios metadados de cliente em:

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

Servidores de autorização buscam esta URL durante o login para verificar a URI de redirecionamento do cliente. Certifique-se de que a URL do site da sua implantação esteja acessível na internet pública via HTTPS — implantações apenas internas atrás de uma VPN não poderão completar um login porque o servidor de autorização do usuário não pode buscar o documento de metadados.

Se você executar o EmDash atrás de um proxy reverso de terminação TLS, defina siteUrl para que o EmDash construa a URI de redirecionamento correta. Sem isso, as solicitações parecem com http://internal-host: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 de 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 resolver atualmente para o mesmo DID que o provedor retornou, a correspondência é rejeitada.

”Self-signup is not allowed”

Você atingiu o callback com sucesso, mas nenhuma lista de permissões está configurada e você não é o primeiro usuário. Adicione-se a allowedDIDs/allowedHandles, ou peça a um administrador existente que o convide para que o usuário já exista quando você fizer login.

O login redireciona para a página de login sem erro

Isso é quase sempre o problema do cookie de 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.

A resolução de handle falha para um handle auto-hospedado

O provedor verifica handles competindo entre DNS-over-HTTPS (endpoint DoH da Cloudflare) e uma busca 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 — eles são correspondidos diretamente.