Auth SDK

身份验证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

访问 http://localhost:3000

文档

• 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

安全

最佳实践

1. 使用强大的秘密：至少32个字符 AUTH_SECRET
2. 启用HTTPS：在生产环境中始终使用HTTPS
3. 设置安全Cookie：httpOnly、security、sameSite标志
4. 验证输入：所有输入均已Zod验证
5. 代币寿命短：MCP令牌将在15分钟后过期
6. 基于范围的访问：为代理使用最小范围
7. 令牌撤销：使用后撤销代币

生产检查表

• \[\]设置强 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代理集成

支持

• 📖 文档
• 💬
• 📧 电子邮件

______________________________________________________________________

使用TypeScript和Next.js制作 • 文档 • 示例