npm provenance·SLSA 실전 가이드 2026: 패키지 배포 보안은 토큰보다 OIDC·빌드 증명·승인 게이트를 먼저 설계해야 하는 이유

작성일: 2026-07-08 · 카테고리: 개발정보

1. 한 줄 문제 정의

핵심 요약: npm 패키지 배포 보안의 시작점은 “누가 배포했나”가 아니라 “어떤 워크플로가 어떤 소스와 빌드 과정을 거쳐 배포했나”를 검증 가능하게 남기는 것입니다.

이 글의 대상 독자는 공개 npm 패키지를 운영하는 프론트엔드·Node.js 개발자, 사내 공통 라이브러리 관리자, 릴리스 자동화를 맡은 DevOps 담당자입니다. 해결하려는 문제는 장기 npm 토큰이 CI에 남아 있거나, 배포된 tarball이 실제 저장소와 같은지 확인하기 어려운 상황입니다.

범위는 npm trusted publishing, provenance attestation, GitHub Actions 기반 배포, SLSA 관점의 검증입니다. 제외 범위는 사설 레지스트리 전체 구축, 모든 언어 생태계의 패키지 서명 비교, 완전한 재현 빌드 구현입니다.

2. 먼저 결론

핵심 요약: 공개 npm 패키지를 자동 배포한다면 2026년 기준 기본 선택지는 “OIDC 기반 trusted publishing + provenance + 필요 시 staged publishing”입니다.

새 패키지를 만들거나 기존 패키지 배포 파이프라인을 손볼 수 있다면, 더 이상 장기 npm automation token을 첫 번째 선택으로 두지 않는 편이 좋습니다. npm trusted publishing은 CI 워크플로가 OpenID Connect, 즉 짧게 살아 있는 신원 토큰으로 npm에 자신을 증명하게 만듭니다.

단, 모든 팀에 즉시 맞지는 않습니다. 자체 호스팅 러너만 쓰는 팀, 레거시 Node 버전을 고정한 팀, publish 전 사람이 tarball을 반드시 확인해야 하는 팀은 staged publishing과 수동 승인까지 함께 설계해야 합니다.

3. 핵심 구조 분해

핵심 요약: npm provenance는 서명 하나가 아니라 CI 신원, 빌드 입력, 패키지 결과물, 공개 검증 로그가 연결된 구조입니다.

구조를 네 계층으로 보면 이해가 쉽습니다.

• 소스 계층: Git 저장소, tag, commit, workflow 파일이 배포의 출발점입니다.
• 실행 계층: GitHub Actions, GitLab CI, CircleCI 같은 지원 CI가 OIDC 토큰을 발급받습니다.
• 증명 계층: npm은 provenance attestation과 publish attestation을 통해 어디서 어떻게 빌드·배포됐는지 연결합니다.
• 검증 계층: 소비자는 npm audit signatures 같은 명령으로 registry signature와 attestation 검증 여부를 확인합니다.

SLSA의 provenance 모델도 같은 문제를 봅니다. artifact가 어떤 buildDefinition과 runDetails에서 나왔는지 설명하고, 외부 입력과 빌드 플랫폼 경계를 분리합니다. 초보 개발자 관점에서는 “패키지의 출생증명서”라고 보면 됩니다.

4. 설계 의도 해설

핵심 요약: trusted publishing의 핵심 의도는 비밀값을 더 잘 숨기는 것이 아니라, 배포 권한을 워크플로 신원으로 바꾸는 것입니다.

기존 npm token 방식은 단순합니다. CI secret에 토큰을 넣고, 배포 job이 그 토큰으로 npm에 publish합니다. 문제는 토큰이 길게 살아 있고, 로그·캐시·권한 오남용·퇴사자 계정 관리에서 계속 부담이 생긴다는 점입니다.

OIDC 방식은 반대로 동작합니다. npm 패키지 설정에 “이 저장소의 이 workflow 파일만 배포할 수 있다”는 신뢰 관계를 만들고, CI 실행 중 짧게 발급된 토큰을 교환합니다. 그래서 탈취해도 재사용하기 어렵고, 어떤 workflow가 배포했는지 추적하기 쉽습니다.

