rootcard 0.0.0-stage → 0.1.0

package/src/log.js

@@ -0,0 +1,316 @@
+// The identity log (SPEC §9) and versions (SPEC §10). A log state is plain JSON, identical to the Rust crate's
+// `LogState::to_value`, so that hosts can store it ([LOG-16]).
+
+import { fail } from "./errors.js";
+import { base64urlEncode, base64urlDecode, bytesEqual } from "./encoding.js";
+import { ed25519Public, ed25519Sign, ed25519Verify, frameObject, sha256 } from "./crypto.js";
+import { canonical, without, isObject, MAX_SAFE } from "./json.js";
+import * as s from "./keys.js";
+import { formatKey } from "./keys.js";
+import { accountId, checkRealm, checkUsername, handle } from "./id.js";
+import { label } from "./labels.js";
+
+export const MAX_EVENTS = 1000;
+export const EVENT_LIMIT = 4096;
+export const FUTURE_WINDOW = 600;
+const REASONS = ["register", "revoke", "restore", "fresh"];
+
+/** The message owners sign on an event ([LOG-6]). */
+export function eventMessage(e) {
+  return frameObject(label("event"), without(e, "sigs"));
+}
+
+/** The message the primary host signs as its receipt ([LOG-8]). */
+export function receiptMessage(e) {
+  return frameObject(label("receipt"), without(e, "sigs"));
+}
+
+/** The event hash ([LOG-5]). */
+export async function eventHash(e) {
+  return sha256(eventMessage(e));
+}
+
+/** `home.url` ([LOG-4]). → bad_field */
+export function checkUrl(url) {
+  if (typeof url !== "string" || url.length < 1 || url.length > 256 || !/^[\x21-\x7e]+$/.test(url)) fail("bad_field");
+}
+
+function parseHome(m) {
+  s.members(m, ["key", "url"]);
+  const key = s.key(m, "key", "ed25519");
+  checkUrl(s.string(m, "url"));
+  return { key: m.key, keyRaw: key, url: m.url };
+}
+
+/** [LOG-12] step 2 for one event. */
+function parseEvent(v, index) {
+  if (isObject(v) && canonical(v).length > EVENT_LIMIT) fail("too_large");
+  const m = s.object(v);
+  s.version(m);
+  const kind = s.string(m, "kind");
+  if (!["incept", "instance", "rotate_recovery", "retire"].includes(kind)) fail("bad_kind");
+  if ((index === 0) !== (kind === "incept")) fail("bad_kind");
+  if (kind === "incept") s.members(m, ["v", "kind", "seq", "body", "sigs"]);
+  else s.members(m, ["v", "account", "seq", "prev", "kind", "time", "body", "sigs"]);
+  const e = { map: m, kind, seq: s.intIn(m, "seq", 0, MAX_SAFE) };
+  if (kind !== "incept") {
+    e.account = s.account(m, "account");
+    e.prev = s.bytes(m, "prev", 32);
+    e.time = s.intIn(m, "time", 0, MAX_SAFE);
+  } else {
+    e.time = 0;
+  }
+  e.sigs = [];
+  for (const x of s.array(m, "sigs")) {
+    const o = s.object(x);
+    s.members(o, ["key", "sig"]);
+    s.key(o, "key", "ed25519");
+    e.sigs.push({ key: o.key, sig: s.sig(o, "sig") });
+  }
+  const body = s.member(m, "body");
+  if (kind === "incept") {
+    s.members(body, ["realm", "username", "recovery"]);
+    e.realm = s.string(body, "realm");
+    e.username = s.string(body, "username");
+    s.key(body, "recovery", "ed25519");
+    e.recovery = body.recovery;
+  } else if (kind === "instance") {
+    s.members(body, ["account_key", "home", "reason"]);
+    s.key(body, "account_key", "ed25519");
+    e.accountKey = body.account_key;
+    e.home = parseHome(s.member(body, "home"));
+    const reason = s.string(body, "reason");
+    if (!REASONS.includes(reason)) fail("bad_reason");
+    e.reason = reason;
+  } else if (kind === "rotate_recovery") {
+    s.members(body, ["recovery"]);
+    s.key(body, "recovery", "ed25519");
+    e.recovery = body.recovery;
+  } else {
+    s.members(body, []);
+  }
+  return e;
+}
+
+function checkLength(n) {
+  if (n === 0) fail("bad_field");
+  if (n > MAX_EVENTS) fail("too_many_events");
+}
+
+function rawKey(k) {
+  return s.parseKey(k, "ed25519");
+}
+
+/** [LOG-12] step 4 for one event, updating the state `st` (a copy) in place. */
+async function apply(st, e, index, now, receipt) {
+  if (st.retired) fail("account_retired");
+  if (e.account !== st.account) fail("account_mismatch");
+  if (e.seq !== index) fail("bad_seq");
+  if (base64urlEncode(e.prev) !== st.version.hash) fail("bad_prev");
+  if (e.time < st.time) fail("time_backwards");
+  if (now !== undefined && now !== null && e.time > now + FUTURE_WINDOW) fail("future_time");
+  let expected;
+  if (e.kind === "instance") {
+    expected = [st.recovery, e.accountKey];
+    if (receipt) expected.push(e.home.key);
+  } else if (e.kind === "rotate_recovery") expected = [st.recovery, e.recovery];
+  else expected = [st.recovery];
+  if (e.sigs.length !== expected.length || e.sigs.some((x, i) => x.key !== expected[i])) fail("wrong_signer");
+  if (e.kind === "instance") {
+    const ak = e.accountKey;
+    const hk = e.home.key;
+    if (ak === hk || st.keys.includes(ak) || st.homes.includes(ak) || st.keys.includes(hk)) fail("key_reuse");
+  } else if (e.kind === "rotate_recovery") {
+    if (st.keys.includes(e.recovery) || st.homes.includes(e.recovery)) fail("key_reuse");
+  }
+  if (e.reason !== undefined) {
+    const has = st.instance !== undefined;
+    const ok = e.reason === "register" ? !has : e.reason === "fresh" ? true : has;
+    if (!ok) fail("bad_reason");
+  }
+  const msg = eventMessage(e.map);
+  const owners = e.kind === "instance" ? 2 : e.sigs.length;
+  for (let i = 0; i < owners; i++) await ed25519Verify(rawKey(e.sigs[i].key), msg, e.sigs[i].sig);
+  if (e.kind === "instance" && receipt) {
+    try {
+      await ed25519Verify(rawKey(e.sigs[2].key), receiptMessage(e.map), e.sigs[2].sig);
+    } catch {
+      fail("bad_receipt");
+    }
+  }
+  const hash = base64urlEncode(await sha256(msg));
+  if (e.kind === "instance") {
+    st.keys.push(e.accountKey);
+    if (!st.homes.includes(e.home.key)) st.homes.push(e.home.key);
+    st.instance = {
+      hash,
+      seq: index,
+      account_key: e.accountKey,
+      home: { key: e.home.key, url: e.home.url },
+      reason: e.reason,
+    };
+  } else if (e.kind === "rotate_recovery") {
+    st.recovery = e.recovery;
+    st.keys.push(e.recovery);
+  } else if (e.kind === "retire") {
+    st.retired = true;
+    delete st.instance;
+  }
+  st.time = e.time;
+  st.version = { seq: index, hash };
+}
+
+function copyState(st) {
+  const c = {
+    account: st.account,
+    realm: st.realm,
+    username: st.username,
+    handle: st.handle,
+    recovery: st.recovery,
+    retired: st.retired,
+    version: { ...st.version },
+    time: st.time,
+    keys: [...st.keys],
+    homes: [...st.homes],
+  };
+  if (st.instance) c.instance = { ...st.instance, home: { ...st.instance.home } };
+  return c;
+}
+
+/**
+ * Verify a whole log ([LOG-12]) and return its state.
+ * @param {any[]} events
+ * @param {{ realms: string[], now?: number }} options
+ */
+export async function verifyLog(events, options) {
+  if (!Array.isArray(events)) fail("bad_field");
+  checkLength(events.length);
+  const parsed = events.map((v, i) => parseEvent(v, i));
+  const inc = parsed[0];
+  if (inc.seq !== 0) fail("bad_seq");
+  checkRealm(inc.realm);
+  if (!options.realms.includes(inc.realm)) fail("realm_not_accepted");
+  checkUsername(inc.username);
+  if (inc.sigs.length !== 1 || inc.sigs[0].key !== inc.recovery) fail("wrong_signer");
+  const msg = eventMessage(inc.map);
+  await ed25519Verify(rawKey(inc.recovery), msg, inc.sigs[0].sig);
+  const account = await accountId(inc.map);
+  const st = {
+    account,
+    realm: inc.realm,
+    username: inc.username,
+    handle: handle(inc.username, account),
+    recovery: inc.recovery,
+    retired: false,
+    version: { seq: 0, hash: base64urlEncode(await sha256(msg)) },
+    time: 0,
+    keys: [inc.recovery],
+    homes: [],
+  };
+  for (let i = 1; i < parsed.length; i++) await apply(st, parsed[i], i, options.now, true);
+  return st;
+}
+
+/** Verify events that extend a verified log state ([LOG-15]). */
+export async function extendLog(state, events, options) {
+  const start = state.version.seq + 1;
+  if (start + events.length > MAX_EVENTS) fail("too_many_events");
+  const parsed = events.map((v, i) => parseEvent(v, start + i));
+  const st = copyState(state);
+  for (let i = 0; i < parsed.length; i++) await apply(st, parsed[i], start + i, options.now, true);
+  return st;
+}
+
+/** Check a pending instance ([LOG-9]). */
+export async function verifyPending(state, event, now) {
+  const index = state.version.seq + 1;
+  if (index >= MAX_EVENTS) fail("too_many_events");
+  const e = parseEvent(event, index);
+  if (e.kind !== "instance") fail("bad_kind");
+  await apply(copyState(state), e, index, now, false);
+}
+
+/** Compare two valid logs of one account ([VER-2]): `b` relative to `a`. → account_mismatch */
+export async function compareLogs(a, b) {
+  if (!a.length || !b.length || !isObject(a[0]) || !isObject(b[0])) fail("bad_field");
+  if ((await accountId(a[0])) !== (await accountId(b[0]))) fail("account_mismatch");
+  const h = async (v) => {
+    if (!isObject(v)) fail("bad_field");
+    return eventHash(v);
+  };
+  if (a.length === b.length) {
+    return bytesEqual(await h(a[a.length - 1]), await h(b[b.length - 1])) ? "same" : "fork";
+  }
+  const [short, long, order] = a.length < b.length ? [a, b, "newer"] : [b, a, "older"];
+  return bytesEqual(await h(short[short.length - 1]), await h(long[short.length - 1])) ? order : "fork";
+}
+
+/** An unsigned event after `state` (`sigs` empty). */
+export function unsignedEvent(state, kind, body, time) {
+  return {
+    v: 1,
+    account: state.account,
+    seq: state.version.seq + 1,
+    prev: state.version.hash,
+    kind,
+    time,
+    body,
+    sigs: [],
+  };
+}
+
+/** Append an owner signature ([LOG-6]). */
+export async function signEvent(e, seed) {
+  const sig = await ed25519Sign(seed, eventMessage(e));
+  e.sigs = [...e.sigs, { key: formatKey("ed25519", await ed25519Public(seed)), sig: base64urlEncode(sig) }];
+  return e;
+}
+
+/** Append the primary host's receipt ([LOG-8]). */
+export async function addReceipt(e, hostSeed) {
+  const sig = await ed25519Sign(hostSeed, receiptMessage(e));
+  e.sigs = [...e.sigs, { key: formatKey("ed25519", await ed25519Public(hostSeed)), sig: base64urlEncode(sig) }];
+  return e;
+}
+
+/** [RK-5] → wrong_recovery_key */
+export async function checkRecoveryKey(state, seed) {
+  if (formatKey("ed25519", await ed25519Public(seed)) !== state.recovery) fail("wrong_recovery_key");
+}
+
+/** A pending instance ([LOG-9]). `home` is `{ key: "ed25519:…", url }`. */
+export async function pendingInstance(state, recoverySeed, accountSeed, home, reason, time) {
+  await checkRecoveryKey(state, recoverySeed);
+  checkUrl(home.url);
+  const body = {
+    account_key: formatKey("ed25519", await ed25519Public(accountSeed)),
+    home: { key: home.key, url: home.url },
+    reason,
+  };
+  const e = unsignedEvent(state, "instance", body, time);
+  await signEvent(e, recoverySeed);
+  await signEvent(e, accountSeed);
+  return e;
+}
+
+/** A `rotate_recovery` event ([KT-5]). */
+export async function rotateRecoveryEvent(state, oldSeed, newSeed, time) {
+  await checkRecoveryKey(state, oldSeed);
+  const e = unsignedEvent(state, "rotate_recovery", { recovery: formatKey("ed25519", await ed25519Public(newSeed)) }, time);
+  await signEvent(e, oldSeed);
+  await signEvent(e, newSeed);
+  return e;
+}
+
+/** A `retire` event ([KT-6]). */
+export async function retireEvent(state, recoverySeed, time) {
+  await checkRecoveryKey(state, recoverySeed);
+  const e = unsignedEvent(state, "retire", {}, time);
+  await signEvent(e, recoverySeed);
+  return e;
+}
+
+/** The raw bytes of a b64u hash string. */
+export function hashBytes(h) {
+  return base64urlDecode(h);
+}

