epic-auth（史诗认证）

Epic Stack: Authentication

When to use this skill

Use this skill when you need to:

• Implement user authentication
• Work with sessions and cookies
• Configure OAuth providers (GitHub, Google, etc.)
• Implement 2FA (Two-Factor Authentication)
• Implement WebAuthn/Passkeys
• Handle login, signup, logout flows
• Manage email verification
• Implement password reset

Patterns and conventions

Authentication Philosophy

Following Epic Web principles:

Least privilege - Users should only have access to what they need, when they need it. Sessions should have minimal permissions and expire appropriately. Don't grant more access than necessary.

Design to fail fast and early - Validate authentication and authorization as early as possible. Check session validity immediately, verify permissions before processing requests, and return clear errors quickly.

Example - Least privilege in sessions:

// ✅ Good - Minimal session data, explicit permissions
const session = await prisma.session.create({
	data: {
		expirationDate: getSessionExpirationDate(),
		userId, // Only store user ID, not full user data
	},
})

// Session only grants access to this specific user
// Permissions checked separately when needed

// ❌ Avoid - Storing too much in session
const session = await prisma.session.create({
	data: {
		expirationDate: getSessionExpirationDate(),
		userId,
		userRole: 'admin', // Don't store roles in session
		permissions: ['all'], // Don't store permissions in session
	},
})
// Roles and permissions should be checked from database, not session

Example - Fail fast authentication:

// ✅ Good - Validate authentication early
export async function loader({ request }: Route.LoaderArgs) {
	// Check authentication immediately - fail fast
	const userId = await requireUserId(request)

	// Check permissions early - fail fast
	await requireUserWithPermission(request, 'read:note:own')

	// Only proceed if authenticated and authorized
	const notes = await prisma.note.findMany({
		where: { ownerId: userId },
	})

	return { notes }
}

// ❌ Avoid - Delayed authentication check
export async function loader({ request }: Route.LoaderArgs) {
	// Process request first...
	const notes = await prisma.note.findMany()

	// Check authentication at the end - too late!
	const userId = await getUserId(request)
	if (!userId) {
		// Already processed request
		throw redirect('/login')
	}
}

Cookie-based Sessions

Epic Stack uses cookie-based sessions for authentication. Sessions are stored in the database and identified by signed cookies.

Session configuration:

// app/utils/session.server.ts
import { createCookieSessionStorage } from 'react-router'

export const authSessionStorage = createCookieSessionStorage({
	cookie: {
		name: 'en_session',
		sameSite: 'lax', // CSRF protection advised if changing to 'none'
		path: '/',
		httpOnly: true,
		secrets: process.env.SESSION_SECRET.split(','),
		secure: process.env.NODE_ENV === 'production',
	},
})

Get current user

Server-side:

import { getUserId, requireUserId } from '#app/utils/auth.server.ts'

// Get userId or null if not authenticated
const userId = await getUserId(request)

// Require authenticated user (redirects to /login if not)
const userId = await requireUserId(request)
const userId = await requireUserId(request, { redirectTo: '/custom-login' })

// Require that user is NOT authenticated
import { requireAnonymous } from '#app/utils/auth.server.ts'
await requireAnonymous(request) // Redirects to / if authenticated

Client-side:

import { useOptionalUser, useUser } from '#app/utils/user.ts'

// Get user or undefined if not authenticated
const user = useOptionalUser()

// Get authenticated user (throws error if not)
const user = useUser()

Login with Email/Password

Validation schema:

const LoginSchema = z.object({
	username: UsernameSchema,
	password: z.string().min(1, 'Password is required'),
	redirectTo: z.string().optional(),
	remember: z.boolean().optional(),
})

Login action (fail fast):

import { login } from '#app/utils/auth.server.ts'
import { handleNewSession } from './login.server.ts'

export async function action({ request }: Route.ActionArgs) {
	const formData = await request.formData()

	// Validate input early - fail fast
	const submission = await parseWithZod(formData, {
		schema: LoginSchema,
	})

	if (submission.status !== 'success') {
		return data({ result: submission.reply() }, { status: 400 })
	}

	const { username, password, redirectTo, remember } = submission.value

	// Authenticate early - fail fast if invalid
	const session = await login({ username, password })

	if (!session) {
		// Return error immediately - don't process further
		return data(
			{
				result: submission.reply({
					formErrors: ['Invalid username or password'],
				}),
			},
			{ status: 400 },
		)
	}

	// Only create session if authentication succeeded
	return handleNewSession({
		request,
		session,
		redirectTo,
		remember: remember ?? false,
	})
}

