@tdxvolt/volt-client-grpc 0.20.8 → 0.20.11

package/lib/index.cjs

@@ -10,6 +10,7 @@ var debug = require('debug');
 var Protobuf = require('protobufjs');
 var camelCase = require('lodash.camelcase');
 var descriptor = require('protobufjs/ext/descriptor/index.js');
+var voltUtility = require('@tdxvolt/volt-utility');
 var EventEmitter = require('events');
 var fs = require('fs');
 var path = require('path');
@@ -135,12 +136,14 @@ function createClient(
   address,
   credentials,
   noSerialise,
-  voltId,
-  serviceId
+  voltId = "",
+  serviceId = ""
 ) {
   let grpcCredentials;
   if (credentials) {
-    const relaying = !!credentials.config?.volt?.relay && !Array.isArray(credentials.config?.volt?.relay);
+    const relaying =
+      !!credentials.config?.volt?.relay &&
+      !Array.isArray(credentials.config?.volt?.relay);
     const ca = relaying
       ? credentials.config?.volt?.relay?.ca_pem
       : credentials.cache.ca;
@@ -1263,128 +1266,6 @@ message RemoteResponse {
     HttpRequest http_request = 5;
   }
 }
-`;
-const spark_api = `syntax = "proto3";
-
-package tdx.volt_api.volt.v1;
-
-import "tdx/volt_api/volt/v1/status.proto";
-
-// The Spark API allows clients to start and communicate with Spark VMs.
-service SparkAPI {
-  // Start or connect to a spark VM and establish a long-lived communication channel.
-  rpc Spark(stream SparkRequest) returns (stream SparkResponse);
-
-  // Get details of running spark VMs.
-  rpc GetSpark(GetSparkRequest) returns (GetSparkResponse);
-}
-
-// Start a resource-hosted spark.
-// Provenance is determined from the resource owner.
-message StartSparkResource {
-  // The id of the resource containing the VM byte code.
-  string resource_id = 1;
-
-  // JSON-encoded payload to parameterise the spark.
-  string payload = 2;
-
-  // Envelope signature.
-  string signature = 3;
-}
-
-// Start a spark from byte code included in the payload, along with issuer/developer claims and signature.
-message StartSparkAdhoc {
-  // Ad-hoc byte code of VM to run.
-  bytes byte_code = 1;
-
-  // Verifiable credentials associated with this spark.
-  repeated string credential = 2;
-
-  // Envelope signature.
-  string signature = 3;
-
-  // JSON-encoded payload to parameterise the spark.
-  string payload = 4;
-}
-
-// Send commands and payloads to communicate with a running spark.
-message SparkCommand {
-  // Optional id to associate with this command.
-  // If this is omitted, an id will be assigned and returned in the command acknowledgement.
-  string command_id = 1;
-
-  // The command to send to the spark.
-  string command = 2;
-
-  // The command payload.
-  string payload = 3;
-
-  // Command verifiable credential.
-  string credential = 4;
-
-  // Command signature.
-  string signature = 5;
-}
-
-// The request must contain one of the messages indicated below.
-message SparkRequest {
-  oneof payload {
-    StartSparkResource start_resource = 1;
-    StartSparkAdhoc start_adhoc = 2;
-    SparkCommand command = 3;
-  }
-}
-
-// Receive events and payload from a running spark.
-message SparkData {
-  // The command id to which this data corresponds.
-  string command_id = 1;
-
-  oneof payload {
-    // Acknowledges receipt of a spark command.
-    bool acknowledge = 2;
-
-    // Indicates the command has completed.
-    bool ended = 3;
-
-    // Will contain error details on command failure.
-    string error = 4;
-
-    // Data emitted by a command, usually in stringified JSON format.
-    string data = 5;
-  }
-}
-
-// Details of a spark instance.
-message SparkInstance {
-  // The UUID assigned to the spark instance.
-  string spark_id = 1;
-}
-
-// The response will contain one of the messages indicated below.
-message SparkResponse {
-  oneof payload {
-    // Details of any error that occurred on the call.
-    tdx.volt_api.volt.v1.Status status = 1;
-
-    // Details of the spark instance, sent in response to a start command.
-    SparkInstance spark_instance = 2;
-
-    // Payload data emitted by the spark.
-    SparkData spark_data = 3;
-  }
-}
-
-message GetSparkRequest {
-  string spark_id = 1;
-}
-
-// One of the following fields will be present in the response.
-message GetSparkResponse {
-  // Details of any error that occurred on the call.
-  tdx.volt_api.volt.v1.Status status = 1;
-}
-
 `;
 const ssi = `syntax = "proto3";
 
@@ -1460,12 +1341,11 @@ const ssi_api = `syntax = "proto3";
 
 package tdx.volt_api.volt.v1;
 
-import "tdx/volt_api/volt/v1/status.proto";
 import "tdx/volt_api/volt/v1/ssi.proto";
+import "tdx/volt_api/volt/v1/status.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);
+  rpc CacheEmailCredential(CacheEmailCredentialRequest) returns (CacheEmailCredentialResponse);
 
   // Delete a DID document or all DID documents originating from a given Volt.
   // Requires \`volt:delete-did\` API privilege.
@@ -1496,20 +1376,25 @@ service SsiAPI {
   rpc SearchDIDRegistry(SearchDIDRegistryRequest) returns (SearchDIDRegistryResponse);
 }
 
-message CreateExchangeTokenRequest {
-  // The VC template to use to create a verifiable credential.
-  string vc_template = 1;
+message CacheEmailCredentialRequest {
+  string identity_did = 1;
+
+  string email_address = 2;
+
+  string identity_provider = 3;
+
+  string key_passphrase = 4;
 
   // The time to live for the token, in seconds.
-  uint32 ttl = 2;
+  uint32 ttl = 5;
 }
 
-message CreateExchangeTokenResponse {
+message CacheEmailCredentialResponse {
   // Details of any error that occurred on the call.
   tdx.volt_api.volt.v1.Status status = 1;
 
-  // The one-time token.
-  string token = 2;
+  // The verifiable credential resource id.
+  string vc_id = 2;
 }
 
 message DeleteDIDRequest {
@@ -1726,6 +1611,7 @@ enum SyncState {
   SYNC_STATE_SYNCING = 1;
   SYNC_STATE_DONE = 2;
   SYNC_STATE_UPDATE = 3;
+  SYNC_STATE_AWARENESS = 4;
 }
 
 message SyncDocumentStart {
@@ -1794,7 +1680,8 @@ message GetDocumentJSONResponse {
     // The current JSON snapshot of the document
     string json = 2;
   }
-}`;
+}
+`;
 const terminal_api = `syntax = "proto3";
 
 package tdx.volt_api.volt.v1;
