tessl/npm-npmcli--config

Configuration management for the npm command-line interface with hierarchical layered configuration system.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Credential Management

Name: tessl/npm-npmcli--config
Author: tessl

Registry authentication and credential handling with URI-based scoping for secure access to npm registries and private repositories.

Capabilities

Get Credentials by URI

Retrieve authentication credentials for a specific registry URI.

/**
 * Get credentials for a registry URI
 * @param uri - Registry URI to get credentials for
 * @returns Credentials object or null if no credentials found
 */
getCredentialsByURI(uri: string): Credentials | null;

interface Credentials {
  /** Authentication token */
  token?: string;
  /** Username for basic authentication */
  username?: string;
  /** Password for basic authentication */
  password?: string;
  /** Email address associated with credentials */
  email?: string;
  /** Base64 encoded username:password for basic auth */
  auth?: string;
  /** Path to client certificate file */
  certfile?: string;
  /** Path to client key file */
  keyfile?: string;
}

Usage Examples:

// Get credentials for npm registry
const creds = config.getCredentialsByURI('https://registry.npmjs.org/');
if (creds && creds.token) {
  console.log('Found auth token for npm registry');
}

// Get credentials for private registry
const privateCreds = config.getCredentialsByURI('https://npm.company.com/');
if (privateCreds) {
  if (privateCreds.username && privateCreds.password) {
    console.log('Found username/password credentials');
  }
  if (privateCreds.auth) {
    console.log('Found basic auth credentials');
  }
}

Set Credentials by URI

Set authentication credentials for a specific registry URI.

/**
 * Set credentials for a registry URI
 * @param uri - Registry URI to set credentials for
 * @param credentials - Credentials object to store
 */
setCredentialsByURI(uri: string, credentials: Credentials): void;

Usage Examples:

// Set token-based authentication
config.setCredentialsByURI('https://registry.npmjs.org/', {
  token: 'npm_1234567890abcdef',
  email: 'user@example.com'
});

// Set username/password authentication
config.setCredentialsByURI('https://npm.company.com/', {
  username: 'john.doe',
  password: 'secret123',
  email: 'john.doe@company.com'
});

// Set certificate-based authentication
config.setCredentialsByURI('https://secure-registry.com/', {
  certfile: '/path/to/client.crt',
  keyfile: '/path/to/client.key'
});

// Set basic auth credentials
config.setCredentialsByURI('https://basic-registry.com/', {
  auth: Buffer.from('username:password').toString('base64')
});

Clear Credentials by URI

Remove authentication credentials for a specific registry URI.

/**
 * Clear credentials for a registry URI
 * @param uri - Registry URI to clear credentials for
 */
clearCredentialsByURI(uri: string): void;

Usage Examples:

// Clear credentials for npm registry
config.clearCredentialsByURI('https://registry.npmjs.org/');

// Clear credentials for private registry
config.clearCredentialsByURI('https://npm.company.com/');

Credential Scoping

Credentials are scoped using the nerf-dart algorithm, which converts registry URIs into configuration keys. This ensures that credentials are properly isolated between different registries and scopes.

Nerf-dart URI Processing:

// Example nerf-dart transformations:
// https://registry.npmjs.org/ → //registry.npmjs.org/:_authToken
// https://npm.company.com/    → //npm.company.com/:_authToken
// https://registry.npmjs.org/@scope/ → @scope:registry

Configuration Key Patterns:

// Token authentication
'//registry.npmjs.org/:_authToken' = 'npm_token_here'

// Username/password authentication  
'//npm.company.com/:username' = 'john.doe'
'//npm.company.com/:_password' = 'secret123'

// Basic auth
'//basic-registry.com/:_auth' = 'dXNlcm5hbWU6cGFzc3dvcmQ='

// Email
'//registry.npmjs.org/:email' = 'user@example.com'

// Certificate files
'//secure-registry.com/:certfile' = '/path/to/client.crt'
'//secure-registry.com/:keyfile' = '/path/to/client.key'

// Scoped registry mapping
'@company:registry' = 'https://npm.company.com/'

Authentication Methods

The credential system supports multiple authentication methods:

Token Authentication (recommended):

Most secure method for npm registries
Uses _authToken configuration key
Typically obtained from npm login or registry provider

Username/Password Authentication:

Uses username and _password configuration keys
Less secure than tokens
May be required for some private registries

Basic Authentication:

Uses _auth configuration key with base64-encoded credentials
Legacy authentication method
Format: base64(username:password)

Certificate Authentication:

Uses certfile and keyfile configuration keys
For registries requiring client certificates
Paths to PEM-formatted certificate and key files

Usage Example - Complete Authentication Setup:

const { Config } = require('@npmcli/config');

// Create config instance
const config = new Config({
  definitions: { /* ... */ },
  npmPath: process.cwd()
});

await config.load();

// Set up authentication for multiple registries
config.setCredentialsByURI('https://registry.npmjs.org/', {
  token: process.env.NPM_TOKEN,
  email: 'developer@company.com'
});

config.setCredentialsByURI('https://npm.company.com/', {
  username: 'john.doe',
  password: process.env.COMPANY_NPM_PASSWORD,
  email: 'john.doe@company.com'
});

// Save credentials to user configuration
await config.save('user');

// Verify credentials are accessible
const npmCreds = config.getCredentialsByURI('https://registry.npmjs.org/');
const companyCreds = config.getCredentialsByURI('https://npm.company.com/');

console.log('NPM registry auth:', npmCreds ? 'configured' : 'missing');
console.log('Company registry auth:', companyCreds ? 'configured' : 'missing');

Error Handling

Credential operations may throw authentication-related errors:

const { ErrInvalidAuth } = require('@npmcli/config/lib/errors');

// Example error handling
try {
  config.setCredentialsByURI('https://registry.npmjs.org/', {
    token: 'invalid-token-format'
  });
} catch (error) {
  if (error instanceof ErrInvalidAuth) {
    console.error(`Authentication error for ${error.registry}: ${error.message}`);
  }
}

Install with Tessl CLI