whalibmob 5.30.0 → 5.32.1

package/README.md

@@ -27,6 +27,8 @@ code, and bring the account into being. Both transports, one API.
 [![Send messages](https://img.shields.io/badge/Send_messages-text_media_polls-34B7F1?style=for-the-badge)](#sending-messages)
 [![Handle events](https://img.shields.io/badge/Handle_events-incoming_%26_receipts-34B7F1?style=for-the-badge)](#handling-events)
 
+[![Device attestation](https://img.shields.io/badge/Device_attestation-Play_Integrity_%2B_App_Attest-8E44AD?style=for-the-badge)](#device-attestation--play-integrity-and-app-attest)
+
 </div>
 
 ##
@@ -61,6 +63,71 @@ If you want to talk with me contact me on Telegram my username îs @brtyu545
 - **The API is identical in both modes.** Everything below — sending, media, groups, events — reads the same whichever way the session was created.
 - No browser, no Selenium, no external runtime. It talks to WhatsApp directly over a **TCP socket** with the **Noise Protocol** handshake.
 - Signal Protocol encryption is **fully inlined** in pure JavaScript — no native binaries, no node-gyp, runs anywhere Node.js runs.
+- **It can prove it is a real handset.** The on-device Frida scripts in [`frida/`](https://github.com/Kunboruto20/whalibmob/tree/main/frida) mint the hardware attestation WhatsApp's registration server expects — Play Integrity and Keystore on Android, App Attest on iOS — and whalibmob folds the result into the registration requests. See [Device Attestation](#device-attestation--play-integrity-and-app-attest).
+
+## Device Attestation — Play Integrity and App Attest
+
+This is the part most projects stop at, so it is worth saying up front what is
+here and what it does.
+
+When the real WhatsApp app registers a number, it does not just send the number
+and the code. It also proves to the server that it is running on a genuine
+handset, by minting a hardware-backed attestation token — **Play Integrity plus
+a Keystore certificate chain** on Android, **DeviceCheck App Attest** on iOS.
+Those tokens cannot be forged off-device: they are signed by a key that lives in
+the phone's secure hardware.
+
+whalibmob ships the on-device scripts that obtain them. They run under
+[Frida](https://frida.re) on a **rooted Android phone** or a **jailbroken
+iPhone**, start a small HTTP server on the device, and whalibmob calls it while
+registering:
+
+| Platform | Endpoint | What it feeds into the registration request |
+|----------|-------------|----------------------------------------------|
+| Android | `/info` | APK hashes, signature and secret key — the device fingerprint |
+| Android | `/integrity` | `gpia` and its `_gg _gi _gp _ge _ga` companions — the Play Integrity verdict |
+| Android | `/cert` | the `&H=` body signature and the `Authorization` certificate chain |
+| iOS | `/integrity` | the App Attest assertion and its `Authorization` header |
+
+```sh
+# on your computer — build the bundle
+cd frida/android                                  # or: cd frida/ios
+npm install && npm run build                      # → server_with_dependencies.js
+
+# attach it to WhatsApp on the device, with the Frida server running there
+frida -U "WhatsApp" -l server_with_dependencies.js
+
+# on the machine running whalibmob — it listens on 1119 (WhatsApp) / 1120 (Business)
+export WA_FRIDA_HOST=192.168.1.50
+wa registration --request-code 919634847671
+```
+
+The code, and the per-platform setup:
+
+- **[`frida/android/server.js`](https://github.com/Kunboruto20/whalibmob/blob/main/frida/android/server.js)** — Play Integrity + Keystore attestation · [setup](https://github.com/Kunboruto20/whalibmob/blob/main/frida/android/README.md)
+- **[`frida/ios/server.js`](https://github.com/Kunboruto20/whalibmob/blob/main/frida/ios/server.js)** — DeviceCheck App Attest · [setup](https://github.com/Kunboruto20/whalibmob/blob/main/frida/ios/README.md)
+- **[`frida/ios/registration/registration.js`](https://github.com/Kunboruto20/whalibmob/blob/main/frida/ios/registration/registration.js)** — prints the registration public key
+- **[`frida/ios/exchange/index.js`](https://github.com/Kunboruto20/whalibmob/blob/main/frida/ios/exchange/index.js)** — hooks `mbedtls_gcm_update` to read the payload
+- **[`lib/Attestation.js`](https://github.com/Kunboruto20/whalibmob/blob/main/lib/Attestation.js)** — the client that talks to the device
+
+> [!NOTE]
+> **None of this is required.** Leave `WA_FRIDA_HOST` unset and whalibmob sends
+> the same empty low-trust attestation fields the native client sends when its
+> own integrity minting fails — which the server tolerates. Registration works
+> without a rooted phone anywhere in sight. Attaching a device raises the trust
+> score, which is what helps when a number keeps hitting `no_routes` or a block
+> screen.
+
+> [!IMPORTANT]
+> **The Frida scripts themselves are reference material, not a maintained
+> feature.** They are published so that anyone with a rooted or jailbroken
+> device can reproduce what the native app does, and so that the method is on
+> the record. They also need the official app installed **from the Play Store /
+> App Store** — a sideloaded APK will not attest, because the token is bound to
+> the store-signed build. `lib/Attestation.js`, the client side inside
+> whalibmob, is maintained as part of the library.
+
+Full walkthrough, with the device prerequisites: [Device Attestation with Frida](#device-attestation-with-frida-optional).
 
 ## Install
 
@@ -76,6 +143,7 @@ npm install -g whalibmob
 
 ## Index
 
+- [Device Attestation — Play Integrity and App Attest](#device-attestation--play-integrity-and-app-attest)
 - [CLI — Getting Started](#cli--getting-started)
   - [Install the CLI](#install-the-cli)
   - [First-Time Setup: Register a Number](#first-time-setup-register-a-number)
@@ -194,6 +262,9 @@ npm install -g whalibmob
     - [One-time Pre-keys](#one-time-pre-keys)
     - [Where the Folder Comes From](#where-the-folder-comes-from)
     - [Working Out the Paths Yourself](#working-out-the-paths-yourself)
+    - [Where a Session Is Kept](#where-a-session-is-kept)
+    - [One Database Instead of 834 Files](#one-database-instead-of-834-files)
+    - [Moving a Session Between Backends](#moving-a-session-between-backends)
   - [Signal Store Utilities](#signal-store-utilities)
     - [makeCacheableSignalKeyStore](#makecacheablesignalkeystore)
     - [addTransactionCapability](#addtransactioncapability)
@@ -3064,6 +3135,171 @@ migrateSession(base, '919634847671')
 `SESSION_SUFFIXES` is every per-number file the library writes — the list to
 copy or delete against if you are moving an account by hand.
 
+### Where a Session Is Kept
+
+Everything above describes files, because files are what whalibmob writes and
+what it will go on writing unless you say otherwise. **Nothing in this section
+is something you have to do.** Leave it alone and sessions stay exactly where
+they have always been, in the JSON files named above.
+
+What is new is that the place is now a choice. A **backend** is four
+synchronous operations over a flat key space:
+
+```js
+read(key)          // the stored text, or null when the key was never written
+write(key, value)  // put it there, replacing whatever was there before
+remove(key)        // take it away; a key that is not there is not an error
+list(prefix)       // every key present that starts with prefix
+```
+
+The keys are logical names rather than file names — `auth`, `signal`,
+`sender-key`, `tc-token`, `device-cache`, `lid-mapping`,
+`lid-reverse-mapping`, `history`, `messages`, `app-state`, `app-state-keys`,
+and `` `pre-key/${id}` `` for each of the 812 one-time pre-keys.
+
+Three implementations ship with the package:
+
+| Backend | Where the state goes | Needs |
+|---|---|---|
+| `FileBackend` | JSON files — what the library has always written | nothing; this is the default |
+| `SqliteBackend` | one database file | Node 22.5+, or `better-sqlite3` |
+| `MemoryBackend` | nowhere; gone when the process ends | nothing |
+
+```js
+const { FileBackend } = require('whalibmob')
+
+const backend = new FileBackend({
+  dir:   '/home/you/.waSession/919634847671',
+  phone: '919634847671'
+})
+
+backend.write('auth', JSON.stringify(creds))
+backend.read('auth')          // the text, or null
+backend.list()                // ['auth', 'pre-key/1', 'signal', …]
+backend.list('pre-key/')      // just the pre-keys
+backend.remove('pre-key/42')
+backend.fileFor('signal')     // …/919634847671.signal.json
+```
+
+`FileBackend` writes the same names in the same places as every release before
+it, so a session written by whalibmob 5.30 opens through it untouched and one
+written through it opens in 5.30. The only change is that writes now go to a
+temporary file and are renamed into place, so a process that dies mid-write
+leaves the previous state intact instead of half a file.
+
+> [!IMPORTANT]
+> **A number has two halves, and they are separate sessions.** The one
+> registered over the Mobile API and the companion linked over the Web API
+> never share state — in particular they have separate pre-key id spaces, and
+> mixing them hands out two different keys under one id and breaks decryption.
+> A backend covers **one** half, chosen by `web`:
+>
+> ```js
+> const mobile = new FileBackend({ dir, phone, web: false })  // default
+> const web    = new FileBackend({ dir, phone, web: true })
+> ```
+>
+> Both take the same keys and keep entirely separate values.
+
+> [!NOTE]
+> **The client does not accept a backend yet.** `new WhalibmobClient({ … })`
+> takes `sessionDir` and writes files, as it always has; the modules that hold
+> session state still do their own file I/O. The backends are usable on their
+> own — for reading, inspecting, copying or moving a session — and wiring them
+> through the client is the next step. Nothing here changes how a session is
+> created or connected today.
+
+### One Database Instead of 834 Files
+
+A number's state is 22 named files plus a file for each of its 812 one-time
+pre-keys. 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.
+
+`SqliteBackend` is the same state as a handful of rows:
+
+```js
+const { SqliteBackend } = require('whalibmob')
+
+const db = new SqliteBackend({
+  path:  '/home/you/.waSession/sessions.sqlite',
+  phone: '919634847671'
+})
+
+db.write('auth', JSON.stringify(creds))
+db.read('auth')
+db.list('pre-key/')
+db.driver          // 'node:sqlite' or 'better-sqlite3'
+db.close()         // let go of the file
+```
+
+**What it needs.** Node ships SQLite of its own from **22.5.0** as
+`node:sqlite`, and that is what this uses when it is there — nothing to
+install, nothing for node-gyp to fail at, and Termux stays a place whalibmob
+runs. On older Node it falls back to `better-sqlite3` if that is installed:
+
+```sh
+npm install better-sqlite3      # only on Node older than 22.5
+```
+
+Neither is a dependency of this package. On a runtime with neither, the
+constructor throws and says which of the two to reach for — and `FileBackend`
+goes on needing nothing at all.
+
+One file holds as many numbers and halves as you like, while each backend sees
+only its own slice:
+
+```js
+const mobile = new SqliteBackend({ path: file, phone: '919634847671' })
+const web    = new SqliteBackend({ path: file, phone: '919634847671', web: true })
+const other  = new SqliteBackend({ path: file, phone: '40712345678' })
+
+SqliteBackend.sessionsIn(file)
+// [ { phone: '40712345678',  half: 'mobile', web: false },
+//   { phone: '919634847671', half: 'mobile', web: false },
+//   { phone: '919634847671', half: 'web',    web: true  } ]
+```
+
+The file handle is shared between the backends opened on it and closed once
+the last of them calls `close()`, so closing one does not pull the file out
+from under the others. Calling `close()` twice is harmless.
+
+The database runs in WAL mode, so a client flushing its Signal store and
+another reading the pre-key pool do not block each other. Values are stored as
+blobs rather than text: a credential blob carrying a NUL byte is truncated by
+a text binding and the session then loads with keys that are wrong from that
+byte on, which is the worst way for a bug to present.
+
+### Moving a Session Between Backends
+
+Nothing is removed and the source is never modified, so if the result is not
+what you wanted the old files are still there to go back to:
+
+```js
+const { FileBackend, SqliteBackend, copySession, compareSessions } = require('whalibmob')
+
+const files = new FileBackend({ dir: '/home/you/.waSession/919634847671',
+                                phone: '919634847671' })
+const db    = new SqliteBackend({ path: '/home/you/.waSession/sessions.sqlite',
+                                  phone: '919634847671' })
+
+const moved = copySession(files, db)
+// { copied: ['auth', 'pre-key/1', …], skipped: [], bytes: 1284 }
+
+const check = compareSessions(files, db)
+// { ok: true, missing: [], differing: [], extra: [] }
+
+db.close()
+```
+
+`compareSessions` reads both sides back rather than trusting that the copy
+said so — run it before deleting anything. A key the destination already holds
+is left alone, so an interrupted copy is safe to run again; pass
+`{ overwrite: true }` when you do mean to replace what is there.
+
+Do both halves of a number separately — `web: false` and `web: true` are two
+sessions and a copy of one is not a copy of the other.
+
 ## Signal Store Utilities
 
 `auth-utils` is a collection of optional helpers for power users who manage their own `SignalStore` instances directly (e.g. custom storage backends, multi-account servers).

package/index.d.ts

@@ -1297,6 +1297,180 @@ export declare const SessionPaths: {
   SHARED_FILES: string[];
 };
 
+// ────────────────────────────────────────────────────────────────────────────
+// Session storage
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * A key under which a piece of session state is kept — one of the fixed names
+ * (`'auth'`, `'signal'`, …) or `` `pre-key/${id}` `` for one one-time pre-key.
+ */
+export type StorageKey = string;
+
+/**
+ * Where a session's state is kept.
+ *
+ * Four synchronous operations over a flat key space. `FileBackend` is the
+ * implementation the library has always used and remains the default; anything
+ * satisfying this interface can take its place.
+ *
+ * Synchronous on purpose: the Signal store flushes from `exit` and `SIGTERM`
+ * handlers, where an awaited write does not land.
+ */
+export interface StorageBackend {
+  /** The stored text, or `null` when the key has never been written. */
+  read(key: StorageKey): string | null;
+  /** Store `value` under `key`, replacing whatever was there. */
+  write(key: StorageKey, value: string): void;
+  /** Remove `key`. A key that is not there is not an error. */
+  remove(key: StorageKey): void;
+  /** Every key present that starts with `prefix` (all of them when omitted). */
+  list(prefix?: string): StorageKey[];
+}
+
+/** Options for {@link FileBackend}. */
+export interface FileBackendOptions {
+  /** The directory this session's files live in. */
+  dir: string;
+  /** The number. Non-digits are stripped. */
+  phone: string;
+  /** The companion (Web API) half rather than the mobile one. Default `false`. */
+  web?: boolean;
+}
+
+/**
+ * The session on disk as JSON files — what whalibmob has always written, under
+ * the same names, in the same place.
+ */
+export declare class FileBackend implements StorageBackend {
+  constructor(opts: FileBackendOptions);
+  readonly dir: string;
+  readonly phone: string;
+  readonly web: boolean;
+  /** The absolute path a key is kept at, whether or not it exists yet. */
+  fileFor(key: StorageKey): string;
+  read(key: StorageKey): string | null;
+  write(key: StorageKey, value: string): void;
+  remove(key: StorageKey): void;
+  list(prefix?: string): StorageKey[];
+  /** key → the part of the file name that follows the number. */
+  static KEY_SUFFIX: Record<string, string>;
+  /** What sits between the stem and a pre-key's id. */
+  static PRE_KEY_INFIX: string;
+}
+
+/** Options for {@link SqliteBackend}. */
+export interface SqliteBackendOptions {
+  /** The database file. Created, with its directory, if missing. */
+  path: string;
+  /** The number. Non-digits are stripped. */
+  phone: string;
+  /** The companion (Web API) half rather than the mobile one. Default `false`. */
+  web?: boolean;
+  /** Demand one driver rather than taking whichever is available. */
+  driver?: 'node' | 'better-sqlite3';
+}
+
+/** One number and half of it, as held in a database file. */
+export interface SqliteSessionRow {
+  phone: string;
+  half: 'mobile' | 'web';
+  web: boolean;
+}
+
+/**
+ * The session in one database instead of 834 files.
+ *
+ * Uses Node's built-in `node:sqlite` (22.5.0 and later) when it is there, and
+ * `better-sqlite3` when it is not. Neither is a dependency of this package —
+ * on a runtime with neither, the constructor throws saying what to install,
+ * and {@link FileBackend} goes on needing nothing.
+ *
+ * One file holds any number of sessions; a backend addresses one number's one
+ * half of it. The file handle is shared between the backends opened on it and
+ * released when the last of them calls `close()`.
+ */
+export declare class SqliteBackend implements StorageBackend {
+  constructor(opts: SqliteBackendOptions);
+  readonly path: string;
+  readonly phone: string;
+  readonly web: boolean;
+  /** Which driver this backend actually opened the file with. */
+  readonly driver: 'node:sqlite' | 'better-sqlite3';
+  read(key: StorageKey): string | null;
+  write(key: StorageKey, value: string): void;
+  remove(key: StorageKey): void;
+  list(prefix?: string): StorageKey[];
+  /** Let go of the database; the file closes once nobody else holds it. */
+  close(): void;
+  /** Every number and half the database file holds. */
+  static sessionsIn(file: string, opts?: { driver?: 'node' | 'better-sqlite3' }): SqliteSessionRow[];
+  /** The schema version this release writes and understands. */
+  static SCHEMA_VERSION: number;
+  /** The table the state lives in. */
+  static TABLE: string;
+}
+
+/** What {@link copySession} did. */
+export interface CopySessionResult {
+  /** Keys written to the destination. */
+  copied: StorageKey[];
+  /** Keys left alone — already present, or gone from the source mid-copy. */
+  skipped: StorageKey[];
+  /** How much was copied, in UTF-8 bytes. */
+  bytes: number;
+}
+
+/** What {@link compareSessions} found. */
+export interface CompareSessionsResult {
+  /** True when both hold the same keys with the same values. */
+  ok: boolean;
+  /** Keys the first has and the second does not. */
+  missing: StorageKey[];
+  /** Keys both have, holding different values. */
+  differing: StorageKey[];
+  /** Keys the second has and the first does not. */
+  extra: StorageKey[];
+}
+
+/**
+ * Copy every key from one backend to another. The source is not modified, and
+ * a key the destination already holds is left alone unless `overwrite` is set —
+ * so an interrupted copy is safe to run again.
+ */
+export declare function copySession(
+  from: StorageBackend,
+  to: StorageBackend,
+  opts?: { overwrite?: boolean }
+): CopySessionResult;
+
+/**
+ * Check that two backends hold the same state, reading both sides rather than
+ * trusting that a copy said so. Worth running before deleting the original.
+ */
+export declare function compareSessions(
+  a: StorageBackend,
+  b: StorageBackend
+): CompareSessionsResult;
+
+/**
+ * A session held only for the life of the process.
+ *
+ * Nothing survives the run: a number registered against this backend cannot be
+ * recovered, because the keys that proved the registration are gone with it.
+ */
+export declare class MemoryBackend implements StorageBackend {
+  constructor();
+  read(key: StorageKey): string | null;
+  write(key: StorageKey, value: string): void;
+  remove(key: StorageKey): void;
+  list(prefix?: string): StorageKey[];
+  /** How many keys are held. Not part of the contract. */
+  readonly size: number;
+  /** Drop everything. Not part of the contract. */
+  clear(): void;
+}
+
 // ────────────────────────────────────────────────────────────────────────────
 // Device
 // ────────────────────────────────────────────────────────────────────────────
@@ -1432,6 +1606,35 @@ export interface LibModule {
   [name: string]: any;
 }
 
+/**
+ * `whalibmob/lib/store/Backend` — the storage contract itself: the key names a
+ * backend has to honour, and the checks that go with them. The implementations
+ * are {@link FileBackend} and {@link MemoryBackend}, declared above.
+ */
+export declare const StoreBackend: {
+  /** Every key that is a fixed name rather than one generated per record. */
+  KEYS: readonly string[];
+  /** The prefix the per-record pre-key keys are built on: `'pre-key/'`. */
+  PRE_KEY_PREFIX: string;
+  /** The key one pre-key id is stored under. Throws on a non-integer id. */
+  preKeyKey(id: number): StorageKey;
+  /** The id back out of a pre-key key, or `null` when the key is not one. */
+  preKeyId(key: StorageKey): number | null;
+  /** Whether a string is a key every backend must accept. */
+  isValidKey(key: unknown): boolean;
+  /** Throw unless `backend` implements the contract. Returns it when it does. */
+  assertBackend<T>(backend: T, what?: string): T;
+};
+
+/**
+ * `whalibmob/lib/store/migrate` — moving a session from one backend to another
+ * and checking that it landed. Both members are also exported flat, above.
+ */
+export declare const StoreMigrate: {
+  copySession: typeof copySession;
+  compareSessions: typeof compareSessions;
+};
+
 /**
  * `whalibmob/lib/MediaService` — the encryption, upload and download beneath
  * `client.downloadMedia()`. Everything it exports is typed.

package/index.js

@@ -102,6 +102,16 @@ const {
 
 const { encodeWAM, BinaryInfo, WEB_EVENTS, WEB_GLOBALS } = WAM;
 
+// Where a session's state goes. FileBackend is what the library has always
+// done — JSON files, same names — and is the default; anything implementing
+// the same four methods can take its place. See lib/store/Backend.js.
+const StoreBackend    = require('./lib/store/Backend');
+const { FileBackend }   = require('./lib/store/FileBackend');
+const { MemoryBackend } = require('./lib/store/MemoryBackend');
+const { SqliteBackend } = require('./lib/store/SqliteBackend');
+const StoreMigrate      = require('./lib/store/migrate');
+const { copySession, compareSessions } = StoreMigrate;
+
 // ─── The namespaces ──────────────────────────────────────────────────────────
 //
 // Every module of lib/, whole, under a name of its own — see the note at the
@@ -229,6 +239,20 @@ module.exports = {
   webStoreFileFor,
   listSessions,
   migrateSession,
+  // Where a session's state is kept. FileBackend is the default and writes the
+  // JSON files whalibmob has always written; MemoryBackend keeps a session only
+  // for the life of the process. Both satisfy the contract in StoreBackend.
+  StoreBackend,
+  FileBackend,
+  MemoryBackend,
+  // One database instead of 834 files. Needs Node 22.5+ for its built-in
+  // node:sqlite, or better-sqlite3 installed; neither is a dependency, and
+  // FileBackend stays the default that needs nothing.
+  SqliteBackend,
+  // Moving a session from one backend to another, and checking that it landed.
+  StoreMigrate,
+  copySession,
+  compareSessions,
   // Device config — reads WA_OS / WA_DEVICE / WA_DEVICE_* from process.env
   getDeviceConfig,
   // Store helpers

package/lib/store/Backend.js

@@ -0,0 +1,143 @@
+'use strict';
+
+// Where a session's state is kept.
+//
+// Every piece of state a number owns — the credentials, the Signal sessions,
+// the sender keys, the app state, the pre-keys — is a named blob of text. Until
+// now each of them knew it was a file and wrote itself to disk with its own
+// fs.writeFileSync. That works, and it is what whalibmob still does; what it
+// cannot do is be anything other than a file. A session that would rather live
+// in one SQLite database than in 834 files has nowhere to say so.
+//
+// A backend is the one thing standing between the session and wherever its
+// state actually goes. It handles four operations on a flat key space:
+//
+//   read(key)        the blob, or null when there is none
+//   write(key, text) put it there, replacing whatever was there before
+//   remove(key)      take it away; a key that is not there is not an error
+//   list(prefix)     every key that starts with prefix
+//
+// That is the whole contract. Anything that can do those four can hold a
+// session, and the session never learns which one it got.
+//
+// ─── Keys ───────────────────────────────────────────────────────────────────
+//
+// Keys are logical names, not file names. `signal` is the Signal snapshot
+// whether it ends up as 919634847671.signal.json, a row in a table, or a value
+// under a Redis hash — the backend decides. A key naming a file would put the
+// file back into the contract and leave every other backend translating paths
+// it has no use for.
+//
+// The names are fixed, because a session written by one backend has to be
+// readable by the next:
+//
+//   auth                  the credentials, the store itself
+//   signal                Signal sessions, identities, signed pre-keys
+//   sender-key            group sender keys
+//   tc-token              trusted-contact tokens
+//   device-cache          the device list per contact
+//   lid-mapping           phone → LID
+//   lid-reverse-mapping   LID → phone
+//   history               the history-sync backlog
+//   messages              the message archive
+//   app-state             app-state collections
+//   app-state-keys        app-state sync keys
+//   pre-key/<id>          one one-time pre-key, by id
+//
+// pre-key/<id> is the only key that is generated rather than named, and the
+// only reason list() exists: there are 812 of them and they are asked for as a
+// group. Hence the slash — a backend that wants to put them somewhere of their
+// own has the prefix to key on, and `list('pre-key/')` is the way to find them
+// all again.
+//
+// ─── Sync, not async ────────────────────────────────────────────────────────
+//
+// read/write/remove/list return values, not promises. Everything that writes
+// session state in whalibmob writes it synchronously today, including the exit
+// and SIGTERM handlers that flush the Signal store on the way out of the
+// process — a handler that awaits is a handler whose write does not land. An
+// async contract would mean rewriting all of that, and for what SQLite offers
+// it buys nothing: better-sqlite3 is synchronous by design.
+//
+// It does rule out a backend that is a network round trip, Redis among them.
+// That is a real limit and it is the price of not touching the exit path. When
+// a network-backed store is worth having, it comes with an async contract
+// alongside this one and a major version to go with it.
+
+/**
+ * @typedef {object} StorageBackend
+ * @property {(key: string) => (string|null)} read
+ * @property {(key: string, value: string) => void} write
+ * @property {(key: string) => void} remove
+ * @property {(prefix?: string) => string[]} list
+ */
+
+/** Every key that is a fixed name rather than one generated per record. */
+const KEYS = Object.freeze([
+  'auth',
+  'signal',
+  'sender-key',
+  'tc-token',
+  'device-cache',
+  'lid-mapping',
+  'lid-reverse-mapping',
+  'history',
+  'messages',
+  'app-state',
+  'app-state-keys'
+]);
+
+/** The prefix the per-record pre-key keys are built on. */
+const PRE_KEY_PREFIX = 'pre-key/';
+
+/** The key one pre-key id is stored under. */
+function preKeyKey(id) {
+  const n = Number(id);
+  if (!Number.isInteger(n) || n < 0) {
+    throw new Error('preKeyKey: id must be a non-negative integer, got ' + id);
+  }
+  return PRE_KEY_PREFIX + n;
+}
+
+/** The id back out of a pre-key key, or null when the key is not one. */
+function preKeyId(key) {
+  if (typeof key !== 'string' || !key.startsWith(PRE_KEY_PREFIX)) return null;
+  const rest = key.slice(PRE_KEY_PREFIX.length);
+  if (!/^\d+$/.test(rest)) return null;
+  return Number(rest);
+}
+
+/** Whether a string is a key any backend is required to accept. */
+function isValidKey(key) {
+  if (typeof key !== 'string' || key.length === 0) return false;
+  return KEYS.includes(key) || preKeyId(key) !== null;
+}
+
+/**
+ * Throw unless `backend` implements the contract.
+ *
+ * Called where a backend is accepted from outside, so that a missing method is
+ * reported at the point it was handed over rather than hours later, from
+ * inside a write, with a session half saved.
+ */
+function assertBackend(backend, what) {
+  const label = what || 'backend';
+  if (!backend || typeof backend !== 'object') {
+    throw new TypeError(label + ' must be an object implementing the storage contract');
+  }
+  for (const method of ['read', 'write', 'remove', 'list']) {
+    if (typeof backend[method] !== 'function') {
+      throw new TypeError(label + ' is missing ' + method + '()');
+    }
+  }
+  return backend;
+}
+
+module.exports = {
+  KEYS,
+  PRE_KEY_PREFIX,
+  preKeyKey,
+  preKeyId,
+  isValidKey,
+  assertBackend
+};