anyos-client 0.2.0

package/connect.js

@@ -0,0 +1,265 @@
+/* The picker. Everything shown is set with textContent; the only markup is
+   the page's own templates. `window.machines` is the preload's door. */
+import { isConnectLine, readConnectLine } from './connect-line.js';
+
+const { machines } = window;
+const section = document.getElementById('machines');
+const list = document.getElementById('list');
+const problem = document.getElementById('problem');
+const form = document.getElementById('form');
+const address = document.getElementById('address');
+const credentials = document.getElementById('credentials');
+const certificate = document.getElementById('certificate');
+const footer = document.getElementById('footer');
+const openButton = document.getElementById('open');
+const rowTemplate = document.getElementById('row');
+const glyphs = { local: document.getElementById('glyph-local'), remote: document.getElementById('glyph-remote') };
+
+let rows = [];          /* the machines, as listed */
+let local = null;       /* this computer: running, installed, or absent */
+let selected = null;    /* the highlighted machine's id */
+let editing = null;     /* the id being edited; null while adding */
+let tokenOnly = false;  /* This computer: a token and nothing else to change */
+let busy = false;
+
+function say(text, tone = 'bad') {
+  problem.textContent = text ?? '';
+  problem.hidden = !text;
+  problem.classList.toggle('good', Boolean(text) && tone === 'good');
+}
+
+function render() {
+  list.textContent = '';
+  for (const machine of rows) {
+    const row = rowTemplate.content.firstElementChild.cloneNode(true);
+    const isLocal = machine.id === 'local';
+    row.classList.toggle('selected', machine.id === selected);
+    row.querySelector('.glyph').append(glyphs[isLocal ? 'local' : 'remote'].content.firstElementChild.cloneNode(true));
+    row.querySelector('.spec-item-title').textContent = machine.name;
+    const detail = row.querySelector('.spec-item-detail');
+    detail.textContent = isLocal ? (local?.detail ?? 'looking for a kernel…') : machine.url;
+    if (isLocal) {
+      if (local?.tone) detail.classList.add(`tone-${local.tone}`);
+      row.classList.toggle('unavailable', local?.state === 'absent');
+      /* This computer has no name and no address to change. It gets one tool,
+         and only when the kernel running on it turned out to want a token. */
+      if (local?.guarded) {
+        row.querySelector('.edit').remove();
+        row.querySelector('.remove').remove();
+      } else {
+        row.querySelector('.tools').remove();
+      }
+    } else {
+      row.querySelector('.token').remove();   /* a machine's token is in its Edit form */
+    }
+    row.addEventListener('click', () => select(machine.id));
+    row.addEventListener('dblclick', open);
+    row.querySelector('.token')?.addEventListener('click', event => { event.stopPropagation(); editToken(machine.id); });
+    row.querySelector('.edit')?.addEventListener('click', event => { event.stopPropagation(); edit(machine); });
+    row.querySelector('.remove')?.addEventListener('click', async event => {
+      event.stopPropagation();
+      await machines.remove(machine.id);
+      await refresh();
+    });
+    list.append(row);
+  }
+  openButton.disabled = busy || !selected || !openable(selected);
+}
+
+/* the one machine that can be unopenable: this computer, with no kernel on it */
+const openable = id => id !== 'local' || local === null || local.state !== 'absent';
+
+async function refresh() {
+  const answer = await machines.list();
+  if (!answer.ok) return say(answer.error);
+  rows = answer.machines;
+  if (!rows.some(m => m.id === selected)) selected = rows.some(m => m.id === answer.last) ? answer.last : 'local';
+  render();
+  await lookLocal();
+}
+
+/* Whether this computer has a kernel is a question with an HTTP request in
+   it, so the list is drawn first and the local row fills in when it answers. */
+async function lookLocal() {
+  const answer = await machines.local();
+  local = answer.ok ? answer.local : { state: 'absent', detail: answer.error, tone: 'bad' };
+  render();
+}
+
+function select(id) { selected = id; render(); }
+
+function move(step) {
+  const i = rows.findIndex(m => m.id === selected);
+  const next = rows[Math.min(rows.length - 1, Math.max(0, i + step))];
+  if (next) select(next.id);
+}
+
+async function open() {
+  if (busy || !selected || !openable(selected) || !form.hidden) return;
+  busy = true;
+  say(null);
+  section.classList.add('busy');
+  render();
+  const answer = await machines.open(selected);
+  busy = false;
+  section.classList.remove('busy');
+  render();
+  if (!answer.ok) { say(answer.error); await lookLocal(); }
+  /* on success the main process closes this window */
+}
+
+/* The kept token is put back in the field, so what is shown is what is
+   stored and clearing the field is how you forget it. */
+async function secretFor(id) {
+  const answer = await machines.secret(id);
+  return answer.ok ? answer : { token: '', fingerprint: '' };
+}
+
+/**
+ * Adding a machine asks for a name and an address, and nothing else.
+ *
+ * A kernel reached by hand is one on a forward, and a forward needs neither a
+ * token nor a certificate — those belong to a kernel on a network, and they
+ * arrive by pasting its connect line, not by being typed. Editing an existing
+ * machine still shows them, because replacing a token after ./remote.sh renew
+ * is a real job and this is where it is done.
+ */
+async function edit(machine) {
+  editing = machine?.id ?? null;
+  tokenOnly = false;
+  address.hidden = false;
+  credentials.hidden = !machine;
+  certificate.hidden = !machine;
+  form.elements.url.required = true;
+  form.elements.name.value = machine?.name ?? '';
+  form.elements.url.value = machine?.url ?? '';
+  const kept = machine ? await secretFor(machine.id) : { token: '', fingerprint: '' };
+  form.elements.token.value = kept.token;
+  form.elements.fingerprint.value = kept.fingerprint;
+  form.hidden = false;
+  footer.hidden = true;
+  say(null);
+  form.elements[machine ? 'name' : 'url'].focus();
+}
+
+async function editToken(id) {
+  editing = id;
+  tokenOnly = true;
+  address.hidden = true;
+  /* the address is not merely hidden — a required field nobody can see would
+     refuse to submit and say nothing about why */
+  form.elements.url.required = false;
+  credentials.hidden = false;
+  /* This computer is http on loopback; there is no certificate to pin */
+  certificate.hidden = true;
+  form.elements.token.value = (await secretFor(id)).token;
+  form.hidden = false;
+  footer.hidden = true;
+  say(null);
+  form.elements.token.focus();
+}
+
+function closeForm() {
+  form.hidden = true;
+  footer.hidden = false;
+  address.hidden = false;
+  credentials.hidden = false;
+  certificate.hidden = false;
+  form.elements.url.required = true;
+  form.elements.token.value = '';
+  form.elements.fingerprint.value = '';
+  editing = null;
+  tokenOnly = false;
+  say(null);
+}
+
+form.addEventListener('submit', async event => {
+  event.preventDefault();
+  const token = form.elements.token.value;
+  if (tokenOnly) {
+    const kept = await machines.token(editing, token);
+    if (!kept.ok) return say(kept.error);
+    closeForm();
+    return refresh();
+  }
+  const fields = {
+    name: form.elements.name.value,
+    url: form.elements.url.value,
+    token,
+    fingerprint: form.elements.fingerprint.value
+  };
+  const answer = editing ? await machines.update(editing, fields) : await machines.add(fields);
+  if (!answer.ok) return say(answer.error);
+  selected = answer.machine.id;
+  closeForm();
+  await refresh();
+});
+/**
+ * A connect line, pasted: it connects. Nothing to fill in, nothing to press.
+ *
+ * There was a review step here and it was taken out. None of these values
+ * were typed by anyone, so there is nothing to have mistyped, and a
+ * 64-character fingerprint is not something a person checks by eye — asking
+ * them to was friction that bought nothing. The form's fields stay for
+ * editing a machine later, which is a different job from arriving at one.
+ *
+ * The machine is saved before the connection is tried, so a kernel that is
+ * down leaves something in the list to retry rather than sending anyone back
+ * to the terminal for the line again.
+ */
+async function connectWith(text, { loud = true } = {}) {
+  if (busy) return;
+  busy = true;
+  say('connecting…', 'good');
+  section.classList.add('busy');
+  render();
+  const answer = await machines.connect(text);
+  busy = false;
+  section.classList.remove('busy');
+  /* the form and the list settle first — closeForm clears the message line,
+     so anything said before this would be wiped by it */
+  closeForm();
+  await refresh();
+  if (!answer.ok && loud) say(answer.error);
+  else say(null);
+  /* when it opened, the main process closes this window and none of this shows */
+}
+
+/* pasted anywhere in the picker — into the address box, or at the list */
+document.addEventListener('paste', event => {
+  const text = event.clipboardData?.getData('text') ?? '';
+  if (!isConnectLine(text)) return;
+  event.preventDefault();
+  connectWith(text);
+});
+
+/* a middle-click or a drag drops text without a paste event; act only once it
+   is a whole line, because this also fires on every keystroke */
+form.elements.url.addEventListener('input', event => {
+  const text = event.target.value;
+  if (!isConnectLine(text)) return;
+  try { readConnectLine(text); } catch { return; }
+  connectWith(text, { loud: false });
+});
+
+document.getElementById('cancel').addEventListener('click', closeForm);
+document.getElementById('add').addEventListener('click', () => edit(null));
+openButton.addEventListener('click', open);
+
+document.addEventListener('keydown', event => {
+  if (!form.hidden) { if (event.key === 'Escape') closeForm(); return; }
+  if (event.key === 'ArrowDown') { event.preventDefault(); move(1); }
+  else if (event.key === 'ArrowUp') { event.preventDefault(); move(-1); }
+  else if (event.key === 'Enter') { event.preventDefault(); open(); }
+  else if (event.key === 'Escape') window.close();
+});
+
+machines.onProblem(say);
+
+/* say which copy this is, before anything else can go wrong */
+machines.version().then(answer => {
+  if (!answer.ok) return;
+  document.getElementById('build').textContent = `anyos-client ${answer.version} · ${answer.from}`;
+}).catch(() => {});
+
+refresh();

