1  using GUNRPG.Application.Identity.Dtos;
 2  using GUNRPG.Application.Results;
 3  
 4  namespace GUNRPG.Application.Identity;
 5  
 6  /// <summary>
 7  /// Manages WebAuthn credential registration and authentication.
 8  /// Abstracts Fido2NetLib to keep the application layer free of library types.
 9  /// </summary>
10  public interface IWebAuthnService
11  {
12      /// <summary>
13      /// Begins credential registration for a user.
14      /// Returns a JSON options object to send to the browser's navigator.credentials.create().
15      /// </summary>
16      Task<ServiceResult<string>> BeginRegistrationAsync(string username, CancellationToken ct = default);
17  
18      /// <summary>
19      /// Completes credential registration, persists the credential, and returns the user ID.
20      /// Returns a typed <see cref="WebAuthnErrorCode"/> inside the error message for client debugging.
21      /// Format: "ERROR_CODE: human readable message" when <see cref="ServiceResult{T}.IsSuccess"/> is false.
22      /// </summary>
23      Task<ServiceResult<string>> CompleteRegistrationAsync(
24          string username,
25          string attestationResponseJson,
26          CancellationToken ct = default);
27  
28      /// <summary>
29      /// Begins a WebAuthn authentication assertion for a known username.
30      /// Returns a JSON options object to send to the browser's navigator.credentials.get().
31      /// </summary>
32      Task<ServiceResult<string>> BeginLoginAsync(string username, CancellationToken ct = default);
33  
34      /// <summary>
35      /// Completes WebAuthn authentication, updates the signature counter, and returns the user ID.
36      /// Returns a typed <see cref="WebAuthnErrorCode"/> inside the error message for client debugging.
37      /// Format: "ERROR_CODE: human readable message" when <see cref="ServiceResult{T}.IsSuccess"/> is false.
38      /// </summary>
39      Task<ServiceResult<string>> CompleteLoginAsync(
40          string username,
41          string assertionResponseJson,
42          CancellationToken ct = default);
43  
44      /// <summary>
45      /// Begins a usernameless (discoverable credential) WebAuthn authentication assertion.
46      /// Returns a session ID and a JSON options object with an empty allowCredentials list so the
47      /// browser can discover resident credentials without the user entering a username first.
48      /// </summary>
49      Task<ServiceResult<(string SessionId, string OptionsJson)>> BeginDiscoverableLoginAsync(CancellationToken ct = default);
50  
51      /// <summary>
52      /// Completes a usernameless WebAuthn authentication.  The user is identified from the
53      /// credential ID in the assertion rather than from a supplied username.
54      /// Returns the authenticated user ID on success.
55      /// </summary>
56      Task<ServiceResult<string>> CompleteDiscoverableLoginAsync(
57          string sessionId,
58          string assertionResponseJson,
59          CancellationToken ct = default);
60  }