@dxos/client-services 0.4.10-main.3e35a2f → 0.4.10-main.3f5e2d2

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

@@ -4,6 +4,7 @@
 
 import { Trigger } from '@dxos/async';
 import { cancelWithContext, Context } from '@dxos/context';
+import { randomBytes, verify } from '@dxos/crypto';
 import { invariant } from '@dxos/invariant';
 import { PublicKey } from '@dxos/keys';
 import { log } from '@dxos/log';
@@ -51,6 +52,8 @@ export class InvitationHostExtension extends RpcExtension<
   private _remoteOptions?: Options;
   private _remoteOptionsTrigger = new Trigger();
 
+  private _challenge?: Buffer = undefined;
+
   public invitation?: Invitation = undefined;
 
   public guestProfile?: ProfileDocument = undefined;
@@ -113,13 +116,17 @@ export class InvitationHostExtension extends RpcExtension<
 
           this._callbacks.onStateUpdate({ ...this.invitation, state: Invitation.State.READY_FOR_AUTHENTICATION });
 
+          this._challenge =
+            this.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,
+            challenge: this._challenge,
           };
         },
 
-        authenticate: async ({ authCode: code }) => {
+        authenticate: async ({ authCode: code, signedChallenge }) => {
           const traceId = PublicKey.random().toHex();
           log.trace('dxos.sdk.invitation-handler.host.authenticate', trace.begin({ id: traceId }));
           log('received authentication request', { authCode: code });
@@ -145,6 +152,26 @@ export class InvitationHostExtension extends RpcExtension<
               break;
             }
 
+            case Invitation.AuthMethod.KNOWN_PUBLIC_KEY: {
+              if (!this.invitation.guestKeypair) {
+                status = AuthenticationResponse.Status.INTERNAL_ERROR;
+                break;
+              }
+              const isSignatureValid =
+                this._challenge &&
+                verify(
+                  this._challenge,
+                  Buffer.from(signedChallenge ?? []),
+                  this.invitation.guestKeypair.publicKey.asBuffer(),
+                );
+              if (isSignatureValid) {
+                this.authenticationPassed = true;
+              } else {
+                status = AuthenticationResponse.Status.INVALID_SIGNATURE;
+              }
+              break;
+            }
+
             default: {
               log.error('invalid authentication method', { authMethod: this.invitation.authMethod });
               status = AuthenticationResponse.Status.INTERNAL_ERROR;

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

@@ -2,6 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
+import { type PublicKey } from '@dxos/keys';
 import type { ApiError } from '@dxos/protocols';
 import type { Invitation } from '@dxos/protocols/proto/dxos/client/services';
 import type { ProfileDocument, DeviceProfileDocument } from '@dxos/protocols/proto/dxos/halo/credentials';
@@ -33,7 +34,12 @@ export interface InvitationProtocol {
   /**
    * Once authentication is successful, the host can admit the guest to the requested resource.
    */
-  admit(request: AdmissionRequest, guestProfile?: ProfileDocument): Promise<AdmissionResponse>;
+  delegate(invitation: Invitation): Promise<PublicKey>;
+
+  /**
+   * Once authentication is successful, the host can admit the guest to the requested resource.
+   */
+  admit(invitation: Invitation, request: AdmissionRequest, guestProfile?: ProfileDocument): Promise<AdmissionResponse>;
 
   //
   // Guest

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

@@ -3,14 +3,9 @@
 //
 
 import { PushStream, scheduleTask, TimeoutError, Trigger } from '@dxos/async';
-import {
-  AuthenticatingInvitation,
-  AUTHENTICATION_CODE_LENGTH,
-  CancellableInvitation,
-  INVITATION_TIMEOUT,
-} from '@dxos/client-protocol';
+import { AuthenticatingInvitation, INVITATION_TIMEOUT } from '@dxos/client-protocol';
 import { Context } from '@dxos/context';
-import { generatePasscode } from '@dxos/credentials';
+import { createKeyPair, sign } from '@dxos/crypto';
 import { invariant } from '@dxos/invariant';
 import { PublicKey } from '@dxos/keys';
 import { log } from '@dxos/log';
@@ -21,9 +16,9 @@ import {
   type SwarmConnection,
 } from '@dxos/network-manager';
 import { InvalidInvitationExtensionRoleError, trace } from '@dxos/protocols';
-import { Invitation } from '@dxos/protocols/proto/dxos/client/services';
+import { type AdmissionKeypair, Invitation } from '@dxos/protocols/proto/dxos/client/services';
 import { type DeviceProfileDocument } from '@dxos/protocols/proto/dxos/halo/credentials';
-import { AuthenticationResponse } from '@dxos/protocols/proto/dxos/halo/invitations';
+import { AuthenticationResponse, type IntroductionResponse } from '@dxos/protocols/proto/dxos/halo/invitations';
 
 import {
   InvitationGuestExtension,
@@ -66,52 +61,12 @@ export class InvitationsHandler {
    */
   constructor(private readonly _networkManager: NetworkManager) {}
 
-  createInvitation(protocol: InvitationProtocol, options?: Partial<Invitation>): CancellableInvitation {
-    const {
-      invitationId = PublicKey.random().toHex(),
-      type = Invitation.Type.INTERACTIVE,
-      authMethod = Invitation.AuthMethod.SHARED_SECRET,
-      state = Invitation.State.INIT,
-      timeout = INVITATION_TIMEOUT,
-      swarmKey = PublicKey.random(),
-      persistent = true,
-      created = new Date(),
-      lifetime = 86400, // 1 day,
-      multiUse = false,
-    } = options ?? {};
-    const authCode =
-      options?.authCode ??
-      (authMethod === Invitation.AuthMethod.SHARED_SECRET ? generatePasscode(AUTHENTICATION_CODE_LENGTH) : undefined);
-    invariant(protocol);
-
-    const invitation: Invitation = {
-      invitationId,
-      type,
-      authMethod,
-      state,
-      swarmKey,
-      authCode,
-      timeout,
-      persistent: persistent && type !== Invitation.Type.OFFLINE, // offline invitations are persisted in control feed
-      created,
-      lifetime,
-      multiUse,
-      ...protocol.getInvitationContext(),
-    };
-
-    const stream = new PushStream<Invitation>();
-    const ctx = new Context({
-      onError: (err) => {
-        stream.error(err);
-        void ctx.dispose();
-      },
-    });
-
-    ctx.onDispose(() => {
-      log('complete', { ...protocol.toJSON() });
-      stream.complete();
-    });
-
+  handleInvitationFlow(
+    ctx: Context,
+    stream: PushStream<Invitation>,
+    protocol: InvitationProtocol,
+    invitation: Invitation,
+  ): void {
     // Called for every connecting peer.
     const createExtension = (): InvitationHostExtension => {
       const extension = new InvitationHostExtension({
@@ -130,7 +85,7 @@ export class InvitationsHandler {
           try {
             const deviceKey = admissionRequest.device?.deviceKey ?? admissionRequest.space?.deviceKey;
             invariant(deviceKey);
-            const admissionResponse = await protocol.admit(admissionRequest, extension.guestProfile);
+            const admissionResponse = await protocol.admit(invitation, admissionRequest, extension.guestProfile);
 
             // Updating credentials complete.
             extension.completedTrigger.wake(deviceKey);
@@ -150,7 +105,7 @@ export class InvitationsHandler {
               log.trace('dxos.sdk.invitations-handler.host.onOpen', trace.begin({ id: traceId }));
               log('connected', { ...protocol.toJSON() });
               stream.next({ ...invitation, state: Invitation.State.CONNECTED });
-              const deviceKey = await extension.completedTrigger.wait({ timeout });
+              const deviceKey = await extension.completedTrigger.wait({ timeout: invitation.timeout });
               log('admitted guest', { guest: deviceKey, ...protocol.toJSON() });
               stream.next({ ...invitation, state: Invitation.State.SUCCESS });
               log.trace('dxos.sdk.invitations-handler.host.onOpen', trace.end({ id: traceId }));
@@ -164,7 +119,7 @@ export class InvitationsHandler {
               }
               log.trace('dxos.sdk.invitations-handler.host.onOpen', trace.error({ id: traceId, error: err }));
             } finally {
-              if (!multiUse) {
+              if (!invitation.multiUse) {
                 // Wait for graceful close before disposing.
                 await swarmConnection.close();
                 await ctx.dispose();
@@ -189,7 +144,7 @@ export class InvitationsHandler {
       return extension;
     };
 
-    if (invitation.lifetime && invitation.created && invitation.lifetime !== 0) {
+    if (invitation.lifetime && invitation.created) {
       if (invitation.created.getTime() + invitation.lifetime * 1000 < Date.now()) {
         log.warn('invitation has already expired');
       } else {
@@ -225,18 +180,6 @@ export class InvitationsHandler {
 
       stream.next({ ...invitation, state: Invitation.State.CONNECTING });
     });
-
-    // TODO(burdon): Stop anything pending.
-    const observable = new CancellableInvitation({
-      initialInvitation: invitation,
-      subscriber: stream.observable,
-      onCancel: async () => {
-        stream.next({ ...invitation, state: Invitation.State.CANCELLED });
-        await ctx.dispose();
-      },
-    });
-
-    return observable;
   }
 
   acceptInvitation(
@@ -247,7 +190,6 @@ export class InvitationsHandler {
     const { timeout = INVITATION_TIMEOUT } = invitation;
     invariant(protocol);
 
-    // TODO(nf): duplicate check in InvitationsService
     if (deviceProfile) {
       invariant(invitation.kind === Invitation.Kind.DEVICE, 'deviceProfile provided for non-device invitation');
     }
@@ -319,26 +261,13 @@ export class InvitationsHandler {
 
               // 2. Get authentication code.
               if (isAuthenticationRequired(invitation)) {
-                for (let attempt = 1; attempt <= MAX_OTP_ATTEMPTS; attempt++) {
-                  log('guest waiting for authentication code...');
-                  setState({ state: Invitation.State.READY_FOR_AUTHENTICATION });
-                  const authCode = await authenticated.wait({ timeout });
-
-                  log('sending authentication request');
-                  setState({ state: Invitation.State.AUTHENTICATING });
-                  const response = await extension.rpc.InvitationHostService.authenticate({ authCode });
-                  if (response.status === undefined || response.status === AuthenticationResponse.Status.OK) {
+                switch (invitation.authMethod) {
+                  case Invitation.AuthMethod.SHARED_SECRET:
+                    await this._handleGuestOtpAuth(extension, setState, authenticated, { timeout });
+                    break;
+                  case Invitation.AuthMethod.KNOWN_PUBLIC_KEY:
+                    await this._handleGuestKpkAuth(extension, setState, invitation, introductionResponse);
                     break;
-                  }
-
-                  if (response.status === AuthenticationResponse.Status.INVALID_OTP) {
-                    if (attempt === MAX_OTP_ATTEMPTS) {
-                      throw new Error(`Maximum retry attempts: ${MAX_OTP_ATTEMPTS}`);
-                    } else {
-                      log('retrying invalid code', { attempt });
-                      authenticated.reset();
-                    }
-                  }
                 }
               }
 
@@ -425,4 +354,61 @@ export class InvitationsHandler {
 
     return observable;
   }
+
+  private async _handleGuestOtpAuth(
+    extension: InvitationGuestExtension,
+    setState: (newState: Partial<Invitation>) => void,
+    authenticated: Trigger<string>,
+    options: { timeout: number },
+  ) {
+    for (let attempt = 1; attempt <= MAX_OTP_ATTEMPTS; attempt++) {
+      log('guest waiting for authentication code...');
+      setState({ state: Invitation.State.READY_FOR_AUTHENTICATION });
+      const authCode = await authenticated.wait(options);
+
+      log('sending authentication request');
+      setState({ state: Invitation.State.AUTHENTICATING });
+      const response = await extension.rpc.InvitationHostService.authenticate({ authCode });
+      if (response.status === undefined || response.status === AuthenticationResponse.Status.OK) {
+        break;
+      }
+
+      if (response.status === AuthenticationResponse.Status.INVALID_OTP) {
+        if (attempt === MAX_OTP_ATTEMPTS) {
+          throw new Error(`Maximum retry attempts: ${MAX_OTP_ATTEMPTS}`);
+        } else {
+          log('retrying invalid code', { attempt });
+          authenticated.reset();
+        }
+      }
+    }
+  }
+
+  private async _handleGuestKpkAuth(
+    extension: InvitationGuestExtension,
+    setState: (newState: Partial<Invitation>) => void,
+    invitation: Invitation,
+    introductionResponse: IntroductionResponse,
+  ) {
+    if (invitation.guestKeypair?.privateKey == null) {
+      throw new Error('keypair missing in the invitation');
+    }
+    if (introductionResponse.challenge == null) {
+      throw new Error('challenge missing in the introduction');
+    }
+    log('sending authentication request');
+    setState({ state: Invitation.State.AUTHENTICATING });
+    const signature = sign(Buffer.from(introductionResponse.challenge), invitation.guestKeypair.privateKey);
+    const response = await extension.rpc.InvitationHostService.authenticate({
+      signedChallenge: signature,
+    });
+    if (response.status !== AuthenticationResponse.Status.OK) {
+      throw new Error(`Authentication failed with code: ${response.status}`);
+    }
+  }
 }
+
+export const createAdmissionKeypair = (): AdmissionKeypair => {
+  const keypair = createKeyPair();
+  return { publicKey: PublicKey.from(keypair.publicKey), privateKey: keypair.secretKey };
+};

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

@@ -0,0 +1,271 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Event, PushStream } from '@dxos/async';
+import {
+  type AuthenticatingInvitation,
+  AUTHENTICATION_CODE_LENGTH,
+  CancellableInvitation,
+  INVITATION_TIMEOUT,
+} from '@dxos/client-protocol';
+import { Context } from '@dxos/context';
+import { generatePasscode } from '@dxos/credentials';
+import { hasInvitationExpired, type MetadataStore } from '@dxos/echo-pipeline';
+import { invariant } from '@dxos/invariant';
+import { PublicKey } from '@dxos/keys';
+import { log } from '@dxos/log';
+import {
+  type AcceptInvitationRequest,
+  type AuthenticationRequest,
+  Invitation,
+} from '@dxos/protocols/proto/dxos/client/services';
+
+import type { InvitationProtocol } from './invitation-protocol';
+import { createAdmissionKeypair, type InvitationsHandler } from './invitations-handler';
+
+/**
+ * Entry point for creating and accepting invitations, keeps track of existing invitation set and
+ * emits events when the set changes.
+ */
+export class InvitationsManager {
+  private readonly _createInvitations = new Map<string, CancellableInvitation>();
+  private readonly _acceptInvitations = new Map<string, AuthenticatingInvitation>();
+
+  public readonly invitationCreated = new Event<Invitation>();
+  public readonly invitationAccepted = new Event<Invitation>();
+  public readonly removedCreated = new Event<Invitation>();
+  public readonly removedAccepted = new Event<Invitation>();
+  public readonly saved = new Event<Invitation>();
+
+  private readonly _persistentInvitationsLoadedEvent = new Event();
+  private _persistentInvitationsLoaded = false;
+
+  constructor(
+    private readonly _invitationsHandler: InvitationsHandler,
+    private readonly _getHandler: (invitation: Partial<Invitation> & Pick<Invitation, 'kind'>) => InvitationProtocol,
+    private readonly _metadataStore: MetadataStore,
+  ) {}
+
+  async createInvitation(options: Partial<Invitation> & Pick<Invitation, 'kind'>): Promise<CancellableInvitation> {
+    if (options.invitationId) {
+      const existingInvitation = this._createInvitations.get(options.invitationId);
+      if (existingInvitation) {
+        return existingInvitation;
+      }
+    }
+
+    const handler = this._getHandler(options);
+    const invitation = this._createInvitation(handler, options);
+    const { ctx, stream, observableInvitation } = this._createObservableInvitation(handler, invitation);
+
+    this._createInvitations.set(invitation.invitationId, observableInvitation);
+    this.invitationCreated.emit(invitation);
+    // onComplete is called on cancel, expiration, or redemption of a single-use invitation
+    this._onInvitationComplete(observableInvitation, async () => {
+      this._createInvitations.delete(observableInvitation.get().invitationId);
+      this.removedCreated.emit(observableInvitation.get());
+      if (observableInvitation.get().persistent) {
+        await this._safeDeleteInvitation(observableInvitation.get());
+      }
+    });
+
+    try {
+      await this._persistIfRequired(handler, stream, invitation);
+    } catch (err) {
+      log.catch(err);
+      await observableInvitation.cancel();
+      return observableInvitation;
+    }
+
+    this._invitationsHandler.handleInvitationFlow(ctx, stream, handler, observableInvitation.get());
+
+    return observableInvitation;
+  }
+
+  async loadPersistentInvitations(): Promise<{ invitations: Invitation[] }> {
+    if (this._persistentInvitationsLoaded) {
+      const invitations = this.getCreatedInvitations().filter((i) => i.persistent);
+      return { invitations };
+    }
+    try {
+      const persistentInvitations = this._metadataStore.getInvitations();
+      // get saved persistent invitations, filter and remove from storage those that have expired.
+      const freshInvitations = persistentInvitations.filter((invitation) => !hasInvitationExpired(invitation));
+
+      const loadTasks = freshInvitations.map((persistentInvitation) => {
+        invariant(!this._createInvitations.get(persistentInvitation.invitationId), 'invitation already exists');
+        return this.createInvitation({ ...persistentInvitation, persistent: false });
+      });
+      const cInvitations = await Promise.all(loadTasks);
+
+      return { invitations: cInvitations.map((invitation) => invitation.get()) };
+    } catch (err) {
+      log.catch(err);
+      return { invitations: [] };
+    } finally {
+      this._persistentInvitationsLoadedEvent.emit();
+      this._persistentInvitationsLoaded = true;
+    }
+  }
+
+  acceptInvitation(request: AcceptInvitationRequest): AuthenticatingInvitation {
+    const options = request.invitation;
+    const existingInvitation = this._acceptInvitations.get(options.invitationId);
+    if (existingInvitation) {
+      return existingInvitation;
+    }
+
+    const handler = this._getHandler(options);
+    const invitation = this._invitationsHandler.acceptInvitation(handler, options, request.deviceProfile);
+    this._acceptInvitations.set(invitation.get().invitationId, invitation);
+    this.invitationAccepted.emit(invitation.get());
+
+    this._onInvitationComplete(invitation, () => {
+      this._acceptInvitations.delete(invitation.get().invitationId);
+      this.removedAccepted.emit(invitation.get());
+    });
+
+    return invitation;
+  }
+
+  async authenticate({ invitationId, authCode }: AuthenticationRequest): Promise<void> {
+    log('authenticating...');
+    invariant(invitationId);
+    const observable = this._acceptInvitations.get(invitationId);
+    if (!observable) {
+      log.warn('invalid invitation', { invitationId });
+    } else {
+      await observable.authenticate(authCode);
+    }
+  }
+
+  async cancelInvitation({ invitationId }: { invitationId: string }): Promise<void> {
+    log('cancelInvitation...', { invitationId });
+    invariant(invitationId);
+    const created = this._createInvitations.get(invitationId);
+    if (created) {
+      // remove from storage before modifying in-memory state, higher chance of failing
+      if (created.get().persistent) {
+        await this._metadataStore.removeInvitation(invitationId);
+      }
+      await created.cancel();
+      this._createInvitations.delete(invitationId);
+      this.removedCreated.emit(created.get());
+      return;
+    }
+
+    const accepted = this._acceptInvitations.get(invitationId);
+    if (accepted) {
+      await accepted.cancel();
+      this._acceptInvitations.delete(invitationId);
+      this.removedAccepted.emit(accepted.get());
+    }
+  }
+
+  getCreatedInvitations(): Invitation[] {
+    return [...this._createInvitations.values()].map((i) => i.get());
+  }
+
+  getAcceptedInvitations(): Invitation[] {
+    return [...this._acceptInvitations.values()].map((i) => i.get());
+  }
+
+  onPersistentInvitationsLoaded(ctx: Context, callback: () => void) {
+    if (this._persistentInvitationsLoaded) {
+      callback();
+    } else {
+      this._persistentInvitationsLoadedEvent.once(ctx, () => callback());
+    }
+  }
+
+  private _createInvitation(protocol: InvitationProtocol, options?: Partial<Invitation>): Invitation {
+    const {
+      invitationId = PublicKey.random().toHex(),
+      type = Invitation.Type.INTERACTIVE,
+      authMethod = Invitation.AuthMethod.SHARED_SECRET,
+      state = Invitation.State.INIT,
+      timeout = INVITATION_TIMEOUT,
+      swarmKey = PublicKey.random(),
+      persistent = options?.authMethod !== Invitation.AuthMethod.KNOWN_PUBLIC_KEY, // default no not storing keypairs
+      created = new Date(),
+      guestKeypair = undefined,
+      lifetime = 86400, // 1 day,
+      multiUse = false,
+    } = options ?? {};
+    const authCode =
+      options?.authCode ??
+      (authMethod === Invitation.AuthMethod.SHARED_SECRET ? generatePasscode(AUTHENTICATION_CODE_LENGTH) : undefined);
+
+    return {
+      invitationId,
+      type,
+      authMethod,
+      state,
+      swarmKey,
+      authCode,
+      timeout,
+      persistent: persistent && type !== Invitation.Type.DELEGATED, // delegated invitations are persisted in control feed
+      guestKeypair:
+        guestKeypair ?? (authMethod === Invitation.AuthMethod.KNOWN_PUBLIC_KEY ? createAdmissionKeypair() : undefined),
+      created,
+      lifetime,
+      multiUse,
+      delegationCredentialId: options?.delegationCredentialId,
+      ...protocol.getInvitationContext(),
+    } satisfies Invitation;
+  }
+
+  private _createObservableInvitation(handler: InvitationProtocol, invitation: Invitation) {
+    const stream = new PushStream<Invitation>();
+    const ctx = new Context({
+      onError: (err) => {
+        stream.error(err);
+        void ctx.dispose();
+      },
+    });
+    ctx.onDispose(() => {
+      log('complete', { ...handler.toJSON() });
+      stream.complete();
+    });
+    const observableInvitation = new CancellableInvitation({
+      initialInvitation: invitation,
+      subscriber: stream.observable,
+      onCancel: async () => {
+        stream.next({ ...invitation, state: Invitation.State.CANCELLED });
+        await ctx.dispose();
+      },
+    });
+    return { ctx, stream, observableInvitation };
+  }
+
+  private async _persistIfRequired(
+    handler: InvitationProtocol,
+    changeStream: PushStream<Invitation>,
+    invitation: Invitation,
+  ): Promise<void> {
+    if (invitation.type === Invitation.Type.DELEGATED && invitation.delegationCredentialId == null) {
+      const delegationCredentialId = await handler.delegate(invitation);
+      changeStream.next({ ...invitation, delegationCredentialId });
+    } else if (invitation.persistent) {
+      await this._metadataStore.addInvitation(invitation);
+      this.saved.emit(invitation);
+    }
+  }
+
+  private async _safeDeleteInvitation(invitation: Invitation): Promise<void> {
+    try {
+      await this._metadataStore.removeInvitation(invitation.invitationId);
+    } catch (err) {
+      log.catch(err);
+    }
+  }
+
+  private _onInvitationComplete(invitation: CancellableInvitation, callback: () => void) {
+    invitation.subscribe(
+      () => {},
+      () => {},
+      callback,
+    );
+  }
+}