rootcard 0.0.0 → 0.2.0

package/src/crypto.js

@@ -0,0 +1,186 @@
+// Cryptographic primitives (SPEC §4) over WebCrypto, and domain separation (SPEC §5).
+// Private keys are imported non-extractable for signing and agreement; raw secret buffers are overwritten by the
+// callers that own them ([IMP-2]).
+
+import { fail } from "./errors.js";
+import { canonical } from "./json.js";
+import { concat, utf8 } from "./encoding.js";
+
+const subtle = globalThis.crypto?.subtle;
+
+let support;
+/** Check that WebCrypto has Ed25519 and X25519 ([IMP-3]). → unsupported_browser */
+export async function checkSupport() {
+  if (support === undefined) {
+    support = (async () => {
+      if (!subtle) return false;
+      try {
+        await subtle.importKey("raw", new Uint8Array(32).fill(9), { name: "X25519" }, true, []);
+        const k = await subtle.importKey("raw", ED_TEST_KEY, { name: "Ed25519" }, true, ["verify"]);
+        return !!k;
+      } catch {
+        return false;
+      }
+    })();
+  }
+  if (!(await support)) fail("unsupported_browser");
+}
+
+// The Ed25519 public key of RFC 8032 test 1, used only to probe for support.
+const ED_TEST_KEY = new Uint8Array([
+  0xd7, 0x5a, 0x98, 0x01, 0x82, 0xb1, 0x0a, 0xb7, 0xd5, 0x4b, 0xfe, 0xd3, 0xc9, 0x64, 0x07, 0x3a, 0x0e, 0xe1, 0x72,
+  0xf3, 0xda, 0xa6, 0x23, 0x25, 0xaf, 0x02, 0x1a, 0x68, 0xf7, 0x07, 0x51, 0x1a,
+]);
+
+/** `frame(label, m) = utf8(label) ‖ 0x00 ‖ m` ([DS-1]). */
+export function frame(label, m) {
+  return concat(utf8(label), new Uint8Array([0]), m);
+}
+
+/** `frame(label, canonical(x))`. */
+export function frameObject(label, x) {
+  return frame(label, canonical(x));
+}
+
+/** SHA-256. */
+export async function sha256(m) {
+  return new Uint8Array(await subtle.digest("SHA-256", m));
+}
+
+/** HKDF-SHA256 with a 32-byte output ([CRY-5]). */
+export async function hkdf(ikm, salt, info) {
+  const key = await subtle.importKey("raw", ikm, "HKDF", false, ["deriveBits"]);
+  return new Uint8Array(await subtle.deriveBits({ name: "HKDF", hash: "SHA-256", salt, info }, key, 256));
+}
+
+const ED_PKCS8 = new Uint8Array([0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20]);
+const X_PKCS8 = new Uint8Array([0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x6e, 0x04, 0x22, 0x04, 0x20]);
+
+function b64uToBytes(s) {
+  const b = atob(s.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - (s.length % 4)) % 4));
+  return Uint8Array.from(b, (c) => c.charCodeAt(0));
+}
+
+async function importPrivate(prefix, alg, secret, extractable, usages) {
+  const der = concat(prefix, secret);
+  try {
+    return await subtle.importKey("pkcs8", der, { name: alg }, extractable, usages);
+  } finally {
+    der.fill(0);
+  }
+}
+
+async function publicOf(prefix, alg, secret, usages) {
+  const k = await importPrivate(prefix, alg, secret, true, usages);
+  const jwk = await subtle.exportKey("jwk", k);
+  const x = b64uToBytes(jwk.x);
+  jwk.d = "";
+  return x;
+}
+
+/** The Ed25519 public key of a 32-byte seed ([CRY-2]). */
+export async function ed25519Public(seed) {
+  return publicOf(ED_PKCS8, "Ed25519", seed, ["sign"]);
+}
+
+/** Import an Ed25519 seed as a non-extractable signing key ([IMP-2]). */
+export async function ed25519SigningKey(seed) {
+  return importPrivate(ED_PKCS8, "Ed25519", seed, false, ["sign"]);
+}
+
+/** A deterministic Ed25519 signature ([CRY-8]). `key` is a seed or a key from ed25519SigningKey. */
+export async function ed25519Sign(key, m) {
+  const k = key instanceof Uint8Array ? await ed25519SigningKey(key) : key;
+  return new Uint8Array(await subtle.sign("Ed25519", k, m));
+}
+
+// L, p and the small-order encodings of [CRY-3].
+const L = 2n ** 252n + 27742317777372353535851937790883648493n;
+const P = 2n ** 255n - 19n;
+const SMALL_ORDER = [
+  "0100000000000000000000000000000000000000000000000000000000000000",
+  "ecffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7f",
+  "0000000000000000000000000000000000000000000000000000000000000000",
+  "0000000000000000000000000000000000000000000000000000000000000080",
+  "26e8958fc2b227b045c3f489f2ef98f0d5dfac05d3c63339b13802886d53fc05",
+  "26e8958fc2b227b045c3f489f2ef98f0d5dfac05d3c63339b13802886d53fc85",
+  "c7176a703d4dd84fba3c0b760d10670f2a2053fa2c39ccc64ec7fd7792ac037a",
+  "c7176a703d4dd84fba3c0b760d10670f2a2053fa2c39ccc64ec7fd7792ac03fa",
+];
+const NEG_ZERO = [
+  "0100000000000000000000000000000000000000000000000000000000000080",
+  "ecffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
+];
+
+function le(bytes) {
+  let n = 0n;
+  for (let i = bytes.length - 1; i >= 0; i--) n = (n << 8n) | BigInt(bytes[i]);
+  return n;
+}
+
+function hex(b) {
+  let s = "";
+  for (const x of b) s += x.toString(16).padStart(2, "0");
+  return s;
+}
+
+/** [CRY-3] steps 3 and 4 for an encoded point: canonical and not of small order (also [KEY-3]). */
+export function ed25519PointOk(e) {
+  if (e.length !== 32) return false;
+  const y = e.slice();
+  y[31] &= 0x7f;
+  if (le(y) >= P) return false;
+  const h = hex(e);
+  return !NEG_ZERO.includes(h) && !SMALL_ORDER.includes(h);
+}
+
+/** Strict Ed25519 verification ([CRY-3]). → bad_signature */
+export async function ed25519Verify(publicKey, m, sig) {
+  if (publicKey.length !== 32 || sig.length !== 64) fail("bad_signature");
+  const r = sig.subarray(0, 32);
+  const s = sig.subarray(32);
+  if (le(s) >= L || !ed25519PointOk(publicKey) || !ed25519PointOk(r)) fail("bad_signature");
+  let ok = false;
+  try {
+    const k = await subtle.importKey("raw", publicKey, { name: "Ed25519" }, false, ["verify"]);
+    ok = await subtle.verify("Ed25519", k, sig, m);
+  } catch {
+    ok = false;
+  }
+  if (!ok) fail("bad_signature");
+}
+
+/** The X25519 public key of a 32-byte secret ([CRY-2]). */
+export async function x25519Public(secret) {
+  return publicOf(X_PKCS8, "X25519", secret, ["deriveBits"]);
+}
+
+/** X25519 key agreement; an all-zero result fails ([CRY-4]). → bad_key */
+export async function x25519(secret, publicKey) {
+  let bits;
+  try {
+    const priv = await importPrivate(X_PKCS8, "X25519", secret, false, ["deriveBits"]);
+    const pub = await subtle.importKey("raw", publicKey, { name: "X25519" }, false, []);
+    bits = new Uint8Array(await subtle.deriveBits({ name: "X25519", public: pub }, priv, 256));
+  } catch {
+    fail("bad_key");
+  }
+  if (bits.every((b) => b === 0)) fail("bad_key");
+  return bits;
+}
+
+/** AES-256-GCM encryption: ciphertext ‖ tag ([CRY-7]). */
+export async function aesGcmEncrypt(key, nonce, plaintext, aad) {
+  const k = await subtle.importKey("raw", key, "AES-GCM", false, ["encrypt"]);
+  return new Uint8Array(await subtle.encrypt({ name: "AES-GCM", iv: nonce, additionalData: aad, tagLength: 128 }, k, plaintext));
+}
+
+/** AES-256-GCM decryption. → unlock_failed */
+export async function aesGcmDecrypt(key, nonce, ct, aad) {
+  const k = await subtle.importKey("raw", key, "AES-GCM", false, ["decrypt"]);
+  try {
+    return new Uint8Array(await subtle.decrypt({ name: "AES-GCM", iv: nonce, additionalData: aad, tagLength: 128 }, k, ct));
+  } catch {
+    fail("unlock_failed");
+  }
+}

