extension-user-approval

ユーザー承認

Caffeine AI のユーザー承認拡張機能です。

概要

このスキルは、承認に基づくユーザー管理を追加します。ユーザーはアクセスを申請し、管理者が承認または拒否します。承認されたユーザーは、保護された機能にアクセスできます。

前提条件：この統合は extension-authorization に依存するため、先に従う必要があります。

バックエンド

モジュール API

プレハブモジュール mo:caffeineai-user-approval/approval は、低レベルの承認状態管理を提供します。変更しないでください。

import AccessControl "mo:caffeineai-authorization/access-control";

module {
    public type ApprovalStatus = {
        #approved;
        #rejected;
        #pending;
    };

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

    public func initState(accessControlState: AccessControl.AccessControlState) : UserApprovalState;

    public func isApproved(state : UserApprovalState, caller : Principal) : Bool;
    public func requestApproval(state : UserApprovalState, caller : Principal);
    public func setApproval(state : UserApprovalState, user : Principal, approval : ApprovalStatus);
    public func removeApproval(state : UserApprovalState, user : Principal);

    public type UserApprovalInfo = {
        principal : Principal;
        status : ApprovalStatus;
    };

    public func listApprovals(state : UserApprovalState) : [UserApprovalInfo];
}

main.mo でのセットアップ

include MixinUserApproval(accessControlState, approvalState) は、カスタムのミックスインファイルではなく、main.mo に配置する必要があります。approvalState をアクターのトップレベルで宣言し、ミックスインに渡してください。ミックスインは、以下の公開エンドポイントを自動的に提供します。

• isCallerApproved()
• requestApproval()
• setApproval(user, status)
• removeApproval(user)
• listApprovals()

アプリ固有のエンドポイントでカスタムの承認ガードを使用できるよう、approvalState をスコープ内に保ってください。

ミックスインが提供する関数を再宣言しないでください。

import AccessControl "mo:caffeineai-authorization/access-control";
import MixinAuthorization "mo:caffeineai-authorization/MixinAuthorization";
import MixinUserApproval "mo:caffeineai-user-approval/MixinUserApproval";
import UserApproval "mo:caffeineai-user-approval/approval";
import Runtime "mo:core/Runtime";

actor {
  let accessControlState : AccessControl.AccessControlState;
  include MixinAuthorization(accessControlState, null);
  let approvalState : UserApproval.UserApprovalState;
  include MixinUserApproval(accessControlState, approvalState);

  // Example custom endpoint with an approval guard:
  // public shared ({ caller }) func protectedFeature() : async () {
  //     if (not (UserApproval.isApproved(approvalState, caller) or AccessControl.hasPermission(accessControlState, caller, #admin))) {
  //         Runtime.trap("Unauthorized: Only approved users can perform this action");
  //     };
  // };
};

マイグレーションチェーンの先頭 — UserApproval.initState はアクセス制御状態に依存するため、マイグレーション本体内で順番に計算してください。

import AccessControl "mo:caffeineai-authorization/access-control";
import UserApproval "mo:caffeineai-user-approval/approval";

module {
  type NewActor = {
    accessControlState : AccessControl.AccessControlState;
    approvalState : UserApproval.UserApprovalState;
  };

  public func migration(_old : {}) : NewActor {
    let accessControlState = AccessControl.initState();
    {
      accessControlState;
      approvalState = UserApproval.initState(accessControlState);
    };
  };
};

initState では、既存の管理者は自動的に承認されます。それ以外のユーザーはすべて保留中になります。

匿名のプリンシパルは承認されません。requestApproval と setApproval は匿名のプリンシパルに対してトラップし、isCallerApproved は false を返します。また、登録していないログイン済みの呼び出し元に対しても、isCallerApproved はトラップせずに false を返します。

重要：各カスタム公開関数に、適切な認可チェックおよび／または承認チェックを適用してください。

フロントエンド

承認に基づくユーザー管理：

ユーザー承認フロー

• 承認状態を確認します（isCallerApproved）
• 承認されていない場合は、承認を申請するオプションを表示します（requestApproval）。ログイン済みのユーザーにのみ表示してください。匿名のプリンシパルに対してはトラップします
• 未承認のユーザーが主要機能にアクセスできないようにします
• 管理者はアプリケーションのすべての機能にアクセスできます
• UI に承認状態を明確に表示します

管理者ダッシュボード

管理者ユーザー向けに、以下を行うダッシュボードを提供します。

• すべてのユーザーとその承認状態を一覧表示します（listApprovals）
• ユーザーを承認または拒否します（setApproval）。拒否されたユーザーは再度承認を申請できません
• ユーザーのエントリーを削除し、再度承認を申請できるようにします（removeApproval）
• ユーザーロールを確認および割り当てます（getCallerUserRole と assignCallerUserRole を使用）

バックエンド統合

バックエンドには、以下の機能がすでに実装されています。 完全なインターフェースは で確認できます。

// 現在のユーザーが承認済みか確認します。管理者は常に承認済みです isCallerApproved(): Promise;

// 承認を申請します requestApproval(): Promise;

// すべてのユーザーとその承認状態を取得します（管理者のみ） listApprovals(): Promise<Array>;

// ユーザーを承認または拒否します（管理者のみ） setApproval(user: Principal, status: ApprovalStatus): Promise;

// ユーザーの承認エントリーを削除し、再度承認を申請できるようにします（管理者のみ） removeApproval(user: Principal): Promise;

// ユーザーにロールを割り当てます（管理者のみ） assignCallerUserRole(user: Principal, role: UserRole): Promise;

// 特定のユーザーの現在のロールを取得します getCallerUserRole(): Promise;