matrix-nodejs-homeserver 0.0.0-stage → 0.3.1

package/dist/core/cluster.js

@@ -0,0 +1,191 @@
+import { randomString } from "./crypto.js";
+//#region src/core/cluster.ts
+/** In-process cluster adapter: a single homeserver instance. */
+function localCluster() {
+	const sequences = /* @__PURE__ */ new Map();
+	const locks = /* @__PURE__ */ new Map();
+	const handlers = /* @__PURE__ */ new Map();
+	const kv = /* @__PURE__ */ new Map();
+	const live = (key) => {
+		const e = kv.get(key);
+		if (!e) return void 0;
+		if (e.expires && e.expires < Date.now()) {
+			kv.delete(key);
+			return;
+		}
+		return e;
+	};
+	return {
+		async nextId(seq) {
+			const v = (sequences.get(seq) ?? 0) + 1;
+			sequences.set(seq, v);
+			return v;
+		},
+		async currentId(seq) {
+			return sequences.get(seq) ?? 0;
+		},
+		async advance(seq, value) {
+			if (value > (sequences.get(seq) ?? 0)) sequences.set(seq, value);
+		},
+		async lock(key, fn) {
+			const run = (locks.get(key) ?? Promise.resolve()).then(fn, fn);
+			const settled = run.catch(() => {});
+			locks.set(key, settled);
+			try {
+				return await run;
+			} finally {
+				if (locks.get(key) === settled) locks.delete(key);
+			}
+		},
+		async publish(channel, message) {
+			for (const h of handlers.get(channel) ?? []) queueMicrotask(() => h(message));
+		},
+		subscribe(channel, handler) {
+			let set = handlers.get(channel);
+			if (!set) handlers.set(channel, set = /* @__PURE__ */ new Set());
+			set.add(handler);
+		},
+		async get(key) {
+			return live(key)?.value ?? null;
+		},
+		async set(key, value, ttlMs) {
+			kv.set(key, {
+				value,
+				expires: ttlMs ? Date.now() + ttlMs : 0
+			});
+		},
+		async setIfAbsent(key, value, ttlMs) {
+			if (live(key)) return false;
+			kv.set(key, {
+				value,
+				expires: ttlMs ? Date.now() + ttlMs : 0
+			});
+			if (kv.size > 2e5) {
+				for (const k of kv.keys()) if (!live(k)) kv.delete(k);
+			}
+			return true;
+		},
+		async delete(key) {
+			kv.delete(key);
+		},
+		async entries(prefix) {
+			const out = [];
+			for (const k of [...kv.keys()]) if (k.startsWith(prefix)) {
+				const e = live(k);
+				if (e) out.push([k, e.value]);
+			}
+			return out;
+		}
+	};
+}
+const WRITER_TTL_MS = 3e4;
+/**
+* Stream positions with multiple writers. Positions are allocated from a global
+* sequence; readers only see positions up to which every writer has finished, so
+* an event committed late with a lower position can never be skipped by /sync.
+*
+* Each writer publishes `{ busy, pos }`: when busy, all of its positions ≤ pos are
+* persisted. Readers use min(global, busy writers' pos).
+*/
+var StreamManager = class {
+	cluster;
+	instanceId;
+	inflight = /* @__PURE__ */ new Set();
+	published = {
+		busy: false,
+		pos: 0
+	};
+	transition = Promise.resolve();
+	heartbeat;
+	positionCache = null;
+	constructor(cluster, instanceId) {
+		this.cluster = cluster;
+		this.instanceId = instanceId;
+		this.heartbeat = setInterval(() => void this.publishState().catch(() => {}), WRITER_TTL_MS / 3);
+		this.heartbeat.unref?.();
+	}
+	key() {
+		return `writer:${this.instanceId}`;
+	}
+	async publishState() {
+		await this.cluster.set(this.key(), this.published, WRITER_TTL_MS);
+	}
+	/** Allocate a position. The caller must call `done()` once its writes are committed. */
+	async allocate() {
+		await (this.transition = this.transition.then(async () => {
+			if (!this.published.busy) {
+				this.published = {
+					busy: true,
+					pos: await this.cluster.currentId("stream")
+				};
+				await this.publishState();
+			}
+		}));
+		const id = await this.cluster.nextId("stream");
+		this.inflight.add(id);
+		let finished = false;
+		const timer = setTimeout(() => void lease.done(), 6e4);
+		timer.unref?.();
+		const lease = {
+			id,
+			done: async () => {
+				if (finished) return;
+				finished = true;
+				clearTimeout(timer);
+				this.inflight.delete(id);
+				await (this.transition = this.transition.then(async () => {
+					this.published = this.inflight.size ? {
+						busy: true,
+						pos: Math.min(...this.inflight) - 1
+					} : {
+						busy: false,
+						pos: await this.cluster.currentId("stream")
+					};
+					await this.publishState();
+				}));
+				this.positionCache = null;
+			}
+		};
+		return lease;
+	}
+	/** Allocate a position, run `fn` with it, then complete it. */
+	async write(fn) {
+		const lease = await this.allocate();
+		try {
+			return await fn(lease.id);
+		} finally {
+			await lease.done();
+		}
+	}
+	/** A fresh decreasing position for backfilled (historical) events. */
+	async backfillId() {
+		return -await this.cluster.nextId("backfill");
+	}
+	/** The highest position below which everything is persisted, cluster-wide. */
+	async position() {
+		if (this.positionCache && Date.now() - this.positionCache.at < 20) return this.positionCache.value;
+		let pos = await this.cluster.currentId("stream");
+		for (const [, w] of await this.cluster.entries("writer:")) if (w?.busy) pos = Math.min(pos, w.pos);
+		if (this.inflight.size) pos = Math.min(pos, Math.min(...this.inflight) - 1);
+		this.positionCache = {
+			value: pos,
+			at: Date.now()
+		};
+		return pos;
+	}
+	async advanceTo(value) {
+		await this.cluster.advance("stream", value);
+	}
+	async lowerBackfillTo(value) {
+		if (value < 0) await this.cluster.advance("backfill", -value);
+	}
+	async stop() {
+		clearInterval(this.heartbeat);
+		await this.cluster.delete(this.key()).catch(() => {});
+	}
+};
+function newInstanceId() {
+	return `${process.pid}-${randomString(8)}`;
+}
+//#endregion
+export { StreamManager, localCluster, newInstanceId };

