@tdxvolt/volt-client-grpc 0.1.0

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

@@ -0,0 +1,563 @@
+syntax = "proto3";
+
+package tdx.volt_api.volt.v1;
+
+enum DiscoveryMode {
+  DISCOVERY_MODE_UNKNOWN = 0;
+
+  // Only local identities with explicit policy PERMIT can discover.
+  DISCOVERY_MODE_TRUSTED = 1;
+
+  // Any bound local identity can discover.
+  DISCOVERY_MODE_PUBLIC = 2;
+
+  // Only identities with explicit policy PERMIT can discover, and the service will be available to local and non-local (tunnelled) clients.
+  DISCOVERY_MODE_TRUSTED_GLOBAL = 3;
+
+  // Any bound identity can discover, and the service will be available to local and non-local (tunnelled) clients.
+  DISCOVERY_MODE_PUBLIC_GLOBAL = 4;
+}
+
+enum OnlineStatus {
+  ONLINE_STATUS_UNKNOWN = 0;
+  ONLINE_STATUS_ONLINE = 1;
+  ONLINE_STATUS_OFFLINE = 2;
+}
+
+// @todo currently this must align with AuthorisationDecision enum in policy library, but some of the values are irrelevant outside of the public API so we need a public-facing enum and some translation.
+enum PolicyDecision {
+  POLICY_DECISION_UNKNOWN = 0;
+  POLICY_DECISION_PROMPT = 1;
+  POLICY_DECISION_PERMIT = 2;
+  POLICY_DECISION_DENY = 3;
+  POLICY_DECISION_INDETERMINATE = 4;
+  POLICY_DECISION_NOT_APPLICABLE = 5;
+  POLICY_DECISION_APPLICABLE = 6;
+  POLICY_DECISION_PENDING = 7;
+}
+
+// Not used ATM.
+enum ResourceStatus {
+  RESOURCE_STATUS_UNKNOWN = 0;
+  RESOURCE_STATUS_LIVE = 1;
+  RESOURCE_STATUS_INACTIVE = 2;
+  RESOURCE_STATUS_DELETED = 999;
+}
+
+// Not used ATM.
+enum ShareMode {
+  SHARE_MODE_UNKNOWN = 0;
+  SHARE_MODE_TRUSTED = 1;
+  SHARE_MODE_PUBLIC_READ = 2;
+}
+
+// Represents an outbound connection from a Volt to a remote service that will act as a proxy for that Volt.
+// This enables Volts to bypass firewall and NATs.
+// Example 1 - connection from a Volt to the cloud-based Volt tunnel at volt.tdxcloud.com
+// Example 2 - connection from a Volt to another Volt running on the public internet, such as tdxvolt.com
+message ProxyConnection {
+  // Unique connection id.
+  string id = 1;
+
+  // A human-readable name for the connection.
+  string name = 2;
+
+  // The remote address of the proxy service.
+  string address = 3;
+
+  // The certificate authority of the proxy service.
+  string ca_pem = 4;
+
+  // Indicates this connection is enabled.
+  bool enabled = 5;
+
+  // Indicates this connection is currently in use.
+  bool connected = 6;
+
+  // Indicates this is a connection to a cloud-based tunnel, rather than to another Volt.
+  bool is_cloud_connection = 7;
+
+  // Indicates that this connection will handle HTTP proxying as well as GRPC.
+  bool enable_http_proxy = 8;
+
+  // Set to indicate the Volt API itself is not automatically exposed to the connection.
+  bool disable_volt_api = 9;
+}
+
+enum SecureMode {
+  SECURE_MODE_UNKNOWN = 0;
+  SECURE_MODE_INSECURE = 1;
+  SECURE_MODE_TLS = 2;
+}
+
+// Encapsulates the various Volt parameters that are configurable by the Volt owner.
+message VoltParameters {
+  string id = 1;
+
+  // The name of the Volt.
+  string name = 2;
+
+  // Human-readable description of the Volt.
+  string description = 3;
+
+  // The database driver in use.
+  string db_driver = 4;
+
+  // The local file path location of the Volt storage.
+  string location = 5;
+
+  // The key strategy in use, this determines how the root key is stored.
+  string key_strategy = 6;
+
+  // The identifier for the key, the semantics depend on the key strategy in use.
+  string key_id = 7;
+
+  // The Volt certificate authority.
+  string ca_pem = 8;
+
+  // The Volt API server certificate.
+  string cert_pem = 9;
+
+  // Optional hostname of the Volt if using DNS or a static IP address, e.g. tdxvolt.com
+  string fixed_host = 10;
+
+  // Port to use for hosting the Volt management service.
+  int32 grpc_port = 11;
+
+  // Port to use for hosting the Volt grpc service.
+  int32 http_port = 12;
+
+  // The Volt http server key file path.
+  string http_key_path = 13;
+
+  // The Volt http server certificate file path.
+  string http_cert_path = 14;
+
+  // The Volt http server certificate authority chain file path.
+  string http_ca_path = 15;
+
+  // Indicates the Volt will be discoverable by clients using the discovery api.
+  bool discoverable = 16;
+
+  // Optional base-64 encoded verifiable credential issued by the owner of this Volt.
+  // @Toby - why is this base64 encoded?
+  string owner_credential = 17;
+
+  // Optional challenge code that can be used aid in the process of verifying clients attempting to bind to the Volt.
+  string bind_challenge = 18;
+
+  // Indicates that clients must present the correct challenge code in order to be able to bind to the Volt.
+  bool require_bind_challenge = 19;
+
+  // Internal use only.
+  bool confirm_stop = 20;
+
+  // Internal use only.
+  bool auto_start = 21;
+
+  // Internal use only.
+  bool enable_messaging = 22;
+
+  // Set to indicate this Volt exposes a tunnel interface.
+  // This means this Volt can act as a proxy for other Volts (or in fact any client) that connect to it.
+  bool has_tunnel = 23;
+
+  // Set to run the tunnel open to any client, i.e. clients can utilise the tunnel without binding to this Volt.
+  bool tunnel_open = 24;
+
+  // Determines if the Volt HTTP server is enabled.
+  bool enable_http_server = 25;
+
+  // Determines whether the HTTP server employs TLS.
+  bool http_server_secure = 26;
+
+  // Determines whether the HTTP server supports forwarding.
+  bool enable_http_forwarding = 27;
+
+  // Determines if the Volt REST API is exposed via the HTTP server.
+  bool enable_http_api = 28;
+
+  // Determines if the Volt Websocket API is exposed via the HTTP server.
+  bool enable_websocket_api = 29;
+
+  // The hostname:port at which the Volt API is currently running.
+  string address = 30;
+
+  // Set to indicate the Volt file store is encrypted.
+  bool encrypt_file_store = 31;
+
+  // This is a unique connection id.
+  // Indicates that these parameters refer to a connection to a remote Volt rather than a local Volt.
+  string connection_id = 32;
+
+  // The certificate authority of the tunnel if this is a remote connection via a tunnel.
+  string tunnel_ca_pem = 33;
+
+  // Set to indicate this is a remote connection to a Volt via a cloud tunnel.
+  bool is_cloud_tunnel = 34;
+
+  // An optional alias that can be used to refer to the Volt rather than the `id` field.
+  // This alias must be unique within the scope of the Battery in which the Volt is stored.
+  string alias = 35;
+}
+
+message VoltEndpoint {
+  // The globally unique Volt id.
+  string id = 1;
+
+  // Optional owner credential, base 64 encoded.
+  string owner_credential = 2;
+
+  // Human-readable name of the Volt.
+  string display_name = 3;
+
+  // The actual host/ip the volt is physically running on (might be a local ip if behind firewall).
+  string local_address = 4;
+
+  // The global (tunnel) address of the volt. Any given volt may be advertising on more than one tunnel instance. The value given here will depend on the tunnel instance that handled the endpoint query response.
+  string tunnel_address = 5;
+
+  // The root certificate of the tunnel instance referred to in `tunnel_address`.
+  string tunnel_ca_pem = 6;
+
+  // The self-signed certificate used by the volt to sign client certificates.
+  string ca_pem = 7;
+
+  // The Volt public key in PEM format.
+  string public_key = 8;
+
+  // The base58 fingerprint of the Volt public key.
+  string fingerprint = 9;
+
+  // The online status of the Volt.
+  OnlineStatus online_status = 10;
+
+  // Set to indicate that this Volt exposes a tunnel interface.
+  bool has_tunnel = 11;
+}
+
+// Internal use only.
+message MethodDescription {
+  string path = 1;
+  bool client_streaming = 2;
+  bool server_streaming = 3;
+}
+
+// Describes a single protobuf file for use in ServiceDescription.
+message ProtoFile {
+  // The path name of the proto file, relative to the 'root' of the namespace, e.g. "tdx/volt_api/volt/v1/volt.proto".
+  string file_path = 1;
+
+  // The actual protobuf file contents.
+  string protobuf = 2;
+
+  // Optional - the service(s) contained in this protobuf file, if omitted here they will be loaded dynamically from the protobuf.
+  repeated string service_name = 3;
+}
+
+// Describes a Volt service.
+message ServiceDescription {
+  // The id of the server resource that is hosting this service.
+  string server_id = 1;
+
+  // The local address of the grpc server hosting this service.
+  string local_address = 2;
+
+  // The discovery mode.
+  DiscoveryMode discoverable = 4;
+
+  // The ping timestamp of the server hosting this service.
+  int64 ping_timestamp = 5;
+
+  // The protobuf definitions of the APIs exposed by this service.
+  repeated ProtoFile proto_file = 6;
+
+  // The fully qualified names of the protobuf services, for example tdx.volt_api.webcam.v1.WebcamControlAPI.
+  repeated string service_api = 7;
+
+  // The certificate authority (chain) that signed the service server certificate.
+  string ca_pem = 8;
+
+  // Internal use only.
+  repeated MethodDescription methods = 100;
+}
+
+// Resource attribute data types.
+enum AttributeDataType {
+  ATTRIBUTE_DATA_TYPE_UNKNOWN = 0;
+  ATTRIBUTE_DATA_TYPE_STRING = 1;
+  ATTRIBUTE_DATA_TYPE_INTEGER = 2;
+  ATTRIBUTE_DATA_TYPE_REAL = 3;
+  ATTRIBUTE_DATA_TYPE_BOOLEAN = 4;
+  ATTRIBUTE_DATA_TYPE_BYTES = 5;
+
+  ATTRIBUTE_DATA_TYPE_IDENTITY = 100;
+  ATTRIBUTE_DATA_TYPE_RESOURCE = 101;
+}
+
+// Resource attribute value will be one of the following fields, depending on the data type.
+message AttributeValue {
+  oneof value {
+    string string = 1;
+    int32 integer = 2;
+    double real = 3;
+    bool boolean = 4;
+    bytes bytes = 5;
+  }
+}
+
+// A resource attribute enables storing arbitrary data associated with a resource.
+message ResourceAttribute {
+  uint32 id = 1;
+
+  string attribute_id = 2;
+
+  string resource_id = 3;
+
+  AttributeDataType data_type = 4;
+
+  repeated AttributeValue values = 5;
+}
+
+// Using `major` and `minor` here upsets the GNU C Library, so we add a `version_` prefix.
+message Version {
+  uint32 version_major = 1;
+  uint32 version_minor = 2;
+  uint32 version_patch = 3;
+}
+
+// The core Resource metadata schema.
+message Resource {
+  // The globally unique resource id.
+  string id = 1;
+
+  // Optional description.
+  string description = 2;
+
+  // Human-readable resource name.
+  string name = 4;
+
+  // Not in use.
+  ShareMode share_mode = 5;
+
+  // The id of the Volt that hosts this resource.
+  string volt_id = 7;
+
+  // Optional description of any services exposed by this resource.
+  ServiceDescription service_description = 8;
+
+  // Attributes assigned to the resource.
+  repeated ResourceAttribute attributes = 9;
+
+  // The version of the platform.
+  Version platform_version = 10;
+
+  // The resource version.
+  uint64 version = 11;
+
+  // The identity of the resource owner.
+  string owner = 101;
+
+  // Creation timestamp, milliseconds since epoch.
+  int64 created = 105;
+
+  // Last modification timestamp, milliseconds since epoch.
+  int64 modified = 106;
+
+  // Not in use.
+  ResourceStatus status = 108;
+
+  // The taxonomy of the resource.
+  repeated string kind = 110;
+
+  // The online status.
+  // For most kinds of resource this indicates that the server hosting the resource is online, the exception being identity resources, in which case the status reflects whether or not the identity has a live session.
+  // All built-in resources are hosted by the Volt itself and are therefore always online when the Volt is running.
+  // Resources hosted by external servers are online if the server itself is online and has registered the resource as online using `setServiceStatus`.
+  OnlineStatus online_status = 111;
+
+  // The size of the resource store in bytes.
+  uint64 size = 113;
+
+  // The path to the resource store.
+  string store = 114;
+
+  repeated string alias = 115;
+
+  // Not yet supported.
+  repeated Resource children = 200;
+}
+
+enum IdentityType {
+  IDENTITY_TYPE_UNKNOWN = 0;
+  IDENTITY_TYPE_USER = 1;
+  IDENTITY_TYPE_AUTHORITY = 2;
+  IDENTITY_TYPE_GROUP = 3;
+}
+
+enum IdentityAliasType {
+  IDENTITY_ALIAS_TYPE_UNKNOWN = 0;
+  IDENTITY_ALIAS_TYPE_PUBLIC_KEY = 1;
+  IDENTITY_ALIAS_TYPE_COMMON_NAME = 2;
+}
+
+enum IdentityAliasSubType {
+  IDENTITY_ALIAS_SUB_TYPE_UNKNOWN = 0;
+
+  // Identifies email common name aliases.
+  IDENTITY_ALIAS_SUB_TYPE_EMAIL = 1;
+
+  // Identifies phone number common name aliases.
+  IDENTITY_ALIAS_SUB_TYPE_PHONE = 2;
+
+  // Identifies DNS common name aliases.
+  IDENTITY_ALIAS_SUB_TYPE_DNS = 3;
+
+  // Identifies public key aliases that originate from owner credentials rather than the identity itself.
+  IDENTITY_ALIAS_SUB_TYPE_OWNER = 4;
+}
+
+message IdentityAlias {
+  // The corresponding identity id.
+  string identity_id = 1;
+
+  // The actual alias, e.g. a common name or key fingerprint.
+  string alias = 2;
+
+  // This will only be populated if alias_type == PUBLIC_KEY
+  string public_key = 3;
+
+  // This will only be populated if alias_type == PUBLIC_KEY
+  string private_key = 4;
+
+  IdentityAliasType alias_type = 5;
+
+  IdentityAliasSubType alias_sub_type = 6;
+
+  // Indicates if this alias has an 'authenticate' policy decision assigned.
+  PolicyDecision authenticate = 7;
+
+  // Indicates if this alias has an 'bind' policy decision assigned.
+  PolicyDecision bind = 8;
+}
+
+// A Volt identity encompasses a Resource and a set of identity aliases.
+message Identity {
+  Resource resource = 1;
+  repeated IdentityAlias aliases = 2;
+}
+
+enum BindCredentialType {
+  BIND_CREDENTIAL_TYPE_UNKNOWN = 0;
+  BIND_CREDENTIAL_TYPE_OWNER = 1;
+  BIND_CREDENTIAL_TYPE_X509 = 2;
+}
+
+message BindCredential {
+  BindCredentialType credential_type = 1;
+  string issuer_id = 2;
+  string issuer_name = 3;
+  string issuer_fingerprint = 4;
+  string issuer_public_key = 5;
+  PolicyDecision decision = 6;
+}
+
+message Binding {
+  // The bind request public key fingerprint.
+  string fingerprint = 1;
+
+  // The bind request public key.
+  string public_key = 2;
+
+  // A human-readable short identifier of the binding.
+  string friendly_name = 3;
+
+  // The host name to add as a SAN to the issued certificate. See also `ip`.
+  string host = 4;
+
+  // The IP address to add as a SAN to the issued certificate as an alternative
+  // to `host`.
+  string ip = 5;
+
+  // Counter of number times a binding was requested.
+  uint32 request_count = 6;
+
+  int64 request_time = 7;
+
+  int64 decision_time = 8;
+
+  // The policy decision assigned to this binding.
+  PolicyDecision decision = 9;
+
+  // The identity id associated with this binding.
+  // Only valid if the bind request has been permitted.
+  string identity_id = 10;
+
+  string status = 11;
+
+  // All credentials supplied as part of bind request.
+  repeated BindCredential credential = 12;
+
+  // The chosen 'owner' credential.
+  BindCredential owner_credential = 14;
+
+  // Set if the bind request presented a valid challenge code.
+  bool volt_challenge = 15;
+}
+
+message Access {
+  string id = 1;
+
+  // The resource being accessed.
+  string resource_id = 2;
+
+  // A human-readable short identifier of the resource.
+  string resource_name = 3;
+
+  // The identity that owns the resource.
+  string resource_owner = 4;
+
+  // The kind of resource.
+  repeated string resource_kind = 5;
+
+  // The identity attempting access.
+  string identity_id = 6;
+
+  // A human-readable short identifier of the subject.
+  string identity_name = 7;
+
+  // The kind of identity.
+  repeated string identity_kind = 8;
+
+  string issuer_id = 9;
+
+  string issuer_name = 10;
+
+  repeated string issuer_kind = 11;
+
+  // Requested access.
+  string access = 12;
+
+  // Assigned decision.
+  PolicyDecision decision = 13;
+
+  bool recursive = 14;
+
+  // Time at which the request was made.
+  int64 request_time = 15;
+
+  // Time at which the decision was taken.
+  int64 decision_time = 16;
+
+  // Counter of number times this access was requested.
+  uint32 request_count = 17;
+}
+
+message VerifiableCredential {
+  string encoded = 1;
+}
+
+message VerifiablePresentation {
+  VerifiableCredential credential = 1;
+  string signature = 2;
+}