Skip to content

A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.

TypeScript fluxerfluxerapp
19.9 KB
Raw Blame
// SPDX-License-Identifier: AGPL-3.0-or-later

import {createHash, createHmac, randomUUID, timingSafeEqual} from 'node:crypto';
import type {AdminAuditService} from '@app/api/admin/services/AdminAuditService';
import {createGuildIDSet, createUserIDSet, type UserID} from '@app/api/BrandedTypes';
import {Config} from '@app/api/Config';
import type {VoiceJoinTokenRow} from '@app/api/database/types/VoiceTypes';
import {Logger} from '@app/api/Logger';
import {calculateDistance} from '@app/api/utils/GeoUtils';
import type {VoiceJoinTokenRepository} from '@app/api/voice/VoiceJoinTokenRepository';
import type {VoiceRegionRecord, VoiceServerRecord} from '@app/api/voice/VoiceModel';
import type {VoiceRepository, VoiceServerNodeFields} from '@app/api/voice/VoiceRepository';
import {
	bundledVoiceServerId,
	checkLiveKitKeys,
	parseNodeEndpoint,
	probeLiveKit,
	VoiceEndpointError,
} from '@app/api/voice/VoiceServerEndpoints';
import {healthOf, toHealthResponse, type VoiceServerHealthSource} from '@app/api/voice/VoiceServerHealth';
import {API_CODE_VERSION} from '@fluxer/constants/src/AppConstants';
import {InputValidationError} from '@fluxer/errors/src/domains/core/InputValidationError';
import {UnknownVoiceRegionError} from '@fluxer/errors/src/domains/voice/UnknownVoiceRegionError';
import {VoiceJoinEndpointInvalidError} from '@fluxer/errors/src/domains/voice/VoiceJoinEndpointInvalidError';
import {VoiceJoinEndpointUnreachableError} from '@fluxer/errors/src/domains/voice/VoiceJoinEndpointUnreachableError';
import {VoiceJoinKeyMismatchError} from '@fluxer/errors/src/domains/voice/VoiceJoinKeyMismatchError';
import {VoiceJoinTokenBusyError} from '@fluxer/errors/src/domains/voice/VoiceJoinTokenBusyError';
import {VoiceJoinTokenInvalidError} from '@fluxer/errors/src/domains/voice/VoiceJoinTokenInvalidError';
import {VoiceNodeSignatureInvalidError} from '@fluxer/errors/src/domains/voice/VoiceNodeSignatureInvalidError';
import {VoiceNodeTokenExpiredError} from '@fluxer/errors/src/domains/voice/VoiceNodeTokenExpiredError';
import {VoiceNodeUnknownError} from '@fluxer/errors/src/domains/voice/VoiceNodeUnknownError';
import {VoiceServerApiKeyInUseError} from '@fluxer/errors/src/domains/voice/VoiceServerApiKeyInUseError';
import {VoiceServerIdInUseError} from '@fluxer/errors/src/domains/voice/VoiceServerIdInUseError';
import type {
	UpdateVoiceNodeRequest,
	VoiceJoinPreviewRequest,
	VoiceJoinPreviewResponse,
	VoiceJoinRequest,
	VoiceJoinResponse,
	VoiceNodeResponse,
	VoiceTurnServer,
} from '@fluxer/schema/src/domains/voice/VoiceNodeSchemas';
import {lookupGeoipByIp} from '@pkgs/geoip/src/GeoipLookup';

export const VOICE_JOIN_TOKEN_PREFIX = 'fvj_';

export function voiceJoinCommand(webApp: string, baseDomain: string, token: string): string {
	const instance = URL.parse(webApp)?.host || baseDomain;
	return `curl -fsSL https://fluxer.dev/install.sh | sh -s -- voice ${instance} ${token}`;
}

const VOICE_NODE_AUDIENCE = 'fluxer-voice-node';
export const VOICE_NODE_PATH = '/voice/node';

const CLAIM_STALE_MS = 2 * 60 * 1000;
const NODE_TOKEN_MAX_AHEAD_SECONDS = 5 * 60;
const NODE_TOKEN_LEEWAY_SECONDS = 60;
const PROBE_TIMEOUT_MS = 10_000;

export function hashJoinSecret(secret: string): string {
	return createHash('sha256').update(secret).digest('hex');
}

function parseJoinToken(header: string | undefined): {tokenId: bigint; secret: string} | null {
	const value = header?.startsWith('VoiceJoin ') ? header.slice('VoiceJoin '.length) : null;
	const match = value ? /^fvj_(\d{1,20})_([A-Za-z0-9_-]{43})$/.exec(value) : null;
	if (!match) return null;
	return {tokenId: BigInt(match[1]!), secret: match[2]!};
}

