RepletoryLib.Data.Interceptors 1.0.0

RepletoryLib.Data.Interceptors

Attribute-driven EF Core interceptors for encryption, masking, validation, normalization, and data conversion.

Part of the RepletoryLib ecosystem -- standalone, reusable .NET 10 libraries with zero business logic.

Overview

RepletoryLib.Data.Interceptors provides a powerful attribute-driven system for applying cross-cutting concerns directly on EF Core entity properties. Instead of scattering encryption, validation, and normalization logic across services, you declare intent with attributes and the interceptors handle the rest during SaveChanges and materialization.

Three interceptors work together:

• AttributeInterceptor -- Processes all property-level attributes (validation, normalization, encryption, conversion, masking)
• AuditInterceptor -- Stamps CreatedAt, UpdatedAt, CreatedBy, UpdatedBy, and TenantId on BaseEntity instances
• SoftDeleteInterceptor -- Converts hard-delete operations into soft-deletes

Key Features

• 30+ attributes covering encryption, hashing, validation, normalization, masking, and data conversion
• Phase-based processing -- Validation runs before normalization, which runs before encryption
• Save and read phases -- Encryption on save, decryption on read; masking on read only
• South African validators -- ID number (Luhn), phone number, and phone format normalization
• Audit stamping -- Automatic CreatedAt/UpdatedAt/CreatedBy/UpdatedBy from ICurrentUserService
• PII tracking -- Mark fields as personally identifiable with optional auto-encryption

Installation

dotnet add package RepletoryLib.Data.Interceptors

Or add to your .csproj:

<PackageReference Include="RepletoryLib.Data.Interceptors" Version="1.0.0" />

Note: RepletoryLib packages are published to a local BaGet feed. See the main repository README for feed configuration.

Dependencies

Quick Start

1. Register interceptors

using RepletoryLib.Data.Interceptors;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRepletoryInterceptors(builder.Configuration);

2. Configure your DbContext to use interceptors

public class AppDbContext : DbContext
{
    private readonly IEnumerable<IInterceptor> _interceptors;

    public AppDbContext(DbContextOptions<AppDbContext> options, IEnumerable<IInterceptor> interceptors)
        : base(options)
    {
        _interceptors = interceptors;
    }

    protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
    {
        optionsBuilder.AddInterceptors(_interceptors);
    }
}

3. Decorate your entities

using RepletoryLib.Common.Entities;
using RepletoryLib.Data.Interceptors.Attributes;

public class Member : BaseEntity
{
    [NormalizeName]
    [Trim]
    public string FullName { get; set; } = string.Empty;

    [NormalizeEmail]
    [ValidateEmail]
    [AesEncrypt]
    public string Email { get; set; } = string.Empty;

    [NormalizePhone(PhoneFormat.E164)]
    [ValidateSaPhone]
    [MaskOnRead(MaskType.Phone)]
    public string PhoneNumber { get; set; } = string.Empty;

    [ValidateSaIdNumber]
    [AesEncrypt]
    [PiiField]
    public string IdNumber { get; set; } = string.Empty;
}

Configuration

InterceptorOptions

Section name: "Interceptors"

{
  "Interceptors": {
    "AesKey": "your-32-character-aes-256-key!!",
    "AesIv": "your-16-char-iv!",
    "EnableAuditStamping": true,
    "EnableSoftDelete": true,
    "AutoEncryptPii": false,
    "DefaultTimezone": "Africa/Johannesburg"
  }
}

Usage Examples

Complete Entity with All Attribute Types

using RepletoryLib.Common.Entities;
using RepletoryLib.Data.Interceptors.Attributes;

public class Customer : BaseEntity
{
    // Normalization
    [NormalizeName]
    [Trim]
    public string FullName { get; set; } = string.Empty;

    // Validation + Normalization + Encryption
    [NormalizeEmail]
    [ValidateEmail]
    [AesEncrypt]
    [PiiField]
    public string Email { get; set; } = string.Empty;

