auth-flow Skill | Bootspring Docs

Implement secure authentication patterns including OAuth, session management, and protected routes.

Overview#

The auth-flow skill generates production-ready authentication code following security best practices. It supports multiple authentication providers and patterns.

Usage#

Use the auth-flow skill to implement OAuth authentication with Google and GitHub.

Parameters#

Parameter	Type	Required	Description
`provider`	string	Yes	Auth provider: clerk, nextauth, custom
`strategies`	array	No	Login strategies: oauth, credentials, magic-link
`providers`	array	No	OAuth providers: google, github, apple
`sessionType`	string	No	Session strategy: jwt, database

Generated Output#

Server-Side Auth Check (Clerk)#

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

export async function requireAuth() {
  const { userId } = await auth()

  if (!userId) {
    throw new Error('UNAUTHORIZED')
  }

  return userId
}

// Usage in Server Action
export async function myAction() {
  const userId = await requireAuth()
  // Continue with authenticated user
}

Protected Layout#

// app/(protected)/layout.tsx
import { auth } from '@clerk/nextjs/server'
import { redirect } from 'next/navigation'

export default async function ProtectedLayout({
  children
}: {
  children: React.ReactNode
}) {
  const { userId } = await auth()

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

  return <>{children}</>
}

Get Current User with Database Sync#

// lib/auth.ts
import { currentUser } from '@clerk/nextjs/server'
import { prisma } from '@/lib/db'

export async function getCurrentUser() {
  const user = await currentUser()
  if (!user) return null

  // Get or create database user
  const dbUser = await prisma.user.upsert({
    where: { clerkId: user.id },
    update: {
      email: user.emailAddresses[0]?.emailAddress,
      name: `${user.firstName} ${user.lastName}`.trim()
    },
    create: {
      clerkId: user.id,
      email: user.emailAddresses[0]?.emailAddress ?? '',
      name: `${user.firstName} ${user.lastName}`.trim()
    }
  })

  return dbUser
}

NextAuth.js Setup#

// auth.ts
import NextAuth from 'next-auth'
import GitHub from 'next-auth/providers/github'
import Google from 'next-auth/providers/google'
import { PrismaAdapter } from '@auth/prisma-adapter'
import { prisma } from '@/lib/db'

export const { handlers, auth, signIn, signOut } = NextAuth({
  adapter: PrismaAdapter(prisma),
  session: { strategy: 'jwt' },
  providers: [
    GitHub({
      clientId: process.env.GITHUB_ID!,
      clientSecret: process.env.GITHUB_SECRET!
    }),
    Google({
      clientId: process.env.GOOGLE_ID!,
      clientSecret: process.env.GOOGLE_SECRET!
    })
  ],
  callbacks: {
    async jwt({ token, user }) {
      if (user) {
        token.id = user.id
      }
      return token
    },
    async session({ session, token }) {
      if (session.user) {
        session.user.id = token.id as string
      }
      return session
    }
  },
  pages: {
    signIn: '/login',
    error: '/login'
  }
})

Custom JWT Session Management#

// lib/session.ts
import { SignJWT, jwtVerify } from 'jose'
import { cookies } from 'next/headers'

const secret = new TextEncoder().encode(process.env.JWT_SECRET)
const COOKIE_NAME = 'session'

export async function createSession(userId: string) {
  const token = await new SignJWT({ userId })
    .setProtectedHeader({ alg: 'HS256' })
    .setIssuedAt()
    .setExpirationTime('7d')
    .sign(secret)

  cookies().set(COOKIE_NAME, token, {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'lax',
    maxAge: 60 * 60 * 24 * 7, // 7 days
    path: '/'
  })

  return token
}

export async function getSession() {
  const token = cookies().get(COOKIE_NAME)?.value

  if (!token) return null

  try {
    const { payload } = await jwtVerify(token, secret)
    return payload as { userId: string }
  } catch {
    return null
  }
}

export async function destroySession() {
  cookies().delete(COOKIE_NAME)
}

Middleware Configuration#

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

const isProtectedRoute = createRouteMatcher([
  '/dashboard(.*)',
  '/settings(.*)',
  '/api/user(.*)'
])

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

export default clerkMiddleware(async (auth, req) => {
  if (isProtectedRoute(req)) {
    await auth.protect()
  }
})

export const config = {
  matcher: ['/((?!.*\\..*|_next).*)', '/', '/(api|trpc)(.*)']
}

// components/auth/SocialButtons.tsx
'use client'

import { signIn } from 'next-auth/react'
import { Github } from 'lucide-react'

export function SocialButtons() {
  return (
    <div className="space-y-3">
      <button
        onClick={() => signIn('google', { callbackUrl: '/dashboard' })}
        className="flex w-full items-center justify-center gap-2 rounded-lg border py-2 hover:bg-gray-50"
      >
        <GoogleIcon className="h-5 w-5" />
        Continue with Google
      </button>

      <button
        onClick={() => signIn('github', { callbackUrl: '/dashboard' })}
        className="flex w-full items-center justify-center gap-2 rounded-lg border py-2 hover:bg-gray-50"
      >
        <Github className="h-5 w-5" />
        Continue with GitHub
      </button>
    </div>
  )
}

Client-Side Auth Hook#

// hooks/use-user.ts
'use client'
import { useUser } from '@clerk/nextjs'

export function useCurrentUser() {
  const { user, isLoaded, isSignedIn } = useUser()

  return {
    user: isSignedIn ? user : null,
    isLoading: !isLoaded,
    isAuthenticated: isSignedIn
  }
}

Features Included#

Server-side authentication checks
Protected route layouts
JWT session management
OAuth provider integration
Middleware protection
Database user sync
Client-side hooks

Customization Options#

Use the auth-flow skill with:
- provider: "nextauth"
- strategies: ["oauth", "credentials"]
- providers: ["google", "github"]
- sessionType: "jwt"

Best Practices#

Security Considerations#

Always use httpOnly cookies for session tokens
Set secure: true in production
Use sameSite: 'lax' or 'strict' for CSRF protection
Never expose JWT secrets to client-side code
Implement session refresh for long-lived sessions

Authentication Flow#

User initiates login
Validate credentials or OAuth callback
Create session token
Store in secure cookie
Verify token on protected routes
Refresh token before expiry

Error Handling#

// app/auth/error/page.tsx
const errorMessages: Record<string, string> = {
  OAuthSignin: 'Error starting OAuth flow',
  OAuthCallback: 'Error in OAuth callback',
  OAuthAccountNotLinked: 'Email already registered with different provider',
  CredentialsSignin: 'Invalid credentials',
  SessionRequired: 'Please sign in to continue',
  default: 'An error occurred'
}

api-endpoint - Protected API routes
validation - Input validation for login forms
error-handling - Auth error management