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]>
compatible-with	claude-code, codex, openclaw
tags	["saas","clerk","security","authentication"]

Clerk Security Basics

Overview

Implement security best practices for Clerk authentication: environment variable protection, middleware hardening, API route defense, webhook verification, and session security.

Prerequisites

• Clerk SDK installed and configured
• Understanding of OWASP authentication best practices
• Production deployment planned or active

Instructions

Step 1: Secure Environment Variables

# .env.local — never commit this file
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_...  # Safe to expose (public)
CLERK_SECRET_KEY=sk_live_...                    # NEVER expose client-side
CLERK_WEBHOOK_SECRET=whsec_...                  # Server-only

# .gitignore — ensure secrets stay out of git
.env.local
.env.*.local
.env.production

Validate at startup that secret keys are not leaked:

// lib/security-check.ts
export function assertServerOnly() {
  if (typeof window !== 'undefined') {
    throw new Error('This module must only be used server-side')
  }
  if (!process.env.CLERK_SECRET_KEY) {
    throw new Error('CLERK_SECRET_KEY is not configured')
  }
}

Step 2: Hardened Middleware Configuration

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

 isPublicRoute = ([
  ,
  ,
  ,
  ,
])

  ( (auth, req) => {
  
   (!(req)) {
     auth.()
  }

  
   response = .()
  response..(, )
  response..(, )
  response..(, )
  response..(
    ,
    
  )
   response
})