Skip to content

Commit 1c1ac13

Browse files
t3chguyt3chguy
authored
Improve types around login, registration, UIA and identity servers (#3537)
1 parent 89cabc4 commit 1c1ac13

File tree

6 files changed

+442
-147
lines changed

6 files changed

+442
-147
lines changed

‎spec/unit/interactive-auth.spec.ts

-1
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,6 @@ describe("InteractiveAuth", () => {
9494
authData: {
9595
session: "sessionId",
9696
flows: [{ stages: [AuthType.Password] }],
97-
errcode: "MockError0",
9897
params: {
9998
[AuthType.Password]: { param: "aa" },
10099
},

‎src/@types/auth.ts

+154-12
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ limitations under the License.
1515
*/
1616

1717
import { UnstableValue } from "../NamespacedValue";
18+
import { IClientWellKnown } from "../client";
1819

1920
// disable lint because these are wire responses
2021
/* eslint-disable camelcase */
@@ -79,25 +80,166 @@ export interface IIdentityProvider {
7980
brand?: IdentityProviderBrand | string;
8081
}
8182

83+
export enum SSOAction {
84+
/** The user intends to login to an existing account */
85+
LOGIN = "login",
86+
87+
/** The user intends to register for a new account */
88+
REGISTER = "register",
89+
}
90+
8291
/**
83-
* Parameters to login request as per https://spec.matrix.org/v1.3/client-server-api/#login
92+
* A client can identify a user using their Matrix ID.
93+
* This can either be the fully qualified Matrix user ID, or just the localpart of the user ID.
94+
* @see https://spec.matrix.org/v1.7/client-server-api/#matrix-user-id
8495
*/
85-
/* eslint-disable camelcase */
86-
export interface ILoginParams {
87-
identifier?: object;
88-
password?: string;
89-
token?: string;
96+
type UserLoginIdentifier = {
97+
type: "m.id.user";
98+
user: string;
99+
};
100+
101+
/**
102+
* A client can identify a user using a 3PID associated with the user’s account on the homeserver,
103+
* where the 3PID was previously associated using the /account/3pid API.
104+
* See the 3PID Types Appendix for a list of Third-party ID media.
105+
* @see https://spec.matrix.org/v1.7/client-server-api/#third-party-id
106+
*/
107+
type ThirdPartyLoginIdentifier = {
108+
type: "m.id.thirdparty";
109+
medium: string;
110+
address: string;
111+
};
112+
113+
/**
114+
* A client can identify a user using a phone number associated with the user’s account,
115+
* where the phone number was previously associated using the /account/3pid API.
116+
* The phone number can be passed in as entered by the user; the homeserver will be responsible for canonicalising it.
117+
* If the client wishes to canonicalise the phone number,
118+
* then it can use the m.id.thirdparty identifier type with a medium of msisdn instead.
119+
*
120+
* The country is the two-letter uppercase ISO-3166-1 alpha-2 country code that the number in phone should be parsed as if it were dialled from.
121+
*
122+
* @see https://spec.matrix.org/v1.7/client-server-api/#phone-number
123+
*/
124+
type PhoneLoginIdentifier = {
125+
type: "m.id.phone";
126+
country: string;
127+
phone: string;
128+
};
129+
130+
type SpecUserIdentifier = UserLoginIdentifier | ThirdPartyLoginIdentifier | PhoneLoginIdentifier;
131+
132+
/**
133+
* User Identifiers usable for login & user-interactive authentication.
134+
*
135+
* Extensibly allows more than Matrix specified identifiers.
136+
*/
137+
export type UserIdentifier =
138+
| SpecUserIdentifier
139+
| { type: Exclude<string, SpecUserIdentifier["type"]>; [key: string]: any };
140+
141+
/**
142+
* Request body for POST /login request
143+
* @see https://spec.matrix.org/v1.7/client-server-api/#post_matrixclientv3login
144+
*/
145+
export interface LoginRequest {
146+
/**
147+
* The login type being used.
148+
*/
149+
type: "m.login.password" | "m.login.token" | string;
150+
/**
151+
* Third-party identifier for the user.
152+
* @deprecated in favour of `identifier`.
153+
*/
154+
address?: string;
155+
/**
156+
* ID of the client device.
157+
* If this does not correspond to a known client device, a new device will be created.
158+
* The given device ID must not be the same as a cross-signing key ID.
159+
* The server will auto-generate a device_id if this is not specified.
160+
*/
90161
device_id?: string;
162+
/**
163+
* Identification information for a user
164+
*/
165+
identifier?: UserIdentifier;
166+
/**
167+
* A display name to assign to the newly-created device.
168+
* Ignored if device_id corresponds to a known device.
169+
*/
91170
initial_device_display_name?: string;
171+
/**
172+
* When logging in using a third-party identifier, the medium of the identifier.
173+
* Must be `email`.
174+
* @deprecated in favour of `identifier`.
175+
*/
176+
medium?: "email";
177+
/**
178+
* Required when type is `m.login.password`. The user’s password.
179+
*/
180+
password?: string;
181+
/**
182+
* If true, the client supports refresh tokens.
183+
*/
184+
refresh_token?: boolean;
185+
/**
186+
* Required when type is `m.login.token`. Part of Token-based login.
187+
*/
188+
token?: string;
189+
/**
190+
* The fully qualified user ID or just local part of the user ID, to log in.
191+
* @deprecated in favour of identifier.
192+
*/
193+
user?: string;
194+
// Extensible
195+
[key: string]: any;
92196
}
93-
/* eslint-enable camelcase */
94197

95-
export enum SSOAction {
96-
/** The user intends to login to an existing account */
97-
LOGIN = "login",
198+
// Export for backwards compatibility
199+
export type ILoginParams = LoginRequest;
98200

99-
/** The user intends to register for a new account */
100-
REGISTER = "register",
201+
/**
202+
* Response body for POST /login request
203+
* @see https://spec.matrix.org/v1.7/client-server-api/#post_matrixclientv3login
204+
*/
205+
export interface LoginResponse {
206+
/**
207+
* An access token for the account.
208+
* This access token can then be used to authorize other requests.
209+
*/
210+
access_token: string;
211+
/**
212+
* ID of the logged-in device.
213+
* Will be the same as the corresponding parameter in the request, if one was specified.
214+
*/
215+
device_id: string;
216+
/**
217+
* The fully-qualified Matrix ID for the account.
218+
*/
219+
user_id: string;
220+
/**
221+
* The lifetime of the access token, in milliseconds.
222+
* Once the access token has expired a new access token can be obtained by using the provided refresh token.
223+
* If no refresh token is provided, the client will need to re-log in to obtain a new access token.
224+
* If not given, the client can assume that the access token will not expire.
225+
*/
226+
expires_in_ms?: number;
227+
/**
228+
* A refresh token for the account.
229+
* This token can be used to obtain a new access token when it expires by calling the /refresh endpoint.
230+
*/
231+
refresh_token?: string;
232+
/**
233+
* Optional client configuration provided by the server.
234+
* If present, clients SHOULD use the provided object to reconfigure themselves, optionally validating the URLs within.
235+
* This object takes the same form as the one returned from .well-known autodiscovery.
236+
*/
237+
well_known?: IClientWellKnown;
238+
/**
239+
* The server_name of the homeserver on which the account has been registered.
240+
* @deprecated Clients should extract the server_name from user_id (by splitting at the first colon) if they require it.
241+
*/
242+
home_server?: string;
101243
}
102244

103245
/**

‎src/@types/registration.ts

+116
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
/*
2+
Copyright 2023 The Matrix.org Foundation C.I.C.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
import { AuthDict } from "../interactive-auth";
18+
19+
/**
20+
* The request body of a call to `POST /_matrix/client/v3/register`.
21+
*
22+
* @see https://spec.matrix.org/v1.7/client-server-api/#post_matrixclientv3register
23+
*/
24+
export interface RegisterRequest {
25+
/**
26+
* Additional authentication information for the user-interactive authentication API.
27+
* Note that this information is not used to define how the registered user should be authenticated,
28+
* but is instead used to authenticate the register call itself.
29+
*/
30+
auth?: AuthDict;
31+
/**
32+
* The basis for the localpart of the desired Matrix ID.
33+
* If omitted, the homeserver MUST generate a Matrix ID local part.
34+
*/
35+
username?: string;
36+
/**
37+
* The desired password for the account.
38+
*/
39+
password?: string;
40+
/**
41+
* If true, the client supports refresh tokens.
42+
*/
43+
refresh_token?: boolean;
44+
/**
45+
* If true, an access_token and device_id should not be returned from this call, therefore preventing an automatic login.
46+
* Defaults to false.
47+
*/
48+
inhibit_login?: boolean;
49+
/**
50+
* A display name to assign to the newly-created device.
51+
* Ignored if device_id corresponds to a known device.
52+
*/
53+
initial_device_display_name?: string;
54+
/**
55+
* @deprecated missing in the spec
56+
*/
57+
guest_access_token?: string;
58+
/**
59+
* @deprecated missing in the spec
60+
*/
61+
x_show_msisdn?: boolean;
62+
/**
63+
* @deprecated missing in the spec
64+
*/
65+
bind_msisdn?: boolean;
66+
/**
67+
* @deprecated missing in the spec
68+
*/
69+
bind_email?: boolean;
70+
}
71+
72+
/**
73+
* The result of a successful call to `POST /_matrix/client/v3/register`.
74+
*
75+
* @see https://spec.matrix.org/v1.7/client-server-api/#post_matrixclientv3register
76+
*/
77+
export interface RegisterResponse {
78+
/**
79+
* The fully-qualified Matrix user ID (MXID) that has been registered.
80+
*/
81+
user_id: string;
82+
/**
83+
* An access token for the account.
84+
* This access token can then be used to authorize other requests.
85+
* Required if the inhibit_login option is false.
86+
*/
87+
access_token?: string;
88+
/**
89+
* ID of the registered device.
90+
* Will be the same as the corresponding parameter in the request, if one was specified.
91+
* Required if the inhibit_login option is false.
92+
*/
93+
device_id?: string;
94+
/**
95+
* The lifetime of the access token, in milliseconds.
96+
* Once the access token has expired a new access token can be obtained by using the provided refresh token.
97+
* If no refresh token is provided, the client will need to re-log in to obtain a new access token.
98+
* If not given, the client can assume that the access token will not expire.
99+
*
100+
* Omitted if the inhibit_login option is true.
101+
*/
102+
expires_in_ms?: number;
103+
/**
104+
* A refresh token for the account.
105+
* This token can be used to obtain a new access token when it expires by calling the /refresh endpoint.
106+
*
107+
* Omitted if the inhibit_login option is true.
108+
*/
109+
refresh_token?: string;
110+
/**
111+
* The server_name of the homeserver on which the account has been registered.
112+
*
113+
* @deprecated Clients should extract the server_name from user_id (by splitting at the first colon) if they require it.
114+
*/
115+
home_server?: string;
116+
}

0 commit comments

Comments
 (0)