mdbrowse-cli 0.2.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saleeh K
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -7,8 +7,7 @@
 
 Zero-install CLI that spins up a local web UI with a file tree, rendered markdown, live reload, and optional Cloudflare Tunnel for remote access.
 
-<!-- TODO: Add screenshot here -->
-<!-- ![mdbrowse screenshot](docs/screenshot.png) -->
+![mdbrowse-cli demo](docs/screenshots/demo.gif)
 
 ## Quick start
 
@@ -22,6 +21,71 @@ Opens in your browser automatically. On SSH/headless servers, grab the printed U
 
 ## Features
 
+<table>
+<tr>
+<td width="50%">
+
+**File tree + markdown rendering**
+
+Browse files in the sidebar, view beautifully rendered markdown with GFM tables, task lists, and more.
+
+![Light theme](docs/screenshots/hero-light.png)
+
+</td>
+<td width="50%">
+
+**Dark / light theme**
+
+Auto-detects system preference. Toggle with one click.
+
+![Dark theme](docs/screenshots/hero-dark.png)
+
+</td>
+</tr>
+<tr>
+<td width="50%">
+
+**Syntax highlighting**
+
+VS Code-quality code blocks via Shiki — JavaScript, Python, Rust, and 100+ languages.
+
+![Code highlighting](docs/screenshots/code-highlight.png)
+
+</td>
+<td width="50%">
+
+**Search**
+
+Filename + content search with Ctrl+K. Results highlighted in context.
+
+![Search](docs/screenshots/search.png)
+
+</td>
+</tr>
+<tr>
+<td width="50%">
+
+**Mermaid diagrams + math**
+
+Flowcharts, sequence diagrams, and LaTeX math rendered inline.
+
+![Mermaid diagrams](docs/screenshots/mermaid.png)
+
+</td>
+<td width="50%">
+
+**Edit mode**
+
+Toggle to edit any file, Ctrl+S to save, with tab indentation support.
+
+![Edit mode](docs/screenshots/edit-mode.png)
+
+</td>
+</tr>
+</table>
+
+**Full feature list:**
+
 - 📁 **File tree sidebar** — browse all files in the directory
 - 📝 **Markdown rendering** — GFM tables, task lists, strikethrough, and more
 - 🎨 **Syntax highlighting** — VS Code-quality code blocks via Shiki
@@ -41,12 +105,48 @@ Opens in your browser automatically. On SSH/headless servers, grab the printed U
 |------|---------|-------------|
 | `[directory]` | `.` | Directory to serve |
 | `-p, --port <number>` | `3000` | Port to listen on |
