extension-authorization

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Authorization

授权

Authorization extendsion for Caffeine AI.

为Caffeine AI开发的授权扩展。

Overview

概述

This skill adds an authentication and authorization system with role-based access control using the mixin pattern. The

MixinAuthorization

mixin provides standard authorization endpoints automatically.

该技能通过混入模式（mixin pattern）添加了一套带有基于角色访问控制的身份认证与授权系统。

MixinAuthorization

混入类可自动提供标准的授权端点。

Backend

后端

Authentication system with role-based access control.

There is a prefabricated library

mo:caffeineai-authorization/access-control.mo

. It provides core authentication with role-based access control.

带有基于角色访问控制的身份认证系统。

预制库

mo:caffeineai-authorization/access-control.mo

提供了基于角色访问控制的核心身份认证功能。

Module API

模块API

module {
  public type UserRole = {
    #admin;
    #user;
    #guest;
  };

  public type AccessControlState = { /* internal state */ };

  public func initState() : AccessControlState;
  public func getUserRole(state : AccessControlState, caller : Principal) : UserRole;
  public func assignRole(state : AccessControlState, caller : Principal, user : Principal, role : UserRole);
  public func isAdmin(state : AccessControlState, caller : Principal) : Bool;
  public func hasPermission(state : AccessControlState, caller : Principal, requiredRole : UserRole) : Bool;
};

Initialization is handled internally by

MixinAuthorization

-- do not call

initialize

directly. The first authenticated user to log in automatically becomes admin; no token or secret is required.

IMPORTANT: The

include MixinAuthorization(accessControlState)

line MUST be placed in

main.mo

, not in a custom mixin file.

module {
  public type UserRole = {
    #admin;
    #user;
    #guest;
  };

  public type AccessControlState = { /* internal state */ };

  public func initState() : AccessControlState;
  public func getUserRole(state : AccessControlState, caller : Principal) : UserRole;
  public func assignRole(state : AccessControlState, caller : Principal, user : Principal, role : UserRole);
  public func isAdmin(state : AccessControlState, caller : Principal) : Bool;
  public func hasPermission(state : AccessControlState, caller : Principal, requiredRole : UserRole) : Bool;
};

初始化由

MixinAuthorization

内部处理——请勿直接调用

initialize

方法。第一个完成身份认证的用户将自动成为管理员，无需令牌或密钥。

重要提示：

include MixinAuthorization(accessControlState)

代码行必须放在

main.mo

中，而非自定义混入文件内。

Opting out / custom authentication

退出/自定义身份认证

If the user asks to replace this authorization system with custom authentication (for example username/password auth, no Internet Identity, or no

MixinAuthorization

), remove the

caffeineai-authorization

mops package from the project. This is the only supported way to remove the

include-authorization

lint requirement, because that lint rule is shipped by the package. Do not add suppression comments or leave the package installed while omitting

include MixinAuthorization(accessControlState)

When removing the package, also remove all

