matrix-js-sdk 41.0.0 → 41.1.0

package/lib/matrixrtc/CallMembership.js

@@ -1,7 +1,7 @@
 import _asyncToGenerator from "@babel/runtime/helpers/asyncToGenerator";
 import _defineProperty from "@babel/runtime/helpers/defineProperty";
 /*
-Copyright 2023 The Matrix.org Foundation C.I.C.
+Copyright 2023-2026 The Matrix.org Foundation C.I.C.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -16,145 +16,95 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-import { MXID_PATTERN } from "../models/room-member.js";
 import { deepCompare } from "../utils.js";
-import { slotDescriptionToId, slotIdToDescription } from "./MatrixRTCSession.js";
-import { sha256 } from "../digest.js";
-import { encodeUnpaddedBase64 } from "../base64.js";
+import { logger } from "../logger.js";
+import { computeSlotId, slotIdToDescription } from "./utils.js";
+import { checkRtcMembershipData, computeRtcIdentityRaw, checkSessionsMembershipData, MatrixRTCMembershipParseError } from "./membershipData/index.js";
+import { EventType } from "../@types/event.js";
+
 /**
  * The default duration in milliseconds that a membership is considered valid for.
  * Ordinarily the client responsible for the session will update the membership before it expires.
  * We use this duration as the fallback case where stale sessions are present for some reason.
  */
 export var DEFAULT_EXPIRE_DURATION = 1000 * 60 * 60 * 4;
