@dxos/client-services 0.1.2 → 0.1.3

package/src/packlets/invitations/invitations.ts

@@ -0,0 +1,149 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import assert from 'assert';
+
+import {
+  AsyncEvents,
+  CancellableObservable,
+  CancellableObservableEvents,
+  Observable,
+  CancellableObservableProvider
+} from '@dxos/async';
+import { Invitation } from '@dxos/protocols/proto/dxos/client/services';
+
+export const AUTHENTICATION_CODE_LENGTH = 6;
+
+export type CreateInvitationsOptions = {
+  type?: Invitation.Type;
+  timeout?: number;
+};
+
+/**
+ * Common invitation events (callbacks) for creating and accepting invitations.
+ */
+// TODO(burdon): Remove optionals.
+export interface InvitationEvents extends AsyncEvents, CancellableObservableEvents {
+  onConnecting?(invitation: Invitation): void;
+  onConnected?(invitation: Invitation): void;
+  onAuthenticating?(invitation: Invitation): void;
+  onSuccess(invitation: Invitation): void; // TODO(burdon): Collides with AsyncEvents.
+}
+
+/**
+ * Base class for all invitation observables and providers.
+ * Observable that supports inspection of the current value.
+ */
+export interface InvitationObservable extends CancellableObservable<InvitationEvents> {
+  get invitation(): Invitation | undefined;
+}
+
+export class InvitationObservableProvider
+  extends CancellableObservableProvider<InvitationEvents>
+  implements InvitationObservable
+{
+  private _invitation?: Invitation;
+
+  get invitation(): Invitation | undefined {
+    return this._invitation;
+  }
+
+  setInvitation(invitation: Invitation) {
+    this._invitation = invitation;
+  }
+}
+
+/**
+ * Cancelable observer.
+ */
+export type CancellableInvitationObservable = InvitationObservable;
+
+/**
+ * Cancelable observer that relays authentication requests.
+ */
+export interface AuthenticatingInvitationObservable extends CancellableInvitationObservable {
+  authenticate(code: string): Promise<void>;
+}
+
+export interface AuthenticatingInvitationProviderActions {
+  onCancel(): Promise<void>;
+  onAuthenticate(code: string): Promise<void>;
+}
+
+export class AuthenticatingInvitationProvider
+  extends InvitationObservableProvider
+  implements AuthenticatingInvitationObservable
+{
+  // prettier-ignore
+  constructor(
+    private readonly _actions: AuthenticatingInvitationProviderActions
+  ) {
+    super(() => this._actions.onCancel());
+  }
+
+  async authenticate(authenticationCode: string): Promise<void> {
+    return this._actions.onAuthenticate(authenticationCode);
+  }
+}
+
+/**
+ * Common interface for Halo and Space invitation proxies and handlers.
+ * Handles the life-cycle of Space invitations between peers.
+ *
+ * Host
+ * - Creates an invitation containing a swarm topic.
+ * - Joins the swarm with the topic and waits for guest's admission request.
+ * - Responds with admission offer then waits for guest's credentials.
+ * - Writes credentials to control feed then exits.
+ *
+ * Guest
+ * - Joins the swarm with the topic.
+ * - NOTE: The topic is transmitted out-of-band (e.g., via a QR code).
+ * - Sends an admission request.
+ * - If Space handler then creates a local cloned space (with genesis block).
+ * - Sends admission credentials (containing local device and feed keys).
+ *
+ * TODO(burdon): Show proxy/service relationship and reference design doc/diagram.
+ *
+ *  ```
+ *  [Guest]                                                  [Host]
+ *   |-------------------------------------RequestAdmission-->|
+ *   |<--AdmissionOffer---------------------------------------|
+ *   |
+ *   |--------------------------PresentAdmissionCredentials-->|
+ *  ```
+ */
+export interface InvitationsHandler<T> {
+  // TODO(burdon): Pass in options.
+  createInvitation(context: T, options?: CreateInvitationsOptions): InvitationObservable;
+  acceptInvitation(invitation: Invitation): AuthenticatingInvitationObservable;
+}
+
+/**
+ * Common interface for Halo and Space proxies.
+ */
+export interface InvitationsProxy<T> extends InvitationsHandler<T> {
+  createInvitationObject(context: T): Invitation;
+}
+
+/**
+ * Util to wrap observable with promise.
+ * @deprecated
+ */
+// TODO(burdon): Replace with InvitationObservableProvider.
+export const invitationObservable = async (observable: Observable<InvitationEvents>): Promise<Invitation> => {
+  return new Promise((resolve, reject) => {
+    const unsubscribe = observable.subscribe({
+      onSuccess: (invitation: Invitation) => {
+        assert(invitation.state === Invitation.State.SUCCESS);
+        unsubscribe();
+        resolve(invitation);
+      },
+      onError: (err: Error) => {
+        unsubscribe();
+        reject(err);
+      }
+    });
+  });
+};

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

