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

package/.env.example

@@ -0,0 +1,28 @@
+# Database credentials — single source of truth for PLC and test postgres.
+# Consumer overrides these to use their own postgres instance.
+SG_DB_USER=postgres
+# SG_DB_PASSWORD=   (unset: snowglobe up makes a random one, in secrets.env in the snowglobe's state folder)
+SG_DB_HOST=postgres
+SG_DB_PORT=5432
+SG_DB_NAME=plc
+
+# Required: SMTP server for PDS email verification
+# Consumer provides this — must be reachable from Docker network
+SG_SMTP_URL=smtp://maildev:1025
+
+# Optional: Override defaults
+# The snowglobe's domain: its PDSes are <name>.<domain>. A domain under .test, .local or
+# .localhost fails sign-in (a PDS refuses an OAuth client there); this default is ours and
+# resolves to this machine.
+# SG_DOMAIN=local.snowglobe.at
+# SG_PDS_HOSTNAME=local.snowglobe.at
+# SG_PDS_ADMIN_PASSWORD=   # unset: up makes a random one and keeps it in the snowglobe's admin.env
+# SG_HANDLE_DOMAIN=.local.snowglobe.at
+# SG_SEED_ACCOUNTS=true
+
+# Host ports — override to avoid conflicts with other local services
+# SG_PDS_PORT=3000
+# SG_PLC_PORT=2582
+# SG_JETSTREAM_PORT=6008
+# SG_JETSTREAM_METRICS_PORT=6009
+# SG_TAP_PORT=2480

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenMeet Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,149 @@
-# Temporary Holding Version
+# Snowglobe
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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
+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.
+
+**Why?** Some things worth trying on atproto can hurt real users if they go wrong: a change to a lexicon,
+a new OAuth flow, an app that writes records in a new way. A snowglobe is a network of your own, where a
+mistake touches nobody. We use it to build against the spaces alpha PDS, a group host and atmo.rsvp.
+
+**How?** Run one on your machine from this repo, or open the one we host,
+[lighthouse.snowglobe.at](https://lighthouse.snowglobe.at). [snowglobe.at](https://snowglobe.at)
+says more about the project.
+
+## What runs in a snowglobe
+
+One file, `snowglobe.yml`, says what a snowglobe runs. [`snowglobe.default.yml`](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;
+- 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;
+- the network's own page, with its services, accounts and live activity.
+
+The file also holds commented examples for adding more, up to a full setup:
+- more PDSes. With more than one, a relay turns on by itself: it merges every PDS's writes into one
+  stream, which Jetstream then follows;
+- the permissioned-spaces alpha, a PDS build with shared spaces;
+- a lexicon authority, the one account every PDS reads record type definitions (lexicons) from;
+- Tap, which follows the stream and fetches whole repos for an app that keeps its own copy of the data;
+- a group host, a server that runs groups as accounts of their own, each with a handle under the host's name;
+- your own app.
+
+[`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.
+[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.
+
+**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.
+
+**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
+     [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).
+
+**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
+handle lookup and an OAuth sign-in resolve to, so an app has to be told it is on a test network to
+use a port instead. A snowglobe can still be small: a file with one PDS, the PLC and Jetstream
+checks and renders ([The file and the commands](docs/snowglobe.md#the-file-and-the-commands)). It
+keeps the https names, and they are what make an app run unchanged.
+
+## Quick start
+
+```bash
+npm install -g @openmeet/snowglobe       # puts the snowglobe command on your PATH
+snowglobe up --default                   # the first run pulls and builds images, which takes a while
+```
+
+To change what it runs, copy the default file into your folder, give it a name of its own on the
+`globe:` line (`snowglobe` is the default file's, and a snowglobe belongs to the file that first
+brought it up), edit it, and run `snowglobe up`:
+`cp "$(npm root -g)/@openmeet/snowglobe/snowglobe.default.yml" snowglobe.yml`.
+To keep the command with one project instead, run `npm install --save-dev @openmeet/snowglobe`, then
+`npx snowglobe up --default` for the default, or `npx snowglobe up` once the folder has a
+`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:
+
+```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'
+```
+
+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,
+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.
+
+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,
+once your browser can reach the snowglobe as above.
+
+Stop the snowglobe with `snowglobe down`. Add `-v` to delete its data too, every account
+included. Everything a snowglobe makes is kept in your own account, in
+`~/.local/share/snowglobe` (or under `XDG_DATA_HOME`), and nothing in the checkout
+([Which snowglobe, and where it lives](docs/snowglobe.md#which-snowglobe-and-where-it-lives)).
+
+To run your own app inside of a snowglobe, see [Your app in a snowglobe](docs/your-app.md).
+
+## Platforms
+
+Snowglobe runs on Linux, and on Windows under WSL 2. Both are tested. macOS is not supported, but we'd love to.
+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.
+
+## Documentation
+
+- [The snowglobe](docs/snowglobe.md): what a `snowglobe.yml` holds, the commands, the snowglobe's names, up and
+  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.
+- [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: 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).
+- [Changelog](CHANGELOG.md): what changed in each version, and how to upgrade.
+
+## License
+
+MIT

package/bin/snowglobe.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// snowglobe: run the globe a snowglobe.yml describes.
+//
+//   check     checks a snowglobe.yml
+//   ls        lists the snowglobes on this machine
+//   render    writes the https globe it describes into its state folder
+//   certs     makes your CA, once, and the leaf nginx serves
+//   trust     puts your CA in the system and browser trust stores (--remove takes it out)
+//   env       prints the settings an app is handed, for eval "$(snowglobe env)"
+//   account   makes an account on a PDS in the running globe
+//   invite    mints an invite code on one of its PDSes
+//   lexicons  publishes lexicons into its lexicon authority
+//   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
+//
+// 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/
+// snowglobe/<globe>/ (XDG_DATA_HOME, %LOCALAPPDATA% on Windows), and its compose project is the
+// file's `globe:` unless SG_PROJECT is set (lib/state.mjs).
+//
+// Each command is a file in lib/commands/, which says what it does and why; the usage below comes
+// from them. Exit 2 for a usage mistake, 1 when the globe refuses, 3 when up or down refuse the
+// shared devnet; certs keeps 1 for --check's answer, so it fails with 2, and run exits with its
+// command's code.
+
+import { readArgs } from '../lib/args.mjs';
+import { Refused, UsageError, adoptOldNames } from '../lib/env.mjs';
+
+// Loaded when it runs, so check and render do without the certificate library.
+const COMMANDS = {
+  check: () => import('../lib/commands/check.mjs'),
+  ls: () => import('../lib/commands/ls.mjs'),
+  render: () => import('../lib/commands/render.mjs'),
+  certs: () => import('../lib/commands/certs.mjs'),
+  trust: () => import('../lib/commands/trust.mjs'),
+  env: () => import('../lib/commands/env.mjs'),
+  account: () => import('../lib/commands/account.mjs'),
+  invite: () => import('../lib/commands/invite.mjs'),
+  lexicons: () => import('../lib/commands/lexicons.mjs'),
+  app: () => import('../lib/commands/app.mjs'),
+  up: () => import('../lib/commands/up.mjs'),
+  down: () => import('../lib/commands/down.mjs'),
+  run: () => import('../lib/commands/run.mjs'),
+};
+
+const [name, ...args] = process.argv.slice(2);
+const helped = ['--help', '-h', 'help'].includes(name ?? '');
+const mod = !helped && Object.hasOwn(COMMANDS, name ?? '') ? await COMMANDS[name]() : null;
+// A command that takes any words reads them itself.
+const parsed = mod && (mod.command.parse ? mod.command.parse(args) : readArgs(mod.command, args));
+if (!parsed) {
+  const lines = await Promise.all(Object.values(COMMANDS).map(async (load) => `snowglobe ${(await load()).command.usage}`));
+  const usage = `Usage: ${lines.join('\n       ')}`;
+  // --help asked for it, so it is the answer; anything else is a mistake.
+  if (helped) {
+    console.log(usage);
+    process.exit(0);
+  }
+  console.error(usage);
+  process.exit(2);
+}
+// DEVNET_* and SNOWGLOBE_* settings, the old names, become SG_* before any command reads them.
+adoptOldNames();
+try {
+  process.exit((await mod.run(parsed)) ?? 0);
+} catch (e) {
+  console.error(`snowglobe ${mod.command.name}: ${e.message}`);
+  process.exit(e instanceof Refused ? e.exitCode : e instanceof UsageError ? 2 : 1);
+}

package/lib/apps.mjs

@@ -0,0 +1,97 @@
+// Apps on this machine, routed through the https globe's nginx: https://<name>.app.<domain> goes
+// to a port here, for an app's pages, its OAuth client metadata and its keys, at an https origin
+// the globe's PDSes and snowglobe run's processes both reach. An app that hands out handles of its own,
+// as a PDS does, also claims an ending: every name under <ending>.<domain> goes to it, so a handle
+// there resolves at the app.
+//
+// The routes are kept in https/apps in the snowglobe's state folder, "<name> <port> [<ending>]" per
+// line. From them and the
+// rendered globe's page facts (globe/page.json), nginx's apps.conf and apps.map and the
+// network page's snowglobe.json are rendered into https/nginx/ there (mounted at /etc/nginx/snowglobe/;
+// see stack/https/nginx.conf.template). The renderers are pure; renderRoutes writes what they render, for
+// bin/snowglobe.mjs app (lib/commands/app.mjs), which keeps the routes.
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ROOT, globeFacts, paths } from './env.mjs';
+
+const HEADER = '# Written by bin/snowglobe.mjs app from https/apps; rerun it instead of editing.\n';
+
+/**
+ * The first saved route whose ending is `app`, or null. app.<domain> is where the apps are, so an
+ * ending of that name (saved before app was reserved) would capture every app route.
+ */
+export const appEnding = (apps) => apps.find((a) => a.ending === 'app') ?? null;
+
+export const appEndingMessage = (file, a) =>
+  `${file}: the line "${formatApps([a]).trim()}" claims the ending app, which is where the apps are (${a.name}.app.<domain>); ` +
+  `remove the route (bin/snowglobe.mjs app --remove ${a.name}) or give it another ending`;
+
+/** The routes in an apps file's text: [{ name, port, ending }], ending null when none. */
+export function parseApps(text) {
+  return text
+    .split('\n')
+    .map((l) => l.split(/\s+/).filter(Boolean))
+    .filter((f) => f.length >= 2)
+    .map(([name, port, ending]) => ({ name, port: Number(port), ending: ending ?? null }));
+}
+
+export const formatApps = (apps) => apps.map((a) => `${a.name} ${a.port}${a.ending ? ` ${a.ending}` : ''}\n`).join('');
+
+const upstream = (a) => `snowglobe_app_${a.name.replace(/-/g, '_')}`;
+
+/**
+ * nginx's part for the routes: apps.conf, one upstream per app at host.docker.internal:<port> and,
+ * for an app that claimed an ending, a server for *.<ending>.<domain>; apps.map, one line per name.
+ */
+export function renderApps(apps, domain) {
+  const conf =
+    HEADER +
+    apps.map((a) => `upstream ${upstream(a)} { server host.docker.internal:${a.port}; }\n`).join('') +
+    // Host is passed through (the http block sets it), so the app answers
+    // /.well-known/atproto-did for each handle. nginx takes the longer of two matching
+    // wildcards, so these win over a PDS's *.<domain>.
+    apps
+      .filter((a) => a.ending)
+      .map(
+        (a) =>
+          `\n# Handles under ${a.ending}.${domain} go to ${a.name}.\nserver {\n    listen 443 ssl;\n    server_name *.${a.ending}.${domain};\n` +
+          `    location / {\n        proxy_pass http://${upstream(a)};\n    }\n}\n`,
+      )
+      .join('');
+  const map = HEADER + apps.map((a) => `${a.name}.app.${domain} ${upstream(a)};\n`).join('');
+  return { 'apps.conf': conf, 'apps.map': map };
+}
+
+/** The network page's snowglobe.json: the rendered globe's page facts, with a link to each routed app. */
+export function renderPage(page, apps, domain = page.domain) {
+  const links = [...(page.apps ?? []), ...apps.map((a) => ({ name: a.name, url: `https://${a.name}.app.${domain}` }))];
+  return JSON.stringify({ ...page, apps: links }, null, 2) + '\n';
+}
+
+// Written aside and renamed, so nginx never reads half a file.
+function put(file, text) {
+  writeFileSync(`${file}.tmp`, text);
+  renameSync(`${file}.tmp`, file);
+}
+
+/** The routes kept in https/apps (`p` from paths()), [] when there are none. */
+export const readApps = (p) => (existsSync(p.apps) ? parseApps(readFileSync(p.apps, 'utf8')) : []);
+
+/** Keep `apps` as the routes in https/apps. */
+export const writeApps = (p, apps) => put(p.apps, formatApps(apps));
+
+/** Render https/nginx/ from the routes and the rendered globe. */
+export function renderRoutes({ root = ROOT, state, env = process.env } = {}) {
+  const p = paths(root, state);
+  const pageJson = join(p.globe, 'page.json');
+  if (!existsSync(pageJson)) throw new Error(`No ${pageJson}: run bin/snowglobe.mjs up, which renders it`);
+  const { domain } = globeFacts({ root, state, env });
+  const apps = readApps(p);
+  const bad = appEnding(apps);
+  if (bad) throw new Error(appEndingMessage(p.apps, bad));
+  const out = join(p.https, 'nginx');
+  mkdirSync(out, { recursive: true });
+  for (const [name, text] of Object.entries(renderApps(apps, domain))) put(join(out, name), text);
+  put(join(out, 'snowglobe.json'), renderPage(JSON.parse(readFileSync(pageJson, 'utf8')), apps));
+}

package/lib/args.mjs

@@ -0,0 +1,29 @@
+// A snowglobe command's words, read with util.parseArgs the way the CLI has always read them: an
+// option's value is the next word even when it starts with a dash (--out -x), and every other
+// word that starts with one is refused, as are --name=value and a bare --. parseArgs in strict
+// mode differs on each of those, so it reads loosely here and its tokens are checked instead.
+
+import { parseArgs } from 'node:util';
+
+/**
+ * Read `args` for `command`, a command's descriptor: its options (as parseArgs takes them), how
+ * many positionals it takes ([min, max]), and `accepts`, any rule on the shape beyond those.
+ * Returns { values, positionals, tokens }, or null for words the command does not take.
+ */
+export function readArgs(command, args) {
+  const options = command.options ?? {};
+  const { values, positionals, tokens } = parseArgs({ args, options, strict: false, allowPositionals: true, tokens: true });
+  for (const t of tokens) {
+    if (t.kind === 'option-terminator') return null;
+    if (t.kind === 'positional' && t.value.startsWith('-')) return null;
+    if (t.kind === 'option') {
+      if (!Object.hasOwn(options, t.name) || t.inlineValue) return null;
+      // A string option as the last word, with no value after it.
+      if (options[t.name].type === 'string' && t.value === undefined) return null;
+    }
+  }
+  const [min, max] = command.positionals ?? [0, 0];
+  if (positionals.length < min || positionals.length > max) return null;
+  const parsed = { values, positionals, tokens };
+  return !command.accepts || command.accepts(parsed) ? parsed : null;
+}

package/lib/certs.mjs

@@ -0,0 +1,211 @@
+// The https globe's certificates: one local CA per user, made once (<state root>/ca), and one
+// leaf per snowglobe, which nginx serves for every name: each PDS and its handles, the globe's services, plc.directory, every app at
+// <name>.app.<domain> (one wildcard), and the handles under each ending an app claimed with
+// bin/snowglobe.mjs app. Made here with @peculiar/x509, so no openssl is needed.
+//
+// Files: ca.crt and ca.key in the CA's folder (`caDir`), leaf.crt and leaf.key in the snowglobe's
+// (`dir`). An existing CA is kept, so a browser or OS that trusts ca.crt keeps trusting every
+// snowglobe; only the leaf is reissued, and only when it lacks a name or another CA signed it.
+// 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
+// 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.
+//
+// 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.
+
+import 'reflect-metadata';
+import { AsnConvert } from '@peculiar/asn1-schema';
+import { GeneralName, GeneralSubtree, GeneralSubtrees, NameConstraints, id_ce_nameConstraints } from '@peculiar/asn1-x509';
+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';
+
+x509.cryptoProvider.set(webcrypto);
+
+const EC = { name: 'ECDSA', namedCurve: 'P-256' };
+const SIGN = { name: 'ECDSA', hash: 'SHA-256' };
+const DAY = 24 * 60 * 60 * 1000;
+// 397 days: under the 398-day ceiling browsers apply to server certificates.
+const LEAF_DAYS = 397;
+const CA_DAYS = 730;
+// Names every globe's CA vouches for besides its domain: the stand-in for the real PLC directory.
+const FIXED = ['plc.directory'];
+
+// Every name the leaf must carry: the rendered globe's (its page, each PDS and its handles, its
+// services, plc.directory and *.app.<domain>), *.<ending>.<domain> for each ending an app
+// claimed, and `extra` (HTTPS_EXTRA_NAMES, space-separated).
+export function leafNames(p, domain, extra = '') {
+  if (!existsSync(p.leafNames)) throw new Error(`No ${p.leafNames}: run snowglobe up, which renders it`);
+  const words = (text) => text.split(/\s+/).filter(Boolean);
+  const endings = existsSync(p.apps)
+    ? readFileSync(p.apps, 'utf8').split('\n').map(words).filter((f) => f.length >= 3).map((f) => `*.${f[2]}.${domain}`)
+    : [];
+  return [...new Set([...words(readFileSync(p.leafNames, 'utf8')), ...endings, ...words(extra)])];
+}
+
+// The names a certificate carries, from its subjectAltName.
+function sans(pem) {
+  const alt = new NodeCertificate(pem).subjectAltName ?? '';
+  return alt.split(', ').filter((s) => s.startsWith('DNS:')).map((s) => s.slice(4));
+}
+
+// True when there is no leaf, or it lacks one of `names`, or the CA in `caDir` did not sign it
+// (a leaf left from another CA is not trusted by whoever trusts this one).
+export function leafLacks(dir, names, caDir = dir) {
+  const crt = join(dir, 'leaf.crt');
+  if (!existsSync(crt) || !existsSync(join(dir, 'leaf.key'))) return true;
+  const leaf = readFileSync(crt, 'utf8');
+  const have = new Set(sans(leaf));
+  if (names.some((n) => !have.has(n))) return true;
+  const caCrt = join(caDir, 'ca.crt');
+  return existsSync(caCrt) && !new NodeCertificate(leaf).verify(new NodeCertificate(readFileSync(caCrt, 'utf8')).publicKey);
+}
+
+// The DNS names a CA may vouch for (its permitted subtrees), or null if it is unconstrained.
+function permitted(ca) {
+  const ext = ca.extensions.find((e) => e.type === id_ce_nameConstraints);
+  if (!ext) return null;
+  const nc = AsnConvert.parse(ext.value, NameConstraints);
+  return (nc.permittedSubtrees ?? []).map((s) => s.base.dNSName).filter(Boolean);
+}
+
+const within = (name, bases) => bases.some((b) => name === b || name.endsWith(`.${b}`));
+
+// A positive serial number of 16 random bytes.
+function serial() {
+  const b = randomBytes(16);
+  b[0] &= 0x7f;
+  b[0] |= 0x01;
+  return b.toString('hex');
+}
+
+const pem = (label, der) =>
+  `-----BEGIN ${label}-----\n${Buffer.from(der).toString('base64').match(/.{1,64}/g).join('\n')}\n-----END ${label}-----\n`;
+
+async function importSigningKey(keyPem) {
+  const key = createPrivateKey(keyPem);
+  const curve = key.asymmetricKeyDetails?.namedCurve;
+  if (key.asymmetricKeyType !== 'ec' || curve !== 'prime256v1') throw new Error('ca.key is not a P-256 key');
+  return webcrypto.subtle.importKey('pkcs8', key.export({ format: 'der', type: 'pkcs8' }), EC, false, ['sign']);
+}
+
+async function makeCa(domain, now) {
+  const keys = await webcrypto.subtle.generateKey(EC, true, ['sign', 'verify']);
+  // Each CA has a name of its own. Two CAs with one name confuse a browser that trusts one of
+  // them: Firefox checks the other's leaf against the trusted key and calls it a bad signature,
+  // with no way to click through, where an unknown CA could be.
+  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 }))),
+    excludedSubtrees: new GeneralSubtrees([subtree({ iPAddress: '0.0.0.0/0' }), subtree({ iPAddress: '::/0' })]),
+  });
+  const cert = await x509.X509CertificateGenerator.createSelfSigned({
+    serialNumber: serial(),
+    name: `O=snowglobe, CN=${name}`,
+    notBefore: now,
+    notAfter: new Date(now.getTime() + CA_DAYS * DAY),
+    signingAlgorithm: SIGN,
+    keys,
+    extensions: [
+      new x509.BasicConstraintsExtension(true, 0, true),
+      new x509.KeyUsagesExtension(x509.KeyUsageFlags.keyCertSign | x509.KeyUsageFlags.cRLSign, true),
+      new x509.ExtendedKeyUsageExtension([x509.ExtendedKeyUsage.serverAuth]),
+      new x509.Extension(id_ce_nameConstraints, true, AsnConvert.serialize(constraints)),
+      await x509.SubjectKeyIdentifierExtension.create(keys.publicKey),
+    ],
+  });
+  const key = pem('PRIVATE KEY', await webcrypto.subtle.exportKey('pkcs8', keys.privateKey));
+  return { cert, key };
+}
+
+// Make the CA (in `caDir`, `dir` by default) if there is none, and issue the leaf (in `dir`) if it
+// lacks a name of `names` (or `force`). Returns { newCa, newLeaf }. Progress goes to `log`; no key
+// is ever logged.
+export async function ensureCerts({ dir, caDir = dir, domain, names, force = false, now = new Date(), log = () => {} }) {
+  mkdirSync(dir, { recursive: true });
+  mkdirSync(caDir, { recursive: true });
+  const f = (n) => join(dir, n);
+  const c = (n) => join(caDir, n);
+  let newCa = false;
+  let ca;
+  let caKey;
+  if (existsSync(c('ca.crt')) && existsSync(c('ca.key'))) {
+    ca = new x509.X509Certificate(readFileSync(c('ca.crt'), 'utf8'));
+    caKey = await importSigningKey(readFileSync(c('ca.key'), 'utf8'));
+    log(`Keeping the existing CA: ${ca.subject}`);
+  } else if (existsSync(c('ca.crt')) || existsSync(c('ca.key'))) {
+    throw new Error(
+      `Only one of ${c('ca.crt')} and ca.key exists. Restore the other, or delete both to make a new CA (which must then be trusted again).`,
+    );
+  } else {
+    const made = await makeCa(domain, now);
+    writeFileSync(c('ca.key'), made.key, { mode: 0o600, flag: 'wx' });
+    writeFileSync(c('ca.crt'), made.cert.toString('pem') + '\n', { mode: 0o644 });
+    ca = made.cert;
+    caKey = await importSigningKey(made.key);
+    newCa = true;
+    log(`Made a new CA: ${ca.subject}`);
+  }
+
+  if (!force && !leafLacks(dir, names, caDir)) {
+    log('The leaf already carries every name; kept');
+    return { newCa, newLeaf: false };
+  }
+
+  // Refused before anything is written, so the leaf nginx serves stays as it is.
+  const bases = permitted(ca);
+  const outside = bases ? names.filter((n) => !within(n.replace(/^\*\./, ''), bases)) : [];
+  if (outside.length)
+    throw new Error(
+      `The CA cannot vouch for ${outside.join(' ')} (it vouches for ${bases.join(', ')}), so the leaf is unchanged. ` +
+        `The domain ${domain} is not one this CA was made for. To make a new CA that is: delete the folder ${caDir} and run up again ` +
+        '(browsers and systems that trusted the old CA must then trust the new one).',
+    );
+
+  const keys = await webcrypto.subtle.generateKey(EC, true, ['sign', 'verify']);
+  const leaf = await x509.X509CertificateGenerator.create({
+    serialNumber: serial(),
+    subject: `O=snowglobe, CN=${domain}`,
+    // The CA's subject as its own bytes. Rebuilt from text, its strings come out PrintableString
+    // where the CA has UTF8String; openssl and Node match names loosely and accept that, but Go
+    // (the relay, TAP) matches the bytes, and calls the CA unknown.
+    issuer: ca.subjectName,
+    notBefore: now,
+    notAfter: new Date(now.getTime() + LEAF_DAYS * DAY),
+    signingAlgorithm: SIGN,
+    publicKey: keys.publicKey,
+    signingKey: caKey,
+    extensions: [
+      new x509.BasicConstraintsExtension(false, undefined, true),
+      new x509.KeyUsagesExtension(x509.KeyUsageFlags.digitalSignature, true),
+      new x509.ExtendedKeyUsageExtension([x509.ExtendedKeyUsage.serverAuth]),
+      await x509.SubjectKeyIdentifierExtension.create(keys.publicKey),
+      await x509.AuthorityKeyIdentifierExtension.create(ca.publicKey),
+      new x509.SubjectAlternativeNameExtension(names.map((value) => ({ type: 'dns', value }))),
+    ],
+  });
+  const leafPem = leaf.toString('pem') + '\n';
+  if (!new NodeCertificate(leafPem).verify(new NodeCertificate(ca.toString('pem')).publicKey))
+    throw new Error('The new leaf does not check out against the CA; the leaf is unchanged');
+
+  // Written in place, not renamed: nginx's single-file mounts follow the file, not the name.
+  writeFileSync(f('leaf.key'), pem('PRIVATE KEY', await webcrypto.subtle.exportKey('pkcs8', keys.privateKey)), { mode: 0o600 });
+  writeFileSync(f('leaf.crt'), leafPem, { mode: 0o644 });
+  // nginx reads the leaf key as root inside its container.
+  chmodSync(f('leaf.key'), 0o600);
+  chmodSync(f('leaf.crt'), 0o644);
+  chmodSync(c('ca.key'), 0o600);
+  log(`Leaf names: ${names.join(' ')}`);
+  log(`Leaf valid until ${leaf.notAfter.toISOString()}`);
+  return { newCa, newLeaf: true };
+}