@tdxvolt/volt-client-grpc 0.1.0

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@tdxvolt/volt-client-grpc",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.1.0",
+  "description": "tdx Volt library for nodejs clients",
+  "type": "module",
+  "exports": {
+    ".": {
+      "require": "./lib/index.cjs",
+      "import": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src",
+    "protobuf"
+  ],
+  "scripts": {
+    "build": "rollup -c",
+    "dev": "rollup -c -w",
+    "prepare": "npm run build"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^19.0.0",
+    "@rollup/plugin-node-resolve": "^13.0.0",
+    "escodegen": "^1.14.3",
+    "espree": "^3.5.4",
+    "installing": "^1.0.0",
+    "jsdoc": "^3.6.10",
+    "rollup": "^2.52.6",
+    "uglify-js": "^3.15.5"
+  },
+  "author": "toby.ealden@gmail.com",
+  "license": "ISC",
+  "dependencies": {
+    "@grpc/proto-loader": "^0.6.4",
+    "bent": "^7.3.12",
+    "bs58": "^4.0.1",
+    "debug": "^4.1.1",
+    "ip": "^1.1.5",
+    "jsonwebtoken": "^8.5.1",
+    "lodash": "^4.17.15",
+    "minimist": "^1.2.0",
+    "node-forge": "^0.9.0",
+    "uuid": "^8.1.0"
+  }
+}

package/protobuf/README.md

@@ -0,0 +1,4 @@
+# tdx Volt protobuf
+
+**WARNING** - this is a duplication of the protobuf defined in https://github.com/tdxvolt/tdxvolt-core, which is the
+source of truth.

package/protobuf/tdx/volt_api/data/v1/sqlite.proto

@@ -0,0 +1,43 @@
+syntax = "proto3";
+
+package tdx.volt_api.data.v1;
+
+// Just reflect SQLite types for now.
+enum ColumnType {
+  COLUMN_TYPE_UNKNOWN = 0;
+  COLUMN_TYPE_TEXT = 1;
+  COLUMN_TYPE_INTEGER = 2;
+  COLUMN_TYPE_REAL = 3;
+  COLUMN_TYPE_BLOB = 4;
+  COLUMN_TYPE_NULL = 5;
+}
+
+message Column {
+  string name = 1;
+  string description = 2;
+  ColumnType type = 3;
+}
+
+message Schema {
+  string name = 1;
+  string description = 2;
+  repeated Column column = 3;
+}
+
+message Variant {
+  ColumnType type = 1;
+  oneof data {
+    string text = 2;
+    int64 integer = 3;
+    double real = 4;
+    bytes blob = 5;
+  }
+}
+
+message RowHeader {
+  repeated Column column = 1;
+}
+
+message VariantRow {
+  repeated Variant column = 1;
+}

package/protobuf/tdx/volt_api/data/v1/sqlite_database_api.proto

