> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/llms.txt

# IFGAProvider

`IFGAProvider` interface 定義細粒度授權（FGA）Provider。Mastra 會呼叫它，以決定用戶或系統 actor 是否可以對特定資源執行某項權限。實作此 interface 可將 Mastra 連接至 FGA 後端，例如 WorkOS Authorization。

有關概念、設定，以及 Mastra 強制執行 FGA 的生命週期節點，請參閱[細粒度授權](https://mastra.zisheng.pro/zh-HK/docs/server/auth/fga)。

## 使用範例

以下範例實作一個最基本的 Provider。`require` 會拋出錯誤以拒絕請求，而 `check` 則傳回 boolean。

```typescript
import { FGADeniedError } from '@mastra/core/auth/ee'
import type { FGACheckParams, IFGAProvider, MastraFGAPermissionInput } from '@mastra/core/auth/ee'

class MyFGAProvider implements IFGAProvider {
  async check(user: any, params: FGACheckParams): Promise<boolean> {
    // Your authorization logic.
    return true
  }

  async require(user: any, params: FGACheckParams): Promise<void> {
    if (!(await this.check(user, params))) {
      throw new FGADeniedError(user, params.resource, params.permission)
    }
  }

  async filterAccessible<T extends { id: string }>(
    user: any,
    resources: T[],
    resourceType: string,
    permission: MastraFGAPermissionInput,
  ): Promise<T[]> {
    return resources
  }
}
```

## 方法

### `check(user, params)`

傳回 `user` 是否對資源擁有指定權限。這適用於不拋出錯誤的檢查，例如篩選或條件式 UI。

傳回：`Promise<boolean>`

### `require(user, params)`

當 `user` 缺少權限時拋出 `FGADeniedError`。Mastra 會在其[強制執行節點](https://mastra.zisheng.pro/zh-HK/docs/server/auth/fga)呼叫此方法。

傳回：`Promise<void>`

### `filterAccessible(user, resources, resourceType, permission)`

傳回 `user` 可使用 `permission` 存取的 `resources` 子集。

傳回：`Promise<T[]>`

### `requireActor(actor, params)`

授權非用戶的系統 actor，例如自主或排程執行的 Agent。選填。

系統 actor 會略過以用戶為中心的 `require()` 路徑，因此請實作 `requireActor`，為它們強制執行各 Agent 的最小權限。拋出 `FGADeniedError` 以拒絕請求。當 Provider 未實作 `requireActor` 時，Mastra 會保留受信任 actor 略過機制（通過租戶 scope 檢查後允許請求），因此新增此方法仍可向後兼容。

請將 `actor.permissions` 視為不受信任的 claim。應使用 `actor.agentId` 作為鍵，從受信任來源解析 Agent 的權威授權，而非信任 inline 值。請參閱[系統 actor](https://mastra.zisheng.pro/zh-HK/docs/server/auth/fga)。

```typescript
import { FGADeniedError } from '@mastra/core/auth/ee'
import type { ActorSignal, FGACheckParams, IFGAProvider } from '@mastra/core/auth/ee'

class MyFGAProvider implements IFGAProvider {
  // ...check, require, filterAccessible...

  async requireActor(actor: ActorSignal, params: FGACheckParams): Promise<void> {
    const agentId = actor === true ? undefined : actor.agentId
    // Resolve the agent's authoritative grants from a trusted source keyed by agentId.
    const granted = await this.grantsForAgent(agentId)
    const required = Array.isArray(params.permission) ? params.permission : [params.permission]
    if (!required.some(permission => granted.includes(permission))) {
      throw new FGADeniedError(null, params.resource, params.permission)
    }
  }
}
```

傳回：`Promise<void>`

## 設定屬性

選填屬性可控制路由涵蓋範圍及啟動驗證。

**requireForProtectedRoutes** (`boolean`): 設為 true 時，沒有路由層級 FGA metadata 或 resolver 輸出的受保護路由會被拒絕，而非獲准通過。 (Default: `false`)

**auditProtectedRoutes** (`boolean | 'warn' | 'error'`): 稽核缺少內置 FGA metadata 的受保護路由。使用 true 或 'warn' 記錄啟動警告，使用 'error' 使啟動失敗，或使用 false 停用。 (Default: `false`)

**resolveRouteFGA** (`FGARouteResolver`): 從路由、已剖析的參數和請求 context 衍生資源類型、資源 ID 及權限。

**validatePermissions** (`(permissions: MastraFGAPermissionInput[]) => void | Promise<void>`): 針對 Provider 特定權限映射的啟動驗證。當 Mastra 可能發出的權限未有映射時，拋出錯誤。

## 參數

傳入 `check`、`require` 和 `requireActor` 的 `params` 引數。

**resource** (`{ type: string; id: string }`): 正在存取的資源。

**permission** (`MastraFGAPermissionInput | MastraFGAPermissionInput[]`): 正在檢查的權限。提供 array 時，actor 只需具備所列權限中的任何一項。

**context** (`FGACheckContext`): 用於解析資源的 Provider 特定 context，包括所屬資源的 resourceId、請求 context 及操作 metadata。

## `ActorSignal`

識別由受信任的非用戶 actor（而非已通過身份驗證的終端用戶）作出的呼叫。它可以是 `true`（匿名系統的簡寫），或是指定執行操作的 Agent 並帶有 Provider 可強制執行之授權的物件。

**actorKind** (`'system'`): 標示 signal 的物件形式。

**agentId** (`string`): 執行操作的系統 Agent 身份。這與檢查資源（目標）不同，它指定 actor 本身，讓 Provider 可以強制執行各 Agent 的最小權限。

**permissions** (`MastraFGAPermissionInput[]`): 為此 actor 聲稱的權限授權。這是不受信任、自我聲明的提示；強制執行真正最小權限的 Provider 會使用 agentId 作為鍵，從受信任來源解析 Agent 的權威授權，而非信任這些值。

**scope** (`Record<string, string>`): Actor 的額外 Provider 特定 scope，例如租戶或環境。

**sourceWorkflow** (`string`): 在適用時，啟動 actor 執行的 Workflow 名稱。

## `FGADeniedError`

授權檢查被拒絕時拋出。`require` 和 `requireActor` 會拋出此錯誤以拒絕請求，而 Mastra 會將其呈現為 HTTP `403`。

```typescript
import { FGADeniedError } from '@mastra/core/auth/ee'

throw new FGADeniedError(user, { type: 'agent', id: 'reporter' }, 'agents:execute')
// Optional fourth argument: a reason string included in the error message.
```

## 相關內容

- [細粒度授權](https://mastra.zisheng.pro/zh-HK/docs/server/auth/fga)
- [系統 actor](https://mastra.zisheng.pro/zh-HK/docs/server/auth/fga)
- [WorkOS 身份驗證](https://mastra.zisheng.pro/zh-HK/reference/auth/workos)