@agentprojectcontext/apx 1.76.0 → 1.77.1

package/src/interfaces/cli/commands/panel.js

@@ -0,0 +1,131 @@
+// apx panel — reach the admin panel from another device on the same network.
+//
+//   apx panel status
+//   apx panel share   [--host 192.168.1.40]
+//   apx panel unshare
+//
+// This binds a second, specific LAN address. It is NOT a tunnel: nothing leaves
+// the local network. Loopback stays the default, sharing is always explicit,
+// and the daemon's auth is untouched — the URL carries the token because
+// /admin/web-token is loopback-only by design, so a phone cannot fetch it.
+import fs from "node:fs";
+import { readConfig, writeConfig, effectivePort, effectiveHost } from "#core/config/index.js";
+import { TOKEN_PATH } from "#core/config/paths.js";
+import { detectLanAddresses, validateBindHost, isLoopback, isWildcard } from "#core/net/lan.js";
+
+export const PANEL_USAGE = {
+  status: "apx panel status",
+  share: "apx panel share [--host <ip>]",
+  unshare: "apx panel unshare",
+};
+
+function readToken() {
+  try {
+    return fs.readFileSync(TOKEN_PATH, "utf8").trim();
+  } catch {
+    return "";
+  }
+}
+
+function panelUrl(host, port, token) {
+  // /admin/web-token refuses anything that is not loopback, so the panel on a
+  // phone can only authenticate from the fragment. The fragment never reaches
+  // the server or a proxy log — that is why it is a fragment and not a query.
+  return `http://${host}:${port}/` + (token ? `#token=${token}` : "");
+}
+
+export async function cmdPanelStatus() {
+  const cfg = readConfig();
+  const host = effectiveHost(cfg);
+  const port = effectivePort(cfg);
+
+  if (isLoopback(host)) {
+    console.log(`panel: local only — http://${host}:${port}`);
+    console.log("  Nothing on your network can reach it.");
+    console.log("  To reach it from your phone: apx panel share");
+    return;
+  }
+
+  // 0.0.0.0 is a bigger promise than "reachable on my network": it also covers
+  // every interface that appears LATER — a VPN, a hotspot, a bridged container.
+  // Worth calling out separately rather than reporting it as ordinary sharing.
+  if (isWildcard(host)) {
+    console.log(`panel: bound to EVERY interface — ${host}:${port}`);
+    const addrs = detectLanAddresses();
+    if (addrs.length) {
+      console.log(`  Currently reachable at: ${addrs.map((a) => `http://${a.address}:${port}`).join(", ")}`);
+    }
+    console.log("  This also covers interfaces that appear later — a VPN, a hotspot, a");
+    console.log("  container bridge. Auth still applies, but the surface is wider than");
+    console.log("  it needs to be.");
+    console.log("");
+    console.log("  Narrow it to one address: apx panel share");
+    console.log("  Turn it off entirely:    apx panel unshare");
+    return;
+  }
+
+  console.log(`panel: SHARED on your network — http://${host}:${port}`);
+  console.log(`  Anyone on this network who has the URL and the token can open it.`);
+  console.log(`  To stop: apx panel unshare`);
+}
+
+export async function cmdPanelShare(args) {
+  const cfg = readConfig();
+  const port = effectivePort(cfg);
+
+  const requested = args?.flags?.host;
+  const candidates = detectLanAddresses();
+
+  if (!requested && candidates.length === 0) {
+    console.error("apx panel share: no network address found on this machine.");
+    console.error("  Are you connected to a network? Pass one explicitly with --host <ip>.");
+    process.exit(1);
+  }
+
+  const host = requested || candidates[0].address;
+  const check = validateBindHost(host);
+  if (!check.ok) {
+    console.error(`apx panel share: ${check.reason}`);
+    process.exit(1);
+  }
+
+  cfg.host = host;
+  writeConfig(cfg);
+
+  const token = readToken();
+  const iface = candidates.find((c) => c.address === host)?.iface;
+
+  console.log(`panel shared on ${host}:${port}${iface ? ` (${iface})` : ""}`);
+  console.log("");
+  console.log("  Open this on your phone — the token is in the URL:");
+  console.log(`  ${panelUrl(host, port, token)}`);
+  console.log("");
+  // Say plainly what changed. A LAN can be a café or a coworking space.
+  console.log("  What this means: anyone on this network can now REACH the panel.");
+  console.log("  They still need the token above, which is not guessable — treat that");
+  console.log("  URL like a password, and run `apx panel unshare` when you are done.");
+  if (candidates.length > 1) {
+    const others = candidates.filter((c) => c.address !== host).map((c) => `${c.address} (${c.iface})`);
+    console.log(`  Other addresses on this machine: ${others.join(", ")}`);
+  }
+  console.log("");
+  console.log("  Restart the daemon for the new binding to take effect: apx restart");
+}
+
+export async function cmdPanelUnshare() {
+  const cfg = readConfig();
+  const port = effectivePort(cfg);
+  const was = effectiveHost(cfg);
+
+  if (isLoopback(was)) {
+    console.log("panel is already local only — nothing to do");
+    return;
+  }
+
+  cfg.host = "127.0.0.1";
+  writeConfig(cfg);
+
+  console.log(`panel is local only again — http://127.0.0.1:${port}`);
+  console.log(`  Was ${was}. Nothing on your network can reach it now.`);
+  console.log("  Restart the daemon to apply: apx restart");
+}

package/src/interfaces/cli/index.js

@@ -161,6 +161,11 @@ import {
   cmdProfileDoctor,
   cmdProfileUninstall,
 } from "./commands/profile.js";
+import {
+  cmdPanelStatus,
+  cmdPanelShare,
+  cmdPanelUnshare,
+} from "./commands/panel.js";
 import {
   cmdOrgShow,
   cmdOrgAreaAdd,
@@ -1617,6 +1622,19 @@ const HELP_TOPICS = new Map(Object.entries({
     examples: ["apx plugins status telegram"],
   }),
 
+  panel: topic({
+    title: "apx panel",
+    summary:
+      "Reach the admin panel from another device on the same network. Not a tunnel — nothing leaves your LAN, and loopback stays the default.",
+    usage: ["apx panel <status|share|unshare>"],
+    commands: [
+      ["status", "Whether the panel is local only or shared, and on what address."],
+      ["share", "Bind a LAN address and print the URL to open on your phone."],
+      ["unshare", "Go back to local only."],
+    ],
+    options: [["--host <ip>", "share: bind this address instead of the detected one."]],
+    examples: ["apx panel status", "apx panel share", "apx panel unshare"],
+  }),
   profile: topic({
     title: "apx profile",
     summary:
@@ -2805,6 +2823,16 @@ async function dispatch(cmd, rest) {
         break;
       }
 
+      case "panel": {
+        const sub = rest[0];
+        const a = parseArgs(rest.slice(1));
+        if (!sub || sub === "status") await cmdPanelStatus(a);
+        else if (sub === "share") await cmdPanelShare(a);
+        else if (sub === "unshare") await cmdPanelUnshare(a);
+        else die(`unknown panel subcommand: ${sub}\nUsage: apx panel <status|share|unshare>`);
+        break;
+      }
+
       case "profile":
       case "profiles": {
         const sub = rest[0];