@dxos/client-services 0.1.4 → 0.1.6

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

@@ -0,0 +1,255 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import assert from 'assert';
+
+import { sleep, Trigger } from '@dxos/async';
+import { generatePasscode } from '@dxos/credentials';
+import { failUndefined } from '@dxos/debug';
+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 { IdentityManager } from '../identity';
+import {
+  AuthenticatingInvitationProvider,
+  InvitationObservable,
+  InvitationObservableProvider,
+  AUTHENTICATION_CODE_LENGTH,
+  INVITATION_TIMEOUT,
+  ON_CLOSE_DELAY
+} from './invitations';
+import { AbstractInvitationsHandler, InvitationsOptions } from './invitations-handler';
+
+/**
+ * Handles the life-cycle of Halo invitations between peers.
+ */
+// TODO(dmaretskyi): Split into Host and Guest parts.
+export class HaloInvitationsHandler extends AbstractInvitationsHandler {
+  // prettier-ignore
+  constructor(
+    networkManager: NetworkManager,
+    private readonly _identityManager: IdentityManager
+  ) {
+    super(networkManager);
+  }
+
+  /**
+   * Creates an invitation and listens for a join request from the invited (guest) peer.
+   */
+  createInvitation(context: void, options?: InvitationsOptions): InvitationObservable {
+    let swarmConnection: SwarmConnection | undefined;
+    const { type, timeout = INVITATION_TIMEOUT } = options ?? {};
+    assert(type !== Invitation.Type.OFFLINE);
+    const identity = this._identityManager.identity ?? failUndefined();
+
+    const invitation: Invitation = {
+      type,
+      invitationId: PublicKey.random().toHex(),
+      swarmKey: PublicKey.random(),
+      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: {
+          HaloHostService: schema.getService('dxos.halo.invitations.HaloHostService')
+        },
+        handlers: {
+          HaloHostService: {
+            requestAdmission: async () => {
+              log('responding with admission offer', {
+                host: identity.deviceKey
+              });
+
+              // TODO(burdon): Is this the right place to set this state?
+              observable.callback.onAuthenticating?.(invitation);
+              return {
+                identityKey: identity.identityKey,
+                haloSpaceKey: identity.haloSpaceKey,
+                genesisFeedKey: identity.haloGenesisFeedKey
+              };
+            },
+
+            authenticate: async ({ authenticationCode: code }) => {
+              log('received authentication request', { authenticationCode: code });
+              authenticationCode = code;
+            },
+
+            // TODO(burdon): Not used: controlFeedKey, dataFeedKey.
+            presentAdmissionCredentials: async (credentials) => {
+              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: identity.deviceKey, guest: credentials.deviceKey });
+                // TODO(burdon): Check if already admitted.
+                await identity.admitDevice(credentials);
+
+                // Updating credentials complete.
+                complete.wake(credentials.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: identity.deviceKey });
+        observable.callback.onConnected?.(invitation);
+        const deviceKey = await complete.wait({ timeout });
+        log('admitted guest', { host: identity.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 halo invitation to the host,
+   * which then writes the guest's credentials to the halo.
+   */
+  acceptInvitation(invitation: Invitation, options?: InvitationsOptions): AuthenticatingInvitationProvider {
+    const { timeout = INVITATION_TIMEOUT } = options ?? {};
+    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<PublicKey>();
+    const plugin = createRpcPlugin(async (port) => {
+      const peer = createProtoRpcPeer({
+        requested: {
+          HaloHostService: schema.getService('dxos.halo.invitations.HaloHostService')
+        },
+        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');
+        observable.callback.onConnected?.(invitation);
+
+        // 1. Send request.
+        log('sending admission request');
+        const { identityKey, haloSpaceKey, genesisFeedKey } = await peer.rpc.HaloHostService.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('guest waiting for authentication code...');
+          observable.callback.onAuthenticating?.(invitation);
+          const authenticationCode = await authenticated.wait({ timeout });
+          log('sending authentication request');
+          await peer.rpc.HaloHostService.authenticate({ authenticationCode });
+        }
+
+        // 3. Create local identity.
+        // TODO(burdon): Abandon if does not complete (otherwise retry will fail).
+        const identity = await this._identityManager.acceptIdentity({
+          identityKey,
+          haloSpaceKey,
+          haloGenesisFeedKey: genesisFeedKey
+        });
+
+        // 4. Send admission credentials to host (with local identity keys).
+        log('presenting admission credentials', { guest: identity.deviceKey, identityKey });
+        await peer.rpc.HaloHostService.presentAdmissionCredentials(identity.getAdmissionCredentials());
+
+        // 5. Success.
+        log('admitted by host', { guest: identity.deviceKey, identityKey });
+        complete.wake(identityKey);
+      } 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);
+      invitation.identityKey = await complete.wait();
+      observable.callback.onSuccess(invitation);
+      await swarmConnection.close();
+    });
+
+    return observable;
+  }
+}

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

@@ -0,0 +1,14 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import { AbstractInvitationsProxy } from './invitations-proxy';
+
+/**
+ * Adapts invitation service observable to client/service stream.
+ */
+export class HaloInvitationsProxy extends AbstractInvitationsProxy {
+  getInvitationOptions() {
+    return {};
+  }
+}

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

@@ -0,0 +1,96 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import assert from 'assert';
+import { expect } from 'chai';
+import waitForExpect from 'wait-for-expect';
+
+import { asyncChain, Trigger } from '@dxos/async';
+import { raise } from '@dxos/debug';
+import { Invitation, HaloInvitationsService } from '@dxos/protocols/proto/dxos/client/services';
+import { afterTest } from '@dxos/testutils';
+
+import { ServiceContext } from '../services';
+import { createPeers } from '../testing';
+import { HaloInvitationsProxy } from './halo-invitations-proxy';
+import { HaloInvitationsServiceImpl } from './halo-invitations-service';
+
+const closeAfterTest = async (peer: ServiceContext) => {
+  afterTest(() => peer.close());
+  return peer;
+};
+
+describe('services/halo-invitation-service', function () {
+  it('creates identity and invites peer', async function () {
+    const [host, guest] = await asyncChain<ServiceContext>([closeAfterTest])(createPeers(2));
+
+    await host.identityManager.createIdentity();
+    expect(host.identityManager.identity!.authorizedDeviceKeys.size).to.eq(1);
+
+    // prettier-ignore
+    const service1: HaloInvitationsService = new HaloInvitationsServiceImpl(
+      host.identityManager,
+      host.haloInvitations
+    );
+    // prettier-ignore
+    const service2: HaloInvitationsService = new HaloInvitationsServiceImpl(
+      guest.identityManager,
+      guest.haloInvitations
+    );
+
+    const success1 = new Trigger<Invitation>();
+    const success2 = new Trigger<Invitation>();
+
+    const authenticationCode = new Trigger<string>();
+
+    {
+      const proxy1 = new HaloInvitationsProxy(service1);
+      const observable1 = proxy1.createInvitation();
+      observable1.subscribe({
+        onConnecting: (invitation: Invitation) => {
+          const proxy2 = new HaloInvitationsProxy(service2);
+          const observable2 = proxy2.acceptInvitation(invitation);
+          observable2.subscribe({
+            onAuthenticating: async () => {
+              await observable2.authenticate(await authenticationCode.wait());
+            },
+            onSuccess: (invitation: Invitation) => {
+              // TODO(burdon): No device.
+              // expect(guest.identityManager.identity!.authorizedDeviceKeys.size).to.eq(1);
+              success2.wake(invitation);
+            },
+            onError: (err: Error) => raise(new Error(err.message))
+          });
+        },
+        onConnected: (invitation: Invitation) => {
+          assert(invitation.authenticationCode);
+          authenticationCode.wake(invitation.authenticationCode);
+        },
+        onSuccess: (invitation: Invitation) => {
+          success1.wake(invitation);
+        },
+        onCancelled: () => raise(new Error()),
+        onTimeout: (err: Error) => raise(new Error(err.message)),
+        onError: (err: Error) => raise(new Error(err.message))
+      });
+    }
+
+    // Check same identity.
+    const [invitation1, invitation2] = await Promise.all([success1.wait(), success2.wait()]);
+    expect(invitation1.identityKey).not.to.exist;
+    expect(invitation2.identityKey).to.deep.eq(host.identityManager.identity!.identityKey);
+    expect(invitation2.identityKey).to.deep.eq(guest.identityManager.identity!.identityKey);
+    expect(invitation1.state).to.eq(Invitation.State.SUCCESS);
+    expect(invitation2.state).to.eq(Invitation.State.SUCCESS);
+
+    // Check devices.
+    // TODO(burdon): Incorrect number of devices.
+    await waitForExpect(() => {
+      expect(host.identityManager.identity!.authorizedDeviceKeys.size).to.eq(2);
+      expect(guest.identityManager.identity!.authorizedDeviceKeys.size).to.eq(2);
+    });
+    // console.log(host.identityManager.identity!.authorizedDeviceKeys.size);
+    // console.log(guest.identityManager.identity!.authorizedDeviceKeys.size);
+  });
+});

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

@@ -0,0 +1,24 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import { Invitation } from '@dxos/protocols/proto/dxos/client/services';
+
+import { IdentityManager } from '../identity';
+import { InvitationsHandler } from './invitations-handler';
+import { AbstractInvitationsService } from './invitations-service';
+
+/**
+ * Adapts invitation service observable to client/service stream.
+ */
+export class HaloInvitationsServiceImpl extends AbstractInvitationsService {
+  // prettier-ignore
+  constructor (
+    identityManager: IdentityManager,
+    private readonly invitationsHandler: InvitationsHandler
+  ) {
+    super(identityManager, () => invitationsHandler);
+  }
+
+  override getContext(invitation: Invitation) {}
+}

package/src/packlets/invitations/index.ts

@@ -3,9 +3,13 @@
 //
 
 export * from './encoder';
-export * from './halo-invitations';
+export * from './halo-invitations-handler';
+export * from './halo-invitations-proxy';
+export * from './halo-invitations-service';
 export * from './invitations';
+export * from './invitations-handler';
 export * from './invitations-proxy';
+export * from './invitations-service';
 export * from './space-invitations-handler';
 export * from './space-invitations-proxy';
 export * from './space-invitations-service';

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

@@ -0,0 +1,59 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import { NetworkManager } from '@dxos/network-manager';
+import { Invitation } from '@dxos/protocols/proto/dxos/client/services';
+
+import { AuthenticatingInvitationObservable, InvitationObservable } from './invitations';
+
+export type InvitationsOptions = {
+  type?: Invitation.Type;
+  timeout?: number;
+};
+
+/**
+ * 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 = void> {
+  createInvitation(context: T, options?: InvitationsOptions): InvitationObservable;
+  acceptInvitation(invitation: Invitation, options?: InvitationsOptions): AuthenticatingInvitationObservable;
+}
+
+/**
+ * Base class for Halo/Space invitations handlers.
+ */
+// TODO(burdon): Extract common functionality.
+export abstract class AbstractInvitationsHandler<T = void> implements InvitationsHandler<T> {
+  // prettier-ignore
+  protected constructor(
+    protected readonly _networkManager: NetworkManager
+  ) {}
+
+  abstract createInvitation(context: T, options?: InvitationsOptions): InvitationObservable;
+  abstract acceptInvitation(invitation: Invitation, options?: InvitationsOptions): AuthenticatingInvitationObservable;
+}

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

@@ -7,32 +7,34 @@ import assert from 'assert';
 import { observableError } from '@dxos/async';
 import { Stream } from '@dxos/codec-protobuf';
 import { log } from '@dxos/log';
-import { Invitation, InvitationsService } from '@dxos/protocols/proto/dxos/client/services';
+import { Invitation } from '@dxos/protocols/proto/dxos/client/services';
 
 import {
   AuthenticatingInvitationObservable,
   AuthenticatingInvitationProvider,
-  CreateInvitationsOptions,
-  InvitationsProxy,
   InvitationObservable,
-  InvitationObservableProvider
+  InvitationObservableProvider,
+  InvitationsService
 } from './invitations';
+import { InvitationsOptions, InvitationsHandler } from './invitations-handler';
 
 /**
  * Adapts invitations service observable to client/service stream.
- * Used by both HALO and Spaces client/service interfaces.
+ * Common base class for HALO and Spaces implementations.
  */
-export abstract class AbstractInvitationsProxy<T> implements InvitationsProxy<T> {
+export interface InvitationsProxy<T = void> extends InvitationsHandler<T> {
+  getInvitationOptions(context: T): Invitation;
+}
+
+export abstract class AbstractInvitationsProxy<T = void> implements InvitationsProxy<T> {
   // prettier-ignore
   constructor(
     private readonly _invitationsService: InvitationsService
   ) {}
 
-  abstract createInvitationObject(context: T): Invitation;
-
-  createInvitation(context: T, options?: CreateInvitationsOptions): InvitationObservable {
-    assert(context);
+  abstract getInvitationOptions(context: T): Invitation;
 
+  createInvitation(context: T, options?: InvitationsOptions): InvitationObservable {
     let invitationId: string;
     const observable = new InvitationObservableProvider(async () => {
       if (invitationId) {
@@ -40,7 +42,7 @@ export abstract class AbstractInvitationsProxy<T> implements InvitationsProxy<T>
       }
     });
 
-    const invitation = { ...this.createInvitationObject(context), ...options };
+    const invitation: Invitation = { ...this.getInvitationOptions(context), ...options };
     const stream: Stream<Invitation> = this._invitationsService.createInvitation(invitation);
 
     stream.subscribe(
@@ -90,7 +92,7 @@ export abstract class AbstractInvitationsProxy<T> implements InvitationsProxy<T>
     return observable;
   }
 
-  acceptInvitation(invitation: Invitation): AuthenticatingInvitationObservable {
+  acceptInvitation(invitation: Invitation, options?: InvitationsOptions): AuthenticatingInvitationObservable {
     assert(invitation && invitation.swarmKey);
 
     const observable = new AuthenticatingInvitationProvider({
@@ -107,7 +109,7 @@ export abstract class AbstractInvitationsProxy<T> implements InvitationsProxy<T>
       }
     });
 
-    const stream: Stream<Invitation> = this._invitationsService.acceptInvitation(invitation);
+    const stream: Stream<Invitation> = this._invitationsService.acceptInvitation({ ...invitation, ...options });
 
     stream.subscribe(
       (invitation: Invitation) => {