chrome/common/extensions/api/passwords_private.idl

// Copyright 2015 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Use the <code>chrome.passwordsPrivate</code> API to add or remove password
// data from the settings UI.
namespace passwordsPrivate {
  // Pair of origin URL and login saved for that URL.
  dictionary LoginPair {
    // The human-readable origin for the URL where the password is used.
    DOMString originUrl;

    // The username used in conjunction with the saved password.
    DOMString username;
  };

  // Entry used to display a password in the settings UI.
  dictionary PasswordUiEntry {
    // The login information for this entry.
    LoginPair loginPair;

    // The complete URL of the page that the password is saved for.
    DOMString linkUrl;

    // The number of characters in the password; used to display placeholder
    // dots in the UI.
    long numCharactersInPassword;

    // Text shown if the password was obtained via a federated identity.
    DOMString? federationText;
  };

  dictionary ExceptionPair {
    // The human-readable URL where passwords will not be saved.
    DOMString exceptionUrl;

    // The complete URL of the page that the exception was created for.
    DOMString linkUrl;
  };

  // Dictionary passed to listeners for the onPlaintextPasswordRetrieved event.
  dictionary PlaintextPasswordEventParameters {
    // The LoginPair associated with the retrieved password.
    LoginPair loginPair;

    // The password in plaintext.
    DOMString plaintextPassword;
  };

  callback PasswordListCallback = void(PasswordUiEntry[] entries);
  callback ExceptionListCallback = void(ExceptionPair[] exceptions);

  interface Functions {
    // Removes the saved password corresponding to |loginPair|. If no saved
    // password for this pair exists, this function is a no-op.
    //
    // |loginPair|: The LoginPair corresponding to the entry to remove.
    static void removeSavedPassword(LoginPair loginPair);

    // Removes the saved password exception corresponding to |exceptionUrl|. If
    // no exception with this URL exists, this function is a no-op.
    //
    // |exceptionUrl|: The URL corresponding to the exception to remove.
    static void removePasswordException(DOMString exceptionUrl);

    // Returns the plaintext password corresponding to |loginPair|. Note that on
    // some operating systems, this call may result in an OS-level
    // reauthentication. Once the password has been fetched, it will be returned
    // via the onPlaintextPasswordRetrieved event.
    // TODO(hcarmona): Investigate using a callback for consistency.
    //
    // |loginPair|: The LoginPair corresponding to the entry whose password
    //     is to be returned.
    static void requestPlaintextPassword(LoginPair loginPair);

    // Returns the list of saved passwords.
    // |callback|: Called with the list of saved passwords.
    static void getSavedPasswordList(PasswordListCallback callback);

    // Returns the list of password exceptions.
    // |callback|: Called with the list of password exceptions.
    static void getPasswordExceptionList(ExceptionListCallback callback);
  };

  interface Events {
    // Fired when the saved passwords list has changed, meaning that an entry
    // has been added or removed.
    //
    // |entries|: The updated list of password entries.
    static void onSavedPasswordsListChanged(PasswordUiEntry[] entries);

    // Fired when the password exceptions list has changed, meaning that an
    // entry has been added or removed.
    //
    // |exceptions|: The updated list of password exceptions.
    static void onPasswordExceptionsListChanged(ExceptionPair[] exceptions);

    // Fired when a plaintext password has been fetched in response to a call to
    // chrome.passwordsPrivate.requestPlaintextPassword().
    //
    // |loginPair|: The LoginPair whose password was found.
    // |plaintextPassword|: The plaintext password which was retrieved.
    static void onPlaintextPasswordRetrieved(
        PlaintextPasswordEventParameters dict);
  };
};