@polymorphism-tech/morph-spec 4.5.0 → 4.7.0

package/.morph/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 |

package/.morph/framework/standards/infrastructure/supabase/supabase-storage.md

@@ -1,153 +0,0 @@
-# Supabase Storage Standard
-
-> **Scope:** nextjs-supabase
-> **Layer:** 2 (on keyword)
-> **Keywords:** supabase, storage, bucket, upload, file storage
-> **Load When:** supabase storage keywords detected
-
-Stack: Next.js 15 + Supabase + .NET Backend
-
-## Core Rules
-
-- ALWAYS use RLS policies on storage.objects for access control
-- NEVER serve private files without signed URLs
-- ALWAYS validate file type and size before upload
-- Public buckets: anyone can read, still need auth for write
-- Private buckets: require signed URLs or authenticated access
-
-## Bucket Configuration
-
-```sql
--- Public bucket (avatars, logos)
-INSERT INTO storage.buckets (id, name, public, file_size_limit, allowed_mime_types)
-VALUES ('avatars', 'avatars', true, 2097152, ARRAY['image/jpeg','image/png','image/webp']);
-
--- Private bucket (documents, reports)
-INSERT INTO storage.buckets (id, name, public, file_size_limit, allowed_mime_types)
-VALUES ('documents', 'documents', false, 10485760, ARRAY['application/pdf','image/jpeg','image/png']);
-```
-
-| Setting | Public Bucket | Private Bucket |
-|---------|--------------|----------------|
-| Read access | Anyone via URL | Signed URL or auth required |
-| Write access | RLS policy required | RLS policy required |
-| Use case | Avatars, public images | Documents, reports |
-
-## Storage RLS Policies
-
-```sql
--- Users upload/view/delete in their own folder
-CREATE POLICY "user_upload" ON storage.objects FOR INSERT
-  WITH CHECK (bucket_id = 'documents' AND (storage.foldername(name))[1] = auth.uid()::text);
-
-CREATE POLICY "user_select" ON storage.objects FOR SELECT
-  USING (bucket_id = 'documents' AND (storage.foldername(name))[1] = auth.uid()::text);
-
-CREATE POLICY "user_delete" ON storage.objects FOR DELETE
-  USING (bucket_id = 'documents' AND (storage.foldername(name))[1] = auth.uid()::text);
-
--- Public bucket: anyone reads, auth users upload to own folder
-CREATE POLICY "public_read" ON storage.objects FOR SELECT
-  USING (bucket_id = 'avatars');
-
-CREATE POLICY "auth_upload_avatar" ON storage.objects FOR INSERT
-  WITH CHECK (bucket_id = 'avatars' AND (storage.foldername(name))[1] = auth.uid()::text);
-```
-
-## Path Naming Convention
-
-```
-{bucket}/{user_id}/{category}/{filename}
-avatars/{user_id}/profile.webp
-documents/{user_id}/invoices/2026-01-invoice.pdf
-```
-
-First folder segment = user_id (enables simple RLS). Use lowercase, hyphens, include extension.
-
-## Upload Patterns
-
-### Browser Upload (Next.js)
-
-```ts
-async function uploadFile(file: File, userId: string) {
-  if (file.size > 10 * 1024 * 1024) throw new Error("File too large");
-  const allowedTypes = ["application/pdf", "image/jpeg", "image/png"];
-  if (!allowedTypes.includes(file.type)) throw new Error("Invalid type");
-
-  const path = `${userId}/uploads/${Date.now()}-${file.name}`;
-  const { data, error } = await supabase.storage
-    .from("documents")
-    .upload(path, file, { cacheControl: "3600", upsert: false, contentType: file.type });
-  if (error) throw error;
-  return data.path;
-}
-```
-
-### Server Upload (.NET)
-
-```csharp
-public sealed class StorageService(Supabase.Client client, ILogger<StorageService> logger)
-{
-    private static readonly string[] AllowedTypes = ["application/pdf", "image/jpeg", "image/png"];
-
-    public async Task<string> UploadAsync(
-        string bucket, string path, Stream stream,
-        string contentType, CancellationToken ct = default)
-    {
-        if (!AllowedTypes.Contains(contentType))
-            throw new ValidationException($"Invalid content type: {contentType}");
-        var response = await client.Storage.From(bucket)
-            .Upload(stream, path, new FileOptions { ContentType = contentType, Upsert = false });
-        return response;
-    }
-}
-```
-
-## Download and Signed URLs
-
-```ts
-// Public bucket: direct URL
-const { data } = supabase.storage.from("avatars").getPublicUrl("user-id/profile.webp");
-
-// Private bucket: signed URL (time-limited)
-const { data } = await supabase.storage
-  .from("documents").createSignedUrl("user-id/report.pdf", 3600); // 1 hour
-
-// Download file content (returns Blob)
-const { data } = await supabase.storage.from("documents").download("user-id/report.pdf");
-```
-
-## Image Transformations
-
-```ts
-const { data } = supabase.storage.from("avatars").getPublicUrl("user-id/photo.jpg", {
-  transform: { width: 200, height: 200, resize: "cover", quality: 80 },
-});
-```
-
-| Parameter | Options | Default |
-|-----------|---------|---------|
-| `width` / `height` | 1-2500 px | original |
-| `resize` | cover, contain, fill | cover |
-| `quality` | 20-100 | 80 |
-| `format` | origin, avif, webp | origin |
-
-## File Validation
-
-| Check | Client-Side | Server-Side | Bucket Config |
-|-------|------------|-------------|---------------|
-| File size | `file.size` | Stream length | `file_size_limit` |
-| MIME type | `file.type` | Content-Type | `allowed_mime_types` |
-| Extension | File name | File name | -- |
-
-Always validate at all three levels. Client-side can be bypassed.
-
-## Common Mistakes
-
-| Wrong | Right | Why |
-|-------|-------|-----|
-| No RLS on storage.objects | Policies for each bucket | Anyone can read/write without policies |
-| Private files via public URL | `createSignedUrl()` | Private bucket returns 403 without auth |
-| User-provided filename as-is | Sanitize + timestamp prefix | Path traversal attacks, collisions |
-| `upsert: true` by default | `upsert: false` | Prevents accidental file overwrites |
-| Files without user folder | `{user_id}/...` path pattern | Cannot write simple RLS policies |

