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

package/lib/strategies/AppserviceJoinRoomStrategy.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppserviceJoinRoomStrategy = void 0;
+/**
+ * A join strategy for application services that proxies joins to an underlying join
+ * strategy while also trying to use the appservice's bot user to invite the underlying
+ * user if needed.
+ * @category Join strategies
+ */
+class AppserviceJoinRoomStrategy {
+    constructor(underlyingStrategy, appservice) {
+        this.underlyingStrategy = underlyingStrategy;
+        this.appservice = appservice;
+    }
+    async joinRoom(roomIdOrAlias, userId, apiCall) {
+        try {
+            // First just try joining via the apiCall
+            return await apiCall(roomIdOrAlias);
+        }
+        catch (err) {
+            // If the user being joined is *not* the bridge bot, try and get the bridge bot to
+            // join them to the room.
+            if (userId !== this.appservice.botUserId) {
+                const client = this.appservice.botIntent.underlyingClient;
+                const roomId = await client.resolveRoom(roomIdOrAlias);
+                try {
+                    // First start with having the bridge bot invite the user to the room
+                    await client.inviteUser(userId, roomId);
+                }
+                catch (inviteErr) {
+                    // The invite failed - use the underlying join strategy to join the room, just in case.
+                    // If there's no join strategy, we want to fall through to an error.
+                    if (this.underlyingStrategy)
+                        return this.underlyingStrategy.joinRoom(roomId, userId, apiCall);
+                    throw inviteErr;
+                }
+                // The invite succeeded - use the underlying join strategy to join the room or just call use
+                // the apiCall if no strategy exists. We are expecting success.
+                if (this.underlyingStrategy)
+                    return this.underlyingStrategy.joinRoom(roomId, userId, apiCall);
+                else
+                    return apiCall(roomId);
+            }
+            else if (this.underlyingStrategy) {
+                // If the user being joined *is* the bridge bot, try and use the join strategy to join.
+                return this.underlyingStrategy.joinRoom(roomIdOrAlias, userId, apiCall);
+            }
+            // Finally, if all else fails, throw.
+            throw err;
+        }
+    }
+}
+exports.AppserviceJoinRoomStrategy = AppserviceJoinRoomStrategy;
+//# sourceMappingURL=AppserviceJoinRoomStrategy.js.map

package/lib/strategies/AppserviceJoinRoomStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AppserviceJoinRoomStrategy.js","sourceRoot":"","sources":["../../src/strategies/AppserviceJoinRoomStrategy.ts"],"names":[],"mappings":";;;AAGA;;;;;GAKG;AACH,MAAa,0BAA0B;IACnC,YAAoB,kBAAqC,EAAU,UAAsB;QAArE,uBAAkB,GAAlB,kBAAkB,CAAmB;QAAU,eAAU,GAAV,UAAU,CAAY;IACzF,CAAC;IAEM,KAAK,CAAC,QAAQ,CAAC,aAAqB,EAAE,MAAc,EAAE,OAAyD;QAClH,IAAI,CAAC;YACD,yCAAyC;YACzC,OAAO,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC;QACxC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACX,kFAAkF;YAClF,yBAAyB;YACzB,IAAI,MAAM,KAAK,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,CAAC;gBACvC,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,gBAAgB,CAAC;gBAC1D,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC;gBACvD,IAAI,CAAC;oBACD,qEAAqE;oBACrE,MAAM,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;gBAC5C,CAAC;gBAAC,OAAO,SAAS,EAAE,CAAC;oBACjB,uFAAuF;oBACvF,oEAAoE;oBACpE,IAAI,IAAI,CAAC,kBAAkB;wBAAE,OAAO,IAAI,CAAC,kBAAkB,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;oBAC9F,MAAM,SAAS,CAAC;gBACpB,CAAC;gBAED,4FAA4F;gBAC5F,+DAA+D;gBAC/D,IAAI,IAAI,CAAC,kBAAkB;oBAAE,OAAO,IAAI,CAAC,kBAAkB,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;;oBACzF,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC;YAChC,CAAC;iBAAM,IAAI,IAAI,CAAC,kBAAkB,EAAE,CAAC;gBACjC,uFAAuF;gBACvF,OAAO,IAAI,CAAC,kBAAkB,CAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;YAC5E,CAAC;YAED,qCAAqC;YACrC,MAAM,GAAG,CAAC;QACd,CAAC;IACL,CAAC;CACJ;AArCD,gEAqCC"}

