whalibmob 5.7.2 → 5.9.0

package/lib/GroupParticipant.js

@@ -0,0 +1,141 @@
+'use strict';
+
+// Participant results for group operations.
+//
+// A group action is not all-or-nothing. When four people are added to a group,
+// the server answers with four <participant> nodes and decides each one on its
+// own merits: three go in, the fourth comes back carrying error="403" because
+// their privacy settings do not let strangers add them. Reporting only the JIDs
+// that worked throws that away — the caller sees three where it asked for four
+// and has no idea which one failed, let alone why.
+//
+// So every participant the server answered about is returned, with its status
+// attached. The objects stringify to the bare JID, so anything that used to
+// print or join the plain string list keeps working untouched.
+
+const OK_STATUS = '200';
+
+function _toInt(v) {
+  if (v == null) return null;
+  const n = parseInt(String(v), 10);
+  return Number.isFinite(n) ? n : null;
+}
+
+function _child(node, desc) {
+  if (!node || !Array.isArray(node.content)) return null;
+  return node.content.find(c => c && c.description === desc) || null;
+}
+
+class GroupParticipantResult {
+  constructor(fields) {
+    /** @type {string} bare JID the server answered about */
+    this.jid = fields.jid;
+    /** @type {string} '200' when the action went through, else the error code */
+    this.status = fields.status;
+    /** @type {number|null} the error code as a number, null on success */
+    this.error = fields.error;
+    /** @type {'admin'|'superadmin'|null} */
+    this.admin = fields.admin || null;
+    /** @type {string|null} phone JID — set for both address families */
+    this.phoneNumber = fields.phoneNumber || null;
+    /** @type {string|null} LID — set when the server told us one */
+    this.lid = fields.lid || null;
+    /** @type {string|null} */
+    this.displayName = fields.displayName || null;
+    // Present when an add was refused because the person cannot be put into a
+    // group directly. The code inside is what a group invite message is built
+    // from, and it stops working at `expiration`.
+    /** @type {{code: string, expiration: number}|null} */
+    this.addRequest = fields.addRequest || null;
+    // The raw node, for anything the server sends that is not modelled here.
+    Object.defineProperty(this, 'node', {
+      value: fields.node || null, enumerable: false, writable: false
+    });
+  }
+
+  /** Whether the server carried the action out for this participant. */
+  get ok() { return this.error == null; }
+
+  /** Whether the refusal is the kind an invite message can work around. */
+  get needsInvite() { return !!(this.addRequest && this.addRequest.code); }
+
+  toString() { return this.jid; }
+
+  toJSON() {
+    return {
+      jid: this.jid, status: this.status, error: this.error, admin: this.admin,
+      phoneNumber: this.phoneNumber, lid: this.lid,
+      displayName: this.displayName, addRequest: this.addRequest
+    };
+  }
+}
+
+// One <participant jid=… [error=…] [type=…] [phone_number=…] [lid=…]> node,
+// optionally wrapping an <add_request code=… expiration=…/>.
+function parseParticipantNode(node) {
+  const a = (node && node.attrs) || {};
+  const rawJid = a.jid != null ? a.jid : a.value;
+  if (rawJid == null) return null;
+  const jid = String(rawJid);
+
+  const error  = _toInt(a.error) || null;   // error="0" means the same as absent
+  const type   = a.type ? String(a.type) : null;
+  const isLid  = jid.endsWith('@lid');
+
+  let addRequest = null;
+  const reqNode = _child(node, 'add_request');
+  if (reqNode && reqNode.attrs && reqNode.attrs.code) {
+    addRequest = {
+      code:       String(reqNode.attrs.code),
+      expiration: _toInt(reqNode.attrs.expiration) || 0
+    };
+  }
+
+  return new GroupParticipantResult({
+    jid,
+    status:      error != null ? String(error) : OK_STATUS,
+    error,
+    admin:       (type === 'admin' || type === 'superadmin') ? type : null,
+    phoneNumber: isLid ? (a.phone_number ? String(a.phone_number) : null) : jid,
+    lid:         isLid ? jid : (a.lid ? String(a.lid) : null),
+    displayName: a.display_name ? String(a.display_name) : null,
+    addRequest,
+    node
+  });
+}
+
+// Every <participant> under the given node, parsed. Failures included — that is
+// the whole point.
+function parseParticipantNodes(parent) {
+  if (!parent || !Array.isArray(parent.content)) return [];
+  return parent.content
+    .filter(n => n && n.description === 'participant')
+    .map(parseParticipantNode)
+    .filter(Boolean);
+}
+
+// Somebody waiting for an admin to let them into a group.
+class GroupJoinRequest {
+  constructor(jid, requestedAt) {
+    this.jid = jid;
+    /** @type {number} unix seconds, 0 when the server did not say */
+    this.requestedAt = requestedAt || 0;
+  }
+  toString() { return this.jid; }
+  toJSON() { return { jid: this.jid, requestedAt: this.requestedAt }; }
+}
+
+function parseJoinRequestNode(node) {
+  const a = (node && node.attrs) || {};
+  const rawJid = a.jid != null ? a.jid : a.user;
+  if (rawJid == null) return null;
+  return new GroupJoinRequest(String(rawJid), _toInt(a.request_time) || 0);
+}
+
+module.exports = {
+  GroupParticipantResult,
+  GroupJoinRequest,
+  parseParticipantNode,
+  parseParticipantNodes,
+  parseJoinRequestNode
+};

