@tdxvolt/volt-client-grpc 0.15.0 → 0.16.0-beta.1

package/src/constants.js

@@ -4,37 +4,37 @@ export const constants = {
   collectionOperation: {
     add: "ADD",
     remove: "REMOVE",
-    update: "UPDATE",
+    update: "UPDATE"
   },
   crypto: {
     subjectDefaults: [
       {
         name: "countryName",
-        value: "GB",
+        value: "GB"
       },
       {
         name: "localityName",
-        value: "Southampton",
+        value: "Southampton"
       },
       {
         name: "organizationName",
-        value: "nquiringminds Ltd",
-      },
+        value: "nquiringminds Ltd"
+      }
     ],
-    userIdOID: "0.9.2342.19200300.100.1.1",
+    userIdOID: "0.9.2342.19200300.100.1.1"
   },
   defaultDIDHostName: "cloud.tdxvolt.com",
   didServiceType: {
-    voltConfig: "tdx-volt-config",
+    voltConfig: "tdx-volt-config"
   },
   identityType: {
     did: "did",
-    volt: "volt",
+    volt: "volt"
   },
   onlineStatus: {
     offline: "offline",
     online: "online",
-    unknown: "unknown",
+    unknown: "unknown"
   },
   publicKeyPrefix: "-----BEGIN PUBLIC KEY-----",
   privateKeyPrefix: "-----BEGIN RSA PRIVATE KEY-----",