package/lib/strategies/JoinRoomStrategy.d.ts

@@ -0,0 +1,11 @@
+export interface IJoinRoomStrategy {
+    joinRoom(roomIdOrAlias: string, userId: string, apiCall: (targetRoomIdOrAlias: string) => Promise<string>): Promise<string>;
+}
+/**
+ * A join strategy that keeps trying to join the room on a set interval.
+ * @category Join strategies
+ */
+export declare class SimpleRetryJoinStrategy implements IJoinRoomStrategy {
+    private schedule;
+    joinRoom(roomIdOrAlias: string, userId: string, apiCall: (targetRoomIdOrAlias: string) => Promise<string>): Promise<string>;
+}

package/lib/strategies/JoinRoomStrategy.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SimpleRetryJoinStrategy = void 0;
+const __1 = require("..");
+/**
+ * A join strategy that keeps trying to join the room on a set interval.
+ * @category Join strategies
+ */
+class SimpleRetryJoinStrategy {
+    constructor() {
+        // Note: The schedule must not have duplicate values to avoid problems in positioning.
+        this.schedule = [
+            0, // Right away
+            1000, // 1 second
+            30 * 1000, // 30 seconds
+            5 * 60 * 1000, // 5 minutes
+            15 * 60 * 1000, // 15 minutes
+        ];
+    }
+    joinRoom(roomIdOrAlias, userId, apiCall) {
+        let currentSchedule = this.schedule[0];
+        const doJoin = () => waitPromise(currentSchedule).then(() => apiCall(roomIdOrAlias));
+        const errorHandler = err => {
+            __1.LogService.error("SimpleRetryJoinStrategy", (0, __1.extractRequestError)(err));
+            const idx = this.schedule.indexOf(currentSchedule);
+            if (idx === this.schedule.length - 1) {
+                __1.LogService.warn("SimpleRetryJoinStrategy", "Failed to join room " + roomIdOrAlias);
+                return Promise.reject(err);
+            }
+            else {
+                currentSchedule = this.schedule[idx + 1];
+                return doJoin().catch(errorHandler);
+            }
+        };
+        return doJoin().catch(errorHandler);
+    }
+}
+exports.SimpleRetryJoinStrategy = SimpleRetryJoinStrategy;
+function waitPromise(interval) {
+    return new Promise((resolve, reject) => {
+        setTimeout(resolve, interval);
+    });
+}
+//# sourceMappingURL=JoinRoomStrategy.js.map

package/lib/strategies/JoinRoomStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"JoinRoomStrategy.js","sourceRoot":"","sources":["../../src/strategies/JoinRoomStrategy.ts"],"names":[],"mappings":";;;AAAA,0BAAqD;AAMrD;;;GAGG;AACH,MAAa,uBAAuB;IAApC;QACI,sFAAsF;QAC9E,aAAQ,GAAG;YACf,CAAC,EAAe,aAAa;YAC7B,IAAI,EAAY,WAAW;YAC3B,EAAE,GAAG,IAAI,EAAO,aAAa;YAC7B,CAAC,GAAG,EAAE,GAAG,IAAI,EAAG,YAAY;YAC5B,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,aAAa;SAChC,CAAC;IAoBN,CAAC;IAlBU,QAAQ,CAAC,aAAqB,EAAE,MAAc,EAAE,OAAyD;QAC5G,IAAI,eAAe,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;QAEvC,MAAM,MAAM,GAAG,GAAG,EAAE,CAAC,WAAW,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC;QACrF,MAAM,YAAY,GAAG,GAAG,CAAC,EAAE;YACvB,cAAU,CAAC,KAAK,CAAC,yBAAyB,EAAE,IAAA,uBAAmB,EAAC,GAAG,CAAC,CAAC,CAAC;YACtE,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;YACnD,IAAI,GAAG,KAAK,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACnC,cAAU,CAAC,IAAI,CAAC,yBAAyB,EAAE,sBAAsB,GAAG,aAAa,CAAC,CAAC;gBACnF,OAAO,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC/B,CAAC;iBAAM,CAAC;gBACJ,eAAe,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;gBACzC,OAAO,MAAM,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;YACxC,CAAC;QACL,CAAC,CAAC;QAEF,OAAO,MAAM,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IACxC,CAAC;CACJ;AA5BD,0DA4BC;AAED,SAAS,WAAW,CAAC,QAAgB;IACjC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACnC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;AACP,CAAC"}

