@dxos/protocols 0.1.0

package/src/proto/dxos/halo/invitations.proto

@@ -0,0 +1,90 @@
+//
+// Copyright 2021 DXOS.org
+//
+
+syntax = "proto3";
+
+import "google/protobuf/empty.proto";
+
+import "dxos/keys.proto";
+
+package dxos.halo.invitations;
+
+message InvitationDescriptor {
+  enum Type {
+    /// Both peers online at the same time.
+    INTERACTIVE = 0;
+    /// Invited peer's public key is known and invitation can be accepted by any valid peer.
+    OFFLINE = 1;
+  }
+
+  Type type = 1;
+
+  /// Topic for network handshake.
+  bytes swarm_key = 2;
+
+  /// TODO(burdon): Remove?
+  bytes invitation = 3;
+
+  /// Only present if type === OFFLINE.
+  optional bytes identity_key = 4;
+
+  /// Must be stripped out when passing to another peer.
+  optional bytes secret = 5;
+}
+
+//
+// HALO device invitations.
+//
+
+// TODO(burdon): ALL invitation messages should be handled over encrypted sessions.
+// TODO(burdon): Or contain some form of signed credential.
+// TODO(burdon): Calls should include some request context (e.g., halo/space key).
+
+message HaloAdmissionCredentials {
+  dxos.keys.PublicKey device_key = 1;
+  dxos.keys.PublicKey control_feed_key = 2;
+  dxos.keys.PublicKey data_feed_key = 3;
+}
+
+message HaloAdmissionOffer {
+  dxos.keys.PublicKey identity_key = 1;
+  dxos.keys.PublicKey halo_space_key = 2;
+  dxos.keys.PublicKey genesis_feed_key = 3;
+}
+
+service HaloHostService {
+  /// Process admission request from guest.
+  rpc PresentAdmissionCredentials(HaloAdmissionCredentials) returns (google.protobuf.Empty);
+}
+
+service HaloGuestService {
+  /// Process admission offer from host.
+  rpc PresentAdmissionOffer(HaloAdmissionOffer) returns (google.protobuf.Empty);
+}
+
+//
+// Space agent invitations.
+//
+
+message SpaceAdmissionCredentials {
+  dxos.keys.PublicKey identity_key = 1;
+  dxos.keys.PublicKey device_key = 2;
+  dxos.keys.PublicKey control_feed_key = 3;
+  dxos.keys.PublicKey data_feed_key = 4;
+}
+
+message SpaceAdmissionOffer {
+  dxos.keys.PublicKey space_key = 1;
+  dxos.keys.PublicKey genesis_feed_key = 3;
+}
+
+service SpaceHostService {
+  /// Process admission request from guest.
+  rpc PresentAdmissionCredentials(SpaceAdmissionCredentials) returns (google.protobuf.Empty);
+}
+
+service SpaceGuestService {
+  /// Process admission offer from host.
+  rpc PresentAdmissionOffer(SpaceAdmissionOffer) returns (google.protobuf.Empty);
+}

package/src/proto/dxos/halo/keyring.proto

@@ -0,0 +1,13 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+syntax = "proto3";
+
+package dxos.halo.keyring;
+
+// TODO(burdon): Conflicts with keyring.proto
+message KeyRecord {
+  bytes public_key = 1;
+  bytes private_key = 2;
+}

package/src/proto/dxos/halo/keys.proto

@@ -0,0 +1,83 @@
+//
+// Copyright 2020 DXOS.org
+//
+
+syntax = "proto3";
+
+import "dxos/keys.proto";
+import "dxos/halo/signed.proto";
+
+package dxos.halo.keys;
+
+// TODO(burdon): Prefix enums (e.g., KEY_TYPE_UNKNOWN).
+// TODO(burdon): CamelCase variables (e.g., public_key).
+
+//
+// The type/use of a public key.
+//
+enum KeyType {
+  UNKNOWN = 0;
+  IDENTITY = 1;
+  DEVICE = 2;
+  PARTY = 3;
+  FEED = 4;
+  DXNS_ADDRESS = 5;
+}
+
+message KeyRecord {
+  /**
+   * The `KeyType` type of the key. This is often unknown for keys from other sources.
+   */
+  KeyType type = 1;
+
+  /**
+   * The public key as a Buffer (required).
+   */
+  dxos.keys.PublicKey public_key = 2;
+
+  /**
+   * The secret key as a Buffer (this will never be visible outside the Keyring).
+   */
+  optional dxos.keys.PrivateKey secret_key = 3;
+
+  /**
+   * Is this key from a Greeting "hint"?
+   */
+  optional bool hint = 4;
+
+  /**
+   * Determines if this is our key?
+   * Usually true if `secret_key` is present; may be false for "inception keys" such as the Party key.
+   */
+  optional bool own = 5; // TODO(burdon): Rename "local" or "private".
+
+  /**
+   * Is this key to be trusted?
+   */
+  optional bool trusted = 6; // TODO(burdon): Rename "trust". How is this determined?
+
+  /**
+   * An RFC-3339 date/time string for when the key was added to the Keyring.
+   */
+  optional string added = 7;
+
+  /**
+   * An RFC-3339 date/time string for when the key was created.
+   */
+  optional string created = 8;
+}
+
+message KeyRecordList {
+  repeated KeyRecord keys = 1;
+}
+
+//
+// A key which includes its parent keys and SignedMessages leading back to the root of its authority.
+// For example, if IdentityA signed for DeviceA, which signed for DeviceB, which signed for DeviceC the chain
+// would comprised: DeviceC->DeviceB->DeviceA->IdentityA moving from tip to root.
+//
+message KeyChain {
+  dxos.keys.PublicKey public_key = 1;
+  dxos.halo.signed.SignedMessage message = 2; // TODO(burdon): Circular dep.
+  repeated KeyChain parents = 3;
+}

