@polymorphism-tech/morph-spec 4.12.0 → 4.13.0

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

@@ -1,428 +0,0 @@
-# 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/framework/standards/backend/database/ef-core.md

@@ -1,199 +0,0 @@
-# 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*