home / skills / hoangnguyen0403 / agent-skills-standard / authentication

authentication skill

This skill helps implement secure Next.js authentication using HttpOnly cookies, server components access, and middleware protection to strengthen token

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill authentication

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.1 KB

---
name: Next.js Authentication
description: Secure token storage (HttpOnly Cookies) and Middleware patterns.
metadata:
  labels: [nextjs, auth, security, cookies]
  triggers:
    files: ['middleware.ts', '**/auth.ts', '**/login/page.tsx']
    keywords: [cookie, jwt, session, localstorage, auth]
---

# Authentication & Token Management

## **Priority: P0 (CRITICAL)**

Use **HttpOnly Cookies** for token storage. **Never** use LocalStorage.

## Key Rules

1. **Storage**: Use `cookies().set()` with `httpOnly: true`, `secure: true`, `sameSite: 'lax'`. (Reference: [Setting Tokens](references/auth-implementation.md))
2. **Access**: Read tokens in Server Components via `cookies().get()`. (Reference: [Reading Tokens](references/auth-implementation.md))
3. **Protection**: Guard routes in `middleware.ts` before rendering. (Reference: [Middleware Protection](references/auth-implementation.md))

## Anti-Pattern: LocalStorage

- **Security Risk**: Vulnerable to XSS.
- **Performance Hit**: Incompatible with Server Components (RSC). Forces client hydration and causes layout shift.

## Related Topics

common/security-standards | server-components | app-router

Overview

This skill documents secure authentication patterns for Next.js using HttpOnly cookies and middleware route protection. It emphasizes server-first token handling to avoid client-side storage risks and to stay compatible with Server Components. The guidance focuses on concrete configuration and common anti-patterns to prevent XSS and layout-hydration issues.

How this skill works

Tokens are issued and stored with cookies().set() configured as httpOnly, secure, and sameSite: 'lax' so they are inaccessible to JavaScript and sent automatically with requests. Server Components and API routes read tokens via cookies().get(), keeping authentication logic on the server. A middleware.ts file inspects requests and redirects or blocks access to protected pages before rendering.

When to use it

When implementing session or JWT authentication in Next.js (App Router)
When using Server Components to render authenticated content on the server
When protecting routes and APIs consistently across server and client requests
When preventing XSS exposure of tokens and avoiding client-side token handling
When you need automatic cookie sending for same-site requests

Best practices

Store tokens only in HttpOnly cookies using cookies().set({ httpOnly: true, secure: true, sameSite: 'lax' })
Read tokens on the server with cookies().get() inside Server Components or API routes
Enforce route protection in middleware.ts to block unauthenticated requests before rendering
Avoid LocalStorage or other client-accessible storage for tokens due to XSS risk and RSC incompatibility
Use short-lived access tokens and refresh tokens with appropriate rotation and revocation policies

Example use cases

Protecting a dashboard route by checking cookies in middleware.ts and redirecting to /login for unauthenticated users
Issuing access and refresh tokens from an API route, storing them as HttpOnly cookies via cookies().set(), and reading them in Server Components
Using server-side token reads to fetch personalized data for Server Components without client hydration
Blocking API access from unauthorized clients in middleware before hitting Next.js API routes

FAQ

Why not use LocalStorage for tokens?

LocalStorage is accessible to JavaScript, making tokens vulnerable to XSS. It also forces client-side hydration and breaks Server Components compatibility, causing layout shifts.

How should I configure cookie options?

Set cookies with httpOnly: true, secure: true (in production), and sameSite: 'lax' to limit cross-site request exposure while allowing normal navigation.