IFGAProvider

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

有關概念、設定，以及 Mastra 強制執行 FGA 的生命週期節點，請參閱細粒度授權。

使用範例

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

src/mastra/fga.ts

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 會在其強制執行節點呼叫此方法。

傳回：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。

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

= false

設為 true 時，沒有路由層級 FGA metadata 或 resolver 輸出的受保護路由會被拒絕，而非獲准通過。

auditProtectedRoutes?:

boolean | 'warn' | 'error'

= false

稽核缺少內置 FGA metadata 的受保護路由。使用 true 或 'warn' 記錄啟動警告，使用 'error' 使啟動失敗，或使用 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。

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.

相關內容

• 細粒度授權
• 系統 actor
• WorkOS 身份驗證