npm의 checksum과 integrity checksum(EINTEGRITY) 오류 해결 방법

TLDR : 서버 패치 or 캐시 and package-lock.json 초기화

사내 nexus repository에 npm 패키지를 배포하고 다운받아 install 하는데 계속 checksum 오류가 발생하였습니다.

(turborepo + pnpm 환경)

따라서 아래 링크와 같은 방법으로 해결했는데, 문제의 근본 원인과 checksum에 대한 궁금증이 생겨 리서치를 진행해 보았습니다.

https://github.com/pnpm/pnpm/issues/1230

integrity checksum failed when using sha1 · Issue #1230 · pnpm/pnpm

pnpm 사용 시 해결 방법은 pnpm-lock과 pnpm-store를 날려버린 뒤 다시 install 하는 것입니다.

rm -rf pnpm-lock.yaml
Path=pnpm store path
rm -rf $path
pnpm install

cache와 같은 역할을 하는 pnpm store

위와 같이 가장 간단한 모든 체크섬 무결성 오류 해결 방법은

클라이언트 측에서 캐시를 날려버리는 것입니다.

package-lock은 알겠는데 캐시는 왜?
package-lock checksum과 cache의 checksum이 충돌할 수 있습니다.

즉, cache가 stale하거나, package-lock이 stale함이 원인입니다.

항상 최신 패키지가 퍼블리시 되는 서버가 stale하진 않겠죠...

EINTEGRITY err 발생 원인 = 해시 불일치

# Solution for all npm ERR! code EINTEGRITY errors 🙏
$ cd <project_directory>
$ rm -rf package-lock.json npm-shrinkwrap.json node_modules
$ npm cache clean --force
$ npm cache verify
$ npm install

이러한 체크섬 오류의 근본 원인은 다음과 같습니다.

1. 네트워크 오류
   • 네트워크 지연, 패킷 손실, 캐시 오류
2. 버전 오류
   1. 버전, 패키지 명을 동일하게 업데이트
   2. 사내 레포지토리에 버전에 해당하는 파일을 잘못 올림
3. 보안 오류
   • 레포지토리가 실제로 해킹당해서 코드가 변경됨
     • 물론 이런 가능성은 매우 낮음

제가 마주친 케이스의 경우 원인은 2.1이었고, 저희 쪽에서 조치할 수 없는 사항이었으므로, 캐시 초기화를 진행하였습니다.

위와 같이 클라이언트, 서버에 걸쳐 다양한 원인이 있으므로, 상황에 따라 적절한 조치를 취해야 합니다.

---

그런데, 체크섬은 어떻게 동작하는 걸까요?

package.json 파일은 npm install 명령으로 설치한 최상위 npm 패키지를

프로젝트의 NPM 패키지 이름 및 버전 태그로 추적합니다.

 

package-lock.json 파일은 정확한 버전 참조를 추적합니다.

실제로 다운로드된 node_modules 디렉토리에 저장된 최상위 패키지와

하위 패키지 모두에 대한 종속성 트리가 완성됩니다.

 

바이트 수준 콘텐츠 불일치, 데이터 손상, 악의적인 콘텐츠 조작을 방지하고

다운로드한 모든 패키지의 데이터 무결성을 일관되게 유지하기 위해

package-lock.json 파일에는 다운로드된 모든 객체의 SHA-512 체크섬 값도 포함됩니다.

npm install 때마다 NPM은 파일에 저장된 이러한 체크섬 값과 다운로드한 패키지 객체의 체크섬 값을 비교하고 확인합니다.

 

이러한 npm 패키지 내부의 콘텐츠가 원격 레포지토리와 로컬 레포지토리 간에 다르다면(의도적/비의도적 시도로 인해)

해당 체크섬 값도 달라지며

npm 패키지 무결성 오류가 발생합니다.

 

 

이 오류는 몇 가지 근본 원인으로 인해 발생할 수 있습니다.

때때로 명확한 이유를 찾아낼 수 있지만,

대부분의 경우 다운로드 실패한 종속성의 패키지 작성자 또는 네트워크 담당자에게 연락하여 근본 원인을 명확히 해야 합니다.

몇 가지 가능한 시나리오가 있습니다.

---

1. integrity checksum failed when using sha512 ... but got sha512

전체 에러(키워드 : tarball)

npm WARN tarball tarball data for <package_name>@<package_version> (sha512-<long_hash_1>) seems to be corrupted. Trying one more time.
npm ERR! code EINTEGRITY
npm ERR! Verification failed while extracting <package_name>@<package_version>
npm ERR! Verification failed while extracting <package_name>@<package_version>
npm ERR! sha512-<long_hash_1> integrity checksum failed when using sha512-<long_hash_1> but got sha512-<long_hash_2> (<number> bytes)

