DOCSEARCHbyAlgolia
Submit Docs

node-keychain 1.5.0

repository·master·Indexed 40 days ago

https://github.com/drudge/node-keychain

A Node.js module providing basic access to the macOS Keychain by wrapping the system's security command-line tool. It supports storing, retrieving, and deleting generic and internet passwords, as well as managing keychains via createKeychain, deleteKeychain, and setDefaultKeychain.

Tokens
2.2K
Snippets
9
Records
10
Agent score
0%

What's inside node-keychain

  2. Store and retrieve generic passwords

    master

    Use setPassword and getPassword with the default type: 'generic' to manage standard service credentials. Both methods require an account and a service name.

    var keychain = require('keychain');

keychain.setPassword({ account: 'foo', service: 'FooBar', password: 'baz' }, function(err) {
  keychain.getPassword({ account: 'foo', service: 'FooBar' }, function(err, pass) {
    console.log('Password is', pass);
    // Prints: Password is baz
  });
});

  3. Store and retrieve internet passwords

    master

    To manage internet-specific credentials (e.g., for websites), set the type option to 'internet'. This requires an account, service (the domain), and password.

    var keychain = require('keychain');

keychain.setPassword({ account: 'foo', service: 'FooBar.com', type: 'internet', password: 'baz' }, function(err) {
  keychain.getPassword({ account: 'foo', service: 'FooBar.com', type: 'internet' }, function(err, pass) {
    console.log('Password is', pass);
    // Prints: Password is baz
  });
});

  4. Keychain API reference

    master

    The keychain module provides the following asynchronous methods. All methods accept an options object and an optional callback function.

    keychain.setPassword(options[, callback]);
keychain.getPassword(options, callback);
keychain.deletePassword(options[, callback]);
keychain.createKeychain(options[, callback]);
keychain.deleteKeychain(options[, callback]);
keychain.setDefaultKeychain(options[, callback]);

  5. Configure keychain options

    master

    The following parameters can be passed within the options object to the keychain methods:

    | Param | Description |
| ----- | ----------- |
| `account` | Specify account name (required) |
| `service` | Specify service name (required) |
| `password` | Specify password to be added (required for `setPassword`) |
| `type` | The type of password to get or save. Supported values are `generic` and `internet`. See [docs](https://developer.apple.com/legacy/library/documentation/Darwin/Reference/ManPages/man1/security.1.html). Default: `generic` |
| `keychainName` | Specify the name of the keychain (required for 'createKeychain' and 'deleteKeychain') |

  6. Delete a password with deletePassword()

    master

    Use deletePassword() to remove a specific password entry from the macOS keychain.

    Parameters:

    • opts.account (String): The account name.
    • opts.service (String): The service name.
    • opts.type (String, optional): The password type. Defaults to 'generic'.

    Callback Signature: fn(err)

    const keychain = require('./keychain');

keychain.deletePassword({ account: 'myUser', service: 'myService' }, (err) => {
  if (err) {
    console.error('Error deleting password:', err.message);
    return;
  }
  console.log('Password deleted');
});

  7. Manage keychains with createKeychain(), deleteKeychain(), and setDefaultKeychain()

    master

    These methods allow for high-level keychain management on macOS.

    Create a new keychain

    createKeychain(opts, fn)

    • opts.keychainName (String): The name of the new keychain.
    • opts.password (String): The password for the new keychain.
    • Callback: fn(err, keychainName)

    Delete a keychain

    deleteKeychain(opts, fn)

    • opts.keychainName (String): The name of the keychain to delete.
    • Callback: fn(err, keychainName)

    Set the default keychain

    setDefaultKeychain(opts, fn)

    • opts.keychainName (String): The name of the keychain to set as default.
    • Callback: fn(err, keychainName)
    const keychain = require('./keychain');

// Create
keychain.createKeychain({ keychainName: 'MyKey', password: 'keyPassword' }, (err, name) => {
  // ...
});

// Set Default
keychain.setDefaultKeychain({ keychainName: 'MyKey' }, (err, name) => {
  // ...
});

// Delete
keychain.deleteKeychain({ keychainName: 'MyKey' }, (err, name) => {
  // ...
});

  8. Set or update a password with setPassword()

    master

    Use setPassword() to store a new password or update an existing one in the macOS keychain.

    Parameters:

    • opts.account (String): The account name.
    • opts.service (String): The service name.
    • opts.password (String): The password to store.
    • opts.type (String, optional): The password type. Defaults to 'generic'.

    Callback Signature: fn(err, password)

    const keychain = require('./keychain');

keychain.setPassword({ 
  account: 'myUser', 
  service: 'myService', 
  password: 'secretPassword' 
}, (err, password) => {
  if (err) {
    console.error('Error setting password:', err.message);
    return;
  }
  console.log('Password set successfully');
});

  9. Retrieve a password with getPassword()

    master

    Use getPassword() to fetch a stored password from the macOS keychain. You must provide an account and a service. You can optionally specify the type of password (e.g., 'generic' or 'internet').

    Parameters:

    • opts.account (String): The account name.
    • opts.service (String): The service name.
    • opts.type (String, optional): The password type. Defaults to 'generic'.

    Callback Signature: fn(err, password)

    const keychain = require('./keychain');

keychain.getPassword({ account: 'myUser', service: 'myService' }, (err, password) => {
  if (err) {
    console.error('Error retrieving password:', err.message);
    return;
  }
  console.log('Retrieved password:', password);
});

  10. Handle KeychainAccess errors

    master

    The library provides specific error classes to help identify why a keychain operation failed. All errors follow the standard Node.js error pattern (err, result) in callbacks.

    Available Error Types:

    • UnsupportedPlatformError: The current platform is not darwin (macOS).
    • NoAccountProvidedError: The account option was missing.
    • NoServiceProvidedError: The service option was missing.
    • NoPasswordProvidedError: The password option was missing.
    • NoKeychainNameProvidedError: The keychainName option was missing.
    • PasswordNotFoundError: The requested password could not be found.
    • ServiceFailureError: The underlying security command failed to execute or returned a non-zero exit code.