Next.js × Spring Boot: SSR JWT 인증 트러블슈팅과 BFF 설계 기록

JWT 글

리팩토링 이전 문제😡

1) CSR 전용 인증을 서버/클라이언트 공통 유틸로 사용

다음은 내가 처음 적용했던 잘못된 공통 fetch 유틸리티 코드이다.

// utils/fetchJWT.ts
"use server";

import { Member } from "@/interface/Member";
import { DataResponse } from "@/interface/DataResponse";
import { getCookie, setCookie } from "@/utils/cookie";

const host = process.env.BACKEND_URL || "http://localhost";


interface IRequestInit {
    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
    body?: BodyInit | null;
    credentials?: RequestCredentials;
    cache?: RequestCache;
    next?: NextFetchRequestConfig | undefined;
    headers?: HeadersInit;
}

// 둘 중에 하나 반환
export type FetchJWTResult<T = any> =
    | { success: true; data: T; message: string; code: number }
    | { success: false; message: string; code: number };

export const fetchJWT = async <T = any>(
    url: string,
    requestInit: IRequestInit
): Promise<FetchJWTResult<T>> => {
    const member = (await getCookie("member")) as Member | undefined;

    if (!member || !member.accessToken || !member.refreshToken) {
        return { success: false, message: "로그인이 필요합니다.", code: 401 };
    }

    const { accessToken, refreshToken, email } = member;
    const configData = getConfigData(requestInit, accessToken);

    let response = await fetch(host + url, configData);
    let raw: DataResponse<T> = await response.json();

    if (response.ok && raw.success) {
        return { success: true, data: raw.data, message: raw.message, code: response.status };
    }

    if (raw.message === "ERROR_ACCESS_TOKEN") {
        try {
            const newJWT = await refreshJWT(accessToken, refreshToken, email, member);
            const newConfigData = getConfigData(configData, newJWT.accessToken);

            response = await fetch(host + url, newConfigData);
            raw = await response.json();

            if (response.ok && raw.success) {
                return { success: true, data: raw.data, message: raw.message, code: response.status };
            }
            return { success: false, message: raw.message || "요청 실패", code: response.status };
        } catch (e) {
            return { success: false, message: "JWT 갱신 실패", code: 401 };
        }
    }

    return { success: false, message: raw.message || "서버 오류", code: response.status };
};

const getConfigData = (requestInit: IRequestInit, accessToken: string) => {
    const { headers } = requestInit;
    return {
        ...requestInit,
        headers: { ...headers, Authorization: `Bearer ${accessToken}` },
    };
};

const refreshJWT = async (
    accessToken: string,
    refreshToken: string,
    email: string,
    member: Member
) => {
    const response = await fetch(
        host + "/api/member/refresh?refreshToken=" + refreshToken,
        {
            method: "POST",
            headers: {
                Authorization: `Bearer ${accessToken}`,
                "Content-Type": "application/json",
            },
            body: JSON.stringify({ email }),
        }
    );

    if (!response.ok) {
        throw new Error("JWT 갱신에 실패했습니다.");
    }

    const newJWT = await response.json();
    const newCookie = {
        ...member,
        accessToken: newJWT.accessToken,
        refreshToken: newJWT.refreshToken,
    } as Member;

    await setCookie("member", JSON.stringify(newCookie));
    return newJWT;
};

이 코드는 fetchJWT라는 공통 유틸을 통해 accessToken 만료 시 자동으로 refreshToken으로 갱신하고, 요청을 재시도하는 기능을 제공한다.
나는 이 유틸을 간단하게 서버/클라이언트 구분 없이 공통으로 사용하려고 했고, accessToken이 만료되면 토큰을 갱신해 다시 Authorization 헤더에 설정하도록 만들었다. 하지만 여기엔 치명적인 문제가 있었다.

1. 서버/클라이언트 혼용 문제

   • 쿠키를 읽기 위해 next/headers의 cookies()를 사용해야 했고, 때문에 파일 최상단에 "use server"를 선언했다.
   • 이 상태에서 클라이언트 컴포넌트에서 fetchJWT()를 호출하면, 빌드 에러가 발생하거나 서버 전용 코드가 번들에 포함되어 클라이언트 런타임에서 터질 위험이 크다.
   • 즉, 하나의 유틸을 양쪽에서 공통으로 쓰는 구조 자체가 잘못된 것이다.

