npm 복구 코드는 배포 직전에 쓰지 마라, 안전한 보관과 복구 순서

npm 복구 코드는 배포 직전에 쓰면 안 된다. 사용하지 않은 복구 코드로 로그인에 성공하면 계정에 72시간 보안 보류가 시작되고, 그동안 패키지 배포와 액세스 토큰 생성이 제한되기 때문이다.

평소에는 등록된 보안 키로 인증하고 복구 코드는 별도 비상 저장소에 둔다. 정상 인증이 불가능할 때만 코드를 사용한 뒤, 본인이 시작한 복구인지 확인하고 보류가 실제로 끝난 다음 계정 권한과 릴리스 산출물을 점검해 배포를 재개하는 순서가 안전하다.

정상 인증 수단과 복구 코드를 분리한다

npm 웹사이트에서 계정의 Two-Factor Authentication 설정을 열어 보안 키를 등록하면 복구 코드가 제공된다. npm의 2FA 설정 안내 는 코드를 두 번째 인증 장치가 아닌 안전한 위치에 복사하고 비밀번호 관리자를 이용하라고 권고한다. 각 코드는 한 번만 쓸 수 있으며 2FA 설정에서 확인하거나 새 세트를 생성할 수 있다.

분리의 기준은 주 인증 장치를 잃어도 복구 코드까지 함께 사라지지 않는가다. 보안 키와 같은 가방, 업무용 노트북의 다운로드 폴더, 휴대전화 메모 앱에만 저장하면 장치 분실이나 계정 탈취가 두 수단을 동시에 무력화할 수 있다. 프로젝트 저장소, CI 변수, 이슈, 빌드 로그, 공동 채팅방처럼 배포 관계자가 넓게 접근하는 곳에도 넣지 않는다.

팀이 쓰는 비밀 관리 저장소에 넣는다면 접근자는 실제 npm 계정 관리자와 비상 승인 담당자로 제한한다. 항목에는 대상 계정을 구분할 정보, 보관 책임자, 마지막 권한 검토 시점만 기록하고 코드 자체를 인수인계 문서에 복제하지 않는다. 저장 여부를 시험한다며 복구 로그인을 실행해서도 안 된다. 성공하는 순간 코드는 소모되고 보안 보류가 시작된다.

• 평소 사용할 보안 키가 정상 작동하는지 배포 전에 확인한다.
• 복구 코드는 보안 키와 다른 장치 또는 통제된 비밀 저장소에 둔다.
• 화면 캡처와 평문 파일 등 회수하기 어려운 사본을 만들지 않는다.
• 관리자 변경 시 저장소 접근 권한을 회수하고 남은 사본을 점검한다.

당번 인수인계에는 코드가 아니라 상태를 남긴다

릴리스 당번이 바뀌어도 복구 코드 문자열을 메신저로 넘기지 않는다. 인수인계할 내용은 새 담당자의 정상 보안 키 작동 여부, 비상 저장소 접근 승인 절차, 대체 배포 담당자, 계정 이상 신고 경로다. 관리자가 각자의 npm 계정과 2FA 수단을 쓰면 한 사람의 장치 분실이 공유 복구 코드 사용으로 번지는 상황도 줄일 수 있다.

담당자 교대, 노트북 초기화, 휴대전화 교체, 보안 키 반납이 있었다면 릴리스 당일보다 앞서 정상 인증을 확인한다. 로그인 세션이 남아 있다는 사실만으로는 충분하지 않다. 실제 2FA 요청을 등록된 수단으로 완료할 수 있어야 하며, 실패하면 복구 코드를 쓰기 전에 다른 등록 수단과 대체 담당자를 확인할 시간이 필요하다.

운영 기록에는 비밀 값 대신 결과를 남긴다. 예를 들면 ‘보안 키 인증 완료’, ‘비상 저장소 승인자 확인’, ‘대체 관리자 지정’, ‘복구 로그인 시 릴리스 중지’와 같이 적을 수 있다. CI/CD 배포 경로도 미리 검증하되, 사고 뒤 새 토큰을 발급해 해결한다는 계획에는 의존하지 않는다. 보류가 시작되면 토큰 생성 자체가 제한된다.

로그인이 막히면 의도된 복구인지 먼저 확인한다

보안 키가 동작하지 않는다고 곧바로 복구 코드를 입력하지 않는다. 다른 등록 보안 키, 브라우저의 WebAuthn 지원, 계정 식별 정보와 기존 로그인 세션을 먼저 확인한다. 장치나 브라우저 문제라면 복구 코드를 소모하거나 배포를 멈추지 않고 해결할 수 있다.

정상 인증 수단을 모두 사용할 수 없을 때는 예정된 배포와 긴급 패치에 미칠 영향을 릴리스 책임자에게 알린 뒤 코드 하나를 사용한다. npm의 계정 복구 절차 에 따르면 새 세트를 생성하면 이전 복구 코드는 모두 무효화되며, 보류 중에는 비밀번호 변경과 새 2FA 수단 추가는 가능하지만 기존 2FA 수단 변경, 패키지 설정·관리자 변경, 조직·팀 구성 변경은 제한된다.

