@makerclay/core 1.0.0

package/src/tenants/index.js

@@ -0,0 +1,355 @@
+import path from 'upath';
+import { can } from '../auth/can.js';
+import { HostError } from '../spec/codes.js';
+import { hashPassword, verifyPassword, generateRecoveryCode, normalizeRecoveryCode } from '../auth/passwords.js';
+import { readFileText, readdirIfExists } from '../util/fsx.js';
+
+// Signups: someone who is not the owner gets their own copy of one of the
+// owner's documents, in their own realm, under their own login.
+//
+// Two things make this safe enough to offer at all, and neither is optional:
+//
+//   1. Invariant 1. Every tenant document is served under an opaque origin, so
+//      a tenant's HTML cannot read the owner's cookies, cannot script the
+//      dashboard, and cannot reach another tenant's document. §16.1 spells out
+//      why nothing weaker works on a single origin.
+//   2. The fork is a COPY, not a link. Alice's instance is her document from the
+//      first byte: the owner can read it and moderate it, and cannot edit it.
+//
+// There is no email on this server, so the only way back into a lost account is
+// a recovery code shown once at signup, or the owner issuing a new one.
+
+const USERNAME = /^[a-z0-9_-]{2,32}$/;
+
+// Not a routing need: `~` keeps tenant paths out of the owner's namespace on its
+// own. These are the names that would let someone look like the machine.
+const RESERVED_USERNAMES = new Set(['_', 'admin', 'api', 'makerclay', 'root', 'owner', 'support']);
+
+// §16.5 names both `features.tenants` and `tenants.enabled`. Two switches for
+// one thing is a bug waiting to happen (and `serve.js` already gates realm
+// resolution on the first), so `features.tenants` is THE switch and this object
+// holds only the knobs.
+export const TENANT_DEFAULTS = {
+  approve: true,
+  maxTenants: 100,
+  maxDocsPerTenant: 25,
+  maxBytesPerTenant: 100e6,
+  signupRateLimit: '10/hour',
+};
+
+export function usernameError(raw) {
+  const name = String(raw ?? '').trim().toLowerCase();
+  if (!name) return 'Pick a username.';
+  if (!USERNAME.test(name)) {
+    return 'Usernames are 2 to 32 characters, using a-z, 0-9, hyphen and underscore.';
+  }
+  if (RESERVED_USERNAMES.has(name)) return 'That username is reserved.';
+  return null;
+}
+
+export function createTenants({
+  store, paths, ops, config, clock, events,
+  sessions = () => null, saveTokens = null, logger = console,
+}) {
+  const limits = { ...TENANT_DEFAULTS, ...(config.tenants || {}) };
+  const enabled = config.features?.tenants === true;
+
+  function assert(condition, code, message) {
+    if (!condition) throw new HostError(code, message);
+  }
+
+  function requireEnabled() {
+    assert(enabled && store, 'not-found', 'This host does not take signups.');
+  }
+
+  function principal(username) {
+    return `tenant:${username}`;
+  }
+
+  // Sessions and save tokens are the same authority in two shapes, so they are
+  // always revoked together. A suspension that ends only the session leaves the
+  // tenant writing through their save token for its full TTL.
+  function endAccess(username) {
+    sessions()?.destroyAllFor(principal(username));
+    saveTokens?.revokeForPrincipal(principal(username));
+  }
+
+  // Provisioning and removal are authorized by the OWNER and performed in the
+  // TENANT's realm, which is the only realm the capability matrix lets that work
+  // in: `can()` gives the owner no write on someone else's tree, deliberately
+  // (§16.5, there is no owner-edits-instance lane). Every call site here checks
+  // `admin` first and then acts as the person whose tree it is.
+  function asTenant(username) {
+    return { kind: 'tenant', username, grants: {} };
+  }
+
+  function shape(row) {
+    if (!row) return null;
+    return {
+      username: row.username,
+      createdAt: row.createdAt,
+      approvedAt: row.approvedAt ?? null,
+      disabledAt: row.disabledAt ?? null,
+      sourceId: row.sourceId ?? null,
+      bytesUsed: row.bytesUsed ?? 0,
+      state: row.disabledAt ? 'suspended' : (row.approvedAt ? 'active' : 'waiting'),
+    };
+  }
+
+  function get(username) {
+    if (!store) return null;
+    return shape(store.getTenant(String(username || '').toLowerCase()));
+  }
+
+  function list({ actor, ctx = {} }) {
+    assert(can(actor, 'admin', null, ctx), 'not-found', 'Not found');
+    if (!store) return [];
+    return store.listTenants().map((row) => ({ ...shape(row), usage: usage(row.username) }));
+  }
+
+  // ---- quotas ------------------------------------------------------------
+
+  function usage(username) {
+    if (!store) return { docs: 0, bytes: 0 };
+    const rows = store.listNodes({ owner: username }).filter((row) => row.kind !== 'dir');
+    return {
+      docs: rows.length,
+      bytes: rows.reduce((total, row) => total + (row.bytes || 0), 0),
+    };
+  }
+
+  // Called by the save lane before the kernel runs, because a quota that only
+  // notices afterwards is an audit log, not a limit.
+  function checkQuota(username, { relPath, bytes }) {
+    if (!store) return;
+    const row = store.getTenant(username);
+    if (!row) return;
+    const current = usage(username);
+    const existing = store.getNode(username, relPath);
+    const docs = existing ? current.docs : current.docs + 1;
+    const total = current.bytes - (existing?.bytes || 0) + bytes;
+
+    assert(docs <= limits.maxDocsPerTenant, 'too-large',
+      `That would be ${docs} documents, and this server allows ${limits.maxDocsPerTenant} each.`);
+    assert(total <= limits.maxBytesPerTenant, 'too-large',
+      'That would put you over your storage limit on this server.');
+  }
+
+  function recordUsage(username) {
+    if (!store || !store.getTenant(username)) return;
+    store.updateTenant(username, { bytesUsed: usage(username).bytes });
+  }
+
+  // ---- signup ------------------------------------------------------------
+
+  // The document being signed up to has to be an ORIGINAL that its owner opened
+  // for signups. Each clause closes a different hole: a private app would leak
+  // through its own instances, and an instance-of-an-instance would let one
+  // tenant recruit tenants of their own inside someone else's tree.
+  function signupTarget(node) {
+    assert(node && !node.provisional, 'not-found', 'Not found');
+    assert(node.signups, 'not-found', 'Not found');
+    assert(!node.private, 'not-found', 'Not found');
+    assert((node.owner ?? '') === '', 'forbidden', 'An instance cannot take signups of its own.');
+    assert(!node.sourceId, 'forbidden', 'An instance cannot take signups of its own.');
+    return node;
+  }
+
+  async function signup({ appNode, username: raw, password, res = null }) {
+    requireEnabled();
+    const app = signupTarget(appNode);
+
+    const username = String(raw ?? '').trim().toLowerCase();
+    const problem = usernameError(username);
+    assert(!problem, 'bad-request', problem || '');
+    assert(typeof password === 'string' && password.length >= 8,
+      'bad-request', 'Choose a password of at least 8 characters.');
+    assert(!store.getTenant(username), 'conflict', 'That username is taken.');
+    assert(store.listTenants().length < limits.maxTenants,
+      'forbidden', 'This server is not taking any more signups.');
+
+    const recoveryCode = generateRecoveryCode();
+    store.insertTenant({
+      username,
+      passwordHash: await hashPassword(password),
+      recoveryHash: await hashPassword(normalizeRecoveryCode(recoveryCode)),
+      sourceId: app.id,
+      createdAt: clock.now(),
+      // Approval is the default because an open signup form on a box someone
+      // runs at home is a way to fill their disk.
+      approvedAt: limits.approve ? null : clock.now(),
+    });
+    events.emit('tenant-created', { username });
+
+    if (limits.approve) {
+      return { username, state: 'waiting', recoveryCode, instance: null };
+    }
+    const instance = await provision(username, app);
+    if (res) sessions()?.issue(res, principal(username));
+    return { username, state: 'active', recoveryCode, instance };
+  }
+
+  // The fork. A copy of the app's bytes, created through the mutation kernel
+  // like every other document (invariant 2), which is also what strips the
+  // ephemeral save token on the way in.
+  async function provision(username, app) {
+    const realm = paths.realmRoot(username);
+    const source = await paths.resolveRead(app.owner ?? '', app.path);
+    const bytes = await readFileText(source);
+
+    const created = await ops.createDocument({
+      actor: asTenant(username),
+      owner: username,
+      name: path.basename(app.path),
+      html: bytes,
+      ctx: {},
+    });
+    store.updateNode(created.node.id, { sourceId: app.id });
+    recordUsage(username);
+    logger.info?.(`[makerclay] provisioned /~${username}/${created.path}`);
+    return { path: created.path, url: `/~${username}/${created.path}`, realm };
+  }
+
+  // ---- owner-side management ---------------------------------------------
+
+  async function approve({ actor, username, ctx: gate = {} }) {
+    requireEnabled();
+    assert(can(actor, 'admin', null, gate), 'not-found', 'Not found');
+    const row = store.getTenant(String(username || '').toLowerCase());
+    assert(row, 'not-found', 'No such person.');
+    assert(!row.approvedAt, 'conflict', 'They are already approved.');
+
+    const app = store.getNodeById(row.sourceId);
+    assert(app, 'not-found', 'The document they signed up to is gone.');
+
+    store.updateTenant(row.username, { approvedAt: clock.now(), disabledAt: null });
+    const instance = await provision(row.username, app);
+    events.emit('tenant-approved', { username: row.username });
+    return { ...get(row.username), instance };
+  }
+
+  function suspend({ actor, username, ctx: gate = {}, suspended = true }) {
+    requireEnabled();
+    assert(can(actor, 'admin', null, gate), 'not-found', 'Not found');
+    const row = store.getTenant(String(username || '').toLowerCase());
+    assert(row, 'not-found', 'No such person.');
+
+    store.updateTenant(row.username, { disabledAt: suspended ? clock.now() : null });
+    // Suspension has to evict, not just refuse the next login: a live session is
+    // exactly what a suspension is trying to end.
+    if (suspended) endAccess(row.username);
+    events.emit('tenant-updated', { username: row.username });
+    return get(row.username);
+  }
+
+  // No email on this server, so a reset is a code the owner reads out. It also
+  // signs every device out, because a reset nobody can be evicted by is theatre.
+  async function issueRecoveryCode({ actor, username, ctx: gate = {} }) {
+    requireEnabled();
+    assert(can(actor, 'admin', null, gate), 'not-found', 'Not found');
+    const row = store.getTenant(String(username || '').toLowerCase());
+    assert(row, 'not-found', 'No such person.');
+
+    const code = generateRecoveryCode();
+    store.updateTenant(row.username, { recoveryHash: await hashPassword(normalizeRecoveryCode(code)) });
+    endAccess(row.username);
+    return { username: row.username, recoveryCode: code };
+  }
+
+  // Trashes the tree rather than deleting it, so an owner who suspends the wrong
+  // person has the same undo everything else on this host has.
+  async function remove({ actor, username, ctx: gate = {} }) {
+    requireEnabled();
+    assert(can(actor, 'admin', null, gate), 'not-found', 'Not found');
+    const row = store.getTenant(String(username || '').toLowerCase());
+    assert(row, 'not-found', 'No such person.');
+
+    endAccess(row.username);
+    const realm = paths.realmRoot(row.username);
+    const trashed = [];
+    for (const name of await readdirIfExists(realm)) {
+      if (name.startsWith('.')) continue;
+      try {
+        await ops.trash({ actor: asTenant(row.username), owner: row.username, relPath: name, ctx: gate });
+        trashed.push(name);
+      } catch (error) {
+        logger.warn?.(`[makerclay] could not trash /~${row.username}/${name}:`, error?.message || error);
+      }
+    }
+    store.deleteTenant(row.username);
+    events.emit('tenant-removed', { username: row.username, trashed });
+    return { ok: true, username: row.username, trashed };
+  }
+
+  // ---- the tenant's own session ------------------------------------------
+
+  async function login({ username: raw, password, res }) {
+    requireEnabled();
+    const username = String(raw ?? '').trim().toLowerCase();
+    const row = store.getTenant(username);
+    // One message for every failure: which of "no such person", "not approved
+    // yet" and "wrong password" it was is not a stranger's business.
+    const fail = () => { throw new HostError('unauthorized', 'That username and password do not match.'); };
+    if (!row || !row.approvedAt || row.disabledAt) fail();
+    if (!(await verifyPassword(password, row.passwordHash))) fail();
+
+    sessions()?.issue(res, principal(username));
+    return { username, home: await homeOf(username) };
+  }
+
+  function logout(req, res) {
+    sessions()?.destroy(req, res);
+    return { ok: true };
+  }
+
+  async function recover({ username: raw, code, password, res }) {
+    requireEnabled();
+    const username = String(raw ?? '').trim().toLowerCase();
+    const row = store.getTenant(username);
+    const fail = () => { throw new HostError('unauthorized', 'That recovery code is not right.'); };
+    if (!row || !row.recoveryHash || row.disabledAt) fail();
+    if (!(await verifyPassword(normalizeRecoveryCode(code), row.recoveryHash))) fail();
+    assert(typeof password === 'string' && password.length >= 8,
+      'bad-request', 'Choose a password of at least 8 characters.');
+
+    // A recovery code is single use, and a fresh one is issued in its place, so
+    // nobody is ever one lost password away from having no way back in.
+    const next = generateRecoveryCode();
+    store.updateTenant(username, {
+      passwordHash: await hashPassword(password),
+      recoveryHash: await hashPassword(normalizeRecoveryCode(next)),
+    });
+    endAccess(username);
+    sessions()?.issue(res, principal(username));
+    return { username, recoveryCode: next, home: await homeOf(username) };
+  }
+
+  async function homeOf(username) {
+    const rows = store ? store.listNodes({ owner: username, kind: 'doc' }) : [];
+    if (rows.length) return `/~${username}/${rows[0].path}`;
+    const names = await readdirIfExists(paths.realmRoot(username));
+    const first = names.find((name) => /\.html?$/i.test(name));
+    return first ? `/~${username}/${first}` : `/~${username}/`;
+  }
+
+  return {
+    enabled,
+    limits,
+    usernameError,
+    get,
+    list,
+    usage,
+    checkQuota,
+    recordUsage,
+    signupTarget,
+    signup,
+    approve,
+    suspend,
+    issueRecoveryCode,
+    remove,
+    login,
+    logout,
+    recover,
+    homeOf,
+  };
+}

