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-backend/src/api/Auth.ts

@@ -1,5 +1,6 @@
 import { RequestHandler } from 'express';
 import { AuthHelper } from '@/napcat-webui-backend/src/helper/SignToken';
+import { PasskeyHelper } from '@/napcat-webui-backend/src/helper/PasskeyHelper';
 import { WebUiDataRuntime } from '@/napcat-webui-backend/src/helper/Data';
 import { sendSuccess, sendError } from '@/napcat-webui-backend/src/utils/response';
 import { isEmpty } from '@/napcat-webui-backend/src/utils/check';
@@ -148,3 +149,115 @@ export const UpdateTokenHandler: RequestHandler = async (req, res) => {
     return sendError(res, `Failed to update token: ${e.message}`);
   }
 };
+
+// 生成Passkey注册选项
+export const GeneratePasskeyRegistrationOptionsHandler: RequestHandler = async (_req, res) => {
+  try {
+    // 使用固定用户ID，因为WebUI只有一个用户
+    const userId = 'napcat-user';
+    const userName = 'NapCat User';
+
+    // 从请求头获取host来确定RP_ID
+    const host = _req.get('host') || 'localhost';
+    const hostname = host.split(':')[0] || 'localhost'; // 移除端口
+    // 对于本地开发，使用localhost而不是IP地址
+    const rpId = (hostname === '127.0.0.1' || hostname === 'localhost') ? 'localhost' : hostname;
+
+    const options = await PasskeyHelper.generateRegistrationOptions(userId, userName, rpId);
+    return sendSuccess(res, options);
+  } catch (error) {
+    return sendError(res, `Failed to generate registration options: ${(error as Error).message}`);
+  }
+};
+
+// 验证Passkey注册
+export const VerifyPasskeyRegistrationHandler: RequestHandler = async (req, res) => {
+  try {
+    const { response } = req.body;
+    if (!response) {
+      return sendError(res, 'Response is required');
+    }
+
+    const origin = req.get('origin') || req.protocol + '://' + req.get('host');
+    const host = req.get('host') || 'localhost';
+    const hostname = host.split(':')[0] || 'localhost'; // 移除端口
+    // 对于本地开发，使用localhost而不是IP地址
+    const rpId = (hostname === '127.0.0.1' || hostname === 'localhost') ? 'localhost' : hostname;
+    const userId = 'napcat-user';
+    const verification = await PasskeyHelper.verifyRegistration(userId, response, origin, rpId);
+
+    if (verification.verified) {
+      return sendSuccess(res, { verified: true });
+    } else {
+      return sendError(res, 'Registration failed');
+    }
+  } catch (error) {
+    return sendError(res, `Registration verification failed: ${(error as Error).message}`);
+  }
+};
+
+// 生成Passkey认证选项
+export const GeneratePasskeyAuthenticationOptionsHandler: RequestHandler = async (_req, res) => {
+  try {
+    const userId = 'napcat-user';
+
+    if (!(await PasskeyHelper.hasPasskeys(userId))) {
+      return sendError(res, 'No passkeys registered');
+    }
+
+    // 从请求头获取host来确定RP_ID
+    const host = _req.get('host') || 'localhost';
+    const hostname = host.split(':')[0] || 'localhost'; // 移除端口
+    // 对于本地开发，使用localhost而不是IP地址
+    const rpId = (hostname === '127.0.0.1' || hostname === 'localhost') ? 'localhost' : hostname;
+
+    const options = await PasskeyHelper.generateAuthenticationOptions(userId, rpId);
+    return sendSuccess(res, options);
+  } catch (error) {
+    return sendError(res, `Failed to generate authentication options: ${(error as Error).message}`);
+  }
+};
+
+// 验证Passkey认证
+export const VerifyPasskeyAuthenticationHandler: RequestHandler = async (req, res) => {
+  try {
+    const { response } = req.body;
+    if (!response) {
+      return sendError(res, 'Response is required');
+    }
+
+    // 获取WebUI配置用于限速检查
+    const WebUiConfigData = await WebUiConfig.GetWebUIConfig();
+    // 获取客户端IP
+    const clientIP = req.ip || req.socket.remoteAddress || '';
+
+    // 检查登录频率
+    if (!WebUiDataRuntime.checkLoginRate(clientIP, WebUiConfigData.loginRate)) {
+      return sendError(res, 'login rate limit');
+    }
+
+    const origin = req.get('origin') || req.protocol + '://' + req.get('host');
+    const host = req.get('host') || 'localhost';
+    const hostname = host.split(':')[0] || 'localhost'; // 移除端口
+    // 对于本地开发，使用localhost而不是IP地址
+    const rpId = (hostname === '127.0.0.1' || hostname === 'localhost') ? 'localhost' : hostname;
+    const userId = 'napcat-user';
+    const verification = await PasskeyHelper.verifyAuthentication(userId, response, origin, rpId);
+
+    if (verification.verified) {
+      // 使用与普通登录相同的凭证签发
+      const initialToken = getInitialWebUiToken();
+      if (!initialToken) {
+        return sendError(res, 'Server token not initialized');
+      }
+      const signCredential = Buffer.from(JSON.stringify(AuthHelper.signCredential(AuthHelper.generatePasswordHash(initialToken)))).toString('base64');
+      return sendSuccess(res, {
+        Credential: signCredential,
+      });
+    } else {
+      return sendError(res, 'Authentication failed');
+    }
+  } catch (error) {
+    return sendError(res, `Authentication verification failed: ${(error as Error).message}`);
+  }
+};

