[npm][보안] linked source recovery에서 repository.url exact match는 맞는데 visibility만 다를 때 어떤 재확인 순서가 가장 짧나

IT 리서치 노트

[npm][보안] linked source recovery에서 repository.url exact match는 맞는데 visibility만 다를 때 어떤 재확인 순서가 가장 짧나

npm package provenance에서 linked source recovery를 하다 보면 repository.url exact match는 이미 맞는데 package page 경고가 계속 남는 경우가 있다. 2026년 7월 28일 기준 npm 공식 문서를 다시 보면 이 구간은 문자열 일치 문제라기보다 public repository 조건, trusted publisher 설정 drift, 새 version의 provenance detail 재확인 순서 문제인 경우가 많다. 이 글은 repository URL은 통과했는데 visibility만 다른 상황에서 무엇부터 다시 보고 어떤 값이 정상으로 돌아와야 linked source 경고를 짧게 정리할 수 있는지 실무 순서로 정리한다.

목차

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

1. 개요

결론부터 말하면 repository.url exact match가 이미 맞는 상황에서 linked source 경고가 남으면 다음 순서는 visibility, trusted publisher, 새 version provenance detail, verify 결과다. repository URL을 다시 오래 붙잡기보다 현재 publish source repo가 public인지와 trusted publisher가 같은 repo와 workflow를 가리키는지 먼저 보면 시간이 훨씬 짧다.

즉 visibility mismatch는 metadata 재검사보다 provenance prerequisite 재확인에 가깝다. 이 순서를 고정해 두면 UI 경고 잔존과 실제 설정 회귀를 같은 사건으로 섞지 않게 된다.

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

현장에서 자주 꼬이는 지점은 네 가지다. 첫째, repository.url이 맞다는 사실을 확인하고도 다시 같은 값을 반복 점검한다. 둘째, 실제 publish source repo visibility가 private로 남아 있는데 package page UI만 본다. 셋째, trusted publisher 설정이 저장 시 검증되지 않는다는 점을 놓쳐 repo 또는 workflow drift를 같이 못 본다. 넷째, 새 version provenance detail 대신 이전 경고 버전 화면만 계속 새로고침한다.

npm 공식 문서는 provenance prerequisite를 분명히 적어 둔다. public repository가 provenance publish 위치와 case-sensitive하게 맞아야 하고, trusted publisher 설정은 저장 단계에서 검증되지 않는다. 즉 linked source 경고가 남을 때는 repository.url exact match 통과 여부보다 현재 publish source repo와 trusted publisher 정합성이 더 중요해진다.

이 문제를 UI 캐시로만 보면 recovery가 길어진다. 반대로 visibility와 trusted publisher를 먼저 점검하면 경고가 실제 설정 문제인지, 아니면 새 버전 페이지가 아직 반영되지 않은 것인지 훨씬 빨리 갈린다. recovery 순서가 곧 원인 분리 순서다.

• 증상: repository.url은 맞는데 linked source repository 경고가 남는다.
• 실패: visibility와 publish source를 안 보고 package.json만 반복 확인한다.
• 막힘: trusted publisher repo와 workflow filename drift를 같이 안 본다.
• 누락: 새 version provenance detail 대신 이전 경고 버전 페이지만 본다.

문제 층	먼저 보는 값	왜 중요한가
publish prerequisites	source repository visibility	public repository 조건이 안 맞으면 provenance 해석이 계속 흔들린다
trusted publisher drift	repository와 workflow filename	저장 시 검증되지 않아 stale config가 남기 쉽다
verification target	새 version provenance detail	경고가 과거 버전에 묶였는지, 현재도 재현되는지 구분한다

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

가장 짧은 재확인 순서는 다섯 단계다. 먼저 repository.url exact match는 이미 맞는지 확인만 하고 넘어간다. 다음으로 publish source repo visibility를 확인한다. 세 번째로 trusted publisher repository와 workflow filename을 조회한다. 네 번째로 고친 설정으로 새 version을 publish하고 provenance detail을 연다. 마지막으로 verify 결과와 package page 경고를 같이 저장해 UI 지연과 실제 drift를 분리한다.

1. repository.url exact match는 통과 여부만 확인한다.
2. source repository visibility를 확인한다.
3. trusted publisher repository와 workflow filename을 다시 본다.
4. 새 version provenance detail을 연다.
5. verify 결과와 package page 경고를 함께 저장한다.

이 순서를 따르면 linked source recovery가 훨씬 짧아진다. 특히 visibility mismatch는 package.json 한 줄이 아니라 provenance publish 조건과 확인 대상 version의 문제이므로, 새 version 기준으로 detail을 열어 source commit과 build file까지 확인하는 편이 안전하다.

재확인 체크리스트

1. repository.url match 확인
2. source repo visibility 확인
3. trusted publisher repo/workflow 확인
4. 새 version publish 후 provenance detail 열기
5. verify 결과와 UI 경고를 같은 메모에 저장

이미 경고가 뜬 과거 버전은 회고 자료로만 두고, 복구 판정은 새 version detail에서 하는 편이 맞다. 그래야 visibility를 고친 뒤에도 UI가 늦게 따라오는 경우와 실제 config drift가 남은 경우를 한 번에 분리할 수 있다.

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

