@240xu/dsh-websearch 2.8.2 → 2.8.4

package/lib/settings-api.js

@@ -0,0 +1,277 @@
+/**
+ * Fenced settings bridge for the browser settings card.
+ *
+ * The card needs three things from the host: the resolved value of every
+ * field, the revision that guards concurrent saves, and a way to write path
+ * ops back into the same profile entry the provider reads. On the 0.2.x
+ * settings line there is no `settingsScope` client service and the settings
+ * shell renders client slot sections only — so this module servers that data
+ * over the plugin's own HTTP surface instead.
+ *
+ * Data flow: the host keeps plugin config in its `settings` service
+ * (`SettingsForms.describe` / `mutate`, keyed by the profile entry id). This
+ * route is a thin bridge to it: writes land in the volatile config entry the
+ * provider resolves from on the next call, so there is no second store and no
+ * out-of-band state. Mutations are validated against the plugin's own schema
+ * here because the host only checks the volatile path, not the value shape.
+ *
+ * Both routes sit behind the host connection admission fence (the same
+ * decision the kernel applies to its own `/api` routes, including the browser
+ * auth cookie), so a LAN or tunnel page holding a valid session can save
+ * settings, and nothing weaker than the app can.
+ *
+ *   GET  /api/unified-search/settings -> { ok, namespace, writable, revision,
+ *                                          value, base, user, reason? }
+ *   POST /api/unified-search/settings -> { ok } + fresh payload on success,
+ *                                        409 { code: 'SETTINGS_CONFLICT' },
+ *                                        400 invalid op value/field,
+ *                                        503 settings service unavailable.
+ *
+ * Headless / CI profiles never mount `webServer`, so registration is skipped
+ * and nothing here runs.
+ *
+ * @module lib/settings-api.js
+ */
+import { rejectionFor } from "./trust.js";
+
+const SETTINGS_PATH = "/api/unified-search/settings";
+const MAX_BODY_BYTES = 64 * 1024;
+const MAX_OPS = 64;
+/**
+ * Field names the card owns. Used only to find the profile entry in
+ * `describe()` output — never as a whitelist; the whitelist is the live
+ * `Config.dict`, so schema growth is picked up without touching this file.
+ */
+const DISCOVERY_FIELDS = ["numResults", "backendTimeoutMs", "enabledBackends", "enableExa"];
+
+/**
+ * Register the (exact) settings route on the late-mounted webServer.
+ * @param {{ register?: (route: { kind: string, path: string, handler: Function }) => void }} ws
+ * @param {{ getSettings: () => unknown, getConfig: () => unknown, getConnection?: () => unknown }} deps
+ */
+export function registerSettingsRoutes(ws, deps) {
+  if (!ws || typeof ws.register !== "function") return;
+  ws.register({
+    kind: "exact",
+    path: SETTINGS_PATH,
+    handler: guarded(deps, (req, res) => {
+      const url = new URL(String(req.url ?? "/"), "http://localhost");
+      if (url.pathname !== SETTINGS_PATH) {
+        sendJson(res, 404, { ok: false, error: "not found" });
+        return;
+      }
+      if (req.method === "GET" || req.method === "HEAD") {
+        const payload = describe(deps);
+        sendJson(res, payload.ok ? 200 : 503, payload);
+        return;
+      }
+      if (req.method === "POST") {
+        void write(req, res, deps);
+        return;
+      }
+      res.setHeader("allow", "GET, POST");
+      sendJson(res, 405, { ok: false, error: "method not allowed (GET/POST)" });
+    }),
+  });
+}
+
+/* ------------------------------------------------------------------ */
+/* handlers                                                            */
+/* ------------------------------------------------------------------ */
+
+function guarded(deps, handler) {
+  return (req, res) => {
+    const rejection = rejectionFor(req, typeof deps.getConnection === "function" ? deps.getConnection() : undefined);
+    if (rejection !== undefined) {
+      sendJson(res, rejection, { ok: false, error: rejection === 503 ? "admission unavailable" : "untrusted request" });
+      return;
+    }
+    Promise.resolve()
+      .then(() => handler(req, res))
+      .catch((err) => {
+        const status = err && Number.isInteger(err.status) ? err.status : 500;
+        sendJson(res, status, { ok: false, error: sanitize(err) });
+      });
+  };
+}
+
+/** Read the plugin's volatile form snapshot from the host settings service. */
+function describe(deps) {
+  const settings = typeof deps.getSettings === "function" ? deps.getSettings() : undefined;
+  if (settings === undefined || settings === null || typeof settings.describe !== "function") {
+    return { ok: false, writable: false, reason: "settings-unavailable" };
+  }
+  let descriptors;
+  try {
+    descriptors = settings.describe();
+  } catch {
+    return { ok: false, writable: false, reason: "settings-unavailable" };
+  }
+  const view = findNamespace(descriptors);
+  if (view === undefined) return { ok: false, writable: false, reason: "namespace-not-found" };
+  return {
+    ok: true,
+    namespace: view.ns,
+    writable: true,
+    applies: view.applies,
+    revision: view.revision,
+    value: view.value,
+    base: view.base,
+    user: view.user,
+  };
+}
+
+/**
+ * Locate this plugin's descriptor: first by shape (the card's own fields
+ * present in the resolved value), then by the profile entry id this package's
+ * bundle patch inserts. Shape-first survives a renamed insert id; the literal
+ * survives a host that reports an empty value.
+ */
+function findNamespace(descriptors) {
+  if (!Array.isArray(descriptors)) return undefined;
+  const rows = descriptors.filter((row) => row !== null && typeof row === "object" && typeof row.ns === "string");
+  return rows.find((row) => row.value !== undefined && row.value !== null
+      && typeof row.value === "object" && DISCOVERY_FIELDS.some((key) => Object.hasOwn(row.value, key)))
+    ?? rows.find((row) => row.ns === "dsh-websearch");
+}
+
+async function write(req, res, deps) {
+  const type = String(req.headers["content-type"] ?? "").toLowerCase();
+  if (!type.includes("application/json")) {
+    sendJson(res, 400, { ok: false, error: "content-type must be application/json" });
+    return;
+  }
+  let body;
+  try {
+    body = JSON.parse(await readBody(req));
+  } catch (err) {
+    sendJson(res, err && Number.isInteger(err.status) ? err.status : 400, { ok: false, error: sanitize(err) || "request body is not valid JSON" });
+    return;
+  }
+  if (body === null || typeof body !== "object" || Array.isArray(body)) {
+    sendJson(res, 400, { ok: false, error: "request body must be a JSON object" });
+    return;
+  }
+  const wanted = Array.isArray(body.ops) ? body.ops : undefined;
+  if (wanted === undefined || wanted.length === 0 || wanted.length > MAX_OPS) {
+    sendJson(res, 400, { ok: false, error: `ops must be a non-empty array of at most ${MAX_OPS} entries` });
+    return;
+  }
+  const settings = typeof deps.getSettings === "function" ? deps.getSettings() : undefined;
+  if (settings === undefined || settings === null || typeof settings.mutate !== "function") {
+    sendJson(res, 503, { ok: false, error: "settings service unavailable" });
+    return;
+  }
+  const config = typeof deps.getConfig === "function" ? deps.getConfig() : undefined;
+  const fields = config !== undefined && config !== null && config.dict !== undefined && config.dict !== null
+    ? config.dict
+    : {};
+  const ops = [];
+  for (const raw of wanted) {
+    const parsed = validateOp(raw, fields);
+    if (typeof parsed === "string") {
+      sendJson(res, 400, { ok: false, error: parsed });
+      return;
+    }
+    ops.push(parsed);
+  }
+  const view = findNamespace(safeDescribe(settings));
+  if (view === undefined) {
+    sendJson(res, 503, { ok: false, error: "settings namespace unavailable" });
+    return;
+  }
+  const expected = Number.isInteger(body.expectedRevision) ? body.expectedRevision : undefined;
+  try {
+    await settings.mutate(view.ns, ops, expected);
+  } catch (err) {
+    if (isConflict(err)) {
+      sendJson(res, 409, { ok: false, code: "SETTINGS_CONFLICT", error: "settings changed elsewhere; reload and retry" });
+      return;
+    }
+    sendJson(res, 400, { ok: false, error: sanitize(err) || "settings write failed" });
+    return;
+  }
+  const payload = describe(deps);
+  sendJson(res, payload.ok ? 200 : 503, payload);
+}
+
+/**
+ * Shape-check one path op against the live schema. The host validates only
+ * that the path is inside the volatile subtree; a wrong-typed value would be
+ * written into the profile patch and break the entry's next reload, so the
+ * value must be validated here.
+ * @returns {object|string} the op to forward, or a fixed reason string
+ */
+function validateOp(raw, fields) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return "ops entries must be objects";
+  const op = raw.op === "set" || raw.op === "unset" ? raw.op : undefined;
+  if (op === undefined) return "unsupported op (expected set|unset)";
+  const path = Array.isArray(raw.path) ? raw.path : undefined;
+  if (path === undefined || path.length !== 1 || typeof path[0] !== "string" || path[0] === "") {
+    return "path must be a one-element array holding a field name";
+  }
+  const field = path[0];
+  if (!Object.hasOwn(fields, field)) return `unknown settings field "${field}"`;
+  if (op === "unset") return { op, path: [field] };
+  if (!Object.hasOwn(raw, "value")) return `op "set" on "${field}" requires a value`;
+  const schema = fields[field];
+  if (typeof schema !== "function") return `field "${field}" is not writable`;
+  let checked;
+  try {
+    checked = schema(raw.value);
+  } catch {
+    return `invalid value for "${field}"`;
+  }
+  return { op, path: [field], value: checked };
+}
+
+function isConflict(err) {
+  if (err === null || err === undefined) return false;
+  if (typeof err === "object" && typeof err.code === "string" && err.code === "SETTINGS_CONFLICT") return true;
+  const message = typeof err === "object" && "message" in err ? String(err.message) : String(err);
+  return /SETTINGS_CONFLICT/.test(message);
+}
+
+function safeDescribe(settings) {
+  try {
+    return settings.describe();
+  } catch {
+    return undefined;
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* plumbing                                                            */
+/* ------------------------------------------------------------------ */
+
+function readBody(req) {
+  return new Promise((resolveBody, rejectBody) => {
+    const chunks = [];
+    let size = 0;
+    req.on("data", (chunk) => {
+      size += chunk.length;
+      if (size > MAX_BODY_BYTES) {
+        const oversize = new Error("request body too large");
+        oversize.status = 413;
+        rejectBody(oversize);
+        req.removeAllListeners("data");
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => resolveBody(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", rejectBody);
+  });
+}
+
+function sendJson(res, status, payload) {
+  if (res.writableEnded === true) return;
+  res.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
+  res.end(JSON.stringify(payload));
+}
+
+/** Fixed-shape diagnostics only: never echo header text or raw error details. */
+function sanitize(err) {
+  const raw = err === null || err === undefined ? "" : String(err && err.message ? err.message : err);
+  return raw.replace(/\s+/g, " ").trim().slice(0, 160);
+}

package/lib/trust.js

@@ -0,0 +1,179 @@
+/**
+ * Request trust fence for the plugin's HTTP surface.
+ *
+ * The plugin registers a prefix *longer* than the kernel's `/api`, and webServer
+ * dispatch is longest-prefix-wins — so these routes run before the connection
+ * service's own admission check and would otherwise answer any loopback caller.
+ * That was measured and documented as an open boundary; this module closes it.
+ *
+ * Two layers, tried in order:
+ *
+ * 1. the composition's own `connection` service when present — the exact
+ *    admission decision the kernel applies to its `/api` routes (trust fence
+ *    plus browser-auth cookie), so the plugin is never weaker than the app;
+ * 2. a structural replica of that fence for compositions without the service:
+ *    loopback host only, no cross-site fetches, and an `Origin`/`Referer` that
+ *    matches the `Host` authority whenever the client supplies one, with a
+ *    narrow exception for the desktop's dsh-app://app relay Referer.
+ *
+ * @module src/trust.js
+ */
+
+/** Hostnames a same-machine caller can legitimately use. */
+const LOOPBACK_NAMES = new Set(['127.0.0.1', '[::1]', '::1', 'localhost'])
+
+/**
+ * Is this address one a same-machine caller can reach — i.e. may the forward
+ * listener bind it? The lanes are keyed to this machine's egress and priced
+ * against whoever shares it, so binding a routable interface would hand the
+ * quota to the whole subnet on the strength of a string in a settings file.
+ */
+export function isLoopbackHost(value) {
+  const authority = authorityOf(String(value ?? ''), 'http')
+  return authority !== null && LOOPBACK_NAMES.has(authority.hostname)
+}
+
+/**
+ * The fence's view of one connection service, keyed under `admit` (issue #89).
+ *
+ * The composition may publish `connection` long after plugins have loaded, so
+ * index.js reads it per request through this late-binding view. Hosts before
+ * dsh 0.1.7 carry the same decision as `requestRejection`: the view maps that
+ * method onto `admit` instead of wrapping a property that does not exist —
+ * the wrapping call used to throw inside the fence and read as 503 admission
+ * unavailable on every request. A bare status travels as the `{rejection}`
+ * envelope `rejectionFor` unwraps: handed through bare, an object-shaped
+ * return reads as "no rejection" and switches the host's authentication off.
+ *
+ * Exported so the tests exercise the real view rather than a replica that can
+ * drift from it.
+ *
+ * @param {object|(() => object|undefined)} service - the harness `connection`
+ *   service, or a thunk resolving it per request (the composition may publish
+ *   it long after plugins have loaded)
+ * @returns {{admit: (req: object) => ({rejection: number}|undefined)|undefined}|{admit: undefined}}
+ */
+export function connectionAdmissionView(service) {
+  return {
+    get admit() {
+      const current = typeof service === 'function' ? service() : service
+      if (current === undefined) return undefined
+      if (typeof current.admit !== 'function' && typeof current.requestRejection === 'function') {
+        return req => {
+          const status = current.requestRejection(req)
+          return status === undefined ? undefined : { rejection: status }
+        }
+      }
+      return req => current.admit(req)
+    },
+  }
+}
+
+/**
+ * Decide one request. Returns an HTTP status to reject with, or `undefined` to
+ * let the handler run.
+ *
+ * @param {import('node:http').IncomingMessage} req
+ * @param {object|undefined} connection - the harness `connection` service, when the composition mounts one
+ * @param {(decision: {status: number, source: string, reason: string}) => void} [onRejection]
+ *   fixed diagnostic fields only; never request headers or error text
+ * @returns {number|undefined}
+ */
+export function rejectionFor(req, connection, onRejection) {
+  let decision
+  try {
+    // Hosts before dsh 0.1.7 publish the same decision under the older name
+    // `requestRejection` (issue #89): `admit` is undefined there, and the
+    // service *exists*, so an empty read must fall through to that method —
+    // treating it as a fault turned every request into 503 admission
+    // unavailable. The return value is a bare status on that spelling and an
+    // `{rejection}` envelope on `admit`.
+    const admit = connection?.admit
+    if (typeof admit === 'function') {
+      const admission = admit.call(connection, req)
+      const status = admission && typeof admission === 'object' ? admission.rejection : undefined
+      if (status === undefined) return undefined
+      decision = { status, source: 'connection', reason: 'host-rejected' }
+    } else {
+      const reject = connection?.requestRejection
+      if (typeof reject === 'function') {
+        const status = reject.call(connection, req)
+        if (status === undefined) return undefined
+        decision = { status, source: 'connection', reason: 'host-rejected' }
+      }
+    }
+  } catch {
+    // Never bypass browser authentication when a mounted Host service fails.
+    decision = { status: 503, source: 'connection', reason: 'admission-error' }
+  }
+  if (decision === undefined) {
+    const reason = structuralReason(req)
+    if (reason === undefined) return undefined
+    decision = { status: 403, source: 'structural', reason }
+  }
+  try {
+    onRejection?.(decision)
+  } catch {
+    // Diagnostics are observational; a logger cannot change the HTTP decision.
+  }
+  return decision.status
+}
+
+/**
+ * The replica fence. Same shape as the kernel's `isTrustedApiRequest`: DNS
+ * rebinding defence via the Host header, cross-site fetch refusal, and an
+ * Origin/Referer authority match.
+ */
+export function structuralRejection(req) {
+  return structuralReason(req) === undefined ? undefined : 403
+}
+
+/** Return a fixed reason without exposing caller-supplied strings. */
+function structuralReason(req) {
+  const host = authorityOf(req.headers.host, 'http')
+  if (host === null || !LOOPBACK_NAMES.has(host.hostname)) return 'host-not-loopback'
+  const site = String(req.headers['sec-fetch-site'] ?? '').toLowerCase()
+  if (site === 'cross-site') return 'cross-site'
+  for (const header of ['origin', 'referer']) {
+    const raw = req.headers[header]
+    if (typeof raw !== 'string' || raw.trim() === '') continue
+    if (header === 'referer' && isDesktopRelayReferer(raw)) {
+      // Desktop forwardWebRequest strips both browser markers before relaying
+      // to HTTP loopback, but retains this Referer. It is not an Origin grant
+      // and never overrides a mounted Host's authentication decision.
+      if (req.headers.origin !== undefined || req.headers['sec-fetch-site'] !== undefined) return 'desktop-relay-markers'
+      continue
+    }
+    const authority = authorityOf(raw.trim())
+    if (authority === null) return `${header}-invalid`
+    // The web server speaks plain http on a loopback bind, so an Origin that
+    // claims https — or any other scheme — is not this page.
+    if (authority.scheme !== host.scheme || authority.hostname !== host.hostname || authority.port !== host.port) return `${header}-mismatch`
+  }
+  return undefined
+}
+
+/** Only the owned application page, never arbitrary custom-protocol pages. */
+function isDesktopRelayReferer(value) {
+  try {
+    const url = new URL(value)
+    return url.protocol === 'dsh-app:' && url.hostname === 'app' && url.port === ''
+      && url.username === '' && url.password === ''
+  } catch {
+    return false
+  }
+}
+
+/** Split a Host/Origin/Referer value into {scheme, hostname, port}, defaulting the port. */
+function authorityOf(value, defaultScheme) {
+  if (typeof value !== 'string' || value.trim() === '') return null
+  let url
+  try {
+    url = new URL(value.includes('://') ? value.trim() : `${defaultScheme ?? 'http'}://${value.trim()}`)
+  } catch {
+    return null
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') return null
+  const port = url.port === '' ? (url.protocol === 'https:' ? '443' : '80') : url.port
+  return { scheme: url.protocol.replace(':', ''), hostname: url.hostname.toLowerCase(), port }
+}