rootcard 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this package are recorded here.
 
 ## Unreleased
 
+## 0.2.1 - 2026-11-05
+
+- **Fixed:** `keytool.html` 0.2.0 refused every host address ("not a host base URL"), because the page did not include
+  `checkBaseUrl` and `API_VERSION`. A test now checks that the page has every function the package exports.
+- **Fixed (loss of the recovery key):** the key tool page sent a recovery key rotation before it downloaded the new
+  card, and registered at a host before it downloaded the card. Both cards are now downloaded and shown first; if a
+  rotation cannot be sent, the page says to keep both cards.
+
 ## 0.2.0 - 2026-11-05
 
 - License: MIT OR Apache-2.0, at the user's option (0.1.0 was MIT only). The package now ships `LICENSE-MIT` and

package/keytool.html

@@ -110,7 +110,7 @@
 <script>
 "use strict";
 (() => {
-const ROOTCARD_VERSION = "0.2.0";
+const ROOTCARD_VERSION = "0.2.1";
 const __modules = {};
 __modules["errors.js"] = (() => {
 // Error codes (SPEC §20).
@@ -936,59 +936,6 @@ function versionRef(v) {
 
 return { formatKey, parseKey, object, version, members, get, string, int, intIn, bool, member, array, bytes, key, sig, account, checkAccountId, versionRef };
 })();
-__modules["recovery.js"] = (() => {
-// The recovery key (SPEC §6).
-
-const { fail } = __modules["errors.js"];
-const { B32, base32Decode, base32Encode, base32Normalize, bytesEqual } = __modules["encoding.js"];
-const { ed25519Public, frame, frameObject, hkdf, sha256 } = __modules["crypto.js"];
-const { label } = __modules["labels.js"];
-
-async function checksum(key) {
-  return base32Encode(await sha256(frame(label("recovery/check"), key))).slice(0, 4);
-}
-
-/** The written form `RCR-XXXX-…-CCCC` ([RK-1]). */
-async function formatRecoveryKey(key) {
-  const body = base32Encode(key) + (await checksum(key));
-  const groups = [];
-  for (let i = 0; i < 14; i++) groups.push(body.slice(4 * i, 4 * i + 4));
-  return "RCR-" + groups.join("-");
-}
-
-/** Parse a typed recovery key ([RK-2]). → bad_base32, bad_checksum */
-async function parseRecoveryKey(text) {
-  let s = [...text].filter((c) => c !== "-" && c !== " ").join("");
-  if ([...s].length === 59 && s.slice(0, 3).toUpperCase() === "RCR") s = s.slice(3);
-  if (s.length !== 56 || !/^[\x00-\x7f]*$/.test(s)) fail("bad_base32");
-  const n = base32Normalize(s);
-  for (const c of n) if (!B32.includes(c)) fail("bad_base32");
-  const key = base32Decode(n.slice(0, 52), 32);
-  if (n.slice(52) !== (await checksum(key))) fail("bad_checksum");
-  return key;
-}
-
-/**
- * Derive an identity's recovery keys ([RK-4]): `signSeed` (Ed25519) and `boxSecret` (X25519).
- * @returns {Promise<{ signSeed: Uint8Array, boxSecret: Uint8Array }>}
- */
-async function deriveRecoveryKeys(rk, realm, username) {
-  const ctx = { realm, username };
-  return {
-    signSeed: await hkdf(rk, new Uint8Array(0), frameObject(label("recovery/sign"), ctx)),
-    boxSecret: await hkdf(rk, new Uint8Array(0), frameObject(label("recovery/box"), ctx)),
-  };
-}
-
-/** The public recovery signing key. */
-async function recoverySignPublic(keys) {
-  return ed25519Public(keys.signSeed);
-}
-
-
-
-return { bytesEqual, formatRecoveryKey, parseRecoveryKey, deriveRecoveryKeys, recoverySignPublic };
-})();
 __modules["id.js"] = (() => {
 // Realm, username, inception, account id (SPEC §7), handles and tags (SPEC §8).
 
@@ -1420,6 +1367,112 @@ function hashBytes(h) {
 
 return { MAX_EVENTS, EVENT_LIMIT, FUTURE_WINDOW, eventMessage, receiptMessage, eventHash, checkUrl, verifyLog, extendLog, verifyPending, compareLogs, unsignedEvent, signEvent, addReceipt, checkRecoveryKey, pendingInstance, rotateRecoveryEvent, retireEvent, hashBytes };
 })();
+__modules["binding.js"] = (() => {
+// The HTTP binding's version and base URLs (HOST_PROTOCOL.md §1, §1.3; SPEC [HST-22]). The core makes no requests;
+// these let hosts, clients and the key tool agree on where endpoints live. Mirrors `rootcard::binding`.
+
+const { fail } = __modules["errors.js"];
+const { checkUrl } = __modules["log.js"];
+
+/**
+ * The version segment of the HTTP binding: every endpoint is under `<base URL>/v0` until 1.0.0, then under `/v1`.
+ * It is never part of a base URL, `home.url` or anything signed.
+ */
+const API_VERSION = "v0";
+
+/** Whether a path segment has the form of an API version (`v0`, `V12`). */
+function isVersionSegment(segment) {
+  return /^[vV][0-9]+$/.test(segment);
+}
+
+function authorityHost(rest) {
+  const authority = rest.split("/")[0];
+  if (authority.startsWith("[")) {
+    const i = authority.indexOf("]");
+    return i < 0 ? "" : authority.slice(0, i + 1);
+  }
+  return authority.split(":")[0];
+}
+
+/**
+ * Check a base URL ([HST-22]): `https://` and a host, an optional port and an optional path without a trailing slash,
+ * query, fragment or user info; plain `http://` only for `localhost`, `127.0.0.1` and `[::1]`; and its last path
+ * segment is not an API version segment. → `bad_field`
+ */
+function checkBaseUrl(url) {
+  checkUrl(url);
+  let rest;
+  if (url.startsWith("https://")) rest = url.slice(8);
+  else if (url.startsWith("http://")) {
+    rest = url.slice(7);
+    if (!["localhost", "127.0.0.1", "[::1]"].includes(authorityHost(rest))) fail("bad_field");
+  } else fail("bad_field");
+  if (/[?#@\\]/.test(rest)) fail("bad_field");
+  const slash = rest.indexOf("/");
+  const authority = slash < 0 ? rest : rest.slice(0, slash);
+  if (authorityHost(authority) === "" || !/^[A-Za-z0-9.\-:[\]]+$/.test(authority)) fail("bad_field");
+  if (slash >= 0) {
+    const segments = rest.slice(slash + 1).split("/");
+    if (segments.some((x) => x === "")) fail("bad_field");
+    if (isVersionSegment(segments[segments.length - 1])) fail("bad_field");
+  }
+}
+
+return { API_VERSION, isVersionSegment, checkBaseUrl };
+})();
+__modules["recovery.js"] = (() => {
+// The recovery key (SPEC §6).
+
+const { fail } = __modules["errors.js"];
+const { B32, base32Decode, base32Encode, base32Normalize, bytesEqual } = __modules["encoding.js"];
+const { ed25519Public, frame, frameObject, hkdf, sha256 } = __modules["crypto.js"];
+const { label } = __modules["labels.js"];
+
+async function checksum(key) {
+  return base32Encode(await sha256(frame(label("recovery/check"), key))).slice(0, 4);
+}
+
+/** The written form `RCR-XXXX-…-CCCC` ([RK-1]). */
+async function formatRecoveryKey(key) {
+  const body = base32Encode(key) + (await checksum(key));
+  const groups = [];
+  for (let i = 0; i < 14; i++) groups.push(body.slice(4 * i, 4 * i + 4));
+  return "RCR-" + groups.join("-");
+}
+
+/** Parse a typed recovery key ([RK-2]). → bad_base32, bad_checksum */
+async function parseRecoveryKey(text) {
+  let s = [...text].filter((c) => c !== "-" && c !== " ").join("");
+  if ([...s].length === 59 && s.slice(0, 3).toUpperCase() === "RCR") s = s.slice(3);
+  if (s.length !== 56 || !/^[\x00-\x7f]*$/.test(s)) fail("bad_base32");
+  const n = base32Normalize(s);
+  for (const c of n) if (!B32.includes(c)) fail("bad_base32");
+  const key = base32Decode(n.slice(0, 52), 32);
+  if (n.slice(52) !== (await checksum(key))) fail("bad_checksum");
+  return key;
+}
+
+/**
+ * Derive an identity's recovery keys ([RK-4]): `signSeed` (Ed25519) and `boxSecret` (X25519).
+ * @returns {Promise<{ signSeed: Uint8Array, boxSecret: Uint8Array }>}
+ */
+async function deriveRecoveryKeys(rk, realm, username) {
+  const ctx = { realm, username };
+  return {
+    signSeed: await hkdf(rk, new Uint8Array(0), frameObject(label("recovery/sign"), ctx)),
+    boxSecret: await hkdf(rk, new Uint8Array(0), frameObject(label("recovery/box"), ctx)),
+  };
+}
+
+/** The public recovery signing key. */
+async function recoverySignPublic(keys) {
+  return ed25519Public(keys.signSeed);
+}
+
+
+
+return { bytesEqual, formatRecoveryKey, parseRecoveryKey, deriveRecoveryKeys, recoverySignPublic };
+})();
 __modules["vaultcheck.js"] = (() => {
 // The vault's structure and signatures (SPEC §11), without any decryption: what hosts need ([VLT-3], [VLT-4]).
 
@@ -2770,8 +2823,8 @@ return { testRandom, systemRandom };
 // user enters ([KT-1]) and gathers the newest log before signing anything ([KT-2]).
 
 const rc = { ...__modules["index.js"] };
-for (const name of ["errors.js", "json.js", "encoding.js", "labels.js", "crypto.js", "keys.js", "recovery.js", "id.js", "log.js",
-  "vaultcheck.js", "profile.js", "messages.js", "proof.js", "file.js", "vault.js", "account.js", "testing.js"]) {
+for (const name of ["errors.js", "json.js", "encoding.js", "labels.js", "binding.js", "crypto.js", "keys.js", "recovery.js", "id.js", "log.js",
+  "vaultcheck.js", "profile.js", "messages.js", "proof.js", "file.js", "argon2.js", "vault.js", "account.js", "testing.js"]) {
   Object.assign(rc, __modules[name]);
 }
 const $ = (id) => document.getElementById(id);
@@ -3034,10 +3087,21 @@ const ops = {
     const { vault, u } = await currentVault();
     const newKey = random(32);
     const r = await rc.rotateRecovery(current.state, current.log, current.keys, newKey, vault, u, now(), random);
-    await http("POST", `${apiRoot(current.state.instance.home.url)}/id/${current.state.account}/events`, { events: [r.event], vault: r.vault });
+    newKey.fill(0);
+    // The new card is saved and shown before the rotation is sent: once the host has the event, the old key no longer
+    // signs and the new card is the only copy of the new key ([KT-5]).
     download(`${current.state.username}-new.card.json`, r.card);
     const text = await rc.cardText(r.card);
-    newKey.fill(0);
+    show(text + "\nSending the rotation… Keep this card.", true);
+    try {
+      await http("POST", `${apiRoot(current.state.instance.home.url)}/id/${current.state.account}/events`, { events: [r.event], vault: r.vault });
+    } catch (e) {
+      throw new Error(
+        `${explain(e)}\n\nThe rotation may or may not have reached the primary host. Keep both cards: the new card ` +
+          `below (also downloaded) and the old one. Load the identity with the old card: if it answers that the ` +
+          `recovery key is not the current one, the rotation arrived and the new card is current.\n\n${text}`,
+      );
+    }
     current = null;
     $("actions").hidden = true;
     return text + "\nThe new card was downloaded. Destroy the old card, then load the new one.";
@@ -3089,6 +3153,10 @@ $("create").addEventListener("click", () =>
     if (base) {
       const home = await hostHome(checkHost(base));
       const reg = await rc.register(rk, realm, username, $("nPassword").value, "Password", home, now(), rc.KDF_DEFAULT, random);
+      rk.fill(0);
+      // The card is saved before anything is sent: once the host has the identity, the card is the only copy of its
+      // recovery key ([CLT-1]).
+      download(`${username}-${rc.tag(reg.account)}.card.json`, reg.card);
       await http("POST", `${apiRoot(home.url)}/id/register`, { log: reg.log, vault: reg.vault, public: reg.public });
       const v = await http("GET", `${apiRoot(home.url)}/id/${reg.account}/log`);
       state = await rc.verifyLog(v.events, { realms: [realm], now: now() });
@@ -3102,7 +3170,7 @@ $("create").addEventListener("click", () =>
       file = rc.exportAccount(state, [inc]);
     }
     rk.fill(0);
-    download(`${username}-${rc.tag(state.account)}.card.json`, card);
+    if (!base) download(`${username}-${rc.tag(state.account)}.card.json`, card);
     download(rc.accountFileName(state), file);
     return (await rc.cardText(card)) + "\n" + describe(state) + "\n\nThe card and the account file were downloaded. Keep the card offline.";
   }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rootcard",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "A portable, self-certifying identity for online logins (core library, zero dependencies, WebCrypto)",
   "keywords": [
     "identity",