[npm][보안] staged publishing을 쓰는 팀은 provenance release record에 approval evidence와 2FA 확인을 어떤 필드로 같이 남기나

IT 리서치 노트

[npm][보안] staged publishing을 쓰는 팀은 provenance release record에 approval evidence와 2FA 확인을 어떤 필드로 같이 남기나

npm staged publishing을 쓰기 시작하면 일반 provenance release record만으로는 설명이 모자라다. 2026년 7월 25일 KST 기준 npm 공식 문서를 다시 보면 `npm stage publish`는 2FA 없이 staging area에 submit할 수 있지만, 최종 approve는 CLI와 npmjs.com 모두에서 2FA verification이 필요하다. 이 글은 staged publishing을 쓰는 팀이 provenance release record에 approval evidence와 2FA 확인을 어떤 필드로 같이 남기는 편이 좋은지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 staged publishing release record는 OIDC provenance 필드만으로 끝내면 안 된다. stage_id, approval actor, approval 2FA confirmation, provenance detail URL, npm audit signatures 결과를 한 묶음으로 남겨야 stage submit부터 live publish까지 경로가 끊기지 않는다.

즉 staged publishing은 publish action이 둘로 나뉜다. submit 단계는 CI와 trusted publisher가 맡을 수 있지만, 승인 단계는 maintainer와 2FA가 맡는다. release record도 이 둘을 같은 문서에 붙여야 한다.

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

실무에서 먼저 꼬이는 지점은 세 가지다. 첫째, npm stage publish가 성공한 로그만 남기고 최종 approval evidence를 안 남긴다. 둘째, provenance detail URL은 저장하지만 누가 approve했고 2FA를 통과했는지는 기록하지 않는다. 셋째, live publish 뒤 npm audit signatures 결과를 안 남겨 최종 registry 검증이 빠진다.

npm 문서는 staged publishing의 흐름을 세 단계로 나눈다. stage, review, approve다. 또 approve 단계에서는 CLI든 npmjs.com이든 2FA verification을 요구한다고 적고 있다. 그리고 trusted publishers 문서는 OIDC로 CI에서 submit할 수 있어도 maintainer approval은 별도라고 설명한다. 즉 release record는 machine proof와 human approval proof를 둘 다 담아야 한다.

일반 provenance record만 남기면 이런 문제가 생긴다. staged package가 실제로 승인돼 live registry에 갔는지, 누가 승인했는지, 2FA가 적용됐는지, 그 후 registry signatures와 provenance attestations가 PASS였는지를 한 번에 설명하지 못한다. incident review나 감사에서 다시 CLI 로그와 npm UI 기록을 따로 뒤져야 한다.

• 증상: stage submit 로그는 있는데 누가 언제 승인했는지 문서가 없다.
• 실패: provenance detail URL만 남기고 approval evidence를 안 남긴다.
• 막힘: 2FA 확인 사실이 빠져 staged publishing의 통제점을 설명하지 못한다.
• 누락: live publish 뒤 npm audit signatures 결과를 기록하지 않는다.

누락된 항목	나중에 생기는 문제	왜 지금 남기나
approval_actor	누가 go-live를 승인했는지 다시 찾아야 한다	human approval 책임을 남기기 위해
approval_2fa_confirmed	문서상 필수 2FA 통과 사실을 설명하지 못한다	승인 통제점이 실제 적용됐는지 남기기 위해
audit_signatures_result	live registry 상태 검증이 빠진다	최종 검증을 자동화하기 위해

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

실무 기준은 다섯 단계가 가장 실용적이다. 먼저 npm stage publish가 만든 stage_id를 기록한다. 두 번째로 review 주체와 approve 주체를 구분해 기록한다. 세 번째로 approve 시 2FA가 확인됐다는 사실을 남긴다. 네 번째로 provenance detail URL과 trusted publisher 정보를 적는다. 마지막으로 live publish 뒤 npm audit signatures 결과를 붙인다.

1. stage_id를 기록한다.
2. review와 approve actor를 구분해 적는다.
3. approve 시 2FA confirmation을 남긴다.
4. provenance detail URL과 trusted publisher 정보를 적는다.
5. live publish 뒤 npm audit signatures 결과를 붙인다.

이 구조가 중요한 이유는 staged publishing이 두 개의 통제면을 가지기 때문이다. 하나는 CI와 trusted publisher가 만드는 OIDC provenance 증거다. 다른 하나는 maintainer와 2FA가 만드는 human approval 증거다. release record는 이 둘을 이어 붙여야만 '어디서 build했고 누가 live publish를 승인했는가'를 한 번에 설명한다. 기록 담당자는 stage submit 로그를 저장하고, approve 주체를 확인하고, 승인 시각을 메모하고, 최종 verify 결과를 붙이는 순서를 반복해야 한다.

실제 작성 순서는 더 단순하다. stage submit 직후 stage_id와 submitter를 적고, tarball review가 끝나면 approval actor와 승인 시각을 적는다. approve 직후 2FA 확인 여부를 표시하고, live registry에 반영된 뒤 provenance detail URL과 npm audit signatures 결과를 붙이면 된다. 이때 CLI에서 stage view를 실행하고, npmjs.com에서 approve 내역을 확인하고, release note에 링크를 저장하고, verify 결과를 복사해 붙여 넣는 식으로 흐름을 고정하면 빠르다. 이미 CLI verify와 registry UI 로그 순서 글을 봤다면 이번 글은 staged publish workflow에 맞게 그 기록 순서를 확장한 것이다.

