feat: support browser UI base paths (#1071)

Adds generic support for serving the Roborev browser application below a configured URL path prefix.

The prefix is applied consistently across HTTP routing, redirects, runtime metadata, CLI deep links, embedded assets, API and event-stream requests, and client-side history. Internal application routes remain distinct from already-prefixed external API base URLs, including when a route overlaps the configured prefix. Root-mounted behavior remains the default.

Remote browser access requires a dedicated origin. A base path provides routing, and cookie path scoping reduces incidental transmission, but neither isolates Roborev from other applications on the same origin.

Also adds a host-local browser token-file option, with fail-closed validation and mutual exclusion from the inline token. Base paths reject values that URL parsers could reinterpret, including percent escapes, backslashes, control characters, and surrounding whitespace. Reverse proxies can preserve the prefix while keeping the browser listener loopback-bound and streaming responses unbuffered.

Production template injection rejects missing or duplicate markers instead of silently serving root-relative URLs. The release check exercises the generated Vite output with a non-root prefix.

The full Go suite, browser suite, repository hooks, and production web build pass.


Co-authored-by: Wes McKinney <wesm@users.noreply.github.com>

Author: wesm

Makefile

@@ -53,7 +53,7 @@ web-restore:
 web-release-check: web-embed
 	@set -e; trap '$(MAKE) web-restore' EXIT; \
 		ROBOREV_RUN_WEB_RELEASE_CHECK=1 CGO_ENABLED=0 \
-		go test ./internal/web -run '^TestEmbeddedReleaseDistribution$$' -count=1
+		go test ./internal/web -run '^TestEmbeddedRelease' -count=1
 
 release-snapshot-check:
 	@set -e; trap 'cd web && bun run assets:restore' EXIT; \

cmd/roborev/daemon_cmd.go

@@ -97,7 +97,11 @@ func discoverWebUIURL(discover func() (*daemon.RuntimeInfo, error)) string {
 	if err != nil || runtimeInfo == nil || runtimeInfo.WebOrigin == "" {
 		return ""
 	}
-	return runtimeInfo.WebOrigin
+	webURL, err := browserRootURL(runtimeInfo.WebOrigin, runtimeInfo.WebBasePath)
+	if err != nil {
+		return ""
+	}
+	return webURL
 }
 
 func displayWebUIURL(webURL string) string {

cmd/roborev/daemon_cmd_test.go

@@ -98,6 +98,27 @@ func TestDaemonRestartShowsPublicWebUIURL(t *testing.T) {
 	assert.Equal(t, "Daemon restarted\nWeb UI: https://reviews.example.com\n", output)
 }
 
+func TestDaemonRestartShowsPrefixedWebUIURL(t *testing.T) {
+	withDaemonCommandDependencies(t,
+		func() error { return nil },
+		func() error { return nil },
+		func() (*daemon.RuntimeInfo, error) {
+			return &daemon.RuntimeInfo{
+				WebOrigin:   "https://reviews.example.com",
+				WebBasePath: "/roborev-ci",
+			}, nil
+		},
+	)
+
+	output := captureStdout(t, func() {
+		cmd := daemonCmd()
+		cmd.SetArgs([]string{"restart"})
+		require.NoError(t, cmd.Execute())
+	})
+
+	assert.Equal(t, "Daemon restarted\nWeb UI: https://reviews.example.com/roborev-ci/\n", output)
+}
+
 func TestDaemonRestartShowsUnavailableWhenBrowserIsDisabled(t *testing.T) {
 	withDaemonCommandDependencies(t,
 		func() error { return nil },

cmd/roborev/status_test.go

@@ -91,6 +91,28 @@ func TestStatusCmdJSONIncludesWebUIURL(t *testing.T) {
 	assert.Equal(t, "https://reviews.example.com", parsed.WebURL)
 }
 
+func TestStatusCmdJSONIncludesPrefixedWebUIURL(t *testing.T) {
+	md := NewMockDaemon(t, MockRefineHooks{})
+	defer md.Close()
+
+	withStatusWebRuntime(t, func() (*daemon.RuntimeInfo, error) {
+		return &daemon.RuntimeInfo{
+			WebOrigin:   "https://reviews.example.com",
+			WebBasePath: "/roborev-ci",
+		}, nil
+	})
+
+	output := captureStdout(t, func() {
+		cmd := statusCmd()
+		cmd.SetArgs([]string{"--json"})
+		require.NoError(t, cmd.Execute())
+	})
+
+	var parsed statusJSONOutput
+	require.NoError(t, json.Unmarshal([]byte(output), &parsed))
+	assert.Equal(t, "https://reviews.example.com/roborev-ci/", parsed.WebURL)
+}
+
 func TestDaemonStatusUsesSharedStatusOutput(t *testing.T) {
 	md := NewMockDaemon(t, MockRefineHooks{})
 	defer md.Close()

cmd/roborev/ui_cmd.go

@@ -10,6 +10,7 @@ import (
 
 	"github.com/spf13/cobra"
 
+	"go.kenn.io/roborev/internal/config"
 	"go.kenn.io/roborev/internal/daemon"
 )
 
@@ -36,7 +37,7 @@ func uiCmd() *cobra.Command {
 			if runtimeInfo.WebOrigin == "" {
 				return fmt.Errorf("the daemon browser listener is disabled")
 			}
-			target, err := uiURL(runtimeInfo.WebOrigin, args)
+			target, err := uiURL(runtimeInfo.WebOrigin, runtimeInfo.WebBasePath, args)
 			if err != nil {
 				return err
 			}
@@ -101,7 +102,15 @@ func validateUIArgs(_ *cobra.Command, args []string) error {
 	return nil
 }
 
-func uiURL(origin string, args []string) (string, error) {
+func uiURL(origin, basePath string, args []string) (string, error) {
+	path := "/reviews"
+	if len(args) == 1 {
+		path += "/" + args[0]
+	}
+	return browserURL(origin, basePath, path)
+}
+
+func browserURL(origin, basePath, internalPath string) (string, error) {
 	parsed, err := url.Parse(origin)
 	if err != nil || parsed.Host == "" || parsed.User != nil || parsed.Path != "" || parsed.RawQuery != "" || parsed.Fragment != "" {
 		return "", fmt.Errorf("daemon published an invalid browser origin")
@@ -111,9 +120,27 @@ func uiURL(origin string, args []string) (string, error) {
 	default:
 		return "", fmt.Errorf("daemon published an invalid browser origin")
 	}
-	parsed.Path = "/reviews"
-	if len(args) == 1 {
-		parsed.Path += "/" + args[0]
+	normalizedBasePath, err := config.NormalizeWebBasePath(basePath)
+	if err != nil {
+		return "", fmt.Errorf("daemon published an invalid browser base path: %w", err)
 	}
+	parsed.Path = normalizedBasePath + internalPath
+	parsed.RawPath = ""
 	return parsed.String(), nil
 }
+
+func browserRootURL(origin, basePath string) (string, error) {
+	if basePath == "" {
+		parsed, err := url.Parse(origin)
+		if err != nil || parsed.Host == "" || parsed.User != nil || parsed.Path != "" || parsed.RawQuery != "" || parsed.Fragment != "" {
+			return "", fmt.Errorf("daemon published an invalid browser origin")
+		}
+		switch strings.ToLower(parsed.Scheme) {
+		case "http", "https":
+		default:
+			return "", fmt.Errorf("daemon published an invalid browser origin")
+		}
+		return parsed.String(), nil
+	}
+	return browserURL(origin, basePath, "/")
+}

cmd/roborev/ui_cmd_test.go

@@ -44,6 +44,25 @@ func TestUICmdOpensReviewRoutes(t *testing.T) {
 	}
 }
 
+func TestUICmdOpensPrefixedReviewRoutes(t *testing.T) {
+	var opened string
+	withUICommandDependencies(t,
+		func() error { return nil },
+		func() (*daemon.RuntimeInfo, error) {
+			return &daemon.RuntimeInfo{
+				WebOrigin:   "https://reviews.example.com",
+				WebBasePath: "/roborev-ci",
+			}, nil
+		},
+		func(target string) error { opened = target; return nil },
+	)
+
+	cmd := uiCmd()
+	cmd.SetArgs([]string{"42"})
+	require.NoError(t, cmd.Execute())
+	assert.Equal(t, "https://reviews.example.com/roborev-ci/reviews/42", opened)
+}
+
 func TestUICmdRejectsInvalidJobIDs(t *testing.T) {
 	for _, args := range [][]string{{"0"}, {"-1"}, {"nope"}, {"1", "2"}} {
 		cmd := uiCmd()

docs/commands.md

@@ -154,11 +154,12 @@ completes.
 `roborev show` displays review comments after the review output when comments
 exist, matching the layout in the TUI review detail view.
 
-`roborev ui` starts the daemon when needed, reads the browser origin from the
-live daemon runtime, and opens `/reviews`. An optional positive numeric job ID
-opens `/reviews/<job-id>`. Job IDs are local to that daemon's SQLite database,
-so a numeric deep link is not portable to another machine even when review data
-is synchronized. Authentication tokens are never placed in the launch URL. The
+`roborev ui` starts the daemon when needed, reads the browser origin and path
+prefix from the live daemon runtime, and opens `/reviews` below that prefix when
+one is configured. An optional positive numeric job ID opens `/reviews/<job-id>`
+below the same prefix. Job IDs are local to that daemon's SQLite database, so a
+numeric deep link is not portable to another machine even when review data is
+synchronized. Authentication tokens are never placed in the launch URL. The
 browser listener is enabled on loopback by default, so an installed release
 needs no additional configuration for local use: run `roborev ui` and the
 application displays the reviews from the same SQLite database used by the CLI

docs/configuration.md

@@ -764,8 +764,10 @@ column_borders = true             # Show separators between TUI columns
 | `server_addr` | string | 127.0.0.1:7373 | Daemon listen address. Use `unix://` for Unix domain socket (see [Unix Domain Socket](#unix-domain-socket)) | No |
 | `web.enabled` | bool | true | Serve the embedded browser application on a separate listener | No |
 | `web.listen` | string | 127.0.0.1:0 | Loopback browser listener address. Port 0 selects an available ephemeral port | No |
-| `web.public_origin` | string | - | Exact HTTPS origin exposed by a reverse proxy | No |
+| `web.public_origin` | string | - | Exact dedicated HTTPS origin exposed by a reverse proxy | No |
+| `web.base_path` | string | - | Optional canonical routing prefix, without a trailing slash; not a same-origin security boundary | No |
 | `web.auth_token` | string | - | Base64url-encoded 32-byte random token exchanged for a process-local browser session | No |
+| `web.auth_token_file` | string | - | Host-local file containing the browser token; mutually exclusive with `web.auth_token` | No |
 | `max_workers` | int | 4 | Number of parallel review workers | No |
 | `job_timeout_minutes` | int | 30 | Per-job timeout in minutes | Yes |
 | `hook_timeout_seconds` | int | `3` (`30` on Windows) | Post-commit hook request timeout, in seconds. Raise it on Windows or large repos where the daemon's enqueue git calls are slow. Zero or negative values are ignored and fall back to the platform default | Yes |
@@ -838,16 +840,34 @@ Paste that command's output as `auth_token`:
 enabled = true
 listen = "127.0.0.1:7374"
 public_origin = "https://reviews.example.com"
-auth_token = "paste-the-generated-token-here"
+base_path = "/reviews"
+auth_token_file = "/etc/roborev/web-auth-token"
 ```
 
+`public_origin` must be an exact scheme-and-authority origin with no path and
+must be dedicated to Roborev-controlled content. Serve sibling applications from
+separate origins. Set `base_path` separately when the proxy mounts the browser
+application below a URL prefix; it must start with `/`, have no trailing slash,
+query, fragment, percent escape, backslash, control character, surrounding
+whitespace, or path traversal. The token file must contain exactly one
+base64url-encoded 32-byte token, optionally followed by one terminal newline. It
+is mutually exclusive with `auth_token` and is read when the daemon starts, so
+the token bytes do not need to be stored in the configuration file.
+
 The proxy must preserve the public `Host`, set conventional forwarding headers,
 and avoid buffering `/api/stream/events` and streamed `/api/job/output`
 responses. The public origin must match the browser origin exactly and must use
 HTTPS for remote access. Roborev rejects non-loopback browser listener addresses
 so credentials are never sent over a plaintext network hop. The CLI API remains
 private on its original listener.
 
+The browser session cookie uses `/` when `base_path` is empty and
+`base_path + "/"` when a prefix is configured. That path scope reduces
+incidental cookie transmission, but it is not an authorization boundary: scripts
+on the same origin can still make requests below the prefix. `base_path`
+provides routing only, so do not host sibling applications on the Roborev
+origin.
+
 The browser exchanges the daemon token for an HTTP-only cookie and tab-scoped
 credentials. The token is entered after the public shell opens and is never
 retained by the application. Sessions are process-local, so every daemon restart

docs/web-ui.md

@@ -29,7 +29,8 @@ Open a particular review with its local job ID:
 roborev ui 42
 ```
 
-This opens `/reviews/42`. Job IDs belong to one daemon's SQLite database, so a
+This opens `/reviews/42`, or the same route below `web.base_path` when a path
+prefix is configured. Job IDs belong to one daemon's SQLite database, so a
 numeric review URL is not portable between machines.
 
 The application has two workspaces:
@@ -87,9 +88,9 @@ a different daemon.
 ## Analytics
 
 Open **Analytics** in the application shell, or navigate directly to
-`/analytics`. Filters are encoded in the URL, so a time range and project,
-source, agent, model, or bucket selection can be bookmarked and shared with
-another user of the same daemon.
+`/analytics` (below `web.base_path` when configured). Filters are encoded in the
+URL, so a time range and project, source, agent, model, or bucket selection can
+be bookmarked and shared with another user of the same daemon.
 
 Project analytics use the display names shown elsewhere in Roborev. Repositories
 with the same display name are intentionally grouped together.
@@ -145,19 +146,30 @@ Choose a fixed loopback port. Generate the required 32-byte base64url token:
 openssl rand -base64 32 | tr '+/' '-_' | tr -d '='
 ```
 
-Paste the generated value into `~/.roborev/config.toml`:
+Store the generated value in a host-local file readable by the Roborev daemon,
+with an optional single trailing newline, and configure that file in
+`~/.roborev/config.toml`:
 
 ```toml
 [web]
 enabled = true
 listen = "127.0.0.1:7374"
 public_origin = "https://reviews.example.com"
-auth_token = "paste-the-generated-token-here"
+base_path = "/reviews"
+auth_token_file = "/etc/roborev/web-auth-token"
 ```
 
 `public_origin` must be the exact origin users open, without a path or trailing
-slash. Protect the config file because it contains the login token. Restart the
-daemon after changing any `[web]` setting:
+slash, and that origin must serve only Roborev-controlled content. Serve sibling
+applications from separate origins. `base_path` is an optional canonical path
+prefix: it starts with `/`, has no trailing slash, and must be preserved by the
+reverse proxy. It cannot contain a percent escape, backslash, control character,
+or surrounding whitespace. The browser session cookie is scoped to that prefix
+to reduce incidental transmission, but same-origin scripts can still make
+requests below it. The prefix provides routing, not isolation. `auth_token_file`
+and `auth_token` are mutually exclusive; the token file must contain exactly one
+token. Protect the token file and restart the daemon after changing any `[web]`
+setting:
 
 ```bash
 roborev daemon restart
@@ -177,9 +189,10 @@ then run:
 tailscale serve --bg http://127.0.0.1:7374
 ```
 
-Use the HTTPS origin printed by `tailscale serve` as `web.public_origin`, then
-restart Roborev. Open that origin on another device in the tailnet and enter the
-configured `web.auth_token` when prompted.
+For this root-mounted example, use the HTTPS origin printed by `tailscale serve`
+as `web.public_origin`, then restart Roborev. Open that origin on another device
+in the tailnet and enter the configured token when prompted. A path-mounted
+deployment needs a reverse proxy that preserves the configured `base_path`.
 
 Do not use Tailscale Funnel for this setup: Serve keeps access inside the
 tailnet. Tailnet policy remains the network-level access boundary, while the