package/src/encoding.js

@@ -0,0 +1,145 @@
+// Byte encodings (SPEC §3): unpadded base64url, Crockford base32, hex and UTF-8.
+
+import { fail } from "./errors.js";
+
+const B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+const B64_VALUE = new Map([...B64].map((c, i) => [c, i]));
+
+/** Unpadded base64url ([B64-1]). @param {Uint8Array} bytes */
+export function base64urlEncode(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const n = (bytes[i] << 16) | ((bytes[i + 1] ?? 0) << 8) | (bytes[i + 2] ?? 0);
+    const chars = Math.min(3, bytes.length - i) + 1;
+    for (let j = 0; j < chars; j++) out += B64[(n >>> (18 - 6 * j)) & 63];
+  }
+  return out;
+}
+
+/** Strict unpadded base64url decoding ([B64-2]). → bad_base64 */
+export function base64urlDecode(text) {
+  if (typeof text !== "string" || text.length % 4 === 1) fail("bad_base64");
+  const out = new Uint8Array(Math.floor((text.length * 3) / 4));
+  let o = 0;
+  for (let i = 0; i < text.length; i += 4) {
+    const chunk = text.slice(i, i + 4);
+    let n = 0;
+    for (let j = 0; j < chunk.length; j++) {
+      const v = B64_VALUE.get(chunk[j]);
+      if (v === undefined) fail("bad_base64");
+      n |= v << (18 - 6 * j);
+    }
+    const len = chunk.length - 1;
+    const unused = len === 1 ? n & 0xffff : len === 2 ? n & 0xff : 0;
+    if (unused !== 0) fail("bad_base64");
+    const b = [(n >>> 16) & 255, (n >>> 8) & 255, n & 255];
+    for (let j = 0; j < len; j++) out[o++] = b[j];
+  }
+  return out;
+}
+
+/** The Crockford base32 alphabet ([B32-1]). */
+export const B32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+
+/** Crockford base32 ([B32-2]). */
+export function base32Encode(bytes) {
+  let out = "";
+  let acc = 0;
+  let bits = 0;
+  for (const b of bytes) {
+    acc = ((acc << 8) | b) >>> 0;
+    bits += 8;
+    while (bits >= 5) {
+      bits -= 5;
+      out += B32[(acc >>> bits) & 31];
+    }
+    acc &= (1 << bits) - 1;
+  }
+  if (bits > 0) out += B32[(acc << (5 - bits)) & 31];
+  return out;
+}
+
+/** Strict Crockford base32 decoding of exactly `len` bytes ([B32-3]). → bad_base32 */
+export function base32Decode(text, len) {
+  if (typeof text !== "string" || text.length !== Math.ceil((len * 8) / 5)) fail("bad_base32");
+  const out = new Uint8Array(len);
+  let o = 0;
+  let acc = 0;
+  let bits = 0;
+  for (const c of text) {
+    const v = B32.indexOf(c);
+    if (v < 0 || c.length !== 1) fail("bad_base32");
+    acc = (acc << 5) | v;
+    bits += 5;
+    if (bits >= 8) {
+      bits -= 8;
+      out[o++] = (acc >>> bits) & 255;
+      acc &= (1 << bits) - 1;
+    }
+  }
+  if (acc !== 0) fail("bad_base32");
+  return out;
+}
+
+/** Lenient normalization of typed base32 ([B32-4]). */
+export function base32Normalize(text) {
+  let out = "";
+  for (const c of text) {
+    if (c === "-" || c === " ") continue;
+    const u = c.length === 1 && c >= "a" && c <= "z" ? c.toUpperCase() : c;
+    out += u === "I" || u === "L" ? "1" : u === "O" ? "0" : u;
+  }
+  return out;
+}
+
+/** Lenient decoding for human input ([B32-4]). → bad_base32 */
+export function base32DecodeLenient(text, len) {
+  return base32Decode(base32Normalize(text), len);
+}
+
+/** Lower-case hexadecimal. */
+export function hexEncode(bytes) {
+  let s = "";
+  for (const b of bytes) s += b.toString(16).padStart(2, "0");
+  return s;
+}
+
+/** Hexadecimal to bytes. → bad_field */
+export function hexDecode(text) {
+  if (text.length % 2 || !/^[0-9a-fA-F]*$/.test(text)) fail("bad_field");
+  const out = new Uint8Array(text.length / 2);
+  for (let i = 0; i < out.length; i++) out[i] = parseInt(text.slice(2 * i, 2 * i + 2), 16);
+  return out;
+}
+
+const te = new TextEncoder();
+/** UTF-8 bytes of a string. */
+export function utf8(s) {
+  return te.encode(s);
+}
+
+/** Concatenate byte arrays. */
+export function concat(...parts) {
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+  let o = 0;
+  for (const p of parts) {
+    out.set(p, o);
+    o += p.length;
+  }
+  return out;
+}
+
+/** Byte equality (not constant time; use ctEqual for secrets). */
+export function bytesEqual(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+/** Constant-time equality of two byte arrays ([IMP-4]). */
+export function ctEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let d = 0;
+  for (let i = 0; i < a.length; i++) d |= a[i] ^ b[i];
+  return d === 0;
+}