package/guard.js

@@ -0,0 +1,76 @@
+/**
+ * The two answers this client gives Chromium about a kernel: which
+ * certificate it will accept, and which secret it will present.
+ *
+ * They live here rather than inline in main.js so a test can install the
+ * real ones on a real Electron app and watch them decide. A handler that is
+ * only ever read, or only ever tested as a copy of itself, is where this
+ * kind of bug survives — and both of these fail dangerous: the certificate
+ * one by trusting anybody, the login one by spinning forever.
+ *
+ * Chromium runs them in the order that matters, and it is the safe one: a
+ * certificate that does not verify means `login` never fires at all, so a
+ * credential is never offered to a machine that failed its pin.
+ */
+import { X509Certificate } from 'node:crypto';
+import { samePin } from './secrets.js';
+
+/** host and port as `certificate-error` and `login` both name them. */
+export function hostPort(url) {
+  try {
+    const parsed = new URL(url);
+    return [parsed.hostname, parsed.port || (parsed.protocol === 'https:' ? '443' : '80')];
+  } catch { return ['', '']; }
+}
+
+/**
+ * Which certificate is this machine's. A kernel's is self-signed, so every
+ * one of these arrives as an error and Chromium is right to object; what
+ * makes overruling it safe is that we overrule it for exactly one key.
+ *
+ * Two ways to get this wrong. Calling back true unconditionally accepts any
+ * certificate at all and is worse than plain http, because the padlock says
+ * otherwise. The subtler one: `certificate.fingerprint` is Chromium's own
+ * `sha256/<base64>` and can never equal what the kernel printed, so
+ * comparing it looks like a pinning bug and tempts someone into "fixing" it
+ * the first way. The PEM in `certificate.data` gives the kernel's own format.
+ *
+ * Fires per request, not per connection — a single page load can bring
+ * fifteen of these — so it stays cheap and decides the same way every time.
+ */
+export function certificateGuard(keyring) {
+  return (event, _contents, url, _error, certificate, callback) => {
+    event.preventDefault();
+    const wanted = keyring.expected(...hostPort(url));
+    if (!wanted) return callback(false);   /* nothing pinned is not permission */
+    let seen = '';
+    try { seen = new X509Certificate(certificate.data).fingerprint256; } catch { seen = ''; }
+    callback(samePin(seen, wanted));
+  };
+}
+
+/**
+ * The kernel's door. HTTP Basic on purpose: app code loaded by import(), the
+ * event stream and the first navigation cannot set a header of their own,
+ * but Chromium attaches a Basic credential to all of them once it has one —
+ * so this fires once and the whole desktop is authenticated.
+ *
+ * The kernel reads the password and ignores the user name.
+ */
+export function loginGuard(keyring) {
+  return (event, _contents, _details, authInfo, callback) => {
+    if (authInfo.isProxy) return;          /* a proxy's challenge is not ours to answer */
+    event.preventDefault();
+    const token = keyring.answer(authInfo.host, authInfo.port);
+    /* declining shows the kernel's own 401 rather than spinning on a password
+       box we have nothing to put in */
+    if (!token) return callback();
+    callback('anyos', token);
+  };
+}
+
+/** Install both on an Electron app. */
+export function installGuards(app, keyring) {
+  app.on('certificate-error', certificateGuard(keyring));
+  app.on('login', loginGuard(keyring));
+}