package/src/messages.js

@@ -0,0 +1,82 @@
+// Challenges and the signed messages of vault fetch, login and password change (SPEC §13).
+
+import { fail } from "./errors.js";
+import { base64urlEncode } from "./encoding.js";
+import { ed25519Sign, ed25519Verify, frameObject } from "./crypto.js";
+import * as s from "./keys.js";
+import { label } from "./labels.js";
+import { checkUrl } from "./log.js";
+
+export const CHALLENGE_LIFETIME = 60;
+
+/** Parse a challenge ([CHL-1]). → bad_field, bad_key */
+export function parseChallenge(v) {
+  const m = s.object(v);
+  s.members(m, ["nonce", "host", "realm", "version", "expires"]);
+  s.bytes(m, "nonce", 32);
+  s.key(m, "host", "ed25519");
+  s.string(m, "realm");
+  s.versionRef(s.get(m, "version"));
+  s.int(m, "expires");
+  return m;
+}
+
+/** The login message ([LGN-1] step 5). `host` is a key string, `nonce` b64u. */
+export function loginMessage(account, host, lock, nonce, realm, url, version) {
+  return frameObject(label("login"), { account, host, lock, nonce, realm, url, version: { seq: version.seq, hash: version.hash } });
+}
+
+/** The vault fetch message ([FET-1]). */
+export function fetchMessage(account, host, lock, nonce, url) {
+  return frameObject(label("fetch"), { account, host, lock, nonce, url });
+}
+
+/** The password change proof message ([CHG-1] step 2). `newLockHash` is b64u. */
+export function changeMessage(account, host, lock, newLockHash, nonce, url) {
+  return frameObject(label("change"), { account, host, lock, new: newLockHash, nonce, url });
+}
+
+/**
+ * Sign a login for `challenge` with the account key and the lock's key ([LGN-1] steps 4, 5). → wrong_host, stale_version
+ * @returns {Promise<{account, nonce, version, url, lock, sig, lock_sig}>}
+ */
+export async function signLogin(state, challenge, url, lock, accountSeed, lockSeed) {
+  const ch = parseChallenge(challenge);
+  if (!state.instance) fail("no_instance");
+  if (ch.host !== state.instance.home.key || ch.realm !== state.realm) fail("wrong_host");
+  if (ch.version.seq !== state.version.seq || ch.version.hash !== state.version.hash) fail("stale_version");
+  checkUrl(url);
+  const msg = loginMessage(state.account, ch.host, lock, ch.nonce, state.realm, url, state.version);
+  return {
+    account: state.account,
+    nonce: ch.nonce,
+    version: { seq: state.version.seq, hash: state.version.hash },
+    url,
+    lock,
+    sig: base64urlEncode(await ed25519Sign(accountSeed, msg)),
+    lock_sig: base64urlEncode(await ed25519Sign(lockSeed, msg)),
+  };
+}
+
+/** Parse a login request. → bad_field */
+export function parseLoginRequest(v) {
+  const m = s.object(v);
+  s.members(m, ["account", "nonce", "version", "url", "lock", "sig", "lock_sig"]);
+  checkUrl(s.string(m, "url"));
+  const lock = s.string(m, "lock");
+  if (lock.length < 1 || lock.length > 16) fail("bad_field");
+  s.account(m, "account");
+  s.bytes(m, "nonce", 32);
+  s.versionRef(s.get(m, "version"));
+  s.sig(m, "sig");
+  s.sig(m, "lock_sig");
+  return m;
+}
+
+/** Verify both signatures of a login request ([LGN-1] step 6). Keys are key strings. → bad_signature */
+export async function verifyLogin(request, realm, homeKey, accountKey, lockKey) {
+  const r = parseLoginRequest(request);
+  const msg = loginMessage(r.account, homeKey, r.lock, r.nonce, realm, r.url, r.version);
+  await ed25519Verify(s.parseKey(accountKey, "ed25519"), msg, s.sig(r, "sig"));
+  await ed25519Verify(s.parseKey(lockKey, "ed25519"), msg, s.sig(r, "lock_sig"));
+}

