Merge pull request #19 from kvokka/configurable-host-path

Author: WilliamJudge94

README.md

@@ -83,6 +83,7 @@ oh-my-opencode-dashboard
 Options:
 
 - `--project <path>` (optional): project root used for plan lookup + session filtering (defaults to current working directory)
+- `--host <hostname>` (optional): server bind host (defaults to `127.0.0.1`; can also be set with `OMO_DASHBOARD_HOST`)
 - `--port <number>` (optional): default 51234
 
 ## Install (from source)
@@ -106,6 +107,26 @@ bun run build
 bun run start -- --project /absolute/path/to/your/project
 ```
 
+Bind to localhost explicitly:
+
+```bash
+OMO_DASHBOARD_HOST=localhost bun run start -- --project /absolute/path/to/your/project
+```
+
+Expose the server outside localhost (for example from a container):
+
+```bash
+OMO_DASHBOARD_HOST=0.0.0.0 bun run start -- --project /absolute/path/to/your/project
+```
+
+Or via CLI:
+
+```bash
+bun run start -- --project /absolute/path/to/your/project --host 0.0.0.0
+```
+
+Use `0.0.0.0` only on trusted networks. It binds the server on all interfaces, while `localhost` keeps it local-only.
+
 ## What It Reads (SQLite + Legacy)
 
 - Project (optional; OhMyOpenCode plan tracking):
@@ -146,7 +167,7 @@ This dashboard is designed to avoid sensitive data:
 
 ## Security
 
-- Server binds to `127.0.0.1` only.
+- Server binds to `127.0.0.1` by default.
 - Path access is allowlisted and realpath-based to prevent symlink escape:
   - project root
   - OpenCode storage root

package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-opencode-dashboard",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Local-only, read-only dashboard for viewing OhMyOpenCode agent progress",
   "license": "SUL-1.0",
   "repository": {

src/server/host.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest"
+
+import { DEFAULT_HOST, getPublicHost, resolveServerHost } from "./host"
+
+describe("resolveServerHost", () => {
+  it("uses the default host when no override is provided", () => {
+    expect(resolveServerHost({})).toBe(DEFAULT_HOST)
+  })
+
+  it("uses the environment host when provided", () => {
+    expect(resolveServerHost({ envHost: "localhost" })).toBe("localhost")
+  })
+
+  it("prefers the CLI host over the environment host", () => {
+    expect(resolveServerHost({ cliHost: "0.0.0.0", envHost: "localhost" })).toBe("0.0.0.0")
+  })
+
+  it("ignores empty host values", () => {
+    expect(resolveServerHost({ cliHost: "   ", envHost: "" })).toBe(DEFAULT_HOST)
+  })
+})
+
+describe("getPublicHost", () => {
+  it("returns the host unchanged when it is already user-facing", () => {
+    expect(getPublicHost("localhost")).toBe("localhost")
+  })
+
+  it("maps 0.0.0.0 to localhost for startup logs", () => {
+    expect(getPublicHost("0.0.0.0")).toBe("localhost")
+  })
+
+  it("maps :: to localhost for startup logs", () => {
+    expect(getPublicHost("::")).toBe("localhost")
+  })
+})

src/server/host.ts

@@ -0,0 +1,17 @@
+const DEFAULT_HOST = "127.0.0.1"
+
+function normalizeHost(value: string | undefined): string | null {
+  if (typeof value !== "string") return null
+  const trimmed = value.trim()
+  return trimmed.length > 0 ? trimmed : null
+}
+
+export function resolveServerHost(opts: { cliHost?: string; envHost?: string }): string {
+  return normalizeHost(opts.cliHost) ?? normalizeHost(opts.envHost) ?? DEFAULT_HOST
+}
+
+export function getPublicHost(host: string): string {
+  return host === "0.0.0.0" || host === "::" ? "localhost" : host
+}
+
+export { DEFAULT_HOST }

src/server/start.ts

@@ -1,12 +1,14 @@
 #!/usr/bin/env bun
-import { Hono } from 'hono'
 import * as fs from "node:fs"
 import { basename, join } from 'node:path'
-import { parseArgs } from 'util'
+import { parseArgs } from 'node:util'
+import { Hono } from 'hono'
+import { addOrUpdateSource, listSources } from "../ingest/sources-registry"
+import { getLegacyStorageRootForBackend, selectStorageBackend } from "../ingest/storage-backend"
 import { createApi } from "./api"
 import { createDashboardStore, type DashboardStore } from "./dashboard"
-import { getLegacyStorageRootForBackend, selectStorageBackend } from "../ingest/storage-backend"
-import { addOrUpdateSource, listSources } from "../ingest/sources-registry"
+import { getPublicHost, resolveServerHost } from "./host"
+import { resolveStaticFilePath } from "./static-file"
 
 function isBunxInvocation(argv: string[]): boolean {
   if (process.env.BUN_INSTALL_CACHE_DIR) return true
@@ -20,14 +22,16 @@ const { values, positionals } = parseArgs({
   options: {
     project: { type: 'string' },
     port: { type: 'string' },
+    host: { type: 'string' },
     name: { type: 'string' },
   },
   allowPositionals: true,
 })
 
 const project = values.project ?? process.cwd()
 
-const port = parseInt(values.port || '51234')
+const port = parseInt(values.port || '51234', 10)
+const host = resolveServerHost({ cliHost: values.host, envHost: process.env.OMO_DASHBOARD_HOST })
 
 const cleanedPositionals = [...positionals]
 if (cleanedPositionals[0] === Bun.argv[0]) cleanedPositionals.shift()
@@ -111,12 +115,12 @@ const distRoot = join(import.meta.dir, '../../dist')
 // SPA fallback middleware
 app.use('*', async (c, next) => {
   const path = c.req.path
-  
+
   // Skip API routes - let them pass through
   if (path.startsWith('/api/')) {
     return await next()
   }
-  
+
   // For non-API routes without extensions, serve index.html
   if (!path.includes('.')) {
     const indexFile = Bun.file(join(distRoot, 'index.html'))
@@ -125,18 +129,22 @@ app.use('*', async (c, next) => {
     }
     return c.notFound()
   }
-  
+
   // For static files with extensions, try to serve them
-  const relativePath = path.startsWith('/') ? path.slice(1) : path
-  const file = Bun.file(join(distRoot, relativePath))
+  const filePath = resolveStaticFilePath(distRoot, path)
+  if (!filePath) {
+    return c.notFound()
+  }
+
+  const file = Bun.file(filePath)
   if (await file.exists()) {
     const ext = path.split('.').pop() || ''
     const contentType = getContentType(ext)
     return new Response(file, {
       headers: { 'Content-Type': contentType }
     })
   }
-  
+
   return c.notFound()
 })
 
@@ -162,8 +170,13 @@ function getContentType(ext: string): string {
 
 Bun.serve({
   fetch: app.fetch,
-  hostname: '127.0.0.1',
+  hostname: host,
   port,
 })
 
-console.log(`Server running on http://127.0.0.1:${port}`)
+const publicHost = getPublicHost(host)
+if (publicHost === host) {
+  console.log(`Server running on http://${publicHost}:${port}`)
+} else {
+  console.log(`Server running on http://${publicHost}:${port} (bound to ${host})`)
+}