package/lib/MediaService.js

@@ -223,8 +223,34 @@ function _tryUpload(host, mediaPath, token, auth, encrypted, web) {
   });
 }
 
+// opts.fileEncSha256, when given, is checked against the blob as it arrived.
+// The MAC inside decryptMedia already proves the plaintext was not tampered
+// with, but this catches a truncated or substituted download before spending
+// the work on it, and tells the two failures apart.
+// Where a message's media actually lives. Most carry an absolute `url`, but a
+// message that arrived through history sync often has only the `directPath`,
+// which is that URL with the CDN host taken off the front.
+const CDN_HOST = 'mmg.whatsapp.net';
+
+function resolveMediaUrl(url, directPath) {
+  if (url) return String(url);
+  if (!directPath) return null;
+  const p = String(directPath);
+  return 'https://' + CDN_HOST + (p.startsWith('/') ? '' : '/') + p;
+}
+
 async function downloadMedia(url, mediaKey, keyName, opts) {
   const encrypted = await _httpGet(url, opts);
+  const expected  = opts && opts.fileEncSha256;
+  if (expected && expected.length) {
+    const actual = crypto.createHash('sha256').update(encrypted).digest();
+    const want   = Buffer.from(expected);
+    // timingSafeEqual throws on a length mismatch rather than returning false.
+    if (want.length !== actual.length || !crypto.timingSafeEqual(actual, want)) {
+      throw new Error('downloadMedia: the downloaded file does not match the message ' +
+        '(fileEncSha256 mismatch)');
+    }
+  }
   return decryptMedia(encrypted, Buffer.from(mediaKey), keyName);
 }
 
@@ -261,5 +287,6 @@ module.exports = {
   // message media, so they need a fetch that does not try to decrypt anything.
   httpGetBuffer: _httpGet,
   deriveMediaKeyData,
-  getMediaKeyName
+  getMediaKeyName,
+  resolveMediaUrl
 };

package/lib/appstate/AppStateStore.js