첫 화면은 exact match 조건이다. linked source recovery를 할 때 가장 먼저 보게 되는 값이 repository.url이지만, 이 값이 맞다고 해서 provenance UI 경고가 끝난 것은 아니다.

npm trusted publishers 문서는 repository.url exact match를 기본 전제로 요구한다.

따라서 repository URL이 맞는지 확인한 뒤에도 경고가 남아 있다면 다음 질문은 visibility와 publish 위치다. exact match는 출발점이지 마지막 점검점이 아니다.

두 번째 자료는 provenance prerequisite 구간이다. npm은 provenance가 자동으로 붙으려면 public repository가 publish 위치와 case-sensitive하게 맞아야 한다고 적고 있다.

npm provenance 문서는 public repository match와 casing을 prerequisite로 설명한다.

이 문장을 보면 visibility mismatch를 UI 캐시 문제로만 볼 수 없는 이유가 분명해진다. repository URL 문자열이 맞아도 실제 저장소 visibility가 public이 아니면 provenance와 linked source 해석이 계속 어긋날 수 있다.

세 번째 자료는 trusted publisher drift를 왜 같이 보아야 하는지 보여 준다. visibility만 다르다고 생각해도 trusted publisher의 repo나 workflow filename이 이미 다른 방향을 가리키면 새 버전 publish에서 또 다른 오류가 이어질 수 있다.

trusted publisher 설정은 저장할 때 검증되지 않으므로 visibility mismatch와 함께 drift를 확인해야 한다.

그래서 recovery 순서는 metadata 확인 다음에 visibility, 그다음 trusted publisher, 마지막에 새 버전 publish로 가는 편이 짧다. 이 순서를 바꾸면 같은 페이지를 반복 새로고침하며 시간을 쓰게 된다.

네 번째 자료는 실제 확인 지점이다. npm 문서는 package page의 provenance check mark에서 View more details로 들어가 build environment, source commit, build file을 다시 보라고 안내한다.

npm provenance detail 화면은 package page의 check mark에서 열어 build environment와 source commit을 다시 확인하게 한다.

즉 visibility mismatch를 의심할 때도 recovery 확인은 새 버전의 provenance detail과 verify 결과에서 해야 한다. 경고 버전 페이지 한 장만 계속 보면 어느 단계가 고쳐졌는지 알기 어렵다.

실무에서는 UI 경고를 보고도 무엇부터 다시 확인할지 막히기 쉽다. 이 표는 repository.url이 이미 맞는 상황에서 visibility mismatch만 남았을 때 가장 짧은 재확인 순서를 고정한 자료다.

repository.url exact match 뒤 visibility mismatch만 남았을 때 쓰는 재확인 순서표다.

이미 linked source recovery 순서 글이 큰 복구 순서를 다뤘다면, 이번 표는 metadata는 통과했는데 visibility만 엇갈릴 때의 짧은 분기표다.

마지막 자료는 recovery 메모 예시다. visibility mismatch는 문자열 하나의 문제가 아니라 publish 위치와 provenance detail 확인 순서 문제라서, 어느 버전에서 무엇을 확인했는지 메모를 남겨야 다음 회고가 짧아진다.

visibility mismatch 재확인 메모 예시다.

이 메모가 있으면 CLI verify와 registry UI 로그 순서 글과 UI 경고 잔존 글을 실제 후속 runbook으로 연결하기 쉽다.

5. 주의사항과 리스크

첫 번째 리스크는 repository.url exact match를 모든 전제의 끝이라고 착각하는 것이다. 두 번째 리스크는 public repository 조건을 빼고 trusted publisher만 손보는 것이다. 세 번째 리스크는 새 version detail을 안 열고 UI 경고 잔존만으로 복구 실패를 선언하는 것이다.

운영 전에 확인할 때는 최소한 source repo visibility, trusted publisher repo/workflow, 새 version provenance detail, verify 결과를 같은 메모에 남기는 편이 좋다. 그래야 같은 경고가 다시 나와도 어디서부터 다시 봐야 하는지 짧아진다.

• exact match 통과 뒤에는 visibility와 publish 위치가 더 중요해진다.
• trusted publisher 설정은 저장 시 검증되지 않는다.
• 복구 판정은 새 version provenance detail에서 한다.

6. 결론

linked source recovery에서 repository.url exact match가 이미 맞다면 다음으로 볼 값은 visibility와 trusted publisher 정합성이다. 이 둘을 확인한 뒤 새 version provenance detail과 verify 결과까지 같이 보면 UI 경고 잔존과 실제 설정 회귀를 더 짧게 분리할 수 있다.

• repository.url이 맞아도 visibility mismatch는 따로 남을 수 있다.
• trusted publisher drift를 같이 보지 않으면 같은 경고가 반복된다.
• 새 version provenance detail이 최종 확인점이다.

7. 참고 링크

1. https://docs.npmjs.com/trusted-publishers/
2. https://docs.npmjs.com/generating-provenance-statements/
3. https://docs.npmjs.com/viewing-package-provenance/
4. https://docs.npmjs.com/cli/v11/configuring-npm/package-json/