using Dpz.Core.Auth.Models.AdminApi;
using Dpz.Core.Public.ViewModel.WebAuthn;

namespace Dpz.Core.Auth.Service;

public interface IUserMfaVerificationService
{
    /// <summary>
    /// 验证后台敏感操作的 2FA 动态验证码,强制要求用户已绑定 2FA
    /// </summary>
    Task<ResponseResult> ValidateRequiredTwoFactorAsync(
        string? account,
        string? pinCode,
        CancellationToken cancellationToken = default
    );

    /// <summary>
    /// 验证登录和修改密码的 2FA 动态验证码,未绑定 2FA 时跳过验证
    /// </summary>
    Task<ResponseResult> ValidateOptionalTwoFactorAsync(
        string? account,
        string? pinCode,
        CancellationToken cancellationToken = default
    );

    /// <summary>
    /// 验证后台敏感操作,优先使用当前设备的 Passkey,当前设备不可用时回退至 2FA 动态验证码;
    /// 账号未绑定任何 MFA 方式时操作直接放行(NeedsSecuritySetup=true),由前端提醒用户完成安全绑定
    /// </summary>
    Task<ResponseResult<AdminMfaVerificationResult>> VerifyAdminOperationAsync(
        string? account,
        string operationKey,
        AdminMfaRequest? request,
        CancellationToken cancellationToken = default
    );

    /// <summary>
    /// 为 Passkey 敏感操作创建 WebAuthn 断言参数
    /// </summary>
    Task<PasskeyOperationVerificationOptions?> BeginPasskeyOperationAsync(
        string account,
        string targetCredentialId,
        string purpose,
        CancellationToken cancellationToken = default
    );

    /// <summary>
    /// 验证 Passkey 敏感操作的 WebAuthn 断言
    /// </summary>
    Task<ResponseResult> CompletePasskeyOperationAsync(
        string account,
        string targetCredentialId,
        string purpose,
        DeleteWebAuthnCredentialRequest request,
        CancellationToken cancellationToken = default
    );
}

public class PasskeyOperationVerificationOptions
{
    public required AssertionOptions AssertionOptions { get; set; }

    public required string Challenge { get; set; }
}
⚠⚠    以下内容为AI分析的结果,请根据实际情况进行判断。

代码解释

这是一个定义了用户多因素认证(MFA)验证服务的接口文件,主要用于处理后台管理系统中的安全验证场景。

主要组成部分

1. IUserMfaVerificationService 接口

这个接口定义了多种 MFA 验证方法,支持不同的安全场景:

ValidateRequiredTwoFactorAsync

Task<ResponseResult> ValidateRequiredTwoFactorAsync(...)
  • 用途:验证后台敏感操作的双因素认证(2FA)动态验证码
  • 特点强制要求用户必须已绑定 2FA
  • 适用场景:高安全级别操作,如删除重要数据、修改系统配置等

ValidateOptionalTwoFactorAsync

Task<ResponseResult> ValidateOptionalTwoFactorAsync(...)
  • 用途:验证登录和修改密码场景的 2FA 验证码
  • 特点:如果用户未绑定 2FA,则跳过验证
  • 适用场景:登录、修改密码等操作

VerifyAdminOperationAsync

Task<ResponseResult<AdminMfaVerificationResult>> VerifyAdminOperationAsync(...)
  • 用途:后台敏感操作的综合验证方法
  • 验证策略
    1. 优先使用 Passkey(WebAuthn)验证
    2. 当前设备 Passkey 不可用时,回退至 2FA 动态验证码
    3. 若账号未绑定任何 MFA,操作放行但返回 NeedsSecuritySetup=true,提示前端引导用户完成安全设置
  • 灵活性:提供多层次的安全验证策略

BeginPasskeyOperationAsync

Task<PasskeyOperationVerificationOptions?> BeginPasskeyOperationAsync(...)
  • 用途:为 Passkey 敏感操作创建 WebAuthn 断言参数
  • 流程:这是 WebAuthn 验证的第一步,生成挑战(Challenge)

CompletePasskeyOperationAsync

Task<ResponseResult> CompletePasskeyOperationAsync(...)
  • 用途:验证 Passkey 敏感操作的 WebAuthn 断言
  • 流程:这是 WebAuthn 验证的第二步,验证客户端返回的断言响应

2. PasskeyOperationVerificationOptions 类

public class PasskeyOperationVerificationOptions
{
    public required AssertionOptions AssertionOptions { get; set; }
    public required string Challenge { get; set; }
}
  • 用途:封装 Passkey 操作验证时需要的选项
  • AssertionOptions:WebAuthn 断言所需的配置参数
  • Challenge:随机生成的挑战字符串,用于防止重放攻击

设计特点

  1. 多层次安全策略:支持 Passkey、2FA 等多种认证方式
  2. 灵活的验证级别:区分强制验证(Required)和可选验证(Optional)
  3. 渐进式安全提示:未绑定 MFA 时不阻止操作,而是提示用户完成设置
  4. 现代化认证:支持 WebAuthn/Passkey 等无密码认证技术
  5. 异步设计:所有方法都是异步的,支持取消令牌

这是一个设计良好的安全认证服务接口,适用于企业级后台管理系统。

评论加载中...