neon-auth-integration

name	neon-auth-integration
description	Complete Neon Auth integration setup for AFENDA, addressing gaps in current codebase. Covers provisioning, server SDK, client SDK, bearer token verification, and security module integration.

Neon Auth Integration for AFENDA

Quick Reference: Vite Quickstart vs. AFENDA Next.js Implementation

The official Neon Auth quickstart is for Vite + React Router (simple client-centric). AFENDA uses Next.js 16 App Router (server + client architecture). This skill adapts the official patterns for Next.js.

Aspect	Official Quickstart	AFENDA Skill
Framework	Vite + React Router	Next.js 16 App Router
Server SDK	None (client-only)	@neondatabase/auth/next/server ✅
Client SDK	@neondatabase/neon-js	@neondatabase/neon-js ✅
Env var	VITE_NEON_AUTH_URL	NEXT_PUBLIC_NEON_AUTH_URL + NEON_AUTH_BASE_URL
Auth Init	createAuthClient() in src/lib/auth.ts	createNeonAuth() in src/lib/auth/server.ts
Route Handler	None (Vite doesn't need it)	app/api/auth/[...auth]/route.ts (Next.js pattern)
Session API	authClient.useSession() (hook)	auth.api.getSession() (server)
UI Components	AuthView, AccountView pre-built	Same + custom Next.js Page wrappers
Multi-tenancy	Not in quickstart	✅ Bridged via toAfendaSession()
API Bearer Tokens	Not covered	✅ Full JWKS + JWT verification
RLS Policies	Not covered	✅ Org isolation patterns

Key Insight: All official Neon Auth APIs are identical; we just adapt the framework-specific setup for Next.js and add AFENDA's multi-tenancy layer.

---

Overview

Neon Auth is a managed authentication service built on Better Auth. This skill provides:

• Complete provisioning workflow for AFENDA's Neon project
• Server-side (Next.js) and client-side SDK integration
• Bearer token verification in Fastify API
• Integration patterns with 67 existing security/governance modules
• Database schema alignment (neon_auth ↔ auth-* security tables)
• Branching-aware auth during preview deployments

Status: Migration from NextAuth v5 → Neon Auth COMPLETE. Validated 2026-03-16.

• ✅ NextAuth removed from runtime
• ✅ Neon Auth provisioned (project lucky-silence-39754997, neon_auth schema live)
• ✅ Server SDK wired (apps/web/src/lib/auth/server.ts — 1,640+ lines, 46 exports)
• ✅ Client SDK wired (apps/web/src/lib/auth/client.ts — createAuthClient() + hooks)
• ✅ Bearer token verification live (apps/api/src/plugins/auth.ts — JWKS + jose.jwtVerify)
• ✅ Session context bridged (apps/web/auth.ts — toAuthSession() enrichment)
• ✅ Sync trigger deployed (sync_neon_auth_user_to_afenda_identity on neon_auth.user)
• ⚠️ No RLS policies on neon_auth.* tables (managed by Neon — not user-editable)
• ⚠️ Zero users registered yet (0 neon_auth.user rows, 0 active sessions)
• ⚠️ Session enrichment reads from Neon Auth claims only — no server-side resolvePrincipalContext() call in web layer (API layer does this via JWT)

---

Current Status Checklist (Validated 2026-03-16)

• Database schema: neon_auth schema provisioned with 9 tables (user, session, account, verification, jwks, organization, member, invitation, project_config)
• Server SDK: @neondatabase/auth v1.4.18 installed, createNeonAuth() in apps/web/src/lib/auth/server.ts
• Server handler: Route handler at apps/web/src/app/api/auth/[...path]/route.ts proxies GET/POST/PUT/DELETE/PATCH
• Client SDK: createAuthClient() from @neondatabase/auth/next in apps/web/src/lib/auth/client.ts with useSession, signIn, signOut, etc.
• API bearer verification: jose.jwtVerify() + createRemoteJWKSet() in apps/api/src/plugins/auth.ts — resolves email → resolvePrincipalContext()
• Cookie handling: apps/web/src/lib/api-client.ts reads session / __Secure-session cookies + Bearer token forwarding
• Session context: resolvePrincipalContext() in packages/core/src/kernel/identity/auth.ts — 7-step principal resolution (API layer)
• RLS policies: No RLS on neon_auth.* tables (Neon-managed schema). AFENDA public.* tables have org_isolation policies via current_setting('app.org_id')
• Multi-tenancy: toAuthSession() in apps/web/auth.ts bridges Neon Auth identity → AFENDA org/role context; auto-assigns single org
• OWNERS.md: apps/web/OWNERS.md references Neon Auth route handler, sign-in page, and auth shim
• Sync trigger: sync_neon_auth_user_to_afenda_identity trigger on neon_auth.user INSERT — creates party, person, iam_principal, party_role, membership
• JWKS: 1 JWKS key pair in neon_auth.jwks for JWT signing/verification
• Env validation: NEON_AUTH_BASE_URL, NEON_AUTH_COOKIE_SECRET (≥32 chars), NEXT_PUBLIC_NEON_AUTH_URL, NEON_AUTH_JWKS_URL all validated in packages/core/src/kernel/infrastructure/env.ts
• Middleware: neonProtectedRouteMiddleware in apps/web/proxy.ts protects /app/*, /admin/*, /finance/*, etc.

---

Phase 0: Prerequisites

0.1 Understand Official Neon Auth Architecture

Important: Neon Auth documentation provides two primary quickstarts:

1. Vite + React Router (Simple, client-centric)

   • Uses unified SDK: @neondatabase/neon-js
   • Env var: VITE_NEON_AUTH_URL
   • Single client setup file
   • Pre-built UI components handle auth entirely

2. Next.js App Router (This skill — More control)

   • Uses server SDK: @neondatabase/auth/next/server
   • Uses client SDK: @neondatabase/neon-js
   • Separate server/client modules
   • Custom route handlers + components
   • Better for multi-tenancy and Fastify API integration

AFENDA uses Next.js, so follow this skill's approach (not the Vite quickstart).

0.2 Environment Validation

Verify AFENDA env schema accepts Neon Auth variables:

✅ DONE — All env vars are configured in packages/core/src/kernel/infrastructure/env.ts:

• ✅ NEON_AUTH_BASE_URL — optional, URL-validated (line 116)
• ✅ NEON_AUTH_COOKIE_SECRET — optional, min 32 chars (line 117–119)
• ✅ NEXT_PUBLIC_NEON_AUTH_URL — optional, URL-validated (line 122–124)
• ✅ NEON_AUTH_JWKS_URL — optional, URL-validated (line 120)
• ✅ All secrets redacted in redactEnv() (line 232)

0.3 Neon Project Readiness

✅ DONE — Verified via Neon MCP 2026-03-16:

• ✅ Neon project: lucky-silence-39754997 (name: AFENDA)
• ✅ Org: org-fragrant-lake-90358173 (name: Jack, plan: Launch)
• ✅ Region: aws-ap-southeast-1 (AWS — Neon Auth compatible)
• ✅ PostgreSQL 17
• ✅ Branches: production (primary) + v2 (child)
• ✅ neon_auth schema active with 9 tables

0.4 Dependency Installation

# Server SDK for Next.js App Router
pnpm add -W @neondatabase/auth

# Unified client SDK (includes UI components)
pnpm add -W @neondatabase/neon-js

# Already installed, but verify
pnpm list zod
pnpm list react react-dom

Compatibility Matrix:

• @neondatabase/auth: Latest (Better Auth 1.4.18)
• @neondatabase/neon-js: Latest (includes @neondatabase/auth/react/ui)
• React: 19+ (AFENDA uses 19.1)
• Next.js: 16+ (AFENDA uses 16.1)

---

Phase 1: Provision Neon Auth

✅ PHASE COMPLETE — Validated 2026-03-16 via Neon MCP

1A. Via Neon Console (Easiest)

1. Open https://console.neon.tech
2. Navigate to your project
3. Auth tab → Enable Neon Auth
4. Select database and org context
5. Wait for neon_auth schema to be created

✅ VERIFIED — neon_auth schema contains 9 tables:

Table	Purpose	Status
neon_auth.user	User identities (id, email, name, role, banned)	✅ Live (0 rows)
neon_auth.session	Login sessions (token, userId, activeOrganizationId, impersonatedBy)	✅ Live (0 active)
neon_auth.account	OAuth accounts (providerId, accessToken, password)	✅ Live
neon_auth.verification	Email/2FA verification codes	✅ Live
neon_auth.jwks	JWT signing keys for bearer verification	✅ Live (1 key pair)
neon_auth.organization	Neon Auth orgs (id, slug, name)	✅ Live (0 rows)
neon_auth.member	Org membership	✅ Live
neon_auth.invitation	Org invitations	✅ Live
neon_auth.project_config	Auth project settings	✅ Live

1B. Via Drizzle Introspection (For CI/CD)

After Neon Console enables auth, introspect the schema:

pnpm db:generate
# Drizzle will discover neon_auth schema tables:
# - neon_auth.user
# - neon_auth.session
# - neon_auth.account
# - neon_auth.verification

Expected tables in packages/db/src/schema/:

schema/
  neon-auth/
    neon-auth-accounts.ts      (OAuth provider accounts)
    neon-auth-sessions.ts      (Login sessions)
    neon-auth-users.ts         (User identities)
    neon-auth-verifications.ts (Email/2FA verification codes)
    relations.ts               (Foreign keys)

Do NOT edit these files. They are auto-generated and controlled by Neon Auth lifecycle.

---

Phase 2: Server-Side SDK Setup (Next.js App Router)

✅ PHASE COMPLETE — apps/web/src/lib/auth/server.ts (1,640+ lines, 46 exports)

2A. Create Server Auth Module

File: apps/web/src/lib/auth/server.ts (NEW)

This file instantiates the official Neon Auth server SDK per documented pattern.

/**
 * Neon Auth Server SDK for Next.js App Router.
 *
 * Official pattern from https://neon.com/docs/auth/quick-start/nextjs
 *
 * This is the source of truth for:
 * - Route handler at /api/auth/[...auth]/route.ts
 * - Server-side session verification
 * - Cookie-based session management
 *
 * Architecture:
 * - Neon Auth provides identity (user, session, OAuth)
 * - AFENDA auth/* modules provide governance (audit, compliance, incident)
 * - `toAfendaSession()` bridges Neon Auth identity → AFENDA context
 */

import { createNeonAuth } from "@neondatabase/auth/next/server";
import type { Session } from "@neondatabase/auth";

// ─────────────────────────────────────────────────────────────────────────────
// Neon Auth Instance
// ─────────────────────────────────────────────────────────────────────────────

/**
 * Neon Auth server configuration.
 * Credentials read from env at startup.
 */
export const auth = createNeonAuth({
  baseUrl: process.env.NEON_AUTH_BASE_URL!,
  cookies: {
    secret: process.env.NEON_AUTH_COOKIE_SECRET!,
  },
});

/**
 * Export Neon Auth route handler for [...auth]/route.ts
 */
export const { GET, POST } = auth.handler();

// ─────────────────────────────────────────────────────────────────────────────
// Bridge to AFENDA Context
// ─────────────────────────────────────────────────────────────────────────────

/**
 * Neon Auth session shape (from Better Auth).
 * Can be queried with `SELECT * FROM neon_auth.user` + `neon_auth.session`.
 */
export type NeonAuthSession = Session | null;

/**
 * AFENDA session shape.
 * Extends Neon Auth identity with AFENDA org/role context.
 */
export interface AfendaSession {
  // From Neon Auth
  user: {
    id: string;           // UUID from neon_auth.user.id
    email: string;        // From neon_auth.user.email
    name: string | null;
    image: string | null;
  };

  // From AFENDA context
  affiliation: {
    orgId: string;        // Resolved from user → party_membership → org
    principalId: string;  // From auth_principal or party table
    roles: string[];      // List of role IDs granted to this principal
    permissions: Set<string>; // Expanded from roles
  };

  // Metadata
  expiresAt: Date;
  createdAt: Date;
}

/**
 * Convert Neon Auth session to AFENDA session.
 *
 * Prerequisites:
 * - Neon Auth user.id must be linked to AFENDA party/principal (via trigger or app logic)
 * - User's org membership must exist in party_membership table
 * - RLS policies must be active on all auth-* tables
 *
 * Stub: Future version will query AFENDA auth domain modules to populate:
 * - orgId from party_membership
 * - principalId from auth_principal or similar
 * - roles/permissions from role_assignment + permission registry
 */
export async function toAfendaSession(
  neonSession: NeonAuthSession,
): Promise<AfendaSession | null> {
  if (!neonSession?.user) return null;

  // TODO: Replace with real lookups once DB linking is in place.
  // For now, every Neon user gets demo org + admin principal.

  return {
    user: {
      id: neonSession.user.id,
      email: neonSession.user.email,
      name: neonSession.user.name ?? null,
      image: neonSession.user.image ?? null,
    },
    affiliation: {
      orgId: process.env.NODE_ENV === "development"
        ? "00000000-0000-0000-0000-000000000001" // demo org UUID
        : "", // Will fail in prod until DB linking implemented
      principalId: neonSession.user.id,
      roles: ["admin"],
      permissions: new Set(["*"]), // TODO: query actual permissions
    },
    expiresAt: new Date(neonSession.expiresAt),
    createdAt: new Date(neonSession.createdAt ?? Date.now()),
  };
}

/**
 * Get current user session from cookies/headers.
 * Wrapper around Neon Auth + AFENDA bridge.
 *
 * Usage in Server Components / Route Handlers:
 *   const session = await getSession();
 *   if (!session) return <SignInPrompt />;
 */
export async function getSession(): Promise<AfendaSession | null> {
  const neonSession = await auth.api.getSession();
  return toAfendaSession(neonSession);
}

/**
 * Verify that a request has a valid session.
 * Middleware / API route pattern.
 */
export async function requireSession(): Promise<AfendaSession> {
  const session = await getSession();
  if (!session) {
    throw new Error("Unauthorized: no session");
  }
  return session;
}

2B. Create Route Handler

File: apps/web/src/app/api/auth/[...auth]/route.ts (REPLACE existing)

/**
 * Neon Auth routes.
 * Replaces the old NextAuth [...nextauth]/route.ts.
 */

import { auth } from "@/lib/auth/server";

export const { GET, POST } = auth.handler();

Old file apps/web/src/app/api/auth/[...nextauth]/route.ts should be deleted.

2C. Enable Session Validation in Middleware

File: apps/web/middleware.ts (UPDATE)

// ... existing imports ...
import { auth } from "@/lib/auth/server";

export async function middleware(request: NextRequest) {
  // Verify Neon Auth session is valid
  // (Optional: you can add extra auth checks here)
  const session = await auth.api.getSession();

  // Let request proceed; protected routes check session in their handlers
  return NextResponse.next();
}

export const config = {
  // Apply to all routes except static
  matcher: ["/((?!_next/static|_next/image|favicon).*)"],
};

---

Phase 3: Client-Side SDK Setup

✅ PHASE COMPLETE — apps/web/src/lib/auth/client.ts (250+ lines) with createAuthClient(), useSession, signIn, signOut, organization.*, emailOtp.*, capability detection, and error-wrapped facades.

3A. Create Auth Client Module

File: apps/web/src/lib/auth/client.ts (NEW)

/**
 * Neon Auth Client SDK for React components.
 *
 * Usage in Client Components:
 *   const { user, isLoading } = useAuth();
 *   if (!isLoading && !user) return <SignInButton />;
 *   return <Dashboard user={user} />;
 */

import { createAuthClient } from "@neondatabase/neon-js/auth";
import type { BetterAuthClientPlugin } from "better-auth/client";

/**
 * Neon Auth client instance.
 * Endpoint is NEXT_PUBLIC_NEON_AUTH_URL from env.
 */
export const authClient = createAuthClient({
  baseURL: process.env.NEXT_PUBLIC_NEON_AUTH_URL ?? "/api/auth",
  // Optional: custom plugins for AFENDA domain (audit, compliance, etc.)
  plugins: [
    // Future: add AFENDA-specific auth plugins (3-factor, anomaly detection, etc.)
  ],
});

/**
 * React hook: Get current user session.
 * Triggers re-render on auth state change (login, logout, session refresh).
 *
 * Example:
 *   const { user, isLoading, error } = useAuth();
 *   if (isLoading) return <Skeleton />;
 *   if (error) return <ErrorAlert error={error} />;
 *   if (!user) return <SignInForm />;
 *   return <Dashboard user={user} />;
 */
export const useAuth = () => {
  const { data: session, isLoading, error } = authClient.useSession();
  return {
    user: session?.user ?? null,
    session,
    isLoading,
    error,
  };
};

/**
 * Sign in with email/password.
 */
export const signIn = authClient.signIn.email;

/**
 * Sign in with OAuth provider (Google, GitHub, etc.)
 * Neon Auth provides out-of-the-box Google + custom OAuth.
 */
export const signInOAuth = authClient.signIn.social;

/**
 * Sign out and clear session cookie.
 */
export const signOut = authClient.signOut;

/**
 * Sign up new user with email/password.
 */
export const signUp = authClient.signUp.email;

/**
 * Request password reset flow.
 */
export const resetPassword = authClient.forgetPassword;

/**
 * Change user profile (name, image, etc.)
 * Does NOT change email or password (use separate endpoints).
 */
export const updateProfile = authClient.updateUser;

3B. Create Auth Provider

File: apps/web/src/components/auth-provider.tsx (NEW)

"use client";

import React, { ReactNode } from "react";
import { NeonAuthUIProvider } from "@neondatabase/neon-js/auth/react/ui";
import { authClient } from "@/lib/auth/client";

/**
 * Wrap your app with this to enable Neon Auth UI components.
 * Use in root layout:
 *
 *   export default function RootLayout({ children }) {
 *     return (
 *       <html>
 *         <body>
 *           <AuthProvider>{children}</AuthProvider>
 *         </body>
 *       </html>
 *     );
 *   }
 */
export function AuthProvider({ children }: { children: ReactNode }) {
  return (
    <NeonAuthUIProvider authClient={authClient}>
      {children}
    </NeonAuthUIProvider>
  );
}

3C. Update Root Layout

File: apps/web/src/app/layout.tsx (UPDATE)

import { AuthProvider } from "@/components/auth-provider";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <AuthProvider>
          {children}
        </AuthProvider>
      </body>
    </html>
  );
}

