@polymorphism-tech/morph-spec 4.16.0 → 4.18.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/design-system/animations.md

@@ -146,6 +146,15 @@ else { <h2>@_title</h2> }
 - [ ] `@media (prefers-reduced-motion)` implemented
 - [ ] Shimmer for loading states
 
+## JavaScript Animation Libraries
+
+For animations beyond CSS capabilities:
+
+| Need | Library | Standard |
+|------|---------|----------|
+| Simple UI transitions (enter/exit, layout, gestures) | Framer Motion | `frontend/nextjs/motion-patterns.md` |
+| Complex animations (ScrollTrigger, SVG morph, timelines) | GSAP | `frontend/gsap/gsap-core.md` |
+
 ---
 
 *MORPH-SPEC by Polymorphism Tech*