IdCard API changes (#1415) (#1663)

packages/composer-common/api.txt

@@ -45,11 +45,10 @@ class FileWallet extends Wallet {
 class IdCard {
    + String getName() 
    + String getDescription() 
-   + String getBusinessNetwork() 
-   + Object getImage() 
-   + Object getConnection() 
-   + Map getCredentials() 
-   + Map getTlsCertificates() 
+   + String getBusinessNetworkName() 
+   + Object getConnectionProfile() 
+   + Object getCredentials() 
+   + Object getEnrollmentCredentials() 
    + Promise fromArchive(Buffer) 
 }
 class BaseModelException extends BaseException {

packages/composer-common/changelog.txt

@@ -11,7 +11,7 @@
 #
 # Note that the latest public API is documented using JSDocs and is available in api.txt.
 #
-Version 0.10.1 {ac4a5b035d77bfa46eeadf4b312eab8f} 2017-07-21
+Version 0.10.1 {7df1a4380321ba2c424afe27257d07a6} 2017-07-24
 - Added IdCard to composer-common package
 
 Version 0.9.2 {60327250ee4f059647020f8aee5ed67b} 2017-07-06

packages/composer-common/index.js

@@ -72,6 +72,7 @@ module.exports.FileWallet = require('./lib/filewallet');
 module.exports.FileWriter = require('./lib/codegen/filewriter');
 module.exports.FSConnectionProfileStore = require('./lib/fsconnectionprofilestore');
 module.exports.Globalize = require('./lib/globalize');
+module.exports.IdCard = require('./lib/idcard');
 module.exports.Introspector = require('./lib/introspect/introspector');
 module.exports.Limit = require('./lib/query/limit');
 module.exports.Logger = require('./lib/log/logger');

packages/composer-common/lib/idcard.js

@@ -15,37 +15,44 @@
 'use strict';
 
 const JSZip = require('jszip');
-const path = require('path');
 
 const Logger = require('./log/logger');
 const LOG = Logger.getLog('IdCard');
 
 /**
- * An ID card.
+ * An ID card. Encapsulates credentials and other information required to connect to a specific business network
+ * as a specific user.
+ * <p>
+ * Instances of this class should be created using {@link IdCard.fromArchive}.
  * @class
  * @memberof module:composer-common
  */
 class IdCard {
 
     /**
-     * Create the BusinessNetworkDefinition.
+     * Create the IdCard.
      * <p>
      * <strong>Note: Only to be called by framework code. Applications should
      * retrieve instances from {@link IdCard.fromArchive}</strong>
      * @param {Object} metadata - metadata associated with the card.
-     * @param {Object} connection - connection properties associated with the card.
-     * @param {Map} credentials - map of credential filename String keys to credential data Buffer objects.
-     * @param {Map} tlscerts - map of TLS certificate filename String keys to TLS certificate data Buffer objects.
+     * @param {Object} connectionProfile - connection profile associated with the card.
+     * @param {Object} credentials - credentials used to connect to business network.
      * @private
      */
-    constructor(metadata, connection, credentials, tlscerts) {
+    constructor(metadata, connectionProfile, credentials) {
         const method = 'constructor';
         LOG.entry(method);
 
+        if (!(metadata && metadata.name)) {
+            throw Error('Required metadata field not found: name');
+        }
+        if (!(connectionProfile && connectionProfile.name)) {
+            throw Error('Required connection field not found: name');
+        }
+
         this.metadata = metadata;
-        this.connection = connection;
+        this.connectionProfile = connectionProfile;
         this.credentials = credentials;
-        this.tlscerts = tlscerts;
 
         LOG.exit(method);
     }
@@ -62,52 +69,55 @@ class IdCard {
 
     /**
      * Free text description of the card.
-     * @return {String} description, or {@link undefined} if none exists.
+     * @return {String} card description.
      */
     getDescription() {
-        return this.metadata.description;
-    }
-
-    /**
-     * Business network to which the ID card applies. Generally this will be present but may be omitted for system
-     * cards.
-     * @return {String} description, or {@link undefined} if none exists.
-     */
-    getBusinessNetwork() {
-        return this.metadata.businessNetwork;
+        return this.metadata.description || '';
     }
 
     /**
-     * Image associated with the card.
-     * @return {Object} an object of the form <i>{ name: imageFileName, data: bufferOfImageData }</i>,
-     * or {@link undefined} if none exists.
+     * Name of the business network to which the ID card applies. Generally this will be present but may be
+     * omitted for system cards.
+     * @return {String} business network name.
      */
-    getImage() {
-        return this.image;
+    getBusinessNetworkName() {
+        return this.metadata.businessNetwork || '';
     }
 
     /**
      * Connection profile for this card.
+     * <p>
+     * This is a mandatory field.
      * @return {Object} connection profile.
      */
-    getConnection() {
-        return this.connection;
+    getConnectionProfile() {
+        return this.connectionProfile;
     }
 
     /**
-     * Credentials associated with this card.
-     * @return {Map} Map of filename {@link String} keys to {@link Buffer} data.
+     * Credentials associated with this card, and which are used to connect to the associated business network.
+     * @return {Object} credentials in the form <em>{ public: publicKey, private: privateKey }</em>, if they exist.
      */
     getCredentials() {
         return this.credentials;
     }
 
     /**
-     * TLS certificates used to connect to the business networks.
-     * @return {Map} Map of filename {@link String} keys to {@link Buffer} data.
+     * Enrollment credentials. If there are no credentials associated with this card, these credentials  are used to
+     * enroll with a business network and obtain certificates.
+     * @return {Object} enrollment credentials in the form <em>{ id: enrollmentId, secret: enrollmentSecret }</em>, if
+     * they exist.
      */
-    getTlsCertificates() {
-        return this.tlscerts;
+    getEnrollmentCredentials() {
+        let result = null;
+        const id = this.metadata.enrollmentId;
+        const secret = this.metadata.enrollmentSecret;
+        if (id || secret) {
+            result = Object.create(null);
+            result.id = id;
+            result.secret = secret;
+        }
+        return result;
     }
 
     /**
@@ -123,10 +133,8 @@ class IdCard {
             let promise = Promise.resolve();
 
             let metadata;
-            let image;
             let connection;
-            const credentials = new Map();
-            const tlscerts = new Map();
+            let credentials = Object.create(null);
 
             LOG.debug(method, 'Loading connection.json');
             const connectionFile = zip.file('connection.json');
@@ -150,52 +158,28 @@ class IdCard {
                 return metadataFile.async('string');
             }).then((metadataContent) => {
                 metadata = JSON.parse(metadataContent);
-                if (!metadata.name) {
-                    throw Error('Required meta-data field not found: name');
-                }
-
-                if (metadata.image) {
-                    LOG.debug(method, 'Loading image ' + metadata.image);
-
-                    const imagePromise = zip.file(metadata.image);
-                    if (!imagePromise) {
-                        throw Error('Image file not found: ' + metadata.image);
-                    }
-
-                    return imagePromise.async('nodebuffer').then((imageContent) => {
-                        const shortFilename = path.basename(metadata.image);
-                        image = {
-                            name: shortFilename,
-                            data: imageContent
-                        };
-                    });
-                }
             });
 
-            const loadDirectoryToMap = function(directoryName, map) {
+            const loadDirectoryToObject = function(directoryName, obj) {
                 // Incude '/' following directory name
                 const fileIndex = directoryName.length + 1;
                 // Find all files that are direct children of specified directory
                 const files = zip.file(new RegExp(`^${directoryName}/[^/]+$`));
                 files && files.forEach((file) => {
                     promise = promise.then(() => {
-                        return file.async('nodebuffer');
+                        return file.async('string');
                     }).then((content) => {
                         const filename = file.name.slice(fileIndex);
-                        map.set(filename, content);
+                        obj[filename] = content;
                     });
                 });
             };
 
             LOG.debug(method, 'Loading credentials');
-            loadDirectoryToMap('credentials', credentials);
-
-            LOG.debug(method, 'Loading tlscerts');
-            loadDirectoryToMap('tlscerts', tlscerts);
+            loadDirectoryToObject('credentials', credentials);
 
             return promise.then(() => {
-                const idCard = new IdCard(metadata, connection, credentials, tlscerts);
-                idCard.image = image;
+                const idCard = new IdCard(metadata, connection, credentials);
                 LOG.exit(method, idCard.toString());
                 return idCard;
             });

packages/composer-common/test/data/id-cards/minimal/connection.json

@@ -1,4 +1,5 @@
 {
+    "name": "hlfv1",
     "type": "hlfv1",
     "orderers": [
         {

packages/composer-common/test/data/id-cards/minimal/metadata.json

@@ -1,3 +1,3 @@
 {
-    "name" : "com.example.cards.Minimal"
+    "name": "Minimal"
 }

packages/composer-common/test/data/id-cards/missing-connection-name/metadata.json

@@ -0,0 +1,3 @@
+{
+    "name": "Minimal"
+}

packages/composer-common/test/data/id-cards/missing-connection/metadata.json

@@ -1,3 +1,3 @@
 {
-    "name" : "com.example.cards.Minimal"
+    "name": "Minimal"
 }

packages/composer-common/test/data/id-cards/missing-metadata-name/connection.json

@@ -1,4 +1,5 @@
 {
+    "name": "hlfv1",
     "type": "hlfv1",
     "orderers": [
         {

packages/composer-common/test/data/id-cards/missing-metadata/connection.json

@@ -1,4 +1,5 @@
 {
+    "name": "hlfv1",
     "type": "hlfv1",
     "orderers": [
         {

packages/composer-common/test/data/id-cards/valid-with-enrollment/connection.json

@@ -0,0 +1,39 @@
+{
+    "name": "hlfv1",
+    "type": "hlfv1",
+    "orderers": [
+        {
+            "url": "grpcs://",
+            "cert": "orderer1.crt"
+        },
+        {
+            "url": "grpcs://",
+            "cert": "orderer2.crt"
+        }
+    ],
+    "ca": {
+            "url": "https://",
+            "name": "",
+            "trustedRoots": "",
+            "verify": true
+    },
+    "peers": [
+        {
+            "requestURL": "grpcs://",
+            "eventURL": "grpcs://",
+            "cert": "peer1.crt"
+        },
+        {
+            "requestURL": "grpcs://",
+            "eventURL": "grpcs://",
+            "cert": "peer2.crt"
+        }
+    ],
+    "keyValStore": "/YOUR_HOME_DIR/.composer-credentials",
+    "channel": "composerchannel",
+    "mspID": "Org1MSP",
+    "timeout": 300,
+    "globalcert": "",
+    "maxSendSize": 10,
+    "maxRecvSize": 15
+}

packages/composer-common/test/data/id-cards/valid-with-enrollment/metadata.json

@@ -0,0 +1,8 @@
+{
+    "name": "Conga",
+    "description": "A valid ID card",
+    "businessNetwork": "org-acme-biznet",
+    "image": "images/conga.png",
+    "enrollmentId": "conga",
+    "enrollmentSecret": "super-secret-passphrase"
+}

packages/composer-common/test/data/id-cards/valid/connection.json

@@ -1,4 +1,5 @@
 {
+    "name": "hlfv1",
     "type": "hlfv1",
     "orderers": [
         {

packages/composer-common/test/data/id-cards/valid/metadata.json

@@ -1,6 +1,6 @@
 {
-    "name" : "com.example.cards.Dan",
-    "description" : "Dan's Card for Production Network",
-    "businessNetwork" : "org-acme-biznet",
-    "image" : "images/conga.png"
+    "name": "Conga",
+    "description": "A valid ID card",
+    "businessNetwork": "org-acme-biznet",
+    "image": "images/conga.png"
 }