@@ -0,0 +1,105 @@
+syntax = "proto3";
+
+package tdx.volt_api.data.v1;
+
+import "tdx/volt_api/volt/v1/status.proto";
+import "tdx/volt_api/data/v1/sqlite.proto";
+
+// The Sqlite Database API exposes functions that enable clients to manipulate data in a given Volt database.
+// Use the Sqlite Server API to create the database resource.
+service SqliteDatabaseAPI {
+  // Execute multiple SQL statements in a single transaction via a single RPC.
+  rpc BulkUpdate(SqlBulkUpdateRequest) returns (SqlBulkUpdateResponse);
+
+  // Execute a single SQL statement. Any valid SQL is accepted. In order to execute non-SELECT statements, the caller must have the "write" permission.
+  rpc Execute(stream SqlExecuteRequest) returns (stream SqlExecuteResponse);
+
+  // Import CSV data into a table.
+  // The data can either be streamed in chunks or retrieved from an existing resource.
+  // If the data is streamed in chunks, the client must call the Close() method on the stream to indicate that it has finished.
+  rpc ImportCSV(stream SqlImportCSVRequest) returns (stream SqlImportCSVResponse);
+}
+
+message SqlBulkUpdateRequest {
+  // The id of the database to update.
+  string database_id = 1;
+
+  // The SQL statements to execute. The statements will be executed within a transaction and will be committed if all statements succeed.
+  // Bear in mind the maximum size limit of a single message is 64MB, and around 1MB seems to be optimal in terms of performance.
+  repeated string statement = 2;
+}
+
+message SqlBulkUpdateResponse {
+  // Details of any error that occurred on the call.
+  tdx.volt_api.volt.v1.Status status = 1;
+}
+
+// The initial request should include the `database_id` and `statement` fields and an optional `page_size` for SELECT statements.
+// To retrieve subsequent pages, send another request with just the `page_size` field set.
+message SqlExecuteRequest {
+  // The id of the database to execute the statement on, only necessary on the first request message.
+  string database_id = 1;
+
+  // The SQL statement to execute, only necessary on the first request message.
+  string statement = 2;
+
+  // This can be used to limit the number of rows returned by `SELECT` statements to avoid overloading a client. It is similar to using 'LIMIT/OFFSET' clauses on the 'SELECT' statement, but this method is easier to manage and the entire result set will be prepared on the Volt, and the client can then page through it by sending successive messages.
+  uint32 page_size = 3;
+}
+
+message SqlExecuteResponse {
+  oneof payload {
+    // A status will be sent on error.
+    tdx.volt_api.volt.v1.Status status = 1;
+
+    // The initial response for SELECT statements will be a header containing the column names and types.
+    RowHeader header = 2;
+
+    // Each row in the result set will be sent as a VariantRow.
+    VariantRow row = 3;
+
+    // NYI - For INSERT/UPDATE statements the number of affected rows will be sent.
+    uint32 affected_rows = 4;
+  }
+}
+
+message SqlImportCSVConfiguration {
+  // The target database resource id, which must already exist, and the authenticated account must have write access to the resource.
+  string database_id = 1;
+
+  // The target table name.
+  string table_name = 2;
+
+  // Not yet implemented - flag indicating that data is to be inserted into an existing table.
+  bool create_table = 3;
+
+  // Optional - when not sending the data via this RPC, this should contain the id of a resource that contains the CSV data. If set, the authenticated account must have read access to the resource.
+  string source_resource_id = 4;
+
+  // Optional - the interval to receive progress updates, in number of rows. E.g. set to 1000 to receive progress updates every 1000 rows. Set to 0 to disable progress updates.
+  uint32 progress_interval = 5;
+}
+
+message SqlImportCSVRequest {
+  oneof payload {
+    // The initial request must contain the configuration parameters for the import.
+    SqlImportCSVConfiguration configuration = 1;
+
+    // Subsequent requests may contain the data to be imported, unless importing from an existing resource that contains the CSV data. It is recommended that the block size is less than 1MB.
+    bytes block = 2;
+
+    // Set to abort the import.
+    bool abort = 3;
+  }
+}
+
+message SqlImportCSVResponse {
+  // The status will contain any error info.
+  tdx.volt_api.volt.v1.Status status = 1;
+
+  // The number of rows processed - this will be sent after every `progress_interval` rows.
+  int64 row_count = 2;
+
+  // The total number of rows to be imported.
+  int64 total_rows = 3;
+}

package/protobuf/tdx/volt_api/data/v1/sqlite_server_api.proto

@@ -0,0 +1,42 @@
+syntax = "proto3";
+
+package tdx.volt_api.data.v1;
+
+import "tdx/volt_api/volt/v1/status.proto";
+import "tdx/volt_api/volt/v1/volt.proto";
+
+// The Sqlite Server API provides database management functions.
+// Use the VoltAPI DeleteResource function to delete a database.
+service SqliteServerAPI {
+  // Create a new database resource.
+  rpc CreateDatabase(CreateDatabaseRequest) returns (CreateDatabaseResponse);
+}
+
+message CreateDatabaseRequest {
+  // The name of the database to create.
+  string name = 1;
+
+  // Optional - the id of the folder resource in which to create the database. If omitted, the callers home folder is used.
+  string create_in_parent_id = 2;
+
+  // Set to encrypt the database. The encryption key will be generated by the server, the internal Volt server uses the root volt key.
+  bool encrypted = 3;
+
+  // Set to audit all SELECT database operations.
+  bool read_audit = 4;
+
+  // Set to audit all INSERT, UPDATE, and DELETE database operations.
+  bool write_audit = 5;
+
+  // The discovery mode of the underlying Volt resource.
+  tdx.volt_api.volt.v1.DiscoveryMode discoverable = 6;
+}
+
+message CreateDatabaseResponse {
+  // Any error message will be returned here.
+  tdx.volt_api.volt.v1.Status status = 1;
+
+  // The new database resource on success.
+  tdx.volt_api.volt.v1.Resource resource = 2;
+}
+

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

