summaryrefslogtreecommitdiff
path: root/deps/npm/node_modules/npm-profile/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'deps/npm/node_modules/npm-profile/README.md')
-rw-r--r--deps/npm/node_modules/npm-profile/README.md216
1 files changed, 98 insertions, 118 deletions
diff --git a/deps/npm/node_modules/npm-profile/README.md b/deps/npm/node_modules/npm-profile/README.md
index 1937e23f72..7a80a729e8 100644
--- a/deps/npm/node_modules/npm-profile/README.md
+++ b/deps/npm/node_modules/npm-profile/README.md
@@ -4,9 +4,8 @@ Provides functions for fetching and updating an npmjs.com profile.
```js
const profile = require('npm-profile')
-profile.get(registry, {token}).then(result => {
- // …
-})
+const result = await profile.get(registry, {token})
+//...
```
The API that this implements is documented here:
@@ -14,22 +13,37 @@ The API that this implements is documented here:
* [authentication](https://github.com/npm/registry/blob/master/docs/user/authentication.md)
* [profile editing](https://github.com/npm/registry/blob/master/docs/user/profile.md) (and two-factor authentication)
-## Functions
+## Table of Contents
+
+* [API](#api)
+ * Login and Account Creation
+ * [`adduser()`](#adduser)
+ * [`login()`](#login)
+ * [`adduserWeb()`](#adduser-web)
+ * [`loginWeb()`](#login-web)
+ * [`adduserCouch()`](#adduser-couch)
+ * [`loginCouch()`](#login-couch)
+ * Profile Data Management
+ * [`get()`](#get)
+ * [`set()`](#set)
+ * Token Management
+ * [`listTokens()`](#list-tokens)
+ * [`removeToken()`](#remove-token)
+ * [`createToken()`](#create-token)
-### profile.adduser(opener, prompter, config) → Promise
+## API
+
+### <a name="adduser"></a> `> profile.adduser(opener, prompter, [opts]) → Promise`
Tries to create a user new web based login, if that fails it falls back to
using the legacy CouchDB APIs.
* `opener` Function (url) → Promise, returns a promise that resolves after a browser has been opened for the user at `url`.
* `prompter` Function (creds) → Promise, returns a promise that resolves to an object with `username`, `email` and `password` properties.
-* `config` Object
+* [`opts`](#opts) Object (optional) plus extra keys:
* `creds` Object, passed through to prompter, common values are:
* `username` String, default value for username
* `email` String, default value for email
- * `registry` String (for reference, the npm registry is `https://registry.npmjs.org`)
- * `opts` Object, [make-fetch-happen options](https://www.npmjs.com/package/make-fetch-happen#extra-options) for setting
- things like cache, proxy, SSL CA and retry rules.
#### **Promise Value**
@@ -50,21 +64,16 @@ on this account isn't allowed from then the `code` will be set to `EAUTHIP`.
Otherwise the code will be `'E'` followed by the HTTP response code, for
example a Forbidden response would be `E403`.
-### profile.login(opener, prompter, config) → Promise
+### <a name="login"></a> `> profile.login(opener, prompter, [opts]) → Promise`
Tries to login using new web based login, if that fails it falls back to
using the legacy CouchDB APIs.
* `opener` Function (url) → Promise, returns a promise that resolves after a browser has been opened for the user at `url`.
* `prompter` Function (creds) → Promise, returns a promise that resolves to an object with `username`, and `password` properties.
-* `config` Object
+* [`opts`](#opts) Object (optional) plus extra keys:
* `creds` Object, passed through to prompter, common values are:
* `name` String, default value for username
- * `registry` String (for reference, the npm registry is `https://registry.npmjs.org`)
- * `auth` Object, properties: `otp`
- the one-time password from a two-factor authentication device.
- * `opts` Object, [make-fetch-happen options](https://www.npmjs.com/package/make-fetch-happen#extra-options) for setting
- things like cache, proxy, SSL CA and retry rules.
#### **Promise Value**
@@ -89,16 +98,13 @@ on this account isn't allowed from then the `code` will be set to `EAUTHIP`.
Otherwise the code will be `'E'` followed by the HTTP response code, for
example a Forbidden response would be `E403`.
-### profile.adduserWeb(opener, config) → Promise
+### <a name="adduser-web"></a> `> profile.adduserWeb(opener, [opts]) → Promise`
Tries to create a user new web based login, if that fails it falls back to
using the legacy CouchDB APIs.
* `opener` Function (url) → Promise, returns a promise that resolves after a browser has been opened for the user at `url`.
-* `config` Object
- * `registry` String (for reference, the npm registry is `https://registry.npmjs.org`)
- * `opts` Object, [make-fetch-happen options](https://www.npmjs.com/package/make-fetch-happen#extra-options) for setting
- things like cache, proxy, SSL CA and retry rules.
+* [`opts`](#opts) Object
#### **Promise Value**
@@ -123,16 +129,13 @@ on this account isn't allowed from then the `code` will be set to `EAUTHIP`.
Otherwise the code will be `'E'` followed by the HTTP response code, for
example a Forbidden response would be `E403`.
-### profile.loginWeb(opener, config) → Promise
+### <a name="login-web"></a> `> profile.loginWeb(opener, [opts]) → Promise`
Tries to login using new web based login, if that fails it falls back to
using the legacy CouchDB APIs.
* `opener` Function (url) → Promise, returns a promise that resolves after a browser has been opened for the user at `url`.
-* `config` Object
- * `registry` String (for reference, the npm registry is `https://registry.npmjs.org`)
- * `opts` Object, [make-fetch-happen options](https://www.npmjs.com/package/make-fetch-happen#extra-options) for setting
- things like cache, proxy, SSL CA and retry rules.
+* [`opts`](#opts) Object (optional)
#### **Promise Value**
@@ -151,19 +154,17 @@ If the registry does not support web-login then an error will be thrown with
its `code` property set to `ENYI` . You should retry with `loginCouch`.
If you use `login` then this fallback will be done automatically.
-
If the action was denied because it came from an IP address that this action
on this account isn't allowed from then the `code` will be set to `EAUTHIP`.
Otherwise the code will be `'E'` followed by the HTTP response code, for
example a Forbidden response would be `E403`.
-### profile.adduserCouch(username, email, password, config) → Promise
+### <a name="adduser-couch"></a> `> profile.adduserCouch(username, email, password, [opts]) → Promise`
```js
-profile.adduser(username, email, password, {registry}).then(result => {
- // do something with result.token
-})
+const {token} = await profile.adduser(username, email, password, {registry})
+// `token` can be passed in through `opts` for authentication.
```
Creates a new user on the server along with a fresh bearer token for future
@@ -176,10 +177,7 @@ this is registry specific and not guaranteed.
* `username` String
* `email` String
* `password` String
-* `config` Object
- * `registry` String (for reference, the npm registry is `https://registry.npmjs.org`)
- * `opts` Object, [make-fetch-happen options](https://www.npmjs.com/package/make-fetch-happen#extra-options) for setting
- things like cache, proxy, SSL CA and retry rules.
+* [`opts`](#opts) Object (optional)
#### **Promise Value**
@@ -203,18 +201,19 @@ on this account isn't allowed from then the `code` will be set to `EAUTHIP`.
Otherwise the code will be `'E'` followed by the HTTP response code, for
example a Forbidden response would be `E403`.
-### profile.loginCouch(username, password, config) → Promise
+### <a name="login-couch"></a> `> profile.loginCouch(username, password, [opts]) → Promise`
```js
-profile.login(username, password, {registry}).catch(err => {
+let token
+try {
+ {token} = await profile.login(username, password, {registry})
+} catch (err) {
if (err.code === 'otp') {
- return getOTPFromSomewhere().then(otp => {
- return profile.login(username, password, {registry, auth: {otp}})
- })
+ const otp = await getOTPFromSomewhere()
+ {token} = await profile.login(username, password, {otp})
}
-}).then(result => {
- // do something with result.token
-})
+}
+// `token` can now be passed in through `opts` for authentication.
```
Logs you into an existing user. Does not create the user if they do not
@@ -224,12 +223,7 @@ future authentication. This is what you use as an `authToken` in an `.npmrc`.
* `username` String
* `email` String
* `password` String
-* `config` Object
- * `registry` String (for reference, the npm registry is `https://registry.npmjs.org`)
- * `auth` Object, properties: `otp` — the one-time password from a two-factor
- authentication device.
- * `opts` Object, [make-fetch-happen options](https://www.npmjs.com/package/make-fetch-happen#extra-options) for setting
- things like cache, proxy, SSL CA and retry rules.
+* [`opts`](#opts) Object (optional)
#### **Promise Value**
@@ -254,24 +248,16 @@ If the error was neither of these then the error object will have a
`code` property set to the HTTP response code and a `headers` property with
the HTTP headers in the response.
-### profile.get(config) → Promise
+### <a name="get"></a> `> profile.get([opts]) → Promise`
```js
-profile.get(registry, {auth: {token}}).then(userProfile => {
- // do something with userProfile
-})
+const {name, email} = await profile.get({token})
+console.log(`${token} belongs to https://npm.im/~${name}, (mailto:${email})`)
```
Fetch profile information for the authenticated user.
-* `config` Object
- * `registry` String (for reference, the npm registry is `https://registry.npmjs.org`)
- * `auth` Object, properties: `token` — a bearer token returned from
- `adduser`, `login` or `createToken`, or, `username`, `password` (and
- optionally `otp`). Authenticating for this command via a username and
- password will likely not be supported in the future.
- * `opts` Object, [make-fetch-happen options](https://www.npmjs.com/package/make-fetch-happen#extra-options) for setting
- things like cache, proxy, SSL CA and retry rules.
+* [`opts`](#opts) Object
#### **Promise Value**
@@ -313,24 +299,17 @@ on this account isn't allowed from then the `code` will be set to `EAUTHIP`.
Otherwise the code will be the HTTP response code.
-### profile.set(profileData, config) → Promise
+### <a name="set"></a> `> profile.set(profileData, [opts]) → Promise`
```js
-profile.set({github: 'great-github-account-name'}, {registry, auth: {token}})
+await profile.set({github: 'great-github-account-name'}, {token})
```
Update profile information for the authenticated user.
* `profileData` An object, like that returned from `profile.get`, but see
below for caveats relating to `password`, `tfa` and `cidr_whitelist`.
-* `config` Object
- * `registry` String (for reference, the npm registry is `https://registry.npmjs.org`)
- * `auth` Object, properties: `token` — a bearer token returned from
- `adduser`, `login` or `createToken`, or, `username`, `password` (and
- optionally `otp`). Authenticating for this command via a username and
- password will likely not be supported in the future.
- * `opts` Object, [make-fetch-happen options](https://www.npmjs.com/package/make-fetch-happen#extra-options) for setting
- things like cache, proxy, SSL CA and retry rules.
+* [`opts`](#opts) Object (optional)
#### **SETTING `password`**
@@ -340,7 +319,12 @@ and `new` properties, where the former has the user's current password and
the latter has the desired new password. For example
```js
-profile.set({password: {old: 'abc123', new: 'my new (more secure) password'}}, {registry, auth: {token}})
+await profile.set({
+ password: {
+ old: 'abc123',
+ new: 'my new (more secure) password'
+ }
+}, {token})
```
#### **SETTING `cidr_whitelist`**
@@ -350,7 +334,9 @@ Be very careful as it's possible to lock yourself out of your account with
this. This is not currently exposed in `npm` itself.
```js
-profile.set({cidr_whitelist: [ '8.8.8.8/32' ], {registry, auth: {token}})
+await profile.set({
+ cidr_whitelist: [ '8.8.8.8/32' ]
+}, {token})
// ↑ only one of google's dns servers can now access this account.
```
@@ -360,7 +346,7 @@ Enabling two-factor authentication is a multi-step process.
1. Call `profile.get` and check the status of `tfa`. If `pending` is true then
you'll need to disable it with `profile.set({tfa: {password, mode: 'disable'}, …)`.
-2. `profile.set({tfa: {password, mode}}, {registry, auth: {token}})`
+2. `profile.set({tfa: {password, mode}}, {registry, token})`
* Note that the user's `password` is required here in the `tfa` object,
regardless of how you're authenticating.
* `mode` is either `auth-only` which requires an `otp` when calling `login`
@@ -381,7 +367,7 @@ Enabling two-factor authentication is a multi-step process.
and they can type or copy paste that in.
4. To complete setting up two factor auth you need to make a second call to
`profile.set` with `tfa` set to an array of TWO codes from the user's
- authenticator, eg: `profile.set(tfa: [otp1, otp2]}, registry, {token})`
+ authenticator, eg: `profile.set(tfa: [otp1, otp2]}, {registry, token})`
5. On success you'll get a result object with a `tfa` property that has an
array of one-time-use recovery codes. These are used to authenticate
later if the second factor is lost and generally should be printed and
@@ -391,7 +377,7 @@ Disabling two-factor authentication is more straightforward, set the `tfa`
attribute to an object with a `password` property and a `mode` of `disable`.
```js
-profile.set({tfa: {password, mode: 'disable'}, {registry, auth: {token}}}
+await profile.set({tfa: {password, mode: 'disable'}}, {token})
```
#### **Promise Value**
@@ -412,24 +398,16 @@ on this account isn't allowed from then the `code` will be set to `EAUTHIP`.
Otherwise the code will be the HTTP response code.
-### profile.listTokens(config) → Promise
+### <a name="list-tokens"></a> `> profile.listTokens([opts]) → Promise`
```js
-profile.listTokens(registry, {token}).then(tokens => {
- // do something with tokens
-})
+const tokens = await profile.listTokens({registry, token})
+console.log(`Number of tokens in your accounts: ${tokens.length}`)
```
Fetch a list of all of the authentication tokens the authenticated user has.
-* `config` Object
- * `registry` String (for reference, the npm registry is `https://registry.npmjs.org`)
- * `auth` Object, properties: `token` — a bearer token returned from
- `adduser`, `login` or `createToken`, or, `username`, `password` (and
- optionally `otp`). Authenticating for this command via a username and
- password will likely not be supported in the future.
- * `opts` Object, [make-fetch-happen options](https://www.npmjs.com/package/make-fetch-happen#extra-options) for setting
- things like cache, proxy, SSL CA and retry rules.
+* [`opts`](#opts) Object (optional)
#### **Promise Value**
@@ -456,25 +434,17 @@ on this account isn't allowed from then the `code` will be set to `EAUTHIP`.
Otherwise the code will be the HTTP response code.
-### profile.removeToken(token|key, config) → Promise
+### <a name="remove-token"><a> `> profile.removeToken(token|key, opts) → Promise`
```js
-profile.removeToken(key, registry, {token}).then(() => {
- // token is gone!
-})
+await profile.removeToken(key, {token})
+// token is gone!
```
Remove a specific authentication token.
* `token|key` String, either a complete authentication token or the key returned by `profile.listTokens`.
-* `config` Object
- * `registry` String (for reference, the npm registry is `https://registry.npmjs.org`)
- * `auth` Object, properties: `token` — a bearer token returned from
- `adduser`, `login` or `createToken`, or, `username`, `password` (and
- optionally `otp`). Authenticating for this command via a username and
- password will likely not be supported in the future.
- * `opts` Object, [make-fetch-happen options](https://www.npmjs.com/package/make-fetch-happen#extra-options) for setting
- things like cache, proxy, SSL CA and retry rules.
+* [`opts`](#opts) Object (optional)
#### **Promise Value**
@@ -494,12 +464,13 @@ on this account isn't allowed from then the `code` will be set to `EAUTHIP`.
Otherwise the code will be the HTTP response code.
-### profile.createToken(password, readonly, cidr_whitelist, config) → Promise
+### <a name="create-token"></a> `> profile.createToken(password, readonly, cidr_whitelist, [opts]) → Promise`
```js
-profile.createToken(password, readonly, cidr_whitelist, registry, {token, otp}).then(newToken => {
- // do something with the newToken
-})
+const newToken = await profile.createToken(
+ password, readonly, cidr_whitelist, {token, otp}
+)
+// do something with the newToken
```
Create a new authentication token, possibly with restrictions.
@@ -507,21 +478,14 @@ Create a new authentication token, possibly with restrictions.
* `password` String
* `readonly` Boolean
* `cidr_whitelist` Array
-* `config` Object
- * `registry` String (for reference, the npm registry is `https://registry.npmjs.org`)
- * `auth` Object, properties: `token` — a bearer token returned from
- `adduser`, `login` or `createToken`, or, `username`, `password` (and
- optionally `otp`). Authenticating for this command via a username and
- password will likely not be supported in the future.
- * `opts` Object, [make-fetch-happen options](https://www.npmjs.com/package/make-fetch-happen#extra-options) for setting
- things like cache, proxy, SSL CA and retry rules.
+* [`opts`](#opts) Object Optional
#### **Promise Value**
The promise will resolve with an object very much like the one's returned by
`profile.listTokens`. The only difference is that `token` is not truncated.
-```
+```js
{
token: String,
key: String, // sha512 hash of the token UUID
@@ -545,12 +509,28 @@ on this account isn't allowed from then the `code` will be set to `EAUTHIP`.
Otherwise the code will be the HTTP response code.
-## Logging
+### <a name="opts"></a> options objects
+
+The various API functions accept an optional `opts` object as a final
+argument. This opts object can either be a regular Object, or a
+[`figgy-pudding`](https://npm.im/figgy-pudding) options object instance.
+
+Unless otherwise noted, the options accepted are the same as the
+[`npm-registry-fetch`
+options](https://www.npmjs.com/package/npm-registry-fetch#fetch-opts).
+
+Of particular note are `opts.registry`, and the auth-related options:
+
+* `opts.token` - used for Bearer auth
+* `opts.username` and `opts.password` - used for Basic auth
+* `opts.otp` - the 2fa OTP token
+
+## <a name="logging"></a> Logging
This modules logs by emitting `log` events on the global `process` object.
These events look like this:
-```
+```js
process.emit('log', 'loglevel', 'feature', 'message part 1', 'part 2', 'part 3', 'etc')
```
@@ -562,13 +542,13 @@ The remaining arguments are evaluated like `console.log` and joined together wit
A real world example of this is:
-```
- process.emit('log', 'http', 'request', '→',conf.method || 'GET', conf.target)
+```js
+ process.emit('log', 'http', 'request', '→', conf.method || 'GET', conf.target)
```
To handle the log events, you would do something like this:
-```
+```js
const log = require('npmlog')
process.on('log', function (level) {
return log[level].apply(log, [].slice.call(arguments, 1))
generated by cgit v1.2.3 (git 2.39.1) at 2024-05-01 13:18:50 +0000