ciphermesh 2.12.0 → 2.14.0

package/src/client/keyboard.js

@@ -0,0 +1,388 @@
+// Keyboard-protocol shim.
+//
+// Terminals cannot tell Shift+Enter from Enter unless the application asks them
+// to: with no protocol negotiated both arrive as a bare `\r`. The two ways to
+// ask are the kitty keyboard protocol (`CSI > 1 u`, reported as `CSI 13;2 u`)
+// and xterm's modifyOtherKeys (`CSI > 4 ; 1 m`, reported as `CSI 27;2;13 ~`).
+//
+// Asking is only half of it. blessed's key parser splits input with
+//
+//   (?:\x1b+)(O|N|\[|\[\[)(?:(\d+)(?:;(\d+))?([~^$])|…|(?:1;)?(\d+)?([a-zA-Z]))
+//
+// which matches neither a `u` final byte after two parameters nor a `~` after
+// three. Both reports fall through to blessed's `/\x1b./` catch-all, so it
+// consumes `\x1b[` and emits the rest — `13;2u` — as ordinary characters typed
+// into the composer. The same regex is why `\x1b\r` (Alt+Enter) reaches blessed
+// with `key.name === undefined`.
+//
+// So the reports are decoded here, upstream of blessed, on the raw byte stream:
+// Enter with a modifier becomes a newline event, every other enhanced report is
+// rewritten to the legacy encoding blessed already understands, and anything
+// unrecognised is passed through untouched. Nothing new can reach the composer
+// as literal text, which is the property that makes enabling a protocol safe.
+
+import { PassThrough } from 'node:stream';
+import { StringDecoder } from 'node:string_decoder';
+
+const ESC = '\x1b';
+const PASTE_START = '\x1b[200~';
+const PASTE_END = '\x1b[201~';
+
+// Ask for both protocols. Terminals that implement neither ignore both; ones
+// that implement the kitty protocol let it take precedence over modifyOtherKeys.
+// Level 1 of modifyOtherKeys is deliberate — level 2 also re-encodes Ctrl+C and
+// friends, which is a much larger blast radius for a newline.
+export const KEY_PROTOCOL_ENABLE = '\x1b[>4;1m\x1b[>1u';
+export const KEY_PROTOCOL_DISABLE = '\x1b[<u\x1b[>4;0m';
+
+// Modifier bits, as reported minus one.
+const MOD_SHIFT = 1;
+const MOD_ALT = 2;
+const MOD_CTRL = 4;
+
+// Kitty's private-use range for keys with no Unicode code point. Under the
+// disambiguate flag most of these keep their legacy encoding, but the keypad
+// reports through CSI u, so the ones that produce text are mapped back.
+const KEYPAD = new Map([
+  [57399, '0'],
+  [57400, '1'],
+  [57401, '2'],
+  [57402, '3'],
+  [57403, '4'],
+  [57404, '5'],
+  [57405, '6'],
+  [57406, '7'],
+  [57407, '8'],
+  [57408, '9'],
+  [57409, '.'],
+  [57410, '/'],
+  [57411, '*'],
+  [57412, '-'],
+  [57413, '+'],
+  [57414, '\r'], // KP_ENTER
+  [57415, '='],
+]);
+
+/**
+ * The control byte a Ctrl+<key> chord produces on a legacy terminal, or '' when
+ * the chord has no legacy encoding (Ctrl+1, say). Pure, exported for testing.
+ */
+export function ctrlByte(code) {
+  if (code >= 97 && code <= 122) {
+    return String.fromCharCode(code - 96); // ctrl+a … ctrl+z
+  }
+  if (code >= 65 && code <= 90) {
+    return String.fromCharCode(code - 64); // ctrl+A … ctrl+Z
+  }
+  switch (code) {
+    case 32: // ctrl+space → NUL
+    case 64: // ctrl+@
+      return '\x00';
+    case 91: // ctrl+[
+      return '\x1b';
+    case 92: // ctrl+backslash
+      return '\x1c';
+    case 93: // ctrl+]
+      return '\x1d';
+    case 94: // ctrl+^
+      return '\x1e';
+    case 95: // ctrl+_
+    case 47: // ctrl+/
+      return '\x1f';
+    case 63: // ctrl+?
+      return '\x7f';
+    default:
+      return '';
+  }
+}
+
+/**
+ * Rewrite one decoded key report as the bytes a legacy terminal would have
+ * sent, so blessed's parser sees input it already knows. Returns '' for reports
+ * with no legacy equivalent — dropping them is the point, since letting them
+ * through is what types `13;2u` into the composer. Pure, exported for testing.
+ *
+ * @param {number} code Unicode code point (or a kitty functional key number)
+ * @param {number} mods modifier bitmask, already decremented by one
+ */
+export function toLegacy(code, mods) {
+  const shift = !!(mods & MOD_SHIFT);
+  const alt = !!(mods & MOD_ALT);
+  const ctrl = !!(mods & MOD_CTRL);
+  const meta = (s) => (alt ? ESC + s : s);
+
+  switch (code) {
+    case 13:
+      return meta('\r'); // enter — modified enter is intercepted upstream
+    case 27:
+      return ESC; // escape carries no modifiers in the legacy encoding
+    case 9:
+      return shift ? '\x1b[Z' : meta('\t');
+    case 8:
+    case 127:
+      return meta('\x7f'); // backspace
+  }
+
+  if (KEYPAD.has(code)) {
+    return meta(KEYPAD.get(code));
+  }
+  // Kitty numbers its functional keys inside the Unicode private-use area, so
+  // anything landing there is a key (Caps Lock, media keys, …) rather than a
+  // character. Emitting it would put an invisible glyph in the composer.
+  if (code >= 0xe000 && code <= 0xf8ff) {
+    return '';
+  }
+  if (code < 32 || code > 0x10ffff) {
+    return ''; // control codes we have no encoding for
+  }
+
+  if (ctrl) {
+    const byte = ctrlByte(code);
+    return byte ? meta(byte) : '';
+  }
+  // Kitty reports the *unshifted* code point plus a shift bit.
+  const base = shift && code >= 97 && code <= 122 ? code - 32 : code;
+  return meta(String.fromCodePoint(base));
+}
+
+// Match a CSI sequence starting at `from`. Returns the parameter string and
+// final byte, `null` when the sequence is still incomplete (hold and wait for
+// more input), or `false` when it can never become one.
+function matchCsi(text, from) {
+  let i = from + 2; // past ESC [
+  while (i < text.length) {
+    const c = text.charCodeAt(i);
+    const isParam = (c >= 0x30 && c <= 0x3f) || (c >= 0x20 && c <= 0x2f); // 0-9;:<=>?!"#$%&'()*+,-./
+    if (isParam) {
+      i++;
+      continue;
+    }
+    if (c >= 0x40 && c <= 0x7e) {
+      return { params: text.slice(from + 2, i), final: text[i], end: i + 1 };
+    }
+    return false; // not a CSI sequence after all
+  }
+  return null; // ran out of input mid-sequence
+}
+
+// Parameters as numbers, taking the first sub-parameter of each (kitty uses
+// `code:shifted:base` and `mods:event`, and only the first matters here).
+function numericParams(params) {
+  return params.split(';').map((p) => {
+    const n = Number.parseInt(p.split(':')[0], 10);
+    return Number.isNaN(n) ? 0 : n;
+  });
+}
+
+/**
+ * Decode an enhanced key report into `{ code, mods }`, or null if the sequence
+ * is not one. Understands the kitty form `CSI <code>[;<mods>] u` and xterm's
+ * modifyOtherKeys form `CSI 27;<mods>;<code> ~`. Pure, exported for testing.
+ */
+export function parseEnhancedKey(params, final) {
+  const nums = numericParams(params);
+  if (final === 'u' && !params.startsWith('>') && !params.startsWith('<')) {
+    const code = nums[0];
+    if (!code) {
+      return null;
+    }
+    return { code, mods: Math.max(0, (nums[1] || 1) - 1) };
+  }
+  if (final === '~' && nums.length === 3 && nums[0] === 27) {
+    return { code: nums[2], mods: Math.max(0, (nums[1] || 1) - 1) };
+  }
+  return null;
+}
+
+/** Enter plus any modifier means "new line in the composer", never "send". */
+function isNewline(key) {
+  return key.code === 13 && (key.mods & (MOD_SHIFT | MOD_ALT | MOD_CTRL)) !== 0;
+}
+
+/**
+ * Scan a chunk of raw terminal input, splitting it into what blessed should see
+ * and the newline requests it never could. Pure and incremental — feed the
+ * returned `pending`/`pasting` back in with the next chunk.
+ *
+ * Bracketed-paste blocks are copied through verbatim: text arriving from the
+ * clipboard is data, and a `\x1b\r` inside it is two pasted characters, not a
+ * key chord.
+ *
+ * @returns {{ events: Array<{type: 'data'|'newline', text?: string}>,
+ *             pending: string, pasting: boolean }}
+ */
+export function filterKeys(input, state = {}) {
+  const text = (state.pending || '') + input;
+  let pasting = !!state.pasting;
+  const events = [];
+  let out = '';
+  let i = 0;
+
+  const flush = () => {
+    if (out) {
+      events.push({ type: 'data', text: out });
+      out = '';
+    }
+  };
+
+  while (i < text.length) {
+    if (pasting) {
+      const end = text.indexOf(PASTE_END, i);
+      if (end === -1) {
+        out += text.slice(i);
+        i = text.length;
+        break;
+      }
+      out += text.slice(i, end + PASTE_END.length);
+      i = end + PASTE_END.length;
+      pasting = false;
+      continue;
+    }
+
+    if (text[i] !== ESC) {
+      let j = i;
+      while (j < text.length && text[j] !== ESC) {
+        j++;
+      }
+      out += text.slice(i, j);
+      i = j;
+      continue;
+    }
+
+    if (text.startsWith(PASTE_START, i)) {
+      out += PASTE_START;
+      i += PASTE_START.length;
+      pasting = true;
+      continue;
+    }
+
+    // Alt+Enter as sent by terminals with no protocol negotiated. blessed
+    // cannot name this one either, so it is intercepted here for every
+    // terminal, protocol or not.
+    if (text.startsWith('\x1b\r', i) || text.startsWith('\x1b\n', i)) {
+      flush();
+      events.push({ type: 'newline' });
+      i += 2;
+      continue;
+    }
+
+    if (text.startsWith('\x1b[', i)) {
+      const csi = matchCsi(text, i);
+      if (csi === null) {
+        break; // incomplete — hold it for the next chunk
+      }
+      if (csi === false) {
+        out += text[i];
+        i++;
+        continue;
+      }
+      const key = parseEnhancedKey(csi.params, csi.final);
+      if (!key) {
+        out += text.slice(i, csi.end); // arrows, function keys, mouse — untouched
+        i = csi.end;
+        continue;
+      }
+      if (isNewline(key)) {
+        flush();
+        events.push({ type: 'newline' });
+      } else {
+        out += toLegacy(key.code, key.mods);
+      }
+      i = csi.end;
+      continue;
+    }
+
+    out += text[i];
+    i++;
+  }
+
+  flush();
+  return { events, pending: text.slice(i), pasting };
+}
+
+/**
+ * A stdin stand-in for blessed that has already had the enhanced key reports
+ * taken out of it. Pass it as `blessed.screen({ input })`.
+ *
+ * blessed only needs `data`/`keypress` events plus `setRawMode`, `isRaw` and
+ * `pause`/`resume` from its input, so the raw-mode calls are forwarded to the
+ * real tty and everything else is an ordinary PassThrough.
+ */
+export class EnhancedInput extends PassThrough {
+  #source;
+  #onNewline;
+  #onData;
+  #decoder = new StringDecoder('utf8');
+  #state = { pending: '', pasting: false };
+  #flushTimer = null;
+
+  constructor(source, onNewline) {
+    super();
+    this.#source = source;
+    this.#onNewline = onNewline;
+    this.#onData = (chunk) => this.#feed(chunk);
+    this.#source.on('data', this.#onData);
+  }
+
+  get isTTY() {
+    return !!this.#source.isTTY;
+  }
+
+  get isRaw() {
+    return !!this.#source.isRaw;
+  }
+
+  setRawMode(mode) {
+    this.#source.setRawMode?.(mode);
+    return this;
+  }
+
+  /** Stop consuming the tty (used when the screen is torn down). */
+  detach() {
+    this.#source.removeListener('data', this.#onData);
+    if (this.#flushTimer) {
+      clearTimeout(this.#flushTimer);
+      this.#flushTimer = null;
+    }
+  }
+
+  #feed(chunk) {
+    // Decode through a StringDecoder so a multi-byte character split across two
+    // reads is not turned into replacement characters on the way back out.
+    const text = Buffer.isBuffer(chunk) ? this.#decoder.write(chunk) : String(chunk);
+    if (!text) {
+      return;
+    }
+    const { events, pending, pasting } = filterKeys(text, this.#state);
+    this.#state = { pending, pasting };
+    for (const event of events) {
+      if (event.type === 'newline') {
+        this.#onNewline?.();
+      } else {
+        this.push(Buffer.from(event.text, 'utf8'));
+      }
+    }
+    this.#armFlush();
+  }
+
+  // A held partial sequence must never swallow input for good: if nothing
+  // completes it, release it as ordinary bytes.
+  #armFlush() {
+    if (this.#flushTimer) {
+      clearTimeout(this.#flushTimer);
+      this.#flushTimer = null;
+    }
+    if (!this.#state.pending) {
+      return;
+    }
+    this.#flushTimer = setTimeout(() => {
+      this.#flushTimer = null;
+      const held = this.#state.pending;
+      this.#state = { pending: '', pasting: this.#state.pasting };
+      if (held) {
+        this.push(Buffer.from(held, 'utf8'));
+      }
+    }, 50);
+    this.#flushTimer.unref?.();
+  }
+}

