@dxos/client-services 0.1.0

package/src/packlets/identity/identity.ts

@@ -0,0 +1,109 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import assert from 'assert';
+
+import {
+  DeviceStateMachine,
+  CredentialSigner,
+  createCredentialSignerWithKey,
+  createCredentialSignerWithChain
+} from '@dxos/credentials';
+import { Signer } from '@dxos/crypto';
+import { failUndefined } from '@dxos/debug';
+import { Database, Space } from '@dxos/echo-db';
+import { PublicKey } from '@dxos/keys';
+import { ComplexSet } from '@dxos/util';
+
+export type IdentityParams = {
+  identityKey: PublicKey;
+  deviceKey: PublicKey;
+  signer: Signer;
+  space: Space;
+};
+
+/**
+ * Agent identity manager, which includes the agent's Halo space.
+ */
+export class Identity {
+  private readonly _space: Space;
+  private readonly _signer: Signer;
+  private readonly _deviceStateMachine: DeviceStateMachine;
+
+  public readonly identityKey: PublicKey;
+  public readonly deviceKey: PublicKey;
+
+  constructor({ space, signer, identityKey, deviceKey }: IdentityParams) {
+    this._space = space;
+    this._signer = signer;
+
+    this.identityKey = identityKey;
+    this.deviceKey = deviceKey;
+
+    this._deviceStateMachine = new DeviceStateMachine(this.identityKey, this.deviceKey);
+
+    // Save device key chain credential when processed by the party state machine.
+    this._space.onCredentialProcessed.set(async (credential) => {
+      await this._deviceStateMachine.process(credential);
+    });
+  }
+
+  // TODO(burdon): Expose state object?
+  get authorizedDeviceKeys(): ComplexSet<PublicKey> {
+    return this._deviceStateMachine.authorizedDeviceKeys;
+  }
+
+  async open() {
+    await this._space.open();
+  }
+
+  async close() {
+    await this._space.close();
+  }
+
+  async ready() {
+    await this._deviceStateMachine.deviceChainReady.wait();
+
+    // TODO(dmaretskyi): Should we also wait for our feeds to be admitted?
+  }
+
+  /**
+   * @test-only
+   */
+  get controlPipeline() {
+    return this._space.controlPipeline;
+  }
+
+  get haloSpaceKey() {
+    return this._space.key;
+  }
+
+  get haloGenesisFeedKey() {
+    return this._space.genesisFeedKey;
+  }
+
+  get haloDatabase(): Database {
+    return this._space.database ?? failUndefined();
+  }
+
+  /**
+   * Issues credentials as identity.
+   * Requires identity to be ready.
+   */
+  getIdentityCredentialSigner(): CredentialSigner {
+    assert(this._deviceStateMachine.deviceCredentialChain, 'Device credential chain is not ready.');
+    return createCredentialSignerWithChain(
+      this._signer,
+      this._deviceStateMachine.deviceCredentialChain,
+      this.deviceKey
+    );
+  }
+
+  /**
+   * Issues credentials as device.
+   */
+  getDeviceCredentialSigner(): CredentialSigner {
+    return createCredentialSignerWithKey(this._signer, this.deviceKey);
+  }
+}

package/src/packlets/identity/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+export * from './authenticator';
+export * from './identity';
+export * from './identity-manager';

package/src/packlets/invitations/common.ts

