@polymorphism-tech/morph-spec 4.16.0 → 4.18.0

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 |

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

@@ -1,184 +0,0 @@
-# Supabase Row Level Security Standard
-
-> **Scope:** nextjs-supabase
-> **Layer:** 2 (on keyword)
-> **Keywords:** supabase, rls, policy, security, row level security
-> **Load When:** supabase rls keywords detected
-
-Stack: Next.js 15 + Supabase + .NET Backend
-
-## Core Rules
-
-- ALWAYS enable RLS on every table: `ALTER TABLE t ENABLE ROW LEVEL SECURITY`
-- NEVER rely solely on application-level filtering — RLS is the security boundary
-- `service_role` key bypasses ALL RLS — use only on trusted backend
-- ALWAYS create at least one policy after enabling RLS — otherwise no rows are accessible
-- ALWAYS add indexes on columns used in RLS policies
-
-## Policy Syntax
-
-### USING vs WITH CHECK
-
-| Clause | Applies To | Purpose |
-|--------|-----------|---------|
-| `USING (expr)` | SELECT, UPDATE, DELETE | Filter which existing rows are visible |
-| `WITH CHECK (expr)` | INSERT, UPDATE | Validate new/modified row data |
-
-```sql
--- SELECT: only see your own rows
-CREATE POLICY "users_select_own" ON documents
-  FOR SELECT USING (user_id = auth.uid());
-
--- INSERT: can only insert rows owned by you
-CREATE POLICY "users_insert_own" ON documents
-  FOR INSERT WITH CHECK (user_id = auth.uid());
-
--- UPDATE: can only see AND modify your own rows
-CREATE POLICY "users_update_own" ON documents
-  FOR UPDATE
-  USING (user_id = auth.uid())
-  WITH CHECK (user_id = auth.uid());
-
--- DELETE: can only delete your own rows
-CREATE POLICY "users_delete_own" ON documents
-  FOR DELETE USING (user_id = auth.uid());
-```
-
-## Auth Functions
-
-| Function | Returns | Use Case |
-|----------|---------|----------|
-| `auth.uid()` | UUID of authenticated user | Ownership checks |
-| `auth.jwt()` | Full JWT claims as JSON | Custom claims, roles, tenant ID |
-| `auth.role()` | Current role string | Distinguish anon vs authenticated |
-
-```sql
--- Access custom JWT claims
-auth.jwt() ->> 'tenant_id'
-auth.jwt() -> 'app_metadata' ->> 'role'
-```
-
-## Common Patterns
-
-### 1. Ownership
-
-```sql
-ALTER TABLE documents ENABLE ROW LEVEL SECURITY;
-
-CREATE POLICY "owner_all" ON documents
-  FOR ALL USING (user_id = auth.uid())
-  WITH CHECK (user_id = auth.uid());
-```
-
-### 2. Tenant Isolation
-
-```sql
--- Requires tenant_id in JWT app_metadata
-CREATE POLICY "tenant_isolation" ON orders
-  FOR ALL
-  USING (tenant_id = (auth.jwt() -> 'app_metadata' ->> 'tenant_id')::uuid)
-  WITH CHECK (tenant_id = (auth.jwt() -> 'app_metadata' ->> 'tenant_id')::uuid);
-```
-
-### 3. Role-Based Access
-
-```sql
--- Admins see everything, users see own
-CREATE POLICY "admin_full_access" ON documents
-  FOR ALL USING (
-    auth.jwt() -> 'app_metadata' ->> 'role' = 'admin'
-  );
-
-CREATE POLICY "user_own_access" ON documents
-  FOR ALL USING (user_id = auth.uid())
-  WITH CHECK (user_id = auth.uid());
-```
-
-### 4. Public Read, Authenticated Write
-
-```sql
-CREATE POLICY "public_read" ON posts
-  FOR SELECT USING (published = true);
-
-CREATE POLICY "auth_write" ON posts
-  FOR INSERT WITH CHECK (auth.role() = 'authenticated');
-```
-
-### 5. Team/Organization Access
-
-```sql
-CREATE POLICY "team_access" ON projects
-  FOR SELECT USING (
-    EXISTS (
-      SELECT 1 FROM team_members
-      WHERE team_members.team_id = projects.team_id
-      AND team_members.user_id = auth.uid()
-    )
-  );
-```
-
-## Index Recommendations
-
-Always index columns used in RLS policies for performance:
-
-```sql
-CREATE INDEX idx_documents_user_id ON documents (user_id);
-CREATE INDEX idx_orders_tenant_id ON orders (tenant_id);
-CREATE INDEX idx_team_members_lookup ON team_members (team_id, user_id);
-```
-
-## Testing RLS Policies
-
-### Via SQL (Supabase SQL Editor)
-
-```sql
--- Test as a specific user
-SET request.jwt.claims = '{"sub": "user-uuid-here", "role": "authenticated",
-  "app_metadata": {"tenant_id": "tenant-uuid", "role": "admin"}}';
-SET role = 'authenticated';
-
-SELECT * FROM documents; -- should only return rows matching policy
-
-RESET role;
-RESET request.jwt.claims;
-```
-
-### Via Client (different auth contexts)
-
-```ts
-// Test with anon key (unauthenticated)
-const anonClient = createClient(url, anonKey);
-const { data } = await anonClient.from("documents").select("*");
-// Should return empty if no public policy
-
-// Test with authenticated user
-const { data: userData } = await authClient.from("documents").select("*");
-// Should return only user's rows
-```
-
-## Migration Pattern
-
-```sql
--- migration: 001_enable_rls.sql
-ALTER TABLE documents ENABLE ROW LEVEL SECURITY;
-ALTER TABLE orders ENABLE ROW LEVEL SECURITY;
-ALTER TABLE team_members ENABLE ROW LEVEL SECURITY;
-
--- Always pair with policies
-CREATE POLICY "documents_owner" ON documents
-  FOR ALL USING (user_id = auth.uid())
-  WITH CHECK (user_id = auth.uid());
-```
-
-## Common Mistakes
-
-| Wrong | Right | Why |
-|-------|-------|-----|
-| Enable RLS without policies | Enable RLS + create policies | No policies = no access at all |
-| `FOR ALL USING (true)` | Specific conditions per operation | Grants unrestricted access, defeats RLS |
-| UPDATE with only USING | UPDATE with USING + WITH CHECK | User could change user_id to another user |
-| Complex subqueries in policies | Simple conditions + indexed columns | Subqueries in policies cause N+1 perf issues |
-| Using `anon` key as service_role | Separate keys, service_role only on backend | anon key respects RLS (correct), don't confuse |
-| RLS on some tables but not others | RLS on ALL tables with user data | Attackers target unprotected tables |
-| `auth.uid()` without null check | `auth.uid() IS NOT NULL AND user_id = auth.uid()` | Prevents anon access when policy is permissive |
-| Forgetting junction table RLS | RLS on junction tables too | team_members without RLS leaks membership |