1. 다른 보안 키와 기존 로그인 세션을 확인한다.
2. 복구 요청자와 계정 소유자가 같은 사람인지 별도 채널로 확인한다.
3. 릴리스 책임자에게 72시간 보류 가능성을 알린다.
4. 필요한 경우에만 사용하지 않은 코드 하나로 로그인하고 시각을 기록한다.
5. 로그인 알림과 계정 활동에서 예상하지 못한 변화를 확인한다.

본인이 시작하지 않은 로그인 알림이나 보안 보류가 보이면 단순한 장치 분실로 처리하지 않는다. 관련 알림과 시각을 보존하고 npm Support에 문의하며, 다른 관리자의 비밀을 공유하거나 계정 구성을 성급하게 바꾸지 않는다. 사용하지 않은 코드까지 노출됐다고 판단되면 계정 통제권을 확인한 뒤 세트 재생성을 검토한다.

72시간 보류 중에는 배포 우회를 시도하지 않는다

2026년 9월 9일부터 성공한 복구 코드 로그인에 따른 72시간 보류는 모든 npm 계정에 적용된다. GitHub의 npm 정책 변경 공지 는 이 기간에 패키지 배포와 액세스 토큰 생성 등 보안에 민감한 쓰기 작업이 중지되지만, 로그인과 패키지 탐색·설치는 계속 가능하다고 설명한다. 보류는 지원 요청 없이 자동으로 끝나며 조기에 해제할 수 없다.

따라서 실패한 배포를 단순 인증 오류로 보고 반복하거나 새 토큰과 관리자 변경으로 우회하려 해서는 안 된다. 또 보류 중 다른 복구 코드로 로그인해도 종료 시각은 연장되지 않지만, 이미 시작된 제한이 사라지는 것도 아니다. 계정에 표시된 상태와 실제 작업 결과를 기준으로 릴리스를 중지한다.

이 기간에는 레지스트리 쓰기가 필요 없는 검증을 마칠 수 있다. 릴리스 커밋과 태그 후보, package.json의 버전, 생성 산출물, 테스트 결과, 변경 기록을 다시 대조한다. 기존 공개 패키지는 계속 탐색하고 설치할 수 있으므로 이미 배포된 버전이 사라진 것으로 오판해 별도 조치를 만들 필요는 없다.

복구 코드를 쓰지 않았는데 배포가 갑자기 막혔다면 자동 만료만 기다리지 않는다. 계정이 침해됐을 가능성을 전제로 npm Support에 즉시 문의하고, 팀에서는 로그인 알림과 변경 흔적을 보존한다. 반대로 본인이 의도적으로 복구했다면 해제 요청을 반복하기보다 보류 종료와 계정 상태 확인을 준비한다.

제한 종료와 계정 상태를 확인한 뒤 배포한다

72시간이 지났다는 계산만으로 곧바로 npm publish를 실행하지 않는다. 먼저 정상 보안 키로 인증하고 보류 표시가 없어졌는지 확인한다. 이어 계정과 패키지 관리자, 조직·팀 권한, 배포 설정에서 예상하지 못한 변경이 없는지 점검한다. 이상 징후가 있으면 릴리스보다 지원 문의와 자격 증명 정리가 우선이다.

복구가 본인의 의도였고 계정 활동도 정상이라면 사용된 코드가 포함된 세트를 계속 보관할지 재생성할지 결정한다. 재생성하면 이전 세트 전체가 무효화되므로 비상 저장소를 새 세트로 교체하고 과거 사본을 폐기한다. 당번 문서에는 새 코드를 붙이지 말고 갱신 완료 사실과 접근 책임자만 남긴다.

마지막으로 보류 전에 승인한 릴리스와 현재 산출물이 같은지 대조한다. 커밋, 버전, 태그, 변경 기록, CI/CD가 사용하는 계정과 권한을 확인하고, 보류 기간에 추가된 수정이 있다면 일반 코드 검토와 빌드를 다시 거친다. 모든 확인이 끝난 뒤 기존의 정상 배포 경로로 배포하고 결과를 운영 기록에 남긴다.

1. 정상 보안 키로 npm 인증을 완료한다.
2. 72시간 보류가 실제로 종료됐는지 확인한다.
3. 계정 활동과 관리자·조직·팀 권한을 점검한다.
4. 필요하면 복구 코드 세트를 재생성하고 이전 사본을 폐기한다.
5. 릴리스 커밋, 버전, 태그와 산출물을 다시 승인한다.
6. 검증된 배포 경로로 게시하고 결과를 기록한다.

함께 읽기:

• CrowdStrike가 npm·PyPI 다운로드를 가로막는다…악성 코드 실행 전 차단
• npm 패키지에 OIDC 발행자 10개까지…직접 배포는 선택 사항