5. 근거 및 비교

핵심 요약: 보안 수준은 “서명을 켰는가”보다 토큰 수명, 실행 환경, 승인 단계, 검증 가능성의 조합으로 판단해야 합니다.

npm 문서 기준 trusted publishing은 npm CLI 11.5.1 이상과 Node 22.14.0 이상을 요구합니다. staged publishing은 npm CLI 11.15.0 이상과 Node 22.14.0 이상을 요구합니다. 이 숫자는 실제 전환 계획에서 빌드 이미지와 setup-node 버전을 정하는 기준점입니다.

6. 실제 동작 흐름 / 단계별 실행 방법

핵심 요약: 먼저 토큰 없는 publish 경로를 만들고, 그 다음 attestation 검증과 승인 루프를 붙이는 순서가 안전합니다.

1단계: npm 패키지 설정에서 trusted publisher 등록

npmjs.com의 패키지 설정에서 Trusted Publisher를 추가합니다. GitHub Actions를 쓴다면 organization/user, repository, workflow filename, 필요 시 environment name을 입력합니다. workflow filename은 전체 경로가 아니라 publish.yml 같은 파일명입니다.

2단계: GitHub Actions workflow 작성

name: Publish Package
on:
  push:
    tags:
      - 'v*'
permissions:
  contents: read
  id-token: write
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: '24'
          registry-url: 'https://registry.npmjs.org'
          package-manager-cache: false
      - run: npm ci
      - run: npm test
      - run: npm run build --if-present
      - run: npm publish

여기서 핵심은 permissions: id-token: write입니다. 이 권한이 있어야 GitHub Actions가 OIDC 토큰을 요청할 수 있습니다. trusted publishing이 설정되어 있으면 npm CLI가 OIDC 환경을 감지하고 전통적인 토큰 방식보다 먼저 사용합니다.

3단계: 기존 provenance 방식과 병행할 때

npm --version
node --version
npm publish --provenance --access public
npm audit signatures

third-party publish 도구를 쓰면 NPM_CONFIG_PROVENANCE=true, publishConfig.provenance=true, 또는 .npmrc의 provenance=true로 우회할 수 있습니다. 단, 이 설정은 “출처 증명”이지 “토큰 제거”가 아닐 수 있으므로 trusted publishing과 구분해야 합니다.

4단계: 고위험 패키지는 staged publishing으로 변경

npm stage publish
npm stage list @scope/package
npm stage view <stage-id>
npm stage download <stage-id>
npm stage approve <stage-id>

staged publishing은 CI가 바로 live registry에 올리지 않고 staging area에 제출합니다. maintainer가 tarball을 확인한 뒤 2FA로 approve해야 공개됩니다. 운영 속도보다 신뢰가 중요한 패키지에 적합합니다.

7. 실수/함정(Pitfalls)

핵심 요약: 대부분의 실패는 OIDC 권한, 러너 조건, repository metadata, 승인 권한을 대충 넘길 때 발생합니다.

• 실패 1: id-token: write 누락. OIDC 토큰이 발급되지 않아 npm이 trusted publishing 경로로 인증하지 못합니다. 예방은 workflow 상단에 최소 권한을 명시하는 것입니다. 복구는 실패한 release tag를 재실행하기 전에 권한을 추가하고 job log에서 OIDC 감지 여부를 확인하는 것입니다.
• 실패 2: self-hosted runner 사용. npm trusted publishing 문서는 현재 클라우드 호스티드 러너를 전제로 합니다. 예방은 publish job만 GitHub-hosted runner로 분리하는 것입니다. 복구는 build는 self-hosted에서 하더라도 publish artifact 검증 후 별도 hosted publish job으로 넘기는 구조를 검토합니다.
• 실패 3: package.json repository가 실제 출처와 불일치. provenance는 공개 repository 정보와 빌드 출처를 연결하므로 대소문자까지 맞춰야 합니다. 예방은 release 전 npm pack --dry-run과 package metadata 점검을 CI에 넣는 것입니다.
• 실패 4: provenance를 악성 코드 부재 보증으로 오해. provenance는 어디서 어떻게 만들어졌는지 보여줄 뿐, 코드가 안전하다는 판정서는 아닙니다. 예방은 CodeQL, dependency review, secret scan, tarball diff 검사를 함께 두는 것입니다.