package/src/errors.js

@@ -0,0 +1,38 @@
+// Error codes (SPEC §20).
+
+/** Every error code of SPEC §20, in its order. */
+export const ERROR_CODES = Object.freeze([
+  "bad_json", "bad_field", "unsupported_version", "too_large", "bad_base64", "bad_base32", "bad_checksum", "bad_key",
+  "bad_signature", "bad_realm", "realm_not_accepted", "bad_username", "username_policy", "bad_handle", "handle_taken",
+  "ambiguous_handle", "account_mismatch", "wrong_recovery_key", "too_many_events", "bad_kind", "bad_seq", "bad_prev",
+  "time_backwards", "future_time", "bad_time", "wrong_signer", "key_reuse", "bad_receipt", "bad_reason",
+  "account_retired", "no_instance", "stale_version", "fork", "wrong_instance", "stale_rev", "stale_locks", "bad_locks",
+  "kdf_params", "weak_password", "unlock_failed", "wrong_account_key", "bad_data_key", "wrong_challenge",
+  "wrong_recipient", "challenge_unknown", "challenge_expired", "not_home", "wrong_host", "unknown_account",
+  "unauthorized", "rate_limited", "unsupported_browser",
+]);
+
+/** A rootcard error. `code` is one of the stable codes of SPEC §20. */
+export class RootcardError extends Error {
+  /** @param {string} code */
+  constructor(code) {
+    super(code);
+    this.name = "RootcardError";
+    this.code = code;
+  }
+}
+
+/** Throw the error `code`. @param {string} code @returns {never} */
+export function fail(code) {
+  throw new RootcardError(code);
+}
+
+/** Run `f`, replacing any RootcardError by `code`. */
+export function remap(code, f) {
+  try {
+    return f();
+  } catch (e) {
+    if (e instanceof RootcardError) fail(code);
+    throw e;
+  }
+}

