{"_id":"@cox-automotive/clortho","_rev":"2-9bd2de3410da0ca2126bc92677bb6d3f","name":"@cox-automotive/clortho","dist-tags":{"latest":"1.2.2"},"versions":{"1.2.2":{"name":"@cox-automotive/clortho","version":"1.2.2","keywords":["keychain","password"],"author":{"name":"zetlen"},"license":"ISC","_id":"@cox-automotive/clortho@1.2.2","maintainers":[{"name":"brianantonelli","email":"brian.antonelli@gmail.com"},{"name":"pofallon","email":"paul@ofallonfamily.com"},{"name":"wbarker","email":"robert.barker@coxautoinc.com"},{"name":"ekozlowski","email":"ekozlowski1@gmail.com"},{"name":"americk0","email":"ben.watson.developer@gmail.com"},{"name":"goistjt","email":"jtgoist@gmail.com"},{"name":"amagana286","email":"andrew.magana@coxautoinc.com"},{"name":"ntangy","email":"nick.tang@coxautoinc.com"}],"homepage":"https://github.com/zetlen/clortho#readme","bugs":{"url":"https://github.com/zetlen/clortho/issues"},"dist":{"shasum":"ea258b62bbf33ed627ec489fd16865971ce3970c","tarball":"https://registry.npmjs.org/@cox-automotive/clortho/-/clortho-1.2.2.tgz","fileCount":30,"integrity":"sha512-1tLLkLP1vGOFXW0EnGjALgvcmECiglYp9kNiw6HTH7Hc+SXdev19iotn/NqOnW3FHpx3wh8ttoYsNW8UnUR/0A==","signatures":[{"sig":"MEQCIBSQZMkdibywMgEO5EvsY80XZUb1ydWHN4WTWeaf7CIRAiA6sgqlSavb8jIOr+477QurN5+IYpRp5WeBhEowwqEmAg==","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":67843,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJgy6/CCRA9TVsSAnZWagAApzwP/iFVzfV6hPvB6Sh+ygTC\nNWtbXKXvpW7G1vtgEtYs9kgFZe4V2bIIzYensM6yXG/vLlJSZ4VgCYBLCxvo\n4yWrL7FDbU6dwD3ywAav239j7xcVxeg0zLIszhDfSEPSljEr9QPurPcQtjlB\n74QdfyeQQwjK6eS0ZkuQ+S0xwyFYxe4af586YPjQunBgU4mCh7B1F1GE88I0\nOUte+TEqnCVvQ0GXHu95UQADWiuzoUxHwEcVZg8WZWG4MZozVzAB+wd35FJV\nRyP2v/i0w9s3kedxQa3Hbs/l+QRwv8lQFaYWD3i4bGAWLpHF740PYzi8gX/2\njBHFfnqvoCAzDIzp9HS1VhqAbKDyuDdPMdL5aMOGDtBZWYZrcMGy/BQLZ+g8\nqXRPSWBx8XxrS6rCZwPDJscesj9Fj6FS5GPjNzsLeHZdxlgbuNEQ1mdnZsQU\nA/8pAob5+kg/zvcRoCWYmfhAHYI6nUp2HoT0fHjjkUIIx5Nz57/pKqiQWSPJ\nq4zjCaA3ChvZLMQ3ud3XAPsq/eBpGMN/R3GXipAwhOi7wAD0WlbFDMcKvD86\nLL9awIvgGGIKR8vv9f+6Me7WrOu7Ydm/m7mlS5dEr3Hel51XgVB4mDhMpLs0\nF6xjth71KR69iNMwiMoR84Ivn0/RuYCLFts4WvfRJYlYERqk00rW92h4lQMK\npngC\r\n=l4mn\r\n-----END PGP SIGNATURE-----\r\n"},"main":"lib/index.js","babel":{"presets":["es2015"]},"engines":{"node":">=4.0.0"},"gitHead":"77cf4c6970c6c787ccf07f97896656fa0ac61db6","scripts":{"lint":"semistandard **/*.js","tape":"tape ./test/**/*.js","test":"npm run lint && npm run babel && npm run tape","babel":"babel src -d lib","version":"git add -A .","lint-fix":"semistandard --fix **/*.js","preversion":"npm run test"},"_npmUser":{"name":"ntangy","email":"nick.tang@coxautoinc.com"},"repository":{"url":"git+https://github.com/zetlen/clortho.git","type":"git"},"_npmVersion":"7.5.6","description":"friendly, OS-appropriate password handling for node scripts","directories":{},"_nodeVersion":"14.4.0","dependencies":{"which":"^1.2.0","inquirer":"^7.3.3","keychain":"^1.0.0","js-string-escape":"^1.0.0"},"semistandard":{"ignore":"lib/**","parser":"babel-eslint"},"_hasShrinkwrap":false,"devDependencies":{"tape":"^4.2.2","babel-cli":"^6.3.15","babel-eslint":"^10.1.0","semistandard":"*","babel-preset-es2015":"^6.3.13"},"_npmOperationalInternal":{"tmp":"tmp/clortho_1.2.2_1623961537851_0.23491063724843908","host":"s3://npm-registry-packages"}}},"time":{"created":"2021-06-17T20:25:37.555Z","modified":"2024-11-06T18:20:57.105Z","1.2.2":"2021-06-17T20:25:38.044Z"},"bugs":{"url":"https://github.com/zetlen/clortho/issues"},"author":{"name":"zetlen"},"license":"ISC","homepage":"https://github.com/zetlen/clortho#readme","keywords":["keychain","password"],"repository":{"url":"git+https://github.com/zetlen/clortho.git","type":"git"},"description":"friendly, OS-appropriate password handling for node scripts","maintainers":[{"email":"brian.antonelli@gmail.com","name":"brianantonelli"},{"email":"paul@ofallonfamily.com","name":"pofallon"},{"email":"robert.barker@coxautoinc.com","name":"wbarker"},{"email":"ekozlowski1@gmail.com","name":"ekozlowski"},{"email":"ben.watson.developer@gmail.com","name":"americk0"},{"email":"jtgoist@gmail.com","name":"goistjt"}],"readme":"![The destructor is coming!](http://i.imgur.com/RiMmYgU.png])\n\n[![js-semistandard-style](https://img.shields.io/badge/code%20style-semistandard-brightgreen.svg?style=flat-square)](https://github.com/Flet/semistandard)\n\n![Travis CI](https://travis-ci.org/zetlen/clortho.svg)\n\n**Clortho** is a library for asking for service passwords from node scripts. It is [not](https://github.com/pivotal/vinz-clortho) the [first](https://github.com/mozilla/vinz-clortho) library to be named after Louis Tully, but I chose a new form for him: that of a giant Slor!\n\n#### Use Clortho if:\n - You're using Node as a scripting language with user interaction, such as a Yeoman generator, or a Grunt or Gulp plugin.\n - You need to prompt the user for a password to some external service.\n - You want to prompt the user in a friendly way, using GUI tools where available.\n - You want to store the password securely.\n \n*Clortho combines keychain authentication with user prompting, so if user interaction isn't a part of your app--that is, if it's a server--then Clortho is not appropriate. If you just want keychain access, you're looking for [node-keytar][1].*\n\n### Usage\n\n`clortho` is a function that returns a promise for a credential. A credential is an object with `username` and `password` properties. The `password` will be in plaintext, so don't cross the streams with it.\n\n```js\n  const clortho = require('clortho');\n\n  clortho({\n    service: 'Gozer',\n    username: 'vinz@clortho.horse',\n    message: 'I am Vinz, Vinz Clortho, Keymaster of Gozer. Volguus Zildrohar, Lord of the Sebouillia. Are you the Gatekeeper?'\n  }).then(credential => {\n    console.log(credential.username);\n    console.log(credential.password);\n  });\n```\n\nThe above is the simplest usage; it should work for most cases, because it does some sane things.\n\n1. First, it checks your operating system's credential store or keychain for a password for the named `service` and `username`, using the `security` utility on OSX, a PowerShell script on Windows, or a simple in-memory storage (that never writes to disk) if neither are available.\n\n2. If it finds a password available in the keychain, it skips prompting the user and resolves the promise with the credential.\n\n3. If it doesn't find a password, it prompts the user with an OS-appropriate authentication prompt. In Windows 7 and above, it looks like this:\n\n  ![Windows PowerShell style](http://i.imgur.com/y79xLc7.png)\n\n  In OSX, it looks like this:\n\n  ![OSX AppleScript style](http://i.imgur.com/YWUxewA.png)\n\n  On other operating systems, or if the username was not supplied on OSX, the prompt occurs in the terminal running the program.\n\n  ![CLI terminal style](http://i.imgur.com/nMnyciR.png)\n\n4. If the user clicks \"Cancel\", the promise rejects. If the user enters a password, however...\n\n5. It stores the username and password in the system keychain.\n\n6. Then, it fulfills the promise with the credential object.\n\nThe available options for the `clortho(opts)` function are:\n - `service`: **Required.** Name of the service for which Clortho is getting a credential. This can be any arbitrary string, like \"zuul\" or \"AWS Sandbox\".\n - `username`: **Optional.** The username for which Clortho is getting a password. If this is not supplied, Clortho will ask for both a username and password.\n - `message`: **Optional.** A custom message to display with the password prompt, instead of the default \"Please enter your username and password\".\n - `cli`: **Optional.** If this is `true`, the prompt step will always use the CLI in-terminal prompt style. If it is `false`, the prompt step will *never* use that style. Default is `undefined`, which will allow Clortho to select an OS-appropriate prompt style.\n - `refresh`: **Optional.** If this is set to `true`, then Clortho will not check the keychain before prompting. This is appropriate to use if the password fails the first time. Default `false`.\n\n### API\n\nThe sensible default above doesn't work in every case. Fortunately, the default `clortho` function is composed of several functions that can be exposed as separate steps. For instance, this example:\n\n```js\n  const clortho = require('clortho');\n\n  clortho({\n    service: 'Gozer',\n    username: 'vinz@clortho.horse',\n    message: 'I am Vinz, Vinz Clortho, Keymaster of Gozer. Volguus Zildrohar, Lord of the Sebouillia. Are you the Gatekeeper?'\n  }).then(credential => {\n    console.log(credential.username);\n    console.log(credential.password);\n  });\n```\n\nis equivalent to:\n\n```js\n  const vinz = require('clortho').forService('Gozer');\n  \n  vinz.getFromKeychain('vinz@clortho.horse')\n  .catch(() =>\n    vinz.prompt(\n      'vinz@clortho.horse'\n      'I am Vinz, Vinz Clortho, Keymaster of Gozer. Volguus Zildrohar, Lord of the Sebouillia. Are you the Gatekeeper?'\n    )\n    .then(vinz.trySaveToKeychain)\n  );\n```\n\nYou can obtain a decomposed object like the above, by running `clortho.forService(serviceName)`. It has the following methods, all of which return promises:\n\n##### `getFromKeychain(username)`\nTakes a string `username`. Queries the system keychain for the username under the service. Resolves with a credential object. Rejects if a credential is not found or the keychain query failed for another reason.\n\n##### `prompt(username, message, cli)`\nPrompts the user with a system-appropriate dialog or prompt. The `username` string is optional (though on OSX, a missing `username` will make the system fall back to CLI style). The `message` string is optional, and works as above in the main `clortho` function. The `cli` boolean is optional. If it is `true`, then the prompt will **always** use the CLI terminal style. If it is `false`, then the prompt will **never** use the CLI terminal style. If it is any other value, or missing, then the prompt will detect the appropriate style to use. Resolves with a credential object. Rejects if the user cancels.\n\n##### `saveToKeychain(username, password)`\nBoth arguments are required. Saves the password securely to the system keychain. Resolves `true` if save was successful. Rejects if save failed for any reason.\n\n##### `trySaveToKeychain(credential)`\nInstead of separate `username` and `password` arguments like `saveToKeychain`, this method takes a credential object with `username` and `password` properties, and attempts to save it to the system keychain. This method **always resolves with the credential again**. It is meant as a pass-through method that should not notify if it fails.\n\n##### `removeFromKeychain(username)`\nRemove the password from the keychain for the service. Resolves `true` if delete was successful.\n\n### Installation\n\nNPM:\n\n    npm install clortho\n\n[1]: https://github.com/atom/node-keytar \"node-keytar\"\n","readmeFilename":"README.md"}