@polymorphism-tech/morph-spec 4.16.0 → 4.18.0

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

@@ -1,290 +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');
-}
-```
-
----
-
-## Supabase Integration
-
-### Sync Users to Supabase
-
-```typescript
-// lib/clerk/sync-user.ts
-import { createClient } from '@supabase/supabase-js';
-
-async function handleUserCreated(userData: any) {
-  const supabase = createClient(
-    process.env.NEXT_PUBLIC_SUPABASE_URL!,
-    process.env.SUPABASE_SERVICE_ROLE_KEY!
-  );
-
-  await supabase.from('profiles').insert({
-    clerk_user_id: userData.id,
-    email: userData.email_addresses[0].email_address,
-    first_name: userData.first_name,
-    last_name: userData.last_name,
-    avatar_url: userData.image_url
-  });
-}
-```
-
----
-
-## 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/standards/infrastructure/supabase/mcp-setup.md

@@ -1,142 +0,0 @@
-# Supabase Local Development Guide
-
-> **Scope:** nextjs-supabase
-> **Layer:** 2 (on keyword)
-> **Keywords:** supabase, cli, local, docker, setup, migrations, psql
-> **Load When:** supabase setup keywords detected
-
-Local-first database management via Supabase CLI and psql — always targeting the local Docker instance.
-
-## CRITICAL WARNING
-
-```
-==========================================================
-  NEVER connect to a PRODUCTION Supabase project.
-
-  All database operations MUST target the local Docker
-  instance started via `npx supabase start`.
-
-  Production schema may diverge from local (renamed tables,
-  columns, migrations). Local is the single source of truth
-  during development.
-==========================================================
-```
-
-## Setup
-
-### 1. Install Supabase CLI
-
-```bash
-npm install -g supabase
-# or use npx (no global install needed)
-npx supabase --version
-```
-
-### 2. Start Local Instance
-
-```bash
-npx supabase start
-```
-
-This starts PostgreSQL, GoTrue (auth), Storage, and other services in Docker containers.
-
-### 3. Get Connection Details
-
-```bash
-npx supabase status
-```
-
-Output includes:
-- **DB URL**: `postgresql://postgres:postgres@127.0.0.1:54322/postgres` (port may vary)
-- **API URL**: `http://127.0.0.1:54321`
-- **anon key** and **service_role key** for local testing
-
-> **Important:** The port (54322) may vary when running multiple Supabase instances. Always use `npx supabase status` to get the current DB URL — never hardcode it.
-
-## Common CLI Commands
-
-### Schema Inspection
-
-```bash
-# Full schema dump
-npx supabase db dump --local --schema public
-
-# List tables (from dump output)
-npx supabase db dump --local --schema public 2>/dev/null | grep "CREATE TABLE"
-
-# Detailed table schema via psql
-psql $DB_URL -c "SELECT column_name, data_type, is_nullable, column_default \
-  FROM information_schema.columns WHERE table_name = 'TABLE_NAME' ORDER BY ordinal_position"
-
-# Foreign key relationships
-psql $DB_URL -c "SELECT tc.table_name, kcu.column_name, ccu.table_name AS foreign_table, \
-  ccu.column_name AS foreign_column FROM information_schema.table_constraints tc \
-  JOIN information_schema.key_column_usage kcu ON tc.constraint_name = kcu.constraint_name \
-  JOIN information_schema.constraint_column_usage ccu ON tc.constraint_name = ccu.constraint_name \
-  WHERE tc.constraint_type = 'FOREIGN KEY' AND tc.table_name = 'TABLE_NAME'"
-
-# RLS policies
-psql $DB_URL -c "SELECT tablename, policyname, cmd, qual FROM pg_policies WHERE schemaname = 'public'"
-
-# Indexes
-psql $DB_URL -c "SELECT indexname, indexdef FROM pg_indexes WHERE tablename = 'TABLE_NAME'"
-```
-
-### Migrations
-
-```bash
-# Create a new migration
-npx supabase migration new add_status_to_leads
-
-# Apply pending migrations to local
-npx supabase migration up --local
-
-# List applied migrations
-npx supabase migration list --local
-
-# Reset local database (destructive — re-applies all migrations)
-npx supabase db reset
-```
-
-### Data Operations
-
-```bash
-# Run arbitrary SQL against local
-psql $DB_URL -c "SELECT * FROM leads LIMIT 5"
-
-# Seed data
-npx supabase db seed --local
-```
-
-## Usage with MORPH-SPEC Workflow
-
-During MORPH-SPEC phases, the Supabase CLI is used for:
-
-| Phase | CLI Usage | Commands |
-|-------|-----------|----------|
-| **Phase 2 (Design)** | Inspect existing schema to inform spec | `npx supabase status` → `psql` queries |
-| **Phase 4 (Tasks)** | Verify migration dependencies | `npx supabase migration list --local` |
-| **Phase 5 (Implement)** | Apply migrations, verify RLS, test queries | `npx supabase migration up --local` + `psql` |
-| **Post-Implementation** | Verify RLS policies are correct | `psql` pg_policies queries |
-
-### Example Workflow
-
-```
-1. Design phase: `npx supabase status` → `psql $DB_URL` to inspect schema
-2. Write migration SQL in supabase/migrations/
-3. Apply: `npx supabase migration up --local`
-4. Verify: `psql $DB_URL -c "SELECT policyname, cmd FROM pg_policies WHERE tablename = 'search_logs'"`
-5. Test: `psql $DB_URL -c "SELECT * FROM search_logs LIMIT 5"`
-```
-
-## Best Practices
-
-1. **Always use local Supabase** (`npx supabase start`) — never connect to remote/production
-2. **Use `npx supabase status`** to detect the DB URL dynamically — port may vary
-3. **Write migrations as SQL files** in `supabase/migrations/` — apply via CLI
-4. **Verify RLS after every table change** — missing policies are a CRITICAL security issue
-5. **Reset local DB when needed** — `npx supabase db reset` re-applies all migrations cleanly
-
----
-
-*MORPH-SPEC by Polymorphism Tech*