package/.morph/framework/standards/integration/api/graphql.md

@@ -1,91 +0,0 @@
-# Integration Standard: GraphQL
-
-## When to Use GraphQL
-✅ Client needs fine-grained field selection (mobile apps, different clients)
-✅ Complex nested resource relationships (avoid N+1 with DataLoader)
-✅ Real-time subscriptions alongside queries
-❌ Simple CRUD APIs (REST is simpler)
-❌ File upload as primary use case (use REST for uploads)
-❌ When caching is critical (GraphQL caching is harder)
-
-## Setup (Hot Chocolate)
-```xml
-<PackageReference Include="HotChocolate.AspNetCore" Version="14.*" />
-<PackageReference Include="HotChocolate.Data.EntityFramework" Version="14.*" />
-```
-
-```csharp
-builder.Services
-    .AddGraphQLServer()
-    .AddQueryType<QueryType>()
-    .AddMutationType<MutationType>()
-    .AddSubscriptionType<SubscriptionType>()
-    .AddProjections()
-    .AddFiltering()
-    .AddSorting()
-    .AddAuthorization();
-
-app.MapGraphQL("/graphql");
-```
-
-## Query Type
-```csharp
-[QueryType]
-public class QueryType
-{
-    [UseProjection]
-    [UseFiltering]
-    [UseSorting]
-    [UsePaging]
-    public IQueryable<Order> GetOrders([Service] AppDbContext ctx) => ctx.Orders;
-
-    public async Task<Order?> GetOrder(Guid id, [Service] AppDbContext ctx)
-        => await ctx.Orders.FindAsync(id);
-}
-```
-
-## Mutation Type
-```csharp
-[MutationType]
-public class MutationType
-{
-    public async Task<CreateOrderPayload> CreateOrder(
-        CreateOrderInput input,
-        [Service] ISender sender)
-    {
-        var result = await sender.Send(new CreateOrderCommand(input.UserId, input.Items));
-        return new CreateOrderPayload(result.OrderId);
-    }
-}
-
-public record CreateOrderInput(Guid UserId, List<OrderItemInput> Items);
-public record CreateOrderPayload(Guid OrderId);
-```
-
-## DataLoader (N+1 Prevention)
-```csharp
-public class UserDataLoader : BatchDataLoader<Guid, User>
-{
-    protected override async Task<IReadOnlyDictionary<Guid, User>> LoadBatchAsync(
-        IReadOnlyList<Guid> keys, CancellationToken ct)
-    {
-        return await _context.Users
-            .Where(u => keys.Contains(u.Id))
-            .ToDictionaryAsync(u => u.Id, ct);
-    }
-}
-
-// Use in resolver
-public async Task<User?> GetUser([Parent] Order order, UserDataLoader loader)
-    => await loader.LoadAsync(order.UserId);
-```
-
-## Security
-- Apply `[Authorize]` on mutations and sensitive queries
-- Disable introspection in production
-- Depth limiting: max 5 levels
-- Complexity limiting: max 1000 nodes per query
-```csharp
-.AddMaxExecutionDepthRule(5)
-.ModifyRequestOptions(opts => opts.MaxAllowedRequestSize = 1_000_000)
-```

