matrix-nodejs-homeserver 0.3.5 → 0.3.6

package/AUDITBOT.md

@@ -0,0 +1,67 @@
+# Audit bot
+
+`matrix-nodejs-homeserver/auditbot` records the rooms of the server, end-to-end encrypted ones
+included, to an archive: an account of the server that is a member of every room (or every room
+but direct messages) and writes each event as one JSON line.
+
+It needs the crypto library, an optional peer dependency:
+
+```sh
+npm install matrix-nodejs-homeserver @matrix-org/matrix-sdk-crypto-nodejs
+```
+
+```ts
+import { createHomeserver } from "matrix-nodejs-homeserver";
+import { fileSink, startAuditBot } from "matrix-nodejs-homeserver/auditbot";
+
+const hs = createHomeserver({ /* … */ });
+const bot = await startAuditBot(hs, {
+  sink: fileSink("/data/audit"),          // {room ID}/{YYYY-MM-DD}.jsonl
+  dataDir: "/data/auditbot",              // crypto store and sync position: keep and back up
+  storePassphrase: process.env.AUDIT_STORE_PASSPHRASE!,
+  rooms: "groups",                        // or "all" (default): with direct messages
+});
+// await bot.stop() on shutdown, before hs.close()
+```
+
+## How it works
+
+- **It is a room member.** It joins new rooms on its own, and existing ones at start and every
+  10 minutes. Public rooms are joined directly. In other rooms, a local member who may invite
+  invites it (`hs.admin.joinUser`, Synapse's `POST /_synapse/admin/v1/join`). The invite shows in
+  the room, and the bot is in the member list as "Audit log (this room is recorded)", so everyone
+  can see that a room is recorded.
+- **End-to-end encryption.** It is a device like any other, with matrix-sdk-crypto (the Rust
+  crypto of the Element apps). Clients send it the room keys as they do to every member's device,
+  and it decrypts the events. Its device is signed by its own cross-signing identity. Keys live in
+  an encrypted SQLite store in `dataDir`, so it reads messages again after a restart.
+- **Direct messages** are left out with `rooms: "groups"`. It does not join rooms created with
+  `is_direct`, and it leaves a room that turns out to be one.
+- **In-process.** It runs in the homeserver's process and calls its API through the request
+  handler, with no network and no port.
+
+What it cannot read: anything sent before it joined a room. It also misses messages from
+clients set to share keys only with verified devices. A message whose key never arrives is
+recorded after an hour with `decryption_error` and its ciphertext.
+
+## Records
+
+```json
+{"recorded_at":1792270000000,"room_id":"!abc:example.com","event_id":"$…","type":"m.room.message",
+ "sender":"@alice:example.com","origin_server_ts":1792269999000,
+ "content":{"msgtype":"m.text","body":"hello"},"encrypted":true,"sender_device":"ABCDEFGHIJ"}
+```
+
+`state_key` and `redacts` appear when the event has them. `initial_state: true` marks state the
+room had when the bot joined. A sink is anything with `write(records)`: `fileSink(dir)`,
+`memorySink()`, or your own (S3, a SIEM, a database).
+
+## Before you turn it on
+
+Recording people's conversations, encrypted ones included, needs a legal basis and telling them:
+terms of use, a privacy policy, and in the EU the GDPR. The bot's name says it in every room, but
+it does not replace those.
+
+The crypto library is a native module (Linux, macOS, Windows; x64 and arm64). Its install script
+downloads it from the project's GitHub releases. With `--ignore-scripts`, run
+`node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js`.

package/README.md

@@ -345,6 +345,18 @@ up for admins (`/_synapse/admin/v1/event_reports`, `reports list`), and the admi
 room is notified. `GET /_matrix/client/v3/admin/whois/{userId}` shows a user's
 devices and IP addresses.
 
+## Audit bot
+
+`matrix-nodejs-homeserver/auditbot` records every room of the server to an archive, end-to-end
+encrypted ones decrypted, like the Auditing of Element Server Suite Pro. The bot is a room
+member with its own device, visible in member lists. See [AUDITBOT.md](https://github.com/k18k/matrix-nodejs-homeserver/blob/main/packages/core/AUDITBOT.md).
+
+```ts
+import { fileSink, startAuditBot } from "matrix-nodejs-homeserver/auditbot";
+
+await startAuditBot(hs, { sink: fileSink("/data/audit"), dataDir: "/data/auditbot", storePassphrase, rooms: "groups" });
+```
+
 ## Administration
 
 You can use `hs.admin` from your own code:

package/dist/api/admin.js

@@ -133,6 +133,11 @@ function registerAdminRoutes(r) {
 		if (body.deactivated === true) await ctx.hs.admin.deactivateUser(userId);
 		return ctx.hs.admin.getUser(userId);
 	} }));
