@firstpick/pi-package-remote-webui 0.1.0 → 0.1.1

package/README.md

@@ -4,7 +4,7 @@ Mobile connection helper for [Pi coding agent](https://www.npmjs.com/package/@ea
 
 This package adds a `/remote` slash command that reuses the existing `@firstpick/pi-package-webui` server/UI, opens it to a trusted local network, and shows a QR code in Pi so a phone can connect quickly.
 
-> **Security:** Pi Web UI can control the Web UI/Pi session. Remote PIN authentication is off by default; enable it in Web UI **Controls → Network → Remote PIN auth** if you want a 4-digit PIN for non-local clients. Use `/remote` only on trusted local networks and close LAN access when done.
+> **Security:** Pi Web UI can control the Web UI/Pi session. `/remote` asks whether to activate Remote PIN authentication before showing the QR code. Use `/remote` only on trusted local networks and close LAN access when done.
 
 ## Install
 
@@ -23,9 +23,10 @@ Restart Pi after installation so the `/remote` command is loaded. The QR rendere
 Default behavior:
 
 1. Reuse a running Pi Web UI on `127.0.0.1:31415`, or start one for the current working directory.
-2. Open the Web UI listener to the local network through the existing Web UI `/api/network/open` endpoint.
-3. Show a terminal QR code, the LAN URL, and the current Remote PIN auth state.
-4. Scan the QR code from your phone and use the normal Pi Web UI. If Remote PIN auth is enabled, enter the displayed 4-digit PIN on the phone.
+2. Ask whether to activate Remote PIN auth when it is currently off.
+3. Open the Web UI listener to the local network through the existing Web UI `/api/network/open` endpoint.
+4. Show a terminal QR code, the LAN URL, and the current Remote PIN auth state.
+5. Scan the QR code from your phone and use the normal Pi Web UI. If Remote PIN auth is enabled and the local server reports the PIN, the QR code opens an auth link that signs in automatically; the displayed PIN remains a manual fallback.
 
 ## Commands
 
@@ -41,24 +42,25 @@ Default behavior:
 
 | Command | Behavior |
 |---|---|
-| `/remote` | Start/reuse Web UI, confirm, open LAN access, and show QR plus Remote PIN auth state. |
+| `/remote` | Start/reuse Web UI, confirm LAN access, ask whether to activate Remote PIN auth, open LAN access, and show QR plus auth state. |
 | `/remote status` | Show Web UI online/network state, LAN URLs, and auth state. |
 | `/remote refresh` | Re-read current LAN URL/auth state and redraw the QR widget. |
 | `/remote close` | Close Web UI LAN exposure and clear the QR widget. |
 | `/remote --port 31500` | Use another Web UI port. |
 | `/remote --name mobile` | Name the initial Web UI tab when this package starts the server. |
-| `/remote --yes` | Skip the LAN exposure confirmation. |
+| `/remote --yes` | Skip prompts and activate Remote PIN auth automatically before opening LAN access. |
 
 ## Remote PIN auth
 
-`/remote` does not enable Remote PIN auth by itself. Auth is intentionally controlled by the Web UI server:
+`/remote` checks the Web UI server's auth state before opening LAN access:
 
-- In the local Web UI, open **Controls → Network → Remote PIN auth**.
+- If Remote PIN auth is off, `/remote` asks whether to activate it.
+- `/remote --yes` treats the auth prompt as accepted and activates it automatically.
 - Enabling it generates a random 4-digit PIN.
-- Non-local browser clients must enter that PIN before reaching Web UI.
+- Non-local browser clients must authenticate before reaching Web UI.
 - Localhost clients can always use the UI and toggle the setting.
 
-The `/remote` QR widget shows `Remote PIN auth: off` or `Remote PIN auth: on · PIN 1234` when the Web UI server reports it. You can also start Web UI with auth already enabled by using `pi-webui --remote-auth` or `/webui-start --remote-auth` from `@firstpick/pi-package-webui`.
+The `/remote` QR widget shows `Remote PIN auth: off` or `Remote PIN auth: on · PIN 1234` when the Web UI server reports it. When a PIN is available, the QR code targets `/remote-auth#pin=1234` so the phone can authenticate automatically without typing the PIN; the fragment is scrubbed by the auth page before it posts to the server. You can also start Web UI with auth already enabled by using `pi-webui --remote-auth` or `/webui-start --remote-auth` from `@firstpick/pi-package-webui`.
 
 ## Caveat
 

package/index.ts

@@ -14,6 +14,7 @@ import {
   generateQrLines,
   openRemoteWebui,
   parseRemoteArgs,
+  remoteAuthQrUrl,
   requiresOpenConfirmation,
   usage,
 } from "./lib/remote-core.mjs";
@@ -25,13 +26,21 @@ const LOCAL_HOST = "127.0.0.1";
 
 const OPEN_WARNING = [
   "Pi Web UI can control Pi/WebUI and run allowed tools from connected browsers.",
-  "Remote PIN auth is off by default; enable it in Web UI Controls if you want a 4-digit PIN for non-local clients.",
+  "You will be asked whether to activate Remote PIN auth before the QR code is shown.",
   "",
   "Only open this on a trusted local network.",
   "",
   "Open to local network?",
 ].join("\n");
 
+const AUTH_WARNING = [
+  "Remote PIN auth is currently off.",
+  "",
+  "Activate it now? /remote will embed the generated PIN in the QR code so your phone can sign in without typing it.",
+  "",
+  "Choose No only on a trusted LAN where anyone with the URL may control Pi/WebUI.",
+].join("\n");
+
 type WebuiChild = ChildProcessByStdio<null, Readable, Readable>;
 
 type RemoteOptions = {
@@ -41,6 +50,11 @@ type RemoteOptions = {
   yes: boolean;
 };
 
+type RemoteNetworkStatus = {
+  auth?: { enabled?: boolean; pin?: string };
+  [key: string]: unknown;
+};
+
 function resolveExistingPath(candidate: string | undefined): string | undefined {
   if (!candidate) return undefined;
   return existsSync(candidate) ? candidate : undefined;
@@ -174,8 +188,9 @@ function setFullRemoteWidget(ctx: ExtensionCommandContext, lines: string[]): voi
 }
 
 async function renderRemoteWidget(ctx: ExtensionCommandContext, result: { url: string; network?: unknown; started?: boolean }): Promise<void> {
-  const qrLines = await generateQrLines(result.url);
-  const lines = buildRemoteWidgetLines({ url: result.url, qrLines, network: result.network, started: result.started });
+  const qrUrl = remoteAuthQrUrl(result.url, result.network || {});
+  const qrLines = await generateQrLines(qrUrl);
+  const lines = buildRemoteWidgetLines({ url: result.url, qrUrl, qrLines, network: result.network, started: result.started });
   setFullRemoteWidget(ctx, lines);
   setRemoteStatus(ctx, `remote ${result.url}`);
 }
@@ -186,6 +201,32 @@ async function confirmRemoteOpen(options: RemoteOptions, ctx: ExtensionCommandCo
   return await ctx.ui.confirm("Open Pi Web UI to LAN?", OPEN_WARNING);
 }
 
+function remoteAuthEnabled(network: unknown): boolean {
+  return (network as RemoteNetworkStatus | undefined)?.auth?.enabled === true;
+}
+
+function networkFromAuthUpdate(previous: unknown, data: unknown): unknown {
+  const update = data as { network?: unknown; auth?: unknown } | undefined;
+  if (update?.network) return update.network;
+  if (update?.auth && previous && typeof previous === "object") return { ...(previous as RemoteNetworkStatus), auth: update.auth };
+  return previous;
+}
+
+async function maybeActivateRemoteAuth(options: RemoteOptions, ctx: ExtensionCommandContext, controller: RemoteWebuiController, network: unknown): Promise<unknown> {
+  if (remoteAuthEnabled(network)) return network;
+
+  let activate = options.yes === true;
+  if (!activate) {
+    if (!ctx.hasUI) return network;
+    activate = await ctx.ui.confirm("Activate Remote PIN auth?", AUTH_WARNING);
+  }
+  if (!activate) return network;
+
+  setRemoteStatus(ctx, "enabling remote PIN auth…");
+  const data = await controller.setRemoteAuth(options.port, true);
+  return networkFromAuthUpdate(network, data);
+}
+
 async function handleStatus(options: RemoteOptions, ctx: ExtensionCommandContext, controller: RemoteWebuiController): Promise<void> {
   setRemoteStatus(ctx, "checking remote webui…");
   try {
@@ -243,6 +284,7 @@ async function handleOpen(options: RemoteOptions, ctx: ExtensionCommandContext,
   const result = await openRemoteWebui(options, {
     controller,
     startWebui: async (startOptions: RemoteOptions) => spawnWebui(startOptions, ctx),
+    prepareNetwork: async (network: unknown) => maybeActivateRemoteAuth(options, ctx, controller, network),
   });
   await renderRemoteWidget(ctx, result);
   ctx.ui.notify(`Pi Remote WebUI ready:\n${result.url}\n\nScan the QR code above from your phone.`, "info");

package/lib/remote-core.mjs

@@ -201,6 +201,16 @@ export class RemoteWebuiController {
     throw new Error(result.body?.error || "Failed to close Pi Web UI network access");
   }
 
+  async setRemoteAuth(port, enabled, timeoutMs = 1_500) {
+    const result = await fetchJsonWithTimeout(endpointUrl(port, "/api/remote-auth/settings"), {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ enabled: enabled === true }),
+    }, timeoutMs, this.fetchImpl);
+    if (result.ok && result.body?.ok === true) return result.body.data;
+    throw new Error(result.body?.error || "Failed to update Pi Web UI Remote PIN auth");
+  }
+
   async waitForNetworkOpen(port, { timeoutMs = DEFAULT_NETWORK_TIMEOUT_MS, pollMs = DEFAULT_POLL_MS } = {}) {
     const deadline = Date.now() + timeoutMs;
     let last;
@@ -235,7 +245,31 @@ export function selectLanUrl(network) {
   return urls.find((url) => typeof url === "string" && /^https?:\/\//i.test(url)) || undefined;
 }
 
-export async function openRemoteWebui(options, { controller, startWebui }) {
+function safeQrReturnPath(value = "/") {
+  const text = String(value || "/").trim();
+  if (!text.startsWith("/") || text.startsWith("//")) return "/";
+  return text;
+}
+
+export function remoteAuthQrUrl(url, network = {}) {
+  if (typeof url !== "string" || !url) return url;
+  const pin = String(network?.auth?.pin || "").trim();
+  if (!network?.auth?.enabled || !/^\d{4}$/.test(pin)) return url;
+
+  try {
+    const parsed = new URL(url);
+    const returnPath = safeQrReturnPath(`${parsed.pathname || "/"}${parsed.search || ""}`);
+    parsed.pathname = "/remote-auth";
+    parsed.search = "";
+    parsed.searchParams.set("return", returnPath);
+    parsed.hash = new URLSearchParams({ pin }).toString();
+    return parsed.toString();
+  } catch {
+    return url;
+  }
+}
+
+export async function openRemoteWebui(options, { controller, startWebui, prepareNetwork } = {}) {
   if (!controller) throw new Error("RemoteWebuiController is required");
   let health = await controller.probeHealth(options.port);
   let started = false;
@@ -254,6 +288,10 @@ export async function openRemoteWebui(options, { controller, startWebui }) {
     network = health.data?.network;
   }
 
+  if (typeof prepareNetwork === "function") {
+    network = (await prepareNetwork(network, { health, started })) || network;
+  }
+
   if (!network?.open || network?.closing) {
     await controller.openNetwork(options.port);
     network = await controller.waitForNetworkOpen(options.port);
@@ -299,25 +337,32 @@ export function formatStatus(status) {
     `Bind:     ${network.host || "unknown"}:${network.port || "?"}`,
   ];
   if (networkUrls.length) lines.push(`LAN URLs: ${networkUrls.join(", ")}`);
+  const auth = network.auth || {};
+  lines.push(auth.enabled ? `Remote PIN auth: on${auth.pin ? ` · PIN ${auth.pin}` : ""}` : "Remote PIN auth: off");
   if (status.health?.data?.webuiVersion) lines.push(`Version:  ${status.health.data.webuiVersion}`);
   if (status.error) lines.push(`Warning:  ${status.error}`);
   return lines.join("\n");
 }
 
-export function buildRemoteWidgetLines({ url, qrLines = [], network = {}, started = false } = {}) {
+export function buildRemoteWidgetLines({ url, qrUrl, qrLines = [], network = {}, started = false } = {}) {
   const auth = network?.auth || {};
+  const displayUrl = url || selectLanUrl(network) || network.localUrl || "(no URL)";
+  const qrTarget = qrUrl || remoteAuthQrUrl(displayUrl, network);
+  const hasAutoAuthQr = auth.enabled && !!auth.pin && qrTarget !== displayUrl;
   const authLine = auth.enabled ? `Remote PIN auth: on${auth.pin ? ` · PIN ${auth.pin}` : ""}` : "Remote PIN auth: off";
-  const warningLine = auth.enabled
-    ? "Trusted LAN only. Anyone with this URL and PIN can control Pi/WebUI."
-    : "Trusted LAN only. Remote PIN auth is off; anyone with this URL can control Pi/WebUI.";
+  const warningLine = hasAutoAuthQr
+    ? "Trusted LAN only. The QR signs in with the embedded PIN; keep it private."
+    : auth.enabled
+      ? "Trusted LAN only. Anyone with this URL and PIN can control Pi/WebUI."
+      : "Trusted LAN only. Remote PIN auth is off; anyone with this URL can control Pi/WebUI.";
   const lines = [
     "Pi Remote WebUI",
     "",
-    "Scan with your phone:",
+    hasAutoAuthQr ? "Scan with your phone (auto-auth QR):" : "Scan with your phone:",
     "",
     ...qrLines,
     "",
-    url || selectLanUrl(network) || network.localUrl || "(no URL)",
+    displayUrl,
     authLine,
     "",
     warningLine,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firstpick/pi-package-remote-webui",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Pi /remote command that opens the existing Pi Web UI to a trusted LAN and shows a QR code for mobile.",
   "license": "MIT",
   "homepage": "https://github.com/Firstp1ck/npm-packages/tree/main/pi-package-remote-webui#readme",

package/tests/remote-args.test.mjs

@@ -1,11 +1,13 @@
 import test from "node:test";
 import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
 import {
   DEFAULT_PORT,
   buildRemoteWidgetLines,
   formatStatus,
   generateQrLines,
   parseRemoteArgs,
+  remoteAuthQrUrl,
   requiresOpenConfirmation,
   selectLanUrl,
   tokenizeArgs,
@@ -60,19 +62,33 @@ test("selectLanUrl chooses the first HTTP LAN URL", () => {
   );
 });
 
-test("formatStatus renders offline and online states", () => {
-  assert.match(formatStatus({ online: false, url: "http://127.0.0.1:31415/", health: { error: "offline" } }), /Online:\s+no/);
-  assert.match(
-    formatStatus({
-      online: true,
-      url: "http://192.168.1.20:31415/",
-      health: { data: { webuiVersion: "0.3.8" } },
-      network: { open: true, host: "0.0.0.0", port: 31415, networkUrls: ["http://192.168.1.20:31415/"] },
-    }),
-    /open to LAN/,
+test("remoteAuthQrUrl embeds an available remote PIN in a URL fragment auth link", () => {
+  assert.equal(
+    remoteAuthQrUrl("http://192.168.1.20:31415/", { auth: { enabled: true, pin: "1234" } }),
+    "http://192.168.1.20:31415/remote-auth?return=%2F#pin=1234",
+  );
+  assert.equal(
+    remoteAuthQrUrl("http://192.168.1.20:31415/tree?tab=abc", { auth: { enabled: true, pin: "1234" } }),
+    "http://192.168.1.20:31415/remote-auth?return=%2Ftree%3Ftab%3Dabc#pin=1234",
+  );
+  assert.equal(
+    remoteAuthQrUrl("http://192.168.1.20:31415/", { auth: { enabled: true } }),
+    "http://192.168.1.20:31415/",
   );
 });
 
+test("formatStatus renders offline, online, and auth states", () => {
+  assert.match(formatStatus({ online: false, url: "http://127.0.0.1:31415/", health: { error: "offline" } }), /Online:\s+no/);
+  const onlineStatus = formatStatus({
+    online: true,
+    url: "http://192.168.1.20:31415/",
+    health: { data: { webuiVersion: "0.3.8" } },
+    network: { open: true, host: "0.0.0.0", port: 31415, networkUrls: ["http://192.168.1.20:31415/"], auth: { enabled: true, pin: "1234" } },
+  });
+  assert.match(onlineStatus, /open to LAN/);
+  assert.match(onlineStatus, /Remote PIN auth: on · PIN 1234/);
+});
+
 test("buildRemoteWidgetLines includes QR, URL, auth state, and close instruction", () => {
   const lines = buildRemoteWidgetLines({
     url: "http://192.168.1.20:31415/",
@@ -83,6 +99,7 @@ test("buildRemoteWidgetLines includes QR, URL, auth state, and close instruction
   assert(lines.includes("QR-A"));
   assert(lines.includes("http://192.168.1.20:31415/"));
   assert(lines.some((line) => line.includes("PIN 1234")));
+  assert(lines.some((line) => line.includes("QR signs in")));
   assert(lines.some((line) => line.includes("/remote close")));
   assert(lines.some((line) => line.includes("Started a Pi Web UI server")));
 });
@@ -110,3 +127,10 @@ test("generateQrLines reports QR failures without duplicating the URL", async ()
   });
   assert.deepEqual(lines, ["[QR generation failed: boom]"]);
 });
+
+test("extension asks whether to activate Remote PIN auth while opening /remote", async () => {
+  const source = await readFile(new URL("../index.ts", import.meta.url), "utf8");
+  assert.match(source, /ctx\.ui\.confirm\("Activate Remote PIN auth\?", AUTH_WARNING\)/);
+  assert.match(source, /controller\.setRemoteAuth\(options\.port, true\)/);
+  assert.match(source, /prepareNetwork: async \(network: unknown\) => maybeActivateRemoteAuth/);
+});

package/tests/remote-webui-control.test.mjs

@@ -75,6 +75,77 @@ test("openRemoteWebui starts when offline, opens network, and returns a LAN URL"
   });
 });
 
+test("openRemoteWebui can prepare network settings before opening LAN access", async () => {
+  const calls = [];
+  let networkOpen = false;
+  let authEnabled = false;
+
+  await withMockWebui((req, res) => {
+    calls.push(`${req.method} ${req.url}`);
+    if (req.url === "/api/health" && req.method === "GET") return sendJson(res, 200, { ok: true, webuiVersion: "0.3.8" });
+    if (req.url === "/api/network" && req.method === "GET") {
+      return sendJson(res, 200, {
+        ok: true,
+        data: {
+          open: networkOpen,
+          opening: false,
+          closing: false,
+          host: networkOpen ? "0.0.0.0" : "127.0.0.1",
+          port: 0,
+          localUrl: "http://127.0.0.1/",
+          networkUrls: networkOpen ? ["http://10.0.0.8:31415/"] : [],
+          auth: authEnabled ? { enabled: true, pin: "1234" } : { enabled: false },
+        },
+      });
+    }
+    if (req.url === "/api/remote-auth/settings" && req.method === "POST") {
+      authEnabled = true;
+      return sendJson(res, 200, {
+        ok: true,
+        data: {
+          network: {
+            open: networkOpen,
+            opening: false,
+            closing: false,
+            host: networkOpen ? "0.0.0.0" : "127.0.0.1",
+            port: 0,
+            localUrl: "http://127.0.0.1/",
+            networkUrls: networkOpen ? ["http://10.0.0.8:31415/"] : [],
+            auth: { enabled: true, pin: "1234" },
+          },
+        },
+      });
+    }
+    if (req.url === "/api/network/open" && req.method === "POST") {
+      networkOpen = true;
+      return sendJson(res, 202, { ok: true, data: { opening: true } });
+    }
+    sendJson(res, 404, { ok: false });
+  }, async (port) => {
+    const controller = new RemoteWebuiController({ sleepImpl: () => Promise.resolve() });
+    const result = await openRemoteWebui({ port }, {
+      controller,
+      startWebui: async () => {},
+      prepareNetwork: async (network) => {
+        calls.push(`prepare auth=${network.auth.enabled}`);
+        const data = await controller.setRemoteAuth(port, true);
+        return data.network;
+      },
+    });
+
+    assert.equal(result.url, "http://10.0.0.8:31415/");
+    assert.equal(result.network.auth.pin, "1234");
+    assert.deepEqual(calls, [
+      "GET /api/health",
+      "GET /api/network",
+      "prepare auth=false",
+      "POST /api/remote-auth/settings",
+      "POST /api/network/open",
+      "GET /api/network",
+    ]);
+  });
+});
+
 test("openRemoteWebui reuses an already open WebUI", async () => {
   let startCalled = false;