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

package/src/helpers/MatrixGlob.ts

@@ -0,0 +1,38 @@
+import * as globToRegexp from "glob-to-regexp";
+
+/**
+ * Represents a common Matrix glob. This is commonly used
+ * for server ACLs and similar functions.
+ * @category Utilities
+ */
+export class MatrixGlob {
+    /**
+     * The regular expression which represents this glob.
+     */
+    public readonly regex: RegExp;
+
+    /**
+     * Creates a new Matrix Glob
+     * @param {string} glob The glob to convert. Eg: "*.example.org"
+     */
+    constructor(glob: string) {
+        const globRegex = globToRegexp(glob, {
+            extended: false,
+            globstar: false,
+        });
+
+        // We need to convert `?` manually because globToRegexp's extended mode
+        // does more than we want it to.
+        const replaced = globRegex.toString().replace(/\\\?/g, ".");
+        this.regex = new RegExp(replaced.substring(1, replaced.length - 1));
+    }
+
+    /**
+     * Tests the glob against a value, returning true if it matches.
+     * @param {string} val The value to test.
+     * @returns {boolean} True if the value matches the glob, false otherwise.
+     */
+    public test(val: string): boolean {
+        return this.regex.test(val);
+    }
+}

package/src/helpers/MentionPill.ts

@@ -0,0 +1,95 @@
+import { MatrixClient } from "../MatrixClient";
+import { Permalinks } from "./Permalinks";
+import { extractRequestError, LogService } from "..";
+
+/**
+ * Represents a system for generating a mention pill for an entity.
+ * @category Utilities
+ */
+export class MentionPill {
+    private constructor(private entityPermalink: string, private displayName: string) {
+    }
+
+    /**
+     * The HTML component of the mention.
+     */
+    public get html(): string {
+        return `<a href="${this.entityPermalink}">${this.displayName}</a>`;
+    }
+
+    /**
+     * The plain text component of the mention.
+     */
+    public get text(): string {
+        return this.displayName;
+    }
+
+    /**
+     * Creates a new mention for a user in an optional room.
+     * @param {string} userId The user ID the mention is for.
+     * @param {String} inRoomId Optional room ID the user is being mentioned in, for the aesthetics of the mention.
+     * @param {MatrixClient} client Optional client for creating a more pleasing mention.
+     * @returns {Promise<MentionPill>} Resolves to the user's mention.
+     */
+    public static async forUser(userId: string, inRoomId: string = null, client: MatrixClient = null): Promise<MentionPill> {
+        const permalink = Permalinks.forUser(userId);
+
+        let displayName = userId;
+        try {
+            if (client) {
+                let profile = null;
+
+                if (inRoomId) {
+                    profile = await client.getRoomStateEvent(inRoomId, "m.room.member", userId);
+                }
+                if (!profile) {
+                    profile = await client.getUserProfile(userId);
+                }
+
+                if (profile['displayname']) {
+                    displayName = profile['displayname'];
+                }
+            }
+        } catch (e) {
+            LogService.warn("MentionPill", "Error getting profile", extractRequestError(e));
+        }
+
+        return new MentionPill(permalink, displayName);
+    }
+
+    /**
+     * Creates a new mention for a room (not @room, but the room itself to be linked).
+     * @param {string} roomIdOrAlias The room ID or alias to mention.
+     * @param {MatrixClient} client Optional client for creating a more pleasing mention.
+     * @returns {Promise<MentionPill>} Resolves to the room's mention.
+     */
+    public static async forRoom(roomIdOrAlias: string, client: MatrixClient = null): Promise<MentionPill> {
+        let permalink = Permalinks.forRoom(roomIdOrAlias);
+        let displayProp = roomIdOrAlias;
+
+        try {
+            if (client) {
+                const roomId = await client.resolveRoom(roomIdOrAlias);
+                const canonicalAlias = await client.getRoomStateEvent(roomId, "m.room.canonical_alias", "");
+                if (canonicalAlias?.alias) {
+                    displayProp = canonicalAlias.alias;
+                    permalink = Permalinks.forRoom(displayProp);
+                }
+            }
+        } catch (e) {
+            LogService.warn("MentionPill", "Error getting room information", extractRequestError(e));
+        }
+
+        return new MentionPill(permalink, displayProp);
+    }
+
+    /**
+     * Creates a mention from static information.
+     * @param {string} userId The user ID the mention is for.
+     * @param {string} displayName The user's display name.
+     * @returns {MentionPill} The mention for the user.
+     */
+    public static withDisplayName(userId: string, displayName: string): MentionPill {
+        return new MentionPill(Permalinks.forUser(userId), displayName || userId);
+    }
+}

