Login com Atmosphere

O pacote @emdash-cms/auth-atproto adiciona ao EmDash uma opção de login com conta Atmosphere. Uma conta Atmosphere é uma identidade portátil e de propriedade do utilizador, usada no Bluesky e noutras apps da rede AT Protocol. Os utilizadores iniciam sessão com o seu handle (por exemplo alice.bsky.social) e autenticam-se no próprio fornecedor — o EmDash nunca vê uma palavra-passe.

Faz sentido quando:

• Os seus contribuidores já têm conta Atmosphere.
• Quer restringir um domínio controlado pela organização (*.suaempresa.com) sem gerir apps OAuth ou convites.
• Está a construir algo integrado no ecossistema Atmosphere e quer identidade consistente com o resto do stack.

Instalação

pnpm add @emdash-cms/auth-atproto

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", // obrigatório em desenvolvimento local — ver «Desenvolvimento local» abaixo
			},
		}),
	],
});

Isto basta para mostrar Entrar com Atmosphere na página de login e no assistente de configuração. Sem lista de permissões, o primeiro utilizador torna-se administrador e o registo aberto fecha para os restantes — veja listas de permissões para reabrir.

Não são necessárias variáveis de ambiente, segredo de cliente nem registo de app OAuth. O fornecedor é um cliente OAuth público e serve o próprio documento de metadados em /.well-known/atproto-client-metadata.json.

Configuração

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

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

Listas de permissões

Se nem allowedDIDs nem allowedHandles estiverem definidos, apenas o primeiro utilizador pode registar-se — qualquer outra tentativa de login é rejeitada com signup_not_allowed. Utilizadores existentes podem sempre voltar a entrar independentemente da lista (por isso retirar-se da lista não o bloqueia, mas também não deixa entrar pessoas novas).

Quando existe pelo menos uma lista, um utilizador é admitido se qualquer uma corresponder:

• Correspondência por DID. O DID do utilizador está em allowedDIDs. Os DIDs são identificadores criptográficos que não podem ser movidos nem falsificados — a forma mais estrita de controlo de acesso.
• Correspondência por handle. O handle corresponde a uma entrada em allowedHandles, exata ou por padrão wildcard inicial (*.example.com corresponde a alice.example.com e bob.team.example.com).

Listas por handle são seguras mesmo sendo os handles mutáveis. Antes de admitir por handle, o EmDash resolve independentemente o registo DNS/HTTP do handle e verifica que aponta para o mesmo DID que o fornecedor declara. Um fornecedor mal intencionado não pode simplesmente afirmar que detém [email protected].

Papel predefinido

Utilizadores permitidos recebem o papel definido em defaultRole. Apenas o primeiro utilizador — quem conclui a configuração — é obrigatório a Admin. Não há mapeamento de grupos ou papéis para contas Atmosphere; para papéis mais finos, altere o papel em Definições → Utilizadores depois de iniciarem sessão uma vez.

Configuração do primeiro utilizador

Ao iniciar um site novo com o fornecedor Atmosphere configurado, o assistente oferece-o como opção para criar a conta de administrador inicial.

O mesmo fluxo repete-se em cada login seguinte — handle, redirecionamento ao fornecedor, regresso, sessão iniciada.

Desenvolvimento local

O perfil OAuth do AT Protocol exige que os URIs de redirecionamento em 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, pelo que a sessão de desenvolvimento também deve começar 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 para 127.0.0.1.

O servidor de desenvolvimento do Astro é o do Vite, e o Vite escuta em localhost por predefinição. Configure-o para escutar também no 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

Nada extra é necessário em produção. O fornecedor serve os metadados do cliente em:

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

Servidores de autorização obtêm este URL durante o processo de login para verificar o URI de redirecionamento do cliente. Garanta que o URL público do deployment é acessível na Internet por HTTPS — deployments apenas internos atrás de VPN não conseguem concluir o login porque o servidor de autorização do utilizador não consegue obter o documento de metadados.

Se o EmDash estiver atrás de um proxy reverso que termina TLS, defina siteUrl para o EmDash construir o URI de redirecionamento correto. Sem isso, os pedidos parecem http://internal-host:4321 e os metadados não coincidem com o que o servidor de autenticação vê.

Resolução de problemas

«Account is not in the allowlist»

O handle ou DID com que entrou não está em allowedDIDs / allowedHandles. Verifique o padrão wildcard (deve começar por *.) e lembre-se de que a correspondência por handle é validada contra DNS/HTTP — se o registo DID do handle não resolver atualmente para o mesmo DID que o fornecedor devolveu, a correspondência é rejeitada.

«Self-signup is not allowed»

Atingiu o callback com sucesso mas não há lista de permissões e não é o primeiro utilizador. Adicione-se a allowedDIDs/allowedHandles ou peça a um administrador existente que o convide para o utilizador já existir ao iniciar sessão.

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

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

Falha na resolução do handle com handle autoalojado

O fornecedor verifica handles competindo entre DNS-over-HTTPS (endpoint DoH da Cloudflare) e um pedido HTTP a /.well-known/atproto-did. Handles autoalojados precisam de pelo menos um dos seguintes:

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

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