@@ -0,0 +1,48 @@
+//
+// Copyright 2020 DXOS.org
+//
+
+import { defaultSecretProvider, defaultSecretValidator, SecretProvider, SecretValidator } from '@dxos/credentials';
+
+/**
+ * Defines a way for peers to authenticate each other through a side channel.
+ */
+export interface InvitationAuthenticator {
+  secretProvider?: SecretProvider;
+  secretValidator: SecretValidator;
+}
+
+export const defaultInvitationAuthenticator: Required<InvitationAuthenticator> = {
+  secretProvider: defaultSecretProvider,
+  secretValidator: defaultSecretValidator
+};
+
+/**
+ * Additional set of callbacks and options used in the invitation process.
+ */
+export interface InvitationOptions {
+  /**
+   * A function to be called when the invitation is closed (successfully or not).
+   */
+  onFinish?: ({ expired }: { expired?: boolean }) => void;
+
+  /**
+   * Date.now()-style timestamp of when this invitation should expire.
+   */
+  expiration?: number;
+}
+
+// TODO(burdon): Remove/move to API.
+export type InviterInvitation = {
+  invitationCode: string;
+  secret: Uint8Array | undefined;
+};
+
+// TODO(burdon): Remove/move to API.
+export type InviteeInvitation = {
+  secret?: Uint8Array | undefined; // Can be undefined initially, then set after receiving secret from the inviter.
+  secretTrigger?: () => void; // Is triggered after supplying the secret.
+};
+
+export type InviterInvitations = InviterInvitation[];
+export type InviteeInvitations = Map<string, InviteeInvitation>;

package/src/packlets/invitations/halo-invitations.ts

