filiptrivan/spiderly/api-keys

[Index(nameof(KeyHash), IsUnique = true)]
[SpiderlyEntity]
public class ApiKey : BusinessObject<long>, IApiKey
{
    [UIDoNotGenerate]
    [Required]
    [StringLength(64, MinimumLength = 1)]
    public string KeyHash { get; set; }            // SHA-256 of the key; the plaintext is never stored
 
    [Required]
    [StringLength(100, MinimumLength = 1)]
    [DisplayName]
    public string Name { get; set; }
 
    // Creator — the principal (any kind) that minted this key. Audit metadata, auto-stamped at creation.
    // A soft reference (no FK): the creator can be any principal kind (User, ApiKey, ...), so it's stored
    // as principal id + kind rather than a typed navigation.
    [UIDoNotGenerate]
    public long CreatedById { get; set; }
 
    [UIDoNotGenerate]
    [Required]
    [StringLength(50, MinimumLength = 1)]
    public string CreatedByPrincipalKind { get; set; }
 
    public DateTime? ExpiresAt { get; set; }
 
    public bool? IsRevoked { get; set; }
 
    // ISecurityPrincipal: the key's authority is the union of its own roles' permissions (M2M, like User.Roles).
    public virtual List<Role> Roles { get; } = new(); // M2M
    IReadOnlyCollection<IRole> ISecurityPrincipal.Roles => Roles;
 
    public bool? IsDisabled { get; set; }
}

[M2M]
[SpiderlyEntity]
public class ApiKeyRole
{
    [M2MWithMany(nameof(ApiKey.Roles))]
    public virtual ApiKey ApiKey { get; set; }
 
    [M2MWithMany(nameof(Role.ApiKeys))]
    public virtual Role Role { get; set; }
}

[SpiderlyService]
public class ApiKeyService : ApiKeyServiceGenerated
{
    private readonly AuthenticationService _authenticationService;
    private readonly AuthorizationService _authorizationService;   // the app's most-derived authorization service
    private string _generatedPlainTextKey;
 
    public ApiKeyService(EntityServiceDependencies deps, AuthenticationService authenticationService, AuthorizationService authorizationService) : base(deps)
    {
        _authenticationService = authenticationService;
        _authorizationService = authorizationService;
    }
 
    protected override async Task OnBeforeSaveApiKeyAndReturnMainUIFormDTO(ApiKeySaveBodyDTO saveBodyDTO)
    {
        if (saveBodyDTO.ApiKeyDTO.Id <= 0)
        {
            string plainTextKey = ApiKeyHelper.GenerateRandomKey();
            saveBodyDTO.ApiKeyDTO.KeyHash = ApiKeyHelper.ComputeSha256Hash(plainTextKey);
            _generatedPlainTextKey = plainTextKey;
            // Principal id, not user id: a key can be minted by another key, and GetCurrentUserId()
            // refuses a machine principal (its id is not a user id).
            saveBodyDTO.ApiKeyDTO.CreatedById = _authenticationService.GetCurrentPrincipalId().Value;
            saveBodyDTO.ApiKeyDTO.CreatedByPrincipalKind = _authenticationService.GetCurrentPrincipalKind();
        }
        else
        {
            saveBodyDTO.ApiKeyDTO.KeyHash = await _deps.Context.DbSet<ApiKey>()
                .AsNoTracking().Where(x => x.Id == saveBodyDTO.ApiKeyDTO.Id).Select(x => x.KeyHash).FirstAsync();
        }
    }
 
    protected override async Task OnAfterSaveApiKeyAndReturnMainUIFormDTO(ApiKeySaveBodyDTO saveBodyDTO, ApiKeyMainUIFormDTO mainUIFormDTO)
    {
        if (_generatedPlainTextKey != null)
        {
            mainUIFormDTO.PlainTextKey = _generatedPlainTextKey;   // add this property via a partial ApiKeyMainUIFormDTO (Step 6)
            _generatedPlainTextKey = null;
        }
    }
 
    // Guard EVERY role-assignment path, not just the Generate endpoint: an admin may only grant a key roles
    // whose permissions they themselves hold. This is the M2M role-mutation method, so guarding it here covers
    // the admin roles editor (and any future caller) by construction.
    public override async Task UpdateRolesForApiKey(long id, List<int> selectedIds)
    {
        await _authorizationService.AuthorizeApiKeyRoleAssignmentAsync(selectedIds);
        await base.UpdateRolesForApiKey(id, selectedIds);
    }
}

spiderly.AddSecurity<User, UserExternalLogin, AuthorizationService>(s => s.AddApiKeys<ApiKey>());

/// <summary>
/// Issuance guard: the principal creating a key may only grant it roles whose permissions that principal
/// already holds, so a key can never be minted more powerful than its creator. The creator can be any
/// principal kind (a user, a service account, another key), so the ceiling is resolved principal-agnostically
/// via GetCurrentPrincipalPermissionCodesAsync() (not the User-typed GetCurrentUserPermissionCodes). No
/// runtime cap — a key authorizes through its own roles — so this is enforced once, at assignment.
/// </summary>
public async Task AuthorizeApiKeyRoleAssignmentAsync(List<int> roleIds)
{
    if (roleIds == null || roleIds.Count == 0)
        return;
 
    HashSet<string> creatorPermissions = (await GetCurrentPrincipalPermissionCodesAsync()).ToHashSet();
 
    List<string> targetRolePermissions = await _context.DbSet<Role>()
        .AsNoTracking()
        .Where(r => roleIds.Contains(r.Id))
        .SelectMany(r => r.Permissions)
        .Select(p => p.Code)
        .Distinct()
        .ToListAsync();
 
    if (!targetRolePermissions.All(p => creatorPermissions.Contains(p)))
        throw new BusinessException(_localizer["ApiKeyRoleExceedsYourPermissionsException"]);
}

// GenerateApiKeyRequestDTO:  string Name; int? ExpiresInDays; [Required] List<int> RoleIds = new();
// GenerateApiKeyResponseDTO: string Key; string Name; DateTime? ExpiresAt; [Required] List<int> RoleIds = new(); [Required] List<string> RoleNames = new();
// RevokeApiKeyRequestDTO:    [Required] long ApiKeyId;
// partial ApiKeyMainUIFormDTO (bare DTO namespace): [UIDoNotGenerate][StringLength(64)] string PlainTextKey;
 
[HttpPost, AuthGuard("InsertApiKey")]   // declared at the boundary; any principal kind holding the permission may create a key
public async Task<GenerateApiKeyResponseDTO> GenerateApiKey([FromBody] GenerateApiKeyRequestDTO request)
{
    long createdById = _authenticationService.GetCurrentPrincipalId().Value;