@polymorphism-tech/morph-spec 4.15.0 → 4.17.0

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 |

package/framework/standards/infrastructure/supabase/supabase-custom-jwt.md

@@ -1,206 +0,0 @@
-# Supabase Custom JWT Standard
-
-> **Scope:** dotnet, nextjs
-> **Layer:** 2 (on keyword)
-> **Keywords:** JWT, custom JWT, JWT signing, token creation, JWT claims, custom claims
-> **Load When:** custom JWT patterns detected (e.g., custom claims, manual token creation)
-
-## JWT Token Creation
-
-### Node.js (jose)
-
-```ts
-import { SignJWT } from "jose";
-
-const secret = new TextEncoder().encode(process.env.SUPABASE_JWT_SECRET!);
-
-export async function createCustomJWT(userId: string, claims: Record<string, unknown>) {
-  return new SignJWT({
-    sub: userId,
-    role: "authenticated",
-    app_metadata: claims,
-    aud: "authenticated",
-  })
-    .setProtectedHeader({ alg: "HS256", typ: "JWT" })
-    .setIssuedAt()
-    .setExpirationTime("1h")
-    .sign(secret);
-}
-```
-
-### .NET (System.IdentityModel.Tokens.Jwt)
-
-```csharp
-using System.IdentityModel.Tokens.Jwt;
-using System.Security.Claims;
-using Microsoft.IdentityModel.Tokens;
-
-public static string CreateCustomJWT(string userId, Dictionary<string, string> appMetadata)
-{
-    var key = new SymmetricSecurityKey(
-        Encoding.UTF8.GetBytes(Environment.GetEnvironmentVariable("SUPABASE_JWT_SECRET")!));
-
-    var claims = new List<Claim>
-    {
-        new(JwtRegisteredClaimNames.Sub, userId),
-        new("role", "authenticated"),
-        new("aud", "authenticated"),
-    };
-
-    // Add app_metadata claims
-    foreach (var (k, v) in appMetadata)
-        claims.Add(new Claim($"app_metadata.{k}", v));
-
-    var token = new JwtSecurityToken(
-        claims: claims,
-        expires: DateTime.UtcNow.AddHours(1),
-        signingCredentials: new SigningCredentials(key, SecurityAlgorithms.HmacSha256));
-
-    return new JwtSecurityTokenHandler().WriteToken(token);
-}
-```
-
-## Custom Claims Structure
-
-### Required Claims
-
-| Claim | Description | Example |
-|-------|-------------|---------|
-| `sub` | User ID (UUID) | `"a1b2c3d4-..."` |
-| `role` | Supabase role | `"authenticated"` |
-| `aud` | Audience | `"authenticated"` |
-| `exp` | Expiration (epoch) | `1710000000` |
-
-### Recommended App Metadata Claims
-
-| Claim | Purpose | Used By |
-|-------|---------|---------|
-| `tenant_id` | Multi-tenant RLS filtering | RLS policies |
-| `org_id` | Organization scoping | RLS policies |
-| `permissions` | Fine-grained access | Application logic |
-
-### Structure
-
-```json
-{
-  "sub": "user-uuid",
-  "role": "authenticated",
-  "aud": "authenticated",
-  "iat": 1710000000,
-  "exp": 1710003600,
-  "app_metadata": {
-    "tenant_id": "tenant-uuid",
-    "org_id": "org-uuid",
-    "permissions": ["read", "write"]
-  }
-}
-```
-
-**RLS Integration:** Always include `tenant_id` in `app_metadata` for RLS policies. Access in SQL via:
-
-```sql
--- In RLS policy
-(auth.jwt() -> 'app_metadata' ->> 'tenant_id')::uuid = tenant_id
-```
-
-Cross-ref: [supabase-rls.md](supabase-rls.md)
-
-## JWT Refresh Patterns
-
-### Token Rotation (Recommended)
-
-1. Issue short-lived access tokens (1h max)
-2. Use refresh tokens with rotation enabled
-3. Invalidate old refresh token on each rotation
-4. Store refresh tokens server-side only — never expose to client JS
-
-### Node.js Refresh Flow
-
-```ts
-import { createClient } from "@supabase/supabase-js";
-
-const supabase = createClient(url, anonKey);
-
-// On auth state change, handle token refresh
-supabase.auth.onAuthStateChange((event, session) => {
-  if (event === "TOKEN_REFRESHED" && session) {
-    // Update server-side session cookie
-    updateSessionCookie(session.access_token, session.refresh_token);
-  }
-});
-```
-
-### .NET Refresh Flow
-
-```csharp
-// Validate and refresh on each request via middleware
-public async Task InvokeAsync(HttpContext context)
-{
-    var token = context.Request.Headers.Authorization.ToString().Replace("Bearer ", "");
-
-    var handler = new JwtSecurityTokenHandler();
-    var jwt = handler.ReadJwtToken(token);
-
-    // If token expires within 5 minutes, trigger refresh
-    if (jwt.ValidTo < DateTime.UtcNow.AddMinutes(5))
-    {
-        var newToken = await RefreshTokenAsync(jwt.Subject);
-        context.Response.Headers.Append("X-New-Token", newToken);
-    }
-
-    await _next(context);
-}
-```
-
-## Validation Setup
-
-### Environment Variables
-
-```env
-# Required — never commit to source control
-SUPABASE_JWT_SECRET=your-jwt-secret-from-supabase-dashboard
-```
-
-- **Always** store JWT secret in environment variables or a secrets manager
-- **Never** hardcode secrets in source code
-- **Use HS256** for shared secrets (default Supabase setup)
-- **Use RS256** for asymmetric keys (advanced: separate sign/verify keys)
-
-### Validation in .NET
-
-```csharp
-builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
-    .AddJwtBearer(options =>
-    {
-        options.TokenValidationParameters = new TokenValidationParameters
-        {
-            ValidateIssuerSigningKey = true,
-            IssuerSigningKey = new SymmetricSecurityKey(
-                Encoding.UTF8.GetBytes(builder.Configuration["Supabase:JwtSecret"]!)),
-            ValidateIssuer = false,
-            ValidateAudience = true,
-            ValidAudience = "authenticated",
-            ClockSkew = TimeSpan.FromSeconds(30),
-        };
-    });
-```
-
-### Validation in Node.js
-
-```ts
-import { jwtVerify } from "jose";
-
-const secret = new TextEncoder().encode(process.env.SUPABASE_JWT_SECRET!);
-
-export async function verifyJWT(token: string) {
-  const { payload } = await jwtVerify(token, secret, {
-    audience: "authenticated",
-  });
-  return payload;
-}
-```
-
-## Cross-References
-
-- [Supabase Auth](supabase-auth.md) — authentication flows and client setup
-- [Supabase RLS](supabase-rls.md) — row-level security policies using JWT claims

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

