@openmeet/snowglobe 0.0.0-stage → 0.3.0-rc.1

package/lib/settings.mjs

@@ -0,0 +1,156 @@
+// The names an app's settings are built from: `${pds.alpha.url}` in snowglobe.yml's apps[].env.
+// Pure: a checked globe and a name in, a value out, or the reason the file has no such name. The
+// names and the reasons for them: OKF projects/atmo-events/2026-10-21-snowglobe-app-settings-design.md.
+//
+// The rule: the file's own section, then the name you gave it, then the field. Most values come from
+// the file alone. A few exist only once the globe is up (an account's DID and password, the lexicon
+// authority's DID, the CA, the mail page): `later` says what they are, and check, which has no state
+// to look in, passes a stand-in.
+
+const LATER = 'a value known only after snowglobe up';
+
+// The secrets: left out of snowglobe env unless asked for.
+export const isSecret = (name) => /^accounts\.[^.]+\.password$/.test(name);
+
+/**
+ * `text` split at its ${name} placeholders: { parts } where a part is { text } or { name }, or
+ * { error }. `$$` is a literal `$`; a `$` that starts neither passes through as written.
+ */
+export function parseValue(text) {
+  const parts = [];
+  let lit = '';
+  for (let i = 0; i < text.length; ) {
+    if (text[i] === '$' && text[i + 1] === '$') {
+      lit += '$';
+      i += 2;
+    } else if (text[i] === '$' && text[i + 1] === '{') {
+      const end = text.indexOf('}', i + 2);
+      if (end === -1) return { error: 'a ${ with no closing } (write $${ for a literal ${)' };
+      const name = text.slice(i + 2, end).trim();
+      if (!name) return { error: 'an empty ${}' };
+      if (lit) parts.push({ text: lit });
+      lit = '';
+      parts.push({ name });
+      i = end + 1;
+    } else lit += text[i++];
+  }
+  if (lit) parts.push({ text: lit });
+  return { parts };
+}
+
+const list = (xs) => (xs.length ? xs.join(', ') : 'none');
+
+/**
+ * The value of `name` in `globe` (a checked file): { value }, or { error } saying what is wrong
+ * with the name. `later(name)` gives the names known only after up (it returns undefined when the
+ * state has no value yet); without it they come back as { later: true }, which is all check needs.
+ */
+export function lookup(globe, name, later) {
+  const D = globe.domain;
+  const [head, ...rest] = name.split('.');
+  const fail = (error) => ({ error });
+  const after = (what = name) => {
+    if (!later) return { later: true };
+    const value = later(what);
+    return value === undefined ? fail(`${name} is ${LATER}; run snowglobe up first`) : { value };
+  };
+
+  // A server of a section, by the name the file gave it: <section>.<name>.<field>.
+  const server = (kind, items, fields) => {
+    const [n, field, ...more] = rest;
+    if (n === undefined) return fail(`${head} needs a name: ${head}.<name>.<field> (${list(items.map((i) => i.name))})`);
+    const item = items.find((i) => i.name === n);
+    if (!item) return fail(`${head}.${n} is not ${kind} in this file: ${list(items.map((i) => i.name))}`);
+    if (field === undefined || more.length || !Object.hasOwn(fields, field))
+      return fail(`${name} is not a value of ${head}.${n}; it has ${list(Object.keys(fields).map((f) => `${head}.${n}.${f}`))}`);
+    return { value: fields[field](item) };
+  };
+  const host = (i) => `${i.name}.${D}`;
+  const web = {
+    url: (i) => `https://${host(i)}`,
+    host,
+    did: (i) => `did:web:${host(i)}`,
+  };
+
+  switch (head) {
+    case 'domain':
+    case 'globe':
+      return rest.length ? fail(`${name} is not a name; ${head} has no fields`) : { value: head === 'domain' ? D : globe.globe };
+    case 'page':
+      return rest.join('.') === 'url' ? { value: `https://${D}/` } : fail(`${name} is not a name; the page has page.url`);
+    case 'pds':
+      return server('a PDS', globe.pds, web);
+    case 'grouphosts':
+      return server('a group host', globe.grouphosts, web);
+    case 'apps':
+      return server('an app', globe.apps, { url: (a) => `https://${a.name}.app.${D}`, host: (a) => `${a.name}.app.${D}` });
+    case 'services': {
+      const [svc, field, ...more] = rest;
+      const svcs = {
+        plc: { url: `https://plc.${D}` },
+        relay: { url: `https://relay.${D}`, ws: `wss://relay.${D}` },
+        jetstream: { url: `https://jetstream.${D}`, ws: `wss://jetstream.${D}/subscribe` },
+        slingshot: { url: `https://slingshot.${D}` },
+        pdsls: { url: `https://pdsls.${D}` },
+        mail: { url: null },
+        tap: { url: null },
+      };
+      if (!svc || !Object.hasOwn(svcs, svc)) return fail(`${svc ? `services.${svc}` : name} is not a service with an address: ${list(Object.keys(svcs))}`);
+      if (field === undefined || more.length || !Object.hasOwn(svcs[svc], field))
+        return fail(`${name} is not a value of services.${svc}; it has ${list(Object.keys(svcs[svc]).map((f) => `services.${svc}.${f}`))}`);
+      if (svc !== 'plc' && svc !== 'mail' && !globe.services[svc]) return fail(`services.${svc} is off in this file, so it has no address`);
+      return svc === 'mail' || svc === 'tap' ? after() : { value: svcs[svc][field] };
+    }
+    case 'accounts': {
+      if (rest.length === 1 && rest[0] === 'file') return after();
+      const [n, field, ...more] = rest;
+      if (n === undefined) return fail(`accounts needs a name: accounts.<name>.<field> (${list(globe.accounts.map((a) => a.name))})`);
+      const a = globe.accounts.find((x) => x.name === n);
+      if (!a) return fail(`accounts.${n} is not an account in this file: ${list(globe.accounts.map((x) => x.name))}`);
+      const fields = ['handle', 'pds', 'did', 'password'];
+      if (!fields.includes(field) || more.length) return fail(`${name} is not a value of accounts.${n}; it has ${list(fields.map((f) => `accounts.${n}.${f}`))}`);
+      if (field === 'handle') return { value: a.handle };
+      if (field === 'pds') return { value: `https://${a.pds}.${D}` };
+      return after();
+    }
+    case 'lexicons': {
+      if (rest[0] !== 'authority' || rest.length !== 2 || !['did', 'handle'].includes(rest[1]))
+        return fail(`${name} is not a name; the lexicon authority has lexicons.authority.did and lexicons.authority.handle`);
+      if (rest[1] === 'did') return after();
+      const p = globe.pds.find((x) => x.name === globe.lexicons.authority);
+      return { value: p?.bare_handles ? `lex-authority.${D}` : `lex-authority.${p?.name}.${D}` };
+    }
+    case 'ca':
+      return rest.join('.') === 'file' ? after() : fail(`${name} is not a name; the certificate authority has ca.file`);
+    default:
+      return fail(`${name} is not a name. Sections: domain, globe, page.url, pds.<name>, grouphosts.<name>, apps.<name>, services.<name>, accounts.<name>, accounts.file, lexicons.authority, ca.file`);
+  }
+}
+
+/** The problems with the names in every apps[].env of `globe`, as [where, message] pairs. */
+export function checkSettings(globe) {
+  const problems = [];
+  if (globe.tap?.webhook) {
+    const { parts, error } = parseValue(globe.tap.webhook);
+    if (error) problems.push(['services.tap.webhook', error]);
+    else
+      for (const part of parts) {
+        const found = part.name && lookup(globe, part.name);
+        if (found?.error) problems.push(['services.tap.webhook', found.error]);
+        else if (found?.later) problems.push(['services.tap.webhook', `${part.name} is known only after snowglobe up, so Tap cannot be given it`]);
+      }
+  }
+  globe.apps.forEach((app, i) => {
+    for (const [key, text] of Object.entries(app.env)) {
+      const at = `apps[${i}].env.${key}`;
+      const { parts, error } = parseValue(text);
+      if (error) problems.push([at, error]);
+      else
+        for (const part of parts) {
+          const found = part.name && lookup(globe, part.name);
+          if (found?.error) problems.push([at, found.error]);
+        }
+    }
+  });
+  return problems;
+}