3D. Create Sign-In Page

File: apps/web/src/app/(public)/signin/page.tsx (NEW/REPLACE)

Choose one approach:

Option A: Use Neon Auth UI Components (Simplest)

"use client";

import { AuthView } from "@neondatabase/neon-js/auth/react/ui";
import { authClient } from "@/lib/auth/client";

export default function SignInPage() {
  return (
    <div className="flex items-center justify-center min-h-screen bg-slate-50">
      <div className="w-full max-w-md">
        <AuthView
          authClient={authClient}
          pathname="sign-in"
          mode="dark"
        />
      </div>
    </div>
  );
}

Option B: Custom UI with shadcn Form (Flexibility)

"use client";

import { useState } from "react";
import { Button } from "@afenda/ui";
import { Input } from "@afenda/ui";
import { signIn } from "@/lib/auth/client";

export default function SignInPage() {
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");
  const [error, setError] = useState<string | null>(null);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setError(null);

    try {
      await signIn({
        email,
        password,
        callbackURL: "/dashboard",
      });
    } catch (err) {
      setError(err instanceof Error ? err.message : "Sign in failed");
    }
  };

  return (
    <div className="flex items-center justify-center min-h-screen">
      <form onSubmit={handleSubmit} className="w-full max-w-md space-y-4">
        <h1 className="text-2xl font-bold">Sign In to AFENDA</h1>

        {error && <div className="text-red-600">{error}</div>}

        <Input
          type="email"
          placeholder="Email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          required
        />

        <Input
          type="password"
          placeholder="Password"
          value={password}
          onChange={(e) => setPassword(e.target.value)}
          required
        />

        <Button type="submit">Sign In</Button>
      </form>
    </div>
  );
}

