@serverkgg/bridge 0.0.21 → 0.1.1

package/src/bot/botEnvironment.ts

@@ -0,0 +1,141 @@
+import type { BotConfig } from "./botVariables";
+import type { BotPlatform } from "./detect";
+import { BOT_PLATFORM, isReservedBotKey, SERVERK_BOT, SERVERK_SERVER_CODE } from "./detect";
+
+export const LAUNCHER_REPO_URL = "SERVERK_REPO_URL";
+
+export const LAUNCHER_REPO_REF = "SERVERK_REPO_REF";
+
+export const LAUNCHER_REPO_BRANCH = "SERVERK_REPO_BRANCH";
+
+export const LAUNCHER_GIT_TOKEN = "SERVERK_GIT_TOKEN";
+
+export const LAUNCHER_START_COMMAND = "SERVERK_START_COMMAND";
+
+export const LAUNCHER_INSTALL_COMMAND = "SERVERK_INSTALL_COMMAND";
+
+export const LAUNCHER_ROOT_DIRECTORY = "SERVERK_ROOT_DIRECTORY";
+
+export const LAUNCHER_DEPLOYMENT_ID = "SERVERK_DEPLOYMENT_ID";
+
+export const LAUNCHER_SNAPSHOT_ID = "SERVERK_SNAPSHOT_ID";
+
+export const LAUNCHER_STATE_DIR = "SERVERK_STATE_DIR";
+
+export const LAUNCHER_DETECT_TABLE = "SERVERK_DETECT_TABLE";
+
+export const LAUNCHER_KEYS: readonly string[] = [
+	LAUNCHER_REPO_URL,
+	LAUNCHER_REPO_REF,
+	LAUNCHER_REPO_BRANCH,
+	LAUNCHER_GIT_TOKEN,
+	LAUNCHER_START_COMMAND,
+	LAUNCHER_INSTALL_COMMAND,
+	LAUNCHER_ROOT_DIRECTORY,
+	LAUNCHER_DEPLOYMENT_ID,
+	LAUNCHER_SNAPSHOT_ID,
+	LAUNCHER_STATE_DIR,
+	LAUNCHER_DETECT_TABLE,
+];
+
+export const customerEnvironment = (
+	variables: Readonly<Record<string, string>>,
+	secrets: Readonly<Record<string, string>>,
+): Record<string, string> => {
+	const environment: Record<string, string> = {};
+
+	for (const [key, value] of [
+		...Object.entries(variables),
+		...Object.entries(secrets),
+	]) {
+		if (!isReservedBotKey(key)) {
+			environment[key] = value;
+		}
+	}
+
+	return environment;
+};
+
+export const launcherEnvironment = (config: BotConfig, stateDir: string): Record<string, string> => {
+	const environment: Record<string, string> = {
+		[LAUNCHER_STATE_DIR]: stateDir,
+	};
+
+	const mapped: [
+		string,
+		string | null,
+	][] = [
+		[
+			LAUNCHER_REPO_URL,
+			config.repo,
+		],
+		[
+			LAUNCHER_REPO_REF,
+			config.repo ? config.ref : null,
+		],
+		[
+			LAUNCHER_REPO_BRANCH,
+			config.repo ? config.branch : null,
+		],
+		[
+			LAUNCHER_GIT_TOKEN,
+			config.repo ? config.gitToken : null,
+		],
+		[
+			LAUNCHER_START_COMMAND,
+			config.startCommand,
+		],
+		[
+			LAUNCHER_INSTALL_COMMAND,
+			config.installCommand,
+		],
+		[
+			LAUNCHER_ROOT_DIRECTORY,
+			config.rootDirectory,
+		],
+		[
+			LAUNCHER_DEPLOYMENT_ID,
+			config.deployment,
+		],
+		[
+			LAUNCHER_SNAPSHOT_ID,
+			config.snapshot,
+		],
+	];
+
+	for (const [key, value] of mapped) {
+		if (value !== null) {
+			environment[key] = value;
+		}
+	}
+
+	return environment;
+};
+
+export const platformEnvironment = (code: string, platform: BotPlatform | null): Record<string, string> => {
+	return {
+		[SERVERK_BOT]: "1",
+		[SERVERK_SERVER_CODE]: code,
+		...(platform
+			? {
+					[BOT_PLATFORM]: platform,
+				}
+			: {}),
+	};
+};
+
+export interface BotProcessEnvironmentInput {
+	tool: Record<string, string>;
+	customer: Record<string, string>;
+	launcher: Record<string, string>;
+	platform: Record<string, string>;
+}
+
+export const botProcessEnvironment = (input: BotProcessEnvironmentInput): Record<string, string> => {
+	return {
+		...input.tool,
+		...input.customer,
+		...input.launcher,
+		...input.platform,
+	};
+};

