hdoc-tools 0.60.1 → 0.62.0

package/hdoc-content-routes.js

@@ -33,6 +33,34 @@ function escape_html(str) {
 		.replace(/>/g, ">");
 }
 
+// Resolve a request URL path against a root directory, refusing anything that
+// escapes the root (path traversal via ../, encoded %2e%2e%2f, backslashes on
+// Windows, or NUL bytes). Returns the absolute resolved path, or null when the
+// URL is malformed or lands outside the root. Both `hdoc serve` (which binds
+// 0.0.0.0 and is LAN-reachable) and `hdoc edit` route raw request URLs through
+// this before touching the filesystem.
+function resolve_within_root(root, url_path) {
+	let decoded;
+	try {
+		decoded = decodeURIComponent(url_path);
+	} catch {
+		return null; // malformed percent-encoding
+	}
+	// Drop any query string and reject NUL bytes outright
+	decoded = decoded.split("?")[0];
+	if (decoded.includes("\0")) return null;
+	const resolved_root = path.resolve(root);
+	const resolved = path.resolve(resolved_root, `.${path.sep}${decoded.replace(/^[/\\]+/, "")}`);
+	if (
+		resolved !== resolved_root &&
+		!resolved.startsWith(resolved_root + path.sep)
+	) {
+		return null;
+	}
+	return resolved;
+}
+exports.resolve_within_root = resolve_within_root;
+
 // Recursively walk <source_path>/<docId>/_inline building the nav fragment
 // consumed by the viewer's nav-section-component. Subfolders become
 // expandable container nodes (items, no link); files become leaf links.
