fix(serve): canonicalise prefixed app entry

Reject malformed base paths such as //prefix before URL generation so the
client cannot drift onto a scheme-relative host.

Serve prefixed apps at /prefix/, redirect /prefix to that canonical route,
and set the manifest scope explicitly so the PWA entry, scope, and proxy
behaviour stay aligned.

Author: connorads

.agents/skills/remobi-setup/references/tailscale-serve.md

@@ -26,7 +26,7 @@ By default `remobi serve` binds to `127.0.0.1`, so it is not exposed on your LAN
 tailscale serve --bg 7681
 ```
 
-Your terminal is now available at `https://<your-machine>.<tailnet>.ts.net`.
+Your terminal is now available at `https://<your-machine>.<tailnet>.ts.net`. If you publish remobi behind a path prefix instead of the root, start remobi with `--base-path /that-prefix` so the WebSocket and PWA URLs stay aligned with the external URL.
 
 On mobile, tap **Add to Home Screen** for a standalone app experience with the remobi icon.
 

docs/architecture/networking-and-websockets.md

@@ -1,6 +1,6 @@
 # Networking and WebSocket flow
 
-This page explains how a browser reaches remobi, how the `/ws` transport works, and how the shared terminal session stays in sync across clients.
+This page explains how a browser reaches remobi, how the WebSocket transport works, and how the shared terminal session stays in sync across clients.
 
 For the high-level runtime layout, see [How remobi works](how-remobi-works.md).
 
@@ -18,6 +18,8 @@ The browser talks to two server entry points:
 - `GET /` for the HTML document with inline JS, CSS, config, and CSP nonce
 - `GET /ws` for the terminal WebSocket
 
+When `remobi serve --base-path /prefix` is used, remobi also serves the same HTML, WebSocket, manifest, and icon routes under `/prefix/...`. Root routes stay available for direct local access.
+
 ## Browser-to-session sequence
 
 ```mermaid
@@ -27,9 +29,9 @@ sequenceDiagram
     participant Session as SharedTerminalSession
     participant PTY as node-pty command
 
-    Browser->>Server: GET /
+    Browser->>Server: GET / or /prefix
     Server-->>Browser: HTML + inline config + client bundle
-    Browser->>Server: GET /ws (upgrade)
+    Browser->>Server: GET /ws or /prefix/ws (upgrade)
     Server->>Server: Validate Origin against Host
     Server->>Session: addClient(client)
     Note over Session,Browser: live output may race with snapshot
@@ -90,14 +92,14 @@ That is why the browser client has both snapshot handling and pending-output buf
 
 The current server behaviour matters for docs because remobi is usually deployed behind another network layer:
 
-- `/ws` upgrades are gated by an Origin check against the request Host header
+- `/ws` upgrades, including prefixed variants such as `/prefix/ws`, are gated by an Origin check against the request Host header
 - when no Origin is sent, loopback hosts are the only implicit allow case
 - CSP `connect-src` is scoped to the request authority, including explicit `ws://` and `wss://` entries for Safari compatibility
 - security headers are applied to both HTML and WebSocket-adjacent responses
 
 ## Client-side connection behaviour
 
-The browser opens exactly one terminal socket to `${location.host}/ws`.
+The browser opens exactly one terminal socket to `${location.host}${basePath}/ws`, where `basePath` is `/` by default and can be overridden with `--base-path`.
 
 - before the socket opens, outbound messages are queued locally
 - on open, the client sends a resize based on the fitted terminal size, then flushes queued messages

src/base-path.ts

@@ -16,6 +16,10 @@ export function normalizeBasePath(value: string): string | null {
 		return '/'
 	}
 
+	if (trimmed.includes('//')) {
+		return null
+	}
+
 	return trimmed
 }
 