-| `--host <address>` | `localhost` | Host to bind to (use `0.0.0.0` for all interfaces) |
+| `--host <address>` | `0.0.0.0` | Host to bind to |
 | `--tunnel` | off | Expose via Cloudflare Tunnel (requires `cloudflared`) |
 | `--auth <user:pass>` | off | Require basic HTTP authentication |
 | `--read-only` | off | Disable file editing |
 | `--no-ignore` | off | Show all files (don't respect `.gitignore`) |
 
+If the port is in use, mdbrowse-cli automatically tries the next available port.
+
+## Configuration
+
+mdbrowse-cli supports a config file and environment variables so you don't have to pass flags every time.
+
+**Priority chain:** `CLI args > Environment variables > .mdbrowse.json > Built-in defaults`
+
+### Config file (`.mdbrowse.json`)
+
+Place a `.mdbrowse.json` in the directory you're serving:
+
+```json
+{
+  "port": 4000,
+  "host": "0.0.0.0",
+  "tunnel": false,
+  "auth": "admin:secret",
+  "readOnly": true,
+  "noIgnore": false
+}
+```
+
+### Environment variables
+
+| Variable | Maps to | Example |
+|----------|---------|---------|
+| `MDBROWSE_PORT` | `--port` | `MDBROWSE_PORT=8080` |
+| `MDBROWSE_HOST` | `--host` | `MDBROWSE_HOST=localhost` |
+| `MDBROWSE_TUNNEL` | `--tunnel` | `MDBROWSE_TUNNEL=1` |
+| `MDBROWSE_AUTH` | `--auth` | `MDBROWSE_AUTH=admin:secret` |
+| `MDBROWSE_READ_ONLY` | `--read-only` | `MDBROWSE_READ_ONLY=1` |
+| `MDBROWSE_NO_IGNORE` | `--no-ignore` | `MDBROWSE_NO_IGNORE=1` |
+
+See [docs/configuration.md](docs/configuration.md) for full details, examples, and shell profile setup.
+
 ## Use cases
 
 **Remote / headless servers** — Working on a cloud dev box or VPS? Run `npx mdbrowse-cli . --tunnel` to get a public URL and view rendered markdown from any browser.
@@ -55,6 +155,14 @@ Opens in your browser automatically. On SSH/headless servers, grab the printed U
 
 **Documentation browsing** — Point it at your `docs/` folder for a quick local docs site with search, live reload, and edit support.
 
+## Try the demo
+
+```bash
+git clone https://github.com/saleehk/mdbrowse.git
+cd mdbrowse && npm install
+npx mdbrowse-cli docs/
+```
+
 ## Tech stack
 
 [Hono](https://hono.dev/) server, [unified](https://unifiedjs.com/)/remark markdown pipeline, [Shiki](https://shiki.style/) syntax highlighting, [KaTeX](https://katex.org/) math, [Mermaid](https://mermaid.js.org/) diagrams, [chokidar](https://github.com/paulmillr/chokidar) file watching, vanilla JS frontend — no build step.

package/bin/mdbrowse-cli.js

@@ -1,17 +1,51 @@
 #!/usr/bin/env node
 
+import fs from 'fs';
+import path from 'path';
 import { Command } from 'commander';
 import { startServer } from '../src/server.js';
 
+/**
+ * Load .mdbrowse.json from the target directory.
+ * Returns an empty object if not found or invalid.
+ */
+function loadConfigFile(directory) {
+  const configPath = path.resolve(directory, '.mdbrowse.json');
+  try {
+    if (fs.existsSync(configPath)) {
+      const raw = fs.readFileSync(configPath, 'utf-8');
+      const config = JSON.parse(raw);
+      return config;
+    }
+  } catch (err) {
+    console.warn(`  Warning: Could not parse .mdbrowse.json — ${err.message}`);
+  }
+  return {};
+}
+
+// Parse directory arg early so we can load config file before commander defaults
+const dirArg = process.argv.find((a, i) => i >= 2 && !a.startsWith('-')) || '.';
+const fileConfig = loadConfigFile(dirArg);
+
+// Priority: CLI args > env vars > .mdbrowse.json > built-in defaults
+const defaults = {
+  port: process.env.MDBROWSE_PORT || fileConfig.port?.toString() || '3000',
+  host: process.env.MDBROWSE_HOST || fileConfig.host || '0.0.0.0',
+  tunnel: process.env.MDBROWSE_TUNNEL === '1' || fileConfig.tunnel === true,
+  auth: process.env.MDBROWSE_AUTH || fileConfig.auth || null,
+  readOnly: process.env.MDBROWSE_READ_ONLY === '1' || fileConfig.readOnly === true,
+  noIgnore: process.env.MDBROWSE_NO_IGNORE === '1' || fileConfig.noIgnore === true,
+};
+
 const program = new Command();
 
 program
   .name('mdbrowse-cli')
   .description('Browse and preview markdown files in any directory')
-  .version('0.1.0')
+  .version('0.2.0')
   .argument('[directory]', 'Directory to serve', '.')
-  .option('-p, --port <number>', 'Port to listen on', '3000')
-  .option('--host <address>', 'Host to bind to', '0.0.0.0')
+  .option('-p, --port <number>', 'Port to listen on', defaults.port)
+  .option('--host <address>', 'Host to bind to', defaults.host)
   .option('--no-ignore', 'Show all files (ignore .gitignore)')
   .option('--auth <credentials>', 'Require basic auth (user:pass)')
   .option('--read-only', 'Disable file editing')
@@ -19,16 +53,18 @@ program
   .action(async (directory, options) => {
     const port = parseInt(options.port, 10);
     const host = options.host;
-    const respectIgnore = options.ignore !== false;
-    const readOnly = !!options.readOnly;
+    const respectIgnore = defaults.noIgnore ? false : options.ignore !== false;
+    const readOnly = options.readOnly || defaults.readOnly;
 
+    // Auth: CLI arg > env var > none
+    const authStr = options.auth || defaults.auth;
     let auth;
-    if (options.auth) {
-      if (!options.auth.includes(':')) {
-        console.error('Error: --auth must be in user:pass format');
+    if (authStr) {
+      if (!authStr.includes(':')) {
+        console.error('Error: --auth (or MDBROWSE_AUTH) must be in user:pass format');
         process.exit(1);
       }
-      const [user, ...rest] = options.auth.split(':');
+      const [user, ...rest] = authStr.split(':');
       auth = { username: user, password: rest.join(':') };
     }
 
@@ -41,6 +77,17 @@ program
       readOnly,
     });
 
+    // Security warnings
+    if ((options.tunnel || defaults.tunnel) && !authStr) {
+      console.warn('\n  ⚠ WARNING: Tunnel is public with no authentication.');
+    }
+    if (authStr && host === '0.0.0.0') {
+      console.warn('\n  ⚠ Warning: Basic auth over HTTP transmits credentials in cleartext.');
+    }
+    if (fileConfig.auth) {
+      console.warn('\n  ⚠ Warning: Auth credentials in .mdbrowse.json — use MDBROWSE_AUTH env var instead.');
+    }
+
     const localUrl = `http://localhost:${actualPort}`;
     console.log(`\n  mdbrowse-cli serving ${directory}`);
     console.log(`  → Local:   ${localUrl}`);
@@ -58,7 +105,7 @@ program
     }
     console.log();
 
-    if (options.tunnel) {
+    if (options.tunnel || defaults.tunnel) {
       const { startTunnel, registerCleanup } = await import('../src/tunnel.js');
       try {
         console.log('  Starting Cloudflare Tunnel...');
@@ -79,14 +126,14 @@ program
     );
 
     if (!isHeadless) {
-      const { exec } = await import('child_process');
+      const { execFile } = await import('child_process');
       const cmd =
         process.platform === 'darwin'
           ? 'open'
           : process.platform === 'win32'
             ? 'start'
             : 'xdg-open';
-      exec(`${cmd} ${localUrl}`);
+      execFile(cmd, [localUrl], () => {});
     }
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdbrowse-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "CLI tool to browse and preview markdown files in any directory",
   "type": "module",
   "bin": {
@@ -31,6 +31,8 @@
     "hono": "^4.7.0",
     "ignore": "^7.0.0",
     "rehype-katex": "^7.0.0",
+    "rehype-parse": "^9.0.1",
+    "rehype-sanitize": "^6.0.0",
     "rehype-stringify": "^10.0.0",
     "remark-gfm": "^4.0.0",
     "remark-html": "^16.0.0",

package/public/app.js

@@ -239,6 +239,7 @@ function initMermaid() {
   mermaid.initialize({
     startOnLoad: false,
     theme: isDark ? 'dark' : 'default',
+    securityLevel: 'strict',
   });
 
   blocks.forEach((block, i) => {

package/src/renderer.js

@@ -4,11 +4,50 @@ import remarkParse from 'remark-parse';
 import remarkGfm from 'remark-gfm';
 import remarkMath from 'remark-math';
 import remarkHtml from 'remark-html';
-import rehypeKatex from 'rehype-katex';
+import rehypeParse from 'rehype-parse';
+import rehypeSanitize, { defaultSchema } from 'rehype-sanitize';
 import rehypeStringify from 'rehype-stringify';
 import matter from 'gray-matter';
 import { createHighlighter } from 'shiki';
 
+// Permissive sanitization schema based on GitHub defaults
+// Allows tables, images, links (http/https only), structural HTML
+// Strips scripts, event handlers, javascript: URLs, iframes, object, embed
+const sanitizeSchema = {
+  ...defaultSchema,
+  tagNames: [
+    ...(defaultSchema.tagNames || []),
+    'div', 'span', 'details', 'summary',
+    'table', 'thead', 'tbody', 'tfoot', 'tr', 'th', 'td',
+    'img', 'a', 'p', 'br', 'hr',
+    'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+    'ul', 'ol', 'li', 'dl', 'dt', 'dd',
+    'pre', 'code', 'blockquote',
+    'strong', 'em', 'b', 'i', 'u', 's', 'del', 'ins',
+    'sup', 'sub', 'mark', 'abbr', 'kbd', 'var', 'samp',
+    'figure', 'figcaption', 'picture', 'source',
+    'input', // for task lists
+  ],
+  attributes: {
+    ...defaultSchema.attributes,
+    '*': ['className', 'id'],
+    a: ['href', 'title', 'target', 'rel'],
+    img: ['src', 'alt', 'title', 'width', 'height', 'loading'],
+    td: ['align', 'valign', 'colSpan', 'rowSpan'],
+    th: ['align', 'valign', 'colSpan', 'rowSpan', 'scope'],
+    input: ['type', 'checked', 'disabled'],
+    code: ['className'],
+    div: ['className'],
+    span: ['className'],
+    source: ['srcSet', 'type', 'media'],
+  },
+  protocols: {
+    href: ['http', 'https', 'mailto'],
+    src: ['http', 'https', '/raw/', 'data'],
+  },
+  strip: ['script', 'style', 'iframe', 'object', 'embed', 'form', 'textarea', 'select', 'button'],
+};
+
 let highlighterPromise = null;
 
 function getHighlighter() {
@@ -59,7 +98,7 @@ export async function renderMarkdown(content, filePath) {
 
   // Build the remark pipeline
   // We use remark-html which outputs an HTML string directly,
-  // then do a second pass for math with rehype
+  // then sanitize the output with rehype-sanitize
   const remarkResult = await unified()
     .use(remarkParse)
     .use(remarkGfm)
@@ -67,7 +106,14 @@ export async function renderMarkdown(content, filePath) {
     .use(remarkHtml, { sanitize: false })
     .process(body);
 
-  let html = String(remarkResult);
+  // Sanitize HTML to prevent XSS from malicious markdown
+  const sanitized = await unified()
+    .use(rehypeParse, { fragment: true })
+    .use(rehypeSanitize, sanitizeSchema)
+    .use(rehypeStringify)
+    .process(String(remarkResult));
+
+  let html = String(sanitized);
 
   // Highlight code blocks in the HTML
   // Match <code class="language-xxx">...</code> blocks

package/src/server.js

@@ -72,6 +72,7 @@ const MIME_TYPES = {
 
 /**
  * Validate that a requested path stays within the root directory.
+ * Resolves symlinks to prevent traversal via symbolic links.
  * Returns the resolved absolute path or null if invalid.
  */
 function safePath(rootDir, requestedPath) {
@@ -79,9 +80,40 @@ function safePath(rootDir, requestedPath) {
   if (!resolved.startsWith(rootDir + path.sep) && resolved !== rootDir) {
     return null;
   }
-  return resolved;
+  try {
+    const real = fs.realpathSync(resolved);
+    const realRoot = fs.realpathSync(rootDir);
+    if (!real.startsWith(realRoot + path.sep) && real !== realRoot) {
+      return null;
+    }
+    return real;
+  } catch {
+    return resolved; // file may not exist yet
+  }
+}
+
+/**
+ * CSRF check: validate Origin/Referer header on state-changing requests.
+ */
+function csrfCheck(c) {
+  const origin = c.req.header('origin');
+  const referer = c.req.header('referer');
+  const source = origin || referer;
+  if (source) {
+    try {
+      const url = new URL(source);
+      if (url.hostname !== 'localhost' && url.hostname !== '127.0.0.1' && !url.hostname.endsWith('.trycloudflare.com')) {
+        return false;
+      }
+    } catch {
+      return false;
+    }
+  }
+  return true;
 }
 
+const MAX_WS_CLIENTS = 100;
+
 export async function startServer({ directory, port, host, respectIgnore, auth, readOnly }) {
   const rootDir = path.resolve(directory);
 
@@ -92,6 +124,25 @@ export async function startServer({ directory, port, host, respectIgnore, auth,
 
   const app = new Hono();
 
+  // Security headers middleware
+  const CSP = [
+    "default-src 'self'",
+    "script-src 'self' https://cdn.jsdelivr.net 'unsafe-inline'",
+    "style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net",
+    "img-src 'self' data: https:",
+    "connect-src 'self' ws: wss:",
+    "frame-src 'none'",
+    "object-src 'none'",
+  ].join('; ');
+
+  app.use('*', async (c, next) => {
+    await next();
+    c.header('X-Content-Type-Options', 'nosniff');
+    c.header('X-Frame-Options', 'DENY');
+    c.header('Referrer-Policy', 'no-referrer');
+    c.header('Content-Security-Policy', CSP);
+  });
+
   if (auth) {
     app.use('*', basicAuth({ username: auth.username, password: auth.password }));
   }
@@ -153,6 +204,11 @@ export async function startServer({ directory, port, host, respectIgnore, auth,
       return c.json({ error: 'Read-only mode' }, 403);
     }
 
+    // CSRF protection: validate Origin header
+    if (!csrfCheck(c)) {
+      return c.json({ error: 'Forbidden: invalid origin' }, 403);
+    }
+
     const filePath = c.req.query('path');
     if (!filePath) {
       return c.json({ error: 'Missing path parameter' }, 400);
@@ -173,6 +229,9 @@ export async function startServer({ directory, port, host, respectIgnore, auth,
     }
 
     const body = await c.req.text();
+    if (body.length > MAX_FILE_SIZE) {
+      return c.json({ error: 'Request too large' }, 413);
+    }
     await fs.promises.writeFile(absPath, body, 'utf-8');
     return c.json({ ok: true });
   });
@@ -200,6 +259,10 @@ export async function startServer({ directory, port, host, respectIgnore, auth,
       return c.text('File not found', 404);
     }
 
+    if (stats.size > MAX_FILE_SIZE) {
+      return c.text('File too large', 413);
+    }
+
     const content = fs.readFileSync(absPath, 'utf-8');
     return c.text(content);
   });
@@ -264,10 +327,21 @@ export async function startServer({ directory, port, host, respectIgnore, auth,
       return c.text('Forbidden', 403);
     }
 
-    if (!fs.existsSync(absPath) || !fs.statSync(absPath).isFile()) {
+    let stats;
+    try {
+      stats = fs.statSync(absPath);
+    } catch {
+      return c.text('Not found', 404);
+    }
+
+    if (!stats.isFile()) {
       return c.text('Not found', 404);
     }
 
+    if (stats.size > MAX_FILE_SIZE) {
+      return c.text('File too large', 413);
+    }
+
     const content = fs.readFileSync(absPath);
     const ext = path.extname(absPath).toLowerCase();
     const contentType = MIME_TYPES[ext] || 'application/octet-stream';
@@ -303,11 +377,45 @@ export async function startServer({ directory, port, host, respectIgnore, auth,
     hostname: host,
   });
 
-  // WebSocket server
-  const wss = new WebSocketServer({ server });
+  // WebSocket server with origin validation
+  const wss = new WebSocketServer({
+    server,
+    verifyClient: (info) => {
+      const origin = info.origin || info.req.headers.origin;
+      if (!origin) return true; // Allow non-browser clients (curl, etc.)
+      try {
+        const url = new URL(origin);
+        return url.hostname === 'localhost' || url.hostname === '127.0.0.1' || url.hostname.endsWith('.trycloudflare.com');
+      } catch {
+        return false;
+      }
+    }
+  });
 
   const clients = new Set();
-  wss.on('connection', (ws) => {
+  wss.on('connection', (ws, req) => {
+    // Authenticate WebSocket connections when auth is enabled
+    if (auth) {
+      const authHeader = req.headers.authorization;
+      if (!authHeader || !authHeader.startsWith('Basic ')) {
+        ws.close(1008, 'Unauthorized');
+        return;
+      }
+      const decoded = Buffer.from(authHeader.slice(6), 'base64').toString();
+      const [user, ...rest] = decoded.split(':');
+      const pass = rest.join(':');
+      if (user !== auth.username || pass !== auth.password) {
+        ws.close(1008, 'Unauthorized');
+        return;
+      }
+    }
+
+    // Connection limit
+    if (clients.size >= MAX_WS_CLIENTS) {
+      ws.close(1013, 'Too many connections');
+      return;
+    }
+
     clients.add(ws);
     ws.on('close', () => clients.delete(ws));
     ws.on('error', () => clients.delete(ws));