交给 Agent 的接入指南

01
在工坊登记作品
填写社区应用名称和精确回调 URI，领取独立 Client ID。
02
复制任务说明
从作品详情复制已填好 Client ID、Redirect URI 和 Scopes 的版本。
03
让 Agent 开工
Agent 会先查看项目，再使用标准 OIDC 库完成登录、回调和测试。

CHOOSE THE ROUTE

先告诉 Agent 你的作品跑在哪里

网站与 Web 应用

用 Authorization Code + PKCE。服务端接收回调并保存会话；浏览器只负责跳转，不保存 Refresh Token。

桌面启动器与本地 App

用系统浏览器完成登录，再回到 loopback 回调。登记的 127.0.0.1 或 [::1] 路径必须完全一致。

终端、服务器插件与设备

在作品审核并启用“设备配对”后使用 Device Flow。程序显示短码，玩家在浏览器确认身份。

给 Agent 的任务说明

还没有作品时先用这份模板；尖括号内容由你或 Agent 补齐。

请在我现有的项目中接入 NewNanCity 账号登录。先检查仓库现有的框架、路由、会话、配置和测试模式，再实施；不要另起一套不符合项目惯例的认证架构。

OIDC Provider 背景：
- Issuer: https://id.newnan.city
- Discovery: https://id.newnan.city/.well-known/openid-configuration
- Client 类型: public client，不存在 client_secret
- Flow: Authorization Code + PKCE S256
- Client ID: <从应用详情复制 Client ID>
- Redirect URI: <开发者中心登记的精确 Redirect URI>
- 允许的 Scopes: openid profile minecraft:profile offline_access

身份语义：
- 用户可能拥有多个 Minecraft Player Profile，登录授权时会选择其中一个。
- sub 是所选 Player 的稳定 UUID；不要改用邮箱、昵称或 Blessing Skin uid 作为业务身份主键。
- profile scope 可读取 name、preferred_username、nickname、picture、profile、updated_at。
- minecraft:profile scope 可读取 minecraft_profile，其中包含 uuid、player_id、player_name、avatar_url。
- 应用本地用户只以 issuer 与 sub 的组合建立唯一绑定；首次登录创建该绑定，后续只按它查找。
  不要把邮箱、昵称、Player 名称、头像 URL 或 Blessing Skin uid 当作本地账户主键；它们仅是可更新的展示资料。
- 只使用应用详情实际允许的 scopes，不要自行追加 email。需要让玩家保持登录时，请请求 offline_access；
  Refresh Token 只能保存在服务端安全存储或原生系统的 Keychain/Credential Manager 中，不能放进浏览器本地存储或日志。

安全与实现要求：
1. 优先使用该技术栈中仍受维护的标准 OIDC/OAuth 客户端库，不要手写协议或 JWT 验签。
2. 登录请求必须生成并校验 state、nonce 和 PKCE code_verifier。通常回调 URI 必须与上面登记值完全一致；但若上面是无端口的 127.0.0.1 或 [::1] URI，它明确表示“支持任意端口”，不代表默认端口 80：程序应监听 127.0.0.1:0 或 [::1]:0 取得随机端口，并在授权请求与 Token 兑换中使用带该实际端口的回调 URI。协议、IP 字面量和路径仍必须一致。
3. 按 Discovery/JWKS 校验 issuer、audience、签名、nonce 和令牌时效；不要关闭 TLS 或验签。
4. 应用不得收集 NewNanCity/Blessing Skin 密码，登录必须重定向到 Identity Provider。
5. Client ID、Issuer、Redirect URI 通过环境变量或项目既有配置系统注入；不要硬编码密钥，也不要虚构 client_secret。
6. 按项目现有安全模式保存本地会话和令牌；日志不得记录授权码、Access Token、Refresh Token 或完整 ID Token。
7. 实现登录入口、回调、登录态读取和本地退出；补正常路径、state/nonce 失败、回调错误和未登录访问测试。
8. 桌面 App 必须用系统浏览器与 loopback IP 回调；当登记 URI 不含端口时，运行时从系统取得随机端口，
   但协议、IP 和路径必须保持一致。不要嵌入 WebView，也不要在 App 内伪造 client_secret。
实施路径：
- 网站或 Web 应用：使用 Authorization Code + PKCE；由服务端（或现有 BFF）处理回调、建立本地会话并保存令牌。不要把 Refresh Token 放在 localStorage、sessionStorage 或前端日志里。
- 桌面启动器或本地 App：使用系统浏览器，不用嵌入 WebView；监听登记的 loopback IP 回调。登记 URI 不含端口时可使用随机端口，但协议、IP 与路径必须一致；令牌仅存入操作系统安全凭据库。
- 无浏览器的 CLI、服务器插件或受限设备：仅当应用详情显示“设备配对已启用”时实现 Device Flow。调用 Discovery 中的 device_authorization_endpoint，展示 user_code / verification_uri，按 interval 轮询 token_endpoint；处理 authorization_pending、slow_down、access_denied 与 expired_token，绝不记录 device_code。
- 长期登录：每次 Refresh Token 兑换成功后，必须在同一持久化操作中先保存响应中的新 Refresh Token，再废弃旧值；不得重用旧 Token。
  收到 invalid_grant、授权撤销或 Refresh Token 缺失时，清理本地会话/凭据并要求用户重新登录，不要循环重试或静默降级。

开始改代码前，如果 Client ID、Redirect URI、技术栈、部署地址或作品运行形态仍缺失，只询问这些最小阻塞信息。完成后请列出修改文件、环境变量、启动方式、测试命令和仍需人工配置的事项。

交出去前，你只需确认这些事

把 Agent 放进正确的项目，并说明它是网站、桌面 App 还是设备程序。
从开发工坊复制 Client ID 和精确 Redirect URI，不要让 Agent 猜测或新建第二套配置。
确认你的应用登录后要保存哪些业务资料；以 issuer 与 sub 的组合绑定本地用户，名称和头像只作展示。
若需要长期登录，要求 Agent 在刷新成功时替换旧 Refresh Token；失效或撤销时清理登录态并重新授权。
不要把牛腩账号密码交给应用或 Agent。登录只会在 NewNan Identity 页面中完成。