@@ -0,0 +1,100 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const { newState, HASH_BYTES } = require('./LTHash');
+
+// The collections app state is divided into. Which one a change belongs to is
+// not ours to choose — the server sorts patches by collection and a mutation
+// filed under the wrong one is refused.
+const COLLECTIONS = [
+  'critical_block',
+  'critical_unblock_low',
+  'regular_high',
+  'regular_low',
+  'regular'
+];
+
+/**
+ * Where each collection has got to.
+ *
+ * This has to survive a restart or every reconnect asks for a full snapshot of
+ * everything — slow, and it throws away the record of which index carried which
+ * value, without which a later mutation cannot displace an earlier one.
+ */
+class AppStateStore {
+  constructor(filePath) {
+    this._path   = filePath;
+    this._states = new Map();   // collection → { version, hash, indexValueMap }
+    this._load();
+  }
+
+  _load() {
+    try {
+      if (!fs.existsSync(this._path)) return;
+      const raw = JSON.parse(fs.readFileSync(this._path, 'utf8'));
+      for (const [name, s] of Object.entries(raw)) {
+        const hash = s.hash ? Buffer.from(s.hash, 'base64') : Buffer.alloc(HASH_BYTES);
+        const map  = {};
+        for (const [k, v] of Object.entries(s.indexValueMap || {})) {
+          map[k] = { valueMac: Buffer.from(v, 'base64') };
+        }
+        this._states.set(name, {
+          // A hash of the wrong length is not something to carry forward; the
+          // arithmetic would be nonsense. Start that collection over instead.
+          version:       hash.length === HASH_BYTES ? (Number(s.version) || 0) : 0,
+          hash:          hash.length === HASH_BYTES ? hash : Buffer.alloc(HASH_BYTES),
+          indexValueMap: hash.length === HASH_BYTES ? map  : {}
+        });
+      }
+    } catch (_) {}
+  }
+
+  _save() {
+    try {
+      const dir = path.dirname(this._path);
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      const obj = {};
+      for (const [name, s] of this._states) {
+        const map = {};
+        for (const [k, v] of Object.entries(s.indexValueMap || {})) {
+          map[k] = Buffer.from(v.valueMac).toString('base64');
+        }
+        obj[name] = {
+          version:       s.version || 0,
+          hash:          Buffer.from(s.hash).toString('base64'),
+          indexValueMap: map
+        };
+      }
+      fs.writeFileSync(this._path, JSON.stringify(obj), 'utf8');
+    } catch (_) {}
+  }
+
+  get(name) {
+    if (!this._states.has(name)) this._states.set(name, newState());
+    return this._states.get(name);
+  }
+
+  set(name, state) {
+    this._states.set(name, {
+      version:       state.version || 0,
+      hash:          Buffer.from(state.hash),
+      indexValueMap: state.indexValueMap || {}
+    });
+    this._save();
+  }
+
+  /** Forget a collection so the next sync asks for a snapshot of it. */
+  reset(name) {
+    this._states.set(name, newState());
+    this._save();
+  }
+
+  versions() {
+    const out = {};
+    for (const name of COLLECTIONS) out[name] = this.get(name).version;
+    return out;
+  }
+}
+
+module.exports = { AppStateStore, COLLECTIONS };

package/lib/appstate/AppStateSync.js

