ADR-004 — DB-backed role/permission resolution with IMemoryCache

Date: 2026-05-08 Status: Accepted

Context

A Fase 2 shipou InMemoryRolePermissionResolver — três roles hard-coded (Admin/Operator/Viewer) com permissões fixas no código. Comentários no DI explicitavam "TEMPLATE PLACEHOLDER — replace before production".

Custos do placeholder:

• Cada consumidor reescreve antes do primeiro deploy — mas há padrões comuns (tabela + cache) que poderiam viver no template.
• Cobertura de testes do path de autorização ficava amarrada às 3 roles fixas.
• Mudanças em roles exigiam deploy de código.

Patterns considerados para produção:

1. DB-backed — tabela RolePermissions(RoleName, Permission) com cache.
2. Config-driven InMemory — appsettings:Authorization:Roles lido por IOptionsMonitor, hot reload.
3. Identity Provider claims — role/permission claims emitidos pelo IdP.

Decision

DB-backed resolver com IMemoryCache em frente, shipado canon. Estrutura:

• Entidade RolePermission em Infrastructure/Authentication/ (composite PK RoleName + Permission, sem invariantes de domínio — pure infra).
• RolePermissionConfiguration mapeia a tabela e usa HasData para seed dos 3 roles canônicos (Admin/Operator/Viewer × Orders.*). HasData funciona tanto em migrations relacionais quanto em EF Core InMemory (via EnsureCreated), unificando dev + CI + prod.
• DbRolePermissionResolver lê por role com IMemoryCache (TTL 5 min). Hot path: 1 query por miss + lookups O(1).
• DI: AddMemoryCache() + AddDevPackRoleBasedPermissionEvaluator<DbRolePermissionResolver>().
• AppDbContext expõe DbSet<RolePermission> RolePermissions mas não o expõe via IAppDbContext — handlers de feature não devem queryar essa tabela diretamente; só o resolver lê.

Estender o catálogo:

1. Adicionar constante em Permissions.cs.
2. Estender RolePermissionConfiguration.HasData com novas linhas.
3. dotnet ef migrations add Add{NewRole}.

Multi-instance (Redis):

• Swap IMemoryCache por IDistributedCache no resolver — mesma superfície.

Consequences

Positivas:

• Template funcional out-of-the-box: rodar dotnet ef database update + ter usuário com claim de role já basta.
• Padrão único para todos os consumidores — menos drift entre projetos.
• Tests integration exercitam o caminho real (DbRolePermissionResolver + HasData seed via EnsureCreated).
• Cache reduz pressão sobre DB; TTL 5min é trade-off razoável entre frescor e custo.

Negativas:

• Adiciona uma tabela extra (RolePermissions) ao schema mínimo. Consumidores com permissões 100% IdP-driven precisam remover/ignorar.
• Cache local (IMemoryCache) em multi-instance fica até 5 min divergente após mudança — IDistributedCache resolve mas exige Redis.
• Mudança de role exige migration ou edição direta no DB.

Alternatives considered

Opção	Por que descartada
Manter InMemoryRolePermissionResolver placeholder	Cada consumidor reescreve; padrão fica perdido.
Config-driven InMemory (appsettings)	Hot reload é vantagem pequena; arquivo de config cresce sem governança.
Claims do IdP (sem tabela local)	Acopla auth à definição de permissions — mudanças exigem coordenação com o IdP team. Não impede uso futuro com claims (consumidor sobrescreve IRolePermissionResolver).

References

• CLAUDE.md § Role catalogue (RolePermission table).
• src/.../Infrastructure/Authentication/DbRolePermissionResolver.cs.
• src/.../Infrastructure/Persistence/Configurations/RolePermissionConfiguration.cs.
• DevPack ADR-004 (role-based permission resolution surface, originou daqui).