rootcard 0.0.0 → 0.2.0

package/package.json

@@ -1,21 +1,45 @@
 {
   "name": "rootcard",
-  "version": "0.0.0",
+  "version": "0.2.0",
   "description": "A portable, self-certifying identity for online logins (core library, zero dependencies, WebCrypto)",
-  "keywords": ["identity", "authentication", "login", "ed25519", "webcrypto", "self-certifying"],
-  "license": "MIT",
+  "keywords": [
+    "identity",
+    "authentication",
+    "login",
+    "ed25519",
+    "webcrypto",
+    "self-certifying"
+  ],
+  "license": "(MIT OR Apache-2.0)",
   "homepage": "https://github.com/Hexagon/rootcard",
-  "repository": { "type": "git", "url": "git+https://github.com/Hexagon/rootcard.git", "directory": "packages/rootcard" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hexagon/rootcard.git",
+    "directory": "packages/rootcard"
+  },
   "bugs": "https://github.com/Hexagon/rootcard/issues",
   "type": "module",
   "exports": {
     ".": "./src/index.js",
+    "./vault": "./src/vault-index.js",
+    "./testing": "./src/testing.js",
+    "./keytool.html": "./keytool.html",
     "./package.json": "./package.json"
   },
-  "files": ["src/", "README.md", "CHANGELOG.md", "LICENSE"],
+  "files": [
+    "src/",
+    "keytool.html",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE-MIT",
+    "LICENSE-APACHE"
+  ],
   "sideEffects": false,
-  "engines": { "node": ">=20" },
+  "engines": {
+    "node": ">=20"
+  },
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "build": "node tools/build-keytool.mjs"
   }
 }

package/src/account.js

@@ -0,0 +1,89 @@
+// High-level flows (SPEC §18): registration ([CLT-1]), new instances ([KT-3], [KT-4], [KT-8]) and recovery-key
+// rotation ([KT-5]). The random draws are in the same order as the Rust crate's `account` module.
+
+import { fail } from "./errors.js";
+import { base64urlEncode } from "./encoding.js";
+import { inception } from "./id.js";
+import { checkRecoveryKey, eventHash, pendingInstance, rotateRecoveryEvent, verifyLog } from "./log.js";
+import { signPublic } from "./profile.js";
+import { deriveRecoveryKeys } from "./recovery.js";
+import { recoveryCard } from "./file.js";
+import { carriedLocks, checkPassword, instanceVault, regrant } from "./vault.js";
+
+/**
+ * Build a registration ([CLT-1]) from a recovery key the caller generated ([RK-3]). `home` is `{ key, url }` with
+ * a key string. Draws: the account seed (32), then instanceVault with one new slot.
+ * @returns {Promise<{ log, vault, public, card, account }>}
+ */
+export async function register(recoveryKey, realm, username, password, slotLabel, home, time, kdf, random) {
+  checkPassword(password, username);
+  const keys = await deriveRecoveryKeys(recoveryKey, realm, username);
+  const inc = await inception(keys, realm, username);
+  const state = await verifyLog([inc], { realms: [realm] });
+  const seed = random(32);
+  const pending = await pendingInstance(state, keys.signSeed, seed, home, "register", time);
+  const instance = base64urlEncode(await eventHash(pending));
+  const vault = await instanceVault(
+    {
+      account: state.account,
+      instance,
+      recovery: keys,
+      contents: { accountSeed: seed, data: {} },
+      keep: [],
+      add: { label: slotLabel, password, kdf },
+    },
+    random,
+  );
+  const pub = await signPublic(state.account, instance, 1, {}, seed);
+  const card = await recoveryCard(realm, username, state.account, recoveryKey);
+  seed.fill(0);
+  keys.signSeed.fill(0);
+  keys.boxSecret.fill(0);
+  return { log: [inc, pending], vault, public: pub, card, account: state.account };
+}
+
+/**
+ * Build a new instance on top of `state` ([KT-3]). `mode` is `{ restore: true }`, `{ revoke: [slot ids] }`,
+ * `{ reset: slot }` or `{ fresh: slot }`, where a slot is `{ label, password, kdf }`. `old` is the current vault
+ * unlocked with the recovery lock (not needed for fresh). Draws: the account seed (32), then instanceVault.
+ * @returns {Promise<{ event, vault, public }>}
+ */
+export async function newInstance(state, recovery, old, oldPublicData, mode, home, time, random) {
+  await checkRecoveryKey(state, recovery.signSeed);
+  const seed = random(32);
+  const reason = mode.restore ? "restore" : mode.fresh ? "fresh" : "revoke";
+  const event = await pendingInstance(state, recovery.signSeed, seed, home, reason, time);
+  const instance = base64urlEncode(await eventHash(event));
+  let data = {};
+  let known;
+  let keep = [];
+  let add;
+  let publicData = {};
+  if (!mode.fresh) {
+    if (!old) fail("bad_locks");
+    data = old.contents.data;
+    known = old.contents.known;
+    publicData = oldPublicData ?? {};
+    if (mode.restore) keep = carriedLocks(old, []);
+    else if (mode.revoke) keep = carriedLocks(old, mode.revoke);
+    else add = mode.reset;
+  } else add = mode.fresh;
+  const contents = { accountSeed: seed, data };
+  if (known !== undefined) contents.known = known;
+  const vault = await instanceVault({ account: state.account, instance, recovery, contents, keep, add }, random);
+  const pub = await signPublic(state.account, instance, 1, publicData, seed);
+  seed.fill(0);
+  return { event, vault, public: pub };
+}
+
+/**
+ * Rotate the recovery key ([KT-5]) to `newKey`. `unlocked` is the current vault unlocked. Draws: regrant.
+ * @returns {Promise<{ event, vault, card }>}
+ */
+export async function rotateRecovery(state, log, oldKeys, newKey, oldVault, unlocked, time, random) {
+  const next = await deriveRecoveryKeys(newKey, state.realm, state.username);
+  const event = await rotateRecoveryEvent(state, oldKeys.signSeed, next.signSeed, time);
+  const vault = await regrant(unlocked, oldVault, next, random);
+  const card = await recoveryCard(state.realm, state.username, state.account, newKey, [...log, event]);
+  return { event, vault, card };
+}

