@polymorphism-tech/morph-spec 7.9.2 → 7.9.3

package/README.md

@@ -3,7 +3,7 @@
 > Spec-driven development framework for multi-stack projects. Turns feature requests into implementation-ready code through structured, AI-orchestrated phases.
 
 **Package:** `@polymorphism-tech/morph-spec`
-**Version:** 7.9.2  
+**Version:** 7.9.3  
 **Requires:** Node.js 22+, Claude Code
 
 ---
@@ -365,4 +365,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v7.9.2 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v7.9.3 by [Polymorphism Tech](https://polymorphism.tech)*

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "7.9.2",
+  "version": "7.9.3",
   "displayName": "MORPH-SPEC Framework",
   "description": "Spec-driven development with 38 agents and 8-phase workflow for .NET/Blazor/Next.js/Azure",
   "publisher": "polymorphism-tech",

package/docs/CHEATSHEET.md

@@ -200,4 +200,4 @@ These files are never edited directly. Use CLI commands or `morph-spec update` i
 
 ---
 
-*morph-spec v7.9.2 by Polymorphism Tech*
+*morph-spec v7.9.3 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -197,4 +197,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v7.9.2 by Polymorphism Tech*
+*morph-spec v7.9.3 by Polymorphism Tech*

package/framework/agents.json

@@ -19,7 +19,8 @@
         "architecture-vertical-slice-vertical-slice",
         "backend-dotnet-result-pattern",
         "backend-dotnet-vsa-handler-patterns",
-        "backend-dotnet-fluent-validation-vsa"
+        "backend-dotnet-fluent-validation-vsa",
+        "backend-integrations-neon-auth-neon-auth"
       ],
       "mcp": ["context7"],
       "persona": "Você é um engenheiro .NET sênior. Pensa em VSA com handlers diretos, result pattern, sealed classes, Guid.CreateVersion7(). Acesso a dados: ApplicationDbContext injetado direto no slice (DbSet<T> já é repository, DbContext já é unit of work); para concorrência ou SQL específico, store dedicado hand-written com justificativa em decisions.md; nunca uma camada de Service/Manager; nunca repository genérico (IRepository<T>/IUnitOfWork). Não usa exceptions como fluxo. Consulta o standard antes de escrever cada slice. Nomeia tudo em PascalCase para tipos, camelCase para parâmetros."
@@ -81,7 +82,8 @@
         "frontend-nextjs-components",
         "frontend-nextjs-data-fetching",
         "frontend-nextjs-naming-conventions",
-        "frontend-nextjs-state-management"
+        "frontend-nextjs-state-management",
+        "backend-integrations-neon-auth-neon-auth"
       ],
       "mcp": ["context7"],
       "persona": "Você escreve Next.js App Router idiomático. Server Components por padrão, Client Components apenas quando há interatividade real. Tailwind + Shadcn + Framer Motion. Tipos via Zod. Nada de getServerSideProps. RSC streaming quando faz sentido."

package/framework/evals/rubrics/architecture.md

@@ -2,6 +2,27 @@
 
 Avalia se a implementação segue o padrão arquitetural definido no spec.md e mandate.md.
 
