npm - pgserve - Versions diffs - 2.2.1 → 2.2.3 - Mend

pgserve 2.2.1 → 2.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (26) hide show

package/CHANGELOG.md +104 -0
package/console/dist/app.js +121 -0
package/console/dist/index.html +13 -0
package/package.json +8 -4
package/src/cli-install.cjs +345 -4
package/src/cli-ui.cjs +81 -6
package/console/README.md +0 -131
package/console/api.js +0 -173
package/console/app.jsx +0 -483
package/console/components.jsx +0 -167
package/console/data.jsx +0 -350
package/console/index.html +0 -31
package/console/screens/databases.jsx +0 -5
package/console/screens/health.jsx +0 -5
package/console/screens/ingress.jsx +0 -5
package/console/screens/optimizer.jsx +0 -5
package/console/screens/rlm-sim.jsx +0 -5
package/console/screens/rlm-trace.jsx +0 -5
package/console/screens/security.jsx +0 -5
package/console/screens/settings.jsx +0 -611
package/console/screens/sql.jsx +0 -5
package/console/screens/sync.jsx +0 -5
package/console/screens/tables.jsx +0 -5
package/console/tweaks-panel.jsx +0 -425
/package/console/{colors_and_type.css → dist/colors_and_type.css} +0 -0
/package/console/{console.css → dist/console.css} +0 -0

package/console/dist/index.html ADDED Viewed

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en" data-theme="mdr" data-screen-label="autopg console">
+<head>
+<meta charset="utf-8" />
+<title>autopg · console</title>
+<link rel="stylesheet" href="colors_and_type.css" />
+<link rel="stylesheet" href="console.css?v=settings1" />
+</head>
+<body>
+<div id="root"></div>
+<script type="module" src="./app.js"></script>
+</body>
+</html>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "pgserve",
-  "version": "2.2.1",
+  "version": "2.2.3",
   "description": "Embedded PostgreSQL server with true concurrent connections - zero config, auto-provision databases",
   "main": "src/index.js",
   "type": "module",
@@ -11,7 +11,7 @@
   "files": [
     "bin/",
     "src/",
-    "console/",
+    "console/dist/",
     "README.md",
     "CHANGELOG.md",
     "LICENSE",
@@ -26,12 +26,14 @@
     "start": "bun bin/postgres-server.js",
     "build": "bun build --compile bin/postgres-server.js --outfile dist/pgserve",
     "build:all": "make build-all",
+    "console:build": "bun build console/src/main.jsx --target browser --minify --define 'process.env.NODE_ENV=\"production\"' --outfile console/dist/app.js && cp console/src/index.html console/dist/index.html && cp console/src/*.css console/dist/",
+    "console:dev": "bun build console/src/main.jsx --target browser --define 'process.env.NODE_ENV=\"development\"' --watch --outfile console/dist/app.js",
     "lint": "eslint src/ bin/",
     "lint:fix": "eslint src/ bin/ --fix",
     "deadcode": "knip",
     "test:npx": "scripts/test-npx.sh",
     "test:bun-self-heal": "scripts/test-bun-self-heal.sh",
-    "prepublishOnly": "npm run lint && npm run deadcode && npm run test:npx && npm run test:bun-self-heal",
+    "prepublishOnly": "npm run console:build && npm run lint && npm run deadcode && npm run test:npx && npm run test:bun-self-heal",
     "prepare": "husky",
     "postinstall": "node scripts/postinstall.cjs"
   },
@@ -76,6 +78,8 @@
     ]
   },
   "dependencies": {
-    "bun": "^1.3.4"
+    "bun": "^1.3.4",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
   }
 }

package/src/cli-install.cjs CHANGED Viewed

@@ -22,6 +22,7 @@
 'use strict';
 const { spawnSync, execFileSync } = require('node:child_process');
+const crypto = require('node:crypto');
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
@@ -29,6 +30,24 @@ const path = require('node:path');
 const PM2_PROCESS_NAME = 'pgserve';
 const DEFAULT_PORT = 8432;