@@ -45,14 +45,14 @@ export const constants = {
     proxy: "proxy",
     proxyView: "proxy-view",
     vc: "vc",
-    vcView: "vc-view",
+    vcView: "vc-view"
   },
   voltStatus: {
     pending: "",
     online: "online",
     offline: "offline",
     deleted: "deleted",
-    revoked: "revoked",
+    revoked: "revoked"
   },
   /**
    * These top-level service types should map to a protobuf definition
@@ -62,14 +62,14 @@ export const constants = {
     fileAPI: "tdx.volt_api.volt.v1.FileAPI",
     sqliteServerAPI: "tdx.volt_api.data.v1.SqliteServerAPI",
     sqliteDatabaseAPI: "tdx.volt_api.data.v1.SqliteDatabaseAPI",
-    ssiAPI: "tdx.volt_api.ssi.v1.SsiAPI",
+    ssiAPI: "tdx.volt_api.volt.v1.SsiAPI",
     relayAPI: "tdx.volt_api.relay.v1.RelayAPI",
     voltAPI: "tdx.volt_api.volt.v1.VoltAPI",
-    wireAPI: "tdx.volt_api.volt.v1.WireAPI",
+    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`.
+  tunnelTimeoutInterval: 10000 * 2 // This must always be greater than `tunnelPingInterval`.
 };

package/src/grpc-call.js

@@ -8,7 +8,7 @@ const log = debug("volt-client-grpc:grpc-call");
 function _prepareInvokeRequest(
   request,
   method,
-  methodType = "METHOD_TYPE_UNARY",
+  methodType = "METHOD_TYPE_UNARY"
 ) {
   const isServiceRelayed =
     this._service?.service_description.host_type ===
@@ -21,7 +21,7 @@ function _prepareInvokeRequest(
       this._voltClient.voltConfig.id,
     this._service?.service_description.host_public_key ||
       this._voltClient.credential.voltPublicKey,
-    true,
+    true
   );
 
   let invokeRequest;
@@ -52,42 +52,40 @@ function _prepareInvokeRequest(
         method_name: this._grpcClient[method].path,
         method_type: methodType,
         token: methodToken.token,
-        request: requestPayload,
-      },
+        request: requestPayload
+      }
     };
 
-    let targetFingerprint = [];
+    let targetDID = [];
     let invokePayload;
     if (this._voltClient.isVoltRelay || isServiceRelayed) {
       // When sending via a relay we need to encrypt the payload.
       invokePayload = VoltCredential.aesEncrypt(
         tunnelMethod.responseSerialize(tunnelResp),
         methodToken.sharedKey.key,
-        methodToken.sharedKey.iv,
+        methodToken.sharedKey.iv
       );
     } else {
       invokePayload = tunnelMethod.responseSerialize(tunnelResp);
     }
 
     if (this._voltClient.isVoltRelay) {
-      targetFingerprint.push(this._voltClient.credential.voltFingerprint);
+      targetDID.push(this._voltClient.voltConfig.id);
     }
 
     if (isServiceRelayed) {
       // Add another relay hop if the target service is relayed.
       log("target service is relayed");
-      targetFingerprint.push(
-        this._service.service_description.host_fingerprint,
-      );
+      targetDID.push(this._service.service_description.host_client_id);
     }
 
-    log("target is %j", targetFingerprint);
+    log("target is %j", targetDID);
 
     invokeRequest = {
-      target_fingerprint: targetFingerprint,
+      target_did: targetDID,
       token: methodToken.token,
       payload: invokePayload,
-      target_service_id: isServiceRelayed ? this._service.id : undefined,
+      target_service_id: isServiceRelayed ? this._service.id : undefined
     };
 
     // Replace the target method with a call to Invoke on the relay Volt.
@@ -100,7 +98,7 @@ function _prepareInvokeRequest(
     meta: methodToken,
     method: callMethod,
     methodName: method,
-    request: invokeRequest,
+    request: invokeRequest
   };
 }
 
@@ -120,18 +118,18 @@ function _preparePayloadRequest(request, invokeInfo) {
 
     const tunnelResp = {
       method_payload: {
-        payload: requestPayload,
-      },
+        payload: requestPayload
+      }
     };
 
     const invokePayload = VoltCredential.aesEncrypt(
       tunnelMethod.responseSerialize(tunnelResp),
       invokeInfo.meta.sharedKey.key,
-      invokeInfo.meta.sharedKey.iv,
+      invokeInfo.meta.sharedKey.iv
     );
 
     payloadRequest = {
-      payload: invokePayload,
+      payload: invokePayload
     };
   } else {
     payloadRequest = request;
@@ -155,7 +153,7 @@ function _parseResponse(method, meta, response) {
         decryptedPayload = VoltCredential.aesDecrypt(
           response.payload,
           meta.sharedKey.key,
-          meta.sharedKey.iv,
+          meta.sharedKey.iv
         );
       } else {
         decryptedPayload = response.payload;
@@ -166,12 +164,12 @@ function _parseResponse(method, meta, response) {
       if (responsePayload.payload === "method_payload") {
         try {
           invokeResponse.payload = this._grpcClient[method].responseDeserialize(
-            responsePayload.method_payload.payload,
+            responsePayload.method_payload.payload
           );
         } catch (err) {
           log("failure deserialising payload for %s", this._methodName);
           throw new Error(
-            "failure deserialising payload - check protobuf definition matches with data being sent",
+            "failure deserialising payload - check protobuf definition matches with data being sent"
           );
         }
       } else if (responsePayload.payload === "method_end") {
@@ -185,11 +183,11 @@ function _parseResponse(method, meta, response) {
         "Tunnel status received: %s, code %d, description: %s",
         response.status.message,
         response.status.code,
-        response.status.description || "n/a",
+        response.status.description || "n/a"
       );
       invokeResponse = {
         ended: true,
-        error: `Error in tunnel: ${response.status.message}`,
+        error: `Error in tunnel: ${response.status.message}`
       };
     } else {
       invokeResponse.methodId = response.invoke_id;
@@ -199,11 +197,11 @@ function _parseResponse(method, meta, response) {
     const decryptedPayload = VoltCredential.aesDecrypt(
       response,
       meta.sharedKey.key,
-      meta.sharedKey.iv,
+      meta.sharedKey.iv
     );
     invokeResponse = {
       payload:
-        this._grpcClient[method].responseDeserializeOriginal(decryptedPayload),
+        this._grpcClient[method].responseDeserializeOriginal(decryptedPayload)
     };
   } else {
     invokeResponse = { payload: response };
@@ -233,7 +231,7 @@ export default class GRPCCall extends EventEmitter {
       this,
       request,
       this._methodName,
-      this._methodType,
+      this._methodType
     );
 
     const isServiceRelayed =
@@ -248,7 +246,7 @@ export default class GRPCCall extends EventEmitter {
     }
 
     this._call = callClient[this._initialRequest.method](
-      this._initialRequest.meta.metadata,
+      this._initialRequest.meta.metadata
     );
 
     this._call.on("data", (streamResponse) => {
@@ -257,14 +255,14 @@ export default class GRPCCall extends EventEmitter {
           this,
           this._methodName,
           this._initialRequest.meta,
-          streamResponse,
+          streamResponse
         );
         if (parsedResponse.payload) {
           // Interpret a non-empty status message as an error.
           if (parsedResponse.payload?.status?.message) {
             this.emit(
               "error",
-              new Error(parsedResponse.payload.status.message),
+              new Error(parsedResponse.payload.status.message)
             );
           } else {
             this.emit("data", parsedResponse.payload);
@@ -283,7 +281,7 @@ export default class GRPCCall extends EventEmitter {
         log(
           "failure processing %s call response: %s",
           this._methodName,
-          err.message,
+          err.message
         );
         this.emit("error", err);
       }
@@ -305,7 +303,7 @@ export default class GRPCCall extends EventEmitter {
       log(
         "ended call %s, method id: %s",
         this._methodName,
-        this._initialRequest.methodId || "n/a - not tunnelling",
+        this._initialRequest.methodId || "n/a - not tunnelling"
       );
       this.emit("end");
     });
@@ -338,7 +336,7 @@ export default class GRPCCall extends EventEmitter {
       const payloadRequest = _preparePayloadRequest.call(
         this,
         request,
-        this._initialRequest,
+        this._initialRequest
       );
       return this._call.write(payloadRequest);
     } else {
@@ -346,7 +344,7 @@ export default class GRPCCall extends EventEmitter {
         this,
         request,
         this._methodName,
-        this._methodType,
+        this._methodType
       );
 
       return this._call.write(this._initialRequest.request);

package/src/utils.js

@@ -64,11 +64,16 @@ export const createPublicKeyFingerprint = (key) => {
   return createBase58Hash(removeCarriageReturn(key));
 };
 
+export const base64ToBase64Url = (base64) => {
+  return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+};
+
 export const signBase64 = (key, msg) => {
   const md = forge.md.sha256.create();
   md.update(msg);
   const signature = key.sign(md);
-  return forge.util.encode64(signature);
+  const base64Standard = forge.util.encode64(signature);
+  return base64ToBase64Url(base64Standard);
 };
 
 export const verifyBase64 = (key, msg, signature) => {
@@ -137,10 +142,25 @@ export const createRSAKey = (passphrase = "") => {
 export const sha256Base64 = (msg) => {
   const md = forge.md.sha256.create();
   md.update(msg);
-  return forge.util.encode64(md.digest().bytes());
+  const base64Standard = forge.util.encode64(md.digest().bytes());
+  return base64ToBase64Url(base64Standard);
 };
 
 export const decryptPrivateKey = (pem, passphrase) => {
   const decryptedKey = pki.decryptRsaPrivateKey(pem, passphrase);
   return forgePrivateKeyToPem(decryptedKey);
 };
+
+export const jwsSignature = (signature) => {
+  //
+  // Use an unattached payload JWS signature for the DID document proof.
+  // This is a JWS with an empty payload and a detached payload digest.
+  //
+  // (https://tools.ietf.org/html/rfc7797#appendix-F) as used in the VC spec
+  // (https://www.w3.org/TR/vc-data-model/).
+  //
+  const jwsHeader = base64ToBase64Url(
+    forge.util.encode64('{"alg":"RS256","b64": false}')
+  );
+  return jwsHeader + ".." + signature;
+};

package/src/volt-client-internal.js

@@ -16,6 +16,7 @@ import * as voltUtils from "./utils.js";
 import { constants } from "./constants.js";
 import GRPCCall from "./grpc-call.js";
 import RpcInvocation from "./rpc-invocation.js";
+import { v4 as generateId } from "uuid";
 
 const { pki } = forge;
 const { filter, pick } = lodash;
@@ -31,6 +32,55 @@ const voltServices = [
   constants.serviceType.wireAPI
 ];
 
+function issueAuthenticate(authenticateRequest, ttl) {
+  // eslint-disable-next-line no-use-before-define
+  return unaryCallInternal
+    .call(this, "Authenticate", authenticateRequest)
+    .then((authenticateResponse) => {
+      log("got authenticate response %j", authenticateResponse);
+      if (authenticateResponse.status?.code) {
+        log("error in bind response: %s", authenticateResponse.status.message);
+        return Promise.reject(new Error(authenticateResponse.status.message));
+      } else {
+        switch (authenticateResponse.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._credential.cache.cert = authenticateResponse.cert;
+
+            // This is the signing CA used by the volt.
+            this._credential.cache.ca = authenticateResponse.chain;
+
+            // Identity resource id is assigned by the volt.
+            this._credential.cache.client_id = authenticateResponse.session_id;
+            this._credential.saveCache();
+            break;
+          }
+          case "POLICY_DECISION_DENY": {
+            log(">>>>>>>>>>>>>>> access request is DENIED <<<<<<<<<<<<<<<<<<<");
+            break;
+          }
+          case "POLICY_DECISION_PROMPT":
+          case "POLICY_DECISION_PENDING": {
+            log("access pending approval - waiting...");
+            break;
+          }
+          default:
+            log(
+              "ignoring unknown bind descision %s",
+              authenticateResponse.status
+            );
+            break;
+        }
+      }
+
+      return authenticateResponse.decision;
+    });
+}
+
 function issueBind(bindRequest, ttl) {
   // eslint-disable-next-line no-use-before-define
   return unaryCallInternal
@@ -86,7 +136,8 @@ function findDIDDocumentService(document, serviceType) {
   return matches;
 }
 
-export async function bindInternal() {
+
+export async function authenticateInternal() {
   try {
     // Check if we need to resolve a Relay volt.
     if (
@@ -100,6 +151,7 @@ export async function bindInternal() {
         this,
         `${relayURL}/discovery`
       );
+
       if (this._voltConfig.relay.ca_pem) {
         log(
           "Auto-fetched Relay CA %s, remote address %s",
@@ -133,19 +185,107 @@ export async function bindInternal() {
     this._credential.saveCache();
 
     // Form the request message.
-    const bindRequest = {
+    const authenticateRequest = {
       binding_name: this._config.client_name,
       public_key: publicKeyPem,
       host: this._credential.cache.bindIp,
-      x509_credential: []
     };
 
-    if (this._credential.cache.cert) {
-      bindRequest.x509_credential = [
-        this._credential.cache.cert + this._credential.cache.ca
-      ];
+    if (this._voltConfig.challenge_code) {
+      authenticateRequest.challenge = voltUtils.signBase64(
+        keyPair.privateKey,
+        this._voltConfig.challenge_code
+      );
+    } else {
+      log(
+        "****no Volt challenge code available**** => not sending challenge signature"
+      );
+    }
+
+    log("authenticate 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 issueAuthenticate.call(
+        this,
+        authenticateRequest,
+        this._voltConfig.bindRequestTTL
+      );
+      log("authenticate decision: %s", decision);
+    } while (
+      decision === "POLICY_DECISION_PROMPT" ||
+      decision === "POLICY_DECISION_PENDING"
+    );
+
+    return decision === "POLICY_DECISION_PERMIT";
+  } catch (err) {
+    log("failure binding to Volt [%s]", err.message);
+    throw err;
+  }
+}
+
+export async function bindInternal() {
+  try {
+    // Check if we need to resolve a Relay volt.
+    if (
+      typeof this._voltConfig?.relay === "string" ||
+      this._voltConfig?.relay?.http_address
+    ) {
+      const relayURL =
+        this._voltConfig.relay?.http_address || this._voltConfig.relay;
+      log("attempting to retrieve Relay information from %s", relayURL);
+      this._voltConfig.relay = await fetchVoltConfig.call(
+        this,
+        `${relayURL}/discovery`
+      );
+      if (this._voltConfig.relay.ca_pem) {
+        log(
+          "Auto-fetched Relay CA %s, remote address %s",
+          this._voltConfig.relay.ca_pem,
+          this._voltConfig.relay.address
+        );
+      } else {
+        throw new Error("Unable to fetch Relay CA - cannot securely connect.");
+      }
     }
 
+    if (!this._credential.cache.ca) {
+      this._credential.cache.ca = this._voltConfig.ca_pem;
+    }
+
+    if (!this._credential.cache.ca) {
+      throw new Error(
+        "No certificate authority found in configuration for target Volt - check configuration"
+      );
+    }
+
+    const keyPair = this._credential.getKey();
+    const publicKeyPem = voltUtils.removeCarriageReturn(
+      pki.publicKeyToPem(keyPair.publicKey)
+    );
+
+    if (!this._credential.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._credential.cache.bindIp = ip.address();
+    }
+
+    this._credential.saveCache();
+
+    // Form the request message.
+    const bindRequest = {
+      binding_name: this._config.client_name,
+      host: this._credential.cache.bindIp
+    };
+
     if (this._voltConfig.challenge_code) {
       bindRequest.challenge = voltUtils.signBase64(
         keyPair.privateKey,
@@ -157,14 +297,65 @@ export async function bindInternal() {
       );
     }
 
-    // For remote connections, add our cloud-issued certificate as an additional credential.
-    if (this._voltConfig?.relay?.ca_pem && this._credential.cache.cloud_cert) {
-      bindRequest.x509_credential = bindRequest.x509_credential.concat(
-        this._credential.cache.cloud_cert + this._voltConfig.relay.ca_pem
-      );
+    if (!this._credential.cache.client_id) {
+      // If we don't have a client id, then we need to create a DID.
+      this._credential.cache.client_id = `did:volt:${generateId()}`;
     }
 
-    log("sending %d x509 credentials", bindRequest.x509_credential.length);
+    const did = this._credential.cache.client_id;
+
+    // Order of properties in the DID document is important,
+    // they must be in alphabetical order throughout the document.
+    // This is because the DID document is signed and the signature
+    // is over the entire document.
+    const didDocument = {
+      "@context": "https://www.w3.org/ns/did/v1",
+      authentication: [`${did}#key-1`],
+      description: this._config.client_name,
+      id: did,
+      verificationMethod: [
+        {
+          controller: did,
+          id: `${did}#key-1`,
+          publicKeyPem: publicKeyPem,
+          type: "RsaSignature2018"
+        }
+      ]
+    };
+
+    const signDocument = JSON.stringify(didDocument, null, 2);
+    log("signing did document");
+    log(signDocument);
+
+    // Sign the DID document.
+    const documentDigest = voltUtils.signBase64(
+      keyPair.privateKey,
+      signDocument
+    );
+
+    const proofSignature = voltUtils.jwsSignature(documentDigest);
+
+    // Create the DID document proof.
+    didDocument.proof = {
+      created: new Date().toISOString(),
+      jws: proofSignature,
+      proofPurpose: "assertionMethod",
+      type: "RsaSignature2018",
+      verificationMethod: `${did}#key-1`
+    };
+
+    // Set the DID document with proof in the bind request.
+    bindRequest.did_document = JSON.stringify(didDocument, null, 2);
+
+    // Now sign the entire DID document, including the proof and set it in the
+    // bind request. This is required by the Volt to verify that we have the private key for the DID.
+    bindRequest.did_document_signature = voltUtils.signBase64(
+      keyPair.privateKey,
+      bindRequest.did_document
+    );
+
+    log("did document is %s", bindRequest.did_document);
+    log("did signature is %s", bindRequest.did_document_signature);
     log("bind TTL is ", this._config.bindRequestTTL);
 
     // This will block while the request is pending.
@@ -304,9 +495,6 @@ export function getVoltAPIClientInternal() {
 
 export function getAPIClientInternal(service) {
   if (!this._cachedService[service.id]) {
-    const isRelayedService =
-      service.service_description.host_type === "SERVICE_HOST_TYPE_RELAYED";
-
     const serviceAddress = this.isRemote
       ? this._voltConfig.relay.address
       : service.service_description.host_address;
@@ -354,9 +542,8 @@ export function getServiceClient(service) {
 }
 
 export function unaryCallInternal(method, request, service) {
-  const grpcClient = getServiceClient.call(this, service);
-
   return new Promise((resolve, reject) => {
+    const grpcClient = getServiceClient.call(this, service);
     const call = new GRPCCall(this, method, "METHOD_TYPE_UNARY", service);
 
     let response = null;

package/src/volt-client.js

@@ -5,6 +5,7 @@ import path from "path";
 import { getServiceDescriptors } from "./proto-utils.js";
 import { createClient as createGrpcClient } from "./grpc-utils.js";
 import {
+  authenticateInternal,
   bindInternal,
   connectInternal,
   fetchVoltConfig,
@@ -166,14 +167,14 @@ export class VoltClient extends EventEmitter {
       if (this._credential._cryptoCache.cert) {
         isBound = true;
       } else {
-        // No certificate present in the cache yet => we need to bind.
+        // No certificate present in the cache yet => we need to authenticate.
         try {
-          isBound = await bindInternal.call(this);
+          isBound = await authenticateInternal.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?"
+              "failure authenticating on Volt - did you supply a challenge code or verified credential?"
             );
             throw bindErr;
           }
@@ -182,7 +183,7 @@ export class VoltClient extends EventEmitter {
 
       if (!isBound) {
         // This is usually because of request being denied.
-        throw new Error("Volt binding failed");
+        throw new Error("Volt authentication failed");
       }
 
       return Promise.resolve();
@@ -408,6 +409,10 @@ export class VoltClient extends EventEmitter {
    * VoltAPI - volt management
    */
 
+  Authenticate(request) {
+    return unaryCallInternal.call(this, "Authenticate", request);
+  }
+
   Bind(request) {
     return unaryCallInternal.call(this, "Bind", request);
   }
@@ -569,6 +574,13 @@ export class VoltClient extends EventEmitter {
     });
   }
 
+  /**
+   * SqliteServerAPI
+   */
+  CreateDatabase(request) {
+    return unaryCallInternal.call(this, "CreateDatabase", request);
+  }
+
   /**
    * SqliteDatabaseAPI
    */