Atmosphere Login

@emdash-cms/auth-atproto 包为 EmDash 添加了 Atmosphere 账户登录选项。Atmosphere 账户是一个可移植的、用户拥有的身份，用于 Bluesky 和 AT Protocol 网络中的其他应用。用户使用他们的 handle（例如 alice.bsky.social）登录，并在自己的提供商处进行身份验证 — EmDash 永远不会看到密码。

这在以下情况下是一个好选择：

• 您的贡献者已经拥有 Atmosphere 账户。
• 您想要控制对组织控制的域（*.yourcompany.com）的访问，而无需管理 OAuth 应用或邀请。
• 您正在构建的东西是更广泛的 Atmosphere 的一部分，并且希望与堆栈的其余部分保持一致的身份。

安装

安装提供商包：

pnpm add @emdash-cms/auth-atproto

将提供商添加到 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
			},
		}),
	],
});

这足以在登录页面和设置向导上显示使用 Atmosphere 登录。如果没有配置允许列表，第一个用户将成为管理员，之后所有人的自助注册都将关闭 — 参见允许列表以开放它。

提供商是一个公共 OAuth 客户端，并在 /.well-known/atproto-client-metadata.json 提供自己的元数据文档，因此它仅使用上述配置即可工作 — 无需环境变量、客户端密钥或 OAuth 应用注册。

配置

atproto() 提供商接受允许列表和默认角色：

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

完整的角色阶梯在主要身份验证指南中记录。

允许列表

如果既没有设置 allowedDIDs 也没有设置 allowedHandles，只有第一个用户可以注册 — 任何其他尝试登录的人都将被 signup_not_allowed 拒绝。现有用户始终可以无视允许列表重新登录（因此从列表中删除自己不会锁定您，但也不会让新人进入）。

当至少配置了一个允许列表时，如果任一列表匹配，则允许用户：

• DID 匹配。 用户的 DID 在 allowedDIDs 中。DID 是不能移动或冒充的加密标识符，因此这是最严格的门控形式。
• Handle 匹配。 用户的 handle 与 allowedHandles 中的条目完全匹配或通过前导通配符模式（*.example.com 匹配 alice.example.com 和 bob.team.example.com）匹配。

Handle 允许列表是安全的，即使 handle 是可变的。在通过 handle 匹配允许用户之前，EmDash 会独立解析 handle 的 DNS/HTTP 记录，并验证它指向提供商声称的相同 DID。行为不当的提供商不能简单地声称它拥有 you@yourcompany.com。

默认角色

允许的用户落在您在 defaultRole 中设置的角色上。只有第一个用户 — 完成设置的用户 — 被强制为管理员。Atmosphere 账户没有组/角色映射；如果您需要更细粒度的角色，请在他们登录一次后从设置 → 用户更改用户的角色。

首次用户设置

当您使用配置的 Atmosphere 提供商启动新站点时，设置向导会将其作为创建初始管理员账户的选项提供。

每次后续登录都运行相同的流程：输入您的 handle，在提供商处进行身份验证，然后以登录状态返回 EmDash。

本地开发

AT Protocol OAuth 配置文件要求回环重定向 URI 使用 IP 字面量（127.0.0.1 或 [::1]），而不是 localhost。EmDash 在生成重定向 URI 时会透明地将 ://localhost 重写为 ://127.0.0.1，但这意味着您的开发会话也需要在 127.0.0.1 上启动 — 否则在 localhost 上设置的会话 cookie 在重定向将您带到 127.0.0.1 后将不可见。

Astro 的开发服务器是 Vite 的开发服务器，Vite 默认绑定到 localhost。告诉它也在回环 IP 上监听：

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

然后打开 http://127.0.0.1:4321/_emdash/admin 进行整个流程。

生产环境

相同的配置在生产环境中有效。提供商在以下位置提供自己的客户端元数据：

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

授权服务器在登录期间获取此 URL 以验证客户端的重定向 URI。确保您的部署站点 URL 可通过 HTTPS 在公共互联网上访问 — VPN 后面的仅内部部署将无法完成登录，因为用户的授权服务器无法获取元数据文档。

如果您在 TLS 终止反向代理后运行 EmDash，请设置 siteUrl，以便 EmDash 构建正确的重定向 URI。没有它，请求看起来像 http://internal-host:4321，元数据将不匹配身份验证服务器看到的内容。

故障排除

”Account is not in the allowlist”

您登录的 handle 或 DID 不在 allowedDIDs / allowedHandles 中。检查通配符模式（必须以 *. 开头）并记住 handle 匹配是针对 DNS/HTTP 验证的 — 如果 handle 的 DID 记录当前未解析为提供商返回的相同 DID，则匹配将被拒绝。

“Self-signup is not allowed”

您成功到达了回调，但没有配置允许列表，并且您不是第一个用户。将自己添加到 allowedDIDs/allowedHandles，或让现有管理员邀请您，以便在您登录时用户已经存在。

登录重定向到登录页面而没有错误

这几乎总是本地开发中描述的回环 cookie 问题。在 http://127.0.0.1:4321（设置 server.host: "127.0.0.1" 后）打开管理员，然后重试。

自托管 handle 的 handle 解析失败

提供商通过竞争 DNS-over-HTTPS（Cloudflare 的 DoH 端点）和 HTTP /.well-known/atproto-did 查找来验证 handle。自托管 handle 至少需要以下之一：

• 包含 did=<your-did> 的 _atproto.<handle> DNS TXT 记录，或
• 包含 DID 的 https://<handle>/.well-known/atproto-did 文件。

如果两种方法都失败，即使底层账户有效，handle 匹配也会被拒绝。allowedDIDs 中的 DID 不受影响 — 它们被直接匹配。