matrix-nodejs-homeserver 0.0.0-stage → 0.3.1

package/dist/federation/keyring.d.ts

@@ -0,0 +1,26 @@
+import { Homeserver } from "../homeserver.js";
+import { KeyObject } from "node:crypto";
+//#region src/federation/keyring.d.ts
+/**
+ * Remote server signing keys. Keys are fetched directly from the server
+ * (`/_matrix/key/v2/server`), verified against their self-signature, cached in
+ * memory and persisted in the database.
+ */
+export declare class KeyRing {
+  private hs;
+  private cache;
+  private inflight;
+  constructor(hs: Homeserver);
+  /** Get a verify key, fetching the server's keys when unknown or expired (as of `minValidUntil`). */
+  getKey(serverName: string, keyId: string, minValidUntil?: number): Promise<KeyObject | null>;
+  private remember;
+  private fetchKeys;
+  private doFetch;
+  /** Validate and store a `/_matrix/key/v2/server` response. */
+  ingestServerKeys(serverName: string, body: Record<string, any>): Promise<void>;
+  /** Verify that `obj` carries a valid signature from `serverName`. */
+  verifySignedBy(obj: Record<string, any>, serverName: string, minValidUntil?: number): Promise<boolean>;
+  /** Cached keys in `/_matrix/key/v2/query` format (we act as a basic notary for keys we know). */
+  knownKeys(serverName: string): Promise<Record<string, any>[]>;
+}
+//#endregion

package/dist/federation/keyring.js

