rootcard 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -4,6 +4,24 @@ 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
+  `LICENSE-APACHE`.
+- **Breaking (HTTP binding):** `keytool.html` calls hosts under `<base URL>/v0` (HOST_PROTOCOL.md §1.3). The core
+  library makes no requests and is unchanged.
+- `API_VERSION` (`"v0"`), `checkBaseUrl` and `isVersionSegment`, equal to the Rust crate's ([HST-22], shared vectors).
+- `keytool.html` checks every host address as a base URL; a trailing slash is still removed from typed addresses.
+- README points to the project README.
+
 ## 0.1.0 - 2026-11-04
 
 - First release of the JavaScript implementation of format version 1, byte for byte equal to the Rust crate on every

package/LICENSE-APACHE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -4,6 +4,10 @@
 logins. Zero dependencies, no build step, WebCrypto only; runs in browsers and Node 20 or later. It produces and checks
 exactly the bytes of the Rust crate `rootcard`; both are tested against the shared vectors of the specification.
 
+> **New to rootcard?** Start with the [project README](https://github.com/Hexagon/rootcard#readme): what rootcard is,
+> the two ways to use it (a safer username-and-password login for your own service, or an ID card across services),
+> how it compares with other login methods, and the roadmap.
+
 ```js
 import { verifyLog, verifyProof } from "rootcard";             // verification: hosts, relying parties, clients
 import { register, unlockVault, changePassword } from "rootcard/vault"; // passwords, Argon2id, vault encryption
@@ -22,3 +26,14 @@ const state = await verifyLog(events, { realms: ["global"], now: Math.floor(Date
 
 Functions that need randomness take `random(n)`; pass `systemRandom` (WebCrypto `getRandomValues`). Errors are
 `RootcardError` with the stable `code` of SPEC §20.
+
+## HTTP binding
+
+The core makes no requests. Application clients that talk to a host build URLs as `` `${base}/${API_VERSION}/…` ``
+(`API_VERSION` is `"v0"` until 1.0.0, HOST_PROTOCOL.md §1.3) and check host addresses with `checkBaseUrl` (SPEC
+[HST-22]) before using them or putting them into an instance. `keytool.html` does both; a `keytool.html` from 0.1.0
+does not reach hosts of 0.2.0.
+
+## License
+
+Licensed under either of MIT or Apache-2.0, at your option (`LICENSE-MIT`, `LICENSE-APACHE`).

package/keytool.html

@@ -110,7 +110,7 @@
 <script>
 "use strict";
 (() => {
-const ROOTCARD_VERSION = "0.1.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);
@@ -2835,6 +2888,23 @@ function checkUrl(url) {
   return url.replace(/\/+$/, "");
 }
 
+// A host address as the user typed it: trailing slashes removed, then checked as a base URL ([HST-22]).
+function checkHost(url) {
+  const base = url.replace(/\/+$/, "");
+  try {
+    rc.checkBaseUrl(base);
+  } catch {
+    throw new Error(`${url}: not a host base URL (https://host[:port][/path], without /v0 at the end)`);
+  }
+  return base;
+}
+
+// The API root of a host: every endpoint is under `<base URL>/v0` until 1.0.0 (HOST_PROTOCOL.md §1.3). Base URLs
+// (`home.url`, and `url` in signed messages) never include the version.
+function apiRoot(base) {
+  return `${checkHost(base)}/${rc.API_VERSION}`;
+}
+
 async function http(method, url, body) {
   const res = await fetch(checkUrl(url), {
     method,
@@ -2855,7 +2925,7 @@ async function http(method, url, body) {
 }
 
 function hostList() {
-  return $("hosts").value.split(",").map((s) => s.trim()).filter(Boolean).map(checkUrl);
+  return $("hosts").value.split(",").map((s) => s.trim()).filter(Boolean).map(checkHost);
 }
 
 /** [KT-2]: the newest log from the card, the account file and the hosts; a fork stops. */
@@ -2894,7 +2964,7 @@ async function gather() {
   const notes = [];
   for (const h of [...new Set(hosts)]) {
     try {
-      const v = await http("GET", `${h}/id/${card.account}/log`);
+      const v = await http("GET", `${apiRoot(h)}/id/${card.account}/log`);
       await consider(v.events, h);
     } catch (e) {
       notes.push(`${h}: ${explain(e)}`);
@@ -2928,14 +2998,14 @@ async function currentVault() {
   if (!current.state.instance) throw new Error("No instance found: load the account file or enter the primary host.");
   const base = current.state.instance.home.url;
   const account = current.state.account;
-  const ch = rc.parseChallenge(await http("POST", `${base}/id/${account}/challenge`, { purpose: "fetch" }));
+  const ch = rc.parseChallenge(await http("POST", `${apiRoot(base)}/id/${account}/challenge`, { purpose: "fetch" }));
   const sig = await rc.ed25519Sign(current.keys.signSeed, rc.fetchMessage(account, ch.host, "recovery", ch.nonce, base));
-  const v = await http("POST", `${base}/id/${account}/fetch`, { lock: "recovery", nonce: ch.nonce, url: base, sig: rc.base64urlEncode(sig) });
+  const v = await http("POST", `${apiRoot(base)}/id/${account}/fetch`, { lock: "recovery", nonce: ch.nonce, url: base, sig: rc.base64urlEncode(sig) });
   return { vault: v.vault, u: await rc.unlockVault(v.vault, current.state, { recovery: current.keys }) };
 }
 
 async function hostHome(base) {
-  const d = await http("GET", `${base}/host`);
+  const d = await http("GET", `${apiRoot(base)}/host`);
   rc.parseKey(d.key, "ed25519");
   return { key: d.key, url: base };
 }
@@ -2956,14 +3026,14 @@ async function submitInstance(base, mode, old) {
   }
   const ni = await rc.newInstance(current.state, current.keys, old, publicData, mode, home, now(), random);
   const account = current.state.account;
-  await http("POST", `${base}/id/${account}/instance`, { events: current.log, instance: ni.event, vault: ni.vault, public: ni.public });
-  const v = await http("GET", `${base}/id/${account}/log`);
+  await http("POST", `${apiRoot(base)}/id/${account}/instance`, { events: current.log, instance: ni.event, vault: ni.vault, public: ni.public });
+  const v = await http("GET", `${apiRoot(base)}/id/${account}/log`);
   const state = await rc.verifyLog(v.events, { realms: [current.state.realm], now: now() });
   const oldHome = current.state.instance?.home.url;
   let note = "";
   if (oldHome && oldHome !== base) {
     try {
-      await http("POST", `${oldHome}/id/${account}/events`, { events: v.events.slice(current.log.length) });
+      await http("POST", `${apiRoot(oldHome)}/id/${account}/events`, { events: v.events.slice(current.log.length) });
     } catch (e) {
       note = `\nCould not tell the previous primary host: ${explain(e)}`;
     }
@@ -2989,10 +3059,10 @@ async function challengeOf(text) {
 const ops = {
   async restore() {
     const { u } = await currentVault();
-    return submitInstance(checkUrl($("targetHost").value.trim()), { restore: true }, u);
+    return submitInstance(checkHost($("targetHost").value.trim()), { restore: true }, u);
   },
   async fresh() {
-    return submitInstance(checkUrl($("targetHost").value.trim()), { fresh: newSlot() }, undefined);
+    return submitInstance(checkHost($("targetHost").value.trim()), { fresh: newSlot() }, undefined);
   },
   async reset() {
     const { u } = await currentVault();
@@ -3007,7 +3077,7 @@ const ops = {
   async add() {
     const { vault, u } = await currentVault();
     const v = await rc.addSlot(u, vault, current.keys, newSlot(), random);
-    await http("PUT", `${current.state.instance.home.url}/id/${current.state.account}/vault`, { vault: v });
+    await http("PUT", `${apiRoot(current.state.instance.home.url)}/id/${current.state.account}/vault`, { vault: v });
     current.vault = v;
     const info = await rc.verifyVault(v, current.state);
     refreshSlots(info);
@@ -3017,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", `${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.";
@@ -3030,7 +3111,7 @@ const ops = {
     const ev = await rc.retireEvent(current.state, current.keys.signSeed, now());
     const base = current.state.instance?.home.url ?? hostList()[0];
     if (!base) throw new Error("Enter a host.");
-    await http("POST", `${base}/id/${current.state.account}/events`, { events: [ev] });
+    await http("POST", `${apiRoot(base)}/id/${current.state.account}/events`, { events: [ev] });
     return `${current.state.handle} is retired.`;
   },
   async card() {
@@ -3070,10 +3151,14 @@ $("create").addEventListener("click", () =>
     let file;
     let state;
     if (base) {
-      const home = await hostHome(checkUrl(base));
+      const home = await hostHome(checkHost(base));
       const reg = await rc.register(rk, realm, username, $("nPassword").value, "Password", home, now(), rc.KDF_DEFAULT, random);
-      await http("POST", `${home.url}/id/register`, { log: reg.log, vault: reg.vault, public: reg.public });
-      const v = await http("GET", `${home.url}/id/${reg.account}/log`);
+      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() });
       card = reg.card;
       file = rc.exportAccount(state, v.events, reg.public, reg.vault);
@@ -3085,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.1.0",
+  "version": "0.2.1",
   "description": "A portable, self-certifying identity for online logins (core library, zero dependencies, WebCrypto)",
   "keywords": [
     "identity",
@@ -10,7 +10,7 @@
     "webcrypto",
     "self-certifying"
   ],
-  "license": "MIT",
+  "license": "(MIT OR Apache-2.0)",
   "homepage": "https://github.com/Hexagon/rootcard",
   "repository": {
     "type": "git",
@@ -31,7 +31,8 @@
     "keytool.html",
     "README.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE-MIT",
+    "LICENSE-APACHE"
   ],
   "sideEffects": false,
   "engines": {

package/src/binding.js

@@ -0,0 +1,49 @@
+// 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`.
+
+import { fail } from "./errors.js";
+import { checkUrl } from "./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.
+ */
+export const API_VERSION = "v0";
+
+/** Whether a path segment has the form of an API version (`v0`, `V12`). */
+export 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`
+ */
+export 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");
+  }
+}

package/src/index.js

@@ -7,6 +7,7 @@
 // Status: 0.x. Nothing here is stable before 1.0.0.
 
 export { FORMAT_VERSION, LABEL_PREFIX, label } from "./labels.js";
+export { API_VERSION, checkBaseUrl, isVersionSegment } from "./binding.js";
 export { ERROR_CODES, RootcardError } from "./errors.js";
 export { canonical, canonicalString, parseJson, parseLimited, validate } from "./json.js";
 export {