[npm Deep Dive] 실제 사고 사례로 알아보는 유의적 버전 관리의 중요성

위키북스의 npm Deep Dive 완독 챌린지 1일차! 출판 소식 보자마자 너무 갖고 싶었던 책인데, 비싸고 저 두꺼운걸 언제 다보나 해서 망설이던 차에 챌린지에 참여하면 완독할 수 있지 않을까 싶어서 신청했다.

 

오늘의 Mission

- 1.1 npm의 정의와 역사 (~p.20)
- 1.2 유의적 버전이란? (~p.52)

👉나에게 npm이란

먼저 책을 읽기전에 나에게 npm은 어떤 존재일까 생각해보았다. 프론트엔드 개발을 시작한지 2년 정도가 되었고, 지금까지 무수하게 많은 npm install, npm start, npm run dev를 쳐왔지만 그냥 개발에 필요한 패키지를 설치할 수 있게 하는 것, 그정도로만 인식하고 있었다. npm이든 pnpm이든 yarn이든 프로젝트를 만들면 당연히 쓰는 것. 너무 익숙하고 당연해서 더 알아볼 필요성을 느끼지 못했다.

 

npm 시스템에 대한 의문, 보다도 개 깊은 빡침을 느낀 것은 express를 사용하기 시작하면서부터였다. commonJS, ESModule...단순한 import, require 구문들이 오류의 원인이 되었고, 테스트 환경마다 모듈 방식이 달라 오류가 나는걸 반복하다보니 내가 모듈 시스템, 나아가 npm에 대해 아는게 없구나 깨달았다. package.json만 두시간 수정하다보니 모듈 시스템과 npm에 대한 본격적인 관심이 생겼고, 당연하게 여겨졌던 npm이라는 것이 내가 개발자가 되기 위해 알아야 할 기반 기술로 다가온 것 같다. 그리고 마침, 관심이 막 피어나던 차에 npm deep dive가 출시됨 destiny

 

사족이 많았지만 정리해보자면 나에게 npm은 그냥 npm이다. 존재 자체가 너무 당연해서 굳이 뭘 더 알고자 할 필요도 없었던 것이다. 하지만 이번 기회를 통해, 당연함을 이해의 영역으로 확장해보려고 한다. 제대로 공부해서 모듈 따위에게 지지 않는 사람이 될거야..

 

📦npm 

npm은 전 세계 자바스크립트 개발자가 공통으로 사용하는 패키지 관리 시스템이자 CLI 도구

npm을 사용하여 전 세계에서 업로드된 자바스크립트 패키지를 손쉽게 설치하고 업데이트하여 프로젝트 의존성을 효율적으로 관리할 수 있다.

 

npm은 node package manager다? 

지나가는 개발자를 붙잡고 npm이 뭔지 아세요? 라고 한다면 대부분 node package manager이라고 할 것이다. 나도 오늘 이 책을 읽기 전에는 node package manager이라고 알고 있었다. 그리고 인터넷에 npm을 검색해보면 대부분의 자료나 블로그에서도 node package manager이라고 설명하고 있다. 하지만 진실은 조금 다르다.

 

npm은 본래 pm라는 bash 유틸에서 출발한 프로젝트이다. pm은 pkgmakeinst(package make install)라는 bash 함수의 축약어이고, 다양한 플랫폼에서 여러 패키지를 설치하는 기능을 했다고 한다.

 

 npm은 이를 계승한 도구이기 때문에, 굳이 약어로 보자면 "node pm"또는 "new pm" 정도의 의미로 쓰일수도 있지만, 공식적으로는 아래처럼 설명한다.

 

npm 이름에 대한 공식 Q&A

Q: "npm"은 "Node package Manager"의 약자인가요?
A: 많은 사람들이 그렇게 생각하지만, 실제로 npm은 "Node Package Manager"의 약자가 아닙니다. 오히려 "npm is not an acronym(npm은 약자가 아니다)"이라는 재귀적 백크로님(bacronym, 사후적으로 붙힌 약자)에서 나온 이름입니다. 만약 이 프로젝트 이름이 ninaa라면 진짜 약자가 되었을 것입니다. 

