Product Completion

Author: mckaragoz

src/client/CodeBeam.UltimateAuth.Client.Blazor/Attributes/UAuthAuthorizeAttribute.cs

@@ -1,8 +1,37 @@
 namespace CodeBeam.UltimateAuth.Client.Blazor;
 
+/// <summary>
+/// Declares UltimateAuth authorization requirements for a Blazor component or page.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The attribute can be used to associate role and permission requirements with routable or authorization-aware Blazor components.
+/// </para>
+/// <para>
+/// Role and permission values are expressed as comma-separated lists. The effective
+/// authorization behavior is determined by the UltimateAuth authorization pipeline that consumes this metadata.
+/// </para>
+/// <para>
+/// This attribute describes authorization requirements only. It does not perform authorization by itself.
+/// </para>
+/// </remarks>
 [AttributeUsage(AttributeTargets.Class)]
 public sealed class UAuthAuthorizeAttribute : Attribute
 {
+    /// <summary>
+    /// Gets or sets the comma-separated roles associated with the authorization requirement.
+    /// </summary>
+    /// <remarks>
+    /// A <see langword="null"/>, empty, or whitespace value indicates that no explicit role requirement is declared by this property.
+    /// </remarks>
     public string? Roles { get; set; }
+
+    /// <summary>
+    /// Gets or sets the comma-separated UltimateAuth permissions associated with the authorization requirement.
+    /// </summary>
+    /// <remarks>
+    /// A <see langword="null"/>, empty, or whitespace value indicates that no explicit 
+    /// permission requirement is declared by this property.
+    /// </remarks>
     public string? Permissions { get; set; }
 }

src/client/CodeBeam.UltimateAuth.Client.Blazor/CodeBeam.UltimateAuth.Client.Blazor.csproj

@@ -2,7 +2,6 @@
 
 	<PropertyGroup>
 		<TargetFrameworks>net8.0;net9.0;net10.0</TargetFrameworks>
-		<NoWarn>$(NoWarn);1591</NoWarn>
 
 		<PackageId>CodeBeam.UltimateAuth.Client.Blazor</PackageId>
 

src/client/CodeBeam.UltimateAuth.Client.Blazor/Components/Base/UAuthComponentBase.cs

@@ -19,13 +19,18 @@ public abstract class UAuthComponentBase : ComponentBase, IDisposable
     /// <summary>
     /// Gets the Blazor navigation service.
     /// </summary>
-    [Inject] protected NavigationManager Nav { get; set; } = default!;
+    [Inject] protected NavigationManager Navigation { get; set; } = default!;
 
     /// <summary>
     /// Automatically re-render when UAuthState changes. Can be overridden to disable.
     /// </summary>
     protected virtual bool AutoRefreshOnAuthStateChanged => true;
 
+    /// <summary>
+    /// Called when the component's parameters have been set. This method ensures that the component is properly registered 
+    /// with the current <see cref="UAuthState"/> and evaluates authorization requirements.
+    /// </summary>
+    /// <exception cref="InvalidOperationException"></exception>
     protected override void OnParametersSet()
     {
         base.OnParametersSet();
@@ -46,6 +51,11 @@ protected override void OnParametersSet()
         EvaluateAuthorization();
     }
 
