@camstack/server 0.1.6 → 0.1.8

package/src/api/oauth2/oauth2-routes.ts

@@ -196,7 +196,11 @@ export function registerOauth2Routes(fastify: FastifyInstance, deps: Oauth2Deps)
       username: tokenInfo.username ?? '',
       scopes: descriptor.requestedScopes,
       redirectUri: v.redirectUri,
-      hubUrl: deps.publicHubUrl(),
+      // Prefer the integration's own public origin (e.g. the operator-selected
+      // external-access endpoint surfaced by a forked exporter addon) so the
+      // claim the cloud Lambda routes back on is the reachable public URL, not
+      // the hub-global fallback (which defaults to localhost in dev).
+      hubUrl: descriptor.hubUrl ?? deps.publicHubUrl(),
     })
 
     return reply.redirect(`${v.redirectUri}?code=${encodeURIComponent(code)}&state=${encodeURIComponent(v.state)}`)

package/src/api/trpc/__tests__/client-ip.spec.ts

@@ -0,0 +1,146 @@
+/**
+ * Unit tests for the client-IP extraction + LAN/remote classification
+ * used by the `webrtcSession.createSession` relay-only override.
+ *
+ * The classification is the load-bearing decision: a `true` from
+ * `isRemoteClientIp` forces TURN-relay-only ICE for that live-view
+ * session. A false positive would needlessly relay a LAN viewer
+ * (latency); a false negative would leave a remote viewer on the dead
+ * direct path (the bug being fixed). The private-range edges are
+ * therefore exercised explicitly.
+ */
+import { describe, it, expect } from 'vitest'
+import type { IncomingMessage } from 'node:http'
+import { extractClientIp, extractUserAgent, isRemoteClientIp } from '../client-ip.js'
+
+function reqWith(opts: {
+  xff?: string | string[]
+  ip?: string
+  remoteAddress?: string
+  userAgent?: string | string[]
+}): IncomingMessage {
+  const headers: Record<string, string | string[]> = {}
+  if (opts.xff !== undefined) headers['x-forwarded-for'] = opts.xff
+  if (opts.userAgent !== undefined) headers['user-agent'] = opts.userAgent
+  const req = {
+    headers,
+    socket: { remoteAddress: opts.remoteAddress },
+  } as unknown as IncomingMessage
+  if (opts.ip !== undefined) {
+    Object.defineProperty(req, 'ip', { value: opts.ip, enumerable: true })
+  }
+  return req
+}
+
+describe('extractClientIp', () => {
+  it('returns null for an absent request (mesh-originated call)', () => {
+    expect(extractClientIp(undefined)).toBeNull()
+  })
+
+  it('prefers the first X-Forwarded-For hop over socket/ip', () => {
+    const req = reqWith({ xff: '203.0.113.7, 10.0.0.1', ip: '10.0.0.1', remoteAddress: '10.0.0.1' })
+    expect(extractClientIp(req)).toBe('203.0.113.7')
+  })
+
+  it('handles X-Forwarded-For as an array', () => {
+    const req = reqWith({ xff: ['198.51.100.4, 10.0.0.1'] })
+    expect(extractClientIp(req)).toBe('198.51.100.4')
+  })
+
+  it('falls back to req.ip when no XFF', () => {
+    const req = reqWith({ ip: '192.168.1.50', remoteAddress: '192.168.1.50' })
+    expect(extractClientIp(req)).toBe('192.168.1.50')
+  })
+
+  it('falls back to socket.remoteAddress when no XFF or ip', () => {
+    const req = reqWith({ remoteAddress: '127.0.0.1' })
+    expect(extractClientIp(req)).toBe('127.0.0.1')
+  })
+
+  it('strips IPv4-mapped IPv6 prefix', () => {
+    const req = reqWith({ remoteAddress: '::ffff:192.168.1.5' })
+    expect(extractClientIp(req)).toBe('192.168.1.5')
+  })
+
+  it('strips IPv6 zone id', () => {
+    const req = reqWith({ remoteAddress: 'fe80::1%en0' })
+    expect(extractClientIp(req)).toBe('fe80::1')
+  })
+})
+
+describe('extractUserAgent', () => {
+  it('returns null for an absent request (mesh-originated call)', () => {
+    expect(extractUserAgent(undefined)).toBeNull()
+  })
+
+  it('returns null when the header is missing', () => {
+    expect(extractUserAgent(reqWith({}))).toBeNull()
+  })
+
+  it('reads the user-agent header', () => {
+    const req = reqWith({ userAgent: 'Mozilla/5.0 (Macintosh) Chrome/120' })
+    expect(extractUserAgent(req)).toBe('Mozilla/5.0 (Macintosh) Chrome/120')
+  })
+
+  it('reads the first entry when the header is an array', () => {
+    const req = reqWith({ userAgent: ['Mozilla/5.0 (X11) Firefox/121', 'ignored'] })
+    expect(extractUserAgent(req)).toBe('Mozilla/5.0 (X11) Firefox/121')
+  })
+
+  it('returns null for an empty header value', () => {
+    expect(extractUserAgent(reqWith({ userAgent: '' }))).toBeNull()
+  })
+})
+
+describe('isRemoteClientIp', () => {
+  it('null → false (treated as LAN — safe default)', () => {
+    expect(isRemoteClientIp(null)).toBe(false)
+  })
+
+  // Private / loopback / link-local / Tailscale ranges → LAN (direct path kept)
+  const lan = [
+    '10.0.0.1',
+    '10.255.255.255',
+    '172.16.0.1',
+    '172.31.255.255',
+    '192.168.1.1',
+    '127.0.0.1',
+    '169.254.1.1',
+    // Tailscale CGNAT overlay (100.64.0.0/10) — direct host↔host over the mesh
+    '100.64.0.1', // bottom of 100.64/10
+    '100.104.179.3', // the hub's own Tailscale IP (confirmed live)
+    '100.127.255.255', // top of 100.64/10
+    '::1',
+    'fe80::1',
+    'fc00::1',
+    'fd12:3456::1',
+    // Tailscale ULA overlay (fd7a::/16) — subset of fc00::/7
+    'fd7a:115c:a1e0::1',
+  ]
+  for (const ip of lan) {
+    it(`LAN: ${ip} → not remote`, () => {
+      expect(isRemoteClientIp(ip)).toBe(false)
+    })
+  }
+
+  // Public ranges → remote (relay-only forced)
+  const remote = [
+    '203.0.113.7', // TEST-NET-3 (public)
+    '8.8.8.8',
+    '172.15.0.1', // just below the 172.16/12 private block
+    '172.32.0.1', // just above the 172.16/12 private block
+    '11.0.0.1', // just above 10/8
+    '100.63.255.255', // just below the 100.64/10 Tailscale block (public)
+    '100.128.0.1', // just above the 100.64/10 Tailscale block (public)
+    '2001:4860:4860::8888', // public IPv6
+  ]
+  for (const ip of remote) {
+    it(`remote: ${ip} → remote`, () => {
+      expect(isRemoteClientIp(ip)).toBe(true)
+    })
+  }
+
+  it('unparseable literal → false (conservative LAN default)', () => {
+    expect(isRemoteClientIp('not-an-ip')).toBe(false)
+  })
+})

