@tdxvolt/volt-client-grpc 0.17.0 → 0.18.1

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.17.0",
+  "version": "0.18.1",
   "description": "tdx Volt library for nodejs clients",
   "type": "module",
   "exports": {
@@ -37,7 +37,7 @@
   "license": "ISC",
   "dependencies": {
     "@grpc/proto-loader": "^0.6.4",
-    "@tdxvolt/volt-client-web": "^0.17.106",
+    "@tdxvolt/volt-client-web": "^0.18.1",
     "bent": "^7.3.12",
     "builtin-modules": "^3.3.0",
     "debug": "^4.1.1",

package/protobuf/tdx/volt_api/volt/v1/ssi_api.proto

@@ -2,18 +2,19 @@ syntax = "proto3";
 
 package tdx.volt_api.volt.v1;
 
-import "tdx/volt_api/volt/v1/ssi.proto";
 import "tdx/volt_api/volt/v1/status.proto";
+import "tdx/volt_api/volt/v1/ssi.proto";
 
 service SsiAPI {
   // Delete a DID document or all DID documents originating from a given Volt.
-  // Requires 'volt:delete-did' API privilege.
+  // Requires `volt:delete-did` API privilege.
   rpc DeleteDID(DeleteDIDRequest) returns (DeleteDIDResponse);
 
   // Get all updates to the DID registry since the specified timestamp.
   // Internal use only.
   rpc GetDIDRegistryUpdates(GetDIDRegistryUpdatesRequest) returns (GetDIDRegistryUpdatesResponse);
 
+  // Import a verifiable credential.
   rpc ImportCredential(ImportCredentialRequest) returns (ImportCredentialResponse);
 
   // Parse a verifiable credential from a URL or a verifiable presentation.
@@ -23,8 +24,8 @@ service SsiAPI {
   rpc ResolveDID(ResolveDIDRequest) returns (ResolveDIDResponse);
 
   // Register a DID document.
-  // This is currently reserved for use by the DID registry when synchronising with other registries.
-  // To register a new DID document, use the VoltAPI Authenticate method.
+  // This is intended for use by the DID registry when synchronising with other registries.
+  // To register a new DID document, it is recommended to use the VoltAPI Authenticate method.
   rpc RegisterDIDDocument(RegisterDIDDocumentRequest) returns (RegisterDIDDocumentResponse);
 
   // Save a verifiable credential.
@@ -153,7 +154,6 @@ message RegisterDIDDocumentRequest {
   DIDRegistryUpdate did_update = 2;
 
   // When updating an existing DID document, it is necessary to include a signature of the document JSON, signed by the DID document's current owner.
-  // This is different from the proof contained in the DID document itself.
   string update_signature = 3;
 }
 

package/protobuf/tdx/volt_api/volt/v1/volt.proto

@@ -309,12 +309,17 @@ message VoltEndpoint {
   // The online status of the Volt.
   OnlineStatus online_status = 11;
 
-  // Set to indicate that this Volt acts as a Relay.
+  // Indicates that this Volt acts as a Relay.
   bool has_relay = 12;
 
+  // The API version supported by the endpoint.
   Version api_version = 13;
 
+  // Optional description of the endpoint.
   string description = 14;
+
+  // The list of DID registries that this Volt trusts.
+  repeated string did_registry = 15;
 }
 
 // Internal use only.

package/protobuf/tdx/volt_api/volt/v1/volt_api.proto

@@ -306,6 +306,9 @@ message ConnectHello {
 
   // The current time on the client.
   uint64 timestamp = 15;
+
+  // Optionally specify the DID registries supported.
+  repeated string did_registry = 16;
 }
 
 message ConnectAcknowledge {

package/protobuf/tdx/volt_api/volt/v1/wire_api.proto

@@ -22,6 +22,10 @@ message PublishWireRequest {
 
   // The chunk of data to publish.
   bytes chunk = 2;
+
+  // Whether to persist the chunk.
+  // This is only valid if the wire is configured to persist messages, i.e. the `volt:wire-persist` attribute is true.
+  bool do_not_persist = 3;
 }
 
 message PublishWireResponse {

package/src/constants.js

@@ -1,57 +1,10 @@
-// eslint-disable-next-line import/prefer-default-export
 export const constants = {
   authTokenName: "volt-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: "tdxvolt.com",
+  defaultDIDHostName: "coreid.com",
   didServiceType: {
     voltConfig: "volt-discovery"
   },
-  identityType: {
-    did: "did",
-    volt: "volt"
-  },
-  onlineStatus: {
-    offline: "offline",
-    online: "online",
-    unknown: "unknown"
-  },
   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.
@@ -64,10 +17,5 @@ export const constants = {
     relayAPI: "tdx.volt_api.relay.v1.RelayAPI",
     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`.
+  }
 };

package/src/grpc-call.js

@@ -1,7 +1,9 @@
 /* eslint-disable no-underscore-dangle */
 import debug from "debug";
 import EventEmitter from "events";
-import {
+import { voltUtils as voltClientUtils } from "@tdxvolt/volt-client-web/js";
+
+const {
   aesCreateKey,
   aesEncrypt,
   aesDecrypt,
@@ -11,7 +13,9 @@ import {
   verify,
   deriveSharedKey,
   x25519
-} from "@tdxvolt/volt-client-web";
+} = voltClientUtils;
+
+const invokeMethod = "Invoke";
 
 const log = debug("volt-client-grpc:grpc-call");
 
@@ -24,10 +28,10 @@ function _prepareInvokeRequest(
     this._service?.service_description.host_type ===
     "SERVICE_HOST_TYPE_RELAYED";
 
-  const relaying = this._voltClient.isVoltRelay || isServiceRelayed;
+  const relaying = this._voltClient.isRelayed || isServiceRelayed;
 
   let targetDID = [];
-  if (this._voltClient.isVoltRelay) {
+  if (this._voltClient.isRelayed) {
     targetDID.push(this._voltClient.voltConfig.id);
   }
 
@@ -52,20 +56,23 @@ function _prepareInvokeRequest(
   let invokeRequest;
   let callMethod = method;
 
+  const voltGrpcClient = this._voltClient.getVoltAPIClient();
+
   if (relaying) {
     //
     // If the volt connection is via a relay (or the target service is relayed),
     // we wrap the rpc in a RemoteRequest message and send it via a call to Invoke().
     //
+
     // Replace the target method with a call to Invoke on the relay Volt.
-    //
-    callMethod = "Invoke";
+    callMethod = invokeMethod;
 
     // But first we need to perform a key exchange with the target service.
-    //
     if (!this._encryptionKey) {
       // We haven't exchanged keys yet, so queue the payload.
-      this._pendingRequests.push(request);
+      if (request) {
+        this._pendingRequests.push(request);
+      }
 
       if (this._keyExchangePending) {
         // We've already sent the key exchange request, so do nothing.
@@ -84,6 +91,13 @@ function _prepareInvokeRequest(
           : undefined
       };
 
+      if (this._voltClient.isRelayed) {
+        // When tunnelling, we serialise the request using the original serialisation
+        // method for Invoke.
+        invokeRequest =
+          voltGrpcClient.Invoke.requestSerializeOriginal(invokeRequest);
+      }
+
       return {
         request: invokeRequest,
         method: callMethod,
@@ -94,41 +108,45 @@ function _prepareInvokeRequest(
 
     let requestPayload;
 
-    // Serialise the rpc request.
+    // Serialise the rpc request using the original serialisation method.
     if (request) {
-      requestPayload = this._grpcClient[method].requestSerialize(request);
+      if (this._voltClient.isRelayed) {
+        requestPayload =
+          this._grpcClient[method].requestSerializeOriginal(request);
+      } else {
+        requestPayload = this._grpcClient[method].requestSerialize(request);
+      }
     } else if (request !== null) {
       log("****************LOOKOUT****************** - empty request");
     } else {
       log("explicit empty request payload");
     }
 
-    // Use this placeholder to serialise the relay request wrapper.
-    const voltGrpcClient = this._voltClient.getVoltAPIClient();
-    const tunnelMethod = voltGrpcClient.Tunnel;
-
-    const tunnelResp = {
+    // Create a tunnel message containing the method call metadata and request payload.
+    const tunnelResp = voltGrpcClient.Tunnel.responseSerialize({
       method_invoke: {
         method_name: this._grpcClient[method].path,
         method_type: methodType,
         request: requestPayload
       }
-    };
-
-    let invokePayload;
-    const iv = aesCreateKey().iv;
+    });
 
     // When sending via a relay we need to encrypt the payload.
-    invokePayload = aesEncrypt(
-      this._encryptionKey,
-      iv,
-      tunnelMethod.responseSerialize(tunnelResp)
-    );
+    const iv = aesCreateKey().iv;
+    const invokePayload = aesEncrypt(this._encryptionKey, iv, tunnelResp);
 
+    // Construct the Invoke request.
     invokeRequest = {
       iv,
       payload: invokePayload
     };
+
+    if (this._voltClient.isRelayed) {
+      // When tunnelling, we serialise the request using the original serialisation
+      // method for Invoke.
+      invokeRequest =
+        voltGrpcClient.Invoke.requestSerializeOriginal(invokeRequest);
+    }
   } else {
     invokeRequest = request;
   }
@@ -148,32 +166,45 @@ function _preparePayloadRequest(request, invokeInfo) {
     this._service?.service_description.host_type ===
     "SERVICE_HOST_TYPE_RELAYED";
 
-  let iv;
-  if (this._voltClient.isVoltRelay || isServiceRelayed) {
-    iv = aesCreateKey().iv;
-
-    const requestPayload =
-      this._grpcClient[invokeInfo.methodName].requestSerialize(request);
+  if (this._voltClient.isRelayed || isServiceRelayed) {
+    let requestPayload;
+    if (this._voltClient.isRelayed) {
+      // Serialise the rpc request using the original serialisation method.
+      requestPayload =
+        this._grpcClient[invokeInfo.methodName].requestSerializeOriginal(
+          request
+        );
+    } else {
+      requestPayload =
+        this._grpcClient[invokeInfo.methodName].requestSerialize(request);
+    }
 
+    // Use the Tunnel method to serialise the relay request wrapper, this
     const voltGrpcClient = this._voltClient.getVoltAPIClient();
-    const tunnelMethod = voltGrpcClient.Tunnel;
 
-    const tunnelResp = {
+    // Create a tunnel message containing the method call metadata and request payload.
+    const tunnelResp = voltGrpcClient.Tunnel.responseSerialize({
       method_payload: {
         payload: requestPayload
       }
-    };
+    });
 
-    const invokePayload = aesEncrypt(
-      this._encryptionKey,
-      iv,
-      tunnelMethod.responseSerialize(tunnelResp)
-    );
+    // Encrypt the payload using the shared key.
+    const iv = aesCreateKey().iv;
+    const invokePayload = aesEncrypt(this._encryptionKey, iv, tunnelResp);
 
+    // We then serialise the entire request using the original serialisation method for Invoke.
     payloadRequest = {
       iv,
       payload: invokePayload
     };
+
+    if (this._voltClient.isRelayed) {
+      // When tunnelling, we serialise the request using the original serialisation
+      // method for Invoke.
+      payloadRequest =
+        voltGrpcClient.Invoke.requestSerializeOriginal(payloadRequest);
+    }
   } else {
     payloadRequest = request;
   }
@@ -189,7 +220,14 @@ function _parseResponse(method, meta, response) {
     this._service?.service_description.host_type ===
     "SERVICE_HOST_TYPE_RELAYED";
 
-  if (this._voltClient.isVoltRelay || isServiceRelayed) {
+  const voltGrpcClient = this._voltClient.getVoltAPIClient();
+
+  if (this._voltClient.isRelayed || isServiceRelayed) {
+    if (this._voltClient.isRelayed) {
+      // Deserialise the incoming response using the original deserialisation method for Invoke.
+      response = voltGrpcClient.Invoke.responseDeserializeOriginal(response);
+    }
+
     if (response.key_exchange) {
       const encryptionKey = response.key_exchange.encryption_key;
       const nonce = response.key_exchange.nonce;
@@ -227,13 +265,24 @@ function _parseResponse(method, meta, response) {
         decryptedPayload = response.payload;
       }
 
-      const tunnelMethod = this._voltClient.getVoltAPIClient().Tunnel;
-      const responsePayload = tunnelMethod.requestDeserialize(decryptedPayload);
+      // Deserialise the decrypted payload using the Tunnel deserialisation method.
+      const responsePayload =
+        voltGrpcClient.Tunnel.requestDeserialize(decryptedPayload);
       if (responsePayload.payload === "method_payload") {
         try {
-          invokeResponse.payload = this._grpcClient[method].responseDeserialize(
-            responsePayload.method_payload.payload
-          );
+          // Deserialise the method payload.
+          if (this._voltClient.isRelayed) {
+            // Use the original deserialisation method for the target method.
+            invokeResponse.payload = this._grpcClient[
+              method
+            ].responseDeserializeOriginal(
+              responsePayload.method_payload.payload
+            );
+          } else {
+            invokeResponse.payload = this._grpcClient[
+              method
+            ].responseDeserialize(responsePayload.method_payload.payload);
+          }
         } catch (err) {
           log("failure deserialising payload for %s", this._methodName);
           throw new Error(
@@ -261,16 +310,6 @@ function _parseResponse(method, meta, response) {
       invokeResponse.methodId = response.invoke_id;
       log("started method %d for %s", invokeResponse.methodId, method);
     }
-  } else if (this._voltClient.isRemote && this._encryptionKey) {
-    const decryptedPayload = aesDecrypt(
-      this._encryptionKey,
-      meta.sharedKey.iv,
-      response
-    );
-    invokeResponse = {
-      payload:
-        this._grpcClient[method].responseDeserializeOriginal(decryptedPayload)
-    };
   } else {
     invokeResponse = { payload: response };
   }
@@ -310,7 +349,7 @@ export default class GRPCCall extends EventEmitter {
       "SERVICE_HOST_TYPE_RELAYED";
 
     let callClient;
-    if (this._voltClient.isVoltRelay || isServiceRelayed) {
+    if (this._voltClient.isRelayed || isServiceRelayed) {
       callClient = this._voltClient.getVoltAPIClient();
     } else {
       callClient = this._grpcClient;
@@ -377,7 +416,11 @@ export default class GRPCCall extends EventEmitter {
     });
 
     this._call.on("error", (err) => {
-      log("ERROR - intercepted stream error %s", err.message);
+      log(
+        "ERROR - intercepted stream error on %s: %s",
+        this._methodName,
+        err.message
+      );
       this.emit("error", err);
     });
 
@@ -413,6 +456,16 @@ export default class GRPCCall extends EventEmitter {
     }
   }
 
+  pause() {
+    log("pausing call %s", this._methodName);
+    return this._call?.pause();
+  }
+
+  resume() {
+    log("resuming call %s", this._methodName);
+    return this._call?.resume();
+  }
+
   get writable() {
     return this._call?.writable;
   }

package/src/grpc-utils.js

@@ -20,7 +20,7 @@ export function createClient(
 ) {
   let grpcCredentials;
   if (credentials) {
-    const relaying = !!credentials.config?.volt?.relay;
+    const relaying = !!credentials.config?.volt?.relay && !Array.isArray(credentials.config?.volt?.relay);
     const ca = relaying
       ? credentials.config?.volt?.relay?.ca_pem
       : credentials.cache.ca;
@@ -28,8 +28,8 @@ export function createClient(
     const { key } = credentials.cache;
 
     if (key && cert) {
-      const cryyptoOptions = { ca, cert, key };
-      const tlsOptions = createSecureContextOptions(cryyptoOptions);
+      const cryptoOptions = { ca, cert, key };
+      const tlsOptions = createSecureContextOptions(cryptoOptions);
       grpcCredentials = grpc.credentials.createSsl(
         tlsOptions.ca,
         tlsOptions.key,

package/src/rpc-invocation.js

@@ -1,7 +1,9 @@
 import debug from "debug";
 import jwt from "jsonwebtoken";
 import EventEmitter from "events";
-import {
+import { voltUtils as voltClientUtils } from "@tdxvolt/volt-client-web/js";
+
+const {
   aesDecrypt,
   aesEncrypt,
   createEncryptionKey,
@@ -13,23 +15,26 @@ import {
   publicKeyToPem,
   randomBytes,
   signBase64,
-  stripPEMHeaders,
+  stripPemHeaders,
   x25519
-} from "@tdxvolt/volt-client-web";
+} = voltClientUtils;
 
-const log = debug("rpc-invocation");
+const log = debug("volt-client-grpc:rpc-invocation");
 
 class RpcInvocation extends EventEmitter {
   #voltClient = null;
   #voltConnection = null;
   #token = null;
+  #callerPublicKeyPem = null;
   #invokeId = null;
+  #serviceId = null;
   #payload = null;
   #isJSON = false;
   #methodDescriptor = null;
   #methodName = null;
   #derivedKey = null;
   #started = false;
+  #endEmitted = false;
 
   constructor(voltClient, voltConnection) {
     super();
@@ -41,6 +46,18 @@ class RpcInvocation extends EventEmitter {
     return this.#invokeId;
   }
 
+  get serviceId() {
+    return this.#serviceId;
+  }
+
+  get token() {
+    return this.#token;
+  }
+
+  get callerPublicKeyPem() {
+    return this.#callerPublicKeyPem;
+  }
+
   get payload() {
     if (!this.#payload) {
       return null;
@@ -82,14 +99,23 @@ class RpcInvocation extends EventEmitter {
     // The rpc implementation should do the verification using the Volt API (e.g. CanAccessResource).
     this.#token = jwt.decode(token);
 
+    if (!this.#token) {
+      log("failed to decode token %s", token || "null");
+      return Promise.reject(new Error("failed to decode token"));
+    }
+
     // Store the JWT key id (kid) for use in the response.
-    const callerPublicKeyPem = formatPEM(this.#token.k, "PUBLIC KEY");
-    const callerKey = keyFromPem(callerPublicKeyPem, "", x25519).publicKey;
+    this.#callerPublicKeyPem = formatPEM(this.#token.k, "PUBLIC KEY");
+    const callerKey = keyFromPem(
+      this.#callerPublicKeyPem,
+      "",
+      x25519
+    ).publicKey;
 
     const ephemeralKeyPem = createEncryptionKey();
     const ephemeralKey = keyFromPem(ephemeralKeyPem, "", x25519);
     const ephemeralPublicKey = fromBase64(
-      stripPEMHeaders(publicKeyToPem(ephemeralKey.publicKey, x25519))
+      stripPemHeaders(publicKeyToPem(ephemeralKey.publicKey, x25519))
     );
 
     this.#derivedKey = deriveSharedKey(
@@ -106,7 +132,7 @@ class RpcInvocation extends EventEmitter {
     message.set(nonce, ephemeralPublicKey.length);
 
     const signature = signBase64(
-      this.#voltClient.credential.getKey().privateKey,
+      this.#voltClient.credential.cache.key,
       message
     );
 
@@ -127,7 +153,10 @@ class RpcInvocation extends EventEmitter {
   }
 
   initialise(invoke_request) {
-    this.#invokeId = invoke_request.invoke_id;
+    if (!this.#invokeId) {
+      this.#invokeId = invoke_request.invoke_id;
+      this.#serviceId = invoke_request.target_service_id;
+    }
 
     if (!this.#derivedKey) {
       // We don't have the derived key yet, so we need to perform the key exchange.
@@ -149,8 +178,7 @@ class RpcInvocation extends EventEmitter {
 
       if (invoke_request.payload) {
         let decryptedPayload;
-
-        if (encryptIV) {
+        if (encryptIV?.length) {
           // Decrypt the actual payload using the shared key and iv.
           decryptedPayload = aesDecrypt(
             this.#derivedKey,
@@ -218,8 +246,13 @@ class RpcInvocation extends EventEmitter {
             );
             this.emit("payload", this);
           } else if (wrappedPayload.method_end) {
-            // We don't need to do anything here, since we notify the client when we receive the client_end.
             log("method_end received");
+            if (!this.#endEmitted) {
+              this.#endEmitted = true;
+              this.emit("end", this);
+            } else {
+              log("method_end: end already emitted");
+            }
           }
         } catch (err) {
           log("JSON.parse failure parsing json_payload: %s", err.message);
@@ -228,7 +261,12 @@ class RpcInvocation extends EventEmitter {
 
         resolve();
       } else if (invoke_request.client_end) {
-        this.emit("end", this);
+        if (!this.#endEmitted) {
+          this.#endEmitted = true;
+          this.emit("end", this);
+        } else {
+          log("client_end: end already emitted");
+        }
       } else {
         // Do we need to support json_payload here?
         reject(new Error("No payload in invoke request"));

package/src/utils.js

@@ -1,6 +1,6 @@
 import ip from "ip";
 import _ from "lodash";
-export * as crypto from "@tdxvolt/volt-client-web";
+export { voltUtils as crypto } from "@tdxvolt/volt-client-web/js";
 
 import { constants } from "./constants.js";