Simple Auth

SimpleAuth 类使用基本的令牌到用户映射提供基于令牌的身份验证。它包含在 @mastra/core/server 中，适用于开发、测试和基本的 API key 身份验证场景。

使用场景

• 本地开发和测试
• 简单的 API key 身份验证
• 在集成完整身份提供商之前进行原型开发
• 使用静态令牌的内部服务

安装

SimpleAuth 包含在 @mastra/core 中，无需额外安装包。

import { SimpleAuth } from '@mastra/core/server'

用法示例

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { SimpleAuth } from '@mastra/core/server'

// Define your user type
type User = {
  id: string
  name: string
  role: 'admin' | 'user'
}

export const mastra = new Mastra({
  server: {
    auth: new SimpleAuth<User>({
      tokens: {
        'sk-admin-token-123': {
          id: 'user-1',
          name: 'Admin User',
          role: 'admin',
        },
        'sk-user-token-456': {
          id: 'user-2',
          name: 'Regular User',
          role: 'user',
        },
      },
    }),
  },
})

配置选项

选项	类型	必填	描述
tokens	Record<string, TUser>	是	令牌到用户对象的映射
headers	string | string[]	否	要检查令牌的其他头
name	string	否	用于日志的提供商名称
authorizeUser	(user, request) => boolean	否	自定义授权函数
protected	(RegExp | string)[]	否	需要身份验证的路径
public	(RegExp | string)[]	否	绕过身份验证的路径

默认头

SimpleAuth 默认检查这些头：

• Authorization（带或不带 Bearer 前缀）
• X-Playground-Access

使用 headers 选项添加自定义头：

new SimpleAuth({
  tokens: {/* ... */},
  headers: ['X-API-Key', 'X-Custom-Auth'],
})

发起已认证请求

在 Authorization 头中包含你的令牌：

curl -X POST http://localhost:4111/api/agents/myAgent/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-admin-token-123" \
  -d '{"messages": "Hello"}'

或不带 Bearer 前缀：

curl -X POST http://localhost:4111/api/agents/myAgent/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: sk-admin-token-123" \
  -d '{"messages": "Hello"}'

自定义授权

添加基于角色或自定义的授权逻辑：

import { SimpleAuth, getWebRequest } from '@mastra/core/server'

new SimpleAuth<User>({
  tokens: {
    'sk-admin-token': { id: '1', name: 'Admin', role: 'admin' },
    'sk-user-token': { id: '2', name: 'User', role: 'user' },
  },
  authorizeUser: (user, request) => {
    const webRequest = getWebRequest(request)
    const path = webRequest ? new URL(webRequest.url).pathname : ''

    // Only admins can access /admin routes
    if (path.includes('/admin')) {
      return user.role === 'admin'
    }
    return true
  },
})

环境变量

对于类似生产的设置，从环境变量加载令牌：

const tokens: Record<string, User> = {}

// Load from environment
const adminToken = process.env.ADMIN_API_KEY
if (adminToken) {
  tokens[adminToken] = { id: 'admin', name: 'Admin', role: 'admin' }
}

const userToken = process.env.USER_API_KEY
if (userToken) {
  tokens[userToken] = { id: 'user', name: 'User', role: 'user' }
}

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

配合 MastraClient

使用你的令牌配置客户端：

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

const client = new MastraClient({
  baseUrl: 'http://localhost:4111',
  headers: {
    Authorization: 'Bearer sk-admin-token-123',
  },
})

const agent = client.getAgent('myAgent')
const response = await agent.generate('Hello')

限制

SimpleAuth 以简单为目标设计，而非生产级安全：

• 令牌存储在内存中
• 没有令牌过期或刷新
• 没有加密验证
• 所有令牌必须在启动时已知

对于生产应用，请考虑使用 JWT、Clerk、Auth0 或其他身份提供商。