@aria-framework/ai 0.14.3 → 0.15.2

package/lmxVerify.js

@@ -0,0 +1,395 @@
+/**
+ * Does this supervisor actually work? — the four questions, asked in the only order they can be.
+ *
+ * WHY THIS EXISTS. A supervisor was saved correctly twice and looked identical both times, while the
+ * engines key sat in the status token's field. The listener answered 401, and the only place that
+ * surfaced was an HTTP code behind a button — a number that names neither credential. Saving
+ * something and finding out later whether it works is the shape of that whole failure.
+ *
+ * THE ORDER IS FORCED, and each step's failure means something the next cannot tell you:
+ *
+ *   1. reachable      — nothing below it means anything if the machine does not answer
+ *   2. certificate    — fails BEFORE any credential leaves this process, which is why its message
+ *                       says so: a pin mismatch is the whole story, and the tokens are not suspect
+ *   3. status token   — FREE. Reading the document is exactly what this credential authorises, so
+ *                       whether it works is learned as a side effect of asking
+ *   4. engines key    — authorises INFERENCE, and no amount of status reading exercises it
+ *
+ * CHECK 4 SPENDS NOTHING. The obvious way to test an inference credential is to run an inference;
+ * asking the engine's own `/models` instead authenticates against the same route with the same
+ * bearer and costs no tokens at all. An operator should never have to weigh "is my key right?"
+ * against what the answer costs.
+ *
+ * NOTHING HERE READS A DATABASE OR A KEYSTORE. Every credential arrives as an argument, which is
+ * what lets the same function serve an admin screen, a boot check and a test with a stub fetch.
+ * Where the values come from is the consuming app's business.
+ *
+ * WHAT IS NEVER DONE: a check is never reported as passed because it probably would have. When the
+ * engine list does not arrive, the engines key reads `not checked` rather than a tick — it is the
+ * credential whose failure stays invisible until a job runs, so a tick meaning "probably" is worse
+ * there than no tick at all.
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+
+const DEFAULT_TIMEOUT_MS = 6000;
+
+/** How long a verification stays on the page before it is stale enough to be misleading. */
+const REPORT_TTL_MS = 10 * 60 * 1000;
+
+/** Certificates inside this window are called out — an expired pin takes the stack out silently. */
+const EXPIRY_WARN_DAYS = 30;
+
+/**
+ * The last verification per instance, so the report survives the redirect that follows a save.
+ *
+ * NOT A FLASH. The flash partial escapes to a single line, and a per-check report is exactly the
+ * kind of result the partial's own notes warn about losing — "the only place that output appears,
+ * and a message that erases itself after three seconds would lose it with no way back". Keeping it
+ * here means it stays readable until something supersedes it, which is also what makes it useful
+ * outside the moment of saving.
+ */
+const _reports = new Map();
+
+function remember(instance, report) {
+  _reports.set(String(instance), report);
+  return report;
+}
+
+/** The last report for an instance, or null once it is old enough to mislead. */
+function lastFor(instance) {
+  const r = _reports.get(String(instance));
+  if (!r) return null;
+  if (Date.now() - new Date(r.at).getTime() > REPORT_TTL_MS) {
+    _reports.delete(String(instance));
+    return null;
+  }
+  return r;
+}
+
+function forget(instance) { _reports.delete(String(instance)); }
+
+/** Only for tests — the cache is process-wide and would otherwise leak between them. */
+function _reset() { _reports.clear(); }
+
+// ── classifying what went wrong ────────────────────────────────────────────────────────────────
+//
+// fetch() reports every transport failure as the same "fetch failed", with the real reason on
+// `cause`. Collapsing those into one message would put a certificate mismatch and an unplugged
+// network cable behind identical words, which is the confusion this whole module exists to end.
+
+const TLS_CODES = new Set([
+  'UNABLE_TO_VERIFY_LEAF_SIGNATURE', 'SELF_SIGNED_CERT_IN_CHAIN', 'DEPTH_ZERO_SELF_SIGNED_CERT',
+  'CERT_HAS_EXPIRED', 'CERT_NOT_YET_VALID', 'ERR_TLS_CERT_ALTNAME_INVALID',
+  'CERT_SIGNATURE_FAILURE', 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY', 'ERR_SSL_WRONG_VERSION_NUMBER'
+]);
+
+function causeOf(err) {
+  let e = err;
+  for (let i = 0; i < 5 && e && e.cause; i += 1) e = e.cause;
+  return e || err;
+}
+
+function classify(err) {
+  const c = causeOf(err);
+  const code = (c && c.code) || '';
+  if (err && err.name === 'TimeoutError') return { kind: 'unreachable', code: 'ETIMEDOUT' };
+  if (TLS_CODES.has(code)) return { kind: 'tls', code };
+  if (/certificate|self.signed|SSL/i.test(String(c && c.message))) return { kind: 'tls', code: code || 'TLS' };
+  return { kind: 'unreachable', code: code || 'unknown' };
+}
+
+// ── the pinned certificate, read locally ───────────────────────────────────────────────────────
+
+/**
+ * What we are pinning, without asking anybody. The fingerprint and expiry are properties of the PEM
+ * in front of us, so they are known even when the stack is off — which is when an operator most
+ * needs to be told the pin expires in a fortnight.
+ */
+function readPin(pem) {
+  if (!pem || !String(pem).trim()) return { present: false };
+  try {
+    const x = new crypto.X509Certificate(String(pem));
+    const expires = new Date(x.validTo);
+    const days = Math.floor((expires.getTime() - Date.now()) / 86400000);
+    return {
+      present: true,
+      valid: true,
+      // Short form, because the whole digest is unreadable and nobody compares 32 bytes by eye.
+      fingerprint: shortPrint(x.fingerprint256),
+      expires,
+      expiresDays: days,
+      expired: days < 0,
+      expiringSoon: days >= 0 && days <= EXPIRY_WARN_DAYS
+    };
+  } catch (e) {
+    return { present: true, valid: false, error: e.message };
+  }
+}
+
+function shortPrint(fp) {
+  const parts = String(fp || '').split(':');
+  if (parts.length < 4) return String(fp || '');
+  return `${parts.slice(0, 2).join(':')}…${parts[parts.length - 1]}`;
+}
+
+function fmtDate(d) {
+  return d instanceof Date && !isNaN(d) ? d.toISOString().slice(0, 10) : 'unknown';
+}
+
+// ── the checks ─────────────────────────────────────────────────────────────────────────────────
+
+const pass = (key, text) => ({ key, status: 'pass', text });
+const fail = (key, text) => ({ key, status: 'fail', text });
+const skip = (key, text) => ({ key, status: 'skip', text });
+
+/**
+ * Run the four (occasionally five) checks against a supervisor.
+ *
+ * @param {object} o
+ *   instance     the id this stack must report as itself
+ *   statusUrl    the status listener
+ *   statusToken  bearer for the status document
+ *   caCert       the certificate to pin, PEM
+ *   enginesKey   bearer for inference — checked only when there is an engine to check it against
+ *   engineName   an adopted engine to authenticate against; omitted, the first healthy one is used
+ *   fetchImpl    test seam; the pinned transport is used when absent
+ */
+async function verify(o = {}) {
+  const instance = String(o.instance || '');
+  const statusUrl = String(o.statusUrl || '');
+  const timeoutMs = Number(o.timeoutMs) || DEFAULT_TIMEOUT_MS;
+  const checks = [];
+  const at = new Date().toISOString();
+
+  const pin = readPin(o.caCert);
+  const host = hostOf(statusUrl);
+
+  // ── 1 + 2 + 3: one request answers all three, because they fail at different layers of it ──
+  let doc = null;
+  let found = null;   // the engine list, when the document arrived
+  try {
+    const started = Date.now();
+    const res = await statusFetch(o, statusUrl, timeoutMs);
+    const ms = Date.now() - started;
+
+    checks.push(pass('reachable', `reached ${host} in ${ms} ms`));
+    checks.push(certCheck(pin, true));
+
+    if (res.status === 401 || res.status === 403) {
+      checks.push(fail('status_token',
+        `status token rejected — the listener answered ${res.status}`));
+      checks.push(skip('engines_key', 'engines key not checked — needs the engine list'));
+      return finish(instance, at, checks, null, found);
+    }
+    if (!res.ok) {
+      checks.push(fail('status_token', `the listener answered ${res.status}`));
+      checks.push(skip('engines_key', 'engines key not checked — needs the engine list'));
+      return finish(instance, at, checks, null, found);
+    }
+
+    try {
+      doc = await res.json();
+    } catch (e) {
+      checks.push(fail('status_token', 'the listener answered, but not with a status document'));
+      checks.push(skip('engines_key', 'engines key not checked — needs the engine list'));
+      return finish(instance, at, checks, null, found);
+    }
+
+    const engines = Array.isArray(doc && doc.engines) ? doc.engines : [];
+    checks.push(pass('status_token',
+      `status token accepted · ${engines.length} engine${engines.length === 1 ? '' : 's'} reported`));
+
+    // THE DOCUMENT COMES BACK WITH THE VERDICT. Verifying already costs a status read, and that read
+    // is the same one the engine picker used to make on demand — so carrying the list here lets the
+    // panel render its engines from what we just fetched instead of asking again from the browser.
+    // It is also what removes the "Discover engines" button: a list you have to press for is a list
+    // that is stale by definition, and pressing it was where the 401 used to hide.
+    found = engines;
+
+    // IDENTITY, not connectivity. Engine names collide across deployments — `analysis` exists on
+    // every stack — so a status URL pointed at the wrong machine answers plausibly and sends work
+    // somewhere else. Only raised when it is actually wrong; a matching id needs no line.
+    if (doc && doc.instance && String(doc.instance) !== instance) {
+      checks.push(fail('instance',
+        `this stack reports itself as “${doc.instance}”, not “${instance}” — the address points at a different deployment`));
+    }
+
+    checks.push(await enginesKeyCheck(o, engines, timeoutMs));
+    return finish(instance, at, checks, null, found);
+  } catch (err) {
+    const { kind, code } = classify(err);
+    if (kind === 'tls') {
+      // NOTHING WAS SENT. The handshake failed, so neither credential left this process — worth
+      // saying, because it means the tokens are not what to go and look at.
+      checks.push(pass('reachable', `reached ${host}`));
+      checks.push(fail('certificate', certFailText(pin, code)));
+      checks.push(skip('status_token', 'status token not sent — the connection was refused first'));
+      checks.push(skip('engines_key', 'engines key not sent'));
+      return finish(instance, at, checks, null, found);
+    }
+    checks.push(fail('reachable', `no answer from ${host} (${code})`));
+    checks.push(skip('certificate', 'certificate not checked'));
+    checks.push(skip('status_token', 'status token not checked'));
+    checks.push(skip('engines_key', 'engines key not checked'));
+    return finish(instance, at, checks, pin, found);
+  }
+}
+
+function hostOf(url) {
+  try { const u = new URL(url); return u.host; } catch (e) { return url || 'the listener'; }
+}
+
+/** The status read, over the pinned transport unless a test supplies its own fetch. */
+async function statusFetch(o, statusUrl, timeoutMs) {
+  const headers = { Accept: 'application/json' };
+  if (o.statusToken) headers.Authorization = `Bearer ${o.statusToken}`;
+  return send(o, statusUrl, headers, timeoutMs);
+}
+
+/**
+ * One request, over the pinned transport.
+ *
+ * THE DISPATCHER IS HALF THE TRANSPORT. `lmxTransport(ca)` returns `{ fetch, dispatcher }` and the
+ * certificate lives on the DISPATCHER — taking only `.fetch` and calling it leaves the pin behind,
+ * and the request goes out against the system trust store instead. Against a self-signed stack that
+ * surfaces as DEPTH_ZERO_SELF_SIGNED_CERT, which reads exactly like a genuine certificate mismatch:
+ * a verifier that reported "the certificate did not match" for a perfectly good certificate, which
+ * is a worse failure than the one it was written to catch.
+ */
+async function send(o, url, headers, timeoutMs) {
+  const opts = { headers, signal: AbortSignal.timeout(timeoutMs) };
+  if (o.fetchImpl) return o.fetchImpl(url, opts);
+  const { lmxTransport } = require('./providers/lmxTransport');
+  const t = lmxTransport(o.caCert || null);
+  if (t.dispatcher) opts.dispatcher = t.dispatcher;
+  return t.fetch(url, opts);
+}
+
+function certCheck(pin, handshakeOk) {
+  if (!pin.present) {
+    // Not a failure: a stack on loopback, or one behind a certificate the system already trusts,
+    // needs no pin. Saying "none pinned" is the true statement; a tick would claim a check ran.
+    return skip('certificate', 'no certificate pinned — the system trust store was used');
+  }
+  if (!pin.valid) return fail('certificate', `the pinned certificate could not be read (${pin.error})`);
+  if (pin.expired) {
+    return fail('certificate',
+      `the pinned certificate EXPIRED on ${fmtDate(pin.expires)} — every call fails at the handshake`);
+  }
+  const base = `certificate matched the pin · ${pin.fingerprint} · expires ${fmtDate(pin.expires)}`;
+  if (pin.expiringSoon) {
+    return { key: 'certificate', status: 'warn', text: `${base} — ${pin.expiresDays} days left` };
+  }
+  return handshakeOk ? pass('certificate', base) : skip('certificate', base);
+}
+
+function certFailText(pin, code) {
+  if (pin.present && pin.expired) {
+    return `the pinned certificate expired on ${fmtDate(pin.expires)} (${code})`;
+  }
+  if (code === 'CERT_HAS_EXPIRED') return 'the stack is presenting an expired certificate';
+  if (code === 'ERR_TLS_CERT_ALTNAME_INVALID') {
+    return 'the certificate is not valid for this address — check the hostname';
+  }
+  if (!pin.present) {
+    return 'the stack presented a certificate this machine does not trust, and none is pinned here';
+  }
+  return `the stack presented a different certificate from the one pinned here (${code})`;
+}
+
+/**
+ * Check 4 — WITHOUT SPENDING ANYTHING.
+ *
+ * The engines key is a bearer on the engine's own OpenAI-compatible API, so asking that API to list
+ * its models authenticates against exactly the route inference uses. A completion would prove the
+ * same thing and bill for the privilege.
+ */
+async function enginesKeyCheck(o, engines, timeoutMs) {
+  if (!o.enginesKey) {
+    return skip('engines_key', 'no engines key set — engines are being called unauthenticated');
+  }
+  const wanted = o.engineName
+    ? engines.find((e) => e && e.name === o.engineName)
+    : engines.find((e) => e && e.state === 'healthy' && e.url);
+  if (!wanted || !wanted.url) {
+    return skip('engines_key',
+      o.engineName
+        ? `engines key not checked — “${o.engineName}” is not currently healthy`
+        : 'engines key not checked — no healthy engine to authenticate against');
+  }
+  try {
+    const url = `${String(wanted.url).replace(/\/+$/, '')}/models`;
+    const res = await send(o, url,
+      { Accept: 'application/json', Authorization: `Bearer ${o.enginesKey}` }, timeoutMs);
+    if (res.status === 401 || res.status === 403) {
+      return fail('engines_key',
+        `engines key rejected by ${wanted.name} — inference calls will fail with ${res.status}`);
+    }
+    if (!res.ok) {
+      return skip('engines_key', `engines key not confirmed — ${wanted.name} answered ${res.status}`);
+    }
+    return pass('engines_key', `engines key accepted · checked against ${wanted.name}`);
+  } catch (err) {
+    const { code } = classify(err);
+    return skip('engines_key', `engines key not checked — ${wanted.name} did not answer (${code})`);
+  }
+}
+
+// ── the verdict ────────────────────────────────────────────────────────────────────────────────
+
+function finish(instance, at, checks, pinForOffline, engines) {
+  // A certificate that expires soon is worth saying even when nothing could be reached, because it
+  // is knowable from the PEM alone and is exactly the failure nobody sees coming.
+  if (pinForOffline && pinForOffline.present && pinForOffline.valid
+      && (pinForOffline.expired || pinForOffline.expiringSoon)) {
+    const i = checks.findIndex((c) => c.key === 'certificate');
+    if (i > -1) checks[i] = certCheck(pinForOffline, false);
+  }
+
+  const failed = checks.filter((c) => c.status === 'fail');
+  const warned = checks.filter((c) => c.status === 'warn');
+  const ok = failed.length === 0;
+
+  return {
+    ok,
+    level: failed.length ? (failed.some((c) => c.key === 'certificate') ? 'bad' : 'warn')
+      : (warned.length ? 'warn' : 'ok'),
+    headline: headlineFor(failed, warned),
+    at,
+    instance,
+    checks,
+    // Null means "we never got a document", which is NOT the same as a stack with no engines — the
+    // panel must be able to say "not checked" rather than "no engines", because those send an
+    // operator to entirely different places.
+    engines: engines || null
+  };
+}
+
+/**
+ * ONE SENTENCE NAMING THE CAUSE, for the flash. "Saved, but the status token is being rejected"
+ * is a different instruction from "saved, but the stack did not answer" — the first sends somebody
+ * to a credential, the second to a machine, and "401" sent them to neither.
+ */
+function headlineFor(failed, warned) {
+  if (!failed.length) {
+    return warned.length ? warned[0].text : 'connected, certificate pinned, both credentials accepted';
+  }
+  const first = failed[0];
+  switch (first.key) {
+    case 'reachable': return 'the stack did not answer — its settings are stored and will be used when it is back';
+    case 'certificate': return 'the certificate did not match — nothing was sent';
+    case 'status_token': return 'the status token is being rejected — engines cannot be listed until it is corrected';
+    case 'instance': return 'this address points at a different deployment';
+    case 'engines_key': return 'the engines key is being rejected — inference calls will fail';
+    default: return first.text;
+  }
+}
+
+module.exports = {
+  verify, remember, lastFor, forget, readPin,
+  DEFAULT_TIMEOUT_MS, EXPIRY_WARN_DAYS, REPORT_TTL_MS,
+  _reset, _classify: classify, _shortPrint: shortPrint
+};

