# 使用以太坊 (SIWE) 登录 Scaffold-ETH 2 ## 先决条件检查当前工作目录中是否直接存在“./packages/nextjs/scaffold.config.ts”（不搜索子目录）。如果它不存在，则这不是 Scaffold-ETH 2 项目。首先按照中的说明对其进行搭建。如果存在，则直接继续构建。 ## 概述 [使用以太坊登录 (SIWE / EIP-4361)]() 允许用户通过使用以太坊钱包签署标准化消息来对 Web 应用程序进行身份验证。用户通过加密签名证明地址的所有权，而不是用户名/密码或 OAuth。服务器验证它并创建一个会话——基本身份验证不需要数据库。此技能涵盖使用 [viem 的本机 SIWE 实用程序]() 和 [iron-session]() 将 SIWE 集成到 SE-2 项目中，以进行基于 cookie 的加密会话。该技能重点关注 SE-2 集成细节和陷阱，而不是完整的参考。对于此处未涵盖的任何内容，请参阅 [EIP-4361 规范]() 或 [viem SIWE 文档]()。 ## 依赖关系将“iron-session”添加到 nextjs 工作区以进行基于加密 cookie 的会话管理：纱线工作区@se-2/nextjs 添加铁会话其他所有内容（viem、wagmi、RainbowKit）均已包含在 SE-2 中。 Viem 原生提供所有 SIWE 实用程序 — **不要安装`siwe` npm 包**。 ### 环境变量添加到“packages/nextjs/.env.local”： IRON_SESSION_SECRET=your_secret_key_at_least_32_characters_long 在开发过程中，代码可以回退到硬编码的开发秘密。 **在生产中，必须将其设置**为随机的 32+ 字符串。生成一个： openssl 兰德-base64 32 ## SIWE 身份验证流程该流程遵循标准 EIP-4361 模式，具有三个 API 路由： 1. 客户端：GET /api/siwe/nonce → 服务器生成随机nonce，存储在session中 2. 客户端：创建 SIWE 消息 → 使用 viem 的 createSiweMessage 和随机数 3.客户端：钱包签名消息→来自wagmi的signMessageAsync 4. 客户端：POST /api/siwe/verify → 服务器验证签名+随机数+域名 5. 服务器：创建经过身份验证的会话→通过iron-session加密cookie 6. 客户端：GET /api/siwe/session → 检查会话是否处于活动状态 7. 客户端：DELETE /api/siwe/session → 注销（销毁会话） ### 为什么随机数优先？随机数可防止重放攻击。服务器生成随机数，将其存储在会话 cookie 中，并且客户端必须在 SIWE 消息中包含该确切的随机数。在验证过程中，服务器会检查随机数是否匹配。验证后，随机数将被清除，因此无法重复使用。 ## 实施 ### 会话配置（`packages/nextjs/utils/siwe.ts`）这是核心会话设置。它配置iron-session并提供帮助实用程序： // packages/nextjs/utils/siwe.ts — 根据您的需求调整会话选项从“iron-session”导入{SessionOptions}； // 会话数据存储在加密的cookie中导出类型 SiweSessionData = { 随机数？：字符串；地址？：字符串； chainId？：数字；已登录：布尔值； signedInAt？：字符串； }; 导出 const defaultSession: SiweSessionData = { 已登录：假， }; 函数 getSessionPassword(): 字符串 { const Secret = process.env.IRON_SESSION_SECRET； if (secret && Secret.length >= 32) 返回秘密； if (process.env.NODE_ENV === "生产") { 抛出新的错误（ “必须在生产环境中设置 IRON_SESSION_SECRET（32 个以上字符）”，）； } // 仅开发后备返回“complex_password_at_least_32_characters_long_for_dev”； } 导出常量会话选项：会话选项= { 密码：getSessionPassword(), cookieName: "siwe-session", cookie选项：{ httpOnly：正确， sameSite：“宽松”，安全：process.env.NODE_ENV ===“生产”， maxAge: 7 * 24 * 60 * 60, // 7 天 — 根据需要进行调整 }, }; // 经过身份验证的会话的类型保护导出函数 isAuthenticated( 会话：SiweSessionData， ): 会话是 SiweSessionData & { 地址: 字符串;链 ID: 数字 } { return session.isLoggedIn && !!session.address && !!session.chainId; } ### SIWE 配置（`packages/nextjs/utils/siwe.config.ts`）可调参数的单独配置： // 包/nextjs/utils/siwe.config.ts 常量 siweConfig = { 会话持续天数：7，消息过期分钟：10，声明：“使用以太坊登录应用程序。”, 作为常量；导出默认的siweConfig；导出 const { sessionDurationDays, messageExpirationMinutes, 语句 } = siwe配置； ### API 路由：Nonce (`packages/nextjs/app/api/siwe/nonce/route.ts`) 生成加密随机数并将其存储在会话中： // 包/nextjs/app/api/siwe/nonce/route.ts 从“next/server”导入{NextResponse}；从“iron-session”导入{ getIronSession }；从“next/headers”导入{cookies}；从“viem/siwe”导入{generateSiweNonce}；从“~~/utils/siwe”导入 { SiweSessionData, defaultSession, sessionOptions }; 导出异步函数 GET() { 尝试{ const 会话 = 等待 getIronSession( 等待 cookies(), 会话选项，）； // 重置会话并生成新的随机数 session.isLoggedIn = defaultSession.isLoggedIn; 会话地址=未定义； session.chainId = 未定义； session.signedInAt = 未定义； session.nonce =generateSiweNonce(); 等待会话.save(); 返回 NextResponse.json({ nonce: session.nonce }); } 捕获（错误）{ console.error("随机数生成错误：", error); 返回 NextResponse.json( { error: "生成随机数失败" }, {状态：500}，）； } } ### API 路由：验证 (`packages/nextjs/app/api/siwe/verify/route.ts`) 最复杂的路线 - 验证签名的 SIWE 消息： // 包/nextjs/app/api/siwe/verify/route.ts 从“next/server”导入{ NextRequest, NextResponse }；从“iron-session”导入{ getIronSession }；从“next/headers”导入{cookies}；从“viem”导入{ type Chain, createPublicClient, http }; 从“viem/siwe”导入 { parseSiweMessage, verifySiweMessage }; 导入{ 主网，多边形, 乐观，任意，基地, 灵知，滚动, zk同步，塞波利亚, 安全帽， } 来自“viem/chains”；从“~~/utils/siwe”导入 { SiweSessionData, sessionOptions }; // 添加/删除您的应用程序支持的链 - ERC-6492 智能钱包验证所需 const SUPPORTED_CHAINS: 记录<编号，链> = { [mainnet.id]：主网， [polygon.id]：多边形， [optimism.id]：乐观， [arbitrum.id]：仲裁， [base.id]：基础， [gnosis.id]：gnosis， [scroll.id]：滚动， [zkSync.id]：zkSync， [sepolia.id]：sepolia， [hardhat.id]：安全帽， }; 导出异步函数 POST(req: NextRequest) { 尝试{ const 会话 = 等待 getIronSession( 等待 cookies(), 会话选项，）； const { 消息，签名 } = wait req.json(); if (!message || !signature) { 返回 NextResponse.json( { 错误：“缺少消息或签名”}， {状态：400}，）； } const StoredNonce = session.nonce; 如果（！storedNonce）{ 返回 NextResponse.json( { 错误：“未找到随机数。首先请求 /api/siwe/nonce。” }, {状态：400}，）； } const parsedMessage = parseSiweMessage(消息); // 安全：根据主机标头验证域。在反向代理后面的生产中， // 确保主机正确转发，或替换为硬编码的预期域。 const ExpectedDomain = req.headers.get("主机"); if (!expectedDomain) { 返回 NextResponse.json( { 错误：“缺少主机标头”}， {状态：400}，）； } // 为链创建客户端，支持ERC-6492（智能钱包）验证 const chainId = parsedMessage.chainId; const 链 = 链 ID ? SUPPORTED_CHAINS[chainId] ：未定义；如果（！链）{ 返回 NextResponse.json( { 错误：`不支持的链：${chainId}` }, {状态：400}，）； } const client = createPublicClient({ 链, 传输: http() }); const isValid = 等待 verifySiweMessage(客户端, { 留言，签名, 随机数：存储的随机数，域：预期域， }); 如果（！isValid）{ 返回 NextResponse.json( { error: "签名验证失败" }, {状态：401}，）； } // 创建经过身份验证的会话 session.isLoggedIn = true; session.address = parsedMessage.address; session.chainId = chainId; session.signedInAt = new Date().toISOString(); 会话.nonce = 未定义; // 清除随机数——一次性使用等待会话.save(); 返回 NextResponse.json({ 好的：是的，地址：会话.地址， chainId: 会话.chainId, }); } 捕获（错误）{ console.error("SIWE 验证错误：", error); return NextResponse.json({ error: "验证失败" }, { status: 500 }); } } ### API 路由：会话 (`packages/nextjs/app/api/siwe/session/route.ts`) 检查并销毁会话： // 包/nextjs/app/api/siwe/session/route.ts 从“next/server”导入{NextResponse}；从“iron-session”导入{ getIronSession }；从“next/headers”导入{cookies}；从“~~/utils/siwe”导入 { SiweSessionData, defaultSession, sessionOptions }; 导出异步函数 GET() { const 会话 = 等待 getIronSession( 等待 cookies(), 会话选项，）； if (session.isLoggedIn) { 返回 NextResponse.json({ 已登录： true，地址：会话.地址， chainId: 会话.chainId, 签名：会话.签名， }); } 返回 NextResponse.json(defaultSession); } 导出异步函数 DELETE() { const 会话 = 等待 getIronSession( 等待 cookies(), 会话选项，）；会话.destroy(); 返回 NextResponse.json(defaultSession); } ### 自定义挂钩 (`packages/nextjs/hooks/useSiwe.ts`) `useSiwe` 钩子封装了整个身份验证流程： // packages/nextjs/hooks/useSiwe.ts — 语法参考，适应您的需求从“react”导入{ useCallback、useEffect、useRef、useState }；从“wagmi”导入 { useAccount, useSignMessage }; 从“viem/siwe”导入{createSiweMessage}；从“~~/utils/siwe.config”导入{messageExpirationMinutes，语句}；类型 SiweState = { 地址：字符串|不明确的; 链 ID: 数字 |不明确的; 已登录：布尔值；正在加载：布尔值；错误：字符串|不明确的; siweMessage: 字符串 |不明确的; 签名：字符串|不明确的; }; 导出函数 useSiwe() { const { 地址：connectedAddress、chainId、isConnected } = useAccount(); const { signMessageAsync } = useSignMessage(); const hasSeenWalletConnected = useRef(false); const [状态，setState] = useState({ 地址：未定义，链 ID：未定义，已登录：假，正在加载：true，错误：未定义， siweMessage：未定义，签名：未定义， }); // 检查挂载上的会话 const checkSession = useCallback(async () => { 尝试{ const res = wait fetch("/api/siwe/session"); const 数据 = 等待 res.json(); setState((上一个) => ({ ...上一页， isSignedIn: data.isLoggedIn ??假的，地址：数据.地址， chainId: 数据.chainId, 签名：data.signedInAt，正在加载：假， })); } 抓住 { setState((上一个) => ({ ...上一个, isLoading: false })); } }, []); 使用效果（（）=> { 检查会话（）； }, [检查会话]); // 钱包断开或地址更改时自动注销使用效果（（）=> { 如果（已连接）{ hasSeenWalletConnected.current = true; } if (!isConnected && hasSeenWalletConnected.current && state.isSignedIn) { // 钱包连接后断开连接 — 注销 fetch("/api/siwe/session", { 方法: "删除" }).then(() => { setState((上一个) => ({ ...上一页，已登录：假，地址：未定义，链 ID：未定义， siweMessage：未定义，签名：未定义， })); }); } }, [isConnected, state.isSignedIn]); const signIn = useCallback(async () => { if (!connectedAddress || !chainId) { setState((prev) => ({ ...prev, 错误:“钱包未连接” })); 返回； } setState((prev) => ({ ...prev, isLoading: true, 错误: 未定义 })); 尝试{ // 1. 获取随机数 const nonceRes = wait fetch("/api/siwe/nonce"); const { nonce } = wait nonceRes.json(); // 2. 创建 SIWE 消息 const now = new Date(); const 消息 = createSiweMessage({ 域：window.location.host，地址：连接地址，链 ID, 随机数， uri：窗口.位置.原点，版本：“1”，声明，发布时间：现在，过期时间：新日期（ now.getTime() + messageExpirationMinutes * 60 * 1000, ), }); // 3. 使用钱包签名 const 签名 = 等待signMessageAsync({ 消息 }); // 4. 在服务器上验证 const verifyRes = 等待 fetch("/api/siwe/verify", { 方法：“POST”， headers: { "Content-Type": "application/json" }, body: JSON.stringify({ 消息, 签名 }), }); 如果（！verifyRes.ok）{ const errorData = 等待 verifyRes.json(); throw new Error(errorData.error || "验证失败"); } const 结果 = 等待 verifyRes.json(); setState((上一个) => ({ ...上一页，已登录：正确，地址：结果.地址， chainId: 结果.chainId, siwe消息：消息， signedInAt: new Date().toISOString(), 正在加载：假， })); } 捕获 (e) { setState((上一个) => ({ ...上一页，正在加载：假，错误：e实例错误？ e.message : "登录失败", })); } }, [connectedAddress, chainId, signMessageAsync]); const signOut = useCallback(async () => { 等待 fetch("/api/siwe/session", { 方法: "删除" }); setState((上一个) => ({ ...上一页，已登录：假，地址：未定义，链 ID：未定义， siweMessage：未定义，签名：未定义，错误：未定义， })); }, []); 返回{ ...状态， isWalletConnected: 已连接, 连接地址，登录，退出，检查会话， }; } **关键钩子行为：** * 检查挂载时的会话，以便刷新页面保留身份验证状态 * 当钱包断开连接或地址更改时自动退出 * 使用 `hasSeenWalletConnected` 引用来避免初始页面加载时错误的自动注销（当钱包异步重新连接时） * 单独的“connectedAddress”（当前钱包）与“address”（经过身份验证的会话）——如果用户切换钱包，这些可能会有所不同 ## 陷阱和陷阱 **每次尝试登录之前必须重新获取随机数。**随机数是一次性的并存储在服务器端。如果用户取消签名或请求失败，他们需要一个新的随机数。 “signIn”函数通过始终首先获取新的随机数来处理此问题。 **域验证对于安全性至关重要。** 验证路由会检查 SIWE 消息的域是否与“Host”标头匹配。在反向代理后面的生产中，请确保正确转发“Host”标头，否则域验证将失败。 **消息过期窗口。** SIWE 消息包括“expirationTime”（默认值：创建后 10 分钟）。如果用户签名时间过长，验证就会失败。这可以在 `siwe.config.ts` 中配置。 **ERC-6492 智能钱包支持。** Viem 的 `verifySiweMessage` 自动支持 [ERC-6492]() 签名，这意味着智能合约钱包（Safe、Argent 等）可以开箱即用。验证路由为签名者链创建一个公共客户端，以实现智能钱包签名的链上验证。 **验证路径中的“SUPPORTED_CHAINS”必须包含您的应用程序支持的所有链。**如果用户从不在地图中的链进行签名，则验证将被拒绝并显示 400 错误。添加您的 SE-2 项目目标的任何链。 **钱包更改时自动注销时间。** 挂钩监视“isConnected”并在钱包断开连接时注销。但在页面刷新时，钱包会异步重新连接，导致短暂的“isConnected: false”状态。 `hasSeenWalletConnected` 引用可防止触发错误注销。 **会话与钱包地址不匹配。**登录后，用户可以切换到不同的钱包地址而无需注销。该钩子公开了“address”（会话）和“connectedAddress”（当前钱包）——如果您需要检测这种不匹配并提示重新身份验证，请对它们进行比较。 **铁会话 cookie 大小限制。** Cookie 限制为 ~4KB。会话数据很小（地址、chainId、时间戳），因此这很少是问题，但不要尝试在会话中存储大量有效负载。 **服务器端会话检查。** 要保护 API 路由或服务器组件，请使用具有相同 `sessionOptions` 的 `getIronSession` 并检查 `session.isLoggedIn`。不要仅依赖客户端检查来进行敏感操作。该钩子返回以下属性：物业 |类型 |描述 ---|---|--- `已登录` | `布尔值` |用户是否有活动的 SIWE 会话 `地址` | `字符串|未定义` |经过验证的钱包地址 `链ID` | `数字|未定义` |签名消息中的链 ID `signInAt` | `字符串|未定义` |登录的 ISO 时间戳 `正在加载` | `布尔值` |登录/会话检查期间的加载状态 `错误` | `字符串|未定义` |上次操作的错误消息 `siwe消息` | `字符串|未定义` |已签名的原始 SIWE 消息 `isWalletConnected` | `布尔值` |当前是否连接任何钱包 `连接地址` | `字符串|未定义` |当前钱包地址（可能与会话不同） `登录` | `() => Promise` |启动 SIWE 登录流程 `退出` | `() => Promise` |销毁会话并退出 `检查会话` | `() => Promise` |手动重新检查会话状态 ## 如何测试 1. 启动前端：`yarn start` 2. 连接钱包 — MetaMask、Coinbase 钱包和 Burner 钱包都支持 SIWE 使用的“personal_sign” 3. 单击“登录” — 查看钱包弹出窗口中的 SIWE 消息，确认 4. 会话在页面刷新后仍然存在（加密的 cookie） 5. 断开钱包连接或点击“退出”结束会话 ## 生产： 1. 在生产中，确保将“IRON_SESSION_SECRET”环境变量设置为安全的 32+ 字符随机字符串

合同

包含技能