package/src/proto/dxos/halo/signed.proto

@@ -0,0 +1,51 @@
+//
+// Copyright 2020 DXOS.org
+//
+
+syntax = "proto3";
+
+import "google/protobuf/any.proto";
+
+import "dxos/halo/keys.proto";
+import "dxos/keys.proto";
+
+package dxos.halo.signed;
+
+// TODO(burdon): Rename (too generic).
+// TODO(burdon): Use default from codec-protobuf.
+message Message {
+  google.protobuf.Any payload = 1;
+}
+
+/**
+ * A generic container message used whenever messages are signed (e.g. PartyCredential)
+ */
+message SignedMessage {
+  //
+  // Provides the common metadata needed for all signed objects.
+  //
+  message Signed {
+    /// RFC-3339 datetime string.
+    string created = 1;
+    bytes nonce = 2;
+    /// The payload to be signed.
+    google.protobuf.Any payload = 10;
+  }
+
+  //
+  // The signature data itself.
+  //
+  message Signature {
+    /// The publicKey of the keypair that made this signature.
+    dxos.keys.PublicKey key = 1;
+    /// The bytes of the signature.
+    bytes signature = 2;
+    /// The certification chain of SignedMessages for this key.
+    optional keys.KeyChain key_chain = 3;
+  }
+
+  /// The signed message contents.
+  Signed signed = 1;
+  /// An array of Signatures, one for each key that signed the message.
+  repeated Signature signatures = 2;
+}

package/src/proto/dxos/iframe.proto

@@ -0,0 +1,24 @@
+//
+// Copyright 2020 DXOS.org
+//
+
+syntax = "proto3";
+
+import "google/protobuf/empty.proto";
+
+package dxos.iframe;
+
+message StartRequest {
+  string origin = 1;
+}
+
+/// Worker-to-iframe RPCs.
+service IframeService {
+  rpc Heartbeat(google.protobuf.Empty) returns (google.protobuf.Empty);
+}
+
+/// Iframe-to-worker RPCs.
+service WorkerService {
+  rpc Start(StartRequest) returns (google.protobuf.Empty);
+  rpc Stop(google.protobuf.Empty) returns (google.protobuf.Empty);
+}

package/src/proto/dxos/keys.proto

@@ -0,0 +1,15 @@
+//
+// Copyright 2020 DXOS.org
+//
+
+syntax = "proto3";
+
+package dxos.keys;
+
+message PublicKey {
+  bytes data = 1;
+}
+
+message PrivateKey {
+  bytes data = 1;
+}

package/src/proto/dxos/mesh/bridge.proto