package/src/helpers/Permalinks.ts

@@ -0,0 +1,101 @@
+/**
+ * The parts of a permalink.
+ * @see Permalinks
+ * @category Utilities
+ */
+export interface PermalinkParts {
+    /**
+     * The room ID or alias the permalink references. May be undefined.
+     */
+    roomIdOrAlias: string;
+
+    /**
+     * The user ID the permalink references. May be undefined.
+     */
+    userId: string;
+
+    /**
+     * The event ID the permalink references. May be undefined.
+     */
+    eventId: string;
+
+    /**
+     * The servers the permalink is routed through. May be undefined or empty.
+     */
+    viaServers: string[];
+}
+
+/**
+ * Functions for handling permalinks
+ * @category Utilities
+ */
+export class Permalinks {
+    private constructor() {
+    }
+
+    // TODO: Encode permalinks
+
+    private static encodeViaArgs(servers: string[]): string {
+        if (!servers || !servers.length) return "";
+
+        return `?via=${servers.join("&via=")}`;
+    }
+
+    /**
+     * Creates a room permalink.
+     * @param {string} roomIdOrAlias The room ID or alias to create a permalink for.
+     * @param {string[]} viaServers The servers to route the permalink through.
+     * @returns {string} A room permalink.
+     */
+    public static forRoom(roomIdOrAlias: string, viaServers: string[] = []): string {
+        return `https://matrix.to/#/${roomIdOrAlias}${Permalinks.encodeViaArgs(viaServers)}`;
+    }
+
+    /**
+     * Creates a user permalink.
+     * @param {string} userId The user ID to create a permalink for.
+     * @returns {string} A user permalink.
+     */
+    public static forUser(userId: string): string {
+        return `https://matrix.to/#/${userId}`;
+    }
+
+    /**
+     * Creates an event permalink.
+     * @param {string} roomIdOrAlias The room ID or alias to create a permalink in.
+     * @param {string} eventId The event ID to reference in the permalink.
+     * @param {string[]} viaServers The servers to route the permalink through.
+     * @returns {string} An event permalink.
+     */
+    public static forEvent(roomIdOrAlias: string, eventId: string, viaServers: string[] = []): string {
+        return `https://matrix.to/#/${roomIdOrAlias}/${eventId}${Permalinks.encodeViaArgs(viaServers)}`;
+    }
+
+    /**
+     * Parses a permalink URL into usable parts.
+     * @param {string} matrixTo The matrix.to URL to parse.
+     * @returns {PermalinkParts} The parts of the permalink.
+     */
+    public static parseUrl(matrixTo: string): PermalinkParts {
+        const matrixToRegexp = /^https:\/\/matrix\.to\/#\/(?<entity>[^/?]+)\/?(?<eventId>[^?]+)?(?<query>\?[^]*)?$/;
+
+        const url = matrixToRegexp.exec(matrixTo)?.groups;
+        if (!url) {
+            throw new Error("Not a valid matrix.to URL");
+        }
+
+        const entity = decodeURIComponent(url.entity);
+        if (entity[0] === '@') {
+            return { userId: entity, roomIdOrAlias: undefined, eventId: undefined, viaServers: undefined };
+        } else if (entity[0] === '#' || entity[0] === '!') {
+            return {
+                userId: undefined,
+                roomIdOrAlias: entity,
+                eventId: url.eventId && decodeURIComponent(url.eventId),
+                viaServers: new URLSearchParams(url.query).getAll('via'),
+            };
+        } else {
+            throw new Error("Unexpected entity");
+        }
+    }
+}

