@polymorphism-tech/morph-spec 4.10.9 → 4.11.0

package/framework/standards/frontend/nextjs/nextjs-patterns.md

@@ -196,20 +196,20 @@ Components are copied to `components/ui/` -- NOT an npm dependency, your code to
 | `useEffect` for data fetching | React Query `useQuery` | No caching, race conditions |
 | Form validation on submit only | Zod resolver + react-hook-form | Delayed error feedback |
 | shadcn as npm package | `npx shadcn@latest add` | Copy-paste system, not a dependency |
-
-## TypeScript Strict Mode (Required)
-
-Always enable `"strict": true` in `tsconfig.json`. This is non-negotiable for
-agent-assisted development because agents rely on compiler errors to self-correct.
-Without strict mode, type/null errors only surface at runtime where agents cannot observe them.
-
-```json
-{
-  "compilerOptions": {
-    "strict": true,
-    "noUncheckedIndexedAccess": true
-  }
-}
-```
-
-Strict mode enables: `strictNullChecks`, `noImplicitAny`, `strictFunctionTypes`, `strictPropertyInitialization`.
+
+## TypeScript Strict Mode (Required)
+
+Always enable `"strict": true` in `tsconfig.json`. This is non-negotiable for
+agent-assisted development because agents rely on compiler errors to self-correct.
+Without strict mode, type/null errors only surface at runtime where agents cannot observe them.
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true
+  }
+}
+```
+
+Strict mode enables: `strictNullChecks`, `noImplicitAny`, `strictFunctionTypes`, `strictPropertyInitialization`.

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

@@ -0,0 +1,206 @@
+# 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/templates/.idea/morph-templates.xml

@@ -0,0 +1,92 @@
+<templateSet group="MORPH Templates">
+  <template name="morph-pascal" value="{{pascalCase $FEATURE_NAME$}}" description="Convert to PascalCase (UserAuth)" toReformat="false" toShortenFQNames="true">
+    <variable name="FEATURE_NAME" expression="" defaultValue="&quot;FEATURE_NAME&quot;" alwaysStopAt="true" />
+    <context>
+      <option name="OTHER" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-camel" value="{{camelCase $FEATURE_NAME$}}" description="Convert to camelCase (userAuth)" toReformat="false" toShortenFQNames="true">
+    <variable name="FEATURE_NAME" expression="" defaultValue="&quot;FEATURE_NAME&quot;" alwaysStopAt="true" />
+    <context>
+      <option name="OTHER" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-snake" value="{{snakeCase $FEATURE_NAME$}}" description="Convert to snake_case (user_auth)" toReformat="false" toShortenFQNames="true">
+    <variable name="FEATURE_NAME" expression="" defaultValue="&quot;FEATURE_NAME&quot;" alwaysStopAt="true" />
+    <context>
+      <option name="OTHER" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-title" value="{{titleCase $FEATURE_NAME$}}" description="Convert to Title Case (User Auth)" toReformat="false" toShortenFQNames="true">
+    <variable name="FEATURE_NAME" expression="" defaultValue="&quot;FEATURE_NAME&quot;" alwaysStopAt="true" />
+    <context>
+      <option name="OTHER" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-kebab" value="{{kebabCase $FEATURE_NAME$}}" description="Convert to kebab-case (user-auth)" toReformat="false" toShortenFQNames="true">
+    <variable name="FEATURE_NAME" expression="" defaultValue="&quot;FEATURE_NAME&quot;" alwaysStopAt="true" />
+    <context>
+      <option name="OTHER" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-if" value="{{#if $CONDITION$}}&#10;  $END$&#10;{{/if}}" description="Handlebars if block" toReformat="false" toShortenFQNames="true">
+    <variable name="CONDITION" expression="" defaultValue="&quot;condition&quot;" alwaysStopAt="true" />
+    <context>
+      <option name="OTHER" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-if-else" value="{{#if $CONDITION$}}&#10;  $TRUE_BRANCH$&#10;{{else}}&#10;  $FALSE_BRANCH$&#10;{{/if}}" description="Handlebars if-else block" toReformat="false" toShortenFQNames="true">
+    <variable name="CONDITION" expression="" defaultValue="&quot;condition&quot;" alwaysStopAt="true" />
+    <variable name="TRUE_BRANCH" expression="" defaultValue="&quot;&quot;" alwaysStopAt="true" />
+    <variable name="FALSE_BRANCH" expression="" defaultValue="&quot;&quot;" alwaysStopAt="true" />
+    <context>
+      <option name="OTHER" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-each" value="{{#each $ITEMS$}}&#10;  {{this.$PROPERTY$}}&#10;{{/each}}" description="Handlebars each loop" toReformat="false" toShortenFQNames="true">
+    <variable name="ITEMS" expression="" defaultValue="&quot;items&quot;" alwaysStopAt="true" />
+    <variable name="PROPERTY" expression="" defaultValue="&quot;name&quot;" alwaysStopAt="true" />
+    <context>
+      <option name="OTHER" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-service" value="namespace {{NAMESPACE}}.Application.Features.{{pascalCase FEATURE_NAME}}.Services;&#10;&#10;public class {{pascalCase FEATURE_NAME}}Service(&#10;    I{{pascalCase FEATURE_NAME}}Repository repository,&#10;    ILogger&lt;{{pascalCase FEATURE_NAME}}Service&gt; logger) : I{{pascalCase FEATURE_NAME}}Service&#10;{&#10;    public async Task&lt;{{pascalCase FEATURE_NAME}}Dto?&gt; GetByIdAsync(int id, CancellationToken cancellationToken = default)&#10;    {&#10;        $END$&#10;    }&#10;}" description="MORPH .NET Service class template" toReformat="false" toShortenFQNames="true">
+    <context>
+      <option name="C_SHARP" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-repository" value="public class {{pascalCase FEATURE_NAME}}Repository(AppDbContext context) : I{{pascalCase FEATURE_NAME}}Repository&#10;{&#10;    private readonly DbSet&lt;{{pascalCase FEATURE_NAME}}&gt; _dbSet = context.Set&lt;{{pascalCase FEATURE_NAME}}&gt;();&#10;&#10;    public async Task&lt;{{pascalCase FEATURE_NAME}}?&gt; GetByIdAsync(int id, CancellationToken cancellationToken = default)&#10;    {&#10;        $END$&#10;    }&#10;}" description="MORPH .NET Repository class template" toReformat="false" toShortenFQNames="true">
+    <context>
+      <option name="C_SHARP" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-component" value="@page &quot;/{{kebabCase FEATURE_NAME}}&quot;&#10;@inject I{{pascalCase FEATURE_NAME}}Service {{pascalCase FEATURE_NAME}}Service&#10;@inject ILogger&lt;{{pascalCase FEATURE_NAME}}Page&gt; Logger&#10;&#10;&lt;PageTitle&gt;{{pascalCase FEATURE_NAME}}&lt;/PageTitle&gt;&#10;&#10;&lt;div class=&quot;container-fluid&quot;&gt;&#10;    $END$&#10;&lt;/div&gt;&#10;&#10;@code {&#10;&#10;}" description="MORPH Blazor component template" toReformat="false" toShortenFQNames="true">
+    <context>
+      <option name="HTML" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-migration" value="public partial class Add{{pascalCase FEATURE_NAME}} : Migration&#10;{&#10;    protected override void Up(MigrationBuilder migrationBuilder)&#10;    {&#10;        migrationBuilder.CreateTable(&#10;            name: &quot;{{pascalCase FEATURE_NAME}}s&quot;,&#10;            columns: table =&gt; new&#10;            {&#10;                Id = table.Column&lt;int&gt;(type: &quot;int&quot;, nullable: false)&#10;                    .Annotation(&quot;SqlServer:Identity&quot;, &quot;1, 1&quot;),&#10;                $END$&#10;            },&#10;            constraints: table =&gt;&#10;            {&#10;                table.PrimaryKey(&quot;PK_{{pascalCase FEATURE_NAME}}s&quot;, x =&gt; x.Id);&#10;            });&#10;    }&#10;&#10;    protected override void Down(MigrationBuilder migrationBuilder)&#10;    {&#10;        migrationBuilder.DropTable(name: &quot;{{pascalCase FEATURE_NAME}}s&quot;);&#10;    }&#10;}" description="MORPH EF Core migration template" toReformat="false" toShortenFQNames="true">
+    <context>
+      <option name="C_SHARP" value="true" />
+    </context>
+  </template>
+
+  <template name="morph-ts-contract" value="export interface {{pascalCase FEATURE_NAME}} {&#10;  id: number;&#10;  $FIELD1$&#10;}&#10;&#10;export interface Create{{pascalCase FEATURE_NAME}}Request {&#10;  $FIELD2$&#10;}&#10;&#10;export interface Update{{pascalCase FEATURE_NAME}}Request {&#10;  $END$&#10;}" description="MORPH TypeScript contract template" toReformat="false" toShortenFQNames="true">
+    <variable name="FIELD1" expression="" defaultValue="&quot;&quot;" alwaysStopAt="true" />
+    <variable name="FIELD2" expression="" defaultValue="&quot;&quot;" alwaysStopAt="true" />
+    <context>
+      <option name="TypeScript" value="true" />
+    </context>
+  </template>
+</templateSet>

package/framework/templates/.vscode/morph-templates.code-snippets

@@ -0,0 +1,186 @@
+{
+  "MORPH Template - PascalCase": {
+    "prefix": "morph-pascal",
+    "body": ["{{pascalCase ${1:FEATURE_NAME}}}"],
+    "description": "Convert to PascalCase (UserAuth)"
+  },
+  "MORPH Template - camelCase": {
+    "prefix": "morph-camel",
+    "body": ["{{camelCase ${1:FEATURE_NAME}}}"],
+    "description": "Convert to camelCase (userAuth)"
+  },
+  "MORPH Template - snake_case": {
+    "prefix": "morph-snake",
+    "body": ["{{snakeCase ${1:FEATURE_NAME}}}"],
+    "description": "Convert to snake_case (user_auth)"
+  },
+  "MORPH Template - Title Case": {
+    "prefix": "morph-title",
+    "body": ["{{titleCase ${1:FEATURE_NAME}}}"],
+    "description": "Convert to Title Case (User Auth)"
+  },
+  "MORPH Template - kebab-case": {
+    "prefix": "morph-kebab",
+    "body": ["{{kebabCase ${1:FEATURE_NAME}}}"],
+    "description": "Convert to kebab-case (user-auth)"
+  },
+  "MORPH Template - UPPER_SNAKE_CASE": {
+    "prefix": "morph-upper-snake",
+    "body": ["{{upperSnakeCase ${1:FEATURE_NAME}}}"],
+    "description": "Convert to UPPER_SNAKE_CASE (USER_AUTH)"
+  },
+  "MORPH Template - Conditional If": {
+    "prefix": "morph-if",
+    "body": [
+      "{{#if ${1:condition}}}",
+      "  $2",
+      "{{/if}}"
+    ],
+    "description": "Handlebars if block"
+  },
+  "MORPH Template - Conditional If-Else": {
+    "prefix": "morph-if-else",
+    "body": [
+      "{{#if ${1:condition}}}",
+      "  $2",
+      "{{else}}",
+      "  $3",
+      "{{/if}}"
+    ],
+    "description": "Handlebars if-else block"
+  },
+  "MORPH Template - Each Loop": {
+    "prefix": "morph-each",
+    "body": [
+      "{{#each ${1:items}}}",
+      "  {{this.$2}}",
+      "{{/each}}"
+    ],
+    "description": "Handlebars each loop"
+  },
+  "MORPH Template - Unless": {
+    "prefix": "morph-unless",
+    "body": [
+      "{{#unless ${1:condition}}}",
+      "  $2",
+      "{{/unless}}"
+    ],
+    "description": "Handlebars unless block"
+  },
+  "MORPH Template - .NET Service Class": {
+    "prefix": "morph-service",
+    "body": [
+      "namespace {{NAMESPACE}}.Application.Features.{{pascalCase FEATURE_NAME}}.Services;",
+      "",
+      "public class {{pascalCase FEATURE_NAME}}Service(",
+      "    I{{pascalCase FEATURE_NAME}}Repository repository,",
+      "    ILogger<{{pascalCase FEATURE_NAME}}Service> logger) : I{{pascalCase FEATURE_NAME}}Service",
+      "{",
+      "    public async Task<{{pascalCase FEATURE_NAME}}Dto?> GetByIdAsync(int id, CancellationToken cancellationToken = default)",
+      "    {",
+      "        $1",
+      "    }",
+      "}"
+    ],
+    "description": "MORPH .NET Service class template"
+  },
+  "MORPH Template - .NET Repository Class": {
+    "prefix": "morph-repository",
+    "body": [
+      "public class {{pascalCase FEATURE_NAME}}Repository(AppDbContext context) : I{{pascalCase FEATURE_NAME}}Repository",
+      "{",
+      "    private readonly DbSet<{{pascalCase FEATURE_NAME}}> _dbSet = context.Set<{{pascalCase FEATURE_NAME}}>();",
+      "",
+      "    public async Task<{{pascalCase FEATURE_NAME}}?> GetByIdAsync(int id, CancellationToken cancellationToken = default)",
+      "    {",
+      "        $1",
+      "    }",
+      "}"
+    ],
+    "description": "MORPH .NET Repository class template"
+  },
+  "MORPH Template - Blazor Component": {
+    "prefix": "morph-component",
+    "body": [
+      "@page \"/{{kebabCase FEATURE_NAME}}\"",
+      "@inject I{{pascalCase FEATURE_NAME}}Service {{pascalCase FEATURE_NAME}}Service",
+      "@inject ILogger<{{pascalCase FEATURE_NAME}}Page> Logger",
+      "",
+      "<PageTitle>{{pascalCase FEATURE_NAME}}</PageTitle>",
+      "",
+      "<div class=\"container-fluid\">",
+      "    $1",
+      "</div>",
+      "",
+      "@code {",
+      "    $2",
+      "}"
+    ],
+    "description": "MORPH Blazor component template"
+  },
+  "MORPH Template - EF Core Migration": {
+    "prefix": "morph-migration",
+    "body": [
+      "public partial class Add{{pascalCase FEATURE_NAME}} : Migration",
+      "{",
+      "    protected override void Up(MigrationBuilder migrationBuilder)",
+      "    {",
+      "        migrationBuilder.CreateTable(",
+      "            name: \"{{pascalCase FEATURE_NAME}}s\",",
+      "            columns: table => new",
+      "            {",
+      "                Id = table.Column<int>(type: \"int\", nullable: false)",
+      "                    .Annotation(\"SqlServer:Identity\", \"1, 1\"),",
+      "                $1",
+      "            },",
+      "            constraints: table =>",
+      "            {",
+      "                table.PrimaryKey(\"PK_{{pascalCase FEATURE_NAME}}s\", x => x.Id);",
+      "            });",
+      "    }",
+      "",
+      "    protected override void Down(MigrationBuilder migrationBuilder)",
+      "    {",
+      "        migrationBuilder.DropTable(name: \"{{pascalCase FEATURE_NAME}}s\");",
+      "    }",
+      "}"
+    ],
+    "description": "MORPH EF Core migration template"
+  },
+  "MORPH Template - Hangfire Job": {
+    "prefix": "morph-job",
+    "body": [
+      "public class {{pascalCase FEATURE_NAME}}ProcessorJob(",
+      "    I{{pascalCase FEATURE_NAME}}Service service,",
+      "    ILogger<{{pascalCase FEATURE_NAME}}ProcessorJob> logger) : I{{pascalCase FEATURE_NAME}}ProcessorJob",
+      "{",
+      "    [AutomaticRetry(Attempts = 3, DelaysInSeconds = new[] { 60, 300, 900 })]",
+      "    [Queue(\"default\")]",
+      "    [JobDisplayName(\"{{pascalCase FEATURE_NAME}} Processing - ID: {0}\")]",
+      "    public async Task ExecuteAsync(int id, CancellationToken cancellationToken)",
+      "    {",
+      "        $1",
+      "    }",
+      "}"
+    ],
+    "description": "MORPH Hangfire job template"
+  },
+  "MORPH Template - TypeScript Contract": {
+    "prefix": "morph-ts-contract",
+    "body": [
+      "export interface {{pascalCase FEATURE_NAME}} {",
+      "  id: number;",
+      "  $1",
+      "}",
+      "",
+      "export interface Create{{pascalCase FEATURE_NAME}}Request {",
+      "  $2",
+      "}",
+      "",
+      "export interface Update{{pascalCase FEATURE_NAME}}Request {",
+      "  $3",
+      "}"
+    ],
+    "description": "MORPH TypeScript contract template"
+  }
+}