package/src/bot/botIdentity.test.ts

@@ -0,0 +1,251 @@
+import { describe, expect, test } from "bun:test";
+import {
+	botNameOf,
+	IDENTITY_CACHE_FILE,
+	identityFromToken,
+	inviteLink,
+	LOGIN_LINE,
+	readIdentityCache,
+	resolveBotIdentity,
+	watchLoginLine,
+	writeIdentityCache,
+} from "./botIdentity";
+import { BotPlatform } from "./detect";
+
+const DISCORD_ID = "1136470478027245683";
+
+const DISCORD_TOKEN = `${btoa(DISCORD_ID).replaceAll("=", "")}.GxYz12.${"a".repeat(38)}`;
+
+const TELEGRAM_TOKEN = "7123456789:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw";
+
+const JWT = `${btoa('{"alg":"HS256","typ":"JWT"}').replaceAll("=", "")}.eyJzdWIiOiIxIn0.${"b".repeat(43)}`;
+
+const memoryFiles = (initial: Record<string, string> = {}) => {
+	const stored = new Map<string, string>(Object.entries(initial));
+
+	return {
+		stored,
+		files: {
+			async exists(path: string) {
+				return stored.has(path);
+			},
+			async read(path: string) {
+				return stored.get(path) ?? "";
+			},
+			async write(path: string, content: string) {
+				stored.set(path, content);
+			},
+		},
+	};
+};
+
+describe("LOGIN_LINE", () => {
+	test("reads the name from the login lines the popular libraries and our templates print", () => {
+		const names = [
+			"Logged in as MyBot#1234, /ping is registered",
+			"Logged in as MyBot (ID: 1136470478027245683)",
+			"Logged in as @serverk_test_bot",
+			"[INFO] logged in as mybot!",
+		].map((line) => botNameOf(LOGIN_LINE.exec(line)?.groups?.name ?? ""));
+
+		expect(names).toEqual([
+			"MyBot#1234",
+			"MyBot",
+			"serverk_test_bot",
+			"mybot",
+		]);
+	});
+
+	test("ignores lines that only mention logging", () => {
+		expect(LOGIN_LINE.test("serverk: bot process starting")).toBe(false);
+		expect(LOGIN_LINE.test("user logged out")).toBe(false);
+	});
+});
+
+describe("identityFromToken", () => {
+	test("reads a Telegram bot id and a Discord application id without the network", () => {
+		expect(identityFromToken(BotPlatform.Telegram, TELEGRAM_TOKEN)).toBe("7123456789");
+		expect(identityFromToken(BotPlatform.Discord, DISCORD_TOKEN)).toBe(DISCORD_ID);
+	});
+
+	test("refuses anything that is not shaped like the platform's token", () => {
+		expect(identityFromToken(BotPlatform.Discord, JWT)).toBeNull();
+		expect(identityFromToken(BotPlatform.Discord, TELEGRAM_TOKEN)).toBeNull();
+		expect(identityFromToken(BotPlatform.Telegram, DISCORD_TOKEN)).toBeNull();
+		expect(identityFromToken(BotPlatform.Telegram, "")).toBeNull();
+	});
+});
+
+describe("the name cache", () => {
+	test("keeps only the name the bot printed, per platform", async () => {
+		const { files, stored } = memoryFiles();
+
+		await writeIdentityCache(files, {
+			platform: BotPlatform.Telegram,
+			name: "serverk_test_bot",
+			seenAt: "2026-09-27T10:00:00.000Z",
+		});
+
+		expect(JSON.parse(stored.get(IDENTITY_CACHE_FILE) ?? "{}")).toEqual({
+			platform: BotPlatform.Telegram,
+			name: "serverk_test_bot",
+			seenAt: "2026-09-27T10:00:00.000Z",
+		});
+		expect((await readIdentityCache(files, BotPlatform.Telegram))?.name).toBe("serverk_test_bot");
+		expect(await readIdentityCache(files, BotPlatform.Discord)).toBeNull();
+	});
+
+	test("reads nothing from a broken or older cache", async () => {
+		expect(
+			await readIdentityCache(
+				memoryFiles({
+					[IDENTITY_CACHE_FILE]: "{",
+				}).files,
+				BotPlatform.Discord,
+			),
+		).toBeNull();
+		expect(
+			await readIdentityCache(
+				memoryFiles({
+					[IDENTITY_CACHE_FILE]: JSON.stringify({
+						key: "abc",
+						identity: {},
+					}),
+				}).files,
+				BotPlatform.Discord,
+			),
+		).toBeNull();
+	});
+});
+
+describe("inviteLink", () => {
+	test("invites a Discord bot by id and opens a Telegram bot by name", () => {
+		expect(
+			inviteLink({
+				platform: BotPlatform.Discord,
+				id: DISCORD_ID,
+				name: null,
+				seenAt: null,
+			}),
+		).toBe(`https://discord.com/oauth2/authorize?client_id=${DISCORD_ID}&scope=bot+applications.commands`);
+		expect(
+			inviteLink({
+				platform: BotPlatform.Telegram,
+				id: "7123456789",
+				name: "serverk_test_bot",
+				seenAt: null,
+			}),
+		).toBe("https://t.me/serverk_test_bot");
+	});
+
+	test("offers nothing it cannot build", () => {
+		expect(
+			inviteLink({
+				platform: BotPlatform.Discord,
+				id: null,
+				name: "MyBot",
+				seenAt: null,
+			}),
+		).toBeNull();
+		expect(
+			inviteLink({
+				platform: BotPlatform.Telegram,
+				id: "7123456789",
+				name: null,
+				seenAt: null,
+			}),
+		).toBeNull();
+	});
+});
+
+describe("watchLoginLine", () => {
+	test("remembers the first login name and stops listening", async () => {
+		const { files, stored } = memoryFiles();
+		const watchers: ((match: RegExpMatchArray) => void)[] = [];
+		let unsubscribed = 0;
+
+		const context = {
+			files,
+			logs: {
+				tail: async () => [],
+				watch: async () => null,
+				follow(pattern: RegExp, onMatch: (match: RegExpMatchArray) => void) {
+					watchers.push((match) => onMatch(match));
+					expect(pattern).toBe(LOGIN_LINE);
+
+					return () => {
+						unsubscribed += 1;
+					};
+				},
+			},
+			log: Object.assign(() => {}, {
+				warn: () => {},
+				error: () => {},
+			}),
+		};
+
+		watchLoginLine(context, BotPlatform.Discord);
+
+		const deliver = (line: string) => {
+			const match = LOGIN_LINE.exec(line);
+
+			if (match) {
+				for (const watcher of watchers) {
+					watcher(match);
+				}
+			}
+		};
+
+		deliver("Logged in as FirstBot#0001");
+		deliver("Logged in as SecondBot#0002");
+
+		await Bun.sleep(10);
+
+		expect(unsubscribed).toBe(1);
+		expect(JSON.parse(stored.get(IDENTITY_CACHE_FILE) ?? "{}")).toMatchObject({
+			platform: BotPlatform.Discord,
+			name: "FirstBot#0001",
+		});
+	});
+});
+
+describe("resolveBotIdentity", () => {
+	test("combines the inferred platform, the id from the token and the remembered name", async () => {
+		const { files } = memoryFiles({
+			[IDENTITY_CACHE_FILE]: JSON.stringify({
+				platform: BotPlatform.Discord,
+				name: "MyBot#1234",
+				seenAt: "2026-09-27T10:00:00.000Z",
+			}),
+		});
+
+		expect(
+			await resolveBotIdentity({
+				files,
+				variables: () => ({
+					GUILD_ID: "1",
+				}),
+				secrets: () => ({
+					DISCORD_TOKEN,
+				}),
+			}),
+		).toEqual({
+			platform: BotPlatform.Discord,
+			id: DISCORD_ID,
+			name: "MyBot#1234",
+			seenAt: "2026-09-27T10:00:00.000Z",
+		});
+	});
+
+	test("knows nothing about a bot with no platform hint", async () => {
+		expect(
+			await resolveBotIdentity({
+				files: memoryFiles().files,
+				variables: () => ({}),
+				secrets: () => ({
+					API_KEY: "sk-live-123",
+				}),
+			}),
+		).toBeNull();
+	});
+});

