@kubb/studio 5.11.1 → 5.11.2

package/README.md

@@ -85,6 +85,10 @@ running in a developer's project and a container running a fixed plugin set.
 the agent is a sandbox and carries its slug and Studio's version. From then on the agent pings every
 30 seconds, and Studio schedules one job at a time on the socket.
 
+With `allowRead`, the connect payload also includes a kept copy of the current `output.path` files.
+Studio can browse these files through `readFiles` before running a generation. Sandbox agents have
+no disk output, and output paths outside the project root are excluded.
+
 Studio ends a socket on purpose with one of these close codes:
 
 | Code   | Meaning                                       | `connectAgent`                        |
@@ -108,7 +112,7 @@ Every permission is off by default, and each covers one trust boundary:
 | `allowWrite`      | Generated files are written to disk. Off means they exist only in memory and stream to Studio. |
 | `allowExec`       | The formatter, the linter, and `output.postGenerate` run as child processes.                   |
 | `allowConfigEdit` | Studio may change plugin options in `kubb.config.ts`.                                          |
-| `allowRead`       | Studio may read back the files a generation produced.                                          |
+| `allowRead`       | Studio may read existing output files and the files a generation produced.                     |
 | `allowReadAst`    | Studio may read back the parsed spec (the Kubb AST).                                           |
 
 A sandbox never writes or edits config, and always allows reads.

package/dist/index.cjs

@@ -140,6 +140,27 @@ async function read(path) {
 	if (runtime.isBun) return Bun.file(path).text();
 	return (0, node_fs_promises.readFile)(path, { encoding: "utf8" });
 }
+/**
+* Resolves to `true` when `path` is `parent` itself or nested inside it. Both sides are resolved
+* to absolute paths first, so relative and `..`-containing inputs compare correctly.
+*
+* Guards a destructive or an out-of-tree operation: before wiping an output directory, check that
+* it does not contain the project root, and before loading a path a caller supplied, check that it
+* did not escape the directory it is allowed to read from.
+*
+* @example
+* isPathInside('./src/gen', '.')   // true  — nested inside the root
+* isPathInside('.', '.')           // true  — the same directory counts as inside
+* isPathInside('.', './src/gen')   // false — the root is not inside its own output
+* isPathInside('../other', '.')    // false — escapes the root
+*/
+function isPathInside(path, parent) {
+	const resolvedPath = (0, node_path.resolve)(path);
+	const resolvedParent = (0, node_path.resolve)(parent);
+	if (resolvedPath === resolvedParent) return true;
+	const rel = (0, node_path.relative)(resolvedParent, resolvedPath);
+	return rel !== "" && !rel.startsWith("..") && !(0, node_path.isAbsolute)(rel);
+}
 //#endregion
 //#region ../../internals/utils/src/promise.ts
 /**
@@ -178,7 +199,7 @@ function getElapsedMs(hrStart) {
 }
 //#endregion
 //#region package.json
-var version = "5.11.1";
+var version = "5.11.2";
 //#endregion
 //#region src/resolveConfig.ts
 /**
@@ -483,6 +504,33 @@ async function mergePlugins({ diskPlugins, studioPlugins, extensions = /* @__PUR
 	})];
 }
 /**
+* Throws `KUBB_PATH_TRAVERSAL` when a plugin would write outside the config's output folder to a path
+* the disk config does not set. Studio can change `output.path`, also inside `override`, and add
+* plugins, so without this check any member of the Studio organization could write any file the agent
+* can reach, including `node_modules` code the next run imports. A path from the config file stays
+* allowed, since a monorepo may write outside its root.
+*/
+function assertOutputPaths({ plugins, diskPlugins, root, outputPath }) {
+	const base = node_path.default.resolve(root, outputPath);
+	const targetsOf = (plugin) => {
+		const { output, override } = plugin.options ?? {};
+		return [output, ...Array.isArray(override) ? override.map((entry) => entry?.options?.output) : []].flatMap((entry) => typeof entry?.path === "string" ? [node_path.default.resolve(base, entry.path)] : []);
+	};
+	const diskTargets = new Set(diskPlugins.flatMap(targetsOf));
+	for (const plugin of plugins) {
+		const target = targetsOf(plugin).find((resolved) => !diskTargets.has(resolved) && !isPathInside(resolved, base));
+		if (!target) continue;
+		throw new _kubb_core.Diagnostics.Error({
+			code: _kubb_core.Diagnostics.code.pathTraversal,
+			severity: "error",
+			message: `Plugin "${plugin.name}" would write to "${target}", outside the output folder "${base}". Studio can only set an output path inside it.`,
+			help: "Choose an output path inside the output folder, or set this path in the config file.",
+			location: { kind: "config" },
+			plugin: plugin.name
+		});
+	}
+}
+/**
 * Re-invokes the factory behind a disk adapter or parser with Studio's options merged over its own.
 * An instance carries live functions (`parse`, `print`, ...) that cannot survive JSON, so Studio's
 * options are a patch, not a replacement, and the factory is found from the disk instance itself: the
@@ -1448,7 +1496,7 @@ function createGenerationStore({ storage, maxCount, maxMb, ttlMs, now = Date.now
 	/**
 	* Copies `files` into the store as one set of `jobId`. Above `maxSetMb` only the hashes are kept.
 	*/
