Atmosphere 登录

@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({
	server: {
		host: "127.0.0.1", // 本地开发必需；见下文
	},
	integrations: [
		emdash({
			authProviders: [atproto()],
		}),
	],
});

这足以在登录页面和设置向导上放置 Sign in with Atmosphere。未配置允许列表时，第一个用户成为 Admin，之后所有人的自助注册关闭 — 请参阅允许列表来开放。

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

配置访问

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

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

完整的角色层级记录在主身份验证指南中。

允许列表

如果 allowedDIDs 和 allowedHandles 都未设置，则只有第一个用户可以注册。已链接到 EmDash 用户的账户可以继续登录，而新账户会被 signup_not_allowed 拒绝。

当至少配置了一个允许列表时，包括现有用户的登录在内的每次登录都必须匹配。从配置的列表中移除现有用户的 DID 和 handle 会阻止该账户登录。用户在任一列表匹配时被允许：

• DID 匹配。 用户的稳定账户标识符与 allowedDIDs 中的值精确匹配。
• Handle 匹配。 用户的 handle 与 allowedHandles 中的条目精确匹配，或通过前导通配符模式匹配（*.example.com 匹配 alice.example.com 和 bob.team.example.com）。

Handle 允许列表即使在 handle 可变的情况下也是安全的。在通过 handle 匹配允许用户之前，EmDash 会独立解析 handle 的 DNS/HTTP 记录，并验证它指向提供者声称的同一个 DID。恶意提供者无法简单地声称拥有 you.yourcompany.com。

默认角色

允许的用户以 defaultRole 中设置的角色进入。只有第一个用户 — 完成设置的那个 — 被强制为 Admin。Atmosphere 账户没有组/角色映射；如果你需要更细粒度的角色，请在用户首次登录后从设置 → 用户中更改其角色。

设置第一个用户

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

后续登录从 handle 开始，在账户提供者处继续，并带着 EmDash 会话返回。提供者的 OAuth 状态和令牌与 EmDash 会话分开存储，以便 OAuth 回调可以完成，提供者可以刷新自己的会话。

本地开发

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，默认绑定到 localhost。将 Astro 的顶层 server.host 选项设置为环回 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”

你成功到达了回调，但没有配置允许列表且你不是第一个用户。将账户的 DID 添加到 allowedDIDs 或其已验证的 handle 添加到 allowedHandles。电子邮件邀请不会将 Atmosphere DID 链接到 EmDash 用户。

登录无错误地重定向到登录页面

这几乎总是本地开发中描述的环回 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 不受影响 — 它们是直接匹配的。