@polymorphism-tech/morph-spec 4.17.0 → 4.19.0

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

@@ -0,0 +1,364 @@
+# Neon Auth (Better Auth) Integration Standard
+
+> **Scope:** universal
+> **Layer:** 2 (on keyword)
+> **Keywords:** neon auth, better auth, authentication, nextjs, user management, session, JWT
+> **Load When:** neon auth or authentication keywords detected
+
+Managed authentication powered by Better Auth, with all auth data stored directly in your Neon database (`neon_auth` schema). No external auth providers, no webhooks, no sync delays.
+
+---
+
+## Overview
+
+Neon Auth provides:
+- Pre-built UI components (AuthView, UserButton, SignedIn)
+- Social auth (Google, GitHub, etc.)
+- Session management with HTTP-only cookies
+- JWT tokens for Row-Level Security
+- Branch-isolated auth data (perfect for preview environments)
+- Database as single source of truth
+
+**Primary Use Case:** Next.js 15 + App Router + Neon PostgreSQL
+
+---
+
+## Core Principles
+
+1. **Database-First**: Auth data lives in `neon_auth` schema — no external service to sync
+2. **Branch Isolation**: Each Neon branch gets isolated users, sessions, and auth config
+3. **Server-First**: Use server-side auth checks with `auth.getSession()`
+4. **JWT for RLS**: Tokens contain `sub` (user ID), `email`, `role: "authenticated"` for database policies
+
+---
+
+## Installation & Setup
+
+### Install Packages
+
+```bash
+npm install @neondatabase/auth@latest
+```
+
+### Environment Variables
+
+```bash
+# .env.local
+NEON_AUTH_BASE_URL=https://ep-xxx.neonauth.us-east-2.aws.neon.build/neondb/auth
+NEON_AUTH_COOKIE_SECRET=your-secret-at-least-32-characters-long
+```
+
+Generate cookie secret:
+```bash
+openssl rand -base64 32
+```
+
+### SDK Initialization
+
+```typescript
+// lib/auth/client.ts
+'use client';
+import { createAuthClient } from '@neondatabase/auth/next';
+export const authClient = createAuthClient();
+
+// lib/auth/server.ts
+import { createNeonAuth } from '@neondatabase/auth/next/server';
+export const auth = createNeonAuth({
+  baseUrl: process.env.NEON_AUTH_BASE_URL!,
+  cookies: {
+    secret: process.env.NEON_AUTH_COOKIE_SECRET!,
+  },
+});
+```
+
+### Root Layout Provider
+
+```tsx
+// app/providers.tsx
+'use client';
+import { NeonAuthUIProvider } from '@neondatabase/auth/react';
+import '@neondatabase/auth/ui/css';
+import Link from 'next/link';
+import { useRouter } from 'next/navigation';
+import { authClient } from '@/lib/auth/client';
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  const router = useRouter();
+  return (
+    <NeonAuthUIProvider
+      authClient={authClient}
+      navigate={router.push}
+      replace={router.replace}
+      onSessionChange={router.refresh}
+      Link={Link}
+    >
+      {children}
+    </NeonAuthUIProvider>
+  );
+}
+```
+
+### Auth API Route
+
+```typescript
+// app/api/auth/[...path]/route.ts
+import { auth } from '@/lib/auth/server';
+
+export const { GET, POST } = auth.handler();
+```
+
+---
+
+## Common Patterns
+
+### Sign In / Sign Up Pages
+
+```tsx
+// app/auth/sign-in/page.tsx
+import { AuthView } from '@neondatabase/auth/react';
+
+export default function SignInPage() {
+  return (
+    <div className="flex items-center justify-center min-h-screen">
+      <AuthView pathname="sign-in" />
+    </div>
+  );
+}
+
+// app/auth/sign-up/page.tsx
+import { AuthView } from '@neondatabase/auth/react';
+
+export default function SignUpPage() {
+  return (
+    <div className="flex items-center justify-center min-h-screen">
+      <AuthView pathname="sign-up" />
+    </div>
+  );
+}
+```
+
+### Server-Side Auth Check
+
+```typescript
+// app/dashboard/page.tsx
+import { auth } from '@/lib/auth/server';
+import { redirect } from 'next/navigation';
+
+export const dynamic = 'force-dynamic';
+
+export default async function DashboardPage() {
+  const { data: session } = await auth.getSession();
+
+  if (!session?.user) {
+    redirect('/auth/sign-in');
+  }
+
+  return <div>Dashboard for {session.user.name || session.user.email}</div>;
+}
+```
+
+### Client Component with User Data
+
+```tsx
+// components/UserProfile.tsx
+'use client';
+import { useSession } from '@/lib/auth/client';
+
+export function UserProfile() {
+  const { data } = useSession();
+  const user = data?.user;
+
+  if (!user) return <div>Not signed in</div>;
+
+  return (
+    <div>
+      <p>Welcome, {user.name || user.email}!</p>
+    </div>
+  );
+}
+```
+
+### Route Protection (Middleware)
+
+```typescript
+// middleware.ts
+import { auth } from '@/lib/auth/server';
+
+export default auth.middleware({
+  loginUrl: '/auth/sign-in',
+});
+
+export const config = {
+  matcher: [
+    '/dashboard/:path*',
+    '/settings/:path*',
+    '/((?!_next/static|_next/image|favicon.ico|auth).*)',
+  ],
+};
+```
+
+### Component-Level Protection
+
+```tsx
+import { SignedIn, RedirectToSignIn } from '@neondatabase/auth/react';
+
+export default function ProtectedPage() {
+  return (
+    <>
+      <SignedIn>
+        <div>Protected content</div>
+      </SignedIn>
+      <RedirectToSignIn />
+    </>
+  );
+}
+```
+
+---
+
+## OAuth (Social Login)
+
+```typescript
+// Trigger OAuth sign-in
+await authClient.signIn.social({
+  provider: 'google',
+  callbackURL: 'http://localhost:3000/auth/callback',
+});
+```
+
+Configure OAuth providers in the Neon Console under Auth > Configuration.
+
+---
+
+## API Route Protection
+
+```typescript
+// app/api/protected/route.ts
+import { auth } from '@/lib/auth/server';
+
+export const dynamic = 'force-dynamic';
+
+export async function GET() {
+  const { data: session } = await auth.getSession();
+
+  if (!session?.user) {
+    return new Response('Unauthorized', { status: 401 });
+  }
+
+  return Response.json({ userId: session.user.id });
+}
+```
+
+---
+
+## .NET Backend Integration
+
+Neon Auth issues standard JWTs. The .NET API validates these tokens directly — no external auth SDK needed.
+
+### JWT Bearer Configuration
+
+```csharp
+// Program.cs
+builder.Services.AddAuthentication("NeonAuth")
+    .AddJwtBearer("NeonAuth", options =>
+    {
+        options.Authority = builder.Configuration["NeonAuth:BaseUrl"];
+        options.TokenValidationParameters = new()
+        {
+            ValidateIssuer = true,
+            ValidateAudience = false,
+            ValidateLifetime = true,
+            ValidateIssuerSigningKey = true,
+            NameClaimType = "sub"
+        };
+    });
+
+builder.Services.AddAuthorization();
+```
+
+### Protected Endpoints
+
+```csharp
+app.MapGet("/api/profile", (ClaimsPrincipal user) =>
+{
+    var userId = user.FindFirstValue("sub");
+    if (userId is null) return Results.Unauthorized();
+    return Results.Ok(new { UserId = userId });
+}).RequireAuthorization();
+```
+
+### appsettings.json
+
+```json
+{
+  "NeonAuth": {
+    "BaseUrl": "https://ep-xxx.neonauth.us-east-2.aws.neon.build/neondb/auth"
+  }
+}
+```
+
+---
+
+## Row-Level Security Integration
+
+Neon Auth JWT tokens are automatically validated by the Data API. The `auth.user_id()` function (via `pg_session_jwt` extension) exposes the authenticated user ID from the JWT `sub` claim.
+
+```sql
+-- Enable RLS
+ALTER TABLE public.documents ENABLE ROW LEVEL SECURITY;
+
+-- Users can only access their own rows
+CREATE POLICY "Users can view own documents"
+  ON public.documents FOR SELECT TO authenticated
+  USING (user_id = auth.user_id());
+
+CREATE POLICY "Users can insert own documents"
+  ON public.documents FOR INSERT TO authenticated
+  WITH CHECK (user_id = auth.user_id());
+```
+
+---
+
+## Database Schema
+
+Neon Auth automatically manages the `neon_auth` schema with these tables:
+- `neon_auth.user` — User profiles
+- `neon_auth.session` — Active sessions
+- `neon_auth.account` — Auth credentials (password hashes, OAuth tokens)
+
+You can query these tables directly for user data — no webhook sync needed:
+```sql
+SELECT id, email, name FROM neon_auth.user WHERE id = auth.user_id();
+```
+
+---
+
+## Branch Isolation
+
+Each Neon branch gets its own isolated auth data. This means:
+- Preview branches have separate users and sessions
+- Feature branches don't share auth state with production
+- Perfect for PR preview environments
+
+---
+
+## Best Practices
+
+1. **Always use `force-dynamic`** on pages/routes that call `auth.getSession()`
+2. **Cookie secret must be 32+ characters** — generate with `openssl rand -base64 32`
+3. **Use `auth.user_id()` for RLS** — never extract JWT claims manually in SQL
+4. **Configure OAuth in Neon Console** — not in code
+5. **Use `SignedIn` / `RedirectToSignIn`** for client-side protection
+6. **Use middleware** for broad route protection patterns
+
+---
+
+## References
+
+- [Neon Auth Documentation](https://neon.com/docs/auth)
+- [Neon Auth Authentication Flow](https://neon.com/docs/auth/authentication-flow)
+- [Migration from Legacy Auth](https://neon.com/docs/auth/migrate/from-legacy-auth)
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/standards/frontend/nextjs/nextjs-patterns.md

@@ -65,10 +65,12 @@ export default function Error({ error, reset }: { error: Error; reset: () => voi
 
 ```ts
 // app/api/documents/route.ts — BFF pattern (delegates to .NET API)
-import { auth } from "@clerk/nextjs/server";
+import { auth } from "@/lib/auth/server";
 import { NextResponse } from "next/server";
 import { z } from "zod";
 
+export const dynamic = "force-dynamic";
+
 const API_URL = process.env.API_URL!; // .NET backend
 
 const CreateSchema = z.object({
@@ -77,27 +79,25 @@ const CreateSchema = z.object({
 });
 
 export async function GET() {
-  const { userId, getToken } = await auth();
-  if (!userId) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  const { data: session } = await auth.getSession();
+  if (!session?.user) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
 
-  const token = await getToken();
   const res = await fetch(`${API_URL}/api/documents`, {
-    headers: { Authorization: `Bearer ${token}` },
+    headers: { Authorization: `Bearer ${session.session.access_token}` },
   });
   return NextResponse.json(await res.json());
 }
 
 export async function POST(request: Request) {
-  const { userId, getToken } = await auth();
-  if (!userId) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  const { data: session } = await auth.getSession();
+  if (!session?.user) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
 
   const parsed = CreateSchema.safeParse(await request.json());
   if (!parsed.success) return NextResponse.json({ error: parsed.error.flatten() }, { status: 400 });
 
-  const token = await getToken();
   const res = await fetch(`${API_URL}/api/documents`, {
     method: "POST",
-    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+    headers: { Authorization: `Bearer ${session.session.access_token}`, "Content-Type": "application/json" },
     body: JSON.stringify(parsed.data),
   });
   return NextResponse.json(await res.json(), { status: res.status });

package/framework/templates/README.md

@@ -77,7 +77,7 @@ framework/templates/
 ├── integrations/      # Platform-agnostic integrations
 │   ├── asaas-client.cs           # Asaas financial API
 │   ├── asaas-webhook.cs          # Asaas webhooks
-│   └── clerk-config.cs           # Clerk auth
+│   └── neon-auth-config.cs       # Neon Auth (Better Auth)
 │
 ├── ui/                # Design systems
 │   └── design-system.css         # CSS tokens
@@ -107,7 +107,7 @@ framework/templates/
 **Future-proof:** When we create `vue-firebase` stack, we can reuse:
 - `code/typescript/` templates
 - `infrastructure/docker/` templates
-- `integrations/` templates (Clerk, etc.)
+- `integrations/` templates (Neon Auth, etc.)
 
 **Only create NEW templates for Vue-specific code.**
 

package/framework/templates/REGISTRY.json

@@ -597,15 +597,15 @@
       ]
     },
     {
-      "id": "integration-clerk",
-      "name": "Clerk Authentication",
-      "path": "integrations/clerk-config.cs",
+      "id": "integration-neon-auth",
+      "name": "Neon Auth Configuration",
+      "path": "integrations/neon-auth-config.cs",
       "location": "framework",
       "category": "integration",
       "phase": "implement",
       "required": false,
-      "description": "Clerk authentication configuration",
-      "outputName": "ClerkConfig.cs",
+      "description": "Neon Auth (Better Auth) authentication configuration for .NET",
+      "outputName": "NeonAuthConfig.cs",
       "placeholders": [
         "NAMESPACE"
       ],

package/framework/templates/code/dotnet/jobs/agent.cs

@@ -5,7 +5,6 @@
 
 using System.ComponentModel;
 using System.Text.Json;
-using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 using Microsoft.Extensions.Logging;
 

package/framework/templates/code/sql/postgresql-migration.sql

@@ -65,27 +65,27 @@ create trigger set_{{TABLE_NAME}}_updated_at
 -- Enable RLS
 alter table public.{{TABLE_NAME}} enable row level security;
 
--- Users can read their own rows (Clerk JWT)
+-- Users can read their own rows (Neon Auth JWT via pg_session_jwt)
 create policy "Users can read own {{TABLE_NAME}}"
   on public.{{TABLE_NAME}}
-  for select
-  using (current_setting('request.jwt.claims')::json->>'sub' = user_id);
+  for select to authenticated
+  using (auth.user_id() = user_id);
 
 -- Users can insert rows for themselves
 create policy "Users can insert own {{TABLE_NAME}}"
   on public.{{TABLE_NAME}}
-  for insert
-  with check (current_setting('request.jwt.claims')::json->>'sub' = user_id);
+  for insert to authenticated
+  with check (auth.user_id() = user_id);
 
 -- Users can update their own rows
 create policy "Users can update own {{TABLE_NAME}}"
   on public.{{TABLE_NAME}}
-  for update
-  using (current_setting('request.jwt.claims')::json->>'sub' = user_id)
-  with check (current_setting('request.jwt.claims')::json->>'sub' = user_id);
+  for update to authenticated
+  using (auth.user_id() = user_id)
+  with check (auth.user_id() = user_id);
 
 -- Users can delete their own rows
 create policy "Users can delete own {{TABLE_NAME}}"
   on public.{{TABLE_NAME}}
-  for delete
-  using (current_setting('request.jwt.claims')::json->>'sub' = user_id);
+  for delete to authenticated
+  using (auth.user_id() = user_id);

package/framework/templates/code/sql/postgresql-migration.template.sql

@@ -70,28 +70,26 @@ create policy "{{TABLE_NAME}}_select_policy"
   on public.{{TABLE_NAME}} for select
   using (true);
 
--- Policy: Users can only insert their own records (Clerk JWT)
+-- Policy: Users can only insert their own records (Neon Auth + pg_session_jwt)
 -- create policy "{{TABLE_NAME}}_insert_policy"
---   on public.{{TABLE_NAME}} for insert
---   with check (current_setting('request.jwt.claims')::json->>'sub' = user_id);
+--   on public.{{TABLE_NAME}} for insert to authenticated
+--   with check (auth.user_id() = user_id);
 
--- Policy: Users can only update their own records (Clerk JWT)
+-- Policy: Users can only update their own records (Neon Auth + pg_session_jwt)
 -- create policy "{{TABLE_NAME}}_update_policy"
---   on public.{{TABLE_NAME}} for update
---   using (current_setting('request.jwt.claims')::json->>'sub' = user_id)
---   with check (current_setting('request.jwt.claims')::json->>'sub' = user_id);
+--   on public.{{TABLE_NAME}} for update to authenticated
+--   using (auth.user_id() = user_id)
+--   with check (auth.user_id() = user_id);
 
--- Policy: Users can only delete their own records (Clerk JWT)
+-- Policy: Users can only delete their own records (Neon Auth + pg_session_jwt)
 -- create policy "{{TABLE_NAME}}_delete_policy"
---   on public.{{TABLE_NAME}} for delete
---   using (current_setting('request.jwt.claims')::json->>'sub' = user_id);
+--   on public.{{TABLE_NAME}} for delete to authenticated
+--   using (auth.user_id() = user_id);
 
--- Policy: Admins have full access (Clerk JWT)
+-- Policy: Admins have full access (Neon Auth + pg_session_jwt)
 -- create policy "{{TABLE_NAME}}_admin_policy"
 --   on public.{{TABLE_NAME}} for all
---   using (
---     current_setting('request.jwt.claims')::json->>'role' = 'admin'
---   );
+--   using (auth.jwt()->>'role' = 'admin');
 
 -- ========================================
 -- Seed Data (Optional)

package/framework/templates/code/sql/postgresql-rls-policy.sql

@@ -40,18 +40,15 @@ create policy "{{POLICY_NAME}}_delete"
   using ({{USING_EXPRESSION}});
 
 -- ============================================================
--- Common USING / WITH CHECK expressions:
+-- Common USING / WITH CHECK expressions (Neon Auth + pg_session_jwt):
 --
--- Owner-based (Clerk JWT):
---   current_setting('request.jwt.claims')::json->>'sub' = user_id
+-- Owner-based:
+--   auth.user_id() = user_id
 --
--- Role-based (Clerk JWT):
---   current_setting('request.jwt.claims')::json->>'role' = 'admin'
---
--- Organization-based (Clerk JWT):
---   org_id = (current_setting('request.jwt.claims')::json->>'org_id')
+-- Role-based (extract from JWT claims):
+--   auth.jwt()->>'role' = 'admin'
 --
 -- Public read, owner write:
 --   SELECT using (true)
---   INSERT/UPDATE/DELETE using (current_setting('request.jwt.claims')::json->>'sub' = user_id)
+--   INSERT/UPDATE/DELETE using (auth.user_id() = user_id)
 -- ============================================================

package/framework/templates/feature/decisions.md

@@ -80,19 +80,20 @@ Need authentication for both Next.js frontend and .NET API.
 
 ### Decision
 
-Use Clerk for authentication on frontend. Validate JWT tokens in .NET API middleware.
+Use Neon Auth (Better Auth) for authentication. Auth data lives in the Neon database. JWT validated by .NET API middleware.
 
 ### Consequences
 
 **Pros:**
-- Single auth provider for both layers
-- RLS policies work with Clerk JWT claims via current_setting('request.jwt.claims')
-- Built-in social login, magic links, email/password
-- No separate auth service to maintain
+- Auth data in same database — no external provider, no sync delays
+- RLS policies work with Neon Auth JWT via auth.user_id() / pg_session_jwt
+- Built-in social login, email/password via @neondatabase/auth SDK
+- Branch isolation — each Neon branch gets isolated auth data
+- No webhooks needed — query neon_auth schema directly
 
 **Cons:**
-- Clerk JWT must be forwarded to database connections for RLS
-- JWT secret must be shared with .NET API
+- Neon Auth is currently in Beta
+- JWT must be forwarded to .NET API for backend auth
 {{/if}}
 
 ---