From e92ea28e816d4f60cc76f016d64c0bf488265838 Mon Sep 17 00:00:00 2001
From: Jacob Reimers <jacob@reimers.dk>
Date: Mon, 31 May 2021 21:53:35 +0200
Subject: [PATCH] Add documentation.

---
 src/simpleauth.client/DeviceTokenRequest.cs   | 25 +++++++++++++
 src/simpleauth.client/PkceBuilder.cs          |  8 ++++
 src/simpleauth.client/TokenCredentials.cs     |  4 ++
 src/simpleauth.client/TokenRequest.cs         | 37 ++++++++++---------
 .../Repositories/IDeviceAuthorizationStore.cs | 34 +++++++++++++++++
 .../Requests/DeviceAuthorizationRequest.cs    | 10 +++++
 .../Responses/DeviceAuthorizationResponse.cs  |  3 ++
 .../Api/Device/DeviceAuthorizationActions.cs  | 18 +++++++++
 .../DeviceAuthorizationController.cs          | 32 ++++++++++++++--
 .../Controllers/DeviceController.cs           | 19 ++++++++++
 src/simpleauth/Controllers/TokenController.cs |  2 +-
 src/simpleauth/RuntimeSettings.cs             |  3 ++
 12 files changed, 172 insertions(+), 23 deletions(-)
 create mode 100644 src/simpleauth.client/DeviceTokenRequest.cs

diff --git a/src/simpleauth.client/DeviceTokenRequest.cs b/src/simpleauth.client/DeviceTokenRequest.cs
new file mode 100644
index 000000000..fca97c79c
--- /dev/null
+++ b/src/simpleauth.client/DeviceTokenRequest.cs
@@ -0,0 +1,25 @@
+namespace SimpleAuth.Client
+{
+    using System.Collections.Generic;
+
+    /// <summary>
+    /// Defines the device token request.
+    /// </summary>
+    public record DeviceTokenRequest : TokenRequest
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DeviceTokenRequest"/> record.
+        /// </summary>
+        /// <param name="form">The request form.</param>
+        /// <param name="interval">The polling interval.</param>
+        public DeviceTokenRequest(Dictionary<string, string> form, int interval) : base(form)
+        {
+            Interval = interval;
+        }
+
+        /// <summary>
+        /// Gets the polling interval.
+        /// </summary>
+        public int Interval { get; }
+    }
+}
\ No newline at end of file
diff --git a/src/simpleauth.client/PkceBuilder.cs b/src/simpleauth.client/PkceBuilder.cs
index 535350968..a029c3e29 100644
--- a/src/simpleauth.client/PkceBuilder.cs
+++ b/src/simpleauth.client/PkceBuilder.cs
@@ -18,10 +18,18 @@ namespace SimpleAuth.Client
     using System.Text;
     using SimpleAuth.Shared.Models;
 
