FactorBasedPermissions 0.0.2

Factor-Based Permissions (C#)

A flexible, attribute-driven authorization library that models permissions as combinations of factors. Designed for compact serialization to fit inside JWT tokens without bloating their size.

Why Factor-Based Permissions?

Traditional role-based access control (RBAC) often leads to role explosion. Factor-based permissions offer a more granular approach:

• Factors represent conditions (e.g., "email verified", "subscription active", "IP whitelisted")
• Permissions are granted when all required factors are satisfied
• Roles can grant sets of permissions declaratively via attributes

JWT-Optimized Serialization

The primary design goal is minimal payload size for embedding in JWT tokens:

Example: A policy with 10 permissions and 5 factors typically serializes to 30-50 characters — small enough to fit in a JWT claim without concern.

Installation

dotnet add package FactorBasedPermissions

Quick Start

1. Define Your Factors and Permissions

public enum Factor
{
    EmailVerified = 1,
    PhoneVerified = 2,
    SubscriptionActive = 3,
    TwoFactorEnabled = 4,
    AdminApproved = 5
}

public enum Permission
{
    [RequiresFactors(Factor.EmailVerified)]
    ViewDashboard = 1,

    [RequiresFactors(Factor.EmailVerified, Factor.SubscriptionActive)]
    DownloadReports = 2,

    [RequiresFactors(Factor.EmailVerified, Factor.TwoFactorEnabled)]
    ManageApiKeys = 3,

    [RequiresFactors(Factor.AdminApproved)]
    AccessAdminPanel = 4
}

2. Define Roles (Optional)

public enum Role
{
    [GrantsPermissions(
        Permission.ViewDashboard
    )]
    Guest = 1,

    [GrantsPermissions(
        Permission.ViewDashboard,
        Permission.DownloadReports,
        Permission.ManageApiKeys
    )]
    User = 2,

    [GrantsPermissions(
        Permission.ViewDashboard,
        Permission.DownloadReports,
        Permission.ManageApiKeys,
        Permission.AccessAdminPanel
    )]
    Admin = 3
}

3. Create and Serialize Permissions

// Factors satisfied by the current user (determined by your business logic)
var satisfiedFactors = new[] { Factor.EmailVerified, Factor.SubscriptionActive };

// Option A: From a role
var permissions = new FactorBasedPermissions<Factor, Permission>(satisfiedFactors, Role.User);

// Option B: From explicit permission list
var permissions = new FactorBasedPermissions<Factor, Permission>(
    satisfiedFactors,
    new[] { Permission.ViewDashboard, Permission.DownloadReports }
);

// Serialize for JWT
string serialized = permissions.Serialize();
// Example output: "!1,3#1+1&2+1,3"

4. Store in JWT

var claims = new[]
{
    new Claim("sub", userId),
    new Claim("ap", permissions.Serialize())  // "ap" = access policies
};

var token = new JwtSecurityToken(
    issuer: "your-app",
    audience: "your-app",
    claims: claims,
    expires: DateTime.UtcNow.AddHours(1),
    signingCredentials: credentials
);

5. Deserialize and Check (Server-Side)

// Extract from JWT claim
string serialized = User.FindFirst("ap")?.Value;

// Deserialize
var permissions = FactorBasedPermissions<Factor, Permission>.Deserialize(serialized);

// Check permissions
if (permissions.HasPermission(Permission.DownloadReports))
{
    // Access granted
}

// Check with detailed result
if (permissions.HasPermission(Permission.ManageApiKeys, out bool satisfied))
{
    // Permission exists in policy
    if (satisfied)
    {
        // All required factors are met
    }
    else
    {
        // Permission exists but factors not satisfied
    }
}
else
{
    // Permission not in policy at all
}

Serialization Format

The format is designed for minimal size while remaining debuggable:

[!<satisfied_factors>][#<permission_group_1>&<permission_group_2>&...]

Both sections are optional:

• If no factors are satisfied, the !... section is omitted
• If no permissions are defined, the #... section is omitted
• An empty policy serializes to an empty string ""

Structure

Number Encoding

All numeric IDs are encoded in Base32 using characters 0-9 and a-v:

Example Breakdown

!1,3#1+1&2+1,3

• !1,3 — Satisfied factors: 1 (EmailVerified), 3 (SubscriptionActive)
• #1+1 — Permission 1 (ViewDashboard) requires factor 1
• &2+1,3 — Permission 2 (DownloadReports) requires factors 1 and 3

Grouping Optimization

Permissions with identical required factors are grouped together:

// These three permissions all require factor 1:
Permission.A  // requires Factor.X
Permission.B  // requires Factor.X  
Permission.C  // requires Factor.X

// Serialized as: #1,2,3+1
// Instead of:    #1+1&2+1&3+1  (longer)

API Reference

FactorBasedPermissions<TFactorId, TPermissionId>

Constructors

// Empty instance
new FactorBasedPermissions<Factor, Permission>()

// From satisfied factors and permission lookup dictionary
new FactorBasedPermissions<Factor, Permission>(
    IEnumerable<Factor> satisfiedFactors,
    Dictionary<Permission, List<Factor>> permissionsLookup
)

// From satisfied factors and permissions (reads RequiresFactors attributes)
new FactorBasedPermissions<Factor, Permission>(
    IEnumerable<Factor> satisfiedFactors,
    IEnumerable<Permission> permissions
)

// From satisfied factors and role (reads GrantsPermissions attribute)
new FactorBasedPermissions<Factor, Permission>(
    IEnumerable<Factor> satisfiedFactors,
    Enum role
)

Properties

Methods

Static Methods

Attributes

RequiresFactorsAttribute

Apply to permission enum members to declare required factors:

// Generic version (type-safe)
[RequiresFactors<Factor>(Factor.A, Factor.B)]
SomePermission = 1

// Non-generic version (for dynamic scenarios)
[RequiresFactors(Factor.A, Factor.B)]
SomePermission = 1

GrantsPermissionsAttribute

Apply to role enum members to declare granted permissions:

// Generic version (type-safe)
[GrantsPermissions<Permission>(Permission.X, Permission.Y)]
SomeRole = 1

// Non-generic version
[GrantsPermissions(Permission.X, Permission.Y)]
SomeRole = 1

Advanced Usage

Custom Type Converters

You can provide custom converters when deserializing. This is especially useful for enum types to avoid boxing overhead and improve performance:

// Explicit converters are MUCH faster than implicit boxing conversion
var permissions = FactorBasedPermissions<AuthFactor, Permission>.Deserialize(
    serialized,
    factorConverter: id => (AuthFactor)id,
    permissionConverter: id => (Permission)id
);

For non-enum numeric types:

var permissions = FactorBasedPermissions<int, int>.Deserialize(
    serialized,
    factorConverter: id => (int)id,
    permissionConverter: id => (int)id
);

Comparing Permission Sets

var permissions1 = new FactorBasedPermissions<Factor, Permission>(factors1, Role.User);
var permissions2 = new FactorBasedPermissions<Factor, Permission>(factors2, Role.User);

if (permissions1.Same(permissions2))
{
    // Identical factors and permissions
}

Extension Methods

// Get required factors for any enum member
var factors = Permission.DownloadReports.GetRequiredFactors<Factor>();

// Get granted permissions for any role
var permissions = Role.Admin.GetGrantedPermissions<Permission>();

Best Practices

1. Consider Your Use of Value 0

// Option A: Start at 1 to distinguish from default/uninitialized
public enum Permission
{
    ViewDashboard = 1,
    DownloadReports = 2,
    ...
}

// Option B: Use 0 intentionally when it has semantic meaning
public enum AuthFactor
{
    AnyMethod = 0,      // Valid: "any authentication method"
    Password = 10,
    Google = 11,
    ...
}

Starting at 1 helps catch uninitialized values, but 0 is perfectly valid when it represents a meaningful concept.

2. Group Related Factors

Keep factor IDs grouped logically for easier debugging of serialized strings:

public enum Factor
{
    // Verification factors: 1-10
    EmailVerified = 1,
    PhoneVerified = 2,
    
    // Subscription factors: 11-20
    SubscriptionActive = 11,
    SubscriptionPremium = 12,
    
    // Security factors: 21-30
    TwoFactorEnabled = 21,
    ...
}

3. Use a DI Service for Permission Checks

Create a scoped service to lazily deserialize and cache permissions per request:

public class UserPermissions : IUserPermissions
{
    private readonly IHttpContextAccessor _httpContextAccessor;
    private FactorBasedPermissions<Factor, Permission>? _permissions;
    private bool _initialized;

    public UserPermissions(IHttpContextAccessor httpContextAccessor)
    {
        _httpContextAccessor = httpContextAccessor;
    }

    public FactorBasedPermissions<Factor, Permission>? Current
    {
        get
        {
            if (!_initialized)
            {
                _permissions = Deserialize();
                _initialized = true;
            }
            return _permissions;
        }
    }

    public bool HasPermission(Permission permission, bool? satisfiedFilter = true)
    {
        return Current?.HasPermission(permission, satisfiedFilter) ?? false;
    }

    private FactorBasedPermissions<Factor, Permission>? Deserialize()
    {
        var serialized = _httpContextAccessor.HttpContext?.User.FindFirst("ap")?.Value;

        if (serialized is null)
            return null;

        return FactorBasedPermissions<Factor, Permission>.Deserialize(serialized, ToFactor, ToPermission);

        static Factor ToFactor(uint x) => (Factor)x;
        static Permission ToPermission(uint x) => (Permission)x;
    }
}

public interface IUserPermissions
{
    FactorBasedPermissions<Factor, Permission> Current { get; }
    bool HasPermission(Permission permission, bool? satisfiedFilter = true);
}

// Registration
services.AddScoped<IUserPermissions, UserPermissions>();

Size Comparison

For JWTs that are sent with every HTTP request, this 5-8x size reduction matters.

Requirements

• .NET Standard 2.1+
• C# 11+

License

MIT