function sameHash(a: string, b: string): boolean {
	const left = Buffer.from(a, 'hex');
	const right = Buffer.from(b, 'hex');
	return left.length === right.length && timingSafeEqual(left, right);
}

export type JoinTokenStatus = 'pending' | 'used' | 'expired' | 'revoked';

export function joinTokenStatus(row: VoiceJoinTokenRow, now = new Date()): JoinTokenStatus {
	if (row.used_at) return 'used';
	if (row.revoked_at) return 'revoked';
	if (row.expires_at.getTime() <= now.getTime()) return 'expired';
	return 'pending';
}

function round(value: number): number {
	return Math.round(value * 10) / 10;
}

function bodyHash(body: string): string {
	return body === '' ? '' : createHash('sha256').update(body).digest('base64');
}

function decodeSegment(segment: string): Record<string, unknown> | null {
	try {
		const value: unknown = JSON.parse(Buffer.from(segment, 'base64url').toString('utf8'));
		return value && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : null;
	} catch {
		return null;
	}
}

interface NodeTokenParts {
	issuer: string;
	signingInput: string;
	signature: Buffer;
	claims: Record<string, unknown>;
}

function splitNodeToken(header: string | undefined): NodeTokenParts | null {
	const token = header?.startsWith('Bearer ') ? header.slice('Bearer '.length) : null;
	const parts = token?.split('.');
	if (parts?.length !== 3) return null;
	const [head, payload, signature] = parts as [string, string, string];
	const headerJson = decodeSegment(head);
	const claims = decodeSegment(payload);
	if (headerJson?.['alg'] !== 'HS256' || !claims || typeof claims['iss'] !== 'string') return null;
	return {
		issuer: claims['iss'],
		signingInput: `${head}.${payload}`,
		signature: Buffer.from(signature, 'base64url'),
		claims,
	};
}

function signatureMatches(parts: NodeTokenParts, secret: string): boolean {
	const expected = createHmac('sha256', secret).update(parts.signingInput).digest();
	return expected.length === parts.signature.length && timingSafeEqual(expected, parts.signature);
}

type EndpointVerifier = (
	endpoint: string,
	keys: {apiKey: string; apiSecret: string},
	internalEndpoint: string | null,
	probePublic: boolean,
) => Promise<void>;

const verifyNodeEndpoint: EndpointVerifier = async (endpoint, keys, internalEndpoint, probePublic) => {
	const base = internalEndpoint ?? endpoint;
	const options = {
		checkAddress: internalEndpoint === null,
		allowPrivate: Config.voice.joinAllowPrivateEndpoints,
		timeoutMs: PROBE_TIMEOUT_MS,
	};
	if (probePublic && internalEndpoint !== null) {
		await probeLiveKit(endpoint, {...options, checkAddress: true}).catch((error: unknown) => {
			Logger.warn(
				{endpoint, error: error instanceof Error ? error.message : String(error)},
				"The API can't connect to the new public endpoint of a voice server with an internal endpoint",
			);
		});
	}
	await probeLiveKit(base, options);
	await checkLiveKitKeys(base, keys, options);
};

function asApiError(error: unknown): Error {
	if (!(error instanceof VoiceEndpointError)) return error as Error;
	switch (error.reason) {
		case 'invalid':
		case 'private':
			return new VoiceJoinEndpointInvalidError(error.message);
		case 'key_mismatch':
			return new VoiceJoinKeyMismatchError();
		default:
			return new VoiceJoinEndpointUnreachableError(error.message);
	}
}

interface VoiceNodeServiceDeps {
	voiceRepository: VoiceRepository;
	joinTokenRepository: VoiceJoinTokenRepository;
	auditService: AdminAuditService;
	health: VoiceServerHealthSource | null;
	publish: (message: string) => Promise<void>;
}

type RegionSource = 'token' | 'requested' | 'nearest' | 'default';

interface ChosenRegion {
	id: string;
	name: string;
	isNew: boolean;
	distanceKm: number | null;
	emoji: string;
	source: RegionSource;
}

export class VoiceNodeService {
	constructor(private readonly deps: VoiceNodeServiceDeps) {}

	async authenticateJoin(header: string | undefined): Promise<VoiceJoinTokenRow> {
		const parsed = parseJoinToken(header);
		if (!parsed) throw new VoiceJoinTokenInvalidError();
		const row = await this.deps.joinTokenRepository.get(parsed.tokenId);
		if (!row || !sameHash(row.secret_hash, hashJoinSecret(parsed.secret)) || joinTokenStatus(row) !== 'pending') {
			throw new VoiceJoinTokenInvalidError();
		}
		return row;
	}