@@ -0,0 +1,162 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import { Trigger } from '@dxos/async';
+import { failUndefined } from '@dxos/debug';
+import { PublicKey } from '@dxos/keys';
+import { log } from '@dxos/log';
+import { createProtocolFactory, NetworkManager, StarTopology } from '@dxos/network-manager';
+import { createRpcPlugin } from '@dxos/protocol-plugin-rpc';
+import { schema } from '@dxos/protocols';
+import { InvitationDescriptor } from '@dxos/protocols/proto/dxos/halo/invitations';
+import { createProtoRpcPeer } from '@dxos/rpc';
+
+import { Identity, IdentityManager } from '../identity';
+
+/**
+ * Creates and processes Halo invitations between devices.
+ */
+export class HaloInvitations {
+  constructor(
+    private readonly _identityManager: IdentityManager,
+    private readonly _networkManager: NetworkManager,
+    private readonly _onInitialize: () => Promise<void> // TODO(burdon): ???
+  ) {}
+
+  /**
+   * Sends a HALO admission offer and waits for guest to accept.
+   */
+  async createInvitation({ onFinish }: { onFinish?: () => void } = {}): Promise<InvitationDescriptor> {
+    const identity = this._identityManager.identity ?? failUndefined();
+
+    const plugin = createRpcPlugin(async (port) => {
+      const peer = createProtoRpcPeer({
+        port,
+        requested: {
+          HaloGuestService: schema.getService('dxos.halo.invitations.HaloGuestService')
+        },
+        exposed: {
+          HaloHostService: schema.getService('dxos.halo.invitations.HaloHostService')
+        },
+        handlers: {
+          HaloHostService: {
+            presentAdmissionCredentials: async ({ deviceKey, controlFeedKey, dataFeedKey }) => {
+              log('processing admission request', { identityKey: identity.identityKey, deviceKey });
+
+              // TODO(burdon): Use CredentialGenerator.
+              const signer = identity.getIdentityCredentialSigner();
+              await identity.controlPipeline.writer.write({
+                '@type': 'dxos.echo.feed.CredentialsMessage',
+                credential: await signer.createCredential({
+                  subject: deviceKey,
+                  assertion: {
+                    '@type': 'dxos.halo.credentials.AuthorizedDevice',
+                    identityKey: identity.identityKey,
+                    deviceKey
+                  }
+                })
+              });
+
+              // TODO(dmaretskyi): Admit guest's feeds otherwise messages from them won't be processed by the pipeline.
+            }
+          }
+        }
+      });
+
+      await peer.open();
+      {
+        log('sending admission offer', { identityKey: identity.identityKey });
+        await peer.rpc.HaloGuestService.presentAdmissionOffer({
+          identityKey: identity.identityKey,
+          haloSpaceKey: identity.haloSpaceKey,
+          genesisFeedKey: identity.haloGenesisFeedKey
+        });
+
+        onFinish?.();
+      }
+      await peer.close();
+      await connection.close();
+    });
+
+    const topic = PublicKey.random();
+    const peerId = PublicKey.random(); // TODO(burdon): Fails if using the actual peer key.
+    const connection = await this._networkManager.openSwarmConnection({
+      topic,
+      peerId: topic, // TODO(burdon): Why???
+      // peerId,
+      protocol: createProtocolFactory(topic, peerId, [plugin]),
+      topology: new StarTopology(topic)
+    });
+
+    return {
+      type: InvitationDescriptor.Type.INTERACTIVE,
+      swarmKey: topic.asUint8Array(),
+      invitation: new Uint8Array() // TODO(burdon): Remove.
+    };
+  }
+
+  /**
+   * Joins an existing identity HALO by invitation.
+   */
+  async acceptInvitation(invitation: InvitationDescriptor): Promise<Identity> {
+    const admitted = new Trigger<Identity>(); // TODO(burdon): Must not share across multiple connections.
+
+    const plugin = createRpcPlugin(async (port) => {
+      const peer = createProtoRpcPeer({
+        port,
+        requested: {
+          // TODO(burdon): Rename in-bound.
+          HaloHostService: schema.getService('dxos.halo.invitations.HaloHostService')
+        },
+        exposed: {
+          // TODO(burdon): Rename out-bound?
+          HaloGuestService: schema.getService('dxos.halo.invitations.HaloGuestService')
+        },
+        handlers: {
+          // TODO(burdon): Factory to create handlers and open/close handlers.
+          HaloGuestService: {
+            presentAdmissionOffer: async ({ identityKey, haloSpaceKey, genesisFeedKey }) => {
+              log('processing admission offer', { identityKey });
+              const identity = await this._identityManager.acceptIdentity({
+                identityKey,
+                haloSpaceKey,
+                haloGenesisFeedKey: genesisFeedKey
+              });
+
+              log('sending admission request', { identityKey: invitation.identityKey });
+              await peer.rpc.HaloHostService.presentAdmissionCredentials({
+                deviceKey: identity.deviceKey,
+                controlFeedKey: PublicKey.random(),
+                dataFeedKey: PublicKey.random()
+              });
+
+              // TODO(burdon): Document.
+              await identity.ready();
+              admitted.wake(identity);
+            }
+          }
+        }
+      });
+
+      await peer.open();
+      await admitted.wait();
+      await peer.close();
+    });
+
+    const topic = PublicKey.from(invitation.swarmKey);
+    const peerId = PublicKey.random(); // TODO(burdon): Fails if using the actual peer key.
+    const connection = await this._networkManager.openSwarmConnection({
+      topic,
+      peerId: PublicKey.random(),
+      // peerId,
+      protocol: createProtocolFactory(topic, peerId, [plugin]),
+      topology: new StarTopology(topic)
+    });
+
+    const identity = await admitted.wait();
+    await this._onInitialize();
+    await connection.close();
+    return identity;
+  }
+}

package/src/packlets/invitations/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+export * from './common';
+export * from './halo-invitations';
+export * from './invitation-wrapper';
+export * from './space-invitations';

package/src/packlets/invitations/invitation-wrapper.ts

