whalibmob 5.10.8 → 5.10.12

package/README.md

@@ -928,55 +928,65 @@ const {
 
 ### `makeCacheableSignalKeyStore`
 
-Wraps a `SignalStore` with an in-memory NodeCache layer (5-minute TTL). All `get` calls for `sessions`, `preKeys`, `signedPreKeys`, and `identities` are served from cache on subsequent accesses. Writes invalidate the cache automatically.
+Wraps a `SignalStore` with an in-memory cache (5-minute TTL). Reads for sessions, pre-keys, signed pre-keys and identity keys are served from cache on subsequent accesses; `store*` calls write through to both, and `remove*` / `delete*` calls drop the entry.
+
+A lookup that finds nothing is **not** cached. Absence is the state most likely to change from underneath — a session about to be built, a pre-key about to be uploaded — so a remembered miss is the one that would hurt.
 
 `useClones` is set to `false` so that `SessionRecord` objects — which carry internal state and methods — are returned by reference and never deep-cloned.
 
-The wrapper also forwards `transaction()` and `isInTransaction()` calls to the underlying store when present, making it safe to stack with `addTransactionCapability`.
+Every method the underlying store has is forwarded, including `transaction()` and `isInTransaction()` when present, so the wrapper is a drop-in replacement and safe to stack with `addTransactionCapability`.
 
 ```js
-const { SignalStore } = require('whalibmob')
-const { makeCacheableSignalKeyStore } = require('whalibmob')
+const { SignalStore, makeCacheableSignalKeyStore } = require('whalibmob')
 
-const store  = new SignalStore(/* ... */)
+const store  = new SignalStore()
 const cached = makeCacheableSignalKeyStore(store)
 
 // reads hit cache after first access
-const session = await cached.getSession('919634847671@s.whatsapp.net:0')
+const session = await cached.loadSession('919634847671.0')
 ```
 
+Call `await cached.flushCache()` to drop everything — after a key rotation, or when another process may have written to the same session file.
+
 **When to use:** whenever your `SignalStore` is backed by a remote or disk-based store (database, Redis, file system) and you want to reduce repeated lookups for sessions that haven't changed between sends.
 
 ### `addTransactionCapability`
 
-Wraps a `SignalStore` with batched-write (transaction) semantics. During a transaction all writes are buffered in memory; they are flushed to the underlying store atomically when `commit()` is called at the end of the transaction.
+Wraps a `SignalStore` with batched-write (transaction) semantics. During a transaction all writes are buffered in memory and flushed to the underlying store in one shot when the callback returns — there is no `commit()` to call. Reads check the buffer first, so a transaction sees its own writes. If the callback throws, nothing is written at all and the error reaches the caller.
 
-Uses `AsyncLocalStorage` to propagate transaction context across async call chains, and a per-key-type `Mutex` with reference-counting to serialize concurrent writers safely.
+Uses `AsyncLocalStorage` to propagate transaction context across async call chains, and a `Mutex` with reference-counting per transaction key.
 
 ```js
-const { addTransactionCapability, makeCacheableSignalKeyStore } = require('whalibmob')
+const { SignalStore, addTransactionCapability, makeCacheableSignalKeyStore } = require('whalibmob')
 
 // recommended: cache first, then transactions on top
-const base        = new SignalStore(/* ... */)
-const cached      = makeCacheableSignalKeyStore(base)
-const txnStore    = addTransactionCapability(cached)
+const base     = new SignalStore()
+const cached   = makeCacheableSignalKeyStore(base)
+const txnStore = addTransactionCapability(cached)
 
 // inside a send flow
 await txnStore.transaction(async () => {
-  // all writes are buffered
-  await txnStore.setSession('919634847671@s.whatsapp.net:0', sessionRecord)
-  await txnStore.setPreKey(1, preKeyPair)
-  // commit is called automatically at the end of the transaction callback
-})
+  // all writes are buffered until this callback returns
+  await txnStore.storeSession('919634847671.0', sessionRecord)
+  await txnStore.storePreKey(1, preKeyPair)
+}, 'send')
 ```
 
-Stacking order matters: put `makeCacheableSignalKeyStore` below `addTransactionCapability` so that the cache always sees the committed state.
+The second argument is a scope: two transactions with different keys run concurrently, two with the same key run one after the other. It defaults to `'default'`. Any key is safe — the transaction locks are kept separate from the locks reads take, so no choice of key can make a transaction wait on itself.
+
+Nested `transaction()` calls reuse the enclosing context instead of opening a second one, so an inner transaction does not commit on its own.
+
+Stacking order matters: put `makeCacheableSignalKeyStore` below `addTransactionCapability`, so that a transaction which rolls back never reaches the cache. The other order works too — a failed transaction flushes the cache rather than leave it holding writes the store never took — but it throws away good entries to do it.
 
 **When to use:** for high-throughput servers that send to many recipients concurrently and need to batch Signal key writes into a single atomic flush per message.
 
 ### `assertMeId`
 
-Validates that a store object has a registered phone number and returns the canonical `@s.whatsapp.net` JID. Throws an `Error` if the store lacks a `phoneNumber` or has `registered !== true`.
+Returns the account's JID, or throws an `Error` describing what is missing.
+
+Works with both kinds of store — the SMS store from `initAuthCreds` / `createNewStore`, and the companion store from `createNewWebStore`. Only the wording of the error differs, since the way out of "not registered yet" is SMS verification in one case and pairing in the other.
+
+Once registered, the JID the server assigned is preferred (`store.me.id`) — on a companion it carries the device suffix, and rebuilding it from the phone number drops that silently. Before registration it throws, including during the pairing window: requesting a pairing code writes a placeholder `me` with no suffix, and that is not treated as being linked.
 
 ```js
 const { assertMeId } = require('whalibmob')
@@ -985,7 +995,8 @@ const store = loadStore(sessFile)
 
 try {
   const jid = assertMeId(store)
-  // jid === '919634847671@s.whatsapp.net'
+  // '919634847671:12@s.whatsapp.net' once connected,
+  // '919634847671@s.whatsapp.net' before that
   console.log('account JID:', jid)
 } catch (err) {
   console.error('store is not registered:', err.message)
@@ -996,7 +1007,9 @@ try {
 
 ### `initAuthCreds`
 
-Creates a fresh credential store for the given phone number. Functionally equivalent to `createNewStore` but also initialises the extra fields the library expects for account sync: `nextPreKeyId`, `firstUnuploadedPreKeyId`, `accountSyncCounter`, `accountSettings`, and `advSecretKey`.
+Creates a fresh credential store for the given phone number — the key pairs, registration ID and device identifiers a number needs before it can even ask for an SMS code. This is what `/reg code` calls.
+
+It returns everything `createNewStore` does, plus a few fields kept for application code that expects them: `nextPreKeyId`, `firstUnuploadedPreKeyId`, `accountSyncCounter`, `accountSettings`, `processedHistoryMessages` and `advSecretKey`. Those extras live on the object only — `saveStore` does not write them, so they are not there again after a reload. Nothing in the library reads them; treat them as a convenience, not as state.
 
 ```js
 const { initAuthCreds, saveStore } = require('whalibmob')
@@ -1013,10 +1026,35 @@ const store = initAuthCreds(phone)
 saveStore(store, sessFile)
 ```
 
-This is the function used internally by the CLI for all new session creation. Prefer it over `createNewStore` for forward compatibility.
+This is the function the CLI uses for every new SMS session. Prefer it over `createNewStore` for forward compatibility.
 
 > [!NOTE]
-> `initAuthCreds` and `createNewStore` produce equivalent stores for all current library operations. The additional fields from `initAuthCreds` are there for future-proofing and interoperability.
+> `initAuthCreds` and `createNewStore` produce equivalent stores for every current library operation, and identical files on disk. Use `createNewWebStore` instead when the device will be linked as a companion rather than registered by SMS — that one adds the pairing fields, and its own serialiser persists them.
+
+The file it writes has exactly these 16 keys:
+
+```json
+{
+  "phoneNumber": "40712345678",
+  "noiseKeyPair":    { "private": "…", "public": "…" },
+  "identityKeyPair": { "private": "…", "public": "…" },
+  "signedPreKey":    { "id": 3649616, "private": "…", "public": "…", "signature": "…" },
+  "registrationId": 2183,
+  "fdid": "2f701f8b-d693-4728-…",
+  "deviceId": "CBIyyJRAokOdYoTYEjTbng==",
+  "identityId": "SE8Q785oful7dGdBgNpwjg==",
+  "advertisingId": "5c97eea9-783f-4fcc-…",
+  "backupToken": "…",
+  "registered": true,
+  "codePending": false,
+  "name": "Boss",
+  "version": "2.26.9.75",
+  "device": { "os": "ios", "platform": 1, "model": "iPhone 15 Pro", "…": "…" },
+  "advIdentity": "…"
+}
+```
+
+`registered` and `codePending` are the two that move: both `false` when the store is created, `codePending` flips to `true` once a code has been requested, and `verifyCode` sets `registered` to `true` and `codePending` back to `false`. `advIdentity` stays `null` until the server sends the signed device identity in `<success>`.
 
 ### Recommended Stacking Pattern
 
@@ -1036,7 +1074,8 @@ const {
 let store = loadStore(sessFile) || initAuthCreds(phone)
 
 // 2. build the layered Signal key store
-const signalStore = new SignalStore(store)
+const signalStore = new SignalStore()
+signalStore.attachFile(sessFile)
 const cachedStore = makeCacheableSignalKeyStore(signalStore)
 const txnStore    = addTransactionCapability(cachedStore)
 
@@ -1791,9 +1830,11 @@ Photos and videos are sent with an inline preview so they show up in the chat
 directly, rather than as a placeholder the recipient has to tap. The dimensions
 are read out of the file header with no dependency at all. The preview itself
 uses `jimp` (installed automatically as an optional dependency) or `sharp` if
-you have it; failing both, a photo that carries an EXIF thumbnail still gets
-one. Video previews need `ffmpeg` on PATH — on Termux, `pkg install ffmpeg`.
-Without any of these the media still sends, just without the preview.
+you have it; failing both, a photo that carries an EXIF thumbnail gets one for
+free, and anything else is scaled in process — JPEG, PNG, GIF and BMP all work
+with nothing installed. Video previews need `ffmpeg` on PATH — on Termux,
+`pkg install ffmpeg`. Without any of these the media still sends, just without
+the preview.
 
 ### Image Message
 
@@ -2180,8 +2221,25 @@ rather than refused — so an unprepared file fails as a timeout that looks like
 network fault. The image is cropped square, scaled and written out as a fresh
 JPEG, which also strips EXIF and any progressive encoding the file was carrying.
 
-This needs `jimp` (an optional dependency) or `sharp`. Without either, the file
-is sent as it is and an already-correct picture still works.
+**No image library is required.** JPEG, PNG, GIF and BMP are decoded, cropped
+and re-encoded in process, so a bare `npm install` on a phone or a container
+built without a compiler converts a picture just as well as a full desktop.
+Whatever is installed is preferred, and the fallbacks run in this order:
+
+| | Handles | Needs |
+|---|---|---|
+| `sharp` or `jimp` | everything, best quality | either installed |
+| built in | JPEG, PNG, GIF, BMP | nothing |
+| `ffmpeg` | WebP, HEIC, progressive JPEG | `ffmpeg` on PATH |
+| metadata strip | an already-square JPEG | nothing |
+
+The built-in converter also reads the EXIF orientation tag, so a photo taken in
+portrait is turned upright instead of arriving on its side, and flattens
+transparency onto white, since a JPEG has no alpha channel.
+
+Only an exotic format with nothing installed — a WebP or a HEIC on a machine
+with no `ffmpeg` — still fails, and the error says so rather than reporting a
+bare `406`.
 
 ```js
 // skip the re-encode if you have prepared the image yourself
@@ -3133,11 +3191,16 @@ about updated
 
 #### CLI Change Profile Picture
 
-Reads the image from disk and uploads it as your profile picture. Supported formats: JPEG, PNG.
+Reads the image from disk, crops it square, scales it to 640×640 and uploads it
+as your profile picture. JPEG, PNG, GIF and BMP need nothing installed; WebP and
+HEIC need `ffmpeg` or `jimp`.
 
 ```sh
 wa> /photo ./avatar.jpg
-profile picture updated
+profile picture updated  id=1753912045
+
+wa> /photo remove
+profile picture removed
 ```
 
 #### CLI Change Privacy Settings

package/cli.js

@@ -447,7 +447,7 @@ const HELP = `
   Profile
     /name    <text>                          change display name
     /about   <text>                          change own bio / about text
-    /photo   <file>|remove                   change or remove own profile picture (JPEG)
+    /photo   <file>|remove                   change or remove own profile picture (any image)
     /privacy [<type> <value>]                show or change privacy settings
                                                types:  last_seen profile_picture status
                                                        online read_receipts groups_add

package/lib/Client.js

@@ -10,7 +10,7 @@ const { NoiseSocket }     = require('./noise');
 const { MessageSender, generateMessageId, makeJid, buildOrGetAdvIdentity } = require('./messages/MessageSender');
 const { checkIfRegistered, checkNumberStatus, requestSmsCode, verifyCode, assertRegistrationKeys, fetchIosVersion, fetchWaVersion } = require('./Registration');
 const { getDeviceConfig } = require('./DeviceConfig');
-const { prepareProfilePicture } = require('./MediaThumbnail');
+const { prepareProfilePicture, probeImageSize, canDecodeImage } = require('./MediaThumbnail');
 const { createNewStore, saveStore, loadStore, toSixParts, fromSixParts } = require('./Store');
 const { BinaryNode }      = require('./BinaryNode');
 const { AppStateStore, COLLECTIONS } = require('./appstate/AppStateStore');
@@ -252,6 +252,38 @@ function describeNodeBriefly(node, depth) {
   return out + '/>';
 }
 
+// Say why a picture was turned down, from what can be read off the file.
+//
+// "not acceptable" is all the server offers, so the useful part is what we can
+// work out ourselves: what the image is, whether it is square, and whether
+// anything was available to fix it before it went out.
+function _pictureRejected(what, picture, original, opts) {
+  const size = picture ? probeImageSize(picture) : null;
+  const bits = ['the server would not take this image (406 not-acceptable)'];
+
+  if (size && size.width && size.height) {
+    bits.push('it went out as ' + size.width + 'x' + size.height +
+      (size.width === size.height ? '' : ', which is not square'));
+  }
+  const isJpeg = picture && picture[0] === 0xff && picture[1] === 0xd8;
+  if (picture && !isJpeg) bits.push('and it is not a JPEG');
+
+  if (opts && opts.raw) {
+    bits.push('this call passed { raw: true }, so the file was sent exactly as given');
+  } else if (!isJpeg && original && !canDecodeImage(original)) {
+    // WebP, HEIC and the like need an outside converter; everything ordinary
+    // is handled without one.
+    bits.push('this format could not be converted here — install ffmpeg, or ' +
+      'save the picture as a JPEG or PNG first');
+  } else {
+    bits.push('the picture was cropped square and re-encoded before sending, ' +
+      'so the file itself is unlikely to be the problem — the account may not ' +
+      'be allowed to set one');
+  }
+
+  return what + ': ' + bits.join('. ') + '.';
+}
+
 function getNodeContent(node) {
   if (!node) return null;
   if (Buffer.isBuffer(node.content)) return node.content;
@@ -4365,15 +4397,16 @@ class WhalibmobClient extends EventEmitter {
         'The server drops a picture it will not take rather than refusing it, so ' +
         'this usually means the image was not in the form it wants' +
         (opts.raw ? ' — this call passed { raw: true }, so nothing was re-encoded'
-                  : '. Install jimp if it is not present, so the image can be ' +
-                    're-encoded before sending') + '.');
+                  : '') + '.');
     }
     if (resp.attrs && resp.attrs.type === 'error') {
       const errNode = findChild(resp, 'error');
       const code    = errNode && errNode.attrs && errNode.attrs.code;
+      if (String(code) === '406') {
+        throw new Error(_pictureRejected('changeProfilePicture', picture, buf, opts));
+      }
       throw new Error('changeProfilePicture: ' +
-        (String(code) === '406' ? 'the image was rejected (must be a JPEG)'
-       : String(code) === '401' ? 'not authorised to change this picture'
+        (String(code) === '401' ? 'not authorised to change this picture'
        : 'server rejected the request' + (code ? ' (' + code + ')' : '')));
     }
 
@@ -5960,9 +5993,11 @@ class WhalibmobClient extends EventEmitter {
     if (resp.attrs && resp.attrs.type === 'error') {
       const errNode = findChild(resp, 'error');
       const code    = errNode && errNode.attrs && errNode.attrs.code;
+      if (String(code) === '406') {
+        throw new Error(_pictureRejected('changeGroupPicture', picture, buf, opts));
+      }
       throw new Error('changeGroupPicture: ' +
-        (String(code) === '406' ? 'the image was rejected (must be a JPEG)'
-       : String(code) === '403' ? 'you are not allowed to change this group picture'
+        (String(code) === '403' ? 'you are not allowed to change this group picture'
        : 'server rejected the request' + (code ? ' (' + code + ')' : '')));
     }
     if (!buf) return 'remove';

package/lib/MediaThumbnail.js

@@ -15,7 +15,8 @@
 //     GIF and BMP — with no library at all.
 //   • The thumbnail is made with sharp or jimp when either is installed. When
 //     neither is, a JPEG that carries an EXIF thumbnail (which is to say, most
-//     photos taken on a phone) still yields one, again with no library.
+//     photos taken on a phone) yields one for free, and anything else goes
+//     through the decoder in lib/image — still with nothing installed.
 //   • Video frames need ffmpeg. Without it the video still sends, just without
 //     an inline preview.
 //
@@ -30,6 +31,8 @@ const path = require('path');
 const crypto = require('crypto');
 const { execFile } = require('child_process');
 
+const { toSquareJpeg, toScaledJpeg, canDecode: canDecodeImage } = require('./image');
+
 // The preview is deliberately tiny; it is only ever shown blurred behind the
 // real image while that downloads.
 const THUMB_WIDTH   = 32;
@@ -220,8 +223,8 @@ async function loadImageLib() {
     }
   } catch (_) {}
 
-  _whaDbg('[DBG] THUMB no image library — install jimp for inline previews ' +
-    'on images an EXIF thumbnail cannot cover');
+  _whaDbg('[DBG] THUMB no image library — falling back to the built-in ' +
+    'decoder, which reads JPEG, PNG, GIF and BMP');
   return _imageLib;
 }
 
@@ -277,16 +280,32 @@ async function imageThumbnail(buf, opts) {
     _whaDbg('[DBG] THUMB image library failed: ' + (err && err.message));
   }
 
-  // No library, or it could not read this file — fall back to whatever the
-  // camera already embedded.
+  // No library, or it could not read this file. The camera's own embedded
+  // preview is the cheapest thing left, and on a phone photo it is usually
+  // there — a few kilobytes already sized about right.
   const exif = extractExifThumbnail(buf);
   if (exif) {
     out.thumbnail = exif;
     _whaDbg('[DBG] THUMB using embedded EXIF thumbnail (' + exif.length + ' bytes)');
-  } else {
-    _whaDbg('[DBG] THUMB none available — the image will show as a download ' +
-      'placeholder; install jimp to fix');
+    return out;
+  }
+
+  // Otherwise scale it here. Slower than a library, but a preview is 32 pixels
+  // wide and this is the difference between the picture showing in the chat and
+  // a grey download placeholder.
+  try {
+    const built = toScaledJpeg(buf, width, quality);
+    if (built && built.length) {
+      out.thumbnail = built;
+      _whaDbg('[DBG] THUMB made in-process (' + built.length + ' bytes)');
+      return out;
+    }
+  } catch (err) {
+    _whaDbg('[DBG] THUMB built-in scaler failed: ' + (err && err.message));
   }
+
+  _whaDbg('[DBG] THUMB none available — the image will show as a download ' +
+    'placeholder; install jimp to fix');
   return out;
 }
 
@@ -301,13 +320,22 @@ const AVATAR_QUALITY = 50;
 /**
  * Re-encode an image into the form a profile picture has to be in.
  *
- * Cropped square from the top-left of the shorter side, scaled to 640x640, and
- * written out as a fresh JPEG. Re-encoding is the point rather than a side
- * effect: it strips EXIF, progressive scans and unusual chroma subsampling —
- * anything the file happened to carry — and produces a plain baseline JPEG.
+ * Cropped square, scaled to 640x640, and written out as a fresh JPEG.
+ * Re-encoding is the point rather than a side effect: it strips EXIF,
+ * progressive scans and unusual chroma subsampling — anything the file happened
+ * to carry — and produces a plain baseline JPEG.
  *
- * Returns the original buffer untouched when no image library is installed,
- * which at least gives an already-correct picture a chance to go through.
+ * Four converters are tried in turn, so a picture goes through whatever the
+ * machine happens to have:
+ *
+ *   1. sharp or jimp, when one is installed — the best quality and the widest
+ *      range of formats.
+ *   2. the built-in converter, which reads JPEG, PNG, GIF and BMP with no
+ *      dependency at all. This is the one that runs on a bare install.
+ *   3. ffmpeg, which covers what the built-in one does not: WebP, HEIC,
+ *      progressive JPEG.
+ *   4. failing all of that, the file with its metadata segments stripped, which
+ *      at least gives an already-square JPEG a chance.
  */
 async function prepareProfilePicture(buf, opts) {
   opts = opts || {};
@@ -345,15 +373,130 @@ async function prepareProfilePicture(buf, opts) {
       return await img.getBufferAsync(Jimp.MIME_JPEG);
     }
   } catch (err) {
-    _whaDbg('[DBG] AVATAR could not re-encode: ' + (err && err.message));
-    return buf;
+    _whaDbg('[DBG] AVATAR image library failed: ' + (err && err.message));
+  }
+
+  // No image library, or it could not read this file. The built-in converter
+  // needs nothing installed and handles the formats a picture is usually in.
+  try {
+    const built = toSquareJpeg(buf, size, quality);
+    if (built && built.length) {
+      _whaDbg('[DBG] AVATAR converted in-process to ' + size + 'x' + size +
+        ' (' + buf.length + ' → ' + built.length + ' bytes)');
+      return built;
+    }
+  } catch (err) {
+    _whaDbg('[DBG] AVATAR built-in converter failed: ' + (err && err.message));
+  }
+
+  // A format the built-in decoder does not read — WebP, HEIC, a progressive
+  // JPEG. ffmpeg can do the same job and is already used by the video path, so
+  // try it before giving up.
+  const viaFfmpeg = await avatarViaFfmpeg(buf, size, quality);
+  if (viaFfmpeg) return viaFfmpeg;
+
+  // Nothing that can re-encode. Strip the metadata segments at least: EXIF and
+  // the other APPn blocks are the part of an ordinary camera JPEG the server
+  // most often will not take, and removing them needs no decoder — the image
+  // data is left exactly as it was.
+  const stripped = stripJpegMetadata(buf);
+  if (stripped !== buf) {
+    _whaDbg('[DBG] AVATAR no converter — sent with metadata stripped (' +
+      buf.length + ' → ' + stripped.length + ' bytes). Install jimp or ffmpeg ' +
+      'to have the image resized properly.');
+    return stripped;
   }
 
-  _whaDbg('[DBG] AVATAR no image library — sending the file as it is. ' +
-    'WhatsApp wants a square JPEG; install jimp to have that done for you.');
+  _whaDbg('[DBG] AVATAR nothing could read this file — sending it as it is. ' +
+    'WhatsApp wants a square JPEG; JPEG, PNG, GIF and BMP are converted here ' +
+    'on their own, and ffmpeg or jimp covers the rest.');
   return buf;
 }
 
+/**
+ * Crop square and resize with ffmpeg, which needs no native npm module.
+ *
+ * Returns null when ffmpeg is not installed or cannot read the file, so the
+ * caller can carry on to the next fallback.
+ */
+async function avatarViaFfmpeg(buf, size, quality) {
+  if (!(await hasFfmpeg())) return null;
+
+  const src = tmpFile('.img');
+  const dst = tmpFile('.jpg');
+  try {
+    fs.writeFileSync(src, buf);
+    // Crop to the shorter side, scale, and write baseline JPEG. -q:v runs 2..31
+    // worst-to-best in ffmpeg, the opposite way round to a percentage quality.
+    const q = Math.max(2, Math.min(31, Math.round(31 - (quality / 100) * 29)));
+    const ok = await run('ffmpeg', [
+      '-y', '-i', src,
+      '-vf', "crop='min(iw,ih)':'min(iw,ih)',scale=" + size + ':' + size,
+      '-q:v', String(q),
+      '-f', 'mjpeg',
+      dst
+    ]);
+    if (ok === null) return null;
+    const out = fs.readFileSync(dst);
+    if (!out.length || out[0] !== 0xff || out[1] !== 0xd8) return null;
+    _whaDbg('[DBG] AVATAR re-encoded with ffmpeg (' + out.length + ' bytes)');
+    return out;
+  } catch (err) {
+    _whaDbg('[DBG] AVATAR ffmpeg failed: ' + (err && err.message));
+    return null;
+  } finally {
+    try { fs.unlinkSync(src); } catch (_) {}
+    try { fs.unlinkSync(dst); } catch (_) {}
+  }
+}
+
+/**
+ * Drop every APPn segment from a JPEG, keeping the image itself byte for byte.
+ *
+ * EXIF, ICC profiles, thumbnails and camera maker notes all live in these, and
+ * a picture that carries them is the ordinary case a phone produces. Removing
+ * them takes no decoder — it is a walk over the segment headers — so it works
+ * where nothing else is installed.
+ *
+ * Returns the input unchanged when it is not a JPEG or has nothing to drop.
+ */
+function stripJpegMetadata(buf) {
+  if (!Buffer.isBuffer(buf) || buf.length < 4) return buf;
+  if (buf[0] !== 0xff || buf[1] !== 0xd8) return buf;   // not a JPEG
+
+  const keep = [buf.slice(0, 2)];
+  let i = 2, dropped = 0;
+
+  while (i + 4 <= buf.length) {
+    if (buf[i] !== 0xff) break;                 // out of step; leave the rest be
+    const marker = buf[i + 1];
+
+    // Start of scan — everything from here is entropy-coded image data.
+    if (marker === 0xda) { keep.push(buf.slice(i)); i = buf.length; break; }
+    // Standalone markers carry no length.
+    if (marker === 0xd8 || (marker >= 0xd0 && marker <= 0xd9)) {
+      keep.push(buf.slice(i, i + 2)); i += 2; continue;
+    }
+
+    const len = buf.readUInt16BE(i + 2);
+    if (len < 2 || i + 2 + len > buf.length) break;     // malformed; stop here
+    const seg = buf.slice(i, i + 2 + len);
+
+    // APP0 is the JFIF header, which is the one to keep; APP1..APPF and the
+    // comment segment are metadata.
+    const isAppN    = marker >= 0xe1 && marker <= 0xef;
+    const isComment = marker === 0xfe;
+    if (isAppN || isComment) dropped += seg.length;
+    else keep.push(seg);
+
+    i += 2 + len;
+  }
+
+  if (!dropped) return buf;
+  if (i < buf.length) keep.push(buf.slice(i));
+  return Buffer.concat(keep);
+}
+
 // ─── ffmpeg ──────────────────────────────────────────────────────────────────
 
 function run(cmd, args) {
@@ -450,6 +593,8 @@ module.exports = {
   extractExifThumbnail,
   imageThumbnail,
   prepareProfilePicture,
+  stripJpegMetadata,
+  canDecodeImage,
   videoThumbnail,
   hasFfmpeg,
   THUMB_WIDTH,