@dxos/protocols 2.28.0

package/src/proto/dxos/halo/greet.proto

@@ -0,0 +1,125 @@
+//
+// Copyright 2020 DXOS.org
+//
+
+syntax = "proto3";
+
+package dxos.credentials.greet;
+
+import "keys.proto";
+import "party.proto";
+import "google/protobuf/any.proto";
+import "google/protobuf/wrappers.proto";
+
+//
+// Greeting protocol:
+//
+//  Two nodes: Greeter which acts like a "server" and Invitee which acts like a "client".
+//  All interactions are request/response with the request always sent by the Invitee and the response always
+//  sent by the Invitee.
+//
+//  1) An invitation is generated for the Invitee with a unique ID, known to the Greeter.
+//  2) The Invitee connects to the Greeter over an *open* Topic, using the invitation ID as their peer ID.
+//     This is NOT the Topic of the Party they wish to join, it is one used for Greeting.
+//  3) The Invitee sends a Command message of type BEGIN. This signals the arrival of the invitee, and if necessary,
+//     triggers creation or retrieval of an auth secret for the rest of the process. This secret is normally
+//     communicated out-of-band (eg, voice, IM, etc.). The Greeter responds with a BeginResponse message, acknowledging
+//     the request and indicating the Invitee should proceed to the next step:
+//  4) The Invitee sends a Command message of type HANDSHAKE which includes their secret (eg, PIN, AuthMessage).
+//  5) The Greeter validates the contents (it's genuine, hasn't already been redeemed, the secret matches, etc.)
+//  6) The Greeter returns a HandshakeResponse message with the Party public key and challenge nonce.
+//  7) The Invitee generates one or more AdmitKey and AdmitFeed messages, including the nonce from step (5) then signs
+//     the contents in a SignedMessage.
+//  8) The Invitee sends the SignedMessages in a Command message of type NOTARIZE.
+//  9) The Greeter checks credentials presented and validates the SignedMessage signatures and nonce values.
+//     If all the checks pass then the Admit messages may be published on the Greeter's feed for the target Party,
+//     placed in Envelope messages signed by the Greeter.
+// 10) After writing the messages, the Greeter marks the invitation as having been redeemed, so that it cannot be
+//     used again.
+// 11) The Greeter sends copies of the Greeter-signed Envelope messages to the Invitee in a NotarizeResponse message,
+//     as well as a list of "hints" regarding keys and feeds which are enrolled in the Party. The Invitee uses thes
+//     "hints" to construct its initial view of Party membership, necessary to participate in mutual authentication
+//     for Party feed replication.
+// 12) The Invitee sends the Greeter a FINISH command to acknowledge receipt.
+
+/**
+ * A Greeter command.
+ */
+message Command {
+  enum Type {
+    BEGIN = 0;
+    HANDSHAKE = 1;
+    NOTARIZE = 2;
+    FINISH = 3;
+    CLAIM = 10;
+  }
+
+  Type command = 1;
+
+  // Auth secret (PIN, hash, AuthMessage, etc.).
+  bytes secret = 2;
+
+  // TODO(burdon): These seem to be signed messages? In which case we already know the type.
+  // TODO(dboreham): static typing of contained messages is not yet supported, change from any when it is.
+  // Parameters to the command.
+  repeated google.protobuf.Any params = 10;
+};
+
+//
+// Info is optional, and not needed for very simple schemes like using a PIN, but more complicated scenarios schemes
+// might need to communicate additional info in the response (eg, what key is expected for a signed AuthMessage).
+//
+message BeginResponse {
+  map<string, google.protobuf.Any> info = 1;
+}
+
+//
+// The next command is 'HANDSHAKE', the invitee sends the `secret` for authentication, and if successful, the
+// Greeter returns the `partyKey` and a `nonce` which the invitee will need to use for the Party credential messages.
+//
+message HandshakeResponse {
+  // Random bytes which must be included in the signed portion of messages submitted in a 'NOTARIZE' command
+  // (proving ownership of the keys in question).
+  bytes nonce = 1;
+
+  // The public key of the party.
+  PubKey partyKey = 2;
+};
+
+//
+// The 'NOTARIZE' command takes an array of SignedMessages which the invitee would like added to the Party. The
+// standard case would be a message admitting an Identity (or Device) key and a message admitting a feed.
+//
+message NotarizeResponse {
+  // A copy of each of the messages as written to the Party (now in an Envelope signed by the Greeter) and the Feed
+  // and key hints necessary to bootstrap the invitee into the Party.
+  repeated google.protobuf.Any copies = 1;
+
+  // Feed and key hints necessary to bootstrap the invitee into the Party.
+  repeated KeyHint hints = 2;
+};
+
+//
+// Feed and key hints are required by the invitee, because even though the Party members now trust it, it does not trust
+// them. Until it has a chance to replicate, it cannot construct its own understanding of the Party from party.*
+// messages, but neither can it replicate unless it trusts its peers. The Hints break this cycle by providing an
+// initial set of keys and Feeds to trust.
+//
+message KeyHint {
+  // TODO(telackey): These should be changed to be the full set of signed party messages, so the recipient can build
+  // and verify the party structure just as it would if it had obtained them from the feeds.
+  PubKey publicKey = 1;
+  KeyType type = 2;
+}
+
+//
+// The 'CLAIM' command is used to trigger the Greeting flow by "claiming" a PartyInvitation which was replicated
+// to the Party or presented as a "proof".
+//
+// The ClaimResponse provides the invitee with information about the interactive invitation triggered by the "claim",
+// such as the invitation ID and the swarm key to use to connect to the Greeter.
+//
+message ClaimResponse {
+  bytes id = 1; // The ID of the invitation.
+  bytes rendezvousKey = 2; // The swarm key to use to rendezvous with the Greeter.
+}

