Clerk Authentication & Proxy Skill

Implement Clerk authentication in Next.js 16 using the proxy pattern (not middleware!), manage session claims, and handle user metadata.

Reference Files:

• proxy-patterns.md - Next.js 16 proxy configuration
• session-claims.md - Custom session claims and metadata
• onboarding-gate.md - Onboarding flow patterns
• examples.md - Complete code examples
• testing.md - Testing authenticated flows

Critical: Next.js 16 Uses Proxy, NOT Middleware

IMPORTANT: Next.js 16 introduced the proxy pattern which replaces the traditional middleware.ts for Clerk.

Next.js Version	File Name	Runtime
15 and earlier	middleware.ts	Edge Runtime
16+	proxy.ts	Node.js Runtime

The proxy pattern provides:

• Full Node.js runtime (not Edge limitations)
• Better async/await support
• Access to all Node.js APIs
• Improved performance

Quick Start

1. Authentication Check in Server Actions

"use server";

import { auth } from "@clerk/nextjs/server";
import type { ActionResponse } from "~/lib/action-types";

export async function myAction(data: InputType): ActionResponse<OutputType> {
  // 1. Always check authentication first
  const { userId } = await auth();
  if (!userId) {
    return { success: false, error: "Authentication required" };
  }

  // 2. Your business logic here
  // ...
}

2. Authentication Check in Page Loaders

import { auth } from "@clerk/nextjs/server";
import { redirect, unauthorized } from "next/navigation";

async function loadData() {
  const { userId, isAuthenticated, sessionClaims } = await auth();

  if (!isAuthenticated) {
    return unauthorized();
  }

  // Check custom session claims
  if (sessionClaims?.metadata.onboardingComplete !== true) {
    redirect("/onboarding");
  }

  // Load user data...
}

3. Updating User Metadata

import { clerkClient } from "@clerk/nextjs/server";

const client = await clerkClient();
await client.users.updateUser(userId, {
  publicMetadata: {
    onboardingComplete: true,
    role: "user",
  },
});

Key Concepts

Authentication Object

The auth() function returns:

interface AuthObject {
  userId: string | null; // Clerk user ID
  isAuthenticated: boolean; // Is user logged in
  sessionClaims: CustomJwtSessionClaims | null; // Custom claims
  redirectToSignIn: (opts?) => Response; // Redirect helper
}

Session Claims Type Definition

Define custom claims in types/clerk.d.ts:

export {};

declare global {
  interface CustomJwtSessionClaims {
    metadata: {
      onboardingComplete?: boolean;
      role?: "user" | "admin";
    };
  }
}

Public vs Private Metadata

Type	Visibility	Use Case
publicMetadata	Included in session token, readable on client	Onboarding status, roles, preferences
privateMetadata	Server-only, never sent to client	Internal flags, sensitive data
unsafeMetadata	User-editable via Clerk components	Profile preferences, settings

File Locations

Purpose	File
Proxy configuration	proxy.ts (root)
Session claims types	types/clerk.d.ts
Auth helpers	features/auth/server/db/user.ts
Providers setup	components/providers.tsx

Common Patterns

Protected Server Action

"use server";

import { auth } from "@clerk/nextjs/server";

export async function protectedAction(): ActionResponse {
  const { userId, isAuthenticated } = await auth();

  if (!isAuthenticated || !userId) {
    return { success: false, error: "Unauthorized" };
  }

  // Action logic...
}

Protected Page with Redirect

import { auth } from "@clerk/nextjs/server";
import { redirect } from "next/navigation";

export default async function ProtectedPage() {
  const { userId } = await auth();

  if (!userId) {
    redirect("/sign-in");
  }

  // Page content...
}

Onboarding Gate Pattern

See onboarding-gate.md for complete implementation.

Security Checklist

When implementing authentication:

1. Always verify userId - Never trust client-provided user IDs
2. Check authorization - Verify user owns the resource they're accessing
3. Use server-only - Mark auth modules with server-only package
4. Log auth events - Log authentication failures for security monitoring
5. Handle edge cases - Expired sessions, revoked tokens

Running and Testing

# Type check
npm run type-check

# Run auth-related tests
npm run test -- features/auth

# E2E tests with authentication
npm run test:e2e

Related Skills

• server-actions - For implementing server actions with auth checks
• firebase-firestore - For database operations after authentication