[npm][보안] trusted publisher를 CLI로 관리할 때 npm trust와 웹 설정을 어떤 순서로 맞추나

IT 리서치 노트

[npm][보안] trusted publisher를 CLI로 관리할 때 npm trust와 웹 설정을 어떤 순서로 맞추나

npm trusted publishing을 운영할 때 많은 팀이 여전히 웹 설정 화면만 source of truth처럼 다룬다. 하지만 2026년 8월 9일 기준 npm 공식 문서를 다시 보면 `npm trust` CLI가 trusted publishing 관계 자체를 관리할 수 있고, 실제 publish 뒤에는 package provenance 화면까지 확인해야 한다. 이 글은 trusted publisher를 CLI로 관리할 때 npm trust와 웹 설정을 어떤 순서로 맞추는 편이 덜 모호해지는지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 trusted publisher 정리는 package와 workflow 대상 고정, npm trust CLI 관계 정리, 웹 설정 저장 상태 확인, provenance detail 검증 순서로 보는 편이 가장 짧다. 웹 화면만 먼저 보면 어떤 package에 어떤 workflow를 붙인 것인지 모호해지고, CLI만 보고 끝내면 실제 registry 결과가 남았는지 알 수 없다.

즉 CLI는 관계를 선언하고 바꾸는 작업면, 웹은 저장 상태를 재확인하는 확인면, provenance detail은 결과 검증면으로 나누는 편이 맞다. 이미 Trusted Publishing 기본 절차 글과 release audit 체크리스트 글을 읽었다면, 이번 글은 그 사이의 trust management 층을 채우는 후속편이다.

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

현장에서 흔한 문제는 세 가지다. 첫째, 웹 화면에서 trusted publisher가 보인다고 해서 실제 publish workflow도 그 관계를 탔다고 단정한다. 둘째, CLI로 trust relationship을 손본 뒤 어떤 package에 반영됐는지 provenance detail을 안 본다. 셋째, package page warning과 provenance detail을 같은 증상으로 보고 time gap이나 캐시 차이를 메모하지 않는다.

npm trust 문서는 trust relationship을 CLI에서 관리하는 명령이라고 설명하고, trusted publishers 문서는 OIDC 기반으로 장기 npm token 없이 publish할 수 있다고 적는다. viewing package provenance 문서는 publish 뒤 provenance attestation 검증 단계를 별도로 안내한다. 이 세 문서를 같이 읽으면 관계 수정, 저장 상태 확인, 결과 검증은 서로 다른 단계라는 점이 분명해진다.

• 증상: trusted publisher는 있어 보이는데 실제 provenance 결과가 기대와 다르다.
• 실패: 웹 화면만 보고 실제 publish workflow를 검증하지 않는다.
• 막힘: CLI trust 변경과 registry 결과 확인 시점을 분리해 기록하지 않는다.
• 누락: npm audit signatures와 package provenance detail을 같은 release note에 붙이지 않는다.

질문	먼저 볼 곳	실무 판단
어떤 package와 workflow를 묶었나	npm trust 대상 값	CLI 관계 정의를 먼저 고정한다
저장이 실제 반영됐나	웹 설정 화면	package와 workflow 문자열을 다시 대조한다
publish 결과가 맞나	provenance detail과 audit signatures	관계 수정이 실제 릴리스에 반영됐는지 본다

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

운영 순서는 네 단계면 충분하다. 먼저 package 이름, source repository, publish workflow 경로를 release note에 적는다. 두 번째로 npm trust로 trust relationship을 조정하거나 확인한다. 세 번째로 npm 웹 화면에서 해당 package의 trusted publisher 저장 상태를 다시 본다. 마지막으로 실제 publish 뒤 provenance detail과 npm audit signatures를 같은 시간축에 확인한다.

1. package와 publish workflow를 먼저 고정한다.
2. npm trust로 관계를 정리하거나 확인한다.
3. 웹 설정 화면에서 저장 상태를 재대조한다.
4. publish 뒤 provenance detail과 audit signatures를 함께 본다.

이 순서를 지키면 관계 수정 단계와 publish 결과 단계를 섞지 않게 된다. 관계가 맞는지와 이번 릴리스가 실제 trusted publishing 경로를 탔는지는 다른 질문이기 때문이다. 특히 여러 package를 한 monorepo에서 publish하거나 workflow_call 구조를 쓰는 팀일수록 CLI 대상과 실제 publish path를 먼저 적어 두는 편이 안전하다.

release_check:
package=@scope/pkg
source_repo=owner/repo
publish_workflow=.github/workflows/release.yml
npm_trust_reviewed=true
web_publisher_state_checked=true
provenance_detail_checked_after_publish=true

이 메모가 있으면 package page warning이 남아도 어느 단계까지는 맞았는지 금방 보인다. 다음 릴리스에서도 trust relationship, publish path, provenance verification을 같은 순서로 다시 확인할 수 있다.

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

