@tdxvolt/volt-client-grpc 0.19.10 → 0.20.2

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 {
@@ -1997,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.
@@ -2103,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 {
@@ -2554,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.
@@ -2664,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.
@@ -2680,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 {
@@ -2708,6 +2735,9 @@ message AuthenticateResponse {
 
   // Reserved for internal use.
   int64 decision_time = 8;
+
+  // Any credentials issued to the client as part of the authentication process.
+  repeated string credential = 9;
 }
 
 message CanAccessResourceRequest {
@@ -3400,6 +3430,7 @@ message ResourceAttributeQuery {
   AttributeValue value = 3;
 }
 
+// Specify one of \`access\` or \`access_list\`.
 message SaveAccessRequest {
   // Omit \`id\` if creating new access.
   Access access = 1;
@@ -4811,6 +4842,11 @@ function issueAuthenticate(authenticateRequest, ttl) {
                 authenticateResponse.identity_did;
             }
 
+            this._credential.cache.vc = this._credential.cache.vc || [];
+            for (const credential of authenticateResponse.credential) {
+              this._credential.cache.vc.push(credential);
+            }
+
             this._credential.saveCache();
             break;
           }
@@ -4859,10 +4895,7 @@ function findDIDDocumentService(document, serviceType) {
   return matches;
 }
 
-async function authenticateInternal(
-  sessionOnly = false,
-  ownDID = false
-) {
+async function authenticateInternal(noDID = false, ownDID = false, exchangeToken = "") {
   try {
     if (!this._credential.cache.ca) {
       this._credential.cache.ca = this._voltConfig.ca_pem;
@@ -4893,18 +4926,23 @@ async function authenticateInternal(
       host: this._credential.cache.bindIp
     };
 
+    if (exchangeToken) {
+      log$2("setting request exchange token");
+      authenticateRequest.exchange_token = exchangeToken;
+    } else {
+      log$2("no exchange token in request");
+    }
+
     if (this._credential.cache.challenge_code) {
-      authenticateRequest.challenge = signBase64(
-        this._credential.cache.key,
-        this._credential.cache.challenge_code
-      );
+      log$2("setting request challenge code");
+      authenticateRequest.challenge = this._credential.cache.challenge_code;
     } else {
       log$2(
-        "****no Volt challenge code available**** => not sending challenge signature"
+        "no challenge code in request"
       );
     }
 
-    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");
@@ -5563,7 +5601,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);
@@ -5647,9 +5686,12 @@ 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.
+   * @param {string} [options.exchangeToken] - optional token to exchange in return for an authenticated session.
    */
   async initialise(config, options = {}) {
-    const { ownDID, didRegistryList, extraConfig } = options;
+    const { ownDID, noDID, didRegistryList, extraConfig } = options;
     try {
       if (!config) {
         throw new Error(
@@ -5735,7 +5777,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, exchangeToken);
         } 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.10",
+  "version": "0.20.2",
   "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

@@ -52,6 +52,11 @@ function issueAuthenticate(authenticateRequest, ttl) {
                 authenticateResponse.identity_did;
             }
 
+            this._credential.cache.vc = this._credential.cache.vc || [];
+            for (const credential of authenticateResponse.credential) {
+              this._credential.cache.vc.push(credential);
+            }
+
             this._credential.saveCache();
             break;
           }
@@ -100,10 +105,7 @@ function findDIDDocumentService(document, serviceType) {
   return matches;
 }
 
-export async function authenticateInternal(
-  sessionOnly = false,
-  ownDID = false
-) {
+export async function authenticateInternal(noDID = false, ownDID = false, exchangeToken = "") {
   try {
     if (!this._credential.cache.ca) {
       this._credential.cache.ca = this._voltConfig.ca_pem;
@@ -134,18 +136,23 @@ export async function authenticateInternal(
       host: this._credential.cache.bindIp
     };
 
+    if (exchangeToken) {
+      log("setting request exchange token");
+      authenticateRequest.exchange_token = exchangeToken;
+    } else {
+      log("no exchange token in request");
+    }
+
     if (this._credential.cache.challenge_code) {
-      authenticateRequest.challenge = signBase64(
-        this._credential.cache.key,
-        this._credential.cache.challenge_code
-      );
+      log("setting request challenge code");
+      authenticateRequest.challenge = this._credential.cache.challenge_code;
     } else {
       log(
-        "****no Volt challenge code available**** => not sending challenge signature"
+        "no challenge code in request"
       );
     }
 
-    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,12 @@ 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.
+   * @param {string} [options.exchangeToken] - optional token to exchange in return for an authenticated session.
    */
   async initialise(config, options = {}) {
-    const { ownDID, didRegistryList, extraConfig } = options;
+    const { ownDID, noDID, didRegistryList, extraConfig } = options;
     try {
       if (!config) {
         throw new Error(
@@ -170,7 +173,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, exchangeToken);
         } catch (bindErr) {
           if (bindErr.message === "invalid arguments") {
             // This is usually the result of a missing challenge signature or credential.

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 {
@@ -1452,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.
@@ -1558,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 {
@@ -2009,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.
@@ -2119,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.
@@ -2135,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 {
@@ -2163,6 +2190,9 @@ message AuthenticateResponse {
 
   // Reserved for internal use.
   int64 decision_time = 8;
+
+  // Any credentials issued to the client as part of the authentication process.
+  repeated string credential = 9;
 }
 
 message CanAccessResourceRequest {
@@ -2855,6 +2885,7 @@ message ResourceAttributeQuery {
   AttributeValue value = 3;
 }
 
+// Specify one of \`access\` or \`access_list\`.
 message SaveAccessRequest {
   // Omit \`id\` if creating new access.
   Access access = 1;