鱼皮AI导航
鱼皮AI导航
  • 主页
  • 社区
  • AI工具
  • AI知识库
  • AI提示词
  • MCP
  • Skills
  • AI学习资源
  • AI资讯
  • GitHub开源
登录/注册

epic-auth

提供端到端身份验证能力,涵盖密码登录、邮箱注册、OAuth 第三方授权、WebAuthn 无密码通行密钥、TOTP 双因素验证及邮箱验证码流程,严格遵循最小权限与快速失败原则,统一管理会话生命周期与安全策略。

测试与安全
访问 GitHub
文档Skills.MD
name
epic-auth
description
Guide on authentication, sessions, OAuth, 2FA, and passkeys for Epic Stack
categories["authentication","sessions","oauth","security"]

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:

▼
typescript
复制代码
// ✅ 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:

▼
typescript
复制代码
// ✅ 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:

▼
typescript
复制代码
// 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:

▼
typescript
复制代码
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:

▼
typescript
复制代码
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:

▼
typescript
复制代码
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):

▼
typescript
复制代码
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:

▼
typescript
复制代码
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):

▼
typescript
复制代码
// 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:

▼
typescript
复制代码
// 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:

▼
typescript
复制代码
// 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:

▼
typescript
复制代码
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:

▼
typescript
复制代码
const verification = await prisma.verification.findUnique({ where: { target_type: { target: session.userId, type: twoFAVerificationType, }, }, }) const userHasTwoFactor = Boolean(verification)

Handle session with 2FA:

▼
typescript
复制代码
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:

▼
typescript
复制代码
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:

▼
typescript
复制代码
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:

▼
typescript
复制代码
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:

▼
typescript
复制代码
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:

▼
typescript
复制代码
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

▼
typescript
复制代码
import { logout } from '#app/utils/auth.server.ts' export async function action({ request }: Route.ActionArgs) { return logout({ request, redirectTo: '/' }) }

Session Management

Create session:

▼
typescript
复制代码
const session = await prisma.session.create({ data: { expirationDate: getSessionExpirationDate(), userId, }, select: { id: true, expirationDate: true }, })

Session expiration:

▼
typescript
复制代码
export const SESSION_EXPIRATION_TIME = 1000 * 60 * 60 * 24 * 30 // 30 days export const getSessionExpirationDate = () => new Date(Date.now() + SESSION_EXPIRATION_TIME)

Destroy session:

▼
typescript
复制代码
await prisma.session.deleteMany({ where: { id: sessionId } })

Destroy all user sessions:

▼
typescript
复制代码
await prisma.session.deleteMany({ where: { userId } })

Common examples

Example 1: Complete login

▼
typescript
复制代码
// 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

▼
typescript
复制代码
// 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

▼
typescript
复制代码
// 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
测试与安全

快捷安装

复制到终端去安装 Skill

npxskillsaddepicweb-dev/epic-stack--skill"epic-auth"
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
🔥热门工具
朱雀AI检测朱雀AI检测
朱雀AI检测助手朱雀AI检测助手
LovartLovart
老鱼简历老鱼简历
WritePass官网WritePass官网
面多多面多多
CursorCursor
星月写作星月写作
朱雀AI检测助手朱雀AI检测助手
零感AI零感AI
Skills 推荐
debug
debug 是一个系统化定位软件缺陷根因的技能,适用于用户报告 'fix'、'broken'、'error' 等问题或测试意外失败时。它通过可验证的假设、最小复现、因果链分析和回归测试,确保在修复前准确定位根本原因。
webapp-testing
提供本地 Web 应用的端到端测试能力,支持页面导航、元素交互、表单填写、动态等待、断言验证、截图捕获、浏览器日志收集及网络请求拦截,适用于前端功能验证与 UI 行为调试。
tdd-process
严格遵循测试驱动开发的红绿重构循环,强制执行先写测试、失败要有意义、实现最小化、验证全覆盖的全流程,确保每次代码变更都由可执行的测试用例驱动并经编译、检查与全量验证确认。
smoke-test
自动化创建 Mastra 项目并完成 Studio 全流程冒烟测试,涵盖项目初始化、环境配置、本地服务启动及 Chrome 浏览器中对 Agents、Tools、Workflows、Scorers 等核心模块的功能验证与截图记录。
property-based-testing
通过生成随机输入验证代码在各类边界条件下的行为一致性,适用于序列化、解析、归一化及纯函数等场景,能有效发现隐含缺陷并提升测试覆盖率,尤其适合需要高可靠性的算法与智能合约验证。