matrix-nodejs-homeserver 0.0.0-stage → 0.3.1

package/dist/core/settings.d.ts

@@ -0,0 +1,11 @@
+import { Homeserver } from "../homeserver.js";
+//#region src/core/settings.d.ts
+/** Runtime server settings changed by admins (stored in the database, shared across instances). */
+export declare class SettingsService {
+  private hs;
+  private cache;
+  constructor(hs: Homeserver);
+  get<T>(key: string): Promise<T | null>;
+  set(key: string, value: unknown): Promise<void>;
+}
+//#endregion

package/dist/core/settings.js

@@ -0,0 +1,29 @@
+//#region src/core/settings.ts
+/** Runtime server settings changed by admins (stored in the database, shared across instances). */
+var SettingsService = class {
+	hs;
+	cache = /* @__PURE__ */ new Map();
+	constructor(hs) {
+		this.hs = hs;
+		hs.cluster.subscribe("settings", (msg) => this.cache.delete(msg?.key));
+	}
+	async get(key) {
+		if (this.cache.has(key)) return this.cache.get(key);
+		const value = (await this.hs.db.findOne("server_settings", [{
+			field: "key",
+			value: key
+		}]))?.value ?? null;
+		this.cache.set(key, value);
+		return value;
+	}
+	async set(key, value) {
+		await this.hs.db.upsert("server_settings", {
+			key,
+			value
+		});
+		this.cache.set(key, value);
+		await this.hs.cluster.publish("settings", { key });
+	}
+};
+//#endregion
+export { SettingsService };

package/dist/core/sso.d.ts

@@ -0,0 +1,46 @@
+import { Homeserver } from "../homeserver.js";
+//#region src/core/sso.d.ts
+/** An upstream OpenID Connect provider for `m.login.sso`. */
+export interface SsoProvider {
+  /** Stable identifier, used in URLs and stored with linked accounts. */
+  id: string;
+  name: string;
+  issuer: string;
+  clientId: string;
+  clientSecret?: string;
+  /** Default: ["openid", "profile", "email"]. */
+  scopes?: string[];
+  icon?: string;
+  brand?: string;
+  /**
+   * Map ID token / userinfo claims to a Matrix account. Return a localpart and optional
+   * display name, or null to refuse login. Default: sanitised `preferred_username`, then `sub`.
+   */
+  mapUser?: (claims: Record<string, any>) => {
+    localpart: string;
+    displayname?: string;
+  } | null | Promise<{
+    localpart: string;
+    displayname?: string;
+  } | null>;
+  /** Create accounts for unknown users. Default: true. */
+  allowRegistration?: boolean;
+}
+export interface SsoOptions {
+  providers: SsoProvider[];
+}
+/** Upstream OIDC login (authorization code + PKCE) issuing Matrix login tokens. */
+export declare class SsoService {
+  private hs;
+  readonly providers: SsoProvider[];
+  private discovery;
+  constructor(hs: Homeserver, options: SsoOptions);
+  private callbackUrl;
+  private discover;
+  /** URL to send the user's browser to. */
+  startLogin(providerId: string | null, redirectUrl: string): Promise<string>;
+  /** Handle the provider's redirect; returns the client URL carrying a login token. */
+  finishLogin(providerId: string, params: URLSearchParams): Promise<string>;
+  private resolveUser;
+}
+//#endregion

package/dist/core/sso.js

