From 7f0f46983d1a1fb544d7b6f3b085d42ada18cfbd Mon Sep 17 00:00:00 2001 From: Paul Welter Date: Tue, 9 Jan 2024 10:12:15 -0600 Subject: [PATCH] add documentation --- src/Privileged/AuthorizationActions.cs | 6 ++ src/Privileged/AuthorizationBuilder.cs | 29 +++++++++ .../AuthorizationBuilderExtensions.cs | 63 +++++++++++++++++++ src/Privileged/AuthorizationContext.cs | 18 +++++- src/Privileged/AuthorizationRule.cs | 7 +++ src/Privileged/AuthorizationSubjects.cs | 6 ++ src/Privileged/IAuthorizationContext.cs | 42 +++++++++++++ 7 files changed, 170 insertions(+), 1 deletion(-) create mode 100644 src/Privileged/IAuthorizationContext.cs diff --git a/src/Privileged/AuthorizationActions.cs b/src/Privileged/AuthorizationActions.cs index 8f26373..eefa8c8 100644 --- a/src/Privileged/AuthorizationActions.cs +++ b/src/Privileged/AuthorizationActions.cs @@ -1,6 +1,12 @@ namespace Privileged; +/// +/// Authorization action defaults +/// public static class AuthorizationActions { + /// + /// Special keyword represents any action will be matched + /// public const string All = "all"; } diff --git a/src/Privileged/AuthorizationBuilder.cs b/src/Privileged/AuthorizationBuilder.cs index 2c03488..0c44c30 100644 --- a/src/Privileged/AuthorizationBuilder.cs +++ b/src/Privileged/AuthorizationBuilder.cs @@ -1,9 +1,22 @@ namespace Privileged; +/// +/// An builder +/// public class AuthorizationBuilder { private readonly List _rules = []; + /// + /// Create a rule allowing the specified , and optional . + /// + /// The action to allow. + /// The subject to allow. + /// The optional fields to allow. + /// The builder for chaining method calls + /// + /// Action or Subject cannot be null or whitespace. + /// public AuthorizationBuilder Allow(string action, string subject, IEnumerable? fields = null) { if (string.IsNullOrWhiteSpace(action)) @@ -18,6 +31,16 @@ public AuthorizationBuilder Allow(string action, string subject, IEnumerable + /// Create a rule forbidding the specified , and optional . + /// + /// The action to forbid. + /// The subject to forbid. + /// The optional fields to forbid. + /// The builder for chaining method calls + /// + /// Action or Subject cannot be null or whitespace. + /// public AuthorizationBuilder Forbid(string action, string subject, IEnumerable? fields = null) { if (string.IsNullOrWhiteSpace(action)) @@ -32,6 +55,12 @@ public AuthorizationBuilder Forbid(string action, string subject, IEnumerable + /// Creates the from the rules specified in or methods. + /// + /// An instance of with the specified rules + /// + /// public AuthorizationContext Build() { return new AuthorizationContext(_rules); diff --git a/src/Privileged/AuthorizationBuilderExtensions.cs b/src/Privileged/AuthorizationBuilderExtensions.cs index 5d155e5..2161b11 100644 --- a/src/Privileged/AuthorizationBuilderExtensions.cs +++ b/src/Privileged/AuthorizationBuilderExtensions.cs @@ -1,7 +1,20 @@ namespace Privileged; +/// +/// An builder extension methods +/// public static class AuthorizationBuilderExtensions { + /// + /// Create a rule allowing the specified , and optional . + /// + /// The builder. + /// The actions to allow. + /// The subjects to allow. + /// The optional fields to allow. + /// + /// The builder for chaining method calls + /// public static AuthorizationBuilder Allow(this AuthorizationBuilder builder, IEnumerable actions, IEnumerable subjects, IEnumerable? fields = null) { if (builder == null) @@ -27,6 +40,16 @@ public static AuthorizationBuilder Allow(this AuthorizationBuilder builder, IEnu return builder; } + /// + /// Create a rule allowing the specified , and optional . + /// + /// The builder. + /// The actions to allow. + /// The subject to allow. + /// The optional fields to allow. + /// + /// The builder for chaining method calls + /// public static AuthorizationBuilder Allow(this AuthorizationBuilder builder, IEnumerable actions, string subject, IEnumerable? fields = null) { if (builder == null) @@ -47,6 +70,16 @@ public static AuthorizationBuilder Allow(this AuthorizationBuilder builder, IEnu return builder; } + /// + /// Create a rule allowing the specified , and optional . + /// + /// The builder. + /// The action to allow. + /// The subjects to allow. + /// The optional fields to allow. + /// + /// The builder for chaining method calls + /// public static AuthorizationBuilder Allow(this AuthorizationBuilder builder, string action, IEnumerable subjects, IEnumerable? fields = null) { if (builder == null) @@ -67,6 +100,16 @@ public static AuthorizationBuilder Allow(this AuthorizationBuilder builder, stri return builder; } + /// + /// Create a rule forbidding the specified , and optional . + /// + /// The builder. + /// The actions to forbid. + /// The subjects to forbid. + /// The optional fields to forbid. + /// + /// The builder for chaining method calls + /// public static AuthorizationBuilder Forbid(this AuthorizationBuilder builder, IEnumerable actions, IEnumerable subjects, IEnumerable? fields = null) { if (builder == null) @@ -92,6 +135,16 @@ public static AuthorizationBuilder Forbid(this AuthorizationBuilder builder, IEn return builder; } + /// + /// Create a rule forbidding the specified , and optional . + /// + /// The builder. + /// The actions to forbid. + /// The subject to forbid. + /// The optional fields to forbid. + /// + /// The builder for chaining method calls + /// public static AuthorizationBuilder Forbid(this AuthorizationBuilder builder, IEnumerable actions, string subject, IEnumerable? fields = null) { if (builder == null) @@ -112,6 +165,16 @@ public static AuthorizationBuilder Forbid(this AuthorizationBuilder builder, IEn return builder; } + /// + /// Create a rule forbidding the specified , and optional . + /// + /// The builder. + /// The action to forbid. + /// The subjects to forbid. + /// The optional fields to forbid. + /// + /// The builder for chaining method calls + /// public static AuthorizationBuilder Forbid(this AuthorizationBuilder builder, string action, IEnumerable subjects, IEnumerable? fields = null) { if (builder == null) diff --git a/src/Privileged/AuthorizationContext.cs b/src/Privileged/AuthorizationContext.cs index af80643..d59a462 100644 --- a/src/Privileged/AuthorizationContext.cs +++ b/src/Privileged/AuthorizationContext.cs @@ -1,12 +1,26 @@ namespace Privileged; -public class AuthorizationContext(IReadOnlyCollection rules, StringComparer? stringComparer = null) +/// +/// The authorization context used to check privileges +/// +/// The authorization rules for this context +/// The used for matching names +/// +public class AuthorizationContext(IReadOnlyCollection rules, StringComparer? stringComparer = null) : IAuthorizationContext { + /// public IReadOnlyCollection Rules { get; } = rules ?? throw new ArgumentNullException(nameof(rules)); + /// + /// Gets the used for matching names. + /// + /// + /// The used for matching names. + /// public StringComparer StringComparer { get; } = stringComparer ?? StringComparer.InvariantCultureIgnoreCase; + /// public bool Authorized(string? action, string? subject, string? field = null) { if (action is null || subject is null) @@ -26,8 +40,10 @@ public bool Authorized(string? action, string? subject, string? field = null) return state ?? false; } + /// public bool Unauthorized(string? action, string? subject, string? field = null) => !Authorized(action, subject, field); + /// public IEnumerable MatchRules(string? action, string? subject, string? field = null) { if (action is null || subject is null) diff --git a/src/Privileged/AuthorizationRule.cs b/src/Privileged/AuthorizationRule.cs index 4e237de..f9aa921 100644 --- a/src/Privileged/AuthorizationRule.cs +++ b/src/Privileged/AuthorizationRule.cs @@ -1,5 +1,12 @@ namespace Privileged; +/// +/// An authorization rule +/// +/// The action to match for this rule +/// The subject to match for this rule +/// The field to match for this rule +/// true to make this a denied rule public record AuthorizationRule( string Action, string Subject, diff --git a/src/Privileged/AuthorizationSubjects.cs b/src/Privileged/AuthorizationSubjects.cs index f2fbb3e..3697861 100644 --- a/src/Privileged/AuthorizationSubjects.cs +++ b/src/Privileged/AuthorizationSubjects.cs @@ -1,6 +1,12 @@ namespace Privileged; +/// +/// Authorization subject defaults +/// public static class AuthorizationSubjects { + /// + /// Special keyword represents any subjects will be matched + /// public const string All = "all"; } diff --git a/src/Privileged/IAuthorizationContext.cs b/src/Privileged/IAuthorizationContext.cs new file mode 100644 index 0000000..59c81d7 --- /dev/null +++ b/src/Privileged/IAuthorizationContext.cs @@ -0,0 +1,42 @@ +namespace Privileged; + +/// +/// The authorization context definition used to check privileges +/// +public interface IAuthorizationContext +{ + /// + /// Gets the authorization rules for this context. + /// + /// + /// The authorization rules for this context. + /// + IReadOnlyCollection Rules { get; } + + /// + /// Check if the specified , and are authorized. + /// + /// The action to authorize. + /// The subject to authorize. + /// The optional field to authorize. + /// true if the specified , and are authorized; otherwise false + bool Authorized(string? action, string? subject, string? field = null); + + /// + /// Check if the specified , and are unauthorized. + /// + /// The action to authorize. + /// The subject to authorize. + /// The optional field to authorize. + /// true if the specified , and are unauthorized; otherwise false + bool Unauthorized(string? action, string? subject, string? field = null); + + /// + /// Find the rules for the specified , and + /// + /// The action to match. + /// The subject to match. + /// The optional field to match. + /// The rules for the specified , and + IEnumerable MatchRules(string? action, string? subject, string? field = null); +}