-	async function keep({ jobId, source, files, maxSetMb }) {
+	async function keep({ jobId, source, files, maxSetMb, normalize = source === require_protocol.FileSource.OUTPUT }) {
 		const maxSetBytes = maxSetMb * MB;
 		const hashes = {};
 		let bytes = 0;
@@ -1459,8 +1507,8 @@ function createGenerationStore({ storage, maxCount, maxMb, ttlMs, now = Date.now
 				if (path.split("/").includes("..")) return;
 				const content = await files.storage.readItem((0, node_path.resolve)(files.root, path));
 				if (content === null) return;
-				if (source === require_protocol.FileSource.OUTPUT && !content.trim()) return;
-				hashes[path] = hashOf(source === require_protocol.FileSource.OUTPUT ? `${content.trim()}\n` : content);
+				if (normalize && !content.trim()) return;
+				hashes[path] = hashOf(normalize ? `${content.trim()}\n` : content);
 				bytes += Buffer.byteLength(content);
 				if (bytes <= maxSetBytes) await storage.writeItem(`${dirOf(jobId)}${source}/${path}`, content);
 			}
@@ -1924,8 +1972,12 @@ var Agent = class extends capnweb.RpcTarget {
 			this.#readConfigFileView(source),
 			this.#installedExtensions(source)
 		]);
+		const output = await this.#readDiskOutput(config).catch(async (error) => {
+			await this.#warn({ message: `Could not read the output directory: ${getErrorMessage(error)}` });
+		});
 		this.#session.connected.resolve(info);
 		return {
+			output,
 			versions: {
 				kubb: version,
 				agent: version$1
@@ -1962,6 +2014,32 @@ var Agent = class extends capnweb.RpcTarget {
 			permissions: this.#permissions
 		};
 	}
+	async #readDiskOutput(config) {
+		if (this.#sandbox || !this.#permissions.allowRead || this.#session.active) return void 0;
+		const files = await listDisk({
+			root: this.#options.root,
+			outputPath: config.output.path,
+			maxFiles: DISK_SNAPSHOT_MAX_FILES
+		});
+		if (!files) return void 0;
+		const jobId = (0, node_crypto.randomUUID)();
+		const output = await this.#generations.keep({
+			jobId,
+			source: require_protocol.FileSource.OUTPUT,
+			files,
+			maxSetMb: this.#limits.maxSnapshotMb,
+			normalize: false
+		});
+		await this.#generations.add({
+			jobId,
+			output
+		});
+		return {
+			jobId,
+			files: output.paths,
+			hashes: output.hashes
+		};
+	}
 	startGeneration(input) {
 		const stream = createGenerationStream(this.#options.hooks, input.jobId);
 		const controller = new AbortController();
@@ -2014,6 +2092,7 @@ var Agent = class extends capnweb.RpcTarget {
 			settled.resolve();
 		}
 	}
+	/** Merges Studio's config over the disk config, refuses output paths outside the output folder, then generates in `root`. */
 	async #generate({ input, root, signal }) {
 		const { jobId, config: patch } = input;
 		const studioInput = this.#sandbox ? patch?.input : void 0;
@@ -2024,6 +2103,14 @@ var Agent = class extends capnweb.RpcTarget {
 				diskPlugins: config.plugins,
 				studioPlugins: patch?.plugins,
 				extensions
+			}).then((merged) => {
+				assertOutputPaths({
+					plugins: merged ?? [],
+					diskPlugins: config.plugins,
+					root,
+					outputPath: config.output.path
+				});
+				return merged;
 			}),
 			mergeAdapter(config.adapter, patch?.adapter, extensions),
 			mergeParsers({