@motujs/host 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scorbutics
+
+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/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@motujs/host",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Server for the shared motu lagoon host: stores published region previews and serves a live URL per branch.",
+  "keywords": [
+    "motu",
+    "react",
+    "islands",
+    "ui-architecture",
+    "state-management",
+    "preview-server",
+    "hosting",
+    "ui-preview"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Scorbutics/motu.git",
+    "directory": "packages/host"
+  },
+  "homepage": "https://github.com/Scorbutics/motu#readme",
+  "type": "module",
+  "bin": {
+    "motu-host": "src/cli.mjs"
+  },
+  "main": "src/store.mjs",
+  "dependencies": {
+    "@motujs/chrome": "0.1.0",
+    "@motujs/coverage": "0.1.0"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  }
 }

package/src/access.mjs

@@ -0,0 +1,180 @@
+// WHO MAY READ, AND WHO MAY WRITE WHAT — the host's access policy, in one place.
+//
+// The host began with a single global token that gated every POST and nothing else: reads were
+// entirely public, and one credential could do everything. That is the right shape for a personal
+// preview server and the wrong one for two things it is being asked to do now.
+//
+//   A LAGOON MAY NEED TO BE PRIVATE. Some pages are the point of the host — a link you send someone.
+//   Others carry a coverage corpus, which is a picture of what a production application does. Both
+//   live here, so visibility has to be per repo rather than a property of the whole host.
+//
+//   AN INGEST CREDENTIAL LIVES SOMEWHERE ELSE. A coverage proxy forwards a corpus to this host from
+//   an application's own server, so its token sits in that application's environment. With one global
+//   token, a leak from any adopting app is write access to EVERY repo here — including the ability to
+//   overwrite published lagoons. So an ingest token is scoped to one repo and can do exactly one
+//   thing.
+//
+// THE DEFAULT IS WHAT THE HOST ALREADY DID. No access file means: every repo public, the global token
+// admits every write. Upgrading changes nothing until somebody writes a policy down.
+//
+// TOKENS ARE STORED HASHED. The file sits in the store directory beside the objects, and a backup of
+// a preview server should not be a credential leak. Comparison is constant-time over the digests, and
+// digests are a fixed 32 bytes — so the compare is total and cannot throw on a length mismatch, which
+// is the failure mode that turns a wrong token into a 500 that distinguishes it from a wrong-length
+// one.
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const ACCESS_FILE = 'access.json';
+
+/** sha256 of a secret, as bytes. Always 32 of them, whatever went in. */
+export function digest(value) {
+  return createHash('sha256').update(String(value ?? ''), 'utf8').digest();
+}
+
+/** Constant-time equality over digests — total, so a wrong length is a mismatch and never a throw. */
+export function secretMatches(offered, expectedHashHex) {
+  if (!expectedHashHex) return false;
+  let expected;
+  try {
+    expected = Buffer.from(String(expectedHashHex), 'hex');
+  } catch {
+    return false;
+  }
+  if (expected.length !== 32) return false;
+  return timingSafeEqual(digest(offered), expected);
+}
+
+/**
+ * Read the policy from the store directory.
+ *
+ * Re-read per request rather than cached: this file changes when a person edits it, the host is a
+ * long-running process nobody wants to restart, and it is a few hundred bytes. A malformed file is
+ * treated as ABSENT and reported by the caller — never as "deny everything", because locking an
+ * operator out of their own host over a stray comma is a worse failure than staying as open as the
+ * host was yesterday.
+ */
+export function loadAccess(dir) {
+  const file = resolve(dir, ACCESS_FILE);
+  if (!existsSync(file)) return { repos: {}, readHash: null, defaultVisibility: 'public', malformed: false };
+  try {
+    const raw = JSON.parse(readFileSync(file, 'utf8'));
+    return {
+      repos: raw && typeof raw.repos === 'object' && raw.repos ? raw.repos : {},
+      readHash: typeof raw?.readHash === 'string' ? raw.readHash : null,
+      // WHICH WAY THE HOST LEANS for a repo nobody has written a policy for. It lives HERE, in the
+      // policy file, rather than in a flag or an environment variable, for the reason the `access`
+      // subcommand already learned the hard way: a value the service reads from its unit file is a
+      // value your shell does not have, so the two disagree silently and the command that reports
+      // the policy reports a different one from the host enforcing it. The file is re-read per
+      // request, so flipping this takes effect without a restart.
+      //
+      // Anything but the exact string 'private' is public, so a typo opens the host rather than
+      // closing it — the same direction as `malformed`, and for the same reason: locking an operator
+      // out of their own host over a stray character is the worse failure.
+      defaultVisibility: raw?.defaultVisibility === 'private' ? 'private' : 'public',
+      malformed: false,
+    };
+  } catch {
+    return { repos: {}, readHash: null, defaultVisibility: 'public', malformed: true };
+  }
+}
+
+/**
+ * Is this repo's content public?
+ *
+ * A repo with a policy answers for itself. One WITHOUT falls back to the host's default, which is
+ * `public` unless somebody wrote `defaultVisibility` down — so the host still behaves exactly as it
+ * did before this existed, and a personal host on a public domain can close the door for everything
+ * at once instead of remembering to do it per repo.
+ *
+ * THIS IS WHAT CLOSES THE WINDOW. Visibility is per repo and a repo comes into existence by being
+ * published to, so with a public default there is a gap between the first publish landing and
+ * somebody marking it private. An agent publishing an ephemeral per-branch lagoon cannot close that
+ * gap itself — nothing in the wire protocol sets visibility — so the only place it CAN be closed is
+ * before the repo exists.
+ */
+export function isPublic(access, repo) {
+  const declared = access.repos?.[repo]?.visibility;
+  if (declared) return declared !== 'private';
+  return access.defaultVisibility !== 'private';
+}
+
+/**
+ * May this request READ this repo?
+ *
+ * A public repo: always. A private one: the admin token, or the host's read secret — which arrives as
+ * a cookie, because the reader is a browser following a link and cannot set a header.
+ */
+export function canRead(access, repo, { adminOk, readSecret }) {
+  if (isPublic(access, repo)) return true;
+  if (adminOk) return true;
+  // TWO SCOPES, and the narrow one exists because of where these end up.
+  //
+  // The host-wide secret opens EVERY private repo. That is right for a person carrying one cookie,
+  // and wrong for a credential that has to live in an application's production environment: an
+  // adopting app needs to read back its OWN accepted set, and giving it a key to every private
+  // lagoon on the host to do that undoes the reason ingest tokens are scoped at all.
+  //
+  // Checked in this order so a repo token is enough on its own, and the host-wide one still works
+  // everywhere — including on a repo that also has its own.
+  if (secretMatches(readSecret, access.repos?.[repo]?.readHash)) return true;
+  return secretMatches(readSecret, access.readHash);
+}
+
+/**
+ * The read secret, from wherever this reader could put it.
+ *
+ * A BROWSER CANNOT SET A HEADER when it follows a link, so a person reading a private lagoon carries
+ * a cookie. A SERVER CANNOT SEND A COOKIE it was never given, so an application reading a corpus back
+ * — a status page, a CI job — carries a bearer. Same secret, two transports, because the constraint
+ * is the caller's and not the policy's.
+ *
+ * The ingest token deliberately does NOT open this door: it is write-only so that a credential
+ * sitting in somebody else's production environment cannot be used to read what is stored here.
+ */
+export function readSecretFrom({ cookieHeader, bearer }) {
+  return cookieValue(cookieHeader, READ_COOKIE) ?? (bearer || null);
+}
+
+/**
+ * May this request INGEST for this repo?
+ *
+ * Deliberately narrow: an ingest token grants ONE repo and only the corpus route. It cannot publish a
+ * lagoon, cannot register a live frame, cannot read anything, and cannot touch another repo — because
+ * it lives in the environment of an application this host does not control.
+ */
+export function canIngest(access, repo, offered) {
+  const hash = access.repos?.[repo]?.ingestHash;
+  return secretMatches(offered, hash);
+}
+
+/**
+ * The ONE repo an ingest token belongs to, or null.
+ *
+ * An ingest token is already scoped to exactly one repo, so the repo is a fact about the token, not
+ * something the application should have to repeat. Asking it to was one of the four values a
+ * production deployment had to get right for coverage to land, and the host has never stored a
+ * corpus. Fewer values to set is fewer ways to be silently wrong.
+ */
+export function ingestRepoOf(access, offered) {
+  if (!offered) return null;
+  for (const [repo, policy] of Object.entries(access.repos ?? {})) {
+    if (secretMatches(offered, policy?.ingestHash)) return repo;
+  }
+  return null;
+}
+
+/** The cookie a reader carries once they have opened a private link. */
+export const READ_COOKIE = 'motu_read';
+
+/** Pull one cookie out of a request without a parser dependency. */
+export function cookieValue(header, name) {
+  for (const part of String(header ?? '').split(';')) {
+    const eq = part.indexOf('=');
+    if (eq < 0) continue;
+    if (part.slice(0, eq).trim() === name) return decodeURIComponent(part.slice(eq + 1).trim());
+  }
+  return null;
+}

