@polymorphism-tech/morph-spec 4.7.0 → 4.7.2

package/.morph/framework/standards/backend/authentication/passkeys.md

@@ -0,0 +1,428 @@
+# Passkeys/WebAuthn - Autenticação Sem Senhas (.NET 10)
+
+> **Scope:** blazor-azure
+> **Layer:** 2 (on keyword)
+> **Keywords:** passkeys, azure entra, fido2, webauthn, authentication
+> **Load When:** passkeys or authentication keywords detected
+
+**Novidade .NET 10:** Suporte nativo a Passkeys/WebAuthn integrado no ASP.NET Core Identity.
+
+---
+
+## 🎯 O Que São Passkeys?
+
+**Passkeys** são credenciais criptográficas que substituem senhas tradicionais.
+
+### Características
+
+| Aspecto | Descrição |
+|---------|-----------|
+| **Segurança** | Resistentes a phishing, não podem ser roubadas |
+| **Usabilidade** | Login com biometria ou PIN do dispositivo |
+| **Privacidade** | Chave privada nunca sai do dispositivo |
+| **Padrão** | WebAuthn (W3C) + FIDO2 |
+
+### Como Funciona
+
+```
+1. Usuário solicita criação de passkey
+2. Sistema gera par de chaves (pública/privada)
+3. Chave pública → Servidor
+4. Chave privada → Authenticator (Windows Hello, smartphone, security key)
+5. Login: Servidor desafia → Authenticator assina → Servidor verifica
+```
+
+**Authenticators suportados:**
+- Windows Hello
+- Face ID / Touch ID (Apple)
+- Biometria Android
+- Security keys (YubiKey, etc.)
+
+---
+
+## 🚀 Setup em Blazor Web App
+
+### 1. Criar Projeto com Identity
+
+```bash
+dotnet new blazor --auth Individual -o MyApp
+cd MyApp
+```
+
+**Importante:** Escolher "Individual User Accounts" habilita passkeys automaticamente.
+
+### 2. Estrutura Gerada
+
+```
+MyApp/
+├── Components/
+│   └── Account/
+│       ├── Pages/
+│       │   ├── Manage/
+│       │   │   └── Passkeys.razor  ← Gerenciamento de passkeys
+│       │   ├── Login.razor         ← Login com passkey
+│       │   └── Register.razor
+│       └── IdentityUserAccessor.cs
+├── Data/
+│   ├── ApplicationDbContext.cs
+│   └── ApplicationUser.cs
+└── Program.cs
+```
+
+### 3. Configuração Automática no Program.cs
+
+```csharp
+// Já vem configurado no template
+builder.Services.AddIdentityCore<ApplicationUser>(options =>
+{
+    options.SignIn.RequireConfirmedAccount = true;
+
+    // Passkeys habilitados por padrão
+    options.Stores.MaxLengthForKeys = 128;
+})
+.AddEntityFrameworkStores<ApplicationDbContext>()
+.AddSignInManager()
+.AddDefaultTokenProviders();
+
+// WebAuthn/Passkeys configurado automaticamente
+builder.Services.AddAuthentication(options =>
+{
+    options.DefaultScheme = IdentityConstants.ApplicationScheme;
+    options.DefaultSignInScheme = IdentityConstants.ExternalScheme;
+})
+.AddIdentityCookies();
+```
+
+---
+
+## 📱 Fluxo de Uso
+
+### Criar Passkey
+
+1. Usuário loga com email/senha (primeira vez)
+2. Acessa perfil → Aba "Passkeys"
+3. Clica "Add Passkey"
+4. Sistema solicita authenticator (Windows Hello, celular, etc.)
+5. Usuário confirma identidade (biometria/PIN)
+6. Passkey é criada e nomeada
+7. Salva no banco de dados
+
+### Login com Passkey
+
+1. Usuário acessa página de login
+2. Clica "Login with Passkey"
+3. Sistema envia desafio
+4. Authenticator assina desafio
+5. Servidor verifica assinatura
+6. Usuário autenticado
+
+---
+
+## 💻 Implementação Customizada
+
+### Adicionar Passkeys a Projeto Existente
+
+Se você tem um projeto Blazor sem passkeys, use o **scaffolder**:
+
+```bash
+dotnet tool install -g dotnet-aspnet-codegenerator
+
+dotnet aspnet-codegenerator identity \
+    --useDefaultUI \
+    --dbContext ApplicationDbContext \
+    --files "Account.Manage.Passkeys;Account.Login"
+```
+
+Isso adiciona:
+- `Components/Account/Pages/Manage/Passkeys.razor`
+- `Components/Account/Pages/Login.razor` (atualizado)
+
+### Verificar Suporte a Passkeys
+
+```csharp
+@inject IPasskeyService PasskeyService
+
+@code {
+    private bool _supportsPasskeys;
+
+    protected override async Task OnInitializedAsync()
+    {
+        _supportsPasskeys = await PasskeyService.IsSupportedAsync();
+    }
+}
+```
+
+### Listar Passkeys do Usuário
+
+```csharp
+@page "/manage/passkeys"
+@inject IPasskeyService PasskeyService
+@inject UserManager<ApplicationUser> UserManager
+
+<h3>Minhas Passkeys</h3>
+
+@if (_passkeys is null)
+{
+    <p>Carregando...</p>
+}
+else if (!_passkeys.Any())
+{
+    <p>Você não tem passkeys configuradas.</p>
+}
+else
+{
+    <ul>
+        @foreach (var passkey in _passkeys)
+        {
+            <li>
+                @passkey.Name (@passkey.CreatedAt.ToString("dd/MM/yyyy"))
+                <button @onclick="() => RemovePasskey(passkey.Id)">Remover</button>
+            </li>
+        }
+    </ul>
+}
+
+<button @onclick="AddPasskey">Adicionar Passkey</button>
+
+@code {
+    private List<Passkey>? _passkeys;
+
+    protected override async Task OnInitializedAsync()
+    {
+        var user = await UserManager.GetUserAsync(User);
+        _passkeys = await PasskeyService.GetUserPasskeysAsync(user!.Id);
+    }
+
+    private async Task AddPasskey()
+    {
+        var user = await UserManager.GetUserAsync(User);
+        await PasskeyService.CreatePasskeyAsync(user!.Id);
+        await OnInitializedAsync(); // Recarregar lista
+    }
+
+    private async Task RemovePasskey(string passkeyId)
+    {
+        await PasskeyService.RemovePasskeyAsync(passkeyId);
+        await OnInitializedAsync(); // Recarregar lista
+    }
+}
+```
+
+---
+
+## 🗄️ Modelo de Dados
+
+### Entidade Passkey
+
+```csharp
+public class Passkey
+{
+    public string Id { get; set; } = Guid.NewGuid().ToString();
+    public string UserId { get; set; } = null!;
+    public string Name { get; set; } = "Passkey";
+    public byte[] CredentialId { get; set; } = Array.Empty<byte>();
+    public byte[] PublicKey { get; set; } = Array.Empty<byte>();
+    public int SignatureCounter { get; set; }
+    public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
+    public DateTime? LastUsedAt { get; set; }
+
+    // Relacionamento
+    public ApplicationUser User { get; set; } = null!;
+}
+```
+
+### DbContext
+
+```csharp
+public class ApplicationDbContext : IdentityDbContext<ApplicationUser>
+{
+    public DbSet<Passkey> Passkeys { get; set; }
+
+    protected override void OnModelCreating(ModelBuilder builder)
+    {
+        base.OnModelCreating(builder);
+
+        builder.Entity<Passkey>(entity =>
+        {
+            entity.HasKey(p => p.Id);
+            entity.HasIndex(p => p.UserId);
+            entity.HasIndex(p => p.CredentialId).IsUnique();
+
+            entity.HasOne(p => p.User)
+                .WithMany()
+                .HasForeignKey(p => p.UserId)
+                .OnDelete(DeleteBehavior.Cascade);
+        });
+    }
+}
+```
+
+### Migration
+
+```bash
+dotnet ef migrations add AddPasskeys
+dotnet ef database update
+```
+
+---
+
+## 🔒 Segurança
+
+### Configurações Recomendadas
+
+```csharp
+builder.Services.AddAuthentication()
+    .AddWebAuthn(options =>
+    {
+        // Nome do site (aparece no authenticator)
+        options.RelyingPartyId = "myapp.com";
+        options.RelyingPartyName = "My Application";
+
+        // Origem permitida
+        options.Origins = new[] { "https://myapp.com" };
+
+        // Timeout de autenticação
+        options.Timeout = TimeSpan.FromSeconds(60);
+
+        // Tipo de authenticator
+        options.AuthenticatorSelection = new()
+        {
+            RequireResidentKey = false,
+            UserVerification = UserVerificationRequirement.Preferred
+        };
+    });
+```
+
+### User Verification
+
+| Modo | Descrição | Quando Usar |
+|------|-----------|-------------|
+| `Required` | Exige biometria/PIN sempre | Alto risco |
+| `Preferred` | Prefere biometria mas aceita alternativa | Padrão recomendado |
+| `Discouraged` | Não solicita verificação | Não use |
+
+### Attestation
+
+```csharp
+options.Attestation = AttestationConveyancePreference.None;
+```
+
+**Valores:**
+- `None`: Não requer attestation (mais compatível)
+- `Indirect`: Valida authenticator via CA
+- `Direct`: Requer attestation direta (mais restritivo)
+
+**Recomendação:** Use `None` para máxima compatibilidade.
+
+---
+
+## 🧪 Testando Passkeys
+
+### Ambiente de Desenvolvimento
+
+1. **HTTPS obrigatório:** WebAuthn só funciona com HTTPS (ou localhost)
+2. **Windows Hello:** Habilite no Windows
+3. **Chrome DevTools:** Use Virtual Authenticator para testes
+
+### Virtual Authenticator (Chrome)
+
+1. F12 → More Tools → WebAuthn
+2. Enable virtual authenticator environment
+3. Add authenticator (escolha tipo: USB, NFC, Internal)
+4. Teste criação e login
+
+### Smartphone como Authenticator
+
+1. Use HTTPS (não localhost)
+2. Escaneie QR code gerado
+3. Confirme com biometria do celular
+
+---
+
+## 🐛 Troubleshooting
+
+### Erro: "WebAuthn not supported"
+
+**Causa:** Navegador antigo ou HTTP (não HTTPS)
+
+**Solução:**
+- Use HTTPS em produção
+- Localhost funciona com HTTP (somente dev)
+- Atualize navegador
+
+### Erro: "User verification failed"
+
+**Causa:** Authenticator não configurado ou cancelado
+
+**Solução:**
+- Configure Windows Hello / Touch ID
+- Tente outro authenticator
+- Verifique `UserVerification = Preferred`
+
+### Passkey não aparece em outro dispositivo
+
+**Causa:** Passkeys não sincronizam automaticamente (depende do authenticator)
+
+**Solução:**
+- Use authenticator com sync (ex: Google Password Manager)
+- Ou crie passkey separada por dispositivo
+
+---
+
+## 📊 Migração Gradual
+
+### Permitir Email/Senha + Passkeys
+
+```csharp
+// Login.razor
+<EditForm Model="Input" OnValidSubmit="LoginAsync">
+    <InputText @bind-Value="Input.Email" />
+    <InputText @bind-Value="Input.Password" type="password" />
+    <button type="submit">Login with Password</button>
+</EditForm>
+
+<hr />
+
+<button @onclick="LoginWithPasskey">Login with Passkey</button>
+
+@code {
+    private async Task LoginAsync()
+    {
+        // Login tradicional com senha
+    }
+
+    private async Task LoginWithPasskey()
+    {
+        // Login com WebAuthn
+    }
+}
+```
+
+**Estratégia:** Mantenha senha como fallback, incentive passkeys.
+
+---
+
+## ✅ Checklist de Implementação
+
+- [ ] Projeto criado com `--auth Individual` ou scaffolder usado
+- [ ] DbContext inclui tabela `Passkeys`
+- [ ] Migration executada
+- [ ] HTTPS habilitado (dev e prod)
+- [ ] Página de gerenciamento de passkeys funcional
+- [ ] Login com passkey funcional
+- [ ] Fallback para email/senha disponível
+- [ ] Testado com Windows Hello ou smartphone
+- [ ] `RelyingPartyId` configurado corretamente
+
+---
+
+## 📚 Referências
+
+- [WebAuthn Specification (W3C)](https://w3c.github.io/webauthn/)
+- [FIDO Alliance](https://fidoalliance.org/)
+- [ASP.NET Core Identity - Passkeys](https://learn.microsoft.com/aspnet/core/security/authentication/identity/passkeys)
+- [Chrome WebAuthn DevTools](https://developer.chrome.com/docs/devtools/webauthn/)
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/.morph/framework/standards/backend/database/ef-core.md

@@ -0,0 +1,199 @@
+# Blazor Server + EF Core
+
+> **Scope:** blazor-azure,nextjs-supabase
+> **Layer:** 1 (on domain)
+> **Keywords:** efcore, entity framework, dbcontext, dbfactory, concurrency
+> **Load When:** database work
+
+Patterns for Blazor Server + EF Core concurrency and background operations.
+
+---
+
+## Core Problem: DbContext Concurrency
+
+Blazor Server scoped services = circuit lifecycle (SignalR), NOT HTTP requests.
+`Task.Run` or fire-and-forget share the same scoped DbContext → concurrent access violations.
+
+**Rule:** Separate thread from HTTP request = isolated DbContext via `IDbContextFactory`.
+
+| Scenario | Pattern |
+|----------|---------|
+| Regular component ops | Scoped DbContext/Repository |
+| `Task.Run` / fire-and-forget | IDbContextFactory |
+| Hangfire / background jobs | IDbContextFactory |
+| SignalR hub handlers | IDbContextFactory |
+| Hosted services | IDbContextFactory |
+
+---
+
+## Pattern: Repository Factory
+
+```csharp
+// Interfaces
+public interface IOrderRepositoryBase
+{
+    Task<Order?> GetByIdAsync(Guid id, CancellationToken ct = default);
+    Task UpdateAsync(Order order, CancellationToken ct = default);
+}
+
+public interface IOrderRepository : IOrderRepositoryBase
+{
+    Task<List<Order>> GetPendingAsync(CancellationToken ct = default);
+}
+
+public interface IScopedOrderRepository : IOrderRepositoryBase, IAsyncDisposable { }
+
+public interface IOrderRepositoryFactory
+{
+    IScopedOrderRepository CreateScoped();
+}
+
+// Implementation
+public abstract class OrderRepositoryBase(AppDbContext context)
+{
+    protected readonly AppDbContext _context = context;
+
+    public async Task<Order?> GetByIdAsync(Guid id, CancellationToken ct = default)
+        => await _context.Orders.Include(o => o.Items).FirstOrDefaultAsync(o => o.Id == id, ct);
+
+    public async Task UpdateAsync(Order order, CancellationToken ct = default)
+    {
+        _context.Orders.Update(order);
+        await _context.SaveChangesAsync(ct);
+    }
+}
+
+public class ScopedOrderRepository(AppDbContext context) : OrderRepositoryBase(context), IScopedOrderRepository
+{
+    public async ValueTask DisposeAsync() => await _context.DisposeAsync();
+}
+
+public class OrderRepositoryFactory(IDbContextFactory<AppDbContext> contextFactory) : IOrderRepositoryFactory
+{
+    public IScopedOrderRepository CreateScoped() => new ScopedOrderRepository(contextFactory.CreateDbContext());
+}
+
+// DI
+builder.Services.AddDbContextFactory<AppDbContext>(o => o.UseSqlServer(conn));
+builder.Services.AddScoped<IOrderRepository, OrderRepository>();
+builder.Services.AddSingleton<IOrderRepositoryFactory, OrderRepositoryFactory>();
+
+// Usage
+_ = Task.Run(async () =>
+{
+    await using var repo = _repoFactory.CreateScoped();
+    var order = await repo.GetByIdAsync(orderId);
+    await repo.UpdateAsync(order);
+});
+```
+
+---
+
+## Background Operations Decision Matrix
+
+| Option | When | Cost | Complexity | Resilience |
+|--------|------|------|------------|------------|
+| Task.Run + RepositoryFactory | < 5min, low volume, non-critical | $0 | Low | Low |
+| Background Service + Queue | Long, needs retry, medium volume | $0-16/mo | Medium | Medium |
+| Hangfire | Scheduled/recurring, needs dashboard | $0 (OSS) | Medium | High |
+| Azure Functions Durable | High volume, spikes, orchestration | Pay-per-use | Med-High | High |
+
+### Hangfire Quick Setup
+
+```csharp
+builder.Services.AddHangfire(c => c.UseSqlServerStorage(conn));
+builder.Services.AddHangfireServer();
+
+public class OrderJob(IOrderRepositoryFactory repoFactory)
+{
+    [AutomaticRetry(Attempts = 3)]
+    public async Task ProcessAsync(Guid id, CancellationToken ct)
+    {
+        await using var repo = repoFactory.CreateScoped();
+        var order = await repo.GetByIdAsync(id, ct);
+    }
+}
+
+BackgroundJob.Enqueue<OrderJob>(x => x.ProcessAsync(orderId, CancellationToken.None));
+RecurringJob.AddOrUpdate<ReportJob>("daily", x => x.GenerateAsync(), Cron.Daily);
+```
+
+---
+
+## EF Core Configuration
+
+### Navigation Properties
+
+```csharp
+// WRONG - Include() silently fails
+builder.HasMany<GeneratedArt>().WithOne(x => x.Order).HasForeignKey(x => x.OrderId);
+
+// CORRECT - Specify navigation property
+builder.HasMany(x => x.GeneratedArts).WithOne(x => x.Order).HasForeignKey(x => x.OrderId);
+```
+
+**Rule:** `ICollection<T>` in entity → MUST appear in `HasMany(x => x.Property)`.
+
+### Migrations (.NET 10)
+
+```bash
+dotnet ef migrations add <Name> --project src/Infrastructure --startup-project src/Web
+dotnet ef database update --project src/Infrastructure --startup-project src/Web
+```
+
+| Environment | Auto-Migration? | Why |
+|-------------|----------------|-----|
+| Development | OK | Fast iteration |
+| Staging | Caution | Test before prod |
+| Production | NO | Use CI/CD pipeline |
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Fix |
+|-------------|-----|
+| Scoped DbContext in `Task.Run` | Use `IDbContextFactory` |
+| Scoped service in singleton | Use factory pattern |
+| Missing `await using` | Always use with scoped repo |
+| `IScopedRepo` inherits full `IRepo` | Inherit only `IBase` |
+
+---
+
+## Checklist
+
+- [ ] Background ops use `IDbContextFactory` / Repository Factory?
+- [ ] Duration/volume assessed against decision matrix?
+- [ ] `HasMany` uses navigation property lambda?
+- [ ] Migration created before `database update`?
+- [ ] `await using` for scoped repositories?
+- [ ] `AsNoTracking()` for read-only queries?
+- [ ] CancellationToken propagated?
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*
+
+---
+
+## Code Review Checklist
+
+Use this checklist during code review for EF Core in Blazor:
+
+### DbContext and Concurrency
+
+- [ ] **No scoped DbContext used in `Task.Run` or background operations?**
+- [ ] **`IDbContextFactory<T>` used for background/parallel operations?**
+- [ ] **Factory-created contexts are properly disposed (`await using`)?**
+- [ ] **No shared DbContext between concurrent operations?**
+
+### File Upload (IBrowserFile)
+
+- [ ] **`IBrowserFile` is read only ONCE and bytes stored?**
+- [ ] **`maxAllowedSize` specified in `OpenReadStream()`?**
+- [ ] **File size validated BEFORE opening stream?**
+- [ ] **File extension/type validated?**
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*