@dxos/client-services 0.1.13 → 0.1.14

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

@@ -2,29 +2,37 @@
 // Copyright 2022 DXOS.org
 //
 
-import assert from 'assert';
+import assert from 'node:assert';
 
-import { sleep, Trigger } from '@dxos/async';
+import { scheduleTask, sleep, Trigger } from '@dxos/async';
+import { Context } from '@dxos/context';
 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 { createTeleportProtocolFactory, NetworkManager, StarTopology } from '@dxos/network-manager';
 import { schema } from '@dxos/protocols';
 import { Invitation } from '@dxos/protocols/proto/dxos/client/services';
-import { createProtoRpcPeer } from '@dxos/rpc';
+import {
+  AuthenticationRequest,
+  AuthenticationResponse,
+  HaloAdmissionCredentials,
+  HaloAdmissionOffer,
+  HaloHostService
+} from '@dxos/protocols/proto/dxos/halo/invitations';
+import { ExtensionContext } from '@dxos/teleport';
 
 import { IdentityManager } from '../identity';
 import {
   AuthenticatingInvitationProvider,
+  AUTHENTICATION_CODE_LENGTH,
   CancellableInvitationObservable,
   InvitationObservableProvider,
-  AUTHENTICATION_CODE_LENGTH,
   INVITATION_TIMEOUT,
   ON_CLOSE_DELAY
 } from './invitations';
 import { AbstractInvitationsHandler, InvitationsOptions } from './invitations-handler';
+import { RpcExtension } from './rpc-extension';
 
 /**
  * Handles the life-cycle of Halo invitations between peers.
@@ -43,11 +51,11 @@ export class HaloInvitationsHandler extends AbstractInvitationsHandler {
    * Creates an invitation and listens for a join request from the invited (guest) peer.
    */
   createInvitation(context: void, options?: InvitationsOptions): CancellableInvitationObservable {
-    let swarmConnection: SwarmConnection | undefined;
     const { type, timeout = INVITATION_TIMEOUT, swarmKey } = options ?? {};
     assert(type !== Invitation.Type.OFFLINE);
     const identity = this._identityManager.identity ?? failUndefined();
 
+    // TODO(dmaretskyi): Add invitation kind: halo/space.
     const invitation: Invitation = {
       type,
       invitationId: PublicKey.random().toHex(),
@@ -55,97 +63,103 @@ export class HaloInvitationsHandler extends AbstractInvitationsHandler {
       authenticationCode: generatePasscode(AUTHENTICATION_CODE_LENGTH)
     };
 
+    const ctx = new Context({
+      onError: (err) => {
+        void ctx.dispose();
+        observable.callback.onError(err);
+      }
+    });
+
     // TODO(burdon): Stop anything pending.
     const observable = new InvitationObservableProvider(async () => {
-      await swarmConnection?.close();
+      await ctx.dispose();
     });
 
     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')
+
+    // Called for every connecting peer.
+    const createExtension = (): HostHaloInvitationExtension => {
+      const hostInvitationExtension = new HostHaloInvitationExtension({
+        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
+          };
         },
-        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.
+        authenticate: async ({ authenticationCode: code }) => {
+          log('received authentication request', { authenticationCode: code });
+          authenticationCode = code;
+          return { status: AuthenticationResponse.Status.OK };
+        },
+
+        // TODO(burdon): Not used: controlFeedKey, dataFeedKey.
+        presentAdmissionCredentials: async (credentials) => {
+          try {
+            // Check authenticated.
+            if (invitation.type !== Invitation.Type.INTERACTIVE_TESTING) {
+              if (invitation.authenticationCode === undefined || invitation.authenticationCode !== authenticationCode) {
+                throw new Error(`invalid authentication code: ${authenticationCode}`);
               }
             }
+
+            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);
+        onOpen: () => {
+          scheduleTask(ctx, async () => {
+            try {
+              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 {
+              // NOTE: If we close immediately after `complete` trigger finishes, Guest won't receive the reply to the last RPC.
+              // TODO(dmaretskyi): Implement a soft-close which waits for the last connection to terminate before closing.
+              await sleep(ON_CLOSE_DELAY);
+              await ctx.dispose();
+            }
+          });
         }
-      } finally {
-        await sleep(ON_CLOSE_DELAY);
-        await peer.close();
-        await swarmConnection!.close();
-      }
-    });
+      });
+      return hostInvitationExtension;
+    };
 
