spelling: fix misspellings
[gpgme.git] / lang / js / src / Key.js
index 37ec7f9..a3f5204 100644 (file)
  * Lesser General Public License for more details.
  *
  * You should have received a copy of the GNU Lesser General Public
- * License along with this program; if not, see <http://www.gnu.org/licenses/>.
+ * License along with this program; if not, see <https://www.gnu.org/licenses/>.
  * SPDX-License-Identifier: LGPL-2.1+
  *
  * Author(s):
  *     Maximilian Krambach <mkrambach@intevation.de>
  */
 
+
 import { isFingerprint, isLongId } from './Helpers';
 import { gpgme_error } from './Errors';
 import { createMessage } from './Message';
@@ -33,41 +34,57 @@ import { createMessage } from './Message';
  * answers will be Promises, and the performance will likely suffer
  * @param {Object} data additional initial properties this Key will have. Needs
  * a full object as delivered by gpgme-json
- * @returns {Object|GPGME_Error} The verified and updated data
+ * @returns {Object} The verified and updated data
  */
-export function createKey(fingerprint, async = false, data){
-    if (!isFingerprint(fingerprint) || typeof(async) !== 'boolean'){
-        return gpgme_error('PARAM_WRONG');
+export function createKey (fingerprint, async = false, data){
+    if (!isFingerprint(fingerprint) || typeof (async) !== 'boolean'){
+        throw gpgme_error('PARAM_WRONG');
     }
     if (data !== undefined){
         data = validateKeyData(fingerprint, data);
     }
     if (data instanceof Error){
-        return gpgme_error('KEY_INVALID');
+        throw gpgme_error('KEY_INVALID');
     } else {
         return new GPGME_Key(fingerprint, async, data);
     }
 }
 
 /**
- * Represents the Keys as stored in the gnupg backend
- * It allows to query almost all information defined in gpgme Key Objects
- * Refer to {@link validKeyProperties} for available information, and the gpgme
- * documentation on their meaning
- * (https://www.gnupg.org/documentation/manuals/gpgme/Key-objects.html)
+ * Represents the Keys as stored in the gnupg backend. A key is defined by a
+ * fingerprint.
+ * A key cannot be directly created via the new operator, please use
+ * {@link createKey} instead.
+ * A GPGME_Key object allows to query almost all information defined in gpgme
+ * Keys. It offers two modes, async: true/false. In async mode, Key properties
+ * with the exception of the fingerprint will be queried from gnupg on each
+ * call, making the operation up-to-date, the answers will be Promises, and
+ * the performance will likely suffer. In Sync modes, all information except
+ * for the armored Key export will be cached and can be refreshed by
+ * [refreshKey]{@link GPGME_Key#refreshKey}.
+ *
+ * <pre>
+ * see also:
+ *      {@link GPGME_UserId} user Id objects
+ *      {@link GPGME_Subkey} subKey objects
+ * </pre>
+ * For other Key properteis, refer to {@link validKeyProperties},
+ * and to the [gpgme documentation]{@link https://www.gnupg.org/documentation/manuals/gpgme/Key-objects.html}
+ * for meanings and further details.
  *
  * @class
  */
 class GPGME_Key {
 
-    constructor(fingerprint, async, data){
+    constructor (fingerprint, async, data){
 
         /**
-         * @property {Boolean} If true, most answers will be asynchronous
+         * @property {Boolean} _async If true, the Key was initialized without
+         * cached data
          */
         this._async = async;
 
-        this._data = {fingerprint: fingerprint.toUpperCase()};
+        this._data = { fingerprint: fingerprint.toUpperCase() };
         if (data !== undefined
             && data.fingerprint.toUpperCase() === this._data.fingerprint
         ) {
@@ -77,14 +94,17 @@ class GPGME_Key {
 
     /**
      * Query any property of the Key listed in {@link validKeyProperties}
-     * @param {String} property property to be retreived
-     * @returns {Boolean| String | Date | Array | Object |GPGME_Error}
-     * the value of the property. If the Key is set to Async, the value
-     * will be fetched from gnupg and resolved as a Promise. If Key is not
-     * async, the armored property is not available (it can still be
-     * retrieved asynchronously by {@link Key.getArmor})
+     * @param {String} property property to be retrieved
+     * @returns {Boolean| String | Date | Array | Object}
+     * @returns {Promise<Boolean| String | Date | Array | Object>} (if in async
+     * mode)
+     * <pre>
+     * Returns the value of the property requested. If the Key is set to async,
+     * the value will be fetched from gnupg and resolved as a Promise. If Key
+     * is not  async, the armored property is not available (it can still be
+     * retrieved asynchronously by [getArmor]{@link GPGME_Key#getArmor})
      */
-    get(property) {
+    get (property) {
         if (this._async === true) {
             switch (property){
             case 'armored':
@@ -96,10 +116,11 @@ class GPGME_Key {
             }
         } else {
             if (property === 'armored') {
-                return gpgme_error('KEY_ASYNC_ONLY');
+                throw gpgme_error('KEY_ASYNC_ONLY');
             }
+            // eslint-disable-next-line no-use-before-define
             if (!validKeyProperties.hasOwnProperty(property)){
-                return gpgme_error('PARAM_WRONG');
+                throw gpgme_error('PARAM_WRONG');
             } else {
                 return (this._data[property]);
             }
@@ -107,23 +128,23 @@ class GPGME_Key {
     }
 
     /**
-     * Reloads the Key information from gnupg. This is only useful if you
+     * Reloads the Key information from gnupg. This is only useful if the Key
      * use the GPGME_Keys cached. Note that this is a performance hungry
      * operation. If you desire more than a few refreshs, it may be
-     * advisable to run {@link Keyring.getKeys} instead.
-     * @returns {Promise<GPGME_Key|GPGME_Error>}
+     * advisable to run [Keyring.getKeys]{@link Keyring#getKeys} instead.
+     * @returns {Promise<GPGME_Key>}
      * @async
      */
-    refreshKey() {
+    refreshKey () {
         let me = this;
-        return new Promise(function(resolve, reject) {
+        return new Promise(function (resolve, reject) {
             if (!me._data.fingerprint){
                 reject(gpgme_error('KEY_INVALID'));
             }
             let msg = createMessage('keylist');
             msg.setParameter('sigs', true);
             msg.setParameter('keys', me._data.fingerprint);
-            msg.post().then(function(result){
+            msg.post().then(function (result){
                 if (result.keys.length === 1){
                     const newdata = validateKeyData(
                         me._data.fingerprint, result.keys[0]);
@@ -131,13 +152,13 @@ class GPGME_Key {
                         reject(gpgme_error('KEY_INVALID'));
                     } else {
                         me._data = newdata;
-                        me.getGnupgSecretState().then(function(){
-                            me.getArmor().then(function(){
+                        me.getGnupgSecretState().then(function (){
+                            me.getArmor().then(function (){
                                 resolve(me);
-                            }, function(error){
+                            }, function (error){
                                 reject(error);
                             });
-                        }, function(error){
+                        }, function (error){
                             reject(error);
                         });
                     }
@@ -154,21 +175,21 @@ class GPGME_Key {
      * Query the armored block of the Key directly from gnupg. Please note
      * that this will not get you any export of the secret/private parts of
      * a Key
-     * @returns {Promise<String|GPGME_Error>}
+     * @returns {Promise<String>}
      * @async
      */
-    getArmor() {
+    getArmor () {
         const me = this;
-        return new Promise(function(resolve, reject) {
+        return new Promise(function (resolve, reject) {
             if (!me._data.fingerprint){
                 reject(gpgme_error('KEY_INVALID'));
             }
             let msg = createMessage('export');
             msg.setParameter('armor', true);
             msg.setParameter('keys', me._data.fingerprint);
-            msg.post().then(function(result){
+            msg.post().then(function (result){
                 resolve(result.data);
-            }, function(error){
+            }, function (error){
                 reject(error);
             });
         });
@@ -178,22 +199,22 @@ class GPGME_Key {
      * Find out if the Key is part of a Key pair including public and
      * private key(s). If you want this information about more than a few
      * Keys in synchronous mode, it may be advisable to run
-     * {@link Keyring.getKeys} instead, as it performs faster in bulk
-     * querying this state.
-     * @returns {Promise<Boolean|GPGME_Error>} True if a private Key is
-     * available in the gnupg Keyring.
+     * [Keyring.getKeys]{@link Keyring#getKeys} instead, as it performs faster
+     * in bulk querying.
+     * @returns {Promise<Boolean>} True if a private Key is available in the
+     * gnupg Keyring.
      * @async
      */
     getGnupgSecretState (){
         const me = this;
-        return new Promise(function(resolve, reject) {
+        return new Promise(function (resolve, reject) {
             if (!me._data.fingerprint){
                 reject(gpgme_error('KEY_INVALID'));
             } else {
                 let msg = createMessage('keylist');
                 msg.setParameter('keys', me._data.fingerprint);
                 msg.setParameter('secret', true);
-                msg.post().then(function(result){
+                msg.post().then(function (result){
                     me._data.hasSecret = null;
                     if (
                         result.keys &&
@@ -206,7 +227,7 @@ class GPGME_Key {
                         me._data.hasSecret = false;
                         resolve(false);
                     }
-                }, function(error){
+                }, function (error){
                     reject(error);
                 });
             }
@@ -215,21 +236,22 @@ class GPGME_Key {
 
     /**
      * Deletes the (public) Key from the GPG Keyring. Note that a deletion
-     * of a secret key is not supported by the native backend.
-     * @returns {Promise<Boolean|GPGME_Error>} Success if key was deleted,
-     * rejects with a GPG error otherwise.
+     * of a secret key is not supported by the native backend, and gnupg will
+     * refuse to delete a Key if there is still a secret/private Key present
+     * to that public Key
+     * @returns {Promise<Boolean>} Success if key was deleted.
      */
-    delete(){
+    delete (){
         const me = this;
-        return new Promise(function(resolve, reject){
+        return new Promise(function (resolve, reject){
             if (!me._data.fingerprint){
                 reject(gpgme_error('KEY_INVALID'));
             }
             let msg = createMessage('delete');
             msg.setParameter('key', me._data.fingerprint);
-            msg.post().then(function(result){
+            msg.post().then(function (result){
                 resolve(result.success);
-            }, function(error){
+            }, function (error){
                 reject(error);
             });
         });
@@ -238,13 +260,14 @@ class GPGME_Key {
     /**
      * @returns {String} The fingerprint defining this Key. Convenience getter
      */
-    get fingerprint(){
+    get fingerprint (){
         return this._data.fingerprint;
     }
 }
 
 /**
- * Representing a subkey of a Key.
+ * Representing a subkey of a Key. See {@link validSubKeyProperties} for
+ * possible properties.
  * @class
  * @protected
  */
@@ -255,7 +278,7 @@ class GPGME_Subkey {
      * @param {Object} data
      * @private
      */
-    constructor(data){
+    constructor (data){
         this._data = {};
         let keys = Object.keys(data);
         const me = this;
@@ -268,7 +291,9 @@ class GPGME_Subkey {
          * @param private
          */
         const setProperty = function (property, value){
+            // eslint-disable-next-line no-use-before-define
             if (validSubKeyProperties.hasOwnProperty(property)){
+                // eslint-disable-next-line no-use-before-define
                 if (validSubKeyProperties[property](value) === true) {
                     if (property === 'timestamp' || property === 'expires'){
                         me._data[property] = new Date(value * 1000);
@@ -288,7 +313,7 @@ class GPGME_Subkey {
      * @param {String} property Information to request
      * @returns {String | Number | Date}
      */
-    get(property) {
+    get (property) {
         if (this._data.hasOwnProperty(property)){
             return (this._data[property]);
         }
@@ -297,7 +322,8 @@ class GPGME_Subkey {
 }
 
 /**
- * Representing user attributes associated with a Key or subkey
+ * Representing user attributes associated with a Key or subkey. See
+ * {@link validUserIdProperties} for possible properties.
  * @class
  * @protected
  */
@@ -308,12 +334,14 @@ class GPGME_UserId {
      * @param {Object} data
      * @private
      */
-    constructor(data){
+    constructor (data){
         this._data = {};
         const me = this;
         let keys = Object.keys(data);
-        const setProperty = function(property, value){
+        const setProperty = function (property, value){
+            // eslint-disable-next-line no-use-before-define
             if (validUserIdProperties.hasOwnProperty(property)){
+                // eslint-disable-next-line no-use-before-define
                 if (validUserIdProperties[property](value) === true) {
                     if (property === 'last_update'){
                         me._data[property] = new Date(value*1000);
@@ -333,7 +361,7 @@ class GPGME_UserId {
      * @param {String} property Information to request
      * @returns {String | Number}
      */
-    get(property) {
+    get (property) {
         if (this._data.hasOwnProperty(property)){
             return (this._data[property]);
         }
@@ -349,52 +377,52 @@ class GPGME_UserId {
  * @const
  */
 const validUserIdProperties = {
-    'revoked': function(value){
-        return typeof(value) === 'boolean';
+    'revoked': function (value){
+        return typeof (value) === 'boolean';
     },
-    'invalid':  function(value){
-        return typeof(value) === 'boolean';
+    'invalid':  function (value){
+        return typeof (value) === 'boolean';
     },
-    'uid': function(value){
-        if (typeof(value) === 'string' || value === ''){
+    'uid': function (value){
+        if (typeof (value) === 'string' || value === ''){
             return true;
         }
         return false;
     },
-    'validity': function(value){
-        if (typeof(value) === 'string'){
+    'validity': function (value){
+        if (typeof (value) === 'string'){
             return true;
         }
         return false;
     },
-    'name': function(value){
-        if (typeof(value) === 'string' || value === ''){
+    'name': function (value){
+        if (typeof (value) === 'string' || value === ''){
             return true;
         }
         return false;
     },
-    'email': function(value){
-        if (typeof(value) === 'string' || value === ''){
+    'email': function (value){
+        if (typeof (value) === 'string' || value === ''){
             return true;
         }
         return false;
     },
-    'address': function(value){
-        if (typeof(value) === 'string' || value === ''){
+    'address': function (value){
+        if (typeof (value) === 'string' || value === ''){
             return true;
         }
         return false;
     },
-    'comment': function(value){
-        if (typeof(value) === 'string' || value === ''){
+    'comment': function (value){
+        if (typeof (value) === 'string' || value === ''){
             return true;
         }
         return false;
     },
-    'origin':  function(value){
+    'origin':  function (value){
         return Number.isInteger(value);
     },
-    'last_update':  function(value){
+    'last_update':  function (value){
         return Number.isInteger(value);
     }
 };
@@ -406,54 +434,54 @@ const validUserIdProperties = {
  * @const
  */
 const validSubKeyProperties = {
-    'invalid': function(value){
-        return typeof(value) === 'boolean';
+    'invalid': function (value){
+        return typeof (value) === 'boolean';
     },
-    'can_encrypt': function(value){
-        return typeof(value) === 'boolean';
+    'can_encrypt': function (value){
+        return typeof (value) === 'boolean';
     },
-    'can_sign': function(value){
-        return typeof(value) === 'boolean';
+    'can_sign': function (value){
+        return typeof (value) === 'boolean';
     },
-    'can_certify':  function(value){
-        return typeof(value) === 'boolean';
+    'can_certify':  function (value){
+        return typeof (value) === 'boolean';
     },
-    'can_authenticate':  function(value){
-        return typeof(value) === 'boolean';
+    'can_authenticate':  function (value){
+        return typeof (value) === 'boolean';
     },
-    'secret': function(value){
-        return typeof(value) === 'boolean';
+    'secret': function (value){
+        return typeof (value) === 'boolean';
     },
-    'is_qualified': function(value){
-        return typeof(value) === 'boolean';
+    'is_qualified': function (value){
+        return typeof (value) === 'boolean';
     },
-    'is_cardkey':  function(value){
-        return typeof(value) === 'boolean';
+    'is_cardkey':  function (value){
+        return typeof (value) === 'boolean';
     },
-    'is_de_vs':  function(value){
-        return typeof(value) === 'boolean';
+    'is_de_vs':  function (value){
+        return typeof (value) === 'boolean';
     },
-    'pubkey_algo_name': function(value){
-        return typeof(value) === 'string';
+    'pubkey_algo_name': function (value){
+        return typeof (value) === 'string';
         // TODO: check against list of known?['']
     },
-    'pubkey_algo_string': function(value){
-        return typeof(value) === 'string';
+    'pubkey_algo_string': function (value){
+        return typeof (value) === 'string';
         // TODO: check against list of known?['']
     },
-    'keyid': function(value){
+    'keyid': function (value){
         return isLongId(value);
     },
-    'pubkey_algo': function(value) {
+    'pubkey_algo': function (value) {
         return (Number.isInteger(value) && value >= 0);
     },
-    'length': function(value){
+    'length': function (value){
         return (Number.isInteger(value) && value > 0);
     },
-    'timestamp': function(value){
+    'timestamp': function (value){
         return (Number.isInteger(value) && value > 0);
     },
-    'expires': function(value){
+    'expires': function (value){
         return (Number.isInteger(value) && value > 0);
     }
 };
@@ -489,73 +517,73 @@ const validSubKeyProperties = {
  * @const
  */
 const validKeyProperties = {
-    'fingerprint': function(value){
+    'fingerprint': function (value){
         return isFingerprint(value);
     },
-    'revoked': function(value){
-        return typeof(value) === 'boolean';
+    'revoked': function (value){
+        return typeof (value) === 'boolean';
     },
-    'expired': function(value){
-        return typeof(value) === 'boolean';
+    'expired': function (value){
+        return typeof (value) === 'boolean';
     },
-    'disabled': function(value){
-        return typeof(value) === 'boolean';
+    'disabled': function (value){
+        return typeof (value) === 'boolean';
     },
-    'invalid': function(value){
-        return typeof(value) === 'boolean';
+    'invalid': function (value){
+        return typeof (value) === 'boolean';
     },
-    'can_encrypt': function(value){
-        return typeof(value) === 'boolean';
+    'can_encrypt': function (value){
+        return typeof (value) === 'boolean';
     },
-    'can_sign': function(value){
-        return typeof(value) === 'boolean';
+    'can_sign': function (value){
+        return typeof (value) === 'boolean';
     },
-    'can_certify': function(value){
-        return typeof(value) === 'boolean';
+    'can_certify': function (value){
+        return typeof (value) === 'boolean';
     },
-    'can_authenticate': function(value){
-        return typeof(value) === 'boolean';
+    'can_authenticate': function (value){
+        return typeof (value) === 'boolean';
     },
-    'secret': function(value){
-        return typeof(value) === 'boolean';
+    'secret': function (value){
+        return typeof (value) === 'boolean';
     },
-    'is_qualified': function(value){
-        return typeof(value) === 'boolean';
+    'is_qualified': function (value){
+        return typeof (value) === 'boolean';
     },
-    'protocol': function(value){
-        return typeof(value) === 'string';
-        //TODO check for implemented ones
+    'protocol': function (value){
+        return typeof (value) === 'string';
+        // TODO check for implemented ones
     },
-    'issuer_serial': function(value){
-        return typeof(value) === 'string';
+    'issuer_serial': function (value){
+        return typeof (value) === 'string';
     },
-    'issuer_name': function(value){
-        return typeof(value) === 'string';
+    'issuer_name': function (value){
+        return typeof (value) === 'string';
     },
-    'chain_id': function(value){
-        return typeof(value) === 'string';
+    'chain_id': function (value){
+        return typeof (value) === 'string';
     },
-    'owner_trust': function(value){
-        return typeof(value) === 'string';
+    'owner_trust': function (value){
+        return typeof (value) === 'string';
     },
-    'last_update': function(value){
+    'last_update': function (value){
         return (Number.isInteger(value));
-        //TODO undefined/null possible?
+        // TODO undefined/null possible?
     },
-    'origin': function(value){
+    'origin': function (value){
         return (Number.isInteger(value));
     },
-    'subkeys': function(value){
+    'subkeys': function (value){
         return (Array.isArray(value));
     },
-    'userids': function(value){
+    'userids': function (value){
         return (Array.isArray(value));
     },
-    'tofu': function(value){
+    'tofu': function (value){
         return (Array.isArray(value));
     },
-    'hasSecret': function(value){
-        return typeof(value) === 'boolean';
+    'hasSecret': function (value){
+        return typeof (value) === 'boolean';
     }
 
 };
@@ -570,9 +598,9 @@ const validKeyProperties = {
 * an error if something went wrong.
 * @private
 */
-function validateKeyData(fingerprint, data){
+function validateKeyData (fingerprint, data){
     const key = {};
-    if (!fingerprint || typeof(data) !== 'object' || !data.fingerprint
+    if (!fingerprint || typeof (data) !== 'object' || !data.fingerprint
      || fingerprint !== data.fingerprint.toUpperCase()
     ){
         return gpgme_error('KEY_INVALID');
@@ -619,13 +647,13 @@ function validateKeyData(fingerprint, data){
  * @async
  */
 function getGnupgState (fingerprint, property){
-    return new Promise(function(resolve, reject) {
+    return new Promise(function (resolve, reject) {
         if (!isFingerprint(fingerprint)) {
             reject(gpgme_error('KEY_INVALID'));
         } else {
             let msg = createMessage('keylist');
             msg.setParameter('keys', fingerprint);
-            msg.post().then(function(res){
+            msg.post().then(function (res){
                 if (!res.keys || res.keys.length !== 1){
                     reject(gpgme_error('KEY_INVALID'));
                 } else {
@@ -675,9 +703,9 @@ function getGnupgState (fingerprint, property){
                         break;
                     }
                 }
-            }, function(error){
+            }, function (error){
                 reject(gpgme_error(error));
             });
         }
     });
-}
\ No newline at end of file
+}