package/src/helpers/ProfileCache.ts

@@ -0,0 +1,119 @@
+import * as LRU from "lru-cache";
+
+import { extractRequestError, LogService, MatrixClient, MatrixProfile } from "..";
+import { MembershipEvent } from "../models/events/MembershipEvent";
+import { Appservice } from "../appservice/Appservice";
+
+type CacheKey = `${string}@${string | '<none>'}`;
+
+/**
+ * Functions for avoiding calls to profile endpoints. Useful for bots when
+ * people are mentioned often or bridges which need profile information
+ * often.
+ * @category Utilities
+ */
+export class ProfileCache {
+    private cache: LRU.LRUCache<CacheKey, MatrixProfile>;
+
+    /**
+     * Creates a new profile cache.
+     * @param {number} maxEntries The maximum number of entries to cache.
+     * @param {number} maxAgeMs The maximum age of an entry in milliseconds.
+     * @param {MatrixClient} client The client to use to get profile updates.
+     */
+    constructor(maxEntries: number, maxAgeMs: number, private client: MatrixClient) {
+        this.cache = new LRU.LRUCache({
+            max: maxEntries,
+            ttl: maxAgeMs,
+        });
+    }
+
+    private getCacheKey(userId: string, roomId: string | null): CacheKey {
+        return `${userId}@${roomId || '<none>'}`;
+    }
+
+    /**
+     * Watch for profile changes to cached entries with the provided client. The
+     * same client will also be used to update the user's profile in the cache.
+     * @param {MatrixClient} client The client to watch for profile changes with.
+     */
+    public watchWithClient(client: MatrixClient) {
+        client.on("room.event", async (roomId: string, event: string) => {
+            if (!event['state_key'] || !event['content'] || event['type'] !== 'm.room.member') return;
+            await this.tryUpdateProfile(roomId, new MembershipEvent(event), client);
+        });
+    }
+
+    /**
+     * Watch for profile changes to cached entries with the provided application
+     * service. The clientFn will be called to get the relevant client for any
+     * updates. If the clientFn is null, the appservice's bot user will be used.
+     * The clientFn takes two arguments: the user ID being updated and the room ID
+     * they are being updated in (shouldn't be null). The return value should be the
+     * MatrixClient to use, or null to use the appservice's bot client. The same
+     * client will be used to update the user's general profile, if that profile
+     * is cached.
+     * @param {Appservice} appservice The application service to watch for profile changes with.
+     * @param {Function} clientFn The function to use to acquire profile updates with. If null, the appservice's bot client will be used.
+     */
+    public watchWithAppservice(appservice: Appservice, clientFn: (userId: string, roomId: string) => MatrixClient = null) {
+        if (!clientFn) clientFn = () => appservice.botClient;
+        appservice.on("room.event", async (roomId: string, event: string) => {
+            if (!event['state_key'] || !event['content'] || event['type'] !== 'm.room.member') return;
+
+            const memberEvent = new MembershipEvent(event);
+            let client = clientFn(memberEvent.membershipFor, roomId);
+            if (!client) client = appservice.botClient;
+
+            await this.tryUpdateProfile(roomId, memberEvent, client);
+        });
+    }
+
+    /**
+     * Gets a profile for a user in optional room.
+     * @param {string} userId The user ID to get a profile for.
+     * @param {string|null} roomId Optional room ID to get a per-room profile for the user.
+     * @returns {Promise<MatrixProfile>} Resolves to the user's profile.
+     */
+    public async getUserProfile(userId: string, roomId: string = null): Promise<MatrixProfile> {
+        const cacheKey = this.getCacheKey(userId, roomId);
+        const cached = this.cache.get(cacheKey);
+        if (cached) return Promise.resolve(<MatrixProfile>cached);
+
+        const profile = await this.getUserProfileWith(userId, roomId, this.client);
+        this.cache.set(cacheKey, profile);
+        return profile;
+    }
+
+    private async getUserProfileWith(userId: string, roomId: string, client: MatrixClient): Promise<MatrixProfile> {
+        try {
+            if (roomId) {
+                const membership = await client.getRoomStateEvent(roomId, "m.room.member", userId);
+                return new MatrixProfile(userId, membership);
+            } else {
+                const profile = await client.getUserProfile(userId);
+                return new MatrixProfile(userId, profile);
+            }
+        } catch (e) {
+            LogService.warn("ProfileCache", "Non-fatal error getting user profile. They might not exist.");
+            LogService.warn("ProfileCache", extractRequestError(e));
+            return new MatrixProfile(userId, {});
+        }
+    }
+
+    private async tryUpdateProfile(roomId: string, memberEvent: MembershipEvent, client: MatrixClient) {
+        const roomCacheKey = this.getCacheKey(memberEvent.membershipFor, roomId);
+        const generalCacheKey = this.getCacheKey(memberEvent.membershipFor, null);
+
+        if (this.cache.has(roomCacheKey)) {
+            this.cache.set(roomCacheKey, new MatrixProfile(memberEvent.membershipFor, memberEvent.content));
+        }
+
+        // TODO: Try and figure out semantics for this updating.
+        // Large accounts could cause hammering on the profile endpoint, but hopefully it is cached by the server.
+        if (this.cache.has(generalCacheKey)) {
+            const profile = await this.getUserProfileWith(memberEvent.membershipFor, null, client);
+            this.cache.set(generalCacheKey, profile);
+        }
+    }
+}