package/.morph/framework/standards/integration/api/grpc.md

@@ -1,114 +0,0 @@
-# Integration Standard: gRPC
-
-## When to Use gRPC
-✅ Internal service-to-service communication (high performance)
-✅ Streaming (server-streaming for real-time data, client-streaming for uploads)
-✅ Multi-language microservices (proto contracts shared across .NET, Go, Python)
-❌ Browser-to-server (use gRPC-Web or REST instead)
-❌ Debugging priority (binary format is harder to inspect than JSON)
-
-## Setup
-```xml
-<PackageReference Include="Grpc.AspNetCore" Version="2.*" />
-```
-
-```csharp
-// Program.cs
-builder.Services.AddGrpc(opts =>
-{
-    opts.EnableDetailedErrors = builder.Environment.IsDevelopment();
-    opts.MaxReceiveMessageSize = 4 * 1024 * 1024; // 4 MB
-});
-app.MapGrpcService<OrdersService>();
-```
-
-## Proto Definition
-```protobuf
-syntax = "proto3";
-option csharp_namespace = "MyApp.Grpc";
-
-service Orders {
-  rpc CreateOrder(CreateOrderRequest) returns (CreateOrderResponse);
-  rpc GetOrder(GetOrderRequest) returns (OrderResponse);
-  rpc StreamOrders(StreamOrdersRequest) returns (stream OrderResponse);
-}
-
-message CreateOrderRequest {
-  string user_id = 1;
-  repeated OrderItem items = 2;
-}
-
-message CreateOrderResponse {
-  string order_id = 1;
-  double total = 2;
-}
-```
-
-## Service Implementation
-```csharp
-public class OrdersService : Orders.OrdersBase
-{
-    public override async Task<CreateOrderResponse> CreateOrder(
-        CreateOrderRequest request, ServerCallContext context)
-    {
-        var cmd = new CreateOrderCommand(
-            Guid.Parse(request.UserId),
-            request.Items.Select(i => new OrderItem(i.ProductId, i.Quantity)).ToList());
-
-        var result = await _sender.Send(cmd, context.CancellationToken);
-
-        return new CreateOrderResponse
-        {
-            OrderId = result.OrderId.ToString(),
-            Total = (double)result.Total
-        };
-    }
-
-    public override async Task StreamOrders(
-        StreamOrdersRequest request,
-        IServerStreamWriter<OrderResponse> responseStream,
-        ServerCallContext context)
-    {
-        await foreach (var order in _service.GetOrderStreamAsync(context.CancellationToken))
-        {
-            await responseStream.WriteAsync(MapToResponse(order), context.CancellationToken);
-            if (context.CancellationToken.IsCancellationRequested) break;
-        }
-    }
-}
-```
-
-## Client Setup
-```csharp
-// Program.cs (client service)
-builder.Services.AddGrpcClient<Orders.OrdersClient>(opts =>
-{
-    opts.Address = new Uri(config["Services:OrdersUrl"]);
-})
-.ConfigureChannel(opts =>
-{
-    opts.HttpHandler = new SocketsHttpHandler
-    {
-        PooledConnectionIdleTimeout = Timeout.InfiniteTimeSpan,
-        KeepAlivePingDelay = TimeSpan.FromSeconds(60),
-        KeepAlivePingTimeout = TimeSpan.FromSeconds(30)
-    };
-});
-```
-
-## Error Handling
-```csharp
-// Map exceptions to gRPC status codes
-try
-{
-    return await _service.ProcessAsync(request.Id);
-}
-catch (NotFoundException)
-{
-    throw new RpcException(new Status(StatusCode.NotFound, "Order not found"));
-}
-catch (ValidationException ex)
-{
-    throw new RpcException(new Status(StatusCode.InvalidArgument, ex.Message));
-}
-```