package/lib/state.mjs

@@ -0,0 +1,109 @@
+// Which snowglobe a command acts on, and where its state is: the snowglobe.yml in the folder you
+// are in or the nearest one above (else SG_FILE, else the default globe at the repo root), the
+// `globe:` name in it, and from that name the state folder (<state root>/<name>, lib/env.mjs
+// stateRoot) and the compose project (the same name, unless SG_PROJECT is set). The state
+// folder records which file owns it, so two files that say `globe: t1` cannot share one folder,
+// or one compose project.
+
+import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { globeName } from './config.mjs';
+import { ROOT, stateRoot } from './env.mjs';
+
+/**
+ * The file a command reads when it is given none: SG_FILE, else ./snowglobe.yml, else the first
+ * snowglobe.yml in a folder above this one, else the default globe at the repo root. A file in
+ * the folder itself is named as 'snowglobe.yml'; one above, by its absolute path. With
+ * allowDefault false (a command that starts something), finding none is an error.
+ */
+export function findFile({ file, env = process.env, cwd = process.cwd(), allowDefault = true } = {}) {
+  if (file) return file;
+  if (env.SG_FILE) return env.SG_FILE;
+  const here = resolve(cwd);
+  for (let dir = here; ; dir = dirname(dir)) {
+    if (existsSync(join(dir, 'snowglobe.yml'))) return dir === here ? 'snowglobe.yml' : join(dir, 'snowglobe.yml');
+    if (dirname(dir) === dir) break;
+  }
+  if (!allowDefault)
+    throw new Error(
+      `no snowglobe.yml in ${here} or any folder above it, and SG_FILE is not set. ` +
+        'To run the default snowglobe on purpose: snowglobe up --default',
+    );
+  return join(ROOT, 'snowglobe.default.yml');
+}
+
+// The file that owns a state folder is recorded here, as an absolute path.
+const OWNER = 'owner';
+
+/** The file recorded as owning the state folder `state`, or '' when none is. */
+export function ownerOf(state) {
+  const record = join(state, OWNER);
+  return existsSync(record) ? readFileSync(record, 'utf8').trim() : '';
+}
+
+/**
+ * The file `up` or `down` was pointed at, from its -f option and its one word, which is a file
+ * or the name of a snowglobe (snowglobe ls shows them): { file } for a file, { name } for a
+ * snowglobe, {} for neither given (the file found from the folder you are in). A word that is a
+ * file that exists is that file; else it is a name when a state folder is called that. Throws
+ * when it is neither, or both -f and a word are given.
+ */
+export function pointedAt({ file, word, env = process.env } = {}) {
+  if (file && word) throw new Error(`give the snowglobe once: -f ${file} or ${word}, not both`);
+  if (file) return { file };
+  if (!word) return {};
+  if (existsSync(word) && statSync(word).isFile()) return { file: word };
+  if (!/[\\/]/.test(word) && existsSync(join(stateRoot(env), word))) return { name: word };
+  throw new Error(`${word} is not a file, and no snowglobe is called that (snowglobe ls lists them)`);
+}
+
+/**
+ * The snowglobe called `name`, as session returns it, for a command that stops or reads one
+ * without its file: `path` is the file recorded as its owner, '' when that file is gone. Throws
+ * when no state folder has the name.
+ */
+export function byName(name, { env = process.env } = {}) {
+  const state = join(stateRoot(env), name);
+  if (!existsSync(state)) throw new Error(`no snowglobe is called ${name} (snowglobe ls lists them)`);
+  const owner = ownerOf(state);
+  return { path: owner && existsSync(owner) ? owner : '', name, state, project: env.SG_PROJECT || name };
+}
+
+/**
+ * Refuse a state folder whose recorded owner is another file that still exists. With `claim`, a
+ * folder with no owner, or whose owner is gone (moved or deleted), is recorded as this file's.
+ */
+function owned({ name, state }, file, claim) {
+  // Returns a line to tell the user when a file took over a name whose first file is gone.
+  const mine = realpathSync(resolve(file));
+  const record = join(state, OWNER);
+  const first = ownerOf(state);
+  if (first && first !== mine && existsSync(first))
+    throw new Error(
+      `the snowglobe ${name} belongs to ${first} (its state is in ${state}), and ${mine} also says globe: ${name}. ` +
+        `Give one of them another name in its globe: line, or delete ${record} to hand ${name} to the second file`,
+    );
+  if (claim && first !== mine) {
+    mkdirSync(state, { recursive: true });
+    writeFileSync(record, `${mine}\n`);
+    if (first) return `the file that owned the snowglobe ${name} (${first}) is gone; ${mine} owns its state now`;
+  }
+  return null;
+}
+
+/**
+ * The snowglobe a command acts on: { path (as given, or found), name, state, project }. Throws
+ * when the file has no usable `globe:` name or another file owns that name's state. `claim`
+ * records this file as the owner (up and render do, once the file checks out; the commands that
+ * only use a snowglobe do not).
+ */
+export function session({ file, env = process.env, cwd = process.cwd(), claim = false, allowDefault = true } = {}) {
+  const path = findFile({ file, env, cwd, allowDefault });
+  const name = globeName(resolve(path));
+  const found = { path, name, state: join(stateRoot(env), name), project: env.SG_PROJECT || name };
+  owned(found, path, claim);
+  return found;
+}
+
+/** Record the session's file as the owner of its state folder (made if need be); a line to show when it took over from a file that is gone, else null. */
+export const claimState = (found) => owned(found, found.path, true);

