@serverkgg/bridge 0.0.21 → 0.1.2

package/src/bot/detect/sensitiveKey.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, test } from "bun:test";
+import { isSensitiveKey, keySegments } from "./sensitiveKey";
+
+describe("isSensitiveKey", () => {
+	test("reads a key as whole segments, split on underscores, case changes and digits", () => {
+		expect(keySegments("DISCORD_BOT_TOKEN")).toEqual([
+			"DISCORD",
+			"BOT",
+			"TOKEN",
+		]);
+		expect(keySegments("discordToken")).toEqual([
+			"DISCORD",
+			"TOKEN",
+		]);
+		expect(keySegments("TOKEN2__X")).toEqual([
+			"TOKEN",
+			"2",
+			"X",
+		]);
+	});
+
+	test("hides every key that names a secret in one of its segments", () => {
+		for (const key of [
+			"DISCORD_TOKEN",
+			"TELEGRAM_BOT_TOKEN",
+			"discordToken",
+			"TOKEN2",
+			"API_KEY",
+			"OPENAI_APIKEY",
+			"CLIENT_SECRET",
+			"DB_PASSWORD",
+			"SMTP_PASS",
+			"AUTH_HEADER",
+			"GOOGLE_CREDENTIALS",
+			"GCP_CREDENTIAL",
+			"PRIVATE_KEY_PEM",
+			"DISCORD_WEBHOOK",
+			"SENTRY_DSN",
+			"JWT_SIGNING_KEY",
+			"PASSWORD_SALT",
+			"SESSION_SECRET",
+			"COOKIE_NAME",
+			"SIGNING_ALGORITHM",
+		]) {
+			expect(isSensitiveKey(key), key).toBe(true);
+		}
+	});
+
+	test("hides connection strings, which carry their password inside the link", () => {
+		for (const key of [
+			"DATABASE_URL",
+			"DB_URI",
+			"MONGODB_URI",
+			"MONGO_URL",
+			"POSTGRES_URL",
+			"MYSQL_URL",
+			"REDIS_URL",
+			"REDISURL",
+			"AMQP_URL",
+			"CONNECTION_STRING",
+			"SHADOW_DATABASE_URL",
+			"DATABASE_URL_POOLED",
+		]) {
+			expect(isSensitiveKey(key), key).toBe(true);
+		}
+	});
+
+	test("leaves plain settings visible, including words that only contain a secret word", () => {
+		for (const key of [
+			"AUTHOR",
+			"AUTHOR_NAME",
+			"KEYWORD",
+			"KEYWORDS",
+			"MONKEY_MODE",
+			"BYPASS_CACHE",
+			"COMPASS_ID",
+			"TOKENIZER",
+			"URL",
+			"API_URL",
+			"BASE_URI",
+			"WEBSITE_URL",
+			"GUILD_ID",
+			"LOG_LEVEL",
+			"PREFIX",
+			"DATABASE_NAME",
+			"REDIS_HOST",
+		]) {
+			expect(isSensitiveKey(key), key).toBe(false);
+		}
+	});
+});

package/src/bot/detect/sensitiveKey.ts

@@ -0,0 +1,44 @@
+const SENSITIVE_SEGMENTS: ReadonlySet<string> = new Set([
+	"TOKEN",
+	"TOKENS",
+	"SECRET",
+	"SECRETS",
+	"PASSWORD",
+	"PASSWD",
+	"PASSPHRASE",
+	"PASS",
+	"KEY",
+	"KEYS",
+	"APIKEY",
+	"AUTH",
+	"CREDENTIAL",
+	"CREDENTIALS",
+	"PRIVATE",
+	"WEBHOOK",
+	"DSN",
+	"JWT",
+	"SALT",
+	"COOKIE",
+	"SESSION",
+	"SIGNING",
+]);
+
+export const CONNECTION_STRING_PATTERN =
+	/(?:^|_)(?:DATABASE|DB|MONGO|MONGODB|POSTGRES|POSTGRESQL|MYSQL|REDIS|AMQP|CONNECTION)_?(?:URL|URI|STRING)(?:_|$)/;
+
+export const keySegments = (key: string): string[] => {
+	return key
+		.replace(/([a-z])(?=[A-Z])/g, "$1_")
+		.replace(/([A-Za-z])(?=[0-9])|([0-9])(?=[A-Za-z])/g, "$1$2_")
+		.toUpperCase()
+		.split("_")
+		.filter((segment) => segment.length > 0);
+};
+
+export const isSensitiveKey = (key: string) => {
+	const segments = keySegments(key);
+
+	return (
+		segments.some((segment) => SENSITIVE_SEGMENTS.has(segment)) || CONNECTION_STRING_PATTERN.test(segments.join("_"))
+	);
+};