	async preview(row: VoiceJoinTokenRow, body: VoiceJoinPreviewRequest, clientIp: string | null) {
		const point = await this.locate(body.public_ipv4 ?? body.public_ipv6 ?? clientIp);
		const region = await this.chooseRegion(row, body.region_id, point);
		const servers = await this.deps.voiceRepository.listAllServers();
		const response: VoiceJoinPreviewResponse = {
			server_id: row.server_id ?? this.suggestServerId(region.id, servers),
			server_id_pinned: row.server_id !== null,
			region: {
				id: region.id,
				name: region.name,
				distance_km: region.distanceKm,
				new: region.isNew,
				source: region.source,
			},
			latitude: point ? round(point.latitude) : null,
			longitude: point ? round(point.longitude) : null,
			hostname: row.hostname,
			suggested_hostname: `voice-${region.id}.${Config.instance.baseDomain}`,
			soft_connection_limit: row.soft_connection_limit,
			webhook_url: `${Config.endpoints.apiPublic}/webhooks/livekit`,
			api_code_version: API_CODE_VERSION,
			release: process.env.BUILD_VERSION?.trim() ?? '',
			expires_at: row.expires_at.toISOString(),
			turn_servers: turnServers(),
		};
		return response;
	}

	async join(row: VoiceJoinTokenRow, body: VoiceJoinRequest, clientIp: string | null): Promise<VoiceJoinResponse> {
		const {joinTokenRepository, voiceRepository} = this.deps;
		const now = new Date();
		if (row.claim_id && row.claimed_at && now.getTime() - row.claimed_at.getTime() < CLAIM_STALE_MS) {
			throw new VoiceJoinTokenBusyError();
		}
		const claimId = randomUUID();
		if (!(await joinTokenRepository.claim(row, claimId, now))) {
			throw new VoiceJoinTokenBusyError();
		}
		try {
			const point =
				body.latitude !== undefined && body.longitude !== undefined
					? {latitude: body.latitude, longitude: body.longitude}
					: await this.locate(body.public_ipv4 ?? body.public_ipv6 ?? clientIp);
			const region = await this.chooseRegion(row, body.region_id, point);
			const servers = await voiceRepository.listAllServers();
			const serverId = row.server_id ?? body.server_id ?? this.suggestServerId(region.id, servers);
			if (serverId === bundledVoiceServerId() || servers.some((server) => server.serverId === serverId)) {
				throw new VoiceServerIdInUseError();
			}
			if (servers.some((server) => server.apiKey === body.api_key)) throw new VoiceServerApiKeyInUseError();
			const endpoint = this.checkEndpoint(body.endpoint, row.hostname);
			await verifyNodeEndpoint(
				endpoint,
				{apiKey: body.api_key, apiSecret: body.api_secret},
				row.internal_endpoint,
				false,
			).catch((error: unknown) => {
				throw asApiError(error);
			});
			if (region.isNew) {
				await voiceRepository.createRegion({
					id: region.id,
					name: region.name,
					emoji: region.emoji,
					latitude: row.region_latitude ?? point?.latitude ?? 0,
					longitude: row.region_longitude ?? point?.longitude ?? 0,
					isDefault: false,
					restrictions: emptyRestrictions(),
				});
			}
			const created = await voiceRepository.createServerIfAbsent({
				regionId: region.id,
				serverId,
				endpoint,
				apiKey: body.api_key,
				apiSecret: body.api_secret,
				latitude: point ? round(point.latitude) : null,
				longitude: point ? round(point.longitude) : null,
				isActive: true,
				draining: false,
				internalEndpoint: row.internal_endpoint,
				pinnedHostname: row.hostname ?? null,
				pinnedSoftLimit: row.soft_connection_limit != null,
				publicIpv4: body.public_ipv4 ?? null,
				publicIpv6: body.public_ipv6 ?? null,
				softConnectionLimit: row.soft_connection_limit ?? body.soft_connection_limit ?? null,
				notes: row.notes ?? `Joined with a join token on ${now.toISOString().slice(0, 10)}`,
				restrictions: {
					vipOnly: row.vip_only ?? false,
					requiredGuildFeatures: new Set(row.required_guild_features ?? []),
					allowedGuildIds: createGuildIDSet(new Set(row.allowed_guild_ids ?? [])),
					allowedUserIds: createUserIDSet(new Set(row.allowed_user_ids ?? [])),
				},
			});
			if (!created) throw new VoiceServerIdInUseError();
			await joinTokenRepository.markUsed(row, claimId, {at: new Date(), ip: clientIp, serverId});
			await this.deps.publish(JSON.stringify({type: 'server_created', regionId: region.id, serverId}));
			await this.deps.auditService.createAuditLog({
				targetId: 0n,
				adminUserId: row.created_by as UserID,
				targetType: 'voice_server',
				action: 'create_voice_server',
				auditLogReason: null,
				metadata: new Map([
					['region_id', region.id],
					['server_id', serverId],
					['endpoint', endpoint],
					['via', `voice_join:${row.token_id}`],
					['node_ip', clientIp ?? ''],
				]),
			});
			return {
				server_id: serverId,
				region_id: region.id,
				endpoint,
				webhook_url: `${Config.endpoints.apiPublic}/webhooks/livekit`,
				node_url: `${Config.endpoints.apiPublic}${VOICE_NODE_PATH}`,
				turn_servers: turnServers(),
			};
		} catch (error) {
			await joinTokenRepository.release(row, claimId).catch(() => false);
			throw error;
		}
	}