2. 잘못된 인증 패턴 적용

   • 이 구조는 HttpOnly 쿠키 기반 인증이 아니라, Authorization 헤더에 accessToken을 직접 넣는 방식이었다.
   • 이 방식은 흔히 CSR 환경에서 localStorage/sessionStorage에 토큰을 저장하고, fetch 호출 시 꺼내서 헤더에 붙이는 패턴이다.
   • 하지만 SSR 환경에서는 localStorage를 쓸 수 없다. 따라서 서버와 클라이언트 모두에서 이 방식을 공통으로 사용하는 건 맞지 않는다.

따라서 fetch 로직을 서버 전용 / 클라이언트 전용으로 분리하는 것이 올바른 방향같다.

2) 인증 구조의 혼란

브라우저 localStorage에 JWT를 저장하고 CSR fetch 때마다 헤더에 수동으로 붙이는 패턴이 클라이언트 중심이고 실무에서 권장되지 않는다. 이유는 다음과 같다.

• XSS 취약성
  localStorage는 자바스크립트로 접근 가능하므로, 스크립트 삽입에 취약할 경우 토큰 탈취 위험이 크다.

• SSR과의 비호환
  서버 렌더링/서버 컴포넌트 환경에서는 localStorage에 접근할 수 없기 때문에 동일 패턴을 그대로 사용할 수 없다.
  (다만 Authorization 헤더 자체는 SSR에서도 사용 가능하며, 서버 측에서 쿠키나 서버 세션을 읽어 헤더를 구성하여 백엔드를 호출할 수 있다.)

• 유지보수 비용
  매 요청마다 토큰을 꺼내 헤더에 붙이고, 만료/재시도/경합을 처리해야 해 코드가 복잡해진다.

따라서 이 프로젝트에서는 Access Token, Refresh Token 모두를 HttpOnly 쿠키 기반으로 전환한다. 이때 SameSite(Lax/Strict)와 CSRF 토큰(더블 서밋 등)을 함께 적용해 CSRF 방어를 필수로 구성한다.

HTTPOnly Cookie🍪

• HttpOnly는 쿠키의 속성 중 하나로, 자바스크립트에서 쿠키에 접근하지 못하게 막는 보안 설정
• 이 쿠키는 백엔드(서버)에서 발급해야 하며, 클라이언트에서 직접 설정할 수 없음

HttpOnly 쿠키는 보안성과 SSR 호환성을 동시에 갖춘 인증 방식으로, accessToken, refreshToken 등 민감한 정보를 안전하게 보호할 수 있는 실무에서 권장되는 방식이다.

백엔드에서 쿠키 설정

Set-Cookie: access_token=abcdefg; HttpOnly; Secure; Path=/; Max-Age=1800;

클라이언트에서 fetch 요청

await fetch("/api/user/me", {
  method: "GET",
  credentials: "include", // 브라우저가 쿠키 자동 전송
});

• HttpOnly: JS로 접근 불가 → XSS로 토큰 탈취 어려움
• 자동 전송: credentials: "include"면 브라우저가 알아서 붙임
• SSR 호환: 서버에서 cookies()로 읽을 수 있어 데이터 패칭에 유리

---

변경 요구사항 요약🐶

• 환경: Next.js 14 (App Router) + Spring Boot
• 기능 요구사항:
  • SSR, CSR, ISR, SSG 혼합 사용
  • HttpOnly 쿠키 기반 인증 시스템 도입 (Spring Boot가 Set-Cookie로 토큰 설정)
  • accessToken 만료 시 /api/member/refresh로 자동 재발급
  • 사용자 정보는 /api/member/me를 호출해서 가져와야 함

---

리팩토링 중 발생한 문제🙊

서버 컴포넌트에서는 쿠키에 저장된 accessToken refresh가 불가하다.

Springboot에서 access_token, refresh_token 모두 HttpOnly 쿠키로 설정 완료한 후에 프론트엔드 리팩토링 중이였다. fetcher 유틸리티를 만들고 아래와 같이 client, server 을 분리시켰다.

export const fetcher = typeof window === 'undefined' ? serverFetcher : clientFetcher;

serverFetcher와 clientFetcher를 각각 분리하고, 토큰이 만료될 경우 refresh 요청을 보내 accessToken을 재발급받는 로직도 포함시켰다.
처음엔 서버 측(serverFetcher)에서 accessToken이 만료되면 refreshToken을 이용해 Spring Boot 서버에 재발급 요청을 보내고,
응답으로 받은 Set-Cookie 헤더를 통해 브라우저의 쿠키가 자동으로 갱신될 것이라 예상했다. 하지만 여기서 중요한 오해가 있었다.