package/src/bot/detect/serverkJson.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, test } from "bun:test";
+import { BotFramework } from "./botFramework";
+import { BotPlatform } from "./botPlatform";
+import { BotRuntime } from "./botRuntime";
+import { parseServerkJson } from "./serverkJson";
+
+describe("parseServerkJson", () => {
+	test("reads every field and ignores unknown ones", () => {
+		expect(
+			parseServerkJson(
+				JSON.stringify({
+					$schema: "https://serverk.gg/serverk.json",
+					runtime: "python",
+					platform: "discord",
+					framework: "discord-py",
+					start: " python -m bot ",
+					install: "pip install -r requirements/prod.txt",
+					env: [
+						"GUILD_ID",
+						{
+							key: "DISCORD_TOKEN",
+							sensitive: true,
+						},
+					],
+				}),
+			),
+		).toEqual({
+			runtime: BotRuntime.Python,
+			platform: BotPlatform.Discord,
+			framework: BotFramework.DiscordPy,
+			start: "python -m bot",
+			install: "pip install -r requirements/prod.txt",
+			env: [
+				{
+					key: "GUILD_ID",
+					sensitive: null,
+					example: null,
+				},
+				{
+					key: "DISCORD_TOKEN",
+					sensitive: true,
+					example: null,
+				},
+			],
+		});
+	});
+
+	test("accepts an empty object", () => {
+		expect(parseServerkJson("{}")).toEqual({
+			runtime: null,
+			platform: null,
+			framework: null,
+			start: null,
+			install: null,
+			env: [],
+		});
+	});
+
+	test("refuses a file with any field it cannot trust", () => {
+		for (const text of [
+			"[]",
+			"not json",
+			'{"runtime":"go"}',
+			'{"platform":"slack"}',
+			'{"start":""}',
+			'{"start":"a\\nb"}',
+			'{"install":""}',
+			'{"install":["npm","ci"]}',
+			`{"start":"${"x".repeat(1025)}"}`,
+			'{"env":["1BAD"]}',
+			'{"env":[{"key":"A","sensitive":"yes"}]}',
+		]) {
+			expect(parseServerkJson(text)).toBeNull();
+		}
+	});
+
+	test("counts a command's length in characters, not UTF-16 units", () => {
+		const command = `echo ${"🤖".repeat(1019)}`;
+
+		expect(
+			parseServerkJson(
+				JSON.stringify({
+					start: command,
+				}),
+			)?.start,
+		).toBe(command);
+	});
+});

package/src/bot/detect/serverkJson.ts

