@tdxvolt/volt-client-grpc 0.15.1 → 0.16.0-beta.2

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

@@ -4,6 +4,7 @@ package tdx.volt_api.volt.v1;
 
 import "tdx/volt_api/volt/v1/status.proto";
 import "tdx/volt_api/volt/v1/remote.proto";
+import "tdx/volt_api/volt/v1/ssi.proto";
 import "tdx/volt_api/volt/v1/volt.proto";
 
 // The top-level volt management service. 
@@ -11,9 +12,11 @@ import "tdx/volt_api/volt/v1/volt.proto";
 // A client certificate can be obtained from the `Bind` method.
 // All methods include a `tdx.volt_api.volt.v1.Status` in the response. If the status contains a non-OK error code the client should assume the remainder of the message is invalid, unless otherwise indicated in the response documentation.
 service VoltAPI {
+  rpc Authenticate(AuthenticateRequest) returns (AuthenticateResponse);
+
   // Issues a request to bind to the volt.
   // All clients must successfully bind to the Volt in order to gain any kind of access.
-  // A client certificate is optional for this RPC, in which case a JWT must be provided in the call metadata.
+  // A client certificate is optional for this RPC, if omitted a JWT must be provided in the call metadata.
   // If the client plans to register one or more services with the Volt, it should use the 'host' field of the request so that the returned certificate has the appropriate SAN extension in place. Note that if the client IP address changes it will be necessary to re-Bind the client and obtain a new certificate.
   // If the bind decision is 'permit', the bind response contains various details that should be persisted by the client, including the unique identifier assigned by the Volt and a signed client certificate along with the Volt CA certificate.
   rpc Bind(BindRequest) returns (BindResponse);
@@ -122,9 +125,6 @@ service VoltAPI {
   // 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);
@@ -133,6 +133,8 @@ service VoltAPI {
   // This is a privileged call that requires Volt root access.
   rpc SetBindingDecision(SetBindingDecisionRequest) returns (SetBindingDecisionResponse);
 
+  rpc SetPolicy(SetPolicyRequest) returns (SetPolicyResponse);
+
   // Set the status of a Volt service.
   rpc SetServiceStatus(SetServiceStatusRequest) returns (SetServiceStatusResponse);
 
@@ -145,31 +147,112 @@ service VoltAPI {
 }
 
 // Describes a request to bind to a volt.
-message BindRequest {
+message AuthenticateRequest {
+
+  oneof client_identifier {
+    // An existing DID owned by the client.
+    // The JWT presented with the Bind call must be signed by the private key corresponding to this DID.
+    string did = 1;
+
+    // If the client doesn't have an existing DID, a DID document can be provided here.
+    // The document must include a proof that the client owns the public key given in `public_key`.
+    // The Volt will register the DID on behalf of the client.
+    // The JWT presented with the Bind call must be signed by the private key corresponding to this document.
+    string did_document = 2;
+
+    // The client public key - must be in PEM format. If the client DID is lost or unknown for some reason, providing the public key here will allow the Volt to match it with the previously registered DID.
+    // Note this is only valid when a DID has previously been registered using this public key.
+    string public_key = 3;
+  }
 
-  // The client public key - must be in PEM format.
-  string public_key = 1;
+  // A base64-encoded signature of the DID document, only required if `did_document` is provided above.
+  string did_document_signature = 4;
 
   // A human-readable name of the entity requesting to bind.
-  string binding_name = 2;
+  string binding_name = 5;
 
   // The volt challenge code, signed by the private key component of the `public_key` field above, and base64 encoded.
   // This is optional.
-  string challenge = 3;
+  string challenge = 6;
 
   // 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 = 4;
+  string host = 7;
+
+  // Optional verifiable credentials describing the client.
+  // This is a work in progress.
+  repeated VerifiablePresentation verifiable_presentation = 8;
+
+  // Reserved for internal use.
+  bool purge_aliases = 9;
+}
+
+message AuthenticateResponse {
+  // Details of any error that occurred on the call.
+  tdx.volt_api.volt.v1.Status status = 1;
+
+  string session_id = 2;
+
+  // The identity id assigned to this binding.
+  // Only valid for PERMIT bind decisions.
+  string identity_id = 3;
+
+  // A certificate issued by the volt CA, binding the request public key to the identity.
+  // Only valid for PERMIT bind decisions.
+  string cert = 4;
+
+  // The volt CA chain. This is used by the client in subsequent API calls to secure the connection.
+  string chain = 5;
+
+  // The bind decision.
+  PolicyDecision decision = 6;
+
+  // Reserved for internal use.
+  int64 request_time = 7;
 
-  // 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 = 5;
+  // Reserved for internal use.
+  int64 decision_time = 8;
+}
+
+// Describes a request to bind to a volt.
+message BindRequest {
+
+  oneof client_identifier {
+    // An existing DID owned by the client.
+    // The JWT presented with the Bind call must be signed by the private key corresponding to this DID.
+    string did = 1;
+
+    // If the client doesn't have an existing DID, a DID document can be provided here.
+    // The document must include a proof that the client owns the public key given in `public_key`.
+    // The Volt will register the DID on behalf of the client.
+    // The JWT presented with the Bind call must be signed by the private key corresponding to this document.
+    string did_document = 2;
+
+    // The client public key - must be in PEM format. If the client DID is lost or unknown for some reason, providing the public key here will allow the Volt to match it with the previously registered DID.
+    // Note this is only valid when a DID has previously been registered using this public key.
+    string public_key = 3;
+  }
+
+  // A base64-encoded signature of the DID document, only required if `did_document` is provided above.
+  string did_document_signature = 4;
+
+  // A human-readable name of the entity requesting to bind.
+  string binding_name = 5;
+
+  // The volt challenge code, signed by the private key component of the `public_key` field above, and base64 encoded.
+  // This is optional.
+  string challenge = 6;
+
+  // 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 = 7;
 
   // Optional verifiable credentials describing the client.
   // This is a work in progress.
-  repeated VerifiablePresentation verifiable_presentation = 6;
+  repeated VerifiablePresentation verifiable_presentation = 8;
+
+  // Reserved for internal use.
+  bool purge_aliases = 9;
 }
 
 message BindResponse {
@@ -278,13 +361,15 @@ message ConnectHello {
   bool subscribe_auth_requests = 8;
 
   bool accept_invocation = 9;
+
+  bool subscribe_did_registry_updates = 10;
 }
 
 message ConnectAcknowledge {
   string connection_id = 1;
 }
 
-// A session ping message.
+// A connection ping message.
 message ConnectPing {
   // The time on the originating server.
   uint64 timestamp = 1;
@@ -343,6 +428,7 @@ enum ConnectResourceEvent {
   CONNECT_RESOURCE_EVENT_DELETE = 3;
   CONNECT_RESOURCE_EVENT_CREATE_CHILD = 4;
   CONNECT_RESOURCE_EVENT_DELETE_CHILD = 5;
+  CONNECT_RESOURCE_EVENT_DATABASE_WRITE = 6;
 }
 
 message ConnectResource {
@@ -363,12 +449,18 @@ message ConnectAuthRequest {
   uint64 timestamp = 7;
 }
 
+message ConnectDIDRegistryUpdate {
+  DIDRegistryUpdate update = 1;
+}
+
 message ConnectEvent {
   oneof event {
     ConnectAuthRequest connect_auth_request = 1;
 
     // A resource event notification, such as updated or deleted.
     ConnectResource connect_resource = 2;
+
+    ConnectDIDRegistryUpdate did_registry_update = 3;
   }
 }
 
@@ -620,6 +712,8 @@ message GetParametersResponse {
 
 // This an empty message.
 message GetPolicyRequest {
+  // Set to only retrieve the custom policy document.
+  bool custom_policy = 1;
 }
 
 message GetPolicyResponse {
@@ -771,10 +865,9 @@ message InvokeRequest {
   // 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.
+  // The DID of the target identity hosting the service.
   // This is used by Relays to route the request.
-  // 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;
+  repeated string target_did = 3;
 
   oneof request_payload {
     // A serialised and encrypted instance of `RemoteResponse` in pure binary format.
@@ -916,6 +1009,17 @@ message SaveIdentityRequest {
 
   // Reserved for system use.
   string create_in_parent_id = 4;
+
+  // Set to indicate the identity aliases should be purged before saving the identity.
+  // If the `identity` field contains aliases they will be saved after the purge.
+  // If the `identity` field does not contain aliases this effectively deletes all aliases for this identity.
+  // This allows you to selectively update aliases if required, i.e. don't set this flag and include a single alias in the update.
+  bool purge_aliases = 5;
+
+  string did_document = 6;
+
+  // The signature of the identity did document, if present.
+  string did_update_signature = 7;
 }
 
 message SaveIdentityResponse {
@@ -985,19 +1089,13 @@ message SaveSessionResponse {
   Session session = 2;
 }
 
-message SessionRequest {
-  string session_id = 1;
-  oneof payload {
-    string fingerprint = 2;
-    string signature = 3;
-  }
+message SetPolicyRequest {
+  string custom_policy = 1;
 }
 
-message SessionResponse {
+message SetPolicyResponse {
   // 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 {

package/src/constants.js

@@ -4,37 +4,37 @@ export const constants = {
   collectionOperation: {
     add: "ADD",
     remove: "REMOVE",
-    update: "UPDATE",
+    update: "UPDATE"
   },
   crypto: {
     subjectDefaults: [
       {
         name: "countryName",
-        value: "GB",
+        value: "GB"
       },
       {
         name: "localityName",
-        value: "Southampton",
+        value: "Southampton"
       },
       {
         name: "organizationName",
-        value: "nquiringminds Ltd",
-      },
+        value: "nquiringminds Ltd"
+      }
     ],
-    userIdOID: "0.9.2342.19200300.100.1.1",
+    userIdOID: "0.9.2342.19200300.100.1.1"
   },
   defaultDIDHostName: "cloud.tdxvolt.com",
   didServiceType: {
-    voltConfig: "tdx-volt-config",
+    voltConfig: "tdx-volt-config"
   },
   identityType: {
     did: "did",
-    volt: "volt",
+    volt: "volt"
   },
   onlineStatus: {
     offline: "offline",
     online: "online",
-    unknown: "unknown",
+    unknown: "unknown"
   },
   publicKeyPrefix: "-----BEGIN PUBLIC KEY-----",
   privateKeyPrefix: "-----BEGIN RSA PRIVATE KEY-----",
@@ -45,14 +45,14 @@ export const constants = {
     proxy: "proxy",
     proxyView: "proxy-view",
     vc: "vc",
-    vcView: "vc-view",
+    vcView: "vc-view"
   },
   voltStatus: {
     pending: "",
     online: "online",
     offline: "offline",
     deleted: "deleted",
-    revoked: "revoked",
+    revoked: "revoked"
   },
   /**
    * These top-level service types should map to a protobuf definition
@@ -62,14 +62,14 @@ export const constants = {
     fileAPI: "tdx.volt_api.volt.v1.FileAPI",
     sqliteServerAPI: "tdx.volt_api.data.v1.SqliteServerAPI",
     sqliteDatabaseAPI: "tdx.volt_api.data.v1.SqliteDatabaseAPI",
-    ssiAPI: "tdx.volt_api.ssi.v1.SsiAPI",
+    ssiAPI: "tdx.volt_api.volt.v1.SsiAPI",
     relayAPI: "tdx.volt_api.relay.v1.RelayAPI",
     voltAPI: "tdx.volt_api.volt.v1.VoltAPI",
-    wireAPI: "tdx.volt_api.volt.v1.WireAPI",
+    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`.
+  tunnelTimeoutInterval: 10000 * 2 // This must always be greater than `tunnelPingInterval`.
 };

package/src/grpc-call.js

@@ -8,7 +8,7 @@ const log = debug("volt-client-grpc:grpc-call");
 function _prepareInvokeRequest(
   request,
   method,
-  methodType = "METHOD_TYPE_UNARY",
+  methodType = "METHOD_TYPE_UNARY"
 ) {
   const isServiceRelayed =
     this._service?.service_description.host_type ===
@@ -21,7 +21,7 @@ function _prepareInvokeRequest(
       this._voltClient.voltConfig.id,
     this._service?.service_description.host_public_key ||
       this._voltClient.credential.voltPublicKey,
-    true,
+    true
   );
 
   let invokeRequest;
@@ -52,42 +52,40 @@ function _prepareInvokeRequest(
         method_name: this._grpcClient[method].path,
         method_type: methodType,
         token: methodToken.token,
-        request: requestPayload,
-      },
+        request: requestPayload
+      }
     };
 
-    let targetFingerprint = [];
+    let targetDID = [];
     let invokePayload;
     if (this._voltClient.isVoltRelay || isServiceRelayed) {
       // When sending via a relay we need to encrypt the payload.
       invokePayload = VoltCredential.aesEncrypt(
         tunnelMethod.responseSerialize(tunnelResp),
         methodToken.sharedKey.key,
-        methodToken.sharedKey.iv,
+        methodToken.sharedKey.iv
       );
     } else {
       invokePayload = tunnelMethod.responseSerialize(tunnelResp);
     }
 
     if (this._voltClient.isVoltRelay) {
-      targetFingerprint.push(this._voltClient.credential.voltFingerprint);
+      targetDID.push(this._voltClient.voltConfig.id);
     }
 
     if (isServiceRelayed) {
       // Add another relay hop if the target service is relayed.
       log("target service is relayed");
-      targetFingerprint.push(
-        this._service.service_description.host_fingerprint,
-      );
+      targetDID.push(this._service.service_description.host_client_id);
     }
 
-    log("target is %j", targetFingerprint);
+    log("target is %j", targetDID);
 
     invokeRequest = {
-      target_fingerprint: targetFingerprint,
+      target_did: targetDID,
       token: methodToken.token,
       payload: invokePayload,
-      target_service_id: isServiceRelayed ? this._service.id : undefined,
+      target_service_id: isServiceRelayed ? this._service.id : undefined
     };
 
     // Replace the target method with a call to Invoke on the relay Volt.
@@ -100,7 +98,7 @@ function _prepareInvokeRequest(
     meta: methodToken,
     method: callMethod,
     methodName: method,
-    request: invokeRequest,
+    request: invokeRequest
   };
 }
 
@@ -120,18 +118,18 @@ function _preparePayloadRequest(request, invokeInfo) {
 
     const tunnelResp = {
       method_payload: {
-        payload: requestPayload,
-      },
+        payload: requestPayload
+      }
     };
 
     const invokePayload = VoltCredential.aesEncrypt(
       tunnelMethod.responseSerialize(tunnelResp),
       invokeInfo.meta.sharedKey.key,
-      invokeInfo.meta.sharedKey.iv,
+      invokeInfo.meta.sharedKey.iv
     );
 
     payloadRequest = {
-      payload: invokePayload,
+      payload: invokePayload
     };
   } else {
     payloadRequest = request;
@@ -155,7 +153,7 @@ function _parseResponse(method, meta, response) {
         decryptedPayload = VoltCredential.aesDecrypt(
           response.payload,
           meta.sharedKey.key,
-          meta.sharedKey.iv,
+          meta.sharedKey.iv
         );
       } else {
         decryptedPayload = response.payload;
@@ -166,12 +164,12 @@ function _parseResponse(method, meta, response) {
       if (responsePayload.payload === "method_payload") {
         try {
           invokeResponse.payload = this._grpcClient[method].responseDeserialize(
-            responsePayload.method_payload.payload,
+            responsePayload.method_payload.payload
           );
         } catch (err) {
           log("failure deserialising payload for %s", this._methodName);
           throw new Error(
-            "failure deserialising payload - check protobuf definition matches with data being sent",
+            "failure deserialising payload - check protobuf definition matches with data being sent"
           );
         }
       } else if (responsePayload.payload === "method_end") {
@@ -185,11 +183,11 @@ function _parseResponse(method, meta, response) {
         "Tunnel status received: %s, code %d, description: %s",
         response.status.message,
         response.status.code,
-        response.status.description || "n/a",
+        response.status.description || "n/a"
       );
       invokeResponse = {
         ended: true,
-        error: `Error in tunnel: ${response.status.message}`,
+        error: `Error in tunnel: ${response.status.message}`
       };
     } else {
       invokeResponse.methodId = response.invoke_id;
@@ -199,11 +197,11 @@ function _parseResponse(method, meta, response) {
     const decryptedPayload = VoltCredential.aesDecrypt(
       response,
       meta.sharedKey.key,
-      meta.sharedKey.iv,
+      meta.sharedKey.iv
     );
     invokeResponse = {
       payload:
-        this._grpcClient[method].responseDeserializeOriginal(decryptedPayload),
+        this._grpcClient[method].responseDeserializeOriginal(decryptedPayload)
     };
   } else {
     invokeResponse = { payload: response };
@@ -233,7 +231,7 @@ export default class GRPCCall extends EventEmitter {
       this,
       request,
       this._methodName,
-      this._methodType,
+      this._methodType
     );
 
     const isServiceRelayed =
@@ -248,7 +246,7 @@ export default class GRPCCall extends EventEmitter {
     }
 
     this._call = callClient[this._initialRequest.method](
-      this._initialRequest.meta.metadata,
+      this._initialRequest.meta.metadata
     );
 
     this._call.on("data", (streamResponse) => {
@@ -257,14 +255,14 @@ export default class GRPCCall extends EventEmitter {
           this,
           this._methodName,
           this._initialRequest.meta,
-          streamResponse,
+          streamResponse
         );
         if (parsedResponse.payload) {
           // Interpret a non-empty status message as an error.
           if (parsedResponse.payload?.status?.message) {
             this.emit(
               "error",
-              new Error(parsedResponse.payload.status.message),
+              new Error(parsedResponse.payload.status.message)
             );
           } else {
             this.emit("data", parsedResponse.payload);
@@ -283,7 +281,7 @@ export default class GRPCCall extends EventEmitter {
         log(
           "failure processing %s call response: %s",
           this._methodName,
-          err.message,
+          err.message
         );
         this.emit("error", err);
       }
@@ -305,7 +303,7 @@ export default class GRPCCall extends EventEmitter {
       log(
         "ended call %s, method id: %s",
         this._methodName,
-        this._initialRequest.methodId || "n/a - not tunnelling",
+        this._initialRequest.methodId || "n/a - not tunnelling"
       );
       this.emit("end");
     });
@@ -338,7 +336,7 @@ export default class GRPCCall extends EventEmitter {
       const payloadRequest = _preparePayloadRequest.call(
         this,
         request,
-        this._initialRequest,
+        this._initialRequest
       );
       return this._call.write(payloadRequest);
     } else {
@@ -346,7 +344,7 @@ export default class GRPCCall extends EventEmitter {
         this,
         request,
         this._methodName,
-        this._methodType,
+        this._methodType
       );
 
       return this._call.write(this._initialRequest.request);

package/src/utils.js

@@ -64,11 +64,16 @@ export const createPublicKeyFingerprint = (key) => {
   return createBase58Hash(removeCarriageReturn(key));
 };
 
+export const base64ToBase64Url = (base64) => {
+  return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+};
+
 export const signBase64 = (key, msg) => {
   const md = forge.md.sha256.create();
   md.update(msg);
   const signature = key.sign(md);
-  return forge.util.encode64(signature);
+  const base64Standard = forge.util.encode64(signature);
+  return base64ToBase64Url(base64Standard);
 };
 
 export const verifyBase64 = (key, msg, signature) => {
@@ -137,10 +142,25 @@ export const createRSAKey = (passphrase = "") => {
 export const sha256Base64 = (msg) => {
   const md = forge.md.sha256.create();
   md.update(msg);
-  return forge.util.encode64(md.digest().bytes());
+  const base64Standard = forge.util.encode64(md.digest().bytes());
+  return base64ToBase64Url(base64Standard);
 };
 
 export const decryptPrivateKey = (pem, passphrase) => {
   const decryptedKey = pki.decryptRsaPrivateKey(pem, passphrase);
   return forgePrivateKeyToPem(decryptedKey);
 };
+
+export const jwsSignature = (signature) => {
+  //
+  // Use an unattached payload JWS signature for the DID document proof.
+  // This is a JWS with an empty payload and a detached payload digest.
+  //
+  // (https://tools.ietf.org/html/rfc7797#appendix-F) as used in the VC spec
+  // (https://www.w3.org/TR/vc-data-model/).
+  //
+  const jwsHeader = base64ToBase64Url(
+    forge.util.encode64('{"alg":"RS256","b64": false}')
+  );
+  return jwsHeader + ".." + signature;
+};