[npm][보안] trusted publisher recovery 뒤 새 버전 publish는 성공했는데 UI 경고가 남을 때 package page와 provenance detail을 어떤 시차로 다시 보나

IT 리서치 노트

[npm][보안] trusted publisher recovery 뒤 새 버전 publish는 성공했는데 UI 경고가 남을 때 package page와 provenance detail을 어떤 시차로 다시 보나

npm trusted publisher 설정을 고치고 새 버전 publish까지 성공했는데 package page 경고가 바로 사라지지 않는 경우가 있다. 2026년 7월 27일 기준 npm 공식 문서를 다시 보면 trusted publisher 저장 시 검증, provenance 자동 생성, package page 표시, provenance detail 검증은 서로 다른 단계다. 이 글은 recovery 뒤 새 버전은 정상인데 UI 경고가 남을 때 package page와 provenance detail을 어떤 시차로 다시 보는 편이 빠른지 정리한다.

목차

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

1. 개요

결론부터 말하면 recovery 뒤 새 버전 publish가 성공했어도 package page와 provenance detail은 같은 시점에 같은 신호를 주지 않을 수 있다. 먼저 CLI 결과와 provenance verify를 확인하고, 그다음 package page 경고를 따로 본 뒤, 마지막에 metadata와 trusted publisher 설정 메모를 다시 대조하는 편이 가장 안전하다.

즉 복구 이후의 핵심은 새로고침 횟수가 아니라 확인 순서다. package page 경고 하나만 보고 복구 실패로 결론 내리면 UI 반영 지연과 실제 설정 회귀를 분리하기 어렵다.

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

현장에서 자주 생기는 혼선은 세 가지다. 첫째, 새 버전 publish 성공과 package page 반영을 같은 사건으로 본다. 둘째, provenance detail이나 npm audit signatures가 정상인데 경고 문구가 남아 있으면 설정이 아직 틀렸다고 단정한다. 셋째, recovery 때 고친 repository.url, trusted publisher의 repository, workflow filename, visibility를 새 버전 확인 시점에 같이 저장하지 않는다.

하지만 npm 문서는 저장 시 검증이 없고 publish 시점에야 오류가 드러날 수 있다고 적고, provenance attestation은 trusted publishing이면 자동 생성된다고 설명한다. 즉 새 버전에서 provenance가 붙었다는 사실과 package page의 연결 경고가 언제 사라지는지는 다른 관찰값이다.

• 증상: 새 버전 publish는 성공했는데 package page warning이 남는다.
• 실패: package page와 provenance detail을 같은 반영 시점으로 가정한다.
• 막힘: verify는 성공했는데 UI 경고가 남아 어떤 값이 틀린지 모른다.
• 누락: repository.url과 workflow filename을 recovery 메모에 같이 남기지 않는다.

관찰 지점	먼저 확인할 것	왜 분리해야 하나
CLI publish 직후	새 버전 번호와 publish 성공	버전이 실제로 바뀌었는지 먼저 고정해야 한다
provenance detail	attestation 생성과 verify 결과	OIDC provenance 축이 살아 있는지 먼저 확인한다
package page	warning 문구와 source repo 표시	표시 지연과 metadata 회귀를 분리해야 한다

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

실무 기준은 다섯 단계가 가장 실용적이다. 1단계에서 새 버전 번호와 publish 성공을 기록한다. 2단계에서 provenance detail이나 verify 결과를 먼저 확인해 OIDC provenance 자체가 정상인지 본다. 3단계에서 package page warning 문구를 별도 시각에 다시 확인한다. 4단계에서 recovery 때 고친 repository.url, trusted publisher의 repository, workflow filename, visibility 값을 메모와 대조한다. 5단계에서 그래도 경고가 남으면 UI 지연 후보와 설정 회귀 후보를 분리해 적는다.

1. 버전 번호와 publish 성공부터 기록한다.
2. provenance detail 또는 verify 결과를 먼저 본다.
3. package page warning은 별도 시각에 다시 본다.
4. repository.url과 trusted publisher 설정을 메모와 대조한다.
5. UI 지연과 설정 회귀를 다른 후보로 기록한다.

recheck 순서 예시

version=1.4.3
verify_result=attestation valid
provenance_detail_checked_at=2026-07-27T10:42:00+09:00
package_page_checked_at=2026-07-27T10:49:00+09:00
repository_url_checked=true

이 순서를 따르면 package page 경고가 남아도 무작정 재배포부터 반복하지 않게 된다. verify가 정상이고 provenance detail이 새 버전으로 붙었다면, 그다음 질문은 "package page가 아직 전 버전 metadata를 보여 주는가"이지 곧바로 "trusted publisher가 또 틀렸는가"가 아니다.

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