packages/napcat-webui-backend/src/helper/PasskeyHelper.ts

@@ -0,0 +1,206 @@
+import {
+  generateRegistrationOptions,
+  verifyRegistrationResponse,
+  generateAuthenticationOptions,
+  verifyAuthenticationResponse,
+  type AuthenticatorTransportFuture,
+} from '@simplewebauthn/server';
+import { isoBase64URL } from '@simplewebauthn/server/helpers';
+import { promises as fs } from 'fs';
+import path from 'path';
+import { webUiPathWrapper } from '../../index';
+
+interface PasskeyCredential {
+  id: string;
+  publicKey: string;
+  counter: number;
+  transports?: AuthenticatorTransportFuture[];
+}
+
+const RP_NAME = 'NapCat WebUI';
+
+export class PasskeyHelper {
+  private static getPasskeyFilePath (): string {
+    return path.join(webUiPathWrapper.configPath, 'passkey.json');
+  }
+
+  // 内存中存储临时挑战数据
+  private static challenges: Map<string, string> = new Map();
+  private static async ensurePasskeyFile (): Promise<void> {
+    try {
+      // 确保配置文件目录存在
+      const passkeyFile = this.getPasskeyFilePath();
+      await fs.mkdir(path.dirname(passkeyFile), { recursive: true });
+      // 检查文件是否存在，如果不存在创建空文件
+      try {
+        await fs.access(passkeyFile);
+      } catch {
+        await fs.writeFile(passkeyFile, JSON.stringify({}, null, 2));
+      }
+    } catch (error) {
+      // Directory or file already exists or other error
+    }
+  }
+
+  private static async getAllPasskeys (): Promise<Record<string, PasskeyCredential[]>> {
+    await this.ensurePasskeyFile();
+    try {
+      const passkeyFile = this.getPasskeyFilePath();
+      const data = await fs.readFile(passkeyFile, 'utf-8');
+      const passkeys = JSON.parse(data);
+      return typeof passkeys === 'object' && passkeys !== null ? passkeys : {};
+    } catch (error) {
+      return {};
+    }
+  }
+
+  private static async saveAllPasskeys (allPasskeys: Record<string, PasskeyCredential[]>): Promise<void> {
+    await this.ensurePasskeyFile();
+    const passkeyFile = this.getPasskeyFilePath();
+    await fs.writeFile(passkeyFile, JSON.stringify(allPasskeys, null, 2));
+  }
+
+  private static async getUserPasskeys (userId: string): Promise<PasskeyCredential[]> {
+    const allPasskeys = await this.getAllPasskeys();
+    return allPasskeys[userId] || [];
+  }
+
+  // 持久性存储用户的passkey到统一配置文件
+  private static async setUserPasskeys (userId: string, passkeys: PasskeyCredential[]): Promise<void> {
+    const allPasskeys = await this.getAllPasskeys();
+    if (passkeys.length > 0) {
+      allPasskeys[userId] = passkeys;
+    } else {
+      delete allPasskeys[userId];
+    }
+    await this.saveAllPasskeys(allPasskeys);
+  }
+
+  static async generateRegistrationOptions (userId: string, userName: string, rpId: string) {
+    const userPasskeys = await this.getUserPasskeys(userId);
+
+    const options = await generateRegistrationOptions({
+      rpName: RP_NAME,
+      rpID: rpId,
+      userID: new TextEncoder().encode(userId),
+      userName: userName,
+      attestationType: 'none',
+      excludeCredentials: userPasskeys.map(passkey => ({
+        id: passkey.id,
+        type: 'public-key' as const,
+        transports: passkey.transports,
+      })),
+      // Temporarily simplify authenticatorSelection - remove residentKey to avoid conflicts
+      authenticatorSelection: {
+        userVerification: 'preferred',
+      },
+    });
+
+    // Store challenge temporarily in memory
+    this.challenges.set(`reg_${userId}`, options.challenge);
+    // Auto cleanup after 5 minutes
+    setTimeout(() => {
+      this.challenges.delete(`reg_${userId}`);
+    }, 300000);
+
+    return options;
+  }
+
+  static async verifyRegistration (userId: string, response: any, origin: string, rpId: string) {
+    const expectedChallenge = this.challenges.get(`reg_${userId}`);
+    if (!expectedChallenge) {
+      throw new Error('Challenge not found or expired');
+    }
+
+    const verification = await verifyRegistrationResponse({
+      response,
+      expectedChallenge,
+      expectedOrigin: origin,
+      expectedRPID: rpId,
+    });
+
+    if (verification.verified && verification.registrationInfo) {
+      const { registrationInfo } = verification;
+
+      const newPasskey: PasskeyCredential = {
+        id: registrationInfo.credential.id,
+        publicKey: isoBase64URL.fromBuffer(registrationInfo.credential.publicKey),
+        counter: registrationInfo.credential.counter || 0,
+        transports: response.response.transports,
+      };
+
+      const userPasskeys = await this.getUserPasskeys(userId);
+      userPasskeys.push(newPasskey);
+      await this.setUserPasskeys(userId, userPasskeys);
+
+      // Clean up challenge
+      this.challenges.delete(`reg_${userId}`);
+    }
+
+    return verification;
+  }
+
+  static async generateAuthenticationOptions (userId: string, rpId: string) {
+    const userPasskeys = await this.getUserPasskeys(userId);
+
+    const options = await generateAuthenticationOptions({
+      rpID: rpId,
+      allowCredentials: userPasskeys.map(passkey => ({
+        id: passkey.id,
+        type: 'public-key' as const,
+        transports: passkey.transports,
+      })),
+      userVerification: 'preferred',
+    });
+
+    // Store challenge temporarily in memory
+    this.challenges.set(`auth_${userId}`, options.challenge);
+    // Auto cleanup after 5 minutes
+    setTimeout(() => {
+      this.challenges.delete(`auth_${userId}`);
+    }, 300000);
+
+    return options;
+  }
+
+  static async verifyAuthentication (userId: string, response: any, origin: string, rpId: string) {
+    const expectedChallenge = this.challenges.get(`auth_${userId}`);
+    if (!expectedChallenge) {
+      throw new Error('Challenge not found or expired');
+    }
+
+    const userPasskeys = await this.getUserPasskeys(userId);
+    const passkey = userPasskeys.find(p => p.id === response.id);
+    if (!passkey) {
+      throw new Error('Passkey not found');
+    }
+
+    const verification = await verifyAuthenticationResponse({
+      response,
+      expectedChallenge,
+      expectedOrigin: origin,
+      expectedRPID: rpId,
+      credential: {
+        id: passkey.id,
+        publicKey: isoBase64URL.toBuffer(passkey.publicKey),
+        counter: passkey.counter,
+      },
+    });
+
+    if (verification.verified && verification.authenticationInfo) {
+      // Update counter
+      passkey.counter = verification.authenticationInfo.newCounter;
+      await this.setUserPasskeys(userId, userPasskeys);
+
+      // Clean up challenge
+      this.challenges.delete(`auth_${userId}`);
+    }
+
+    return verification;
+  }
+
+  static async hasPasskeys (userId: string): Promise<boolean> {
+    const userPasskeys = await this.getUserPasskeys(userId);
+    return userPasskeys.length > 0;
+  }
+}

