rootcard 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,33 @@
+// 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 reproduce. This module is the verification
+// core; the vault cryptography (passwords, Argon2id, encryption) is in "rootcard/vault".
+//
+// Status: 0.x. Nothing here is stable before 1.0.0.
+
+export { FORMAT_VERSION, LABEL_PREFIX, label } from "./labels.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";