@gajae-code/tui 0.18.11 → 0.19.0

package/src/terminal-capabilities.ts

@@ -404,6 +404,79 @@ export function setCellDimensions(dims: CellDimensions): void {
 	cellDimensions = dims;
 }
 
+/**
+ * Kitty caps a single APC escape at 4096 bytes, and every chunk except the last
+ * must carry a payload that is a multiple of 4 bytes (each chunk is decoded as
+ * its own base64 group). An escape that the terminal abandons mid-payload
+ * surfaces the remaining base64 as printable text in the transcript, so chunks
+ * are sized against the whole escape (introducer + control + `;` + data + ST)
+ * rather than against the data alone.
+ */
+const KITTY_MAX_ESCAPE_CHARS = 4096;
+/** `\x1b_G` + `;` + `\x1b\\` — the bytes around one chunk's control and data. */
+const KITTY_ESCAPE_FRAME_CHARS = 3 + 1 + 2;
+const KITTY_CHUNK_FLAG_CHARS = ",m=1".length;
+
+/**
+ * RFC 4648 base64, the same guard `encodeITerm2Multipart` already applies.
+ * The alphabet excludes ESC, ST, and BEL, so a payload cannot end an APC or OSC early.
+ * A linear scan, not a repeating-group regex: that regex rejects some multi-megabyte
+ * valid payloads in this runtime.
+ */
+function isBase64Alphabet(code: number): boolean {
+	return (
+		(code >= 65 && code <= 90) ||
+		(code >= 97 && code <= 122) ||
+		(code >= 48 && code <= 57) ||
+		code === 43 ||
+		code === 47
+	);
+}
+
+function isRfc4648Base64(value: string): boolean {
+	const length = value.length;
+	if (length % 4 !== 0) return false;
+	let body = length;
+	if (length > 0 && value.charCodeAt(length - 1) === 61) {
+		body = value.charCodeAt(length - 2) === 61 ? length - 2 : length - 1;
+	}
+	for (let index = 0; index < body; index++) {
+		if (!isBase64Alphabet(value.charCodeAt(index))) return false;
+	}
+	return true;
+}
+
+function assertIterm2Base64(value: string): void {
+	if (!isRfc4648Base64(value)) throw new Error("Invalid RFC 4648 base64");
+}
+
+/**
+ * Encode one kitty transmission behind `header` (the control string without a
+ * chunk flag), splitting the base64 payload so each escape fits
+ * {@link KITTY_MAX_ESCAPE_CHARS} and each non-final chunk keeps the protocol's
+ * 4-byte base64 quantum. A payload that fits in one escape carries no `m=`
+ * field at all.
+ */
+export function encodeKittyTransmission(header: string, base64Data: string): string {
+	assertIterm2Base64(base64Data);
+	const whole = `\x1b_G${header};${base64Data}\x1b\\`;
+	if (whole.length <= KITTY_MAX_ESCAPE_CHARS) return whole;
+	const chunks: string[] = [];
+	let offset = 0;
+	let first = true;
+	while (offset < base64Data.length) {
+		const budget =
+			KITTY_MAX_ESCAPE_CHARS - KITTY_ESCAPE_FRAME_CHARS - KITTY_CHUNK_FLAG_CHARS - (first ? header.length : 0);
+		const chunkSize = Math.max(4, budget - (budget % 4));
+		const chunk = base64Data.slice(offset, offset + chunkSize);
+		offset += chunk.length;
+		const more = offset < base64Data.length ? 1 : 0;
+		chunks.push(`\x1b_G${first ? `${header},m=${more}` : `m=${more}`};${chunk}\x1b\\`);
+		first = false;
+	}
+	return chunks.join("");
+}
+
 export function encodeKitty(
 	base64Data: string,
 	options: {
@@ -413,8 +486,6 @@ export function encodeKitty(
 		placementId?: number;
 	} = {},
 ): string {
-	const CHUNK_SIZE = 4096;
-
 	const params: string[] = ["a=T", "f=100", "q=2"];
 
 	if (options.columns) params.push(`c=${options.columns}`);
@@ -427,31 +498,7 @@ export function encodeKitty(
 		if (options.placementId) params.push(`p=${options.placementId}`);
 	}
 
-	if (base64Data.length <= CHUNK_SIZE) {
-		return `\x1b_G${params.join(",")};${base64Data}\x1b\\`;
-	}
-
-	const chunks: string[] = [];
-	let offset = 0;
-	let isFirst = true;
-
-	while (offset < base64Data.length) {
-		const chunk = base64Data.slice(offset, offset + CHUNK_SIZE);
-		const isLast = offset + CHUNK_SIZE >= base64Data.length;
-
-		if (isFirst) {
-			chunks.push(`\x1b_G${params.join(",")},m=1;${chunk}\x1b\\`);
-			isFirst = false;
-		} else if (isLast) {
-			chunks.push(`\x1b_Gm=0;${chunk}\x1b\\`);
-		} else {
-			chunks.push(`\x1b_Gm=1;${chunk}\x1b\\`);
-		}
-
-		offset += CHUNK_SIZE;
-	}
-
-	return chunks.join("");
+	return encodeKittyTransmission(params.join(","), base64Data);
 }
 
 /** Kitty image ids already uploaded to the terminal in this process. */
@@ -477,7 +524,8 @@ export function setKittyTransmitWriter(writer: (sequence: string) => void): void
 
 /**
  * Encode a kitty transmit-only (`a=t`) escape: uploads image data under a
- * stable id without creating a placement. Chunked at 4096 bytes per spec.
+ * stable id without creating a placement. Chunked so every escape stays within
+ * {@link KITTY_MAX_ESCAPE_CHARS}.
  *
  * This is deliberately separate from placement: re-sending data (`a=t`/`a=T`)
  * for an existing image id deletes the image and ALL of its placements, so
@@ -485,34 +533,7 @@ export function setKittyTransmitWriter(writer: (sequence: string) => void): void
  * {@link encodeKittyPlacement} only.
  */
 export function encodeKittyTransmit(base64Data: string, imageId: number): string {
-	const CHUNK_SIZE = 4096;
-	const params = ["a=t", "f=100", "q=2", `i=${imageId}`];
-
-	if (base64Data.length <= CHUNK_SIZE) {
-		return `\x1b_G${params.join(",")};${base64Data}\x1b\\`;
-	}
-
-	const chunks: string[] = [];
-	let offset = 0;
-	let isFirst = true;
-
-	while (offset < base64Data.length) {
-		const chunk = base64Data.slice(offset, offset + CHUNK_SIZE);
-		const isLast = offset + CHUNK_SIZE >= base64Data.length;
-
-		if (isFirst) {
-			chunks.push(`\x1b_G${params.join(",")},m=1;${chunk}\x1b\\`);
-			isFirst = false;
-		} else if (isLast) {
-			chunks.push(`\x1b_Gm=0;${chunk}\x1b\\`);
-		} else {
-			chunks.push(`\x1b_Gm=1;${chunk}\x1b\\`);
-		}
-
-		offset += CHUNK_SIZE;
-	}
-
-	return chunks.join("");
+	return encodeKittyTransmission(["a=t", "f=100", "q=2", `i=${imageId}`].join(","), base64Data);
 }
 
 /**
@@ -603,6 +624,7 @@ export function encodeITerm2(
 		inline?: boolean;
 	} = {},
 ): string {
+	assertIterm2Base64(base64Data);
 	const params: string[] = [`inline=${options.inline !== false ? 1 : 0}`];
 
 	if (options.width !== undefined) params.push(`width=${options.width}`);
@@ -825,6 +847,7 @@ export function renderImage(
 	const fit = calculateImageFit(imageDimensions, options, cellDims);
 
 	if (TERMINAL.imageProtocol === ImageProtocol.Kitty) {
+		if (!isRfc4648Base64(base64Data)) return null;
 		const imageId = options.imageId ?? kittyImageId(base64Data);
 		const placementId = options.placementId ?? 1;
 		// Upload data once per image id (out-of-band; the transmit escape is
@@ -853,6 +876,7 @@ export function renderImage(
 		}
 	}
 	if (TERMINAL.imageProtocol === ImageProtocol.Iterm2) {
+		if (!isRfc4648Base64(base64Data)) return null;
 		const sequence = encodeITerm2(base64Data, {
 			width: fit.columns,
 			height: "auto",
@@ -896,13 +920,8 @@ export function parseITerm2CapabilityReply(input: Uint8Array | string): Iterm2Ca
 	return complete ? "missing-f" : undefined;
 }
 
-const ITERM2_BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u;
 const ITERM2_MAX_CAPABILITY_BYTES = 4096;
 
-function assertIterm2Base64(value: string): void {
-	if (value.length % 4 !== 0 || !ITERM2_BASE64.test(value)) throw new Error("Invalid RFC 4648 base64");
-}
-
 export function encodeITerm2Multipart(
 	base64Data: string,
 	options: { width?: number | string; height?: number | string } = {},

package/src/tui.ts

@@ -4,7 +4,14 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { performance } from "node:perf_hooks";
-import { $flag, $pickflag, getDebugLogPath, logger, onDefaultTabWidthChange } from "@gajae-code/utils";
+import {
+	$flag,
+	$pickflag,
+	getDebugLogPath,
+	logger,
+	onDefaultTabWidthChange,
+	redactCrashSecrets,
+} from "@gajae-code/utils";
 import { getKeybindings } from "./keybindings";
 import { isKeyRelease } from "./keys";
 import { renderMetrics } from "./metrics";
@@ -999,6 +1006,23 @@ function createPreparationCancellation(entry: RenderPreparation): () => void {
 
 function cancelNoPreparation(): void {}
 
+function filesystemErrorCode(error: unknown): string | undefined {
+	if (error === null || typeof error !== "object" || !("code" in error)) return undefined;
+	return typeof error.code === "string" ? error.code : undefined;
+}
+
+// JSON.stringify writes ESC as "\\u001b", and a CSI final is a letter, so a
+// following "Bearer" has no word boundary. Split that join, scrub, then restore.
+function redactTuiRenderDump(debugData: string): string {
+	const separateCsiFinal = (match: string) => `${match}\u0000`;
+	const separated = debugData
+		.replace(/\u001b\[[0-9;?]*[A-Za-z]/g, separateCsiFinal)
+		.replace(/\\u001[bB]\[[0-9;?]*[A-Za-z]/g, separateCsiFinal);
+	return redactCrashSecrets(separated)
+		.replace(/\u001b\[[0-9;?]*[A-Za-z]\u0000/g, match => match.slice(0, -1))
+		.replace(/\\u001[bB]\[[0-9;?]*[A-Za-z]\u0000/g, match => match.slice(0, -1));
+}
+
 /**
  * TUI - Main class for managing terminal UI with differential rendering
  */
@@ -1274,6 +1298,38 @@ export class TUI extends Container {
 		fs.appendFileSync(getDebugLogPath(), message);
 	}
 
+	// Sibling of the debug log. Create the parent only when it is missing.
+	// The dump file is opened exclusive and no-follow, then written through that fd.
+	#writeRenderDebugDump(debugData: string): void {
+		const debugDir = path.dirname(getDebugLogPath());
+		if (!fs.existsSync(debugDir)) {
+			fs.mkdirSync(debugDir, { recursive: true, mode: 0o700 });
+			fs.chmodSync(debugDir, 0o700);
+		}
+		// stat follows a symlink to the real agent directory; a directory we do
+		// not own is not a place for a session frame.
+		const dirStat = fs.statSync(debugDir);
+		const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+		if (!dirStat.isDirectory() || (uid !== undefined && dirStat.uid !== uid)) return;
+
+		const debugPath = path.join(debugDir, `render-${Date.now()}-${Math.random().toString(36).slice(2)}.log`);
+		const flags = fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW ?? 0);
+		let fd: number;
+		try {
+			fd = fs.openSync(debugPath, flags, 0o600);
+		} catch (error) {
+			const code = filesystemErrorCode(error);
+			if (code === "EEXIST" || code === "ELOOP") return;
+			throw error;
+		}
+		try {
+			fs.writeFileSync(fd, redactTuiRenderDump(debugData));
+			fs.fchmodSync(fd, 0o600);
+		} finally {
+			fs.closeSync(fd);
+		}
+	}
+
 	#visibleWidthForDifferentialGuard(line: string): number {
 		if (line.length === 0) return 0;
 		const cached = this.#lineEmitWidthCache.get(line);
@@ -6360,9 +6416,6 @@ export class TUI extends Container {
 		buffer = this.#frameSynchronizedOutput(buffer);
 
 		if ($pickflag("GJC_TUI_DEBUG", "PI_TUI_DEBUG")) {
-			const debugDir = "/tmp/tui";
-			fs.mkdirSync(debugDir, { recursive: true });
-			const debugPath = path.join(debugDir, `render-${Date.now()}-${Math.random().toString(36).slice(2)}.log`);
 			const debugData = [
 				`firstChanged: ${firstChanged}`,
 				`viewportTop: ${viewportTop}`,
@@ -6386,7 +6439,7 @@ export class TUI extends Container {
 				"=== buffer ===",
 				JSON.stringify(buffer),
 			].join("\n");
-			fs.writeFileSync(debugPath, debugData);
+			this.#writeRenderDebugDump(debugData);
 		}
 
 		// Write entire buffer at once. Once those bytes are accepted, the painted