@@ -0,0 +1,165 @@
+import { randomToken, urlSafeBase64 } from "./crypto.js";
+import { errors } from "./errors.js";
+import { LOCALPART_RE } from "./ids.js";
+import { createHash, randomBytes } from "node:crypto";
+//#region src/core/sso.ts
+function sanitizeLocalpart(raw) {
+	return raw.toLowerCase().replace(/[^a-z0-9._=\-/+]/g, "_").slice(0, 200);
+}
+function decodeJwtPayload(jwt) {
+	const part = jwt.split(".")[1];
+	if (!part) throw new Error("Malformed ID token");
+	return JSON.parse(Buffer.from(part, "base64url").toString("utf8"));
+}
+/** Upstream OIDC login (authorization code + PKCE) issuing Matrix login tokens. */
+var SsoService = class {
+	hs;
+	providers;
+	discovery = /* @__PURE__ */ new Map();
+	constructor(hs, options) {
+		this.hs = hs;
+		this.providers = options.providers;
+	}
+	callbackUrl(provider) {
+		const base = this.hs.config.publicBaseUrl;
+		if (!base) throw new Error("publicBaseUrl is required for SSO");
+		return `${base.replace(/\/$/, "")}/_matrix/client/v3/login/sso/callback/${encodeURIComponent(provider.id)}`;
+	}
+	async discover(provider) {
+		const cached = this.discovery.get(provider.id);
+		if (cached) return cached;
+		const res = await this.hs.fetch(`${provider.issuer.replace(/\/$/, "")}/.well-known/openid-configuration`, { signal: AbortSignal.timeout(1e4) });
+		if (!res.ok) throw new Error(`OIDC discovery for ${provider.id} failed with ${res.status}`);
+		const meta = await res.json();
+		this.discovery.set(provider.id, meta);
+		return meta;
+	}
+	/** URL to send the user's browser to. */
+	async startLogin(providerId, redirectUrl) {
+		const provider = providerId ? this.providers.find((p) => p.id === providerId) : this.providers[0];
+		if (!provider) throw errors.notFound("Unknown identity provider");
+		const meta = await this.discover(provider);
+		const state = randomToken(24);
+		const verifier = urlSafeBase64(randomBytes(32));
+		const nonce = randomToken(16);
+		await this.hs.cluster.set(`sso:${state}`, {
+			providerId: provider.id,
+			redirectUrl,
+			verifier,
+			nonce,
+			expires: Date.now() + 6e5
+		}, 6e5);
+		const url = new URL(meta.authorization_endpoint);
+		url.searchParams.set("response_type", "code");
+		url.searchParams.set("client_id", provider.clientId);
+		url.searchParams.set("redirect_uri", this.callbackUrl(provider));
+		url.searchParams.set("scope", (provider.scopes ?? [
+			"openid",
+			"profile",
+			"email"
+		]).join(" "));
+		url.searchParams.set("state", state);
+		url.searchParams.set("nonce", nonce);
+		url.searchParams.set("code_challenge", urlSafeBase64(createHash("sha256").update(verifier).digest()));
+		url.searchParams.set("code_challenge_method", "S256");
+		return url.toString();
+	}
+	/** Handle the provider's redirect; returns the client URL carrying a login token. */
+	async finishLogin(providerId, params) {
+		const state = params.get("state") ?? "";
+		const pending = await this.hs.cluster.get(`sso:${state}`);
+		await this.hs.cluster.delete(`sso:${state}`);
+		if (!pending || pending.expires < Date.now() || pending.providerId !== providerId) throw errors.forbidden("Unknown or expired login attempt");
+		if (params.get("error")) throw errors.forbidden(`Login failed: ${params.get("error")}`);
+		const code = params.get("code");
+		if (!code) throw errors.missingParam("Missing code");
+		const provider = this.providers.find((p) => p.id === providerId);
+		const meta = await this.discover(provider);
+		const body = new URLSearchParams({
+			grant_type: "authorization_code",
+			code,
+			redirect_uri: this.callbackUrl(provider),
+			code_verifier: pending.verifier,
+			client_id: provider.clientId
+		});
+		const headers = {
+			"content-type": "application/x-www-form-urlencoded",
+			accept: "application/json"
+		};
+		if (provider.clientSecret) headers.authorization = `Basic ${Buffer.from(`${encodeURIComponent(provider.clientId)}:${encodeURIComponent(provider.clientSecret)}`).toString("base64")}`;
+		const res = await this.hs.fetch(meta.token_endpoint, {
+			method: "POST",
+			headers,
+			body,
+			signal: AbortSignal.timeout(1e4)
+		});
+		if (!res.ok) throw errors.forbidden("Code exchange failed");
+		const tokens = await res.json();
+		let claims = {};
+		if (typeof tokens.id_token === "string") {
+			claims = decodeJwtPayload(tokens.id_token);
+			const aud = Array.isArray(claims.aud) ? claims.aud : [claims.aud];
+			if (claims.iss !== meta.issuer || !aud.includes(provider.clientId)) throw errors.forbidden("ID token issuer or audience mismatch");
+			if (claims.nonce !== pending.nonce) throw errors.forbidden("ID token nonce mismatch");
+			if (typeof claims.exp === "number" && claims.exp * 1e3 < Date.now()) throw errors.forbidden("ID token expired");
+		}
+		if (meta.userinfo_endpoint && typeof tokens.access_token === "string") {
+			const info = await this.hs.fetch(meta.userinfo_endpoint, {
+				headers: { authorization: `Bearer ${tokens.access_token}` },
+				signal: AbortSignal.timeout(1e4)
+			});
+			if (info.ok) {
+				const userinfo = await info.json();
+				if (claims.sub && userinfo.sub !== claims.sub) throw errors.forbidden("Userinfo subject mismatch");
+				claims = {
+					...userinfo,
+					...claims
+				};
+			}
+		}
+		if (typeof claims.sub !== "string") throw errors.forbidden("Provider did not return a subject");
+		const userId = await this.resolveUser(provider, claims);
+		const loginToken = await this.hs.auth.createLoginToken(userId);
+		await this.hs.audit.record({
+			action: "sso_login",
+			actor: userId,
+			details: {
+				idp: provider.id,
+				subject: claims.sub
+			}
+		});
+		const redirect = new URL(pending.redirectUrl);
+		redirect.searchParams.set("loginToken", loginToken);
+		return redirect.toString();
+	}
+	async resolveUser(provider, claims) {
+		const link = await this.hs.db.findOne("sso_identities", [{
+			field: "idp_id",
+			value: provider.id
+		}, {
+			field: "subject",
+			value: claims.sub
+		}]);
+		if (link) return link.user_id;
+		if (provider.allowRegistration === false) throw errors.forbidden("No account is linked to this identity");
+		const mapped = provider.mapUser ? await provider.mapUser(claims) : {
+			localpart: sanitizeLocalpart(claims.preferred_username ?? claims.sub),
+			displayname: claims.name
+		};
+		if (!mapped || !LOCALPART_RE.test(mapped.localpart)) throw errors.forbidden("Could not map identity to a Matrix user");
+		let localpart = mapped.localpart;
+		for (let i = 1; await this.hs.db.findOne("users", [{
+			field: "user_id",
+			value: `@${localpart}:${this.hs.serverName}`
+		}]); i++) localpart = `${mapped.localpart}${i}`;
+		const userId = await this.hs.admin.createUser(localpart, { displayname: mapped.displayname });
+		await this.hs.db.create("sso_identities", {
+			idp_id: provider.id,
+			subject: claims.sub,
+			user_id: userId
+		});
+		return userId;
+	}
+};
+//#endregion
+export { SsoService };

