@camstack/server 0.1.6 → 0.1.7

package/src/api/core/bulk-update-coordinator.ts

@@ -0,0 +1,302 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-argument -- The server installs @camstack/types@0.1.38 (last published) in server/backend/node_modules, while the workspace has 0.1.39 with the new BulkUpdate* types. ESLint's type-checker resolves against 0.1.38 and treats the new imports as `any`. Runtime is correct because Node module resolution walks up to root node_modules → workspace symlink. This disable mirrors the pattern in cap-providers.ts (same root cause). Will resolve when 0.1.39 is published and the local dist is synced. */
+import { randomUUID } from 'node:crypto'
+import {
+  EventCategory,
+  type BulkUpdateItem,
+  type BulkUpdateState,
+  type BulkUpdatePhase,
+  type BulkUpdateItemStatus,
+} from '@camstack/types'
+
+/**
+ * Narrow event-bus interface required by BulkUpdateCoordinator.
+ * Intentionally narrower than IEventBus: the coordinator only emits a single
+ * topic, so we avoid importing the full IEventBus (which lives in @camstack/types
+ * and would pull in all event-catalog types). The full IEventBus satisfies this
+ * interface structurally, so wiring in cap-providers.ts is cast-free.
+ */
+export interface IBulkUpdateEventBus {
+  emit(category: EventCategory.AddonsBulkUpdateProgress, payload: BulkUpdateState): void
+}
+
+export interface IBulkUpdateLogger {
+  info(message: string, ...args: unknown[]): void
+  warn(message: string, ...args: unknown[]): void
+  error(message: string, ...args: unknown[]): void
+  debug(message: string, ...args: unknown[]): void
+}
+
+export interface BulkUpdateCoordinatorDeps {
+  readonly eventBus: IBulkUpdateEventBus
+  readonly updateAddon: (input: { name: string; version: string }) => Promise<void>
+  readonly updateFrameworkPackage: (input: { packageName: string; version: string; deferRestart: boolean }) => Promise<void>
+  readonly restartServer: (input: { confirm: true }) => Promise<void>
+  readonly logger: IBulkUpdateLogger
+  /** Injectable clock for tests. Default: `() => Date.now()`. */
+  readonly clock?: () => number
+  /** How long to keep completed state before purging. Default: 5 minutes. */
+  readonly cleanupAfterMs?: number
+}
+
+export interface StartBulkUpdateInput {
+  readonly nodeId: string
+  readonly items: readonly { name: string; version: string; isSystem: boolean }[]
+}
+
+const DEFAULT_CLEANUP_AFTER_MS = 5 * 60 * 1_000
+
+export class BulkUpdateCoordinator {
+  private readonly states = new Map<string, BulkUpdateState>()
+  private readonly cancelFlags = new Map<string, { cancelled: boolean }>()
+  /**
+   * Tracks wall-clock time (ms) when each bulk completed. Used for lazy
+   * cleanup in `get()` — avoids scheduling a fake-timer `setTimeout` that
+   * would be eagerly fired by `vi.runAllTimersAsync()` in tests.
+   */
+  private readonly completedWallMs = new Map<string, number>()
+  /** Tracks which nodeIds currently have an active (non-completed) bulk update. */
+  private readonly activeNodeIds = new Set<string>()
+
+  private readonly now: () => number
+  private readonly cleanupAfterMs: number
+  /** Wall-clock source. Fake timers intercept `Date.now`, so tests can advance via `advanceTimersByTimeAsync`. */
+  private readonly wallNow: () => number
+
+  constructor(private readonly deps: BulkUpdateCoordinatorDeps) {
+    this.now = deps.clock ?? (() => Date.now())
+    this.cleanupAfterMs = deps.cleanupAfterMs ?? DEFAULT_CLEANUP_AFTER_MS
+    this.wallNow = () => Date.now()
+  }
+
+  // ── Public API ────────────────────────────────────────────────────
+
+  start(input: StartBulkUpdateInput): { id: string } {
+    if (this.activeNodeIds.has(input.nodeId)) {
+      throw new Error(`Bulk update already in progress for node ${input.nodeId}`)
+    }
+
+    const id = randomUUID()
+
+    const items: BulkUpdateItem[] = input.items.map(i => ({
+      name: i.name,
+      isSystem: i.isSystem,
+      // fromVersion: the cap interface receives name+version+isSystem only;
+      // the caller (cap-providers.ts) may enrich this with the current version
+      // if available. Empty string is acceptable per plan spec.
+      fromVersion: '',
+      toVersion: i.version,
+      status: 'queued' as BulkUpdateItemStatus,
+    }))
+
+    const state: BulkUpdateState = {
+      id,
+      nodeId: input.nodeId,
+      startedAtMs: this.now(),
+      total: items.length,
+      completed: 0,
+      failed: 0,
+      current: null,
+      phase: 'regular',
+      cancelled: false,
+      items,
+    }
+
+    this.states.set(id, state)
+    this.activeNodeIds.add(input.nodeId)
+
+    const cancelFlag = { cancelled: false }
+    this.cancelFlags.set(id, cancelFlag)
+
+    // Emit initial state so clients see the bulk as started immediately
+    this.emit(state)
+
+    void this.runLoop(id, cancelFlag).catch(err => {
+      this.deps.logger.error('BulkUpdateCoordinator: loop crashed unexpectedly', err)
+    })
+
+    return { id }
+  }
+
+  get(id: string): BulkUpdateState | null {
+    const state = this.states.get(id)
+    if (state === undefined) return null
+    // Lazy cleanup: purge if the wall-clock elapsed since completion exceeds threshold.
+    // This avoids scheduling a long-lived setTimeout that would be eagerly fired
+    // by vi.runAllTimersAsync() in tests.
+    const completedWall = this.completedWallMs.get(id)
+    if (completedWall !== undefined && this.wallNow() - completedWall >= this.cleanupAfterMs) {
+      this.purge(id)
+      return null
+    }
+    return state
+  }
+
+  list(nodeId?: string): readonly BulkUpdateState[] {
+    const all = [...this.states.keys()]
+      .map(id => this.get(id))                // get() applies lazy-cleanup
+      .filter((s): s is BulkUpdateState => s !== null)
+    return nodeId === undefined ? all : all.filter(s => s.nodeId === nodeId)
+  }
+
+  cancel(id: string): { cancelled: boolean } {
+    const state = this.states.get(id)
+    const flag = this.cancelFlags.get(id)
+    if (state === undefined || flag === undefined) return { cancelled: false }
+    // Once restarting, the hub restart is committed — cancel has no effect.
+    if (state.phase === 'restarting') return { cancelled: false }
+    // Already completed.
+    if (state.completedAtMs !== undefined) return { cancelled: false }
+
+    flag.cancelled = true
+    this.mutate(id, s => ({ ...s, cancelled: true }))
+    return { cancelled: true }
+  }
+
+  // ── Internal loop ─────────────────────────────────────────────────
+
+  private async runLoop(id: string, cancelFlag: { cancelled: boolean }): Promise<void> {
+    const initial = this.states.get(id)!
+
+    // ── Phase 1: regular addons ──────────────────────────────────────
+    this.transitionPhase(id, 'regular')
+
+    for (const item of initial.items.filter(i => !i.isSystem)) {
+      if (cancelFlag.cancelled) break
+      await this.processItem(id, item, false)
+    }
+
+    // ── Phase 2: system packages (deferRestart: true) ────────────────
+    if (!cancelFlag.cancelled && initial.items.some(i => i.isSystem)) {
+      this.transitionPhase(id, 'system')
+
+      for (const item of initial.items.filter(i => i.isSystem)) {
+        if (cancelFlag.cancelled) break
+        await this.processItem(id, item, true)
+      }
+
+      // ── Phase 3: single restart ──────────────────────────────────
+      const anySystemPendingRestart = this.states.get(id)!.items.some(
+        i => i.isSystem && i.status === 'done-pending-restart',
+      )
+
+      if (anySystemPendingRestart && !cancelFlag.cancelled) {
+        this.transitionPhase(id, 'restarting')
+        try {
+          await this.deps.restartServer({ confirm: true })
+          // NOTE: In production, restartServer kills+respawns the hub process.
+          // Code below this point will not execute in that scenario.
+          // If the mock/stub returns (e.g. in tests), we fall through to finalizing.
+        } catch (err) {
+          // Restart failed but the npm installs already completed. Promote all
+          // done-pending-restart items to done with a caveat error so the UI
+          // can inform the user that a manual restart is needed.
+          this.deps.logger.error('BulkUpdateCoordinator: restart failed', err)
+          const errMsg = err instanceof Error ? err.message : String(err)
+          for (const it of this.states.get(id)!.items) {
+            if (it.status === 'done-pending-restart') {
+              this.setItemStatus(id, it.name, 'done', {
+                error: `Restart failed; manual restart required (${errMsg})`,
+              })
+            }
+          }
+        }
+      }
+    }
+
+    // ── Phase 4: finalize ────────────────────────────────────────────
+    // Reached when:
+    //  a) no system packages at all, OR
+    //  b) restart failed (process continued), OR
+    //  c) cancelled before the restart phase.
+    this.transitionPhase(id, 'finalizing')
+    this.completeBulk(id)
+  }
+
+  private async processItem(id: string, item: BulkUpdateItem, isSystem: boolean): Promise<void> {
+    this.setItemStatus(id, item.name, 'updating', { startedAtMs: this.now() })
+    this.mutate(id, s => ({ ...s, current: item.name }))
+    this.emit(this.states.get(id)!)
+
+    try {
+      if (isSystem) {
+        await this.deps.updateFrameworkPackage({
+          packageName: item.name,
+          version: item.toVersion,
+          deferRestart: true,
+        })
+        this.setItemStatus(id, item.name, 'done-pending-restart', { completedAtMs: this.now() })
+      } else {
+        await this.deps.updateAddon({ name: item.name, version: item.toVersion })
+        this.setItemStatus(id, item.name, 'done', { completedAtMs: this.now() })
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      this.setItemStatus(id, item.name, 'failed', { error: msg, completedAtMs: this.now() })
+    }
+
+    this.mutate(id, s => ({ ...s, current: null }))
+    this.emit(this.states.get(id)!)
+  }
+
+  // ── State mutation helpers ────────────────────────────────────────
+
+  private setItemStatus(
+    id: string,
+    name: string,
+    status: BulkUpdateItemStatus,
+    fields: { error?: string; startedAtMs?: number; completedAtMs?: number } = {},
+  ): void {
+    this.mutate(id, s => {
+      const items = s.items.map(it =>
+        it.name === name ? { ...it, status, ...fields } : it,
+      )
+      // completed = all terminal states: done | done-pending-restart | failed
+      const completed = items.filter(
+        it => it.status === 'done' || it.status === 'done-pending-restart' || it.status === 'failed',
+      ).length
+      const failed = items.filter(it => it.status === 'failed').length
+      return { ...s, items, completed, failed }
+    })
+  }
+
+  private transitionPhase(id: string, phase: BulkUpdatePhase): void {
+    this.mutate(id, s => ({ ...s, phase }))
+    this.emit(this.states.get(id)!)
+  }
+
+  private completeBulk(id: string): void {
+    this.mutate(id, s => ({ ...s, completedAtMs: this.now(), current: null }))
+    this.emit(this.states.get(id)!)
+
+    // Free the nodeId slot so a new bulk for the same node can be started
+    const nodeId = this.states.get(id)!.nodeId
+    this.activeNodeIds.delete(nodeId)
+
+    // Record wall-clock completion time for lazy cleanup in `get()`.
+    // We intentionally avoid scheduling a setTimeout here: a long-lived
+    // setTimeout (5 min) would be eagerly fired by vi.runAllTimersAsync()
+    // in tests, causing `get()` to return null immediately after the run.
+    // Instead, `get()` lazily checks whether the cleanup threshold has
+    // elapsed using Date.now() — which fake timers DO advance via
+    // advanceTimersByTimeAsync(), making the cleanup testable without
+    // a long-running timer.
+    this.completedWallMs.set(id, this.wallNow())
+  }
+
+  private purge(id: string): void {
+    this.states.delete(id)
+    this.cancelFlags.delete(id)
+    this.completedWallMs.delete(id)
+  }
+
+  /** Immutably update the state for the given id. No-op if id is unknown. */
+  private mutate(id: string, update: (s: BulkUpdateState) => BulkUpdateState): void {
+    const current = this.states.get(id)
+    if (current === undefined) return
+    this.states.set(id, update(current))
+  }
+
+  private emit(state: BulkUpdateState): void {
+    this.deps.eventBus.emit(EventCategory.AddonsBulkUpdateProgress, state)
+  }
+}

package/src/api/core/cap-providers.ts

@@ -58,6 +58,8 @@ import type { AddonPackageService } from '../../core/addon/addon-package.service
 import type { NetworkQualityService } from '../../core/network/network-quality.service'
 import type { ConfigService } from '../../core/config/config.service'
 import { persistCollectionDisabled } from './collection-preference.js'
+import { BulkUpdateCoordinator } from './bulk-update-coordinator.js'
+import { FRAMEWORK_PACKAGE_ALLOWLIST } from '../../core/addon/addon-package.service.js'
 
 const execFileAsync = promisify(execFile)
 
@@ -477,9 +479,17 @@ export function buildNodesProvider(
       return reg.getGraph({ windowSeconds: input.windowSeconds, nowMs: Date.now() })
     },
     setProcessLogLevel: async (input) => {
-      await broker.call('$node-mgmt.setLogLevel', {
-        level: input.level,
-      }, { nodeID: input.nodeId, timeout: 5_000 })
+      // E2: for hub-local children, try the UDS path first (fire-and-forget);
+      // fall back to the Moleculer $node-mgmt.setLogLevel action for remote
+      // nodes (agents) that still run a per-node broker. The UDS path is always
+      // attempted for hub/<runner> nodeIds even when the Moleculer path would
+      // also work — both are safe to run in parallel during Phase E.
+      const reachedViaUds = moleculer.setChildLogLevelByNodeId(input.nodeId, input.level)
+      if (!reachedViaUds) {
+        await broker.call('$node-mgmt.setLogLevel', {
+          level: input.level,
+        }, { nodeID: input.nodeId, timeout: 5_000 })
+      }
       return { success: true }
     },
     executeQuery: async (input) => {
@@ -806,8 +816,45 @@ export function buildAddonsProvider(
   moleculer: MoleculerService,
   configService: ConfigService,
   ctx: TrpcContext,
+  eb: EventBusService,
 ): IAddonsProvider {
   const broker = moleculer.broker as unknown as BrokerLike
+
+  // Adapt the hub EventBusService (which takes a full SystemEvent object) to
+  // the IBulkUpdateEventBus interface (which takes (category, payload) pairs).
+  // Using `import { EventCategory }` from @camstack/types avoids a new import
+  // — it is already resolved in the generated-cap-routers layer above. The
+  // `eb.emit` overload that takes a TypedSystemEvent is the type-safe path.
+  const bulkEventBus = {
+    emit: (category: Parameters<typeof eb.emit>[0]['category'], payload: unknown) => {
+      eb.emit({
+        id: randomUUID(),
+        timestamp: new Date(),
+        source: { type: 'core', id: 'bulk-update-coordinator' },
+        category,
+        data: payload as Record<string, unknown>,
+      })
+    },
+  }
+
+  const bulkCoordinator = new BulkUpdateCoordinator({
+    eventBus: bulkEventBus,
+    updateAddon: async (i) => { await ps.updatePackage(i.name, i.version) },
+    updateFrameworkPackage: async (i) => {
+      await ps.updateFrameworkPackage({
+        packageName: i.packageName,
+        version: i.version,
+        deferRestart: i.deferRestart,
+      })
+    },
+    restartServer: async () => {
+      await ps.restartServer(ctx.user?.username ?? ctx.user?.id)
+    },
+    logger: ls.createLogger('bulk-update'),
+  })
+
+  const frameworkAllowSet = new Set<string>(FRAMEWORK_PACKAGE_ALLOWLIST)
+
   return {
     list: async () => {
       const rollbackable = ps.getRollbackablePackages()
@@ -843,9 +890,10 @@ export function buildAddonsProvider(
     },
     listUpdates: async (input) => {
       const nodeId = input.nodeId
-      if (nodeId === undefined || isHubNode(nodeId)) return ps.checkUpdates()
-      const installed = await fetchAgentInstalledPackages(broker, nodeId)
-      return ps.checkUpdatesForInstalled(installed)
+      const updates = nodeId === undefined || isHubNode(nodeId)
+        ? await ps.checkUpdates()
+        : await ps.checkUpdatesForInstalled(await fetchAgentInstalledPackages(broker, nodeId))
+      return updates.map(u => ({ ...u, isSystem: frameworkAllowSet.has(u.name) }))
     },
     updatePackage: async (input) => {
       const nodeId = input.nodeId
@@ -937,6 +985,7 @@ export function buildAddonsProvider(
         : ctx.user?.id !== undefined
           ? { requestedBy: ctx.user.id }
           : {}),
+      ...(input.deferRestart !== undefined ? { deferRestart: input.deferRestart } : {}),
     }),
     getVersions: async (input) => ps.getPackageVersions(input.name),
     restartAddon: async (input) => ar.restartAddon(input.addonId),
@@ -955,6 +1004,10 @@ export function buildAddonsProvider(
       }
       return { success: true as const }
     },
+    startBulkUpdate: async (input) => bulkCoordinator.start(input),
+    getBulkUpdateState: async ({ id }) => bulkCoordinator.get(id),
+    cancelBulkUpdate: async ({ id }) => bulkCoordinator.cancel(id),
+    listActiveBulkUpdates: async ({ nodeId }) => bulkCoordinator.list(nodeId),
     custom: async (input) => {
       const registry = ar.getCustomActionRegistry()
       const entry = registry.resolve(input.addonId, input.action)

package/src/api/core/capabilities.router.ts

@@ -28,12 +28,35 @@ export function createCapabilitiesRouter(
       }),
 
     setActiveSingleton: adminProcedure
-      .input(z.object({ capability: z.string(), addonId: z.string() }))
+      .input(z.object({
+        capability: z.string(),
+        addonId: z.string(),
+        nodeId: z.string().optional(),
+      }))
       .output(z.void())
       .mutation(async ({ input }) => {
         if (!registry) throw new Error('Capability registry unavailable')
-        await registry.setActiveSingleton(input.capability, input.addonId)
-        config.update('capabilities', { [input.capability]: input.addonId })
+        await registry.setActiveSingleton(input.capability, input.addonId, input.nodeId)
+        if (input.nodeId !== undefined) {
+          // Per-node override: persist under the node-qualified key so the boot
+          // restorer (`setNodeConfigReader`) replays it on restart.
+          config.set(`capabilities.singletonNode.${input.capability}.${input.nodeId}`, input.addonId)
+        } else {
+          // Cluster-global default: persist to the SAME key the boot restorer reads
+          // (addon-registry `setConfigReader` → `capabilities.singleton.<cap>`).
+          config.set(`capabilities.singleton.${input.capability}`, input.addonId)
+        }
+      }),
+
+    clearSingletonNodeOverride: adminProcedure
+      .input(z.object({ capability: z.string(), nodeId: z.string() }))
+      .output(z.void())
+      .mutation(({ input }) => {
+        if (!registry) throw new Error('Capability registry unavailable')
+        registry.clearSingletonNodeOverride(input.capability, input.nodeId)
+        // Persist the cleared state as null so the boot restorer doesn't re-apply
+        // a stale override on restart.
+        config.set(`capabilities.singletonNode.${input.capability}.${input.nodeId}`, null)
       }),
 
     /**

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,120 @@
+/**
+ * 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, isRemoteClientIp } from '../client-ip.js'
+
+function reqWith(opts: {
+  xff?: string | string[]
+  ip?: string
+  remoteAddress?: string
+}): IncomingMessage {
+  const headers: Record<string, string | string[]> = {}
+  if (opts.xff !== undefined) headers['x-forwarded-for'] = opts.xff
+  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('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)
+  })
+})