在 Caffeine AI/Motoko…

适用于 Caffeine AI 项目需要角色访问控制、Internet Identity/Google/Microsoft/SSO 登录、用户资料和已验证邮箱属性时，配置后端授权与前端认证 UI。

适用场景

解决思路

1. 使用预制库 `mo:caffeineai-authorization/access-control.mo`，它提供带角色访问控制（RBAC）的核心认证；不要自己实现基础认证。
2. 模块 API 包含：`UserRole = { #admin; #user; #guest; }`、`AccessControlState`、`initState()`、`getUserRole(state, caller)`、`assignRole(state, caller, user, role)`、`isAdmin(state, caller)`、`hasPermission(state, caller, requiredRole)`。
3. 初始化由 `MixinAuthorization` 内部处理，不要直接调用 `initialize`；第一个登录的已认证用户自动成为 admin，不需要 token 或 secret。
4. 必须把 `include MixinAuthorization(accessControlState);` 放在 `main.mo` 中，不能放在自定义 mixin 文件里。
5. 如果需要退出或替换为自定义认证（例如用户名密码、不用 Internet Identity、不用 `MixinAuthorization`），唯一支持方式是从项目移除 `caffeineai-authorization` mops 包；不要添加 suppression comments，也不要在包仍安装时省略 `include MixinAuthorization(accessControlState)`。
6. 移除该包时，同时移除所有 `mo:caffeineai-authorization/*` imports、`accessControlState` 初始化、`include MixinAuthorization(accessControlState)`，以及属于该组件的 `AccessControl` guard calls；替换为用户要求的自定义认证和授权检查。
7. 在 `src/backend/main.mo` 中按示例设置：import `Map`、`Principal`、`AccessControl`、`MixinAuthorization`、`Types`、`ProfileMixin`；定义 `let accessControlState : AccessControl.AccessControlState; include MixinAuthorization(accessControlState, null);`；定义 `userProfiles` Map；`include ProfileMixin(accessControlState, userProfiles);`。
8. 在 `src/backend/migrations/00000000_000000.mo` 配置迁移链头：import `Map` 和 `AccessControl`；定义 `NewActor` 包含 `accessControlState : AccessControl.AccessControlState` 和 `userProfiles : Map.Map<Principal, UserProfile>`；migration 返回 `{ accessControlState = AccessControl.initState(); userProfiles = Map.empty<Principal, UserProfile>(); }`。
9. 在 `src/backend/types.mo` 定义所需类型，例如 `public type UserProfile = { name : Text; };`。
10. 自定义 mixin 示例放在 `src/backend/mixins/Profile.mo`：mixin 接收 `accessControlState` 和 `userProfiles`；前端需要 `getCallerUserProfile`、`saveCallerUserProfile`、`getUserProfile`。
11. 实现 `getCallerUserProfile`：如果 `not AccessControl.hasPermission(accessControlState, caller, #user)`，则 `Runtime.trap("Unauthorized")`；返回 `userProfiles.get(caller)`。
12. 实现 `saveCallerUserProfile`：如果 `not AccessControl.hasPermission(accessControlState, caller, #user)`，则 `Runtime.trap("Unauthorized")`；然后 `userProfiles.add(caller, profile)`。
13. 实现 `getUserProfile(user)`：如果 `caller != user and not AccessControl.isAdmin(accessControlState, caller)`，则 `Runtime.trap("Unauthorized: Can only view your own profile")`；返回 `userProfiles.get(user)`。
14. 对每个 public function 应用合适的 guard：Admin-only 用 `if (not AccessControl.hasPermission(accessControlState, caller, #admin)) { Runtime.trap("Unauthorized: Only admins can perform this action"); };`；Users only 用 `if (not AccessControl.hasPermission(accessControlState, caller, #user)) { Runtime.trap("Unauthorized: Only users can perform this action"); };`；任何用户包括 guest 不需要检查。
15. 设计指南：匿名 principals 视为 guests。
16. 设计指南：`assignRole` 内部已包含 admin-only guard。
17. 设计指南：修改数据的已认证端点用 `shared({ caller })`；获取数据的已认证端点用 `query({ caller })`。
18. 设计指南：需要时处理 ownership verification。
19. 设计指南：授权失败使用 `Runtime.trap`。
20. Email attributes：`MixinAuthorization` 可在登录时捕获用户已验证的 Internet Identity 属性（name 和 email）。传入回调作为第二个参数，而不是 `null`；回调每次登录运行一次，在属性 bundle 验证后运行。
21. Email attributes：不要直接使用 `mo:identity-attributes` mixin，始终通过 `MixinAuthorization`。
22. Email attributes：回调接收 caller principal 和已验证属性：`{ name : ?Text; email : ?Text; sso : ?Text; }`。字段名是 `email`，但只保存 II 的 `verified_email` 值，从不读取未验证的 `email` key；使用 `attrs.email`，没有 `attrs.verified_email` 字段。
23. Email attributes 取决于前端使用的 sign-in variant：`login()`（plain Internet Identity）在用户有 verified email 时提供 `email`，`sso` 为 null；`login({ provider: 'google' })` 提供来自 Google 的 verified `name` 和 `email`，`sso` 为 null；`login({ provider: 'microsoft' })` 提供来自 Microsoft 的 verified `name` 和 `email`，`sso` 为 null；`login({ ssoDomain: 'acme.com' })` 提供来自公司身份提供方的 verified `name` 和 `email`，`sso` 保存域名（如 `"acme.com"`），可用 `attrs.sso` 限制公司成员功能或按域名自动分配角色。
24. 将属性存储在自己的 state 中，并暴露 getter 读回。示例：`let emails : Map.Map<Principal, Text>; include MixinAuthorization(accessControlState, ?(func(caller, attrs) { switch (attrs.email) { case (?email) { emails.add(caller, email) }; case null {}; }; })); public query ({ caller }) func getCallerEmail() : async ?Text { emails.get(caller); };`。
25. `trusted_attribute_signers` 和 `frontend_origins` canister 环境变量由 Caffeine platform 自动配置，你不需要设置。
26. 前端获取 email：登录后像其他已认证 actor 方法一样查询 getter，例如 `useQuery<string | null>({ queryKey: ['callerEmail'], queryFn: () => actor.getCallerEmail(), enabled: !!actor && isAuthenticated, });`。
27. 前端 sign-in 通过 `@caffeineai/core-infrastructure` 的 `useInternetIdentity` hook；默认使用普通 `login()`，除非要求 Google、Microsoft 或 company/workspace SSO。
28. 当要求 Google、Microsoft 或 SSO 登录时，登录屏幕必须显示所请求的直接选项（Google 按钮、Microsoft 按钮和/或 SSO domain input），并保留普通 `login()` "Sign in with Internet Identity" 按钮作为 fallback；没有 Google/Microsoft 账号或未注册公司域名的用户仍必须能登录。
29. 对已有用户的应用，永远不要移除 Internet Identity 选项。principal 来自用户 Internet Identity：Google/Microsoft-backed II 用户通过任一按钮得到相同 principal；但用 passkey-based II 身份注册的用户，如果用一个未链接到该身份的 Google/Microsoft 账号认证，会得到不同 principal，数据会看似丢失。保留两个按钮让每个现有用户按原方式登录。
30. 用户资料设置：使用 Internet Identity 时，用户仅登录后获得 principal id；匿名 principals 视为 guests；principal id 不可读，因此第一次用新 principal 登录时询问用户名。
31. 后端 profile API：`getCallerUserProfile(): Promise<UserProfile | null>` 无 profile 时返回 null；`saveCallerUserProfile(profile: UserProfile): Promise<void>` 保存 name 和 profile 数据；`getUserProfile(user: Principal): Promise<UserProfile | null>` 获取他人 profile。
32. Profile 规则：登录时如果用户已有 profile，不要再问 name；显示用户 profile name 而不是 principal id；确保用户登录后才能看到任何应用数据；登出时清除所有缓存应用数据，包括缓存的 user profile。
33. 防止 Profile Setup Modal Flash：使用 `useGetCallerUserProfile` hook，组合 `useActor()` 的 `actor, isFetching: actorFetching`；`useQuery<UserProfile | null>`，`queryKey: ['currentUserProfile']`，`queryFn` 如果 actor 不存在则 throw，否则返回 `actor.getCallerUserProfile()`；`enabled: !!actor && !actorFetching`，`retry: false`；返回 `...query, isLoading: actorFetching || query.isLoading, isFetched: !!actor && query.isFetched`。
34. 组件中设置 `const showProfileSetup = isAuthenticated && !profileLoading && isFetched && userProfile === null;`。
35. Auth State Lifecycle：`useInternetIdentity` 暴露两种 state，要用对。场景：页面加载无存储会话时 `loginStatus='idle'`、`isAuthenticated=false`；页面加载恢复存储会话时 `loginStatus='initializing'`、`isAuthenticated=false → true`；重载后恢复存储会话时 `loginStatus='idle'`、`isAuthenticated=true`；交互式登录进行中（popup 打开）时 `loginStatus='logging-in'`、`isAuthenticated=false`；交互式登录刚完成时 `loginStatus='success'`、`isAuthenticated=true`；登录 popup 失败或取消时 `loginStatus='loginError'`、`isAuthenticated=false`。
36. IMPORTANT：`isLoginSuccess`（`loginStatus === 'success'`）仅在通过 popup 交互式登录后为 true，页面重载恢复存储身份时不为 true。绝不用 `isLoginSuccess` 来 gate authenticated vs. unauthenticated UI，始终用 `isAuthenticated`。
37. 登录按钮关键状态：`isInitializing` 表示 `AuthClient` 正从 IndexedDB 加载，禁用按钮防止在 client ready 前点击；`isLoggingIn` 表示 II popup 打开，禁用按钮防止重复 popup。
38. Login 组件示例：从 `@caffeineai/core-infrastructure` 导入 `useInternetIdentity`，从 `@tanstack/react-query` 导入 `useQueryClient`；使用 `const { login, clear, isAuthenticated, isInitializing, isLoggingIn } = useInternetIdentity(); const queryClient = useQueryClient();`；handleAuth 中如果 `isAuthenticated` 则 `clear(); queryClient.clear();`，否则 `login();`；按钮 `onClick={handleAuth}`、`disabled={isInitializing || isLoggingIn}`，class 按状态变化，文本用 `isInitializing ? 'Loading...' : isAuthenticated ? 'Logout' : 'Login'`。
39. `login()` 和 `clear()` 是 fire-and-forget（不返回跟踪完整流程的 promise）。hook 的 `isLoggingIn` / `isInitializing` 状态跟踪异步生命周期，不要把它们包在本地 `useState` / `isPending` 逻辑中。
40. 当应用要求 Google、Microsoft 或 company/workspace SSO 时，使用同一 hook 带 options：`login({ provider: 'google' })`、`login({ provider: 'microsoft' })`、`login({ ssoDomain: 'acme.com' })`。所有变体产生相同 identity 和 session 行为；完整登录 UI 模式见 `extension-core-infrastructure` skill。
41. Gate authenticated UI 用 `{isAuthenticated ? <AuthenticatedApp /> : <LoginScreen />}`，覆盖新登录和页面重载恢复会话。
42. 比较当前用户与数据作者：从 `@caffeineai/core-infrastructure` 导入 `useInternetIdentity`，从 `@icp-sdk/core/principal` 导入 `Principal`；使用 `const { identity } = useInternetIdentity(); const isAuthor = (authorPrincipal: Principal): boolean => { if (!identity) return false; return authorPrincipal.toString() === identity.getPrincipal().toString(); };`。
43. 访问控制 UI：对于 admin-only 或个人应用，当未授权用户尝试访问应用时显示 `AccessDeniedScreen` 组件。
44. 错误处理：在 UI 中优雅处理后端 `Debug.trap` 调用的授权错误，向用户显示适当错误消息。
45. 注意：第一个 admin 的初始化在 `@caffeineai/core-infrastructure` 中自动完成；第一个已认证登录用户成为 admin，不需要 token 或 secret。

适用边界 · 注意事项

• 不适用于非 Caffeine AI/Motoko 项目，或不需要 Internet Identity、角色访问控制的项目。
• 不适用于未使用 `caffeineai-authorization` mops 包和 `@caffeineai/core-infrastructure` 的项目。
• 如果只想局部权限但不想引入 `MixinAuthorization`，必须走移除包并替换为自定义认证的路径；不能保留包同时省略 `include MixinAuthorization(accessControlState)`。