package/src/api/trpc/__tests__/webrtc-session-ua-enrich.spec.ts

@@ -0,0 +1,128 @@
+/**
+ * Unit tests for the User-Agent enrichment the hub applies to the
+ * `webrtc-session` mount. The hub reads the UA from the tRPC request
+ * context and merges it into the subscriber attribution so the
+ * stream-broker SUBSCRIBERS panel can identify a browser viewer. Any
+ * client-supplied `userAgent` is OVERWRITTEN — the server trusts only the
+ * request context, never the client.
+ */
+import { describe, it, expect, vi } from 'vitest'
+import type { IncomingMessage } from 'node:http'
+import type { InferProvider, BrokerConsumerAttribution } from '@camstack/types'
+import { webrtcSessionCapability } from '@camstack/types'
+import { enrichInputWithUserAgent, wrapWebrtcSessionProviderWithRelay } from '../trpc.router.js'
+import type { TrpcContext } from '../trpc.context.js'
+
+type WebrtcSessionProvider = InferProvider<typeof webrtcSessionCapability>
+
+function reqWithUa(userAgent?: string): IncomingMessage {
+  const headers: Record<string, string | string[]> = {}
+  if (userAgent !== undefined) headers['user-agent'] = userAgent
+  return { headers, socket: {} } as unknown as IncomingMessage
+}
+
+describe('enrichInputWithUserAgent', () => {
+  it('passes input through unchanged when userAgent is null', () => {
+    const input = { deviceId: 1, consumerAttribution: { kind: 'webrtc-browser' } as const }
+    expect(enrichInputWithUserAgent(input, null)).toBe(input)
+  })
+
+  it('merges userAgent into an existing attribution (new object)', () => {
+    const attribution: BrokerConsumerAttribution = { kind: 'webrtc-browser', label: 'alice' }
+    const input = { deviceId: 1, consumerAttribution: attribution }
+    const out = enrichInputWithUserAgent(input, 'Chrome/120')
+    expect(out.consumerAttribution).toEqual({ kind: 'webrtc-browser', label: 'alice', userAgent: 'Chrome/120' })
+    // Immutability: the original attribution is untouched.
+    expect(attribution.userAgent).toBeUndefined()
+  })
+
+  it('defaults to webrtc-browser when no attribution was supplied', () => {
+    const out = enrichInputWithUserAgent({ deviceId: 1 }, 'Firefox/121')
+    expect(out.consumerAttribution).toEqual({ kind: 'webrtc-browser', userAgent: 'Firefox/121' })
+  })
+
+  it('OVERWRITES a client-supplied userAgent (never trust the client)', () => {
+    const input = {
+      deviceId: 1,
+      consumerAttribution: { kind: 'webrtc-browser', userAgent: 'spoofed' } as const,
+    }
+    const out = enrichInputWithUserAgent(input, 'Safari/17')
+    expect(out.consumerAttribution?.userAgent).toBe('Safari/17')
+  })
+})
+
+describe('wrapWebrtcSessionProviderWithRelay — UA enrichment', () => {
+  function mockProvider(): WebrtcSessionProvider {
+    const createSession = vi.fn().mockResolvedValue({ sessionId: 's', sdpOffer: 'o' })
+    const handleOffer = vi.fn().mockResolvedValue({ sessionId: 's', sdpAnswer: 'a' })
+    const passthrough = vi.fn().mockResolvedValue(undefined)
+    return {
+      createSession,
+      handleOffer,
+      listStreams: vi.fn().mockResolvedValue([]),
+      handleAnswer: passthrough,
+      addIceCandidate: passthrough,
+      getIceCandidates: vi.fn().mockResolvedValue({ candidates: [], done: true }),
+      closeSession: passthrough,
+      hasAdaptiveBitrate: vi.fn().mockResolvedValue(false),
+      getSessionState: vi.fn().mockResolvedValue({ pendingRenegotiation: null }),
+    }
+  }
+
+  function ctxWith(userAgent?: string): TrpcContext {
+    return { user: null, req: reqWithUa(userAgent) }
+  }
+
+  it('injects the request UA into createSession attribution', async () => {
+    const provider = mockProvider()
+    const wrapped = wrapWebrtcSessionProviderWithRelay(provider, ctxWith('Edg/120'))
+
+    await wrapped.createSession({ deviceId: 1, target: { kind: 'adaptive' } })
+
+    expect(provider.createSession).toHaveBeenCalledTimes(1)
+    const arg = vi.mocked(provider.createSession).mock.calls[0]![0]
+    expect(arg.consumerAttribution).toEqual({ kind: 'webrtc-browser', userAgent: 'Edg/120' })
+  })
+
+  it('injects the request UA into handleOffer attribution', async () => {
+    const provider = mockProvider()
+    const wrapped = wrapWebrtcSessionProviderWithRelay(provider, ctxWith('CriOS/120'))
+
+    await wrapped.handleOffer({ deviceId: 1, sdpOffer: 'x' })
+
+    const arg = vi.mocked(provider.handleOffer).mock.calls[0]![0]
+    expect(arg.consumerAttribution).toEqual({ kind: 'webrtc-browser', userAgent: 'CriOS/120' })
+  })
+
+  it('overwrites a client-supplied UA on createSession', async () => {
+    const provider = mockProvider()
+    const wrapped = wrapWebrtcSessionProviderWithRelay(provider, ctxWith('TrustedUA/1'))
+
+    await wrapped.createSession({
+      deviceId: 1,
+      target: { kind: 'adaptive' },
+      consumerAttribution: { kind: 'webrtc-browser', userAgent: 'spoofed', label: 'bob' },
+    })
+
+    const arg = vi.mocked(provider.createSession).mock.calls[0]![0]
+    expect(arg.consumerAttribution).toEqual({ kind: 'webrtc-browser', label: 'bob', userAgent: 'TrustedUA/1' })
+  })
+
+  it('does not alter the call when no UA header is present', async () => {
+    const provider = mockProvider()
+    const wrapped = wrapWebrtcSessionProviderWithRelay(provider, ctxWith(undefined))
+
+    await wrapped.createSession({ deviceId: 1, target: { kind: 'adaptive' } })
+
+    const arg = vi.mocked(provider.createSession).mock.calls[0]![0]
+    expect(arg.consumerAttribution).toBeUndefined()
+  })
+
+  it('delegates other methods straight through', async () => {
+    const provider = mockProvider()
+    const wrapped = wrapWebrtcSessionProviderWithRelay(provider, ctxWith('Chrome/120'))
+
+    await wrapped.closeSession({ deviceId: 1, sessionId: 's' })
+    expect(provider.closeSession).toHaveBeenCalledWith({ deviceId: 1, sessionId: 's' })
+  })
+})

