將 RainbowKit SIWE 遷移到 NextAuth v5

RainbowKit 的 @rainbow-me/rainbowkit-siwe-next-auth 套件現在支持 NextAuth v5。由於 NextAuth 更改了其伺服器配置 API、會話助手 API 和內部 CSRF 流程，因此這對使用 NextAuth SIWE 適配器的應用程式來說是一次重大升級。

NextAuth.js 現在是一個更廣泛的Auth.js項目的一部分。包名仍然是 next-auth，官方的 NextAuth.js 文檔仍在下一步-auth.js.org 可用。本指南使用您 oggi 安裝的 next-auth 包名稱，並在影響 Cookie 名稱和 v5 API 的地方提及 Auth.js 過渡。

如果您的應用程式目前使用 @rainbow-me/rainbowkit-siwe-next-auth 並且 NextAuth 為 v4，請按照以下步驟操作。

1. 升級依賴項

安裝由 RainbowKit 支援的 NextAuth v5 套件版本。

- npm install next-auth@^4 @rainbow-me/rainbowkit-siwe-next-auth
+ npm install [email protected] @rainbow-me/rainbowkit-siwe-next-auth

2. 更新你的 NextAuth 伺服器配置

NextAuth v5，作為 Auth.js 項目的一部分記錄，使用 NextAuthConfig 類型、Credentials 提供者匯出以及從 NextAuth(authOptions) 返回的幫助程序。

Auth.js 建議使用 AUTH_URL 和 AUTH_SECRET 環境變量。如果你已經有使用 NEXTAUTH_URL 和 NEXTAUTH_SECRET 的 NextAuth v4 部署，遷移期間保持這些作為備選。

- import type { NextAuthOptions } from 'next-auth';
- import CredentialsProvider from 'next-auth/providers/credentials';
+ import NextAuth from 'next-auth';
+ import type { NextAuthConfig } from 'next-auth';
+ import Credentials from 'next-auth/providers/credentials';

- export const authOptions: NextAuthOptions = {
+ export const authOptions: NextAuthConfig = {
    providers: [
-     CredentialsProvider({
+     Credentials({
        name: 'Ethereum',
        credentials: {
          message: { label: 'Message', type: 'text' },
          signature: { label: 'Signature', type: 'text' },
        },
        async authorize(credentials) {
          /* Validate SIWE message, domain, nonce, and signature */
        },
      }),
    ],
+   secret: process.env.AUTH_SECRET ?? process.env.NEXTAUTH_SECRET,
  };
+
+ export const { handlers, auth, signIn, signOut } = NextAuth(authOptions);

對於應用程式路由的處理器，匯出返回的 GET 和 POST 處理器。

export const { GET, POST } = handlers;

對於頁面路由 API 路由，將你的 v5 authOptions 傳遞給 NextAuth。

export default NextAuth(authOptions);

3. 更新伺服器端會話讀取

如果你在 getServerSideProps 中讀取已驗證的地址，請從 v4 會話幫助程序切換到 v5 使用的配置匯出的 auth 幫助程序。

分別傳遞 req 和 res。將完整的 GetServerSidePropsContext 對象傳遞給 auth 不受 v5 重載支持。

- import { getServerSession } from 'next-auth';
- import { authOptions } from '../auth';
+ import { auth } from '../auth';

  export const getServerSideProps: GetServerSideProps = async (context) => {
-   const session = await getServerSession(
-     context.req,
-     context.res,
-     authOptions,
-   );
+   const session = await auth(context.req, context.res);

    return {
      props: {
        session,
      },
    };
  };

4. 更新 SIWE nonce 驗證

在 v4 實現中，RainbowKit 示例將 SIWE nonce 與 authorize 中的 getCsrfToken 進行比較。

在 NextAuth v5 中，Credentials 提供者在 NextAuth 驗證請求的 CSRF cookie 後，接收已驗證的 CSRF token 作為 credentials.csrfToken。

- import { getCsrfToken } from 'next-auth/react';

- if (
-   siweMessage.nonce !==
-   (await getCsrfToken({ req: { headers: req.headers } }))
- ) {
-   return null;
- }
+ const csrfToken =
+   credentials && 'csrfToken' in credentials
+     ? credentials.csrfToken
+     : undefined;
+
+ if (siweMessage.nonce !== csrfToken) {
+   return null;
+ }

NextAuth v5 內部 cookie 使用 Auth.js authjs 前綴，包括 authjs.csrf-token 或 __Host-authjs.csrf-token，根據安全 cookie 設置而定。對於 RainbowKit 的 SIWE 流程，你不需要自行解析這些 cookie。

5. 在會話中返回已驗證地址

如果你的應用讀取 session.address，持續將 JWT 主體映射到你的 NextAuth 回呼中的會話。

callbacks: {
  async session({ session, token }) {
    session.address = token.sub;
    session.user = {
      ...session.user,
      name: token.sub,
    };
    return session;
  },
},

你可以在 with-next-siwe-next-auth 範例中查看完整的 NextAuth v5 設置。

如果你也在升級舊版的 RainbowKit SIWE 集成，請查看 0.5.0 變更日誌了解 viem/siwe 遷移，以及 0.3.0 變更日誌了解早期 getCsrfToken 請求形狀的更改。