whalibmob 5.30.0 → 5.32.0

package/lib/store/FileBackend.js

@@ -0,0 +1,178 @@
+'use strict';
+
+// The session on disk, as JSON files — what whalibmob has always done.
+//
+// This is the default and it writes exactly the files the library wrote
+// before there was a backend at all: same directory, same names, same
+// contents. A session saved by an older version opens here without being
+// touched, and one saved here opens in an older version. The file names are
+// the contract with everything already installed, so they are settled in the
+// table below and not derived anywhere else.
+//
+// A number has two halves that never share state — the one registered over
+// the Mobile API and the companion linked over the Web API — and a backend
+// covers one of them. Which one is decided by `web` at construction, and it
+// is the whole difference between the two: the companion's files carry .web
+// ahead of the suffix, so 919634847671.signal.json and
+// 919634847671.web.signal.json sit side by side in one directory without ever
+// being confused for each other.
+//
+// Writes go to a temporary file and are renamed into place. The old code
+// wrote some files straight and others through a rename; doing it one way
+// everywhere costs nothing and means a session cannot be left half written by
+// a process that died mid-write — which, for the file holding a number's
+// identity keys, is the difference between a session and a lost number.
+
+const fs   = require('fs');
+const path = require('path');
+
+const { preKeyId } = require('./Backend');
+
+// key → the part of the file name that follows the number (and the .web that
+// marks the companion half). These are the names in SessionPaths.SESSION_SUFFIXES;
+// the two lists describe the same files and have to stay in step.
+const KEY_SUFFIX = Object.freeze({
+  'auth':                '.json',
+  'signal':              '.signal.json',
+  'sender-key':          '.sk.json',
+  'tc-token':            '.tctoken.json',
+  'device-cache':        '.device-cache.json',
+  'lid-mapping':         '.lid-mapping.json',
+  'lid-reverse-mapping': '.lid-reverse-mapping.json',
+  'history':             '.history.json',
+  'messages':            '.messages.json',
+  'app-state':           '.appState.json',
+  'app-state-keys':      '.appStateKeys.json'
+});
+
+// The one-time pre-keys are a file each, named by id.
+const PRE_KEY_INFIX = '.pre-key-';
+
+function _escapeRe(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+class FileBackend {
+  /**
+   * @param {object} opts
+   * @param {string} opts.dir    the directory this session's files live in
+   * @param {string} opts.phone  the number, digits only
+   * @param {boolean} [opts.web] the companion half rather than the mobile one
+   */
+  constructor(opts) {
+    if (!opts || !opts.dir) throw new TypeError('FileBackend: dir is required');
+    if (!opts.phone)        throw new TypeError('FileBackend: phone is required');
+
+    this.dir   = String(opts.dir);
+    this.phone = String(opts.phone).replace(/\D/g, '');
+    this.web   = !!opts.web;
+
+    if (!this.phone) throw new TypeError('FileBackend: phone must contain digits');
+
+    // <phone> for the mobile half, <phone>.web for the companion.
+    this._stem = this.phone + (this.web ? '.web' : '');
+  }
+
+  /** The file a key is kept in. Absolute, whether or not it exists. */
+  fileFor(key) {
+    const id = preKeyId(key);
+    if (id !== null) {
+      return path.join(this.dir, this._stem + PRE_KEY_INFIX + id + '.json');
+    }
+    const suffix = KEY_SUFFIX[key];
+    if (!suffix) throw new Error('FileBackend: unknown key ' + JSON.stringify(key));
+    return path.join(this.dir, this._stem + suffix);
+  }
+
+  read(key) {
+    let raw;
+    try {
+      raw = fs.readFileSync(this.fileFor(key), 'utf8');
+    } catch (err) {
+      // A key that was never written reads as absent, the way a fresh session
+      // reads. Anything else — a permission problem, a directory where a file
+      // should be — is the caller's to know about, because silently treating
+      // it as absent starts a brand new session over the top of a real one.
+      if (err && (err.code === 'ENOENT' || err.code === 'ENOTDIR')) return null;
+      throw err;
+    }
+    return raw;
+  }
+
+  write(key, value) {
+    if (typeof value !== 'string') {
+      throw new TypeError('FileBackend: value must be a string, got ' + typeof value);
+    }
+    const file = this.fileFor(key);
+    const dir  = path.dirname(file);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+    // Rename is atomic within a filesystem, so a reader sees either the whole
+    // old file or the whole new one and never the half-written middle. The
+    // temporary name carries the pid so two processes writing one session do
+    // not land on each other's scratch file.
+    const tmp = file + '.tmp-' + process.pid + '-' + Date.now().toString(36);
+    try {
+      fs.writeFileSync(tmp, value, 'utf8');
+      fs.renameSync(tmp, file);
+    } catch (err) {
+      try { fs.unlinkSync(tmp); } catch (_) {}
+      throw err;
+    }
+  }
+
+  remove(key) {
+    try {
+      fs.unlinkSync(this.fileFor(key));
+    } catch (err) {
+      if (err && (err.code === 'ENOENT' || err.code === 'ENOTDIR')) return;
+      throw err;
+    }
+  }
+
+  list(prefix) {
+    const want = prefix == null ? '' : String(prefix);
+
+    let entries;
+    try {
+      entries = fs.readdirSync(this.dir);
+    } catch (_) {
+      return [];   // no directory yet is no keys, not an error
+    }
+
+    const found = [];
+
+    // The pre-keys, by name. The mobile half must not pick up the companion's:
+    // <phone>.pre-key-1.json and <phone>.web.pre-key-1.json both start with the
+    // number, so the stem — which carries the .web or does not — is what the
+    // pattern is anchored on.
+    const preKeyRe = new RegExp(
+      '^' + _escapeRe(this._stem + PRE_KEY_INFIX) + '(\\d+)\\.json$');
+
+    for (const name of entries) {
+      const m = preKeyRe.exec(name);
+      if (!m) continue;
+      const key = 'pre-key/' + Number(m[1]);
+      if (key.startsWith(want)) found.push(key);
+    }
+
+    // The named keys. Read off the file names rather than statted one by one,
+    // so a directory of 812 pre-keys is still one readdir.
+    const present = new Set(entries);
+    for (const key of Object.keys(KEY_SUFFIX)) {
+      if (!key.startsWith(want)) continue;
+      if (present.has(this._stem + KEY_SUFFIX[key])) found.push(key);
+    }
+
+    return found.sort();
+  }
+}
+
+// The name table hangs off the class rather than travelling as a second export:
+// anything that needs it — a tool migrating a session between backends, say —
+// has the class already, and a loose export of the same object would be one more
+// thing to keep reachable from the package for no gain.
+FileBackend.KEY_SUFFIX    = KEY_SUFFIX;
+FileBackend.PRE_KEY_INFIX = PRE_KEY_INFIX;
+
+module.exports = { FileBackend };

package/lib/store/MemoryBackend.js

@@ -0,0 +1,73 @@
+'use strict';
+
+// A session that is never written down.
+//
+// It exists for two reasons. The first is tests: a contract this small is only
+// worth having if every backend behaves the same way, and the way to know that
+// is to run one suite against all of them — which needs a second backend that
+// is obviously correct, so that a disagreement points at the one being judged
+// rather than at the referee.
+//
+// The second is throwaway sessions. A companion link opened to read one thing
+// and dropped, a number being tried out, a test against the live server — none
+// of them want 834 files left behind in ~/.waSession. Handed this, they leave
+// nothing at all; when the process ends the session is simply gone, and the
+// device is unlinked or has to re-pair the next time.
+//
+// Which is also the warning. Nothing here survives the process. A registered
+// number whose credentials only ever lived in memory is not recoverable — the
+// registration is spent, the number is taken, and the keys that proved it was
+// yours are gone. Use it for sessions that were never meant to outlive the run.
+
+const { isValidKey } = require('./Backend');
+
+class MemoryBackend {
+  constructor() {
+    this._data = new Map();
+  }
+
+  read(key) {
+    this._assertKey(key);
+    const v = this._data.get(key);
+    return v === undefined ? null : v;
+  }
+
+  write(key, value) {
+    this._assertKey(key);
+    if (typeof value !== 'string') {
+      throw new TypeError('MemoryBackend: value must be a string, got ' + typeof value);
+    }
+    this._data.set(key, value);
+  }
+
+  remove(key) {
+    this._assertKey(key);
+    this._data.delete(key);
+  }
+
+  list(prefix) {
+    const want = prefix == null ? '' : String(prefix);
+    return [...this._data.keys()].filter(k => k.startsWith(want)).sort();
+  }
+
+  /** How many keys are held. Not part of the contract — for tests. */
+  get size() {
+    return this._data.size;
+  }
+
+  /** Drop everything. Not part of the contract — for tests. */
+  clear() {
+    this._data.clear();
+  }
+
+  // The file backend rejects a key it has no file name for, so this one has to
+  // reject it too — otherwise a typo passes in tests and fails in production,
+  // which is the one failure a second implementation exists to catch.
+  _assertKey(key) {
+    if (!isValidKey(key)) {
+      throw new Error('MemoryBackend: unknown key ' + JSON.stringify(key));
+    }
+  }
+}
+
+module.exports = { MemoryBackend };

package/lib/store/SqliteBackend.js

@@ -0,0 +1,306 @@
+'use strict';
+
+// The session in one database instead of 834 files.
+//
+// A number's state is twenty-two named files plus a file for each of its 812
+// one-time pre-keys. That works, and on a laptop nobody notices. On a phone
+// under Termux, on a container with a small inode budget, or with fifty
+// numbers in one folder, it is 40 000 files whose directory has to be read
+// every time the pre-key pool is counted.
+//
+// The same state here is a handful of rows. A write is a transaction, so a
+// process that dies mid-write leaves the previous value intact rather than a
+// half-written file; and one database can hold every number and both of their
+// halves at once, while each backend still sees only its own slice of it.
+//
+// ─── The driver ─────────────────────────────────────────────────────────────
+//
+// Node ships SQLite of its own from 22.5 as node:sqlite, synchronous and with
+// nothing to install. That is what this uses when it is there, which keeps the
+// promise whalibmob makes everywhere else in the library: no native build step,
+// nothing for node-gyp to fail at, and Termux stays a place it runs.
+//
+// better-sqlite3 is accepted as well, for Node older than 22.5, and is used
+// when node:sqlite is missing. It is a native module and has to compile, which
+// is why it is not the one reached for first and why it is not a dependency of
+// this package.
+//
+// ─── Why the values are BLOBs ───────────────────────────────────────────────
+//
+// node:sqlite binds a JavaScript string to a TEXT column as a C string, and a
+// C string stops at the first NUL. A value carrying one is silently cut short
+// — the session still loads, the keys in it are simply wrong from that byte
+// on, which is the worst way for a bug like this to present. Bound as a BLOB
+// the bytes go in and come back exactly, whatever is in them, so that is what
+// the column is and the conversion happens here rather than in the caller.
+
+const path = require('path');
+const fs   = require('fs');
+
+const { preKeyId, isValidKey } = require('./Backend');
+
+// Bumped when the shape of the table changes; kept in the file's user_version.
+const SCHEMA_VERSION = 1;
+
+const TABLE = 'session_state';
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS ${TABLE} (
+  phone TEXT NOT NULL,
+  half  TEXT NOT NULL,
+  key   TEXT NOT NULL,
+  value BLOB NOT NULL,
+  PRIMARY KEY (phone, half, key)
+) WITHOUT ROWID;
+`;
+
+// ─── Driver detection ────────────────────────────────────────────────────────
+
+let _driverCache;
+
+/**
+ * Load node:sqlite without its ExperimentalWarning reaching the console.
+ *
+ * The warning is true and it is also not the user's business: they asked
+ * whalibmob for a session store, not for a lecture about a Node flag they did
+ * not set. Only that one warning is swallowed, and only around this require —
+ * anything else Node has to say still gets through.
+ */
+function _requireNodeSqlite() {
+  const original = process.emitWarning;
+  process.emitWarning = function (warning, ...rest) {
+    const name = (rest[0] && rest[0].type) || rest[0];
+    const text = typeof warning === 'string' ? warning : (warning && warning.message) || '';
+    if (name === 'ExperimentalWarning' && /SQLite/i.test(text)) return;
+    return original.call(process, warning, ...rest);
+  };
+  try {
+    return require('node:sqlite');
+  } finally {
+    process.emitWarning = original;
+  }
+}
+
+/**
+ * The SQLite driver available here, as a uniform shape.
+ *
+ * @param {string} [prefer] 'node' or 'better-sqlite3' to demand one
+ * @returns {{ name: string, open: (file: string) => object }}
+ */
+function resolveDriver(prefer) {
+  if (!prefer && _driverCache) return _driverCache;
+
+  const tryNode = () => {
+    let sqlite;
+    try { sqlite = _requireNodeSqlite(); } catch (_) { return null; }
+    if (!sqlite || typeof sqlite.DatabaseSync !== 'function') return null;
+    return {
+      name: 'node:sqlite',
+      open: (file) => new sqlite.DatabaseSync(file)
+    };
+  };
+
+  const tryBetter = () => {
+    let Database;
+    try { Database = require('better-sqlite3'); } catch (_) { return null; }
+    return {
+      name: 'better-sqlite3',
+      open: (file) => new Database(file)
+    };
+  };
+
+  let driver = null;
+  if (prefer === 'node')                 driver = tryNode();
+  else if (prefer === 'better-sqlite3')  driver = tryBetter();
+  else                                   driver = tryNode() || tryBetter();
+
+  if (!driver) {
+    const [major, minor] = process.versions.node.split('.').map(Number);
+    const tooOld = major < 22 || (major === 22 && minor < 5);
+    throw new Error(
+      'SqliteBackend: no SQLite driver available.\n' +
+      (tooOld
+        ? `  Node ${process.versions.node} has no built-in SQLite — it arrives in 22.5.0.\n` +
+          '  Either upgrade Node, or install the fallback driver:\n' +
+          '      npm install better-sqlite3\n'
+        : `  node:sqlite should be present on Node ${process.versions.node} but could not ` +
+          'be loaded.\n  Install the fallback driver instead:\n' +
+          '      npm install better-sqlite3\n') +
+      '  Or leave it out entirely: the default FileBackend needs nothing installed.'
+    );
+  }
+
+  if (!prefer) _driverCache = driver;
+  return driver;
+}
+
+// ─── Connections ─────────────────────────────────────────────────────────────
+//
+// A number's two halves are two backends over one file, and fifty numbers in
+// one database are a hundred. Each opening its own handle would be a hundred
+// handles onto the same file for no reason, so they are shared by resolved
+// path and counted, and the file is closed when the last backend using it
+// lets go.
+
+const _open = new Map();   // resolved path → { db, driver, refs }
+
+function _acquire(file, prefer) {
+  const key = path.resolve(file);
+  const existing = _open.get(key);
+  if (existing) { existing.refs++; return existing; }
+
+  const dir = path.dirname(key);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  const driver = resolveDriver(prefer);
+  const db = driver.open(key);
+
+  // WAL lets a reader and a writer work at once, which is what a client
+  // flushing its Signal store while another reads the pre-key pool is doing.
+  // NORMAL is the synchronous level WAL is designed around: a crash of the
+  // process cannot lose a committed transaction, only a crash of the machine
+  // can, and paying FULL for every pre-key write is not worth that.
+  db.exec('PRAGMA journal_mode = WAL');
+  db.exec('PRAGMA synchronous = NORMAL');
+  db.exec('PRAGMA busy_timeout = 5000');
+  db.exec(SCHEMA);
+
+  const found = db.prepare('PRAGMA user_version').get();
+  const version = found ? Number(found.user_version) : 0;
+  if (version > SCHEMA_VERSION) {
+    db.close();
+    throw new Error(
+      `SqliteBackend: ${key} was written by a newer whalibmob (schema ` +
+      `${version}, this one understands ${SCHEMA_VERSION}). Upgrade whalibmob ` +
+      'rather than letting an older release write to it.'
+    );
+  }
+  if (version < SCHEMA_VERSION) db.exec('PRAGMA user_version = ' + SCHEMA_VERSION);
+
+  const entry = { db, driver, refs: 1, key };
+  _open.set(key, entry);
+  return entry;
+}
+
+// The count belongs to the shared entry; remembering that you have already let
+// go belongs to whoever is letting go. Keeping that flag on the entry would
+// mean the first backend to close it stopped every other one from ever
+// decrementing, and the file would stay open for the life of the process.
+function _release(entry) {
+  if (!entry) return;
+  entry.refs--;
+  if (entry.refs > 0) return;
+  _open.delete(entry.key);
+  try { entry.db.close(); } catch (_) {}
+}
+
+// ─── The backend ─────────────────────────────────────────────────────────────
+
+class SqliteBackend {
+  /**
+   * @param {object} opts
+   * @param {string} opts.path     the database file; created if missing
+   * @param {string} opts.phone    the number, digits only
+   * @param {boolean} [opts.web]   the companion half rather than the mobile one
+   * @param {string} [opts.driver] 'node' or 'better-sqlite3' to demand one
+   */
+  constructor(opts) {
+    if (!opts || !opts.path) throw new TypeError('SqliteBackend: path is required');
+    if (!opts.phone)         throw new TypeError('SqliteBackend: phone is required');
+
+    this.path  = String(opts.path);
+    this.phone = String(opts.phone).replace(/\D/g, '');
+    this.web   = !!opts.web;
+
+    if (!this.phone) throw new TypeError('SqliteBackend: phone must contain digits');
+
+    this._half = this.web ? 'web' : 'mobile';
+    this._conn = _acquire(this.path, opts.driver);
+    this.driver = this._conn.driver.name;
+
+    const db = this._conn.db;
+    // Prepared once. A pre-key sweep runs these 812 times and re-preparing the
+    // statement each time is most of what it would cost.
+    this._get = db.prepare(
+      `SELECT value FROM ${TABLE} WHERE phone = ? AND half = ? AND key = ?`);
+    this._put = db.prepare(
+      `INSERT INTO ${TABLE} (phone, half, key, value) VALUES (?, ?, ?, ?) ` +
+      'ON CONFLICT(phone, half, key) DO UPDATE SET value = excluded.value');
+    this._del = db.prepare(
+      `DELETE FROM ${TABLE} WHERE phone = ? AND half = ? AND key = ?`);
+    this._keys = db.prepare(
+      `SELECT key FROM ${TABLE} WHERE phone = ? AND half = ?`);
+  }
+
+  _assertKey(key) {
+    if (!isValidKey(key)) {
+      throw new Error('SqliteBackend: unknown key ' + JSON.stringify(key));
+    }
+    return key;
+  }
+
+  read(key) {
+    this._assertKey(key);
+    const row = this._get.get(this.phone, this._half, key);
+    if (!row || row.value == null) return null;
+    // node:sqlite hands a BLOB back as a Uint8Array, better-sqlite3 as a
+    // Buffer. Buffer.from copes with either without copying twice.
+    return Buffer.from(row.value).toString('utf8');
+  }
+
+  write(key, value) {
+    this._assertKey(key);
+    if (typeof value !== 'string') {
+      throw new TypeError('SqliteBackend: value must be a string, got ' + typeof value);
+    }
+    this._put.run(this.phone, this._half, key, Buffer.from(value, 'utf8'));
+  }
+
+  remove(key) {
+    this._assertKey(key);
+    this._del.run(this.phone, this._half, key);
+  }
+
+  list(prefix) {
+    const want = prefix == null ? '' : String(prefix);
+    const out = [];
+    for (const row of this._keys.all(this.phone, this._half)) {
+      if (row.key.startsWith(want)) out.push(row.key);
+    }
+    return out.sort();
+  }
+
+  // ── beyond the contract ───────────────────────────────────────────────────
+
+  /**
+   * Let go of the database.
+   *
+   * The file is shared between every backend opened on it, so it is closed
+   * once the last of them has called this. Calling it twice is harmless; using
+   * the backend afterwards is not, and throws.
+   */
+  close() {
+    if (this._closed) return;
+    this._closed = true;
+    _release(this._conn);
+  }
+
+  /** Every number the database holds, as `{ phone, half }`. */
+  static sessionsIn(file, opts) {
+    const conn = _acquire(file, opts && opts.driver);
+    try {
+      return conn.db
+        .prepare(`SELECT DISTINCT phone, half FROM ${TABLE} ORDER BY phone, half`)
+        .all()
+        .map(r => ({ phone: r.phone, half: r.half, web: r.half === 'web' }));
+    } finally {
+      _release(conn);
+    }
+  }
+}
+
+SqliteBackend.SCHEMA_VERSION = SCHEMA_VERSION;
+SqliteBackend.TABLE = TABLE;
+SqliteBackend.resolveDriver = resolveDriver;
+
+module.exports = { SqliteBackend, resolveDriver, SCHEMA_VERSION };

package/lib/store/migrate.js

@@ -0,0 +1,82 @@
+'use strict';
+
+// Moving a session from one backend to another.
+//
+// Somebody with a working number and 834 files who now wants one database has
+// to get the first into the second, and the one thing that must not happen on
+// the way is losing the credentials in the middle. So nothing is removed: the
+// state is copied, the source is left exactly as it was, and if the result is
+// wrong the old files are still sitting there to go back to.
+//
+// A destination that already holds a key is left alone unless `overwrite` says
+// otherwise, which makes an interrupted copy safe to run again — it picks up
+// what did not make it the first time and does not undo what did.
+
+const { assertBackend } = require('./Backend');
+
+/**
+ * Copy every key from one backend to another.
+ *
+ * @param {object} from  the backend to read from
+ * @param {object} to    the backend to write to
+ * @param {object} [opts]
+ * @param {boolean} [opts.overwrite]  replace keys the destination already has
+ * @returns {{copied: string[], skipped: string[], bytes: number}}
+ */
+function copySession(from, to, opts) {
+  assertBackend(from, 'source backend');
+  assertBackend(to, 'destination backend');
+  if (from === to) throw new Error('copySession: source and destination are the same backend');
+
+  const overwrite = !!(opts && opts.overwrite);
+  const copied = [], skipped = [];
+  let bytes = 0;
+
+  for (const key of from.list()) {
+    if (!overwrite && to.read(key) !== null) { skipped.push(key); continue; }
+
+    const value = from.read(key);
+    // A key that list() named and read() will not return has gone since the
+    // listing — a pre-key consumed by a message arriving mid-copy. It is not
+    // an error and it is not ours to invent a value for.
+    if (value === null) { skipped.push(key); continue; }
+
+    to.write(key, value);
+    bytes += Buffer.byteLength(value, 'utf8');
+    copied.push(key);
+  }
+
+  return { copied: copied.sort(), skipped: skipped.sort(), bytes };
+}
+
+/**
+ * Check that two backends hold the same state, key for key.
+ *
+ * Worth running after a copy and before deleting anything: it reads both sides
+ * rather than trusting that the copy said so.
+ *
+ * @returns {{ok: boolean, missing: string[], differing: string[], extra: string[]}}
+ */
+function compareSessions(a, b) {
+  assertBackend(a, 'first backend');
+  assertBackend(b, 'second backend');
+
+  const aKeys = new Set(a.list());
+  const bKeys = new Set(b.list());
+  const missing = [], differing = [], extra = [];
+
+  for (const key of aKeys) {
+    if (!bKeys.has(key)) { missing.push(key); continue; }
+    if (a.read(key) !== b.read(key)) differing.push(key);
+  }
+  for (const key of bKeys) if (!aKeys.has(key)) extra.push(key);
+
+  return {
+    ok: missing.length === 0 && differing.length === 0 && extra.length === 0,
+    missing: missing.sort(),
+    differing: differing.sort(),
+    extra: extra.sort()
+  };
+}
+
+module.exports = { copySession, compareSessions };