@@ -0,0 +1,174 @@
+import { type BotFramework, isBotFramework } from "./botFramework";
+import { type BotPlatform, isBotPlatform } from "./botPlatform";
+import { type BotRuntime, isBotRuntime } from "./botRuntime";
+import { isEnvKey } from "./envKey";
+
+export const SERVERK_JSON = "serverk.json";
+
+export interface ServerkJsonEnv {
+	key: string;
+	sensitive: boolean | null;
+	example: string | null;
+}
+
+export interface ServerkJson {
+	runtime: BotRuntime | null;
+	platform: BotPlatform | null;
+	framework: BotFramework | null;
+	start: string | null;
+	install: string | null;
+	env: ServerkJsonEnv[];
+}
+
+export const SERVERK_JSON_COMMAND_LENGTH_LIMIT = 1024;
+
+export const SERVERK_JSON_EXAMPLE_LENGTH_LIMIT = 256;
+
+export const SERVERK_JSON_ENV_LIMIT = 100;
+
+const codePointLength = (value: string) => {
+	return Array.from(value).length;
+};
+
+type Parsed<Value> =
+	| {
+			ok: true;
+			value: Value;
+	  }
+	| {
+			ok: false;
+	  };
+
+const accept = <Value>(value: Value): Parsed<Value> => ({
+	ok: true,
+	value,
+});
+
+const REFUSED = {
+	ok: false,
+} as const;
+
+const optionalOf = <Value>(raw: unknown, guard: (value: string) => value is Value & string): Parsed<Value | null> => {
+	if (raw === undefined || raw === null) {
+		return accept(null);
+	}
+
+	return typeof raw === "string" && guard(raw) ? accept(raw) : REFUSED;
+};
+
+const commandOf = (raw: unknown): Parsed<string | null> => {
+	if (raw === undefined || raw === null) {
+		return accept(null);
+	}
+
+	if (typeof raw !== "string") {
+		return REFUSED;
+	}
+
+	const command = raw.trim();
+
+	return command.length > 0 && codePointLength(command) <= SERVERK_JSON_COMMAND_LENGTH_LIMIT && !command.includes("\n")
+		? accept(command)
+		: REFUSED;
+};
+
+const envEntryOf = (raw: unknown): Parsed<ServerkJsonEnv> => {
+	if (typeof raw === "string") {
+		return isEnvKey(raw)
+			? accept({
+					key: raw,
+					sensitive: null,
+					example: null,
+				})
+			: REFUSED;
+	}
+
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+		return REFUSED;
+	}
+
+	const entry = raw as Record<string, unknown>;
+	const key = entry.key;
+	const sensitive = entry.sensitive ?? null;
+	const example = entry.example ?? null;
+
+	if (typeof key !== "string" || !isEnvKey(key)) {
+		return REFUSED;
+	}
+
+	if (sensitive !== null && typeof sensitive !== "boolean") {
+		return REFUSED;
+	}
+
+	if (
+		example !== null
+		&& (typeof example !== "string" || codePointLength(example) > SERVERK_JSON_EXAMPLE_LENGTH_LIMIT)
+	) {
+		return REFUSED;
+	}
+
+	return accept({
+		key,
+		sensitive,
+		example,
+	});
+};
+
+const envOf = (raw: unknown): Parsed<ServerkJsonEnv[]> => {
+	if (raw === undefined || raw === null) {
+		return accept([]);
+	}
+
+	if (!Array.isArray(raw) || raw.length > SERVERK_JSON_ENV_LIMIT) {
+		return REFUSED;
+	}
+
+	const entries: ServerkJsonEnv[] = [];
+
+	for (const item of raw) {
+		const entry = envEntryOf(item);
+
+		if (!entry.ok) {
+			return REFUSED;
+		}
+
+		entries.push(entry.value);
+	}
+
+	return accept(entries);
+};
+
+export const parseServerkJson = (text: string): ServerkJson | null => {
+	let raw: unknown;
+
+	try {
+		raw = JSON.parse(text);
+	} catch {
+		return null;
+	}
+
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+		return null;
+	}
+
+	const document = raw as Record<string, unknown>;
+	const runtime = optionalOf(document.runtime, isBotRuntime);
+	const platform = optionalOf(document.platform, isBotPlatform);
+	const framework = optionalOf(document.framework, isBotFramework);
+	const start = commandOf(document.start);
+	const install = commandOf(document.install);
+	const env = envOf(document.env);
+
+	if (!runtime.ok || !platform.ok || !framework.ok || !start.ok || !install.ok || !env.ok) {
+		return null;
+	}
+
+	return {
+		runtime: runtime.value,
+		platform: platform.value,
+		framework: framework.value,
+		start: start.value,
+		install: install.value,
+		env: env.value,
+	};
+};

package/src/bot/index.ts

@@ -0,0 +1,8 @@
+export * from "./botDeploy";
+export * from "./botEnvironment";
+export * from "./botIdentity";
+export * from "./botPanel";
+export * from "./botState";
+export * from "./botTerminal";
+export * from "./botVariables";
+export * from "./detect";

package/src/cli/detectTable.test.ts

@@ -0,0 +1,66 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { renderDetectTable } from "../bot/detect";
+import { runDetectTable } from "./detectTable";
+
+describe("serverk-bridge detect-table", () => {
+	let root = "";
+	let restore = () => {};
+
+	beforeEach(() => {
+		root = mkdtempSync(join(tmpdir(), "serverk-detect-table-"));
+
+		const spy = spyOn(console, "log").mockImplementation(() => {});
+
+		restore = () => spy.mockRestore();
+	});
+
+	afterEach(() => {
+		restore();
+		rmSync(root, {
+			force: true,
+			recursive: true,
+		});
+	});
+
+	test("writes the table the launchers read, then passes its own check", async () => {
+		const out = join(root, "detect.json");
+
+		await runDetectTable([
+			"--out",
+			out,
+		]);
+
+		expect(readFileSync(out, "utf8")).toBe(renderDetectTable());
+
+		await runDetectTable([
+			"--out",
+			out,
+			"--check",
+		]);
+	});
+
+	test("fails the check on a stale or missing table", async () => {
+		const out = join(root, "detect.json");
+
+		await expect(
+			runDetectTable([
+				"--out",
+				out,
+				"--check",
+			]),
+		).rejects.toThrow("is missing");
+
+		writeFileSync(out, "{}\n");
+
+		await expect(
+			runDetectTable([
+				"--out",
+				out,
+				"--check",
+			]),
+		).rejects.toThrow("is out of date");
+	});
+});

