authentication-patterns skill

Authentication Patterns Skill

Reference for implementing secure, production-ready authentication.

WHENTOUSE

Apply this skill when implementing authentication in a project, reviewing existing auth flows for security issues, choosing between auth providers, or migrating between auth strategies. Use the security checklist before shipping any auth-related change.

AUTH_APPROACHES

Decision Guide

• Server-rendered app with simple needs → Session-based
• SPA or mobile app calling APIs → JWT with refresh token rotation
• Want social login or SSO → OAuth 2.0 / OIDC
• Greenfield with modern UX goals → Passkeys + OAuth fallback

JWTBESTPRACTICES

Token Lifecycle

Login → Access Token (short-lived) + Refresh Token (long-lived, rotated)
  │
  ├─ Access Token: 15 min expiry, sent via httpOnly cookie or Authorization header
  │
  └─ Refresh Token: 7-30 day expiry, stored in httpOnly secure cookie
       │
       └─ On use: issue new access + new refresh token, invalidate old refresh token

Rules

• [P0-MUST] Set short expiry on access tokens (15 minutes or less).
• [P0-MUST] Store tokens in httpOnly, Secure, SameSite=Lax cookies — never in localStorage or sessionStorage.
• [P0-MUST] Implement refresh token rotation — each refresh token is single-use.
• [P0-MUST] Maintain a server-side blocklist for revoked refresh tokens.
• [P1-SHOULD] Include only essential claims in JWT payload (sub, iat, exp, role). Keep it small.
• [P1-SHOULD] Use asymmetric signing (RS256 or ES256) for distributed systems; symmetric (HS256) for single-service only.
• [P1-SHOULD] Validate iss, aud, and exp claims on every request.
• [P2-MAY] Use JWE (encrypted JWT) when token payload contains sensitive data.

Token Storage Comparison

PROVIDER_PATTERNS

Comparison

When to Use Each

• NextAuth / Auth.js: You want provider flexibility, self-hosting, and database session control. Best when you need custom flows.
• Clerk: You want auth done fast with pre-built UI components. Best for MVPs and teams that don't want to build auth UI.
• Supabase Auth: You're already using Supabase. Auth integrates with RLS policies for row-level security.
• Lucia: You want a minimal, type-safe session library without framework lock-in.

NextAuth.js Setup Pattern

// app/api/auth/[...nextauth]/route.ts
import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";
import { PrismaAdapter } from "@auth/prisma-adapter";
import { prisma } from "@/lib/prisma";

export const { handlers, auth, signIn, signOut } = NextAuth({
  adapter: PrismaAdapter(prisma),
  providers: [
    GitHub({
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    }),
  ],
  callbacks: {
    session({ session, user }) {
      session.user.id = user.id;
      return session;
    },
  },
});

SECURITY_CHECKLIST

Before Shipping Auth

• [ ] Rate limiting: Login endpoint limited to 5-10 attempts per minute per IP.
• [ ] CSRF protection: Anti-CSRF tokens on all state-changing requests (or use SameSite=Lax cookies).
• [ ] Password hashing: Using bcrypt (cost 12+) or argon2id — never MD5, SHA-1, or plain SHA-256.
• [ ] HTTPS only: All auth endpoints served over TLS. Cookies have Secure flag.
• [ ] Input validation: Email format, password length (min 8, max 128), no SQL/NoSQL injection vectors.
• [ ] Account enumeration: Login and registration return the same response whether account exists or not.
• [ ] Session invalidation: Logout invalidates server-side session/refresh token, not just client cookie.
• [ ] MFA support: TOTP (authenticator app) or WebAuthn as second factor for sensitive accounts.
• [ ] Password reset: Time-limited tokens (1 hour), single-use, sent over secure channel.
• [ ] Audit logging: Log auth events (login, logout, failed attempts, password changes) with timestamp and IP.

Password Hashing

// Using bcrypt
import bcrypt from "bcrypt";

const SALT_ROUNDS = 12;

async function hashPassword(password: string): Promise<string> {
  return bcrypt.hash(password, SALT_ROUNDS);
}

async function verifyPassword(password: string, hash: string): Promise<boolean> {
  return bcrypt.compare(password, hash);
}

// Using argon2 (preferred for new projects)
import argon2 from "argon2";

async function hashPassword(password: string): Promise<string> {
  return argon2.hash(password, { type: argon2.argon2id });
}

async function verifyPassword(hash: string, password: string): Promise<boolean> {
  return argon2.verify(hash, password);
}

COMMON_MISTAKES