@tdxvolt/volt-client-grpc 0.1.0

package/lib/index.cjs

@@ -0,0 +1,1883 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var lodash = require('lodash');
+var ip = require('ip');
+var forge = require('node-forge');
+var bs58 = require('bs58');
+var debug = require('debug');
+var EventEmitter = require('events');
+var fs = require('fs');
+var jwt = require('jsonwebtoken');
+var crypto = require('crypto');
+var path = require('path');
+var protoLoader = require('@grpc/proto-loader');
+var url = require('url');
+var bent = require('bent');
+var uuid = require('uuid');
+
+function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
+
+var lodash__default = /*#__PURE__*/_interopDefaultLegacy(lodash);
+var ip__default = /*#__PURE__*/_interopDefaultLegacy(ip);
+var forge__default = /*#__PURE__*/_interopDefaultLegacy(forge);
+var bs58__default = /*#__PURE__*/_interopDefaultLegacy(bs58);
+var debug__default = /*#__PURE__*/_interopDefaultLegacy(debug);
+var EventEmitter__default = /*#__PURE__*/_interopDefaultLegacy(EventEmitter);
+var fs__default = /*#__PURE__*/_interopDefaultLegacy(fs);
+var jwt__default = /*#__PURE__*/_interopDefaultLegacy(jwt);
+var crypto__default = /*#__PURE__*/_interopDefaultLegacy(crypto);
+var path__default = /*#__PURE__*/_interopDefaultLegacy(path);
+var protoLoader__default = /*#__PURE__*/_interopDefaultLegacy(protoLoader);
+var bent__default = /*#__PURE__*/_interopDefaultLegacy(bent);
+
+// eslint-disable-next-line import/prefer-default-export
+const constants = {
+  authTokenName: "tdx-token",
+  collectionOperation: {
+    add: "ADD",
+    remove: "REMOVE",
+    update: "UPDATE",
+  },
+  crypto: {
+    subjectDefaults: [
+      {
+        name: "countryName",
+        value: "GB",
+      },
+      {
+        name: "localityName",
+        value: "Southampton",
+      },
+      {
+        name: "organizationName",
+        value: "nquiringminds Ltd",
+      },
+    ],
+    userIdOID: "0.9.2342.19200300.100.1.1",
+  },
+  defaultDIDHostName: "volt.tdxcloud.com",
+  didServiceType: {
+    voltConfig: "tdx-volt-config",
+  },
+  identityType: {
+    did: "did",
+    volt: "volt",
+  },
+  onlineStatus: {
+    offline: "offline",
+    online: "online",
+    unknown: "unknown",
+  },
+  publicKeyPrefix: "-----BEGIN PUBLIC KEY-----",
+  privateKeyPrefix: "-----BEGIN RSA PRIVATE KEY-----",
+  privateEncryptedKeyPrefix: "-----BEGIN ENCRYPTED PRIVATE KEY-----",
+  resource: {
+    identity: "ident",
+    identityView: "ident-view",
+    proxy: "proxy",
+    proxyView: "proxy-view",
+    vc: "vc",
+    vcView: "vc-view",
+  },
+  voltStatus: {
+    pending: "",
+    online: "online",
+    offline: "offline",
+    deleted: "deleted",
+    revoked: "revoked",
+  },
+  /**
+   * These top-level service types should map to a protobuf definition
+   * in @tdxvolt/volt-proto.
+   */
+  serviceType: {
+    fileAPI: "tdx.volt_api.volt.v1.FileAPI",
+    protocolBridgeDataStream: "tdx.volt_api.protocol_bridge.v1.ProtocolBridgeStreamAPI",
+    sqliteServerAPI: "tdx.volt_api.data.v1.SqliteServerAPI",
+    ssiAPI: "tdx.volt_api.ssi.v1.SsiAPI",
+    tunnelAPI: "tdx.volt_api.tunnel.v1.TunnelAPI",
+    voltAPI: "tdx.volt_api.volt.v1.VoltAPI",
+    wireAPI: "tdx.volt_api.volt.v1.WireAPI",
+  },
+  tunnelInvokeMethod: "/tdx.volt_api.volt.v1.VoltAPI/Invoke",
+  tunnelPingInterval: 10000,
+  tunnelPingTimeout: 2500,
+  tunnelReconnectAfter: 30000,
+  tunnelTimeoutInterval: 10000 * 2, // This must always be greater than `tunnelPingInterval`.
+};
+
+const {pki: pki$2} = forge__default["default"];
+
+const createSecureContextOptions = (cryptoOptions) => {
+  const tlsOptions = {
+    cert: Buffer.from(cryptoOptions.cert),
+    ca: Buffer.from(cryptoOptions.ca),
+    key: Buffer.from(cryptoOptions.key),
+  };
+  return tlsOptions;
+};
+
+const getServiceAddress = (mdnsService) => {
+  let address;
+
+  if (mdnsService.txtRecord && mdnsService.txtRecord.ip) {
+    // Use the advertised IP address if present.
+    address = `${mdnsService.txtRecord.ip}:${mdnsService.port}`;
+  } else {
+    // Find a valid ipv4 address.
+    const ipv4 = lodash__default["default"].find(mdnsService.addresses, (addy) => ip__default["default"].isV4Format(addy));
+    const serviceDetails = {
+      host: ipv4,
+      port: mdnsService.port,
+    };
+
+    address = `${serviceDetails.host}:${serviceDetails.port}`;
+  }
+
+  return address;
+};
+
+const privateKeyToPem = (keyPair) => {
+  return pki$2.privateKeyToPem(keyPair.privateKey);
+};
+
+const publicKeyToPem = (keyPair) => {
+  return pki$2.publicKeyToPem(keyPair.publicKey);
+};
+
+const deserialisePEM = (pem) => {
+  return pem.replace(/\\r\\n/g, "\r\n");
+};
+
+const removeCarriageReturn = (inp) => {
+  return inp.replace(/\r\n/g, "\n");
+};
+
+const createBase58Hash = (inp) => {
+  const md = forge__default["default"].md.sha256.create();
+  md.update(inp);
+  const hashBuf = Buffer.from(md.digest().getBytes(), "binary");
+  return bs58__default["default"].encode(hashBuf);
+};
+
+const createPublicKeyFingerprint = (key) => {
+  // Remove carriage returns before creating hash to bring into line with openSSL / volt format.
+  return createBase58Hash(removeCarriageReturn(key));
+};
+
+const signBase64 = (key, msg) => {
+  const md = forge__default["default"].md.sha256.create();
+  md.update(msg);
+  const signature = key.sign(md);
+  return forge__default["default"].util.encode64(signature);
+};
+
+const verifyBase64 = (key, msg, signature) => {
+  const md = forge__default["default"].md.sha256.create();
+  md.update(msg);
+  return key.verify(md.digest().bytes(), forge__default["default"].util.decode64(signature));
+};
+
+const getDIDResolutionURL = (didIn) => {
+  const did = didIn.toLowerCase().split(":");
+  if (did.length < 3) {
+    return "";
+  }
+
+  if (did[0] !== "did") {
+    return "";
+  }
+
+  if (did[1] !== "tdx") {
+    return "";
+  }
+
+  let hostName;
+  let didGUID;
+  if (did.length === 3) {
+    hostName = constants.defaultDIDHostName;
+    didGUID = did[2];
+  } else {
+    hostName = did[2];
+    didGUID = did[3];
+  }
+
+  return `https://${hostName}/api/identity/${didGUID}`;
+};
+
+var utils = /*#__PURE__*/Object.freeze({
+  __proto__: null,
+  createSecureContextOptions: createSecureContextOptions,
+  getServiceAddress: getServiceAddress,
+  privateKeyToPem: privateKeyToPem,
+  publicKeyToPem: publicKeyToPem,
+  deserialisePEM: deserialisePEM,
+  removeCarriageReturn: removeCarriageReturn,
+  createBase58Hash: createBase58Hash,
+  createPublicKeyFingerprint: createPublicKeyFingerprint,
+  signBase64: signBase64,
+  verifyBase64: verifyBase64,
+  getDIDResolutionURL: getDIDResolutionURL
+});
+
+/* eslint-disable no-underscore-dangle */
+
+const {forEach, isEmpty} = lodash__default["default"];
+
+const serialiseNOP = (arg) => {
+  return arg;
+};
+
+function createClient(grpc, serviceDescriptors, address, cryptoOptions, noSerialise, voltId, serviceId) {
+  let credentials;
+  if (cryptoOptions) {
+    const ca = cryptoOptions.tunnel_ca_pem || cryptoOptions.ca;
+    const cert = cryptoOptions.cloud_cert || cryptoOptions.cert;
+    const {key} = cryptoOptions;
+
+    if (key && cert) {
+      const cryyptoOptions = {ca, cert, key};
+      const tlsOptions = createSecureContextOptions(cryyptoOptions);
+      credentials = grpc.credentials.createSsl(tlsOptions.ca, tlsOptions.key, tlsOptions.cert);
+    } else {
+      // Cache has no private key, this implies we are connecting without supplying a client certificate.
+      // Simply connect using the CA certificate.
+      credentials = grpc.credentials.createSsl(Buffer.from(ca));
+    }
+  } else {
+    credentials = grpc.credentials.createInsecure();
+  }
+
+  // Force all methods to appear bi-directional, since we manually handle the call flow (see grpc-call.js).
+  forEach(serviceDescriptors, (method) => {
+    method.requestStream = true;
+    method.responseStream = true;
+  });
+
+  if (noSerialise || voltId) {
+    if (voltId && !serviceId) {
+      // We must have a service identifier id when tunnelling in order to be able to route the rpc.
+      throw new Error("createClient - no serviceId given");
+    }
+    forEach(serviceDescriptors, (method) => {
+      if (voltId) {
+        // Prepend the resource id to the method path if tunnelling.
+        if (voltId === serviceId) {
+          method.path = `/${voltId}${method.path}`;
+        } else {
+          method.path = `/${voltId}/${serviceId}${method.path}`;
+        }
+      }
+      if (noSerialise) {
+        // Save original serialisation methods so we can encrypt/decrypt in the tunnel.
+        method.requestSerializeOriginal = method.requestSerialize;
+        method.responseDeserializeOriginal = method.responseDeserialize;
+
+        // Replace default serialisation with NOP, since when tunnelling we encrypt the payload
+        // before sending it to the channel, so we want it to be treated as a pure byte array (pass-through).
+        method.requestSerialize = serialiseNOP;
+        method.responseDeserialize = serialiseNOP;
+      }
+    });
+  }
+
+  const SubClass = grpc.makeGenericClientConstructor(serviceDescriptors);
+
+  return new SubClass(address, credentials);
+}
+
+/**
+ * Implementations should utilise promises => wrap each method as a grpc request/response callback.
+ * @param {*} api
+ */
+const grpcWrap = (api) => {
+  const grpcRoutes = {};
+
+  // Don't bother trying to wrap class constructors.
+  const ignoreMethods = ["constructor"];
+
+  // Support class instances and PoJos
+  const isClass = api.constructor !== Object;
+  const iterate = Object.getOwnPropertyNames(isClass ? api.constructor.prototype : api);
+
+  // Wrap each method on the api.
+  forEach(iterate, (name) => {
+    if (!ignoreMethods.includes(name)) {
+      const method = api[name];
+      grpcRoutes[name] = (call, callback) => {
+        // Execute the method in the context of the api.
+        const resultPromise = method.call(api, call.request, call);
+
+        // Enforce promise results.
+        if (!resultPromise || !resultPromise.then || !resultPromise.catch) {
+          throw new Error(`implementation methods must return a Promise [${name}]`);
+        }
+
+        resultPromise
+          .then((response) => {
+            if (callback) {
+              callback(null, response);
+            }
+          })
+          .catch((err) => {
+            if (callback) {
+              callback(err);
+            } else {
+              // TODO - verify this => how to send error to stream clients?
+              // Destroy stream on error.
+              call.destroy(err);
+            }
+          });
+      };
+    }
+  });
+
+  return grpcRoutes;
+};
+
+class GrpcServer {
+  constructor(options) {
+    const {grpc, serviceDescriptors, routes, tlsOptions, requireClientCert} = options;
+    this._grpc = grpc;
+    this._server = new this._grpc.Server();
+
+    if (tlsOptions) {
+      const caList = [];
+      const certChains = [];
+      [].concat(tlsOptions).forEach((tlsOption) => {
+        caList.push(tlsOption.ca);
+        certChains.push({
+          private_key: tlsOption.key,
+          cert_chain: tlsOption.cert,
+        });
+      });
+
+      // Create credentials from the volt CA and our own pub/priv key.
+      this._credentials = grpc.ServerCredentials.createSsl(
+        // The root CAs we trust when verifying client certificates.
+        Buffer.concat(caList),
+        // The certificate chain(s) we present to the client.
+        certChains,
+        // Flag indicating if we insist on a client certificate.
+        requireClientCert
+      );
+    } else {
+      this._credentials = grpc.ServerCredentials.createInsecure();
+    }
+
+    if (serviceDescriptors && !isEmpty(routes)) {
+      // Enforce decoupling of the service implementation.
+      const router = grpcWrap(routes);
+      this._server.addService(serviceDescriptors, router);
+    }
+  }
+
+  close(force = false) {
+    return new Promise((resolve) => {
+      if (force) {
+        resolve(this._server.forceShutdown());
+      } else {
+        this._server.tryShutdown(resolve);
+      }
+    });
+  }
+
+  listen(address) {
+    return new Promise((resolve, reject) => {
+      // If no port is specified, grpc will return the port number assigned.
+      this._server.bindAsync(address, this._credentials, (err, port) => {
+        if (err) {
+          reject(err);
+        } else {
+          this._port = port;
+          this._server.start();
+          resolve(port);
+        }
+      });
+    });
+  }
+
+  get server() {
+    return this._server;
+  }
+
+  get port() {
+    return this._port;
+  }
+}
+
+function createServer(grpc, serviceDescriptors, routes, cryptoCache, requireClientCert) {
+  let tlsOptions;
+  if (cryptoCache) {
+    tlsOptions = createSecureContextOptions(cryptoCache);
+  }
+  const serverArgs = {grpc, serviceDescriptors, routes, tlsOptions, requireClientCert};
+  return new GrpcServer(serverArgs);
+}
+
+var grpcUtils = /*#__PURE__*/Object.freeze({
+  __proto__: null,
+  createClient: createClient,
+  createServer: createServer
+});
+
+/* eslint-disable no-underscore-dangle */
+
+const {pki: pki$1} = forge__default["default"];
+const log$4 = debug__default["default"]("volt-client-grpc:volt-crypto");
+const aesAlgorithm = "aes-256-cbc";
+const rs256Algorithm = "RS256";
+
+class VoltCrypto {
+  constructor(config, configPath) {
+    this._config = config;
+    this._voltConfig = config.volt;
+    this._configPath = configPath;
+    this._persistCache = !!configPath;
+
+    if (!this._config.crypto) {
+      this._cryptoCache = {};
+    } else {
+      this._cryptoCache = this._config.crypto;
+    }
+
+    // Determine if we're dealing with an encrypted key.
+    if (this._cryptoCache.key && this._cryptoCache.key.startsWith(constants.privateEncryptedKeyPrefix)) {
+      if (!config.p) {
+        throw new Error("encrypted key but no passphrase given");
+      }
+
+      // Need to unencrypt the private key.
+      const decrypted = pki$1.decryptRsaPrivateKey(this._cryptoCache.key, config.p);
+      if (!decrypted) {
+        throw new Error("failed to decrypt key - check passphrase");
+      }
+      this._cryptoCache.key = pki$1.privateKeyToPem(decrypted);
+    }
+
+    if (this._voltConfig.ca_pem) {
+      if (!this._cryptoCache.ca) {
+        // Copy the volt signing CA to the crypto cache.
+        this._cryptoCache.ca = this._voltConfig.ca_pem;
+      }
+
+      // Pre-cache the target Volt public key by extracting it from the signing certificate.
+      const voltCert = forge__default["default"].pki.certificateFromPem(this._voltConfig.ca_pem);
+
+      // Extract Volt public key (used for encrypting tunnel payloads).
+      this._voltPublicKey = forge__default["default"].pki.publicKeyToPem(voltCert.publicKey);
+      this._voltFingerprint = createPublicKeyFingerprint(this._voltPublicKey);
+    }
+  }
+
+  get cache() {
+    return this._cryptoCache;
+  }
+
+  get voltFingerprint() {
+    return this._voltFingerprint;
+  }
+
+  getKey() {
+    const privateKey = pki$1.privateKeyFromPem(this._cryptoCache.key);
+    const publicKey = pki$1.rsa.setPublicKey(privateKey.n, privateKey.e);
+    return {privateKey, publicKey};
+  }
+
+  /**
+   * Retrieves and re-hydrates the pub/priv key data from the crypto cache, or creates one if not found.
+   */
+  createKey() {
+    if (!this._cryptoCache.key) {
+      log$4("creating key");
+      return new Promise((resolve, reject) => {
+        pki$1.rsa.generateKeyPair({bits: 2048, workers: -1}, (err, keypair) => {
+          if (err) {
+            log$4("failure creating key [%s]", err.message);
+            reject(err);
+          } else {
+            log$4("successfully created key");
+            const pem = pki$1.privateKeyToPem(keypair.privateKey);
+            this._cryptoCache.key = pem;
+            resolve(keypair);
+          }
+        });
+      });
+    } else {
+      // Already have key data in the cache in pem format => create fully-formed pki instances.
+      log$4("createKey - key already exists");
+      return Promise.resolve(this.getKey());
+    }
+  }
+
+  /**
+   * Create cryptocache from scratch.
+   */
+  initialise() {
+    return this.createKey()
+      .then((/* keypair */) => {
+        return this.saveCache();
+      })
+      .then(() => {
+        return this._cryptoCache;
+      })
+      .catch((err) => {
+        log$4("failure initialising crypto [%s]", err.message);
+        return Promise.reject(err);
+      });
+  }
+
+  get isBound() {
+    return !!this._cryptoCache.cert;
+  }
+
+  /**
+   * Signs the identity resource id using the private key.
+   * @param {*} audience the token audience (usually the target volt)
+   * @param {*} tunnelling flag indicating if the token is required for a tunnelled connection
+   * @param {*} ttl time to live in seconds (default to 1 minute)
+   */
+  getIdentityToken(audience, tunnelling = false, ttl = 60) {
+    if (!this._cryptoCache.key) {
+      throw new Error("crypto cache invalid");
+    }
+
+    const keyPair = this.getKey();
+    const publicKeyPem = pki$1.publicKeyToPem(keyPair.publicKey);
+    const base58Key = createPublicKeyFingerprint(publicKeyPem);
+
+    log$4("base58 key is %s", base58Key);
+
+    // Allow TTL either side of the current time.
+    // @todo - fix with server time sync on volt connection.
+    const payload = {
+      aud: audience,
+      iat: Math.floor(Date.now() / 1000) - ttl,
+      exp: Math.floor(Date.now() / 1000) + ttl,
+    };
+
+    let sharedKey;
+    if (tunnelling) {
+      // Initialise the tunnel encryption key.
+      sharedKey = VoltCrypto.aesCreateKey();
+
+      // Encrypt the key details using the target Volt public key and include this in the JWT payload.
+      payload.sk = VoltCrypto.rsaEncrypt(this._voltPublicKey, sharedKey.key);
+      payload.iv = VoltCrypto.rsaEncrypt(this._voltPublicKey, sharedKey.iv);
+    }
+
+    // Sign synchronously.
+    const token = jwt__default["default"].sign(payload, this._cryptoCache.key, {algorithm: rs256Algorithm, keyid: base58Key});
+
+    // Return the token along with any encryption key details.
+    return {
+      token,
+      sharedKey,
+    };
+  }
+
+  /**
+   * Creates the metadata required for a grpc call, including the Volt authentication token
+   * and optionally tunnel encryption parameters.
+   * @param {*} grpc
+   * @param {*} audience
+   * @param {*} tunnelling
+   * @param {*} ttl
+   * @returns
+   */
+  getIdentityMetadata(grpc, audience, tunnelling = false, ttl = 10) {
+    const identityToken = this.getIdentityToken(audience || this._voltConfig.id, tunnelling, ttl);
+    const metadata = new grpc.Metadata();
+    metadata.add(constants.authTokenName, identityToken.token);
+    return {...identityToken, metadata};
+  }
+
+  saveCache() {
+    if (this._persistCache) {
+      const clone = {...this._config, crypto: {...this._cryptoCache}};
+      if (this._config.p) {
+        // A passphrase option exists => encrypt the key before writing the cache file.
+        const privateKey = pki$1.privateKeyFromPem(this._cryptoCache.key);
+        clone.crypto.key = pki$1.encryptRsaPrivateKey(privateKey, this._config.p);
+      }
+      fs__default["default"].writeFileSync(this._configPath, JSON.stringify(clone, null, 2));
+    }
+  }
+
+  static aesCreateKey() {
+    // Generate random key for the AES-256 algorithm (32 bytes = 256 bits).
+    const key = crypto__default["default"].randomBytes(32);
+    const iv = crypto__default["default"].randomBytes(16);
+    return {key, iv};
+  }
+
+  static aesEncrypt(buffer, key, iv) {
+    const cipher = crypto__default["default"].createCipheriv(aesAlgorithm, key, iv);
+    const crypted = Buffer.concat([cipher.update(buffer), cipher.final()]);
+    return crypted;
+  }
+
+  static aesDecrypt(buffer, key, iv) {
+    const cipher = crypto__default["default"].createDecipheriv(aesAlgorithm, key, iv);
+    const decrypted = Buffer.concat([cipher.update(buffer), cipher.final()]);
+    return decrypted;
+  }
+
+  static rsaEncrypt(key, buffer) {
+    return crypto__default["default"].publicEncrypt(key, buffer).toString("base64");
+  }
+}
+
+const {get: getProp, snakeCase} = lodash__default["default"];
+const __dirname$1 = path.dirname(url.fileURLToPath((typeof document === 'undefined' ? new (require('u' + 'rl').URL)('file:' + __filename).href : (document.currentScript && document.currentScript.src || new URL('index.cjs', document.baseURI).href))));
+
+const defaultProtoPath = path.join(__dirname$1, "../protobuf");
+
+const defaultLoaderOptions = {
+  keepCase: true,
+  longs: String,
+  enums: String,
+  defaults: true,
+  oneofs: true,
+  includeDirs: [defaultProtoPath],
+};
+
+const getProtoDescriptors = (grpc, protoPath, opts) => {
+  const definition = protoLoader__default["default"].loadSync(protoPath, opts || defaultLoaderOptions);
+  const descriptors = grpc.loadPackageDefinition(definition);
+  return descriptors;
+};
+
+const getProtoService = (descriptors, servicePath) => {
+  const serviceDef = getProp(descriptors, servicePath);
+  if (serviceDef && serviceDef.service) {
+    return serviceDef.service;
+  } else {
+    return null;
+  }
+};
+
+function getServiceDescriptorsFromPath(grpc, protoPath, servicePackageName, opts) {
+  let serviceDescriptors;
+  const descriptors = getProtoDescriptors(grpc, protoPath, opts);
+  if (descriptors) {
+    serviceDescriptors = getProtoService(descriptors, servicePackageName);
+  }
+
+  return serviceDescriptors;
+}
+
+function getServiceDescriptors(grpc, servicePackageName, opts) {
+  // Extract the package components of the service proto package. The package name should be of the
+  // fully qualified proto path, e.g. tdx.volt_api.webcam.v1.WebcamControlAPI.
+  const protoServiceComponents = servicePackageName.split(".");
+
+  // The service name is the last component of the path.
+  const protoServiceName = protoServiceComponents.pop();
+
+  // The actual file name should match the snake case of the service name.
+  const protoFileName = snakeCase(protoServiceName).toLowerCase() + ".proto";
+
+  // The path to the proto file should match each component of the package name.
+  const protoPath = path.join(defaultProtoPath, ...protoServiceComponents, protoFileName);
+
+  let serviceDescriptors;
+  const descriptors = getProtoDescriptors(grpc, protoPath, opts);
+  if (descriptors) {
+    serviceDescriptors = getProtoService(descriptors, servicePackageName);
+  }
+
+  return serviceDescriptors;
+}
+
+function getProtoDescriptorMethods(protoDescriptor) {
+  const methods = [];
+  Object.keys(protoDescriptor).forEach((methodName) => {
+    const method = protoDescriptor[methodName];
+    methods.push({
+      path: method.path,
+      client_streaming: method.requestStream,
+      server_streaming: method.responseStream,
+    });
+  });
+  return methods;
+}
+
+var protoUtils = /*#__PURE__*/Object.freeze({
+  __proto__: null,
+  getServiceDescriptors: getServiceDescriptors,
+  getProtoDescriptors: getProtoDescriptors,
+  getProtoDescriptorMethods: getProtoDescriptorMethods,
+  getServiceDescriptorsFromPath: getServiceDescriptorsFromPath
+});
+
+/* eslint-disable no-underscore-dangle */
+
+const log$3 = debug__default["default"]("volt-client-grpc:grpc-call");
+
+function _prepareInvokeRequest(request, method, methodType = "METHOD_TYPE_UNARY") {
+  const meta = this._voltClient.crypto.getIdentityMetadata(
+    this._voltClient.grpc,
+    this._voltClient.options.id,
+    this._voltClient.isRemote
+  );
+  let invokeRequest;
+  let callMethod = method;
+
+  if (this._voltClient.isVoltTunnel) {
+    let requestPayload;
+    if (request) {
+      requestPayload = this._grpcClient[method].requestSerialize(request);
+    } else if (request !== null) {
+      log$3("****************LOOKOUT****************** - empty request");
+    } else {
+      log$3("explicit empty request payload");
+    }
+
+    const tunnelMethod = this._grpcClient.Tunnel;
+
+    const tunnelResp = {
+      method_invoke: {
+        method_name: this._grpcClient[method].path,
+        method_type: methodType,
+        token: meta.token,
+        request: requestPayload,
+      },
+    };
+
+    const invokePayload = VoltCrypto.aesEncrypt(
+      tunnelMethod.responseSerialize(tunnelResp),
+      meta.sharedKey.key,
+      meta.sharedKey.iv
+    );
+
+    log$3("target volt is %s", this._voltClient.crypto.voltFingerprint);
+
+    invokeRequest = {
+      identity_fingerprint: this._voltClient.crypto.voltFingerprint,
+      payload: invokePayload,
+    };
+
+    callMethod = "Invoke";
+  } else if (this._voltClient.isRemote && meta.sharedKey.key) {
+    const requestPayload = this._grpcClient[method].requestSerializeOriginal(request);
+    invokeRequest = VoltCrypto.aesEncrypt(requestPayload, meta.sharedKey.key, meta.sharedKey.iv);
+  } else {
+    invokeRequest = request;
+  }
+
+  return {
+    meta,
+    method: callMethod,
+    methodName: method,
+    request: invokeRequest,
+  };
+}
+
+function _preparePayloadRequest(request, invokeInfo) {
+  let payloadRequest;
+
+  if (this._voltClient.isVoltTunnel) {
+    const requestPayload = this._grpcClient[invokeInfo.methodName].requestSerialize(request);
+    const tunnelMethod = this._grpcClient.Tunnel;
+
+    const tunnelResp = {
+      method_payload: {
+        payload: requestPayload,
+      },
+    };
+
+    const invokePayload = VoltCrypto.aesEncrypt(
+      tunnelMethod.responseSerialize(tunnelResp),
+      invokeInfo.meta.sharedKey.key,
+      invokeInfo.meta.sharedKey.iv
+    );
+
+    payloadRequest = {
+      payload: invokePayload,
+    };
+  } else if (this._voltClient.isRemote && invokeInfo.meta.sharedKey.key) {
+    const requestPayload = this._grpcClient[invokeInfo.methodName].requestSerializeOriginal(request);
+    payloadRequest = VoltCrypto.aesEncrypt(requestPayload, invokeInfo.meta.sharedKey.key, invokeInfo.meta.sharedKey.iv);
+  } else {
+    payloadRequest = request;
+  }
+
+  return payloadRequest;
+}
+
+function _parseResponse(method, meta, response) {
+  let invokeResponse = {};
+
+  if (this._voltClient.isVoltTunnel) {
+    if (response.payload) {
+      const decryptedPayload = VoltCrypto.aesDecrypt(response.payload, meta.sharedKey.key, meta.sharedKey.iv);
+      const tunnelMethod = this._grpcClient.Tunnel;
+      const responsePayload = tunnelMethod.requestDeserialize(decryptedPayload);
+      if (responsePayload.payload === "method_payload") {
+        invokeResponse.payload = this._grpcClient[method].responseDeserialize(responsePayload.method_payload.payload);
+      } else if (responsePayload.payload === "method_end") {
+        invokeResponse = responsePayload.method_end;
+      } else {
+        log$3("unexpected tunnel payload type: %s", responsePayload.payload);
+      }
+    } else if (response.status && response.status.message) {
+      // There's been an error in the tunnel.
+      log$3(
+        "Tunnel status received: %s, code %d, description: %s",
+        response.status.message,
+        response.status.code,
+        response.status.description || "n/a"
+      );
+      invokeResponse = {ended: true, error: `Error in tunnel: ${response.status.message}`};
+    } else {
+      invokeResponse.methodId = response.invoke_id;
+      log$3("started method %d for %s", invokeResponse.methodId, method);
+    }
+  } else if (this._voltClient.isRemote && meta.sharedKey.key) {
+    const decryptedPayload = VoltCrypto.aesDecrypt(response, meta.sharedKey.key, meta.sharedKey.iv);
+    invokeResponse = {payload: this._grpcClient[method].responseDeserializeOriginal(decryptedPayload)};
+  } else {
+    invokeResponse = {payload: response};
+  }
+
+  return invokeResponse;
+}
+
+class GRPCCall extends EventEmitter__default["default"] {
+  constructor(voltClient, methodName, methodType) {
+    super();
+    this._methodName = methodName;
+    this._methodType = methodType;
+    this._call = null;
+    this._voltClient = voltClient;
+    this._lastResponse = null;
+    this._promise = null;
+    this._reject = null;
+  }
+
+  reject(err) {
+    if (this._reject) {
+      this._reject(err);
+    }
+  }
+
+  wait() {
+    return this._promise;
+  }
+
+  start(grpcClient, request, responseCB) {
+    this._promise = new Promise((resolve, reject) => {
+      this._grpcClient = grpcClient;
+      this._reject = reject;
+
+      const callbackIntercept = (err, response) => {
+        log$3("received callback for method %s", this._methodName);
+        if (err) {
+          reject(err);
+        } else if (response) {
+          this._lastResponse = response;
+          if (responseCB) {
+            responseCB(err, response);
+          }
+        } else {
+          this.end();
+          resolve(this._lastResponse);
+        }
+      };
+
+      this._initialRequest = _prepareInvokeRequest.call(this, request, this._methodName, this._methodType);
+
+      this._call = this._grpcClient[this._initialRequest.method](this._initialRequest.meta.metadata, callbackIntercept);
+
+      this._call.on("data", (streamResponse) => {
+        try {
+          const parsedResponse = _parseResponse.call(this, this._methodName, this._initialRequest.meta, streamResponse);
+          if (parsedResponse.payload) {
+            callbackIntercept(null, parsedResponse.payload);
+          } else if (parsedResponse.ended) {
+            if (parsedResponse.error) {
+              callbackIntercept(new Error(parsedResponse.error), null);
+            } else {
+              callbackIntercept(null, null);
+            }
+          } else {
+            log$3("method id is %s", parsedResponse.methodId);
+          }
+        } catch (err) {
+          log$3("failure processing connect response: %s", err.message);
+          this.emit("error", err);
+        }
+      });
+
+      this._call.on("error", (err) => {
+        log$3("ERROR - intercepted stream error %s", err.message);
+        callbackIntercept(err, null);
+      });
+
+      this._call.on("finish", () => {
+        // The read side has ended (i.e. we called end()).
+        log$3("finished call %s", this._methodName);
+        this.emit("finish");
+      });
+
+      this._call.on("end", () => {
+        // The remote peer ended the stream.
+        log$3("ended call %s, method id: %s", this._methodName, this._initialRequest.methodId || "n/a - not tunnelling");
+        this.emit("end");
+        callbackIntercept(null, null);
+      });
+
+      if (this._initialRequest.request) {
+        this._call.write(this._initialRequest.request);
+      }
+    });
+
+    return this;
+  }
+
+  end() {
+    if (!this._call) {
+      throw new Error("call not initialised");
+    } else {
+      return this._call.end();
+    }
+  }
+
+  get writable() {
+    return this._call && this._call.writable;
+  }
+
+  write(request) {
+    if (!this._call) {
+      log$3("ERROR - call not initialised");
+      throw new Error("call not initialised");
+    } else if (!this._initialRequest) {
+      this._initialRequest = _prepareInvokeRequest.call(this, request, this._methodName, this._methodType);
+
+      return this._call.write(this._initialRequest.request);
+    } else {
+      const payloadRequest = _preparePayloadRequest.call(this, request, this._initialRequest);
+      return this._call.write(payloadRequest);
+    }
+  }
+}
+
+/* eslint-disable no-use-before-define */
+
+const log$2 = debug__default["default"]("volt-client-grpc:volt-connection");
+
+function _cleanUp(immediateReconnect) {
+  this._session = false;
+
+  if (this._pingTimer) {
+    clearTimeout(this._pingTimer);
+    this._pingTimer = 0;
+  }
+
+  if (this._pingTimeoutTimer) {
+    clearTimeout(this._pingTimeoutTimer);
+    this._pingTimeoutTimer = 0;
+  }
+
+  if (!this._dying && (immediateReconnect || (this._autoRetry && !this._reconnectTimer))) {
+    this._reconnectTimer = setTimeout(
+      () => {
+        this._reconnectTimer = 0;
+        _doConnect.call(this);
+      },
+      immediateReconnect ? 0 : this._reconnectInterval
+    );
+  }
+
+  if (this.call && this.call.writable) {
+    this.call.end();
+  }
+}
+
+function _connectionTimeoutHandler() {
+  log$2("server timed out");
+  this.emit("connected", false);
+  _cleanUp.call(this);
+}
+
+function _doConnect() {
+  this.call = new GRPCCall(this._voltClient, "Connect", "METHOD_TYPE_BIDI");
+
+  const grpcClient = this._voltClient.getVoltAPIClient();
+  const helloPayload = {
+    hello: {},
+  };
+
+  this.call.start(grpcClient, helloPayload, (err, response) => {
+    if (err) {
+      log$2("error on connection stream [%s]", err.message);
+      _cleanUp.call(this);
+      this.emit("error", err);
+    } else {
+      switch (response.payload) {
+        case "ping": {
+          log$2("pinged");
+
+          // Received ping response from server => clear timeout.
+          if (this._pingTimeoutTimer) {
+            clearTimeout(this._pingTimeoutTimer);
+          }
+
+          // Schedule the next ping.
+          _startPingTimer.call(this);
+          break;
+        }
+        case "hello":
+          if (!this._session) {
+            this._session = true;
+            this.emit("connected", this._session);
+          }
+          break;
+        case "evt":
+          log$2("received event %s", response.evt.event_type);
+          this.emit("evt", response.evt);
+          break;
+        default:
+          log$2("unimplemented connect response payload: %s", response.payload);
+          break;
+      }
+    }
+  });
+
+  this.call
+    .wait()
+    .then(() => {
+      if (this._session) {
+        this.emit("connected", false);
+      }
+    })
+    .catch((err) => {
+      log$2("unexpected error on connect call [%s]", err.message);
+    })
+    .finally(() => {
+      _cleanUp.call(this);
+    });
+
+  _startPingTimer.call(this);
+}
+
+function _startPingTimer() {
+  if (this._pingTimer) {
+    log$2("ping timer running");
+    return;
+  }
+
+  this._pingTimer = setTimeout(() => {
+    // Send next ping to server.
+    const request = {ping: {timestamp: Date.now()}};
+
+    log$2("pinging Volt");
+    this.call.write(request);
+
+    this._pingTimer = 0;
+
+    // Schedule a timeout if we don't hear back from the server.
+    if (this._pingTimeoutTimer) {
+      clearTimeout(this._pingTimeoutTimer);
+    }
+
+    this._pingTimeoutTimer = setTimeout(_connectionTimeoutHandler.bind(this), this._timeoutInterval);
+  }, this._pingInterval);
+}
+
+class VoltConnection extends EventEmitter__default["default"] {
+  constructor(voltClient, grpc, options = {}) {
+    super();
+
+    this._grpc = grpc;
+    this._autoRetry = options.autoReconnect === undefined ? true : !!options.autoReconnect;
+    this._dying = false;
+    this._voltClient = voltClient;
+    this._options = options;
+    this._pingTimer = 0;
+    this._pingTimeoutTimer = 0;
+    this._session = false;
+    this._pingInterval = options.pingInterval || 10000;
+    this._reconnectInterval = options.reconnectInterval || 5000;
+    this._timeoutInterval = options.timeoutInterval || 60000;
+  }
+
+  connect(throwOnFail) {
+    if (throwOnFail) {
+      return _doConnect.call(this);
+    } else {
+      return Promise.resolve(_cleanUp.call(this, true));
+    }
+  }
+
+  disconnect() {
+    this._dying = true;
+    _cleanUp.call(this);
+  }
+}
+
+/* eslint-disable no-underscore-dangle */
+
+const {pki} = forge__default["default"];
+const {filter, pick} = lodash__default["default"];
+
+const log$1 = debug__default["default"]("volt-client-grpc:volt-client-internal");
+const voltServices = [
+  constants.serviceType.voltAPI,
+  constants.serviceType.fileAPI,
+  constants.serviceType.sqliteServerAPI,
+  constants.serviceType.ssiAPI,
+  constants.serviceType.tunnelAPI,
+  constants.serviceType.wireAPI,
+];
+
+function issueBind(bindRequest, ttl) {
+  // eslint-disable-next-line no-use-before-define
+  return unaryCall.call(this, "Bind", bindRequest).then((bindResponse) => {
+    log$1("got binding request response %j", bindResponse);
+    if (bindResponse.status && bindResponse.status.code) {
+      log$1("error in bind response: %s", bindResponse.status.message);
+      return Promise.reject(new Error(bindResponse.status.message));
+    } else {
+      switch (bindResponse.decision) {
+        case "POLICY_DECISION_PERMIT":
+          //
+          // The request status is permit => cache the bind response info.
+          //
+
+          // This is the certificate assigned to us by the volt.
+          this._crypto.cache.cert = bindResponse.cert;
+
+          // This is the signing CA used by the volt (don't ov)
+          this._crypto.cache.ca = bindResponse.chain;
+
+          // Resource id is assigned by the volt.
+          this._crypto.cache.client_id = bindResponse.identity_id;
+          this._crypto.saveCache();
+          break;
+        case "POLICY_DECISION_DENY":
+          log$1(">>>>>>>>>>>>>>> access request is DENIED <<<<<<<<<<<<<<<<<<<");
+          break;
+        case "POLICY_DECISION_PROMPT":
+        case "POLICY_DECISION_PENDING":
+          log$1("access pending approval - waiting...");
+          break;
+        default:
+          log$1("ignoring unknown bind descision %s", bindResponse.status);
+          break;
+      }
+    }
+
+    return bindResponse.decision;
+  });
+}
+
+function findDIDDocumentService(document, serviceType) {
+  if (!document.service) {
+    return [];
+  }
+
+  const matches = filter(document.service, (svc) => svc.type === serviceType);
+  return matches;
+}
+
+async function bindInternal() {
+  try {
+    // Build grpc client info.
+    if (this.isRemote) {
+      const getJSON = bent__default["default"]("json");
+      // @todo - currently Volt tunnel CA discovery is not secure.
+      const protocol =
+        this._config.tunnel_host?.startsWith("localhost:") || this._config.cloud_host?.startsWith("localhost:")
+          ? "http"
+          : "https";
+      const tunnelURL = `${protocol}://${this._config.tunnel_host || this._config.cloud_host}/info`;
+      log$1("attempting to retrieve tunnel information from %s", tunnelURL);
+      const tunnelInfo = await getJSON(tunnelURL);
+      if (!tunnelInfo.ca_pem) {
+        throw new Error("Unable to fetch tunnel CA - cannot securely connect.");
+      } else {
+        log$1("Auto-fetched tunnel CA %s, remote address %s", tunnelInfo.ca_pem, tunnelInfo.local_address);
+        this._crypto.cache.tunnel_ca_pem = tunnelInfo.ca_pem;
+        this._crypto.cache.tunnel_address = tunnelInfo.local_address;
+      }
+    }
+
+    if (!this._crypto.cache.ca) {
+      this._crypto.cache.ca = this._options.ca_pem;
+    }
+
+    if (!this._crypto.cache.ca) {
+      throw new Error("No certificate authority found in configuration for target Volt - check configuration");
+    }
+
+    const keyPair = this._crypto.getKey();
+    const publicKeyPem = pki.publicKeyToPem(keyPair.publicKey);
+
+    if (!this._crypto.cache.bindIp) {
+      // Default the IP address if none is specified. This is used to set the SAN in the
+      // certificate issued by the Volt.
+      this._crypto.cache.bindIp = ip__default["default"].address();
+    }
+
+    this._crypto.saveCache();
+
+    // Form the request message.
+    const bindRequest = {
+      binding_name: this._config.client_name,
+      public_key: publicKeyPem,
+      host: this._crypto.cache.bindIp,
+      x509_credential: [],
+    };
+
+    if (this._crypto.cache.cert) {
+      bindRequest.x509_credential = [this._crypto.cache.cert + this._crypto.cache.ca];
+    }
+
+    if (this._options.challenge_code) {
+      bindRequest.challenge = signBase64(keyPair.privateKey, this._options.challenge_code);
+    } else {
+      log$1("****no Volt challenge code available**** => not sending challenge signature");
+    }
+
+    // For remote connections, add our cloud-issued certificate as an additional credential.
+    if (this._crypto.cache.tunnel_ca_pem && this._crypto.cache.cloud_cert) {
+      bindRequest.x509_credential = bindRequest.x509_credential.concat(
+        this._crypto.cache.cloud_cert + this._crypto.cache.tunnel_ca_pem
+      );
+    }
+
+    log$1("sending %d x509 credentials", bindRequest.x509_credential.length);
+    log$1("bind TTL is ", this._config.bindRequestTTL);
+
+    // This will block while the request is pending.
+    const pollInterval = 10000;
+    let decision = "";
+    do {
+      if (decision) {
+        // Wait a while before retrying.
+        // eslint-disable-next-line no-await-in-loop
+        await new Promise((resolve) => setTimeout(resolve, pollInterval));
+      }
+      // eslint-disable-next-line no-await-in-loop
+      decision = await issueBind.call(this, bindRequest, this._options.bindRequestTTL);
+      log$1("binding decision: %s", decision);
+    } while (decision === "POLICY_DECISION_PROMPT" || decision === "POLICY_DECISION_PENDING");
+
+    return decision === "POLICY_DECISION_PERMIT";
+  } catch (err) {
+    log$1("failure binding to Volt [%s]", err.message);
+    throw err;
+  }
+}
+
+function connectInternal() {
+  try {
+    if (this._voltConnection) {
+      log$1("connectInternal - Volt connection already exists");
+      return Promise.resolve();
+    }
+
+    const onDisconnected = () => {
+      this._connected = false;
+      this._session = null;
+
+      if (this._cachedClient) {
+        this._grpc.closeClient(this._cachedClient);
+        this._cachedClient = null;
+      }
+
+      if (this._cachedRemoteClient) {
+        this._grpc.closeClient(this._cachedRemoteClient);
+        this._cachedRemoteClient = null;
+      }
+    };
+
+    this._voltConnection = new VoltConnection(this, this._grpc, this._options);
+
+    this._voltConnection.on("connected", (session) => {
+      this._session = session;
+      this._connected = !!session;
+      if (!this._connected) {
+        onDisconnected();
+      }
+      this.emit("connected", !!session);
+    });
+
+    this._voltConnection.on("error", (err) => {
+      // Should auto-reconnect.
+      log$1("Volt connection error [%s]", err.message);
+      if (this._connected) {
+        onDisconnected();
+        this.emit("connected", false);
+      }
+    });
+
+    this._voltConnection.on("evt", (evt) => {
+      this.emit("evt", evt);
+    });
+
+    return this._voltConnection.connect();
+  } catch (err) {
+    log$1("connect - error [%s]", err.message);
+    throw err;
+  }
+}
+
+function getVoltAPIClientInternal() {
+  if (!this._cachedClient) {
+    const serviceAddress = this.isRemote ? this._crypto.cache.tunnel_address : this._options.local_address;
+    log$1("creating cached VoltAPI service client on %s", serviceAddress);
+    let serviceDescriptors = {};
+    voltServices.forEach((pkg) => {
+      const packageDescriptors = getServiceDescriptors(this._grpc, pkg);
+      serviceDescriptors = {...serviceDescriptors, ...packageDescriptors};
+    });
+
+    this._cachedClient = createClient(
+      this._grpc,
+      serviceDescriptors,
+      serviceAddress,
+      this._crypto.cache,
+      this.isRemote && !this.isVoltTunnel,
+      this._config.cloud_host ? this._options.id : "",
+      this._config.cloud_host ? this._options.id : ""
+    );
+  }
+
+  return this._cachedClient;
+}
+
+function unaryCall(method, request) {
+  const grpcClient = this.getVoltAPIClient();
+
+  const call = new GRPCCall(this, method, "METHOD_TYPE_UNARY");
+  call.start(grpcClient, request);
+  return call.wait();
+}
+
+async function fetchVoltConfig(volt_did) {
+  const didResolution = getDIDResolutionURL(volt_did);
+  if (!didResolution) {
+    throw new Error(`Invalid Volt DID: ${volt_did}`);
+  }
+
+  const getJSON = bent__default["default"]("json");
+  const didDocument = await getJSON(didResolution);
+  const voltConfigServices = findDIDDocumentService(didDocument, constants.didServiceType.voltConfig);
+  if (voltConfigServices.length !== 1) {
+    log$1(
+      "Unexpected number of Volt configuration endpoints found in DID document for %s, services found: %d",
+      volt_did,
+      voltConfigServices.length
+    );
+  }
+  const serviceEndpoint = voltConfigServices[0].serviceEndpoint;
+  const resolvedConfig = await getJSON(serviceEndpoint);
+
+  const voltConfig = pick(
+    resolvedConfig,
+    "id",
+    "display_name",
+    "public_key",
+    "fingerprint",
+    "local_address",
+    "ca_pem",
+    "challenge_code"
+  );
+
+  return {
+    volt: voltConfig,
+    tunnel_ca_pem: resolvedConfig.tunnel_ca_pem,
+    tunnel_address: resolvedConfig.tunnel_address,
+    cloud_host: resolvedConfig.tunnel_address.split(":")[0],
+  };
+}
+
+const {readFile} = fs__default["default"].promises;
+const log = debug__default["default"]("volt-client-grpc:volt-client");
+
+class VoltClient extends EventEmitter__default["default"] {
+  /**
+   * @param {object} grpc - an instance of the grpc module (see https://www.npmjs.com/package/grpc)
+   */
+  constructor(grpc) {
+    super();
+
+    if (!grpc) {
+      throw new Error("invalid arguments, grpc is required");
+    }
+    this._grpc = grpc;
+    this._cachedClient = null;
+    this._cachedRemoteClient = null;
+    this._session = null;
+    this._config = null;
+    this._options = null;
+    this._voltConnection = null;
+  }
+
+  get config() {
+    return this._config;
+  }
+
+  get crypto() {
+    return this._crypto;
+  }
+
+  get grpc() {
+    return this._grpc;
+  }
+
+  get options() {
+    return this._options;
+  }
+
+  /**
+   * Initialises a binding and connection to the volt.
+   * @param {string} [config] - the location of the Volt configuration file, or a configuration object
+   */
+  async initialise(config, extras = {}) {
+    try {
+      if (!config) {
+        throw new Error("configPath argument is required to be a non-empty string");
+      }
+
+      let configPath;
+      let configJSON;
+      if (typeof config === "string") {
+        configPath = path__default["default"].resolve(config);
+        log("Attempt to load config from file %s", configPath);
+        try {
+          const configContents = await readFile(new URL(configPath, (typeof document === 'undefined' ? new (require('u' + 'rl').URL)('file:' + __filename).href : (document.currentScript && document.currentScript.src || new URL('index.cjs', document.baseURI).href))));
+          configJSON = JSON.parse(configContents);
+        } catch (err) {
+          log("failure loading config file %s [%s]", configPath, err.message);
+          throw new Error(`failed to load configuration - check JSON format in ${configPath}`);
+        }
+      } else if (typeof config === "object") {
+        configJSON = config;
+      } else {
+        throw new Error("config must be either a file path or a config object");
+      }
+
+      if (!configJSON || typeof configJSON !== "object") {
+        throw new Error("config argument is required to be an object");
+      }
+
+      if (!configJSON.client_name || typeof configJSON.client_name !== "string") {
+        throw new Error("client_name property required in config");
+      }
+
+      this._config = {...configJSON, ...extras};
+
+      if (this._config.volt_did && !this._config.volt) {
+        // No Volt configuration, attempt to discover it via the given DID.
+        const didConfig = await fetchVoltConfig.call(this, this._config.volt_did);
+        log("resolved config from DID: %s", JSON.stringify(didConfig, null, 2));
+        this._config = {...this._config, ...didConfig};
+      }
+
+      this._options = this._config.volt;
+
+      if (!this._options || typeof this._options !== "object") {
+        throw new Error("configuration is missing the 'volt' object");
+      }
+
+      if (!this._options.id || typeof this._options.id !== "string") {
+        throw new Error("'id' property is missing in Volt configuration");
+      }
+
+      this._crypto = new VoltCrypto(this._config, configPath);
+
+      await this._crypto.initialise();
+
+      if (!this.isRemote) {
+        // If we're not connecting via a tunnel, we must have the address and CA.
+        if (!this._options.local_address || typeof this._options.local_address !== "string") {
+          throw new Error("'local_address' property missing in Volt configuration");
+        }
+
+        if (!this._options.ca_pem || typeof this._options.ca_pem !== "string") {
+          throw new Error("'ca_pPem' property missing in Volt configuration");
+        }
+      }
+
+      let isBound;
+      if (!this._crypto._cryptoCache.cert) {
+        // No certificate present in the cache yet => we need to bind.
+        try {
+          isBound = await bindInternal.call(this);
+        } catch (bindErr) {
+          if (bindErr.message === "invalid arguments") {
+            // This is usually the result of a missing challenge signature or credential.
+            log("failure binding to Volt - did you supply a challenge code or verified credential?");
+            throw bindErr;
+          }
+        }
+      } else {
+        isBound = true;
+      }
+
+      if (!isBound) {
+        // This is usually because of request being denied.
+        throw new Error("Volt binding failed");
+      }
+
+      return Promise.resolve();
+    } catch (err) {
+      log("Failure starting Volt client [%s]", err.message);
+      throw err;
+    }
+  }
+
+  initialiseAndConnect(configPath, extras = {}) {
+    return this.initialise(configPath, extras)
+      .then(() => {
+        return connectInternal.call(this);
+      })
+      .catch((err) => {
+        log("startAndConnect failure: %s", err.message);
+        return Promise.reject(err);
+      });
+  }
+
+  /**
+   * Creates a GRPC client for the given Volt service description.
+   *
+   * Automatically handles remote connections.
+   *
+   * n.b. for this javascript client Protobuf definitions should conform to the recommended
+   * structure, which is that a package proto file resides in a folder path that matches the
+   * package name, and services contained in the package are named in in Pascal Case and using
+   * the suffix 'API'. For example the WebcamControlAPI in package tdx.volt_api.webcam.v1 should reside
+   * in a protobuf file at tdx/api/webcam/v1/webcam_control_api.proto
+   *
+   * @param {object} service a service description.
+   * @param {object} descriptors the service descriptors, must be specified unless the service
+   * packages are well-known Volt APIs.
+   */
+  createServiceClient(service, descriptors) {
+    const pkg = service.service_description.service_api;
+
+    let serviceDescriptors;
+    if (!descriptors) {
+      serviceDescriptors = {};
+      pkg.forEach((svc) => {
+        log("adding service %s to service client", svc);
+        const packageDescriptors = getServiceDescriptors(this._grpc, svc);
+        serviceDescriptors = {...serviceDescriptors, ...packageDescriptors};
+      });
+    } else {
+      serviceDescriptors = descriptors;
+    }
+
+    if (this.isRemote) {
+      if (!this._crypto.cache.tunnel_address) {
+        throw new Error("Remote connection enabled but no tunnel address - have you called start()?");
+      }
+
+      // In remote mode => create a client using the discovered tunnel address **and** passing the service reourceId
+      return createClient(
+        this._grpc,
+        serviceDescriptors,
+        this._crypto.cache.tunnel_address,
+        this._crypto.cache,
+        false,
+        service.volt_id,
+        service.id
+      );
+    } else {
+      return createClient(
+        this._grpc,
+        serviceDescriptors,
+        service.service_description.local_address,
+        this._crypto.cache
+      );
+    }
+  }
+
+  get isRemote() {
+    return (this._config.cloud_host || this._config.tunnel_host) && this._options.id;
+  }
+
+  get isVoltTunnel() {
+    return this.isRemote && this._config.tunnel_host;
+  }
+
+  connect() {
+    return connectInternal.call(this);
+  }
+
+  disconnect() {
+    if (this._voltConnection) {
+      this._voltConnection.disconnect();
+      this._voltConnection = null;
+    }
+  }
+
+  getVoltAPIClient() {
+    return getVoltAPIClientInternal.call(this);
+  }
+
+  /**
+   * Request resource access.
+   * @param {*} targetResourceId
+   * @param {*} accessType - see vault.proto for enum values.
+   */
+  async RequestAccessBlocking(targetResourceId, accessType = "VOLT_ACCESS_READ") {
+    try {
+      const accessRequest = {
+        access: accessType,
+        resource_id: targetResourceId,
+      };
+
+      // This will block while the request is pending.
+      // TODO - implement streamed rpc on volt? Not sure there is a need really...
+      const pollInterval = 10000;
+      let decision = "";
+      do {
+        if (decision) {
+          await new Promise((resolve) => setTimeout(resolve, pollInterval));
+        }
+        const accessResponse = await this.RequestAccess(accessRequest);
+        decision = accessResponse.decision;
+        log("access decision: %s", decision);
+      } while (decision === "POLICY_DECISION_PROMPT" || decision === "POLICY_DECISION_PENDING");
+
+      log("requestResourceAccess result is %j", decision);
+      return decision === "POLICY_DECISION_PERMIT";
+    } catch (err) {
+      log("failure requesting resource access [%s]", err.message);
+      return Promise.reject(err);
+    }
+  }
+
+  /**
+   * VoltAPI - resource management
+   */
+
+  CanAccessResource(request) {
+    return unaryCall.call(this, "CanAccessResource", request);
+  }
+
+  DeleteResource(request) {
+    return unaryCall.call(this, "DeleteResource", request);
+  }
+
+  DiscoverServices(request) {
+    return unaryCall.call(this, "DiscoverServices", request);
+  }
+
+  GetResource(request) {
+    return unaryCall.call(this, "GetResource", request);
+  }
+
+  GetResources(request) {
+    return unaryCall.call(this, "GetResources", request);
+  }
+
+  GetResourceAncestors(request) {
+    return unaryCall.call(this, "GetResourceAncestors", request);
+  }
+
+  GetResourceDescendants(request) {
+    return unaryCall.call(this, "GetResourceDescendants", request);
+  }
+
+  RequestAccess(request) {
+    return unaryCall.call(this, "RequestAccess", request);
+  }
+
+  SaveResource(request) {
+    return unaryCall.call(this, "SaveResource", request);
+  }
+
+  SaveResourceAttribute(request) {
+    return unaryCall.call(this, "SaveResourceAttribute", request);
+  }
+
+  SetServiceStatus(request) {
+    return unaryCall.call(this, "SetServiceStatus", request);
+  }
+
+  /**
+   * VoltAPI - volt management
+   */
+
+  Bind(request) {
+    return unaryCall.call(this, "Bind", request);
+  }
+
+  DeleteAccess(request) {
+    return unaryCall.call(this, "DeleteAccess", request);
+  }
+
+  DeleteVolt(request) {
+    return unaryCall.call(this, "DeleteVolt", request);
+  }
+
+  GetAccess(request) {
+    return unaryCall.call(this, "GetAccess", request);
+  }
+
+  GetBindings(request) {
+    return unaryCall.call(this, "GetBindings", request);
+  }
+
+  GetIdentities(request) {
+    return unaryCall.call(this, "GetIdentities", request);
+  }
+
+  GetIdentity(request) {
+    return unaryCall.call(this, "GetIdentity", request);
+  }
+
+  GetIdentityToken(request) {
+    return unaryCall.call(this, "GetIdentityToken", request);
+  }
+
+  GetPolicy(request) {
+    return unaryCall.call(this, "GetPolicy", request);
+  }
+
+  GetSettings(request) {
+    return unaryCall.call(this, "GetSettings", request);
+  }
+
+  SaveAccess(request) {
+    return unaryCall.call(this, "SaveAccess", request);
+  }
+
+  SaveCloudConnection(request) {
+    return unaryCall.call(this, "SaveCloudConnection", request);
+  }
+
+  SaveIdentity(request) {
+    return unaryCall.call(this, "SaveIdentity", request);
+  }
+
+  SaveSettings(request) {
+    return unaryCall.call(this, "SaveSettings", request);
+  }
+
+  SetAccessRequestDecision(request) {
+    return unaryCall.call(this, "SetAccessRequestDecision", request);
+  }
+
+  SetBindingDecision(request) {
+    return unaryCall.call(this, "SetBindingDecision", request);
+  }
+
+  Shutdown(request) {
+    return unaryCall.call(this, "Shutdown", request);
+  }
+
+  SignVerify(request) {
+    return unaryCall.call(this, "SignVerify", request);
+  }
+
+  /**
+   * FileAPI
+   */
+  GetFileDescendants(request) {
+    return unaryCall.call(this, "GetFileDescendants", request);
+  }
+
+  /**
+   * Asynchronous file download
+   * @param {*} request
+   * @returns stream
+   */
+  DownloadFile(request) {
+    const grpcClient = this.getVoltAPIClient();
+
+    return new Promise((resolve, reject) => {
+      const meta = this._crypto.getIdentityMetadata(this._grpc, this._options.id, this.isRemote);
+      resolve(grpcClient.DownloadFile(request, meta.metadata));
+    }).catch((err) => {
+      log("error during %s [%s]", method, err.message);
+      return Promise.reject(err);
+    });
+  }
+
+  UploadFile(request, callback) {
+    const grpcClient = this.getVoltAPIClient();
+
+    const uploadCall = new GRPCCall(this, "UploadFile", "METHOD_TYPE_BIDI");
+    return uploadCall.start(grpcClient, request, callback);
+  }
+
+  /**
+   * Synchronous file download
+   * @param {*} request
+   * @returns file buffer, base64 encoded
+   */
+  DownloadFileSync(request) {
+    const grpcClient = this.getVoltAPIClient();
+
+    const blocks = [];
+
+    const call = new GRPCCall(this, "DownloadFile", "METHOD_TYPE_SERVER_STREAM");
+    call.start(grpcClient, request, (err, response) => {
+      if (err) {
+        return call.reject(err);
+      }
+
+      switch (response.payload) {
+        case "block":
+          blocks.push(response.block);
+          break;
+        case "status":
+          if (response.status.message) {
+            return call.reject(new Error(response.status.message));
+          }
+          break;
+        default:
+          log("unrecognised response payload %s", response.payload);
+          break;
+      }
+    });
+
+    return call
+      .wait()
+      .then(() => {
+        log("Download finished");
+        return {buffer: Buffer.concat(blocks).toString("base64")};
+      })
+      .catch((err) => {
+        log("error during DownloadFile [%s]", err.message);
+        return Promise.reject(err);
+      });
+  }
+
+  /**
+   * WireAPI
+   */
+  PublishWire(request, callback) {
+    const grpcClient = this.getVoltAPIClient();
+
+    const publishCall = new GRPCCall(this, "PublishWire", "METHOD_TYPE_CLIENT_STREAM");
+    return publishCall.start(grpcClient, request, callback);
+  }
+
+  SubscribeWire(request, callback) {
+    const grpcClient = this.getVoltAPIClient();
+
+    const subscribeCall = new GRPCCall(this, "SubscribeWire", "METHOD_TYPE_BIDI");
+    return subscribeCall.start(grpcClient, request, callback);
+  }
+}
+
+Object.defineProperty(exports, 'generateId', {
+  enumerable: true,
+  get: function () { return uuid.v4; }
+});
+exports.VoltClient = VoltClient;
+exports.VoltCrypto = VoltCrypto;
+exports.constants = constants;
+exports.grpcUtils = grpcUtils;
+exports.protoUtils = protoUtils;
+exports.utils = utils;