IFGAProvider

L’interface IFGAProvider définit un Provider d’autorisation granulaire (FGA). Mastra l’appelle pour déterminer si un utilisateur ou un acteur système peut exercer une permission sur une ressource donnée. Implémentez-la pour connecter Mastra à un backend FGA tel que WorkOS Authorization.

Pour découvrir les concepts, la configuration et les étapes du cycle de vie auxquelles Mastra applique FGA, consultez la page Autorisation granulaire.

Exemple d’utilisation

L’exemple suivant implémente un Provider minimal. require lève une erreur pour refuser l’accès, tandis que check renvoie un booléen.

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
  }
}

Méthodes

check(user, params)

Indique si user possède la permission sur la ressource. Utilisez cette méthode pour les vérifications qui ne lèvent pas d’erreur, comme le filtrage ou les interfaces conditionnelles.

Renvoie : Promise<boolean>

require(user, params)

Lève FGADeniedError lorsque user ne possède pas la permission. Mastra appelle cette méthode à ses points d’application.

Renvoie : Promise<void>

filterAccessible(user, resources, resourceType, permission)

Renvoie le sous-ensemble de resources auquel user peut accéder avec permission.

Renvoie : Promise<T[]>

requireActor(actor, params)

Autorise un acteur système qui n’est pas un utilisateur, tel qu’un Agent autonome ou planifié. Facultatif.

Les acteurs système contournent le chemin require() centré sur l’utilisateur. Implémentez donc requireActor afin d’appliquer pour eux le principe du moindre privilège à chaque Agent. Levez FGADeniedError pour refuser l’accès. Lorsqu’un Provider n’implémente pas requireActor, Mastra conserve le contournement destiné aux acteurs de confiance, c’est-à-dire l’autorisation après vérification de la portée du tenant. L’ajout de cette méthode reste ainsi rétrocompatible.

Traitez actor.permissions comme un claim non fiable. Résolvez les autorisations faisant foi de l’Agent à partir d’une source de confiance indexée par actor.agentId, au lieu de vous fier aux valeurs intégrées. Consultez la section Acteurs système.

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)
    }
  }
}

Renvoie : Promise<void>

Propriétés de configuration

Des propriétés facultatives contrôlent la couverture des routes et la validation au démarrage.

requireForProtectedRoutes?:

boolean

= false

Lorsque la valeur est true, les routes protégées dépourvues de métadonnées FGA au niveau de la route ou de sortie du résolveur sont refusées au lieu d’être autorisées.

auditProtectedRoutes?:

boolean | 'warn' | 'error'

= false

Audite les routes protégées qui ne possèdent pas de métadonnées FGA intégrées. Utilisez true ou 'warn' pour consigner un avertissement au démarrage, 'error' pour faire échouer le démarrage ou false pour désactiver l’audit.

resolveRouteFGA?:

FGARouteResolver

Déduit le type et l’ID de la ressource, ainsi que la permission, à partir de la route, des paramètres analysés et du contexte de requête.

validatePermissions?:

(permissions: MastraFGAPermissionInput[]) => void | Promise<void>

Validation au démarrage des correspondances de permissions propres au Provider. Lève une erreur lorsqu’une permission que Mastra peut émettre n’est pas associée.

Paramètres

Argument params transmis à check, require et requireActor.

resource:

{ type: string; id: string }

Ressource faisant l’objet de l’accès.

permission:

MastraFGAPermissionInput | MastraFGAPermissionInput[]

Permission(s) vérifiée(s). Lorsqu’un tableau est fourni, l’acteur doit posséder au moins l’une des permissions répertoriées.

context?:

FGACheckContext

Contexte propre au Provider pour la résolution de la ressource, notamment le resourceId propriétaire, le contexte de requête et les métadonnées de l’action.

ActorSignal

Identifie un appel effectué par un acteur de confiance qui n’est pas un utilisateur, plutôt que par un utilisateur final authentifié. Il s’agit soit de true, forme abrégée du système anonyme, soit d’un objet qui nomme l’Agent agissant et contient les autorisations qu’un Provider peut appliquer.

actorKind:

'system'

Identifie la forme objet du signal.

agentId?:

string

Identité de l’Agent système agissant. Contrairement à la ressource vérifiée, qui constitue la cible, cette valeur nomme l’acteur lui-même afin qu’un Provider puisse appliquer le principe du moindre privilège pour chaque Agent.

permissions?:

MastraFGAPermissionInput[]

Autorisations revendiquées pour cet acteur. Il s’agit d’une indication autodéclarée et non fiable ; un Provider qui applique réellement le principe du moindre privilège résout les autorisations faisant foi de l’Agent à partir d’une source de confiance indexée par agentId, au lieu de se fier à ces valeurs.

scope?:

Record<string, string>

Portée supplémentaire propre au Provider pour l’acteur, par exemple le tenant ou l’environnement.

sourceWorkflow?:

string

Nom du Workflow qui a démarré l’exécution de l’acteur, le cas échéant.

FGADeniedError

Erreur levée lorsqu’une vérification d’autorisation est refusée. require et requireActor la lèvent pour refuser l’accès, et Mastra la présente comme une réponse 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.

Voir aussi

• Autorisation granulaire
• Acteurs système
• Authentification WorkOS