feat(pit): serve a name at an IPv6 address, and say how on the page

A name could be pointed at an IPv6 address and then not work, in two
different ways, neither of which said so.

The bridge only answered A. An AAAA query got an empty answer and the
target went into `ipv4()`, which returned null, which is NXDOMAIN — so a
name pointed at a v6 address did not resolve at all. It now answers both
families, and an A query for a v6-only name comes back NOERROR with no
answers rather than NXDOMAIN: browsers ask for both, and NXDOMAIN on the
A half is entitled to take the AAAA answer down with it.

The gateway built `http://2606:4700::1111:80/`, which is not a URL — the
address's own colons are indistinguishable from the port separator, so
fetch threw and every v6 name 504'd as "the origin could not be reached".
`checkTarget` now returns the origin with the host bracketed.

Targets are validated when they are written rather than only when they
are fetched, and IPv4 literals are refused: an A record on a small host
is usually leased or NATed, and a name pointed at one goes stale without
telling anyone. Hostnames still work. Storing an unroutable address now
fails at the form instead of minting a name that 502s for every visitor.

Also adds the instructions to the page the field is on, with the Caddy
and nginx blocks — including the `http://` Caddy needs, since no public
CA will issue for an ending that is not in the DNS root.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: ralyodio

apps/pwa/src/lib/moshpit-gateway.mjs

@@ -104,6 +104,67 @@ export function parseTarget(target) {
   return { host: raw, port: 80 };
 }
 
+/** A hostname target: dotted, and every label a legal DNS label. */
+const HOSTNAME = /^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$/i;
+
+/**
+ * Bracket an IPv6 host so it can go in a URL.
+ *
+ * `http://2606:4700::1111:80/` is not a URL — the colons in the address are
+ * indistinguishable from the port separator, and `new URL` rejects it. Every
+ * place that turns a target back into a URL has to go through here.
+ */
+export function urlHost(host) {
+  return isIP(host) === 6 ? `[${host}]` : host;
+}
+
+/** The origin URL to fetch, with an IPv6 host bracketed. */
+export function originUrl({ host, port }) {
+  return `http://${urlHost(host)}:${port}`;
+}
+
+/**
+ * Validate what an owner typed into "points at", and return the form to store.
+ *
+ * IP literals must be IPv6. An A record is a commitment to an address that a
+ * name's owner usually does not own for long — IPv4 on a small host is leased,
+ * NATed, or shared, and a name pointed at one goes stale silently. Every host
+ * worth pointing a Moshpit name at has a stable /64 to spare, so the registry
+ * asks for the address that will still be theirs next month. Hostnames stay
+ * allowed: the address behind them is someone else's problem to keep current.
+ *
+ * Empty is not an error. A name with no target is a name waiting to be pointed,
+ * which is the state every name starts in and a state owners return it to.
+ */
+export function normalizeTarget(input) {
+  const raw = String(input ?? "").trim();
+  if (!raw) return { ok: true, target: null };
+
+  const parsed = parseTarget(raw);
+  if (!parsed) return { ok: false, error: "not a usable target" };
+
+  const version = isIP(parsed.host);
+  if (version === 4) {
+    return {
+      ok: false,
+      error: "IPv4 addresses are not accepted — point the name at an IPv6 address, or at a hostname",
+    };
+  }
+
+  if (version === 6) {
+    const why = blockedReason(parsed.host);
+    if (why) return { ok: false, error: `that address is ${why} — a target has to be reachable from the public internet` };
+    // Stored bare when it is just an address, so anything reading the column
+    // gets something it can use as an address without unwrapping it first.
+    // Brackets appear only when a port forces them to.
+    return { ok: true, target: parsed.port === 80 ? parsed.host.toLowerCase() : `[${parsed.host.toLowerCase()}]:${parsed.port}` };
+  }
+
+  if (!HOSTNAME.test(parsed.host)) return { ok: false, error: "not a usable target" };
+  const host = parsed.host.toLowerCase();
+  return { ok: true, target: parsed.port === 80 ? host : `${host}:${parsed.port}` };
+}
+
 /**
  * Is this target safe to fetch, and at what address?
  *
@@ -118,7 +179,7 @@ export async function checkTarget(target, { resolve = dns.lookup } = {}) {
     const why = blockedReason(parsed.host);
     return why
       ? { ok: false, error: `target is ${why}` }
-      : { ok: true, host: parsed.host, port: parsed.port, addresses: [parsed.host] };
+      : { ok: true, host: parsed.host, port: parsed.port, origin: originUrl(parsed), addresses: [parsed.host] };
   }
 
   let addresses;
@@ -133,7 +194,13 @@ export async function checkTarget(target, { resolve = dns.lookup } = {}) {
     const why = blockedReason(address);
     if (why) return { ok: false, error: `target resolves to ${why}` };
   }
-  return { ok: true, host: parsed.host, port: parsed.port, addresses: addresses.map((a) => a.address) };
+  return {
+    ok: true,
+    host: parsed.host,
+    port: parsed.port,
+    origin: originUrl(parsed),
+    addresses: addresses.map((a) => a.address),
+  };
 }
 
 /** Headers worth passing to the origin. Everything else is dropped. */