package/lib/trust.mjs

@@ -0,0 +1,288 @@
+// Trusting the per-user CA (<state root>/ca/ca.crt) in the places a browser or a program looks, and
+// undoing it. One function per platform builds the steps for it, and the command runs them the same
+// way on every platform (lib/commands/trust.mjs).
+//
+// A step is { label, sudo, present(), add: [argv...], remove: [argv...], missing?, manual?, note? }:
+//   present()  true when the CA is already in that store, false when not, null when it can't be told
+//   add/remove the commands that put the CA there or take it out, as argument lists (printed as
+//              they run, so nothing is hidden)
+//   sudo       the commands need root; run through `sudo` unless we are root already
+//   missing    a tool the step needs that is not installed (what to install); the step is printed,
+//              not run
+//   manual     the step happens outside this machine's reach (Windows from WSL); it is printed
+//
+// The CA is limited by name constraints (lib/certs.mjs): it can only vouch for the snowglobe's
+// domain, devnet.internal and plc.directory, and for no IP address. Linux (OpenSSL, NSS), Windows and
+// macOS all enforce them, so trusting the CA machine-wide does not let it vouch for any other site.
+// They stay as they are.
+
+import { X509Certificate } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+
+// The CA's own name, from its subject: each CA has one of its own, which is also the nickname it
+// goes by in the NSS and Windows stores.
+export function caName(crt) {
+  const subject = new X509Certificate(readFileSync(crt)).subject;
+  const cn = subject.split('\n').find((l) => l.startsWith('CN='));
+  if (!cn) throw new Error(`${crt} has no common name`);
+  return cn.slice(3);
+}
+
+/** What the steps run on: real by default; tests pass their own `exec`, `onPath`, `isRoot` and `home`. */
+export function realContext(env = process.env) {
+  const onPath = (cmd) => {
+    for (const dir of (env.PATH ?? '').split(process.platform === 'win32' ? ';' : ':')) if (dir && existsSync(join(dir, cmd))) return true;
+    return false;
+  };
+  return {
+    platform: process.platform,
+    env,
+    home: env.HOME || env.USERPROFILE || '',
+    isRoot: typeof process.getuid === 'function' && process.getuid() === 0,
+    onPath,
+    // Runs argv; { status, stdout }. `capture` keeps the output (a check); otherwise the command talks to the terminal (a password prompt).
+    exec: (argv, { capture = false } = {}) => {
+      const r = spawnSync(argv[0], argv.slice(1), { env, encoding: 'utf8', stdio: capture ? ['ignore', 'pipe', 'pipe'] : 'inherit' });
+      return { status: r.error ? 127 : r.status, stdout: r.stdout ?? '' };
+    },
+  };
+}
+
+const ok = (ctx, argv) => ctx.exec(argv, { capture: true }).status === 0;
+
+/** True when the machine is Windows Subsystem for Linux (a Linux whose browser usually runs on Windows). */
+export function isWsl(ctx) {
+  if (ctx.platform !== 'linux') return false;
+  if (ctx.wsl !== undefined) return ctx.wsl;
+  if (ctx.env.WSL_DISTRO_NAME || ctx.env.WSL_INTEROP) return true;
+  try {
+    return /microsoft|wsl/i.test(readFileSync('/proc/sys/kernel/osrelease', 'utf8'));
+  } catch {
+    return false;
+  }
+}
+
+// ---- Linux ----------------------------------------------------------------------------------
+
+// The system store: Debian's update-ca-certificates or Fedora's update-ca-trust. Read by curl,
+// Node with --use-openssl-ca, Python, Go and the like.
+function linuxOsStep(ca, ctx) {
+  const same = (file) => existsSync(file) && readFileSync(file, 'utf8') === readFileSync(ca, 'utf8');
+  if (ctx.onPath('update-ca-certificates')) {
+    const file = '/usr/local/share/ca-certificates/snowglobe-ca.crt';
+    return {
+      label: 'system store (update-ca-certificates)',
+      sudo: true,
+      present: () => same(file),
+      add: [['install', '-m', '644', ca, file], ['update-ca-certificates']],
+      remove: [['rm', '-f', file], ['update-ca-certificates', '--fresh']],
+    };
+  }
+  if (ctx.onPath('update-ca-trust')) {
+    const file = '/etc/pki/ca-trust/source/anchors/snowglobe-ca.crt';
+    return {
+      label: 'system store (update-ca-trust)',
+      sudo: true,
+      present: () => same(file),
+      add: [['install', '-m', '644', ca, file], ['update-ca-trust', 'extract']],
+      remove: [['rm', '-f', file], ['update-ca-trust', 'extract']],
+    };
+  }
+  return {
+    label: 'system store',
+    sudo: true,
+    present: () => null,
+    add: [],
+    remove: [],
+    manual: true,
+    note: 'neither update-ca-certificates nor update-ca-trust is installed; add the CA to this system\'s store by its own tool',
+  };
+}
+
+// One NSS database (Chrome, Edge and Chromium read ~/.pki/nssdb; each Firefox profile has its own).
+// `create` makes an empty one when there is none (only the shared one is ever made).
+function nssStep(label, dir, ca, nick, ctx, { create = false } = {}) {
+  const db = `sql:${dir}`;
+  const have = existsSync(join(dir, 'cert9.db'));
+  const step = {
+    label,
+    sudo: false,
+    present: () => (!ctx.onPath('certutil') ? null : have && ok(ctx, ['certutil', '-L', '-d', db, '-n', nick])),
+    add: [
+      ...(have || !create ? [] : [['mkdir', '-p', dir], ['certutil', '-N', '-d', db, '--empty-password']]),
+      ['certutil', '-A', '-d', db, '-t', 'C,,', '-n', nick, '-i', ca],
+    ],
+    remove: [['certutil', '-D', '-d', db, '-n', nick]],
+  };
+  if (!ctx.onPath('certutil')) step.missing = 'certutil (Debian and Ubuntu: apt install libnss3-tools; Fedora: dnf install nss-tools)';
+  return step;
+}
+
+// Where Firefox keeps profiles on Linux: its own folder, and the snap and flatpak ones.
+function firefoxProfiles(home) {
+  const roots = [join(home, '.mozilla/firefox'), join(home, 'snap/firefox/common/.mozilla/firefox'), join(home, '.var/app/org.mozilla.firefox/.mozilla/firefox')];
+  return roots.flatMap((root) => {
+    if (!existsSync(root)) return [];
+    return readdirSync(root, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && existsSync(join(root, e.name, 'cert9.db')))
+      .map((e) => join(root, e.name));
+  });
+}
+
+function linuxSteps(ca, nick, ctx) {
+  const steps = [linuxOsStep(ca, ctx), nssStep('Chrome, Edge, Chromium (~/.pki/nssdb)', join(ctx.home, '.pki/nssdb'), ca, nick, ctx, { create: true })];
+  // A snap Chromium keeps its own copy of the shared database.
+  const snap = join(ctx.home, 'snap/chromium/current/.pki/nssdb');
+  if (existsSync(join(snap, 'cert9.db'))) steps.push(nssStep('Chromium snap', snap, ca, nick, ctx));
+  for (const dir of firefoxProfiles(ctx.home)) steps.push(nssStep(`Firefox profile ${dir}`, dir, ca, nick, ctx));
+  return steps;
+}
+
+// ---- WSL ------------------------------------------------------------------------------------
+
+// The browser runs on Windows, whose user store a Linux program can't change silently (Windows
+// asks you to confirm), so these are printed for you to run in PowerShell. The Linux steps still
+// run, for what runs inside WSL.
+function wslSteps(ca, nick, ctx) {
+  let winPath = ctx.exec(['wslpath', '-w', ca], { capture: true });
+  winPath = winPath.status === 0 ? winPath.stdout.trim() : '<the ca.crt above, as a Windows path (wslpath -w)>';
+  return [
+    ...linuxSteps(ca, nick, ctx),
+    {
+      label: 'Windows user store (Chrome, Edge, Firefox on Windows)',
+      sudo: false,
+      manual: true,
+      present: () => null,
+      add: [['certutil', '-user', '-addstore', 'Root', winPath]],
+      remove: [['certutil', '-user', '-delstore', 'Root', nick]],
+      note: 'run this in PowerShell on Windows; Windows asks you to confirm',
+    },
+  ];
+}
+
+// ---- macOS (not tried: no Mac was available when this was written) ------------------------------
+
+function macSteps(ca, nick, ctx) {
+  const keychain = join(ctx.home, 'Library/Keychains/login.keychain-db');
+  return [
+    {
+      label: 'login keychain (Chrome, Edge, Safari)',
+      sudo: false,
+      present: () => ok(ctx, ['security', 'find-certificate', '-c', nick, keychain]),
+      // macOS asks for your password or Touch ID itself.
+      add: [['security', 'add-trusted-cert', '-r', 'trustRoot', '-k', keychain, ca]],
+      remove: [['security', 'delete-certificate', '-c', nick, '-t', keychain]],
+    },
+    {
+      label: 'Firefox',
+      sudo: false,
+      manual: true,
+      present: () => null,
+      add: [],
+      remove: [],
+      note: 'Firefox keeps its own list: Settings, Privacy & Security, View Certificates, Authorities, Import (remove it there too)',
+    },
+  ];
+}
+
+// ---- Windows ----------------------------------------------------------------------------------
+
+function windowsSteps(ca, nick, ctx) {
+  return [
+    {
+      label: 'Windows user store (Chrome, Edge, Firefox)',
+      sudo: false,
+      present: () => ok(ctx, ['certutil', '-user', '-store', 'Root', nick]),
+      // Windows asks you to confirm; no administrator needed.
+      add: [['certutil', '-user', '-addstore', 'Root', ca]],
+      remove: [['certutil', '-user', '-delstore', 'Root', nick]],
+    },
+  ];
+}
+
+/** The steps for this platform, in order: [{ label, sudo, present, add, remove, ... }]. */
+export function trustSteps(ca, ctx = realContext()) {
+  const nick = caName(ca);
+  if (ctx.platform === 'darwin') return macSteps(ca, nick, ctx);
+  if (ctx.platform === 'win32') return windowsSteps(ca, nick, ctx);
+  return isWsl(ctx) ? wslSteps(ca, nick, ctx) : linuxSteps(ca, nick, ctx);
+}
+
+const show = (argv) => argv.map((a) => (/[^\w@%+=:,./-]/.test(a) ? `'${a}'` : a)).join(' ');
+
+/**
+ * Run (or, with dryRun, only print) the steps to add the CA or, with `remove`, to take it out.
+ * Every command is printed as it is run. Returns { done, failed, manual }: counts of steps taken
+ * (or already in place), steps that could not be (a missing tool, a refused sudo, a failed
+ * command, `noSudo`), and steps left for the user to run. Idempotent: a step whose store already
+ * has the CA (or, for remove, no longer has it) is skipped.
+ */
+export function applySteps(steps, { remove = false, dryRun = false, noSudo = false, ctx = realContext(), say = console.log } = {}) {
+  const out = { done: 0, failed: 0, manual: 0 };
+  const wrap = (step, argv) => (step.sudo && !ctx.isRoot ? ['sudo', ...argv] : argv);
+  for (const step of steps) {
+    const cmds = remove ? step.remove : step.add;
+    const verb = remove ? 'remove' : 'add';
+    say(`${step.label}${step.sudo && !ctx.isRoot ? ' [needs sudo]' : ''}`);
+    const print = (prefix) => cmds.forEach((c) => say(`  ${prefix}${show(wrap(step, c))}`));
+    if (step.manual) {
+      out.manual++;
+      say(`  for you to ${verb}${step.note ? ` (${step.note})` : ''}:`);
+      if (!cmds.length) continue;
+      print('$ ');
+      continue;
+    }
+    if (step.missing) {
+      // Nothing to remove from a store that was never made.
+      if (remove && !existsNss(step)) {
+        say('  nothing to remove');
+        out.done++;
+        continue;
+      }
+      out.failed++;
+      say(`  not done: needs ${step.missing}. Then run snowglobe trust${remove ? ' --remove' : ''} again; it would run:`);
+      print('$ ');
+      continue;
+    }
+    const present = step.present();
+    if (remove ? present === false : present === true) {
+      say(remove ? '  not in this store; nothing to remove' : '  already trusted; nothing to add');
+      out.done++;
+      continue;
+    }
+    if (noSudo && step.sudo && !ctx.isRoot) {
+      out.failed++;
+      say('  skipped (--no-sudo). To do it yourself:');
+      print('$ ');
+      continue;
+    }
+    if (dryRun) {
+      say(`  would ${verb}:`);
+      print('$ ');
+      out.done++;
+      continue;
+    }
+    if (step.sudo && !ctx.isRoot && !ctx.onPath('sudo')) {
+      out.failed++;
+      say('  not done: sudo is not installed. Run these as root:');
+      cmds.forEach((c) => say(`  # ${show(c)}`));
+      continue;
+    }
+    let good = true;
+    for (const c of cmds) {
+      say(`  $ ${show(wrap(step, c))}`);
+      if (ctx.exec(wrap(step, c)).status !== 0) {
+        good = false;
+        break;
+      }
+    }
+    say(good ? `  ${remove ? 'removed' : 'added'}` : '  failed');
+    good ? out.done++ : out.failed++;
+  }
+  return out;
+}
+
+// A step's own database exists, so a missing certutil leaves something behind to remove.
+const existsNss = (step) => step.remove.some((c) => c.some((a) => typeof a === 'string' && a.startsWith('sql:') && existsSync(join(a.slice(4), 'cert9.db'))));

