Node.js 운영 보안(Security) 설정 기준¶

운영 서버(Production Server) 환경에서 Node.js + Express 기반 서비스의
인증 / 인가 / 요청 보호 / 운영 차단 전략에 대한 기준을 정리한 문서임.

“보안 기능 나열”이 아니라,
실제 운영 서버에서 사용 중인 보안 패키지들을 어떻게 안전하게 운용할 것인가에 초점을 둠.

1. 기본 원칙¶

보안은 기능이 아니라 운영 기준임
“일단 막자” 식의 미들웨어 추가는 장애의 원인이 됨
운영 서버에서는:
- 명확한 책임 경계
- 예측 가능한 요청 흐름
- 장애 시 원인 추적 가능성 이 보안의 핵심임
보안 관련 패키지 역시 /home/[User]/[ProjectName] 또는 동등한 작업 경로에서 설치 후 배포함

⚠️ 중요
/var/www/[ProjectName]/current 경로에서 npm install 수행 ❌
보안 패키지도 예외 없이 /home/[User]/[ProjectName] 또는 동등한 작업 경로에서 설치 후 배포함

2. 설치 기준 (현재 운영 환경 기준)¶

다음 패키지들은 현재 streaum 서버에서 실제 사용 중인 보안 패키지들임.

설치 위치 / 주체¶

운영 사용자 계정
/home/[User]/[ProjectName] 또는 동등한 작업 경로

npm install jsonwebtoken cookie-parser express-jwt csurf cors --save

3. 패키지별 역할 및 운영 기준¶

3.1 jsonwebtoken (JWT Core)¶

npm install jsonwebtoken --save

역할¶

JWT 토큰 생성 / 검증의 핵심 라이브러리
서명 알고리즘, 만료 시간(exp) 직접 제어 가능

운영 기준¶

JWT payload에 민감 정보 절대 금지
- ❌ password
- ❌ email
- ❌ phone
- ❌ access level 세부 정보
payload에는 식별자 수준 정보만 포함

{
  user_id: 123,
  role: 'user'
}

만료 시간(exp) 필수
secret / private key는 환경 변수로만 관리

3.2 cookie-parser¶

npm install cookie-parser --save

역할¶

HTTP Cookie 파싱
JWT를 Cookie 기반으로 운용할 경우 필수

운영 기준¶

보안 옵션 없는 쿠키 사용 금지

res.cookie('token', jwt, {
    httpOnly: true,
    secure: true,
    sameSite: 'strict',
});

httpOnly 없는 토큰 쿠키는 XSS에 취약
secure 옵션 없는 운영 쿠키는 허용하지 않음

3.3 express-jwt (JWT 인증 미들웨어)¶

npm install express-jwt --save

역할¶

요청 단위 JWT 자동 검증 미들웨어

사용 배경 (히스토리)¶

다수의 API에 대해 일괄 인증 처리가 필요했던 구조
직접 jsonwebtoken.verify()를 매번 호출하는 코드 중복 제거 목적

운영 주의사항¶

미들웨어 실패 시 요청 전체 차단
에러 메시지 커스터마이징이 어려움
디버깅 시 스택 추적이 불편함

⚠️ 결론
express-jwt는 “편의용” 도구이며,
복잡한 인증 로직에서는 jsonwebtoken 직접 검증 방식이 더 명확함.

3.4 cors (Cross-Origin Resource Sharing)¶

npm install cors --save

역할¶

브라우저 기반 요청의 출처 제어

운영 기준¶

origin: "*" 운영 서버에서 금지

cors({
    origin: [
        'https://service.example.com',
    ],
    credentials: true,
});

credentials 사용 시:
- Access-Control-Allow-Origin: * ❌
- 반드시 명시적 origin 지정

3.5 csurf (CSRF 보호)¶

npm install csurf --save

역할¶

CSRF(Cross Site Request Forgery) 방어

사용 배경 (히스토리)¶

Cookie 기반 인증 구조
브라우저 직접 요청 위주 서비스
서버 렌더링 페이지 + 폼 전송 구조

운영 주의사항¶

SPA + JSON API 구조에서는:
- 토큰 불일치로 인한 장애 발생 빈번
- 프록시 / 로드밸런서 환경에서 오작동 가능성
잘못 적용 시 보안 강화가 아니라 서비스 장애가 됨

⚠️ 결론
csurf는 조건부 도구이며,
모든 API 서버에 무조건 적용하는 것은 금지함.

4. 운영 환경 차단 전략 (가장 중요한 보안)¶

보안 미들웨어보다 강력한 보안은 라우팅 차단임.

운영 서버에서 수행하는 차단¶

NODE_ENV === 'production' 인 경우
- /Utils/* 라우트 미등록
- /StreaumDocs/* 라우트 미등록
- 테스트 / 초기화 / 관리용 API 완전 차단

if (process.env.NODE_ENV !== 'production')
{
    router.use('/Utils', require('./Utils'));
}

이 방식은: - 인증 우회 가능성 ❌ - 토큰 탈취 ❌ - 실수로 호출되는 관리 API ❌

→ 아예 요청 경로 자체를 제거함

5. 절대 하지 말아야 할 것 (Do Not Do)¶

운영 서버에서 npm install 실행
JWT payload에 개인정보 저장
CORS * 허용
Cookie 옵션 없이 인증 토큰 저장
csurf를 “보안이니까” 무조건 적용
Production에서 테스트/관리 API 노출

6. 정리¶

보안은 라이브러리가 아니라 운영 설계
이미 사용 중인 보안 패키지라도:
- 왜 쓰는지
- 어디까지 쓰는지
- 언제 쓰지 말아야 하는지 를 문서로 남겨야 함
운영 서버에서 가장 강력한 보안은 차단임

streaum 서버에서 실제 사용 중인 보안 구조를 기준으로 작성된 운영 문서임