@@ -0,0 +1,37 @@
+syntax = "proto3";
+
+package tdx.volt_api.ssi.v1;
+
+import "tdx/volt_api/volt/v1/status.proto";
+
+// Volt DIDs are essentially 'peer DIDs', i.e. they are not globally resolvable.
+// TDX DIDs are globally resolvable.
+
+service SsiAPI {
+  rpc ResolveDID(ResolveDIDRequest) returns (ResolveDIDResponse);
+  rpc TrustVerifiableCredential(TrustVerifiableCredentialRequest) returns (TrustVerifiableCredentialResponse);
+}
+
+//
+// Do we need to support/differentiate between plain DIDs and DID urls here?
+// Where a DID url is a DID followed by some additional lookup info,
+// e.g. did:tdx:volt:92181ffa-072a-452a-ae79-a243ab2812fc;service=/some/service?query#fragment
+//
+message ResolveDIDRequest {
+  string did_url = 1;
+}
+
+message ResolveDIDResponse {
+  tdx.volt_api.volt.v1.Status status = 1;
+  string did_document_json = 2;
+}
+
+// Empty ATM - a VC is issued for the authenticated identity.
+message TrustVerifiableCredentialRequest {
+}
+
+message TrustVerifiableCredentialResponse {
+  tdx.volt_api.volt.v1.Status status = 1;
+  string verifiable_credential_json = 2;
+}
+

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

@@ -0,0 +1,14 @@
+syntax = "proto3";
+
+package tdx.volt_api.sync.v1;
+
+message ProtobufSyncConfiguration {
+  // The actual protobuf definition text.
+  string message_proto = 1;
+  // The name of the message within `message_proto` above that represents the data to be synched.
+  string message_name = 2;
+  // The name of the table within the target database.
+  string table_name = 3;
+  // Optional maximum size of the serialised messages, this doesn't need to be exact and the default is 64K if omitted.
+  int32 maximum_message_size = 6;
+}

package/protobuf/tdx/volt_api/tunnel/v1/proxy_api.proto

@@ -0,0 +1,9 @@
+syntax = "proto3";
+
+package tdx.volt_api.tunnel.v1;
+
+// Placeholder API for the proxy.
+// Methods are injected into this service at runtime
+// when a remote volt connects via the TunnelAPI.
+service ProxyAPI {
+}

package/protobuf/tdx/volt_api/tunnel/v1/tunnel_api.proto

@@ -0,0 +1,77 @@
+syntax = "proto3";
+
+package tdx.volt_api.tunnel.v1;
+
+import "tdx/volt_api/volt/v1/status.proto";
+import "tdx/volt_api/volt/v1/remote.proto";
+import "tdx/volt_api/volt/v1/volt.proto";
+
+service TunnelAPI {
+  // Retrieve the list of Volts available on the tunnel server (Volt-based or cloud-based).
+  rpc GetVoltEndpoint(GetVoltEndpointRequest) returns (GetVoltEndpointResponse);
+
+  // This is the actual tunnel stream.
+  rpc Tunnel(stream tdx.volt_api.volt.v1.RemoteRequest) returns (stream tdx.volt_api.volt.v1.RemoteResponse);
+
+  // This is the tunnel stream for cloud-based tunnels.
+  rpc CloudTunnel(stream TunnelRequest) returns (stream TunnelResponse);
+}
+
+message GetVoltEndpointRequest {
+  // Optional - if omitted a list of all volts known to the authenticated
+  // account will be returned.
+  oneof filter {
+    // Filter on the owning identity.
+    string owner_id = 2;
+    // Filter on volt id.
+    string volt_id = 1;
+  }
+}
+
+message GetVoltEndpointResponse {
+  tdx.volt_api.volt.v1.Status status = 1;
+  repeated tdx.volt_api.volt.v1.VoltEndpoint endpoints = 2;
+}
+
+message TunnelStart {
+  uint32 preferred_port = 1;
+  string local_address = 2;
+  string public_key = 3;
+  string fingerprint = 4;
+  string ca_pem = 5;
+  string volt_version = 6;
+}
+
+message TunnelServiceControl {
+  string resource_id = 1;
+  string service_name = 2;
+  tdx.volt_api.volt.v1.ServiceDescription service_description = 3;
+}
+
+message TunnelControl {
+  oneof msg {
+    TunnelStart start = 2;
+    TunnelServiceControl add_service = 3;
+    TunnelServiceControl remove_service = 4;
+  }
+}
+
+message TunnelRequest {
+  oneof payload {
+    tdx.volt_api.volt.v1.RemotePing ping = 1;
+    TunnelControl control = 2;
+    tdx.volt_api.volt.v1.MethodPayload method_payload = 3;
+    tdx.volt_api.volt.v1.MethodEnd method_end = 4;
+    tdx.volt_api.volt.v1.HttpResponse http_response = 5;
+  }
+}
+
+message TunnelResponse {
+  oneof payload {
+    tdx.volt_api.volt.v1.RemotePing ping = 1;
+    tdx.volt_api.volt.v1.MethodInvoke method_invoke = 2;
+    tdx.volt_api.volt.v1.MethodPayload method_payload = 3;
+    tdx.volt_api.volt.v1.MethodEnd method_end = 4;
+    tdx.volt_api.volt.v1.HttpRequest http_request = 5;
+  }
+}

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