package/src/bot/botIdentity.ts

@@ -0,0 +1,140 @@
+import { z } from "zod";
+import type { BridgeContext, BridgeFiles } from "../context";
+import { BOT_STATE_DIR } from "./botState";
+import { BotPlatform, discordApplicationId, findBotToken, inferBotPlatform, telegramBotId } from "./detect";
+
+export const IDENTITY_CACHE_FILE = `${BOT_STATE_DIR}/identity.json`;
+
+export const LOGIN_LINE = /\blogged in as @?(?<name>[^\s,!()]+)/i;
+
+export const LOGIN_WATCH_MS = 600_000;
+
+export const BOT_NAME_LENGTH_LIMIT = 64;
+
+export interface BotIdentity {
+	platform: BotPlatform;
+	id: string | null;
+	name: string | null;
+	seenAt: string | null;
+}
+
+const identityCacheSchema = z.object({
+	platform: z.enum(BotPlatform),
+	name: z.string().min(1).max(BOT_NAME_LENGTH_LIMIT),
+	seenAt: z.string(),
+});
+
+export type BotIdentityCache = z.infer<typeof identityCacheSchema>;
+
+const NAME_TRAILER = /[.:;]+$/;
+
+export const botNameOf = (raw: string): string | null => {
+	const name = raw.replace(NAME_TRAILER, "").slice(0, BOT_NAME_LENGTH_LIMIT);
+
+	return name.length === 0 ? null : name;
+};
+
+export const identityFromToken = (platform: BotPlatform, token: string): string | null => {
+	return platform === BotPlatform.Telegram ? telegramBotId(token) : discordApplicationId(token);
+};
+
+export const readIdentityCache = async (
+	files: Pick<BridgeFiles, "exists" | "read">,
+	platform: BotPlatform,
+): Promise<BotIdentityCache | null> => {
+	if (!(await files.exists(IDENTITY_CACHE_FILE))) {
+		return null;
+	}
+
+	try {
+		const cached = identityCacheSchema.safeParse(JSON.parse(await files.read(IDENTITY_CACHE_FILE)));
+
+		return cached.success && cached.data.platform === platform ? cached.data : null;
+	} catch {
+		return null;
+	}
+};
+
+export const writeIdentityCache = async (files: Pick<BridgeFiles, "write">, cache: BotIdentityCache) => {
+	await files.write(IDENTITY_CACHE_FILE, `${JSON.stringify(cache, null, "\t")}\n`);
+};
+
+export const inviteLink = (identity: BotIdentity): string | null => {
+	if (identity.platform === BotPlatform.Discord) {
+		return identity.id
+			? `https://discord.com/oauth2/authorize?client_id=${encodeURIComponent(identity.id)}&scope=bot+applications.commands`
+			: null;
+	}
+
+	return identity.name ? `https://t.me/${encodeURIComponent(identity.name)}` : null;
+};
+
+export interface LoginWatchContext extends Pick<BridgeContext, "logs" | "log"> {
+	files: Pick<BridgeFiles, "write">;
+}
+
+export const watchLoginLine = (context: LoginWatchContext, platform: BotPlatform) => {
+	let done = false;
+	let unsubscribe = () => {};
+	let timer: ReturnType<typeof setTimeout> | null = null;
+
+	const stop = () => {
+		done = true;
+		unsubscribe();
+
+		if (timer) {
+			clearTimeout(timer);
+		}
+	};
+
+	unsubscribe = context.logs.follow(LOGIN_LINE, (match) => {
+		const name = botNameOf(match.groups?.name ?? "");
+
+		if (done || !name) {
+			return;
+		}
+
+		stop();
+
+		void writeIdentityCache(context.files, {
+			platform,
+			name,
+			seenAt: new Date().toISOString(),
+		}).catch((error: unknown) => {
+			context.log.warn("the bot name was not remembered", {
+				error: error instanceof Error ? error.message : String(error),
+			});
+		});
+	});
+
+	timer = setTimeout(stop, LOGIN_WATCH_MS);
+	timer.unref?.();
+
+	return stop;
+};
+
+export interface IdentityContext extends Pick<BridgeContext, "variables" | "secrets"> {
+	files: Pick<BridgeFiles, "exists" | "read">;
+}
+
+export const resolveBotIdentity = async (context: IdentityContext): Promise<BotIdentity | null> => {
+	const maps = {
+		variables: context.variables(),
+		secrets: context.secrets(),
+	};
+	const platform = inferBotPlatform(maps);
+
+	if (!platform) {
+		return null;
+	}
+
+	const token = findBotToken(platform, maps);
+	const cache = await readIdentityCache(context.files, platform);
+
+	return {
+		platform,
+		id: token ? identityFromToken(platform, token.value) : null,
+		name: cache?.name ?? null,
+		seenAt: cache?.seenAt ?? null,
+	};
+};