@serverkgg/bridge 0.0.13 → 0.0.15

package/src/rcon/rconAccess.test.ts

@@ -0,0 +1,304 @@
+import { describe, expect, test } from "bun:test";
+import type { BridgeContext } from "../context";
+import { BridgeDetailFormat, BridgeDetailTone, BridgeFormTarget, BridgeLayout } from "../panel";
+import {
+	createRconAccess,
+	RCON_ACCESS_MODULE,
+	RCON_ACCESS_PORT,
+	RCON_ACCESS_ROTATE,
+	RCON_ACCESS_VARIABLE,
+	type RconAccessPassword,
+	rconAccessSections,
+	rconBindHost,
+	rconExposed,
+} from "./rconAccess";
+
+interface StubOptions {
+	exposed?: boolean;
+	port?: number | null;
+}
+
+const stubContext = (options: StubOptions = {}) => {
+	const logged: string[] = [];
+
+	const context = {
+		variable: (key: string) => {
+			return key === RCON_ACCESS_VARIABLE && options.exposed === true ? "true" : null;
+		},
+		port: (key: string) => {
+			if (options.port === null) {
+				throw new Error(`this game declares no port named "${key}"`);
+			}
+
+			return options.port ?? 12_500;
+		},
+		log: (message: string) => {
+			logged.push(message);
+		},
+	} as unknown as BridgeContext;
+
+	return {
+		context,
+		logged,
+	};
+};
+
+const accessWith = (password: RconAccessPassword | null, rotate?: () => Promise<void>) => {
+	return createRconAccess({
+		async password() {
+			return password;
+		},
+		async rotate() {
+			await rotate?.();
+		},
+	});
+};
+
+describe("rconExposed", () => {
+	test("only the string true opens remote access", () => {
+		expect(
+			rconExposed(
+				stubContext({
+					exposed: true,
+				}).context,
+			),
+		).toBe(true);
+		expect(rconExposed(stubContext().context)).toBe(false);
+	});
+});
+
+describe("rconBindHost", () => {
+	test("an exposed server binds every interface and a closed one stays on loopback", () => {
+		expect(
+			rconBindHost(
+				stubContext({
+					exposed: true,
+				}).context,
+			),
+		).toBe("0.0.0.0");
+		expect(rconBindHost(stubContext().context)).toBe("127.0.0.1");
+	});
+});
+
+describe("createRconAccess", () => {
+	test("an exposed server reads as open", async () => {
+		const detail = await accessWith({
+			value: "secret",
+			pending: false,
+		}).read(
+			stubContext({
+				exposed: true,
+				port: 12_501,
+			}).context,
+		);
+
+		expect(detail?.id).toBe(RCON_ACCESS_MODULE);
+		expect(detail?.badges.map((badge) => badge.label.en)).toEqual([
+			"Open",
+		]);
+		expect(detail?.badges[0]?.tone).toBe(BridgeDetailTone.Success);
+		expect(detail?.actions).toEqual([
+			RCON_ACCESS_ROTATE,
+		]);
+	});
+
+	test("a closed server reads as closed", async () => {
+		const detail = await accessWith({
+			value: "secret",
+			pending: false,
+		}).read(stubContext().context);
+
+		expect(detail?.badges.map((badge) => badge.label.en)).toEqual([
+			"Closed",
+		]);
+		expect(detail?.badges[0]?.tone).toBe(BridgeDetailTone.Neutral);
+	});
+
+	test("the port and the password are the two stats", async () => {
+		const detail = await accessWith({
+			value: "secret",
+			pending: false,
+		}).read(
+			stubContext({
+				port: 12_507,
+			}).context,
+		);
+
+		expect(detail?.stats).toEqual([
+			{
+				key: "port",
+				label: {
+					ar: "منفذ RCON",
+					en: "RCON port",
+				},
+				value: 12_507,
+				format: BridgeDetailFormat.Number,
+			},
+			{
+				key: "password",
+				label: {
+					ar: "كلمة مرور RCON",
+					en: "RCON password",
+				},
+				value: "secret",
+				format: BridgeDetailFormat.Secret,
+			},
+		]);
+	});
+
+	test("a password waiting for the next restart carries the pending badge", async () => {
+		const detail = await accessWith({
+			value: "next",
+			pending: true,
+		}).read(stubContext().context);
+
+		expect(detail?.badges.map((badge) => badge.label.en)).toEqual([
+			"Closed",
+			"Applies after restart",
+		]);
+	});
+
+	test("an inactive port leaves the port stat empty instead of failing the read", async () => {
+		const detail = await accessWith({
+			value: "secret",
+			pending: false,
+		}).read(
+			stubContext({
+				port: null,
+			}).context,
+		);
+
+		expect(detail?.stats.find((stat) => stat.key === "port")?.value).toBeNull();
+		expect(detail?.stats.find((stat) => stat.key === "password")?.value).toBe("secret");
+	});
+
+	test("a server with no password yet has no detail", async () => {
+		expect(await accessWith(null).read(stubContext().context)).toBeNull();
+	});
+
+	test("rotating delegates to the driver, logs without the value and answers nothing", async () => {
+		let rotated = 0;
+
+		const access = accessWith(
+			{
+				value: "secret",
+				pending: false,
+			},
+			async () => {
+				rotated += 1;
+			},
+		);
+
+		const { context, logged } = stubContext();
+		const outcome = await access.actions?.[RCON_ACCESS_ROTATE]?.(context, {});
+
+		expect(rotated).toBe(1);
+		expect(outcome).toBeNull();
+		expect(logged).toEqual([
+			"rotated the remote access password",
+		]);
+	});
+
+	test("the protocol name names the detail and both stats", async () => {
+		const detail = await createRconAccess({
+			protocol: {
+				ar: "Telnet",
+				en: "Telnet",
+			},
+			async password() {
+				return {
+					value: "secret",
+					pending: false,
+				};
+			},
+			async rotate() {
+				return;
+			},
+		}).read(stubContext().context);
+
+		expect(detail?.subtitle).toEqual({
+			ar: "Telnet",
+			en: "Telnet",
+		});
+		expect(detail?.stats.map((stat) => stat.label)).toEqual([
+			{
+				ar: "منفذ Telnet",
+				en: "Telnet port",
+			},
+			{
+				ar: "كلمة مرور Telnet",
+				en: "Telnet password",
+			},
+		]);
+	});
+
+	test("a tools line joins the security copy", async () => {
+		const detail = await createRconAccess({
+			tools: {
+				ar: "أدوات مثل RustAdmin.",
+				en: "Tools such as RustAdmin.",
+			},
+			async password() {
+				return {
+					value: "secret",
+					pending: false,
+				};
+			},
+			async rotate() {
+				return;
+			},
+		}).read(stubContext().context);
+
+		expect(detail?.description).toMatchObject({
+			en: expect.stringContaining("Tools such as RustAdmin."),
+		});
+	});
+});
+
+describe("rconAccessSections", () => {
+	test("the form declares the variable the manifest activates the port on", () => {
+		const [form] = rconAccessSections();
+
+		expect(form?.layout).toBe(BridgeLayout.Form);
+
+		if (form?.layout !== BridgeLayout.Form) {
+			throw new Error("the first section is the toggle form");
+		}
+
+		expect(form.target).toBe(BridgeFormTarget.Variables);
+		expect(form.reinstall).toBe(false);
+		expect(form.fields.map((field) => field.key)).toEqual([
+			RCON_ACCESS_VARIABLE,
+		]);
+	});
+
+	test("the detail points at the module and offers the rotate action", () => {
+		const [, detail] = rconAccessSections();
+
+		if (detail?.layout !== BridgeLayout.Detail) {
+			throw new Error("the second section is the detail");
+		}
+
+		expect(detail.module).toBe(RCON_ACCESS_MODULE);
+		expect(detail.actions?.map((action) => action.id)).toEqual([
+			RCON_ACCESS_ROTATE,
+		]);
+		expect(detail.empty).toBeDefined();
+	});
+
+	test("a dedicated port opens a port and a shared one only turns access on", () => {
+		const [dedicated] = rconAccessSections({
+			portKey: RCON_ACCESS_PORT,
+		});
+		const [shared] = rconAccessSections({
+			portKey: "game",
+		});
+
+		if (dedicated?.layout !== BridgeLayout.Form || shared?.layout !== BridgeLayout.Form) {
+			throw new Error("the first section is the toggle form");
+		}
+
+		expect(dedicated.fields[0]?.help?.en).toContain("Opens the RCON port");
+		expect(shared.fields[0]?.help?.en).toContain("Turns remote access on");
+	});
+});