---

Phase 4: API Bearer Token Verification

✅ PHASE COMPLETE — apps/api/src/plugins/auth.ts uses jose.jwtVerify() + createRemoteJWKSet(). JWKS auto-discovered from NEON_AUTH_JWKS_URL or derived from NEON_AUTH_BASE_URL/.well-known/jwks.json. Email extracted from JWT payload → resolvePrincipalContext() → full RequestContext set on req.ctx.

4A. Update Auth Plugin

File: apps/api/src/plugins/auth.ts (REPLACE bearer stub)

/**
 * Fastify plugin: Authentication for Neon Auth bearer tokens.
 *
 * Expects: Authorization: Bearer <JWK-signed-JWT-from-Neon-Auth>
 *
 * Neon Auth provides a JWKS endpoint; this plugin:
 * 1. Fetches JWKS (cached)
 * 2. Verifies JWT signature
 * 3. Resolves userId → AFENDA principal context
 * 4. Sets req.ctx with org/role/permission context
 */

import type { FastifyInstance } from "fastify";
import fp from "fastify-plugin";
import jwtVerify from "@panva/hkdf"; // Or use @noble/ciphers for JWT verification
import { resolvePrincipalContext } from "@afenda/core";

const DEV_HEADER = "x-dev-user-email";

/**
 * Placeholder: Fetch Neon Auth JWKS from provisioned auth endpoint.
 * In production, implement:
 * 1. GET {NEON_AUTH_BASE_URL}/.well-known/jwks.json
 * 2. Cache with 1-hour TTL
 * 3. Use `jose` lib to verify JWT
 */