    // Phone formatting + Validation + Masking
    [NormalizePhone(PhoneFormat.E164)]
    [ValidateSaPhone]
    [MaskOnRead(MaskType.Phone)]
    public string PhoneNumber { get; set; } = string.Empty;

    // SA ID validation + Encryption + PII
    [ValidateSaIdNumber]
    [AesEncrypt]
    [PiiField]
    public string IdNumber { get; set; } = string.Empty;

    // Money stored as cents (decimal 150.50 -> long 15050)
    [MoneyInCents]
    [ValidateRange(0, 10_000_000)]
    public decimal MonthlyIncome { get; set; }

    // Complex type serialized as JSON
    [JsonSerialize]
    public List<string> Tags { get; set; } = new();

    // DateTime handling
    [StoreAsUtc]
    [DisplayInTimezone("Africa/Johannesburg")]
    public DateTime DateOfBirth { get; set; }

    // Password hashing (one-way)
    [HashStore(HashAlgorithmType.BCrypt)]
    public string Pin { get; set; } = string.Empty;

    // Enum stored as string
    [EnumToString]
    public CustomerStatus Status { get; set; }
}

What Happens During Save

When SaveChangesAsync is called, the AttributeInterceptor processes properties in phases:

1. Validation -- [ValidateEmail], [ValidateSaPhone], [ValidateSaIdNumber], [ValidateRange], [ValidateRequired] etc. Throws if validation fails.
2. Normalization -- [Trim], [NormalizeName], [NormalizeEmail], [NormalizePhone], [Uppercase], [Lowercase], [RemoveWhitespace], [TruncateAt]
3. Conversion -- [MoneyInCents], [StoreAsUtc], [EnumToString], [JsonSerialize], [CsvSerialize], [StoreDateOnly], [StoreAsUnixTimestamp]
4. Encryption/Hashing -- [AesEncrypt], [RsaEncrypt], [HashStore], [HmacSign], [Base64Encode], [Compress]

What Happens During Read

When entities are materialized from the database:

1. Decryption -- [AesEncrypt], [RsaEncrypt], [Base64Encode], [Compress] reverse their transformations
2. Conversion -- [MoneyInCents] converts cents back to decimal, [EnumToString] parses back to enum
3. Masking -- [MaskOnRead] masks sensitive values, [Redact] returns "[REDACTED]"
4. Display -- [DisplayInTimezone] converts UTC to the specified timezone

Audit Stamping

The AuditInterceptor automatically sets audit fields on BaseEntity instances:

// On Add:
entity.CreatedAt = DateTime.UtcNow;
entity.CreatedBy = currentUser.UserId;
entity.TenantId = currentUser.TenantId;

// On Update:
entity.UpdatedAt = DateTime.UtcNow;
entity.UpdatedBy = currentUser.UserId;

Soft-Delete Interception

The SoftDeleteInterceptor converts hard-deletes to soft-deletes:

// When you call:
context.Customers.Remove(customer);
await context.SaveChangesAsync();

// The interceptor changes it to:
customer.IsDeleted = true;
customer.DeletedAt = DateTime.UtcNow;
customer.DeletedBy = currentUser.UserId;
// Entity is NOT removed from the database

Attribute Reference

Validation Attributes (Save Phase)

Normalization Attributes (Save Phase)

Conversion Attributes (Save/Read)

Encryption & Encoding Attributes (Save/Read)

Privacy Attributes

Integration with Other RepletoryLib Packages

Testing

Interceptors are EF Core SaveChangesInterceptor instances. For unit testing, test the entity logic separately or use an in-memory database:

[Fact]
public void NormalizeName_attribute_applies_title_case()
{
    // Test the normalization logic directly
    var member = new Member { FullName = "  john  DOE  " };

    // After interceptor processing:
    // FullName should become "John Doe"
}

[Fact]
public void ValidateEmail_rejects_invalid_format()
{
    var member = new Member { Email = "not-an-email" };

    // SaveChangesAsync should throw due to [ValidateEmail]
}

Troubleshooting

License

This project is licensed under the MIT License.

Copyright (c) 2024-2026 Repletory.

For complete documentation, infrastructure setup, and configuration reference, see the RepletoryLib main repository.