package/lib/up.mjs

@@ -0,0 +1,54 @@
+// What snowglobe up decides without Docker: the app routes the file adds, whether the globe's
+// PDSes clash with an app's handle ending, the env names the file's accounts keep their logins
+// under. Pure: inputs in, text or lists out (lib/commands/up.mjs runs the globe).
+
+const envName = (label) => label.toUpperCase().replace(/-/g, '_');
+
+/**
+ * The routes in data/https/apps (`routes`) with each app the file runs locally (`fileApps`, the
+ * parsed globe's apps) set to the file's port and handle ending. A route the file does not name is
+ * kept, as `snowglobe app` made it. Throws when the file's ending is another route's.
+ */
+export function mergeRoutes(routes, fileApps) {
+  const out = [...routes];
+  for (const a of fileApps.filter((x) => x.local)) {
+    const route = { name: a.name, port: a.local.port, ending: a.local.handles ?? null };
+    const owner = route.ending && out.find((r) => r.ending === route.ending && r.name !== a.name);
+    if (owner)
+      throw new Error(`the file's app ${a.name} claims the handles under ${route.ending}, which already go to ${owner.name} (data/https/apps); snowglobe app --remove ${owner.name}`);
+    const i = out.findIndex((r) => r.name === a.name);
+    if (i === -1) out.push(route);
+    else out[i] = route;
+  }
+  return out;
+}
+
+/**
+ * The file's accounts ({ name, pds }), each with the env prefix its login is kept under in
+ * data/accounts.env: <NAME> on `home` (the PDS snowglobe account makes accounts on by default,
+ * where the base init's ALICE and BOB are), <NAME>_<PDS> on any other. A shell name cannot start
+ * with a digit, so 1st is _1ST. Throws when two accounts would share one.
+ */
+export function accountPrefixes(accounts, home) {
+  const seen = new Map();
+  return accounts.map(({ name, pds }) => {
+    const v = pds === home ? envName(name) : `${envName(name)}_${envName(pds)}`;
+    const prefix = /^[0-9]/.test(v) ? `_${v}` : v;
+    if (seen.has(prefix)) throw new Error(`${name}@${pds} and ${seen.get(prefix)} would both keep their logins as ${prefix}_*; rename one`);
+    seen.set(prefix, `${name}@${pds}`);
+    return { name, pds, prefix };
+  });
+}
+
+/**
+ * The first server of `pdsNames` (the PDSes and group hosts) named like the ending an app in
+ * `apps` claimed, as { pds, app }, or null. Such a server would take that app's handles: nginx
+ * keeps the first of two servers with one name, and the globe's come before the apps'.
+ */
+export function endingClash(pdsNames, apps) {
+  for (const pds of pdsNames) {
+    const app = apps.find((a) => a.ending === pds);
+    if (app) return { pds, app: app.name };
+  }
+  return null;
+}

