@fibscope/agent 0.1.0 → 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.0",
+  "agentVersion": "0.1.2",
   "chain": "testnet",
   "collectedAt": 1710000000000,
   "node": {},
@@ -105,12 +104,20 @@ Collection and transmission are independent loops:
 
 The local status file is `.fiber/agent-status.json`.
 
+## Run FNN With PM2
+
+Create the working directory, install setup and PM2, then run the setup process under PM2 with one command:
+
+```bash
+mkdir -p "$HOME/fibscope" && cd "$HOME/fibscope" && npm install -g pm2 @fibscope/setup && rm -f "$(npm prefix -g)/bin/fnn" && FIBER_SECRET_KEY_PASSWORD='<your-password>' pm2 start "$(command -v setup)" --name fiber-testnet --interpreter node -- --network testnet --rpc-host 127.0.0.1 --rpc-port 8227 --p2p-port 8228 && pm2 save
+```
+
+The Agent Setup page generates this command from a masked password field. The `fnn` link removal avoids confusing the package helper with the downloaded Fiber binary.
+
 ## 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

@@ -3,7 +3,7 @@
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
@@ -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.0";
+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,
   };
 }
@@ -3227,7 +3241,7 @@ async function promptLine(label) {
   }
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
   const { command, options } = parseArgs(process.argv.slice(2));
   const commands = { init, start, once, status, help };
   if (!commands[command]) {

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.0",
+  "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": {