package/dist/core/stateres.d.ts

@@ -0,0 +1,4 @@
+//#region src/core/stateres.d.ts
+/** A state map of (type, state_key) → event ID. */
+export type StateIds = Record<string, string>;
+//#endregion

package/dist/core/stateres.js

@@ -0,0 +1,209 @@
+import { M } from "./m.js";
+import { eventIdOf, roomVersionFeatures, stateKey } from "./events.js";
+import { authEventKeys, checkAuth, powerLevels, userLevel } from "./authrules.js";
+//#region src/core/stateres.ts
+const isPowerEvent = (ev) => ev.type === M.ROOM.POWER_LEVELS && ev.state_key === "" || ev.type === M.ROOM.JOIN_RULES && ev.state_key === "" || ev.type === M.ROOM.CREATE && ev.state_key === "" || ev.type === M.ROOM.MEMBER && ["leave", "ban"].includes(ev.content?.membership) && ev.sender !== ev.state_key;
+const authIds = (ev) => (ev.auth_events ?? []).map(eventIdOf);
+var EventCache = class {
+	events = /* @__PURE__ */ new Map();
+	source;
+	constructor(source) {
+		this.source = source;
+	}
+	async load(ids) {
+		const missing = [...ids].filter((id) => !this.events.has(id));
+		if (!missing.length) return;
+		for (const [id, ev] of await this.source(missing)) this.events.set(id, ev);
+	}
+	get(id) {
+		return this.events.get(id);
+	}
+	/** All auth ancestors of the given events (not including them). */
+	async authChain(ids) {
+		const chain = /* @__PURE__ */ new Set();
+		let frontier = [...ids];
+		while (frontier.length) {
+			await this.load(frontier);
+			const next = [];
+			for (const id of frontier) {
+				const ev = this.get(id);
+				if (!ev) continue;
+				for (const a of authIds(ev)) if (!chain.has(a)) {
+					chain.add(a);
+					next.push(a);
+				}
+			}
+			frontier = next;
+		}
+		return chain;
+	}
+};
+/**
+* State resolution v2 (and v2.1 for room version 12).
+* `createEvent` is required for v12, where the create event is not in auth_events.
+*/
+async function resolveState(stateSets, roomVersion, source, createEvent) {
+	if (stateSets.length === 0) return {};
+	if (stateSets.length === 1) return { ...stateSets[0] };
+	const v21 = roomVersionFeatures(roomVersion).v12;
+	const cache = new EventCache(source);
+	const keys = new Set(stateSets.flatMap((s) => Object.keys(s)));
+	const unconflicted = {};
+	const conflicted = /* @__PURE__ */ new Set();
+	for (const key of keys) {
+		const values = stateSets.map((s) => s[key]);
+		if (values.every((v) => v !== void 0 && v === values[0])) unconflicted[key] = values[0];
+		else for (const v of values) if (v !== void 0) conflicted.add(v);
+	}
+	if (conflicted.size === 0) return unconflicted;
+	const chains = await Promise.all(stateSets.map((s) => cache.authChain(Object.values(s))));
+	const authDifference = [...new Set(chains.flatMap((c) => [...c]))].filter((id) => !chains.every((c) => c.has(id)));
+	const full = /* @__PURE__ */ new Set([...conflicted, ...authDifference]);
+	if (v21) for (const id of await conflictedSubgraph(cache, conflicted)) full.add(id);
+	await cache.load(full);
+	for (const id of [...full]) if (!cache.get(id)) full.delete(id);
+	const powerEvents = [...full].filter((id) => isPowerEvent(cache.get(id)));
+	const control = new Set(powerEvents);
+	for (const id of await cache.authChain(powerEvents)) if (full.has(id)) control.add(id);
+	let resolved = await iterativeAuthChecks(cache, await reverseTopologicalPowerSort(cache, control, roomVersion, createEvent), v21 ? {} : { ...unconflicted }, roomVersion, createEvent);
+	const remaining = [...full].filter((id) => !control.has(id));
+	const mainline = await mainlineOf(cache, resolved[stateKey(M.ROOM.POWER_LEVELS, "")]);
+	const positions = /* @__PURE__ */ new Map();
+	for (const id of remaining) positions.set(id, await mainlinePosition(cache, id, mainline));
+	remaining.sort((a, b) => {
+		const ea = cache.get(a);
+		const eb = cache.get(b);
+		return positions.get(a) - positions.get(b) || ea.origin_server_ts - eb.origin_server_ts || (a < b ? -1 : a > b ? 1 : 0);
+	});
+	resolved = await iterativeAuthChecks(cache, remaining, resolved, roomVersion, createEvent);
+	return {
+		...resolved,
+		...unconflicted
+	};
+}
+/** v2.1: events on auth paths between two conflicted events. */
+async function conflictedSubgraph(cache, conflicted) {
+	const ancestors = await cache.authChain(conflicted);
+	await cache.load(ancestors);
+	const memo = /* @__PURE__ */ new Map();
+	const reachesConflicted = (id, seen = /* @__PURE__ */ new Set()) => {
+		const cached = memo.get(id);
+		if (cached !== void 0) return cached;
+		if (seen.has(id)) return false;
+		seen.add(id);
+		const ev = cache.get(id);
+		const result = !!ev && authIds(ev).some((a) => conflicted.has(a) || reachesConflicted(a, seen));
+		memo.set(id, result);
+		return result;
+	};
+	const out = /* @__PURE__ */ new Set();
+	for (const id of ancestors) if (!conflicted.has(id) && reachesConflicted(id)) out.add(id);
+	return out;
+}
+/** Power level of an event's sender according to its own auth events. */
+async function senderPowerLevel(cache, ev, roomVersion, createEvent) {
+	await cache.load(authIds(ev));
+	const state = /* @__PURE__ */ new Map();
+	for (const id of authIds(ev)) {
+		const a = cache.get(id);
+		if (a && a.state_key !== void 0) state.set(stateKey(a.type, a.state_key), a);
+	}
+	if (createEvent) state.set(stateKey(M.ROOM.CREATE, ""), createEvent);
+	const level = userLevel(powerLevels(state, roomVersion), ev.sender);
+	return Number.isFinite(level) ? level : Number.MAX_SAFE_INTEGER;
+}
+async function reverseTopologicalPowerSort(cache, ids, roomVersion, createEvent) {
+	const levels = /* @__PURE__ */ new Map();
+	for (const id of ids) levels.set(id, await senderPowerLevel(cache, cache.get(id), roomVersion, createEvent));
+	const pending = /* @__PURE__ */ new Map();
+	const dependents = /* @__PURE__ */ new Map();
+	for (const id of ids) {
+		const deps = new Set(authIds(cache.get(id)).filter((a) => ids.has(a)));
+		pending.set(id, deps);
+		for (const d of deps) (dependents.get(d) ?? dependents.set(d, []).get(d)).push(id);
+	}
+	const compare = (a, b) => {
+		const ea = cache.get(a);
+		const eb = cache.get(b);
+		return levels.get(b) - levels.get(a) || ea.origin_server_ts - eb.origin_server_ts || (a < b ? -1 : a > b ? 1 : 0);
+	};
+	const ready = [...ids].filter((id) => pending.get(id).size === 0).sort(compare);
+	const out = [];
+	while (ready.length) {
+		const id = ready.shift();
+		out.push(id);
+		for (const dep of dependents.get(id) ?? []) {
+			const p = pending.get(dep);
+			p.delete(id);
+			if (p.size === 0) {
+				ready.push(dep);
+				ready.sort(compare);
+			}
+		}
+	}
+	return out;
+}
+async function iterativeAuthChecks(cache, ids, base, roomVersion, createEvent) {
+	const state = { ...base };
+	for (const id of ids) {
+		const ev = cache.get(id);
+		if (!ev || ev.state_key === void 0) continue;
+		await cache.load(authIds(ev));
+		const authState = /* @__PURE__ */ new Map();
+		for (const aid of authIds(ev)) {
+			const a = cache.get(aid);
+			if (a && a.state_key !== void 0) authState.set(stateKey(a.type, a.state_key), a);
+		}
+		const keys = authEventKeys(ev, roomVersion);
+		await cache.load(keys.map((k) => state[k]).filter(Boolean));
+		for (const k of keys) {
+			const sid = state[k];
+			const sev = sid ? cache.get(sid) : void 0;
+			if (sev) authState.set(k, sev);
+		}
+		if (createEvent) authState.set(stateKey(M.ROOM.CREATE, ""), createEvent);
+		try {
+			checkAuth(ev, authState, roomVersion);
+			state[stateKey(ev.type, ev.state_key)] = id;
+		} catch {}
+	}
+	return state;
+}
+async function mainlineOf(cache, plId) {
+	const chain = [];
+	let current = plId;
+	while (current) {
+		chain.push(current);
+		await cache.load([current]);
+		const ev = cache.get(current);
+		if (!ev) break;
+		await cache.load(authIds(ev));
+		current = authIds(ev).find((a) => {
+			const e = cache.get(a);
+			return e?.type === M.ROOM.POWER_LEVELS && e.state_key === "";
+		});
+	}
+	const positions = /* @__PURE__ */ new Map();
+	chain.reverse().forEach((id, i) => positions.set(id, i + 1));
+	return positions;
+}
+async function mainlinePosition(cache, id, mainline) {
+	let current = id;
+	const seen = /* @__PURE__ */ new Set();
+	while (current && !seen.has(current)) {
+		seen.add(current);
+		const pos = mainline.get(current);
+		if (pos !== void 0) return pos;
+		await cache.load([current]);
+		const ev = cache.get(current);
+		if (!ev) return 0;
+		await cache.load(authIds(ev));
+		current = authIds(ev).find((a) => {
+			const e = cache.get(a);
+			return e?.type === M.ROOM.POWER_LEVELS && e.state_key === "";
+		});
+	}
+	return 0;
+}
+//#endregion
+export { resolveState };

