[npm][보안] provenance는 있는데 linked source repository를 찾을 수 없을 때 repository.url·repo visibility·삭제 이력을 어디부터 맞추나

IT 리서치 노트

[npm][보안] provenance는 있는데 linked source repository를 찾을 수 없을 때 repository.url·repo visibility·삭제 이력을 어디부터 맞추나

npm provenance 화면에 build summary와 ledger는 보이는데 linked source repository를 찾을 수 없다는 경고가 뜨면, 많은 팀이 registry 문제부터 의심한다. 2026년 7월 20일 KST 기준 npm 공식 문서를 다시 보면 이 경고는 source commit 또는 repository lookup 실패, 그리고 GitHub publish metadata 불일치와 더 가깝다. 이 글은 provenance는 있는데 linked source repository를 찾을 수 없을 때 무엇부터 다시 맞추는 편이 빠른지 정리한 것이다.

목차

1. 개요
2. 어디서 실제로 막히는가
3. 실무에서 적용하는 순서
4. 공식 문서와 예시 화면으로 확인하기
5. 주의사항과 리스크
6. 결론
7. 참고 링크

1. 개요

결론부터 말하면 linked source repository 경고는 provenance attestation이 없다는 뜻보다 source link를 더 이상 검증할 수 없다는 뜻에 가깝다. 먼저 문제가 난 정확한 버전, repository.url 정확성, 저장소 public/private 상태, 삭제 이력을 봐야 한다.

특히 npm trusted publishers 문서는 GitHub publish에서 repository.url이 실제 GitHub 저장소와 정확히 일치해야 한다고 적고 있다. rename, transfer, fork publish 이후 metadata를 안 고친 경우에는 provenance UI보다 package.json이 더 직접적인 원인이다.

2. 어디서 실제로 막히는가

현장에서 자주 생기는 오해는 세 가지다. 첫째, provenance warning이 뜨면 attestation 자체가 생성되지 않았다고 본다. 둘째, package가 public이니 source repo도 당연히 public일 것이라고 생각한다. 셋째, 저장소 rename이나 transfer 뒤에도 repository metadata가 자동으로 따라온다고 여긴다.

하지만 npm provenance 문서는 linked source commit 또는 repository를 찾을 수 없으면 provenance를 더 이상 establish할 수 없다고 분명히 적고 있다. trusted publishing 문서는 GitHub publish에 필요한 repository.url exact match까지 요구한다. 여기에 GitHub Packages 문서도 repository field가 실제 GitHub repository URL과 맞아야 한다고 덧붙인다.

즉 이 경고는 attestation 존재 여부와 source link 검증 가능성을 분리해서 봐야 하는 사건이다. CLI의 npm audit signatures가 통과하더라도 source repo가 private로 돌아가거나 metadata가 stale이면 웹 UI는 다른 경고를 낼 수 있다.

• 증상: provenance detail은 보이는데 source repository 경고가 함께 뜬다.
• 실패: registry attestation 실패와 source link lookup 실패를 같은 문제로 본다.
• 막힘: repository rename·transfer 후 package.json metadata를 다시 보지 않는다.
• 누락: source repo public/private 전환 또는 삭제 시각을 기록하지 않는다.

3. 실무에서 적용하는 순서

실무 점검은 다섯 단계가 가장 짧다. 먼저 경고가 난 정확한 package version을 적는다. 두 번째로 package.json의 repository.url과 실제 GitHub repo URL이 완전히 일치하는지 본다. 세 번째로 source repo와 source commit이 아직 public 접근 가능한지 본다. 네 번째로 publish workflow가 기대한 repo에서 실행됐는지 확인한다. 마지막으로 metadata를 고쳤다면 새 버전으로 다시 배포한다.

1. 문제가 난 버전을 먼저 고정한다.
2. repository.url exact match를 확인한다.
3. repo와 commit 접근성을 확인한다.
4. publish 경로와 workflow repo를 확인한다.
5. 필요하면 metadata 수정 후 새 버전을 배포한다.

핵심은 옛 버전을 직접 덮어쓰려 하지 않는 것이다. provenance나 source link 문제는 보통 이미 배포된 버전의 metadata와 당시 저장소 상태가 남긴 흔적이기 때문에, 수정은 다음 버전에서 명확히 남기는 편이 낫다.

npm view @scope/pkg version
npm pkg get repository.url
gh repo view ORG/REPO --json visibility,nameWithOwner

# compare the exact package version page with the repo URL and visibility

이 세 조회 결과를 같은 로그에 저장하고 같은 표에서 비교해야 한다. 버전, URL, visibility, publish workflow, provenance 경고 상태를 한 번에 비교하지 않으면 source link 오류와 단순 UI 지연을 자꾸 섞게 된다.

