@fibscope/agent 0.1.1 → 0.1.3

package/.env.example

@@ -5,3 +5,5 @@ FIBSCOPE_AGENT_CHAIN=testnet
 FIBSCOPE_AGENT_FIBER_RPC_URL=http://127.0.0.1:8227
 FIBSCOPE_AGENT_PUSH_INTERVAL_MS=15000
 FIBSCOPE_AGENT_PUBLIC_PROFILE=false
+# Optional override; by default the agent discovers its own public IPv4.
+# FIBSCOPE_AGENT_PUBLIC_IP=54.179.226.154

package/README.md

@@ -32,7 +32,6 @@ The agent also supports `.fiber/agent.json`:
   "agentToken": "raw-token-issued-by-platform",
   "chain": "testnet",
   "fiberRpcUrl": "http://127.0.0.1:8247",
-  "peerAddress": "/ip4/127.0.0.1/tcp/8248",
   "pushIntervalMs": 15000,
   "publicProfileEnabled": true,
   "overwriteNodeRegistration": false,
@@ -49,7 +48,7 @@ The agent also supports `.fiber/agent.json`:
 }
 ```
 
-`peerAddress` is the Fiber dial address advertised to Fibscope for public routing and channel creation. For local duo development this is usually a loopback multiaddr like `/ip4/127.0.0.1/tcp/8228`; for an internet-facing public node, set it to an address other nodes can actually dial.
+The agent discovers its own public IPv4 through `https://api.ipify.org`, combines it with the local FNN P2P port, and includes both the IP and resulting public multiaddr in registration and report requests. Loopback, wildcard, private, and documentation addresses are never published. Set `FIBSCOPE_AGENT_PUBLIC_IP` only when intentionally overriding automatic discovery, or `FIBSCOPE_AGENT_PUBLIC_IP_URL` to use another compatible JSON or plain-text discovery endpoint.
 
 ## Commands
 
@@ -75,9 +74,11 @@ The agent pushes to `POST /agent/v1/report` with:
 
 ```json
 {
-  "agentVersion": "0.1.1",
+  "agentVersion": "0.1.3",
   "chain": "testnet",
   "collectedAt": 1710000000000,
+  "publicIp": "54.179.226.154",
+  "peerAddress": "/ip4/54.179.226.154/tcp/8228",
   "node": {},
   "peers": [],
   "channels": [],
@@ -117,10 +118,8 @@ The Agent Setup page generates this command from a masked password field. The `f
 
 ## NPM Usage
 
