English

Работа с NPM¶

CodeScoring.Save реализует npm Registry API с префиксом /npm/<project>/<repository>/. Совместим со стандартными клиентами npm, yarn и pnpm.

Proxy-репозиторий¶

curl -X POST https://save.example.com/api/v1/repos \
  -H "Content-Type: application/json" \
  -u "<username>:<password>" \
  -d '{
    "project": "frontend",
    "name": "npmjs-proxy",
    "format": "npm",
    "repository_type": "proxy",
    "remote_url": "https://registry.npmjs.org",
    "cache_ttl": 3600
  }'

Hosted-репозиторий¶

curl -X POST https://save.example.com/api/v1/repos \
  -H "Content-Type: application/json" \
  -u "<username>:<password>" \
  -d '{
    "project": "frontend",
    "name": "npm-hosted",
    "format": "npm",
    "repository_type": "hosted"
  }'

Настройка клиента¶

npm¶

# Установка registry в текущем проекте
echo "registry=https://save.example.com/npm/<project>/npmjs-proxy/" > .npmrc

# Аутентификация (npm 7+, _auth — base64(username:password))
NPM_AUTH=$(echo -n "<username>:<password>" | base64)
cat >> .npmrc << EOF
//save.example.com/npm/<project>/npmjs-proxy/:_auth=${NPM_AUTH}
//save.example.com/npm/<project>/npmjs-proxy/:always-auth=true
EOF

# Установка зависимости
npm install lodash

Robot-аккаунты в CI

Для CI/CD используйте robot-аккаунт: username = sa$<robot-name>, password = <api-key>. Структура .npmrc не меняется — отличается только значение _auth (base64 от sa$<robot-name>:<api-key>). Подробнее — в общем разделе Аутентификация.

Opaque bearer-токены

npm-клиент после npm adduser / npm login сохраняет полученный opaque-токен и далее использует его как Authorization: Bearer <token>. cs-auth классифицирует любой не-JWT bearer-токен (Bearer-значение без трёх сегментов через точку) как npm_token и валидирует через сервис-аккаунты, привязанные к API-ключам.

Публикация в hosted-репозиторий:

cat > .npmrc << EOF
registry=https://save.example.com/npm/<project>/npm-hosted/
//save.example.com/npm/<project>/npm-hosted/:_auth=${NPM_AUTH}
//save.example.com/npm/<project>/npm-hosted/:always-auth=true
EOF

npm publish

yarn¶

Yarn Classic (1.x)¶

Yarn 1.x использует тот же .npmrc, что и npm:

echo "registry=https://save.example.com/npm/<project>/npmjs-proxy/" > .npmrc
yarn install

Yarn 2+ (Berry)¶

В .yarnrc.yml:

npmRegistryServer: "https://save.example.com/npm/<project>/npmjs-proxy/"

npmRegistries:
  "https://save.example.com/npm/<project>/npmjs-proxy/":
    npmAlwaysAuth: true
    npmAuthIdent: "<username>:<password>"

pnpm¶

pnpm читает тот же .npmrc:

echo "registry=https://save.example.com/npm/<project>/npmjs-proxy/" > .npmrc
pnpm install

Для scoped-пакетов можно настроить отдельный registry:

echo "@mycompany:registry=https://save.example.com/npm/<project>/npm-hosted/" >> .npmrc

Миграция URL репозитория¶

Сценарий использования: миграция npm-репозитория с Nexus / Artifactory на CodeScoring.Save.

Источник	`.npmrc` `registry=` до миграции	`.npmrc` `registry=` после миграции
Nexus	`https://nexus.host.ru/repository/npm-proxy`	`https://save.example.com/npm/<project>/npmjs-proxy/`
Artifactory	`https://jfrog.host.ru/artifactory/api/npm/npm-remote`	`https://save.example.com/npm/<project>/npmjs-proxy/`
Официальный репозиторий	`https://registry.npmjs.org`	`https://save.example.com/npm/<project>/npmjs-proxy/`

При миграции достаточно заменить URL в .npmrc/.yarnrc.yml. Существующие credentials Nexus/Artifactory можно переиспользовать как Basic Auth.

Устранение неполадок¶

Проверка метаданных пакета¶

curl -u "<username>:<password>" \
  https://save.example.com/npm/<project>/npmjs-proxy/lodash | jq .

Whoami / ping¶

curl -u "<username>:<password>" \
  https://save.example.com/npm/<project>/npmjs-proxy/-/whoami

curl -u "<username>:<password>" \
  https://save.example.com/npm/<project>/npmjs-proxy/-/ping

Состояние сервиса¶

curl https://save.example.com/health

Аудит по репозиторию¶

curl -u "<username>:<password>" \
  "https://save.example.com/api/v1/admin/audit?resource_type=repository&q=npmjs-proxy&limit=50"

Страница была полезна?