search(options)

This function is used to retrieve a credential, or a list of credentials, stored in the Password Manager.

You pass it any subset of the possible properties a credential can contain. Credentials which match all the properties you supplied are returned as an argument to the onComplete callback.

So if you pass in an empty set of properties, all stored credentials are returned:

function show_all_passwords() {
  require("passwords").search({
    onComplete: function onComplete(credentials) {
      credentials.forEach(function(credential) {
        console.log(credential.username);
        console.log(credential.password);
        });
      }
    });
  }

If you pass it a single property, only credentials matching that property are returned:

function show_passwords_for_joe() {
  require("passwords").search({
    username: "joe",
    onComplete: function onComplete(credentials) {
      credentials.forEach(function(credential) {
        console.log(credential.username);
        console.log(credential.password);
        });
      }
    });
  }

If you pass more than one property, returned credentials must match all of them:

function show_google_password_for_joe() {
  require("passwords").search({
    username: "joe",
    url: "https://www.google.com",
    onComplete: function onComplete(credentials) {
      credentials.forEach(function(credential) {
        console.log(credential.username);
        console.log(credential.password);
        });
      }
    });
  }

To retrieve only credentials associated with your add-on, use the url property, initialized from self.uri:

function show_my_addon_passwords() {
  require("passwords").search({
    url: require("self").uri,
    onComplete: function onComplete(credentials) {
      credentials.forEach(function(credential) {
        console.log(credential.username);
        console.log(credential.password);
        });
      }
    });
  }

store(options)

This function is used to store a credential in the Password Manager.

It takes an options object as an argument: this contains all the properties for the new credential.

As different sorts of credentials contain different properties, the appropriate options differ depending on the sort of credential being stored.

To store an add-on credential:

require("passwords").store({
  realm: "User Registration",
  username: "joe",
  password: "SeCrEt123",
});

To store an HTML form credential:

require("passwords").store({
  url: "http://www.example.com",
  formSubmitURL: "http://login.example.com",
  username: "joe",
  usernameField: "uname",
  password: "SeCrEt123",
  passwordField: "pword"
});

To store an HTTP Authentication credential:

require("passwords").store({
  url: "http://www.example.com",
  realm: "ExampleCo Login",
  username: "joe",
  password: "SeCrEt123",
});

See "Credentials" above for more details on how to set these properties.

The options parameter may also include onComplete and onError callback functions, which are called when the function has completed successfully and when it encounters an error, respectively. These options are both optional.

remove(options)

Removes a stored credential. You supply it all the properties of the credential to remove, along with optional onComplete and onError callbacks.

Because you must supply all the credential's properties, it may be convenient to call search first, and use its output as the input to remove. For example, to remove all of joe's stored credentials:

require("passwords").search({
  username: "joe",
  onComplete: function onComplete(credentials) {
    credentials.forEach(require("passwords").remove);
  })
});

To change an existing credential just call store after remove succeeds:

require("passwords").remove({
  realm: "User Registration",
  username: "joe",
  password: "SeCrEt123"
  onComplete: function onComplete() {
    require("passwords").store({
      realm: "User Registration",
      username: "joe",
      password: "{{new password}}"
    })
  }
});