@polymorphism-tech/morph-spec 4.17.0 → 4.19.0

package/framework/standards/backend/integrations/clerk/clerk-auth.md

@@ -1,292 +0,0 @@
-# Clerk Authentication Integration Standard
-
-> **Scope:** universal
-> **Layer:** 2 (on keyword)
-> **Keywords:** clerk, auth, authentication, nextjs, user management
-> **Load When:** clerk authentication keywords detected
-
-Modern authentication and user management for Next.js applications.
-
----
-
-## Overview
-
-Clerk provides:
-- Pre-built UI components (SignIn, SignUp, UserProfile)
-- Social auth (Google, GitHub, etc.)
-- Multi-factor authentication
-- Session management
-- User metadata and organizations
-
-**Primary Use Case:** Next.js 15 + App Router
-
----
-
-## Core Principles
-
-1. **Server-First**: Use server-side auth checks with `auth()` helper
-2. **Route Protection**: Middleware-based protection for private routes
-3. **Type Safety**: Use Clerk's TypeScript types
-4. **Edge Compatible**: Works with Edge Runtime
-
----
-
-## Installation & Setup
-
-### Install Packages
-
-```bash
-npm install @clerk/nextjs
-```
-
-### Environment Variables
-
-```bash
-# .env.local
-NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
-CLERK_SECRET_KEY=sk_test_...
-NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
-NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
-NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/dashboard
-NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/onboarding
-```
-
-### Root Layout Wrapper
-
-```typescript
-// app/layout.tsx
-import { ClerkProvider } from '@clerk/nextjs';
-
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <ClerkProvider>
-      <html lang="en">
-        <body>{children}</body>
-      </html>
-    </ClerkProvider>
-  );
-}
-```
-
-### Middleware Protection
-
-```typescript
-// middleware.ts
-import { authMiddleware } from '@clerk/nextjs';
-
-export default authMiddleware({
-  publicRoutes: ['/', '/api/webhooks/clerk'],
-  ignoredRoutes: ['/api/public']
-});
-
-export const config = {
-  matcher: ['/((?!.+\\.[\\w]+$|_next).*)', '/', '/(api|trpc)(.*)'],
-};
-```
-
----
-
-## Common Patterns
-
-### Sign In Page
-
-```typescript
-// app/sign-in/[[...sign-in]]/page.tsx
-import { SignIn } from '@clerk/nextjs';
-
-export default function SignInPage() {
-  return (
-    <div className="flex items-center justify-center min-h-screen">
-      <SignIn />
-    </div>
-  );
-}
-```
-
-### Server-Side Auth Check
-
-```typescript
-// app/dashboard/page.tsx
-import { auth } from '@clerk/nextjs';
-import { redirect } from 'next/navigation';
-
-export default async function DashboardPage() {
-  const { userId } = auth();
-
-  if (!userId) {
-    redirect('/sign-in');
-  }
-
-  return <div>Dashboard for user {userId}</div>;
-}
-```
-
-### Client Component with User Data
-
-```typescript
-// components/UserProfile.tsx
-'use client';
-import { useUser } from '@clerk/nextjs';
-
-export function UserProfile() {
-  const { user, isLoaded, isSignedIn } = useUser();
-
-  if (!isLoaded) return <div>Loading...</div>;
-  if (!isSignedIn) return <div>Not signed in</div>;
-
-  return (
-    <div>
-      <p>Welcome, {user.firstName}!</p>
-      <p>Email: {user.primaryEmailAddress?.emailAddress}</p>
-    </div>
-  );
-}
-```
-
-### API Route Protection
-
-```typescript
-// app/api/protected/route.ts
-import { auth } from '@clerk/nextjs';
-
-export async function GET() {
-  const { userId } = auth();
-
-  if (!userId) {
-    return new Response('Unauthorized', { status: 401 });
-  }
-
-  // Fetch user-specific data
-  const data = await fetchUserData(userId);
-
-  return Response.json(data);
-}
-```
-
----
-
-## Webhook Integration
-
-### Setup Webhook Endpoint
-
-```typescript
-// app/api/webhooks/clerk/route.ts
-import { Webhook } from 'svix';
-import { headers } from 'next/headers';
-
-export async function POST(req: Request) {
-  const WEBHOOK_SECRET = process.env.CLERK_WEBHOOK_SECRET!;
-
-  const headerPayload = headers();
-  const svix_id = headerPayload.get('svix-id');
-  const svix_timestamp = headerPayload.get('svix-timestamp');
-  const svix_signature = headerPayload.get('svix-signature');
-
-  if (!svix_id || !svix_timestamp || !svix_signature) {
-    return new Response('Missing svix headers', { status: 400 });
-  }
-
-  const payload = await req.json();
-  const body = JSON.stringify(payload);
-
-  const wh = new Webhook(WEBHOOK_SECRET);
-
-  let evt;
-  try {
-    evt = wh.verify(body, {
-      'svix-id': svix_id,
-      'svix-timestamp': svix_timestamp,
-      'svix-signature': svix_signature,
-    });
-  } catch (err) {
-    return new Response('Invalid signature', { status: 400 });
-  }
-
-  // Handle events
-  switch (evt.type) {
-    case 'user.created':
-      await handleUserCreated(evt.data);
-      break;
-    case 'user.updated':
-      await handleUserUpdated(evt.data);
-      break;
-    case 'user.deleted':
-      await handleUserDeleted(evt.data);
-      break;
-  }
-
-  return new Response('OK');
-}
-```
-
----
-
-## Neon Integration
-
-### Sync Users to Neon PostgreSQL (via EF Core / Npgsql)
-
-```csharp
-// Services/ClerkUserSyncService.cs
-public sealed class ClerkUserSyncService(IDbContextFactory<AppDbContext> dbFactory)
-{
-    public async Task HandleUserCreatedAsync(ClerkUserData userData, CancellationToken ct)
-    {
-        await using var db = await dbFactory.CreateDbContextAsync(ct);
-
-        db.Profiles.Add(new Profile
-        {
-            ClerkUserId = userData.Id,
-            Email = userData.EmailAddresses[0].EmailAddress,
-            FirstName = userData.FirstName,
-            LastName = userData.LastName,
-            AvatarUrl = userData.ImageUrl
-        });
-
-        await db.SaveChangesAsync(ct);
-    }
-}
-```
-
----
-
-## Best Practices
-
-### Custom Claims
-
-```typescript
-// Add custom claims in Clerk Dashboard or via API
-const { sessionClaims } = auth();
-const role = sessionClaims?.metadata?.role as string;
-
-if (role !== 'admin') {
-  return new Response('Forbidden', { status: 403 });
-}
-```
-
-### Organizations
-
-```typescript
-import { auth } from '@clerk/nextjs';
-
-const { orgId, orgRole } = auth();
-
-if (!orgId) {
-  redirect('/create-organization');
-}
-
-if (orgRole !== 'admin') {
-  return <div>Admin access required</div>;
-}
-```
-
----
-
-## References
-
-- [Clerk Next.js Documentation](https://clerk.com/docs/nextjs)
-- [Clerk API Reference](https://clerk.com/docs/reference/backend-api)
-- [Webhooks Guide](https://clerk.com/docs/integrations/webhooks)
-
----
-
-*MORPH-SPEC by Polymorphism Tech*

package/framework/templates/integrations/clerk-config.cs

@@ -1,217 +0,0 @@
-// ==============================================================================
-// MORPH-SPEC - Clerk Authentication Configuration Template
-// Configuração de autenticação com Clerk para .NET
-// ==============================================================================
-
-using Microsoft.AspNetCore.Authentication;
-using System.Security.Claims;
-
-namespace {{Namespace}}.Infrastructure.Auth;
-
-// ==============================================================================
-// OPTIONS
-// ==============================================================================
-
-public class ClerkOptions
-{
-    public const string SectionName = "Clerk";
-
-    /// <summary>
-    /// Clerk Secret Key (starts with sk_)
-    /// </summary>
-    public string SecretKey { get; set; } = string.Empty;
-
-    /// <summary>
-    /// Clerk Publishable Key (starts with pk_)
-    /// </summary>
-    public string PublishableKey { get; set; } = string.Empty;
-
-    /// <summary>
-    /// Clerk Frontend API URL
-    /// </summary>
-    public string FrontendApi { get; set; } = string.Empty;
-}
-
-// ==============================================================================
-// SERVICE EXTENSIONS
-// ==============================================================================
-
-public static class ClerkServiceExtensions
-{
-    /// <summary>
-    /// Adiciona autenticação Clerk ao projeto
-    /// Requer: Clerk.Net.AspNetCore.Security
-    /// </summary>
-    public static IServiceCollection AddClerkAuthentication(
-        this IServiceCollection services,
-        IConfiguration configuration)
-    {
-        services.Configure<ClerkOptions>(configuration.GetSection(ClerkOptions.SectionName));
-
-        // Opção 1: Usando Clerk.Net SDK oficial
-        // services.AddClerk(configuration);
-
-        // Opção 2: Configuração manual com JWT
-        services.AddAuthentication("Clerk")
-            .AddJwtBearer("Clerk", options =>
-            {
-                var clerkOptions = configuration.GetSection(ClerkOptions.SectionName).Get<ClerkOptions>()!;
-
-                options.Authority = clerkOptions.FrontendApi;
-                options.TokenValidationParameters = new()
-                {
-                    ValidateIssuer = true,
-                    ValidateAudience = false,
-                    ValidateLifetime = true,
-                    ValidateIssuerSigningKey = true,
-                    NameClaimType = ClaimTypes.NameIdentifier
-                };
-            });
-
-        services.AddAuthorization();
-
-        return services;
-    }
-
-}
-
-// ==============================================================================
-// CLERK USER SERVICE
-// ==============================================================================
-
-public interface IClerkUserService
-{
-    Task<ClerkUser?> GetCurrentUserAsync(CancellationToken ct = default);
-    Task<ClerkUser?> GetUserByIdAsync(string userId, CancellationToken ct = default);
-    Task UpdateUserMetadataAsync(string userId, Dictionary<string, object> metadata, CancellationToken ct = default);
-}
-
-public class ClerkUserService : IClerkUserService
-{
-    private readonly HttpClient _httpClient;
-    private readonly IHttpContextAccessor _httpContextAccessor;
-    private readonly ILogger<ClerkUserService> _logger;
-
-    public ClerkUserService(
-        HttpClient httpClient,
-        IHttpContextAccessor httpContextAccessor,
-        ILogger<ClerkUserService> logger)
-    {
-        _httpClient = httpClient;
-        _httpContextAccessor = httpContextAccessor;
-        _logger = logger;
-    }
-
-    public async Task<ClerkUser?> GetCurrentUserAsync(CancellationToken ct = default)
-    {
-        var userId = _httpContextAccessor.HttpContext?.User.FindFirstValue(ClaimTypes.NameIdentifier);
-        if (string.IsNullOrEmpty(userId)) return null;
-
-        return await GetUserByIdAsync(userId, ct);
-    }
-
-    public async Task<ClerkUser?> GetUserByIdAsync(string userId, CancellationToken ct = default)
-    {
-        try
-        {
-            var response = await _httpClient.GetAsync($"users/{userId}", ct);
-
-            if (!response.IsSuccessStatusCode)
-            {
-                _logger.LogWarning("Failed to get Clerk user {UserId}: {Status}", userId, response.StatusCode);
-                return null;
-            }
-
-            return await response.Content.ReadFromJsonAsync<ClerkUser>(ct);
-        }
-        catch (Exception ex)
-        {
-            _logger.LogError(ex, "Error getting Clerk user {UserId}", userId);
-            return null;
-        }
-    }
-
-    public async Task UpdateUserMetadataAsync(string userId, Dictionary<string, object> metadata, CancellationToken ct = default)
-    {
-        var request = new { public_metadata = metadata };
-        var response = await _httpClient.PatchAsJsonAsync($"users/{userId}", request, ct);
-        response.EnsureSuccessStatusCode();
-    }
-}
-
-// ==============================================================================
-// CLERK USER MODEL
-// ==============================================================================
-
-public record ClerkUser
-{
-    public string Id { get; init; } = string.Empty;
-    public string? FirstName { get; init; }
-    public string? LastName { get; init; }
-    public string? ImageUrl { get; init; }
-    public List<ClerkEmailAddress>? EmailAddresses { get; init; }
-    public string? PrimaryEmailAddressId { get; init; }
-    public Dictionary<string, object>? PublicMetadata { get; init; }
-    public long CreatedAt { get; init; }
-    public long UpdatedAt { get; init; }
-
-    public string? PrimaryEmail => EmailAddresses?
-        .FirstOrDefault(e => e.Id == PrimaryEmailAddressId)?.EmailAddress;
-
-    public string FullName => $"{FirstName} {LastName}".Trim();
-}
-
-public record ClerkEmailAddress
-{
-    public string Id { get; init; } = string.Empty;
-    public string EmailAddress { get; init; } = string.Empty;
-    public bool Verified { get; init; }
-}
-
-// ==============================================================================
-// MIDDLEWARE PIPELINE
-// ==============================================================================
-
-public static class ClerkMiddlewareExtensions
-{
-    public static IApplicationBuilder UseClerkAuthentication(this IApplicationBuilder app)
-    {
-        app.UseAuthentication();
-        app.UseAuthorization();
-        return app;
-    }
-}
-
-// ==============================================================================
-// APPSETTINGS EXAMPLE
-// ==============================================================================
-
-/*
-{
-  "Clerk": {
-    "SecretKey": "sk_test_xxxxx",
-    "PublishableKey": "pk_test_xxxxx",
-    "FrontendApi": "https://your-app.clerk.accounts.dev"
-  }
-}
-*/
-
-// ==============================================================================
-// PROGRAM.CS EXAMPLE
-// ==============================================================================
-
-/*
-// Program.cs
-var builder = WebApplication.CreateBuilder(args);
-
-// Add Clerk authentication
-builder.Services.AddClerkAuthentication(builder.Configuration);
-
-var app = builder.Build();
-
-app.UseClerkAuthentication();
-
-app.MapControllers().RequireAuthorization();
-
-app.Run();
-*/