package/src/profile.js

@@ -0,0 +1,89 @@
+// Arbitrary data: the public profile and data keys (SPEC §12).
+
+import { fail } from "./errors.js";
+import { base64urlEncode } from "./encoding.js";
+import { ed25519Sign, ed25519Verify, frameObject } from "./crypto.js";
+import { canonical, validate, without } from "./json.js";
+import * as s from "./keys.js";
+import { label } from "./labels.js";
+
+export const PROFILE_LIMIT = 16 * 1024;
+const MAX_REV = 2 ** 32;
+
+/** [DAT-4] → bad_data_key */
+export function checkDataKey(key) {
+  if (typeof key !== "string" || key.length < 1 || key.length > 64 || !/^[a-z0-9._-]+$/.test(key)) fail("bad_data_key");
+  let rest;
+  if (key.startsWith("user.")) rest = key.slice(5);
+  else if (key.startsWith("app.")) {
+    const r = key.slice(4);
+    const dot = r.indexOf(".");
+    if (dot < 0) fail("bad_data_key");
+    checkAppName(r.slice(0, dot));
+    rest = r.slice(dot + 1);
+  } else fail("bad_data_key");
+  if (rest.length === 0) fail("bad_data_key");
+}
+
+/** An application namespace name ([DAT-4]). → bad_data_key */
+export function checkAppName(name) {
+  if (!/^[a-z0-9][a-z0-9-]{0,31}$/.test(name)) fail("bad_data_key");
+}
+
+/** Every key of `data` is valid and its canonical form is at most `limit` bytes. → bad_data_key, too_large */
+export function checkData(data, limit) {
+  for (const k of Object.keys(data)) checkDataKey(k);
+  if (canonical(data).length > limit) fail("too_large");
+}
+
+/** Set `key` on behalf of application `app` ([DAT-7]). Returns a new object. → bad_data_key, bad_json */
+export function setData(data, app, key, value) {
+  checkDataKey(key);
+  checkAppName(app);
+  if (!key.startsWith("user.") && !key.startsWith(`app.${app}.`)) fail("bad_data_key");
+  validate(value);
+  return { ...data, [key]: value };
+}
+
+/** Remove `key` on behalf of application `app` ([DAT-7]). Returns a new object. → bad_data_key */
+export function removeData(data, app, key) {
+  checkDataKey(key);
+  if (!key.startsWith("user.") && !key.startsWith(`app.${app}.`)) fail("bad_data_key");
+  const d = { ...data };
+  delete d[key];
+  return d;
+}
+
+/** The message the account key signs on a profile ([DAT-2]). */
+export function publicMessage(profile) {
+  return frameObject(label("public"), without(profile, "sig"));
+}
+
+/** Sign a public profile with the account key. → bad_data_key, too_large */
+export async function signPublic(account, instance, rev, data, accountSeed) {
+  checkData(data, PROFILE_LIMIT);
+  const p = { v: 1, account, instance, rev, data };
+  p.sig = base64urlEncode(await ed25519Sign(accountSeed, publicMessage(p)));
+  if (canonical(p).length > PROFILE_LIMIT) fail("too_large");
+  return p;
+}
+
+/** Verify a public profile ([DAT-2]). Returns `{ rev, data }`. */
+export async function verifyPublic(profile, state) {
+  if (canonical(profile).length > PROFILE_LIMIT) fail("too_large");
+  const m = s.object(profile);
+  s.version(m);
+  s.members(m, ["v", "account", "instance", "rev", "data", "sig"]);
+  const account = s.account(m, "account");
+  s.bytes(m, "instance", 32);
+  const rev = s.intIn(m, "rev", 1, MAX_REV);
+  const data = s.member(m, "data");
+  const sig = s.sig(m, "sig");
+  if (account !== state.account) fail("account_mismatch");
+  if (state.retired) fail("account_retired");
+  if (!state.instance) fail("no_instance");
+  if (m.instance !== state.instance.hash) fail("wrong_instance");
+  for (const k of Object.keys(data)) checkDataKey(k);
+  await ed25519Verify(s.parseKey(state.instance.account_key, "ed25519"), publicMessage(m), sig);
+  return { rev, data };
+}

