@fibscope/agent 0.1.1 → 0.1.2

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 hosted gateway returns the public IPv4 it observes for the authenticated agent request. The agent combines that IP with the local FNN P2P port and reports the resulting public multiaddr. Loopback, wildcard, private, and documentation addresses are never published. Set `peerAddress` only when intentionally overriding automatic discovery with another publicly dialable multiaddr.
 
 ## Commands
 
@@ -75,7 +74,7 @@ The agent pushes to `POST /agent/v1/report` with:
 
 ```json
 {
-  "agentVersion": "0.1.1",
+  "agentVersion": "0.1.2",
   "chain": "testnet",
   "collectedAt": 1710000000000,
   "node": {},
@@ -117,10 +116,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@0.1.2 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,8 +31,9 @@ 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, peerTcpPort, publishablePeerAddresses } from "./lib/public-peer-address.mjs";
 
-const AGENT_VERSION = "0.1.1";
+const AGENT_VERSION = "0.1.2";
 const DEFAULT_CONFIG_PATH = ".fiber/agent.json";
 const DEFAULT_STATUS_PATH = ".fiber/agent-status.json";
 const DEFAULT_PUSH_INTERVAL_MS = 15_000;
@@ -367,6 +368,8 @@ export async function createRuntime(options = {}) {
   const config = await loadConfig(configPath, options);
   await ensureFnnPreflight(config, statusPath, options);
   const remoteConfig = await fetchAgentConfig(config).catch(() => undefined);
+  config.observedPublicIp = remoteConfig?.observedPublicIp ?? config.observedPublicIp;
+  config.observedPeerAddress = remoteConfig?.observedPeerAddress ?? config.observedPeerAddress;
   if (!config.nodeDisplayName && remoteConfig?.node?.displayName) {
     config.nodeDisplayName = remoteConfig.node.displayName;
   }
@@ -499,19 +502,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.observedPeerAddress,
+    buildObservedPeerAddress(config.observedPublicIp, [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) {
@@ -2301,7 +2314,11 @@ 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"));
+  configUrl.searchParams.set("p2pPort", String(peerTcpPort([
+    config.fnnP2pListenAddr,
+    ...configuredPeerAddresses(config),
+  ], 8228)));
   const response = await fetch(configUrl, {
     headers: {
       "x-agent-token": config.agentToken,
@@ -2539,15 +2556,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,54 @@
+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 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);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fibscope/agent",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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": {