@jeongsu816/matrix-bot-sdk 0.0.0-stage → 0.8.1

package/src/appservice/Intent.ts

@@ -0,0 +1,342 @@
+import {
+    DeviceKeyAlgorithm,
+    extractRequestError,
+    IAppserviceCryptoStorageProvider,
+    IAppserviceStorageProvider,
+    ICryptoStorageProvider,
+    LogService,
+    MatrixClient,
+    Metrics,
+} from "..";
+import { Appservice, IAppserviceOptions } from "./Appservice";
+// noinspection TypeScriptPreferShortImport
+import { timedIntentFunctionCall } from "../metrics/decorators";
+import { UnstableAppserviceApis } from "./UnstableAppserviceApis";
+import { MatrixError } from "../models/MatrixError";
+
+/**
+ * An Intent is an intelligent client that tracks things like the user's membership
+ * in rooms to ensure the action being performed is possible. This is very similar
+ * to how Intents work in the matrix-js-sdk in that the Intent will ensure that the
+ * user is joined to the room before posting a message, for example.
+ * @category Application services
+ */
+export class Intent {
+    /**
+     * The metrics instance for this intent. Note that this will not raise metrics
+     * for the underlying client - those will be available through this instance's
+     * parent (the appservice).
+     */
+    public readonly metrics: Metrics;
+
+    private readonly storage: IAppserviceStorageProvider;
+    private readonly cryptoStorage: IAppserviceCryptoStorageProvider;
+
+    private client: MatrixClient;
+    private unstableApisInstance: UnstableAppserviceApis;
+    private knownJoinedRooms: string[] = [];
+    private cryptoSetupPromise: Promise<void>;
+
+    /**
+     * Creates a new intent. Intended to be created by application services.
+     * @param {IAppserviceOptions} options The options for the application service.
+     * @param {string} impersonateUserId The user ID to impersonate.
+     * @param {Appservice} appservice The application service itself.
+     */
+    constructor(private options: IAppserviceOptions, private impersonateUserId: string, private appservice: Appservice) {
+        this.metrics = new Metrics(appservice.metrics);
+        this.storage = options.storage;
+        this.cryptoStorage = options.cryptoStorage;
+        this.makeClient(false);
+    }
+
+    private makeClient(withCrypto: boolean, accessToken?: string) {
+        let cryptoStore: ICryptoStorageProvider;
+        const storage = this.storage?.storageForUser?.(this.userId);
+        if (withCrypto) {
+            cryptoStore = this.cryptoStorage?.storageForUser(this.userId);
+            if (!cryptoStore) {
+                throw new Error("Tried to set up client with crypto when not available");
+            }
+            if (!storage) {
+                throw new Error("Tried to set up client with crypto, but no persistent storage");
+            }
+        }
+        this.client = new MatrixClient(this.options.homeserverUrl, accessToken ?? this.options.registration.as_token, storage, cryptoStore);
+        this.client.metrics = new Metrics(this.appservice.metrics); // Metrics only go up by one parent
+        this.unstableApisInstance = new UnstableAppserviceApis(this.client);
+        if (this.impersonateUserId !== this.appservice.botUserId) {
+            this.client.impersonateUserId(this.impersonateUserId);
+        }
+        if (this.options.joinStrategy) {
+            this.client.setJoinStrategy(this.options.joinStrategy);
+        }
+    }
+
+    /**
+     * Gets the user ID this intent is for.
+     */
+    public get userId(): string {
+        return this.impersonateUserId;
+    }
+
+    /**
+     * Gets the underlying MatrixClient that powers this Intent.
+     */
+    public get underlyingClient(): MatrixClient {
+        return this.client;
+    }
+
+    /**
+     * Gets the unstable API access class. This is generally not recommended to be
+     * used by appservices.
+     * @return {UnstableAppserviceApis} The unstable API access class.
+     */
+    public get unstableApis(): UnstableAppserviceApis {
+        return this.unstableApisInstance;
+    }
+
+    /**
+     * Sets up crypto on the client if it hasn't already been set up.
+     * @returns {Promise<void>} Resolves when complete.
+     */
+    @timedIntentFunctionCall()
+    public async enableEncryption(): Promise<void> {
+        if (!this.cryptoSetupPromise) {
+            // eslint-disable-next-line no-async-promise-executor
+            this.cryptoSetupPromise = new Promise(async (resolve, reject) => {
+                try {
+                    // Prepare a client first
+                    await this.ensureRegistered();
+                    const storage = this.storage?.storageForUser?.(this.userId);
+                    this.client.impersonateUserId(this.userId); // make sure the devices call works
+
+                    const cryptoStore = this.cryptoStorage?.storageForUser(this.userId);
+                    if (!cryptoStore) {
+                        // noinspection ExceptionCaughtLocallyJS
+                        throw new Error("Failed to create crypto store");
+                    }
+
+                    // Try to impersonate a device ID
+                    const ownDevices = await this.client.getOwnDevices();
+                    let deviceId = await cryptoStore.getDeviceId();
+                    if (!deviceId || !ownDevices.some(d => d.device_id === deviceId)) {
+                        const deviceKeys = await this.client.getUserDevices([this.userId]);
+                        const userDeviceKeys = deviceKeys.device_keys[this.userId];
+                        if (userDeviceKeys) {
+                            // We really should be validating signatures here, but we're actively looking
+                            // for devices without keys to impersonate, so it should be fine. In theory,
+                            // those devices won't even be present but we're cautious.
+                            const devicesWithKeys = Array.from(Object.entries(userDeviceKeys))
+                                .filter(d => d[0] === d[1].device_id && !!d[1].keys?.[`${DeviceKeyAlgorithm.Curve25519}:${d[1].device_id}`])
+                                .map(t => t[0]); // grab device ID from tuple
+                            deviceId = ownDevices.find(d => !devicesWithKeys.includes(d.device_id))?.device_id;
+                        }
+                    }
+                    let prepared = false;
+                    if (deviceId) {
+                        this.makeClient(true);
+                        this.client.impersonateUserId(this.userId, deviceId);
+
+                        // verify that the server supports impersonating the device
+                        const respDeviceId = (await this.client.getWhoAmI()).device_id;
+                        prepared = (respDeviceId === deviceId);
+                    }
+
+                    if (!prepared) {
+                        // XXX: We work around servers that don't support device_id impersonation
+                        const accessToken = await Promise.resolve(storage?.readValue("accessToken"));
+                        if (!accessToken) {
+                            const loginBody = {
+                                type: "m.login.application_service",
+                                identifier: {
+                                    type: "m.id.user",
+                                    user: this.userId,
+                                },
+                            };
+                            const res = await this.client.doRequest("POST", "/_matrix/client/v3/login", {}, loginBody);
+                            this.makeClient(true, res['access_token']);
+                            storage.storeValue("accessToken", this.client.accessToken);
+                            prepared = true;
+                        } else {
+                            this.makeClient(true, accessToken);
+                            prepared = true;
+                        }
+                    }
+
+                    if (!prepared) {// noinspection ExceptionCaughtLocallyJS
+                        throw new Error("Unable to establish a device ID");
+                    }
+
+                    // Now set up crypto
+                    await this.client.crypto.prepare(await this.refreshJoinedRooms());
+
+                    this.appservice.on("room.event", (roomId, event) => {
+                        if (!this.knownJoinedRooms.includes(roomId)) return;
+                        this.client.crypto.onRoomEvent(roomId, event);
+                    });
+
+                    resolve();
+                } catch (e) {
+                    reject(e);
+                }
+            });
+        }
+        return this.cryptoSetupPromise;
+    }
+
+    /**
+     * Gets the joined rooms for the intent. Note that by working around
+     * the intent to join rooms may yield inaccurate results.
+     * @returns {Promise<string[]>} Resolves to an array of room IDs where
+     * the intent is joined.
+     */
+    @timedIntentFunctionCall()
+    public async getJoinedRooms(): Promise<string[]> {
+        await this.ensureRegistered();
+        if (this.knownJoinedRooms.length === 0) await this.refreshJoinedRooms();
+        return this.knownJoinedRooms.map(r => r); // clone
+    }
+
+    /**
+     * Leaves the given room.
+     * @param {string} roomId The room ID to leave
+     * @param {string=} reason Optional reason to be included as the reason for leaving the room.
+     * @returns {Promise<any>} Resolves when the room has been left.
+     */
+    @timedIntentFunctionCall()
+    public async leaveRoom(roomId: string, reason?: string): Promise<any> {
+        await this.ensureRegistered();
+        return this.client.leaveRoom(roomId, reason).then(async () => {
+            // Recalculate joined rooms now that we've left a room
+            await this.refreshJoinedRooms();
+        });
+    }
+
+    /**
+     * Joins the given room
+     * @param {string} roomIdOrAlias the room ID or alias to join
+     * @returns {Promise<string>} resolves to the joined room ID
+     */
+    @timedIntentFunctionCall()
+    public async joinRoom(roomIdOrAlias: string): Promise<string> {
+        await this.ensureRegistered();
+        return this.client.joinRoom(roomIdOrAlias).then(async roomId => {
+            // Recalculate joined rooms now that we've joined a room
+            await this.refreshJoinedRooms();
+            return roomId;
+        });
+    }
+
+    /**
+     * Sends a text message to a room.
+     * @param {string} roomId The room ID to send text to.
+     * @param {string} body The message body to send.
+     * @param {"m.text" | "m.emote" | "m.notice"} msgtype The message type to send.
+     * @returns {Promise<string>} Resolves to the event ID of the sent message.
+     */
+    @timedIntentFunctionCall()
+    public async sendText(roomId: string, body: string, msgtype: "m.text" | "m.emote" | "m.notice" = "m.text"): Promise<string> {
+        return this.sendEvent(roomId, { body: body, msgtype: msgtype });
+    }
+
+    /**
+     * Sends an event to a room.
+     * @param {string} roomId The room ID to send the event to.
+     * @param {any} content The content of the event.
+     * @returns {Promise<string>} Resolves to the event ID of the sent event.
+     */
+    @timedIntentFunctionCall()
+    public async sendEvent(roomId: string, content: any): Promise<string> {
+        await this.ensureRegisteredAndJoined(roomId);
+        return this.client.sendMessage(roomId, content);
+    }
+
+    /**
+     * Ensures the user is registered and joined to the given room.
+     * @param {string} roomId The room ID to join
+     * @returns {Promise<any>} Resolves when complete
+     */
+    @timedIntentFunctionCall()
+    public async ensureRegisteredAndJoined(roomId: string) {
+        await this.ensureRegistered();
+        await this.ensureJoined(roomId);
+    }
+
+    /**
+     * Ensures the user is joined to the given room
+     * @param {string} roomId The room ID to join
+     * @returns {Promise<any>} Resolves when complete
+     */
+    @timedIntentFunctionCall()
+    public async ensureJoined(roomId: string) {
+        if (this.knownJoinedRooms.indexOf(roomId) !== -1) {
+            return;
+        }
+
+        await this.refreshJoinedRooms();
+
+        if (this.knownJoinedRooms.indexOf(roomId) !== -1) {
+            return;
+        }
+
+        const returnedRoomId = await this.client.joinRoom(roomId);
+        if (!this.knownJoinedRooms.includes(returnedRoomId)) {
+            this.knownJoinedRooms.push(returnedRoomId);
+        }
+        return returnedRoomId;
+    }
+
+    /**
+     * Refreshes which rooms the user is joined to, potentially saving time on
+     * calls like ensureJoined()
+     * @returns {Promise<string[]>} Resolves to the joined room IDs for the user.
+     */
+    @timedIntentFunctionCall()
+    public async refreshJoinedRooms(): Promise<string[]> {
+        this.knownJoinedRooms = await this.client.getJoinedRooms();
+        return this.knownJoinedRooms.map(r => r); // clone
+    }
+
+    /**
+     * Ensures the user is registered
+     * @param deviceId An optional device ID to register with.
+     * @returns {Promise<any>} Resolves when complete
+     */
+    @timedIntentFunctionCall()
+    public async ensureRegistered(deviceId?: string) {
+        if (!(await Promise.resolve(this.storage.isUserRegistered(this.userId)))) {
+            try {
+                const result = await this.client.doRequest("POST", "/_matrix/client/v3/register", null, {
+                    type: "m.login.application_service",
+                    username: this.userId.substring(1).split(":")[0],
+                    device_id: deviceId,
+                });
+
+                // HACK: Workaround for unit tests
+                if (result['errcode']) {
+                    // noinspection ExceptionCaughtLocallyJS
+                    throw { body: result }; // eslint-disable-line no-throw-literal
+                }
+
+                this.client.impersonateUserId(this.userId, result["device_id"]);
+            } catch (err) {
+                if (err instanceof MatrixError && err.errcode === "M_USER_IN_USE") {
+                    await Promise.resolve(this.storage.addRegisteredUser(this.userId));
+                    if (this.userId === this.appservice.botUserId) {
+                        return null;
+                    } else {
+                        LogService.error("Appservice", "Error registering user: User ID is in use");
+                        return null;
+                    }
+                } else {
+                    LogService.error("Appservice", "Encountered error registering user: ");
+                    LogService.error("Appservice", extractRequestError(err));
+                }
+                throw err;
+            }
+
+            await Promise.resolve(this.storage.addRegisteredUser(this.userId));
+        }
+    }
+}