@@ -0,0 +1,122 @@
+import { isObject } from "../core/json.js";
+import { publicKeyFromBase64, verifyJsonSignature } from "../core/crypto.js";
+import { createPublicKey } from "node:crypto";
+//#region src/federation/keyring.ts
+/**
+* Remote server signing keys. Keys are fetched directly from the server
+* (`/_matrix/key/v2/server`), verified against their self-signature, cached in
+* memory and persisted in the database.
+*/
+var KeyRing = class {
+	hs;
+	cache = /* @__PURE__ */ new Map();
+	inflight = /* @__PURE__ */ new Map();
+	constructor(hs) {
+		this.hs = hs;
+	}
+	/** Get a verify key, fetching the server's keys when unknown or expired (as of `minValidUntil`). */
+	async getKey(serverName, keyId, minValidUntil = Date.now()) {
+		if (serverName === this.hs.serverName) return keyId === `ed25519:${this.hs.signingKey.keyId}` ? createPublicKey(this.hs.signingKey.privateKey) : null;
+		const cached = this.cache.get(serverName)?.get(keyId);
+		if (cached && cached.validUntil >= minValidUntil) return cached.key;
+		if (!cached) {
+			const row = await this.hs.db.findOne("remote_server_keys", [{
+				field: "server_name",
+				value: serverName
+			}, {
+				field: "key_id",
+				value: keyId
+			}]);
+			if (row) {
+				this.remember(serverName, keyId, row.key, row.valid_until_ts);
+				if (row.valid_until_ts >= minValidUntil) return this.cache.get(serverName).get(keyId).key;
+			}
+		}
+		await this.fetchKeys(serverName);
+		const fetched = this.cache.get(serverName)?.get(keyId);
+		return fetched ? fetched.key : null;
+	}
+	remember(serverName, keyId, key, validUntil) {
+		let m = this.cache.get(serverName);
+		if (!m) this.cache.set(serverName, m = /* @__PURE__ */ new Map());
+		m.set(keyId, {
+			key: publicKeyFromBase64(key),
+			validUntil
+		});
+	}
+	fetchKeys(serverName) {
+		let p = this.inflight.get(serverName);
+		if (!p) {
+			p = this.doFetch(serverName).finally(() => this.inflight.delete(serverName));
+			this.inflight.set(serverName, p);
+		}
+		return p;
+	}
+	async doFetch(serverName) {
+		try {
+			const body = await this.hs.federation.client.request(serverName, "GET", "/_matrix/key/v2/server", { signed: false });
+			await this.ingestServerKeys(serverName, body);
+		} catch (err) {
+			this.hs.logger.debug("Fetching keys for", serverName, "failed", err);
+		}
+	}
+	/** Validate and store a `/_matrix/key/v2/server` response. */
+	async ingestServerKeys(serverName, body) {
+		if (body.server_name !== serverName || !isObject(body.verify_keys)) return;
+		const validUntil = Number(body.valid_until_ts) || 0;
+		const entries = [];
+		for (const [keyId, v] of Object.entries(body.verify_keys)) if (typeof v?.key === "string") entries.push([
+			keyId,
+			v.key,
+			validUntil
+		]);
+		for (const [keyId, v] of Object.entries(isObject(body.old_verify_keys) ? body.old_verify_keys : {})) if (typeof v?.key === "string") entries.push([
+			keyId,
+			v.key,
+			Number(v.expired_ts) || 0
+		]);
+		for (const [keyId, key] of entries.filter(([id]) => id in body.verify_keys)) if (!verifyJsonSignature(body, serverName, keyId, publicKeyFromBase64(key))) return;
+		for (const [keyId, key, until] of entries) {
+			this.remember(serverName, keyId, key, until);
+			await this.hs.db.upsert("remote_server_keys", {
+				server_name: serverName,
+				key_id: keyId,
+				key,
+				valid_until_ts: until
+			});
+		}
+	}
+	/** Verify that `obj` carries a valid signature from `serverName`. */
+	async verifySignedBy(obj, serverName, minValidUntil) {
+		const sigs = obj.signatures?.[serverName];
+		if (!isObject(sigs)) return false;
+		for (const keyId of Object.keys(sigs)) {
+			if (!keyId.startsWith("ed25519:")) continue;
+			const key = await this.getKey(serverName, keyId, minValidUntil);
+			if (key && verifyJsonSignature(obj, serverName, keyId, key)) return true;
+		}
+		return false;
+	}
+	/** Cached keys in `/_matrix/key/v2/query` format (we act as a basic notary for keys we know). */
+	async knownKeys(serverName) {
+		const rows = await this.hs.db.findMany("remote_server_keys", { where: [{
+			field: "server_name",
+			value: serverName
+		}] });
+		if (!rows.length) return [];
+		const verify_keys = {};
+		let until = 0;
+		for (const r of rows) {
+			verify_keys[r.key_id] = { key: r.key };
+			until = Math.max(until, r.valid_until_ts);
+		}
+		return [{
+			server_name: serverName,
+			valid_until_ts: until,
+			verify_keys,
+			old_verify_keys: {}
+		}];
+	}
+};
+//#endregion
+export { KeyRing };

package/dist/federation/sender.d.ts

@@ -0,0 +1,26 @@
+import { Homeserver } from "../homeserver.js";
+//#region src/federation/sender.d.ts
+/**
+ * Outbound transaction queue backed by the database (`federation_outbox`), so any
+ * instance can enqueue and pending items survive restarts. Per destination, one
+ * instance at a time (cluster lock) builds and sends transactions. Failed
+ * destinations back off; ephemeral EDUs (typing, presence) are dropped on failure.
+ */
+export declare class TransactionSender {
+  private hs;
+  private timers;
+  private sweepTimer;
+  constructor(hs: Homeserver);
+  /** Start background sweeping for destinations with pending items (e.g. after a restart). */
+  start(): void;
+  private sweep;
+  sendPdu(destinations: Iterable<string>, pdu: Record<string, any>): Promise<void>;
+  sendEdu(destinations: Iterable<string>, eduType: string, content: Record<string, any>, durable?: boolean): Promise<void>;
+  private enqueue;
+  private schedule;
+  private flush;
+  /** Retry a destination immediately (e.g. after it contacted us). */
+  wake(destination: string): Promise<void>;
+  stop(): void;
+}
+//#endregion

package/dist/federation/sender.js