package/src/file.js

@@ -0,0 +1,118 @@
+// The account file and the recovery card (SPEC §15).
+
+import { fail } from "./errors.js";
+import { canonical } from "./json.js";
+import * as s from "./keys.js";
+import { verifyLog } from "./log.js";
+import { verifyPublic } from "./profile.js";
+import { verifyVault } from "./vaultcheck.js";
+import { accountId, inception, tag } from "./id.js";
+import { deriveRecoveryKeys, formatRecoveryKey, parseRecoveryKey, recoverySignPublic } from "./recovery.js";
+import { formatKey } from "./keys.js";
+
+export const FILE_LIMIT = 5 * 1024 * 1024;
+export const HOST_DATA_LIMIT = 16 * 1024;
+
+/** Build an account file ([FIL-2]). */
+export function exportAccount(state, log, publicProfile, vault, hostData) {
+  const f = {
+    format: "rootcard-account",
+    v: 1,
+    realm: state.realm,
+    account: state.account,
+    handle: state.handle,
+    version: { seq: state.version.seq, hash: state.version.hash },
+    log: [...log],
+  };
+  if (publicProfile !== undefined && publicProfile !== null) f.public = publicProfile;
+  if (vault !== undefined && vault !== null) f.vault = vault;
+  if (hostData !== undefined && hostData !== null) f.host_data = hostData;
+  return f;
+}
+
+/** The suggested file name ([FIL-1]). */
+export function accountFileName(state) {
+  return `${state.username}-${tag(state.account)}.rootcard.json`;
+}
+
+/** Import an account file ([FIL-3]). Returns `{ state, log, public?, vault?, hostData? }`. */
+export async function importAccount(file, options) {
+  if (canonical(file).length > FILE_LIMIT) fail("too_large");
+  const m = s.object(file);
+  if (m.format !== "rootcard-account") fail("bad_field");
+  s.version(m);
+  s.members(m, ["format", "v", "realm", "account", "handle", "version", "log"], ["public", "vault", "host_data"]);
+  const realm = s.string(m, "realm");
+  const account = s.account(m, "account");
+  const handle = s.string(m, "handle");
+  const version = s.versionRef(s.get(m, "version"));
+  const log = s.array(m, "log");
+  let hostData;
+  if (Object.hasOwn(m, "host_data")) {
+    hostData = s.object(m.host_data);
+    if (canonical(hostData).length > HOST_DATA_LIMIT) fail("too_large");
+  }
+  const state = await verifyLog(log, options);
+  if (state.account !== account || state.realm !== realm || state.handle !== handle ||
+      state.version.seq !== version.seq || state.version.hash !== version.hash) {
+    fail("account_mismatch");
+  }
+  const out = { state, log };
+  if (Object.hasOwn(m, "public")) out.public = { value: m.public, info: await verifyPublic(m.public, state) };
+  if (Object.hasOwn(m, "vault")) out.vault = { value: m.vault, info: await verifyVault(m.vault, state) };
+  if (hostData !== undefined) out.hostData = hostData;
+  return out;
+}
+
+/** Build a recovery card ([CRD-1], [CRD-2]). */
+export async function recoveryCard(realm, username, account, key, log) {
+  const c = { format: "rootcard-card", v: 1, realm, username, account, key: await formatRecoveryKey(key) };
+  if (log) c.log = [...log];
+  return c;
+}
+
+/** Read a recovery card ([CRD-3]). Returns `{ realm, username, account, key, keys, log, state }`. */
+export async function readCard(card) {
+  const m = s.object(card);
+  if (m.format !== "rootcard-card") fail("bad_field");
+  s.version(m);
+  s.members(m, ["format", "v", "realm", "username", "account", "key"], ["log"]);
+  const realm = s.string(m, "realm");
+  const username = s.string(m, "username");
+  const account = s.account(m, "account");
+  const keyText = s.string(m, "key");
+  const logValue = Object.hasOwn(m, "log") ? s.array(m, "log") : undefined;
+  const key = await parseRecoveryKey(keyText);
+  const keys = await deriveRecoveryKeys(key, realm, username);
+  const options = { realms: [realm] };
+  let log;
+  let state;
+  if (logValue === undefined) {
+    const inc = await inception(keys, realm, username);
+    if ((await accountId(inc)) !== account) fail("account_mismatch");
+    log = [inc];
+    state = await verifyLog(log, options);
+  } else {
+    log = logValue;
+    state = await verifyLog(log, options);
+    if (state.account !== account || state.realm !== realm || state.username !== username) fail("account_mismatch");
+    if (formatKey("ed25519", await recoverySignPublic(keys)) !== state.recovery) fail("wrong_recovery_key");
+  }
+  return { realm, username, account, key, keys, log, state };
+}
+
+/** The printable text form of a recovery card ([CRD-4]). */
+export async function cardText(card) {
+  const c = await readCard(card);
+  const groups = (str) => str.match(/.{1,4}/g).join(" ");
+  const key = (await formatRecoveryKey(c.key)).slice(4).replace(/-/g, " ");
+  return (
+    "rootcard recovery card\n\n" +
+    `Handle:     ${c.state.handle}\n` +
+    `Realm:      ${c.realm}\n` +
+    `Account id: ${groups(c.account)}\n\n` +
+    `Recovery key:\n  RCR ${key}\n\n` +
+    "Anyone who has this card controls the identity. Keep it offline and private.\n" +
+    "Only enter the recovery key in the rootcard key tool.\n"
+  );
+}

