Merge pull request #286 from gosuda/feature/serve-file-share-links

feat(tunnel): serve local static sites and detect share links

Author: gosunuts

cmd/portal-tunnel/README.md

@@ -38,6 +38,16 @@ Default HTTPS stream for most local web apps:
 portal expose 3000 --name myapp
 ```
 
+Static site when you want to publish a local folder or a single HTML file
+without running a server. Pass a directory (served with `index.html`) or an HTML
+file (its folder is served with that file as the SPA/CSR entry). Unknown paths
+fall back to the entry file, and paths escaping the folder are refused:
+
+```text
+portal expose --serve ./site --name my-app
+portal expose --serve ./site/main.html --name my-app
+```
+
 Routed HTTP when one public URL should mount multiple local HTTP upstreams:
 
 ```text
@@ -100,6 +110,7 @@ Common `portal expose` flags:
 --thumbnail          Service thumbnail URL metadata
 --owner              Service owner metadata
 --hide               Hide service from relay listing screens
+--serve              Serve a local static site: a directory (served with index.html) or an HTML file (folder served with that file as SPA/CSR entry)
 --http-route         HTTP route mapping in PATH=UPSTREAM [METHOD[,METHOD...]:USDC_AMOUNT] form
 --x402-pay-to        Sui USDC payment recipient address for this tunnel
 --x402-testnet       Use Sui testnet for tunnel x402 payments
@@ -130,6 +141,10 @@ the Settings pane. Edit `http_routes`, `x402_pay_to`, `x402_testnet`, or
 ## Constraints
 
 - A positional `<target>` cannot be combined with `--http-route`.
+- `--serve` cannot be combined with a positional `<target>`, `--http-route`,
+  `--udp`, or `--tcp`. The `--serve` entry file must exist. Path traversal
+  (`..`) is refused, but a symlink inside the folder that points outside it is
+  still followed, so only serve folders you trust.
 - `--http-route` cannot be combined with `--udp`.
 - Route payment amounts are USDC values such as `0.01`, are part of
   `--http-route`, and require `--x402-pay-to`; add `--x402-testnet` for Sui

cmd/portal-tunnel/main.go