package/src/appservice/MatrixBridge.ts

@@ -0,0 +1,139 @@
+import { Appservice } from "./Appservice";
+import { Intent } from "./Intent";
+
+export const REMOTE_USER_INFO_ACCOUNT_DATA_EVENT_TYPE = "io.t2bot.sdk.bot.remote_user_info";
+export const REMOTE_ROOM_INFO_ACCOUNT_DATA_EVENT_TYPE = "io.t2bot.sdk.bot.remote_room_info";
+export const REMOTE_USER_MAP_ACCOUNT_DATA_EVENT_TYPE_PREFIX = "io.t2bot.sdk.bot.remote_user_map";
+export const REMOTE_ROOM_MAP_ACCOUNT_DATA_EVENT_TYPE_PREFIX = "io.t2bot.sdk.bot.remote_room_map";
+
+/**
+ * @see MatrixBridge
+ * @category Application services
+ */
+export interface IRemoteRoomInfo {
+    /**
+     * A unique identifier for the remote user.
+     */
+    id: string;
+}
+
+/**
+ * @see MatrixBridge
+ * @category Application services
+ */
+export interface IRemoteUserInfo {
+    /**
+     * A unique identifier for the remote room (or room equivalent).
+     */
+    id: string;
+}
+
+/**
+ * Utility class for common operations performed by bridges (represented
+ * as appservices).
+ *
+ * The storage utilities are not intended for bridges which allow 1:many
+ * relationships with the remote network.
+ *
+ * Bridges are generally expected to create their own classes which extend
+ * the IRemoteRoomInfo and IRemoteUserInfo interfaces and serialize to JSON
+ * cleanly. The serialized version of these classes is persisted in various
+ * account data locations for future lookups.
+ * @category Application services
+ */
+export class MatrixBridge {
+    constructor(private appservice: Appservice) {
+    }
+
+    /**
+     * Gets information about a remote user.
+     * @param {Intent} userIntent The Matrix user intent to get information on.
+     * @returns {Promise<IRemoteUserInfo>} Resolves to the remote user information.
+     */
+    public async getRemoteUserInfo<T extends IRemoteUserInfo>(userIntent: Intent): Promise<T> {
+        await userIntent.ensureRegistered();
+        return <Promise<T>>userIntent.underlyingClient.getAccountData(REMOTE_USER_INFO_ACCOUNT_DATA_EVENT_TYPE);
+    }
+
+    /**
+     * Sets information about a remote user. Calling this function will map the
+     * provided remote user ID to the intent's owner.
+     * @param {Intent} userIntent The Matrix user intent to store information on.
+     * @param {IRemoteUserInfo} remoteInfo The remote user information to store
+     * @returns {Promise<any>} Resolves when the information has been updated.
+     */
+    public async setRemoteUserInfo<T extends IRemoteUserInfo>(userIntent: Intent, remoteInfo: T): Promise<any> {
+        await userIntent.ensureRegistered();
+        await userIntent.underlyingClient.setAccountData(REMOTE_USER_INFO_ACCOUNT_DATA_EVENT_TYPE, remoteInfo);
+        await this.updateRemoteUserMapping(userIntent.userId, remoteInfo.id);
+    }
+
+    /**
+     * Gets information about a remote room.
+     * @param {string} matrixRoomId The Matrix room ID to get information on.
+     * @returns {Promise<IRemoteRoomInfo>} Resolves to the remote room information.
+     */
+    public async getRemoteRoomInfo<T extends IRemoteRoomInfo>(matrixRoomId: string): Promise<T> {
+        const bridgeBot = this.appservice.botIntent;
+        await bridgeBot.ensureRegistered();
+        // We do not need to ensure the user is joined to the room because we can associate
+        // room account data with any arbitrary room.
+        return <Promise<T>>bridgeBot.underlyingClient.getRoomAccountData(REMOTE_ROOM_INFO_ACCOUNT_DATA_EVENT_TYPE, matrixRoomId);
+    }
+
+    /**
+     * Sets information about a remote room. Calling this function will map the
+     * provided remote room ID to the matrix room ID.
+     * @param {string} matrixRoomId The Matrix room ID to store information on.
+     * @param {IRemoteRoomInfo} remoteInfo The remote room information to store
+     * @returns {Promise<any>} Resolves when the information has been updated.
+     */
+    public async setRemoteRoomInfo<T extends IRemoteRoomInfo>(matrixRoomId: string, remoteInfo: T): Promise<any> {
+        const bridgeBot = this.appservice.botIntent;
+        await bridgeBot.ensureRegistered();
+        // We do not need to ensure the user is joined to the room because we can associate
+        // room account data with any arbitrary room.
+        await bridgeBot.underlyingClient.setRoomAccountData(REMOTE_ROOM_INFO_ACCOUNT_DATA_EVENT_TYPE, matrixRoomId, remoteInfo);
+        await this.updateRemoteRoomMapping(matrixRoomId, remoteInfo.id);
+    }
+
+    /**
+     * Gets the Matrix room ID for the provided remote room ID.
+     * @param {string} remoteRoomId The remote room ID to look up.
+     * @returns {Promise<string>} Resolves to the Matrix room ID.
+     */
+    public async getMatrixRoomIdForRemote(remoteRoomId: string): Promise<string> {
+        const eventType = `${REMOTE_ROOM_MAP_ACCOUNT_DATA_EVENT_TYPE_PREFIX}.${remoteRoomId}`;
+        const bridgeBot = this.appservice.botIntent;
+        await bridgeBot.ensureRegistered();
+        const result = await bridgeBot.underlyingClient.getAccountData(eventType);
+        return result['id'];
+    }
+
+    /**
+     * Gets a Matrix user intent for the provided remote user ID.
+     * @param {string} remoteUserId The remote user ID to look up.
+     * @returns {Promise<Intent>} Resolves to the Matrix user intent.
+     */
+    public async getIntentForRemote(remoteUserId: string): Promise<Intent> {
+        const eventType = `${REMOTE_USER_MAP_ACCOUNT_DATA_EVENT_TYPE_PREFIX}.${remoteUserId}`;
+        const bridgeBot = this.appservice.botIntent;
+        await bridgeBot.ensureRegistered();
+        const result = await bridgeBot.underlyingClient.getAccountData(eventType);
+        return this.appservice.getIntentForUserId(result['id']);
+    }
+
+    private async updateRemoteUserMapping(matrixUserId: string, remoteUserId: string): Promise<any> {
+        const eventType = `${REMOTE_USER_MAP_ACCOUNT_DATA_EVENT_TYPE_PREFIX}.${remoteUserId}`;
+        const bridgeBot = this.appservice.botIntent;
+        await bridgeBot.ensureRegistered();
+        await bridgeBot.underlyingClient.setAccountData(eventType, { id: matrixUserId });
+    }
+
+    private async updateRemoteRoomMapping(matrixRoomId: string, remoteRoomId: string): Promise<any> {
+        const eventType = `${REMOTE_ROOM_MAP_ACCOUNT_DATA_EVENT_TYPE_PREFIX}.${remoteRoomId}`;
+        const bridgeBot = this.appservice.botIntent;
+        await bridgeBot.ensureRegistered();
+        await bridgeBot.underlyingClient.setAccountData(eventType, { id: matrixRoomId });
+    }
+}