package/src/id.js

@@ -0,0 +1,107 @@
+// Realm, username, inception, account id (SPEC §7), handles and tags (SPEC §8).
+
+import { fail } from "./errors.js";
+import { B32, base32Encode, base64urlEncode } from "./encoding.js";
+import { ed25519Public, ed25519Sign, frameObject, sha256 } from "./crypto.js";
+import { without } from "./json.js";
+import { formatKey } from "./keys.js";
+import { label } from "./labels.js";
+
+/** [RLM-1] → bad_realm */
+export function checkRealm(realm) {
+  if (typeof realm !== "string" || !/^[a-z0-9]([a-z0-9._-]{0,62}[a-z0-9])?$/.test(realm)) fail("bad_realm");
+}
+
+/** [USR-1] → bad_username */
+export function checkUsername(username) {
+  if (typeof username !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$/.test(username)) fail("bad_username");
+}
+
+/** The default username policy ([USR-3]): [USR-1], 3 to 20 characters, beginning with A–Z a–z. */
+export function defaultUsernamePolicy(username) {
+  return /^[A-Za-z][A-Za-z0-9_-]{2,19}$/.test(username);
+}
+
+/** [USR-2] */
+export function similarUsernames(a, b) {
+  return a.toLowerCase() === b.toLowerCase() && /^[\x00-\x7f]*$/.test(a + b);
+}
+
+/** The account id of an inception ([ID-3]). */
+export async function accountId(inception) {
+  return base32Encode(await sha256(frameObject(label("id"), without(inception, "sigs"))));
+}
+
+/** The deterministic inception of an identity ([ID-1], [ID-2]). → bad_realm, bad_username */
+export async function inception(keys, realm, username) {
+  checkRealm(realm);
+  checkUsername(username);
+  const recovery = formatKey("ed25519", await ed25519Public(keys.signSeed));
+  const unsigned = { v: 1, kind: "incept", seq: 0, body: { realm, username, recovery } };
+  const sig = await ed25519Sign(keys.signSeed, frameObject(label("event"), unsigned));
+  return { ...unsigned, sigs: [{ key: recovery, sig: base64urlEncode(sig) }] };
+}
+
+/** The tag of an account id ([HDL-1]). */
+export function tag(account) {
+  return account.slice(0, 4);
+}
+
+/** `username + "#" + tag` ([HDL-1]). */
+export function handle(username, account) {
+  return `${username}#${tag(account)}`;
+}
+
+function lenientChars(s) {
+  let out = "";
+  for (const c of s) {
+    const u = c.length === 1 && c >= "a" && c <= "z" ? c.toUpperCase() : c;
+    const m = u === "I" || u === "L" ? "1" : u === "O" ? "0" : u;
+    if (m.length !== 1 || !B32.includes(m)) return null;
+    out += m;
+  }
+  return out;
+}
+
+/** Parse a typed handle ([HDL-3]). → bad_handle */
+export function parseHandle(text) {
+  const at = text.lastIndexOf("#");
+  if (at < 0) fail("bad_handle");
+  const username = text.slice(0, at);
+  try {
+    checkUsername(username);
+  } catch {
+    fail("bad_handle");
+  }
+  const t = text.slice(at + 1);
+  const dash = t.indexOf("-");
+  const t4 = lenientChars(dash < 0 ? t : t.slice(0, dash));
+  if (t4 === null || t4.length !== 4) fail("bad_handle");
+  const result = { username, tag: t4 };
+  if (dash >= 0) {
+    const e = lenientChars(t.slice(dash + 1));
+    if (e === null || e.length < 1 || e.length > 48) fail("bad_handle");
+    result.extension = e;
+  }
+  return result;
+}
+
+/** Whether an identity matches a parsed handle (similar username, [USR-2]). */
+export function handleMatches(parsed, username, account) {
+  return similarUsernames(parsed.username, username) && account.startsWith(parsed.tag + (parsed.extension ?? ""));
+}
+
+/** The extended tags of colliding account ids ([HDL-6]), in the order given. */
+export function extendedTags(ids) {
+  const distinct = [...new Set(ids)];
+  if (distinct.length < 2) return ids.map(tag);
+  const max = Math.min(...distinct.map((s) => s.length));
+  let n = 5;
+  while (n < max) {
+    const prefixes = distinct.map((s) => s.slice(0, n));
+    if (new Set(prefixes).size === prefixes.length) break;
+    n++;
+  }
+  n = Math.min(n, max);
+  return ids.map((id) => `${id.slice(0, 4)}-${id.slice(4, n)}`);
+}

