fix(settings): warn when a server share link is generated for loopback

The address picker under "Share this Orca server" defaults to 127.0.0.1,
and its hint rendered as static muted copy that read the same whichever
address was selected. Nothing distinguished the one selection that
produces a link no other device can open, so pairing a second machine
tended to fail only after the link had been copied and pasted.

Make the hint track the selection: loopback gets warning emphasis, any
other address states which host the peer has to reach. Generated links
carry their own warning, keyed to the address the link was actually
minted for rather than the current picker value, so moving the picker
afterwards cannot make the warning lie.

Loopback detection lives in shared/network so the picker and the link
row agree; it covers 127.x, localhost, ::1, and ws(s):// forms. The
warning uses typography and an icon rather than a new color, since a
loopback address is a valid choice and the palette reserves color for
selection, destructive, and git decorations.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: 2 people

src/renderer/src/components/settings/RuntimePairingGeneratorForm.tsx

@@ -1,9 +1,12 @@
-import { Loader2, RefreshCw } from 'lucide-react'
+import { AlertTriangle, Loader2, RefreshCw } from 'lucide-react'
 import { Button } from '../ui/button'
 import { Label } from '../ui/label'
 import { Tooltip, TooltipContent, TooltipTrigger } from '../ui/tooltip'
 import { AddressPicker, type AddressOption } from '../network/AddressPicker'
-import { parseServerShareAddress } from '../../../../shared/network/server-share-address'
+import {
+  isLoopbackShareAddress,
+  parseServerShareAddress
+} from '../../../../shared/network/server-share-address'
 import { GeneratedUrlRow, UnavailableUrlRow } from './RuntimePairingGeneratedUrlRows'
 import { translate } from '@/i18n/i18n'
 