@@ -0,0 +1,164 @@
+import { randomString } from "../core/crypto.js";
+//#region src/federation/sender.ts
+const MAX_PDUS = 50;
+const MAX_EDUS = 100;
+const MIN_RETRY_MS = 1e3;
+const MAX_RETRY_MS = 36e5;
+/** Destinations that only just went down are retried quickly; long outages back off further. */
+const FAST_RETRY_CAP_MS = 1e4;
+const FAST_RETRY_ATTEMPTS = 10;
+const SWEEP_INTERVAL_MS = 3e4;
+/**
+* Outbound transaction queue backed by the database (`federation_outbox`), so any
+* instance can enqueue and pending items survive restarts. Per destination, one
+* instance at a time (cluster lock) builds and sends transactions. Failed
+* destinations back off; ephemeral EDUs (typing, presence) are dropped on failure.
+*/
+var TransactionSender = class {
+	hs;
+	timers = /* @__PURE__ */ new Map();
+	sweepTimer = null;
+	constructor(hs) {
+		this.hs = hs;
+	}
+	/** Start background sweeping for destinations with pending items (e.g. after a restart). */
+	start() {
+		if (this.sweepTimer) return;
+		this.sweepTimer = setInterval(() => void this.sweep().catch(() => {}), SWEEP_INTERVAL_MS);
+		this.sweepTimer.unref?.();
+		this.sweep().catch(() => {});
+	}
+	async sweep() {
+		const rows = await this.hs.db.findMany("federation_outbox", {
+			sortBy: {
+				field: "id",
+				direction: "asc"
+			},
+			limit: 1e3
+		});
+		for (const dest of new Set(rows.map((r) => r.destination))) this.schedule(dest, 0);
+	}
+	async sendPdu(destinations, pdu) {
+		await this.enqueue(destinations, "pdu", pdu);
+	}
+	async sendEdu(destinations, eduType, content, durable = true) {
+		await this.enqueue(destinations, durable ? "edu" : "edu-ephemeral", {
+			edu_type: eduType,
+			content
+		});
+	}
+	async enqueue(destinations, kind, payload) {
+		for (const destination of new Set(destinations)) {
+			if (destination === this.hs.serverName) continue;
+			const id = await this.hs.cluster.nextId("federation_outbox");
+			await this.hs.db.create("federation_outbox", {
+				id,
+				destination,
+				kind,
+				payload,
+				created_ts: Date.now()
+			});
+			this.schedule(destination, 0);
+		}
+	}
+	schedule(destination, delayMs) {
+		if (this.hs.isClosed) return;
+		const existing = this.timers.get(destination);
+		if (existing && delayMs > 0) return;
+		if (existing) clearTimeout(existing);
+		const timer = setTimeout(() => {
+			this.timers.delete(destination);
+			this.flush(destination).catch((err) => this.hs.logger.debug("Federation flush failed", err));
+		}, delayMs);
+		timer.unref?.();
+		this.timers.set(destination, timer);
+	}
+	async flush(destination) {
+		await this.hs.cluster.lock(`fedsend:${destination}`, async () => {
+			const status = await this.hs.db.findOne("destination_status", [{
+				field: "destination",
+				value: destination
+			}]);
+			if (status && status.retry_after_ts > Date.now()) {
+				this.schedule(destination, status.retry_after_ts - Date.now());
+				return;
+			}
+			try {
+				for (;;) {
+					const rows = await this.hs.db.findMany("federation_outbox", {
+						where: [{
+							field: "destination",
+							value: destination
+						}],
+						sortBy: {
+							field: "id",
+							direction: "asc"
+						},
+						limit: 150
+					});
+					if (!rows.length) break;
+					const pdus = rows.filter((r) => r.kind === "pdu").slice(0, MAX_PDUS);
+					const edus = rows.filter((r) => r.kind !== "pdu").slice(0, MAX_EDUS);
+					const txnId = `${Date.now()}${randomString(6)}`;
+					await this.hs.federation.client.request(destination, "PUT", `/_matrix/federation/v1/send/${txnId}`, {
+						body: {
+							origin: this.hs.serverName,
+							origin_server_ts: Date.now(),
+							pdus: pdus.map((p) => p.payload),
+							edus: edus.map((e) => e.payload)
+						},
+						timeoutMs: 2e4
+					});
+					const sent = [...pdus, ...edus].map((r) => r.id);
+					await this.hs.db.delete("federation_outbox", [{
+						field: "id",
+						operator: "in",
+						value: sent
+					}]);
+				}
+				if (status) await this.hs.db.delete("destination_status", [{
+					field: "destination",
+					value: destination
+				}]);
+			} catch (err) {
+				const failures = (status?.failures ?? 0) + 1;
+				const cap = failures <= FAST_RETRY_ATTEMPTS ? FAST_RETRY_CAP_MS : MAX_RETRY_MS;
+				const delay = Math.min(Math.round(MIN_RETRY_MS * 1.5 ** (failures - 1)), cap);
+				await this.hs.db.upsert("destination_status", {
+					destination,
+					failures,
+					retry_after_ts: Date.now() + delay
+				});
+				await this.hs.db.delete("federation_outbox", [{
+					field: "destination",
+					value: destination
+				}, {
+					field: "kind",
+					value: "edu-ephemeral"
+				}]);
+				this.hs.logger.debug("Federation send to", destination, "failed; retrying in", delay, "ms", err);
+				this.schedule(destination, delay);
+			}
+		});
+	}
+	/** Retry a destination immediately (e.g. after it contacted us). */
+	async wake(destination) {
+		if (!await this.hs.db.findOne("destination_status", [{
+			field: "destination",
+			value: destination
+		}])) return;
+		await this.hs.db.delete("destination_status", [{
+			field: "destination",
+			value: destination
+		}]);
+		this.schedule(destination, 0);
+	}
+	stop() {
+		for (const t of this.timers.values()) clearTimeout(t);
+		this.timers.clear();
+		if (this.sweepTimer) clearInterval(this.sweepTimer);
+		this.sweepTimer = null;
+	}
+};
+//#endregion
+export { TransactionSender };