package/src/cli/detectTable.ts

@@ -0,0 +1,43 @@
+import { parseArgs } from "node:util";
+import { DETECT_TABLE_FILE, renderDetectTable } from "../bot/detect";
+import { writeRenderedFile } from "./renderedFile";
+
+const HELP = `serverk-bridge detect-table [options]
+
+options:
+  --out <path>   file to write (default: ${DETECT_TABLE_FILE})
+  --check        fail when the file on disk is out of date instead of writing
+  --help         show this help`;
+
+export const runDetectTable = async (args: string[]) => {
+	const { values } = parseArgs({
+		args,
+		options: {
+			out: {
+				type: "string",
+				default: DETECT_TABLE_FILE,
+			},
+			check: {
+				type: "boolean",
+				default: false,
+			},
+			help: {
+				type: "boolean",
+				default: false,
+			},
+		},
+	});
+
+	if (values.help) {
+		console.log(HELP);
+
+		return;
+	}
+
+	writeRenderedFile({
+		out: values.out,
+		check: values.check,
+		rendered: renderDetectTable(),
+		command: "serverk-bridge detect-table",
+	});
+};

package/src/cli/main.ts

@@ -2,6 +2,7 @@
 
 import { errorText } from "../runtime/bridgeLog";
 import { runCompile } from "./compile";
+import { runDetectTable } from "./detectTable";
 import { runLink } from "./link";
 import { runSchema } from "./schema";
 import { runValidate } from "./validate";
@@ -9,10 +10,11 @@ import { runValidate } from "./validate";
 const USAGE = `serverk-bridge <command>
 
 commands:
-  validate   validate serverk.yml, assets, and driver wiring
-  schema     write the serverk.yml JSON Schema for editor tooling
-  compile    compile the bridge binary for amd64
-  link       use a local bridge checkout while developing
+  validate       validate serverk.yml, assets, and driver wiring
+  schema         write the serverk.yml JSON Schema for editor tooling
+  detect-table   write the bot detection table the launchers read
+  compile        compile the bridge binary for amd64
+  link           use a local bridge checkout while developing
 
 run "serverk-bridge <command> --help" for options`;
 
@@ -32,6 +34,12 @@ try {
 			break;
 		}
 
+		case "detect-table": {
+			await runDetectTable(args);
+
+			break;
+		}
+
 		case "compile": {
 			await runCompile(args);
 

package/src/cli/renderedFile.ts

@@ -0,0 +1,35 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+export interface RenderedFile {
+	out: string;
+	check: boolean;
+	rendered: string;
+	command: string;
+}
+
+export const writeRenderedFile = (file: RenderedFile) => {
+	const target = resolve(file.out);
+
+	if (file.check) {
+		let current: string;
+
+		try {
+			current = readFileSync(target, "utf8");
+		} catch {
+			throw new Error(`${file.out} is missing — run "${file.command}" and commit it`);
+		}
+
+		if (current !== file.rendered) {
+			throw new Error(`${file.out} is out of date — run "${file.command}" and commit it`);
+		}
+
+		console.log(`${file.out} is up to date`);
+
+		return;
+	}
+
+	writeFileSync(target, file.rendered);
+
+	console.log(`wrote ${file.out}`);
+};

package/src/cli/schema.ts

@@ -1,7 +1,6 @@
-import { readFileSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { renderJsonSchema, SCHEMA_FILE } from "../manifest";
+import { writeRenderedFile } from "./renderedFile";
 
 const HELP = `serverk-bridge schema [options]
 
@@ -35,28 +34,10 @@ export const runSchema = async (args: string[]) => {
 		return;
 	}
 
-	const target = resolve(values.out);
-	const rendered = renderJsonSchema();
-
-	if (values.check) {
-		let current: string;
-
-		try {
-			current = readFileSync(target, "utf8");
-		} catch {
-			throw new Error(`${values.out} is missing — run "serverk-bridge schema" and commit it`);
-		}
-
-		if (current !== rendered) {
-			throw new Error(`${values.out} is out of date — run "serverk-bridge schema" and commit it`);
-		}
-
-		console.log(`${values.out} is up to date`);
-
-		return;
-	}
-
-	writeFileSync(target, rendered);
-
-	console.log(`wrote ${values.out}`);
+	writeRenderedFile({
+		out: values.out,
+		check: values.check,
+		rendered: renderJsonSchema(),
+		command: "serverk-bridge schema",
+	});
 };