package/package.json

@@ -1,6 +1,138 @@
 {
   "name": "@jeongsu816/matrix-bot-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.8.1",
+  "description": "Fork of matrix-bot-sdk with cross-signing, secret storage and dependency security fixes",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jeongsu816/matrix-bot-sdk.git"
+  },
+  "author": "turt2live",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/jeongsu816/matrix-bot-sdk/issues"
+  },
+  "homepage": "https://github.com/jeongsu816/matrix-bot-sdk#readme",
+  "scripts": {
+    "prepublishOnly": "npm run build",
+    "docs": "jsdoc -c jsdoc.json -P package.json -u docs/tutorials",
+    "build": "tsc --listEmittedFiles -p tsconfig-release.json",
+    "lint": "eslint \"{src,test,examples}/**/*.ts\"",
+    "lint:fix": "eslint \"{src,test,examples}/**/*.ts\" --fix",
+    "test": "jest",
+    "build:examples": "tsc -p tsconfig-examples.json",
+    "example:bot": "npm run build:examples && node lib/examples/bot.js",
+    "example:appservice": "npm run build:examples && node lib/examples/appservice.js",
+    "example:login_register": "npm run build:examples && node lib/examples/login_register.js",
+    "example:encryption_bot": "npm run build:examples && node lib/examples/encryption_bot.js",
+    "example:encryption_appservice": "npm run build:examples && node lib/examples/encryption_appservice.js"
+  },
+  "main": "./lib/index.js",
+  "typings": "./lib/index.d.ts",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "keywords": [
+    "matrix",
+    "bot",
+    "sdk",
+    "js",
+    "ts",
+    "node",
+    "helpers",
+    "snippets",
+    "chat",
+    "modules",
+    "bot-sdk",
+    "appservices"
+  ],
+  "files": [
+    "src/*",
+    "lib/*",
+    "scripts/*",
+    "tsconfig.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@matrix-org/matrix-sdk-crypto-nodejs": "0.6.1",
+    "@types/express": "^4.17.20",
+    "another-json": "^0.2.0",
+    "async-lock": "^1.4.0",
+    "chalk": "4",
+    "express": "^4.18.2",
+    "glob-to-regexp": "^0.4.1",
+    "hash.js": "^1.1.7",
+    "html-to-text": "^9.0.5",
+    "htmlencode": "^0.0.4",
+    "lowdb": "1",
+    "lru-cache": "^10.0.1",
+    "mkdirp": "^3.0.1",
+    "morgan": "^1.10.0",
+    "postgres": "^3.4.1",
+    "request": "npm:@cypress/request@^4.0.1",
+    "sanitize-html": "^2.18.1"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.28.6",
+    "@babel/eslint-parser": "^7.28.6",
+    "@babel/eslint-plugin": "^7.27.1",
+    "@eslint/eslintrc": "^3.3.3",
+    "@eslint/js": "^9.39.2",
+    "@stylistic/eslint-plugin": "^5.7.0",
+    "@testcontainers/postgresql": "^10.2.2",
+    "@types/async-lock": "^1.4.1",
+    "@types/jest": "^30.0.0",
+    "@types/lowdb": "^1.0.14",
+    "@types/mocha": "^10.0.3",
+    "@types/node": "22",
+    "@types/request-promise": "^4.1.51",
+    "@types/sanitize-html": "^2.9.3",
+    "@types/simple-mock": "^0.8.4",
+    "@typescript-eslint/eslint-plugin": "^8.53.0",
+    "@typescript-eslint/parser": "^8.53.0",
+    "better-docs": "^2.7.3",
+    "eslint": "^9.39.2",
+    "eslint-config-google": "^0.14.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-deprecate": "^0.8.7",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-matrix-org": "^3.0.0",
+    "eslint-plugin-unicorn": "^62.0.0",
+    "get-port": "5",
+    "globals": "^17.0.0",
+    "jest": "^30.2.0",
+    "jsdoc": "^4.0.5",
+    "matrix-mock-request": "^2.6.0",
+    "request-promise": "^4.2.6",
+    "simple-mock": "^0.8.0",
+    "taffydb": "^2.7.3",
+    "testcontainers": "^10.2.2",
+    "tmp": "^0.2.1",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.9.3"
+  },
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "testMatch": [
+      "<rootDir>/test/**/*Test.ts"
+    ],
+    "transform": {
+      "^.+\\.ts$": "ts-jest",
+      "^.+\\.js$": [
+        "ts-jest",
+        {
+          "tsconfig": {
+            "allowJs": true,
+            "module": "commonjs"
+          },
+          "isolatedModules": true
+        }
+      ]
+    },
+    "transformIgnorePatterns": [
+      "/node_modules/(?!(htmlparser2|domhandler|domutils|dom-serializer|domelementtype|entities)/)[^/]+/(?!.*node_modules)"
+    ]
+  }
+}

