-
[npm][보안] npm audit signatures는 통과하는데 registry provenance 화면이 비어 있을 때 package visibility와 version 조건을 어떤 순서로 다시 보나기타개발지식/풀스택개발 2026. 7. 19. 20:14
IT 리서치 노트
[npm][보안] npm audit signatures는 통과하는데 registry provenance 화면이 비어 있을 때 package visibility와 version 조건을 어떤 순서로 다시 보나
npm supply chain 검증을 붙이다 보면 `npm audit signatures`는 통과하는데 npm registry의 provenance UI가 기대와 다르게 비어 보일 때가 있다. 2026년 7월 19일 기준 npm 공식 문서를 다시 보면 trusted publishing의 OIDC 감지 순서, public repository와 public package 조건, 그리고 registry UI가 버전 단위라는 점이 서로 맞물린다. 이 글은 CLI 검증은 통과하는데 registry provenance 화면이 헷갈릴 때 무엇부터 다시 보는 편이 빠른지 정리한 것이다.
1. 개요
결론부터 말하면 이 증상은 UI만의 문제가 아니라 publish path, package visibility, version 단위를 섞어 읽을 때 가장 자주 생긴다. trusted publishing은 OIDC를 먼저 시도하지만 필요하면 전통적 토큰으로 fallback할 수 있고, 자동 provenance 생성은 public repository와 public package 조건까지 같이 맞아야 한다.
그래서
npm audit signatures가 통과해도 먼저 최신 버전이 맞는지, package visibility가 public인지, 이번 publish가 OIDC 경로였는지를 차례로 확인해야 한다. registry provenance 체크는 package 전역 배지가 아니라 version 우측 UI라는 점도 같이 기억해야 한다.2. 어디서 실제로 막히는가
현장에서 흔한 오해는 두 가지다. 첫째, CLI 검증이 통과하면 npm website도 바로 같은 상태를 보여 줄 것이라고 본다. 둘째, trusted publisher 설정이 있으니 이번 publish도 자동으로 OIDC 경로를 탔을 것이라고 단정한다.
하지만 npm trusted publishing 문서는 npm CLI가 OIDC 환경을 먼저 감지한 뒤 전통적인 토큰으로 fallback할 수 있다고 적고 있다. 또 자동 provenance 생성은 trusted publishing, public repository, public package 조건을 모두 요구한다. scoped package가 private 상태이거나, public 전환 전 버전을 보고 있거나, 이번 릴리스가 토큰 경로로 올라갔다면 UI가 기대와 다를 수 있다.
- 증상: audit signatures는 통과하는데 npm website의 provenance 영역이 비어 보인다.
- 실패: registry UI를 package 전체 상태로 보고 version별 차이를 놓친다.
- 막힘: trusted publisher 존재만 보고 이번 publish path가 OIDC였다고 가정한다.
- 누락: scoped package의 public/private visibility와 first publish 조건을 같이 보지 않는다.
특히 scoped package는 처음 공개할 때
npm publish --access public가 필요할 수 있고, npm 문서는 scoped package가 기본적으로 private visibility로 올라간다고 설명한다. 이 기본값을 놓치면 provenance UI 빈 화면을 registry 버그로 오해하게 된다.3. 실무에서 적용하는 순서
점검 순서는 다섯 단계가 가장 실용적이다. 먼저 지금 보고 있는 npm website가 최신 version인지 확인한다. 다음으로 package visibility가 public인지, 특히 scoped package라면 첫 publish 때
--access public가 적용됐는지 본다. 세 번째로 이번 릴리스가 OIDC trusted publishing 경로였는지, 아니면 token fallback이었는지 로그를 확인한다. 네 번째로 그 뒤에야 registry provenance UI와 CLI 결과를 나란히 비교한다. 마지막으로 필요하면 trusted publishing에서 토큰 접근을 막아 fallback 가능성을 줄인다.실무에서는 이 다섯 단계를 같은 순서로 반복 점검하는 편이 좋다. 최신 version을 다시 조회하고, package access를 다시 확인하고, publish 로그를 다시 비교하고, public 전환 여부를 다시 점검하고, 마지막에 UI를 다시 확인한다. 이 순서를 고정해야 버전 착각과 visibility 착각을 빠르게 분리할 수 있다.
- 최신 version을 보고 있는지부터 확인한다.
- package visibility와 scoped package 공개 상태를 확인한다.
- 이번 publish path가 OIDC였는지 token fallback이었는지 로그로 분리한다.
- 그다음 registry UI와
npm audit signatures를 같이 읽는다. - 가능하면 token 접근을 제한해 fallback 경로를 줄인다.
짧게 적으면 이렇다. 버전을 확인하고, visibility를 조회하고, publish path를 비교하고, 공개 상태를 점검하고, 마지막에 provenance UI를 다시 확인한다. 이 다섯 동작을 같은 순서로 반복해야 사람이 바뀌어도 같은 결론에 도달하기 쉽다.
npm 문서는 trusted publishers를 쓸 때 토큰 접근을 제한하는 방향도 권장한다. 이 설정을 걸어 두면 다음 릴리스에서 provenance UI 빈 화면을 볼 때 publish path 분기가 한 단계 줄어든다.
1. latest version 맞는지 본다 2. scoped package면 public visibility인지 본다 3. publish log에서 OIDC / token fallback을 나눈다 4. npm audit signatures 결과를 확인한다 5. registry provenance UI를 같은 version으로 다시 본다4. 공식 문서와 예시 화면으로 확인하기
첫 화면은 trusted publishing의 실제 동작 순서를 설명한다. npm CLI는 OIDC 환경을 먼저 감지하고, 거기서 안 되면 전통적인 토큰으로 fallback할 수 있다고 적고 있다.
즉 audit signatures가 통과했다는 사실만으로 이번 버전이 OIDC publish였다고 단정할 수는 없다. publish path와 provenance UI를 분리해서 봐야 하는 이유가 여기서 나온다.
두 번째 자료는 자동 provenance 생성 조건이다. trusted publishing, public repository, public package 세 조건이 모두 맞아야 자동 생성이 붙는다고 문서가 직접 적고 있다.
그래서 registry UI가 비어 보일 때는 화면이 늦게 뜨는지보다 이번 릴리스 버전이 이 세 조건을 실제로 탔는지를 먼저 점검해야 한다. package visibility가 private이면 바로 분기가 갈린다.
세 번째 화면은 trusted publishing과 --provenance 플래그 관계를 정리한다. OIDC trusted publishing이면 별도 --provenance 없이도 자동 생성이 붙는다고 문서가 말한다.
따라서 registry provenance 화면이 비었다고 해서 곧바로 플래그 누락만 의심하면 안 된다. 이번 버전의 publish path와 package visibility를 먼저 정리한 뒤 CLI 검증과 UI를 나란히 읽는 편이 빠르다.
네 번째 자료는 npm registry UI에서 provenance를 확인하는 위치다. 문서는 README 오른쪽 Version 영역의 초록 체크를 먼저 보라고 안내한다.
중요한 점은 이 UI가 버전 단위라는 것이다. 예전 버전에 provenance가 있었더라도 방금 올린 새 버전이 조건을 못 탔다면 최신 화면은 비어 보일 수 있다. package 단위와 version 단위를 섞으면 바로 헷갈린다.
마지막 표는 CLI 검증과 registry UI를 같이 읽을 때 어떤 순서로 분기하는지 정리한 triage 표다. 이 표가 있으면 package visibility, version, publish path를 한 장에서 나눌 수 있다.
이미 OIDC publish인지 token fallback인지 다시 보는 글을 읽었다면, 이번 글은 그 다음 단계인 version과 visibility 분기다. 또 --provenance와 audit signatures 글과도 바로 이어진다.
5. 주의사항과 리스크
첫 번째 리스크는 registry UI를 새로고침하면서 시간을 보내는 것이다. 조건이 안 맞는 버전이면 기다려도 provenance가 생기지 않는다. 두 번째는 scoped package의 기본 private visibility를 놓치고 publish flag 문제를 지나치는 것이다. 세 번째는 token fallback을 허용한 채 trusted publishing만 설정해 놓고, 실제 릴리스 경로를 기록하지 않는 것이다.
운영 전에는 release record에 version, package visibility, repo visibility, OIDC 감지 여부, token fallback 여부를 같이 남기는 편이 좋다. 그래야 provenance attestation 누락 글과 release audit 체크리스트 글의 후속 운영도 짧아진다.
6. 결론
npm audit signatures가 통과하는데 registry provenance 화면이 비어 보일 때는 UI보다 version, package visibility, publish path를 먼저 나눠야 한다. trusted publishing의 OIDC 감지와 token fallback, scoped package의 공개 기본값, 버전별 체크 표시 위치를 같이 보면 대부분의 혼선을 더 빨리 줄일 수 있다.관련 글로는 --provenance와 audit signatures 글, OIDC publish와 token fallback 글, trusted publishing 절차 글을 같이 보면 좋다.
같은 npm provenance 가지에서 단일 버전 triage를 넘어서 같은 패키지의 여러 버전이 왜 서로 다른 provenance 노출을 보이는지 시간축으로 정리하고 싶다면 version history와 visibility 변경 이력을 같이 보는 후속 글을 이어서 보면 좋다. 이번 글이 한 버전의 조건 분기라면, 그 글은 여러 버전의 차이를 읽는 메모다.
7. 참고 링크
'기타개발지식 > 풀스택개발' 카테고리의 다른 글