package/src/argon2.js

@@ -0,0 +1,239 @@
+// Argon2id, version 0x13 (RFC 9106), the one primitive this package implements itself ([CRY-1]). It supports the
+// general parameters of the RFC (lanes, secret, associated data) so that it can be checked against the RFC vectors;
+// rootcard uses p = 1, no secret and no associated data ([CRY-6]).
+
+import { blake2b } from "./blake2b.js";
+
+function le32(n) {
+  return new Uint8Array([n & 255, (n >>> 8) & 255, (n >>> 16) & 255, (n >>> 24) & 255]);
+}
+
+/** H' (RFC 9106 §3.3): variable-length hash of `parts` to `T` bytes. */
+function hPrime(T, ...parts) {
+  if (T <= 64) return blake2b(T, le32(T), ...parts);
+  const out = new Uint8Array(T);
+  const r = Math.ceil(T / 32) - 2;
+  let v = blake2b(64, le32(T), ...parts);
+  out.set(v.subarray(0, 32), 0);
+  for (let i = 1; i < r; i++) {
+    v = blake2b(64, v);
+    out.set(v.subarray(0, 32), i * 32);
+  }
+  out.set(blake2b(T - 32 * r, v), r * 32);
+  return out;
+}
+
+// Scratch space for the compression function: R (256 words) and Q (256 words).
+const R = new Uint32Array(256);
+const Q = new Uint32Array(256);
+
+// a = a + b + 2 * lo(a) * lo(b) on 64-bit words at word offsets a and b of Q (in u32 units: 2a, 2a+1).
+function fBlaMka(a, b) {
+  const al = Q[a];
+  const bl = Q[b];
+  // 64-bit product of the two low halves.
+  const a1 = al >>> 16;
+  const a0 = al & 0xffff;
+  const b1 = bl >>> 16;
+  const b0 = bl & 0xffff;
+  const p00 = a0 * b0;
+  const mid = a1 * b0 + a0 * b1 + (p00 >>> 16);
+  let ph = a1 * b1 + Math.floor(mid / 65536);
+  let pl = (Math.imul(al, bl) >>> 0);
+  // times two
+  ph = ((ph << 1) | (pl >>> 31)) >>> 0;
+  pl = (pl << 1) >>> 0;
+  // a + b
+  let lo = Q[a] + Q[b];
+  let hi = Q[a + 1] + Q[b + 1] + (lo >= 0x100000000 ? 1 : 0);
+  lo >>>= 0;
+  // + product
+  const lo2 = lo + pl;
+  hi = hi + ph + (lo2 >= 0x100000000 ? 1 : 0);
+  Q[a] = lo2;
+  Q[a + 1] = hi;
+}
+
+function rotr(d, n) {
+  const l = Q[d];
+  const h = Q[d + 1];
+  if (n === 32) {
+    Q[d] = h;
+    Q[d + 1] = l;
+  } else if (n < 32) {
+    Q[d] = (l >>> n) | (h << (32 - n));
+    Q[d + 1] = (h >>> n) | (l << (32 - n));
+  } else {
+    const k = n - 32;
+    Q[d] = (h >>> k) | (l << (32 - k));
+    Q[d + 1] = (l >>> k) | (h << (32 - k));
+  }
+}
+
+function xor(d, a) {
+  Q[d] ^= Q[a];
+  Q[d + 1] ^= Q[a + 1];
+}
+
+// GB on 64-bit words with u32 offsets a, b, c, d into Q.
+function gb(a, b, c, d) {
+  fBlaMka(a, b);
+  xor(d, a);
+  rotr(d, 32);
+  fBlaMka(c, d);
+  xor(b, c);
+  rotr(b, 24);
+  fBlaMka(a, b);
+  xor(d, a);
+  rotr(d, 16);
+  fBlaMka(c, d);
+  xor(b, c);
+  rotr(b, 63);
+}
+
+// P on 16 64-bit words whose u32 offsets are in `w`.
+function p(w) {
+  gb(w[0], w[4], w[8], w[12]);
+  gb(w[1], w[5], w[9], w[13]);
+  gb(w[2], w[6], w[10], w[14]);
+  gb(w[3], w[7], w[11], w[15]);
+  gb(w[0], w[5], w[10], w[15]);
+  gb(w[1], w[6], w[11], w[12]);
+  gb(w[2], w[7], w[8], w[13]);
+  gb(w[3], w[4], w[9], w[14]);
+}
+
+const ROWS = [];
+const COLS = [];
+for (let i = 0; i < 8; i++) {
+  ROWS.push(Array.from({ length: 16 }, (_, k) => 2 * (16 * i + k)));
+  COLS.push(Array.from({ length: 16 }, (_, k) => 2 * (2 * i + 16 * (k >> 1) + (k & 1))));
+}
+
+/**
+ * G(X, Y) of RFC 9106 §3.5 into `out` (all Uint32Array views of 256 words). With `xorOut`, the result is XORed into
+ * the existing contents of `out` (passes after the first, version 0x13).
+ */
+function compress(out, outOff, x, xOff, y, yOff, xorOut) {
+  for (let i = 0; i < 256; i++) R[i] = x[xOff + i] ^ y[yOff + i];
+  Q.set(R);
+  for (let i = 0; i < 8; i++) p(ROWS[i]);
+  for (let i = 0; i < 8; i++) p(COLS[i]);
+  if (xorOut) for (let i = 0; i < 256; i++) out[outOff + i] ^= Q[i] ^ R[i];
+  else for (let i = 0; i < 256; i++) out[outOff + i] = Q[i] ^ R[i];
+}
+
+function blockToWords(bytes, mem, off) {
+  for (let i = 0; i < 256; i++) {
+    mem[off + i] = bytes[4 * i] | (bytes[4 * i + 1] << 8) | (bytes[4 * i + 2] << 16) | (bytes[4 * i + 3] << 24);
+  }
+}
+
+/**
+ * Argon2id (RFC 9106) with a `tagLength`-byte tag. `m` is in KiB.
+ * @param {Uint8Array} password
+ * @param {Uint8Array} salt
+ * @param {{ m: number, t: number, p: number, tagLength?: number, secret?: Uint8Array, ad?: Uint8Array }} params
+ */
+export function argon2id(password, salt, params) {
+  const { m, t, p: lanes } = params;
+  const T = params.tagLength ?? 32;
+  const K = params.secret ?? new Uint8Array(0);
+  const X = params.ad ?? new Uint8Array(0);
+  if (!(lanes >= 1 && t >= 1 && m >= 8 * lanes && T >= 4)) throw new RangeError("argon2id parameters");
+  const h0 = blake2b(
+    64,
+    le32(lanes), le32(T), le32(m), le32(t), le32(0x13), le32(2),
+    le32(password.length), password, le32(salt.length), salt, le32(K.length), K, le32(X.length), X,
+  );
+  const mPrime = 4 * lanes * Math.floor(m / (4 * lanes));
+  const q = mPrime / lanes;
+  const segment = q / 4;
+  const mem = new Uint32Array(mPrime * 256);
+  const at = (lane, col) => (lane * q + col) * 256;
+  for (let l = 0; l < lanes; l++) {
+    blockToWords(hPrime(1024, h0, le32(0), le32(l)), mem, at(l, 0));
+    blockToWords(hPrime(1024, h0, le32(1), le32(l)), mem, at(l, 1));
+  }
+  const zero = new Uint32Array(256);
+  const input = new Uint32Array(256);
+  const address = new Uint32Array(256);
+  for (let pass = 0; pass < t; pass++) {
+    for (let slice = 0; slice < 4; slice++) {
+      for (let lane = 0; lane < lanes; lane++) {
+        const independent = pass === 0 && slice < 2;
+        if (independent) {
+          input.fill(0);
+          input[0] = pass;
+          input[2] = lane;
+          input[4] = slice;
+          input[6] = mPrime;
+          input[8] = t;
+          input[10] = 2;
+          input[12] = 0; // counter
+        }
+        const nextAddresses = () => {
+          input[12]++;
+          address.fill(0);
+          compress(address, 0, zero, 0, input, 0, false);
+          compress(address, 0, zero, 0, address.slice(), 0, false);
+        };
+        let start = 0;
+        if (pass === 0 && slice === 0) {
+          start = 2;
+          if (independent) nextAddresses();
+        }
+        for (let index = start; index < segment; index++) {
+          const col = slice * segment + index;
+          const prevCol = col === 0 ? q - 1 : col - 1;
+          let j1;
+          let j2;
+          if (independent) {
+            if (index % 128 === 0) nextAddresses();
+            const k = 2 * (index % 128);
+            j1 = address[k];
+            j2 = address[k + 1];
+          } else {
+            const o = at(lane, prevCol);
+            j1 = mem[o];
+            j2 = mem[o + 1];
+          }
+          let refLane = j2 % lanes;
+          if (pass === 0 && slice === 0) refLane = lane;
+          const same = refLane === lane;
+          let area;
+          if (pass === 0) {
+            if (slice === 0) area = index - 1;
+            else if (same) area = slice * segment + index - 1;
+            else area = slice * segment + (index === 0 ? -1 : 0);
+          } else if (same) area = q - segment + index - 1;
+          else area = q - segment + (index === 0 ? -1 : 0);
+          // x = j1^2 >> 32; y = area * x >> 32; z = area - 1 - y
+          const x = Number((BigInt(j1) * BigInt(j1)) >> 32n);
+          const y = Number((BigInt(area) * BigInt(x)) >> 32n);
+          const z = area - 1 - y;
+          const startPos = pass === 0 ? 0 : slice === 3 ? 0 : (slice + 1) * segment;
+          const refCol = (startPos + z) % q;
+          compress(mem, at(lane, col), mem, at(lane, prevCol), mem, at(refLane, refCol), pass > 0);
+        }
+      }
+    }
+  }
+  const c = new Uint32Array(256);
+  for (let l = 0; l < lanes; l++) {
+    const o = at(l, q - 1);
+    for (let i = 0; i < 256; i++) c[i] ^= mem[o + i];
+  }
+  const cb = new Uint8Array(1024);
+  for (let i = 0; i < 256; i++) {
+    cb[4 * i] = c[i];
+    cb[4 * i + 1] = c[i] >>> 8;
+    cb[4 * i + 2] = c[i] >>> 16;
+    cb[4 * i + 3] = c[i] >>> 24;
+  }
+  const tag = hPrime(T, cb);
+  mem.fill(0);
+  cb.fill(0);
+  c.fill(0);
+  return tag;
+}

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/blake2b.js