package/src/cli.mjs

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+// `motu-host` — run the lagoon host.
+//
+// Its own binary, not `motu lagoon host`, and that is a boundary rather than a convenience: every
+// `motu` subcommand resolves ONE project's motu.config.json at import time, and this process serves
+// many repositories and belongs to none of them.
+//
+//   motu-host --token $(openssl rand -hex 24)     accept uploads, serve on 127.0.0.1:8818
+//   motu-host --host --max-records 1000           bind the LAN too, keep 1000 records per repo
+//
+// Reads are open; uploads need the token. Without one the host still serves what it already holds
+// and refuses every write, which is the right shape for putting a read-only mirror somewhere.
+import { networkInterfaces } from 'node:os';
+import { createLagoonHost } from './server.mjs';
+import { DEFAULT_MAX_RECORDS, DEFAULT_MAX_BYTES } from './store.mjs';
+
+const color = {
+  red: (s) => `\x1b[31m${s}\x1b[0m`,
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+  dim: (s) => `\x1b[2m${s}\x1b[0m`,
+  bold: (s) => `\x1b[1m${s}\x1b[0m`,
+};
+
+function parse(args) {
+  const out = { _: [] };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith('--no-')) out[a.slice(5)] = false;
+    else if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = args[i + 1];
+      if (next !== undefined && !next.startsWith('--')) {
+        out[key] = next;
+        i++;
+      } else out[key] = true;
+    } else out._.push(a);
+  }
+  return out;
+}
+
+const argv = parse(process.argv.slice(2));
+
+if (argv.help || argv.h) {
+  console.log(`${color.bold('motu-host')} — serve published lagoons
+
+  --port <n>            default 8818
+  --host                also bind 0.0.0.0 (LAN), not just loopback
+  --dir <path>          store location (default $MOTU_HOST_DIR or ~/.motu/host)
+  --max-records <n>     publish records kept per repo (default ${DEFAULT_MAX_RECORDS})
+  --max-bytes <n>       bytes kept per repo (default ${(DEFAULT_MAX_BYTES / 1073741824).toFixed(0)} GB) — whichever cap binds first wins
+  --token <secret>      required for uploads (or $MOTU_HOST_TOKEN)
+
+  ${color.dim('$MOTU_LIVE_ALLOW     hosts a live lagoon may be announced from, beyond loopback')}
+  ${color.dim('  comma-separated; a leading dot is a suffix. Unset = loopback only.')}
+  ${color.dim('  MOTU_LIVE_ALLOW=.my-tailnet.ts.net,192.168.1.20')}
+  ${color.dim('  This host FETCHES what it is told, so every name here is one it can be aimed at.')}
+`);
+  process.exit(0);
+}
+
+const port = Number.parseInt(String(argv.port ?? 8818), 10);
+if (!Number.isInteger(port) || port < 1 || port > 65535) {
+  console.error(color.red(`✗ --port must be 1-65535, got "${argv.port}"`));
+  process.exit(1);
+}
+const maxRecords = Number.parseInt(String(argv['max-records'] ?? process.env.MOTU_HOST_MAX_RECORDS ?? DEFAULT_MAX_RECORDS), 10);
+if (!Number.isInteger(maxRecords) || maxRecords < 1) {
+  console.error(color.red(`✗ --max-records must be a positive integer, got "${argv['max-records']}"`));
+  process.exit(1);
+}
+const maxBytes = Number.parseInt(String(argv['max-bytes'] ?? process.env.MOTU_HOST_MAX_BYTES ?? DEFAULT_MAX_BYTES), 10);
+if (!Number.isInteger(maxBytes) || maxBytes < 1) {
+  console.error(color.red(`✗ --max-bytes must be a positive integer, got "${argv['max-bytes']}"`));
+  process.exit(1);
+}
+// `motu-host access` — mint a credential, or make a repo private.
+//
+// THE HASHES ARE NOT HAND-WRITABLE, which is the only reason this subcommand exists. access.json
+// stores sha256 digests so a backup of a preview server is not a credential leak, and asking somebody
+// to produce one with an openssl incantation is asking them to skip the feature.
+//
+// The secret is printed ONCE and never stored — the file keeps only its digest, so there is nothing
+// here to read it back from. That is the point, and it is worth saying out loud at the moment
+// somebody is deciding whether to copy it.
+if (argv._[0] === 'access') {
+  const { digest, loadAccess } = await import('./access.mjs');
+  const { randomBytes } = await import('node:crypto');
+  const { writeFileSync, mkdirSync, existsSync } = await import('node:fs');
+  const { homedir } = await import('node:os');
+  const { resolve } = await import('node:path');
+  const { storeDir } = await import('./store.mjs');
+  const dir = storeDir(typeof argv.dir === 'string' ? argv.dir : undefined);
+
+  // IS THIS THE DIRECTORY THE RUNNING HOST READS? Almost the only way to get this wrong, and it fails
+  // silently: the policy is written, the command says ✓, and nothing changes.
+  //
+  // It happened. The service sets MOTU_HOST_DIR in its unit file, which is not in a shell's
+  // environment — so `motu-host access --repo X --private` resolved the DEFAULT `~/.motu/host`,
+  // created it, wrote a correct policy into it, and reported success while the live host at
+  // ~/.local/share/motu-host went on serving the repo to everyone. Sharing `storeDir()` between the
+  // two was not enough, because what differs is the ENVIRONMENT, not the expression.
+  //
+  // `index.json` is the store's own file, so its absence means this directory is not a store — either
+  // the wrong one, or a host that has never run. Refused rather than warned: a warning above a ✓ is
+  // read as a ✓, and the whole failure mode here is a command that looks like it worked.
+  if (!existsSync(resolve(dir, 'index.json'))) {
+    const guesses = [
+      process.env.MOTU_HOST_DIR,
+      resolve(homedir(), '.local/share/motu-host'),
+      resolve(homedir(), '.motu/host'),
+    ].filter((d, i, all) => d && all.indexOf(d) === i && existsSync(resolve(d, 'index.json')));
+    console.error(color.red(`✗ no lagoon host store in ${dir}`));
+    console.error(color.dim('  There is no index.json there, so this is not the directory a host is using — and'));
+    console.error(color.dim('  writing a policy into it would report success and change nothing.'));
+    if (guesses.length) {
+      console.error('');
+      console.error(color.dim('  A store does exist here:'));
+      for (const g of guesses) console.error(`      --dir ${g}`);
+      console.error('');
+      console.error(color.dim('  The service sets MOTU_HOST_DIR in its unit file, which your shell does not inherit.'));
+    } else {
+      console.error(color.dim('  Pass --dir <path>, or set MOTU_HOST_DIR to the directory the host runs with.'));
+    }
+    process.exit(1);
+  }
+
+  const file = resolve(dir, 'access.json');
+  const access = loadAccess(dir);
+  if (access.malformed) {
+    console.error(color.red(`✗ ${file} is not valid JSON — refusing to overwrite it`));
+    process.exit(1);
+  }
+  // CARRY WHAT WE ARE NOT CHANGING. This object REPLACES the file, so a key omitted here is a key
+  // deleted — and the one that matters is `defaultVisibility`: minting a read token would have
+  // silently reopened every repo on the host.
+  const out = { readHash: access.readHash, defaultVisibility: access.defaultVisibility, repos: { ...access.repos } };
+  const repo = typeof argv.repo === 'string' ? argv.repo : null;
+  const minted = [];
+
+  if (argv.read) {
+    const secret = randomBytes(32).toString('hex');
+    if (repo) {
+      // `--read --repo X` is the NARROW one: it opens that repo and nothing else. This is what an
+      // application holds so it can read back its own accepted set, and what you hand somebody who
+      // should see one project rather than all of them.
+      out.repos[repo] = { ...(out.repos[repo] ?? {}), readHash: digest(secret).toString('hex') };
+      minted.push([`read token for ${repo} (that repo only)`, secret]);
+    } else {
+      out.readHash = digest(secret).toString('hex');
+      minted.push(['read secret (opens EVERY private lagoon — for your browser, not an app)', secret]);
+    }
+  }
+  if (argv.ingest) {
+    if (!repo) {
+      console.error(color.red('✗ --ingest needs --repo <owner/name>: an ingest token grants exactly one repo'));
+      process.exit(1);
+    }
+    const secret = randomBytes(32).toString('hex');
+    out.repos[repo] = { ...(out.repos[repo] ?? {}), ingestHash: digest(secret).toString('hex') };
+    minted.push([`ingest token for ${repo}`, secret]);
+  }
+  if (argv.private || argv.public) {
+    if (!repo) {
+      console.error(color.red('✗ --private/--public needs --repo <owner/name>'));
+      process.exit(1);
+    }
+    out.repos[repo] = { ...(out.repos[repo] ?? {}), visibility: argv.private ? 'private' : 'public' };
+  }
+  // WHICH WAY A REPO NOBODY HAS DECIDED ABOUT LEANS. Its own switch rather than a spelling of
+  // --private, because it is a different act: --private closes ONE repo that already exists, this
+  // decides what happens to every repo that does NOT exist yet — including the ones an agent is
+  // about to create by publishing to them.
+  let defaultChanged = false;
+  if (argv.default !== undefined) {
+    const want = String(argv.default);
+    if (want !== 'private' && want !== 'public') {
+      console.error(color.red(`✗ --default takes private or public, got "${want}"`));
+      process.exit(1);
+    }
+    defaultChanged = out.defaultVisibility !== want;
+    out.defaultVisibility = want;
+  }
+  if (!minted.length && !argv.private && !argv.public && argv.default === undefined) {
+    console.log('');
+    console.log('  motu-host access --read                      mint the secret that opens EVERY private lagoon');
+    console.log('  motu-host access --repo <r> --read           mint one that opens only that repo');
+    console.log('  motu-host access --repo <r> --ingest         mint a write-only coverage token for one repo');
+    console.log('  motu-host access --repo <r> --private        stop serving that repo to strangers');
+    console.log('  motu-host access --repo <r> --public         serve it again');
+    console.log('  motu-host access --default private           close every repo nobody decided about');
+    console.log('');
+    const names = Object.keys(access.repos);
+    console.log(color.dim(`  ${file}`));
+    console.log(color.dim(`  ${names.length} repo(s) with a policy${names.length ? `: ${names.join(', ')}` : ''}`));
+    // SAID OUT LOUD, because "no policy" reads as public and is the one thing here nobody can infer
+    // from the repo list — a host leaning private lists nothing and serves nothing to strangers.
+    console.log(
+      access.defaultVisibility === 'private'
+        ? color.dim('  default for a repo with no policy: PRIVATE — including ones not published yet')
+        : color.dim('  default for a repo with no policy: public  (motu-host access --default private)'),
+    );
+    console.log(color.dim(`  read secret ${access.readHash ? 'set' : 'NOT set — every private lagoon is closed to everyone but the admin token'}`));
+    process.exit(0);
+  }
+
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(file, `${JSON.stringify(out, null, 2)}\n`);
+  console.log('');
+  for (const [what, secret] of minted) {
+    console.log(`  ${color.green('✓')} ${what}`);
+    console.log(`    ${secret}`);
+  }
+  if (argv.private) console.log(`  ${color.green('✓')} ${repo} is private — strangers get 404, not 403`);
+  if (argv.public) console.log(`  ${color.green('✓')} ${repo} is public`);
+  if (argv.default !== undefined) {
+    const now = out.defaultVisibility;
+    console.log(
+      `  ${color.green('✓')} repos with no policy of their own are ${now.toUpperCase()}${defaultChanged ? '' : ' (unchanged)'}`,
+    );
+    if (now === 'private')
+      console.log(color.dim('    a publish now creates a CLOSED repo — mint a reader with --read, then visit /?k=<secret> once'));
+  }
+  if (minted.length) {
+    console.log('');
+    console.log(color.dim('  Shown once. Only the digest is stored, so this cannot be read back — mint a new one if it is lost.'));
+    if (argv.read) console.log(color.dim('  A reader opens a private link by visiting it with ?k=<secret> once.'));
+  }
+  console.log(color.dim(`  ${file}`));
+  console.log('');
+  process.exit(0);
+}
+
+const token = typeof argv.token === 'string' ? argv.token : process.env.MOTU_HOST_TOKEN || null;
+const lan = argv.host === true || argv.host === '0.0.0.0';
+const bind = lan ? '0.0.0.0' : '127.0.0.1';
+
+const { server, store } = createLagoonHost({ dir: typeof argv.dir === 'string' ? argv.dir : undefined, maxRecords, maxBytes, token });
+
+server.on('error', (err) => {
+  if (err.code === 'EADDRINUSE') console.error(color.red(`✗ port ${port} is already in use — pass --port <n>`));
+  else if (err.code === 'EACCES') console.error(color.red(`✗ not allowed to bind port ${port} — pick one above 1024`));
+  else console.error(color.red(`✗ ${err.message}`));
+  process.exit(1);
+});
+
+function lanAddress() {
+  for (const [name, addrs] of Object.entries(networkInterfaces())) {
+    if (/^(docker|br-|veth|virbr|tun|tap)/.test(name)) continue;
+    for (const a of addrs ?? []) if (a.family === 'IPv4' && !a.internal) return a.address;
+  }
+  return null;
+}
+
+server.listen(port, bind, () => {
+  const s = store.stats();
+  console.log('');
+  console.log(`${color.green('✓')} ${color.bold('motu lagoon host')} — ${s.repos} repo(s), ${s.blobs} object(s), ${(s.bytes / 1048576).toFixed(1)} MB`);
+  console.log(`  http://localhost:${port}`);
+  const ip = lan ? lanAddress() : null;
+  if (ip) console.log(`  http://${ip}:${port}   ${color.dim('(LAN)')}`);
+  console.log(color.dim(`  store ${s.root} · cap ${maxRecords} records or ${(maxBytes / 1073741824).toFixed(0)} GB per repo`));
+  if (!token) console.log(color.yellow('  no token — uploads are refused. Pass --token or set MOTU_HOST_TOKEN.'));
+  // SAID EVERY START, because this one is easy to leave on. It only ever answers an unproxied
+  // loopback request, so it cannot be reached through a tunnel — but an operator who forgot it is set
+  // should be reminded by the thing they look at when they start the host.
+  if (process.env.MOTU_HOST_OPEN_LOCAL === '1')
+    console.log(
+      color.yellow('  MOTU_HOST_OPEN_LOCAL=1 — private repos are READABLE by unproxied requests from this machine.'),
+    );
+  console.log('');
+  console.log(color.dim('  Publish into it:  motu lagoon publish --remote http://localhost:' + port));
+  console.log(color.dim('  Ctrl-C to stop.'));
+});