@@ -0,0 +1,140 @@
+//
+// Copyright 2020 DXOS.org
+//
+
+import base from 'base-x';
+import stableStringify from 'json-stable-stringify';
+import assert from 'node:assert';
+
+import { ripemd160 } from '@dxos/crypto';
+import { InvalidInvitationError } from '@dxos/echo-db';
+import { PublicKey } from '@dxos/keys';
+import { InvitationDescriptor } from '@dxos/protocols/proto/dxos/halo/invitations';
+
+// TODO(burdon): Move to Client API.
+
+// Encode with only alpha-numeric characters.
+const base62 = base('0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ');
+
+/**
+ * A serialized version of InvitationWrapper that's suitable to be encoded as an URL query string.
+ */
+export interface InvitationQueryParameters {
+  hash: string;
+  swarmKey: string;
+  invitation: string;
+  identityKey?: string;
+  type: string;
+}
+
+/**
+ * Describes an issued invitation.
+ *
+ * Can be serialized to protobuf or JSON.
+ * Invitations can be interactive or offline.
+ *
+ * This descriptor might also have a bundled secret for authentication in interactive mode.
+ */
+// TODO(burdon): Move to Client API (and/or remove).
+export class InvitationWrapper {
+  static decode(code: string): InvitationWrapper {
+    const json = base62.decode(code).toString();
+    return InvitationWrapper.fromQueryParameters(JSON.parse(json));
+  }
+
+  static encode(invitation: InvitationWrapper): string {
+    const buffer = Buffer.from(JSON.stringify(invitation.toQueryParameters()));
+    return base62.encode(buffer);
+  }
+
+  static fromQueryParameters(queryParameters: InvitationQueryParameters): InvitationWrapper {
+    const { hash, swarmKey, invitation, identityKey, type } = queryParameters;
+    const descriptor = new InvitationWrapper(
+      parseInvitationType(type),
+      PublicKey.from(swarmKey),
+      PublicKey.bufferize(invitation),
+      identityKey ? PublicKey.from(identityKey) : undefined
+    );
+
+    if (hash !== descriptor.hash) {
+      throw new InvalidInvitationError();
+    }
+
+    return descriptor;
+  }
+
+  static fromProto(invitation: InvitationDescriptor): InvitationWrapper {
+    assert(invitation.type !== undefined);
+    assert(invitation.swarmKey, 'Missing swarm key');
+    assert(invitation.invitation);
+
+    return new InvitationWrapper(
+      invitation.type,
+      PublicKey.from(invitation.swarmKey),
+      Buffer.from(invitation.invitation),
+      invitation.identityKey ? PublicKey.from(invitation.identityKey) : undefined,
+      invitation.secret ? Buffer.from(invitation.secret) : undefined
+    );
+  }
+
+  constructor(
+    public readonly type: InvitationDescriptor.Type,
+    public readonly swarmKey: PublicKey,
+    public readonly invitation: Uint8Array,
+    public readonly identityKey?: PublicKey,
+    public secret?: Uint8Array
+  ) {
+    assert(type !== undefined);
+    assert(PublicKey.isPublicKey(swarmKey));
+    assert(invitation instanceof Uint8Array);
+    if (identityKey) {
+      PublicKey.assertValidPublicKey(identityKey);
+    }
+    if (secret) {
+      assert(secret instanceof Uint8Array);
+    }
+  }
+
+  get hash() {
+    const query = this.toQueryParameters();
+    return query.hash;
+  }
+
+  toProto(): InvitationDescriptor {
+    return {
+      type: this.type,
+      swarmKey: this.swarmKey.asUint8Array(),
+      invitation: this.invitation,
+      identityKey: this.identityKey?.asUint8Array(),
+      secret: this.secret
+    };
+  }
+
+  toQueryParameters(): InvitationQueryParameters {
+    const query: Partial<InvitationQueryParameters> = {
+      swarmKey: this.swarmKey.toHex(),
+      invitation: PublicKey.stringify(this.invitation),
+      type: stringifyInvitationType(this.type)
+    };
+
+    if (this.identityKey) {
+      query.identityKey = this.identityKey.toHex();
+    }
+
+    query.hash = ripemd160(stableStringify(query));
+    return query as InvitationQueryParameters;
+  }
+}
+
+// TODO(burdon): Move to client API.
+const parseInvitationType = (str: string): InvitationDescriptor.Type => {
+  const type = parseInt(str);
+  assert(
+    type === InvitationDescriptor.Type.INTERACTIVE || type === InvitationDescriptor.Type.OFFLINE,
+    'Invalid invitation type'
+  );
+  return type;
+};
+
+// TODO(burdon): Move to client API.
+const stringifyInvitationType = (type: InvitationDescriptor.Type): string => type.toString();