package/dist/core/crypto.d.ts

@@ -0,0 +1,10 @@
+import { KeyObject } from "node:crypto";
+//#region src/core/crypto.d.ts
+export interface SigningKey {
+  keyId: string;
+  privateKey: KeyObject;
+  publicKeyBase64: string;
+  /** Unpadded base64 of the 32-byte ed25519 seed, for persistence. */
+  seed: string;
+}
+//#endregion

package/dist/core/crypto.js

@@ -0,0 +1,100 @@
+import { canonicalJson } from "./json.js";
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, randomBytes, randomInt, scrypt, sign, timingSafeEqual, verify } from "node:crypto";
+import { promisify } from "node:util";
+//#region src/core/crypto.ts
+const scryptAsync = promisify(scrypt);
+function unpaddedBase64(buf) {
+	return Buffer.from(buf).toString("base64").replace(/=+$/, "");
+}
+function urlSafeBase64(buf) {
+	return unpaddedBase64(buf).replace(/\+/g, "-").replace(/\//g, "_");
+}
+function randomString(length) {
+	const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+	let out = "";
+	for (let i = 0; i < length; i++) out += alphabet[randomInt(52)];
+	return out;
+}
+function randomToken(bytes = 32) {
+	return urlSafeBase64(randomBytes(bytes));
+}
+function sha256(data) {
+	return createHash("sha256").update(data).digest();
+}
+async function hashPassword(password) {
+	const salt = randomBytes(16);
+	const hash = await scryptAsync(password.normalize("NFKC"), salt, 64);
+	return `scrypt$${salt.toString("base64")}$${hash.toString("base64")}`;
+}
+async function verifyPassword(password, stored) {
+	const [scheme, saltB64, hashB64] = stored.split("$");
+	if (scheme !== "scrypt" || !saltB64 || !hashB64) return false;
+	const expected = Buffer.from(hashB64, "base64");
+	const actual = await scryptAsync(password.normalize("NFKC"), Buffer.from(saltB64, "base64"), expected.length);
+	return timingSafeEqual(expected, actual);
+}
+const PKCS8_ED25519_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex");
+function loadSigningKey(keyId, seed) {
+	let privateKey;
+	if (seed) {
+		const raw = Buffer.from(seed, "base64");
+		privateKey = createPrivateKey({
+			key: Buffer.concat([PKCS8_ED25519_PREFIX, raw]),
+			format: "der",
+			type: "pkcs8"
+		});
+	} else privateKey = generateKeyPairSync("ed25519").privateKey;
+	const der = privateKey.export({
+		format: "der",
+		type: "pkcs8"
+	});
+	const rawSeed = der.subarray(der.length - 32);
+	const spki = createPublicKey(privateKey).export({
+		format: "der",
+		type: "spki"
+	});
+	const rawPub = spki.subarray(spki.length - 32);
+	return {
+		keyId,
+		privateKey,
+		publicKeyBase64: unpaddedBase64(rawPub),
+		seed: unpaddedBase64(rawSeed)
+	};
+}
+/** Sign a JSON object in place according to the Matrix signing algorithm. */
+function signJson(obj, serverName, key) {
+	const { signatures, unsigned, ...rest } = obj;
+	const sig = unpaddedBase64(sign(null, Buffer.from(canonicalJson(rest)), key.privateKey));
+	const merged = { ...signatures };
+	merged[serverName] = {
+		...merged[serverName],
+		[`ed25519:${key.keyId}`]: sig
+	};
+	obj.signatures = merged;
+	return obj;
+}
+const SPKI_ED25519_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+/** Decode unpadded (standard or URL-safe) base64. */
+function decodeBase64(s) {
+	return Buffer.from(s.replace(/-/g, "+").replace(/_/g, "/"), "base64");
+}
+function publicKeyFromBase64(key) {
+	return createPublicKey({
+		key: Buffer.concat([SPKI_ED25519_PREFIX, decodeBase64(key)]),
+		format: "der",
+		type: "spki"
+	});
+}
+/** Verify one ed25519 signature on a JSON object (signatures/unsigned excluded). */
+function verifyJsonSignature(obj, serverName, keyId, publicKey) {
+	const sig = obj.signatures?.[serverName]?.[keyId];
+	if (typeof sig !== "string") return false;
+	const { signatures, unsigned, ...rest } = obj;
+	try {
+		return verify(null, Buffer.from(canonicalJson(rest)), publicKey, decodeBase64(sig));
+	} catch {
+		return false;
+	}
+}
+//#endregion
+export { decodeBase64, hashPassword, loadSigningKey, publicKeyFromBase64, randomString, randomToken, sha256, signJson, unpaddedBase64, urlSafeBase64, verifyJsonSignature, verifyPassword };

package/dist/core/delayed.d.ts

@@ -0,0 +1,39 @@
+import { Homeserver } from "../homeserver.js";
+//#region src/core/delayed.d.ts
+export interface DelayedEventsOptions {
+  /** Maximum delay a client may request, in ms. Default: 24 hours. */
+  maxDelayMs?: number;
+  /** Maximum pending delayed events per user. Default: 100. */
+  maxPerUser?: number;
+}
+/**
+ * Delayed events (MSC4140), used by MatrixRTC so that a call membership is removed
+ * when a client disappears. Stored in the database; any instance may send a due
+ * event, and deleting the row first guarantees it is sent exactly once.
+ */
+export declare class DelayedEventService {
+  private hs;
+  private timer;
+  readonly maxDelayMs: number;
+  readonly maxPerUser: number;
+  constructor(hs: Homeserver, options?: DelayedEventsOptions);
+  start(): void;
+  stop(): void;
+  schedule(opts: {
+    userId: string;
+    deviceId: string;
+    roomId: string;
+    type: string;
+    stateKey?: string;
+    content: Record<string, any>;
+    delayMs: number;
+    txnId?: string;
+  }): Promise<string>;
+  list(userId: string): Promise<Record<string, any>[]>;
+  update(userId: string, delayId: string, action: string): Promise<void>;
+  /** Cancel pending delayed state events for a key overwritten by someone else (MSC4140). */
+  onStateEvent(roomId: string, type: string, stateKey: string, sender: string): Promise<void>;
+  private tick;
+  private send;
+}
+//#endregion

package/dist/core/delayed.js

@@ -0,0 +1,160 @@
+import { randomString } from "./crypto.js";
+import { UNSTABLE } from "./m.js";
+import { MatrixError, errors } from "./errors.js";
+//#region src/core/delayed.ts
+/**
+* Delayed events (MSC4140), used by MatrixRTC so that a call membership is removed
+* when a client disappears. Stored in the database; any instance may send a due
+* event, and deleting the row first guarantees it is sent exactly once.
+*/
+var DelayedEventService = class {
+	hs;
+	timer = null;
+	maxDelayMs;
+	maxPerUser;
+	constructor(hs, options = {}) {
+		this.hs = hs;
+		this.maxDelayMs = options.maxDelayMs ?? 864e5;
+		this.maxPerUser = options.maxPerUser ?? 100;
+	}
+	start() {
+		if (this.timer) return;
+		this.timer = setInterval(() => void this.tick().catch((err) => this.hs.logger.warn("Delayed events failed", err)), 250);
+		this.timer.unref?.();
+	}
+	stop() {
+		if (this.timer) clearInterval(this.timer);
+		this.timer = null;
+	}
+	async schedule(opts) {
+		if (!Number.isInteger(opts.delayMs) || opts.delayMs < 0) throw errors.invalidParam("Invalid delay");
+		if (opts.delayMs > this.maxDelayMs) throw new MatrixError(400, "M_MAX_DELAY_EXCEEDED", "Delay is too long", { [UNSTABLE.ORG.MATRIX.MSC4140.MAX_DELAY]: this.maxDelayMs });
+		const txnKey = opts.txnId ? `${opts.userId}|${opts.deviceId}|${opts.roomId}|${opts.txnId}` : null;
+		if (txnKey) {
+			const existing = await this.hs.db.findOne("delayed_events", [{
+				field: "txn_key",
+				value: txnKey
+			}]);
+			if (existing) return existing.delay_id;
+		}
+		if ((await this.hs.db.findMany("delayed_events", { where: [{
+			field: "user_id",
+			value: opts.userId
+		}] })).length >= this.maxPerUser) throw new MatrixError(400, "M_LIMIT_EXCEEDED", "Too many delayed events");
+		await this.hs.rooms.requireJoined(opts.roomId, opts.userId);
+		const delayId = `syd_${randomString(20)}`;
+		const now = Date.now();
+		await this.hs.db.create("delayed_events", {
+			delay_id: delayId,
+			user_id: opts.userId,
+			device_id: opts.deviceId,
+			room_id: opts.roomId,
+			event_type: opts.type,
+			state_key: opts.stateKey ?? null,
+			content: opts.content,
+			delay_ms: opts.delayMs,
+			send_at: now + opts.delayMs,
+			running_since: now,
+			txn_key: txnKey
+		});
+		return delayId;
+	}
+	async list(userId) {
+		return (await this.hs.db.findMany("delayed_events", {
+			where: [{
+				field: "user_id",
+				value: userId
+			}],
+			sortBy: {
+				field: "send_at",
+				direction: "asc"
+			}
+		})).map((r) => ({
+			delay_id: r.delay_id,
+			room_id: r.room_id,
+			type: r.event_type,
+			...r.state_key !== null ? { state_key: r.state_key } : {},
+			delay: r.delay_ms,
+			running_since: r.running_since,
+			content: r.content
+		}));
+	}
+	async update(userId, delayId, action) {
+		if (![
+			"cancel",
+			"restart",
+			"send"
+		].includes(action)) throw errors.unrecognized("Unknown action");
+		const where = [{
+			field: "delay_id",
+			value: delayId
+		}, {
+			field: "user_id",
+			value: userId
+		}];
+		const row = await this.hs.db.findOne("delayed_events", where);
+		if (!row) throw errors.notFound("Unknown delayed event");
+		if (action === "cancel") await this.hs.db.delete("delayed_events", where);
+		else if (action === "restart") {
+			const now = Date.now();
+			await this.hs.db.update("delayed_events", where, {
+				send_at: now + row.delay_ms,
+				running_since: now
+			});
+		} else if (await this.hs.db.delete("delayed_events", where)) await this.send(row);
+	}
+	/** Cancel pending delayed state events for a key overwritten by someone else (MSC4140). */
+	async onStateEvent(roomId, type, stateKey, sender) {
+		const rows = await this.hs.db.findMany("delayed_events", { where: [
+			{
+				field: "room_id",
+				value: roomId
+			},
+			{
+				field: "event_type",
+				value: type
+			},
+			{
+				field: "state_key",
+				value: stateKey
+			}
+		] });
+		for (const r of rows) if (r.user_id !== sender) await this.hs.db.delete("delayed_events", [{
+			field: "delay_id",
+			value: r.delay_id
+		}]);
+	}
+	async tick() {
+		const due = await this.hs.db.findMany("delayed_events", {
+			where: [{
+				field: "send_at",
+				operator: "lte",
+				value: Date.now()
+			}],
+			sortBy: {
+				field: "send_at",
+				direction: "asc"
+			},
+			limit: 100
+		});
+		for (const row of due) {
+			if (!await this.hs.db.delete("delayed_events", [{
+				field: "delay_id",
+				value: row.delay_id
+			}, {
+				field: "send_at",
+				value: row.send_at
+			}])) continue;
+			await this.send(row).catch((err) => this.hs.logger.warn("Sending delayed event failed", row.delay_id, err));
+		}
+	}
+	async send(row) {
+		await this.hs.rooms.sendEvent(row.room_id, row.user_id, {
+			type: row.event_type,
+			content: row.content,
+			...row.state_key !== null ? { state_key: row.state_key } : {}
+		});
+	}
+};
+//#endregion
+export { DelayedEventService };

package/dist/core/errors.d.ts

@@ -0,0 +1,9 @@
+//#region src/core/errors.d.ts
+export declare class MatrixError extends Error {
+  readonly status: number;
+  readonly errcode: string;
+  readonly extra: Record<string, unknown>;
+  constructor(status: number, errcode: string, message: string, extra?: Record<string, unknown>);
+  toJSON(): Record<string, unknown>;
+}
+//#endregion

package/dist/core/errors.js

@@ -0,0 +1,45 @@
+//#region src/core/errors.ts
+var MatrixError = class extends Error {
+	status;
+	errcode;
+	extra;
+	constructor(status, errcode, message, extra = {}) {
+		super(message);
+		this.status = status;
+		this.errcode = errcode;
+		this.extra = extra;
+	}
+	toJSON() {
+		return {
+			errcode: this.errcode,
+			error: this.message,
+			...this.extra
+		};
+	}
+};
+const errors = {
+	forbidden: (msg = "Forbidden") => new MatrixError(403, "M_FORBIDDEN", msg),
+	notFound: (msg = "Not found") => new MatrixError(404, "M_NOT_FOUND", msg),
+	unrecognized: (msg = "Unrecognized request") => new MatrixError(404, "M_UNRECOGNIZED", msg),
+	badJson: (msg = "Bad JSON") => new MatrixError(400, "M_BAD_JSON", msg),
+	notJson: (msg = "Content not JSON") => new MatrixError(400, "M_NOT_JSON", msg),
+	missingParam: (msg = "Missing parameter") => new MatrixError(400, "M_MISSING_PARAM", msg),
+	invalidParam: (msg = "Invalid parameter") => new MatrixError(400, "M_INVALID_PARAM", msg),
+	unknownToken: (msg = "Unknown access token", softLogout = false) => new MatrixError(401, "M_UNKNOWN_TOKEN", msg, { soft_logout: softLogout }),
+	userLocked: (msg = "This account has been locked") => new MatrixError(401, "M_USER_LOCKED", msg, { soft_logout: true }),
+	userSuspended: (msg = "You cannot perform this action while suspended.") => new MatrixError(403, "M_USER_SUSPENDED", msg),
+	missingToken: () => new MatrixError(401, "M_MISSING_TOKEN", "Missing access token"),
+	userInUse: () => new MatrixError(400, "M_USER_IN_USE", "User ID already taken"),
+	invalidUsername: (msg = "Invalid username") => new MatrixError(400, "M_INVALID_USERNAME", msg),
+	roomInUse: () => new MatrixError(400, "M_ROOM_IN_USE", "Room alias already taken"),
+	tooLarge: (msg = "Too large") => new MatrixError(413, "M_TOO_LARGE", msg),
+	unsupportedRoomVersion: () => new MatrixError(400, "M_UNSUPPORTED_ROOM_VERSION", "Unsupported room version"),
+	unknown: (msg = "Unknown error") => new MatrixError(400, "M_UNKNOWN", msg),
+	limitExceeded: () => new MatrixError(429, "M_LIMIT_EXCEEDED", "Too many requests"),
+	userDeactivated: () => new MatrixError(403, "M_USER_DEACTIVATED", "User is deactivated"),
+	invalidRoomState: (msg = "Invalid room state") => new MatrixError(400, "M_INVALID_ROOM_STATE", msg),
+	exclusive: (msg = "Exclusive namespace") => new MatrixError(400, "M_EXCLUSIVE", msg),
+	threepidDenied: () => new MatrixError(403, "M_THREEPID_DENIED", "Third party identifiers are not supported")
+};
+//#endregion
+export { MatrixError, errors };

package/dist/core/events.d.ts

@@ -0,0 +1,32 @@
+//#region src/core/events.d.ts
+export interface PDU {
+  event_id?: string;
+  room_id: string;
+  sender: string;
+  type: string;
+  state_key?: string;
+  content: Record<string, any>;
+  origin_server_ts: number;
+  depth: number;
+  prev_events: any[];
+  auth_events: any[];
+  redacts?: string;
+  hashes?: {
+    sha256: string;
+  };
+  signatures?: Record<string, Record<string, string>>;
+  unsigned?: Record<string, any>;
+  origin?: string;
+}
+export interface ClientEvent {
+  event_id: string;
+  room_id?: string;
+  sender: string;
+  type: string;
+  state_key?: string;
+  content: Record<string, any>;
+  origin_server_ts: number;
+  unsigned?: Record<string, any>;
+  redacts?: string;
+}
+//#endregion