package/src/api/trpc/cap-mount-helpers.ts

@@ -92,7 +92,18 @@ export function requireDeviceScoped<K extends keyof CapabilityProviderMap>(
             message: `Capability "${String(capName)}" provider for device ${deviceId} does not implement "${prop}"`,
           })
         }
-        return fn.call(native, input)
+        const result = await fn.call(native, input)
+        // Device-property-wiring overlay (read-time): only `getStatus`, and only
+        // when the device has links for this cap (resolveLinkedStatus returns
+        // null otherwise → base result untouched). One in-process singleton hop.
+        if (prop === 'getStatus') {
+          const deviceManager = registry.getSingleton<{
+            resolveLinkedStatus?: (i: { deviceId: number; cap: string; baseStatus: unknown }) => Promise<Record<string, unknown> | null>
+          }>('device-manager')
+          const overlaid = await deviceManager?.resolveLinkedStatus?.({ deviceId, cap: String(capName), baseStatus: result })
+          if (overlaid != null) return overlaid
+        }
+        return result
       }
     },
   })

package/src/api/trpc/cap-route-error-formatter.ts

@@ -0,0 +1,163 @@
+/**
+ * tRPC error formatter that serializes CapRouteError diagnostic fields
+ * across the server→client boundary.
+ *
+ * tRPC only carries `error.message` by default. This formatter augments
+ * the default shape's `data` block with typed CapRouteError fields so the
+ * admin-UI can read `capRouteReason` instead of substring-matching message text.
+ *
+ * Fields added (all optional — absent when the error is not a CapRouteError):
+ *   - `capRouteReason` — 'no-provider' | 'node-offline' | 'cap-unknown' | 'transport-failed'
+ *   - `capRouteRejected` — array of `{ kind: string; why: string }` route-rejection descriptors
+ *   - `capRouteNodeId` — the target node id, when known
+ *
+ * The formatter is EXPORTED for unit testing (no side-effects, pure function).
+ */
+import { CapRouteError } from '@camstack/kernel'
+import type { RejectedRoute } from '@camstack/kernel'
+import type { TRPCError } from '@trpc/server'
+import type { DefaultErrorShape } from '@trpc/server/unstable-core-do-not-import'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** The augmented data block we attach when a CapRouteError is present. */
+export interface CapRouteErrorData {
+  readonly capRouteReason: string
+  readonly capRouteRejected: readonly RejectedRoute[]
+  readonly capRouteNodeId?: string
+}
+
+export interface AugmentedErrorShape extends DefaultErrorShape {
+  readonly data: DefaultErrorShape['data'] & Partial<CapRouteErrorData>
+}
+
+// ---------------------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------------------
+
+/** Known CapRouteError reason values — used as a runtime safety rail. */
+const KNOWN_REASONS = new Set<string>(['no-provider', 'node-offline', 'cap-unknown', 'transport-failed'])
+
+/** Narrows a plain string to the `CapRouteError['reason']` union. */
+function isCapRouteReason(r: string): r is CapRouteError['reason'] {
+  return KNOWN_REASONS.has(r)
+}
+
+/** Narrows an `unknown` value to `RejectedRoute` by checking structural shape. */
+function isRejectedRoute(r: unknown): r is RejectedRoute {
+  if (typeof r !== 'object' || r === null) return false
+  const kind: unknown = Reflect.get(r, 'kind')
+  const why: unknown = Reflect.get(r, 'why')
+  return typeof kind === 'string' && typeof why === 'string'
+}
+
+// ---------------------------------------------------------------------------
+// CapRouteError extraction helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Walks the `.cause` chain of an error to find a CapRouteError.
+ * Returns the first one found, or null.
+ *
+ * Detection is dual-mode:
+ *   1. `instanceof CapRouteError` — works when the same module is loaded.
+ *   2. Duck-type: `name === 'CapRouteError'` + `typeof reason === 'string'`
+ *      — robust against module-boundary issues (self-contained addons).
+ */
+function extractCapRouteError(err: unknown): CapRouteError | null {
+  let current: unknown = err
+  for (let depth = 0; depth < 8; depth++) {
+    if (current === null || current === undefined) return null
+
+    if (current instanceof CapRouteError) {
+      return current
+    }
+
+    // Duck-type fallback: err.name + err.reason field present
+    if (typeof current === 'object' && Reflect.get(current, 'name') === 'CapRouteError') {
+      const rawReason: unknown = Reflect.get(current, 'reason')
+      if (typeof rawReason === 'string') {
+        // Runtime safety: reject unrecognised reason strings so the formatter
+        // only promotes values it knows are valid CapRouteError reasons.
+        if (!isCapRouteReason(rawReason)) {
+          // Unrecognised reason — treat as a non-CapRouteError and keep walking
+          const cause: unknown = Reflect.get(current, 'cause')
+          if (cause === current) return null
+          current = cause
+          continue
+        }
+        const reason: CapRouteError['reason'] = rawReason
+
+        const rawRejected: unknown = Reflect.get(current, 'rejected')
+        const rejected: readonly RejectedRoute[] = Array.isArray(rawRejected)
+          ? rawRejected.filter(isRejectedRoute)
+          : []
+
+        const nodeId: unknown = Reflect.get(current, 'nodeId')
+        const message: unknown = Reflect.get(current, 'message')
+        const rawCapName: unknown = Reflect.get(current, 'capName')
+        const capName: string = typeof rawCapName === 'string' ? rawCapName : '(unknown)'
+
+        // Build a minimal object with the same shape — enough for the formatter.
+        const synthetic = Object.assign(new CapRouteError(capName, undefined, {
+          reason,
+          rejected,
+          ...(typeof nodeId === 'string' ? { nodeId } : {}),
+        }), {
+          // Override message from the original if available
+          message: typeof message === 'string' ? message : '(duck-typed CapRouteError)',
+        })
+        return synthetic
+      }
+    }
+
+    // Walk the cause chain
+    if (typeof current !== 'object') return null
+    const cause: unknown = Reflect.get(current, 'cause')
+    if (cause === current) return null // Guard against circular refs
+    current = cause
+  }
+  return null
+}
+
+// ---------------------------------------------------------------------------
+// Formatter — exported for unit tests
+// ---------------------------------------------------------------------------
+
+export interface FormatTrpcErrorOpts {
+  readonly error: TRPCError
+  readonly shape: DefaultErrorShape
+}
+
+/**
+ * Augments the default tRPC error shape with CapRouteError diagnostic fields
+ * when the thrown error (or any error in its `.cause` chain) is a CapRouteError.
+ * Returns the shape unchanged for all other errors.
+ */
+export function formatTrpcError(opts: FormatTrpcErrorOpts): AugmentedErrorShape {
+  const { error, shape } = opts
+
+  // extractCapRouteError already walks the full .cause chain, so a single call
+  // starting from `error` covers both `error instanceof CapRouteError` and
+  // `error.cause` (and deeper nesting). No second call needed.
+  const capRouteError = extractCapRouteError(error)
+  if (capRouteError === null) {
+    return { ...shape, data: { ...shape.data } }
+  }
+
+  const extraData: CapRouteErrorData = {
+    capRouteReason: capRouteError.reason,
+    capRouteRejected: capRouteError.rejected,
+    ...(capRouteError.nodeId !== undefined ? { capRouteNodeId: capRouteError.nodeId } : {}),
+  }
+
+  return {
+    ...shape,
+    data: {
+      ...shape.data,
+      ...extraData,
+    },
+  }
+}