+    /// <summary>
+    /// Defines the PKCE builder.
+    /// </summary>
     public static class PkceBuilder
     {
         private static readonly Random Random = new();
 
+        /// <summary>
+        /// Builds a PKCE challenge.
+        /// </summary>
+        /// <param name="method">The challenge method.</param>
+        /// <returns>A <see cref="Pkce"/> instance.</returns>
         public static Pkce BuildPkce(this string method)
         {
             var codeVerifier = GetCodeVerifier();
diff --git a/src/simpleauth.client/TokenCredentials.cs b/src/simpleauth.client/TokenCredentials.cs
index 9c9065103..1d89a0fe7 100644
--- a/src/simpleauth.client/TokenCredentials.cs
+++ b/src/simpleauth.client/TokenCredentials.cs
@@ -124,6 +124,10 @@ public static TokenCredentials FromClientSecret(string clientAssertion, string c
             return new TokenCredentials(dict);
         }
 
+        /// <summary>
+        /// Creates the credentials as a device.
+        /// </summary>
+        /// <returns></returns>
         public static TokenCredentials AsDevice()
         {
             return new(new Dictionary<string, string>());
diff --git a/src/simpleauth.client/TokenRequest.cs b/src/simpleauth.client/TokenRequest.cs
index 7fc2b176c..9b54d5d52 100644
--- a/src/simpleauth.client/TokenRequest.cs
+++ b/src/simpleauth.client/TokenRequest.cs
@@ -27,6 +27,10 @@ public record TokenRequest : IEnumerable<KeyValuePair<string?, string?>>
     {
         private readonly Dictionary<string, string> _form;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="TokenRequest"/> record.
+        /// </summary>
+        /// <param name="form"></param>
         protected internal TokenRequest(Dictionary<string, string> form)
         {
             _form = form;
@@ -212,18 +216,13 @@ public static TokenRequest FromPassword(string userName, string password, string
             return FromPassword(userName, password, scopes, new[] { amrValue });
         }
 
-        /// <inheritdoc />
-        public IEnumerator<KeyValuePair<string?, string?>> GetEnumerator()
-        {
-            return _form.GetEnumerator();
-        }
-
-        /// <inheritdoc />
-        IEnumerator IEnumerable.GetEnumerator()
-        {
-            return GetEnumerator();
-        }
-
+        /// <summary>
+        /// Creates a request from the device code.
+        /// </summary>
+        /// <param name="clientId">The client id.</param>
+        /// <param name="deviceCode">The device code.</param>
+        /// <param name="interval">The polling interval.</param>
+        /// <returns>A <see cref="TokenRequest"/> instance.</returns>
         public static TokenRequest FromDeviceCode(string clientId, string deviceCode, int interval)
         {
             var dictionary = new Dictionary<string, string>
@@ -234,15 +233,17 @@ public static TokenRequest FromDeviceCode(string clientId, string deviceCode, in
             };
             return new DeviceTokenRequest(dictionary, interval);
         }
-    }
 
-    public record DeviceTokenRequest : TokenRequest
-    {
-        public DeviceTokenRequest(Dictionary<string, string> form, int interval) : base(form)
+        /// <inheritdoc />
+        public IEnumerator<KeyValuePair<string?, string?>> GetEnumerator()
         {
-            Interval = interval;
+            return _form.GetEnumerator();
         }
 
-        public int Interval { get; }
+        /// <inheritdoc />
+        IEnumerator IEnumerable.GetEnumerator()
+        {
+            return GetEnumerator();
+        }
     }
 }
\ No newline at end of file
diff --git a/src/simpleauth.shared/Repositories/IDeviceAuthorizationStore.cs b/src/simpleauth.shared/Repositories/IDeviceAuthorizationStore.cs
index 96b1ccf1c..652470625 100644
--- a/src/simpleauth.shared/Repositories/IDeviceAuthorizationStore.cs
+++ b/src/simpleauth.shared/Repositories/IDeviceAuthorizationStore.cs
@@ -5,16 +5,50 @@
     using SimpleAuth.Shared.Requests;
     using SimpleAuth.Shared.Responses;
 
+    /// <summary>
+    /// Defines the device authorization store interface.
+    /// </summary>
     public interface IDeviceAuthorizationStore
     {
+        /// <summary>
+        /// Gets the <see cref="DeviceAuthorizationResponse"/> for the user code.
+        /// </summary>
+        /// <param name="userCode">The user code.</param>
+        /// <param name="cancellationToken">The <see cref="CancellationToken"/> for the async operation.</param>
+        /// <returns>A <see cref="DeviceAuthorizationResponse"/> as an async operation.</returns>
         public Task<Option<DeviceAuthorizationResponse>> Get(string userCode, CancellationToken cancellationToken = default);
 
+        /// <summary>
+        /// Gets the <see cref="DeviceAuthorizationData"/> for the device code.
+        /// </summary>
+        /// <param name="clientId">The client id.</param>
+        /// <param name="deviceCode">The device code.</param>
+        /// <param name="cancellationToken">The <see cref="CancellationToken"/> for the async operation.</param>
+        /// <returns>A <see cref="DeviceAuthorizationData"/> as an async operation.</returns>
         public Task<Option<DeviceAuthorizationData>> Get(string clientId, string deviceCode, CancellationToken cancellationToken = default);
 
+        /// <summary>
+        /// Approves the authorization request.
+        /// </summary>
+        /// <param name="userCode">The user code.</param>
+        /// <param name="cancellationToken">The <see cref="CancellationToken"/> for the async operation.</param>
+        /// <returns>An <see cref="Option"/> as an async operation.</returns>
         public Task<Option> Approve(string userCode, CancellationToken cancellationToken = default);
 
+        /// <summary>
+        /// Saves the passed <see cref="DeviceAuthorizationData"/>.
+        /// </summary>
+        /// <param name="request">The <see cref="DeviceAuthorizationData"/> to save.</param>
+        /// <param name="cancellationToken">The <see cref="CancellationToken"/> for the async operation.</param>
+        /// <returns>An <see cref="Option"/> as an async operation.</returns>
         Task<Option> Save(DeviceAuthorizationData request, CancellationToken cancellationToken = default);
 
+        /// <summary>
+        /// Removes the passed <see cref="DeviceAuthorizationData"/>.
+        /// </summary>
+        /// <param name="authRequest">The <see cref="DeviceAuthorizationData"/> to save.</param>
+        /// <param name="cancellationToken">The <see cref="CancellationToken"/> for the async operation.</param>
+        /// <returns>An <see cref="Option"/> as an async operation.</returns>
         Task<Option> Remove(DeviceAuthorizationData authRequest, CancellationToken cancellationToken);
     }
 }
\ No newline at end of file
diff --git a/src/simpleauth.shared/Requests/DeviceAuthorizationRequest.cs b/src/simpleauth.shared/Requests/DeviceAuthorizationRequest.cs
index 1627e0cdd..77f359c94 100644
--- a/src/simpleauth.shared/Requests/DeviceAuthorizationRequest.cs
+++ b/src/simpleauth.shared/Requests/DeviceAuthorizationRequest.cs
@@ -18,10 +18,20 @@ public DeviceAuthorizationRequest(string clientId, params string[] scopes)
             Scopes = scopes;
         }
 
+        /// <summary>
+        /// Gets the client id.
+        /// </summary>
         public string ClientId { get; }
 
+        /// <summary>
+        /// Gets the scopes.
+        /// </summary>
         public string[] Scopes { get; }
 
+        /// <summary>
+        /// Returns the request as a form.
+        /// </summary>
+        /// <returns>The form fields.</returns>
         public IEnumerable<KeyValuePair<string?, string?>> ToForm()
         {
             yield return new KeyValuePair<string?, string?>("client_id", ClientId);
diff --git a/src/simpleauth.shared/Responses/DeviceAuthorizationResponse.cs b/src/simpleauth.shared/Responses/DeviceAuthorizationResponse.cs
index 3c9889237..f17ed8e92 100644
--- a/src/simpleauth.shared/Responses/DeviceAuthorizationResponse.cs
+++ b/src/simpleauth.shared/Responses/DeviceAuthorizationResponse.cs
@@ -2,6 +2,9 @@
 {
     using System.Runtime.Serialization;
 
+    /// <summary>
+    /// Defines the device authorization response.
+    /// </summary>
     [DataContract]
     public record DeviceAuthorizationResponse
     {
diff --git a/src/simpleauth/Api/Device/DeviceAuthorizationActions.cs b/src/simpleauth/Api/Device/DeviceAuthorizationActions.cs
index c2b2b6db4..46030a77b 100644
--- a/src/simpleauth/Api/Device/DeviceAuthorizationActions.cs
+++ b/src/simpleauth/Api/Device/DeviceAuthorizationActions.cs
@@ -13,6 +13,9 @@
     using SimpleAuth.Shared.Requests;
     using SimpleAuth.Shared.Responses;
 
+    /// <summary>
+    /// Defines the device authorization.
+    /// </summary>
     public class DeviceAuthorizationActions
     {
         private readonly RuntimeSettings _settings;
@@ -22,6 +25,13 @@ public class DeviceAuthorizationActions
         private static readonly char[] Characters = "ABCDEFGHIJKMOPRSTVXYZ123456789".ToCharArray();
         private static readonly Random Rnd = new(DateTime.UtcNow.Millisecond);
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DeviceAuthorizationActions"/> class.
+        /// </summary>
+        /// <param name="settings">The runtime settings.</param>
+        /// <param name="store">The device authorization store.</param>
+        /// <param name="clientStore">The client store.</param>
+        /// <param name="logger">The logger.</param>
         public DeviceAuthorizationActions(RuntimeSettings settings, IDeviceAuthorizationStore store, IClientStore clientStore, ILogger logger)
         {
             _settings = settings;
@@ -30,6 +40,14 @@ public DeviceAuthorizationActions(RuntimeSettings settings, IDeviceAuthorization
             _logger = logger;
         }
 
+        /// <summary>
+        /// Starts the device authorization request.
+        /// </summary>
+        /// <param name="clientId">The client id of the requesting application.</param>
+        /// <param name="authority">The token authority.</param>
+        /// <param name="scopes">The requested scopes.</param>
+        /// <param name="cancellationToken">The <see cref="CancellationToken"/> for the async operation.</param>
+        /// <returns></returns>
         public async Task<Option<DeviceAuthorizationData>> StartDeviceAuthorizationRequest(string clientId, Uri authority, string[] scopes, CancellationToken cancellationToken)
         {
             if (string.IsNullOrWhiteSpace(clientId)
diff --git a/src/simpleauth/Controllers/DeviceAuthorizationController.cs b/src/simpleauth/Controllers/DeviceAuthorizationController.cs
index 0fb637ed8..0a961811e 100644
--- a/src/simpleauth/Controllers/DeviceAuthorizationController.cs
+++ b/src/simpleauth/Controllers/DeviceAuthorizationController.cs
@@ -13,6 +13,9 @@
     using SimpleAuth.Shared.Repositories;
     using SimpleAuth.Shared.Requests;
 
+    /// <summary>
+    /// Defines the device authorization controller.
+    /// </summary>
     [Route(CoreConstants.EndPoints.DeviceAuthorization)]
     [ThrottleFilter]
     [ResponseCache(Duration = 0, Location = ResponseCacheLocation.None, NoStore = true)]
@@ -20,6 +23,13 @@ public class DeviceAuthorizationController : ControllerBase
     {
         private readonly DeviceAuthorizationActions _actions;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DeviceAuthorizationController"/> class.
+        /// </summary>
+        /// <param name="settings">The runtime settings.</param>
+        /// <param name="deviceAuthorizationStore">The device authorization store.</param>
+        /// <param name="clientStore">The client store.</param>
+        /// <param name="logger">The logger.</param>
         public DeviceAuthorizationController(
             RuntimeSettings settings,
             IClientStore clientStore,
@@ -29,14 +39,25 @@ public DeviceAuthorizationController(
             _actions = new DeviceAuthorizationActions(settings, deviceAuthorizationStore, clientStore, logger);
         }
 
+        /// <summary>
+        /// Requests the authorization.
+        /// </summary>
+        /// <param name="request">The token request.</param>
+        /// <param name="cancellationToken">The <see cref="CancellationToken"/> for the async operation.</param>
+        /// <returns></returns>
         [HttpPost]
-        public async Task<IActionResult> RequestAuthorization([FromForm] TokenRequest request, CancellationToken cancellationToken)
+        public async Task<IActionResult> RequestAuthorization(
+            [FromForm] TokenRequest request,
+            CancellationToken cancellationToken)
         {
             if (string.IsNullOrWhiteSpace(request.client_id))
             {
                 return BadRequest();
             }
-            var scopeArray = string.IsNullOrWhiteSpace(request.scope) ? Array.Empty<string>() : request.scope.Split(' ', StringSplitOptions.TrimEntries).ToArray();
+
+            var scopeArray = string.IsNullOrWhiteSpace(request.scope)
+                ? Array.Empty<string>()
+                : request.scope.Split(' ', StringSplitOptions.TrimEntries).ToArray();
             var response = await _actions.StartDeviceAuthorizationRequest(
                     request.client_id,
                     Request.GetAbsoluteUri(),
@@ -47,9 +68,12 @@ public async Task<IActionResult> RequestAuthorization([FromForm] TokenRequest re
             return response switch
             {
                 Option<DeviceAuthorizationData>.Result r => Ok(r.Item.Response),
-                Option<DeviceAuthorizationData>.Error e => new ObjectResult(e.Details) { StatusCode = (int)e.Details.Status },
+                Option<DeviceAuthorizationData>.Error e => new ObjectResult(e.Details)
+                {
+                    StatusCode = (int) e.Details.Status
+                },
                 _ => throw new ArgumentOutOfRangeException()
             };
         }
     }
-}
\ No newline at end of file
+}
diff --git a/src/simpleauth/Controllers/DeviceController.cs b/src/simpleauth/Controllers/DeviceController.cs
index 5c93a9cc2..4bee496c1 100644
--- a/src/simpleauth/Controllers/DeviceController.cs
+++ b/src/simpleauth/Controllers/DeviceController.cs
@@ -10,6 +10,9 @@
     using SimpleAuth.Shared.Repositories;
     using SimpleAuth.ViewModels;
 
+    /// <summary>
+    /// Defines the device controller.
+    /// </summary>
     [Authorize]
     [Route(CoreConstants.EndPoints.Device)]
     [ThrottleFilter]
@@ -19,18 +22,34 @@ public class DeviceController : ControllerBase
         private readonly IDeviceAuthorizationStore _deviceAuthorizationStore;
         private readonly ILogger<DeviceController> _logger;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DeviceController"/> class.
+        /// </summary>
+        /// <param name="deviceAuthorizationStore">The device authorization store.</param>
+        /// <param name="logger">The logger.</param>
         public DeviceController(IDeviceAuthorizationStore deviceAuthorizationStore, ILogger<DeviceController> logger)
         {
             _deviceAuthorizationStore = deviceAuthorizationStore;
             _logger = logger;
         }
 
+        /// <summary>
+        /// Gets the authorization form.
+        /// </summary>
+        /// <param name="code">The optional user code.</param>
+        /// <returns>The authorization form.</returns>
         [HttpGet]
         public async Task<IActionResult> Get([FromQuery] string code)
         {
             return Ok(new DeviceAuthorizationViewModel { Code = code });
         }
 
+        /// <summary>
+        /// Approves the authorization request.
+        /// </summary>
+        /// <param name="code">The user code.</param>
+        /// <param name="cancellationToken">The <see cref="CancellationToken"/> for the async operation.</param>
+        /// <returns>The authorized form.</returns>
         [HttpPost]
         public async Task<IActionResult> Approve([FromForm] string code, CancellationToken cancellationToken)
         {
diff --git a/src/simpleauth/Controllers/TokenController.cs b/src/simpleauth/Controllers/TokenController.cs
index 46c2928e5..f72195f10 100644
--- a/src/simpleauth/Controllers/TokenController.cs
+++ b/src/simpleauth/Controllers/TokenController.cs
@@ -13,7 +13,6 @@
     using System.Linq;
     using System.Net;
     using System.Net.Http.Headers;
-    using System.Runtime.Serialization;
     using System.Security.Cryptography.X509Certificates;
     using System.Threading;
     using System.Threading.Tasks;
@@ -50,6 +49,7 @@ public class TokenController : ControllerBase
         /// <param name="ticketStore">The ticket store.</param>
         /// <param name="jwksStore"></param>
         /// <param name="resourceSetRepository">The resource set repository.</param>
+        /// <param name="deviceAuthorizationStore">The device authorization store.</param>
         /// <param name="eventPublisher">The event publisher.</param>
         /// <param name="logger">The logger.</param>
         public TokenController(
diff --git a/src/simpleauth/RuntimeSettings.cs b/src/simpleauth/RuntimeSettings.cs
index 7e9fe5401..8c47ed497 100644
--- a/src/simpleauth/RuntimeSettings.cs
+++ b/src/simpleauth/RuntimeSettings.cs
@@ -107,6 +107,9 @@ public RuntimeSettings(
         /// </summary>
         public TimeSpan DevicePollingInterval { get; }
 
+        /// <summary>
+        /// Gets the device authorization request lifetime.
+        /// </summary>
         public TimeSpan DeviceAuthorizationLifetime { get; }
     }
 }