npm의 전신은 pm이라는 bash 유틸리티였는데, 이는 다양한 플랫폼에서 여러 가지를 설치하는 pkgmakeinst라는 bash 함수의 축약형 이름이었습니다. 만약 npm을 억지로 약자로 본다면, "node pm"또는 "new pm" 정도가 될 수 있습니다. 

 

즉, 이름 자체는 의미 없는 문자열로 봐야 한다는 것이 공식의 입장인 것 같다. 

 

 

npm의 주요 기능

npm은 프로젝트 의존성 설치 외에도 다양한 기능을 제공하여 개발 생산성을 높이고 프로젝트 관리 효율성을 극대화할 수 있게 한다.

• 패키지 설치 및 관리: package.json의 dependencies와 devDependencies에 선언된 패키지를 node_modules에 설지하여 Node.js 기반 패키지에서 사용할 수 있게 한다. 
• 패키지 배포 및 공유: npm 레지스트리에 자바스크립트 패키지를 업로드 할 수 있고, 또 설치하여 사용할 수 있다.
• 스크립트 실행: package.json의 scripts 필드를 통해 원하는 스크립트를 cli로 실행할 수 있다.
• 패키지 정보 확인: npmjs.com 사이트에서 패키지의 개요, 실제 코드, 의존성, 다운로드 수 등 전반적인 정보를 확인할 수 있다.

---

⭐유의적 버전 

오픈소스 소프트웨어는 매일같이 새로운 코드가 추가되고, 기능이 개선되며 발전한다. 이런 끊임없는 발전 속에서 패키지 버전을 어떻게 관리할 것인지에 대한 명확한 규칙이 없다면, 개발자들은 큰 혼란에 빠질 수밖에 없다.

 

패키지를 사용하는 입장에서 선택지는 크게 두 가지이다.

• ✅안정성을 위해 의존성을 고정
• 🔁항상 최신 패키지로 업데이트

하지만 이 두 가지 방식 모두 단점이 있다. 

의존성을 고정하면, 예측 가능한 환경은 유지할 수 있지만, 오픈소스의 발전을 반영하지 못한다. 항상 최신 버전을 유지하려고 한다면 예상치 못한 breaking change나 비효율적인 유지보수 작업에 시간과 에너지를 쏟아야 한다. 

 

💡이 문제를 해결하는 규칙이 바로, 유의적 버전이다. 

sementic versioning, semVer: 소프트웨어 버전이 의미를 가지도록 구성하는 표준

유의적 버전의 목적은 버전만 보고도 어떤 변화가 생겼는지 예측할 수 있도록 하는 것이다. 이를 통해 개발자는 보다 유연하고 안전하게 의존성 관리를 할 수 있다.

 

유의적 버전의 기본 구조

주, 부, 수(Major, Minor, Patch)

• 주: 호환되지 않는 API 변경이 있는 경우
• 부: 기능이 추가되었지만, 기존과 호환되는 경우
• 수: 버그 수정처럼, 기능에는 영향이 없고 호환성도 유지되는 경우

버전의 기본 구조를 약속하여, 버전 숫자만 보아도 패키지 업데이트 시 예상되는 위험도를 파악할 수 있다.

 

유의적 버전의 구체적 명세

https://semver.org/

Semantic Versioning 2.0.0

 

1. 공개 API 선언

유의적 버전을 사용하는 소프트웨어는 공개 API를 반드시 선언해야 한다. 이 API는 코드에 정의될 수도 있고, 오직 문서상으로 존재할 수도 있다. 어떤 방식이든 API는 정확하고 포괄적이어야 한다.

 

 

2. 버전 형식

