Автентифікація & Параметри реєстру (.npmrc)

Параметри на цій сторінці необхідно налаштувати за допомогою файлів .npmrc. pnpm використовує інтерфейс командного рядка npm для публікації, тому ці налаштування мають бути у форматі, який може прочитати npm.

Докладніше про завантаження файлів .npmrc див. у команді pnpm config.

Щодо параметрів, які можна налаштувати у файлі pnpm-workspace.yaml, див. Налаштування (pnpm-workspace.yaml).

Змінні оточення#

Значення у файлах .npmrc можуть посилатися на змінні середовища за допомогою синтаксису `${NAME}.

Починаючи з v10.34.2, змінні середовища не розгортаються в проєкті та в робочому просторі файлів .npmrc (ті, що виділяються разом із репозиторієм) для наступних параметрів:

URL-адреси проксі та реєстру (registry, @scope:registry, proxy, https-proxy, http-proxy);
Ключі для URL-адреси (ключі, що починаються з //);
Значення облікових даних (_authToken, _auth, _password, username, tokenHelper, cert, key).

Налаштування, яке містить '${...}' заповнювач у будь-якій із цих позицій ігнорується, і pnpm виводить попередження. Файли .npmrc, що контролюються репозиторієм, не повинні мати можливості розгортати змінні середовища в URL-адреси, на які pnpm надсилає запити, або в облікові дані, що додаються до цих запитів — інакше зловмисний репозиторій може викрасти секретні дані з вашого середовища (наприклад, токени CI) і передати їх до реєстру, контрольованого зловмисником, під час встановлення (GHSA-3qhv-2rgh-x77r).

Якщо ваш проєкт базувався на зафіксованому '.npmrc', що містить рядок на кшталт '//registry.npmjs.org/:_authToken=${NPM_TOKEN}', замість цього перемістіть токен у довірене місце:

Запишіть токен до глобального файлу конфігурації перед встановленням (наприклад, в етапі CI):
```
pnpm config set //registry.npmjs.org/:_authToken "$NPM_TOKEN"
```
pnpm config set зазвичай пише у глобальний конфігураційний файл, а не у файл .npmrc проєкту, тому токен ніколи не потрапляє до репозиторію.
Або залиште рядок із замінником ${NPM_TOKEN}, але розмістіть його у файлі ~/.npmrc на рівні користувача, а не в репозиторії — там змінні середовища все ще розгортаються.
Або встановіть значення безпосередньо у змінній середовища без будь-якого жодного запису в .npmrc:
```
npm_config_//registry.npmjs.org/:_authToken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```
У GitHub Actions скрипт actions/setup-node із вхідним параметром registry-url записує налаштування автентифікації у файл .npmrc на рівні користувача (на який посилається змінна середовища NPM_CONFIG_USERCONFIG, яку враховує pnpm), тому автентифікація за допомогою змінної середовища NODE_AUTH_TOKEN продовжує працювати.
Якщо ви не можете легко внести зміни в конвеєр CI, ви можете оголосити проєкт .npmrc довіреним шляхом встановлення одної змінної середовища в середовищі CI (наприклад на рівні організації або на рівні робочого простору):
```
NPM_CONFIG_USERCONFIG=.npmrc
```
Це змушує pnpm читати .npmrc проєкту як конфігураційний файл рівня користувача (відносний шлях розвʼязується у робочій теці), тому змінні середовища в ньому розгортаються як раніше. Оскільки декларація довіри походить із середовища, а не з репозиторію, зловмисний репозиторій не може встановити її за вас.

небезпека

Використовуйте це лише в середовищах, які створюють виключно довірені репозиторії. Це повністю вимикає цей захист для отриманого репозиторію, включаючи обмеження, згідно з яким tokenHelper можна налаштовувати лише в конфігурації на рівні користувача.

Це ж правило поширюється на реєстр та проксі-сервери в проєкті або в робочому просторі .npmrc (registry, @scope:registry, proxy, https-proxy, http-proxy). Якщо ви використали змінну середовища для створення URL-адреси реєстру, вкажіть в налаштуваннях довірене джерело — ~/.npmrc користувача, глобальну конфігурацію (pnpm config set "<key>" <value>), опцію CLI або змінну середовища. Якщо URL-адреса не є секретною, ви також можете вказати розвʼязане значення безпосередньо в проєкті . pmrc, оскільки ігноруються тільки ${...} заповнювачі.

Налаштування реєстру#

registry#

Стандартно: https://registry.npmjs.org/
Тип: url**

Базова URL-адреса реєстру пакунків npm (включно з кінцевою косою рискою).

@jsr:registry#

Додано у: v10.9.0

Стандартно: https://npm.jsr.io/
Тип: url**

Базова URL-адреса реєстру пакунків JSR.

<scope>:registry#

Реєстр npm, який слід використовувати для пакунків вказаної області доступу. Наприклад, встановлення @babel:registry=https://example.com/packages/npm/ призведе до того, що при використанні pnpm add @babel/core або будь-якого пакунка з діапазоном @babel, пакунок буде отримано з https://example.com/packages/npm, а не зі стандартного реєстру.

Налаштування автентифікації#

<URL>:_authToken#

Визначає токен автентифікації на предʼявника, який буде використовуватися при доступі до вказаного реєстру. Наприклад:

//registry.npmjs.org/:_authToken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Ви також можете використовувати змінну оточення. Наприклад:

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

Починаючи з версії 10.34.2, змінні середовища розгортаються лише в довірених місцях (у файлі користувача ~/.npmrc, глобальній конфігурації, параметрах командного рядка та змінних середовища npm_config_*), а не у файлі .npmrc проєкту чи робочої області. Див. Змінні середовища.

