@tdxvolt/volt-client-grpc 0.14.60 → 0.14.134

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.14.60",
+  "version": "0.14.134",
   "description": "tdx Volt library for nodejs clients",
   "type": "module",
   "exports": {

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

@@ -8,7 +8,7 @@ import "tdx/volt_api/volt/v1/file.proto";
 // The File API exposes basic file management functions.
 service FileAPI {
 
-  // A server-stream to download contents from a file resource.
+  // Download from file resource.
   rpc DownloadFile(DownloadFileRequest) returns (stream DownloadFileResponse);
 
   // Get file resource metadata.

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

@@ -787,8 +787,10 @@ message InvokeRequest {
   // Indicates the client has ended the invocation.
   bool client_end = 6;
 
+  // Reserved for internal use.
   uint32 hop_index = 7;
 
+  // Reserved for internal use.
   string target_service_id = 8;
 }
 

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

@@ -6,7 +6,7 @@ import "tdx/volt_api/volt/v1/status.proto";
 
 // The Wire API allows clients to subscribe and publish to Volt wire resources.
 service WireAPI {
-  // Establishes a bi-directional streaming call to the wire resource.
+  // Establishes a client-streaming call to the wire resource.
   rpc PublishWire(stream PublishWireRequest) returns (stream PublishWireResponse);
 
   // Establishes a bi-directional streaming call to the wire resource.

package/src/grpc-call.js

@@ -10,16 +10,31 @@ function _prepareInvokeRequest(
   method,
   methodType = "METHOD_TYPE_UNARY",
 ) {
-  const meta = this._voltClient.credential.getIdentityMetadata(
+  const isServiceRelayed =
+    this._service?.service_description.host_type ===
+    "SERVICE_HOST_TYPE_RELAYED";
+
+  // Use the service's host client id and public key if the service is relayed.
+  const methodToken = this._voltClient.credential.getIdentityMetadata(
     this._voltClient.grpc,
-    this._voltClient.voltConfig.id,
-    this._voltClient.isRemote,
+    this._service?.service_description.host_client_id ||
+      this._voltClient.voltConfig.id,
+    this._service?.service_description.host_public_key ||
+      this._voltClient.credential.voltPublicKey,
+    true,
   );
+
   let invokeRequest;
   let callMethod = method;
 
-  if (this._voltClient.isVoltRelay) {
+  if (this._voltClient.isVoltRelay || isServiceRelayed) {
+    //
+    // 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().
+    //
     let requestPayload;
+
+    // Serialise the rpc request.
     if (request) {
       requestPayload = this._grpcClient[method].requestSerialize(request);
     } else if (request !== null) {
@@ -28,45 +43,61 @@ function _prepareInvokeRequest(
       log("explicit empty request payload");
     }
 
-    const tunnelMethod = this._grpcClient.Tunnel;
+    // Use this placeholder to serialise the relay request wrapper.
+    const voltGrpcClient = this._voltClient.getVoltAPIClient();
+    const tunnelMethod = voltGrpcClient.Tunnel;
 
     const tunnelResp = {
       method_invoke: {
         method_name: this._grpcClient[method].path,
         method_type: methodType,
-        token: meta.token,
+        token: methodToken.token,
         request: requestPayload,
       },
     };
 
-    const invokePayload = VoltCredential.aesEncrypt(
-      tunnelMethod.responseSerialize(tunnelResp),
-      meta.sharedKey.key,
-      meta.sharedKey.iv,
-    );
+    let targetFingerprint = [];
+    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,
+      );
+    } else {
+      invokePayload = tunnelMethod.responseSerialize(tunnelResp);
+    }
 
-    log("target volt is %s", this._voltClient.credential.voltFingerprint);
+    if (this._voltClient.isVoltRelay) {
+      targetFingerprint.push(this._voltClient.credential.voltFingerprint);
+    }
+
+    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,
+      );
+    }
+
+    log("target is %j", targetFingerprint);
 
     invokeRequest = {
-      identity_fingerprint: this._voltClient.credential.voltFingerprint,
+      target_fingerprint: targetFingerprint,
+      token: methodToken.token,
       payload: invokePayload,
+      target_service_id: isServiceRelayed ? this._service.id : undefined,
     };
 
+    // Replace the target method with a call to Invoke on the relay Volt.
     callMethod = "Invoke";
-  } else if (this._voltClient.isRemote && meta.sharedKey.key) {
-    const requestPayload =
-      this._grpcClient[method].requestSerializeOriginal(request);
-    invokeRequest = VoltCredential.aesEncrypt(
-      requestPayload,
-      meta.sharedKey.key,
-      meta.sharedKey.iv,
-    );
   } else {
     invokeRequest = request;
   }
 
   return {
-    meta,
+    meta: methodToken,
     method: callMethod,
     methodName: method,
     request: invokeRequest,
@@ -76,10 +107,16 @@ function _prepareInvokeRequest(
 function _preparePayloadRequest(request, invokeInfo) {
   let payloadRequest;
 
-  if (this._voltClient.isVoltRelay) {
+  const isServiceRelayed =
+    this._service?.service_description.host_type ===
+    "SERVICE_HOST_TYPE_RELAYED";
+
+  if (this._voltClient.isVoltRelay || isServiceRelayed) {
     const requestPayload =
       this._grpcClient[invokeInfo.methodName].requestSerialize(request);
-    const tunnelMethod = this._grpcClient.Tunnel;
+
+    const voltGrpcClient = this._voltClient.getVoltAPIClient();
+    const tunnelMethod = voltGrpcClient.Tunnel;
 
     const tunnelResp = {
       method_payload: {
@@ -96,14 +133,6 @@ function _preparePayloadRequest(request, invokeInfo) {
     payloadRequest = {
       payload: invokePayload,
     };
-  } else if (this._voltClient.isRemote && invokeInfo.meta.sharedKey.key) {
-    const requestPayload =
-      this._grpcClient[invokeInfo.methodName].requestSerializeOriginal(request);
-    payloadRequest = VoltCredential.aesEncrypt(
-      requestPayload,
-      invokeInfo.meta.sharedKey.key,
-      invokeInfo.meta.sharedKey.iv,
-    );
   } else {
     payloadRequest = request;
   }
@@ -112,21 +141,39 @@ function _preparePayloadRequest(request, invokeInfo) {
 }
 
 function _parseResponse(method, meta, response) {
+  // log("parseResponse for %s", this._methodName);
   let invokeResponse = {};
 
-  if (this._voltClient.isVoltRelay) {
+  const isServiceRelayed =
+    this._service?.service_description.host_type ===
+    "SERVICE_HOST_TYPE_RELAYED";
+
+  if (this._voltClient.isVoltRelay || isServiceRelayed) {
     if (response.payload) {
-      const decryptedPayload = VoltCredential.aesDecrypt(
-        response.payload,
-        meta.sharedKey.key,
-        meta.sharedKey.iv,
-      );
-      const tunnelMethod = this._grpcClient.Tunnel;
+      let decryptedPayload;
+      if (meta.sharedKey.key) {
+        decryptedPayload = VoltCredential.aesDecrypt(
+          response.payload,
+          meta.sharedKey.key,
+          meta.sharedKey.iv,
+        );
+      } else {
+        decryptedPayload = response.payload;
+      }
+
+      const tunnelMethod = this._voltClient.getVoltAPIClient().Tunnel;
       const responsePayload = tunnelMethod.requestDeserialize(decryptedPayload);
       if (responsePayload.payload === "method_payload") {
-        invokeResponse.payload = this._grpcClient[method].responseDeserialize(
-          responsePayload.method_payload.payload,
-        );
+        try {
+          invokeResponse.payload = this._grpcClient[method].responseDeserialize(
+            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",
+          );
+        }
       } else if (responsePayload.payload === "method_end") {
         invokeResponse = responsePayload.method_end;
       } else {
@@ -166,17 +213,22 @@ function _parseResponse(method, meta, response) {
 }
 
 export default class GRPCCall extends EventEmitter {
-  constructor(voltClient, methodName, methodType) {
+  constructor(voltClient, methodName, methodType, service = undefined) {
     super();
     this._methodName = methodName;
     this._methodType = methodType;
     this._call = null;
     this._voltClient = voltClient;
+    this._service = service;
   }
 
   start(grpcClient, request) {
     this._grpcClient = grpcClient;
 
+    if (typeof this._grpcClient[this._methodName] !== "function") {
+      throw new Error(`method not found: '${this._methodName}'`);
+    }
+
     this._initialRequest = _prepareInvokeRequest.call(
       this,
       request,
@@ -184,13 +236,18 @@ export default class GRPCCall extends EventEmitter {
       this._methodType,
     );
 
-    if (!this._grpcClient[this._initialRequest.method]) {
-      return reject(
-        new Error(`method not found: '${this._initialRequest.method}'`),
-      );
+    const isServiceRelayed =
+      this._service?.service_description.host_type ===
+      "SERVICE_HOST_TYPE_RELAYED";
+
+    let callClient;
+    if (this._voltClient.isVoltRelay || isServiceRelayed) {
+      callClient = this._voltClient.getVoltAPIClient();
+    } else {
+      callClient = this._grpcClient;
     }
 
-    this._call = this._grpcClient[this._initialRequest.method](
+    this._call = callClient[this._initialRequest.method](
       this._initialRequest.meta.metadata,
     );
 
@@ -223,7 +280,11 @@ export default class GRPCCall extends EventEmitter {
           log("method id is %s", parsedResponse.methodId);
         }
       } catch (err) {
-        log("failure processing connect response: %s", err.message);
+        log(
+          "failure processing %s call response: %s",
+          this._methodName,
+          err.message,
+        );
         this.emit("error", err);
       }
     });

package/src/proto-utils.js

@@ -2,6 +2,7 @@ import protoLoader from "@grpc/proto-loader";
 import lodash from "lodash";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
+import { writeFileSync, mkdirSync } from "fs";
 
 const { get: getProp, snakeCase } = lodash;
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -17,23 +18,23 @@ const defaultLoaderOptions = {
   includeDirs: [defaultProtoPath],
 };
 
-const getProtoDescriptors = (grpc, protoPath, opts) => {
+function getProtoDescriptors(grpc, protoPath, opts) {
   const definition = protoLoader.loadSync(
     protoPath,
     opts || defaultLoaderOptions,
   );
   const descriptors = grpc.loadPackageDefinition(definition);
   return descriptors;
-};
+}
 
-const getProtoService = (descriptors, servicePath) => {
+function getProtoService(descriptors, servicePath) {
   const serviceDef = getProp(descriptors, servicePath);
   if (serviceDef?.service) {
     return serviceDef.service;
   } else {
     return null;
   }
-};
+}
 
 function getServiceDescriptorsFromPath(
   grpc,
@@ -41,8 +42,30 @@ function getServiceDescriptorsFromPath(
   servicePackageName,
   opts,
 ) {
+  if (!opts) {
+    opts = { ...defaultLoaderOptions };
+    opts.includeDirs = [protoPath];
+  }
+
+  // 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 serviceProtoPath = join(
+    protoPath,
+    ...protoServiceComponents,
+    protoFileName,
+  );
+
   let serviceDescriptors;
-  const descriptors = getProtoDescriptors(grpc, protoPath, opts);
+  const descriptors = getProtoDescriptors(grpc, serviceProtoPath, opts);
   if (descriptors) {
     serviceDescriptors = getProtoService(descriptors, servicePackageName);
   }
@@ -90,7 +113,16 @@ function getProtoDescriptorMethods(protoDescriptor) {
   return methods;
 }
 
+function createServiceProtobufFiles(service, protoPath) {
+  for (let protoFile of service.service_description.proto_file) {
+    const filePath = join(protoPath, protoFile.file_path);
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, protoFile.protobuf);
+  }
+}
+
 export {
+  createServiceProtobufFiles,
   getServiceDescriptors,
   getProtoDescriptors,
   getProtoDescriptorMethods,

package/src/rpc-invocation.js

@@ -0,0 +1,273 @@
+import debug from "debug";
+import { VoltCredential } from "./volt-credential.js";
+import jwt from "jsonwebtoken";
+import EventEmitter from "events";
+
+const log = debug("rpc-invocation");
+
+class RpcInvocation extends EventEmitter {
+  #voltClient = null;
+  #voltConnection = null;
+  #token = null;
+  #encryptKey = null;
+  #encryptIV = null;
+  #invokeId = null;
+  #payload = null;
+  #isJSON = false;
+  #methodDescriptor = null;
+  #methodName = null;
+
+  constructor(voltClient, voltConnection) {
+    super();
+    this.#voltClient = voltClient;
+    this.#voltConnection = voltConnection;
+  }
+
+  get id() {
+    return this.#invokeId;
+  }
+
+  get payload() {
+    if (!this.#payload) {
+      return null;
+    }
+
+    let deserialisedPayload = null;
+
+    if (this.#isJSON) {
+      // Don't need to deserialise JSON payload.
+      deserialisedPayload = this.#payload;
+    } else if (this.#methodDescriptor) {
+      deserialisedPayload = this.#methodDescriptor.requestDeserialize(
+        this.#payload,
+      );
+    } else {
+      log("unexpected: no method descriptor");
+      throw new Error(
+        "no method descriptor - set this before accessing payload",
+      );
+    }
+
+    return deserialisedPayload;
+  }
+
+  get methodName() {
+    return this.#methodName;
+  }
+
+  set methodDescriptor(methodDescriptor) {
+    this.#methodDescriptor = methodDescriptor;
+  }
+
+  #decodeToken(token) {
+    // We don't verify the token at this point, as we don't know the public key.
+    // The rpc implementation should do the verification using the Volt API (e.g. CanAccessResource).
+    this.#token = jwt.decode(token);
+
+    if (this.#token.sk) {
+      // Decrypt the shared key and iv using the private key.
+      this.#encryptKey = VoltCredential.rsaDecrypt(
+        this.#voltClient.credential.cache.key,
+        this.#token.sk,
+      );
+      this.#encryptIV = VoltCredential.rsaDecrypt(
+        this.#voltClient.credential.cache.key,
+        this.#token.iv,
+      );
+    }
+
+    return Promise.resolve(this.#token);
+  }
+
+  initialise(invoke_request) {
+    this.#invokeId = invoke_request.invoke_id;
+
+    return this.#decodeToken(invoke_request.token)
+      .then(() => {
+        // Parse the initial payload.
+        return this.parsePayload(invoke_request);
+      })
+      .catch((err) => {
+        log("failure initialising invocation: %s", err.message);
+        return Promise.reject(err);
+      });
+  }
+
+  parsePayload(invoke_request) {
+    return new Promise((resolve, reject) => {
+      if (invoke_request.payload) {
+        let decryptedPayload;
+
+        if (this.#encryptKey) {
+          // Decrypt the actual payload using the shared key and iv.
+          decryptedPayload = VoltCredential.aesDecrypt(
+            invoke_request.payload,
+            this.#encryptKey,
+            this.#encryptIV,
+          );
+        } else {
+          // No encryption => just use the payload.
+          decryptedPayload = invoke_request.payload;
+        }
+
+        const tunnelMethod = this.#voltClient.getVoltAPIClient().Tunnel;
+        const wrappedPayload =
+          tunnelMethod.responseDeserialize(decryptedPayload);
+
+        if (wrappedPayload.method_invoke) {
+          // This is the initial request payload.
+          this.#methodName = wrappedPayload.method_invoke.method_name;
+          this.#payload = wrappedPayload.method_invoke.request;
+          this.emit("payload", this);
+        } else if (wrappedPayload.method_payload) {
+          // This is a subsequent payload, e.g. for streaming rpcs.
+          this.#payload = wrappedPayload.method_payload.payload;
+          this.emit("payload", this);
+        } else if (wrappedPayload.method_end) {
+          // This indicates the client has finished sending payloads.
+          // We don't need to do anything here, since we notify the client when we receive the client_end.
+          log("method_end received");
+        }
+
+        resolve();
+      } else if (invoke_request.json_payload) {
+        let decryptedPayload;
+
+        this.#isJSON = true;
+
+        if (this.#encryptKey) {
+          // Decrypt the actual payload using the shared key and iv.
+          decryptedPayload = VoltCredential.aesDecrypt(
+            Buffer.from(invoke_request.json_payload, "base64"),
+            this.#encryptKey,
+            this.#encryptIV,
+          );
+        } else {
+          // No encryption => just use the payload.
+          decryptedPayload = invoke_request.json_payload;
+        }
+
+        try {
+          const wrappedPayload = JSON.parse(decryptedPayload.toString());
+
+          if (wrappedPayload.method_invoke) {
+            this.#methodName = wrappedPayload.method_invoke.method_name;
+            this.#payload = JSON.parse(
+              wrappedPayload.method_invoke.json_request,
+            );
+            this.emit("payload", this);
+          } else if (wrappedPayload.method_payload) {
+            this.#payload = JSON.parse(
+              wrappedPayload.method_payload.json_payload,
+            );
+            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");
+          }
+        } catch (err) {
+          log("JSON.parse failure parsing json_payload: %s", err.message);
+          reject(err);
+        }
+
+        resolve();
+      } else if (invoke_request.client_end) {
+        this.emit("end", this);
+      } else {
+        // Do we need to support json_payload here?
+        reject(new Error("No payload in invoke request"));
+      }
+    }).catch((err) => {
+      log("failure parsing payload: %s", err.message);
+      return Promise.reject(err);
+    });
+  }
+
+  sendResponse(response) {
+    let responsePayload;
+    if (this.#isJSON) {
+      responsePayload = JSON.stringify({
+        method_payload: { json_payload: JSON.stringify(response) },
+      });
+    } else {
+      // We need to serialise the response, and then wrap it in a RemoteRequest.
+      const serialisedResponse =
+        this.#methodDescriptor.responseSerialize(response);
+      const tunnelMethod = this.#voltClient.getVoltAPIClient().Tunnel;
+      responsePayload = tunnelMethod.requestSerialize({
+        method_payload: { payload: serialisedResponse },
+      });
+    }
+
+    if (this.#token.sk) {
+      // Encrypt the response using the shared key and iv.
+      responsePayload = VoltCredential.aesEncrypt(
+        responsePayload,
+        this.#encryptKey,
+        this.#encryptIV,
+      );
+    }
+
+    const invokeResponse = {
+      invoke_id: this.#invokeId,
+    };
+
+    if (this.#isJSON) {
+      invokeResponse.json_payload =
+        Buffer.from(responsePayload).toString("base64");
+    } else {
+      invokeResponse.payload = responsePayload;
+    }
+
+    this.#voltConnection.send({
+      invoke_response: invokeResponse,
+    });
+  }
+
+  sendEnd(errorMessage) {
+    const tunnelMethod = this.#voltClient.getVoltAPIClient().Tunnel;
+
+    let endPayload;
+    if (errorMessage) {
+      endPayload = {
+        method_end: { error: errorMessage, ended: true },
+      };
+    } else {
+      endPayload = {
+        method_end: { ended: true },
+      };
+    }
+
+    if (this.#isJSON) {
+      endPayload = JSON.stringify(endPayload);
+    } else {
+      endPayload = tunnelMethod.requestSerialize(endPayload);
+    }
+
+    if (this.#token.sk) {
+      // Encrypt the response using the shared key and iv.
+      endPayload = VoltCredential.aesEncrypt(
+        endPayload,
+        this.#encryptKey,
+        this.#encryptIV,
+      );
+    }
+
+    const invokeResponse = {
+      invoke_id: this.#invokeId,
+      server_end: true,
+    };
+
+    if (this.#isJSON) {
+      invokeResponse.json_payload = Buffer.from(endPayload).toString("base64");
+    } else {
+      invokeResponse.payload = endPayload;
+    }
+
+    this.#voltConnection.send({
+      invoke_response: invokeResponse,
+    });
+  }
+}
+
+export default RpcInvocation;