@serverkgg/bridge 0.0.21 → 0.1.2

package/src/runtime/bridgeServer.ts

@@ -1,5 +1,12 @@
 import { timingSafeEqual } from "node:crypto";
-import { BridgeFailureError, BridgeSecretError, BridgeUserError, type BridgeValues } from "../core";
+import type { Socket } from "bun";
+import {
+	type BridgeActivity,
+	BridgeFailureError,
+	BridgeSecretError,
+	BridgeUserError,
+	type BridgeValues,
+} from "../core";
 import {
 	BRIDGE_FRAME_LIMIT,
 	type BridgeAnnounceResult,
@@ -15,7 +22,10 @@ import {
 	type BridgeSetupResult,
 	type BridgeStatus,
 } from "../protocol";
-import { type BridgeLogger, errorText } from "./bridgeLog";
+import type { BridgeActivityAnswer } from "./bridgeActivity";
+import { type BridgeLogger, errorDetail } from "./bridgeLog";
+import { redactLocalized } from "./bridgeRedaction";
+import { BridgeRefusalError } from "./bridgeRefusalError";
 
 export interface ServerOptions {
 	socket: string;
@@ -25,7 +35,12 @@ export interface ServerOptions {
 	onStart: () => Promise<void>;
 	onStop: () => Promise<void>;
 	onCommand: (input: string, expect: string | undefined, timeoutMs: number | undefined) => Promise<BridgeCommandResult>;
-	onInvoke: (module: string, action: string, args: BridgeValues, recoveryOperationId?: string) => Promise<unknown>;
+	onInvoke: (
+		module: string,
+		action: string,
+		args: BridgeValues,
+		recoveryOperationId?: string,
+	) => Promise<BridgeActivityAnswer<unknown>>;
 	onEvents: (cursor: number) => BridgeEventsResult;
 	onSample: () => Promise<BridgeSampleResult>;
 	onQuiesce: (supportsSnapshot: boolean, leaseId?: string) => Promise<BridgeQuiesceResult>;
@@ -35,8 +50,15 @@ export interface ServerOptions {
 	onPendingList: () => Promise<BridgePendingResult>;
 	onPendingAdd: (input: string) => Promise<BridgePendingResult>;
 	onSetupStatus: () => BridgeSetupResult;
-	onSetupSubmit: (step: string, action: string, args: BridgeValues) => Promise<BridgeSetupResult>;
+	onSetupSubmit: (step: string, action: string, args: BridgeValues) => Promise<BridgeActivityAnswer<BridgeSetupResult>>;
+	onUndelivered: (activity: BridgeActivity[]) => void;
 	onLog: BridgeLogger;
+	redact?: (text: string) => string;
+}
+
+interface SocketState {
+	buffer: string;
+	closed: boolean;
 }
 
 interface IncomingFrame {
@@ -71,6 +93,23 @@ const encode = (response: BridgeResponse) => {
 	return `${JSON.stringify(response)}\n`;
 };
 
+interface PlainAnswer {
+	result: unknown;
+	activity: null;
+}
+
+const deliver = (socket: Socket<SocketState>, frame: string): boolean => {
+	if (socket.data.closed) {
+		return false;
+	}
+
+	try {
+		return socket.write(frame) === Buffer.byteLength(frame);
+	} catch {
+		return false;
+	}
+};
+
 const asArgs = (value: unknown): BridgeValues => {
 	if (value === null || typeof value !== "object" || Array.isArray(value)) {
 		return {};
@@ -87,6 +126,23 @@ const asArgs = (value: unknown): BridgeValues => {
 	return out;
 };
 
+const logFailure = (onLog: BridgeLogger, method: string, error: unknown) => {
+	if (error instanceof BridgeUserError || error instanceof BridgeRefusalError) {
+		onLog("bridge call refused", {
+			method,
+			error: errorDetail(error),
+		});
+
+		return;
+	}
+
+	onLog("bridge call failed", {
+		method,
+		error: errorDetail(error),
+		stack: error instanceof Error ? (error.stack ?? null) : null,
+	});
+};
+
 export const createServer = (options: ServerOptions) => {
 	const handle = async (method: string, request: IncomingFrame): Promise<unknown> => {
 		switch (method) {
@@ -118,15 +174,6 @@ export const createServer = (options: ServerOptions) => {
 				);
 			}
 
-			case BridgeMethod.Invoke: {
-				return await options.onInvoke(
-					String(request.module ?? ""),
-					String(request.action ?? ""),
-					asArgs(request.args),
-					asText(request.recoveryOperationId) ?? undefined,
-				);
-			}
-
 			case BridgeMethod.Events: {
 				return options.onEvents(typeof request.cursor === "number" ? request.cursor : 0);
 			}
@@ -177,33 +224,68 @@ export const createServer = (options: ServerOptions) => {
 				return options.onSetupStatus();
 			}
 
-			case BridgeMethod.SetupSubmit: {
-				const step = asText(request.module);
+			default: {
+				throw new Error(`unknown method "${method}"`);
+			}
+		}
+	};
+
+	const answer = async (
+		method: string,
+		request: IncomingFrame,
+	): Promise<BridgeActivityAnswer<unknown> | PlainAnswer> => {
+		if (method === BridgeMethod.Invoke) {
+			return await options.onInvoke(
+				String(request.module ?? ""),
+				String(request.action ?? ""),
+				asArgs(request.args),
+				asText(request.recoveryOperationId) ?? undefined,
+			);
+		}
 
-				if (!step) {
-					throw new Error("setupSubmit needs a step id");
-				}
+		if (method === BridgeMethod.SetupSubmit) {
+			const step = asText(request.module);
 
-				return await options.onSetupSubmit(step, String(request.action ?? ""), asArgs(request.args));
+			if (!step) {
+				throw new Error("setupSubmit needs a step id");
 			}
 
-			default: {
-				throw new Error(`unknown method "${method}"`);
-			}
+			return await options.onSetupSubmit(step, String(request.action ?? ""), asArgs(request.args));
 		}
+
+		return {
+			result: await handle(method, request),
+			activity: null,
+		};
+	};
+
+	const undelivered = (method: string, activity: BridgeActivity[]) => {
+		if (activity.length === 0) {
+			return;
+		}
+
+		options.onLog("answer not delivered, its activity goes to the events ring", {
+			method,
+			entries: activity.length,
+		});
+
+		options.onUndelivered(activity);
 	};
 
-	return Bun.listen<{
-		buffer: string;
-	}>({
+	return Bun.listen<SocketState>({
 		unix: options.socket,
 		socket: {
 			open(socket) {
 				socket.data = {
 					buffer: "",
+					closed: false,
 				};
 			},
 
+			close(socket) {
+				socket.data.closed = true;
+			},
+
 			data(socket, chunk) {
 				socket.data.buffer += chunk.toString();
 
@@ -259,28 +341,43 @@ export const createServer = (options: ServerOptions) => {
 						continue;
 					}
 
-					void handle(String(request.method ?? ""), request)
-						.then((result) => {
-							socket.write(
-								encode({
+					void answer(String(request.method ?? ""), request)
+						.then(({ result, activity }) => {
+							const method = String(request.method ?? "");
+
+							let frame: string;
+
+							try {
+								frame = encode({
 									id,
 									ok: true,
 									result,
-								}),
-							);
+									...(activity === null
+										? {}
+										: {
+												activity,
+											}),
+								});
+							} catch (error) {
+								undelivered(method, activity ?? []);
+
+								throw error;
+							}
+
+							if (!deliver(socket, frame)) {
+								undelivered(method, activity ?? []);
+							}
 						})
 						.catch((error: unknown) => {
-							options.onLog("bridge call failed", {
-								method: String(request.method ?? ""),
-								error: errorText(error),
-								stack: error instanceof Error ? (error.stack ?? null) : null,
-							});
+							logFailure(options.onLog, String(request.method ?? ""), error);
+
+							const redact = options.redact ?? ((text: string) => text);
 
 							socket.write(
 								encode({
 									id,
 									ok: false,
-									error: errorText(error),
+									error: redact(errorDetail(error)),
 									...(error instanceof BridgeSecretError
 										? {
 												secret: error.key,
@@ -293,7 +390,17 @@ export const createServer = (options: ServerOptions) => {
 										: {}),
 									...(error instanceof BridgeUserError
 										? {
-												text: error.text,
+												text: redactLocalized(error.text, redact),
+											}
+										: {}),
+									...(error instanceof BridgeRefusalError
+										? {
+												unchanged: true,
+												...(error.text
+													? {
+															text: redactLocalized(error.text, redact),
+														}
+													: {}),
 											}
 										: {}),
 								}),

package/src/runtime/bridgeSetupHandlers.test.ts

@@ -3,7 +3,7 @@ import { tmpdir } from "node:os";
 import type { BridgeContext } from "../context";
 import { BridgeKind, BridgeSetupPromptKind, BridgeSetupStepKind, BridgeSetupStepState, BridgeUserError } from "../core";
 import type { BridgeDriver, BridgeSetupModule } from "../modules";
-import type { BridgeConfig, BridgeSetupRuntime } from "../protocol";
+import { type BridgeConfig, BridgeEventName, type BridgeSetupRuntime } from "../protocol";
 import { createContext } from "./bridgeContext";
 import type { BridgeLeveledLogger } from "./bridgeLog";
 import { log } from "./bridgeLog";
@@ -51,6 +51,12 @@ const contextOf = (): BridgeContext => {
 		onSetup() {
 			return;
 		},
+		onActivity() {
+			return;
+		},
+		async onRestart() {
+			return;
+		},
 	});
 };
 
@@ -143,7 +149,7 @@ describe("the setup handlers", () => {
 			runtime: null,
 		});
 
-		expect(await handlers.onSetupSubmit(contextOf(), "sign-in", "renew", {})).toEqual({
+		expect((await handlers.onSetupSubmit(contextOf(), "sign-in", "renew", {})).result).toEqual({
 			supported: false,
 			runtime: null,
 		});
@@ -204,7 +210,7 @@ describe("the setup handlers", () => {
 		const { logger } = recorder();
 		const handlers = createSetupHandlers(driverWith(setupWith()), logger);
 
-		expect(await handlers.onSetupSubmit(contextOf(), "sign-in", "renew", {})).toEqual({
+		expect((await handlers.onSetupSubmit(contextOf(), "sign-in", "renew", {})).result).toEqual({
 			supported: false,
 			runtime: null,
 		});
@@ -224,7 +230,7 @@ describe("the setup handlers", () => {
 
 		handlers.onSetup(signIn());
 
-		expect(await handlers.onSetupSubmit(contextOf(), "sign-in", "renew", {})).toEqual({
+		expect((await handlers.onSetupSubmit(contextOf(), "sign-in", "renew", {})).result).toEqual({
 			supported: true,
 			runtime: {
 				steps: [
@@ -248,6 +254,65 @@ describe("the setup handlers", () => {
 		expect(warnings.at(-1)?.message).toBe("setup submit rejected");
 	});
 
+	test("add one rejected entry built from the user error", async () => {
+		const { logger } = recorder();
+
+		const handlers = createSetupHandlers(
+			driverWith(
+				setupWith(async () => {
+					throw new BridgeUserError({
+						ar: "الكود ما عاد ينفع",
+						en: "this code cannot be renewed any more",
+					});
+				}),
+			),
+			logger,
+		);
+
+		handlers.onSetup(signIn());
+
+		const { activity } = await handlers.onSetupSubmit(contextOf(), "sign-in", "renew", {});
+
+		expect(activity).toEqual([
+			{
+				name: BridgeEventName.SetupRejected,
+				text: {
+					ar: "الكود ما عاد ينفع",
+					en: "this code cannot be renewed any more",
+				},
+				details: {
+					step: "sign-in",
+					action: "renew",
+				},
+			},
+		]);
+	});
+
+	test("answer what the driver reported while submitting", async () => {
+		const { logger } = recorder();
+
+		const handlers = createSetupHandlers(
+			driverWith(
+				setupWith(async (context) => {
+					context.activity.report({
+						name: BridgeEventName.SetupCompleted,
+						text: text("signed in"),
+					});
+				}),
+			),
+			logger,
+		);
+
+		const { activity } = await handlers.onSetupSubmit(contextOf(), "sign-in", "renew", {});
+
+		expect(activity).toEqual([
+			{
+				name: BridgeEventName.SetupCompleted,
+				text: text("signed in"),
+			},
+		]);
+	});
+
 	test("answer the runtime the driver reported while submitting", async () => {
 		const { logger } = recorder();
 
@@ -270,7 +335,7 @@ describe("the setup handlers", () => {
 
 		handlers.onSetup(signIn());
 
-		expect(await handlers.onSetupSubmit(contextOf(), "sign-in", "renew", {})).toEqual({
+		expect((await handlers.onSetupSubmit(contextOf(), "sign-in", "renew", {})).result).toEqual({
 			supported: true,
 			runtime: {
 				steps: [
@@ -301,3 +366,89 @@ describe("the setup handlers", () => {
 		);
 	});
 });
+
+describe("the setup handlers redaction", () => {
+	const SECRET = "123456789:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw";
+
+	const redact = (value: string) => value.split(SECRET).join("••••");
+
+	test("blanks a secret value in the prompt a driver reports", () => {
+		const { logger } = recorder();
+		const handlers = createSetupHandlers(driverWith(setupWith()), logger, redact);
+
+		handlers.onSetup({
+			steps: [
+				{
+					id: "sign-in",
+					state: BridgeSetupStepState.Active,
+				},
+			],
+			prompt: {
+				kind: BridgeSetupPromptKind.Progress,
+				message: text(`checking ${SECRET}`),
+				percent: 50,
+				detail: `token ${SECRET}`,
+			},
+		});
+
+		expect(handlers.onSetupStatus().runtime?.prompt).toEqual({
+			kind: BridgeSetupPromptKind.Progress,
+			message: text("checking ••••"),
+			percent: 50,
+			detail: "token ••••",
+		});
+	});
+
+	test("blanks a secret value in every text of a link prompt", () => {
+		const { logger } = recorder();
+		const handlers = createSetupHandlers(driverWith(setupWith()), logger, redact);
+		const reported = signIn();
+
+		handlers.onSetup({
+			...reported,
+			prompt: {
+				kind: BridgeSetupPromptKind.Link,
+				message: text(`sign in ${SECRET}`),
+				url: "https://hytale.com/device",
+				code: "ABCD-EFGH",
+				expiresAt: null,
+				actions: [
+					{
+						id: "renew",
+						label: text(`renew ${SECRET}`),
+					},
+				],
+			},
+		});
+
+		expect(JSON.stringify(handlers.current())).not.toContain(SECRET);
+		expect(handlers.current()?.prompt).toMatchObject({
+			message: text("sign in ••••"),
+			url: "https://hytale.com/device",
+			code: "ABCD-EFGH",
+		});
+	});
+
+	test("blanks a secret value in the text of a rejected submit", async () => {
+		const { logger } = recorder();
+		const handlers = createSetupHandlers(
+			driverWith(
+				setupWith(async () => {
+					throw new BridgeUserError(text(`telegram refused ${SECRET}`));
+				}),
+			),
+			logger,
+			redact,
+		);
+
+		handlers.onSetup(signIn());
+
+		const { result, activity } = await handlers.onSetupSubmit(contextOf(), "sign-in", "renew", {});
+
+		expect(result.runtime?.prompt).toMatchObject({
+			kind: BridgeSetupPromptKind.Failed,
+			message: text("telegram refused ••••"),
+		});
+		expect(JSON.stringify(activity)).not.toContain(SECRET);
+	});
+});

package/src/runtime/bridgeSetupHandlers.ts

@@ -1,29 +1,52 @@
 import type { BridgeContext } from "../context";
 import { BridgeUserError, type BridgeValues } from "../core";
 import type { BridgeDriver } from "../modules";
-import type { BridgeSetupResult, BridgeSetupRuntime } from "../protocol";
-import type { BridgeLeveledLogger } from "./bridgeLog";
+import { BridgeEventName, type BridgeSetupResult, type BridgeSetupRuntime } from "../protocol";
+import { type ActivityNormalizeOptions, type BridgeActivityAnswer, createActivityScope } from "./bridgeActivity";
+import { type BridgeLeveledLogger, errorDetail } from "./bridgeLog";
+import { type BridgeRedact, redactLocalized, redactSetupRuntime, secretFieldKeys } from "./bridgeRedaction";
+import { scopedContext } from "./bridgeScopedContext";
 import { failedSetup, normalizeSetupRuntime, unsupportedSetup } from "./bridgeSetup";
 
 export interface BridgeSetupHandlers {
 	onSetup(runtime: BridgeSetupRuntime | null): void;
 	onSetupStatus(): BridgeSetupResult;
-	onSetupSubmit(context: BridgeContext, step: string, action: string, args: BridgeValues): Promise<BridgeSetupResult>;
+	onSetupSubmit(
+		context: BridgeContext,
+		step: string,
+		action: string,
+		args: BridgeValues,
+	): Promise<BridgeActivityAnswer<BridgeSetupResult>>;
 	current(): BridgeSetupRuntime | null;
 }
 
-export const createSetupHandlers = (driver: BridgeDriver, log: BridgeLeveledLogger): BridgeSetupHandlers => {
+const unredacted: BridgeRedact = (text) => text;
+
+export const createSetupHandlers = (
+	driver: BridgeDriver,
+	log: BridgeLeveledLogger,
+	redact: BridgeRedact = unredacted,
+): BridgeSetupHandlers => {
 	const declared: ReadonlySet<string> = new Set((driver.setup?.steps ?? []).map((step) => step.id));
 
+	const activity: ActivityNormalizeOptions = {
+		secretKeys: new Set(secretFieldKeys(driver)),
+		redact,
+		warn: log.warn,
+	};
+
 	let current: BridgeSetupRuntime | null = null;
 
 	return {
 		onSetup(runtime) {
 			current = driver.setup
-				? normalizeSetupRuntime(runtime, {
-						declared,
-						warn: log.warn,
-					})
+				? redactSetupRuntime(
+						normalizeSetupRuntime(runtime, {
+							declared,
+							warn: log.warn,
+						}),
+						redact,
+					)
 				: null;
 		},
 		current() {
@@ -43,28 +66,50 @@ export const createSetupHandlers = (driver: BridgeDriver, log: BridgeLeveledLogg
 			const module = driver.setup;
 
 			if (!module?.submit) {
-				return unsupportedSetup();
+				return {
+					result: unsupportedSetup(),
+					activity: [],
+				};
 			}
 
+			const scope = createActivityScope(context.activity, activity);
+
 			try {
-				await module.submit(context, step, action, args);
+				await module.submit(scopedContext(context, scope.reporter), step, action, args);
 			} catch (error) {
 				if (!(error instanceof BridgeUserError)) {
+					scope.drain();
+
 					throw error;
 				}
 
 				log.warn("setup submit rejected", {
 					step,
 					action,
-					error: error.message,
+					error: errorDetail(error),
+				});
+
+				scope.reporter.report({
+					name: BridgeEventName.SetupRejected,
+					text: error.text,
+					details: {
+						step,
+						action,
+					},
 				});
 
-				return failedSetup(current, error.text);
+				return {
+					result: failedSetup(current, redactLocalized(error.text, redact)),
+					activity: scope.close(),
+				};
 			}
 
 			return {
-				supported: true,
-				runtime: current,
+				result: {
+					supported: true,
+					runtime: current,
+				},
+				activity: scope.close(),
 			};
 		},
 	};