async function verifyNeonAuthToken(token: string): Promise<{ sub: string; email: string } | null> {
  // TODO: Implement JWKS fetch + JWT verification
  // Stub returns null (bearer path disabled)
  return null;
}

export const authPlugin = fp(async function authPlugin(app: FastifyInstance) {
  app.decorateRequest("ctx", undefined);

  app.addHook("onRequest", async (req) => {
    // Skip infra endpoints
    if (req.url === "/healthz" || req.url === "/readyz") return;

    const isDev = process.env.NODE_ENV === "development";
    const slug = req.orgSlug ?? "demo";

    // ── Dev-mode shortcut ────────────────────────────────────────────────
    if (isDev && req.headers[DEV_HEADER]) {
      const email = req.headers[DEV_HEADER] as string;
      const ctx = await resolvePrincipalContext(app.db, email, slug, req.correlationId);
      if (ctx) {
        req.ctx = ctx;
        if (ctx.activeContext?.orgId) {
          req.orgId = ctx.activeContext.orgId;
        }
      }
      return;
    }

    // ── Neon Auth bearer token ───────────────────────────────────────────
    const authHeader = req.headers.authorization;
    if (authHeader?.startsWith("Bearer ")) {
      const token = authHeader.slice(7);
      const payload = await verifyNeonAuthToken(token);

      if (payload?.email) {
        const ctx = await resolvePrincipalContext(
          app.db,
          payload.email,
          slug,
          req.correlationId,
        );

        if (ctx) {
          req.ctx = ctx;
          if (ctx.activeContext?.orgId) {
            req.orgId = ctx.activeContext.orgId;
          }
        }
      }
    }

    // If no session resolved, routes requiring auth will return 401
  });
});