package/src/tenants/isolation.js

@@ -0,0 +1,91 @@
+// Which documents run under an opaque origin.
+//
+//   off        nothing in the owner's realm is sandboxed
+//   untrusted  every tenant document, plus any document the owner never saved
+//              through this host (uploaded, rsynced, restored from a backup).
+//              Needs a store to answer that; with store: null it runs as `off`.
+//   all        everything, the right posture for hosting files you did not write
+//
+// A per-node override in nodes.isolated wins over the config, in the owner's own
+// realm only: a tenant document is sandboxed under every mode and every override.
+
+const ISOLATION_MODES = ['off', 'untrusted', 'all'];
+
+export const SANDBOX_HEADER =
+  'sandbox allow-scripts allow-forms allow-popups allow-modals allow-downloads allow-top-navigation-by-user-activation';
+
+// Isolation decides two things and they must not drift apart: whether a node is
+// sandboxed, and what the response carrying its bytes says. Every lane that
+// sends node bytes calls this, so a new one cannot forget the header the way the
+// version-read lane did.
+export function applySecurityHeaders(res, isolated) {
+  res.setHeader('X-Content-Type-Options', 'nosniff');
+  if (!isolated) return;
+  res.setHeader('Content-Security-Policy', SANDBOX_HEADER);
+  res.setHeader('Referrer-Policy', 'no-referrer');
+}
+
+export function createIsolation({ config, store = null, logger = console }) {
+  const requested = ISOLATION_MODES.includes(config.isolation) ? config.isolation : 'untrusted';
+
+  // `untrusted` asks a question only a store can answer: has the owner ever saved
+  // this document through this host? With no store there are no rows, so every
+  // node is provisional and every `etag` is null. Read literally that says "this
+  // host has never vouched for anything", and the mode sandboxes the entire tree.
+  //
+  // That is not a strict reading of `untrusted`, it is a different mode: it is
+  // `all` in everything but name, and it silently breaks saving. A sandboxed
+  // document sends `Origin: null`, which the CSRF guard only accepts when the
+  // request carries a save token, and minting a save token needs the store that
+  // is not there. So the advertised `store: null` configuration boots, serves,
+  // and cannot save a single document from a browser.
+  //
+  // "Cannot know" is not "untrusted". With no memory to consult, the honest
+  // answer is the one that matches the configuration's own promise: no store
+  // means no per-document state, so no per-document sandboxing either.
+  const downgraded = requested === 'untrusted' && !store;
+  const mode = downgraded ? 'off' : requested;
+
+  if (downgraded) {
+    logger.warn?.(
+      '[makerclay] isolation "untrusted" needs a store to know which documents this host has saved. '
+      + 'With store: null it would sandbox every document and, because a sandboxed save needs a save '
+      + 'token this host cannot mint, make saving impossible. Running as isolation "off". '
+      + 'Set isolation: "all" if you meant to sandbox everything, and expect saves to be refused.',
+    );
+  }
+  if (mode === 'all' && !store) {
+    logger.warn?.(
+      '[makerclay] isolation "all" with store: null sandboxes every document, and a sandboxed save '
+      + 'needs a save token this host cannot mint without a store. Documents will serve but no save '
+      + 'will succeed from a browser.',
+    );
+  }
+
+  function isolatedFor(node) {
+    if (!node) return mode === 'all';
+    // A tenant realm is isolated unconditionally, ahead of both the per-node
+    // override and `isolation: 'off'`. Those two exist for the owner's own files.
+    // Letting either reach a tenant document means the owner opens someone else's
+    // HTML at their own origin, carrying their own session, which is the one
+    // outcome invariant 1 exists to prevent. There is no legitimate reason to
+    // turn this off for one document, so it is not offered.
+    if ((node.owner ?? '') !== '') return true;
+    if (node.isolated === true) return true;
+    if (node.isolated === false) return false;
+    if (mode === 'off') return false;
+    if (mode === 'all') return true;
+    // `etag` is written only by the mutation kernel, so a null one means the owner
+    // has never saved this document through this host: it was uploaded, rsynced or
+    // dropped in by an editor, and nobody here has vouched for it.
+    //
+    // Deliberately a fact about the DOCUMENT, not about the bytes currently on
+    // disk. A document saved once stays trusted even if it is later replaced from
+    // outside, because the alternative sandboxes every file the owner has ever
+    // edited in a terminal, which on this host is nearly all of them. The residual
+    // risk is restoring a compromised backup over a live install.
+    return node.etag == null;
+  }
+
+  return { mode, isolatedFor };
+}