일반 버전 번호는 반드시 주.부.수 (X.Y.Z) 형식을 따라야 하며, X, Y, Z는 0 이상의 정수이다. 숫자에는 선행 0이 있어서는 안 된다. 각 항목은 수치적으로 증가해야 한다. 예: 1.9.0 → 1.10.0 → 1.11.0

 

 

3. 버전 불변성

일단 버전이 릴리스되면, 해당 버전의 내용은 절대 수정할 수 없다.모든 변경 사항은 반드시 새로운 버전으로 릴리스
해야 한다.

 

4. 초기 개발 (주 버전 0)

0.y.z 형태의 버전은 초기 개발 단계를 의미한다.이 단계에서는 모든 것이 언제든지 변경될 수 있다.공개 API는 안정적이지 않다고 간주해야 한다.

 

5. 공개 API 정의 기준점

버전 1.0.0은 공개 API가 정의되었음을 의미한다. 그 이후의 버전 증분은 API의 변경 사항을 기반으로 결정된다.

 

6. 수 버전 증가 조건

수 버전 (x.y.Z, 단 x > 0)은 다음의 경우 반드시 증가해야 한다:
- API와 호환되는 버그 수정이 포함된 경우.여기서 버그 수정이란 잘못된 동작을 고치는 내부 변경을 의미한다.

 

7. 부 버전 증가 조건

부 버전 (x.Y.z, 단 x > 0)은 다음의 경우 반드시 증가해야 한다:
- API에 호환되는 기능이 새로 추가된 경우
- 공개 API의 일부가 deprecated(사용 중단 예정) 으로 표시된 경우

다음의 경우에는 증가할 수 있다(MAY):
- 내부 코드에 의미 있는 기능 추가나 개선이 있는 경우

부 버전 증가 시 수 버전은 0으로 초기화해야 한다.

 

8. 주 버전 증가 조건

주 버전 (X.y.z, 단 X > 0)은 다음의 경우 반드시 증가해야 한다:
- API에 호환되지 않는 변경이 발생한 경우

또한 다음을 포함할 수 있다:
- 부 및 수 수준의 변경

주 버전 증가 시 부와 수 버전은 0으로 초기화해야 한다.

 

 

9. 프리릴리스 버전

프리릴리스(pre-release) 버전은 수 버전 뒤에 하이픈(-) 을 붙이고, 점(.)으로 구분된 식별자 시퀀스를 추가하여 표현한다.
이 식별자는 ASCII 영숫자 및 하이픈([0-9A-Za-z-])만 포함해야 하며, 비어 있을 수 없다. 숫자 식별자는 선행 0을 포함할 수 없다. 프리릴리스 버전은 일반 버전보다 낮은 우선순위를 가진다. 이는 해당 버전이 불안정하며, 일반 버전이 보장하는 호환성을 충족하지 않을 수 있음을 나타낸다.

예시:1.0.0-alpha,1.0.0-alpha.11.0.0-0.3.71.0.0-x.7.z.921.0.0-x-y-z.--

 

 

10. 빌드 메타데이터

빌드 메타데이터는 수 또는 프리릴리스 버전 뒤에 플러스 기호(+) 와 점(.)으로 구분된 식별자 시퀀스를 추가하여 표현할 수 있다. 식별자는 ASCII 영숫자 및 하이픈만 사용할 수 있으며, 비어 있어서는 안 된다. 빌드 메타데이터는 버전 우선순위 계산에서 무시된다. 즉, 빌드 메타데이터만 다른 두 버전은 동일한 우선순위를 가진다.

예시: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f851.0.0+21AF26D3----117B344092BD

 

11. 우선순위 규칙

버전 간의 우선순위(Precedence) 는 정렬 기준에 따라 비교된다.우선순위 계산 시 버전은 다음 순서로 분해하여 비교한다:주 → 부 → 수 → 프리릴리스빌드

