使用说明

身份验证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 <div>Loading...</div>;
  if (!session) return <a href="/login">Sign In</a>;

  return (
    <div>
      <span>{session.user.email}</span>
      <button onClick={signOut}>Sign Out</button>
    </div>
  );
}

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<AuthenticateResult>

interface AuthenticateResult {
  session?: Session;
  error?: string;
  redirectUrl?: string;
}

`getSession(request, secret)`

从请求Cookie获取当前会话。

参数：

request: Request -带有Cookie的HTTP请求
secret: string -JWT签名秘密

退货： Promise<Session | null>

`signOut(request, config)`

注销用户并清除会话。

参数：

request: Request -HTTP请求
config: AuthConfig -身份验证配置

退货： Promise<void>

`verifyAgentToken(request, secret)`

验证授权标头中的MCP代理令牌。

参数：

request: Request -HTTP请求
secret: string -JWT签名秘密

退货： Promise<Session | null>

提供商

`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<void>;
  signOut: () => Promise<void>;
  refreshSession: () => Promise<void>;
} = 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

安全

最佳实践

使用强大的秘密：至少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代理集成

支持

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

使用说明

身份验证SDK

特性

快速开始

安装

基本设置

环境变量

使用示例

Google OAuth登录

电子邮件魔术链接

重新发送

使用Nodemailer（SMTP）

双因素电子邮件身份验证（2FA）

重新发送

使用Nodemailer（SMTP）

获取会话

React挂钩

MCP（AI代理身份验证）

创建MCP工具

代理登录

使用代理令牌

AI SDK集成

数据库适配器

API 参考

核心功能

authenticate(config, request?, payload?)

getSession(request, secret)

signOut(request, config)

verifyAgentToken(request, secret)

提供商

google(options)

email(options)

MCP工具

createMCPTools({ secret, adapter? })

React挂钩

useAuth()

示例

运行示例

文档

建筑

安全

最佳实践

生产检查表

TypeScript支持

贡献

发展

路线图

完成✅

未来🚀

许可证

鸣谢

支持

相关 MCP

OTP生成服务器

供应链风险分析工具

模型上下文协议服务器

营销自动化平台

捷克出生号码生成器

认证MCP服务器

`authenticate(config, request?, payload?)`

`getSession(request, secret)`

`signOut(request, config)`

`verifyAgentToken(request, secret)`

`google(options)`

`email(options)`

`createMCPTools({ secret, adapter? })`

`useAuth()`