matrix-js-sdk 42.4.0 → 43.0.0

package/src/http-api/refresh.ts

@@ -15,8 +15,10 @@ limitations under the License.
 */
 
 import { MatrixError, TokenRefreshLogoutError } from "./errors.ts";
-import { type IHttpOpts } from "./interface.ts";
+import { type AccessTokens, type IHttpOpts, type OAuth2ClientConfig } from "./interface.ts";
 import { sleep } from "../utils.ts";
+import { TokenRefresher } from "../oauth/tokenRefresher.ts";
+import { OAuth2, type ValidatedAuthMetadata } from "../oauth/index.ts";
 
 /**
  * This is an internal module. See {@link MatrixHttpApi} for the public class.
@@ -28,25 +30,25 @@ export const enum TokenRefreshOutcome {
     Logout = "logout",
 }
 
-interface Snapshot {
-    accessToken: string;
-    refreshToken?: string;
-    expiry?: Date;
-}
-
 // If the token expires in less than this time amount of time, we will eagerly refresh it before making the intended request.
 const REFRESH_IF_TOKEN_EXPIRES_WITHIN_MS = 500;
 // If we get an unknown token error and the token expires in less than this time amount of time, we will refresh it before making the intended request.
 // Otherwise, we will error as the token should not have expired yet and we need to avoid retrying indefinitely.
 const REFRESH_ON_ERROR_IF_TOKEN_EXPIRES_WITHIN_MS = 60 * 1000;
 
-type Opts = Pick<IHttpOpts, "tokenRefreshFunction" | "logger" | "refreshToken" | "accessToken">;
+type Opts = Pick<
+    IHttpOpts,
+    "onTokenRefresh" | "logger" | "refreshToken" | "accessToken" | "oauth2ClientConfig" | "authMetadataCallback"
+>;
 
 /**
  * This class is responsible for managing the access token and refresh token for authenticated requests.
- * It will automatically refresh the access token when it is about to expire, and will handle unknown token errors.
+ * It will automatically refresh the tokens when the access token is about to expire and can handle
+ * Unknown Token errors (via {@link TokenManager.handleUnknownToken})
+ *
+ * It will update the {@link Opts} object with new tokens as they are refreshed, and also call the {@link IHttpOpts.onTokenRefresh} callback if provided.
  */