첫 공식 화면은 npm CLI의 `npm trust` 문서다. 이 명령이 trusted publishing 관계 자체를 관리하는 CLI라는 점을 먼저 고정해야 한다.

npm trust 문서는 trusted publishing 관계를 CLI에서 관리하는 명령이라고 설명한다.

즉 trusted publisher 설정은 더 이상 웹 UI에만 묶인 작업이 아니다. package 이름, provider, workflow 관계를 코드에 가까운 흐름에서 점검할 수 있다.

두 번째 자료도 같은 `npm trust` 문서지만, 이번에는 trust relationship 자체를 어떻게 다룰지 설명하는 구간이다. CLI가 package와 CI provider 신뢰 관계를 직접 다루는 점이 핵심이다.

npm trust는 package와 CI/CD provider의 trust relationship을 직접 다루는 CLI라고 적고 있다.

이 문구를 기준으로 보면 웹 화면은 확인면이고, CLI는 관계를 선언하고 수정하는 작업면에 가깝다. 둘을 같은 층으로 보면 바뀐 것이 package인지 workflow인지 헷갈리기 쉽다.

세 번째 공식 화면은 trusted publishers 문서의 개요다. এখানে OIDC 기반 trusted publishing이 장기 npm token 없이 동작한다는 핵심을 다시 확인한다.

npm trusted publishers 문서는 CI/CD workflow에서 장기 npm token 없이 publish하게 해 준다고 설명한다.

결국 trust relationship이 맞는지 틀린지는 publish path와 provenance 결과에 직결된다. CLI와 웹 설정을 맞출 때도 어느 workflow가 실제 publish path인지부터 적어 두는 편이 낫다.

네 번째 자료는 package provenance 확인 문서다. trusted publisher를 손본 뒤에는 관계가 바뀌었다는 사실보다 provenance attestations가 기대대로 보이는지가 더 중요하다.

npm viewing package provenance 문서는 publish 뒤 provenance attestation 검증 단계를 안내한다.

즉 trust 관계 수정은 CLI나 웹 화면에서 끝나는 작업이 아니다. package page와 provenance detail에서 실제 결과를 확인하는 검증 단계까지 이어져야 한다.

실무에서는 CLI와 웹 설정을 어느 순서로 보느냐가 중요하다. 둘을 번갈아 눌러 보다가 어떤 쪽이 source of truth인지 놓치는 경우가 많기 때문이다.

npm trust CLI와 웹 설정, provenance 검증을 어떤 순서로 맞출지 정리한 운영표다.

이미 Trusted Publishing 기본 절차 글과 release audit 체크리스트 글이 publish path와 검증 축을 다뤘다면, 이번 표는 그 사이에 CLI trust 관리 단계를 끼워 넣는 후속편이다.

마지막 자료는 release 메모에 남기면 좋은 CLI와 검증 로그 예시다. package, provider, workflow, verify 결과를 한 줄씩 분리하는 정도면 충분하다.

trusted publisher CLI 변경과 provenance 검증을 같이 남기는 메모 예시다.

이 메모가 있으면 package page warning이 남더라도 어떤 trust relationship을 언제 바꿨는지 바로 복기할 수 있다. 최근 provenance 화면 triage는 audit signatures는 통과하는데 registry 화면이 비어 있을 때 글과 함께 보면 더 짧아진다.

5. 주의사항과 리스크

첫 번째 리스크는 웹 설정 존재 여부만 보고 actual publish path를 확인하지 않는 것이다. 두 번째 리스크는 npm trust 관계 수정 뒤 provenance detail 검증을 생략하는 것이다. 세 번째 리스크는 CLI 변경 시각과 package page 반영 시각을 남기지 않아, 캐시·전파 시간과 실제 misconfiguration을 구분하지 못하는 것이다.

운영 전에 확인할 때는 최소한 package 이름, source repo, workflow 경로, trust 변경 시각, publish 시각, provenance 검증 시각을 같은 표에 남기는 편이 좋다. 그래야 화면 경고가 남았을 때도 추적이 짧아진다.

• CLI 관계 정의와 웹 저장 상태는 다른 단계다.
• publish 결과 검증은 provenance detail과 audit signatures로 닫는다.
• 시각 메모가 없으면 캐시 지연과 설정 오류를 구분하기 어렵다.

6. 결론

trusted publisher를 CLI로 관리할 때는 npm trust와 웹 설정을 같은 화면 문제로 보면 안 된다. CLI는 trust relationship 관리, 웹은 저장 상태 확인, provenance detail은 실제 결과 검증이라는 세 단계로 나누면 release audit가 훨씬 짧아진다.

• package와 workflow 대상을 먼저 고정한다.
• npm trust와 웹 저장 상태를 차례로 맞춘다.
• publish 뒤 provenance detail과 audit signatures로 닫는다.

7. 참고 링크

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