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 不受影響 — 它們是直接匹配的。