身份验证SDK
用于Next.js应用程序的轻量级模块化身份验证SDK，具有 模型上下文协议（MCP） 支持AI代理身份验证。
特性
- ✅ 多个身份验证提供程序
- 谷歌、脸书、GitHub、GitLab、领英、微软、Spotify、Discord、Twitch、Epic Games OAuth 2.0 - 支持重新发送和Nodemailer的电子邮件魔术链接（无密码） - 带有6位验证码的双因素电子邮件身份验证（2FA） - 可定制的React电子邮件模板 - 为所有OAuth提供者提供PKCE支持 - 可扩展的提供商系统
- ✅ MCP（模型上下文协议）集成
- AI代理委托身份验证 - 有范围、有时间限制的访问令牌 - 与Vercel AI SDK兼容
- ✅ 会话管理
- 基于JWT的会议 - 安全的、仅支持httpOnly的Cookie - 数据库适配器支持（Prisma）
- ✅ React集成
- useAuth() 钩子 - AuthProvider 上下文 - 服务器端会话助手
- ✅ 安全第一
- OAuth流的CSRF保护 - 已签名的JWT代币 - 令牌撤销支持 - 使用Zod进行输入验证
- ✅ Next.js 15+应用路由器
- 服务器组件 - API路线 - 流媒体支持
快速开始
安装
npm install auth-sdk基本设置
// app/api/auth/config.ts
import { google, email } from 'auth-sdk';
export const authConfig = {
provider: google({
clientId: process.env.GOOGLE_CLIENT_ID!,
clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
redirectUri: 'http://localhost:3000/api/auth/callback/google',
}),
secret: process.env.AUTH_SECRET!,
};环境变量
AUTH_SECRET=your-secret-key-min-32-characters-long
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret使用示例
Google OAuth登录
// app/api/auth/signin/google/route.ts
import { authenticate } from 'auth-sdk';
import { googleAuthConfig } from '../config';
export async function GET(request: Request) {
const result = await authenticate(googleAuthConfig, request);
if (result.redirectUrl) {
return Response.redirect(result.redirectUrl);
}
}电子邮件魔术链接
重新发送
// app/api/auth/signin/email/route.ts
import { authenticate, email } from 'auth-sdk';
const emailConfig = {
provider: email({
from: 'noreply@yourdomain.com',
service: {
type: 'resend',
apiKey: process.env.RESEND_API_KEY!
},
appName: 'My App',
companyName: 'My Company'
}),
secret: process.env.AUTH_SECRET!,
};
export async function POST(request: Request) {
const { email } = await request.json();
const result = await authenticate(emailConfig, request);
return Response.json({ success: !result.error });
}使用Nodemailer（SMTP）
const emailConfig = {
provider: email({
from: 'noreply@yourdomain.com',
service: {
type: 'nodemailer',
server: 'smtp.gmail.com:587',
auth: {
user: process.env.GMAIL_USER!,
pass: process.env.GMAIL_APP_PASSWORD!
}
}
}),
secret: process.env.AUTH_SECRET!,
};双因素电子邮件身份验证（2FA）
通过电子邮件发送6位验证码，以增强安全性。
重新发送
// app/api/auth/signin/twofa/route.ts
import { authenticate, twofa } from 'auth-sdk';
const twofaConfig = {
provider: twofa({
from: 'noreply@yourdomain.com',
service: {
type: 'resend',
apiKey: process.env.RESEND_API_KEY!
},
appName: 'My App',
expirationMinutes: 5 // Code expires in 5 minutes
}),
secret: process.env.AUTH_SECRET!,
};
export async function GET(request: Request) {
// Step 1: Send code (when ?email=user@example.com)
// Step 2: Verify code (when ?identifier=xxx&code=123456)
const result = await authenticate(twofaConfig, request);
if (result.redirectUrl) {
return Response.redirect(result.redirectUrl);
}
if (result.session) {
// Code verified, session created
return Response.json({ success: true });
}
return Response.json({ error: result.error });
}使用Nodemailer（SMTP）
const twofaConfig = {
provider: twofa({
from: 'noreply@yourdomain.com',
service: {
type: 'nodemailer',
server: 'smtp.gmail.com:587',
auth: {
user: process.env.GMAIL_USER!,
pass: process.env.GMAIL_APP_PASSWORD!
}
}
}),
secret: process.env.AUTH_SECRET!,
};特征：
- 加密安全的6位代码
- 短期代币（默认5分钟）
- 支持重试的一次性代码
- 漂亮的电子邮件模板
- 自动清理
看 2FA提供商文档 和 2FA实施指南 以获取完整的文档。
获取会话
// app/api/auth/session/route.ts
import { getSession } from 'auth-sdk';
export async function GET(request: Request) {
const session = await getSession(request, process.env.AUTH_SECRET!);
return Response.json({ session });
}React挂钩
'use client';
import { useAuth } from 'auth-sdk/hooks';
export function ProfileButton() {
const { session, loading, signOut } = useAuth();
if (loading) return
Loading...
;
if (!session) return Sign In;
return (
{session.user.email}
Sign Out
);
}MCP（AI代理身份验证）
使AI代理能够作为具有范围、时间限制访问权限的用户进行身份验证。
创建MCP工具
// app/api/mcp/route.ts
import { createMCPTools } from 'auth-sdk/mcp';
const mcpTools = createMCPTools({
secret: process.env.AUTH_SECRET!,
});
export async function POST(request: Request) {
const { tool, args } = await request.json();
const result = await mcpTools[tool].execute(args);
return Response.json(result);
}代理登录
// AI agent logs in as user
const response = await fetch('/api/mcp', {
method: 'POST',
body: JSON.stringify({
tool: 'agent_login',
args: {
userId: 'user-123',
scopes: ['debug', 'read'],
agentId: 'claude-assistant',
expiresIn: '15m'
}
})
});
const { token } = await response.json();使用代理令牌
// Protected route
import { verifyAgentToken } from 'auth-sdk';
export async function GET(request: Request) {
const session = await verifyAgentToken(request, process.env.AUTH_SECRET!);
if (!session || !session.scopes?.includes('read')) {
return new Response('Unauthorized', { status: 401 });
}
return Response.json({ data: 'Protected data' });
}AI SDK集成
import { generateText } from 'ai';
import { createMCPTools } from 'auth-sdk/mcp';
const mcpTools = createMCPTools({ secret: process.env.AUTH_SECRET! });
const { text } = await generateText({
model: openai('gpt-4'),
tools: mcpTools,
prompt: 'Login as user-123 with debug scope and check their activity'
});数据库适配器
使用Prisma适配器进行会话持久化。
import { prismaAdapter } from 'auth-sdk/adapters/prisma';
import { PrismaClient } from '@prisma/client';
const prisma = new PrismaClient();
const authConfig = {
provider: google({ /* ... */ }),
secret: process.env.AUTH_SECRET!,
adapter: prismaAdapter(prisma), // Enable DB sessions
};API 参考
核心功能
authenticate(config, request?, payload?)
支持OAuth、电子邮件和MCP的主要身份验证功能。
参数：
config: AuthConfig-身份验证配置request?: Request-HTTP请求（用于OAuth/电子邮件）payload?: MCPLoginPayload-MCP代理登录有效负载
退货： Promise
interface AuthenticateResult {
session?: Session;
error?: string;
redirectUrl?: string;
}getSession(request, secret)
从请求Cookie获取当前会话。
参数：
request: Request-带有Cookie的HTTP请求secret: string-JWT签名秘密
退货： Promise
signOut(request, config)
注销用户并清除会话。
参数：
request: Request-HTTP请求config: AuthConfig-身份验证配置
退货： Promise
verifyAgentToken(request, secret)
验证授权标头中的MCP代理令牌。
参数：
request: Request-HTTP请求secret: string-JWT签名秘密
退货： Promise
提供商
google(options)
谷歌OAuth提供商。
google({
clientId: string;
clientSecret: string;
redirectUri: string;
scope?: string[]; // Default: ['openid', 'email', 'profile']
})email(options)
电子邮件魔术链接提供商。
email({
server: string; // 'smtp.gmail.com:587'
from: string; // 'noreply@example.com'
auth?: {
user: string;
pass: string;
};
})MCP工具
createMCPTools({ secret, adapter? })
为AI代理创建MCP工具。
退货：
agent_login-以具有范围访问权限的用户身份登录get_session-验证并检索会话信息revoke_token-使令牌无效
React挂钩
useAuth()
访问React组件中的session和auth方法。
const {
session: Session | null;
loading: boolean;
signIn: (email: string) => Promise;
signOut: () => Promise;
refreshSession: () => Promise;
} = useAuth();示例
看 examples/nextjs应用路由器 完整Next.js应用路由器示例的目录，包括：
- Google OAuth登录
- 电子邮件魔术链接登录
- 会话管理
- MCP代理身份验证
- 受保护的路线
- React钩子的使用
运行示例
cd examples/nextjs-app-router
cp .env.example .env.local
# Edit .env.local with your credentials
npm install
npm run dev文档
- CLAUDE.md -架构和实施指南
- API-ROUTES.md -完整的API参考
- MCP-INTEGRATION.md -MCP集成指南
- MVP-Plan.md -实施路线图
- 实施.md -详细的实施文档
建筑
auth-sdk/
├── src/
│ ├── core.ts # Main authentication functions
│ ├── providers/ # OAuth, Email providers
│ │ ├── google.ts
│ │ ├── email.ts
│ │ └── types.ts
│ ├── adapters/ # Database adapters
│ │ ├── prisma.ts
│ │ └── types.ts
│ ├── mcp/ # MCP tools for AI agents
│ │ └── mcp.ts
│ ├── hooks/ # React hooks
│ │ └── useAuth.tsx
│ └── utils/ # Utilities
│ ├── jwt.ts
│ ├── csrf.ts
│ ├── oauth.ts
│ ├── cookie.ts
│ └── tokens.ts
└── examples/
└── nextjs-app-router/ # Complete Next.js example安全
最佳实践
- 使用强大的秘密：至少32个字符
AUTH_SECRET - 启用HTTPS：在生产环境中始终使用HTTPS
- 设置安全Cookie：httpOnly、security、sameSite标志
- 验证输入：所有输入均已Zod验证
- 代币寿命短：MCP令牌将在15分钟后过期
- 基于范围的访问：为代理使用最小范围
- 令牌撤销：使用后撤销代币
生产检查表
- \[\]设置强
AUTH_SECRET（最少32个字符） - \[\]使用生产OAuth凭据
- \[\]配置生产SMTP服务器
- \[\]启用HTTPS/TLS
- \[\]添加速率限制
- \[\]设置错误监控
- \[\]配置数据库适配器
- \[\]检查安全设置
- \[\]添加审核日志记录
- \[\]测试所有身份验证流
TypeScript支持
完全使用TypeScript 5.9+。所有函数和接口都以类型导出。
import type {
AuthConfig,
Session,
Provider,
Adapter,
MCPLoginPayload,
AuthenticateResult,
} from 'auth-sdk';贡献
欢迎投稿！请在提交PR之前阅读我们的投稿指南。
发展
# Clone repository
git clone https://github.com/yourusername/auth-sdk.git
cd auth-sdk
# Install dependencies
npm install
# Build
npm run build
# Run tests (when available)
npm test
# Lint
npm run eslint路线图
完成✅
- \[x\] 核心认证系统
- \[x\] 谷歌OAuth提供商
- \[x\] 电子邮件魔术链接提供商
- \[x\] 会话管理
- \[x\] 用于AI代理的MCP工具
- \[x\] React挂钩
- \[x\] Prisma适配器
- \[x\] Next.js示例应用
- \[x\] 全面的文件
未来🚀
- \[\]其他OAuth提供者（GitHub、微软、推特）
- \[\]凭据提供程序（用户名/密码）
- \[\]多因素身份验证（MFA/2FA）
- \[\]JWT刷新令牌轮换
- \[\]用于会话的Redis适配器
- \[\]限速中间件
- \[\]Webhook支持
- \[\]会话管理的管理UI
- \[\]Vitest单元测试
许可证
ISC许可证-请参阅 许可证 文件以获取详细信息。
鸣谢
创建于♥ 通过 卢卡斯·奥利维拉
灵感来源：
- NextAuth.js -身份验证模式
- Vercel AI SDK -API设计理念
- 模型上下文协议 -AI代理集成
支持
______________________________________________________________________