@tdxvolt/volt-client-grpc 0.11.8 → 0.14.60

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

@@ -24,12 +24,18 @@ service VoltAPI {
 
   rpc CheckCompatibility(CheckCompatibilityRequest) returns (CheckCompatibilityResponse);
 
-  // Creates a long-lived, bi-directional connection (session) to the Volt.
+  // Creates a long-lived, bi-directional connection to the Volt.
   // The connection stream serves several purposes, including remote invocations via a Relay, Volt event notifications, pings and service registration management.
-  // A connection session is required in order for a client to be able to register services with the Volt.
+  // A connection stream is required in order for a client to be able to register services with the Volt.
   // When the stream is closed, any services registered on it will be set to offline.
   rpc Connect(stream ConnectRequest) returns (stream ConnectResponse);
 
+  // Copy a resource from one folder to another.
+  // The resource metadata, attributes and store are copied.
+  // The shares attributed to the resource are **not** currently copied.
+  // n.b. Copy resources between Volts is not supported by this API. This is achieved by creating an API instance for the source and target Volts, getting the resource from the source and creating it on the target.
+  rpc CopyResource(CopyResourceRequest) returns (CopyResourceResponse);
+
   // This is a work in progress - do not use.
   rpc CreateVerifiableCredentialSession(CreateVerifiableCredentialSessionRequest) returns (CreateVerifiableCredentialSessionResponse);
 
@@ -84,10 +90,14 @@ service VoltAPI {
   // Get descendants of a resource.
   rpc GetResourceDescendants(GetResourceDescendantsRequest) returns (GetResourceDescendantsResponse);
 
+  // Get session(s).
+  rpc GetSession(GetSessionRequest) returns (GetSessionResponse);
+
   // Invoke a method.
   // This is primarily for use by Relay connections when proxying invocations.
   rpc Invoke(stream InvokeRequest) returns (stream InvokeResponse);
 
+  // Move a resource from one folder to another.
   rpc MoveResource(MoveResourceRequest) returns (MoveResourceResponse);
 
   // Request access to a resource.
@@ -97,8 +107,7 @@ service VoltAPI {
   // Create or update an access rule.
   rpc SaveAccess(SaveAccessRequest) returns (SaveAccessResponse);
 
-  // Create or update a cloud connection resource.
-  rpc SaveCloudConnection(SaveCloudConnectionRequest) returns (SaveCloudConnectionResponse);
+  rpc SaveAuthentication(SaveAuthenticationRequest) returns (SaveAuthenticationResponse);
 
   // Create or update an identity.
   rpc SaveIdentity(SaveIdentityRequest) returns (SaveIdentityResponse);
@@ -110,6 +119,12 @@ service VoltAPI {
   // Create or update resource in this volt.
   rpc SaveResource(SaveResourceRequest) returns (SaveResourceResponse);
 
+  // Save a session.
+  rpc SaveSession(SaveSessionRequest) returns (SaveSessionResponse);
+
+  // Experimental - please ignore.
+  rpc Session(SessionRequest) returns (SessionResponse);
+
   // Set Volt access request decision.
   // This is a privileged call that requires Volt root access.
   rpc SetAccessRequestDecision(SetAccessRequestDecisionRequest) returns (SetAccessRequestDecisionResponse);
@@ -144,17 +159,17 @@ message BindRequest {
 
   // The host name to add as a SAN to the issued certificate.
   // This is optional, if you don't intend to host services with the certificate this can be omitted.
-  string host = 5;
+  string host = 4;
 
   // DO NOT USE
   // Additional credentials to support the bind request.
   // If a certificate chain is presented (in the form of a concatenated list of PEM format x509 certificates) that includes a certificate with a public key matching the `public_key` field and that certificate is signed by another certificate for which the volt policy has a trust rule, this can be used to automatically permit/deny the request.
   // This is probably deprecated in favour of verifiable credentials.
-  repeated string x509_credential = 6;
+  repeated string x509_credential = 5;
 
   // Optional verifiable credentials describing the client.
   // This is a work in progress.
-  repeated VerifiablePresentation verifiable_presentation = 7;
+  repeated VerifiablePresentation verifiable_presentation = 6;
 }
 
 message BindResponse {
@@ -245,19 +260,28 @@ message ConnectHello {
   // Set to receive notification of resource events.
   bool subscribe_resource_events = 3;
 
-  // Set this to support Relayled service invocation.
+  // Set this to support Relayed service invocation.
   // This indicates that the callee is happy to receive method invocations from other clients of the Relay.
   // Currently this will usually be set to the `id` of the calling Volt, but in theory any client could receive remote invocation requests in this way.
   string relay_id = 4;
 
-  // A friendly name to present to other Relay clients.
+  // A friendly name to present to Relay clients.
   string relay_name = 5;
 
-  // The certificate authority to present to other Relay clients.
+  // The certificate authority to present to Relay clients.
   string relay_ca_pem = 6;
 
   // Set to indicate the connection is discoverable to other Relay clients.
   bool relay_discoverable = 7;
+
+  // Set to receive notification of authentication requests.
+  bool subscribe_auth_requests = 8;
+
+  bool accept_invocation = 9;
+}
+
+message ConnectAcknowledge {
+  string connection_id = 1;
 }
 
 // A session ping message.
@@ -285,25 +309,25 @@ enum ConnectMessageRelay {
 message ConnectMessage {
   string id = 1;
   string thread_id = 2;
-  string to_id = 4;
-  string to_identity_id = 5;
-  string to_name = 6;
-  string message = 7;
-  uint64 timestamp = 8;
-  string from_id = 9;
-  string from_identity_id = 10;
-  string from_name = 11;
+  string to_id = 3;
+  string to_identity_id = 4;
+  string to_name = 5;
+  string message = 6;
+  uint64 timestamp = 7;
+  string from_id = 8;
+  string from_identity_id = 9;
+  string from_name = 10;
 
-  repeated string receipt = 12;
-  ConnectMessageType message_type = 15;
-  ConnectMessageRelay message_relay = 16;
+  repeated string receipt = 11;
+  ConnectMessageType message_type = 12;
+  ConnectMessageRelay message_relay = 13;
 }
 
 message ConnectGoodbye {
   // Details of any error that occurred on the call.
   tdx.volt_api.volt.v1.Status status = 1;
 
-  // Set if the session was ended gracefully, as opposed to errored.
+  // Set if the connection was ended gracefully, as opposed to errored.
   bool ended = 2;
 }
 
@@ -323,19 +347,28 @@ enum ConnectResourceEvent {
 
 message ConnectResource {
   // The type of resource event that has occurred.
-  ConnectResourceEvent resource_event = 1;
+  ConnectResourceEvent event = 1;
 
   // Details of the resource.
   Resource resource = 2;
 }
 
+message ConnectAuthRequest {
+  Session session = 1;
+
+  string context = 5;
+
+  string challenge = 6;
+
+  uint64 timestamp = 7;
+}
+
 message ConnectEvent {
   oneof event {
-    // A resource event notification, such as updated or deleted.
-    ConnectResource connect_resource = 3;
+    ConnectAuthRequest connect_auth_request = 1;
 
-    // Events relating to Relay connections.
-    ConnectRelay relay = 6;
+    // A resource event notification, such as updated or deleted.
+    ConnectResource connect_resource = 2;
   }
 }
 
@@ -345,7 +378,7 @@ message ConnectRequest {
     // A ConnectHello message is the first message a client sends to the target upon successfully starting the call.
     ConnectHello hello = 1;
 
-    // Indicates the client is closing the session.
+    // Indicates the client is closing the connection.
     ConnectGoodbye goodbye = 2;
 
     // Reserved for internal use.
@@ -366,32 +399,63 @@ message ConnectRequest {
 
 // One of the following payloads will be present in a given ConnectResponse message.
 message ConnectResponse {
+  // Details of any error that occurred on the call.
+  tdx.volt_api.volt.v1.Status status = 1;
+
   oneof payload {
     // Server response to initial handshake.
-    ConnectHello hello = 1;
+    ConnectAcknowledge acknowledge = 2;
 
-    // Indicates the server is ending the session.
-    ConnectGoodbye goodbye = 2;
+    // Indicates the server is ending the connection.
+    ConnectGoodbye goodbye = 3;
 
     // Notifies clients of various events on the Volt.
-    ConnectEvent evt = 3;
+    ConnectEvent evt = 4;
 
     // Reserved for internal use.
-    ConnectMessage msg = 4;
+    ConnectMessage msg = 5;
 
     // Periodic ping response.
-    ConnectPing ping = 5;
+    ConnectPing ping = 6;
 
     // Send an invocation request to a remote target.
     // n.b. The 'request' and 'response' semantics are inverted for remote invocations because the Relayed connection is established by a request **from** the 'target' Volt to the Relay. Hence any invocation on behalf of a client of the Relay involves sending a **response** back down the Relay connection to the 'target' Volt.
-    InvokeRequest invoke_request = 6;
+    InvokeRequest invoke_request = 7;
 
     // Send an HTTP request to a remote target.
     // n.b. The 'request' and 'response' semantics are inverted for HTTP requests for the same reason as `invoke_request` above.
-    HttpRequest http_request = 7;
+    HttpRequest http_request = 8;
   }
 }
 
+enum CopyResourceMode {
+  COPY_RESOURCE_MODE_UNKNOWN = 0;
+  COPY_RESOURCE_MODE_COPY = 1;
+  COPY_RESOURCE_MODE_LINK = 2;
+}
+
+message CopyResourceRequest {
+  // The id of the resource to copy.
+  string resource_id = 1;
+
+  // The id of the resource to receive the new copy.
+  string to_resource_id = 2;
+
+  // The copy mode to use.
+  CopyResourceMode mode = 3;
+
+  // Indicates if all descendants of the resource should be copied too. Only relevant for COPY_RESOURCE_MODE_COPY mode.
+  bool recursive = 4;
+
+  // The parent resource to link from, only relevant for COPY_RESOURCE_MODE_LINK mode.
+  string from_resource_id = 5;
+}
+
+message CopyResourceResponse {
+  // Details of any error that occurred on the call.
+  tdx.volt_api.volt.v1.Status status = 1;
+}
+
 message CreateVerifiableCredentialSessionRequest {
   string presentation = 1;
 }
@@ -434,13 +498,13 @@ message DiscoverServicesRequest {
   // List the service APIs that should be discovered.
   // The response will include services that match **any of** the terms given.
   // Use of '*' to indicate wildcards is supported.
-  repeated string service_api = 2;
+  repeated string service_api = 1;
 
   // Set to indicate that offline services should be included in the response.
-  bool include_offline = 3;
+  bool include_offline = 2;
 
   // Set to include the service protobuf in the response.
-  bool include_protobuf = 4;
+  bool include_protobuf = 3;
 }
 
 message DiscoverServicesResponse {
@@ -571,7 +635,7 @@ message GetResourceRequest {
   string resource_id = 1;
 
   // Set to include service description protobuf in the response, if applicable.
-  bool include_protobuf = 3;
+  bool include_protobuf = 2;
 }
 
 message GetResourceResponse {
@@ -603,22 +667,22 @@ message GetResourcesRequest {
   // Wildcards permitted.
   repeated string service_api = 6;
 
-  repeated string owner = 8;
+  repeated string owner = 7;
 
-  repeated string store = 9;
+  repeated string store = 8;
 
   // Indicates that the above terms should be combined using 'or' rather than 'and' (the default).
-  bool combine_terms_exclusive = 10;
+  bool combine_terms_exclusive = 9;
 
   // Attributes to search by.
   // n.b. currently this API is mutually exclusive in that if any attribute queries are specified the rpc will only search on those attributes, ignoring any parameters defined above.
-  repeated ResourceAttributeQuery attribute = 100;
+  repeated ResourceAttributeQuery attribute = 10;
 
   // If set, will return resources where *any of* the attribute queries apply, otherwise will only return resources where *all of* the attribute queries apply.
-  bool any_of = 101;
+  bool any_of = 11;
 
   // Set to include service description protobuf in the response where applicable.
-  bool include_protobuf = 102;
+  bool include_protobuf = 12;
 }
 
 message GetResourcesResponse {
@@ -686,16 +750,31 @@ message GetResourceDescendantsResponse {
   repeated Resource descendant = 2;
 }
 
+message GetSessionRequest {
+  string id = 1;
+
+  string identity_id = 2;
+}
+
+message GetSessionResponse {
+  // Details of any error that occurred on the call.
+  tdx.volt_api.volt.v1.Status status = 1;
+
+  repeated Session session = 2;
+}
+
 message InvokeRequest {
   // Client-assigned identifier for the request. Will be used to match responses and any subsequent requests.
   uint64 invoke_id = 1;
 
   // The client token to use for the invocation.
+  // This contains the key and iv used to encrypt the payload, which only the token audience can access because the key and iv are themselves encrypted using the public key of the invocation target.
   string token = 2;
 
   // Key fingerprint of the target Volt.
   // This is used by Relays to route the request.
-  string identity_fingerprint = 3;
+  // We can't (currently) use the target Volt id here, since there is currently no way to universally 'reason about' a given identity (Volt). For example, Alice may have assigned Bob an identity of 123, whereas Carol assigned Bob an identity of 456.
+  repeated string target_fingerprint = 3;
 
   oneof request_payload {
     // A serialised and encrypted instance of `RemoteResponse` in pure binary format.
@@ -707,6 +786,10 @@ message InvokeRequest {
 
   // Indicates the client has ended the invocation.
   bool client_end = 6;
+
+  uint32 hop_index = 7;
+
+  string target_service_id = 8;
 }
 
 message InvokeResponse {
@@ -728,18 +811,15 @@ message InvokeResponse {
   bool server_end = 5;
 }
 
-enum MoveResourceMode {
-  MOVE_RESOURCE_MODE_UNKNOWN = 0;
-  MOVE_RESOURCE_MODE_MOVE = 1;
-  MOVE_RESOURCE_MODE_LINK = 2;
-  MOVE_RESOURCE_MODE_COPY = 3;
-}
-
 message MoveResourceRequest {
+  // The id of the resource to move.
   string resource_id = 1;
+
+  // The resource the parent folder to move the resource from.
   string from_resource_id = 2;
+
+  // The target folder to move the resource into.
   string to_resource_id = 3;
-  MoveResourceMode move_mode = 4;
 }
 
 message MoveResourceResponse {
@@ -763,25 +843,25 @@ message RequestAccessResponse {
   string resource_id = 2;
 
   // The identity attempting access.
-  string identity_id = 4;
+  string identity_id = 3;
 
   // The identity of the issuer of the access.
-  string issuer_id = 5;
+  string issuer_id = 4;
 
   // Requested access.
-  string access = 7;
+  string access = 5;
 
   // Assigned decision.
-  PolicyDecision decision = 9;
+  PolicyDecision decision = 6;
 
   // Time at which the request was made.
-  int64 request_time = 10;
+  int64 request_time = 7;
 
   // Time at which the decision was taken.
-  int64 decision_time = 11;
+  int64 decision_time = 8;
 
   // Counter of number times this access was requested.
-  int32 request_count = 12;
+  int32 request_count = 9;
 }
 
 message ResourceAttributeQuery {
@@ -800,23 +880,25 @@ message SaveAccessResponse {
   tdx.volt_api.volt.v1.Status status = 1;
 }
 
-message SaveCloudConnectionRequest {
-  // Details of the cloud connection.
-  ProxyConnection connection = 1;
+message SaveAuthenticationRequest {
+  string id = 1;
 
-  // Set to indicate that this is a new cloud connection.
-  bool create = 2;
+  string identity_id = 2;
 
-  // Reserved for system use.
-  string create_in_parent_id = 3;
+  string identity_did = 3;
+
+  string public_key = 4;
+
+  string encrypt_key = 5;
+
+  string encrypt_iv = 6;
+
+  PolicyDecision decision = 7;
 }
 
-message SaveCloudConnectionResponse {
+message SaveAuthenticationResponse {
   // Details of any error that occurred on the call.
   tdx.volt_api.volt.v1.Status status = 1;
-
-  // The updated connection details.
-  ProxyConnection connection = 2;
 }
 
 message SaveIdentityRequest {
@@ -890,6 +972,32 @@ message SaveResourceResponse {
   Resource resource = 2;
 }
 
+message SaveSessionRequest {
+  Session session = 1;
+}
+
+message SaveSessionResponse {
+  // Details of any error that occurred on the call.
+  tdx.volt_api.volt.v1.Status status = 1;
+
+  Session session = 2;
+}
+
+message SessionRequest {
+  string session_id = 1;
+  oneof payload {
+    string fingerprint = 2;
+    string signature = 3;
+  }
+}
+
+message SessionResponse {
+  // Details of any error that occurred on the call.
+  tdx.volt_api.volt.v1.Status status = 1;
+  string proof = 2;
+  string session_id = 3;
+}
+
 message SetServiceStatusRequest {
   // The service description details.
   Resource service = 2;
@@ -968,9 +1076,9 @@ message SignVerifyResponse {
 
   oneof payload {
     // The signature in raw binary form.
-    bytes digest = 3;
+    bytes digest = 2;
 
     // The signature encoded using base64.
-    string digest_encoded = 4;
+    string digest_encoded = 3;
   }
 }

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 client-streaming call to the wire resource.
+  // Establishes a bi-directional 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/volt-client-internal.js

@@ -42,10 +42,10 @@ function issueBind(bindRequest, ttl) {
           // This is the certificate assigned to us by the volt.
           this._credential.cache.cert = bindResponse.cert;
 
-          // This is the signing CA used by the volt (don't ov)
+          // This is the signing CA used by the volt.
           this._credential.cache.ca = bindResponse.chain;
 
-          // Resource id is assigned by the volt.
+          // Identity resource id is assigned by the volt.
           this._credential.cache.client_id = bindResponse.identity_id;
           this._credential.saveCache();
           break;
@@ -187,7 +187,7 @@ export async function bindInternal() {
   }
 }
 
-export function connectInternal() {
+export function connectInternal(helloPayload) {
   try {
     if (this._voltConnection) {
       log("connectInternal - Volt connection already exists");
@@ -217,7 +217,7 @@ export function connectInternal() {
       if (!this._connected) {
         onDisconnected();
       }
-      this.emit("connected", !!session);
+      this.emit("connected", session);
     });
 
     this._voltConnection.on("error", (err) => {
@@ -233,7 +233,7 @@ export function connectInternal() {
       this.emit("evt", evt);
     });
 
-    return this._voltConnection.connect();
+    return this._voltConnection.connect(helloPayload);
   } catch (err) {
     log("connect - error [%s]", err.message);
     throw err;

package/src/volt-client.js

@@ -189,10 +189,10 @@ export class VoltClient extends EventEmitter {
     }
   }
 
-  initialiseAndConnect(configPath, extras = {}) {
+  initialiseAndConnect(configPath, helloPayload = undefined, extras = {}) {
     return this.initialise(configPath, extras)
       .then(() => {
-        return connectInternal.call(this);
+        return connectInternal.call(this, helloPayload);
       })
       .catch((err) => {
         log("initialiseAndConnect failure: %s", err.message);
@@ -265,8 +265,8 @@ export class VoltClient extends EventEmitter {
     return this.isRemote && !this._voltConfig?.relay.cloud;
   }
 
-  connect() {
-    return connectInternal.call(this);
+  connect(helloPayload) {
+    return connectInternal.call(this, helloPayload);
   }
 
   disconnect() {