path: root/packages/meshbay-hub/src/meshbay_hub/static/keyderive.js

/**
 * MeshBay Browser Key Management — keyderive.js
 *
 * Web registration flow (avoids algorithm mismatch with Python Argon2id):
 *
 * REGISTRATION:
 *   1. Browser generates RANDOM Ed25519 + X25519 keypairs via WebCrypto
 *   2. Bundle (sk_ed || sk_x) is encrypted with AES-256-GCM
 *      using a key derived from password via PBKDF2-SHA512
 *   3. Encrypted bundle + public keys sent to hub for storage
 *
 * LOGIN (new device):
 *   1. Hub returns the encrypted bundle
 *   2. Browser decrypts it locally with the password
 *   3. Private keys loaded into memory (never leave the browser)
 *
 * Password change: re-encrypt bundle with new password-derived key.
 *
 * Keys never leave the browser in cleartext.
 * Hub stores: public keys + encrypted bundle (cannot read private keys).
 */

const PBKDF2_ITERATIONS = 600000;  // OWASP 2023 recommendation for PBKDF2-SHA512
/**
 * Where the hub is, and how to reach it — resolved when a call is made, not
 * when this file loads.
 *
 * This used to be `const HUB = ''`, "same origin", which is true of a page the
 * hub served and false of one loaded from a package: there the origin is
 * `app://meshbay`, so `/v1/users/register` resolved against it and the
 * application's own protocol handler answered 404. Registration and sign-in —
 * the first two things anybody does — failed with "Not found".
 *
 * This is a classic script, loaded before the module graph, so it cannot import
 * the adapter. It reads the global the adapter publishes, at call time: by then
 * `platform.js` has run, and in a browser both of these are exactly what they
 * were before.
 */
function hubBase() {
  const p = typeof window !== 'undefined' && window.MeshBayPlatform;
  return p ? p.hubBase() : '';
}

function hubCall(path, init) {
  const p = typeof window !== 'undefined' && window.MeshBayPlatform;
  return p && p.apiFetch ? p.apiFetch(hubBase() + path, init)
                         : fetch(hubBase() + path, init);
}

// ── Auth key derivation (password split) ──────────────────────────────────────

/**
 * Derive an auth key from password + username using PBKDF2-SHA512.
 * This key is sent to the hub for authentication — the raw password never leaves the browser.
 * Uses a different salt domain than deriveEncryptionKey (bundle key), so the two
 * derived values are cryptographically independent.
 */
async function deriveAuthKey(password, username) {
  const enc = new TextEncoder();
  const km = await crypto.subtle.importKey(
    'raw', enc.encode(password), 'PBKDF2', false, ['deriveBits']);
  const salt = await crypto.subtle.digest(
    'SHA-256', enc.encode(`meshbay:auth:v1:${username}`));
  const bits = await crypto.subtle.deriveBits(
    { name: 'PBKDF2', hash: 'SHA-512', salt, iterations: PBKDF2_ITERATIONS },
    km, 256);
  return btoa(String.fromCharCode(...new Uint8Array(bits)));
}

// ── Key generation ────────────────────────────────────────────────────────────

/**
 * Generate random Ed25519 + X25519 keypairs using WebCrypto.
 * Returns raw bytes for both (not CryptoKey objects, for easier serialisation).
 */
async function generateKeypairs() {
  // Ed25519 (signing)
  const edKey = await crypto.subtle.generateKey(
    { name: 'Ed25519' }, true, ['sign', 'verify']);
  const skEdRaw = await crypto.subtle.exportKey('pkcs8', edKey.privateKey);
  const pkEdRaw = await crypto.subtle.exportKey('spki',  edKey.publicKey);

  // X25519 (key agreement)
  const xKey = await crypto.subtle.generateKey(
    { name: 'X25519' }, true, ['deriveBits']);
  const skXRaw = await crypto.subtle.exportKey('pkcs8', xKey.privateKey);
  const pkXRaw = await crypto.subtle.exportKey('spki',  xKey.publicKey);

  return { skEdRaw, pkEdRaw, skXRaw, pkXRaw };
}

// ── Password → AES key ────────────────────────────────────────────────────────