@@ -0,0 +1,292 @@
+'use strict';
+
+const crypto     = require('crypto');
+const { hkdf }   = require('@noble/hashes/hkdf');
+const { sha256 } = require('@noble/hashes/sha256');
+const { makeGenerator, newState } = require('./LTHash');
+const S = require('./SyncdProto');
+
+// The five keys every app-state mutation is worked with, expanded from the one
+// key the primary device shares over an encrypted message.
+//
+//   indexKey            HMACs the index, so the same index always MACs the same
+//   valueEncryptionKey  AES-256-CBC over the mutation body
+//   valueMacKey         authenticates that body
+//   snapshotMacKey      authenticates the state as a whole at a version
+//   patchMacKey         authenticates one patch against that state
+const KEY_EXPANSION_INFO = 'WhatsApp Mutation Keys';
+const KEY_EXPANSION_LEN  = 160;
+
+function mutationKeys(keyData) {
+  const ikm = Buffer.isBuffer(keyData) ? keyData : Buffer.from(keyData);
+  const e   = Buffer.from(hkdf(sha256, ikm, Buffer.alloc(0),
+    Buffer.from(KEY_EXPANSION_INFO, 'utf8'), KEY_EXPANSION_LEN));
+  return {
+    indexKey:           e.subarray(0, 32),
+    valueEncryptionKey: e.subarray(32, 64),
+    valueMacKey:        e.subarray(64, 96),
+    snapshotMacKey:     e.subarray(96, 128),
+    patchMacKey:        e.subarray(128, 160)
+  };
+}
+
+function hmac(data, key, alg) {
+  return crypto.createHmac(alg || 'sha256', key).update(data).digest();
+}
+
+// The value MAC covers the operation, the key it was encrypted under, the
+// ciphertext, and the length of that prefix. Binding the operation in is what
+// stops a SET being replayed as a REMOVE.
+function valueMac(operation, encContent, keyId, key) {
+  const id     = Buffer.isBuffer(keyId) ? keyId : Buffer.from(keyId, 'base64');
+  const prefix = Buffer.concat([Buffer.from([operation === S.REMOVE ? 0x02 : 0x01]), id]);
+  const last   = Buffer.alloc(8);
+  last[7]      = prefix.length;
+  return hmac(Buffer.concat([prefix, encContent, last]), key, 'sha512').subarray(0, 32);
+}
+
+// Version numbers go into the MACs as 8 bytes, big-endian.
+function versionBytes(version) {
+  const b = Buffer.alloc(8);
+  b.writeUInt32BE(version >>> 0, 4);
+  return b;
+}
+
+function snapshotMac(hash, version, name, key) {
+  return hmac(Buffer.concat([hash, versionBytes(version), Buffer.from(name, 'utf8')]), key);
+}
+
+function patchMac(snapMac, valueMacs, version, name, key) {
+  return hmac(Buffer.concat([snapMac, ...valueMacs, versionBytes(version),
+    Buffer.from(name, 'utf8')]), key);
+}
+
+function aesDecrypt(buf, key) {
+  const iv = buf.subarray(0, 16);
+  const d  = crypto.createDecipheriv('aes-256-cbc', key, iv);
+  return Buffer.concat([d.update(buf.subarray(16)), d.final()]);
+}
+
+function aesEncrypt(buf, key) {
+  const iv = crypto.randomBytes(16);
+  const c  = crypto.createCipheriv('aes-256-cbc', key, iv);
+  return Buffer.concat([iv, c.update(buf), c.final()]);
+}
+
+class MissingAppStateKeyError extends Error {
+  constructor(keyId) {
+    super('app state key "' + keyId + '" has not been shared with this device yet');
+    this.name         = 'MissingAppStateKeyError';
+    this.isMissingKey = true;
+    this.keyId        = keyId;
+  }
+}
+
+// ─── decoding ────────────────────────────────────────────────────────────────
+
+/**
+ * Walk a run of mutations, decrypting each and folding it into the hash.
+ *
+ * getKey(base64KeyId) → { keyData } | null
+ * onMutation({ index, action, operation }) is called for every one that decodes.
+ *
+ * A record that fails its own MAC or its own decryption is skipped rather than
+ * abandoning the run: one corrupt row should not cost the whole collection. A
+ * missing key is different — nothing after it can be read either, and the fix
+ * is to wait for the key rather than to carry on — so that one is thrown.
+ */
+function decodeMutations(mutations, state, getKey, onMutation, validateMacs) {
+  const gen   = makeGenerator(state);
+  const cache = new Map();
+  let skipped = 0;
+
+  const keysFor = (keyId) => {
+    const b64 = Buffer.from(keyId).toString('base64');
+    if (cache.has(b64)) return cache.get(b64);
+    const rec = getKey(b64);
+    if (!rec || !rec.keyData) throw new MissingAppStateKeyError(b64);
+    const k = mutationKeys(rec.keyData);
+    cache.set(b64, k);
+    return k;
+  };
+
+  for (const m of mutations) {
+    if (!m || !m.valueBlob || !m.keyId) { skipped++; continue; }
+    const keys = keysFor(m.keyId);
+
+    const encContent = m.valueBlob.subarray(0, -32);
+    const theirMac   = m.valueBlob.subarray(-32);
+
+    if (validateMacs) {
+      const ours = valueMac(m.operation, encContent, m.keyId, keys.valueMacKey);
+      if (!ours.equals(theirMac)) { skipped++; continue; }
+    }
+
+    let plain;
+    try { plain = aesDecrypt(encContent, keys.valueEncryptionKey); }
+    catch (_) { skipped++; continue; }
+
+    let data;
+    try { data = S.decodeSyncActionData(plain); }
+    catch (_) { skipped++; continue; }
+
+    if (validateMacs && m.indexBlob) {
+      const ours = hmac(data.index, keys.indexKey);
+      if (!ours.equals(m.indexBlob)) { skipped++; continue; }
+    }
+
+    let index;
+    try { index = JSON.parse(data.index.toString('utf8')); }
+    catch (_) { skipped++; continue; }
+
+    onMutation({ index, action: data.value, operation: m.operation });
+    gen.mix({
+      indexMac: m.indexBlob,
+      valueMac: theirMac,
+      remove:   m.operation === S.REMOVE
+    });
+  }
+
+  return Object.assign(gen.finish(), { skipped });
+}
+
+/**
+ * Decode a snapshot — the whole collection, at one version, from nothing.
+ *
+ * A snapshot whose MAC does not check out is reported rather than thrown: the
+ * usual cause is a record we had to skip above, which leaves our hash short of
+ * the server's through no fault of the rest. The caller decides whether partial
+ * state is worth keeping.
+ */
+function decodeSnapshot(name, snapshot, getKey, getMutation, validateMacs) {
+  const state = newState();
+  state.version = snapshot.version;
+
+  const res = decodeMutations(snapshot.records, state, getKey, getMutation, validateMacs);
+  state.hash          = res.hash;
+  state.indexValueMap = res.indexValueMap;
+
+  let macOk = true;
+  if (validateMacs && snapshot.keyId) {
+    const b64 = Buffer.from(snapshot.keyId).toString('base64');
+    const rec = getKey(b64);
+    if (!rec || !rec.keyData) throw new MissingAppStateKeyError(b64);
+    const k = mutationKeys(rec.keyData);
+    macOk = snapshotMac(state.hash, state.version, name, k.snapshotMacKey)
+      .equals(snapshot.mac || Buffer.alloc(0));
+  }
+
+  return { state, macOk, skipped: res.skipped };
+}
+
+/**
+ * Apply a run of patches on top of a state we already hold.
+ *
+ * Stops at the first patch whose snapshot MAC does not match: from that point
+ * on our state and the server's have diverged, so everything after it would be
+ * applied to the wrong base. The caller's answer to that is to ask for a fresh
+ * snapshot.
+ */
+function decodePatches(name, patches, initial, getKey, getMutation, validateMacs) {
+  const state = {
+    version:       initial.version || 0,
+    hash:          Buffer.from(initial.hash),
+    indexValueMap: Object.assign({}, initial.indexValueMap || {})
+  };
+
+  let macFailed = false;
+  let skipped   = 0;
+
+  for (const p of patches) {
+    if (p.version != null) state.version = p.version;
+
+    if (validateMacs && p.keyId) {
+      const b64 = Buffer.from(p.keyId).toString('base64');
+      const rec = getKey(b64);
+      if (!rec || !rec.keyData) throw new MissingAppStateKeyError(b64);
+      const k    = mutationKeys(rec.keyData);
+      const macs = p.mutations.map(m => m.valueBlob.subarray(-32));
+      if (!patchMac(p.snapshotMac, macs, state.version, name, k.patchMacKey)
+            .equals(p.patchMac || Buffer.alloc(0))) {
+        macFailed = true;
+        break;
+      }
+    }
+
+    const res = decodeMutations(p.mutations, state, getKey, getMutation, validateMacs);
+    state.hash          = res.hash;
+    state.indexValueMap = res.indexValueMap;
+    skipped            += res.skipped;
+
+    if (validateMacs && p.keyId) {
+      const k = mutationKeys(getKey(Buffer.from(p.keyId).toString('base64')).keyData);
+      if (!snapshotMac(state.hash, state.version, name, k.snapshotMacKey)
+            .equals(p.snapshotMac || Buffer.alloc(0))) {
+        macFailed = true;
+        break;
+      }
+    }
+  }
+
+  return { state, macFailed, skipped };
+}
+
+// ─── encoding (the write path) ───────────────────────────────────────────────
+
+/**
+ * Turn one change into a patch, and advance the state it applies to.
+ *
+ * The state has to move forward here rather than when the server answers: the
+ * patch is signed against the version it produces, so a second change made
+ * before the first is acknowledged still has to build on it.
+ */
+function buildPatch({ name, index, action, apiVersion, operation }, keyId, keyData, state) {
+  const keys       = mutationKeys(keyData);
+  const encKeyId   = Buffer.isBuffer(keyId) ? keyId : Buffer.from(keyId, 'base64');
+  const indexBuf   = Buffer.from(JSON.stringify(index), 'utf8');
+  const op         = operation == null ? S.SET : operation;
+
+  const body     = S.encodeSyncActionData({
+    index: indexBuf, value: action, apiVersion, timestampMs: Date.now()
+  });
+  const encValue = aesEncrypt(body, keys.valueEncryptionKey);
+  const vMac     = valueMac(op, encValue, encKeyId, keys.valueMacKey);
+  const iMac     = hmac(indexBuf, keys.indexKey);
+
+  const next = {
+    version:       state.version || 0,
+    hash:          Buffer.from(state.hash),
+    indexValueMap: Object.assign({}, state.indexValueMap || {})
+  };
+  const gen = makeGenerator(next);
+  gen.mix({ indexMac: iMac, valueMac: vMac, remove: op === S.REMOVE });
+  const mixed = gen.finish();
+  next.hash          = mixed.hash;
+  next.indexValueMap = mixed.indexValueMap;
+  next.version      += 1;
+
+  const sMac = snapshotMac(next.hash, next.version, name, keys.snapshotMacKey);
+
+  const patch = S.encodePatch({
+    version:     next.version,
+    snapshotMac: sMac,
+    patchMac:    patchMac(sMac, [vMac], next.version, name, keys.patchMacKey),
+    keyId:       encKeyId,
+    mutations: [{
+      operation: op,
+      indexMac:  iMac,
+      valueBlob: Buffer.concat([encValue, vMac]),
+      keyId:     encKeyId
+    }]
+  });
+
+  return { patch, state: next };
+}
+
+module.exports = {
+  mutationKeys, valueMac, snapshotMac, patchMac, versionBytes,
+  aesEncrypt, aesDecrypt,
+  decodeMutations, decodeSnapshot, decodePatches, buildPatch,
+  MissingAppStateKeyError,
+  KEY_EXPANSION_INFO
+};