package/package.json

@@ -1,49 +1,53 @@
-{
-  "name": "@aria-framework/ai",
-  "description": "Aria App Framework — AI module. A dependency-injected model seam (createAiClient) over several providers (LM Studio / OpenAI-compatible / Anthropic), with a fact-preservation guard, generic Polish and Generate writing engines, and a browser polish widget. Prompts and config stay in the consuming app.",
-  "version": "0.14.3",
-  "license": "UNLICENSED",
-  "private": false,
-  "publishConfig": {
-    "access": "public"
-  },
-  "main": "index.js",
-  "files": [
-    "index.js",
-    "error.js",
-    "facts.js",
-    "polish.js",
-    "generate.js",
-    "providers/openai-compatible.js",
-    "providers/anthropic.js",
-    "browser/ai-polish.js",
-    "usageStore.js",
-    "providerStore.js",
-    "speedStore.js",
-    "health.js",
-    "benchmark.js",
-    "views/",
-    "providers/lmx.js",
-    "providers/lmxDiscovery.js",
-    "providers/lmxTransport.js"
-  ],
-  "peerDependencies": {
-    "@aria-framework/db-worker": ">=0.7.0",
-    "undici": ">=6"
-  },
-  "peerDependenciesMeta": {
-    "@aria-framework/db-worker": {
-      "optional": true
-    },
-    "undici": {
-      "optional": true
-    }
-  },
-  "scripts": {
-    "test": "node test/smoke.js && node test/usageStore.js && node test/providerStore.js && node test/speedStore.js && node test/health.js && node test/listModels.js && node test/benchmark.js && node test/lmxDiscovery.js && node test/lmx.js && node test/packaging.js && node test/views.js"
-  },
-  "devDependencies": {
-    "undici": "^8.10.0",
-    "ejs": "^3.1.10"
-  }
-}
+{
+  "name": "@aria-framework/ai",
+  "description": "Aria App Framework \u2014 AI module. A dependency-injected model seam (createAiClient) over several providers (LM Studio / OpenAI-compatible / Anthropic), with a fact-preservation guard, generic Polish and Generate writing engines, and a browser polish widget. Prompts and config stay in the consuming app.",
+  "version": "0.15.2",
+  "license": "UNLICENSED",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "error.js",
+    "facts.js",
+    "polish.js",
+    "generate.js",
+    "providers/openai-compatible.js",
+    "providers/anthropic.js",
+    "browser/ai-polish.js",
+    "usageStore.js",
+    "providerStore.js",
+    "speedStore.js",
+    "health.js",
+    "benchmark.js",
+    "views/",
+    "providers/lmx.js",
+    "providers/lmxDiscovery.js",
+    "providers/lmxTransport.js",
+    "lmxVerify.js",
+    "lmxStore.js",
+    "lmxStatus.js",
+    "browser/ai-panels.js"
+  ],
+  "peerDependencies": {
+    "@aria-framework/db-worker": ">=0.7.0",
+    "undici": ">=6"
+  },
+  "peerDependenciesMeta": {
+    "@aria-framework/db-worker": {
+      "optional": true
+    },
+    "undici": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "test": "node test/smoke.js && node test/usageStore.js && node test/providerStore.js && node test/speedStore.js && node test/health.js && node test/listModels.js && node test/benchmark.js && node test/lmxDiscovery.js && node test/lmx.js && node test/lmxVerify.js && node test/lmxStore.js && node test/lmxStatus.js && node test/packaging.js && node test/views.js"
+  },
+  "devDependencies": {
+    "undici": "^8.10.0",
+    "ejs": "^3.1.10"
+  }
+}