@@ -1,169 +0,0 @@
-# Supabase pgvector Standard
-
-> **Scope:** nextjs-supabase
-> **Layer:** 2 (on keyword)
-> **Keywords:** supabase, pgvector, embedding, similarity, vector search
-> **Load When:** supabase pgvector keywords detected
-
-Stack: Next.js 15 + Supabase + .NET Backend
-
-## Core Rules
-
-- ALWAYS use HNSW indexes for production (faster queries, no training required)
-- ALWAYS match dimensions to embedding model (e.g., 1536 for text-embedding-3-small)
-- NEVER store embeddings without an index -- full table scan at query time
-- Use `halfvec` for large datasets to halve storage (16-bit vs 32-bit per dimension)
-- ALWAYS use RLS on tables containing embeddings
-
-## Setup and Table Design
-
-```sql
-CREATE EXTENSION IF NOT EXISTS vector;
-
-CREATE TABLE documents (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  user_id UUID NOT NULL REFERENCES auth.users(id),
-  title TEXT NOT NULL,
-  content TEXT NOT NULL,
-  metadata JSONB DEFAULT '{}',
-  embedding vector(1536),
-  created_at TIMESTAMPTZ DEFAULT now()
-);
-
-ALTER TABLE documents ENABLE ROW LEVEL SECURITY;
-CREATE POLICY "owner_access" ON documents FOR ALL
-  USING (user_id = auth.uid()) WITH CHECK (user_id = auth.uid());
-CREATE INDEX idx_documents_user_id ON documents (user_id);
-```
-
-### halfvec Optimization
-
-| Type | Storage/dim | 1536-dim | Best for |
-|------|------------|----------|----------|
-| `vector` | 4 bytes | 6 KB | High precision, small datasets |
-| `halfvec` | 2 bytes | 3 KB | Large datasets, cost optimization |
-
-## Index Types
-
-```sql
--- HNSW (recommended)
-CREATE INDEX idx_docs_embedding ON documents
-  USING hnsw (embedding vector_cosine_ops) WITH (m = 16, ef_construction = 64);
-
--- IVFFlat (legacy, requires existing data)
-CREATE INDEX idx_docs_ivf ON documents
-  USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);
-```
-
-| Feature | HNSW | IVFFlat |
-|---------|------|---------|
-| Query speed | Faster | Slower |
-| Requires training | No | Yes |
-| Recall quality | Higher | Lower |
-| Recommended | Yes | Only for very large datasets |
-
-## HNSW Parameters
-
-| Parameter | Default | Tuning |
-|-----------|---------|--------|
-| `m` | 16 | Higher = better recall, more memory |
-| `ef_construction` | 64 | Higher = better index, slower build |
-| `ef_search` | 40 | `SET hnsw.ef_search = 100;` per session |
-
-## Distance Functions
-
-| Operator | Function | Index Ops | Use Case |
-|----------|----------|-----------|----------|
-| `<=>` | Cosine distance | `vector_cosine_ops` | Normalized embeddings (most common) |
-| `<->` | L2 (Euclidean) | `vector_l2_ops` | Spatial/positional data |
-| `<#>` | Inner product (neg) | `vector_ip_ops` | Pre-normalized, max similarity |
-
-## Similarity Search
-
-```sql
-CREATE OR REPLACE FUNCTION match_documents(
-  query_embedding vector(1536),
-  match_threshold float DEFAULT 0.78,
-  match_count int DEFAULT 10,
-  p_user_id uuid DEFAULT auth.uid()
-) RETURNS TABLE (id uuid, title text, content text, similarity float)
-LANGUAGE sql STABLE AS $$
-  SELECT d.id, d.title, d.content,
-    1 - (d.embedding <=> query_embedding) AS similarity
-  FROM documents d
-  WHERE d.user_id = p_user_id
-    AND 1 - (d.embedding <=> query_embedding) > match_threshold
-  ORDER BY d.embedding <=> query_embedding
-  LIMIT match_count;
-$$;
-```
-
-## Hybrid Search (Vector + Full-Text)
-
-```sql
-CREATE OR REPLACE FUNCTION hybrid_search(
-  query_text text, query_embedding vector(1536),
-  match_count int DEFAULT 10,
-  text_weight float DEFAULT 0.3, vector_weight float DEFAULT 0.7
-) RETURNS TABLE (id uuid, title text, content text, score float)
-LANGUAGE sql STABLE AS $$
-  WITH vector_results AS (
-    SELECT id, title, content,
-      1 - (embedding <=> query_embedding) AS vector_score
-    FROM documents WHERE user_id = auth.uid()
-    ORDER BY embedding <=> query_embedding LIMIT match_count * 2
-  ),
-  text_results AS (
-    SELECT id, title, content,
-      ts_rank(to_tsvector('english', content), plainto_tsquery('english', query_text)) AS text_score
-    FROM documents WHERE user_id = auth.uid()
-      AND to_tsvector('english', content) @@ plainto_tsquery('english', query_text)
-    LIMIT match_count * 2
-  )
-  SELECT COALESCE(v.id, t.id), COALESCE(v.title, t.title), COALESCE(v.content, t.content),
-    (COALESCE(v.vector_score, 0) * vector_weight + COALESCE(t.text_score, 0) * text_weight)
-  FROM vector_results v FULL OUTER JOIN text_results t ON v.id = t.id
-  ORDER BY score DESC LIMIT match_count;
-$$;
-```
-
-## .NET Integration (Npgsql)
-
-```csharp
-public sealed class DocumentRepository(AppDbContext db)
-{
-    public async Task StoreEmbeddingAsync(
-        Guid documentId, float[] embedding, CancellationToken ct = default)
-    {
-        await db.Database.ExecuteSqlInterpolatedAsync(
-            $"UPDATE documents SET embedding = {new Vector(embedding)} WHERE id = {documentId}", ct);
-    }
-
-    public async Task<List<DocumentMatch>> SearchSimilarAsync(
-        float[] queryEmbedding, int limit = 10, float threshold = 0.78f,
-        CancellationToken ct = default)
-    {
-        return await db.Database.SqlQuery<DocumentMatch>($"""
-            SELECT id, title, content,
-              1 - (embedding <=> {new Vector(queryEmbedding)}::vector) AS similarity
-            FROM documents
-            WHERE 1 - (embedding <=> {new Vector(queryEmbedding)}::vector) > {threshold}
-            ORDER BY embedding <=> {new Vector(queryEmbedding)}::vector LIMIT {limit}
-            """).ToListAsync(ct);
-    }
-}
-
-// EF Core registration
-builder.Services.AddDbContext<AppDbContext>(o =>
-    o.UseNpgsql(connectionString, npg => npg.UseVector()));
-```
-
-## Common Mistakes
-
-| Wrong | Right | Why |
-|-------|-------|-----|
-| No index on embedding column | HNSW index | Full table scan, extremely slow |
-| `ORDER BY similarity DESC` | `ORDER BY embedding <=> query ASC` | Operator returns distance, not similarity |
-| Mixing embedding dimensions | Consistent dimensions per column | Dimension mismatch causes runtime errors |
-| Full-precision for millions of rows | `halfvec` for large datasets | 2x storage savings, minimal quality loss |
-| Missing RLS on embedding tables | RLS with user/tenant policies | Embeddings contain sensitive content context |