@polymorphism-tech/morph-spec 2.2.0 → 2.4.0

package/content/.claude/skills/integrations/clerk-auth.md

@@ -1,290 +1,108 @@
-# Clerk Auth
-
-Especialista em autenticação com Clerk para aplicações .NET/Blazor.
-
-## Responsabilidades
-
-1. **Configurar Clerk** em projetos .NET
-2. **Implementar autenticação** com SDK oficial
-3. **Gerenciar sessões** e tokens
-4. **Proteger endpoints** e páginas
-
-## Triggers
-
-Keywords: `clerk`, `auth`, `login`, `signup`, `authentication`, `session`, `jwt`, `user`
-
-## Sobre o Clerk
-
-- **Plataforma de autenticação** SaaS moderna
-- **SDK oficial C#** lançado em Janeiro/2025
-- **Suporta**: Email/senha, Social login, MFA, Passkeys
-- **Dashboard** para gerenciar usuários
-- **Ideal para**: SaaS B2C, MVPs rápidos
-
-## Instalação
-
-```bash
-dotnet add package Clerk.Net.AspNetCore.Security
-```
-
-## Configuração Básica
-
-```csharp
-// appsettings.json
-{
-  "Clerk": {
-    "SecretKey": "${CLERK_SECRET_KEY}",
-    "PublishableKey": "pk_test_xxx"  // Para frontend
-  }
-}
-
-// Program.cs
-builder.Services.AddClerk(builder.Configuration);
-
-// Ou manualmente
-builder.Services.AddClerk(options =>
-{
-    options.SecretKey = builder.Configuration["Clerk:SecretKey"]!;
-});
-
-// Adicionar autenticação
-builder.Services.AddAuthentication(ClerkAuthenticationDefaults.AuthenticationScheme)
-    .AddClerk(options =>
-    {
-        options.Authority = "https://clerk.{your-instance}.com";
-        options.ValidAudiences = new[] { "your-app-id" };
-    });
-
-builder.Services.AddAuthorization();
-
-// Pipeline
-app.UseAuthentication();
-app.UseAuthorization();
-```
-
-## Proteger Endpoints (Minimal API)
-
-```csharp
-// Endpoint protegido
-app.MapGet("/api/profile", async (ClaimsPrincipal user, IClerkClient clerk) =>
-{
-    var userId = user.FindFirstValue(ClaimTypes.NameIdentifier);
-
-    if (userId is null)
-        return Results.Unauthorized();
-
-    var clerkUser = await clerk.Users.GetUserAsync(userId);
-
-    return Results.Ok(new
-    {
-        Id = clerkUser.Id,
-        Email = clerkUser.EmailAddresses.FirstOrDefault()?.EmailAddress,
-        Name = $"{clerkUser.FirstName} {clerkUser.LastName}"
-    });
-})
-.RequireAuthorization();
-
-// Endpoint público
-app.MapGet("/api/public", () => "Hello World!")
-    .AllowAnonymous();
-```
-
-## Proteger Endpoints (Controllers)
-
-```csharp
-[ApiController]
-[Route("api/[controller]")]
-[Authorize]  // Requer autenticação
-public class ProfileController : ControllerBase
-{
-    private readonly IClerkClient _clerk;
-
-    public ProfileController(IClerkClient clerk)
-    {
-        _clerk = clerk;
-    }
-
-    [HttpGet]
-    public async Task<IActionResult> GetProfile()
-    {
-        var userId = User.FindFirstValue(ClaimTypes.NameIdentifier);
-
-        if (userId is null)
-            return Unauthorized();
-
-        var user = await _clerk.Users.GetUserAsync(userId);
-
-        return Ok(new
-        {
-            user.Id,
-            Email = user.EmailAddresses.FirstOrDefault()?.EmailAddress,
-            Name = $"{user.FirstName} {user.LastName}"
-        });
-    }
-
-    [HttpGet("admin")]
-    [Authorize(Roles = "admin")]  // Requer role admin
-    public IActionResult AdminOnly()
-    {
-        return Ok("Admin access granted");
-    }
-}
-```
-
-## Blazor Server
-
-```csharp
-// Program.cs
-builder.Services.AddClerk(builder.Configuration);
-builder.Services.AddAuthentication(ClerkAuthenticationDefaults.AuthenticationScheme)
-    .AddClerk();
-
-// App.razor
-<CascadingAuthenticationState>
-    <Router AppAssembly="@typeof(App).Assembly">
-        <Found Context="routeData">
-            <AuthorizeRouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)">
-                <NotAuthorized>
-                    <RedirectToLogin />
-                </NotAuthorized>
-            </AuthorizeRouteView>
-        </Found>
-    </Router>
-</CascadingAuthenticationState>
-
-// Components/RedirectToLogin.razor
-@inject NavigationManager Navigation
-
-@code {
-    protected override void OnInitialized()
-    {
-        Navigation.NavigateTo($"/sign-in?redirect_url={Uri.EscapeDataString(Navigation.Uri)}", forceLoad: true);
-    }
-}
-```
-
-## Páginas Protegidas
-
-```razor
-@* Pages/Dashboard.razor *@
-@page "/dashboard"
-@attribute [Authorize]
-
-<h1>Dashboard</h1>
-
-<AuthorizeView>
-    <Authorized>
-        <p>Bem-vindo, @context.User.Identity?.Name!</p>
-    </Authorized>
-</AuthorizeView>
-
-@* Verificar role específica *@
-<AuthorizeView Roles="admin">
-    <Authorized>
-        <AdminPanel />
-    </Authorized>
-    <NotAuthorized>
-        <p>Acesso restrito a administradores.</p>
-    </NotAuthorized>
-</AuthorizeView>
-```
-
-## Clerk Client para Operações
-
-```csharp
-// Buscar usuário
-var user = await _clerk.Users.GetUserAsync(userId);
-
-// Listar usuários
-var users = await _clerk.Users.GetUserListAsync(new()
-{
-    Limit = 10,
-    Offset = 0
-});
-
-// Atualizar metadata
-await _clerk.Users.UpdateUserMetadataAsync(userId, new()
-{
-    PublicMetadata = new Dictionary<string, object>
-    {
-        ["plan"] = "pro",
-        ["company"] = "Acme Inc"
-    }
-});
-
-// Deletar usuário
-await _clerk.Users.DeleteUserAsync(userId);
-```
-
-## Webhooks
-
-```csharp
-// Controllers/ClerkWebhookController.cs
-[ApiController]
-[Route("api/webhooks/clerk")]
-public class ClerkWebhookController : ControllerBase
-{
-    private readonly IUserService _userService;
-
-    public ClerkWebhookController(IUserService userService)
-    {
-        _userService = userService;
-    }
-
-    [HttpPost]
-    public async Task<IActionResult> HandleWebhook([FromBody] ClerkWebhookPayload payload)
-    {
-        // Verificar signature (importante em produção!)
-
-        switch (payload.Type)
-        {
-            case "user.created":
-                await _userService.SyncUserAsync(payload.Data);
-                break;
-
-            case "user.updated":
-                await _userService.UpdateUserAsync(payload.Data);
-                break;
-
-            case "user.deleted":
-                await _userService.DeleteUserAsync(payload.Data.Id);
-                break;
-        }
-
-        return Ok();
-    }
-}
-```
-
-## Clerk vs Azure Identity
-
-| Aspecto | Clerk | Azure Identity |
-|---------|-------|----------------|
-| **Setup** | Mais rápido | Mais complexo |
-| **Custo** | Freemium (5k MAU grátis) | Grátis (Azure AD) |
-| **Multi-tenant** | Built-in | Requer config |
-| **Social login** | 20+ providers | Limitado |
-| **UI components** | Pré-construídos | Precisa criar |
-| **Ideal para** | SaaS B2C | Enterprise/Azure |
-
-## Documentação de Referência
-
-- [Clerk C# SDK](https://clerk.com/changelog/2025-01-09-csharp-sdk)
-- [Clerk.Net GitHub](https://github.com/Hawxy/Clerk.Net)
-- [Clerk Documentation](https://clerk.com/docs)
-- [Webhooks](https://clerk.com/docs/integrations/webhooks)
-
-## Checklist de Integração
-
-- [ ] Secret Key no Key Vault (não hardcoded)
-- [ ] Publishable Key para frontend
-- [ ] Authentication scheme configurado
-- [ ] Authorization policies definidas
-- [ ] Webhook endpoint para sync de usuários
-- [ ] Verificação de webhook signature
-- [ ] Redirect após login configurado
-- [ ] Error handling para sessões expiradas
-
----
-
-*MORPH-SPEC by Polymorphism Tech*
+# Clerk Auth
+
+> **Layer:** 2 | **Load:** on-keyword | **Keywords:** clerk, auth, login, signup, authentication, session, jwt, user
+
+Autenticação SaaS com Clerk para .NET/Blazor. SDK: `Clerk.Net.AspNetCore.Security`.
+
+## Setup
+
+```csharp
+// appsettings.json
+{ "Clerk": { "SecretKey": "${CLERK_SECRET_KEY}", "PublishableKey": "pk_test_xxx" } }
+
+// Program.cs
+builder.Services.AddClerk(builder.Configuration);
+builder.Services.AddAuthentication(ClerkAuthenticationDefaults.AuthenticationScheme)
+    .AddClerk(o => { o.Authority = "https://clerk.{instance}.com"; o.ValidAudiences = ["your-app-id"]; });
+builder.Services.AddAuthorization();
+app.UseAuthentication();
+app.UseAuthorization();
+```
+
+## Protected Endpoints
+
+```csharp
+// Minimal API
+app.MapGet("/api/profile", async (ClaimsPrincipal user, IClerkClient clerk) =>
+{
+    var userId = user.FindFirstValue(ClaimTypes.NameIdentifier);
+    if (userId is null) return Results.Unauthorized();
+    var u = await clerk.Users.GetUserAsync(userId);
+    return Results.Ok(new { u.Id, Email = u.EmailAddresses.FirstOrDefault()?.EmailAddress });
+}).RequireAuthorization();
+
+// Controller: same pattern with [Authorize] + User.FindFirstValue()
+// Role-based: [Authorize(Roles = "admin")]
+```
+
+## Blazor Server
+
+> **Ref:** Same `CascadingAuthenticationState` + `AuthorizeRouteView` pattern as `azure-identity.md`
+
+```razor
+@* RedirectToLogin.razor *@
+@inject NavigationManager Nav
+@code {
+    protected override void OnInitialized() =>
+        Nav.NavigateTo($"/sign-in?redirect_url={Uri.EscapeDataString(Nav.Uri)}", forceLoad: true);
+}
+
+@* Protected page *@
+@page "/dashboard"
+@attribute [Authorize]
+<AuthorizeView><Authorized>Welcome, @context.User.Identity?.Name!</Authorized></AuthorizeView>
+<AuthorizeView Roles="admin"><Authorized><AdminPanel /></Authorized></AuthorizeView>
+```
+
+## Client Operations
+
+```csharp
+var user = await _clerk.Users.GetUserAsync(userId);                    // Get
+var users = await _clerk.Users.GetUserListAsync(new() { Limit = 10 }); // List
+await _clerk.Users.UpdateUserMetadataAsync(userId, new()               // Update metadata
+    { PublicMetadata = new Dictionary<string, object> { ["plan"] = "pro" } });
+await _clerk.Users.DeleteUserAsync(userId);                            // Delete
+```
+
+## Webhooks
+
+```csharp
+[ApiController, Route("api/webhooks/clerk")]
+public class ClerkWebhookController(IUserService users) : ControllerBase
+{
+    [HttpPost]
+    public async Task<IActionResult> Handle([FromBody] ClerkWebhookPayload payload)
+    {
+        switch (payload.Type)
+        {
+            case "user.created": await users.SyncUserAsync(payload.Data); break;
+            case "user.updated": await users.UpdateUserAsync(payload.Data); break;
+            case "user.deleted": await users.DeleteUserAsync(payload.Data.Id); break;
+        }
+        return Ok();
+    }
+}
+```
+
+## Clerk vs Azure Identity
+
+| Aspecto | Clerk | Azure Identity |
+|---------|-------|----------------|
+| Setup | Faster | More complex |
+| Cost | Freemium (5k MAU free) | Free (Azure AD) |
+| Social login | 20+ providers | Limited |
+| UI components | Pre-built | Build your own |
+| Best for | SaaS B2C, MVPs | Enterprise/Azure |
+
+## Checklist
+
+- [ ] Secret Key in Key Vault (not hardcoded)
+- [ ] Authentication scheme configured
+- [ ] Authorization policies defined
+- [ ] Webhook endpoint + signature validation
+- [ ] Redirect after login configured
+- [ ] Error handling for expired sessions
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/content/.claude/skills/integrations/resend-email.md

@@ -0,0 +1,119 @@
+# Resend Email
+
+> **Layer:** 2 | **Load:** on-keyword | **Keywords:** resend, email, envio, transactional, notification, send email, template
+
+Transactional email via Resend for .NET. REST API, no official SDK. Simple, developer-friendly.
+
+## Setup
+
+```csharp
+// appsettings.json
+{ "Resend": { "BaseUrl": "https://api.resend.com", "ApiKey": "${RESEND_API_KEY}", "FromEmail": "noreply@yourdomain.com" } }
+
+// Program.cs
+builder.Services.Configure<ResendOptions>(builder.Configuration.GetSection("Resend"));
+builder.Services.AddHttpClient<IResendClient, ResendClient>((sp, client) =>
+{
+    var options = sp.GetRequiredService<IOptions<ResendOptions>>().Value;
+    client.BaseAddress = new Uri(options.BaseUrl);
+    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", options.ApiKey);
+});
+```
+
+## Client Interface
+
+```csharp
+public interface IResendClient
+{
+    Task<EmailResponse> SendAsync(SendEmailRequest request, CancellationToken ct = default);
+    Task<EmailResponse> SendBatchAsync(IEnumerable<SendEmailRequest> requests, CancellationToken ct = default);
+    Task<EmailDetails> GetEmailAsync(string emailId, CancellationToken ct = default);
+}
+```
+
+Implementation: `HttpClient.PostAsJsonAsync("/emails")` + `ReadFromJsonAsync<EmailResponse>`. Log errors, throw `ResendException` on failure.
+
+## DTOs
+
+```csharp
+public record SendEmailRequest
+{
+    [JsonPropertyName("from")] public required string From { get; init; }
+    [JsonPropertyName("to")] public required string[] To { get; init; }
+    [JsonPropertyName("subject")] public required string Subject { get; init; }
+    [JsonPropertyName("html")] public string? Html { get; init; }
+    [JsonPropertyName("text")] public string? Text { get; init; }
+    [JsonPropertyName("reply_to")] public string? ReplyTo { get; init; }
+    [JsonPropertyName("tags")] public Tag[]? Tags { get; init; }
+}
+
+public record EmailResponse
+{
+    [JsonPropertyName("id")] public string Id { get; init; } = "";
+}
+
+public record Tag
+{
+    [JsonPropertyName("name")] public required string Name { get; init; }
+    [JsonPropertyName("value")] public required string Value { get; init; }
+}
+```
+
+## Webhooks
+
+```csharp
+[ApiController, Route("api/webhooks/resend")]
+public class ResendWebhookController(IEmailTrackingService tracking, ILogger<ResendWebhookController> logger) : ControllerBase
+{
+    [HttpPost]
+    public async Task<IActionResult> Handle([FromBody] ResendWebhookPayload payload)
+    {
+        logger.LogInformation("Resend webhook: {Type} for {EmailId}", payload.Type, payload.Data?.EmailId);
+        switch (payload.Type)
+        {
+            case "email.delivered": await tracking.MarkDeliveredAsync(payload.Data!.EmailId); break;
+            case "email.bounced": await tracking.MarkBouncedAsync(payload.Data!.EmailId); break;
+            case "email.complained": await tracking.MarkComplainedAsync(payload.Data!.EmailId); break;
+        }
+        return Ok();
+    }
+}
+```
+
+## Abstraction Pattern
+
+```csharp
+// Use IEmailService abstraction over IResendClient for testability
+public interface IEmailService
+{
+    Task<string> SendTransactionalAsync(string to, string subject, string htmlBody, CancellationToken ct = default);
+}
+
+// ResendEmailService implements IEmailService using IResendClient
+// FakeEmailClient implements IEmailService for simulation mode
+```
+
+## Gotchas
+
+| Issue | Fix |
+|-------|-----|
+| Rate limit: 100 req/sec (free), 1000 (pro) | Queue emails via Hangfire for bulk sends |
+| Domain verification required for production | Verify in Resend dashboard, add DNS records |
+| `from` must match verified domain | Use `noreply@yourdomain.com` |
+| HTML email rendering varies | Test with Litmus/Email on Acid, use MJML |
+| Webhook signature validation | Verify `svix-signature` header in production |
+
+## Checklist
+
+- [ ] API Key in Key Vault (not hardcoded)
+- [ ] HttpClient with `Authorization: Bearer` header
+- [ ] Domain verified in Resend dashboard
+- [ ] `IEmailService` abstraction for testability
+- [ ] Webhook endpoint + signature validation
+- [ ] Rate limiting handled (queue for bulk)
+- [ ] Tags used for tracking/analytics
+- [ ] Simulation mode (`FakeEmailClient`) for dev
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*