package/src/appservice/UnstableAppserviceApis.ts

@@ -0,0 +1,63 @@
+import { MatrixClient } from "../MatrixClient";
+import { MSC2716BatchSendResponse } from "../models/MSC2176";
+
+/**
+ * Unstable APIs that shouldn't be used in most circumstances for appservices.
+ * @category Unstable APIs
+ */
+export class UnstableAppserviceApis {
+    private requestId = 0;
+
+    constructor(private client: MatrixClient) {
+    }
+
+    /**
+     * Send several historical events into a room.
+     * @see https://github.com/matrix-org/matrix-doc/pull/2716
+     * @param {string} roomId The roomID to send to.
+     * @param {string} prevEventId The event ID where this batch will be inserted
+     * @param {string} chunkId The chunk ID returned from a previous call. Set falsy to start at the beginning.
+     * @param {any[]} events A set of event contents for events to be inserted into the room.
+     * @param {any[]} stateEventsAtStart A set of state events to be inserted into the room. Defaults to empty.
+     * @returns A set of eventIds and the next chunk ID
+     */
+    public async sendHistoricalEventBatch(roomId: string, prevEventId: string, events: any[], stateEventsAtStart: any[] = [], chunkId?: string): Promise<MSC2716BatchSendResponse> {
+        return this.client.doRequest("POST", `/_matrix/client/unstable/org.matrix.msc2716/rooms/${encodeURIComponent(roomId)}/batch_send`, {
+            prev_event: prevEventId,
+            chunk_id: chunkId,
+        }, {
+            events,
+            state_events_at_start: stateEventsAtStart,
+        });
+    }
+
+    /**
+     * Sends an event to the given room with a given timestamp.
+     * @param {string} roomId the room ID to send the event to
+     * @param {string} eventType the type of event to send
+     * @param {string} content the event body to send
+     * @param {number} ts The origin_server_ts of the new event
+     * @returns {Promise<string>} resolves to the event ID that represents the event
+     */
+    public async sendEventWithTimestamp(roomId: string, eventType: string, content: any, ts: number) {
+        const txnId = `${(new Date().getTime())}__inc_appts${++this.requestId}`;
+        const path = `/_matrix/client/v3/rooms/${encodeURIComponent(roomId)}/send/${encodeURIComponent(eventType)}/${encodeURIComponent(txnId)}`;
+        const response = await this.client.doRequest("PUT", path, { ts }, content);
+        return response.event_id;
+    }
+
+    /**
+     * Sends a state event to the given room with a given timestamp.
+     * @param {string} roomId the room ID to send the event to
+     * @param {string} type the event type to send
+     * @param {string} stateKey the state key to send, should not be null
+     * @param {string} content the event body to send
+     * @param {number} ts The origin_server_ts of the new event
+     * @returns {Promise<string>} resolves to the event ID that represents the message
+     */
+    public async sendStateEventWithTimestamp(roomId: string, type: string, stateKey: string, content: any, ts: number): Promise<string> {
+        const path = `/_matrix/client/v3/rooms/${encodeURIComponent(roomId)}/state/${encodeURIComponent(type)}/${encodeURIComponent(stateKey)}`;
+        const response = await this.client.doRequest("PUT", path, { ts }, content);
+        return response.event_id;
+    }
+}