package/src/document.mjs

@@ -0,0 +1,65 @@
+// Putting the document skeleton back on a published fragment.
+//
+// `motu lagoon publish` deliberately strips <!doctype>/<html>/<head>/<body>, because the Artifact
+// host supplies its own. A browser will limp along without them, but it gets no charset and no
+// viewport meta — so the page renders desktop-width on exactly the device this whole feature exists
+// to serve. The CLI's `motu lagoon serve` already re-wraps for the same reason; this is that rule,
+// applied on the hosted side, to the same bytes.
+//
+// Tolerant on purpose: if a fragment ever arrives already wrapped (an older publish, someone's
+// curl), serve it as-is rather than nesting a second <html> inside the first.
+
+const HAS_SKELETON = /<html[\s>]/i;
+
+export function wrapFragment(fragment, { title } = {}) {
+  const body = typeof fragment === 'string' ? fragment : fragment.toString('utf8');
+  if (HAS_SKELETON.test(body)) return body;
+  const head = title ? `<title>${escapeHtml(title)}</title>\n` : '';
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+${head}</head>
+<body>
+${body}</body>
+</html>
+`;
+}
+
+export function escapeHtml(s) {
+  return String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+}
+
+/**
+ * Tell a served page which repo it belongs to, so it can ask this host about itself.
+ *
+ * A published lagoon is a self-contained document, so `wrapFragment` returns it untouched — there is
+ * no skeleton to add a tag to. The host inserts one here instead, at the moment it serves the bytes,
+ * because it is the only party that knows the answer: the page was built before anyone chose where to
+ * publish it, and inside a gallery frame the URL says nothing about the repo either.
+ *
+ * A REPO NAME, AND NOTHING ELSE. Not a URL and not a credential — the page asks its OWN origin, and
+ * whoever is reading it is already authorised (or not) by the same cookie that let them open the
+ * page. That is what keeps a published lagoon free of the two things it must never carry.
+ *
+ * WRAP FIRST, THEN STAMP — the order matters and it is not obvious. A published lagoon is a whole
+ * document nested inside the skeleton `wrapFragment` adds, so stamping the fragment puts the tag in
+ * the OUTER document's body. It is in the bytes, curl finds it, and the page's own React render
+ * replaces the body and takes it with it: `document.querySelector('meta[name=motu-repo]')` returns
+ * null in the one place that needed it. Stamping the wrapped document puts it in the outer <head>,
+ * which nothing on the page touches.
+ *
+ * Fails open: a document with no <head> to insert into is returned exactly as it arrived. A page that
+ * cannot look up its coverage is a page missing one panel, and mangling somebody's HTML to avoid that
+ * is a bad trade.
+ */
+export function withRepoMeta(bytes, repo) {
+  if (!repo) return bytes;
+  const html = typeof bytes === 'string' ? bytes : bytes.toString('utf8');
+  const at = html.search(/<head[^>]*>/i);
+  if (at < 0) return bytes;
+  const insert = html.indexOf('>', at) + 1;
+  const tag = `\n<meta name="motu-repo" content="${escapeHtml(repo)}" />`;
+  return Buffer.from(html.slice(0, insert) + tag + html.slice(insert), 'utf8');
+}

package/src/manifest.mjs

@@ -0,0 +1,68 @@
+// A CHUNKED lagoon, as the host stores and serves it.
+//
+// `motu lagoon publish --remote` (and a pushed draft) sends a MANIFEST rather than one self-contained
+// page: the page's HTML, and each file it loads named by the sha256 of its content. The chunks
+// themselves arrive first, as blobs, so an edit in one region costs that region's chunk.
+//
+//   { "motu": "lagoon-manifest/1", "html": "<fragment>", "files": { "region-members.js": "<sha256>" } }
+//
+// The page's references read `__MOTU_ASSETS__/<file>`; serving fills that with
+// `/__motu_assets/<manifest hash>`, and that route answers each file from the manifest. The address is
+// keyed by the manifest's content, so it can be cached forever, and a `latest` page that moves on
+// never mixes chunks from two builds. The CLI side is `packages/cli/src/lib/lagoon-bundle.mjs`; the
+// format strings below must match it.
+
+export const MANIFEST_FORMAT = 'lagoon-manifest/1';
+export const MANIFEST_TYPE = 'application/vnd.motu.lagoon+json';
+export const ASSETS_PLACEHOLDER = '__MOTU_ASSETS__';
+
+const HASH = /^[0-9a-f]{64}$/;
+const NAME = /^[A-Za-z0-9._@+-][A-Za-z0-9._@+/-]*$/;
+
+/** The manifest in these bytes, or null when they are a single-file page (or not a manifest). */
+export function parseManifest(bytes) {
+  const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(String(bytes), 'utf8');
+  // Cheap test first: a page is HTML and never starts with `{`.
+  let i = 0;
+  while (i < buf.length && (buf[i] === 0x20 || buf[i] === 0x0a || buf[i] === 0x0d || buf[i] === 0x09)) i++;
+  if (buf[i] !== 0x7b) return null;
+  let m;
+  try {
+    m = JSON.parse(buf.toString('utf8'));
+  } catch {
+    return null;
+  }
+  if (!m || m.motu !== MANIFEST_FORMAT || typeof m.html !== 'string' || !m.files || typeof m.files !== 'object') return null;
+  for (const [name, h] of Object.entries(m.files)) {
+    if (!NAME.test(name) || name.includes('..') || typeof h !== 'string' || !HASH.test(h)) return null;
+  }
+  return { html: m.html, files: m.files };
+}
+
+/** The page of a manifest, with its chunks' address filled in. */
+export function manifestPage(manifest, manifestHash) {
+  return manifest.html.split(ASSETS_PLACEHOLDER).join(`/__motu_assets/${manifestHash}`);
+}
+
+const TYPES = {
+  js: 'text/javascript; charset=utf-8',
+  mjs: 'text/javascript; charset=utf-8',
+  css: 'text/css; charset=utf-8',
+  json: 'application/json',
+  svg: 'image/svg+xml',
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  avif: 'image/avif',
+  ico: 'image/x-icon',
+  woff: 'font/woff',
+  woff2: 'font/woff2',
+  ttf: 'font/ttf',
+  otf: 'font/otf',
+  wasm: 'application/wasm',
+  mp4: 'video/mp4',
+  webm: 'video/webm',
+};
+export const contentTypeOf = (name) => TYPES[String(name).split('.').pop().toLowerCase()] ?? 'application/octet-stream';