anyos-client 0.2.0

package/machines.js

@@ -0,0 +1,225 @@
+/**
+ * Machines: where a kernel runs. The client keeps only this list — the
+ * workspace, the state dir and pid1's memory of you live with the kernel, so
+ * each machine is its own anyOS. "This Mac" is always first and means the
+ * kernel on this computer, found rather than stored — see local.js, which
+ * knows whether one is running or merely installed. Every other machine is
+ * an address where a kernel is already listening, and the window is pointed
+ * at it.
+ *
+ * The client does not start a remote kernel and does not own its lifetime.
+ * Reaching one that is not on this machine is the owner's arrangement — an
+ * ssh forward (`ssh -N -L 8765:127.0.0.1:8765 host`), a private network — and
+ * the address is whatever that arrangement makes local. The kernel binds
+ * loopback and authenticates nobody, so an address it answers on is a
+ * decision about the network, not about this list.
+ *
+ * Everything here runs without Electron: the store is one JSON file, an
+ * address is text, and whether a kernel answers is one HTTP request.
+ */
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import http from 'node:http';
+import https from 'node:https';
+import path from 'node:path';
+import { samePin } from './secrets.js';
+
+export const LOCAL = 'local';
+export const DEFAULT_PORT = 8765;
+
+export const localMachine = () => ({
+  id: LOCAL,
+  name: process.platform === 'darwin' ? 'This Mac' : 'This computer',
+  url: null
+});
+
+const oops = message => Object.assign(new Error(message), { status: 400 });
+
+/**
+ * `host`, `host:port`, or either with a scheme — normalised to
+ * `http://host:port`. A bare host gets 8765, the port the kernel listens on.
+ * No path, no credentials: this names a machine, not a page on it.
+ */
+export function clean({ name, url } = {}) {
+  const raw = String(url ?? '').trim();
+  if (!raw) throw oops('an address is needed, like localhost:8765');
+  if (/\s/.test(raw)) throw oops(`"${raw}" is not an address`);
+  let parsed;
+  try { parsed = new URL(/^[a-z]+:\/\//i.test(raw) ? raw : `http://${raw}`); } catch { throw oops(`"${raw}" is not an address`); }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') throw oops('an address is http or https');
+  if (!parsed.hostname) throw oops(`"${raw}" is not an address`);
+  if (parsed.username || parsed.password) throw oops('an address carries no user — that was the ssh form');
+  if (parsed.pathname !== '/' || parsed.search || parsed.hash) throw oops('an address is a host and a port, with nothing after it');
+  /* URL drops a port that is the scheme's default, so :443 and :80 come back
+     empty and would silently become 8765. Only a host with no port at all
+     gets the kernel's. */
+  const named = /:\d+$/.test(raw.replace(/^[a-z]+:\/\//i, ''));
+  const port = parsed.port || (named ? (parsed.protocol === 'https:' ? '443' : '80') : String(DEFAULT_PORT));
+  const address = `${parsed.protocol}//${parsed.hostname}:${port}`;
+  const label = String(name ?? '').trim() || `${parsed.hostname}:${port}`;
+  return { name: label, url: address };
+}
+
+export function createMachines(file) {
+  const data = load();
+
+  function load() {
+    try {
+      const parsed = JSON.parse(readFileSync(file, 'utf8'));
+      const machines = [];
+      for (const row of Array.isArray(parsed.machines) ? parsed.machines : []) {
+        try { machines.push({ id: String(row.id), ...clean(row) }); } catch { /* a broken row is dropped, not fatal */ }
+      }
+      const last = typeof parsed.last === 'string' ? parsed.last : LOCAL;
+      return { machines, last: machines.some(m => m.id === last) ? last : LOCAL };
+    } catch {
+      return { machines: [], last: LOCAL };
+    }
+  }
+  function save() {
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(data, null, 2) + '\n');
+  }
+  function idFor(name) {
+    const base = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'machine';
+    let id = base;
+    for (let n = 2; id === LOCAL || data.machines.some(m => m.id === id); n++) id = `${base}-${n}`;
+    return id;
+  }
+
+  return {
+    list: () => [localMachine(), ...data.machines.map(m => ({ ...m }))],
+    last: () => data.last,
+    get: id => id === LOCAL ? localMachine() : data.machines.find(m => m.id === id) ?? null,
+    /* the machine already at an address, if there is one — a connect line for
+       somewhere already in the list replaces its credentials rather than
+       adding a second row for the same kernel */
+    byUrl(url) {
+      let want;
+      try { want = clean({ url }).url; } catch { return null; }
+      return data.machines.find(m => m.url === want) ?? null;
+    },
+    add(fields) {
+      const machine = clean(fields);
+      const row = { id: idFor(machine.name), ...machine };
+      data.machines.push(row);
+      save();
+      return { ...row };
+    },
+    update(id, fields) {
+      const i = data.machines.findIndex(m => m.id === id);
+      if (i < 0) throw oops('that machine is no longer in the list');
+      data.machines[i] = { id, ...clean(fields) };
+      save();
+      return { ...data.machines[i] };
+    },
+    remove(id) {
+      data.machines = data.machines.filter(m => m.id !== id);
+      if (data.last === id) data.last = LOCAL;
+      save();
+    },
+    used(id) { data.last = id; save(); }
+  };
+}
+
+/**
+ * A GET to a kernel, with its certificate held to the fingerprint pinned for
+ * it. Over http this is an ordinary request; over https the certificate is
+ * self-signed, so no authority can vouch for it and the pin is the whole of
+ * the check.
+ *
+ * `rejectUnauthorized: false` looks alarming and is the point: Node would
+ * refuse a self-signed certificate before we ever saw it, so the chain check
+ * is turned off and replaced with a stricter one — this exact key, not any
+ * key some authority on this machine would sign. A pin that does not match
+ * destroys the socket at the handshake.
+ *
+ * Safe to check after the handshake rather than before only because these two
+ * routes carry no credential. Everything that does travels through the window,
+ * where certificate-error in main.js holds the same pin.
+ */
+function ask(url, route, { timeout, pin }, onResponse, onProblem) {
+  const secure = url.startsWith('https:');
+  if (secure && !pin) {
+    onProblem(`${url} is https, but no certificate is pinned for it — add its fingerprint`);
+    return null;
+  }
+  const agent = secure ? https : http;
+  /* agent: false — a pooled socket from a previous probe comes back reset
+     rather than refused, which reads as a kernel that hung up on us */
+  const options = { timeout, agent: false };
+  if (secure) options.rejectUnauthorized = false;
+  const request = agent.get(`${url}${route}`, options, onResponse);
+  if (secure) {
+    request.on('socket', socket => socket.on('secureConnect', () => {
+      const seen = socket.getPeerX509Certificate?.()?.fingerprint256 ?? '';
+      if (samePin(seen, pin)) return;
+      socket.destroy();
+      onProblem(seen
+        ? `${url} is not the machine you pinned — its certificate has changed`
+        : `${url} offered no certificate`);
+    }));
+  }
+  return request;
+}
+
+/**
+ * Does a kernel answer here? Resolves null when one does, or one sentence
+ * saying what is wrong — the picker shows it instead of opening a window on
+ * nothing. `/fs/health` is the cheapest syscall that proves it is a kernel
+ * and not merely something listening.
+ */
+export function reachable(url, { timeout = 4_000, pin = null } = {}) {
+  return new Promise(resolve => {
+    let settled = false;
+    const done = answer => { if (!settled) { settled = true; resolve(answer); } };
+    const request = ask(url, '/fs/health', { timeout, pin }, response => {
+      if (response.statusCode !== 200) {
+        response.resume();
+        return done(`${url} answered ${response.statusCode}, which is not a kernel`);
+      }
+      let body = '';
+      response.setEncoding('utf8');
+      response.on('data', chunk => { body += chunk.slice(0, 4_096); });
+      response.on('end', () => {
+        try { done(JSON.parse(body).ok ? null : `${url} answered, but not like a kernel`); }
+        catch { done(`${url} answered, but not like a kernel`); }
+      });
+    }, done);
+    request?.on('timeout', () => { request.destroy(); done(`${url} did not answer in ${Math.round(timeout / 1000)}s`); });
+    request?.on('error', err => done(explain(err, url)));
+  });
+}
+
+/** Why an address did not answer, in one sentence the owner can act on. */
+export function explain(err, url) {
+  const host = new URL(url).hostname;
+  if (err.code === 'ECONNREFUSED') return `nothing is listening at ${url} — is its kernel running?`;
+  if (err.code === 'ENOTFOUND' || err.code === 'EAI_AGAIN') return `${host} could not be found`;
+  if (err.code === 'ETIMEDOUT' || err.code === 'EHOSTUNREACH' || err.code === 'ENETUNREACH') return `${host} could not be reached`;
+  if (err.code === 'ECONNRESET') return `${url} closed the connection`;
+  return `${url}: ${err.message}`;
+}
+
+/**
+ * Does this kernel want a secret? Resolves true when an uncredentialed
+ * request is refused, false when it is served, and null when the question
+ * could not be asked at all.
+ *
+ * `/kernel/health` is the cheapest route behind the door. `/fs/health` is
+ * deliberately in front of it — a window must be able to find a kernel
+ * before it can talk to one — so the two together say both "something is
+ * there" and "it will want a password".
+ */
+export function guarded(url, { timeout = 4_000, pin = null } = {}) {
+  return new Promise(resolve => {
+    let settled = false;
+    const done = answer => { if (!settled) { settled = true; resolve(answer); } };
+    const request = ask(url, '/kernel/health', { timeout, pin }, response => {
+      response.resume();
+      /* a kernel too old to have the route answers 404, which is not a door */
+      done(response.statusCode === 401);
+    }, () => done(null));   /* a certificate we cannot vouch for answers nothing */
+    request?.on('timeout', () => { request.destroy(); done(null); });
+    request?.on('error', () => done(null));
+  });
+}

package/main.js

@@ -0,0 +1,287 @@
+/**
+ * The anyOS client — a window on a kernel, and nothing else.
+ *
+ * This is deliberately the thinnest possible client. It contains no kernel,
+ * no filesystem and no agents: those live on a machine, and this opens one
+ * window on that machine's URL. Everything that matters — the wire, the
+ * apps, the agents — is exactly what a browser would get; the kernel cannot
+ * tell the difference. The desktop windows get no preload, no IPC, no
+ * nodeIntegration: the page talks to the kernel over HTTP like any client,
+ * so the renderer holds no powers a browser tab did not have.
+ *
+ * There is still a local machine, but it is found rather than contained. A
+ * kernel already answering here is connected to and left alone; a kernel
+ * merely installed here is started, and stopped again when its window
+ * closes. See local.js.
+ *
+ * The one page with a door into this process is the picker (connect.html):
+ * it lists machines and asks for one to be opened. Each machine opens once;
+ * asking again focuses its window.
+ *
+ *   anyos               the picker, then a desktop
+ *   anyos --smoke       open the local machine, verify, quit — for the suite
+ */
+import path from 'node:path';
+import { app, BrowserWindow, Menu, ipcMain, dialog, safeStorage } from 'electron';
+import { createMachines, LOCAL, reachable, guarded } from './machines.js';
+import { readConnectLine } from './connect-line.js';
+import { localKernel, startKernel, describe } from './local.js';
+import { createSecrets, createKeyring, normalise } from './secrets.js';
+import { installGuards } from './guard.js';
+
+const smoke = process.argv.includes('--smoke');
+const here = import.meta.dirname;
+const darwin = process.platform === 'darwin';
+
+/* the client's own memory — which machines it knows and the last one opened.
+   Not the state dir: that belongs to a kernel, and there is one per machine. */
+const machines = createMachines(path.join(app.getPath('userData'), 'machines.json'));
+
+/* the tokens for those machines, kept in their own 0600 file and sealed with
+   the OS keychain where there is one — see secrets.js */
+const secrets = createSecrets(path.join(app.getPath('userData'), 'secrets.json'), { cipher: safeStorage });
+
+/* what to answer a challenge with, per origin. A kernel we started put its
+   own minted token here and it never touches disk; a machine in the list
+   contributes the one that was typed for it. */
+const keyring = createKeyring();
+const offer = (url, token) => keyring.offer(url, token);
+
+/* the two answers this client gives Chromium about a kernel — which
+   certificate it accepts and which secret it presents. See guard.js. */
+installGuards(app, keyring);
+
+let picker = null;
+const windows = new Map();   /* machine id → its desktop window */
+const stops = new Set();     /* kernels started here, for will-quit — one we merely found is not ours */
+
+function desktopWindow(title) {
+  const win = new BrowserWindow({
+    width: 1280,
+    height: 800,
+    show: !smoke,
+    title,
+    backgroundColor: '#101014',
+    /* our shell draws its own menubar; keep the native controls as a slim
+       overlay rather than a title bar above a desktop */
+    titleBarStyle: darwin ? 'hiddenInset' : 'default',
+    webPreferences: { nodeIntegration: false, contextIsolation: true }
+  });
+  win.removeMenu?.();
+  return win;
+}
+
+/* a window closes → whatever this client started for it stops with it */
+function serve(win, stop) {
+  stops.add(stop);
+  win.on('closed', () => { stops.delete(stop); stop().catch(() => {}); });
+}
+
+/**
+ * This computer. A kernel already listening is someone else's — very likely
+ * an `anyos` in a terminal — so the window points at it and closing changes
+ * nothing. One we start is ours, and stops with its window.
+ */
+async function openLocal() {
+  const local = await localKernel();
+  if (local.state === 'absent') {
+    throw new Error('anyos is not installed on this computer — install it, or add a machine to connect to');
+  }
+  if (local.state === 'running') {
+    /* not ours, so not our token either — whatever was typed for This
+       computer is all we have to offer it */
+    offer(local.url, secrets.get(LOCAL));
+    return { win: desktopWindow('anyOS'), url: local.url };
+  }
+
+  const { url, stop, token } = await startKernel(local.kernel);
+  offer(url, token);
+  const win = desktopWindow('anyOS');
+  serve(win, stop);
+  return { win, url };
+}
+
+/* A kernel we did not start and do not own: ask whether it is there, then
+   point a window at it. Closing the window leaves it running — its lifetime
+   is the owner's, like the forward that made it reachable. */
+async function openAt(machine) {
+  const pin = secrets.pin(machine.id);
+  /* the window is told what to expect before it is pointed anywhere */
+  keyring.expect(machine.url, pin);
+  const problem = await reachable(machine.url, { pin });
+  if (problem) throw new Error(problem);
+  const token = secrets.get(machine.id);
+  if (!token && await guarded(machine.url, { pin })) {
+    throw new Error(`${machine.name} wants a token — Edit it and give it the kernel's ANYOS_TOKEN`);
+  }
+  offer(machine.url, token);
+  return { win: desktopWindow(`${machine.name} — anyOS`), url: machine.url };
+}
+
+async function openMachine(id) {
+  const open = windows.get(id);
+  if (open && !open.isDestroyed()) { open.focus(); return open; }
+  const machine = machines.get(id);
+  if (!machine) throw new Error('that machine is no longer in the list');
+  const { win, url } = await (id === LOCAL ? openLocal() : openAt(machine));
+  windows.set(id, win);
+  win.on('closed', () => { if (windows.get(id) === win) windows.delete(id); });
+  machines.used(id);
+  win.loadURL(url).catch(() => {});
+  return win;
+}
+
+function showPicker(problem) {
+  if (picker && !picker.isDestroyed()) {
+    picker.focus();
+    if (problem) picker.webContents.send('machines:problem', problem);
+    return;
+  }
+  picker = new BrowserWindow({
+    width: 620,
+    height: 540,
+    resizable: false,
+    minimizable: false,
+    fullscreenable: false,
+    title: 'anyOS',
+    backgroundColor: '#0c1014',
+    titleBarStyle: darwin ? 'hiddenInset' : 'default',
+    webPreferences: { preload: path.join(here, 'preload.cjs'), contextIsolation: true, nodeIntegration: false, sandbox: true }
+  });
+  picker.removeMenu?.();
+  picker.on('closed', () => { picker = null; });
+  if (problem) picker.webContents.once('did-finish-load', () => picker?.webContents.send('machines:problem', problem));
+  picker.loadFile(path.join(here, 'connect.html'));
+}
+
+/* the picker's calls; each answers { ok } or { ok: false, error } — a sentence, never a stack */
+const answer = fn => async (event, ...args) => {
+  try { return { ok: true, ...(await fn(event, ...args) ?? {}) }; } catch (err) { return { ok: false, error: err.message }; }
+};
+/* which build this is — the picker shows it, because "I pulled and still see
+   the old form" is otherwise unanswerable without a filesystem search */
+ipcMain.handle('machines:version', answer(() => ({ version: app.getVersion(), from: here })));
+ipcMain.handle('machines:list', answer(() => ({ machines: machines.list(), last: machines.last() })));
+ipcMain.handle('machines:local', answer(async () => {
+  const local = await localKernel();
+  const token = secrets.get(LOCAL);
+  /* only worth asking of a kernel that is actually up; one we would start
+     ourselves gets a door we hold the key to */
+  const door = local.state === 'running' ? await guarded(local.url) === true : false;
+  return { local: { state: local.state, guarded: door, ...describe({ ...local, guarded: door, token }) } };
+}));
+/* a fingerprint that is not one would otherwise be normalised away to
+   nothing, quietly leaving the machine unpinned and unreachable for a reason
+   nobody could see */
+function checkPin(fields) {
+  const given = String(fields?.fingerprint ?? '').trim();
+  if (given && !normalise(given)) {
+    throw Object.assign(new Error('that is not a certificate fingerprint — 64 hex characters, as the kernel printed it'), { status: 400 });
+  }
+}
+ipcMain.handle('machines:add', answer((_event, fields) => {
+  checkPin(fields);
+  const machine = machines.add(fields);
+  secrets.set(machine.id, fields?.token);
+  secrets.setPin(machine.id, fields?.fingerprint);
+  return { machine };
+}));
+ipcMain.handle('machines:update', answer((_event, id, fields) => {
+  checkPin(fields);
+  const machine = machines.update(id, fields);
+  secrets.set(machine.id, fields?.token);
+  secrets.setPin(machine.id, fields?.fingerprint);
+  return { machine };
+}));
+/* This computer is not in the list and has nothing to edit but its token */
+ipcMain.handle('machines:token', answer((_event, id, token) => { secrets.set(id, token); }));
+/* the form prefills with the real secret, so leaving it blank forgets it */
+ipcMain.handle('machines:secret', answer((_event, id) => ({
+  token: secrets.get(id) ?? '', fingerprint: secrets.pin(id) ?? '', sealed: secrets.sealed()
+})));
+ipcMain.handle('machines:remove', answer((_event, id) => { machines.remove(id); secrets.forget(id); }));
+/**
+ * A connect line, pasted: the machine is saved and opened, with nothing to
+ * press in between.
+ *
+ * There is no review step because there would be nothing to review — none of
+ * these values were typed here, and nobody checks a 64-character fingerprint
+ * by eye. The form's fields remain for editing a machine later, which is a
+ * different job.
+ *
+ * Saved before connecting, always. A kernel that is down or a port the
+ * firewall has not opened yet should leave a machine in the list to retry,
+ * not send someone back to the terminal for the line again.
+ */
+ipcMain.handle('machines:connect', answer(async (_event, text) => {
+  const line = readConnectLine(text);        /* throws a sentence of its own */
+  checkPin(line);
+  const existing = machines.byUrl(line.url);
+  /* the one case where a paste destroys something: an address already in the
+     list keeps its name, but its token and its certificate are replaced */
+  if (existing && !await confirmReplace(existing)) return { cancelled: true };
+
+  const machine = existing
+    ? machines.update(existing.id, { name: existing.name, url: line.url })
+    : machines.add({ name: line.name, url: line.url });
+  secrets.set(machine.id, line.token);
+  secrets.setPin(machine.id, line.fingerprint);
+
+  await openMachine(machine.id);
+  picker?.close();
+  return { machine };
+}));
+
+async function confirmReplace(machine) {
+  const { response } = await dialog.showMessageBox(picker ?? null, {
+    type: 'warning',
+    buttons: ['Replace', 'Cancel'],
+    defaultId: 0,
+    cancelId: 1,
+    message: `Replace the credentials for ${machine.name}?`,
+    detail: `${machine.url} is already in the list. This connect line replaces its token and the certificate it pins.`
+  });
+  return response === 0;
+}
+
+ipcMain.handle('machines:open', answer(async (_event, id) => {
+  await openMachine(id);
+  picker?.close();
+}));
+
+const menu = Menu.buildFromTemplate([
+  ...(darwin ? [{ role: 'appMenu' }] : []),
+  {
+    label: 'Machine',
+    submenu: [
+      { label: 'Connect to…', accelerator: 'CmdOrCtrl+Shift+O', click: () => showPicker() },
+      { type: 'separator' },
+      { role: 'close' }
+    ]
+  },
+  { role: 'editMenu' },
+  { role: 'windowMenu' }
+]);
+
+app.whenReady().then(async () => {
+  Menu.setApplicationMenu(menu);
+  if (!smoke) return showPicker();
+
+  const win = await openMachine(LOCAL);
+  win.webContents.once('did-finish-load', async () => {
+    const title = await win.webContents.executeJavaScript('document.title');
+    /* the desktop mounts asynchronously after load — give it a beat */
+    const shell = await win.webContents.executeJavaScript(`new Promise(done => setTimeout(() => {
+      const bar = document.querySelector('#menubar');
+      done(document.documentElement.className + ' · menubar ' + (bar
+        ? 'pad ' + getComputedStyle(bar).paddingLeft : 'not mounted'));
+    }, 800))`);
+    console.log(`[client] loaded ${win.webContents.getURL()} — title "${title}" · ${shell}`);
+    app.quit();
+  });
+});
+
+/* an OS quits when its window closes, on every platform — there is no
+   sensible dockless background state for a desktop */
+app.on('window-all-closed', () => app.quit());
+app.on('will-quit', () => { for (const stop of stops) stop().catch(() => {}); });

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "anyos-client",
+  "version": "0.2.0",
+  "license": "MIT",
+  "description": "The anyOS thin client \u2014 one window on a kernel, here or on another machine",
+  "type": "module",
+  "main": "main.js",
+  "bin": {
+    "anyos": "bin/anyos.js"
+  },
+  "files": [
+    "bin/",
+    "main.js",
+    "local.js",
+    "machines.js",
+    "secrets.js",
+    "guard.js",
+    "preload.cjs",
+    "connect.html",
+    "connect.css",
+    "connect.js",
+    "connect-line.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "electron": "^44.0.0"
+  },
+  "scripts": {
+    "start": "electron .",
+    "smoke": "electron . --smoke",
+    "test": "node test/machines.mjs && node test/secrets.mjs && node test/connect-line.mjs && node test/local.mjs && node test/electron.mjs",
+    "lint": "node test/boundaries.mjs"
+  }
+}

package/preload.cjs

@@ -0,0 +1,18 @@
+/* The picker's one door to the main process: a handful of calls about
+   machines, each answered with { ok } or { ok: false, error }. The desktop
+   windows get no preload at all. */
+const { contextBridge, ipcRenderer } = require('electron');
+
+contextBridge.exposeInMainWorld('machines', {
+  version: () => ipcRenderer.invoke('machines:version'),
+  list: () => ipcRenderer.invoke('machines:list'),
+  local: () => ipcRenderer.invoke('machines:local'),
+  add: fields => ipcRenderer.invoke('machines:add', fields),
+  update: (id, fields) => ipcRenderer.invoke('machines:update', id, fields),
+  remove: id => ipcRenderer.invoke('machines:remove', id),
+  secret: id => ipcRenderer.invoke('machines:secret', id),
+  token: (id, token) => ipcRenderer.invoke('machines:token', id, token),
+  open: id => ipcRenderer.invoke('machines:open', id),
+  connect: line => ipcRenderer.invoke('machines:connect', line),
+  onProblem: handler => { ipcRenderer.on('machines:problem', (_event, text) => handler(String(text))); }
+});