@serverkgg/bridge 0.0.6 → 0.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@serverkgg/bridge",
-	"version": "0.0.6",
+	"version": "0.0.8",
 	"description": "Serverk game bridge — driver runtime, wire protocol, manifest schema, and maintainer CLI",
 	"homepage": "https://serverk.gg",
 	"license": "SEE LICENSE IN LICENSE.md",
@@ -21,11 +21,12 @@
 		"./protocol": "./src/protocol/index.ts",
 		"./manifest": "./src/manifest/index.ts",
 		"./guides": "./src/guides/index.ts",
+		"./wire": "./src/wire/index.ts",
 		"./package.json": "./package.json"
 	},
 	"scripts": {
 		"tsc": "tsc",
-		"test": "bun test"
+		"test": "bun test --parallel"
 	},
 	"dependencies": {
 		"zod": "4.4.3"

package/src/runtime/bridgeExec.ts

@@ -97,9 +97,10 @@ export const createBridgeExec = (target: BridgeExecTarget) => {
 			throw new BridgeExecError("the exec command is empty");
 		}
 
-		const { argv } = await unprivilegedArgv(command, target.uid, target.gid);
+		const { argv, credentials } = await unprivilegedArgv(command, target.uid, target.gid);
 
 		const child = Bun.spawn(argv, {
+			...credentials,
 			cwd: target.cwd,
 			env: {
 				...baseEnvironment(),

package/src/runtime/bridgePrivilege.test.ts

@@ -0,0 +1,77 @@
+import { afterEach, describe, expect, it, spyOn } from "bun:test";
+import { privilegePlan, readEffectiveUid, setprivArgv, spawnCredentials } from "./bridgePrivilege";
+
+const COMMAND = [
+	"java",
+	"-jar",
+	"server.jar",
+];
+
+describe("spawnCredentials", () => {
+	it("carries the uid and gid for the spawn options", () => {
+		expect(spawnCredentials(1000, 1000)).toEqual({
+			uid: 1000,
+			gid: 1000,
+		});
+	});
+});
+
+describe("setprivArgv", () => {
+	afterEach(() => {
+		spyOn(Bun, "which").mockRestore();
+	});
+
+	it("wraps the command with a full privilege drop", () => {
+		spyOn(Bun, "which").mockReturnValue("/usr/bin/setpriv");
+
+		expect(setprivArgv(COMMAND, 1000, 1000)).toEqual([
+			"setpriv",
+			"--reuid=1000",
+			"--regid=1000",
+			"--clear-groups",
+			"--",
+			...COMMAND,
+		]);
+	});
+
+	it("refuses to build a wrapper the image cannot run", () => {
+		spyOn(Bun, "which").mockReturnValue(null);
+
+		expect(() => setprivArgv(COMMAND, 1000, 1000)).toThrow("setpriv is missing");
+	});
+});
+
+describe("privilegePlan", () => {
+	afterEach(() => {
+		spyOn(Bun, "which").mockRestore();
+	});
+
+	it("passes credentials to the runtime when the spawn uid option is honoured", () => {
+		const plan = privilegePlan(true, COMMAND, 1000, 1000);
+
+		expect(plan.argv, "a native runtime must run the bare command").toEqual(COMMAND);
+		expect(plan.credentials, "the drop must ride the spawn options or the game runs as root").toEqual({
+			uid: 1000,
+			gid: 1000,
+		});
+	});
+
+	it("falls back to setpriv with no spawn credentials otherwise", () => {
+		spyOn(Bun, "which").mockReturnValue("/usr/bin/setpriv");
+
+		const plan = privilegePlan(false, COMMAND, 1000, 1000);
+
+		expect(plan.argv.at(0), "the wrapper must lead the argv").toBe("setpriv");
+		expect(plan.credentials, "credentials on a setpriv wrapper would fail the spawn").toEqual({});
+	});
+});
+
+describe("readEffectiveUid", () => {
+	it("reads this process's own effective uid", async () => {
+		expect(await readEffectiveUid(process.pid)).toBe(process.getuid?.() ?? 0);
+	});
+
+	it("answers null for a pid that does not exist", async () => {
+		expect(await readEffectiveUid(2 ** 22 - 1)).toBeNull();
+	});
+});

package/src/runtime/bridgePrivilege.ts

@@ -39,14 +39,16 @@ export const settleUid = async (pid: number, expected: number) => {
 	return observed;
 };
 
-const spawnWithUid = (command: string[], uid: number, gid: number) => {
-	const credentials: object = {
+export const spawnCredentials = (uid: number, gid: number): object => {
+	return {
 		uid,
 		gid,
 	};
+};
 
+const spawnWithUid = (command: string[], uid: number, gid: number) => {
 	return Bun.spawn(command, {
-		...credentials,
+		...spawnCredentials(uid, gid),
 		stderr: "ignore",
 		stdin: "ignore",
 		stdout: "ignore",
@@ -89,11 +91,13 @@ export const setprivArgv = (command: string[], uid: number, gid: number) => {
 	];
 };
 
-export const unprivilegedArgv = async (command: string[], uid: number, gid: number) => {
-	const native = await probeNativeUid(uid, gid);
-
+export const privilegePlan = (native: boolean, command: string[], uid: number, gid: number) => {
 	return {
 		argv: native ? command : setprivArgv(command, uid, gid),
-		native,
+		credentials: native ? spawnCredentials(uid, gid) : {},
 	};
 };
+
+export const unprivilegedArgv = async (command: string[], uid: number, gid: number) => {
+	return privilegePlan(await probeNativeUid(uid, gid), command, uid, gid);
+};

package/src/runtime/bridgeSupervisor.ts

@@ -218,8 +218,9 @@ export const createSupervisor = (options: SupervisorOptions) => {
 			...rest,
 		];
 
-		const { argv: spawnArgv } = await unprivilegedArgv(argv, options.uid, options.gid);
+		const { argv: spawnArgv, credentials } = await unprivilegedArgv(argv, options.uid, options.gid);
 		const spawned = Bun.spawn(spawnArgv, {
+			...credentials,
 			cwd: options.cwd,
 			stderr: "pipe",
 			stdin: "pipe",

package/src/wire/index.ts

@@ -0,0 +1,2 @@
+export * from "./panel";
+export * from "./zEnvKey";

package/src/wire/panel.test.ts

@@ -0,0 +1,285 @@
+import { describe, expect, test } from "bun:test";
+import {
+	BridgeAccess,
+	BridgeAction,
+	BridgeConfirm,
+	BridgeControl,
+	BridgeFormTarget,
+	BridgeKind,
+	BridgeLayout,
+	type BridgeManifest,
+} from "@serverkgg/bridge/protocol";
+import { bridgeManifestSchema } from "./panel";
+
+const text = (value: string) => ({
+	ar: value,
+	en: value,
+});
+
+const manifest = (): BridgeManifest => ({
+	version: "1.0.0",
+	panel: {
+		tabs: [
+			{
+				id: "gameplay",
+				title: text("Gameplay"),
+				access: BridgeAccess.Invoke,
+				sections: [
+					{
+						layout: BridgeLayout.Actions,
+						id: "broadcast",
+						title: text("Broadcast"),
+						help: text("Send a message to everyone playing"),
+						module: "broadcast",
+						actions: [
+							{
+								id: "say",
+								label: text("Say"),
+								fields: [
+									{
+										key: "message",
+										control: BridgeControl.Text,
+										label: text("Message"),
+										maxLength: 200,
+									},
+								],
+							},
+							{
+								id: "saveAll",
+								label: text("Save"),
+								confirm: BridgeConfirm.Normal,
+							},
+						],
+					},
+					{
+						layout: BridgeLayout.Table,
+						id: "players",
+						module: "players",
+						columns: [
+							{
+								key: "name",
+								label: text("Name"),
+							},
+						],
+						actions: [
+							{
+								id: "xp",
+								label: text("Give XP"),
+								fields: [
+									{
+										key: "amount",
+										control: BridgeControl.Number,
+										label: text("Amount"),
+										min: 1,
+										max: 1000,
+									},
+									{
+										key: "kind",
+										control: BridgeControl.Select,
+										label: text("Kind"),
+										options: [
+											{
+												value: "levels",
+												label: text("Levels"),
+											},
+											{
+												value: "points",
+												label: text("Points"),
+											},
+										],
+									},
+								],
+							},
+						],
+					},
+				],
+			},
+		],
+	},
+	terminal: null,
+	modules: [
+		{
+			id: "broadcast",
+			kind: BridgeKind.Actions,
+			requiresRunning: true,
+			refreshSeconds: null,
+			pageSize: null,
+			dependsOn: [],
+			actions: [
+				"say",
+				"saveAll",
+			],
+		},
+		{
+			id: "players",
+			kind: BridgeKind.Collection,
+			requiresRunning: true,
+			refreshSeconds: 10,
+			pageSize: null,
+			dependsOn: [],
+			actions: [
+				"list",
+				"xp",
+			],
+		},
+	],
+	events: [
+		"PlayerJoined",
+	],
+});
+
+const previewManifest = (): BridgeManifest => ({
+	version: "1.0.0",
+	panel: {
+		tabs: [
+			{
+				id: "version",
+				title: text("Version"),
+				sections: [
+					{
+						layout: BridgeLayout.Form,
+						id: "version",
+						target: BridgeFormTarget.Variables,
+						preview: {
+							module: "transition",
+						},
+						reinstall: true,
+						confirm: BridgeConfirm.Strong,
+						fields: [
+							{
+								key: "MC_VERSION",
+								control: BridgeControl.Text,
+								label: text("Version"),
+							},
+						],
+					},
+				],
+			},
+		],
+	},
+	terminal: null,
+	modules: [
+		{
+			id: "transition",
+			kind: BridgeKind.Preview,
+			requiresRunning: false,
+			refreshSeconds: null,
+			pageSize: null,
+			dependsOn: [],
+			actions: [
+				BridgeAction.Preview,
+			],
+		},
+	],
+	events: [],
+});
+
+const tabsOf = (count: number) => {
+	return Array.from({
+		length: count,
+	}).map((_entry, index) => ({
+		id: `tab-${index}`,
+		title: text(`Tab ${index}`),
+		sections: [
+			{
+				layout: BridgeLayout.Actions,
+				id: "broadcast",
+				module: "broadcast",
+				actions: [
+					{
+						id: "say",
+						label: text("Say"),
+					},
+				],
+			},
+		],
+	}));
+};
+
+describe("the panel mirror", () => {
+	test("carries an actions section and its fields through unchanged", () => {
+		const source = manifest();
+		const parsed = bridgeManifestSchema.parse(source);
+
+		expect(parsed).toEqual(source);
+	});
+
+	test("refuses an action carrying more fields than a prompt fits", () => {
+		const source = manifest();
+		const [tab] = source.panel?.tabs ?? [];
+		const [section] = tab?.sections ?? [];
+
+		if (section?.layout !== BridgeLayout.Actions) {
+			throw new Error("fixture is missing its actions section");
+		}
+
+		const [action] = section.actions;
+
+		if (!action) {
+			throw new Error("fixture is missing its action");
+		}
+
+		action.fields = Array.from({
+			length: 6,
+		}).map((_entry, index) => ({
+			key: `field${index}`,
+			control: BridgeControl.Text,
+			label: text("Field"),
+		}));
+
+		expect(bridgeManifestSchema.safeParse(source).success).toBe(false);
+	});
+
+	test("keeps a variables form's preview ref instead of stripping it", () => {
+		const source = previewManifest();
+		const parsed = bridgeManifestSchema.parse(source);
+		const [section] = parsed.panel?.tabs[0]?.sections ?? [];
+
+		if (section?.layout !== BridgeLayout.Form) {
+			throw new Error("fixture is missing its form section");
+		}
+
+		expect(section.preview).toEqual({
+			module: "transition",
+		});
+		expect(parsed).toEqual(source);
+	});
+
+	test("takes a preview module and the preview action it answers", () => {
+		const parsed = bridgeManifestSchema.parse(previewManifest());
+
+		expect(parsed.modules[0]).toEqual({
+			id: "transition",
+			kind: BridgeKind.Preview,
+			requiresRunning: false,
+			refreshSeconds: null,
+			pageSize: null,
+			dependsOn: [],
+			actions: [
+				BridgeAction.Preview,
+			],
+		});
+	});
+
+	test("takes eight tabs and refuses nine", () => {
+		const source = manifest();
+
+		expect(
+			bridgeManifestSchema.safeParse({
+				...source,
+				panel: {
+					tabs: tabsOf(8),
+				},
+			}).success,
+		).toBe(true);
+
+		expect(
+			bridgeManifestSchema.safeParse({
+				...source,
+				panel: {
+					tabs: tabsOf(9),
+				},
+			}).success,
+		).toBe(false);
+	});
+});

package/src/wire/panel.ts

@@ -0,0 +1,263 @@
+import {
+	BRIDGE_ID_PATTERN,
+	BRIDGE_MODULE_ID_PATTERN,
+	BridgeAccess,
+	BridgeConfirm,
+	BridgeControl,
+	BridgeFormTarget,
+	BridgeIcon,
+	BridgeKind,
+	BridgeLayout,
+	type BridgeManifest,
+	type BridgePanel,
+	type BridgeSection,
+	BridgeStream,
+	type BridgeTerminalArg,
+	type BridgeTerminalCommand,
+	BridgeTerminalLevel,
+	type BridgeTerminalManifest,
+	type BridgeTerminalRuleManifest,
+} from "@serverkgg/bridge/protocol";
+import { z } from "zod";
+import { zEnvKey } from "./zEnvKey";
+
+const PANEL_TEXT_LENGTH_LIMIT = 512;
+
+const ACTION_FIELDS_LIMIT = 5;
+
+const SECTION_ACTIONS_LIMIT = 10;
+
+const zKey = z
+	.string()
+	.min(1)
+	.max(64)
+	.regex(/^[A-Za-z][A-Za-z0-9_-]*$/);
+
+const zBridgeId = z.string().min(1).max(32).regex(BRIDGE_ID_PATTERN);
+
+export const zBridgeModuleId = z.string().min(1).max(32).regex(BRIDGE_MODULE_ID_PATTERN);
+
+export const bridgeValueSchema = z.union([
+	z.boolean(),
+	z.number(),
+	z.string().max(8192),
+	z.null(),
+]);
+
+export type BridgeValueInput = z.infer<typeof bridgeValueSchema>;
+
+export const bridgeValuesSchema = z.record(zKey, bridgeValueSchema);
+
+export type BridgeValuesInput = z.infer<typeof bridgeValuesSchema>;
+
+export const panelTextSchema = z.object({
+	ar: z.string().min(1).max(PANEL_TEXT_LENGTH_LIMIT),
+	en: z.string().min(1).max(PANEL_TEXT_LENGTH_LIMIT),
+});
+
+export const bridgeOptionSchema = z.object({
+	value: z.string().min(1).max(128),
+	label: panelTextSchema,
+	help: panelTextSchema.optional(),
+	latest: z.boolean().optional(),
+});
+
+export const bridgeVisibleWhenSchema = z
+	.object({
+		variable: zKey,
+		values: z.array(z.string().max(128)).min(1).max(16).optional(),
+		empty: z.boolean().optional(),
+	})
+	.refine((rule) => rule.empty !== undefined || rule.values !== undefined);
+
+export const bridgeOptionsRefSchema = z.object({
+	module: zBridgeModuleId,
+});
+
+export const bridgePreviewRefSchema = z.object({
+	module: zBridgeModuleId,
+});
+
+export const bridgeFieldSchema = z.object({
+	key: zKey,
+	control: z.enum(BridgeControl),
+	label: panelTextSchema,
+	help: panelTextSchema.optional(),
+	warning: panelTextSchema.optional(),
+	placeholder: z.string().max(256).optional(),
+	min: z.number().optional(),
+	max: z.number().optional(),
+	step: z.number().optional(),
+	maxLength: z.int().positive().optional(),
+	options: z
+		.union([
+			z.array(bridgeOptionSchema).max(64),
+			bridgeOptionsRefSchema,
+		])
+		.optional(),
+	visibleWhen: bridgeVisibleWhenSchema.optional(),
+});
+
+export const bridgeSectionActionSchema = z.object({
+	id: zKey,
+	label: panelTextSchema,
+	confirm: z.enum(BridgeConfirm).optional(),
+	confirmText: panelTextSchema.optional(),
+	download: z.boolean().optional(),
+	fields: z.array(bridgeFieldSchema).max(ACTION_FIELDS_LIMIT).optional(),
+});
+
+export const bridgeSectionAddSchema = z.object({
+	label: panelTextSchema,
+	placeholder: z.string().max(256).optional(),
+});
+
+export const bridgeSectionUploadSchema = z.object({
+	label: panelTextSchema,
+	extensions: z.array(z.string().min(1).max(16)).min(1).max(8),
+	staging: z.string().min(1).max(128),
+});
+
+export const bridgeActionsSectionSchema = z.object({
+	layout: z.literal(BridgeLayout.Actions),
+	id: zBridgeId,
+	title: panelTextSchema.optional(),
+	help: panelTextSchema.optional(),
+	module: zBridgeModuleId,
+	actions: z.array(bridgeSectionActionSchema).min(1).max(SECTION_ACTIONS_LIMIT),
+	visibleWhen: bridgeVisibleWhenSchema.optional(),
+	access: z.enum(BridgeAccess).optional(),
+});
+
+export const bridgeFormSectionSchema = z.object({
+	layout: z.literal(BridgeLayout.Form),
+	id: zBridgeId,
+	title: panelTextSchema.optional(),
+	target: z.enum(BridgeFormTarget),
+	module: zBridgeModuleId.optional(),
+	preview: bridgePreviewRefSchema.optional(),
+	reinstall: z.boolean().optional(),
+	restartHint: z.boolean().optional(),
+	confirm: z.enum(BridgeConfirm).optional(),
+	confirmText: panelTextSchema.optional(),
+	fields: z.array(bridgeFieldSchema).min(1).max(32),
+	visibleWhen: bridgeVisibleWhenSchema.optional(),
+	access: z.enum(BridgeAccess).optional(),
+});
+
+export const bridgeColumnSchema = z.object({
+	key: zKey,
+	label: panelTextSchema,
+});
+
+export const bridgeTableSectionSchema = z.object({
+	layout: z.literal(BridgeLayout.Table),
+	id: zBridgeId,
+	title: panelTextSchema.optional(),
+	module: zBridgeModuleId,
+	restartHint: z.boolean().optional(),
+	columns: z.array(bridgeColumnSchema).min(1).max(8),
+	add: bridgeSectionAddSchema.optional(),
+	upload: bridgeSectionUploadSchema.optional(),
+	actions: z.array(bridgeSectionActionSchema).max(8).optional(),
+	empty: panelTextSchema.optional(),
+	visibleWhen: bridgeVisibleWhenSchema.optional(),
+	access: z.enum(BridgeAccess).optional(),
+});
+
+export const bridgeCardsSectionSchema = z.object({
+	layout: z.literal(BridgeLayout.Cards),
+	id: zBridgeId,
+	title: panelTextSchema.optional(),
+	module: zBridgeModuleId,
+	titleKey: zKey,
+	subtitleKey: zKey.optional(),
+	actions: z.array(bridgeSectionActionSchema).max(8).optional(),
+	empty: panelTextSchema.optional(),
+	visibleWhen: bridgeVisibleWhenSchema.optional(),
+	access: z.enum(BridgeAccess).optional(),
+});
+
+export const bridgeCatalogSectionSchema = z.object({
+	layout: z.literal(BridgeLayout.Catalog),
+	id: zBridgeId,
+	title: panelTextSchema.optional(),
+	module: zBridgeModuleId,
+	restartHint: z.boolean().optional(),
+	reinstall: z.boolean().optional(),
+	variable: zEnvKey.optional(),
+	confirm: z.enum(BridgeConfirm).optional(),
+	confirmText: panelTextSchema.optional(),
+	empty: panelTextSchema.optional(),
+	visibleWhen: bridgeVisibleWhenSchema.optional(),
+	access: z.enum(BridgeAccess).optional(),
+});
+
+export const bridgeSectionSchema: z.ZodType<BridgeSection> = z.discriminatedUnion("layout", [
+	bridgeActionsSectionSchema,
+	bridgeCardsSectionSchema,
+	bridgeCatalogSectionSchema,
+	bridgeFormSectionSchema,
+	bridgeTableSectionSchema,
+]);
+
+export const bridgeTabSchema = z.object({
+	id: zBridgeId,
+	title: panelTextSchema,
+	icon: z.enum(BridgeIcon).optional(),
+	sections: z.array(bridgeSectionSchema).min(1).max(8),
+	access: z.enum(BridgeAccess).optional(),
+});
+
+export const bridgePanelSchema: z.ZodType<BridgePanel> = z.object({
+	tabs: z.array(bridgeTabSchema).min(1).max(8),
+});
+
+export const bridgeTerminalArgSchema: z.ZodType<BridgeTerminalArg> = z.object({
+	key: zKey,
+	label: panelTextSchema.optional(),
+	required: z.boolean().optional(),
+	variadic: z.boolean().optional(),
+	values: z.array(z.string().min(1).max(64)).max(64).optional(),
+	module: zBridgeModuleId.optional(),
+	column: zKey.optional(),
+});
+
+export const bridgeTerminalCommandSchema: z.ZodType<BridgeTerminalCommand> = z.object({
+	name: z.string().min(1).max(64),
+	summary: panelTextSchema,
+	syntax: z.string().max(160).optional(),
+	args: z.array(bridgeTerminalArgSchema).max(8).optional(),
+	danger: z.boolean().optional(),
+	requiresRunning: z.boolean().optional(),
+});
+
+export const bridgeTerminalRuleSchema: z.ZodType<BridgeTerminalRuleManifest> = z.object({
+	match: z.string().min(1).max(512),
+	flags: z.string().max(8),
+	level: z.enum(BridgeTerminalLevel),
+	stream: z.enum(BridgeStream).optional(),
+});
+
+export const bridgeTerminalManifestSchema: z.ZodType<BridgeTerminalManifest> = z.object({
+	commands: z.array(bridgeTerminalCommandSchema).max(128),
+	rules: z.array(bridgeTerminalRuleSchema).max(64),
+});
+
+export const bridgeModuleManifestSchema = z.object({
+	id: zBridgeModuleId,
+	kind: z.enum(BridgeKind),
+	requiresRunning: z.boolean(),
+	refreshSeconds: z.int().positive().nullable(),
+	pageSize: z.int().positive().nullable().default(null),
+	dependsOn: z.array(zKey).max(8),
+	actions: z.array(z.string().min(1).max(64)).max(16),
+});
+
+export const bridgeManifestSchema: z.ZodType<BridgeManifest> = z.object({
+	version: z.string(),
+	panel: bridgePanelSchema.nullable(),
+	terminal: bridgeTerminalManifestSchema.nullable().default(null),
+	modules: z.array(bridgeModuleManifestSchema).max(32),
+	events: z.array(z.string().min(1).max(64)).max(32),
+});

package/src/wire/zEnvKey.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+
+export const zEnvKey = z
+	.string()
+	.min(2)
+	.max(32)
+	.regex(/^[A-Z][A-Z0-9_]*$/);