@@ -34,3 +38,7 @@ export function joinBasePath(basePath: string, path: string): string {
 export function documentRoute(basePath: string): string {
 	return basePath === '/' ? '/' : `${basePath}/`
 }
+
+export function bareDocumentRoute(basePath: string): string | null {
+	return basePath === '/' ? null : basePath
+}

src/pwa/manifest.ts

@@ -5,6 +5,7 @@ interface WebAppManifest {
 	readonly name: string
 	readonly short_name: string
 	readonly start_url: string
+	readonly scope: string
 	readonly display: string
 	readonly background_color: string
 	readonly theme_color: string
@@ -22,6 +23,7 @@ export function generateManifest(name: string, pwa: PwaConfig, basePath = '/'):
 		name,
 		short_name: pwa.shortName ?? name,
 		start_url: documentRoute(basePath),
+		scope: documentRoute(basePath),
 		display: 'standalone',
 		background_color: pwa.themeColor,
 		theme_color: pwa.themeColor,

src/serve.ts

@@ -7,7 +7,7 @@ import { Hono } from 'hono'
 import type { WSContext } from 'hono/ws'
 import type WebSocket from 'ws'
 import { bundleClientAssets, renderClientHtml } from '../build'
-import { documentRoute, joinBasePath } from './base-path'
+import { bareDocumentRoute, documentRoute, joinBasePath } from './base-path'
 import { manifestToJson } from './pwa/manifest'
 import type { SessionClient, SharedTerminalSession } from './session'
 import {
@@ -414,13 +414,17 @@ export async function serve(
 
 	const canonicalDocumentRoute = documentRoute(basePath)
 	if (canonicalDocumentRoute !== '/') {
-		app.get(basePath, (c) =>
-			withSecurityHeaders(c.html(html), securityHeadersForRequest(c.req.header('host'))),
-		)
-
 		app.get(canonicalDocumentRoute, (c) =>
 			withSecurityHeaders(c.html(html), securityHeadersForRequest(c.req.header('host'))),
 		)
+
+		const bareRoute = bareDocumentRoute(basePath)
+		if (bareRoute) {
+			app.get(bareRoute, (c) => {
+				const securityHeaders = securityHeadersForRequest(c.req.header('host'))
+				return withSecurityHeaders(c.redirect(canonicalDocumentRoute, 308), securityHeaders)
+			})
+		}
 	}
 
 	if (manifestJson !== null) {

tests/base-path.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'vitest'
-import { documentRoute, joinBasePath, normalizeBasePath } from '../src/base-path'
+import { bareDocumentRoute, documentRoute, joinBasePath, normalizeBasePath } from '../src/base-path'
 
 describe('normalizeBasePath', () => {
 	test('accepts root and trims trailing slash for nested paths', () => {
@@ -8,8 +8,10 @@ describe('normalizeBasePath', () => {
 		expect(normalizeBasePath('/proxy/nested/')).toBe('/proxy/nested')
 	})
 
-	test('rejects relative paths and URL suffixes', () => {
+	test('rejects relative paths, repeated slashes, and URL suffixes', () => {
 		expect(normalizeBasePath('proxy')).toBeNull()
+		expect(normalizeBasePath('//proxy')).toBeNull()
+		expect(normalizeBasePath('/proxy//nested')).toBeNull()
 		expect(normalizeBasePath('/proxy?x=1')).toBeNull()
 		expect(normalizeBasePath('/proxy#frag')).toBeNull()
 	})
@@ -32,4 +34,9 @@ describe('document routes', () => {
 		expect(documentRoute('/')).toBe('/')
 		expect(documentRoute('/proxy')).toBe('/proxy/')
 	})
+
+	test('exposes the bare route only for nested base paths', () => {
+		expect(bareDocumentRoute('/')).toBeNull()
+		expect(bareDocumentRoute('/proxy')).toBe('/proxy')
+	})
 })

tests/cli-args.test.ts

@@ -336,7 +336,7 @@ describe('parseCliArgs', () => {
 	})
 
 	test('rejects invalid --base-path values', () => {
-		for (const value of ['', 'proxy', '/proxy?x=1', '/proxy#frag']) {
+		for (const value of ['', 'proxy', '//proxy', '/proxy//nested', '/proxy?x=1', '/proxy#frag']) {
 			const result = parseCliArgs(['serve', '--base-path', value])
 			expect(result.ok).toBe(false)
 			if (!result.ok) {

tests/playwright/proxy.spec.ts

@@ -63,17 +63,39 @@ async function waitForHttp(url: string, timeoutMs = 10_000): Promise<void> {
 	throw new Error(`timed out waiting for ${url}`)
 }
 
+function rewriteProxyPath(requestUrl: string | undefined, basePath: string): string | null {
+	const path = requestUrl ?? '/'
+	if (basePath === '/') {
+		return path
+	}
+	if (path === basePath || path === `${basePath}/`) {
+		return path
+	}
+	if (!path.startsWith(`${basePath}/`)) {
+		return null
+	}
+	return path
+}
+
 async function createReverseProxy(
 	backendPort: number,
 	proxyPort: number,
+	basePath = '/',
 ): Promise<{ close(): Promise<void> }> {
 	const sockets = new Set<Socket>()
 	const server = createServer((request, response) => {
+		const upstreamPath = rewriteProxyPath(request.url, basePath)
+		if (upstreamPath === null) {
+			response.statusCode = 404
+			response.end('not found')
+			return
+		}
+
 		const upstream = httpRequest(
 			{
 				hostname: '127.0.0.1',
 				port: backendPort,
-				path: request.url ?? '/',
+				path: upstreamPath,
 				method: request.method,
 				headers: request.headers,
 			},
@@ -98,6 +120,12 @@ async function createReverseProxy(
 	})
 
 	server.on('upgrade', (request, socket, head) => {
+		const upstreamPath = rewriteProxyPath(request.url, basePath)
+		if (upstreamPath === null) {
+			socket.destroy()
+			return
+		}
+
 		const upstreamSocket = connect(backendPort, '127.0.0.1', () => {
 			const headerLines = Object.entries(request.headers).flatMap(([name, value]) => {
 				if (typeof value === 'string') {
@@ -109,7 +137,7 @@ async function createReverseProxy(
 				return []
 			})
 			const handshake = [
-				`${request.method ?? 'GET'} ${request.url ?? '/ws'} HTTP/${request.httpVersion}`,
+				`${request.method ?? 'GET'} ${upstreamPath} HTTP/${request.httpVersion}`,
 				...headerLines,
 				'',
 				'',
@@ -153,9 +181,12 @@ async function createReverseProxy(
 	}
 }
 
-test('reverse-proxied access uses request-scoped CSP and a live websocket', async ({ page }) => {
+test('reverse-proxied subpath access uses request-scoped CSP and a live websocket', async ({
+	page,
+}) => {
 	const backendPort = await reservePort()
 	const proxyPort = await reservePort()
+	const basePath = '/random-token'
 	const home = mkdtempSync(join(tmpdir(), 'remobi-playwright-home-'))
 	tempDirs.push(home)
 
@@ -168,6 +199,8 @@ test('reverse-proxied access uses request-scoped CSP and a live websocket', asyn
 			'serve',
 			'--port',
 			String(backendPort),
+			'--base-path',
+			basePath,
 			'--',
 			'bash',
 			'--norc',
@@ -186,7 +219,7 @@ test('reverse-proxied access uses request-scoped CSP and a live websocket', asyn
 		exited = true
 	})
 
-	const proxy = await createReverseProxy(backendPort, proxyPort)
+	const proxy = await createReverseProxy(backendPort, proxyPort, basePath)
 	const consoleErrors: string[] = []
 	page.on('console', (message) => {
 		if (message.type() === 'error') {
@@ -196,11 +229,12 @@ test('reverse-proxied access uses request-scoped CSP and a live websocket', asyn
 
 	try {
 		await waitForHttp(`http://127.0.0.1:${backendPort}`)
-		await waitForHttp(`http://127.0.0.1:${proxyPort}`)
+		await waitForHttp(`http://127.0.0.1:${proxyPort}${basePath}`)
 
-		const response = await page.goto(`http://127.0.0.1:${proxyPort}`)
+		const response = await page.goto(`http://127.0.0.1:${proxyPort}${basePath}`)
 		expect(response).not.toBeNull()
 		const csp = response?.headers()['content-security-policy'] ?? ''
+		expect(page.url()).toBe(`http://127.0.0.1:${proxyPort}${basePath}/`)
 		expect(csp).toContain(`ws://127.0.0.1:${proxyPort}`)
 		expect(csp).toContain(`wss://127.0.0.1:${proxyPort}`)
 		expect(csp).not.toContain(`ws://127.0.0.1:${backendPort}`)

tests/pwa.test.ts

@@ -70,6 +70,15 @@ describe('generateManifest', () => {
 		}
 	})
 
+	test('prefixes start_url, scope, and icon paths when mounted under a subpath', () => {
+		const manifest = generateManifest('remobi', defaultPwa, '/proxy')
+		expect(manifest.start_url).toBe('/proxy/')
+		expect(manifest.scope).toBe('/proxy/')
+		for (const icon of manifest.icons) {
+			expect(icon.src.startsWith('/proxy/')).toBe(true)
+		}
+	})
+
 	test('custom name is reflected', () => {
 		const manifest = generateManifest('My Terminal', { ...defaultPwa, shortName: 'Term' })
 		expect(manifest.name).toBe('My Terminal')
@@ -99,6 +108,7 @@ describe('manifestToJson', () => {
 		const manifest = generateManifest('remobi', defaultPwa)
 		expect(parsed.name).toBe(manifest.name)
 		expect(parsed.display).toBe(manifest.display)
+		expect(parsed.scope).toBe(manifest.scope)
 	})
 })
 
@@ -109,6 +119,12 @@ describe('generatePwaHtml', () => {
 		expect(html).toContain('href="/manifest.json"')
 	})
 
+	test('prefixes asset links when mounted under a subpath', () => {
+		const html = generatePwaHtml('remobi', defaultPwa, '/proxy')
+		expect(html).toContain('href="/proxy/manifest.json"')
+		expect(html).toContain('href="/proxy/apple-touch-icon.png"')
+	})
+
 	test('includes theme-color meta', () => {
 		const html = generatePwaHtml('remobi', defaultPwa)
 		expect(html).toContain('name="theme-color"')