matrix-js-sdk 42.3.0 → 42.4.0

package/src/matrixrtc/MatrixRTCSession.ts

@@ -26,7 +26,7 @@ import { CallMembership } from "./CallMembership.ts";
 import { RoomStateEvent } from "../models/room-state.ts";
 import { MembershipManager, StickyEventMembershipManager } from "./MembershipManager.ts";
 import { type CallMembershipIdentityParts, type IEncryptionManager } from "./EncryptionManager.ts";
-import { logDurationSync } from "../utils.ts";
+import { deepCompare, logDurationSync } from "../utils.ts";
 import type {
     Statistics,
     RTCNotificationType,
@@ -36,6 +36,7 @@ import type {
     Transport,
     SlotDescription,
     RtcSlotEventContent,
+    RtcSlotEncryptionContent,
 } from "./types.ts";
 import {
     MembershipManagerEvent,
@@ -65,6 +66,8 @@ export enum MatrixRTCSessionEvent {
     MembershipManagerError = "membership_manager_error",
     /** The RTCSession did send a call notification caused by joining the call as the first member */
     DidSendCallNotification = "did_send_call_notification",
+    /** Whether the session is too large for the media key to be rotated has changed */
+    KeyRotationSuppressedChanged = "key_rotation_suppressed_changed",
 }
 
 export type MatrixRTCSessionEventHandlerMap = {
@@ -83,6 +86,7 @@ export type MatrixRTCSessionEventHandlerMap = {
     [MatrixRTCSessionEvent.DidSendCallNotification]: (
         notificationContentNew: { event_id: string } & IRTCNotificationContent,
     ) => void;
+    [MatrixRTCSessionEvent.KeyRotationSuppressedChanged]: (isKeyRotationSuppressed: boolean) => void;
 };
 
 export interface SessionConfig {
@@ -204,6 +208,17 @@ export interface EncryptionConfig {
      */
     keyRotationGracePeriodMs?: number;
 
+    /**
+     * The number of participants in the session at which the media key will no longer be rotated.
+     *
+     * Rotating a key requires sending it to every participant device, so in large sessions the cost of rotating
+     * on every join/leave becomes prohibitive. At this limit the current key is kept and
+     * distributed to new joiners. No new keys are generated for joiners/leavers.
+     *
+     * Defaults to undefined.
+     */
+    keyRotationParticipantLimit?: number;
+
     /**
      * The delay (in milliseconds) after a member leaves before we create and publish a new key, because people
      * tend to leave calls at the same time.
@@ -296,6 +311,14 @@ export class MatrixRTCSession extends TypedEventEmitter<
         return this.membershipManager?.delayId;
     }
 
+    /**
+     * Whether the key rotation is currently halted.
+     * mirror of: EncryptionConfig.keyRotationParticipantLimit
+     */
+    public get isKeyRotationSuppressed(): boolean {
+        return this.encryptionManager?.isKeyRotationSuppressed ?? false;
+    }
+
     /**
      * The callId (sessionId) of the call.
      *
@@ -335,6 +358,55 @@ export class MatrixRTCSession extends TypedEventEmitter<
         return isSlotClosed(this.roomSubset, this.slotDescription);
     }
 
+    /**
+     * Ensures this session's slot is open, sending a slot state event to open (or create) it if needed.
+     *
+     * The event's `application` is set from this session's slot description and its `encryption` from
+     * `opts.encryption`, replacing whatever an existing slot event declares. Other content is preserved.
+     * No-op if the slot is already open with matching `application` and `encryption`.
+     *
+     * @param opts.encryption - The encryption to declare on the slot, or `undefined` for none.
+     * @throws if sending the state event fails.
+     */
+    public async ensureRtcSlotOpen(opts: { encryption?: RtcSlotEncryptionContent } = {}): Promise<void> {
+        const application = { type: this.slotDescription.application };
+        const existingContent = this.getRtcSlot();
+        if (
+            existingContent?.status === "open" &&
+            deepCompare(existingContent.application, application) &&
+            deepCompare(existingContent.encryption, opts.encryption)
+        ) {
+            return;
+        }
+        await this.sendRtcSlot({
+            ...existingContent,
+            status: "open",
+            application,
+            encryption: opts.encryption,
+        });
+    }
+
+    /**
+     * Ensures this session's slot is closed, sending a slot state event to close it if needed.
+     * The other content of the existing slot event is preserved. No-op if no slot event exists.
+     *
+     * @throws if sending the state event fails.
+     */
+    public async ensureRtcSlotClosed(): Promise<void> {
+        const existingContent = this.getRtcSlot();
+        if (!existingContent || existingContent.status === "closed") return;
+        await this.sendRtcSlot({ ...existingContent, status: "closed" });
+    }
+
+    private async sendRtcSlot(content: RtcSlotEventContent): Promise<void> {
+        await this.client.sendStateEvent(
+            this.roomSubset.roomId,
+            EventType.RTCSlot,
+            content,
+            computeSlotId(this.slotDescription),
+        );
+    }
+
     /**
      * Returns all the call memberships for a room that match the provided `sessionDescription`,
      * oldest first.
@@ -810,6 +882,8 @@ export class MatrixRTCSession extends TypedEventEmitter<
         // Clear the flag.
         this.membershipNeedsRecalculation = false;
         const oldMemberships = this.memberships;
+        // Needs to be computed before `this.memberships` is updated below, since it is derived from it.
+        const wasKeyRotationSuppressed = this.isKeyRotationSuppressed;
 
         this.memberships = await MatrixRTCSession.sessionMembershipsForSlot(
             this.room,
@@ -854,6 +928,12 @@ export class MatrixRTCSession extends TypedEventEmitter<
         // This also needs to be done if `changed` = false
         // A member might have updated their fingerprint (created_ts)
         this.encryptionManager?.onMembershipsUpdate(oldMemberships);
+        if (this.isKeyRotationSuppressed !== wasKeyRotationSuppressed) {
+            this.logger.info(
+                `Key rotation is now ${this.isKeyRotationSuppressed ? "suppressed" : "active again"} (${this.memberships.length} members)`,
+            );
+            this.emit(MatrixRTCSessionEvent.KeyRotationSuppressedChanged, this.isKeyRotationSuppressed);
+        }
 
         this.setExpiryTimer();
     };

package/src/matrixrtc/MembershipManager.ts

@@ -919,15 +919,15 @@ export class MembershipManager
         const retryCounterString = "(" + retries + "/" + this.maximumNetworkErrorRetryCount + ")";
 
         // Variables for scheduling the new event
-        let retryDuration = this.networkErrorRetryMs;
+        const retryDuration = this.networkErrorRetryMs;
 
         if (error instanceof Error && error.name === "AbortError") {
-            // We do not wait for the timeout on local timeouts.
-            retryDuration = 0;
-            this.logger.warn(
-                "Network local timeout error while sending event, immediate retry (" + retryCounterString + ")",
-                error,
-            );
+            // A local timeout means the server accepted the request but is slow to answer. Retry immediately and
+            // do not count it towards the fatal retry limit: the server's delayed leave already bounds how long a
+            // stalled restart can go unnoticed, and the resulting forced re-join recovers the membership. Giving
+            // up here would only replace a temporary media pause with a "connection lost" error for the user.
+            this.logger.warn("Network local timeout error while sending event, immediate retry", error);
+            return createInsertActionUpdate(type, 0);
         } else if (error instanceof Error && error.message.includes("updating delayed event")) {
             // TODO: We do not want error message matching here but instead the error should be a typed HTTPError
             // and be handled below automatically (the same as in the SPA case).

package/src/matrixrtc/RTCEncryptionManager.ts

@@ -34,6 +34,17 @@ import {
 import { OutdatedKeyFilter } from "./utils.ts";
 import { computeRtcIdentityRaw } from "./membershipData/rtc.ts";
 
+/**
+ * Default for {@link EncryptionConfig.keyRotationParticipantLimit}.
+ *
+ * Setting this to undefined implies that we do not have a limit and full rotations are always done.
+ * This is the most secure and least performant option.
+ * It is highly recommended to set this to < 50 for client deployments that are planned to be used for large calls.
+ * But before setting this, make yourself familiar with the exact security implications.
+ * Key, rotations will stop when reaching this user limit in a call. The call will still be encrypted.
+ */
+const DEFAULT_KEY_ROTATION_PARTICIPANT_LIMIT: number | undefined = undefined;
+
 /**
  * RTCEncryptionManager is used to manage the encryption keys for a call.
  *
@@ -93,6 +104,14 @@ export class RTCEncryptionManager implements IEncryptionManager {
      */
     private keyRotationGracePeriodMs = 10_000;
 
+    /**
+     * The number of participants at or above which we stop rotating the key altogether.
+     * The current key is still distributed to new joiners, but no new key is generated.
+     * @see EncryptionConfig.keyRotationParticipantLimit
+     * @private
+     */
+    private keyRotationParticipantLimit = DEFAULT_KEY_ROTATION_PARTICIPANT_LIMIT;
+
     /**
      * If a new key distribution is being requested while one is going on, we will set this flag to true.
      * This will ensure that a new round is started after the current one.
@@ -141,6 +160,21 @@ export class RTCEncryptionManager implements IEncryptionManager {
         this.rtcIdentityProvider = rtcBackendIdProvider ?? computeRtcIdentityRaw;
     }
 
+    /**
+     * Whether the session currently has too many participants for the key to be rotated.
+     *
+     * This is computed by checking the participant count. If there are too many participants for efficient rotations,
+     * the key rotation will be suppressed.
+     * While this is true, the current key is still shared with new joiners and the current call is still fully encrypted,
+     * but no new key is generated for joiners or leavers. Changes are signalled by {@link MatrixRTCSessionEvent.KeyRotationSuppressedChanged}.
+     * @see EncryptionConfig.keyRotationParticipantLimit
+     */
+    public get isKeyRotationSuppressed(): boolean {
+        if (!this.manageMediaKeys) return false;
+        if (this.keyRotationParticipantLimit === undefined) return false;
+        return this.getMemberships().length >= this.keyRotationParticipantLimit;
+    }
+
     private async getOwnRtcBackendIdentity(): Promise<string> {
         if (this.ownRtcBackendIdentityCache) return this.ownRtcBackendIdentityCache;
 
@@ -221,6 +255,8 @@ export class RTCEncryptionManager implements IEncryptionManager {
         this.useHashedRtcBackendIdentity = joinConfig?.unstableSendStickyEvents ?? false;
         this.useKeyDelay = joinConfig?.useKeyDelay ?? 1000;
         this.keyRotationGracePeriodMs = joinConfig?.keyRotationGracePeriodMs ?? 10_000;
+        this.keyRotationParticipantLimit =
+            joinConfig?.keyRotationParticipantLimit ?? DEFAULT_KEY_ROTATION_PARTICIPANT_LIMIT;
 
         this.transport.on(KeyTransportEvents.ReceivedKeys, this.onNewKeyReceived);
         void this.getOwnRtcBackendIdentity(); // precompute own identity
@@ -374,53 +410,66 @@ export class RTCEncryptionManager implements IEncryptionManager {
         );
 
         let toDistributeTo: ParticipantDeviceInfo[] = [];
-        let outboundKey: OutboundEncryptionSession;
+        //default to current session
+        let newOutboundEncryptionSession: OutboundEncryptionSession = this.outboundSession!;
         let hasKeyChanged = false;
-        if (anyLeft.length > 0) {
-            // We need to rotate the key
-            const newOutboundKey = this.createNewOutboundSession();
-            hasKeyChanged = true;
-            toDistributeTo = toShareWith;
-            outboundKey = newOutboundKey;
-        } else if (anyJoined.length > 0) {
-            const now = Date.now();
-            const keyAge = now - this.outboundSession!.creationTS;
-            // If the current key is recently created (less than `keyRotationGracePeriodMs`), we can keep it and just distribute it to the new joiners.
-            if (keyAge < this.keyRotationGracePeriodMs) {
-                // keep the same key
-                // XXX In the future we want to distribute a ratcheted key, not the current one
-                this.logger?.debug(`New joiners detected, but the key is recent enough (age:${keyAge}), keeping it`);
-                toDistributeTo = anyJoined;
-                outboundKey = this.outboundSession!;
-            } else {
+
+        // Rotating means sending the new key to every participant, this is expensive in large session.
+        if (this.isKeyRotationSuppressed) {
+            if (anyJoined.length > 0) {
+                this.logger?.debug(
+                    `New joiners detected, but the session has ${toShareWith.length} participants (limit:${this.keyRotationParticipantLimit}), keeping the key`,
+                );
+            }
+            toDistributeTo = anyJoined;
+        } else {
+            if (anyLeft.length > 0) {
                 // We need to rotate the key
-                this.logger?.debug(`New joiners detected, rotating the key`);
-                const newOutboundKey = this.createNewOutboundSession();
+                newOutboundEncryptionSession = this.createNewOutboundSession();
                 hasKeyChanged = true;
                 toDistributeTo = toShareWith;
-                outboundKey = newOutboundKey;
+            } else if (anyJoined.length > 0) {
+                const keyAge = Date.now() - this.outboundSession!.creationTS;
+                if (keyAge < this.keyRotationGracePeriodMs) {
+                    this.logger?.debug(
+                        `New joiners detected, but the key is recent enough (age:${keyAge}), keeping it`,
+                    );
+                    toDistributeTo = anyJoined;
+                } else {
+                    this.logger?.debug(`New joiners detected, rotating the key`);
+                    // We need to rotate the key
+                    newOutboundEncryptionSession = this.createNewOutboundSession();
+                    hasKeyChanged = true;
+                    toDistributeTo = toShareWith;
+                }
             }
-        } else {
-            // no changes
+        }
+        // return early if we dont have anything to distribute.
+        if (toDistributeTo.length === 0) {
             return;
         }
 
         try {
             this.logger?.trace(`Sending key...`);
-            await this.transport.sendKey(encodeBase64(outboundKey.key), outboundKey.keyId, toDistributeTo);
-            outboundKey.sharedWith.push(...toDistributeTo);
-            this.logger?.trace(
-                `key index:${outboundKey.keyId} sent to ${outboundKey.sharedWith.map((m) => `${m.userId}:${m.deviceId}`).join(",")}`,
+            await this.transport.sendKey(
+                encodeBase64(newOutboundEncryptionSession.key),
+                newOutboundEncryptionSession.keyId,
+                toDistributeTo,
             );
+            newOutboundEncryptionSession.sharedWith.push(...toDistributeTo);
+            const outboundSessionList = newOutboundEncryptionSession.sharedWith
+                .map((m) => `${m.userId}:${m.deviceId}`)
+                .join(",");
+            this.logger?.trace(`key index:${newOutboundEncryptionSession.keyId} sent to ${outboundSessionList}`);
             if (hasKeyChanged) {
                 // Delay a bit before using this key
                 // It is recommended not to start using a key immediately but instead wait for a short time to make sure it is delivered.
-                this.logger?.trace(`Delay Rollout for key:${outboundKey.keyId}...`);
+                this.logger?.trace(`Delay Rollout for key:${newOutboundEncryptionSession.keyId}...`);
                 await sleep(this.useKeyDelay);
-                this.logger?.trace(`...Delayed rollout of index:${outboundKey.keyId} `);
+                this.logger?.trace(`...Delayed rollout of index:${newOutboundEncryptionSession.keyId} `);
                 this.addKeyToParticipantWithBackendIdentity(
-                    outboundKey.key,
-                    outboundKey.keyId,
+                    newOutboundEncryptionSession.key,
+                    newOutboundEncryptionSession.keyId,
                     this.ownMembership,
                     await this.getOwnRtcBackendIdentity(),
                 );

package/src/models/room-receipts.ts

@@ -158,13 +158,22 @@ export class RoomReceipts {
             }
         }
 
-        // TODO: what if they sent the second-last event in the thread?
-        if (this.userSentLatestEventInThread(threadId, userId)) {
-            // The user sent the latest message in this event's thread, so we
-            // consider everything in the thread to be read.
+        if (this.userSentEventAfterOrSame(threadId, userId, eventId)) {
+            // The user sent an event at or after this one, so they must have
+            // seen this one: we consider it read.
             //
-            // Note: maybe we don't need this because synthetic receipts should
-            // do this job for us?
+            // Note: the synthetic receipts we create when we see an event
+            // usually do this job for us, but not always - e.g. we don't create
+            // them for events we paginated in.
+            return true;
+        }
+
+        if (event.isThreadRoot && this.userRepliedInThread(eventId, userId)) {
+            // The user replied in the thread rooted at this event, and you
+            // can't reply to a thread without seeing its root. We have to check
+            // this separately because their reply is in the thread's timeline
+            // whereas the root is in the main one, so no receipt of theirs can
+            // cover the root.
             return true;
         }
 
@@ -173,17 +182,52 @@ export class RoomReceipts {
     }
 
     /**
-     * @returns true if the thread with this ID can be found, and the supplied
-     *          user sent the latest message in it.
+     * @returns true if the timeline for this thread ID can be found, and the
+     *          supplied user sent an event in it that is the same as, or after,
+     *          the event with the supplied ID.
      */
-    private userSentLatestEventInThread(threadId: string, userId: string): boolean {
+    private userSentEventAfterOrSame(threadId: string, userId: string, eventId: string): boolean {
         const timeline =
             threadId === MAIN_ROOM_TIMELINE
                 ? this.room.getLiveTimeline().getEvents()
                 : this.room.getThread(threadId)?.timeline;
 
-        return !!(timeline && timeline.length > 0 && timeline[timeline.length - 1].getSender() === userId);
+        const latestEventId = latestEventIdSentByUser(timeline, userId);
+        return !!latestEventId && isAfterOrSame(latestEventId, eventId, this.room);
     }
+
+    /**
+     * @returns true if the thread rooted at the event with the supplied ID can
+     *          be found, and the supplied user sent a reply in it.
+     */
+    private userRepliedInThread(rootEventId: string, userId: string): boolean {
+        // The root is part of the thread's timeline, but it is not a reply to
+        // the thread, so leave it out.
+        const replies = this.room.getThread(rootEventId)?.timeline.filter((event) => event.getId() !== rootEventId);
+        return !!latestEventIdSentByUser(replies, userId);
+    }
+}
+
+/**
+ * Find the last event in the supplied timeline that was sent by this user.
+ *
+ * Events that are still on their way to the server (or failed to get there) are
+ * ignored: they have no place in the timeline yet, and a failed send tells us
+ * nothing about what the user has seen.
+ *
+ * @returns the ID of the found event, or undefined if there is no such event.
+ */
+function latestEventIdSentByUser(timeline: Array<MatrixEvent> | undefined, userId: string): string | undefined {
+    if (!timeline) return undefined;
+
+    for (let index = timeline.length - 1; index >= 0; index--) {
+        const event = timeline[index];
+        if (event.getSender() === userId && !event.status) {
+            return event.getId();
+        }
+    }
+
+    return undefined;
 }
 
 // --- implementation details ---

package/src/oauth/authorize.ts

@@ -27,6 +27,8 @@ import {
 import { Method } from "../http-api/index.ts";
 import { OAuthGrantType } from "./register.ts";
 import { sleep } from "../utils.ts";
+import { type Logger, logger as rootLogger } from "../logger.ts";
+import { fetchWithLogging } from "./fetch.ts";
 
 /**
  * The expected response type from the token endpoint during authorization code flow
@@ -185,6 +187,7 @@ export function validateDeviceAuthorizationResponse(
  * @param options.clientId - the client ID returned from client registration.
  * @param options.scope - the scope to request for authorization.
  * @param options.metadata - the validated OAuth2 metadata for the Identity Provider.
+ * @param options.logger - optional logger to use for the request, defaults to the root logger of the js-sdk.
  * @returns a promise that resolves to a device access token response,
  *   or an error response if the user denies authorization or the device code expires.
  */
@@ -192,10 +195,12 @@ export const startDeviceAuthorization = async ({
     clientId,
     scope,
     metadata,
+    logger = rootLogger,
 }: {
     clientId: string;
     scope: string;
     metadata: ValidatedAuthMetadata;
+    logger?: Logger;
 }): Promise<DeviceAuthorizationResponse> => {
     const body = new URLSearchParams({ client_id: clientId, scope: scope }).toString();
 
@@ -204,7 +209,7 @@ export const startDeviceAuthorization = async ({
         throw new Error("No device_authorization_endpoint given");
     }
 
-    const response = await fetch(url, {
+    const response = await fetchWithLogging(logger, url, {
         method: Method.Post,
         headers: {
             "Content-Type": "application/x-www-form-urlencoded",
@@ -223,6 +228,7 @@ export const startDeviceAuthorization = async ({
  * @param options.session - The session returned from a previous call to {@link startDeviceAuthorization}.
  * @param options.metadata - The validated OAuth2 metadata for the Identity Provider.
  * @param options.clientId - The client ID returned from client registration.
+ * @param options.logger - optional logger to use for the requests, defaults to the root logger of the js-sdk.
  * @returns a promise that resolves to a device access token response,
  *   or an error response if the user denies authorization or the device code expires.
  */
@@ -230,10 +236,12 @@ export const waitForDeviceAuthorization = async ({
     session,
     metadata,
     clientId,
+    logger = rootLogger,
 }: {
     session: DeviceAuthorizationResponse;
     metadata: ValidatedAuthMetadata;
     clientId: string;
+    logger?: Logger;
 }): Promise<DeviceAccessTokenResponse | DeviceAccessTokenError> => {
     let interval = (session.interval ?? 5) * 1000; // poll interval
     const expiration = Date.now() + session.expires_in * 1000;
@@ -243,7 +251,7 @@ export const waitForDeviceAuthorization = async ({
             grant_type: OAuthGrantType.DeviceAuthorization,
             client_id: clientId,
         }).toString();
-        const response = await fetch(metadata.token_endpoint, {
+        const response = await fetchWithLogging(logger, metadata.token_endpoint, {
             method: Method.Post,
             headers: { "Content-Type": "application/x-www-form-urlencoded" },
             body,

package/src/oauth/fetch.ts

@@ -0,0 +1,54 @@
+/*
+Copyright 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.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import { sanitizeUrlForLogs } from "../http-api/logging.ts";
+import { Method } from "../http-api/method.ts";
+import { type Logger } from "../logger.ts";
+
+/**
+ * Perform a `fetch` request, logging the request and response in the same manner as
+ * `FetchHttpApi` does for Client-Server API requests.
+ *
+ * Neither the request nor the response body is logged, as they routinely contain credentials.
+ * Query parameter values are redacted for the same reason.
+ *
+ * @internal
+ * @param logger - the logger to write the request and response lines to.
+ * @param resource - the URL to request.
+ * @param options - the options to pass to `fetch`.
+ * @returns the `Response`, whatever its status code.
+ * @throws rethrows whatever `fetch` threw, having logged it.
+ */
+export async function fetchWithLogging(
+    logger: Logger,
+    resource: URL | string,
+    options: RequestInit = {},
+): Promise<Response> {
+    const method = options.method ?? Method.Get;
+    const urlForLogs = sanitizeUrlForLogs(resource);
+
+    logger.debug(`OAuth2: --> ${method} ${urlForLogs}`);
+
+    const start = Date.now();
+    try {
+        const res = await globalThis.fetch(resource, options);
+        logger.debug(`OAuth2: <-- ${method} ${urlForLogs} [${Date.now() - start}ms ${res.status}]`);
+        return res;
+    } catch (e) {
+        logger.debug(`OAuth2: <-- ${method} ${urlForLogs} [${Date.now() - start}ms ${e}]`);
+        throw e;
+    }
+}

package/src/oauth/index.ts

@@ -35,7 +35,8 @@ import {
 import { encodeUnpaddedBase64Url } from "../base64.ts";
 import { sha256 } from "../digest.ts";
 import { HTTPError, isMatrixErrorResponse, MatrixError, Method } from "../http-api/index.ts";
-import { logger } from "../logger.ts";
+import { type Logger, logger as rootLogger } from "../logger.ts";
+import { fetchWithLogging } from "./fetch.ts";
 import { isOAuth2ErrorResponse, OAuth2Error, OAuth2HTTPError } from "./error.ts";
 import { secureRandomString } from "../randomstring.ts";
 import { type NonEmptyArray } from "../@types/common.ts";
@@ -67,12 +68,14 @@ export class OAuth2 {
      * @param authMetadata - Auth config from {@link MatrixClient.getAuthMetadata}
      * @param clientMetadata - The metadata for the client which to register,
      *     grant_types & response_types & token_endpoint_auth_method will be sanely calculated if omitted.
+     * @param logger - Optional logger to use for the request, defaults to the root logger of the js-sdk.
      * @returns Promise<string> resolved with registered clientId
      * @throws when registration is not supported, on failed request or invalid response
      */
     public static async registerClient(
         authMetadata: ValidatedAuthMetadata,
         clientMetadata: OAuthRegistrationRequest,
+        logger: Logger = rootLogger,
     ): Promise<string> {
         const defaultGrantTypes: NonEmptyArray<string> = [
             OAuthGrantType.AuthorizationCode,
@@ -102,7 +105,7 @@ export class OAuth2 {
         };
 
         try {
-            const response = await fetch(authMetadata.registration_endpoint, {
+            const response = await fetchWithLogging(logger, authMetadata.registration_endpoint, {
                 method: Method.Post,
                 headers: {
                     "Accept": "application/json",
@@ -133,9 +136,16 @@ export class OAuth2 {
 
     public readonly context: Required<Context>;
 
+    /**
+     * @param metadata - The validated OAuth 2.0 metadata for the Identity Provider.
+     * @param context - The persistent context needed for the OAuth flows.
+     * @param logger - Optional logger to use for the requests made by this instance,
+     *     defaults to the root logger of the js-sdk.
+     */
     public constructor(
         public readonly metadata: ValidatedAuthMetadata,
         context: Context,
+        private readonly logger: Logger = rootLogger,
     ) {
         this.context = {
             clientId: context.clientId,
@@ -200,7 +210,8 @@ export class OAuth2 {
         params.append("redirect_uri", this.context.redirectUri);
         params.append("code", code);
 
-        const tokenResponse = await this.fetch("token", params, OAuth2Error.CodeExchangeFailed);
+        const res = await this.fetch("token", params, OAuth2Error.CodeExchangeFailed);
+        const tokenResponse = await res.json();
 
         // throws when response is invalid
         validateBearerTokenResponse(tokenResponse);
@@ -217,7 +228,8 @@ export class OAuth2 {
         params.append("client_id", this.context.clientId);
         params.append("refresh_token", refreshToken);
 
-        const tokenResponse = await this.fetch("token", params, OAuth2Error.RefreshTokenFailed);
+        const res = await this.fetch("token", params, OAuth2Error.RefreshTokenFailed);
+        const tokenResponse = await res.json();
 
         // throws when response is invalid
         validateBearerTokenResponse(tokenResponse);
@@ -237,10 +249,11 @@ export class OAuth2 {
             params.append("token_type_hint", type);
         }
 
+        // [RFC 7009 section 2.2](https://www.rfc-editor.org/rfc/rfc7009.html#section-2.2) says:
+        // > The content of the response body is ignored by the client as all
+        // > necessary information is conveyed in the response code.
+        // so, we don't do anything with the response body.
         await this.fetch("revocation", params, OAuth2Error.RevokeTokenFailed);
-
-        const headers = new Headers();
-        headers.set("Content-Type", "application/x-www-form-urlencoded");
     }
 
     /**
@@ -254,6 +267,7 @@ export class OAuth2 {
             scope: scope ?? generateScope(this.context.deviceId),
             metadata: this.metadata,
             clientId: this.context.clientId,
+            logger: this.logger,
         });
     }
 
@@ -270,16 +284,21 @@ export class OAuth2 {
             session,
             metadata: this.metadata,
             clientId: this.context.clientId,
+            logger: this.logger,
         });
     }
 
+    /**
+     * Make a request to one of the OAuth 2.0 endpoints, throwing if it responds with an error.
+     * @returns the {@link Response}, for the caller to parse if the endpoint returns a body.
+     */
     private async fetch(
         target: "token" | "registration" | "revocation",
         params: URLSearchParams,
         error: OAuth2Error,
-    ): Promise<unknown> {
+    ): Promise<Response> {
         const url = this.metadata[`${target}_endpoint`];
-        const res = await fetch(url, {
+        const res = await fetchWithLogging(this.logger, url, {
             method: Method.Post,
             headers: {
                 "Content-Type": "application/x-www-form-urlencoded",
@@ -309,6 +328,6 @@ export class OAuth2 {
             throw new HTTPError(error, res.status, res.headers);
         }
 
-        return await res.json();
+        return res;
     }
 }