package/src/tenants/routes.js

@@ -0,0 +1,131 @@
+import express from 'express';
+import { can } from '../auth/can.js';
+import { jsonError } from '../json-errors.js';
+import { createRateLimiter, parseRate } from '../auth/rate-limit.js';
+
+// The signup surface. Everything here is origin-checked by the host's CSRF guard
+// (no exemptions: unlike a collection submission, a signup has no reason to come
+// from someone else's site) and the public half is rate-limited by IP.
+
+export function mountTenantRoutes(ctx) {
+  const { router, config, tenants, resolveTarget, gateCtx, wrap, clock, ui } = ctx;
+  const json = express.json({ limit: '64kb' });
+  const form = express.urlencoded({ extended: false, limit: '64kb' });
+  const rate = parseRate(tenants.limits.signupRateLimit, { max: 10, windowMs: 3_600_000 });
+  const limiter = createRateLimiter({ clock, ...rate });
+
+  function requireOwner(req, res, next) {
+    if (!can(req.actor, 'admin', null, gateCtx)) return jsonError(res, 'not-found', 'Not found');
+    return next();
+  }
+
+  function wantsJson(req) {
+    return req.accepts(['html', 'json']) === 'json' || req.is('application/json');
+  }
+
+  function finish(req, res, body, redirect) {
+    if (wantsJson(req) || !redirect) return res.json({ ok: true, ...body });
+    return res.redirect(303, redirect);
+  }
+
+  function throttle(req, res) {
+    const verdict = limiter.check(req);
+    if (verdict.ok) return true;
+    res.setHeader('Retry-After', String(verdict.retryAfter));
+    jsonError(res, 'rate-limited', 'Too many attempts. Try again later.');
+    return false;
+  }
+
+  // ---- the public half ---------------------------------------------------
+
+  router.post('/tenant/signup', json, form, wrap(async (req, res) => {
+    if (!throttle(req, res)) return undefined;
+    const { app: appHref, username, password } = req.body || {};
+    if (typeof appHref !== 'string' || !appHref) {
+      return jsonError(res, 'bad-request', 'Which document are you signing up to?');
+    }
+
+    // Resolved through the normal read gate, so a private app is a 404 here for
+    // exactly the same reason it is a 404 everywhere else.
+    const found = await resolveTarget(req.actor, appHref, 'read');
+    if (!found) return jsonError(res, 'not-found', 'Not found');
+
+    // No `forgive` here, unlike login: the limit exists to stop a spray of
+    // SUCCESSFUL signups filling someone's disk, so a success has to count.
+    const result = await tenants.signup({
+      appNode: found.node, username, password, ctx: gateCtx, res,
+    });
+
+    return finish(req, res, {
+      username: result.username,
+      state: result.state,
+      // Shown once. There is no email on this server, so this is the only way
+      // back in, and the caller has to put it in front of the person NOW.
+      recoveryCode: result.recoveryCode,
+      home: result.instance?.url ?? null,
+      msg: result.state === 'waiting'
+        ? 'Your account is waiting for the owner to approve it.'
+        : 'Your copy is ready.',
+    }, result.instance?.url ?? null);
+  }));
+
+  router.post('/tenant/login', json, form, wrap(async (req, res) => {
+    if (!throttle(req, res)) return undefined;
+    const { username, password } = req.body || {};
+    const result = await tenants.login({ username, password, res });
+    limiter.forgive(req);
+    return finish(req, res, result, result.home);
+  }));
+
+  router.post('/tenant/logout', wrap(async (req, res) => {
+    return finish(req, res, tenants.logout(req, res), '/');
+  }));
+
+  router.post('/tenant/recover', json, form, wrap(async (req, res) => {
+    if (!throttle(req, res)) return undefined;
+    const { username, code, password } = req.body || {};
+    const result = await tenants.recover({ username, code, password, res });
+    limiter.forgive(req);
+    return finish(req, res, result, null);
+  }));
+
+  // Where a tenant lands with no idea what their document is called.
+  router.get('/tenant/home', wrap(async (req, res) => {
+    if (req.actor?.kind !== 'tenant') return jsonError(res, 'unauthorized', 'Sign in first.');
+    return res.redirect(303, await tenants.homeOf(req.actor.username));
+  }));
+
+  // ---- the owner's Tenants view -------------------------------------------
+
+  router.get('/tenants', requireOwner, wrap(async (req, res) => {
+    res.json({ ok: true, tenants: tenants.list({ actor: req.actor, ctx: gateCtx }), limits: tenants.limits });
+  }));
+
+  router.post('/tenants/:username/approve', requireOwner, wrap(async (req, res) => {
+    res.json({ ok: true, tenant: await tenants.approve({ actor: req.actor, username: req.params.username, ctx: gateCtx }) });
+  }));
+
+  for (const [route, suspended] of [['suspend', true], ['resume', false]]) {
+    router.post(`/tenants/:username/${route}`, requireOwner, wrap(async (req, res) => {
+      res.json({
+        ok: true,
+        tenant: tenants.suspend({ actor: req.actor, username: req.params.username, ctx: gateCtx, suspended }),
+      });
+    }));
+  }
+
+  router.post('/tenants/:username/reset', requireOwner, wrap(async (req, res) => {
+    const result = await tenants.issueRecoveryCode({ actor: req.actor, username: req.params.username, ctx: gateCtx });
+    // Read this out to them. It is single use and it signs their devices out.
+    res.json({ ok: true, ...result });
+  }));
+
+  router.post('/tenants/:username/delete', requireOwner, wrap(async (req, res) => {
+    res.json(await tenants.remove({ actor: req.actor, username: req.params.username, ctx: gateCtx }));
+  }));
+
+  router.get('/tenants.html', requireOwner, wrap(async (req, res) => {
+    if (config.features?.dashboard === false) return jsonError(res, 'not-found', 'Not found');
+    return ui.send(res, 'tenants', { title: 'People on this server' });
+  }));
+}