package/dist/homeserver.d.ts

@@ -0,0 +1,224 @@
+import { PartialStateService } from "./core/partialstate.js";
+import { SigningKey } from "./core/crypto.js";
+import { PolicyServers } from "./core/policy.js";
+import { ThreepidOptions, ThreepidService } from "./core/threepid.js";
+import { IdentityServers } from "./core/identity.js";
+import { M } from "./core/m.js";
+import { AppServiceRegistration, AppServiceService } from "./core/appservices.js";
+import { AuthService } from "./core/auth.js";
+import { KeyService } from "./core/keys.js";
+import { ClusterAdapter, StreamManager } from "./core/cluster.js";
+import { Notifier } from "./core/notifier.js";
+import { DatabaseAdapter } from "./storage/types.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 { SsoOptions, SsoService } from "./core/sso.js";
+import { FederationOptions, FederationService } from "./federation/index.js";
+import { DelayedEventService, DelayedEventsOptions } from "./core/delayed.js";
+import { RateLimitAction, RateLimitRule, RateLimiter, RateLimits } from "./core/ratelimit.js";
+import { Router } from "./http/router.js";
+import { RtcOptions } from "./api/rtc.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 { EventEmitter } from "node:events";
+//#region src/homeserver.d.ts
+export interface Logger {
+  debug(...args: unknown[]): void;
+  info(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+  error(...args: unknown[]): void;
+}
+export interface HomeserverOptions {
+  /** The server name, i.e. the part after the colon in `@user:server`. */
+  homeserver: string;
+  /** Storage backend. Defaults to an in-memory database. */
+  databaseAdapter?: DatabaseAdapter | Record<string, never>;
+  /** Authentication customisation. Defaults to built-in password auth. */
+  userAuthAdapter?: UserAuthAdapter;
+  /** Media byte storage. Defaults to in-memory storage. */
+  mediaAdapter?: MediaAdapter | Record<string, never>;
+  /** Public URL of the client API, advertised via `/.well-known/matrix/client`. */
+  publicBaseUrl?: string;
+  /**
+   * Federation address ("host" or "host:port") advertised at `/.well-known/matrix/server`, when
+   * other servers should reach this server somewhere else than `<server name>:8448`.
+   */
+  federationAddress?: string;
+  /** Contacts and page served at `/.well-known/matrix/support` (e.g. to appeal a locked account). */
+  support?: {
+    contacts?: {
+      role: typeof M.ROLE.ADMIN | typeof M.ROLE.SECURITY | (string & {});
+      matrix_id?: string;
+      email_address?: string;
+    }[];
+    supportPage?: string;
+  };
+  /**
+   * Email addresses and phone numbers (3PIDs): how validation messages are sent, and whether
+   * registration needs an email address. 3PID invites through identity servers work without it.
+   */
+  threepid?: ThreepidOptions;
+  /**
+   * Lets a logged-in client generate a one-time login token for a new device
+   * (`POST /login/get_token`, after re-authentication). Default: true.
+   */
+  loginViaExistingSession?: boolean;
+  /** Enables Synapse-compatible shared-secret registration at `/_synapse/admin/v1/register`. */
+  registrationSharedSecret?: string;
+  /** Persisted ed25519 signing key. Generated and stored in the database when omitted. */
+  signingKey?: {
+    keyId: string;
+    seed: string;
+  };
+  /** Room version used when clients do not ask for one. Default: "10". */
+  defaultRoomVersion?: string;
+  /** When set, clients requesting refresh tokens get access tokens that expire after this many ms. */
+  accessTokenLifetimeMs?: number;
+  /** Maximum `/sync` long-poll duration in ms. Default: 30000. */
+  maxSyncTimeoutMs?: number;
+  /**
+   * Enables `/preview_url`. Off by default because it makes the server fetch arbitrary URLs.
+   * Private/internal addresses stay blocked unless `allowPrivateAddresses` is set.
+   */
+  urlPreviews?: boolean | {
+    allowPrivateAddresses?: boolean;
+  };
+  logger?: Logger;
+  /** Custom `fetch` for outgoing HTTP requests. */
+  fetch?: typeof globalThis.fetch;
+  /**
+   * Rate limiting. `false` disables it; otherwise per-action overrides and an optional
+   * shared limiter (defaults to an in-memory token bucket). Admins are never limited.
+   */
+  /** Delegate authentication to an external OAuth 2.0 / OIDC provider (disables password login and registration). */
+  oauth?: OAuthDelegationOptions;
+  /** Upstream OpenID Connect providers for `m.login.sso`. Requires `publicBaseUrl`. */
+  sso?: SsoOptions;
+  /**
+   * Coordination between instances. The default (`localCluster()`) supports one process;
+   * use `postgresCluster()` / `redisCluster()` to scale horizontally.
+   */
+  cluster?: ClusterAdapter;
+  /**
+   * Admin room with an admin bot (tuwunel-style); the first registered account becomes
+   * a server admin. Pass `true` or options to enable. Default: disabled.
+   */
+  adminRoom?: boolean | AdminRoomOptions;
+  /** Audit log of security-relevant actions. Default: disabled. */
+  audit?: AuditOptions;
+  /** Application service registrations (bridges, bots). */
+  appservices?: AppServiceRegistration[];
+  /** VoIP (TURN) and MatrixRTC configuration. */
+  rtc?: RtcOptions;
+  /** Delayed events (MSC4140) limits. */
+  delayedEvents?: DelayedEventsOptions;
+  /** Federation (server-server API). Enabled by default. */
+  federation?: FederationOptions;
+  /** Generates image thumbnails, e.g. `sharpThumbnailer(sharp)`. Without one, originals are served. */
+  thumbnailer?: Thumbnailer;
+  /** Server notices (system messages to users). */
+  serverNotices?: ServerNoticesOptions;
+  rateLimits?: false | {
+    limiter?: RateLimiter;
+    rules?: Partial<Record<RateLimitAction, RateLimitRule>>;
+  };
+  /** Interval for background cleanup of expired data, in ms. Default: 10 minutes. `0` disables it. */
+  cleanupIntervalMs?: number;
+}
+export interface ResolvedConfig {
+  serverName: string;
+  publicBaseUrl: string | null;
+  federationAddress: string | null;
+  support: {
+    contacts: {
+      role: string;
+      matrix_id?: string;
+      email_address?: string;
+    }[];
+    support_page?: string;
+  } | null;
+  loginViaExistingSession: boolean;
+  threepid: ThreepidOptions & {
+    identityServerProtocol: "https" | "http";
+  };
+  registrationSharedSecret: string | null;
+  defaultRoomVersion: string;
+  accessTokenLifetimeMs: number | null;
+  maxSyncTimeoutMs: number;
+  urlPreviews: {
+    allowPrivateAddresses: boolean;
+  } | null;
+  serverNotices: Required<ServerNoticesOptions>;
+  thumbnailer: Thumbnailer | null;
+  rtc: RtcOptions;
+}
+export declare class Homeserver extends EventEmitter {
+  readonly serverName: string;
+  readonly config: ResolvedConfig;
+  readonly db: DatabaseAdapter;
+  readonly media: MediaAdapter;
+  readonly userAuth: ResolvedUserAuth;
+  readonly logger: Logger;
+  readonly router: Router;
+  readonly cluster: ClusterAdapter;
+  readonly instanceId: string;
+  readonly streams: StreamManager;
+  readonly notifier: Notifier;
+  readonly auth: AuthService;
+  readonly rooms: RoomService;
+  readonly keys: KeyService;
+  readonly typing: TypingService;
+  readonly push: PushService;
+  readonly rateLimits: RateLimits;
+  readonly admin: AdminService;
+  readonly oauth: OAuthDelegation | null;
+  readonly sso: SsoService | null;
+  readonly federation: FederationService;
+  readonly delayedEvents: DelayedEventService;
+  readonly audit: AuditService;
+  readonly settings: SettingsService;
+  readonly adminRoom: AdminRoomService | null;
+  readonly appservices: AppServiceService;
+  readonly partialState: PartialStateService;
+  readonly policyServers: PolicyServers;
+  readonly threepids: ThreepidService;
+  readonly identityServers: IdentityServers;
+  /** `fetch` used for outgoing requests (push gateways, URL previews, OAuth). Overridable for testing. */
+  readonly fetch: typeof globalThis.fetch;
+  /** Resolves once storage is migrated and the server is ready to serve requests. */
+  readonly ready: Promise<void>;
+  private _signingKey;
+  private cleanupTimer;
+  private closed;
+  constructor(options: HomeserverOptions);
+  get signingKey(): SigningKey;
+  private init;
+  /** Remove expired tokens, abandoned uploads and old notifications. */
+  cleanup(): Promise<void>;
+  /** Stop background work and release long-polling requests. Call before shutting down your HTTP server. */
+  close(): Promise<void>;
+  get isClosed(): boolean;
+  /**
+   * Effective registration mode: an admin's runtime setting overrides the configuration.
+   * "open" | "token" | "closed".
+   */
+  registrationMode(): Promise<"open" | "token" | "closed">;
+  /** Whether `/register` is allowed right now, including the first-user exception. */
+  registrationAllowed(): Promise<boolean>;
+  /** Run `fn` atomically when the database adapter supports transactions. */
+  transaction<T>(fn: (db: DatabaseAdapter) => Promise<T>): Promise<T>;
+  /** The user's current profile, as included in member events. */
+  profile(userId: string): Promise<{
+    displayname?: string;
+    avatar_url?: string;
+  }>;
+  isLocalUser(userId: string): boolean;
+}
+export declare function createHomeserver(options: HomeserverOptions): Homeserver;
+//#endregion