red-pen-hub 0.7.0

package/src/server.js

@@ -0,0 +1,861 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Red Pen Hub - the PRO combined project dashboard.
+ *
+ * A local-only Express app that aggregates Red Pen review notes from every
+ * project and every surface into one board. It reads note stores via adapters
+ * and normalizes them to the shared Red Pen note model (see RED-PEN-SPEC.md in
+ * red-pen-express). No SaaS, no phone-home: it only reads stores you point it at.
+ *
+ * The board is driven by a CURATED source list in sources.json. The PRO
+ * "Add Projects" flow scans a dev directory, detects every Red Pen install
+ * regardless of platform, and lets you pick which to add:
+ *   - file stores  (.redpen/notes.json)  -> Express, static export, Ableton
+ *   - WordPress    (wp-config.php + the wp-red-pen plugin) -> wp-rest adapter
+ *
+ * Write-back (v0.3): resolve / reopen a note from the board and the Hub pushes
+ * the status to its real source - file store, connected push store, or the WP
+ * plugin's REST status route (Application Password auth).
+ */
+
+const express = require('express');
+const http = require('http');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+
+// ---------------------------------------------------------------------------
+// Runtime data directory. The Hub writes ALL of its state - sources.json (which
+// holds the hub token, the PRO license key, and live WP Application Passwords),
+// plus the connected/ push stores - into a PER-USER data dir, NOT next to its own
+// code. That separation is what lets the Hub run from a read-only npm cache
+// (`npx red-pen-hub`) or a baked single-file executable, where the app folder
+// itself is not writable.
+//   Windows:      %APPDATA%\red-pen-hub
+//   macOS/Linux:  $XDG_CONFIG_HOME/red-pen-hub  (else ~/.config/red-pen-hub)
+// Override with the RED_PEN_HUB_DATA env var for portable / testing setups.
+// PKG_DIR is the (possibly read-only) app folder - used only for shipped assets
+// and the one-time migration of legacy in-app state.
+// ---------------------------------------------------------------------------
+const PKG_DIR = path.resolve(__dirname, '..');
+function resolveDataDir() {
+  if (process.env.RED_PEN_HUB_DATA) return path.resolve(process.env.RED_PEN_HUB_DATA);
+  const home = os.homedir();
+  if (process.platform === 'win32') {
+    return path.join(process.env.APPDATA || path.join(home, 'AppData', 'Roaming'), 'red-pen-hub');
+  }
+  return path.join(process.env.XDG_CONFIG_HOME || path.join(home, '.config'), 'red-pen-hub');
+}
+const DATA_DIR = resolveDataDir();
+const CONFIG_PATH = path.join(DATA_DIR, 'sources.json');
+const CONNECTED_DIR = path.join(DATA_DIR, 'connected');
+
+function ensureDataDir() {
+  try { fs.mkdirSync(DATA_DIR, { recursive: true }); } catch (e) { /* surfaced on first write */ }
+  try { fs.mkdirSync(CONNECTED_DIR, { recursive: true }); } catch (e) { /* ignore */ }
+}
+
+// One-time migration: versions <= 0.6.5 stored state next to the code. On an
+// in-place upgrade, if the new data dir has no sources.json yet but a legacy
+// in-app one exists, carry it (and the connected/ stores) over so every source,
+// the hub token, and the saved license key survive the move. Best-effort and
+// idempotent - it only ever fills gaps, never overwrites new-location state.
+function migrateLegacyState() {
+  const legacyCfg = path.join(PKG_DIR, 'sources.json');
+  if (legacyCfg !== CONFIG_PATH && !fs.existsSync(CONFIG_PATH) && fs.existsSync(legacyCfg)) {
+    try {
+      fs.copyFileSync(legacyCfg, CONFIG_PATH);
+      try { fs.chmodSync(CONFIG_PATH, 0o600); } catch (e) { /* best-effort */ }
+      console.log('Red Pen Hub: migrated sources.json into ' + DATA_DIR);
+    } catch (e) { /* best-effort */ }
+  }
+  const legacyConn = path.join(PKG_DIR, 'connected');
+  if (legacyConn !== CONNECTED_DIR && fs.existsSync(legacyConn)) {
+    try {
+      for (const f of fs.readdirSync(legacyConn)) {
+        if (!f.endsWith('.json')) continue;
+        const dest = path.join(CONNECTED_DIR, f);
+        if (!fs.existsSync(dest)) fs.copyFileSync(path.join(legacyConn, f), dest);
+      }
+    } catch (e) { /* best-effort */ }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Config (read + write - the Add Projects flow persists here)
+// ---------------------------------------------------------------------------
+function loadConfig() {
+  // Real, saved config lives in the per-user data dir. A fresh install has none
+  // and starts empty (no baked-in sources, no machine-specific scan path) - the
+  // shipped sources.example.json is documentation only, never loaded as state.
+  try { return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8')); }
+  catch (e) { return {}; }
+}
+
+function saveConfig(cfg) {
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2) + '\n', 'utf8');
+  // sources.json holds live WP Application Passwords + the hub token; restrict it to
+  // the owner. Best-effort: on Windows chmod maps to limited ACL bits, but it is a
+  // no-op-safe hardening on POSIX and never throws the request.
+  try { fs.chmodSync(CONFIG_PATH, 0o600); } catch (e) { /* best-effort */ }
+}
+
+ensureDataDir();
+migrateLegacyState();
+let cfg = loadConfig();
+const PORT = process.env.PORT || cfg.port || 3900;
+
+// A shared token sites use to push to this Hub (the "connect" credential).
+// Generated once, persisted, never phoned home anywhere.
+if (!cfg.hubToken) { cfg.hubToken = crypto.randomBytes(16).toString('hex'); saveConfig(cfg); }
+
+// ---------------------------------------------------------------------------
+// PRO license gate (offline Ed25519 signed key). The SAME key that unlocks the
+// WordPress plugin unlocks the Hub - verified locally against the embedded public
+// key, no phone-home, no expiry, no revocation. Unlicensed, the board aggregates
+// up to FREE_PROJECT_CAP projects (a real try-before-buy); a valid key lifts the
+// cap to unlimited. The public key can only verify, never mint - safe to ship.
+// ---------------------------------------------------------------------------
+const PRO_PUBKEY_B64 = 'wFHUq3h8K8Kw8zKfpN7sjFT49529e8ACkbXJYmnR8h4=';
+const FREE_PROJECT_CAP = 3;
+// Reconstruct an Ed25519 SPKI public key from the raw 32 bytes (12-byte DER prefix
+// + the raw key), so Node's crypto verifies the SAME keys PHP's libsodium signs against.
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+function b64urlToBuf(s) { return Buffer.from(String(s || '').replace(/-/g, '+').replace(/_/g, '/'), 'base64'); }
+// Verify a license key ("base64url(email|YYYYMMDD).base64url(sig)"). Returns { email } or null.
+function verifyLicense(key) {
+  key = String(key || '').trim();
+  if (!key || (key.split('.').length !== 2)) return null;
+  try {
+    const [pEnc, sEnc] = key.split('.');
+    const payload = b64urlToBuf(pEnc), sig = b64urlToBuf(sEnc);
+    const rawPub = Buffer.from(PRO_PUBKEY_B64, 'base64');
+    if (sig.length !== 64 || rawPub.length !== 32) return null;
+    const pubKey = crypto.createPublicKey({ key: Buffer.concat([ED25519_SPKI_PREFIX, rawPub]), format: 'der', type: 'spki' });
+    if (!crypto.verify(null, payload, pubKey, sig)) return null;
+    const email = payload.toString('utf8').split('|')[0];
+    return email ? { email } : null;
+  } catch (e) { return null; }
+}
+// Live license status off the stored key (single source of truth, no drift).
+function licenseStatus() {
+  const info = verifyLicense(cfg.licenseKey || '');
+  return { licensed: !!info, email: info ? info.email : null, projectCap: FREE_PROJECT_CAP };
+}
+// Default directory the Add Projects scanner prefills. Once a user has saved a
+// scan root (or has any config), that wins; on a truly fresh install there is no
+// machine to guess, so fall back to the working directory the Hub was launched
+// from - for `npx red-pen-hub` that is the dev's own project folder.
+function scanRoots() {
+  const roots = cfg.scanRoots || cfg.discover;
+  if (roots && roots.length) return roots;
+  return [process.cwd()];
+}
+function sourcesList() { return Array.isArray(cfg.sources) ? cfg.sources : []; }
+
+// Repo path map: project name -> local working-tree path. The Hub runs git checks
+// there so the Sources tab can show each project's clean / dirty git status.
+function repoPaths() { return (cfg.repoPaths && typeof cfg.repoPaths === 'object') ? cfg.repoPaths : {}; }
+
+function gitStatusFor(repoPath) {
+  if (!repoPath) return { hasPath: false };
+  if (!fs.existsSync(repoPath)) return { hasPath: true, exists: false, path: repoPath };
+  function git(args) {
+    return execFileSync('git', ['-C', repoPath].concat(args), { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 }).trim();
+  }
+  try {
+    if (git(['rev-parse', '--is-inside-work-tree']) !== 'true') {
+      return { hasPath: true, exists: true, path: repoPath, isRepo: false };
+    }
+    let branch = '(detached)';
+    try { branch = git(['rev-parse', '--abbrev-ref', 'HEAD']); } catch (e) { /* detached */ }
+    const porcelain = git(['status', '--porcelain']);
+    const dirty = porcelain ? porcelain.split('\n').filter(Boolean).length : 0;
+    return { hasPath: true, exists: true, path: repoPath, isRepo: true, branch: branch, dirty: dirty, clean: dirty === 0 };
+  } catch (e) {
+    return { hasPath: true, exists: true, path: repoPath, isRepo: false, error: String((e && e.message) || e).slice(0, 200) };
+  }
+}
+
+// A stable key per source so the UI can dedupe / remove.
+function sourceKey(s) {
+  return (s.type === 'wp-rest' ? 'wp:' + s.url : 'file:' + path.resolve(s.path)).toLowerCase();
+}
+
+// Directories we never descend into during a scan.
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', 'vendor', 'wp-admin', 'wp-includes',
+  'dist', 'build', '.cache', '_debug'
+]);
+
+// ---------------------------------------------------------------------------
+// Normalization - everything becomes the shared Red Pen note model + metadata
+// ---------------------------------------------------------------------------
+// The id the board uses to address a note for write-back. Must match the raw
+// note exactly so setStatusInFile() can find it again - keep this the single
+// source of truth for note identity (used by normalizeNote + write-back).
+function noteId(raw) {
+  raw = raw || {};
+  return String(raw.id != null ? raw.id : (raw.created != null ? raw.created : Math.abs(hashStr(JSON.stringify(raw)))));
+}
+
+function normalizeNote(raw, meta) {
+  raw = raw || {};
+  return {
+    id: noteId(raw),
+    body: raw.body || raw.text || raw.note || '',
+    type: raw.type || 'note',
+    typeColor: raw.typeColor || '',
+    priority: raw.priority || 'normal',
+    // WP emits both a raw post_status (wprp_resolved) and a normalized statusKey
+    // (open/progress/resolved); prefer the normalized one so the board buckets it
+    // correctly. file/static stores have no statusKey, so the fallback preserves them.
+    status: raw.statusKey || raw.status || 'open',
+    page: raw.page || raw.url || '',
+    url: raw.url || raw.page || '',
+    anchor: raw.anchor || raw.selector || '',
+    createdAt: raw.createdAt || raw.created || raw.date || null,
+    // Only accept a real timestamp string here. WP sends a boolean `resolved` flag
+    // which must NOT become the Resolved date (new Date(true) is epoch+1ms).
+    resolvedAt: raw.resolvedAt || (typeof raw.resolved === 'string' ? raw.resolved : null),
+    // Identity + thread signal the source surfaces already populate (WP: author/assignee/
+    // resolvedBy + a replies array). Carried through so the board can attribute and count
+    // them; blank/0 on surfaces that don't supply them, never faked.
+    author: raw.author || '',
+    assignee: raw.assigneeName || (typeof raw.assignee === 'string' ? raw.assignee : '') || '',
+    resolvedBy: raw.resolvedBy || '',
+    replyCount: Array.isArray(raw.replies) ? raw.replies.length : (+raw.replyCount || 0),
+    // Forward-compatible fields no surface emits yet: severity (impact, distinct from
+    // priority/scheduling) and duplicate/related links. Carried + rendered only when
+    // present so they light up the moment a surface starts sending them.
+    severity: raw.severity || '',
+    dupeOf: raw.dupeOf || raw.duplicateOf || '',
+    relatedTo: raw.relatedTo || '',
+    project: meta.project,
+    surface: meta.surface,
+    source: meta.source,
+    sourceKey: meta.key || ''
+  };
+}
+
+function hashStr(s) {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) { h = (h * 31 + s.charCodeAt(i)) | 0; }
+  return h;
+}
+
+function notesFromJson(parsed) {
+  if (Array.isArray(parsed)) return parsed;
+  if (parsed && Array.isArray(parsed.notes)) return parsed.notes;
+  return [];
+}
+
+function readJsonFile(file) {
+  try { return notesFromJson(JSON.parse(fs.readFileSync(file, 'utf8'))); }
+  catch (e) { return []; }
+}
+
+// ---------------------------------------------------------------------------
+// Adapters
+// ---------------------------------------------------------------------------
+function readFileSource(file, meta) {
+  return readJsonFile(file).map((n) => normalizeNote(n, meta));
+}
+
+async function readWpRestSource(src) {
+  const meta = { project: src.label || src.url, surface: 'wordpress', source: src.url, key: sourceKey(src) };
+  const base = String(src.url).replace(/\/+$/, '');
+  // scope=all pulls every note on the site (all targets), not just the target=0
+  // site-wide default - otherwise page/post-attached notes never reach the board.
+  const endpoint = base + '/wp-json/wprp/v1/notes?scope=all';
+  const headers = { 'Accept': 'application/json' };
+  if (src.user && src.appPassword) {
+    const token = Buffer.from(src.user + ':' + src.appPassword).toString('base64');
+    headers['Authorization'] = 'Basic ' + token;
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 6000);
+  try {
+    const res = await safeFetch(endpoint, { headers }, controller.signal);
+    if (res.status === 401 || res.status === 403) {
+      return { meta, notes: [], error: 'auth (needs an Application Password)' };
+    }
+    if (!res.ok) return { meta, notes: [], error: 'HTTP ' + res.status + ' (check site URL / plugin active)' };
+    const text = await res.text();
+    let data;
+    try { data = JSON.parse(text); }
+    catch (e) { return { meta, notes: [], error: 'not a REST endpoint (check the site URL)' }; }
+    return { meta, notes: notesFromJson(data).map((n) => normalizeNote(n, meta)) };
+  } catch (e) {
+    return { meta, notes: [], error: e.name === 'AbortError' ? 'timeout (site not responding)' : String(e.message || e) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Connected stores - projects that PUSH to this Hub via /api/ingest.
+// They self-register (one JSON per project under connected/) on first push,
+// so no "add" step is needed for a connected site.
+function readConnectedStores() {
+  let files;
+  try { files = fs.readdirSync(CONNECTED_DIR).filter((f) => f.endsWith('.json')); }
+  catch (e) { return []; }
+  return files.map((f) => {
+    try {
+      const data = JSON.parse(fs.readFileSync(path.join(CONNECTED_DIR, f), 'utf8'));
+      const key = 'conn:' + f.replace(/\.json$/, '');
+      const meta = { project: data.project, surface: data.surface || 'wordpress', source: 'connected', key: key };
+      const notes = (Array.isArray(data.notes) ? data.notes : []).map((n) => normalizeNote(n, meta));
+      return { key: key, label: data.project, surface: meta.surface, notes, lastSync: data.lastSync };
+    } catch (e) { return null; }
+  }).filter(Boolean);
+}
+
+// ---------------------------------------------------------------------------
+// Aggregation - curated pull sources + connected push stores
+// ---------------------------------------------------------------------------
+async function aggregate() {
+  // Fetch all pull sources concurrently - WP fetches are time-bound so one slow
+  // site cannot stall the board.
+  const results = await Promise.all(sourcesList().map(async (src) => {
+    if (src.type === 'wp-rest') {
+      const r = await readWpRestSource(src);
+      return { notes: r.notes, source: { key: sourceKey(src), label: r.meta.project, surface: 'wordpress', source: src.url, count: r.notes.length, error: r.error } };
+    }
+    const meta = { project: src.label || src.path, surface: src.surface || 'file', source: src.path, key: sourceKey(src) };
+    const got = readFileSource(src.path, meta);
+    return { notes: got, source: { key: sourceKey(src), label: meta.project, surface: meta.surface, source: src.path, count: got.length } };
+  }));
+  const notes = [];
+  const sources = [];
+  for (const r of results) { notes.push(...r.notes); sources.push(r.source); }
+  // Connected (pushed) projects
+  for (const c of readConnectedStores()) {
+    notes.push(...c.notes);
+    sources.push({ key: c.key, label: c.label, surface: c.surface, source: 'connected (pushed)', count: c.notes.length, connected: true, lastSync: c.lastSync });
+  }
+  return { notes, sources, generatedAt: new Date().toISOString() };
+}
+
+// ---------------------------------------------------------------------------
+// Scanning (the Add Projects flow) - detect every Red Pen install under a root
+// ---------------------------------------------------------------------------
+function findRedpenStores(root, depth, out) {
+  if (depth > 7) return out;
+  let ents;
+  try { ents = fs.readdirSync(root, { withFileTypes: true }); } catch (e) { return out; }
+  for (const e of ents) {
+    if (!e.isDirectory()) continue;
+    if (SKIP_DIRS.has(e.name)) continue;
+    const dir = path.join(root, e.name);
+    if (e.name === '.redpen') {
+      const nf = path.join(dir, 'notes.json');
+      if (fs.existsSync(nf)) out.push(nf);
+    } else {
+      findRedpenStores(dir, depth + 1, out);
+    }
+  }
+  return out;
+}
+
+function findWpInstalls(root, depth, out) {
+  if (depth > 7) return out;
+  let ents;
+  try { ents = fs.readdirSync(root, { withFileTypes: true }); } catch (e) { return out; }
+  const names = new Set(ents.map((e) => e.name));
+  if (names.has('wp-config.php')) {
+    // This is a WordPress root - record if the Red Pen plugin is present, don't descend.
+    const plugin = path.join(root, 'wp-content', 'plugins', 'wp-red-pen', 'wp-red-pen.php');
+    if (fs.existsSync(plugin)) out.push(root);
+    return out;
+  }
+  for (const e of ents) {
+    if (!e.isDirectory()) continue;
+    if (SKIP_DIRS.has(e.name) || e.name === '.redpen') continue;
+    findWpInstalls(path.join(root, e.name), depth + 1, out);
+  }
+  return out;
+}
+
+// project label = path from the scan root down to the project (minus /.redpen/notes.json)
+function labelFromStore(file, root) {
+  let rel = path.relative(root, file).replace(/[\\/]\.redpen[\\/]notes\.json$/i, '');
+  rel = rel.split(path.sep).join('/');
+  return rel || path.basename(path.dirname(path.dirname(file)));
+}
+
+// express if a package.json sits anywhere from the store's project dir up to root, else static
+function inferSurface(file, root) {
+  let dir = path.dirname(path.dirname(file)); // dir holding .redpen
+  const stop = path.resolve(root);
+  for (let i = 0; i < 8; i++) {
+    if (fs.existsSync(path.join(dir, 'package.json'))) return 'express';
+    if (path.resolve(dir) === stop) break;
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return 'static';
+}
+
+const HTDOCS = 'c:\\xampp\\htdocs\\';
+function guessLocalUrl(installDir) {
+  const abs = path.resolve(installDir);
+  if (abs.toLowerCase().startsWith(HTDOCS)) {
+    const rel = abs.slice(HTDOCS.length).split(path.sep).map(encodeURIComponent).join('/');
+    return 'http://localhost/' + rel;
+  }
+  return '';
+}
+
+function scan(root) {
+  const abs = path.resolve(root);
+  const existing = new Set(sourcesList().map(sourceKey));
+  const candidates = [];
+
+  for (const file of findRedpenStores(abs, 0, [])) {
+    const key = ('file:' + path.resolve(file)).toLowerCase();
+    candidates.push({
+      key, type: 'file', label: labelFromStore(file, abs),
+      surface: inferSurface(file, abs), path: file,
+      count: readJsonFile(file).length, already: existing.has(key)
+    });
+  }
+  for (const install of findWpInstalls(abs, 0, [])) {
+    const url = guessLocalUrl(install);
+    const key = ('wp:' + url).toLowerCase();
+    candidates.push({
+      key, type: 'wp-rest', label: path.basename(install),
+      surface: 'wordpress', url, install, needsAuth: true, already: existing.has(key)
+    });
+  }
+  candidates.sort((a, b) => a.label.localeCompare(b.label));
+  return { root: abs, candidates };
+}
+
+// ---------------------------------------------------------------------------
+// Write-back - resolve / reopen a note at its real source of truth
+// ---------------------------------------------------------------------------
+function sourceByKey(key) {
+  return sourcesList().find((s) => sourceKey(s) === key) || null;
+}
+
+// Flip a note's status inside a raw notes file, preserving the file's shape
+// (a bare array, or a { notes: [...] } wrapper). Used for both file sources and
+// connected push stores. For a connected store, pass recordOverride=true so the
+// change is remembered in `_hubOverrides` and re-applied when the site pushes again
+// (applyOverrides on ingest) - otherwise the next push would silently revert it.
+function setStatusInFile(file, id, status, recordOverride) {
+  let parsed;
+  try { parsed = JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (e) { return { ok: false, error: 'could not read store' }; }
+  const arr = Array.isArray(parsed) ? parsed : (Array.isArray(parsed.notes) ? parsed.notes : null);
+  if (!arr) return { ok: false, error: 'unexpected store shape' };
+  const note = arr.find((n) => noteId(n) === id);
+  if (!note) return { ok: false, error: 'note not found in store' };
+  note.status = status;
+  // Stamp a resolved timestamp so the board can show when a note was closed;
+  // clear it if the note is reopened.
+  if (status === 'resolved') { note.resolvedAt = note.resolvedAt || new Date().toISOString(); }
+  else { delete note.resolvedAt; }
+  if (recordOverride && parsed && !Array.isArray(parsed)) {
+    parsed._hubOverrides = parsed._hubOverrides || {};
+    parsed._hubOverrides[id] = { status: status, resolvedAt: note.resolvedAt || null, at: new Date().toISOString() };
+  }
+  try { fs.writeFileSync(file, JSON.stringify(parsed, null, 2) + '\n', 'utf8'); }
+  catch (e) { return { ok: false, error: 'could not write store' }; }
+  return { ok: true };
+}
+
+// Re-apply the Hub's local status changes on top of a fresh push from a connected
+// site. For each override: if the note is gone, or the site has caught up (its pushed
+// status already matches the override), drop the override; otherwise force the Hub's
+// status/resolvedAt onto the incoming note and keep the override until the site agrees.
+// Returns the (mutated) notes plus the surviving overrides to persist.
+function applyOverrides(notes, overrides) {
+  if (!overrides) return { notes: notes, overrides: {} };
+  const byId = {};
+  notes.forEach((n) => { byId[noteId(n)] = n; });
+  const surviving = {};
+  Object.keys(overrides).forEach((id) => {
+    const ov = overrides[id];
+    const n = byId[id];
+    if (!n) return;                                   // note removed on the site - drop it
+    if (String(n.status || 'open') === String(ov.status)) return;   // site caught up - drop it
+    n.status = ov.status;
+    if (ov.status === 'resolved') { if (ov.resolvedAt) n.resolvedAt = ov.resolvedAt; }
+    else { delete n.resolvedAt; }
+    surviving[id] = ov;
+  });
+  return { notes: notes, overrides: surviving };
+}
+
+// Push a status change to a WordPress source via the wp-red-pen plugin's
+// POST /notes/{id}/status route, authenticated with the source's Application Password.
+async function setStatusWp(src, id, status) {
+  if (!src.user || !src.appPassword) return { ok: false, error: 'no Application Password set for this source' };
+  const base = String(src.url).replace(/\/+$/, '');
+  const endpoint = base + '/wp-json/wprp/v1/notes/' + encodeURIComponent(id) + '/status';
+  const token = Buffer.from(src.user + ':' + src.appPassword).toString('base64');
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), 6000);
+  try {
+    const res = await safeFetch(endpoint, {
+      method: 'POST',
+      headers: { 'Authorization': 'Basic ' + token, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ status: status })
+    }, ctrl.signal);
+    if (res.status === 401 || res.status === 403) return { ok: false, error: 'auth (Application Password lacks edit rights)' };
+    if (!res.ok) return { ok: false, error: 'HTTP ' + res.status };
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: e.name === 'AbortError' ? 'timeout (site not responding)' : String(e.message || e) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Security helpers
+// ---------------------------------------------------------------------------
+// Constant-time compare for the hub token - it is the app's only auth boundary and
+// is injected into the served board page, so a timing side-channel is worth closing.
+function tokenEq(a, b) {
+  a = String(a == null ? '' : a);
+  b = String(b == null ? '' : b);
+  if (!b || a.length !== b.length) return false;
+  try { return crypto.timingSafeEqual(Buffer.from(a), Buffer.from(b)); } catch (e) { return false; }
+}
+
+// Host allow-list: the Hub binds loopback only, so any request whose Host header is not
+// localhost/127.0.0.1/[::1] is a DNS-rebinding attempt (a hostile page resolving its own
+// name to 127.0.0.1) or misrouted. Rejecting it protects GET / (which injects the token)
+// and /api/ingest (token-body-gated, exempt from the header gate).
+function isLoopbackHost(hostHeader) {
+  let h = String(hostHeader || '').trim().toLowerCase();
+  if (!h) return false;
+  const m = h.match(/^\[([^\]]+)\](?::\d+)?$/);   // [::1]:3900
+  if (m) { h = m[1]; } else { h = h.replace(/:\d+$/, ''); }
+  return h === 'localhost' || h === '127.0.0.1' || h === '::1';
+}
+
+// The Hub deliberately fetches LOCAL dev sites (localhost / LAN WordPress installs), so
+// blocking internal addresses would break its core job. What we DO enforce on any URL
+// derived from source/note data: it must parse and be http(s) (no file:/data:/gopher:),
+// and redirects are followed manually with per-hop re-validation and a small cap - so a
+// site cannot 30x the Hub onto a hostile scheme or into a redirect loop.
+async function safeFetch(rawUrl, opts, signal) {
+  let url = String(rawUrl || '');
+  for (let hop = 0; hop < 4; hop++) {
+    let u;
+    try { u = new URL(url); } catch (e) { throw new Error('invalid URL'); }
+    if (u.protocol !== 'http:' && u.protocol !== 'https:') throw new Error('URL must be http or https');
+    const res = await fetch(u.href, Object.assign({ redirect: 'manual', signal: signal }, opts || {}));
+    if (res.status >= 300 && res.status < 400) {
+      const loc = res.headers.get('location');
+      if (!loc) return res;
+      url = new URL(loc, u).href;   // re-validate the redirect target on the next pass
+      continue;
+    }
+    return res;
+  }
+  throw new Error('too many redirects');
+}
+
+// ---------------------------------------------------------------------------
+// Server
+// ---------------------------------------------------------------------------
+const app = express();
+// Reject non-loopback Host headers before anything else (DNS-rebinding guard).
+app.use((req, res, next) => {
+  if (!isLoopbackHost(req.headers.host)) return res.status(403).json({ error: 'forbidden host' });
+  next();
+});
+app.use(express.json());
+app.use(express.static(path.join(__dirname, 'public')));
+
+// Token gate: every /api route requires the hub token in an x-hub-token header,
+// EXCEPT /api/ingest (which authenticates via the token in its JSON body so external
+// sites can push cross-origin) and CORS preflights. The board page is served with the
+// token injected, so its same-origin fetches pass; anything else on the box does not.
+app.use('/api', (req, res, next) => {
+  if (req.path === '/ingest' || req.method === 'OPTIONS') return next();
+  if (!tokenEq(req.get('x-hub-token'), cfg.hubToken)) {
+    return res.status(401).json({ error: 'unauthorized' });
+  }
+  next();
+});
+
+// Resolve a "conn:<slug>" board key to its store file under CONNECTED_DIR, hardened
+// against path traversal. Returns '' if the slug is missing or would escape the dir.
+function connFile(key) {
+  const slug = String(key || '').replace(/^conn:/, '');
+  if (!slug || !/^[a-z0-9-]+$/.test(slug)) return '';
+  const p = path.resolve(CONNECTED_DIR, slug + '.json');
+  const base = path.resolve(CONNECTED_DIR) + path.sep;
+  return p.slice(0, base.length) === base ? p : '';
+}
+
+app.get('/api/notes', async (req, res) => {
+  try {
+    const data = await aggregate();
+    const lic = licenseStatus();
+    data.license = { licensed: lic.licensed, licensedTo: lic.email, projectCap: FREE_PROJECT_CAP, totalProjects: data.sources.length, capped: false };
+    // Unlicensed: cap the board to the first FREE_PROJECT_CAP projects (keep their notes only).
+    // Sources are still fully configurable on the Sources tab; the cap is only on what the board aggregates.
+    if (!lic.licensed && data.sources.length > FREE_PROJECT_CAP) {
+      const keep = new Set(data.sources.slice(0, FREE_PROJECT_CAP).map((s) => s.key));
+      data.sources = data.sources.filter((s) => keep.has(s.key));
+      data.notes = data.notes.filter((n) => keep.has(n.sourceKey));
+      data.license.capped = true;
+    }
+    res.json(data);
+  } catch (e) { res.status(500).json({ error: String(e.message || e) }); }
+});
+
+// PRO license: read status, or save a key. The key is verified LOCALLY (offline Ed25519);
+// saving persists it to sources.json (0600). Same key as the WordPress plugin.
+app.get('/api/license', (req, res) => { res.json(licenseStatus()); });
+app.post('/api/license', (req, res) => {
+  const key = (req.body && typeof req.body.key === 'string') ? req.body.key.trim() : '';
+  cfg.licenseKey = key;
+  saveConfig(cfg);
+  const info = verifyLicense(key);
+  res.json({ licensed: !!info, email: info ? info.email : null, projectCap: FREE_PROJECT_CAP, saved: true });
+});
+
+// List curated sources + the default scan root for the modal.
+app.get('/api/sources', (req, res) => {
+  res.json({
+    sources: sourcesList().map((s) => ({ key: sourceKey(s), type: s.type, label: s.label, surface: s.surface || (s.type === 'wp-rest' ? 'wordpress' : 'file'), path: s.path, url: s.url })),
+    scanRoots: scanRoots()
+  });
+});
+
+// Scan a directory for Red Pen installs of every platform.
+app.get('/api/scan', (req, res) => {
+  const root = req.query.root || scanRoots()[0];
+  try { res.json(scan(root)); }
+  catch (e) { res.status(500).json({ error: String(e.message || e) }); }
+});
+
+// Add selected sources (the confirm step). Body: { add: [source, ...] }.
+app.post('/api/sources', (req, res) => {
+  const add = Array.isArray(req.body && req.body.add) ? req.body.add : [];
+  const have = new Set(sourcesList().map(sourceKey));
+  const next = sourcesList().slice();
+  let added = 0;
+  for (const s of add) {
+    const clean = s.type === 'wp-rest'
+      ? { type: 'wp-rest', label: s.label || s.url, url: s.url, user: s.user || '', appPassword: s.appPassword || '', surface: 'wordpress' }
+      : { type: 'file', label: s.label || s.path, path: s.path, surface: s.surface || 'file' };
+    if (!clean.url && !clean.path) continue;
+    // File sources are read (and written on status change) directly off disk, so pin the
+    // path to a resolved, existing location at add time - the board can only ever touch
+    // paths that were deliberately registered here, never an arbitrary one from a request.
+    if (clean.type === 'file') {
+      const rp = path.resolve(String(clean.path));
+      if (!fs.existsSync(rp)) continue;
+      clean.path = rp;
+    }
+    const k = sourceKey(clean);
+    if (have.has(k)) continue;
+    have.add(k); next.push(clean); added++;
+  }
+  cfg.sources = next;
+  saveConfig(cfg);
+  res.json({ added, sources: next.map((s) => ({ key: sourceKey(s), type: s.type, label: s.label })) });
+});
+
+// Remove a source by key. Body: { key }.
+app.post('/api/sources/remove', (req, res) => {
+  const key = req.body && req.body.key;
+  cfg.sources = sourcesList().filter((s) => sourceKey(s) !== key);
+  saveConfig(cfg);
+  res.json({ removed: key, sources: cfg.sources.map((s) => ({ key: sourceKey(s), type: s.type, label: s.label })) });
+});
+
+// The connect credentials a site needs to push to this Hub.
+app.get('/api/connect-info', (req, res) => {
+  res.json({ url: 'http://localhost:' + PORT, token: cfg.hubToken });
+});
+
+// Repo-path map the Hub owns - powers the passive git-status indicator in the Sources tab.
+app.get('/api/repo-paths', (req, res) => { res.json({ paths: repoPaths() }); });
+app.post('/api/repo-paths', (req, res) => {
+  const b = req.body || {};
+  cfg.repoPaths = repoPaths();
+  if (b.project) {
+    const p = String(b.path || '').trim();
+    if (p) cfg.repoPaths[b.project] = p; else delete cfg.repoPaths[b.project];
+  } else if (b.paths && typeof b.paths === 'object') {
+    cfg.repoPaths = b.paths;
+  }
+  saveConfig(cfg);
+  res.json({ paths: cfg.repoPaths });
+});
+
+// Git status for a set of projects (passive clean/dirty indicator). Body: { projects: [names] }.
+app.post('/api/git-status', (req, res) => {
+  const projects = Array.isArray(req.body && req.body.projects) ? req.body.projects : [];
+  const map = repoPaths();
+  const out = {};
+  projects.forEach((proj) => { out[proj] = gitStatusFor(map[proj]); });
+  res.json({ status: out });
+});
+
+// A connected site pushes its notes here. Body: { token, project, surface, notes }.
+// CORS for browser-based pushes (the static red-pen.js surface posts cross-origin
+// from a site's own origin to this Hub on :3900). Token-gated + local-only, so a
+// permissive origin is safe here. Preflight OPTIONS gets a bare 204.
+app.use('/api/ingest', (req, res, next) => {
+  res.header('Access-Control-Allow-Origin', '*');
+  res.header('Access-Control-Allow-Methods', 'POST, OPTIONS');
+  res.header('Access-Control-Allow-Headers', 'Content-Type');
+  if (req.method === 'OPTIONS') return res.sendStatus(204);
+  next();
+});
+
+app.post('/api/ingest', (req, res) => {
+  const b = req.body || {};
+  if (!tokenEq(b.token, cfg.hubToken)) return res.status(401).json({ error: 'invalid token' });
+  if (!b.project) return res.status(400).json({ error: 'project required' });
+  const slug = String(b.project).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'project';
+  const file = path.join(CONNECTED_DIR, slug + '.json');
+  // Re-apply any Hub-side status changes (resolve/reopen/start) recorded for this store
+  // so a push from the site doesn't silently revert them; keep the ones the site hasn't
+  // caught up to yet.
+  let prevOverrides = null;
+  try { prevOverrides = (JSON.parse(fs.readFileSync(file, 'utf8')) || {})._hubOverrides || null; } catch (e) { /* first push */ }
+  const merged = applyOverrides(Array.isArray(b.notes) ? b.notes : [], prevOverrides);
+  const payload = {
+    project: b.project,
+    surface: b.surface || 'wordpress',
+    notes: merged.notes,
+    lastSync: new Date().toISOString()
+  };
+  if (Object.keys(merged.overrides).length) payload._hubOverrides = merged.overrides;
+  fs.writeFileSync(file, JSON.stringify(payload, null, 2));
+  // Two-way sync: hand the pushing site back the status changes the Hub made to its
+  // notes (the surviving overrides), so the origin can apply them locally and reflect a
+  // Hub-side resolve/reopen/start. Each entry is { status, resolvedAt }.
+  res.json({ ok: true, project: b.project, count: payload.notes.length, held: Object.keys(merged.overrides).length, changes: merged.overrides });
+});
+
+// Write-back: set a note's status at its source. Body: { key, id, status }.
+// key is the note's sourceKey (conn:<slug> | file:<path> | wp:<url>); status is
+// one of open|progress|resolved. Routes to the right adapter by key prefix.
+app.post('/api/note-status', async (req, res) => {
+  const b = req.body || {};
+  const key = String(b.key || '');
+  const id = String(b.id || '');
+  const status = String(b.status || '');
+  if (!key || !id || !status) return res.status(400).json({ error: 'key, id and status required' });
+  if (!new Set(['open', 'progress', 'resolved']).has(status)) return res.status(400).json({ error: 'invalid status' });
+  try {
+    if (key.indexOf('conn:') === 0) {
+      const file = connFile(key);
+      if (!file) return res.status(400).json({ error: 'invalid key' });
+      const r = setStatusInFile(file, id, status, true);
+      return r.ok ? res.json({ ok: true, local: true }) : res.status(400).json(r);
+    }
+    const src = sourceByKey(key);
+    if (!src) return res.status(404).json({ error: 'unknown source' });
+    if (src.type === 'wp-rest') {
+      const r = await setStatusWp(src, id, status);
+      return r.ok ? res.json({ ok: true }) : res.status(400).json(r);
+    }
+    const r = setStatusInFile(path.resolve(src.path), id, status);
+    return r.ok ? res.json({ ok: true }) : res.status(400).json(r);
+  } catch (e) {
+    res.status(500).json({ error: String(e.message || e) });
+  }
+});
+
+// Forget a connected project. Body: { key } (the "conn:<slug>" key from the board).
+app.post('/api/connected/remove', (req, res) => {
+  const key = (req.body && req.body.key) || '';
+  const file = connFile(key);
+  if (file) { try { fs.unlinkSync(file); } catch (e) { /* gone */ } }
+  res.json({ removed: key });
+});
+
+// Refresh a connected source's display name from the live WP site title.
+// Discovers the site's REST root (the Link rel="https://api.w.org/" header on any
+// of its pages) and reads its name. Renames the store file to the new name's slug
+// so a future push updates the same store instead of creating a duplicate.
+app.post('/api/refresh-name', async (req, res) => {
+  const key = (req.body && req.body.key) || '';
+  const slug = String(key).replace(/^conn:/, '');
+  const file = connFile(key);
+  if (!file) return res.status(400).json({ error: 'invalid key' });
+  let store;
+  try { store = JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (e) { return res.status(404).json({ error: 'not a connected source' }); }
+  // A base URL to discover the WP REST root: the stored home, else any note's url.
+  let base = store.home || '';
+  if (!base) { for (const n of (store.notes || [])) { if (n && n.url) { base = n.url; break; } } }
+  if (!base) return res.json({ updated: false, error: 'no site URL to check (source has no notes yet)' });
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), 6000);
+  try {
+    let root = '';
+    try {
+      const r0 = await safeFetch(base, {}, ctrl.signal);
+      const link = r0.headers.get('link') || '';
+      const m = link.match(/<([^>]+)>;\s*rel="https:\/\/api\.w\.org\/"/);
+      root = m ? m[1] : base.replace(/\/?$/, '/') + 'wp-json/';
+    } catch (e) { root = base.replace(/\/?$/, '/') + 'wp-json/'; }
+    const r = await safeFetch(root, {}, ctrl.signal);
+    const data = await r.json();
+    const name = (data && typeof data.name === 'string') ? data.name.trim() : '';
+    if (!name) return res.json({ updated: false, error: 'the site did not return a name' });
+    if (name === store.project) return res.json({ updated: false, name });
+    store.project = name;
+    const newSlug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'project';
+    fs.writeFileSync(path.join(CONNECTED_DIR, newSlug + '.json'), JSON.stringify(store, null, 2));
+    if (newSlug !== slug) { try { fs.unlinkSync(file); } catch (e) { /* ignore */ } }
+    res.json({ updated: true, name: name, slug: newSlug });
+  } catch (e) {
+    res.json({ updated: false, error: String((e && e.message) || e).slice(0, 200) });
+  } finally { clearTimeout(timer); }
+});
+
+app.get('/', (req, res) => {
+  // Inject the hub token so the board's same-origin fetches can pass the /api gate.
+  let html = fs.readFileSync(path.join(__dirname, 'public', 'board.html'), 'utf8');
+  html = html.replace('%%HUB_TOKEN%%', String(cfg.hubToken || '').replace(/[^a-zA-Z0-9]/g, ''));
+  res.type('html').send(html);
+});
+
+// Bind to loopback only - the Hub aggregates local project notes and has no login,
+// so it must never be reachable from the LAN. Bind BOTH loopback stacks (IPv4
+// 127.0.0.1 AND IPv6 ::1): on Windows/Node `localhost` commonly resolves to ::1
+// first, so an IPv4-only bind leaves http://localhost:PORT unreachable (it hangs)
+// even though the Hub is up on 127.0.0.1. Two servers share the same (token-gated)
+// app; both are loopback-only, so the LAN is still never reachable.
+const LOOPBACKS = ['127.0.0.1', '::1'];
+let hubBound = 0;
+LOOPBACKS.forEach((host) => {
+  http.createServer(app).listen(PORT, host)
+    .on('listening', () => {
+      if (!hubBound++) {
+        console.log('Red Pen Hub running at http://localhost:' + PORT);
+        console.log('Data dir: ' + DATA_DIR);
+        console.log('Curated sources: ' + sourcesList().length + '  |  default scan root: ' + scanRoots()[0]);
+      }
+    })
+    .on('error', (e) => {
+      // A missing stack (e.g. no IPv6 on this box) is fine to skip - the other bind covers localhost.
+      if (e.code === 'EADDRNOTAVAIL' || e.code === 'EAFNOSUPPORT' || e.code === 'EINVAL') { return; }
+      if (e.code === 'EADDRINUSE') {
+        console.error('Red Pen Hub: port ' + PORT + ' already in use on ' + host + ' - is another Hub already running?');
+        return;
+      }
+      throw e;
+    });
+});