@@ -0,0 +1,154 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import assert from 'assert';
+import { expect } from 'chai';
+
+import { asyncChain, Trigger } from '@dxos/async';
+import { raise } from '@dxos/debug';
+import { PublicKey } from '@dxos/keys';
+import { ObjectModel } from '@dxos/object-model';
+import { Invitation } from '@dxos/protocols/proto/dxos/client/services';
+import { afterTest } from '@dxos/testutils';
+
+import { ServiceContext } from '../services';
+import { createIdentity, createPeers, syncItems } from '../testing';
+
+const closeAfterTest = async (peer: ServiceContext) => {
+  afterTest(() => peer.close());
+  return peer;
+};
+
+describe('services/space-invitations-handler', function () {
+  it('genesis', async function () {
+    const [peer] = await asyncChain<ServiceContext>([createIdentity, closeAfterTest])(createPeers(1));
+
+    const space = await peer.spaceManager!.createSpace();
+    expect(space.database).not.to.be.undefined;
+    expect(peer.spaceManager!.spaces.has(space.key)).to.be.true;
+    await space.close();
+  });
+
+  it('genesis with database mutations', async function () {
+    const [peer] = await asyncChain<ServiceContext>([createIdentity, closeAfterTest])(createPeers(1));
+    const space = await peer.spaceManager!.createSpace();
+
+    {
+      const item = await space.database!.createItem<ObjectModel>({ type: 'test' });
+      void item.model.set('name', 'test');
+    }
+
+    {
+      const [item] = space.database!.select({ type: 'test' }).exec().entities;
+      expect(item.model.get('name')).to.eq('test');
+    }
+
+    await space.close();
+  });
+
+  it('creates and accepts invitation', async function () {
+    const [host, guest] = await asyncChain<ServiceContext>([createIdentity, closeAfterTest])(createPeers(2));
+
+    const complete1 = new Trigger<PublicKey>();
+    const complete2 = new Trigger<PublicKey>();
+
+    const authenticationCode = new Trigger<string>();
+
+    const space1 = await host.spaceManager!.createSpace();
+    const observable1 = host.spaceInvitations!.createInvitation(space1);
+    observable1.subscribe({
+      onConnecting: async (invitation1: Invitation) => {
+        const observable2 = guest.spaceInvitations!.acceptInvitation(invitation1);
+        observable2.subscribe({
+          onConnecting: async (invitation2: Invitation) => {},
+          onConnected: async (invitation2: Invitation) => {
+            expect(invitation1.swarmKey).to.eq(invitation2.swarmKey);
+          },
+          onAuthenticating: async (invitation2: Invitation) => {
+            await observable2.authenticate(await authenticationCode.wait());
+          },
+          onSuccess: (invitation: Invitation) => {
+            complete2.wake(invitation.spaceKey!);
+          },
+          onCancelled: () => raise(new Error()),
+          onTimeout: (err: Error) => raise(new Error(err.message)),
+          onError: (err: Error) => raise(new Error(err.message))
+        });
+      },
+      onConnected: (invitation: Invitation) => {
+        assert(invitation.authenticationCode);
+        authenticationCode.wake(invitation.authenticationCode);
+      },
+      onSuccess: (invitation: Invitation) => {
+        complete1.wake(space1.key);
+      },
+      onCancelled: () => raise(new Error()),
+      onTimeout: (err: Error) => raise(new Error(err.message)),
+      onError: (err: Error) => raise(new Error(err.message))
+    });
+
+    {
+      const [spaceKey1, spaceKey2] = await Promise.all([complete1.wait(), complete2.wait()]);
+      expect(spaceKey1).to.deep.eq(spaceKey2);
+
+      const space1 = host.spaceManager!.spaces.get(spaceKey1)!;
+      const space2 = guest.spaceManager!.spaces.get(spaceKey2)!;
+      expect(space1).not.to.be.undefined;
+      expect(space2).not.to.be.undefined;
+
+      await syncItems(space1, space2);
+
+      await space1.close();
+      await space2.close();
+    }
+  });
+
+  it('cancels invitation', async function () {
+    const [host, guest] = await asyncChain<ServiceContext>([createIdentity, closeAfterTest])(createPeers(2));
+
+    const cancelled = new Trigger();
+    const connecting1 = new Trigger<Invitation>(); // peer 1 connected.
+    const connecting2 = new Trigger<Invitation>(); // peer 2 connected.
+
+    const space1 = await host.spaceManager!.createSpace();
+    const observable1 = await host.spaceInvitations!.createInvitation(space1);
+    observable1.subscribe({
+      onConnecting: async (invitation1: Invitation) => {
+        connecting1.wake(invitation1);
+
+        const observable2 = await guest.spaceInvitations!.acceptInvitation(invitation1);
+        observable2.subscribe({
+          onConnecting: async (invitation2: Invitation) => {
+            expect(invitation1.swarmKey).to.eq(invitation2.swarmKey);
+            connecting2.wake(invitation2);
+          },
+          onConnected: async (invitation2: Invitation) => {},
+          onSuccess: () => {},
+          onCancelled: () => raise(new Error()),
+          onTimeout: (err: Error) => raise(new Error(err.message)),
+          onError: (err: Error) => raise(new Error(err.message))
+        });
+      },
+      onConnected: async (invitation1: Invitation) => {},
+      onCancelled: () => {
+        cancelled.wake();
+      },
+      onSuccess: () => raise(new Error()),
+      onTimeout: (err: Error) => raise(new Error(err.message)),
+      onError: (err: Error) => raise(new Error(err.message))
+    });
+
+    const invitation1 = await connecting1.wait();
+    const invitation2 = await connecting2.wait();
+    expect(invitation1.swarmKey).to.eq(invitation2.swarmKey);
+
+    // TODO(burdon): Simulate network latency.
+    setTimeout(async () => {
+      await observable1.cancel();
+    });
+
+    await cancelled.wait();
+    await space1.close();
+  });
+});

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

