Support for MSC3906 v2

src/rendezvous/MSC3906Rendezvous.ts

@@ -16,20 +16,69 @@ limitations under the License.
 
 import { UnstableValue } from "matrix-events-sdk";
 
-import { RendezvousChannel, RendezvousFailureListener, RendezvousFailureReason, RendezvousIntent } from ".";
+import {
+ RendezvousChannel,
+ RendezvousFailureListener,
+ RendezvousFailureReason,
+ RendezvousFlow,
+ RendezvousIntent,
+ SETUP_ADDITIONAL_DEVICE_FLOW_V1,
+} from ".";
 import { MatrixClient } from "../client";
 import { CrossSigningInfo } from "../crypto/CrossSigning";
 import { DeviceInfo } from "../crypto/deviceinfo";
 import { buildFeatureSupportMap, Feature, ServerSupport } from "../feature";
 import { logger } from "../logger";
 import { sleep } from "../utils";
 
+/**
+ * These are the possible types of payload that are used in
+ * [MSC3906](https://github.com/matrix-org/matrix-spec-proposals/pull/3906) payloads.
+ * The values are used in the `type` field.
+ */
 enum PayloadType {
- Start = "m.login.start",
+ /**
+ * @deprecated Only used in MSC3906 v1
+ */
  Finish = "m.login.finish",
+ /**
+ * Indicates that a new device is ready to proceed with the setup process.
+ */
  Progress = "m.login.progress",
+ /**
+ * Used by the new device to indicate which protocol to use.
+ */
+ Protocol = "m.login.protocol",
+ /**
+ * Used for the new device to indicate which protocols are supported by the existing device and
+ * homeserver.
+ */
+ Protocols = "m.login.protocols",
+ /**
+ * Indicates that the sign of the new device was approved by the user on the existing device.
+ */
+ Approved = "m.login.approved",
+ /**
+ * Indicates that the new device has signed in successfully.
+ */
+ Success = "m.login.success",
+ /**
+ * Indicates that the new device has been successfully verified by the existing device.
+ */
+ Verified = "m.login.verified",
+ /**
+ * Indicates that the login failed.
+ */
+ Failure = "m.login.failure",
+ /**
+ * Indicates that the user declined the login on the existing device.
+ */
+ Declined = "m.login.declined",
 }
 