package/src/rcon/rconAccess.ts

@@ -0,0 +1,260 @@
+import type { BridgeContext } from "../context";
+import { BridgeKind, type LocalizedText } from "../core";
+import type { ManifestHostRange } from "../manifest";
+import type { BridgeDetailModule } from "../modules";
+import {
+	BridgeConfirm,
+	BridgeControl,
+	type BridgeDetailBadge,
+	BridgeDetailFormat,
+	BridgeDetailTone,
+	BridgeFormTarget,
+	BridgeLayout,
+	type BridgeSection,
+} from "../panel";
+
+export const RCON_ACCESS_VARIABLE = "RCON_EXPOSED";
+
+export const RCON_ACCESS_PORT = "rcon";
+
+export const RCON_ACCESS_MODULE = "rconAccess";
+
+export const RCON_ACCESS_ROTATE = "rotate";
+
+export const RCON_ACCESS_HOST_RANGE: ManifestHostRange = {
+	default: 12_500,
+	min: 12_500,
+	max: 12_599,
+};
+
+export const RCON_PASSWORD_LENGTH = 24;
+
+export const LOOPBACK_HOST = "127.0.0.1";
+
+export const ANY_HOST = "0.0.0.0";
+
+const FORM_SECTION_ID = "rcon-access";
+
+const DETAIL_SECTION_ID = "rcon-access-detail";
+
+const REFRESH_SECONDS = 30;
+
+const DEFAULT_PROTOCOL: LocalizedText = {
+	ar: "RCON",
+	en: "RCON",
+};
+
+const ACCESS_TITLE: LocalizedText = {
+	ar: "الوصول عن بُعد",
+	en: "Remote access",
+};
+
+const ACCESS_DESCRIPTION: LocalizedText = {
+	ar: "الوصول عن بُعد يخلي أداة خارجية تتحكم بسيرفرك بكلمة المرور هذي. الكلمة تمشي على النت بدون تشفير، فاقفل الوصول لما ما فيه أداة تستخدمه، ولا تعطي الكلمة أحد. لو تسربت غيّرها على طول.",
+	en: "Remote access lets an external tool control your server with this password. The password crosses the internet in the clear, so turn remote access off when no tool is using it, and never share the password. Rotate it the moment it leaks.",
+};
+
+const OPEN_BADGE: BridgeDetailBadge = {
+	label: {
+		ar: "مفتوح",
+		en: "Open",
+	},
+	tone: BridgeDetailTone.Success,
+};
+
+const CLOSED_BADGE: BridgeDetailBadge = {
+	label: {
+		ar: "مقفول",
+		en: "Closed",
+	},
+	tone: BridgeDetailTone.Neutral,
+};
+
+const PENDING_BADGE: BridgeDetailBadge = {
+	label: {
+		ar: "يطبّق بعد إعادة التشغيل",
+		en: "Applies after restart",
+	},
+	tone: BridgeDetailTone.Warning,
+};
+
+export const rconExposed = (context: BridgeContext): boolean => {
+	return context.variable(RCON_ACCESS_VARIABLE) === "true";
+};
+
+export const rconBindHost = (context: BridgeContext): string => {
+	return rconExposed(context) ? ANY_HOST : LOOPBACK_HOST;
+};
+
+export interface RconAccessPassword {
+	value: string;
+	pending: boolean;
+}
+
+export interface RconAccessOptions {
+	protocol?: LocalizedText;
+	portKey?: string;
+	tools?: LocalizedText;
+	password(context: BridgeContext): Promise<RconAccessPassword | null>;
+	rotate(context: BridgeContext): Promise<void>;
+}
+
+export interface RconAccessSectionsOptions {
+	protocol?: LocalizedText;
+	portKey?: string;
+}
+
+const describeAccess = (tools: LocalizedText | undefined): LocalizedText => {
+	if (!tools) {
+		return ACCESS_DESCRIPTION;
+	}
+
+	return {
+		ar: `${ACCESS_DESCRIPTION.ar} ${tools.ar}`,
+		en: `${ACCESS_DESCRIPTION.en} ${tools.en}`,
+	};
+};
+
+const badgesFor = (exposed: boolean, pending: boolean): BridgeDetailBadge[] => {
+	const badges = [
+		exposed ? OPEN_BADGE : CLOSED_BADGE,
+	];
+
+	if (pending) {
+		badges.push(PENDING_BADGE);
+	}
+
+	return badges;
+};
+
+const declaredPort = (context: BridgeContext, key: string): number | null => {
+	try {
+		return context.port(key);
+	} catch {
+		return null;
+	}
+};
+
+export const createRconAccess = (options: RconAccessOptions): BridgeDetailModule => {
+	const protocol = options.protocol ?? DEFAULT_PROTOCOL;
+	const portKey = options.portKey ?? RCON_ACCESS_PORT;
+
+	return {
+		kind: BridgeKind.Detail,
+		refreshSeconds: REFRESH_SECONDS,
+		async read(context) {
+			const password = await options.password(context);
+
+			if (!password) {
+				return null;
+			}
+
+			return {
+				id: RCON_ACCESS_MODULE,
+				title: ACCESS_TITLE,
+				subtitle: protocol,
+				description: describeAccess(options.tools),
+				image: null,
+				badges: badgesFor(rconExposed(context), password.pending),
+				stats: [
+					{
+						key: "port",
+						label: {
+							ar: `منفذ ${protocol.ar}`,
+							en: `${protocol.en} port`,
+						},
+						value: declaredPort(context, portKey),
+						format: BridgeDetailFormat.Number,
+					},
+					{
+						key: "password",
+						label: {
+							ar: `كلمة مرور ${protocol.ar}`,
+							en: `${protocol.en} password`,
+						},
+						value: password.value,
+						format: BridgeDetailFormat.Secret,
+					},
+				],
+				links: [],
+				stale: false,
+				actions: [
+					RCON_ACCESS_ROTATE,
+				],
+			};
+		},
+		actions: {
+			async [RCON_ACCESS_ROTATE](context) {
+				await options.rotate(context);
+
+				context.log("rotated the remote access password");
+
+				return null;
+			},
+		},
+	};
+};
+
+export const rconAccessSections = (options: RconAccessSectionsOptions = {}): BridgeSection[] => {
+	const protocol = options.protocol ?? DEFAULT_PROTOCOL;
+	const dedicated = (options.portKey ?? RCON_ACCESS_PORT) === RCON_ACCESS_PORT;
+
+	return [
+		{
+			layout: BridgeLayout.Form,
+			id: FORM_SECTION_ID,
+			title: ACCESS_TITLE,
+			target: BridgeFormTarget.Variables,
+			reinstall: false,
+			confirm: BridgeConfirm.Normal,
+			confirmText: {
+				ar: "نعيد تشغيل سيرفرك عشان يشتغل التغيير.",
+				en: "We restart your server so the change takes effect.",
+			},
+			fields: [
+				{
+					key: RCON_ACCESS_VARIABLE,
+					control: BridgeControl.Boolean,
+					label: ACCESS_TITLE,
+					help: dedicated
+						? {
+								ar: `يفتح منفذ ${protocol.ar} عشان تتحكم بسيرفرك من أداة خارجية. المنفذ يطلع مع بقية عناوين سيرفرك بعد ما يرجع يشتغل.`,
+								en: `Opens the ${protocol.en} port so an external tool can control your server. The port appears with your server's other addresses once it is back up.`,
+							}
+						: {
+								ar: `يشغّل الوصول عن بُعد عشان تتحكم بسيرفرك من أداة خارجية على نفس عنوان اللعبة ومنفذها.`,
+								en: `Turns remote access on so an external tool can control your server over the same address and port as the game.`,
+							},
+					warning: {
+						ar: "كلمة المرور تمشي على النت بدون تشفير. اقفل الوصول لما ما تستخدمه.",
+						en: "The password crosses the internet in the clear. Turn it off when you are not using it.",
+					},
+				},
+			],
+		},
+		{
+			layout: BridgeLayout.Detail,
+			id: DETAIL_SECTION_ID,
+			title: ACCESS_TITLE,
+			module: RCON_ACCESS_MODULE,
+			actions: [
+				{
+					id: RCON_ACCESS_ROTATE,
+					label: {
+						ar: "غيّر كلمة المرور",
+						en: "Rotate the password",
+					},
+					confirm: BridgeConfirm.Strong,
+					confirmText: {
+						ar: "كل أداة خارجية عندك بتوقف لين تحط الكلمة الجديدة فيها.",
+						en: "Every external tool you use stops working until you paste the new password into it.",
+					},
+				},
+			],
+			empty: {
+				ar: "شغّل سيرفرك مرة عشان تتولد كلمة المرور.",
+				en: "Start your server once to generate the password.",
+			},
+		},
+	];
+};