package/src/proof.js

@@ -0,0 +1,66 @@
+// Proofs of identity (SPEC §14).
+
+import { fail } from "./errors.js";
+import { base64urlEncode } from "./encoding.js";
+import { ed25519Public, ed25519Sign, ed25519Verify, frameObject, sha256 } from "./crypto.js";
+import { utf8 } from "./encoding.js";
+import { validate, without } from "./json.js";
+import * as s from "./keys.js";
+import { formatKey } from "./keys.js";
+import { label } from "./labels.js";
+import { checkRecoveryKey, verifyLog } from "./log.js";
+
+/** `SHA-256(frame("rootcard/statement/v1", { statement }))` ([PRF-5]). → bad_json */
+export async function statementChallenge(statement) {
+  validate(statement);
+  return sha256(frameObject(label("statement"), { statement }));
+}
+
+function checkRecipient(r) {
+  const n = utf8(r).length;
+  if (n < 1 || n > 256) fail("bad_field");
+}
+
+/** Make a proof ([PRF-1], [PRF-2]). `by` is "account" or "recovery"; `challenge` is 32 bytes. */
+export async function prove(state, by, seed, challenge, recipient) {
+  checkRecipient(recipient);
+  const pub = formatKey("ed25519", await ed25519Public(seed));
+  const p = { v: 1, by, account: state.account, challenge: base64urlEncode(challenge), recipient };
+  if (by === "account") {
+    if (!state.instance) fail("no_instance");
+    if (state.instance.account_key !== pub) fail("wrong_account_key");
+    p.instance = state.instance.hash;
+  } else {
+    await checkRecoveryKey(state, seed);
+  }
+  p.sig = base64urlEncode(await ed25519Sign(seed, frameObject(label("proof"), p)));
+  return p;
+}
+
+/** Verify a proof against the newest log the verifier knows ([PRF-4]). Returns the log state. */
+export async function verifyProof(proof, log, challenge, recipient, options) {
+  const m = s.object(proof);
+  s.version(m);
+  const by = s.string(m, "by");
+  if (by !== "account" && by !== "recovery") fail("bad_field");
+  if (by === "account") s.members(m, ["v", "by", "account", "instance", "challenge", "recipient", "sig"]);
+  else s.members(m, ["v", "by", "account", "challenge", "recipient", "sig"]);
+  const account = s.account(m, "account");
+  if (by === "account") s.bytes(m, "instance", 32);
+  s.bytes(m, "challenge", 32);
+  checkRecipient(s.string(m, "recipient"));
+  const sig = s.sig(m, "sig");
+  const state = await verifyLog(log, options);
+  if (account !== state.account) fail("account_mismatch");
+  if (state.retired) fail("account_retired");
+  if (m.challenge !== base64urlEncode(challenge)) fail("wrong_challenge");
+  if (m.recipient !== recipient) fail("wrong_recipient");
+  let key;
+  if (by === "account") {
+    if (!state.instance) fail("no_instance");
+    if (m.instance !== state.instance.hash) fail("stale_version");
+    key = state.instance.account_key;
+  } else key = state.recovery;
+  await ed25519Verify(s.parseKey(key, "ed25519"), frameObject(label("proof"), without(m, "sig")), sig);
+  return state;
+}

