api.proto

syntax = "proto3";

package pomerium.cli;
option go_package = "github.com/pomerium/cli/proto";
import "google/protobuf/timestamp.proto";

// Config represents desktop client configuration
service Config {
  // List returns records that match Selector
  rpc List(Selector) returns (Records);
  // Delete deletes records that match Selector
  rpc Delete(Selector) returns (DeleteRecordsResponse);
  // Upsert inserts (if no ID is provided) or updates records
  // you may omit the Connection data to just manipulate tags
  rpc Upsert(Record) returns (Record);
  // GetTags returns all tags. Note that tags are case sensitive
  rpc GetTags(GetTagsRequest) returns (GetTagsResponse);
  // Export dumps config into serialized format
  rpc Export(ExportRequest) returns (ConfigData);
  // Import imports previously serialized records
  rpc Import(ImportRequest) returns (ImportResponse);
}

// Record represents a single tunnel record in the configuration
message Record {
  // if omitted, a new record would be created
  optional string id = 1;
  repeated string tags = 2;
  // connection data may be omitted if i.e. just manipulating the tags data
  optional Connection conn = 3;
}

message Records { repeated Record records = 1; }

// Selector defines record filter
// one of the options must be set
// we do not use oneof as it results in inconveniences on the JS client side
message Selector {
  // all records
  bool all = 1;
  // only return connections matching tag(s)
  repeated string ids = 2;
  // only return specific connection(s)
  repeated string tags = 3;
}
message DeleteRecordsResponse {}

// Export dumps configuration (or subset of, based on provided tag filter)
// in the JSON format
message ExportRequest {
  Selector selector = 1;
  // remove_tags to strip tags from output
  bool remove_tags = 2;
  enum Format {
    EXPORT_FORMAT_UNDEFINED = 0;
    EXPORT_FORMAT_JSON_COMPACT = 1;
    EXPORT_FORMAT_JSON_PRETTY = 2;
  }
  Format format = 3;
}

message GetTagsRequest {};
message GetTagsResponse { repeated string tags = 1; }

message ConfigData { bytes data = 1; }

// ImportRequest would consume the previously exported data back,
// merging it with existing configuration,
// and performing de-duplication of the records so that multiple imports would
// yield the same result
message ImportRequest {
  // if set, all connections would receive that tag instead
  optional string override_tag = 1;
  bytes data = 2;
}

message ImportResponse {}

// Listener service controls listeners
service Listener {
  // Update alters connection status.
  rpc Update(ListenerUpdateRequest) returns (ListenerStatusResponse);
  // GetStatus returns current listener status for active tunnels
  rpc GetStatus(Selector) returns (ListenerStatusResponse);
  // StatusUpdates opens a stream to listen to connection status updates
  // a client has to subscribe and continuously
  // listen to the broadcasted updates
  rpc StatusUpdates(StatusUpdatesRequest) returns (stream ConnectionStatusUpdate);
}

message ListenerUpdateRequest {
  // omit connection ids to connect all connections
  repeated string connection_ids = 1;
  bool connected = 2;
}

message ListenerStatus {
  bool listening = 1;
  optional string listen_addr = 2;
  optional string last_error = 3;
}

message ListenerStatusResponse { map<string, ListenerStatus> listeners = 1; }

message StatusUpdatesRequest { string connection_id = 1; }

// ConnectionStatusUpdates represent connection state changes
message ConnectionStatusUpdate {
  // record this event relates to
  string id = 1;
  // peer_addr represents connecting party remote address and may be used to
  // distinguish between individual TCP connections
  optional string peer_addr = 2;
  enum ConnectionStatus {
    CONNECTION_STATUS_UNDEFINED = 0;
    CONNECTION_STATUS_CONNECTING = 1;
    CONNECTION_STATUS_AUTH_REQUIRED = 2;
    CONNECTION_STATUS_CONNECTED = 3;
    CONNECTION_STATUS_DISCONNECTED = 4;
    // listener is up; peer_addr would not be set
    CONNECTION_STATUS_LISTENING = 5;
    // listener is closed; peer_addr would not be set
    CONNECTION_STATUS_CLOSED = 6;
  }
  ConnectionStatus status = 3;
  // in case the connection failed or terminated, last error may be available
  optional string last_error = 4;
  // provides an authentication URL when AUTH_REQUIRED status is set
  optional string auth_url = 5;
  // event timestamp
  google.protobuf.Timestamp ts = 6;
}

message KeyUsage {
  // standard key usages
  bool digital_signature = 1;
  bool content_commitment = 2;
  bool key_encipherment = 3;
  bool data_encipherment = 4;
  bool key_agreement = 5;
  // certificate authority
  bool cert_sign = 6;
  bool crl_sign = 7;
  bool encipher_only = 8;
  bool decipher_only = 9;
  // extensions derived from x509.ExtKeyUsage
  // server certificate
  bool server_auth = 10;
  // client certificate
  bool client_auth = 11;
}

// Name defines the x509 identity
message Name {
  repeated string country = 1;
  repeated string organization = 2;
  repeated string organizational_unit = 3;
  repeated string locality = 4;
  repeated string province = 5;
  repeated string street_address = 6;
  repeated string postal_code = 7;
  string serial_number = 8;
  string common_name = 9;
}

message CertificateInfo {
  int64 version = 1;
  string serial = 2;

  Name issuer = 3;
  Name subject = 4;

  google.protobuf.Timestamp not_before = 5;
  google.protobuf.Timestamp not_after = 6;

  KeyUsage key_usage = 7;

  repeated string dns_names = 10;
  repeated string email_addresses = 11;
  repeated string ip_addresses = 12;
  repeated string uris = 13;

  bool permitted_dns_domains_critical = 14;
  repeated string permitted_dns_domains = 15;
  repeated string excluded_dns_domains = 16;
  repeated string permitted_ip_ranges = 17;
  repeated string excluded_ip_ranges = 18;
  repeated string permitted_email_addresses = 19;
  repeated string excluded_email_addresses = 20;
  repeated string permitted_uri_domains = 21;
  repeated string excluded_uri_domains = 22;

  // error is set if there was an error parsing provided certificate
  optional string error = 23;
}

message Certificate {
  bytes cert = 1;
  optional bytes key = 2;
  // info field is ignored during upsert requests
  // and is set when returning certificate info
  optional CertificateInfo info = 3;
}

// ClientCertFromStore contains additional filters to apply when searching for
// a client certificate in the system trust store. (This search will always
// take into account any CA names from the TLS CertificateRequest message.)
message ClientCertFromStore {
  // filters based on a single name attribute (e.g. "CN=my cert" or "O=my org")
  optional string issuer_filter = 1;
  optional string subject_filter = 2;
}

// Connection
message Connection {
  // name is a user friendly connection name that a user may define
  optional string name = 1;
  // remote_addr is a remote pomerium host:port
  string remote_addr = 2;
  // listen_address, if not provided, will assign a random port each time
  optional string listen_addr = 3;
  // the URL of the pomerium server to connect to
  optional string pomerium_url = 4;
  oneof tls_options {
    bool disable_tls_verification = 5;
    bytes ca_cert = 6;
  }
  optional Certificate client_cert = 7;
  reserved 8; // unreleased client_cert_issuer_cn search criterion
  // indicates to search the system trust store for a client certificate
  optional ClientCertFromStore client_cert_from_store = 9;
}