[Next.js] Route Handlers와 쿠키 기반 인증

1. 오늘 배운 점

오늘 새로 알게 된 것

• Next.js Route Handlers(app/api/*/route.ts)는 서버에서 실행되는 API 엔드포인트다
• httpOnly 쿠키는 JavaScript로 접근할 수 없어서 XSS 공격으로부터 안전하다
• Route Handler가 브라우저와 외부 API 사이의 프록시 역할을 하면서 쿠키를 Authorization 헤더로 변환한다

정리

로그인 기능을 만들면서 처음에는 localStorage에 토큰을 저장했는데, 보안 문제 때문에 httpOnly 쿠키로 전환했다. 브라우저는 쿠키를 자동으로 서버에 보내주고, Next.js Route Handler가 이 쿠키를 읽어서 외부 API 호출 시 Authorization 헤더로 변환해준다. 카페 멤버십 카드 비유처럼, 쿠키가 멤버십 카드고 Route Handler가 카드를 확인하는 직원 역할을 한다.

2. 헷갈렸던 점

처음에 헷갈렸던 부분

• Route Handler와 클라이언트 API 함수의 차이 - 둘 다 API를 호출하는데 왜 따로 만들어야 하는지
• 쿠키가 자동으로 전송되는데 왜 수동으로 헤더에 넣어야 하는지
• route.ts와 loginApi.ts의 역할 차이

생각 정리

Route Handler는 서버에서 실행되고, loginApi 같은 함수는 브라우저에서 실행된다는 걸 이해하니 명확해졌다. 브라우저는 쿠키를 Next.js 서버로만 자동 전송하고, Next.js 서버가 외부 API로 요청할 때는 수동으로 Authorization 헤더를 만들어야 한다. 결국 Route Handler는 "안전한 중간 다리" 역할이다.

3. 공식문서 핵심

참고한 공식문서

• Next.js Route Handlers https://nextjs.org/docs/app/building-your-application/routing/route-handlers
• Next.js Data Fetching https://nextjs.org/docs/app/building-your-application/data-fetching
• Next.js Authentication https://nextjs.org/docs/app/building-your-application/authentication

공식문서에서 말하는 핵심

• Route Handlers는 Web Request/Response API를 사용해서 커스텀 요청 핸들러를 만들 수 있다
• app/api 폴더의 route.ts 파일이 API 엔드포인트가 된다
• 쿠키는 cookies() 함수로 서버에서 안전하게 읽고 쓸 수 있다

4. 그래서 나는 이렇게 쓰기로 했다

• 인증이 필요한 API는 무조건 Route Handler를 거쳐서 호출
• 토큰은 httpOnly 쿠키에 저장 (localStorage 사용 안 함)
• 클라이언트 코드에서는 /api/auth/login 같은 내부 엔드포인트만 호출
• 환경변수는 서버 전용(API_URL)과 클라이언트 노출용(NEXT_PUBLIC_)을 구분

5. 한 줄 회고

Route Handler는 단순한 프록시가 아니라 보안의 핵심 방어선이다.