Implementation of MSC3882 login token request (#2687)

spec/integ/matrix-client-methods.spec.js

@@ -1075,6 +1075,29 @@ describe("MatrixClient", function() {
             expect(await prom).toStrictEqual(response);
         });
     });
+
+    describe("requestLoginToken", () => {
+        it("should hit the expected API endpoint with UIA", async () => {
+            const response = {};
+            const uiaData = { foo: "baa" };
+            const prom = client.requestLoginToken(uiaData);
+            httpBackend
+                .when("POST", "/unstable/org.matrix.msc3882/login/token", { auth: uiaData })
+                .respond(200, response);
+            await httpBackend.flush();
+            expect(await prom).toStrictEqual(response);
+        });
+
+        it("should hit the expected API endpoint without UIA", async () => {
+            const response = {};
+            const prom = client.requestLoginToken();
+            httpBackend
+                .when("POST", "/unstable/org.matrix.msc3882/login/token", {})
+                .respond(200, response);
+            await httpBackend.flush();
+            expect(await prom).toStrictEqual(response);
+        });
+    });
 });
 
 function withThreadId(event, newThreadId) {

src/@types/auth.ts

@@ -90,3 +90,19 @@ export enum SSOAction {
     /** The user intends to register for a new account */
     REGISTER = "register",
 }
+
+/**
+ * The result of a successful [MSC3882](https://github.com/matrix-org/matrix-spec-proposals/pull/3882)
+ * `m.login.token` issuance request.
+ * Note that this is UNSTABLE and subject to breaking changes without notice.
+ */
+export interface LoginTokenPostResponse {
+    /**
+     * The token to use with `m.login.token` to authenticate.
+     */
+    login_token: string;
+    /**
+     * Expiration in seconds.
+     */
+    expires_in: number;
+}

src/@types/uia.ts

@@ -0,0 +1,29 @@
+/*
+Copyright 2022 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 { IAuthData } from "..";
+
+/**
+ * Helper type to represent HTTP request body for a UIA enabled endpoint
+ */
+export type UIARequest<T> = T & {
+  auth?: IAuthData;
+};
+
+/**
+ * Helper type to represent HTTP response body for a UIA enabled endpoint
+ */
+export type UIAResponse<T> = T | IAuthData;

src/client.ts

@@ -189,7 +189,7 @@ import { IPusher, IPusherRequest, IPushRules, PushRuleAction, PushRuleKind, Rule
 import { IThreepid } from "./@types/threepids";
 import { CryptoStore } from "./crypto/store/base";
 import { MediaHandler } from "./webrtc/mediaHandler";
-import { ILoginFlowsResponse, IRefreshTokenResponse, SSOAction } from "./@types/auth";
+import { LoginTokenPostResponse, ILoginFlowsResponse, IRefreshTokenResponse, SSOAction } from "./@types/auth";
 import { TypedEventEmitter } from "./models/typed-event-emitter";
 import { ReceiptType } from "./@types/read_receipts";
 import { MSC3575SlidingSyncRequest, MSC3575SlidingSyncResponse, SlidingSync } from "./sliding-sync";
@@ -201,6 +201,7 @@ import { ToDeviceMessageQueue } from "./ToDeviceMessageQueue";
 import { ToDeviceBatch } from "./models/ToDeviceMessage";
 import { MAIN_ROOM_TIMELINE } from "./models/read-receipt";
 import { IgnoredInvites } from "./models/invites-ignorer";
+import { UIARequest, UIAResponse } from "./@types/uia";
 
 export type Store = IStore;
 
@@ -7291,6 +7292,27 @@ export class MatrixClient extends TypedEventEmitter<EmittedEvents, ClientEventHa
         return this.http.authedRequest(undefined, Method.Post, '/account/deactivate', undefined, body);
     }
 
+    /**
+     * Make a request for an `m.login.token` to be issued as per
+     * [MSC3882](https://github.com/matrix-org/matrix-spec-proposals/pull/3882).
+     * The server may require User-Interactive auth.
+     * Note that this is UNSTABLE and subject to breaking changes without notice.
+     * @param {IAuthData} auth Optional. Auth data to supply for User-Interactive auth.
+     * @return {Promise<UIAResponse<LoginTokenPostResponse>>} Resolves: On success, the token response
+     * or UIA auth data.
+     */
+    public requestLoginToken(auth?: IAuthData): Promise<UIAResponse<LoginTokenPostResponse>> {
+        const body: UIARequest<{}> = { auth };
+        return this.http.authedRequest(
+            undefined, // no callback support
+            Method.Post,
+            "/org.matrix.msc3882/login/token",
+            undefined, // no query params
+            body,
+            { prefix: PREFIX_UNSTABLE },
+        );
+    }
+
     /**
      * Get the fallback URL to use for unknown interactive-auth stages.
      *