[npm][보안] 첫 scoped package publish에서 public 전환과 provenance 조건을 어떤 순서로 다시 보나

IT 리서치 노트

[npm][보안] 첫 scoped package publish에서 public 전환과 provenance 조건을 어떤 순서로 다시 보나

npm에서 첫 scoped package를 public으로 올릴 때는 token 없이 OIDC trusted publishing까지 켜 놨는데도 package page와 provenance 기대가 어긋나는 경우가 있다. 2026년 7월 29일 기준 npm 공식 문서를 다시 보면 scoped package는 기본 private visibility로 올라가고, 첫 publish에선 `--access public`이 필요하며, provenance 자동 생성은 OIDC trusted publishing, public repository, public package 조건이 함께 맞아야 한다. 이 글은 첫 scoped package publish에서 public 전환과 provenance 조건을 어떤 순서로 다시 봐야 하는지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 첫 scoped package publish는 먼저 public 전환을 닫고, 그다음 provenance 조건을 닫아야 한다. 첫 publish command에 --access public이 있는지 확인하고, 이후에 OIDC trusted publishing 경로, repository visibility, package visibility를 차례로 확인하는 편이 가장 빠르다.

즉 trusted publishing과 public 전환은 같은 버튼이 아니다. OIDC 경로가 맞아도 package가 private로 올라가면 사람들이 기대하는 public package provenance 흐름과 다른 결과가 보일 수 있다.

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

현장에서 자주 생기는 혼선은 세 가지다. 첫째, trusted publishing을 켰으니 첫 publish도 public일 것이라고 생각한다. 둘째, provenance 문서를 보며 --provenance만 넣고 --access public은 빼먹는다. 셋째, package page가 기대와 다를 때 repository visibility와 package visibility를 같은 문제로 묶는다.

npm의 scoped public package 문서는 scoped package가 기본 private visibility라고 분명히 적는다. provenance 문서는 첫 publish라면 npm publish --provenance --access public이 필요하다고 예시를 준다. trusted publishing 문서는 automatic provenance가 OIDC trusted publishing, public repository, public package 조건을 모두 요구한다고 말한다. 따라서 첫 릴리스 점검은 publish command와 package/repository 공개 상태를 한 번에 봐야 한다.

문제가 더 커지는 지점은 이후 버전 배포와 첫 배포를 같은 체크리스트로 보는 순간이다. scope 문서는 초기 npm publish에 --access public을 넣으면 이후 public 상태가 유지된다고 설명한다. 그러므로 '이번이 첫 publish인지'를 메모에 먼저 적지 않으면, 이미 공개된 패키지의 후속 릴리스 문제를 첫 public 전환 문제로 오해할 수 있다.

• 증상: OIDC publish는 성공했는데 package page가 public처럼 안 보인다.
• 실패: --provenance만 넣고 --access public은 빼먹는다.
• 막힘: repository visibility와 package visibility를 구분하지 않는다.
• 누락: 이번이 첫 publish인지 후속 version publish인지 기록하지 않는다.

막히는 상황	먼저 볼 것	판단 기준
package page가 public처럼 안 보인다	첫 publish command	첫 릴리스라면 --access public 여부를 먼저 본다
provenance가 기대처럼 안 보인다	OIDC + public repo + public package	셋 중 하나라도 빠지면 automatic provenance 기대가 틀어진다
후속 릴리스도 같은 플래그를 의심한다	첫 publish 여부	scope 문서는 초기 publish에만 --access public이 필요하다고 말한다

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

가장 짧은 점검 순서는 다섯 단계다. 1단계에서 이번이 첫 publish인지 후속 version publish인지 적는다. 2단계에서 첫 publish라면 command에 --access public이 들어갔는지 확인한다. 3단계에서 GitHub Actions 또는 CI가 OIDC trusted publishing 경로로 실행됐는지 확인한다. 4단계에서 repository visibility와 package visibility가 public 조건에 맞는지 본다. 5단계에서 그다음에만 provenance detail과 package page UI를 비교한다.

1. 이번이 첫 publish인지부터 적는다.
2. 첫 publish라면 --access public을 먼저 확인한다.
3. CI가 OIDC trusted publishing 경로인지 확인한다.
4. repository와 package visibility를 각각 확인한다.
5. 마지막에 provenance UI와 release 기록을 비교한다.

특히 npm은 trusted publishing만으로 모든 조건이 해결된다고 말하지 않는다. public repository와 public package가 함께 필요하다고 명시한다. 따라서 publish가 성공했다는 한 줄보다, 어떤 command를 썼고 어떤 visibility 상태였고 어떤 CI 경로였는지를 같이 남기는 편이 훨씬 중요하다.

first_publish = true
publish_command = "npm publish --provenance --access public"
oidc_trusted_publishing = true
repository_visibility = "public"
package_visibility = "public"

if first_publish and "--access public" not in publish_command:
  fail("public transition missing")
if not oidc_trusted_publishing:
  fail("trusted publishing path mismatch")
if repository_visibility != "public" or package_visibility != "public":
  fail("automatic provenance conditions not met")

실제 운영 때는 workflow YAML, npm publish command, package page visibility, provenance detail 화면을 같은 릴리스 기록에 묶는 편이 좋다. 이 기록이 있으면 새 버전이 public 전환 문제인지, OIDC 경로 문제인지, 후속 UI 반영 문제인지 빠르게 나눌 수 있다.