-var checkRtcMembershipData = (data, errors, referenceUserId) => {
-  var _data$sticky_key;
-  var prefix = " - ";
 
-  // required fields
-  if (typeof data.slot_id !== "string") {
-    errors.push(prefix + "slot_id must be string");
-  } else {
-    if (data.slot_id.split("#").length !== 2) errors.push(prefix + 'slot_id must include exactly one "#"');
-  }
-  if (typeof data.member !== "object" || data.member === null) {
-    errors.push(prefix + "member must be an object");
-  } else {
-    if (typeof data.member.user_id !== "string") errors.push(prefix + "member.user_id must be string");else if (!MXID_PATTERN.test(data.member.user_id)) errors.push(prefix + "member.user_id must be a valid mxid");
-    // This is not what the spec enforces but there currently are no rules what power levels are required to
-    // send a m.rtc.member event for a other user. So we add this check for simplicity and to avoid possible attacks until there
-    // is a proper definition when this is allowed.
-    else if (data.member.user_id !== referenceUserId) errors.push(prefix + "member.user_id must match the sender");
-    if (typeof data.member.device_id !== "string") errors.push(prefix + "member.device_id must be string");
-    if (typeof data.member.id !== "string") errors.push(prefix + "member.id must be string");
-  }
-  if (typeof data.application !== "object" || data.application === null) {
-    errors.push(prefix + "application must be an object");
-  } else {
-    if (typeof data.application.type !== "string") {
-      errors.push(prefix + "application.type must be a string");
-    } else {
-      if (data.application.type.includes("#")) errors.push(prefix + 'application.type must not include "#"');
-    }
-  }
-  if (data.rtc_transports === undefined || !Array.isArray(data.rtc_transports)) {
-    errors.push(prefix + "rtc_transports must be an array");
-  } else {
-    // validate that each transport has at least a string 'type'
-    for (var t of data.rtc_transports) {
-      if (typeof t !== "object" || t === null || typeof t.type !== "string") {
-        errors.push(prefix + "rtc_transports entries must be objects with a string type");
-        break;
+/**
+ * Describes the source event type that provided the membership data.
+ */
+var MembershipKind = /*#__PURE__*/function (MembershipKind) {
+  /**
+   * The modern MSC4143 format event.
+   */
+  MembershipKind["RTC"] = "rtc";
+  /**
+   * The legacy call event type.
+   */
+  MembershipKind["Session"] = "session";
+  return MembershipKind;
+}(MembershipKind || {});
+// TODO: Rename to RtcMembership once we removed the legacy SessionMembership is removed, to avoid confusion.
+export class CallMembership {
+  /**
+   * Parse the membershipdata from a call membership event.
+   * @param matrixEvent The Matrix event to read.
+   * @returns MembershipData in either MembershipKind.RTC or MembershipKind.Session format.
+   * @throws If the content is neither format.
+   */
+  static membershipDataFromMatrixEvent(matrixEvent) {
+    var sender = matrixEvent.getSender();
+    var evType = matrixEvent.getType();
+    var data = matrixEvent.getContent();
+    if (sender === undefined) throw new Error("matrixEvent is missing sender field");
+    try {
+      // Event types are strictly checked here.
+      if (evType === EventType.RTCMembership && checkRtcMembershipData(data, sender)) {
+        return {
+          kind: MembershipKind.RTC,
+          data
+        };
+      } else if (evType === EventType.GroupCallMemberPrefix && checkSessionsMembershipData(data)) {
+        return {
+          kind: MembershipKind.Session,
+          data
+        };
+      } else {
+        throw Error("'".concat(evType, " is not a known call membership type"));
       }
+    } catch (ex) {
+      if (ex instanceof MatrixRTCMembershipParseError) {
+        logger.debug("CallMembership.MatrixRTCMembershipParseError provided invalid data", data);
+      }
+      throw ex;
     }
   }
-  if (data.versions === undefined || !Array.isArray(data.versions)) {
-    errors.push(prefix + "versions must be an array");
-  } else if (!data.versions.every(v => typeof v === "string")) {
-    errors.push(prefix + "versions must be an array of strings");
-  }
-
-  // optional fields
-  if (((_data$sticky_key = data.sticky_key) !== null && _data$sticky_key !== void 0 ? _data$sticky_key : data.msc4354_sticky_key) === undefined) {
-    errors.push(prefix + "sticky_key or msc4354_sticky_key must be a defined");
-  }
-  if (data.sticky_key !== undefined && typeof data.sticky_key !== "string") {
-    errors.push(prefix + "sticky_key must be a string");
-  }
-  if (data.msc4354_sticky_key !== undefined && typeof data.msc4354_sticky_key !== "string") {
-    errors.push(prefix + "msc4354_sticky_key must be a string");
-  }
-  if (data.sticky_key !== undefined && data.msc4354_sticky_key !== undefined && data.sticky_key !== data.msc4354_sticky_key) {
-    errors.push(prefix + "sticky_key and msc4354_sticky_key must be equal if both are defined");
-  }
-  if (data["m.relates_to"] !== undefined) {
-    var rel = data["m.relates_to"];
-    if (typeof rel !== "object" || rel === null) {
-      errors.push(prefix + "m.relates_to must be an object if provided");
-    } else {
-      if (typeof rel.event_id !== "string") errors.push(prefix + "m.relates_to.event_id must be a string");
-      if (rel.rel_type !== "m.reference") errors.push(prefix + "m.relates_to.rel_type must be m.reference");
-    }
-  }
-  return errors.length === 0;
-};
-
-/**
- * MSC4143 (MatrixRTC) session membership data.
- * Represents the `session` in the memberships section of an m.call.member event as it is on the wire.
- **/
-
-var checkSessionsMembershipData = (data, errors) => {
-  var _data$focus_active;
-  var prefix = " - ";
-  if (typeof data.device_id !== "string") errors.push(prefix + "device_id must be string");
-  if (typeof data.call_id !== "string") errors.push(prefix + "call_id must be string");
-  if (typeof data.application !== "string") errors.push(prefix + "application must be a string");
-  if (typeof ((_data$focus_active = data.focus_active) === null || _data$focus_active === void 0 ? void 0 : _data$focus_active.type) !== "string") errors.push(prefix + "focus_active.type must be a string");
-  if (data.focus_active === undefined) {
-    errors.push(prefix + "focus_active has an invalid type");
-  }
-  if (data.foci_preferred !== undefined && !(Array.isArray(data.foci_preferred) && data.foci_preferred.every(f => typeof f === "object" && f !== null && typeof f.type === "string"))) {
-    errors.push(prefix + "foci_preferred must be an array of transport objects");
-  }
-  // optional parameters
-  if (data.created_ts !== undefined && typeof data.created_ts !== "number") {
-    errors.push(prefix + "created_ts must be number");
-  }
 
-  // application specific data (we first need to check if they exist)
-  if (data.scope !== undefined && typeof data.scope !== "string") errors.push(prefix + "scope must be string");
-  if (data["m.call.intent"] !== undefined && typeof data["m.call.intent"] !== "string") {
-    errors.push(prefix + "m.call.intent must be a string");
+  /**
+   * Parse the contents of a MatrixEvent and create a CallMembership instance.
+   * @param matrixEvent The Matrix event to read.
+   */
+  static parseFromEvent(matrixEvent) {
+    var _this = this;
+    return _asyncToGenerator(function* () {
+      var membershipData = _this.membershipDataFromMatrixEvent(matrixEvent);
+      var rtcBackendIdentity = membershipData.kind === MembershipKind.RTC ? yield computeRtcIdentityRaw(membershipData.data.member.user_id, membershipData.data.member.device_id, membershipData.data.member.id) : "".concat(matrixEvent.getSender(), ":").concat(membershipData.data.device_id);
+      return new CallMembership(matrixEvent, membershipData, rtcBackendIdentity);
+    })();
   }
-  return errors.length === 0;
-};
-// TODO: Rename to RtcMembership once we removed the legacy SessionMembership from this file.
-export class CallMembership {
   static equal(a, b) {
     return deepCompare(a === null || a === void 0 ? void 0 : a.membershipData, b === null || b === void 0 ? void 0 : b.membershipData);
   }
-  constructor(/** The required parts of the Matrix event that this membership is based on */
-  matrixEvent,
   /**
-   * The type checked membership data {data: (content of the matrix event), kind: (type hint)}
-   *
-   */
-  membershipData,
-  /**
-   *
-   * Anonymized identity to use with the RTC backend.
-   *
-   * The rtcBackendIdentity is a hashed version of all the identity parts:
-   * `sha256(${this.userId}|${this.deviceId}|${this.memberId})`
-   *
-   * It is used to anonymize the identity of the user in the RTC backend.
-   */
-  rtcBackendIdentity,
-  /**
-   * The constructor will automatically create a properly tagged child logger instance.
+   * Use `parseFromEvent`.
+   * Constructor should only be used by tests.
+   * @private
+   * @param matrixEvent
+   * @param membershipData
+   * @param rtcBackendIdentity
    */
-  logger) {
+  constructor(/** The Matrix event that this membership is based on */
+  matrixEvent, membershipData, rtcBackendIdentity) {
+    this.matrixEvent = matrixEvent;
     this.membershipData = membershipData;
     this.rtcBackendIdentity = rtcBackendIdentity;
     _defineProperty(this, "logger", void 0);
@@ -162,63 +112,15 @@ export class CallMembership {
      * To access checked eventId and sender from the matrixEvent.
      * Class construction will fail if these values cannot get obtained. */
     _defineProperty(this, "matrixEventData", void 0);
-    var [eventId, sender, ts] = [matrixEvent.getId(), matrixEvent.getSender(), matrixEvent.getTs()];
+    var eventId = matrixEvent.getId();
+    var sender = matrixEvent.getSender();
     if (eventId === undefined) throw new Error("parentEvent is missing eventId field");
     if (sender === undefined) throw new Error("parentEvent is missing sender field");
+    this.logger = logger.getChild("[CallMembership ".concat(sender, ":").concat(this.deviceId, "]"));
     this.matrixEventData = {
       eventId,
-      sender,
-      ts
+      sender
     };
-    this.logger = logger === null || logger === void 0 ? void 0 : logger.getChild("[CallMembership ".concat(sender, ":").concat(this.deviceId, "]"));
-  }
-
-  /**
-   * sha256(`${this.userId}|${this.deviceId}|${this.memberId}`) for sticky events (kind = rtc)
-   * `${this.userId}:${this.deviceId}` for state events (kind = session)
-   */
-  static computeRtcBackendIdentity(matrixEvent, membershipData) {
-    return _asyncToGenerator(function* () {
-      var {
-        kind,
-        data
-      } = membershipData;
-      switch (kind) {
-        case "rtc":
-          {
-            return CallMembership.computeRtcIdentityRaw(data.member.user_id, data.member.device_id, data.member.id);
-          }
-        case "session":
-          return "".concat(matrixEvent.getSender(), ":").concat(data.device_id);
-      }
-    })();
-  }
-  static computeRtcIdentityRaw(userId, deviceId, memberId) {
-    return _asyncToGenerator(function* () {
-      return encodeUnpaddedBase64(yield sha256("".concat(userId, "|").concat(deviceId, "|").concat(memberId)));
-    })();
-  }
-  static membershipDataFromMatrixEvent(matrixEvent) {
-    var [eventId, sender, content] = [matrixEvent.getId(), matrixEvent.getSender(), matrixEvent.getContent()];
-    if (eventId === undefined) throw new Error("parentEvent is missing eventId field");
-    if (sender === undefined) throw new Error("parentEvent is missing sender field");
-    var sessionErrors = [];
-    var rtcErrors = [];
-    if (checkSessionsMembershipData(content, sessionErrors)) {
-      return {
-        kind: "session",
-        data: content
-      };
-    } else if (checkRtcMembershipData(content, rtcErrors, sender)) {
-      return {
-        kind: "rtc",
-        data: content
-      };
-    } else {
-      var details = sessionErrors.length < rtcErrors.length ? "Does not match MSC4143 m.call.member:\n".concat(sessionErrors.join("\n"), "\n\n") : "Does not match MSC4143 m.rtc.member:\n".concat(rtcErrors.join("\n"), "\n\n");
-      var json = "\nevent:\n" + JSON.stringify(content).replaceAll('"', "'");
-      throw Error("unknown CallMembership data.\n" + details + json);
-    }
   }
 
   /** @deprecated use userId instead */
@@ -231,9 +133,9 @@ export class CallMembership {
       data
     } = this.membershipData;
     switch (kind) {
-      case "rtc":
+      case MembershipKind.RTC:
         return data.member.user_id;
-      case "session":
+      case MembershipKind.Session:
       default:
         return this.matrixEventData.sender;
     }
@@ -254,12 +156,12 @@ export class CallMembership {
     } = this.membershipData;
     if (data.application === "m.call") {
       switch (kind) {
-        case "rtc":
+        case MembershipKind.RTC:
           return data.slot_id;
-        case "session":
+        case MembershipKind.Session:
         default:
           {
-            var [application, id] = [this.application, data.call_id];
+            var [application, id] = [data.application, data.call_id];
 
             // INFO_SLOT_ID_LEGACY_CASE  (search for all occurances of this INFO to get the full picture)
             // The spec got changed to use `"ROOM"` instead of `""` empyt string for the implicit default call.
@@ -282,7 +184,7 @@ export class CallMembership {
             } else {
               compatibilityAdaptedId = id;
             }
-            return slotDescriptionToId({
+            return computeSlotId({
               application,
               id: compatibilityAdaptedId
             });
@@ -293,17 +195,14 @@ export class CallMembership {
     // This is what the function should look like for any other application that did not
     // go through a `""`=> `"ROOM"` rename
     switch (kind) {
-      case "rtc":
+      case MembershipKind.RTC:
         return data.slot_id;
-      case "session":
+      case MembershipKind.Session:
       default:
-        {
-          var [_application, _id] = [this.application, data.call_id];
-          return slotDescriptionToId({
-            application: _application,
-            id: _id
-          });
-        }
+        return computeSlotId({
+          application: data.application,
+          id: data.call_id
+        });
     }
   }
   get deviceId() {
@@ -312,64 +211,64 @@ export class CallMembership {
       data
     } = this.membershipData;
     switch (kind) {
-      case "rtc":
+      case MembershipKind.RTC:
         return data.member.device_id;
-      case "session":
+      case MembershipKind.Session:
       default:
         return data.device_id;
     }
   }
   get callIntent() {
-    var {
-      kind,
-      data
-    } = this.membershipData;
-    switch (kind) {
-      case "rtc":
-        {
-          var _this$logger3;
-          var intent = data.application["m.call.intent"];
-          if (typeof intent === "string") {
-            return intent;
-          }
-          (_this$logger3 = this.logger) === null || _this$logger3 === void 0 || _this$logger3.warn("RTC membership has invalid m.call.intent");
-          return undefined;
-        }
-      case "session":
-      default:
-        return data["m.call.intent"];
+    var intent = this.applicationData["m.call.intent"];
+    if (typeof intent === "string") {
+      return intent;
     }
+    this.logger.warn("RTC membership has invalid m.call.intent");
+    return undefined;
   }
 
   /**
    * Parsed `slot_id` (format `{application}#{id}`) into its components (application and id).
    */
   get slotDescription() {
-    return slotIdToDescription(this.slotId);
-  }
-  get application() {
     var {
       kind,
       data
     } = this.membershipData;
-    switch (kind) {
-      case "rtc":
-        return data.application.type;
-      case "session":
-      default:
-        return data.application;
+    if (kind === MembershipKind.RTC) {
+      var id = data.slot_id.slice("".concat(data.application.type, "#").length);
+      return {
+        application: data.application.type,
+        id
+      };
     }
+    return slotIdToDescription(this.slotId);
+  }
+
+  /**
+   * The application `type`.
+   * @deprecated Use @see applicationData
+   */
+  get application() {
+    return this.applicationData.type;
   }
+
+  /**
+   * Information about the application being used for the RTC session.
+   * May contain extra keys specific to the application.
+   */
   get applicationData() {
     var {
       kind,
       data
     } = this.membershipData;
     switch (kind) {
-      case "rtc":
+      case MembershipKind.RTC:
         return data.application;
-      case "session":
+      case MembershipKind.Session:
       default:
+        // SessionData does not have application data as such. We return specific
+        // properties in use by other getters in this class, for compatibility.
         return {
           "type": data.application,
           "m.call.intent": data["m.call.intent"]
@@ -384,19 +283,13 @@ export class CallMembership {
       data
     } = this.membershipData;
     switch (kind) {
-      case "rtc":
+      case MembershipKind.RTC:
         return undefined;
-      case "session":
+      case MembershipKind.Session:
       default:
         return data.scope;
     }
   }
-  /**
-   * @deprecated renamed to `memberId`
-   */
-  get membershipID() {
-    return this.memberId;
-  }
 
   /**
    * This computes the membership ID for the membership.
@@ -425,13 +318,21 @@ export class CallMembership {
       case "rtc":
         return data.member.id;
       case "session":
-      default:
         return (// best case we have a client already publishing the right custom membershipId
           (_data$membershipID = data.membershipID) !== null && _data$membershipID !== void 0 ? _data$membershipID : // alternativly we use the hard coded jwt id defuatl value (used until version 0.16.0)
           "".concat(this.matrixEventData.sender, ":").concat(data.device_id)
         );
+      default:
+        throw Error("Not possible to get memberID without knowing the membership event kind");
     }
   }
+
+  /**
+   * @deprecated renamed to `memberId`
+   */
+  get membershipID() {
+    return this.memberId;
+  }
   createdTs() {
     var _data$created_ts;
     var {
@@ -439,12 +340,12 @@ export class CallMembership {
       data
     } = this.membershipData;
     switch (kind) {
-      case "rtc":
+      case MembershipKind.RTC:
         // TODO we need to read the referenced (relation) event if available to get the real created_ts
-        return this.matrixEventData.ts;
-      case "session":
+        return this.matrixEvent.getTs();
+      case MembershipKind.Session:
       default:
-        return (_data$created_ts = data.created_ts) !== null && _data$created_ts !== void 0 ? _data$created_ts : this.matrixEventData.ts;
+        return (_data$created_ts = data.created_ts) !== null && _data$created_ts !== void 0 ? _data$created_ts : this.matrixEvent.getTs();
     }
   }
 
@@ -459,9 +360,9 @@ export class CallMembership {
       data
     } = this.membershipData;
     switch (kind) {
-      case "rtc":
+      case MembershipKind.RTC:
         return undefined;
-      case "session":
+      case MembershipKind.Session:
       default:
         // TODO: calculate this from the MatrixRTCSession join configuration directly
         return this.createdTs() + ((_data$expires = data.expires) !== null && _data$expires !== void 0 ? _data$expires : DEFAULT_EXPIRE_DURATION);
@@ -470,21 +371,22 @@ export class CallMembership {
 
   /**
    * @returns The number of milliseconds until the membership expires or undefined if applicable
+   * @deprecated Not used by RTC events.
    */
   getMsUntilExpiry() {
     var {
       kind
     } = this.membershipData;
-    switch (kind) {
-      case "rtc":
-        return undefined;
-      case "session":
-      default:
+    if (kind === MembershipKind.Session) {
+      var absExpiry = this.getAbsoluteExpiry();
+      if (absExpiry) {
         // Assume that local clock is sufficiently in sync with other clocks in the distributed system.
         // We used to try and adjust for the local clock being skewed, but there are cases where this is not accurate.
         // The current implementation allows for the local clock to be -infinity to +MatrixRTCSession.MEMBERSHIP_EXPIRY_TIME/2
-        return this.getAbsoluteExpiry() - Date.now();
+        return absExpiry - Date.now();
+      }
     }
+    return undefined;
   }
 
   /**
@@ -495,9 +397,9 @@ export class CallMembership {
       kind
     } = this.membershipData;
     switch (kind) {
-      case "rtc":
+      case MembershipKind.RTC:
         return false;
-      case "session":
+      case MembershipKind.Session:
       default:
         return this.getMsUntilExpiry() <= 0;
     }
@@ -526,33 +428,26 @@ export class CallMembership {
       data
     } = this.membershipData;
     switch (kind) {
-      case "rtc":
+      case MembershipKind.RTC:
         return data.rtc_transports[0];
-      case "session":
+      case MembershipKind.Session:
         switch (data.focus_active.focus_selection) {
-          case "multi_sfu":
-            return data.foci_preferred[0];
           case "oldest_membership":
             if (CallMembership.equal(this, oldestMembership)) return data.foci_preferred[0];
             if (oldestMembership !== undefined) return oldestMembership.getTransport(oldestMembership);
             break;
+          case "multi_sfu":
+            return data.foci_preferred[0];
+          default:
+            // `focus_selection` not understood.
+            return undefined;
         }
+        break;
+      default:
+        return undefined;
     }
-    return undefined;
   }
 
-  /**
-   * The focus_active filed of the session membership (m.call.member).
-   * @deprecated focus_active is not used and will be removed in future versions.
-   */
-  getFocusActive() {
-    var {
-      kind,
-      data
-    } = this.membershipData;
-    if (kind === "session") return data.focus_active;
-    return undefined;
-  }
   /**
    * The value of the `rtc_transports` field for RTC memberships (m.rtc.member).
    * Or the value of the `foci_preferred` field for legacy session memberships (m.call.member).
@@ -563,15 +458,12 @@ export class CallMembership {
       data
     } = this.membershipData;
     switch (kind) {
-      case "rtc":
+      case MembershipKind.RTC:
         return data.rtc_transports;
-      case "session":
+      case MembershipKind.Session:
       default:
         return data.foci_preferred;
     }
   }
-  get kind() {
-    return this.membershipData.kind;
-  }
 }
 //# sourceMappingURL=CallMembership.js.map