4B. Install JWT Dependencies

# For JWT verification (use jose or @noble/ciphers, NOT @panva/hkdf)
pnpm add -W jose

# Or use @noble/ciphers if you prefer smaller bundle
pnpm add -W @noble/ciphers

4C. Implement verifyNeonAuthToken

Full implementation sketch:

import * as jose from "jose";

let cachedJwks: jose.JSONWebKeySet | null = null;
let jwksCacheTTL = 0;

async function fetchJwks(): Promise<jose.JSONWebKeySet> {
  const now = Date.now();
  if (cachedJwks && now < jwksCacheTTL) {
    return cachedJwks;
  }

  const baseURL = process.env.NEON_AUTH_BASE_URL;
  if (!baseURL) throw new Error("NEON_AUTH_BASE_URL not set");

  const res = await fetch(`${baseURL}/.well-known/jwks.json`);
  if (!res.ok) throw new Error(`JWKS fetch failed: ${res.status}`);

  cachedJwks = await res.json();
  jwksCacheTTL = now + 3600_000; // 1 hour

  return cachedJwks;
}

async function verifyNeonAuthToken(
  token: string,
): Promise<{ sub: string; email: string } | null> {
  const jwks = await fetchJwks();
  const secret = jose.importJWKSet(jwks);

  try {
    const verified = await jose.jwtVerify(token, secret);
    const payload = verified.payload as { sub?: string; email?: string };

    if (payload.sub && payload.email) {
      return { sub: payload.sub, email: payload.email };
    }
  } catch (err) {
    // Invalid or expired token
    return null;
  }

  return null;
}