+/**
+ * @deprecated Only used in MSC3906 v1
+ */
 enum Outcome {
  Success = "success",
  Failure = "failure",
@@ -38,10 +87,28 @@ enum Outcome {
  Unsupported = "unsupported",
 }
 
+/**
+ * Used in the `reason` field of the `m.login.failure` payload.
+ */
+enum FailureReason {
+ Cancelled = "cancelled",
+ Unsupported = "unsupported",
+ E2EESecurityError = "e2ee_security_error",
+ IncompatibleIntent = "incompatible_intent",
+}
+
+/**
+ * This represents an [MSC3906](https://github.com/matrix-org/matrix-spec-proposals/pull/3906) payload.
+ */
 export interface MSC3906RendezvousPayload {
+ /** The type of the payload */
  type: PayloadType;
  intent?: RendezvousIntent;
+ /**
+ * @deprecated Only used in MSC3906 v1. Instead the type field should be used in future
+ */
  outcome?: Outcome;
+ reason?: FailureReason;
  device_id?: string;
  device_key?: string;
  verifying_device_id?: string;
@@ -53,48 +120,75 @@ export interface MSC3906RendezvousPayload {
  homeserver?: string;
 }
 
+/**
+ * Represents the use of an `m.login.token` obtained from an existing device to sign in on a new device.
+ */
 const LOGIN_TOKEN_PROTOCOL = new UnstableValue("login_token", "org.matrix.msc3906.login_token");
 
 /**
- * Implements MSC3906 to allow a user to sign in on a new device using QR code.
- * This implementation only supports generating a QR code on a device that is already signed in.
+ * This class can be used to complete a "rendezvous flow" as defined in MSC3906.
+ *
+ * Currently it only supports being used on a device that is already signed in that wishes to help sign in
+ * another device.
+ *
  * Note that this is UNSTABLE and may have breaking changes without notice.
  */
 export class MSC3906Rendezvous {
  private newDeviceId?: string;
  private newDeviceKey?: string;
  private ourIntent: RendezvousIntent = RendezvousIntent.RECIPROCATE_LOGIN_ON_EXISTING_DEVICE;
+ // if true then we follow the v1 flow, otherwise we follow the v2 flow
+ private usingV1Flow: boolean;
  private _code?: string;
 
  /**
- * @param channel - The secure channel used for communication
- * @param client - The Matrix client in used on the device already logged in
- * @param onFailure - Callback for when the rendezvous fails
+ * Creates an instance that can be used to manage the execution of a rendezvous flow.
+ *
+ * @param channel - The rendezvous channel that should be used for communication with the other device
+ * @param client - The Matrix client that should be used.
+ * @param onFailure - Optional callback function to be notified of rendezvous failures.
+ * @param flow - The rendezvous flow to use. Defaults to setting up an additional device using MSC3906 v1,
+ * for backwards compatibility.
  */
  public constructor(
  private channel: RendezvousChannel<MSC3906RendezvousPayload>,
  private client: MatrixClient,
  public onFailure?: RendezvousFailureListener,
- ) {}
+ private flow: RendezvousFlow = SETUP_ADDITIONAL_DEVICE_FLOW_V1,
+ ) {
+ this.usingV1Flow = flow === SETUP_ADDITIONAL_DEVICE_FLOW_V1;
+ }
 
  /**
- * Returns the code representing the rendezvous suitable for rendering in a QR code or undefined if not generated yet.
+ * @returns The code representing the rendezvous suitable for rendering in a QR code or undefined if not generated yet.
  */
  public get code(): string | undefined {
  return this._code;
  }
 
  /**
- * Generate the code including doing partial set up of the channel where required.
+ * Generate the code including doing partial set up of the channel where required. This code could be encoded in a QR.
  */
  public async generateCode(): Promise<void> {
  if (this._code) {
  return;
  }
 
- this._code = JSON.stringify(await this.channel.generateCode(this.ourIntent));
+ const raw = this.usingV1Flow
+ ? await this.channel.generateCode(this.ourIntent)
+ : await this.channel.generateCode(this.ourIntent, this.flow);
+ this._code = JSON.stringify(raw);
  }
 
+ /**
+ * Call this after the code has been shown to the user (perhaps in a QR). It will poll for the other device
+ * at the rendezvous point and start the process of setting up the new device.
+ *
+ * If successful then the user should be asked to approve the login of the other device whilst displaying the
+ * returned checksum code which the user should verify matches the code shown on the other device.
+ *
+ * @returns the checksum of the secure channel if the rendezvous set up was successful, otherwise undefined
+ */
  public async startAfterShowingCode(): Promise<string | undefined> {
  const checksum = await this.channel.connect();
 
@@ -104,39 +198,114 @@ export class MSC3906Rendezvous {
  // determine available protocols
  if (features.get(Feature.LoginTokenRequest) === ServerSupport.Unsupported) {
  logger.info("Server doesn't support MSC3882");
- await this.send({ type: PayloadType.Finish, outcome: Outcome.Unsupported });
+ await this.send(
+ this.usingV1Flow
+ ? { type: PayloadType.Finish, outcome: Outcome.Unsupported }
+ : { type: PayloadType.Failure, reason: FailureReason.Unsupported },
+ );
  await this.cancel(RendezvousFailureReason.HomeserverLacksSupport);
  return undefined;
  }
 
- await this.send({ type: PayloadType.Progress, protocols: [LOGIN_TOKEN_PROTOCOL.name] });
+ await this.send({
+ type: this.usingV1Flow ? PayloadType.Progress : PayloadType.Protocols,
+ protocols: [LOGIN_TOKEN_PROTOCOL.name],
+ });
 
  logger.info("Waiting for other device to chose protocol");
- const { type, protocol, outcome } = await this.receive();
+ const nextPayload = await this.receive();
 
+ // even if we didn't start in v1 mode we might detect that the other device is v1:
+ // - the finish payload is only used in v1
+ // - a progress payload is only sent at this point in v1, in v2 the use of it is different
+ if (nextPayload.type === PayloadType.Finish || nextPayload.type === PayloadType.Progress) {
+ this.usingV1Flow = true;
+ }
+
+ const protocol = this.usingV1Flow
+ ? await this.handleV1ProtocolPayload(nextPayload)
+ : await this.handleV2ProtocolPayload(nextPayload);
+
+ // invalid protocol
+ if (!protocol || !LOGIN_TOKEN_PROTOCOL.matches(protocol)) {
+ await this.cancel(RendezvousFailureReason.UnsupportedAlgorithm);
+ return undefined;
+ }
+
+ return checksum;
+ }
+
+ private async handleV1ProtocolPayload({
+ type,
+ protocol,
+ outcome,
+ reason,
+ intent,
+ }: MSC3906RendezvousPayload): Promise<string | void> {
  if (type === PayloadType.Finish) {
  // new device decided not to complete
- switch (outcome ?? "") {
- case "unsupported":
- await this.cancel(RendezvousFailureReason.UnsupportedAlgorithm);
- break;
- default:
- await this.cancel(RendezvousFailureReason.Unknown);
+ let reason: RendezvousFailureReason;
+ if (intent) {
+ reason =
+ this.ourIntent === RendezvousIntent.LOGIN_ON_NEW_DEVICE
+ ? RendezvousFailureReason.OtherDeviceNotSignedIn
+ : RendezvousFailureReason.OtherDeviceAlreadySignedIn;
+ } else if (outcome === Outcome.Unsupported) {
+ reason = RendezvousFailureReason.UnsupportedAlgorithm;
+ } else {
+ reason = RendezvousFailureReason.Unknown;
  }
- return undefined;
+ await this.cancel(reason);
+ return;
  }
 
+ // unexpected payload
  if (type !== PayloadType.Progress) {
  await this.cancel(RendezvousFailureReason.Unknown);
- return undefined;
+ return;
  }
 
- if (!protocol || !LOGIN_TOKEN_PROTOCOL.matches(protocol)) {
- await this.cancel(RendezvousFailureReason.UnsupportedAlgorithm);
- return undefined;
+ return protocol;
+ }
+
+ private async handleV2ProtocolPayload({
+ type,
+ protocol,
+ outcome,
+ reason,
+ intent,
+ }: MSC3906RendezvousPayload): Promise<string | void> {
+ // v2 flow
+ if (type === PayloadType.Failure) {
+ // new device decided not to complete
+ let failureReason: RendezvousFailureReason;
+ switch (reason ?? "") {
+ case FailureReason.Cancelled:
+ failureReason = RendezvousFailureReason.UserCancelled;
+ break;
+ case FailureReason.IncompatibleIntent:
+ failureReason =
+ this.ourIntent === RendezvousIntent.LOGIN_ON_NEW_DEVICE
+ ? RendezvousFailureReason.OtherDeviceNotSignedIn
+ : RendezvousFailureReason.OtherDeviceAlreadySignedIn;
+ break;
+ case FailureReason.Unsupported:
+ failureReason = RendezvousFailureReason.UnsupportedAlgorithm;
+ break;
+ default:
+ failureReason = RendezvousFailureReason.Unknown;
+ }
+ await this.cancel(failureReason);
+ return;
  }
 
- return checksum;
+ // unexpected payload
+ if (type !== PayloadType.Protocol) {
+ await this.cancel(RendezvousFailureReason.Unknown);
+ return;
+ }
+
+ return protocol;
  }
 
  private async receive(): Promise<MSC3906RendezvousPayload> {
@@ -147,23 +316,38 @@ export class MSC3906Rendezvous {
  await this.channel.send(payload);
  }
 
+ /**
+ * Call this if the user has declined the login.
+ */
  public async declineLoginOnExistingDevice(): Promise<void> {
  logger.info("User declined sign in");
- await this.send({ type: PayloadType.Finish, outcome: Outcome.Declined });
+ await this.send(
+ this.usingV1Flow ? { type: PayloadType.Finish, outcome: Outcome.Declined } : { type: PayloadType.Declined },
+ );
  }
 
+ /**
+ * Call this if the user has approved the login.
+ *
+ * @param loginToken - the login token to send to the new device for it to complete the login flow
+ * @returns if the new device successfully completed the login flow and provided their device id then the device id is
+ * returned, otherwise undefined
+ */
  public async approveLoginOnExistingDevice(loginToken: string): Promise<string | undefined> {
- // eslint-disable-next-line camelcase
- await this.send({ type: PayloadType.Progress, login_token: loginToken, homeserver: this.client.baseUrl });
+ await this.channel.send({
+ type: this.usingV1Flow ? PayloadType.Progress : PayloadType.Approved,
+ login_token: loginToken,
+ homeserver: this.client.baseUrl,
+ });
 
  logger.info("Waiting for outcome");
  const res = await this.receive();
  if (!res) {
  return undefined;
  }
- const { outcome, device_id: deviceId, device_key: deviceKey } = res;
+ const { type, outcome, device_id: deviceId, device_key: deviceKey } = res;
 
- if (outcome !== "success") {
+ if ((this.usingV1Flow && outcome !== "success") || (!this.usingV1Flow && type !== PayloadType.Success)) {
  throw new Error("Linking failed");
  }
 
@@ -201,8 +385,8 @@ export class MSC3906Rendezvous {
  const masterPublicKey = this.client.crypto.crossSigningInfo.getId("master")!;
 
  await this.send({
- type: PayloadType.Finish,
- outcome: Outcome.Verified,
+ type: this.usingV1Flow ? PayloadType.Finish : PayloadType.Verified,
+ outcome: this.usingV1Flow ? Outcome.Verified : undefined,
  verifying_device_id: this.client.getDeviceId()!,
  verifying_device_key: this.client.getDeviceEd25519Key()!,
  master_key: masterPublicKey,
@@ -212,7 +396,8 @@ export class MSC3906Rendezvous {
  }
 
  /**
- * Verify the device and cross-sign it.
+ * Wait for a device to be visible via the homeserver and then verify/cross-sign it.
+ *
  * @param timeout - time in milliseconds to wait for device to come online
  * @returns the new device info if the device was verified
  */