Better Auth

Le package @mastra/auth-better-auth fournit l'authentification Better Auth à Mastra. Il vérifie les requêtes entrantes au moyen de votre instance Better Auth et s'intègre au serveur Mastra via l'option server.auth.

Prérequis

Cet exemple utilise Better Auth. Vérifiez que votre instance Better Auth est configurée et que vos variables d'environnement sont définies.

.env

# Required by Better Auth
BETTER_AUTH_SECRET=...   # at least 32 chars
BETTER_AUTH_URL=http://localhost:3000

# Example DB URL used by the snippet below (adjust for your setup)
DATABASE_URL=postgres://...

remarque

Pour des raisons de sécurité et de stabilité, Better Auth recommande de définir explicitement baseURL (ou de le faire au moyen de BETTER_AUTH_URL).

Si vous n'avez pas encore monté le gestionnaire de Better Auth afin que votre application puisse connecter les utilisateurs et créer des sessions, suivez le guide d'installation de Better Auth pour monter la route /api/auth/* (ou le chemin de base que vous avez configuré).

Installation

Installez le package @mastra/auth-better-auth :

npm

npm install @mastra/auth-better-auth

pnpm

pnpm add @mastra/auth-better-auth

Yarn

yarn add @mastra/auth-better-auth

Bun

bun add @mastra/auth-better-auth

Exemple d'utilisation

Commencez par créer votre instance Better Auth :

lib/auth.ts

import { betterAuth } from 'better-auth'

export const auth = betterAuth({
  database: {
    provider: 'postgresql',
    url: process.env.DATABASE_URL!,
  },
  emailAndPassword: {
    enabled: true,
  },
  baseURL: process.env.BETTER_AUTH_URL,
  secret: process.env.BETTER_AUTH_SECRET,
})

Utilisez-la ensuite avec Mastra :

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraAuthBetterAuth } from '@mastra/auth-better-auth'
import { auth } from '@/lib/auth'

const mastraAuth = new MastraAuthBetterAuth({
  auth,
})

export const mastra = new Mastra({
  server: {
    auth: mastraAuth,
  },
})

Consultez MastraAuthBetterAuth pour découvrir toutes les options de configuration disponibles.

Autorisation personnalisée

const mastraAuth = new MastraAuthBetterAuth({
  auth,
  async authorizeUser(user) {
    // Example: only allow verified emails
    return user?.user?.emailVerified === true
  },
})

Configuration des routes

const mastraAuth = new MastraAuthBetterAuth({
  auth,
  public: ['/health', '/api/status'],
  protected: ['/api/*', '/admin/*'],
})

Règles de correspondance

• public et protected acceptent des chemins exacts, des motifs avec caractères génériques (comme /api/*) et des paramètres de chemin (comme /users/:id).
• Pour définir des règles propres à une méthode, utilisez des tuples comme ["/api/agents", ["GET", "POST"]].
• Si une route correspond à la fois à public et à protected, public l'emporte et aucune authentification n'est requise.
• Si aucune règle ne correspond, les routes sont considérées comme protégées par défaut, sauf si une route porte explicitement le marqueur requiresAuth: false.

Configuration côté client

Lorsque l'authentification est activée, les requêtes adressées aux routes intégrées de Mastra doivent être authentifiées. En pratique, votre client doit donc envoyer l'identifiant utilisé par votre configuration Better Auth pour les requêtes authentifiées.

Session par cookie (recommandé)

Si votre configuration Better Auth utilise des cookies, configurez le client pour qu'il envoie les identifiants. Pour les requêtes interorigines (par exemple Next.js sur :3000 appelant Mastra sur :4111), activez la transmission des identifiants CORS sur le serveur Mastra :

src/mastra/index.ts

export const mastra = new Mastra({
  server: {
    auth: mastraAuth,
    cors: {
      origin: 'http://localhost:3000', // your frontend origin
      credentials: true,
    },
  },
})

Configurez ensuite le client pour inclure les identifiants :

import { MastraClient } from '@mastra/client-js'

export const mastraClient = new MastraClient({
  baseUrl: 'http://localhost:4111',
  credentials: 'include',
})

Si vous appelez directement l'API, incluez également les identifiants dans fetch :

await fetch('http://localhost:4111/api/agents/weatherAgent/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  credentials: 'include',
  body: JSON.stringify({ messages: 'Weather in London' }),
})

Jeton Bearer

Vous pouvez transmettre le jeton de session signé comme jeton Bearer. Récupérez-le depuis la session de votre client Better Auth et incluez-le dans l'en-tête Authorization :

import { MastraClient } from '@mastra/client-js'
import { authClient } from './auth-client' // your Better Auth client

const session = await authClient.getSession()

export const mastraClient = new MastraClient({
  baseUrl: 'http://localhost:4111',
  headers: {
    Authorization: `Bearer ${session.data?.session.token}`,
  },
})

Consultez le SDK client Mastra pour davantage d’options de configuration.

Effectuer des requêtes authentifiées

React

src/components/test-agent.tsx

import { mastraClient } from '../lib/mastra-client'

export const TestAgent = () => {
  async function handleClick() {
    const agent = mastraClient.getAgent('weatherAgent')

    const response = await agent.generate('Weather in London')

    console.log(response)
  }

  return <button onClick={handleClick}>Test Agent</button>
}

cURL

curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-token>" \
  -d '{
    "messages": "Weather in London"
  }'

Dépannage

• Réponse 401 à chaque requête : vérifiez que le gestionnaire Better Auth est monté et que votre application peut créer une session valide. Assurez-vous que le client envoie soit un cookie de session, soit un en-tête Authorization: Bearer <signed-token>.
• Cookies non envoyés entre origines : définissez credentials: "include" dans MastraClient, puis configurez server.cors avec l'origine de votre frontend et credentials: true.
• Jeton Bearer rejeté : veillez à transmettre le jeton de session signé complet, obtenu depuis authClient.getSession(), et non un jeton brut ou non signé.
• Problèmes d'URL de base : définissez baseURL dans betterAuth({ ... }) ou définissez BETTER_AUTH_URL.
• Erreurs de connexion à la base de données : vérifiez DATABASE_URL et la configuration du Provider de base de données.