package/src/packlets/invitations/observable.test.ts

@@ -0,0 +1,67 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import { expect } from 'chai';
+
+import { asyncCatch, AsyncCallbacks, Observable, ObservableImpl } from '@dxos/async';
+import { Space } from '@dxos/echo-db';
+import { InvitationDescriptor } from '@dxos/protocols/proto/dxos/halo/invitations';
+
+// TODO(burdon): Timeout.
+// TODO(burdon): Objective: Service impl pattern with clean open/close semantics.
+// TODO(burdon): Isolate deps on protocol throughout echo-db.
+
+import { SpaceInvitations } from './space-invitations';
+
+interface InvitationEvents extends AsyncCallbacks {
+  onConnect(invitation: InvitationDescriptor): void;
+  onComplete(): void;
+  onReject(): void;
+}
+
+type InvitationObservable = Observable<InvitationEvents>;
+
+describe('observable', function () {
+  it('sanity', function () {
+    // TODO(burdon): Testing.
+    const _ = async (space: Space, spaceInvitations: SpaceInvitations) => {
+      // Impl.
+      const doTest = (): InvitationObservable => {
+        const observable = new ObservableImpl<InvitationEvents>();
+
+        asyncCatch(
+          async () => {
+            setTimeout(() => {
+              observable.callbacks?.onConnect({} as InvitationDescriptor);
+            }, 100);
+          },
+          observable,
+          30_000
+        );
+
+        return observable;
+      };
+
+      // TODO(burdon): Ability to cancel.
+
+      // Caller.
+      const observable = doTest();
+      observable.subscribe({
+        onConnect: (invitation) => {
+          console.log(invitation);
+        },
+        onComplete: () => {},
+        onReject: () => {},
+        onTimeout: (err) => {
+          console.log(err);
+        },
+        onError: (err: Error) => {
+          console.log(err);
+        }
+      });
+    };
+
+    expect(true).to.be.true;
+  });
+});

package/src/packlets/invitations/space-invitations.ts