package/lib/xrpc.mjs

@@ -0,0 +1,49 @@
+// XRPC calls to the globe's PDSes, for what an app makes on the https globe for itself: accounts
+// (snowglobe account), invite codes (snowglobe invite) and lexicons in the globe's lexicon
+// authority (snowglobe lexicons), each in lib/commands/. Each keeps its logins in a private env
+// file, prints only what an app reads (a DID, an NSID) on stdout, and nothing secret anywhere: a
+// password or code goes only to the file and to the PDS, in a request body, and an admin login or
+// access token only in a request header.
+
+import { adminPassword, snowglobeRequest } from './env.mjs';
+
+// An XRPC call. Resolves to { ok, status, json } (json {} when the answer is not JSON).
+export async function xrpc(base, nsid, { body, query, auth, root, state, env }) {
+  const url = new URL(`/xrpc/${nsid}`, base);
+  for (const [k, v] of Object.entries(query ?? {})) url.searchParams.set(k, v);
+  const headers = {};
+  if (auth) headers.Authorization = auth;
+  if (body !== undefined) headers['Content-Type'] = 'application/json';
+  const res = await snowglobeRequest(url.href, {
+    method: body === undefined ? 'GET' : 'POST',
+    headers,
+    body: body === undefined ? undefined : JSON.stringify(body),
+    root,
+    state,
+    env,
+  });
+  let json = {};
+  try {
+    json = JSON.parse(res.body);
+  } catch {}
+  return { ok: res.status >= 200 && res.status < 300, status: res.status, json };
+}
+
+// What a PDS said when it refused: its error name and message, never the rest of the answer.
+export const why = ({ status, json }) => [json.error, json.message].filter(Boolean).join(' ') || `HTTP ${status}`;
+
+// The admin password the PDSes were started with (lib/env.mjs adminPassword); no default, so a PDS
+// that has another password is not sent a guess.
+const adminAuth = (root, state, env) => {
+  const password = adminPassword({ root, state, env });
+  if (!password) throw new Error('no PDS admin password: run snowglobe up, which makes one, or set SG_PDS_ADMIN_PASSWORD to the one the PDSes were started with');
+  return `Basic ${Buffer.from(`admin:${password}`).toString('base64')}`;
+};
+
+// An invite code from a PDS's admin API.
+export async function mintInvite(pdsUrl, useCount, { root, state, env }) {
+  const res = await xrpc(pdsUrl, 'com.atproto.server.createInviteCode', { body: { useCount }, auth: adminAuth(root, state, env), root, state, env });
+  if (!res.ok || typeof res.json.code !== 'string') throw new Error(`createInviteCode on ${pdsUrl} failed: ${why(res)}`);
+  return res.json.code;
+}
+