@openmeet/snowglobe 0.3.0 → 0.5.0

package/README.md

@@ -1,7 +1,7 @@
-# Snowglobe
+# <img src="assets/snowglobe.svg" width="40" alt=""> Snowglobe
 
 Your own isolated [AT Protocol](https://atproto.com) network, for testing, research, and demos. A snowglobe has its own
-PDS, PLC directory and Jetstream (and a relay, once there is more than one PDS), and nothing in it reaches Bluesky's network. It uses
+PDS, PLC directory, relay and Jetstream, and nothing in it reaches Bluesky's network. It uses
 https and the real network's sign-in (OAuth), so an app built for the real network runs against it
 with no test-only code.
 
@@ -19,9 +19,9 @@ One file, `snowglobe.yml`, says what a snowglobe runs. [`snowglobe.default.yml`]
 is the one to start from. It gives you:
 
 - one current PDS (personal data server, where an account's records live and where it signs in), at
-  `https://main.local.snowglobe.at`, with two test accounts, `alice` and `bob`;
-- a PLC directory, the phone book that says which PDS holds each `did:plc` account; it also answers as
-  `plc.directory` for your app;
+  `https://main.snowglobe.local.snowglobe.at`, with two test accounts, `alice` and `bob`;
+- a PLC directory, the phone book that says which PDS holds each `did:plc` account; your app is told
+  its address;
 - Jetstream, a simple stream of every write on the network, for apps that follow it;
 - Slingshot, which looks up a handle's DID and PDS inside the network;
 - PDSls, to browse the network's records;
@@ -39,36 +39,32 @@ The file also holds commented examples for adding more, up to a full setup:
 [`docs/examples/atmo.yml`](docs/examples/atmo.yml) is a larger file, with three PDSes, a relay and a
 lexicon authority, that [Example: atmo](docs/examples/atmo.md) builds on.
 
-Every name is under one domain, `local.snowglobe.at`, served by nginx with a certificate from a
-local CA that the snowglobe makes for itself. There is no AppView and no feed generator.
+Every name is under the snowglobe's own domain, `<globe>.local.snowglobe.at`, served by nginx with a
+certificate from a local CA that the snowglobe makes for itself. There is no AppView and no feed generator.
 [The snowglobe](docs/snowglobe.md) shows the whole file and what each part does.
 
 ## What you need
 
-Every service in a snowglobe has its own https name under `local.snowglobe.at`, such as
-`alice.local.snowglobe.at`. Handles, sign-in (OAuth) and DID documents all carry those names, so
-your computer has to send the names to the snowglobe, and trust its certificate. Here is what to do.
+Every service in a snowglobe has its own https name under the snowglobe's domain, such as
+`alice.snowglobe.local.snowglobe.at` for the default file. Handles, sign-in (OAuth) and DID documents
+all carry those names, so your computer has to send the names to the snowglobe, and trust its
+certificate. Here is what to do.
 
-**Before you start it:**
-
-1. Install Docker with Compose, and Node 20 or newer. Use Linux, or Windows with WSL 2.
-2. To run a command against the snowglobe from your machine (`snowglobe run`: your own app, its
-   tests, or the `curl` example below), also install
-   [bubblewrap](https://github.com/containers/bubblewrap): `sudo apt install bubblewrap` on Debian or
-   Ubuntu. You do not need it to bring a snowglobe up or to look at one in a browser.
+**Before you start it:** install Docker with Compose, and Node 20 or newer. Use Linux, or Windows with
+WSL 2.
 
 **After it is up, to open it in a browser or reach it from an app:**
 
-3. Make the names reach the snowglobe.
-   - Docker and your browser on the same computer: you usually do nothing, because public DNS answers
-     every name under `local.snowglobe.at` with `127.0.0.1`. If the browser says "server not found",
-     your router is dropping that answer. See
+1. The names reach the snowglobe on their own. Public DNS answers every name under
+   `local.snowglobe.at` with `127.0.0.1`, where `snowglobe up` starts a name router that passes each
+   connection to the snowglobe the name is under, so every snowglobe on the machine answers at once.
+   - If the browser says "server not found", your router is dropping that answer. See
      [When the browser cannot open it](docs/browser.md#when-the-browser-cannot-open-it).
-   - Docker in a dev container, or on another machine: the snowglobe's proxy runs with every `up`, on
-     `127.0.0.1:1080`; point your browser at it ([From a browser on your own computer](docs/browser.md)).
-   - A command started with `snowglobe run`: you do nothing, it sets the names up itself.
-4. Trust the snowglobe's certificate authority (CA). Run `snowglobe trust` on the machine that runs
-   Docker. For another machine, see [From a browser on your own computer](docs/browser.md).
+   - With Docker in a dev container, or on another machine, forward its port 443 to your computer
+     ([From a browser on your own computer](docs/browser.md)).
+2. Trust the snowglobe's certificate authority (CA). Run `snowglobe trust` on the machine that runs
+   Docker. For another machine, see [From a browser on your own computer](docs/browser.md). A
+   command started with `snowglobe run` trusts it without this.
 
 **Why not just use ports?** The PDSes are not published on ports at all: only nginx (443), the proxy,
 the PLC, Jetstream and MailDev are. A PDS's address is its name, and that name is what a DID document, a
@@ -93,25 +89,25 @@ To keep the command with one project instead, run `npm install --save-dev @openm
 `snowglobe.yml` (copy it from `node_modules/@openmeet/snowglobe/snowglobe.default.yml`). Either
 command also fits in a `package.json` script.
 
-Now try it. `snowglobe run` runs a command that can reach the snowglobe by name, and `--cacert`
-gives curl the snowglobe's certificate authority (CA), so it trusts the snowglobe's https:
+Now try it. The snowglobe's names work for any program on the machine, and `--cacert` gives curl the
+snowglobe's certificate authority (CA), so it trusts the snowglobe's https:
 
 ```bash
 # Sign up a new account, then look up alice's account through Slingshot
 snowglobe account carol CAROL                # CAROL: the prefix of her login variables, such as CAROL_PASSWORD
-snowglobe run curl -s --cacert ~/.local/share/snowglobe/ca/ca.crt \
-  'https://slingshot.local.snowglobe.at/xrpc/com.bad-example.identity.resolveMiniDoc?identifier=alice.local.snowglobe.at'
+curl -s --cacert ~/.local/share/snowglobe/ca/ca.crt \
+  'https://slingshot.snowglobe.local.snowglobe.at/xrpc/com.bad-example.identity.resolveMiniDoc?identifier=alice.snowglobe.local.snowglobe.at'
 ```
 
 To look around in a browser, you need two things: the browser has to trust the snowglobe's
 certificate, and it has to be able to find the snowglobe. If Docker runs on the same computer as your
-browser, run `snowglobe trust` and open `https://local.snowglobe.at/`, the network's page,
+browser, run `snowglobe trust` and open `https://snowglobe.local.snowglobe.at/`, the network's page,
 which lists every service, account and write. If Docker runs in a dev container or on another
-machine, your browser also needs the snowglobe's small proxy, which sends the snowglobe's names to
-it; [From a browser on your own computer](docs/browser.md) walks through both.
+machine, also forward its port 443 to your computer;
+[From a browser on your own computer](docs/browser.md) walks through both.
 
 The default snowglobe comes with one app to look at, [PDSls](docs/snowglobe.md#pdsls-browsing-the-networks-records),
-the record browser. `https://pdsls.local.snowglobe.at/at://alice.local.snowglobe.at` shows alice's repo,
+the record browser. `https://pdsls.snowglobe.local.snowglobe.at/at://alice.snowglobe.local.snowglobe.at` shows alice's repo,
 once your browser can reach the snowglobe as above.
 
 Stop the snowglobe with `snowglobe down`. Add `-v` to delete its data too, every account
@@ -123,10 +119,10 @@ To run your own app inside of a snowglobe, see [Your app in a snowglobe](docs/yo
 
 ## Platforms
 
-Snowglobe runs on Linux, and on Windows under WSL 2. Both are tested. macOS is not supported, but we'd love to.
+Snowglobe runs on Linux, and on Windows under WSL 2. Both are tested. macOS is not supported yet.
 If you try it on a Mac, please
 [open an issue](https://github.com/OpenMeet-Team/snowglobe/issues) with what broke, or that it
-worked, and we'd love to experiment with you.
+worked.
 
 ## Documentation
 
@@ -134,11 +130,13 @@ worked, and we'd love to experiment with you.
   down, and what it writes.
 - [Your app in a snowglobe](docs/your-app.md): `snowglobe run`, and the tools that make an app's
   accounts, invite codes, lexicons and routes.
-- [From a browser on your own computer](docs/browser.md): the proxy, launch flags, and trusting the
-  CA.
+- [From a browser on your own computer](docs/browser.md): the name router, Docker on another
+  machine, and trusting the CA.
 - [How it works](docs/how-it-works.md): what runs and how it is wired, Slingshot, and the relay build.
 - [Configuration](docs/configuration.md): the settings.
 - [Testing Snowglobe](docs/testing.md): the test suite and the smoke run.
+- [Example: Statusphere](docs/examples/statusphere.md): the atproto example app on a snowglobe, with
+  two small changes. CI runs it end to end.
 - [Example: atmo](docs/examples/atmo.md): an events app on a local snowglobe.
 - The older plain-http stack (`npm run up`) is not in this version. Its code and README are in the
   [v0.2.0 tag](https://github.com/OpenMeet-Team/snowglobe/tree/v0.2.0) (v0.1.0 has the first version of it).

package/bin/snowglobe.mjs

@@ -13,7 +13,7 @@
 //   app       routes https://<name>.app.<domain> to a port on this machine
 //   up        brings the globe up, as the compose project named for its file (or <name>, -f <file>)
 //   down      stops it (the same ways)
-//   run       runs a command with the app's settings, and plc.directory pointed at the snowglobe
+//   run       runs a command with the app's settings and the snowglobe's CA
 //
 // A snowglobe is the snowglobe.yml in the folder you are in or the nearest one above (else
 // SG_FILE, else the default). Its state is kept per user, not in a checkout: ~/.local/share/

package/lib/certs.mjs

@@ -9,14 +9,15 @@
 // Delete the CA's ca.* to start over, and then trust the new ca.crt again everywhere the old one
 // was trusted.
 //
-// The CA can only vouch for servers under the default domain, the domain it was made for
+// The CA can only vouch for servers under local.snowglobe.at (the zone every snowglobe's own
+// domain is under, <globe>.local.snowglobe.at), a domain outside it that it was made for,
 // and plc.directory (name constraints, serverAuth only, no IP addresses), so
 // trusting it on a host cannot put any other site at risk, even if ca.key leaks. A name outside
-// those is refused before the leaf is touched; widening the list, or a snowglobe on another
-// domain made after the CA, means a new CA, trusted again.
+// those is refused before the leaf is touched; widening the list, or a snowglobe on a domain
+// outside the zone made after the CA, means a new CA, trusted again.
 //
-// A TLS wildcard covers one label, so *.local.snowglobe.at does not cover a handle on the PDS
-// named regular (<name>.regular.local.snowglobe.at); each handle domain has its own.
+// A TLS wildcard covers one label, so *.mine.local.snowglobe.at does not cover a handle on the PDS
+// named regular (<name>.regular.mine.local.snowglobe.at); each handle domain has its own.
 
 import 'reflect-metadata';
 import { AsnConvert } from '@peculiar/asn1-schema';
@@ -25,7 +26,7 @@ import * as x509 from '@peculiar/x509';
 import { X509Certificate as NodeCertificate, createPrivateKey, randomBytes, webcrypto } from 'node:crypto';
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { DEFAULT_DOMAIN } from './config.mjs';
+import { LOCAL_ZONE } from './config.mjs';
 
 x509.cryptoProvider.set(webcrypto);
 
@@ -104,9 +105,11 @@ async function makeCa(domain, now) {
   const name = `snowglobe local CA ${now.toISOString().slice(0, 10)} ${randomBytes(3).toString('hex')}`;
   const subtree = (gn) => new GeneralSubtree({ base: new GeneralName(gn) });
   const constraints = new NameConstraints({
-    // One CA serves every snowglobe, so the default domain is always in, whatever domain the
-    // snowglobe that makes it is on.
-    permittedSubtrees: new GeneralSubtrees([...new Set([DEFAULT_DOMAIN, domain, ...FIXED])].map((d) => subtree({ dNSName: d }))),
+    // One CA serves every snowglobe, so the local zone is always in, whatever domain the
+    // snowglobe that makes it is on; a domain inside the zone needs no subtree of its own.
+    permittedSubtrees: new GeneralSubtrees(
+      [...new Set([LOCAL_ZONE, ...(within(domain, [LOCAL_ZONE]) ? [] : [domain]), ...FIXED])].map((d) => subtree({ dNSName: d })),
+    ),
     excludedSubtrees: new GeneralSubtrees([subtree({ iPAddress: '0.0.0.0/0' }), subtree({ iPAddress: '::/0' })]),
   });
   const cert = await x509.X509CertificateGenerator.createSelfSigned({

package/lib/commands/account.mjs

@@ -2,13 +2,13 @@
 //
 // account creates or finds <name> on <pds> (the PDS with bare handles, else the seed PDS):
 // <name>.<domain> there, <name>.<pds>.<domain> on the others. Its login goes into ACCOUNTS_FILE
-// (accounts.env in the snowglobe's state folder by default, mode 600) as <PREFIX>_HANDLE, _DID, _PASSWORD and _PDS, its
-// handle into the names bin/snowglobe.mjs run maps (restart a process under it to pick one up), and
-// its DID alone to stdout. A rerun finds it. It reads the rendered globe, and prints no secret
+// (accounts.env in the snowglobe's state folder by default, mode 600) as <PREFIX>_HANDLE, _DID, _PASSWORD and _PDS, and
+// its DID alone to stdout. The handle resolves at once: it is under the snowglobe's domain, which
+// the name router serves. A rerun finds it. It reads the rendered globe, and prints no secret
 // (lib/xrpc.mjs).
 
 import { randomBytes } from 'node:crypto';
-import { ROOT, UsageError, addName, envGet, envPut, globeFacts, loginsFile, paths } from '../env.mjs';
+import { ROOT, UsageError, envGet, envPut, globeFacts, loginsFile, paths } from '../env.mjs';
 import { session } from '../state.mjs';
 import { mintInvite, why, xrpc } from '../xrpc.mjs';
 
@@ -31,7 +31,7 @@ export async function run({ positionals: [name, prefix, pds] }) {
 /**
  * Create, or find, the account <name> on the globe's PDS `pds` (the one with bare handles, else
  * the seed PDS, by default), and keep its login in `file` as <prefix>_HANDLE, _DID, _PASSWORD and
- * _PDS. Its handle is added to the names snowglobe run maps. Resolves to the DID. A rerun signs in
+ * _PDS. Resolves to the DID. A rerun signs in
  * with the kept password and finds the account; a PDS that takes invite codes is sent one
  * (SG_INVITE_CODE, else a single-use code minted for this account), the others none.
  */
@@ -64,7 +64,6 @@ export async function account({ name, prefix, pds, file, root = ROOT, state, env
     const res = await xrpc(pdsUrl, 'com.atproto.server.createSession', { body: { identifier: handle, password: kept }, ...opts });
     if (res.ok && typeof res.json.did === 'string') {
       if (envGet(`${prefix}_DID`, accounts) !== res.json.did) save(res.json.did, kept);
-      addName(handle, { root, state });
       log(`Found ${handle} -> ${res.json.did}`);
       return res.json.did;
     }
@@ -79,7 +78,6 @@ export async function account({ name, prefix, pds, file, root = ROOT, state, env
   const res = await xrpc(pdsUrl, 'com.atproto.server.createAccount', { body, ...opts });
   if (!res.ok || typeof res.json.did !== 'string') throw new Error(`createAccount ${handle} on ${pdsUrl} failed: ${why(res)}`);
   save(res.json.did, password);
-  addName(handle, { root, state });
   log(`Created ${handle} on ${pdsUrl} -> ${res.json.did}`);
   return res.json.did;
 }

package/lib/commands/down.mjs

@@ -11,9 +11,14 @@
 // alice and bob and rewrites accounts.env from scratch, dropping the logins the tools wrote there
 // (their accounts are gone too), and the lexicon authority is made again. The fixed secrets an
 // older snowglobe kept for its data (secrets.env) are dropped with it, so up makes random ones. The CA, the leaf and
-// the app routes stay either way. The project is guarded as up guards it.
+// the app routes stay either way. The project is guarded as up guards it. Once the project is
+// down, the name router stops routing to it, and is removed when no snowglobe is left to route
+// (lib/router.mjs).
 
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import { ROOT, dc, dropLegacySecrets, guardProject } from '../env.mjs';
+import { dropRoute, routerDir, syncRouter } from '../router.mjs';
 import { byName, pointedAt, session } from '../state.mjs';
 
 export const command = {
@@ -27,7 +32,7 @@ export function run({ values, positionals: [word] }) {
   return down({ volumes: values.volumes, ...pointedAt({ file: values.file, word }) });
 }
 
-export function down({ volumes = false, file, name, root = ROOT, env = process.env } = {}) {
+export async function down({ volumes = false, file, name, root = ROOT, env = process.env, log = (m) => console.error(m) } = {}) {
   // The shared devnet is refused before anything is looked up, even by a file that is not there.
   if (env.SG_PROJECT) guardProject(env);
   const found = name ? byName(name, { env }) : session({ file, env });
@@ -36,5 +41,9 @@ export function down({ volumes = false, file, name, root = ROOT, env = process.e
   if (res.error) throw res.error;
   // The data the fixed secrets were kept for is gone only once compose says it removed it.
   if (volumes && res.status === 0) dropLegacySecrets({ root, state: found.state });
+  // Only a snowglobe the router routes to touches it. The route is dropped under the router's
+  // lock; when another down got there first, the router is already in line.
+  const rdir = routerDir(env);
+  if (res.status === 0 && existsSync(join(rdir, 'routes', project))) await syncRouter({ dir: rdir, env, log, change: () => dropRoute(rdir, project) });
   return res.status ?? 1;
 }

package/lib/commands/ls.mjs

@@ -1,16 +1,19 @@
 // bin/snowglobe.mjs ls
 //
 // ls lists the snowglobes on this machine: every folder in the state root (lib/env.mjs stateRoot;
-// ca/, the one CA, is not one) with its name, the domain it was rendered for, whether its compose
-// project is running, and the file that owns it. Take the name to `up`, `down`, or a file to -f.
+// ca/, the one CA, and dot folders such as the name router's .router are not ones) with its name,
+// the domain it was rendered for, whether its compose project is running, and the file that owns
+// it. Take the name to `up`, `down`, or a file to -f.
 // "up" is a project with a container running (the one-shot init and relay-init have exited by
 // then), "down" is none, or no project yet; "unknown" is what it says when Docker did not answer.
+// When the name router routes any snowglobe, a last line says whether it is running and to which.
 // Reads only; nothing is started.
 
 import { spawnSync } from 'node:child_process';
 import { existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { ROOT, envGet, paths, stateRoot } from '../env.mjs';
+import { ROOT, ROUTER_ADDRESS, envGet, paths, stateRoot } from '../env.mjs';
+import { readRoutes, routerDir, routerState } from '../router.mjs';
 import { ownerOf } from '../state.mjs';
 
 export const command = {
@@ -44,7 +47,7 @@ export function list({ root = ROOT, env = process.env, statuses = projectStatuse
   const base = stateRoot(env);
   if (!existsSync(base)) return [];
   return readdirSync(base, { withFileTypes: true })
-    .filter((e) => e.isDirectory() && e.name !== 'ca')
+    .filter((e) => e.isDirectory() && e.name !== 'ca' && !e.name.startsWith('.'))
     .map((e) => {
       const state = join(base, e.name);
       const owner = ownerOf(state);
@@ -58,15 +61,26 @@ export function list({ root = ROOT, env = process.env, statuses = projectStatuse
     .sort((a, b) => a.name.localeCompare(b.name));
 }
 
+// The last line: whether the name router runs and what it routes, when it routes anything. Shown
+// with no snowglobe listed too, since a route can outlive its state folder.
+function routerLine() {
+  const routes = readRoutes(routerDir());
+  if (!routes.length) return;
+  const word = { running: 'running', stopped: 'stopped', missing: 'not running' }[routerState().state];
+  console.log(`\nName router on ${ROUTER_ADDRESS}:443: ${word}, routing ${routes.map((r) => `${r.domain} to ${r.globe}`).join(', ')}`);
+}
+
 export function run() {
   const rows = list();
   if (!rows.length) {
     console.log(`No snowglobes in ${stateRoot()}. snowglobe up in a folder with a snowglobe.yml makes one.`);
+    routerLine();
     return 0;
   }
   const head = { name: 'NAME', domain: 'DOMAIN', state: 'STATE', file: 'FILE' };
   const cols = Object.keys(head);
   const width = Object.fromEntries(cols.map((c) => [c, Math.max(head[c].length, ...rows.map((r) => r[c].length))]));
   for (const r of [head, ...rows]) console.log(cols.map((c, i) => (i === cols.length - 1 ? r[c] : r[c].padEnd(width[c]))).join('  '));
+  routerLine();
   return 0;
 }

package/lib/commands/run.mjs

@@ -1,14 +1,10 @@
 // bin/snowglobe.mjs run [--app <name>] [--] <cmd> [args...]
 //
-// run runs a command with the snowglobe around it, for that command's process tree only:
+// run runs a command with the snowglobe's settings:
 //   - it is handed the app's settings, the apps[].env of the snowglobe.yml (lib/commands/env.mjs;
 //     the same as snowglobe env, secrets included, none printed). They win over a value already in
 //     the environment, and one line names the ones they replaced. --app picks the app when the
 //     file lists several;
-//   - the globe's names (its page, each PDS, its services and plc.directory, from the rendered
-//     globe), every handle in https/names (account and up add them) and every app in
-//     https/apps, as <name>.app.<domain>, resolve to SG_BIND, where nginx answers on
-//     443 (lib/hosts.mjs). HTTPS_RUN_EXTRA_NAMES adds names (space-separated);
 //   - Node trusts the globe's CA (NODE_EXTRA_CA_CERTS=<state root>/ca/ca.crt), on top of its own
 //     roots. Miniflare passes the same file on to workerd.
 //
@@ -17,20 +13,18 @@
 // e.g. bin/snowglobe.mjs run node scripts/https-probe.mjs
 //      (cd ../myapp && ../snowglobe/bin/snowglobe.mjs run npm run dev)
 //
-// How: bubblewrap gives the command its own mount namespace with a generated hosts file bound
-// over /etc/hosts. Nothing else changes: same filesystem, same network, same user. Outside,
-// every name resolves as usual. The names are read when the command starts, so a handle or app
-// added later needs a restart of the command. Linux only: a Mac has no bubblewrap, and reaches
-// the globe through snowglobe env instead (the names resolve through public DNS, and the CA is in
-// NODE_EXTRA_CA_CERTS).
+// Nothing maps names. Each snowglobe has a domain of its own under local.snowglobe.at, whose
+// public DNS answers every name with 127.0.0.1, where the name router passes each connection to
+// the snowglobe the name is under (lib/router.mjs). So every name resolves as it does anywhere on
+// the machine, a handle made after the command started included. plc.directory is the real one:
+// an app takes the snowglobe's PLC directory as a setting (${services.plc.url}), as it must on a
+// hosted globe. A domain of your own, outside local.snowglobe.at, has to resolve to 127.0.0.1 the
+// same way.
 
 import { spawn } from 'node:child_process';
-import { accessSync, constants, existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { constants as os } from 'node:os';
-import { delimiter, join } from 'node:path';
-import { readApps } from '../apps.mjs';
-import { ROOT, paths, resolveBind, resolveDomain } from '../env.mjs';
-import { hostsFile, runNames } from '../hosts.mjs';
+import { ROOT, paths, resolveDomain } from '../env.mjs';
 import { session } from '../state.mjs';
 import { appSettings } from './env.mjs';
 
@@ -48,48 +42,25 @@ export const command = {
   },
 };
 
-// The first `name` on PATH that can be run, or null.
-function onPath(name, env) {
-  for (const dir of (env.PATH ?? '').split(delimiter).filter(Boolean)) {
-    try {
-      accessSync(join(dir, name), constants.X_OK);
-      return join(dir, name);
-    } catch {}
-  }
-  return null;
-}
-
 export const run = ({ cmd, app }) => runUnder(cmd, { settings: appSettings({ app, secrets: true }).vars });
 
 /**
- * Run `cmd` (a word list) under the globe's names with `settings` ([{ name, value }], from
- * appSettings) in its environment; resolves to its exit code. A setting replaces a value of the same
- * name already in `env`, and `log` is told which.
+ * Run `cmd` (a word list) with `settings` ([{ name, value }], from appSettings) and the globe's CA
+ * in its environment; resolves to its exit code. A setting replaces a value of the same name
+ * already in `env`, and `log` is told which.
  */
 export function runUnder(cmd, { root = ROOT, env = process.env, state = session({ env }).state, settings = [], log = (m) => console.error(m) } = {}) {
-  if (process.platform !== 'linux')
-    throw new Error('run needs Linux (bubblewrap) for now; on this system eval "$(snowglobe env)" hands the app the same settings');
   const p = paths(root, state);
   if (!existsSync(p.ca)) throw new Error(`no ${p.ca}; run snowglobe up (or certs) first`);
-  if (!existsSync(p.leafNames)) throw new Error(`no ${p.leafNames}; run snowglobe up first`);
-  const bwrap = onPath('bwrap', env);
-  if (!bwrap) throw new Error('bwrap (bubblewrap) is not installed, or not on PATH');
-  // Refuses a SG_DOMAIN the render is not for, and a SG_BIND that is not loopback.
-  const { domain } = resolveDomain({ root, state, env });
-  const bind = resolveBind({ root, state, env });
-
-  const read = (f) => (existsSync(f) ? readFileSync(f, 'utf8') : '');
-  const names = runNames({ leafNames: read(p.leafNames), handles: read(p.names), apps: readApps(p), domain, extra: env.HTTPS_RUN_EXTRA_NAMES });
-  // Written aside and renamed, so a run already holding the old file is undisturbed.
-  const hosts = join(p.https, 'hosts');
-  writeFileSync(`${hosts}.tmp.${process.pid}`, hostsFile(read('/etc/hosts'), names, bind), { mode: 0o644 });
-  renameSync(`${hosts}.tmp.${process.pid}`, hosts);
+  if (!existsSync(p.globeEnv)) throw new Error(`no ${p.globeEnv}; run snowglobe up first`);
+  // Refuses a SG_DOMAIN the render is not for.
+  resolveDomain({ root, state, env });
 
   // Never the values: a setting may be a login.
   const replaced = settings.filter((x) => !x.auto && env[x.name] !== undefined && env[x.name] !== x.value).map((x) => x.name);
   if (replaced.length) log(`snowglobe run: the snowglobe's settings replaced ${replaced.join(', ')} from the environment`);
 
-  const child = spawn(bwrap, ['--dev-bind', '/', '/', '--ro-bind', hosts, '/etc/hosts', '--die-with-parent', '--', ...cmd], {
+  const child = spawn(cmd[0], cmd.slice(1), {
     stdio: 'inherit',
     env: { ...env, NODE_EXTRA_CA_CERTS: p.ca, ...Object.fromEntries(settings.map((x) => [x.name, x.value])) },
   });

package/lib/commands/up.mjs

@@ -23,7 +23,9 @@
 //      group host built from a folder is built again (Docker's cache keeps that quick)
 //   4. pass 1: up. The base init seeds alice, bob and SG_INVITE_CODE into
 //      data/accounts.env on the PDS with bare handles (else the first), as it does for the
-//      http stacks.
+//      http stacks. Then the name router (lib/router.mjs) sends the globe's domain and every name
+//      under it to the globe's own address, and is started if it is not running. A domain another
+//      running snowglobe is routed at is refused before anything starts.
 //   5. the lexicon authority, lex-authority on the file's lexicons.authority PDS
 //      (LEX_AUTHORITY_* in data/accounts.env), then pass 2: up with
 //      SG_LEXICON_AUTHORITY_DID, which recreates the PDSes with it
@@ -41,16 +43,18 @@
 // two snowglobes need no port settings; a port variable moves one, in the environment or .env. devnet-spaces, the shared devnet, is refused (exit 3) as
 // the project unless SG_RESET_OK=1, before anything else is done.
 
+import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { appEnding, appEndingMessage, formatApps, readApps, renderRoutes, writeApps } from '../apps.mjs';
 import { loadGlobe } from '../config.mjs';
-import { ROOT, addName, chooseBind, dc, ensureSecrets, projectHasData, snowglobeRequest, envGet, guardProject, makePrivate, oldDataNotice, paths, renamedDefaultNotice, resolveBind, resolveDomain } from '../env.mjs';
+import { ROOT, ROUTER_ADDRESS, chooseBind, dc, ensureSecrets, projectHasData, snowglobeRequest, envGet, guardProject, makePrivate, oldDataNotice, ownNginxUp, paths, renamedDefaultNotice, resolveBind, resolveDomain, routerRuns } from '../env.mjs';
 import { prebuilt } from '../prebuilt.mjs';
+import { claimDomain, readRoutes, routerDir, syncRouter } from '../router.mjs';
 import { byName, claimState, pointedAt, session } from '../state.mjs';
-import { accountPrefixes, endingClash, mergeRoutes } from '../up.mjs';
+import { accountPrefixes, endingClash, mergeRoutes, startedAfterRelay } from '../up.mjs';
 import { account } from './account.mjs';
 import { lexicons } from './lexicons.mjs';
 import { checkedGlobe } from './check.mjs';
@@ -125,7 +129,23 @@ export async function up({ file, root = ROOT, env = process.env, log = () => {}
   if (took) log(took);
   // Its own loopback address for every published port, chosen once, so a second snowglobe starts beside this one.
   const bind = await chooseBind({ root, state, project, env });
-  if (bind !== '127.0.0.1') log(`${found.name} publishes its ports on ${bind}`);
+  if (bind !== ROUTER_ADDRESS) log(`${found.name} publishes its ports on ${bind}`);
+  // Routed by name unless it holds the router's own address (SG_BIND, or kept while it runs).
+  const routed = routerRuns({ root, env }) && bind !== ROUTER_ADDRESS;
+  if (routerRuns({ root, env }) && !routed)
+    log(`${found.name} is on ${ROUTER_ADDRESS}, the name router's address, so the router is not started and no other snowglobe is reached by name while it runs. To move it: snowglobe down, then up${env.SG_BIND ? ' without SG_BIND' : ''}`);
+  const rdir = routerDir(env);
+  const taken = (other) =>
+    new Error(
+      `${other.globe} (compose project ${other.project}) is up at ${globe.domain} already, and the name router sends a name to one snowglobe only: take it down first, or leave the domain line out of ${path} so ${found.name} gets its own`,
+    );
+  // Asked before anything starts; asked again under the router's lock when the route is written,
+  // for another up at the same domain in between.
+  const isUp = (other) => ownNginxUp(other, env);
+  if (routed) {
+    const other = readRoutes(rdir).find((r) => r.project !== project && r.domain === globe.domain && isUp(r.project));
+    if (other) throw taken(other);
+  }
   // Checked before the render changes, so a refused file leaves the running globe's render.
   const kept = readApps(p);
   const badEnding = appEnding(kept);
@@ -171,10 +191,12 @@ export async function up({ file, root = ROOT, env = process.env, log = () => {}
       throw new Error(`docker compose ${args.join(' ')} failed (exit ${res.status}). If a container crash-loops after you updated snowglobe, an image built earlier may be stale (the slingshot image is tagged by its commit, so a changed stack/slingshot/ folder alone does not rebuild it): run snowglobe down (without -v, which keeps your data), remove the image with docker rmi, then run up again`);
     return res;
   };
-  // The nginx template as the running nginx last started with it (stamped after a restart here).
-  const templateFile = join(root, 'stack/https/nginx.conf.template');
+  // The files nginx mounts one by one from the checkout, as the running nginx last started with
+  // them (stamped after a restart here): its template, and the network page and its config. A
+  // mounted file keeps the content it had when nginx started, so a new one needs a restart.
+  const templateFiles = ['stack/https/nginx.conf.template', 'stack/page/snowglobe.conf', 'stack/page/index.html'].map((f) => join(root, f));
   const templateStamp = join(p.https, 'nginx-template.sha256');
-  const templateHash = createHash('sha256').update(existsSync(templateFile) ? readFileSync(templateFile) : '').digest('hex');
+  const templateHash = templateFiles.reduce((h, f) => h.update(existsSync(f) ? readFileSync(f) : '').update('\0'), createHash('sha256')).digest('hex');
   const templateChanged = !existsSync(templateStamp) || readFileSync(templateStamp, 'utf8').trim() !== templateHash;
   const put = (file, text) => {
     writeFileSync(`${file}.tmp`, `${text}\n`);
@@ -203,10 +225,6 @@ export async function up({ file, root = ROOT, env = process.env, log = () => {}
     waitServices();
   }
 
-  // What runs before this run: the relay, and every container, to notice a PDS this run makes.
-  const relayBefore = ids(['-q', 'relay']);
-  const before = new Set(ids(['-aq']));
-
   // Every image the file builds is built before anything starts, so `up` never builds while
   // containers are being made (on a runner with no images, the relay and the other built services
   // were made, then made again by the next `up`, and Jetstream lost the relay between the two).
@@ -234,8 +252,16 @@ export async function up({ file, root = ROOT, env = process.env, log = () => {}
   composeEnv.SG_LEXICON_AUTHORITY_DID = envGet('LEX_AUTHORITY_DID', p.accounts);
   log(`Pass 1: up (project ${project})`);
   await upStack();
-  // A running nginx keeps the certificate files it started with, and the template it was started
-  // with (the image fills it in at start); new ones need a restart, whether or not the leaf was
+  if (routed) {
+    const change = () => {
+      const other = claimDomain(rdir, { project, domain, bind, globe: found.name }, isUp, log);
+      if (other) throw taken(other);
+    };
+    await syncRouter({ dir: rdir, env, log, change });
+    log(`The name router sends ${domain} and every name under it to ${bind}`);
+  }
+  // A running nginx keeps the certificate files it started with, and the template and page files
+  // it was started with (the image fills the template in at start); new ones need a restart, whether or not the leaf was
   // reissued. The globe's servers may have changed with the render, so a running nginx reloads them.
   if (newCerts || templateChanged) {
     compose(['restart', 'nginx'], { stdio: 'ignore' });
@@ -250,34 +276,32 @@ export async function up({ file, root = ROOT, env = process.env, log = () => {}
   if (did !== composeEnv.SG_LEXICON_AUTHORITY_DID) {
     composeEnv.SG_LEXICON_AUTHORITY_DID = did;
     log(`Pass 2: up with the lexicon authority ${did}`);
-    // Pass 2 recreates every PDS. Jetstream with no relay reads the first PDS itself and exits
-    // while it is gone; on a slow machine (a CI runner) it was still restarting when compose
-    // checked it, and up failed with "jetstream is unhealthy". Stopped first, it is started
-    // again only once the PDS is healthy.
-    const running = facts('SG_SERVICES');
-    if (running.includes('jetstream') && !running.includes('relay')) compose(['stop', 'jetstream'], { stdio: 'ignore' });
+    // Pass 2 recreates every PDS, so the relay restarts after it (below).
     await upStack();
   }
 
-  // A relay that was running when a PDS went away redials it with a growing backoff; a PDS
-  // added back under that name was not crawled again until the relay restarted (2026-10-20: no
-  // dial in the nine minutes after it came back). So when this run made a PDS container beside a
-  // relay that was already running, the relay restarts, and the services wait for it again.
-  if (relayBefore.length) {
-    const fresh = facts('SG_PDS').find((x) => ids(['-q', `pds-${x}`]).some((id) => !before.has(id)));
-    if (fresh) {
-      log(`Restarting the relay: pds-${fresh} is new beside it`);
+  // A relay that was running when a PDS, or nginx in front of it, went away redials it, and after
+  // ten quick failures it waits 30 s between dials: what the PDS writes meanwhile reaches it half a
+  // minute late, or not for minutes. A PDS added back was not dialed in the nine minutes after it
+  // came back (2026-10-20), and a record written right after a first up in CI had not reached Tap
+  // 20 s later (2026-10-30). Pass 2 recreates every PDS, new certificates restart nginx, and a rerun
+  // can make a PDS. So when one of them started after the relay did, the relay restarts, and the
+  // services wait for it again.
+  if (ids(['-q', 'relay']).length) {
+    const started = (service) => {
+      const containers = ids(['-q', service]);
+      if (!containers.length) return [];
+      return (spawnSync('docker', ['inspect', '-f', '{{.State.StartedAt}}', ...containers], { encoding: 'utf8', env }).stdout ?? '').split('\n').filter(Boolean);
+    };
+    const dialed = Object.fromEntries([...facts('SG_PDS').map((x) => `pds-${x}`), 'nginx'].map((s) => [s, started(s)]));
+    const later = startedAfterRelay(started('relay'), dialed);
+    if (later) {
+      log(`Restarting the relay: ${later} started after it`);
       compose(['restart', 'relay'], { stdio: 'ignore' });
       waitServices();
     }
   }
 
-  // init's accounts are on the seed PDS; run maps their handles.
-  for (const prefix of ['ALICE', 'BOB']) {
-    const handle = envGet(`${prefix}_HANDLE`, p.accounts);
-    if (handle) addName(handle, { root, state });
-  }
-
   // What the file seeds. A rerun finds each account by its kept login.
   for (const a of seedAccounts) await account({ ...a, file: p.accounts, root, state, env, log });
   if (globe.lexicons.publish) await lexicons({ dir: resolve(dirname(path), globe.lexicons.publish), root, state, env, log });