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