matrix-js-sdk 42.4.0 → 43.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "matrix-js-sdk",
-  "version": "42.4.0",
+  "version": "43.0.0",
   "description": "Matrix Client-Server SDK for Javascript",
   "engines": {
     "node": ">=22.0.0"
@@ -8,7 +8,7 @@
   "devEngines": {
     "packageManager": {
       "name": "pnpm",
-      "version": "11.9.0",
+      "version": "12.3.4",
       "onFail": "download"
     }
   },
@@ -68,8 +68,8 @@
     "@types/node": "22",
     "@types/sdp-transform": "^3.0.0",
     "@typescript/native": "npm:typescript@7.0.2",
-    "@vitest/coverage-v8": "^4.0.17",
-    "@vitest/ui": "^4.0.17",
+    "@vitest/coverage-v8": "^5.0.0",
+    "@vitest/ui": "^5.0.0",
     "concurrently": "^10.0.0",
     "debug": "^4.3.4",
     "fake-indexeddb": "^6.0.0",
@@ -79,7 +79,7 @@
     "knip": "^6.0.0",
     "lint-staged": "^17.0.0",
     "matrix-mock-request": "^2.5.0",
-    "oxfmt": "^0.65.0",
+    "oxfmt": "^0.67.0",
     "oxlint": "^1.70.0",
     "oxlint-tsgolint": "^7.0.0",
     "typedoc": "^0.28.1",
@@ -87,7 +87,7 @@
     "typedoc-plugin-mdn-links": "^5.0.0",
     "typedoc-plugin-missing-exports": "^4.0.0",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "vitest": "^4.0.17"
+    "vitest": "^5.0.0"
   },
   "scripts": {
     "start": "concurrently 'pnpm run build:compile --watch' 'pnpm run build:types --watch'",

package/src/@types/PushRules.ts

@@ -155,6 +155,8 @@ export enum RuleId {
     PollStartOneToOneUnstable = ".org.matrix.msc3930.rule.poll_start_one_to_one",
     PollEndOneToOne = ".m.rule.poll_end_one_to_one",
     PollEndOneToOneUnstable = ".org.matrix.msc3930.rule.poll_end_one_to_one",
+    RtcInviteForMe = ".org.matrix.msc4075.rule.rtc.invite_for_me",
+    RtcInviteForRoom = ".org.matrix.msc4075.rule.rtc.invite_for_room",
 }
 
 export type PushRuleSet = {

package/src/@types/event.ts

@@ -361,7 +361,7 @@ export interface TimelineEvents {
     [M_BEACON.name]: MBeaconEventContent;
     [M_POLL_START.name]: PollStartEventContent;
     [M_POLL_END.name]: PollEndEventContent;
-    [EventType.RTCMembership]: RtcMembershipData | { msc4354_sticky_key: string }; // An object containing just the sticky key is empty.
+    [EventType.RTCMembership]: RtcMembershipData | { slot_id: string; msc4354_sticky_key: string };
 }
 
 /**

package/src/@types/matrix-sdk-crypto-wasm.d.ts

@@ -16,20 +16,23 @@ limitations under the License.
 
 import type * as RustSdkCryptoJs from "@matrix-org/matrix-sdk-crypto-wasm";
 
+/** Return type of `SecretsBundle.to_json` */
+type SecretsBundleJson = {
+    cross_signing: {
+        master_key: string;
+        self_signing_key: string;
+        user_signing_key: string;
+    };
+    backup?: {
+        algorithm: string;
+        key: string;
+        backup_version: string;
+    };
+};
+
 declare module "@matrix-org/matrix-sdk-crypto-wasm" {
     interface SecretsBundle {
-        to_json(): Promise<{
-            cross_signing: {
-                master_key: string;
-                self_signing_key: string;
-                user_signing_key: string;
-            };
-            backup?: {
-                algorithm: string;
-                key: string;
-                backup_version: string;
-            };
-        }>;
+        to_json(): Promise<SecretsBundleJson>;
     }
 
     interface Device {

package/src/client.ts

@@ -73,7 +73,7 @@ import {
     MediaPrefix,
     Method,
     retryNetworkOperation,
-    type TokenRefreshFunction,
+    type TokenRefreshCallback,
     type Upload,
     type UploadOpts,
     type UploadResponse,
@@ -251,7 +251,9 @@ import {
     type LivekitGetTokenResponse,
     type Transport,
 } from "./matrixrtc/index.ts";
+import { type IRTCDeclineContent, RTC_NOTIFICATION_MAX_LIFETIME_MS } from "./matrixrtc/types.ts";
 import { RetentionPolicyService } from "./retentionPolicy.ts";
+import { fetchRoomSummary, type RoomSummary } from "./room-summary-api.ts";
 import { createRtcTransportsCachedValue } from "./rtcTransportsCachedValue.ts";
 import { createWellKnownCachedValue } from "./wellKnownCachedValue.ts";
 import { type PollingCachedValue } from "./pollingCachedValue.ts";
@@ -319,15 +321,32 @@ export interface ICreateClientOpts {
      */
     deviceId?: string;
 
+    /**
+     * The access token to use. Can be omitted if to call only unauthenticated APIs, or provided to
+     * create an authenticated client.
+     */
     accessToken?: string;
+
+    /**
+     * The current refresh token, or omit if the session has no refresh token in which case the tokens
+     * will not be refreshed.
+     */
     refreshToken?: string;
 
     /**
-     * Function used to attempt refreshing access and refresh tokens
-     * Called by http-api when a possibly expired token is encountered
-     * and a refreshToken is found
+     * Called when the access tokens are refreshed.
+     * The client must replace the tokens it had stored previously which will no
+     * longer be valid.
+     *
+     * Required if a {@link refreshToken} is provided.
      */
-    tokenRefreshFunction?: TokenRefreshFunction;
+    onTokenRefresh?: TokenRefreshCallback;
+
+    /**
+     * If this is an OAuth2-native session (as per MSC2965/MSC3861), the OAuth client ID this
+     * application is registered with the delegated auth server under.
+     */
+    oauthClientId?: string;
 
     /**
      * Identity server provider to retrieve the user's access token when accessing
@@ -865,25 +884,8 @@ interface IThirdPartyUser {
     fields: object;
 }
 
-/**
- * The summary of a room as defined by an initial version of MSC3266 and implemented in Synapse
- * Proposed at https://github.com/matrix-org/matrix-doc/pull/3266
- */
-export interface RoomSummary extends Omit<IPublicRoomsChunkRoom, "canonical_alias" | "aliases"> {
-    /**
-     * The current membership of this user in the room.
-     * Usually "leave" if the room is fetched over federation.
-     */
-    "membership"?: Membership;
-    /**
-     * Version of the room.
-     */
-    "im.nheko.summary.room_version"?: string;
-    /**
-     * The encryption algorithm used for this room, if the room is encrypted.
-     */
-    "im.nheko.summary.encryption"?: string;
-}
+// Re-export for backwards compatibility
+export { type RoomSummary };
 
 interface IRoomHierarchy {
     rooms: IHierarchyRoom[];
@@ -1358,7 +1360,14 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
             idBaseUrl: opts.idBaseUrl,
             accessToken: opts.accessToken,
             refreshToken: opts.refreshToken,
-            tokenRefreshFunction: opts.tokenRefreshFunction,
+            onTokenRefresh: opts.onTokenRefresh,
+            oauth2ClientConfig: opts.oauthClientId
+                ? {
+                      clientId: opts.oauthClientId,
+                      deviceId: this.deviceId ?? undefined,
+                  }
+                : undefined,
+            authMetadataCallback: this.getAuthMetadata.bind(this),
             prefix: ClientPrefix.V3,
             onlyData: true,
             extraParams: opts.queryParams,
@@ -2769,7 +2778,7 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
      * If we expect that an event is part of a thread but is missing the relation
      * we need to add it manually, as well as the reply fallback
      */
-    private addThreadRelationIfNeeded(content: IContent, threadId: string | null, roomId: string): void {
+    protected addThreadRelationIfNeeded(content: IContent, threadId: string | null, roomId: string): void {
         if (threadId && !content["m.relates_to"]?.rel_type) {
             const isReply = !!content["m.relates_to"]?.["m.in_reply_to"];
             content["m.relates_to"] = {
@@ -2794,12 +2803,18 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
     }
 
     /**
-     * @param eventObject - An object with the partial structure of an event, to which event_id, user_id, room_id and origin_server_ts will be added.
-     * @param txnId - Optional.
-     * @returns Promise which resolves: to an empty object `{}`
+     * Sends an event, adding it to the local echo and encrypting it if the room requires it.
+     *
+     * @param params - What to send and where.
+     * @param params.roomId - The room to send the event to.
+     * @param params.threadId - The thread to send the event in, or `null` for the main timeline.
+     * @param params.eventObject - An object with the partial structure of an event, to which event_id, user_id, room_id and origin_server_ts will be added.
+     * @param params.queryDict - Optional query parameters for the send request.
+     * @param params.txnId - Optional transaction ID. Generated if omitted.
+     * @returns Promise which resolves: to an object with the ID of the sent event.
      * @returns Rejects: with an error response.
      */
-    private sendCompleteEvent(params: {
+    protected sendCompleteEvent(params: {
         roomId: string;
         threadId: string | null;
         eventObject: Partial<IEvent>;
@@ -2808,13 +2823,18 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
     }): Promise<ISendEventResponse>;
     /**
      * Sends a delayed event (MSC4140).
-     * @param eventObject - An object with the partial structure of an event, to which event_id, user_id, room_id and origin_server_ts will be added.
-     * @param delayOpts - Properties of the delay for this event.
-     * @param txnId - Optional.
-     * @returns Promise which resolves: to an empty object `{}`
+     *
+     * @param params - What to send and where.
+     * @param params.roomId - The room to send the event to.
+     * @param params.threadId - The thread to send the event in, or `null` for the main timeline.
+     * @param params.eventObject - An object with the partial structure of an event, to which event_id, user_id, room_id and origin_server_ts will be added.
+     * @param params.delayOpts - Properties of the delay for this event.
+     * @param params.queryDict - Optional query parameters for the send request.
+     * @param params.txnId - Optional transaction ID. Generated if omitted.
+     * @returns Promise which resolves: to an object with the ID of the scheduled delayed event.
      * @returns Rejects: with an error response.
      */
-    private sendCompleteEvent(params: {
+    protected sendCompleteEvent(params: {
         roomId: string;
         threadId: string | null;
         eventObject: Partial<IEvent>;
@@ -2822,7 +2842,7 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
         queryDict?: QueryDict;
         txnId?: string;
     }): Promise<SendDelayedEventResponse>;
-    private sendCompleteEvent({
+    protected sendCompleteEvent({
         roomId,
         threadId,
         eventObject,
@@ -3952,17 +3972,38 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
     }
 
     /**
+     * Declines a MatrixRTC notification.
      *
-     * @param roomId
-     * @param notificationEventId
-     * @returns
+     * The decline is sent as a sticky event (MSC4354) keyed on the notification's event ID, so that the
+     * user's other devices stop notifying. If the server doesn't support sticky events, a regular event is
+     * sent instead. That one still counts as a decline for any device that receives it, but it isn't
+     * re-delivered after a gappy or initial sync the way a sticky event is, so a device that was offline
+     * when it was sent keeps notifying until the notification's lifetime elapses.
+     *
+     * @param roomId The room the notification was received in.
+     * @param notificationEventId The event ID of the notification being declined.
+     * @param stickyDurationMs How long (in milliseconds) the decline should stay sticky. Must not be smaller
+     * than the notification's `lifetime`, otherwise the notification can become valid again once the decline
+     * expires. Defaults to the maximum lifetime a notification may have.
      * @throws May throw a `MatrixSafetyError` if content is deemed unsafe.
      * @see MatrixSafetyError
      */
-    public sendRtcDecline(roomId: string, notificationEventId: string): Promise<ISendEventResponse> {
-        return this.sendEvent(roomId, EventType.RTCDecline, {
+    public async sendRtcDecline(
+        roomId: string,
+        notificationEventId: string,
+        stickyDurationMs: number = RTC_NOTIFICATION_MAX_LIFETIME_MS,
+    ): Promise<ISendEventResponse> {
+        const content: IRTCDeclineContent = {
             "m.relates_to": { event_id: notificationEventId, rel_type: RelationType.Reference },
-        });
+            "msc4354_sticky_key": notificationEventId,
+        };
+        try {
+            return await this._unstable_sendStickyEvent(roomId, stickyDurationMs, null, EventType.RTCDecline, content);
+        } catch (error) {
+            if (!(error instanceof UnsupportedStickyEventsEndpointError)) throw error;
+            this.logger.debug("Server does not support sticky events, sending decline as a regular event");
+            return await this.sendEvent(roomId, EventType.RTCDecline, content);
+        }
     }
 
     /**
@@ -6299,6 +6340,7 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
     /**
      * Get the API versions supported by the server, along with any
      * unstable APIs it supports
+     *
      * @returns The server /versions response
      */
     public async getVersions(): Promise<IServerVersions> {
@@ -6847,7 +6889,12 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
      * method is called. The state of the MatrixClient object is not affected:
      * it is up to the caller to either reset or destroy the MatrixClient after
      * this method succeeds.
-     * @param stopClient - whether to stop the client before calling /logout to prevent invalid token errors.
+     *
+     * For an OAuth2-native session (ie. one created with `oauth2ClientConfig`), this revokes the access
+     * and refresh tokens directly with the delegated auth server instead of calling the `/logout` API,
+     * since the homeserver does not own the tokens in that case.
+     *
+     * @param stopClient - whether to stop the client before logging out to prevent invalid token errors.
      * @returns Promise which resolves: On success, the empty object `{}`
      */
     public async logout(stopClient = false): Promise<EmptyObject> {
@@ -6856,6 +6903,11 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
             this.http.abort();
         }
 
+        if (this.http.opts.oauth2ClientConfig) {
+            await this.http.revokeOAuthTokens();
+            return {};
+        }
+
         return this.http.authedRequest(Method.Post, "/logout");
     }
 
@@ -8856,26 +8908,18 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
     }
 
     /**
-     * Fetches the summary of a room as defined by an initial version of MSC3266 and implemented in Synapse
-     * Proposed at https://github.com/matrix-org/matrix-doc/pull/3266
+     * Fetches the summary of a room.
+     * https://spec.matrix.org/latest/client-server-api/#get_matrixclientv1room_summaryroomidoralias
+     *
+     * Uses the initial version of MSC3266, as implemented in older versions of Synapse, unless the
+     * server advertises support for the spec version which stabilised it.
+     *
      * @param roomIdOrAlias - The ID or alias of the room to get the summary of.
-     * @param via - The list of servers which know about the room if only an ID was provided.
+     * @param via - The servers to attempt to request the summary from, when the local server cannot
+     *              generate it (for instance, because it has no local user in the room).
      */
     public async getRoomSummary(roomIdOrAlias: string, via?: string[]): Promise<RoomSummary> {
-        const paramOpts = {
-            prefix: "/_matrix/client/unstable/im.nheko.summary",
-        };
-        try {
-            const path = utils.encodeUri("/summary/$roomid", { $roomid: roomIdOrAlias });
-            return await this.http.authedRequest(Method.Get, path, { via }, undefined, paramOpts);
-        } catch (e) {
-            if (e instanceof MatrixError && e.errcode === "M_UNRECOGNIZED") {
-                const path = utils.encodeUri("/rooms/$roomid/summary", { $roomid: roomIdOrAlias });
-                return await this.http.authedRequest(Method.Get, path, { via }, undefined, paramOpts);
-            } else {
-                throw e;
-            }
-        }
+        return fetchRoomSummary(this.http, await this.getVersions(), roomIdOrAlias, via);
     }
 
     /**
@@ -8982,9 +9026,8 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
      * @throws when delegated auth config is invalid or unreachable
      */
     public async getAuthMetadata(): Promise<ValidatedAuthMetadata> {
-        const useStable = await this.isVersionSupported("v1.15");
         const authMetadata = await this.http.request(Method.Get, "/auth_metadata", undefined, undefined, {
-            prefix: useStable ? ClientPrefix.V1 : ClientPrefix.Unstable + "/org.matrix.msc2965",
+            prefix: ClientPrefix.V1,
         });
 
         if (isValidAuthMetadata(authMetadata)) {

package/src/crypto-api/index.ts

@@ -14,7 +14,6 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-import type { SecretsBundle } from "@matrix-org/matrix-sdk-crypto-wasm";
 import type { IMegolmSessionData } from "../@types/crypto.ts";
 import type { ToDeviceBatch, ToDevicePayload } from "../models/ToDeviceMessage.ts";
 import { type Room } from "../models/room.ts";
@@ -31,6 +30,7 @@ import {
 } from "./keybackup.ts";
 import { type ISignatures } from "../@types/signed.ts";
 import { type MatrixEvent } from "../models/event.ts";
+import type { SecretsBundleJson } from "../@types/matrix-sdk-crypto-wasm.d.ts";
 
 /**
  * `matrix-js-sdk/lib/crypto-api`: End-to-end encryption support.
@@ -723,13 +723,13 @@ export interface CryptoApi {
     /**
      * Export secrets bundle for transmitting to another device as part of OAuth2 QR login
      */
-    exportSecretsBundle?(): Promise<Awaited<ReturnType<SecretsBundle["to_json"]>>>;
+    exportSecretsBundle?(): Promise<SecretsBundleJson>;
 
     /**
      * Import secrets bundle transmitted from another device.
      * @param secrets - The secrets bundle received from the other device
      */
-    importSecretsBundle?(secrets: Awaited<ReturnType<SecretsBundle["to_json"]>>): Promise<void>;
+    importSecretsBundle?(secrets: SecretsBundleJson): Promise<void>;
 }
 
 /** A reason code for a failure to decrypt an event. */

package/src/embedded.ts

@@ -46,7 +46,7 @@ import {
     UpdateDelayedEventAction,
     isSendDelayedEventRequestOpts,
 } from "./@types/requests.ts";
-import { EventType, type StateEvents } from "./@types/event.ts";
+import { EventType, type StateEvents, type TimelineEvents } from "./@types/event.ts";
 import { logger } from "./logger.ts";
 import {
     MatrixClient,
@@ -64,7 +64,12 @@ import { User } from "./models/user.ts";
 import { type Room } from "./models/room.ts";
 import { type ToDeviceBatch, type ToDevicePayload } from "./models/ToDeviceMessage.ts";
 import { MapWithDefault, type QueryDict, recursiveMapToObject } from "./utils.ts";
-import { type EmptyObject, TypedEventEmitter, UnsupportedDelayedEventsEndpointError } from "./matrix.ts";
+import {
+    type EmptyObject,
+    TypedEventEmitter,
+    UnsupportedDelayedEventsEndpointError,
+    UnsupportedStickyEventsEndpointError,
+} from "./matrix.ts";
 
 interface IStateEventRequest {
     eventType: string;
@@ -539,6 +544,60 @@ export class RoomWidgetClient extends MatrixClient {
         return this.validateSendDelayedEventResponse(response);
     }
 
+    /**
+     * Sends a sticky timeline event through the widget API.
+     *
+     * A widget can't probe the homeserver for MSC4354 support and doesn't need to: the host either granted it
+     * the capability to send sticky events or it didn't. A missing capability is reported the same way a
+     * missing server feature is, so that callers fall back to a regular event in both cases alike.
+     *
+     * The host may still refuse the request, typically because its own homeserver turns out not to support
+     * sticky events. Such a refusal reaches the widget without Matrix API error details, as those only accompany
+     * errors from requests the host actually made to the homeserver. It is therefore reported as unsupported too,
+     * with the host's error as `cause`. A refusal that does carry Matrix API error details came from the
+     * homeserver itself and is rethrown as is.
+     */
+    public async _unstable_sendStickyEvent<K extends keyof TimelineEvents>(
+        roomId: string,
+        stickDuration: number,
+        threadId: string | null,
+        eventType: K,
+        content: TimelineEvents[K] & { msc4354_sticky_key?: string },
+        txnId?: string,
+    ): Promise<ISendEventResponse> {
+        if (!this.widgetApi.hasCapability(MatrixCapabilities.MSC4407SendStickyEvent)) {
+            throw new UnsupportedStickyEventsEndpointError(
+                "Widget was not granted the capability to send sticky events",
+                "sendStickyEvent",
+            );
+        }
+
+        this.addThreadRelationIfNeeded(content, threadId, roomId);
+        txnId ??= this.makeTxnId();
+        try {
+            return await this.sendCompleteEvent({
+                roomId,
+                threadId,
+                eventObject: { type: eventType, content },
+                queryDict: { "org.matrix.msc4354.sticky_duration_ms": stickDuration },
+                txnId,
+            });
+        } catch (error) {
+            if (!(error instanceof WidgetApiResponseError) || error.data.matrix_api_error !== undefined) throw error;
+
+            // Callers fall back to sending a regular event, so drop the local echo of the failed sticky one
+            // rather than leaving it in the timeline as unsent.
+            const localEvent = this.getRoom(roomId)?.getEventForTxnId(txnId);
+            if (localEvent?.status === EventStatus.NOT_SENT) this.cancelPendingEvent(localEvent);
+
+            throw new UnsupportedStickyEventsEndpointError(
+                `Host could not send the sticky event: ${error.message}`,
+                "sendStickyEvent",
+                { cause: error },
+            );
+        }
+    }
+
     private validateSendDelayedEventResponse(response: ISendEventFromWidgetResponseData): SendDelayedEventResponse {
         if (response.delay_id === undefined) {
             throw new Error("'delay_id' absent from response to a delayed event request");

package/src/errors.ts

@@ -80,8 +80,9 @@ export class UnsupportedStickyEventsEndpointError extends Error {
     public constructor(
         message: string,
         public clientEndpoint: "sendStickyEvent" | "sendStickyStateEvent",
+        options?: ErrorOptions,
     ) {
-        super(message);
+        super(message, options);
         this.name = "UnsupportedStickyEventsEndpointError";
     }
 }

package/src/http-api/fetch.ts

@@ -33,11 +33,11 @@ import {
 import { anySignal, parseErrorResponse, timeoutSignal } from "./utils.ts";
 import { sanitizeUrlForLogs } from "./logging.ts";
 import { type QueryDict } from "../utils.ts";
-import { TokenRefresher, TokenRefreshOutcome } from "./refresh.ts";
+import { TokenManager, TokenRefreshOutcome } from "./refresh.ts";
 
 export class FetchHttpApi<O extends IHttpOpts> {
     private abortController = new AbortController();
-    private readonly tokenRefresher: TokenRefresher;
+    private readonly tokenManager: TokenManager;
 
     public constructor(
         private eventEmitter: TypedEventEmitter<HttpApiEvent, HttpApiEventHandlerMap>,
@@ -49,7 +49,7 @@ export class FetchHttpApi<O extends IHttpOpts> {
         }
         opts.useAuthorizationHeader = opts.useAuthorizationHeader ?? true;
 
-        this.tokenRefresher = new TokenRefresher(opts);
+        this.tokenManager = new TokenManager(opts);
     }
 
     public abort(): void {
@@ -57,6 +57,15 @@ export class FetchHttpApi<O extends IHttpOpts> {
         this.abortController = new AbortController();
     }
 
+    /**
+     * Attempt to revoke the current access and refresh tokens with the OAuth2 authorization server, e.g. as
+     * part of logging out an OAuth2-native session. Does nothing if `opts.oauth2ClientConfig` was not supplied.
+     * @throws when discovery of the auth server metadata, or revocation of either token, fails
+     */
+    public async revokeOAuthTokens(): Promise<void> {
+        return this.tokenManager.revokeTokens();
+    }
+
     public fetch(resource: URL | string, options?: RequestInit): ReturnType<typeof globalThis.fetch> {
         if (this.opts.fetchFn) {
             return this.opts.fetchFn(resource, options);
@@ -147,7 +156,7 @@ export class FetchHttpApi<O extends IHttpOpts> {
         opts.abortSignal = paramOpts.abortSignal;
 
         // Take a snapshot of the current token state before we start the request so we can reference it if we error
-        const requestSnapshot = await this.tokenRefresher.prepareForRequest();
+        const requestSnapshot = await this.tokenManager.prepareForRequest();
         if (requestSnapshot.accessToken) {
             if (this.opts.useAuthorizationHeader) {
                 if (!opts.headers) {
@@ -173,7 +182,7 @@ export class FetchHttpApi<O extends IHttpOpts> {
             }
 
             if (error.errcode === "M_UNKNOWN_TOKEN") {
-                const outcome = await this.tokenRefresher.handleUnknownToken(requestSnapshot, attempt);
+                const outcome = await this.tokenManager.handleUnknownToken(requestSnapshot, attempt);
                 if (outcome === TokenRefreshOutcome.Success) {
                     // if we got a new token retry the request
                     return this.doAuthedRequest(attempt + 1, method, path, queryParams, body, paramOpts);

package/src/http-api/interface.ts

@@ -17,6 +17,7 @@ limitations under the License.
 import { type MatrixError } from "./errors.ts";
 import { type Logger } from "../logger.ts";
 import { type QueryDict } from "../utils.ts";
+import { type ValidatedAuthMetadata } from "../oauth/discover.ts";
 
 export type Body = Record<string, any> | BodyInit;
 
@@ -39,12 +40,25 @@ export type AccessTokens = {
 };
 
 /**
- * Function that performs token refresh using the given refreshToken.
- * Returns a promise that resolves to the refreshed access and (optional) refresh tokens.
+ * A callback function called when tokens are refreshed such that stored tokens can be updated with
+ * the refreshed ones.
+ */
+export type TokenRefreshCallback = (newTokens: AccessTokens) => void;
+
+/**
+ * Configuration required for {@link IHttpOpts} to allow the SDK to manage the full lifecycle of tokens for an
+ * OAuth2-native session (as per MSC2965/MSC3861): discovering the delegated auth server's metadata, refreshing
+ * access/refresh tokens, and revoking them (e.g. on logout).
  *
- * Can be passed to HttpApi instance as {@link IHttpOpts.tokenRefreshFunction} during client creation {@link ICreateClientOpts}
+ * The SDK constructs the underlying OAuth2 client itself, lazily, the first time it is actually needed (so that,
+ * for example, a client started with no network connection does not fail to ever set up token refresh).
  */
-export type TokenRefreshFunction = (refreshToken: string) => Promise<AccessTokens>;
+export interface OAuth2ClientConfig {
+    /** The OAuth2 client ID this application is registered with the delegated auth server under. */
+    clientId: string;
+    /** The device ID of the current session, used to scope refreshed/revoked tokens to this session. */
+    deviceId?: string;
+}
 
 /** Options object for `FetchHttpApi` and {@link MatrixHttpApi}. */
 export interface IHttpOpts {
@@ -57,14 +71,28 @@ export interface IHttpOpts {
 
     accessToken?: string;
     /**
-     * Used in conjunction with tokenRefreshFunction to attempt token refresh
+     * Used in conjunction with oauth2ClientConfig to attempt token refresh
      */
     refreshToken?: string;
     /**
-     * Function to attempt token refresh when a possibly expired token is encountered
-     * Optional, only called when a refreshToken is present
+     * Callback called when tokens are refreshed. Must be supplied if refreshToken is supplied.
+     */
+    onTokenRefresh?: TokenRefreshCallback;
+    /**
+     * Configuration needed to refresh (given refreshToken) and revoke (e.g. on logout) tokens for an
+     * OAuth2-native session. Optional; if omitted, tokens will not be refreshed or revoked by the SDK.
+     * authMetadataCallback must also be supplied to refresh tokens.
+     */
+    oauth2ClientConfig?: OAuth2ClientConfig;
+
+    /**
+     * Discovers and validates the delegated auth server's metadata for the current homeserver.
+     * Must be supplied along with oauth2ClientConfig in order to refresh tokens.
+     *
+     * @returns validated authentication metadata
+     * @throws when delegated auth config is invalid or unreachable
      */
-    tokenRefreshFunction?: TokenRefreshFunction;
+    authMetadataCallback?: () => Promise<ValidatedAuthMetadata>;
 
     /**
      * Whether to use the HTTP Authorization header over the `access_token` query parameter