Chainguard Registry Auth for npm

This repository contains tools to simplify the process of working with npm/yarn packages using Chainguard authentication via chainctl.

Chainguard Registry Auth Module

The chainguard-registry-auth module is an npm package which allows you to configure npm/yarn to interact with private npm Chainguard Libraries using chainctl for authentication.

The module automatically retrieves credentials from chainctl auth token --audience=libraries.cgr.dev and configures your npm/yarn environment to use these credentials with the username _token.

Prerequisites

• chainctl must be installed
• You must be authenticated via chainctl auth login

Usage

1. Log in with chainctl

chainctl auth login

2. Add registry settings to .npmrc / .yarnrc.yml

For npm (and .npmrc)

Add the following to your .npmrc file:

registry=https://libraries.cgr.dev
//libraries.cgr.dev/:always-auth=true

For yarn (and .yarnrc.yml)

Add the following to your .yarnrc.yml file:

npmScopes:
  workspace:
    npmRegistryServer: 'https://libraries.cgr.dev'
    npmAlwaysAuth: true
    npmAuthToken: 'empty'

3. Run the authentication script

Option 1: Run directly with npx

For npm:

npx chainguard-registry-auth --repo-config=./.npmrc --credential-config=~/.npmrc

For yarn:

npx chainguard-registry-auth --repo-config-yarn=./.yarnrc.yml --credential-config-yarn=~/.yarnrc.yml

Option 2: Add to package.json scripts

For npm, add to your package.json:

"scripts": {
  "chainguard-login": "npx chainguard-registry-auth --repo-config=./.npmrc --credential-config=~/.npmrc"
}

For yarn:

"scripts": {
  "chainguard-login": "npx chainguard-registry-auth --repo-config-yarn=./.yarnrc.yml --credential-config-yarn=~/.yarnrc.yml"
}

Then run:

npm run chainguard-login

Option 3: Install as a dev dependency

If npx is not available, install the module as a dev dependency:

npm install chainguard-registry-auth --save-dev

For npm, add to your package.json:

"scripts": {
  "chainguard-login": "./node_modules/.bin/chainguard-registry-auth --repo-config=./.npmrc --credential-config=~/.npmrc"
}

For yarn:

"scripts": {
  "chainguard-login": "./node_modules/.bin/chainguard-registry-auth --repo-config-yarn=./.yarnrc.yml --credential-config-yarn=~/.yarnrc.yml"
}

Then run:

npm run chainguard-login

Command-line Options

• --repo-config - Path to the .npmrc file with your repository settings. Defaults to the project-level .npmrc if it exists, otherwise the user-level .npmrc file.
• --credential-config - Path to the .npmrc file where you want to write the access token. Defaults to your user .npmrc file (~/.npmrc).
• --repo-config-yarn - Path to the .yarnrc.yml file with your repository settings. Defaults to the project-level .yarnrc.yml if it exists, otherwise the user-level .yarnrc.yml file.
• --credential-config-yarn - Path to the .yarnrc.yml file where you want to write the access token. Defaults to your user .yarnrc.yml file.
• --token - If set, use this token directly instead of calling chainctl auth token.
• --allow-all-domains - If set, allows the auth token to be attached to any registry domains, not just libraries.cgr.dev.
• --verbose - Enable verbose logging.

How It Works

1. The module calls chainctl auth token --audience=libraries.cgr.dev to retrieve a fresh authentication token
2. It configures npm/yarn to use this token with the username _token
3. Project-level configuration files (.npmrc or .yarnrc.yml) store registry URLs
4. User-level configuration files store the authentication credentials separately
5. This separation allows you to commit registry settings without exposing credentials