package/lib/appstate/LTHash.js

@@ -0,0 +1,119 @@
+'use strict';
+
+const { hkdf }   = require('@noble/hashes/hkdf');
+const { sha256 } = require('@noble/hashes/sha256');
+
+// A summation hash that survives being edited out of order.
+//
+// App state is a stream of mutations that the server hands out in pieces, and a
+// client has to be able to prove the state it ended up with is the state the
+// server meant it to have — without replaying every mutation ever made. An
+// ordinary hash cannot do that: it only tells you about a sequence you fed it
+// front to back.
+//
+// This one can, because it is addition. Every value is expanded into 128 bytes
+// and folded into the running hash as 64 little-endian 16-bit words, each added
+// with wraparound. Addition commutes, so the order the mutations arrive in does
+// not matter, and it inverts, so a mutation that is replaced can be subtracted
+// back out without touching the rest.
+//
+// The salt is the domain separator; it is what makes these hashes mean
+// "WhatsApp app state" and not something else expanded from the same bytes.
+const HASH_BYTES  = 128;
+const PATCH_SALT  = 'WhatsApp Patch Integrity';
+
+class LTHash {
+  constructor(salt) {
+    this.salt = salt;
+  }
+
+  // 128 bytes of key material for one value.
+  _expand(value) {
+    const ikm = Buffer.isBuffer(value) ? value : Buffer.from(value);
+    return Buffer.from(
+      hkdf(sha256, ikm, Buffer.alloc(0), Buffer.from(this.salt, 'utf8'), HASH_BYTES)
+    );
+  }
+
+  // Word-by-word, 16 bits at a time, little-endian, wrapping at 2^16.
+  //
+  // The wraparound is not a defect to guard against — it is what keeps the
+  // hash a fixed 128 bytes no matter how many mutations are folded in, and
+  // what makes subtraction the exact inverse of addition.
+  _pointwise(base, other, add) {
+    const a   = Buffer.isBuffer(base) ? base : Buffer.from(base);
+    const out = Buffer.alloc(HASH_BYTES);
+    for (let i = 0; i < HASH_BYTES; i += 2) {
+      const x = a.readUInt16LE(i);
+      const y = other.readUInt16LE(i);
+      out.writeUInt16LE((add ? (x + y) : (x - y)) & 0xffff, i);
+    }
+    return out;
+  }
+
+  add(hash, values) {
+    let out = hash;
+    for (const v of values) out = this._pointwise(out, this._expand(v), true);
+    return out;
+  }
+
+  subtract(hash, values) {
+    let out = hash;
+    for (const v of values) out = this._pointwise(out, this._expand(v), false);
+    return out;
+  }
+
+  // Retire the old values first, then fold the new ones in. Doing it the other
+  // way round is arithmetically the same, but this order matches how a patch
+  // reads: what it replaces, then what it puts there.
+  subtractThenAdd(hash, toAdd, toSubtract) {
+    return this.add(this.subtract(hash, toSubtract || []), toAdd || []);
+  }
+}
+
+const PATCH_INTEGRITY = new LTHash(PATCH_SALT);
+
+// Folds a run of mutations into a state, keeping track of which index each
+// value is filed under so a later mutation can displace it.
+//
+// indexValueMap is index MAC (base64) → { valueMac }. It is the reason a
+// mutation can be replaced at all: without knowing the value an index used to
+// carry, there is nothing to subtract back out.
+function makeGenerator(state) {
+  const indexValueMap = Object.assign({}, state.indexValueMap || {});
+  const hash    = Buffer.isBuffer(state.hash) ? state.hash : Buffer.alloc(HASH_BYTES);
+  const addBufs = [];
+  const subBufs = [];
+
+  return {
+    mix({ indexMac, valueMac, remove }) {
+      const key    = Buffer.from(indexMac).toString('base64');
+      const prev   = indexValueMap[key];
+      if (remove) {
+        // A remove for something we never had is the server telling us about a
+        // mutation we missed. There is nothing to subtract; the hash will not
+        // match at the end, and that mismatch is the signal to resync from a
+        // snapshot rather than something to paper over here.
+        if (!prev) return;
+        delete indexValueMap[key];
+      } else {
+        addBufs.push(Buffer.from(valueMac));
+        indexValueMap[key] = { valueMac: Buffer.from(valueMac) };
+      }
+      if (prev) subBufs.push(Buffer.from(prev.valueMac));
+    },
+
+    finish() {
+      return {
+        hash: PATCH_INTEGRITY.subtractThenAdd(hash, addBufs, subBufs),
+        indexValueMap
+      };
+    }
+  };
+}
+
+function newState() {
+  return { version: 0, hash: Buffer.alloc(HASH_BYTES), indexValueMap: {} };
+}
+
+module.exports = { LTHash, PATCH_INTEGRITY, makeGenerator, newState, HASH_BYTES };