@tdxvolt/volt-client-grpc 0.1.0

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

@@ -0,0 +1,50 @@
+syntax = "proto3";
+
+package tdx.volt_api.volt.v1;
+
+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 client-streaming call to the wire resource.
+  rpc PublishWire(stream PublishRequest) returns (PublishResponse);
+
+  // Establishes a bi-directional streaming call to the wire resource.
+  // Although we're only really interested in receiving data from the wire, a bi-directional stream is required so that we can gracefully stop the subscription.
+  rpc SubscribeWire(stream SubscribeRequest) returns (stream SubscribeResponse);
+}
+
+message PublishRequest {
+  // Only necessary in the first payload.
+  string wire_id = 1;
+
+  // The chunk of data to publish.
+  bytes chunk = 2;
+}
+
+message PublishResponse {
+  // Details of any error that occurred on the call.
+  tdx.volt_api.volt.v1.Status status = 1;
+}
+
+// The request must include one of the following fields.
+message SubscribeRequest {
+  oneof payload {
+    // The wire id, only required for the first message.
+    string wire_id = 1;
+    // Request to stop the subscription.
+    bool stop = 2;
+  }
+}
+
+// One of the following fields will be present in the response.
+message SubscribeResponse {
+  oneof payload {
+    // Details of any error that occured on the call.
+    tdx.volt_api.volt.v1.Status status = 1;
+
+    // Data received from the wire.
+    bytes chunk = 2;
+  }
+}
+

package/src/constants.js

@@ -0,0 +1,75 @@
+// eslint-disable-next-line import/prefer-default-export
+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`.
+};

package/src/grpc-call.js

@@ -0,0 +1,254 @@
+/* eslint-disable no-underscore-dangle */
+import debug from "debug";
+import EventEmitter from "events";
+import {VoltCrypto} from "./volt-crypto.js";
+
+const log = debug("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("****************LOOKOUT****************** - empty request");
+    } else {
+      log("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("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("unexpected tunnel payload type: %s", responsePayload.payload);
+      }
+    } else if (response.status && response.status.message) {
+      // There's been an error in the tunnel.
+      log(
+        "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("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;
+}
+
+export default class GRPCCall extends EventEmitter {
+  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("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("method id is %s", parsedResponse.methodId);
+          }
+        } catch (err) {
+          log("failure processing connect response: %s", err.message);
+          this.emit("error", err);
+        }
+      });
+
+      this._call.on("error", (err) => {
+        log("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("finished call %s", this._methodName);
+        this.emit("finish");
+      });
+
+      this._call.on("end", () => {
+        // The remote peer ended the stream.
+        log("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("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);
+    }
+  }
+}

package/src/grpc-utils.js

@@ -0,0 +1,197 @@
+/* eslint-disable no-underscore-dangle */
+/* eslint-disable no-param-reassign */
+import lodash from "lodash";
+import {createSecureContextOptions} from "./utils.js";
+
+const {forEach, isEmpty} = lodash;
+
+const serialiseNOP = (arg) => {
+  return arg;
+};
+
+export 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;
+  }
+}
+
+export 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);
+}

package/src/index.js

@@ -0,0 +1,7 @@
+export {constants} from "./constants.js";
+export * as grpcUtils from "./grpc-utils.js";
+export * as utils from "./utils.js";
+export {VoltClient} from "./volt-client.js";
+export * from "./volt-crypto.js";
+export * as protoUtils from "./proto-utils.js";
+export {v4 as generateId} from "uuid";

package/src/proto-utils.js

@@ -0,0 +1,81 @@
+import protoLoader from "@grpc/proto-loader";
+import lodash from "lodash";
+import {dirname, join} from "path";
+import {fileURLToPath} from "url";
+
+const {get: getProp, snakeCase} = lodash;
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const defaultProtoPath = join(__dirname, "../protobuf");
+
+const defaultLoaderOptions = {
+  keepCase: true,
+  longs: String,
+  enums: String,
+  defaults: true,
+  oneofs: true,
+  includeDirs: [defaultProtoPath],
+};
+
+const getProtoDescriptors = (grpc, protoPath, opts) => {
+  const definition = protoLoader.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 = 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;
+}
+
+export {getServiceDescriptors, getProtoDescriptors, getProtoDescriptorMethods, getServiceDescriptorsFromPath};