@@ -0,0 +1,76 @@
+//
+// Copyright 2020 DXOS.org
+//
+
+syntax = "proto3";
+
+import "dxos/keys.proto";
+import "dxos/mesh/swarm.proto";
+import "google/protobuf/empty.proto";
+
+package dxos.mesh.bridge;
+
+//
+// Broker connections between processes and peers.
+//
+service BridgeService {
+
+  ///
+  rpc Open(ConnectionRequest) returns (stream BridgeEvent);
+
+  ///
+  rpc SendSignal(SignalRequest) returns (google.protobuf.Empty);
+
+  ///
+  rpc SendData(DataRequest) returns (google.protobuf.Empty);
+
+  ///
+  rpc Close(CloseRequest) returns (google.protobuf.Empty);
+}
+
+enum ConnectionState {
+  INVALID = 0;
+  CONNECTING = 1;
+  CONNECTED = 2;
+  CLOSED = 3;
+}
+
+message BridgeEvent {
+  message ConnectionEvent {
+    ConnectionState state = 1;
+    optional string error = 2; // TODO(burdon): Error type.
+  }
+
+  message SignalEvent {
+    dxos.mesh.swarm.Signal payload = 1;
+  }
+
+  message DataEvent {
+    bytes payload = 1;
+  }
+
+  oneof type {
+    ConnectionEvent connection = 1;
+    SignalEvent signal = 2;
+    DataEvent data = 3;
+  }
+}
+
+message ConnectionRequest {
+  dxos.keys.PublicKey  proxy_id = 1;
+  bool initiator = 2;
+}
+
+message SignalRequest {
+  dxos.keys.PublicKey  proxy_id = 1;
+  dxos.mesh.swarm.Signal signal = 2;
+}
+
+message DataRequest {
+  dxos.keys.PublicKey  proxy_id = 1;
+  bytes payload = 2;
+}
+
+message CloseRequest{
+  dxos.keys.PublicKey  proxy_id = 1;
+}

package/src/proto/dxos/mesh/broadcast.proto

@@ -0,0 +1,21 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+syntax = "proto3";
+
+package dxos.mesh.broadcast;
+
+message Packet {
+  // Id message.
+  bytes seq = 1;
+
+  // Represents the author's ID of the message. To identify a message in the network you should check for the: `seqno + origin`.
+  bytes origin = 2;
+
+  // Represents the current sender's ID of the message.
+  optional bytes from = 3;
+
+  // Represents an opaque blob of data, it can contain any data that the publisher wants to send.
+  bytes data = 4;
+}

package/src/proto/dxos/mesh/messaging.proto

@@ -0,0 +1,24 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+syntax = "proto3";
+
+import "google/protobuf/any.proto";
+
+import "dxos/keys.proto";
+
+package dxos.mesh.messaging;
+
+message ReliablePayload {
+  /// Unique message identifier. Used for Acknolegment.
+  dxos.keys.PublicKey message_id = 1;
+
+  /// Payload for signal server netwrok.
+  google.protobuf.Any payload = 2;
+}
+
+message Acknowledgement {
+  /// MessageId of the Message that is being acknowledged.
+  dxos.keys.PublicKey message_id = 1;
+}

package/src/proto/dxos/mesh/presence.proto

@@ -0,0 +1,22 @@
+//
+// Copyright 2021 DXOS.org
+//
+
+syntax = "proto3";
+
+package dxos.mesh.presence;
+
+// Even though those definitions don't use Any the schema can be added dynamically later.
+// Import Any so that the protobuf compiler is happy that there's a substitution.
+import "google/protobuf/any.proto";
+
+message Alive {
+  message Connection {
+    bytes peer_id = 1;
+    optional bool initiator = 2;
+  }
+
+  bytes peer_id = 1;
+  repeated Connection connections = 2;
+  optional bytes metadata = 3;
+}

package/src/proto/dxos/mesh/protocol.proto

@@ -0,0 +1,28 @@
+//
+// Copyright 2021 DXOS.org
+//
+
+syntax = "proto3";
+
+import "google/protobuf/any.proto";
+
+package dxos.mesh.protocol;
+
+// TODO(burdon): Rename ProtoMessage.
+message Message {
+  string nmId = 1; // TODO(burdon): nm???
+  bool nmResponse = 2;
+  bool nmEphemeral = 3;
+  google.protobuf.Any nmData = 4;
+}
+
+// TODO(burdon): Rename ProtoError.
+message Error {
+  string code = 1;
+  string message = 2;
+}
+
+// TODO(burdon): Rename ProtoBuffer.
+message Buffer {
+  bytes data = 1;
+}

package/src/proto/dxos/mesh/replicator.proto

@@ -0,0 +1,19 @@
+//
+// Copyright 2019 DXOS.org
+//
+
+syntax = "proto3";
+
+import "google/protobuf/any.proto";
+
+package dxos.mesh.replicator;
+
+message Container {
+  string type = 1;
+  repeated google.protobuf.Any data = 2;
+}
+
+message Feed {
+  optional bytes key = 1;
+  optional bytes discovery_key = 2;
+}

package/src/proto/dxos/mesh/signal.proto