src/server/static-file.test.ts

@@ -0,0 +1,51 @@
+import * as fs from "node:fs"
+import * as os from "node:os"
+import * as path from "node:path"
+import { describe, expect, it } from "vitest"
+
+import { resolveStaticFilePath } from "./static-file"
+
+function mkTempDir(prefix: string): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix))
+}
+
+describe("resolveStaticFilePath", () => {
+  it("returns a resolved path for files under dist", () => {
+    const distRoot = path.join("/tmp", "omo-dashboard-dist")
+    expect(resolveStaticFilePath(distRoot, "/assets/app.js")).toBe(path.join(distRoot, "assets", "app.js"))
+  })
+
+  it("rejects parent-directory traversal", () => {
+    const distRoot = path.join("/tmp", "omo-dashboard-dist")
+    expect(resolveStaticFilePath(distRoot, "/../package.json")).toBeNull()
+  })
+
+  it("rejects encoded parent-directory traversal", () => {
+    const distRoot = path.join("/tmp", "omo-dashboard-dist")
+    expect(resolveStaticFilePath(distRoot, "/..%2F..%2Fpackage.json")).toBeNull()
+  })
+
+  it("rejects encoded backslash traversal", () => {
+    const distRoot = path.join("/tmp", "omo-dashboard-dist")
+    expect(resolveStaticFilePath(distRoot, "/..%5Csecret.txt")).toBeNull()
+  })
+
+  it("rejects invalid URL encoding", () => {
+    const distRoot = path.join("/tmp", "omo-dashboard-dist")
+    expect(resolveStaticFilePath(distRoot, "/bad%E0%A4%A.txt")).toBeNull()
+  })
+
+  it("rejects symlink escapes from dist", () => {
+    const root = mkTempDir("omo-static-file-")
+    const distRoot = path.join(root, "dist")
+    const outsideRoot = path.join(root, "outside")
+    fs.mkdirSync(distRoot, { recursive: true })
+    fs.mkdirSync(outsideRoot, { recursive: true })
+
+    const outsideFile = path.join(outsideRoot, "secret.txt")
+    fs.writeFileSync(outsideFile, "shh", "utf8")
+    fs.symlinkSync(outsideFile, path.join(distRoot, "secret.txt"))
+
+    expect(resolveStaticFilePath(distRoot, "/secret.txt")).toBeNull()
+  })
+})

src/server/static-file.ts

@@ -0,0 +1,38 @@
+import { assertAllowedPath } from "../ingest/paths"
+
+function decodeRequestPath(requestPath: string): string | null {
+  try {
+    return decodeURIComponent(requestPath)
+  } catch {
+    return null
+  }
+}
+
+export function resolveStaticFilePath(distRoot: string, requestPath: string): string | null {
+  const decodedPath = decodeRequestPath(requestPath)
+  if (!decodedPath) return null
+
+  const relativePath = decodedPath.startsWith("/") ? decodedPath.slice(1) : decodedPath
+  const normalizedSegments = relativePath
+    .replace(/\\/g, "/")
+    .split("/")
+    .filter((segment) => segment.length > 0 && segment !== ".")
+
+  if (normalizedSegments.length === 0 || normalizedSegments.some((segment) => segment === "..")) {
+    return null
+  }
+
+  try {
+    return assertAllowedPath({
+      candidatePath: normalizedSegments.join("/"),
+      allowedRoots: [distRoot],
+      baseDir: distRoot,
+    })
+  } catch (error) {
+    if (error instanceof Error && error.message === "Access denied") {
+      return null
+    }
+
+    throw error
+  }
+}