@dxos/client-services 0.5.1-next.5e6b3f6 → 0.5.1-next.65aaa36

package/src/packlets/invitations/{invitation-extension.ts → invitation-host-extension.ts}

@@ -2,10 +2,10 @@
 // Copyright 2022 DXOS.org
 //
 
-import { Trigger } from '@dxos/async';
+import { type Mutex, type MutexGuard, Trigger, scheduleTask } from '@dxos/async';
 import { cancelWithContext, Context } from '@dxos/context';
 import { randomBytes, verify } from '@dxos/crypto';
-import { invariant } from '@dxos/invariant';
+import { invariant, InvariantViolation } from '@dxos/invariant';
 import { PublicKey } from '@dxos/keys';
 import { log } from '@dxos/log';
 import { InvalidInvitationExtensionRoleError, schema, trace } from '@dxos/protocols';
@@ -15,25 +15,26 @@ import {
   type AdmissionRequest,
   type AdmissionResponse,
   AuthenticationResponse,
-  type IntroductionRequest,
   type InvitationHostService,
   Options,
 } from '@dxos/protocols/proto/dxos/halo/invitations';
 import { type ExtensionContext, RpcExtension } from '@dxos/teleport';
 
+import { stateToString, tryAcquireBeforeContextDisposed } from './utils';
+
 /// Timeout for the options exchange.
 const OPTIONS_TIMEOUT = 10_000;
 
 export const MAX_OTP_ATTEMPTS = 3;
 
 type InvitationHostExtensionCallbacks = {
+  activeInvitation: Invitation | null;
+
   // Deliberately not async to not block the extensions opening.
-  onOpen: () => void;
+  onOpen: (ctx: Context, extensionCtx: ExtensionContext) => void;
   onError: (error: Error) => void;
 
-  onStateUpdate: (invitation: Invitation) => void;
-
-  resolveInvitation: (request: IntroductionRequest) => Promise<Invitation | undefined>;
+  onStateUpdate: (newState: Invitation.State) => void;
 
   admit: (request: AdmissionRequest) => Promise<AdmissionResponse>;
 };
@@ -54,8 +55,6 @@ export class InvitationHostExtension extends RpcExtension<
 
   private _challenge?: Buffer = undefined;
 
-  public invitation?: Invitation = undefined;
-
   public guestProfile?: ProfileDocument = undefined;
 
   public authenticationPassed = false;
@@ -70,7 +69,15 @@ export class InvitationHostExtension extends RpcExtension<
    */
   public completedTrigger = new Trigger<PublicKey>();
 