@@ -0,0 +1,120 @@
+// BLAKE2b (RFC 7693), needed only inside Argon2id ([CRY-1]): WebCrypto has neither. 64-bit words are pairs of 32-bit
+// integers (low, high) in a Uint32Array.
+
+const IV = new Uint32Array([
+  0xf3bcc908, 0x6a09e667, 0x84caa73b, 0xbb67ae85, 0xfe94f82b, 0x3c6ef372, 0x5f1d36f1, 0xa54ff53a, 0xade682d1,
+  0x510e527f, 0x2b3e6c1f, 0x9b05688c, 0xfb41bd6b, 0x1f83d9ab, 0x137e2179, 0x5be0cd19,
+]);
+
+const SIGMA = [
+  [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15],
+  [14, 10, 4, 8, 9, 15, 13, 6, 1, 12, 0, 2, 11, 7, 5, 3],
+  [11, 8, 12, 0, 5, 2, 15, 13, 10, 14, 3, 6, 7, 1, 9, 4],
+  [7, 9, 3, 1, 13, 12, 11, 14, 2, 6, 5, 10, 4, 0, 15, 8],
+  [9, 0, 5, 7, 2, 4, 10, 15, 14, 1, 11, 12, 6, 8, 3, 13],
+  [2, 12, 6, 10, 0, 11, 8, 3, 4, 13, 7, 5, 15, 14, 1, 9],
+  [12, 5, 1, 15, 14, 13, 4, 10, 0, 7, 6, 3, 9, 2, 8, 11],
+  [13, 11, 7, 14, 12, 1, 3, 9, 5, 0, 15, 4, 8, 6, 2, 10],
+  [6, 15, 14, 9, 11, 3, 0, 8, 12, 2, 13, 7, 1, 4, 10, 5],
+  [10, 2, 8, 4, 7, 6, 1, 5, 15, 11, 9, 14, 3, 12, 13, 0],
+].map((r) => r.map((x) => x * 2));
+
+const v = new Uint32Array(32);
+const m = new Uint32Array(32);
+
+function add64(a, b) {
+  const lo = v[a] + v[b];
+  let hi = v[a + 1] + v[b + 1];
+  if (lo >= 0x100000000) hi++;
+  v[a] = lo;
+  v[a + 1] = hi;
+}
+
+function add64m(a, i) {
+  const lo = v[a] + m[i];
+  let hi = v[a + 1] + m[i + 1];
+  if (lo >= 0x100000000) hi++;
+  v[a] = lo;
+  v[a + 1] = hi;
+}
+
+function g(a, b, c, d, x, y) {
+  add64(a, b);
+  add64m(a, x);
+  let xl = v[d] ^ v[a];
+  let xh = v[d + 1] ^ v[a + 1];
+  v[d] = xh;
+  v[d + 1] = xl;
+  add64(c, d);
+  xl = v[b] ^ v[c];
+  xh = v[b + 1] ^ v[c + 1];
+  v[b] = (xl >>> 24) ^ (xh << 8);
+  v[b + 1] = (xh >>> 24) ^ (xl << 8);
+  add64(a, b);
+  add64m(a, y);
+  xl = v[d] ^ v[a];
+  xh = v[d + 1] ^ v[a + 1];
+  v[d] = (xl >>> 16) ^ (xh << 16);
+  v[d + 1] = (xh >>> 16) ^ (xl << 16);
+  add64(c, d);
+  xl = v[b] ^ v[c];
+  xh = v[b + 1] ^ v[c + 1];
+  v[b] = (xh >>> 31) ^ (xl << 1);
+  v[b + 1] = (xl >>> 31) ^ (xh << 1);
+}
+
+function compress(h, block, t, last) {
+  for (let i = 0; i < 16; i++) {
+    v[i] = h[i];
+    v[i + 16] = IV[i];
+  }
+  v[24] ^= t;
+  v[25] ^= t / 0x100000000;
+  if (last) {
+    v[28] = ~v[28];
+    v[29] = ~v[29];
+  }
+  for (let i = 0; i < 32; i++) {
+    m[i] = block[4 * i] | (block[4 * i + 1] << 8) | (block[4 * i + 2] << 16) | (block[4 * i + 3] << 24);
+  }
+  for (let r = 0; r < 12; r++) {
+    const s = SIGMA[r % 10];
+    g(0, 8, 16, 24, s[0], s[1]);
+    g(2, 10, 18, 26, s[2], s[3]);
+    g(4, 12, 20, 28, s[4], s[5]);
+    g(6, 14, 22, 30, s[6], s[7]);
+    g(0, 10, 20, 30, s[8], s[9]);
+    g(2, 12, 22, 24, s[10], s[11]);
+    g(4, 14, 16, 26, s[12], s[13]);
+    g(6, 8, 18, 28, s[14], s[15]);
+  }
+  for (let i = 0; i < 16; i++) h[i] ^= v[i] ^ v[i + 16];
+}
+
+/** BLAKE2b without a key, with an output of `outlen` bytes (1 to 64), over the concatenation of `parts`. */
+export function blake2b(outlen, ...parts) {
+  const h = new Uint32Array(16);
+  h.set(IV);
+  h[0] ^= 0x01010000 ^ outlen;
+  const block = new Uint8Array(128);
+  let fill = 0;
+  let t = 0;
+  for (const p of parts) {
+    for (let i = 0; i < p.length; i++) {
+      if (fill === 128) {
+        t += 128;
+        compress(h, block, t, false);
+        fill = 0;
+      }
+      block[fill++] = p[i];
+    }
+  }
+  t += fill;
+  block.fill(0, fill);
+  compress(h, block, t, true);
+  const out = new Uint8Array(outlen);
+  for (let i = 0; i < outlen; i++) out[i] = h[i >> 2] >>> (8 * (i & 3));
+  block.fill(0);
+  h.fill(0);
+  return out;
+}