첫 화면은 trusted publishing 문서의 중요한 경고다. npm은 trusted publisher 설정을 저장할 때 검증하지 않고, 실제 publish 시점에야 오류가 드러날 수 있다고 설명한다.

npm 문서는 trusted publisher 설정을 저장할 때 검증하지 않는다고 안내한다.

따라서 recovery 뒤 새 버전 publish가 성공했다고 해서 package page 경고가 즉시 사라진다고 가정하면 안 된다. 저장 시 검증, publish 시 검증, package page 반영은 같은 단계가 아니다.

두 번째 자료는 trusted publishers 문서의 exact match 규칙이다. GitHub에서 publish할 때는 package.json의 repository.url이 실제 저장소와 정확히 일치해야 한다.

npm은 trusted publishing에서 package.json의 repository.url이 실제 GitHub 저장소와 정확히 일치해야 한다고 설명한다.

이 조건을 맞춘 뒤 새 버전을 올렸더라도 package page와 provenance detail은 서로 다른 정보를 다시 보여 줄 수 있다. 그래서 recovery 이후에는 어느 화면이 먼저 바뀌는지 시간을 나눠 기록하는 편이 좋다.

세 번째 화면은 generating provenance statements 문서다. trusted publishing을 쓰면 provenance attestations가 자동으로 생성된다고 다시 확인할 수 있다.

npm 문서는 trusted publishing을 쓰면 provenance attestation이 자동 생성된다고 설명한다.

즉 새 버전 publish가 성공하고 provenance가 붙었다는 사실과, package page 경고가 사라졌는지는 따로 봐야 한다. 자동 attestation 생성은 provenance detail 쪽 신호이고, package page 경고는 source repository 연결과 표시 반영 축에 더 가깝다.

네 번째 자료는 provenance를 보는 문서의 verify 단계다. npm은 registry 화면만 보지 말고 provenance attestation을 따로 검증하는 흐름을 제공한다.

Viewing package provenance 문서는 registry 화면 확인과 provenance verify 흐름을 분리해 보여 준다.

따라서 recovery 뒤에는 package page 경고와 provenance verify를 같은 순간의 진실로 보지 않는 편이 안전하다. 같은 버전이라도 어느 화면이 먼저 반영됐는지 메모가 없으면 UI 지연과 설정 오류를 구분하기 어렵다.

실무에서는 package page와 provenance detail을 같은 새로고침 주기로 보면 오판이 잦다. 복구 뒤에는 각 화면을 다른 시차로 확인하는 표를 만들어 두는 편이 빠르다.

recovery 뒤 package page와 provenance detail을 다른 시차로 확인하는 분리표다.

이미 linked source repository recovery 순서 글이 새 버전 재배포 전까지의 복구 runbook을 다뤘다면, 이번 표는 그 다음 단계인 반영 확인 순서를 좁혀 준다.

마지막 자료는 recheck 메모 예시다. 복구 후에는 단순히 '경고가 남음'이라고 적기보다 어떤 화면을 언제 확인했는지까지 남겨야 한다.

package page와 provenance detail 재확인 시간을 같이 남기는 메모 예시다.

이 메모가 있으면 UI 지연과 실제 설정 회귀를 분리하기 쉽다. CLI verify와 registry UI 로그 순서 글과 함께 보면 반영 확인까지 한 runbook으로 묶을 수 있다.

5. 주의사항과 리스크

첫 번째 리스크는 verify 성공과 UI 경고를 같은 층의 신호로 보는 것이다. 두 번째는 recovery 때 고친 metadata 값을 새 버전 확인 메모에 안 남겨 어떤 수정이 실제로 효과가 있었는지 잃어버리는 것이다. 세 번째는 staged publishing이나 approve 경로가 있는 팀에서 최종 live 버전 확인 시각을 따로 적지 않는 것이다.

• publish 성공과 package page 반영은 같은 체크포인트가 아니다.
• verify가 정상이어도 package page 경고는 별도 확인이 필요하다.
• 버전 번호와 확인 시각이 없으면 UI 지연과 설정 회귀를 분리하기 어렵다.

6. 결론

trusted publisher recovery 뒤 새 버전 publish는 성공했는데 경고가 남으면, registry를 계속 새로고침하기보다 확인 순서를 고정하는 편이 빠르다. 새 버전 번호, provenance verify, package page warning, recovery metadata 메모를 다른 시차로 남기면 UI 지연과 실제 회귀를 훨씬 짧게 가를 수 있다.

repository.url exact match는 이미 맞는데 GitHub 저장소 visibility만 달라 보이는 상황이라면, 후속 점검 순서를 따로 정리한 linked source visibility mismatch 재확인 글을 바로 이어서 보면 좋다.

선행 글로는 linked source repository recovery 순서 글, CLI verify와 registry UI 로그 순서 글, provenance incident 허브 글을 같이 보면 좋다.

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/staged-publishing/