package/src/appservice/http_responses.ts

@@ -0,0 +1,77 @@
+/**
+ * This is the response format documented in
+ * https://matrix.org/docs/spec/application_service/r0.1.2#get-matrix-app-v1-thirdparty-protocol-protocol
+ * @category Application services
+ */
+export interface IApplicationServiceProtocol {
+    user_fields: string[];
+    location_fields: string[];
+    icon: string;
+    field_types: { [field: string]: IFieldType };
+    instances: { [name: string]: IProtocolInstance };
+}
+
+interface IFieldType {
+    regexp: string;
+    placeholder: string;
+}
+
+interface IProtocolInstance {
+    desc: string;
+    icon: string;
+    fields: { [field: string]: string };
+    network_id: string;
+}
+
+/**
+ * This is the response format for an MSC3983 `/keys/claim` request.
+ * See https://github.com/matrix-org/matrix-spec-proposals/pull/3983
+ * @deprecated This can be removed at any time without notice as it is unstable functionality.
+ * @category Application services
+ */
+export interface MSC3983KeyClaimResponse {
+    [userId: string]: {
+        [deviceId: string]: {
+            [keyId: string]: {
+                // for signed_curve25519 keys
+                key: string;
+                signatures: {
+                    [userId: string]: {
+                        [keyId: string]: string;
+                    };
+                };
+            };
+        };
+    };
+}
+
+/**
+ * This is the response format for an MSC3984 `/keys/query` request.
+ * See https://github.com/matrix-org/matrix-spec-proposals/pull/3984
+ * @deprecated This can be removed at any time without notice as it is unstable functionality.
+ * @category Application services
+ */
+export interface MSC3984KeyQueryResponse {
+    device_keys: {
+        [userId: string]: {
+            [deviceId: string]: {
+                algorithms: string[];
+                device_id: string;
+                user_id: string;
+                keys: {
+                    [keyId: string]: string;
+                };
+                signatures: {
+                    [userId: string]: {
+                        [keyId: string]: string;
+                    };
+                };
+                unsigned?: {
+                    [key: string]: any;
+                };
+            };
+        };
+    };
+
+    // TODO: Cross-signing support
+}