@@ -63,6 +63,7 @@ type exposeFlags struct {
 	x402Testnet     bool
 	targetAddr      string
 	httpRoutes      []string
+	serve           string
 	udp             bool
 	udpAddr         string
 	tcp             bool
@@ -92,6 +93,7 @@ func runExposeCommand(args []string) error {
 	utils.StringFlag(fs, &flags.x402PayTo, "x402-pay-to", "", "Sui USDC payment recipient address for this tunnel")
 	utils.BoolFlag(fs, &flags.x402Testnet, "x402-testnet", false, "Use Sui testnet for tunnel x402 payments; default is Sui mainnet")
 	utils.RepeatedStringFlag(fs, &flags.httpRoutes, "http-route", "HTTP route mapping in PATH=UPSTREAM [METHOD[,METHOD...]:USDC_AMOUNT] form; repeat to aggregate multiple local HTTP services behind one public URL")
+	utils.StringFlag(fs, &flags.serve, "serve", "", "Serve a local static site: pass a directory (served with index.html) or an HTML file (its folder is served with that file as the SPA/CSR entry). Unknown paths fall back to the entry file")
 	utils.BoolFlagEnv(fs, &flags.udp, "udp", false, "Enable public UDP relay in addition to the default TCP relay", "UDP_ENABLED")
 	utils.StringFlagEnv(fs, &flags.udpAddr, "udp-addr", "", "Local UDP target address for relayed datagrams (host:port or port only); defaults to the target when --udp is enabled", "UDP_ADDR")
 	utils.BoolFlagEnv(fs, &flags.tcp, "tcp", false, "Request a dedicated TCP port on the relay for raw TCP services (no TLS; e.g., Minecraft, game servers)", "TCP_ENABLED")
@@ -113,10 +115,23 @@ func runExposeCommand(args []string) error {
 		return err
 	}
 	httpRouteInputs := append([]string(nil), flags.httpRoutes...)
+	serve := strings.TrimSpace(flags.serve)
 	switch {
-	case flags.targetAddr == "" && len(httpRouteInputs) == 0:
+	case serve != "" && flags.targetAddr != "":
 		printExposeUsage(os.Stderr)
-		return errors.New("target or at least one --http-route is required")
+		return errors.New("target cannot be combined with --serve")
+	case serve != "" && len(httpRouteInputs) > 0:
+		printExposeUsage(os.Stderr)
+		return errors.New("--serve cannot be combined with --http-route")
+	case serve != "" && flags.udp:
+		printExposeUsage(os.Stderr)
+		return errors.New("--serve cannot be combined with --udp")
+	case serve != "" && flags.tcp:
+		printExposeUsage(os.Stderr)
+		return errors.New("--serve cannot be combined with --tcp")
+	case serve == "" && flags.targetAddr == "" && len(httpRouteInputs) == 0:
+		printExposeUsage(os.Stderr)
+		return errors.New("target, --serve, or at least one --http-route is required")
 	case flags.targetAddr != "" && len(flags.httpRoutes) > 0:
 		printExposeUsage(os.Stderr)
 		return errors.New("target cannot be combined with --http-route")
@@ -125,7 +140,19 @@ func runExposeCommand(args []string) error {
 		return errors.New("--udp cannot be combined with --http-route")
 	}
 
-	httpRoutes := make([]sdk.HTTPRouteConfig, 0, len(httpRouteInputs))
+	httpRoutes := make([]sdk.HTTPRouteConfig, 0, len(httpRouteInputs)+1)
+	if serve != "" {
+		root, index, err := utils.ResolveStaticSite(serve)
+		if err != nil {
+			printExposeUsage(os.Stderr)
+			return fmt.Errorf("--serve %q: %w", serve, err)
+		}
+		httpRoutes = append(httpRoutes, sdk.HTTPRouteConfig{
+			Prefix:      "/",
+			StaticRoot:  root,
+			StaticIndex: index,
+		})
+	}
 	for _, raw := range httpRouteInputs {
 		fields := strings.Fields(raw)
 		if len(fields) == 0 || len(fields) > 2 {
@@ -210,7 +237,7 @@ func runExposeCommand(args []string) error {
 	if err != nil {
 		return fmt.Errorf("failed to start relays: %w", err)
 	}
-	if len(httpRouteInputs) > 0 {
+	if len(httpRoutes) > 0 {
 		defer exposure.Close()
 		return exposure.RunHTTPRoutes(ctx, httpRoutes, "")
 	}
@@ -376,11 +403,14 @@ func printExposeUsage(w io.Writer) {
 	utils.WriteCommandUsage(w,
 		[]string{
 			"portal expose [flags] <target>",
+			"portal expose [flags] --serve <dir|file.html>",
 			"portal expose [flags] --http-route \"PATH=UPSTREAM [METHOD[,METHOD...]:USDC_AMOUNT]\" [...]",
 		},
 		[]string{
 			"portal expose 3000",
 			"portal expose localhost:8080 --name my-app",
+			"portal expose --serve ./site --name my-app",
+			"portal expose --serve ./site/main.html --name my-app",
 			"portal expose --http-route /api=http://127.0.0.1:3001 --http-route /=http://127.0.0.1:5173 --name my-app",
 			"portal expose --http-route \"/paid=http://127.0.0.1:3001 GET:0.01\" --http-route /=http://127.0.0.1:5173 --x402-pay-to 0x...",
 			"portal expose 3000 --udp --udp-addr 127.0.0.1:5353",

docs/src/lib/components/landing/TunnelCommandForm.svelte

@@ -6,11 +6,15 @@
 		RELAY_ORIGIN,
 		type TunnelCommandOS
 	} from '$lib/tunnel-command';
-	import { buildDefaultExposeName, resolveExposeName } from '$lib/expose-name';
+	import { buildDefaultExposeName } from '$lib/expose-name';
+	import { classifyShareInput, type ShareKind } from '$lib/share-link';
 
-	const DEFAULT_HOST = '3000';
+	const SHARE_KIND_LABEL: Record<ShareKind, string> = { url: 'URL', file: 'File', port: 'Port' };
+	const SHARE_PLACEHOLDER = 'file:///Users/me/site/index.html or 3000';
 
-	let target = $state('3000');
+	// Empty by default so the field reads as "paste a link here" instead of
+	// pre-committing the user to a local port.
+	let target = $state('');
 	let os: TunnelCommandOS = $state('unix');
 	let name = $state('');
 	let nameSeed = $state('');
@@ -20,49 +24,35 @@
 		nameSeed = crypto.randomUUID();
 	});
 
-	const generatedName = $derived(buildDefaultExposeName(target, nameSeed));
+	const share = $derived(classifyShareInput(target));
+	const generatedName = $derived(buildDefaultExposeName(share.seedTarget, nameSeed));
 	const effectiveName = $derived(name.trim() || generatedName);
 
-	const installBlock = $derived.by(() => {
-		const cmd = buildTunnelDisplayCommand({
+	const commandLines = $derived.by(() =>
+		buildTunnelDisplayCommand({
 			currentOrigin: RELAY_ORIGIN,
-			target,
+			target: share.target,
 			name: effectiveName,
 			nameSeed,
 			relayUrls: [RELAY_ORIGIN],
 			discovery: true,
 			thumbnailURL: '',
-			os
-		});
-		const lines = cmd.split('\n');
-		// Install is first line(s), expose is the rest
-		if (os === 'windows') {
-			// Windows: first two lines are install
-			return lines.slice(0, 2).join('\n');
-		}
-		return lines[0] ?? '';
-	});
+			os,
+			shareKind: share.kind,
+			servePath: share.path
+		}).split('\n')
+	);
 
-	const runBlock = $derived.by(() => {
-		const cmd = buildTunnelDisplayCommand({
-			currentOrigin: RELAY_ORIGIN,
-			target,
-			name: effectiveName,
-			nameSeed,
-			relayUrls: [RELAY_ORIGIN],
-			discovery: true,
-			thumbnailURL: '',
-			os
-		});
-		const lines = cmd.split('\n');
-		if (os === 'windows') {
-			return lines.slice(2).join('\n');
-		}
-		return lines.slice(1).join('\n');
-	});
+	// Install is the first line(s); the expose command is the rest.
+	const installBlock = $derived(
+		os === 'windows' ? commandLines.slice(0, 2).join('\n') : (commandLines[0] ?? '')
+	);
+	const runBlock = $derived(
+		os === 'windows' ? commandLines.slice(2).join('\n') : commandLines.slice(1).join('\n')
+	);
 
 	const previewURL = $derived(
-		buildTunnelPreviewURL(RELAY_ORIGIN, effectiveName, target, nameSeed)
+		buildTunnelPreviewURL(RELAY_ORIGIN, effectiveName, share.seedTarget, nameSeed)
 	);
 
 	function handleCopy() {
@@ -123,16 +113,23 @@
 			</div>
 
 			<div class="space-y-5">
-				<!-- 1. Start your local app -->
+				<!-- 1. Paste what you want to share -->
 				<div class="space-y-2">
 					<div class="space-y-1.5">
 						<p class="text-[13px] font-semibold tracking-[0.04em] text-slate-100 sm:text-sm">
-							1. Start your local app
-							<span class="ml-1 normal-case tracking-normal text-slate-400">
-								(e.g.
-								<span class="mx-1 font-mono text-slate-200">localhost:3000</span>
-								)
-							</span>
+							1. Paste what you want to share
+						</p>
+						<p class="text-[12px] leading-5 text-slate-400">
+							A local port such as
+							<span class="mx-1 font-mono text-slate-200">3000</span>, a running URL
+							such as
+							<span class="mx-1 font-mono text-slate-200">http://localhost:3000</span>,
+							or a file path such as
+							<span class="mx-1 font-mono text-slate-200"
+								>file:///Users/me/site/index.html</span
+							>
+							— file paths are served as a static site straight from that folder, so
+							nothing needs to be running locally.
 						</p>
 					</div>
 				</div>
@@ -174,23 +171,32 @@
 						</div>
 					</div>
 
-					<!-- Port + Name controls -->
-					<div class="flex flex-wrap items-center gap-x-4 gap-y-2 sm:flex-nowrap">
-						<div class="flex shrink-0 items-center gap-2">
+					<!-- Share + Name controls -->
+					<div class="space-y-2">
+						<div class="flex min-w-0 items-center gap-2">
 							<span
 								class="shrink-0 text-[9px] font-semibold uppercase tracking-[0.16em] text-slate-500"
 							>
-								Port
+								Share
 							</span>
 							<input
 								type="text"
 								bind:value={target}
-								placeholder={DEFAULT_HOST}
-								aria-label="Local port or address"
-								class="h-auto w-[76px] border-0 bg-transparent px-0 py-0 font-mono text-[13px] text-slate-200 shadow-none outline-none placeholder:text-slate-600"
+								placeholder={SHARE_PLACEHOLDER}
+								aria-label="Link, file path, or local port to share"
+								class="h-auto min-w-0 flex-1 border-0 bg-transparent px-0 py-0 font-mono text-[13px] text-slate-200 shadow-none outline-none placeholder:text-slate-600"
 							/>
+							{#if target.trim() !== ''}
+								<span
+									class="shrink-0 rounded px-1.5 py-0.5 text-[9px] font-semibold uppercase tracking-[0.12em] text-slate-400"
+									style="background: rgba(255,255,255,0.06);"
+									title="Detected share type"
+								>
+									{SHARE_KIND_LABEL[share.kind]}
+								</span>
+							{/if}
 						</div>
-						<div class="ml-auto flex min-w-0 items-center justify-end gap-2 sm:w-88">
+						<div class="flex min-w-0 items-center gap-2">
 							<span
 								class="shrink-0 text-[9px] font-semibold uppercase tracking-[0.16em] text-slate-500"
 							>

docs/src/lib/share-link.ts

@@ -0,0 +1,70 @@
+/**
+ * Classifies what a user pasted into the quick-start form so the generated
+ * command matches their intent:
+ *
+ * - `url`  — an `http(s)://` link: expose the host/port it points at.
+ * - `file` — a `file://` URL, a Windows path, or an absolute POSIX path: serve
+ *            the local static site with `portal expose --serve <path>`.
+ * - `port` — a bare port, `host:port`, or anything else: current behavior.
+ */
+export type ShareKind = 'url' | 'file' | 'port';
+
+export interface ShareInput {
+	kind: ShareKind;
+	/** Positional `portal expose <target>` value for `url` / `port` kinds. */
+	target: string;
+	/** Local filesystem path passed to `--serve` for the `file` kind. */
+	path: string;
+	/** Stable string used to seed auto-generated names. */
+	seedTarget: string;
+}
+
+const WINDOWS_PATH = /^[A-Za-z]:[\\/]/;
+const UNC_PATH = /^\\\\/;
+
+export function classifyShareInput(raw: string): ShareInput {
+	const trimmed = raw.trim();
+	if (trimmed === '') {
+		return { kind: 'port', target: '', path: '', seedTarget: '' };
+	}
+
+	if (/^https?:\/\//i.test(trimmed)) {
+		const target = urlToExposeTarget(trimmed);
+		return { kind: 'url', target, path: '', seedTarget: target || trimmed };
+	}
+
+	if (/^file:\/\//i.test(trimmed)) {
+		const path = fileURLToPath(trimmed);
+		return { kind: 'file', target: '', path, seedTarget: path || trimmed };
+	}
+
+	if (WINDOWS_PATH.test(trimmed) || UNC_PATH.test(trimmed) || trimmed.startsWith('/')) {
+		return { kind: 'file', target: '', path: trimmed, seedTarget: trimmed };
+	}
+
+	return { kind: 'port', target: trimmed, path: '', seedTarget: trimmed };
+}
+
+function urlToExposeTarget(raw: string): string {
+	try {
+		const parsed = new URL(raw);
+		if (parsed.hostname === '') return '';
+		return parsed.port ? `${parsed.hostname}:${parsed.port}` : parsed.hostname;
+	} catch {
+		return '';
+	}
+}
+
+function fileURLToPath(raw: string): string {
+	try {
+		const parsed = new URL(raw);
+		let path = decodeURIComponent(parsed.pathname);
+		// file:///C:/dir/main.html → /C:/dir/main.html → C:/dir/main.html
+		if (/^\/[A-Za-z]:[\\/]/.test(path)) {
+			path = path.slice(1);
+		}
+		return path;
+	} catch {
+		return raw.replace(/^file:\/\//i, '');
+	}
+}