-  constructor(private readonly _callbacks: InvitationHostExtensionCallbacks) {
+  /**
+   * Held to allow only one invitation flow at a time to be active.
+   */
+  private _invitationFlowLock: MutexGuard | null = null;
+
+  constructor(
+    private readonly _invitationFlowMutex: Mutex,
+    private readonly _callbacks: InvitationHostExtensionCallbacks,
+  ) {
     super({
       requested: {
         InvitationHostService: schema.getService('dxos.halo.invitations.InvitationHostService'),
@@ -81,6 +88,10 @@ export class InvitationHostExtension extends RpcExtension<
     });
   }
 
+  public hasFlowLock(): boolean {
+    return this._invitationFlowLock != null;
+  }
+
   protected override async getHandlers(): Promise<{ InvitationHostService: InvitationHostService }> {
     return {
       // TODO(dmaretskyi): For now this is just forwarding the data to callbacks since we don't have session-specific logic.
@@ -98,30 +109,29 @@ export class InvitationHostExtension extends RpcExtension<
           const traceId = PublicKey.random().toHex();
           log.trace('dxos.sdk.invitation-handler.host.introduce', trace.begin({ id: traceId }));
 
-          const invitation = await this._callbacks.resolveInvitation(request);
-          if (!invitation) {
-            log.warn('invitation not found', { invitationId });
-            this._callbacks.onError(new Error('Invitation not found.'));
+          const invitation = this._requireActiveInvitation();
+          this._assertInvitationState(Invitation.State.CONNECTED);
+
+          if (invitationId !== invitation?.invitationId) {
+            log.warn('incorrect invitationId', { expected: invitation.invitationId, actual: invitationId });
+            this._callbacks.onError(new Error('Incorrect invitationId.'));
+            scheduleTask(this._ctx, () => this.close());
             // TODO(dmaretskyi): Better error handling.
             return {
               authMethod: Invitation.AuthMethod.NONE,
             };
           }
-          this.invitation = invitation;
 
-          log('guest introduced itself', {
-            guestProfile: profile,
-          });
+          log('guest introduced themselves', { guestProfile: profile });
           this.guestProfile = profile;
-
-          this._callbacks.onStateUpdate({ ...this.invitation, state: Invitation.State.READY_FOR_AUTHENTICATION });
+          this._callbacks.onStateUpdate(Invitation.State.READY_FOR_AUTHENTICATION);
 
           this._challenge =
-            this.invitation.authMethod === Invitation.AuthMethod.KNOWN_PUBLIC_KEY ? randomBytes(32) : undefined;
+            invitation.authMethod === Invitation.AuthMethod.KNOWN_PUBLIC_KEY ? randomBytes(32) : undefined;
 
           log.trace('dxos.sdk.invitation-handler.host.introduce', trace.end({ id: traceId }));
           return {
-            authMethod: this.invitation.authMethod,
+            authMethod: invitation.authMethod,
             challenge: this._challenge,
           };
         },
@@ -129,21 +139,25 @@ export class InvitationHostExtension extends RpcExtension<
         authenticate: async ({ authCode: code, signedChallenge }) => {
           const traceId = PublicKey.random().toHex();
           log.trace('dxos.sdk.invitation-handler.host.authenticate', trace.begin({ id: traceId }));
+
+          const invitation = this._requireActiveInvitation();
           log('received authentication request', { authCode: code });
           let status = AuthenticationResponse.Status.OK;
 
-          invariant(this.invitation, 'Invitation is not set.');
-          switch (this.invitation.authMethod) {
+          this._assertInvitationState([Invitation.State.AUTHENTICATING, Invitation.State.READY_FOR_AUTHENTICATION]);
+          this._callbacks.onStateUpdate(Invitation.State.AUTHENTICATING);
+
+          switch (invitation.authMethod) {
             case Invitation.AuthMethod.NONE: {
               log('authentication not required');
               return { status: AuthenticationResponse.Status.OK };
             }
 
             case Invitation.AuthMethod.SHARED_SECRET: {
-              if (this.invitation.authCode) {
+              if (invitation.authCode) {
                 if (this.authenticationRetry++ > MAX_OTP_ATTEMPTS) {
                   status = AuthenticationResponse.Status.INVALID_OPT_ATTEMPTS;
-                } else if (code !== this.invitation.authCode) {
+                } else if (code !== invitation.authCode) {
                   status = AuthenticationResponse.Status.INVALID_OTP;
                 } else {
                   this.authenticationPassed = true;
@@ -153,7 +167,7 @@ export class InvitationHostExtension extends RpcExtension<
             }
 
             case Invitation.AuthMethod.KNOWN_PUBLIC_KEY: {
-              if (!this.invitation.guestKeypair) {
+              if (!invitation.guestKeypair) {
                 status = AuthenticationResponse.Status.INTERNAL_ERROR;
                 break;
               }
@@ -162,7 +176,7 @@ export class InvitationHostExtension extends RpcExtension<
                 verify(
                   this._challenge,
                   Buffer.from(signedChallenge ?? []),
-                  this.invitation.guestKeypair.publicKey.asBuffer(),
+                  invitation.guestKeypair.publicKey.asBuffer(),
                 );
               if (isSignatureValid) {
                 this.authenticationPassed = true;
@@ -173,12 +187,18 @@ export class InvitationHostExtension extends RpcExtension<
             }
 
             default: {
-              log.error('invalid authentication method', { authMethod: this.invitation.authMethod });
+              log.error('invalid authentication method', { authMethod: invitation.authMethod });
               status = AuthenticationResponse.Status.INTERNAL_ERROR;
               break;
             }
           }
 
+          if (![AuthenticationResponse.Status.OK, AuthenticationResponse.Status.INVALID_OTP].includes(status)) {
+            this._callbacks.onError(new Error(`Authentication failed, with status=${status}`));
+            scheduleTask(this._ctx, () => this.close());
+            return { status };
+          }
+
           log.trace('dxos.sdk.invitation-handler.host.authenticate', trace.end({ id: traceId, data: { status } }));
           return { status };
         },
@@ -186,12 +206,15 @@ export class InvitationHostExtension extends RpcExtension<
         admit: async (request) => {
           const traceId = PublicKey.random().toHex();
           log.trace('dxos.sdk.invitation-handler.host.admit', trace.begin({ id: traceId }));
+          const invitation = this._requireActiveInvitation();
 
           try {
-            invariant(this.invitation, 'Invitation is not set.');
             // Check authenticated.
-            if (isAuthenticationRequired(this.invitation) && !this.authenticationPassed) {
-              throw new Error('Not authenticated');
+            if (isAuthenticationRequired(invitation)) {
+              this._assertInvitationState(Invitation.State.AUTHENTICATING);
+              if (!this.authenticationPassed) {
+                throw new Error('Not authenticated');
+              }
             }
 
             const response = await this._callbacks.admit(request);
@@ -211,100 +234,71 @@ export class InvitationHostExtension extends RpcExtension<
     await super.onOpen(context);
 
     try {
+      log('host acquire lock');
+      this._invitationFlowLock = await tryAcquireBeforeContextDisposed(this._ctx, this._invitationFlowMutex);
+      log('host lock acquired');
+      const lastState = this._requireActiveInvitation().state;
+      this._callbacks.onStateUpdate(Invitation.State.CONNECTING);
       await this.rpc.InvitationHostService.options({ role: Options.Role.HOST });
+      log('options sent');
       await cancelWithContext(this._ctx, this._remoteOptionsTrigger.wait({ timeout: OPTIONS_TIMEOUT }));
+      log('options received');
       if (this._remoteOptions?.role !== Options.Role.GUEST) {
+        // we connected with another host, restore previous real invitation flow status
+        this._callbacks.onStateUpdate(lastState);
         throw new InvalidInvitationExtensionRoleError(undefined, {
           expected: Options.Role.GUEST,
           remoteOptions: this._remoteOptions,
+          remotePeerId: context.remotePeerId,
         });
       }
-
-      this._callbacks.onOpen();
+      this._callbacks.onStateUpdate(Invitation.State.CONNECTED);
+      this._callbacks.onOpen(this._ctx, context);
     } catch (err: any) {
-      this._callbacks.onError(err);
+      if (this._invitationFlowLock != null) {
+        this._callbacks.onError(err);
+      }
+      if (!this._ctx.disposed) {
+        context.close(err);
+      }
     }
   }
 
-  override async onClose() {
-    await this._ctx.dispose();
+  private _requireActiveInvitation(): Invitation {
+    const invitation = this._callbacks.activeInvitation;
+    if (invitation == null) {
+      scheduleTask(this._ctx, () => this.close());
+      throw new Error('Active invitation not found');
+    }
+    return invitation;
   }
-}
-
-type InvitationGuestExtensionCallbacks = {
-  // Deliberately not async to not block the extensions opening.
-  onOpen: (ctx: Context) => void;
-  onError: (error: Error) => void;
-};
-
-/**
- * Guest's side for a connection to a concrete peer in p2p network during invitation.
- */
-export class InvitationGuestExtension extends RpcExtension<
-  { InvitationHostService: InvitationHostService },
-  { InvitationHostService: InvitationHostService }
-> {
-  private _ctx = new Context();
-  private _remoteOptions?: Options;
-  private _remoteOptionsTrigger = new Trigger();
 
-  constructor(private readonly _callbacks: InvitationGuestExtensionCallbacks) {
-    super({
-      requested: {
-        InvitationHostService: schema.getService('dxos.halo.invitations.InvitationHostService'),
-      },
-      exposed: {
-        InvitationHostService: schema.getService('dxos.halo.invitations.InvitationHostService'),
-      },
-    });
+  private _assertInvitationState(stateOrMany: Invitation.State | Invitation.State[]) {
+    const invitation = this._requireActiveInvitation();
+    const validStates = Array.isArray(stateOrMany) ? stateOrMany : [stateOrMany];
+    if (!validStates.includes(invitation.state)) {
+      scheduleTask(this._ctx, () => this.close());
+      throw new InvariantViolation(
+        `Expected ${stateToString(invitation.state)} to be one of [${validStates.map(stateToString).join(', ')}]`,
+      );
+    }
   }
 
-  protected override async getHandlers(): Promise<{ InvitationHostService: InvitationHostService }> {
-    return {
-      InvitationHostService: {
-        options: async (options) => {
-          invariant(!this._remoteOptions, 'Remote options already set.');
-          this._remoteOptions = options;
-          this._remoteOptionsTrigger.wake();
-        },
-        introduce: () => {
-          throw new Error('Method not allowed.');
-        },
-        authenticate: () => {
-          throw new Error('Method not allowed.');
-        },
-        admit: () => {
-          throw new Error('Method not allowed.');
-        },
-      },
-    };
+  override async onClose() {
+    await this._destroy();
   }
 
-  override async onOpen(context: ExtensionContext) {
-    await super.onOpen(context);
-
-    try {
-      log('begin options');
-      await cancelWithContext(this._ctx, this.rpc.InvitationHostService.options({ role: Options.Role.GUEST }));
-      await cancelWithContext(this._ctx, this._remoteOptionsTrigger.wait({ timeout: OPTIONS_TIMEOUT }));
-      log('end options');
-      if (this._remoteOptions?.role !== Options.Role.HOST) {
-        throw new InvalidInvitationExtensionRoleError(undefined, {
-          expected: Options.Role.HOST,
-          remoteOptions: this._remoteOptions,
-        });
-      }
-
-      this._callbacks.onOpen(this._ctx);
-    } catch (err: any) {
-      log('openError', err);
-      this._callbacks.onError(err);
-    }
+  override async onAbort() {
+    await this._destroy();
   }
 
-  override async onClose() {
-    log('onClose');
+  private async _destroy() {
     await this._ctx.dispose();
+    if (this._invitationFlowLock != null) {
+      this._invitationFlowLock?.release();
+      this._invitationFlowLock = null;
+      log('invitation flow lock released');
+    }
   }
 }
 

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

@@ -32,10 +32,16 @@ export interface InvitationProtocol {
   getInvitationContext(): Partial<Invitation> & Pick<Invitation, 'kind'>;
 
   /**
-   * Once authentication is successful, the host can admit the guest to the requested resource.
+   * Allow authorized peers to handle this invitation behalf of invitation creator.
+   * @return id of the delegation credential written to subject control-feed.
    */
   delegate(invitation: Invitation): Promise<PublicKey>;
 
+  /**
+   * Notify other peers that a delegated invitation was cancelled;
+   */
+  cancelDelegation(invitation: Invitation): Promise<void>;
+
   /**
    * Once authentication is successful, the host can admit the guest to the requested resource.
    */

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

@@ -0,0 +1,87 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { invariant } from '@dxos/invariant';
+import { PublicKey } from '@dxos/keys';
+import { log } from '@dxos/log';
+import type { SwarmController, Topology } from '@dxos/network-manager';
+import { Options } from '@dxos/protocols/proto/dxos/halo/invitations';
+import { ComplexSet } from '@dxos/util';
+
+/**
+ * Hosts are listening on an invitation topic.
+ * They initiate a connection with any new peer if they are not currently in the invitation flow
+ * with another peer (connected.length > 0).
+ * When the invitation flow ends guest leaves the swarm and topology is updated once again,
+ * so we can connect to the next peer we haven't tried yet.
+ * If the peer turns out to be a host or a malicious guest their ID is remembered so that we don't try
+ * to establish a connection with them again.
+ *
+ * Guests don't initiate connections. They accept all connections because if we reject,
+ * the host won't retry their offer.
+ * Even if we started an invitation flow with one host we might want to try other hosts in case
+ * the first one failed due to a network error, so multiple connections are accepted.
+ */
+export class InvitationTopology implements Topology {
+  private _controller?: SwarmController;
+
+  /**
+   * Peers we tried to establish a connection with.
+   * In invitation flow peers are assigned random ids when they join the swarm, so we'll retry
+   * a peer if they reload an invitation.
+   *
+   * Consider keeping a separate set for peers we know are hosts and have some retry timeout
+   * for guests we failed an invitation flow with (potentially due to a network error).
+   */
+  private _seenPeers = new ComplexSet<PublicKey>(PublicKey.hash);
+
+  constructor(private readonly _role: Options.Role) {}
+
+  init(controller: SwarmController): void {
+    invariant(!this._controller, 'Already initialized.');
+    this._controller = controller;
+  }
+
+  update(): void {
+    invariant(this._controller, 'Not initialized.');
+    const { ownPeerId, candidates, connected, allPeers } = this._controller.getState();
+
+    // guests don't initiate connections
+    if (this._role === Options.Role.GUEST) {
+      return;
+    }
+
+    // don't start a connection while we have an active invitation flow
+    if (connected.length > 0) {
+      // update seenPeers here as well in case another host initiated a connection with us
+      connected.forEach((c) => this._seenPeers.add(c));
+      return;
+    }
+
+    const firstUnknownPeer = candidates.find((peerId) => !this._seenPeers.has(peerId));
+    // cleanup
+    this._seenPeers = new ComplexSet<PublicKey>(
+      PublicKey.hash,
+      allPeers.filter((peerId) => this._seenPeers.has(peerId)),
+    );
+    if (firstUnknownPeer != null) {
+      log('invitation connect', { ownPeerId, remotePeerId: firstUnknownPeer });
+      this._controller.connect(firstUnknownPeer);
+      this._seenPeers.add(firstUnknownPeer);
+    }
+  }
+
+  async onOffer(peer: PublicKey): Promise<boolean> {
+    invariant(this._controller, 'Not initialized.');
+    return !this._seenPeers.has(peer);
+  }
+
+  async destroy(): Promise<void> {
+    this._seenPeers.clear();
+  }
+
+  toString() {
+    return `InvitationTopology(${this._role === Options.Role.GUEST ? 'guest' : 'host'})`;
+  }
+}