Spring Boot는 refresh 요청에 대해 accessToken을 재발급하고, 응답에 Set-Cookie 헤더를 포함하여 accessToken 쿠키를 갱신하려 한다. 하지만 이 요청이 Next.js의 serverFetcher (즉, 서버 사이드 fetch) 에서 발생한 경우, 응답은 브라우저가 직접 받은 것이 아니기 때문에 쿠키는 브라우저에 반영되지 않는다.

백엔드(Spring Boot)는 쿠키를 설정(Set-Cookie)했지만, 해당 응답은 브라우저가 받은 게 아니기 때문에,브라우저의 HttpOnly 쿠키는 여전히 만료된 accessToken 상태로 남게 된다. Set-Cookie는 오직 브라우저가 직접 받은 응답에만 반영된다.

정리

• Spring Boot에서 Set-Cookie로 accessToken을 재설정하더라도, 해당 요청이 Next.js 서버(fetcher) 내부에서 발생한 것이라면 브라우저에는 아무런 쿠키 변경도 반영되지 않는다.
• 따라서 JWT 재발급 요청은 반드시 브라우저가 직접 보내야 하며 그 응답을 통해서만 HttpOnly 쿠키를 실제로 갱신할 수 있다.
  

---

해결법 구상🙉

✅방법 1. 서버에서 accessToken을 갱신하지 않고, CSR 에서만 refresh 처리

1. SSR: 주문 조회 시도 → accessToken 만료 → SSR 렌더 결과: "주문 조회 실패"
2. CSR: 페이지 마운트 시 → refresh 시도 → 성공 시 다시 주문 정보 요청
3. 성공하면 → "주문 상세"로 전환

서버(fetcher)에서는 accessToken이 만료되면 401을 반환하고, 이후 클라이언트 컴포넌트에서 mount 시점에 /api/refresh 요청을 보내 쿠키를 갱신한다. 브라우저가 직접 Spring Boot에 refresh 요청을 보내면, Spring Boot의 Set-Cookie 응답이 브라우저에 도달하고, 실제 쿠키가 갱신된다.

❌방법 2. middleware.ts에서 SSR 진입 전에 accessToken 자동 갱신

SSR 진입 전에 middleware에서 access_token을 검사 → 없으면 refresh → 쿠키 덮어쓰기

Next.js의 middleware.ts는 모든 요청 전에 실행되니까,
SSR이든 CSR이든 access_token이 없거나 만료됐다면 여기서 자동으로 /refresh 호출해서 새 access_token 쿠키를 받아오면 되지 않을까?

확실히 간단한 것 같다.

기대한 흐름

[브라우저] GET /mypage
   ↓
[middleware.ts] access_token 검사 → 없거나 만료됨
   ↓
/api/member/refresh 요청 → 새 access_token 응답 (Set-Cookie)
   ↓
[SSR 컴포넌트] cookies().get('access_token') → 새 accessToken 기대

SSR 진입 전인 middleware에서 access_token을 갱신해도, SSR 컴포넌트에서 읽는 cookies()에는 반영되지 않는다. middleware는 "요청 처리 전"에 실행되지만 SSR에서 사용하는 cookies()는 요청 당시의 쿠키를 기준으로 동작한다. middleware에서 Set-Cookie 응답을 내려도 현재 렌더링 요청에는 적용되지 않고, 다음 요청부터 적용된다. 즉 SSR 컴포넌트 내부에서 여전히 기존 (만료된) 쿠키 값을 읽게 된다. 실무에서 middleware는 인증 여부 판별까지는 OK, 하지만 쿠키 갱신은 못한다.

❌방법 3. BFF(Backend For Frontend)로 refresh 처리

(아래에 자세히 적어놨다. 결국 BFF를 사용했다.)
구글링 서칭을 통해 BFF를 사용해보라는 글을 읽었다. 혹시나 해서 적용해본다.

// src/app/api/bff/me/route.ts
import { cookies } from 'next/headers'
import { NextResponse } from 'next/server'