8. 강점과 한계

핵심 요약: 이 접근은 배포 신뢰도를 크게 올리지만, 코드 리뷰와 취약점 분석을 대체하지 않습니다.

강점은 분명합니다. 장기 토큰을 줄이고, 배포 워크플로 신원을 고정하며, 소비자가 attestation과 registry signature를 검증할 수 있습니다. 특히 조직 공통 패키지처럼 downstream 영향이 큰 라이브러리에서 효과가 큽니다.

한계도 명확합니다. 악성 maintainer가 정상 workflow에서 악성 코드를 넣으면 provenance는 그것을 “정상 workflow에서 만들어졌다”고 말할 뿐입니다. 또 자체 호스팅 CI, 오래된 Node 이미지, 복잡한 monorepo release 도구는 전환 난이도가 높습니다.

9. 더 깊게 공부할 포인트

핵심 요약: npm 문서만 보지 말고 SLSA의 buildDefinition/runDetails 개념까지 같이 보면 운영 판단이 쉬워집니다.

• npm의 trusted publishing 설정 항목: 어떤 repository와 workflow를 신뢰할지 정합니다.
• SLSA provenance의 externalParameters: 사용자가 바꿀 수 있는 입력이 무엇인지 이해합니다.
• GitHub Actions OIDC claim: workflow, repository, ref, environment 같은 신원 정보가 토큰에 어떻게 들어가는지 봅니다.
• staged publishing: 자동화와 사람 승인 사이의 경계를 어디에 둘지 정합니다.

10. 실행 체크리스트 + 작성자 관점

핵심 요약: 저는 공개 패키지라면 token publish를 기본값에서 내리고, trusted publishing을 기본 배포 경로로 올리는 쪽을 추천합니다.

• package.json의 repository URL이 실제 공개 저장소와 대소문자까지 일치한다.
• publish workflow가 GitHub-hosted/GitLab shared/CircleCI cloud 같은 지원 환경에서 실행된다.
• Node 22.14.0 이상, npm CLI 11.5.1 이상을 쓰며 staged publishing이면 npm 11.15.0 이상을 쓴다.
• workflow에 contents: read와 id-token: write가 최소 권한으로 설정되어 있다.
• release tag 생성, test, build, publish 순서가 하나의 감사 가능한 흐름으로 남는다.
• npm audit signatures 결과를 릴리스 후 검증 로그로 보관한다.
• 보안 민감 패키지는 staged publishing으로 tarball review와 2FA approve를 분리한다.

Definition of Done: 새 release tag에서 토큰 없이 publish가 성공하고, 패키지 페이지와 npm audit signatures에서 registry signature와 attestation 검증 흔적을 확인할 수 있으면 1차 전환은 완료입니다.

작성자 관점에서는, 혼자 관리하는 작은 실험 패키지는 npm publish --provenance부터 시작해도 됩니다. 하지만 사용자가 있는 라이브러리, 조직 공통 SDK, 빌드 결과물이 여러 서비스에 들어가는 패키지는 trusted publishing을 우선 도입하는 편이 낫습니다. 배포 속도가 하루 몇 분 느려지는 것보다 장기 토큰 하나가 새는 비용이 훨씬 큽니다.

참고자료

• npm Docs: Trusted publishing for npm packages, 확인일 2026-07-08
• npm Docs: Generating provenance statements, 확인일 2026-07-08
• npm Docs: Staged publishing for npm packages, 확인일 2026-07-08
• npm Docs: About ECDSA registry signatures, 확인일 2026-07-08
• SLSA Specification v1.1: Provenance, 확인일 2026-07-08
• GitHub Docs: OpenID Connect, 확인일 2026-07-08

WRITING-STANDARD 자가채점