@@ -0,0 +1,39 @@
+syntax = "proto3";
+
+package tdx.volt_api.volt.v1;
+
+import "tdx/volt_api/volt/v1/status.proto";
+import "tdx/volt_api/volt/v1/volt.proto";
+
+// The public Volt discovery service. 
+// This is exposed by the Volt battery over an INSECURE grpc channel.
+// This insecurity is ameliorated by the fact that discovered Volts return signatures of their challenge code and owner credential.
+// Note that only Volts that have explicitly set 'discoverable' in the Volt settings will be discovered.
+service DiscoveryAPI {
+  rpc Discover(DiscoverRequest) returns (DiscoverResponse) {};
+}
+
+message DiscoverRequest {
+  // Set to require that only Volts that expose a tunnel be included in the response.
+  bool require_tunnel = 1;
+}
+
+message SignedEndpoint {
+  // The discovered Volt endpoint information.
+  tdx.volt_api.volt.v1.VoltEndpoint endpoint = 1;
+
+  // The discovered Volt's challenge code, signed by the Volt private key and base64 encoded.
+  // If a client knows the Volt challenge code by some out-of-band means, it can use the Volt public key (contained in the endpoint information above) to determine that the discovered Volt also knows the same challenge code.
+  string challenge_signature = 2;
+
+  // The discovered Volt's owner credential, signed by the Volt private key and base64 encoded.
+  // A client can use this to discover all Volts owned by a specific user.
+  string owner_credential_signature = 4;
+}
+
+message DiscoverResponse {
+  tdx.volt_api.volt.v1.Status status = 1;
+
+  // A list of endpoints that match the request criteria.
+  repeated SignedEndpoint endpoints = 2;
+}

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

@@ -0,0 +1,17 @@
+syntax = "proto3";
+
+package tdx.volt_api.volt.v1;
+
+message File {
+  string file_path = 1;
+  string absolute_path = 2;
+  string file_name = 3;
+  string extension = 4;
+  uint64 size = 5;
+  string media_type = 6;
+  bool is_directory = 7;
+  uint64 modified = 8;
+
+  string resource_id = 100;
+  string owner_resource_id = 101;
+}

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

@@ -0,0 +1,117 @@
+syntax = "proto3";
+
+package tdx.volt_api.volt.v1;
+
+import "tdx/volt_api/volt/v1/status.proto";
+import "tdx/volt_api/volt/v1/file.proto";
+
+// The File API exposes basic file management functions.
+service FileAPI {
+
+  // Download from file resource.
+  rpc DownloadFile(DownloadFileRequest) returns (stream DownloadFileResponse);
+
+  // Get file resource metadata.
+  rpc GetFile(GetFileRequest) returns (GetFileResponse);
+
+  // Get the file resource metadata of all descendants of a given file resource. 
+  rpc GetFileDescendants(GetFileDescendantsRequest) returns (GetFileDescendantsResponse);
+
+  // Upload data to a file resource.
+  rpc UploadFile(stream UploadFileRequest) returns (stream UploadFileResponse);
+}
+
+message DownloadFileRequest {
+  // The id of the resource to download.
+  string resource_id = 1;
+
+  // This is required for linked folders, and represents the relative path to the source file from the base folder.
+  string file_path = 2;
+}
+
+message DownloadFileResponse {
+  oneof payload {
+    // A chunk of file data.
+    bytes block = 1;
+
+    // A status will be sent when the file is completely downloaded, or if an error occurs.
+    tdx.volt_api.volt.v1.Status status = 2;
+  }
+}
+
+message GetFileRequest {
+  // The resource id of the base folder.
+  string resource_id = 1;
+
+  // Optional - the path to the file, relative to the base folder. Required for linked folders.
+  string file_path = 2;
+}
+
+message GetFileResponse {
+  // Details of any error that occurred on the call.
+  tdx.volt_api.volt.v1.Status status = 1;
+
+  // The file metadata.
+  File file = 2;
+}
+
+message GetFileDescendantsRequest {
+  // The resource id of the base folder.
+  string resource_id = 1;
+
+  // For linked files, this is the relative path to the 'parent' file from the base folder.
+  string file_path = 2;
+
+  // Optional - only match descendants of the given kind.
+  string extension = 3;
+
+  // Optional - can be used to determine if a resource is a descendant.
+  string descendant_id = 5;
+}
+
+message GetFileDescendantsResponse {
+  // Details of any error that occurred on the call.
+  tdx.volt_api.volt.v1.Status status = 1;
+
+  // The list of descendants.
+  repeated File descendants = 2;
+}
+
+message UploadFileStart {
+  // The resource to upload to, required.
+  string resource_id = 1;
+
+  // Optional store name to use.
+  string store_name = 2;
+
+  // Optionally set streaming mode.
+  // When in streaming mode, data is written directly to the resource.
+  // Otherwise, data is written to a temporary file and then copied over once the upload completes successfully.
+  bool streaming_mode = 3;
+
+  // Optional, truncates the file prior to beginning the upload. This is only really relevant if 'streaming_mode' is set.
+  bool truncate = 4;
+
+  // Optional, buffer will flush after each write.
+  bool eager_flush = 5;
+}
+
+// One of the following fields must be present.
+message UploadFileRequest {
+  oneof payload {
+    // Describes the file upload, should only be sent as first message.
+    UploadFileStart start = 1;
+
+    // The next block of data.
+    bytes block = 2;
+  }
+}
+
+message UploadFileResponse {
+  // Details of any error that occurred on the call.
+  tdx.volt_api.volt.v1.Status status = 1;
+
+  // Reserved for internal use.
+  bool back_off = 2;
+}
+

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