Signup with Email/Password

Signup action:

import { signup } from '#app/utils/auth.server.ts'

export async function action({ request }: Route.ActionArgs) {
	const formData = await request.formData()

	// Validate form...

	const session = await signup({
		email,
		username,
		password,
		name,
	})

	// Handle session and redirect...
}

OAuth Providers (GitHub, Google, etc.)

Epic Stack uses remix-auth for OAuth providers.

Configure provider (GitHub example):

// app/utils/providers/github.server.ts
import { GitHubStrategy } from 'remix-auth-github'

export class GitHubProvider implements AuthProvider {
	getAuthStrategy() {
		return new GitHubStrategy(
			{
				clientID: process.env.GITHUB_CLIENT_ID,
				clientSecret: process.env.GITHUB_CLIENT_SECRET,
				callbackURL: '/auth/github/callback',
			},
			async ({ profile }) => {
				// Return user profile
				return {
					id: profile.id,
					email: profile.emails[0].value,
					username: profile.displayName,
					name: profile.displayName,
				}
			},
		)
	}
}

Callback handler:

// app/routes/_auth/auth.$provider/callback.ts
export async function loader({ request, params }: Route.LoaderArgs) {
	const providerName = ProviderNameSchema.parse(params.provider)
	const authResult = await authenticator.authenticate(providerName, request)

	if (!authResult.success) {
		throw redirectWithToast('/login', {
			title: 'Auth Failed',
			description: `Error authenticating with ${providerName}`,
			type: 'error',
		})
	}

	const { data: profile } = authResult

	// Check if connection exists
	const existingConnection = await prisma.connection.findUnique({
		where: {
			providerName_providerId: {
				providerName,
				providerId: String(profile.id),
			},
		},
	})

	// If exists, create session
	if (existingConnection) {
		return makeSession({ request, userId: existingConnection.userId })
	}

	// If email exists, link account
	const user = await prisma.user.findUnique({
		where: { email: profile.email.toLowerCase() },
	})
	if (user) {
		await prisma.connection.create({
			data: {
				providerName,
				providerId: String(profile.id),
				userId: user.id,
			},
		})
		return makeSession({ request, userId: user.id })
	}

	// New user, go to onboarding
	// ...
}

WebAuthn/Passkeys

Epic Stack supports authentication with passkeys using WebAuthn.

Loader to generate options:

// app/routes/_auth/webauthn/authentication.ts
import { generateAuthenticationOptions } from '@simplewebauthn/server'

export async function loader({ request }: Route.LoaderArgs) {
	const config = getWebAuthnConfig(request)
	const options = await generateAuthenticationOptions({
		rpID: config.rpID,
		userVerification: 'preferred',
	})

	const cookieHeader = await passkeyCookie.serialize({
		challenge: options.challenge,
	})

	return Response.json(
		{ options },
		{
			headers: { 'Set-Cookie': cookieHeader },
		},
	)
}

Action to verify authentication:

import { verifyAuthenticationResponse } from '@simplewebauthn/server'

export async function action({ request }: Route.ActionArgs) {
	const cookie = await passkeyCookie.parse(request.headers.get('Cookie'))

	if (!cookie?.challenge) {
		throw new Error('Authentication challenge not found')
	}

	const { authResponse } = await request.json()
	const passkey = await prisma.passkey.findUnique({
		where: { id: authResponse.id },
		include: { user: true },
	})

	const verification = await verifyAuthenticationResponse({
		response: authResponse,
		expectedChallenge: cookie.challenge,
		expectedOrigin: config.origin,
		expectedRPID: config.rpID,
		credential: {
			id: authResponse.id,
			publicKey: passkey.publicKey,
			counter: Number(passkey.counter),
		},
	})

	if (!verification.verified) {
		throw new Error('Authentication verification failed')
	}

	// Actualizar counter
	await prisma.passkey.update({
		where: { id: passkey.id },
		data: { counter: BigInt(verification.authenticationInfo.newCounter) },
	})

	// Create sesión
	const session = await prisma.session.create({
		data: {
			expirationDate: getSessionExpirationDate(),
			userId: passkey.userId,
		},
	})

	return handleNewSession({ request, session, remember: true })
}

Two-Factor Authentication (2FA) with TOTP