@@ -15,6 +18,7 @@ type RuntimePairingGeneratorFormProps = {
   isGeneratingPairing: boolean
   webClientUrl: string | null
   runtimePairingUrl: string | null
+  generatedAddress: string | null
   copiedTarget: 'web' | 'pairing' | null
   onSelectedAddressChange: (address: string) => void
   onRefreshNetworkInterfaces: () => void
@@ -30,12 +34,15 @@ export function RuntimePairingGeneratorForm({
   isGeneratingPairing,
   webClientUrl,
   runtimePairingUrl,
+  generatedAddress,
   copiedTarget,
   onSelectedAddressChange,
   onRefreshNetworkInterfaces,
   onGenerate,
   onCopy
 }: RuntimePairingGeneratorFormProps): React.JSX.Element {
+  const selectionIsLoopback = isLoopbackShareAddress(selectedAddress)
+  const generatedForLoopback = generatedAddress !== null && isLoopbackShareAddress(generatedAddress)
   const options: AddressOption[] = [
     {
       value: loopbackAddress,
@@ -147,12 +154,23 @@ export function RuntimePairingGeneratorForm({
             </Tooltip>
           </div>
         </div>
-        <p className="text-xs text-muted-foreground">
-          {translate(
-            'auto.components.settings.RuntimePairingUrlGenerator.279e0dcb57',
-            '127.0.0.1 only works on this computer. Use a LAN, Tailscale, or custom address for another device.'
-          )}
-        </p>
+        {selectionIsLoopback ? (
+          <p className="flex items-start gap-1.5 text-xs text-foreground">
+            <AlertTriangle className="mt-0.5 size-3.5 shrink-0" />
+            {translate(
+              'auto.components.settings.RuntimePairingUrlGenerator.279e0dcb57',
+              '127.0.0.1 only works on this computer. Use a LAN, Tailscale, or custom address for another device.'
+            )}
+          </p>
+        ) : (
+          <p className="text-xs text-muted-foreground">
+            {translate(
+              'auto.components.settings.RuntimePairingUrlGenerator.reachable-address-hint',
+              'The other device must be able to reach {{address}}.',
+              { address: selectedAddress }
+            )}
+          </p>
+        )}
         <div className="flex justify-end">
           <Button
             type="button"
@@ -171,6 +189,17 @@ export function RuntimePairingGeneratorForm({
         </div>
       </div>
 
+      {generatedForLoopback && (webClientUrl || runtimePairingUrl) ? (
+        <p className="flex items-start gap-1.5 text-xs text-foreground">
+          <AlertTriangle className="mt-0.5 size-3.5 shrink-0" />
+          {translate(
+            'auto.components.settings.RuntimePairingUrlGenerator.generated-loopback-warning',
+            'These links were generated for {{address}}, so only this computer can open them. Pick a reachable address above and generate again to pair another device.',
+            { address: generatedAddress ?? '' }
+          )}
+        </p>
+      ) : null}
+
       {webClientUrl ? (
         <GeneratedUrlRow
           label={translate(

src/renderer/src/components/settings/RuntimePairingUrlGenerator.tsx

@@ -16,11 +16,15 @@ const runtimePairingUrlCache: {
   runtimePairingUrl: string | null
   webClientUrl: string | null
   runtimePairingDeviceId: string | null
+  generatedAddress: string | null
 } = {
   selectedAddress: LOOPBACK_ADDRESS,
   runtimePairingUrl: null,
   webClientUrl: null,
-  runtimePairingDeviceId: null
+  runtimePairingDeviceId: null,
+  // Why: the picker can move after generating, so the link warning tracks the
+  // address the displayed link was actually minted for.
+  generatedAddress: null
 }
 
 type RuntimePairingUrlGeneratorProps = {
@@ -47,6 +51,9 @@ export function RuntimePairingUrlGenerator({
   const [runtimePairingDeviceId, setRuntimePairingDeviceId] = useState<string | null>(
     runtimePairingUrlCache.runtimePairingDeviceId
   )
+  const [generatedAddress, setGeneratedAddress] = useState<string | null>(
+    runtimePairingUrlCache.generatedAddress
+  )
   const [runtimeAccessGrants, setRuntimeAccessGrants] = useState<RuntimeAccessGrant[]>([])
   const [isLoadingAccessGrants, setIsLoadingAccessGrants] = useState(false)
   const [refreshingNetworkInterfaces, setRefreshingNetworkInterfaces] = useState(false)
@@ -165,10 +172,12 @@ export function RuntimePairingUrlGenerator({
     runtimePairingUrlCache.runtimePairingUrl = null
     runtimePairingUrlCache.webClientUrl = null
     runtimePairingUrlCache.runtimePairingDeviceId = null
+    runtimePairingUrlCache.generatedAddress = null
     if (mountedRef.current) {
       setRuntimePairingUrl(null)
       setWebClientUrl(null)
       setRuntimePairingDeviceId(null)
+      setGeneratedAddress(null)
     }
   }
 
@@ -194,10 +203,12 @@ export function RuntimePairingUrlGenerator({
       runtimePairingUrlCache.runtimePairingUrl = result.pairingUrl
       runtimePairingUrlCache.webClientUrl = result.webClientUrl
       runtimePairingUrlCache.runtimePairingDeviceId = result.deviceId
+      runtimePairingUrlCache.generatedAddress = selectedAddress
       if (mountedRef.current) {
         setRuntimePairingUrl(result.pairingUrl)
         setWebClientUrl(result.webClientUrl)
         setRuntimePairingDeviceId(result.deviceId)
+        setGeneratedAddress(selectedAddress)
       }
       await loadRuntimeAccessGrants()
       if (mountedRef.current) {
@@ -356,6 +367,7 @@ export function RuntimePairingUrlGenerator({
           isGeneratingPairing={isGeneratingPairing}
           webClientUrl={webClientUrl}
           runtimePairingUrl={runtimePairingUrl}
+          generatedAddress={generatedAddress}
           copiedTarget={copiedTarget}
           onSelectedAddressChange={updateSelectedAddress}
           onRefreshNetworkInterfaces={() => void loadNetworkInterfaces({ showToastOnError: true })}

src/renderer/src/i18n/locales/en.json

@@ -6718,7 +6718,9 @@
           "custom-description": "Advertise an address another device can reach — a LAN or Tailscale host, or a full ws(s):// URL.",
           "custom-hint": "Enter a host, host:port, or a ws(s):// URL.",
           "custom-cancel": "Cancel",
-          "custom-use": "Use address"
+          "custom-use": "Use address",
+          "reachable-address-hint": "The other device must be able to reach {{address}}.",
+          "generated-loopback-warning": "These links were generated for {{address}}, so only this computer can open them. Pick a reachable address above and generate again to pair another device."
         },
         "Settings": {
           "3bf149e873": "Project Settings > {{value0}}",

src/renderer/src/i18n/locales/es.json

@@ -6658,7 +6658,9 @@
           "custom-description": "Anuncia una dirección que otro dispositivo pueda alcanzar: un host de LAN o Tailscale, o una URL ws(s):// completa.",
           "custom-hint": "Introduce un host, host:puerto o una URL ws(s)://.",
           "custom-cancel": "Cancelar",
-          "custom-use": "Usar dirección"
+          "custom-use": "Usar dirección",
+          "reachable-address-hint": "The other device must be able to reach {{address}}.",
+          "generated-loopback-warning": "These links were generated for {{address}}, so only this computer can open them. Pick a reachable address above and generate again to pair another device."
         },
         "Settings": {
           "3bf149e873": "Configuración del proyecto > {{value0}}",

src/renderer/src/i18n/locales/ja.json

@@ -6680,7 +6680,9 @@
           "custom-description": "他のデバイスから到達できるアドレスを指定します。LAN や Tailscale のホスト、または完全な ws(s):// URL です。",
           "custom-hint": "ホスト、host:port、または ws(s):// URL を入力してください。",
           "custom-cancel": "キャンセル",
-          "custom-use": "アドレスを使用"
+          "custom-use": "アドレスを使用",
+          "reachable-address-hint": "The other device must be able to reach {{address}}.",
+          "generated-loopback-warning": "These links were generated for {{address}}, so only this computer can open them. Pick a reachable address above and generate again to pair another device."
         },
         "Settings": {
           "3bf149e873": "プロジェクト設定 > {{value0}}",

src/renderer/src/i18n/locales/ko.json

@@ -6643,7 +6643,9 @@
           "custom-description": "다른 기기가 연결할 수 있는 주소를 알립니다. LAN 또는 Tailscale 호스트, 또는 전체 ws(s):// URL입니다.",
           "custom-hint": "호스트, host:port 또는 ws(s):// URL을 입력하세요.",
           "custom-cancel": "취소",
-          "custom-use": "주소 사용"
+          "custom-use": "주소 사용",
+          "reachable-address-hint": "The other device must be able to reach {{address}}.",
+          "generated-loopback-warning": "These links were generated for {{address}}, so only this computer can open them. Pick a reachable address above and generate again to pair another device."
         },
         "Settings": {
           "3bf149e873": "프로젝트 설정 > {{value0}}",

src/renderer/src/i18n/locales/zh.json

@@ -6643,7 +6643,9 @@
           "custom-description": "公布其他设备可以访问的地址：LAN 或 Tailscale 主机，或完整的 ws(s):// URL。",
           "custom-hint": "请输入主机、host:port 或 ws(s):// URL。",
           "custom-cancel": "取消",
-          "custom-use": "使用地址"
+          "custom-use": "使用地址",
+          "reachable-address-hint": "The other device must be able to reach {{address}}.",
+          "generated-loopback-warning": "These links were generated for {{address}}, so only this computer can open them. Pick a reachable address above and generate again to pair another device."
         },
         "Settings": {
           "3bf149e873": "项目设置 > {{value0}}",

src/shared/network/server-share-address.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest'
-import { parseServerShareAddress } from './server-share-address'
+import { isLoopbackShareAddress, parseServerShareAddress } from './server-share-address'
 
 describe('parseServerShareAddress', () => {
   it('accepts a bare hostname or IP', () => {
@@ -35,3 +35,36 @@ describe('parseServerShareAddress', () => {
     expect(parseServerShareAddress('my-host:70000').ok).toBe(false)
   })
 })
+
+describe('isLoopbackShareAddress', () => {
+  it('detects loopback hosts in every accepted address form', () => {
+    for (const address of [
+      '127.0.0.1',
+      '127.1.2.3',
+      '127.0.0.1:6768',
+      'localhost',
+      'LocalHost:6768',
+      '::1',
+      '[::1]',
+      'ws://127.0.0.1:6768',
+      'wss://localhost/runtime'
+    ]) {
+      expect(isLoopbackShareAddress(address), address).toBe(true)
+    }
+  })
+
+  it('leaves routable LAN, tailnet, and public addresses alone', () => {
+    for (const address of [
+      '192.168.1.50',
+      '100.64.0.2',
+      '10.0.0.5:6768',
+      'my-mac.tail-abcd.ts.net',
+      'ws://100.64.0.2:6768',
+      '128.0.0.1',
+      '27.0.0.1',
+      ''
+    ]) {
+      expect(isLoopbackShareAddress(address), address).toBe(false)
+    }
+  })
+})

src/shared/network/server-share-address.ts

@@ -40,3 +40,31 @@ export function parseServerShareAddress(input: string): ParseServerShareAddressR
   }
   return { ok: true, value: trimmed }
 }
+
+// Why: a shared address that resolves to loopback produces a pairing link only
+// this computer can dial, so both the picker and the generated link warn on it.
+export function isLoopbackShareAddress(input: string): boolean {
+  const trimmed = input.trim()
+  if (trimmed === '') {
+    return false
+  }
+
+  let host = trimmed
+  if (/^[a-z]+:\/\//i.test(trimmed)) {
+    try {
+      host = new URL(trimmed).hostname
+    } catch {
+      return false
+    }
+  } else if (HOST_OR_HOST_PORT.test(trimmed) && trimmed.includes(':')) {
+    host = trimmed.slice(0, trimmed.lastIndexOf(':'))
+  }
+
+  const normalized = host.replace(/^\[|\]$/g, '').toLowerCase()
+  return (
+    normalized === 'localhost' ||
+    normalized === '::1' ||
+    normalized === '0:0:0:0:0:0:0:1' ||
+    /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(normalized)
+  )
+}