@@ -0,0 +1,94 @@
+syntax = "proto3";
+
+package tdx.volt_api.volt.v1;
+
+message HttpInvoke {
+  string host = 1;
+  int32 port = 2;
+  string method = 3;
+  string url = 4;
+  string version = 5;
+  map <string, string> headers = 6;
+  bytes body = 7;
+}
+
+message HttpPayload {
+  bytes chunk = 1;
+  oneof end_ {
+    bool end = 2;
+  }
+  oneof error_ {
+    int32 error = 3;
+  }
+}
+
+message HttpRequest {
+  uint64 id = 1;
+  oneof payload {
+    HttpInvoke http_invoke = 2;
+    HttpPayload http_payload = 3;
+  }
+}
+
+message HttpResponse {
+  uint64 id = 1;
+  HttpPayload http_payload = 7;
+}
+
+enum MethodType {
+  METHOD_TYPE_UNKNOWN = 0;
+  METHOD_TYPE_UNARY = 1;
+  METHOD_TYPE_CLIENT_STREAM = 2;
+  METHOD_TYPE_SERVER_STREAM = 3;
+  METHOD_TYPE_BIDI = 4;
+}
+
+message MethodInvoke {
+  uint64 id = 1;
+  string service_id = 2;
+  string method_name = 3;
+  MethodType method_type = 4;
+  string token = 5;
+  oneof invoke_request {
+    bytes request = 6;
+    string json_request = 7;
+  }
+}
+
+message MethodPayload {
+  uint64 id = 1;
+  oneof method_payload {
+    bytes payload = 2;
+    string json_payload = 3;
+  }
+}
+
+message MethodEnd {
+  uint64 id = 1;
+  bool ended = 4;
+  string error = 5;
+  int32 error_code = 6;
+}
+
+message RemotePing {
+  uint64 timestamp = 1;
+}
+
+message RemoteRequest {
+  oneof payload {
+    RemotePing ping = 1;
+    MethodPayload method_payload = 3;
+    MethodEnd method_end = 4;
+    HttpResponse http_response = 5;
+  }
+}
+
+message RemoteResponse {
+  oneof payload {
+    RemotePing ping = 1;
+    MethodInvoke method_invoke = 2;
+    MethodPayload method_payload = 3;
+    MethodEnd method_end = 4;
+    HttpRequest http_request = 5;
+  }
+}

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

@@ -0,0 +1,15 @@
+syntax = "proto3";
+
+package tdx.volt_api.volt.v1;
+
+message Status {
+  // A simple error code that can be easily handled by the client.
+  // Mirrors the grpc StatusCode enum, 0 => OK
+  int32 code = 1;
+
+  // A developer-facing human-readable error message in English. It should both explain the error and offer an actionable resolution to it.
+  string message = 2;
+
+  // Long form error description.
+  string description = 3;
+}