Epic Stack uses TOTP (Time-based One-Time Password) para 2FA.

Check if user has 2FA:

const verification = await prisma.verification.findUnique({
	where: {
		target_type: {
			target: session.userId,
			type: twoFAVerificationType,
		},
	},
})
const userHasTwoFactor = Boolean(verification)

Handle session with 2FA:

export async function handleNewSession({
	request,
	session,
	redirectTo,
	remember,
}: {
	request: Request
	session: { userId: string; id: string; expirationDate: Date }
	redirectTo?: string
	remember: boolean
}) {
	const verification = await prisma.verification.findUnique({
		where: {
			target_type: {
				target: session.userId,
				type: twoFAVerificationType,
			},
		},
	})
	const userHasTwoFactor = Boolean(verification)

	if (userHasTwoFactor) {
		// Save unverified session
		const verifySession = await verifySessionStorage.getSession()
		verifySession.set(unverifiedSessionIdKey, session.id)
		verifySession.set(rememberKey, remember)

		// Redirect to 2FA verification
		const redirectUrl = getRedirectToUrl({
			request,
			type: twoFAVerificationType,
			target: session.userId,
			redirectTo,
		})
		return redirect(redirectUrl.toString(), {
			headers: {
				'set-cookie': await verifySessionStorage.commitSession(verifySession),
			},
		})
	} else {
		// User without 2FA, create session directly
		const authSession = await authSessionStorage.getSession(
			request.headers.get('cookie'),
		)
		authSession.set(sessionKey, session.id)
		return redirect(safeRedirect(redirectTo), {
			headers: {
				'set-cookie': await authSessionStorage.commitSession(authSession, {
					expires: remember ? session.expirationDate : undefined,
				}),
			},
		})
	}
}

Verify 2FA code:

import { prepareTOTP, verifyTOTP } from '@epic-web/totp'

export async function action({ request }: Route.ActionArgs) {
	const formData = await request.formData()
	const submission = await parseWithZod(formData, {
		schema: VerifySchema,
	})

	if (submission.status !== 'success') {
		return data({ result: submission.reply() }, { status: 400 })
	}

	const { code } = submission.value
	const verifySession = await verifySessionStorage.getSession(
		request.headers.get('cookie'),
	)
	const target = verifySession.get(targetKey)
	const type = verifySession.get(typeKey)

	if (!target || !type) {
		throw redirect('/login')
	}

	const verification = await prisma.verification.findUnique({
		where: { target_type: { target, type } },
		select: {
			secret: true,
			algorithm: true,
			period: true,
			digits: true,
		},
	})

	if (!verification) {
		throw redirect('/login')
	}

	const isValid = verifyTOTP({
		otp: code,
		secret: verification.secret,
		algorithm: verification.algorithm as any,
		period: verification.period,
		digits: verification.digits,
	})

	if (!isValid) {
		return data(
			{
				result: submission.reply({
					formErrors: ['Invalid code'],
				}),
			},
			{ status: 400 },
		)
	}

	// Verify session and complete login
	return handleVerification({ request, submission })
}

Email Verification

Epic Stack uses TOTP codes sent via email for verification.

Prepare verification:

import { prepareVerification } from './verify.server.ts'

const { verifyUrl, redirectTo, otp } = await prepareVerification({
	period: 10 * 60, // 10 minutes
	request,
	type: 'onboarding',
	target: email,
})

// Enviar email con código y URL
await sendEmail({
	to: email,
	subject: 'Welcome!',
	react: <VerificationEmail verifyUrl={verifyUrl.toString()} otp={otp} />,
})

return redirect(redirectTo.toString())

Verify code:

export async function loader({ request }: Route.LoaderArgs) {
	const verifySession = await verifySessionStorage.getSession(
		request.headers.get('cookie'),
	)
	const target = verifySession.get(targetKey)
	const type = verifySession.get(typeKey)

	if (!target || !type) {
		throw redirect('/signup')
	}

	return { target, type }
}

export async function action({ request }: Route.ActionArgs) {
	// Verify code (similar to 2FA)
	// ...
}

Password Reset

Request reset:

export async function action({ request }: Route.ActionArgs) {
	const formData = await request.formData()
	const submission = await parseWithZod(formData, {
		schema: ForgotPasswordSchema,
	})

	if (submission.status !== 'success') {
		return data({ result: submission.reply() }, { status: 400 })
	}

	const { email } = submission.value

	// Prepare verification
	const { verifyUrl, redirectTo, otp } = await prepareVerification({
		period: 10 * 60,
		request,
		type: 'reset-password',
		target: email,
	})

	// Enviar email con código y URL
	await sendEmail({
		to: email,
		subject: 'Reset your password',
		react: <ResetPasswordEmail verifyUrl={verifyUrl.toString()} otp={otp} />,
	})

	return redirect(redirectTo.toString())
}

Reset password:

export async function action({ request }: Route.ActionArgs) {
	// Verify code first (similar to email verification)
	// Then reset password

	const formData = await request.formData()
	const submission = await parseWithZod(formData, {
		schema: ResetPasswordSchema,
	})

	// Verify that code is valid
	// ...

	const { password } = submission.value

	await resetUserPassword({
		username,
		password,
	})

	// Destroy verification session and redirect to login
	// ...
}

Logout

import { logout } from '#app/utils/auth.server.ts'

export async function action({ request }: Route.ActionArgs) {
	return logout({ request, redirectTo: '/' })
}

Session Management

Create session:

const session = await prisma.session.create({
	data: {
		expirationDate: getSessionExpirationDate(),
		userId,
	},
	select: { id: true, expirationDate: true },
})

Session expiration:

export const SESSION_EXPIRATION_TIME = 1000 * 60 * 60 * 24 * 30 // 30 days

export const getSessionExpirationDate = () =>
	new Date(Date.now() + SESSION_EXPIRATION_TIME)

Destroy session:

await prisma.session.deleteMany({ where: { id: sessionId } })

Destroy all user sessions:

await prisma.session.deleteMany({ where: { userId } })

Common examples

Example 1: Complete login

// app/routes/_auth/login.tsx
export async function action({ request }: Route.ActionArgs) {
	const formData = await request.formData()
	await checkHoneypot(formData)

	const submission = await parseWithZod(formData, {
		schema: LoginSchema,
	})

	if (submission.status !== 'success') {
		return data({ result: submission.reply() }, { status: 400 })
	}

	const { username, password, redirectTo, remember } = submission.value

	const session = await login({ username, password })

	if (!session) {
		return data(
			{
				result: submission.reply({
					formErrors: ['Invalid username or password'],
				}),
			},
			{ status: 400 },
		)
	}

	return handleNewSession({
		request,
		session,
		redirectTo,
		remember: remember ?? false,
	})
}

Example 2: Protect route

// app/routes/protected.tsx
export async function loader({ request }: Route.LoaderArgs) {
	const userId = await requireUserId(request)

	const data = await prisma.something.findMany({
		where: { userId },
	})

	return { data }
}

export default function ProtectedRoute({ loaderData }: Route.ComponentProps) {
	return <div>{/* Datos protegidos */}</div>
}

Example 3: Route only for unauthenticated users

// app/routes/_auth/signup.tsx
export async function loader({ request }: Route.LoaderArgs) {
	await requireAnonymous(request)
	return null
}

Common mistakes to avoid

• ❌ Delayed authentication checks: Validate authentication and authorization as early as possible - fail fast
• ❌ Granting excessive privileges: Follow least privilege - only grant access to what's needed, when it's needed
• ❌ Storing too much in sessions: Store minimal data in sessions (just user ID), check permissions from database
• ❌ Not verifying session on each request: Always use getUserId or requireUserId in protected loaders/actions
• ❌ Not handling 2FA correctly: Verify if user has 2FA before creating session
• ❌ Not destroying expired sessions: Sessions must be verified against expirationDate - check early
• ❌ Not using handleNewSession: This helper correctly handles 2FA and cookie creation
• ❌ Forgetting to handle remember: Make sure to respect user preference
• ❌ Not validating OAuth callbacks: Always validate that provider exists and result is successful - fail fast
• ❌ Not linking OAuth accounts: If email exists, link the account instead of creating duplicate
• ❌ Not updating counter in passkeys: Always update counter after successful verification

References

• Epic Stack Authentication Docs
• Epic Web Principles
• Remix Auth
• SimpleWebAuthn
• app/utils/auth.server.ts - Authentication utilities
• app/utils/session.server.ts - Gestión de sesiones
• app/routes/_auth/login.server.ts - Helpers de login
• app/routes/_auth/auth.$provider/callback.ts - OAuth callback
• app/routes/_auth/webauthn/ - WebAuthn implementation