+	r.post("/_synapse/admin/v1/join/:roomIdOrAlias", procedure({
+		guard: adminGuard,
+		input: body({ user_id: string(fail("M_MISSING_PARAM", "user_id is required", "user_id")) }),
+		handler: async (ctx) => ({ room_id: await ctx.hs.admin.joinUser(ctx.input.user_id, ctx.params.roomIdOrAlias) })
+	}));
 	r.post("/_synapse/admin/v1/users/:userId/_allow_cross_signing_replacement_without_uia", procedure({
 		guard: adminGuard,
 		handler: async (ctx) => {

package/dist/auditbot/bot.d.ts

@@ -0,0 +1,37 @@
+import { Homeserver } from "../homeserver.js";
+import { AuditSink } from "./sinks.js";
+//#region src/auditbot/bot.d.ts
+export interface AuditBotOptions {
+  /** Where the records go: `fileSink(dir)`, or your own. */
+  sink: AuditSink;
+  /**
+   * Directory for the bot's state: its crypto store (room keys, device keys) and the sync
+   * position. Losing it loses the keys of encrypted rooms, so keep it on a persistent volume and
+   * back it up.
+   */
+  dataDir: string;
+  /** Encrypts the crypto store. Required; keep it with the backups of `dataDir`. */
+  storePassphrase: string;
+  /** Default "auditbot". */
+  localpart?: string;
+  /** The bot's name in member lists. Default "Audit log (this room is recorded)". */
+  displayName?: string;
+  /** "all" rooms, or "groups": not direct messages (rooms created with is_direct). Default "all". */
+  rooms?: "all" | "groups";
+  /** How often to look for rooms it is not in yet, in ms. Default 10 minutes. */
+  sweepIntervalMs?: number;
+  /** How long a new room has to be quiet before the bot joins it, in ms. Default 500. */
+  joinDelayMs?: number;
+  /** How long an undecryptable event waits for its room key before it is recorded as such. Default 1 hour. */
+  keyWaitMs?: number;
+}
+export interface AuditBot {
+  userId: string;
+  /** Resolves once the bot has synced up to now (tests). */
+  synced(): Promise<void>;
+  /** Join every room it is not in yet (it also does this on its own). */
+  sweep(): Promise<void>;
+  stop(): Promise<void>;
+}
+export declare function startAuditBot(hs: Homeserver, options: AuditBotOptions): Promise<AuditBot>;
+//#endregion

package/dist/auditbot/bot.js

@@ -0,0 +1,208 @@
+import { getFetchHandler } from "../http/adapters.js";
+import { CryptoClient } from "./client.js";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+//#region src/auditbot/bot.ts
+const MAX_PENDING = 1e4;
+async function startAuditBot(hs, options) {
+	await hs.ready;
+	const localpart = options.localpart ?? "auditbot";
+	const userId = `@${localpart}:${hs.serverName}`;
+	const displayName = options.displayName ?? "Audit log (this room is recorded)";
+	await mkdir(options.dataDir, { recursive: true });
+	const statePath = join(options.dataDir, "state.json");
+	const saved = await readFile(statePath, "utf8").then(JSON.parse, () => null);
+	if (!await hs.admin.getUser(userId)) await hs.admin.createUser(localpart, { displayname: displayName });
+	const session = await hs.auth.createSession(userId, {
+		deviceId: saved?.deviceId,
+		displayName: "Audit bot"
+	});
+	const state = {
+		deviceId: session.device_id,
+		since: saved?.since
+	};
+	const save = () => writeFile(statePath, JSON.stringify(state));
+	await save();
+	const client = new CryptoClient({
+		fetch: getFetchHandler(hs),
+		userId,
+		deviceId: session.device_id,
+		accessToken: session.access_token
+	});
+	await client.open(join(options.dataDir, "crypto"), options.storePassphrase);
+	await client.flush();
+	await client.ensureCrossSigning();
+	await client.request("PUT", `/_matrix/client/v3/profile/${encodeURIComponent(userId)}/displayname`, { displayname: displayName });
+	const pending = [];
+	const recorded = /* @__PURE__ */ new Set();
+	const encryptedRooms = /* @__PURE__ */ new Set();
+	let stopped = false;
+	const abort = new AbortController();
+	let syncedUpTo = 0;
+	const syncWaiters = [];
+	const isDirect = async (roomId) => {
+		const state = await hs.rooms.currentState(roomId);
+		for (const ev of state.values()) if (ev.type === "m.room.member" && ev.content?.is_direct === true) return true;
+		return false;
+	};
+	const joining = /* @__PURE__ */ new Map();
+	const ensureJoined = (roomId) => {
+		const running = joining.get(roomId);
+		if (running) return running;
+		const p = (async () => {
+			if ((await hs.rooms.roomsForUser(userId)).includes(roomId)) return;
+			if (options.rooms === "groups" && await isDirect(roomId)) return;
+			try {
+				await hs.admin.joinUser(userId, roomId);
+				hs.logger.info("Audit bot joined", roomId);
+			} catch (err) {
+				hs.logger.warn("Audit bot could not join", roomId, err.message);
+			}
+		})().finally(() => joining.delete(roomId));
+		joining.set(roomId, p);
+		return p;
+	};
+	const sweep = async () => {
+		const { rooms } = await hs.admin.listRooms({ limit: 1e6 });
+		for (const r of rooms) await ensureJoined(r.room_id);
+	};
+	const quietTimers = /* @__PURE__ */ new Map();
+	const joinWhenQuiet = (roomId) => {
+		clearTimeout(quietTimers.get(roomId));
+		quietTimers.set(roomId, setTimeout(() => {
+			quietTimers.delete(roomId);
+			ensureJoined(roomId);
+		}, options.joinDelayMs ?? 500));
+	};
+	const onEvent = (ev) => {
+		if (stopped || ev.type !== "m.room.member" || ev.state_key === userId) return;
+		if (ev.content?.membership === "join") joinWhenQuiet(ev.room_id);
+		if (options.rooms === "groups" && ev.content?.is_direct === true) (async () => {
+			if (!(await hs.rooms.joinedMembers(ev.room_id)).includes(userId)) return;
+			await client.request("POST", `/_matrix/client/v3/rooms/${encodeURIComponent(ev.room_id)}/leave`, {}).catch(() => {});
+			hs.logger.info("Audit bot left a direct message room", ev.room_id);
+		})();
+	};
+	hs.on("event", onEvent);
+	const toRecord = (roomId, ev, extra = {}) => ({
+		recorded_at: Date.now(),
+		room_id: roomId,
+		event_id: ev.event_id,
+		type: ev.type,
+		sender: ev.sender,
+		origin_server_ts: ev.origin_server_ts,
+		...ev.state_key !== void 0 ? { state_key: ev.state_key } : {},
+		content: ev.content ?? {},
+		...ev.redacts ? { redacts: ev.redacts } : {},
+		encrypted: false,
+		...extra
+	});
+	/** A record for an event, decrypting it when it is encrypted; null when its key is not here yet. */
+	const process = async (roomId, ev) => {
+		if (ev.type !== "m.room.encrypted") return toRecord(roomId, ev);
+		try {
+			const decrypted = await client.decrypt(ev, roomId);
+			const clear = JSON.parse(decrypted.event);
+			return toRecord(roomId, {
+				...ev,
+				type: clear.type,
+				content: clear.content
+			}, {
+				encrypted: true,
+				sender_device: decrypted.senderDevice?.toString()
+			});
+		} catch {
+			return null;
+		}
+	};
+	const write = async (records) => {
+		const fresh = records.filter((r) => !recorded.has(r.event_id));
+		if (fresh.length === 0) return;
+		await options.sink.write(fresh);
+		for (const r of fresh) recorded.add(r.event_id);
+		if (recorded.size > 1e5) recorded.clear();
+	};
+	const retryPending = async () => {
+		const out = [];
+		const keyWait = options.keyWaitMs ?? 36e5;
+		for (let i = pending.length - 1; i >= 0; i--) {
+			const p = pending[i];
+			const record = await process(p.roomId, p.event);
+			if (record || Date.now() - p.since > keyWait) {
+				out.push(record ?? toRecord(p.roomId, p.event, {
+					encrypted: true,
+					decryption_error: "The room key did not reach the audit bot"
+				}));
+				pending.splice(i, 1);
+			}
+		}
+		await write(out.reverse());
+	};
+	const handleSync = async (sync) => {
+		await client.receiveSync(sync);
+		const out = [];
+		for (const [roomId, room] of Object.entries(sync.rooms?.join ?? {})) {
+			const timeline = room.timeline?.events ?? [];
+			const stateEvents = room.state?.events ?? [];
+			for (const ev of [...stateEvents, ...timeline]) if (ev.type === "m.room.encryption") encryptedRooms.add(roomId);
+			if (encryptedRooms.has(roomId) && (stateEvents.length || timeline.some((e) => e.type === "m.room.member"))) await client.track(await hs.rooms.joinedMembers(roomId));
+			for (const ev of stateEvents) out.push(toRecord(roomId, ev, { initial_state: true }));
+			for (const ev of timeline) {
+				const record = await process(roomId, ev);
+				if (record) out.push(record);
+				else if (pending.length < MAX_PENDING) pending.push({
+					roomId,
+					event: ev,
+					since: Date.now()
+				});
+			}
+		}
+		await write(out);
+		await retryPending();
+	};
+	const loop = async () => {
+		while (!stopped) try {
+			const params = new URLSearchParams({
+				timeout: "30000",
+				filter: JSON.stringify({ room: { timeline: { limit: 200 } } })
+			});
+			if (state.since) params.set("since", state.since);
+			const sync = await client.request("GET", `/_matrix/client/v3/sync?${params}`, void 0, abort.signal);
+			await handleSync(sync);
+			state.since = sync.next_batch;
+			await save();
+			syncedUpTo = Date.now();
+			for (const w of syncWaiters.splice(0)) w();
+		} catch (err) {
+			if (stopped) return;
+			hs.logger.warn("Audit bot sync failed", err.message);
+			await new Promise((r) => setTimeout(r, 5e3));
+		}
+	};
+	await sweep();
+	const running = loop();
+	const timer = setInterval(() => void sweep().catch(() => {}), options.sweepIntervalMs ?? 6e5);
+	timer.unref();
+	return {
+		userId,
+		sweep,
+		synced() {
+			const asked = Date.now();
+			return new Promise((resolve) => {
+				const check = () => syncedUpTo > asked ? resolve() : syncWaiters.push(check);
+				check();
+			});
+		},
+		async stop() {
+			stopped = true;
+			abort.abort();
+			clearInterval(timer);
+			for (const t of quietTimers.values()) clearTimeout(t);
+			hs.off("event", onEvent);
+			await running.catch(() => {});
+			client.close();
+		}
+	};
+}
+//#endregion
+export { startAuditBot };

package/dist/auditbot/client.d.ts

@@ -0,0 +1,41 @@
+import { DecryptedRoomEvent, OlmMachine } from "@matrix-org/matrix-sdk-crypto-nodejs";
+//#region src/auditbot/client.d.ts
+export type Fetch = (request: Request) => Promise<Response>;
+export declare class CryptoClient {
+  readonly userId: string;
+  readonly deviceId: string;
+  private accessToken;
+  private fetch;
+  private baseUrl;
+  private txn;
+  machine: OlmMachine;
+  constructor(opts: {
+    fetch: Fetch;
+    baseUrl?: string;
+    userId: string;
+    deviceId: string;
+    accessToken: string;
+  });
+  /**
+   * Open the crypto store. With `storePath`, keys live in an encrypted SQLite store there (they
+   * must survive restarts: room keys are sent once). Without, in memory (tests).
+   */
+  open(storePath?: string, passphrase?: string): Promise<void>;
+  request<T = any>(method: string, path: string, body?: unknown, signal?: AbortSignal): Promise<T>;
+  /** Feed a /sync response to the crypto machine, then send what it needs sent. */
+  receiveSync(sync: Record<string, any>): Promise<void>;
+  /** Send every outgoing request of the crypto machine (key uploads, queries, claims, to-device). */
+  flush(): Promise<void>;
+  /** Make sure the crypto machine knows these users' devices. */
+  track(users: string[]): Promise<void>;
+  decrypt(event: Record<string, any>, roomId: string): Promise<DecryptedRoomEvent>;
+  /**
+   * Set up cross-signing for this account and sign the device with it, so other users' clients
+   * see the device as its owner's (not as an unknown one). Only once: an existing identity is kept.
+   */
+  ensureCrossSigning(): Promise<void>;
+  /** Encrypt and send a message (the test's sender; the bot itself sends nothing encrypted). */
+  sendEncrypted(roomId: string, members: string[], content: Record<string, unknown>): Promise<string>;
+  close(): void;
+}
+//#endregion

package/dist/auditbot/client.js

@@ -0,0 +1,156 @@
+import { DeviceId, DeviceLists, OlmMachine, RoomId, UserId } from "@matrix-org/matrix-sdk-crypto-nodejs";
+//#region src/auditbot/client.ts
+/** The request types of matrix-sdk-crypto (a const enum in its typings). */
+const Req = {
+	KeysUpload: 0,
+	KeysQuery: 1,
+	KeysClaim: 2,
+	ToDevice: 3,
+	SignatureUpload: 4,
+	RoomMessage: 5,
+	KeysBackup: 6
+};
+/**
+* matrix-sdk-crypto puts signature uploads under `signed_keys`; the endpoint takes the map of
+* signatures itself as the body.
+*/
+function signatureUploadBody(body) {
+	const parsed = JSON.parse(body);
+	return Object.keys(parsed).length === 1 && parsed.signed_keys ? JSON.stringify(parsed.signed_keys) : body;
+}
+var MatrixError = class extends Error {
+	status;
+	body;
+	constructor(status, body) {
+		super(`${status} ${body.errcode ?? ""} ${body.error ?? ""}`.trim());
+		this.status = status;
+		this.body = body;
+	}
+};
+var CryptoClient = class {
+	userId;
+	deviceId;
+	accessToken;
+	fetch;
+	baseUrl;
+	txn = 0;
+	machine;
+	constructor(opts) {
+		this.fetch = opts.fetch;
+		this.baseUrl = opts.baseUrl ?? "http://localhost";
+		this.userId = opts.userId;
+		this.deviceId = opts.deviceId;
+		this.accessToken = opts.accessToken;
+	}
+	/**
+	* Open the crypto store. With `storePath`, keys live in an encrypted SQLite store there (they
+	* must survive restarts: room keys are sent once). Without, in memory (tests).
+	*/
+	async open(storePath, passphrase) {
+		this.machine = await OlmMachine.initialize(new UserId(this.userId), new DeviceId(this.deviceId), storePath ?? null, passphrase ?? null, storePath ? 0 : null);
+	}
+	async request(method, path, body, signal) {
+		const res = await this.fetch(new Request(`${this.baseUrl}${path}`, {
+			method,
+			signal,
+			headers: {
+				authorization: `Bearer ${this.accessToken}`,
+				"content-type": "application/json"
+			},
+			body: body === void 0 ? void 0 : typeof body === "string" ? body : JSON.stringify(body)
+		}));
+		const text = await res.text();
+		const json = text ? JSON.parse(text) : {};
+		if (!res.ok) throw new MatrixError(res.status, json);
+		return json;
+	}
+	/** Feed a /sync response to the crypto machine, then send what it needs sent. */
+	async receiveSync(sync) {
+		const changed = (sync.device_lists?.changed ?? []).map((u) => new UserId(u));
+		const left = (sync.device_lists?.left ?? []).map((u) => new UserId(u));
+		await this.machine.receiveSyncChanges(JSON.stringify(sync.to_device?.events ?? []), new DeviceLists(changed, left), sync.device_one_time_keys_count ?? {}, sync.device_unused_fallback_key_types ?? []);
+		await this.flush();
+	}
+	/** Send every outgoing request of the crypto machine (key uploads, queries, claims, to-device). */
+	async flush() {
+		for (let round = 0; round < 10; round++) {
+			const requests = await this.machine.outgoingRequests();
+			if (requests.length === 0) return;
+			for (const r of requests) {
+				let response;
+				switch (r.type) {
+					case Req.KeysUpload:
+						response = await this.request("POST", "/_matrix/client/v3/keys/upload", r.body);
+						break;
+					case Req.KeysQuery:
+						response = await this.request("POST", "/_matrix/client/v3/keys/query", r.body);
+						break;
+					case Req.KeysClaim:
+						response = await this.request("POST", "/_matrix/client/v3/keys/claim", r.body);
+						break;
+					case Req.SignatureUpload:
+						response = await this.request("POST", "/_matrix/client/v3/keys/signatures/upload", signatureUploadBody(r.body));
+						break;
+					case Req.ToDevice: {
+						const t = r;
+						response = await this.request("PUT", `/_matrix/client/v3/sendToDevice/${encodeURIComponent(t.eventType)}/${encodeURIComponent(t.txnId)}`, t.body);
+						break;
+					}
+					case Req.RoomMessage: {
+						const m = r;
+						response = await this.request("PUT", `/_matrix/client/v3/rooms/${encodeURIComponent(m.roomId)}/send/${encodeURIComponent(m.eventType)}/${encodeURIComponent(m.txnId)}`, m.body);
+						break;
+					}
+					default: continue;
+				}
+				await this.machine.markRequestAsSent(r.id, r.type, JSON.stringify(response));
+			}
+		}
+	}
+	/** Make sure the crypto machine knows these users' devices. */
+	async track(users) {
+		await this.machine.updateTrackedUsers(users.map((u) => new UserId(u)));
+		await this.flush();
+	}
+	decrypt(event, roomId) {
+		return this.machine.decryptRoomEvent(JSON.stringify(event), new RoomId(roomId));
+	}
+	/**
+	* Set up cross-signing for this account and sign the device with it, so other users' clients
+	* see the device as its owner's (not as an unknown one). Only once: an existing identity is kept.
+	*/
+	async ensureCrossSigning() {
+		const status = await this.machine.crossSigningStatus();
+		if (status.hasMaster && status.hasSelfSigning) return;
+		const requests = await this.machine.bootstrapCrossSigning(true);
+		if (requests.uploadKeysReq) {
+			const response = await this.request("POST", "/_matrix/client/v3/keys/upload", requests.uploadKeysReq.body);
+			await this.machine.markRequestAsSent(requests.uploadKeysReq.id, requests.uploadKeysReq.type, JSON.stringify(response));
+		}
+		await this.request("POST", "/_matrix/client/v3/keys/device_signing/upload", requests.uploadSigningKeysReq);
+		const signatures = await this.request("POST", "/_matrix/client/v3/keys/signatures/upload", signatureUploadBody(requests.uploadSignaturesReq.body));
+		await this.machine.markRequestAsSent(requests.uploadSignaturesReq.id, requests.uploadSignaturesReq.type, JSON.stringify(signatures));
+	}
+	/** Encrypt and send a message (the test's sender; the bot itself sends nothing encrypted). */
+	async sendEncrypted(roomId, members, content) {
+		const { EncryptionSettings } = await import("@matrix-org/matrix-sdk-crypto-nodejs");
+		await this.track(members);
+		const users = members.map((u) => new UserId(u));
+		const claim = await this.machine.getMissingSessions(users);
+		if (claim) {
+			const response = await this.request("POST", "/_matrix/client/v3/keys/claim", claim.body);
+			await this.machine.markRequestAsSent(claim.id, claim.type, JSON.stringify(response));
+		}
+		for (const r of await this.machine.shareRoomKey(new RoomId(roomId), users, new EncryptionSettings())) {
+			const response = await this.request("PUT", `/_matrix/client/v3/sendToDevice/${encodeURIComponent(r.eventType)}/${encodeURIComponent(r.txnId)}`, r.body);
+			await this.machine.markRequestAsSent(r.id, r.type, JSON.stringify(response));
+		}
+		const encrypted = await this.machine.encryptRoomEvent(new RoomId(roomId), "m.room.message", JSON.stringify(content));
+		return (await this.request("PUT", `/_matrix/client/v3/rooms/${encodeURIComponent(roomId)}/send/m.room.encrypted/e2e${Date.now()}${this.txn++}`, encrypted)).event_id;
+	}
+	close() {
+		this.machine?.close();
+	}
+};
+//#endregion
+export { CryptoClient, MatrixError };

package/dist/auditbot/index.d.ts

@@ -0,0 +1,4 @@
+import { AuditRecord, AuditSink, fileSink, memorySink } from "./sinks.js";
+import { AuditBot, AuditBotOptions, startAuditBot } from "./bot.js";
+import { CryptoClient } from "./client.js";
+export { type AuditBot, type AuditBotOptions, type AuditRecord, type AuditSink, CryptoClient, fileSink, memorySink, startAuditBot };

package/dist/auditbot/index.js

@@ -0,0 +1,4 @@
+import { CryptoClient } from "./client.js";
+import { startAuditBot } from "./bot.js";
+import { fileSink, memorySink } from "./sinks.js";
+export { CryptoClient, fileSink, memorySink, startAuditBot };

package/dist/auditbot/sinks.d.ts

@@ -0,0 +1,37 @@
+//#region src/auditbot/sinks.d.ts
+/** One recorded event, as written to the archive (one JSON object per line). */
+export interface AuditRecord {
+  /** When the bot recorded it (ms). */
+  recorded_at: number;
+  room_id: string;
+  event_id: string;
+  type: string;
+  sender: string;
+  origin_server_ts: number;
+  state_key?: string;
+  /** The content as the room's members see it: decrypted for end-to-end encrypted events. */
+  content: Record<string, unknown>;
+  redacts?: string;
+  /** The event was end-to-end encrypted. */
+  encrypted: boolean;
+  /** For encrypted events: the sending device, as the room key says. */
+  sender_device?: string;
+  /** The event could not be decrypted (no room key reached the bot); `content` is the ciphertext. */
+  decryption_error?: string;
+  /** Part of the room's state when the bot joined, not a new event. */
+  initial_state?: boolean;
+}
+/** Where records go. Writes for one room come in order; a write that throws is retried. */
+export interface AuditSink {
+  write(records: AuditRecord[]): Promise<void>;
+}
+/**
+ * JSON Lines files: `{directory}/{room ID}/{YYYY-MM-DD}.jsonl`, one file per room and UTC day of
+ * the event. Room IDs are percent-encoded, so they cannot name a path outside the directory.
+ */
+export declare function fileSink(directory: string): AuditSink;
+/** Records kept in memory (tests, or a custom forwarder that reads `records`). */
+export declare function memorySink(): AuditSink & {
+  records: AuditRecord[];
+};
+//#endregion

package/dist/auditbot/sinks.js

@@ -0,0 +1,33 @@
+import { appendFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+//#region src/auditbot/sinks.ts
+const day = (ts) => new Date(ts).toISOString().slice(0, 10);
+/**
+* JSON Lines files: `{directory}/{room ID}/{YYYY-MM-DD}.jsonl`, one file per room and UTC day of
+* the event. Room IDs are percent-encoded, so they cannot name a path outside the directory.
+*/
+function fileSink(directory) {
+	return { async write(records) {
+		const byFile = /* @__PURE__ */ new Map();
+		for (const r of records) {
+			const file = join(directory, encodeURIComponent(r.room_id), `${day(r.origin_server_ts)}.jsonl`);
+			byFile.set(file, [...byFile.get(file) ?? [], JSON.stringify(r)]);
+		}
+		for (const [file, lines] of byFile) {
+			await mkdir(join(file, ".."), { recursive: true });
+			await appendFile(file, `${lines.join("\n")}\n`);
+		}
+	} };
+}
+/** Records kept in memory (tests, or a custom forwarder that reads `records`). */
+function memorySink() {
+	const records = [];
+	return {
+		records,
+		async write(batch) {
+			records.push(...batch);
+		}
+	};
+}
+//#endregion
+export { fileSink, memorySink };

package/dist/core/admin.d.ts

@@ -53,6 +53,12 @@ export declare class AdminService {
   }>;
   listRegistrationTokens(): Promise<Row[]>;
   deleteRegistrationToken(token: string): Promise<void>;
+  /**
+   * Make a local user join a room, as Synapse's `POST /_synapse/admin/v1/join` does: public rooms
+   * directly; otherwise a local member who may invite invites them first (the invite shows in the
+   * room, so its members see who added them). Returns the room ID.
+   */
+  joinUser(userId: string, roomIdOrAlias: string): Promise<string>;
   listRooms(opts?: {
     from?: number;
     limit?: number;

package/dist/core/admin.js

@@ -2,6 +2,7 @@ import { randomString } from "./crypto.js";
 import { M } from "./m.js";
 import { errors } from "./errors.js";
 import { LOCALPART_RE, isValidUserId } from "./ids.js";
+import { getState, membershipOf, powerLevels, userLevel } from "./authrules.js";
 import { createUser } from "../api/account.js";
 //#region src/core/admin.ts
 /** Programmatic administration, for embedding applications and the admin HTTP API. */
@@ -145,6 +146,30 @@ var AdminService = class {
 			value: token
 		}])) throw errors.notFound("Unknown token");
 	}
+	/**
+	* Make a local user join a room, as Synapse's `POST /_synapse/admin/v1/join` does: public rooms
+	* directly; otherwise a local member who may invite invites them first (the invite shows in the
+	* room, so its members see who added them). Returns the room ID.
+	*/
+	async joinUser(userId, roomIdOrAlias) {
+		if (!this.hs.isLocalUser(userId) || !await this.getUser(userId)) throw errors.notFound("Unknown user");
+		const roomId = await this.hs.rooms.resolveRoomIdOrAlias(roomIdOrAlias);
+		const version = await this.hs.rooms.roomVersion(roomId);
+		if (!version) throw errors.notFound("Unknown room");
+		const state = await this.hs.rooms.currentState(roomId);
+		const membership = membershipOf(state, userId);
+		if (membership === "join") return roomId;
+		if (membership === "ban") throw errors.forbidden("The user is banned from the room");
+		const joinRule = getState(state, M.ROOM.JOIN_RULES)?.content?.join_rule;
+		if (membership !== "invite" && joinRule !== "public") {
+			const pl = powerLevels(state, version);
+			const inviter = (await this.hs.rooms.joinedMembers(roomId)).find((m) => this.hs.isLocalUser(m) && userLevel(pl, m) >= pl.invite);
+			if (!inviter) throw errors.forbidden("No local member of the room may invite");
+			await this.hs.rooms.invite(roomId, inviter, userId);
+		}
+		await this.hs.rooms.join(userId, roomId);
+		return roomId;
+	}
 	async listRooms(opts = {}) {
 		const rows = await this.hs.db.findMany("rooms", { sortBy: {
 			field: "created_ts",

package/dist/homeserver.d.ts

@@ -13,20 +13,20 @@ import { Notifier } from "./core/notifier.js";
 import { RoomService } from "./core/rooms.js";
 import { TypingService } from "./core/typing.js";
 import { PushService } from "./core/push.js";
-import { AdminService, ServerNoticesOptions } from "./core/admin.js";
-import { OAuthDelegation, OAuthDelegationOptions } from "./core/oauth.js";
-import { OAuthServer, OAuthServerOptions } from "./core/oauthserver.js";
-import { SsoOptions, SsoService } from "./core/sso.js";
-import { FederationOptions, FederationService } from "./federation/index.js";
-import { DelayedEventService, DelayedEventsOptions } from "./core/delayed.js";
+import { ResolvedUserAuth, UserAuthAdapter } from "./adapters/auth.js";
+import { MediaAdapter, Thumbnailer } from "./adapters/media.js";
 import { RateLimitAction, RateLimitRule, RateLimiter, RateLimits } from "./core/ratelimit.js";
+import { FederationOptions, FederationService } from "./federation/index.js";
 import { Router } from "./http/router.js";
 import { RtcOptions } from "./api/rtc.js";
+import { DelayedEventService, DelayedEventsOptions } from "./core/delayed.js";
+import { OAuthDelegation, OAuthDelegationOptions } from "./core/oauth.js";
+import { OAuthServer, OAuthServerOptions } from "./core/oauthserver.js";
+import { SsoOptions, SsoService } from "./core/sso.js";
 import { AuditOptions, AuditService } from "./core/audit.js";
-import { SettingsService } from "./core/settings.js";
 import { AdminRoomOptions, AdminRoomService } from "./core/adminroom.js";
-import { ResolvedUserAuth, UserAuthAdapter } from "./adapters/auth.js";
-import { MediaAdapter, Thumbnailer } from "./adapters/media.js";
+import { AdminService, ServerNoticesOptions } from "./core/admin.js";
+import { SettingsService } from "./core/settings.js";
 import { ChangeTracker } from "./core/changes.js";
 import { AddressPolicy } from "./core/outbound.js";
 import { EventEmitter } from "node:events";

package/dist/index.d.ts

@@ -3,25 +3,25 @@ import { M, UNSTABLE } from "./core/m.js";
 import { AppServiceRegistration, loadAppServiceRegistrations, parseAppServiceRegistration } from "./core/appservices.js";
 import { DatabaseAdapter, FieldDef, FindManyOptions, ModelDef, Operator, Row, Schema, WhereClause } from "./storage/types.js";
 import { ClusterAdapter, localCluster } from "./core/cluster.js";
-import { AdminService, ServerNoticesOptions } from "./core/admin.js";
-import { OAuthDelegationOptions } from "./core/oauth.js";
-import { OAuthServerOptions } from "./core/oauthserver.js";
-import { SsoOptions, SsoProvider, githubProvider } from "./core/sso.js";
-import { MatrixError } from "./core/errors.js";
-import { FederationOptions } from "./federation/index.js";
-import { DelayedEventsOptions } from "./core/delayed.js";
-import { RateLimitAction, RateLimitRule, RateLimiter, memoryRateLimiter } from "./core/ratelimit.js";
-import { RtcOptions, TurnOptions } from "./api/rtc.js";
-import { AuditAction, AuditEntry, AuditOptions } from "./core/audit.js";
-import { AdminRoomOptions } from "./core/adminroom.js";
-import { PasswordCheckContext, UserAuthAdapter } from "./adapters/auth.js";
-import { MediaAdapter, MediaMetadata, ThumbnailRequest, Thumbnailer, filesystemMedia, memoryMedia, sharpThumbnailer } from "./adapters/media.js";
-import { Homeserver, HomeserverOptions, Logger, createHomeserver } from "./homeserver.js";
 import { NodeHandler, getExpressHandler, getFastifyPlugin, getFetchHandler, getHonoHandler, getNodeHandler, isMatrixPath } from "./http/adapters.js";
 import { handleRequest } from "./http/handler.js";
+import { MatrixError } from "./core/errors.js";
 import { memoryAdapter } from "./storage/memory.js";
 import { MysqlPoolLike, PgPoolLike, SqlAdapterOptions, SqlDialect, SqlExecutor, SqliteDatabaseLike, mysqlAdapter, postgresAdapter, sqlAdapter, sqliteAdapter } from "./storage/sql.js";
 import { schema } from "./storage/schema.js";
+import { PasswordCheckContext, UserAuthAdapter } from "./adapters/auth.js";
+import { MediaAdapter, MediaMetadata, ThumbnailRequest, Thumbnailer, filesystemMedia, memoryMedia, sharpThumbnailer } from "./adapters/media.js";
 import { S3MediaOptions, s3Media } from "./adapters/s3.js";
+import { RateLimitAction, RateLimitRule, RateLimiter, memoryRateLimiter } from "./core/ratelimit.js";
 import { PgClusterPoolLike, postgresCluster } from "./adapters/cluster.js";
+import { FederationOptions } from "./federation/index.js";
+import { RtcOptions, TurnOptions } from "./api/rtc.js";
+import { DelayedEventsOptions } from "./core/delayed.js";
+import { OAuthDelegationOptions } from "./core/oauth.js";
+import { OAuthServerOptions } from "./core/oauthserver.js";
+import { SsoOptions, SsoProvider, githubProvider } from "./core/sso.js";
+import { AuditAction, AuditEntry, AuditOptions } from "./core/audit.js";
+import { AdminRoomOptions } from "./core/adminroom.js";
+import { AdminService, ServerNoticesOptions } from "./core/admin.js";
+import { Homeserver, HomeserverOptions, Logger, createHomeserver } from "./homeserver.js";
 export { type AdminRoomOptions, type AdminService, type AppServiceRegistration, type AuditAction, type AuditEntry, type AuditOptions, type ClusterAdapter, type DatabaseAdapter, type DelayedEventsOptions, type FederationOptions, type FieldDef, type FindManyOptions, Homeserver, type HomeserverOptions, type Logger, M, MatrixError, type MediaAdapter, type MediaMetadata, type ModelDef, type MysqlPoolLike, type NodeHandler, type OAuthDelegationOptions, type OAuthServerOptions, type Operator, type PasswordCheckContext, type PgClusterPoolLike, type PgPoolLike, type RateLimitAction, type RateLimitRule, type RateLimiter, type Row, type RtcOptions, type S3MediaOptions, type Schema, type ServerNoticesOptions, type SqlAdapterOptions, type SqlDialect, type SqlExecutor, type SqliteDatabaseLike, type SsoOptions, type SsoProvider, type ThreepidEmail, type ThreepidOptions, type ThreepidPurpose, type ThreepidSms, type ThumbnailRequest, type Thumbnailer, type TurnOptions, UNSTABLE, type UserAuthAdapter, type WhereClause, createHomeserver, filesystemMedia, getExpressHandler, getFastifyPlugin, getFetchHandler, getHonoHandler, getNodeHandler, githubProvider, handleRequest, isMatrixPath, loadAppServiceRegistrations, localCluster, memoryAdapter, memoryMedia, memoryRateLimiter, mysqlAdapter, parseAppServiceRegistration, postgresAdapter, postgresCluster, s3Media, schema, sharpThumbnailer, sqlAdapter, sqliteAdapter };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "matrix-nodejs-homeserver",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "A framework- and database-agnostic Matrix homeserver library for Node.js",
   "keywords": [
     "chat",
@@ -20,9 +20,10 @@
     "directory": "packages/core"
   },
   "files": [
-    "dist",
+    "AUDITBOT.md",
+    "LICENSE",
     "README.md",
-    "LICENSE"
+    "dist"
   ],
   "type": "module",
   "main": "./dist/index.js",
@@ -34,6 +35,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./auditbot": {
+      "types": "./dist/auditbot/index.d.ts",
+      "default": "./dist/auditbot/index.js"
     }
   },
   "publishConfig": {
@@ -56,12 +61,21 @@
     "@better-auth/oauth-provider": "1.7.6",
     "@better-auth/utils": "0.4.2",
     "@better-fetch/fetch": "1.3.2",
+    "@matrix-org/matrix-sdk-crypto-nodejs": "0.6.6",
     "better-auth": "1.7.6",
     "better-call": "1.4.0",
     "publint": "^0.3.25",
     "tsdown": "^0.23.1",
     "zod": "^4.6.7"
   },
+  "peerDependencies": {
+    "@matrix-org/matrix-sdk-crypto-nodejs": "^0.6.6"
+  },
+  "peerDependenciesMeta": {
+    "@matrix-org/matrix-sdk-crypto-nodejs": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=22"
   }