Feat: Add NodeJS E2EE TS example.

examples/crypto-node/.gitignore

@@ -0,0 +1,3 @@
+credentials.json
+lib
+localstorage

examples/crypto-node/.npmrc

@@ -0,0 +1 @@
+@matrix-org:registry=https://gitlab.matrix.org/api/v4/packages/npm/

examples/crypto-node/README.md

@@ -0,0 +1,76 @@
+## About
+
+This is a functional terminal app which allows you to see the room list for a user, join rooms, send messages and view room membership lists with E2EE enabled.
+
+## Install
+
+To try it out, you will need to create a credentials file: `credentials.json` in the root of this example folder and configure it for your `homeserver`, `access_token` and `user_id` like so:
+
+```json
+{
+	"userId": "@my_user:matrix.org",
+	"password": "my_password",
+	"baseUrl": "https://matrix.org"
+}
+```
+
+You may also copy `credentials.template.json` to `credentials.json` and just edit the fields.
+
+You then can install dependencies and build the example.
+```
+ $ npm install
+ $ npm run build
+```
+
+## Usage
+You can run the exmaple by running the following command:
+
+```
+$ node lib/index.js
+```
+
+Once it starts up you can list commands by typing:
+
+```
+/help
+```
+
+If you have trouble with encryption errors caused by devices with broken olm sessions (Usually occurring from use of the in-memory crypto store.) you can delete them all by running:
+
+```
+/cleardevices
+```
+
+This will delete all the devices on the account (except for the current one) so be careful if you have devices you do not wish to lose.
+
+## Limitations
+
+This example does not provide any way of verifying your sessions, so on some clients, users in the room will get a warning that someone is using an unverified session.
+
+This example relies on the `node-localstorage` package to provide persistance which is more or less required for E2EE and at the time of writing there are no working alternative packages.
+
+## Structure
+
+The structure of this example has been split into separate files that deal with specific logic.
+
+If you want to know how to import the Matrix SDK, have a look at `matrix-importer.ts`. If you want to know how to use the Matrix SDK, take a look at `matrix.ts`. If you want to know how to read the state, the `io.ts` file has a few related methods for things like printing rooms or messages. Finally the `index.ts` file glues a lot of these methods together to turn it into a small Matrix messaging client.
+
+### matrix-importer.ts
+
+This file is responsible for setting up the globals needed to enable E2EE on Matrix and importing the Matrix SDK correctly. This file then exports the Matrix SDK for ease of use.
+
+### matrix.ts
+
+This file provides a few methods to assist with certain actions through the Matrix SDK, such as logging in, verifying devices, clearing devices and getting rooms.
+
+* `getTokenLogin` - This method logs in via password to obtain an access token and device ID.
+* `startWithToken` - This method uses an access token to log into the user's account, starts the client and initializes crypto.
+* `clearDevices` - This method deletes the devices (other than the current one) from the user's account.
+
+### io.ts
+
+This file is responsible for handling the input and output to the console and reading credentials from a file.
+
+### index.ts
+
+This file handles the application setup and requests input from the user. This file essentially glues the methods from `matrix.ts` and `io.ts` together to turn it into a console messaging application.

examples/crypto-node/credentials.template.json

@@ -0,0 +1,5 @@
+{
+	"userId": "@my_user:matrix.org",
+	"password": "my_password",
+	"baseUrl": "https://matrix.org"
+}

examples/crypto-node/package.json

@@ -0,0 +1,23 @@
+{
+	"name": "example-app",
+	"type": "module",
+	"version": "0.0.0",
+	"description": "",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"scripts": {
+		"preinstall": "npm install ../..",
+		"build": "tsc -b"
+	},
+	"author": "",
+	"license": "Apache 2.0",
+	"dependencies": {
+		"@matrix-org/olm": "^3.2.15",
+		"matrix-js-sdk": "file:../..",
+		"node-localstorage": "^2.2.1"
+	},
+	"devDependencies": {
+		"@types/node-localstorage": "^1.3.0",
+		"typescript": "^5.0.4"
+	}
+}

examples/crypto-node/src/index.ts

