@textrp/briij-js-sdk 41.0.0

package/lib/interactive-auth.d.ts

@@ -0,0 +1,341 @@
+import { type BriijClient } from "./client.ts";
+import { type UserIdentifier } from "./@types/auth.ts";
+export interface UIAFlow {
+    stages: Array<AuthType | string>;
+}
+export interface IInputs {
+    emailAddress?: string;
+    phoneCountry?: string;
+    phoneNumber?: string;
+    registrationToken?: string;
+}
+export interface IStageStatus {
+    emailSid?: string;
+    errcode?: string;
+    error?: string;
+}
+/**
+ * Data returned in the body of a 401 response from a UIA endpoint.
+ *
+ * @see https://spec.matrix.org/v1.6/client-server-api/#user-interactive-api-in-the-rest-api
+ */
+export interface IAuthData {
+    /**
+     * This is a session identifier that the client must pass back to the home server,
+     * if one is provided, in subsequent attempts to authenticate in the same API call.
+     */
+    session?: string;
+    /**
+     * A list of the stages the client has completed successfully
+     */
+    completed?: string[];
+    /**
+     * A list of the login flows supported by the server for this API.
+     */
+    flows?: UIAFlow[];
+    /**
+     * Contains any information that the client will need to know in order to use a given type of authentication.
+     * For each login type presented, that type may be present as a key in this dictionary.
+     * For example, the public part of an OAuth client ID could be given here.
+     */
+    params?: Record<string, Record<string, any>>;
+}
+export declare enum AuthType {
+    Password = "m.login.password",
+    Recaptcha = "m.login.recaptcha",
+    Terms = "m.login.terms",
+    Email = "m.login.email.identity",
+    Msisdn = "m.login.msisdn",
+    Sso = "m.login.sso",
+    SsoUnstable = "org.matrix.login.sso",
+    Dummy = "m.login.dummy",
+    RegistrationToken = "m.login.registration_token",
+    UnstableRegistrationToken = "org.matrix.msc3231.login.registration_token",
+    /**
+     * m.oauth stage introduced by MSC4312:
+     * https://spec.matrix.org/v1.17/client-server-api/#oauth-authentication
+     */
+    OAuth = "m.oauth"
+}
+/**
+ * https://spec.matrix.org/v1.7/client-server-api/#password-based
+ */
+type PasswordDict = {
+    type: AuthType.Password;
+    identifier: UserIdentifier;
+    password: string;
+    session: string;
+};
+/**
+ * https://spec.matrix.org/v1.7/client-server-api/#google-recaptcha
+ */
+type RecaptchaDict = {
+    type: AuthType.Recaptcha;
+    response: string;
+    session: string;
+};
+interface ThreepidCreds {
+    sid: string;
+    client_secret: string;
+    id_server: string;
+    id_access_token: string;
+}
+/**
+ * https://spec.matrix.org/v1.7/client-server-api/#email-based-identity--homeserver
+ */
+type EmailIdentityDict = {
+    type: AuthType.Email;
+    threepid_creds: ThreepidCreds;
+    session: string;
+};
+/**
+ * The parameters which are submitted as the `auth` dict in a UIA request
+ *
+ * @see https://spec.matrix.org/v1.6/client-server-api/#authentication-types
+ */
+export type AuthDict = PasswordDict | RecaptchaDict | EmailIdentityDict | {
+    type: Exclude<string, AuthType>;
+    [key: string]: any;
+} | {};
+export declare class NoAuthFlowFoundError extends Error {
+    readonly required_stages: string[];
+    readonly flows: UIAFlow[];
+    name: string;
+    constructor(m: string, required_stages: string[], flows: UIAFlow[]);
+}
+/**
+ * The type of an application callback to perform the user-interactive bit of UIA.
+ *
+ * It is called with a single parameter, `makeRequest`, which is a function which takes the UIA parameters and
+ * makes the HTTP request. The `authData` parameter in `makeRequest` can be set to null to omit the `auth` field
+ * from the UIA request.
+ *
+ * The generic parameter `T` is the type of the response of the endpoint, once it is eventually successful.
+ */
+export type UIAuthCallback<T> = (makeRequest: (authData: AuthDict | null) => Promise<T>) => Promise<T>;
+interface IOpts<T> {
+    /**
+     * A matrix client to use for the auth process
+     */
+    matrixClient: BriijClient;
+    /**
+     * Error response from the last request. If null, a request will be made with no auth before starting.
+     */
+    authData?: IAuthData;
+    /**
+     * Inputs provided by the user and used by different stages of the auto process.
+     * The inputs provided will affect what flow is chosen.
+     */
+    inputs?: IInputs;
+    /**
+     * If resuming an existing interactive auth session, the sessionId of that session.
+     */
+    sessionId?: string;
+    /**
+     * If resuming an existing interactive auth session, the client secret for that session
+     */
+    clientSecret?: string;
+    /**
+     * If returning from having completed m.login.email.identity auth, the sid for the email verification session.
+     */
+    emailSid?: string;
+    /**
+     * If specified, will prefer flows which entirely consist of listed stages.
+     * These should normally be of type AuthTypes but can be string when supporting custom auth stages.
+     *
+     * This can be used to avoid needing the fallback mechanism.
+     */
+    supportedStages?: Array<AuthType | string>;
+    /**
+     * Called with the new auth dict to submit the request.
+     * Also passes a second deprecated arg which is a flag set to true if this request is a background request.
+     * The busyChanged callback should be used instead of the background flag.
+     * Should return a promise which resolves to the successful response or rejects with a BriijError.
+     */
+    doRequest(auth: AuthDict | null, background: boolean): Promise<T>;
+    /**
+     * Called when the status of the UI auth changes,
+     * ie. when the state of an auth stage changes of when the auth flow moves to a new stage.
+     * The arguments are: the login type (eg m.login.password); and an object which is either an error or an
+     * informational object specific to the login type.
+     * If the 'errcode' key is defined, the object is an error, and has keys:
+     *     errcode: string, the textual error code, eg. M_UNKNOWN
+     *     error: string, human readable string describing the error
+     *
+     * The login type specific objects are as follows:
+     *     m.login.email.identity:
+     *         * emailSid: string, the sid of the active email auth session
+     */
+    stateUpdated(nextStage: AuthType | string, status: IStageStatus): void;
+    /**
+     * A function that takes the email address (string), clientSecret (string), attempt number (int) and
+     * sessionId (string) and calls the relevant requestToken function and returns the promise returned by that
+     * function.
+     * If the resulting promise rejects, the rejection will propagate through to the attemptAuth promise.
+     */
+    requestEmailToken(email: string, secret: string, attempt: number, session: string): Promise<{
+        sid: string;
+    }>;
+    /**
+     * Called whenever the interactive auth logic becomes busy submitting information provided by the user or finishes.
+     * After this has been called with true the UI should indicate that a request is in progress
+     * until it is called again with false.
+     */
+    busyChanged?(busy: boolean): void;
+    startAuthStage?(nextStage: string): Promise<void>;
+}
+/**
+ * Abstracts the logic used to drive the interactive auth process.
+ *
+ * <p>Components implementing an interactive auth flow should instantiate one of
+ * these, passing in the necessary callbacks to the constructor. They should
+ * then call attemptAuth, which will return a promise which will resolve or
+ * reject when the interactive-auth process completes.
+ *
+ * <p>Meanwhile, calls will be made to the startAuthStage and doRequest
+ * callbacks, and information gathered from the user can be submitted with
+ * submitAuthDict.
+ *
+ * @param opts - options object
+ * @typeParam T - the return type of the request when it is successful
+ */
+export declare class InteractiveAuth<T> {
+    private readonly matrixClient;
+    private readonly inputs;
+    private readonly clientSecret;
+    private readonly requestCallback;
+    private readonly busyChangedCallback?;
+    private readonly stateUpdatedCallback;
+    private readonly requestEmailTokenCallback;
+    private readonly supportedStages?;
+    private data;
+    private emailSid?;
+    private requestingEmailToken;
+    private attemptAuthDeferred;
+    private chosenFlow;
+    private currentStage;
+    private emailAttempt;
+    private submitPromise;
+    constructor(opts: IOpts<T>);
+    /**
+     * begin the authentication process.
+     *
+     * @returns which resolves to the response on success,
+     * or rejects with the error on failure. Rejects with NoAuthFlowFoundError if
+     *     no suitable authentication flow can be found
+     */
+    attemptAuth(): Promise<T>;
+    /**
+     * Poll to check if the auth session or current stage has been
+     * completed out-of-band. If so, the attemptAuth promise will
+     * be resolved.
+     */
+    poll(): Promise<void>;
+    /**
+     * get the auth session ID
+     *
+     * @returns session id
+     */
+    getSessionId(): string | undefined;
+    /**
+     * get the client secret used for validation sessions
+     * with the identity server.
+     *
+     * @returns client secret
+     */
+    getClientSecret(): string;
+    /**
+     * get the server params for a given stage
+     *
+     * @param loginType - login type for the stage
+     * @returns any parameters from the server for this stage
+     */
+    getStageParams(loginType: string): Record<string, any> | undefined;
+    getChosenFlow(): UIAFlow | null;
+    /**
+     * submit a new auth dict and fire off the request. This will either
+     * make attemptAuth resolve/reject, or cause the startAuthStage callback
+     * to be called for a new stage.
+     *
+     * @param authData - new auth dict to send to the server. Should
+     *    include a `type` property denoting the login type, as well as any
+     *    other params for that stage.
+     * @param background - If true, this request failing will not result
+     *    in the attemptAuth promise being rejected. This can be set to true
+     *    for requests that just poll to see if auth has been completed elsewhere.
+     */
+    submitAuthDict(authData: AuthDict, background?: boolean): Promise<void>;
+    /**
+     * Gets the sid for the email validation session
+     * Specific to m.login.email.identity
+     *
+     * @returns The sid of the email auth session
+     */
+    getEmailSid(): string | undefined;
+    /**
+     * Sets the sid for the email validation session
+     * This must be set in order to successfully poll for completion
+     * of the email validation.
+     * Specific to m.login.email.identity
+     *
+     * @param sid - The sid for the email validation session
+     */
+    setEmailSid(sid: string): void;
+    /**
+     * Requests a new email token and sets the email sid for the validation session
+     */
+    requestEmailToken: () => Promise<void>;
+    /**
+     * Fire off a request, and either resolve the promise, or call
+     * startAuthStage.
+     *
+     * @internal
+     * @param auth - new auth dict, including session id
+     * @param background - If true, this request is a background poll, so it
+     *    failing will not result in the attemptAuth promise being rejected.
+     *    This can be set to true for requests that just poll to see if auth has
+     *    been completed elsewhere.
+     */
+    private doRequest;
+    /**
+     * Pick the next stage and call the callback
+     *
+     * @internal
+     * @throws {@link NoAuthFlowFoundError} If no suitable authentication flow can be found
+     */
+    private startNextAuthStage;
+    /**
+     * Pick the next auth stage
+     *
+     * @internal
+     * @returns login type
+     * @throws {@link NoAuthFlowFoundError} If no suitable authentication flow can be found
+     */
+    private chooseStage;
+    private scoreFlow;
+    /**
+     * Pick one of the flows from the returned list
+     * If a flow using all of the inputs is found, it will
+     * be returned, otherwise, null will be returned.
+     *
+     * Only flows using all given inputs are chosen because it
+     * is likely to be surprising if the user provides a
+     * credential and it is not used. For example, for registration,
+     * this could result in the email not being used which would leave
+     * the account with no means to reset a password.
+     *
+     * @internal
+     * @returns flow
+     * @throws {@link NoAuthFlowFoundError} If no suitable authentication flow can be found
+     */
+    private chooseFlow;
+    /**
+     * Get the first uncompleted stage in the given flow
+     *
+     * @internal
+     * @returns login type
+     */
+    private firstUncompletedStage;
+}
+export {};
+//# sourceMappingURL=interactive-auth.d.ts.map