Або ви можете використовувати змінну оточення безпосередньо, не змінюючи .npmrc взагалі:

npm_config_//registry.npmjs.org/:_authToken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

<URL>:tokenHelper#

Помічник токена — це виконуваний файл, який виводить токен авторизації. Його можна використовувати в ситуаціях, коли authToken не є постійним значенням, а регулярно оновлюється, коли скрипт або інший інструмент може використовувати наявний токен оновлення для отримання нового токену доступу.

Конфігурація шляху до помічника має бути абсолютним шляхом, без аргументів. З міркувань безпеки дозволено встановлювати це значення лише у файлі .npmrc користувача. Інакше проєкт може помістити значення у локальний файл .npmrc і запустити довільні виконувані файли.

Встановлення помічника токенів для стандартного реєстру:

tokenHelper=/home/ivan/token-generator

Встановлення помічника токена для вказаного реєстру:

//registry.corp.com:tokenHelper=/home/ivan/token-generator

Налаштування проксі#

https-proxy#

Стандартно: null
Тип: url**

Проксі-сервер для вихідних HTTPS-запитів. Якщо встановлено змінні оточення HTTPS_PROXY, https_proxy, HTTP_PROXY або http_proxy, замість них буде використано їхні значення.

Якщо URL-адреса вашого проксі містить імʼя користувача та пароль, переконайтеся, що вони закодовані в URL. Наприклад:

https-proxy=https://use%21r:pas%2As@my.proxy:1234/foo

Не кодуйте двокрапку (:) між іменем користувача та паролем.

http-proxy#

proxy#

Стандартно: null
Тип: url

Проксі для вихідних http-запитів. Якщо встановлено змінні оточення HTTP_PROXY або http_proxy, налаштування проксі будуть враховані базовою бібліотекою запитів.

local-address#

Стандартно: undefined
Тип: IP Address

IP-адреса локального інтерфейсу для підключення до реєстру npm.

maxsockets#

Стандартно: networkConcurrency x 3
Тип: Number

Максимальна кількість зʼєднань, які можна використовувати для одного джерела (комбінація протокол/хост/порт).

noproxy#

Стандартно: null
Типи: String

Розділений комами рядок розширень доменів, для яких не слід використовувати проксі-сервер.

Налаштування SSL#

strict-ssl#

Стандартно: true
Тип: Boolean

Чи потрібно робити перевірку SSL-ключів при запитах до реєстру через HTTPS.

Дивіться також параметр ca.

Налаштування сертифіката#

ca#

Стандартно: Сертифікат npm CA
Тип: Array або null

Сертифікат підпису центру сертифікації, якому довіряють для SSL-зʼєднань з реєстром. Значення повинні бути у форматі PEM (також відомий як «Base-64 кодований X.509 (.CER)»). Наприклад:

ca="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"

Встановіть значення null, щоб дозволити довіряти лише відомим реєстраторам, або певному сертифікату ЦС, щоб довіряти лише цьому конкретному центру сертифікації підписів.

Можна довіряти декільком центрам сертифікації, вказавши масив сертифікатів:

ca[]="..."
ca[]="..."

Дивіться також конфігурацію strict-ssl.

cafile#

Стандартно: null
Тип: path

Шлях до файлу, що містить один або декілька сертифікатів підпису центру сертифікації. Подібно до параметра ca, але дозволяє використовувати декілька центрів сертифікації, а також зберігати інформацію про центри сертифікації у файлі замість того, щоб вказувати її за допомогою CLI.

<URL>:cafile#

Визначає шлях до файлу центру сертифікації, який буде використовуватися при доступі до вказаного реєстру. Наприклад:

//registry.npmjs.org/:cafile=ca-cert.pem

<URL>:ca#

Додано у: v10.25.0

Визначте вбудований сертифікат центру сертифікації для вказаного реєстру. Значення має бути закодовано у форматі PEM, як і глобальний параметр ca, але воно застосовується лише до відповідної URL-адреси реєстру.

//registry.example.com/:ca=-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----

cert#

Стандартно: null
Тип: String

Клієнтський сертифікат, який потрібно передати при доступі до реєстру. Значення повинні бути у форматі PEM (також відомий як «Base-64 кодований X.509 (.CER)»). Наприклад:

cert="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"

Це не шлях до файлу сертифіката.

<URL>:cert#

Додано у: v10.25.0

Визначає вбудований сертифікат клієнта, який буде використовуватися при доступі до вказаного реєстру. Приклад:

//registry.example.com/:cert=-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----

<URL>:certfile#

Визначає шлях до файлу сертифіката, який буде використовуватися при доступі до вказаного реєстру. Наприклад:

//registry.npmjs.org/:certfile=server-cert.pem

key#

Стандартно: null
Тип: String

Ключ клієнта, який потрібно передати при доступі до реєстру. Значення повинні бути у форматі PEM (також відомий як «Base-64 кодований X.509 (.CER)»). Наприклад:

key="-----BEGIN PRIVATE KEY-----\nXXXX\nXXXX\n-----END PRIVATE KEY-----"

Це не шлях до файлу ключа. Використовуйте <URL>:keyfile, якщо вам потрібно посилатися на файлову систему, замість того, щоб вбудовувати ключ.

Цей параметр містить конфіденційну інформацію. Не записуйте його до локального файлу .npmrc, зафіксованого у репозиторії.

<URL>:key#

Додано у: v10.25.0

Визначає вбудований ключ клієнта для вказаної URL-адреси реєстру.

//registry.example.com/:key=-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----

<URL>:keyfile#

Визначає шлях до файлу клієнтського ключа, який буде використовуватися при доступі до вказаного реєстру. Наприклад:

//registry.npmjs.org/:keyfile=server-key.pem