package/src/helpers/RichReply.ts

@@ -0,0 +1,46 @@
+import * as sanitizeHtml from "sanitize-html";
+
+/**
+ * Helper for creating rich replies.
+ * @category Utilities
+ */
+export class RichReply {
+    private constructor() {
+    }
+
+    /**
+     * Generates the event content required to reply to the provided event with the
+     * provided text.
+     * @param {string} roomId the room ID the event being replied to resides in
+     * @param {any} event the event to reply to
+     * @param {string} withText the plain text to reply with
+     * @param {string} withHtml the HTML to reply with
+     * @returns {any} the content of the event representing the reply
+     */
+    public static createFor(roomId: string, event: any, withText: string, withHtml: string): any {
+        const originalBody = (event["content"] ? event["content"]["body"] : "") || "";
+        let originalHtml = (event["content"] ? event["content"]["formatted_body"] : "") || null;
+        if (originalHtml === null) {
+            originalHtml = sanitizeHtml(originalBody);
+        }
+
+        const fallbackText = "> <" + event["sender"] + "> " + originalBody.split("\n").join("\n> ");
+        const fallbackHtml = "<mx-reply><blockquote>"
+            + `<a href="https://matrix.to/#/${roomId}/${event["event_id"]}">In reply to</a> `
+            + `<a href="https://matrix.to/#/${event["sender"]}">${event["sender"]}</a>`
+            + "<br />" + originalHtml
+            + "</blockquote></mx-reply>";
+
+        return {
+            "m.relates_to": {
+                "m.in_reply_to": {
+                    "event_id": event["event_id"],
+                },
+            },
+            "msgtype": "m.text", // for those who just want to send the reply as-is
+            "body": fallbackText + "\n\n" + withText,
+            "format": "org.matrix.custom.html",
+            "formatted_body": fallbackHtml + withHtml,
+        };
+    }
+}

package/src/helpers/UnpaddedBase64.ts