+// Console UI is auto-supervised under pm2 alongside the daemon since v2.2.3.
+// The bundled SPA (console/dist/) is served on this port; operator-facing
+// only, 127.0.0.1, no auth, no TLS — matches autopg's "single-user dev tool"
+// posture. Opt-out with `autopg install --no-ui` for headless/CI hosts.
+const UI_PM2_PROCESS_NAME = 'autopg-ui';
+const DEFAULT_UI_PORT = 8433;
+const DEFAULT_UI_HOST = '127.0.0.1';
+const UI_MAX_MEMORY = '256M';
+// Admin password file shape (~/.autopg/admin.json, mode 0600):
+//   { scheme: 'scrypt', salt: <b64>, hash: <b64>, createdAt, rotatedAt }
+// Generated on first `autopg install`; rotated via `autopg auth
+// rotate-admin-password`. cli-ui.cjs reads this via getAdminFilePath()
+// and gates Basic Auth against it.
+const ADMIN_FILE_NAME = 'admin.json';
+const SCRYPT_PARAMS = { N: 16384, r: 8, p: 1, dkLen: 32 };
+const ADMIN_PASSWORD_BYTES = 12; // 96 bits → ~24 hex chars; plenty for a localhost dev tool
 /**
  * Hardening defaults — tuned for production-grade elasticity, NOT
  * the toy-machine values an initial draft of the wish carried.
@@ -268,13 +287,248 @@ function ok(message) {
 }
 /**
- * `pgserve install [--port N] [--data PATH]`
+ * Resolve the autopg wrapper used to launch the UI under pm2. The wrapper
+ * lives next to `postgres-server.js` (same `bin/` dir).
+ */
+function getUiBinPath(scriptPath) {
+  return path.join(path.dirname(scriptPath), 'autopg-wrapper.cjs');
+}
+/**
+ * pm2 start args for the UI process. Smaller memory cap than the daemon
+ * (idle node http server, no postgres backend), shares the same restart
+ * budget + exp-backoff as pgserve.
+ */
+function buildUiPm2StartArgs({ uiBinPath, uiPort, uiHost }) {
+  const logs = {
+    out: path.join(getLogsDir(), `${UI_PM2_PROCESS_NAME}-out.log`),
+    error: path.join(getLogsDir(), `${UI_PM2_PROCESS_NAME}-error.log`),
+  };
+  const supervision = getEffectiveSupervision();
+  return [
+    'start',
+    uiBinPath,
+    '--name',
+    UI_PM2_PROCESS_NAME,
+    '--interpreter',
+    'none',
+    '--max-restarts',
+    String(supervision.maxRestarts),
+    '--restart-delay',
+    String(supervision.restartDelayMs),
+    '--exp-backoff-restart-delay',
+    String(supervision.expBackoffRestartDelayMs),
+    '--max-memory-restart',
+    UI_MAX_MEMORY,
+    '--kill-timeout',
+    String(supervision.killTimeoutMs),
+    '--log-date-format',
+    supervision.logDateFormat,
+    '--output',
+    logs.out,
+    '--error',
+    logs.error,
+    '--',
+    'ui',
+    '--no-open',
+    '--port',
+    String(uiPort),
+    '--host',
+    uiHost,
+  ];
+}
+/**
+ * Register `autopg-ui` under pm2. Soft-fails: if pm2 is missing, the bin
+ * is missing, or the spawn fails — log a note and return 0 anyway. The
+ * daemon is the load-bearing process; the UI is convenience.
+ */
+function cmdInstallUi(ctx, options = {}) {
+  if (!pm2IsAvailable()) {
+    note('pm2 not found; skipping UI install (run `autopg ui` on demand)');
+    return 0;
+  }
+  const uiBinPath = getUiBinPath(ctx.scriptPath);
+  if (!fs.existsSync(uiBinPath)) {
+    note(`UI bin not found at ${uiBinPath}; skipping UI install`);
+    return 0;
+  }
+  const uiPort = options.uiPort ?? DEFAULT_UI_PORT;
+  const uiHost = options.uiHost ?? DEFAULT_UI_HOST;
+  const refresh = options.refresh === true;
+  // If a UI process already exists: refresh-mode replaces it (pick up new
+  // host/port/etc); idempotent-mode keeps it. Default behavior is
+  // idempotent — operators who want to apply new flags pass --with-ui
+  // (which sets refresh=true) so the change takes effect without a
+  // separate uninstall step.
+  const existing = pm2GetProcess(UI_PM2_PROCESS_NAME);
+  if (existing && !refresh) {
+    ok(`UI already installed (pm2 process "${UI_PM2_PROCESS_NAME}", status=${existing.pm2_env?.status ?? 'unknown'})`);
+    return 0;
+  }
+  if (existing && refresh) {
+    spawnSync('pm2', ['delete', UI_PM2_PROCESS_NAME], { stdio: ['ignore', 'pipe', 'pipe'] });
+  }
+  ensureLogsDir();
+  const pm2Args = buildUiPm2StartArgs({ uiBinPath, uiPort, uiHost });
+  const result = spawnSync('pm2', pm2Args, { stdio: 'inherit' });
+  if (result.status !== 0) {
+    note(`UI install failed (exit ${result.status}); daemon is unaffected. Run \`autopg ui\` manually.`);
+    return 0;
+  }
+  ok(`UI ${refresh && existing ? 'refreshed' : 'installed'}: pm2 process "${UI_PM2_PROCESS_NAME}" on http://${uiHost}:${uiPort}`);
+  return 0;
+}
+function cmdUninstallUi() {
+  if (!pm2IsAvailable()) return 0;
+  // Always attempt the delete — `pm2 delete <name>` is idempotent and
+  // exits non-zero on a missing process, which is fine to swallow. This
+  // is more robust than a pre-existence check against `pm2 jlist`, which
+  // can lag the actual process state (or, in test stubs, return a
+  // partial registry).
+  const result = spawnSync('pm2', ['delete', UI_PM2_PROCESS_NAME], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (result.status === 0) {
+    ok(`UI uninstalled (pm2 process "${UI_PM2_PROCESS_NAME}" removed)`);
+  }
+  return 0;
+}
+// ─── Admin password (Basic Auth for `autopg ui`) ─────────────────────────
+function getAdminFilePath() {
+  return path.join(getConfigDir(), ADMIN_FILE_NAME);
+}
+function generateAdminPassword() {
+  // 12 bytes → 24 hex chars, grouped in 4-char chunks for human transcription:
+  // "7f3a-92c1-8ed4-1b6c-..." (no ambiguous chars beyond hex; matches the
+  // "really simple, don't reinvent" bar — operators copy-paste from a single
+  // stdout line into a browser dialog).
+  const raw = crypto.randomBytes(ADMIN_PASSWORD_BYTES).toString('hex');
+  return raw.match(/.{1,4}/g).join('-');
+}
+function hashAdminPassword(password, salt) {
+  // scrypt is RFC 7914 + built into Node since 10.5. No npm dep.
+  return crypto.scryptSync(password, salt, SCRYPT_PARAMS.dkLen, {
+    N: SCRYPT_PARAMS.N,
+    r: SCRYPT_PARAMS.r,
+    p: SCRYPT_PARAMS.p,
+  });
+}
+function writeAdminFile({ password, rotated = false }) {
+  const salt = crypto.randomBytes(32);
+  const hash = hashAdminPassword(password, salt);
+  const file = getAdminFilePath();
+  const now = new Date().toISOString();
+  const payload = {
+    scheme: 'scrypt',
+    params: SCRYPT_PARAMS,
+    salt: salt.toString('base64'),
+    hash: hash.toString('base64'),
+    createdAt: rotated ? readAdminFile()?.createdAt ?? now : now,
+    rotatedAt: rotated ? now : null,
+  };
+  ensureConfigDir();
+  // Atomic write: tmp + rename. mode 0600 enforced via fchmod after write.
+  const tmp = `${file}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(payload, null, 2), { mode: 0o600 });
+  fs.renameSync(tmp, file);
+  fs.chmodSync(file, 0o600);
+  return payload;
+}
+function readAdminFile() {
+  try {
+    const raw = fs.readFileSync(getAdminFilePath(), 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function ensureConfigDir() {
+  const dir = getConfigDir();
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+/**
+ * Verify a candidate password against the stored hash. Returns true on match.
+ * Used by cli-ui.cjs at every Basic Auth check. Constant-time comparison
+ * via crypto.timingSafeEqual.
+ */
+function verifyAdminPassword(candidate) {
+  const stored = readAdminFile();
+  if (!stored || stored.scheme !== 'scrypt') return false;
+  const salt = Buffer.from(stored.salt, 'base64');
+  const expected = Buffer.from(stored.hash, 'base64');
+  const params = stored.params || SCRYPT_PARAMS;
+  let actual;
+  try {
+    actual = crypto.scryptSync(candidate, salt, params.dkLen, {
+      N: params.N,
+      r: params.r,
+      p: params.p,
+    });
+  } catch {
+    return false;
+  }
+  if (actual.length !== expected.length) return false;
+  return crypto.timingSafeEqual(actual, expected);
+}
+function ensureAdminPassword({ rotate = false } = {}) {
+  const existing = readAdminFile();
+  if (existing && !rotate) return null;
+  const password = generateAdminPassword();
+  writeAdminFile({ password, rotated: !!existing });
+  return password;
+}
+function cmdAuthRotate() {
+  const password = ensureAdminPassword({ rotate: true });
+  if (!password) {
+    fail('admin password rotation produced no new password (unexpected)');
+  }
+  process.stdout.write(`pgserve: admin password rotated. New password (printed ONCE):\n\n  ${password}\n\n`);
+  process.stdout.write(`Saved hash to ${getAdminFilePath()} (mode 0600).\n`);
+  process.stdout.write(`Existing browser sessions will be re-prompted on their next request.\n`);
+  return 0;
+}
+function cmdAuthDispatch(args) {
+  const sub = args[0];
+  switch (sub) {
+    case 'rotate-admin-password':
+      return cmdAuthRotate();
+    case 'show-admin-path':
+      process.stdout.write(`${getAdminFilePath()}\n`);
+      return 0;
+    default:
+      fail(`pgserve auth: unknown subcommand "${sub ?? ''}". Try: rotate-admin-password | show-admin-path`);
+  }
+}
+/**
+ * `pgserve install [--port N] [--data PATH] [--no-ui] [--ui-port N]`
  *
  * Idempotent. When the process is already registered, prints a reuse line
  * and exits 0 without touching anything. Otherwise: writes `~/.pgserve/
  * config.json` (creating the dir if needed), then registers the process
  * under pm2 with the hardened defaults.
  *
+ * Since v2.2.3: also auto-supervises the autopg console UI under pm2 as
+ * `autopg-ui` (default port 8433). Opt out via `--no-ui`. The UI is a thin
+ * http server bound to 127.0.0.1 — single-user dev tool, no auth, no TLS.
+ *
  * `scriptPath` is the path to `bin/postgres-server.js` resolved by the
  * wrapper before this module is required (avoids re-resolving here).
  */
@@ -286,14 +540,48 @@ function cmdInstall(args, ctx) {
   const port = parsePort(args) ?? readConfig()?.port ?? DEFAULT_PORT;
   const dataDir = parseDataDir(args) ?? readConfig()?.dataDir ?? getDataDir();
-  // Idempotent: already-registered = no-op success.
-  const existing = pm2GetProcess(PM2_PROCESS_NAME);
+  const noUi = args.includes('--no-ui');
+  const withUi = args.includes('--with-ui');
+  const redeploy = args.includes('--redeploy');
+  const uiPort = parseUiPort(args) ?? DEFAULT_UI_PORT;
+  const uiHost = parseUiHost(args) ?? DEFAULT_UI_HOST;
+  if (noUi && withUi) {
+    fail('--no-ui and --with-ui are mutually exclusive');
+  }
+  // --with-ui: UI-only path. Don't touch the daemon — register or refresh
+  // autopg-ui only. Useful for v2.2.2 → v2.2.3 upgrades where the daemon
+  // is fine and only the UI is missing, AND for changing UI host/port
+  // post-install without restarting postgres.
+  if (withUi) {
+    cmdInstallUi(ctx, { uiPort, uiHost, refresh: true });
+    return 0;
+  }
+  // --redeploy: full reset. Tear down both processes, then proceed with
+  // a fresh install. Equivalent to `autopg uninstall && autopg install`
+  // but in one verb.
+  if (redeploy) {
+    const had = pm2GetProcess(PM2_PROCESS_NAME);
+    if (had) {
+      spawnSync('pm2', ['delete', PM2_PROCESS_NAME], { stdio: ['ignore', 'pipe', 'pipe'] });
+    }
+    spawnSync('pm2', ['delete', UI_PM2_PROCESS_NAME], { stdio: ['ignore', 'pipe', 'pipe'] });
+    note('--redeploy: removed any existing pm2 processes; reinstalling fresh');
+  }
+  // Idempotent: already-registered = no-op success. Still reconcile the UI
+  // process so re-running `autopg install` after an upgrade picks up the UI
+  // even on hosts where the daemon was registered pre-v2.2.3.
+  const existing = redeploy ? null : pm2GetProcess(PM2_PROCESS_NAME);
   if (existing) {
     ok(`already installed (pm2 process "${PM2_PROCESS_NAME}", status=${existing.pm2_env?.status ?? 'unknown'})`);
     // Refresh config in case install was re-run with new flags — but
     // don't tear down the live process. Operators wanting a port change
-    // should `uninstall` then `install`.
+    // should `uninstall` then `install` (or pass --redeploy).
     writeConfig({ port, dataDir, registeredAt: readConfig()?.registeredAt ?? new Date().toISOString() });
+    if (!noUi) cmdInstallUi(ctx, { uiPort, uiHost });
     return 0;
   }
@@ -309,6 +597,25 @@ function cmdInstall(args, ctx) {
   writeConfig({ port, dataDir, registeredAt: new Date().toISOString() });
   ok(`installed: pm2 process "${PM2_PROCESS_NAME}" on port ${port} (data: ${dataDir})`);
   ok(`url: postgres://localhost:${port}/postgres`);
+  if (noUi) {
+    note('--no-ui set; skipping console install. Run `autopg ui` on demand.');
+  } else {
+    // Generate admin password BEFORE starting the UI process, so the UI
+    // server reads admin.json on first request without a race. Print
+    // ONCE — operator must copy now or run `autopg auth rotate-admin-
+    // password` to get a new one.
+    const newPassword = ensureAdminPassword();
+    if (newPassword) {
+      process.stdout.write('\n');
+      process.stdout.write(`  🔑 ADMIN PASSWORD (printed ONCE — saved hash at ${getAdminFilePath()}):\n`);
+      process.stdout.write(`     ${newPassword}\n`);
+      process.stdout.write('\n');
+      process.stdout.write('  Browser will prompt on first access. Rotate via:\n');
+      process.stdout.write('     autopg auth rotate-admin-password\n\n');
+    }
+    cmdInstallUi(ctx, { uiPort, uiHost, refresh: redeploy });
+  }
   return 0;
 }
@@ -320,9 +627,13 @@ function cmdInstall(args, ctx) {
  * downstream service still depends on the data.
  */
 function cmdUninstall() {
+  // Delete the daemon first — it's the load-bearing process and the order
+  // of "what existed at uninstall start" is determined by the daemon's
+  // pm2 registry, not the UI's. UI cleanup follows; soft-fails if absent.
   const existing = pm2GetProcess(PM2_PROCESS_NAME);
   if (!existing) {
     ok(`not registered under pm2 (nothing to uninstall)`);
+    cmdUninstallUi();
     return 0;
   }
   const result = spawnSync('pm2', ['delete', PM2_PROCESS_NAME], { stdio: 'inherit' });
@@ -330,6 +641,7 @@ function cmdUninstall() {
     fail(`pm2 delete failed (exit ${result.status})`);
   }
   ok(`uninstalled (pm2 process removed; data dir preserved at ${getDataDir()})`);
+  cmdUninstallUi();
   return 0;
 }
@@ -435,6 +747,25 @@ function parseDataDir(args) {
   return path.resolve(v);
 }
+function parseUiPort(args) {
+  const i = args.indexOf('--ui-port');
+  if (i < 0) return null;
+  const v = args[i + 1];
+  if (!v) fail('--ui-port requires a value');
+  const n = Number.parseInt(v, 10);
+  if (!Number.isInteger(n) || n < 1 || n > 65535) fail(`invalid --ui-port "${v}"`);
+  return n;
+}
+function parseUiHost(args) {
+  const i = args.indexOf('--ui-host');
+  if (i < 0) return null;
+  const v = args[i + 1];
+  if (!v) fail('--ui-host requires a value');
+  // Pass through verbatim. cli-ui.cjs warns on non-loopback at bind time.
+  return v;
+}
 /**
  * One-shot migration check from `~/.pgserve/` → `~/.autopg/`. Runs once
  * per process at the top of dispatch() so every CLI entry point gets
@@ -510,6 +841,8 @@ function dispatch(subcommand, args, ctx) {
       const ui = require('./cli-ui.cjs');
       return ui.dispatch(args, { scriptPath: ctx.wrapperPath });
     }
+    case 'auth':
+      return cmdAuthDispatch(args);
     default:
       throw new Error(`pgserve: dispatch called with unknown subcommand "${subcommand}"`);
   }
@@ -518,6 +851,10 @@ function dispatch(subcommand, args, ctx) {
 module.exports = {
   // Public API for the wrapper.
   dispatch,
+  // Auth surface used by cli-ui.cjs.
+  verifyAdminPassword,
+  getAdminFilePath,
+  readAdminFile,
   // Test surface.
   _internals: {
     HARDENED_DEFAULTS,
@@ -533,5 +870,9 @@ module.exports = {
     getEffectiveSupervision,
     parsePort,
     parseDataDir,
+    generateAdminPassword,
+    hashAdminPassword,
+    writeAdminFile,
+    ensureAdminPassword,
   },
 };

package/src/cli-ui.cjs CHANGED Viewed

@@ -80,11 +80,15 @@ function parseArgs(args) {
     } else if (a === '--no-open') {
       out.noOpen = true;
     } else if (a === '--host') {
-      // Defense: still bind 127.0.0.1 unless explicitly opted out via env.
-      // We accept --host for parity but ignore non-loopback values.
       const v = args[++i];
-      if (v === '127.0.0.1' || v === 'localhost') {
-        out.host = v;
+      out.host = v;
+      // Loud warning on non-loopback. The console has no auth, no TLS —
+      // exposing it on the LAN means any host on the network reads your
+      // settings file. Accepted (operator opted in) but flagged.
+      if (v !== '127.0.0.1' && v !== 'localhost') {
+        process.stderr.write(
+          `autopg ui: WARNING binding to ${v} (not loopback) — console has no auth, anyone reaching this address can read settings\n`,
+        );
       }
     }
   }
@@ -142,8 +146,25 @@ function listenWithFallback(server, host, preferredPort) {
  * via npm the `files` allowlist preserves the layout.
  */
 function resolveConsoleRoot() {
-  // src/ → repo root → console/
-  return path.resolve(__dirname, '..', 'console');
+  // After autopg-console-dist (v2.2.2): the SPA ships pre-bundled in
+  // console/dist/ instead of as flat .jsx files at console/. Prefer dist/;
+  // fall back to console/src/ for repo-checkout dev mode (where dist/ is
+  // gitignored and only built on demand).
+  const consoleParent = path.resolve(__dirname, '..', 'console');
+  const distRoot = path.join(consoleParent, 'dist');
+  if (fs.existsSync(distRoot)) return distRoot;
+  const srcRoot = path.join(consoleParent, 'src');
+  if (fs.existsSync(srcRoot)) {
+    process.stderr.write(
+      'autopg ui: running unbuilt sources from console/src/ — run `bun run console:build` for production behavior\n',
+    );
+    return srcRoot;
+  }
+  throw new Error(
+    'console assets not found: expected console/dist/ (run `bun run console:build`) or console/src/ (repo checkout)',
+  );
 }
 /**
@@ -445,12 +466,66 @@ function serveFile(res, filePath) {
  * `bin/pgserve-wrapper.cjs` (used for shell-outs). `ctx.consoleRoot`
  * defaults to the repo's `console/` directory.
  */
+// Lazy-load the auth verifier to avoid a require cycle with cli-install.
+function getAuthVerifier() {
+  try {
+    return require('./cli-install.cjs').verifyAdminPassword;
+  } catch {
+    return () => false;
+  }
+}
+/**
+ * Basic Auth gate. Returns true if the request is authorized (or auth is
+ * disabled via env), false if the response has been sent (401). The handler
+ * MUST stop processing when this returns false.
+ */
+function requireAuth(req, res) {
+  // Escape hatch: AUTOPG_DISABLE_AUTH=1 only honored when bound loopback.
+  // The startServer loop binds to opts.host (default 127.0.0.1); this check
+  // refuses the bypass when the request's interface isn't loopback to keep
+  // it useful for CI/tests but useless for accidentally-exposed UIs.
+  if (process.env.AUTOPG_DISABLE_AUTH === '1') {
+    const remote = req.socket?.remoteAddress || '';
+    if (remote === '127.0.0.1' || remote === '::1' || remote === '::ffff:127.0.0.1') {
+      return true;
+    }
+  }
+  const verify = getAuthVerifier();
+  const header = req.headers['authorization'] || '';
+  const m = /^Basic\s+([A-Za-z0-9+/=]+)\s*$/.exec(header);
+  if (m) {
+    const decoded = Buffer.from(m[1], 'base64').toString('utf8');
+    const colonIdx = decoded.indexOf(':');
+    if (colonIdx >= 0) {
+      // Username is ignored — single-tenant tool. Only the password matters.
+      const pw = decoded.slice(colonIdx + 1);
+      if (verify(pw)) return true;
+    }
+  }
+  res.writeHead(401, {
+    'www-authenticate': 'Basic realm="autopg console"',
+    'content-type': 'text/plain; charset=utf-8',
+    'cache-control': 'no-store',
+  });
+  res.end(
+    'autopg console requires authentication.\n' +
+      'Username: any (e.g. "admin")\n' +
+      'Password: see the value printed by `autopg install` or run `autopg auth rotate-admin-password`.\n',
+  );
+  return false;
+}
 function createHandler(ctx = {}) {
   const consoleRoot = ctx.consoleRoot || resolveConsoleRoot();
   return function handler(req, res) {
     const url = req.url || '/';
     const method = req.method || 'GET';
+    if (!requireAuth(req, res)) return;
     if (url.startsWith('/api/')) {
       if (url === '/api/settings' && method === 'GET') return handleGetSettings(req, res);
       if (url === '/api/settings' && method === 'PUT') return handlePutSettings(req, res);