+    /// <summary>
+    /// Called after the component has been rendered. This method sets the _rendered flag to true on the first render.
+    /// </summary>
+    /// <param name="firstRender"></param>
+    /// <returns></returns>
     protected override async Task OnAfterRenderAsync(bool firstRender)
     {
         await base.OnAfterRenderAsync(firstRender);
@@ -117,17 +127,20 @@ private void EvaluateAuthorization()
     /// </summary>
     protected virtual void OnUnauthorized()
     {
-        Nav.NavigateTo("/");
+        Navigation.NavigateTo("/");
     }
 
     /// <summary>
     /// Called when the current user is authenticated but does not satisfy the authorization requirements of the component.
     /// </summary>
     protected virtual void OnForbidden()
     {
-        Nav.NavigateTo("/forbidden");
+        Navigation.NavigateTo("/forbidden");
     }
 
+    /// <summary>
+    /// Disposes of the component and unsubscribes from the <see cref="UAuthState.Changed"/> event to prevent memory leaks.
+    /// </summary>
     public virtual void Dispose()
     {
         if (_previousState is not null)

src/client/CodeBeam.UltimateAuth.Client.Blazor/Components/Base/UAuthHubLayoutBase.cs

@@ -5,20 +5,67 @@
 
 namespace CodeBeam.UltimateAuth.Client.Blazor;
 
+/// <summary>
+/// Base class for Blazor layouts that participate in an UltimateAuth Hub flow.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The layout resolves the Hub session identifier from the current navigation URI
+/// and exposes the corresponding <see cref="HubFlowState"/> to derived layouts.
+/// </para>
+/// <para>
+/// Hub state is obtained through <see cref="IHubFlowReader"/>. An absent or invalid
+/// Hub session identifier results in no current Hub state.
+/// </para>
+/// <para>
+/// This type provides Hub flow state to the UI and does not itself authorize,
+/// complete, or otherwise make security decisions for the authentication flow.
+/// </para>
+/// </remarks>
 public abstract class UAuthHubLayoutBase : LayoutComponentBase
 {
+    /// <summary>
+    /// Gets the navigation service used to inspect the current URI.
+    /// </summary>
     [Inject] protected NavigationManager Navigation { get; set; } = default!;
+
+    /// <summary>
+    /// Gets the Hub flow reader used to retrieve the state of the current Hub session.
+    /// </summary>
     [Inject] protected IHubFlowReader HubFlowReader { get; set; } = default!;
 
+    /// <summary>
+    /// Gets the state associated with the current Hub session, when one can be resolved.
+    /// </summary>
+    /// <remarks>
+    /// The value is <see langword="null"/> when the current URI does not contain a Hub
+    /// session identifier, the identifier is invalid, or no state has been loaded.
+    /// </remarks>
     protected HubFlowState? HubState { get; private set; }
 
+    /// <summary>
+    /// Gets a value indicating whether the resolved Hub flow exists.
+    /// </summary>
     protected bool HasHub => HubState?.Exists == true;
+
+    /// <summary>
+    /// Gets a value indicating whether the resolved Hub flow exists and is active.
+    /// </summary>
     protected bool IsHubActive => HasHub && HubState?.IsActive == true;
+
+    /// <summary>
+    /// Gets a value indicating whether the resolved Hub flow has expired.
+    /// </summary>
     protected bool IsExpired => HubState?.IsExpired == true;
+
+    /// <summary>
+    /// Gets the error associated with the resolved Hub flow, if any.
+    /// </summary>
     protected HubErrorCode? Error => HubState?.Error;
 
     private string? _lastHubKey;
 
+    /// <inheritdoc />
     protected override async Task OnParametersSetAsync()
     {
         await base.OnParametersSetAsync();
@@ -46,6 +93,17 @@ protected override async Task OnParametersSetAsync()
         }
     }
 
+    /// <summary>
+    /// Resolves the Hub session identifier associated with the current navigation URI.
+    /// </summary>
+    /// <returns>
+    /// The raw Hub session identifier when present; otherwise, <see langword="null"/>.
+    /// </returns>
+    /// <remarks>
+    /// The default implementation reads <see cref="UAuthConstants.Query.Hub"/> from
+    /// the current query string. Derived layouts may override this method to provide
+    /// the Hub session identifier from another source.
+    /// </remarks>
     protected virtual string? ResolveHubKey()
     {
         var uri = Navigation.ToAbsoluteUri(Navigation.Uri);

src/client/CodeBeam.UltimateAuth.Client.Blazor/Components/Base/UAuthHubPageBase.cs

@@ -5,24 +5,77 @@
 
 namespace CodeBeam.UltimateAuth.Client.Blazor;
 
+/// <summary>
+/// Base class for Blazor pages that participate in an UltimateAuth Hub flow.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The page receives the Hub session identifier from the current query string
+/// and exposes the corresponding <see cref="HubFlowState"/> to derived pages.
+/// </para>
+/// <para>
+/// Hub state is obtained through <see cref="IHubFlowReader"/> and is automatically
+/// loaded when component parameters are processed. Derived pages can explicitly
+/// refresh the state by calling <see cref="ReloadStateAsync"/>.
+/// </para>
+/// <para>
+/// This type provides Hub flow state to the UI and does not itself authorize,
+/// complete, or otherwise make security decisions for the authentication flow.
+/// </para>
+/// </remarks>
 public abstract class UAuthHubPageBase : UAuthComponentBase
 {
+    /// <summary>
+    /// Gets the Hub flow reader used to retrieve the state of the current Hub session.
+    /// </summary>
     [Inject] protected IHubFlowReader HubFlowReader { get; set; } = default!;
 
+    /// <summary>
+    /// Gets or sets the raw Hub session identifier supplied by the current query string.
+    /// </summary>
+    /// <remarks>
+    /// The value is supplied from <see cref="UAuthConstants.Query.Hub"/>.
+    /// It is validated as a <see cref="HubSessionId"/> before Hub state is read.
+    /// </remarks>
     [Parameter]
     [SupplyParameterFromQuery(Name = UAuthConstants.Query.Hub)]
     public string? HubKey { get; set; }
 
+    /// <summary>
+    /// Gets the state associated with the current Hub session, when one can be resolved.
+    /// </summary>
+    /// <remarks>
+    /// The value is <see langword="null"/> when no Hub session identifier is supplied
+    /// or when the supplied identifier is invalid.
+    /// </remarks>
     protected HubFlowState? HubState { get; private set; }
 
+    /// <summary>
+    /// Gets a value indicating whether the resolved Hub flow exists and is active.
+    /// </summary>
     protected bool IsHubActive => HubState is { Exists: true, IsActive: true };
 
+    /// <inheritdoc />
     protected override async Task OnParametersSetAsync()
     {
         await base.OnParametersSetAsync();
         await ReloadStateAsync();
     }
 
+    /// <summary>
+    /// Reloads the Hub flow state associated with the current <see cref="HubKey"/>.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// When <see cref="HubKey"/> is missing, empty, or invalid, <see cref="HubState"/> is cleared.
+    /// </para>
+    /// <para>
+    /// A valid Hub session identifier is resolved through <see cref="IHubFlowReader"/>.
+    /// </para>
+    /// </remarks>
+    /// <returns>
+    /// A task that represents the asynchronous reload operation.
+    /// </returns>
     public async Task ReloadStateAsync()
     {
         if (string.IsNullOrWhiteSpace(HubKey))

src/client/CodeBeam.UltimateAuth.Client.Blazor/Components/Base/UAuthPageBase.cs

@@ -45,11 +45,12 @@ public abstract class UAuthPageBase : UAuthComponentBase
     private string? _lastParsedUri;
     private bool _payloadConsumed;
 
+    /// <inheritdoc />
     protected override void OnParametersSet()
     {
         base.OnParametersSet();
 
-        var currentUri = Nav.Uri;
+        var currentUri = Navigation.Uri;
 
         if (string.Equals(_lastParsedUri, currentUri, StringComparison.Ordinal))
             return;
@@ -58,7 +59,7 @@ protected override void OnParametersSet()
 
         _payloadConsumed = false;
 
-        var uri = Nav.ToAbsoluteUri(currentUri);
+        var uri = Navigation.ToAbsoluteUri(currentUri);
         var query = QueryHelpers.ParseQuery(uri.Query);
 
         ShouldFocus = query.TryGetValue(UAuthConstants.Query.Focus, out var focus) && focus == "1";
@@ -84,6 +85,7 @@ protected override void OnParametersSet()
         _needsClear = ClearUAuthQueryAfterParse && HasUAuthPageQuery(query);
     }
 
+    /// <inheritdoc />
     protected override async Task OnAfterRenderAsync(bool firstRender)
     {
         await base.OnAfterRenderAsync(firstRender);
@@ -99,8 +101,8 @@ protected override async Task OnAfterRenderAsync(bool firstRender)
             _needsClear = false;
             var cleanUri = BuildUriWithoutConsumedUAuthQuery();
 
-            if (!string.Equals(cleanUri, Nav.Uri, StringComparison.Ordinal))
-                Nav.NavigateTo(cleanUri, replace: true);
+            if (!string.Equals(cleanUri, Navigation.Uri, StringComparison.Ordinal))
+                Navigation.NavigateTo(cleanUri, replace: true);
         }
     }
 
@@ -135,12 +137,24 @@ protected bool TryConsumePayload(out AuthFlowPayload? payload)
         return true;
     }
 
+    /// <summary>
+    /// Called when a new UltimateAuth flow payload is available for the current page.
+    /// This method is called only once per parsed URL, and only when a valid payload is present.
+    /// </summary>
+    /// <param name="payload"></param>
+    /// <returns></returns>
     protected virtual Task OnUAuthPayloadAsync(AuthFlowPayload payload) => Task.CompletedTask;
+
+    /// <summary>
+    /// Called when a focus request is present for the current page.
+    /// This method is called only once per parsed URL, and only when a focus request is present.
+    /// </summary>
+    /// <returns></returns>
     protected virtual Task OnFocusRequestedAsync() => Task.CompletedTask;
 
     private string BuildUriWithoutConsumedUAuthQuery()
     {
-        var uri = Nav.ToAbsoluteUri(Nav.Uri);
+        var uri = Navigation.ToAbsoluteUri(Navigation.Uri);
         var query = QueryHelpers.ParseQuery(uri.Query);
 
         var remaining = query

src/client/CodeBeam.UltimateAuth.Client.Blazor/Components/UAuthApp.razor.cs

@@ -111,11 +111,13 @@ public partial class UAuthApp
     [Parameter]
     public EventCallback OnReauthRequired { get; set; }
 
+    /// <inheritdoc />
     protected override async Task OnInitializedAsync()
     {
         Coordinator.ReauthRequired += HandleReauthRequired;
     }
 
+    /// <inheritdoc />
     protected override async Task OnAfterRenderAsync(bool firstRender)
     {
         if (firstRender)
@@ -190,6 +192,10 @@ private IEnumerable<Assembly> GetAdditionalAssemblies()
         return Enumerable.Empty<Assembly>();
     }
 
+    /// <summary>
+    /// Disposes the component and stops the session coordinator if it was started.
+    /// </summary>
+    /// <returns></returns>
     public async ValueTask DisposeAsync()
     {
         StateManager.State.Changed -= OnStateChanged;