package/framework/standards/infrastructure/supabase/supabase-auth.md

@@ -1,176 +0,0 @@
-# Supabase Authentication Standard
-
-> **Scope:** nextjs-supabase
-> **Layer:** 2 (on keyword)
-> **Keywords:** supabase, auth, rls, user, authentication
-> **Load When:** supabase auth keywords detected
-
-Stack: Next.js 15 + Supabase + .NET Backend
-
-## Core Rules
-
-- NEVER use `supabase.auth.getSession()` on server -- reads from cookies without validation
-- ALWAYS use `supabase.auth.getUser()` on server -- validates JWT with Supabase
-- NEVER expose `service_role` key on frontend -- bypasses RLS
-- ALWAYS use `@supabase/ssr` for Next.js -- not `@supabase/auth-helpers-nextjs` (deprecated)
-- ALWAYS use PKCE flow for SSR auth
-
-## Client Setup
-
-### Browser Client
-
-```ts
-// lib/supabase/client.ts
-import { createBrowserClient } from "@supabase/ssr";
-
-export function createClient() {
-  return createBrowserClient(
-    process.env.NEXT_PUBLIC_SUPABASE_URL!,
-    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
-  );
-}
-```
-
-### Server Client
-
-```ts
-// lib/supabase/server.ts
-import { createServerClient } from "@supabase/ssr";
-import { cookies } from "next/headers";
-
-export async function createClient() {
-  const cookieStore = await cookies();
-  return createServerClient(
-    process.env.NEXT_PUBLIC_SUPABASE_URL!,
-    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
-    {
-      cookies: {
-        getAll() { return cookieStore.getAll(); },
-        setAll(cookiesToSet) {
-          cookiesToSet.forEach(({ name, value, options }) =>
-            cookieStore.set(name, value, options));
-        },
-      },
-    }
-  );
-}
-```
-
-## Auth Flows
-
-```ts
-// Email/Password sign up
-await supabase.auth.signUp({ email, password,
-  options: { emailRedirectTo: `${origin}/auth/callback` } });
-
-// Email/Password sign in
-await supabase.auth.signInWithPassword({ email, password });
-
-// OAuth (Google / GitHub)
-await supabase.auth.signInWithOAuth({
-  provider: "google", // or "github"
-  options: { redirectTo: `${origin}/auth/callback`,
-    queryParams: { access_type: "offline", prompt: "consent" } } // Google-specific
-});
-
-// Magic Link
-await supabase.auth.signInWithOtp({ email,
-  options: { emailRedirectTo: `${origin}/auth/callback` } });
-```
-
-## Auth Callback Route (PKCE)
-
-```ts
-// app/auth/callback/route.ts
-import { createClient } from "@/lib/supabase/server";
-import { NextResponse } from "next/server";
-
-export async function GET(request: Request) {
-  const { searchParams, origin } = new URL(request.url);
-  const code = searchParams.get("code");
-  const next = searchParams.get("next") ?? "/dashboard";
-  if (code) {
-    const supabase = await createClient();
-    const { error } = await supabase.auth.exchangeCodeForSession(code);
-    if (!error) return NextResponse.redirect(`${origin}${next}`);
-  }
-  return NextResponse.redirect(`${origin}/auth/error`);
-}
-```
-
-## Middleware Pattern
-
-```ts
-// middleware.ts
-import { createServerClient } from "@supabase/ssr";
-import { NextResponse, type NextRequest } from "next/server";
-
-export async function middleware(request: NextRequest) {
-  let supabaseResponse = NextResponse.next({ request });
-  const supabase = createServerClient(
-    process.env.NEXT_PUBLIC_SUPABASE_URL!,
-    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
-    {
-      cookies: {
-        getAll() { return request.cookies.getAll(); },
-        setAll(cookiesToSet) {
-          cookiesToSet.forEach(({ name, value, options }) => {
-            request.cookies.set(name, value);
-            supabaseResponse.cookies.set(name, value, options);
-          });
-        },
-      },
-    }
-  );
-  const { data: { user } } = await supabase.auth.getUser();
-  if (!user && request.nextUrl.pathname.startsWith("/dashboard"))
-    return NextResponse.redirect(new URL("/login", request.url));
-  return supabaseResponse;
-}
-
-export const config = {
-  matcher: ["/((?!_next/static|_next/image|favicon.ico|api/webhooks).*)"],
-};
-```
-
-## .NET JWT Validation
-
-```csharp
-builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
-    .AddJwtBearer(options => {
-        options.TokenValidationParameters = new TokenValidationParameters {
-            ValidateIssuer = true,
-            ValidIssuer = $"https://{supabaseProjectRef}.supabase.co/auth/v1",
-            ValidateAudience = true,
-            ValidAudience = "authenticated",
-            ValidateIssuerSigningKey = true,
-            IssuerSigningKey = new SymmetricSecurityKey(
-                Encoding.UTF8.GetBytes(supabaseJwtSecret)),
-            ValidateLifetime = true,
-            ClockSkew = TimeSpan.FromSeconds(30)
-        };
-    });
-
-// Extract user ID: maps to auth.uid()
-var userId = User.FindFirstValue(ClaimTypes.NameIdentifier);
-```
-
-## Environment Variables
-
-| Variable | Where | Purpose |
-|----------|-------|---------|
-| `NEXT_PUBLIC_SUPABASE_URL` | Frontend | Supabase project URL |
-| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Frontend | Public anon key (respects RLS) |
-| `SUPABASE_SERVICE_ROLE_KEY` | Backend ONLY | Bypasses RLS -- NEVER on frontend |
-| `SUPABASE_JWT_SECRET` | Backend ONLY | JWT validation secret |
-
-## Common Mistakes
-
-| Wrong | Right | Why |
-|-------|-------|-----|
-| `getSession()` on server | `getUser()` on server | getSession reads unvalidated cookie data |
-| `@supabase/auth-helpers-nextjs` | `@supabase/ssr` | auth-helpers is deprecated |
-| `service_role` in `NEXT_PUBLIC_*` | `anon` key in `NEXT_PUBLIC_*` | service_role bypasses all RLS |
-| Implicit flow for SSR | PKCE flow with code exchange | Implicit exposes tokens in URL fragments |
-| Auth only in page components | Auth check in middleware.ts | Middleware prevents flash of content |
-| Missing `setAll` in cookie config | Both `getAll` and `setAll` | Session refresh silently fails without setAll |