package/src/AdminApis.ts

@@ -0,0 +1,60 @@
+import { MatrixClient } from "./MatrixClient";
+import { SynapseAdminApis } from "./SynapseAdminApis";
+
+/**
+ * Whois information about a user.
+ * See https://matrix.org/docs/spec/client_server/r0.5.0#get-matrix-client-r0-admin-whois-userid for more information.
+ * @category Admin APIs
+ */
+export interface WhoisInfo {
+    user_id: string;
+    devices: {
+        [device_id: string]: {
+            sessions: [{
+                connections: WhoisConnectionInfo[];
+            }];
+        };
+    };
+}
+
+interface WhoisConnectionInfo {
+    /**
+     * Most recently seen IP address of the session.
+     */
+    ip: string;
+
+    /**
+     * Unix timestamp that the session was last active.
+     */
+    last_seen: number;
+
+    /**
+     * User agent string last seen in the session.
+     */
+    user_agent: string;
+}
+
+/**
+ * Access to various administrative APIs.
+ * @category Admin APIs
+ */
+export class AdminApis {
+    constructor(private client: MatrixClient) {
+    }
+
+    /**
+     * Gets access to the Synapse administrative APIs object.
+     */
+    public get synapse(): SynapseAdminApis {
+        return new SynapseAdminApis(this.client);
+    }
+
+    /**
+     * Gets information about a particular user.
+     * @param {string} userId the user ID to lookup
+     * @returns {Promise<WhoisInfo>} resolves to the whois information
+     */
+    public whoisUser(userId: string): Promise<WhoisInfo> {
+        return this.client.doRequest("GET", "/_matrix/client/v3/admin/whois/" + encodeURIComponent(userId));
+    }
+}

package/src/DMs.ts