package/src/ui.js

@@ -0,0 +1,95 @@
+import path from 'upath';
+import { fileURLToPath } from 'node:url';
+import {
+  readdirIfExists, readFileTextIfExists, statIfExists, atomicWrite, mkdirp,
+} from './util/fsx.js';
+
+// Two copies of the shipped UI, and a third the owner can make (§17.2).
+//
+//   packages/core/ui/    read-only, what the release contains
+//   <data>/ui/           copied on first run, and what actually serves
+//   files/_ui/           `makerclay eject`: ordinary, editable, VERSIONED
+//                        malleable documents, preferred when present
+//
+// The canonical UI stays boring and unbrickable; `makerclay repair --ui`
+// restores it. The ejected copy is the fork button that makes "you own this" a
+// command rather than a slogan.
+
+const PACKAGE_UI = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'ui');
+const EJECT_DIR = '_ui';
+
+const ESCAPES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+
+function escapeHtml(value) {
+  return String(value ?? '').replace(/[&<>"']/g, (char) => ESCAPES[char]);
+}
+
+// {{name}} is escaped, {{{name}}} is raw. A missing key renders empty rather
+// than leaving the braces on screen.
+export function renderTemplate(source, vars = {}) {
+  return source
+    .replace(/\{\{\{\s*([\w.]+)\s*\}\}\}/g, (_, key) => String(vars[key] ?? ''))
+    .replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_, key) => escapeHtml(vars[key] ?? ''));
+}
+
+export function createUi({ paths, logger = console }) {
+  async function packagePages() {
+    return (await readdirIfExists(PACKAGE_UI))
+      .filter((name) => name.endsWith('.html') || name.endsWith('.css'));
+  }
+
+  // Copy the shipped pages into the data directory on first run. Never
+  // overwrites: an owner who edited <data>/ui/ keeps their edits, and
+  // `repair --ui` is the explicit way back.
+  async function ensure({ force = false } = {}) {
+    await mkdirp(paths.dirs.ui);
+    let copied = 0;
+    for (const name of await packagePages()) {
+      const target = path.join(paths.dirs.ui, name);
+      if (!force && (await statIfExists(target))) continue;
+      const source = await readFileTextIfExists(path.join(PACKAGE_UI, name));
+      if (source == null) continue;
+      await atomicWrite(target, source);
+      copied += 1;
+    }
+    if (copied) logger.info?.(`[makerclay] installed ${copied} UI page(s) into ${paths.dirs.ui}`);
+    return { copied };
+  }
+
+  // Ejected copy first, then the data directory, then the package. One chain,
+  // so an owner who ejects gets their version of every page at once.
+  async function resolveFile(filename) {
+    const safe = String(filename).replace(/[^a-z0-9.-]/gi, '');
+    if (!safe || safe.includes('..')) return null;
+    for (const dir of [path.join(paths.dirs.files, EJECT_DIR), paths.dirs.ui, PACKAGE_UI]) {
+      const candidate = path.join(dir, safe);
+      if (await statIfExists(candidate)) return candidate;
+    }
+    return null;
+  }
+
+  async function resolve(name) {
+    return resolveFile(`${String(name).replace(/[^a-z0-9-]/gi, '')}.html`);
+  }
+
+  async function render(name, vars = {}) {
+    const file = await resolve(name);
+    if (!file) return null;
+    const source = await readFileTextIfExists(file);
+    if (source == null) return null;
+    return renderTemplate(source, vars);
+  }
+
+  async function send(res, name, vars = {}, status = 200) {
+    const body = await render(name, vars);
+    if (body == null) {
+      return res.status(500).type('text/html')
+        .send('<!DOCTYPE html><title>Missing page</title><h1>This page is missing</h1><p>Run <code>makerclay repair --ui</code>.</p>');
+    }
+    res.status(status).type('text/html; charset=utf-8');
+    res.setHeader('Cache-Control', 'no-store');
+    return res.send(body);
+  }
+
+  return { ensure, resolve, resolveFile, render, send, packageDir: PACKAGE_UI, ejectDir: EJECT_DIR, packagePages };
+}