Add Passkey (WebAuthn) authentication support

Introduces Passkey (WebAuthn) registration and authentication to both backend and frontend. Backend adds new API endpoints, middleware exceptions, and a PasskeyHelper for credential management using @simplewebauthn/server. Frontend integrates @simplewebauthn/browser, updates login and config pages for Passkey registration and login flows, and adds related UI and controller methods.

packages/napcat-webui-frontend/src/controllers/webui_manager.ts

@@ -212,4 +212,35 @@ export default class WebUIManager {
     );
     return data.data;
   }
+
+  // Passkey相关方法
+  public static async generatePasskeyRegistrationOptions () {
+    const { data } = await serverRequest.post<ServerResponse<any>>(
+      '/auth/passkey/generate-registration-options'
+    );
+    return data.data;
+  }
+
+  public static async verifyPasskeyRegistration (response: any) {
+    const { data } = await serverRequest.post<ServerResponse<any>>(
+      '/auth/passkey/verify-registration',
+      { response }
+    );
+    return data.data;
+  }
+
+  public static async generatePasskeyAuthenticationOptions () {
+    const { data } = await serverRequest.post<ServerResponse<any>>(
+      '/auth/passkey/generate-authentication-options'
+    );
+    return data.data;
+  }
+
+  public static async verifyPasskeyAuthentication (response: any) {
+    const { data } = await serverRequest.post<ServerResponse<any>>(
+      '/auth/passkey/verify-authentication',
+      { response }
+    );
+    return data.data;
+  }
 }

packages/napcat-webui-frontend/src/pages/dashboard/config/webui.tsx

@@ -1,6 +1,7 @@
 import { Input } from '@heroui/input';
+import { Button } from '@heroui/button';
 import { useLocalStorage } from '@uidotdev/usehooks';
-import { useEffect } from 'react';
+import { useEffect, useState } from 'react';
 import { Controller, useForm } from 'react-hook-form';
 import toast from 'react-hot-toast';
 
@@ -14,6 +15,24 @@ import useMusic from '@/hooks/use-music';
 
 import { siteConfig } from '@/config/site';
 import FileManager from '@/controllers/file_manager';