npm ERR! A complete log of this run can be found in:
npm ERR!     <npm_debug_log_file_location>​

 

 

에러 의미

• 명백히 이전 객체와 새 객체의 체크섬 값이 다릅니다.
  • 즉, 패키지 이름과 버전 태그가 변경되지 않았더라도 내용이 변경되었습니다.
  • 이러한 타입의 콘텐츠 변경에는 위험도 수반되므로 근본 원인을 조사해야 합니다.

가능한 원인

• 프록시 서버, 중간 캐시 또는 대상 NPM 레지스트리는 잘못된 패키지 객체를 포함할 수 있습니다.
  • 데이터 손상
  • 네트워크 패킷 손실
  • 잘못된 패키지 재빌드
  • 해킹에 의한 패키지 조작
  • 노드/npm 버그 및 많은 유사한 시나리오
•  패키지 작성자가 대상 NPM 레지스트리에서 현재 패키지의 게시를 취소하고 일부 콘텐츠를 변경한 다음 동일한 버전 태그로 다시 게시하였습니다.
  • 버전 태그가 변경되지 않았더라도 콘텐츠가 변경된 이후 새 체크섬 값이 생성됩니다.
  • 이는 사설 개발 환경에서 종종 발생할 수 있지만 오픈 소스 세계에서는 거의 발생하지 않습니다.

2. integrity checksum failed when using sha1: wanted sha1 ... but got sha512

전체 에러

npm WARN registry Unexpected warning for https://registry.npmjs.org/: Miscellaneous Warning EINTEGRITY: sha1-<long_hash_1> integrity checksum failed when using sha1: wanted sha1-<long_hash_1> but got sha512-<long_hash_2> (<number> bytes)

 

에러 의미

• NPM 프로세스는 sha1 기반 체크섬을 예상하였지만, sha512 기반 체크섬을 받았습니다(둘 다 악의적인 변경으로부터 안전한 암호화 해시 함수임).

가능한 원인

• package-lock.json 파일이 sha512를 사용하는 최신 NPM 버전에서 생성되었습니다.
  • 당신의 NPM 버전이 오래되어 sha1을 사용하고 있습니다.

참고: 과거에는 체크섬 생성을 위해 NPM에서 SHA1을 사용했습니다.

sha512 방법은 sha1보다 새롭고 더 좋습니다.

최신 NPM은 이제 sha512 방법을 사용합니다.

맨 위의 솔루션을 적용하여 이 오류를 수정할 수 있지만

npm i -g npm을 통해 로컬 NPM 버전을 업데이트하고 모든 곳에서 sha512를 사용하는 것이 좋습니다.

 

3. integrity checksum failed when using sha512: wanted sha512 ... but got sha

전체 에러

npm WARN registry Unexpected warning for https://registry.npmjs.org/: Miscellaneous Warning EINTEGRITY: sha512-<long_hash_1> integrity checksum failed when using sha512: wanted sha512-<long_hash_1> but got sha1-<long_hash_2> (<number> bytes)

에러 의미

• NPM 프로세스는 sha512 기반 체크섬을 예상하지만 sha1 기반 체크섬을 수신했습니다(즉, 2의 시나리오와 정반대).

가능한 원인:

• package-lock.json 파일이 sha1을 사용하는 이전 NPM 버전에서 생성되었습니다.
  • 당신의 NPM 버전이 최신이며 sha512를 사용하고 있습니다.

참고: #2에서 언급한 것처럼 이 문제는 NPM 체크섬 계산 방법의 불일치로 인해 발생했습니다.

위의 솔루션을 적용하여 이 오류를 수정할 수 있지만,

npm i -g npm을 통해 리모트 레포지토리의 NPM 버전을 업데이트하고 모든 곳에서 sha512를 사용하는 것이 좋습니다.

 

 

4. npm ERR! shasum check failed for ... npm ERR! Expected: ... npm ERR! Actual: ...

전체 에러

npm ERR! shasum check failed for <local_file_location>
npm ERR! Expected: <long_hash_1>
npm ERR! Actual: <long_hash_2>  
npm ERR! From:  <remote_file_location>

에러 의미

• 이번에도 새로 다운로드하는 개체와 package-lock.json 파일에 언급된 개체의 체크섬 값이 일치하지 않습니다.

가능한 원인

• #1에서 언급한 것과 동일한 이유로 인해 발생할 수 있습니다.

참고

https://platformengineer.com/fix-npm-err-code-eintegrity-verification-failed-error/

[SOLVED] Fix npm ERR! code EINTEGRITY, integrity checksum failed, tarball data seems to be corrupted, npm ERR! shasum check fail