diff options
Diffstat (limited to 'deps/npm/node_modules/npm-profile/README.md')
| -rw-r--r-- | deps/npm/node_modules/npm-profile/README.md | 216 |
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)) |