@@ -0,0 +1,164 @@
+import { MatrixClient } from "./MatrixClient";
+import { EncryptionAlgorithm } from "./models/Crypto";
+import { LogService } from "./logging/LogService";
+
+/**
+ * Handles DM (direct messages) matching between users. Note that bots which
+ * existed prior to this might not have DM rooms populated correctly - the
+ * account data can be populated externally and that will be reflected here.
+ *
+ * Note that DM status is persisted across all access tokens for a user and
+ * is not persisted with the regular stores. The DM map is instead tracked
+ * on the homeserver as account data and thus survives the bot's own storage
+ * being wiped.
+ * @category Utilities
+ */
+export class DMs {
+    private cached = new Map<string, string[]>();
+    private ready: Promise<void>;
+
+    /**
+     * Creates a new DM map.
+     * @param {MatrixClient} client The client the DM map is for.
+     */
+    public constructor(private client: MatrixClient) {
+        this.client.on("account_data", (ev) => {
+            if (ev['type'] !== 'm.direct') return;
+
+            // noinspection JSIgnoredPromiseFromCall
+            this.updateFromAccountData();
+        });
+        this.client.on("room.invite", (rid, ev) => this.handleInvite(rid, ev));
+    }
+
+    private async updateFromAccountData() {
+        // Don't trust the sync update
+        let map = {};
+        try {
+            map = await this.client.getAccountData("m.direct");
+        } catch (e) {
+            if (e.body?.errcode !== "M_NOT_FOUND" && e.statusCode !== 404) {
+                LogService.warn("DMs", "Error getting m.direct account data: ", e);
+            }
+        }
+
+        this.cached = new Map<string, string[]>();
+
+        for (const [userId, roomIds] of Object.entries(map)) {
+            this.cached.set(userId, roomIds as string[]);
+        }
+    }
+
+    private async handleInvite(roomId: string, ev: any) {
+        if (ev['content']?.['is_direct'] === true) {
+            const userId = ev['sender'];
+            if (!this.cached.has(userId)) this.cached.set(userId, []);
+            this.cached.set(userId, [roomId, ...this.cached.get(userId)]);
+            await this.persistCache();
+        }
+    }
+
+    private async persistCache() {
+        const obj: Record<string, string[]> = {};
+        for (const [uid, rids] of this.cached.entries()) {
+            obj[uid] = rids;
+        }
+        await this.client.setAccountData("m.direct", obj);
+    }
+
+    private async fixDms(userId: string) {
+        const currentRooms = this.cached.get(userId);
+        if (!currentRooms) return;
+
+        const toKeep: string[] = [];
+        for (const roomId of currentRooms) {
+            try {
+                const members = await this.client.getAllRoomMembers(roomId);
+                const joined = members.filter(m => m.effectiveMembership === "join" || m.effectiveMembership === "invite");
+                if (joined.some(m => m.membershipFor === userId)) {
+                    toKeep.push(roomId);
+                }
+            } catch (e) {
+                LogService.warn("DMs", `Unable to check ${roomId} for room members - assuming invalid DM`);
+            }
+        }
+
+        if (toKeep.length === currentRooms.length) return; // no change
+
+        if (toKeep.length > 0) {
+            this.cached.set(userId, toKeep);
+        } else {
+            this.cached.delete(userId);
+        }
+        await this.persistCache();
+    }
+
+    /**
+     * Forces an update of the DM cache.
+     * @returns {Promise<void>} Resolves when complete.
+     */
+    public async update(): Promise<void> {
+        await this.ready; // finish the existing call if present
+        this.ready = this.updateFromAccountData();
+        return this.ready;
+    }
+
+    /**
+     * Gets or creates a DM with a given user. If a DM needs to be created, it will
+     * be created as an encrypted DM (if both the MatrixClient and target user support
+     * crypto). Otherwise, the createFn can be used to override the call. Note that
+     * when creating a DM room the room should have `is_direct: true` set.
+     * @param {string} userId The user ID to get/create a DM for.
+     * @param {Function} createFn Optional function to use to create the room. Resolves
+     * to the created room ID.
+     * @returns {Promise<string>} Resolves to the DM room ID.
+     */
+    public async getOrCreateDm(userId: string, createFn?: (targetUserId: string) => Promise<string>): Promise<string> {
+        await this.ready;
+        await this.fixDms(userId);
+        const rooms = this.cached.get(userId);
+        if (rooms?.length) return rooms[0];
+
+        let roomId: string;
+        if (createFn) {
+            roomId = await createFn(userId);
+        } else {
+            let hasKeys = false;
+            if (!!this.client.crypto) {
+                const keys = await this.client.getUserDevices([userId]);
+                const userKeys = keys?.device_keys?.[userId] ?? {};
+                hasKeys = Object.values(userKeys).filter(device => Object.values(device).length > 0).length > 0;
+            }
+            roomId = await this.client.createRoom({
+                invite: [userId],
+                is_direct: true,
+                preset: "trusted_private_chat",
+                initial_state: hasKeys ? [{
+                    type: "m.room.encryption",
+                    state_key: "",
+                    content: { algorithm: EncryptionAlgorithm.MegolmV1AesSha2 },
+                }] : [],
+            });
+        }
+
+        if (!this.cached.has(userId)) this.cached.set(userId, []);
+        this.cached.set(userId, [roomId, ...this.cached.get(userId)]);
+        await this.persistCache();
+
+        return roomId;
+    }
+
+    /**
+     * Determines if a given room is a DM according to the cache.
+     * @param {string} roomId The room ID.
+     * @returns {boolean} True if the room ID is a cached DM room ID.
+     */
+    public isDm(roomId: string): boolean {
+        for (const val of this.cached.values()) {
+            if (val.includes(roomId)) {
+                return true;
+            }
+        }
+        return false;
+    }
+}

package/src/IFilter.ts

@@ -0,0 +1,7 @@
+/**
+ * Sync filter information.
+ */
+export interface IFilterInfo {
+    id: number;
+    filter: any; // TODO: Define what a filter is
+}

package/src/MatrixAuth.ts

