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 id;
  };

  dictionary ExceptionEntry {
    UrlCollection urls;

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

  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 PlaintextPasswordCallback = void(optional DOMString password);
  callback PasswordListCallback = void(PasswordUiEntry[] entries);
  callback ExceptionListCallback = void(ExceptionEntry[] exceptions);
  callback ExportProgressStatusCallback = void(ExportProgressStatus status);
  callback EmptyCallback = void();

  interface Functions {
    // Function that logs that the Passwords page was accessed from the Chrome
    // Settings WebUI.
    static void recordPasswordsPageAccessInSettings();

    // Changes the username and password corresponding to |id|.
    // |id|: The id for the password entry being updated.
    // |new_username|: The new username.
    // |new_password|: The new password.
    static void changeSavedPassword(long id,
                                    DOMString new_username,
                                    optional DOMString new_password);

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

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

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

    // Returns the plaintext password corresponding to |id|. 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 |callback|.
    // |id|: The id for the password entry being being retrieved.
    // |callback|: The callback that gets invoked with the retrieved password.
    static void requestPlaintextPassword(long id,
                                         PlaintextPasswordCallback callback);

    // 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 the status of the export has changed.
    // |status|: The progress status and an optional UI message.
    static void onPasswordsFileExportProgress(PasswordExportProgress status);
  };
};