@@ -0,0 +1,79 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+syntax = "proto3";
+
+import "google/protobuf/any.proto";
+import "google/protobuf/empty.proto";
+import "google/protobuf/timestamp.proto";
+
+package dxos.mesh.signal;
+
+option go_package = "github.com/dxos/kube/go/signal/pb";
+
+message JoinRequest {
+  bytes swarm = 1;
+  bytes peer = 2;
+}
+
+message Message {
+  // TODO(egor): Rename to `sender`.
+  bytes author = 1;
+  bytes recipient = 2;
+  google.protobuf.Any payload = 3;
+}
+
+message ReceptionRequest {
+  bytes peer = 1;
+}
+
+/// Goes on Pub/Sub swarm topic and as a Join stream in RPC.
+message SwarmEvent {
+  // Announce peer available on swarm.
+  message PeerAvailable {
+    bytes peer = 1;
+
+    google.protobuf.Timestamp since = 2;
+
+    // When, if at all (handle the default value as not), this availability would expires were it not re-announced, like
+    // periodically in Pub/Sub with some margin such that Pub/Sub network partitions lead to offline statuses.
+    optional google.protobuf.Timestamp until = 3;
+
+    /// Only relevant in Pub/Sub. Optional, the host topic to eagerly send PeerAvailable messages back to.
+    optional bytes announce_back_to_host = 4;
+  }
+
+  message PeerLeft {
+    bytes peer = 1;
+  }
+
+  oneof event {
+    /// The peer was announced as available on the swarm.
+    PeerAvailable peer_available = 1;
+    /// The peer left, or their announcement timed out.
+    PeerLeft peer_left = 2;
+  }
+}
+
+/// Goes on a Pub/Sub host topic.
+message HostEvent {
+  oneof event {
+    SwarmEvent.PeerAvailable peer_available = 1;
+  }
+}
+
+/// Goes on Pub/Sub peer topic.
+message PeerEvent {
+  oneof event {
+    Message message = 1;
+  }
+}
+
+// TOOD(burdon): Rename.
+// TODO(burdon): Reconcile with `@dxos/kube`.
+service Signal {
+  rpc Join(JoinRequest) returns (stream SwarmEvent);
+  rpc ReceiveMessages(ReceptionRequest) returns (stream Message);
+  rpc SendMessage(Message) returns (google.protobuf.Empty);
+}

package/src/proto/dxos/mesh/swarm.proto

@@ -0,0 +1,41 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+syntax = "proto3";
+
+import "dxos/keys.proto";
+
+package dxos.mesh.swarm;
+
+message SwarmMessage {
+  /// Swarm identefier.
+  dxos.keys.PublicKey topic = 3;
+  /// Unique connection identifier.
+  dxos.keys.PublicKey session_id = 4;
+  /// Message payload.
+  MessageData data = 5;
+  /// Unique message identifier. Used for Acknolegment and matching Anwers to Offers.
+  dxos.keys.PublicKey message_id = 6;
+}
+
+message MessageData {
+  oneof payload {
+    Offer offer = 1;
+    Answer answer = 2;
+    Signal signal = 3;
+  }
+}
+
+message Offer {
+}
+
+message Answer {
+  bool accept = 1;
+  /// MessageId of the Offer being answered.
+  optional dxos.keys.PublicKey offer_message_id = 2;
+}
+
+message Signal {
+  string json = 1;
+}

package/src/proto/dxos/registry.proto

@@ -0,0 +1,60 @@
+//
+// Copyright 2021 DXOS.org
+//
+
+syntax = "proto3";
+
+import "google/protobuf/timestamp.proto";
+
+// TODO(burdon): Rename `dxos.registry.record`.
+package dxos.registry;
+
+message Record {
+  /**
+   * Types are system records that define protocol-buffer schema of other records.
+   */
+  message Type {
+    /// FQ protobuf message name.
+    string message_name = 1;
+    /// Set of protobuf messages encoded in JSON.
+    string protobuf_defs = 2;
+    /// CID of protobuf source file.
+    optional string protobuf_ipfs_cid = 3;
+  }
+
+  /**
+   * Data with a reference to a type record that defines the encoding.
+   */
+  message Extension {
+    /// CID of type record.
+    bytes type_record = 1;
+    /// Serialized payload data.
+    bytes data = 2;
+  }
+
+  //
+  // Metadata
+  //
+
+  /// Record creation timetstamp.
+  optional google.protobuf.Timestamp created = 1;
+
+  /// Human-readable name of record.
+  optional string display_name = 2;
+
+  /// Record description.
+  optional string description = 3;
+
+  /// Optional record tags.
+  repeated string tags = 4;
+
+  oneof kind {
+    /// Type record variant.
+    Type type = 100;
+
+    /// Data record variant.
+    Extension payload = 101;
+
+    // TODO(damaretskyi): Add DID record definition.
+  }
+}