	async authenticateNode(header: string | undefined, method: string, body: string): Promise<VoiceServerRecord> {
		const parts = splitNodeToken(header);
		if (!parts) throw new VoiceNodeSignatureInvalidError();
		const candidates = (await this.deps.voiceRepository.listAllServers()).filter(
			(server) => server.apiKey === parts.issuer,
		);
		if (candidates.length === 0) throw new VoiceNodeUnknownError();
		const server = candidates.find((candidate) => signatureMatches(parts, candidate.apiSecret));
		const {claims} = parts;
		const valid =
			claims['aud'] === VOICE_NODE_AUDIENCE &&
			claims['method'] === method &&
			claims['path'] === VOICE_NODE_PATH &&
			claims['sha256'] === bodyHash(body) &&
			claims['video'] === undefined &&
			typeof claims['exp'] === 'number';
		if (!valid || !server) throw new VoiceNodeSignatureInvalidError();
		const now = Math.floor(Date.now() / 1000);
		const exp = claims['exp'] as number;
		const iat = typeof claims['iat'] === 'number' ? claims['iat'] : null;
		const current =
			exp > now - NODE_TOKEN_LEEWAY_SECONDS &&
			exp <= now + NODE_TOKEN_MAX_AHEAD_SECONDS + NODE_TOKEN_LEEWAY_SECONDS &&
			(iat === null || iat <= now + NODE_TOKEN_LEEWAY_SECONDS);
		if (!current) throw new VoiceNodeTokenExpiredError();
		return server;
	}

	describe(server: VoiceServerRecord): VoiceNodeResponse {
		return {
			region_id: server.regionId,
			server_id: server.serverId,
			endpoint: server.endpoint,
			latitude: server.latitude,
			longitude: server.longitude,
			is_active: server.isActive,
			draining: server.draining,
			soft_connection_limit: server.softConnectionLimit,
			public_ipv4: server.publicIpv4,
			public_ipv6: server.publicIpv6,
			turn_servers: turnServers(),
			features: ['server_addresses'],
			health: toHealthResponse(healthOf(this.deps.health, server)),
		};
	}

	async update(server: VoiceServerRecord, body: UpdateVoiceNodeRequest): Promise<VoiceNodeResponse> {
		const fields: VoiceServerNodeFields = {};
		if (body.endpoint !== undefined && body.endpoint !== server.endpoint) {
			fields.endpoint = this.checkEndpoint(body.endpoint, server.pinnedHostname);
			await verifyNodeEndpoint(fields.endpoint, server, server.internalEndpoint, true).catch((error: unknown) => {
				throw asApiError(error);
			});
		}
		const current = await this.deps.voiceRepository.getServer(server.regionId, server.serverId);
		if (!current) throw new VoiceNodeUnknownError();
		if (
			current.pinnedSoftLimit &&
			body.soft_connection_limit !== undefined &&
			body.soft_connection_limit !== current.softConnectionLimit
		) {
			throw InputValidationError.create(
				'soft_connection_limit',
				'The join token set the soft limit of this server. Change it in the admin panel.',
			);
		}
		if (body.draining !== undefined) fields.draining = body.draining;
		if (body.latitude !== undefined) fields.latitude = body.latitude;
		if (body.longitude !== undefined) fields.longitude = body.longitude;
		if (body.soft_connection_limit !== undefined) fields.softConnectionLimit = body.soft_connection_limit;
		if (body.public_ipv4 !== undefined) fields.publicIpv4 = body.public_ipv4 || null;
		if (body.public_ipv6 !== undefined) fields.publicIpv6 = body.public_ipv6 || null;
		const updatedAt = new Date();
		await this.deps.voiceRepository.patchServerNodeFields(server.regionId, server.serverId, fields, updatedAt);
		const updated: VoiceServerRecord = {...current, ...fields, updatedAt};
		await this.deps.publish(
			JSON.stringify({type: 'server_updated', regionId: server.regionId, serverId: server.serverId}),
		);
		await this.audit(server, 'update_voice_server', Object.keys(body).sort().join(','));
		return this.describe(updated);
	}