package/dist/core/threepid.d.ts

@@ -0,0 +1,80 @@
+import { Homeserver } from "../homeserver.js";
+//#region src/core/threepid.d.ts
+export type Medium = "email" | "msisdn";
+export type ThreepidPurpose = "register" | "password_reset" | "add_threepid";
+export interface ThreepidEmail {
+  to: string;
+  purpose: ThreepidPurpose;
+  subject: string;
+  text: string;
+  html: string;
+  /** Opening this link validates the address. */
+  link: string;
+  token: string;
+}
+export interface ThreepidSms {
+  /** MSISDN (international format, digits only). */
+  to: string;
+  purpose: ThreepidPurpose;
+  text: string;
+  /** Short code the user types into the client. */
+  token: string;
+}
+export interface ThreepidOptions {
+  /** Sends validation emails. Without it, email addresses cannot be added or used to register. */
+  sendEmail?: (message: ThreepidEmail) => Promise<void>;
+  /** Sends validation SMS messages. Without it, phone numbers cannot be added. */
+  sendSms?: (message: ThreepidSms) => Promise<void>;
+  /** Registration requires a validated email address. Needs `sendEmail`. */
+  requireEmailForRegistration?: boolean;
+  /** How long a validation session stays usable, in ms. Default: 24 hours. */
+  sessionLifetimeMs?: number;
+  /** Scheme used to reach identity servers. Default: "https" ("http" is for tests only). */
+  identityServerProtocol?: "https" | "http";
+}
+export interface Threepid {
+  medium: Medium;
+  address: string;
+}
+export declare class ThreepidService {
+  private readonly hs;
+  constructor(hs: Homeserver);
+  private get options();
+  /** Whether this server can validate addresses of `medium` itself. */
+  canValidate(medium: Medium): boolean;
+  /** Account changes involving 3PIDs are possible at all (the m.3pid_changes capability). */
+  get enabled(): boolean;
+  userFor(medium: Medium, address: string): Promise<string | null>;
+  list(userId: string): Promise<{
+    medium: string;
+    address: string;
+    validated_at: number;
+    added_at: number;
+  }[]>;
+  add(userId: string, threepid: Threepid & {
+    validatedTs: number;
+  }): Promise<void>;
+  remove(userId: string, medium: Medium, address: string): Promise<boolean>;
+  /**
+   * Unbind a 3PID from the identity servers it was bound on through this server (or `idServer`).
+   * Returns "success" if every unbind succeeded, "no-support" otherwise.
+   */
+  unbindAll(userId: string, medium: string, address: string, idServer?: string): Promise<"success" | "no-support">;
+  /** Remove every 3PID of a (deactivated) account, unbinding them from identity servers. */
+  removeAll(userId: string): Promise<"success" | "no-support">;
+  /**
+   * Start (or continue) validating an address: `POST .../{medium}/requestToken`. Repeating a
+   * request with the same `client_secret`, address and `send_attempt` does not send again.
+   */
+  requestToken(purpose: ThreepidPurpose, medium: Medium, body: Record<string, any>): Promise<Record<string, unknown>>;
+  private tokenResponse;
+  private send;
+  private expired;
+  /** Validate a session with the token the user received. Returns the session's `next_link`. */
+  submitToken(sid: string, clientSecret: string, token: string): Promise<string | null>;
+  /** The address a client proved ownership of, given its `threepid_creds`. */
+  validated(creds: unknown): Promise<(Threepid & {
+    validatedTs: number;
+  }) | null>;
+}
+//#endregion