apps/pwa/src/moshpit.mjs

@@ -11,6 +11,7 @@
 // checkable rather than trusted.
 
 import { db, get, all, run } from "./db.mjs";
+import { normalizeTarget } from "./lib/moshpit-gateway.mjs";
 import {
   BULK_CHUNK,
   BULK_TIME_BUDGET_MS,
@@ -325,9 +326,15 @@ export async function registerName({ tld: tldInput, label: labelInput, userId, t
   if (!owner) return { ok: false, error: `.${tld} is not registered` };
   if (owner.user_id !== userId) return { ok: false, error: `you do not own .${tld}` };
 
+  // Checked on the way in, not only on the way out. A target that fails is a
+  // name that looks minted and serves nothing, and the owner finds out from a
+  // visitor rather than from the form they typed it into.
+  const dest = normalizeTarget(target);
+  if (!dest.ok) return { ok: false, error: dest.error };
+
   try {
     await run(`INSERT INTO moshpit_names (tld, label, user_id, target, created_at) VALUES (?,?,?,?,?)`,
-      [tld, label, userId, target || null, Date.now()]);
+      [tld, label, userId, dest.target, Date.now()]);
   } catch {
     const existing = await getName(tld, label);
     if (existing) return { ok: false, error: `${label}.${tld} is already registered`, taken: true };
@@ -342,8 +349,10 @@ export async function registerName({ tld: tldInput, label: labelInput, userId, t
 export async function setNameTarget({ tld: tldInput, label: labelInput, userId, target }) {
   const owned = await ownedName(tldInput, labelInput, userId);
   if (!owned.ok) return owned;
+  const dest = normalizeTarget(target);
+  if (!dest.ok) return { ok: false, error: dest.error };
   await run(`UPDATE moshpit_names SET target = ? WHERE tld = ? AND label = ?`,
-    [target || null, owned.tld, owned.label]);
+    [dest.target, owned.tld, owned.label]);
   await logAction(owned.tld, userId, `retarget:${owned.label}`);
   return { ok: true };
 }

apps/pwa/src/routes/moshpit.mjs

@@ -470,7 +470,7 @@ async function proxyToOrigin(req, res, resolution, check) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), ORIGIN_TIMEOUT_MS);
   try {
-    const upstream = await fetch(`http://${check.host}:${check.port}${req.originalUrl.replace(/^\/n\/[^/?]+/, "") || "/"}`, {
+    const upstream = await fetch(`${check.origin}${req.originalUrl.replace(/^\/n\/[^/?]+/, "") || "/"}`, {
       headers: forwardableHeaders(req.headers, resolution.resolved),
       redirect: "manual",
       signal: controller.signal,
@@ -1030,7 +1030,7 @@ const landingCard = (req, landing) => {
         ${csrfInput(req)}
         <input type="hidden" name="label" value="${esc(landing.label)}">
         <span class="mono acid">${esc(landing.name)}</span>
-        <input name="target" placeholder="points at… (optional)" autocomplete="off">
+        <input name="target" placeholder="points at… (IPv6 or hostname, optional)" autocomplete="off">
         <button class="btn acid" type="submit">Register it</button>
       </form>
     </div>`;
@@ -1332,6 +1332,51 @@ const pager = ({ page, total, perPage, href }) => {
   </nav>`;
 };
 
+/**
+ * What to put in "points at", and what has to be listening at the other end.
+ *
+ * This sits next to the field rather than on a docs page because the field is
+ * a bare text input whose one hint is a placeholder, and the thing it wants —
+ * an address that a web server is already virtual-hosting the name on — is not
+ * guessable from "points at…". Collapsed by default: the answer is three lines
+ * once you know it, and this list is only in the way afterwards.
+ */
+function hostingHelp() {
+  return `<details class="pit-bulk">
+  <summary>how do I host a site at a name I hold?</summary>
+  <ol class="pit-steps dim">
+    <li><strong>Put your server's IPv6 address in "points at".</strong> Just the address —
+      <code>2606:4700:4700::1111</code>. IPv4 literals are refused: an A record on a small host
+      is usually leased or NATed and goes stale without telling anyone. A hostname
+      (<code>box.example.com</code>) works too.</li>
+    <li><strong>Turn the resolver on, on any machine that should reach the name:</strong>
+      <code>sudo moshcode dns enable</code>. Moshpit endings are not in the public DNS root, so
+      nothing resolves them until this is running — it answers <code>AAAA</code> for your names
+      out of the registry and leaves every other lookup alone.</li>
+    <li><strong>Serve the name on that address, port 80.</strong> The browser connects straight to
+      your box and sends <code>Host: name.ending</code> — nothing proxies, nothing redirects, so
+      your web server needs a block that answers to the name.</li>
+  </ol>
+  <p class="pit-copy" style="font-size:.84rem">Caddy — the <code>http://</code> is required, not a
+    typo: no public CA will issue a certificate for an ending that is not in the DNS root, so
+    automatic HTTPS has to stay off.</p>
+  <div class="pit-pre">http://seo.rank {
+    root * /var/www/seo.rank
+    file_server
+}</div>
+  <p class="pit-copy" style="font-size:.84rem">nginx:</p>
+  <div class="pit-pre">server {
+    listen [::]:80;
+    server_name seo.rank;
+    root /var/www/seo.rank;
+}</div>
+  <p class="pit-copy" style="font-size:.84rem">Check it with <code>moshcode dns resolve seo.rank</code>,
+    then <code>curl -6 http://seo.rank/</code>. A port other than 80 only works in the
+    <code>/n/</code> view — DNS carries an address and has nowhere to put a port, so the browser
+    goes to 80 whatever the target says.</p>
+</details>`;
+}
+
 moshpitRouter.get("/pit", async (req, res) => {
   // An unknown ?tab= falls back to Yours rather than rendering an empty page.
   const tab = req.query.tab === "theirs" ? "theirs" : "yours";
@@ -1424,7 +1469,7 @@ moshpitRouter.get("/pit", async (req, res) => {
                   ${csrfInput(req)}
                   <input type="hidden" name="label" value="${esc(n.label)}">
                   <span class="mono acid">${esc(n.label)}.${esc(t.tld)}</span>
-                  <input name="target" placeholder="points at…" value="${esc(n.target || "")}" autocomplete="off">
+                  <input name="target" placeholder="points at… (IPv6 or hostname)" value="${esc(n.target || "")}" autocomplete="off">
                   <button class="btn" type="submit" name="retarget" value="1">Save</button>
                   <button class="btn" type="submit" name="release" value="1">Release</button>
                 </form>`).join("")
@@ -1439,7 +1484,7 @@ moshpitRouter.get("/pit", async (req, res) => {
               ${csrfInput(req)}
               <input name="label" placeholder="new name" autocomplete="off" required>
               <span class="mono faint">.${esc(t.tld)}</span>
-              <input name="target" placeholder="points at… (optional)" autocomplete="off">
+              <input name="target" placeholder="points at… (IPv6 or hostname, optional)" autocomplete="off">
               <button class="btn acid" type="submit">Add name</button>
             </form>
           </div>
@@ -1526,6 +1571,7 @@ moshpitRouter.get("/pit", async (req, res) => {
       Endings you hold. Names under them are yours to mint for nothing — or put a price on the
       ending and let anyone buy one.
     </p>`}
+    ${hostingHelp()}
     ${mineHtml}
     ${focused ? "" : pager({
       page: pageNo, total: mineTotal, perPage: TLDS_PER_PAGE,

apps/pwa/test/moshpit-api-key.test.mjs

@@ -142,11 +142,19 @@ test("api key: names can be minted and pointed from a script", skip, async () =>
   const { one } = await app();
   assert.equal((await one("POST", "/api/moshpit/tlds/held/names", { label: "blue" })).status, 201);
 
-  const pointed = await one("PUT", "/api/moshpit/tlds/held/names", { label: "blue", target: "203.0.113.7" });
+  const pointed = await one("PUT", "/api/moshpit/tlds/held/names", {
+    label: "blue", target: "2606:4700:4700::1111",
+  });
   assert.equal(pointed.status, 200, pointed.text);
 
   const resolved = await one("GET", "/api/moshpit/resolve?name=blue.held");
-  assert.equal(resolved.json.target, "203.0.113.7");
+  assert.equal(resolved.json.target, "2606:4700:4700::1111");
+
+  // The IPv6 rule holds for scripts too, or the API becomes the way around it.
+  const v4 = await one("PUT", "/api/moshpit/tlds/held/names", { label: "blue", target: "198.51.100.7" });
+  assert.equal(v4.status, 400, v4.text);
+  const still = await one("GET", "/api/moshpit/resolve?name=blue.held");
+  assert.equal(still.json.target, "2606:4700:4700::1111", "a refused target left the old one alone");
 });
 
 test("api key: the browser routes are still browser routes", skip, async () => {

apps/pwa/test/moshpit-gateway.test.mjs

@@ -8,7 +8,7 @@ import assert from "node:assert/strict";
 import test from "node:test";
 
 import {
-  blockedReason, checkTarget, forwardableHeaders, parseTarget,
+  blockedReason, checkTarget, forwardableHeaders, normalizeTarget, originUrl, parseTarget, urlHost,
 } from "../src/lib/moshpit-gateway.mjs";
 
 test("addresses that must never be fetched", () => {
@@ -92,7 +92,13 @@ test("one bad address among good ones fails the whole target", async () => {
 test("a public hostname passes and reports where it went", async () => {
   const resolve = async () => [{ address: "93.184.216.34" }];
   const result = await checkTarget("example.com:8080", { resolve });
-  assert.deepEqual(result, { ok: true, host: "example.com", port: 8080, addresses: ["93.184.216.34"] });
+  assert.deepEqual(result, {
+    ok: true,
+    host: "example.com",
+    port: 8080,
+    origin: "http://example.com:8080",
+    addresses: ["93.184.216.34"],
+  });
 });
 
 test("a name that does not resolve is refused", async () => {
@@ -122,3 +128,53 @@ test("credentials are never forwarded to an origin", () => {
   assert.equal(headers.host, "blue.eggs");
   assert.equal(headers["x-moshpit-name"], "blue.eggs");
 });
+
+/* --------------------------------------------------------- what may be stored */
+
+test("an IPv6 target survives the round trip into a fetchable URL", async () => {
+  // The bug this pins: `http://2606:4700::1111:80/` is not a URL. Unbracketed,
+  // the address's own colons are indistinguishable from the port separator, so
+  // fetch rejected it and every IPv6 name 504'd with "could not be reached".
+  const stored = normalizeTarget("2606:4700:4700::1111");
+  assert.equal(stored.target, "2606:4700:4700::1111");
+
+  const result = await checkTarget(stored.target);
+  assert.equal(result.ok, true);
+  assert.equal(result.origin, "http://[2606:4700:4700::1111]:80");
+  assert.doesNotThrow(() => new URL(`${result.origin}/`));
+  assert.equal(urlHost("203.0.114.9"), "203.0.114.9");
+  assert.equal(originUrl({ host: "box.example.com", port: 8080 }), "http://box.example.com:8080");
+});
+
+test("IPv4 literals are refused, and the message says what to use instead", () => {
+  const result = normalizeTarget("203.0.114.9");
+  assert.equal(result.ok, false);
+  assert.match(result.error, /IPv6/);
+});
+
+test("empty is not an error — a name may wait to be pointed", () => {
+  for (const empty of ["", "   ", null, undefined]) {
+    assert.deepEqual(normalizeTarget(empty), { ok: true, target: null });
+  }
+});
+
+test("a port forces brackets, and only then", () => {
+  assert.equal(normalizeTarget("2606:4700::1111").target, "2606:4700::1111");
+  assert.equal(normalizeTarget("[2606:4700::1111]:8080").target, "[2606:4700::1111]:8080");
+  assert.equal(normalizeTarget("http://[2606:4700::1111]:8080/").target, "[2606:4700::1111]:8080");
+});
+
+test("hostnames stay allowed, lowercased, scheme stripped", () => {
+  assert.equal(normalizeTarget("https://Box.Example.COM/").target, "box.example.com");
+  assert.equal(normalizeTarget("box.example.com:8443").target, "box.example.com:8443");
+  assert.equal(normalizeTarget("not a hostname").ok, false);
+  // A bare label has no dot, so it cannot be a public name.
+  assert.equal(normalizeTarget("localhost").ok, false);
+});
+
+test("an unroutable IPv6 address is refused at the form, not at fetch time", () => {
+  // Storing it would mint a name that looks live and 502s for every visitor.
+  for (const addr of ["::1", "fe80::1", "fd00::1", "ff02::1"]) {
+    assert.equal(normalizeTarget(addr).ok, false, addr);
+  }
+});

apps/pwa/test/moshpit-registry.test.mjs

@@ -144,7 +144,7 @@ test("moshpit registry", { skip: installed ? false : "pwa dependencies not insta
     const r = await m.registerName({ tld: "eggs", label: "Blue", userId: ALICE, target: "https://example.com" });
     assert.equal(r.ok, true);
     assert.equal(r.name.label, "blue");
-    assert.equal(r.name.target, "https://example.com");
+    assert.equal(r.name.target, "example.com");
     assert.deepEqual((await m.listNames("eggs")).map((n) => n.label), ["blue"]);
   });
 
@@ -178,7 +178,7 @@ test("moshpit registry", { skip: installed ? false : "pwa dependencies not insta
     const r = await m.resolveMoshpitName("blue.eggs");
     assert.equal(r.registered, true, "the TLD is claimed");
     assert.equal(r.name_registered, true);
-    assert.equal(r.target, "https://example.com");
+    assert.equal(r.target, "example.com");
   });
 
   await t.test("an unminted name under a claimed TLD is not registered", async () => {
@@ -196,7 +196,7 @@ test("moshpit registry", { skip: installed ? false : "pwa dependencies not insta
     const viaAlias = await m.resolveMoshpitName("foo.agentic");
     assert.equal(viaAlias.resolved, "foo.agents");
     assert.equal(viaAlias.name_registered, true);
-    assert.equal(viaAlias.target, "https://foo.example");
+    assert.equal(viaAlias.target, "foo.example");
     await m.clearAlias("agentic", ALICE);
   });
 
@@ -205,7 +205,7 @@ test("moshpit registry", { skip: installed ? false : "pwa dependencies not insta
     assert.equal((await m.releaseName({ tld: "eggs", label: "blue", userId: BOB })).ok, false);
 
     assert.equal((await m.setNameTarget({ tld: "eggs", label: "blue", userId: ALICE, target: "https://new.example" })).ok, true);
-    assert.equal((await m.getName("eggs", "blue")).target, "https://new.example");
+    assert.equal((await m.getName("eggs", "blue")).target, "new.example");
 
     assert.equal((await m.releaseName({ tld: "eggs", label: "blue", userId: ALICE })).ok, true);
     assert.equal(await m.getName("eggs", "blue"), null);
@@ -215,10 +215,10 @@ test("moshpit registry", { skip: installed ? false : "pwa dependencies not insta
     // A TLD may not be all-numeric (ambiguous against an IPv4 literal), but a
     // label under one carries no such ambiguity -- 123.eggs is a fine name.
     assert.equal((await m.registerName({ tld: "eggs", label: "123", userId: ALICE, target: "https://n.example" })).ok, true);
-    assert.equal((await m.getName("eggs", "123")).target, "https://n.example");
+    assert.equal((await m.getName("eggs", "123")).target, "n.example");
 
     assert.equal((await m.setNameTarget({ tld: "eggs", label: "123", userId: ALICE, target: "https://n2.example" })).ok, true);
-    assert.equal((await m.getName("eggs", "123")).target, "https://n2.example");
+    assert.equal((await m.getName("eggs", "123")).target, "n2.example");
 
     assert.equal((await m.resolveMoshpitName("123.eggs")).name_registered, true);