export async function GET() {
  const cookieStore = cookies()
  const accessToken = cookieStore.get('access_token')?.value
  const refreshToken = cookieStore.get('refresh_token')?.value

  if (!accessToken) {
    return NextResponse.json({ success: false, message: 'no accessToken' }, { status: 401 })
  }

  // 사용자 정보 요청
  let res = await fetch(`${process.env.BACK_URL}/api/member/me`, {
    headers: {
      Cookie: `access_token=${accessToken}; refresh_token=${refreshToken}`
    },
    credentials: 'include',
  })

  // accessToken 만료 시 → refresh
  if (res.status === 401 && refreshToken) {
    const refreshRes = await fetch(`${process.env.BACK_URL}/api/member/refresh`, {
      method: 'POST',
      headers: {
        Cookie: `refresh_token=${refreshToken}`
      },
      credentials: 'include',
    })

    if (!refreshRes.ok) {
      return NextResponse.json({ success: false, message: 'refresh failed' }, { status: 401 })
    }

    // 새로운 access_token과 함께 재시도
    res = await fetch(`${process.env.BACK_URL}/api/member/me`, {
      headers: {
        Cookie: `access_token=${accessToken}; refresh_token=${refreshToken}`
      },
      credentials: 'include',
    })
  }

  const user = await res.json()
  return NextResponse.json({ success: true, data: user })
}

• /api/member/refresh 요청 결과로 백엔드(Spring Boot)는 Set-Cookie로 access_token을 응답
• 그러나 이 응답은 Next.js 서버가 받을 뿐, 브라우저는 이 응답을 직접 받지 않음
• 따라서 브라우저의 쿠키는 전혀 갱신되지 않고, 이전 access_token 상태 그대로 유지됨

동일하게 BFF사용해서 서버 측에서 accessToken을 재발급 받아도, 브라우저 쿠키에 반영되지 않아서 무의미

---

결론: SSR은 안전하게 실패하고, CSR에서 복구하자😾→😺

SSR에서 accessToken 만료
serverFetcher() → 401 → prefetchQuery() error 상태 저장
CSR에서 hydration 후 useQuery()의 retryOnMount: true (기본값) → 자동 재요청 발생
clientFetcher() 401 → /refresh 요청 → accessToken 갱신 → 원 요청 재시도 ✅ 정상 작동

1. SSR: 주문 조회 시도 → accessToken 만료 → SSR 렌더 결과: "주문 조회 실패"
2. CSR: 페이지 마운트 시 → refresh 시도 → 성공 시 다시 주문 정보 요청
3. 성공하면 → "주문 상세"로 전환

전략 요약

1. SSR에서는 access_token이 유효할 때만 사용자 정보를 가져온다.
   • 만료되면 SSR 단계에서는 null 반환
2. CSR에서 refresh → /api/member/me 재요청으로 사용자 상태를 복구한다.

---

구현 방법😻

위치	역할
RootLayout (SSR)	SSR 시 access_token 쿠키가 있다면 getUserInfo() 실행 → 유저 정보 확보
UserHydration	SSR에서 얻은 유저 정보를 CSR 쪽 zustand나 context에 초기 주입
UserSyncHandler	CSR에서 access_token이 만료되었거나 SSR에서 유저 정보를 못 불러온 경우, refresh 요청 → 상태 복구
SessionExpiredRedirect	로그인된 것처럼 보이지만 실제로 인증 실패 상태일 때 자동 리디렉션 처리

1. 서버/클라이언트 fetcher 분리

serverFetcher 예시

'use server';
import { cookies } from 'next/headers';

export const serverFetcher = async <T = any>(
  path: string,
  options: RequestInit = {}
): Promise<T> => {
  const finalUrl = `${process.env.NEXT_PUBLIC_BACKEND_URL}${path}`;
  const cookieString = cookies().toString();

  const res = await fetch(finalUrl, {
    ...options,
    headers: {
      ...(options.headers || {}),
      cookie: cookieString,
    },
    cache: 'no-store',
  });

  const json = await res.json().catch(() => ({}));

  if (!res.ok || json?.success === false) {
    throw new Error(json?.message || '요청 실패');
  }

  return json.data;
};

clientFetcher 예시 (accessToken refresh 포함)

import { SessionExpiredError } from '@/libs/error/errors';