package/src/recovery.js

@@ -0,0 +1,49 @@
+// The recovery key (SPEC §6).
+
+import { fail } from "./errors.js";
+import { B32, base32Decode, base32Encode, base32Normalize, bytesEqual } from "./encoding.js";
+import { ed25519Public, frame, frameObject, hkdf, sha256 } from "./crypto.js";
+import { label } from "./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]). */
+export 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 */
+export 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 }>}
+ */
+export 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. */
+export async function recoverySignPublic(keys) {
+  return ed25519Public(keys.signSeed);
+}
+
+export { bytesEqual };

package/src/testing.js

@@ -0,0 +1,34 @@
+// A deterministic byte stream for tests and vectors. Never use it for keys or nonces.
+// The stream is SHA-256(seed ‖ be32(0)) ‖ SHA-256(seed ‖ be32(1)) ‖ …, consumed byte by byte, the same as the Rust
+// crate's `testing::TestRandom`, so both implementations draw identical bytes (SPEC §21).
+
+/**
+ * A deterministic `random(n)` function for tests. It is synchronous; it needs `sha256Sync`, a synchronous SHA-256,
+ * which the tests take from `node:crypto`.
+ * @param {Uint8Array} seed
+ * @param {(m: Uint8Array) => Uint8Array} sha256Sync
+ */
+export function testRandom(seed, sha256Sync) {
+  let counter = 0;
+  let buf = new Uint8Array(0);
+  let pos = 0;
+  return (n) => {
+    const out = new Uint8Array(n);
+    for (let i = 0; i < n; i++) {
+      if (pos === buf.length) {
+        const m = new Uint8Array(seed.length + 4);
+        m.set(seed);
+        new DataView(m.buffer).setUint32(seed.length, counter++);
+        buf = sha256Sync(m);
+        pos = 0;
+      }
+      out[i] = buf[pos++];
+    }
+    return out;
+  };
+}
+
+/** Random bytes from the platform's secure generator, for applications ([CRY-1]). Not used by the core itself. */
+export function systemRandom(n) {
+  return globalThis.crypto.getRandomValues(new Uint8Array(n));
+}

package/src/vault-index.js

@@ -0,0 +1,9 @@
+// rootcard/vault: password locks, Argon2id, vault encryption and the high-level flows that need them.
+
+export {
+  checkPassword, deriveLockSecrets, wrapVaultKey, unwrapVaultKey, checkContents, unlockVault, signGrant, sealVault,
+  newPasswordLock, instanceVault, carriedLocks, updateContents, changePassword, addSlot, regrant,
+} from "./vault.js";
+export { register, newInstance, rotateRecovery } from "./account.js";
+export { argon2id } from "./argon2.js";
+export { x25519, x25519Public } from "./crypto.js";