mo:caffeineai-authorization/*

imports, the

accessControlState

initialization,

include MixinAuthorization(accessControlState)

, and any

AccessControl

guard calls that belonged to this component. Replace them with the custom authentication and authorization checks requested by the user.

若用户要求用自定义身份认证（例如用户名/密码认证、不使用Internet Identity或不使用

MixinAuthorization

）替换本授权系统，请从项目中移除

caffeineai-authorization

mops包。这是移除

include-authorization

lint检查要求的唯一支持方式，因为该lint规则由该包提供。请勿添加抑制注释，也不要在省略

include MixinAuthorization(accessControlState)

的情况下保留该包。

移除包时，还需删除所有

mo:caffeineai-authorization/*

导入、

accessControlState

初始化代码、

include MixinAuthorization(accessControlState)

以及所有属于该组件的

AccessControl

守卫调用。替换为用户要求的自定义身份认证与授权检查逻辑。

Setup in main.mo

在main.mo中配置

motoko

import Map "mo:core/Map";
import Principal "mo:core/Principal";
import AccessControl "mo:caffeineai-authorization/access-control";
import MixinAuthorization "mo:caffeineai-authorization/MixinAuthorization";
import Types "types";
import ProfileMixin "mixins/Profile";

actor {
  let accessControlState = AccessControl.initState();
  include MixinAuthorization(accessControlState, null);

  let userProfiles = Map.empty<Principal, Types.UserProfile>();

  include ProfileMixin(accessControlState, userProfiles);
};

motoko

import Map "mo:core/Map";
import Principal "mo:core/Principal";
import AccessControl "mo:caffeineai-authorization/access-control";
import MixinAuthorization "mo:caffeineai-authorization/MixinAuthorization";
import Types "types";
import ProfileMixin "mixins/Profile";

actor {
  let accessControlState = AccessControl.initState();
  include MixinAuthorization(accessControlState, null);

  let userProfiles = Map.empty<Principal, Types.UserProfile>();

  include ProfileMixin(accessControlState, userProfiles);
};

Type Definitions in types.mo

types.mo中的类型定义

motoko

module {
  public type UserProfile = {
    name : Text;
  };
};

motoko

module {
  public type UserProfile = {
    name : Text;
  };
};

Custom Mixin Example (mixins/Profile.mo)

自定义混入示例（mixins/Profile.mo）

The frontend requires

getCallerUserProfile

saveCallerUserProfile

, and

getUserProfile

. Pass

accessControlState

to your mixin so it can check permissions.

motoko

import Map "mo:core/Map";
import Principal "mo:core/Principal";
import Runtime "mo:core/Runtime";
import AccessControl "mo:caffeineai-authorization/access-control";
import Types "../types";

mixin (
  accessControlState : AccessControl.AccessControlState,
  userProfiles : Map.Map<Principal, Types.UserProfile>,
) {
  public query ({ caller }) func getCallerUserProfile() : async ?Types.UserProfile {
    if (not AccessControl.hasPermission(accessControlState, caller, #user)) {
      Runtime.trap("Unauthorized");
    };
    userProfiles.get(caller);
  };

  public shared ({ caller }) func saveCallerUserProfile(profile : Types.UserProfile) : async () {
    if (not AccessControl.hasPermission(accessControlState, caller, #user)) {
      Runtime.trap("Unauthorized");
    };
    userProfiles.add(caller, profile);
  };

  public query ({ caller }) func getUserProfile(user : Principal) : async ?Types.UserProfile {
    if (caller != user and not AccessControl.isAdmin(accessControlState, caller)) {
      Runtime.trap("Unauthorized: Can only view your own profile");
    };
    userProfiles.get(user);
  };
};

前端需要

getCallerUserProfile

、

saveCallerUserProfile

和

getUserProfile

方法。将

accessControlState

传入混入类以检查权限。

motoko

import Map "mo:core/Map";
import Principal "mo:core/Principal";
import Runtime "mo:core/Runtime";
import AccessControl "mo:caffeineai-authorization/access-control";
import Types "../types";

mixin (
  accessControlState : AccessControl.AccessControlState,
  userProfiles : Map.Map<Principal, Types.UserProfile>,
) {
  public query ({ caller }) func getCallerUserProfile() : async ?Types.UserProfile {
    if (not AccessControl.hasPermission(accessControlState, caller, #user)) {
      Runtime.trap("Unauthorized");
    };
    userProfiles.get(caller);
  };

  public shared ({ caller }) func saveCallerUserProfile(profile : Types.UserProfile) : async () {
    if (not AccessControl.hasPermission(accessControlState, caller, #user)) {
      Runtime.trap("Unauthorized");
    };
    userProfiles.add(caller, profile);
  };

  public query ({ caller }) func getUserProfile(user : Principal) : async ?Types.UserProfile {
    if (caller != user and not AccessControl.isAdmin(accessControlState, caller)) {
      Runtime.trap("Unauthorized: Can only view your own profile");
    };
    userProfiles.get(user);
  };
};

Guard Patterns

守卫模式

Apply the appropriate guard to every public function:

// 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");
};

// Any user including guests: No check needed

为每个公共函数应用合适的权限守卫：

// 仅管理员可访问:
if (not AccessControl.hasPermission(accessControlState, caller, #admin)) {
  Runtime.trap("Unauthorized: Only admins can perform this action");
};

// 仅普通用户可访问:
if (not AccessControl.hasPermission(accessControlState, caller, #user)) {
  Runtime.trap("Unauthorized: Only users can perform this action");
};

// 包括访客在内的所有用户：无需检查

Design Guidelines

设计准则

Anonymous principals are treated as guests.
```
assignRole
```
includes an admin-only guard internally.
Use
```
shared({ caller })
```
for authenticated endpoints that modify data.
Use
```
query({ caller })
```
for authenticated endpoints that fetch data.
Handle ownership verification where needed.
Use
```
Runtime.trap
```
for authorization failures.

匿名主体（Principal）被视为访客。
```
assignRole
```
内部包含仅管理员可调用的守卫。
对于修改数据的认证端点，使用
```
shared({ caller })
```
。
对于获取数据的认证端点，使用
```
query({ caller })
```
。
必要时处理所有权验证。
授权失败时使用
```
Runtime.trap
```
抛出错误。

Email Attributes

邮箱属性

MixinAuthorization

can capture the user's verified Internet Identity attributes (name and email) at sign-in. Pass a callback as the second argument instead of

null

; it runs once per sign-in, after the attribute bundle has been verified.

Do NOT use the

mo:identity-attributes

mixin directly -- always go through

MixinAuthorization

. The callback receives the caller principal and the verified attributes:

{
  name : ?Text;   // verified display name, when present
  email : ?Text;  // always the verified address -- sourced from II's `verified_email`, never the unverified `email` key
  sso : ?Text;    // SSO domain when the identity came from SSO, otherwise null
}

The field is named

email

, but it only ever holds II's

verified_email

value -- the unverified

email

key is never read. Use

attrs.email

in the callback (there is no

attrs.verified_email

field).

Store them in your own state and expose a getter to read them back:

import Map "mo:core/Map";
import Principal "mo:core/Principal";
import AccessControl "mo:caffeineai-authorization/access-control";
import MixinAuthorization "mo:caffeineai-authorization/MixinAuthorization";

actor {
  let accessControlState = AccessControl.initState();

  let emails = Map.empty<Principal, Text>();

  include MixinAuthorization(
    accessControlState,
    ?(func(caller : Principal, attrs : { name : ?Text; email : ?Text; sso : ?Text }) {
      switch (attrs.email) {
        case (?email) { emails.add(caller, email) };
        case null {};
      };
    }),
  );

  public query ({ caller }) func getCallerEmail() : async ?Text {
    emails.get(caller);
  };
};

The

trusted_attribute_signers

and

frontend_origins

canister environment variables required for attribute verification are configured automatically by the Caffeine platform -- you do not set them.

MixinAuthorization

可在用户登录时捕获其已验证的Internet Identity属性（姓名和邮箱）。将回调函数作为第二个参数传入，而非

null

；该回调会在每次登录且属性包验证通过后执行一次。

请勿直接使用

mo:identity-attributes

混入类——务必通过

MixinAuthorization

调用。回调函数会收到调用者主体和已验证的属性：

{
  name : ?Text;   // 已验证的显示名称（如有）
  email : ?Text;  // 始终为已验证的地址——来自II的`verified_email`，绝不会读取未验证的`email`字段
  sso : ?Text;    // 当身份来自SSO时的SSO域名，否则为null
}

字段名为

email

，但仅存储II的

verified_email

值——未验证的

email

字段绝不会被读取。在回调中使用

attrs.email

（不存在

attrs.verified_email

字段）。

将这些属性存储在自定义状态中，并暴露一个获取方法：

import Map "mo:core/Map";
import Principal "mo:core/Principal";
import AccessControl "mo:caffeineai-authorization/access-control";
import MixinAuthorization "mo:caffeineai-authorization/MixinAuthorization";

actor {
  let accessControlState = AccessControl.initState();

  let emails = Map.empty<Principal, Text>();

  include MixinAuthorization(
    accessControlState,
    ?(func(caller : Principal, attrs : { name : ?Text; email : ?Text; sso : ?Text }) {
      switch (attrs.email) {
        case (?email) { emails.add(caller, email) };
        case null {};
      };
    }),
  );

  public query ({ caller }) func getCallerEmail() : async ?Text {
    emails.get(caller);
  };
}

属性验证所需的

trusted_attribute_signers

和

frontend_origins

容器环境变量由Caffeine平台自动配置——无需手动设置。

Fetching the Email on the Frontend

在前端获取邮箱

After sign-in, query the getter like any other authenticated actor method:

typescript

const { data: callerEmail } = useQuery<string | null>({
  queryKey: ['callerEmail'],
  queryFn: () => actor.getCallerEmail(),
  enabled: !!actor && isAuthenticated,
});

登录后，像调用其他认证后的actor方法一样调用获取方法：

typescript

const { data: callerEmail } = useQuery<string | null>({
  queryKey: ['callerEmail'],
  queryFn: () => actor.getCallerEmail(),
  enabled: !!actor && isAuthenticated,
});

Frontend

前端

Authentication system with role-based access control.

带有基于角色访问控制的身份认证系统。

User Profile Setup

用户配置文件设置

When using Internet Identity, the user gets a principal id only after login. Anonymous principals are treated as guests. The principal id is not human-readable -- ask the user for their name the first time they log in with a new principal.

Backend API for profiles:

getCallerUserProfile(): Promise<UserProfile | null>

-- returns

null

if no profile exists

saveCallerUserProfile(profile: UserProfile): Promise<void>

-- saves name and profile data

getUserProfile(user: Principal): Promise<UserProfile | null>

-- fetch another user's profile

Rules:

On login, if the user already has a profile, do not ask for the name again
Display the user's profile name instead of the principal id
Make sure the user must be logged in before seeing any application data
When logging out, clear all cached application data including the cached user profile

使用Internet Identity时，用户仅在登录后获得主体ID（principal id）。匿名主体被视为访客。主体ID不具备可读性——用户首次使用新主体登录时，请询问其姓名。

配置文件相关后端API：

getCallerUserProfile(): Promise<UserProfile | null>

—— 若配置文件不存在则返回

null

saveCallerUserProfile(profile: UserProfile): Promise<void>

—— 保存姓名和配置文件数据

getUserProfile(user: Principal): Promise<UserProfile | null>

—— 获取其他用户的配置文件

规则：

登录时，若用户已有配置文件，则不再询问姓名
显示用户的配置文件姓名而非主体ID
确保用户必须登录后才能查看任何应用数据
登出时，清除所有缓存的应用数据，包括缓存的用户配置文件

Preventing Profile Setup Modal Flash

避免配置文件设置弹窗闪现

typescript

export function useGetCallerUserProfile() {
  const { actor, isFetching: actorFetching } = useActor();

  const query = useQuery<UserProfile | null>({
    queryKey: ['currentUserProfile'],
    queryFn: async () => {
      if (!actor) throw new Error('Actor not available');
      return actor.getCallerUserProfile();
    },
    enabled: !!actor && !actorFetching,
    retry: false,
  });

  return {
    ...query,
    isLoading: actorFetching || query.isLoading,
    isFetched: !!actor && query.isFetched,
  };
}

Then in your component:

typescript

const showProfileSetup = isAuthenticated && !profileLoading && isFetched && userProfile === null;

typescript

export function useGetCallerUserProfile() {
  const { actor, isFetching: actorFetching } = useActor();

  const query = useQuery<UserProfile | null>({
    queryKey: ['currentUserProfile'],
    queryFn: async () => {
      if (!actor) throw new Error('Actor not available');
      return actor.getCallerUserProfile();
    },
    enabled: !!actor && !actorFetching,
    retry: false,
  });

  return {
    ...query,
    isLoading: actorFetching || query.isLoading,
    isFetched: !!actor && query.isFetched,
  };
}

然后在组件中：

typescript

const showProfileSetup = isAuthenticated && !profileLoading && isFetched && userProfile === null;

Auth State Lifecycle

认证状态生命周期

The

useInternetIdentity

hook exposes two kinds of state — use the right one:

Scenario	`loginStatus`	`isAuthenticated`
Page load, no stored session	`"idle"`	`false`
Page load, restoring stored session	`"initializing"`	`false` → `true`
Stored session restored after reload	`"idle"`	`true`
Interactive login in progress (popup open)	`"logging-in"`	`false`
Interactive login just completed	`"success"`	`true`
Login popup failed / cancelled	`"loginError"`	`false`

IMPORTANT:

isLoginSuccess

(

loginStatus === "success"

) is only

true

after an interactive login via the popup. It is NOT

true

when a stored identity is restored on page reload. Never use

isLoginSuccess

to gate authenticated vs. unauthenticated UI — always use

isAuthenticated

Key states for the login button:

```
isInitializing
```
—
```
AuthClient
```
is loading from IndexedDB; disable the button to prevent clicks before the client is ready.
```
isLoggingIn
```
— the II popup is open; disable the button to prevent duplicate popups.

useInternetIdentity

钩子暴露两种状态——请使用正确的状态：

场景	`loginStatus`	`isAuthenticated`
页面加载，无存储会话	`"idle"`	`false`
页面加载，恢复存储会话	`"initializing"`	`false` → `true`
页面重载后恢复存储会话	`"idle"`	`true`
交互登录进行中（弹窗打开）	`"logging-in"`	`false`
交互登录刚完成	`"success"`	`true`
登录弹窗失败/取消	`"loginError"`	`false`

重要提示：

isLoginSuccess

（即

loginStatus === "success"

）仅在通过弹窗完成交互登录后为

true

。页面重载恢复存储身份时，该值不会为

true

。切勿使用

isLoginSuccess

来区分认证与未认证UI——请始终使用

isAuthenticated

。

登录按钮的关键状态：

```
isInitializing
```
——
```
AuthClient
```
正在从IndexedDB加载；禁用按钮以防止客户端准备好前被点击。
```
isLoggingIn
```
—— II弹窗已打开；禁用按钮以防止重复弹窗。

Login Component

登录组件

typescript

import { useInternetIdentity } from '@caffeineai/core-infrastructure';
import { useQueryClient } from '@tanstack/react-query';

export default function LoginButton() {
  const { login, clear, isAuthenticated, isInitializing, isLoggingIn } = useInternetIdentity();
  const queryClient = useQueryClient();

  const handleAuth = () => {
    if (isAuthenticated) {
      clear();
      queryClient.clear();
    } else {
      login();
    }
  };

  return (
    <button
      onClick={handleAuth}
      disabled={isInitializing || isLoggingIn}
      className={`px-6 py-2 rounded-full transition-colors font-medium ${
        isAuthenticated
          ? 'bg-gray-200 hover:bg-gray-300 text-gray-800'
          : 'bg-blue-600 hover:bg-blue-700 text-white'
      } disabled:opacity-50`}
    >
      {isInitializing ? 'Loading...' : isAuthenticated ? 'Logout' : 'Login'}
    </button>
  );
}

The

login()

and

clear()

functions are fire-and-forget (they don't return promises that track the full flow). The hook's

isLoggingIn

isInitializing

states track the async lifecycle — do not wrap them in local

useState

isPending

logic.

Gate authenticated UI on

isAuthenticated

(covers both fresh login and restored sessions on page reload):

typescript

{isAuthenticated ? (
  <AuthenticatedApp />
) : (
  <LoginScreen />
)}

typescript

import { useInternetIdentity } from '@caffeineai/core-infrastructure';
import { useQueryClient } from '@tanstack/react-query';

export default function LoginButton() {
  const { login, clear, isAuthenticated, isInitializing, isLoggingIn } = useInternetIdentity();
  const queryClient = useQueryClient();

  const handleAuth = () => {
    if (isAuthenticated) {
      clear();
      queryClient.clear();
    } else {
      login();
    }
  };

  return (
    <button
      onClick={handleAuth}
      disabled={isInitializing || isLoggingIn}
      className={`px-6 py-2 rounded-full transition-colors font-medium ${
        isAuthenticated
          ? 'bg-gray-200 hover:bg-gray-300 text-gray-800'
          : 'bg-blue-600 hover:bg-blue-700 text-white'
      } disabled:opacity-50`}
    >
      {isInitializing ? 'Loading...' : isAuthenticated ? 'Logout' : 'Login'}
    </button>
  );
}

login()

和

clear()

函数是“即发即忘”式的（不返回跟踪完整流程的Promise）。钩子的

isLoggingIn

isInitializing

状态会跟踪异步生命周期——不要用本地

useState

isPending

逻辑包裹它们。

通过

isAuthenticated

控制认证UI的显示（涵盖新登录和页面重载恢复会话两种情况）：

typescript

{isAuthenticated ? (
  <AuthenticatedApp />
) : (
  <LoginScreen />
)}

Comparing Current User with Data Author

对比当前用户与数据作者

typescript

import { useInternetIdentity } from '@caffeineai/core-infrastructure';
import type { Principal } from '@icp-sdk/core/principal';

const { identity } = useInternetIdentity();

const isAuthor = (authorPrincipal: Principal): boolean => {
  if (!identity) return false;
  return authorPrincipal.toString() === identity.getPrincipal().toString();
};

typescript

import { useInternetIdentity } from '@caffeineai/core-infrastructure';
import type { Principal } from '@icp-sdk/core/principal';

const { identity } = useInternetIdentity();

const isAuthor = (authorPrincipal: Principal): boolean => {
  if (!identity) return false;
  return authorPrincipal.toString() === identity.getPrincipal().toString();
};

Access Control UI

访问控制UI

For admin-only or personal applications, show an AccessDeniedScreen component when unauthorized users try to access the application.

对于仅管理员或个人使用的应用，当未授权用户尝试访问时，显示AccessDeniedScreen组件。

Error Handling

错误处理

Handle authorization errors from backend

Debug.trap

calls gracefully in the UI with appropriate error messages shown to the user.

Note: The initialization of the first admin is done automatically in

@caffeineai/core-infrastructure

. The first authenticated user to log in becomes admin; no token or secret is needed.

在UI中优雅处理后端

Debug.trap

调用抛出的授权错误，向用户显示合适的错误信息。

注意：第一个管理员的初始化在

@caffeineai/core-infrastructure

中自动完成。第一个完成身份认证的用户将成为管理员，无需令牌或密钥。