package/local.js

@@ -0,0 +1,197 @@
+/**
+ * The local kernel: whether one is running on this computer, and how to
+ * bring one up if it is only installed.
+ *
+ * The client does not contain a kernel. It looks for one, in the order a
+ * person would: is something already answering on the kernel's port — then
+ * that is the machine, and it is not ours to start or stop. Otherwise, is
+ * `anyos` installed here — then opening starts it, and what we started we
+ * stop when its window closes. If neither, there is no local machine, and
+ * the only way in is an address somewhere else.
+ *
+ * Where the kernel is found, in order: ANYOS_KERNEL if it is set (a command,
+ * or a path to the kernel's bin), then `anyos` on PATH, then the anyos package
+ * installed next to this one. Nothing here imports the kernel — a command is
+ * spawned and an address is probed, which is all a client may know.
+ *
+ * The kernel was called webos before it was called anyos, so each lookup tries
+ * the new name and then the old one: a machine that has not pulled the rename
+ * still starts. WEBOS_KERNEL is read after ANYOS_KERNEL for the same reason.
+ *
+ * A kernel started here is started behind a door: a secret minted per launch
+ * and passed in its environment, which the client can answer because it is
+ * the one that minted it. See mintToken at the foot of this file.
+ */
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { accessSync, constants } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { reachable, DEFAULT_PORT } from './machines.js';
+
+/* the kernel binds 127.0.0.1; `localhost` may resolve to ::1 first and be
+   refused by a kernel that is running perfectly well */
+export const LOCAL_URL = `http://127.0.0.1:${DEFAULT_PORT}`;
+
+/* the kernel's command and package, the name it has now first — an install or
+   a checkout still on the old name is found by the second pass, not missed */
+const KERNELS = [
+  { name: 'anyos', script: 'anyos/bin/anyos.js' },
+  { name: 'webos', script: 'webos/bin/webos.js' }
+];
+
+const isExecutable = file => {
+  try { accessSync(file, constants.X_OK); return true; } catch { return false; }
+};
+
+/** A command on PATH, as an absolute path — or null. Windows tries PATHEXT. */
+export function which(name, {
+  PATH = process.env.PATH ?? '',
+  PATHEXT = process.env.PATHEXT ?? '',
+  platform = process.platform,
+  executable = isExecutable
+} = {}) {
+  const windows = platform === 'win32';
+  const exts = windows ? (PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean) : [''];
+  /* the separators are the named platform's, not the one we happen to run on */
+  const join = windows ? path.win32.join : path.posix.join;
+  for (const dir of PATH.split(windows ? ';' : ':').filter(Boolean)) {
+    for (const ext of exts) {
+      const full = join(dir, name + ext);
+      if (executable(full)) return full;
+    }
+  }
+  return null;
+}
+
+/**
+ * Where the kernel is on this computer: { command, args, from } to spawn, or
+ * null if it is not installed. `from` is for the sentence shown to a person,
+ * not for logic.
+ */
+export function findKernel({
+  env = process.env,
+  resolve = specifier => createRequire(import.meta.url).resolve(specifier),
+  node = process.execPath,
+  ...lookup
+} = {}) {
+  const named = String(env.ANYOS_KERNEL ?? '').trim() ? 'ANYOS_KERNEL' : 'WEBOS_KERNEL';
+  const explicit = String(env.ANYOS_KERNEL ?? env.WEBOS_KERNEL ?? '').trim();
+  if (explicit) {
+    return explicit.endsWith('.js') || explicit.endsWith('.mjs')
+      ? { command: node, args: [explicit], from: named }
+      : { command: explicit, args: [], from: named };
+  }
+
+  for (const { name } of KERNELS) {
+    const onPath = which(name, { ...lookup, PATH: env.PATH ?? '', PATHEXT: env.PATHEXT ?? '' });
+    if (onPath) return { command: onPath, args: [], from: 'PATH' };
+  }
+
+  /* installed as a package beside this one — the shape a `npm i anyos
+     anyos-client` or a checkout with both leaves behind */
+  for (const { name, script } of KERNELS) {
+    try {
+      const found = resolve(script);
+      if (found) return { command: node, args: [found], from: `the ${name} package` };
+    } catch { /* not installed here */ }
+  }
+  return null;
+}
+
+/**
+ * What the local machine is right now:
+ *   running    a kernel answers at LOCAL_URL — connect, do not own it
+ *   installed  anyos is here but nothing is listening — opening starts it
+ *   absent     no kernel on this computer; only an address will do
+ */
+export async function localKernel({ url = LOCAL_URL, probe = reachable, ...options } = {}) {
+  const problem = await probe(url, { timeout: 1_500 });
+  if (!problem) return { state: 'running', url, kernel: findKernel(options) };
+  const kernel = findKernel(options);
+  return { state: kernel ? 'installed' : 'absent', url, kernel };
+}
+
+/** One line for the picker's local row, and how it should read. */
+export function describe({ state, url, guarded, token } = {}) {
+  if (state === 'running') {
+    /* a kernel we did not start may have a door we have no key to; saying so
+       here is kinder than a window that opens onto a password box */
+    if (guarded && !token) return { detail: `a kernel is running at ${short(url)} — it wants a token`, tone: '' };
+    return { detail: `a kernel is running at ${short(url)}`, tone: 'good' };
+  }
+  if (state === 'installed') return { detail: 'anyos is installed here — opening starts it', tone: '' };
+  return { detail: 'anyos is not installed on this computer', tone: 'bad' };
+}
+
+const short = url => String(url ?? '').replace(/^https?:\/\//, '');
+
+const wait = ms => new Promise(done => setTimeout(done, ms));
+const lastLine = text => String(text).trim().split('\n').filter(Boolean).pop() ?? '';
+
+/**
+ * Start the local kernel and resolve once it answers: { url, stop }.
+ *
+ * The port is the kernel's usual one, not a free one — a kernel this client
+ * started is still the computer's kernel, and the next client to look should
+ * find it where it belongs. If the child dies first, its last line is the
+ * error, because that is the sentence the kernel wrote about itself.
+ */
+export function startKernel(kernel, {
+  port = DEFAULT_PORT,
+  url = `http://127.0.0.1:${port}`,
+  timeout = 20_000,
+  probe = reachable,
+  launch = spawn,
+  env = process.env,
+  token = mintToken(env)
+} = {}) {
+  if (!kernel) return Promise.reject(new Error('anyos is not installed on this computer'));
+
+  const child = launch(kernel.command, [...kernel.args, '--port', String(port)], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: token ? { ...env, ANYOS_TOKEN: token } : { ...env }
+  });
+
+  let noise = '';
+  let done = null;   /* how the child ended, if it has */
+  const listen = stream => stream?.on('data', chunk => { noise = (noise + chunk).slice(-4_096); });
+  child.stdout?.setEncoding('utf8');
+  child.stderr?.setEncoding('utf8');
+  listen(child.stdout);
+  listen(child.stderr);
+  child.on('error', err => { done = err.code === 'ENOENT' ? `${kernel.command} could not be run` : err.message; });
+  child.on('exit', code => { done ??= lastLine(noise) || `the kernel exited with code ${code}`; });
+
+  const stop = async () => { child.kill(); };
+
+  return (async () => {
+    const deadline = Date.now() + timeout;
+    for (;;) {
+      if (done) throw new Error(`the kernel did not start — ${done}`);
+      if (!await probe(url, { timeout: 1_500 })) return { url, stop, token };
+      if (Date.now() >= deadline) {
+        await stop();
+        throw new Error(`the kernel did not answer at ${short(url)} in ${Math.round(timeout / 1000)}s`);
+      }
+      await wait(200);
+    }
+  })();
+}
+
+/**
+ * The secret a kernel we start will ask for. Fresh bytes per launch, held in
+ * two process environments and never written down: the client knows it
+ * because it minted it, and answers the kernel's challenge with it.
+ *
+ * If the environment already names one, that is the owner's decision and it
+ * is inherited rather than replaced — the same token their other tools use.
+ *
+ * Only a kernel this client spawns gets a door this way. One already running
+ * is untouched, so `anyos` in a terminal stays as open as it ever was, and
+ * so does the browser tab pointed at it.
+ */
+export function mintToken(env = process.env) {
+  const named = String(env.ANYOS_TOKEN ?? '').trim();
+  return named || randomBytes(32).toString('hex');
+}