	async remove(server: VoiceServerRecord): Promise<void> {
		await this.deps.voiceRepository.deleteServer(server.regionId, server.serverId);
		await this.deps.publish(
			JSON.stringify({type: 'server_deleted', regionId: server.regionId, serverId: server.serverId}),
		);
		await this.audit(server, 'delete_voice_server', '');
	}

	private async audit(server: VoiceServerRecord, action: string, fields: string): Promise<void> {
		const metadata = new Map([
			['region_id', server.regionId],
			['server_id', server.serverId],
			['via', `voice_node:${server.serverId}`],
		]);
		if (fields) metadata.set('fields', fields);
		await this.deps.auditService.createAuditLog({
			targetId: 0n,
			adminUserId: 0n as UserID,
			targetType: 'voice_server',
			action,
			auditLogReason: null,
			metadata,
		});
	}

	private checkEndpoint(endpoint: string, hostname: string | null): string {
		try {
			const url = parseNodeEndpoint(endpoint);
			if (hostname && url.hostname.toLowerCase() !== hostname.toLowerCase()) {
				throw new VoiceEndpointError('invalid', `The endpoint must use the hostname ${hostname}`);
			}
			return url.toString().replace(/\/$/, '');
		} catch (error) {
			throw asApiError(error);
		}
	}

	private async locate(ip: string | null): Promise<{latitude: number; longitude: number} | null> {
		if (!ip || !Config.geoip.maxmindDbPath) return null;
		const result = await lookupGeoipByIp(ip, Config.geoip.maxmindDbPath).catch(() => null);
		if (result?.latitude == null || result.longitude == null) return null;
		return {latitude: result.latitude, longitude: result.longitude};
	}

	private async chooseRegion(
		row: VoiceJoinTokenRow,
		requested: string | undefined,
		point: {latitude: number; longitude: number} | null,
	): Promise<ChosenRegion> {
		const regions = await this.deps.voiceRepository.listRegions();
		const distance = (region: VoiceRegionRecord) =>
			point ? Math.round(calculateDistance(point.latitude, point.longitude, region.latitude, region.longitude)) : null;
		const pick = (region: VoiceRegionRecord, source: RegionSource): ChosenRegion => ({
			id: region.id,
			name: region.name,
			emoji: region.emoji,
			isNew: false,
			distanceKm: distance(region),
			source,
		});
		const wanted = row.region_id ?? requested ?? null;
		if (wanted) {
			const source = row.region_id ? 'token' : 'requested';
			const existing = regions.find((region) => region.id === wanted);
			if (existing) return pick(existing, source);
			if (row.region_id && row.region_name) {
				return {
					id: row.region_id,
					name: row.region_name,
					emoji: row.region_emoji ?? '🌍',
					isNew: true,
					distanceKm: 0,
					source,
				};
			}
			throw new UnknownVoiceRegionError();
		}
		if (regions.length === 0) throw new UnknownVoiceRegionError();
		if (point) {
			const nearest = regions.reduce((best, region) =>
				(distance(region) ?? 0) < (distance(best) ?? 0) ? region : best,
			);
			return pick(nearest, 'nearest');
		}
		return pick(regions.find((region) => region.isDefault) ?? regions[0]!, 'default');
	}

	private suggestServerId(regionId: string, servers: Array<VoiceServerRecord>): string {
		const used = new Set(servers.map((server) => server.serverId));
		const bundled = bundledVoiceServerId();
		if (bundled) used.add(bundled);
		for (let n = 1; ; n++) {
			const id = `${regionId}-server-${n}`;
			if (!used.has(id)) return id;
		}
	}
}

function turnServers(): Array<VoiceTurnServer> {
	return Config.voice.turnServers.map((server) => ({...server}));
}

function emptyRestrictions(): VoiceRegionRecord['restrictions'] {
	return {
		vipOnly: false,
		requiredGuildFeatures: new Set(),
		allowedGuildIds: createGuildIDSet(new Set()),
		allowedUserIds: createUserIDSet(new Set()),
	};
}