@@ -0,0 +1,228 @@
+/**
+ * This file glues the matrix helper methods in './matrix.ts' with the IO helper
+ * methods in './io.ts' together to create a simple CLI.
+ */
+
+import Path from "path";
+import { fileURLToPath } from 'url';
+
+/**
+ * Import out IO helper methods.
+ */
+import {
+	readCredentials,
+	prompt,
+	fixWidth,
+	printRoomList,
+	printMessage,
+	printMessages,
+	printMemberList,
+	printRoomInfo,
+	addCommand
+} from "./io.js";
+
+/**
+ * Import our matrix helper methods.
+ */
+import { start, verifyRoom, getRoomList, clearDevices } from "./matrix.js";
+
+/**
+ * Import the types and enums from matrix-js-sdk.
+ */
+import { ClientEvent, RoomEvent, EventType, JoinRule, MsgType } from "matrix-js-sdk"
+import type { Room } from "matrix-js-sdk";
+
+/**
+ * Global state for keeping track of rooms.
+ */
+let roomList: Room[] = [];
+let viewingRoom: Room | null = null;
+
+/**
+* Import the user's credentials.
+*/
+const dirname = Path.dirname(fileURLToPath(import.meta.url));
+const credentials = await readCredentials(Path.join(dirname, "../credentials.json"));
+
+/**
+ * Create our matrix client.
+ */
+const client = await start(credentials);
+
+/**
+ * When a room is added or removed update the room list.
+ */
+client.on(ClientEvent.Room, () => {
+	roomList = getRoomList(client);
+
+	if (!viewingRoom) {
+		printRoomList(roomList);
+	}
+
+	prompt();
+});
+
+/**
+ * When we receive a message, check if we are in that room and if so display it.
+ */
+client.on(RoomEvent.Timeline, async(event, room) => {
+	const type = event.getType() as EventType;
+
+	if (![EventType.RoomMessage, EventType.RoomMessageEncrypted].includes(type)) {
+		return;
+	}
+
+	if (room != null && room.roomId !== viewingRoom?.roomId) {
+		return;
+	}
+
+	await client.decryptEventIfNeeded(event);
+
+	printMessage(event);
+	prompt();
+});
+
+/**
+ * Below is all of the possible commands and definitions.
+ */
+
+/**
+ * Basic help command, displays the possible commands.
+ */
+addCommand("/help", () => {
+	const displayCommand = (command: string, description: string) => {
+		console.log(`  ${fixWidth(command, 20)} : ${description}`);
+	};
+
+	console.log("Global commands:");
+	displayCommand("/help", "Show this help.");
+	displayCommand("/quit", "Quit the program.");
+	displayCommand("/cleardevices", "Clear all other devices from this account.");
+
+	console.log("Room list index commands:");
+	displayCommand("/join <index>", "Join a room, e.g. '/join 5'");
+
+	console.log("Room commands:");
+	displayCommand("/exit", "Return to the room list index.");
+	displayCommand("/send <message>", "Send a message to the room, e.g. '/send Hello World.'");
+	displayCommand("/members", "Show the room member list.");
+	displayCommand("/invite @foo:bar", "Invite @foo:bar to the room.");
+	displayCommand("/roominfo", "Display room info e.g. name, topic.");
+});
+
+/**
+ * Quit command for quitting the program.
+ */
+addCommand("/quit", () => {
+	process.exit();
+});
+
+/**
+ * Clear devices command for removing all other devices from the users account.
+ */
+addCommand("/cleardevices", async () => {
+	await clearDevices(client);
+});
+
+/**
+ * Join room command for joining a room from the room index.
+ */
+addCommand("/join", async (index) => {
+	if (viewingRoom != null) {
+		return "You must first exit your current room.";
+	}
+
+	viewingRoom = roomList[index];
+
+	if (viewingRoom == null) {
+		return "Invalid Room.";
+	}
+
+	if (viewingRoom.getMember(client.getUserId() ?? "")?.membership === JoinRule.Invite) {
+		await client.joinRoom(viewingRoom.roomId);
+	}
+
+	await verifyRoom(client, viewingRoom);
+	await client.roomInitialSync(viewingRoom.roomId, 20);
+
+	printMessages(viewingRoom);
+});
+
+/**
+ * Exit command for exiting a joined room.
+ */
+addCommand("/exit", () => {
+	viewingRoom = null;
+	printRoomList(roomList);
+});
+
+/**
+ * Invite command for inviting a user to the current room.
+ */
+addCommand("/invite", async (userId) => {
+	if (viewingRoom == null) {
+		return "You must first join a room.";
+	}
+
+	try {
+		await client.invite(viewingRoom.roomId, userId);
+	} catch (error) {
+		return `/invite Error: ${error}`;
+	}
+});
+
+/**
+ * Members command, displays the list of members in the current room.
+ */
+addCommand("/members", async () => {
+	if (viewingRoom == null) {
+		return "You must first join a room.";
+	}
+
+	printMemberList(viewingRoom);
+});
+
+/**
+ * Members command, displays the information about the current room.
+ */
+addCommand("/roominfo", async () => {
+	if (viewingRoom == null) {
+		return "You must first join a room.";
+	}
+
+	printRoomInfo(viewingRoom);
+});
+
+/**
+ * Send command for allowing the user to send messages in the current room.
+ */
+addCommand("/send", async (...tokens) => {
+	if (viewingRoom == null) {
+		return "You must first join a room.";
+	}
+
+	console.log(tokens);
+	console.log(tokens.join(" "));
+
+	const message = {
+		msgtype: MsgType.Text,
+		body: tokens.join(" ")
+	};
+
+	await client.sendMessage(viewingRoom.roomId, message);
+});
+
+/**
+ * Initialize the room list.
+ */
+roomList = getRoomList(client);
+
+/**
+ * Print the list of rooms.
+ */
+printRoomList(roomList);
+
+/**
+ * Request the first input from the user.
+ */
+prompt();