export const clientFetcher = async <T = any>(
  path: string,
  options: RequestInit = {}
): Promise<T> => {
  const finalUrl = `${process.env.NEXT_PUBLIC_BACKEND_URL}${path}`;
  let res = await fetch(finalUrl, {
    ...options,
    credentials: 'include',
  });

  let json: any = await res.json().catch(() => ({}));

  if (res.status === 401) {
    const refresh = await fetch(`${process.env.NEXT_PUBLIC_BACKEND_URL}/api/member/refresh`, {
      method: 'POST',
      credentials: 'include',
    });

    if (refresh.ok) {
      res = await fetch(finalUrl, {
        ...options,
        credentials: 'include',
      });
      json = await res.json().catch(() => ({}));
    } else {
      throw new SessionExpiredError();
    }
  }

  if (!res.ok || json?.success === false) {
    throw new Error(json?.message || '요청 실패');
  }

  return json.data;
};

그 외 accessToken이 필요없는 누구나 접근 가능한 public API도 추가했다..

2. UserSyncHandler – CSR에서 상태 복구

사용자가 페이지를 새로고침하거나, CSR으로 직접 특정 페이지에 접근할 경우, Zustand에 저장된 유저 상태는 메모리에서 초기화된다.
이때 상태 복구를 위해 HttpOnly 쿠키에 저장된 access_token을 기반으로 /api/member/me 요청을 보내 유저 정보를 다시 가져온다.

UserSyncHandler는 바로 이 과정을 담당하는 클라이언트 전용 컴포넌트로, 유저 정보를 동기화(sync)하고 상태 관리 도구(Zustand 등)에 로그인 정보를 복원한다.

• 최초 클라이언트 마운트 시 1회만 실행
• 401 에러가 발생하면 내부적으로 refresh 요청 후 재시도
• refresh까지 실패하면 세션 만료로 판단 → 로그아웃 처리

'use client';
import { useEffect } from 'react';
import { useUserStore } from '@/store/userStore';

export function UserSyncHandler() {
  const setUser = useUserStore((s) => s.setUser);

  useEffect(() => {
    const fetchUser = async () => {
      let res = await fetch('/api/me', { credentials: 'include' });

      if (res.status === 401) {
        const refresh = await fetch('/api/member/refresh', {
          method: 'POST',
          credentials: 'include',
        });

        if (refresh.ok) {
          res = await fetch('/api/me', { credentials: 'include' });
        }
      }

      if (res.ok) {
        const user = await res.json();
        setUser(user);
      }
    };

    fetchUser();
  }, []);

  return null;
}

3. SessionExpiredRedirect – 전역 감지 후 로그아웃

react-query의 전역 error handler에서 SessionExpiredError를 감지하면, SessionExpiredRedirect 컴포넌트를 통해 리디렉션함

동작 순서 요약

1. SSR: serverFetcher → access_token 쿠키 기반으로 유저 데이터 획득
2. 클라이언트 초기 진입 (CSR): UserSyncHandler가 /api/me로 상태 복원 시도
3. 실패하면 자동 refresh
4. refresh도 실패 시 → throw SessionExpiredError
5. RQProvider (React Query 전역 onError 실행) → SessionExpiredError 발생 시 → useUserStore().setSessionExpired()
6. app/layout.tsx에 있는 SessionExpiredRedirect가 이를 감지(isSessionExpired가 변경됨)하고 /login 이동

---

SSR에서 사용자 정보가 필요한 경우엔?

❌ 직접 user?.email 등을 넣으면 안 되는 이유

• SSR 시점의 accessToken이 만료되어 있다면 잘못된 사용자 정보로 요청하게 됨

✅ 해결법: 사용자 정보는 백엔드에서 access_token 파싱으로 처리

• 즉, 프론트에서 sellerEmail, userId 등 보내지 않고
• 백엔드(Spring)에서 access_token을 읽어 사용자 정보 처리

@GetMapping("/api/dashboard/real-time-top")
public ResponseEntity<?> getTopData(@AuthenticationPrincipal CustomUserDetails user) {
    String email = user.getUsername(); // JWT에서 추출된 값
    ...
}

---

결론

구분	처리 방식
SSR accessToken 만료	그대로 실패 (user === null)
CSR에서 상태 복구	/refresh → /me → 상태 동기화
SSR에서 사용자 정보 필요 시	accessToken 파싱은 백엔드(Spring)에서 수행
로그인 직후 SSR 쿠키 반영	router.refresh() 또는 CSR 상태 동기화 사용

---

.
.
.
.
.

이게 끝일 줄 알았지만..

BFF

