1  using GUNRPG.Application.Identity.Dtos;
 2  using GUNRPG.Application.Results;
 3  
 4  namespace GUNRPG.Application.Identity;
 5  
 6  /// <summary>
 7  /// Manages the Device Code Flow for console clients that cannot open a browser directly.
 8  /// The console displays a short user code; the user completes WebAuthn in their browser;
 9  /// the console polls until authorization is granted.
10  /// </summary>
11  public interface IDeviceCodeService
12  {
13      /// <summary>
14      /// Issues a new device code and user code pair.
15      /// The caller should display the <see cref="DeviceCodeResponse.UserCode"/> and
16      /// <see cref="DeviceCodeResponse.VerificationUri"/> to the end user.
17      /// </summary>
18      Task<DeviceCodeResponse> StartAsync(CancellationToken ct = default);
19  
20      /// <summary>
21      /// Authorizes a pending device code after the user completes browser authentication.
22      /// Called from the browser-side verification URI handler.
23      /// </summary>
24      Task<ServiceResult> AuthorizeAsync(string userCode, string userId, CancellationToken ct = default);
25  
26      /// <summary>
27      /// Polls for the status of a device code authorization.
28      /// Enforces the minimum poll interval to prevent abuse.
29      /// Returns an RFC 8628-aligned status via <see cref="DevicePollResponse.Status"/>:
30      /// <c>authorization_pending</c>, <c>slow_down</c>, <c>expired_token</c>, or <c>authorized</c> (with tokens).
31      /// </summary>
32      Task<ServiceResult<DevicePollResponse>> PollAsync(string deviceCode, CancellationToken ct = default);
33  }