메타데이터는 비교 대상이 아니다.
- 주, 부, 수는 항상 숫자적으로 비교한다. 예시:1.0.0 < 2.0.0 < 2.1.0 < 2.1.1
- 주, 부, 수가 같을 경우, 프리릴리스 버전은 일반 버전보다 우선순위가 낮다.예시:1.0.0-alpha < 1.0.0
- 동일한 주, 부, 수 버전의 두 프리릴리스 버전은 식별자를 왼쪽부터 차례로 비교하여 첫 차이가 나는 부분에서 순서를 정한다.
   - 모두 숫자인 경우: 숫자적으로 비교
   - 문자가 포함된 경우: ASCII 사전순 비교
   - 숫자 식별자는 문자 식별자보다 항상 낮다
   - 앞의 식별자가 모두 동일한 경우, 식별자 개수가 더 많은 쪽이 더 높은 우선순위

예시:1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0

 

 

유의적 버전을 정확하게 매칭하는 정규식은 다음과 같다. 하지만 보통의 자바스크립트 프로젝트에서는 정규표현식을 직접 사용하기보단 semver 패키지를 사용한다.

^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9A-Za-z-][0-9A-Za-z-]*))*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$

 

💡유의적 버전은 명세이자 규칙이지만, 이를 강제하는 기술적 장치는 존재하지 않는다. 따라서 이를 따를지 여부는 전적으로 개발자의 판단과 책임에 달려 있다.

 

유의적 버전 범위 연산자

npm에서 의존성 버전 범위를 지정할 때 자주 사용하는 버전 범위 연산자들이다. package.json의 depedencies안에서 버전을 지정할 때 함께 사용한다. 앞으로 쓸 유의적 버전 사고사를 이해하는데도 필수적인 연산자들이다. 

 

연산자	의미	예시	설치 가능한 범위
^	최대한 최신 버전 허용 (MAJOR 고정)	^1.2.3	>=1.2.3 <2.0.0
~	패치 버전만 자유롭게 업데이트 (MINOR 고정)	~1.2.3	>=1.2.3 <1.3.0
>=	이 버전 이상	>=1.2.3	1.2.3 이상
<=	이 버전 이하	<=1.2.3	1.2.3 이하
>	초과 버전만 허용	>1.2.3	1.2.4 이상
<	미만 버전만 허용	<1.2.3	1.2.2 이하
- (범위)	버전 범위 지정	1.2.3 - 1.5.0	>=1.2.3 <=1.5.0
*	모든 버전 허용	*	모든 버전 가능
빈 문자열	최신 안정 버전 사용	""	npm install 시 최신 버전

 

유의적 버전 사고사례

유의적 버전은 명문화된 규칙일 뿐이며, 이를 위반하더라도 이를 제한하거나 차단할 수 있는 수단은 존재하지 않는다. 결과적으로 이 규칙 준수 여부는 전적으로 개발자의 판단과 관리에 의존하게 된다.

 

많은 오픈소스 프로젝트와 라이브러리에서 유의적 버전은 필수적인 버전 관리 방식으로 자리잡았지만, 예외없이 완벽하게 지켜지는 것은 아니다. 실제로 npm 생태계에는 유의적 버전 관리의 허점으로 인한 예상치 못한 의존성 충돌이나 업데이트 오류가 발생한 사례들이 존재한다. 

 

left-pad: 11줄 패키지가 만든 대혼란

2016년, 자바스크립트 생태계에서 믿기 힘든 일이 벌어졌다. left-pad라는 이름의 npm 패키지가 삭제되면서 수많은 빌드가 깨지고, 전 세계 자바스크립트 생태계가 잠시 마비되는 사태가 발생한 것이다.

 

left-pad는 문자열 왼쪽에 지정한 길이만큼 문자(주로 공백 또는 0)을 채워주는 기능을 가진 단 11줄짜리 유틸리티 패키지였다. 기능은 단순했지만, 문제는 이 패키지를 의존하고 있는 곳이 너무 많았다는 점이다.

 

