Better Auth

@mastra/auth-better-auth パッケージは、Better Auth を使用した Mastra の認証を提供します。Better Auth インスタンスを使用して受信リクエストを検証し、server.auth オプションで Mastra サーバーと統合します。

前提条件

この例では Better Auth を使用します。Better Auth インスタンスが設定され、環境変数がセットされていることを確認してください。

.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://...

注記

Better Auth では、セキュリティと安定性のために baseURL を明示的に設定する（または BETTER_AUTH_URL を使用する）ことを推奨しています。

Better Auth のハンドラーをまだマウントしていない場合（アプリでユーザーのサインインやセッションの作成を可能にするため）、Better Auth のインストールガイドに従って /api/auth/* ルート（または設定したベースパス）をマウントしてください。

インストール

@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

使用例

まず、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,
})

次に、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,
  },
})

利用可能なすべての設定オプションについては、MastraAuthBetterAuth を参照してください。

カスタム認可

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

ルート設定

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

マッチングルール

• public と protected には、完全一致パス、ワイルドカードパターン（/api/* など）、パスパラメーター（/users/:id など）を指定できます。
• メソッド固有のルールには、["/api/agents", ["GET", "POST"]] のようなタプルを使用します。
• ルートが public と protected の両方に一致する場合は public が優先され、認証は不要です。
• どちらにも一致しない場合、ルートはデフォルトで保護対象として扱われます（ルートに requiresAuth: false が明示的に指定されている場合を除きます）。

クライアント側の設定

認証を有効にすると、Mastra の組み込みルートへのリクエストに認証が必要になります。つまり、実際には Better Auth の設定で認証済みリクエストに使用する認証情報をクライアントから送信する必要があります。

Cookie セッション（推奨）

Better Auth の設定で Cookie を使用する場合は、認証情報を送信するようにクライアントを設定します。クロスオリジンリクエスト（たとえば、:3000 の Next.js から :4111 の Mastra を呼び出す場合）では、Mastra サーバーで CORS の認証情報を有効にします。

src/mastra/index.ts

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

次に、認証情報を含めるようにクライアントを設定します。

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

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

API を直接呼び出す場合も、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' }),
})

Bearer トークン

署名済みセッショントークンを Bearer トークンとして渡せます。Better Auth のクライアントセッションから取得し、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}`,
  },
})

その他の設定オプションについては、Mastra Client SDK を参照してください。

認証済みリクエストの送信

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

トラブルシューティング

• すべてのリクエストで 401 が発生する: Better Auth のハンドラーがマウントされ、アプリで有効なセッションを作成できることを確認します。クライアントがセッション Cookie または Authorization: Bearer <signed-token> ヘッダーのいずれかを送信していることを確認してください。
• クロスオリジンで Cookie が送信されない: MastraClient で credentials: "include" を設定し、フロントエンドのオリジンと credentials: true を指定して server.cors を設定します。
• Bearer トークンが拒否される: 生のトークンや未署名のトークンではなく、（authClient.getSession() から取得した）完全な署名済みセッショントークンを渡していることを確認します。
• ベース URL の問題: betterAuth({ ... }) で baseURL を設定するか、BETTER_AUTH_URL を設定します。
• DB 接続エラー: DATABASE_URL とデータベース Provider の設定を確認します。