@@ -94,6 +122,30 @@ exports.create_content_handler = (ctx) => {
 	// process_includes resolves include paths relative to the source root.
 	const global_source_path = source_path;
 
+	// Configs are re-read from disk per request so `hdoc serve` / `hdoc edit`
+	// pick up edits to hdocbook.json / hdocbook-project.json without a restart.
+	// Falls back to the startup copy when a mid-edit save is momentarily
+	// invalid JSON.
+	function load_json(file_path, fallback) {
+		try {
+			return JSON.parse(fs.readFileSync(file_path, "utf8"));
+		} catch {
+			return fallback;
+		}
+	}
+	function get_project_config() {
+		return load_json(
+			path.join(source_path, "hdocbook-project.json"),
+			hdocbook_project,
+		);
+	}
+	function get_book_config() {
+		return load_json(
+			path.join(source_path, docId, "hdocbook.json"),
+			hdocbook_config,
+		);
+	}
+
 	// Render markdown SOURCE to HTML through the same pipeline as published output:
 	// expand_variables -> process_includes -> markdown-it (+ mermaid, tips, frontmatter).
 	//
@@ -236,45 +288,50 @@ exports.create_content_handler = (ctx) => {
 	// we will transform to HTML and return that
 	//
 	// Anything else in this handler will return a 404 error
-	function handle_books_request(req, res) {
-		let url = req.url.replace("/_books/", "/");
-
-		console.log("URL Requested:", url);
-
-		// Process redirect
-		if (
-			hdocbook_project.redirects &&
-			Array.isArray(hdocbook_project.redirects) &&
-			hdocbook_project.redirects.length > 0
-		) {
-			const source_url = url.indexOf("/") === 0 ? url : `/${url}`;
-			for (const redir of hdocbook_project.redirects) {
-				redir.url =
-					redir.url.indexOf("/") === 0 ? redir.url : `/${redir.url}`;
-				if (
-					redir.url === source_url &&
-					redir.location &&
-					redir.location !== ""
-				) {
-					url = `${redir.location}`;
-					console.log(`Redirecting to ${url}`);
+	async function handle_books_request(req, res) {
+		try {
+			let url = req.url.replace("/_books/", "/");
+
+			console.log("URL Requested:", url);
+
+			// Process redirect (config read fresh so redirect edits apply live)
+			const project_config = get_project_config();
+			if (
+				project_config.redirects &&
+				Array.isArray(project_config.redirects) &&
+				project_config.redirects.length > 0
+			) {
+				const source_url = url.indexOf("/") === 0 ? url : `/${url}`;
+				for (const redir of project_config.redirects) {
+					redir.url =
+						redir.url.indexOf("/") === 0 ? redir.url : `/${redir.url}`;
+					if (
+						redir.url === source_url &&
+						redir.location &&
+						redir.location !== ""
+					) {
+						url = `${redir.location}`;
+						console.log(`Redirecting to ${url}`);
+					}
 				}
 			}
-		}
 
-		const file_path = path.join(source_path, url);
-
-		if (path.extname(file_path) === ".html") {
-			// 1a. check for html files, and send/transform as required
-			if (fs.existsSync(file_path)) {
-				// HTML file exists on disk, just return it verbatim
-				res.setHeader("Content-Type", "text/html");
-				send_file(req, res, file_path);
-				return true;
+			const file_path = resolve_within_root(source_path, url);
+			if (file_path === null) {
+				send_content_resource_404(req, res);
+				return;
 			}
-			if (fs.existsSync(file_path.replace(".html", ".md"))) {
+
+			if (path.extname(file_path) === ".html") {
+				// 1a. check for html files, and send/transform as required
+				if (fs.existsSync(file_path)) {
+					// HTML file exists on disk, just return it verbatim
+					res.setHeader("Content-Type", "text/html");
+					send_file(req, res, file_path);
+					return;
+				}
 				if (
-					transform_markdown_and_send_html(
+					await transform_markdown_and_send_html(
 						req,
 						res,
 						file_path.replace(".html", ".md"),
@@ -282,22 +339,19 @@ exports.create_content_handler = (ctx) => {
 				) {
 					return;
 				}
-			}
-		} else if (path.extname(file_path) === ".md") {
-			// If the markdown file exists, just send to caller as is
-			if (fs.existsSync(file_path)) {
-				send_content_file(req, res, file_path);
-				return true;
-			}
-		} else if (path.extname(file_path).length === 0) {
-			// 2. If we request a file, without any file extension
-			if (fs.existsSync(`${file_path}.md`)) {
-				if (transform_markdown_and_send_html(req, res, `${file_path}.md`)) {
+			} else if (path.extname(file_path) === ".md") {
+				// If the markdown file exists, just send to caller as is
+				if (fs.existsSync(file_path)) {
+					send_content_file(req, res, file_path);
+					return;
+				}
+			} else if (path.extname(file_path).length === 0) {
+				// 2. If we request a file, without any file extension
+				if (await transform_markdown_and_send_html(req, res, `${file_path}.md`)) {
 					return;
 				}
-			} else if (fs.existsSync(path.join(`${file_path}index.md`))) {
 				if (
-					transform_markdown_and_send_html(
+					await transform_markdown_and_send_html(
 						req,
 						res,
 						path.join(file_path, "index.md"),
@@ -305,55 +359,61 @@ exports.create_content_handler = (ctx) => {
 				) {
 					return;
 				}
-			} else if (fs.existsSync(path.join(`${file_path}index.html`))) {
-				res.setHeader("Content-Type", "text/html");
-				send_content_file(req, res, path.join(`${file_path}index.html`));
-				return;
-			} else if (fs.existsSync(`${file_path}/index.md`)) {
+				if (fs.existsSync(path.join(`${file_path}index.html`))) {
+					res.setHeader("Content-Type", "text/html");
+					send_content_file(req, res, path.join(`${file_path}index.html`));
+					return;
+				}
+				if (fs.existsSync(path.join(`${file_path}/index.html`))) {
+					res.setHeader("Content-Type", "text/html");
+					send_content_file(req, res, path.join(`${file_path}/index.html`));
+					return;
+				}
+				if (fs.existsSync(path.join(`${file_path}.html`))) {
+					res.setHeader("Content-Type", "text/html");
+					send_content_file(req, res, path.join(`${file_path}.html`));
+					return;
+				}
+				if (fs.existsSync(path.join(`${file_path}.htm`))) {
+					res.setHeader("Content-Type", "text/html");
+					send_content_file(req, res, path.join(`${file_path}.htm`));
+					return;
+				}
+			} else if (fs.existsSync(file_path)) {
 				if (
-					transform_markdown_and_send_html(req, res, `${file_path}/index.md`)
+					file_path.endsWith("hdocbook.json") ||
+					file_path.endsWith("hdocbook_project.json")
 				) {
-					return;
+					try {
+						// Read & parse file
+						JSON.parse(fs.readFileSync(file_path));
+					} catch (e) {
+						console.error(`Error parsing hdocbook.json: ${e}`);
+					}
 				}
-			} else if (fs.existsSync(path.join(`${file_path}/index.html`))) {
-				res.setHeader("Content-Type", "text/html");
-				send_content_file(req, res, path.join(`${file_path}/index.html`));
-				return;
-			} else if (fs.existsSync(path.join(`${file_path}.html`))) {
-				res.setHeader("Content-Type", "text/html");
-				send_content_file(req, res, path.join(`${file_path}.html`));
-				return;
-			} else if (fs.existsSync(path.join(`${file_path}.htm`))) {
-				res.setHeader("Content-Type", "text/html");
-				send_content_file(req, res, path.join(`${file_path}.htm`));
+				send_file(req, res, file_path);
 				return;
 			}
-		} else if (fs.existsSync(file_path)) {
-			if (
-				file_path.endsWith("hdocbook.json") ||
-				file_path.endsWith("hdocbook_project.json")
-			) {
-				try {
-					// Read & parse file
-					JSON.parse(fs.readFileSync(file_path));
-				} catch (e) {
-					console.error(`Error parsing hdocbook.json: ${e}`);
-				}
+
+			// Return a 404 error here
+			send_content_resource_404(req, res);
+		} catch (e) {
+			// A markdown render failure (bad include, plugin throw, etc.) lands
+			// here rather than as an unhandled promise rejection.
+			console.error(`Error handling content request ${req.url}:`, e);
+			if (!res.headersSent) {
+				res.status(500).send("Error rendering content");
 			}
-			send_file(req, res, file_path);
-			return;
 		}
-
-		// Return a 404 error here
-		send_content_resource_404(req, res);
 	}
 
 	function handle_library_request(req, res) {
+		const book_config = get_book_config();
 		const library = {
 			books: [
 				{
-					docId: hdocbook_config.docId,
-					title: hdocbook_config.title,
+					docId: book_config.docId,
+					title: book_config.title,
 					nav_inline: nav_inline,
 				},
 			],

package/hdoc-create.js

@@ -1,108 +1,110 @@
-(() => {
-	const fs = require("node:fs");
-	const path = require("node:path");
-	const hdoc = require(path.join(__dirname, "hdoc-module.js"));
-
-	let doc_id;
-	let file_count = 0;
-	let folder_count = 0;
-
-	const processed_links = {};
-
-	exports.run = async (source_path) => {
-		console.log("Hornbill HDocBook Create", "\n");
-		console.log("Path:", source_path, "\n");
-
-		// Load the hdocbook-project.json file to get the docId
-		// use the docId to get the book config
-		const hdocbook_project_config_path = path.join(
-			source_path,
-			"hdocbook-project.json",
-		);
-		let hdocbook_project = {};
-		try {
-			hdocbook_project = require(hdocbook_project_config_path);
-		} catch (e) {
-			console.error(`File not found: ${hdocbook_project_config_path}\n`);
-			console.error(
-				"hdoc create needs to be run in the root of a HDoc Book.\n",
-			);
-			process.exit(1);
-		}
-		doc_id = hdocbook_project.docId;
-
-		const book_path = path.join(source_path, doc_id);
-		const hdocbook_path = path.join(book_path, "hdocbook.json");
-
-		let hdocbook = {};
-		try {
-			hdocbook = require(hdocbook_path);
-		} catch (e) {
-			console.error(`File not found: ${hdocbook_path}\n`);
-			console.error(
-				"hdoc create needs to be run in the root of a HDoc Book.\n",
-			);
-			process.exit(1);
-		}
-
-		// Get paths from breadcrumb builder
-		const nav_paths = hdoc.build_breadcrumbs(hdocbook.navigation.items);
-		for (const key in nav_paths) {
-			if (Object.hasOwn(nav_paths, key)) {
-				for (const navkey in nav_paths[key]) {
-					if (Object.hasOwn(nav_paths[key], navkey)) {
-						for (let i = 0; i < nav_paths[key][navkey].length; i++) {
-							if (
-								nav_paths[key][navkey][i].link &&
-								!processed_links[nav_paths[key][navkey][i].link]
-							) {
-								nav_paths[key][navkey][i].path = path.join(
-									source_path,
-									nav_paths[key][navkey][i].link,
-								);
-								await add_doc(nav_paths[key][navkey][i]);
-							}
-						}
-					}
-				}
-			}
-		}
-		console.log("\n-----------------------");
-		console.log(" Docs Creation Summary");
-		console.log("-----------------------\n");
-		console.log(`  Files Created: ${file_count}`);
-		console.log(`Folders Created: ${folder_count}\n`);
-	};
-
-	const add_doc = async (doc_info) => {
-		// Does folder exist? Create if not
-		const folder = path.dirname(doc_info.path);
-		if (!fs.existsSync(folder)) {
-			try {
-				fs.mkdirSync(folder, { recursive: true });
-				console.log("Folder created:", folder);
-				folder_count++;
-			} catch (e) {
-				console.error("\nError creating folder", folder, ":", e);
-				return;
-			}
-		}
-
-		// Does file exist? Create if not
-		if (
-			!fs.existsSync(`${doc_info.path}.md`) &&
-			!fs.existsSync(`${doc_info.path}.htm`) &&
-			!fs.existsSync(`${doc_info.path}.html`)
-		) {
-			try {
-				const file_path = `${doc_info.path}.md`;
-				fs.writeFileSync(file_path, `# ${doc_info.text}\n`);
-				console.log("  File created:", file_path);
-				processed_links[doc_info.link] = true;
-				file_count++;
-			} catch (e) {
-				console.error("\nError creating file", doc_info.path, ":", e);
-			}
-		}
-	};
-})();
+(() => {
+	const fs = require("node:fs");
+	const path = require("node:path");
+	const hdoc = require(path.join(__dirname, "hdoc-module.js"));
+
+	let doc_id;
+	let file_count = 0;
+	let folder_count = 0;
+
+	const processed_links = {};
+
+	exports.run = async (source_path) => {
+		console.log("Hornbill HDocBook Create", "\n");
+		console.log("Path:", source_path, "\n");
+
+		// Load the hdocbook-project.json file to get the docId
+		// use the docId to get the book config
+		const hdocbook_project_config_path = path.join(
+			source_path,
+			"hdocbook-project.json",
+		);
+		let hdocbook_project = {};
+		try {
+			hdocbook_project = JSON.parse(
+				fs.readFileSync(hdocbook_project_config_path, "utf8"),
+			);
+		} catch (e) {
+			console.error(`File not found: ${hdocbook_project_config_path}\n`);
+			console.error(
+				"hdoc create needs to be run in the root of a HDoc Book.\n",
+			);
+			process.exit(1);
+		}
+		doc_id = hdocbook_project.docId;
+
+		const book_path = path.join(source_path, doc_id);
+		const hdocbook_path = path.join(book_path, "hdocbook.json");
+
+		let hdocbook = {};
+		try {
+			hdocbook = JSON.parse(fs.readFileSync(hdocbook_path, "utf8"));
+		} catch (e) {
+			console.error(`File not found: ${hdocbook_path}\n`);
+			console.error(
+				"hdoc create needs to be run in the root of a HDoc Book.\n",
+			);
+			process.exit(1);
+		}
+
+		// Get paths from breadcrumb builder
+		const nav_paths = hdoc.build_breadcrumbs(hdocbook.navigation.items);
+		for (const key in nav_paths) {
+			if (Object.hasOwn(nav_paths, key)) {
+				for (const navkey in nav_paths[key]) {
+					if (Object.hasOwn(nav_paths[key], navkey)) {
+						for (let i = 0; i < nav_paths[key][navkey].length; i++) {
+							if (
+								nav_paths[key][navkey][i].link &&
+								!processed_links[nav_paths[key][navkey][i].link]
+							) {
+								nav_paths[key][navkey][i].path = path.join(
+									source_path,
+									nav_paths[key][navkey][i].link,
+								);
+								await add_doc(nav_paths[key][navkey][i]);
+							}
+						}
+					}
+				}
+			}
+		}
+		console.log("\n-----------------------");
+		console.log(" Docs Creation Summary");
+		console.log("-----------------------\n");
+		console.log(`  Files Created: ${file_count}`);
+		console.log(`Folders Created: ${folder_count}\n`);
+	};
+
+	const add_doc = async (doc_info) => {
+		// Does folder exist? Create if not
+		const folder = path.dirname(doc_info.path);
+		if (!fs.existsSync(folder)) {
+			try {
+				fs.mkdirSync(folder, { recursive: true });
+				console.log("Folder created:", folder);
+				folder_count++;
+			} catch (e) {
+				console.error("\nError creating folder", folder, ":", e);
+				return;
+			}
+		}
+
+		// Does file exist? Create if not
+		if (
+			!fs.existsSync(`${doc_info.path}.md`) &&
+			!fs.existsSync(`${doc_info.path}.htm`) &&
+			!fs.existsSync(`${doc_info.path}.html`)
+		) {
+			try {
+				const file_path = `${doc_info.path}.md`;
+				fs.writeFileSync(file_path, `# ${doc_info.text}\n`);
+				console.log("  File created:", file_path);
+				processed_links[doc_info.link] = true;
+				file_count++;
+			} catch (e) {
+				console.error("\nError creating file", doc_info.path, ":", e);
+			}
+		}
+	};
+})();