대표적으로 유명 유틸리티 패키지 line-numbers가 left-pad를 사용하고 있었고, line-numbers는 Babel의 하위 패키지 중 하나인 babel-core-frame에서 사용되고 있었다. 

left-pad의 개발자는 kik이라는 새로운 패키지를 npm에 등록했다. 그러나 "kik"이라는 매신저 서비스를 운영하는 Kik사로부터 회사의 이름을 사용하지 말라는 요청을 받았는데, 이 메일이 꽤나 정말 많이 아주 불쾌했고, 이 와중에 npm마저 kik 측의 손을 들어준 터라 이에 대응하기 위해 개발자는 자신의 모든 패키지를 npm에서 삭제했다. 이 중에는 left-pad도 포함되어 있었다. 그리고 이 순간부터 left-pad를 의존하는 패키지, 빌드 툴들이 연쇄적으로 영향을 받아, 자바스크립트 생태계 전반이 마비가 되었다.

 

사건의 전말

Kik, Left-Pad, and NPM — Oh My!

 

이 사건을 계기로 npm은 패키지 삭제에 대한 까다로운 정책을 도입했다.

1. 의존성이 존재하는 패키지의 삭제 제한
2. 유명 패키지가 삭제될 경우 악의적인 사용자가 같은 이름으로 가짜 패키지를 업로드하는 것을 방지하기 위한 security-holder 패키지 추가

문제를 해결하기 위한 정책이었지만,,,,슬프게도 또 다른 문제를 야기하게 된다. 

 

left-pad를 복구하여 문제를 해결했으나 이 사건은 정말 많은 점들을 시사한다. 문제의 본질은 단순하다. kik사의 메일이 조금만 더 정중했더라면, npm이 개발자의 손을 들어주었다면-이라는 if도 가능하지만, 근본적으로는 "작고 단순한 기능도 직접 구현하기보다는 패키지로 가져다 쓰는 관행"이 문제가 된 것이다. npm 생태계에서는 직접 설치한 패키지 뿐 아니라, 그 패키지가 의존하는 패키지의 의존 패키지까지 자동으로 설치된다. 이런 깊은 의존 체인 속에서, 근간이 되는 단 하나의, 11줄짜리 단순한 패키지가 삭제되었을 분인데도 전체 시스템이 연쇄적으로 마비되어버린 것이다. 

 

everything: npm 삭제 버튼 압수 사건

left-pad 사건 이후, npm은 의존성이 존재하는 패키지에 대한 삭제를 제한하는 정책을 도입했다. 이는 중요한 패키지가 예기치 않게 삭제되어 생태계 전체가 흔들리는 것을 방지하기 위한 장치였다. 하지만 이 정책은 새로운 허점을 만들어냈다.

 

만약 모든 패키지를 의존성으로 등록한다면...?

 

이런 개쩌는 발상을 한 개발자가 있었고, 실제로 시도까지 했고, 심지어 성공했다.

 

everything 패키지는 npm에 존재하는 거의 모든 패키지를 의존성으로 설정한 후 배포되었고, 심지어 버전을 *로 설정하여 해당 패키지의 모든 버전이 의존되는 구조를 만들어냈다. everthing 패키지가 존재하는 한, 대부분의 패키지가 삭제가 불가능하게 되는 상황이 벌어진 것이다.

 

장난스러운 시도였으나, npm이 의존성 삭제 제한 정책을 무조건적으로 적용한 결과가 어떤 문제를 야기할 수 있는지 정확하게 짚어낸 셈이 되었다. npm 생태계가 얼마나 중앙화된 구조에 의존하고 있는지를 적나라하게 보여준 사례이다.

 

event-stream: npm은 안전한가

2018년 인기 스트림 유틸리티 패키지 event-stream에 악성코드가 심어진 사건이 발생했다.

 

event-stream은 Node.js에서 비동기 스트림 처리를 쉽게 만들어주는 유명 유틸리티 패키지로, 수많은 오픈소스 프로젝트가 직간접적으로 의존하는 인기 패키지였다. 

 