// Argon2id parameters for the keypair bundle.
//
// This is the one KDF in the browser that guards something an adversary can take
// away and attack at leisure: the bundle is stored on every node whose group its
// owner joins (finding C4). PBKDF2 was the wrong tool — it is compute-only, which
// is exactly what a GPU is good at, so 600k iterations bought far less than the
// wall-clock time suggested.
//
// 128 MB / t=3 / p=1 measured at ~640 ms through this WASM build on a desktop.
// Memory is the lever, not time: each guess must hold 128 MB, so a 24 GB card
// fits ~187 in parallel and its bandwidth caps it near 2k guesses/s, against no
// ceiling at all for PBKDF2. 256 MB would double that again at ~1.3 s, which is
// too much to ask of a phone for something paid at every sign-in.
const ARGON2_MEM_KIB = 131072;   // 128 MB
const ARGON2_TIME    = 3;
const ARGON2_LANES   = 1;

// Bundles written before this carry no marker and are read with the old KDF.
// They are re-encrypted the first time their owner signs in (see upgradeBundle).
const BUNDLE_V2_MAGIC = 'MBK2';

function _argon2() {
  const a = (typeof window !== 'undefined' && window.argon2) || globalThis.argon2;
  if (!a) throw new Error('Argon2 unavailable — vendor/argon2.min.js did not load');
  return a;
}

/** Legacy: PBKDF2-SHA512. Kept to read bundles written before the change. */
async function deriveEncryptionKeyV1(password, username) {
  const enc   = new TextEncoder();
  const km    = await crypto.subtle.importKey(
    'raw', enc.encode(password), 'PBKDF2', false, ['deriveKey']);
  const salt  = await crypto.subtle.digest(
    'SHA-256', enc.encode(`meshbay:bundle:v1:${username}`));
  return crypto.subtle.deriveKey(
    { name: 'PBKDF2', hash: 'SHA-512', salt, iterations: PBKDF2_ITERATIONS },
    km,
    { name: 'AES-GCM', length: 256 },
    false,
    ['encrypt', 'decrypt'],
  );
}

/**
 * Derive the bundle key with Argon2id.
 *
 * The salt stays deterministic and domain-separated per user, as before: it is
 * what lets the key be derived once at sign-in and kept, instead of holding the
 * passphrase in memory to re-derive it whenever a bundle turns up. It is unique
 * per account, so it does what a salt is for — no shared precomputation.
 */
async function _bundleKeyBytes(password, username) {
  const enc  = new TextEncoder();
  const salt = new Uint8Array(await crypto.subtle.digest(
    'SHA-256', enc.encode(`meshbay:bundle:v2:${username}`))).slice(0, 16);
  const out = await _argon2().hash({
    pass: password, salt,
    time: ARGON2_TIME, mem: ARGON2_MEM_KIB, parallelism: ARGON2_LANES,
    hashLen: 32, type: _argon2().ArgonType.Argon2id,
  });
  return out.hash;
}