package/src/b64.ts

@@ -0,0 +1,63 @@
+/**
+ * Encodes Base64.
+ * @category Utilities
+ * @param {ArrayBuffer | Uint8Array} b The buffer to encode.
+ * @returns {string} The Base64 string.
+ */
+export function encodeBase64(b: ArrayBuffer | Uint8Array): string {
+    if (b instanceof ArrayBuffer) {
+        return Buffer.from(b).toString('base64');
+    } else {
+        return Buffer.from(b.buffer, b.byteOffset, b.byteLength).toString('base64');
+    }
+}
+
+/**
+ * Encodes Unpadded Base64.
+ * @category Utilities
+ * @param {ArrayBuffer | Uint8Array} b The buffer to encode.
+ * @returns {string} The Base64 string.
+ */
+export function encodeUnpaddedBase64(b: ArrayBuffer | Uint8Array): string {
+    return encodeBase64(b).replace(/=+/g, '');
+}
+
+/**
+ * Encodes URL-Safe Unpadded Base64.
+ * @category Utilities
+ * @param {ArrayBuffer | Uint8Array} b The buffer to encode.
+ * @returns {string} The Base64 string.
+ */
+export function encodeUnpaddedUrlSafeBase64(b: ArrayBuffer | Uint8Array): string {
+    return encodeUnpaddedBase64(b).replace(/\+/g, '-').replace(/\//g, '_');
+}
+
+/**
+ * Decodes Base64.
+ * @category Utilities
+ * @param {string} s The Base64 string.
+ * @returns {Uint8Array} The encoded data as a buffer.
+ */
+export function decodeBase64(s: string): Uint8Array {
+    return Buffer.from(s, 'base64');
+}
+
+/**
+ * Decodes Unpadded Base64.
+ * @category Utilities
+ * @param {string} s The Base64 string.
+ * @returns {Uint8Array} The encoded data as a buffer.
+ */
+export function decodeUnpaddedBase64(s: string): Uint8Array {
+    return decodeBase64(s); // yay, it's the same
+}
+
+/**
+ * Decodes URL-Safe Unpadded Base64.
+ * @category Utilities
+ * @param {string} s The Base64 string.
+ * @returns {Uint8Array} The encoded data as a buffer.
+ */
+export function decodeUnpaddedUrlSafeBase64(s: string): Uint8Array {
+    return decodeUnpaddedBase64(s.replace(/-/g, '+').replace(/_/g, '/'));
+}