4. 공식 문서와 예시 화면으로 확인하기

첫 화면은 npm provenance 문서가 보여 주는 경고 예시다. provenance가 아예 없다는 뜻이 아니라, linked source repository나 source commit을 더 이상 확인할 수 없을 때 이런 경고가 뜬다는 점이 핵심이다.

npm provenance 문서는 linked source commit 또는 repository를 찾을 수 없을 때 provenance를 더 이상 establish할 수 없다고 경고한다.

이 문구를 보면 원인이 registry 서명 실패가 아니라 source link 검증 실패일 수 있다는 점이 드러난다. CLI 검증과 웹 UI 경고를 같은 문제로 묶으면 사고 지점이 약해진다.

두 번째 화면은 trusted publishing 문서의 정확한 조건이다. GitHub에서 publish할 때는 repository.url이 실제 GitHub 저장소와 정확히 일치해야 한다고 npm이 직접 적고 있다.

npm trusted publishers 문서는 GitHub publish에서 repository.url이 실제 GitHub 저장소와 정확히 일치해야 한다고 설명한다.

즉 저장소를 rename하거나 fork에서 publish한 뒤 package.json을 안 고치면 provenance 자체는 있어도 linked source repository 검증이 꼬일 수 있다. 이 경우 문제는 UI가 아니라 metadata다.

실무에서는 private 전환, 삭제, repository.url mismatch를 한 번에 구분하는 표가 필요하다. 세 경우 모두 비슷한 경고를 만들지만 대응은 서로 다르다.

linked source repository 경고의 대표 원인을 metadata, visibility, 삭제 이력으로 나눈 표다.

이미 version history와 visibility 이력 글이 버전 시간축을 다뤘다면, 이번 표는 단일 버전에서 source link 경고를 분리하는 운영판이다.

metadata mismatch는 실제 파일에서 더 빨리 보인다. 저장소를 옮긴 뒤 repository.url을 그대로 두면 publish path와 linked source lookup이 서로 다른 저장소를 가리킬 수 있다.

repository.url mismatch를 수정하는 package.json 예시다.

이 예시는 OIDC publish와 token fallback 글에서 본 publish path 점검과 잘 맞물린다. 이번엔 token이 아니라 source link를 바로잡는 단계다.

마지막 자료는 source link 경고 triage 순서다. provenance 화면을 새로고침하기 전에 metadata와 저장소 접근성을 먼저 보는 편이 시간을 덜 쓴다.

linked source repository 경고가 뜰 때의 점검 순서다.

이 순서를 release record에 붙여 두면 provenance 경고를 registry 장애와 구분하기 쉬워진다. 특히 package가 public인데 저장소만 private로 돌아간 팀에서 반복해서 유용하다.

5. 주의사항과 리스크

첫 번째 리스크는 저장소를 private로 바꿔 놓고 provenance UI 경고를 registry 지연으로 오해하는 것이다. 두 번째는 fork에서 publish하면서 repository.url을 원본 저장소로 남겨 두는 것이다. 세 번째는 문제 버전을 고치지 않고 UI 새로고침만 반복하는 것이다.

release record에는 최소한 version, repository.url, repo_visibility, publish_repo, publish_workflow, warning_seen를 남기는 편이 좋다. 그래야 단일 버전 provenance triage 글과 trusted publishing 절차 글을 운영 메모 안에서 바로 연결할 수 있다.

6. 결론

provenance는 있는데 linked source repository를 찾을 수 없을 때는 registry보다 먼저 metadata와 저장소 접근성을 봐야 한다. npm은 source repo와 commit을 다시 확인하고, trusted publishing은 repository.url의 exact match를 요구하므로, rename·transfer·private 전환 사건이 있으면 source link 경고가 자연스럽게 생길 수 있다.

같은 가지의 선행 글로는 audit signatures는 통과하지만 provenance UI가 비는 글, version history와 visibility 이력 글을 같이 보면 좋다.

오늘 기준 후속으로는 CLI verify 결과와 registry UI 경고를 어떤 로그 순서로 같이 남길지 정리한 글도 같이 보면 좋다. 이 글이 원인 축을 metadata와 접근성으로 좁혀 준다면, 후속 글은 릴리스 회고에 어떤 명령 결과와 어떤 UI 문구를 같은 줄에 기록할지까지 정리한다.

7. 참고 링크

1. https://docs.npmjs.com/viewing-package-provenance/
2. https://docs.npmjs.com/trusted-publishers/
3. https://docs.github.com/packages/working-with-a-github-packages-registry/working-with-the-npm-registry