async function deriveEncryptionKey(password, username) {
  return crypto.subtle.importKey(
    'raw', await _bundleKeyBytes(password, username),
    { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']);
}

/**
 * The bundle key as **two handles over one Argon2 run**.
 *
 * `aes` is what has always been returned: the key that opens a node's identity
 * bundle. `hkdf` is the same 32 bytes imported a second time as an HKDF key,
 * from which purpose-separated subkeys can be derived — playlists are the
 * first (docs/playlists.md §3.4).
 *
 * It has to be a second import of the same bytes, and not a derivation from
 * `aes`: that one is imported non-extractably with `['encrypt','decrypt']`, so
 * nothing can be derived from it at all. And it has to be one Argon2 run: a
 * second call would put another ~650 ms on the sign-in path for a key that is
 * mathematically identical.
 *
 * A subkey rather than the bundle key reused with a different AAD, for the
 * reason `groupbox.py` already writes down for chunk keys — purpose separation
 * is what stops one use's mistake becoming every use's.
 */
async function deriveBundleKeys(password, username) {
  const raw = await _bundleKeyBytes(password, username);
  return {
    aes: await crypto.subtle.importKey(
      'raw', raw, { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']),
    // HKDF keys are non-extractable by specification; `false` is the only
    // value this accepts.
    hkdf: await crypto.subtle.importKey('raw', raw, 'HKDF', false, ['deriveKey']),
  };
}

// ── Account recovery key ─────────────────────────────────────────────────────
//
// docs/MESHBAY_DESIGN.md §3.6. A full-entropy secret the user keeps outside the
// passphrase — in their password manager, or (step 3) e-mailed to them. It
// wraps a *second* copy of every per-node identity bundle, so a forgotten
// passphrase does not strand the account's group identities.
//
// 256 bits of real entropy, so the derivation is HKDF, not Argon2: there is
// nothing to brute-force and no reason to make the legitimate path slow. The
// username domain-separates it, exactly as for the bundle key.

const _B32 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';   // RFC 4648, no padding

/** 32 random bytes, shown to the human as 13 groups of 4 Base32 chars. */
function generateRecoveryKey() {
  const R = crypto.getRandomValues(new Uint8Array(32));
  return {
    rawB64: btoa(String.fromCharCode(...R)),
    mnemonic: _toMnemonic(R),
  };
}

function _toMnemonic(bytes) {
  let bits = 0, value = 0, out = '';
  for (const b of bytes) {
    value = (value << 8) | b;
    bits += 8;
    while (bits >= 5) { out += _B32[(value >>> (bits - 5)) & 31]; bits -= 5; }
  }
  if (bits > 0) out += _B32[(value << (5 - bits)) & 31];
  return out.replace(/(.{4})(?=.)/g, '$1 ');
}

function _fromMnemonic(mnemonic) {
  const clean = String(mnemonic).replace(/[^A-Za-z2-7]/g, '').toUpperCase();
  let bits = 0, value = 0;
  const out = [];
  for (const ch of clean) {
    const idx = _B32.indexOf(ch);
    if (idx < 0) throw new Error('invalid recovery key');
    value = (value << 5) | idx;
    bits += 5;
    if (bits >= 8) { out.push((value >>> (bits - 8)) & 0xff); bits -= 8; }
  }
  if (out.length < 32) throw new Error('recovery key too short');
  return new Uint8Array(out.slice(0, 32));
}

/**
 * Derive the AES-GCM key that wraps the recovery copy of a bundle.
 * `R` is the raw Uint8Array(32) or its Base32 mnemonic string.
 */
async function deriveRecoveryKey(R, username) {
  const raw = (typeof R === 'string') ? _fromMnemonic(R) : new Uint8Array(R);
  const km = await crypto.subtle.importKey('raw', raw, 'HKDF', false, ['deriveKey']);
  return crypto.subtle.deriveKey(
    {
      name: 'HKDF', hash: 'SHA-256',
      salt: new Uint8Array(0),
      info: new TextEncoder().encode(`meshbay:recovery:v1:${username}`),
    },
    km, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
}

// ── Bundle encryption ─────────────────────────────────────────────────────────

/**
 * Encrypt the keypair bundle with the password-derived AES key.
 * Bundle format: JSON { skEd: base64(pkcs8), skX: base64(pkcs8) }
 */
async function encryptBundle(skEdRaw, skXRaw, password, username) {
  const aesKey = await deriveEncryptionKey(password, username);
  return encryptBundleWithKey(skEdRaw, skXRaw, aesKey);
}

/** Same, when the key was already derived at sign-in. Always writes v2. */
async function encryptBundleWithKey(skEdRaw, skXRaw, aesKey) {
  const nonce  = crypto.getRandomValues(new Uint8Array(12));
  const data   = new TextEncoder().encode(JSON.stringify({
    skEd: btoa(String.fromCharCode(...new Uint8Array(skEdRaw))),
    skX:  btoa(String.fromCharCode(...new Uint8Array(skXRaw))),
  }));
  const ct = await crypto.subtle.encrypt({ name: 'AES-GCM', iv: nonce }, aesKey, data);
  // base64( "MBK2" || nonce || ciphertext ). The marker is what tells a reader
  // which KDF produced the key, so old bundles stay readable and new ones are
  // never fed to the old derivation.
  const magic = new TextEncoder().encode(BUNDLE_V2_MAGIC);
  const out = new Uint8Array(magic.length + nonce.length + ct.byteLength);
  out.set(magic);
  out.set(nonce, magic.length);
  out.set(new Uint8Array(ct), magic.length + nonce.length);
  return btoa(String.fromCharCode(...out));
}

function bundleVersion(bundleB64) {
  try {
    return atob(bundleB64).startsWith(BUNDLE_V2_MAGIC) ? 2 : 1;
  } catch { return 1; }
}

/**
 * Decrypt a keypair bundle. Throws if password is wrong.
 */
async function decryptBundle(bundleB64, password, username) {
  const key = bundleVersion(bundleB64) === 2
    ? await deriveEncryptionKey(password, username)
    : await deriveEncryptionKeyV1(password, username);
  return decryptBundleWithKey(bundleB64, key);
}

// ── Registration ──────────────────────────────────────────────────────────────

/**
 * Full registration flow:
 * 1. Generate random keypairs
 * 2. Encrypt bundle with password
 * 3. POST to hub (public keys only — no keypair bundle)
 * 4. Store encrypted bundle locally for backup to node on first connect
 *
 * Returns the raw private keys for immediate use after registration.
 */
async function registerUser(username, email, password, recoveryMnemonic, captchaToken) {
  // No keypair here any more. Identity keys are per node: one is generated the
  // first time this account joins a given node, encrypted under the passphrase,
  // and left with that node. So an operator who cracks what sits on their own
  // disk holds a key that is worthless anywhere else — and on their own node,
  // one that unlocks nothing they did not already have.
  //
  // It also means the hub stores no user key to publish, which is what H3 read.
  const authKey = await deriveAuthKey(password, username);

  const payload = { username, email, auth_key: authKey };
  // The recovery mnemonic, when the user opted to have it e-mailed: the hub
  // appends it to the verification e-mail and stores it nowhere
  // (docs/MESHBAY_DESIGN.md §3.6). Omitted when they chose to save it themselves.
  if (recoveryMnemonic) payload.recovery_key = recoveryMnemonic;
  // reCAPTCHA response, when the hub has a captcha configured. The widget lives
  // in RegisterPage (auth-page.js); this function just forwards its token. A
  // hub with no captcha configured sends nothing and the server does not check.
  if (captchaToken) payload.captcha_token = captchaToken;

  const resp = await hubCall('/v1/users/register', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload),
  });

  if (!resp.ok) throw new Error(`Registration failed: ${await resp.text()}`);
  return { registered: true };
}

/**
 * A fresh identity for one node, encrypted under the passphrase-derived key.
 *
 * Returns { skEdB64, skXB64, pkXB64, bundleEnc, bundleEncRecovery? } — the
 * bundle goes to that node and nowhere else, and is what any other browser
 * fetches to become the same person there. When `recoveryKey` is supplied a
 * second copy wrapped under it rides along, so a forgotten passphrase does not
 * strand this identity (docs/MESHBAY_DESIGN.md §3.6).
 */
async function generateNodeIdentity(bundleKey, recoveryKey) {
  const { skEdRaw, pkEdRaw, skXRaw, pkXRaw } = await generateKeypairs();
  const b64 = (buf) => btoa(String.fromCharCode(...new Uint8Array(buf)));
  const pkXCrypto = await crypto.subtle.importKey('spki', pkXRaw, { name: 'X25519' }, true, []);
  const pkXBytes = new Uint8Array(await crypto.subtle.exportKey('raw', pkXCrypto));
  const out = {
    skEdB64: b64(skEdRaw),
    skXB64: b64(skXRaw),
    pkXB64: b64(pkXBytes),
    bundleEnc: await encryptBundleWithKey(skEdRaw, skXRaw, bundleKey.v2 || bundleKey),
  };
  if (recoveryKey) {
    out.bundleEncRecovery = await encryptBundleWithKey(skEdRaw, skXRaw, recoveryKey);
  }
  return out;
}

/**
 * Decrypt a keypair bundle using a pre-derived AES-256 CryptoKey.
 * Used when the bundle is fetched from the node (bundleKey was derived at login).
 */
async function decryptBundleWithKey(bundleB64, aesKeyOrPair) {
  const v2  = bundleVersion(bundleB64) === 2;
  // Callers derive both keys at sign-in and pass the pair, because which one a
  // bundle needs is only known once it has been read — and the passphrase is
  // deliberately not kept around to derive the other one later.
  const key = (aesKeyOrPair && aesKeyOrPair.v2)
    ? (v2 ? aesKeyOrPair.v2 : aesKeyOrPair.v1)
    : aesKeyOrPair;
  const raw   = Uint8Array.from(atob(bundleB64), c => c.charCodeAt(0));
  const off   = v2 ? BUNDLE_V2_MAGIC.length : 0;
  const nonce = raw.slice(off, off + 12);
  const ct    = raw.slice(off + 12);
  const plain = await crypto.subtle.decrypt({ name: 'AES-GCM', iv: nonce }, key, ct);
  return JSON.parse(new TextDecoder().decode(plain));
}

/**
 * Login and recover private keys.
 *
 * If localStorage has a keypair bundle (new registration, not yet pushed to node),
 * decrypts it and returns the keys + encrypted bundle for push to node.
 * Otherwise returns bundleKey so the caller can fetch from node during handshake.
 */
async function loginAndRecover(username, password) {
  const authKey = await deriveAuthKey(password, username);

  const resp = await hubCall('/v1/users/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ username, auth_key: authKey }),
  });

  if (!resp.ok) {
    // The hub's `detail`, not the raw body: the sign-in page matches on it
    // (`email_verification_required`, `account_locked`), and a message wrapped
    // as "Login failed: {json}" matched nothing, so neither was ever shown.
    const body = await resp.text();
    let detail = body;
    // `error` is the per-IP rate limiter's field (slowapi), `detail` everyone else's.
    try {
      const j = JSON.parse(body);
      detail = j.detail || j.error || body;
    } catch { /* not JSON */ }
    const err = new Error(String(detail));
    err.status = resp.status;
    err.retryAfter = Number(resp.headers && resp.headers.get
      ? resp.headers.get('Retry-After') : 0) || 0;
    throw err;
  }

  const data   = await resp.json();
  const result = {
    accessToken:  data.access_token,
    refreshToken: data.refresh_token,
    // Both, so a bundle written before the KDF changed can still be opened —
    // and re-written with the new one on the next backup.
    bundleKey: {
      ...(await _bundleKeyPairFields(password, username)),
      v1: await deriveEncryptionKeyV1(password, username),
    },
  };

  // Nothing else to recover at sign-in. Identity keys belong to a node, so they
  // are fetched from the node being connected to (or generated there on a first
  // join) — see transport.js. All that is needed here is the key that opens them.
  return result;
}

// regenerateKeys() removed. Rotating an identity is now per node: the operator
// runs `meshbay-node member unpin <user>` and issues a fresh code. A hub call
// that silently changed what every node believed about someone was the wrong
// shape for this.

async function signBytes(skEdPkcs8B64, message) {
  const skRaw = Uint8Array.from(atob(skEdPkcs8B64), c => c.charCodeAt(0));
  const sk = await crypto.subtle.importKey(
    'pkcs8', skRaw, { name: 'Ed25519' }, false, ['sign']);
  const sig = await crypto.subtle.sign('Ed25519', sk, message);
  return btoa(String.fromCharCode(...new Uint8Array(sig)));
}

/**
 * `{ v2, v2hkdf }` — the two fields every `session.bundleKey` carries for the
 * current KDF. One helper because there are two places that build that object
 * and they must not drift: a `v2hkdf` missing from one of them is a playlist
 * store that silently does nothing on whichever sign-in path skipped it.
 */
async function _bundleKeyPairFields(password, username) {
  const { aes, hkdf } = await deriveBundleKeys(password, username);
  return { v2: aes, v2hkdf: hkdf };
}

window.MeshBayKeys = {
  registerUser, loginAndRecover, generateNodeIdentity, generateKeypairs, signBytes,
  deriveAuthKey, decryptBundleWithKey, encryptBundleWithKey, bundleVersion,
  // Exposed for the passphrase change (docs/MESHBAY_DESIGN.md §3.6): re-wrapping a
  // node's identity bundle needs the old key (a {v2,v1} pair, since an old
  // bundle may be v1) to read it and the new v2 key to write it back.
  deriveEncryptionKey, deriveEncryptionKeyV1,
  // One Argon2 run, an AES handle and an HKDF handle. Whatever builds a
  // `session.bundleKey` uses this, so `v2hkdf` is never the field one sign-in
  // path forgot (docs/playlists.md §3.4).
  deriveBundleKeys, bundleKeyPairFields: _bundleKeyPairFields,
  // Account recovery key (docs/MESHBAY_DESIGN.md §3.6).
  generateRecoveryKey, deriveRecoveryKey,
};