---

Phase 5: Database Schema Alignment — ✅ PHASE COMPLETE

Validated 2026-03-16 — Sync trigger deployed and operational on live Neon DB.

5A. Link Neon Auth to AFENDA Domain — ✅ DONE

Deployed trigger: sync_neon_auth_user_to_afenda_identity on neon_auth.user (AFTER INSERT).

On new Neon Auth signup, the trigger automatically provisions:

1. ✅ party record (kind='person', external_key='person:{email}')
2. ✅ person record (id=party.id, email, display name) — ON CONFLICT updates
3. ✅ iam_principal record (person_id, kind='user', email) — ON CONFLICT updates
4. ✅ party_role record (org_id=demo org, party_id, role_type='employee') — ON CONFLICT updates
5. ✅ membership record (principal_id, party_role_id, status='active') — ON CONFLICT reactivates

Fail-safe: Wrapped in EXCEPTION WHEN OTHERS — trigger failure never blocks Neon Auth user creation. Warnings logged via RAISE WARNING.

Live DB state (verified):

• public.organization: 2 orgs (Demo Organization slug='demo', Acme Supplies slug='acme-supplies')
• public.iam_principal: 3 principals (pre-seeded)
• neon_auth.user: 0 rows (no signups yet — trigger fires on first signup)
• neon_auth.jwks: 1 key pair for JWT signing/verification