package/src/proto/dxos/halo/identity.proto

@@ -0,0 +1,24 @@
+//
+// Copyright 2020 DXOS.org
+//
+
+syntax = "proto3";
+
+package dxos.credentials.identity;
+
+import "google/protobuf/any.proto";
+import "greet.proto";
+import "keys.proto";
+import "signed.proto";
+
+// Additional, descriptive information about an Identity. Must be signed by the Identity's key.
+message IdentityInfo {
+  PubKey publicKey = 1;          // The publicKey of the Identity (must be signed by this key).
+  string displayName = 2;       // The display name to use for this key.
+}
+
+// Additional, descriptive information about a Device. Must be signed by the Device's key.
+message DeviceInfo {
+  PubKey publicKey = 1;          // The publicKey of the Device (must be signed by this key).
+  string displayName = 2;       // The display name to use for this key.
+}

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

@@ -0,0 +1,88 @@
+//
+// Copyright 2020 DXOS.org
+//
+
+syntax = "proto3";
+
+package dxos.halo.keys;
+
+import "signed.proto";
+import "google/protobuf/any.proto";
+
+//
+// The type/use of a public key.
+//
+enum KeyType {
+  UNKNOWN = 0;
+  IDENTITY = 1;
+  DEVICE = 2;
+  PARTY = 3;
+  FEED = 4;
+  DXNS_ADDRESS = 5;
+}
+
+message PubKey {
+  bytes data = 1;
+}
+
+message PrivKey {
+  bytes data = 1;
+}
+
+message KeyRecord {
+  /**
+   * - The `KeyType` type of the key. This is often unknown for keys from other sources.
+   */
+  required KeyType type = 1;
+
+  /**
+   * - The public key as a Buffer (required).
+   */
+  required PubKey publicKey = 2;
+
+  /**
+   * - The secret key as a Buffer (this will never be visible outside the Keyring).
+   */
+  PrivKey secretKey = 3;
+
+  /**
+   * - Is this key from a Greeting "hint"?
+   */
+  bool hint = 4;
+
+  /**
+   * - Is this our key? Usually true if `secretKey` is present,
+   *          may be false for "inception keys" such as the Party key.
+   */
+  bool own = 5;
+
+  /**
+   * - Is this key to be trusted?
+   */
+  bool trusted = 6;
+
+  /**
+   * - An RFC-3339 date/time string for when the key was added to the Keyring.
+   */
+  string added = 7;
+
+  /**
+   * - An RFC-3339 date/time string for when the key was created.
+   */
+  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 {
+  required PubKey publicKey = 1;
+  required SignedMessage message = 2;
+  repeated KeyChain parents = 3;
+}

package/src/proto/dxos/halo/party.proto

@@ -0,0 +1,127 @@
+//
+// Copyright 2020 DXOS.org
+//
+
+syntax = "proto3";
+
+package dxos.credentials.party;
+
+import "keys.proto";
+import "signed.proto";
+import "google/protobuf/any.proto";
+
+//
+// Party Credentials are messages that, by virtue of their being signed by a key that is a
+// recognized authority, convey to the recipient that something should be allowed or done.
+// They are therefore similar in structure and purpose to X.509 certificates and to W3C
+// Verifiable Credentials. The "subject" for a Party Credential (who or what can do the thing allowed),
+// along with the kind of action permitted is specified in one of the four contained message
+// types: PartyGenesis, FeedGenesis, KeyAdmit, FeedAdmit. One such subject message is
+// present in the contents field of each PartyCredential message.
+// PartyMessage carries common metadata (created, nonce) and the type of the subject message (type).
+// Note that the subject message type is explicitly present in the type field even though
+// its type will be discoverable via the relevant codec at runtime. This arrangement allows
+// for signing to be done over the relevant fields (fields for which signature inclusion is
+// necessary to ensure the security of the system), without needing to make assumptions about
+// the presence and specific form of the codec-supplied message type identification.
+// The complete credential comprises the PartyCredential message contents, signed by the
+// relevant authority key(s), encoded as a SignedMessage (see ../signed.proto).
+//
+message PartyCredential {
+  enum Type {
+    ENVELOPE = 0;
+    PARTY_GENESIS = 1;
+    FEED_GENESIS = 2;
+    KEY_ADMIT = 3;
+    FEED_ADMIT = 4;
+  }
+
+  Type type = 1;
+
+  oneof contents {
+    Envelope envelope = 10;
+    PartyGenesis partyGenesis = 11;
+    KeyAdmit keyAdmit = 12;
+    FeedAdmit feedAdmit = 13;
+    FeedGenesis feedGenesis = 14;
+  }
+}
+
+//
+// The start-of-authority record for the Party, admitting a single key (usually a pseudonym) and a single feed.
+// It must be signed by all three keys (party, key, feed). The Party private key should be destroyed after
+// signing this message. This pattern is sometimes called an Inception Key.
+//
+message PartyGenesis {
+  PubKey partyKey = 1;                        // The party public key.
+  PubKey feedKey = 2;                         // The initial feed to admit.
+  PubKey admitKey = 3;                        // The key to admit (usually a pseudonym key).
+  KeyType admitKeyType = 4;                  // The KeyType of the admitKey.
+}
+
+//
+// Admit a single public key to the Party. This message must be signed by the key to be admitted, to prevent
+// impersonation attacks, and unless the contents of an Envelope, also by a key which has already been admitted.
+// Admitted keys represent entities in the Party Authority trust tree, for example: an identity pseudonym key
+// representing "Alice in this party", or a device pseudonym key representing "Alice's Laptop in this Party".
+//
+message KeyAdmit {
+  PubKey partyKey = 1;
+  PubKey admitKey = 2;                        // The public key to admit.
+  KeyType admitKeyType = 3;                  // The KeyType of the admitKey.
+}
+
+//
+// Admit a single feed to the Party. This message must be signed by the feed key to be admitted, also by some other
+// key which has already been admitted (usually by a device pseudonym key).
+// FeedAdmit messages constitute the leaf nodes in the Party Authority trust tree in that Party data is transmitted
+// via feeds and therefore to write to a Party a node must have at least one feed admitted.
+//
+message FeedAdmit {
+  PubKey partyKey = 1;                        // The Party public key.
+  PubKey feedKey = 2;                         // The Feed public key.
+}
+
+//
+// The start-of-authority record for the Feed, signed by the owner of the feed and the feed.
+// The owner must be a key previously admitted to the Party.
+//
+message FeedGenesis {
+  PubKey feedKey  = 1;                        // The feed public key.
+  PubKey ownerKey = 2;                        // The public key of the owner of this feed.
+}
+
+//
+// TODO(burdon): Needs discussion.
+// A signed message containing a signed message. The nested signed structure allows a signed message
+// received from another node that is not yet a party member (invitee), to be published on the party on behalf
+// of that node by another node (greeter). It thereby provides a kind of delegated authority mechanism used to
+// link signatures across the two nodes in a replay and impersonation resistant manner.
+// Envelope is used by a Greeter to write, and countersign using
+// its key, a message provided to it, signed by the Invitee, to the Party, via the greeting node's feed.
+// The signature on the Envelope is that of the Greeter, while the signature(s) on the interior message are
+// those of the Invitee, demonstrating ownership by the Invitee of the keys or feeds to be admitted.
+// Envelope exists solely to include the party key under the countersignature, otherwise two nested SignedMessages
+// could be used. The party key is included to prevent replay attacks where a valid credential from one
+// party is used to gain access to a different party.
+// The interior message can only be of types:
+//   KEY_ADMIT
+//   FEED_ADMIT
+//
+message Envelope {
+  PubKey partyKey = 1;                        // The Party public key.
+  Message message = 2;                       // The original Message.
+}
+
+//
+// A PartyInvitation message that can be written to the Party so that any Party member can authenticate
+// the invitee and perform greeting. This message must be written within a SignedMessage signed by the key (or KeyChain)
+// of listed as the `issuer`. The invitee must authenticate themselves to the Greeter with Auth messages signed by
+// the key (or KeyChain) of listed in the `invitee` field.
+//
+message PartyInvitation {
+  bytes id = 1; // A unique ID for this Invitation.
+  PubKey partyKey = 2; // The public key of the Party for which this Invitation is valid.
+  PubKey issuerKey = 3; // The public key of the Party member issuing this invitation.
+  PubKey inviteeKey = 4; // The public key of the non-member that is being invited to join the Party.
+}

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

@@ -0,0 +1,42 @@
+//
+// Copyright 2020 DXOS.org
+//
+
+syntax = "proto3";
+
+// TODO(burdon): Rename dxos.halo?
+package dxos.credentials;
+
+import "keys.proto";
+import "google/protobuf/any.proto";
+
+// TODO(burdon): Use default from codec-protobuf.
+message Message {
+  required 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 {
+    required string created = 1;                    // RFC-3339 datetime string.
+    required bytes nonce = 2;
+    required google.protobuf.Any payload = 10;      // The payload to be signed.
+  }
+
+  //
+  // The signature data itself.
+  //
+  message Signature {
+    required PubKey key = 1;                        // The publicKey of the keypair that made this signature.
+    required bytes signature = 2;                   // The bytes of the signature.
+    KeyChain keyChain = 3;                          // Optional. The certification chain of SignedMessages for this key.
+  }
+
+  required Signed signed = 1;                       // The signed message contents.
+  repeated Signature signatures = 2;                // An array of Signatures, one for each key that signed the message.
+}

package/src/proto/dxos/rpc.proto

@@ -0,0 +1,59 @@
+//
+// Copyright 2020 DXOS.org
+//
+
+syntax = "proto3";
+
+import "google/protobuf/any.proto";
+
+package dxos.rpc;
+
+message RpcMessage {
+  oneof content {
+    Request request = 1;
+    Response response = 2;
+
+    /// Means that the node is open to receiving requests. Second stage of the hasnshake protocol.
+    bool open = 3;
+
+    StreamClose streamClose = 4;
+  }
+}
+
+message Request {
+  int32 id = 1;
+  string method = 2;
+  google.protobuf.Any payload = 3;
+  bool stream = 4;
+}
+
+message Response {
+  int32 id = 1;
+  oneof content {
+    google.protobuf.Any payload = 2;
+    Error error = 3;
+    // Sent when stream is closed without an error.
+    bool close = 4;
+  }
+}
+
+// Sent by client to end the streaming response.
+message StreamClose {
+  int32 id = 1;
+}
+
+message Error {
+  string name = 1;
+  string message = 2;
+  string stack = 3;
+}
+
+message MessageTrace {
+  enum Direction {
+    INCOMING = 0;
+    OUTGOING = 1;
+  }
+
+  Direction direction = 1;
+  bytes data = 2;
+}

package/src/proto/gen/dxos/bot.ts

@@ -0,0 +1,120 @@
+import type { Stream } from "@dxos/codec-protobuf";
+import * as dxos_client from "./client";
+import * as dxos_config from "./config";
+import * as dxos_credentials from "./credentials";
+import * as dxos_credentials_auth from "./credentials/auth";
+import * as dxos_credentials_greet from "./credentials/greet";
+import * as dxos_credentials_identity from "./credentials/identity";
+import * as dxos_credentials_party from "./credentials/party";
+import * as dxos_devtools from "./devtools";
+import * as dxos_echo_feed from "./echo/feed";
+import * as dxos_echo_invitation from "./echo/invitation";
+import * as dxos_echo_metadata from "./echo/metadata";
+import * as dxos_echo_service from "./echo/service";
+import * as dxos_echo_snapshot from "./echo/snapshot";
+import * as dxos_halo_keys from "./halo/keys";
+import * as dxos_rpc from "./rpc";
+import * as google_protobuf from "../google/protobuf";
+export interface BotPackageSpecifier {
+    dxn?: string;
+    ipfsCid?: string;
+    localPath?: string;
+}
+export interface Bot {
+    id?: string;
+    status?: Bot.Status;
+    packageSpecifier?: BotPackageSpecifier;
+    lastStart?: google_protobuf.Timestamp;
+    partyKey?: dxos_halo_keys.PubKey;
+    runtime?: Bot.Runtime;
+}
+export namespace Bot {
+    export enum Status {
+        STOPPED = 0,
+        STARTING = 1,
+        RUNNING = 2,
+        STOPPING = 3
+    }
+    export interface Runtime {
+        exitCode?: number;
+        exitSignal?: string;
+        error?: string;
+    }
+}
+export interface GetBotsResponse {
+    bots?: Bot[];
+}
+export interface SpawnBotRequest {
+    package?: BotPackageSpecifier;
+    /**
+     * Invitation for the bot to join the target party.
+     */
+    invitation?: dxos_echo_invitation.InvitationDescriptor;
+    /**
+     * Key of the party bot is invited to.
+     */
+    partyKey?: dxos_halo_keys.PubKey;
+}
+export interface SendCommandRequest {
+    botId?: string;
+    command?: Uint8Array;
+}
+export interface SendCommandResponse {
+    response?: Uint8Array;
+}
+export interface GetLogsResponse {
+    chunk?: Uint8Array;
+}
+export interface GetLogsRequest {
+    botId?: string;
+}
+/**
+ * Service that is used by clients to communicate with bot factory.
+ */
+export interface BotFactoryService {
+    getBots: (request: void) => Promise<GetBotsResponse>;
+    spawnBot: (request: SpawnBotRequest) => Promise<Bot>;
+    start: (request: Bot) => Promise<Bot>;
+    stop: (request: Bot) => Promise<Bot>;
+    remove: (request: Bot) => Promise<void>;
+    getLogs: (request: GetLogsRequest) => Stream<GetLogsResponse>;
+    sendCommand: (request: SendCommandRequest) => Promise<SendCommandResponse>;
+    removeAll: (request: void) => Promise<void>;
+}
+export interface InitializeRequest {
+    /**
+     * Bot runtime configuration.
+     */
+    config?: dxos_config.Config;
+    /**
+     * Invitation for the bot to join the target party.
+     */
+    invitation?: dxos_echo_invitation.InvitationDescriptor;
+}
+export interface StartRequest {
+    /**
+     * Bot runtime configuration.
+     */
+    config?: dxos_config.Config;
+}
+/**
+ * Service that is used by bots communicating with bot factory.
+ */
+export interface BotService {
+    /**
+     * Initialize Client, create profile, and join a party.
+     */
+    initialize: (request: InitializeRequest) => Promise<void>;
+    /**
+     * Initialize Client.
+     */
+    start: (request: StartRequest) => Promise<void>;
+    /**
+     * Custom commands sent to the bot factory.
+     */
+    command: (request: SendCommandRequest) => Promise<SendCommandResponse>;
+    /**
+     * Stop the bot.
+     */
+    stop: (request: void) => Promise<void>;
+}