clerk-security-basics

name	clerk-security-basics
description	Implement security best practices with Clerk authentication. Use when securing your application, reviewing auth implementation, or hardening Clerk configuration. Trigger with phrases like "clerk security", "secure clerk", "clerk best practices", "clerk hardening".
allowed-tools	Read, Write, Edit, Grep
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>

Clerk Security Basics

Overview

Implement security best practices for Clerk authentication in your application.

Prerequisites

• Clerk SDK installed and configured
• Understanding of authentication security concepts
• Production deployment planned or active

Instructions

Step 1: Secure Environment Variables

# .env.local (development)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...

# .env.production (production - use secrets manager)
# NEVER commit production keys to git
# Use Vercel/Railway/AWS Secrets Manager

# .gitignore
.env.local
.env.production
.env*.local

// lib/env.ts - Validate environment at startup
const requiredEnvVars = [
  'NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY',
  'CLERK_SECRET_KEY'
]

export function validateEnv() {
  for (const envVar of requiredEnvVars) {
    if (!process.env[envVar]) {
      throw new Error(`Missing required environment variable: ${envVar}`)
    }
  }

  // Validate key format
  const pk = process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY!
  if (!pk.startsWith('pk_test_') && !pk.startsWith('pk_live_')) {
    throw new Error('Invalid publishable key format')
  }
}

Step 2: Secure Middleware Configuration

// middleware.ts
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'
import { NextResponse } from 'next/server'

const isPublicRoute = createRouteMatcher([
  '/',
  '/sign-in(.*)',
  '/sign-up(.*)',
  '/api/webhooks(.*)'
])

const isAdminRoute = createRouteMatcher(['/admin(.*)'])
const isSensitiveRoute = createRouteMatcher(['/api/admin(.*)', '/api/billing(.*)'])

export default clerkMiddleware(async (auth, request) => {
  const { userId, orgRole } = await auth()

  // Security headers
  const response = NextResponse.next()
  response.headers.set('X-Frame-Options', 'DENY')
  response.headers.set('X-Content-Type-Options', 'nosniff')
  response.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin')

  // Protect routes
  if (!isPublicRoute(request)) {
    if (!userId) {
       .( (, request.))
    }
  }

  
   ((request) && orgRole !== ) {
     .( (, request.))
  }

  
   ((request)) {
    .(, {
      : request..,
      userId,
      :  ().()
    })
  }

   response
})

Step 3: Secure API Routes

// app/api/protected/route.ts
import { auth } from '@clerk/nextjs/server'
import { headers } from 'next/headers'

export async function POST(request: Request) {
  // 1. Verify authentication
  const { userId, sessionId } = await auth()
  if (!userId) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 })
  }

  // 2. Validate request origin (CSRF protection)
  const headersList = await headers()
  const origin = headersList.get('origin')
  const allowedOrigins = [
    process.env.NEXT_PUBLIC_APP_URL,
    'https://yourdomain.com'
  ]

  if (origin && !allowedOrigins.includes(origin)) {
    return Response.json({ error: 'Invalid origin' }, { status: 403 })
  }

  // 3. Validate content type
  const contentType = headersList.get()
   (!contentType?.()) {
     .({ :  }, { :  })
  }

  
   body
   {
    body =  request.()
  }  {
     .({ :  }, { :  })
  }

  
   .({ :  })
}

Step 4: Secure Webhook Handling

// app/api/webhooks/clerk/route.ts
import { Webhook } from 'svix'
import { headers } from 'next/headers'
import { WebhookEvent } from '@clerk/nextjs/server'

export async function POST(req: Request) {
  const WEBHOOK_SECRET = process.env.CLERK_WEBHOOK_SECRET

  if (!WEBHOOK_SECRET) {
    console.error('CLERK_WEBHOOK_SECRET not configured')
    return Response.json({ error: 'Configuration error' }, { status: 500 })
  }

  // Get headers
  const headerPayload = await headers()
  const svix_id = headerPayload.get('svix-id')
  const svix_timestamp = headerPayload.get('svix-timestamp')
  const svix_signature = headerPayload.get('svix-signature')

  // Validate required headers
  if (!svix_id || !svix_timestamp || !svix_signature) {
     .({ :  }, { :  })
  }

  
   body =  req.()
   wh =  ()

   : 

   {
    evt = wh.(body, {
      : svix_id,
      : svix_timestamp,
      : svix_signature
    })  
  }  (err) {
    .(, err)
     .({ :  }, { :  })
  }

  
   eventType = evt.

  
   processed =  (svix_id)
   (processed) {
     .({ :  })
  }

  
   (evt)

  
   (svix_id)

   .({ :  })
}

Step 5: Session Security

// lib/session-security.ts
import { auth } from '@clerk/nextjs/server'

export async function validateSession() {
  const { userId, sessionClaims } = await auth()

  if (!userId) {
    throw new Error('No session')
  }

  // Check session age
  const issuedAt = sessionClaims?.iat
  const maxAge = 60 * 60 // 1 hour in seconds

  if (issuedAt && Date.now() / 1000 - issuedAt > maxAge) {
    throw new Error('Session too old, please re-authenticate')
  }

  return { userId, sessionClaims }
}

// Force re-authentication for sensitive operations
export async function requireFreshAuth() {
  const { userId, sessionClaims } = await auth()

  if (!userId) {
    throw new Error('Not authenticated')
  }

  const issuedAt = sessionClaims?.iat
  const freshThreshold =  *  

   (issuedAt && .() /  - issuedAt > freshThreshold) {
      ()
  }

   { userId }
}

Output

• Secure environment configuration
• Hardened middleware
• Protected API routes
• Verified webhook handling

Security Checklist

• Production keys stored in secrets manager
• Environment variables validated at startup
• Middleware protects all sensitive routes
• API routes validate authentication
• Webhooks verified with svix
• Security headers configured
• HTTPS enforced in production
• Session timeouts configured

Resources

• Clerk Security
• Webhook Security
• OWASP Guidelines

Next Steps

Proceed to clerk-prod-checklist for production readiness.