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 {
  enum ExportProgressStatus {
    // No export was started.
    NOT_STARTED,
    // Data is being written to the destination.
    IN_PROGRESS,
    // Data has been written.
    SUCCEEDED,
    // The user rejected the file selection prompts.
    FAILED_CANCELLED,
    // Writing to the destination failed.
    FAILED_WRITE_FAILED
  };

  dictionary UrlCollection {
    // The fully specified URL of the credential's origin.
    DOMString origin;

    // A human readable version of the URL of the credential's origin.
    DOMString shown;

    // The URL that will be linked to when an entry is clicked.
    DOMString link;
  };

  // Pair of a URL collection and a username saved for these URLs.
  dictionary LoginPair {
    UrlCollection urls;

    // 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 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;

    // An index to refer back to a unique password entry record.
    long index;
  };

  // Dictionary passed to listeners for the onPlaintextPasswordRetrieved event.
  dictionary PlaintextPasswordEventParameters {
    // An index to refer back to a unique password entry record.
    long index;

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

  dictionary ExceptionEntry {
    UrlCollection urls;

    // An index to refer back to a unique exception entry record.
    long index;
  };

  dictionary PasswordExportProgress {
    // The current status of the export task.
    ExportProgressStatus status;

    // If |status| is $ref(ExportProgressStatus.FAILED_WRITE_FAILED), this will
    // be the name of the selected folder to export to.
    DOMString? folderName;
  };

  callback PasswordListCallback = void(PasswordUiEntry[] entries);
  callback ExceptionListCallback = void(ExceptionEntry[] exceptions);
  callback ExportProgressStatusCallback = void(ExportProgressStatus status);
  callback EmptyCallback = void();

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

    // Removes the saved password exception corresponding to |exceptionUrl|. If
    // no exception with this URL exists, this function is a no-op.
    //
    // |index|: The index for the exception url entry being removed.
    static void removePasswordException(long index);

    // Undoes the last removal of a saved password or exception.
    static void undoRemoveSavedPasswordOrException();

    // Returns the plaintext password corresponding to |index|. 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.
    //
    // |index|: The index for the password entry being being retrieved.
    static void requestPlaintextPassword(long index);

    // 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);

    // Triggers the Password Manager password import functionality.
    static void importPasswords();

    // Triggers the Password Manager password export functionality. Completion
    // Will be signaled by the onPasswordsFileExportProgress event.
    //
    // |callback| will be called when the request is started or rejected. If
    // rejected <code>chrome.runtime.lastError</code> will be set to
    // 'in-progress' or 'reauth-failed'.
    static void exportPasswords(EmptyCallback callback);

    // Requests the export progress status. This is the same as the last value
    // seen on the onPasswordsFileExportProgress event. This function is useful
    // for checking if an export has already been initiated from an older tab,
    // where we might have missed the original event.
    static void requestExportProgressStatus(ExportProgressStatusCallback callback);

    // Stops exporting passwords and cleans up any passwords, which were already
    // written to the filesystem.
    static void cancelExportPasswords();
  };

  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(ExceptionEntry[] exceptions);

    // Fired when a plaintext password has been fetched in response to a call to
    // chrome.passwordsPrivate.requestPlaintextPassword().
    //
    // |index|: The index for the password entry being being retrieved.
    // |plaintextPassword|: The plaintext password which was retrieved.
    static void onPlaintextPasswordRetrieved(
        PlaintextPasswordEventParameters dict);

    // Fired when the status of the export has changed.
    //
    // |status|: The progress status and an optional UI message.
    static void onPasswordsFileExportProgress(PasswordExportProgress status);
  };
};