record stage_id
record approval actor
record approval 2FA confirmation
record provenance detail url
record npm audit signatures result

이 메모 구조를 쓰면 stage submit은 자동화했지만 approval은 사람이 했다는 사실이 명확해진다. 사고가 생겼을 때도 CI provenance와 maintainer approval을 따로 뒤지지 않아도 된다.

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

첫 화면은 staged publishing의 승인 단계다. npm 문서는 staged package를 live registry로 올릴 때 CLI든 npmjs.com이든 2FA 확인을 요구한다고 적고 있다.

npm staged publishing 문서는 staged package 승인 시 2FA verification이 필요하다고 설명한다.

즉 staged publishing을 쓰는 팀의 release record는 publish command만으로는 끝나지 않는다. approval evidence와 2FA 통과 사실을 별도 필드로 남겨야 provenance가 실제 live publish까지 이어졌는지 설명할 수 있다.

두 번째 자료는 trusted publishing과 staged publishing의 결합 구간이다. npm 문서는 OIDC 기반 trusted publishing으로 package를 submit할 수 있지만, 최종 approval은 maintainer가 2FA로 해야 한다고 적고 있다.

npm 문서는 trusted publishing으로 stage는 할 수 있지만 최종 approval은 maintainer의 2FA가 필요하다고 설명한다.

이 문장을 release record 관점으로 바꾸면, OIDC provenance evidence와 human approval evidence를 같은 문서에 남겨야 한다는 뜻이 된다. 둘 중 하나만 있으면 staged publish의 실제 go-live 경로가 끊긴다.

세 번째 화면은 provenance 상세 화면 역할이다. npm 문서는 provenance로 누가, 어디서, 어떻게 publish했는지와 authorized user 여부를 검증할 수 있다고 설명한다.

npm provenance 문서는 publish 경로와 authorized user 검증 근거를 제공한다고 설명한다.

하지만 staged publishing에서는 여기만으로는 부족하다. review와 approve가 분리되므로 provenance evidence 옆에 staged approval evidence를 붙여야 감사 기록이 완성된다.

네 번째 자료는 CLI 검증 단계다. npm 문서는 `npm audit signatures`가 registry signatures와 provenance attestations를 검증한다고 설명한다.

npm audit signatures는 registry signatures와 provenance attestations를 검증한다.

따라서 staged publishing release record는 UI approval evidence만으로 끝내지 말고, live publish 뒤 `npm audit signatures` 결과도 같이 남기는 편이 안전하다.

실무에서는 어떤 필드를 남길지 표로 고정하는 편이 좋다. staged publishing은 stage-submit, review, approve, provenance verify가 나뉘기 때문에 release record도 그 흐름을 그대로 따라가야 한다.

staged publishing release record에 남길 필드를 정리한 표다.

이미 provenance release record 템플릿 글이 일반 필드를 다뤘다면, 이번 표는 staged publishing 전용 approval evidence를 붙이는 단계다.

마지막 자료는 실제 메모 예시다. stage submit과 approval과 provenance verify를 한 줄로 이어서 남기면 회고와 감사를 모두 줄일 수 있다.

staged publishing release record 예시다.

이 구조를 쓰면 trusted publishing OIDC 증거와 maintainer approval 증거가 끊기지 않는다. staged publish를 incident 대응이나 보안 감사에서 다시 꺼내 볼 때도 설명이 짧아진다.

5. 주의사항과 리스크

첫 번째 리스크는 trusted publishing이 있으니 approval evidence는 생략해도 된다고 생각하는 것이다. 두 번째 리스크는 approval actor는 적지만 2FA 통과 사실을 빼먹는 것이다. 세 번째 리스크는 live publish 뒤 npm audit signatures를 안 돌려 최종 registry 상태를 문서화하지 않는 것이다.

운영 전에 확인할 때는 최소한 stage_id, approval actor, approval 2FA confirmation, provenance detail URL, audit signatures result 다섯 필드를 같은 release record에 두는 편이 좋다. staged publishing은 submit과 approve가 분리되므로 어느 한쪽 로그만 남기면 설명이 비게 된다. stage list를 조회하고, approve 직후 2FA 통과를 체크하고, audit 결과를 저장하는 절차를 팀 문서에 함께 남기면 재발 시 확인이 빨라진다.

• staged publishing은 machine proof와 human approval proof를 둘 다 남긴다.
• 2FA confirmation은 문서상 필수 통제점이므로 별도 필드로 남긴다.
• live publish 뒤 npm audit signatures 결과까지 붙여야 기록이 닫힌다.

6. 결론

npm staged publishing을 쓰는 팀의 release record는 일반 provenance 템플릿보다 한 단계 더 길어야 한다. stage_id, approval actor, 2FA confirmation, provenance detail URL, npm audit signatures 결과를 같이 남겨야 stage submit부터 live registry 승인까지 경로가 끊기지 않는다.

• submit 증거와 approval 증거를 분리해 적는다.
• 2FA confirmation을 빠뜨리지 않는다.
• live publish 뒤 audit signatures 결과를 붙인다.
• incident triage 순서를 먼저 보고 싶다면 npm package provenance incident 허브 글에서 linked source repository, release record, staged approval evidence 사다리를 먼저 확인하면 된다.
• 다음 단계는 release record template 글에 staged publish 전용 필드를 합치는 것이다.

7. 참고 링크

1. https://docs.npmjs.com/staged-publishing/
2. https://docs.npmjs.com/trusted-publishers/
3. https://docs.npmjs.com/viewing-package-provenance/