-    setTimeout(async () => {
+    scheduleTask(ctx, async () => {
       const topic = invitation.swarmKey!;
-      const peerId = PublicKey.random(); // Use anonymous key.
-      swarmConnection = await this._networkManager.joinSwarm({
+      const swarmConnection = await this._networkManager.joinSwarm({
         topic,
         peerId: topic,
-        protocol: createProtocolFactory(topic, peerId, [plugin]),
+        protocolProvider: createTeleportProtocolFactory(async (teleport) => {
+          teleport.addExtension('dxos.halo.invitations', createExtension());
+        }),
         topology: new StarTopology(topic)
       });
+      ctx.onDispose(() => swarmConnection.close());
 
       observable.callback.onConnecting?.(invitation);
     });
@@ -160,12 +174,18 @@ export class HaloInvitationsHandler extends AbstractInvitationsHandler {
    */
   acceptInvitation(invitation: Invitation, options?: InvitationsOptions): AuthenticatingInvitationProvider {
     const { timeout = INVITATION_TIMEOUT } = options ?? {};
-    let swarmConnection: SwarmConnection | undefined;
+
+    const ctx = new Context({
+      onError: (err) => {
+        void ctx.dispose();
+        observable.callback.onError(err);
+      }
+    });
 
     const authenticated = new Trigger<string>();
     const observable = new AuthenticatingInvitationProvider({
       onCancel: async () => {
-        await swarmConnection?.close();
+        await ctx.dispose();
       },
 
       // TODO(burdon): Consider retry.
@@ -176,80 +196,157 @@ export class HaloInvitationsHandler extends AbstractInvitationsHandler {
 
     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}`);
-        }
+    const createExtension = (): GuestHaloInvitationExtension => {
+      const extension = new GuestHaloInvitationExtension({
+        onOpen: () => {
+          scheduleTask(ctx, async () => {
+            try {
+              // 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);
+              log('connected');
+              observable.callback.onConnected?.(invitation);
 
-        // 1. Send request.
-        log('sending admission request');
-        const { identityKey, haloSpaceKey, genesisFeedKey } = await peer.rpc.HaloHostService.requestAdmission();
+              // 1. Send request.
+              log('sending admission request');
+              const { identityKey, haloSpaceKey, genesisFeedKey } =
+                await extension.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 });
-        }
+              // 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 extension.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);
+              // 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 extension.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('auth failed', err);
+                observable.callback.onError(err);
+              }
+            } finally {
+              await ctx.dispose();
+            }
+          });
         }
-      } finally {
-        await peer.close();
-      }
-    });
+      });
+      return extension;
+    };
 
-    setTimeout(async () => {
+    scheduleTask(ctx, async () => {
       assert(invitation.swarmKey);
       const topic = invitation.swarmKey;
-      const peerId = PublicKey.random(); // Use anonymous key.
-      swarmConnection = await this._networkManager.joinSwarm({
+      const swarmConnection = await this._networkManager.joinSwarm({
         topic,
         peerId: PublicKey.random(),
-        protocol: createProtocolFactory(topic, peerId, [plugin]),
+        protocolProvider: createTeleportProtocolFactory(async (teleport) => {
+          teleport.addExtension('dxos.halo.invitations', createExtension());
+        }),
         topology: new StarTopology(topic)
       });
+      ctx.onDispose(() => swarmConnection.close());
 
       observable.callback.onConnecting?.(invitation);
       invitation.identityKey = await complete.wait();
       observable.callback.onSuccess(invitation);
-      await swarmConnection.close();
+      await ctx.dispose();
     });
 
     return observable;
   }
 }
+
+type HostHaloInvitationExtensionCallbacks = {
+  requestAdmission: () => Promise<HaloAdmissionOffer>;
+  authenticate: (request: AuthenticationRequest) => Promise<AuthenticationResponse>;
+  presentAdmissionCredentials: (request: HaloAdmissionCredentials) => Promise<void>;
+  // Deliberately not async to not block the extensions opening.
+  onOpen: () => void;
+};
+
+/**
+ * Host's side for a connection to a concrete peer in p2p network during invitation.
+ */
+class HostHaloInvitationExtension extends RpcExtension<{}, { HaloHostService: HaloHostService }> {
+  constructor(private readonly _callbacks: HostHaloInvitationExtensionCallbacks) {
+    super({
+      exposed: {
+        HaloHostService: schema.getService('dxos.halo.invitations.HaloHostService')
+      }
+    });
+  }
+
+  protected override async getHandlers(): Promise<{ HaloHostService: HaloHostService }> {
+    return {
+      // TODO(dmaretskyi): For now this is just forwarding the data to callbacks since we don't have session-specific logic.
+      // Perhaps in the future we will have more complex logic here.
+      HaloHostService: {
+        requestAdmission: async () => {
+          return this._callbacks.requestAdmission();
+        },
+
+        authenticate: async (credentials) => {
+          return this._callbacks.authenticate(credentials);
+        },
+
+        // TODO(burdon): Not used: controlFeedKey, dataFeedKey.
+        presentAdmissionCredentials: async (credentials) => {
+          return this._callbacks.presentAdmissionCredentials(credentials);
+        }
+      }
+    };
+  }
+
+  override async onOpen(context: ExtensionContext) {
+    await super.onOpen(context);
+    this._callbacks.onOpen();
+  }
+}
+
+type GuestHaloInvitationExtensionCallbacks = {
+  // Deliberately not async to not block the extensions opening.
+  onOpen: () => void;
+};
+
+/**
+ * Guest's side for a connection to a concrete peer in p2p network during invitation.
+ */
+class GuestHaloInvitationExtension extends RpcExtension<{ HaloHostService: HaloHostService }, {}> {
+  constructor(private readonly _callbacks: GuestHaloInvitationExtensionCallbacks) {
+    super({
+      requested: {
+        HaloHostService: schema.getService('dxos.halo.invitations.HaloHostService')
+      }
+    });
+  }
+
+  protected override async getHandlers() {
+    return {};
+  }
+
+  override async onOpen(context: ExtensionContext) {
+    await super.onOpen(context);
+    this._callbacks.onOpen();
+  }
+}

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

@@ -2,14 +2,14 @@
 // Copyright 2022 DXOS.org
 //
 
-import assert from 'assert';
 import { expect } from 'chai';
+import assert from 'node:assert';
 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 { describe, test, afterTest } from '@dxos/test';
 
 import { ServiceContext } from '../services';
 import { createPeers } from '../testing';
@@ -21,8 +21,8 @@ const closeAfterTest = async (peer: ServiceContext) => {
   return peer;
 };
 
-describe('services/halo-invitation-service', function () {
-  it('creates identity and invites peer', async function () {
+describe('services/halo-invitation-service', () => {
+  test('creates identity and invites peer', async () => {
     const [host, guest] = await asyncChain<ServiceContext>([closeAfterTest])(createPeers(2));
 
     await host.identityManager.createIdentity();

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

@@ -20,26 +20,26 @@ export type InvitationsOptions = {
  * Handles the life-cycle of Space invitations between peers.
  *
  * Host
- * - Creates an invitation containing a swarm topic.
+ * - Creates an invitation containing a swarm topic (which can be shared via a URL, QR code, or direct message).
  * - Joins the swarm with the topic and waits for guest's admission request.
- * - Responds with admission offer then waits for guest's credentials.
+ * - Wait for guest to authenticate with OTP.
+ * - Waits for guest to present credentials (containing local device and feed keys).
  * - 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.
+ * - Sends authentication OTP.
  * - If Space handler then creates a local cloned space (with genesis block).
- * - Sends admission credentials (containing local device and feed keys).
+ * - Sends admission credentials.
  *
  * TODO(burdon): Show proxy/service relationship and reference design doc/diagram.
  *
  *  ```
- *  [Guest]                                                  [Host]
- *   |-------------------------------------RequestAdmission-->|
- *   |<--AdmissionOffer---------------------------------------|
- *   |
- *   |--------------------------PresentAdmissionCredentials-->|
+ *  [Guest]                                          [Host]
+ *   |-----------------------------RequestAdmission-->|
+ *   |-------------------------------[Authenticate]-->|
+ *   |------------------PresentAdmissionCredentials-->|
  *  ```
  */
 export interface InvitationsHandler<T = void> {

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

@@ -2,7 +2,7 @@
 // Copyright 2022 DXOS.org
 //
 
-import assert from 'assert';
+import assert from 'node:assert';
 
 import { observableError } from '@dxos/async';
 import { Stream } from '@dxos/codec-protobuf';

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

@@ -2,7 +2,7 @@
 // Copyright 2022 DXOS.org
 //
 
-import assert from 'assert';
+import assert from 'node:assert';
 
 import { TimeoutError } from '@dxos/async';
 import { Stream } from '@dxos/codec-protobuf';

package/src/packlets/invitations/invitations.ts

@@ -2,7 +2,7 @@
 // Copyright 2022 DXOS.org
 //
 
-import assert from 'assert';
+import assert from 'node:assert';
 
 import {
   AsyncEvents,

package/src/packlets/invitations/rpc-extension.ts

@@ -0,0 +1,56 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import { createProtoRpcPeer, ProtoRpcPeer, ProtoRpcPeerOptions } from '@dxos/rpc';
+import { ExtensionContext, TeleportExtension } from '@dxos/teleport';
+
+export abstract class RpcExtension<Client, Server> implements TeleportExtension {
+  private _extensionContext!: ExtensionContext;
+  private _rpc!: ProtoRpcPeer<Client>;
+
+  constructor(private readonly _params: Omit<ProtoRpcPeerOptions<Client, Server>, 'port' | 'handlers'>) {}
+
+  get initiator() {
+    return this._extensionContext.initiator;
+  }
+
+  get localPeerId() {
+    return this._extensionContext.localPeerId;
+  }
+
+  get remotePeerId() {
+    return this._extensionContext.remotePeerId;
+  }
+
+  get rpc(): Client {
+    return this._rpc.rpc;
+  }
+
+  protected abstract getHandlers(): Promise<Server>;
+
+  async onOpen(context: ExtensionContext): Promise<void> {
+    this._extensionContext = context;
+
+    const handlers = await this.getHandlers();
+
+    const port = context.createPort('rpc', {
+      contentType: 'application/x-protobuf; messageType="dxos.rpc.Message"'
+    });
+    this._rpc = createProtoRpcPeer({
+      ...this._params,
+      handlers,
+      port
+    });
+
+    await this._rpc.open();
+  }
+
+  async onClose(err?: Error | undefined): Promise<void> {
+    await this._rpc.close();
+  }
+
+  close() {
+    this._extensionContext.close();
+  }
+}