From b022f3923a075269ef3c616b80790776cac9920c Mon Sep 17 00:00:00 2001
From: blaise1030 <blaisetiong.dev@gmail.com>
Date: Wed, 17 Jun 2026 18:08:26 +0800
Subject: [PATCH] feat(lan): add rotating single-use invite tokens for secure
 LAN access (30s)

- Tokens rotate every 30 seconds and are immediately invalidated after use
- QR code now encodes invite URL with current token (?invite=...)
- Non-loopback LAN clients must present a valid unconsumed token to authenticate
- Desktop localhost access remains tokenless for convenience
- Settings > Network now shows current invite link + live-updating QR
- Frontend auto-detects token from URL, sends it on auth, cleans URL after use
- Polling keeps the invite QR fresh while viewing settings

Also includes earlier LAN binding (0.0.0.0) and mobile UI responsiveness improvements (sidebar collapse, aux panels via page layout on small screens).

Tested: pnpm build succeeds, Go builds and basic flows verified.
---
 apps/cli/args.ts                              |   7 +-
 apps/frontend/src/api/auth.ts                 |   9 +-
 .../settings/pages/NetworkSettings.vue        | 102 +++++++++-
 .../terminal/layout/TerminalWorkspace.vue     |  28 +--
 .../workspace/layout/WorkspaceLayout.vue      |  10 +-
 apps/frontend/src/router/index.ts             |  13 +-
 apps/server-go/internal/api/router.go         |   2 +-
 apps/server-go/internal/appstate/state.go     |   4 +-
 apps/server-go/internal/auth/local.go         |  24 +++
 apps/server-go/internal/auth/router.go        |  14 +-
 apps/server-go/internal/cli/cli.go            |   1 +
 apps/server-go/internal/cli/flags.go          |   8 +-
 apps/server-go/internal/lan/lan.go            | 176 +++++++++++++++++-
 .../internal/server/allowed_hosts_test.go     |  15 +-
 apps/server-go/internal/server/server.go      |  40 +++-
 apps/server-go/internal/settings/router.go    |  29 ++-
 16 files changed, 432 insertions(+), 50 deletions(-)

diff --git a/apps/cli/args.ts b/apps/cli/args.ts
index 0a77513..bfd35fb 100644
--- a/apps/cli/args.ts
+++ b/apps/cli/args.ts
@@ -9,6 +9,7 @@ export interface CliArgs {
   host: string;
   forceHttp: boolean;
   assumeYes: boolean;
+  lan: boolean;
   showHelp: boolean;
 }
 
@@ -21,6 +22,7 @@ Options:
   -p, --port <number>   Port (default: ${DEFAULT_NETWORK_PORT}, or PORT env, or ~/.workbench/config.json)
   --host <hostname>     Local hostname (default: ${DEFAULT_NETWORK_HOST}, or WORKBENCH_HOST env)
   --http, --insecure    Serve HTTP on localhost only (no mkcert)
+  --lan, --expose       Bind on all interfaces and show LAN URLs
   -y, --yes             Install mkcert without prompting if missing
   -h, --help            Show this help
 