처음 인증구조를 마친 뒤, 백엔드가 HttpOnly 쿠키로 토큰을 내려줄 때 Next.js는 어떻게 받아야 하는가를 다시 생각해봤다.
처음엔 BFF(프록시 Route Handler)를 SSR 내부에서 서버→백엔드 호출 용도로만 이해해서, 브라우저가 Set-Cookie를 못 받아 갱신 효과가 없네? 라고 느꼈다.
하지만 포인트는 "SSR에서 BFF를 호출"이 아니라, "브라우저가 BFF의 응답을 직접 받도록 하는 것"이다.

• BFF는 브라우저가 /api/*(BFF)로 요청하게 하고, BFF가 요청 쿠키를 백엔드로 전달한 뒤, 백엔드가 내려준 Set-Cookie를 브라우저 응답에 그대로 실어 패스스루하는 것이다. 이렇게 해야 브라우저 쿠키가 실제로 갱신된다.
• 반대로, SSR의 일반적인 데이터 패칭은 Next 서버가 백엔드를 직접 호출(요청자의 쿠키를 Cookie 헤더로 수동 첨부)하고, 만료(401/419) 시에는 SSR을 실패로 두고 하이드레이션 후 CSR에서 /api/member/refresh(BFF)로 갱신하는 흐름이 가장 단순하고 빠르다.

아래는 구현한 BFF 라우트 핸들러 코드이다.

// app/api/bff/[...path]/route.ts

import { NextResponse } from 'next/server';
import { cookies } from 'next/headers';

const API_BASE_URL = process.env.BACKEND_URL!;
const ACCESS_TOKEN_COOKIE = 'access_token';
const REFRESH_TOKEN_COOKIE = 'refresh_token';

/** Set-Cookie 문자열에서 access/refresh 토큰만 뽑는다 */
function parseTokensFromSetCookie(setCookieHeader: string) {
  const map = new Map<string, string>();
  // 여러 Set-Cookie가 하나의 헤더로 합쳐질 수 있음
  const parts = setCookieHeader.split(/,(?=[^;]+=)/);

  for (const p of parts) {
    const [kv] = p.trim().split(';');
    const eq = kv.indexOf('=');
    if (eq > 0) {
      const name = kv.slice(0, eq).trim();
      const value = kv.slice(eq + 1).trim();
      if (name === ACCESS_TOKEN_COOKIE || name === REFRESH_TOKEN_COOKIE) {
        map.set(name, value);
      }
    }
  }
  return map;
}

/** 현재 요청에서 인증 쿠키를 읽어 Cookie 헤더로 만든다 */
function getAuthCookiesHeader() {
  const cookieStore = cookies();
  const access = cookieStore.get(ACCESS_TOKEN_COOKIE)?.value;
  const refresh = cookieStore.get(REFRESH_TOKEN_COOKIE)?.value;
  return [
    access && `${ACCESS_TOKEN_COOKIE}=${access}`,
    refresh && `${REFRESH_TOKEN_COOKIE}=${refresh}`,
  ]
    .filter(Boolean)
    .join('; ');
}

/** 업스트림(백엔드)으로 원요청을 1회 전달 */
async function sendToBackend(
  path: string,
  req: Request,
  cookieHeader?: string,
  bodyBuf?: ArrayBuffer,
) {
  const url = new URL(req.url);
  const backendURL = `${API_BASE_URL}${url.pathname.replace(/^\/api\/bff/, '')}${url.search || ''}`;

  const headers = new Headers(req.headers);
  // 브라우저가 보낸 도메인 지움 (Host → BFF 주소이므로)
  headers.delete('host');
  headers.delete('cookie');
  // 필요한 헤더만 다시 세팅
  if (cookieHeader) headers.set('cookie', cookieHeader);
  headers.set('accept', headers.get('accept') ?? 'application/json');

  const body =
    req.method === 'GET' || req.method === 'HEAD'
      ? undefined
      : (bodyBuf ?? (await req.arrayBuffer()));

  return fetch(backendURL, { method: req.method, headers, body });
}