배포 전에 workflow 권한을 확인하고, publish command를 기록하고, package page visibility를 조회하고, provenance detail 화면을 열어 로그와 결과를 같이 비교해 두면 다음 점검이 훨씬 빨라진다.

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

첫 자료는 npm의 scoped public package 문서다. npm은 scoped package가 기본적으로 private visibility로 올라가며, public으로 올리려면 초기 publish에서 `npm publish --access public`을 명시해야 한다고 적고 있다.

npm 문서는 scoped package가 기본 private visibility이며 첫 publish에서 `--access public`이 필요하다고 설명한다.

즉 첫 배포에서 public 전환을 놓치면 이후 provenance UI나 package page를 보며 한참 헤맬 수 있다. package 이름과 workflow가 맞아도 visibility가 private면 사람들이 기대하는 공개 패키지 흐름과 달라진다.

두 번째 자료는 npm의 provenance 문서다. GitHub Actions에서 provenance를 붙일 때 첫 publish라면 `npm publish --provenance --access public`처럼 access와 provenance를 함께 명시해야 한다고 안내한다.

npm provenance 문서는 첫 publish에서 `--provenance`와 `--access public`을 함께 넣는 예시를 직접 보여 준다.

현장에서 자주 놓치는 부분이 바로 이 조합이다. trusted publishing을 이미 켰으니 public 전환도 알아서 될 것이라 생각하면 첫 릴리스에서 package visibility와 provenance 기대가 서로 어긋난다.

세 번째 자료는 trusted publishing 문서의 automatic provenance 조건이다. npm은 OIDC trusted publishing, public repository, public package가 모두 맞을 때만 provenance 자동 생성이 붙는다고 설명한다.

Trusted publishing만 켠다고 provenance가 항상 붙는 것은 아니며 public repository와 public package 조건도 필요하다.

따라서 첫 배포 점검은 publish command 한 줄만 볼 일이 아니다. repository visibility, package visibility, OIDC 경로가 동시에 맞는지 닫아야 provenance 화면과 릴리스 기록이 일치한다.

네 번째 자료는 npm CLI의 scope 문서다. scoped package는 기본 public이 아니며, 초기 `npm publish`에서 `--access public`을 주면 이후 `npm access public`을 실행한 것과 같은 효과가 난다고 설명한다.

npm CLI 문서는 scoped package의 초기 publish에서만 `--access public`을 넣으면 된다고 정리한다.

이 문장을 기억하면 새 버전 배포 때마다 같은 플래그를 의심하는 시간을 줄일 수 있다. 첫 publish와 이후 version publish를 다른 문제로 나눠 보는 편이 훨씬 깔끔하다.

다섯 번째 자료는 첫 scoped public publish 점검표다. public 전환, OIDC, provenance, repository visibility를 어떤 순서로 다시 보는지 한 표로 묶었다.

첫 scoped public publish에서 public 전환과 provenance 조건을 같이 점검하는 순서표다.

이미 trusted publishing 절차 글이 token 없는 배포 자체를 다뤘다면, 이번 표는 첫 public 릴리스에서 visibility와 provenance를 함께 닫는 단계다.

마지막 자료는 GitHub Actions 기준 최소 workflow 메모다. first publish에서 `id-token: write`, GitHub-hosted runner, `--provenance`, `--access public`을 같이 적어 두면 운영자가 다음 릴리스와 첫 릴리스를 혼동하지 않기 쉽다.

GitHub Actions에서 첫 scoped public publish를 할 때 남겨야 할 최소 workflow 메모 예시다.

또 trusted publisher recovery 뒤 UI 경고 글과 linked source visibility 글을 같이 보면 첫 publish 문제와 후속 UI drift 문제를 분리하기 쉬워진다.

5. 주의사항과 리스크

첫 번째 리스크는 첫 publish와 후속 publish를 같은 체크리스트로 보는 것이다. 두 번째는 --provenance만 넣고 public 전환 플래그를 놓치는 것이다. 세 번째는 repository visibility와 package visibility를 구분하지 않고 한쪽 상태만 확인하는 것이다.

운영 메모에는 최소한 first publish 여부, publish command, OIDC path, repository visibility, package visibility를 함께 남겨 두는 편이 좋다. 그래야 provenance 화면이 기대와 다를 때도 어느 층에서 어긋났는지 다시 빠르게 좁힐 수 있다.

• 첫 scoped package는 기본 public이 아니므로 --access public을 먼저 본다.
• automatic provenance는 OIDC, public repo, public package가 함께 맞아야 한다.
• 첫 publish 문제와 후속 UI drift 문제를 한 원인으로 묶지 않는다.

6. 결론

첫 scoped package publish에서 public 전환과 provenance를 동시에 보려면 순서를 분리해야 한다. 먼저 public 전환을 닫고, 그다음 OIDC와 visibility 조건을 닫는 편이 가장 빠르다.

정리하면 첫 릴리스 여부, --access public, OIDC 경로, public repo, public package를 차례로 확인하면 package page와 provenance 화면이 왜 어긋났는지 대부분 짧게 설명할 수 있다.

7. 참고 링크

1. https://docs.npmjs.com/creating-and-publishing-scoped-public-packages/
2. https://docs.npmjs.com/generating-provenance-statements/
3. https://docs.npmjs.com/trusted-publishers/
4. https://docs.npmjs.com/cli/v11/using-npm/scope/