-export class TokenRefresher {
+export class TokenManager {
     public constructor(private readonly opts: Opts) {}
 
     /**
@@ -57,12 +59,22 @@ export class TokenRefresher {
 
     private latestTokenRefreshExpiry?: Date;
 
+    // The object at the OAuth API layer that actually does the refreshing
+    // This needs OAuth params to be fetched before it can be constructed so it starts
+    // off as undefined and is constructed once we are able to do so.
+    private tokenRefresher?: TokenRefresher;
+
+    // Tracks an in-progress attempt to discover the OAuth2 auth server metadata and construct
+    // `tokenRefresher`, so that concurrent callers wait for (and share the result of) the same attempt
+    // rather than racing to discover it independently.
+    private tokenRefresherPromise?: Promise<TokenRefresher>;
+
     /**
      * This function is called before every request to ensure that the access token is valid.
      * @returns a snapshot containing the access token and other properties which must be passed to the handleUnknownToken
      *     handler if an M_UNKNOWN_TOKEN error is encountered.
      */
-    public async prepareForRequest(): Promise<Snapshot> {
+    public async prepareForRequest(): Promise<AccessTokens> {
         // Ensure our token is refreshed before we build the headers/params
         await this.refreshIfNeeded();
 
@@ -93,13 +105,13 @@ export class TokenRefresher {
      * @param attempt - the number of attempts made for this request so far
      * @returns a TokenRefreshOutcome indicating the result of the refresh attempt
      */
-    public async handleUnknownToken(snapshot: Snapshot, attempt: number): Promise<TokenRefreshOutcome> {
+    public async handleUnknownToken(snapshot: AccessTokens, attempt: number): Promise<TokenRefreshOutcome> {
         return this._handleUnknownToken(snapshot, attempt);
     }
 
     private async _handleUnknownToken(): Promise<TokenRefreshOutcome>;
-    private async _handleUnknownToken(snapshot: Snapshot, attempt: number): Promise<TokenRefreshOutcome>;
-    private async _handleUnknownToken(snapshot?: Snapshot, attempt?: number): Promise<TokenRefreshOutcome> {
+    private async _handleUnknownToken(snapshot: AccessTokens, attempt: number): Promise<TokenRefreshOutcome>;
+    private async _handleUnknownToken(snapshot?: AccessTokens, attempt?: number): Promise<TokenRefreshOutcome> {
         if (snapshot?.expiry) {
             // If our token is unknown, but it should not have expired yet, then we should not refresh
             const expiresIn = snapshot.expiry.getTime() - Date.now();
@@ -132,8 +144,8 @@ export class TokenRefresher {
      * @returns Promise that resolves to a boolean - true when token was refreshed successfully
      */
     private async doTokenRefresh(attempt?: number): Promise<TokenRefreshOutcome> {
-        if (!this.opts.refreshToken || !this.opts.tokenRefreshFunction) {
-            this.opts.logger?.error("Unable to refresh token - no refresh token or refresh function");
+        if (!this.opts.refreshToken || !this.opts.oauth2ClientConfig) {
+            this.opts.logger?.error("Unable to refresh token - no refresh token or OAuth2 client config");
             return TokenRefreshOutcome.Logout;
         }
 
@@ -144,7 +156,13 @@ export class TokenRefresher {
 
         try {
             this.opts.logger?.debug("Attempting to refresh token");
-            const { accessToken, refreshToken, expiry } = await this.opts.tokenRefreshFunction(this.opts.refreshToken);
+            const tokenRefresher = await this.ensureTokenRefresher();
+            if (!tokenRefresher) {
+                // We already checked `oauth2ClientConfig` is set above, so this should be unreachable.
+                return TokenRefreshOutcome.Logout;
+            }
+
+            const { accessToken, refreshToken, expiry } = await tokenRefresher.refreshTokens(this.opts.refreshToken);
             this.opts.accessToken = accessToken;
             this.opts.refreshToken = refreshToken;
             this.latestTokenRefreshExpiry = expiry;
@@ -163,4 +181,70 @@ export class TokenRefresher {
             return TokenRefreshOutcome.Failure;
         }
     }
+
+    /**
+     * Attempt to revoke the current access and refresh tokens with the OAuth2 authorization server, e.g. as
+     * part of logging out. Does nothing if this is not an OAuth2-native session (ie. no `oauth2ClientConfig`
+     * was supplied).
+     * @throws when discovery of the auth server metadata, or revocation of either token, fails
+     */
+    public async revokeTokens(): Promise<void> {
+        const tokenRefresher = await this.ensureTokenRefresher();
+        if (!tokenRefresher) return;
+
+        await Promise.all(
+            [
+                this.opts.accessToken ? tokenRefresher.revokeToken(this.opts.accessToken, "access_token") : undefined,
+                this.opts.refreshToken
+                    ? tokenRefresher.revokeToken(this.opts.refreshToken, "refresh_token")
+                    : undefined,
+            ].filter((p): p is Promise<void> => p !== undefined),
+        );
+    }
+
+    /**
+     * Lazily constructs (and caches) the {@link TokenRefresher} used to talk to the OAuth2 authorization
+     * server, discovering its metadata first if this is the first time it's needed.
+     * @returns the token refresher, or undefined if no `oauth2ClientConfig` was supplied
+     * @throws when discovery of the auth server metadata fails in a way that isn't worth retrying
+     */
+    private async ensureTokenRefresher(): Promise<TokenRefresher | undefined> {
+        if (this.tokenRefresher) return this.tokenRefresher;
+        if (!this.opts.oauth2ClientConfig) return undefined;
+        if (!this.opts.authMetadataCallback) return undefined;
+
+        if (!this.tokenRefresherPromise) {
+            this.tokenRefresherPromise = this.discoverTokenRefresher(
+                this.opts.oauth2ClientConfig,
+                this.opts.authMetadataCallback,
+            );
+        }
+
+        try {
+            this.tokenRefresher = await this.tokenRefresherPromise;
+            return this.tokenRefresher;
+        } finally {
+            // Either we now have `tokenRefresher` cached and won't need this again, or discovery
+            // failed and a future call should be free to retry from scratch.
+            this.tokenRefresherPromise = undefined;
+        }
+    }
+
+    /**
+     * Discovers the OAuth2 auth server metadata and constructs the OAuth2 client and token refresher from it.
+     * Throws if the request fails.
+     */
+    private async discoverTokenRefresher(
+        config: OAuth2ClientConfig,
+        authMetaDataCallback: () => Promise<ValidatedAuthMetadata>,
+    ): Promise<TokenRefresher> {
+        const metadata = await authMetaDataCallback();
+
+        const oauth2 = new OAuth2(metadata, {
+            clientId: config.clientId,
+            deviceId: config.deviceId,
+        });
+
+        return new TokenRefresher(oauth2, (tokens) => this.opts.onTokenRefresh?.(tokens));
+    }
 }

package/src/matrix.ts

@@ -84,7 +84,7 @@ export * from "./models/event-status.ts";
 export * from "./models/profile-keys.ts";
 export * from "./models/related-relations.ts";
 export { type StickyMatrixEvent, RoomStickyEventsEvent } from "./models/room-sticky-events.ts";
-export type { RoomSummary } from "./client.ts";
+export type { RoomSummary } from "./room-summary-api.ts";
 export * as ContentHelpers from "./content-helpers.ts";
 export * as SecretStorage from "./secret-storage.ts";
 export { createNewMatrixCall, CallEvent } from "./webrtc/call.ts";

package/src/matrixrtc/CallMembership.ts

@@ -36,6 +36,20 @@ import { EventType } from "../@types/event.ts";
  */
 export const DEFAULT_EXPIRE_DURATION = 1000 * 60 * 60 * 4;
 
+/** The fields of a legacy session membership that belong to the session, not the application */
+const sessionFields: (keyof SessionMembershipData)[] = [
+    "application",
+    "call_id",
+    "device_id",
+    "focus_active",
+    "foci_preferred",
+    "created_ts",
+    "scope",
+    "expires",
+    "m.call.intent",
+    "membershipID",
+];
+
 /**
  * Describes the source event type that provided the membership data.
  */
@@ -261,10 +275,14 @@ export class CallMembership {
             case MembershipKind.RTC:
                 return data.application;
             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"] };
+            default: {
+                // SessionData has no application object: the application's own
+                // data sits at the top level beside the session fields, so
+                // everything but those is the application's
+                const { application, ...rest } = data;
+                for (const key of sessionFields) delete rest[key as keyof typeof rest];
+                return { ...rest, "type": application, "m.call.intent": data["m.call.intent"] };
+            }
         }
     }
 

package/src/matrixrtc/IMembershipManager.ts

@@ -117,4 +117,10 @@ export interface IMembershipManager extends TypedEventEmitter<
      * @param callIntent The new intent to set.
      */
     updateCallIntent(callIntent: RTCCallIntent): Promise<void>;
+
+    /**
+     * Replace the application-specific data of our membership (see
+     * `SessionConfig.applicationData`), re-sending the membership if it changed.
+     */
+    updateApplicationData(applicationData: Record<string, unknown>): Promise<void>;
 }

package/src/matrixrtc/MatrixRTCSession.ts

@@ -38,6 +38,9 @@ import type {
     RtcSlotEventContent,
     RtcSlotEncryptionContent,
 } from "./types.ts";
+import { RTC_NOTIFICATION_MAX_SENDER_TS_AHEAD_MS } from "./types.ts";
+import { isLeftMembershipContent } from "./membershipData/index.ts";
+import { UnsupportedStickyEventsEndpointError } from "../errors.ts";
 import {
     MembershipManagerEvent,
     type MembershipManagerEventHandlerMap,
@@ -48,7 +51,7 @@ import { ToDeviceKeyTransport } from "./ToDeviceKeyTransport.ts";
 import { TypedReEmitter } from "../ReEmitter.ts";
 import { type IContent, type MatrixEvent } from "../models/event.ts";
 import { RoomStickyEventsEvent, type RoomStickyEventsMap } from "../models/room-sticky-events.ts";
-import { computeSlotId } from "./utils.ts";
+import { computeSlotId, getSlotEventContent, isSlotClosed, isSlotOpen } from "./utils.ts";
 
 /**
  * Events emitted by MatrixRTCSession
@@ -101,6 +104,15 @@ export interface SessionConfig {
      */
     callIntent?: RTCCallIntent;
 
+    /**
+     * Application-specific data to publish in our membership alongside the
+     * application `type` and `m.call.intent`: in the `application` object of
+     * an `m.rtc.member` event, or at the top level of a legacy `m.call.member`
+     * one. Keys should be namespaced. Read back through
+     * {@link CallMembership.applicationData}.
+     */
+    applicationData?: Record<string, unknown>;
+
     /**
      * How long (in milliseconds) the callee's client should keep ringing/waiting for an
      * answer before the sender gives up and the call notification is considered timed out.
@@ -358,6 +370,16 @@ export class MatrixRTCSession extends TypedEventEmitter<
         return isSlotClosed(this.roomSubset, this.slotDescription);
     }
 
+    /**
+     * Whether this session's slot is open.
+     *
+     * @returns `true` if the slot is open, `false` if the slot is closed or `undefined`
+     * if no slot exists.
+     */
+    public isSlotOpen(): boolean | undefined {
+        return isSlotOpen(this.roomSubset, this.slotDescription);
+    }
+
     /**
      * Ensures this session's slot is open, sending a slot state event to open (or create) it if needed.
      *
@@ -721,6 +743,18 @@ export class MatrixRTCSession extends TypedEventEmitter<
         await this.membershipManager?.updateCallIntent(callIntent);
     }
 
+    /**
+     * Replace the application-specific data in our membership (see
+     * {@link SessionConfig.applicationData}), re-sending it if it changed.
+     */
+    public async updateApplicationData(applicationData: Record<string, unknown>): Promise<void> {
+        const myMembership = this.membershipManager?.ownMembership;
+        if (!myMembership) {
+            throw Error("Not connected yet");
+        }
+        await this.membershipManager?.updateApplicationData(applicationData);
+    }
+
     /**
      * Re-emit an EncryptionKeyChanged event for each tracked encryption key. This can be used to export
      * the keys.
@@ -776,11 +810,13 @@ export class MatrixRTCSession extends TypedEventEmitter<
         callIntent?: RTCCallIntent,
     ): void {
         const lifetime = this.joinConfig?.notificationLifetimeMs ?? 90_000;
+        const slotId = computeSlotId(this.slotDescription);
         const sendNotificationEvent = async (): Promise<{
             response: ISendEventResponse;
             content: IRTCNotificationContent;
         }> => {
             const content: IRTCNotificationContent = {
+                "slot_id": slotId,
                 "m.mentions": { user_ids: [], room: true },
                 "notification_type": notificationType,
                 "m.relates_to": {
@@ -789,12 +825,12 @@ export class MatrixRTCSession extends TypedEventEmitter<
                 },
                 "sender_ts": Date.now(),
                 "lifetime": lifetime,
+                "msc4354_sticky_key": slotId,
             };
             if (callIntent) {
                 content["m.call.intent"] = callIntent;
             }
-            const response = await this.client.sendEvent(this.roomSubset.roomId, EventType.RTCNotification, content);
-            return { response, content };
+            return { response: await this.sendNotificationEvent(content), content };
         };
 
         void sendNotificationEvent()
@@ -803,9 +839,30 @@ export class MatrixRTCSession extends TypedEventEmitter<
                 const newResult = { ...notification.response, ...notification.content };
                 this.emit(MatrixRTCSessionEvent.DidSendCallNotification, newResult);
             })
-            .catch(([errorLegacy, errorNew]) =>
-                this.logger.error("Failed to send call notification", errorLegacy, errorNew),
+            .catch((error) => this.logger.error("Failed to send call notification", error));
+    }
+
+    /**
+     * Sends a notification event, as a sticky event (MSC4354) where the server supports it.
+     */
+    private async sendNotificationEvent(content: IRTCNotificationContent): Promise<ISendEventResponse> {
+        const roomId = this.roomSubset.roomId;
+        try {
+            // Stay sticky slightly longer than the lifetime, since the server measures the sticky duration
+            // from `origin_server_ts` while receivers measure the lifetime from `sender_ts`.
+            const stickyDurationMs = content.lifetime + RTC_NOTIFICATION_MAX_SENDER_TS_AHEAD_MS;
+            return await this.client._unstable_sendStickyEvent(
+                roomId,
+                stickyDurationMs,
+                null,
+                EventType.RTCNotification,
+                content,
             );
+        } catch (error) {
+            if (!(error instanceof UnsupportedStickyEventsEndpointError)) throw error;
+            this.logger.debug("Server does not support sticky events, sending notification as a regular event");
+            return await this.client.sendEvent(roomId, EventType.RTCNotification, content);
+        }
     }
 
     /**
@@ -843,13 +900,14 @@ export class MatrixRTCSession extends TypedEventEmitter<
 
     /**
      * Call this when something changed that may impacts the current MatrixRTC members in this session.
+     *
+     * @deprecated use {@link ensureRecalculateSessionMembers} instead.
      */
-    // We allow this name schema since this function should only be used for testing purposes.
     public _onRTCSessionMemberUpdate = async (): Promise<void> => {
-        await this.recalculateSessionMembers();
+        await this.ensureRecalculateSessionMembers();
     };
 
-    // helper variables to make sure we do not have parallel running recalculations.
+    // Recalculations are chained onto this promise, so they never run in parallel.
     private recalculateSessionMembersPromise: Promise<void> = Promise.resolve();
 
     /**
@@ -857,7 +915,7 @@ export class MatrixRTCSession extends TypedEventEmitter<
      * Also ensures that only one recalculation is made at a time.
      * @returns A promise resolving when the state has been recalculated.
      */
-    private ensureRecalculateSessionMembers(): Promise<void> {
+    public ensureRecalculateSessionMembers(): Promise<void> {
         if (this.membershipNeedsRecalculation) {
             // We have already requested recalcuation, don't attempt a new one.
             return this.recalculateSessionMembersPromise;
@@ -952,7 +1010,7 @@ async function computeBackendIdentityAndVerifyMemberEvents(
         const content = memberEvent.getContent();
 
         // Quick filter to avoid unneeded processing of invalid events or left events.
-        if (!quickFilterNonRelevantContents(content, logger)) {
+        if (!quickFilterNonRelevantContents(content)) {
             continue;
         }
 
@@ -970,11 +1028,12 @@ async function computeBackendIdentityAndVerifyMemberEvents(
     return callMemberships;
 }
 
-function quickFilterNonRelevantContents(content: IContent, logger: Logger): boolean {
+function quickFilterNonRelevantContents(content: IContent): boolean {
+    // Don't even bother about left memberships (saves us from costly type/"key in" checks in bigger rooms)
+    if (isLeftMembershipContent(content)) return false;
+
     // Ignore sticky keys for the count
     const eventKeysCount = Object.keys(content).filter((k) => k !== "msc4354_sticky_key").length;
-    // Don't even bother about empty events (saves us from costly type/"key in" checks in bigger rooms)
-    if (eventKeysCount === 0) return false;
 
     // We first decide if it's a MSC4143 event (per device state key)
     if (eventKeysCount > 1 && "application" in content) {
@@ -1016,42 +1075,6 @@ function isValidMembership(
     return true;
 }
 
-/**
- * Reads the slot state event's content for the given slot description.
- *
- * @returns The slot event's content, or `undefined` if no slot event exists for the given description.
- */
-function getSlotEventContent(
-    room: Pick<Room, "getLiveTimeline">,
-    slotDescription: SlotDescription,
-): RtcSlotEventContent | undefined {
-    const slotId = computeSlotId(slotDescription);
-    const slotEvent = room
-        .getLiveTimeline()
-        .getState(EventTimeline.FORWARDS)
-        ?.getStateEvents(EventType.RTCSlot, slotId);
-    if (!slotEvent) return undefined;
-
-    return slotEvent.getContent<RtcSlotEventContent>();
-}
-
-/**
- * Whether the given slot is closed.
- *
- * @returns `true` if the slot is closed, `false` if the slot is open or `undefined`
- * if no slot exists.
- */
-function isSlotClosed(room: Pick<Room, "getLiveTimeline">, slotDescription: SlotDescription): boolean | undefined {
-    const content = getSlotEventContent(room, slotDescription) as Partial<RtcSlotEventContent> | undefined;
-    if (content === undefined) return undefined;
-
-    return (
-        content.status !== "open" ||
-        typeof content.application !== "object" ||
-        content.application?.type !== slotDescription.application
-    );
-}
-
 /**
  * Collects the raw member events from room state and sticky store.
  */

package/src/matrixrtc/MatrixRTCSessionManager.ts

@@ -172,7 +172,7 @@ export class MatrixRTCSessionManager extends TypedEventEmitter<MatrixRTCSessionM
         // Alternatively we would need to setup some event emission when the RTC session ended.
         // TODO we want to add the emission en session end. This makes the responsibility of the session manager more clear.
 
-        await session._onRTCSessionMemberUpdate().catch((error) => {
+        await session.ensureRecalculateSessionMembers().catch((error) => {
             this.logger.error(`Error updating RTC session members for ${room.roomId}: ${error}`);
         });