matrix-nodejs-homeserver 0.0.0-stage → 0.3.1

package/dist/core/appservices.js

@@ -0,0 +1,369 @@
+import { M, UNSTABLE } from "./m.js";
+import { splitStateKey, toClientEvent } from "./events.js";
+import { MatrixError, errors } from "./errors.js";
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+//#region src/core/appservices.ts
+const compile = (ns = []) => ns.map((n) => ({
+	exclusive: !!n.exclusive,
+	re: new RegExp(`^(?:${n.regex})$`)
+}));
+/**
+* Parse an application service registration file. Accepts JSON or the YAML subset
+* used by registration files (nested mappings and lists of mappings, scalars).
+*/
+function parseAppServiceRegistration(text) {
+	const trimmed = text.trim();
+	if (trimmed.startsWith("{")) return JSON.parse(trimmed);
+	return parseSimpleYaml(text);
+}
+function parseScalar(raw) {
+	const v = raw.trim();
+	if (v === "" || v === "~" || v === "null") return null;
+	if (v === "true") return true;
+	if (v === "false") return false;
+	if (v === "[]") return [];
+	if (v === "{}") return {};
+	if (/^-?\d+(\.\d+)?$/.test(v)) return Number(v);
+	if (v.startsWith("\"") && v.endsWith("\"")) return JSON.parse(v);
+	if (v.startsWith("'") && v.endsWith("'")) return v.slice(1, -1).replace(/''/g, "'");
+	if (v.startsWith("[") && v.endsWith("]")) return v.slice(1, -1).split(",").map((x) => parseScalar(x)).filter((x) => x !== null);
+	return v;
+}
+/**
+* Remove a `# comment` (at the start of the line, or after whitespace).
+* Security (https://github.com/k18k/matrix-nodejs-homeserver/issues/4): this was the regex `/\s+#.*$/`, polynomial on long whitespace runs (ReDoS,
+* CWE-1333); registration files are operator-provided, but a malformed one could hang startup.
+*/
+function stripComment(line) {
+	for (let i = 0; i < line.length; i++) if (line[i] === "#" && (i === 0 || /\s/.test(line[i - 1]))) return line.slice(0, i).trimEnd();
+	return line;
+}
+/** Minimal YAML reader (indentation-based maps, "- " lists, scalars, comments). */
+function parseSimpleYaml(text) {
+	const lines = text.split(/\r?\n/).map(stripComment).filter((l) => l.trim() !== "").map((l) => ({
+		indent: l.length - l.trimStart().length,
+		text: l.trim()
+	}));
+	let i = 0;
+	const parseBlock = (indent) => {
+		if (i < lines.length && lines[i].text.startsWith("- ")) {
+			const list = [];
+			while (i < lines.length && lines[i].indent === indent && lines[i].text.startsWith("- ")) {
+				const rest = lines[i].text.slice(2);
+				if (/^[\w.-]+:/.test(rest)) {
+					lines[i] = {
+						indent: indent + 2,
+						text: rest
+					};
+					list.push(parseBlock(indent + 2));
+				} else {
+					list.push(parseScalar(rest));
+					i++;
+				}
+			}
+			return list;
+		}
+		const obj = {};
+		while (i < lines.length && lines[i].indent === indent && !lines[i].text.startsWith("- ")) {
+			const m = /^([^:]+):\s*(.*)$/.exec(lines[i].text);
+			if (!m) {
+				i++;
+				continue;
+			}
+			const key = m[1].trim().replace(/^["']|["']$/g, "");
+			i++;
+			if (m[2] !== "") obj[key] = parseScalar(m[2]);
+			else if (i < lines.length && (lines[i].indent > indent || lines[i].indent === indent && lines[i].text.startsWith("- "))) obj[key] = parseBlock(lines[i].indent);
+			else obj[key] = null;
+		}
+		return obj;
+	};
+	return parseBlock(lines[0]?.indent ?? 0);
+}
+/** Load every *.yaml / *.yml / *.json registration in a directory. */
+async function loadAppServiceRegistrations(directory) {
+	let names;
+	try {
+		names = await readdir(directory);
+	} catch {
+		return [];
+	}
+	const out = [];
+	for (const name of names.filter((n) => /\.(ya?ml|json)$/.test(n)).sort()) out.push(parseAppServiceRegistration(await readFile(join(directory, name), "utf8")));
+	return out;
+}
+/** Application Service API: authentication, namespaces, event push and queries. */
+var AppServiceService = class {
+	hs;
+	services;
+	timers = /* @__PURE__ */ new Map();
+	constructor(hs, registrations) {
+		this.hs = hs;
+		this.services = registrations.map((reg) => ({
+			reg,
+			users: compile(reg.namespaces?.users),
+			aliases: compile(reg.namespaces?.aliases),
+			rooms: compile(reg.namespaces?.rooms)
+		}));
+	}
+	get registrations() {
+		return this.services.map((s) => s.reg);
+	}
+	byToken(token) {
+		return this.services.find((s) => s.reg.as_token === token)?.reg ?? null;
+	}
+	byId(id) {
+		return this.services.find((s) => s.reg.id === id)?.reg ?? null;
+	}
+	senderOf(reg) {
+		return `@${reg.sender_localpart}:${this.hs.serverName}`;
+	}
+	compiled(reg) {
+		return this.services.find((s) => s.reg === reg);
+	}
+	/** Whether the AS owns this user ID (its sender or its user namespace). */
+	isInterestedUser(reg, userId) {
+		return userId === this.senderOf(reg) || this.hs.isLocalUser(userId) && this.compiled(reg).users.some((n) => n.re.test(userId));
+	}
+	/** An exclusive namespace owned by some AS (other than `except`) covers this user ID. */
+	exclusiveUserOwner(userId) {
+		return this.services.find((s) => s.users.some((n) => n.exclusive && n.re.test(userId)))?.reg ?? null;
+	}
+	exclusiveAliasOwner(alias) {
+		return this.services.find((s) => s.aliases.some((n) => n.exclusive && n.re.test(alias)))?.reg ?? null;
+	}
+	/** Resolve the user an AS request acts as (masquerading with `user_id`). */
+	async masquerade(reg, userIdParam) {
+		const userId = userIdParam ?? this.senderOf(reg);
+		if (!this.isInterestedUser(reg, userId)) throw errors.forbidden("Application service cannot masquerade as this user");
+		if (userId === this.senderOf(reg) && !await this.hs.db.findOne("users", [{
+			field: "user_id",
+			value: userId
+		}])) await this.hs.db.create("users", {
+			user_id: userId,
+			localpart: reg.sender_localpart,
+			password_hash: null,
+			displayname: reg.sender_localpart,
+			avatar_url: null,
+			is_guest: false,
+			is_admin: false,
+			deactivated: false,
+			created_ts: Date.now()
+		});
+		if (!await this.hs.db.findOne("users", [{
+			field: "user_id",
+			value: userId
+		}])) throw errors.forbidden("Application service has not registered this user");
+		return userId;
+	}
+	async interestedInEvent(svc, pdu, state) {
+		const reg = svc.reg;
+		if (this.isInterestedUser(reg, pdu.sender)) return true;
+		if (pdu.type === M.ROOM.MEMBER && typeof pdu.state_key === "string" && this.isInterestedUser(reg, pdu.state_key)) return true;
+		if (svc.rooms.some((n) => n.re.test(pdu.room_id))) return true;
+		if (svc.aliases.length) {
+			if ((await this.hs.db.findMany("room_aliases", { where: [{
+				field: "room_id",
+				value: pdu.room_id
+			}] })).some((a) => svc.aliases.some((n) => n.re.test(a.alias)))) return true;
+		}
+		for (const [key, ev] of state) {
+			const [type, userId] = splitStateKey(key);
+			if (type === M.ROOM.MEMBER && ev.content?.membership === "join" && this.isInterestedUser(reg, userId)) return true;
+		}
+		return false;
+	}
+	/** Queue an event for every interested application service. */
+	async onEvent(pdu, state) {
+		for (const svc of this.services) {
+			if (!svc.reg.url || !await this.interestedInEvent(svc, pdu, state)) continue;
+			await this.enqueue(svc.reg, "event", toClientEvent(pdu));
+		}
+	}
+	/** Queue an ephemeral event (typing/receipt/presence) for interested services that asked for them. */
+	async onEphemeral(roomId, event, users) {
+		for (const svc of this.services) {
+			const reg = svc.reg;
+			if (!reg.url || !(reg.receive_ephemeral || reg[UNSTABLE.DE.SORUNOME.MSC2409.PUSH_EPHEMERAL])) continue;
+			let interested = users.some((u) => this.isInterestedUser(reg, u)) || roomId !== null && svc.rooms.some((n) => n.re.test(roomId));
+			if (!interested && roomId) {
+				for (const u of await this.hs.rooms.joinedMembers(roomId)) if (this.isInterestedUser(reg, u)) {
+					interested = true;
+					break;
+				}
+			}
+			if (interested) await this.enqueue(reg, "ephemeral", roomId ? {
+				...event,
+				room_id: roomId
+			} : event);
+		}
+	}
+	async enqueue(reg, kind, payload) {
+		const id = await this.hs.cluster.nextId("appservice_outbox");
+		await this.hs.db.create("appservice_outbox", {
+			id,
+			as_id: reg.id,
+			kind,
+			payload,
+			created_ts: Date.now()
+		});
+		this.schedule(reg.id, 0);
+	}
+	schedule(asId, delay) {
+		if (this.hs.isClosed || this.timers.has(asId) && delay > 0) return;
+		const existing = this.timers.get(asId);
+		if (existing) clearTimeout(existing);
+		const timer = setTimeout(() => {
+			this.timers.delete(asId);
+			this.flush(asId).catch((err) => this.hs.logger.debug("Appservice flush failed", err));
+		}, delay);
+		timer.unref?.();
+		this.timers.set(asId, timer);
+	}
+	retries = /* @__PURE__ */ new Map();
+	async flush(asId) {
+		const reg = this.byId(asId);
+		if (!reg?.url) return;
+		await this.hs.cluster.lock(`appservice:${asId}`, async () => {
+			for (;;) {
+				const rows = await this.hs.db.findMany("appservice_outbox", {
+					where: [{
+						field: "as_id",
+						value: asId
+					}],
+					sortBy: {
+						field: "id",
+						direction: "asc"
+					},
+					limit: 100
+				});
+				if (!rows.length) return;
+				const body = { events: rows.filter((r) => r.kind === "event").map((r) => r.payload) };
+				const ephemeral = rows.filter((r) => r.kind === "ephemeral").map((r) => r.payload);
+				if (ephemeral.length) {
+					body.ephemeral = ephemeral;
+					body[UNSTABLE.DE.SORUNOME.MSC2409.EPHEMERAL] = ephemeral;
+				}
+				const txnId = String(rows[rows.length - 1].id);
+				try {
+					const res = await this.hs.fetch(`${reg.url.replace(/\/$/, "")}/_matrix/app/v1/transactions/${txnId}`, {
+						method: "PUT",
+						headers: {
+							"content-type": "application/json",
+							authorization: `Bearer ${reg.hs_token}`
+						},
+						body: JSON.stringify(body),
+						signal: AbortSignal.timeout(3e4)
+					});
+					if (!res.ok) throw new Error(`Application service returned ${res.status}`);
+				} catch (err) {
+					const n = (this.retries.get(asId) ?? 0) + 1;
+					this.retries.set(asId, n);
+					this.schedule(asId, Math.min(1e3 * 2 ** n, 3e5));
+					this.hs.logger.debug("Appservice", asId, "unreachable", err);
+					return;
+				}
+				this.retries.delete(asId);
+				await this.hs.db.delete("appservice_outbox", [{
+					field: "id",
+					operator: "in",
+					value: rows.map((r) => r.id)
+				}]);
+			}
+		});
+	}
+	start() {
+		for (const s of this.services) if (s.reg.url) this.schedule(s.reg.id, 0);
+	}
+	stop() {
+		for (const t of this.timers.values()) clearTimeout(t);
+		this.timers.clear();
+	}
+	async query(reg, path) {
+		if (!reg.url) return null;
+		try {
+			return await this.hs.fetch(`${reg.url.replace(/\/$/, "")}${path}`, {
+				headers: { authorization: `Bearer ${reg.hs_token}` },
+				signal: AbortSignal.timeout(1e4)
+			});
+		} catch {
+			return null;
+		}
+	}
+	/** Ask the owning AS whether a user exists (it may create it). */
+	async queryUser(userId) {
+		for (const svc of this.services) {
+			if (!svc.users.some((n) => n.re.test(userId))) continue;
+			if ((await this.query(svc.reg, `/_matrix/app/v1/users/${encodeURIComponent(userId)}`))?.ok && await this.hs.db.findOne("users", [{
+				field: "user_id",
+				value: userId
+			}])) return true;
+		}
+		return false;
+	}
+	/** Ask the owning AS about an alias; returns the room ID if it now exists. */
+	async queryAlias(alias) {
+		for (const svc of this.services) {
+			if (!svc.aliases.some((n) => n.re.test(alias))) continue;
+			if ((await this.query(svc.reg, `/_matrix/app/v1/rooms/${encodeURIComponent(alias)}`))?.ok) {
+				const row = await this.hs.db.findOne("room_aliases", [{
+					field: "alias",
+					value: alias
+				}]);
+				if (row) return row.room_id;
+			}
+		}
+		return null;
+	}
+	async ping(reg, transactionId) {
+		if (!reg.url) throw new MatrixError(400, "M_URL_NOT_SET", "Application service has no URL");
+		const started = Date.now();
+		let res;
+		try {
+			res = await this.hs.fetch(`${reg.url.replace(/\/$/, "")}/_matrix/app/v1/ping`, {
+				method: "POST",
+				headers: {
+					"content-type": "application/json",
+					authorization: `Bearer ${reg.hs_token}`
+				},
+				body: JSON.stringify(transactionId ? { transaction_id: transactionId } : {}),
+				signal: AbortSignal.timeout(3e4)
+			});
+		} catch (err) {
+			throw new MatrixError(502, "M_CONNECTION_FAILED", `Could not reach the application service: ${err.message}`);
+		}
+		if (!res.ok) throw new MatrixError(502, "M_BAD_STATUS", "Application service returned an error", {
+			status: res.status,
+			body: await res.text().catch(() => "")
+		});
+		return Date.now() - started;
+	}
+	async thirdParty(path, query) {
+		const results = [];
+		for (const svc of this.services) {
+			const res = await this.query(svc.reg, `/_matrix/app/v1/thirdparty/${path}${query.toString() ? `?${query}` : ""}`);
+			if (res?.ok) {
+				const body = await res.json().catch(() => null);
+				if (Array.isArray(body)) results.push(...body);
+			}
+		}
+		return results;
+	}
+	async protocols() {
+		const out = {};
+		for (const svc of this.services) for (const protocol of svc.reg.protocols ?? []) {
+			const res = await this.query(svc.reg, `/_matrix/app/v1/thirdparty/protocol/${encodeURIComponent(protocol)}`);
+			out[protocol] = (res?.ok ? await res.json().catch(() => null) : null) ?? {
+				user_fields: [],
+				location_fields: [],
+				icon: "",
+				field_types: {},
+				instances: []
+			};
+		}
+		return out;
+	}
+};
+//#endregion
+export { AppServiceService, loadAppServiceRegistrations, parseAppServiceRegistration };

package/dist/core/audit.d.ts

@@ -0,0 +1,50 @@
+import { Row } from "../storage/types.js";
+import { Homeserver } from "../homeserver.js";
+//#region src/core/audit.d.ts
+/** Security-relevant actions recorded in the audit log. */
+export type AuditAction = "login" | "login_failed" | "logout" | "register" | "password_change" | "deactivate" | "device_create" | "device_delete" | "token_refresh" | "room_create" | "room_delete" | "member_kick" | "member_ban" | "member_unban" | "admin_action" | "admin_command" | "registration_token_create" | "registration_token_delete" | "registration_setting" | "event_report" | "user_report" | "sso_login" | "oauth_login" | "user_lock" | "user_unlock" | "user_suspend" | "user_unsuspend";
+export interface AuditEntry {
+  action: AuditAction;
+  /** User (or "server") performing the action. */
+  actor: string | null;
+  /** Subject of the action (user, room, token…). */
+  target?: string | null;
+  ip?: string | null;
+  userAgent?: string | null;
+  outcome?: "success" | "failure";
+  details?: Record<string, unknown>;
+}
+export interface AuditOptions {
+  /** Enable the audit log. Default: false. */
+  enabled?: boolean;
+  /** Store entries in the database (queryable via the admin API). Default: true. */
+  database?: boolean;
+  /** Additional sink, e.g. to forward to a SIEM. Errors are logged, never thrown. */
+  sink?: (entry: AuditEntry & {
+    ts: number;
+    id: number;
+  }) => void | Promise<void>;
+  /** Only record these actions. Default: all. */
+  actions?: AuditAction[];
+  /** Delete database entries older than this many days. Default: 365. `0` keeps them forever. */
+  retentionDays?: number;
+}
+/** Audit log of security-relevant actions (logins, account changes, admin actions…). */
+export declare class AuditService {
+  private hs;
+  readonly options: AuditOptions;
+  constructor(hs: Homeserver, options?: AuditOptions);
+  get enabled(): boolean;
+  /** Record an entry. Never throws: auditing must not break the action being audited. */
+  record(entry: AuditEntry): Promise<void>;
+  query(opts?: {
+    actor?: string;
+    target?: string;
+    action?: string;
+    since?: number;
+    before?: number;
+    limit?: number;
+  }): Promise<Row[]>;
+  prune(): Promise<void>;
+}
+//#endregion

package/dist/core/audit.js

@@ -0,0 +1,86 @@
+//#region src/core/audit.ts
+/** Audit log of security-relevant actions (logins, account changes, admin actions…). */
+var AuditService = class {
+	hs;
+	options;
+	constructor(hs, options = {}) {
+		this.hs = hs;
+		this.options = options;
+	}
+	get enabled() {
+		return !!this.options.enabled;
+	}
+	/** Record an entry. Never throws: auditing must not break the action being audited. */
+	async record(entry) {
+		if (!this.options.enabled) return;
+		if (this.options.actions && !this.options.actions.includes(entry.action)) return;
+		try {
+			const id = await this.hs.cluster.nextId("audit_log");
+			const ts = Date.now();
+			const row = {
+				id,
+				ts,
+				action: entry.action,
+				actor: entry.actor ?? null,
+				target: entry.target ?? null,
+				ip: entry.ip ?? null,
+				user_agent: entry.userAgent ?? null,
+				outcome: entry.outcome ?? "success",
+				details: entry.details ?? {}
+			};
+			if (this.options.database !== false) await this.hs.db.create("audit_log", row);
+			await this.options.sink?.({
+				...entry,
+				outcome: row.outcome,
+				id,
+				ts
+			});
+		} catch (err) {
+			this.hs.logger.error("Failed to write audit log entry", err);
+		}
+	}
+	async query(opts = {}) {
+		const where = [];
+		if (opts.actor) where.push({
+			field: "actor",
+			value: opts.actor
+		});
+		if (opts.target) where.push({
+			field: "target",
+			value: opts.target
+		});
+		if (opts.action) where.push({
+			field: "action",
+			value: opts.action
+		});
+		if (opts.since) where.push({
+			field: "ts",
+			operator: "gte",
+			value: opts.since
+		});
+		if (opts.before) where.push({
+			field: "id",
+			operator: "lt",
+			value: opts.before
+		});
+		return this.hs.db.findMany("audit_log", {
+			where,
+			sortBy: {
+				field: "id",
+				direction: "desc"
+			},
+			limit: Math.min(opts.limit ?? 100, 1e3)
+		});
+	}
+	async prune() {
+		const days = this.options.retentionDays ?? 365;
+		if (!this.options.enabled || days <= 0) return;
+		await this.hs.db.delete("audit_log", [{
+			field: "ts",
+			operator: "lt",
+			value: Date.now() - days * 864e5
+		}]);
+	}
+};
+//#endregion
+export { AuditService };

package/dist/core/auth.d.ts

@@ -0,0 +1,48 @@
+import { AppServiceRegistration } from "./appservices.js";
+import { Homeserver } from "../homeserver.js";
+//#region src/core/auth.d.ts
+export interface Session {
+  userId: string;
+  deviceId: string;
+  accessToken: string;
+  isGuest: boolean;
+  isAdmin: boolean;
+  /** The account is locked: only logging out is allowed. */
+  locked?: boolean;
+  /** The account is suspended: see `assertNotSuspended`. */
+  suspended?: boolean;
+  /** Set when the request was made with an application service token. */
+  appservice?: AppServiceRegistration;
+}
+export interface CreatedSession {
+  user_id: string;
+  device_id: string;
+  access_token: string;
+  refresh_token?: string;
+  expires_in_ms?: number;
+}
+export declare class AuthService {
+  private hs;
+  private cache;
+  constructor(hs: Homeserver);
+  authenticate(token: string, ip: string | null): Promise<Session>;
+  /** Create (or reuse) a device and issue a fresh access token for it. */
+  createSession(userId: string, opts?: {
+    deviceId?: string;
+    displayName?: string;
+    refreshToken?: boolean;
+  }): Promise<CreatedSession>;
+  issueToken(userId: string, deviceId: string, withRefresh: boolean): Promise<CreatedSession>;
+  refresh(refreshToken: string): Promise<CreatedSession>;
+  /** Drop cached sessions of a user (after admin/deactivation changes). */
+  invalidateUser(userId: string): Promise<void>;
+  /** Issue a short-lived single-use `m.login.token` for a user (SSO, or host-app sign-in). */
+  createLoginToken(userId: string, ttlMs?: number): Promise<string>;
+  /** Redeem a login token; returns the user ID or throws. */
+  consumeLoginToken(token: string): Promise<string>;
+  revokeToken(token: string): Promise<void>;
+  revokeDeviceTokens(userId: string, deviceId: string): Promise<void>;
+  deleteDevice(userId: string, deviceId: string): Promise<void>;
+  deleteAllDevices(userId: string, except?: string): Promise<void>;
+}
+//#endregion