0
# Credential Management
1
2
Registry authentication and credential handling with URI-based scoping for secure access to npm registries and private repositories.
3
4
## Capabilities
5
6
### Get Credentials by URI
7
8
Retrieve authentication credentials for a specific registry URI.
9
10
```javascript { .api }
11
/**
12
* Get credentials for a registry URI
13
* @param uri - Registry URI to get credentials for
14
* @returns Credentials object or null if no credentials found
15
*/
16
getCredentialsByURI(uri: string): Credentials | null;
17
18
interface Credentials {
19
/** Authentication token */
20
token?: string;
21
/** Username for basic authentication */
22
username?: string;
23
/** Password for basic authentication */
24
password?: string;
25
/** Email address associated with credentials */
26
email?: string;
27
/** Base64 encoded username:password for basic auth */
28
auth?: string;
29
/** Path to client certificate file */
30
certfile?: string;
31
/** Path to client key file */
32
keyfile?: string;
33
}
34
```
35
36
**Usage Examples:**
37
38
```javascript
39
// Get credentials for npm registry
40
const creds = config.getCredentialsByURI('https://registry.npmjs.org/');
41
if (creds && creds.token) {
42
console.log('Found auth token for npm registry');
43
}
44
45
// Get credentials for private registry
46
const privateCreds = config.getCredentialsByURI('https://npm.company.com/');
47
if (privateCreds) {
48
if (privateCreds.username && privateCreds.password) {
49
console.log('Found username/password credentials');
50
}
51
if (privateCreds.auth) {
52
console.log('Found basic auth credentials');
53
}
54
}
55
```
56
57
### Set Credentials by URI
58
59
Set authentication credentials for a specific registry URI.
60
61
```javascript { .api }
62
/**
63
* Set credentials for a registry URI
64
* @param uri - Registry URI to set credentials for
65
* @param credentials - Credentials object to store
66
*/
67
setCredentialsByURI(uri: string, credentials: Credentials): void;
68
```
69
70
**Usage Examples:**
71
72
```javascript
73
// Set token-based authentication
74
config.setCredentialsByURI('https://registry.npmjs.org/', {
75
token: 'npm_1234567890abcdef',
76
email: 'user@example.com'
77
});
78
79
// Set username/password authentication
80
config.setCredentialsByURI('https://npm.company.com/', {
81
username: 'john.doe',
82
password: 'secret123',
83
email: 'john.doe@company.com'
84
});
85
86
// Set certificate-based authentication
87
config.setCredentialsByURI('https://secure-registry.com/', {
88
certfile: '/path/to/client.crt',
89
keyfile: '/path/to/client.key'
90
});
91
92
// Set basic auth credentials
93
config.setCredentialsByURI('https://basic-registry.com/', {
94
auth: Buffer.from('username:password').toString('base64')
95
});
96
```
97
98
### Clear Credentials by URI
99
100
Remove authentication credentials for a specific registry URI.
101
102
```javascript { .api }
103
/**
104
* Clear credentials for a registry URI
105
* @param uri - Registry URI to clear credentials for
106
*/
107
clearCredentialsByURI(uri: string): void;
108
```
109
110
**Usage Examples:**
111
112
```javascript
113
// Clear credentials for npm registry
114
config.clearCredentialsByURI('https://registry.npmjs.org/');
115
116
// Clear credentials for private registry
117
config.clearCredentialsByURI('https://npm.company.com/');
118
```
119
120
### Credential Scoping
121
122
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.
123
124
**Nerf-dart URI Processing:**
125
126
```javascript
127
// Example nerf-dart transformations:
128
// https://registry.npmjs.org/ → //registry.npmjs.org/:_authToken
129
// https://npm.company.com/ → //npm.company.com/:_authToken
130
// https://registry.npmjs.org/@scope/ → @scope:registry
131
```
132
133
**Configuration Key Patterns:**
134
135
```javascript
136
// Token authentication
137
'//registry.npmjs.org/:_authToken' = 'npm_token_here'
138
139
// Username/password authentication
140
'//npm.company.com/:username' = 'john.doe'
141
'//npm.company.com/:_password' = 'secret123'
142
143
// Basic auth
144
'//basic-registry.com/:_auth' = 'dXNlcm5hbWU6cGFzc3dvcmQ='
145
146
147
'//registry.npmjs.org/:email' = 'user@example.com'
148
149
// Certificate files
150
'//secure-registry.com/:certfile' = '/path/to/client.crt'
151
'//secure-registry.com/:keyfile' = '/path/to/client.key'
152
153
// Scoped registry mapping
154
'@company:registry' = 'https://npm.company.com/'
155
```
156
157
### Authentication Methods
158
159
The credential system supports multiple authentication methods:
160
161
**Token Authentication (recommended):**
162
- Most secure method for npm registries
163
- Uses `_authToken` configuration key
164
- Typically obtained from `npm login` or registry provider
165
166
**Username/Password Authentication:**
167
- Uses `username` and `_password` configuration keys
168
- Less secure than tokens
169
- May be required for some private registries
170
171
**Basic Authentication:**
172
- Uses `_auth` configuration key with base64-encoded credentials
173
- Legacy authentication method
174
- Format: `base64(username:password)`
175
176
**Certificate Authentication:**
177
- Uses `certfile` and `keyfile` configuration keys
178
- For registries requiring client certificates
179
- Paths to PEM-formatted certificate and key files
180
181
**Usage Example - Complete Authentication Setup:**
182
183
```javascript
184
const { Config } = require('@npmcli/config');
185
186
// Create config instance
187
const config = new Config({
188
definitions: { /* ... */ },
189
npmPath: process.cwd()
190
});
191
192
await config.load();
193
194
// Set up authentication for multiple registries
195
config.setCredentialsByURI('https://registry.npmjs.org/', {
196
token: process.env.NPM_TOKEN,
197
email: 'developer@company.com'
198
});
199
200
config.setCredentialsByURI('https://npm.company.com/', {
201
username: 'john.doe',
202
password: process.env.COMPANY_NPM_PASSWORD,
203
email: 'john.doe@company.com'
204
});
205
206
// Save credentials to user configuration
207
await config.save('user');
208
209
// Verify credentials are accessible
210
const npmCreds = config.getCredentialsByURI('https://registry.npmjs.org/');
211
const companyCreds = config.getCredentialsByURI('https://npm.company.com/');
212
213
console.log('NPM registry auth:', npmCreds ? 'configured' : 'missing');
214
console.log('Company registry auth:', companyCreds ? 'configured' : 'missing');
215
```
216
217
### Error Handling
218
219
Credential operations may throw authentication-related errors:
220
221
```javascript { .api }
222
const { ErrInvalidAuth } = require('@npmcli/config/lib/errors');
223
224
// Example error handling
225
try {
226
config.setCredentialsByURI('https://registry.npmjs.org/', {
227
token: 'invalid-token-format'
228
});
229
} catch (error) {
230
if (error instanceof ErrInvalidAuth) {
231
console.error(`Authentication error for ${error.registry}: ${error.message}`);
232
}
233
}
234
```