package/src/index.js

@@ -1,22 +1,34 @@
 // rootcard: a portable, self-certifying identity for online logins.
 //
 // This package mirrors the `rootcard` Rust crate byte for byte. The normative format is spec/SPEC.md in the repository,
-// and spec/vectors/ holds the shared test vectors both implementations must reproduce.
+// and spec/vectors/ holds the shared test vectors both implementations reproduce. This module is the verification
+// core; the vault cryptography (passwords, Argon2id, encryption) is in "rootcard/vault".
 //
-// Status: skeleton (phase 0). Nothing here is stable.
+// Status: 0.x. Nothing here is stable before 1.0.0.
 
-/** Version of the wire and storage format described by the specification. */
-export const FORMAT_VERSION = 1;
-
-/** Prefix of every domain-separation label (`rootcard/<purpose>/v<n>`). */
-export const LABEL_PREFIX = "rootcard/";
-
-/**
- * Build a domain-separation label, e.g. `label("id", 1) === "rootcard/id/v1"`.
- * @param {string} purpose
- * @param {number} version
- * @returns {string}
- */
-export function label(purpose, version) {
-  return `${LABEL_PREFIX}${purpose}/v${version}`;
-}
+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 {
+  base64urlEncode, base64urlDecode, base32Encode, base32Decode, base32DecodeLenient, hexEncode, hexDecode,
+} from "./encoding.js";
+export { checkSupport, sha256, ed25519Public, ed25519Sign, ed25519Verify, ed25519SigningKey } from "./crypto.js";
+export { formatKey, parseKey } from "./keys.js";
+export { formatRecoveryKey, parseRecoveryKey, deriveRecoveryKeys } from "./recovery.js";
+export {
+  checkRealm, checkUsername, defaultUsernamePolicy, similarUsernames, accountId, inception, tag, handle, parseHandle,
+  handleMatches, extendedTags,
+} from "./id.js";
+export {
+  MAX_EVENTS, verifyLog, extendLog, verifyPending, compareLogs, eventHash, eventMessage, receiptMessage, unsignedEvent,
+  signEvent, addReceipt, pendingInstance, rotateRecoveryEvent, retireEvent, checkRecoveryKey, checkUrl,
+} from "./log.js";
+export { verifyVault, vaultChange, KDF_DEFAULT, KDF_MIN } from "./vaultcheck.js";
+export { checkDataKey, setData, removeData, signPublic, verifyPublic } from "./profile.js";
+export {
+  parseChallenge, loginMessage, fetchMessage, changeMessage, signLogin, parseLoginRequest, verifyLogin,
+} from "./messages.js";
+export { statementChallenge, prove, verifyProof } from "./proof.js";
+export { exportAccount, importAccount, accountFileName, recoveryCard, readCard, cardText } from "./file.js";
+export { systemRandom } from "./testing.js";