-```powershell
-npm install -g @fibscope/agent
-agent init
-agent start
+```bash
+npm install -g @fibscope/agent pm2 && agent init && pm2 start "$(command -v agent)" --name fibscope-agent --interpreter node -- start && pm2 save
 ```
 
 Or run without a global install:

package/index.mjs

@@ -31,14 +31,17 @@ import { createTelemetryCollector } from "./lib/observe/collector.mjs";
 import { recommend } from "./lib/bridge/recommendation.mjs";
 import { virtualizePayment } from "./lib/route/route.mjs";
 import { chooseFnnInstance, describeFnnInstance, discoverFnnInstances, rpcResponds } from "./lib/fnn-discovery.mjs";
+import { buildObservedPeerAddress, discoverPublicIpv4, publishablePeerAddresses } from "./lib/public-peer-address.mjs";
 
-const AGENT_VERSION = "0.1.1";
+const AGENT_VERSION = "0.1.3";
 const DEFAULT_CONFIG_PATH = ".fiber/agent.json";
 const DEFAULT_STATUS_PATH = ".fiber/agent-status.json";
 const DEFAULT_PUSH_INTERVAL_MS = 15_000;
 const MAX_BACKOFF_MS = 300_000;
 const DEFAULT_PULSE_MODULE = new URL("./lib/pulse/index.mjs", import.meta.url).href;
 const DEFAULT_FNN_PREFLIGHT_TIMEOUT_MS = 2_500;
+const DEFAULT_PUBLIC_IP_DISCOVERY_URL = "https://api.ipify.org?format=json";
+const DEFAULT_PUBLIC_IP_DISCOVERY_TIMEOUT_MS = 5_000;
 const DEFAULT_REPORT_URL = "https://ejchwtvdxpyojxsursmh.supabase.co/functions/v1/fibscope-gateway/agent/v1/report";
 const AGENT_ENV_PATHS = [resolve("agent/.env"), resolve(".env")];
 const ENV_REPORT_URL = "FIBGATE";
@@ -366,6 +369,7 @@ export async function createRuntime(options = {}) {
   const statusPath = resolve(options.status ?? DEFAULT_STATUS_PATH);
   const config = await loadConfig(configPath, options);
   await ensureFnnPreflight(config, statusPath, options);
+  await resolveAgentPublicIdentity(config);
   const remoteConfig = await fetchAgentConfig(config).catch(() => undefined);
   if (!config.nodeDisplayName && remoteConfig?.node?.displayName) {
     config.nodeDisplayName = remoteConfig.node.displayName;
@@ -478,6 +482,8 @@ export async function collectReport(config, previousReport = undefined) {
     agentVersion: AGENT_VERSION,
     chain: config.chain ?? "testnet",
     collectedAt,
+    publicIp: config.publicIp,
+    peerAddress: config.publicPeerAddress,
     node: state.node,
     peers: state.peers ?? [],
     channels: state.channels ?? [],
@@ -499,19 +505,29 @@ export async function collectReport(config, previousReport = undefined) {
 async function enrichReportNode(node, config) {
   if (!node || typeof node !== "object") return node;
   const displayName = textValue(config.nodeDisplayName);
-  const addresses = uniqueStrings([
+  const candidates = uniqueStrings([
     ...readAddressList(node.addresses),
     ...readAddressList(node.address),
     ...configuredPeerAddresses(config),
     ...await inferPeerAddressesFromLocalFnn(config),
   ]);
-  if (!addresses.length && !displayName) return node;
-  return {
+  const addresses = publishablePeerAddresses([
+    config.publicPeerAddress,
+    buildObservedPeerAddress(config.publicIp, [config.fnnP2pListenAddr, ...candidates]),
+    ...candidates,
+  ]);
+  const enriched = {
     ...node,
     ...(displayName ? { displayName } : {}),
-    address: node.address ?? addresses[0],
-    addresses,
   };
+  if (addresses.length) {
+    enriched.address = addresses[0];
+    enriched.addresses = addresses;
+  } else {
+    delete enriched.address;
+    delete enriched.addresses;
+  }
+  return enriched;
 }
 
 function configuredPeerAddresses(config) {
@@ -2281,6 +2297,8 @@ async function loadConfig(configPath, options = {}) {
       ckbIndexerUrl: process.env.FIBSCOPE_AGENT_CKB_INDEXER_URL,
       walletPath: process.env.FIBSCOPE_AGENT_WALLET_PATH ?? envValue(ENV_WALLET_PATH),
       peerAddress: process.env.FIBSCOPE_AGENT_PEER_ADDRESS,
+      publicIp: process.env.FIBSCOPE_AGENT_PUBLIC_IP,
+      publicIpDiscoveryUrl: process.env.FIBSCOPE_AGENT_PUBLIC_IP_URL,
     };
     label = "agent/.env";
   } else if (!existsSync(configPath)) {
@@ -2301,7 +2319,7 @@ function resolveReportUrl(config = {}) {
 }
 
 async function fetchAgentConfig(config) {
-  const configUrl = config.configUrl ?? config.reportUrl.replace(/\/report\/?$/, "/config");
+  const configUrl = new URL(config.configUrl ?? config.reportUrl.replace(/\/report\/?$/, "/config"));
   const response = await fetch(configUrl, {
     headers: {
       "x-agent-token": config.agentToken,
@@ -2351,6 +2369,8 @@ async function registerAgentNode(config, report, remoteConfig) {
       displayName: config.nodeDisplayName ?? remoteConfig?.node?.displayName,
       publicProfileEnabled: Boolean(report.publicProfileEnabled),
       overwrite: Boolean(config.overwriteNodeRegistration),
+      publicIp: report.publicIp ?? config.publicIp,
+      peerAddress: report.peerAddress ?? config.publicPeerAddress,
       node: report.node ?? {},
     }),
   });
@@ -2488,6 +2508,8 @@ function normalizeConfig(config, label) {
     ckbRpcUrl: process.env.FIBSCOPE_AGENT_CKB_RPC_URL ?? envValue(ENV_CKB_RPC_URL) ?? config.ckbRpcUrl,
     ckbIndexerUrl: process.env.FIBSCOPE_AGENT_CKB_INDEXER_URL ?? config.ckbIndexerUrl,
     walletPath: process.env.FIBSCOPE_AGENT_WALLET_PATH ?? envValue(ENV_WALLET_PATH) ?? config.walletPath,
+    publicIp: process.env.FIBSCOPE_AGENT_PUBLIC_IP ?? config.publicIp,
+    publicIpDiscoveryUrl: process.env.FIBSCOPE_AGENT_PUBLIC_IP_URL ?? config.publicIpDiscoveryUrl,
     pushIntervalMs: positiveNumber(config.pushIntervalMs, DEFAULT_PUSH_INTERVAL_MS),
     commandPollMs: positiveNumber(config.commandPollMs, DEFAULT_COMMAND_POLL_MS),
     knownPeerReconnectMs: positiveNumber(config.knownPeerReconnectMs, DEFAULT_KNOWN_PEER_RECONNECT_MS),
@@ -2499,6 +2521,25 @@ function normalizeConfig(config, label) {
   return normalized;
 }
 
+async function resolveAgentPublicIdentity(config) {
+  try {
+    const publicIp = await discoverPublicIpv4({
+      publicIp: config.publicIp,
+      endpoint: config.publicIpDiscoveryUrl ?? DEFAULT_PUBLIC_IP_DISCOVERY_URL,
+      timeoutMs: config.publicIpDiscoveryTimeoutMs ?? DEFAULT_PUBLIC_IP_DISCOVERY_TIMEOUT_MS,
+    });
+    config.publicIp = publicIp;
+    config.publicPeerAddress = buildObservedPeerAddress(publicIp, [
+      config.fnnP2pListenAddr,
+      ...configuredPeerAddresses(config),
+    ]);
+  } catch (error) {
+    console.warn(`Fibscope agent public IP unavailable: ${message(error)}`);
+    config.publicIp = undefined;
+    config.publicPeerAddress = publishablePeerAddresses(configuredPeerAddresses(config))[0];
+  }
+}
+
 async function bindAgentConfigToFnn(config, label, options = {}) {
   const next = { ...config };
   if (options.fiberRpcUrl) {
@@ -2539,15 +2580,12 @@ async function enrichConfigFromMatchingFnn(config) {
 }
 
 function applyFnnMatchToAgentConfig(config, match) {
-  const peerAddress = normalizeLocalListenAddress(match?.p2pListenAddr);
-  const hasConfiguredPeerAddress = configuredPeerAddresses(config).length > 0;
   return {
     ...config,
     ckbRpcUrl: config.ckbRpcUrl ?? match.ckbRpcUrl,
     fnnBaseDir: config.fnnBaseDir ?? match.baseDir,
     fnnConfigPath: config.fnnConfigPath ?? match.configPath,
     fnnP2pListenAddr: config.fnnP2pListenAddr ?? match.p2pListenAddr,
-    ...(!hasConfiguredPeerAddress && peerAddress ? { peerAddress } : {}),
     chain: config.chain ?? match.network,
   };
 }

package/lib/public-peer-address.mjs

@@ -0,0 +1,92 @@
+export function buildObservedPeerAddress(observedPublicIp, candidates = [], fallbackPort = 8228) {
+  const ip = normalizePublicIpv4(observedPublicIp);
+  if (!ip) return undefined;
+  const port = peerTcpPort(candidates, fallbackPort);
+  return `/ip4/${ip}/tcp/${port}`;
+}
+
+export async function discoverPublicIpv4(options = {}) {
+  const configured = normalizePublicIpv4(options.publicIp);
+  if (configured) return configured;
+
+  const endpoint = String(options.endpoint ?? "https://api.ipify.org?format=json").trim();
+  if (!endpoint) throw new Error("Public IPv4 discovery endpoint is not configured.");
+  const timeoutMs = positiveTimeout(options.timeoutMs, 5_000);
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await (options.fetchImpl ?? fetch)(endpoint, {
+      headers: { accept: "application/json, text/plain;q=0.9" },
+      signal: controller.signal,
+    });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    const body = await response.text();
+    let candidate = body;
+    try {
+      candidate = JSON.parse(body)?.ip ?? body;
+    } catch {
+      // Configurable plain-text IP endpoints are supported too.
+    }
+    const publicIp = normalizePublicIpv4(candidate);
+    if (!publicIp) throw new Error("response did not contain a public IPv4 address");
+    return publicIp;
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`Public IPv4 discovery failed at ${endpoint}: ${detail}`);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export function peerTcpPort(values, fallback = 8228) {
+  for (const value of flatStrings(values)) {
+    const match = value.match(/\/tcp\/(\d{1,5})(?:\/|$)/i);
+    const port = Number(match?.[1]);
+    if (Number.isInteger(port) && port > 0 && port <= 65_535) return port;
+  }
+  return fallback;
+}
+
+export function publishablePeerAddresses(values) {
+  return [...new Set(flatStrings(values).filter(isPublishablePeerAddress))];
+}
+
+export function isPublishablePeerAddress(value) {
+  const address = String(value ?? "").trim();
+  if (!address) return false;
+  const ipv4 = /\/ip4\/([^/]+)/i.exec(address)?.[1];
+  if (ipv4) return Boolean(normalizePublicIpv4(ipv4));
+  const ipv6 = /\/ip6\/([^/]+)/i.exec(address)?.[1]?.toLowerCase();
+  if (ipv6) {
+    return ipv6 !== "::" && ipv6 !== "::1" && !ipv6.startsWith("fc") && !ipv6.startsWith("fd") && !/^fe[89ab]/.test(ipv6);
+  }
+  return /\/(?:dns|dns4|dns6)\/[^/]+/i.test(address);
+}
+
+export function normalizePublicIpv4(value) {
+  let candidate = String(value ?? "").trim();
+  if (candidate.startsWith("::ffff:")) candidate = candidate.slice(7);
+  const parts = candidate.split(".").map(Number);
+  if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return undefined;
+  const [a, b, c] = parts;
+  if (a === 0 || a === 10 || a === 127 || a >= 224) return undefined;
+  if (a === 100 && b >= 64 && b <= 127) return undefined;
+  if (a === 169 && b === 254) return undefined;
+  if (a === 172 && b >= 16 && b <= 31) return undefined;
+  if (a === 192 && b === 168) return undefined;
+  if (a === 198 && (b === 18 || b === 19)) return undefined;
+  if (a === 192 && b === 0 && (c === 0 || c === 2)) return undefined;
+  if (a === 198 && b === 51 && c === 100) return undefined;
+  if (a === 203 && b === 0 && c === 113) return undefined;
+  return parts.join(".");
+}
+
+function flatStrings(values) {
+  const input = Array.isArray(values) ? values.flat(Infinity) : [values];
+  return input.map((value) => String(value ?? "").trim()).filter(Boolean);
+}
+
+function positiveTimeout(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? number : fallback;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fibscope/agent",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "description": "Fibscope Agent for Fiber node owners.",
   "bin": {
@@ -16,7 +16,7 @@
     ".env.example"
   ],
   "scripts": {
-    "check": "node --check index.mjs && node --check lib/pulse/index.mjs && node --check lib/pulse/engine.mjs && node --check lib/pulse/snapshot.mjs && node --check lib/pulse/intelligence.mjs && node --check lib/pulse/providers.mjs && node --check lib/pulse/server.mjs && node --check lib/observe/collector.mjs && node --check lib/bridge/recommendation.mjs && node --check lib/route/route.mjs && node --check lib/fnn-discovery.mjs",
+    "check": "node --check index.mjs && node --check lib/public-peer-address.mjs && node --check lib/pulse/index.mjs && node --check lib/pulse/engine.mjs && node --check lib/pulse/snapshot.mjs && node --check lib/pulse/intelligence.mjs && node --check lib/pulse/providers.mjs && node --check lib/pulse/server.mjs && node --check lib/observe/collector.mjs && node --check lib/bridge/recommendation.mjs && node --check lib/route/route.mjs && node --check lib/fnn-discovery.mjs && node --test test/*.test.mjs",
     "pack:dry-run": "npm pack --dry-run"
   },
   "dependencies": {