packages/napcat-webui-backend/src/middleware/auth.ts

@@ -12,6 +12,12 @@ export async function auth (req: Request, res: Response, next: NextFunction) {
   if (req.url === '/auth/login') {
     return next();
   }
+  if (req.url === '/auth/passkey/generate-authentication-options' ||
+    req.url === '/auth/passkey/verify-authentication') {
+    return next();
+  }
+
+
 
   // 判断是否有Authorization头
   if (req.headers?.authorization) {

packages/napcat-webui-backend/src/router/auth.ts

@@ -5,6 +5,10 @@ import {
   LoginHandler,
   LogoutHandler,
   UpdateTokenHandler,
+  GeneratePasskeyRegistrationOptionsHandler,
+  VerifyPasskeyRegistrationHandler,
+  GeneratePasskeyAuthenticationOptionsHandler,
+  VerifyPasskeyAuthenticationHandler,
 } from '@/napcat-webui-backend/src/api/Auth';
 
 const router = Router();
@@ -16,5 +20,13 @@ router.post('/check', checkHandler);
 router.post('/logout', LogoutHandler);
 // router:更新token
 router.post('/update_token', UpdateTokenHandler);
+// router:生成Passkey注册选项
+router.post('/passkey/generate-registration-options', GeneratePasskeyRegistrationOptionsHandler);
+// router:验证Passkey注册
+router.post('/passkey/verify-registration', VerifyPasskeyRegistrationHandler);
+// router:生成Passkey认证选项
+router.post('/passkey/generate-authentication-options', GeneratePasskeyAuthenticationOptionsHandler);
+// router:验证Passkey认证
+router.post('/passkey/verify-authentication', VerifyPasskeyAuthenticationHandler);
 
 export { router as AuthRouter };