Note: The actual trigger uses AFENDA's domain model (party, person, iam_principal, party_role, membership) — not the outdated names (auth_principal, party_membership, role_assignment) from the original skill draft.

5B. resolvePrincipalContext — ✅ DONE

Already implemented at packages/core/src/kernel/identity/auth.ts (550+ lines):

• Accepts email + orgSlug + correlationId
• 7-step resolution: find principal → resolve org → find active memberships → select hat → fetch roles → fetch permissions → parse via RequestContextSchema
• Used by API layer (apps/api/src/plugins/auth.ts) after JWT verification
• Also provides listPrincipalContexts() for hat-switching UI

Note: The web layer (apps/web/auth.ts) uses toAuthSession() which reads from Neon Auth claims directly — it does NOT call resolvePrincipalContext(). The API layer is the one that does full DB-backed RBAC resolution.

5C: Row Level Security (RLS) Alignment — ✅ DONE (AFENDA side)

AFENDA public.* tables use current_setting('app.org_id')::uuid via withOrgContext() (ADR-0003 pattern).

neon_auth.* tables have no RLS policies — this is expected because:

• The neon_auth schema is Neon-managed (not user-editable)
• Auth operations go through the Neon Auth SDK, not direct SQL
• Org isolation for business data is enforced at the AFENDA public.* layer

---

Phase 6: Remove Dev Shim — ✅ PHASE COMPLETE

Validated 2026-03-16 — Dev shim replaced by production Neon Auth integration.

6A. Delete Temporary Auth Handler — ✅ DONE

apps/web/auth.ts is now the production session orchestrator (not a dev shim):

• toAuthSession() bridges Neon Auth session → AuthSession with AFENDA enrichment
• resolveSession() calls getNeonSession() → toAuthSession() → auto-assigns single org
• auth() overloaded: zero-arg returns session, one-arg wraps route handler
• No synthetic/hardcoded sessions remain

6B. Update Imports — ✅ DONE

All auth imports use the Neon Auth SDK wrappers:

• import { auth } from "@/auth" — production auth() backed by Neon Auth
• import { getNeonSession } from "@/lib/auth/server" — server-side session
• import { useSession, signIn, signOut } from "@/lib/auth/client" — client-side hooks

6C. Dev-Header Bypass — ⚠️ RETAINED (intentional)

apps/api/src/plugins/auth.ts still allows x-dev-user-email header bypass in development mode. This is intentional for local API testing without a full browser session. Should be removed or gated before production deployment.

---

Integration: Auth Domain Modules — ✅ COMPATIBLE

AFENDA's security/governance modules work via the pillar structure (not auth-provider-specific):

• Audit logging: kernel/governance/audit — writes audit log on every mutation via writeAuditLog()
• Identity/RBAC: kernel/identity — resolvePrincipalContext() resolves email → principal → roles → permissions
• Org isolation: withOrgContext() sets PostgreSQL GUCs (app.org_id, app.principal_id) for RLS

These modules are identity-provider-agnostic. They work with Neon Auth because:

1. The sync trigger provisions AFENDA entities on Neon Auth user creation
2. The API plugin resolves JWT email → AFENDA principal context
3. All business queries go through withOrgContext() for org isolation

---

Environment Variables Checklist

Production

# Neon Auth endpoint (from console)
NEON_AUTH_BASE_URL=https://your-endpoint.neonauth.region.aws.neon.tech/db/auth