@@ -0,0 +1,44 @@
+/**
+ * Unpadded Base64 utilities for Matrix.
+ * @category Utilities
+ */
+export class UnpaddedBase64 {
+    private constructor() {
+    }
+
+    /**
+     * Encodes a buffer to Unpadded Base64
+     * @param {Buffer} buf The buffer to encode.
+     * @returns {string} The Unpadded Base64 string
+     */
+    public static encodeBuffer(buf: Buffer): string {
+        return buf.toString('base64').replace(/[=]*$/g, '');
+    }
+
+    /**
+     * Encodes a string to Unpadded Base64
+     * @param {string} str The string to encode.
+     * @returns {string} The Unpadded Base64 string
+     */
+    public static encodeString(str: string): string {
+        return UnpaddedBase64.encodeBuffer(Buffer.from(str));
+    }
+
+    /**
+     * Encodes a buffer to Unpadded Base64 (URL Safe Edition)
+     * @param {Buffer} buf The buffer to encode.
+     * @returns {string} The Unpadded Base64 string
+     */
+    public static encodeBufferUrlSafe(buf: Buffer): string {
+        return UnpaddedBase64.encodeBuffer(buf).replace(/\+/g, '-').replace(/\//g, '_');
+    }
+
+    /**
+     * Encodes a string to Unpadded Base64 (URL Safe Edition)
+     * @param {string} str The string to encode.
+     * @returns {string} The Unpadded Base64 string
+     */
+    public static encodeStringUrlSafe(str: string): string {
+        return UnpaddedBase64.encodeBufferUrlSafe(Buffer.from(str));
+    }
+}

package/src/http.ts

@@ -0,0 +1,166 @@
+import { LogLevel, LogService } from "./logging/LogService";
+import { getRequestFn } from "./request";
+import { MatrixError } from "./models/MatrixError";
+
+let lastRequestId = 0;
+
+/**
+ * Performs a web request to a server.
+ * @category Unit testing
+ * @param {string} baseUrl The base URL to apply to the call.
+ * @param {"GET"|"POST"|"PUT"|"DELETE"} method The HTTP method to use in the request
+ * @param {string} endpoint The endpoint to call. For example: "/_matrix/client/v3/account/whoami"
+ * @param {any} qs The query string to send. Optional.
+ * @param {any} body The request body to send. Optional. Will be converted to JSON unless the type is a Buffer.
+ * @param {any} headers Additional headers to send in the request.
+ * @param {number} timeout The number of milliseconds to wait before timing out.
+ * @param {boolean} raw If true, the raw response will be returned instead of the response body.
+ * @param {string} contentType The content type to send. Only used if the `body` is a Buffer.
+ * @param {string} noEncoding Set to true to disable encoding, and return a Buffer. Defaults to false
+ * @returns {Promise<any>} Resolves to the response (body), rejected if a non-2xx status code was returned.
+ */
+export async function doHttpRequest(
+    baseUrl: string,
+    method: "GET" | "POST" | "PUT" | "DELETE",
+    endpoint: string,
+    qs = null,
+    body = null,
+    headers = {},
+    timeout = 60000,
+    raw = false,
+    contentType = "application/json",
+    noEncoding = false,
+): Promise<any> {
+    if (!endpoint.startsWith('/')) {
+        endpoint = '/' + endpoint;
+    }
+
+    const requestId = ++lastRequestId;
+    const url = baseUrl + endpoint;
+
+    // This is logged at info so that when a request fails people can figure out which one.
+    LogService.debug("MatrixHttpClient", "(REQ-" + requestId + ")", method + " " + url);
+
+    // Don't log the request unless we're in debug mode. It can be large.
+    if (LogService.level.includes(LogLevel.TRACE)) {
+        if (qs) LogService.trace("MatrixHttpClient", "(REQ-" + requestId + ")", "qs = " + JSON.stringify(qs));
+        if (body && !Buffer.isBuffer(body)) LogService.trace("MatrixHttpClient", "(REQ-" + requestId + ")", "body = " + JSON.stringify(redactObjectForLogging(body)));
+        if (body && Buffer.isBuffer(body)) LogService.trace("MatrixHttpClient", "(REQ-" + requestId + ")", "body = <Buffer>");
+    }
+
+    const params: { uri: string, [k: string]: any } = {
+        uri: url,
+        method: method,
+        qs: qs,
+        // If this is undefined, then a string will be returned. If it's null, a Buffer will be returned.
+        encoding: noEncoding === false ? undefined : null,
+        useQuerystring: true,
+        qsStringifyOptions: {
+            options: { arrayFormat: 'repeat' },
+        },
+        timeout: timeout,
+        headers: headers,
+        // Enable KeepAlive for HTTP
+        forever: true,
+    };
+
+    if (body) {
+        if (Buffer.isBuffer(body)) {
+            params.headers["Content-Type"] = contentType;
+            params.body = body;
+        } else {
+            params.headers["Content-Type"] = "application/json";
+            params.body = JSON.stringify(body);
+        }
+    }
+
+    const { response, resBody } = await new Promise<{ response: any, resBody: any }>((resolve, reject) => {
+        getRequestFn()(params, (err, res, rBody) => {
+            if (err) {
+                LogService.error("MatrixHttpClient", "(REQ-" + requestId + ")", err);
+                reject(err);
+                return;
+            }
+
+            if (typeof (rBody) === 'string') {
+                try {
+                    rBody = JSON.parse(rBody);
+                } catch (e) {
+                }
+            }
+
+            if (typeof (res.body) === 'string') {
+                try {
+                    res.body = JSON.parse(res.body);
+                } catch (e) {
+                }
+            }
+
+            resolve({ response: res, resBody: rBody });
+        });
+    });
+
+    const respIsBuffer = (response.body instanceof Buffer);
+
+    // Check for errors.
+    const errBody = response.body || resBody;
+    if (typeof (errBody) === "object" && 'errcode' in errBody) {
+        const redactedBody = respIsBuffer ? '<Buffer>' : redactObjectForLogging(errBody);
+        LogService.error("MatrixHttpClient", "(REQ-" + requestId + ")", redactedBody);
+        throw new MatrixError(errBody, response.statusCode);
+    }
+
+    // Don't log the body unless we're in debug mode. They can be large.
+    if (LogService.level.includes(LogLevel.TRACE)) {
+        const redactedBody = respIsBuffer ? '<Buffer>' : redactObjectForLogging(response.body);
+        LogService.trace("MatrixHttpClient", "(REQ-" + requestId + " RESP-H" + response.statusCode + ")", redactedBody);
+    }
+
+    if (response.statusCode < 200 || response.statusCode >= 300) {
+        const redactedBody = respIsBuffer ? '<Buffer>' : redactObjectForLogging(response.body);
+        LogService.error("MatrixHttpClient", "(REQ-" + requestId + ")", redactedBody);
+        throw response;
+    }
+    return raw ? response : resBody;
+}
+
+export function redactObjectForLogging(input: any): any {
+    if (!input) return input;
+
+    const fieldsToRedact = [
+        'access_token',
+        'password',
+        'new_password',
+    ];
+
+    const redactFn = (i) => {
+        if (!i) return i;
+
+        // Don't treat strings like arrays/objects
+        if (typeof i === 'string') return i;
+
+        if (Array.isArray(i)) {
+            const rebuilt = [];
+            for (const v of i) {
+                rebuilt.push(redactFn(v));
+            }
+            return rebuilt;
+        }
+
+        if (i instanceof Object) {
+            const rebuilt = {};
+            for (const key of Object.keys(i)) {
+                if (fieldsToRedact.includes(key)) {
+                    rebuilt[key] = '<redacted>';
+                } else {
+                    rebuilt[key] = redactFn(i[key]);
+                }
+            }
+            return rebuilt;
+        }
+
+        return i; // It's a primitive value
+    };
+
+    return redactFn(input);
+}