/** 1) 원요청 호출 → 2) 401이면 refresh → 3) 성공 시 재시도 */
async function handler(req: Request, path: string) {
  // 재시도를 위해 요청 바디를 한 번만 읽어 보관
  const bodyBuf =
    req.method === 'GET' || req.method === 'HEAD' ? undefined : await req.arrayBuffer(); // 요청 body 전체를 ArrayBuffer로 읽어옴

  // 1) 현재 쿠키로 원요청 호출
  const cookieHeader = getAuthCookiesHeader();
  const response = await sendToBackend(path, req, cookieHeader, bodyBuf);

  if (response.status !== 401) {
    const payload = await response.arrayBuffer(); // 원요청 응답의 body 전체를 ArrayBuffer로 읽음
    const bffRes = new NextResponse(payload, { status: response.status });

    const setCookie = response.headers.get('set-cookie');
    if (setCookie) bffRes.headers.append('set-cookie', setCookie);

    response.headers.forEach((v, k) => {
      if (k.toLowerCase() !== 'set-cookie') bffRes.headers.set(k, v);
    });
    return bffRes;
  }

  // 2) 401 → 토큰 리프레시 시도
  console.log('[BFF] 401 Unauthorized → refresh 시도');
  const refreshHeaders = new Headers();
  if (cookieHeader) refreshHeaders.set('cookie', cookieHeader);
  const refreshRes = await fetch(`${API_BASE_URL}/api/member/refresh`, {
    method: 'POST',
    headers: refreshHeaders,
  });
  console.log('[BFF] refresh 응답 상태:', refreshRes.status);

  if (!refreshRes.ok) {
    // 실패 → 세션 만료 처리
    const bffRes = NextResponse.json({ error: 'session_expired' }, { status: 401 });
    bffRes.cookies.set(ACCESS_TOKEN_COOKIE, '', { maxAge: 0, path: '/' });
    bffRes.cookies.set(REFRESH_TOKEN_COOKIE, '', { maxAge: 0, path: '/' });
    return bffRes;
  }

  // 3) 리프레시 성공 → 새 쿠키 패스스루 + 원요청 재시도
  const setCookie = refreshRes.headers.get('set-cookie');
  let retryCookieHeader = cookieHeader;

  if (setCookie) {
    // refresh 응답의 Set-Cookie 문자열에서 access/refresh 토큰만 뽑아냄
    const parsed = parseTokensFromSetCookie(setCookie);
    const access = parsed.get(ACCESS_TOKEN_COOKIE) ?? cookies().get(ACCESS_TOKEN_COOKIE)?.value;
    const refresh = parsed.get(REFRESH_TOKEN_COOKIE) ?? cookies().get(REFRESH_TOKEN_COOKIE)?.value;
    retryCookieHeader = [
      access && `${ACCESS_TOKEN_COOKIE}=${access}`,
      refresh && `${REFRESH_TOKEN_COOKIE}=${refresh}`,
    ]
      .filter(Boolean)
      .join('; ');
  }

  // 원래 요청을 새 토큰 쿠키로 다시 백엔드에 전달 (재시도)
  const retryRes = await sendToBackend(path, req, retryCookieHeader, bodyBuf);
  // 재시도 응답의 body 를 ArrayBuffer 로 읽음
  const retryPayload = await retryRes.arrayBuffer();
  // Next.js 응답 객체 생성해서 클라이언트로 돌려줄 준비
  const resp = new NextResponse(retryPayload, { status: retryRes.status });
  // refresh 응답에 Set-Cookie 가 있으면 그대로 브라우저로 전달해서 쿠키 갱신
  if (setCookie) resp.headers.append('set-cookie', setCookie);
  // 나머지 헤더들도 복사
  retryRes.headers.forEach((v, k) => {
    if (k.toLowerCase() !== 'set-cookie') resp.headers.set(k, v);
  });
  // 브라우저에 돌려줌
  return resp;
}

// 라우트 엔트리
export async function GET(req: Request, { params }: { params: { path: string[] } }) {
  return handler(req, params.path.join('/'));
}
export async function POST(req: Request, { params }: { params: { path: string[] } }) {
  return handler(req, params.path.join('/'));
}
export async function PUT(req: Request, { params }: { params: { path: string[] } }) {
  return handler(req, params.path.join('/'));
}
export async function PATCH(req: Request, { params }: { params: { path: string[] } }) {
  return handler(req, params.path.join('/'));
}
export async function DELETE(req: Request, { params }: { params: { path: string[] } }) {
  return handler(req, params.path.join('/'));
}

clientFetcher 에서도 원래는 backend 로 바로보냈지만, bff를 경유하게끔 변경해야한다.

// 클라이언트 전용 fetcher (쿠키는 자동 포함)
import { SessionExpiredError } from '@/libs/error/errors';