package/src/api/trpc/client-ip.ts

@@ -0,0 +1,147 @@
+/**
+ * Client-IP extraction + LAN/remote classification for the tRPC layer.
+ *
+ * Used by the `webrtcSession.createSession` override to decide whether a
+ * live-view session should force TURN-relay-only ICE: a viewer behind
+ * CGNAT/4G (a non-LAN source IP) only ever offers a relay candidate, so
+ * the broker must offer a genuinely relay-only SDP (the patched werift
+ * emits one under `iceTransportPolicy:'relay'`) to get a clean
+ * relay↔relay media path. LAN viewers (private/loopback source IP) keep
+ * the low-latency direct host/srflx path. The SERVER computes this — the
+ * client never sends a relay-only flag.
+ */
+import type { FastifyRequest } from 'fastify'
+import type { IncomingMessage } from 'node:http'
+
+export type ClientRequest = FastifyRequest | IncomingMessage
+
+/**
+ * Best-effort extraction of the originating client IP from a tRPC
+ * request. Order of preference:
+ *   1. `X-Forwarded-For` first hop (when behind a reverse proxy — the
+ *      hub is typically fronted by Caddy/nginx/Cloudflare for remote
+ *      access, so the socket peer is the proxy, not the viewer).
+ *   2. Fastify's `req.ip` (already proxy-aware when `trustProxy` is on).
+ *   3. The raw socket remote address.
+ *
+ * Returns `null` when no address can be determined (e.g. mesh-originated
+ * calls that carry no HTTP request) — the caller treats `null` as "not
+ * remote" so the LAN/direct path stays the safe default.
+ */
+export function extractClientIp(req: ClientRequest | undefined): string | null {
+  if (!req) return null
+
+  // 1. X-Forwarded-For — comma-separated list, client is the FIRST entry.
+  const xff = req.headers['x-forwarded-for']
+  const xffValue = Array.isArray(xff) ? xff[0] : xff
+  if (typeof xffValue === 'string' && xffValue.length > 0) {
+    const first = xffValue.split(',')[0]?.trim()
+    if (first) return normalizeIp(first)
+  }
+
+  // 2. Fastify's parsed `req.ip` (honours `trustProxy` config).
+  if ('ip' in req && typeof req.ip === 'string' && req.ip.length > 0) {
+    return normalizeIp(req.ip)
+  }
+
+  // 3. Raw socket peer (WS / IncomingMessage path).
+  const remote = req.socket?.remoteAddress
+  if (typeof remote === 'string' && remote.length > 0) {
+    return normalizeIp(remote)
+  }
+
+  return null
+}
+
+/**
+ * Best-effort read of the originating client's `User-Agent` header. Both
+ * request shapes in the union (`FastifyRequest` and the raw WS-transport
+ * `IncomingMessage`) expose `.headers['user-agent']`. Returns `null` when
+ * absent (mesh-originated calls carry no HTTP request, and some clients
+ * omit the header). Used by the `webrtc-session` mount to tag a browser
+ * subscriber's broker attribution with the viewer's UA — the SERVER reads
+ * it from the request context; any client-supplied value is ignored.
+ */
+export function extractUserAgent(req: ClientRequest | undefined): string | null {
+  if (!req) return null
+  const ua = req.headers['user-agent']
+  const value = Array.isArray(ua) ? ua[0] : ua
+  if (typeof value === 'string' && value.length > 0) return value
+  return null
+}
+
+/**
+ * Strip an IPv4-mapped IPv6 prefix (`::ffff:192.168.1.5` → `192.168.1.5`)
+ * and any zone id (`fe80::1%en0` → `fe80::1`) so the range checks below
+ * see a clean address.
+ */
+function normalizeIp(ip: string): string {
+  let out = ip.trim()
+  if (out.startsWith('::ffff:')) out = out.slice('::ffff:'.length)
+  const pct = out.indexOf('%')
+  if (pct !== -1) out = out.slice(0, pct)
+  return out
+}
+
+/**
+ * True when the address is NOT in a private / loopback / link-local /
+ * Tailscale range — i.e. an internet (remote) viewer. Covers IPv4
+ * (10/8, 172.16/12, 192.168/16, 127/8, 100.64/10 Tailscale CGNAT) and
+ * IPv6 (::1, fc00::/7 unique-local, fe80::/10 link-local — fd7a::/16
+ * Tailscale ULA is a subset of fc00::/7 and is therefore already
+ * covered).
+ *
+ * Tailscale clients (the 100.64.0.0/10 CGNAT overlay or the fd7a::/16
+ * ULA overlay) are deliberately classified LOCAL: over the Tailscale
+ * mesh BOTH peers sit on the 100.x / fd7a:: overlay and are mutually
+ * reachable, so the broker offers ALL candidates (host/srflx/relay)
+ * — including the hub's Tailscale host candidate — and a direct
+ * host↔host pair wins ICE with native (non-re-encoded) media. Forcing
+ * relay-only for Tailscale would push them onto the broken relay path.
+ *
+ * Unparseable or null addresses return `false` (treated as LAN — the
+ * safe default that preserves the existing direct path).
+ */
+export function isRemoteClientIp(ip: string | null): boolean {
+  if (!ip) return false
+  if (ip.includes(':')) return !isPrivateIpv6(ip)
+  if (isIpv4(ip)) return !isPrivateIpv4(ip)
+  // Not a recognisable IP literal — be conservative, treat as LAN.
+  return false
+}
+
+function isIpv4(ip: string): boolean {
+  const parts = ip.split('.')
+  if (parts.length !== 4) return false
+  return parts.every((p) => {
+    if (!/^\d{1,3}$/.test(p)) return false
+    const n = Number.parseInt(p, 10)
+    return n >= 0 && n <= 255
+  })
+}
+
+function isPrivateIpv4(ip: string): boolean {
+  const parts = ip.split('.').map((p) => Number.parseInt(p, 10))
+  const [a, b] = parts
+  if (a === undefined || b === undefined) return false
+  if (a === 10) return true // 10.0.0.0/8
+  if (a === 127) return true // 127.0.0.0/8 loopback
+  if (a === 172 && b >= 16 && b <= 31) return true // 172.16.0.0/12
+  if (a === 192 && b === 168) return true // 192.168.0.0/16
+  if (a === 169 && b === 254) return true // 169.254.0.0/16 link-local
+  // 100.64.0.0/10 — Tailscale CGNAT overlay (100.64.0.0 – 100.127.255.255).
+  // Both Tailscale peers are mutually reachable on this overlay, so treat
+  // it as local (direct host↔host pair, no relay).
+  if (a === 100 && b >= 64 && b <= 127) return true
+  return false
+}
+
+function isPrivateIpv6(ip: string): boolean {
+  const lower = ip.toLowerCase()
+  if (lower === '::1') return true // loopback
+  if (lower === '::') return true // unspecified
+  if (lower.startsWith('fe80')) return true // fe80::/10 link-local
+  // fc00::/7 unique-local — covers fc.. and fd..
+  if (lower.startsWith('fc') || lower.startsWith('fd')) return true
+  return false
+}