@@ -0,0 +1,266 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import assert from 'assert';
+
+import { sleep, Trigger } from '@dxos/async';
+import { createAdmissionCredentials, generatePasscode } 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, SwarmConnection } from '@dxos/network-manager';
+import { createRpcPlugin, RpcPlugin } from '@dxos/protocol-plugin-rpc';
+import { schema } from '@dxos/protocols';
+import { Invitation } from '@dxos/protocols/proto/dxos/client/services';
+import { createProtoRpcPeer } from '@dxos/rpc';
+
+import {
+  AuthenticatingInvitationProvider,
+  CreateInvitationsOptions,
+  InvitationsHandler,
+  InvitationObservable,
+  InvitationObservableProvider,
+  AUTHENTICATION_CODE_LENGTH
+} from './invitations';
+
+// TODO(burdon): Pass options from client.
+// TODO(burdon): Don't close until RPC has complete.
+const ON_CLOSE_DELAY = 500;
+const INVITATION_TIMEOUT = 3 * 60_000; // 3 mins.
+
+/**
+ * Handles the life-cycle of Space invitations between peers.
+ */
+export class SpaceInvitationsHandler implements InvitationsHandler<Space> {
+  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.
+   */
+  createInvitation(space: Space, options?: CreateInvitationsOptions): InvitationObservable {
+    let swarmConnection: SwarmConnection | undefined;
+    const { type, timeout = INVITATION_TIMEOUT } = options ?? {};
+    assert(type !== Invitation.Type.OFFLINE);
+
+    const invitation: Invitation = {
+      type,
+      // type: Invitation.Type.INTERACTIVE_TESTING,
+      invitationId: PublicKey.random().toHex(),
+      swarmKey: PublicKey.random(),
+      spaceKey: space.key,
+      authenticationCode: generatePasscode(AUTHENTICATION_CODE_LENGTH)
+    };
+
+    // TODO(burdon): Stop anything pending.
+    const observable = new InvitationObservableProvider(async () => {
+      await swarmConnection?.close();
+    });
+
+    let authenticationCode: string;
+    const complete = new Trigger<PublicKey>();
+    const plugin = new RpcPlugin(async (port) => {
+      const peer = createProtoRpcPeer({
+        exposed: {
+          SpaceHostService: schema.getService('dxos.halo.invitations.SpaceHostService')
+        },
+        handlers: {
+          SpaceHostService: {
+            requestAdmission: async () => {
+              log('responding with admission offer', {
+                host: this._signingContext.deviceKey,
+                spaceKey: space.key
+              });
+
+              // TODO(burdon): Is this the right place to set this state?
+              observable.callback.onAuthenticating?.(invitation);
+              return {
+                spaceKey: space.key,
+                genesisFeedKey: space.genesisFeedKey
+              };
+            },
+
+            authenticate: async ({ authenticationCode: code }) => {
+              log('received authentication request', { authenticationCode: code });
+              authenticationCode = code;
+            },
+
+            presentAdmissionCredentials: async ({ identityKey, deviceKey, controlFeedKey, dataFeedKey }) => {
+              try {
+                // Check authenticated.
+                if (invitation.type === undefined || invitation.type === Invitation.Type.INTERACTIVE) {
+                  if (
+                    invitation.authenticationCode === undefined ||
+                    authenticationCode !== invitation.authenticationCode
+                  ) {
+                    throw new Error('authentication code not set');
+                  }
+                }
+
+                log('writing guest credentials', { host: this._signingContext.deviceKey, guest: deviceKey });
+                // TODO(burdon): Check if already admitted.
+                await writeMessages(
+                  space.controlPipeline.writer,
+                  await createAdmissionCredentials(
+                    this._signingContext.credentialSigner,
+                    identityKey,
+                    deviceKey,
+                    space.key,
+                    controlFeedKey,
+                    dataFeedKey
+                  )
+                );
+
+                // Updating credentials complete.
+                complete.wake(deviceKey);
+              } catch (err) {
+                // TODO(burdon): Generic RPC callback to report error to client.
+                observable.callback.onError(err);
+                throw err; // Propagate error to guest.
+              }
+            }
+          }
+        },
+        port
+      });
+
+      try {
+        await peer.open();
+        log('connected', { host: this._signingContext.deviceKey });
+        observable.callback.onConnected?.(invitation);
+        const deviceKey = await complete.wait({ timeout });
+        log('admitted guest', { host: this._signingContext.deviceKey, guest: deviceKey });
+        observable.callback.onSuccess(invitation);
+      } catch (err) {
+        if (!observable.cancelled) {
+          log.error('failed', err);
+          observable.callback.onError(err);
+        }
+      } finally {
+        await sleep(ON_CLOSE_DELAY);
+        await peer.close();
+        await swarmConnection!.close();
+      }
+    });
+
+    setTimeout(async () => {
+      const topic = invitation.swarmKey!;
+      const peerId = PublicKey.random(); // Use anonymous key.
+      swarmConnection = await this._networkManager.openSwarmConnection({
+        topic,
+        peerId: topic,
+        protocol: createProtocolFactory(topic, peerId, [plugin]),
+        topology: new StarTopology(topic)
+      });
+
+      observable.callback.onConnecting?.(invitation);
+    });
+
+    return observable;
+  }
+
+  /**
+   * Waits for the host peer (inviter) to accept our join request.
+   * The local guest peer (invitee) then sends the local space invitation to the host,
+   * which then writes the guest's credentials to the space.
+   */
+  acceptInvitation(invitation: Invitation): AuthenticatingInvitationProvider {
+    let swarmConnection: SwarmConnection | undefined;
+
+    const authenticated = new Trigger<string>();
+    const observable = new AuthenticatingInvitationProvider({
+      onCancel: async () => {
+        await swarmConnection?.close();
+      },
+
+      // TODO(burdon): Consider retry.
+      onAuthenticate: async (code: string) => {
+        authenticated.wake(code);
+      }
+    });
+
+    let connectionCount = 0;
+    const complete = new Trigger();
+    const plugin = createRpcPlugin(async (port) => {
+      const peer = createProtoRpcPeer({
+        requested: {
+          SpaceHostService: schema.getService('dxos.halo.invitations.SpaceHostService')
+        },
+        port
+      });
+
+      try {
+        await peer.open();
+        // TODO(burdon): Bug where guest may create multiple connections.
+        if (++connectionCount > 1) {
+          throw new Error(`multiple connections detected: ${connectionCount}`);
+        }
+
+        log('connected', { guest: this._signingContext.deviceKey });
+        observable.callback.onConnected?.(invitation);
+
+        // 1. Send request.
+        log('sending admission request', { guest: this._signingContext.deviceKey });
+        const { spaceKey, genesisFeedKey } = await peer.rpc.SpaceHostService.requestAdmission();
+
+        // 2. Get authentication code.
+        // TODO(burdon): Test timeout (options for timeouts at different steps).
+        if (invitation.type === undefined || invitation.type === Invitation.Type.INTERACTIVE) {
+          log('waiting for authentication code...');
+          observable.callback.onAuthenticating?.(invitation);
+          const authenticationCode = await authenticated.wait({ timeout: INVITATION_TIMEOUT });
+          log('sending authentication request');
+          await peer.rpc.SpaceHostService.authenticate({ authenticationCode });
+        }
+
+        // 3. Create local space.
+        // TODO(burdon): Abandon if does not complete (otherwise retry will fail).
+        const space = await this._spaceManager.acceptSpace({ spaceKey, genesisFeedKey });
+
+        // 4. Send admission credentials to host (with local space keys).
+        log('presenting admission credentials', { guest: this._signingContext.deviceKey, spaceKey: space.key });
+        await peer.rpc.SpaceHostService.presentAdmissionCredentials({
+          identityKey: this._signingContext.identityKey,
+          deviceKey: this._signingContext.deviceKey,
+          controlFeedKey: space.controlFeedKey,
+          dataFeedKey: space.dataFeedKey
+        });
+
+        // 5. Success.
+        log('admitted by host', { guest: this._signingContext.deviceKey, spaceKey: space.key });
+        complete.wake();
+      } catch (err) {
+        if (!observable.cancelled) {
+          log.warn('failed', err);
+          observable.callback.onError(err);
+        }
+      } finally {
+        await peer.close();
+      }
+    });
+
+    setTimeout(async () => {
+      assert(invitation.swarmKey);
+      const topic = invitation.swarmKey;
+      const peerId = PublicKey.random(); // Use anonymous key.
+      swarmConnection = await this._networkManager.openSwarmConnection({
+        topic,
+        peerId: PublicKey.random(),
+        protocol: createProtocolFactory(topic, peerId, [plugin]),
+        topology: new StarTopology(topic)
+      });
+
+      observable.callback.onConnecting?.(invitation);
+      await complete.wait();
+      observable.callback.onSuccess(invitation);
+      await swarmConnection.close();
+    });
+
+    return observable;
+  }
+}

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

@@ -0,0 +1,16 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import { PublicKey } from '@dxos/keys';
+
+import { AbstractInvitationsProxy } from './invitations-proxy';
+
+/**
+ * Adapts invitation service observable to client/service stream.
+ */
+export class SpaceInvitationsProxy extends AbstractInvitationsProxy<PublicKey> {
+  createInvitationObject(spaceKey: PublicKey) {
+    return { spaceKey };
+  }
+}