package/src/crypto/DeviceIdentity.js

@@ -0,0 +1,307 @@
+import sodium from 'sodium-native';
+
+// ── Device identity ─────────────────────────────────────────────
+//
+// Step 1 of multi-device (docs/design/multi-device.md, item 4 of #481). This
+// module has no callers on purpose. The sender-key rollout worked because the
+// asymmetric half landed before the wire that carries it existed — "it cost a
+// field on a wire nobody was using yet" — and the same trick applies here.
+//
+// The model, in one paragraph. Today the X25519 box key *is* the identity: it
+// is what a fingerprint is computed from, what a SAS compares, and what a ban
+// keys on. That works for one machine and breaks for two, because two machines
+// can only share it by sharing the secret — which is what `/backup` plus the
+// restore prompt actually does today, and it cannot be revoked. So identity
+// moves up a level: a long-term **Ed25519 key that only ever signs**, and one
+// **X25519 box key per device**, listed and signed by it. A device is added by
+// signing a longer list; revoked by signing a shorter one with a higher
+// counter.
+//
+// Nothing here encrypts. That separation is the point: a signing key that never
+// touches a message is a key that can be kept somewhere a message key cannot.
+
+const DEVICE_ID_SIZE = 16;
+const MAX_DEVICES = 8;
+const MAX_LABEL_LENGTH = 32;
+
+// Domain separation. Two different structures must never produce the same
+// bytes to sign, or a signature over one is a signature over the other.
+const LIST_DOMAIN = 'CipherMesh-DeviceList-v1';
+const FINGERPRINT_DOMAIN = 'CipherMesh-IdentityFingerprint-v1';
+
+// Release a key allocated with sodium_malloc.
+//
+// Same reasoning as SenderKey.js: sodium_malloc'd pages are mlock'd, the OS
+// caps how much a process may lock, and zeroing alone leaves them locked until
+// a finaliser happens to run. sodium_free zeroes before releasing.
+function freeKey(buf) {
+  if (buf) {
+    sodium.sodium_free(buf);
+  }
+}
+
+/**
+ * A stable name for one device, drawn once and kept.
+ *
+ * Deliberately *not* derived from the device's box key. A box key rotates
+ * (`KeyManager.rotate`) and the device is still the same device; an id derived
+ * from the key would rename it on every rotation, which is precisely when a
+ * peer most needs to recognise it. Forging an id buys nothing on its own —
+ * only a list signed by the identity key binds an id to a key.
+ */
+export function newDeviceId() {
+  const buf = Buffer.alloc(DEVICE_ID_SIZE);
+  sodium.randombytes_buf(buf);
+  return buf.toString('hex');
+}
+
+/**
+ * The long-term signing key. Signs device lists; never encrypts anything.
+ */
+export class DeviceIdentity {
+  #publicKey;
+  #secretKey;
+
+  constructor(secretKey = null) {
+    this.#publicKey = Buffer.alloc(sodium.crypto_sign_PUBLICKEYBYTES);
+    this.#secretKey = sodium.sodium_malloc(sodium.crypto_sign_SECRETKEYBYTES);
+
+    if (secretKey) {
+      // An Ed25519 secret key carries its public half in the last 32 bytes, so
+      // restoring one cannot disagree with the public key it is paired with.
+      secretKey.copy(this.#secretKey);
+      this.#secretKey
+        .subarray(sodium.crypto_sign_SECRETKEYBYTES - sodium.crypto_sign_PUBLICKEYBYTES)
+        .copy(this.#publicKey);
+    } else {
+      sodium.crypto_sign_keypair(this.#publicKey, this.#secretKey);
+    }
+  }
+
+  get publicKey() {
+    return this.#publicKey;
+  }
+
+  get publicKeyB64() {
+    return this.#publicKey.toString('base64');
+  }
+
+  get fingerprint() {
+    return identityFingerprint(this.#publicKey);
+  }
+
+  /** Detached signature over arbitrary bytes. */
+  sign(bytes) {
+    const signature = Buffer.alloc(sodium.crypto_sign_BYTES);
+    sodium.crypto_sign_detached(signature, bytes, this.#secretKey);
+    return signature;
+  }
+
+  serialize() {
+    return { secretKey: this.#secretKey.toString('base64') };
+  }
+
+  static deserialize(data) {
+    const secretKey = decodeKey(data?.secretKey, sodium.crypto_sign_SECRETKEYBYTES);
+    return secretKey ? new DeviceIdentity(secretKey) : null;
+  }
+
+  destroy() {
+    freeKey(this.#secretKey);
+    this.#secretKey = null;
+    this.#publicKey = null;
+  }
+}
+
+/**
+ * The identity fingerprint, as a human compares it.
+ *
+ * 128 bits, not the 32 the box-key fingerprint uses. That difference is
+ * deliberate: `KeyManager.computeFingerprint` is a display aid sitting next to
+ * a 40-bit SAS that does the real work, whereas the plan (step 4) is for *this*
+ * value to become what a person verifies. `computeSAS` already carries a note
+ * that 20 bits was grindable offline; 32 is not enough to inherit that job.
+ */
+export function identityFingerprint(publicKey) {
+  const key = Buffer.isBuffer(publicKey) ? publicKey : Buffer.from(publicKey, 'base64');
+  const hash = Buffer.alloc(32);
+  sodium.crypto_generichash(hash, Buffer.concat([Buffer.from(FINGERPRINT_DOMAIN), key]));
+
+  const parts = [];
+  for (let i = 0; i < 16; i += 2) {
+    parts.push(
+      hash
+        .subarray(i, i + 2)
+        .toString('hex')
+        .toUpperCase(),
+    );
+  }
+  return parts.join(':');
+}
+
+function decodeKey(b64, size) {
+  if (typeof b64 !== 'string') {
+    return null;
+  }
+  let buf;
+  try {
+    buf = Buffer.from(b64, 'base64');
+  } catch {
+    return null;
+  }
+  return buf.length === size ? buf : null;
+}
+
+// Length-prefixed on the *byte* count, so a label with a multi-byte character
+// cannot make two different lists serialise the same way. The separator is
+// cosmetic — the prefixes are what make the encoding injective.
+const lp = (value) => `${Buffer.byteLength(String(value), 'utf-8')}:${value}`;
+
+/**
+ * What the signature covers.
+ *
+ * Everything a relay or a peer could tamper with: which identity the list
+ * belongs to, its position in the sequence, how many devices it names, and
+ * every field of every device. The count is in there so devices cannot be
+ * dropped from the end without breaking the signature.
+ *
+ * The ML-KEM key is deliberately *not* in a descriptor. A list is a set of
+ * claims about identity, and a KEM key is not one — it is transport material,
+ * already advertised per session in JOIN, and a device could change it without
+ * changing who it is. Carrying it here also cost 1584 bytes of base64 per
+ * device, which is the difference between a provisioning grant that fits in a
+ * QR code and one that does not.
+ */
+export function deviceListBytes({ identityPk, counter, devices }) {
+  const parts = [LIST_DOMAIN, identityPk, String(counter), String(devices.length)];
+  for (const device of devices) {
+    parts.push(device.deviceId, device.boxPk, device.label, String(device.createdAt));
+  }
+  return Buffer.from(parts.map(lp).join('|'), 'utf-8');
+}
+
+/**
+ * Sign a set of devices as the current list for this identity.
+ *
+ * `counter` is the caller's responsibility and must only ever go up — see
+ * `isNewerList`. A list is a statement about *now*, so adding a device and
+ * revoking one are the same operation with a different array.
+ */
+export function signDeviceList(identity, counter, devices) {
+  const list = {
+    identityPk: identity.publicKeyB64,
+    counter,
+    devices: devices.map(normaliseDevice),
+  };
+  const signature = identity.sign(deviceListBytes(list));
+  return { ...list, signature: signature.toString('base64') };
+}
+
+function normaliseDevice(device) {
+  return {
+    deviceId: device.deviceId,
+    boxPk: device.boxPk,
+    label: device.label ?? '',
+    createdAt: device.createdAt,
+  };
+}
+
+/**
+ * Read a device list that arrived from somewhere else.
+ *
+ * Returns the normalised list, or `null`. Never throws and never partially
+ * accepts: a list is one signed statement, so half of it is not usable and
+ * "the good devices out of a bad list" is exactly the shape of bug the
+ * capability validator was written to avoid.
+ *
+ * The signature is checked *last*, after the structure, because verifying a
+ * signature over a shape we would reject anyway is work an unauthenticated
+ * peer gets to ask for.
+ */
+export function verifyDeviceList(envelope) {
+  if (!envelope || typeof envelope !== 'object') {
+    return null;
+  }
+
+  const identityKey = decodeKey(envelope.identityPk, sodium.crypto_sign_PUBLICKEYBYTES);
+  const signature = decodeKey(envelope.signature, sodium.crypto_sign_BYTES);
+  if (!identityKey || !signature) {
+    return null;
+  }
+
+  if (!Number.isSafeInteger(envelope.counter) || envelope.counter < 0) {
+    return null;
+  }
+
+  if (!Array.isArray(envelope.devices) || envelope.devices.length === 0) {
+    return null;
+  }
+  if (envelope.devices.length > MAX_DEVICES) {
+    return null;
+  }
+
+  const devices = [];
+  const ids = new Set();
+  const boxKeys = new Set();
+
+  for (const device of envelope.devices) {
+    if (!device || typeof device !== 'object') {
+      return null;
+    }
+    if (typeof device.deviceId !== 'string' || !/^[0-9a-f]{32}$/.test(device.deviceId)) {
+      return null;
+    }
+    if (!decodeKey(device.boxPk, sodium.crypto_box_PUBLICKEYBYTES)) {
+      return null;
+    }
+    if (typeof device.label !== 'string' || device.label.length > MAX_LABEL_LENGTH) {
+      return null;
+    }
+    if (!Number.isSafeInteger(device.createdAt) || device.createdAt < 0) {
+      return null;
+    }
+
+    // Two entries naming one device, or one key under two device ids, would
+    // make "which device is this" ambiguous for every reader.
+    if (ids.has(device.deviceId) || boxKeys.has(device.boxPk)) {
+      return null;
+    }
+    ids.add(device.deviceId);
+    boxKeys.add(device.boxPk);
+
+    devices.push(normaliseDevice(device));
+  }
+
+  const list = { identityPk: envelope.identityPk, counter: envelope.counter, devices };
+  if (!sodium.crypto_sign_verify_detached(signature, deviceListBytes(list), identityKey)) {
+    return null;
+  }
+
+  return { ...list, signature: envelope.signature };
+}
+
+/**
+ * Should `candidate` replace `held`?
+ *
+ * Highest counter wins, and it is enforced here — on receipt — rather than
+ * trusted from the sender. Without it, a relay that kept a copy of an older
+ * list could replay it to put a revoked device back.
+ *
+ * A candidate for a different identity is never newer; it is a different
+ * question, and answering it here would let one identity's list displace
+ * another's.
+ */
+export function isNewerList(candidate, held) {
+  if (!candidate) {
+    return false;
+  }
+  if (!held) {
+    return true;
+  }
+  if (candidate.identityPk !== held.identityPk) {
+    return false;
+  }
+  return candidate.counter > held.counter;
+}
+
+export const DEVICE_LIMITS = { MAX_DEVICES, MAX_LABEL_LENGTH, DEVICE_ID_SIZE };