+import WebUIManager from '@/controllers/webui_manager';
+
+// Base64URL to Uint8Array converter
+function base64UrlToUint8Array (base64Url: string): Uint8Array {
+  const base64 = base64Url.replace(/-/g, '+').replace(/_/g, '/');
+  const rawData = window.atob(base64);
+  const outputArray = new Uint8Array(rawData.length);
+  for (let i = 0; i < rawData.length; ++i) {
+    outputArray[i] = rawData.charCodeAt(i);
+  }
+  return outputArray;
+}
+
+// Uint8Array to Base64URL converter
+function uint8ArrayToBase64Url (uint8Array: Uint8Array): string {
+  const base64 = window.btoa(String.fromCharCode(...uint8Array));
+  return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+}
 
 const WebUIConfigCard = () => {
   const {
@@ -35,6 +54,25 @@ const WebUIConfigCard = () => {
     {}
   );
   const { setListId, listId } = useMusic();
+  const [registrationOptions, setRegistrationOptions] = useState<any>(null);
+  const [isLoadingOptions, setIsLoadingOptions] = useState(false);
+
+  // 预先获取注册选项（可以在任何时候调用）
+  const preloadRegistrationOptions = async () => {
+    setIsLoadingOptions(true);
+    try {
+      console.log('预先获取注册选项...');
+      const options = await WebUIManager.generatePasskeyRegistrationOptions();
+      setRegistrationOptions(options);
+      console.log('✅ 注册选项已获取并存储');
+      toast.success('注册选项已准备就绪，请点击注册按钮');
+    } catch (error) {
+      console.error('❌ 获取注册选项失败:', error);
+      toast.error('获取注册选项失败，请重试');
+    } finally {
+      setIsLoadingOptions(false);
+    }
+  };
 
   const reset = () => {
     setWebuiValue('musicListID', listId);
@@ -125,6 +163,122 @@ const WebUIConfigCard = () => {
           />
         ))}
       </div>
+      <div className='flex flex-col gap-2'>
+        <div className='flex-shrink-0 w-full'>Passkey认证</div>
+        <div className='text-sm text-default-400 mb-2'>
+          注册Passkey后，您可以更便捷地登录WebUI，无需每次输入token
+        </div>
+        <div className='flex gap-2'>
+          <Button
+            color='secondary'
+            variant='flat'
+            onPress={preloadRegistrationOptions}
+            isLoading={isLoadingOptions}
+            className='w-fit'
+          >
+            {!isLoadingOptions && '📥'}
+            准备选项
+          </Button>
+          <Button
+            color='primary'
+            variant='flat'
+            onPress={() => {
+              // 必须在用户手势的同步上下文中立即调用WebAuthn API
+              if (!registrationOptions) {
+                toast.error('请先点击"准备选项"按钮获取注册选项');
+                return;
+              }
+
+              console.log('开始Passkey注册...');
+              console.log('使用预先获取的选项:', registrationOptions);
+
+              // 立即调用WebAuthn API，不要用async/await
+              navigator.credentials.create({
+                publicKey: {
+                  challenge: base64UrlToUint8Array(registrationOptions.challenge) as BufferSource,
+                  rp: {
+                    name: registrationOptions.rp.name,
+                    id: registrationOptions.rp.id
+                  },
+                  user: {
+                    id: base64UrlToUint8Array(registrationOptions.user.id) as BufferSource,
+                    name: registrationOptions.user.name,
+                    displayName: registrationOptions.user.displayName,
+                  },
+                  pubKeyCredParams: registrationOptions.pubKeyCredParams,
+                  timeout: 30000,
+                  excludeCredentials: registrationOptions.excludeCredentials?.map((cred: any) => ({
+                    id: base64UrlToUint8Array(cred.id) as BufferSource,
+                    type: cred.type,
+                    transports: cred.transports,
+                  })) || [],
+                  attestation: registrationOptions.attestation,
+                },
+              }).then(async (credential) => {
+                console.log('✅ 注册成功！凭据已创建');
+                console.log('凭据ID:', (credential as PublicKeyCredential).id);
+                console.log('凭据类型:', (credential as PublicKeyCredential).type);
+
+                // Prepare response for verification - convert to expected format
+                const cred = credential as PublicKeyCredential;
+                const response = {
+                  id: cred.id,  // 保持为base64url字符串
+                  rawId: uint8ArrayToBase64Url(new Uint8Array(cred.rawId)),  // 转换为base64url字符串
+                  response: {
+                    attestationObject: uint8ArrayToBase64Url(new Uint8Array((cred.response as AuthenticatorAttestationResponse).attestationObject)),  // 转换为base64url字符串
+                    clientDataJSON: uint8ArrayToBase64Url(new Uint8Array(cred.response.clientDataJSON)),  // 转换为base64url字符串
+                    transports: (cred.response as AuthenticatorAttestationResponse).getTransports?.() || [],
+                  },
+                  type: cred.type,
+                };
+
+                console.log('准备验证响应:', response);
+
+                try {
+                  // Verify registration
+                  const result = await WebUIManager.verifyPasskeyRegistration(response);
+
+                  if (result.verified) {
+                    toast.success('Passkey注册成功！现在您可以使用Passkey自动登录');
+                    setRegistrationOptions(null); // 清除已使用的选项
+                  } else {
+                    throw new Error('Passkey registration failed');
+                  }
+                } catch (verifyError) {
+                  console.error('❌ 验证失败:', verifyError);
+                  const err = verifyError as Error;
+                  toast.error(`Passkey验证失败: ${err.message}`);
+                }
+              }).catch((error) => {
+                console.error('❌ 注册失败:', error);
+                const err = error as Error;
+                console.error('错误名称:', err.name);
+                console.error('错误信息:', err.message);
+
+                // Provide more specific error messages
+                if (err.name === 'NotAllowedError') {
+                  toast.error('Passkey注册被拒绝。请确保您允许了生物识别认证权限。');
+                } else if (err.name === 'NotSupportedError') {
+                  toast.error('您的浏览器不支持Passkey功能。');
+                } else if (err.name === 'SecurityError') {
+                  toast.error('安全错误：请确保使用HTTPS或localhost环境。');
+                } else {
+                  toast.error(`Passkey注册失败: ${err.message}`);
+                }
+              });
+            }}
+            disabled={!registrationOptions}
+            className='w-fit'
+          >
+            🔐 注册Passkey
+          </Button>
+        </div>
+        {registrationOptions && (
+          <div className='text-xs text-green-600'>
+            ✅ 注册选项已准备就绪，可以开始注册
+          </div>
+        )}
+      </div>
       <SaveButtons
         onSubmit={onSubmit}
         reset={reset}

packages/napcat-webui-frontend/src/pages/web_login.tsx

@@ -24,7 +24,78 @@ export default function WebLoginPage () {
   const navigate = useNavigate();
   const [tokenValue, setTokenValue] = useState<string>(token || '');
   const [isLoading, setIsLoading] = useState<boolean>(false);
+  const [isPasskeyLoading, setIsPasskeyLoading] = useState<boolean>(true); // 初始为true，表示正在检查passkey
   const [, setLocalToken] = useLocalStorage<string>(key.token, '');
+
+  // Helper function to decode base64url
+  function base64UrlToUint8Array (base64Url: string): Uint8Array {
+    const base64 = base64Url.replace(/-/g, '+').replace(/_/g, '/');
+    const binaryString = atob(base64);
+    const bytes = new Uint8Array(binaryString.length);
+    for (let i = 0; i < binaryString.length; i++) {
+      bytes[i] = binaryString.charCodeAt(i);
+    }
+    return bytes;
+  }
+
+  // Helper function to encode Uint8Array to base64url
+  function uint8ArrayToBase64Url (uint8Array: Uint8Array): string {
+    const base64 = btoa(String.fromCharCode(...uint8Array));
+    return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+  }
+
+  // 自动检查并尝试passkey登录
+  const tryPasskeyLogin = async () => {
+    try {
+      // 检查是否有passkey
+      const options = await WebUIManager.generatePasskeyAuthenticationOptions();
+
+      // 如果有passkey，自动进行认证
+      const credential = await navigator.credentials.get({
+        publicKey: {
+          challenge: base64UrlToUint8Array(options.challenge) as BufferSource,
+          allowCredentials: options.allowCredentials?.map((cred: any) => ({
+            id: base64UrlToUint8Array(cred.id) as BufferSource,
+            type: cred.type,
+            transports: cred.transports,
+          })),
+          userVerification: options.userVerification,
+        },
+      }) as PublicKeyCredential;
+
+      if (!credential) {
+        throw new Error('Passkey authentication cancelled');
+      }
+
+      // 准备响应进行验证 - 转换为base64url字符串格式
+      const authResponse = credential.response as AuthenticatorAssertionResponse;
+      const response = {
+        id: credential.id,
+        rawId: uint8ArrayToBase64Url(new Uint8Array(credential.rawId)),
+        response: {
+          authenticatorData: uint8ArrayToBase64Url(new Uint8Array(authResponse.authenticatorData)),
+          clientDataJSON: uint8ArrayToBase64Url(new Uint8Array(authResponse.clientDataJSON)),
+          signature: uint8ArrayToBase64Url(new Uint8Array(authResponse.signature)),
+          userHandle: authResponse.userHandle ? uint8ArrayToBase64Url(new Uint8Array(authResponse.userHandle)) : null,
+        },
+        type: credential.type,
+      };
+
+      // 验证认证
+      const data = await WebUIManager.verifyPasskeyAuthentication(response);
+
+      if (data && data.Credential) {
+        setLocalToken(data.Credential);
+        navigate('/qq_login', { replace: true });
+        return true; // 登录成功
+      }
+    } catch (error) {
+      // passkey登录失败，继续显示token登录界面
+      console.log('Passkey login failed or not available:', error);
+    }
+    return false; // 登录失败
+  };
+
   const onSubmit = async () => {
     if (!tokenValue) {
       toast.error('请输入token');
@@ -48,7 +119,7 @@ export default function WebLoginPage () {
 
   // 处理全局键盘事件
   const handleKeyDown = (e: KeyboardEvent) => {
-    if (e.key === 'Enter' && !isLoading) {
+    if (e.key === 'Enter' && !isLoading && !isPasskeyLoading) {
       onSubmit();
     }
   };
@@ -60,12 +131,19 @@ export default function WebLoginPage () {
     return () => {
       document.removeEventListener('keydown', handleKeyDown);
     };
-  }, [tokenValue, isLoading]); // 依赖项包含用于登录的状态
+  }, [tokenValue, isLoading, isPasskeyLoading]); // 依赖项包含用于登录的状态
 
   useEffect(() => {
+    // 如果URL中有token，直接登录
     if (token) {
       onSubmit();
+      return;
     }
+
+    // 否则尝试passkey自动登录
+    tryPasskeyLogin().finally(() => {
+      setIsPasskeyLoading(false);
+    });
   }, []);
 
   return (
@@ -92,6 +170,11 @@ export default function WebLoginPage () {
             </CardHeader>
 
             <CardBody className='flex gap-5 py-5 px-5 md:px-10'>
+              {isPasskeyLoading && (
+                <div className='text-center text-small text-default-600 dark:text-default-400 px-2'>
+                  🔐 正在检查Passkey...
+                </div>
+              )}
               <form
                 onSubmit={(e) => {
                   e.preventDefault();
@@ -135,7 +218,7 @@ export default function WebLoginPage () {
                       '!cursor-text',
                     ],
                   }}
-                  isDisabled={isLoading}
+                  isDisabled={isLoading || isPasskeyLoading}
                   label='Token'
                   placeholder='请输入token'
                   radius='lg'