@@ -2709,7 +2596,7 @@ message AuthenticateRequest {
   // A human-readable name of the entity requesting to authenticate.
   string client_name = 6;
 
-  // Optional challenge code, hashed using SHA-256 and base64 encoded.
+  // Optional challenge code, hashed using SHA-256 and base64 URL encoded (no padding).
   string challenge = 7;
 
   // The host name to add as a SAN to the issued certificate.
@@ -2737,7 +2624,7 @@ message AuthenticateResponse {
   // This should be persisted by the client, and submitted with all subsequent API calls as part of the call metadata.
   string session_id = 2;
 
-  // The identity id assigned to this authentication.
+  // The 'primary' session identity assigned to this authentication. This will be the DID in DID-based sessions, otherwise it will be the first email-based credential found, if any, otherwise it will be the public key fingerprint.
   string identity_did = 3;
 
   // A certificate issued by the volt CA, binding the request public key to the identity.
@@ -2793,6 +2680,9 @@ message CanAccessResourceResponse {
 
   // The policy decision for this access request.
   PolicyDecision decision = 6;
+
+  // The session that the access relates to.
+  string session_id = 7;
 }
 
 message  CheckCompatibilityRequest {
@@ -3138,6 +3028,9 @@ message GetIdentityResponse {
 message GetOneTimeTokenRequest {
   // Optional token TTL, in seconds. Default is 10 seconds.
   int32 ttl = 1;
+
+  // Optional token context.
+  string context = 2;
 }
 
 message GetOneTimeTokenResponse {
@@ -3200,6 +3093,9 @@ message GetResourceResponse {
 message GetResourcesRequest {
   repeated string id = 1;
 
+  // Wildcards permitted.
+  repeated string alias = 16;
+
   // Wildcards permitted.
   repeated string name = 2;
 
@@ -3716,7 +3612,7 @@ message SubscribeWireResponse {
 }
 
 `;
-const voltProtos = [sqlite, sqlite_database_api, sqlite_server_api, proto_db_sync, proxy_api, relay_api, discovery_api, file, file_api, remote, spark_api, ssi, ssi_api, status, sync_api, terminal_api, volt, volt_api, wire_api];
+const voltProtos = [sqlite, sqlite_database_api, sqlite_server_api, proto_db_sync, proxy_api, relay_api, discovery_api, file, file_api, remote, ssi, ssi_api, status, sync_api, terminal_api, volt, volt_api, wire_api];
 
 debug__default["default"]("volt-client-grpc:proto-utils");
 
@@ -4137,11 +4033,6 @@ class GRPCCall extends EventEmitter__default["default"] {
     );
 
     this._call.on("data", (streamResponse) => {
-      if (this._ended) {
-        log$5("ignoring data after end on %s", this._methodName);
-        return;
-      }
-
       try {
         const parsedResponse = _parseResponse.call(
           this,
@@ -4149,6 +4040,13 @@ class GRPCCall extends EventEmitter__default["default"] {
           this._initialRequest.meta,
           streamResponse
         );
+
+        if (this._ended && !parsedResponse.ended) {
+          log$5("ignoring data after end on %s", this._methodName);
+          log$5(parsedResponse);
+          return;
+        }
+
         if (parsedResponse.key_exchange) {
           const peerKey = keyFromPem$2(
             parsedResponse.key_exchange.encryption_key
@@ -4180,9 +4078,6 @@ class GRPCCall extends EventEmitter__default["default"] {
         } else if (parsedResponse.ended) {
           if (parsedResponse.error) {
             this.emit("error", new Error(parsedResponse.error));
-          } else {
-            // Not sure this is necessary - we should receive "end" from grpc soon...
-            this.emit("end");
           }
         } else {
           log$5("method id is %s", parsedResponse.methodId);
@@ -4658,6 +4553,7 @@ function _cleanUp(immediateReconnect) {
   }
 
   if (this._dying) {
+    log$3("dying - clearing reconnect timer");
     clearTimeout(this._reconnectTimer);
   } else if (immediateReconnect || (this._autoRetry && !this._reconnectTimer)) {
     this._reconnectTimer = setTimeout(
@@ -4670,6 +4566,7 @@ function _cleanUp(immediateReconnect) {
   }
 
   if (this.call?.writable) {
+    log$3("ending Connect call");
     this.call.end();
   }
 }
@@ -4760,9 +4657,7 @@ function _doConnect(connectHello) {
   });
 
   this.call.on("end", () => {
-    if (this._connectionId) {
-      this.emit("connected", false);
-    }
+    this.emit("connected", false);
     _cleanUp.call(this);
   });
 
@@ -4844,8 +4739,6 @@ class VoltConnection extends EventEmitter__default["default"] {
 
 const { publicKeyToPem: publicKeyToPem$1, removeCarriageReturn, signBase64 } = js.voltUtils;
 
-const { filter, pick } = lodash__default["default"];
-
 const log$2 = debug__default["default"]("volt-client-grpc:volt-client-internal");
 
 function issueAuthenticate(authenticateRequest, ttl) {
@@ -4918,15 +4811,6 @@ function issueAuthenticate(authenticateRequest, ttl) {
     });
 }
 
-function findDIDDocumentService(document, serviceType) {
-  if (!document.service) {
-    return [];
-  }
-
-  const matches = filter(document.service, (svc) => svc.type === serviceType);
-  return matches;
-}
-
 async function authenticateInternal(
   noDID = false,
   ownDID = false,
@@ -5103,18 +4987,18 @@ function connectInternal(helloPayload) {
     this._voltConnection.on("connected", (session) => {
       this._session = session;
       this._connected = !!session;
+      this.emit("connected", session);
       if (!this._connected) {
         onDisconnected();
       }
-      this.emit("connected", session);
     });
 
     this._voltConnection.on("error", (err) => {
       // Should auto-reconnect.
       log$2("Volt connection error [%s]", err.message);
       if (this._connected) {
-        onDisconnected();
         this.emit("connected", false);
+        onDisconnected();
       }
 
       if (err.message.endsWith("session invalid")) {
@@ -5189,7 +5073,11 @@ function getVoltAPIClientInternal() {
     const serviceAddress = this.isRelayed
       ? this._voltConfig.relay.address
       : this._voltConfig.address;
-    log$2("creating cached VoltAPI service client on %s", serviceAddress);
+    log$2(
+      "creating cached VoltAPI service client on %s for %j",
+      serviceAddress,
+      this._voltConfig
+    );
 
     const serviceDescriptors = getBuiltInServiceDescriptors();
 
@@ -5198,9 +5086,7 @@ function getVoltAPIClientInternal() {
       serviceDescriptors,
       serviceAddress,
       this._credential,
-      this.isRelayed,
-      this._voltConfig?.relay?.cloud ? this._voltConfig.id : "",
-      this._voltConfig?.relay?.cloud ? this._voltConfig.id : ""
+      this.isRelayed
     );
   }
 
@@ -5285,211 +5171,6 @@ function streamingCallInternal(methodType, method, request, service) {
   return call;
 }
 
-async function fetchVoltConfig(discovery_url) {
-  try {
-    const response = await fetch(discovery_url);
-
-    if (!response.ok) {
-      log$2("fetchVoltConfig - error [%s]", response.status);
-      return null;
-    }
-
-    const fullVoltConfig = await response.json();
-
-    if (!fullVoltConfig || typeof fullVoltConfig !== "object") {
-      log$2("fetchVoltConfig - invalid config resolved from: %s", discovery_url);
-      return null;
-    }
-
-    const voltConfig = pick(
-      fullVoltConfig,
-      "id",
-      "display_name",
-      "public_key",
-      "fingerprint",
-      "address",
-      "http_address",
-      "ca_pem",
-      "relay"
-    );
-
-    log$2("fetchVoltConfig from %s", discovery_url);
-
-    return voltConfig;
-  } catch (err) {
-    log$2("fetchVoltConfig - %s error [%s]", discovery_url, err.message);
-    return null;
-  }
-}
-
-async function fetchVoltConfigFromDIDInternal(volt_did, registryUrl) {
-  try {
-    const didResolution = getDIDResolutionURL(volt_did, registryUrl);
-    if (!didResolution) {
-      throw new Error(`Invalid Volt DID: ${volt_did}`);
-    }
-
-    const response = await fetch(didResolution);
-
-    if (!response.ok) {
-      throw new Error(`HTTP error, status: ${response.status}`);
-    }
-
-    const didDocument = await response.json();
-    const voltConfigServices = findDIDDocumentService(
-      didDocument,
-      constants.didServiceType.voltConfig
-    );
-    if (voltConfigServices.length !== 1) {
-      log$2(
-        "Unexpected number of Volt configuration endpoints found in DID document for %s, services found: %d",
-        volt_did,
-        voltConfigServices.length
-      );
-    }
-
-    log$2("resolved DID from %s", didResolution);
-
-    const serviceEndpoint = voltConfigServices[0].serviceEndpoint;
-    const voltConfig = await fetchVoltConfig.call(this, serviceEndpoint);
-    if (!voltConfig) {
-      throw new Error(`failed to resolve Volt config from ${serviceEndpoint}`);
-    }
-
-    return voltConfig;
-  } catch (err) {
-    throw new Error(
-      `Failure fetching Volt config from DID document ${volt_did}: ${err.message}`
-    );
-  }
-}
-
-async function fetchVoltConfigFromDID(volt_did, registryListIn) {
-  let registryList;
-  if (!registryListIn) {
-    //  If no registry list is provided, use the default registry list.
-    registryList = constants.defaultRegistryList;
-  } else {
-    // If a registry list is provided, merge it with the default registry list.
-    registryList = Array.from(
-      new Set(registryListIn.concat(constants.defaultRegistryList))
-    );
-  }
-
-  let voltConfig;
-  for (let registryUrl of registryList) {
-    try {
-      voltConfig = await fetchVoltConfigFromDIDInternal.call(
-        this,
-        volt_did,
-        registryUrl
-      );
-
-      // If we've found a config, break out of the loop.
-      break;
-    } catch (err) {
-      log$2("unable to fetch Volt config from %s: %s", registryUrl, err.message);
-    }
-  }
-
-  if (!voltConfig) {
-    log$2("failed to fetch Volt config for %s from any registry", volt_did);
-  }
-
-  return voltConfig;
-}
-
-async function resolveVoltConfig(cfg, didRegistryList) {
-  // Start by resolving the relay if one is specified.
-  let relay = cfg?.relay?.http_address || cfg?.relay;
-  if (relay) {
-    relay = await resolveVoltConfig.call(this, relay, didRegistryList);
-  }
-
-  let voltDID = "";
-  let voltHttpAddress = "";
-
-  if (typeof cfg === "string") {
-    // If the configuration is a string, determine if it is a DID or HTTP address.
-    if (cfg.indexOf("did:") === 0) {
-      voltDID = cfg;
-    } else {
-      voltHttpAddress = cfg;
-    }
-    cfg = {};
-  } else if (typeof cfg === "object") {
-    voltDID = cfg.id;
-    voltHttpAddress = cfg.http_address;
-  } else {
-    throw new Error("configuration is missing the 'volt' object");
-  }
-
-  let resolvedConfig;
-
-  if (relay) {
-    if (!voltDID) {
-      throw new Error("relay specified but no Volt DID provided");
-    }
-
-    // Build the sub-domain URL for the Volt discovery service by inserting the volt DID into the relay URL.
-    const relayURL = relay.http_address;
-    const relayParts = relayURL.split("://");
-    const subdomain = voltDID.substring(constants.voltDIDPrefix.length);
-    voltHttpAddress = `${relayParts[0]}://${subdomain}.${relayParts[1]}`;
-  } else if (voltDID) {
-    resolvedConfig = await fetchVoltConfigFromDID.call(
-      this,
-      voltDID,
-      didRegistryList
-    );
-  }
-
-  if (!resolvedConfig && voltHttpAddress) {
-    try {
-      resolvedConfig = await fetchVoltConfig.call(
-        this,
-        `${voltHttpAddress}/discover`
-      );
-
-      // Update the http address in the resolved config to the one we used to
-      // fetch it, since we may have used the relay rather than local address.
-      resolvedConfig.http_address = voltHttpAddress;
-    } catch (err) {
-      log$2(
-        "failed to resolve Volt configuration %s [%s]",
-        voltHttpAddress,
-        err.message
-      );
-    }
-  }
-
-  if (!resolvedConfig) {
-    if (cfg.address && cfg.ca_pem) {
-      log$2(
-        "unable to resolve %s / %s, using existing configuration",
-        voltDID,
-        voltHttpAddress
-      );
-    } else {
-      throw new Error(
-        `failed to resolve Volt ${voltDID} / ${voltHttpAddress} and no existing configuration`
-      );
-    }
-  } else {
-    log$2("resolved config from: %s", voltDID || voltHttpAddress);
-    log$2(JSON.stringify(resolvedConfig, null, 2));
-
-    cfg = {
-      ...cfg,
-      ...resolvedConfig
-    };
-  }
-
-  cfg.relay = relay;
-
-  return cfg;
-}
-
 /* eslint-disable no-underscore-dangle */
 
 const {
@@ -5746,10 +5427,19 @@ class VoltClient extends EventEmitter__default["default"] {
    * instead of a DID-based authentication session.
    * @param {string} [options.exchangeToken] - optional token to exchange in return for an authenticated session.
    * @param {boolean} [options.waitForAuth] - whether to block and poll on 'prompt' authenticate decisions. Default is true.
+   * @param {boolean} [options.noResolve] - whether to skip resolving the Volt configuration. Default is false.
    */
   async initialise(config, options = {}) {
-    const { ownDID, noDID, didRegistryList, exchangeToken, extraConfig } =
-      options;
+    log("initialise ", config, options);
+
+    const {
+      ownDID,
+      noDID,
+      didRegistryList,
+      exchangeToken,
+      extraConfig,
+      noResolve
+    } = options;
     const waitForAuth =
       options.waitForAuth === undefined ? true : !!options.waitForAuth;
 
@@ -5799,14 +5489,17 @@ class VoltClient extends EventEmitter__default["default"] {
         throw new Error("client_name property required in config");
       }
 
-      this._config.volt = await resolveVoltConfig.call(
-        this,
-        this._config.volt,
-        didRegistryList
-      );
+      if (!noResolve) {
+        this._config.volt = await voltUtility.resolveVoltConfig(
+          this._config.volt,
+          didRegistryList
+        );
+      }
 
       this._voltConfig = this._config.volt;
 
+      log("config is ", this._voltConfig);
+
       if (!this._voltConfig.id || typeof this._voltConfig.id !== "string") {
         throw new Error("'id' property is missing in Volt configuration");
       }
@@ -5864,7 +5557,7 @@ class VoltClient extends EventEmitter__default["default"] {
         this._credential.saveCache();
       }
 
-      return Promise.resolve(this._config);
+      return Promise.resolve(this.credential.config);
     } catch (err) {
       log("failure starting Volt client [%s]", err.message);
       throw err;

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.20.8",
+  "version": "0.20.11",
   "description": "tdx Volt library for nodejs clients",
   "type": "module",
   "exports": {
@@ -33,7 +33,8 @@
   "author": "toby.ealden@gmail.com",
   "license": "ISC",
   "dependencies": {
-    "@tdxvolt/volt-client-web": "^0.20.8",
+    "@tdxvolt/volt-client-web": "^0.20.10",
+    "@tdxvolt/volt-utility": "^0.20.10",
     "debug": "^4.1.1",
     "ip": "^1.1.5",
     "jsonwebtoken": "^8.5.1",

package/src/grpc-call.js

@@ -361,11 +361,6 @@ export default class GRPCCall extends EventEmitter {
     );
 
     this._call.on("data", (streamResponse) => {
-      if (this._ended) {
-        log("ignoring data after end on %s", this._methodName);
-        return;
-      }
-
       try {
         const parsedResponse = _parseResponse.call(
           this,
@@ -373,6 +368,13 @@ export default class GRPCCall extends EventEmitter {
           this._initialRequest.meta,
           streamResponse
         );
+
+        if (this._ended && !parsedResponse.ended) {
+          log("ignoring data after end on %s", this._methodName);
+          log(parsedResponse);
+          return;
+        }
+
         if (parsedResponse.key_exchange) {
           const peerKey = keyFromPem(
             parsedResponse.key_exchange.encryption_key
@@ -404,9 +406,6 @@ export default class GRPCCall extends EventEmitter {
         } else if (parsedResponse.ended) {
           if (parsedResponse.error) {
             this.emit("error", new Error(parsedResponse.error));
-          } else {
-            // Not sure this is necessary - we should receive "end" from grpc soon...
-            this.emit("end");
           }
         } else {
           log("method id is %s", parsedResponse.methodId);

package/src/grpc-utils.js

@@ -15,12 +15,14 @@ export function createClient(
   address,
   credentials,
   noSerialise,
-  voltId,
-  serviceId
+  voltId = "",
+  serviceId = ""
 ) {
   let grpcCredentials;
   if (credentials) {
-    const relaying = !!credentials.config?.volt?.relay && !Array.isArray(credentials.config?.volt?.relay);
+    const relaying =
+      !!credentials.config?.volt?.relay &&
+      !Array.isArray(credentials.config?.volt?.relay);
     const ca = relaying
       ? credentials.config?.volt?.relay?.ca_pem
       : credentials.cache.ca;

package/src/volt-client-internal.js

@@ -4,7 +4,6 @@ import debug from "debug";
 import ip from "ip";
 import lodash from "lodash";
 import { v4 as generateId } from "uuid";
-import { constants } from "./constants.js";
 import GRPCCall from "./grpc-call.js";
 import { createClient as createGrpcClient } from "./grpc-utils.js";
 import {
@@ -12,7 +11,6 @@ import {
   getServiceDescriptors
 } from "./proto-utils.js";
 import RpcInvocation from "./rpc-invocation.js";
-import * as voltUtils from "./utils.js";
 import VoltConnection from "./volt-connection.js";
 
 const { publicKeyToPem, removeCarriageReturn, signBase64 } = voltClientUtils;
@@ -91,15 +89,6 @@ function issueAuthenticate(authenticateRequest, ttl) {
     });
 }
 
-function findDIDDocumentService(document, serviceType) {
-  if (!document.service) {
-    return [];
-  }
-
-  const matches = filter(document.service, (svc) => svc.type === serviceType);
-  return matches;
-}
-
 export async function authenticateInternal(
   noDID = false,
   ownDID = false,
@@ -276,18 +265,18 @@ export function connectInternal(helloPayload) {
     this._voltConnection.on("connected", (session) => {
       this._session = session;
       this._connected = !!session;
+      this.emit("connected", session);
       if (!this._connected) {
         onDisconnected();
       }
-      this.emit("connected", session);
     });
 
     this._voltConnection.on("error", (err) => {
       // Should auto-reconnect.
       log("Volt connection error [%s]", err.message);
       if (this._connected) {
-        onDisconnected();
         this.emit("connected", false);
+        onDisconnected();
       }
 
       if (err.message.endsWith("session invalid")) {
@@ -362,7 +351,11 @@ export function getVoltAPIClientInternal() {
     const serviceAddress = this.isRelayed
       ? this._voltConfig.relay.address
       : this._voltConfig.address;
-    log("creating cached VoltAPI service client on %s", serviceAddress);
+    log(
+      "creating cached VoltAPI service client on %s for %j",
+      serviceAddress,
+      this._voltConfig
+    );
 
     const serviceDescriptors = getBuiltInServiceDescriptors();
 
@@ -371,9 +364,7 @@ export function getVoltAPIClientInternal() {
       serviceDescriptors,
       serviceAddress,
       this._credential,
-      this.isRelayed,
-      this._voltConfig?.relay?.cloud ? this._voltConfig.id : "",
-      this._voltConfig?.relay?.cloud ? this._voltConfig.id : ""
+      this.isRelayed
     );
   }
 
@@ -457,208 +448,3 @@ export function streamingCallInternal(methodType, method, request, service) {
 
   return call;
 }
-
-export async function fetchVoltConfig(discovery_url) {
-  try {
-    const response = await fetch(discovery_url);
-
-    if (!response.ok) {
-      log("fetchVoltConfig - error [%s]", response.status);
-      return null;
-    }
-
-    const fullVoltConfig = await response.json();
-
-    if (!fullVoltConfig || typeof fullVoltConfig !== "object") {
-      log("fetchVoltConfig - invalid config resolved from: %s", discovery_url);
-      return null;
-    }
-
-    const voltConfig = pick(
-      fullVoltConfig,
-      "id",
-      "display_name",
-      "public_key",
-      "fingerprint",
-      "address",
-      "http_address",
-      "ca_pem",
-      "relay"
-    );
-
-    log("fetchVoltConfig from %s", discovery_url);
-
-    return voltConfig;
-  } catch (err) {
-    log("fetchVoltConfig - %s error [%s]", discovery_url, err.message);
-    return null;
-  }
-}
-
-async function fetchVoltConfigFromDIDInternal(volt_did, registryUrl) {
-  try {
-    const didResolution = voltUtils.getDIDResolutionURL(volt_did, registryUrl);
-    if (!didResolution) {
-      throw new Error(`Invalid Volt DID: ${volt_did}`);
-    }
-
-    const response = await fetch(didResolution);
-
-    if (!response.ok) {
-      throw new Error(`HTTP error, status: ${response.status}`);
-    }
-
-    const didDocument = await response.json();
-    const voltConfigServices = findDIDDocumentService(
-      didDocument,
-      constants.didServiceType.voltConfig
-    );
-    if (voltConfigServices.length !== 1) {
-      log(
-        "Unexpected number of Volt configuration endpoints found in DID document for %s, services found: %d",
-        volt_did,
-        voltConfigServices.length
-      );
-    }
-
-    log("resolved DID from %s", didResolution);
-
-    const serviceEndpoint = voltConfigServices[0].serviceEndpoint;
-    const voltConfig = await fetchVoltConfig.call(this, serviceEndpoint);
-    if (!voltConfig) {
-      throw new Error(`failed to resolve Volt config from ${serviceEndpoint}`);
-    }
-
-    return voltConfig;
-  } catch (err) {
-    throw new Error(
-      `Failure fetching Volt config from DID document ${volt_did}: ${err.message}`
-    );
-  }
-}
-
-export async function fetchVoltConfigFromDID(volt_did, registryListIn) {
-  let registryList;
-  if (!registryListIn) {
-    //  If no registry list is provided, use the default registry list.
-    registryList = constants.defaultRegistryList;
-  } else {
-    // If a registry list is provided, merge it with the default registry list.
-    registryList = Array.from(
-      new Set(registryListIn.concat(constants.defaultRegistryList))
-    );
-  }
-
-  let voltConfig;
-  for (let registryUrl of registryList) {
-    try {
-      voltConfig = await fetchVoltConfigFromDIDInternal.call(
-        this,
-        volt_did,
-        registryUrl
-      );
-
-      // If we've found a config, break out of the loop.
-      break;
-    } catch (err) {
-      log("unable to fetch Volt config from %s: %s", registryUrl, err.message);
-    }
-  }
-
-  if (!voltConfig) {
-    log("failed to fetch Volt config for %s from any registry", volt_did);
-  }
-
-  return voltConfig;
-}
-
-export async function resolveVoltConfig(cfg, didRegistryList) {
-  // Start by resolving the relay if one is specified.
-  let relay = cfg?.relay?.http_address || cfg?.relay;
-  if (relay) {
-    relay = await resolveVoltConfig.call(this, relay, didRegistryList);
-  }
-
-  let voltDID = "";
-  let voltHttpAddress = "";
-
-  if (typeof cfg === "string") {
-    // If the configuration is a string, determine if it is a DID or HTTP address.
-    if (cfg.indexOf("did:") === 0) {
-      voltDID = cfg;
-    } else {
-      voltHttpAddress = cfg;
-    }
-    cfg = {};
-  } else if (typeof cfg === "object") {
-    voltDID = cfg.id;
-    voltHttpAddress = cfg.http_address;
-  } else {
-    throw new Error("configuration is missing the 'volt' object");
-  }
-
-  let resolvedConfig;
-
-  if (relay) {
-    if (!voltDID) {
-      throw new Error("relay specified but no Volt DID provided");
-    }
-
-    // Build the sub-domain URL for the Volt discovery service by inserting the volt DID into the relay URL.
-    const relayURL = relay.http_address;
-    const relayParts = relayURL.split("://");
-    const subdomain = voltDID.substring(constants.voltDIDPrefix.length);
-    voltHttpAddress = `${relayParts[0]}://${subdomain}.${relayParts[1]}`;
-  } else if (voltDID) {
-    resolvedConfig = await fetchVoltConfigFromDID.call(
-      this,
-      voltDID,
-      didRegistryList
-    );
-  }
-
-  if (!resolvedConfig && voltHttpAddress) {
-    try {
-      resolvedConfig = await fetchVoltConfig.call(
-        this,
-        `${voltHttpAddress}/discover`
-      );
-
-      // Update the http address in the resolved config to the one we used to
-      // fetch it, since we may have used the relay rather than local address.
-      resolvedConfig.http_address = voltHttpAddress;
-    } catch (err) {
-      log(
-        "failed to resolve Volt configuration %s [%s]",
-        voltHttpAddress,
-        err.message
-      );
-    }
-  }
-
-  if (!resolvedConfig) {
-    if (cfg.address && cfg.ca_pem) {
-      log(
-        "unable to resolve %s / %s, using existing configuration",
-        voltDID,
-        voltHttpAddress
-      );
-    } else {
-      throw new Error(
-        `failed to resolve Volt ${voltDID} / ${voltHttpAddress} and no existing configuration`
-      );
-    }
-  } else {
-    log("resolved config from: %s", voltDID || voltHttpAddress);
-    log(JSON.stringify(resolvedConfig, null, 2));
-
-    cfg = {
-      ...cfg,
-      ...resolvedConfig
-    };
-  }
-
-  cfg.relay = relay;
-
-  return cfg;
-}

package/src/volt-client.js

@@ -1,3 +1,4 @@
+import { resolveVoltConfig } from "@tdxvolt/volt-utility";
 import debug from "debug";
 import EventEmitter from "events";
 import fs from "fs";
@@ -7,7 +8,6 @@ import {
   authenticateInternal,
   connectInternal,
   getVoltAPIClientInternal,
-  resolveVoltConfig,
   streamingCallInternal,
   unaryCallInternal
 } from "./volt-client-internal.js";
@@ -86,10 +86,19 @@ export class VoltClient extends EventEmitter {
    * instead of a DID-based authentication session.
    * @param {string} [options.exchangeToken] - optional token to exchange in return for an authenticated session.
    * @param {boolean} [options.waitForAuth] - whether to block and poll on 'prompt' authenticate decisions. Default is true.
+   * @param {boolean} [options.noResolve] - whether to skip resolving the Volt configuration. Default is false.
    */
   async initialise(config, options = {}) {
-    const { ownDID, noDID, didRegistryList, exchangeToken, extraConfig } =
-      options;
+    log("initialise ", config, options);
+
+    const {
+      ownDID,
+      noDID,
+      didRegistryList,
+      exchangeToken,
+      extraConfig,
+      noResolve
+    } = options;
     const waitForAuth =
       options.waitForAuth === undefined ? true : !!options.waitForAuth;
 
@@ -139,14 +148,17 @@ export class VoltClient extends EventEmitter {
         throw new Error("client_name property required in config");
       }
 
-      this._config.volt = await resolveVoltConfig.call(
-        this,
-        this._config.volt,
-        didRegistryList
-      );
+      if (!noResolve) {
+        this._config.volt = await resolveVoltConfig(
+          this._config.volt,
+          didRegistryList
+        );
+      }
 
       this._voltConfig = this._config.volt;
 
+      log("config is ", this._voltConfig);
+
       if (!this._voltConfig.id || typeof this._voltConfig.id !== "string") {
         throw new Error("'id' property is missing in Volt configuration");
       }
@@ -204,7 +216,7 @@ export class VoltClient extends EventEmitter {
         this._credential.saveCache();
       }
 
-      return Promise.resolve(this._config);
+      return Promise.resolve(this.credential.config);
     } catch (err) {
       log("failure starting Volt client [%s]", err.message);
       throw err;

package/src/volt-connection.js

@@ -20,6 +20,7 @@ function _cleanUp(immediateReconnect) {
   }
 
   if (this._dying) {
+    log("dying - clearing reconnect timer");
     clearTimeout(this._reconnectTimer);
   } else if (immediateReconnect || (this._autoRetry && !this._reconnectTimer)) {
     this._reconnectTimer = setTimeout(
@@ -32,6 +33,7 @@ function _cleanUp(immediateReconnect) {
   }
 
   if (this.call?.writable) {
+    log("ending Connect call");
     this.call.end();
   }
 }
@@ -122,9 +124,7 @@ function _doConnect(connectHello) {
   });
 
   this.call.on("end", () => {
-    if (this._connectionId) {
-      this.emit("connected", false);
-    }
+    this.emit("connected", false);
     _cleanUp.call(this);
   });
 

package/src/volt-proto-literals.js

@@ -718,128 +718,6 @@ message RemoteResponse {
     HttpRequest http_request = 5;
   }
 }
-`;
-export const spark_api = `syntax = "proto3";
-
-package tdx.volt_api.volt.v1;
-
-import "tdx/volt_api/volt/v1/status.proto";
-
-// The Spark API allows clients to start and communicate with Spark VMs.
-service SparkAPI {
-  // Start or connect to a spark VM and establish a long-lived communication channel.
-  rpc Spark(stream SparkRequest) returns (stream SparkResponse);
-
-  // Get details of running spark VMs.
-  rpc GetSpark(GetSparkRequest) returns (GetSparkResponse);
-}
-
-// Start a resource-hosted spark.
-// Provenance is determined from the resource owner.
-message StartSparkResource {
-  // The id of the resource containing the VM byte code.
-  string resource_id = 1;
-
-  // JSON-encoded payload to parameterise the spark.
-  string payload = 2;
-
-  // Envelope signature.
-  string signature = 3;
-}
-
-// Start a spark from byte code included in the payload, along with issuer/developer claims and signature.
-message StartSparkAdhoc {
-  // Ad-hoc byte code of VM to run.
-  bytes byte_code = 1;
-
-  // Verifiable credentials associated with this spark.
-  repeated string credential = 2;
-
-  // Envelope signature.
-  string signature = 3;
-
-  // JSON-encoded payload to parameterise the spark.
-  string payload = 4;
-}
-
-// Send commands and payloads to communicate with a running spark.
-message SparkCommand {
-  // Optional id to associate with this command.
-  // If this is omitted, an id will be assigned and returned in the command acknowledgement.
-  string command_id = 1;
-
-  // The command to send to the spark.
-  string command = 2;
-
-  // The command payload.
-  string payload = 3;
-
-  // Command verifiable credential.
-  string credential = 4;
-
-  // Command signature.
-  string signature = 5;
-}
-
-// The request must contain one of the messages indicated below.
-message SparkRequest {
-  oneof payload {
-    StartSparkResource start_resource = 1;
-    StartSparkAdhoc start_adhoc = 2;
-    SparkCommand command = 3;
-  }
-}
-
-// Receive events and payload from a running spark.
-message SparkData {
-  // The command id to which this data corresponds.
-  string command_id = 1;
-
-  oneof payload {
-    // Acknowledges receipt of a spark command.
-    bool acknowledge = 2;
-
-    // Indicates the command has completed.
-    bool ended = 3;
-
-    // Will contain error details on command failure.
-    string error = 4;
-
-    // Data emitted by a command, usually in stringified JSON format.
-    string data = 5;
-  }
-}
-
-// Details of a spark instance.
-message SparkInstance {
-  // The UUID assigned to the spark instance.
-  string spark_id = 1;
-}
-
-// The response will contain one of the messages indicated below.
-message SparkResponse {
-  oneof payload {
-    // Details of any error that occurred on the call.
-    tdx.volt_api.volt.v1.Status status = 1;
-
-    // Details of the spark instance, sent in response to a start command.
-    SparkInstance spark_instance = 2;
-
-    // Payload data emitted by the spark.
-    SparkData spark_data = 3;
-  }
-}
-
-message GetSparkRequest {
-  string spark_id = 1;
-}
-
-// One of the following fields will be present in the response.
-message GetSparkResponse {
-  // Details of any error that occurred on the call.
-  tdx.volt_api.volt.v1.Status status = 1;
-}
-
 `;
 export const ssi = `syntax = "proto3";
 
@@ -915,12 +793,11 @@ export const ssi_api = `syntax = "proto3";
 
 package tdx.volt_api.volt.v1;
 
-import "tdx/volt_api/volt/v1/status.proto";
 import "tdx/volt_api/volt/v1/ssi.proto";
+import "tdx/volt_api/volt/v1/status.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);
+  rpc CacheEmailCredential(CacheEmailCredentialRequest) returns (CacheEmailCredentialResponse);
 
   // Delete a DID document or all DID documents originating from a given Volt.
   // Requires \`volt:delete-did\` API privilege.
@@ -951,20 +828,25 @@ service SsiAPI {
   rpc SearchDIDRegistry(SearchDIDRegistryRequest) returns (SearchDIDRegistryResponse);
 }
 
-message CreateExchangeTokenRequest {
-  // The VC template to use to create a verifiable credential.
-  string vc_template = 1;
+message CacheEmailCredentialRequest {
+  string identity_did = 1;
+
+  string email_address = 2;
+
+  string identity_provider = 3;
+
+  string key_passphrase = 4;
 
   // The time to live for the token, in seconds.
-  uint32 ttl = 2;
+  uint32 ttl = 5;
 }
 
-message CreateExchangeTokenResponse {
+message CacheEmailCredentialResponse {
   // Details of any error that occurred on the call.
   tdx.volt_api.volt.v1.Status status = 1;
 
-  // The one-time token.
-  string token = 2;
+  // The verifiable credential resource id.
+  string vc_id = 2;
 }
 
 message DeleteDIDRequest {
@@ -1181,6 +1063,7 @@ enum SyncState {
   SYNC_STATE_SYNCING = 1;
   SYNC_STATE_DONE = 2;
   SYNC_STATE_UPDATE = 3;
+  SYNC_STATE_AWARENESS = 4;
 }
 
 message SyncDocumentStart {
@@ -1249,7 +1132,8 @@ message GetDocumentJSONResponse {
     // The current JSON snapshot of the document
     string json = 2;
   }
-}`;
+}
+`;
 export const terminal_api = `syntax = "proto3";
 
 package tdx.volt_api.volt.v1;
@@ -2164,7 +2048,7 @@ message AuthenticateRequest {
   // A human-readable name of the entity requesting to authenticate.
   string client_name = 6;
 
-  // Optional challenge code, hashed using SHA-256 and base64 encoded.
+  // Optional challenge code, hashed using SHA-256 and base64 URL encoded (no padding).
   string challenge = 7;
 
   // The host name to add as a SAN to the issued certificate.
@@ -2192,7 +2076,7 @@ message AuthenticateResponse {
   // This should be persisted by the client, and submitted with all subsequent API calls as part of the call metadata.
   string session_id = 2;
 
-  // The identity id assigned to this authentication.
+  // The 'primary' session identity assigned to this authentication. This will be the DID in DID-based sessions, otherwise it will be the first email-based credential found, if any, otherwise it will be the public key fingerprint.
   string identity_did = 3;
 
   // A certificate issued by the volt CA, binding the request public key to the identity.
@@ -2248,6 +2132,9 @@ message CanAccessResourceResponse {
 
   // The policy decision for this access request.
   PolicyDecision decision = 6;
+
+  // The session that the access relates to.
+  string session_id = 7;
 }
 
 message  CheckCompatibilityRequest {
@@ -2593,6 +2480,9 @@ message GetIdentityResponse {
 message GetOneTimeTokenRequest {
   // Optional token TTL, in seconds. Default is 10 seconds.
   int32 ttl = 1;
+
+  // Optional token context.
+  string context = 2;
 }
 
 message GetOneTimeTokenResponse {
@@ -2655,6 +2545,9 @@ message GetResourceResponse {
 message GetResourcesRequest {
   repeated string id = 1;
 
+  // Wildcards permitted.
+  repeated string alias = 16;
+
   // Wildcards permitted.
   repeated string name = 2;
 
@@ -3171,4 +3064,4 @@ message SubscribeWireResponse {
 }
 
 `;
-export const voltProtos = [sqlite, sqlite_database_api, sqlite_server_api, proto_db_sync, proxy_api, relay_api, discovery_api, file, file_api, remote, spark_api, ssi, ssi_api, status, sync_api, terminal_api, volt, volt_api, wire_api];
+export const voltProtos = [sqlite, sqlite_database_api, sqlite_server_api, proto_db_sync, proxy_api, relay_api, discovery_api, file, file_api, remote, ssi, ssi_api, status, sync_api, terminal_api, volt, volt_api, wire_api];