package/lib/interactive-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interactive-auth.d.ts","sourceRoot":"","sources":["../src/interactive-auth.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAKvD,MAAM,WAAW,OAAO;IACpB,MAAM,EAAE,KAAK,CAAC,QAAQ,GAAG,MAAM,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,OAAO;IAEpB,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,YAAY;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACtB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;IAClB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;CAChD;AAED,oBAAY,QAAQ;IAChB,QAAQ,qBAAqB;IAC7B,SAAS,sBAAsB;IAC/B,KAAK,kBAAkB;IACvB,KAAK,2BAA2B;IAChC,MAAM,mBAAmB;IACzB,GAAG,gBAAgB;IACnB,WAAW,yBAAyB;IACpC,KAAK,kBAAkB;IACvB,iBAAiB,+BAA+B;IAIhD,yBAAyB,gDAAgD;IACzE;;;OAGG;IACH,KAAK,YAAY;CACpB;AAED;;GAEG;AACH,KAAK,YAAY,GAAG;IAChB,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC;IACxB,UAAU,EAAE,cAAc,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;GAEG;AACH,KAAK,aAAa,GAAG;IACjB,IAAI,EAAE,QAAQ,CAAC,SAAS,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,UAAU,aAAa;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,KAAK,iBAAiB,GAAG;IACrB,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC;IACrB,cAAc,EAAE,aAAa,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GACd,YAAY,GACZ,aAAa,GACb,iBAAiB,GACjB;IAAE,IAAI,EAAE,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,GAEvD,EAAE,CAAC;AAET,qBAAa,oBAAqB,SAAQ,KAAK;aAMvB,eAAe,EAAE,MAAM,EAAE;aACzB,KAAK,EAAE,OAAO,EAAE;IAN7B,IAAI,SAA0B;gBAGjC,CAAC,EAAE,MAAM,EAEO,eAAe,EAAE,MAAM,EAAE,EACzB,KAAK,EAAE,OAAO,EAAE;CAIvC;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;AAEvG,UAAU,KAAK,CAAC,CAAC;IACb;;OAEG;IACH,YAAY,EAAE,WAAW,CAAC;IAC1B;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,KAAK,CAAC,QAAQ,GAAG,MAAM,CAAC,CAAC;IAE3C;;;;;OAKG;IACH,SAAS,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,EAAE,UAAU,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAClE;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,SAAS,EAAE,QAAQ,GAAG,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IAEvE;;;;;OAKG;IACH,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7G;;;;OAIG;IACH,WAAW,CAAC,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IAClC,cAAc,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,eAAe,CAAC,CAAC;IAC1B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAc;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAwB;IACxD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAA0B;IAC/D,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAA2B;IAChE,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAgC;IAC1E,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAc;IAG/C,OAAO,CAAC,IAAI,CAAiC;IAC7C,OAAO,CAAC,QAAQ,CAAC,CAAS;IAC1B,OAAO,CAAC,oBAAoB,CAAS;IACrC,OAAO,CAAC,mBAAmB,CAAwC;IACnE,OAAO,CAAC,UAAU,CAAwB;IAC1C,OAAO,CAAC,YAAY,CAAuB;IAE3C,OAAO,CAAC,YAAY,CAAK;IAIzB,OAAO,CAAC,aAAa,CAA8B;gBAEhC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;IAgBjC;;;;;;OAMG;IACU,WAAW,IAAI,OAAO,CAAC,CAAC,CAAC;IAsBtC;;;;OAIG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA+BlC;;;;OAIG;IACI,YAAY,IAAI,MAAM,GAAG,SAAS;IAIzC;;;;;OAKG;IACI,eAAe,IAAI,MAAM;IAIhC;;;;;OAKG;IACI,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS;IAIlE,aAAa,IAAI,OAAO,GAAG,IAAI;IAItC;;;;;;;;;;;OAWG;IACU,cAAc,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,UAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IA8ClF;;;;;OAKG;IACI,WAAW,IAAI,MAAM,GAAG,SAAS;IAIxC;;;;;;;OAOG;IACI,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIrC;;OAEG;IACI,iBAAiB,QAAa,OAAO,CAAC,IAAI,CAAC,CAuBhD;IAEF;;;;;;;;;;OAUG;YACW,SAAS;IAqEvB;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAyB1B;;;;;;OAMG;IACH,OAAO,CAAC,WAAW;IAYnB,OAAO,CAAC,SAAS;IASjB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,UAAU;IAmClB;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;CAIhC"}