@tdxvolt/volt-client-grpc 0.19.9 → 0.20.1

package/lib/index.cjs

@@ -1158,6 +1158,9 @@ message UploadFileResponse {
 
   // Reserved for internal use.
   bool back_off = 2;
+  
+  // Indicates the number of blocks that have been received.
+  uint32 ack = 3;
 }
 
 `;
@@ -1452,6 +1455,9 @@ import "tdx/volt_api/volt/v1/status.proto";
 import "tdx/volt_api/volt/v1/ssi.proto";
 
 service SsiAPI {
+  // Get a short-lived, one-time token that can be used to authenticate with the Volt and potentially create verifiable credential(s).
+  rpc CreateExchangeToken(CreateExchangeTokenRequest) returns (CreateExchangeTokenResponse);
+
   // Delete a DID document or all DID documents originating from a given Volt.
   // Requires \`volt:delete-did\` API privilege.
   rpc DeleteDID(DeleteDIDRequest) returns (DeleteDIDResponse);
@@ -1481,6 +1487,22 @@ service SsiAPI {
   rpc SearchDIDRegistry(SearchDIDRegistryRequest) returns (SearchDIDRegistryResponse);
 }
 
+message CreateExchangeTokenRequest {
+  // The VC template to use to create a verifiable credential.
+  string vc_template = 1;
+
+  // The time to live for the token, in seconds.
+  uint32 ttl = 2;
+}
+
+message CreateExchangeTokenResponse {
+  // Details of any error that occurred on the call.
+  tdx.volt_api.volt.v1.Status status = 1;
+
+  // The one-time token.
+  string token = 2;
+}
+
 message DeleteDIDRequest {
   // Specify an individual DID as the target of the delete operation, or a Volt to delete all DIDs owned by that Volt.
   oneof target {
@@ -1709,6 +1731,9 @@ message SyncDocumentStart {
 
   // Set to true to only receive updates from other clients.
   bool read_only = 4;
+
+  // Set to true to downgrade to read-only access if the client does not have write access.
+  bool read_only_fallback = 5;
 }
 
 message SyncDocumentUpdate {
@@ -1742,6 +1767,9 @@ message SyncDocumentResponse {
 
   // The sync state of the Volt (remote) document
   SyncState sync_state = 4;
+
+  // Set to true if the client is in read-only mode. Only present in the initial response.
+  bool is_read_only = 5;
 }
 
 message GetDocumentJSONRequest {
@@ -1765,38 +1793,56 @@ package tdx.volt_api.volt.v1;
 import "tdx/volt_api/volt/v1/status.proto";
 
 service TerminalAPI {
+  // Bidirectional streaming RPC for real-time terminal control and data exchange.
   rpc CommandStream(stream CommandStreamRequest) returns (stream CommandStreamResponse);
 }
 
 message TerminalSize {
+  // The number of rows in the terminal.
   int32 rows = 1;
+  // The number of columns in the terminal.
   int32 cols = 2;
 }
 
 message Control {
+  // Optional command to execute on the terminal. If omitted, the default command is \`bash\` on linux and \`zsh\` on macos.
   string command = 1;
+  // Optional arguments to pass to the command.
   repeated string arg = 2;
+  // Not currently used.
   string stop = 3;
+  // Not currently used.
   string pause = 4;
+  // Not currently used.
   string resume = 5;
+  // Not currently used.
   string reset = 6;
+  // Optional terminal size to set.
   TerminalSize terminal_size = 7;
+  // If non-zero, a \`kill\` signal will be sent with this value to the running process.
   int32 interrupt = 8;
 }
 
 message Input {
+  // The data to send to the terminal.
   bytes data = 1;
 }
 
+// The request message must contain either a control message or an input message.
 message CommandStreamRequest {
   oneof payload {
+    // Control messages can be used to configure and control the terminal.
     Control control = 1;
+    // Input messages are used to send data to the terminal.
     Input input = 2;
   }
 }
 
+// The response message contains either a status message or stream of bytes.
 message CommandStreamResponse {
+  // Details of any error that occurred on the call.
   tdx.volt_api.volt.v1.Status status = 1;
+  // Bytes received from the terminal.
   bytes data = 2;
 }
 
@@ -1973,10 +2019,10 @@ message VoltParameters {
   // Indicates the Volt will be discoverable by clients using the discovery api.
   bool discoverable = 16;
 
-  // Optional challenge code that can be used aid in the process of authenticating clients.
+  // DEPRECATED: Optional challenge code that can be used aid in the process of authenticating clients.
   string authenticate_challenge = 18;
 
-  // Indicates that clients must present the correct challenge code in order to be able to authenticate.
+  // DEPRECATED: Indicates that clients must present the correct challenge code in order to be able to authenticate.
   bool require_authenticate_challenge = 19;
 
   // Internal use only.
@@ -2079,6 +2125,9 @@ message VoltParameters {
 
   // The time at which the Volt was started.
   uint64 start_time = 50;
+
+  // If set, enables the agent event pool.
+  bool enable_agent_event_pool = 51;
 }
 
 message VoltEndpoint {
@@ -2530,7 +2579,7 @@ service VoltAPI {
   // The identity will only be retrieved if the authenticated identity has read access to it.
   rpc GetIdentity(GetIdentityRequest) returns (GetIdentityResponse);
 
-  // Gets a one-time token that can be used as a temporary authentication token, for example create an file download link that expires after a certain time.
+  // Gets a one-time token that can be used as a temporary authentication token, for example to create a file download link that expires after a certain time.
   rpc GetOneTimeToken(GetOneTimeTokenRequest) returns (GetOneTimeTokenResponse);
 
   // Retrieve the Volt parameters.
@@ -2640,8 +2689,7 @@ message AuthenticateRequest {
   // A human-readable name of the entity requesting to authenticate.
   string client_name = 6;
 
-  // The volt challenge code, signed by the private key component of the \`public_key\` field above, and base64 encoded.
-  // This is optional.
+  // Optional challenge code, hashed using SHA-256 and base64 encoded.
   string challenge = 7;
 
   // The host name to add as a SAN to the issued certificate.
@@ -2656,6 +2704,9 @@ message AuthenticateRequest {
 
   // Optional additional name to differentiate between multiple sessions for a given client.
   string session_name = 11;
+
+  // Optional one-time token to exchange for a session.
+  string exchange_token = 12;
 }
 
 message AuthenticateResponse {
@@ -2745,6 +2796,9 @@ message ConnectHello {
   // Set to receive notification of resource events.
   bool subscribe_resource_events = 4;
 
+  // Optionally specify which resource events to subscribe to. Only valid if \`subscribe_resource_events\` is set. If omitted or empty, all resource events will be subscribed to.
+  repeated ConnectResourceEvent resource_event_list = 17;
+
   // Set this if you are connecting to a relay, i.e. the Volt you are sending to this message is a relay.
   // This indicates that you are happy to receive method invocations from clients of the Relay.
   // This will usually be set to the \`id\` of your Volt, but in theory any client could receive remote invocation requests in this way.
@@ -2937,6 +2991,9 @@ message CopyResourceResponse {
 message DeleteAccessRequest {
   // The id of the access rule to delete.
   string id = 1;
+
+  // Set to indicate all access rules for the resource should be deleted. The \`id\` field is ignored if this is set.
+  string resource_id = 2;
 }
 
 message DeleteAccessResponse {
@@ -3370,9 +3427,13 @@ message ResourceAttributeQuery {
   AttributeValue value = 3;
 }
 
+// Specify one of \`access\` or \`access_list\`.
 message SaveAccessRequest {
   // Omit \`id\` if creating new access.
   Access access = 1;
+
+  // Add multiple access rules in one request. The \`access\` field is ignored if this is non-empty.
+  repeated Access access_list = 2;
 }
 
 message SaveAccessResponse {
@@ -4606,7 +4667,7 @@ function _doConnect(connectHello) {
   this.call.on("data", (response) => {
     switch (response.payload) {
       case "ping": {
-        log$3("pinged");
+        log$3("received ping [%s]", this._voltClient.config.client_name);
 
         // Received ping response from server => clear timeout.
         if (this._pingTimeoutTimer) {
@@ -4678,7 +4739,7 @@ function _startPingTimer() {
     // Send next ping to server.
     const request = { ping: { timestamp: Date.now() } };
 
-    log$3("pinging Volt");
+    log$3("sending ping [%s]", this._voltClient.config.client_name);
     this.call.write(request);
 
     this._pingTimer = 0;
@@ -4826,10 +4887,7 @@ function findDIDDocumentService(document, serviceType) {
   return matches;
 }
 
-async function authenticateInternal(
-  sessionOnly = false,
-  ownDID = false
-) {
+async function authenticateInternal(noDID = false, ownDID = false) {
   try {
     if (!this._credential.cache.ca) {
       this._credential.cache.ca = this._voltConfig.ca_pem;
@@ -4861,17 +4919,14 @@ async function authenticateInternal(
     };
 
     if (this._credential.cache.challenge_code) {
-      authenticateRequest.challenge = signBase64(
-        this._credential.cache.key,
-        this._credential.cache.challenge_code
-      );
+      authenticateRequest.challenge = this._credential.cache.challenge_code;
     } else {
       log$2(
-        "****no Volt challenge code available**** => not sending challenge signature"
+        "****challenge code NOT available**** => not sending challenge signature"
       );
     }
 
-    if (sessionOnly) {
+    if (noDID) {
       // We want to create a session-based authentication based simply on our key, rather than a
       // fully-blown DID-based authentication.
       log$2("creating session-only request");
@@ -5530,7 +5585,8 @@ class VoltCredential {
   }
 
   saveCache() {
-    const clone = { ...this._config, credential: { ...this._cryptoCache } };
+    this._config = {...this._config, credential: { ...this._cryptoCache } };
+    const clone = { ...this._config };
     if (this._config.p) {
       // A passphrase option exists => encrypt the key before writing the cache file.
       const key = keyFromPem(this._cryptoCache.key);
@@ -5614,9 +5670,11 @@ class VoltClient extends EventEmitter__default["default"] {
    * configuration from the config file.
    * @param {boolean} [options.ownDID] - whether the Volt should manage the DID - set to
    * true  if you want to manage the DID yourself
+   * @param {boolean} [options.noDID] - whether to create a key-based authentication session
+   * instead of a DID-based authentication session.
    */
   async initialise(config, options = {}) {
-    const { ownDID, didRegistryList, extraConfig } = options;
+    const { ownDID, noDID, didRegistryList, extraConfig } = options;
     try {
       if (!config) {
         throw new Error(
@@ -5702,7 +5760,7 @@ class VoltClient extends EventEmitter__default["default"] {
       } else {
         // No certificate present in the cache yet => we need to authenticate.
         try {
-          isBound = await authenticateInternal.call(this, false, ownDID);
+          isBound = await authenticateInternal.call(this, noDID, ownDID);
         } catch (bindErr) {
           if (bindErr.message === "invalid arguments") {
             // This is usually the result of a missing challenge signature or credential.

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.19.9",
+  "version": "0.20.1",
   "description": "tdx Volt library for nodejs clients",
   "type": "module",
   "exports": {
@@ -33,7 +33,7 @@
   "author": "toby.ealden@gmail.com",
   "license": "ISC",
   "dependencies": {
-    "@tdxvolt/volt-client-web": "^0.19.9",
+    "@tdxvolt/volt-client-web": "^0.20.4",
     "debug": "^4.1.1",
     "ip": "^1.1.5",
     "jsonwebtoken": "^8.5.1",
@@ -42,4 +42,4 @@
     "protobufjs": "^7.4.0",
     "uuid": "^8.1.0"
   }
-}
+}

package/src/volt-client-internal.js

@@ -100,10 +100,7 @@ function findDIDDocumentService(document, serviceType) {
   return matches;
 }
 
-export async function authenticateInternal(
-  sessionOnly = false,
-  ownDID = false
-) {
+export async function authenticateInternal(noDID = false, ownDID = false) {
   try {
     if (!this._credential.cache.ca) {
       this._credential.cache.ca = this._voltConfig.ca_pem;
@@ -135,17 +132,14 @@ export async function authenticateInternal(
     };
 
     if (this._credential.cache.challenge_code) {
-      authenticateRequest.challenge = signBase64(
-        this._credential.cache.key,
-        this._credential.cache.challenge_code
-      );
+      authenticateRequest.challenge = this._credential.cache.challenge_code;
     } else {
       log(
-        "****no Volt challenge code available**** => not sending challenge signature"
+        "****challenge code NOT available**** => not sending challenge signature"
       );
     }
 
-    if (sessionOnly) {
+    if (noDID) {
       // We want to create a session-based authentication based simply on our key, rather than a
       // fully-blown DID-based authentication.
       log("creating session-only request");

package/src/volt-client.js

@@ -82,9 +82,11 @@ export class VoltClient extends EventEmitter {
    * configuration from the config file.
    * @param {boolean} [options.ownDID] - whether the Volt should manage the DID - set to
    * true  if you want to manage the DID yourself
+   * @param {boolean} [options.noDID] - whether to create a key-based authentication session
+   * instead of a DID-based authentication session.
    */
   async initialise(config, options = {}) {
-    const { ownDID, didRegistryList, extraConfig } = options;
+    const { ownDID, noDID, didRegistryList, extraConfig } = options;
     try {
       if (!config) {
         throw new Error(
@@ -170,7 +172,7 @@ export class VoltClient extends EventEmitter {
       } else {
         // No certificate present in the cache yet => we need to authenticate.
         try {
-          isBound = await authenticateInternal.call(this, false, ownDID);
+          isBound = await authenticateInternal.call(this, noDID, ownDID);
         } catch (bindErr) {
           if (bindErr.message === "invalid arguments") {
             // This is usually the result of a missing challenge signature or credential.

package/src/volt-connection.js

@@ -69,7 +69,7 @@ function _doConnect(connectHello) {
   this.call.on("data", (response) => {
     switch (response.payload) {
       case "ping": {
-        log("pinged");
+        log("received ping [%s]", this._voltClient.config.client_name);
 
         // Received ping response from server => clear timeout.
         if (this._pingTimeoutTimer) {
@@ -141,7 +141,7 @@ function _startPingTimer() {
     // Send next ping to server.
     const request = { ping: { timestamp: Date.now() } };
 
-    log("pinging Volt");
+    log("sending ping [%s]", this._voltClient.config.client_name);
     this.call.write(request);
 
     this._pingTimer = 0;

package/src/volt-credential.js

@@ -170,7 +170,8 @@ export class VoltCredential {
   }
 
   saveCache() {
-    const clone = { ...this._config, credential: { ...this._cryptoCache } };
+    this._config = {...this._config, credential: { ...this._cryptoCache } };
+    const clone = { ...this._config };
     if (this._config.p) {
       // A passphrase option exists => encrypt the key before writing the cache file.
       const key = keyFromPem(this._cryptoCache.key);

package/src/volt-proto-literals.js

@@ -613,6 +613,9 @@ message UploadFileResponse {
 
   // Reserved for internal use.
   bool back_off = 2;
+  
+  // Indicates the number of blocks that have been received.
+  uint32 ack = 3;
 }
 
 `;