# Cookie secret for session protection (generate with `openssl rand -base64 32`)
NEON_AUTH_COOKIE_SECRET=your-base64-encoded-32-byte-secret

# Web app client-side auth URL (same as above)
NEXT_PUBLIC_NEON_AUTH_URL=https://your-endpoint.neonauth.region.aws.neon.tech/db/auth

Development

# Dev can use localhost or neon endpoint
NEON_AUTH_BASE_URL=http://localhost:5000/db/auth        # (local dev)
NEON_AUTH_BASE_URL=https://staging-endpoint.neonauth... # (shared dev)

NEON_AUTH_COOKIE_SECRET=dev-secret-not-used-in-tests

NEXT_PUBLIC_NEON_AUTH_URL=http://localhost:3000/api/auth # (dev)

CI/CD

# GitHub Actions or similar should inject from secrets
NEON_AUTH_BASE_URL=${{ secrets.NEON_AUTH_BASE_URL }}
NEON_AUTH_COOKIE_SECRET=${{ secrets.NEON_AUTH_COOKIE_SECRET }}
NEXT_PUBLIC_NEON_AUTH_URL=${{ env.NEXT_PUBLIC_NEON_AUTH_URL }}

---

Testing Checklist

Unit Tests

• apps/web/src/lib/__vitest_test__/auth.server.facade.test.ts — Server SDK facade tests
• apps/web/src/lib/__vitest_test__/auth.client.facade.test.ts — Client SDK facade tests
• apps/api/src/__vitest_test__/auth-flows.test.ts — API auth flows (bearer verification, principal resolution)
• packages/contracts/src/kernel/identity/__vitest_test__/auth.commands.test.ts — Auth command schemas
• apps/web/src/app/api/internal/admin/_lib/__vitest_test__/authorization.test.ts — Admin authorization

Integration Tests

• Sync trigger verified: sync_neon_auth_user_to_afenda_identity creates party/person/principal/role/membership
• Bearer token path: JWT → jose.jwtVerify() → email → resolvePrincipalContext() → req.ctx
• Sign out → Session cleared → API returns 401 (needs live E2E)
• Multi-org: User in Org A cannot access Org B data (needs live E2E with 2+ users)

E2E Tests (Playwright) — Not Yet Implemented

• Sign up flow: email/password signup → redirect to dashboard
• Sign in flow: email/password login → session cookie set
• OAuth: Google/GitHub sign in → neon_auth.user created
• Protected route: /app without session → redirect to /auth/sign-in
• Session expiry: token expires → automatic logout + redirect

Branching Test

• Create Neon preview branch → auth state branches with data
• Sign up in preview → user exists only in preview branch

---

Rollback Plan — ℹ️ NOT NEEDED (Migration Complete)

Neon Auth is the production identity provider. NextAuth has been fully removed. The dev shim in apps/web/auth.ts has been replaced with the production toAuthSession() orchestrator.

If Neon Auth service becomes unavailable:

• API: Bearer token verification fails → 401 responses (graceful)
• Web: getNeonSession() returns null → redirect to sign-in page (graceful)
• Sync trigger: No new Neon Auth users → no trigger fires (no-op)

No code rollback is needed. The system degrades gracefully when the Neon Auth endpoint is unreachable.

---

Neon Auth Limitations (As of March 2026)

• ⚠️ AWS regions only (no Azure yet)
• ⚠️ No IP Allow or Private Networking in same project
• ⚠️ Better Auth 1.4.18 only (not latest)
• ⚠️ Roadmap items not yet supported:
  • Custom OAuth flows
  • SAML/OIDC enterprise integrations
  • Advanced 2FA plugins
  • Session analytics dashboards

For unsupported features, self-host Better Auth instead.

---

Related Skills

• neon-postgres – Neon fundamentals, branching, connection pooling
• better-auth-best-practices – Better Auth API design, security
• nextauth-authentication – Migration path from NextAuth v5
• fastify-best-practices – Bearer token patterns in Fastify

---

References

• Neon Auth Overview
• Neon Auth Next.js Quick Start
• Better Auth Documentation
• AFENDA Architecture (PROJECT.md)
• AFENDA Auth Domain Module Structure

---

Last updated: March 16, 2026 (validated against live codebase + Neon DB)