@@ -0,0 +1,129 @@
+import { MatrixClient } from "./MatrixClient";
+
+/**
+ * Functions for interacting with Matrix prior to having an access token. Intended
+ * to be used for logging in/registering to get a MatrixClient instance.
+ *
+ * By design, this limits the options used to create the MatrixClient. To specify
+ * custom elements to the client, get the access token from the returned client
+ * and create a new MatrixClient instance. Due to the nature of Matrix, it is
+ * also recommended to use the homeserverUrl from the generated MatrixClient as
+ * it may be different from that given to the MatrixAuth class.
+ */
+export class MatrixAuth {
+    /**
+     * Creates a new MatrixAuth class for creating a MatrixClient
+     * @param {string} homeserverUrl The homeserver URL to authenticate against.
+     */
+    public constructor(private homeserverUrl: string) {
+        // nothing to do
+    }
+
+    /**
+     * Generate a client with no access token so we can reuse the doRequest
+     * logic already written.
+     */
+    private createTemplateClient(): MatrixClient {
+        return new MatrixClient(this.homeserverUrl, "");
+    }
+
+    /**
+     * Performs simple registration using a password for the account. This will
+     * assume the server supports the m.login.password flow for registration, and
+     * will attempt to complete only that stage. The caller is expected to determine
+     * if the homeserver supports registration prior to invocation.
+     * @param {string} localpart The localpart (username) to register
+     * @param {string} password The password to register with
+     * @param {string} deviceName The name of the newly created device. Optional.
+     * @returns {Promise<MatrixClient>} Resolves to a logged-in MatrixClient
+     */
+    public async passwordRegister(localpart: string, password: string, deviceName?: string): Promise<MatrixClient> {
+        // First try and complete the stage without UIA in hopes the server is kind to us:
+        const body = {
+            username: localpart,
+            password: password,
+            initial_device_display_name: deviceName,
+        };
+
+        let response;
+
+        try {
+            response = await this.createTemplateClient().doRequest("POST", "/_matrix/client/v3/register", null, body);
+        } catch (e) {
+            if (e.statusCode === 401) {
+                if (typeof (e.body) === "string") e.body = JSON.parse(e.body);
+                if (!e.body) throw new Error(JSON.stringify(Object.keys(e)));
+
+                // 401 means we need to do UIA, so try and complete a stage
+                const sessionId = e.body['session'];
+                const expectedFlow = ["m.login.dummy"];
+
+                let hasFlow = false;
+                for (const flow of e.body['flows']) {
+                    const stages = flow['stages'];
+                    if (stages.length !== expectedFlow.length) continue;
+
+                    let stagesMatch = true;
+                    for (let i = 0; i < stages.length; i++) {
+                        if (stages[i] !== expectedFlow[i]) {
+                            stagesMatch = false;
+                            break;
+                        }
+                    }
+
+                    if (stagesMatch) {
+                        hasFlow = true;
+                        break;
+                    }
+                }
+
+                if (!hasFlow) throw new Error("Failed to find appropriate login flow in User-Interactive Authentication");
+
+                body['auth'] = {
+                    type: expectedFlow[0], // HACK: We assume we only have one entry here
+                    session: sessionId,
+                };
+                response = await this.createTemplateClient().doRequest("POST", "/_matrix/client/v3/register", null, body);
+            }
+        }
+
+        if (!response) throw new Error("Failed to register");
+
+        const accessToken = response['access_token'];
+        if (!accessToken) throw new Error("No access token returned");
+
+        return new MatrixClient(this.homeserverUrl, accessToken);
+    }
+
+    /**
+     * Performs simple password login with the homeserver. The caller is
+     * expected to confirm if the homeserver supports this login flow prior
+     * to invocation.
+     * @param {string} username The username (localpart or user ID) to log in with
+     * @param {string} password The password for the account
+     * @param {string} deviceName The name of the newly created device. Optional.
+     * @returns {Promise<MatrixClient>} Resolves to a logged-in MatrixClient
+     */
+    public async passwordLogin(username: string, password: string, deviceName?: string): Promise<MatrixClient> {
+        const body = {
+            type: "m.login.password",
+            identifier: {
+                type: "m.id.user",
+                user: username,
+            },
+            password: password,
+            initial_device_display_name: deviceName,
+        };
+
+        const response = await this.createTemplateClient().doRequest("POST", "/_matrix/client/v3/login", null, body);
+        const accessToken = response["access_token"];
+        if (!accessToken) throw new Error("Expected access token in response - got nothing");
+
+        let homeserverUrl = this.homeserverUrl;
+        if (response['well_known'] && response['well_known']['m.homeserver'] && response['well_known']['m.homeserver']['base_url']) {
+            homeserverUrl = response['well_known']['m.homeserver']['base_url'];
+        }
+
+        return new MatrixClient(homeserverUrl, accessToken);
+    }
+}