@@ -907,6 +910,9 @@ import "tdx/volt_api/volt/v1/status.proto";
 import "tdx/volt_api/volt/v1/ssi.proto";
 
 service SsiAPI {
+  // Get a short-lived, one-time token that can be used to authenticate with the Volt and potentially create verifiable credential(s).
+  rpc CreateExchangeToken(CreateExchangeTokenRequest) returns (CreateExchangeTokenResponse);
+
   // Delete a DID document or all DID documents originating from a given Volt.
   // Requires \`volt:delete-did\` API privilege.
   rpc DeleteDID(DeleteDIDRequest) returns (DeleteDIDResponse);
@@ -936,6 +942,22 @@ service SsiAPI {
   rpc SearchDIDRegistry(SearchDIDRegistryRequest) returns (SearchDIDRegistryResponse);
 }
 
+message CreateExchangeTokenRequest {
+  // The VC template to use to create a verifiable credential.
+  string vc_template = 1;
+
+  // The time to live for the token, in seconds.
+  uint32 ttl = 2;
+}
+
+message CreateExchangeTokenResponse {
+  // Details of any error that occurred on the call.
+  tdx.volt_api.volt.v1.Status status = 1;
+
+  // The one-time token.
+  string token = 2;
+}
+
 message DeleteDIDRequest {
   // Specify an individual DID as the target of the delete operation, or a Volt to delete all DIDs owned by that Volt.
   oneof target {
@@ -1164,6 +1186,9 @@ message SyncDocumentStart {
 
   // Set to true to only receive updates from other clients.
   bool read_only = 4;
+
+  // Set to true to downgrade to read-only access if the client does not have write access.
+  bool read_only_fallback = 5;
 }
 
 message SyncDocumentUpdate {
@@ -1197,6 +1222,9 @@ message SyncDocumentResponse {
 
   // The sync state of the Volt (remote) document
   SyncState sync_state = 4;
+
+  // Set to true if the client is in read-only mode. Only present in the initial response.
+  bool is_read_only = 5;
 }
 
 message GetDocumentJSONRequest {
@@ -1220,38 +1248,56 @@ package tdx.volt_api.volt.v1;
 import "tdx/volt_api/volt/v1/status.proto";
 
 service TerminalAPI {
+  // Bidirectional streaming RPC for real-time terminal control and data exchange.
   rpc CommandStream(stream CommandStreamRequest) returns (stream CommandStreamResponse);
 }
 
 message TerminalSize {
+  // The number of rows in the terminal.
   int32 rows = 1;
+  // The number of columns in the terminal.
   int32 cols = 2;
 }
 
 message Control {
+  // Optional command to execute on the terminal. If omitted, the default command is \`bash\` on linux and \`zsh\` on macos.
   string command = 1;
+  // Optional arguments to pass to the command.
   repeated string arg = 2;
+  // Not currently used.
   string stop = 3;
+  // Not currently used.
   string pause = 4;
+  // Not currently used.
   string resume = 5;
+  // Not currently used.
   string reset = 6;
+  // Optional terminal size to set.
   TerminalSize terminal_size = 7;
+  // If non-zero, a \`kill\` signal will be sent with this value to the running process.
   int32 interrupt = 8;
 }
 
 message Input {
+  // The data to send to the terminal.
   bytes data = 1;
 }
 
+// The request message must contain either a control message or an input message.
 message CommandStreamRequest {
   oneof payload {
+    // Control messages can be used to configure and control the terminal.
     Control control = 1;
+    // Input messages are used to send data to the terminal.
     Input input = 2;
   }
 }
 
+// The response message contains either a status message or stream of bytes.
 message CommandStreamResponse {
+  // Details of any error that occurred on the call.
   tdx.volt_api.volt.v1.Status status = 1;
+  // Bytes received from the terminal.
   bytes data = 2;
 }
 
@@ -1428,10 +1474,10 @@ message VoltParameters {
   // Indicates the Volt will be discoverable by clients using the discovery api.
   bool discoverable = 16;
 
-  // Optional challenge code that can be used aid in the process of authenticating clients.
+  // DEPRECATED: Optional challenge code that can be used aid in the process of authenticating clients.
   string authenticate_challenge = 18;
 
-  // Indicates that clients must present the correct challenge code in order to be able to authenticate.
+  // DEPRECATED: Indicates that clients must present the correct challenge code in order to be able to authenticate.
   bool require_authenticate_challenge = 19;
 
   // Internal use only.
@@ -1534,6 +1580,9 @@ message VoltParameters {
 
   // The time at which the Volt was started.
   uint64 start_time = 50;
+
+  // If set, enables the agent event pool.
+  bool enable_agent_event_pool = 51;
 }
 
 message VoltEndpoint {
@@ -1985,7 +2034,7 @@ service VoltAPI {
   // The identity will only be retrieved if the authenticated identity has read access to it.
   rpc GetIdentity(GetIdentityRequest) returns (GetIdentityResponse);
 
-  // Gets a one-time token that can be used as a temporary authentication token, for example create an file download link that expires after a certain time.
+  // Gets a one-time token that can be used as a temporary authentication token, for example to create a file download link that expires after a certain time.
   rpc GetOneTimeToken(GetOneTimeTokenRequest) returns (GetOneTimeTokenResponse);
 
   // Retrieve the Volt parameters.
@@ -2095,8 +2144,7 @@ message AuthenticateRequest {
   // A human-readable name of the entity requesting to authenticate.
   string client_name = 6;
 
-  // The volt challenge code, signed by the private key component of the \`public_key\` field above, and base64 encoded.
-  // This is optional.
+  // Optional challenge code, hashed using SHA-256 and base64 encoded.
   string challenge = 7;
 
   // The host name to add as a SAN to the issued certificate.
@@ -2111,6 +2159,9 @@ message AuthenticateRequest {
 
   // Optional additional name to differentiate between multiple sessions for a given client.
   string session_name = 11;
+
+  // Optional one-time token to exchange for a session.
+  string exchange_token = 12;
 }
 
 message AuthenticateResponse {
@@ -2200,6 +2251,9 @@ message ConnectHello {
   // Set to receive notification of resource events.
   bool subscribe_resource_events = 4;
 
+  // Optionally specify which resource events to subscribe to. Only valid if \`subscribe_resource_events\` is set. If omitted or empty, all resource events will be subscribed to.
+  repeated ConnectResourceEvent resource_event_list = 17;
+
   // Set this if you are connecting to a relay, i.e. the Volt you are sending to this message is a relay.
   // This indicates that you are happy to receive method invocations from clients of the Relay.
   // This will usually be set to the \`id\` of your Volt, but in theory any client could receive remote invocation requests in this way.
@@ -2392,6 +2446,9 @@ message CopyResourceResponse {
 message DeleteAccessRequest {
   // The id of the access rule to delete.
   string id = 1;
+
+  // Set to indicate all access rules for the resource should be deleted. The \`id\` field is ignored if this is set.
+  string resource_id = 2;
 }
 
 message DeleteAccessResponse {
@@ -2825,9 +2882,13 @@ message ResourceAttributeQuery {
   AttributeValue value = 3;
 }
 
+// Specify one of \`access\` or \`access_list\`.
 message SaveAccessRequest {
   // Omit \`id\` if creating new access.
   Access access = 1;
+
+  // Add multiple access rules in one request. The \`access\` field is ignored if this is non-empty.
+  repeated Access access_list = 2;
 }
 
 message SaveAccessResponse {