export const clientFetcher = async <T = any>(
  path: string,
  options: RequestInit = {},
): Promise<T> => {
  // BFF 경유
  const finalUrl = `/api/bff${path}`;

  const res = await fetch(finalUrl, {
    ...options,
    credentials: 'include',
    headers: {
      Accept: 'application/json',
      ...(options.headers || {}),
    },
  });

  // BFF가 refresh 실패 시 401을 그대로 내려줌
  if (res.status === 401) {
    console.log('refresh 실패했습니다.');
    throw new SessionExpiredError();
  }

  const json: any = await res.json().catch(() => ({}));

  if (!res.ok || json?.success === false) {
    throw new Error(json?.message || '요청 실패');
  }

  return json.data;

};

---

회고

이번 경험을 통해 배운 점은 토큰 저장 위치가 인증 구조의 안전성과 유지보수성을 좌우한다는 점이다. 다시 accessToken, refreshToken 인증 방식에 대해서 공부해봤다.

1) AccessToken은 메모리 / RefreshToken은 HttpOnly 쿠키

• 인증 성공 시:
  • accessToken은 응답 본문 (body)으로 내려주고, 클라이언트 앱은 이를 메모리(예: 상태관리 스토어)로 저장한다.
  • refreshToken은 서버에서 Set-Cookie로 HttpOnly, Secure, SameSite 속성을 지정해 쿠키로 내려준다.
• 요청 시:
  • API 요청은 Authorization 헤더에 Bearer accessToken을 붙인다 (메모리에서 꺼내서)
• 토큰 만료 시:
  • accessToken 유효기간이 끝나면, 클라이언트가 refresh 요청을 보낸다 (브라우저가 자동으로 쿠키의 refreshToken을 전송).
  • 서버가 refreshToken을 검증하고 accessToken + (옵션으로) 새로운 refreshToken을 응답 + Set-Cookie로 갱신.

이 패턴의 장점으로는 accessToken이 노출되는 범위가 제한되고 refreshToken은 HttpOnly 쿠키로 보호된다. CSRF 위험은 refresh 호출 엔드포인트만 조심하면 된다 (그리고 SameSite, CSRF 토큰 등을 활용)
하지만 이 방식에서는 페이지 새로고침 시 accessToken이 사라지므로, 클라이언트가 초기 마운트 시 /me 호출 → 에러 → refresh 시도 → 복구 로직을 둬야 한다. refresh 요청을 반드시 브라우저가 직접 보내야 쿠키 갱신이 가능하다.

2) 둘 다 HttpOnly 쿠키

• accessToken과 refreshToken을 둘 다 HttpOnly 쿠키로 설정
• API 서버 또는 BFF가 쿠키 기반으로 인증 검증 / 갱신 흐름을 다룸
• 클라이언트는 Authorization 헤더를 직접 설정할 필요 없으며, credentials 포함 fetch로 요청만 하면 됨
• 장점:
  • JS에서 전혀 토큰을 읽을 수 없음 → XSS 공격에 대한 방어력 상승.
  • 클라이언트 로직 단순 (Authorization 헤더 붙이는 로직이 없음).
• 단점 / 주의사항:
  • 쿠키가 자동 전송되기 때문에 CSRF 공격 가능성 있음 → SameSite, CSRF 토큰, 경로 제한 등을 잘 구성해야 함.
  • 일부 요청에서는 명시적 Authorization 헤더를 써야 하는 경우가 있을 때 유연성이 떨어질 수 있음
  • refreshToken이 모든 요청 쿠키와 함께 전송되는 걸 막고 싶으면, refreshToken 쿠키에 Path=/refresh 같은 제한을 둘 수 있다는 제안도 있음

---

출처

• https://olrlobt.tistory.com/98
• https://homebody-coder.tistory.com/entry/React-Query%EC%9D%98-Prefetch%EB%9E%80
• https://velog.io/@clydehan/Next.js%EB%A1%9C-Access-Token-%EB%A7%8C%EB%A3%8C-%ED%99%95%EC%9D%B8-%EB%B0%8F-%EC%9E%AC%EB%B0%9C%EA%B8%89-%EB%B0%9B%EA%B8%B0
• https://velog.io/@clydehan/%ED%94%84%EB%A1%A0%ED%8A%B8%EC%97%94%EB%93%9C-%EB%A1%9C%EA%B7%B8%EC%9D%B8-%EB%B0%A9%EC%8B%9D-%EC%84%B8%EC%85%98-%ED%86%A0%ED%81%B0-%EA%B7%B8%EB%A6%AC%EA%B3%A0-JWT#3-access-token--refresh-token