package/.morph/framework/standards/integration/api/rest-design.md

@@ -1,95 +0,0 @@
-# Integration Standard: REST API Design
-
-## URL Structure
-```
-GET    /api/v1/orders              — list (paginated)
-GET    /api/v1/orders/{id}         — get by ID
-POST   /api/v1/orders              — create
-PUT    /api/v1/orders/{id}         — full update
-PATCH  /api/v1/orders/{id}         — partial update
-DELETE /api/v1/orders/{id}         — delete
-
-GET    /api/v1/users/{id}/orders   — nested resource (ownership)
-POST   /api/v1/orders/{id}/cancel  — verb action (exception to noun rule)
-```
-
-## Request/Response Conventions
-
-### Pagination (always paginate lists)
-```json
-// Request
-GET /api/v1/orders?page=1&pageSize=20&sort=createdAt&order=desc
-
-// Response
-{
-  "data": [...],
-  "pagination": {
-    "page": 1,
-    "pageSize": 20,
-    "total": 150,
-    "totalPages": 8,
-    "hasNext": true,
-    "hasPrevious": false
-  }
-}
-```
-
-### Error Response (RFC 7807 ProblemDetails)
-```json
-{
-  "type": "https://api.myapp.com/errors/validation",
-  "title": "Validation Failed",
-  "status": 422,
-  "detail": "One or more fields failed validation",
-  "instance": "/api/v1/orders",
-  "errors": {
-    "userId": ["UserId is required"],
-    "items": ["At least one item is required"]
-  }
-}
-```
-
-## Status Codes
-| Code | When |
-|------|------|
-| 200 OK | GET, PUT, PATCH success |
-| 201 Created | POST success (include Location header) |
-| 204 No Content | DELETE success |
-| 400 Bad Request | Malformed request body |
-| 401 Unauthorized | Missing/invalid auth token |
-| 403 Forbidden | Valid token, insufficient permissions |
-| 404 Not Found | Resource doesn't exist |
-| 409 Conflict | Duplicate/optimistic lock conflict |
-| 422 Unprocessable | Validation failures |
-| 429 Too Many Requests | Rate limit exceeded (include Retry-After) |
-| 500 Internal Server Error | Unexpected server error |
-
-## Versioning
-- URL versioning: `/api/v1/`, `/api/v2/`
-- Never version via headers (poor discoverability)
-- Maintain N-1 version for 6 months before deprecating
-
-## Minimal API Setup (.NET 10)
-```csharp
-var ordersGroup = app.MapGroup("/api/v1/orders")
-    .RequireAuthorization()
-    .WithTags("Orders")
-    .WithOpenApi();
-
-ordersGroup.MapGet("/", GetOrdersHandler)
-    .WithName("GetOrders")
-    .Produces<PagedResponse<OrderDto>>()
-    .Produces<ProblemDetails>(400);
-
-ordersGroup.MapPost("/", CreateOrderHandler)
-    .WithName("CreateOrder")
-    .Produces<OrderDto>(201)
-    .Produces<ProblemDetails>(422);
-```
-
-## Security Requirements
-- All endpoints require authentication (except /health, /api/docs)
-- Authorization policy per endpoint (not just [Authorize])
-- Rate limiting on write endpoints
-- Input validation via FluentValidation
-- Never expose internal IDs in error messages