rootcard 0.2.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rootcard",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "A portable, self-certifying identity for online logins (core library, zero dependencies, WebCrypto)",
   "keywords": [
     "identity",
@@ -11,13 +11,13 @@
     "self-certifying"
   ],
   "license": "(MIT OR Apache-2.0)",
-  "homepage": "https://github.com/Hexagon/rootcard",
+  "homepage": "https://github.com/rootcard/rootcard",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Hexagon/rootcard.git",
+    "url": "git+https://github.com/rootcard/rootcard.git",
     "directory": "packages/rootcard"
   },
-  "bugs": "https://github.com/Hexagon/rootcard/issues",
+  "bugs": "https://github.com/rootcard/rootcard/issues",
   "type": "module",
   "exports": {
     ".": "./src/index.js",

package/src/account.js

@@ -6,21 +6,33 @@ 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 { checkNewRecoveryKey, deriveRecoveryKeys } from "./recovery.js";
+import { DRAW_ATTEMPTS, usableSeed } from "./crypto.js";
 import { recoveryCard } from "./file.js";
 import { carriedLocks, checkPassword, instanceVault, regrant } from "./vault.js";
 
+/** The account seed of a new instance: 32 random bytes, drawn again while unusable ([CRY-9]). → bad_key (broken generator) */
+function drawAccountSeed(random) {
+  for (let i = 0; i < DRAW_ATTEMPTS; i++) {
+    const seed = random(32);
+    if (usableSeed(seed)) return seed;
+  }
+  fail("bad_key");
+}
+
 /**
- * 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.
+ * Build a registration ([CLT-1]) from a recovery key the caller generated ([RK-3]; usable by [CRY-9], see
+ * newRecoveryKey → bad_key). `home` is `{ key, url }` with a key string. Draws: the account seed (32, again while
+ * unusable, [CRY-9]), 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);
+  checkNewRecoveryKey(keys);
   const inc = await inception(keys, realm, username);
   const state = await verifyLog([inc], { realms: [realm] });
-  const seed = random(32);
+  const seed = drawAccountSeed(random);
   const pending = await pendingInstance(state, keys.signSeed, seed, home, "register", time);
   const instance = base64urlEncode(await eventHash(pending));
   const vault = await instanceVault(
@@ -30,7 +42,7 @@ export async function register(recoveryKey, realm, username, password, slotLabel
       recovery: keys,
       contents: { accountSeed: seed, data: {} },
       keep: [],
-      add: { label: slotLabel, password, kdf },
+      add: { label: slotLabel, password, username, kdf },
     },
     random,
   );
@@ -45,12 +57,19 @@ export async function register(recoveryKey, realm, username, password, slotLabel
 /**
  * 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.
+ * unlocked with the recovery lock (not needed for fresh). Draws: the account seed (32, again while unusable,
+ * [CRY-9]), 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 slot = mode.reset ?? mode.fresh;
+  if (slot) {
+    // The new password is checked before anything is drawn ([LCK-8]); its username must be this identity's.
+    if (slot.username !== state.username) fail("bad_field");
+    checkPassword(slot.password, state.username);
+  }
+  const seed = drawAccountSeed(random);
   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));
@@ -77,11 +96,12 @@ export async function newInstance(state, recovery, old, oldPublicData, mode, hom
 }
 
 /**
- * Rotate the recovery key ([KT-5]) to `newKey`. `unlocked` is the current vault unlocked. Draws: regrant.
+ * Rotate the recovery key ([KT-5]) to `newKey` (usable by [CRY-9] → bad_key; see newRecoveryKey). `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);
+  checkNewRecoveryKey(next);
   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]);

package/src/binding.js

@@ -15,6 +15,11 @@ export function isVersionSegment(segment) {
   return /^[vV][0-9]+$/.test(segment);
 }
 
+// A base URL path segment ([HST-22]): non-empty, only unreserved characters (no percent-encoding), not a dot segment.
+function isPathSegment(segment) {
+  return /^[A-Za-z0-9\-._~]+$/.test(segment) && segment !== "." && segment !== "..";
+}
+
 function authorityHost(rest) {
   const authority = rest.split("/")[0];
   if (authority.startsWith("[")) {
@@ -26,8 +31,8 @@ function authorityHost(rest) {
 
 /**
  * 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`
+ * query, fragment or user info; plain `http://` only for `localhost`, `127.0.0.1` and `[::1]`; path segments of
+ * unreserved characters only, never `.` or `..`; and its last path segment is not an API version segment. → `bad_field`
  */
 export function checkBaseUrl(url) {
   checkUrl(url);
@@ -43,7 +48,7 @@ export function checkBaseUrl(url) {
   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 (!segments.every(isPathSegment)) fail("bad_field");
     if (isVersionSegment(segments[segments.length - 1])) fail("bad_field");
   }
 }

package/src/crypto.js

@@ -78,14 +78,76 @@ async function publicOf(prefix, alg, secret, usages) {
   return x;
 }
 
+/** How often a seed is drawn again before a generator is taken to be broken ([CRY-9]). */
+export const DRAW_ATTEMPTS = 64;
+
+/** Whether an Ed25519 seed may be used for a new key: its first byte is not zero ([CRY-9]). */
+export function usableSeed(seed) {
+  return seed[0] !== 0;
+}
+
+// [IMP-6]: WebKit's WebCrypto rejects a pkcs8 Ed25519 seed whose first byte is zero, but signs with it when it is
+// imported as a JWK with its public key. Public keys of seeds checked against a key on record (ed25519PublicIs) are
+// kept here, keyed by the seed's buffer, so that later signatures with the same buffer can use that import. Nothing
+// here is secret, and nothing is added without the check.
+const CHECKED = new WeakMap();
+
+function b64u(bytes) {
+  let b = "";
+  for (const x of bytes) b += String.fromCharCode(x);
+  return btoa(b).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+async function importJwk(seed, publicKey, extractable) {
+  const jwk = { kty: "OKP", crv: "Ed25519", d: b64u(seed), x: b64u(publicKey), ext: extractable };
+  try {
+    return await subtle.importKey("jwk", jwk, { name: "Ed25519" }, extractable, ["sign"]);
+  } finally {
+    jwk.d = "";
+  }
+}
+
 /** The Ed25519 public key of a 32-byte seed ([CRY-2]). */
 export async function ed25519Public(seed) {
-  return publicOf(ED_PKCS8, "Ed25519", seed, ["sign"]);
+  try {
+    return await publicOf(ED_PKCS8, "Ed25519", seed, ["sign"]);
+  } catch (e) {
+    const known = CHECKED.get(seed);
+    if (known) return known.slice();
+    throw e;
+  }
 }
 
-/** Import an Ed25519 seed as a non-extractable signing key ([IMP-2]). */
+/**
+ * Whether the Ed25519 public key of `seed` is `publicKey` (raw 32 bytes). Where the platform cannot import the seed
+ * ([IMP-6]), the import of the seed with `publicKey` answers it, since the platform rejects a public key that does
+ * not belong to the seed; the key is then remembered for signing with this seed buffer.
+ */
+export async function ed25519PublicIs(seed, publicKey) {
+  let pub;
+  try {
+    pub = await publicOf(ED_PKCS8, "Ed25519", seed, ["sign"]);
+  } catch {
+    try {
+      await importJwk(seed, publicKey, false);
+    } catch {
+      return false;
+    }
+    CHECKED.set(seed, Uint8Array.from(publicKey));
+    return true;
+  }
+  return pub.length === publicKey.length && pub.every((b, i) => b === publicKey[i]);
+}
+
+/** Import an Ed25519 seed as a non-extractable signing key ([IMP-2], [IMP-6]). */
 export async function ed25519SigningKey(seed) {
-  return importPrivate(ED_PKCS8, "Ed25519", seed, false, ["sign"]);
+  try {
+    return await importPrivate(ED_PKCS8, "Ed25519", seed, false, ["sign"]);
+  } catch (e) {
+    const known = CHECKED.get(seed);
+    if (known) return importJwk(seed, known, false);
+    throw e;
+  }
 }
 
 /** A deterministic Ed25519 signature ([CRY-8]). `key` is a seed or a key from ed25519SigningKey. */
@@ -150,20 +212,41 @@ export async function ed25519Verify(publicKey, m, sig) {
   if (!ok) fail("bad_signature");
 }
 
+// An X25519 secret as WebCrypto imports it. WebKit's WebCrypto on Linux rejects a secret whose first byte is zero
+// (DataError), probably because it handles the key as a big integer, so ~1 in 256 secrets failed there. X25519 clamps
+// every secret (RFC 7748 §5: the low 3 bits of the first byte cleared, the top bit of the last cleared and the next
+// set), so a zero first byte is given as 1 and a zero last byte as 0x40: the same scalar, the same keys and results.
+function x25519Secret(secret) {
+  const c = Uint8Array.from(secret);
+  if (c.length === 32) {
+    if (c[0] === 0) c[0] = 1;
+    if (c[31] === 0) c[31] = 0x40;
+  }
+  return c;
+}
+
 /** The X25519 public key of a 32-byte secret ([CRY-2]). */
 export async function x25519Public(secret) {
-  return publicOf(X_PKCS8, "X25519", secret, ["deriveBits"]);
+  const c = x25519Secret(secret);
+  try {
+    return await publicOf(X_PKCS8, "X25519", c, ["deriveBits"]);
+  } finally {
+    c.fill(0);
+  }
 }
 
 /** X25519 key agreement; an all-zero result fails ([CRY-4]). → bad_key */
 export async function x25519(secret, publicKey) {
   let bits;
+  const c = x25519Secret(secret);
   try {
-    const priv = await importPrivate(X_PKCS8, "X25519", secret, false, ["deriveBits"]);
+    const priv = await importPrivate(X_PKCS8, "X25519", c, 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");
+  } finally {
+    c.fill(0);
   }
   if (bits.every((b) => b === 0)) fail("bad_key");
   return bits;

package/src/index.js

@@ -13,9 +13,9 @@ export { canonical, canonicalString, parseJson, parseLimited, validate } from ".
 export {
   base64urlEncode, base64urlDecode, base32Encode, base32Decode, base32DecodeLenient, hexEncode, hexDecode,
 } from "./encoding.js";
-export { checkSupport, sha256, ed25519Public, ed25519Sign, ed25519Verify, ed25519SigningKey } from "./crypto.js";
+export { checkSupport, sha256, ed25519Public, ed25519PublicIs, ed25519Sign, ed25519Verify, ed25519SigningKey, usableSeed } from "./crypto.js";
 export { formatKey, parseKey } from "./keys.js";
-export { formatRecoveryKey, parseRecoveryKey, deriveRecoveryKeys } from "./recovery.js";
+export { formatRecoveryKey, parseRecoveryKey, deriveRecoveryKeys, newRecoveryKey, checkNewRecoveryKey } from "./recovery.js";
 export {
   checkRealm, checkUsername, defaultUsernamePolicy, similarUsernames, accountId, inception, tag, handle, parseHandle,
   handleMatches, extendedTags,

package/src/log.js

@@ -3,7 +3,7 @@
 
 import { fail } from "./errors.js";
 import { base64urlEncode, base64urlDecode, bytesEqual } from "./encoding.js";
-import { ed25519Public, ed25519Sign, ed25519Verify, frameObject, sha256 } from "./crypto.js";
+import { ed25519Public, ed25519PublicIs, 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";
@@ -275,7 +275,7 @@ export async function addReceipt(e, hostSeed) {
 
 /** [RK-5] → wrong_recovery_key */
 export async function checkRecoveryKey(state, seed) {
-  if (formatKey("ed25519", await ed25519Public(seed)) !== state.recovery) fail("wrong_recovery_key");
+  if (!(await ed25519PublicIs(seed, s.parseKey(state.recovery, "ed25519")))) fail("wrong_recovery_key");
 }
 
 /** A pending instance ([LOG-9]). `home` is `{ key: "ed25519:…", url }`. */

package/src/proof.js

@@ -2,7 +2,7 @@
 
 import { fail } from "./errors.js";
 import { base64urlEncode } from "./encoding.js";
-import { ed25519Public, ed25519Sign, ed25519Verify, frameObject, sha256 } from "./crypto.js";
+import { ed25519PublicIs, ed25519Sign, ed25519Verify, frameObject, sha256 } from "./crypto.js";
 import { utf8 } from "./encoding.js";
 import { validate, without } from "./json.js";
 import * as s from "./keys.js";
@@ -24,11 +24,10 @@ function checkRecipient(r) {
 /** 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");
+    if (!(await ed25519PublicIs(seed, s.parseKey(state.instance.account_key, "ed25519")))) fail("wrong_account_key");
     p.instance = state.instance.hash;
   } else {
     await checkRecoveryKey(state, seed);

package/src/recovery.js

@@ -2,7 +2,7 @@
 
 import { fail } from "./errors.js";
 import { B32, base32Decode, base32Encode, base32Normalize, bytesEqual } from "./encoding.js";
-import { ed25519Public, frame, frameObject, hkdf, sha256 } from "./crypto.js";
+import { DRAW_ATTEMPTS, ed25519Public, frame, frameObject, hkdf, sha256, usableSeed } from "./crypto.js";
 import { label } from "./labels.js";
 
 async function checksum(key) {
@@ -41,6 +41,28 @@ export async function deriveRecoveryKeys(rk, realm, username) {
   };
 }
 
+/**
+ * Generate a recovery key for an identity ([RK-3]): 32 random bytes, drawn again while the derived signing seed is
+ * unusable ([CRY-9]). Draws: 32 bytes per attempt. → bad_key only for a broken generator.
+ */
+export async function newRecoveryKey(realm, username, random) {
+  for (let i = 0; i < DRAW_ATTEMPTS; i++) {
+    const rk = random(32);
+    const keys = await deriveRecoveryKeys(rk, realm, username);
+    const ok = usableSeed(keys.signSeed);
+    keys.signSeed.fill(0);
+    keys.boxSecret.fill(0);
+    if (ok) return rk;
+    rk.fill(0);
+  }
+  fail("bad_key");
+}
+
+/** A new recovery key must give a usable signing seed ([CRY-9]). → bad_key */
+export function checkNewRecoveryKey(keys) {
+  if (!usableSeed(keys.signSeed)) fail("bad_key");
+}
+
 /** The public recovery signing key. */
 export async function recoverySignPublic(keys) {
   return ed25519Public(keys.signSeed);

package/src/vault.js

@@ -7,7 +7,7 @@
 import { fail } from "./errors.js";
 import { base64urlDecode, base64urlEncode, concat, utf8 } from "./encoding.js";
 import {
-  aesGcmDecrypt, aesGcmEncrypt, ed25519Public, ed25519Sign, frameObject, hkdf, sha256, x25519, x25519Public,
+  aesGcmDecrypt, aesGcmEncrypt, DRAW_ATTEMPTS, ed25519Public, ed25519PublicIs, ed25519Sign, frameObject, hkdf, sha256, usableSeed, x25519, x25519Public,
 } from "./crypto.js";
 import { argon2id } from "./argon2.js";
 import { canonical, parseLimited } from "./json.js";
@@ -136,9 +136,13 @@ export async function unlockVault(vault, state, secret) {
   const contents = checkContents(parseLimited(pt, CONTENTS_LIMIT));
   pt.fill(0);
   if (!state.instance) fail("no_instance");
-  if (formatKey("ed25519", await ed25519Public(contents.accountSeed)) !== state.instance.account_key) {
+  if (!(await ed25519PublicIs(contents.accountSeed, s.parseKey(state.instance.account_key, "ed25519")))) {
     fail("wrong_account_key");
   }
+  // Check the signing seed of the lock against its key on record, so that a platform that cannot import it signs
+  // with it anyway ([IMP-6]); a mismatch is not this function's to judge (a login with it fails at the host).
+  const signKey = lockId === "recovery" ? state.recovery : lock.value.auth;
+  await ed25519PublicIs(lockSeed, s.parseKey(signKey, "ed25519"));
   return { vaultKey: vk, contents, lock: lockId, lockSeed, info };
 }
 
@@ -167,13 +171,29 @@ function kdfValue(kdf, salt) {
   return { alg: "argon2id", m: kdf.m, t: kdf.t, p: kdf.p, salt: base64urlEncode(salt) };
 }
 
-/** Create a new password lock's public part. Draws: slot id (8), salt (16). Returns `[slot, lockPublic]`. */
+/** A new salt and its lock secrets, drawn again while the auth seed is unusable ([CRY-9]). → bad_key (broken generator) */
+async function newLockSecrets(account, lock, password, kdf, random) {
+  for (let i = 0; i < DRAW_ATTEMPTS; i++) {
+    const salt = random(16);
+    const ls = await deriveLockSecrets(account, lock, password, kdf, salt);
+    if (usableSeed(ls.authSeed)) return [salt, ls];
+    ls.authSeed.fill(0);
+    ls.boxSecret.fill(0);
+  }
+  fail("bad_key");
+}
+
+/**
+ * Create a new password lock's public part. `slot` is `{ label, password, username, kdf }`; the password must satisfy
+ * [LCK-8] for `username` (`weak_password`), as in every function that creates a password lock. Draws: slot id (8),
+ * salt (16, again while the auth seed is unusable, [CRY-9]). Returns `[slot, lockPublic]`.
+ */
 export async function newPasswordLock(account, slot, random) {
+  checkPassword(slot.password, slot.username);
   checkLabel(slot.label);
   const id = base64urlEncode(random(8));
-  const salt = random(16);
   const kdf = { m: slot.kdf.m, t: slot.kdf.t, p: slot.kdf.p ?? 1 };
-  const ls = await deriveLockSecrets(account, id, slot.password, kdf, salt);
+  const [salt, ls] = await newLockSecrets(account, id, slot.password, kdf, random);
   const pub = {
     id,
     kdf: kdfValue(kdf, salt),
@@ -244,16 +264,17 @@ export async function updateContents(u, vault, contents, random) {
 }
 
 /**
- * A password change ([CHG-1] step 1). Draws: salt (16), wrap (32 + 12), contents nonce (12).
+ * A password change ([CHG-1] step 1); the new password must satisfy [LCK-8] for `username` (`weak_password`).
+ * Draws: salt (16), wrap (32 + 12), contents nonce (12).
  * Returns `{ vault, new }` where `new` is `SHA-256(canonical(new lock))`.
  */
-export async function changePassword(u, vault, slot, password, kdf, random) {
+export async function changePassword(u, vault, slot, password, username, kdf, random) {
+  checkPassword(password, username);
   const { account, instance, grant } = idsOf(u, vault);
   const index = u.info.locks.findIndex((l) => l.kind === "password" && l.id === slot);
   if (index < 0) fail("bad_locks");
-  const salt = random(16);
   const k = { m: kdf.m, t: kdf.t, p: kdf.p ?? 1 };
-  const ls = await deriveLockSecrets(account, slot, password, k, salt);
+  const [salt, ls] = await newLockSecrets(account, slot, password, k, random);
   const box = await x25519Public(ls.boxSecret);
   const pub = { id: slot, kdf: kdfValue(k, salt), auth: formatKey("ed25519", await ed25519Public(ls.authSeed)), box: formatKey("x25519", box) };
   ls.authSeed.fill(0);