@@ -0,0 +1,159 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import { Trigger } from '@dxos/async';
+import { createAdmissionCredentials } from '@dxos/credentials';
+import { SigningContext, Space, SpaceManager } from '@dxos/echo-db';
+import { writeMessages } from '@dxos/feed-store';
+import { PublicKey } from '@dxos/keys';
+import { log } from '@dxos/log';
+import { createProtocolFactory, NetworkManager, StarTopology } from '@dxos/network-manager';
+import { createRpcPlugin } from '@dxos/protocol-plugin-rpc';
+import { schema } from '@dxos/protocols';
+import { InvitationDescriptor } from '@dxos/protocols/proto/dxos/halo/invitations';
+import { createProtoRpcPeer } from '@dxos/rpc';
+
+/**
+ * Manages the life-cycle of Space invitations between peers.
+ */
+// TODO(burdon): Rename factory.
+export class SpaceInvitations {
+  constructor(
+    private readonly _spaceManager: SpaceManager,
+    private readonly _networkManager: NetworkManager,
+    private readonly _signingContext: SigningContext
+  ) {}
+
+  /**
+   * Creates an invitation and listens for a join request from the invited (guest) peer.
+   */
+  // TODO(burdon): Replace callback with cancelable observable.
+  async createInvitation(space: Space, { onFinish }: { onFinish?: () => void } = {}): Promise<InvitationDescriptor> {
+    const admitted = new Trigger();
+
+    const plugin = createRpcPlugin(async (port) => {
+      const peer = createProtoRpcPeer({
+        port,
+        requested: {
+          SpaceGuestService: schema.getService('dxos.halo.invitations.SpaceGuestService')
+        },
+        exposed: {
+          SpaceHostService: schema.getService('dxos.halo.invitations.SpaceHostService')
+        },
+        handlers: {
+          SpaceHostService: {
+            presentAdmissionCredentials: async ({ identityKey, deviceKey, controlFeedKey, dataFeedKey }) => {
+              log('processing admission request', { identityKey, deviceKey });
+
+              await writeMessages(
+                space.controlPipeline.writer,
+                await createAdmissionCredentials(
+                  this._signingContext.credentialSigner,
+                  identityKey,
+                  deviceKey,
+                  space.key,
+                  controlFeedKey,
+                  dataFeedKey
+                )
+              );
+
+              admitted.wake();
+            }
+          }
+        }
+      });
+
+      // TODO(burdon): Error handling and timeout.
+      await peer.open();
+      {
+        log('sending admission offer', { spaceKey: space.key });
+        await peer.rpc.SpaceGuestService.presentAdmissionOffer({
+          spaceKey: space.key,
+          genesisFeedKey: space.genesisFeedKey
+        });
+
+        onFinish?.();
+      }
+      await peer.close();
+      await connection.close();
+    });
+
+    const topic = PublicKey.random();
+    const peerId = PublicKey.random(); // TODO(burdon): Use actual key.
+    const connection = await this._networkManager.openSwarmConnection({
+      topic,
+      peerId: topic, // TODO(burdon): Why???
+      // peerId,
+      protocol: createProtocolFactory(topic, peerId, [plugin]),
+      topology: new StarTopology(topic)
+    });
+
+    return {
+      type: InvitationDescriptor.Type.INTERACTIVE, // TODO(burdon): Remove (default).
+      swarmKey: topic.asUint8Array(),
+      invitation: new Uint8Array() // TODO(burdon): Remove.
+    };
+  }
+
+  /**
+   * Waits for the host peer (inviter) to accept our join request.
+   * The local guest peer (invitee) then sends the local party invitation to the host,
+   * which then writes the guest's credentials to the space.
+   */
+  async acceptInvitation(invitation: InvitationDescriptor): Promise<Space> {
+    const admitted = new Trigger<Space>();
+
+    const plugin = createRpcPlugin(async (port) => {
+      const peer = createProtoRpcPeer({
+        port,
+        requested: {
+          SpaceHostService: schema.getService('dxos.halo.invitations.SpaceHostService')
+        },
+        exposed: {
+          SpaceGuestService: schema.getService('dxos.halo.invitations.SpaceGuestService')
+        },
+        handlers: {
+          SpaceGuestService: {
+            presentAdmissionOffer: async ({ spaceKey, genesisFeedKey }) => {
+              log('processing admission offer', { spaceKey });
+              // Create local space.
+              const space = await this._spaceManager.acceptSpace({ spaceKey, genesisFeedKey });
+
+              // Send local space's details to host (inviter).
+              // TODO(burdon): Space is orphaned if we crash before other side ACKs. Retry from cold start possible?
+              log('sending admission request', { identityKey: invitation.identityKey });
+              await peer.rpc.SpaceHostService.presentAdmissionCredentials({
+                identityKey: this._signingContext.identityKey,
+                deviceKey: this._signingContext.deviceKey,
+                controlFeedKey: space.controlFeedKey,
+                dataFeedKey: space.dataFeedKey
+              });
+
+              // TODO(burdon): Error: Writable stream closed prematurely
+              admitted.wake(space);
+            }
+          }
+        }
+      });
+
+      await peer.open();
+      await admitted.wait();
+      await peer.close();
+    });
+
+    const topic = PublicKey.from(invitation.swarmKey);
+    const peerId = PublicKey.random(); // TODO(burdon): Use actual key.
+    const connection = await this._networkManager.openSwarmConnection({
+      topic,
+      peerId: PublicKey.random(), // TODO(burdon): Why???
+      // peerId,
+      protocol: createProtocolFactory(topic, peerId, [plugin]),
+      topology: new StarTopology(topic)
+    });
+
+    const space = await admitted.wait();
+    await connection.close();
+    return space;
+  }
+}