event-stream의 최초 개발자는 몇 년간 유지보수를 진행하지 않았는데, 어느 날 한 개발자가 유지보수를 이어가겠다는 의사를 밝혔다. 원 개발자는 이를 수락하고 소유권을 양도했다.

 

양도받은 개발자는 새로운 버전에서 flatmap-streamd이라는 패키지를 의존성으로 추가했는데, 이 flatmap-stream 내부에 암호화된 백도어 코드가 포함되어 있어서 문제가 되었다. event-stream 자체에는 아무 문제 없어 보였지만, 수많은 프로젝트에서 비트코인 탈취 코드가 포함된 패키지를 간접적으로 의존하게 된 것이다. 

 

대부분의 패키지가 ^, ~에 의존하는 것을 노린 악의적인 행위였다. 의도적으로 수 버전을 업데이트하여 자동 설치를 유도했으며, 자동으로 업데이트된 패키지를 사용하게 되어 탈취 코드에 노출된 것이다. npm 패키지 생태계에서 신뢰가 어떻게 보안 위협으로 바뀔 수 있는지, 유의적 버전관리 규칙이 어떻게 악용될 수 잇는지 보여준 단적인 예이다.

---

책에서는 이보다 더 많은 사례들을 소개하고 있지만, 특히 인상 깊었던 사례들만 정리해보앗다. 일부 사건은 유의적 버전 그 자체보다는 npm 생태계의 구조적 취약점에서 비롯된 문제처럼 보이기도 하지만, 결국 명세일 뿐인 유의적 버전 규칙이 강제력을 가지지 않는 현실, 그리고 이를 악용하거나 무시했을 때 얼마나 큰 파장이 생길 수 있는지 보여주는 대표적인 예시들이었다.

 

이러한 사례들을 통해, 개발자 개인의 책임에 대해서 다시 한번 생각해보게된 것 같다.

 

안전하게 npm 쓰기

위에서 봤듯, 모든 개발자가 유의적 버전을 엄격히 따르는 것은 아니며, 때로는 이를 악용하는 경우까지 존재한다. 그렇기 때문에 새로운 패키지를 도입하거나 기존 패키지를 업데이트 할 때는 반드시 주의 깊게 검토하는 습관이 필요하다. 

 

md 파일, 릴리스 노트를 꼼꼼히 살펴보고, 호환성이나 보안 측면에서 문제가 없는지를 스스로 점검해야 한다.

 

또한 패키지를 어디까지, 어떤 기준으로 사용할지에 대한 고민을 해보는 것도 중요하다. 자바스크립트 생태계에서는 left-pad처럼 극히 단순한 기능조차 패키지로 분리되어 유통되는 일이 흔하다. 자바스크립트의 장점이기도 하지만, 곧 불필요한 의존성과 보안 위협의 가능성을 높일 수 있다. 따라서 패캐지를 도입하기 전, 먼저 생각을 해보자.  

• 이 패키지는 정말로 대체 불가능한가? 
• 충분히 검증된 커뮤니티 신뢰도와 유지 관리 기록을 가지고 있는가?
• 의존성 트리가 납득 가능한 수준인지, 과도하게 또는 수상하게 얽혀있지는 않은가? 

패키지를 배포하는 것도, 사용하는 것도 개발자 개인의 책임이다. 개발자의 무심함이 오픈소스를 사용하는 다른 개발자들, 나아가 최종 사용자에게까지 피해를 줄 수 있다. 따라서 무심코 가져다 쓰기보다는 선택이 가져올 영향과 리스크를 충분히 고려할 수 있는 개발자가 되어야 한다.

 

---

유용한 사이트

 

npm

npm | Home

 

Bundlephobia-패키지 크기 정보 확인

Bundlephobia | Size of npm dependencies

 

npm trends

unpkg

UNPKG

snyk

Snyk AI-powered Developer Security Platform | AI-powered AppSec Tool & Security Platform | Snyk