@@ -36,6 +38,7 @@ export function parseCliArgs(argv: string[]): CliArgs {
   let host = process.env.WORKBENCH_HOST?.trim() || fileConfig.host;
   let forceHttp = false;
   let assumeYes = false;
+  let lan = false;
   let showHelp = false;
 
   for (let i = 0; i < argv.length; i++) {
@@ -46,6 +49,8 @@ export function parseCliArgs(argv: string[]): CliArgs {
       assumeYes = true;
     } else if (arg === "--http" || arg === "--insecure") {
       forceHttp = true;
+    } else if (arg === "--lan" || arg === "--expose") {
+      lan = true;
     } else if (arg === "--port" || arg === "-p") {
       const next = argv[++i];
       if (!next) throw new Error("Missing value for --port");
@@ -60,7 +65,7 @@ export function parseCliArgs(argv: string[]): CliArgs {
     }
   }
 
-  return { port, host, forceHttp, assumeYes, showHelp };
+  return { port, host, forceHttp, assumeYes, lan, showHelp };
 }
 
 export function printCliHelp(): void {
diff --git a/apps/frontend/src/api/auth.ts b/apps/frontend/src/api/auth.ts
index 47a7ca4..8a9f6f9 100644
--- a/apps/frontend/src/api/auth.ts
+++ b/apps/frontend/src/api/auth.ts
@@ -1,8 +1,11 @@
 import { apiClient } from "@/lib/api-client";
 import { ensureOk } from "@/lib/api-error";
 
-/** Auto-authenticate when the UI is served from the same machine as the server. */
-export async function ensureLocalAuth(): Promise<void> {
-  const res = await apiClient.auth.local.$post();
+/** Auto-authenticate when the UI is served from the same machine as the server.
+ *  If an invite token is provided (from QR), it will be sent for validation.
+ */
+export async function ensureLocalAuth(token?: string): Promise<void> {
+  const body = token ? { token } : {};
+  const res = await apiClient.auth.local.$post({ json: body });
   await ensureOk<{ ok: true }>(res);
 }
diff --git a/apps/frontend/src/modules/settings/pages/NetworkSettings.vue b/apps/frontend/src/modules/settings/pages/NetworkSettings.vue
index e7856b4..c866a1b 100644
--- a/apps/frontend/src/modules/settings/pages/NetworkSettings.vue
+++ b/apps/frontend/src/modules/settings/pages/NetworkSettings.vue
@@ -1,7 +1,10 @@
 <script setup lang="ts">
-import { computed, ref, watch } from "vue";
+import { computed, onUnmounted, ref, watch } from "vue";
+import QRCode from "qrcode";
 import { toast } from "vue-sonner";
 import { Input } from "@/components/ui/input";
+import { useQueryClient } from "@tanstack/vue-query";
+import { settingsKeys } from "@/modules/settings/queries/settings";
 import { Button } from "@/components/ui/button";
 import { Card } from "@/components/ui/card";
 import { Textarea } from "@/components/ui/textarea";
@@ -37,9 +40,64 @@ const tlsSetupPrompt = computed(() =>
     : "",
 );
 
+const lanMode = computed(() => networkData.value?.lanMode ?? false);
+const lanUrls = computed(() => networkData.value?.lanUrls ?? []);
+const lanIps = computed(() => networkData.value?.lanIps ?? []);
+const inviteUrl = computed(() => networkData.value?.inviteUrl ?? "");
+const primaryLanUrl = computed(() => lanUrls.value[0] ?? "");
+const qrDataUrl = ref<string>("");
+
+watch(
+  inviteUrl,
+  async (url) => {
+    if (url) {
+      try {
+        // Use the invite URL (contains rotating single-use token) for the QR
+        qrDataUrl.value = await QRCode.toDataURL(url, { margin: 1, width: 160 });
+      } catch {
+        qrDataUrl.value = "";
+      }
+    } else if (lanUrls.value.length > 0) {
+      // fallback to plain LAN URL if no invite token
+      try {
+        qrDataUrl.value = await QRCode.toDataURL(lanUrls.value[0], { margin: 1, width: 160 });
+      } catch {
+        qrDataUrl.value = "";
+      }
+    } else {
+      qrDataUrl.value = "";
+    }
+  },
+  { immediate: true },
+);
+
 const hostInput = ref("");
 const portInput = ref("");
 
+const queryClient = useQueryClient();
+let inviteRefresh: ReturnType<typeof setInterval> | undefined;
+
+watch(
+  lanMode,
+  (active) => {
+    if (inviteRefresh) {
+      clearInterval(inviteRefresh);
+      inviteRefresh = undefined;
+    }
+    if (active) {
+      // Poll for fresh rotating invite token / QR (token changes every ~30s)
+      inviteRefresh = setInterval(() => {
+        queryClient.invalidateQueries({ queryKey: settingsKeys.network() });
+      }, 7000);
+    }
+  },
+  { immediate: true },
+);
+
+onUnmounted(() => {
+  if (inviteRefresh) clearInterval(inviteRefresh);
+});
+
 watch(
   networkData,
   (n) => {
@@ -110,6 +168,15 @@ async function copyTlsSetupPrompt() {
     toast.error("Could not copy to clipboard.");
   }
 }
+
+async function copyLanUrl(url: string) {
+  try {
+    await navigator.clipboard.writeText(url);
+    toast.success("Copied LAN URL to clipboard.");
+  } catch {
+    toast.error("Could not copy to clipboard.");
+  }
+}
 </script>
 
 <template>
@@ -231,6 +298,39 @@ async function copyTlsSetupPrompt() {
           </div>
         </div>
 
+        <div v-if="lanUrls.length" class="mt-3 border-t pt-3">
+          <div class="mb-2">
+            <div class="font-medium text-sm">LAN access</div>
+            <div class="text-xs text-muted-foreground">
+              Base LAN URLs. For secure access from other devices use the rotating invite link below (token changes every 30s and is single-use).
+            </div>
+          </div>
+
+          <!-- Plain LAN URLs (for reference) -->
+          <div class="flex flex-col gap-2 mb-3">
+            <div v-for="u in lanUrls" :key="u" class="flex items-center gap-2">
+              <code class="flex-1 truncate rounded bg-muted px-2 py-1 text-xs font-mono">{{ u }}</code>
+              <Button variant="outline" size="sm" :disabled="loading" @click="copyLanUrl(u)">Copy</Button>
+            </div>
+          </div>
+
+          <!-- Invite link + QR (recommended for phone) -->
+          <div v-if="inviteUrl" class="space-y-2">
+            <div class="text-xs font-medium">Invite link (rotates every 30s, single-use)</div>
+            <div class="flex items-center gap-2">
+              <code class="flex-1 truncate rounded bg-muted px-2 py-1 text-xs font-mono">{{ inviteUrl }}</code>
+              <Button variant="outline" size="sm" :disabled="loading" @click="copyLanUrl(inviteUrl)">Copy</Button>
+            </div>
+            <div v-if="qrDataUrl" class="mt-2 flex items-start gap-3">
+              <img :src="qrDataUrl" alt="Scan to open on another device" class="rounded border bg-white p-1" />
+              <div class="text-[10px] text-muted-foreground pt-1 leading-tight">
+                Scan with phone camera.<br />
+                Token auto-invalidates after use or 30s.
+              </div>
+            </div>
+          </div>
+        </div>
+
         <div class="flex justify-end pt-2">
           <Button :disabled="loading || !networkDirty" @click="saveNetwork">
             Save
diff --git a/apps/frontend/src/modules/terminal/layout/TerminalWorkspace.vue b/apps/frontend/src/modules/terminal/layout/TerminalWorkspace.vue
index 80343f9..a624be5 100644
--- a/apps/frontend/src/modules/terminal/layout/TerminalWorkspace.vue
+++ b/apps/frontend/src/modules/terminal/layout/TerminalWorkspace.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { computed, provide, ref, watch, type ComponentPublicInstance } from "vue";
-import { useDebounceFn } from "@vueuse/core";
+import { useDebounceFn, useMediaQuery } from "@vueuse/core";
 import { useQuery, useQueryClient } from "@tanstack/vue-query";
 import {
   FolderTreeIcon,
@@ -76,6 +76,8 @@ const router = useRouter();
 const queryClient = useQueryClient();
 const { effectiveTheme } = useAppTheme();
 const sessions = useTerminalSessions();
+const isMobile = useMediaQuery('(max-width: 768px)');
+const effectiveLayoutMode = computed(() => (isMobile.value ? 'page' : layoutMode.value) as 'split' | 'page');
 
 /** Remount only on theme change; terminal switches reuse the instance (see below). */
 const routerViewKey = computed(() => {
@@ -117,7 +119,7 @@ const gitItemIdsRef = ref<string[]>([]);
 provide(contextQueueGitItemIdsKey, gitItemIdsRef);
 
 const effectiveRouteName = computed(() => {
-  if (layoutMode.value !== "split") return route.name;
+  if (effectiveLayoutMode.value !== "split") return route.name;
   if (splitAuxPanel.value === "explorer") return "explorer";
   if (splitAuxPanel.value === "git") return "git";
   return route.name;
@@ -158,13 +160,13 @@ const terminalTabItems = computed(() =>
 );
 
 const isGitVisible = computed(() =>
-  layoutMode.value === "split"
+  effectiveLayoutMode.value === "split"
     ? splitAuxPanel.value === "git"
     : route.name === "git",
 );
 
 const isExplorerVisible = computed(() =>
-  layoutMode.value === "split"
+  effectiveLayoutMode.value === "split"
     ? splitAuxPanel.value === "explorer"
     : route.name === "explorer",
 );
@@ -201,7 +203,7 @@ function onSplitLayout(sizes: number[]) {
 }
 
 const hasPanelContent = computed(() => {
-  if (layoutMode.value === "split") {
+  if (effectiveLayoutMode.value === "split") {
     return terminalTabItems.value.length > 0 || splitAuxPanel.value !== null;
   }
   return (
@@ -212,7 +214,7 @@ const hasPanelContent = computed(() => {
 });
 
 const activeId = computed(() => {
-  if (layoutMode.value === "split") {
+  if (effectiveLayoutMode.value === "split") {
     return activeTerminalId.value;
   }
   if (route.name === "terminal") return route.params.terminalId as string;
@@ -359,7 +361,7 @@ async function addTerminal(choice: AddTerminalChoice = { kind: "shell" }) {
 
 function openAuxPanel(type: "git" | "explorer") {
   panelsState.value = activateWorktreeAuxPanel(panelsState.value, type);
-  if (layoutMode.value === "page") {
+  if (effectiveLayoutMode.value === "page") {
     router.push({
       name: type,
       params: { worktreeId: props.worktreeId },
@@ -416,7 +418,7 @@ function toggleAuxPanel(type: "git" | "explorer") {
     } else {
       panelsState.value = { ...panelsState.value, explorer: false };
     }
-    if (layoutMode.value === "page") {
+    if (effectiveLayoutMode.value === "page") {
       navigateToFirstTerminal();
     }
     return;
@@ -480,7 +482,7 @@ function equalizeSplitPanes() {
 
 <template>
   <div class="flex min-h-0 flex-1 flex-col">
-    <header v-if="layoutMode === 'page'" class="flex shrink-0 items-stretch bg-sidebar">
+    <header v-if="effectiveLayoutMode === 'page'" class="flex shrink-0 items-stretch bg-sidebar">
       <div
         class="flex aspect-square shrink-0 items-stretch border-e border-border/60"
       >
@@ -587,7 +589,7 @@ function equalizeSplitPanes() {
         </div>
       </div>
       <RouterView
-        v-else-if="layoutMode === 'page'"
+        v-else-if="effectiveLayoutMode === 'page'"
         :key="routerViewKey"
         class="absolute inset-0 border-t"
       />
@@ -681,12 +683,12 @@ function equalizeSplitPanes() {
           />
         </ResizablePanel>
         <ResizableHandle
-          v-if="activeTerminalId && splitAuxPanel"
+          v-if="!isMobile && activeTerminalId && splitAuxPanel"
           with-handle
           @dblclick.prevent="equalizeSplitPanes"
         />
         <ResizablePanel
-          v-if="splitAuxPanel === 'git'"
+          v-if="!isMobile && splitAuxPanel === 'git'"
           id="split-git"
           :min-size="SPLIT_AUX_MIN_SIZE"
           :default-size="splitAuxDefaultSize"
@@ -695,7 +697,7 @@ function equalizeSplitPanes() {
           <GitPanel :worktree-id="worktreeId" class="min-h-0 flex-1" />
         </ResizablePanel>
         <ResizablePanel
-          v-else-if="splitAuxPanel === 'explorer'"
+          v-else-if="!isMobile && splitAuxPanel === 'explorer'"
           id="split-explorer"
           :min-size="SPLIT_AUX_MIN_SIZE"
           :default-size="splitAuxDefaultSize"
diff --git a/apps/frontend/src/modules/workspace/layout/WorkspaceLayout.vue b/apps/frontend/src/modules/workspace/layout/WorkspaceLayout.vue
index c805548..40e36c1 100644
--- a/apps/frontend/src/modules/workspace/layout/WorkspaceLayout.vue
+++ b/apps/frontend/src/modules/workspace/layout/WorkspaceLayout.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { computed, provide } from "vue";
-import { useDebounceFn, useLocalStorage } from "@vueuse/core";
+import { useDebounceFn, useLocalStorage, useMediaQuery } from "@vueuse/core";
 import {
   ResizableHandle,
   ResizablePanel,
@@ -38,7 +38,9 @@ provide(workspaceSidebarKey, workspaceSidebar);
 const terminalSessions = createTerminalSessionsStore();
 provide(terminalSessionsKey, terminalSessions);
 
-const sidebarDefaultSize = computed(() => clampWidth(sidebarWidth.value));
+const isMobile = useMediaQuery('(max-width: 768px)');
+
+const sidebarDefaultSize = computed(() => (isMobile.value ? 0 : clampWidth(sidebarWidth.value)));
 
 const persistSidebarWidth = useDebounceFn((width: number) => {
   sidebarWidth.value = clampWidth(width);
@@ -54,7 +56,7 @@ function onLayout(sizes: number[]) {
 </script>
 
 <template>
-  <div class="flex h-screen flex-col">
+  <div class="flex h-dvh min-h-dvh flex-col">
     <ResizablePanelGroup
       direction="horizontal"
       class="min-h-0 flex-1"
@@ -77,7 +79,7 @@ function onLayout(sizes: number[]) {
         />
         <WorkspaceSidebar :active-worktree-id="activeWorktreeId" />
       </ResizablePanel>
-      <ResizableHandle v-show="!workspaceSidebar.isCollapsed.value" with-handle />
+      <ResizableHandle v-show="!isMobile && !workspaceSidebar.isCollapsed.value" with-handle />
       <ResizablePanel :min-size="30" class="flex min-h-0 flex-col">
         <div class="flex h-full min-h-0 flex-1 flex-col">
           <slot />
diff --git a/apps/frontend/src/router/index.ts b/apps/frontend/src/router/index.ts
index 382eef0..27fb27e 100644
--- a/apps/frontend/src/router/index.ts
+++ b/apps/frontend/src/router/index.ts
@@ -85,9 +85,20 @@ router.beforeEach(async (to, from) => {
     rememberSettingsReturnRoute(from.fullPath);
   }
 
+  const search = new URLSearchParams(window.location.search);
+  const inviteToken = search.get("invite") || search.get("token") || undefined;
+
   try {
-    await ensureLocalAuth();
+    await ensureLocalAuth(inviteToken);
     queryClient.prefetchQuery(networkSettingsQueryOptions());
+
+    // Clean the token from the URL after successful validation (one-time use)
+    if (inviteToken) {
+      const url = new URL(window.location.href);
+      url.searchParams.delete("invite");
+      url.searchParams.delete("token");
+      window.history.replaceState({}, "", url.pathname + url.search + url.hash);
+    }
   } catch {
     // Auth failed (e.g. API down, or dev UI origin not allowed on Go). Skip prefetch.
   }
diff --git a/apps/server-go/internal/api/router.go b/apps/server-go/internal/api/router.go
index ecf3950..0ed0d16 100644
--- a/apps/server-go/internal/api/router.go
+++ b/apps/server-go/internal/api/router.go
@@ -159,7 +159,7 @@ func RegisterRoutes(r *chi.Mux, version string, state *appstate.AppState, cookie
 			})
 
 			r.Route("/auth", func(r chi.Router) {
-				auth.RegisterRoutes(r, state.Session, cookieSecure)
+				auth.RegisterRoutes(r, state.Session, cookieSecure, state.Lan.ValidateAndConsumeInviteToken)
 			})
 
 			r.Route("/settings", func(r chi.Router) {
diff --git a/apps/server-go/internal/appstate/state.go b/apps/server-go/internal/appstate/state.go
index 7ac4934..e49b1ce 100644
--- a/apps/server-go/internal/appstate/state.go
+++ b/apps/server-go/internal/appstate/state.go
@@ -24,7 +24,7 @@ type AppState struct {
 	WorktreeWatcher *watcher.WorktreeWatcher
 }
 
-func New(port int, host string, forceHTTP bool) (*AppState, error) {
+func New(port int, host string, forceHTTP bool, lanMode bool) (*AppState, error) {
 	storeFile := filepath.Join(config.DataDir(), "settings.json")
 	database, err := db.Open(config.DbPath())
 	if err != nil {
@@ -33,7 +33,7 @@ func New(port int, host string, forceHTTP bool) (*AppState, error) {
 	bus := events.NewBus()
 	return &AppState{
 		Session:         auth.CreateSession(),
-		Lan:             lan.New(port, host, forceHTTP),
+		Lan:             lan.New(port, host, forceHTTP, lanMode),
 		SettingsStore:   settings.NewFileStore(storeFile),
 		DB:              database,
 		EventBus:        bus,
diff --git a/apps/server-go/internal/auth/local.go b/apps/server-go/internal/auth/local.go
index 37b56cd..e5ab2f8 100644
--- a/apps/server-go/internal/auth/local.go
+++ b/apps/server-go/internal/auth/local.go
@@ -31,3 +31,27 @@ func ClientAddress(r *http.Request) string {
 func IsLocalRequest(r *http.Request) bool {
 	return IsLoopbackAddress(ClientAddress(r))
 }
+
+// IsPrivateLANAddress reports whether addr is an RFC1918 private IPv4 or IPv6 ULA address.
+func IsPrivateLANAddress(addr string) bool {
+	ip := net.ParseIP(addr)
+	if ip == nil {
+		return false
+	}
+	if ip4 := ip.To4(); ip4 != nil {
+		return ip4[0] == 10 || (ip4[0] == 172 && ip4[1] >= 16 && ip4[1] <= 31) || (ip4[0] == 192 && ip4[1] == 168)
+	}
+	// IPv6 unique local (fc00::/7)
+	return len(ip) == 16 && (ip[0] == 0xfc || ip[0] == 0xfd)
+}
+
+// CanBootstrapSession returns true for loopback or private LAN addresses.
+// Used only for initial session cookie bootstrap (/auth/local) to support LAN mode
+// while keeping strict localhost for dangerous actions (folder picker etc.).
+func CanBootstrapSession(r *http.Request) bool {
+	addr := ClientAddress(r)
+	if IsLoopbackAddress(addr) {
+		return true
+	}
+	return IsPrivateLANAddress(addr)
+}
diff --git a/apps/server-go/internal/auth/router.go b/apps/server-go/internal/auth/router.go
index 09f45dc..647f138 100644
--- a/apps/server-go/internal/auth/router.go
+++ b/apps/server-go/internal/auth/router.go
@@ -32,12 +32,22 @@ func jsonErr(w http.ResponseWriter, msg string, code int) {
 }
 
 // RegisterRoutes mounts POST /local on the given router sub-path.
-func RegisterRoutes(r chi.Router, session *Session, cookieSecure bool) {
+// tokenValidator, if non-nil, is used to validate a one-time invite token for LAN access.
+func RegisterRoutes(r chi.Router, session *Session, cookieSecure bool, tokenValidator func(string) bool) {
 	r.Post("/local", func(w http.ResponseWriter, r *http.Request) {
-		if !IsLocalRequest(r) {
+		var body struct {
+			Token string `json:"token"`
+		}
+		_ = json.NewDecoder(r.Body).Decode(&body) // best effort
+
+		if body.Token != "" && tokenValidator != nil && tokenValidator(body.Token) {
+			// token validated and consumed by validator
+		} else if !IsLoopbackAddress(ClientAddress(r)) {
+			// without a valid token, only allow pure localhost (loopback)
 			jsonErr(w, "Forbidden", http.StatusForbidden)
 			return
 		}
+
 		if !session.Active() {
 			session.Activate()
 		}
diff --git a/apps/server-go/internal/cli/cli.go b/apps/server-go/internal/cli/cli.go
index 7697e01..8abda34 100644
--- a/apps/server-go/internal/cli/cli.go
+++ b/apps/server-go/internal/cli/cli.go
@@ -34,5 +34,6 @@ func Execute(argv []string) error {
 		Host:      cfg.Host,
 		ForceHTTP: cfg.ForceHTTP,
 		AssumeYes: cfg.AssumeYes,
+		Lan:       cfg.Lan,
 	})
 }
diff --git a/apps/server-go/internal/cli/flags.go b/apps/server-go/internal/cli/flags.go
index d2ef54c..a21454e 100644
--- a/apps/server-go/internal/cli/flags.go
+++ b/apps/server-go/internal/cli/flags.go
@@ -14,6 +14,7 @@ type Config struct {
 	Host      string
 	ForceHTTP bool
 	AssumeYes bool
+	Lan       bool
 	ShowHelp  bool
 }
 
@@ -27,10 +28,12 @@ Options:
   -p, --port <number>   Port (default: %d, or PORT env, or ~/.workbench/config.json)
   --host <hostname>     Local hostname (default: %s, or WORKBENCH_HOST env)
   --http, --insecure    Serve HTTP on localhost only (no mkcert)
+  --lan, --expose       Bind on all interfaces (0.0.0.0) and show LAN IPs for other devices
   -y, --yes             Install mkcert without prompting if missing
   -h, --help            Show this help
 
 HTTPS uses mkcert for trusted local certificates. HTTP mode skips mkcert.
+--lan serves on the local network (anyone on your WiFi/LAN can reach it).
 Without --yes, the CLI asks before installing mkcert.
 
 Add to /etc/hosts once: 127.0.0.1 %s
@@ -51,7 +54,7 @@ func ParseArgs(argv []string) (Config, error) {
 		host = envHost
 	}
 
-	var forceHTTP, assumeYes, showHelp bool
+	var forceHTTP, assumeYes, lan, showHelp bool
 
 	for i := 0; i < len(argv); i++ {
 		arg := argv[i]
@@ -62,6 +65,8 @@ func ParseArgs(argv []string) (Config, error) {
 			assumeYes = true
 		case "--http", "--insecure":
 			forceHTTP = true
+		case "--lan", "--expose":
+			lan = true
 		case "--port", "-p":
 			i++
 			if i >= len(argv) {
@@ -90,6 +95,7 @@ func ParseArgs(argv []string) (Config, error) {
 		Host:      host,
 		ForceHTTP: forceHTTP,
 		AssumeYes: assumeYes,
+		Lan:       lan,
 		ShowHelp:  showHelp,
 	}, nil
 }
diff --git a/apps/server-go/internal/lan/lan.go b/apps/server-go/internal/lan/lan.go
index b4166dd..45151ab 100644
--- a/apps/server-go/internal/lan/lan.go
+++ b/apps/server-go/internal/lan/lan.go
@@ -1,28 +1,81 @@
 package lan
 
 import (
+	"crypto/rand"
+	"encoding/hex"
 	"fmt"
+	"net"
 	"sync"
+	"time"
 )
 
 // Manager tracks local URL scheme, hostname, and port for settings and TLS.
+// When lanMode is true the server listens on 0.0.0.0 and advertises LAN IPs.
 type Manager struct {
 	mu        sync.RWMutex
 	urlScheme string
 	port      int
 	localHost string
+	lan       bool
+	lanIPs    []string
+
+	// invite token state (rotates every 30s, single-use after consumption)
+	inviteMu        sync.Mutex
+	currentInvite   string
+	inviteExpiresAt time.Time
+}
+
+// getPrivateIPv4 discovers usable private LAN IPv4 addresses (excludes loopback, link-local).
+func getPrivateIPv4() []string {
+	var ips []string
+	ifaces, err := net.Interfaces()
+	if err != nil {
+		return nil
+	}
+	for _, iface := range ifaces {
+		if iface.Flags&net.FlagUp == 0 || iface.Flags&(net.FlagLoopback|net.FlagPointToPoint) != 0 {
+			continue
+		}
+		addrs, err := iface.Addrs()
+		if err != nil {
+			continue
+		}
+		for _, addr := range addrs {
+			ipnet, ok := addr.(*net.IPNet)
+			if !ok {
+				continue
+			}
+			ip := ipnet.IP.To4()
+			if ip == nil {
+				continue
+			}
+			if ip.IsLoopback() || ip.IsLinkLocalUnicast() || ip.IsLinkLocalMulticast() {
+				continue
+			}
+			// RFC1918 private ranges
+			if ip[0] == 10 || (ip[0] == 172 && ip[1] >= 16 && ip[1] <= 31) || (ip[0] == 192 && ip[1] == 168) {
+				ips = append(ips, ip.String())
+			}
+		}
+	}
+	return ips
 }
 
-func New(port int, localHost string, forceHTTP bool) *Manager {
+func New(port int, localHost string, forceHTTP bool, lan bool) *Manager {
 	scheme := "https"
 	if forceHTTP {
 		scheme = "http"
 	}
-	return &Manager{
+	m := &Manager{
 		urlScheme: scheme,
 		port:      port,
 		localHost: localHost,
+		lan:       lan,
+		lanIPs:    getPrivateIPv4(),
 	}
+	m.rotateInviteToken()
+	go m.runInviteRotation()
+	return m
 }
 
 func (m *Manager) GetLocalURL() string {
@@ -60,5 +113,122 @@ func (m *Manager) GetHostname() string {
 func (m *Manager) GetTLSHosts() []string {
 	m.mu.RLock()
 	defer m.mu.RUnlock()
-	return []string{m.localHost, "localhost", "127.0.0.1"}
+	hosts := []string{m.localHost, "localhost", "127.0.0.1"}
+	if m.lan {
+		for _, ip := range m.lanIPs {
+			hosts = append(hosts, ip)
+		}
+	}
+	return hosts
+}
+
+// IsLANMode reports whether the server is bound for LAN access.
+func (m *Manager) IsLANMode() bool {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	return m.lan
+}
+
+// GetLANIPs returns discovered private LAN IPv4 addresses (may be empty).
+func (m *Manager) GetLANIPs() []string {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	out := make([]string, len(m.lanIPs))
+	copy(out, m.lanIPs)
+	return out
+}
+
+// GetLANURLs returns full http(s) URLs using the discovered LAN IPs.
+func (m *Manager) GetLANURLs() []string {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	urls := make([]string, len(m.lanIPs))
+	for i, ip := range m.lanIPs {
+		urls[i] = fmt.Sprintf("%s://%s:%d/", m.urlScheme, ip, m.port)
+	}
+	return urls
+}
+
+// --- Invite token (rotating every 30s, single-use) ---
+
+func generateSecureToken() string {
+	b := make([]byte, 16)
+	if _, err := rand.Read(b); err != nil {
+		// extremely rare fallback
+		return fmt.Sprintf("%x", time.Now().UnixNano())
+	}
+	return hex.EncodeToString(b)
+}
+
+func (m *Manager) runInviteRotation() {
+	ticker := time.NewTicker(30 * time.Second)
+	defer ticker.Stop()
+	for range ticker.C {
+		m.rotateInviteToken()
+	}
+}
+
+func (m *Manager) rotateInviteToken() {
+	token := generateSecureToken()
+	m.inviteMu.Lock()
+	m.currentInvite = token
+	m.inviteExpiresAt = time.Now().Add(30 * time.Second)
+	m.inviteMu.Unlock()
+}
+
+// GetCurrentInviteToken returns the currently active invite token if still valid.
+// The token is only valid for a short window and is single-use.
+func (m *Manager) GetCurrentInviteToken() string {
+	m.inviteMu.Lock()
+	defer m.inviteMu.Unlock()
+	if m.currentInvite == "" || m.inviteExpiresAt.IsZero() || time.Now().After(m.inviteExpiresAt) {
+		return ""
+	}
+	return m.currentInvite
+}
+
+// GetInviteURL returns a ready-to-use URL containing the current invite token
+// (appended as ?invite=TOKEN). It prefers a discovered LAN IP when available.
+func (m *Manager) GetInviteURL() string {
+	token := m.GetCurrentInviteToken()
+	if token == "" {
+		return ""
+	}
+
+	m.mu.RLock()
+	scheme := m.urlScheme
+	port := m.port
+	host := m.localHost
+	ips := append([]string(nil), m.lanIPs...)
+	m.mu.RUnlock()
+
+	if len(ips) > 0 {
+		host = ips[0]
+	}
+	return fmt.Sprintf("%s://%s:%d/?invite=%s", scheme, host, port, token)
+}
+
+// ValidateAndConsumeInviteToken checks the provided token against the current active one.
+// If it matches and has not expired, the token is immediately invalidated (single-use)
+// and true is returned.
+func (m *Manager) ValidateAndConsumeInviteToken(token string) bool {
+	if token == "" {
+		return false
+	}
+	m.inviteMu.Lock()
+	defer m.inviteMu.Unlock()
+
+	if m.currentInvite == "" || token != m.currentInvite {
+		return false
+	}
+	if m.inviteExpiresAt.IsZero() || time.Now().After(m.inviteExpiresAt) {
+		m.currentInvite = ""
+		m.inviteExpiresAt = time.Time{}
+		return false
+	}
+
+	// valid and within window — consume it
+	m.currentInvite = ""
+	m.inviteExpiresAt = time.Time{}
+	return true
 }
diff --git a/apps/server-go/internal/server/allowed_hosts_test.go b/apps/server-go/internal/server/allowed_hosts_test.go
index 59fb488..ca90441 100644
--- a/apps/server-go/internal/server/allowed_hosts_test.go
+++ b/apps/server-go/internal/server/allowed_hosts_test.go
@@ -7,7 +7,7 @@ import (
 
 func TestBuildAllowedHosts_IncludesServerAndDevUI(t *testing.T) {
 	t.Setenv("WORKBENCH_DEV_UI_PORT", "5173")
-	hosts := buildAllowedHosts(4740, "workbench.local")
+	hosts := buildAllowedHosts(4740, "workbench.local", nil)
 	want := map[string]bool{
 		"localhost:4740":       true,
 		"127.0.0.1:4740":       true,
@@ -27,8 +27,19 @@ func TestBuildAllowedHosts_IncludesServerAndDevUI(t *testing.T) {
 
 func TestBuildAllowedHosts_NoDevPort(t *testing.T) {
 	os.Unsetenv("WORKBENCH_DEV_UI_PORT")
-	hosts := buildAllowedHosts(4738, "workbench.local")
+	hosts := buildAllowedHosts(4738, "workbench.local", nil)
 	if len(hosts) != 3 {
 		t.Fatalf("got %v", hosts)
 	}
 }
+
+func TestBuildAllowedHosts_IncludesLAN(t *testing.T) {
+	hosts := buildAllowedHosts(4738, "workbench.local", []string{"192.168.1.42", "10.0.0.5"})
+	found := map[string]bool{}
+	for _, h := range hosts {
+		found[h] = true
+	}
+	if !found["192.168.1.42:4738"] || !found["10.0.0.5:4738"] {
+		t.Fatalf("expected LAN hosts in %v", hosts)
+	}
+}
diff --git a/apps/server-go/internal/server/server.go b/apps/server-go/internal/server/server.go
index 7470764..ea6a94e 100644
--- a/apps/server-go/internal/server/server.go
+++ b/apps/server-go/internal/server/server.go
@@ -34,7 +34,7 @@ func Version() string {
 
 // buildAllowedHosts lists Origin header hosts permitted for state-changing API calls.
 // WORKBENCH_DEV_UI_PORT adds localhost:<port> when Vite proxies /api during dev:go.
-func buildAllowedHosts(port int, host string) []string {
+func buildAllowedHosts(port int, host string, lanIPs []string) []string {
 	portStr := fmt.Sprintf("%d", port)
 	hosts := []string{
 		fmt.Sprintf("localhost:%s", portStr),
@@ -43,6 +43,10 @@ func buildAllowedHosts(port int, host string) []string {
 	if cfgHost := fmt.Sprintf("%s:%s", host, portStr); cfgHost != hosts[0] && cfgHost != hosts[1] {
 		hosts = append(hosts, cfgHost)
 	}
+	for _, ip := range lanIPs {
+		h := fmt.Sprintf("%s:%s", ip, portStr)
+		hosts = append(hosts, h)
+	}
 	if devPort := strings.TrimSpace(os.Getenv("WORKBENCH_DEV_UI_PORT")); devPort != "" {
 		hosts = append(hosts,
 			fmt.Sprintf("localhost:%s", devPort),
@@ -57,10 +61,11 @@ type Config struct {
 	Host      string
 	ForceHTTP bool
 	AssumeYes bool
+	Lan       bool
 }
 
 func Run(cfg Config) error {
-	state, err := appstate.New(cfg.Port, cfg.Host, cfg.ForceHTTP)
+	state, err := appstate.New(cfg.Port, cfg.Host, cfg.ForceHTTP, cfg.Lan)
 	if err != nil {
 		return fmt.Errorf("init state: %w", err)
 	}
@@ -109,14 +114,23 @@ func Run(cfg Config) error {
 	cookieSecure := !cfg.ForceHTTP
 	r := chi.NewRouter()
 
+	lanIPs := state.Lan.GetLANIPs()
 	openHost := cfg.Host
-	if cfg.ForceHTTP {
+	listenHost := "127.0.0.1"
+	if cfg.Lan {
+		listenHost = "0.0.0.0"
+		if len(lanIPs) > 0 {
+			// Prefer first LAN IP for display when explicitly in lan mode
+			openHost = lanIPs[0]
+		}
+	}
+	if cfg.ForceHTTP && !cfg.Lan {
 		openHost = "127.0.0.1"
 	}
-	allowedHosts := buildAllowedHosts(cfg.Port, cfg.Host)
+	allowedHosts := buildAllowedHosts(cfg.Port, cfg.Host, lanIPs)
 	api.RegisterRoutes(r, version, state, cookieSecure, registry, allowedHosts)
 
-	listenAddr := fmt.Sprintf("127.0.0.1:%d", cfg.Port)
+	listenAddr := fmt.Sprintf("%s:%d", listenHost, cfg.Port)
 
 	ln, err := net.Listen("tcp", listenAddr)
 	if err != nil {
@@ -125,13 +139,17 @@ func Run(cfg Config) error {
 
 	scheme := "http"
 	if !cfg.ForceHTTP {
-		hosts := []string{cfg.Host, "localhost", "127.0.0.1"}
+		hosts := state.Lan.GetTLSHosts()
 		creds, tlsErr := tlsutil.EnsureTLS(hosts, tlsutil.EnsureOptions{
 			AutoInstall: cfg.AssumeYes,
 		})
 		if tlsErr != nil {
 			slog.Warn("TLS setup failed, falling back to HTTP", "err", tlsErr)
-			fmt.Printf("\n  ⚠ Serving over HTTP on localhost only (not encrypted).\n  %s\n\n", tlsErr)
+			if cfg.Lan {
+				fmt.Printf("\n  ⚠ TLS failed; serving over HTTP on LAN (not encrypted).\n  %s\n\n", tlsErr)
+			} else {
+				fmt.Printf("\n  ⚠ Serving over HTTP on localhost only (not encrypted).\n  %s\n\n", tlsErr)
+			}
 		} else {
 			scheme = "https"
 			ln = tls.NewListener(ln, &tls.Config{
@@ -140,7 +158,13 @@ func Run(cfg Config) error {
 		}
 	}
 
-	fmt.Printf("\n  → %s://%s:%d\n\n", scheme, openHost, cfg.Port)
+	fmt.Printf("\n  → %s://%s:%d\n", scheme, openHost, cfg.Port)
+	if cfg.Lan {
+		for _, u := range state.Lan.GetLANURLs() {
+			fmt.Printf("  → %s (LAN)\n", u)
+		}
+	}
+	fmt.Println()
 	slog.Info("workbench-cli started", "url", fmt.Sprintf("%s://%s:%d", scheme, openHost, cfg.Port))
 
 	srv := &http.Server{
diff --git a/apps/server-go/internal/settings/router.go b/apps/server-go/internal/settings/router.go
index 0c347f5..60e5e9b 100644
--- a/apps/server-go/internal/settings/router.go
+++ b/apps/server-go/internal/settings/router.go
@@ -17,18 +17,27 @@ type NetworkProvider interface {
 	GetURLScheme() string
 	GetLocalHost() string
 	Port() int
+	IsLANMode() bool
+	GetLANIPs() []string
+	GetLANURLs() []string
+	GetCurrentInviteToken() string
+	GetInviteURL() string
 }
 
 // NetworkSettings matches networkSettingsSchema.
 type NetworkSettings struct {
-	Host           string `json:"host"`
-	Port           int    `json:"port"`
-	ProdPort       int    `json:"prodPort"`
-	NonProdPort    int    `json:"nonProdPort"`
-	LocalURL       string `json:"localUrl"`
-	Scheme         string `json:"scheme"`
-	HostsFileLine  string `json:"hostsFileLine"`
-	PendingRestart bool   `json:"pendingRestart"`
+	Host           string   `json:"host"`
+	Port           int      `json:"port"`
+	ProdPort       int      `json:"prodPort"`
+	NonProdPort    int      `json:"nonProdPort"`
+	LocalURL       string   `json:"localUrl"`
+	Scheme         string   `json:"scheme"`
+	HostsFileLine  string   `json:"hostsFileLine"`
+	PendingRestart bool     `json:"pendingRestart"`
+	LANMode        bool     `json:"lanMode"`
+	LANURLs        []string `json:"lanUrls"`
+	LANIPs         []string `json:"lanIps"`
+	InviteURL      string   `json:"inviteUrl"`
 }
 
 func buildNetworkSettings(net NetworkProvider) NetworkSettings {
@@ -44,6 +53,10 @@ func buildNetworkSettings(net NetworkProvider) NetworkSettings {
 		Scheme:         net.GetURLScheme(),
 		HostsFileLine:  fmt.Sprintf("127.0.0.1 %s", saved.Host),
 		PendingRestart: pendingRestart,
+		LANMode:        net.IsLANMode(),
+		LANURLs:        net.GetLANURLs(),
+		LANIPs:         net.GetLANIPs(),
+		InviteURL:      net.GetInviteURL(),
 	}
 }