+## Verificações mecânicas obrigatórias (auto-reprovação se falhar)
+
+Estas duas checagens são objetivas — não dependem de julgamento sobre estilo — e cobrem bugs reais que
+já derrubaram uma app em produção (ver `backend/integrations/neon-auth/neon-auth.md` → "Known Failure
+Modes"). Rode ambas sempre que o diff tocar endpoints minimal API ou fetch de dados cross-camada, mesmo
+que o mandate não as mencione explicitamente. Uma violação em qualquer uma delas é bloqueante — não
+"ressalva" — independente do resto do score de arquitetura.
+
+1. **DI de todo serviço injetado em endpoint.** Para cada parâmetro de tipo serviço em uma lambda de
+   endpoint minimal API (qualquer tipo que não seja `TRequest`, `CancellationToken`, `ClaimsPrincipal`
+   ou um primitivo de rota/query), confirme que existe `AddScoped<T>()` / `AddSingleton<T>()` /
+   `AddTransient<T>()` correspondente em `Program.cs` (ou registro via assembly-scanning). Um serviço
+   não registrado é inferido como `[FromBody]` pelo Minimal API e derruba a app inteira no startup —
+   isso é "Score 1-2", não "Score 5-6 com ressalva", porque não é estilo: é a aplicação não subir.
+2. **Nenhum prefixo de rota reusado para dois propósitos.** Se o projeto tem chamadas server-direct ao
+   backend E chamadas client-side via proxy same-origin, confirme que existem DUAS constantes
+   nomeadas distintas (uma por propósito) e que nenhuma delas aparece do lado errado (grep: arquivos de
+   Server Component só importam a constante server-direct; hooks/Client Component só importam a
+   constante de proxy). Uma única constante reusada para os dois quebra silenciosamente um dos dois
+   caminhos em runtime, sem sinal em build — também bloqueante.
+
 ## Score 9-10 — Exemplar
 
 - Segue o padrão de feature folder rigorosamente: cada feature tem seus próprios handlers, commands/queries, validators e endpoints.
@@ -36,6 +57,8 @@ Avalia se a implementação segue o padrão arquitetural definido no spec.md e m
 - Implementação plana sem estrutura de feature.
 - Dependências circulares ou acoplamento total entre camadas.
 - Requer refatoração antes de qualquer entrega.
+- Qualquer violação das "Verificações mecânicas obrigatórias" acima (DI faltando, prefixo de rota
+  reusado) — teto de score 2 independente de quão bem o resto segue o padrão.
 
 ## Perguntas de avaliação
 
@@ -44,3 +67,7 @@ Avalia se a implementação segue o padrão arquitetural definido no spec.md e m
 3. Objetos de domínio importam de infraestrutura (ORM, HTTP, I/O)?
 4. Se remover esta feature, alguma outra quebra?
 5. O padrão arquitetural descrito no spec.md foi seguido?
+6. Todo serviço injetado numa lambda de endpoint minimal API tem `AddScoped`/`AddSingleton`/
+   `AddTransient` correspondente em `Program.cs`?
+7. Se o diff tem chamada server-direct ao backend E chamada client-side via proxy para o mesmo
+   recurso, elas usam duas constantes de prefixo distintas — nenhuma reusada para o outro propósito?

package/framework/skills/core/create-umbraco-lp/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a criação de uma landing page nova ponta-a-ponta a partir do
 version: core
 when-to-invoke: ao iniciar um novo projeto de LP com o template Umbraco genérico
 user-invokable: true
-cliVersion: "7.9.2"
+cliVersion: "7.9.3"
 ---
 
 # create-umbraco-lp

package/framework/skills/core/migrate-lp-to-umbraco/SKILL.md

@@ -4,7 +4,7 @@ description: Migra uma landing page existente (React/Vite, Next.js estático ou
 version: core
 when-to-invoke: ao receber instrução "use /migrate-lp-to-umbraco {projeto}" do usuário, ou quando o usuário descrever necessidade de migrar uma LP para Umbraco
 user-invokable: true
-cliVersion: "7.9.2"
+cliVersion: "7.9.3"
 ---
 
 # migrate-lp-to-umbraco

package/framework/skills/core/morph-apply/SKILL.md

@@ -4,7 +4,7 @@ description: Orquestra a execução autônoma de tasks de uma feature morph-spec
 version: core
 when-to-invoke: após Gate 2 aprovado, ao receber instrução "use /morph-apply" ou "implementar feature"
 user-invokable: true
-cliVersion: "7.9.2"
+cliVersion: "7.9.3"
 ---
 
 # morph-apply

package/framework/skills/core/morph-brainstorming/SKILL.md

@@ -4,7 +4,7 @@ description: Entende o negócio, os usuários e a arquitetura antes de qualquer
 version: core
 when-to-invoke: ao receber um novo request de feature, antes de morph-plan
 user-invokable: true
-cliVersion: "7.9.2"
+cliVersion: "7.9.3"
 ---
 
 # morph-brainstorming

package/framework/skills/core/morph-eval/SKILL.md

@@ -4,7 +4,7 @@ description: Avalia a qualidade de uma tarefa ou fase com rubricas graduadas 0-1
 version: core
 when-to-invoke: ao completar uma tarefa ou ao finalizar uma fase de implementação
 user-invokable: false
-cliVersion: "7.9.2"
+cliVersion: "7.9.3"
 ---
 
 # morph-eval

package/framework/skills/core/morph-implement/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a execução de cada tarefa de implementação com standard e
 version: core
 when-to-invoke: ao iniciar cada task de implementação listada em tasks.json
 user-invokable: false
-cliVersion: "7.9.2"
+cliVersion: "7.9.3"
 ---
 
 # morph-implement

package/framework/skills/core/morph-plan/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a produção dos três artefatos de planejamento de uma featur
 version: core
 when-to-invoke: ao iniciar a fase plan de uma feature, após o Gate 1 (proposal aprovado)
 user-invokable: true
-cliVersion: "7.9.2"
+cliVersion: "7.9.3"
 ---
 
 # morph-plan

package/framework/skills/core/morph-proposal/SKILL.md

@@ -4,7 +4,7 @@ description: Orquestra a fase de proposta+plano de uma feature morph-spec. Encad
 version: core
 when-to-invoke: ao receber instrução "use /morph-proposal" do usuário, ou ao iniciar uma nova feature
 user-invokable: true
-cliVersion: "7.9.2"
+cliVersion: "7.9.3"
 ---
 
 # morph-proposal

package/framework/skills/core/morph-review/SKILL.md

@@ -4,7 +4,7 @@ description: Conduz a fase de revisão e produz o review-report.md para o Gate 3
 version: core
 when-to-invoke: ao iniciar a fase review, após todas as tasks de tasks.json estarem com status `done`
 user-invokable: true
-cliVersion: "7.9.2"
+cliVersion: "7.9.3"
 ---
 
 # morph-review
@@ -33,6 +33,15 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
    - Se não atendido: registre como "bloqueante" com descrição do gap.
    - Se parcialmente atendido: registre como "pendência" com o que falta.
 
+   **Verificações mecânicas sempre-rodar** (independente do mandate mencionar ou não — cobrem bugs
+   reais já vistos em produção, ver `framework/evals/rubrics/architecture.md` → "Verificações
+   mecânicas obrigatórias"), quando o diff tocar endpoints minimal API ou fetch cross-camada:
+   - Todo serviço injetado numa lambda de endpoint tem `AddScoped`/`AddSingleton`/`AddTransient`
+     correspondente em `Program.cs`. Falha aqui é bloqueante — a app não sobe.
+   - Se há chamada server-direct ao backend e chamada client-side via proxy para o mesmo recurso,
+     confirme que usam duas constantes de prefixo nomeadas distintas, nenhuma reusada para o
+     outro propósito. Falha aqui é bloqueante — quebra silenciosa em runtime, não em build.
+
 4. **Despache o avaliador independente** — o score do Gate 3 nunca é auto-atribuído por quem implementou:
    - Rode a suíte de testes do projeto e capture a **saída real** (não um resumo seu).
    - Gere o **diff da implementação** (`git diff` do range da feature, ou a lista de arquivos do recap.md com seus conteúdos atuais).

package/framework/skills/core/morph-stack-scan/SKILL.md

@@ -4,7 +4,7 @@ description: Varre o codebase existente, detecta stack atual, compara com o stac
 version: core
 when-to-invoke: ao iniciar uma feature em projeto brownfield (codebase já existente)
 user-invokable: true
-cliVersion: "7.9.2"
+cliVersion: "7.9.3"
 ---
 
 # morph-stack-scan

package/framework/skills/core/morph-standards/SKILL.md

@@ -4,7 +4,7 @@ description: Localiza e carrega um standard específico do STANDARDS.json sob de
 version: core
 when-to-invoke: quando precisar consultar um standard específico durante a implementação
 user-invokable: true
-cliVersion: "7.9.2"
+cliVersion: "7.9.3"
 ---
 
 # morph-standards

package/framework/standards/STANDARDS.json

@@ -933,15 +933,26 @@
         "authentication",
         "OAuth",
         "JWT",
-        "session management"
+        "session management",
+        "trusted origins",
+        "EdDSA",
+        "Ed25519",
+        "BouncyCastle",
+        "signature validator",
+        "jwks",
+        "middleware runtime",
+        "api prefix"
       ],
       "anchors": {
         "setup": "#installation--setup",
+        "onboarding": "#onboarding-checklist--do-this-before-testing-login-mandatory",
         "middleware": "#route-protection-middleware",
+        "api-prefix": "#api-prefix-convention--server-direct-vs-client-proxy",
         "dotnet": "#net-backend-integration",
-        "rls": "#row-level-security-integration"
+        "rls": "#row-level-security-integration",
+        "postmortem": "#known-failure-modes-postmortem"
       },
-      "digest": "Use @neondatabase/auth SDK for Next.js. Auth data lives in neon_auth schema — no external provider, no webhooks. Server: createNeonAuth() with NEON_AUTH_BASE_URL + NEON_AUTH_COOKIE_SECRET. Client: createAuthClient(). Pages: AuthView component. Protection: auth.middleware(). .NET: JWT Bearer with Neon Auth authority, NameClaimType=sub. RLS: auth.user_id() via pg_session_jwt."
+      "digest": "Use @neondatabase/auth SDK for Next.js. Auth data lives in neon_auth schema — no external provider, no webhooks. Server: createNeonAuth() with NEON_AUTH_BASE_URL + NEON_AUTH_COOKIE_SECRET. Client: createAuthClient(). Pages: AuthView component. Protection: auth.middleware() with runtime='nodejs' (Edge times out minting the session cookie). Register every dev/preview origin in trusted_origins before testing login. Two named prefix constants (BACKEND_API_PREFIX / PROXY_API_PREFIX) — never share one between server-direct and client-proxy calls. .NET: tokens are EdDSA/Ed25519 (OKP) — Microsoft.IdentityModel.Tokens can't verify OKP keys and there's no OIDC discovery; fetch+cache the JWKS yourself and verify signatures manually via BouncyCastle.Cryptography + TokenValidationParameters.SignatureValidator (must return Microsoft.IdentityModel.JsonWebTokens.JsonWebToken, not JwtSecurityToken — else IDX10506). NeonAuth:BaseUrl is mandatory in appsettings.Development.json (public value). RLS: auth.user_id() via pg_session_jwt."
     },
     {
       "id": "backend-integrations-hangfire-hangfire-jobs",

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

@@ -2,10 +2,15 @@
 
 > **Scope:** universal
 > **Layer:** 2 (on keyword)
-> **Keywords:** neon auth, better auth, authentication, nextjs, user management, session, JWT
+> **Keywords:** neon auth, better auth, authentication, nextjs, user management, session, JWT, trusted origins, EdDSA, Ed25519, BouncyCastle, signature validator, jwks, middleware runtime, api prefix
 > **Load When:** neon auth or authentication keywords detected
 
-**Verified against:** Neon Auth — @neondatabase/auth + @neondatabase/auth-ui (Better Auth). Last-verified: 2026-05-20.
+**Verified against:** Neon Auth — @neondatabase/auth + @neondatabase/auth-ui (Better Auth). Last-verified: 2026-07-13.
+
+> This standard is the reference implementation, not a troubleshooting log. Every section below
+> exists because a real end-to-end run (MORPH_GHLBrain, feature `catalogo-produtos-crud`, task T16,
+> 2026-07-13) hit the failure mode it documents. See [Known Failure Modes](#known-failure-modes-postmortem)
+> for the map from bug → section.
 
 ---
 
@@ -33,6 +38,9 @@ Neon Auth provides:
 2. **Branch Isolation**: Each Neon branch gets isolated users, sessions, and auth config
 3. **Server-First**: Use server-side auth checks with `auth.getSession()`
 4. **JWT for RLS**: Tokens contain `sub` (user ID), `email`, `role: "authenticated"` for database policies
+5. **No OIDC discovery**: Neon Auth does **not** expose `/.well-known/openid-configuration` — only the
+   raw `/.well-known/jwks.json`. Never assume `options.Authority` alone gives you working discovery on
+   the .NET side (see [.NET Backend Integration](#net-backend-integration)).
 
 ---
 
@@ -65,6 +73,27 @@ Generate cookie secret:
 openssl rand -base64 32
 ```
 
+### Onboarding Checklist — Do This Before Testing Login (mandatory)
+
+Run once per environment (local dev, every preview URL, every new dev machine) — **before** the first
+real sign-in attempt, not after debugging a mysterious "session never sticks" bug:
+
+1. **Register every dev/preview origin in `trusted_origins`.** Neon Auth's middleware silently refuses
+   to recognize a session on a full-page navigation from an origin it doesn't know about — there is no
+   error, the user just bounces back to sign-in as if the session never existed. `localhost:3000` is not
+   automatically enough; a second dev port (`localhost:3001`), a new preview deploy URL, or a tunnel URL
+   each need to be added explicitly. Use the `configure_neon_auth` tool (Neon MCP) to list current
+   `trusted_origins` and add the one you're about to test against:
+   ```
+   mcp: Neon.configure_neon_auth  →  confirm/add the exact origin (scheme + host + port) you will open in the browser
+   ```
+   Do this **before** attempting a real login — not as the first debugging step after login silently fails.
+2. Confirm `NEON_AUTH_COOKIE_SECRET` is 32+ characters (`openssl rand -base64 32`).
+3. Confirm `NEON_AUTH_BASE_URL` / `NEXT_PUBLIC_AUTH_URL` point at the same Neon Auth endpoint you
+   configured `trusted_origins` against (branch-specific — see [Branch Isolation](#branch-isolation)).
+4. On the .NET side, confirm `NeonAuth:BaseUrl` exists in `appsettings.Development.json` — see
+   [appsettings.Development.json (mandatory)](#appsettingsdevelopmentjson-mandatory-public-value).
+
 ### SDK Initialization
 
 ```typescript
@@ -195,6 +224,12 @@ export function UserProfile() {
 // middleware.ts
 import { auth } from '@/lib/auth/server';
 
+// MANDATORY for any middleware.ts that touches Neon Auth. Next.js middleware runs on the Edge
+// runtime by default, and the network call the Neon Auth SDK makes to mint the session-data cookie
+// times out inside the Edge sandbox on `next dev` — the request silently bounces back to sign-in
+// even with a fully valid session, with no error surfaced. Force the Node.js runtime instead.
+export const runtime = 'nodejs';
+
 export default auth.middleware({
   loginUrl: '/auth/sign-in',
 });
@@ -262,29 +297,274 @@ export async function GET() {
 
 ---
 
+## API Prefix Convention — Server-Direct vs Client-Proxy
+
+A Next.js app talking to a Neon-Auth-protected .NET backend fetches from **two different places**
+depending on where the code runs:
+
+- **Server Components / Route Handlers** call the .NET backend directly (server-to-server, no browser
+  involved) — the backend's own route prefix applies (e.g. the backend exposes `catalog/items`, no
+  `/api` prefix at all if that's how the VSA endpoints are mapped).
+- **Client Components** cannot call the .NET backend's origin directly without CORS/cookie complications,
+  so they call a **same-origin Next.js proxy route** (e.g. `/api/catalog/items`) which forwards the
+  request (and the session cookie) to the .NET backend.
+
+These are **two distinct prefixes with two distinct purposes**. Collapsing them into a single shared
+constant (`API_PREFIX = '/api'` used for both) silently breaks one of the two call sites the moment the
+backend's real prefix and the proxy's public prefix don't happen to match character-for-character — and
+because this is a runtime routing mismatch (404, or the proxy calling itself), it **never shows up at
+build time**, only when a human clicks the page.
+
+```typescript
+// lib/api/prefixes.ts
+// BACKEND_API_PREFIX: used ONLY by Server Components / Route Handlers calling the .NET backend directly.
+export const BACKEND_API_PREFIX = process.env.API_URL; // e.g. https://api.example.com — backend's own routes have NO /api prefix
+
+// PROXY_API_PREFIX: used ONLY by Client Components calling the same-origin Next.js proxy.
+export const PROXY_API_PREFIX = '/api/proxy'; // matches app/api/proxy/[...path]/route.ts
+```
+
+```typescript
+// app/(dashboard)/catalog/page.tsx — Server Component, direct backend call
+import { BACKEND_API_PREFIX } from '@/lib/api/prefixes';
+
+async function getItems() {
+  // cross-reference: PROXY_API_PREFIX below MUST resolve to the same backend route
+  const res = await fetch(`${BACKEND_API_PREFIX}/catalog/items`, { next: { revalidate: 60 } });
+  return res.json();
+}
+```
+
+```typescript
+// features/catalog/hooks/use-items.ts — Client Component, via same-origin proxy
+import { PROXY_API_PREFIX } from '@/lib/api/prefixes';
+
+export function useItems() {
+  return useQuery({
+    queryKey: ['catalog', 'items'],
+    // cross-reference: BACKEND_API_PREFIX above MUST resolve to the same backend route
+    queryFn: async () => (await fetch(`${PROXY_API_PREFIX}/catalog/items`)).json(),
+  });
+}
+```
+
+**Rule:** never reuse `BACKEND_API_PREFIX` for a proxy call, and never reuse `PROXY_API_PREFIX` for a
+direct server call. If a review needs to check this mechanically: grep for both constants and confirm
+neither name appears on the "wrong" side (Server Component files should only import
+`BACKEND_API_PREFIX`; Client Component / hook files should only import `PROXY_API_PREFIX`).
+
+---
+
 ## .NET Backend Integration
 
-Neon Auth issues standard JWTs. The .NET API validates these tokens directly — no external auth SDK needed.
+Neon Auth issues standard JWTs, **signed with EdDSA (Ed25519, JWK `kty: "OKP"`)**. The .NET API must
+validate these tokens itself — there is no external auth SDK and, critically, **no OIDC discovery
+document to lean on**.
+
+> **`options.Authority` alone does not work here.** Neon Auth does not serve
+> `/.well-known/openid-configuration` — only the raw `/.well-known/jwks.json`. Setting `Authority` and
+> trusting the framework's normal metadata-refresh machinery either does nothing useful or wastes retries
+> against a URL that never returns valid OIDC metadata. Fetch and cache the JWKS yourself (below).
+
+> **`Microsoft.IdentityModel.Tokens` cannot verify these signatures out of the box.** It has no support
+> for OKP (EdDSA/Ed25519) keys — `JsonWebKeySet.GetSigningKeys()` silently drops any OKP key, so
+> `IssuerSigningKeyResolver` never gets a usable key, and every legitimate token is rejected with a bare
+> `401` and no useful error message. .NET has no built-in (BCL) Ed25519 primitive either. The fix below
+> uses `BouncyCastle.Cryptography` (pure C#, no native `libsodium` dependency — safe on Linux containers)
+> and a manual `TokenValidationParameters.SignatureValidator`.
+
+### NuGet Packages
+
+```xml
+<PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.3" />
+<!-- Pure C# Ed25519 — .NET's BCL has no EdDSA primitive. Pin >= 2.3.1: CVE-2024-30172 (infinite loop
+     on a crafted signature) was fixed in 2.3.1; use the current stable release. -->
+<PackageReference Include="BouncyCastle.Cryptography" Version="2.6.2" />
+```
+
+### DI Registration Checklist (do this before marking any auth task done)
+
+Minimal API endpoints infer a lambda parameter's binding source from its type: known simple types come
+from the route/query, `ClaimsPrincipal`/`CancellationToken` are special-cased, and any other complex
+type is bound to the **request body** *unless* it's registered in the DI container, in which case it's
+resolved as a service instead. If you inject a custom service (a tenant resolver, a current-user
+accessor, anything beyond the built-ins) into an endpoint lambda **without registering it**, ASP.NET
+Core silently treats it as a second `[FromBody]` parameter — and the app crashes at startup with
+*"Action ... has more than one parameter that was specified or inferred as bound from request body"*,
+taking down every endpoint in that assembly, not just the one you forgot.
+
+Before marking any task that adds or touches an endpoint as done:
+1. List every parameter type in the endpoint lambda that isn't `TRequest`, `CancellationToken`,
+   `ClaimsPrincipal`, or a route/query primitive.
+2. For each one, confirm a matching `AddScoped<T>()` / `AddSingleton<T>()` / `AddTransient<T>()` exists
+   in `Program.cs` (or via assembly-scanning registration).
+3. If it's missing, the fix is the registration — not a `[FromServices]` attribute band-aid.
 
 ### JWT Bearer Configuration
 
 ```csharp
-// Program.cs
-builder.Services.AddAuthentication("NeonAuth")
-    .AddJwtBearer("NeonAuth", options =>
+// Infrastructure/Auth/NeonAuthOptions.cs
+namespace {ProjectName}.Infrastructure.Auth;
+
+public sealed class NeonAuthOptions
+{
+    public const string SectionName = "NeonAuth";
+
+    /// <summary>Neon Auth Base URL, e.g. https://ep-xxx.neonauth.us-east-2.aws.neon.build/neondb/auth</summary>
+    public string BaseUrl { get; set; } = string.Empty;
+}
+```
+
+```csharp
+// Infrastructure/Auth/NeonAuthJwksProvider.cs
+namespace {ProjectName}.Infrastructure.Auth;
+
+using Microsoft.Extensions.Options;
+using Microsoft.IdentityModel.Tokens;
+
+/// <summary>
+/// Fetches and caches Neon Auth's raw JWKS (/.well-known/jwks.json — there is no OIDC discovery
+/// document). Cached for 15 minutes; a forced refresh happens once when an unknown `kid` is seen,
+/// to survive key rotation without waiting out the TTL.
+/// </summary>
+public sealed class NeonAuthJwksProvider(HttpClient httpClient, IOptions<NeonAuthOptions> options)
+{
+    private static readonly TimeSpan CacheTtl = TimeSpan.FromMinutes(15);
+    private readonly SemaphoreSlim _refreshLock = new(1, 1);
+    private JsonWebKeySet? _cached;
+    private DateTimeOffset _cachedAt;
+
+    public async Task<JsonWebKey?> GetKeyAsync(string kid, CancellationToken cancellationToken)
     {
-        options.Authority = builder.Configuration["NeonAuth:BaseUrl"];
-        options.TokenValidationParameters = new()
+        var keySet = await GetKeySetAsync(forceRefresh: false, cancellationToken);
+        var key = keySet.Keys.FirstOrDefault(k => k.Kid == kid);
+        if (key is not null) return key;
+
+        // Unknown kid — could be key rotation. Force a single refresh before giving up.
+        keySet = await GetKeySetAsync(forceRefresh: true, cancellationToken);
+        return keySet.Keys.FirstOrDefault(k => k.Kid == kid);
+    }
+
+    private async Task<JsonWebKeySet> GetKeySetAsync(bool forceRefresh, CancellationToken cancellationToken)
+    {
+        if (!forceRefresh && _cached is not null && DateTimeOffset.UtcNow - _cachedAt < CacheTtl)
+            return _cached;
+
+        await _refreshLock.WaitAsync(cancellationToken);
+        try
         {
-            ValidateIssuer = true,
-            ValidateAudience = false,
-            ValidateLifetime = true,
-            ValidateIssuerSigningKey = true,
-            NameClaimType = "sub"
-        };
-    });
-
-builder.Services.AddAuthorization();
+            if (!forceRefresh && _cached is not null && DateTimeOffset.UtcNow - _cachedAt < CacheTtl)
+                return _cached;
+
+            var jwksUri = $"{options.Value.BaseUrl.TrimEnd('/')}/.well-known/jwks.json";
+            var json = await httpClient.GetStringAsync(jwksUri, cancellationToken);
+            _cached = new JsonWebKeySet(json);
+            _cachedAt = DateTimeOffset.UtcNow;
+            return _cached;
+        }
+        finally
+        {
+            _refreshLock.Release();
+        }
+    }
+}
+```
+
+```csharp
+// Infrastructure/Auth/NeonAuthServiceExtensions.cs
+namespace {ProjectName}.Infrastructure.Auth;
+
+using System.Text;
+using Microsoft.AspNetCore.Authentication.JwtBearer;
+using Microsoft.Extensions.Options;
+using Microsoft.IdentityModel.JsonWebTokens;
+using Microsoft.IdentityModel.Tokens;
+using Org.BouncyCastle.Crypto.Parameters;
+using Org.BouncyCastle.Crypto.Signers;
+
+public static class NeonAuthServiceExtensions
+{
+    public static IServiceCollection AddNeonAuthentication(
+        this IServiceCollection services,
+        IConfiguration configuration)
+    {
+        services.Configure<NeonAuthOptions>(configuration.GetSection(NeonAuthOptions.SectionName));
+        services.AddHttpClient<NeonAuthJwksProvider>();
+
+        services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
+            .AddJwtBearer(options =>
+            {
+                // Do NOT set options.Authority — Neon Auth serves no /.well-known/openid-configuration,
+                // so Authority-driven metadata refresh has nothing valid to fetch. ValidIssuer is set
+                // explicitly below instead.
+                options.TokenValidationParameters = new TokenValidationParameters
+                {
+                    ValidateIssuer = true,
+                    ValidIssuer = configuration["NeonAuth:BaseUrl"],
+                    ValidateAudience = false,
+                    ValidateLifetime = true,
+                    NameClaimType = "sub",
+                    // Trust in the signing key is established entirely inside SignatureValidator
+                    // below (fetched from our own cached JWKS) — this flag doesn't gate that path.
+                    ValidateIssuerSigningKey = false,
+                };
+            });
+
+        // A second Configure<TDep> pass with DI available — AddJwtBearer's own setup has already run,
+        // so this only *adds* the SignatureValidator to the TokenValidationParameters built above.
+        services.AddOptions<JwtBearerOptions>(JwtBearerDefaults.AuthenticationScheme)
+            .Configure<NeonAuthJwksProvider>((options, jwks) =>
+            {
+                options.TokenValidationParameters.SignatureValidator = (token, _) =>
+                {
+                    var jwt = new JsonWebToken(token);
+
+                    // Pin the algorithm — refuse anything that isn't EdDSA to block alg-substitution attacks.
+                    if (!string.Equals(jwt.Alg, "EdDSA", StringComparison.Ordinal))
+                        throw new SecurityTokenInvalidSignatureException(
+                            $"Unsupported alg '{jwt.Alg}' — Neon Auth tokens must be EdDSA.");
+
+                    var kid = jwt.Kid;
+                    if (string.IsNullOrEmpty(kid))
+                        throw new SecurityTokenInvalidSignatureException("Token is missing 'kid'.");
+
+                    // Blocking call: JWKS is cached in-memory (see NeonAuthJwksProvider), so this is
+                    // I/O-free on the hot path. SignatureValidator has no async overload in this
+                    // library version — only a cold-start / key-rotation miss ever awaits real I/O here.
+                    var jwk = jwks.GetKeyAsync(kid, CancellationToken.None).GetAwaiter().GetResult()
+                        ?? throw new SecurityTokenInvalidSignatureException($"No JWKS key found for kid '{kid}'.");
+
+                    if (jwk.Kty != "OKP" || jwk.Crv != "Ed25519")
+                        throw new SecurityTokenInvalidSignatureException("JWKS key is not an Ed25519 (OKP) key.");
+
+                    var parts = token.Split('.');
+                    if (parts.Length != 3)
+                        throw new SecurityTokenInvalidSignatureException("Malformed JWT — expected 3 segments.");
+
+                    var signingInput = Encoding.ASCII.GetBytes($"{parts[0]}.{parts[1]}");
+                    var signature = Base64UrlEncoder.DecodeBytes(parts[2]);
+                    var publicKey = new Ed25519PublicKeyParameters(Base64UrlEncoder.DecodeBytes(jwk.X), 0);
+
+                    var verifier = new Ed25519Signer();
+                    verifier.Init(forSigning: false, publicKey);
+                    verifier.BlockUpdate(signingInput, 0, signingInput.Length);
+
+                    if (!verifier.VerifySignature(signature))
+                        throw new SecurityTokenInvalidSignatureException("Ed25519 signature verification failed.");
+
+                    // MUST return Microsoft.IdentityModel.JsonWebTokens.JsonWebToken — ASP.NET Core 8+
+                    // uses JsonWebTokenHandler internally. Returning a
+                    // System.IdentityModel.Tokens.Jwt.JwtSecurityToken here fails with IDX10506
+                    // ("SignatureValidator returned a token of an unexpected type").
+                    return jwt;
+                };
+            });
+
+        services.AddAuthorization();
+
+        return services;
+    }
+}
 ```
 
 ### Protected Endpoints
@@ -298,7 +578,7 @@ app.MapGet("/api/profile", (ClaimsPrincipal user) =>
 }).RequireAuthorization();
 ```
 
-### appsettings.json
+### appsettings.Development.json (mandatory, public value)
 
 ```json
 {
@@ -308,6 +588,30 @@ app.MapGet("/api/profile", (ClaimsPrincipal user) =>
 }
 ```
 
+This is **not optional** and **not a secret** — it's the Neon Auth endpoint URL, safe to commit.
+Without it, `NeonAuthOptions.BaseUrl` resolves to an empty string, the JWKS fetch fails, and every
+request is rejected the same way a broken signature validator would fail: a bare `401` with nothing
+in the logs pointing at the real cause. Add it to `appsettings.Development.json` specifically (not only
+`appsettings.json`) when scaffolding the backend — it's easy to add the entry to one and forget the
+other, and the app only fails in the environment missing it.
+
+### Program.cs Usage
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddNeonAuthentication(builder.Configuration);
+
+var app = builder.Build();
+
+app.UseAuthentication();
+app.UseAuthorization();
+
+app.MapControllers().RequireAuthorization();
+
+app.Run();
+```
+
 ---
 
 ## Row-Level Security Integration
@@ -360,7 +664,32 @@ Each Neon branch gets its own isolated auth data. This means:
 3. **Use `auth.user_id()` for RLS** — never extract JWT claims manually in SQL
 4. **Configure OAuth in Neon Console** — not in code
 5. **Use `SignedIn` / `RedirectToSignIn`** for client-side protection
-6. **Use middleware** for broad route protection patterns
+6. **Use middleware** for broad route protection patterns — and force `runtime = 'nodejs'` (Edge times
+   out minting the session-data cookie)
+7. **Register every dev/preview origin in `trusted_origins`** before testing login, not after it fails
+8. **Never share a route-prefix constant** between server-direct backend calls and client-side proxy
+   calls — use two named constants (`BACKEND_API_PREFIX` / `PROXY_API_PREFIX`)
+9. **Verify DI registration for every service injected into an endpoint lambda** — an unregistered
+   service silently becomes a phantom `[FromBody]` parameter and crashes the app at startup
+10. **On .NET, never rely on `options.Authority` alone** — Neon Auth has no OIDC discovery document;
+    fetch and cache the JWKS yourself and verify EdDSA signatures manually (BouncyCastle)
+
+---
+
+## Known Failure Modes (Postmortem)
+
+Real bugs hit during the `catalogo-produtos-crud` end-to-end run (MORPH_GHLBrain, task T16,
+2026-07-13). Each one now has a permanent fix in this standard — this table exists so a review can
+scan it in one pass instead of rediscovering these by trial and error.
+
+| # | Symptom | Root cause | Fixed in |
+|---|---------|------------|----------|
+| 1 | App crashes at startup on a specific endpoint | Custom service injected into an endpoint lambda without DI registration — Minimal API infers it as a second `[FromBody]` parameter | [DI Registration Checklist](#di-registration-checklist-do-this-before-marking-any-auth-task-done) |
+| 2 | A route works from the server but 404s from the client (or vice versa) | Single shared prefix constant reused for both the direct backend call and the same-origin proxy call | [API Prefix Convention](#api-prefix-convention--server-direct-vs-client-proxy) |
+| 3 | Session never sticks after a full-page navigation, no error shown | New dev/preview origin not registered in Neon Auth `trusted_origins` | [Onboarding Checklist](#onboarding-checklist--do-this-before-testing-login-mandatory) |
+| 4 | Valid session still bounces back to sign-in on `next dev` | `middleware.ts` runs on Edge runtime by default; the session-data cookie mint call times out there | [Route Protection (Middleware)](#route-protection-middleware) |
+| 5 | Every legitimate request gets a bare `401`, no useful log | `Microsoft.IdentityModel.Tokens` can't verify EdDSA/OKP signatures — `IssuerSigningKeyResolver` never finds a usable key | [.NET Backend Integration](#net-backend-integration) |
+| 6 | Same bare-`401` symptom as #5, different cause | `NeonAuth:BaseUrl` missing from `appsettings.Development.json` | [appsettings.Development.json](#appsettingsdevelopmentjson-mandatory-public-value) |
 
 ---
 
@@ -369,6 +698,8 @@ Each Neon branch gets its own isolated auth data. This means:
 - [Neon Auth Documentation](https://neon.com/docs/auth)
 - [Neon Auth Authentication Flow](https://neon.com/docs/auth/authentication-flow)
 - [Migration from Legacy Auth](https://neon.com/docs/auth/migrate/from-legacy-auth)
+- [RFC 8037 — EdDSA for JOSE](https://www.rfc-editor.org/rfc/rfc8037) — `alg: "EdDSA"`, `kty: "OKP"`, `crv: "Ed25519"`
+- [BouncyCastle.Cryptography (NuGet)](https://www.nuget.org/packages/BouncyCastle.Cryptography)
 
 ---
 

package/framework/standards/frontend/nextjs/app-router.md

@@ -74,12 +74,17 @@ src/app/
 
 ## Server Component Data Fetch Pattern
 
+Server Components call the .NET backend directly — use a dedicated `BACKEND_API_PREFIX` constant, never
+the same-origin proxy prefix Client Components use. See `frontend/nextjs/data-fetching.md` →
+"Common Mistakes" and `backend/integrations/neon-auth/neon-auth.md` → "API Prefix Convention".
+
 ```tsx
 // app/(dashboard)/users/page.tsx
 import { UserList } from '@/features/users/components/user-list';
+import { BACKEND_API_PREFIX } from '@/lib/api/prefixes'; // server-direct prefix ONLY
 
 async function getUsers(): Promise<User[]> {
-  const res = await fetch(`${process.env.API_URL}/api/users`, {
+  const res = await fetch(`${BACKEND_API_PREFIX}/users`, {
     next: { revalidate: 60 },
   });
   if (!res.ok) throw new Error('Failed to fetch users');

package/framework/standards/frontend/nextjs/data-fetching.md

@@ -51,12 +51,19 @@ export const userKeys = {
 
 ## useQuery Hook Pattern
 
+Client Components never call the .NET backend directly — they call a same-origin proxy route. Use a
+dedicated `PROXY_API_PREFIX` constant for this, never the backend's own prefix (see
+[Common Mistakes](#common-mistakes) and `backend/integrations/neon-auth/neon-auth.md` →
+"API Prefix Convention" for why sharing one constant between server-direct and proxy calls silently
+breaks one of the two at runtime).
+
 ```ts
 // features/users/hooks/use-users.ts
 import { useQuery } from '@tanstack/react-query';
 import { userKeys } from './query-keys';
 import { z } from 'zod';
 import { userSchema } from '@/features/users/types/user.schemas';
+import { PROXY_API_PREFIX } from '@/lib/api/prefixes'; // client-proxy prefix ONLY — never BACKEND_API_PREFIX here
 
 const usersResponseSchema = z.array(userSchema);
 
@@ -64,7 +71,7 @@ export function useUsers() {
   return useQuery({
     queryKey: userKeys.lists(),
     queryFn: async () => {
-      const res = await fetch('/api/proxy/users');
+      const res = await fetch(`${PROXY_API_PREFIX}/users`);
       if (!res.ok) throw new Error('Failed to fetch users');
       return usersResponseSchema.parse(await res.json());
     },
@@ -79,12 +86,13 @@ export function useUsers() {
 import { useMutation, useQueryClient } from '@tanstack/react-query';
 import { userKeys } from './query-keys';
 import type { CreateUserInput } from '@/features/users/types/user.types';
+import { PROXY_API_PREFIX } from '@/lib/api/prefixes';
 
 export function useCreateUser() {
   const queryClient = useQueryClient();
   return useMutation({
     mutationFn: async (input: CreateUserInput) => {
-      const res = await fetch('/api/proxy/users', {
+      const res = await fetch(`${PROXY_API_PREFIX}/users`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify(input),
@@ -101,10 +109,15 @@ export function useCreateUser() {
 
 ## Server Component + TanStack Query Handoff
 
+Server Components call the .NET backend directly — use `BACKEND_API_PREFIX`, never the client-proxy
+constant, and never a single shared `API_PREFIX` reused for both call sites.
+
 ```tsx
 // app/(dashboard)/users/page.tsx — Server Component: initial fetch
+import { BACKEND_API_PREFIX } from '@/lib/api/prefixes'; // server-direct prefix ONLY — never PROXY_API_PREFIX here
+
 export default async function UsersPage() {
-  const initialUsers = await fetch(`${process.env.API_URL}/api/users`).then(r => r.json());
+  const initialUsers = await fetch(`${BACKEND_API_PREFIX}/users`).then(r => r.json());
   return <UserListClient initialData={initialUsers} />;
 }
 
@@ -124,6 +137,7 @@ export function UserListClient({ initialData }: { initialData: User[] }) {
 | No Zod on API response | `schema.parse(await res.json())` | Type safety at runtime |
 | Hardcoded query keys: `['users']` | Key factory: `userKeys.lists()` | Consistent invalidation |
 | `queryClient.invalidateQueries(['users'])` | `{ queryKey: userKeys.lists() }` | Object syntax required in v5 |
+| One shared `API_PREFIX` for server-direct AND client-proxy fetches | Two named constants: `BACKEND_API_PREFIX` / `PROXY_API_PREFIX` | Silent runtime break on whichever side drifts — no build-time signal |
 
 ---
 

package/framework/templates/REGISTRY.json

@@ -648,9 +648,9 @@
       "category": "integration",
       "phase": "implement",
       "required": false,
-      "description": "Neon Auth (Better Auth) authentication configuration for .NET",
+      "description": "Neon Auth (Better Auth) EdDSA/Ed25519 JWT validation for .NET via BouncyCastle — cached JWKS provider + manual SignatureValidator (no OIDC discovery available)",
       "outputName": "NeonAuthConfig.cs",
-      "placeholders": [],
+      "placeholders": ["Namespace"],
       "stackSpecific": false,
       "engine": "handlebars",
       "deprecated": false,

package/framework/templates/integrations/neon-auth-config.cs

@@ -1,12 +1,28 @@
 // ==============================================================================
 // MORPH-SPEC - Neon Auth Configuration Template
 // Configuracao de autenticacao com Neon Auth (Better Auth) para .NET
+//
+// Neon Auth tokens are signed with EdDSA (Ed25519, JWK kty "OKP"). There is no
+// OIDC discovery document (/.well-known/openid-configuration) — only the raw
+// /.well-known/jwks.json — and Microsoft.IdentityModel.Tokens cannot verify
+// OKP/EdDSA signatures on its own. See:
+//   .morph/framework/standards/backend/integrations/neon-auth/neon-auth.md
+//   → "## .NET Backend Integration" for the full reference and rationale.
+//
+// NuGet (add both):
+//   <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.3" />
+//   <PackageReference Include="BouncyCastle.Cryptography" Version="2.6.2" /> <!-- pin >= 2.3.1, CVE-2024-30172 -->
 // ==============================================================================
 
+using System.Security.Claims;
+using System.Text;
 using Microsoft.AspNetCore.Authentication;
 using Microsoft.AspNetCore.Authentication.JwtBearer;
+using Microsoft.Extensions.Options;
+using Microsoft.IdentityModel.JsonWebTokens;
 using Microsoft.IdentityModel.Tokens;
-using System.Security.Claims;
+using Org.BouncyCastle.Crypto.Parameters;
+using Org.BouncyCastle.Crypto.Signers;
 
 namespace {{Namespace}}.Infrastructure.Auth;
 
@@ -19,11 +35,65 @@ public class NeonAuthOptions
     public const string SectionName = "NeonAuth";
 
     /// <summary>
-    /// Neon Auth Base URL (e.g., https://ep-xxx.neonauth.us-east-2.aws.neon.build/neondb/auth)
+    /// Neon Auth Base URL (e.g., https://ep-xxx.neonauth.us-east-2.aws.neon.build/neondb/auth).
+    /// MUST be present in appsettings.Development.json — it's a public value, not a secret.
+    /// Missing it produces the same symptom as a broken signature validator: every request
+    /// gets a bare 401 with nothing useful in the logs.
     /// </summary>
     public string BaseUrl { get; set; } = string.Empty;
 }
 
+// ==============================================================================
+// JWKS PROVIDER (cached — Neon Auth has no OIDC discovery to piggyback on)
+// ==============================================================================
+
+/// <summary>
+/// Fetches and caches Neon Auth's raw JWKS. Cached for 15 minutes; a forced refresh
+/// happens once when an unknown `kid` is seen, to survive key rotation without
+/// waiting out the TTL.
+/// </summary>
+public sealed class NeonAuthJwksProvider(HttpClient httpClient, IOptions<NeonAuthOptions> options)
+{
+    private static readonly TimeSpan CacheTtl = TimeSpan.FromMinutes(15);
+    private readonly SemaphoreSlim _refreshLock = new(1, 1);
+    private JsonWebKeySet? _cached;
+    private DateTimeOffset _cachedAt;
+
+    public async Task<JsonWebKey?> GetKeyAsync(string kid, CancellationToken cancellationToken)
+    {
+        var keySet = await GetKeySetAsync(forceRefresh: false, cancellationToken);
+        var key = keySet.Keys.FirstOrDefault(k => k.Kid == kid);
+        if (key is not null) return key;
+
+        // Unknown kid — could be key rotation. Force a single refresh before giving up.
+        keySet = await GetKeySetAsync(forceRefresh: true, cancellationToken);
+        return keySet.Keys.FirstOrDefault(k => k.Kid == kid);
+    }
+
+    private async Task<JsonWebKeySet> GetKeySetAsync(bool forceRefresh, CancellationToken cancellationToken)
+    {
+        if (!forceRefresh && _cached is not null && DateTimeOffset.UtcNow - _cachedAt < CacheTtl)
+            return _cached;
+
+        await _refreshLock.WaitAsync(cancellationToken);
+        try
+        {
+            if (!forceRefresh && _cached is not null && DateTimeOffset.UtcNow - _cachedAt < CacheTtl)
+                return _cached;
+
+            var jwksUri = $"{options.Value.BaseUrl.TrimEnd('/')}/.well-known/jwks.json";
+            var json = await httpClient.GetStringAsync(jwksUri, cancellationToken);
+            _cached = new JsonWebKeySet(json);
+            _cachedAt = DateTimeOffset.UtcNow;
+            return _cached;
+        }
+        finally
+        {
+            _refreshLock.Release();
+        }
+    }
+}
+
 // ==============================================================================
 // SERVICE EXTENSIONS
 // ==============================================================================
@@ -31,28 +101,91 @@ public class NeonAuthOptions
 public static class NeonAuthServiceExtensions
 {
     /// <summary>
-    /// Adds Neon Auth JWT Bearer authentication to the project.
-    /// Validates JWTs issued by Neon Auth service.
+    /// Adds Neon Auth JWT Bearer authentication to the project. Validates EdDSA-signed
+    /// JWTs issued by Neon Auth via a manually-fetched, cached JWKS — see
+    /// NeonAuthJwksProvider above and the standard's "## .NET Backend Integration" section
+    /// for why options.Authority / the default IssuerSigningKeyResolver do not work here.
     /// </summary>
     public static IServiceCollection AddNeonAuthentication(
         this IServiceCollection services,
         IConfiguration configuration)
     {
         services.Configure<NeonAuthOptions>(configuration.GetSection(NeonAuthOptions.SectionName));
-
-        var neonAuthOptions = configuration.GetSection(NeonAuthOptions.SectionName).Get<NeonAuthOptions>()!;
+        services.AddHttpClient<NeonAuthJwksProvider>();
 
         services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
             .AddJwtBearer(options =>
             {
-                options.Authority = neonAuthOptions.BaseUrl;
+                // Do NOT set options.Authority — Neon Auth serves no
+                // /.well-known/openid-configuration, so Authority-driven metadata refresh
+                // has nothing valid to fetch. ValidIssuer is set explicitly instead.
                 options.TokenValidationParameters = new TokenValidationParameters
                 {
                     ValidateIssuer = true,
+                    ValidIssuer = configuration["NeonAuth:BaseUrl"],
                     ValidateAudience = false,
                     ValidateLifetime = true,
-                    ValidateIssuerSigningKey = true,
-                    NameClaimType = "sub"
+                    NameClaimType = "sub",
+                    // Trust in the signing key is established entirely inside
+                    // SignatureValidator below (fetched from our own cached JWKS) —
+                    // this flag doesn't gate that path.
+                    ValidateIssuerSigningKey = false,
+                };
+            });
+
+        // A second Configure<TDep> pass with DI available — AddJwtBearer's own setup has
+        // already run, so this only *adds* the SignatureValidator to the
+        // TokenValidationParameters instance built above.
+        services.AddOptions<JwtBearerOptions>(JwtBearerDefaults.AuthenticationScheme)
+            .Configure<NeonAuthJwksProvider>((options, jwks) =>
+            {
+                options.TokenValidationParameters.SignatureValidator = (token, _) =>
+                {
+                    var jwt = new JsonWebToken(token);
+
+                    // Pin the algorithm — refuse anything that isn't EdDSA to block
+                    // alg-substitution attacks.
+                    if (!string.Equals(jwt.Alg, "EdDSA", StringComparison.Ordinal))
+                        throw new SecurityTokenInvalidSignatureException(
+                            $"Unsupported alg '{jwt.Alg}' — Neon Auth tokens must be EdDSA.");
+
+                    var kid = jwt.Kid;
+                    if (string.IsNullOrEmpty(kid))
+                        throw new SecurityTokenInvalidSignatureException("Token is missing 'kid'.");
+
+                    // Blocking call: JWKS is cached in-memory, so this is I/O-free on the hot
+                    // path. SignatureValidator has no async overload — only a cold-start /
+                    // key-rotation miss ever awaits real I/O here.
+                    var jwk = jwks.GetKeyAsync(kid, CancellationToken.None).GetAwaiter().GetResult()
+                        ?? throw new SecurityTokenInvalidSignatureException(
+                            $"No JWKS key found for kid '{kid}'.");
+
+                    if (jwk.Kty != "OKP" || jwk.Crv != "Ed25519")
+                        throw new SecurityTokenInvalidSignatureException(
+                            "JWKS key is not an Ed25519 (OKP) key.");
+
+                    var parts = token.Split('.');
+                    if (parts.Length != 3)
+                        throw new SecurityTokenInvalidSignatureException(
+                            "Malformed JWT — expected 3 segments.");
+
+                    var signingInput = Encoding.ASCII.GetBytes($"{parts[0]}.{parts[1]}");
+                    var signature = Base64UrlEncoder.DecodeBytes(parts[2]);
+                    var publicKey = new Ed25519PublicKeyParameters(Base64UrlEncoder.DecodeBytes(jwk.X), 0);
+
+                    var verifier = new Ed25519Signer();
+                    verifier.Init(forSigning: false, publicKey);
+                    verifier.BlockUpdate(signingInput, 0, signingInput.Length);
+
+                    if (!verifier.VerifySignature(signature))
+                        throw new SecurityTokenInvalidSignatureException(
+                            "Ed25519 signature verification failed.");
+
+                    // MUST return Microsoft.IdentityModel.JsonWebTokens.JsonWebToken — ASP.NET
+                    // Core 8+ uses JsonWebTokenHandler internally. Returning a
+                    // System.IdentityModel.Tokens.Jwt.JwtSecurityToken here fails with
+                    // IDX10506 ("SignatureValidator returned a token of an unexpected type").
+                    return jwt;
                 };
             });
 
@@ -100,7 +233,7 @@ public static class NeonAuthMiddlewareExtensions
 }
 
 // ==============================================================================
-// APPSETTINGS EXAMPLE
+// APPSETTINGS.DEVELOPMENT.JSON — mandatory, public value, safe to commit
 // ==============================================================================
 
 /*
@@ -118,7 +251,7 @@ public static class NeonAuthMiddlewareExtensions
 /*
 var builder = WebApplication.CreateBuilder(args);
 
-// Add Neon Auth authentication
+// Add Neon Auth authentication (registers the JWKS provider + EdDSA signature validator)
 builder.Services.AddNeonAuthentication(builder.Configuration);
 builder.Services.AddHttpContextAccessor();
 builder.Services.AddScoped<ICurrentUserService, CurrentUserService>();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "7.9.2",
+  "version": "7.9.3",
   "description": "MORPH-SPEC: NLH (Natural Language Harness) for spec-driven development with Claude Code",
   "keywords": [
     "claude-code",